zcode-acp-server 0.46.7 → 0.47.1

package/dist/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"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"}

package/docs/ARCHITECTURE.md

@@ -196,6 +196,20 @@ API only because the ZCode backend itself sends them for inference.
 | `runtime-model.ts` | runtimeModel overlay construction and application              |
 | `model-cache.ts`   | Model ID cache and usage initialization                        |
 
+### `settings/` — ZCode configuration management (ADR-0025–0028)
+
+| File                 | Responsibility                                                                                                                                   |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `file-lock.ts`       | ZCode's cross-process file lock (`<path>.lock` + owner files + stale reclaim) so the bridge and a running desktop app never overwrite each other |
+| `atomic-write.ts`    | Locked read-modify-write of a config file: unknown keys preserved, self-validation, backup, temp + rename                                        |
+| `provider-config.ts` | `~/.zcode/v2/provider_config.json`: provider enable/rename, model add/remove, contextWindow / reasoningLevel                                     |
+| `cli-config.ts`      | `~/.zcode/cli/config.json`: skills enablement, MCP servers, hooks tree, plugin enablement                                                        |
+| `agents-config.ts`   | `~/.zcode/v2/agents-state.json` + `~/.zcode/agents/*.md`: subagent CRUD (frontmatter only), enable, model override                               |
+| `skills.ts`          | Skill discovery + enable/delete/copy-to-user with realpath escape guards                                                                         |
+| `usage-stats.ts`     | Local `~/.zcode/cli/db.sqlite` aggregation: per-model tokens + daily buckets                                                                     |
+| `coding-plan.ts`     | Credential decryption + coding-plan reset card status/opportunity/use                                                                            |
+| `app-update.ts`      | ZCode desktop app release check + verified download + bundle swap where the location allows (ADR-0028)                                           |
+
 ### `remote/` — Remote access (opt-in via `ZCODE_ACP_REMOTE=1`)
 
 | File                        | Responsibility                                                                                                                                                                                                                      |
@@ -206,6 +220,7 @@ API only because the ZCode backend itself sends them for inference.
 | `file-endpoint.ts`          | Read-only `GET /fs/list` + `GET /fs/file` on the loopback server (ADR-0004): Session Root scoping, byte/line windows, streaming                                                                                                     |
 | `status-endpoint.ts`        | `GET /status` on the loopback server (ADR-0005): in-memory per-session running state (`pendingTurns` derivation), zero backend RPC                                                                                                  |
 | `session-close-endpoint.ts` | `POST /sessions/{id}/close` on the loopback server (ADR-0006): running-guarded discovery retirement with self-healing re-appearance                                                                                                 |
+| `settings-endpoint.ts`      | `settings/*` routes on the loopback server (ADR-0025): the ZCode configuration API, mounted again by the hub behind the token                                                                                                       |
 | `hub-server.ts`             | The hub singleton: token auth, instance discovery, byte-level WS proxying, heartbeat pruning, on-demand `?probe=1` liveness, idle exit, version self-upgrade, `GET /api/quota` direct query (ADR-0005), POST close proxy (ADR-0006) |
 
 When enabled, the same `AgentApp` serves the stdio editor and a loopback
@@ -248,6 +263,56 @@ surface's first write op: `POST /api/instances/{id}/sessions/{sid}/close`
 retires a conversation from discovery (running-guarded, self-healing if the
 editor still has it open).
 
