@zvada/agent-server 0.2.2 → 0.3.1

package/src/core/provision/pins.ts

@@ -27,7 +27,11 @@ export type CliTool = (typeof CLI_TOOLS)[number];
  *   set `provision.pins.codex` to their SDK's vendored version.
  */
 export const DEFAULT_PINS: Record<CliTool, string> = {
-	claude: "0.3.168",
+	// Held at 0.3.220: the paired CLI (2.1.220) honors `--thinking-display
+	// summarized`, so reasoning parts carry text. 2.1.233 ignores the flag and
+	// streams token-estimate placeholders instead — bump only after verifying
+	// thinking summaries still flow (see options.ts extraArgs).
+	claude: "0.3.220",
 	// 0.146.1 re-verified 2026-08-06: generate-ts snapshot carries our full
 	// surface unchanged (thread/turn/item methods, tokenUsage w/ window,
 	// approvals) and a live turn ran clean incl. the gpt-5.6-sol default.

package/src/core/proxy/anthropic-proxy.ts

@@ -1,8 +1,29 @@
+import { type DiagnosticHandler, emitDiagnostic } from "../diagnostics.ts";
 import { type ApiKeyStore, apiKeyStore } from "./api-key-store.ts";
 
 /** Placeholder key handed to the agent subprocess; swapped for the real one here. */
 export const PROXY_PLACEHOLDER_KEY = "sk-proxy-managed";
 
+/**
+ * The `anthropic-beta` capability that must accompany OAuth bearer traffic.
+ * Anthropic's gateway guidance: proxies carrying subscription-OAuth requests
+ * must advertise this capability or the upstream rejects the bearer token.
+ */
+export const ANTHROPIC_OAUTH_BETA = "oauth-2025-04-20";
+
+/** Append a capability to `anthropic-beta` without clobbering existing ones. */
+function appendAnthropicBeta(headers: Headers, capability: string): void {
+	const existing = headers.get("anthropic-beta");
+	const values = existing
+		? existing
+				.split(",")
+				.map((value) => value.trim())
+				.filter(Boolean)
+		: [];
+	if (!values.includes(capability)) values.push(capability);
+	headers.set("anthropic-beta", values.join(","));
+}
+
 /** Minimal fetch shape (`globalThis.fetch` qualifies; injectable for tests/platforms). */
 export type FetchLike = (
 	input: string | URL | Request,
@@ -16,6 +37,8 @@ export interface AnthropicProxyOptions {
 	pathPrefix?: string;
 	/** Fetch implementation (test seam / platform override). Default `globalThis.fetch`. */
 	fetch?: FetchLike;
+	/** Notified on upstream 401/403 — the STORED key is bad, not the placeholder. */
+	onDiagnostic?: DiagnosticHandler;
 }
 
 /**
@@ -65,10 +88,19 @@ export function createAnthropicProxy(
 		}
 
 		const headers = new Headers(request.headers);
-		headers.set("x-api-key", entry.apiKey);
-		headers.delete("authorization");
 		headers.delete("host");
 		headers.delete("content-length");
+		if (entry.kind === "oauth") {
+			// Subscription token: bearer auth + the OAuth capability. The
+			// x-api-key the CLI sent carries only the placeholder — it must go,
+			// or the upstream sees two conflicting credentials.
+			headers.delete("x-api-key");
+			headers.set("authorization", `Bearer ${entry.apiKey}`);
+			appendAnthropicBeta(headers, ANTHROPIC_OAUTH_BETA);
+		} else {
+			headers.set("x-api-key", entry.apiKey);
+			headers.delete("authorization");
+		}
 
 		const init: RequestInit & { duplex?: "half" } = {
 			method: request.method,
@@ -98,6 +130,15 @@ export function createAnthropicProxy(
 			);
 		}
 
+		if (upstream.status === 401 || upstream.status === 403) {
+			emitDiagnostic(options.onDiagnostic, {
+				type: "proxyUpstreamAuth",
+				sessionId,
+				message: `upstream rejected the stored key for session ${sessionId} (${upstream.status})`,
+				detail: { status: upstream.status },
+			});
+		}
+
 		const contentType = upstream.headers.get("content-type") ?? "";
 		// Media type only — parameters (charset) stripped, case-insensitive, so
 		// `text/event-streamish` or a parameter VALUE never selects SSE handling.

package/src/core/proxy/api-key-store.ts

@@ -1,20 +1,52 @@
-/** A real upstream key + base URL, keyed by an opaque proxy session id. */
+/** How a stored credential is presented to the upstream API. */
+export type ApiCredentialKind = "api_key" | "oauth";
+
+/** A real upstream credential + base URL, keyed by an opaque proxy session id. */
 export interface ApiKeyEntry {
 	apiKey: string;
 	upstreamBaseUrl: string;
+	/**
+	 * `api_key` → sent as `x-api-key` (Anthropic API keys).
+	 * `oauth` → sent as `Authorization: Bearer` with the OAuth capability
+	 * advertised in `anthropic-beta` (Claude subscription tokens from
+	 * `claude setup-token`, `sk-ant-oat01-…`).
+	 */
+	kind: ApiCredentialKind;
+}
+
+export interface ApiKeyStoreSetOptions {
+	upstreamBaseUrl?: string;
+	kind?: ApiCredentialKind;
 }
 
 /**
  * In-memory map of proxy-session → real credentials. The agent subprocess is
  * given a placeholder key and pointed at the local proxy; the proxy swaps in the
- * real key from this store before forwarding upstream, so the key never lives in
- * the subprocess environment. (BYOK pattern from the echo/agnt sidecars.)
+ * real credential from this store before forwarding upstream, so it never lives
+ * in the subprocess environment. (BYOK pattern from the echo/agnt sidecars.)
+ * That no-exfiltration property is exactly why subscription OAuth tokens ride
+ * the same store instead of the child env: the child keeps the placeholder
+ * either way, only the upstream header shape differs.
  */
 export class ApiKeyStore {
 	private readonly entries = new Map<string, ApiKeyEntry>();
 
-	set(sessionId: string, apiKey: string, upstreamBaseUrl = "https://api.anthropic.com"): void {
-		this.entries.set(sessionId, { apiKey, upstreamBaseUrl });
+	set(
+		sessionId: string,
+		apiKey: string,
+		// A plain string third argument (the base URL) remains supported: the
+		// pre-kind signature every existing sidecar call site uses.
+		optionsOrBaseUrl: string | ApiKeyStoreSetOptions = {},
+	): void {
+		const options =
+			typeof optionsOrBaseUrl === "string"
+				? { upstreamBaseUrl: optionsOrBaseUrl }
+				: optionsOrBaseUrl;
+		this.entries.set(sessionId, {
+			apiKey,
+			upstreamBaseUrl: options.upstreamBaseUrl ?? "https://api.anthropic.com",
+			kind: options.kind ?? "api_key",
+		});
 	}
 
 	get(sessionId: string): ApiKeyEntry | undefined {

package/src/core/proxy/index.ts

@@ -1,6 +1,13 @@
 // @zvada/agent-server/core/proxy — optional BYOK Anthropic proxy building block.
-export { type ApiKeyEntry, ApiKeyStore, apiKeyStore } from "./api-key-store.ts";
 export {
+	type ApiCredentialKind,
+	type ApiKeyEntry,
+	ApiKeyStore,
+	type ApiKeyStoreSetOptions,
+	apiKeyStore,
+} from "./api-key-store.ts";
+export {
+	ANTHROPIC_OAUTH_BETA,
 	type AnthropicProxyOptions,
 	createAnthropicProxy,
 	PROXY_PLACEHOLDER_KEY,

package/src/core/runtime/agent-runtime.ts

@@ -1,3 +1,9 @@
+import {
+	type ErrorCategory,
+	classifyError,
+	isCancellation,
+	isRecoverable,
+} from "../../protocol/errors.ts";
 import type {
 	AgentCapabilities,
 	AgentHarness,
@@ -11,13 +17,8 @@ import type {
 } from "../../protocol/index.ts";
 import { DEFAULT_TOKEN_USAGE, generateUUIDv7 } from "../../protocol/index.ts";
 import type { AgentExecuteOptions, CancelResult, PermissionDecision } from "../agents/base.ts";
-import {
-	type ErrorCategory,
-	classifyError,
-	isCancellation,
-	isRecoverable,
-} from "../agents/error-classifier.ts";
 import type { AgentRegistry } from "../agents/registry.ts";
+import { type DiagnosticHandler, emitDiagnostic } from "../diagnostics.ts";
 import { TurnConflictError } from "../utils/errors.ts";
 import { EventProcessor } from "./event-processor.ts";
 import type { EventSink } from "./event-sink.ts";
@@ -69,10 +70,14 @@ const turnKeyOf = (sessionId: string, turnId: string) => `${sessionId}:${turnId}
 const inputKeyOf = (request: RunRequest) =>
 	canonicalJson({ input: request.input, config: request.config });
 
-/** The standard options offered for every brokered permission request. */
+/** The standard options offered for every brokered permission request (§6.4:
+ * the broker must actually offer the `*_always` kinds the schema advertises —
+ * a "don't ask again" answer becomes a standing per-session rule). */
 const PERMISSION_OPTIONS: PermissionOption[] = [
 	{ optionId: "allow", name: "Allow", kind: "allow_once" },
+	{ optionId: "allow_always", name: "Always allow", kind: "allow_always" },
 	{ optionId: "reject", name: "Reject", kind: "reject_once" },
+	{ optionId: "reject_always", name: "Always reject", kind: "reject_always" },
 ];
 
 interface PendingPermission {
@@ -91,6 +96,8 @@ interface PendingPermission {
 export class AgentRuntime {
 	/** Permission requests awaiting `respondPermission`, across all live turns. */
 	private readonly pendingPermissions = new Map<string, PendingPermission>();
+	/** Standing per-session `*_always` answers: sessionId -> toolName -> verdict. */
+	private readonly alwaysDecisions = new Map<string, Map<string, "allow" | "deny">>();
 	private readonly activeRuns = new Set<Promise<RunSummary>>();
 	/** In-flight turns by turn key — the convergence target for retried runs. */
 	private readonly inflightTurns = new Map<
@@ -106,7 +113,10 @@ export class AgentRuntime {
 	private static readonly COMPLETED_TURN_MEMORY = 16;
 	private shutdownPromise?: Promise<void>;
 
-	constructor(private readonly registry: AgentRegistry) {}
+	constructor(
+		private readonly registry: AgentRegistry,
+		private readonly options: { onDiagnostic?: DiagnosticHandler } = {},
+	) {}
 
 	get harnesses(): AgentHarness[] {
 		return this.registry.list();
@@ -229,18 +239,22 @@ export class AgentRuntime {
 		const { sessionId, turnId, input, config } = request;
 		const agent = this.registry.getAgent(config.harness);
 		const transformer = this.registry.getAdapter(config.harness)({ sessionId });
-		const processor = new EventProcessor(sessionId, turnId, {
-			harness: config.harness,
-			model: config.model,
-		});
+		const processor = new EventProcessor(sessionId, turnId, { model: config.model });
 
 		// Isolate sink failures: a misbehaving transport must never break the
 		// turn's lifecycle bracketing (turn.started ... turn.ended).
 		const emit = async (e: LifecycleEvent) => {
 			try {
 				await sink.emit(e);
-			} catch {
-				// swallow — the sink owns its own reliability
+			} catch (err) {
+				// The turn must not fail on a misbehaving sink — but the host gets
+				// to know its sink dropped an event.
+				emitDiagnostic(this.options.onDiagnostic, {
+					type: "sinkError",
+					sessionId,
+					message: `sink emit failed for ${e.type}: ${err instanceof Error ? err.message : String(err)}`,
+					detail: err,
+				});
 			}
 		};
 
@@ -274,6 +288,16 @@ export class AgentRuntime {
 			permOpts?: { signal?: AbortSignal },
 		): Promise<PermissionDecision> => {
 			if (permOpts?.signal?.aborted) return { decision: "cancel" };
+			// A standing `*_always` rule from an earlier prompt in this session
+			// answers without a round-trip (and without fake prompt events). The
+			// rule carries the verdict only — an `updatedInput` edit belongs to the
+			// call it was made for, never to every later call to the same tool.
+			const standing = this.alwaysDecisions.get(sessionId)?.get(toolCall.toolName);
+			if (standing) {
+				return standing === "allow"
+					? { decision: "allow" }
+					: { decision: "deny", reason: "Denied by a standing rule" };
+			}
 			const requestId = generateUUIDv7();
 			// Register BEFORE emitting so even a sink that answers synchronously
 			// from its emit() finds the pending entry.
@@ -317,8 +341,26 @@ export class AgentRuntime {
 			const outcome = await outcomePromise;
 			if (outcome.outcome === "cancelled") return { decision: "cancel" };
 			const selected = PERMISSION_OPTIONS.find((o) => o.optionId === outcome.optionId);
-			return selected?.kind === "allow_once" || selected?.kind === "allow_always"
-				? { decision: "allow" }
+			const allowed = selected?.kind === "allow_once" || selected?.kind === "allow_always";
+			// An `*_always` answer becomes a standing per-session rule: later calls
+			// to the same tool skip the round-trip entirely (the user already gave
+			// a durable answer — re-asking would be noise, re-emitting events would
+			// fake a prompt that never happened). Cleared on session close.
+			if (selected?.kind === "allow_always" || selected?.kind === "reject_always") {
+				let rules = this.alwaysDecisions.get(sessionId);
+				if (!rules) {
+					rules = new Map();
+					this.alwaysDecisions.set(sessionId, rules);
+				}
+				rules.set(toolCall.toolName, allowed ? "allow" : "deny");
+			}
+			return allowed
+				? {
+						decision: "allow",
+						// What was approved is what runs (C1): an edited input replaces
+						// the original all the way into the harness.
+						...(outcome.updatedInput !== undefined && { updatedInput: outcome.updatedInput }),
+					}
 				: { decision: "deny", reason: "Denied by user" };
 		};
 		/** Cancellation / turn end resolves everything still pending as cancelled.
@@ -334,6 +376,11 @@ export class AgentRuntime {
 
 		await emit({ type: "turn.started", turnId, sessionId, timestamp: Date.now() });
 
+		// The user echo (spec §7.2): the submitted input goes back onto the stream
+		// as a complete user message (outputIndex 0) before any harness output, so
+		// the stream is a complete transcript and multi-client attach works.
+		for (const le of processor.echoUserMessage(input)) await emit(le);
+
 		const options: AgentExecuteOptions = {
 			sessionId,
 			turnId,
@@ -395,9 +442,9 @@ export class AgentRuntime {
 					type: "error",
 					turnId,
 					sessionId,
-					error: message,
+					category,
+					message,
 					recoverable: isRecoverable(category),
-					code: category,
 					stack: err instanceof Error ? err.stack : undefined,
 					timestamp: Date.now(),
 				});
@@ -453,6 +500,7 @@ export class AgentRuntime {
 	/** Dispose one idle logical session and its harness-native resources. */
 	async closeSession(harness: AgentHarness, sessionId: string): Promise<void> {
 		this.completedTurns.delete(sessionId);
+		this.alwaysDecisions.delete(sessionId);
 		await Promise.all(
 			[...this.pendingPermissions.values()]
 				.filter((pending) => pending.sessionId === sessionId)

package/src/core/runtime/event-processor.ts

@@ -1,5 +1,10 @@
-import { generateUUIDv7 } from "../../protocol/index.ts";
-import type { Delta, LifecycleEvent, Part, StopReason } from "../../protocol/index.ts";
+import {
+	classifyError,
+	createUserEchoParts,
+	echoMessageId,
+	generateUUIDv7,
+} from "../../protocol/index.ts";
+import type { AgentInput, Delta, LifecycleEvent, Part, StopReason } from "../../protocol/index.ts";
 import type { AdapterEvent, TransformResult } from "../agents/types.ts";
 
 /** Where a part lives on the wire — fixed at first emission for the whole turn. */
@@ -21,7 +26,7 @@ interface PartAddress {
  */
 export class EventProcessor {
 	private openMessageId?: string;
-	/** `parentToolUseId` of the open message (undefined for top-level messages). */
+	/** `parentToolCallId` of the open message (undefined for top-level messages). */
 	private openMessageParent?: string;
 	private currentOutputIndex = -1;
 	private nextOutputIndex = 0;
@@ -31,9 +36,24 @@ export class EventProcessor {
 	constructor(
 		private readonly sessionId: string,
 		private readonly turnId: string,
-		private readonly meta: { harness?: string; model?: string } = {},
+		private readonly meta: { model?: string } = {},
 	) {}
 
+	/**
+	 * The user echo: emits the submitted input back onto the stream as a
+	 * complete user message at outputIndex 0, before any harness output — the
+	 * stream is a complete transcript. Its messageId is DERIVED from the turn
+	 * id (`echoMessageId`), so a consumer that minted the turnId can predict the
+	 * whole echo instead of reconciling a look-alike against it.
+	 */
+	*echoUserMessage(input: AgentInput): Generator<LifecycleEvent> {
+		yield* this.openMessage("user", undefined, echoMessageId(this.turnId));
+		for (const part of createUserEchoParts(input, this.turnId)) {
+			yield* this.emitPart(part);
+		}
+		yield* this.closeMessage();
+	}
+
 	*handle(ev: AdapterEvent): Generator<LifecycleEvent> {
 		switch (ev.kind) {
 			case "message-start":
@@ -47,18 +67,18 @@ export class EventProcessor {
 				yield* this.emitPart(ev.part);
 				return;
 			case "text-delta": {
-				const e = this.delta(ev.partId, { type: "text-delta", text: ev.text });
+				const e = this.delta(ev.partId, { type: "text", text: ev.text });
 				if (e) yield e;
 				return;
 			}
 			case "reasoning-delta": {
-				const e = this.delta(ev.partId, { type: "reasoning-delta", text: ev.text });
+				const e = this.delta(ev.partId, { type: "reasoning", text: ev.text });
 				if (e) yield e;
 				return;
 			}
 			case "tool-input-delta": {
 				const e = this.delta(ev.partId, {
-					type: "tool-input-delta",
+					type: "tool_input",
 					toolCallId: ev.toolCallId,
 					toolName: ev.toolName,
 					input: ev.input,
@@ -78,10 +98,14 @@ export class EventProcessor {
 				};
 				return;
 			case "compacted":
+				// Harnesses report compaction after the fact — a single completed
+				// upsert of the positional entity (its first appearance anchors it).
 				yield {
-					type: "session.compacted",
+					type: "session.compaction",
 					sessionId: this.sessionId,
 					turnId: this.turnId,
+					compactionId: generateUUIDv7(),
+					status: "completed",
 					...(ev.trigger && { trigger: ev.trigger }),
 					...(ev.preTokens !== undefined && { preTokens: ev.preTokens }),
 					...(ev.postTokens !== undefined && { postTokens: ev.postTokens }),
@@ -103,7 +127,7 @@ export class EventProcessor {
 			cost: result.cost,
 			error:
 				result.error && !result.cancelled
-					? { name: "AgentError", message: result.error }
+					? { category: classifyError(result.error), message: result.error }
 					: undefined,
 			timestamp: Date.now(),
 		};
@@ -111,29 +135,28 @@ export class EventProcessor {
 
 	private *openMessage(
 		role: "assistant" | "user",
-		parentToolUseId?: string,
+		parentToolCallId?: string,
+		/** Derived id for the user echo; harness messages get a fresh UUIDv7. */
+		id?: string,
 	): Generator<LifecycleEvent> {
 		if (this.openMessageId) yield* this.closeMessage();
-		const messageId = generateUUIDv7();
+		const messageId = id ?? generateUUIDv7();
 		this.openMessageId = messageId;
-		this.openMessageParent = parentToolUseId;
+		this.openMessageParent = parentToolCallId;
 		this.currentOutputIndex = this.nextOutputIndex++;
 		this.nextPartIndex = 0;
 		yield {
 			type: "message.started",
+			sessionId: this.sessionId,
 			turnId: this.turnId,
 			messageId,
 			outputIndex: this.currentOutputIndex,
 			role,
 			// A parented message is a sub-agent's output — nests under its tool call,
 			// not a top-level model message (see DESIGN.md D5).
-			...(parentToolUseId && { parentToolUseId }),
+			...(parentToolCallId && { parentToolCallId }),
+			...(this.meta.model && { model: this.meta.model }),
 			timestamp: Date.now(),
-			metadata: {
-				sessionId: this.sessionId,
-				...(this.meta.harness && { harness: this.meta.harness }),
-				...(this.meta.model && { model: this.meta.model }),
-			},
 		};
 	}
 
@@ -141,6 +164,7 @@ export class EventProcessor {
 		if (!this.openMessageId) return;
 		yield {
 			type: "message.ended",
+			sessionId: this.sessionId,
 			turnId: this.turnId,
 			messageId: this.openMessageId,
 			timestamp: Date.now(),
@@ -150,25 +174,25 @@ export class EventProcessor {
 	}
 
 	/** Ensure an open message whose parent matches the incoming part. A part
-	 * whose `parentToolUseId` differs from the open message (main↔sub-agent, or
+	 * whose `parentToolCallId` differs from the open message (main↔sub-agent, or
 	 * between sibling sub-agents) starts a new message so sub-agent output is
 	 * grouped under its own parented message rather than mixed into another. */
-	private *ensureMessage(parentToolUseId?: string): Generator<LifecycleEvent> {
-		if (this.openMessageId && this.openMessageParent !== parentToolUseId) {
+	private *ensureMessage(parentToolCallId?: string): Generator<LifecycleEvent> {
+		if (this.openMessageId && this.openMessageParent !== parentToolCallId) {
 			yield* this.closeMessage();
 		}
-		if (!this.openMessageId) yield* this.openMessage("assistant", parentToolUseId);
+		if (!this.openMessageId) yield* this.openMessage("assistant", parentToolCallId);
 	}
 
 	/** Resolve (or assign) the wire address of a part. Yields a message.started
 	 * first when the part is new and no matching message is open. */
 	private *addressFor(
 		partId: string,
-		parentToolUseId?: string,
+		parentToolCallId?: string,
 	): Generator<LifecycleEvent, PartAddress> {
 		const existing = this.partAddressById.get(partId);
 		if (existing) return existing;
-		yield* this.ensureMessage(parentToolUseId);
+		yield* this.ensureMessage(parentToolCallId);
 		const address: PartAddress = {
 			messageId: this.openMessageId as string,
 			outputIndex: this.currentOutputIndex,
@@ -179,7 +203,7 @@ export class EventProcessor {
 	}
 
 	private *emitPart(part: Part): Generator<LifecycleEvent> {
-		const address = yield* this.addressFor(part.id, part.parentToolUseId);
+		const address = yield* this.addressFor(part.id, part.parentToolCallId);
 		// Snapshot: adapters mutate their part objects in place across
 		// open/update, so we must clone at emit time or buffered consumers would
 		// all observe the final state. Stamp ownership so the part is
@@ -189,12 +213,12 @@ export class EventProcessor {
 		snapshot.messageId = address.messageId;
 		yield {
 			type: "message.part",
+			sessionId: this.sessionId,
 			turnId: this.turnId,
 			messageId: address.messageId,
 			outputIndex: address.outputIndex,
 			partIndex: address.partIndex,
 			part: snapshot,
-			...(snapshot.parentToolUseId && { parentToolUseId: snapshot.parentToolUseId }),
 			timestamp: Date.now(),
 		};
 	}
@@ -206,6 +230,7 @@ export class EventProcessor {
 		if (!address) return null;
 		return {
 			type: "message.part.delta",
+			sessionId: this.sessionId,
 			turnId: this.turnId,
 			messageId: address.messageId,
 			outputIndex: address.outputIndex,

package/src/protocol/config.ts

@@ -4,17 +4,19 @@ import { AgentInputSchema } from "./part-input.ts";
 import { ThinkingLevelSchema } from "./thinking.ts";
 
 /**
- * Permission posture for a turn. `bypassPermissions`/`yolo` auto-approve every
+ * Permission posture for a turn. `bypass_permissions` auto-approves every
  * tool (the right default inside a sandbox); `plan` is read-only planning;
- * `dontAsk` never prompts — unapproved tools are denied, sandboxes stay at
- * their normal (non-dangerous) level. Harnesses map this onto their own modes.
+ * `dont_ask` never prompts — unapproved tools are denied, sandboxes stay at
+ * their normal (non-dangerous) level. Values follow the casing law (snake);
+ * adapters map to provider vocabulary at the edge (Claude SDK: acceptEdits,
+ * bypassPermissions).
  */
 export const PermissionModeSchema = z.enum([
 	"default",
 	"plan",
-	"acceptEdits",
-	"dontAsk",
-	"bypassPermissions",
+	"accept_edits",
+	"dont_ask",
+	"bypass_permissions",
 ]);
 export type PermissionMode = z.infer<typeof PermissionModeSchema>;
 

package/src/{core/agents/error-classifier.ts → protocol/errors.ts}

@@ -1,20 +1,42 @@
+import { z } from "zod";
+import { openVocabulary } from "./vocabulary.ts";
+
 /**
- * Maps a raw harness error into a stable category, so callers can react
- * (retry on `network`/`rate_limit`, surface `auth` prominently, treat `abort`
- * as success). Distilled from deus-machine's lifecycle classifier.
+ * The one error vocabulary (Law: one shape per concept). Used by
+ * `turn.ended.error`, the standalone `error` event, and `RunSummary.error`.
+ *
+ * OPEN (Law 3): products may extend with their own categories (deus adds
+ * "db_write"); unknown non-`_` values are reserved for this protocol.
+ * `usage_limit` (plan/quota exhausted) and `rate_limit` (429/backoff) are
+ * deliberately distinct — they need different user guidance; collapsing them
+ * is a display choice, never a wire merge.
  */
 export const ERROR_CATEGORIES = [
 	"auth",
 	"rate_limit",
+	"usage_limit",
 	"context_limit",
 	"network",
 	"abort",
+	"invalid_request",
 	"process_exit",
-	"usage_limit",
-	"unknown",
+	"internal",
 ] as const;
-export type ErrorCategory = (typeof ERROR_CATEGORIES)[number];
+export type ErrorCategory = (typeof ERROR_CATEGORIES)[number] | (string & {});
+export const ErrorCategorySchema = openVocabulary<ErrorCategory>();
+
+export const ErrorInfoSchema = z.object({
+	category: ErrorCategorySchema,
+	message: z.string(),
+});
+export type ErrorInfo = z.infer<typeof ErrorInfoSchema>;
 
+/**
+ * Maps a raw harness error into a stable category, so callers can react
+ * (retry on `network`/`rate_limit`, surface `auth` prominently, treat `abort`
+ * as success). Rule order matters. Distilled from deus-machine's lifecycle
+ * classifier; lives in /protocol because categories are vocabulary.
+ */
 const RULES: ReadonlyArray<[ErrorCategory, readonly string[]]> = [
 	["abort", ["aborted", "aborterror", "cancelled", "canceled", "interrupted", "sigint"]],
 	[
@@ -46,6 +68,10 @@ const RULES: ReadonlyArray<[ErrorCategory, readonly string[]]> = [
 			"socket hang up",
 		],
 	],
+	[
+		"invalid_request",
+		["invalid request", "invalid_request_error", "status 400", "http 400", "bad request"],
+	],
 	["process_exit", ["exited with code", "process exited", "spawn", "enoent", "killed"]],
 ];
 
@@ -54,7 +80,7 @@ export function classifyError(error: unknown): ErrorCategory {
 	for (const [category, needles] of RULES) {
 		if (needles.some((n) => message.includes(n))) return category;
 	}
-	return "unknown";
+	return "internal";
 }
 
 /** Whether a turn can plausibly be retried after this error. */