goatchain 0.0.3 → 0.0.5

package/dist/acp-adapter/ACPAgent.d.ts

@@ -0,0 +1,63 @@
+import type { Agent } from '../agent';
+import type { Session } from '../session';
+import type { ToolApprovalResult } from '../tool';
+import type { ACPAgentOptions, ACPMessage, ACPMetadata } from './types';
+/**
+ * ACPAgent wraps a GoatChain Agent and provides ACP protocol interface
+ *
+ * Key features:
+ * - Session-based routing using session_id from metadata
+ * - Bidirectional protocol conversion (ACP ↔ GoatChain)
+ * - Transparent middleware support (plan mode, subagent, etc.)
+ * - Streaming event forwarding
+ */
+export declare class ACPAgent {
+    private agent;
+    private router;
+    private converter;
+    private debug;
+    constructor(agent: Agent, options?: ACPAgentOptions);
+    /**
+     * Main entry point for receiving ACP messages and returning ACP responses
+     *
+     * This method:
+     * 1. Extracts session_id from metadata
+     * 2. Gets or creates the corresponding GoatChain Session
+     * 3. Converts ACP messages to GoatChain format
+     * 4. Sends messages to the session
+     * 5. Streams back converted ACP responses
+     *
+     * @param messages - Array of ACP messages
+     * @param metadata - Optional metadata including session_id
+     * @returns AsyncGenerator yielding ACP message responses
+     */
+    receiveMessage(messages: ACPMessage[], metadata?: ACPMetadata): AsyncGenerator<ACPMessage, void, void>;
+    /**
+     * Resume a session after tool approval decisions are provided.
+     */
+    receiveWithApprovals(decisions: Record<string, ToolApprovalResult>, metadata?: ACPMetadata): AsyncGenerator<ACPMessage, void, void>;
+    /**
+     * Get information about active sessions
+     */
+    getSessionInfo(): {
+        activeSessions: string[];
+        sessionCount: number;
+    };
+    getSession(sessionId: string): Session | undefined;
+    /**
+     * Manually close a specific session
+     */
+    closeSession(sessionId: string): boolean;
+    /**
+     * Get the wrapped GoatChain agent
+     */
+    getAgent(): Agent;
+    /**
+     * Clean up resources
+     */
+    destroy(): void;
+    /**
+     * Generate a unique session ID
+     */
+    private generateSessionId;
+}

package/dist/acp-adapter/ProtocolConverter.d.ts

@@ -0,0 +1,48 @@
+import type { AgentEvent, Message as GoatChainMessage } from '../types';
+import type { ACPMessage } from './types';
+/**
+ * ProtocolConverter handles bidirectional conversion between
+ * GoatChain events/messages and ACP protocol messages
+ */
+export declare class ProtocolConverter {
+    private debug;
+    constructor(options?: {
+        debug?: boolean;
+    });
+    /**
+     * Convert GoatChain event stream to ACP message stream
+     */
+    convertToACP(events: AsyncIterable<AgentEvent>): AsyncGenerator<ACPMessage, void, void>;
+    /**
+     * Convert subagent event to ACP messages
+     */
+    private convertSubagentEventToACP;
+    /**
+     * Convert regular (non-subagent) event to ACP messages
+     */
+    private convertRegularEvent;
+    /**
+     * Convert ACP messages to GoatChain message format
+     */
+    convertFromACP(messages: ACPMessage[]): GoatChainMessage[];
+    /**
+     * Convert a single ACP message to GoatChain message
+     */
+    private convertSingleMessage;
+    /**
+     * Convert GoatChain ToolCall to ACP ToolCall
+     */
+    private convertToolCallToACP;
+    /**
+     * Convert ACP ToolCall to GoatChain ToolCall
+     */
+    private convertToolCallFromACP;
+    /**
+     * Extract text content from ACP content
+     */
+    private extractTextContent;
+    /**
+     * Format tool result for ACP
+     */
+    private formatToolResult;
+}

