@cuylabs/agent-core 0.1.0

package/README.md

@@ -0,0 +1,275 @@
+# @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
+- **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
+
+## Installation
+
+```bash
+npm install @cuylabs/agent-core
+# or
+pnpm add @cuylabs/agent-core
+```
+
+You'll 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:
+
+```bash
+npm install @ai-sdk/openai-compatible
+```
+
+## Quick Start
+
+```typescript
+import { createAgent, Tool } from "@cuylabs/agent-core";
+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}!`,
+  },
+];
+
+// Create agent
+const agent = createAgent({
+  model: openai("gpt-4o"),
+  cwd: process.cwd(),
+  tools,
+});
+
+// Stream responses
+for await (const event of agent.chat("session-1", "Hello!")) {
+  switch (event.type) {
+    case "text-delta":
+      process.stdout.write(event.text);
+      break;
+    case "tool-call":
+      console.log(`Calling tool: ${event.toolName}`);
+      break;
+    case "tool-result":
+      console.log(`Tool result: ${event.result}`);
+      break;
+    case "complete":
+      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 { defineTool, Tool, ToolRegistry } from "@cuylabs/agent-core";
+import { z } from "zod";
+
+const myTool = defineTool({
+  name: "calculate",
+  description: "Perform a calculation",
+  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!
+  },
+});
+
+// Register tools
+const registry = new ToolRegistry();
+registry.register(myTool);
+```
+
+### 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);
+```
+
+### 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"
+  ]),
+});
+
+// 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");
+
+// Clean up
+await agent.close();
+```
+
+## Event Types
+
+The `chat()` method yields these event types:
+
+| Event Type | Description |
+|------------|-------------|
+| `text-delta` | Streaming text chunk |
+| `tool-call` | Tool invocation started |
+| `tool-result` | Tool execution completed |
+| `reasoning` | Model reasoning (if supported) |
+| `message` | Complete assistant message |
+| `complete` | Stream finished with usage stats |
+| `error` | Error occurred |
+
+## 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.
+

package/dist/chunk-6VKLWNRE.js

@@ -0,0 +1,288 @@
+// src/tool/tool.ts
+import { z } from "zod";
+
+// src/tool/truncation.ts
+import * as fs from "fs/promises";
+import * as path from "path";
+import * as os from "os";
+import * as crypto from "crypto";
+var MAX_LINES = 2e3;
+var MAX_BYTES = 1e5;
+var TRUNCATE_DIR = path.join(os.tmpdir(), "cuylabs-agent-outputs");
+var TRUNCATE_GLOB = path.join(TRUNCATE_DIR, "*");
+function truncateOutput(output, options = {}) {
+  const maxLines = options.maxLines ?? MAX_LINES;
+  const maxBytes = options.maxBytes ?? MAX_BYTES;
+  const lines = output.split("\n");
+  const bytes = Buffer.byteLength(output, "utf-8");
+  if (lines.length <= maxLines && bytes <= maxBytes) {
+    return {
+      content: output,
+      truncated: false
+    };
+  }
+  const hash = crypto.createHash("sha256").update(output).digest("hex").slice(0, 16);
+  const outputPath = path.join(TRUNCATE_DIR, `output-${hash}.txt`);
+  fs.mkdir(TRUNCATE_DIR, { recursive: true }).then(() => fs.writeFile(outputPath, output, "utf-8")).catch(() => {
+  });
+  let truncated;
+  if (lines.length > maxLines) {
+    const keepLines = Math.floor(maxLines / 2);
+    const firstPart = lines.slice(0, keepLines);
+    const lastPart = lines.slice(-keepLines);
+    const omitted = lines.length - keepLines * 2;
+    truncated = [
+      ...firstPart,
+      `
+... (${omitted} lines omitted, full output saved to ${outputPath}) ...
+`,
+      ...lastPart
+    ].join("\n");
+  } else {
+    const keepBytes = Math.floor(maxBytes / 2);
+    const start = output.slice(0, keepBytes);
+    const end = output.slice(-keepBytes);
+    const omittedBytes = bytes - keepBytes * 2;
+    truncated = `${start}
+... (${omittedBytes} bytes omitted, full output saved to ${outputPath}) ...
+${end}`;
+  }
+  return {
+    content: truncated,
+    truncated: true,
+    outputPath
+  };
+}
+function formatSize(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+// src/tool/tool.ts
+var Tool;
+((Tool2) => {
+  function define(id, init) {
+    return {
+      id,
+      init: async (initCtx) => {
+        const toolInfo = typeof init === "function" ? await init(initCtx) : init;
+        const originalExecute = toolInfo.execute;
+        toolInfo.execute = async (params, ctx) => {
+          try {
+            toolInfo.parameters.parse(params);
+          } catch (error) {
+            if (error instanceof z.ZodError && toolInfo.formatValidationError) {
+              throw new Error(toolInfo.formatValidationError(error), { cause: error });
+            }
+            throw new Error(
+              `The ${id} tool was called with invalid arguments: ${error}.
+Please rewrite the input so it satisfies the expected schema.`,
+              { cause: error }
+            );
+          }
+          const result = await originalExecute(params, ctx);
+          if (result.metadata.truncated !== void 0) {
+            return result;
+          }
+          const truncated = truncateOutput(result.output);
+          return {
+            ...result,
+            output: truncated.content,
+            metadata: {
+              ...result.metadata,
+              truncated: truncated.truncated,
+              ...truncated.truncated && { outputPath: truncated.outputPath }
+            }
+          };
+        };
+        return toolInfo;
+      }
+    };
+  }
+  Tool2.define = define;
+  function defineSimple(id, config) {
+    return define(id, config);
+  }
+  Tool2.defineSimple = defineSimple;
+})(Tool || (Tool = {}));
+function defineTool(definition) {
+  return Tool.define(definition.id, {
+    description: definition.description,
+    parameters: definition.parameters,
+    execute: async (params, ctx) => {
+      const result = await definition.execute(params, ctx);
+      return {
+        title: result.title,
+        output: result.output,
+        metadata: result.metadata ?? {}
+      };
+    }
+  });
+}
+
+// src/tool/registry.ts
+var ToolRegistry = class {
+  tools = /* @__PURE__ */ new Map();
+  groups = /* @__PURE__ */ new Map();
+  // --------------------------------------------------------------------------
+  // Tool registration
+  // --------------------------------------------------------------------------
+  /**
+   * Register a tool. Throws if a tool with the same ID is already registered.
+   * Use `set()` for upsert semantics.
+   */
+  register(tool) {
+    if (this.tools.has(tool.id)) {
+      throw new Error(`Tool '${tool.id}' is already registered`);
+    }
+    this.tools.set(tool.id, tool);
+  }
+  /** Register multiple tools (throws on duplicates). */
+  registerAll(tools) {
+    for (const tool of tools) {
+      this.register(tool);
+    }
+  }
+  /** Register or replace a tool (upsert). */
+  set(tool) {
+    this.tools.set(tool.id, tool);
+  }
+  /** Unregister a tool by ID. Returns `true` if it existed. */
+  unregister(id) {
+    return this.tools.delete(id);
+  }
+  /** Get a tool by ID. */
+  get(id) {
+    return this.tools.get(id);
+  }
+  /** Check if a tool is registered. */
+  has(id) {
+    return this.tools.has(id);
+  }
+  /** Get all tool IDs. */
+  ids() {
+    return Array.from(this.tools.keys());
+  }
+  /** Get all tools. */
+  all() {
+    return Array.from(this.tools.values());
+  }
+  /** Clear all tools and groups. */
+  clear() {
+    this.tools.clear();
+    this.groups.clear();
+  }
+  /** Number of registered tools. */
+  get size() {
+    return this.tools.size;
+  }
+  // --------------------------------------------------------------------------
+  // Group management
+  // --------------------------------------------------------------------------
+  /**
+   * Register a named group of tool IDs.
+   * The group name can be used in `resolve()` specs.
+   * Tool IDs don't need to be registered yet — resolution is lazy.
+   */
+  registerGroup(name, toolIds) {
+    this.groups.set(name, toolIds);
+  }
+  /** Get tools in a group (only returns registered tools). */
+  getGroup(name) {
+    const ids = this.groups.get(name);
+    if (!ids) return void 0;
+    return ids.map((id) => this.tools.get(id)).filter((t) => t !== void 0);
+  }
+  /** Check if a group is registered. */
+  hasGroup(name) {
+    return this.groups.has(name);
+  }
+  /** List all group names. */
+  listGroups() {
+    return Array.from(this.groups.keys());
+  }
+  // --------------------------------------------------------------------------
+  // Resolution
+  // --------------------------------------------------------------------------
+  /**
+   * Resolve a `ToolSpec` to an array of tools.
+   *
+   * Supports group names, individual tool IDs, comma-separated strings,
+   * exclusions with `-` prefix, booleans, and pass-through arrays.
+   *
+   * @example
+   * ```typescript
+   * registry.resolve("read-only");          // group name
+   * registry.resolve("read,grep,glob");     // comma-separated IDs
+   * registry.resolve("all,-bash");          // all except bash
+   * registry.resolve(["read", "grep"]);     // array of IDs
+   * registry.resolve(true);                 // all registered tools
+   * registry.resolve(false);                // empty array
+   * ```
+   */
+  resolve(spec) {
+    if (spec === true) return this.all();
+    if (spec === false) return [];
+    if (Array.isArray(spec) && spec.length > 0 && typeof spec[0] !== "string") {
+      return spec;
+    }
+    const tokens = Array.isArray(spec) ? spec : spec.split(",").map((s) => s.trim()).filter(Boolean);
+    const includes = [];
+    const excludes = [];
+    for (const token of tokens) {
+      if (token.startsWith("-")) {
+        excludes.push(token.slice(1));
+      } else {
+        includes.push(token);
+      }
+    }
+    let result = /* @__PURE__ */ new Map();
+    if (includes.length === 0 && excludes.length > 0) {
+      for (const [id, tool] of this.tools) {
+        result.set(id, tool);
+      }
+    } else {
+      for (const token of includes) {
+        if (token === "all") {
+          for (const [id, tool] of this.tools) {
+            result.set(id, tool);
+          }
+        } else if (this.groups.has(token)) {
+          const ids = this.groups.get(token);
+          for (const id of ids) {
+            const tool = this.tools.get(id);
+            if (tool) result.set(id, tool);
+          }
+        } else if (this.tools.has(token)) {
+          result.set(token, this.tools.get(token));
+        }
+      }
+    }
+    for (const id of excludes) {
+      if (this.groups.has(id)) {
+        const ids = this.groups.get(id);
+        for (const gid of ids) {
+          result.delete(gid);
+        }
+      } else {
+        result.delete(id);
+      }
+    }
+    return Array.from(result.values());
+  }
+};
+var defaultRegistry = new ToolRegistry();
+
+export {
+  MAX_LINES,
+  MAX_BYTES,
+  TRUNCATE_DIR,
+  TRUNCATE_GLOB,
+  truncateOutput,
+  formatSize,
+  Tool,
+  defineTool,
+  ToolRegistry,
+  defaultRegistry
+};