@codeany/open-agent-sdk 0.2.1 → 0.2.2

package/.env.example

@@ -0,0 +1,8 @@
+# Required: your LLM API key
+CODEANY_API_KEY=sk-or-...
+
+# Optional: override model
+# CODEANY_MODEL=anthropic/claude-sonnet-4
+
+# Optional: custom API endpoint (e.g. third-party proxy)
+# CODEANY_BASE_URL=https://openrouter.ai/api

package/examples/01-simple-query.ts

@@ -0,0 +1,43 @@
+/**
+ * Example 1: Simple Query with Streaming
+ *
+ * Demonstrates the basic createAgent() + query() flow with
+ * real-time event streaming.
+ *
+ * Run: npx tsx examples/01-simple-query.ts
+ */
+import { createAgent } from '../src/index.js'
+
+async function main() {
+  console.log('--- Example 1: Simple Query ---\n')
+
+  const agent = createAgent({
+    model: process.env.CODEANY_MODEL || 'claude-sonnet-4-6',
+    maxTurns: 10,
+  })
+
+  for await (const event of agent.query(
+    'Read package.json and tell me the project name and version in one sentence.',
+  )) {
+    const msg = event as any
+
+    if (msg.type === 'assistant') {
+      // Print tool calls
+      for (const block of msg.message?.content || []) {
+        if (block.type === 'tool_use') {
+          console.log(`[Tool] ${block.name}(${JSON.stringify(block.input).slice(0, 80)})`)
+        }
+        if (block.type === 'text') {
+          console.log(`\nAssistant: ${block.text}`)
+        }
+      }
+    }
+
+    if (msg.type === 'result') {
+      console.log(`\n--- Result: ${msg.subtype} ---`)
+      console.log(`Tokens: ${msg.usage?.input_tokens} in / ${msg.usage?.output_tokens} out`)
+    }
+  }
+}
+
+main().catch(console.error)

package/examples/02-multi-tool.ts

@@ -0,0 +1,44 @@
+/**
+ * Example 2: Multi-Tool Orchestration
+ *
+ * The agent autonomously uses Glob, Bash, and Read tools to
+ * accomplish a multi-step task.
+ *
+ * Run: npx tsx examples/02-multi-tool.ts
+ */
+import { createAgent } from '../src/index.js'
+
+async function main() {
+  console.log('--- Example 2: Multi-Tool Orchestration ---\n')
+
+  const agent = createAgent({
+    model: process.env.CODEANY_MODEL || 'claude-sonnet-4-6',
+    maxTurns: 15,
+  })
+
+  for await (const event of agent.query(
+    'Do these steps: ' +
+    '1) Use Glob to find all .ts files in src/ (pattern "src/*.ts"). ' +
+    '2) Use Bash to count lines in src/agent.ts with `wc -l`. ' +
+    '3) Give a brief summary.',
+  )) {
+    const msg = event as any
+
+    if (msg.type === 'assistant') {
+      for (const block of msg.message?.content || []) {
+        if (block.type === 'tool_use') {
+          console.log(`[${block.name}] ${JSON.stringify(block.input).slice(0, 100)}`)
+        }
+        if (block.type === 'text' && block.text.trim()) {
+          console.log(`\n${block.text}`)
+        }
+      }
+    }
+
+    if (msg.type === 'result') {
+      console.log(`\n--- ${msg.subtype} | ${msg.usage?.input_tokens}/${msg.usage?.output_tokens} tokens ---`)
+    }
+  }
+}
+
+main().catch(console.error)

package/examples/03-multi-turn.ts

@@ -0,0 +1,39 @@
+/**
+ * Example 3: Multi-Turn Conversation
+ *
+ * Demonstrates session persistence across multiple turns.
+ * The agent remembers context from previous interactions.
+ *
+ * Run: npx tsx examples/03-multi-turn.ts
+ */
+import { createAgent } from '../src/index.js'
+
+async function main() {
+  console.log('--- Example 3: Multi-Turn Conversation ---\n')
+
+  const agent = createAgent({
+    model: process.env.CODEANY_MODEL || 'claude-sonnet-4-6',
+    maxTurns: 5,
+  })
+
+  // Turn 1: Create a file
+  console.log('> Turn 1: Create a file')
+  const r1 = await agent.prompt(
+    'Use Bash to run: echo "Hello Open Agent SDK" > /tmp/oas-test.txt. Confirm briefly.',
+  )
+  console.log(`  ${r1.text}\n`)
+
+  // Turn 2: Read back (should remember context)
+  console.log('> Turn 2: Read the file back')
+  const r2 = await agent.prompt('Read the file you just created and tell me its contents.')
+  console.log(`  ${r2.text}\n`)
+
+  // Turn 3: Clean up
+  console.log('> Turn 3: Cleanup')
+  const r3 = await agent.prompt('Delete that file with Bash. Confirm.')
+  console.log(`  ${r3.text}\n`)
+
+  console.log(`Session history: ${agent.getMessages().length} messages`)
+}
+
+main().catch(console.error)

