@cuylabs/agent-core 0.5.0 → 0.6.0

package/README.md

@@ -1,26 +1,40 @@
 # @cuylabs/agent-core
 
-Embeddable AI agent infrastructure using Vercel AI SDK. Core building blocks for AI agents with session management, tools, skills, sub-agents, and tracing.
-
-## Features
-
-- **Named Agents** — `name` field for identity in spans, runtime traces, and logging
-- **Agent Framework** — Create AI agents with tool support and streaming responses
-- **OpenTelemetry Tracing** — Built-in tracing with a single `tracing` config — Zipkin, Phoenix, any OTLP backend
-- **Session Management** — Persistent conversation state with branching support
-- **Execution Streaming** — Real-time event 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
-- **Runtime Integration** — Extracted turn-runner phases for durable workflow integration
+Embeddable AI agent infrastructure built on the AI SDK.
+
+`@cuylabs/agent-core` is the in-process execution layer in this workspace. It
+owns the `Agent` API, tool and model execution semantics, middleware, sessions,
+prompt construction, tracing, and the reusable task/turn/workflow primitives
+that higher layers build on.
+
+## Package Boundary
+
+Use `@cuylabs/agent-core` when you want:
+
+- `Agent` creation and `chat()` / `send()` APIs
+- tool definition and execution
+- model hooks, tool hooks, and lifecycle middleware
+- sessions, storage, branching, and prompt construction
+- tracing, MCP, skills, presets, and sub-agents
+- runtime-facing task/turn/workflow helpers from `@cuylabs/agent-core/runtime`
+
+This package does not own outer orchestration or hosting:
+
+- use `@cuylabs/agent-runtime` for jobs, schedules, retries, and workload dispatch
+- use `@cuylabs/agent-runtime-dapr` for Dapr-backed durability and workflow hosting
+- use `@cuylabs/agent-http` for an AI SDK chat-stream HTTP adapter
+
+## Core Capabilities
+
+- Streaming agent execution with structured events
+- Type-safe tools with Zod schemas
+- Middleware for model input/output, stream chunks, tool calls, and lifecycle hooks
+- Session persistence with branching support
+- Prompt pipeline and dynamic prompt sections
+- Skills and built-in sub-agent delegation
+- OpenTelemetry tracing
+- MCP integration
+- Runtime-facing task, turn, and workflow primitives for durable adapters
 
 ## Installation
 
@@ -30,14 +44,14 @@ npm install @cuylabs/agent-core
 pnpm add @cuylabs/agent-core
 ```
 
-You'll also need at least one AI SDK provider:
+You will also need at least one AI SDK provider:
 
 ```bash
 npm install @ai-sdk/openai
 # or @ai-sdk/anthropic, @ai-sdk/google
 ```
 
-For OpenAI-compatible endpoints (local or hosted), add:
+For OpenAI-compatible endpoints, add:
 
 ```bash
 npm install @ai-sdk/openai-compatible
@@ -45,33 +59,15 @@ npm install @ai-sdk/openai-compatible
 
 ## Quick Start
 
-Everything is available from the root import, plus focused subpath imports for clearer boundaries:
-
-```typescript
-import { createAgent, Tool } from "@cuylabs/agent-core";            // full API
-import { defineTool } from "@cuylabs/agent-core/tool";              // tools only
-import { createSkillRegistry } from "@cuylabs/agent-core/skill";    // skill system
-import { createSubAgentTools } from "@cuylabs/agent-core/sub-agent"; // sub-agents
-import { createAgentTaskRunner } from "@cuylabs/agent-core/runtime"; // runtime
-import type { AgentMiddleware } from "@cuylabs/agent-core/middleware"; // middleware
-import { createPromptBuilder } from "@cuylabs/agent-core/prompt";    // prompts
-import { createMCPManager } from "@cuylabs/agent-core/mcp";          // MCP integration
-```
-
-Additional focused entrypoints are available for `storage`, `context`, `reasoning`,
-`capabilities`, `models`, and `tracking` when you want imports to mirror the
-module layout.
-
 ```typescript
 import { createAgent, Tool } from "@cuylabs/agent-core";
 import { openai } from "@ai-sdk/openai";
 import { z } from "zod";
 
-// Define tools
 const greet = Tool.define("greet", {
   description: "Greet a user by name",
   parameters: z.object({
-    name: z.string().describe("Name to greet"),
+    name: z.string(),
   }),
   execute: async ({ name }) => ({
     title: "Greeting",
@@ -80,371 +76,84 @@ const greet = Tool.define("greet", {
   }),
 });
 
-// Create agent
 const agent = createAgent({
-  name: "my-assistant",
+  name: "assistant",
   model: openai("gpt-4o"),
   tools: [greet],
   systemPrompt: "You are a helpful assistant.",
 });
 
-// Stream responses
-for await (const event of agent.chat("session-1", "Hello!")) {
+for await (const event of agent.chat("session-1", "Say hi to Ada")) {
   switch (event.type) {
     case "text-delta":
       process.stdout.write(event.text);
       break;
     case "tool-start":
-      console.log(`Calling tool: ${event.toolName}`);
+      console.log(`calling ${event.toolName}`);
       break;
     case "tool-result":
-      console.log(`Tool result: ${event.result}`);
+      console.log(`tool result:`, event.result);
       break;
     case "complete":
-      console.log("\nDone!");
+      console.log("\ndone");
       break;
   }
 }
 ```
 
