zcode-acp-server 0.1.0 → 0.2.0

package/docs/TROUBLESHOOTING.md

@@ -5,6 +5,7 @@
 ### Backend fails to start
 
 **Symptom:**
+
 ```
 [zcode-acp] backend: started zcode app-server (pid=12345)
 [zcode-acp] backend: reader exited (stdout closed)
@@ -13,12 +14,14 @@
 **Troubleshooting steps:**
 
 1. Check the ZCode CLI version:
+
    ```bash
    zcode --version
    ```
    - Must be >= 0.14.8
 
 2. Check whether `zcode` is on PATH:
+
    ```bash
    which zcode
    ```
@@ -31,22 +34,60 @@
    - Confirm a `provider` is enabled
    - Confirm `models` are defined
 
+### Authentication / credential errors (401, provider auth failed)
+
+**Symptom:** turns fail with authentication errors (e.g. `401`, `provider auth failed`, `invalid api key`), or `~/.zcode/v2/config.json` is missing.
+
+**Why:** This bridge advertises agent-managed auth — it reads the GLM API key from `~/.zcode/v2/config.json` and forwards it to the ZCode subprocess. No editor-side API key or environment variable is involved. If the credentials file is absent, empty, or carries an expired/invalid key, every turn will fail at the first model call.
+
+**Troubleshooting steps:**
+
+1. Confirm the credentials file exists and has an enabled provider:
+
+   ```bash
+   cat ~/.zcode/v2/config.json
+   ```
+   - There must be a `provider` entry with `"enabled": true`
+   - Its `options.apiKey` must be present and non-empty
+
+2. If the file is missing or the key is stale, **install and log into the ZCode desktop app** — it writes a fresh `config.json` with a valid enabled provider. There is no manual API-key configuration in the editor.
+
+3. If you need to override the key/base URL without touching `config.json`, set `ZCODE_BASE_URL` and provide the key via the provider config (see `src/backend/credentials.ts` for the merge order).
+
 ### session/subscribe fails
 
 **Symptom:**
+
 ```
-session/subscribe failed (ZCode CLI 0.14.8+ required)
+session/subscribe failed: <backend error message> [(code <N>)]
 ```
 
+The error message carries the backend's real failure reason. It is **no longer**
+a hardcoded version string — read the message text to identify the root cause.
+
+**Common causes:**
+
+| Message fragment                 | Cause                                                                      |
+| -------------------------------- | -------------------------------------------------------------------------- |
+| `reader exited (backend dead)`   | The zcode subprocess crashed/exited. Restart the editor session.           |
+| `timeout`                        | The per-attempt 10s subscribe deadline elapsed. The bridge retries transient timeouts up to 3× (the backend can be briefly busy finalising a cancelled turn after a preempt / `session/stop`); if all retries fail, the backend was unresponsive for ~30s. |
+| `pipe broken`                    | The stdin pipe to the zcode subprocess broke (process died mid-write).     |
+| `method not found (code -32601)` | The CLI genuinely is too old (< 0.14.8). Upgrade.                          |
+| session-level business error     | The target session no longer exists or was evicted.                        |
+
 **Troubleshooting steps:**
 
-1. Confirm ZCode CLI >= 0.14.8:
+1. **Read the error message** — the fragment identifies the cause (table above).
+
+2. If the message indicates `method not found`, confirm ZCode CLI >= 0.14.8:
+
    ```bash
    zcode --version
    ```
 
-2. If the version is correct but it still fails, check whether the zcode
+3. If the version is correct but it still fails, check whether the zcode
    app-server supports subscribe:
+
    ```bash
    cd /path/to/project
    zcode app-server --stdio
@@ -54,7 +95,7 @@ session/subscribe failed (ZCode CLI 0.14.8+ required)
    { "id": 1, "method": "session/subscribe", "params": { "sessionId": "test", "deliveryKind": "desktop-continuous", "includeSnapshot": true, "afterSeq": 0 } }
    ```
 
-3. Check whether other zcode processes are running:
+4. Check whether other zcode processes are running:
    ```bash
    ps aux | grep zcode
    killall -9 zcode  # caution: this kills all zcode processes
