@compilr-dev/agents 0.0.1

package/dist/state/serializer.js

@@ -0,0 +1,172 @@
+/**
+ * State Serializers
+ *
+ * Implementations for serializing/deserializing AgentState.
+ */
+import { CURRENT_STATE_VERSION } from './types.js';
+import { StateError } from './errors.js';
+/**
+ * JSON-based state serializer.
+ * Handles standard JSON serialization with validation.
+ */
+export class JsonSerializer {
+    version = '1.0';
+    /**
+     * Serialize agent state to JSON string
+     */
+    serialize(state) {
+        try {
+            return JSON.stringify(state, null, 2);
+        }
+        catch (error) {
+            throw StateError.serialization('Failed to serialize state to JSON', error instanceof Error ? error : undefined);
+        }
+    }
+    /**
+     * Deserialize JSON string to agent state
+     */
+    deserialize(data) {
+        let parsed;
+        try {
+            parsed = JSON.parse(data);
+        }
+        catch (error) {
+            throw StateError.deserialization('Invalid JSON format', error instanceof Error ? error : undefined);
+        }
+        this.validateParsed(parsed);
+        return parsed;
+    }
+    /**
+     * Validate state before serialization (public interface method).
+     * This is called by checkpointers before saving to prevent corrupted checkpoints.
+     * @throws StateError if state is invalid
+     */
+    validate(state) {
+        this.validateParsed(state);
+    }
+    /**
+     * Validate that parsed data is a valid AgentState
+     */
+    validateParsed(data) {
+        if (!data || typeof data !== 'object') {
+            throw StateError.invalidState('State must be an object');
+        }
+        const state = data;
+        // Required string fields
+        const requiredStrings = ['sessionId', 'systemPrompt', 'createdAt', 'updatedAt'];
+        for (const field of requiredStrings) {
+            if (typeof state[field] !== 'string') {
+                throw StateError.invalidState(`Missing or invalid field: ${field}`);
+            }
+        }
+        // Messages array
+        if (!Array.isArray(state.messages)) {
+            throw StateError.invalidState('messages must be an array');
+        }
+        // Todos array
+        if (!Array.isArray(state.todos)) {
+            throw StateError.invalidState('todos must be an array');
+        }
+        // Numeric fields
+        if (typeof state.currentIteration !== 'number') {
+            throw StateError.invalidState('currentIteration must be a number');
+        }
+        if (typeof state.totalTokensUsed !== 'number') {
+            throw StateError.invalidState('totalTokensUsed must be a number');
+        }
+        if (typeof state.version !== 'number') {
+            throw StateError.invalidState('version must be a number');
+        }
+        // Version check - safe to cast since we validated it's a number
+        const version = state.version;
+        if (version > CURRENT_STATE_VERSION) {
+            throw StateError.versionMismatch(CURRENT_STATE_VERSION, version);
+        }
+    }
+    /**
+     * Migrate from older versions (currently no-op for v1)
+     */
+    migrate(data, fromVersion) {
+        // Parse to validate JSON format
+        JSON.parse(data);
+        // Currently only version 1, no migration needed
+        if (fromVersion === '1.0') {
+            return data;
+        }
+        throw StateError.versionMismatch(CURRENT_STATE_VERSION, parseFloat(fromVersion) || 0);
+    }
+}
+/**
+ * Compact JSON serializer (no pretty printing).
+ * Useful for storage-constrained environments.
+ */
+export class CompactJsonSerializer {
+    version = '1.0';
+    serialize(state) {
+        try {
+            return JSON.stringify(state);
+        }
+        catch (error) {
+            throw StateError.serialization('Failed to serialize state to compact JSON', error instanceof Error ? error : undefined);
+        }
+    }
+    deserialize(data) {
+        let parsed;
+        try {
+            parsed = JSON.parse(data);
+        }
+        catch (error) {
+            throw StateError.deserialization('Invalid JSON format', error instanceof Error ? error : undefined);
+        }
+        this.validateParsed(parsed);
+        return parsed;
+    }
+    /**
+     * Validate state before serialization (public interface method).
+     * This is called by checkpointers before saving to prevent corrupted checkpoints.
+     * @throws StateError if state is invalid
+     */
+    validate(state) {
+        this.validateParsed(state);
+    }
+    validateParsed(data) {
+        if (!data || typeof data !== 'object') {
+            throw StateError.invalidState('State must be an object');
+        }
+        const state = data;
+        // Required string fields
+        const requiredStrings = ['sessionId', 'systemPrompt', 'createdAt', 'updatedAt'];
+        for (const field of requiredStrings) {
+            if (typeof state[field] !== 'string') {
+                throw StateError.invalidState(`Missing or invalid field: ${field}`);
+            }
+        }
+        // Messages array
+        if (!Array.isArray(state.messages)) {
+            throw StateError.invalidState('messages must be an array');
+        }
+        // Todos array
+        if (!Array.isArray(state.todos)) {
+            throw StateError.invalidState('todos must be an array');
+        }
+        // Numeric fields
+        if (typeof state.currentIteration !== 'number') {
+            throw StateError.invalidState('currentIteration must be a number');
+        }
+        if (typeof state.totalTokensUsed !== 'number') {
+            throw StateError.invalidState('totalTokensUsed must be a number');
+        }
+        if (typeof state.version !== 'number') {
+            throw StateError.invalidState('version must be a number');
+        }
+        // Version check - safe to cast since we validated it's a number
+        const version = state.version;
+        if (version > CURRENT_STATE_VERSION) {
+            throw StateError.versionMismatch(CURRENT_STATE_VERSION, version);
+        }
+    }
+}
+/**
+ * Default serializer instance
+ */
+export const defaultSerializer = new JsonSerializer();