package/dist/acp-adapter/SessionRouter.d.ts

@@ -0,0 +1,50 @@
+import type { Agent } from '../agent';
+import type { Session } from '../session';
+/**
+ * SessionRouter manages session lifecycle and routing based on session_id
+ */
+export declare class SessionRouter {
+    private sessions;
+    private sessionContexts;
+    private sessionTimeout;
+    private maxConcurrentSessions;
+    private maxIterations?;
+    private cleanupTimer?;
+    constructor(options?: {
+        sessionTimeout?: number;
+        maxConcurrentSessions?: number;
+        maxIterations?: number;
+    });
+    /**
+     * Get or create a session for the given session_id
+     */
+    getOrCreateSession(sessionId: string, agent: Agent): Promise<Session>;
+    /**
+     * Get an existing session (without creating)
+     */
+    getSession(sessionId: string): Session | undefined;
+    /**
+     * Remove a specific session
+     */
+    removeSession(sessionId: string): boolean;
+    /**
+     * Get all active session IDs
+     */
+    getActiveSessions(): string[];
+    /**
+     * Get session count
+     */
+    getSessionCount(): number;
+    /**
+     * Cleanup expired sessions based on timeout
+     */
+    private cleanupExpiredSessions;
+    /**
+     * Remove the oldest session (by creation time)
+     */
+    private removeOldestSession;
+    /**
+     * Cleanup and stop the router
+     */
+    destroy(): void;
+}

package/dist/acp-adapter/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * ACP (Agent Communication Protocol) Adapter for GoatChain
+ *
+ * This module provides an adapter layer to make GoatChain agents compatible
+ * with the ACP protocol, enabling interoperability with ACP clients.
+ *
+ * @packageDocumentation
+ */
+export { ACPAgent } from './ACPAgent';
+export { ProtocolConverter } from './ProtocolConverter';
+export { SessionRouter } from './SessionRouter';
+export type { ACPAgentOptions, ACPContent, ACPMessage, ACPMetadata, ACPRole, ACPToolCall, ExtendedAgentEvent, SessionContext, SubagentMetadata, } from './types';

package/dist/acp-adapter/types.d.ts

