@gaunt-sloth/agent 2.0.0-alpha.9 → 2.0.0-beta.0

package/dist/modules/acp/acpPermissionsV1.js

@@ -0,0 +1,110 @@
+/**
+ * @packageDocumentation
+ * Bridges the agent's tool-approval gate to ACP **v1**'s `session/request_permission`.
+ * (`acpPermissions.ts` is the v2 half and carries the reasoning both share.)
+ *
+ * **The gate must reach a human on this surface too.** [[EXT-54]] records what happens otherwise:
+ * a server that wires no approval callback does not get a quieter gate, it gets a gated tool that
+ * silently does nothing. A new dialect is a new surface, and the hole reopens per surface unless
+ * each one answers it.
+ *
+ * ## What v1 has instead of v2's `subject`
+ *
+ * v2 carries a request-level `title`, an optional `description`, and a structured `subject` that
+ * can say "this is a shell command, here it is, and here is its cwd". **v1 has none of those**: a
+ * `RequestPermissionRequest` is a session id, a `ToolCallUpdate`, and the options. So:
+ *
+ * - the command travels as `rawInput`, which is where a v1 client reads a tool call's arguments;
+ * - the gate's explanation — the rater's verdict, the escalation entry that fired, what a
+ *   remembered answer would store — travels as the tool call's `content`, the only free-text field
+ *   in the request. Dropping it is not an option: a user asked to rule on a call their own
+ *   configuration should have approved reads an unexplained prompt as the gate malfunctioning.
+ *
+ * The `toolCall` field is an UPSERT against the call the client is already rendering, so every
+ * descriptive field is sent with the same values the creating `tool_call` update carried. Re-sending
+ * them is a no-op for a call the client knows, and it is what lets the request stand on its own for
+ * a call the client has never seen — which is what a minted id means.
+ *
+ * ## 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, and they are not painted through `core/shell/framing` here. That 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, and framing them would ship a line-number gutter into
+ * a GUI. What matters is that they stay in their own fields rather than being interpolated into the
+ * prompt's own prose, so nothing the model writes can impersonate the request itself.
+ */
+import { ACP_PERMISSION_OPTIONS } from '#src/modules/acp/acpPermissions.js';
+import { toolKindFor } from '#src/modules/acp/acpToolCalls.js';
+/** The gated tool whose argument is a shell command. */
+const SHELL_TOOL = 'run_shell_command';
+/**
+ * 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, for the same reason. Empty when
+ * the gate has nothing to add, in which case no content is attached rather than an empty block.
+ */
+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 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;
+}
+/** One tool-call content entry wrapping a line of text. */
+function toolText(text) {
+    return { type: 'content', content: { type: 'text', text } };
+}
+/**
+ * What the request puts in front of the human, beyond the tool's name and arguments.
+ *
+ * The command comes first when there is one: v2 can say "this is a command" structurally and v1
+ * cannot, so on this dialect the only way to put it where a person ruling on it will read it is to
+ * spell it out. The gate's own explanation follows.
+ */
+function explanationFor(pending) {
+    const command = shellCommandOf(pending);
+    const description = descriptionFor(pending);
+    return [
+        ...(command === undefined ? [] : [toolText(`Shell command: ${command}`)]),
+        ...(description === undefined ? [] : [toolText(description)]),
+    ];
+}
+/** The ACP v1 permission request for one pending tool call the gate escalated to a human. */
+export function permissionRequestForV1(options) {
+    const { sessionId, pending, toolCallId } = options;
+    const content = explanationFor(pending);
+    return {
+        sessionId,
+        toolCall: {
+            // A request about a call the update stream never announced still needs an id. It is minted
+            // rather than omitted — the field is required — and carries the same descriptive fields a
+            // creating update would, so the client renders the tool by name instead of an empty row.
+            toolCallId: toolCallId ?? `permission-${pending.name}`,
+            name: pending.name,
+            // The SAME title the creating update sent. This request is an upsert against a call the
+            // client is already drawing, so a different title here would rename that row mid-flight.
+            title: pending.name,
+            kind: toolKindFor(pending.name),
+            status: 'pending',
+            rawInput: pending.args,
+            ...(content.length === 0 ? {} : { content }),
+        },
+        options: [...ACP_PERMISSION_OPTIONS],
+    };
+}
+//# sourceMappingURL=acpPermissionsV1.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"acpPermissionsV1.js","sourceRoot":"","sources":["../../../src/modules/acp/acpPermissionsV1.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAQH,OAAO,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AAC5E,OAAO,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AAE/D,wDAAwD;AACxD,MAAM,UAAU,GAAG,mBAAmB,CAAC;AAEvC;;;;;;GAMG;AACH,SAAS,cAAc,CAAC,OAA6B;IACnD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;QAC1B,KAAK,CAAC,IAAI,CACR,aAAa,OAAO,CAAC,aAAa,CAAC,OAAO,MAAM,OAAO,CAAC,aAAa,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,CACzF,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;QACxB,KAAK,CAAC,IAAI,CAAC,mDAAmD,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IACvF,CAAC;IACD,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;QACzB,KAAK,CAAC,IAAI,CAAC,oCAAoC,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IACzE,CAAC;IACD,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3D,CAAC;AAED,2FAA2F;AAC3F,SAAS,cAAc,CAAC,OAA6B;IACnD,IAAI,OAAO,CAAC,IAAI,KAAK,UAAU;QAAE,OAAO,SAAS,CAAC;IAClD,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC;IACrC,OAAO,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3D,CAAC;AAED,2DAA2D;AAC3D,SAAS,QAAQ,CAAC,IAAY;IAC5B,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC;AAC9D,CAAC;AAED;;;;;;GAMG;AACH,SAAS,cAAc,CAAC,OAA6B;IACnD,MAAM,OAAO,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IACxC,MAAM,WAAW,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IAC5C,OAAO;QACL,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,kBAAkB,OAAO,EAAE,CAAC,CAAC,CAAC;QACzE,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC;KAC9D,CAAC;AACJ,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,sBAAsB,CAAC,OAKtC;IACC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;IACnD,MAAM,OAAO,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IACxC,OAAO;QACL,SAAS;QACT,QAAQ,EAAE;YACR,2FAA2F;YAC3F,0FAA0F;YAC1F,yFAAyF;YACzF,UAAU,EAAE,UAAU,IAAI,cAAc,OAAO,CAAC,IAAI,EAAE;YACtD,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,wFAAwF;YACxF,yFAAyF;YACzF,KAAK,EAAE,OAAO,CAAC,IAAI;YACnB,IAAI,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC;YAC/B,MAAM,EAAE,SAAS;YACjB,QAAQ,EAAE,OAAO,CAAC,IAAI;YACtB,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC;SAC7C;QACD,OAAO,EAAE,CAAC,GAAG,sBAAsB,CAAC;KACrC,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,41 @@
+/**
+ * @packageDocumentation
+ * Picks the ACP dialect a connection gets, from the connection itself.
+ *
+ * ## The problem, and why the SDK solves it rather than us
+ *
+ * There is one stdio connection and the protocol version is knowable only from the first
+ * `initialize` — which is also the first thing the chosen app has to handle. So a dispatcher has to
+ * read a message it is not allowed to consume, and pushing it back onto a `ReadableStream` is the
+ * part that is awkward to do correctly.
+ *
+ * `@agentclientprotocol/sdk` already does exactly this. {@link acp.agentProtocolRouter} takes the
+ * first wire item, requires it to be an `initialize`, selects the highest configured version that
+ * does not exceed the client's requested one, and re-enqueues the request into a fresh readable in
+ * front of the rest of the stream. Nothing later is touched. Using it means the sniff, the pushback
+ * and the not-configured / not-an-initialize error paths are the SDK's problem, on the same pinned
+ * version as the two apps it routes between.
+ *
+ * It is exported from the `experimental/v2` entry point rather than from `experimental/server` —
+ * `AcpServer` there is an HTTP/WebSocket transport and does not route by version.
+ *
+ * ## What each side gets
+ *
+ * A client asking for **1** reaches the v1 app; a client asking for **2 or higher** reaches the v2
+ * app. Neither app sees the other's traffic and neither is a translation layer over the other:
+ * `acpAgentAppV1.ts` and `acpAgentApp.ts` implement their own dialects, which differ in more than
+ * naming (see either module's doc).
+ *
+ * A version below 1 gets the SDK's `unsupported ACP protocol version` error, which is the honest
+ * answer — there is no ACP dialect this agent could serve such a client in.
+ */
+import * as acp from '@agentclientprotocol/sdk/experimental/v2';
+import type { AcpAgentAppOptions } from '#src/modules/acp/acpCommon.js';
+/**
+ * Builds the version-dispatching front door: both apps, wired behind one connector.
+ *
+ * `options` reaches both apps unchanged, so a caller cannot end up with a configured v2 surface and
+ * a default v1 one — a divergence that would show up only against whichever client the tests do not
+ * use.
+ */
+export declare function createAcpAgentRouter(options?: AcpAgentAppOptions): acp.AgentProtocolRouter;