package/dist/state/types.d.ts

@@ -0,0 +1,312 @@
+/**
+ * State Management Types
+ *
+ * Core types and interfaces for conversation persistence.
+ * Inspired by LangGraph's checkpointer pattern.
+ */
+import type { Message } from '../providers/types.js';
+import type { TodoItem } from '../tools/builtin/todo.js';
+/**
+ * Serializable snapshot of an agent's current state.
+ * Contains everything needed to resume a conversation.
+ */
+export interface AgentState {
+    /**
+     * Unique session identifier
+     */
+    sessionId: string;
+    /**
+     * Conversation messages
+     */
+    messages: Message[];
+    /**
+     * System prompt (needed for resume)
+     */
+    systemPrompt: string;
+    /**
+     * Model identifier (optional, for resume)
+     */
+    model?: string;
+    /**
+     * Todo items state
+     */
+    todos: TodoItem[];
+    /**
+     * Current iteration count
+     */
+    currentIteration: number;
+    /**
+     * Total tokens used in the session
+     */
+    totalTokensUsed: number;
+    /**
+     * When the session was created (ISO 8601)
+     */
+    createdAt: string;
+    /**
+     * When the session was last updated (ISO 8601)
+     */
+    updatedAt: string;
+    /**
+     * Schema version for migration support
+     */
+    version: number;
+}
+/**
+ * Metadata stored alongside state for listing/filtering.
+ */
+export interface SessionMetadata {
+    /**
+     * Session identifier
+     */
+    sessionId: string;
+    /**
+     * User-friendly session name
+     */
+    name?: string;
+    /**
+     * Creation timestamp (ISO 8601)
+     */
+    createdAt: string;
+    /**
+     * Last update timestamp (ISO 8601)
+     */
+    updatedAt: string;
+    /**
+     * Number of messages in the conversation
+     */
+    messageCount: number;
+    /**
+     * Truncated preview of last user message
+     */
+    lastUserMessage?: string;
+    /**
+     * Truncated preview of last assistant message
+     */
+    lastAssistantMessage?: string;
+    /**
+     * Tags for organization
+     */
+    tags?: string[];
+}
+/**
+ * Lightweight session info for listing (without full state).
+ */
+export interface SessionInfo {
+    /**
+     * Session identifier
+     */
+    sessionId: string;
+    /**
+     * User-friendly session name
+     */
+    name?: string;
+    /**
+     * Creation timestamp (ISO 8601)
+     */
+    createdAt: string;
+    /**
+     * Last update timestamp (ISO 8601)
+     */
+    updatedAt: string;
+    /**
+     * Number of messages
+     */
+    messageCount: number;
+    /**
+     * Preview text (last message truncated)
+     */
+    preview?: string;
+    /**
+     * Tags for organization
+     */
+    tags?: string[];
+}
+/**
+ * Handles conversion between AgentState and string representation.
+ */
+export interface StateSerializer {
+    /**
+     * Serialize agent state to string
+     */
+    serialize(state: AgentState): string;
+    /**
+     * Deserialize string back to agent state
+     * @throws StateError if data is invalid
+     */
+    deserialize(data: string): AgentState;
+    /**
+     * Validate state before serialization.
+     * Called by checkpointers before saving to prevent corrupted checkpoints.
+     * @throws StateError if state is invalid
+     */
+    validate(state: AgentState): void;
+    /**
+     * Version identifier for migration support
+     */
+    readonly version: string;
+    /**
+     * Optional migration from older versions
+     */
+    migrate?(data: string, fromVersion: string): string;
+}
+/**
+ * Options for listing sessions.
+ */
+export interface ListSessionsOptions {
+    /**
+     * Maximum number of sessions to return
+     */
+    limit?: number;
+    /**
+     * Number of sessions to skip (for pagination)
+     */
+    offset?: number;
+    /**
+     * Field to sort by
+     */
+    orderBy?: 'createdAt' | 'updatedAt';
+    /**
+     * Sort direction
+     */
+    order?: 'asc' | 'desc';
+    /**
+     * Filter by tags (sessions must have all specified tags)
+     */
+    tags?: string[];
+}
+/**
+ * Core persistence interface. Implementations handle actual storage.
+ */
+export interface Checkpointer {
+    /**
+     * Save agent state to storage
+     * @param sessionId - Unique session identifier
+     * @param state - Complete agent state to save
+     * @param metadata - Optional metadata overrides
+     */
+    save(sessionId: string, state: AgentState, metadata?: Partial<SessionMetadata>): Promise<void>;
+    /**
+     * Load agent state from storage
+     * @param sessionId - Session to load
+     * @returns AgentState if found, null if not exists
+     */
+    load(sessionId: string): Promise<AgentState | null>;
+    /**
+     * List all saved sessions
+     * @param options - Optional filtering/sorting options
+     * @returns Array of session info (without full state)
+     */
+    list(options?: ListSessionsOptions): Promise<SessionInfo[]>;
+    /**
+     * Delete a saved session
+     * @param sessionId - Session to delete
+     * @returns true if deleted, false if not found
+     */
+    delete(sessionId: string): Promise<boolean>;
+    /**
+     * Check if a session exists
+     * @param sessionId - Session to check
+     */
+    exists(sessionId: string): Promise<boolean>;
+    /**
+     * Get session metadata without loading full state
+     * @param sessionId - Session to query
+     */
+    getMetadata(sessionId: string): Promise<SessionMetadata | null>;
+}
+/**
+ * Pending write from incomplete tool execution.
+ * Used for fault-tolerant checkpointing.
+ */
+export interface PendingWrite {
+    /**
+     * Tool call ID
+     */
+    toolCallId: string;
+    /**
+     * Tool name
+     */
+    toolName: string;
+    /**
+     * Tool execution result
+     */
+    result: {
+        success: boolean;
+        result?: unknown;
+        error?: string;
+    };
+    /**
+     * When the write was completed (ISO 8601)
+     */
+    completedAt: string;
+}
+/**
+ * Extended checkpointer with fault tolerance support.
+ * Tracks pending writes for recovery from mid-step failures.
+ */
+export interface CheckpointerWithPending extends Checkpointer {
+    /**
+     * Save pending writes (incomplete tool executions)
+     */
+    savePending(sessionId: string, writes: PendingWrite[]): Promise<void>;
+    /**
+     * Load pending writes for a session
+     */
+    loadPending(sessionId: string): Promise<PendingWrite[]>;
+    /**
+     * Clear pending writes (called after step completion)
+     */
+    clearPending(sessionId: string): Promise<void>;
+}
+/**
+ * Options for resuming an agent from a checkpoint.
+ */
+export interface ResumeOptions {
+    /**
+     * LLM provider to use
+     */
+    provider: unknown;
+    /**
+     * Checkpointer to load from
+     */
+    checkpointer: Checkpointer;
+    /**
+     * Override saved system prompt
+     */
+    systemPrompt?: string;
+    /**
+     * Override saved tools
+     */
+    tools?: unknown[];
+    /**
+     * Event handler
+     */
+    onEvent?: (event: unknown) => void;
+}
+/**
+ * Options for creating agent from exported state.
+ */
+export interface FromStateOptions {
+    /**
+     * LLM provider to use
+     */
+    provider: unknown;
+    /**
+     * Optional checkpointer for subsequent saves
+     */
+    checkpointer?: Checkpointer;
+    /**
+     * Override saved tools
+     */
+    tools?: unknown[];
+    /**
+     * Event handler
+     */
+    onEvent?: (event: unknown) => void;
+}
+/**
+ * Current schema version for AgentState.
+ * Increment when making breaking changes to the schema.
+ */
+export declare const CURRENT_STATE_VERSION = 1;

