@cuylabs/agent-code 0.1.6 → 0.6.0

package/README.md

@@ -1,18 +1,40 @@
 # @cuylabs/agent-code
 
-An embeddable AI coding agent library built on top of the [Vercel AI SDK](https://sdk.vercel.ai/).
+Coding-agent package built on `@cuylabs/agent-core`.
 
-Designed to be embedded into larger applications, using modern Vercel AI SDK patterns for streaming, tool calling, and multi-provider support.
+It gives you a ready-made coding toolset and a convenience package for starting
+from a coding-focused surface without rebuilding the common file and shell tools
+yourself.
 
-## Features
+## Package Boundary
 
-- 🔌 **Embeddable** - Drop into any Node.js/TypeScript application
-- 🤖 **Multi-Provider** - Works with OpenAI, Anthropic, Google, and more via Vercel AI SDK
-- 🛠️ **Coding Tools** - Built-in tools for file operations, search, and shell commands
-- 📡 **Streaming** - Real-time streaming of responses and tool execution
-- 🔧 **Extensible** - Easy to add custom tools
-- 💾 **Session Management** - Built-in conversation history tracking
-- 🧠 **Reasoning Support** - Works with reasoning models (o3-mini, etc.)
+Use `@cuylabs/agent-code` when you want:
+
+- the built-in coding tools
+- `defaultCodingTools` for a full coding agent
+- easy read-only or no-shell tool subsets
+- a convenience package that re-exports `agent-core`
+
+Use `@cuylabs/agent-core` directly when you need lower-level framework surfaces
+such as:
+
+- middleware and prompt construction
+- runtime helpers
+- skills, presets, and sub-agent composition
+- non-coding toolsets or framework-level customization
+
+Focused tool imports are available from `@cuylabs/agent-code/tools`.
+
+## Included Tools
+
+| Tool | Purpose |
+|------|---------|
+| `read` | Read file contents with line numbers |
+| `write` | Create or overwrite files |
+| `edit` | Surgical text replacement |
+| `grep` | Search file contents with regex |
+| `glob` | Find files by glob pattern |
+| `bash` | Execute shell commands |
 
 ## Installation
 
@@ -28,222 +50,74 @@ pnpm add @cuylabs/agent-code ai @ai-sdk/openai
 import { createAgent, defaultCodingTools } from "@cuylabs/agent-code";
 import { openai } from "@ai-sdk/openai";
 
-// Create an agent with GPT-4o
 const agent = createAgent({
   model: openai("gpt-4o"),
   cwd: process.cwd(),
   tools: defaultCodingTools,
 });
 
-// Non-streaming usage
-const { response, toolCalls } = await agent.send(
+const { response } = await agent.send(
   "session-1",
-  "List all TypeScript files in the src directory"
+  "List the TypeScript files in src and summarize what each one does.",
 );
-console.log(response);
 
-// Streaming usage
-for await (const event of agent.chat("session-1", "Fix the bug in utils.ts")) {
-  switch (event.type) {
-    case "text-delta":
-      process.stdout.write(event.text);
-      break;
-    case "tool-start":
-      console.log(`\n🔧 ${event.toolName}...`);
-      break;
-    case "tool-result":
-      console.log(`✅ ${event.toolName} complete`);
-      break;
-    case "error":
-      console.error(`❌ Error:`, event.error);
-      break;
-  }
-}
+console.log(response);
 ```
 
-## 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 |
-
-## Custom Tools
+## Choosing A Tool Set
 
-Add your own tools using the `Tool.define` helper:
+Use the default set:
 
 ```typescript
-import { createAgent, Tool } from "@cuylabs/agent-code";
-import { openai } from "@ai-sdk/openai";
-import { z } from "zod";
-
-const myTool = Tool.define("my_custom_tool", {
-  description: "Does something custom",
-  parameters: z.object({
-    input: z.string().describe("The input to process"),
-  }),
-  execute: async (params, ctx) => ({
-    title: "Custom Tool",
-    output: `Processed: ${params.input}`,
-    metadata: {},
-  }),
-});
+import { createAgent, defaultCodingTools } from "@cuylabs/agent-code";
 
 const agent = createAgent({
-  model: openai("gpt-4o"),
+  model,
   cwd: process.cwd(),
+  tools: defaultCodingTools,
 });
-
-agent.addTool(myTool);
 ```
 
-## Using Different Providers
+Or build a narrower agent:
 
 ```typescript
-// OpenAI (recommended)
-import { openai } from "@ai-sdk/openai";
-const agent = createAgent({ 
-  model: openai("gpt-4o"),
-  cwd: process.cwd(),
-});
-
-// OpenAI with reasoning
-const reasoningAgent = createAgent({ 
-  model: openai("o3-mini"),
-  cwd: process.cwd(),
-  reasoningLevel: "high",
-});
-
-// Anthropic
-import { anthropic } from "@ai-sdk/anthropic";
-const agent = createAgent({ 
-  model: anthropic("claude-sonnet-4-20250514"),
+import {
+  createAgent,
+  readTool,
+  grepTool,
+  globTool,
+} from "@cuylabs/agent-code";
+
+const readOnlyAgent = createAgent({
+  model,
   cwd: process.cwd(),
-});
-
-// Google
-import { google } from "@ai-sdk/google";
-const agent = createAgent({ 
-  model: google("gemini-2.0-flash"),
-  cwd: process.cwd(),
-});
-```
-
-## Configuration
-
-```typescript
-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],
+  tools: [readTool, grepTool, globTool],
 });
 ```
 
-## Session Management
+If you only want the tool surface:
 
 ```typescript
-// Sessions are managed automatically
-// Just use a unique session ID for each conversation
-
-// List all sessions
-const sessions = await agent.listSessions();
-
-// Delete a session
-await agent.deleteSession("session-id");
-
-// Get current session's messages
-const messages = agent.getMessages();
-
-// Branch from current point (for undo/redo)
-const branchId = await agent.branch("checkpoint before refactor");
+import { defaultCodingTools, readTool } from "@cuylabs/agent-code/tools";
 ```
 
-## Events
+## Relationship To `agent-core`
 
-The streaming `chat()` method yields these events:
+`agent-code` is the coding-tool layer. It does not own the lower-level agent
+framework semantics.
 
-```typescript
-type AgentEvent =
-  // Text streaming
-  | { 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-error"; toolName: string; toolCallId: string; error: string }
-  
-  // Progress
-  | { type: "step-start"; step: number; maxSteps: number }
-  | { type: "step-finish"; step: number; usage?: TokenUsage; finishReason?: string }
-  
-  // Completion
-  | { type: "error"; error: Error }
-  | { type: "complete"; usage?: TokenUsage };
-```
-
-## Examples
-
-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 |
-
-```bash
-cd packages/agent-code/examples
-cp .env.example .env
-# Add your OPENAI_API_KEY
-
-npx tsx examples/01-basic.ts
-```
+- `agent-core` owns sessions, middleware, runtime helpers, prompt construction, and tracing
+- `agent-code` adds a coding-focused toolset and convenience defaults on top
 
-## Architecture
+So if your main need is “give my agent practical coding tools,” use
+`agent-code`. If your main need is “customize the framework internals,” use
+`agent-core`.
 
-This library is built on:
+## Learn More
 
-- **@cuylabs/agent-core** - Core agent infrastructure (sessions, streaming, tool execution)
-- **Vercel AI SDK** - LLM interaction and multi-provider support
-- **Zod** - Parameter validation for tools
+- [examples/README.md](./examples/README.md) for runnable examples
+- [docs/README.md](./docs/README.md) for per-tool guides
+- [docs/read.md](./docs/read.md), [docs/edit.md](./docs/edit.md), and [docs/bash.md](./docs/bash.md) for the tool details most people care about first
 
 ## License
 

package/dist/{chunk-LMWOKL6B.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,8 +531,12 @@ 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;
@@ -569,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");
@@ -610,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) {
@@ -658,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.
@@ -670,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-LMWOKL6B.js";
+} from "./chunk-U6W6NJNW.js";
 
 // src/index.ts
 export * from "@cuylabs/agent-core";

package/dist/tools/index.d.ts

@@ -11,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;
 }>;
@@ -35,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;
 }>, {
@@ -61,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>;
 /**
@@ -78,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;
@@ -147,11 +147,11 @@ 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>;
 /**
@@ -161,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;

package/dist/tools/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cuylabs/agent-code",
-  "version": "0.1.6",
+  "version": "0.6.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.4.0"
+    "@cuylabs/agent-core": "^0.6.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"
   }
 }