Initial commit: Open Agent SDK (TypeScript)

Open-source Agent SDK with 30+ built-in tools, MCP integration,
multi-turn sessions, subagents, and streaming support.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

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)

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)

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)

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)

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)

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',
+    )
+  }
+})

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)

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)

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)

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)

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)

examples/web/index.html

@@ -0,0 +1,365 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Open Agent SDK</title>
+<style>
+*{margin:0;padding:0;box-sizing:border-box}
+:root{
+  --bg:#f5f6f8;--surface:#fff;--border:#e5e7eb;
+  --text:#1a1a1a;--text2:#6b7280;--accent:#111;
+  --user-bg:#111;--user-fg:#fff;
+  --tool-bg:#f3f4f6;--tool-border:#e0e1e4;
+  --think-bg:#fffbeb;--think-border:#fde68a;
+  --ok-bg:#ecfdf5;--ok-border:#86efac;--ok-text:#166534;
+  --err-bg:#fef2f2;--err-border:#fca5a5;--err-text:#991b1b;
+  --radius:16px;
+}
+body{font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,'Helvetica Neue',sans-serif;
+  background:var(--bg);color:var(--text);height:100vh;display:flex;flex-direction:column}
+
+/* Header */
+header{display:flex;align-items:center;justify-content:space-between;
+  padding:14px 20px;background:var(--surface);border-bottom:1px solid var(--border)}
+header h1{font-size:16px;font-weight:600}
+header button{width:34px;height:34px;border-radius:50%;border:1px solid var(--border);
+  background:var(--surface);font-size:18px;cursor:pointer;display:flex;align-items:center;justify-content:center}
+header button:hover{background:var(--bg)}
+
+/* Chat */
+#chat{flex:1;overflow-y:auto;padding:24px 16px}
+#chat-inner{max-width:800px;margin:0 auto;display:flex;flex-direction:column;gap:20px}
+
+/* Welcome */
+#welcome{text-align:center;padding:60px 0 30px}
+#welcome h2{font-size:22px;font-weight:600;margin-bottom:22px;color:var(--text)}
+.suggestions{display:grid;grid-template-columns:1fr 1fr;gap:10px;max-width:500px;margin:0 auto}
+.suggestions button{padding:12px 16px;border:1px solid var(--border);border-radius:12px;
+  background:var(--surface);cursor:pointer;text-align:left;font-size:13px;color:var(--text);transition:border-color .15s}
+.suggestions button:hover{border-color:#999}
+.suggestions span{margin-right:6px}
+
+/* Message rows */
+.msg-row{display:flex}
+.msg-row.user{justify-content:flex-end}
+.msg-row.assistant{justify-content:flex-start}
+
+/* Bubbles */
+.bubble-user{background:var(--user-bg);color:var(--user-fg);padding:10px 16px;
+  border-radius:18px 18px 4px 18px;max-width:75%;font-size:14px;line-height:1.55;white-space:pre-wrap}
+.bubble-assistant{max-width:85%;font-size:14.5px;line-height:1.65}
+.bubble-assistant p{margin-bottom:8px}
+.bubble-assistant p:last-child{margin-bottom:0}
+.bubble-assistant strong{font-weight:600}
+.bubble-assistant code{background:#f0f1f3;padding:1px 5px;border-radius:4px;font-size:13px}
+.bubble-assistant pre{background:#1e1e1e;color:#d4d4d4;padding:14px 16px;border-radius:10px;
+  overflow-x:auto;margin:8px 0;font-size:13px;line-height:1.5}
+.bubble-assistant pre code{background:none;padding:0;color:inherit}
+.bubble-assistant ul,.bubble-assistant ol{padding-left:22px;margin:6px 0}
+.bubble-assistant li{margin:3px 0}
+
+/* Tool call card */
+.tool-card{background:var(--tool-bg);border:1px solid var(--tool-border);border-radius:10px;
+  padding:10px 14px;margin:8px 0;font-size:13px}
+.tool-card .tool-hd{display:flex;align-items:center;gap:6px;font-weight:600;margin-bottom:4px}
+.tool-card .tool-icon{font-size:15px}
+.tool-card .tool-input{color:var(--text2);white-space:nowrap;overflow:hidden;text-overflow:ellipsis;max-width:100%}
+.tool-result{margin:4px 0 8px 12px;padding:8px 12px;border-left:3px solid var(--tool-border);
+  font-size:12.5px;color:var(--text2);max-height:200px;overflow-y:auto;white-space:pre-wrap;word-break:break-all}
+
+/* Thinking */
+.think-box{background:var(--think-bg);border:1px solid var(--think-border);border-radius:10px;
+  padding:10px 14px;margin:8px 0;font-size:13px;font-style:italic;color:#92400e}
+
+/* Result banner */
+.result-banner{border-radius:10px;padding:10px 16px;font-size:13px;margin:8px 0;display:flex;align-items:center;gap:8px}
+.result-banner.ok{background:var(--ok-bg);border:1px solid var(--ok-border);color:var(--ok-text)}
+.result-banner.err{background:var(--err-bg);border:1px solid var(--err-border);color:var(--err-text)}
+
+/* Typing indicator */
+.typing{display:flex;align-items:center;gap:4px;padding:8px 0}
+.typing span{width:7px;height:7px;background:#aaa;border-radius:50%;animation:bounce .6s infinite alternate}
+.typing span:nth-child(2){animation-delay:.15s}
+.typing span:nth-child(3){animation-delay:.3s}
+@keyframes bounce{to{transform:translateY(-6px);opacity:.4}}
+
+/* Input area */
+#input-area{padding:12px 16px 16px;background:var(--surface);border-top:1px solid var(--border)}
+#input-wrap{max-width:800px;margin:0 auto;display:flex;align-items:flex-end;gap:10px;
+  border:1px solid var(--border);border-radius:26px;padding:6px 8px 6px 18px;background:var(--surface);
+  transition:border-color .2s}
+#input-wrap:focus-within{border-color:#999}
+#prompt{flex:1;border:none;outline:none;font-size:14px;line-height:1.5;resize:none;
+  min-height:24px;max-height:180px;font-family:inherit;background:transparent}
+#send-btn{width:38px;height:38px;border-radius:50%;border:none;background:var(--accent);
+  color:#fff;font-size:18px;cursor:pointer;flex-shrink:0;display:flex;align-items:center;justify-content:center;
+  transition:opacity .15s}
+#send-btn:disabled{opacity:.35;cursor:default}
+
+@keyframes fadeIn{from{opacity:0;transform:translateY(6px)}to{opacity:1;transform:none}}
+.msg-row,.tool-card,.tool-result,.think-box,.result-banner{animation:fadeIn .2s ease}
+</style>
+</head>
+<body>
+
+<header>
+  <h1>Open Agent SDK</h1>
+  <button onclick="newSession()" title="New session">+</button>
+</header>
+
+<div id="chat">
+  <div id="chat-inner">
+    <div id="welcome">
+      <h2>What can I do for you?</h2>
+      <div class="suggestions">
+        <button onclick="useSuggestion(this)"><span>&#128193;</span>List files in this project</button>
+        <button onclick="useSuggestion(this)"><span>&#128196;</span>Read package.json</button>
+        <button onclick="useSuggestion(this)"><span>&#128202;</span>Count lines of code</button>
+        <button onclick="useSuggestion(this)"><span>&#128187;</span>Show system info</button>
+      </div>
+    </div>
+  </div>
+</div>
+
+<div id="input-area">
+  <div id="input-wrap">
+    <textarea id="prompt" rows="1" placeholder="Assign a task or ask anything" onkeydown="handleKey(event)" oninput="autoResize()"></textarea>
+    <button id="send-btn" onclick="sendMessage()">&#8593;</button>
+  </div>
+</div>
+
+<script>
+const chatInner = document.getElementById('chat-inner');
+const chatEl    = document.getElementById('chat');
+const promptEl  = document.getElementById('prompt');
+const sendBtn   = document.getElementById('send-btn');
+const welcomeEl = document.getElementById('welcome');
+
+let streaming = false;
+
+const TOOL_ICONS = {
+  Bash:'&#128736;',Read:'&#128196;',Write:'&#128221;',Edit:'&#9998;',
+  Glob:'&#128269;',Grep:'&#128270;',WebFetch:'&#127760;',WebSearch:'&#128269;',
+  Agent:'&#129302;',NotebookEdit:'&#128211;',TaskCreate:'&#128203;',
+};
+
+/* ---- helpers ---- */
+function esc(s){return s.replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;')}
+
+function renderMarkdown(raw){
+  let h = esc(raw);
+  // code blocks
+  h = h.replace(/```(\w*)\n([\s\S]*?)```/g, (_,lang,code) =>
+    `<pre><code class="lang-${lang}">${code.trim()}</code></pre>`);
+  // inline code
+  h = h.replace(/`([^`\n]+)`/g, '<code>$1</code>');
+  // bold
+  h = h.replace(/\*\*(.+?)\*\*/g, '<strong>$1</strong>');
+  // unordered lists
+  h = h.replace(/^[\-\*] (.+)$/gm, '<li>$1</li>');
+  h = h.replace(/(<li>.*<\/li>\n?)+/g, m => '<ul>'+m+'</ul>');
+  // ordered lists
+  h = h.replace(/^\d+\. (.+)$/gm, '<li>$1</li>');
+  // paragraphs
+  h = h.replace(/\n{2,}/g, '</p><p>');
+  h = h.replace(/\n/g, '<br>');
+  return '<p>'+h+'</p>';
+}
+
+function scrollToBottom(){
+  requestAnimationFrame(()=>{ chatEl.scrollTop = chatEl.scrollHeight; });
+}
+
+function autoResize(){
+  promptEl.style.height = 'auto';
+  promptEl.style.height = Math.min(promptEl.scrollHeight, 180)+'px';
+}
+
+/* ---- actions ---- */
+function handleKey(e){
+  if(e.key==='Enter' && !e.shiftKey){ e.preventDefault(); sendMessage(); }
+}
+
+function useSuggestion(btn){
+  const text = btn.textContent.replace(/^.\s*/u,'');
+  promptEl.value = text;
+  sendMessage();
+}
+
+async function newSession(){
+  await fetch('/api/new',{method:'POST'});
+  chatInner.innerHTML = '';
+  chatInner.appendChild(welcomeEl);
+  welcomeEl.style.display = '';
+}
+
+async function sendMessage(){
+  const text = promptEl.value.trim();
+  if(!text || streaming) return;
+  streaming = true;
+  sendBtn.disabled = true;
+  promptEl.value = '';
+  autoResize();
+
+  // hide welcome
+  welcomeEl.style.display = 'none';
+
+  // user bubble
+  const uRow = document.createElement('div');
+  uRow.className = 'msg-row user';
+  uRow.innerHTML = `<div class="bubble-user">${esc(text)}</div>`;
+  chatInner.appendChild(uRow);
+  scrollToBottom();
+
+  // typing indicator
+  const typingEl = document.createElement('div');
+  typingEl.className = 'msg-row assistant';
+  typingEl.innerHTML = '<div class="typing"><span></span><span></span><span></span></div>';
+  chatInner.appendChild(typingEl);
+  scrollToBottom();
+
+  // assistant wrapper
+  const aRow = document.createElement('div');
+  aRow.className = 'msg-row assistant';
+  const aBubble = document.createElement('div');
+  aBubble.className = 'bubble-assistant';
+  aRow.appendChild(aBubble);
+
+  let textAcc = '';
+  let textEl = null;
+  let typingRemoved = false;
+
+  function ensureTextEl(){
+    if(!textEl){
+      textEl = document.createElement('div');
+      aBubble.appendChild(textEl);
+    }
+  }
+
+  try{
+    const resp = await fetch('/api/chat',{
+      method:'POST',
+      headers:{'Content-Type':'application/json'},
+      body: JSON.stringify({message:text}),
+    });
+
+    if(!resp.ok){
+      throw new Error(`HTTP ${resp.status}: ${await resp.text()}`);
+    }
+
+    // Two code paths: streaming (ReadableStream) or fallback (text)
+    if(resp.body && typeof resp.body.getReader === 'function'){
+      // --- Streaming path ---
+      const reader = resp.body.getReader();
+      const decoder = new TextDecoder();
+      let buf = '';
+
+      while(true){
+        const {done,value} = await reader.read();
+        if(done) break;
+        buf += decoder.decode(value, {stream:true});
+        processSSEBuffer();
+      }
+      // flush remaining
+      if(buf.trim()) processSSEBuffer();
+
+      function processSSEBuffer(){
+        const lines = buf.split('\n');
+        buf = lines.pop() || '';
+        for(const line of lines) handleSSELine(line);
+      }
+    } else {
+      // --- Fallback: read full text at once (proxy/polyfill environments) ---
+      const fullText = await resp.text();
+      for(const line of fullText.split('\n')) handleSSELine(line);
+    }
+
+    function handleSSELine(line){
+      const trimmed = line.trim();
+      if(!trimmed.startsWith('data: ')) return;
+      let parsed;
+      try{ parsed = JSON.parse(trimmed.slice(6)); } catch{ return; }
+      const {event, data} = parsed;
+      if(!event || !data) return;
+
+      // remove typing on first real event
+      if(!typingRemoved){ typingRemoved = true; typingEl.remove(); chatInner.appendChild(aRow); }
+
+      switch(event){
+        case 'text':
+          textAcc += data.text;
+          ensureTextEl();
+          textEl.innerHTML = renderMarkdown(textAcc);
+          scrollToBottom();
+          break;
+
+        case 'tool_use':{
+          textAcc = ''; textEl = null;
+          const icon = TOOL_ICONS[data.name] || '&#128295;';
+          const inputStr = typeof data.input === 'string' ? data.input : JSON.stringify(data.input);
+          const card = document.createElement('div');
+          card.className = 'tool-card';
+          card.id = 'tool-'+data.id;
+          card.innerHTML = `<div class="tool-hd"><span class="tool-icon">${icon}</span>${esc(data.name)}</div>`
+            + `<div class="tool-input">${esc(inputStr).slice(0,200)}</div>`;
+          aBubble.appendChild(card);
+          scrollToBottom();
+          break;
+        }
+
+        case 'tool_result':{
+          const card = document.getElementById('tool-'+data.tool_use_id);
+          const rd = document.createElement('div');
+          rd.className = 'tool-result';
+          rd.textContent = (data.content||'').slice(0,3000);
+          if(card) card.after(rd); else aBubble.appendChild(rd);
+          scrollToBottom();
+          break;
+        }
+
+        case 'thinking':{
+          textAcc = ''; textEl = null;
+          const tb = document.createElement('div');
+          tb.className = 'think-box';
+          tb.textContent = data.thinking.slice(0,1000);
+          aBubble.appendChild(tb);
+          scrollToBottom();
+          break;
+        }
+
+        case 'result':{
+          const b = document.createElement('div');
+          b.className = 'result-banner ok';
+          b.innerHTML = `&#9989; Done &middot; $${(data.cost||0).toFixed(2)} &middot; ${((data.duration_ms||0)/1000).toFixed(1)}s &middot; ${(data.input_tokens||0)+(data.output_tokens||0)} tokens`;
+          aBubble.appendChild(b);
+          scrollToBottom();
+          break;
+        }
+
+        case 'error':{
+          const b = document.createElement('div');
+          b.className = 'result-banner err';
+          b.innerHTML = `&#10060; Error: ${esc(data.message||'unknown')}`;
+          aBubble.appendChild(b);
+          scrollToBottom();
+          break;
+        }
+      }
+    }
+
+  }catch(err){
+    if(!typingRemoved){ typingEl.remove(); chatInner.appendChild(aRow); }
+    const b = document.createElement('div');
+    b.className = 'result-banner err';
+    b.textContent = 'Network error: '+err.message;
+    aBubble.appendChild(b);
+  }
+
+  streaming = false;
+  sendBtn.disabled = false;
+  promptEl.focus();
+}
+</script>
+</body>
+</html>

