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

package/dist/core/GthDeepAgent.js

@@ -1,712 +0,0 @@
-import { SHELL_TOOL_NAME, commandAnswersApprovals, resolveApprovals, resolveGatedToolNames, resolveInterruptToolNames, resolveShellApprovalGate, } from '@gaunt-sloth/core/config.js';
-import { GthAbstractAgent } from '@gaunt-sloth/core/core/GthAbstractAgent.js';
-import { StatusLevel } from '@gaunt-sloth/core/core/types.js';
-import { debugLog, debugLogObject } from '@gaunt-sloth/core/utils/debugUtils.js';
-import { buildSystemMessages, formatToolCalls, readModePrompt, } from '@gaunt-sloth/core/utils/llmUtils.js';
-import { getCurrentWorkDir, getProjectDir, getUseColour, setProjectDir, setUseColour, } from '@gaunt-sloth/core/utils/systemUtils.js';
-import { getConsoleLevel, setConsoleLevel } from '@gaunt-sloth/core/utils/consoleUtils.js';
-import { buildProfileSubagents } from '#src/core/subagentProfiles.js';
-import { isToolAllowed } from '@gaunt-sloth/core/utils/toolMatching.js';
-// GS2-27: the OS/shell-dialect and real-cwd notes are backend-agnostic (both backends expose
-// run_shell_command and run on the real-fs cwd), so their canonical source moved to core so the
-// lean backend composes them too. Imported here for GthDeepAgent.init()'s code-mode composition and
-// re-exported so existing importers of this module keep working.
-import { appendOsShellNote, appendCwdNote, appendCommitCoAuthorNote, appendModelContextNote, appendMcpServerInstructionsNote, resolveModelIdentity, } from '@gaunt-sloth/core/utils/systemPromptNotes.js';
-export { appendOsShellNote, appendCwdNote, appendCommitCoAuthorNote, appendModelContextNote, resolveModelIdentity, OS_SHELL_GUIDANCE, } from '@gaunt-sloth/core/utils/systemPromptNotes.js';
-import { AIMessage, ToolMessage } from '@langchain/core/messages';
-import { GraphInterrupt } from '@langchain/langgraph';
-import { createMiddleware } from 'langchain';
-import { createDeepAgent, FilesystemBackend } from 'deepagents';
-import { buildPermissions, DEEP_AGENT_BUILT_IN_TOOL_NAMES, FILESYSTEM_TOOL_NAMES, guardFilesystemBackend, } from '#src/core/deepAgentPermissions.js';
-import { extractDebugRequestExtras } from '#src/core/debugCapture.js';
-// Re-export so existing importers of this module (extractDebugRequestExtras.spec) keep working
-// now that the implementation lives in @gaunt-sloth/core.
-export { extractDebugRequestExtras } from '#src/core/debugCapture.js';
-import { ShellCommandFailedError } from '#src/tools/GthDevToolkit.js';
-/**
- * EXT-16: decide whether the deepagents filesystem backend must run in virtualMode.
- *
- * deepagents' permission layer (`validatePath`) requires POSIX `/`-rooted glob paths, and its
- * fs tools hand the SAME model-supplied path string to both the permission check and the native
- * `path.resolve`/`fs` backend. On Windows a real cwd is `D:\...`, which can satisfy neither side
- * as one string, so the EXT-13 real-path sandbox throws `Error: path must be absolute` on every
- * turn and the agent hangs. The precise trigger is "the real cwd is not POSIX-rooted", so we key
- * off that directly (not just `win32`): when true, run virtualMode (cwd→`/`) with virtual
- * permissions — the pre-EXT-13 known-good behavior. POSIX keeps the EXT-13 real-path namespace.
- */
-function shouldUseVirtualFs() {
-    return !getCurrentWorkDir().startsWith('/');
-}
-/**
- * Deep agent: builds a `createDeepAgent` graph (deepagents). All run/stream/event
- * plumbing lives in {@link GthAbstractAgent}; this class only knows how to construct
- * the graph in {@link init}.
- *
- * Differences from the lean {@link GthLangChainAgent}:
- * - deepagents provides the filesystem tools (`read_file`/`write_file`/`edit_file`/
- *   `ls`/`glob`/`grep`/`execute`) via its own middleware, backed by a
- *   {@link FilesystemBackend}. gsloth's `.aiignore` + `filesystem` config are mapped
- *   onto deepagents `permissions` (see {@link buildPermissions}). Any resolved tool
- *   that reuses a deepagents filesystem-tool name is therefore superseded and dropped
- *   (`createDeepAgent` would otherwise throw on the collision). EXT-14: the
- *   `FilesystemBackend` itself is wrapped with {@link guardFilesystemBackend} before it
- *   reaches `createDeepAgent`, adding a realpath (symlink-resolved) containment check the
- *   permission globs alone can't provide.
- * - todos / subagents / summarization come from deepagents' standard middleware.
- *
- * The transport-agnostic param assembly lives in {@link buildDeepAgentParams} so the ACP
- * entry (`deepagents-acp`) can reuse the exact same tool resolution, permission mapping and
- * middleware hardening without re-running `createDeepAgent` locally.
- */
-export class GthDeepAgent extends GthAbstractAgent {
-    // `debugCapture` (the opt-in TUI `/debug` sink) now lives on the shared GthAbstractAgent base
-    // so the lean backend supports it too; the wrapModelCall capture middleware below reads it.
-    async init(command, configIn, checkpointer) {
-        const params = await this.buildDeepAgentParams(command, configIn);
-        // Runner-path only: surface requested tool calls to the console. This is intentionally
-        // NOT part of buildDeepAgentParams — it writes via statusUpdate (stdout) and the ACP
-        // server renders tool calls itself over its own protocol channel.
-        const statusUpdate = this.statusUpdate;
-        const toolCallStatusMiddleware = createMiddleware({
-            name: 'GthMiddlewareToolCallStatusUpdate',
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            afterModel: (state) => {
-                debugLogObject('postModel state', state);
-                const lastMessage = state.messages[state.messages.length - 1];
-                if (AIMessage.isInstance(lastMessage) &&
-                    lastMessage.tool_calls &&
-                    lastMessage.tool_calls?.length > 0) {
-                    statusUpdate(StatusLevel.INFO, `\nRequested tools: ${formatToolCalls(lastMessage.tool_calls)}\n`);
-                }
-                return state;
-            },
-        });
-        // Debug-capture middleware (TUI `/debug` panel). Always installed but lazy: it reads
-        // `this.debugCapture` per call, so until the TUI attaches a sink it is a transparent
-        // pass-through (one extra await around the handler — the normal path pays nothing).
-        // `request.messages` is the real history at call time (post-summarization/middleware),
-        // and `handler(request)` resolves to the AIMessage response (decision (a): whole
-        // resolved message, not per-chunk — the streaming core stays untouched).
-        const getDebugCapture = () => this.debugCapture;
-        const debugCaptureMiddleware = createMiddleware({
-            name: 'GthMiddlewareDebugCapture',
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            wrapModelCall: async (request, handler) => {
-                // GS2-56: stash the always-on last-model-request snapshot (extras + as-sent messages)
-                // UNCONDITIONALLY — before the `capture` short-circuit — so `/debug-dump` has the full
-                // model input even when no TUI `/debug` sink is attached (a non-TUI surface, or `/debug`
-                // never opened). Guarded: snapshotting must never break the run. The computed extras are
-                // reused for the sink below so extraction runs once. Symmetric with the lean backend.
-                let extras;
-                try {
-                    extras = extractDebugRequestExtras(request);
-                    this.setLastModelRequest(request.messages, extras);
-                }
-                catch {
-                    /* the always-on snapshot must never break the run */
-                }
-                const capture = getDebugCapture();
-                if (!capture)
-                    return handler(request);
-                try {
-                    capture.onRequest?.(request.messages, extras);
-                }
-                catch {
-                    /* a debug sink must never break the run */
-                }
-                const response = await handler(request);
-                try {
-                    capture.onResponse?.(response);
-                }
-                catch {
-                    /* a debug sink must never break the run */
-                }
-                return response;
-            },
-        });
-        // EXT-16: whether the deepagents fs backend runs in virtualMode. deepagents' permission layer
-        // requires POSIX `/`-rooted paths, so a Windows real cwd (`D:\...`) can't be expressed as a
-        // permission glob and the EXT-13 real-path mode hangs there (`Error: path must be absolute`).
-        // When the real cwd isn't POSIX-rooted, fall back to virtualMode (cwd→`/`) with virtual
-        // permissions — the pre-EXT-13 known-good Windows behavior. Computed here because the EXT-22 S1
-        // middleware (below), the backend, and the systemPrompt gate (further down) all key off it.
-        const useVirtualFs = shouldUseVirtualFs();
-        // EXT-22 (S1): last-word path-namespace correction. Appends the shared guidance as a trailing
-        // system-message block ONLY in code + virtualMode (where the fs virtual `/` root and the
-        // shell's real-OS paths diverge); a transparent pass-through otherwise. Added LAST in the
-        // middleware array so, being the innermost wrapModelCall, its block lands AFTER deepagents'
-        // "All file paths must start with a /." line (see handoff/spike-systemmessage-ordering.md).
-        const pathNamespaceCorrectionMiddleware = createPathNamespaceCorrectionMiddleware(this.command === 'code' && useVirtualFs);
-        const middleware = [
-            ...params.middleware,
-            toolCallStatusMiddleware,
-            debugCaptureMiddleware,
-            pathNamespaceCorrectionMiddleware,
-        ];
-        this.headerStatus(`Loaded middleware: ${middleware.map((m) => m.name).join(', ')}`);
-        // EXT-13: the backend always runs in REAL-path mode (virtualMode off) so the deepagents fs
-        // tools and the EXT-9 run_shell_command tool share ONE path namespace — real absolute paths
-        // rooted at cwd. Containment is enforced by the permission allow/deny globs built in
-        // buildDeepAgentParams (default: allow cwd/**, deny /**), which match what virtualMode used to
-        // give for free (see deepAgentPermissions + the EXT-13 symlink/`..` parity tests), PLUS the
-        // EXT-14 realpath guard wrapped around the backend below (closes the intermediate-symlinked-
-        // directory gap those lexical globs alone can't catch).
-        // `--allow-dir` (config.allowDirs) further widens those allow-rules to reach extra real dirs;
-        // it removes a guardrail, so it is announced loudly by the exec command and surfaced here.
-        const allowDirs = this.config?.allowDirs;
-        const widenFs = Array.isArray(allowDirs) && allowDirs.length > 0;
-        if (widenFs) {
-            this.statusUpdate(StatusLevel.WARNING, `Filesystem sandbox widened beyond cwd (--allow-dir): ${allowDirs.join(', ')}` +
-                (useVirtualFs
-                    ? ' — note: on this platform the sandbox runs in virtual mode, so widening beyond cwd is not applied.'
-                    : ''));
-        }
-        // EXT-14: layer the realpath containment guard around the backend deepagents' fs middleware
-        // (main agent AND every subagent — they all share this one `backend` reference, see
-        // guardFilesystemBackend's doc comment) reads/writes through. Closes the intermediate-
-        // symlinked-directory escape that the lexical allow/deny globs alone cannot catch.
-        const backend = guardFilesystemBackend(new FilesystemBackend({
-            rootDir: getCurrentWorkDir(),
-            virtualMode: useVirtualFs,
-        }), {
-            cwd: getCurrentWorkDir(),
-            virtual: useVirtualFs,
-            allowDirs: widenFs ? allowDirs : undefined,
-        });
-        // EXT-13 (part b): on the local-runner code path the model used to be told nothing about
-        // where it is, so it assumed `/` was cwd and fed `/`-rooted paths to the real-fs shell. Now
-        // the backend uses real absolute paths (above), so inject the dynamic real cwd + path model
-        // into the prompt the model actually receives. Code mode only — the surface with full fs +
-        // shell access; the ACP transport keeps virtualMode and re-roots per session, so this
-        // real-path note must NOT leak there (which is why it lives in init(), not the
-        // transport-agnostic buildDeepAgentParams).
-        // In virtualMode (EXT-16, Windows) the real-cwd note must NOT be injected — it would mislabel
-        // the namespace (the fs tools' `/` is the virtual root, not the real cwd). Instead, EXT-22 (S2)
-        // injects the virtualMode path-namespace note so the model is told EARLY that the fs virtual
-        // `/` root and run_shell_command's real-OS paths differ (the S1 middleware repeats it as the
-        // authoritative last word after deepagents' `/`-rooted line). Non-code paths get neither.
-        // EXT-26: after the cwd/virtual-cwd note, append the OS + shell-dialect note so the model is
-        // told its host OS and which shell run_shell_command spawns (cmd.exe on Windows, /bin/sh on
-        // POSIX). This is ORTHOGONAL to the path-namespace notes above (those say WHERE it is; this
-        // says WHAT shell it speaks) and applies in BOTH code-mode branches, independent of
-        // virtualMode — the shell dialect matters on every platform. Non-code paths get nothing new.
-        // GS2-34/EXT-83: resolve the active model identity ONCE, honouring the `injectModelContext`
-        // opt-out (default ON) at this single read site. Both consumers below take this same value, so
-        // the commit trailer and the model-context note can never disagree about which model is serving
-        // the session — and the opt-out means "my model identity stays out of the prompt", which covers
-        // the trailer as much as the identity line. Mirrors the lean backend seam.
-        const modelIdentity = this.config?.injectModelContext !== false ? resolveModelIdentity(this.config) : undefined;
-        // GS2-35: append the commit co-authoring rule (config `commit.coAuthor`, defaulting to the Gaunt
-        // Sloth account) so agent-authored commits credit Gaunt Sloth in the `Co-Authored-By` trailer,
-        // and the EXT-83 commit-message rules (plain English, and passed by file — never inline, where
-        // the shell would expand the message before git runs). Mirrors the lean backend seam so both
-        // compose the same shared note (GS2-27 parity); same code-mode gate as the shell/cwd notes and
-        // independent of virtualMode.
-        // EXT-84: the effective `filesystem` is threaded in so the note names the writing tool only
-        // where that tool is registered. It is the command-merged value set by buildDeepAgentParams
-        // (getEffectiveConfig) — NOT the `filesystem: 'none'` override used purely to keep gsloth's
-        // filesystem toolkit out of tool resolution, which says nothing about the fs access deepagents
-        // itself grants from the same value. Mirrors the lean backend seam.
-        const codeNotesPrompt = this.command === 'code'
-            ? appendCommitCoAuthorNote(appendOsShellNote(useVirtualFs
-                ? appendVirtualCwdNote(params.systemPrompt)
-                : appendCwdNote(params.systemPrompt, getCurrentWorkDir())), this.config?.commit?.coAuthor, modelIdentity, this.config?.filesystem)
-            : params.systemPrompt;
-        // GS2-34: inject the resolved provider:model identity (mirrors the lean GthLangChainAgent seam so
-        // both backends compose the same shared note — GS2-27 parity). Composed OUTSIDE the code-mode
-        // gate above: "which model are you?" can be asked in ANY mode (chat/ask/code/exec), so the
-        // identity is visible everywhere, unlike the code-only cwd/os-shell/commit notes. The
-        // `injectModelContext` opt-out is applied at the single read site above; when it is off — or
-        // when no model resolves — `modelIdentity` is undefined, nothing is appended, and the prompt is
-        // exactly as before. Lives in init() like the cwd note (not buildDeepAgentParams), so the
-        // deepagents-acp transport is unaffected, consistent with every other init()-composed note.
-        // GS2-6 capability note deferred.
-        const modelContextPrompt = appendModelContextNote(codeNotesPrompt, modelIdentity);
-        // EXT-32: inject the connected MCP servers' discovery `instructions` (captured by the resolver
-        // during buildDeepAgentParams' resolveTools call, above) into the prompt — fenced + per-server-
-        // labelled as untrusted server-provided context. Mode-independent (MCP tools load in every
-        // mode). This mirrors the lean backend's GthLangChainAgent seam so both backends compose the
-        // same shared note (GS2-27 shared-path parity). Lives in init() like the cwd note, so the ACP
-        // buildDeepAgentParams entry is intentionally unaffected. Empty capture adds nothing.
-        // When tools are disabled, buildDeepAgentParams skips resolveTools (no MCP contact), so a REUSED
-        // resolver could still hold a prior run's capture — gate on toolsDisabled (recomputed from the
-        // effective config buildDeepAgentParams set on `this.config`) so no stale instructions leak.
-        const deepToolsDisabled = Array.isArray(this.config?.allowedTools) && this.config.allowedTools.length === 0;
-        const mcpInstructions = deepToolsDisabled
-            ? []
-            : (this.resolvers?.getMcpServerInstructions?.() ?? []);
-        const systemPrompt = appendMcpServerInstructionsNote(modelContextPrompt, mcpInstructions);
-        // GS2-33 — resolve profile-backed subagents (config `subagents`). Runner-only, like the
-        // cwd/model-context notes above: it lives in init() (NOT the transport-agnostic
-        // buildDeepAgentParams), so the deepagents-acp path is unaffected and the child-config
-        // resolution's process-global side effects stay on the local-runner path. Each declared
-        // subagent's CHILD resolves its named profile through the GS2-1 cascade, so the deepagents `task`
-        // tool can dispatch it under that profile's own model + tools + prompt (e.g. a cheap flash-lite
-        // profile for recall/search while the parent runs on a strong model). Because resolving a child
-        // goes through initConfig — which mutates projectDir/consoleLevel/useColour exactly as the parent
-        // run's own initConfig did — snapshot and restore those globals so a child profile's console
-        // level / colour can never leak into the parent run.
-        let subagents;
-        const subagentSpecs = this.config?.subagents;
-        if (Array.isArray(subagentSpecs) && subagentSpecs.length > 0) {
-            const savedProjectDir = getProjectDir();
-            const savedConsoleLevel = getConsoleLevel();
-            const savedUseColour = getUseColour();
-            try {
-                subagents = await buildProfileSubagents(subagentSpecs, {
-                    command: this.command,
-                    resolveTools: this.resolvers?.resolveTools?.bind(this.resolvers),
-                });
-                this.headerStatus(`Loaded profile subagents: ${subagents.map((s) => s.name).join(', ')}`);
-            }
-            finally {
-                setProjectDir(savedProjectDir);
-                setConsoleLevel(savedConsoleLevel);
-                setUseColour(savedUseColour);
-            }
-        }
-        this.agent = createDeepAgent({
-            model: params.model,
-            tools: params.tools,
-            // GS2-33 — profile-backed subagents (undefined when none configured → deepagents' default
-            // general-purpose subagent only, unchanged behaviour).
-            subagents,
-            // gsloth's composed prompt, combined ADDITIVELY by deepagents with its base + fs prompts
-            // into a single system message (avoids the two-system-message Anthropic rejection).
-            systemPrompt,
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            middleware: middleware,
-            backend,
-            permissions: params.permissions,
-            // Per-tool human-in-the-loop gating (e.g. run_shell_command confirmation). When set,
-            // deepagents installs humanInTheLoopMiddleware so a matching tool call suspends the graph
-            // for approval; `undefined` (the default, and under bypass) leaves every tool ungated.
-            interruptOn: params.interruptOn,
-            checkpointer,
-        });
-        debugLog('Deep agent created successfully');
-    }
-    /**
-     * Assemble the transport-agnostic {@link GthDeepAgentParams}: resolve tools (with the
-     * filesystem disabled so deepagents owns fs access), apply the allowedTools allow-list and
-     * the deepagents fs-name supersession safety-net, map `.aiignore` + filesystem mode onto
-     * deepagents permissions, and build the fs-denial-softening middleware. Shared by the local
-     * runner ({@link init}) and the `deepagents-acp` ACP entry.
-     */
-    async buildDeepAgentParams(command, configIn) {
-        this.command = command;
-        debugLog(`GthDeepAgent.buildDeepAgentParams called with command: ${command || 'default'}`);
-        // Merge command-specific filesystem config if provided
-        this.config = this.getEffectiveConfig(configIn, command);
-        debugLogObject('Effective Config', {
-            filesystem: this.config.filesystem,
-            builtInTools: this.config.builtInTools,
-            streamOutput: this.config.streamOutput,
-            debugLog: this.config.debugLog,
-        });
-        this.headerStatus(`Workdir: ${getCurrentWorkDir()}`);
-        if (this.config.modelDisplayName) {
-            this.headerStatus(`Model: ${this.config.modelDisplayName}`);
-        }
-        // An empty allowedTools allow-list disables every tool. Skip resolution entirely so we
-        // don't contact MCP servers (and trigger OAuth) just to discard the result.
-        const allowedTools = this.config.allowedTools;
-        const toolsDisabled = Array.isArray(allowedTools) && allowedTools.length === 0;
-        if (toolsDisabled) {
-            this.headerStatus('Tool loading disabled by allowedTools: []; MCP/A2A servers will not be contacted. Omit allowedTools for no filtering.');
-        }
-        // Resolve tools with filesystem access disabled. deepagents OWNS the filesystem
-        // (its fs middleware + the `permissions` built below); gsloth's filesystem toolkit
-        // must NOT be loaded here, because its non-colliding tools (read_multiple_files,
-        // delete_file, search_files, …) would otherwise bypass deepagents' permission
-        // enforcement entirely — a model could read an .aiignore-protected file through them.
-        debugLog('Resolving tools (filesystem disabled; deepagents provides fs)...');
-        const toolResolutionConfig = { ...this.config, filesystem: 'none' };
-        const resolvedTools = !toolsDisabled && this.resolvers?.resolveTools
-            ? await this.resolvers.resolveTools(toolResolutionConfig, command)
-            : [];
-        debugLog(`Resolved tools loaded: ${resolvedTools.length}`);
-        // Get user config tools (toolkit-flattened; client tools get interrupt() stubs)
-        const flattenedConfigTools = toolsDisabled
-            ? []
-            : this.extractAndFlattenTools(this.config.tools || []);
-        debugLog(`User config tools loaded: ${flattenedConfigTools.length}`);
-        // Combine all tools, then apply the allowedTools name allow-list when configured. Entries
-        // match by exact name, or glob-style when they contain `*` (e.g. `mcp__unimarket__*`) — see
-        // isToolAllowed. Nameless ServerTools are retained (they can't be named in the allow-list).
-        let tools = [...resolvedTools, ...flattenedConfigTools];
-        if (Array.isArray(allowedTools)) {
-            tools = tools.filter((tool) => !tool.name || isToolAllowed(tool.name, allowedTools));
-        }
-        // Safety net: a custom/dev/MCP tool may still reuse a deepagents filesystem-tool
-        // name (createDeepAgent throws on such a collision). Drop the colliding tool — the
-        // deep agent's built-in fs tool wins. With filesystem disabled above this is normally
-        // empty; it only fires for a genuine user/MCP name clash.
-        const reserved = new Set(FILESYSTEM_TOOL_NAMES);
-        const superseded = tools.filter((tool) => tool.name && reserved.has(tool.name));
-        const passThroughTools = tools.filter((tool) => !tool.name || !reserved.has(tool.name));
-        if (superseded.length > 0) {
-            const names = superseded.map((tool) => tool.name).join(', ');
-            this.statusUpdate(StatusLevel.WARNING, `Dropping tool(s) that collide with deepagents built-in filesystem tools: ${names}`);
-        }
-        if (passThroughTools.length > 0) {
-            const toolNames = passThroughTools
-                .map((tool) => tool.name)
-                .filter((name) => name)
-                .join(', ');
-            this.headerStatus(`Loaded tools: ${toolNames}`);
-            debugLog(`Total tools available: ${passThroughTools.length}`);
-            debugLogObject('All Tools', toolNames.split(', '));
-        }
-        debugLog('Creating deep agent...');
-        // Resolve middleware via resolver or fall back to empty. These are applied AFTER
-        // deepagents' standard middleware (todos, subagents, summarization, filesystem).
-        const resolvedMiddleware = this.resolvers?.resolveMiddleware
-            ? await this.resolvers.resolveMiddleware(
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            this.config.middleware, this.config)
-            : [];
-        // deepagents' standard middleware already summarizes long conversations; drop any
-        // gsloth-configured summarization middleware so the deep agent doesn't summarize twice.
-        const configuredMiddleware = resolvedMiddleware.filter((m) => {
-            const name = m.name ?? '';
-            if (/summar/i.test(name)) {
-                debugLog(`Dropping duplicate summarization middleware '${name}' (deepagents provides it)`);
-                return false;
-            }
-            return true;
-        });
-        // Soften deepagents' fail-hard filesystem tool throws. By default the permission layer
-        // THROWS on both a denied read/write AND on a malformed path the model supplied — a relative
-        // path, a `..`/`~` segment, or an empty string (deepagents' validatePath, run BEFORE the
-        // permission check in enforcePermission). Any of these aborts the WHOLE run. On the AG-UI
-        // transport that throw propagates out of streamWithEvents into the run handler's catch, which
-        // emits RUN_ERROR and ends the response WITHOUT a terminal RUN_FINISHED — and since AG-UI's
-        // protocol makes RUN_ERROR terminal ("no further events can be sent"), a consumer waiting for
-        // RUN_FINISHED hangs (EXT-24). Wrap tool calls so each of these becomes a recoverable error
-        // ToolMessage instead, letting the model observe the mistake, retry with a good path, and
-        // finish the run normally (reaching RUN_FINISHED). This preserves gsloth's recoverable-denial
-        // UX (the old GthFileSystemToolkit returned a message rather than throwing). Only these known
-        // fs path/permission messages are caught; every other throw (GraphInterrupt from a client-tool
-        // interrupt stub, AbortError on client disconnect, unexpected errors) is rethrown untouched so
-        // control-flow and genuine failures still surface.
-        const fsDenialSoftening = createMiddleware({
-            name: 'GthDeepFsDenialSoftening',
-            wrapToolCall: async (request, handler) => {
-                try {
-                    return await handler(request);
-                }
-                catch (e) {
-                    // EXT-25: rethrow control-flow throws BY TYPE, BEFORE the message regex below. A
-                    // GraphInterrupt (a client-tool interrupt() suspending the graph for HITL tool
-                    // approval) and an AbortError (caller cancellation) must ALWAYS propagate so the graph
-                    // suspends / cancels — never be converted into a benign ToolMessage. Mirrors the guard
-                    // in GthAbstractAgent (error.name checks + GraphInterrupt instanceof). Today these
-                    // survive only because their messages happen not to match the regex; guarding by type
-                    // stops a future regex broadening from silently swallowing the HITL suspend.
-                    if (e instanceof GraphInterrupt ||
-                        e?.name === 'GraphInterrupt' ||
-                        e?.name === 'AbortError') {
-                        throw e;
-                    }
-                    const message = e instanceof Error ? e.message : String(e);
-                    // A permission denial, or a path that is relative / contains ".." or "~" / is empty —
-                    // all recoverable model-input errors. The live source of these throws is gsloth's own
-                    // realpath guard (guardFilesystemBackend); deepagents' enforcement used to throw the
-                    // same messages too, but since 1.11.1 it returns the equivalent error ToolMessage
-                    // itself and so never reaches this catch. Keep matching both: the observation the model
-                    // sees is identical either way, and the guard still depends on this softening.
-                    if (/permission denied for (read|write)|path must (be absolute|not contain|be a non-empty string)/i.test(message)) {
-                        debugLog(`Softened fs tool throw into a ToolMessage: ${message}`);
-                        return new ToolMessage({
-                            content: message,
-                            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                            tool_call_id: request.toolCall?.id ?? '',
-                            status: 'error',
-                        });
-                    }
-                    throw e;
-                }
-            },
-        });
-        // EXT-20: sibling of fsDenialSoftening for the run_* (dev/shell) tools. GthDevToolkit's
-        // executeCommand now THROWS a ShellCommandFailedError on a non-zero exit or a timeout-kill
-        // (instead of resolving with the failure text), so the tool result no longer misreports
-        // status:'success' (✓). Catch it here and return an error ToolMessage that PRESERVES the full
-        // stdout/stderr body — the model's observation is unchanged except that status flips to
-        // 'error', which drives the ✗ (isError) glyph (GthAbstractAgent maps status==='error' →
-        // isError). Returning a ToolMessage (rather than rethrowing) also means the approved-then-failed
-        // command does NOT trigger a retry loop — it is a normal, observed tool result.
-        const shellExitSoftening = createMiddleware({
-            name: 'GthDeepShellExitSoftening',
-            wrapToolCall: async (request, handler) => {
-                try {
-                    return await handler(request);
-                }
-                catch (e) {
-                    if (e instanceof ShellCommandFailedError) {
-                        debugLog(`Softened shell/dev command failure (exit ${e.exitCode ?? 'timeout'}) into an ` +
-                            `error ToolMessage for '${e.command}'`);
-                        return new ToolMessage({
-                            content: e.output,
-                            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                            tool_call_id: request.toolCall?.id ?? '',
-                            status: 'error',
-                        });
-                    }
-                    throw e;
-                }
-            },
-        });
-        // MCP tool-execution errors are spec-compliant RESULTS, not fatal faults. Per the MCP spec
-        // (2025-11-25 & draft, "Server › Tools › Error Handling"), a tool that hits an API failure, an
-        // input-validation problem, or a business-logic error (e.g. a disabled capability) returns a
-        // normal tools/call result with `isError: true`, and the CLIENT *SHOULD* hand that error to the
-        // model so it can self-correct. `@langchain/mcp-adapters` instead surfaces such a result by
-        // THROWING a ToolException at call time (its `_convertCallToolResult`). Because we install a
-        // wrapToolCall middleware, langchain's ToolNode treats any error a middleware rethrows as a fatal
-        // "middleware error" (`errorFromMiddleware && handleToolErrors !== true` → throw) and aborts the
-        // whole turn instead of relaying the error to the model — the opposite of the spec's client
-        // SHOULD. This middleware closes that gap: it catches a thrown ToolException and RETURNS it as a
-        // status:'error' ToolMessage (→ isError → ✗), so the model observes the error and can retry or
-        // explain (matching the non-stream invoke path's ToolException handling). Scope & safety: matched
-        // by name === 'ToolException' (the adapter's marker), so GraphInterrupt and every non-MCP throw
-        // fall through the final rethrow untouched. The adapter ALSO wraps a call-time AbortError into a
-        // ToolException (its `_callTool` catch-all), so we RETHROW when the run's abort signal is set —
-        // otherwise softening here would swallow user cancellation that ToolNode's own `signal?.aborted`
-        // guard normally enforces (bypassed once we handle the error in middleware). MCP connect/auth
-        // (401/403) and load failures are handled at CONNECT time (resolvers.ts throwOnLoadError +
-        // onConnectionError), not here, so they stay fatal as intended.
-        const mcpToolErrorSoftening = createMiddleware({
-            name: 'GthMcpToolErrorSoftening',
-            wrapToolCall: async (request, handler) => {
-                try {
-                    return await handler(request);
-                }
-                catch (e) {
-                    if (e instanceof Error &&
-                        e.name === 'ToolException' &&
-                        !request.runtime?.signal?.aborted) {
-                        debugLog(`Softened MCP tool error into an error ToolMessage: ${e.message}`);
-                        return new ToolMessage({
-                            content: e.message,
-                            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                            tool_call_id: request.toolCall?.id ?? '',
-                            status: 'error',
-                        });
-                    }
-                    throw e;
-                }
-            },
-        });
-        // fsDenialSoftening first so it is the outermost wrapToolCall — it must see the throw from
-        // deepagents' permission-enforcing fs tools. shellExitSoftening sits right after it (still
-        // outboard of any user-configured middleware, so it always sees the raw ShellCommandFailedError
-        // throw before a user wrapToolCall could transform it). Order between the two softeners is not
-        // load-bearing: they catch DISJOINT conditions (a permission-denied regex vs an
-        // `instanceof ShellCommandFailedError`) and each rethrows what it doesn't recognize, so neither
-        // can swallow the other. The console-bound tool-call-status middleware is NOT added here (see
-        // GthDeepAgentParams.middleware); the runner appends it. mcpToolErrorSoftening sits alongside the
-        // other two softeners (still outboard of user middleware); it catches a DISJOINT condition
-        // (name==='ToolException') and rethrows everything else, so ordering among the three is not
-        // load-bearing.
-        const middleware = [
-            fsDenialSoftening,
-            shellExitSoftening,
-            mcpToolErrorSoftening,
-            ...configuredMiddleware,
-        ];
-        // Map gsloth's .aiignore + filesystem mode onto deepagents permission rules. When
-        // `--allow-dir` widens the sandbox, the backend runs without virtualMode, so paths are REAL
-        // absolute paths: constrain read+write to cwd + the allowed dirs (everything else denied),
-        // layered under the .aiignore deny rules.
-        const permissions = buildPermissions({
-            filesystem: this.config.filesystem,
-            aiignore: this.config.aiignore,
-            allowDirs: Array.isArray(this.config.allowDirs) && this.config.allowDirs.length > 0
-                ? this.config.allowDirs
-                : undefined,
-        }, 
-        // EXT-16: build virtual (`/`-rooted) permission rules when the backend will run in
-        // virtualMode (Windows), matching the FilesystemBackend created in init().
-        shouldUseVirtualFs());
-        debugLogObject('Filesystem permissions', permissions);
-        // Compose gsloth's system prompt (backstory + guidelines + per-command mode prompt +
-        // system prompt) so identity profiles (Gaunt Sloth, sorcerer, fisher-alt, …) and
-        // `.gsloth.*.md` are honored. This is passed to createDeepAgent as `systemPrompt` — combined
-        // additively with deepagents' base + fs prompts into ONE system message — rather than injected
-        // as a separate SystemMessage per turn (which produced a non-first system message that
-        // Anthropic rejects). GS2-79: which mode prompt a command gets is decided ONCE, in core's
-        // `readModePrompt` — 'code' the code-mode prompt, 'exec' the prompt-as-script exec-mode prompt,
-        // 'review'/'pr' the REVIEW INSTRUCTIONS, chat/api/others the chat prompt — so this backend and
-        // the lean one cannot disagree, and a command left out of the selection can no longer be served
-        // the chat prompt by silent default.
-        const modePrompt = readModePrompt(this.command, this.config);
-        const systemMessages = buildSystemMessages(this.config, modePrompt);
-        const systemPrompt = typeof systemMessages[0]?.content === 'string' ? systemMessages[0].content : undefined;
-        // Gate the opt-in run_shell_command tool behind a per-command approval interrupt. The gate
-        // condition and its user-facing notices are the SHARED core policy (`resolveShellApprovalGate`,
-        // EXT-12 semantics documented there), so this backend and the lean one can never drift; here it
-        // is installed through deepagents' `interruptOn` rather than as middleware. The resolver reads
-        // the same `builtInTools` registry GthDevToolkit emits the tool from (CFG-18), so the wiring
-        // stays in lockstep with where the tool actually exists.
-        const { gateShell, notice: shellGateNotice } = resolveShellApprovalGate(this.config ?? undefined, this.command);
-        //
-        // EXT-80: at `manual` and `write` every bound tool the rung's access class does not
-        // auto-grant must reach the human. Both sets below come from core's shared policy — the same one
-        // the lean backend and `GthAgentRunner` call — so the three cannot disagree about what is gated.
-        //
-        // **The interrupt is wired rung-INDEPENDENTLY, over every tool any rung could gate.** It is
-        // built once, here, while `/approvals <rung>` moves the rung for the rest of the session without
-        // rebuilding the graph; a set that carried the rung would be frozen at the rung the session
-        // started on, and since the default is `assisted`, typing `/approvals manual` would leave
-        // exactly the write tools ungated. `GthAgentRunner.decideToolApproval` decides on the rung in
-        // force, so wiring wider does not gate wider.
-        //
-        // **`boundToolNames` must include deepagents' OWN tools.** deepagents registers its filesystem
-        // tools, `execute`, `task` and `write_todos` itself (this backend resolves with
-        // `filesystem: 'none'`), so they never appear in `passThroughTools`; deriving the set from that
-        // array alone would leave `write_file`, `edit_file`, `execute`, `task` and `write_todos` ungated
-        // at `manual` on this backend — precisely the defect this change exists to remove. Gating
-        // them by name works because deepagents installs the very same langchain
-        // `humanInTheLoopMiddleware`, which matches the model's tool CALLS by name in `afterModel` and so
-        // does not care which party registered the tool.
-        //
-        // Note this union keeps `execute`, unlike `additionalToolNames` below: that list answers "what
-        // may the rater offer as a granted alternative", a different question from "what must the gate
-        // stop". `execute` is deepagents' shell and has no access class, so it must be gated at both
-        // deterministic rungs and offered as an alternative at none.
-        const rung = resolveApprovals(this.config ?? undefined, this.command).rung;
-        const boundToolNames = [
-            ...passThroughTools
-                .map((tool) => tool?.name)
-                .filter((name) => typeof name === 'string' && name.length > 0),
-            ...DEEP_AGENT_BUILT_IN_TOOL_NAMES,
-        ];
-        // **What a surface that answers no approval gets — for BOTH sets below.** An interrupt nobody
-        // can answer suspends the graph forever: the tool never runs and the client is never asked. So
-        // such a surface is wired with exactly what the shell gate itself requires and nothing more,
-        // and is not TOLD it will be asked either. This backend is ONE of the two the AG-UI server can
-        // run on — `apiAgUiModule.createConfiguredAgent` builds a `GthDeepAgent` only when
-        // `agent.backend === 'deep'` (and warns that it is experimental); every other configuration,
-        // the default included, gets the lean `GthLangChainAgent`, which carries the same wiring for
-        // the same reason. It matters on both: at `manual` and `write` the live set is non-empty, so a
-        // write, an MCP call, `task` or deepagents' own `write_todos` bookkeeping would simply vanish —
-        // or be announced to the model as approvable when nothing will ever approve it.
-        const answersApprovals = commandAnswersApprovals(this.command);
-        const noDrainTools = gateShell ? [SHELL_TOOL_NAME] : [];
-        // The LIVE gated set — what THIS rung gates — for the §4.5 tool descriptions below.
-        const gatedTools = answersApprovals
-            ? resolveGatedToolNames({ rung, gateShell, boundToolNames })
-            : noDrainTools;
-        // Rung-independent ONLY where something answers the interrupt.
-        const interruptTools = answersApprovals
-            ? resolveInterruptToolNames({ gateShell, boundToolNames })
-            : noDrainTools;
-        // Keyed off the interrupt SET, not `gateShell`: at a deterministic rung there is a gate to
-        // install even when the shell tool is disabled, and deepagents installs no HITL middleware at
-        // all when `interruptOn` is undefined.
-        const interruptOn = interruptTools.length > 0
-            ? Object.fromEntries(interruptTools.map((name) => [name, { allowedDecisions: ['approve', 'reject'] }]))
-            : undefined;
-        if (shellGateNotice) {
-            this.statusUpdate(shellGateNotice.level, shellGateNotice.message);
-        }
-        // EXT-58 (spec §4.5) — the same tool-registration hook the lean backend calls, on the same LIVE
-        // gated set, so neither backend's descriptions can disagree with its own rung. That set is
-        // narrower than the `interruptOn` set above, which covers every rung so the rung can still move
-        // mid-session; describing from the wider one would promise approvals this rung does not ask
-        // for. deepagents registers its OWN filesystem tools (this backend
-        // resolves with `filesystem: 'none'`), so they never appear in `passThroughTools` and their
-        // descriptions are deepagents' rather than ours, which is why they cannot be suffixed here even
-        // though the gated set above does gate them. They are declared as additional registered names so
-        // the rater's granted-alternative list (§4.4) reflects the tools a deep session actually has.
-        // `execute` is deliberately excluded from THAT list: it is deepagents' shell, not a filesystem
-        // tool, and must never be offered as a granted alternative to a shell command.
-        this.registerApprovalsAwareTools(passThroughTools, {
-            rung,
-            gatedTools,
-            additionalToolNames: FILESYSTEM_TOOL_NAMES.filter((name) => name !== 'execute'),
-        });
-        return {
-            model: this.config.llm,
-            tools: passThroughTools,
-            permissions,
-            middleware,
-            systemPrompt,
-            interruptOn,
-        };
-    }
-}
-/**
- * EXT-22: shared virtualMode path-namespace guidance — ONE source of truth used by BOTH the S2
- * early-framing note ({@link appendVirtualCwdNote}, injected into gsloth's composed systemPrompt =
- * block 0) and the S1 last-word correction middleware
- * ({@link createPathNamespaceCorrectionMiddleware}, appended after deepagents' `/`-rooted line).
- *
- * In a virtualMode `code` session (EXT-16, e.g. Windows) the deepagents filesystem tools use a
- * VIRTUAL `/` root (= the working dir) while `run_shell_command` uses REAL native OS paths; the
- * model conflates the two forms. This text draws the distinction and steers toward cwd-relative
- * paths (the one form both tool families read alike).
- *
- * It deliberately does NOT equate the virtual root with a specific real path (no "`/` = D:\\work"):
- * virtualMode withholds the real cwd on purpose (see the systemPrompt gate in {@link
- * GthDeepAgent.init}), so the guidance is about the DISTINCTION between the two namespaces and the
- * safety of relative paths, not a mapping between them.
- */
-export const PATH_NAMESPACE_GUIDANCE = 'The filesystem tools (ls, read_file, write_file, edit_file, glob, grep) use a VIRTUAL root in ' +
-    'this session: a leading `/` means your working directory, and their paths are written ' +
-    '`/`-rooted relative to it (this is what "all file paths must start with a /" refers to). That ' +
-    '`/` is NOT the real operating-system filesystem root. run_shell_command is different: it runs ' +
-    'in the real operating system and uses real native paths (on Windows, e.g. ' +
-    '`C:\\Users\\...\\project`, with backslashes), never the virtual `/` root. A `/`-rooted path ' +
-    'from the filesystem tools is NOT a valid shell path and must never be passed to ' +
-    'run_shell_command. The one form that means the same thing to both tool families is a path ' +
-    'RELATIVE to the working directory (e.g. `src/index.ts`); prefer relative paths for both. When ' +
-    'you must be absolute, use `/`-rooted form ONLY for the filesystem tools and real native form ' +
-    'ONLY for run_shell_command.';
-/**
- * EXT-22 (S2): virtualMode variant of {@link appendCwdNote}. On the `code` path when the fs
- * backend runs in virtualMode (EXT-16), inject the shared path-namespace guidance EARLY in
- * gsloth's composed systemPrompt (block 0) so the model is framed before deepagents' own prompt.
- *
- * This is early framing only: deepagents' hardcoded `/`-rooted line lands in a LATER block and can
- * partially override block 0, so the authoritative last word is delivered by the S1 middleware
- * ({@link createPathNamespaceCorrectionMiddleware}); see handoff/spike-systemmessage-ordering.md.
- * Returns the note alone when there is no base prompt.
- */
-export function appendVirtualCwdNote(systemPrompt) {
-    const note = `Filesystem vs shell path namespaces: ${PATH_NAMESPACE_GUIDANCE}`;
-    return systemPrompt ? `${systemPrompt}\n\n${note}` : note;
-}
-/**
- * EXT-22 (S1): the load-bearing path-namespace correction. A gsloth `wrapModelCall` middleware
- * runs INNERMOST (inside deepagents' filesystem middleware), so appending a trailing block to
- * `request.systemMessage` lands AFTER deepagents' hardcoded "All file paths must start with a /."
- * line — giving gsloth the last word on path semantics (empirically verified; see
- * handoff/spike-systemmessage-ordering.md). It APPENDS via `request.systemMessage.concat(...)`
- * (mirroring how deepagents appends its own fs prompt), never string-splices, and returns a NEW
- * request so it never mutates persisted state (no compounding across turns).
- *
- * `appendCorrection` gates it to `code` + virtualMode: only there do the fs virtual `/` root and
- * the shell's real-OS paths diverge. On POSIX real-path mode deepagents' "start with /" is
- * literally true, so the middleware is a transparent pass-through (like the debug-capture
- * middleware when no sink is attached).
- */
-export function createPathNamespaceCorrectionMiddleware(appendCorrection) {
-    return createMiddleware({
-        name: 'GthDeepPathNamespaceCorrection',
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        wrapModelCall: async (request, handler) => {
-            if (!appendCorrection || !request?.systemMessage)
-                return handler(request);
-            const correction = 'IMPORTANT — path namespaces (authoritative; this overrides any earlier instruction that ' +
-                `implies every path is a simple \`/\`-rooted filesystem path): ${PATH_NAMESPACE_GUIDANCE}`;
-            return handler({ ...request, systemMessage: request.systemMessage.concat(correction) });
-        },
-    });
-}
-// The `/debug` request-extras extraction (extractDebugRequestExtras + its model-param / tool-def
-// allowlist helpers) now lives in @gaunt-sloth/core (`core/debugCapture.ts`) so the lean backend
-// shares it. Imported at the top of this module and re-exported for back-compat.
-//# sourceMappingURL=GthDeepAgent.js.map