@cuylabs/agent-core 0.4.0 → 0.6.0

package/README.md

@@ -1,23 +1,40 @@
 # @cuylabs/agent-core
 
-Embeddable AI agent infrastructure using Vercel AI SDK. Core building blocks for streaming AI agents with session management, resilience, and model capabilities.
-
-## 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
-- **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
+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
 
@@ -27,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
@@ -47,11 +64,10 @@ 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",
@@ -60,342 +76,84 @@ const greet = Tool.define("greet", {
   }),
 });
 
-// Create agent
 const agent = createAgent({
+  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, createModelResolver } from "@cuylabs/agent-core";
-
-const resolveModel = createModelResolver({
-  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
-
-```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({
-  dataDir: "/path/to/data",
-});
-
-const sessions = new SessionManager(fileStorage);
-await sessions.createSession({ id: "my-session" });
-```
-
-### Tool Framework
-
-```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()`.
+## Focused Imports
 
-### Skills
-
-Modular knowledge packs with three-level progressive disclosure:
+The root export is available, but focused subpath imports mirror the package
+structure when you want clearer boundaries:
 
 ```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)
-
-```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"
-  ]),
-});
+Additional focused entrypoints are available for `tool`, `tracking`, `storage`,
+`context`, `reasoning`, `capabilities`, and `models`.
 
-// Create agent with MCP tools
-const agent = createAgent({
-  model: anthropic("claude-sonnet-4-20250514"),
-  mcp,
-});
+## Relationship To The Runtime Packages
 
-// 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:
-
-| 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 |
+- `agent-core` owns live agent execution
+- `agent-runtime` owns generic workload scheduling and dispatch
+- `agent-runtime-dapr` adds Dapr-backed durability and host integration
 
-See [examples/03-streaming.ts](examples/03-streaming.ts) for a complete event handling example.
+If you need durable orchestration, `agent-core` already exposes the task and
+turn surfaces those packages build on:
 
-## Concurrency Note
+- `createAgentTaskRunner(...)`
+- task execution observers and checkpoints
+- turn-step helpers such as `prepareModelStep(...)` and `runToolBatch(...)`
+- workflow-safe state/planning helpers
 
-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.
+## Learn More
 
-## Examples
+Start with the package docs:
 
