@gaunt-sloth/agent 2.0.0-alpha.2 → 2.0.0-alpha.20

package/README.md

@@ -8,9 +8,19 @@ The deep-agent runtime for Gaunt Sloth. Consolidates what were previously
 - MCP client + OAuth provider
 - A2A client and tools
 - The AG-UI server (`startAgUiServer`) and interactive session module
+- The ACP (Agent Client Protocol) server (`startAcpServer`), exposed as the
+  `gaunt-sloth-acp` binary
 - The `createResolvers` tool/middleware resolver wiring
 
 It builds on `@gaunt-sloth/core` (config, provider factory, lean langchain runtime).
 
+> **Running the ACP server:** prefer `gaunt-sloth --acp-agent` from the
+> [`gaunt-sloth`](https://www.npmjs.com/package/gaunt-sloth) app, not the standalone
+> `gaunt-sloth-acp` binary. The LLM providers are `peerDependencies` of `@gaunt-sloth/core` that
+> only the app declares, so a bare `@gaunt-sloth/agent` install has no providers to construct a
+> model from. See the
+> [app README → ACP server](https://github.com/pukeko-robotics/gaunt-sloth/blob/main/packages/app/README.md#acp-server-editor-integration)
+> for setup and a Zed `settings.json` example.
+
 > `@gaunt-sloth/tools` and `@gaunt-sloth/api` are deprecated and now re-export
 > from this package.

package/dist/builtInToolsConfig.d.ts

@@ -10,15 +10,29 @@ export declare const AVAILABLE_BUILT_IN_TOOLS: {
     /**
      * Reference tool. Simply prints provided argument to the screen.
      */
-    readonly gth_status_update: "#src/tools/gthStatusUpdateTool.js";
+    readonly gth_status_update: '#src/tools/gthStatusUpdateTool.js';
     /**
      * Web fetch tool.
      */
-    readonly gth_web_fetch: "#src/tools/gthWebFetchTool.js";
+    readonly gth_web_fetch: '#src/tools/gthWebFetchTool.js';
     /**
      * AG-UI A2UI surface tool: lets the agent render an A2UI surface in the web client.
      */
-    readonly show_a2ui_surface: "#src/tools/showA2UISurfaceTool.js";
+    readonly show_a2ui_surface: '#src/tools/showA2UISurfaceTool.js';
+    /**
+     * Checklist / todo planning tool for the lean agent (the `write_todos` equivalent). Enabled
+     * by default (see {@link DEFAULT_CONFIG}); disable by setting your own `builtInTools`.
+     */
+    readonly gth_checklist: '#src/tools/gthChecklistTool.js';
+    /**
+     * Content-search (grep) tool: ripgrep-backed regex search over file CONTENTS, with an
+     * in-process JS fallback when `rg` is absent. Permission-light (no shell approval) and
+     * available in every mode. Named `gth_grep` to avoid colliding with the deep backend's
+     * built-in `grep`. Enabled by default (see {@link DEFAULT_CONFIG.builtInTools}, GS2-51); disable
+     * with `{ "builtInTools": { "gth_grep": { "enabled": false } } }`. Its searched corpus is
+     * selectable via the `fileSet` tool-config key (`gitignore` default / `all`).
+     */
+    readonly gth_grep: '#src/tools/gthGrepTool.js';
 };
 /**
  * Get default tools based on filesystem and built-in tools configuration

package/dist/builtInToolsConfig.js

@@ -3,6 +3,7 @@
  * Built-in tools config. {@link AVAILABLE_BUILT_IN_TOOLS} has a list of available tools.
  */
 import GthFileSystemToolkit from '#src/tools/GthFileSystemToolkit.js';
+import { getEffectiveDevToolsConfig, normalizeBuiltInTools, isBuiltInToolEntryEnabled, DEV_TOOL_NAMES, } from '@gaunt-sloth/core/config.js';
 import { displayWarning } from '@gaunt-sloth/core/utils/consoleUtils.js';
 import { getCurrentWorkDir } from '@gaunt-sloth/core/utils/systemUtils.js';
 import GthDevToolkit from '#src/tools/GthDevToolkit.js';
@@ -25,6 +26,20 @@ export const AVAILABLE_BUILT_IN_TOOLS = {
      * AG-UI A2UI surface tool: lets the agent render an A2UI surface in the web client.
      */
     show_a2ui_surface: '#src/tools/showA2UISurfaceTool.js',
+    /**
+     * Checklist / todo planning tool for the lean agent (the `write_todos` equivalent). Enabled
+     * by default (see {@link DEFAULT_CONFIG}); disable by setting your own `builtInTools`.
+     */
+    gth_checklist: '#src/tools/gthChecklistTool.js',
+    /**
+     * Content-search (grep) tool: ripgrep-backed regex search over file CONTENTS, with an
+     * in-process JS fallback when `rg` is absent. Permission-light (no shell approval) and
+     * available in every mode. Named `gth_grep` to avoid colliding with the deep backend's
+     * built-in `grep`. Enabled by default (see {@link DEFAULT_CONFIG.builtInTools}, GS2-51); disable
+     * with `{ "builtInTools": { "gth_grep": { "enabled": false } } }`. Its searched corpus is
+     * selectable via the `fileSet` tool-config key (`gitignore` default / `all`).
+     */
+    gth_grep: '#src/tools/gthGrepTool.js',
 };
 /**
  * Get default tools based on filesystem and built-in tools configuration
@@ -33,24 +48,29 @@ export async function getDefaultTools(config, command) {
     const filesystemTools = filterFilesystemTools(config.filesystem, config.aiignore, config.binaryFormats);
     const builtInTools = await getBuiltInTools(config);
     // Dev tools (run commands etc.) are available to the interactive `code` command and to the
-    // scripted `exec` command — both are "do-the-job" runs — each via its own per-command config.
-    // `ask --write` (config.askWriteMode) opts `ask` into the same do-the-job tools, reusing the
-    // devTools config the --write flag copied onto commands.ask.
+    // scripted `exec` command — both are "do-the-job" runs. `ask --write` (config.askWriteMode) opts
+    // `ask` into the same do-the-job tools. CFG-18: the dev/shell config is resolved from the unified
+    // `builtInTools` registry by the shared core resolver (was per-command `devTools`).
     const askWrite = command === 'ask' && config.askWriteMode === true;
-    const devToolConfig = command === 'exec'
-        ? config.commands?.exec?.devTools
-        : askWrite
-            ? config.commands?.ask?.devTools
-            : config.commands?.code?.devTools;
+    const devToolConfig = getEffectiveDevToolsConfig(config, command);
     const devTools = await filterDevTools(askWrite ? 'code' : command, devToolConfig);
     const customTools = getCustomTools(config, command);
     return [...filesystemTools, ...devTools, ...customTools, ...builtInTools];
 }
 async function filterDevTools(command, devToolConfig) {
-    if ((command !== 'code' && command !== 'exec') || !devToolConfig) {
+    // Dev tools only apply to the do-the-job commands (`code` / `exec`; `ask --write` is mapped
+    // to `code` by the caller). EXT-12: for `code` the toolkit is constructed even when no
+    // devTools config is present, so the shell tool's absent-config default (ON in `code`) can
+    // emit `run_shell_command` (still gated). For `exec` we keep the prior behaviour — no config
+    // means no dev tools — by short-circuiting when the config is absent.
+    if (command !== 'code' && command !== 'exec') {
         return [];
     }
-    const toolkit = new GthDevToolkit(devToolConfig);
+    if (command === 'exec' && !devToolConfig) {
+        return [];
+    }
+    // Pass the command so GthDevToolkit resolves the shell default for the active mode.
+    const toolkit = new GthDevToolkit(devToolConfig ?? {}, command);
     return [...toolkit.getTools()];
 }
 /**
@@ -126,10 +146,17 @@ function filterFilesystemTools(filesystemConfig, aiignoreConfig, binaryFormats)
  */
 async function getBuiltInTools(config) {
     const tools = [];
-    if (!config.builtInTools) {
-        return tools;
-    }
-    for (const toolName of config.builtInTools) {
+    // CFG-18: `builtInTools` may be a string[] or the widened registry — normalize to a name→value
+    // lookup. Dev/shell tools (run_*, run_shell_command) are emitted by GthDevToolkit via the dev
+    // bucket, so skip them here (a registry entry for them is legitimate, not an unknown built-in).
+    const registry = normalizeBuiltInTools(config.builtInTools);
+    for (const [toolName, value] of Object.entries(registry)) {
+        if (DEV_TOOL_NAMES.includes(toolName)) {
+            continue;
+        }
+        if (!isBuiltInToolEntryEnabled(value)) {
+            continue;
+        }
         if (toolName in AVAILABLE_BUILT_IN_TOOLS) {
             try {
                 const tool = await import(AVAILABLE_BUILT_IN_TOOLS[toolName]);

package/dist/builtInToolsConfig.js.map

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

package/dist/core/GthDeepAgent.d.ts

@@ -1,10 +1,12 @@
 import type { GthConfig } from '@gaunt-sloth/core/config.js';
 import { GthAbstractAgent } from '@gaunt-sloth/core/core/GthAbstractAgent.js';
 import { type GthCommand } from '@gaunt-sloth/core/core/types.js';
+export { appendOsShellNote, appendCwdNote, appendCommitCoAuthorNote, appendModelContextNote, resolveModelIdentity, OS_SHELL_GUIDANCE, } from '@gaunt-sloth/core/utils/systemPromptNotes.js';
 import type { StructuredToolInterface } from '@langchain/core/tools';
 import type { BaseCheckpointSaver } from '@langchain/langgraph';
+import { type InterruptOnConfig } from 'langchain';
 import { type FilesystemPermission } from '#src/core/deepAgentPermissions.js';
-import type { DebugCapture, DebugRequestExtras } from '#src/core/debugCapture.js';
+export { extractDebugRequestExtras } from '#src/core/debugCapture.js';
 /**
  * The subset of `createDeepAgent` params that are independent of the transport
  * (the local runner vs. the ACP server). Both {@link GthDeepAgent.init} (which adds the
@@ -31,6 +33,21 @@ export interface GthDeepAgentParams {
      * no prompt content is composed (lets deepagents use only its base prompt).
      */
     systemPrompt: string | undefined;
+    /**
+     * Per-tool human-in-the-loop configuration passed straight to
+     * `createDeepAgent({ interruptOn })` (deepagents installs LangChain's
+     * `humanInTheLoopMiddleware` for it). A matching tool call suspends the graph with a
+     * `__interrupt__` (a `HITLRequest`) so a consumer can approve/reject before the tool runs;
+     * resume with `new Command({ resume: { decisions: [...] } })` on the same `thread_id`.
+     *
+     * gsloth sets this for the opt-in `run_shell_command` tool whenever the shell tool is
+     * enabled — including under `run_shell_command.yolo` in interactive `code` mode, where the tool
+     * stays gated so the runtime `/auto-approve` flag governs it (the runner seeds that flag ON
+     * from shellYolo and auto-approves silently). It is left `undefined` only for a non-interactive
+     * yolo run (exec / ask --write), whose single-shot path does not drain interrupts, so the tool
+     * there runs inline without suspending. See `getAgentBuildParams`.
+     */
+    interruptOn?: Record<string, boolean | InterruptOnConfig>;
 }
 /**
  * Deep agent: builds a `createDeepAgent` graph (deepagents). All run/stream/event
@@ -43,7 +60,10 @@ export interface GthDeepAgentParams {
  *   {@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).
+ *   (`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
@@ -51,13 +71,6 @@ export interface GthDeepAgentParams {
  * middleware hardening without re-running `createDeepAgent` locally.
  */
 export declare class GthDeepAgent extends GthAbstractAgent {
-    /**
-     * Opt-in debug sink for the TUI `/debug` panel. Set AFTER {@link init} via
-     * `runner.getAgent()`; read lazily inside the `wrapModelCall` middleware so that when it
-     * is `undefined` (the normal path) the middleware is a transparent pass-through. Never
-     * touched by the lean agent or the AG-UI server, so those contracts are unchanged.
-     */
-    debugCapture: DebugCapture | undefined;
     init(command: GthCommand | undefined, configIn: GthConfig, checkpointer?: BaseCheckpointSaver | undefined): Promise<void>;
     /**
      * Assemble the transport-agnostic {@link GthDeepAgentParams}: resolve tools (with the
@@ -69,8 +82,45 @@ export declare class GthDeepAgent extends GthAbstractAgent {
     buildDeepAgentParams(command: GthCommand | undefined, configIn: GthConfig): Promise<GthDeepAgentParams>;
 }
 /**
- * Assemble the non-message request parts ({@link DebugRequestExtras}) for the `/debug`
- * panel from a `wrapModelCall` request, defensively and key-free. Never throws (the caller
- * already guards, but a debug sink must never break a run) and never dumps the raw model.
+ * 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 declare const PATH_NAMESPACE_GUIDANCE: string;
+/**
+ * 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 declare function appendVirtualCwdNote(systemPrompt: string | undefined): string;
+/**
+ * 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 declare function extractDebugRequestExtras(request: unknown): DebugRequestExtras | undefined;
+export declare function createPathNamespaceCorrectionMiddleware(appendCorrection: boolean): import("langchain").AgentMiddleware<undefined, undefined, unknown, readonly (import("@langchain/core/tools").ServerTool | import("@langchain/core/tools").ClientTool)[], readonly []>;