@cuylabs/agent-code 0.1.5 → 0.5.0

package/README.md

@@ -4,6 +4,18 @@ An embeddable AI coding agent library built on top of the [Vercel AI SDK](https:
 
 Designed to be embedded into larger applications, using modern Vercel AI SDK patterns for streaming, tool calling, and multi-provider support.
 
+## Package Boundary
+
+Use `@cuylabs/agent-code` when you want ready-made coding tools and coding-agent defaults.
+
+Use `@cuylabs/agent-core` directly when you need lower-level framework surfaces such as:
+- runtime helpers
+- middleware primitives
+- prompt construction
+- skills and sub-agent composition
+
+`agent-code` re-exports `agent-core` for convenience, but its main responsibility is the coding-tool layer.
+
 ## Features
 
 - 🔌 **Embeddable** - Drop into any Node.js/TypeScript application
@@ -38,7 +50,7 @@ const agent = createAgent({
 // Non-streaming usage
 const { response, toolCalls } = await agent.send(
   "session-1",
-  "List all TypeScript files in the src directory"
+  "List all TypeScript files in the src directory",
 );
 console.log(response);
 
@@ -63,14 +75,14 @@ for await (const event of agent.chat("session-1", "Fix the bug in utils.ts")) {
 
 ## Built-in Tools
 
-| Tool | Description |
-|------|-------------|
-| `bash` | Execute shell commands |
-| `read` | Read file contents with line numbers |
-| `edit` | Edit files by replacing text |
-| `write` | Create or overwrite files |
-| `grep` | Search file contents with regex |
-| `glob` | Find files by glob pattern |
+| Tool    | Description                          |
+| ------- | ------------------------------------ |
+| `bash`  | Execute shell commands               |
+| `read`  | Read file contents with line numbers |
+| `edit`  | Edit files by replacing text         |
+| `write` | Create or overwrite files            |
+| `grep`  | Search file contents with regex      |
+| `glob`  | Find files by glob pattern           |
 
 ## Custom Tools
 
@@ -106,13 +118,13 @@ agent.addTool(myTool);
 ```typescript
 // OpenAI (recommended)
 import { openai } from "@ai-sdk/openai";
-const agent = createAgent({ 
+const agent = createAgent({
   model: openai("gpt-4o"),
   cwd: process.cwd(),
 });
 
 // OpenAI with reasoning
-const reasoningAgent = createAgent({ 
+const reasoningAgent = createAgent({
   model: openai("o3-mini"),
   cwd: process.cwd(),
   reasoningLevel: "high",
@@ -120,14 +132,14 @@ const reasoningAgent = createAgent({
 
 // Anthropic
 import { anthropic } from "@ai-sdk/anthropic";
-const agent = createAgent({ 
+const agent = createAgent({
   model: anthropic("claude-sonnet-4-20250514"),
   cwd: process.cwd(),
 });
 
 // Google
 import { google } from "@ai-sdk/google";
-const agent = createAgent({ 
+const agent = createAgent({
   model: google("gemini-2.0-flash"),
   cwd: process.cwd(),
 });
@@ -136,34 +148,40 @@ const agent = createAgent({
 ## Configuration
 
 ```typescript
-import { createAgent, defaultCodingTools, readTool, grepTool, globTool } from "@cuylabs/agent-code";
+import {
+  createAgent,
+  defaultCodingTools,
+  readTool,
+  grepTool,
+  globTool,
+} from "@cuylabs/agent-code";
 import { openai } from "@ai-sdk/openai";
 
 const agent = createAgent({
   // Required: Vercel AI SDK model instance
   model: openai("gpt-4o"),
-  
+
   // Working directory for file operations (default: process.cwd())
   cwd: "/path/to/project",
-  
+
   // System prompt (has sensible defaults for coding)
   systemPrompt: "You are a helpful coding assistant...",
-  
+
   // Temperature (0-1, default varies by provider)
   temperature: 0.7,
-  
+
   // Max output tokens (default: 32000)
   maxOutputTokens: 16000,
-  
+
   // Max steps for tool calling loops (default: 50)
   maxSteps: 25,
-  
+
   // Reasoning level for reasoning models (default: "off")
   reasoningLevel: "high", // "off", "low", "medium", "high"
-  
+
   // Tools to enable (defaults to empty, use defaultCodingTools for all)
   tools: defaultCodingTools,
-  
+
   // Or use a subset for read-only operations
   // tools: [readTool, grepTool, globTool],
 });
@@ -198,21 +216,31 @@ type AgentEvent =
   | { type: "text-start" }
   | { type: "text-delta"; text: string }
   | { type: "text-end" }
-  
+
   // Reasoning (for o3-mini, etc.)
   | { type: "reasoning-start"; id: string }
   | { type: "reasoning-delta"; id: string; text: string }
   | { type: "reasoning-end"; id: string }
-  
+
   // Tool execution
   | { type: "tool-start"; toolName: string; toolCallId: string; input: unknown }
-  | { type: "tool-result"; toolName: string; toolCallId: string; result: unknown }
+  | {
+      type: "tool-result";
+      toolName: string;
+      toolCallId: string;
+      result: unknown;
+    }
   | { type: "tool-error"; toolName: string; toolCallId: string; error: string }
-  
+
   // Progress
   | { type: "step-start"; step: number; maxSteps: number }
-  | { type: "step-finish"; step: number; usage?: TokenUsage; finishReason?: string }
-  
+  | {
+      type: "step-finish";
+      step: number;
+      usage?: TokenUsage;
+      finishReason?: string;
+    }
+
   // Completion
   | { type: "error"; error: Error }
   | { type: "complete"; usage?: TokenUsage };
@@ -222,12 +250,12 @@ type AgentEvent =
 
 See the [examples/](./examples/) folder for working examples:
 
-| # | File | What it shows |
-|---|------|---------------|
-| 01 | `01-basic.ts` | Basic streaming chat with coding tools |
-| 02 | `02-reasoning.ts` | Using reasoning models (o4-mini) |
-| 03 | `03-read-only.ts` | Read-only agent (no bash/edit/write) |
-| 04 | `04-custom-tools.ts` | Adding your own tools |
+| #   | File                 | What it shows                          |
+| --- | -------------------- | -------------------------------------- |
+| 01  | `01-basic.ts`        | Basic streaming chat with coding tools |
+| 02  | `02-reasoning.ts`    | Using reasoning models (o4-mini)       |
+| 03  | `03-read-only.ts`    | Read-only agent (no bash/edit/write)   |
+| 04  | `04-custom-tools.ts` | Adding your own tools                  |
 
 ```bash
 cd packages/agent-code/examples
@@ -237,11 +265,11 @@ cp .env.example .env
 npx tsx examples/01-basic.ts
 ```
 
-## Architecture
+## Layering
 
 This library is built on:
 
-- **@cuylabs/agent-core** - Core agent infrastructure (sessions, streaming, tool execution)
+- **@cuylabs/agent-core** - Core agent infrastructure (sessions, execution, tool orchestration)
 - **Vercel AI SDK** - LLM interaction and multi-provider support
 - **Zod** - Parameter validation for tools
 

package/dist/{chunk-IOXLKDEB.js → chunk-U6W6NJNW.js}

@@ -5,8 +5,12 @@ var DEFAULT_TIMEOUT = 2 * 60 * 1e3;
 var bashParameters = z.object({
   command: z.string().describe("The shell command to execute"),
   timeout: z.number().optional().describe("Timeout in milliseconds (default: 120000)"),
-  workdir: z.string().optional().describe("Working directory to run the command in. Defaults to current working directory."),
-  description: z.string().describe("Clear, concise description of what this command does in 5-10 words")
+  workdir: z.string().optional().describe(
+    "Working directory to run the command in. Defaults to current working directory."
+  ),
+  description: z.string().describe(
+    "Clear, concise description of what this command does in 5-10 words"
+  )
 });
 async function executeBash(params, host, cwd, abort) {
   const workdir = params.workdir || cwd;
@@ -35,6 +39,11 @@ IMPORTANT:
 - Output is automatically truncated if too long
 - For pager commands, output is piped through 'cat' automatically`,
   parameters: bashParameters,
+  replayPolicy: {
+    mode: "manual",
+    sideEffectLevel: "external",
+    reason: "Arbitrary shell execution may affect processes, services, or systems outside the current turn."
+  },
   async execute(params, ctx) {
     const host = ctx.host;
     const result = await executeBash(params, host, ctx.cwd, ctx.abort);
@@ -141,7 +150,9 @@ async function isBinaryFile(filepath, host) {
 var readParameters = z2.object({
   filePath: z2.string().describe("The path to the file to read"),
   offset: z2.number().optional().describe("The line number to start reading from (0-based)"),
-  limit: z2.number().optional().describe(`The number of lines to read (defaults to ${DEFAULT_READ_LIMIT})`)
+  limit: z2.number().optional().describe(
+    `The number of lines to read (defaults to ${DEFAULT_READ_LIMIT})`
+  )
 });
 var readTool = Tool2.define("read", {
   description: `Read the contents of a file.
@@ -153,6 +164,10 @@ IMPORTANT:
 - Binary files cannot be read
 - Images and PDFs are returned as attachments`,
   parameters: readParameters,
+  replayPolicy: {
+    sideEffectLevel: "none",
+    reason: "Read-only file inspection is safe to replay."
+  },
   async execute(params, ctx) {
     const host = ctx.host;
     let filepath = params.filePath;
@@ -338,7 +353,9 @@ function findTextFuzzy(content, searchText) {
 }
 var editParameters = z3.object({
   filePath: z3.string().describe("The absolute path to the file to modify"),
-  oldString: z3.string().describe("The text to replace (must match exactly or with minor whitespace differences)"),
+  oldString: z3.string().describe(
+    "The text to replace (must match exactly or with minor whitespace differences)"
+  ),
   newString: z3.string().describe("The text to replace it with (must be different from oldString)"),
   replaceAll: z3.boolean().optional().describe("Replace all occurrences of oldString (default: false)")
 });
@@ -352,6 +369,11 @@ IMPORTANT:
 - Use replaceAll: true to replace all occurrences
 - For creating new files, use the write tool instead`,
   parameters: editParameters,
+  replayPolicy: {
+    mode: "manual",
+    sideEffectLevel: "local",
+    reason: "Text replacement mutates local files and needs explicit replay control."
+  },
   // Enable automatic baseline capture for turn tracking
   fileOps: {
     pathArgs: ["filePath"],
@@ -445,6 +467,11 @@ IMPORTANT:
 - Parent directories are created automatically
 - Existing content is completely replaced`,
   parameters: writeParameters,
+  replayPolicy: {
+    mode: "manual",
+    sideEffectLevel: "local",
+    reason: "Replaying a file write can overwrite state unexpectedly."
+  },
   // Enable automatic baseline capture for turn tracking
   fileOps: {
     pathArgs: ["filePath"],
@@ -504,11 +531,18 @@ function sq(s) {
 }
 var grepParameters = z5.object({
   pattern: z5.string().describe("The regex pattern to search for in file contents"),
-  path: z5.string().optional().describe("The directory to search in. Defaults to current working directory."),
-  include: z5.string().optional().describe('File pattern to include in the search (e.g. "*.js", "*.{ts,tsx}")')
+  path: z5.string().optional().describe(
+    "The directory to search in. Defaults to current working directory."
+  ),
+  include: z5.string().optional().describe(
+    'File pattern to include in the search (e.g. "*.js", "*.{ts,tsx}")'
+  )
 });
 async function executeGrep(params, host, cwd, abort) {
   const searchPath = params.path ? path4.isAbsolute(params.path) ? params.path : path4.resolve(cwd, params.path) : cwd;
+  if (!await host.exists(searchPath)) {
+    return { matches: [], truncated: false };
+  }
   const parts = [
     "rg",
     "-nH",
@@ -566,6 +600,10 @@ IMPORTANT:
 - Results are sorted by modification time (newest first)
 - Maximum ${MAX_RESULTS} results returned`,
   parameters: grepParameters,
+  replayPolicy: {
+    sideEffectLevel: "none",
+    reason: "Content search is read-only and safe to repeat."
+  },
   async execute(params, ctx) {
     if (!params.pattern) {
       throw new Error("pattern is required");
@@ -607,10 +645,10 @@ async function findFiles(pattern, cwd, host, abort) {
   const files = [];
   let truncated = false;
   try {
-    const result = await host.exec(
-      `rg --files --glob ${sq2(pattern)}`,
-      { cwd, signal: abort }
-    );
+    const result = await host.exec(`rg --files --glob ${sq2(pattern)}`, {
+      cwd,
+      signal: abort
+    });
     if (result.exitCode === 0 || result.exitCode === 1) {
       const found = result.stdout.trim().split(/\r?\n/).filter(Boolean);
       for (const file of found) {
@@ -655,8 +693,12 @@ async function findFiles(pattern, cwd, host, abort) {
   return { files, truncated };
 }
 var globParameters = z6.object({
-  pattern: z6.string().describe('The glob pattern to match files (e.g. "**/*.ts", "src/**/*.js")'),
-  path: z6.string().optional().describe("The directory to search in. Defaults to current working directory.")
+  pattern: z6.string().describe(
+    'The glob pattern to match files (e.g. "**/*.ts", "src/**/*.js")'
+  ),
+  path: z6.string().optional().describe(
+    "The directory to search in. Defaults to current working directory."
+  )
 });
 var globTool = Tool6.define("glob", {
   description: `Find files matching a glob pattern.
@@ -667,10 +709,19 @@ IMPORTANT:
 - Results are sorted by modification time (newest first)
 - Maximum ${MAX_RESULTS2} results returned`,
   parameters: globParameters,
+  replayPolicy: {
+    sideEffectLevel: "none",
+    reason: "Filesystem discovery does not mutate state."
+  },
   async execute(params, ctx) {
     const host = ctx.host;
     const searchPath = params.path ? path5.isAbsolute(params.path) ? params.path : path5.resolve(ctx.cwd, params.path) : ctx.cwd;
-    const { files, truncated } = await findFiles(params.pattern, searchPath, host, ctx.abort);
+    const { files, truncated } = await findFiles(
+      params.pattern,
+      searchPath,
+      host,
+      ctx.abort
+    );
     if (files.length === 0) {
       return {
         title: params.pattern,

package/dist/index.js

@@ -18,7 +18,7 @@ import {
   toolset,
   writeParameters,
   writeTool
-} from "./chunk-IOXLKDEB.js";
+} from "./chunk-U6W6NJNW.js";
 
 // src/index.ts
 export * from "@cuylabs/agent-core";

package/dist/tools/index.d.ts

@@ -3,7 +3,6 @@ import { z } from 'zod';
 
 /**
  * Bash tool - Execute shell commands
- * Based on OpenCode's tool/bash.ts patterns
  */
 
 declare const bashParameters: z.ZodObject<{
@@ -12,13 +11,13 @@ declare const bashParameters: z.ZodObject<{
     workdir: z.ZodOptional<z.ZodString>;
     description: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    command: string;
     description: string;
+    command: string;
     timeout?: number | undefined;
     workdir?: string | undefined;
 }, {
-    command: string;
     description: string;
+    command: string;
     timeout?: number | undefined;
     workdir?: string | undefined;
 }>;
@@ -36,13 +35,13 @@ declare const bashTool: Tool.Info<z.ZodObject<{
     workdir: z.ZodOptional<z.ZodString>;
     description: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    command: string;
     description: string;
+    command: string;
     timeout?: number | undefined;
     workdir?: string | undefined;
 }, {
-    command: string;
     description: string;
+    command: string;
     timeout?: number | undefined;
     workdir?: string | undefined;
 }>, {
@@ -54,7 +53,6 @@ declare const bashTool: Tool.Info<z.ZodObject<{
 
 /**
  * Read tool - Read file contents
- * Based on OpenCode's tool/read.ts patterns
  */
 
 declare const readParameters: z.ZodObject<{
@@ -63,12 +61,12 @@ declare const readParameters: z.ZodObject<{
     limit: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     filePath: string;
-    offset?: number | undefined;
     limit?: number | undefined;
+    offset?: number | undefined;
 }, {
     filePath: string;
-    offset?: number | undefined;
     limit?: number | undefined;
+    offset?: number | undefined;
 }>;
 type ReadParams = z.infer<typeof readParameters>;
 /**
@@ -80,12 +78,12 @@ declare const readTool: Tool.Info<z.ZodObject<{
     limit: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     filePath: string;
-    offset?: number | undefined;
     limit?: number | undefined;
+    offset?: number | undefined;
 }, {
     filePath: string;
-    offset?: number | undefined;
     limit?: number | undefined;
+    offset?: number | undefined;
 }>, {
     totalLines: number;
     linesRead: number;
@@ -96,7 +94,6 @@ declare const readTool: Tool.Info<z.ZodObject<{
 
 /**
  * Edit tool - Edit files by replacing text
- * Based on OpenCode's tool/edit.ts patterns
  */
 
 declare const editParameters: z.ZodObject<{
@@ -144,18 +141,17 @@ declare const editTool: Tool.Info<z.ZodObject<{
 
 /**
  * Write tool - Create or overwrite files
- * Based on OpenCode's tool/write.ts patterns
  */
 
 declare const writeParameters: z.ZodObject<{
     filePath: z.ZodString;
     content: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    filePath: string;
     content: string;
-}, {
     filePath: string;
+}, {
     content: string;
+    filePath: string;
 }>;
 type WriteParams = z.infer<typeof writeParameters>;
 /**
@@ -165,11 +161,11 @@ declare const writeTool: Tool.Info<z.ZodObject<{
     filePath: z.ZodString;
     content: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    filePath: string;
     content: string;
-}, {
     filePath: string;
+}, {
     content: string;
+    filePath: string;
 }>, {
     filepath: string;
     created: boolean;
@@ -179,7 +175,6 @@ declare const writeTool: Tool.Info<z.ZodObject<{
 
 /**
  * Grep tool - Search file contents
- * Based on OpenCode's tool/grep.ts patterns
  */
 
 declare const grepParameters: z.ZodObject<{
@@ -229,7 +224,6 @@ declare const grepTool: Tool.Info<z.ZodObject<{
 
 /**
  * Glob tool - Find files by pattern
- * Based on OpenCode's tool/glob.ts patterns
  */
 
 declare const globParameters: z.ZodObject<{

package/dist/tools/index.js

@@ -18,7 +18,7 @@ import {
   toolset,
   writeParameters,
   writeTool
-} from "../chunk-IOXLKDEB.js";
+} from "../chunk-U6W6NJNW.js";
 export {
   ToolsetBuilder,
   bashParameters,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cuylabs/agent-code",
-  "version": "0.1.5",
+  "version": "0.5.0",
   "description": "Embeddable AI coding agent built on @cuylabs/agent-core",
   "type": "module",
   "main": "./dist/index.js",
@@ -24,7 +24,7 @@
   "dependencies": {
     "ai": "^6.0.67",
     "zod": "^3.24.0",
-    "@cuylabs/agent-core": "^0.3.0"
+    "@cuylabs/agent-core": "^0.5.0"
   },
   "peerDependencies": {
     "@ai-sdk/anthropic": "^3.0.0",
@@ -76,6 +76,7 @@
     "build": "tsup src/index.ts src/tools/index.ts --format esm --dts --clean",
     "dev": "tsup src/index.ts src/tools/index.ts --format esm --dts --watch",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run"
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
 }