-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.
+- [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
 
-## Documentation
+Runnable examples live in [examples/README.md](./examples/README.md).
 
-See [docs/](docs/) for in-depth guides on each subsystem.
+## License
 
+Apache-2.0

package/dist/builder-BKkipazh.d.ts

@@ -0,0 +1,34 @@
+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 {
+    id: string;
+    label: string;
+    priority: number;
+    size: number;
+}
+
+declare class PromptBuilder {
+    private readonly config;
+    private customSections;
+    private envCache?;
+    private instructionCache?;
+    private skillRegistryCache?;
+    constructor(config?: PromptConfig);
+    build(context: PromptBuildContext, middleware?: MiddlewareRunner): Promise<string>;
+    addSection(section: PromptSection): void;
+    removeSection(id: string): boolean;
+    toggleSection(id: string, enabled: boolean): void;
+    getSections(): PromptSection[];
+    hasSection(id: string): boolean;
+    clearCache(): void;
+    getSkillRegistry(cwd: string): Promise<SkillRegistry>;
+    getModelFamily(model: PromptBuildContext["model"]): ModelFamily;
+    getBaseTemplate(model: PromptBuildContext["model"]): string;
+    preview(context: PromptBuildContext, middleware?: MiddlewareRunner): Promise<PromptSectionPreview[]>;
+    private getEnvironment;
+    private getInstructions;
+}
+declare function createPromptBuilder(config?: PromptConfig): PromptBuilder;
+
+export { PromptBuilder as P, createPromptBuilder as c };

package/dist/capabilities/index.d.ts

@@ -0,0 +1,97 @@
+import { C as CapabilitySource, S as SourcePriority, b as SourceResult, P as ProviderCompatibility, R as ResolverOptions, M as ModelEntry, c as ModelCapabilities } from '../resolver-DOfZ-xuk.js';
+export { D as DEFAULT_RESOLVER_OPTIONS, I as InputModality, d as ModelCapabilityResolver, N as NetworkStatus, O as OutputModality, f as ResolutionResult, g as configureResolver, e as extractModelId, a as extractProvider, h as getDefaultResolver } from '../resolver-DOfZ-xuk.js';
+export { g as getModelId, a as getProviderId } from '../identifiers-BLUxFqV_.js';
+export { g as getNetworkStatus } from '../network-D76DS5ot.js';
+import 'ai';
+
+/**
+ * Pattern-Based Capability Detection for @cuylabs/agent-core
+ *
+ * Static pattern matching for model capabilities when no external data is available.
+ * This is the fallback layer - always works offline.
+ */
+
+/**
+ * Infer provider from model ID
+ */
+declare function inferProvider(modelId: string): string | undefined;
+/**
+ * Pattern-based capability source
+ * Always available, uses heuristics to detect capabilities
+ */
+declare class PatternCapabilitySource implements CapabilitySource {
+    readonly priority = SourcePriority.PatternMatch;
+    readonly name = "Pattern Matching";
+    lookup(modelId: string, providerHint?: string): Promise<SourceResult>;
+    isAvailable(): Promise<boolean>;
+}
+/**
+ * Quick check if a model ID likely supports reasoning
+ */
+declare function likelySupportsReasoning(modelId: string): boolean;
+/**
+ * Get provider compatibility for a model
+ */
+declare function getProviderCompatibility(modelId: string, provider?: string): ProviderCompatibility | undefined;
+
+type CapabilityOverrides = ResolverOptions["modelOverrides"];
+type OverrideLookup = {
+    override?: Partial<ModelCapabilities>;
+    matchedKey?: string;
+};
+declare function findCapabilityOverride(overrides: CapabilityOverrides, modelId: string, provider?: string): OverrideLookup;
+declare function applyCapabilityOverride(entry: ModelEntry, override?: Partial<ModelCapabilities>): ModelEntry;
+
+declare class CapabilityCache {
+    private adapter;
+    private memoryCache;
+    private ttlMs;
+    private loaded;
+    constructor(options?: Partial<ResolverOptions>);
+    private load;
+    get(modelId: string, provider?: string): Promise<ModelEntry | undefined>;
+    set(entry: ModelEntry): Promise<void>;
+    setMany(entries: ModelEntry[]): Promise<void>;
+    persist(): Promise<void>;
+    clear(): Promise<void>;
+    stats(): {
+        size: number;
+        loaded: boolean;
+    };
+    getAll(): Promise<ModelEntry[]>;
+    getAllByProvider(): Promise<Record<string, ModelEntry[]>>;
+}
+declare class CacheCapabilitySource implements CapabilitySource {
+    private cache;
+    readonly priority = SourcePriority.LocalCache;
+    readonly name = "Local Cache";
+    constructor(cache: CapabilityCache);
+    lookup(modelId: string, provider?: string): Promise<SourceResult>;
+    isAvailable(): Promise<boolean>;
+}
+
+declare class RemoteCapabilityFetcher {
+    private apiUrl;
+    private timeoutMs;
+    private cache;
+    private lastFetchTime;
+    private minFetchInterval;
+    constructor(cache: CapabilityCache, options?: Partial<ResolverOptions>);
+    fetchAll(): Promise<ModelEntry[]>;
+    ping(): Promise<boolean>;
+}
+
+declare class RemoteCapabilitySource implements CapabilitySource {
+    readonly priority = SourcePriority.RemoteAPI;
+    readonly name = "Remote API (models.dev)";
+    private fetcher;
+    private cache;
+    private fetchPromise;
+    private enabled;
+    constructor(cache: CapabilityCache, options?: Partial<ResolverOptions>);
+    lookup(modelId: string, provider?: string): Promise<SourceResult>;
+    isAvailable(): Promise<boolean>;
+    refresh(): Promise<void>;
+}
+
+export { CacheCapabilitySource, CapabilityCache, type CapabilityOverrides, CapabilitySource, ModelCapabilities, ModelEntry, PatternCapabilitySource, ProviderCompatibility, RemoteCapabilityFetcher, RemoteCapabilitySource, ResolverOptions, SourcePriority, SourceResult, applyCapabilityOverride, findCapabilityOverride, getProviderCompatibility, inferProvider, likelySupportsReasoning };

package/dist/capabilities/index.js

@@ -0,0 +1,46 @@
+import {
+  CacheCapabilitySource,
+  CapabilityCache,
+  DEFAULT_RESOLVER_OPTIONS,
+  ModelCapabilityResolver,
+  PatternCapabilitySource,
+  RemoteCapabilityFetcher,
+  RemoteCapabilitySource,
+  SourcePriority,
+  applyCapabilityOverride,
+  configureResolver,
+  extractModelId,
+  extractProvider,
+  findCapabilityOverride,
+  getDefaultResolver,
+  getNetworkStatus,
+  getProviderCompatibility,
+  inferProvider,
+  likelySupportsReasoning
+} from "../chunk-QWFMX226.js";
+import {
+  getModelId,
+  getProviderId
+} from "../chunk-DWYX7ASF.js";
+export {
+  CacheCapabilitySource,
+  CapabilityCache,
+  DEFAULT_RESOLVER_OPTIONS,
+  ModelCapabilityResolver,
+  PatternCapabilitySource,
+  RemoteCapabilityFetcher,
+  RemoteCapabilitySource,
+  SourcePriority,
+  applyCapabilityOverride,
+  configureResolver,
+  extractModelId,
+  extractProvider,
+  findCapabilityOverride,
+  getDefaultResolver,
+  getModelId,
+  getNetworkStatus,
+  getProviderCompatibility,
+  getProviderId,
+  inferProvider,
+  likelySupportsReasoning
+};