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

package/dist/modules/acp/acpAgentApp.js

@@ -0,0 +1,378 @@
+/**
+ * @packageDocumentation
+ * Gaunt Sloth's ACP (Agent Client Protocol) **v2** agent, built on the official SDK's
+ * `experimental/v2` surface.
+ *
+ * ## One of two dialects
+ *
+ * v1 is ACP's stable protocol and v2 is a draft, and the agent serves **both**: `acpRouter.ts`
+ * reads the `protocolVersion` on the first `initialize` and hands the connection to the matching
+ * app, so a host gets the dialect it asked for. This file is the v2 half; `acpAgentAppV1.ts` is
+ * the v1 half. Serving only v2 would cut the surface off from every shipping editor that speaks
+ * ACP today — measured against Zed 1.15.0 stable, which sends `protocolVersion: 1` as a literal
+ * with no setting to change it.
+ *
+ * ## Shape
+ *
+ * v2's agent side is a fluent app builder: `acp.agent()` returns an {@link AgentApp} on which
+ * typed handlers are registered by ACP method name, and `connect()` serves a client — either over
+ * a transport stream or, for tests, directly against a `ClientApp`. The SDK's v1 entry point offers
+ * the same builder, which is why the two dialects read alike even though their handlers differ.
+ *
+ * ## The prompt lifecycle is the part that looks wrong until you read the spec
+ *
+ * This is also the sharpest difference from v1, which answers the prompt request with the stop
+ * reason itself. In v2 `session/prompt` returns `{}` **as soon as the prompt is accepted** — not
+ * when the turn finishes.
+ * Progress, tool calls and the final stop reason all arrive as `session/update` notifications, and
+ * the turn is over when an idle `state_update` carrying a stop reason lands. That is what makes
+ * cancellation expressible at all: a cancelled turn reports `cancelled` on a `state_update`, while
+ * the prompt request it belongs to was answered long before. A client that waited on the prompt
+ * response for the result would hang through every tool call.
+ *
+ * ## Why a runner and not an agent
+ *
+ * Each session drives a {@link GthAgentRunner}, not a bare agent. The runner is where the
+ * tool-approval gate lives, so this is also the surface where `session/request_permission` is
+ * wired — see `acpPermissions.ts` for why that is not optional.
+ *
+ * ## One workspace per process
+ *
+ * Config discovery, the filesystem tools' allowed root, grep and the shell tool ALL resolve
+ * through `getCurrentWorkDir()`, a process-global. So the workspace is bound by the first
+ * `session/new` and a later `session/new` naming a different `cwd` is refused rather than served
+ * from the wrong root. An editor spawns one agent process per project, which is exactly the shape
+ * this serves; the alternative — letting the second session silently re-root the first session's
+ * tools — is the kind of quiet wrongness that is worse than an error a host can report.
+ */
+import * as acp from '@agentclientprotocol/sdk/experimental/v2';
+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 { AcpUpdateMapper } from '#src/modules/acp/acpUpdates.js';
+import { decisionForOutcome, permissionRequestFor } from '#src/modules/acp/acpPermissions.js';
+import { ACP_AGENT_NAME, ACP_AGENT_TITLE, CLOSE_TURN_DRAIN_MS, acpStatusCallback, agentVersion, announceAcpStart, drainWithDeadline, isSameWorkspace, loadConfigForCwd, promptText, resolveAcpSessionCommand, } from '#src/modules/acp/acpCommon.js';
+export { ACP_AGENT_NAME, ACP_AGENT_TITLE, announceAcpStart, isSameWorkspace };
+/**
+ * Builds the ACP v2 agent app. Register-and-return only: nothing is connected and no config is
+ * read until a client connects and creates a session.
+ */
+export function createAcpAgentApp(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;
+    /**
+     * Release the workspace binding when nothing — live or in flight — still depends on it.
+     *
+     * The binding exists to stop a second workspace re-rooting a LIVE session's tools; with no session
+     * and nothing building one there is nothing to re-root, and holding it would refuse a workspace
+     * for no reason left.
+     */
+    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,
+        });
+    };
+    const sendState = async (session, state) => {
+        await sendUpdate(session, { sessionUpdate: 'state_update', ...state });
+    };
+    /**
+     * Runs one prompt turn to completion and reports it entirely through notifications.
+     *
+     * Never rejects: this is started detached from the `session/prompt` request (which has already
+     * been answered), so a throw here would be an unhandled rejection rather than an error anyone
+     * sees. Every exit — success, cancellation, failure — ends on an idle `state_update` with a stop
+     * reason, because that notification is the ONLY thing that tells a client the turn is over.
+     */
+    const runTurn = async (session, prompt) => {
+        const mapper = new AcpUpdateMapper();
+        const abort = new AbortController();
+        session.abort = abort;
+        session.cancelled = false;
+        const text = promptText(prompt);
+        const userMessageId = randomUUID();
+        /** Assistant text accumulated per message id, so the replay log can carry whole messages. */
+        const assistantText = new Map();
+        let stopReason = 'end_turn';
+        try {
+            // The spec's step 2: after accepting the prompt, report where the user message landed.
+            const userMessage = {
+                sessionUpdate: 'user_message',
+                messageId: userMessageId,
+                content: prompt,
+            };
+            session.replayLog.push(userMessage);
+            await sendUpdate(session, userMessage);
+            await sendState(session, { state: 'running' });
+            // 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) => {
+                await sendState(session, { state: 'requires_action' }).catch(() => undefined);
+                try {
+                    const response = await session.client.request(acp.CLIENT_METHODS.session_request_permission, permissionRequestFor({
+                        sessionId: session.sessionId,
+                        pending,
+                        toolCallId: mapper.claimToolCallId(pending.name, pending.args),
+                        cwd: session.cwd,
+                    }), 
+                    // 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. Cooperative by design — the promise
+                    // still settles on the peer's eventual answer — which is why `session/close` bounds its
+                    // wait rather than trusting this to end it.
+                    { cancellationSignal: abort.signal });
+                    return decisionForOutcome(response.outcome);
+                }
+                finally {
+                    // Never allowed to become the callback's result. A notification that fails — the usual
+                    // reason being the connection going away mid-prompt — must not turn a decision the human
+                    // actually made into an error the runner records as a failed gate.
+                    await sendState(session, { state: 'running' }).catch(() => undefined);
+                }
+            });
+            for await (const event of session.runner.processMessagesWithEvents([new HumanMessage(text)], abort.signal)) {
+                for (const update of mapper.map(event)) {
+                    if (update.sessionUpdate === 'agent_message_chunk') {
+                        const chunk = update;
+                        assistantText.set(chunk.messageId, (assistantText.get(chunk.messageId) ?? '') + (chunk.content.text ?? ''));
+                    }
+                    if (update.sessionUpdate === 'tool_call_update') {
+                        session.replayLog.push(update);
+                    }
+                    await sendUpdate(session, update);
+                }
+            }
+            if (session.cancelled || abort.signal.aborted)
+                stopReason = 'cancelled';
+        }
+        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 a generic failure, or a client
+            // shows an error for something the user asked for.
+            if (session.cancelled || abort.signal.aborted) {
+                stopReason = 'cancelled';
+            }
+            else {
+                // NOT `refusal`, which the spec defines as the agent declining to continue — a crash is
+                // not a refusal, and a client would render it as one. v2 reserves custom stop reasons to
+                // names beginning with an underscore, so this is the sanctioned way to say "stopped, and
+                // none of the defined reasons is what happened".
+                stopReason = '_error';
+                const message = error instanceof Error ? error.message : String(error);
+                displayWarning(`ACP session ${session.sessionId}: turn failed — ${message}`);
+                await sendUpdate(session, {
+                    sessionUpdate: 'agent_message',
+                    messageId: randomUUID(),
+                    content: [{ type: 'text', text: `The agent could not complete this turn: ${message}` }],
+                }).catch(() => {
+                    /* the connection is already gone; the idle state below is still attempted */
+                });
+            }
+        }
+        finally {
+            session.runner.setToolApprovalCallback(null);
+            session.abort = null;
+            // `turn` is deliberately NOT cleared here: this runs inside the promise it holds, so clearing
+            // it would let a `session/close` that reads the field in that instant skip the wait entirely.
+            // A settled promise is harmless to await and the next prompt replaces it.
+            for (const [messageId, content] of assistantText) {
+                if (content.length > 0) {
+                    session.replayLog.push({
+                        sessionUpdate: 'agent_message',
+                        messageId,
+                        content: [{ type: 'text', text: content }],
+                    });
+                }
+            }
+            // The turn is over only once this lands, whatever happened above.
+            await sendState(session, { state: 'idle', stopReason }).catch(() => {
+                /* connection closed mid-turn; nothing left to report to */
+            });
+        }
+    };
+    const closeSession = async (session) => {
+        session.closed = true;
+        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. That is precisely the "re-rooting a live session's tools" hazard
+        // the binding exists to prevent, so the release must not be the thing that opens it.
+        //
+        // BOUNDED, for the reason {@link 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, () => ({
+        protocolVersion: acp.PROTOCOL_VERSION,
+        info: { name: ACP_AGENT_NAME, title: ACP_AGENT_TITLE, version: agentVersion() },
+        // `session: {}` claims the baseline session surface and nothing more. Per the v2
+        // initialization spec the baseline is `session/new`, `session/list`, `session/resume`,
+        // `session/close`, `session/prompt`, `session/cancel` and `session/update` — which is
+        // exactly the set of handlers registered below. (The SDK's own type doc for this field
+        // enumerates a shorter baseline; the protocol doc is the authority, and the handlers here
+        // match it.)
+        //
+        // Nothing beyond it is advertised, because every capability is a promise a client will hold
+        // us to: image and audio prompt content, MCP server transports, `session/delete`,
+        // `session/fork` and `additionalDirectories` are the things this agent does not serve, so it
+        // does not claim them.
+        capabilities: { session: {} },
+    }))
+        .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 both saw an unset root, both suspended on the config load, and both
+        // assigned — leaving two live sessions in different workspaces, which is the exact state the
+        // refusal exists to prevent. 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.
+            //
+            // **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,
+                closed: false,
+                cancelled: false,
+                replayLog: [],
+            });
+            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. Released on the same condition `closeSession` uses, and counting the in-flight
+            // requests as well as the live ones: a concurrent `session/new` that has claimed the root
+            // and is still loading is exactly as much a reason to hold it as a session already running.
+            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_resume, async ({ params }) => {
+        const session = sessionOrThrow(params.sessionId);
+        // Same comparison as the workspace binding, for the same reason: on win32 a client re-sending
+        // its own cwd with different casing names the same directory.
+        if (!isSameWorkspace(resolvePath(params.cwd), session.cwd)) {
+            throw acp.RequestError.invalidParams({ cwd: params.cwd, sessionCwd: session.cwd }, `Session ${session.sessionId} belongs to ${session.cwd}.`);
+        }
+        // `replayFrom` is an INCLUSIVE cursor and the only cursor type in v2 is `start`, so a request
+        // that carries one asks for the whole conversation and anything else asks for none of it.
+        // Replayed as message-level updates rather than as the original chunk stream: a client
+        // rebuilding a transcript wants the messages, and re-emitting thousands of one-token chunks
+        // to say the same thing would be a worse answer to the same question.
+        if (params.replayFrom?.type === 'start') {
+            for (const update of session.replayLog)
+                await sendUpdate(session, update);
+        }
+        return {};
+    })
+        .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, ({ 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 the idle state update.');
+        }
+        // Detached ON PURPOSE, and after this handler's response: the response only acknowledges
+        // acceptance, and the turn reports itself through notifications. `setImmediate` (rather than
+        // starting it inline) is what keeps the acknowledgement first on the wire — a client that
+        // saw a `session/update` for a prompt it had not yet been told was accepted would be right
+        // to treat it as a protocol error.
+        setImmediate(() => {
+            // A close that landed in the gap between accepting the prompt and this tick wins: starting
+            // the turn now would run it against a session already torn down, and nothing would be
+            // waiting for it.
+            if (session.closed)
+                return;
+            session.turn = runTurn(session, params.prompt);
+        });
+        return {};
+    })
+        .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 report `cancelled` instead of reading its own truncated stream as a normal finish.
+        session.cancelled = true;
+        session.abort?.abort();
+    });
+}
+//# sourceMappingURL=acpAgentApp.js.map

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

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

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;