@adecore/agents 0.29.2 → 0.30.0

package/src/chat/acp-protocol.ts

@@ -0,0 +1,763 @@
+import { isRecord, type ChatFileChange, type RuntimeMode } from '@adecore/agent-contracts';
+import { z } from 'zod';
+import { MODE_ORDER } from '../modes.ts';
+import type { ApprovalDecision, BackendEvent } from './backend.ts';
+
+/*
+ * The Agent Client Protocol (https://agentclientprotocol.com), version 1, as far as a chat needs it.
+ * Every schema is loose: an agent may add fields, and a field or an update this version does not
+ * know is ignored rather than refused, as the protocol asks of a client.
+ */
+
+export const ACP_PROTOCOL_VERSION = 1;
+
+// The code an agent answers `session/new` or `session/load` with when it needs `authenticate` first.
+export const ACP_AUTH_REQUIRED = -32000;
+
+const ContentBlockSchema = z.looseObject({ type: z.string(), text: z.string().optional() });
+
+const ContentChunkSchema = z.looseObject({ content: ContentBlockSchema, messageId: z.string().nullish() });
+
+const ToolCallSchema = z.looseObject({
+    toolCallId: z.string(),
+    title: z.string().nullish(),
+    name: z.string().nullish(),
+    kind: z.string().nullish(),
+    status: z.string().nullish(),
+    content: z.array(z.unknown()).nullish(),
+    locations: z.array(z.unknown()).nullish(),
+    rawInput: z.unknown().optional(),
+    rawOutput: z.unknown().optional()
+});
+
+const DiffSchema = z.looseObject({ type: z.literal('diff'), path: z.string(), oldText: z.string().nullish(), newText: z.string() });
+
+const ToolContentSchema = z.looseObject({ type: z.literal('content'), content: ContentBlockSchema });
+
+const LocationSchema = z.looseObject({ path: z.string() });
+
+const PlanEntrySchema = z.looseObject({ content: z.string(), status: z.string(), priority: z.string().optional() });
+
+const CommandSchema = z.looseObject({ name: z.string() });
+
+const UsageSchema = z.looseObject({
+    used: z.number(),
+    size: z.number(),
+    cost: z.looseObject({ amount: z.number(), currency: z.string() }).nullish()
+});
+
+const PermissionOptionSchema = z.looseObject({ optionId: z.string(), name: z.string(), kind: z.string() });
+
+const PermissionRequestSchema = z.looseObject({
+    sessionId: z.string(),
+    toolCall: ToolCallSchema,
+    options: z.array(PermissionOptionSchema)
+});
+
+const SessionNotificationSchema = z.looseObject({ sessionId: z.string(), update: z.looseObject({ sessionUpdate: z.string() }) });
+
+const PromptResponseSchema = z.looseObject({ stopReason: z.string() });
+
+const ModeStateSchema = z.looseObject({
+    currentModeId: z.string(),
+    availableModes: z.array(z.unknown())
+});
+
+const ModeSchema = z.looseObject({ id: z.string(), name: z.string() });
+
+const SelectValueSchema = z.looseObject({ value: z.string(), name: z.string() });
+
+const ConfigOptionSchema = z.looseObject({
+    id: z.string(),
+    name: z.string(),
+    type: z.string(),
+    category: z.string().nullish(),
+    currentValue: z.unknown().optional(),
+    options: z.array(z.unknown()).optional()
+});
+
+// Models as agents reported them before the protocol moved them into config options; still sent by some.
+const ModelStateSchema = z.looseObject({
+    currentModelId: z.string(),
+    availableModels: z.array(z.unknown())
+});
+
+const ModelEntrySchema = z.looseObject({ modelId: z.string(), name: z.string(), description: z.string().nullish() });
+
+const AuthMethodSchema = z.looseObject({ id: z.string(), name: z.string() });
+
+const InitializeResponseSchema = z.looseObject({
+    protocolVersion: z.number(),
+    agentCapabilities: z
+        .looseObject({
+            loadSession: z.boolean().optional(),
+            promptCapabilities: z.looseObject({ image: z.boolean().optional() }).optional(),
+            sessionCapabilities: z
+                .looseObject({
+                    resume: z.unknown().optional(),
+                    additionalDirectories: z.unknown().optional()
+                })
+                .optional()
+        })
+        .optional(),
+    authMethods: z.array(z.unknown()).optional(),
+    agentInfo: z.looseObject({ name: z.string(), title: z.string().nullish(), version: z.string() }).nullish()
+});
+
+const SessionResponseSchema = z.looseObject({ sessionId: z.string().optional() });
+
+/* Parses each item on its own, dropping the ones that do not fit instead of the whole list. */
+function validItems<T>(schema: z.ZodType<T>, items: readonly unknown[] | null | undefined): T[] {
+    return (items ?? []).flatMap((item) => {
+        const parsed = schema.safeParse(item);
+        return parsed.success ? [parsed.data] : [];
+    });
+}
+
+export interface AcpAgentInfo {
+    name: string;
+    title: string | null;
+    version: string;
+}
+
+/* What `initialize` answered, as far as a chat acts on it. */
+export interface AcpAgentCapabilities {
+    protocolVersion: number;
+    loadSession: boolean;
+    resumeSession: boolean;
+    additionalDirectories: boolean;
+    images: boolean;
+    authMethods: string[];
+    agent: AcpAgentInfo | null;
+}
+
+export function parseInitialize(result: unknown): AcpAgentCapabilities {
+    const parsed = InitializeResponseSchema.safeParse(result);
+    if (!parsed.success) {
+        throw new Error('initialize failed: the agent answered with something that is not an initialize response');
+    }
+    const capabilities = parsed.data.agentCapabilities;
+    const sessions = capabilities?.sessionCapabilities;
+    const agent = parsed.data.agentInfo;
+    return {
+        protocolVersion: parsed.data.protocolVersion,
+        loadSession: capabilities?.loadSession === true,
+        resumeSession: sessions?.resume !== undefined && sessions.resume !== null,
+        additionalDirectories: sessions?.additionalDirectories !== undefined && sessions.additionalDirectories !== null,
+        images: capabilities?.promptCapabilities?.image === true,
+        authMethods: validItems(AuthMethodSchema, parsed.data.authMethods).map((method) => method.id),
+        agent: agent ? { name: agent.name, title: agent.title ?? null, version: agent.version } : null
+    };
+}
+
+export interface AcpModel {
+    id: string;
+    name: string;
+    description: string | null;
+}
+
+/* The models a session offers. `configId` is the config option that picks one, or null where the agent takes `session/set_model`. */
+export interface AcpModelState {
+    current: string;
+    models: AcpModel[];
+    configId: string | null;
+}
+
+export interface AcpMode {
+    id: string;
+    name: string;
+}
+
+/* The modes a session offers. `configId` is the config option that picks one, or null where the agent takes `session/set_mode`. */
+export interface AcpModeState {
+    current: string;
+    modes: AcpMode[];
+    configId: string | null;
+}
+
+/* What `session/new`, `session/load` or `session/resume` said about the session, for a host that fills its catalog from it. */
+export interface AcpSessionInfo {
+    sessionId: string;
+    agent: AcpAgentInfo | null;
+    models: AcpModelState | null;
+    modes: AcpModeState | null;
+    // The reasoning effort a session offers, as a config option with the `thought_level` category.
+    thoughtLevel: { configId: string; current: string; values: string[] } | null;
+}
+
+type ConfigOption = z.infer<typeof ConfigOptionSchema>;
+
+/* The values of a select option, grouped or not. */
+function selectValues(option: ConfigOption): Array<z.infer<typeof SelectValueSchema>> {
+    const flat = (option.options ?? []).flatMap((entry) => (isRecord(entry) && Array.isArray(entry.options) ? entry.options : [entry]));
+    return validItems(SelectValueSchema, flat);
+}
+
+function selectOption(options: ConfigOption[], category: string): ConfigOption | null {
+    return options.find((option) => option.type === 'select' && option.category === category && typeof option.currentValue === 'string') ?? null;
+}
+
+export function parseSessionInfo(result: unknown, sessionId: string, agent: AcpAgentInfo | null): AcpSessionInfo {
+    const record = isRecord(result) ? result : {};
+    const options = validItems(ConfigOptionSchema, Array.isArray(record.configOptions) ? record.configOptions : []);
+    return { sessionId, agent, ...sessionState(options, record.modes, record.models) };
+}
+
+function sessionState(options: ConfigOption[], modes: unknown, models: unknown): Omit<AcpSessionInfo, 'sessionId' | 'agent'> {
+    const modelOption = selectOption(options, 'model');
+    const modeOption = selectOption(options, 'mode');
+    const thoughtOption = selectOption(options, 'thought_level');
+    const modeState = ModeStateSchema.safeParse(modes);
+    const modelState = ModelStateSchema.safeParse(models);
+    return {
+        models: modelOption
+            ? {
+                  current: modelOption.currentValue as string,
+                  models: selectValues(modelOption).map((value) => ({ id: value.value, name: value.name, description: null })),
+                  configId: modelOption.id
+              }
+            : modelState.success
+              ? {
+                    current: modelState.data.currentModelId,
+                    models: validItems(ModelEntrySchema, modelState.data.availableModels).map((model) => ({
+                        id: model.modelId,
+                        name: model.name,
+                        description: model.description ?? null
+                    })),
+                    configId: null
+                }
+              : null,
+        modes: modeOption
+            ? {
+                  current: modeOption.currentValue as string,
+                  modes: selectValues(modeOption).map((value) => ({ id: value.value, name: value.name })),
+                  configId: modeOption.id
+              }
+            : modeState.success
+              ? {
+                    current: modeState.data.currentModeId,
+                    modes: validItems(ModeSchema, modeState.data.availableModes).map((mode) => ({ id: mode.id, name: mode.name })),
+                    configId: null
+                }
+              : null,
+        thoughtLevel: thoughtOption
+            ? { configId: thoughtOption.id, current: thoughtOption.currentValue as string, values: selectValues(thoughtOption).map((value) => value.value) }
+            : null
+    };
+}
+
+export function sessionIdOf(result: unknown): string | null {
+    const parsed = SessionResponseSchema.safeParse(result);
+    return parsed.success ? (parsed.data.sessionId ?? null) : null;
+}
+
+/* The agent's own mode ids per runtime mode, best first. */
+export type AcpModeMap = Partial<Record<RuntimeMode, readonly string[]>>;
+
+/*
+ * The agent mode a runtime mode runs in: the first id the agent offers for that mode, else for the
+ * next narrower one, and so on down to `supervised`. Never a wider one; null when nothing fits.
+ */
+export function resolveAcpMode(requested: RuntimeMode, map: AcpModeMap, offered: readonly string[]): { modeId: string; runtimeMode: RuntimeMode } | null {
+    for (let index = MODE_ORDER.indexOf(requested); index >= 0; index--) {
+        const runtimeMode = MODE_ORDER[index]!;
+        const modeId = (map[runtimeMode] ?? []).find((candidate) => offered.includes(candidate));
+        if (modeId !== undefined) {
+            return { modeId, runtimeMode };
+        }
+    }
+    return null;
+}
+
+/* The widest runtime mode a map puts an agent mode under, which is what that mode grants; null for one it does not name. */
+export function runtimeModeOf(modeId: string, map: AcpModeMap): RuntimeMode | null {
+    for (let index = MODE_ORDER.length - 1; index >= 0; index--) {
+        const runtimeMode = MODE_ORDER[index]!;
+        if ((map[runtimeMode] ?? []).includes(modeId)) {
+            return runtimeMode;
+        }
+    }
+    return null;
+}
+
+// The tool kinds whose requests a runtime mode answers on its own when the agent has no mode for it.
+const AUTO_ALLOWED: Record<RuntimeMode, ReadonlySet<string> | 'all'> = {
+    supervised: new Set(),
+    'auto-accept-edits': new Set(['read', 'search', 'think', 'edit', 'move']),
+    auto: new Set(['read', 'search', 'think', 'edit', 'move', 'fetch']),
+    'full-access': 'all'
+};
+
+export function autoAllows(mode: RuntimeMode, kind: string | null): boolean {
+    const allowed = AUTO_ALLOWED[mode];
+    return allowed === 'all' || (kind !== null && allowed.has(kind));
+}
+
+/* The trimmed hunk between two texts, as one unified diff; null when they are the same. */
+export function unifiedDiff(oldText: string, newText: string): string | null {
+    const lines = (text: string): string[] => {
+        const split = text === '' ? [] : text.split('\n');
+        if (split.at(-1) === '') {
+            split.pop();
+        }
+        return split;
+    };
+    const before = lines(oldText);
+    const after = lines(newText);
+    let prefix = 0;
+    while (prefix < before.length && prefix < after.length && before[prefix] === after[prefix]) {
+        prefix++;
+    }
+    let suffix = 0;
+    while (suffix < before.length - prefix && suffix < after.length - prefix && before[before.length - 1 - suffix] === after[after.length - 1 - suffix]) {
+        suffix++;
+    }
+    const removed = before.slice(prefix, before.length - suffix);
+    const added = after.slice(prefix, after.length - suffix);
+    if (removed.length === 0 && added.length === 0) {
+        return null;
+    }
+    const range = (count: number): string => `${count === 0 ? prefix : prefix + 1},${count}`;
+    return (
+        [`@@ -${range(removed.length)} +${range(added.length)} @@`, ...removed.map((line) => `-${line}`), ...added.map((line) => `+${line}`)].join('\n') + '\n'
+    );
+}
+
+type Diff = z.infer<typeof DiffSchema>;
+
+interface ToolState {
+    title: string;
+    name: string | null;
+    kind: string | null;
+    status: string | null;
+    rawInput: unknown;
+    rawOutput: unknown;
+    locations: string[];
+    diffs: Diff[];
+    text: string[];
+    // What the thread last heard, so an update that changes nothing about the row sends nothing.
+    shown: string | null;
+    settled: boolean;
+}
+
+// `Edit` would have the thread draw a diff of nothing until the agent sends one.
+const KIND_NAMES: Record<string, string> = {
+    edit: 'Change',
+    delete: 'Delete',
+    move: 'Move',
+    think: 'Think',
+    switch_mode: 'Switch mode',
+    other: 'Tool'
+};
+
+function str(value: unknown): string | null {
+    return typeof value === 'string' && value !== '' ? value : null;
+}
+
+/* A field of the agent's own input, which no schema promises; the first one that is a non-empty string. */
+function rawField(raw: unknown, ...keys: string[]): string | null {
+    if (!isRecord(raw)) {
+        return null;
+    }
+    for (const key of keys) {
+        const value = raw[key];
+        if (Array.isArray(value) && value.every((part) => typeof part === 'string') && value.length > 0) {
+            return value.join(' ');
+        }
+        if (str(value) !== null) {
+            return value as string;
+        }
+    }
+    return null;
+}
+
+/* The row a tool call becomes: a name the thread has words for where the kind says which, and an input it reads a subject from. */
+export function toolRow(tool: Pick<ToolState, 'title' | 'name' | 'kind' | 'rawInput' | 'locations' | 'diffs'>): {
+    name: string;
+    input: Record<string, unknown>;
+    changes?: ChatFileChange[];
+} {
+    const description = tool.title;
+    const path = tool.locations[0] ?? rawField(tool.rawInput, 'file_path', 'path', 'filePath') ?? null;
+    if (tool.diffs.length > 0) {
+        const paths = new Set(tool.diffs.map((diff) => diff.path));
+        if (paths.size === 1) {
+            const [first] = tool.diffs;
+            if (tool.diffs.length === 1 && (first!.oldText ?? null) === null) {
+                return { name: 'Write', input: { file_path: first!.path, content: first!.newText, description } };
+            }
+            if (tool.diffs.length === 1) {
+                return { name: 'Edit', input: { file_path: first!.path, old_string: first!.oldText, new_string: first!.newText, description } };
+            }
+            return {
+                name: 'MultiEdit',
+                input: { file_path: first!.path, edits: tool.diffs.map((diff) => ({ old_string: diff.oldText ?? '', new_string: diff.newText })), description }
+            };
+        }
+        const changes = tool.diffs.flatMap((diff): ChatFileChange[] => {
+            const text = unifiedDiff(diff.oldText ?? '', diff.newText);
+            return text === null ? [] : [{ path: diff.path, kind: (diff.oldText ?? null) === null ? 'add' : 'update', diff: text }];
+        });
+        return { name: 'ApplyPatch', input: { summary: [...paths].join(', '), description }, changes };
+    }
+    const raw = isRecord(tool.rawInput) ? tool.rawInput : {};
+    switch (tool.kind) {
+        case 'execute':
+            return { name: 'Bash', input: { ...raw, description, command: rawField(tool.rawInput, 'command', 'cmd') ?? description } };
+        case 'read':
+            return { name: 'Read', input: { ...raw, description, ...(path === null ? {} : { file_path: path }) } };
+        case 'search':
+            return { name: 'Grep', input: { ...raw, description, pattern: rawField(tool.rawInput, 'pattern', 'query', 'regex') ?? description } };
+        case 'fetch': {
+            const url = rawField(tool.rawInput, 'url', 'uri');
+            return url === null
+                ? { name: 'WebSearch', input: { ...raw, description, query: rawField(tool.rawInput, 'query') ?? description } }
+                : { name: 'WebFetch', input: { ...raw, description, url } };
+        }
+        default:
+            return {
+                name: tool.name ?? KIND_NAMES[tool.kind ?? 'other'] ?? 'Tool',
+                input: { description, ...raw, ...(path === null ? {} : { path }) }
+            };
+    }
+}
+
+function toolOutput(tool: ToolState): string | null {
+    if (tool.text.length > 0) {
+        return tool.text.join('\n');
+    }
+    if (typeof tool.rawOutput === 'string') {
+        return tool.rawOutput;
+    }
+    if (isRecord(tool.rawOutput)) {
+        const text = rawField(tool.rawOutput, 'output', 'stdout', 'content', 'result', 'error');
+        return text ?? JSON.stringify(tool.rawOutput);
+    }
+    return null;
+}
+
+/* A permission request as the backend acts on it: the event it raises, and the tool kind a runtime mode may answer it by. */
+export interface AcpPermission {
+    requestId: string;
+    rpcId: number | string;
+    kind: string | null;
+    events: BackendEvent[];
+}
+
+/* The words a turn that ended for another reason than its end leaves in the thread. */
+export interface AcpStopWords {
+    maxTokens: string;
+    maxTurnRequests: string;
+    refusal: string;
+}
+
+export function acpStopWords(agentName: string): AcpStopWords {
+    return {
+        maxTokens: `${agentName} stopped: the response reached its token limit.`,
+        maxTurnRequests: `${agentName} stopped: the turn reached its limit of model requests.`,
+        refusal: `${agentName} refused to continue this turn.`
+    };
+}
+
+/*
+ * One ACP session's `session/update` stream, mapped onto backend events. A message's chunks become
+ * one text item, cut where the agent switches to a thought or a tool; a tool call becomes a row that
+ * is drawn again whenever an update changes what it shows, and settles when it completes or fails.
+ */
+export class AcpProtocol {
+    private readonly generation: number;
+    private readonly modes: AcpModeMap;
+    private readonly words: AcpStopWords;
+    private readonly tools = new Map<string, ToolState>();
+    private readonly permissions = new Map<string, { rpcId: number | string; options: Array<z.infer<typeof PermissionOptionSchema>> }>();
+    private text: { ref: string; messageId: string | null; text: string } | null = null;
+    private thought: { ref: string; text: string } | null = null;
+    private counter = 0;
+    private costUsd = 0;
+
+    constructor(generation: number, modes: AcpModeMap, words: AcpStopWords) {
+        this.generation = generation;
+        this.modes = modes;
+        this.words = words;
+    }
+
+    /* One `session/update` notification; empty for another session, an unknown update or one that does not parse. */
+    update(sessionId: string, params: unknown): BackendEvent[] {
+        const notification = SessionNotificationSchema.safeParse(params);
+        if (!notification.success || notification.data.sessionId !== sessionId) {
+            return [];
+        }
+        const update = notification.data.update;
+        switch (update.sessionUpdate) {
+            case 'agent_message_chunk':
+                return this.messageChunk(update);
+            case 'agent_thought_chunk':
+                return this.thoughtChunk(update);
+            case 'tool_call':
+            case 'tool_call_update': {
+                const call = ToolCallSchema.safeParse(update);
+                return call.success ? [...this.closeText(), ...this.closeThought(), ...this.toolCall(call.data)] : [];
+            }
+            case 'plan':
+                return this.plan(update);
+            case 'available_commands_update': {
+                const commands = validItems(CommandSchema, Array.isArray(update.availableCommands) ? update.availableCommands : []);
+                return [{ type: 'session', agentSessionId: null, model: null, slashCommands: commands.map((command) => command.name) }];
+            }
+            case 'current_mode_update':
+                return typeof update.currentModeId === 'string' ? [this.modeEvent(update.currentModeId)] : [];
+            case 'config_option_update': {
+                const options = validItems(ConfigOptionSchema, Array.isArray(update.configOptions) ? update.configOptions : []);
+                const state = sessionState(options, null, null);
+                return [
+                    ...(state.models === null ? [] : [{ type: 'model', model: state.models.current } as const]),
+                    ...(state.modes === null ? [] : [this.modeEvent(state.modes.current)])
+                ];
+            }
+            case 'usage_update': {
+                const usage = UsageSchema.safeParse(update);
+                if (!usage.success) {
+                    return [];
+                }
+                const cost = usage.data.cost?.currency === 'USD' ? usage.data.cost.amount : undefined;
+                if (cost !== undefined) {
+                    this.costUsd = cost;
+                }
+                return [{ type: 'usage', contextTokens: usage.data.used, contextWindow: usage.data.size, ...(cost === undefined ? {} : { costUsd: cost }) }];
+            }
+            case 'session_info_update':
+                return str(update.title) === null ? [] : [{ type: 'title', title: update.title as string }];
+            default:
+                return [];
+        }
+    }
+
+    modeEvent(modeId: string): BackendEvent {
+        const runtimeMode = runtimeModeOf(modeId, this.modes);
+        return { type: 'permissions', permissionMode: modeId, ...(runtimeMode === null ? {} : { effectiveRuntimeMode: runtimeMode }) };
+    }
+
+    /* A `session/request_permission` request; null when it does not parse, which the caller answers with an error. */
+    permission(rpcId: number | string, sessionId: string, params: unknown): AcpPermission | null {
+        const request = PermissionRequestSchema.safeParse(params);
+        if (!request.success || request.data.sessionId !== sessionId) {
+            return null;
+        }
+        const requestId = `acp-${this.generation}-${String(rpcId)}`;
+        const events = [...this.closeText(), ...this.closeThought(), ...this.toolCall(request.data.toolCall, false)];
+        const tool = this.tools.get(request.data.toolCall.toolCallId)!;
+        const row = toolRow(tool);
+        const options = request.data.options;
+        this.permissions.set(requestId, { rpcId, options });
+        events.push({
+            type: 'approval.requested',
+            requestId,
+            ref: request.data.toolCall.toolCallId,
+            toolName: row.name,
+            input: row.changes ? { ...row.input, changes: row.changes } : row.input,
+            description: tool.title === '' ? null : tool.title,
+            canAllowAlways: options.some((option) => option.kind === 'allow_always')
+        });
+        return { requestId, rpcId, kind: tool.kind, events };
+    }
+
+    /*
+     * The answer to a permission request: allow once, reject, or allow always only when the agent offered it.
+     * A decision the agent offered no option for falls to the narrower one, and a refusal with no reject option
+     * at all is a cancelled outcome.
+     */
+    answer(requestId: string, decision: ApprovalDecision): { rpcId: number | string; result: unknown } | null {
+        const pending = this.permissions.get(requestId);
+        if (!pending) {
+            return null;
+        }
+        this.permissions.delete(requestId);
+        const byKind = (...kinds: string[]): string | null => {
+            for (const kind of kinds) {
+                const option = pending.options.find((candidate) => candidate.kind === kind);
+                if (option) {
+                    return option.optionId;
+                }
+            }
+            return null;
+        };
+        const optionId =
+            decision === 'allow-always'
+                ? byKind('allow_always', 'allow_once')
+                : decision === 'allow'
+                  ? byKind('allow_once', 'allow_always')
+                  : byKind('reject_once', 'reject_always');
+        return { rpcId: pending.rpcId, result: { outcome: optionId === null ? { outcome: 'cancelled' } : { outcome: 'selected', optionId } } };
+    }
+
+    /* Every permission request still open, answered as cancelled, which the protocol asks of a client that cancels a turn. */
+    cancelPermissions(): Array<{ requestId: string; rpcId: number | string; result: unknown }> {
+        const cancelled = [...this.permissions].map(([requestId, pending]) => ({
+            requestId,
+            rpcId: pending.rpcId,
+            result: { outcome: { outcome: 'cancelled' } }
+        }));
+        this.permissions.clear();
+        return cancelled;
+    }
+
+    hasPermission(requestId: string): boolean {
+        return this.permissions.has(requestId);
+    }
+
+    /* The end of a turn, from the `stopReason` of its `session/prompt` response. */
+    finish(result: unknown, promptId: string | undefined): BackendEvent[] {
+        const parsed = PromptResponseSchema.safeParse(result);
+        const reason = parsed.success ? parsed.data.stopReason : 'end_turn';
+        const events = [...this.closeText(), ...this.closeThought()];
+        const base = { ...(promptId === undefined ? {} : { promptId }), costUsd: this.costUsd };
+        switch (reason) {
+            case 'cancelled':
+                events.push({ type: 'turn.done', ...base, state: 'aborted' });
+                break;
+            case 'refusal':
+                events.push({ type: 'turn.done', ...base, state: 'error', error: this.words.refusal });
+                break;
+            case 'max_tokens':
+                events.push({ type: 'note', level: 'warning', text: this.words.maxTokens }, { type: 'turn.done', ...base, state: 'done' });
+                break;
+            case 'max_turn_requests':
+                events.push({ type: 'note', level: 'warning', text: this.words.maxTurnRequests }, { type: 'turn.done', ...base, state: 'done' });
+                break;
+            default:
+                events.push({ type: 'turn.done', ...base, state: 'done' });
+        }
+        return events;
+    }
+
+    /* A turn that ended without a `stopReason`: the request failed, or was cancelled before the agent said so. */
+    abort(promptId: string | undefined, error: string | null): BackendEvent[] {
+        const base = { ...(promptId === undefined ? {} : { promptId }), costUsd: this.costUsd };
+        return [
+            ...this.closeText(),
+            ...this.closeThought(),
+            error === null ? { type: 'turn.done', ...base, state: 'aborted' } : { type: 'turn.done', ...base, state: 'error', error }
+        ];
+    }
+
+    private messageChunk(update: Record<string, unknown>): BackendEvent[] {
+        const chunk = ContentChunkSchema.safeParse(update);
+        if (!chunk.success || chunk.data.content.type !== 'text' || chunk.data.content.text === undefined) {
+            return [];
+        }
+        const messageId = chunk.data.messageId ?? null;
+        const events = this.closeThought();
+        if (this.text !== null && messageId !== null && this.text.messageId !== messageId) {
+            events.push(...this.closeText());
+        }
+        if (this.text === null) {
+            this.text = { ref: messageId === null ? `message-${++this.counter}` : `message-${messageId}`, messageId, text: '' };
+        }
+        this.text.text += chunk.data.content.text;
+        events.push({ type: 'text.delta', ref: this.text.ref, text: chunk.data.content.text });
+        return events;
+    }
+
+    private thoughtChunk(update: Record<string, unknown>): BackendEvent[] {
+        const chunk = ContentChunkSchema.safeParse(update);
+        if (!chunk.success || chunk.data.content.type !== 'text' || chunk.data.content.text === undefined) {
+            return [];
+        }
+        const events = this.closeText();
+        if (this.thought === null) {
+            this.thought = { ref: `thought-${++this.counter}`, text: '' };
+        }
+        this.thought.text += chunk.data.content.text;
+        events.push({ type: 'thinking.delta', ref: this.thought.ref, text: chunk.data.content.text });
+        return events;
+    }
+
+    private closeText(): BackendEvent[] {
+        const text = this.text;
+        this.text = null;
+        return text === null ? [] : [{ type: 'text.done', ref: text.ref, text: text.text }];
+    }
+
+    private closeThought(): BackendEvent[] {
+        const thought = this.thought;
+        this.thought = null;
+        return thought === null ? [] : [{ type: 'thinking.done', ref: thought.ref, text: thought.text }];
+    }
+
+    /* A tool call or an update to one; fields an update leaves out keep what the call said before, and a list it sends replaces the old one. */
+    private toolCall(call: z.infer<typeof ToolCallSchema>, settle = true): BackendEvent[] {
+        const known = this.tools.get(call.toolCallId);
+        const tool: ToolState = known ?? {
+            title: '',
+            name: null,
+            kind: null,
+            status: null,
+            rawInput: undefined,
+            rawOutput: undefined,
+            locations: [],
+            diffs: [],
+            text: [],
+            shown: null,
+            settled: false
+        };
+        tool.title = call.title ?? tool.title;
+        tool.name = call.name ?? tool.name;
+        tool.kind = call.kind ?? tool.kind;
+        tool.status = call.status ?? tool.status;
+        tool.rawInput = call.rawInput ?? tool.rawInput;
+        tool.rawOutput = call.rawOutput ?? tool.rawOutput;
+        if (call.locations) {
+            tool.locations = validItems(LocationSchema, call.locations).map((location) => location.path);
+        }
+        if (call.content) {
+            tool.diffs = validItems(DiffSchema, call.content);
+            tool.text = validItems(ToolContentSchema, call.content).flatMap((entry) =>
+                entry.content.type === 'text' && entry.content.text ? [entry.content.text] : []
+            );
+        }
+        this.tools.set(call.toolCallId, tool);
+        const events: BackendEvent[] = [];
+        const row = toolRow(tool);
+        const shown = JSON.stringify(row);
+        if (shown !== tool.shown) {
+            tool.shown = shown;
+            events.push({
+                type: 'tool.started',
+                ref: call.toolCallId,
+                name: row.name,
+                input: row.input,
+                parentRef: null,
+                ...(row.changes ? { changes: row.changes } : {})
+            });
+        }
+        if (settle && !tool.settled && (tool.status === 'completed' || tool.status === 'failed')) {
+            tool.settled = true;
+            events.push({
+                type: 'tool.done',
+                ref: call.toolCallId,
+                output: toolOutput(tool),
+                state: tool.status === 'completed' ? 'done' : 'error',
+                ...(row.changes ? { changes: row.changes } : {})
+            });
+        }
+        return events;
+    }
+
+    /* A plan is the whole list each time; it becomes a to-do row of its own, as a plan update in the thread. */
+    private plan(update: Record<string, unknown>): BackendEvent[] {
+        const entries = validItems(PlanEntrySchema, Array.isArray(update.entries) ? update.entries : []);
+        const ref = `plan-${++this.counter}`;
+        const todos = entries.map((entry) => ({
+            content: entry.content,
+            status: entry.status,
+            activeForm: entry.content,
+            ...(entry.priority ? { priority: entry.priority } : {})
+        }));
+        return [
+            ...this.closeText(),
+            ...this.closeThought(),
+            { type: 'tool.started', ref, name: 'TodoWrite', input: { todos }, parentRef: null },
+            { type: 'tool.done', ref, output: null, state: 'done' }
+        ];
+    }
+}