@@ -67,6 +108,7 @@ session/subscribe failed (ZCode CLI 0.14.8+ required)
 **Troubleshooting steps:**
 
 1. Confirm the client declares `terminal_output`:
+
    ```typescript
    // should be present in clientCapabilities:
    { "_meta": { "terminal_output": true } }
@@ -87,9 +129,11 @@ session/subscribe failed (ZCode CLI 0.14.8+ required)
 **Troubleshooting steps:**
 
 1. Check whether `EventStreamListener` subscribed successfully:
+
    ```
    [zcode-acp] backend: started zcode app-server (pid=12345)
    ```
+
    If this log is missing, the backend did not start.
 
 2. Check whether `session/event` pushes arrive:
@@ -106,6 +150,7 @@ session/subscribe failed (ZCode CLI 0.14.8+ required)
 **Troubleshooting steps:**
 
 1. Check whether zcode sent an interaction request:
+
    ```
    [zcode-acp]   -> interaction/requestPermission (zcode_id=100)
    ```
@@ -120,6 +165,43 @@ session/subscribe failed (ZCode CLI 0.14.8+ required)
    - `⚠ elicitation/create failed: ...` → the client does not support it or the request failed
    - `⚠ request_permission failed: ...` → the fallback path failed
 
+### Turn fails with `model_request_failed` / network error
+
+**Symptom:** A turn ends with an error like `model_request_failed` / "Network
+connection failed for the provider request" / "Turn execution failed". Instead
+of stopping the session, the bridge retries transient failures automatically.
+
+**What happens:**
+
+When the ZCode backend emits `turn.failed` with a transient cause (provider
+network blip, rate limit, brief outage), the bridge retries the turn up to
+**5 times** (6 total attempts) with exponential backoff capped at 4s
+(1s / 2s / 4s / 4s / 4s). Each retry re-sends the prompt and surfaces a
+`[网络异常，正在重试 (n/5)…]` hint so the user knows the turn is being retried
+rather than hanging.
+
+Transient errors are identified by the nested `error.cause.code`
+(`model_request_failed`, `provider_not_configured`, `rate_limit`, `timeout`,
+`ECONNRESET`, etc.) or by network/connection/timeout keywords in
+`error.cause.message`. Non-transient failures (e.g. `prompt is running`) still
+surface as hard errors immediately.
+
+After retries are exhausted, the bridge **degrades gracefully**: it emits a
+user-visible `[请求失败：…。会话仍可用，请重新发送消息重试。]` message and returns
+`end_turn`, so the session stays usable — resend the message to try again.
+
+**Debugging:**
+
+```
+ZCODE_ACP_DEBUG=1
+```
+
+Look for `[retry] transient turn failed, re-sending (attempt N/6)` lines to
+confirm the retry path is active. If transient failures persist across all
+retries, the underlying provider/network issue needs investigation (see
+[Authentication / credential errors](#authentication--credential-errors-401-provider-auth-failed)
+and check the provider endpoint reachability).
+
 ### `/` completion menu is empty
 
 **Symptom:** Typing `/` shows no command completion.
@@ -147,6 +229,7 @@ session/subscribe failed (ZCode CLI 0.14.8+ required)
    - backend reader death
 
 2. Manually inspect zombie processes:
+
    ```bash
    ps aux | grep zcode
    killall -9 zcode  # cleanup
@@ -197,6 +280,7 @@ session/subscribe failed (ZCode CLI 0.14.8+ required)
 
 2. If the lock is still stuck on an older bridge, the zcode subprocess must be
    killed manually:
+
    ```bash
    ps aux | grep zcode
    killall -9 zcode  # caution: kills all zcode processes
@@ -239,13 +323,13 @@ export function log(msg: string): void {
 
 ### Common log patterns
 
-| Log | Meaning |
-|------|------|
-| `backend: started zcode app-server (pid=...)` | Backend started successfully |
-| `backend: reader exited (...)` | Backend reader exited (backend may have crashed) |
-| `session/new -> sess_xxx` | New session created successfully |
-| `[event] turn.started` | Turn started |
-| `[event] turn.completed (resultType=...)` | Turn completed |
-| `-> interaction/... (zcode_id=...)` | Interaction request received |
-| `<- replied to zcode (N request(s))` | Interaction request replied |
-| `⚠ ...` | Warning / error |
+| Log                                           | Meaning                                          |
+| --------------------------------------------- | ------------------------------------------------ |
+| `backend: started zcode app-server (pid=...)` | Backend started successfully                     |
+| `backend: reader exited (...)`                | Backend reader exited (backend may have crashed) |
+| `session/new -> sess_xxx`                     | New session created successfully                 |
+| `[event] turn.started`                        | Turn started                                     |
+| `[event] turn.completed (resultType=...)`     | Turn completed                                   |
+| `-> interaction/... (zcode_id=...)`           | Interaction request received                     |
+| `<- replied to zcode (N request(s))`          | Interaction request replied                      |
+| `⚠ ...`                                       | Warning / error                                  |

package/docs/agents/domain.md

@@ -0,0 +1,51 @@
+# Domain Docs
+
+How engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root (if it exists) — it points to one `CONTEXT.md` per context. Read each file relevant to the current topic.
+- **`docs/adr/`** — read ADRs related to the area you are about to work on. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If these files don't exist, **continue silently**. Don't flag the absence; don't proactively suggest creating them. The producer skill (`/grill-with-docs`) will lazily create them when terms or decisions are actually resolved.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Multi-context repo (root has `CONTEXT-MAP.md`):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (issue title, refactor proposal, hypothesis, test name), use the term defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal: either you're inventing language the project doesn't use (reconsider), or there's a genuine gap (note it for `/grill-with-docs`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, call it out explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_

package/docs/agents/issue-tracker.md

@@ -0,0 +1,22 @@
+# Issue tracker: GitHub
+
+This repo's issues and PRDs live in GitHub issues. All operations use the `gh` CLI.
+
+## Conventions
+
+- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
+- **Read an issue**: `gh issue view <number> --comments`, filter comments with `jq`, and fetch labels at the same time.
+- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'`, add `--label` and `--state` filters as needed.
+- **Comment on an issue**: `gh issue comment <number> --body "..."`
+- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **Close**: `gh issue close <number> --comment "..."`
+
+The repo is inferred from `git remote -v`; when running inside a clone, `gh` handles this automatically.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitHub issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `gh issue view <number> --comments`.

package/docs/agents/triage-labels.md

@@ -0,0 +1,15 @@
+# Triage Labels
+
+Skills use five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill refers to a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
+
+Edit the right column to match the vocabulary you actually use.

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "zcode-acp-server",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Agent Client Protocol (ACP) server bridging headless ZCode to editors like Zed and JetBrains.",
   "type": "module",
   "license": "Apache-2.0",
   "author": "ZCode ACP Server Contributors",
   "repository": {
     "type": "git",
-    "url": "https://github.com/zcode-org/zcode-acp-server.git"
+    "url": "https://github.com/william0wang/zcode-acp.git"
   },
-  "homepage": "https://github.com/zcode-org/zcode-acp-server#readme",
+  "homepage": "https://github.com/william0wang/zcode-acp#readme",
   "bugs": {
-    "url": "https://github.com/zcode-org/zcode-acp-server/issues"
+    "url": "https://github.com/william0wang/zcode-acp/issues"
   },
   "keywords": [
     "acp",
@@ -23,7 +23,8 @@
     "zcode"
   ],
   "bin": {
-    "zcode-acp-server": "dist/index.js"
+    "zcode-acp-server": "dist/index.js",
+    "zcode-quota": "dist/bin/quota.js"
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",