@gaunt-sloth/agent 2.0.0-alpha.34 → 2.0.0-alpha.36

package/dist/modules/acp/acpPermissions.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @packageDocumentation
+ * Bridges the agent's tool-approval gate to ACP v2's `session/request_permission`.
+ *
+ * **This is the reason the ACP server drives {@link GthAgentRunner} rather than an agent
+ * directly.** The runner is what owns the gate — the bypass check, the allow-list, the AI rater,
+ * the deny list, and finally the human callback — and a surface that skips it does not get a
+ * quieter gate, it gets a gated tool that silently does nothing (the hole [[EXT-54]] records
+ * against the AG-UI and the old ACP servers). Everything here is the last hop of that gate: the
+ * runner has already decided the call needs a human, and this turns "needs a human" into a request
+ * an editor can put in front of one, then turns the answer back into a decision the runner
+ * understands.
+ *
+ * ## Untrusted text crosses this boundary as DATA, deliberately
+ *
+ * The command, the rater's reason and the escalation provenance are all model- or third-party-
+ * authored. On the terminal surfaces they are painted through `core/shell/framing` because a
+ * carriage return there reaches column 0 and an escape sequence clears the screen. **That renderer
+ * is not applied here, and its absence is not an oversight:** these values leave as JSON fields of
+ * a structured request, and the client draws them in its own UI, where terminal control codes are
+ * inert. Framing them would ship a line-number gutter and box drawing into a GUI. What matters on
+ * this surface is that they stay in their own fields rather than being interpolated into the
+ * prompt's own prose — so a client can style them as untrusted, and nothing the model writes can
+ * impersonate the request's title.
+ */
+import type { PermissionOption, RequestPermissionOutcome, RequestPermissionRequest, SessionId } from '@agentclientprotocol/sdk/experimental/v2';
+import type { PendingToolInterrupt, ToolApprovalDecision } from '@gaunt-sloth/core/core/types.js';
+/**
+ * The four answers offered on every permission request, one per ACP `PermissionOptionKind`.
+ *
+ * The set is fixed rather than computed from what the gate would accept, because a menu that
+ * appears and disappears per call is a menu a user cannot learn. What each one MEANS is in
+ * {@link decisionForOutcome}; the labels say it in words, since a bare kind hint does not tell
+ * anyone what "always" persists to.
+ */
+export declare const ACP_PERMISSION_OPTIONS: readonly PermissionOption[];
+/** The ACP permission request for one pending tool call the gate escalated to a human. */
+export declare function permissionRequestFor(options: {
+    sessionId: SessionId;
+    pending: PendingToolInterrupt;
+    /** The tool call id the update stream already announced for this call, when it is known. */
+    toolCallId?: string;
+    /** The session's working directory — the `cwd` a `command` subject is required to carry. */
+    cwd: string;
+}): RequestPermissionRequest;
+/**
+ * The gate decision an ACP permission outcome means.
+ *
+ * **Every path that is not an explicit allow is a reject**, including an option id we do not
+ * recognise and an outcome variant that postdates this code. That polarity is the whole safety
+ * property: a client that answers with something unexpected must not be able to run a command,
+ * and a future ACP outcome must fail toward refusing rather than toward executing.
+ *
+ * `allow-always` maps to the `always` scope, which persists to the project allow-list — the same
+ * thing the terminal menu's *always approve* does. `reject-always` maps to the `session` scope
+ * because that is the strongest refusal the gate actually persists; ACP's `reject_always` is a UI
+ * hint, and promising a persistence nothing implements would be worse than serving it with the
+ * refusal that does exist. The option's own label says "for this session" so the user is told.
+ */
+export declare function decisionForOutcome(outcome: RequestPermissionOutcome): ToolApprovalDecision;

package/dist/modules/acp/acpPermissions.js