package/examples/04-prompt-api.ts

@@ -0,0 +1,29 @@
+/**
+ * Example 4: Simple Prompt API
+ *
+ * Uses the blocking prompt() method for quick one-shot queries.
+ * No need to iterate over streaming events.
+ *
+ * Run: npx tsx examples/04-prompt-api.ts
+ */
+import { createAgent } from '../src/index.js'
+
+async function main() {
+  console.log('--- Example 4: Simple Prompt API ---\n')
+
+  const agent = createAgent({
+    model: process.env.CODEANY_MODEL || 'claude-sonnet-4-6',
+    maxTurns: 5,
+  })
+
+  const result = await agent.prompt(
+    'Use Bash to run `node --version` and `npm --version`, then tell me the versions.',
+  )
+
+  console.log(`Answer: ${result.text}`)
+  console.log(`Turns: ${result.num_turns}`)
+  console.log(`Tokens: ${result.usage.input_tokens} in / ${result.usage.output_tokens} out`)
+  console.log(`Duration: ${result.duration_ms}ms`)
+}
+
+main().catch(console.error)

package/examples/05-custom-system-prompt.ts

@@ -0,0 +1,26 @@
+/**
+ * Example 5: Custom System Prompt
+ *
+ * Shows how to customize the agent's behavior with a system prompt.
+ *
+ * Run: npx tsx examples/05-custom-system-prompt.ts
+ */
+import { createAgent } from '../src/index.js'
+
+async function main() {
+  console.log('--- Example 5: Custom System Prompt ---\n')
+
+  const agent = createAgent({
+    model: process.env.CODEANY_MODEL || 'claude-sonnet-4-6',
+    maxTurns: 5,
+    systemPrompt:
+      'You are a senior code reviewer. When asked to review code, focus on: ' +
+      '1) Security issues, 2) Performance concerns, 3) Maintainability. ' +
+      'Be concise and use bullet points.',
+  })
+
+  const result = await agent.prompt('Read src/agent.ts and give a brief code review.')
+  console.log(result.text)
+}
+
+main().catch(console.error)

package/examples/06-mcp-server.ts

@@ -0,0 +1,49 @@
+/**
+ * Example 6: MCP Server Integration
+ *
+ * Connects to an MCP (Model Context Protocol) server and uses
+ * its tools through the agent. This example uses the filesystem
+ * MCP server as a demonstration.
+ *
+ * Prerequisites:
+ *   npm install -g @modelcontextprotocol/server-filesystem
+ *
+ * Run: npx tsx examples/06-mcp-server.ts
+ */
+import { createAgent } from '../src/index.js'
+
+async function main() {
+  console.log('--- Example 6: MCP Server Integration ---\n')
+
+  const agent = createAgent({
+    model: process.env.CODEANY_MODEL || 'claude-sonnet-4-6',
+    maxTurns: 10,
+    mcpServers: {
+      filesystem: {
+        command: 'npx',
+        args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
+      },
+    },
+  })
+
+  console.log('Connecting to MCP filesystem server...\n')
+
+  const result = await agent.prompt(
+    'Use the filesystem MCP tools to list files in /tmp. Be brief.',
+  )
+
+  console.log(`Answer: ${result.text}`)
+  console.log(`Turns: ${result.num_turns}`)
+
+  await agent.close()
+}
+
+main().catch(e => {
+  console.error('Error:', e.message)
+  if (e.message.includes('ENOENT') || e.message.includes('not found')) {
+    console.error(
+      '\nMCP server not found. Install it with:\n' +
+      '  npm install -g @modelcontextprotocol/server-filesystem\n',
+    )
+  }
+})

package/examples/07-custom-tools.ts

