@cuylabs/agent-core 0.3.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-QR704uRr.d.ts → index-BlSTfS-W.d.ts}

@@ -203,7 +203,7 @@ 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.
  */
 
 /**
@@ -233,7 +233,7 @@ interface CompatibleSchema<T = any> {
  */
 type InferSchemaOutput<T extends CompatibleSchema> = T["_output"];
 /**
- * Tool namespace - OpenCode-style tool definition
+ * Tool namespace - tool definition utilities
  */
 declare namespace Tool {
     /**
@@ -298,7 +298,7 @@ declare namespace Tool {
         metadata: TMeta;
     }
     /**
-     * Define a tool with OpenCode-style patterns
+     * Define a tool with standard patterns
      *
      * @example
      * ```typescript
@@ -438,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;
@@ -469,4 +467,4 @@ declare function truncateOutput(output: string, options?: {
  */
 declare function formatSize(bytes: number): string;
 
-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, 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 };