🎖️ feat: Expose Authenticated Workspace Tool API

docs/remote-bridge/README.md

@@ -86,6 +86,52 @@ locally, proves possession on every request, and rotates its short-lived
 credential before expiry. `CODEAPI_BRIDGE_AUTH_MODE=static` remains available
 for non-hardened development compatibility only.
 
+To expose an existing checkout as a worker-local workspace, start the CLI with
+an explicit directory and logical ID:
+
+```bash
+librechat-code run \
+  --worker-dir /srv/checkouts/librechat \
+  --workspace-id primary \
+  --workspace-name LibreChat
+```
+
+The worker advertises only the workspace ID, optional display name, and
+supported operations. Its host path is never registered with Code API. An
+authenticated caller can execute the initial read-only operations through:
+
+```bash
+curl -fsS https://code.example.com/v1/workspace-tools/execute \
+  -H "Authorization: Bearer $LIBRECHAT_JWT" \
+  -H 'Content-Type: application/json' \
+  --data '{
+    "protocolVersion":1,
+    "operation":"read_file",
+    "workspaceId":"primary",
+    "path":"README.md",
+    "startLine":1,
+    "maxLines":200
+  }'
+```
+
+The endpoint uses the same authenticated principal-bound worker selection,
+tenant fence, lease deadline, cancellation, and settlement lifecycle as remote
+sandbox execution. Requests must name a workspace and operation advertised by
+that worker. Results are validated against the originating request before they
+leave Code API, and are bounded to 1 MiB/500 lines for reads or 200 matches for
+searches. Absolute paths, traversal, backslashes, symlink escapes, unexpected
+fields, and host roots are rejected.
+
+The workspace root can be an existing project, a Git repository, or an empty
+directory; Git is not required. This boundary keeps that directory local to the
+operator's machine, but the selected file contents, search matches, and later
+tool results necessarily cross the outbound bridge to Code API and the model.
+Treat them as explicit tool outputs, apply the same retention and audit policy
+as chat content, and do not register a directory containing secrets. The
+default operations are read-only; future mutation and shell operations must be
+gated by LibreChat's tool-approval hooks in addition to worker capability
+checks.
+
 Stateful deployments must also set `LIBRECHAT_CODE_STATEFUL_WORKSPACE=true`
 and route the CLI's `{runtimeSessionId}` endpoint template to an isolated,
 persistent local runner per session. A single sandbox endpoint is stateless and

packages/code/README.md

@@ -191,7 +191,9 @@ API did not commit.
 ## 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.
+coding-agent access to workspace directories on the worker machine. A workspace
+may be an existing project, a Git repository, or a newly created empty
+directory; Git is optional.
 `LocalWorkspaceTools` registers opaque workspace IDs with optional display
 names and exposes bounded `read_file` and literal `search_text` operations.
 Only IDs, names, protocol version, and supported operations appear in worker
@@ -207,11 +209,11 @@ 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.
 
-Register one repository already present on the worker machine with the
-Cursor-style worker-directory option:
+Register one directory already present on the worker machine with the
+worker-directory option:
 
 ```bash
-librechat-code run --worker-dir /path/to/repository
+librechat-code run --worker-dir /path/to/workspace
 ```
 
 The default public workspace ID is `primary` and the default display name is
@@ -223,7 +225,7 @@ 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,
+workspace 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