goatchain 0.0.2 → 0.0.4

package/dist/session/handlers/CheckpointManager.d.ts

@@ -0,0 +1,10 @@
+import type { StateStore } from '../../state';
+import type { AgentLoopCheckpoint } from '../../types';
+export declare class CheckpointManager {
+    private readonly stateStore?;
+    constructor(stateStore?: StateStore | undefined);
+    hasStore(): boolean;
+    saveCheckpoint(checkpoint: AgentLoopCheckpoint): Promise<void>;
+    loadCheckpoint(sessionId: string): Promise<AgentLoopCheckpoint | undefined>;
+    clearCheckpoint(sessionId: string): Promise<void>;
+}

package/dist/session/index.d.ts

@@ -0,0 +1,4 @@
+export { BaseSession } from './base';
+export { BaseSessionManager } from './manager';
+export { Session } from './session';
+export { StateStoreSessionManager } from './stateStoreSessionManager';

package/dist/session/manager.d.ts

@@ -0,0 +1,35 @@
+import type { Session } from './session';
+/**
+ * Abstract base class for session management.
+ *
+ * Handles session lifecycle: creation, retrieval, listing, and destruction.
+ * Implement this class for different storage backends (e.g., Redis, SQLite, in-memory).
+ */
+export declare abstract class BaseSessionManager {
+    /**
+     * Create a new session for an agent
+     *
+     * @param sessionId - Optional session ID to use. If not provided, a random UUID will be generated.
+     * @returns Newly created session
+     */
+    abstract create(sessionId?: string): Promise<Session>;
+    /**
+     * Get a session by ID
+     *
+     * @param sessionId - Session identifier
+     * @returns Session or undefined if not found
+     */
+    abstract get(sessionId: string): Promise<Session | undefined>;
+    /**
+     * List all sessions for an agent
+     *
+     * @returns Array of sessions belonging to the agent
+     */
+    abstract list(): Promise<Session[]>;
+    /**
+     * Destroy a session
+     *
+     * @param sessionId - Session identifier to destroy
+     */
+    abstract destroy(sessionId: string): Promise<void>;
+}

package/dist/session/session.d.ts

