🏓 feat: Dispatch Worker-Local Workspace Tools

packages/code/README.md

@@ -188,7 +188,7 @@ accepting another assignment. Reset or discard that session's local runner
 before restarting the worker; its workspace may contain mutations that Code
 API did not commit.
 
-## Local workspace tools (library preview)
+## Local workspace tools (bridge preview)
 
 `@librechat/code/workspace` provides the provider-neutral foundation for
 coding-agent access to repositories that already live on the worker machine.
@@ -207,9 +207,28 @@ and stops after a bounded global result count. The worker process still belongs
 inside the trusted BYOM boundary and should receive filesystem access only to
 roots the operator intentionally registers.
 
-This release exposes the library protocol only. The subsequent bridge-dispatch
-layer will route signed, deadline-bound workspace tool assignments to it; until
-that layer is configured, the CLI does not advertise or execute these tools.
+Register one repository already present on the worker machine with the
+Cursor-style worker-directory option:
+
+```bash
+librechat-code run --worker-dir /path/to/repository
+```
+
+The default public workspace ID is `primary` and the default display name is
+the directory basename. Operators can use `--workspace-id` and
+`--workspace-name`, or `LIBRECHAT_CODE_WORKER_DIR`,
+`LIBRECHAT_CODE_WORKSPACE_ID`, and `LIBRECHAT_CODE_WORKSPACE_NAME`, to set them
+explicitly. `rg` must be installed on the worker for `search_text`.
+
+The worker advertises these capabilities only when a directory is configured
+and executes matching assignments under the bridge's existing lease,
+deadline, cancellation, credential-refresh, and settlement fencing. The
+repository itself remains on the worker. As with Cursor's self-hosted agents,
+text deliberately selected by `read_file` or `search_text` crosses the outbound
+bridge so the remote agent/model can reason over it. Host paths are never part
+of that payload. The Code API workspace-tool endpoint is delivered as a
+dependent layer; deployments without it continue to use sandbox assignments
+unchanged.
 
 After discarding or resetting that session's local runner, acknowledge recovery
 with `librechat-code reset-workspace <runtime-session-id>`. The command uses the

packages/code/src/cli.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { createHash, createHmac, randomBytes } from 'node:crypto';
 import { readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { basename, resolve } from 'node:path';
 
 import { pairBridgeWorker } from './pairing.js';
 import { startFileRelay } from './relay.js';
@@ -13,7 +13,9 @@ import {
 } from './storage.js';
 import { BridgeWorker } from './worker.js';
 import { DockerRuntimeSupervisor, EndpointRuntimeSupervisor } from './runtime.js';
+import { LocalWorkspaceTools } from './workspace.js';
 import {
+  BRIDGE_WORKSPACE_NAME_MAX_LENGTH,
   isValidBridgeWorkerCapabilities,
   isValidBridgeWorkerId,
 } from './protocol.js';
@@ -65,6 +67,14 @@ function option(args: string[], name: string): string | undefined {
   return args.find((value) => value.startsWith(`${name}=`))?.slice(name.length + 1);
 }
 
+function defaultWorkspaceName(workerDirectory: string, workspaceId: string): string {
+  const directoryName = basename(resolve(workerDirectory));
+  return directoryName.trim().length > 0 &&
+    directoryName.length <= BRIDGE_WORKSPACE_NAME_MAX_LENGTH
+    ? directoryName
+    : workspaceId;
+}
+
 async function pair(args: string[]): Promise<void> {
   const codeApiUrl = required('instance URL', args[1]);
   const code = required('one-time pairing code', args[2]);
@@ -117,7 +127,7 @@ async function relay(): Promise<void> {
   await handle.close();
 }
 
-async function run(runtimeSessionId?: string): Promise<void> {
+async function run(runtimeSessionId?: string, args: string[] = []): Promise<void> {
   const configuredWorkerId = process.env.LIBRECHAT_CODE_WORKER_ID?.trim();
   const configuredIdentityPath = process.env.LIBRECHAT_CODE_IDENTITY_FILE?.trim();
   const configuredToken = process.env.LIBRECHAT_CODE_WORKER_TOKEN?.trim();
@@ -187,6 +197,29 @@ async function run(runtimeSessionId?: string): Promise<void> {
     runtimeMode === 'docker-macos-nsjail' &&
     runtimeSessionId == null &&
     (fileRelayUpstream?.length ?? 0) > 0;
+  const workerDirectory =
+    runtimeSessionId == null
+      ? option(args, '--worker-dir') ??
+        process.env.LIBRECHAT_CODE_WORKER_DIR?.trim()
+      : undefined;
+  const workspaceId =
+    option(args, '--workspace-id') ??
+    process.env.LIBRECHAT_CODE_WORKSPACE_ID?.trim() ??
+    'primary';
+  const workspaceTools = workerDirectory
+    ? await LocalWorkspaceTools.create({
+        workspaces: [
+          {
+            id: workspaceId,
+            name:
+              option(args, '--workspace-name') ??
+              process.env.LIBRECHAT_CODE_WORKSPACE_NAME?.trim() ??
+              defaultWorkspaceName(workerDirectory, workspaceId),
+            root: workerDirectory,
+          },
+        ],
+      })
+    : undefined;
   const capabilities = {
     statefulWorkspace,
     sandboxProfile:
@@ -195,6 +228,7 @@ async function run(runtimeSessionId?: string): Promise<void> {
     runtimes: list(process.env.LIBRECHAT_CODE_RUNTIMES),
     policyDigest: createHash('sha256').update(policy).digest('hex'),
     ...(fileRelayEnabled ? { requiresReadyConfirmation: true } : {}),
+    ...(workspaceTools ? { workspaceTools: workspaceTools.capabilities } : {}),
   };
   if (!isValidBridgeWorkerCapabilities(capabilities)) {
     throw new Error(
@@ -330,6 +364,7 @@ async function run(runtimeSessionId?: string): Promise<void> {
               statefulWorkspace,
             }),
       capabilities,
+      workspaceTools,
       onIdentityChange:
         pairedIdentity && identityPath
           ? async (identity) => {
@@ -401,7 +436,7 @@ async function main(): Promise<void> {
   if (args[0] && args[0] !== 'run') {
     throw new Error(`Unknown command: ${args[0]}`);
   }
-  await run();
+  await run(undefined, args.slice(1));
 }
 main().catch((error: Error) => {
   process.stderr.write(`librechat-code: ${error.message}\n`);

packages/code/src/protocol.ts

@@ -1,3 +1,5 @@
+import type { WorkspaceToolRequest } from './workspace.js';
+
 export const BRIDGE_PROTOCOL_VERSION = 1 as const;
 export const BRIDGE_WORKER_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
 export const BRIDGE_SANDBOX_PROFILE_MAX_LENGTH = 128;
@@ -77,7 +79,8 @@ export interface BridgeAssignment<TBody = object> {
   /** Server-calculated execution budget at lease time; avoids VM clock skew. */
   remainingMs?: number;
   runtimeSessionId?: string;
-  request: BridgeSandboxRequest<TBody>;
+  executionKind?: 'sandbox' | 'workspace_tool';
+  request: BridgeSandboxRequest<TBody> | WorkspaceToolRequest;
 }
 
 export interface BridgeLeaseResponse<TBody = object> {