@gaunt-sloth/agent 2.0.0-alpha.37 → 2.0.0-alpha.39

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

@@ -0,0 +1,52 @@
+/**
+ * @packageDocumentation
+ * Gaunt Sloth's ACP (Agent Client Protocol) **v1** agent, built on the official SDK's stable root
+ * export. (`acpAgentApp.ts` is the v2 half; `acpRouter.ts` picks between them.)
+ *
+ * ## Why v1 is served at all
+ *
+ * v1 is ACP's stable protocol; v2 is a draft. Every shipping editor that speaks ACP today speaks
+ * v1 — measured against Zed 1.15.0 stable, whose `initialize` carries `protocolVersion: 1` as a
+ * literal with no setting to change it, and whose build does not compile the draft-v2 API at all.
+ * An agent that serves only v2 cannot open a session with any of them.
+ *
+ * ## The shape is the same; the semantics are not
+ *
+ * The SDK's v1 entry point offers the same fluent app builder as v2 — `acp.agent()` returns an
+ * `AgentApp`, handlers are registered by ACP method name, and `connect()` serves either a transport
+ * or, in tests, a `ClientApp` directly. That similarity is a trap if it is mistaken for sameness.
+ * Four differences decide what this file does, and none of them can be reached by renaming a v2
+ * handler:
+ *
+ * 1. **`session/prompt` answers with the stop reason.** The turn runs INSIDE the request and the
+ *    response is what tells the client it is over. v2 acknowledges immediately and reports the stop
+ *    reason later on an idle `state_update`, which does not exist here.
+ * 2. **A cancelled turn is a `cancelled` stop reason, never an error.** The v1 spec is explicit
+ *    that agents MUST catch the abort their libraries throw and answer with the stop reason,
+ *    because clients show unrecognized errors to the user and a cancellation is not one.
+ * 3. **A FAILED turn is a JSON-RPC error**, because v1's `StopReason` union is closed —
+ *    `end_turn | max_tokens | max_turn_requests | refusal | cancelled` — and none of them means
+ *    "crashed". (This is exactly why v2 needed a custom `_error` reason: there, the response was
+ *    already sent and the notification stream was the only channel left. Here the request is still
+ *    open, so the error belongs in its response, and answering `end_turn` would be a lie.)
+ * 4. **No `session/load`, and no `loadSession` capability.** In v1 that capability means sessions
+ *    survive restarts and can be picked up by another client instance; these sessions live in one
+ *    process and die with it. Clients MUST NOT call `session/load` unless it is advertised, so
+ *    declining to advertise it is the conforming way to say so — and the same goes for
+ *    `sessionCapabilities.resume`. Claiming either would be a promise this agent cannot keep.
+ *
+ * ## What carries over unchanged, because it must
+ *
+ * `session/request_permission` is wired to the approval gate, so [[EXT-54]]'s hole does not reopen
+ * on a second surface; and the process serves ONE workspace, refusing a `session/new` that names a
+ * different directory rather than silently re-rooting a live session's file tools. Both are
+ * properties of this agent rather than of a protocol version, so both hold here exactly as they do
+ * on v2.
+ */
+import * as acp from '@agentclientprotocol/sdk';
+import type { AcpAgentAppOptions } from '#src/modules/acp/acpCommon.js';
+/**
+ * Builds the ACP v1 agent app. Register-and-return only: nothing is connected and no config is
+ * read until a client connects and creates a session.
+ */
+export declare function createAcpV1AgentApp(options?: AcpAgentAppOptions): acp.AgentApp;

package/dist/modules/acp/acpAgentAppV1.js