@@ -0,0 +1,159 @@
+import type { Middleware } from '../agent/middleware';
+import type { AgentLoopState, CreateSessionOptions, SendOptions } from '../agent/types';
+import type { ModelClient } from '../model';
+import type { StateStore } from '../state';
+import type { ToolApprovalResult, ToolRegistry } from '../tool';
+import type { AgentEvent, Message, MessageContent, ModelConfig, SessionConfigOverride, SessionSnapshot, SessionStatus } from '../types';
+import { EventEmitter } from 'node:events';
+interface SessionRuntimeOptions extends CreateSessionOptions {
+    modelClient?: ModelClient;
+    systemPrompt?: string;
+    agentName?: string;
+    tools?: ToolRegistry;
+    middlewares?: Middleware<AgentLoopState>[];
+    onUsage?: (usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    }) => void;
+    hasCheckpoint?: boolean;
+    emitSessionCreatedEvent?: boolean;
+}
+/**
+ * Concrete Session implementation that stores data in StateStore.
+ */
+export declare class Session extends EventEmitter {
+    readonly id: string;
+    readonly createdAt: number;
+    status: SessionStatus;
+    title?: string;
+    updatedAt: number;
+    lastActiveAt: number;
+    errorMessage?: string;
+    configOverride?: SessionConfigOverride;
+    messages: Message[];
+    toolCallCount: number;
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    responseCount: number;
+    avgResponseTime?: number;
+    private readonly _stateStore;
+    private readonly _checkpointManager;
+    private readonly _approvalHandler;
+    private readonly _parallelTaskExecutor;
+    private readonly _toolExecutor;
+    private _autoSave;
+    private readonly _autoSaveManager;
+    private readonly _modelClient?;
+    private readonly _tools?;
+    private _middlewares;
+    private readonly _systemPrompt?;
+    private readonly _agentName?;
+    private readonly _onUsage?;
+    private _hasCheckpoint;
+    private _checkpointRestored;
+    private _pendingInput;
+    private _isReceiving;
+    private readonly _hooks?;
+    private _modelOverride?;
+    private readonly _maxIterations?;
+    private readonly _requestParams?;
+    private readonly _emitSessionCreatedEvent;
+    private _sessionCreatedEventEmitted;
+    private getDisabledToolNames;
+    private isToolDisabled;
+    private collectBlockedTools;
+    private isToolBlocked;
+    private getToolsForModel;
+    private getEffectiveSystemPrompt;
+    /**
+     * Create a new Session or load from StateStore.
+     *
+     * @param stateStore - StateStore instance for persistence
+     * @param sessionId - Session identifier
+     * @param snapshot - Optional snapshot to restore from (if not provided, will create new session)
+     */
+    constructor(stateStore: StateStore, sessionId: string, snapshot?: SessionSnapshot, options?: SessionRuntimeOptions);
+    get hasCheckpoint(): boolean;
+    send(input: MessageContent, options?: SendOptions): void;
+    receive(options?: SendOptions): AsyncIterable<AgentEvent>;
+    /**
+     * Convenience helper for "pause → decide → resume" flows.
+     *
+     * This merges `decisions` into `toolContext.approval.decisions` and resumes streaming.
+     */
+    receiveWithApprovals(decisions: Record<string, ToolApprovalResult>, options?: SendOptions): AsyncIterable<AgentEvent>;
+    private _stream;
+    private resolveModelRef;
+    private getRuntimeModelOverride;
+    private _ensureRuntimeConfigured;
+    private extractTextFromContent;
+    private createTitle;
+    private _recordUsage;
+    private executeModelStream;
+    private mergeStateResults;
+    private addToolResultToHistory;
+    private addAssistantMessageWithToolCalls;
+    private addFinalAssistantMessage;
+    private persistSessionState;
+    private _streamWithState;
+    /**
+     * Check if there's an assistant message containing the tool call
+     */
+    private hasAssistantToolCallMessage;
+    private handleFinalResponse;
+    private _finalizeRun;
+    /**
+     * Get preview of the last message (truncated for display)
+     *
+     * @param maxLength - Maximum length of preview
+     * @returns Preview string or undefined if no messages
+     */
+    getLastMessagePreview(maxLength?: number): string | undefined;
+    /**
+     * Create a snapshot of the session for persistence
+     *
+     * @returns Session snapshot
+     */
+    toSnapshot(): SessionSnapshot;
+    /**
+     * Restore session state from a snapshot
+     *
+     * @param snapshot - Session snapshot to restore from
+     */
+    restoreFromSnapshot(snapshot: SessionSnapshot): void;
+    /**
+     * Save session to StateStore.
+     */
+    save(): Promise<void>;
+    /**
+     * Load session from StateStore.
+     */
+    load(): Promise<boolean>;
+    private triggerAutoSave;
+    setStatus(status: SessionStatus, errorMessage?: string): void;
+    markActive(): void;
+    addMessage(message: Message): void;
+    addUsage(usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    }): void;
+    recordResponse(durationMs: number): void;
+    incrementToolCallCount(): void;
+    setModelOverride(model: ModelConfig): void;
+    clearModelOverride(): void;
+    setSystemPromptOverride(systemPrompt: string): void;
+    clearSystemPromptOverride(): void;
+    disableTools(toolNames: string[]): void;
+    enableAllTools(): void;
+    setMiddlewares(middlewares: Middleware<AgentLoopState>[]): void;
+    /**
+     * Enable or disable auto-save.
+     */
+    setAutoSave(enabled: boolean): void;
+}
+export {};

package/dist/session/stateStoreSessionManager.d.ts

@@ -0,0 +1,36 @@
+import type { StateStore } from '../state';
+import { BaseSessionManager } from './manager';
+import { Session } from './session';
+/**
+ * SessionManager implementation using StateStore for persistence.
+ */
+export declare class StateStoreSessionManager extends BaseSessionManager {
+    private readonly _stateStore;
+    constructor(stateStore: StateStore);
+    /**
+     * Create a new session for an agent.
+     *
+     * @param sessionId - Optional session ID to use. If not provided, a random UUID will be generated.
+     * @returns Newly created session
+     */
+    create(sessionId?: string): Promise<Session>;
+    /**
+     * Get a session by ID.
+     *
+     * @param sessionId - Session identifier
+     * @returns Session or undefined if not found
+     */
+    get(sessionId: string): Promise<Session | undefined>;
+    /**
+     * List all sessions for an agent.
+     *
+     * @returns Array of sessions belonging to the agent
+     */
+    list(): Promise<Session[]>;
+    /**
+     * Destroy a session.
+     *
+     * @param sessionId - Session identifier to destroy
+     */
+    destroy(sessionId: string): Promise<void>;
+}

package/dist/session/utils/AsyncQueue.d.ts

@@ -0,0 +1,7 @@
+export declare class AsyncQueue<T> {
+    private readonly queue;
+    private readonly waiters;
+    enqueue(item: T): void;
+    isEmpty(): boolean;
+    dequeueOrWait(timeoutMs: number): Promise<T | undefined>;
+}

