@huaqiu/dsh-log 0.0.0-stage → 1.1.2

package/README.md

@@ -1,3 +1,533 @@
-# Temporary Holding Version
+# dsh-log (v1.1.2)
+
+DSH plugin providing two tools with **structured audit logging**:
+
+| Tool | Capability |
+| --- | --- |
+| `call_external_api` | HTTP GET/POST/PUT/PATCH/DELETE/HEAD with host whitelist (SSRF protection), AbortController timeout, recursive sensitive-field masking (keys, URL strings, error text), request/response byte caps, `set-cookie` redaction |
+| `run_external_script` | Executes scripts inside a whitelisted directory (bare file names only — path traversal refused), **interpreter chosen from the file extension**, process-group kill on timeout, byte-capped stdout/stderr capture |
+
+Every invocation emits the spec's unified audit record (`sessionId`, `callId` UUID v4, `schemaVersion`, `tool`, `level`, `seq`, `phase`, masked `request`, truncated `response`, `costMs`, `code`, `errorType`, `error`) as **two records per call** — a `start` record plus exactly one terminal record (`finished` **or** `error`, mutually exclusive) — through a dual sink:
+
+1. **Host log** — one structured JSON line per record on `ctx.logger('dsh-log')`. Cordis's built-in logger only buffers in memory and some DSH builds register no exporters, so the plugin registers its OWN persistent exporter: every record is appended as a JSON line to `$DSH_HOME/logs/dsh-log-YYYY-MM-DD.jsonl` (survives restarts, grep-able, works for non-agent callers too). Files rotate daily and by size (`-partN` siblings past `maxLogFileSizeBytes`), and files older than `logRetentionDays` are cleaned up automatically. If the exporter API is missing or its registration fails, the plugin says so out loud (`event: exporter-unavailable` + `persistentLog: false` on the boot record) instead of silently dropping to an in-memory buffer. Boot also writes one `plugin-started` record carrying the effective config, `pluginVersion` and the sink status for ops. These files are the v1.2 remote-push (ELK/CLS/OTEL) hook point.
+2. **Session stream / Trajectory** — the **terminal** audit record is embedded in the tool's canonical result (`audit` field), which DSH persists through the well-known `tool/result` session event and renders on the WebUI Trajectory page; `render` also prints it as human-readable text.
+
+> **Why not a custom `audit/log` session event type?** This build's persistence restore
+> refuses unknown non-ignorable event types (a session containing one would fail to reload),
+> and `Session.append` cannot mark events ignorable. Embedding the record in the tool result
+> is the persistence-safe, replayable equivalent — documented here as a deliberate v1.0 choice.
+
+## What each channel actually holds
+
+The two sinks are not two renderings of the same thing — they have **different coverage**.
+Verified against a real 30 s TIMEOUT call and its session archive:
+
+| | Host log (channel 1) | Trajectory (channel 2) |
+| --- | --- | --- |
+| Records per call | **2** — `start` + one terminal | **1** — the terminal record only |
+| Written | per record, in real time | once, after the tool returns |
+| Timestamp | every record carries `ts` (ms) | no `ts`; the session event carries `time` |
+| Coverage | non-agent callers (`sessionId: "standalone"`) and boot/lifecycle events too | only calls owned by a session; no boot record |
+| Lifetime | own JSONL files, rotated daily + by size, pruned after `logRetentionDays` | persisted with the session; no rotation or expiry, dies with the session |
+| Durability | best-effort — a failing sink is contained, but never silent: the downgrade is announced at boot, and a sink that dies mid-run reports on stderr and records `event: audit-sink-recovered` (with the lost count) once it writes again | structural — part of the tool result DSH must persist |
+| Consumer | ops / machines: grep, and the v1.2 push to ELK/CLS/OTEL | session replay **and the model's context window** |
+
+Three operational consequences:
+
+- **A call that begins and never returns is invisible on the trajectory.** During that 30 s
+  TIMEOUT the log already held a `start` record while the trajectory was empty.
+- **`isError` on the `tool/result` is `false` even for a failed audit record** (the tool
+  returned normally rather than throwing). Judge failure by `ok` / `audit.errorType`, never
+  by `isError`.
+- Because `seq` is carried on every record, a **lost record is detectable**: a call whose
+  records are not `1, 2` lost one. That is a check the single-record channel cannot make —
+  `tools/audit-log.mjs --incomplete` performs it.
+
+
+---
+
+## Tool surface
+
+### `call_external_api`
+
+| Param | Type | Notes |
+| --- | --- | --- |
+| `url` | string, required | Host must exactly match an `apiAllowHosts` entry |
+| `method` | `GET`\|`POST`\|`PUT`\|`PATCH`\|`DELETE`\|`HEAD` | default `GET` |
+| `headers` | object | Any JSON values; stringified. Sensitive names masked in logs only |
+| `query` | object | Merged into the URL with the URL parser's encoder — a value containing `&`/`=`/spaces **cannot** smuggle an extra parameter |
+| `body` | JSON | Sent for POST/PUT/PATCH/DELETE. Objects/arrays are `JSON.stringify`-ed; **a string is sent verbatim** (form-urlencoded, plain text). No body is sent at all when omitted |
+| `timeoutMs` | integer | Per-call override, clamped to `[1, maxTimeoutMs]`. The audit record shows the **effective** value |
+
+Result: `ok`, `status`, `responseHeaders` (byte-bounded; a 3xx keeps `location` visible
+even though it is never followed), `data`, `error`, `audit`.
+
+### `run_external_script`
+
+| Param | Type | Notes |
+| --- | --- | --- |
+| `scriptName` | string, required | **Bare file name** inside `scriptAllowDir` — paths/separators/`..` refused before any process starts |
+| `args` | string[] | Passed verbatim as argv — never through a shell |
+| `stdin` | string | Piped to the child, then EOF. Only its **byte count** is logged (it is a plausible credential carrier) |
+| `timeoutMs` | integer | Per-call override, clamped to `[1, maxTimeoutMs]` |
+
+Result: `ok`, `exitCode`, `interpreter`, `stdout`, `stderr`, `error`, `audit`.
+
+**Interpreter dispatch (v1.1).** This is what makes the tool actually usable on Windows,
+where a `.py`/`.js`/`.sh` file is *not* directly executable by `CreateProcess` (Node's
+`spawn` fails outright — Windows resolves interpreters through file associations only when a
+shell is involved, which spec §5.5 forbids):
+
+| Extension | Launch |
+| --- | --- |
+| `.py` | `python` → `python3` → `py` (first one found on PATH wins) |
+| `.js` / `.mjs` / `.cjs` | `node` |
+| `.sh` / `.bash` | `bash` → `sh` |
+| `.ps1` | `pwsh`/`powershell` `-NoProfile -ExecutionPolicy Bypass -File` |
+| `.bat` / `.cmd` (Windows) | `cmd.exe /d /s /c` |
+| anything else | executed directly (must be a real executable) |
+
+Interpreter names come from this built-in table, **never from the model**, so no
+caller-supplied string can become an interpreter. A refusal before spawn also names what
+*is* runnable (`… (available in script_allow_dir: a.py, b.sh)`), so a wrong guess is
+recoverable without guessing again.
+
+The child's working directory is `scriptWorkingDir`, defaulting to `scriptAllowDir`, so
+scripts get a predictable cwd instead of inheriting DSH's.
+
+---
+
+## Spec → real DSH SDK adaptation table
+
+The spec document targets an idealized `@dsh/sdk`. The actual DeepSeek Harness (this
+checkout) uses the Cordis plugin system + `@deepseek-ai/dsh-tools`; per the spec's own
+instruction ("如接口签名不一致，优先适配真实SDK，业务逻辑、日志模型、安全规则保持不变"),
+the business logic, log data model, masking/truncation rules and security rules are
+implemented unchanged in `audit-core.ts`, while the adapter surface maps as follows:
+
+| Spec (assumed) | Real DSH (this implementation) |
+| --- | --- |
+| `defineTool({ id, name, params, handler(ctx) })` from `@dsh/sdk` | `defineTool({ name, description, parameters, output: { schema, render }, execute(args, exec) })` from `@deepseek-ai/dsh-tools`; registered via `ctx.tools.register(...)` |
+| `ctx.sessionId` | `exec.agent.session.id` (Agent → Session; same seam the todo/schedule tools use); non-agent callers log under `sessionId: "standalone"` |
+| `ctx.config` (yml values) | Cordis plugin `Config`: schemastery schema validated + defaulted at plugin load, values supplied by the `cordis.patch.yml` entry's `config:` block |
+| `ctx.log.info / ctx.log.error` → session event stream | Dual sink above: host logger JSON lines **plus** audit record embedded in the tool result (persisted via `tool/result`, Trajectory-replayable) |
+| standalone yml plugin file loaded directly | Plugin is an ESM module with Cordis exports (`name`/`inject`/`Config`/`apply`); registered through a patch entry. `dsh-log.yml` is kept as the spec's config reference document |
+| `callId` = generated UUID | `callId` is always a fresh UUID v4 (spec §3); DSH's own `exec.callId` rides along as an extra `dshCallId` field for joining with `tool/call`/`tool/result` events |
+
+Config key mapping: `api_allow_hosts → apiAllowHosts`, `script_allow_dir → scriptAllowDir`,
+`default_timeout → defaultTimeoutMs`, `maxReqLogSize → maxReqLogBytes`,
+`maxRespLogSize → maxRespLogBytes`, `maxOutputLogSize → maxOutputLogBytes`.
+Hardening keys added beyond the spec reference: `maxTimeoutMs` (ceiling for a per-call
+timeout override, default 120000; boot fails if it is below `defaultTimeoutMs`),
+`scriptWorkingDir` (defaults to `scriptAllowDir`), `maxResponseBytes` (response-body memory
+cap, default 10 MiB), `maxRequestBytes` (request-body memory/egress cap, default 1 MiB),
+`logRetentionDays` (audit-log retention, default 14) and
+`maxLogFileSizeBytes` (rotation budget per file, default 20 MiB).
+(`enable_otel` is a v1.2 switch — not read in v1.0.)
+
+### Deliberately NOT implemented
+
+- **Retries / backoff.** A retry loop would turn one audit record ("this call") into an
+  ambiguous number of transport attempts and break the `seq` = 1/2 invariant the lost-record
+  check depends on. Retry belongs in the caller, where it is itself auditable.
+- **Following redirects.** `redirect: 'manual'` is load-bearing: the whitelist only validates
+  the initial URL, so a 302 from a whitelisted host would otherwise pivot to an internal
+  address. The `location` header is returned instead, so the caller sees where it was sent.
+- **Model-supplied env vars for scripts.** `NODE_OPTIONS`, `PYTHONPATH`, `LD_PRELOAD`,
+  `BASH_ENV`… turn "run a whitelisted script" into "run an arbitrary file outside the allow
+  dir". Credentials can be passed as argv (and/or read by the script itself).
+
+---
+
+## Files
+
+```
+dsh-log/
+├── index.ts                     # DSH adapter: Cordis plugin exports + both defineTool registrations + audit sinks
+├── audit-core.ts                # Pure business logic (SDK-free): masking (incl. URL-aware), truncation, whitelist, path traversal, interpreter dispatch, fetch, spawn+process-group kill
+├── dsh-log.yml     # Spec §8 config reference (values are registered via cordis.patch.yml — see below)
+├── package.json                 # type: module (ESM + native TS execution), dependency declarations, npm scripts (test / demo / log)
+├── tsconfig.typecheck.json      # Standalone typecheck config (paths → DSH checkout; see "Typechecking" below)
+├── tools/
+│   └── audit-log.mjs            # Host-log reader CLI: filter, stats, and lost-record detection (`npm run log`)
+└── test/
+    ├── audit-core.test.ts       # 62 unit tests: masking (keys + URLs + text + folded names) / truncation / uuid / whitelist / whitelist-hygiene classification / traversal / timeout resolution / interpreter dispatch + live HTTP & spawn round-trips (incl. redirect refusal, response-body cap, request-body cap, set-cookie redaction, .js execution, stdin, cwd)
+    ├── plugin.test.ts           # 31 acceptance tests (spec §12 cases 1–7 + §5.6 internal-exception, standalone caller, callId chaining + phase/seq, lossless JSON, persistent/rotated log, startup record, sink-downgrade warning, sink write-failure reporting, v1.1 request/response surface, v1.1.1 leak-surface closure, v1.1.2 allowlist-risk warning + per-call address class)
+    ├── audit-log.test.ts        # 10 CLI tests: table/stats/json/error filters, legacy records without phase/seq, lost-record detection, v1.1.2 event types, helpful failure on a missing dir
+    ├── register-stubs.mjs       # `node --import` entry: registers the module hook
+    ├── stub-loader.mjs          # Resolves @deepseek-ai/* to local stubs (defineTool/z/Context stand-ins)
+    └── stubs/                   # dsh-tools.ts, schemastery.ts, cordis.ts
+```
+
+## Deployment (real DSH)
+
+1. Copy the `dsh-log/` folder into the **profile directory** (the directory
+   holding the profile's `cordis.yml`, e.g. under `$DSH_HOME/profiles/<name>/`). The
+   loader anchors relative plugin specifiers at that directory.
+2. Register in the profile's **`cordis.patch.yml`** (or the home-level
+   `$DSH_HOME/cordis.patch.yml`) — the same file the spec document names:
+
+   ```yaml
+   - insert:
+       - id: dsh-log
+         name: ./dsh-log/index.ts
+         config:
+           apiAllowHosts: [api.example.com]
+           scriptAllowDir: /opt/dsh/scripts/
+           scriptWorkingDir: /opt/dsh/work     # optional; defaults to scriptAllowDir
+           defaultTimeoutMs: 30000
+           maxTimeoutMs: 120000                # ceiling for a per-call timeoutMs override
+           maxReqLogBytes: 2048
+           maxRespLogBytes: 2048
+           maxOutputLogBytes: 512
+   ```
+
+   (Explicit `/index.ts` — Node ESM needs the file extension; `name:` is resolved
+   relative to the profile directory where the Loader anchors its base URL.)
+3. Restart the DSH service. The WebUI tool list shows `call_external_api` and
+   `run_external_script`.
+
+Notes:
+
+- **The profile copy is the one that runs.** The loader anchors `./dsh-log/index.ts`
+  beside the profile directory, so editing this source folder has no effect until it is
+  re-copied there and the DSH service is restarted. On this machine the live copy is
+  `$DSH_HOME/profiles/web/dsh-log/` (registered from
+  `$DSH_HOME/profiles/web/cordis.patch.yml`).
+- `scriptAllowDir` is **required** — boot fails loud when empty (a script tool with no
+  allow dir is a misconfiguration, not a runtime surprise).
+- An empty `apiAllowHosts` does not break boot; every API call is then refused at
+  runtime with `PERMISSION_DENIED` (fail closed).
+- The SDK packages (`@deepseek-ai/dsh-tools`, `@deepseek-ai/schemastery`,
+  `@deepseek-ai/cordis`) resolve from the DSH host's own module graph — no local
+  `node_modules` install is needed in the plugin folder.
+
+## Usage (agent calls)
+
+```
+使用 call_external_api，url="https://api.example.com/info", method="POST", headers={"token":"xxx"}, body={"name":"test"}
+```
+
+```
+使用 call_external_api，url="https://api.example.com/items", query={"page":2,"sort":"created"}, timeoutMs=10000
+```
+
+```
+使用 run_external_script，scriptName="get_data.py", args=["2026"], timeoutMs=60000
+```
+
+`scriptName` is a **bare file name** — the script must live in `scriptAllowDir`;
+paths/separators/`..` are refused before any process starts, and the extension selects the
+interpreter (so `get_data.py` runs under `python`). After either call, the structured audit
+record (masked request, truncated response/output, costMs, code, errorType) is visible in
+the session Trajectory via the tool result and in the host log as JSON lines.
+
+## Reading the log (ops)
+
+`tools/audit-log.mjs` is a zero-dependency reader for channel 1 — run it with
+`npm run log -- <options>` (or `node tools/audit-log.mjs`):
+
+```sh
+node tools/audit-log.mjs                     # newest day: header + last 20 records
+node tools/audit-log.mjs --stats             # calls, phases, error mix, p50/p95 latency
+node tools/audit-log.mjs --errors --tail 50  # recent failures
+node tools/audit-log.mjs --call 8b47827d     # one invocation (callId prefix works)
+node tools/audit-log.mjs --incomplete        # calls that LOST a record
+node tools/audit-log.mjs --all --json        # every rotated file, raw JSON lines
+```
+
+`--incomplete` is the part the trajectory cannot replace: it groups records by `callId`
+and reports
+
+- `缺终态` — the call started and never reported back (killed mid-flight, or still running), and
+- `首条记录丢失` / `seq 不连续` — the log's own `seq` proves a record should exist and does not.
+
+Lost-record detection needs `seq` evidence, so logs written by versions before 1.0.1
+(no `phase`/`seq`) still analyse, just with the `缺终态` check only — those older records
+are classified by field-presence inference. The reader defaults to `$DSH_HOME/logs`
+(falling back to `~/.dsh/logs`), reads all `-partN` siblings of the newest day, and
+tolerates unparsable lines instead of dying on them.
+
+## Security model (spec §5, enforced in `audit-core.ts`)
+
+1. **SSRF protection** — exact case-insensitive host match against `apiAllowHosts`; only
+   `http:`/`https:` schemes accepted; refusal happens before any network I/O. Redirects
+   are **never followed** (`redirect: 'manual'`): fetch's default redirect-following would
+   let a whitelisted host 302-jump to an internal address and bypass the gate (only the
+   initial URL is validated) — a 3xx response is reported as-is with its status and the
+   body is cancelled so no second request can happen.
+2. **Script containment** — bare file names only (absolute paths, separators and `..`
+   components refused), resolved path re-checked under the allow dir, target must exist
+   as a regular file; missing script → `PERMISSION_DENIED`. The refusal also lists what is
+   available, which is a usability feature, not a security one: the model could already
+   learn the directory contents from its own container.
+3. **Recursive masking** — keys naming any of `token/secret/password/ak/sk/accessKey/apiKey`
+   become `***` in log copies only; the live request keeps raw credentials. Names are **folded**
+   (lowercased, separators stripped) before matching, so `apiKey`, `api_key`, `api-key` and
+   `x-api-key` are all recognised — a separator cannot hide a credential. Applied to the request
+   segment, the API response summary AND the free-text `error` field of every record
+   (spec §5.3: logs must never store credentials in plaintext — an API that echoes request
+   headers back, or a refusal that quotes the caller's own input, would otherwise leak them).
+   A secret with no matching KEY is still caught when it hides **inside a URL string**: query
+   values and userinfo are masked in absolute URLs, in bare relative references
+   (`/v1/x?token=…`) and in free text that quotes one back (`your request to …?token=… failed`)
+   — the everyday shape of an error body. Ordinary prose is never rewritten. Cyclic references
+   become `[Circular]` instead of crashing. Script stdout/stderr are plain strings (no keys to
+   mask) and are bounded by truncation only — but a URL echoed into stdout is masked by the
+   same pass.
+   **The two-letter keywords over-match on purpose.** `ak`/`sk` are matched as substrings of the
+   folded name, so an innocuous `task`, `disk` or `mask` is redacted too. Over-masking a log field
+   is free; under-masking a credential is not — so the direction is deliberate, and it becomes a
+   naming RULE for every audit record: **a field whose name contains `ak` or `sk` is redacted
+   whatever its value.** (`hostRiskTier` folded to `hostri[sk]tier` and was silently masked to
+   `***` — which is why the address class is called `addressClass`.) A test pins both the
+   over-match and the field names that must survive it.
+4. **Global timeout** — both tools bound by `defaultTimeoutMs`, overridable per call via the
+   `timeoutMs` argument and clamped to `maxTimeoutMs`. API via AbortController, scripts via
+   process-group kill (POSIX: `SIGKILL -pid`; Windows: `taskkill /t /f`, array args — never
+   a shell string). When several interpreter candidates are tried, ONE timer covers the whole
+   invocation, so probing several interpreters cannot extend the budget. Caller cancellation
+   (`exec.signal`) is honored too.
+5. **No shell injection** — script args pass through verbatim as argv; no shell string is
+   ever built or concatenated. Interpreter names come from an internal table, never from the
+   model. On Windows, `.bat`/`.cmd` files are routed through
+   `cmd.exe /d /s /c <fullPath> <args…>` — still a pure argv array (the gated full path
+   and each arg are separate elements, never string-concatenated), with the batch's exit
+   code propagated back.
+6. **Audit integrity** — top-level try/catch in both tools: even a plugin-internal
+   exception yields an `INTERNAL_ERROR` audit record (`ok: false` result); the host-log
+   sink itself is failure-contained so a broken sink cannot mask the business outcome.
+   `runExternalScript` additionally contains *synchronous* spawn rejections (Windows throws
+   `EFTYPE`/`EINVAL` outright for a file `CreateProcess` cannot start) so its promise never
+   rejects — the "always audited" guarantee depends on that.
+   A sink that fails at RUN time is no longer invisible either: the first failure (then at
+   most once a minute) is reported on **stderr** — deliberately not through the logger, whose
+   only persistent output *is* that sink — and the next successful write appends
+   `event: audit-sink-recovered` carrying how many records were dropped meanwhile. Without
+   that, a mid-run failure would leave a truncated file that reads as "no calls happened".
+7. **Response memory cap** — API response bodies are STREAMED with a byte budget
+   (`maxResponseBytes`, default 10 MiB) instead of buffered whole; beyond it the request
+   is aborted and classified `NETWORK_ERROR`, so a malicious/faulty endpoint returning a
+   huge body cannot OOM the DSH process. Log-side truncation (item 3's siblings) still
+   applies on top for what actually fits in memory. Response headers are surfaced under a
+   separate 8 KiB budget (`MAX_RESPONSE_HEADER_BYTES`), where `set-cookie`/`set-cookie2`
+   values are replaced by `[REDACTED]` **at the source** — so the session credential reaches
+   neither the log nor the model, and the two cannot drift apart. Nothing is lost by that:
+   this tool holds no cookie jar, so the caller could not use the value anyway.
+8. **Request memory/egress cap** — the request body is serialized ONCE, measured, and refused
+   **before any I/O** when it exceeds `maxRequestBytes` (default 1 MiB), the exact counterpart
+   of item 7: the response side is bounded because a hostile endpoint controls it, the request
+   side because the *model* does. The refusal is classified `PERMISSION_DENIED` — a local
+   pre-flight rejection, like the whitelist gate — so it stays inside the spec's enum instead
+   of inventing a class every consumer would have to learn.
+9. **Whitelist hygiene** — the gate compares host STRINGS, so it can never notice that a
+   whitelisted host *is* the cloud metadata service or an intranet box. `classifyHost` answers
+   that **lexically** (special-purpose IP literals + private-use name suffixes; no DNS lookup —
+   the gate must stay a pure string comparison, and a request-path resolver would be both a
+   latency and a TOCTOU liability). Boot emits `event: allowlist-risk` at **WARN** when an entry
+   lands in `metadata` / `link-local` / `private` (IMDS `169.254.169.254`, `fd00:ec2::254`,
+   RFC1918, `fe80::/10`, ULA, CGNAT, `.internal`/`.local`/`.home.arpa`, single-label names), and
+   tags **loopback** (`127.0.0.0/8`, `::1`, `localhost`, `0.0.0.0`) as `INFO` only — warning on
+   `127.0.0.1` would train the operator to ignore the warning that matters. The boot record always
+   carries `allowlist: { entries, risks, scope }`, where `scope` states the limit out loud: a
+   public name that *resolves* to a private address is not detectable without DNS. Warnings are
+   advisory, never fatal — reaching an intranet API can be a legitimate deployment. Every audited
+   call additionally carries `request.addressClass` (short tier only, positioned high so a tight
+   `maxReqLogBytes` cannot truncate it away), which labels a refusal too: "this attempt was aimed
+   at the metadata service" is the fact an incident review needs and the fact a URL never states.
+
+## Error classification (spec §6)
+
+| errorType | API tool | Script tool |
+| --- | --- | --- |
+| `TIMEOUT` | request exceeded the effective timeout (AbortController fired) | process group killed at the effective timeout |
+| `NETWORK_ERROR` | fetch/TLS/connection failure (incl. mid-body drop); response body exceeded `maxResponseBytes` (aborted) | — |
+| `PERMISSION_DENIED` | host not whitelisted / non-http(s) scheme / invalid URL / request body over `maxRequestBytes` | traversal, absolute path, missing script, interpreter not found on PATH, a target the OS refuses to start, missing `scriptWorkingDir`, spawn failure |
+| `SCRIPT_EXIT_ERROR` | — | non-zero exit code (`code` carries the exit code) |
+| `INTERNAL_ERROR` | plugin-internal exception (top-level catch) | plugin-internal exception; caller abort (USER_CANCEL tracking lands in v1.3) |
+
+Non-2xx HTTP responses are **not** errors in v1.0 (the spec's enum has no HTTP_ERROR
+class): the call returns `ok: true` with `status` and the parsed body; the audit record
+carries the code for review.
+
+## Running the tests
+
+From the plugin folder (Node ≥ 23.6, native TypeScript execution):
+
+```sh
+# all three suites (103 tests)
+npm test
+
+# 62 unit tests — pure core, no stubs
+node --test test/audit-core.test.ts
+
+# 31 acceptance tests — real index.ts adapter with SDK boundary stubbed
+node --import ./test/register-stubs.mjs --test test/plugin.test.ts
+
+# 10 CLI tests — the host-log reader
+node --test test/audit-log.test.ts
+```
+
+The acceptance suite covers spec §12 end-to-end through `apply() → ctx.tools.register →
+tool.execute(args, exec)`: case 1 whitelist refusal (asserts zero server hits), case 2
+masking (server echoes raw credentials back to prove the live request is untouched),
+case 3 timeout, case 4 path traversal, case 5 normal run, case 6 non-zero exit,
+case 7 oversized-body truncation (full payload verified at the server), plus §5.6
+internal-exception auditing, standalone (non-agent) callers, single-callId chaining
+with `phase`/`seq` ordering across one invocation, lossless-JSON result regression,
+persistent host-log durability, the `plugin-started` config record (including its
+`persistentLog` flag), the loud sink-downgrade warning for a logger without the
+`exporter` API, and size-based rotation (`-partN`) with retention cleanup of stale
+dated files.
+
+v1.1 adds: `query` merging with encoding (asserting a `&` in a value cannot create an
+extra parameter) and its name-based masking; a credential inside the URL string being
+masked even in the response echo; `responseHeaders` reaching both caller and audit record;
+a 3xx reporting `location` while the server is hit exactly once; a per-call `timeoutMs`
+override shortening a hung call and appearing in the `start` record; a string body going out
+verbatim vs. an object body being JSON-encoded; a `.js` script running under `node` with a
+predictable cwd and `interpreter` in the audit record; stdin being piped while only its byte
+count is logged; and a refusal naming the scripts that are actually available.
+
+v1.1.1 adds the leak-surface and health cases: a credential quoted back inside an error
+message reaching neither the log nor the result (the traversal refusal echoes the caller's
+own file name, which is exactly how it would escape); `set-cookie` redacted in both the
+audit log and the model-visible result while `x-trace` passes through; a 1 MiB+1 request
+body refused with zero server hits and a complete `start` + `error` record pair; and a sink
+pointed at an unwritable path announcing itself on stderr rather than dropping records
+silently.
+
+v1.1.2 adds the whitelist-hygiene cases: the tier table asserted directly (loopback /
+private / link-local / metadata, including IPv4-mapped `::ffff:169.254.169.254` and the
+`172.32.0.1` / `192.169.0.1` boundaries that must NOT be flagged); a near-miss that is not
+an address (`999.1.1.1`) staying half-classified-free; the single-label rule not swallowing
+a global IPv6 literal (a real bug this suite caught — `2606:4700::1111` has no dot either);
+whitespace/case/zone-id/bracket normalisation; a boot context whose whitelist mixes public,
+private, metadata and loopback entries, asserting the WARN line lists exactly the three
+warned hosts with reasons while loopback stays out of it; the suite's own loopback-only
+whitelist raising NO warning; and a refused call still carrying `request.addressClass`
+(incl. a metadata-targeted attempt). It also pins the masker's deliberate over-match
+(`task`/`disk`/`mask` → `***`) alongside the field names that must survive it.
+
+The CLI suite proves the reader on a fixture containing a complete call, a call missing
+its terminal record, a call whose first record was lost, a call that failed *before*
+starting (which must not be reported as broken), a corrupt line, legacy records
+without `phase`/`seq`, and v1.1.2 records (`allowlist-risk` counted as an event, not a
+parse failure; the unknown `addressClass` field round-tripping untouched).
+
+## Typechecking against the real SDK types
+
+`tsconfig.typecheck.json` maps `@deepseek-ai/dsh-tools`, `@deepseek-ai/schemastery` and
+`@deepseek-ai/cordis` into a local DSH checkout (edit the `paths` values to your
+checkout location):
+
+```sh
+node <dsh-checkout>/node_modules/typescript/bin/tsc -p tsconfig.typecheck.json
+```
+
+Result on this checkout: **zero errors in `index.ts` / `audit-core.ts`**. The remaining
+diagnostics are pre-existing strict-mode findings inside the vendored
+`vendor/cordis/src/*.ts` sources (cordis ships no built `.d.ts`, so the standalone
+harness compiles its raw source under this config's stricter flags); they are unrelated
+to this plugin and do not appear in DSH's own build.
+
+## v1.2+ roadmap hooks (per spec §2/§7)
+
+- Remote log push: consume the rotated host-log JSONL files (`$DSH_HOME/logs/dsh-log-YYYY-MM-DD*.jsonl`; single structured sink already in place).
+- OTEL metrics, sampling, webhook alerts — off by default (`enable_otel: false`).
+- v1.3: global audit middleware subscribing `tool.beforeInvoke/afterInvoke/onError` +
+  `USER_CANCEL` event logging; per-invocation spanId.
+
+## Changelog
+
+- **1.1.2** — additive; `schemaVersion` stays `1.0` (no audit field changed shape; the new
+  information rides inside `request` plus a new lifecycle event). Readers of 1.0/1.1.x
+  records are unaffected.
+  - **A risky whitelist entry is announced at boot** (`event: allowlist-risk`, WARN). The gate
+    compares host strings, so it can never notice that a whitelisted host *is* the cloud
+    metadata service (`169.254.169.254`, `fd00:ec2::254`, `metadata.google.internal`) or an
+    intranet box (RFC1918, IPv6 ULA, CGNAT, `fe80::/10`, `.internal`/`.local`/`.home.arpa`,
+    single-label names). `classifyHost` decides *lexically* — no DNS, so the request path stays
+    a pure string comparison — and boot states the limit of that method rather than implying a
+    guarantee it cannot give. **Loopback is `INFO`, never part of the warning**: warning on
+    `127.0.0.1` would train the operator to ignore the warning that matters. Advisory, not
+    fatal — reaching an intranet API can be a legitimate deployment.
+  - **Every audited call carries `request.addressClass`** (the short tier: `loopback` /
+    `private` / `link-local` / `metadata`) and it labels a *refusal* too, because the attempt is
+    recorded before the gate runs. The field sits high in the request object on purpose: at
+    ~15 bytes it must not be what a tight `maxReqLogBytes` truncates away.
+  - **The masker's deliberate over-match is now a documented contract, with a naming rule
+    attached.** `ak`/`sk` match as substrings of the folded key name, so `task`, `disk` and
+    `mask` are redacted as well. This is the safe direction, but it bit this very release:
+    `request.hostRiskTier` folded to `hostri[sk]tier` and its value was silently masked to
+    `***` — the field is therefore named `addressClass`. Any future audit field must avoid the
+    substrings `ak`/`sk`; a test pins both the over-match and the names that must survive.
+  - **One bug caught while writing the tests**: the single-label rule (a dotless host resolves
+    locally, never on the public internet) also matched global IPv6 literals, which have no dot
+    either — so `2606:4700::1111` was reported as `private`. Address literals are now excluded
+    from the name rules, and IMDS detection matches on octets so the IPv4-mapped
+    `::ffff:169.254.169.254` is recognised as metadata rather than merely link-local.
+- **1.1.1** — additive; `schemaVersion` stays `1.0` (no audit field changed shape). Closes the
+  remaining leak surfaces and makes a broken sink audible.
+  - **The `error` field is masked.** Every record's free-text `error` (and the `error` handed
+    back to the caller) now passes through the same URL-aware masking as the request segment.
+    This mattered because error strings are *helpful by design* — a refusal quotes the offending
+    input back so the model can correct it, and that echo is exactly how a credential would
+    leave the tool. `fetch` failures and internal exceptions are covered too, since their
+    messages are not ours to control.
+  - **Credential names are matched across separators.** `isSensitiveName` folds a name
+    (lowercase, separators stripped) before matching, so `apiKey` / `api_key` / `api-key` /
+    `x-api-key` are all recognised; previously only spellings containing the keyword
+    contiguously were masked, and `api_key` slipped through. (Found by a new test that expected
+    it to be caught — the test was right and the code was wrong.)
+  - **`maxRequestBytes` (default 1 MiB)** caps the request body. It is serialized once, measured,
+    and refused **before any I/O**, so an oversized body is never pushed onto the wire — the
+    counterpart of `maxResponseBytes`. Classified `PERMISSION_DENIED` (a local pre-flight
+    rejection, like the whitelist gate) rather than adding a new class to the spec's enum.
+  - **`set-cookie`/`set-cookie2` are redacted at the source** (inside `collectResponseHeaders`),
+    so the session credential reaches neither the audit log nor the model and the two cannot
+    drift apart. Nothing usable is lost: this tool holds no cookie jar.
+  - **A sink that dies mid-run reports itself.** Write failures are counted and announced on
+    stderr — first failure immediately, then at most once a minute — and the next successful
+    write appends `event: audit-sink-recovered` carrying how many records were dropped meanwhile.
+    Previously the only trace of a mid-run failure was a file that quietly stopped growing,
+    which reads as "no calls happened".
+- **1.1** — additive; `schemaVersion` stays `1.0` (no audit field changed shape; new
+  information rides inside `request`/`response`). Readers of 1.0 records are unaffected.
+  - **`run_external_script` picks the interpreter from the file extension.** On Windows a
+    `.py`/`.js`/`.sh` file could not be spawned AT ALL in v1.0 — the tool only worked for
+    `.bat`/`.cmd` and real executables. Now `.py`/`.js`/`.mjs`/`.cjs`/`.sh`/`.bash`/`.ps1`
+    run under their interpreter (with candidate fallbacks, e.g. `python`→`python3`→`py`),
+    and the interpreter that actually ran is recorded on the audit record.
+  - **Per-call `timeoutMs`** on both tools, clamped by the new `maxTimeoutMs` ceiling
+    (default 120000; boot fails if it is below `defaultTimeoutMs`). The audit record shows
+    the effective value.
+  - **`call_external_api`**: added `PATCH`/`HEAD`; a `query` object merged with proper
+    percent-encoding; `responseHeaders` returned (and logged) under a byte budget, so a 3xx's
+    `location` is visible without ever following it; a **string body is sent verbatim**
+    instead of JSON-quoted; no body at all is sent when omitted (previously a literal `null`).
+  - **`run_external_script`**: `stdin` piped to the child (logged as a byte count only) and a
+    configurable `scriptWorkingDir` (defaults to `scriptAllowDir`) so scripts get a
+    predictable cwd. A refusal now names the scripts that ARE available.
+  - **Masking is URL-aware.** A credential with no matching KEY is now masked when it hides in
+    a URL string: query values and userinfo in absolute URLs, bare relative references
+    (`/v1/x?token=…`) and URLs quoted inside prose (`… request to /v1/x?token=… failed`) —
+    i.e. the shape an API's error body usually takes. Ordinary prose is never rewritten.
+  - **Robustness**: `runExternalScript` contains synchronous spawn rejections (Windows throws
+    `EFTYPE`/`EINVAL` for a file `CreateProcess` cannot start) so its promise never rejects;
+    a missing working directory is refused up front instead of being misreported as a missing
+    interpreter; one timer covers all interpreter candidates.
+- **1.0.1** — additive; readers of 1.0 records are unaffected.
+  - `phase` (`start`/`finished`/`error`) and `seq` on every record: the lifecycle is
+    explicit and a lost record becomes detectable (previously only inferable).
+  - Boot record carries `pluginVersion`, `persistentLog` and `logDir`; if the logger has no
+    `exporter` API or registration fails, the plugin emits `event: exporter-unavailable`
+    at WARN (and `persistentLog: false`) instead of downgrading to an in-memory buffer silently.
+  - Request log segments are built through a never-throwing path with a credential-free
+    fallback (the fallback strips query strings), so a masking failure can no longer cost
+    the `start` record.
+  - New `tools/audit-log.mjs` host-log reader: filters, statistics, lost-record detection,
+    legacy-record inference; `npm test` / `npm run demo` / `npm run log` scripts added.
+  - README corrected: **two** records per call (start + one terminal), not three events.
+- **1.0** — initial release (spec §1–§12).
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.