-## API Reference
-
-### Local Models (Ollama Example)
-
-```typescript
-import { createAgent, createResolver } from "@cuylabs/agent-core";
-
-const resolveModel = createResolver({
-  engines: {
-    ollama: {
-      adapter: "openai-compatible",
-      settings: {
-        baseUrl: "http://localhost:11434/v1",
-      },
-    },
-  },
-});
-
-const agent = createAgent({
-  model: resolveModel("ollama/llama3.1"),
-  cwd: process.cwd(),
-});
-```
-
-### Agent
-
-```typescript
-import { createAgent, Agent } from "@cuylabs/agent-core";
-import { openai } from "@ai-sdk/openai";
-
-const agent = createAgent({
-  model: openai("gpt-4o"),
-  cwd: "/path/to/project",
-  tools: myTools,
-  systemPrompt: "You are a helpful assistant.",
-  temperature: 0.7,
-  maxSteps: 10,
-});
-
-// Streaming chat
-for await (const event of agent.chat(sessionId, message)) {
-  // Handle events
-}
-```
-
-### Session Management
+## Focused Imports
 
-```typescript
-import { 
-  SessionManager, 
-  MemoryStorage, 
-  FileStorage 
-} from "@cuylabs/agent-core";
-
-// In-memory storage (default)
-const memoryStorage = new MemoryStorage();
-
-// File-based persistent storage
-const fileStorage = new FileStorage({
-  directory: "/path/to/data",
-});
-
-const sessions = new SessionManager(fileStorage);
-await sessions.create({ id: "my-session", cwd: process.cwd() });
-```
-
-### Tool Framework
+The root export is available, but focused subpath imports mirror the package
+structure when you want clearer boundaries:
 
 ```typescript
-import { Tool } from "@cuylabs/agent-core";
-import { z } from "zod";
-
-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, host, etc.
-    return {
-      title: "Calculator",
-      output: String(eval(expression)), // Don't actually do this!
-      metadata: {},
-    };
-  },
-});
-```
-
-### Middleware
-
-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()`.
-
-### Tracing (OpenTelemetry)
-
-Enable full tracing with a single `tracing` field — no manual provider setup:
-
-```typescript
-import { createAgent } from "@cuylabs/agent-core";
-import { openai } from "@ai-sdk/openai";
-import { SimpleSpanProcessor } from "@opentelemetry/sdk-trace-node";
-import { ZipkinExporter } from "@opentelemetry/exporter-zipkin";
-
-const agent = createAgent({
-  name: "my-agent",
-  model: openai("gpt-4o"),
-  tools: [myTool],
-  tracing: {
-    spanProcessor: new SimpleSpanProcessor(
-      new ZipkinExporter({ url: "http://localhost:9411/api/v2/spans" }),
-    ),
-  },
-});
-
-// ... use agent ...
-
-// Flush spans before exit
-await agent.close();
-```
-
-This auto-creates agent-level, tool-level, and AI SDK LLM spans following the [GenAI Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/). Works with Zipkin, Arize Phoenix, Jaeger, or any OTLP backend. See [docs/tracing.md](docs/tracing.md) for the full reference.
-
-### 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
-import { 
-  withRetry, 
-  LLMError, 
-  isRetryable,
-  getRetryDelay 
-} from "@cuylabs/agent-core";
-
-const result = await withRetry(
-  async () => {
-    // Your operation
-  },
-  {
-    maxRetries: 3,
-    initialDelay: 1000,
-    maxDelay: 30000,
-  }
-);
-```
-
-### Context Management
-
-```typescript
-import { 
-  ContextManager,
-  estimateTokens,
-  pruneContext 
-} from "@cuylabs/agent-core";
-
-const ctx = new ContextManager({
-  maxInputTokens: 100000,
-  pruneThreshold: 0.9,
-});
-
-const tokens = estimateTokens("Your text here");
-```
-
-### Model Capabilities
-
-```typescript
-import { 
-  ModelCapabilityResolver,
-  getDefaultResolver 
-} from "@cuylabs/agent-core";
-
-const resolver = getDefaultResolver();
-const caps = await resolver.resolve("gpt-4o");
-
-console.log(caps.supportsImages);
-console.log(caps.supportsToolUse);
-console.log(caps.maxOutputTokens);
+import { createAgent, Tool } from "@cuylabs/agent-core";
+import type { AgentMiddleware } from "@cuylabs/agent-core/middleware";
+import { createAgentTaskRunner } from "@cuylabs/agent-core/runtime";
+import { createPromptBuilder } from "@cuylabs/agent-core/prompt";
+import { createSkillRegistry } from "@cuylabs/agent-core/skill";
+import { createSubAgentTools } from "@cuylabs/agent-core/sub-agent";
+import { createMCPManager } from "@cuylabs/agent-core/mcp";
 ```
 