package/dist/session/utils/AutoSaveManager.d.ts

@@ -0,0 +1,6 @@
+export declare class AutoSaveManager {
+    private readonly saveHandler;
+    private readonly onError?;
+    constructor(saveHandler: () => Promise<void>, onError?: ((error: Error) => void) | undefined);
+    trigger(): Promise<void>;
+}

package/dist/state/FileStateStore.d.ts

@@ -0,0 +1,72 @@
+import type { StateStoreOptions } from './types';
+import { StateStore } from './stateStore';
+/**
+ * Options for creating a FileStateStore.
+ */
+export interface FileStateStoreOptions extends StateStoreOptions {
+    /**
+     * Directory path for storing state files.
+     */
+    dir: string;
+}
+/**
+ * File-based implementation of StateStore.
+ *
+ * Stores state data as JSON files in a directory structure organized by session:
+ *
+ * ```
+ * <baseDir>/
+ *   <sessionId>/
+ *     checkpoint.json
+ *     compression.json
+ *     session.json
+ *     custom-key.json
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const store = new FileStateStore({
+ *   dir: './state',
+ *   savePoint: 'before',
+ *   deleteOnComplete: true,
+ * })
+ *
+ * const agent = new Agent({
+ *   name: 'MyAgent',
+ *   stateStore: store,
+ *   // ...
+ * })
+ * ```
+ */
+export declare class FileStateStore extends StateStore {
+    private baseDir;
+    constructor(options: FileStateStoreOptions);
+    protected _write(storagePath: string, data: string): Promise<void>;
+    protected _read(storagePath: string): Promise<string | undefined>;
+    protected _delete(storagePath: string): Promise<void>;
+    protected _exists(storagePath: string): Promise<boolean>;
+    protected _list(prefix: string): Promise<string[]>;
+    /**
+     * Convert storage path to file system path.
+     * Storage path: `{sessionId}/{key}`
+     * File path: `{baseDir}/{sessionId}/{key}.json`
+     */
+    private toFilePath;
+    /**
+     * Ensure a directory exists.
+     */
+    private ensureDir;
+    /**
+     * List all JSON files in a directory.
+     */
+    private listJsonFiles;
+    /**
+     * Get the base directory path.
+     */
+    getBaseDir(): string;
+    /**
+     * Clear all state data from the store.
+     * WARNING: This will delete all files in the base directory.
+     */
+    clear(): void;
+}

package/dist/state/InMemoryStateStore.d.ts

@@ -0,0 +1,46 @@
+import type { StateStoreOptions } from './types';
+import { StateStore } from './stateStore';
+/**
+ * In-memory implementation of StateStore.
+ *
+ * Useful for development, testing, and short-lived applications.
+ * Data is lost when the process exits.
+ *
+ * @example
+ * ```typescript
+ * const store = new InMemoryStateStore({
+ *   savePoint: 'before',
+ *   deleteOnComplete: true,
+ * })
+ *
+ * const agent = new Agent({
+ *   name: 'MyAgent',
+ *   stateStore: store,
+ *   // ...
+ * })
+ * ```
+ */
+export declare class InMemoryStateStore extends StateStore {
+    /**
+     * Internal storage: path -> data
+     */
+    private store;
+    constructor(options?: StateStoreOptions);
+    protected _write(path: string, data: string): Promise<void>;
+    protected _read(path: string): Promise<string | undefined>;
+    protected _delete(path: string): Promise<void>;
+    protected _exists(path: string): Promise<boolean>;
+    protected _list(prefix: string): Promise<string[]>;
+    /**
+     * Clear all data from the store.
+     * Useful for testing.
+     */
+    clear(): void;
+    /**
+     * Get statistics about the store.
+     */
+    stats(): {
+        entryCount: number;
+        sessionCount: number;
+    };
+}

package/dist/state/index.d.ts

@@ -0,0 +1,6 @@
+export { FileStateStore } from './FileStateStore';
+export type { FileStateStoreOptions } from './FileStateStore';
+export { InMemoryStateStore } from './InMemoryStateStore';
+export { StateStore } from './stateStore';
+export type { CompressedMessagesSnapshot, CompressionState, StateKey, StateStoreOptions } from './types';
+export { StateKeys } from './types';

package/dist/state/stateStore.d.ts