@@ -0,0 +1,307 @@
+/**
+ * @packageDocumentation
+ * Gaunt Sloth's ACP (Agent Client Protocol) **v1** agent, built on the official SDK's stable root
+ * export. (`acpAgentApp.ts` is the v2 half; `acpRouter.ts` picks between them.)
+ *
+ * ## Why v1 is served at all
+ *
+ * v1 is ACP's stable protocol; v2 is a draft. Every shipping editor that speaks ACP today speaks
+ * v1 — measured against Zed 1.15.0 stable, whose `initialize` carries `protocolVersion: 1` as a
+ * literal with no setting to change it, and whose build does not compile the draft-v2 API at all.
+ * An agent that serves only v2 cannot open a session with any of them.
+ *
+ * ## The shape is the same; the semantics are not
+ *
+ * The SDK's v1 entry point offers the same fluent app builder as v2 — `acp.agent()` returns an
+ * `AgentApp`, handlers are registered by ACP method name, and `connect()` serves either a transport
+ * or, in tests, a `ClientApp` directly. That similarity is a trap if it is mistaken for sameness.
+ * Four differences decide what this file does, and none of them can be reached by renaming a v2
+ * handler:
+ *
+ * 1. **`session/prompt` answers with the stop reason.** The turn runs INSIDE the request and the
+ *    response is what tells the client it is over. v2 acknowledges immediately and reports the stop
+ *    reason later on an idle `state_update`, which does not exist here.
+ * 2. **A cancelled turn is a `cancelled` stop reason, never an error.** The v1 spec is explicit
+ *    that agents MUST catch the abort their libraries throw and answer with the stop reason,
+ *    because clients show unrecognized errors to the user and a cancellation is not one.
+ * 3. **A FAILED turn is a JSON-RPC error**, because v1's `StopReason` union is closed —
+ *    `end_turn | max_tokens | max_turn_requests | refusal | cancelled` — and none of them means
+ *    "crashed". (This is exactly why v2 needed a custom `_error` reason: there, the response was
+ *    already sent and the notification stream was the only channel left. Here the request is still
+ *    open, so the error belongs in its response, and answering `end_turn` would be a lie.)
+ * 4. **No `session/load`, and no `loadSession` capability.** In v1 that capability means sessions
+ *    survive restarts and can be picked up by another client instance; these sessions live in one
+ *    process and die with it. Clients MUST NOT call `session/load` unless it is advertised, so
+ *    declining to advertise it is the conforming way to say so — and the same goes for
+ *    `sessionCapabilities.resume`. Claiming either would be a promise this agent cannot keep.
+ *
+ * ## What carries over unchanged, because it must
+ *
+ * `session/request_permission` is wired to the approval gate, so [[EXT-54]]'s hole does not reopen
+ * on a second surface; and the process serves ONE workspace, refusing a `session/new` that names a
+ * different directory rather than silently re-rooting a live session's file tools. Both are
+ * properties of this agent rather than of a protocol version, so both hold here exactly as they do
+ * on v2.
+ */
+import * as acp from '@agentclientprotocol/sdk';
+import { randomUUID } from 'node:crypto';
+import { resolve as resolvePath } from 'node:path';
+import { HumanMessage } from '@langchain/core/messages';
+import { MemorySaver } from '@langchain/langgraph';
+import { GthAgentRunner } from '@gaunt-sloth/core/core/GthAgentRunner.js';
+import { displayWarning } from '@gaunt-sloth/core/utils/consoleUtils.js';
+import { createResolvers } from '#src/resolvers.js';
+import { resolveAgentFactory } from '#src/core/resolveAgentFactory.js';
+import { AcpV1UpdateMapper } from '#src/modules/acp/acpUpdatesV1.js';
+import { decisionForOutcome } from '#src/modules/acp/acpPermissions.js';
+import { permissionRequestForV1 } from '#src/modules/acp/acpPermissionsV1.js';
+import { ACP_AGENT_NAME, ACP_AGENT_TITLE, CLOSE_TURN_DRAIN_MS, acpStatusCallback, agentVersion, drainWithDeadline, isSameWorkspace, loadConfigForCwd, promptText, resolveAcpSessionCommand, } from '#src/modules/acp/acpCommon.js';
+/**
+ * Resolves with the `cancelled` permission outcome once `signal` aborts, and never otherwise.
+ *
+ * Used to race a permission request that the client may never answer. Resolving rather than
+ * rejecting is deliberate: the caller turns this into a gate DECISION, and a rejection there would
+ * be recorded as the gate failing rather than as the user's turn being stopped.
+ */
+function cancelledWhenAborted(signal) {
+    const cancelled = { outcome: 'cancelled' };
+    if (signal.aborted)
+        return Promise.resolve(cancelled);
+    return new Promise((resolveCancelled) => {
+        signal.addEventListener('abort', () => resolveCancelled(cancelled), { once: true });
+    });
+}
+/**
+ * Builds the ACP v1 agent app. Register-and-return only: nothing is connected and no config is
+ * read until a client connects and creates a session.
+ */
+export function createAcpV1AgentApp(options = {}) {
+    const loadConfig = options.loadConfig ?? loadConfigForCwd;
+    const agentFactoryFor = options.agentFactory ?? ((config) => resolveAgentFactory(config, 'lean'));
+    const sessions = new Map();
+    /** The workspace this process is serving, bound by the first `session/new`. */
+    let workspaceRoot;
+    /**
+     * `session/new` requests that have claimed the workspace and are still building their session.
+     *
+     * Counted so a release can tell "nothing depends on this binding" from "the session that depends
+     * on it does not exist yet". Without it, one `session/new` failing while a concurrent one is still
+     * loading would clear the root out from under the survivor, and a third request could then bind a
+     * different directory — the same race the claim closes, reopened by the cleanup.
+     */
+    let pendingSessions = 0;
+    const releaseWorkspaceIfIdle = () => {
+        if (sessions.size === 0 && pendingSessions === 0)
+            workspaceRoot = undefined;
+    };
+    const sessionOrThrow = (sessionId) => {
+        const session = sessions.get(sessionId);
+        if (!session) {
+            throw acp.RequestError.invalidParams({ sessionId }, `No such session: ${sessionId}. Create one with session/new.`);
+        }
+        return session;
+    };
+    /** Send one `session/update`. Notifications, so nothing here waits on the client. */
+    const sendUpdate = async (session, update) => {
+        await session.client.notify(acp.CLIENT_METHODS.session_update, {
+            sessionId: session.sessionId,
+            update,
+        });
+    };
+    /**
+     * Runs one prompt turn to completion and reports how it ended.
+     *
+     * Never rejects: the caller needs to answer the still-open `session/prompt` request, and it has
+     * to be able to tell a cancellation from a crash to do that. Progress goes out as
+     * `session/update` notifications; the outcome comes back here.
+     */
+    const runTurn = async (session, prompt) => {
+        const mapper = new AcpV1UpdateMapper();
+        const abort = new AbortController();
+        session.abort = abort;
+        session.cancelled = false;
+        try {
+            // Inside the try, so a throw here is reported as a failed turn rather than leaving
+            // `session.abort` set by the prologue above and every later prompt refused as concurrent.
+            const text = promptText(prompt);
+            // No `user_message` echo. v1 replays a conversation only on `session/load`; during a turn the
+            // client already has the message it just sent, and echoing it would draw it twice.
+            //
+            // The gate's last hop. Registered per turn so it closes over THIS turn's mapper, which is
+            // what knows the id of the tool call a permission request is about.
+            session.runner.setToolApprovalCallback(async (pending) => {
+                const asked = session.client.request(acp.CLIENT_METHODS.session_request_permission, permissionRequestForV1({
+                    sessionId: session.sessionId,
+                    pending,
+                    toolCallId: mapper.claimToolCallId(pending.name, pending.args),
+                }), 
+                // The spec's cancellation cascade: when the turn is cancelled, outstanding permission
+                // requests are cancelled too, so the client can take its prompt off the screen instead of
+                // asking about work that has already stopped.
+                { cancellationSignal: abort.signal });
+                // **The abort has to be able to end this wait on its own.** `cancellationSignal` sends the
+                // peer a `$/cancel_request` and then keeps waiting for its answer — cooperative by design.
+                // The spec says a client MUST answer an outstanding permission request with the `cancelled`
+                // outcome, but on v1 a client that does not would wedge the whole connection rather than
+                // just this turn: the `session/prompt` request is still open, so it would never be answered
+                // and the client would hold a pending request forever. (On v2 the prompt was acknowledged
+                // long before, which is why bounding the CLOSE was enough there and is not here.)
+                //
+                // Racing the signal ends the wait locally. `cancelled` is what the spec says the answer
+                // would have been, and {@link decisionForOutcome} turns it into a rejection — the same
+                // fail-closed polarity every other unrecognised answer gets.
+                const outcome = await Promise.race([
+                    asked.then((response) => response.outcome),
+                    cancelledWhenAborted(abort.signal),
+                ]);
+                return decisionForOutcome(outcome);
+            });
+            for await (const event of session.runner.processMessagesWithEvents([new HumanMessage(text)], abort.signal)) {
+                for (const update of mapper.map(event))
+                    await sendUpdate(session, update);
+            }
+            if (session.cancelled || abort.signal.aborted)
+                return { ok: true, stopReason: 'cancelled' };
+            return { ok: true, stopReason: 'end_turn' };
+        }
+        catch (error) {
+            // A cancelled run surfaces as a thrown abort from whatever library noticed the signal first.
+            // The spec is explicit that this MUST NOT reach the client as an error: clients render
+            // unrecognized errors, and a user who pressed stop would be shown a failure for it.
+            if (session.cancelled || abort.signal.aborted)
+                return { ok: true, stopReason: 'cancelled' };
+            const message = error instanceof Error ? error.message : String(error);
+            displayWarning(`ACP session ${session.sessionId}: turn failed — ${message}`);
+            return { ok: false, message };
+        }
+        finally {
+            session.runner.setToolApprovalCallback(null);
+            session.abort = null;
+        }
+    };
+    const closeSession = async (session) => {
+        session.cancelled = true;
+        session.abort?.abort();
+        sessions.delete(session.sessionId);
+        // Wait for the aborted turn to finish unwinding before anything else. `cleanup()` does not do
+        // this — it drops the agent and returns — so releasing the workspace below without the wait
+        // would let a `session/new` for another directory reassign INIT_CWD out from under a turn still
+        // running its last tool call.
+        //
+        // BOUNDED, for the reason CLOSE_TURN_DRAIN_MS gives: a turn parked on a permission request is
+        // waiting on the client, and no abort of ours can force that to settle.
+        await drainWithDeadline(session.turn, CLOSE_TURN_DRAIN_MS);
+        try {
+            await session.runner.cleanup();
+        }
+        catch (error) {
+            displayWarning(`ACP session ${session.sessionId}: cleanup failed — ${error instanceof Error ? error.message : String(error)}`);
+        }
+        releaseWorkspaceIfIdle();
+    };
+    return acp
+        .agent({ name: ACP_AGENT_NAME })
+        .onRequest(acp.AGENT_METHODS.initialize, () => ({
+        // The version the CLIENT asked for, which the router has already checked this app can serve.
+        protocolVersion: acp.PROTOCOL_VERSION,
+        agentInfo: { name: ACP_AGENT_NAME, title: ACP_AGENT_TITLE, version: agentVersion() },
+        agentCapabilities: {
+            // `loadSession` and `sessionCapabilities.resume` are deliberately absent: both promise a
+            // session that outlives the process, and these do not. `promptCapabilities` is absent for
+            // the same reason — omitted means the v1 baseline of text and resource links, which is
+            // exactly what this agent reads; claiming `image`, `audio` or `embeddedContext` would
+            // invite content it can only describe back.
+            sessionCapabilities: { list: {}, close: {} },
+        },
+    }))
+        .onRequest(acp.AGENT_METHODS.session_new, async ({ params, client }) => {
+        const cwd = resolvePath(params.cwd);
+        if (workspaceRoot !== undefined && !isSameWorkspace(workspaceRoot, cwd)) {
+            throw acp.RequestError.invalidParams({ cwd: params.cwd, workspaceRoot }, `This agent process is serving ${workspaceRoot}. Start a separate agent process for ${cwd}.`);
+        }
+        // **Claim the workspace BEFORE the first await, or the check above decides nothing.** Nothing
+        // serialises inbound requests on a stdio connection, so two `session/new` calls naming
+        // different directories would both see an unset root, both suspend on the config load, and
+        // both assign. Testing and assigning either side of an await is not a check.
+        workspaceRoot = cwd;
+        pendingSessions += 1;
+        try {
+            const config = await loadConfig(cwd);
+            const runner = new GthAgentRunner(acpStatusCallback, options.resolvers ?? createResolvers(), agentFactoryFor(config));
+            // The command a run is resolved under decides its toolset, its mode prompt and its
+            // approvals posture. For an editor session that is `acp.mode`, defaulting to `code`.
+            //
+            // **The checkpoint saver is not optional here, even though `init` accepts none.** A gated
+            // tool call suspends the graph on a LangGraph interrupt, and an interrupt with nowhere to
+            // checkpoint throws `MISSING_CHECKPOINTER` instead of asking the client for permission — so
+            // without one every shell command in an editor session fails while the ungated built-ins
+            // keep working. `MemorySaver` is the right lifetime as well as the right shape: these
+            // sessions live in one process and die with it, which is also why `loadSession` is not
+            // advertised.
+            //
+            // **Per session, not per process.** Each session owns its runner, its workspace and the
+            // graphs suspended in it, and `sessions` holds several at once; one shared saver would pool
+            // every session's checkpoint threads, so a `session/close` could clear state another
+            // session is still parked on.
+            await runner.init(resolveAcpSessionCommand(config), config, new MemorySaver());
+            const sessionId = randomUUID();
+            sessions.set(sessionId, {
+                sessionId,
+                cwd,
+                runner,
+                client,
+                abort: null,
+                turn: null,
+                cancelled: false,
+            });
+            return { sessionId };
+        }
+        finally {
+            pendingSessions -= 1;
+            // A `session/new` that never produced a session must not leave the process bound to its
+            // directory — one bad config would otherwise refuse every later session for the life of the
+            // agent.
+            releaseWorkspaceIfIdle();
+        }
+    })
+        .onRequest(acp.AGENT_METHODS.session_list, ({ params }) => {
+        const filter = params.cwd === undefined || params.cwd === null ? undefined : params.cwd;
+        return {
+            sessions: [...sessions.values()]
+                .filter((session) => filter === undefined || session.cwd === resolvePath(filter))
+                .map((session) => ({ sessionId: session.sessionId, cwd: session.cwd })),
+        };
+    })
+        .onRequest(acp.AGENT_METHODS.session_close, async ({ params }) => {
+        // Closing MUST cancel whatever is running, exactly as session/cancel would, before the
+        // session's resources go away.
+        await closeSession(sessionOrThrow(params.sessionId));
+        return {};
+    })
+        .onRequest(acp.AGENT_METHODS.session_prompt, async ({ params }) => {
+        const session = sessionOrThrow(params.sessionId);
+        if (session.abort) {
+            throw acp.RequestError.invalidRequest({ sessionId: params.sessionId }, 'A prompt is already running in this session. Wait for it to answer.');
+        }
+        // Started synchronously and recorded before anything can suspend: `runTurn` assigns
+        // `session.abort` before its first await, and `session.turn` is what a concurrent
+        // `session/close` waits on. A gap here is a close that skips the drain.
+        const turn = runTurn(session, params.prompt);
+        session.turn = turn.then(() => undefined);
+        const outcome = await turn;
+        if (!outcome.ok) {
+            throw acp.RequestError.internalError({ sessionId: session.sessionId }, `The agent could not complete this turn: ${outcome.message}`);
+        }
+        return { stopReason: outcome.stopReason };
+    })
+        .onNotification(acp.AGENT_METHODS.session_cancel, ({ params }) => {
+        const session = sessions.get(params.sessionId);
+        if (!session)
+            return;
+        // Recorded as well as aborted: the abort makes the run stop, and the flag is what makes the
+        // turn answer `cancelled` instead of reading its own truncated stream as a normal finish.
+        session.cancelled = true;
+        session.abort?.abort();
+    });
+}
+//# sourceMappingURL=acpAgentAppV1.js.map

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

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

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