+### `settings/` — ZCode configuration management (ADR-0025–0028)
+
+The settings API exposes the desktop app's management surface as JSON so a
+native client can render it: models, skills, MCP servers, hooks, subagents,
+app usage, coding-plan reset cards, and app updates. All of it is machine-level
+state under `~/.zcode/` that the desktop app owns, which drives two design
+choices.
+
+First, **the bridge is not the owner of these files** — it is a second writer
+next to a running desktop app. Every write therefore goes through
+`file-lock.ts`, a re-implementation of ZCode's own cross-process lock
+(`<path>.lock` directory + per-holder owner file + stale reclaim), and through
+`atomic-write.ts`'s read-modify-write that preserves unknown keys, self-
+validates, backs up, then temp-file + rename (ADR-0026). Without the shared
+lock a settings write landing during an app write silently discards the app's
+change.
+
+Second, **the API layer is mounted twice from one factory**
+(`remote/settings-endpoint.ts`): on the bridge's loopback server unauthenticated
+(exactly like `/status` and `/fs` — any local process can already write these
+files) and on the hub under `/api/settings/*` behind the token, plus the
+per-instance proxy `…/settings/*`. Writing the routing once and mounting twice
+is what keeps the two in sync (ADR-0025).
+
+Each write reports an **effect class**: `immediate` for the provider table
+(absorbed by the backend's ~1s poll) and skills enablement (read live), versus
+`needs-restart` for MCP servers, hooks, and subagent markdown, which the agent
+reads once at start. The client either prompts or calls
+`POST /api/instances/{id}/backend/restart`, which reuses the sandbox
+arm-flip's cancel-then-respawn path.
+
+App usage stats are aggregated locally from the agent database
+(`~/.zcode/cli/db/db.sqlite`) rather than proxying the backend's `usage/stats`
+RPC, so usage works with no backend process alive and degrades to
+`{available: false}` on a machine that never ran an agent (ADR-0027). Coding-
+plan reset cards are the one irreversible operation: they require the nonce
+from a fresh status read, are restricted to `account:*` providers, and carry an
+idempotency key so a retry cannot burn two cards.
+
+App updates (ADR-0028) reproduce the desktop app's own discovery half — the same
+manifest endpoint, platform/channel spelling, and sha512 verification — but stop
+short of privileged escalation. Whether the bundle can be swapped is probed at
+install time with `accessSync(dirname(app), W_OK)` rather than assumed: a
+writable location is replaced directly (old bundle renamed aside first, deleted
+only after the new one is in place, so a failed install leaves the previous
+version intact), and anything else is reported as `needs-user-install` with the
+artifact path so the client can hand the user a one-step instruction. The
+running app is never killed. No claim is made about which branch a given machine
+takes — that is what the probe is for.
+
 ## Key State Machines
 
 ### Turn state

package/docs/REMOTE-CLIENTS.md

@@ -393,6 +393,291 @@ section — so clients can reproduce the CLI layout exactly:
   later. Only transport-level failures reject the request.
 - Cached ~10s server-side (same caches as the `/quota` command).
 
+## Settings API
+
+The machine's ZCode configuration, exposed as JSON so a native client can
+render the management UI that the desktop app provides (ADR-0025). Plain HTTP,
+no ACP connection needed. **User scope only** — `~/.zcode/`; project-level
+(`<ws>/.zcode/`) configuration is not part of this contract yet.
+
+Two mounts, identical routes and identical semantics:
+
+- `{hub}/api/settings/*` — token-gated (`Authorization: Bearer …` or
+  `?token=…`), the only public entry.
+- `http://127.0.0.1:{bridgePort}/settings/*` — the bridge's own loopback
+  server, **unauthenticated** like `/status` and `/fs`. Any local process can
+  already write these files, so the HTTP route grants no new capability. The
+  bind is `127.0.0.1` only.
+- Per-instance proxying is available too:
+  `{hub}/api/instances/{id}/settings/*` relays to that bridge's loopback
+  mount (same body passthrough as session close/rename).
+
+Every write answers with an **effect class** — read it before deciding whether
+to prompt the user:
+
+| `effect`        | Meaning                                                                 |
+| --------------- | ----------------------------------------------------------------------- |
+| `immediate`     | Applied to the running backend within ~1s (provider table poll, skills) |
+| `needs-restart` | Read once at agent start — needs a new backend process to take effect   |
+
+`needs-restart` applies to MCP servers, hooks, and subagent markdown. After
+such a write, either prompt the user or call
+`POST {hub}/api/instances/{id}/backend/restart`, which cancels in-flight turns
+and respawns that bridge's backend (see below). `GET /api/settings/pending-restart`
+reports whether this process has recorded any `needs-restart` write since it
+started.
+
+### Read endpoints
+
+| Endpoint                     | Purpose                                                                  |
+| ---------------------------- | ------------------------------------------------------------------------ |
+| `GET /settings/all`          | One-shot snapshot of every section (first screen)                        |
+| `GET /settings/models`       | Selectable models, unioned across `config.json` + `provider_config.json` |
+| `GET /settings/skills`       | Discovered skills with their enabled state                               |
+| `GET /settings/mcp`          | Configured MCP servers (user config + enabled plugins)                   |
+| `GET /settings/hooks`        | The full hooks tree, 7 event names                                       |
+| `GET /settings/agents`       | Subagents with enabled state and model override                          |
+| `GET /settings/usage?range=` | `7d` \| `30d` \| `all` per-model token usage                             |
+| `GET /settings/quota`        | Same payload as `/api/quota` (account-level, hub only)                   |
+| `GET /settings/reset-cards`  | Coding-plan reset card status (`?providerId=` required)                  |
+| `GET /settings/backups`      | Config backups available for restore                                     |
+| `GET /settings/app-update`   | ZCode desktop app version check (`?channel=stable\|preview`)             |
+
+`/settings/all` degrades per section: a failure to read the local config files
+is a whole-request `500` (the environment is broken), while `usage` and
+`resetCards` report their own state — no database and no credentials are normal,
+not errors. `resetCards` in the snapshot carries **eligibility only**
+(`providers` + whether the credential store decrypts); the cards themselves need
+a `providerId` and a network read, so fetch them from
+`GET /settings/reset-cards?providerId=…`.
+
+### Write endpoints
+
+| Endpoint                                  | Effect          | Purpose                                     |
+| ----------------------------------------- | --------------- | ------------------------------------------- |
+| `PUT /settings/providers/{id}`            | `immediate`     | Enable/disable, rename                      |
+| `POST /settings/models`                   | `immediate`     | Add a model to an existing provider         |
+| `DELETE /settings/models/{pid}/{mid}`     | `immediate`     | Remove a model                              |
+| `POST /settings/skills/enable`            | `immediate`     | `{path, enable}`                            |
+| `DELETE /settings/skills/{path}`          | `immediate`     | Delete a skill directory                    |
+| `POST /settings/skills/copy-to-user`      | `immediate`     | Copy a workspace skill to `~/.zcode/skills` |
+| `PUT /settings/mcp/{name}`                | `needs-restart` | Create or update an MCP server              |
+| `DELETE /settings/mcp/{name}`             | `needs-restart` | Remove an MCP server                        |
+| `POST /settings/mcp/enable`               | `needs-restart` | `{name, enable}`                            |
+| `PUT /settings/hooks/{event}/{index}`     | `needs-restart` | Edit one existing hook entry                |
+| `POST /settings/hooks/enabled`            | `needs-restart` | `{enabled}` — the whole hooks tree          |
+| `PUT /settings/agents/{id}`               | `needs-restart` | Create or update a subagent                 |
+| `DELETE /settings/agents/{id}`            | `needs-restart` | Delete a subagent                           |
+| `POST /settings/agents/{id}/enable`       | `needs-restart` | `{enable}`                                  |
+| `POST /settings/reset-cards/use`          | —               | Consume a reset card (see below)            |
+| `POST /settings/reset-cards/opportunity`  | —               | Request an opportunity (see below)          |
+| `POST /settings/reset-cards/history-read` | —               | Mark the reset history read                 |
+| `POST /settings/backups/restore`          | per file        | Restore a backup                            |
+| `POST /settings/app-update/install`       | —               | Download and stage a new app build          |
+
+Notes that clients must honor:
+
+- **Methods include PUT and DELETE**, and the hub's CORS preflight allows all
+  four (`GET, POST, PUT, DELETE, OPTIONS`) — a browser-based client can issue
+  them without a plugin fetch shim.
+- **Providers cannot be created or deleted** through this API — only enabled
+  state, display name, and the models inside an existing provider. Adding a
+  brand-new provider stays a desktop-app (or hand-edit) operation.
+- **MCP writes are type-checked**: `type` / `url` / `command` must be strings,
+  `args` an array of strings, `env` / `headers` objects of strings, `enabled` a
+  boolean — anything else is a `400`. Unknown keys still pass through, but a
+  malformed known field is refused rather than persisted: the agent runtime
+  validates each server on its own and silently SKIPS the one that fails, so a
+  bad entry would make the server you just added vanish at the next start with
+  no error anywhere. `type` may be omitted — the runtime infers `stdio` from a
+  `command` and `http` from a `url`, and also accepts a legacy `remote`.
+- **Hooks are read-complete but write-limited**: the tree is returned in full,
+  and writes may only modify an existing entry's `command` / `timeoutMs` /
+  `enabled`. Adding or removing events, matchers, or hook entries is not
+  supported. Unknown keys on a hook object are preserved verbatim.
+- **Subagents**: `name`, `description`, `color`, `model`, `thoughtLevel` are
+  editable; the system-prompt body is not. Built-in agents (`general-purpose`,
+  `Explore`) cannot be edited or deleted — only their model override can change.
+  Send `{"providerId": null, "modelId": null}` on a built-in agent to CLEAR its
+  override and return it to the workspace default.
+- **Reset cards are irreversible.** `POST /settings/reset-cards/use` requires
+  the `nonce` returned by `GET /settings/reset-cards`, is restricted to
+  `account:*` providers (`403` otherwise), and carries an idempotency key so a
+  retry cannot burn two cards. `credentials_unavailable` means the machine's
+  encrypted credential store could not be decrypted.
+- Every write is a locked read-modify-write of the real file: unknown keys are
+  preserved, a backup is taken first, and a write that fails self-validation
+  never lands. Concurrent writers are serialized by ZCode's own cross-process
+  lock, so the last write wins and no change is silently dropped.
+
+### Restarting the backend
+
+```text
+POST {hub}/api/instances/{id}/backend/restart → 200 { "ok": true, "cancelledTurns": 2 }
+```
+
+Cancels that bridge's in-flight turns, kills its `zcode app-server` child, and
+lets the next prompt respawn it — the same path the sandbox arm-flip uses.
+`cancelledTurns` is how many conversations were interrupted; surface it before
+the user commits to the action. The response also carries `closed`: `false`
+means the old child refused to die, the pending flag stays armed (the writes
+were NOT applied), and the restart is worth retrying.
+
+`GET /api/instances/{id}/settings/pending-restart` reports whether that bridge
+process has recorded any `needs-restart` write since it last restarted its
+backend, so a client can ask "is a restart needed?" on a fresh screen instead of
+tracking it itself. The flag is cleared by a successful backend restart.
+
+Use the **per-instance** spelling, not the hub-local
+`GET /api/settings/pending-restart`: the counter lives in the bridge that served
+the write, and the hub has no backend of its own to restart, so its copy can
+never be cleared. The hub-local route therefore answers `409` with a pointer to
+the per-instance spelling rather than a `pendingRestart` boolean — reporting
+`true` would strand a client on "restart needed" with no request able to clear
+it, and reporting `false` would be a claim it cannot verify.
+
+### Reset cards (coding-plan quota)
+
+Three calls, in this order:
+
+```text
+GET  /settings/reset-cards?providerId=account:bigmodel-individual-coding-plan
+POST /settings/reset-cards/use            { providerId, resetType, nonce, idempotencyKey }
+POST /settings/reset-cards/history-read   { providerId }
+```
+
+```json
+→ { "ok": true, "resetCards": {
+      "availableFiveHour": [{ "expireAt": 1790000000000 }],
+      "availableWeek": [],
+      "latestFiveHour": { "usedAt": 1789000000000 },
+      "latestWeek": null,
+      "hasUnreadHistory": true,
+      "nonce": "3f6c…" } }
+```
+
+- `resetType` is `FIVE_HOUR` or `WEEK`.
+- The `nonce` is issued per status read. Sending one that was never issued (or
+  that a newer status read replaced) answers `409` — refresh the status and
+  retry. This is what stops a screen the user left open an hour ago from
+  spending a card they have since seen change.
+- The nonce is burned only **after** the spend settles, never before it. A spend
+  that reached the server and failed on the way back (timeout, dropped
+  response, upstream error) leaves the nonce valid, so the retry is judged by
+  the backend and its idempotency key — not rejected out of hand with a `409`
+  the user cannot act on.
+- A spend already in flight for the same provider is refused with `409` ("a
+  reset for this provider is already in progress"). The deferred burn is safe
+  for a RETRY of the same gesture — same key, so the backend answers with the
+  outcome it already recorded — but a second INDEPENDENT gesture (a double tap,
+  another client that read the same status) brings its own key, and nothing
+  upstream could stop it burning a second card. Serialize the UI on the busy
+  state the client already tracks.
+- The `idempotencyKey` is what makes a retry safe: the same key always answers
+  the same outcome, so a dropped response cannot burn a second card. Generate
+  it once per user gesture and reuse it on retry — a FRESH key per attempt is
+  exactly what defeats it.
+- Status codes carry the retry advice. A `409` is a nonce problem (refresh). A
+  `502`/`504` means the reset API was unreachable or failed — the card may have
+  been spent, so retry with the same key rather than assuming the write failed.
+  A `400` is a request the server rejected outright.
+- A denial is `{ok: true, granted: false, nextTryAt: <ms>}` — a countdown to
+  render, not an error.
+- `credentials_unavailable` means the machine's encrypted credential store
+  could not be decrypted (missing file, wrong `ZCODE_CREDENTIAL_SECRET`, or a
+  different machine's store).
+- Known limit: a **team** plan needs organization/project scope headers whose
+  ids are not in the credential store a headless process can read, so team-plan
+  resets answer a backend error. Personal plans work.
+
+### Usage payload
+
+```json
+{
+  "available": true,
+  "range": "7d",
+  "summary": { "totalTokens": 1587917357, "requestCount": 20630, "models": 7 },
+  "models": [
+    {
+      "modelId": "GLM-5.3",
+      "totalTokens": 1587917357,
+      "inputTokens": 0,
+      "outputTokens": 0,
+      "reasoningTokens": 0,
+      "cacheReadTokens": 0,
+      "requestCount": 11419,
+      "share": 0.53
+    }
+  ],
+  "daily": [{ "date": "2026-09-22", "models": [{ "modelId": "GLM-5.3", "totalTokens": 100 }] }]
+}
+```
+
+`available: false` with zero values means the local agent database does not
+exist on this machine (never ran an agent) — render an empty state, not an
+error. Tool statistics and the activity heatmap are not in the first version.
+
+### Updating the ZCode desktop app
+
+The bridge checks the official release feed and stages the verified download, so
+a client can offer "update available" without the user opening the app.
+
+```text
+GET  /settings/app-update?channel=stable
+POST /settings/app-update/install  { version, url, channel? }
+```
+
+```json
+→ { "ok": true, "appUpdate": {
+      "updateAvailable": true,
+      "currentVersion": "3.14.1",
+      "latestVersion": "3.14.3",
+      "channel": "preview",
+      "platform": "darwin-aarch64",
+      "appPath": "/Applications/ZCode.app",
+      "releaseName": "Release v3.14.3",
+      "releaseNotes": "## 新功能\n…",
+      "files": [{ "url": "https://cdn-zcode.z.ai/…/ZCode-3.14.3-mac-arm64.zip", "sha512": "…" }],
+      "install": { "stage": "idle", "version": null, "receivedBytes": 0, "totalBytes": null } } }
+```
+
+- `channel` is `stable` (default) or `preview`. The preview channel is the app's
+  own opt-in setting; do not switch a user into it silently.
+- `updateAvailable: false` with `currentVersion: null` means **no ZCode app is
+  installed on this machine** — hide the row, do not show an error.
+- Pass `version` and `url` from the same `GET` response you just read. The bridge
+  then **re-reads the manifest itself** and refuses (`409`) unless that exact URL
+  is a current manifest entry with a checksum, and `version` is what the channel
+  is actually serving — so a client cannot ask for an old build (a silent
+  downgrade) or skip verification. A `sha512` in the request body is ignored for
+  the same reason: the manifest's checksum is the one that counts.
+- Only `https://cdn-zcode.z.ai/…` URLs are accepted (`400` otherwise).
+- The install answers `202 Accepted` immediately and runs in the background;
+  poll `GET /settings/app-update` (its `install` field) for progress. A second
+  install while one is running answers `409`.
+
+`install.stage` is the outcome, and clients must render each one differently:
+
+| `stage`              | Meaning and what to show                                                      |
+| -------------------- | ----------------------------------------------------------------------------- |
+| `downloading`        | `receivedBytes` / `totalBytes` progress                                       |
+| `installing`         | Verified, swapping the bundle                                                 |
+| `done`               | Installed. `restartRequired: true` — ask the user to quit and reopen the app  |
+| `needs-user-install` | `artifactPath` holds the verified bundle; the install location needs the user |
+| `failed`             | `error` carries the reason                                                    |
+
+**`needs-user-install` is an outcome, not a failure.** The bridge probes whether
+the install location is writable and swaps the bundle only when it is. When it
+is not, the download and checksum still ran, so the verified bundle is left at
+`artifactPath` and the user finishes the job: show the path (or reveal it in
+Finder), and they drag `ZCode.app` over the old one — macOS raises a one-shot
+confirmation for that replacement. Reporting `done` here would be a lie the user
+discovers on relaunch.
+
+An app installed in a writable location is replaced directly and answers `done`.
+The old bundle is only deleted after the new one is in place, so a failed install
+leaves the previous version intact.
+
 ## Session running status
 
 Two layers (ADR-0005), both plain HTTP — no ACP connection needed:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zcode-acp-server",
-  "version": "0.46.7",
+  "version": "0.47.1",
   "description": "Agent Client Protocol (ACP) server bridging headless ZCode to editors like Zed and JetBrains.",
   "type": "module",
   "license": "Apache-2.0",