@gapi/gcli 1.8.243 → 1.8.244

package/.agents/skills/local-ai-runners/SKILL.md

@@ -44,3 +44,12 @@ node release/index.js runner:models --show qwen3.8:27b   # keep the picker short
 Lambforge socket (acks, operation replies, pushes requests), `fakeOllama`
 plays Ollama (tags/show/streamed body, optional hold). Add a case there for
 any protocol change.
+
+## Shared with `workspace:*`
+
+The WebSocket client is `TunnelConnection` (`src/commands/runner/tunnel.ts`);
+`RunnerConnection` (Ollama) and `WorkspaceConnection` (local workspaces,
+`src/commands/workspace/`, feature `local-workspaces`) are its two
+subclasses. Protocol changes (frames, ack/ping, reconnect) go in the base
+class and must keep both test files green (`test/runner.spec.ts`,
+`test/workspace.spec.ts`).

package/AGENTS.md

@@ -34,7 +34,7 @@ fragment in every repo the change touches.
 |---|---|
 | `gcli-command` | Adding a command: registration, lazy actions, `GraphqlClienAPI`, tests, build/release, regenerating `README-CLI.md` |
 | `cluster-targeting` | Commands touching resources that can live on a private cluster (`--clusterId/--clusterName`) |
-| `local-ai-runners` | `runner:*` - the outbound WS client bridging a user's Ollama to the chat |
+| `local-ai-runners` | `runner:*` - the outbound WS client bridging a user's Ollama to the chat (its `TunnelConnection` base also serves `workspace:*`) |
 | `changelog` | Feature-keyed changelog fragments + feature docs |
 
 ## Documentation map
@@ -46,6 +46,7 @@ fragment in every repo the change touches.
 | Features (current state) | [`docs/features/README.md`](docs/features/README.md) |
 | Change history of a feature | `node scripts/changelog.mjs render --feature <slug>` |
 | Local AI runner (slice; canonical in graphql-server) | [`docs/features/local-ai-runners.md`](docs/features/local-ai-runners.md) |
+| Local workspaces - `workspace:*` (slice; canonical in graphql-server) | [`docs/features/local-workspaces.md`](docs/features/local-workspaces.md) |
 | Claude Code config in this package | [`.claude/README.md`](.claude/README.md) |
 
 ## Key patterns
@@ -102,4 +103,4 @@ to debug" live.
   gateway points every later command (and `runner:start`) at dev.
 - Jest needs the `moduleNameMapper` in `jest.config.js` for the `~/` alias -
   without it any spec importing command code fails to resolve.
-- `runner:start` needs Node >= 22 (global `WebSocket`).
+- `runner:start` and `workspace:start` need Node >= 22 (global `WebSocket`).

package/README-CLI.md

@@ -63,6 +63,9 @@ Commands:
   runner:list                                          List your local AI runners and the models they serve
   runner:models [options]                              Choose which of a runner's models appear in the chat model picker (no flags: list them)
   runner:delete [options]                              Delete a local AI runner and revoke its token
+  workspace:start [options]                            Connect the current directory to the Lambforge chat as a local workspace: the AI agents can read/edit its files and run commands here (outbound connection only - works behind NAT)
+  workspace:list [options]                             List your local workspaces (online status, directory, processes)
+  workspace:delete [options]                           Delete a local workspace and revoke its token (default: the one registered for this directory)
   help [command]                                       display help for command
 
 --- Subcommand: login ---
@@ -132,6 +135,7 @@ Options:
   --configs <configs...>                           List of kubernetes config names
   --secrets <secrets...>                           List of kubernetes secret names
   --envSecrets <envSecrets...>                     List of kubernetes secret names projected into process.env (graphql environment only)
+  --bodyLimit <bodyLimit>                          Largest request body the lambda accepts, e.g. 20mb (default 10mb, max 100mb)
   --network <network>                              Can be private or public meaning exposed to the router or just for private available can be both also --network private --network public
   --route <route>                                  Lambda route in which will be accessible
   --code <code>                                    URL or local path for single file source code
@@ -174,6 +178,7 @@ Options:
   --configs <configs...>                           List of kubernetes config names
   --secrets <secrets...>                           List of kubernetes secret names
   --envSecrets <envSecrets...>                     List of kubernetes secret names projected into process.env (graphql environment only)