@@ -0,0 +1,181 @@
+import type { AgentLoopCheckpoint } from '../types';
+import type { StateStoreOptions } from './types';
+/**
+ * Abstract base class for state storage.
+ *
+ * StateStore provides a session-centric storage abstraction where all data
+ * is organized by sessionId. Each session can have multiple keys storing
+ * different types of data (checkpoint, compression state, session info, etc.).
+ *
+ * Subclasses only need to implement the low-level storage primitives:
+ * - _write: Write data to a path
+ * - _read: Read data from a path
+ * - _delete: Delete data at a path
+ * - _exists: Check if data exists at a path
+ * - _list: List all paths with a given prefix
+ *
+ * The base class provides:
+ * - High-level API for session-based storage (save, load, delete, etc.)
+ * - Convenience methods for checkpoint operations
+ * - JSON serialization/deserialization
+ *
+ * @example
+ * ```typescript
+ * // Using with an agent
+ * const store = new FileStateStore({ dir: './state' })
+ *
+ * const agent = new Agent({
+ *   name: 'MyAgent',
+ *   stateStore: store,
+ *   // ...
+ * })
+ *
+ * // Manual state operations
+ * await store.save(sessionId, 'custom-key', { myData: 123 })
+ * const data = await store.load(sessionId, 'custom-key')
+ * ```
+ */
+export declare abstract class StateStore {
+    /**
+     * When to save checkpoints during agent execution.
+     */
+    readonly savePoint: 'before' | 'after' | 'both';
+    /**
+     * Whether to delete checkpoint after successful completion.
+     */
+    readonly deleteOnComplete: boolean;
+    constructor(options?: StateStoreOptions);
+    protected assertValidStorageSegment(label: string, value: string): void;
+    /**
+     * Save data for a session under a specific key.
+     *
+     * @param sessionId - Session identifier
+     * @param key - Data key (e.g., 'checkpoint', 'compression', or custom keys)
+     * @param data - Data to save (will be JSON serialized)
+     */
+    save<T>(sessionId: string, key: string, data: T): Promise<void>;
+    /**
+     * Load data for a session by key.
+     *
+     * @param sessionId - Session identifier
+     * @param key - Data key
+     * @returns The data or undefined if not found
+     */
+    load<T>(sessionId: string, key: string): Promise<T | undefined>;
+    /**
+     * Delete data for a session by key.
+     *
+     * @param sessionId - Session identifier
+     * @param key - Data key
+     */
+    delete(sessionId: string, key: string): Promise<void>;
+    /**
+     * Delete all data for a session.
+     *
+     * @param sessionId - Session identifier
+     */
+    deleteSession(sessionId: string): Promise<void>;
+    /**
+     * List all keys for a session.
+     *
+     * @param sessionId - Session identifier
+     * @returns Array of keys
+     */
+    listKeys(sessionId: string): Promise<string[]>;
+    /**
+     * Check if data exists for a session key.
+     *
+     * @param sessionId - Session identifier
+     * @param key - Data key
+     * @returns True if data exists
+     */
+    exists(sessionId: string, key: string): Promise<boolean>;
+    /**
+     * Save an agent loop checkpoint.
+     *
+     * This is a convenience method that saves the checkpoint under the
+     * predefined CHECKPOINT key with additional metadata.
+     *
+     * @param checkpoint - Checkpoint to save
+     */
+    saveCheckpoint(checkpoint: AgentLoopCheckpoint): Promise<void>;
+    /**
+     * Load an agent loop checkpoint by session ID.
+     *
+     * @param sessionId - Session identifier
+     * @returns Checkpoint or undefined if not found
+     */
+    loadCheckpoint(sessionId: string): Promise<AgentLoopCheckpoint | undefined>;
+    /**
+     * Delete an agent loop checkpoint.
+     *
+     * @param sessionId - Session identifier
+     */
+    deleteCheckpoint(sessionId: string): Promise<void>;
+    /**
+     * List all checkpoints across all sessions.
+     *
+     * @returns Array of checkpoints
+     */
+    listCheckpoints(): Promise<AgentLoopCheckpoint[]>;
+    /**
+     * List all session IDs that have stored data.
+     *
+     * @returns Array of session IDs
+     */
+    listSessions(): Promise<string[]>;
+    /**
+     * Build a storage path from sessionId and key.
+     * Default format: `{sessionId}/{key}`
+     *
+     * Subclasses can override this for different path formats.
+     */
+    protected buildPath(sessionId: string, key: string): string;
+    /**
+     * Build a prefix for listing all data under a session.
+     * Default format: `{sessionId}/`
+     */
+    protected buildPrefix(sessionId: string): string;
+    /**
+     * Extract the key from a full path.
+     */
+    protected extractKey(sessionId: string, path: string): string;
+    /**
+     * Extract the sessionId from a full path.
+     */
+    protected extractSessionId(path: string): string | undefined;
+    /**
+     * Write data to a storage path.
+     *
+     * @param path - Storage path
+     * @param data - Serialized data string
+     */
+    protected abstract _write(path: string, data: string): Promise<void>;
+    /**
+     * Read data from a storage path.
+     *
+     * @param path - Storage path
+     * @returns Data string or undefined if not found
+     */
+    protected abstract _read(path: string): Promise<string | undefined>;
+    /**
+     * Delete data at a storage path.
+     *
+     * @param path - Storage path
+     */
+    protected abstract _delete(path: string): Promise<void>;
+    /**
+     * Check if data exists at a storage path.
+     *
+     * @param path - Storage path
+     * @returns True if data exists
+     */
+    protected abstract _exists(path: string): Promise<boolean>;
+    /**
+     * List all paths with a given prefix.
+     *
+     * @param prefix - Path prefix (empty string for all paths)
+     * @returns Array of full paths
+     */
+    protected abstract _list(prefix: string): Promise<string[]>;
+}