@@ -0,0 +1,87 @@
+/**
+ * Example 7: Custom Tools
+ *
+ * Shows how to define and use custom tools alongside built-in tools.
+ *
+ * Run: npx tsx examples/07-custom-tools.ts
+ */
+import { createAgent, getAllBaseTools, defineTool } from '../src/index.js'
+
+const weatherTool = defineTool({
+  name: 'GetWeather',
+  description: 'Get current weather for a city. Returns temperature and conditions.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      city: { type: 'string', description: 'City name (e.g., "Tokyo", "London")' },
+    },
+    required: ['city'],
+  },
+  isReadOnly: true,
+  isConcurrencySafe: true,
+  async call(input) {
+    const temps: Record<string, number> = {
+      tokyo: 22, london: 14, beijing: 25, 'new york': 18, paris: 16,
+    }
+    const temp = temps[input.city?.toLowerCase()] ?? 20
+    return `Weather in ${input.city}: ${temp}°C, partly cloudy`
+  },
+})
+
+const calculatorTool = defineTool({
+  name: 'Calculator',
+  description: 'Evaluate a mathematical expression. Use ** for exponentiation.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      expression: { type: 'string', description: 'Math expression (e.g., "42 * 17 + 3", "2 ** 10")' },
+    },
+    required: ['expression'],
+  },
+  isReadOnly: true,
+  isConcurrencySafe: true,
+  async call(input) {
+    try {
+      const result = Function(`'use strict'; return (${input.expression})`)()
+      return `${input.expression} = ${result}`
+    } catch (e: any) {
+      return { data: `Error: ${e.message}`, is_error: true }
+    }
+  },
+})
+
+async function main() {
+  console.log('--- Example 7: Custom Tools ---\n')
+
+  const builtinTools = getAllBaseTools()
+  const allTools = [...builtinTools, weatherTool, calculatorTool]
+
+  const agent = createAgent({
+    model: process.env.CODEANY_MODEL || 'claude-sonnet-4-6',
+    maxTurns: 10,
+    tools: allTools,
+  })
+
+  console.log(`Loaded ${allTools.length} tools (${builtinTools.length} built-in + 2 custom)\n`)
+
+  for await (const event of agent.query(
+    'What is the weather in Tokyo and London? Also calculate 2**10 * 3. Be brief.',
+  )) {
+    const msg = event as any
+    if (msg.type === 'assistant') {
+      for (const block of msg.message?.content || []) {
+        if (block.type === 'tool_use') {
+          console.log(`[${block.name}] ${JSON.stringify(block.input)}`)
+        }
+        if (block.type === 'text' && block.text.trim()) {
+          console.log(`\n${block.text}`)
+        }
+      }
+    }
+    if (msg.type === 'result') {
+      console.log(`\n--- ${msg.subtype} ---`)
+    }
+  }
+}
+
+main().catch(console.error)

package/examples/08-official-api-compat.ts

@@ -0,0 +1,38 @@
+/**
+ * Example 8: Official SDK-Compatible API
+ *
+ * Demonstrates the query() function with the same API pattern
+ * as open-agent-sdk. Drop-in compatible.
+ *
+ * Run: npx tsx examples/08-official-api-compat.ts
+ */
+import { query } from '../src/index.js'
+
+async function main() {
+  console.log('--- Example 8: Official SDK-Compatible API ---\n')
+
+  // Standard SDK query pattern
+  for await (const message of query({
+    prompt: 'What files are in this directory? Be brief.',
+    options: {
+      allowedTools: ['Bash', 'Glob'],
+      permissionMode: 'bypassPermissions',
+    },
+  })) {
+    const msg = message as any
+
+    if (msg.type === 'assistant' && msg.message?.content) {
+      for (const block of msg.message.content) {
+        if ('text' in block && block.text) {
+          console.log(block.text)
+        } else if ('name' in block) {
+          console.log(`Tool: ${block.name}`)
+        }
+      }
+    } else if (msg.type === 'result') {
+      console.log(`\nDone: ${msg.subtype}`)
+    }
+  }
+}
+
+main().catch(console.error)

package/examples/09-subagents.ts