@@ -0,0 +1,95 @@
+import type { AgentEvent } from '../types';
+/**
+ * ACP message role types
+ */
+export type ACPRole = 'user' | 'assistant' | 'tool' | 'system';
+/**
+ * ACP message content (simplified)
+ * In practice, this should match the ACP SDK types
+ */
+export type ACPContent = string | Array<{
+    type: string;
+    text?: string;
+    [key: string]: unknown;
+}>;
+/**
+ * ACP tool call structure
+ */
+export interface ACPToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string | Record<string, unknown>;
+    };
+}
+/**
+ * ACP message structure
+ */
+export interface ACPMessage {
+    role: ACPRole;
+    content?: ACPContent;
+    tool_calls?: ACPToolCall[];
+    tool_call_id?: string;
+    name?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * ACP metadata for session routing
+ */
+export interface ACPMetadata {
+    session_id?: string;
+    [key: string]: unknown;
+}
+/**
+ * Configuration options for ACPAgent
+ */
+export interface ACPAgentOptions {
+    /**
+     * Session timeout in milliseconds (default: 30 minutes)
+     */
+    sessionTimeout?: number;
+    /**
+     * Maximum number of concurrent sessions (default: 10)
+     */
+    maxConcurrentSessions?: number;
+    /**
+     * Enable debug logging
+     */
+    debug?: boolean;
+    /**
+     * Maximum number of loop iterations per session (default: 30)
+     */
+    maxIterations?: number;
+}
+/**
+ * Internal session context
+ */
+export interface SessionContext {
+    sessionId: string;
+    createdAt: number;
+    lastAccessedAt: number;
+}
+/**
+ * Event conversion result for internal use
+ */
+export interface ConversionResult {
+    messages: ACPMessage[];
+    shouldClose?: boolean;
+}
+/**
+ * Subagent event metadata
+ */
+export interface SubagentMetadata {
+    subagent: boolean;
+    subagentId: string;
+    subagentType: string;
+    originalEventType?: string;
+    [key: string]: unknown;
+}
+/**
+ * Extended AgentEvent with potential subagent metadata
+ */
+export type ExtendedAgentEvent = AgentEvent & {
+    metadata?: SubagentMetadata | Record<string, unknown>;
+};

package/dist/acp-server.d.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * Simple ACP Server for GoatChain
+ *
+ * This script exposes a GoatChain agent as an ACP-compliant server via stdio,
+ * enabling integration with ACP clients like Zed editor.
+ *
+ * Usage:
+ *   pnpm acp-server
+ *
+ * Or in Zed settings.json:
+ * {
+ *   "agent_servers": {
+ *     "goatchain": {
+ *       "command": "pnpm",
+ *       "args": ["--dir", "/path/to/GoatChain", "acp-server"]
+ *     }
+ *   }
+ * }
+ */
+import 'dotenv/config';

package/dist/agent/agent.d.ts

@@ -0,0 +1,196 @@
+import type { ModelClient, ModelRef } from '../model';
+import type { BaseSessionManager } from '../session';
+import type { StateStore } from '../state';
+import type { ToolRegistry } from '../tool';
+import type { Middleware, NamedMiddleware } from './middleware';
+import type { AgentLoopState, AgentOptions, CreateSessionOptions, SessionHandleOptions } from './types';
+import { Session } from '../session';
+/**
+ * Agent class - the main orchestrator.
+ *
+ * Agent is a blueprint/configuration that can handle multiple sessions.
+ * It composes model, tools, state store, and session manager.
+ *
+ * Supports middleware pattern for extensible hooks at each loop iteration.
+ */
+export declare class Agent {
+    readonly id: string;
+    readonly name: string;
+    readonly systemPrompt: string;
+    readonly createdAt: number;
+    private _model;
+    private _modelOverride?;
+    private _tools?;
+    private _stateStore?;
+    private _sessionManager?;
+    private _middlewares;
+    private _middlewareCounter;
+    private _middlewareTools;
+    constructor(options: AgentOptions);
+    /**
+     * Get the model client
+     */
+    get model(): ModelClient;
+    /**
+     * Get the effective default model ID.
+     */
+    get modelId(): string;
+    /**
+     * Get the effective default model reference (provider + modelId), if available.
+     *
+     * - If `setModel(ModelRef)` was used, this returns that pinned model.
+     * - Otherwise, returns the model client's default `modelRef` (if supported).
+     */
+    get modelRef(): ModelRef | undefined;
+    /**
+     * Get the available model references (e.g. routing fallback order), if supported by the model client.
+     */
+    get modelRefs(): ModelRef[];
+    /**
+     * Get the tool registry
+     */
+    get tools(): ToolRegistry | undefined;
+    /**
+     * Get the state store
+     */
+    get stateStore(): StateStore | undefined;
+    /**
+     * Get the session manager
+     */
+    get sessionManager(): BaseSessionManager | undefined;
+    /**
+     * Create a new session and return a Session.
+     */
+    createSession(options?: CreateSessionOptions): Promise<Session>;
+    /**
+     * Resume an existing session and return a Session.
+     */
+    resumeSession(sessionId: string, options?: SessionHandleOptions): Promise<Session>;
+    /**
+     * Add middleware to the agent.
+     *
+     * Middleware runs at each loop iteration and can intercept/transform the loop state.
+     * Middleware follows an immutable pattern - it receives state and returns new state via next().
+     *
+     * If the middleware provides a `__createTools` function, the tools will be automatically
+     * registered with a namespace prefix (`<middlewareName>_<toolName>`) and automatically
+     * unregistered when the middleware is removed.
+     *
+     * @param fn - Middleware function
+     * @param name - Optional name for the middleware. If not provided:
+     *               - Uses fn.__middlewareName if available (set by built-in factories)
+     *               - Otherwise auto-generates a unique name
+     * @returns A function to remove this middleware (unsubscribe)
+     *
+     * @example
+     * ```ts
+     * // Named middleware (recommended)
+     * agent.use(async (state, next) => {
+     *   console.log('Before iteration', state.iteration);
+     *   const result = await next(state);
+     *   console.log('After iteration', state.iteration);
+     *   return result;
+     * }, 'logging');
+     *
+     * // Built-in middleware with default name
+     * agent.use(createContextCompressionMiddleware({ ... })); // auto-named 'context-compression'
+     *
+     * // Override default name
+     * agent.use(createPlanModeMiddleware(), 'my-plan-mode');
+     *
+     * // Middleware with tools (auto-registers tools with namespace)
+     * const middleware: Middleware = async (state, next) => next(state);
+     * middleware.__middlewareName = 'plan-mode';
+     * middleware.__createTools = () => [new EnterPlanModeTool()];
+     * agent.use(middleware);
+     * // Tool registered as: 'plan-mode_EnterPlanMode'
+     *
+     * // Anonymous middleware (auto-named)
+     * const unsubscribe = agent.use(async (state, next) => {
+     *   const compressed = { ...state, messages: compress(state.messages) };
+     *   return next(compressed);
+     * });
+     *
+     * // Remove using unsubscribe function
+     * unsubscribe();
+     * ```
+     */
+    use(fn: Middleware<AgentLoopState>, name?: string): () => void;
+    /**
+     * Remove a specific middleware from the agent by name or function reference.
+     *
+     * If the middleware has associated tools (registered via `__createTools`),
+     * they will be automatically unregistered.
+     *
+     * @param nameOrFn - The middleware name (string) or function to remove
+     * @returns true if the middleware was found and removed, false otherwise
+     *
+     * @example
+     * ```ts
+     * // Remove by name (recommended)
+     * agent.use(loggingMiddleware, 'logging');
+     * agent.removeMiddleware('logging');
+     *
+     * // Remove by function reference (legacy)
+     * const loggingMiddleware = async (state, next) => {
+     *   console.log('Before iteration', state.iteration);
+     *   return next(state);
+     * };
+     * agent.use(loggingMiddleware);
+     * agent.removeMiddleware(loggingMiddleware);
+     * ```
+     */
+    removeMiddleware(nameOrFn: string | Middleware<AgentLoopState>): boolean;
+    /**
+     * Clear all middlewares from the agent.
+     *
+     * Also removes all tools that were registered by middlewares via `__createTools`.
+     *
+     * @example
+     * ```ts
+     * agent.clearMiddlewares();
+     * ```
+     */
+    clearMiddlewares(): void;
+    /**
+     * Get the current list of named middlewares (read-only).
+     *
+     * @returns A copy of the middlewares array with their names
+     */
+    get middlewares(): ReadonlyArray<NamedMiddleware<AgentLoopState>>;
+    /**
+     * Get all middleware names.
+     *
+     * @returns Array of middleware names in registration order
+     *
+     * @example
+     * ```ts
+     * agent.use(loggingMiddleware, 'logging');
+     * agent.use(compressionMiddleware, 'compression');
+     * console.log(agent.middlewareNames); // ['logging', 'compression']
+     * ```
+     */
+    get middlewareNames(): string[];
+    /**
+     * Switch to a different model
+     *
+     * @param model - New model client to use, or a `ModelRef` to pin the default model for subsequent requests.
+     */
+    setModel(model: ModelClient): void;
+    setModel(model: ModelRef): void;
+    /**
+     * Get namespaced tool name for a middleware's tool
+     * @private
+     */
+    private _getNamespacedToolName;
+    /**
+     * Register tools provided by a middleware's __createTools function
+     * @private
+     */
+    private _registerMiddlewareTools;
+    /**
+     * Unregister all tools associated with a middleware
+     * @private
+     */
+    private _unregisterMiddlewareTools;
+}

package/dist/agent/errors.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Error thrown when agent execution is aborted via AbortSignal
+ */
+export declare class AgentAbortError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when agent exceeds maximum iterations
+ */
+export declare class AgentMaxIterationsError extends Error {
+    readonly iterations: number;
+    constructor(iterations: number, message?: string);
+}
+/**
+ * Internal control-flow error used to stop streaming when execution is paused.
+ *
+ * This is caught by the Agent and is not intended to be shown to end users.
+ */
+export declare class AgentPauseError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Check if the abort signal has been triggered and throw if so.
+ *
+ * @param signal - AbortSignal to check
+ * @param context - Optional context for error message
+ * @throws AgentAbortError if signal is aborted
+ */
+export declare function ensureNotAborted(signal?: AbortSignal, context?: string): void;

package/dist/agent/hooks/index.d.ts

@@ -0,0 +1,2 @@
+export { HookManager } from './manager';
+export type { HookContext, PostToolUseFailureHook, PostToolUseHook, PreToolUseHook, PreToolUseResult, ToolHooks, } from './types';

package/dist/agent/hooks/manager.d.ts

@@ -0,0 +1,8 @@
+import type { HookContext, PreToolUseResult, ToolHooks } from './types';
+export declare class HookManager {
+    private readonly hooks;
+    constructor(hooks?: ToolHooks);
+    executePreToolUse(context: HookContext): Promise<PreToolUseResult>;
+    executePostToolUse(context: HookContext, result: unknown): Promise<void>;
+    executePostToolUseFailure(context: HookContext, error: Error): Promise<void>;
+}

package/dist/agent/hooks/types.d.ts

@@ -0,0 +1,19 @@
+import type { ToolExecutionContext } from '../../tool';
+import type { ToolCall } from '../../types';
+export interface HookContext {
+    sessionId: string;
+    toolCall: ToolCall;
+    toolContext: ToolExecutionContext;
+}
+export interface PreToolUseResult {
+    allow: boolean;
+    modifiedToolCall?: ToolCall;
+}
+export type PreToolUseHook = (ctx: HookContext) => Promise<PreToolUseResult>;
+export type PostToolUseHook = (ctx: HookContext, result: unknown) => Promise<void>;
+export type PostToolUseFailureHook = (ctx: HookContext, error: Error) => Promise<void>;
+export interface ToolHooks {
+    preToolUse?: PreToolUseHook;
+    postToolUse?: PostToolUseHook;
+    postToolUseFailure?: PostToolUseFailureHook;
+}

package/dist/agent/index.d.ts

@@ -0,0 +1,14 @@
+export { fromLoopCheckpoint, toLoopCheckpoint } from '../middleware/checkpointMiddleware';
+export type { ToCheckpointOptions } from '../middleware/checkpointMiddleware';
+export { compressSessionManually, createContextCompressionMiddleware } from '../middleware/contextCompressionMiddleware';
+export type { ManualCompressionOptions, ManualCompressionResult } from '../middleware/contextCompressionMiddleware';
+export type { CompressionStats, ContextCompressionOptions } from '../middleware/contextCompressionMiddleware';
+export { Agent } from './agent';
+export { AgentAbortError, AgentMaxIterationsError, AgentPauseError, ensureNotAborted } from './errors';
+export { HookManager } from './hooks';
+export type { HookContext, PostToolUseFailureHook, PostToolUseHook, PreToolUseHook, PreToolUseResult, ToolHooks, } from './hooks';
+export { compose } from './middleware';
+export type { Middleware, NamedMiddleware, NextFunction } from './middleware';
+export { countContentTokens, countMessagesTokens, countMessageTokens, countTokens, estimateTokens, } from './tokenCounter';
+export { createInitialLoopState } from './types';
+export type { AgentInput, AgentLoopState, AgentOptions, CreateSessionOptions, SendOptions, SessionHandleOptions, ToolCallWithResult, } from './types';