@cuylabs/agent-core 0.4.0 → 0.6.0

package/dist/tool-DYp6-cC3.d.ts

@@ -0,0 +1,239 @@
+/**
+ * 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";
+}
+/**
+ * Replay mode used by resume-capable runtimes after a crash.
+ *
+ * - `replay` — the tool may be executed again automatically
+ * - `skip` — the tool should not be replayed automatically
+ * - `manual` — a higher-level runtime must require an explicit decision
+ */
+type ToolReplayMode = "replay" | "skip" | "manual";
+/**
+ * Coarse side-effect classification for tool execution.
+ *
+ * - `none` — read-only or otherwise safe to repeat
+ * - `local` — mutates local state such as files
+ * - `external` — may affect processes, networks, services, or systems
+ */
+type ToolSideEffectLevel = "none" | "local" | "external";
+/**
+ * Declares how a resume-capable runtime should treat a tool after failure.
+ *
+ * This stays infrastructure-agnostic so Dapr and other runtimes can consume
+ * the same semantics without leaking runtime-specific types into `agent-core`.
+ */
+interface ToolReplayPolicy {
+    /** Replay behavior requested by the tool author. */
+    mode?: ToolReplayMode;
+    /** Coarse side-effect classification. */
+    sideEffectLevel?: ToolSideEffectLevel;
+    /** Optional human-readable rationale for audits and recovery UIs. */
+    reason?: string;
+}
+/**
+ * Fully resolved replay policy with defaults applied.
+ */
+interface NormalizedToolReplayPolicy {
+    mode: ToolReplayMode;
+    sideEffectLevel: ToolSideEffectLevel;
+    reason?: string;
+}
+/**
+ * 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;
+}
+
+export type { DirEntry as D, ExecOptions as E, FileOperationMeta as F, NormalizedToolReplayPolicy as N, ToolMetadata as T, ToolReplayPolicy as a, ToolContext as b, ToolResult as c, ToolHost as d, TurnTrackerContext as e, ExecResult as f, FileStat as g, ToolReplayMode as h, ToolSideEffectLevel as i };

package/dist/tool-pFAnJc5Y.d.ts

@@ -0,0 +1,419 @@
+import { z } from 'zod';
+import { T as ToolMetadata, a as ToolReplayPolicy, b as ToolContext, F as FileOperationMeta, c as ToolResult } from './tool-DYp6-cC3.js';
+
+/**
+ * Skill System Types
+ *
+ * Skills are modular, on-demand knowledge packs that extend an agent's
+ * capabilities with specialized instructions, workflows, and resources.
+ *
+ * Design principles:
+ *
+ * 1. **Progressive disclosure** — summaries always in context,
+ *    full content loaded only when needed. Minimizes baseline token cost.
+ *
+ * 2. **Scoped priority** — project skills override user skills
+ *    override global skills. Closest scope wins on name collision.
+ *
+ * 3. **Agent-initiated loading** — the agent decides when to
+ *    activate a skill by calling the `skill` tool. No guesswork.
+ *
+ * 4. **Bundled resources** — skills can ship scripts,
+ *    references, assets, and examples alongside instructions.
+ *
+ * 5. **Remote sources** — skills can be fetched from URLs,
+ *    enabling shared skill repositories across teams.
+ *
+ * The lifecycle:
+ *
+ *   Discovery → Registry → Summary injection → Agent tool call → Full load
+ *
+ * @packageDocumentation
+ */
+/**
+ * Where a skill was discovered, determining its override priority.
+ *
+ * When two skills share the same name, the narrower scope wins:
+ *   project > user > global > builtin
+ *
+ * Uses a 4-tier hierarchy with names that are intuitive for
+ * library consumers.
+ */
+type SkillScope = "project" | "user" | "global" | "builtin";
+/**
+ * How a skill was obtained — local filesystem or remote URL.
+ */
+type SkillSourceType = "local" | "remote";
+/**
+ * Where a skill came from, for provenance tracking.
+ */
+interface SkillSource {
+    /** Local or remote origin */
+    type: SkillSourceType;
+    /** Root directory or URL this skill was discovered under */
+    root: string;
+}
+/**
+ * Classification of bundled resources within a skill directory.
+ *
+ * Resource taxonomy:
+ * - `script`    — executable code for deterministic tasks (can be run without reading)
+ * - `reference` — documentation loaded into context on demand
+ * - `asset`     — templates, images, fonts used in output (not read into context)
+ * - `example`   — working code samples for the agent to learn from
+ */
+type SkillResourceType = "script" | "reference" | "asset" | "example";
+/**
+ * A file bundled with a skill.
+ *
+ * Resources are discovered but NOT loaded into memory until the agent
+ * explicitly requests them. This is the L3 layer of progressive disclosure.
+ */
+interface SkillResource {
+    /** Path relative to the skill's base directory */
+    relativePath: string;
+    /** Classified resource type */
+    type: SkillResourceType;
+    /** Absolute path on disk (for local resources) */
+    absolutePath: string;
+}
+/**
+ * Lightweight skill metadata parsed from SKILL.md YAML frontmatter.
+ *
+ * This is the **L1 layer** — always present in the system prompt so the
+ * agent knows which skills exist. Kept intentionally small (~100 words each)
+ * to minimize baseline context cost.
+ *
+ * Uses YAML frontmatter in a SKILL.md file — the widely-adopted
+ * canonical format for skill definitions.
+ */
+interface SkillMetadata {
+    /** Unique skill identifier (from frontmatter `name`) */
+    name: string;
+    /**
+     * When to use this skill — the single most important field.
+     *
+     * This description is what the agent reads to decide whether to
+     * activate the skill. Should contain trigger phrases that match
+     * task types. Written for another LLM to consume, not humans.
+     */
+    description: string;
+    /** Semantic version (from frontmatter, optional) */
+    version?: string;
+    /** Scope that determines override priority */
+    scope: SkillScope;
+    /** How this skill was obtained */
+    source: SkillSource;
+    /** Absolute path to the SKILL.md file */
+    filePath: string;
+    /** Directory containing the skill (parent of SKILL.md) */
+    baseDir: string;
+    /** Optional tags for categorization */
+    tags?: string[];
+    /**
+     * Names of skills this skill depends on.
+     * When this skill is loaded, its dependencies are suggested to be loaded too.
+     */
+    dependencies?: string[];
+}
+/**
+ * Full skill content including the markdown body and resource listing.
+ *
+ * This is the **L2 layer** — loaded only when the agent calls the skill
+ * tool. Contains the actual instructions plus awareness of bundled resources.
+ */
+interface SkillContent extends SkillMetadata {
+    /**
+     * The full markdown body of SKILL.md (everything below the frontmatter).
+     * This is the core instructional content injected into the conversation.
+     */
+    body: string;
+    /**
+     * Bundled resources discovered in the skill directory.
+     * Listed so the agent knows what's available but not yet loaded.
+     */
+    resources: SkillResource[];
+}
+/**
+ * Configuration for skill discovery and loading.
+ *
+ * Controls where skills are found, how deep to scan, and which
+ * external conventions to support.
+ *
+ * @example
+ * ```typescript
+ * const skillConfig: SkillConfig = {
+ *   // Scan standard locations
+ *   externalDirs: [".agents", ".claude"],
+ *   // Add custom skill roots
+ *   roots: ["./company-skills"],
+ *   // Limit scan depth for performance
+ *   maxScanDepth: 4,
+ * };
+ * ```
+ */
+interface SkillConfig {
+    /**
+     * Additional directories to scan for skills (absolute or relative to cwd).
+     * Each directory is scanned recursively for SKILL.md files.
+     */
+    roots?: string[];
+    /**
+     * External skill directory names to scan in project and home directories.
+     *
+     * These are checked as `<project>/<dir>/skills/` and `~/<dir>/skills/`.
+     * Supports `.claude` and `.agents` directory conventions.
+     *
+     * @default [".agents", ".claude"]
+     */
+    externalDirs?: string[];
+    /**
+     * Maximum directory depth to scan within each root.
+     * Higher values find more deeply nested skills but take longer.
+     *
+     * @default 4
+     */
+    maxScanDepth?: number;
+    /**
+     * Maximum file size for SKILL.md files in bytes.
+     * Skills larger than this are skipped with a warning.
+     *
+     * @default 102400 (100KB)
+     */
+    maxFileSize?: number;
+    /**
+     * Enable fetching skills from remote URLs.
+     * When false, `remoteUrls` is ignored.
+     *
+     * @default false
+     */
+    enableRemote?: boolean;
+    /**
+     * Remote skill index URLs to fetch.
+     *
+     * Each URL should serve a JSON index listing available skills.
+     * See `RemoteSkillIndex` for the expected format.
+     *
+     * @example
+     * ```typescript
+     * remoteUrls: ["https://skills.example.com/index.json"]
+     * ```
+     */
+    remoteUrls?: string[];
+    /**
+     * Cache directory for remote skills.
+     * Defaults to `~/.cache/cuylabs/skills/`.
+     */
+    remoteCacheDir?: string;
+    /**
+     * Include built-in skills bundled with agent-core.
+     * Currently reserved for future use.
+     *
+     * @default true
+     */
+    includeBuiltin?: boolean;
+}
+/**
+ * Schema for remote skill index JSON files.
+ *
+ * Hosted at a URL like `https://skills.example.com/index.json`.
+ * Enables team-wide or organization-wide skill sharing.
+ *
+ * @example
+ * ```json
+ * {
+ *   "version": 1,
+ *   "skills": [
+ *     {
+ *       "name": "testing",
+ *       "files": ["SKILL.md", "scripts/run-tests.sh", "references/patterns.md"]
+ *     }
+ *   ]
+ * }
+ * ```
+ */
+interface RemoteSkillIndex {
+    /** Schema version (currently 1) */
+    version: number;
+    /** List of available skills */
+    skills: RemoteSkillEntry[];
+}
+/**
+ * A single skill listing in a remote index.
+ */
+interface RemoteSkillEntry {
+    /** Skill name (must match the `name` in SKILL.md frontmatter) */
+    name: string;
+    /** Relative file paths to download (SKILL.md is required) */
+    files: string[];
+}
+/**
+ * Result of a full skill discovery pass.
+ */
+interface SkillDiscoveryResult {
+    /** All discovered skills (deduplicated, scope-prioritized) */
+    skills: SkillMetadata[];
+    /** Skills that failed to load with reasons */
+    errors: SkillDiscoveryError[];
+    /** Total directories scanned */
+    dirsScanned: number;
+    /** Discovery duration in milliseconds */
+    durationMs: number;
+}
+/**
+ * An error encountered during skill discovery.
+ */
+interface SkillDiscoveryError {
+    /** Path that caused the error */
+    path: string;
+    /** What went wrong */
+    reason: string;
+}
+
+/**
+ * Tool definition namespace for @cuylabs/agent-core
+ *
+ * Provides consistent tool creation via Tool.define.
+ */
+
+/**
+ * A schema type compatible with both Zod 3 and Zod 4.
+ *
+ * Uses structural typing so that schemas from either Zod version satisfy
+ * the constraint. This avoids the problem where Zod 3's `ZodType` class
+ * and Zod 4's `ZodType` class have incompatible internal shapes, causing
+ * type errors when a library compiled against one version is consumed with
+ * the other.
+ *
+ * Both Zod 3 and Zod 4 (classic API) schemas have `parse()` and `_output`.
+ */
+interface CompatibleSchema<T = any> {
+    /** Parse and validate input data. Present in both Zod 3 and Zod 4. */
+    parse(data: unknown): T;
+    /**
+     * Type-level output marker used by both Zod versions:
+     * - Zod 3: `readonly _output!: T` (definite assignment assertion)
+     * - Zod 4 classic: `get _output(): T` (getter)
+     */
+    readonly _output: T;
+}
+/**
+ * Infer the output type from a compatible schema.
+ * Equivalent to `z.infer<T>` but works with both Zod 3 and Zod 4 schemas.
+ */
+type InferSchemaOutput<T extends CompatibleSchema> = T["_output"];
+/**
+ * Tool namespace - tool definition utilities
+ */
+declare namespace Tool {
+    /**
+     * Tool info interface - the shape of a defined tool
+     */
+    interface Info<TParams extends CompatibleSchema = any, TMeta extends ToolMetadata = ToolMetadata> {
+        /** Unique tool identifier */
+        id: string;
+        /** Recovery semantics for resume-capable runtimes. */
+        replayPolicy?: ToolReplayPolicy;
+        /** 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 CompatibleSchema = any, TMeta extends ToolMetadata = ToolMetadata> {
+        /** Tool description for the LLM */
+        description: string;
+        /** Zod schema for parameters */
+        parameters: TParams;
+        /** Execute the tool */
+        execute: (params: InferSchemaOutput<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;
+        /** Optional replay metadata for resume-capable runtimes. */
+        replayPolicy?: ToolReplayPolicy;
+    }
+    /**
+     * Result of tool execution
+     */
+    interface ExecuteResult<TMeta extends ToolMetadata = ToolMetadata> {
+        /** Short title for display */
+        title: string;
+        /** Main output text */
+        output: string;
+        /** Metadata */
+        metadata: TMeta;
+    }
+    interface DefineOptions {
+        /** Static replay metadata exposed to higher-level runtimes. */
+        replayPolicy?: ToolReplayPolicy;
+    }
+    /**
+     * Define a tool with standard 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 CompatibleSchema, TMeta extends ToolMetadata = ToolMetadata>(id: string, init: Info<TParams, TMeta>["init"] | Awaited<ReturnType<Info<TParams, TMeta>["init"]>>, options?: DefineOptions): Info<TParams, TMeta>;
+    /**
+     * Simple define for static tools (no async init)
+     */
+    function defineSimple<TParams extends CompatibleSchema, TMeta extends ToolMetadata = ToolMetadata>(id: string, config: {
+        description: string;
+        parameters: TParams;
+        execute: (params: InferSchemaOutput<TParams>, ctx: ToolContext) => Promise<ExecuteResult<TMeta>>;
+        replayPolicy?: ToolReplayPolicy;
+    }): Info<TParams, TMeta>;
+}
+/**
+ * Legacy helper - wraps to Tool.Info format
+ *
+ * @deprecated Use Tool.define instead
+ */
+declare function defineTool<TParams extends CompatibleSchema>(definition: {
+    id: string;
+    description: string;
+    parameters: TParams;
+    execute: (params: InferSchemaOutput<TParams>, ctx: ToolContext) => Promise<ToolResult>;
+}): Tool.Info<TParams>;
+
+export { type CompatibleSchema as C, type InferSchemaOutput as I, type RemoteSkillEntry as R, type SkillDiscoveryResult as S, Tool as T, type SkillMetadata as a, type SkillContent as b, type SkillResource as c, type SkillConfig as d, type RemoteSkillIndex as e, type SkillDiscoveryError as f, type SkillResourceType as g, type SkillScope as h, type SkillSource as i, type SkillSourceType as j, defineTool as k };