@@ -0,0 +1,48 @@
+/**
+ * Example 9: Subagents
+ *
+ * Define specialized subagents that the main agent can delegate
+ * tasks to. Matches the official SDK's agents option.
+ *
+ * Run: npx tsx examples/09-subagents.ts
+ */
+import { query } from '../src/index.js'
+
+async function main() {
+  console.log('--- Example 9: Subagents ---\n')
+
+  for await (const message of query({
+    prompt: 'Use the code-reviewer agent to review src/agent.ts',
+    options: {
+      allowedTools: ['Read', 'Glob', 'Grep', 'Agent'],
+      agents: {
+        'code-reviewer': {
+          description: 'Expert code reviewer for quality and security reviews.',
+          prompt:
+            'Analyze code quality and suggest improvements. Focus on ' +
+            'security, performance, and maintainability. Be concise.',
+          tools: ['Read', 'Glob', 'Grep'],
+        },
+      },
+    },
+  })) {
+    const msg = message as any
+
+    if (msg.type === 'assistant') {
+      for (const block of msg.message?.content || []) {
+        if ('text' in block && block.text?.trim()) {
+          console.log(block.text)
+        }
+        if ('name' in block) {
+          console.log(`[${block.name}] ${JSON.stringify(block.input || {}).slice(0, 80)}`)
+        }
+      }
+    }
+
+    if (msg.type === 'result') {
+      console.log(`\n--- ${msg.subtype} ---`)
+    }
+  }
+}
+
+main().catch(console.error)

package/examples/10-permissions.ts

@@ -0,0 +1,40 @@
+/**
+ * Example 10: Permissions and Allowed Tools
+ *
+ * Shows how to restrict which tools the agent can use.
+ * Creates a read-only agent that can analyze but not modify code.
+ *
+ * Run: npx tsx examples/10-permissions.ts
+ */
+import { query } from '../src/index.js'
+
+async function main() {
+  console.log('--- Example 10: Read-Only Agent ---\n')
+
+  // Read-only agent: can only use Read, Glob, Grep
+  for await (const message of query({
+    prompt: 'Review the code in src/agent.ts for best practices. Be concise.',
+    options: {
+      allowedTools: ['Read', 'Glob', 'Grep'],
+    },
+  })) {
+    const msg = message as any
+
+    if (msg.type === 'assistant') {
+      for (const block of msg.message?.content || []) {
+        if ('text' in block && block.text?.trim()) {
+          console.log(block.text)
+        }
+        if ('name' in block) {
+          console.log(`[${block.name}]`)
+        }
+      }
+    }
+
+    if (msg.type === 'result') {
+      console.log(`\n--- ${msg.subtype} ---`)
+    }
+  }
+}
+
+main().catch(console.error)

package/examples/11-custom-mcp-tools.ts

@@ -0,0 +1,101 @@
+/**
+ * Example 11: Custom Tools with tool() + createSdkMcpServer()
+ *
+ * Shows the Zod-based tool() helper and in-process MCP server creation.
+ * This is the recommended way to add custom tools.
+ *
+ * Run: npx tsx examples/11-custom-mcp-tools.ts
+ */
+import { z } from 'zod'
+import { query, tool, createSdkMcpServer } from '../src/index.js'
+
+// Define tools using Zod schemas for type-safe input validation
+const getTemperature = tool(
+  'get_temperature',
+  'Get the current temperature at a location',
+  {
+    city: z.string().describe('City name'),
+    unit: z.enum(['celsius', 'fahrenheit']).default('celsius').describe('Temperature unit'),
+  },
+  async ({ city, unit }) => {
+    // Mock weather data
+    const temps: Record<string, number> = {
+      tokyo: 22, london: 14, paris: 16, 'new york': 18, beijing: 25,
+    }
+    const tempC = temps[city.toLowerCase()] ?? 20
+    const temp = unit === 'fahrenheit' ? tempC * 9 / 5 + 32 : tempC
+    const symbol = unit === 'fahrenheit' ? '°F' : '°C'
+
+    return {
+      content: [{ type: 'text' as const, text: `Temperature in ${city}: ${temp}${symbol}` }],
+    }
+  },
+  { annotations: { readOnlyHint: true } },
+)
+
+const convertUnits = tool(
+  'convert_units',
+  'Convert between measurement units',
+  {
+    value: z.number().describe('Value to convert'),
+    from_unit: z.string().describe('Source unit'),
+    to_unit: z.string().describe('Target unit'),
+  },
+  async ({ value, from_unit, to_unit }) => {
+    const conversions: Record<string, Record<string, (v: number) => number>> = {
+      km: { miles: (v) => v * 0.621371, m: (v) => v * 1000 },
+      miles: { km: (v) => v * 1.60934, m: (v) => v * 1609.34 },
+      kg: { lbs: (v) => v * 2.20462, g: (v) => v * 1000 },
+      lbs: { kg: (v) => v * 0.453592, g: (v) => v * 453.592 },
+    }
+
+    const fn = conversions[from_unit]?.[to_unit]
+    if (!fn) {
+      return {
+        content: [{ type: 'text' as const, text: `Cannot convert from ${from_unit} to ${to_unit}` }],
+        isError: true,
+      }
+    }
+
+    const result = fn(value)
+    return {
+      content: [{ type: 'text' as const, text: `${value} ${from_unit} = ${result.toFixed(2)} ${to_unit}` }],
+    }
+  },
+)
+
+// Bundle tools into an in-process MCP server
+const utilityServer = createSdkMcpServer({
+  name: 'utilities',
+  version: '1.0.0',
+  tools: [getTemperature, convertUnits],
+})
+
+async function main() {
+  console.log('--- Example 11: Custom MCP Tools (tool + createSdkMcpServer) ---\n')
+
+  for await (const message of query({
+    prompt: 'What is the temperature in Tokyo and Paris? Also convert 10 km to miles. Be brief.',
+    options: {
+      mcpServers: { utilities: utilityServer as any },
+      allowedTools: ['mcp__utilities__*'],
+      permissionMode: 'bypassPermissions',
+    },
+  })) {
+    const msg = message as any
+
+    if (msg.type === 'assistant' && msg.message?.content) {
+      for (const block of msg.message.content) {
+        if ('text' in block && block.text?.trim()) {
+          console.log(block.text)
+        } else if ('name' in block) {
+          console.log(`[${block.name}] ${JSON.stringify(block.input || {})}`)
+        }
+      }
+    } else if (msg.type === 'result') {
+      console.log(`\nDone: ${msg.subtype} (cost: $${msg.total_cost_usd?.toFixed(4) || '0'})`)
+    }
+  }
+}
+
+main().catch(console.error)