package/dist/state/types.js

@@ -0,0 +1,14 @@
+/**
+ * State Management Types
+ *
+ * Core types and interfaces for conversation persistence.
+ * Inspired by LangGraph's checkpointer pattern.
+ */
+// ============================================================
+// Current State Version
+// ============================================================
+/**
+ * Current schema version for AgentState.
+ * Increment when making breaking changes to the schema.
+ */
+export const CURRENT_STATE_VERSION = 1;

package/dist/tools/builtin/bash-output.d.ts

@@ -0,0 +1,61 @@
+/**
+ * BashOutput Tool - Retrieve output from background shells
+ */
+import type { Tool } from '../types.js';
+import { type ShellManager } from './shell-manager.js';
+/**
+ * Input parameters for bashOutput tool
+ */
+export interface BashOutputInput {
+    /**
+     * The ID of the background shell to retrieve output from
+     */
+    bash_id: string;
+    /**
+     * Optional regular expression to filter output lines
+     * Only lines matching this regex will be included
+     */
+    filter?: string;
+}
+/**
+ * Result of bashOutput tool
+ */
+export interface BashOutputResult {
+    /**
+     * Shell ID
+     */
+    id: string;
+    /**
+     * Current status of the shell
+     */
+    status: 'running' | 'completed' | 'failed' | 'killed';
+    /**
+     * Standard output (new since last read)
+     */
+    stdout: string;
+    /**
+     * Standard error (new since last read)
+     */
+    stderr: string;
+    /**
+     * Whether the shell is still running and may produce more output
+     */
+    hasMore: boolean;
+    /**
+     * Exit code (if completed)
+     */
+    exitCode?: number;
+}
+/**
+ * BashOutput tool definition
+ */
+export declare const bashOutputTool: Tool<BashOutputInput>;
+/**
+ * Factory function to create a bashOutput tool with custom shell manager
+ */
+export declare function createBashOutputTool(options?: {
+    /**
+     * Custom shell manager to use
+     */
+    shellManager?: ShellManager;
+}): Tool<BashOutputInput>;

