@gaunt-sloth/agent 0.1.8 → 2.0.0-alpha.1

package/dist/middleware/registry.js

@@ -0,0 +1,124 @@
+/**
+ * @packageDocumentation
+ * Middleware registry for Gaunt Sloth Assistant.
+ *
+ * This module provides factory functions for creating predefined middleware instances
+ * and a resolver to convert middleware configurations into middleware objects.
+ */
+import { displayWarning } from '@gaunt-sloth/core/utils/consoleUtils.js';
+import { debugLog } from '@gaunt-sloth/core/utils/debugUtils.js';
+import { anthropicPromptCachingMiddleware, summarizationMiddleware, } from 'langchain';
+import { createBinaryContentInjectionMiddleware, } from '#src/middleware/binaryContentInjectionMiddleware.js';
+const predefinedMiddlewareFactories = {
+    /**
+     * Anthropic prompt caching middleware. see https://docs.langchain.com/oss/javascript/langchain/middleware#anthropic-prompt-caching
+     */
+    'anthropic-prompt-caching': (settings, gthConfig) => createAnthropicPromptCachingMiddleware(settings, gthConfig),
+    /**
+     * Summarization middleware. see https://docs.langchain.com/oss/javascript/langchain/middleware#summarization
+     */
+    summarization: (settings, gthConfig) => createSummarizationMiddleware(settings, gthConfig),
+    /**
+     * Binary content injection middleware.
+     * Intercepts tool results containing binary data (images, PDFs, audio) and injects them
+     * as HumanMessage content blocks before the next model call.
+     * This works around LangChain's limitation where ToolMessage doesn't support binary content.
+     */
+    'binary-content-injection': (settings, gthConfig) => createBinaryContentInjectionMiddleware(settings, gthConfig),
+};
+function isPredefinedMiddlewareName(name) {
+    return name in predefinedMiddlewareFactories;
+}
+function isPredefinedMiddlewareObject(config) {
+    return (typeof config === 'object' &&
+        config !== null &&
+        'name' in config &&
+        typeof config.name === 'string' &&
+        isPredefinedMiddlewareName(config.name));
+}
+/**
+ * Create Anthropic prompt caching middleware.
+ * This middleware adds cache control headers to reduce API costs.
+ */
+export async function createAnthropicPromptCachingMiddleware(config, _) {
+    debugLog(`Creating Anthropic prompt caching middleware with TTL: ${config.ttl || 'default'}`);
+    // Dynamic import for async initialization
+    return Promise.resolve(anthropicPromptCachingMiddleware({ ttl: config.ttl }));
+}
+/**
+ * Create summarization middleware.
+ * This middleware automatically condenses conversation history when approaching token limits.
+ *
+ * @param config - Configuration for the middleware
+ * @param gthConfig - Full Gaunt Sloth configuration
+ * @returns Middleware object
+ */
+export async function createSummarizationMiddleware(config, gthConfig) {
+    debugLog('Creating summarization middleware');
+    return Promise.resolve(summarizationMiddleware({
+        model: config.model || gthConfig.llm,
+        ...config,
+    }));
+}
+/**
+ * Resolve middleware configuration into middleware instances.
+ * Converts string identifiers and config objects into actual middleware.
+ * Automatically injects binary-content-injection middleware if binaryFormats is enabled.
+ *
+ * @param configs - Array of middleware configurations
+ * @param gthConfig - Full Gaunt Sloth configuration
+ * @returns Array of middleware instances
+ */
+export async function resolveMiddleware(configs, gthConfig) {
+    const configsToResolve = configs || [];
+    const middleware = [];
+    // Auto-inject binary-content-injection middleware if binaryFormats is configured
+    // It is only auto-injected if binaryFormats is enabled.
+    const hasBinaryFormats = gthConfig.binaryFormats !== undefined &&
+        gthConfig.binaryFormats !== false &&
+        gthConfig.binaryFormats.length > 0;
+    const hasBinaryMiddleware = configsToResolve.some((c) => c === 'binary-content-injection' ||
+        (typeof c === 'object' && 'name' in c && c.name === 'binary-content-injection'));
+    if (hasBinaryFormats && !hasBinaryMiddleware) {
+        debugLog('Auto-injecting binary-content-injection middleware (binaryFormats is enabled)');
+        middleware.push(await createPredefinedMiddleware('binary-content-injection', {}, gthConfig));
+    }
+    for (const config of configsToResolve) {
+        try {
+            // Handle string configuration (predefined middleware with defaults)
+            if (typeof config === 'string') {
+                middleware.push(await createPredefinedMiddleware(config, {}, gthConfig));
+            }
+            // Handle predefined middleware with custom settings
+            else if (isPredefinedMiddlewareObject(config)) {
+                const { name, ...settings } = config;
+                middleware.push(await createPredefinedMiddleware(name, settings, gthConfig));
+            }
+            // Handle custom middleware object (JS config only)
+            else {
+                debugLog('Adding custom middleware');
+                middleware.push(config);
+            }
+        }
+        catch (error) {
+            displayWarning(`Failed to create middleware: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return middleware;
+}
+/**
+ * Create a predefined middleware instance by name.
+ *
+ * @param name - Name of the predefined middleware
+ * @param settings - Configuration settings for the middleware
+ * @param gthConfig - Full Gaunt Sloth configuration
+ * @returns Middleware instance
+ */
+async function createPredefinedMiddleware(name, settings, gthConfig) {
+    if (!isPredefinedMiddlewareName(name)) {
+        throw new Error(`Unknown predefined middleware: ${name}`);
+    }
+    const factory = predefinedMiddlewareFactories[name];
+    return factory(settings, gthConfig);
+}
+//# sourceMappingURL=registry.js.map

package/dist/middleware/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/middleware/registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,OAAO,EAAE,cAAc,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,EAAE,QAAQ,EAAE,MAAM,uCAAuC,CAAC;AACjE,OAAO,EACL,gCAAgC,EAChC,uBAAuB,GAExB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,sCAAsC,GAEvC,MAAM,qDAAqD,CAAC;AAO7D,MAAM,6BAA6B,GAAG;IACpC;;OAEG;IACH,0BAA0B,EAAE,CAC1B,QAAiC,EACjC,SAAoB,EACM,EAAE,CAC5B,sCAAsC,CAAC,QAAwC,EAAE,SAAS,CAAC;IAC7F;;OAEG;IACH,aAAa,EAAE,CACb,QAAiC,EACjC,SAAoB,EACM,EAAE,CAC5B,6BAA6B,CAAC,QAA+B,EAAE,SAAS,CAAC;IAC3E;;;;;OAKG;IACH,0BAA0B,EAAE,CAC1B,QAAiC,EACjC,SAAoB,EACM,EAAE,CAC5B,sCAAsC,CACpC,QAAoD,EACpD,SAAS,CACV;CACkD,CAAC;AAExD,SAAS,0BAA0B,CACjC,IAAY;IAEZ,OAAO,IAAI,IAAI,6BAA6B,CAAC;AAC/C,CAAC;AAED,SAAS,4BAA4B,CACnC,MAAwB;IAExB,OAAO,CACL,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,KAAK,IAAI;QACf,MAAM,IAAI,MAAM;QAChB,OAAQ,MAA4B,CAAC,IAAI,KAAK,QAAQ;QACtD,0BAA0B,CAAE,MAA2B,CAAC,IAAI,CAAC,CAC9D,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,sCAAsC,CAC1D,MAAoC,EACpC,CAAY;IAEZ,QAAQ,CAAC,0DAA0D,MAAM,CAAC,GAAG,IAAI,SAAS,EAAE,CAAC,CAAC;IAE9F,0CAA0C;IAC1C,OAAO,OAAO,CAAC,OAAO,CAAC,gCAAgC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;AAChF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,6BAA6B,CACjD,MAA2B,EAC3B,SAAoB;IAEpB,QAAQ,CAAC,mCAAmC,CAAC,CAAC;IAE9C,OAAO,OAAO,CAAC,OAAO,CACpB,uBAAuB,CAAC;QACtB,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,SAAS,CAAC,GAAG;QACpC,GAAG,MAAM;KACV,CAAC,CACH,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAAuC,EACvC,SAAoB;IAEpB,MAAM,gBAAgB,GAAG,OAAO,IAAI,EAAE,CAAC;IACvC,MAAM,UAAU,GAAsB,EAAE,CAAC;IAEzC,iFAAiF;IACjF,wDAAwD;IACxD,MAAM,gBAAgB,GACpB,SAAS,CAAC,aAAa,KAAK,SAAS;QACrC,SAAS,CAAC,aAAa,KAAK,KAAK;QACjC,SAAS,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,CAAC;IACrC,MAAM,mBAAmB,GAAG,gBAAgB,CAAC,IAAI,CAC/C,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,KAAK,0BAA0B;QAChC,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,0BAA0B,CAAC,CAClF,CAAC;IAEF,IAAI,gBAAgB,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAC7C,QAAQ,CAAC,+EAA+E,CAAC,CAAC;QAC1F,UAAU,CAAC,IAAI,CAAC,MAAM,0BAA0B,CAAC,0BAA0B,EAAE,EAAE,EAAE,SAAS,CAAC,CAAC,CAAC;IAC/F,CAAC;IAED,KAAK,MAAM,MAAM,IAAI,gBAAgB,EAAE,CAAC;QACtC,IAAI,CAAC;YACH,oEAAoE;YACpE,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;gBAC/B,UAAU,CAAC,IAAI,CAAC,MAAM,0BAA0B,CAAC,MAAM,EAAE,EAAE,EAAE,SAAS,CAAC,CAAC,CAAC;YAC3E,CAAC;YACD,oDAAoD;iBAC/C,IAAI,4BAA4B,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC9C,MAAM,EAAE,IAAI,EAAE,GAAG,QAAQ,EAAE,GAAG,MAAM,CAAC;gBACrC,UAAU,CAAC,IAAI,CAAC,MAAM,0BAA0B,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC;YAC/E,CAAC;YACD,mDAAmD;iBAC9C,CAAC;gBACJ,QAAQ,CAAC,0BAA0B,CAAC,CAAC;gBACrC,UAAU,CAAC,IAAI,CAAC,MAAyB,CAAC,CAAC;YAC7C,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,cAAc,CACZ,gCAAgC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CACzF,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;;;;GAOG;AACH,KAAK,UAAU,0BAA0B,CACvC,IAAY,EACZ,QAAiC,EACjC,SAAoB;IAEpB,IAAI,CAAC,0BAA0B,CAAC,IAAI,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,kCAAkC,IAAI,EAAE,CAAC,CAAC;IAC5D,CAAC;IAED,MAAM,OAAO,GAAG,6BAA6B,CAAC,IAAI,CAAC,CAAC;IACpD,OAAO,OAAO,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;AACtC,CAAC"}

package/dist/middleware/types.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @packageDocumentation
+ * Type definitions for middleware configuration in Gaunt Sloth Assistant.
+ *
+ * Middleware provides hooks to intercept and control agent execution at critical points.
+ * This module defines the configuration interfaces for both predefined and custom middleware.
+ */
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import { AgentMiddleware } from 'langchain';
+/**
+ * Predefined middleware types that can be configured via JSON config.
+ */
+export type PredefinedMiddlewareName = 'anthropic-prompt-caching' | 'summarization' | 'binary-content-injection';
+/**
+ * Configuration for Anthropic prompt caching middleware.
+ */
+export interface AnthropicPromptCachingConfig {
+    /**
+     * Cache TTL (time to live).
+     * Examples: "5m" for 5 minutes, "1h" for 1 hour
+     */
+    ttl?: '5m' | '1h';
+}
+/**
+ * Configuration for summarization middleware.
+ */
+export interface SummarizationConfig {
+    /**
+     * Model to use for summarization.
+     * If not provided, uses the main LLM from config.
+     */
+    model?: BaseChatModel;
+    /**
+     * Maximum tokens before triggering summarization.
+     * Set one of:
+     */
+    trigger?: {
+        fraction?: number;
+        tokens?: number;
+        messages?: number;
+    };
+    /**
+     * How many tokens, messages, or a fraction of context to keep.
+     * Set one of:
+     */
+    keep?: {
+        fraction?: number;
+        tokens?: number;
+        messages?: number;
+    };
+    /**
+     * Custom prompt template for summarization.
+     */
+    summaryPrompt?: string;
+}
+/**
+ * Configuration for image format transformation middleware.
+ */
+export interface ImageFormatTransformConfig {
+    /**
+     * Detail level for image processing.
+     * Examples: "low", "high", "auto"
+     */
+    detail?: 'low' | 'high' | 'auto';
+}
+/**
+ * Configuration for binary content injection middleware.
+ * This middleware intercepts tool results containing binary data (images, PDFs, audio)
+ * and injects them as HumanMessage content blocks.
+ */
+export interface BinaryContentInjectionConfig {
+}
+/**
+ * Union type of all predefined middleware configurations.
+ */
+export type PredefinedMiddlewareConfig = ({
+    name: 'anthropic-prompt-caching';
+} & AnthropicPromptCachingConfig) | ({
+    name: 'summarization';
+} & SummarizationConfig) | ({
+    name: 'binary-content-injection';
+} & BinaryContentInjectionConfig);
+/**
+ * Middleware configuration that can be specified in JSON or JS config.
+ * - String: Name of predefined middleware with default settings
+ * - PredefinedMiddlewareConfig: Predefined middleware with custom settings (JSON compatible)
+ * - CustomMiddleware: Custom middleware object (JS config only)
+ */
+export type MiddlewareConfig = string | PredefinedMiddlewareConfig | AgentMiddleware;

package/dist/middleware/types.js

@@ -0,0 +1,9 @@
+/**
+ * @packageDocumentation
+ * Type definitions for middleware configuration in Gaunt Sloth Assistant.
+ *
+ * Middleware provides hooks to intercept and control agent execution at critical points.
+ * This module defines the configuration interfaces for both predefined and custom middleware.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/middleware/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/middleware/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/modules/a2a/A2AClientWrapper.d.ts

@@ -0,0 +1,22 @@
+/** Configuration for A2A client */
+export interface A2AClientConfig {
+    /** Unique identifier for the agent */
+    agentId: string;
+    /** URL endpoint for the A2A agent */
+    agentUrl: string;
+}
+/**
+ * Wrapper around the A2A SDK client for communicating with external agents.
+ * @experimental
+ */
+export declare class A2AClientWrapper {
+    private client;
+    private config;
+    constructor(config: A2AClientConfig);
+    /**
+     * Sends a message to the A2A agent and returns the response.
+     * @param messageText - The message to send to the agent
+     * @returns The agent's response as a string
+     */
+    sendMessage(messageText: string): Promise<string>;
+}

package/dist/modules/a2a/A2AClientWrapper.js

@@ -0,0 +1,63 @@
+/**
+ * @module A2AClientWrapper
+ * Wrapper for A2A (Agent-to-Agent) protocol client.
+ * @experimental A2A support is experimental and may change.
+ */
+import { A2AClient } from '@a2a-js/sdk/client';
+import { debugLog, debugLogError } from '@gaunt-sloth/core/utils/debugUtils.js';
+import { v4 as uuidv4 } from 'uuid';
+/**
+ * Wrapper around the A2A SDK client for communicating with external agents.
+ * @experimental
+ */
+export class A2AClientWrapper {
+    client;
+    config;
+    constructor(config) {
+        this.config = config;
+        // Initialize with agent URL. The SDK will fetch the agent card.
+        this.client = new A2AClient(config.agentUrl);
+    }
+    /**
+     * Sends a message to the A2A agent and returns the response.
+     * @param messageText - The message to send to the agent
+     * @returns The agent's response as a string
+     */
+    async sendMessage(messageText) {
+        debugLog(`Sending message to A2A agent ${this.config.agentId} at ${this.config.agentUrl}: ${messageText}`);
+        try {
+            const messageId = uuidv4();
+            const response = await this.client.sendMessage({
+                message: {
+                    kind: 'message',
+                    messageId: messageId,
+                    role: 'user',
+                    parts: [{ kind: 'text', text: messageText }],
+                },
+            });
+            debugLog(`Received response from A2A agent: ${JSON.stringify(response)}`);
+            // Check for error response
+            if ('error' in response) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                throw new Error(`A2A Error: ${JSON.stringify(response.error)}`);
+            }
+            // Extract text from response
+            // The result is likely a TaskStatus which contains a message
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const result = response.result;
+            if (result.message && result.message.parts && result.message.parts.length > 0) {
+                // Assuming the first part is text for now
+                return result.message.parts[0].text || JSON.stringify(result.message.parts);
+            }
+            else if (result.state) {
+                return `Task state: ${result.state}`;
+            }
+            return JSON.stringify(result);
+        }
+        catch (error) {
+            debugLogError('Error sending message to A2A agent', error);
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=A2AClientWrapper.js.map

package/dist/modules/a2a/A2AClientWrapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"A2AClientWrapper.js","sourceRoot":"","sources":["../../../src/modules/a2a/A2AClientWrapper.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,uCAAuC,CAAC;AAChF,OAAO,EAAE,EAAE,IAAI,MAAM,EAAE,MAAM,MAAM,CAAC;AAUpC;;;GAGG;AACH,MAAM,OAAO,gBAAgB;IACnB,MAAM,CAAY;IAClB,MAAM,CAAkB;IAEhC,YAAY,MAAuB;QACjC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,gEAAgE;QAChE,IAAI,CAAC,MAAM,GAAG,IAAI,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC/C,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,WAAW,CAAC,WAAmB;QACnC,QAAQ,CACN,gCAAgC,IAAI,CAAC,MAAM,CAAC,OAAO,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,KAAK,WAAW,EAAE,CACjG,CAAC;QACF,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,MAAM,EAAE,CAAC;YAC3B,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC;gBAC7C,OAAO,EAAE;oBACP,IAAI,EAAE,SAAS;oBACf,SAAS,EAAE,SAAS;oBACpB,IAAI,EAAE,MAAM;oBACZ,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;iBAC7C;aACF,CAAC,CAAC;YAEH,QAAQ,CAAC,qCAAqC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;YAE1E,2BAA2B;YAC3B,IAAI,OAAO,IAAI,QAAQ,EAAE,CAAC;gBACxB,8DAA8D;gBAC9D,MAAM,IAAI,KAAK,CAAC,cAAc,IAAI,CAAC,SAAS,CAAE,QAAgB,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAC3E,CAAC;YAED,6BAA6B;YAC7B,6DAA6D;YAC7D,8DAA8D;YAC9D,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAa,CAAC;YAEtC,IAAI,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC9E,0CAA0C;gBAC1C,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YAC9E,CAAC;iBAAM,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;gBACxB,OAAO,eAAe,MAAM,CAAC,KAAK,EAAE,CAAC;YACvC,CAAC;YAED,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAChC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,aAAa,CAAC,oCAAoC,EAAE,KAAK,CAAC,CAAC;YAC3D,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;CACF"}

package/dist/modules/acpModule.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @packageDocumentation
+ * ACP (Agent Client Protocol) server entry for the Gaunt Sloth deep agent.
+ *
+ * This is a parallel front-door to the AG-UI server ({@link startAgUiServer}); both expose
+ * the SAME {@link GthDeepAgent}. AG-UI stays the robot-controller path; ACP is an additional
+ * way to drive Galvanized Pukeko from an ACP host (Zed, JetBrains, a future Pukeko client).
+ *
+ * It reuses {@link GthDeepAgent.buildDeepAgentParams} so tool resolution (with the filesystem
+ * disabled so deepagents owns fs access), the `.aiignore`/filesystem→permission mapping and the
+ * fs-denial-softening middleware are identical to the local runner path. `deepagents-acp`
+ * supplies the rest of the coding-agent surface itself: a per-session `ACPFilesystemBackend`
+ * (proxying reads/writes through the ACP client so unsaved editor buffers are visible), the
+ * checkpointer, interactive `session/request_permission` gating, and tool-call/plan reporting.
+ */
+import type { GthConfig } from '@gaunt-sloth/core/config.js';
+import type { GthCommand } from '@gaunt-sloth/core/core/types.js';
+export interface StartAcpServerOptions {
+    /** Agent name advertised to the ACP client (used for session routing). */
+    name?: string;
+    /** Human-readable description shown to ACP clients when listing agents. */
+    description?: string;
+    /** gsloth command whose config/prompt to apply (defaults to `'code'`, the full-fs agent). */
+    command?: GthCommand;
+}
+/**
+ * Start the Gaunt Sloth deep agent as an ACP server over stdio.
+ *
+ * Resolves once the stdio transport is listening; the process then stays alive serving the
+ * ACP host until it is terminated. The returned promise rejecting means startup failed.
+ *
+ * NOTE: deepagents-acp 0.1.12 does NOT forward `permissions` to `createDeepAgent` — on the ACP
+ * path fs gating is delegated to the host's interactive permission prompts, not gsloth's
+ * `.aiignore`→permissions mapping. `permissions` is still passed here for forward-compatibility
+ * (if a later deepagents-acp forwards it, gsloth's mapping applies with no change here).
+ */
+export declare function startAcpServer(config: GthConfig, options?: StartAcpServerOptions): Promise<void>;

package/dist/modules/acpModule.js

@@ -0,0 +1,67 @@
+/**
+ * @packageDocumentation
+ * ACP (Agent Client Protocol) server entry for the Gaunt Sloth deep agent.
+ *
+ * This is a parallel front-door to the AG-UI server ({@link startAgUiServer}); both expose
+ * the SAME {@link GthDeepAgent}. AG-UI stays the robot-controller path; ACP is an additional
+ * way to drive Galvanized Pukeko from an ACP host (Zed, JetBrains, a future Pukeko client).
+ *
+ * It reuses {@link GthDeepAgent.buildDeepAgentParams} so tool resolution (with the filesystem
+ * disabled so deepagents owns fs access), the `.aiignore`/filesystem→permission mapping and the
+ * fs-denial-softening middleware are identical to the local runner path. `deepagents-acp`
+ * supplies the rest of the coding-agent surface itself: a per-session `ACPFilesystemBackend`
+ * (proxying reads/writes through the ACP client so unsaved editor buffers are visible), the
+ * checkpointer, interactive `session/request_permission` gating, and tool-call/plan reporting.
+ */
+import { getProcessCwd, stderr } from '@gaunt-sloth/core/utils/systemUtils.js';
+import { debugLog } from '@gaunt-sloth/core/utils/debugUtils.js';
+import { GthDeepAgent } from '#src/core/GthDeepAgent.js';
+import { startGthAcpServer } from '#src/core/gthAcpServer.js';
+import { createResolvers } from '#src/resolvers.js';
+/**
+ * ACP-side status routing: the ACP protocol owns stdout (JSON-RPC framing), so agent
+ * status/info must never touch it. Route everything to stderr.
+ */
+const acpStatusUpdate = (_level, message) => {
+    stderr.write(`${message}\n`);
+};
+/**
+ * Start the Gaunt Sloth deep agent as an ACP server over stdio.
+ *
+ * Resolves once the stdio transport is listening; the process then stays alive serving the
+ * ACP host until it is terminated. The returned promise rejecting means startup failed.
+ *
+ * NOTE: deepagents-acp 0.1.12 does NOT forward `permissions` to `createDeepAgent` — on the ACP
+ * path fs gating is delegated to the host's interactive permission prompts, not gsloth's
+ * `.aiignore`→permissions mapping. `permissions` is still passed here for forward-compatibility
+ * (if a later deepagents-acp forwards it, gsloth's mapping applies with no change here).
+ */
+export async function startAcpServer(config, options = {}) {
+    const command = options.command ?? 'code';
+    const agent = new GthDeepAgent(acpStatusUpdate, createResolvers());
+    const params = await agent.buildDeepAgentParams(command, config);
+    // gsloth's composed system prompt (backstory + guidelines + per-command mode prompt + system
+    // prompt) comes back on `params.systemPrompt` — the SAME prompt the local runner passes to
+    // createDeepAgent. ACP has no per-turn hook, so it sets the agent's `systemPrompt` here.
+    const systemPrompt = params.systemPrompt;
+    // workspaceRoot is only the startup default: startGthAcpServer re-roots the filesystem backend
+    // to each ACP session's `cwd` (the IDE's project root). Use the raw process cwd, not
+    // getCurrentWorkDir() — its INIT_CWD preference leaks stale paths into this long-lived subprocess.
+    const workspaceRoot = getProcessCwd();
+    debugLog(`Starting ACP server (command: ${command}, startup workspace: ${workspaceRoot})`);
+    await startGthAcpServer({
+        agents: {
+            name: options.name ?? 'gaunt-sloth',
+            description: options.description ?? 'Gaunt Sloth deep coding agent',
+            model: params.model,
+            tools: params.tools,
+            systemPrompt,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            middleware: params.middleware,
+            // Forward-compat: ignored by deepagents-acp 0.1.12 (the host gates fs interactively).
+            permissions: params.permissions,
+        },
+        workspaceRoot,
+    });
+}
+//# sourceMappingURL=acpModule.js.map

package/dist/modules/acpModule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"acpModule.js","sourceRoot":"","sources":["../../src/modules/acpModule.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,wCAAwC,CAAC;AAC/E,OAAO,EAAE,QAAQ,EAAE,MAAM,uCAAuC,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAWpD;;;GAGG;AACH,MAAM,eAAe,GAAyB,CAAC,MAAmB,EAAE,OAAe,EAAQ,EAAE;IAC3F,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;AAC/B,CAAC,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,MAAiB,EACjB,UAAiC,EAAE;IAEnC,MAAM,OAAO,GAAe,OAAO,CAAC,OAAO,IAAI,MAAM,CAAC;IAEtD,MAAM,KAAK,GAAG,IAAI,YAAY,CAAC,eAAe,EAAE,eAAe,EAAE,CAAC,CAAC;IACnE,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,oBAAoB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAEjE,6FAA6F;IAC7F,2FAA2F;IAC3F,yFAAyF;IACzF,MAAM,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC;IAEzC,+FAA+F;IAC/F,qFAAqF;IACrF,mGAAmG;IACnG,MAAM,aAAa,GAAG,aAAa,EAAE,CAAC;IACtC,QAAQ,CAAC,iCAAiC,OAAO,wBAAwB,aAAa,GAAG,CAAC,CAAC;IAE3F,MAAM,iBAAiB,CAAC;QACtB,MAAM,EAAE;YACN,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,aAAa;YACnC,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,+BAA+B;YACnE,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,YAAY;YACZ,8DAA8D;YAC9D,UAAU,EAAE,MAAM,CAAC,UAAiB;YACpC,sFAAsF;YACtF,WAAW,EAAE,MAAM,CAAC,WAAW;SAChC;QACD,aAAa;KACd,CAAC,CAAC;AACL,CAAC"}

package/dist/modules/apiAgUiModule.d.ts

@@ -0,0 +1,2 @@
+import { GthConfig } from '@gaunt-sloth/core/config.js';
+export declare function startAgUiServer(config: GthConfig, port: number): Promise<void>;