ysagc-agent 0.8.5 → 0.9.1

package/README.md

@@ -1,266 +1,266 @@
-# ysagc-agent
-
-The **local execution agent** for ysagc. It runs on a user's own computer, opens a
-WebSocket to the platform backend, receives tool instructions, executes them
-**safely inside an authorization root**, and reports results back.
-
-`ysagc-agent` is deliberately **state-agnostic**: it never stores balances, never
-makes billing decisions, and never holds platform secrets. It is a dumb, safe,
-well-scoped executor — all policy lives on the platform.
-
-## Highlights
-
-- **Zero-config startup** — a bare `ysagc-agent` (or `npx ysagc-agent`) starts
-  immediately with the default platform, a generated local device identity, `cwd`
-  as the authorization root, and connects — **no prompts, no wizard**.
-- **Auto-reconnect until connected** — if the first connection can't be
-  established it prints a single notice and then **retries every `--retry-interval`
-  (default 1000ms)** until it reaches the platform; it never exits and never
-  cascades into a prompt.
-- **Opt-in `--configure` wizard** — run `ysagc-agent --configure` to
-  interactively set the address / token / root.
-- **No baked-in secrets** — the default server is the customer platform; the
-  device token is self-generated on a zero-config run, never logged, never
-  committed anywhere, and never a real platform secret.
-- **Authorization root** — every file operation is forced inside one directory tree.
-- **Danger-command guard** — destructive shell commands are detected and blocked.
-- **Sensitive-path guard** — credential/system paths are blocked regardless of mode.
-- **Secret masking** — secrets are redacted from logs and tool results.
-- **Idempotency** — repeated `tool_call`s with the same key return the cached result
-  and never double-execute or double-write. `needsApproval` results are **not**
-  cached, so an approved re-send re-runs the job.
-- **Rich tool set** — `search` (grep), `glob`, `tree`, `str_replace_editor`,
-  `mv`/`cp`, `delete_file`, `json` pretty-print, and segmented `read_file`
-  (`offset`/`length`) alongside the core file + shell tools.
-- **Heartbeat & auto-reconnect** — exponential backoff with a cap.
-- **Cancel support** — in-flight commands can be aborted by the platform.
-- **Strict TypeScript** — compiled with `tsc` to CommonJS, zero `any` leaks.
-- **Cross-platform** — bash, PowerShell and cmd command detection.
-
-## Requirements
-
-- Node.js **>= 18**
-
-## Quick start
-
-### One-command startup (zero config)
-
-```bash
-npm install -g ysagc-agent
-ysagc-agent
-```
-
-That's it. With no saved config the agent **silently builds defaults and
-connects immediately** — no wizard, no prompts:
-
-- **server** — defaults to `ws://interface.ysagi.cn/api/workbench/agent`, **but with
-  local/online auto-detection**: when the default platform URL is in use, the agent
-  first tries the **local dev backend** `ws://localhost:5000/api/workbench/agent`,
-  and falls through to the default if it's unreachable. So a bare `ysagc-agent`
-  works whether you're testing locally or connecting to the platform. If you pass an
-  explicit `--server`/`WS_URL`, that one is used exclusively.
-- **deviceId** — generated as `agent-<random>-<n>`
-- **token** — a self-generated local identity (never a real platform secret)
-- **root** — the current working directory (`process.cwd()`)
-
-The resolved defaults are saved to `~/.ysagc-agent/config.json` (mode `0600`,
-directory created if missing) so every later run connects the same way. A bare run
-logs its config **without the token** (`describeConfig` omits it).
-
-Referenced by `WS_URL`, `YSAGC_TOKEN`, `DEVICE_ID`/`WORKSPACE_ROOT` environment
-variables and the `--server/--token/--device-id/--root` flags still win over the
-defaults, and a silent-save never overrides them.
-
-### Configure the address / token / root (opt-in)
-
-The interactive wizard is **off by default**. Run it explicitly once to set the
-platform address, device token and workspace root, which are then persisted and
-used on every later run:
-
-```bash
-ysagc-agent --configure
-```
-
-It asks, in order:
-
-1. **平台地址 / server URL** — the default is `ws://interface.ysagi.cn/api/workbench/agent`; press **Enter** to accept, or type another (`http`/`https` are accepted and converted to `ws`/`wss`).
-2. **设备 Token** — paste the device token copied from the workbench's「如何连接」. Input is **masked** (not echoed). Leave it empty to generate a local device id and a short pairing hint instead.
-3. **工作区目录 / workspace root** — defaults to the current directory; press **Enter** to accept or type an absolute path.
-
-Any value already supplied by flags/env is used as-is and its prompt is skipped.
-
-> **Non-interactive `--configure`:** `--configure` requires a real terminal. In a
-> piped/non-TTY run it prints `--configure 需要一个交互式终端来运行。` and exits `1`
-> instead of hanging.
-
-`npx ysagc-agent` is the same entry and needs no flags either.
-
-> **First-run connection failure:** if a zero-config run cannot connect or is
-> rejected, it prints one clear line —
-> `暂未连接平台(<err>)，正在每 1s 自动重试，直到连上为止…（Ctrl+C 退出）`
-> — then **retries every `--retry-interval` (default 1000ms) until it connects**.
-> It does **not** prompt and does **not** exit.
-
-Once connected the agent sends a `hello` frame, waits for `welcome`, then answers
-`ping`/`tool_call`/`cancel` frames.
-
-### Or run it from this checkout
-
-```bash
-npm install
-npm run build               # tsc -> dist/
-node dist/cli.js --selftest # run the smoke test
-node dist/cli.js            # same zero-config auto-connect
-```
-
-## Configuration
-
-Settings are resolved in this precedence order:
-
-**CLI flags > environment variables > saved config (`~/.ysagc-agent/config.json`) > defaults.**
-
-The device token is **never logged** — `describeConfig` omits it and the logger
-masks secret-looking values before they reach stdout/stderr.
-
-| CLI flag              | Environment        | Default           | Description                                          |
-| --------------------- | ------------------ | ----------------- | ---------------------------------------------------- |
-| `--server <url>`      | `WS_URL`           | `ws://interface.ysagi.cn/api/workbench/agent` | Platform WebSocket URL (http/https auto-converted to ws/wss) |
-| `--token <token>`     | `YSAGC_TOKEN`      | _(saved config)_  | Device/agent auth token; **never** defaulted/baked-in |
-| `--device-id <id>`    | `DEVICE_ID`        | host+pid / generated | Stable device identifier                          |
-| `--root <dir>`        | `WORKSPACE_ROOT`   | cwd               | Authorization root (all file ops stay inside it)     |
-| `--mode <mode>`       | `PERMISSION_MODE`  | `smart`           | Permission mode (see below)                          |
-| `--web`               | `YSAGC_WEB`        | off               | Enable the local web_search (stub) tool              |
-| `--timeout <ms>`      | `YSAGC_TIMEOUT`    | `120000`          | Command timeout in milliseconds                      |
-| `--max-bytes <n>`     | `YSAGC_MAX_BYTES`  | `64000`           | Per-stream output cap before truncation              |
-| `--log-level <level>` | `YSAGC_LOG_LEVEL`  | `info`            | `silent\|error\|warn\|info\|debug`                      |
-| `--retry-interval <ms>` | `YSAGC_RETRY_MS` | `1000`           | Connection retry interval (retries until connected)  |
-| `--configure`         | —                  | —                 | Run the interactive setup wizard and save the config (opt-in) |
-| `--selftest`          | —                  | —                 | Run the local smoke test and exit                    |
-| `-V, --version`       | —                  | —                 | Print version                                        |
-| `-h, --help`          | —                  | —                 | Print usage                                          |
-
-### Saved config file
-
-A zero-config run — or an explicit `ysagc-agent --configure` — persists the
-resolved settings to `~/.ysagc-agent/config.json` (mode `0600`, directory created
-if missing). Override the path with the `YSAGC_CONFIG` environment variable. A
-missing or corrupt file is treated as a first run: the agent silently starts with
-defaults again (it never prompts unless `--configure` is passed).
-
-### Permission modes
-
-| Mode       | Shell behaviour                                                           |
-| ---------- | ------------------------------------------------------------------------- |
-| `supervise`| Every `run_command`/`git` is **denied** (requires human approval)         |
-| `smart`    | Safe commands are allowed; dangerous ones are blocked (default)           |
-| `auto`     | All non-dangerous commands are allowed                                    |
-
-Dangerous commands and sensitive paths are blocked **in every mode**.
-
-## Tools
-
-| Tool                  | Args                                 | Returns                                 |
-| --------------------- | ------------------------------------ | --------------------------------------- |
-| `list_dir`            | `path`, `depth`                      | entries (`name`, `type`, `size`, `mtime`) |
-| `fs_drives`           | —                                    | machine drive roots (Windows letters / `/`) |
-| `fs_browse`           | `path`                               | **whole-machine read-only** directory browse (any dir, sensitive paths blocked) — used for choosing a workspace |
-| `fs_pick_folder`      | —                                    | opens the **OS-native "select folder" dialog** and returns the chosen absolute path |
-| `read_file`           | `path`, `offset?`, `length?`/`maxBytes?` | text or hex, truncated, size/offset info |
-| `write_file`          | `path`, `content`, `mode?`           | `path`, `bytesWritten`                  |
-| `edit_file`           | `path`, `oldText`, `newText`         | `path`, `replacements`                  |
-| `str_replace_editor`  | `command`, `path`, `…`               | editor ops: `create`, `view`, `str_replace`, `insert`, `delete` |
-| `search`              | `pattern`, `path?`, `recursive?`, `caseSensitive?`, `maxResults?` | file/line matches (bounded) |
-| `glob`                | `pattern`, `path?`, `maxResults?`    | matching paths (bounded)                |
-| `tree`                | `path?`, `depth?`, `maxEntries?`     | nested + rendered tree (bounded)        |
-| `run_command`         | `cmd`, `timeout?`, `cwd?`            | `exitCode`, `stdout`, `stderr`, flags   |
-| `web_search`          | `query`                              | labelled **stub** result (real search is platform-side) |
-| `git`                 | `args` (array) or `command` (string) | git output, `exitCode`, flags           |
-| `generate`            | `template`, `name`                   | file list it created                    |
-| `mv`                  | `source`, `destination`, `overwrite?` | moved path pair (rename if same dir)   |
-| `cp`                  | `source`, `destination`, `overwrite?` | copied path pair                        |
-| `delete_file`         | `path`, `recursive?`                 | deleted path (requires approval)        |
-| `json`                | `value` or `path`, `indent?`, `sortKeys?` | pretty-printed JSON                |
-| `skill`               | `name?`                              | loaded skill / available list           |
-
-Every tool canonicalizes its path, asserts it is inside the authorization root,
-rejects outside/sensitive paths, and never leaks platform internals or keys.
-`mv`/`cp`/`delete_file` and `str_replace_editor` is a single operator;
-`mv` with no `overwrite` refuses to clobber an existing destination (and asks
-for approval when overwriting), and `delete_file` always requires approval in
-`workspace-write` mode.
-
-## Security model
-
-1. **Authorization root** — `canonicalize()` resolves `..`, symlinks, the
-   `\\?\` prefix, trailing dots/spaces and Windows reserved names, then
-   `isWithinRoot()` strictly checks the result is under the root. Writes equal
-   to the root are rejected; `..` and symlink escapes are rejected too.
-2. **Danger-command detection** — `isDangerCommand()` flags `rm -rf`, `sudo`,
-   `format <drive>`, `del /f`, `rd /s /q`, `shutdown`, `reboot`,
-   `git reset --hard`, `git clean -fdx`, `find ... -delete`,
-   `Remove-Item -Recurse -Force`, `diskpart`, `reg delete`/`reg add`,
-   `powershell -enc`, `iex`/`Invoke-Expression`, `certutil -decode`,
-   `regsvr32`/`rundll32`/`mshta`/`wmic`/`bitsadmin`, `curl|wget -> sh`,
-   `sh/bash -c`, `sc create`, `net user`, `schtasks /create`,
-   `icacls`/`cacls`, `takeown`, `vssadmin`, `bcdedit`, `cipher /w`,
-   `taskkill /f`, `chmod -R 777 /`, `mkfs`, `dd of=/dev/...`,
-   redirects to block devices, fork bombs and more. Cross-platform
-   (bash / PowerShell / cmd).
-3. **Sensitive-path detection** — `isSensitivePath()` blocks system and
-   credential paths (`/etc/passwd`, `C:\Windows\System32`, `~/.ssh`, `.env`
-   with keys, `id_rsa`, `.npmrc` with `_authToken`, and so on) regardless of mode.
-4. **Secret masking** — `maskSecrets()` redacts provider keys, bearer tokens,
-   JWTs, private keys and `key=value` secrets from logs and tool output.
-5. **Idempotency** — results are cached by a hash of `(tool, args, idempotencyKey)`;
-   replayed jobs return the cached result without re-executing. Request-for-approval
-   (`needsApproval`) results are deliberately **not** cached so the platform can
-   prompt a human and then re-send the same key to actually run it.
-6. **Environment sanitization** — child processes never inherit the agent's own
-   token or credential variables.
-
-## Self-test
-
-```bash
-node dist/cli.js --selftest
-```
-
-Runs 53 checks over path safety, danger-command detection, sensitive-path
-detection, secret masking, the tool registry, command timeout/process-tree kill,
-environment sanitization, config resolution + save/load (never logging the token),
-and idempotency over a real WebSocket connection. It prints `PASS`/`FAIL` lines
-and exits `0`/`1`.
-
-## Protocol
-
-JSON text frames over a WebSocket.
-
-**Client → server**
-
-```jsonc
-{ "type": "hello", "token": "...", "deviceId": "...", "version": "0.7.1", "platform": "node" }
-{ "type": "pong", "t": 42 }                       // reply to a server ping
-{ "type": "tool_result", "jobId": "j1", "ok": true, "result": { }, "durationMs": 12 }
-{ "type": "status", "state": "online" | "busy" | "error", "sessionId": "..." }
-```
-
-**Server → client**
-
-```jsonc
-{ "type": "welcome", "sessionId": "..." }
-{ "type": "ping", "t": 42 }
-{ "type": "tool_call", "jobId": "j1", "idempotencyKey": "k1", "tool": "write_file", "args": { } }
-{ "type": "cancel", "jobId": "j1" }
-```
-
-## Development
-
-```bash
-npm install
-npm run build          # tsc -> dist/
-npm run test           # node dist/cli.js --selftest
-npm start              # node dist/cli.js
-```
-
-## License
-
-MIT
+# ysagc-agent
+
+The **local execution agent** for ysagc. It runs on a user's own computer, opens a
+WebSocket to the platform backend, receives tool instructions, executes them
+**safely inside an authorization root**, and reports results back.
+
+`ysagc-agent` is deliberately **state-agnostic**: it never stores balances, never
+makes billing decisions, and never holds platform secrets. It is a dumb, safe,
+well-scoped executor — all policy lives on the platform.
+
+## Highlights
+
+- **Zero-config startup** — a bare `ysagc-agent` (or `npx ysagc-agent`) starts
+  immediately with the default platform, a generated local device identity, `cwd`
+  as the authorization root, and connects — **no prompts, no wizard**.
+- **Auto-reconnect until connected** — if the first connection can't be
+  established it prints a single notice and then **retries every `--retry-interval`
+  (default 1000ms)** until it reaches the platform; it never exits and never
+  cascades into a prompt.
+- **Opt-in `--configure` wizard** — run `ysagc-agent --configure` to
+  interactively set the address / token / root.
+- **No baked-in secrets** — the default server is the customer platform; the
+  device token is self-generated on a zero-config run, never logged, never
+  committed anywhere, and never a real platform secret.
+- **Authorization root** — every file operation is forced inside one directory tree.
+- **Danger-command guard** — destructive shell commands are detected and blocked.
+- **Sensitive-path guard** — credential/system paths are blocked regardless of mode.
+- **Secret masking** — secrets are redacted from logs and tool results.
+- **Idempotency** — repeated `tool_call`s with the same key return the cached result
+  and never double-execute or double-write. `needsApproval` results are **not**
+  cached, so an approved re-send re-runs the job.
+- **Rich tool set** — `search` (grep), `glob`, `tree`, `str_replace_editor`,
+  `mv`/`cp`, `delete_file`, `json` pretty-print, and segmented `read_file`
+  (`offset`/`length`) alongside the core file + shell tools.
+- **Heartbeat & auto-reconnect** — fixed-interval reconnect until connected.
+- **Cancel support** — in-flight commands can be aborted by the platform.
+- **Strict TypeScript** — compiled with `tsc` to CommonJS, zero `any` leaks.
+- **Cross-platform** — bash, PowerShell and cmd command detection.
+
+## Requirements
+
+- Node.js **>= 18**
+
+## Quick start
+
+### One-command startup (zero config)
+
+```bash
+npm install -g ysagc-agent
+ysagc-agent
+```
+
+That's it. With no saved config the agent **silently builds defaults and
+connects immediately** — no wizard, no prompts:
+
+- **server** — defaults to `ws://interface.ysagi.cn/api/workbench/agent`, **but with
+  local/online auto-detection**: when the default platform URL is in use, the agent
+  first tries the **local dev backend** `ws://localhost:5000/api/workbench/agent`,
+  and falls through to the default if it's unreachable. So a bare `ysagc-agent`
+  works whether you're testing locally or connecting to the platform. If you pass an
+  explicit `--server`/`WS_URL`, that one is used exclusively.
+- **deviceId** — generated as `agent-<random>-<n>`
+- **token** — a self-generated local identity (never a real platform secret)
+- **root** — the current working directory (`process.cwd()`)
+
+The resolved defaults are saved to `~/.ysagc-agent/config.json` (mode `0600`,
+directory created if missing) so every later run connects the same way. A bare run
+logs its config **without the token** (`describeConfig` omits it).
+
+Referenced by `WS_URL`, `YSAGC_TOKEN`, `DEVICE_ID`/`WORKSPACE_ROOT` environment
+variables and the `--server/--token/--device-id/--root` flags still win over the
+defaults, and a silent-save never overrides them.
+
+### Configure the address / token / root (opt-in)
+
+The interactive wizard is **off by default**. Run it explicitly once to set the
+platform address, device token and workspace root, which are then persisted and
+used on every later run:
+
+```bash
+ysagc-agent --configure
+```
+
+It asks, in order:
+
+1. **平台地址 / server URL** — the default is `ws://interface.ysagi.cn/api/workbench/agent`; press **Enter** to accept, or type another (`http`/`https` are accepted and converted to `ws`/`wss`).
+2. **设备 Token** — paste the device token copied from the workbench's「如何连接」. Input is **masked** (not echoed). Leave it empty to generate a local device id and a short pairing hint instead.
+3. **工作区目录 / workspace root** — defaults to the current directory; press **Enter** to accept or type an absolute path.
+
+Any value already supplied by flags/env is used as-is and its prompt is skipped.
+
+> **Non-interactive `--configure`:** `--configure` requires a real terminal. In a
+> piped/non-TTY run it prints `--configure 需要一个交互式终端来运行。` and exits `1`
+> instead of hanging.
+
+`npx ysagc-agent` is the same entry and needs no flags either.
+
+> **First-run connection failure:** if a zero-config run cannot connect or is
+> rejected, it prints one clear line —
+> `暂未连接平台(<err>)，正在每 1s 自动重试，直到连上为止…（Ctrl+C 退出）`
+> — then **retries every `--retry-interval` (default 1000ms) until it connects**.
+> It does **not** prompt and does **not** exit.
+
+Once connected the agent sends a `hello` frame, waits for `welcome`, then answers
+`ping`/`tool_call`/`cancel` frames.
+
+### Or run it from this checkout
+
+```bash
+npm install
+npm run build               # tsc -> dist/
+node dist/cli.js --selftest # run the smoke test
+node dist/cli.js            # same zero-config auto-connect
+```
+
+## Configuration
+
+Settings are resolved in this precedence order:
+
+**CLI flags > environment variables > saved config (`~/.ysagc-agent/config.json`) > defaults.**
+
+The device token is **never logged** — `describeConfig` omits it and the logger
+masks secret-looking values before they reach stdout/stderr.
+
+| CLI flag              | Environment        | Default           | Description                                          |
+| --------------------- | ------------------ | ----------------- | ---------------------------------------------------- |
+| `--server <url>`      | `WS_URL`           | `ws://interface.ysagi.cn/api/workbench/agent` | Platform WebSocket URL (http/https auto-converted to ws/wss) |
+| `--token <token>`     | `YSAGC_TOKEN`      | _(saved config)_  | Device/agent auth token; **never** defaulted/baked-in |
+| `--device-id <id>`    | `DEVICE_ID`        | host+pid / generated | Stable device identifier                          |
+| `--root <dir>`        | `WORKSPACE_ROOT`   | cwd               | Authorization root (all file ops stay inside it)     |
+| `--mode <mode>`       | `PERMISSION_MODE`  | `smart`           | Permission mode (see below)                          |
+| `--web`               | `YSAGC_WEB`        | off               | Enable the local web_search (stub) tool              |
+| `--timeout <ms>`      | `YSAGC_TIMEOUT`    | `120000`          | Command timeout in milliseconds                      |
+| `--max-bytes <n>`     | `YSAGC_MAX_BYTES`  | `64000`           | Per-stream output cap before truncation              |
+| `--log-level <level>` | `YSAGC_LOG_LEVEL`  | `info`            | `silent\|error\|warn\|info\|debug`                      |
+| `--retry-interval <ms>` | `YSAGC_RETRY_MS` | `1000`           | Connection retry interval (retries until connected)  |
+| `--configure`         | —                  | —                 | Run the interactive setup wizard and save the config (opt-in) |
+| `--selftest`          | —                  | —                 | Run the local smoke test and exit                    |
+| `-V, --version`       | —                  | —                 | Print version                                        |
+| `-h, --help`          | —                  | —                 | Print usage                                          |
+
+### Saved config file
+
+A zero-config run — or an explicit `ysagc-agent --configure` — persists the
+resolved settings to `~/.ysagc-agent/config.json` (mode `0600`, directory created
+if missing). Override the path with the `YSAGC_CONFIG` environment variable. A
+missing or corrupt file is treated as a first run: the agent silently starts with
+defaults again (it never prompts unless `--configure` is passed).
+
+### Permission modes
+
+| Mode       | Shell behaviour                                                           |
+| ---------- | ------------------------------------------------------------------------- |
+| `supervise`| Every `run_command`/`git` is **denied** (requires human approval)         |
+| `smart`    | Safe commands are allowed; dangerous ones are blocked (default)           |
+| `auto`     | All non-dangerous commands are allowed                                    |
+
+Dangerous commands and sensitive paths are blocked **in every mode**.
+
+## Tools
+
+| Tool                  | Args                                 | Returns                                 |
+| --------------------- | ------------------------------------ | --------------------------------------- |
+| `list_dir`            | `path`, `depth`                      | entries (`name`, `type`, `size`, `mtime`) |
+| `fs_drives`           | —                                    | machine drive roots (Windows letters / `/`) |
+| `fs_browse`           | `path`                               | **whole-machine read-only** directory browse (any dir, sensitive paths blocked) — used for choosing a workspace |
+| `fs_pick_folder`      | —                                    | opens the **OS-native "select folder" dialog** and returns the chosen absolute path |
+| `read_file`           | `path`, `offset?`, `length?`/`maxBytes?` | text or hex, truncated, size/offset info |
+| `write_file`          | `path`, `content`, `mode?`           | `path`, `bytesWritten`                  |
+| `edit_file`           | `path`, `oldText`, `newText`         | `path`, `replacements`                  |
+| `str_replace_editor`  | `command`, `path`, `…`               | editor ops: `create`, `view`, `str_replace`, `insert`, `delete` |
+| `search`              | `pattern`, `path?`, `recursive?`, `caseSensitive?`, `maxResults?` | file/line matches (bounded) |
+| `glob`                | `pattern`, `path?`, `maxResults?`    | matching paths (bounded)                |
+| `tree`                | `path?`, `depth?`, `maxEntries?`     | nested + rendered tree (bounded)        |
+| `run_command`         | `cmd`, `timeout?`, `cwd?`            | `exitCode`, `stdout`, `stderr`, flags   |
+| `web_search`          | `query`                              | labelled **stub** result (real search is platform-side) |
+| `git`                 | `args` (array) or `command` (string) | git output, `exitCode`, flags           |
+| `generate`            | `template`, `name`                   | file list it created                    |
+| `mv`                  | `source`, `destination`, `overwrite?` | moved path pair (rename if same dir)   |
+| `cp`                  | `source`, `destination`, `overwrite?` | copied path pair                        |
+| `delete_file`         | `path`, `recursive?`                 | deleted path (requires approval)        |
+| `json`                | `value` or `path`, `indent?`, `sortKeys?` | pretty-printed JSON                |
+| `skill`               | `name?`                              | loaded skill / available list           |
+
+Every tool canonicalizes its path, asserts it is inside the authorization root,
+rejects outside/sensitive paths, and never leaks platform internals or keys.
+`mv`/`cp`/`delete_file` and `str_replace_editor` is a single operator;
+`mv` with no `overwrite` refuses to clobber an existing destination (and asks
+for approval when overwriting), and `delete_file` always requires approval in
+`workspace-write` mode.
+
+## Security model
+
+1. **Authorization root** — `canonicalize()` resolves `..`, symlinks, the
+   `\\?\` prefix, trailing dots/spaces and Windows reserved names, then
+   `isWithinRoot()` strictly checks the result is under the root. Writes equal
+   to the root are rejected; `..` and symlink escapes are rejected too.
+2. **Danger-command detection** — `isDangerCommand()` flags `rm -rf`, `sudo`,
+   `format <drive>`, `del /f`, `rd /s /q`, `shutdown`, `reboot`,
+   `git reset --hard`, `git clean -fdx`, `find ... -delete`,
+   `Remove-Item -Recurse -Force`, `diskpart`, `reg delete`/`reg add`,
+   `powershell -enc`, `iex`/`Invoke-Expression`, `certutil -decode`,
+   `regsvr32`/`rundll32`/`mshta`/`wmic`/`bitsadmin`, `curl|wget -> sh`,
+   `sh/bash -c`, `sc create`, `net user`, `schtasks /create`,
+   `icacls`/`cacls`, `takeown`, `vssadmin`, `bcdedit`, `cipher /w`,
+   `taskkill /f`, `chmod -R 777 /`, `mkfs`, `dd of=/dev/...`,
+   redirects to block devices, fork bombs and more. Cross-platform
+   (bash / PowerShell / cmd).
+3. **Sensitive-path detection** — `isSensitivePath()` blocks system and
+   credential paths (`/etc/passwd`, `C:\Windows\System32`, `~/.ssh`, `.env`
+   with keys, `id_rsa`, `.npmrc` with `_authToken`, and so on) regardless of mode.
+4. **Secret masking** — `maskSecrets()` redacts provider keys, bearer tokens,
+   JWTs, private keys and `key=value` secrets from logs and tool output.
+5. **Idempotency** — results are cached by a hash of `(tool, args, idempotencyKey)`;
+   replayed jobs return the cached result without re-executing. Request-for-approval
+   (`needsApproval`) results are deliberately **not** cached so the platform can
+   prompt a human and then re-send the same key to actually run it.
+6. **Environment sanitization** — child processes never inherit the agent's own
+   token or credential variables.
+
+## Self-test
+
+```bash
+node dist/cli.js --selftest
+```
+
+Runs 53 checks over path safety, danger-command detection, sensitive-path
+detection, secret masking, the tool registry, command timeout/process-tree kill,
+environment sanitization, config resolution + save/load (never logging the token),
+and idempotency over a real WebSocket connection. It prints `PASS`/`FAIL` lines
+and exits `0`/`1`.
+
+## Protocol
+
+JSON text frames over a WebSocket.
+
+**Client → server**
+
+```jsonc
+{ "type": "hello", "token": "...", "deviceId": "...", "version": "0.9.0", "platform": "node" }
+{ "type": "pong", "t": 42 }                       // reply to a server ping
+{ "type": "tool_result", "jobId": "j1", "ok": true, "result": { }, "durationMs": 12 }
+{ "type": "status", "state": "online" | "busy" | "error", "sessionId": "..." }
+```
+
+**Server → client**
+
+```jsonc
+{ "type": "welcome", "sessionId": "..." }
+{ "type": "ping", "t": 42 }
+{ "type": "tool_call", "jobId": "j1", "idempotencyKey": "k1", "tool": "write_file", "args": { } }
+{ "type": "cancel", "jobId": "j1" }
+```
+
+## Development
+
+```bash
+npm install
+npm run build          # tsc -> dist/
+npm run test           # node dist/cli.js --selftest
+npm start              # node dist/cli.js
+```
+
+## License
+
+MIT

package/dist/agent.d.ts

@@ -1,7 +1,7 @@
 import { type ClientState } from './protocol';
 import { type AgentConfig } from './config';
 /** Kept in sync with package.json. */
-export declare const AGENT_VERSION = "0.8.5";
+export declare const AGENT_VERSION = "0.9.1";
 export interface AgentHandle {
     stop(): void;
 }

package/dist/agent.js

@@ -12,7 +12,7 @@ const tools_1 = require("./tools");
 const config_1 = require("./config");
 const tokens_1 = require("./tokens");
 /** Kept in sync with package.json. */
-exports.AGENT_VERSION = '0.8.5';
+exports.AGENT_VERSION = '0.9.1';
 const MAX_IDEMPOTENCY_ENTRIES = 512;
 const HEARTBEAT_MS = 30000;
 const READY_OPEN = 1; // ws.WebSocket.OPEN
@@ -168,7 +168,7 @@ class Agent {
     async onToolCall(msg) {
         if (!(0, protocol_1.isToolCall)(msg))
             return;
-        const { jobId, tool, args, idempotencyKey, root } = msg;
+        const { jobId, tool, args, idempotencyKey, root, preApproved } = msg;
         const key = (0, protocol_1.computeIdempotencyKey)(tool, args ?? {}, idempotencyKey);
         if (this.idempotencyCache.has(key)) {
             const cached = this.idempotencyCache.get(key);
@@ -181,7 +181,7 @@ class Agent {
         this.jobs.set(jobId, controller);
         this.log.info('running tool', { jobId, tool });
         try {
-            const result = await this.registry.dispatch(tool, args ?? {}, controller.signal, root);
+            const result = await this.registry.dispatch(tool, args ?? {}, controller.signal, root, preApproved === true);
             if (controller.signal.aborted) {
                 // The platform sent a cancel for this job; report it explicitly.
                 this.sendResult({ ok: false, error: 'Job cancelled by platform', durationMs: result.durationMs }, jobId);