package/dist/modules/acp/acpRouter.js

@@ -0,0 +1,48 @@
+/**
+ * @packageDocumentation
+ * Picks the ACP dialect a connection gets, from the connection itself.
+ *
+ * ## The problem, and why the SDK solves it rather than us
+ *
+ * There is one stdio connection and the protocol version is knowable only from the first
+ * `initialize` — which is also the first thing the chosen app has to handle. So a dispatcher has to
+ * read a message it is not allowed to consume, and pushing it back onto a `ReadableStream` is the
+ * part that is awkward to do correctly.
+ *
+ * `@agentclientprotocol/sdk` already does exactly this. {@link acp.agentProtocolRouter} takes the
+ * first wire item, requires it to be an `initialize`, selects the highest configured version that
+ * does not exceed the client's requested one, and re-enqueues the request into a fresh readable in
+ * front of the rest of the stream. Nothing later is touched. Using it means the sniff, the pushback
+ * and the not-configured / not-an-initialize error paths are the SDK's problem, on the same pinned
+ * version as the two apps it routes between.
+ *
+ * It is exported from the `experimental/v2` entry point rather than from `experimental/server` —
+ * `AcpServer` there is an HTTP/WebSocket transport and does not route by version.
+ *
+ * ## What each side gets
+ *
+ * A client asking for **1** reaches the v1 app; a client asking for **2 or higher** reaches the v2
+ * app. Neither app sees the other's traffic and neither is a translation layer over the other:
+ * `acpAgentAppV1.ts` and `acpAgentApp.ts` implement their own dialects, which differ in more than
+ * naming (see either module's doc).
+ *
+ * A version below 1 gets the SDK's `unsupported ACP protocol version` error, which is the honest
+ * answer — there is no ACP dialect this agent could serve such a client in.
+ */
+import * as acp from '@agentclientprotocol/sdk/experimental/v2';
+import { createAcpAgentApp } from '#src/modules/acp/acpAgentApp.js';
+import { createAcpV1AgentApp } from '#src/modules/acp/acpAgentAppV1.js';
+/**
+ * Builds the version-dispatching front door: both apps, wired behind one connector.
+ *
+ * `options` reaches both apps unchanged, so a caller cannot end up with a configured v2 surface and
+ * a default v1 one — a divergence that would show up only against whichever client the tests do not
+ * use.
+ */
+export function createAcpAgentRouter(options = {}) {
+    return acp
+        .agentProtocolRouter()
+        .withV1(createAcpV1AgentApp(options))
+        .withV2(createAcpAgentApp(options));
+}
+//# sourceMappingURL=acpRouter.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"acpRouter.js","sourceRoot":"","sources":["../../../src/modules/acp/acpRouter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,GAAG,MAAM,0CAA0C,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AAGxE;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAO,GAAuB,EAAE;IACnE,OAAO,GAAG;SACP,mBAAmB,EAAE;SACrB,MAAM,CAAC,mBAAmB,CAAC,OAAO,CAAC,CAAC;SACpC,MAAM,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC;AACxC,CAAC"}

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