package/dist/state/types.d.ts

@@ -0,0 +1,85 @@
+import type { CompressionStats } from '../middleware/contextCompressionMiddleware';
+import type { MessageContent } from '../types';
+/**
+ * State store configuration options.
+ */
+export interface StateStoreOptions {
+    /**
+     * When to save checkpoints:
+     * - 'before': Save before each iteration (default)
+     * - 'after': Save after each iteration
+     * - 'both': Save before and after
+     */
+    savePoint?: 'before' | 'after' | 'both';
+    /**
+     * Whether to delete the checkpoint after successful completion.
+     * Default: true
+     */
+    deleteOnComplete?: boolean;
+}
+/**
+ * Predefined state keys for common data types.
+ */
+export declare const StateKeys: {
+    /** AgentLoopCheckpoint data */
+    readonly CHECKPOINT: "checkpoint";
+    /** CompressionState data */
+    readonly COMPRESSION: "compression";
+    /** SessionSnapshot data */
+    readonly SESSION: "session";
+    /**
+     * Compressed messages snapshot key pattern.
+     * Use with timestamp: `compression-snapshot-${timestamp}`
+     */
+    readonly COMPRESSION_SNAPSHOT: "compression-snapshot";
+};
+export type StateKey = (typeof StateKeys)[keyof typeof StateKeys];
+/**
+ * Compressed messages snapshot.
+ * Stores the compressed messages after a compression operation.
+ */
+export interface CompressedMessagesSnapshot {
+    /**
+     * Compressed messages after compression.
+     */
+    messages: Array<{
+        role: string;
+        content: MessageContent;
+        tool_call_id?: string;
+        name?: string;
+        tool_calls?: unknown[];
+    }>;
+    /**
+     * Compression statistics.
+     */
+    stats: CompressionStats;
+    /**
+     * Timestamp when this compression occurred (ms).
+     */
+    timestamp: number;
+}
+/**
+ * Compression state for context compression middleware.
+ *
+ * This stores all compression-related data for a session,
+ * allowing the middleware to restore its state after a restart.
+ */
+export interface CompressionState {
+    /**
+     * Statistics from the last compression operation.
+     */
+    lastStats?: CompressionStats;
+    /**
+     * History of all compression operations.
+     */
+    history: CompressionStats[];
+    /**
+     * Rolling summary content from summarized messages.
+     * This can be used when resuming from a checkpoint to provide context.
+     */
+    summary?: string;
+    /**
+     * Last update timestamp (ms).
+     */
+    updatedAt: number;
+}

package/dist/subagent/file-search-specialist.d.ts

@@ -0,0 +1,16 @@
+import type { SubagentDefinition } from '../tool/builtin/task';
+/**
+ * System prompt for File Search Specialist
+ *
+ * Based on the configuration from subagent_file.json, this prompt
+ * defines the specialist's role, capabilities, and guidelines.
+ */
+export declare function buildFileSearchSpecialistPrompt(cwd: string, now?: Date): string;
+export declare const fileSearchSpecialistPrompt: string;
+/**
+ * File Search Specialist Subagent Definition
+ *
+ * This subagent specializes in navigating and exploring codebases,
+ * finding files, searching content, and analyzing file structures.
+ */
+export declare const fileSearchSpecialist: SubagentDefinition;

package/dist/subagent/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Subagent Definitions
+ *
+ * This module exports predefined subagent configurations
+ * that can be used with the parallel subagent middleware.
+ */
+export * from './file-search-specialist';