@agentchatham/cli 2.26.0 → 2.28.0

package/CLAUDE.md

@@ -26,8 +26,11 @@ register:     src/registration.ts    — bindOrRegister: idempotent register-or-
 storage:      src/agentConfig.ts     — per-agent cli.json (read/writeAgentConfig: harness+mode); NO cli dep,
                                         so registration.ts reuses it without depending on cli/
 slash-cmds:   src/commands/          — agent in-chat slash-commands (distinct from cli/commands.ts)
+errors:       src/errors/            — ErrorClass/TurnError vocabulary + formatting; no classification
 abstraction:  src/provider.ts        — ProviderAgent / ProviderAdapter interfaces
 adapters:     src/providers/*/       — one per provider, implements ProviderAdapter
+                                        <name>/errors.ts classifies that harness's failures
+              src/providers/shared/  — prose + errno tables the classifiers fall back on
 loop:         src/dispatcher.ts      — buffer, retry, watermarks; private to /cli
 format:       src/prompts.ts         — formatters; input is ParsedNotification not raw events
 infra:        src/lifecycle.ts       — shutdown choreography
@@ -52,6 +55,83 @@ infra:        src/lifecycle.ts       — shutdown choreography
 4. Add case in `src/auth.ts` and `selectAdapter()` in `src/server.ts`
 5. Add provider SDK dep to `package.json` (exact pin)
 6. Add `test/providers/<name>/adapter.test.ts` using `fakeAgent`
+7. Create `src/providers/<name>/errors.ts` — export `create<Name>ErrorTracker()`,
+   wire it into the adapter, and add the harness to `test/errors/conformance.test.ts`
+
+## Error classification
+
+Each harness classifies its own errors in `src/providers/<name>/errors.ts`, because
+the four share no error types: Claude has typed stream events, Cursor typed error
+subclasses, Codex and Gemini carry their cause as prose inside stream events.
+
+`src/errors/` holds what is common and nothing else:
+
+- `types.ts`  — `ErrorClass` / `TurnError`, the vocabulary every classifier returns.
+- `format.ts` — `makeTurnError` (the only constructor), `safeCode`, `withError`
+                (the one place a failure is logged), `formatChannelNotice`,
+                `toErrorInfo` (the wire projection).
+
+It contains no branch that decides what an error is, and imports nothing from
+`src/providers/`. `providers/shared/textPatterns.ts` holds the last-tier prose
+table — used by Codex, Gemini and Cursor's fallback — and the errno mapping,
+which is Node's vocabulary rather than any harness's and is used by all four.
+
+A classifier collects signals across the turn and resolves once; precedence is the
+`??` chain in its `resolve()`, most specific cause first. Rule ids are
+`<harness>/<signal>/<variant>`, so a rule can be found and disabled by name.
+`test/errors/conformance.test.ts` asserts all four harnesses map equivalent
+failures onto the same `ErrorClass`.
+
+Rules:
+
+- `TurnError.message` is built from `class`, the `code` where it adds anything,
+  and the reset time. It reaches channels, and harness stderr carries tokens and
+  env vars, so no harness output goes into it. It carries no harness name
+  either: the channel has one agent, and log lines are already tagged with it.
+- Prose matching is the last tier and is labelled `source: "text"`. A harness whose
+  `code` matches turn into `text` matches has changed a structured shape. Where a
+  harness exports its own error strings, import them rather than hardcoding.
+- Warning-level signals are not errors. Claude's approaching-limit and
+  overage-transition notices never arrive as API errors.
+
+## Error policy
+
+`TurnError.retryable` decides everything:
+
+- **`false`** — announce once in the channel, drop the batch (advancing the
+  watermark), stay alive, and reset the retry budget rather than spending it.
+  Because the batch is dropped, the notice states that the message went
+  unanswered.
+- **`true`** — re-enqueue, linear backoff, `onFatal` after `MAX_BATCH_RETRIES`. One
+  notice is posted just before exiting.
+
+It means "does the dispatcher retry this automatically", not "could a retry ever
+succeed": `usage_limit` is `false` because the notice carries the reset time and the
+human re-sends. A harness may override it per error — Cursor reports its own
+`isRetryable`, which may raise an error to retryable but never reopens
+`usage_limit` or `billing` — the SDK marks every 429 retryable, including the
+ones that mean the plan is exhausted.
+
+Notices are deduped per (channel, class) on a cooldown; fatal ones are not. The
+cooldown is a loop breaker, not just noise control: a notice is an ordinary
+channel message, so it wakes every other agent in the channel, and two agents
+failing the same way would answer each other's notices indefinitely.
+
+A failure outside a turn is not reported in-channel: a phase that fails parks the
+agent (`state: failed`) and `sendFailed` tells the backend, which is where that
+state belongs. Only a classified turn failure reaches a channel.
+
+A notice goes out through `sendAgentError`, which puts the sentence and
+`toErrorInfo(error, {fatal})` on one text body (SDK `TurnErrorInfo`). The
+console renders the structured half as a card; every older consumer — including
+other agents in the channel — reads the sentence and is unaffected. The
+projection drops `ruleId` and `source`: they say how we classified, which
+belongs in logs, not in a channel. Keep the sentence self-sufficient; nothing
+downstream may depend on the structured half being understood.
+
+Process-level survival predicates (`isTransientNetworkError` and friends) stay in
+`lifecycle.ts`. They answer "may the daemon survive this?", have no turn context,
+and never map to an `ErrorClass`.
 
 ## The agent loop is private