@@ -0,0 +1,47 @@
+/**
+ * @packageDocumentation
+ * The stdio entry point both ACP doors go through — the standalone `gaunt-sloth-acp` bin and
+ * `gaunt-sloth --acp-agent` — serving whichever protocol version the client speaks.
+ *
+ * **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/acpCommon.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 over stdio until the client disconnects, in whichever protocol version the client
+ * asks for on its first message.
+ *
+ * The dialect is not chosen here and is not configurable: `acpRouter.ts` reads it off the
+ * `initialize` and hands the connection to the matching app. A flag would be the wrong shape —
+ * an editor spawns this command with no arguments, so a version it had to be told would be a
+ * version it never gets.
+ *
+ * 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,71 @@
+/**
+ * @packageDocumentation
+ * The stdio entry point both ACP doors go through — the standalone `gaunt-sloth-acp` bin and
+ * `gaunt-sloth --acp-agent` — serving whichever protocol version the client speaks.
+ *
+ * **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 } from '#src/modules/acp/acpCommon.js';
+import { createAcpAgentRouter } from '#src/modules/acp/acpRouter.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 over stdio until the client disconnects, in whichever protocol version the client
+ * asks for on its first message.
+ *
+ * The dialect is not chosen here and is not configurable: `acpRouter.ts` reads it off the
+ * `initialize` and hands the connection to the matching app. A flag would be the wrong shape —
+ * an editor spawns this command with no arguments, so a version it had to be told would be a
+ * version it never gets.
+ *
+ * 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 connection = createAcpAgentRouter(appOptions).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,MAAM,+BAA+B,CAAC;AAEjE,OAAO,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAarE;;;;;;;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;;;;;;;;;;;GAWG;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,UAAU,GAAG,oBAAoB,CAAC,UAAU,CAAC,CAAC,OAAO,CACzD,GAAG,CAAC,YAAY,CAAC,WAAW,EAAE,UAAU,CAAC,CAC1C,CAAC;IACF,gBAAgB,EAAE,CAAC;IACnB,MAAM,UAAU,CAAC,MAAM,CAAC;AAC1B,CAAC"}

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

@@ -0,0 +1,93 @@
+/**
+ * @packageDocumentation
+ * Tool-call identity, shared by both ACP dialects.
+ *
+ * The two dialects disagree about how a tool call is REPORTED — v1 has a distinct `tool_call`
+ * update that creates one and a `tool_call_update` that patches it, v2 folds creation into the
+ * first `tool_call_update` — but they agree completely about what a tool call IS. The kind hint, the
+ * reassembly of streamed argument deltas, and the pairing of a permission request with the call it
+ * is about are the same problem on both surfaces, so they are solved once here.
+ *
+ * **The pairing especially.** {@link AcpToolCallTracker.claimToolCallId} is the piece that took
+ * three attempts to get right, and a second copy of it living in the other dialect's mapper is how
+ * one of them silently regresses to attaching a permission prompt to the wrong row.
+ */
+import type { ToolKind } from '@agentclientprotocol/sdk';
+/**
+ * The ACP tool kind for a gth tool name; `other` for anything not built in.
+ *
+ * Typed against **v1's** `ToolKind`, which is the closed union of the ten defined kinds; v2 widens
+ * the same union with a catch-all for future values. Typing against the stricter one is what lets a
+ * single function serve both — a v1 kind is always a valid v2 kind, and the reverse is not true.
+ */
+export declare function toolKindFor(name: string): ToolKind;
+/**
+ * Tracks the tool calls a turn has opened, so a permission request can name the one it is about.
+ *
+ * A dialect's update mapper extends this and keeps the fields fed: {@link trackToolStart} when the
+ * model announces a call, {@link appendToolArgs} for each argument delta, {@link trackToolSettled}
+ * when a result lands.
+ */
+export declare abstract class AcpToolCallTracker {
+    /**
+     * 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.
+     */
+    protected readonly toolArgs: Map<string, string>;
+    /**
+     * 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.
+     */
+    protected readonly openToolCalls: Array<[string, string]>;
+    /** Records a newly announced call and opens its argument buffer. */
+    protected trackToolStart(id: string, name: string): void;
+    /** Accumulates one streamed argument delta. */
+    protected appendToolArgs(id: string, delta: string): void;
+    /** The reassembled arguments for a call, as a value for `rawInput`. */
+    protected rawInputFor(id: string): unknown;
+    /** Forgets a call that has produced its result. */
+    protected trackToolSettled(id: string): void;
+    /**
+     * 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 tracker 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:** this 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;
+}

package/dist/modules/acp/acpToolCalls.js

@@ -0,0 +1,193 @@
+/**
+ * @packageDocumentation
+ * Tool-call identity, shared by both ACP dialects.
+ *
+ * The two dialects disagree about how a tool call is REPORTED — v1 has a distinct `tool_call`
+ * update that creates one and a `tool_call_update` that patches it, v2 folds creation into the
+ * first `tool_call_update` — but they agree completely about what a tool call IS. The kind hint, the
+ * reassembly of streamed argument deltas, and the pairing of a permission request with the call it
+ * is about are the same problem on both surfaces, so they are solved once here.
+ *
+ * **The pairing especially.** {@link AcpToolCallTracker.claimToolCallId} is the piece that took
+ * three attempts to get right, and a second copy of it living in the other dialect's mapper is how
+ * one of them silently regresses to attaching a permission prompt to the wrong row.
+ */
+/**
+ * ACP tool KIND for a gth tool name — the hint a client uses to pick an icon and a UI treatment.
+ *
+ * Matched by exact name, with `other` as the fallback, because a wrong kind is worse than a
+ * generic one: a client that shows a delete glyph for a read is actively misleading about what the
+ * agent is doing. Unknown names (custom tools, MCP tools) therefore land on `other` rather than
+ * being guessed at from substrings.
+ */
+const TOOL_KINDS = {
+    create_directory: 'edit',
+    delete_directory: 'delete',
+    delete_file: 'delete',
+    directory_tree: 'read',
+    edit_file: 'edit',
+    get_file_info: 'read',
+    gth_read_binary: 'read',
+    gth_status_update: 'think',
+    gth_web_fetch: 'fetch',
+    list_allowed_directories: 'read',
+    list_directory: 'read',
+    list_directory_with_sizes: 'read',
+    move_file: 'move',
+    read_file: 'read',
+    read_multiple_files: 'read',
+    run_build: 'execute',
+    run_lint: 'execute',
+    run_shell_command: 'execute',
+    run_single_test: 'execute',
+    run_tests: 'execute',
+    search_files: 'search',
+    write_file: 'edit',
+};
+/**
+ * The ACP tool kind for a gth tool name; `other` for anything not built in.
+ *
+ * Typed against **v1's** `ToolKind`, which is the closed union of the ten defined kinds; v2 widens
+ * the same union with a catch-all for future values. Typing against the stricter one is what lets a
+ * single function serve both — a v1 kind is always a valid v2 kind, and the reverse is not true.
+ */
+export function toolKindFor(name) {
+    return TOOL_KINDS[name] ?? 'other';
+}
+/**
+ * Tracks the tool calls a turn has opened, so a permission request can name the one it is about.
+ *
+ * A dialect's update mapper extends this and keeps the fields fed: {@link trackToolStart} when the
+ * model announces a call, {@link appendToolArgs} for each argument delta, {@link trackToolSettled}
+ * when a result lands.
+ */
+export class AcpToolCallTracker {
+    /**
+     * 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.
+     */
+    toolArgs = new Map();
+    /**
+     * 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.
+     */
+    openToolCalls = [];
+    /** Records a newly announced call and opens its argument buffer. */
+    trackToolStart(id, name) {
+        this.toolArgs.set(id, '');
+        this.openToolCalls.push([id, name]);
+    }
+    /** Accumulates one streamed argument delta. */
+    appendToolArgs(id, delta) {
+        this.toolArgs.set(id, (this.toolArgs.get(id) ?? '') + delta);
+    }
+    /** The reassembled arguments for a call, as a value for `rawInput`. */
+    rawInputFor(id) {
+        return parseToolArgs(this.toolArgs.get(id));
+    }
+    /** Forgets a call that has produced its result. */
+    trackToolSettled(id) {
+        this.toolArgs.delete(id);
+        // A call a permission request already claimed is no longer in the queue; that is expected,
+        // not a miss.
+        const open = this.openToolCalls.findIndex(([openId]) => openId === id);
+        if (open >= 0)
+            this.openToolCalls.splice(open, 1);
+    }
+    /**
+     * 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 tracker 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:** this 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, args) {
+        const candidates = this.openToolCalls
+            .map(([id, toolName], index) => ({ id, toolName, index }))
+            .filter((candidate) => candidate.toolName === name);
+        if (candidates.length === 0)
+            return undefined;
+        const wanted = args === undefined ? undefined : canonicalJson(args);
+        const matched = wanted === undefined
+            ? undefined
+            : candidates.find((candidate) => canonicalJson(parseToolArgs(this.toolArgs.get(candidate.id))) === wanted);
+        const chosen = matched ?? candidates[0];
+        this.openToolCalls.splice(chosen.index, 1);
+        return chosen.id;
+    }
+}
+/**
+ * A value serialized with object keys in sorted order, so two arguments objects that differ only in
+ * key order compare equal.
+ *
+ * They routinely do: one side is JSON reassembled from a model's streamed argument deltas and the
+ * other is the object the graph handed the gate. Comparing raw `JSON.stringify` output would make
+ * the exact match in {@link AcpToolCallTracker.claimToolCallId} fail for a reason that has nothing
+ * to do with whether the two describe the same call.
+ */
+function canonicalJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'undefined';
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    const entries = Object.keys(value)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`);
+    return `{${entries.join(',')}}`;
+}
+/**
+ * The reassembled tool arguments as a value for `rawInput`, or `undefined` when there is nothing
+ * worth sending.
+ *
+ * Deliberately fail-soft: a model that emits malformed argument JSON is a real and recurring
+ * condition (see the AG-UI server's `parseToolArguments` note), and it must not take down the turn
+ * that reports it. An unparseable payload is passed through as the raw string so the client can
+ * still show what the model asked for.
+ */
+function parseToolArgs(raw) {
+    const text = (raw ?? '').trim();
+    if (text.length === 0)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+//# sourceMappingURL=acpToolCalls.js.map

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

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