@cuylabs/agent-core 0.5.0 → 0.7.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,88 @@ 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 { Inference } from "@cuylabs/agent-core/inference";
+import { createAgentTaskRunner } from "@cuylabs/agent-core/runtime";
+import { localHost } from "@cuylabs/agent-core/host";
+import { createPromptBuilder } from "@cuylabs/agent-core/prompt";
+import { withinScope } from "@cuylabs/agent-core/scope";
+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`, `models`, `mcp`, `inference`, `host`, and `scope`.
 
-```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/scope.md](./docs/scope.md) for nested execution lineage and scope snapshots
+- [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-BRvqCcIk.d.ts}

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

package/dist/{resolver-DOfZ-xuk.d.ts → capability-resolver-CgRGsWVX.d.ts}

@@ -251,4 +251,4 @@ declare function getDefaultResolver(): ModelCapabilityResolver;
  */
 declare function configureResolver(options: Partial<ResolverOptions>): void;
 
-export { type CapabilitySource as C, DEFAULT_RESOLVER_OPTIONS as D, type InputModality as I, type ModelEntry as M, type NetworkStatus as N, type OutputModality as O, type ProviderCompatibility as P, type ResolverOptions as R, SourcePriority as S, extractProvider as a, type SourceResult as b, type ModelCapabilities as c, ModelCapabilityResolver as d, extractModelId as e, type ResolutionResult as f, configureResolver as g, getDefaultResolver as h };
+export { type CapabilitySource as C, DEFAULT_RESOLVER_OPTIONS as D, type InputModality as I, type ModelCapabilities as M, type NetworkStatus as N, type OutputModality as O, type ProviderCompatibility as P, type ResolutionResult as R, SourcePriority as S, ModelCapabilityResolver as a, type ModelEntry as b, type ResolverOptions as c, type SourceResult as d, configureResolver as e, extractModelId as f, extractProvider as g, getDefaultResolver as h };