@loomcycle/client 1.112.0 → 1.114.0

package/README.md

@@ -141,7 +141,7 @@ The low-level primitives (`runStreaming({interactive:true})` + `sendRunInput` +
 | `getAgent(agentId)` | `Promise<Agent>` | One agent's status + usage. Raises `AgentNotFoundError` if unknown. |
 | `getRun(runId)` | `Promise<Agent>` | One run by its run id — `getAgent`'s shape. Use it when an agent id names several runs (every walk of a team is `team:<name>`). Raises `NotFoundError` if unknown. |
 | `cancelAgent(agentId, opts?)` | `Promise<{ cancelledCount: number }>` | Cascades to children via `parent_agent_id`. Idempotent. |
-| `listUserAgents(userId, opts?)` | `Promise<Agent[]>` | Optional filter by status (`running` / `completed` / `failed` / `cancelled`). |
+| `listUserAgents(userId, opts?)` | `Promise<AgentList>` | Up to 100 runs. `status`: one status or an array (a run in any of them; omitted = running, `"all"` = every status). `awaitedState`: one or more of `channel` / `interrupted` / `review` / `input` / `children` — only running runs blocked on one of those waits; the server reads at most 1,000 running runs and the returned array carries `truncated: true` when it left some unread. An unknown value is a 400. `AgentList` is an `Agent[]`. |
 | `listWalkRuns(walkId, { limit?, cursor? })` | `Promise<WalkRunsPage>` | One page of a team walk's runs — its own run and every member, oldest first: `{ agents, next_cursor }`. Pass `next_cursor` back as `cursor`; `""` on the last page. `limit` defaults to 100, at most 1000. Raises `NotFoundError` for a walk you cannot read. |
 | `listChildRuns(parentRunId, { limit?, cursor? })` | `Promise<WalkRunsPage>` | One page of a run's direct children (the runs it started itself), of every status, oldest first, paged like `listWalkRuns`. Not the run itself, and not its grandchildren. Raises `NotFoundError` for a run you cannot read. |
 | `deleteRunTree(runId)` | `Promise<RunTreeDeletion>` | Permanently delete a run and every run it spawned, with what is stored about them. The usage ledger is kept. Needs the `runs:delete` scope. Returns `{ deleted_runs, counts, kept, not_reached }`; an unknown, already deleted or unreadable run returns `deleted_runs: 0` instead of raising. A tree with a live or paused run deletes nothing and raises with `code: "run_tree_live"`. |
@@ -190,6 +190,44 @@ console.log(`restored memory rows: ${result.memory_restored}`);
 | `listMemoryEntries(scope, scopeID, opts?)` | `Promise<MemoryEntriesResponse>` | Optional `prefix` + `limit`. |
 | `getMemoryEntry(scope, scopeID, key)` | `Promise<MemoryEntryResponse>` | Single row read. |
 
+### Memory / document change feeds (RFC CD Part C)
+
+Live SSE tails of what changed in the caller's tenant's memory and documents — for a cache, an index, or a console that reacts to writes without polling.
+
+| Method | Returns | Notes |
+|---|---|---|
+| `streamMemoryChanges(opts?)` | `AsyncIterable<ChangeFeedFrame>` | `memory.set` / `memory.delete` / `memory.scope_deleted`. Mirrors `GET /v1/_memory/changes`. |
+| `streamDocumentChanges(opts?)` | `AsyncIterable<ChangeFeedFrame>` | `document.chunk.updated` / `document.chunk.deleted`, naming the `chunk_id`. Mirrors `GET /v1/_document/changes`. |
+
+Each change is a **value-free coordinate** (`seq`, `type`, `scope`, `scope_id`, `key` or `chunk_id`, `at`): it says *what* changed, and you pull the current value through the data API. The first item is always `{ kind: "feed", payload: { enabled, since, embedder? } }`, then one `{ kind: "change", payload: MemoryChange }` per change, oldest first.
+
+- **Off by default.** The server only records changes with `LOOMCYCLE_MEMORY_CHANGES_ENABLED`. Without it the stream opens and idles forever, so check `payload.enabled` on the feed frame rather than waiting.
+- **Tenant-scoped, operator-only.** You see your own tenant's changes, never another's. The routes need `substrate:tenant` (or admin); a tenant member's token gets a 403 (`LoomcycleError`, `status: 403`).
+- **Resumable.** Persist the last `seq` you processed and pass it back as `since` on reconnect; delivery is strictly after it. `since` must be a non-negative integer — the client throws otherwise, because the server would read a bad value as `0` and replay everything it retains.
+- **Read failures are reported, not fatal.** A `{ kind: "error", payload: { code, error } }` item (`code: "store_unavailable"`) means the server could not read its change log. Keep iterating: the server retries with backoff without advancing its cursor, so changes resume after recovery with nothing skipped. You get one item per failure streak.
+- **The embedder's health rides along.** An embedding failure does not fail the write, so a busy feed can sit over rows that are no longer searchable; `payload.embedder.state === "failing"` (with a `failures` count) is the signal to run `backfillEmbeddings`.
+
+```ts
+let since = await loadCursor(); // your own persistence
+const ac = new AbortController();
+
+for await (const item of client.streamMemoryChanges({ since, signal: ac.signal })) {
+  if (item.kind === "feed") {
+    if (!item.payload.enabled) throw new Error("change feed is off on this server");
+    continue;
+  }
+  if (item.kind === "error") {
+    console.warn(`change feed: ${item.payload.code}: ${item.payload.error}`); // stream continues
+    continue;
+  }
+  const ch = item.payload; // { seq, type, scope, scope_id, key?, at }
+  await invalidate(ch.scope, ch.scope_id, ch.key);
+  since = ch.seq;
+  await saveCursor(since);
+}
+// The loop ends when the server closes the stream (e.g. a restart): reconnect with `since`.
+```
+
 ### Interruption (v0.8.16)
 
 | Method | Returns | Notes |
@@ -202,9 +240,12 @@ console.log(`restored memory rows: ${result.memory_restored}`);
 
 | Method | Returns | Notes |
 |---|---|---|
-| `hookDef(input)` | `Promise<SubstrateToolResponse>` | Reusable hook definitions (create / fork / get / list / promote / retire / verify / delete). An agent attaches hooks in its own definition (`tools` entries `{name, hooks}` and `hooks`). |
+| `hookDef(input)` | `Promise<SubstrateToolResponse>` | Reusable hook definitions (create / fork / get / list / promote / retire / verify / delete). An agent attaches hooks in its own definition (`tools` entries `{name, hooks}` and `hooks`). `input` is a `HookDefInput` or the loose `SubstrateToolInput` — see [Typed HookDef / ScheduleDef / WebhookDef inputs](#typed-hookdef--scheduledef--webhookdef-inputs-rfc-eo). |
+| `createHookDef(name, overlay, opts?)` | `Promise<HookDefRowResponse>` | `op: "create"` with a strictly-typed `HookDefOverlay` — a misspelt key is a compile error even in a bare literal. Promoted unless `promote: false`. |
+| `forkHookDef(name, overlay, opts?)` | `Promise<HookDefRowResponse>` | `op: "fork"` with a `HookDefForkOverlay` (partial; `null` clears a field). `opts.parentDefId` picks the parent (default: the active version). Not promoted unless `promote: true`. |
+| `ensureHookDef(name, overlay, opts?)` | `Promise<EnsureHookDefResult>` | Idempotent register-if-changed for a `HookDefOverlay` — safe to call on every boot. `changed: false` when the active version already carries the same definition. |
 
-A hook is attached in the agent's definition — a tool entry `{name, hooks}` or the agent's own `hooks` — and loomcycle posts to its URL during the agent's runs. The other side is the **callback receiver**, a small HTTP endpoint your app runs at that URL. The adapter exports the wire shapes (`PreHookCall` / `PostHookCall` / `PreHookResult` / `PostHookResult`) so you can type the handler against the same JSON loomcycle posts.
+A **HookDef** is a stored, versioned hook definition in your tenant: the event it answers, the tools it matches, its body (a `code-js` script run in-process, or a webhook URL), its fail mode and timeout. It fires on nothing by itself. An agent definition, a team definition or a run attaches it by name — in a tool entry `{name, hooks}` or the agent's own `hooks` — as `"scan"` (the active version) or `"scan@3"` (pinned). A hook can also be written inline as a webhook `{name, url, …}` in the definition that attaches it. For a webhook body, loomcycle posts to its URL during the agent's runs. The other side is the **callback receiver**, a small HTTP endpoint your app runs at that URL. The adapter exports the wire shapes (`PreHookCall` / `PostHookCall` / `PreHookResult` / `PostHookResult`) so you can type the handler against the same JSON loomcycle posts.
 
 **Attach it in the agent's definition:**
 
@@ -265,13 +306,98 @@ export async function POST(req: Request) {
 }
 ```
 
+**Verify a signed delivery.** A HookDef whose webhook body names a `signing_secret` (a credential, `"$cred:<name>"`) signs every call: `X-Loomcycle-Signature: t=<unix>,v1=<hex HMAC-SHA256 of t + "." + raw body>`. **Only the body is signed.** It carries `delivery_id` (a retry keeps it), `hook_name` and `owner`; the `X-Loomcycle-Delivery` and `X-Loomcycle-Hook` headers are unsigned copies a replayer can change, so dedupe and identify the hook from the verified body, never from them. Verify against the **raw** body, before parsing it:
+
+```ts
+import { verifyLoomcycleDelivery } from "@loomcycle/client";
+import type { PreHookCall } from "@loomcycle/client";
+
+export async function POST(req: Request) {
+  const raw = await req.text(); // the exact bytes; JSON.stringify(await req.json()) will not match
+  const d = await verifyLoomcycleDelivery<PreHookCall>(raw, req.headers.get("x-loomcycle-signature") ?? "", process.env.HOOK_SIGNING_SECRET!);
+  if (!d) return new Response(null, { status: 401 });
+  if (await seen(d.deliveryId)) return Response.json(previousAnswer(d.deliveryId)); // keep ids ≥ 300 s
+  // d.hookName / d.owner say which hook sent it; d.body is the payload.
+}
+```
+
+`verifyLoomcycleDelivery(rawBody, header, secret, opts)` resolves the body's `{deliveryId, hookName, owner, body}`, or `null` when the signature fails or the body has no `delivery_id`/`hook_name`. `verifyLoomcycleSignature(rawBody, header, secret, { toleranceSec = 300, now?, subtle? })` is the bare check: `true` only for a signature made within the tolerance; every malformed header, stale or future `t`, or wrong MAC is `false`. Both use Web Crypto (`crypto.subtle`), so they run in Node 19+, browsers and edge runtimes; on Node 18 pass `subtle: require("node:crypto").webcrypto.subtle`. Give each receiver its own signing secret, so a delivery captured at one cannot be replayed to another.
+
 **Important constraints**:
 
-- Hook registrations are **in-memory** on the loomcycle server. Re-register on every app startup; the `(owner, name)` idempotency contract makes this safe (replaces in place).
-- Auth flows one-way: loomcycle → your callback URL. Loomcycle does NOT attach a bearer token to callback POSTs by default. If you need to authenticate the caller, validate by source IP or include a shared secret in the `callback_url` path/query (`https://jobember.example/hooks/scan?secret=...`).
+- HookDefs are **stored and versioned**, not in-memory: they survive restarts, and every `create` mints a new version (the active one is what a by-name reference runs). To register from app startup without piling up versions, use `ensureHookDef`, which writes only when the definition changed. `fork` + `promote` (or `forkHookDef(…, {promote: true})`) derives a version from an existing one.
+- Auth flows one-way: loomcycle → your receiver. Loomcycle attaches no credential of its own. To authenticate the caller, send a secret in the hook's `headers` as `$cred:<name>` (a stored credential, resolved for the run when the hook is called) rather than in the URL.
 - `fail_mode: "open"` (default) is right for telemetry hooks where a down receiver shouldn't break tool dispatch. `"closed"` is right for security hooks where a down receiver should fail the tool call (don't let bypassed payloads through).
 - `allow_hosts` in `PreHookResult` is a **trust-sensitive surface** — it widens the agent's outbound network policy for one tool call. Server enforces an operator-yaml allowlist (`hooks.permit_host_widen.owners`); your owner has to be on that list for `allow_hosts` to take effect. See the SECURITY note in `internal/hooks/types.go` before using.
 
+### Typed HookDef / ScheduleDef / WebhookDef inputs (RFC EO)
+
+**For checked keys, use the create / fork methods.** They take only the typed overlay, so a bare object literal is checked against it:
+
+| Method | Returns | Notes |
+|---|---|---|
+| `createHookDef(name, overlay, opts?)` / `forkHookDef(name, overlay, opts?)` | `Promise<HookDefRowResponse>` | See [Hook management](#hook-management-v0818). Any unknown key is a compile error. |
+| `createScheduleDef(name, overlay, opts?)` / `forkScheduleDef(name, overlay, opts?)` | `Promise<ScheduleDefRowResponse>` | Both promoted unless `promote: false`; a fork defaults to the active version, or the yaml template of `name`. |
+| `createWebhookDef(name, overlay, opts?)` / `forkWebhookDef(name, overlay, opts?)` | `Promise<WebhookDefRowResponse>` | Same defaults as the schedule pair. |
+
+`opts` is `{description?, promote?, signal?}`, plus `parentDefId?` on a fork. `promote` is sent only when you set it, so each def's own default applies otherwise.
+
+The op-discriminated methods keep working as before. `hookDef`, `scheduleDef` and `webhookDef` accept a typed per-op input — `HookDefInput`, `ScheduleDefInput`, `WebhookDefInput` — or the loose `SubstrateToolInput` they always took, so existing calls compile unchanged. There the checking is opt-in: annotate the input (or use `satisfies`). A bare object literal with a misspelt key still compiles, because it matches the loose shape.
+
+| Method | Returns | Notes |
+|---|---|---|
+| `scheduleDef(input)` | `Promise<SubstrateToolResponse>` | Scheduled-run definitions (create / fork / get / list / retire / add_hook / remove_hook). Mirrors `POST /v1/_scheduledef`. `add_hook` / `remove_hook` are expressible only through `ScheduleDefInput`. |
+| `webhookDef(input)` | `Promise<SubstrateToolResponse>` | Inbound webhook definitions (create / fork / get / list / retire). Mirrors `POST /v1/_webhookdef`. |
+
+- **`HookDefOverlay` is closed.** The server decodes a HookDef overlay strictly and refuses an unknown key, so the type has no index signature: a misspelt key is a compile error. `body` is a union on `kind` — `{kind: "code-js", code}` or `{kind: "http", url, headers?}` — because the server refuses a body that mixes them. A fork takes `HookDefForkOverlay`: every field optional, and `null` clears one.
+- **`ScheduleDefOverlay` and `WebhookDefOverlay` stay open** (`[extra: string]: unknown`): the server decodes them loosely and drops keys it does not know. So even through `createScheduleDef` / `createWebhookDef`, a misspelt key compiles. What fails is a wrong type or value on a declared key, such as `concurrency_policy: "skip"`, `delivery: "run"` on a webhook, or an `mcp.call` hook without `tool`. They leave out the fields the server stamps itself (`operator_key_restricted`, `isolated`, `capture_disabled`, and on schedules `operator_layer`) — an overlay can neither set nor clear those.
+- `on_complete` entries on both are a `ScheduledRunHook`: `channel.publish` (`channel`), `mcp.call` (`server` + `tool`) or `memory.set` (`scope` + `key`).
+
+```ts
+await client.createHookDef("scan-webfetch", {
+  event: "post",
+  match: { tools: ["WebFetch"] },
+  body: { kind: "http", url: "https://jobember.example/hooks/scan", headers: { Authorization: "$cred:scan" } },
+  fail_mode: "open",
+  timeout_ms: 3000,
+});
+
+await client.createScheduleDef("weekly-digest", {
+  agent: "digest",
+  schedule: "0 6 * * 1",
+  timezone: "Europe/Berlin",
+  prompt: [{ role: "user", content: [{ type: "trusted-text", text: "Write this week's digest." }] }],
+  on_complete: [{ kind: "channel.publish", channel: "digests" }],
+});
+
+await client.createWebhookDef("gh-push", {
+  delivery: "spawn",
+  agent: "ingest",
+  auth: { kind: "hmac", algorithm: "sha256", header: "X-Hub-Signature-256", signing_secret_env: "LOOMCYCLE_GH_WEBHOOK_SECRET" },
+  payload_mapping: { goal: "$.head_commit.message" },
+});
+
+// The op-discriminated form, checked by annotation:
+import type { ScheduleDefInput } from "@loomcycle/client";
+const addHook: ScheduleDefInput = {
+  op: "add_hook",
+  def_id: "sdf_…",
+  hook: { kind: "memory.set", scope: "user", key: "last_digest" },
+};
+await client.scheduleDef(addHook);
+```
+
+**Register a HookDef on every boot** with `ensureHookDef`. A HookDef `create` always mints a new version, so this reads the active version first and compares its stored definition with yours, normalized the way the server stores it (`fail_mode` defaults to `"open"`; empty `match.tools`, description, headers and timeout are dropped). Equal → no write. A difference it cannot see through mints a redundant version rather than skipping a real change; `opts.description` is a rationale, not part of the definition, and does not count as a change.
+
+```ts
+const r = await client.ensureHookDef("scan-webfetch", {
+  event: "post",
+  match: { tools: ["WebFetch"] },
+  body: { kind: "http", url: "https://jobember.example/hooks/scan" },
+});
+console.log(r.changed ? `registered v${r.version}` : "already current");
+```
+
 ### Substrate admin: AgentDef + SkillDef (v0.8.22)
 
 Two op-discriminated methods that mirror the in-process `AgentDef` / `SkillDef` built-in tools over HTTP. The same `op` values an agent's tool_use would invoke are reachable directly from your app code — useful for runtime fork / promote / retire / list, and for the `verify` op covered in [Content signatures](#content-signatures-v09x).
@@ -280,6 +406,7 @@ Two op-discriminated methods that mirror the in-process `AgentDef` / `SkillDef`
 |---|---|---|
 | `agentDef(input)` | `Promise<SubstrateToolResponse>` | Op-discriminated. Mirrors `POST /v1/_agentdef`. |
 | `skillDef(input)` | `Promise<SubstrateToolResponse>` | Op-discriminated. Mirrors `POST /v1/_skilldef`. |
+| `getAgentOverridable(name, { tenant? })` | `Promise<AgentOverridableResponse>` | Which per-run overrides a run of `name` may set, **for this caller**: one entry per override (`model`, `effort`, `max_tokens`, …) with `overridable`, and a `reason` (`token_locked` / `agent_locked`) when refused. Folds the agent's `allow_overrides` with your token's overrides policy, as a run would. An overridable field may carry `narrow_only`, `max`, or `values` (a closed set the definition declares). For building run forms. `substrate:tenant`; a token limited to certain agents may ask about those. Raises `AgentNotFoundError` for an unknown or another tenant's agent. Mirrors `GET /v1/_agentdef/{name}/overridable`. |
 
 The response type is intentionally `unknown` because the shape varies per op (`create`/`fork` return a row envelope; `list` returns `{name, versions: [...]}`; `verify` returns `AgentDefVerifyResult` / `SkillDefVerifyResult`). Cast / narrow as needed:
 
@@ -326,6 +453,60 @@ const { entries } = await client.listVolumes();
 
 Refusals throw `SubstrateToolRefusedError` (collision with a static volume name, no `dynamic_root` configured, cross-tenant); transport failures throw the usual typed errors.
 
+### Schedules admin
+
+The schedules surface the Web UI drives: one merged list, a schedule's runtime state, and run-now / pause / resume. Authoring stays on `scheduleDef(input)`. Tenant-confined: a `substrate:tenant` token sees and acts on its own tenant's ScheduleDefs only, and another tenant's `def_id` answers 404 like an unknown one.
+
+| Method | Returns | Notes |
+|---|---|---|
+| `listAllSchedules(opts?)` | `Promise<ScheduleListResponse>` | Static yaml `scheduled_runs` + ScheduleDefs, merged by name. Statics appear for an admin only; `opts.tenant` focuses one tenant. `GET /v1/_schedules/list-all`. |
+| `getScheduleState(defId)` | `Promise<ScheduleStateView>` | Last/next fire, pause, last slot claim, catch-up backlog, runs in flight. `GET /v1/_schedules/{def_id}/state`. |
+| `runScheduleNow(defId)` | `Promise<ScheduleRunNowResult>` | Fires on the scheduler's next tick; the cadence continues after it. `POST .../run-now`. |
+| `pauseSchedule(defId)` | `Promise<SchedulePauseResult>` | Indefinite (no duration). `POST .../pause`. |
+| `resumeSchedule(defId)` | `Promise<SchedulePauseResult>` | `POST .../resume`. |
+
+The per-schedule methods take the ScheduleDef's `active_def_id` from the list; a static-only schedule has none. Every optional instant in `ScheduleStateView` (`last_run_at`, `paused_until`, `slot_at`, `catch_up_until`, …) is **absent** when unset — test for presence. (Servers before this release sent `last_run_at` and `paused_until` as `"0001-01-01T00:00:00Z"`.)
+
+```ts
+const { entries } = await client.listAllSchedules();
+for (const e of entries.filter((e) => e.active_def_id)) {
+  const st = await client.getScheduleState(e.active_def_id!);
+  if (st.paused_until) console.log(`${e.name} is paused`);
+}
+```
+
+### Models, routing + provider models
+
+| Method | Returns | Notes |
+|---|---|---|
+| `listModels()` | `Promise<ModelAliasesResponse>` | The configured model aliases (`models:`), alias → `{provider, model, kind?}`. Tenant-readable. `GET /v1/_models`. |
+| `getRouting()` | `Promise<RoutingResponse>` | Per user tier × tier, the ordered provider/model cascade with live availability and the `selected` candidate. Tenant-readable; a non-admin gets no raw `last_error`, and under the operator-key gate only providers it can key. `GET /v1/_routing`. |
+| `listProviderModels(providerId)` | `Promise<ProviderModelsResponse>` | A live listing from the provider. **Admin token only** — a tenant token gets a 403 `LoomcycleError`; fall back to `listModels()` plus free-text entry. `GET /v1/_providers/{id}/models`. |
+
+Store an alias from `listModels()` on an agent or fork rather than the model it names: the agent then follows the operator's retarget of the alias.
+
+### Def name listings
+
+One method per substrate family returns every declared name with its version roll-up (`version_count`, `active_def_id`, `latest_version`, `last_updated`) — what a family's `list` op cannot, since it lists the versions of one name. Tenant-scoped server-side; `opts.tenant` focuses one tenant for an admin and is ignored for a tenant token. `names` is `[]` when nothing is declared.
+
+| Method | Route |
+|---|---|
+| `listAgentDefNames(opts?)` | `GET /v1/_agentdef/names` |
+| `listSkillDefNames(opts?)` | `GET /v1/_skilldef/names` |
+| `listHookDefNames(opts?)` | `GET /v1/_hookdef/names` |
+| `listMcpServerDefNames(opts?)` | `GET /v1/_mcpserverdef/names` |
+| `listScheduleDefNames(opts?)` | `GET /v1/_scheduledef/names` |
+| `listA2AServerCardDefNames(opts?)` | `GET /v1/_a2aservercarddef/names` |
+| `listA2AAgentDefNames(opts?)` | `GET /v1/_a2aagentdef/names` |
+| `listWebhookDefNames(opts?)` | `GET /v1/_webhookdef/names` |
+| `listMemoryBackendDefNames(opts?)` | `GET /v1/_memorybackenddef/names` |
+| `listDocumentSourceDefNames(opts?)` | `GET /v1/_documentsourcedef/names` |
+| `listOperatorTokenDefNames(opts?)` | `GET /v1/_operatortokendef/names` — **admin token only**; `{name, tenant_id, subject, token_count, has_current, last_updated}`, never a token. |
+
+All but the last return `DefNamesResponse`; `live_version_count` / `active_retired` are reported by the AgentDef, SkillDef, HookDef and MCPServerDef families. Teams have `listTeams()`.
+
+Team options ride on existing methods: `createTeam(name, overlay, { promote, description })` sends the create's own fields (omitted, a create is promoted — the server default; `promote: false` authors it without putting it in force), `forkTeam(name, overlay, { promote, parentDefId, description })` sends the fork's (omitted, the fork is authored but not active — the server default for a fork), and `runTeam({ ..., interruptOnCap: true })` asks a human whether to continue, reroute or abort when a state hits its iteration cap, instead of ending with `iteration_cap`.
+
 ### Decision models
 
 Ask a **decision model** typed questions about a piece of text and get each answer with its probabilities. A decision model does not write: it reads the `state` you give it and answers a choice, a yes/no or a score, so there is no reply to parse and a call costs a few output tokens. Use it to route, gate, rank or grade text you already have. No run is involved; the tokens are charged to the caller and count against its token budget.
@@ -380,10 +561,10 @@ A refusal throws with the decision's own code on `e.code` (see [Errors](#errors)
 | 400 | `model_not_allowed` | Omit `model`, or use a name from `listDecisionModels()`. |
 | 403 | `operator_key_restricted` | The caller may not use the operator's provider key and has none of its own. Do not retry. |
 | 413 | `prompt_too_large` | The request does not fit the model's context and is never shortened for you: shorten `state` or ask fewer questions. |
-| 429 | `token_limit_exceeded` | The caller is at a hard token budget. Retrying does not help until the budget is raised or the month rolls over. |
-| 502 | `model_not_found` / `call_failed` | The provider does not serve that model (the same call fails again) / the call did not complete (try once more). |
+| 429 | `token_limit_exceeded` | The caller is at a hard token budget (`TokenLimitExceededError`, `retryable` false). Retrying does not help until the budget is raised or the month rolls over. |
+| 502 | `model_not_found` / `call_failed` | The provider does not serve that model (the same call fails again) / the call did not complete (try once more; `retryable` is true). |
 | 503 | `decision_not_configured` | This deployment declares no decision models. Do not retry. |
-| 504 | `timeout` | Send the same call again; if it repeats, make it smaller. |
+| 504 | `timeout` | Send the same call again (`retryable` is true); if it repeats, make it smaller. |
 
 ```ts
 try {
@@ -397,6 +578,64 @@ try {
 
 Two of these have a class of their own: a `prompt_too_large` throws `PromptTooLargeError` and a `token_limit_exceeded` throws `TokenLimitExceededError` (with the budget on `e.scope` / `e.used` / `e.limit`). For the rest, branch on `e.code`, not on the class: the class follows the HTTP status alone.
 
+### Credentials (RFC AR)
+
+The encrypted credential store an agent's `$cred:<name>` references resolve against. `scope` is `user` (your own subject's credentials) or `tenant` (shared across the tenant; needs `substrate:tenant`). Every read is metadata only — a stored value is never returned.
+
+| Method | Returns | Notes |
+|---|---|---|
+| `listCredentials(scope)` | `Promise<CredentialListResponse>` | Every credential's metadata in the scope. `{op: "list"}`. |
+| `getCredential({ scope, name })` | `Promise<CredentialMeta>` | One credential's metadata: `backend`, `created_at` / `updated_at`, and `expires_at` / `allowed_urls` / `username` when set. Raises `SubstrateToolRefusedError` for an absent name. `{op: "get"}`. |
+| `createCredential({ scope, name, value, allowed_urls?, username?, expires_at?, backend? })` | `Promise<CredentialMeta>` | Store or rotate. `value` is write-only. `expires_at` is RFC3339; `backend` is `"inline"`, the only one accepted. `{op: "create"}`. |
+| `deleteCredential({ scope, name })` | `Promise<{ name, scope, deleted }>` | Anything referencing `$cred:<name>` at that scope stops resolving. `{op: "delete"}`. |
+
+All four post to `POST /v1/_credentialdef`.
+
+```ts
+const meta = await client.getCredential({ scope: "user", name: "GIT_TOKEN" });
+console.log(meta.allowed_urls ?? "unrestricted");
+```
+
+### Evaluations
+
+Scores attached to runs: record a verdict on a run, read the scores back, and roll them up per definition version to compare versions. All of these post to `POST /v1/_evaluation`; `evaluation(input)` takes the op-discriminated input directly and its return type follows `op`.
+
+| Method | Returns | Notes |
+|---|---|---|
+| `submitEvaluation(runId, score, { dimensions?, judgement?, rationale? })` | `Promise<EvaluationSubmitResult>` | Additive: submitting again records another evaluation. `{op: "submit"}`. |
+| `getEvaluation(evalId)` | `Promise<EvaluationRecord>` | `{op: "get"}`. |
+| `listEvaluationsForRun(runId, { limit? })` | `Promise<EvaluationListForRunResult>` | `{op: "list_for_run"}`. |
+| `listEvaluationsForDef(defId, { limit? })` | `Promise<EvaluationListForDefResult>` | Your tenant's scores of that definition version. `{op: "list_for_def"}`. |
+| `aggregateEvaluations(defId, { includeLineage? })` | `Promise<EvaluationAggregate>` | Mean / median / min / max / latest, per dimension and per emitter role. `{op: "aggregate"}`. |
+
+What a token may do: `substrate:tenant` every op inside its own tenant; admin every op in every tenant; any other token (an isolated `substrate:user`, a tenant member) only `submit_self`, which a call from outside a run cannot use, so each op is refused with `SubstrateToolRefusedError`. A token without `runs:read` gets a 403. Another tenant's evaluation or run reads exactly like one that does not exist.
+
+```ts
+await client.submitEvaluation(runId, 0.8, { rationale: "correct, but slow" });
+const agg = await client.aggregateEvaluations(defId);
+console.log(agg.count, agg.score.mean);
+```
+
+### Team runs
+
+`runTeam(target)` walks a team's state graph. Its return type follows `target.mode`:
+
+| Call | Returns |
+|---|---|
+| `runTeam({ name, input, mode: "detach" })` | `Promise<TeamRunDetached>` — the `run_id` at once; the walk keeps running. |
+| `runTeam({ name, input })` | `Promise<TeamRunResult>` — waits for the walk; `steps` is the per-state trace. |
+| `runTeam(target: TeamRunTarget)` | `Promise<TeamRunResult \| TeamRunDetached>` — for a target whose `mode` is not known statically (built from a form or a node parameter). Narrow by the `mode` you sent. |
+
+A start with an `idempotencyKey` another start already holds is answered with that walk, marked `deduplicated: true`, and carries no `steps` — the trace is not stored on the run. Once that walk has ended it also has `final_output`, and `final_state` / `stop_reason` / `error` where they were recorded.
+
+```ts
+import type { TeamRunTarget } from "@loomcycle/client";
+
+const target: TeamRunTarget = { name: "triage", input, mode: detach ? "detach" : undefined };
+const res = await client.runTeam(target);
+console.log(res.run_id);
+```
+
 ### Channels + run-state stream (v0.9.x n8n Phase 0)
 
 Two substrate-side surfaces added in the n8n integration's Phase 0 wire-API work. Useful for any orchestrator (not just n8n) that needs to see channel state or subscribe to run-state transitions.
@@ -538,9 +777,10 @@ When the error body is JSON with a string `code` (`token_limit_exceeded`, `per_u
 |---|---|
 | 400 | `InvalidArgumentError` |
 | 401 | `AuthError` |
+| 403 + code `insufficient_scope` | `InsufficientScopeError` (not retryable; `e.requiredScope` names the scope the token lacks — from the body's `required_scope`, or from `WWW-Authenticate` on an older server that sent plain text) |
+| 403 (other) | `LoomcycleError` (base; e.g. `restricted_token`, `operator_key_restricted` on `e.code`) |
 | 404 + "snapshot" | `SnapshotNotFoundError` ⎫ |
 | 404 + "session" | `SessionNotFoundError` ⎬ all extend `NotFoundError` |
-| 404 + "hook" | `HookNotFoundError` ⎬ |
 | 404 + "agent" | `AgentNotFoundError` ⎬ |
 | 404 (other) | `NotFoundError` (base) ⎭ catch any 404 with one `instanceof` |
 | 409 + "already_pausing" / "already paused" | `AlreadyPausingError` |
@@ -552,39 +792,55 @@ When the error body is JSON with a string `code` (`token_limit_exceeded`, `per_u
 | 413 + code `prompt_too_large` | `PromptTooLargeError` ⎬ all are `instanceof SnapshotTooLargeError` (back-compat) |
 | 413 (other) | `RequestTooLargeError` ⎭ |
 | 422 | `SnapshotVersionError` |
-| 429 + code `per_user_quota_exhausted` | `PerUserQuotaExhaustedError` |
-| 429 + code `token_limit_exceeded` | `TokenLimitExceededError` (subclass of `BackpressureError` — back-compat) |
-| 429 (other) | `BackpressureError` |
+| 429 + code `per_user_quota_exhausted` | `PerUserQuotaExhaustedError` (retryable; `e.retryAfterMs` from `Retry-After`) |
+| 429 + code `token_limit_exceeded` | `TokenLimitExceededError` (NOT a `BackpressureError`; not retryable) |
+| 429 + code `rate_limited` | `RateLimitedError` (subclass of `BackpressureError`; retryable; `e.retryAfterMs` from `Retry-After`) |
+| 429 + code `configured_run_cap` | `BackpressureError` (NOT retryable: start or discard a configured run first) |
+| 429 (other) | `BackpressureError` (retryable) |
 | 503 + "pause manager not configured" | `PauseNotConfiguredError` (subclass of `UnavailableError` — back-compat) |
 | 503 (other) | `UnavailableError` |
 | 500 / other | `LoomcycleError` (base) |
 
-**429: a token budget is not backpressure.** A plain `BackpressureError` is transient: the server is busy, back off and retry. `TokenLimitExceededError` is not: the caller is at a hard token budget (run creation and `decide()` both refuse with it), and the same call is refused until the budget is raised or the calendar month rolls over. It extends `BackpressureError` only so that an existing `instanceof BackpressureError` keeps catching it, so test for it first. The client never retries on its own; this matters to your retry loop.
+**`e.retryable`: can the same call succeed later?** Every error carries a read-only `retryable`. It is `true` only for a refusal that clears on its own: a `BackpressureError` (the server or a provider queue is busy), a `RateLimitedError` (the caller is starting runs faster than its run-start rate allows), a `PerUserQuotaExhaustedError` (the caller's own in-flight runs are at their cap), a 503 `UnavailableError` with code `runtime_paused` (the operator has paused the runtime), and a `decide()` call that failed (502 `call_failed`) or timed out (504 `timeout`). It is `false` for everything else, a hard token budget included, and so is a `BackpressureError` with code `configured_run_cap`: the user already holds as many configured runs as allowed, and waiting never makes room — start or discard one first. A 503 is shared between a paused runtime and features the deployment does not have (`decision_not_configured`, `store_unavailable`, …), and many 503 bodies carry no code, so only `runtime_paused` counts; a code-less 503 from run creation can also be a model tier with no provider available, which you may retry on your own judgement. The default is `false` because a wrong `true` turns a refusal that never clears into an endless loop. The client never retries on its own, so bound your loop even when `retryable` is true, and prefer `e.retryAfterMs` where the class has it.
+
+**429: a token budget is not backpressure.** A `BackpressureError` is transient: back off and retry. `TokenLimitExceededError` is not: the caller is at a hard token budget (run creation and `decide()` both refuse with it), and the same call is refused until the budget is raised or the calendar month rolls over. **It is no longer a `BackpressureError`** (it was, through 1.112.x). It extended that class so that an older `instanceof BackpressureError` check kept catching it, but such a check is nearly always a retry loop, which then retried the refusal for the rest of the month; that relation was dropped on purpose. If your code caught the budget through `instanceof BackpressureError`, catch `TokenLimitExceededError` (or test `e.code === "token_limit_exceeded"`) instead.
 
 ```ts
-import { BackpressureError, TokenLimitExceededError } from "@loomcycle/client";
+import {
+  LoomcycleError,
+  PerUserQuotaExhaustedError,
+  RateLimitedError,
+  TokenLimitExceededError,
+} from "@loomcycle/client";
 
-try {
-  for await (const ev of client.runStreaming({ /* ... */ })) {}
-} catch (e) {
-  if (e instanceof TokenLimitExceededError) {
-    // Not retryable now. e.scope is "operator" | "tenant" | "user"; e.scopeId is
-    // the tenant or user (null for the operator-wide budget); e.used and e.limit
-    // are tokens; e.window is "month". Each is null if the server did not send it.
-    console.error(`token budget reached for ${e.scope}: ${e.used}/${e.limit} this ${e.window}`);
-  } else if (e instanceof BackpressureError) {
-    // Transient: back off and retry.
-  } else {
-    throw e;
+for (let attempt = 0; ; attempt++) {
+  try {
+    for await (const ev of client.runStreaming({ /* ... */ })) {}
+    break;
+  } catch (e) {
+    if (e instanceof TokenLimitExceededError) {
+      // Not retryable. e.scope is "operator" | "tenant" | "user"; e.scopeId is
+      // the tenant or user (null for the operator-wide budget); e.used and e.limit
+      // are tokens; e.window is "month". Each is null if the server did not send it.
+      console.error(`token budget reached for ${e.scope}: ${e.used}/${e.limit} this ${e.window}`);
+      throw e;
+    }
+    if (!(e instanceof LoomcycleError) || !e.retryable || attempt >= 5) throw e;
+    // These two carry the server's own hint; otherwise back off exponentially.
+    const hint =
+      e instanceof RateLimitedError || e instanceof PerUserQuotaExhaustedError
+        ? e.retryAfterMs
+        : null;
+    await new Promise((r) => setTimeout(r, hint ?? 1000 * 2 ** attempt));
   }
 }
 ```
 
 **413: three classes, one legacy base.** Every 413 used to throw `SnapshotTooLargeError`, whatever was too large. A 413 is now named for its cause: `PromptTooLargeError` for a `decide()` request that does not fit the model's context (shorten `state` or ask fewer questions), `RequestTooLargeError` for any other non-snapshot 413 (a request body over the server's limit, a memory value or quota, a channel payload — `e.code` says which), and `SnapshotTooLargeError` itself for a snapshot over its cap. `PromptTooLargeError` extends `RequestTooLargeError`, which extends `SnapshotTooLargeError`, so an existing `instanceof SnapshotTooLargeError` still matches every 413; that relation is for compatibility and says nothing about snapshots. To single out a snapshot that is too large, test `e.code === "snapshot_too_large"`.
 
-`e.name` (and the `meta_reason` of a `stream_close` frame) is the most specific class name, so it reads `TokenLimitExceededError`, `PromptTooLargeError` or `RequestTooLargeError` where it used to read `BackpressureError` or `SnapshotTooLargeError`. Match with `instanceof` or `e.code`, not on the name.
+`e.name` (and the `meta_reason` of a `stream_close` frame) is the most specific class name, so it reads `TokenLimitExceededError`, `RateLimitedError`, `PromptTooLargeError` or `RequestTooLargeError` where it used to read `BackpressureError` or `SnapshotTooLargeError`. Match with `instanceof` or `e.code`, not on the name.
 
-Priority within `404`: most-specific keyword wins (`snapshot` → `session` → `hook` → `agent` → base). The dispatch is keyword-matched on the response body lowercase; a hook with id `hook_agent_scan` still routes to `HookNotFoundError`, not `AgentNotFoundError`.
+Priority within `404`: most-specific keyword wins (`snapshot` → `session` → `agent` → base). The dispatch is keyword-matched on the response body lowercase, so a body that names none of them — a missing hook, memory row or interrupt — is a plain `NotFoundError`, while one that happens to contain "agent" (a hook id like `hook_agent_scan`) is an `AgentNotFoundError`. There is no hook-specific class; catch `NotFoundError` for any 404.
 
 ```ts
 import {
@@ -642,7 +898,7 @@ for await (const item of client.streamUserRunStates(userId, {
 A detached team walk returns a `run_id`, and that id **is** the walk id every run it spawns carries in `parent_context.walk_id`. Pass it back as `walkId` and the server filters the stream to that workflow — no second identifier, nothing to map:
 
 ```ts
-const { run_id } = await client.runTeam({ team: "triage", detach: true });
+const { run_id } = await client.runTeam({ name: "triage", mode: "detach" });
 
 for await (const item of client.streamUserRunStates(userId, { walkId: run_id })) {
   if (item.kind === "open") {