@cuylabs/agent-code 0.5.0 → 0.6.0

package/README.md

@@ -1,30 +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.
 
 ## Package Boundary
 
-Use `@cuylabs/agent-code` when you want ready-made coding tools and coding-agent defaults.
+Use `@cuylabs/agent-code` when you want:
 
-Use `@cuylabs/agent-core` directly when you need lower-level framework surfaces such as:
+- 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
-- middleware primitives
-- prompt construction
-- skills and sub-agent composition
+- skills, presets, and sub-agent composition
+- non-coding toolsets or framework-level customization
 
-`agent-code` re-exports `agent-core` for convenience, but its main responsibility is the coding-tool layer.
+Focused tool imports are available from `@cuylabs/agent-code/tools`.
 
-## Features
+## Included Tools
 
-- 🔌 **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.)
+| 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
 
@@ -40,238 +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
+## Choosing A Tool Set
 
-| 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
-
-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: {},
-  }),
-});
-
-const agent = createAgent({
-  model: openai("gpt-4o"),
-  cwd: process.cwd(),
-});
-
-agent.addTool(myTool);
-```
-
-## Using Different Providers
-
-```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"),
-  cwd: process.cwd(),
-});
+import { createAgent, defaultCodingTools } from "@cuylabs/agent-code";
 
-// Google
-import { google } from "@ai-sdk/google";
 const agent = createAgent({
-  model: google("gemini-2.0-flash"),
+  model,
   cwd: process.cwd(),
+  tools: defaultCodingTools,
 });
 ```
 
-## Configuration
+Or build a narrower agent:
 
 ```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],
+const readOnlyAgent = createAgent({
+  model,
+  cwd: process.cwd(),
+  tools: [readTool, grepTool, globTool],
 });
 ```
 
-## Session Management
-
-```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");
-```
-
-## Events
-
-The streaming `chat()` method yields these events:
+If you only want the tool surface:
 
 ```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 };
+import { defaultCodingTools, readTool } from "@cuylabs/agent-code/tools";
 ```
 
-## Examples
-
-See the [examples/](./examples/) folder for working examples:
+## Relationship To `agent-core`
 
-| #   | 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                  |
+`agent-code` is the coding-tool layer. It does not own the lower-level agent
+framework semantics.
 
-```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
 
-## Layering
+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, execution, tool orchestration)
-- **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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cuylabs/agent-code",
-  "version": "0.5.0",
+  "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.5.0"
+    "@cuylabs/agent-core": "^0.6.0"
   },
   "peerDependencies": {
     "@ai-sdk/anthropic": "^3.0.0",