@@ -0,0 +1,158 @@
+/**
+ * @packageDocumentation
+ * Bridges the agent's tool-approval gate to ACP v2's `session/request_permission`.
+ *
+ * **This is the reason the ACP server drives {@link GthAgentRunner} rather than an agent
+ * directly.** The runner is what owns the gate — the bypass check, the allow-list, the AI rater,
+ * the deny list, and finally the human callback — and a surface that skips it does not get a
+ * quieter gate, it gets a gated tool that silently does nothing (the hole [[EXT-54]] records
+ * against the AG-UI and the old ACP servers). Everything here is the last hop of that gate: the
+ * runner has already decided the call needs a human, and this turns "needs a human" into a request
+ * an editor can put in front of one, then turns the answer back into a decision the runner
+ * understands.
+ *
+ * ## Untrusted text crosses this boundary as DATA, deliberately
+ *
+ * The command, the rater's reason and the escalation provenance are all model- or third-party-
+ * authored. On the terminal surfaces they are painted through `core/shell/framing` because a
+ * carriage return there reaches column 0 and an escape sequence clears the screen. **That renderer
+ * is not applied here, and its absence is not an oversight:** these values leave as JSON fields of
+ * a structured request, and the client draws them in its own UI, where terminal control codes are
+ * inert. Framing them would ship a line-number gutter and box drawing into a GUI. What matters on
+ * this surface is that they stay in their own fields rather than being interpolated into the
+ * prompt's own prose — so a client can style them as untrusted, and nothing the model writes can
+ * impersonate the request's title.
+ */
+import { toolKindFor } from '#src/modules/acp/acpUpdates.js';
+/** The gated tool whose argument is a shell command, and so has an ACP `command` subject. */
+const SHELL_TOOL = 'run_shell_command';
+/**
+ * The four answers offered on every permission request, one per ACP `PermissionOptionKind`.
+ *
+ * The set is fixed rather than computed from what the gate would accept, because a menu that
+ * appears and disappears per call is a menu a user cannot learn. What each one MEANS is in
+ * {@link decisionForOutcome}; the labels say it in words, since a bare kind hint does not tell
+ * anyone what "always" persists to.
+ */
+export const ACP_PERMISSION_OPTIONS = [
+    { optionId: 'allow-once', name: 'Allow once', kind: 'allow_once' },
+    { optionId: 'allow-always', name: 'Allow and remember', kind: 'allow_always' },
+    { optionId: 'reject-once', name: 'Reject once', kind: 'reject_once' },
+    { optionId: 'reject-always', name: 'Reject for this session', kind: 'reject_always' },
+];
+/** The shell command a pending call would run, when it is one and it is a plain string. */
+function shellCommandOf(pending) {
+    if (pending.name !== SHELL_TOOL)
+        return undefined;
+    const command = pending.args.command;
+    return typeof command === 'string' ? command : undefined;
+}
+/**
+ * The structured `subject` for a pending call: a `command` subject when the gate stopped a shell
+ * command (so the client can show the command as a command), a `tool_call` subject otherwise.
+ *
+ * `toolCallId` correlates the request with the tool call the client is ALREADY rendering from the
+ * `session/update` stream — the model emits its tool call before the graph suspends on the gate,
+ * so by the time a permission request goes out the client has drawn the call and is waiting on it.
+ * Without the correlation the prompt is about a tool call the client cannot point at.
+ */
+function subjectFor(pending, toolCallId, cwd) {
+    const command = shellCommandOf(pending);
+    if (command !== undefined) {
+        return {
+            type: 'command',
+            command,
+            cwd,
+            ...(toolCallId === undefined ? {} : { toolCallId }),
+        };
+    }
+    return {
+        type: 'tool_call',
+        toolCall: {
+            // A `tool_call` subject has nowhere to put "no id", so a call the update stream never
+            // announced still needs one. It is minted rather than omitted, and it is the same shape a
+            // creating `tool_call_update` would carry, so a client that renders the subject shows the
+            // tool by name instead of an empty row.
+            toolCallId: toolCallId ?? `permission-${pending.name}`,
+            name: pending.name,
+            title: pending.name,
+            kind: toolKindFor(pending.name),
+            status: 'pending',
+            rawInput: pending.args,
+        },
+    };
+}
+/**
+ * The human-readable explanation for the prompt: everything the gate knows about WHY this call
+ * reached a human.
+ *
+ * Assembled from the same three sources the terminal surfaces show — the rater's verdict, the
+ * declared `approvals.escalate` entry that fired, and what a remembered answer would store — for
+ * the same reason: a user asked to rule on a call their configuration should have approved reads
+ * an unexplained prompt as the gate malfunctioning. Empty when the gate has nothing to add, in
+ * which case the field is omitted rather than sent as an empty string.
+ */
+function descriptionFor(pending) {
+    const parts = [];
+    if (pending.safetyVerdict) {
+        parts.push(`AI rater: ${pending.safetyVerdict.outcome} — ${pending.safetyVerdict.reason}`.trimEnd());
+    }
+    if (pending.escalatedBy) {
+        parts.push(`Your approvals.escalate list matched this call: ${pending.escalatedBy}`);
+    }
+    if (pending.grantPreview) {
+        parts.push(`"Allow and remember" will store: ${pending.grantPreview}`);
+    }
+    return parts.length > 0 ? parts.join('\n\n') : undefined;
+}
+/** The ACP permission request for one pending tool call the gate escalated to a human. */
+export function permissionRequestFor(options) {
+    const { sessionId, pending, toolCallId, cwd } = options;
+    const command = shellCommandOf(pending);
+    const description = descriptionFor(pending);
+    return {
+        sessionId,
+        // The title is the AGENT's own words and carries no untrusted text: what the model wrote is in
+        // the subject, where a client can style it as the model's.
+        title: command !== undefined ? 'Run a shell command' : `Run the ${pending.name} tool`,
+        ...(description === undefined ? {} : { description }),
+        subject: subjectFor(pending, toolCallId, cwd),
+        options: [...ACP_PERMISSION_OPTIONS],
+    };
+}
+/**
+ * The gate decision an ACP permission outcome means.
+ *
+ * **Every path that is not an explicit allow is a reject**, including an option id we do not
+ * recognise and an outcome variant that postdates this code. That polarity is the whole safety
+ * property: a client that answers with something unexpected must not be able to run a command,
+ * and a future ACP outcome must fail toward refusing rather than toward executing.
+ *
+ * `allow-always` maps to the `always` scope, which persists to the project allow-list — the same
+ * thing the terminal menu's *always approve* does. `reject-always` maps to the `session` scope
+ * because that is the strongest refusal the gate actually persists; ACP's `reject_always` is a UI
+ * hint, and promising a persistence nothing implements would be worse than serving it with the
+ * refusal that does exist. The option's own label says "for this session" so the user is told.
+ */
+export function decisionForOutcome(outcome) {
+    if (outcome.outcome !== 'selected') {
+        return { type: 'reject', message: 'The client cancelled the permission request.' };
+    }
+    const optionId = outcome.optionId;
+    switch (optionId) {
+        case 'allow-once':
+            return { type: 'approve' };
+        case 'allow-always':
+            return { type: 'approve', scope: 'always' };
+        case 'reject-always':
+            return { type: 'reject', scope: 'session', message: 'The user rejected this tool call.' };
+        case 'reject-once':
+            return { type: 'reject', message: 'The user rejected this tool call.' };
+        default:
+            return {
+                type: 'reject',
+                message: `The client selected an unknown permission option (${String(optionId)}).`,
+            };
+    }
+}
+//# sourceMappingURL=acpPermissions.js.map