@@ -0,0 +1,167 @@
+/**
+ * @packageDocumentation
+ * The parts of Gaunt Sloth's ACP surface that are the same in **both** protocol dialects.
+ *
+ * The agent serves ACP v1 and ACP v2 from one process (`acpRouter.ts` picks between them on the
+ * first message). Two dialects mean two sets of handlers, and everything that is genuinely about
+ * the protocol version belongs in those. Everything else lives here — the workspace binding's
+ * comparison rule, the config load that roots a session, the version reported in a handshake, the
+ * bounded drain a close waits on, and, most importantly, the **untrusted-attachment fencing** a
+ * prompt goes through.
+ *
+ * **The fencing is here rather than duplicated because a second copy is how one of them ends up
+ * missing an arm.** It is the one piece on this surface that is a security boundary rather than a
+ * convenience: client-supplied names, URIs, descriptions and block types are interpolated into the
+ * same message as the user's own words, and the defang → cap → collapse → fence pipeline is what
+ * keeps them from impersonating the agent's instructions. A dialect that grew its own copy would
+ * be one review away from diverging.
+ */
+import type { GthConfig } from '@gaunt-sloth/core/config.js';
+import type { AgentResolvers, GthAgentFactory, GthCommand, StatusUpdateCallback } from '@gaunt-sloth/core/core/types.js';
+/** How this agent identifies itself in the `initialize` response. */
+export declare const ACP_AGENT_NAME = "gaunt-sloth";
+/** Human-facing name for the same, used where a client shows a title rather than an id. */
+export declare const ACP_AGENT_TITLE = "Gaunt Sloth";
+/**
+ * How long `session/close` waits for an aborted turn to finish unwinding before proceeding anyway.
+ *
+ * **The wait is bounded because it cannot be trusted to end.** A turn parked on
+ * `session/request_permission` is waiting on the CLIENT, and ACP cancellation is cooperative: the
+ * `$/cancel_request` we send settles the promise only when the peer answers it. A client that closes
+ * a session while its own permission prompt is on screen and then never answers would otherwise
+ * leave this handler suspended forever — and `session/close` would never get a response, which is a
+ * worse failure than the narrow re-rooting window the wait exists to close.
+ *
+ * On expiry the close proceeds exactly as it did before the wait existed. So the bound degrades to
+ * the previously accepted behaviour rather than to a hang, and an aborted turn — which unwinds in
+ * milliseconds — is unaffected.
+ */
+export declare const CLOSE_TURN_DRAIN_MS = 2000;
+/** Seams the tests replace; production leaves every one of them at its default. */
+export interface AcpAgentAppOptions {
+    /**
+     * Loads the effective gth config for a session rooted at `cwd`. Defaults to pointing config
+     * discovery at the session workspace and running the normal loader.
+     */
+    loadConfig?: (cwd: string) => Promise<GthConfig>;
+    /**
+     * The agent backend for a session. Defaults to `resolveAgentFactory`, i.e. the lean agent
+     * — the same backend every other command resolves, reached through the same seam rather than
+     * named here, so a future backend choice stays a single edit.
+     */
+    agentFactory?: (config: GthConfig) => GthAgentFactory;
+    /** Tool/content resolvers handed to the runner. Defaults to `createResolvers`. */
+    resolvers?: AgentResolvers;
+}
+/**
+ * Whether two already-resolved absolute paths name the same workspace.
+ *
+ * **Case-insensitive on win32 and nowhere else**, because that is where the answer differs: NTFS is
+ * case-insensitive and case-preserving, so `C:\Foo` and `c:\foo` are one directory and an exact
+ * string compare calls them two — a client that re-sends its own `cwd` with different casing would
+ * be told to start a second agent process for the project it is already in. On POSIX the two really
+ * are different directories and must keep comparing unequal, so the platform is the whole
+ * distinction rather than a workaround for one.
+ *
+ * `platform` is a parameter with the live value as its default so both arms are testable on any
+ * host. Every other bug of this shape in this repo (OPS-27, EXT-38, GS2-42, EXT-16) was a POSIX-only
+ * assertion that passed everywhere except the Windows cell, and a test that can only run on win32
+ * would have the same blind spot pointed the other way.
+ */
+export declare function isSameWorkspace(a: string, b: string, platform?: NodeJS.Platform): boolean;
+/**
+ * Points config discovery — and with it the filesystem toolkit's allowed root, grep's boundary and
+ * the shell tool's spawn directory — at the ACP session's workspace.
+ *
+ * All of them read `getCurrentWorkDir()`, which prefers `INIT_CWD`. In a normal CLI run that is
+ * npm's, and correct. In an editor-spawned agent it is whatever the install shell left behind, and
+ * pointing an agent's file tools at a stale directory is worse than any error: it reads and writes
+ * real files in the wrong project. Setting it to the workspace the CLIENT named replaces a guess
+ * with the one authoritative value, and does it without `process.chdir()`, which in a process
+ * serving several sessions would be a race rather than a fix.
+ */
+export declare function loadConfigForCwd(cwd: string): Promise<GthConfig>;
+/**
+ * The command an ACP session is resolved under — `acp.mode`, defaulting to **`code`**.
+ *
+ * An editor connects to get an agent that can do the job. Resolving its sessions under `chat`
+ * hands it `filesystem: 'read'` and, because `filterDevTools` only builds the toolkit for `code`
+ * and `exec`, no shell and no dev tools at all: a read-only agent in a place nobody asked for one.
+ * `code` is the same default the bare `gth` CLI already resolves to.
+ *
+ * **Why `acp.mode` naming an existing command, and not a `commands.acp` block.** `runner.init`
+ * takes a {@link GthCommand}, and two pieces of tool gating branch on that union — `filterDevTools`
+ * (`command !== 'code' && command !== 'exec'`) and `GthDevToolkit`, which resolves the shell
+ * default for the active mode. An `acp` command would have to join the union and every one of
+ * those branches would have to learn the new member, with a silently wrong default wherever one was
+ * missed. A `mode` whose value is an existing command passes something those branches already
+ * handle. `ask --write` is mapped the same way, to `'code'` at the call boundary, rather than
+ * becoming a command of its own. The return type is what enforces it: a mode that is not a
+ * `GthCommand` does not compile.
+ *
+ * **Both dialects call this**, so the v1 and v2 apps cannot drift on the answer.
+ */
+export declare function resolveAcpSessionCommand(config: GthConfig): GthCommand;
+/**
+ * Status output from a session goes to the console utilities, which this surface has already
+ * routed away from stdout (see `acpStdio.ts`) — stdout belongs to the JSON-RPC framing.
+ *
+ * Only warnings and errors are forwarded. The rest of a run's status chatter is already reported
+ * to the client as `session/update` notifications, where the editor can render it; duplicating it
+ * into the agent's stderr would make the log a second, worse copy of the transcript.
+ */
+export declare const acpStatusCallback: StatusUpdateCallback;
+/**
+ * This build's version, for the `initialize` handshake, or `unknown` when it cannot be read.
+ *
+ * `getSlothVersion()` reads the package manifest under the install dir, which an entry point has
+ * to have registered. Both ACP doors do. It is caught anyway because failing the HANDSHAKE over a
+ * display string would take the whole agent down for a piece of metadata — a host that cannot
+ * connect is a far worse outcome than one that shows an unknown version. The bins' own spec pins
+ * that the real path reports a real version, so this fallback cannot become the normal answer
+ * without something going red.
+ */
+export declare function agentVersion(): string;
+/**
+ * Waits for `work` to settle, giving up after `ms`. Never rejects — the caller is tearing a session
+ * down, and a failure in what it is waiting on changes nothing about that.
+ *
+ * The timer is cleared on the winning path and unreferenced regardless, so a close cannot leave a
+ * pending timer holding the process open.
+ */
+export declare function drainWithDeadline(work: Promise<void> | null, ms: number): Promise<void>;
+/**
+ * The least a prompt content block is guaranteed to be in either dialect.
+ *
+ * v1 and v2 declare their own `ContentBlock` unions and they are not the same type, but every
+ * member of both carries a `type` discriminator and nothing below reads a field without checking
+ * it first. Typing the seam this way is what lets one implementation of the fencing serve both,
+ * which is the point of keeping it here.
+ */
+export interface AcpContentBlockLike {
+    readonly type: string;
+}
+/**
+ * The prompt as the text handed to the model: the user's own words, then — when the client attached
+ * anything else — ONE fenced section describing what arrived.
+ *
+ * **The user's `text` blocks stay unfenced and everything else is fenced.** That split is the whole
+ * design: the text IS the user's instruction and always was, while a resource link's metadata comes
+ * from the editor, the filesystem or an MCP server, and a block's `type` is whatever the client put
+ * on the wire. Interpolating those into the same prose would put attacker-influenceable bytes in
+ * the model's context with no marker of provenance and a structural marker they could forge — the
+ * thing `acpPermissions.ts` says this surface must not do.
+ *
+ * The framing line and the closing reassertion are first-party and sit OUTSIDE the fence, so the
+ * last thing the model reads about the attachments is this agent's own authority rather than the
+ * client's text. That is the same shape `appendMcpServerInstructionsNote` uses, deliberately: a
+ * second shape for the same problem is how one of them ends up missing an arm.
+ */
+export declare function promptText(prompt: readonly AcpContentBlockLike[]): string;
+/**
+ * Kept for the entry points, which announce themselves on stderr before serving.
+ *
+ * Both protocol versions are named because both are served, and the version a host gets is the
+ * one it asks for. A notice claiming a single dialect is how the wrong one ends up believed.
+ */
+export declare function announceAcpStart(): void;