@cuylabs/agent-core 0.4.0 → 0.5.0

package/README.md

@@ -1,12 +1,14 @@
 # @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.
+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
-- **LLM Streaming** — Real-time streaming with proper backpressure handling
+- **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
@@ -18,6 +20,7 @@ Embeddable AI agent infrastructure using Vercel AI SDK. Core building blocks for
 - **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
 
 ## Installation
 
@@ -42,6 +45,23 @@ 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";
@@ -62,6 +82,7 @@ const greet = Tool.define("greet", {
 
 // Create agent
 const agent = createAgent({
+  name: "my-assistant",
   model: openai("gpt-4o"),
   tools: [greet],
   systemPrompt: "You are a helpful assistant.",
@@ -91,9 +112,9 @@ for await (const event of agent.chat("session-1", "Hello!")) {
 ### Local Models (Ollama Example)
 
 ```typescript
-import { createAgent, createModelResolver } from "@cuylabs/agent-core";
+import { createAgent, createResolver } from "@cuylabs/agent-core";
 
-const resolveModel = createModelResolver({
+const resolveModel = createResolver({
   engines: {
     ollama: {
       adapter: "openai-compatible",
@@ -145,11 +166,11 @@ const memoryStorage = new MemoryStorage();
 
 // File-based persistent storage
 const fileStorage = new FileStorage({
-  dataDir: "/path/to/data",
+  directory: "/path/to/data",
 });
 
 const sessions = new SessionManager(fileStorage);
-await sessions.createSession({ id: "my-session" });
+await sessions.create({ id: "my-session", cwd: process.cwd() });
 ```
 
 ### Tool Framework
@@ -230,6 +251,35 @@ const agent = createAgent({
 
 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:
@@ -393,9 +443,8 @@ When using `runConcurrent()` to run multiple tasks in parallel, be aware that al
 
 ## 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.
+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.
 
 ## Documentation
 
 See [docs/](docs/) for in-depth guides on each subsystem.
-

package/dist/builder-RcTZuYnO.d.ts

@@ -0,0 +1,34 @@
+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';
+
+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
+};

package/dist/chunk-6TDTQJ4P.js

@@ -0,0 +1,116 @@
+// src/models/resolver.ts
+function parseKey(input) {
+  const [engineId, ...rest] = input.split("/");
+  if (!engineId || rest.length === 0) return null;
+  return { engineId, modelId: rest.join("/") };
+}
+function mergeSettings(base, override) {
+  return {
+    apiKey: override?.apiKey ?? base?.apiKey,
+    baseUrl: override?.baseUrl ?? base?.baseUrl,
+    headers: {
+      ...base?.headers ?? {},
+      ...override?.headers ?? {}
+    },
+    extra: {
+      ...base?.extra ?? {},
+      ...override?.extra ?? {}
+    }
+  };
+}
+function settingsKey(settings, adapter, engineId) {
+  return JSON.stringify({
+    engineId,
+    adapter,
+    apiKey: settings.apiKey ?? "",
+    baseUrl: settings.baseUrl ?? "",
+    headers: settings.headers ?? {},
+    extra: settings.extra ?? {}
+  });
+}
+function buildOptions(settings) {
+  const opts = { ...settings.extra ?? {} };
+  if (settings.apiKey) opts.apiKey = settings.apiKey;
+  if (settings.baseUrl) opts.baseURL = settings.baseUrl;
+  if (settings.headers && Object.keys(settings.headers).length > 0) opts.headers = settings.headers;
+  return opts;
+}
+async function createFactory(adapter, settings) {
+  const asModel = (m) => m;
+  const opts = buildOptions(settings);
+  switch (adapter) {
+    case "openai": {
+      const { createOpenAI } = await import("@ai-sdk/openai").catch(() => {
+        throw new Error(
+          `Provider "@ai-sdk/openai" is required for the "openai" adapter. Install it with: pnpm add @ai-sdk/openai`
+        );
+      });
+      const provider = createOpenAI(opts);
+      return (modelId) => provider.languageModel(modelId);
+    }
+    case "anthropic": {
+      const { createAnthropic } = await import("@ai-sdk/anthropic").catch(() => {
+        throw new Error(
+          `Provider "@ai-sdk/anthropic" is required for the "anthropic" adapter. Install it with: pnpm add @ai-sdk/anthropic`
+        );
+      });
+      const provider = createAnthropic(opts);
+      return (modelId) => provider.languageModel(modelId);
+    }
+    case "google": {
+      const { createGoogleGenerativeAI } = await import("@ai-sdk/google").catch(() => {
+        throw new Error(
+          `Provider "@ai-sdk/google" is required for the "google" adapter. Install it with: pnpm add @ai-sdk/google`
+        );
+      });
+      const provider = createGoogleGenerativeAI(opts);
+      return (modelId) => asModel(provider.languageModel(modelId));
+    }
+    case "openai-compatible": {
+      const { createOpenAICompatible } = await import("@ai-sdk/openai-compatible").catch(() => {
+        throw new Error(
+          `Provider "@ai-sdk/openai-compatible" is required for the "openai-compatible" adapter. Install it with: pnpm add @ai-sdk/openai-compatible`
+        );
+      });
+      const provider = createOpenAICompatible({
+        name: opts.name ?? "custom",
+        baseURL: opts.baseURL ?? "",
+        ...opts.apiKey ? { apiKey: opts.apiKey } : {},
+        ...opts.headers ? { headers: opts.headers } : {}
+      });
+      return (modelId) => provider.languageModel(modelId);
+    }
+    default:
+      throw new Error(`No factory registered for adapter: ${adapter}`);
+  }
+}
+function createResolver(directory) {
+  const factoryCache = /* @__PURE__ */ new Map();
+  return async (key) => {
+    const parsed = parseKey(key);
+    const entry = parsed ? void 0 : directory.entries?.[key];
+    const engineId = parsed?.engineId ?? entry?.engine;
+    const modelId = parsed?.modelId ?? entry?.id;
+    if (!engineId || !modelId) {
+      throw new Error(`Unknown model reference: ${key}`);
+    }
+    const engine = directory.engines[engineId];
+    if (!engine) {
+      throw new Error(`Unknown engine: ${engineId}`);
+    }
+    const settings = mergeSettings(engine.settings, entry?.settings);
+    if (engine.build) {
+      return engine.build(modelId, settings);
+    }
+    const cacheKey = settingsKey(settings, engine.adapter, engineId);
+    const cached = factoryCache.get(cacheKey);
+    if (cached) return cached(modelId);
+    const factory = await createFactory(engine.adapter, settings);
+    factoryCache.set(cacheKey, factory);
+    return factory(modelId);
+  };
+}
+
+export {
+  createResolver
+};