package/examples/12-skills.ts

@@ -0,0 +1,88 @@
+/**
+ * Example 12: Skills
+ *
+ * Shows how to use the skill system: bundled skills, custom skills,
+ * and invoking skills programmatically.
+ *
+ * Run: npx tsx examples/12-skills.ts
+ */
+import {
+  createAgent,
+  registerSkill,
+  getAllSkills,
+  getUserInvocableSkills,
+  getSkill,
+  initBundledSkills,
+} from '../src/index.js'
+import type { SkillContentBlock } from '../src/index.js'
+
+async function main() {
+  console.log('--- Example 12: Skills ---\n')
+
+  // Bundled skills are auto-initialized when creating an Agent,
+  // but you can also init them explicitly:
+  initBundledSkills()
+
+  // List all registered skills
+  const all = getAllSkills()
+  console.log(`Registered skills (${all.length}):`)
+  for (const skill of all) {
+    console.log(`  - ${skill.name}: ${skill.description.slice(0, 80)}...`)
+  }
+
+  // Register a custom skill
+  registerSkill({
+    name: 'explain',
+    description: 'Explain a concept or piece of code in simple terms.',
+    aliases: ['eli5'],
+    userInvocable: true,
+    async getPrompt(args): Promise<SkillContentBlock[]> {
+      return [{
+        type: 'text',
+        text: `Explain the following in simple, clear terms that a beginner could understand. Use analogies where helpful.\n\nTopic: ${args || 'Ask the user what they want explained.'}`,
+      }]
+    },
+  })
+
+  console.log(`\nAfter registering custom skill: ${getAllSkills().length} total`)
+  console.log(`User-invocable: ${getUserInvocableSkills().length}`)
+
+  // Get a specific skill
+  const commitSkill = getSkill('commit')
+  if (commitSkill) {
+    const blocks = await commitSkill.getPrompt('', { cwd: process.cwd() })
+    console.log(`\nCommit skill prompt (first 200 chars):`)
+    console.log(blocks[0]?.type === 'text' ? blocks[0].text.slice(0, 200) + '...' : '(non-text)')
+  }
+
+  // Use skills with an agent - the model can invoke them via the Skill tool
+  console.log('\n--- Using skills with an agent ---\n')
+
+  const agent = createAgent({
+    model: process.env.CODEANY_MODEL || 'claude-sonnet-4-6',
+    maxTurns: 5,
+  })
+
+  for await (const event of agent.query(
+    'Use the "explain" skill to explain what git rebase does.',
+  )) {
+    const msg = event as any
+    if (msg.type === 'assistant') {
+      for (const block of msg.message?.content || []) {
+        if (block.type === 'tool_use') {
+          console.log(`[Tool: ${block.name}] ${JSON.stringify(block.input)}`)
+        }
+        if (block.type === 'text' && block.text.trim()) {
+          console.log(block.text)
+        }
+      }
+    }
+    if (msg.type === 'result') {
+      console.log(`\n--- ${msg.subtype} ---`)
+    }
+  }
+
+  await agent.close()
+}
+
+main().catch(console.error)