@cuylabs/agent-core 0.1.0

package/dist/index-eud06GDQ.d.ts

@@ -0,0 +1,446 @@
+import { z } from 'zod';
+
+/**
+ * ToolHost — execution environment abstraction for agent tools.
+ *
+ * A ToolHost defines *where* tools execute: local machine, Docker container,
+ * SSH remote, etc. Every host provides two surfaces:
+ *
+ * 1. **File system** — read, write, stat, list, check existence
+ * 2. **Process execution** — spawn commands, kill processes
+ *
+ * Tools call `ctx.host.readFile()` / `ctx.host.exec()` instead of importing
+ * `fs` and `child_process` directly. The host implementation handles the rest.
+ *
+ * @example
+ * ```typescript
+ * // Default: runs everything locally
+ * const agent = createAgent({ host: localHost() });
+ *
+ * // Future: run tools inside a Docker container
+ * const agent = createAgent({ host: dockerHost("my-container") });
+ * ```
+ */
+/** Options for spawning a process. */
+interface ExecOptions {
+    /** Working directory for the command. */
+    cwd?: string;
+    /** Environment variables (merged with host defaults). */
+    env?: Record<string, string | undefined>;
+    /** Abort signal for cancellation. */
+    signal?: AbortSignal;
+    /** Timeout in milliseconds. 0 = no timeout. */
+    timeout?: number;
+    /** Callback for stdout data as it arrives. */
+    onStdout?: (data: Buffer) => void;
+    /** Callback for stderr data as it arrives. */
+    onStderr?: (data: Buffer) => void;
+}
+/** Result of a process execution. */
+interface ExecResult {
+    /** Combined stdout output. */
+    stdout: string;
+    /** Combined stderr output. */
+    stderr: string;
+    /** Exit code (null if killed by signal). */
+    exitCode: number | null;
+    /** Whether the process was killed due to timeout. */
+    timedOut: boolean;
+}
+/** Minimal stat result — only the fields tools actually need. */
+interface FileStat {
+    /** File size in bytes. */
+    size: number;
+    /** Last modification time. */
+    mtime: Date;
+    /** Whether this entry is a directory. */
+    isDirectory: boolean;
+    /** Whether this entry is a regular file. */
+    isFile: boolean;
+}
+/** A directory entry returned by `readdir`. */
+interface DirEntry {
+    /** Entry name (not full path). */
+    name: string;
+    /** Whether this entry is a directory. */
+    isDirectory: boolean;
+    /** Whether this entry is a regular file. */
+    isFile: boolean;
+}
+/**
+ * The execution environment for agent tools.
+ *
+ * Abstracts filesystem and process operations so tools work identically
+ * whether running locally, in Docker, over SSH, or in any other environment.
+ */
+interface ToolHost {
+    /** Human-readable host identifier (e.g. "local", "docker:my-container"). */
+    readonly name: string;
+    /** Read a file as a UTF-8 string. Throws if the file doesn't exist. */
+    readFile(path: string): Promise<string>;
+    /** Read raw bytes from a file. Throws if the file doesn't exist. */
+    readBytes(path: string, offset: number, length: number): Promise<Buffer>;
+    /** Write a UTF-8 string to a file. Creates parent directories as needed. */
+    writeFile(path: string, content: string): Promise<void>;
+    /** Check if a path exists. Never throws. */
+    exists(path: string): Promise<boolean>;
+    /** Get file metadata. Throws if the path doesn't exist. */
+    stat(path: string): Promise<FileStat>;
+    /** List directory entries. Throws if the path is not a directory. */
+    readdir(path: string): Promise<DirEntry[]>;
+    /** Create directories recursively. No-op if they already exist. */
+    mkdir(path: string): Promise<void>;
+    /**
+     * Execute a shell command.
+     *
+     * The host decides which shell to use (e.g. local host uses the user's
+     * `$SHELL`, Docker host uses `docker exec`, SSH host uses remote shell).
+     */
+    exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+}
+
+/**
+ * Tool-related types for @cuylabs/agent-core
+ *
+ * Defines the interfaces for tool execution context, results,
+ * and metadata used throughout the agent system.
+ */
+
+/**
+ * Turn tracker interface for tool context
+ * Minimal interface to avoid circular dependencies
+ */
+interface TurnTrackerContext {
+    /** Capture baseline before writing to a file */
+    beforeWrite(path: string): Promise<boolean>;
+    /** Check if a file is being tracked */
+    isTracking(path: string): boolean;
+}
+/**
+ * Tool execution context
+ */
+interface ToolContext {
+    /** Working directory for file operations */
+    cwd: string;
+    /** Abort signal for cancellation */
+    abort: AbortSignal;
+    /** Session ID */
+    sessionID: string;
+    /** Message ID */
+    messageID: string;
+    /** Agent name */
+    agent: string;
+    /**
+     * Execution environment for file and process operations.
+     *
+     * Tools should call `ctx.host.readFile()`, `ctx.host.exec()`, etc.
+     * instead of importing `fs` and `child_process` directly. This
+     * allows the same tools to work on local, Docker, SSH, or any
+     * other host without code changes.
+     *
+     * When not provided, tools may fall back to direct Node.js APIs,
+     * but new tools should always prefer `ctx.host`.
+     */
+    host?: ToolHost;
+    /**
+     * Turn change tracker - automatically captures file baselines.
+     * Call `turnTracker.beforeWrite(path)` before modifying files
+     * for undo/diff capabilities.
+     */
+    turnTracker?: TurnTrackerContext;
+    /** Extra context data */
+    extra?: Record<string, unknown>;
+}
+/**
+ * Result returned by a tool
+ */
+interface ToolResult {
+    /** Short title for display */
+    title: string;
+    /** Main output text */
+    output: string;
+    /** Optional metadata */
+    metadata?: ToolMetadata;
+}
+/**
+ * File operation metadata - declare how a tool modifies files
+ * Used by TurnChangeTracker for automatic baseline capture
+ */
+interface FileOperationMeta {
+    /**
+     * Names of parameters that contain file paths to track.
+     * The tracker will capture baselines for these files before the tool runs.
+     * @example ['path'] for write tool, ['filePath'] for edit tool
+     */
+    pathArgs?: string[];
+    /**
+     * Type of file operation - determines if baseline capture is needed.
+     * - 'read': No baseline capture (file not modified)
+     * - 'write': Capture baseline before overwriting
+     * - 'create': Capture baseline (to know file didn't exist)
+     * - 'delete': Capture baseline before deletion
+     */
+    operationType?: "read" | "write" | "delete" | "create";
+}
+/**
+ * Tool metadata
+ */
+interface ToolMetadata {
+    /** Whether output was truncated */
+    truncated?: boolean;
+    /** Path to full output if truncated */
+    outputPath?: string;
+    /**
+     * File operation metadata for automatic turn tracking.
+     * When set, the agent will automatically capture file baselines
+     * before tool execution for undo/diff capabilities.
+     */
+    fileOps?: FileOperationMeta;
+    /** Additional metadata */
+    [key: string]: unknown;
+}
+
+/**
+ * Tool definition namespace for @cuylabs/agent-core
+ *
+ * Following OpenCode's Tool.define pattern for consistent tool creation.
+ */
+
+/**
+ * Tool namespace - OpenCode-style tool definition
+ */
+declare namespace Tool {
+    /**
+     * Tool info interface - the shape of a defined tool
+     */
+    interface Info<TParams extends z.ZodType = z.ZodType, TMeta extends ToolMetadata = ToolMetadata> {
+        /** Unique tool identifier */
+        id: string;
+        /** Initialize the tool (can be async for dynamic descriptions) */
+        init: (ctx?: InitContext) => Promise<InitResult<TParams, TMeta>> | InitResult<TParams, TMeta>;
+    }
+    /**
+     * Any tool info - for use in arrays and collections where generic types vary
+     */
+    type AnyInfo = Info<any, any>;
+    /**
+     * Context passed during tool initialization
+     */
+    interface InitContext {
+        /** Working directory */
+        cwd?: string;
+        /** Agent name (if known) */
+        agent?: string;
+    }
+    /**
+     * Result of tool initialization
+     */
+    interface InitResult<TParams extends z.ZodType = z.ZodType, TMeta extends ToolMetadata = ToolMetadata> {
+        /** Tool description for the LLM */
+        description: string;
+        /** Zod schema for parameters */
+        parameters: TParams;
+        /** Execute the tool */
+        execute: (params: z.infer<TParams>, ctx: ToolContext) => Promise<ExecuteResult<TMeta>>;
+        /** Optional custom validation error formatter */
+        formatValidationError?: (error: z.ZodError) => string;
+        /**
+         * File operation metadata for automatic turn tracking.
+         * When set, the agent will automatically capture file baselines
+         * before tool execution for undo/diff capabilities.
+         *
+         * @example
+         * ```typescript
+         * // For a write tool
+         * fileOps: {
+         *   pathArgs: ['path'],
+         *   operationType: 'write'
+         * }
+         * ```
+         */
+        fileOps?: FileOperationMeta;
+    }
+    /**
+     * Result of tool execution
+     */
+    interface ExecuteResult<TMeta extends ToolMetadata = ToolMetadata> {
+        /** Short title for display */
+        title: string;
+        /** Main output text */
+        output: string;
+        /** Metadata */
+        metadata: TMeta;
+    }
+    /**
+     * Define a tool with OpenCode-style patterns
+     *
+     * @example
+     * ```typescript
+     * const myTool = Tool.define("my_tool", {
+     *   description: "Does something useful",
+     *   parameters: z.object({
+     *     input: z.string().describe("The input to process"),
+     *   }),
+     *   execute: async (params, ctx) => ({
+     *     title: "Processed",
+     *     output: `Result: ${params.input}`,
+     *     metadata: {},
+     *   }),
+     * });
+     * ```
+     */
+    function define<TParams extends z.ZodType, TMeta extends ToolMetadata = ToolMetadata>(id: string, init: Info<TParams, TMeta>["init"] | Awaited<ReturnType<Info<TParams, TMeta>["init"]>>): Info<TParams, TMeta>;
+    /**
+     * Simple define for static tools (no async init)
+     */
+    function defineSimple<TParams extends z.ZodType, TMeta extends ToolMetadata = ToolMetadata>(id: string, config: {
+        description: string;
+        parameters: TParams;
+        execute: (params: z.infer<TParams>, ctx: ToolContext) => Promise<ExecuteResult<TMeta>>;
+    }): Info<TParams, TMeta>;
+}
+/**
+ * Legacy helper - wraps to Tool.Info format
+ *
+ * @deprecated Use Tool.define instead
+ */
+declare function defineTool<TParams extends z.ZodType>(definition: {
+    id: string;
+    description: string;
+    parameters: TParams;
+    execute: (params: z.infer<TParams>, ctx: ToolContext) => Promise<ToolResult>;
+}): Tool.Info<TParams>;
+
+/**
+ * Tool registry for @cuylabs/agent-core
+ *
+ * Manages available tools, named groups, and resolution from specs.
+ */
+
+/**
+ * A tool spec that can be resolved to an array of tools.
+ *
+ * - `string`   — group name (`"read-only"`), single tool ID (`"bash"`),
+ *                or comma-separated list (`"read,grep,glob"`).
+ *                Prefix with `-` to exclude: `"all,-bash"`.
+ * - `string[]` — array of tool IDs and/or group names.
+ * - `Tool.AnyInfo[]` — pass-through (already resolved).
+ * - `true`     — all registered tools.
+ * - `false`    — no tools.
+ */
+type ToolSpec = string | string[] | Tool.AnyInfo[] | boolean;
+/**
+ * Tool registry — manages available tools and named groups.
+ *
+ * Tools are registered individually. Groups are named collections of tool IDs
+ * that resolve against the registry at lookup time.
+ *
+ * @example
+ * ```typescript
+ * const reg = new ToolRegistry();
+ * reg.registerAll([readTool, grepTool, bashTool]);
+ * reg.registerGroup("read-only", ["read", "grep", "glob"]);
+ *
+ * // Resolve a spec to a tool array
+ * reg.resolve("read-only");             // → [readTool, grepTool]
+ * reg.resolve("all,-bash");             // → [readTool, grepTool]
+ * reg.resolve(["read", "grep"]);        // → [readTool, grepTool]
+ * reg.resolve(true);                    // → all tools
+ * ```
+ */
+declare class ToolRegistry {
+    private tools;
+    private groups;
+    /**
+     * Register a tool. Throws if a tool with the same ID is already registered.
+     * Use `set()` for upsert semantics.
+     */
+    register(tool: Tool.AnyInfo): void;
+    /** Register multiple tools (throws on duplicates). */
+    registerAll(tools: Tool.AnyInfo[]): void;
+    /** Register or replace a tool (upsert). */
+    set(tool: Tool.AnyInfo): void;
+    /** Unregister a tool by ID. Returns `true` if it existed. */
+    unregister(id: string): boolean;
+    /** Get a tool by ID. */
+    get(id: string): Tool.AnyInfo | undefined;
+    /** Check if a tool is registered. */
+    has(id: string): boolean;
+    /** Get all tool IDs. */
+    ids(): string[];
+    /** Get all tools. */
+    all(): Tool.AnyInfo[];
+    /** Clear all tools and groups. */
+    clear(): void;
+    /** Number of registered tools. */
+    get size(): number;
+    /**
+     * Register a named group of tool IDs.
+     * The group name can be used in `resolve()` specs.
+     * Tool IDs don't need to be registered yet — resolution is lazy.
+     */
+    registerGroup(name: string, toolIds: string[]): void;
+    /** Get tools in a group (only returns registered tools). */
+    getGroup(name: string): Tool.AnyInfo[] | undefined;
+    /** Check if a group is registered. */
+    hasGroup(name: string): boolean;
+    /** List all group names. */
+    listGroups(): string[];
+    /**
+     * Resolve a `ToolSpec` to an array of tools.
+     *
+     * Supports group names, individual tool IDs, comma-separated strings,
+     * exclusions with `-` prefix, booleans, and pass-through arrays.
+     *
+     * @example
+     * ```typescript
+     * registry.resolve("read-only");          // group name
+     * registry.resolve("read,grep,glob");     // comma-separated IDs
+     * registry.resolve("all,-bash");          // all except bash
+     * registry.resolve(["read", "grep"]);     // array of IDs
+     * registry.resolve(true);                 // all registered tools
+     * registry.resolve(false);                // empty array
+     * ```
+     */
+    resolve(spec: ToolSpec): Tool.AnyInfo[];
+}
+/**
+ * Default tool registry instance.
+ * Shared across the application — register tools here for global access.
+ */
+declare const defaultRegistry: ToolRegistry;
+
+/**
+ * Output truncation utilities for @cuylabs/agent-core
+ *
+ * Based on OpenCode's tool/truncation.ts
+ */
+/** Maximum lines before truncation */
+declare const MAX_LINES = 2000;
+/** Maximum bytes before truncation */
+declare const MAX_BYTES = 100000;
+/** Directory for storing truncated outputs */
+declare const TRUNCATE_DIR: string;
+/** Glob pattern for truncation directory */
+declare const TRUNCATE_GLOB: string;
+interface TruncateResult {
+    /** The (possibly truncated) content */
+    content: string;
+    /** Whether the content was truncated */
+    truncated: boolean;
+    /** Path to full output if truncated */
+    outputPath?: string;
+}
+/**
+ * Truncate output if it exceeds limits
+ */
+declare function truncateOutput(output: string, options?: {
+    maxLines?: number;
+    maxBytes?: number;
+}): TruncateResult;
+/**
+ * Format file size for display
+ */
+declare function formatSize(bytes: number): string;
+
+export { type DirEntry as D, type ExecOptions as E, type FileOperationMeta as F, MAX_BYTES as M, type ToolHost as T, Tool as a, type TurnTrackerContext as b, type ExecResult as c, type FileStat as d, MAX_LINES as e, TRUNCATE_DIR as f, TRUNCATE_GLOB as g, type ToolContext as h, type ToolMetadata as i, ToolRegistry as j, type ToolResult as k, type ToolSpec as l, type TruncateResult as m, defaultRegistry as n, defineTool as o, formatSize as p, truncateOutput as t };