-### MCP (Model Context Protocol)
+Additional focused entrypoints are available for `tool`, `tracking`, `storage`,
+`context`, `reasoning`, `capabilities`, and `models`.
 
-```typescript
-import { 
-  createAgent, 
-  createMCPManager, 
-  stdioServer 
-} from "@cuylabs/agent-core";
-import { anthropic } from "@ai-sdk/anthropic";
-
-// Create MCP manager with servers
-const mcp = createMCPManager({
-  filesystem: stdioServer("npx", [
-    "-y", "@modelcontextprotocol/server-filesystem", "/tmp"
-  ]),
-});
+## Relationship To The Runtime Packages
 
-// Create agent with MCP tools
-const agent = createAgent({
-  model: anthropic("claude-sonnet-4-20250514"),
-  mcp,
-});
-
-// MCP tools are automatically available
-const result = await agent.send("session", "List files in /tmp");
+The layering is:
 
-// Clean up
-await agent.close();
+```text
+agent-core
+  -> agent-runtime
+    -> agent-runtime-dapr
 ```
 
-## Event Types
-
-The `chat()` method yields these event types:
+- `agent-core` owns live agent execution
+- `agent-runtime` owns generic workload scheduling and dispatch
+- `agent-runtime-dapr` adds Dapr-backed durability and host integration
 
-| Event Type | Description |
-|------------|-------------|
-| `text-delta` | Streaming text chunk |
-| `text-start` / `text-end` | Text generation boundaries |
-| `tool-start` | Tool invocation started |
-| `tool-result` | Tool execution completed |
-| `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` | Unrecoverable error |
+If you need durable orchestration, `agent-core` already exposes the task and
+turn surfaces those packages build on:
 
-See [examples/03-streaming.ts](examples/03-streaming.ts) for a complete event handling example.
+- `createAgentTaskRunner(...)`
+- task execution observers and checkpoints
+- turn-step helpers such as `prepareModelStep(...)` and `runToolBatch(...)`
+- workflow-safe state/planning helpers
 
-## Concurrency Note
+## Learn More
 
-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.
+Start with the package docs:
 
-## Examples
+- [docs/README.md](./docs/README.md) for the learning path
+- [docs/agent.md](./docs/agent.md) for the main `Agent` API
+- [docs/middleware.md](./docs/middleware.md) for model/tool hooks and lifecycle middleware
+- [docs/tools.md](./docs/tools.md) for tool definition and execution
+- [docs/runtime-integration.md](./docs/runtime-integration.md) for task/turn/workflow runtime integration
+- [docs/tracing.md](./docs/tracing.md) for tracing setup
 
-See [examples/](examples/) for 20 runnable examples covering every feature — from basic chat to middleware, skills, tracing, and Docker execution. The [examples README](examples/README.md) has setup instructions and run commands.
+Runnable examples live in [examples/README.md](./examples/README.md).
 
-## Documentation
+## License
 
-See [docs/](docs/) for in-depth guides on each subsystem.
+Apache-2.0

package/dist/{builder-RcTZuYnO.d.ts → builder-BKkipazh.d.ts}

@@ -1,4 +1,4 @@
-import { P as PromptConfig, a as PromptBuildContext, M as MiddlewareRunner, b as PromptSection, c as ModelFamily } from './runner-C7aMP_x3.js';
+import { P as PromptConfig, a as PromptBuildContext, M as MiddlewareRunner, b as PromptSection, c as ModelFamily } from './runner-G1wxEgac.js';
 import { S as SkillRegistry } from './registry-CuRWWtcT.js';
 
 interface PromptSectionPreview {