package/dist/modules/acp/acpPermissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"acpPermissions.js","sourceRoot":"","sources":["../../../src/modules/acp/acpPermissions.ts"],"names":[],"mappings":"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"}

package/dist/modules/acp/acpStdio.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @packageDocumentation
+ * The stdio entry point both ACP doors go through — the standalone `gaunt-sloth-acp` bin and
+ * `gaunt-sloth --acp-agent`.
+ *
+ * **It is one function on purpose.** Two entry points spelling the same startup twice is how the
+ * doors drift, and the thing that would drift here is not cosmetic: it is the stdout guarantee
+ * below, which is invisible until an editor cannot parse a frame.
+ *
+ * ## stdout belongs to the protocol, and nothing else may touch it
+ *
+ * An ACP host reads JSON-RPC off the agent's stdout. Any other byte there is a framing error, not
+ * a message someone reads — and this codebase writes to stdout constantly: `displayInfo` and
+ * friends go through `console.log`/`console.info`, the streaming path writes to
+ * `process.stdout` directly, and the dev/custom toolkits pipe a child process's stdout through.
+ * A single status line would corrupt the stream.
+ *
+ * So the transport captures the REAL stdout writer first, and then `process.stdout.write` is
+ * redirected to stderr for the life of the process. Everything that thought it was printing to the
+ * user keeps working and lands on stderr, where a host shows it as agent output; the protocol
+ * keeps the channel it needs. Redirecting rather than silencing is deliberate — a warning nobody
+ * can see is how a misconfigured agent looks identical to a working one.
+ */
+import type { AcpAgentAppOptions } from '#src/modules/acp/acpAgentApp.js';
+/** Seams for the tests; production passes nothing. */
+export interface AcpStdioOptions extends AcpAgentAppOptions {
+    /** Byte stream the client writes to. Defaults to the process's stdin. */
+    input?: ReadableStream<Uint8Array>;
+    /**
+     * Byte sink the protocol writes to. Defaults to the process's real stdout, captured before the
+     * redirect below so the redirect cannot swallow the protocol along with everything else.
+     */
+    output?: WritableStream<Uint8Array>;
+}
+/**
+ * Serves ACP v2 over stdio until the client disconnects.
+ *
+ * Resolves when the connection closes, so a bin can `await` it and exit cleanly rather than
+ * holding the event loop open on a socket nobody is reading.
+ */
+export declare function startAcpServer(options?: AcpStdioOptions): Promise<void>;