+  --bodyLimit <bodyLimit>                          Largest request body the lambda accepts, e.g. 20mb (default 10mb, max 100mb)
   --network <network>                              Can be private or public meaning exposed to the router or just for private available can be both also --network private --network public
   --route <route>                                  Lambda route in which will be accessible
   --code <code>                                    URL or local path for single file source code
@@ -289,6 +294,7 @@ Options:
   --configs <configs...>                           List of kubernetes config names
   --secrets <secrets...>                           List of kubernetes secret names
   --envSecrets <envSecrets...>                     List of kubernetes secret names projected into process.env (graphql environment only)
+  --bodyLimit <bodyLimit>                          Largest request body the lambda accepts, e.g. 20mb (default 10mb, max 100mb)
   --network <network>                              Can be private or public meaning exposed to the router or just for private available can be both also --network private --network public
   --route <route>                                  Lambda route in which will be accessible
   --code <code>                                    URL or local path for single file source code
@@ -924,3 +930,52 @@ Delete a local AI runner and revoke its token
 Options:
   --id <id>   Runner id (default: the runner saved on this machine)
   -h, --help  display help for command
+
+--- Subcommand: workspace:start ---
+Usage: gcli workspace:start [options]
+
+Connect the current directory to the Lambforge chat as a local workspace: the AI agents can read/edit its files and run commands here (outbound connection only - works behind NAT)
+
+Options:
+  -n, --name <name>          Workspace name shown in the chat (default:
+                             directory name)
+  -p, --project <projectId>  Project the workspace belongs to (default: `gcli
+                             project:use`)
+  -t, --token <token>        Workspace token (instead of registering with `gcli
+                             login`)
+  --allow <commands>         Comma-separated commands that run without
+                             approval; * matches anything (e.g. "npm test,npm
+                             run *")
+  --no-default-allow         Do not pre-allow read-only commands (git
+                             status/diff/log, ls, ...)
+  --yolo                     Run EVERY command without asking (only in a
+                             sandbox / a repo you can reset)
+  --no-terminal-approval     Approve commands only in the chat, never prompt in
+                             this terminal
+  --env <names>              Comma-separated environment variables to pass to
+                             commands (default: a minimal environment)
+  --inherit-env              Pass your whole shell environment to commands
+  --allow-secrets            Let the chat read/write .env files, keys and other
+                             secrets files
+  --wsUrl <url>              Lambforge subscriptions endpoint override
+  --reset                    Forget the workspace saved for this directory and
+                             register a new one
+  -h, --help                 display help for command
+
+--- Subcommand: workspace:list ---
+Usage: gcli workspace:list [options]
+
+List your local workspaces (online status, directory, processes)
+
+Options:
+  -p, --project <projectId>  Only this project
+  -h, --help                 display help for command
+
+--- Subcommand: workspace:delete ---
+Usage: gcli workspace:delete [options]
+
+Delete a local workspace and revoke its token (default: the one registered for this directory)
+
+Options:
+  --id <id>   Workspace id (see `gcli workspace:list`)
+  -h, --help  display help for command

package/README.md

@@ -920,6 +920,56 @@ Notes:
 - Use Profile -> Local AI runners in the web app to see runners, choose
   models with checkboxes, and create tokens.
 
+## Local Workspaces (the chat works in your own project)
+
+`gcli workspace:start` connects the **current directory** to the Lambforge
+chat: the AI agents can read and edit its files, run commands (`npm install`,
+`npm test`, `git diff`, `tsc`) and keep dev servers running (`npm start`) -
+on your machine, in your real (git) project. Same **outbound** WebSocket as
+the Ollama runner: works behind NAT, opens no port. Web workspaces keep
+working as before; this is an additional, local kind.
+
+```bash
+gcli login
+gcli project:use <projectId>           # the workspace belongs to one project
+cd ~/code/my-app
+gcli workspace:start                   # --allow "npm test,npm run *" to skip approvals for those
+```
+
+Then, in a chat of that project (mode Auto): "run the tests in my local
+project and fix what fails", "start the dev server and check it boots". The
+agents only touch files under that directory.
+
+**Commands need your approval** - in this terminal (`[y]es / [a]lways for
+this session / [N]o`) or on the card in the chat; whichever you answer first
+wins. Read-only commands (`git status/diff/log/show`, `ls`, `pwd`, ...) and
+your `--allow` rules run unasked. Destructive ones (`git push`, `git reset
+--hard`, `git clean`, `git commit`, `rm -r`, `sudo`, `curl ... | sh`, ...)
+always ask. `--yolo` runs everything unasked - only for a sandbox or a repo
+you can reset. Nobody answers in 5 minutes = denied.
+
+| Command | Description |
+|---|---|
+| `gcli workspace:start` | Connect this directory. First run registers it (saved in `~/.graphql-server/workspaces.json`, per directory). Options: `--name`, `--project <id>` (default: `gcli project:use`), `--allow <list>` (comma-separated, `*` wildcard), `--no-default-allow`, `--yolo`, `--no-terminal-approval` (approve only in the chat), `--env A,B` (pass these variables to commands), `--inherit-env` (pass your whole environment), `--allow-secrets` (let the chat read `.env`/keys), `--token`, `--wsUrl`, `--reset` |
+| `gcli workspace:list` | Your local workspaces: online, project, directory, running processes (`--project`) |
+| `gcli workspace:delete` | Remove a workspace and revoke its token (`--id`, default: this directory's). Nothing on disk is deleted |
+
+What the chat can and can't do:
+
+- Files: only under the directory (symlinks resolved); `.git` is read-only;
+  `.env*`, private keys, `.npmrc`, ... are invisible unless `--allow-secrets`;
+  `node_modules` and `.gitignore`d files are not listed or searched.
+- Commands run as you, in a minimal environment (PATH, HOME, nvm/pnpm
+  dirs - none of your shell's tokens) unless `--env` / `--inherit-env`.
+- Background processes (`npm start`) live until the chat stops them or you
+  stop gcli - Ctrl+C stops every one of them.
+- Every operation is printed here (`->` read, `✎` write, `$` command,
+  `▶` process), so you can watch what the agent does.
+- Review with `git diff` and commit yourself - the agents are told not to
+  commit, push or reset.
+
+Requires Node.js >= 22.
+
 ## Build System & Local Development
 
 `gcli` includes a high-performance bundler powered by **esbuild**.

package/docs/changelog.d/2026-10-23-local-workspaces-gcli-workspace-start-list-delete-the-chat-agents-work-in-a-l.md

@@ -0,0 +1,13 @@
+## 2026-10-23 - local-workspaces: gcli workspace:start/list/delete - the chat agents work in a local directory
+
+**Feature:** local-workspaces · **Type:** feat
+
+- New `workspace:start` (connect the current directory; registers it with the `gcli login` account in the `--project` / `project:use` project, token saved per directory in `~/.graphql-server/workspaces.json`), `workspace:list`, `workspace:delete`. Options: `--allow`, `--no-default-allow`, `--yolo`, `--no-terminal-approval`, `--env`, `--inherit-env`, `--allow-secrets`, `--token`, `--wsUrl`, `--reset`.
+- The runner's WebSocket client is now a shared base class `TunnelConnection` (`src/commands/runner/tunnel.ts`); `RunnerConnection` keeps its behaviour (same tests) and `WorkspaceConnection` (`src/commands/workspace/connection.ts`) serves `POST /workspace/<op>`.
+- `WorkspaceFiles`: everything confined to the root (symlinks resolved), `.git` read-only, secrets files hidden unless `--allow-secrets`, git-aware listing/search (`.gitignore` respected, `node_modules` skipped), edits by exact unique match with content-hash conflict checks.
+- `CommandPolicy` + `ApprovalGate`: read-only defaults and `--allow` rules run unasked; everything else asks in the terminal AND on the chat card (first answer wins, 5-min expiry); destructive commands always ask unless `--yolo`; "always" remembers program + verb for the session.
+- `runCommand` / `ProcessManager`: process groups (children die too), timeouts, output tails, background processes with a ring buffer and `waitFor`; all stopped when gcli exits. Commands get a minimal environment unless `--env` / `--inherit-env`.
+- Backend half in graphql-server (registry, tunnel, agent tools, LOCAL worker), UI in gql-fission. Canonical doc: `graphql-server/docs/features/local-workspaces.md`.
+- **Test:** `npx jest --coverage=false test/workspace test/runner` - files (escape, symlink, secrets, .gitignore, edit/hash), policy, approvals (web wins, early web answer, terminal deny, expiry), commands/processes (exit codes, timeout kill, waitFor/logs/stop), the connection end to end against a fake server.
+- **Debug:** gcli's own log (`->`, `✎`, `$`, `▶`, `?`, `x`); "refused this workspace" = deleted -> `--reset`; wrong environment -> `~/.graphql-server/url`.
+- **Verification:** full gcli suite 99/99 passing, `npx tsc --noEmit -p .` clean, `npx eslint src test` clean. Not yet run against a live backend.

package/docs/features/README.md

@@ -31,6 +31,7 @@ Outline (drop sections that don't apply):
 | Feature | Doc | Notes |
 |---|---|---|
 | `local-ai-runners` | [local-ai-runners.md](local-ai-runners.md) | `runner:*` commands; canonical doc in graphql-server |
+| `local-workspaces` | [local-workspaces.md](local-workspaces.md) | `workspace:*` commands - the chat agents edit files and run commands in a local directory; canonical doc in graphql-server |
 | `lambforge-agent-skill` | [lambforge-agent-skill.md](lambforge-agent-skill.md) | The agent skill that teaches gcli + `mcp:start`; canonical doc in gql-fission |
 | `dedicated-platform-cluster` | [dedicated-platform-cluster.md](dedicated-platform-cluster.md) | `cluster:status/health/scale/autoscale/...` commands; canonical doc in lambforge-agent |
 | `ci-token-scopes` | [ci-token-scopes.md](ci-token-scopes.md) | Which permission each command needs; `mq-trigger:*` commands; canonical doc in graphql-server |

package/docs/features/local-workspaces.md

@@ -0,0 +1,42 @@
+# Local workspaces (gcli slice)
+
+**Status:** built 2026-10-23. **Feature slug:** `local-workspaces`.
+Canonical doc (flow, backend, security model, debugging):
+`graphql-server/docs/features/local-workspaces.md`.
+
+`gcli workspace:start` serves the current directory to the chat agents over
+the outbound WebSocket tunnel local AI runners use.
+
+## Files
+
+| Path | Responsibility |
+|---|---|
+| `src/commands/runner/tunnel.ts` | `TunnelConnection` - the shared subscriptions-transport-ws client (connect/reconnect, heartbeat timer, request dispatch, ack/ping, `FrameSender`); `RunnerConnection` and `WorkspaceConnection` extend it |
+| `src/commands/workspace/connection.ts` | `WorkspaceConnection`: `workspaceToken`, `localWorkspaceHeartbeat`, the ops allow-list (`WORKSPACE_OPS`, mirrors the backend), `dispatch(op)`, approval frames |
+| `src/commands/workspace/files.ts` | `WorkspaceFiles`: root confinement (incl. symlinks), `.git` read-only, secrets files, git-aware list/search, read/write/edit with content hashes |
+| `src/commands/workspace/policy.ts` | `CommandPolicy`: default allow rules, `--allow`, always-ask patterns, segment matching, "always" rules |
+| `src/commands/workspace/approvals.ts` | `ApprovalGate` (policy -> web card + terminal prompt race, timeout, settle), `TerminalPrompt` |
+| `src/commands/workspace/processes.ts` | `runCommand` (timeout, process-group kill, output tails), `ProcessManager` (background processes, ring buffer, waitFor), `buildEnv` |
+| `src/commands/workspace/{start,list,delete,config,index}.ts` | the commands; `~/.graphql-server/workspaces.json` (0600, keyed by directory) |
+
+## Protocol (what the backend sends)
+
+`POST /workspace/<op>` with a JSON body, answered `head(status) + chunks + end`
+with a JSON body; errors are `{ error }` with 400/403/404/409/500. Ops:
+`info list read write edit delete search exec process/start process/list
+process/logs process/stop`. Anything else is refused before the ack.
+`type: 'approval'` frames carry `{ decision: allow|always|deny }` for an
+approval id this client created with `requestLocalWorkspaceApproval`.
+
+## How to test
+
+`npx jest --coverage=false test/workspace` - real files and processes in a
+temp dir; the connection runs against a fake subscriptions server
+(edit over the tunnel, refused paths, web approval -> command runs, denial).
+
+## How to debug
+
+gcli prints every op: `->` read/list/search, `✎` write/edit/delete, `$`
+command (+ exit code and duration), `▶` / `■` processes, `?` approval
+needed, `x` failed/cancelled. "refused this workspace" = deleted on the web
+(`--reset`). Pointing at the wrong environment: `~/.graphql-server/url`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gapi/gcli",
-  "version": "1.8.243",
+  "version": "1.8.244",
   "repository": {
     "type": "git",
     "url": "https://github.com/Stradivario/gapi.git"