examples/web/server.ts

@@ -0,0 +1,157 @@
+/**
+ * Web Chat Server
+ *
+ * A lightweight HTTP server providing:
+ *   GET  /           — serves the chat UI
+ *   POST /api/chat   — SSE stream of agent events
+ *   POST /api/new    — resets the session
+ *
+ * Run: npx tsx examples/web/server.ts
+ */
+
+import { createServer, type IncomingMessage, type ServerResponse } from 'http'
+import { readFile } from 'fs/promises'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+import { createAgent, type Agent } from '../../src/index.js'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const PORT = parseInt(process.env.PORT || '8081')
+
+let agent: Agent | null = null
+
+function getOrCreateAgent(): Agent {
+  if (!agent) {
+    agent = createAgent({
+      model: process.env.CODEANY_MODEL || 'claude-sonnet-4-6',
+      maxTurns: 20,
+    })
+  }
+  return agent
+}
+
+function resetAgent(): void {
+  agent?.close().catch(() => {})
+  agent = null
+}
+
+/** Read the full request body as a string. */
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = []
+    req.on('data', (c: Buffer) => chunks.push(c))
+    req.on('end', () => resolve(Buffer.concat(chunks).toString()))
+    req.on('error', reject)
+  })
+}
+
+/** Handle POST /api/chat — SSE stream */
+async function handleChat(req: IncomingMessage, res: ServerResponse) {
+  const body = JSON.parse(await readBody(req))
+  const prompt = body.message?.trim()
+  if (!prompt) {
+    res.writeHead(400, { 'Content-Type': 'application/json' })
+    res.end(JSON.stringify({ error: 'empty message' }))
+    return
+  }
+
+  // SSE headers
+  res.writeHead(200, {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache',
+    'Connection': 'keep-alive',
+    'X-Accel-Buffering': 'no',
+  })
+
+  const send = (event: string, data: unknown) => {
+    res.write(`data: ${JSON.stringify({ event, data })}\n\n`)
+  }
+
+  const ag = getOrCreateAgent()
+  const startMs = Date.now()
+
+  try {
+    for await (const ev of ag.query(prompt)) {
+      switch (ev.type) {
+        case 'assistant': {
+          for (const block of ev.message.content) {
+            if (block.type === 'text') {
+              send('text', { text: block.text })
+            } else if (block.type === 'tool_use') {
+              send('tool_use', {
+                id: block.id,
+                name: block.name,
+                input: block.input,
+              })
+            } else if ('thinking' in block) {
+              send('thinking', { thinking: (block as any).thinking })
+            }
+          }
+          break
+        }
+        case 'tool_result':
+          send('tool_result', {
+            tool_use_id: ev.result.tool_use_id,
+            content: ev.result.output,
+            is_error: false,
+          })
+          break
+        case 'result':
+          send('result', {
+            num_turns: ev.num_turns ?? 0,
+            input_tokens: ev.usage?.input_tokens ?? 0,
+            output_tokens: ev.usage?.output_tokens ?? 0,
+            cost: ev.total_cost_usd ?? ev.cost ?? 0,
+            duration_ms: Date.now() - startMs,
+          })
+          break
+      }
+    }
+  } catch (err: any) {
+    send('error', { message: err.message })
+  }
+
+  send('done', null)
+  res.end()
+}
+
+/** Handle POST /api/new */
+function handleNewSession(_req: IncomingMessage, res: ServerResponse) {
+  resetAgent()
+  res.writeHead(200, { 'Content-Type': 'application/json' })
+  res.end(JSON.stringify({ ok: true }))
+}
+
+/** Serve the static index.html */
+async function serveIndex(_req: IncomingMessage, res: ServerResponse) {
+  const html = await readFile(join(__dirname, 'index.html'), 'utf-8')
+  res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' })
+  res.end(html)
+}
+
+// --- HTTP Server ---
+
+const server = createServer(async (req, res) => {
+  const url = req.url || '/'
+  const method = req.method || 'GET'
+
+  try {
+    if (url === '/' && method === 'GET') return await serveIndex(req, res)
+    if (url === '/api/chat' && method === 'POST') return await handleChat(req, res)
+    if (url === '/api/new' && method === 'POST') return handleNewSession(req, res)
+
+    res.writeHead(404)
+    res.end('Not Found')
+  } catch (err: any) {
+    console.error(err)
+    if (!res.headersSent) {
+      res.writeHead(500, { 'Content-Type': 'application/json' })
+    }
+    res.end(JSON.stringify({ error: err.message }))
+  }
+})
+
+server.listen(PORT, () => {
+  console.log(`\n  Open Agent SDK — Web Chat`)
+  console.log(`  http://localhost:${PORT}\n`)
+})