package/dist/modules/acp/acpStdio.js

@@ -0,0 +1,65 @@
+/**
+ * @packageDocumentation
+ * The stdio entry point both ACP doors go through — the standalone `gaunt-sloth-acp` bin and
+ * `gaunt-sloth --acp-agent`.
+ *
+ * **It is one function on purpose.** Two entry points spelling the same startup twice is how the
+ * doors drift, and the thing that would drift here is not cosmetic: it is the stdout guarantee
+ * below, which is invisible until an editor cannot parse a frame.
+ *
+ * ## stdout belongs to the protocol, and nothing else may touch it
+ *
+ * An ACP host reads JSON-RPC off the agent's stdout. Any other byte there is a framing error, not
+ * a message someone reads — and this codebase writes to stdout constantly: `displayInfo` and
+ * friends go through `console.log`/`console.info`, the streaming path writes to
+ * `process.stdout` directly, and the dev/custom toolkits pipe a child process's stdout through.
+ * A single status line would corrupt the stream.
+ *
+ * So the transport captures the REAL stdout writer first, and then `process.stdout.write` is
+ * redirected to stderr for the life of the process. Everything that thought it was printing to the
+ * user keeps working and lands on stderr, where a host shows it as agent output; the protocol
+ * keeps the channel it needs. Redirecting rather than silencing is deliberate — a warning nobody
+ * can see is how a misconfigured agent looks identical to a working one.
+ */
+import { Readable } from 'node:stream';
+import * as acp from '@agentclientprotocol/sdk/experimental/v2';
+import { announceAcpStart, createAcpAgentApp } from '#src/modules/acp/acpAgentApp.js';
+/**
+ * Sends everything written to `process.stdout` to stderr instead, and returns a sink holding the
+ * ORIGINAL writer.
+ *
+ * The capture must happen before the redirect, and the sink must hold the captured function rather
+ * than reach for `process.stdout.write` at write time — otherwise the transport's own frames go
+ * through the redirect too and the agent talks to itself.
+ */
+function captureStdoutForProtocol() {
+    const writeToRealStdout = process.stdout.write.bind(process.stdout);
+    const writeToStderr = process.stderr.write.bind(process.stderr);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    process.stdout.write = ((chunk, ...rest) => 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    writeToStderr(chunk, ...rest));
+    return new WritableStream({
+        write(chunk) {
+            writeToRealStdout(chunk);
+        },
+    });
+}
+/**
+ * Serves ACP v2 over stdio until the client disconnects.
+ *
+ * Resolves when the connection closes, so a bin can `await` it and exit cleanly rather than
+ * holding the event loop open on a socket nobody is reading.
+ */
+export async function startAcpServer(options = {}) {
+    const { input, output, ...appOptions } = options;
+    // Before anything can print. `announceAcpStart` below is the first thing that tries, and it is
+    // there so the guarantee is exercised on every real start rather than only under test.
+    const protocolOut = output ?? captureStdoutForProtocol();
+    const protocolIn = input ?? Readable.toWeb(process.stdin);
+    const app = createAcpAgentApp(appOptions);
+    const connection = app.connect(acp.ndJsonStream(protocolOut, protocolIn));
+    announceAcpStart();
+    await connection.closed;
+}
+//# sourceMappingURL=acpStdio.js.map

