@cuylabs/agent-core 0.2.0 → 0.4.0

package/README.md

@@ -4,16 +4,20 @@ Embeddable AI agent infrastructure using Vercel AI SDK. Core building blocks for
 
 ## Features
 
-- **Agent Framework** - Create AI agents with tool support and streaming responses
-- **Session Management** - Persistent conversation state with branching support
-- **LLM Streaming** - Real-time streaming with proper backpressure handling
-- **Error Resilience** - Automatic retry with exponential backoff
-- **Context Management** - Token counting and automatic context pruning
-- **Tool Framework** - Type-safe tool definitions with Zod schemas
-- **Approval System** - Configurable tool approval workflows
-- **Checkpoint System** - Undo/restore capabilities for file operations
-- **Model Capabilities** - Runtime model capability detection
-- **MCP Support** - Extend agents with Model Context Protocol servers
+- **Agent Framework** — Create AI agents with tool support and streaming responses
+- **Session Management** — Persistent conversation state with branching support
+- **LLM Streaming** — Real-time streaming with proper backpressure handling
+- **Error Resilience** — Automatic retry with exponential backoff
+- **Context Management** — Token counting and automatic context pruning
+- **Tool Framework** — Type-safe tool definitions with Zod schemas
+- **Middleware** — Composable lifecycle hooks for tool interception, prompt injection, logging, and guardrails
+- **Skills** — Modular knowledge packs with progressive disclosure (L1 summary → L2 content → L3 resources)
+- **Approval System** — Configurable tool approval via middleware (rules + interactive prompts)
+- **Checkpoint System** — Undo/restore capabilities for file operations
+- **Model Capabilities** — Runtime model capability detection
+- **MCP Support** — Extend agents with Model Context Protocol servers
+- **Sub-Agents** — Fork agents with inherited config, run tasks in parallel, or let the LLM delegate via `invoke_agent`
+- **Presets** — Reusable agent configurations with tool filtering
 
 ## Installation
 
@@ -44,22 +48,23 @@ import { openai } from "@ai-sdk/openai";
 import { z } from "zod";
 
 // Define tools
-const tools: Tool[] = [
-  {
-    name: "greet",
-    description: "Greet a user by name",
-    parameters: z.object({
-      name: z.string().describe("Name to greet"),
-    }),
-    execute: async ({ name }) => `Hello, ${name}!`,
-  },
-];
+const greet = Tool.define("greet", {
+  description: "Greet a user by name",
+  parameters: z.object({
+    name: z.string().describe("Name to greet"),
+  }),
+  execute: async ({ name }) => ({
+    title: "Greeting",
+    output: `Hello, ${name}!`,
+    metadata: {},
+  }),
+});
 
 // Create agent
 const agent = createAgent({
   model: openai("gpt-4o"),
-  cwd: process.cwd(),
-  tools,
+  tools: [greet],
+  systemPrompt: "You are a helpful assistant.",
 });
 
 // Stream responses