package/dist/tools/builtin/bash-output.js

@@ -0,0 +1,90 @@
+/**
+ * BashOutput Tool - Retrieve output from background shells
+ */
+import { defineTool, createSuccessResult, createErrorResult } from '../define.js';
+import { getDefaultShellManager } from './shell-manager.js';
+/**
+ * BashOutput tool definition
+ */
+export const bashOutputTool = defineTool({
+    name: 'bash_output',
+    description: 'Retrieve output from a running or completed background bash shell. ' +
+        'Returns only new output since the last check. ' +
+        'Use this to monitor long-running commands started with run_in_background.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            bash_id: {
+                type: 'string',
+                description: 'The ID of the background shell to retrieve output from',
+            },
+            filter: {
+                type: 'string',
+                description: 'Optional regular expression to filter output lines. ' +
+                    'Only lines matching this regex will be included.',
+            },
+        },
+        required: ['bash_id'],
+    },
+    execute: (input) => {
+        const manager = getDefaultShellManager();
+        return Promise.resolve(executeBashOutput(input, manager));
+    },
+});
+/**
+ * Execute the bashOutput tool
+ */
+function executeBashOutput(input, manager) {
+    const { bash_id, filter } = input;
+    // Parse filter regex if provided
+    let filterRegex;
+    if (filter) {
+        try {
+            filterRegex = new RegExp(filter);
+        }
+        catch {
+            return createErrorResult(`Invalid filter regex: ${filter}`);
+        }
+    }
+    // Get output from shell
+    const output = manager.getOutput(bash_id, filterRegex);
+    if (!output) {
+        return createErrorResult(`Shell '${bash_id}' not found. It may have been cleaned up or never existed.`);
+    }
+    return createSuccessResult({
+        id: output.id,
+        status: output.status,
+        stdout: output.stdout,
+        stderr: output.stderr,
+        hasMore: output.hasMore,
+        ...(output.exitCode !== undefined && { exitCode: output.exitCode }),
+    });
+}
+/**
+ * Factory function to create a bashOutput tool with custom shell manager
+ */
+export function createBashOutputTool(options) {
+    const manager = options?.shellManager ?? getDefaultShellManager();
+    return defineTool({
+        name: 'bash_output',
+        description: 'Retrieve output from a running or completed background bash shell. ' +
+            'Returns only new output since the last check. ' +
+            'Use this to monitor long-running commands started with run_in_background.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                bash_id: {
+                    type: 'string',
+                    description: 'The ID of the background shell to retrieve output from',
+                },
+                filter: {
+                    type: 'string',
+                    description: 'Optional regular expression to filter output lines. ' +
+                        'Only lines matching this regex will be included.',
+                },
+            },
+            required: ['bash_id'],
+        },
+        execute: (input) => Promise.resolve(executeBashOutput(input, manager)),
+    });
+}