package/dist/modules/acp/acpStdio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"acpStdio.js","sourceRoot":"","sources":["../../../src/modules/acp/acpStdio.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,KAAK,GAAG,MAAM,0CAA0C,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AActF;;;;;;;GAOG;AACH,SAAS,wBAAwB;IAC/B,MAAM,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACpE,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAChE,8DAA8D;IAC9D,OAAO,CAAC,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC,KAAU,EAAE,GAAG,IAAW,EAAE,EAAE;IACrD,8DAA8D;IAC7D,aAAqB,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,CAAgC,CAAC;IACzE,OAAO,IAAI,cAAc,CAAa;QACpC,KAAK,CAAC,KAAK;YACT,iBAAiB,CAAC,KAAK,CAAC,CAAC;QAC3B,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAAO,GAAoB,EAAE;IAChE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,UAAU,EAAE,GAAG,OAAO,CAAC;IACjD,+FAA+F;IAC/F,uFAAuF;IACvF,MAAM,WAAW,GAAG,MAAM,IAAI,wBAAwB,EAAE,CAAC;IACzD,MAAM,UAAU,GAAG,KAAK,IAAK,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAgC,CAAC;IAE1F,MAAM,GAAG,GAAG,iBAAiB,CAAC,UAAU,CAAC,CAAC;IAC1C,MAAM,UAAU,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC,CAAC;IAC1E,gBAAgB,EAAE,CAAC;IACnB,MAAM,UAAU,CAAC,MAAM,CAAC;AAC1B,CAAC"}

package/dist/modules/acp/acpUpdates.d.ts

