Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

docs(adapters): describe the call abort and the signing-value registry

Jack Rudenko46ec0486f200
diff --git a/ai-docs/architecture/adapters.md b/ai-docs/architecture/adapters.md
index 63241eeb..345aee62 100644
--- a/ai-docs/architecture/adapters.md
+++ b/ai-docs/architecture/adapters.md
@@ -818,3 +818,94 @@ Two things this uncovered:
the always-on structural log only through `isStructuralLogWorthy`, a whitelist.
Use `-d` / `--debug-claudish` (which writes `./logs/`), not `--debug` — the
latter is passed through to Claude Code and tells you nothing about the proxy.
+
+## A credential a request signed with is redacted by value in every sink (`redact.ts`)
+
+A provider can echo the key it received: in a 401 body, in an error frame of a 200 stream, in the
+message of a token-refresh exception, in an OpenRouter 429. Shape rules (`sk-…`, `Bearer …`)
+cannot recognise an opaque key, and patching each sink leaves the next `log(` call open. So the
+exact values a request signed with are held in ONE process-wide registry and applied at the few
+places text leaves claudish.
+
+**The registry.** `acquireSigningLease()` (`redact.ts:165`) returns a lease; `lease.add(values)`
+holds each value (8 characters or more) refcounted in one module-level map (`:116`), in its
+verbatim, JSON-escaped, twice-JSON-escaped and URL-encoded forms (`holdSigningValue`, `:154`);
+`release()` drops the lease's hold once. `redactSigningValues(text)` (`:197`) returns the text
+untouched when nothing is held and otherwise replaces every held form, longest first, with
+`[redacted]` by plain substring replacement (no regex, so no stateful predicate). Replacements
+only shorten, so JSON stays JSON. There is **no timer**: a lease lives until its work ends. A fixed
+TTL could expire under a stream that is still producing frames.
+
+Why one process-wide union and not a per-request `AsyncLocalStorage` scope:
+`OpenRouterRequestQueue`'s loop runs in the async context of whichever request first started it,
+so its 429 line for request B would be attributed to request A's scope. Over-redaction across
+concurrent requests is harmless; a missed value is not.
+
+**Where values come from.** Every header fetch of a request, through `ComposedHandler`'s one
+choke point `fetchHeaders` (`composed-handler.ts:1755`): `credentialValuesFromRequest` takes
+every credential-bearing header (authorization, `x-api-key`, `api-key`, `x-goog-api-key`,
+cookie values, any header whose name contains `token`, `secret` or `key`), with and without its
+scheme word, plus the endpoint's credential query parameters. That covers the primary fetch, the
+parameter re-fetch, the 401 retry's fresh token and every Responses leg. A transport that signs
+outside its headers exposes the value through `redactionSecrets?()`: Devin (the key is in the
+body) and Antigravity (its capacity fallback sends the access token itself). The advisor adds
+Claude Code's inbound bearer and `x-api-key` to the main request's lease when it reads them
+(`claudeRequestFacts`, `handlers/native-handler-advisor.ts`).
+
+**Who holds a lease, and when it is released.**
+
+| Request | Installed by | Released when |
+|---|---|---|
+| Every session-app route | `app.use("*", …)` (`proxy-server.ts:793`) sets `SIGNING_SECRETS_KEY` | the response body is fully read, cancelled (after the cancel is forwarded to the source) or errors; at once for no body (`releaseWhenBodyEnds`, `handlers/shared/call-context.ts:186`) |
+| An advisor panel call | the panel gateway (`handlers/advisor-panel-gateway.ts`) | when the call's work settles, after the body was read and redacted; a timed-out call's aborted work can still log |
+| A Claude advisor call | `runClaudeAdvisorCall`, for its own headers | when it returns (the login value is also on the main request's lease) |
+| A Context nothing installed (tests) | `signingSecretsOf` (`call-context.ts:57`) | never: retention costs redaction, never exposure |
+
+The lease belongs to the INBOUND request, never to one hop, because `FallbackHandler` logs its
+combined error after every hop has returned; and it outlives `handle()`, because a streamed body
+is parsed and logged long after the handler returned.
+
+**Every sink, and how it is covered.**
+
+| Sink | Covered by |
+|---|---|
+| `--debug` file, always-on `~/.claudish/logs/`, stderr, `DiagOutput` | `log()` and `logStderr()` call `redactSigningValues` before any write (`logger.ts:282`, `:320`); `logStructured`/`logRecovery` go through them. This covers the queue's 429 line, the parsers' frame and error lines, the auth-refresh exception and `FallbackHandler`'s stderr |
+| `CLAUDISH_UPSTREAM_ERROR_LOG`, team/pane/MCP error text | `redactSecrets` runs the registry pass before its shape rules (`redact.ts:246`) |
+| Telemetry report | `buildReport` runs it before `sanitizeMessage` (`telemetry.ts:439`, `:473`) |
+| Text sent back to Claude Code | `redactForClient` (`redact.ts:235`) at each client-body family: `ComposedHandler`'s error bodies, the Responses leg issuer, the error frames of every stream parser (`anthropic-sse`, `openai-sse`, `gemini-sse`, `ollama-jsonl`, `devin-connect`, `responses/claude-sse-sink`), `FallbackHandler`'s combined body and thrown messages, the proxy's catch and `onError` bodies |
+| An advisor result | the gateway redacts the whole body by value against the call's own set (`redactExactValues`, `redact.ts:215`) before the reason reaches records, warnings or the tool result |
+
+A new sink that writes upstream text without going through `log`, `logStderr` or
+`redactSecrets`, or a client body built from upstream text without `redactForClient`, reopens
+credential echo, and nothing errors. A refresh token the credential layer sends to a token host
+is not a signing value of the model request and is not registered; that layer formats its own
+errors through its shape redactor.
+
+## An internal call's deadline reaches every piece of upstream work (`handlers/shared/call-context.ts`)
+
+An advisor panel call has a deadline (60 s, 30 s for the collector). `Promise.race` alone would
+stop the WAITING, not the work: the chain would advance to its next hop, a queued request would
+still start, and a retry sleep would still fire, all billed. The gateway therefore installs an
+abort signal on the call's Context (`CALL_ABORT_SIGNAL_KEY`, `call-context.ts:241`), and every
+place upstream work can start or wait checks it. Main requests never install it, so
+`callAbortSignal(c)` is `undefined` and every expression below collapses to the main path's code.
+
+| Upstream work | Reach point |
+|---|---|
+| Handler entry | already aborted → `abortedResponse()` (`composed-handler.ts:1203`) |
+| Token refresh (5b), header fetch | `raceCallAbort(...)` (`:1515`, `:1762`); the shared single-flight refresh is not cancelled (unbilled), the handler stops waiting; `raceCallAbort` owns the losing promise's rejection |
+| Queued work | `doFetch` rejects with `AbortError` before calling `fetch` when the signal is aborted (`:1833`); every `enqueueRequest` call gets `{signal}` (`:1852`, `:1931`); the OpenRouter and Gemini queues drop a waiting entry on abort and reject an aborted entry before and after their rate-limit wait (`shared/openrouter-queue.ts`, `shared/gemini-queue.ts`); `LocalModelQueue` already honoured it |
+| Primary fetch and its body | the signal is composed with the deadline clamp (`withCallSignal`, `:1843`), so it still governs the body read after the clamp is disarmed; an abort returns before any connection-error classification, stderr line or recovery (`:1866`) |
+| Parameter re-fetch, 401 auth retry | pre-start check, `raceCallAbort` on the forced refresh, composed fetch signal (`:2087`, `:2189`) |
+| 7b stream-head re-issue and its backoff | `sleepUnlessAborted` ends the wait (`:3002`); the re-issue uses `doFetch` |
+| Responses legs | `AbortSignal.any([turnSignal, callSignal])` (`:2851`) |
+| Antigravity retries and capacity fallback | signal checked before each attempt and each fallback candidate, passed to the candidate `fetch`; the retry sleep is `sleepUnlessAborted` (`providers/transport/antigravity.ts:614`); the quota reads are raced, not cancelled |
+| OpenAI and anthropic-compat retry waits | `sleepUnlessAborted(delay, opts.signal)` (`providers/transport/openai.ts:149`, `anthropic-compat.ts:203`) |
+| Routing chain advancement | `FallbackHandler` checks at the top of each iteration, right after `handle()` returns (returning that response before `isRetryableError` or any `[Fallback] … failed` line), and in its catch (`fallback-handler.ts:71`, `:90`, `:241`) |
+
+`abortedResponse()` (`call-context.ts:332`) is HTTP 408, error type `timeout_error`, header
+`x-claudish-call-aborted: 1`. Nothing classifies it by status, it writes nothing to stderr, and
+main requests never produce it. Accepted residuals: the 7c Devin re-issue's backoff sleep can
+outlive the deadline by one delay (no upstream work starts after it), and the tier-1 recovery
+re-issue is not given the signal, because advisor calls skip tier 1
+(`x-claudish-no-recovery: advisor`) and the primary catch returns on abort before recovery.