@@ -68,7 +73,7 @@ for await (const event of agent.chat("session-1", "Hello!")) {
     case "text-delta":
       process.stdout.write(event.text);
       break;
-    case "tool-call":
+    case "tool-start":
       console.log(`Calling tool: ${event.toolName}`);
       break;
     case "tool-result":
@@ -150,26 +155,131 @@ await sessions.createSession({ id: "my-session" });
 ### Tool Framework
 
 ```typescript
-import { defineTool, Tool, ToolRegistry } from "@cuylabs/agent-core";
+import { Tool } from "@cuylabs/agent-core";
 import { z } from "zod";
 
-const myTool = defineTool({
-  name: "calculate",
-  description: "Perform a calculation",
+const calculator = Tool.define("calculator", {
+  description: "Evaluate a math expression",
   parameters: z.object({
     expression: z.string(),
   }),
   execute: async ({ expression }, ctx) => {
-    // ctx provides sessionId, cwd, abort signal, etc.
-    return eval(expression); // Don't actually do this!
+    // ctx provides sessionID, cwd, abort signal, host, etc.
+    return {
+      title: "Calculator",
+      output: String(eval(expression)), // Don't actually do this!
+      metadata: {},
+    };
   },
 });
+```
+
+### Middleware
 
-// Register tools
-const registry = new ToolRegistry();
-registry.register(myTool);
+Composable lifecycle hooks for tool interception, prompt injection, logging, and guardrails:
+
+```typescript
+import { createAgent, type AgentMiddleware, approvalMiddleware } from "@cuylabs/agent-core";
+
+// Simple logging middleware
+const logger: AgentMiddleware = {
+  name: "logger",
+  async beforeToolCall(tool, args) {
+    console.log(`→ ${tool}`, args);
+    return { action: "allow" };
+  },
+  async afterToolCall(tool, _args, result) {
+    console.log(`← ${tool}`, result.title);
+    return result;
+  },
+  async onChatStart(sessionId, message) {
+    console.log(`Chat started: ${sessionId}`);
+  },
+  async onChatEnd(sessionId, { usage, error }) {
+    console.log(`Chat ended: ${usage?.totalTokens} tokens`);
+  },
+};
+
+// Guardrail middleware — block dangerous tools
+const guardrail: AgentMiddleware = {
+  name: "guardrail",
+  async beforeToolCall(tool) {
+    if (tool === "bash") {
+      return { action: "deny", reason: "Shell commands are disabled." };
+    }
+    return { action: "allow" };
+  },
+};
+
+const agent = createAgent({
+  model: openai("gpt-4o"),
+  tools: myTools,
+  middleware: [
+    logger,
+    guardrail,
+    approvalMiddleware({
+      rules: [{ pattern: "*", tool: "read_file", action: "allow" }],
+      onRequest: async (req) => {
+        // Prompt user for approval
+        return await askUser(req);
+      },
+    }),
+  ],
+});
 ```
 
+Middleware hooks: `beforeToolCall`, `afterToolCall`, `promptSections`, `onEvent`, `onChatStart`, `onChatEnd`. Sub-agents inherit middleware via `fork()`.
+
+### Skills
+
+Modular knowledge packs with three-level progressive disclosure:
+
+```typescript
+import { createAgent, createSkillRegistry, createSkillTools } from "@cuylabs/agent-core";
+
+// Discover skills from SKILL.md files
+const registry = await createSkillRegistry(process.cwd(), {
+  externalDirs: [".agents", ".claude"],
+});
+
+// Create skill tools (skill + skill_resource)
+const skillTools = createSkillTools(registry);
+
+// Inject L1 summary into system prompt, give agent skill tools
+const agent = createAgent({
+  model: openai("gpt-4o"),
+  tools: [...myTools, ...skillTools],
+  systemPrompt: `You are a coding assistant.\n\n${registry.formatSummary()}`,
+});
+```
+
+Skills use the `SKILL.md` format with YAML frontmatter. See [examples/skills/](examples/skills/) for samples.
+
+### Built-in Sub-Agent Tools
+
+Let the LLM delegate work to specialized sub-agents via tool calls:
+
+```typescript
+import { createAgent, createSubAgentTools, Presets } from "@cuylabs/agent-core";
+import type { AgentProfile } from "@cuylabs/agent-core";
+
+const profiles: AgentProfile[] = [
+  { name: "explorer", description: "Fast code search", preset: Presets.explore },
+  { name: "reviewer", description: "Thorough code review", preset: Presets.review },
+];
+
+const parent = createAgent({ model, tools: codeTools });
+const subTools = createSubAgentTools(parent, { profiles, async: true });
+
+const agent = createAgent({
+  model,
+  tools: [...codeTools, ...subTools],
+});
+// The LLM can now call invoke_agent, wait_agent, and close_agent
+```
+
+Tools: `invoke_agent` (spawn), `wait_agent` (collect results), `close_agent` (cancel). Supports sync and async modes, depth limiting, and concurrency control. See [docs/subagents.md](docs/subagents.md#built-in-sub-agent-tools-llm-callable).
+
 ### Error Handling & Retry
 
 ```typescript
@@ -262,14 +372,30 @@ The `chat()` method yields these event types:
 | Event Type | Description |
 |------------|-------------|
 | `text-delta` | Streaming text chunk |
-| `tool-call` | Tool invocation started |
+| `text-start` / `text-end` | Text generation boundaries |
+| `tool-start` | Tool invocation started |
 | `tool-result` | Tool execution completed |
-| `reasoning` | Model reasoning (if supported) |
-| `message` | Complete assistant message |
+| `tool-error` | Tool execution failed |
+| `step-start` / `step-finish` | LLM step boundaries with usage stats |
+| `reasoning-delta` | Model reasoning chunk (if supported) |
+| `status` | Agent state changes (thinking, calling-tool, etc.) |
+| `doom-loop` | Repeated tool call pattern detected |
+| `context-overflow` | Context window exceeded |
+| `message` | Complete user/assistant message |
 | `complete` | Stream finished with usage stats |
-| `error` | Error occurred |
+| `error` | Unrecoverable error |
+
+See [examples/03-streaming.ts](examples/03-streaming.ts) for a complete event handling example.
 
 ## Concurrency Note
 
 When using `runConcurrent()` to run multiple tasks in parallel, be aware that all tasks share the same `SessionManager` instance. For independent conversations, create separate `Agent` instances or use distinct session IDs.
 
+## Examples
+
+See [examples/](examples/) for 17 runnable examples covering every feature — from basic chat to middleware, skills, and Docker execution. The [examples README](examples/README.md) has setup instructions and run commands.
+
+## Documentation
+
+See [docs/](docs/) for in-depth guides on each subsystem.
+

package/dist/{index-eud06GDQ.d.ts → index-BlSTfS-W.d.ts}

@@ -203,17 +203,43 @@ interface ToolMetadata {
 /**
  * Tool definition namespace for @cuylabs/agent-core
  *
- * Following OpenCode's Tool.define pattern for consistent tool creation.
+ * Provides consistent tool creation via Tool.define.
  */
 
 /**
- * Tool namespace - OpenCode-style tool definition
+ * 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 z.ZodType = z.ZodType, TMeta extends ToolMetadata = ToolMetadata> {
+    interface Info<TParams extends CompatibleSchema = any, TMeta extends ToolMetadata = ToolMetadata> {
         /** Unique tool identifier */
         id: string;
         /** Initialize the tool (can be async for dynamic descriptions) */
@@ -235,13 +261,13 @@ declare namespace Tool {
     /**
      * Result of tool initialization
      */
-    interface InitResult<TParams extends z.ZodType = z.ZodType, TMeta extends ToolMetadata = ToolMetadata> {
+    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: z.infer<TParams>, ctx: ToolContext) => Promise<ExecuteResult<TMeta>>;
+        execute: (params: InferSchemaOutput<TParams>, ctx: ToolContext) => Promise<ExecuteResult<TMeta>>;
         /** Optional custom validation error formatter */
         formatValidationError?: (error: z.ZodError) => string;
         /**
@@ -272,7 +298,7 @@ declare namespace Tool {
         metadata: TMeta;
     }
     /**
-     * Define a tool with OpenCode-style patterns
+     * Define a tool with standard patterns
      *
      * @example
      * ```typescript
@@ -289,14 +315,14 @@ declare namespace Tool {
      * });
      * ```
      */
-    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>;
+    function define<TParams extends CompatibleSchema, 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: {
+    function defineSimple<TParams extends CompatibleSchema, TMeta extends ToolMetadata = ToolMetadata>(id: string, config: {
         description: string;
         parameters: TParams;
-        execute: (params: z.infer<TParams>, ctx: ToolContext) => Promise<ExecuteResult<TMeta>>;
+        execute: (params: InferSchemaOutput<TParams>, ctx: ToolContext) => Promise<ExecuteResult<TMeta>>;
     }): Info<TParams, TMeta>;
 }
 /**
@@ -304,11 +330,11 @@ declare namespace Tool {
  *
  * @deprecated Use Tool.define instead
  */
-declare function defineTool<TParams extends z.ZodType>(definition: {
+declare function defineTool<TParams extends CompatibleSchema>(definition: {
     id: string;
     description: string;
     parameters: TParams;
-    execute: (params: z.infer<TParams>, ctx: ToolContext) => Promise<ToolResult>;
+    execute: (params: InferSchemaOutput<TParams>, ctx: ToolContext) => Promise<ToolResult>;
 }): Tool.Info<TParams>;
 
 /**
@@ -412,8 +438,6 @@ 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;
@@ -443,4 +467,4 @@ declare function truncateOutput(output: string, options?: {
  */
 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 };
+export { type CompatibleSchema as C, type DirEntry as D, type ExecOptions as E, type FileOperationMeta as F, type InferSchemaOutput as I, MAX_BYTES as M, type ToolHost as T, type ToolContext as a, Tool as b, type TurnTrackerContext as c, type ExecResult as d, type FileStat as e, MAX_LINES as f, TRUNCATE_DIR as g, TRUNCATE_GLOB 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 };