@@ -0,0 +1,101 @@
+/**
+ * @packageDocumentation
+ * Translates the agent runtime's typed {@link AgentStreamEvent} stream into ACP v2
+ * `session/update` payloads.
+ *
+ * Kept as a pure, stateful-but-transport-free mapper rather than inlined in the request handlers
+ * for two reasons. It is the half of the ACP surface with real logic — message identity, tool-call
+ * upserts, which events open and close a run — so it is the half worth testing without a
+ * connection. And the `session/update` **upsert semantics** live here and nowhere else: what the
+ * mapper omits is what a client must leave unchanged, so a mapper that re-sent a full replacement
+ * on every update would silently erase fields a client had already rendered.
+ *
+ * ## The upsert contract this mapper is written against
+ *
+ * A client applies updates per id, in arrival order: an omitted field leaves the stored value
+ * unchanged, `null` clears it, a concrete value replaces it, and a chunk appends. The first
+ * `tool_call_update` a client sees for a `toolCallId` CREATES the tool call. So the mapper sends
+ * the descriptive fields **once**, on the creating update, and every later update for that call
+ * carries only what actually changed — which is what makes a client's rendering of a running tool
+ * call correct rather than flickering back to a bare id.
+ */
+import type { SessionUpdate, ToolKind } from '@agentclientprotocol/sdk/experimental/v2';
+import type { AgentStreamEvent } from '@gaunt-sloth/core/core/types.js';
+/** The ACP tool kind for a gth tool name; `other` for anything not built in. */
+export declare function toolKindFor(name: string): ToolKind;
+/**
+ * Turns one agent run's event stream into ACP `session/update` payloads.
+ *
+ * One instance per prompt turn: it holds the message identity of the assistant text run and of the
+ * reasoning run, plus the accumulated argument text per tool call. A fresh instance per turn is
+ * what makes a new turn a new `messageId`, which is how a client tells two messages apart.
+ */
+export declare class AcpUpdateMapper {
+    /**
+     * `messageId` of the assistant text message currently being streamed, or `null` when no text run
+     * is open. Cleared whenever something else interrupts the text (a tool call, a reasoning block),
+     * so the text that resumes afterwards is a NEW message rather than an append to the one the
+     * client already considers finished.
+     */
+    private assistantMessageId;
+    /** `messageId` of the reasoning message currently being streamed, or `null` outside one. */
+    private thoughtMessageId;
+    /**
+     * Streamed argument text per tool call id, reassembled from `tool_args` deltas. Held rather than
+     * forwarded per delta because ACP has no argument-delta update: `rawInput` is a whole value, so
+     * it can only be sent once the deltas stop arriving.
+     */
+    private readonly toolArgs;
+    /**
+     * Tool calls the model has requested but which have neither produced a result nor been claimed by
+     * a permission request, in the order they were announced, as `[toolCallId, toolName]`.
+     *
+     * Kept so the approval bridge can name the tool call a permission request is ABOUT. The gate's
+     * `PendingToolInterrupt` carries the tool's name and arguments but no call id — the graph
+     * suspends inside the middleware wrapping the call, which is downstream of where the id lives —
+     * while the client has already drawn that call from this stream. This queue reconnects the two.
+     */
+    private readonly openToolCalls;
+    /**
+     * Takes the id of the unclaimed tool call that matches `name` and `args`, removing it from the
+     * queue, or `undefined` when there is none.
+     *
+     * **Matched on the ARGUMENTS, because position is not a reliable discriminator here.** The
+     * arguments are the one value both sides hold: the gate's `PendingToolInterrupt` carries them, and
+     * this mapper still holds the streamed argument text at claim time (it is only discarded on
+     * `tool_result`, which exists solely on the resumed run).
+     *
+     * **Where the exact match degrades, named rather than implied:** the mapper's side is JSON
+     * reassembled from the model's streamed argument deltas, and a local model that ignores
+     * `disable_parallel_tool_use` can merge sibling calls' buffers into invalid JSON (`{}{}`,
+     * `{"steps":3}{}` — see the AG-UI server's `parseToolArguments` note). {@link parseToolArgs}
+     * deliberately does not carry that path's recovery, so such a payload stays a raw string, matches
+     * nothing, and falls back to position — on exactly the model class most likely to emit sloppy
+     * parallel calls. The fallback is still the best remaining answer and the cost is which row a
+     * client attaches the prompt to, never which command the human rules on.
+     *
+     * **Position was tried and is wrong in both directions**, which is why it is only the fallback.
+     * The runner drains suspended calls as a BATCH — every pending call decided in turn before
+     * anything resumes — so a model emitting two parallel calls of one tool has both open and neither
+     * running. Returning "the most recent" handed BOTH requests the second call's id. But plain
+     * oldest-first is no better in the case that is *normal* at the rated rungs: this method is
+     * reached only from the human-approval callback, which sits behind the gate's earlier exits
+     * (not-gated, deny list, bypass, the hardline floor, the allow list, and the rater's own arms), so
+     * a batch where one call is settled without a human and its sibling escalates leaves the settled
+     * call's id unclaimed at the head of the queue — and oldest-first then hands the request the
+     * wrong one, with every upstream ordering assumption perfectly intact.
+     *
+     * **Consuming is right either way**, and the queue order still decides between two calls whose
+     * arguments are genuinely identical, where either answer is equally true.
+     *
+     * Absent rather than guessed when nothing matches — a permission request pointing at the WRONG
+     * call is worse than one pointing at no call, because a client would then attach the answer to a
+     * call the user never saw.
+     */
+    claimToolCallId(name: string, args?: Record<string, unknown>): string | undefined;
+    /**
+     * The `session/update` payloads one runtime event produces — usually one, sometimes none
+     * (`tool_args`, which only accumulates; the reasoning boundaries, which only move state).
+     */
+    map(event: AgentStreamEvent): SessionUpdate[];
+}