@cuylabs/agent-code 0.1.0

package/README.md

@@ -0,0 +1,250 @@
+# @cuylabs/agent-code
+
+An embeddable AI coding agent library built on top of the [Vercel AI SDK](https://sdk.vercel.ai/).
+
+Designed to be embedded into larger applications, using modern Vercel AI SDK patterns for streaming, tool calling, and multi-provider support.
+
+## Features
+
+- 🔌 **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.)
+
+## Installation
+
+```bash
+npm install @cuylabs/agent-code ai @ai-sdk/openai
+# or
+pnpm add @cuylabs/agent-code ai @ai-sdk/openai
+```
+
+## Quick Start
+
+```typescript
+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(
+  "session-1",
+  "List all TypeScript files in the src directory"
+);
+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;
+  }
+}
+```
+
+## 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
+
+Add your own tools using the `Tool.define` helper:
+
+```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(),
+});
+
+// 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],
+});
+```
+
+## 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:
+
+```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
+```
+
+## Architecture
+
+This library is built on:
+
+- **@cuylabs/agent-core** - Core agent infrastructure (sessions, streaming, tool execution)
+- **Vercel AI SDK** - LLM interaction and multi-provider support
+- **Zod** - Parameter validation for tools
+
+## License
+
+Apache-2.0