@secemp/elwood 0.1.0

package/examples/10-hooks-redirect-sandbox.js

@@ -0,0 +1,70 @@
+/**
+ * 10-hooks-redirect-sandbox.js
+ *
+ * Equivalent of the official "redirect writes to sandbox" hooks example.
+ *
+ * Official version:
+ *   const redirectToSandbox: HookCallback = async (input, toolUseID, { signal }) => {
+ *     if (input.hook_event_name !== "PreToolUse") return {};
+ *     const preInput = input as PreToolUseHookInput;
+ *     const toolInput = preInput.tool_input as Record<string, unknown>;
+ *     if (preInput.tool_name === "Write") {
+ *       const originalPath = toolInput.file_path as string;
+ *       return {
+ *         hookSpecificOutput: {
+ *           hookEventName: preInput.hook_event_name,
+ *           permissionDecision: "allow",
+ *           updatedInput: { ...toolInput, file_path: `/sandbox${originalPath}` }
+ *         }
+ *       };
+ *     }
+ *     return {};
+ *   };
+ *
+ * This elwood version intercepts Write tool calls and rewrites the file_path
+ * to prepend /sandbox, redirecting all file writes to a sandboxed directory.
+ *
+ * Prerequisites:
+ *   - ANTHROPIC_API_KEY set in environment
+ *   - Claude Code CLI installed
+ *
+ * Run:
+ *   node examples/10-hooks-redirect-sandbox.js
+ */
+
+import { query } from '../src/index.js';
+
+// Redirect all file writes to a sandboxed directory
+const redirectToSandbox = async (input, _toolUseID, { signal }) => {
+  if (input.hook_event_name !== 'PreToolUse') return {};
+
+  const toolInput = input.tool_input;
+  if (input.tool_name === 'Write' && typeof toolInput === 'object') {
+    const originalPath = toolInput.file_path;
+    return {
+      hookSpecificOutput: {
+        hookEventName: input.hook_event_name,
+        permissionDecision: 'allow',
+        updatedInput: {
+          ...toolInput,
+          file_path: `/sandbox${originalPath}`,
+        },
+      },
+    };
+  }
+  return {};
+};
+
+for await (const message of query({
+  prompt: 'Create a hello.txt file',
+  options: {
+    hooks: {
+      PreToolUse: [{ matcher: 'Write', hooks: [redirectToSandbox] }],
+    },
+    maxTurns: 3,
+  },
+})) {
+  if (message.type === 'result') {
+    console.log(message);
+  }
+}

package/examples/11-subagents.js

@@ -0,0 +1,54 @@
+/**
+ * 11-subagents.js
+ *
+ * Equivalent of the official "subagents" example.
+ *
+ * Official version:
+ *   import { query } from "@anthropic-ai/claude-agent-sdk";
+ *   for await (const message of query({
+ *     prompt: "Use the code-reviewer agent to review this codebase",
+ *     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.",
+ *           tools: ["Read", "Glob", "Grep"]
+ *         }
+ *       }
+ *     }
+ *   })) {
+ *     if ("result" in message) console.log(message.result);
+ *   }
+ *
+ * This elwood version spawns a specialized subagent for code review.
+ * Subagents are invoked via the Agent tool and report back to the main agent.
+ *
+ * Prerequisites:
+ *   - ANTHROPIC_API_KEY set in environment
+ *   - Claude Code CLI installed
+ *
+ * Run:
+ *   node examples/11-subagents.js
+ */
+
+import { query } from '../src/index.js';
+
+for await (const message of query({
+  prompt: 'Use the code-reviewer agent to review this codebase',
+  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.',
+        tools: ['Read', 'Glob', 'Grep'],
+      },
+    },
+    maxTurns: 10,
+  },
+})) {
+  if ('result' in message) {
+    console.log(message.result);
+  }
+}

package/examples/12-mcp-stdio.js

@@ -0,0 +1,48 @@
+/**
+ * 12-mcp-stdio.js
+ *
+ * Equivalent of the official "MCP stdio server" example (Playwright browser).
+ *
+ * Official version:
+ *   import { query } from "@anthropic-ai/claude-agent-sdk";
+ *   for await (const message of query({
+ *     prompt: "Open example.com and describe what you see",
+ *     options: {
+ *       mcpServers: {
+ *         playwright: { command: "npx", args: ["@playwright/mcp@latest"] }
+ *       }
+ *     }
+ *   })) {
+ *     if ("result" in message) console.log(message.result);
+ *   }
+ *
+ * This elwood version connects to an external MCP server via stdio transport.
+ * The example uses the Playwright MCP server for browser automation.
+ *
+ * Prerequisites:
+ *   - ANTHROPIC_API_KEY set in environment
+ *   - Claude Code CLI installed
+ *   - npx available in PATH
+ *
+ * Run:
+ *   node examples/12-mcp-stdio.js
+ */
+
+import { query } from '../src/index.js';
+
+for await (const message of query({
+  prompt: 'Open example.com and describe what you see',
+  options: {
+    mcpServers: {
+      playwright: {
+        command: 'npx',
+        args: ['@playwright/mcp@latest'],
+      },
+    },
+    maxTurns: 5,
+  },
+})) {
+  if ('result' in message) {
+    console.log(message.result);
+  }
+}

package/examples/13-mcp-http.js

@@ -0,0 +1,54 @@
+/**
+ * 13-mcp-http.js
+ *
+ * Equivalent of the official "MCP HTTP/SSE server" example.
+ *
+ * Official version:
+ *   import { query } from "@anthropic-ai/claude-agent-sdk";
+ *   for await (const message of query({
+ *     prompt: "Use the docs MCP server to explain what hooks are in Claude Code",
+ *     options: {
+ *       mcpServers: {
+ *         "claude-code-docs": {
+ *           type: "http",
+ *           url: "https://code.claude.com/docs/mcp"
+ *         }
+ *       },
+ *       allowedTools: ["mcp__claude-code-docs__*"]
+ *     }
+ *   })) {
+ *     if (message.type === "result" && message.subtype === "success") {
+ *       console.log(message.result);
+ *     }
+ *   }
+ *
+ * This elwood version connects to the Claude Code documentation MCP server
+ * via HTTP transport.
+ *
+ * Prerequisites:
+ *   - ANTHROPIC_API_KEY set in environment
+ *   - Claude Code CLI installed
+ *
+ * Run:
+ *   node examples/13-mcp-http.js
+ */
+
+import { query } from '../src/index.js';
+
+for await (const message of query({
+  prompt: 'Use the docs MCP server to explain what hooks are in Claude Code',
+  options: {
+    mcpServers: {
+      'claude-code-docs': {
+        type: 'http',
+        url: 'https://code.claude.com/docs/mcp',
+      },
+    },
+    allowedTools: ['mcp__claude-code-docs__*'],
+    maxTurns: 5,
+  },
+})) {
+  if (message.type === 'result' && message.subtype === 'success') {
+    console.log(message.result);
+  }
+}

package/examples/14-custom-tool.js

@@ -0,0 +1,84 @@
+/**
+ * 14-custom-tool.js
+ *
+ * Equivalent of the official "custom tool" example (weather temperature tool).
+ *
+ * Official version:
+ *   import { tool, createSdkMcpServer, query } from "@anthropic-ai/claude-agent-sdk";
+ *   import { z } from "zod";
+ *
+ *   const getTemperature = tool(
+ *     "get_temperature",
+ *     "Get the current temperature at a location",
+ *     { latitude: z.number(), longitude: z.number() },
+ *     async (args) => {
+ *       const response = await fetch(`https://api.open-meteo.com/v1/forecast?...`);
+ *       const data = await response.json();
+ *       return { content: [{ type: "text", text: `Temperature: ${data.current.temperature_2m}F` }] };
+ *     }
+ *   );
+ *
+ *   const weatherServer = createSdkMcpServer({
+ *     name: "weather", version: "1.0.0", tools: [getTemperature]
+ *   });
+ *
+ * Note: In elwood, tool() returns a simple { name, description, inputSchema, handler }
+ * object. The Zod schema validation from the official SDK is not included -- pass a
+ * plain JSON Schema object as inputSchema instead.
+ *
+ * Prerequisites:
+ *   - ANTHROPIC_API_KEY set in environment
+ *   - Claude Code CLI installed
+ *
+ * Run:
+ *   node examples/14-custom-tool.js
+ */
+
+import { query, tool, createSdkMcpServer } from '../src/index.js';
+
+// Define a tool: name, description, input schema (JSON Schema), handler
+const getTemperature = tool(
+  'get_temperature',
+  'Get the current temperature at a location',
+  {
+    type: 'object',
+    properties: {
+      latitude: { type: 'number', description: 'Latitude coordinate' },
+      longitude: { type: 'number', description: 'Longitude coordinate' },
+    },
+    required: ['latitude', 'longitude'],
+  },
+  async (args) => {
+    const response = await fetch(
+      `https://api.open-meteo.com/v1/forecast?latitude=${args.latitude}&longitude=${args.longitude}&current=temperature_2m&temperature_unit=fahrenheit`
+    );
+    const data = await response.json();
+
+    // Return a content array - Claude sees this as the tool result
+    return {
+      content: [
+        { type: 'text', text: `Temperature: ${data.current.temperature_2m}\u00B0F` },
+      ],
+    };
+  }
+);
+
+// Wrap the tool in an in-process MCP server
+const weatherServer = await createSdkMcpServer({
+  name: 'weather',
+  version: '1.0.0',
+  tools: [getTemperature],
+});
+
+for await (const message of query({
+  prompt: "What's the temperature in San Francisco?",
+  options: {
+    mcpServers: { weather: weatherServer },
+    allowedTools: ['mcp__weather__get_temperature'],
+    maxTurns: 3,
+  },
+})) {
+  if (message.type === 'result' && message.subtype === 'success') {
+    console.log(message.result);
+  }
+}

package/examples/15-custom-tool-unit-converter.js

@@ -0,0 +1,132 @@
+/**
+ * 15-custom-tool-unit-converter.js
+ *
+ * Equivalent of the official "unit converter" custom tool example.
+ *
+ * Official version uses Zod schemas with z.enum(). This elwood version uses
+ * plain JSON Schema objects instead.
+ *
+ * This example demonstrates:
+ *   - Enum schemas via JSON Schema "enum" constraint
+ *   - Error handling with isError: true (keeps agent loop alive)
+ *   - Running the same tool with multiple prompts
+ *
+ * Prerequisites:
+ *   - ANTHROPIC_API_KEY set in environment
+ *   - Claude Code CLI installed
+ *
+ * Run:
+ *   node examples/15-custom-tool-unit-converter.js
+ */
+
+import { query, tool, createSdkMcpServer } from '../src/index.js';
+
+const convertUnits = tool(
+  'convert_units',
+  'Convert a value from one unit to another',
+  {
+    type: 'object',
+    properties: {
+      unit_type: {
+        type: 'string',
+        enum: ['length', 'temperature', 'weight'],
+        description: 'Category of unit',
+      },
+      from_unit: {
+        type: 'string',
+        description: 'Unit to convert from, e.g. kilometers, fahrenheit, pounds',
+      },
+      to_unit: {
+        type: 'string',
+        description: 'Unit to convert to',
+      },
+      value: {
+        type: 'number',
+        description: 'Value to convert',
+      },
+    },
+    required: ['unit_type', 'from_unit', 'to_unit', 'value'],
+  },
+  async (args) => {
+    const conversions = {
+      length: {
+        kilometers_to_miles: (v) => v * 0.621371,
+        miles_to_kilometers: (v) => v * 1.60934,
+        meters_to_feet: (v) => v * 3.28084,
+        feet_to_meters: (v) => v * 0.3048,
+      },
+      temperature: {
+        celsius_to_fahrenheit: (v) => (v * 9) / 5 + 32,
+        fahrenheit_to_celsius: (v) => ((v - 32) * 5) / 9,
+        celsius_to_kelvin: (v) => v + 273.15,
+        kelvin_to_celsius: (v) => v - 273.15,
+      },
+      weight: {
+        kilograms_to_pounds: (v) => v * 2.20462,
+        pounds_to_kilograms: (v) => v * 0.453592,
+        grams_to_ounces: (v) => v * 0.035274,
+        ounces_to_grams: (v) => v * 28.3495,
+      },
+    };
+
+    const key = `${args.from_unit}_to_${args.to_unit}`;
+    const fn = conversions[args.unit_type]?.[key];
+
+    if (!fn) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Unsupported conversion: ${args.from_unit} to ${args.to_unit}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    const result = fn(args.value);
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `${args.value} ${args.from_unit} = ${result.toFixed(4)} ${args.to_unit}`,
+        },
+      ],
+    };
+  }
+);
+
+// Wrap in an MCP server
+const converterServer = await createSdkMcpServer({
+  name: 'converter',
+  version: '1.0.0',
+  tools: [convertUnits],
+});
+
+// Run multiple prompts through the same tool
+const prompts = [
+  'Convert 100 kilometers to miles.',
+  'What is 72 degrees Fahrenheit in Celsius?',
+  'How many pounds is 5 kilograms?',
+];
+
+for (const prompt of prompts) {
+  for await (const message of query({
+    prompt,
+    options: {
+      mcpServers: { converter: converterServer },
+      allowedTools: ['mcp__converter__convert_units'],
+      maxTurns: 3,
+    },
+  })) {
+    if (message.type === 'assistant') {
+      for (const block of message.message?.content ?? []) {
+        if (block.type === 'tool_use') {
+          console.log(`[tool call] ${block.name}`, block.input);
+        }
+      }
+    } else if (message.type === 'result' && message.subtype === 'success') {
+      console.log(`Q: ${prompt}\nA: ${message.result}\n`);
+    }
+  }
+}

package/examples/16-mcp-github.js

@@ -0,0 +1,71 @@
+/**
+ * 16-mcp-github.js
+ *
+ * Equivalent of the official "GitHub MCP server" example.
+ *
+ * Official version:
+ *   import { query } from "@anthropic-ai/claude-agent-sdk";
+ *   for await (const message of query({
+ *     prompt: "List the 3 most recent issues in anthropics/claude-code",
+ *     options: {
+ *       mcpServers: {
+ *         github: {
+ *           command: "npx",
+ *           args: ["-y", "@modelcontextprotocol/server-github"],
+ *           env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN }
+ *         }
+ *       },
+ *       allowedTools: ["mcp__github__list_issues"]
+ *     }
+ *   })) { ... }
+ *
+ * This elwood version connects to the GitHub MCP server via stdio transport
+ * and lists recent issues with debug logging.
+ *
+ * Prerequisites:
+ *   - ANTHROPIC_API_KEY set in environment
+ *   - GITHUB_TOKEN set in environment (GitHub personal access token with repo scope)
+ *   - Claude Code CLI installed
+ *   - npx available in PATH
+ *
+ * Run:
+ *   GITHUB_TOKEN=ghp_xxx node examples/16-mcp-github.js
+ */
+
+import { query } from '../src/index.js';
+
+for await (const message of query({
+  prompt: 'List the 3 most recent issues in anthropics/claude-code',
+  options: {
+    mcpServers: {
+      github: {
+        command: 'npx',
+        args: ['-y', '@modelcontextprotocol/server-github'],
+        env: {
+          GITHUB_TOKEN: process.env.GITHUB_TOKEN,
+        },
+      },
+    },
+    allowedTools: ['mcp__github__list_issues'],
+    maxTurns: 5,
+  },
+})) {
+  // Verify MCP server connected successfully
+  if (message.type === 'system' && message.subtype === 'init') {
+    console.log('MCP servers:', message.mcp_servers);
+  }
+
+  // Log when Claude calls an MCP tool
+  if (message.type === 'assistant') {
+    for (const block of message.message?.content ?? []) {
+      if (block.type === 'tool_use' && block.name?.startsWith('mcp__')) {
+        console.log('MCP tool called:', block.name);
+      }
+    }
+  }
+
+  // Print the final result
+  if (message.type === 'result' && message.subtype === 'success') {
+    console.log(message.result);
+  }
+}

package/examples/17-session-store-postgres.js

@@ -0,0 +1,78 @@
+/**
+ * 17-session-store-postgres.js
+ *
+ * Equivalent of the official examples/session-stores/postgres/demo.ts
+ *
+ * Official version:
+ *   import { Pool } from 'pg';
+ *   import { query } from '@anthropic-ai/claude-agent-sdk';
+ *   import { PostgresSessionStore } from './src/PostgresSessionStore.ts';
+ *
+ *   const pool = new Pool({ connectionString: url });
+ *   const store = new PostgresSessionStore({ pool });
+ *   await store.ensureSchema();
+ *
+ *   for await (const m of query({
+ *     prompt, options: { sessionStore: store, resume, maxTurns: 1 }
+ *   })) { ... }
+ *
+ * This elwood version shows how to use a Postgres-backed session store
+ * with elwood's query() function. The session store is an external adapter
+ * that mirrors conversation transcripts to a Postgres table.
+ *
+ * Note: The SessionStore interface is passed directly to options.sessionStore.
+ * The PostgresSessionStore implementation would be identical to the official
+ * example since it is a pure database adapter with no SDK-specific logic.
+ *
+ * Prerequisites:
+ *   - ANTHROPIC_API_KEY set in environment
+ *   - Claude Code CLI installed
+ *   - PostgreSQL server running
+ *   - SESSION_STORE_POSTGRES_URL set (e.g., postgresql://postgres:postgres@localhost:5432/postgres)
+ *   - npm install pg
+ *
+ * Run:
+ *   SESSION_STORE_POSTGRES_URL=postgresql://postgres:postgres@localhost:5432/postgres \
+ *     node examples/17-session-store-postgres.js
+ */
+
+import { query } from '../src/index.js';
+
+// Note: You would need to implement or import a PostgresSessionStore adapter.
+// The adapter is identical to the official example since it is pure database logic.
+// See: https://github.com/anthropics/claude-agent-sdk-typescript/tree/main/examples/session-stores/postgres
+
+const url = process.env.SESSION_STORE_POSTGRES_URL;
+if (!url) {
+  console.error('Set SESSION_STORE_POSTGRES_URL (see header)');
+  console.error('Example: postgresql://postgres:postgres@localhost:5432/postgres');
+  console.error(
+    '\nFor local testing:\n  docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=postgres postgres:16-alpine'
+  );
+  process.exit(1);
+}
+
+console.log('To use this example, implement or import a PostgresSessionStore adapter.');
+console.log('The adapter is identical to the official claude-agent-sdk example.');
+console.log('');
+console.log('Usage pattern with elwood:');
+console.log('');
+console.log('  import { query } from "elwood";');
+console.log('  // import { PostgresSessionStore } from "./PostgresSessionStore.js";');
+console.log('');
+console.log('  const store = new PostgresSessionStore({ pool });');
+console.log('  await store.ensureSchema();');
+console.log('');
+console.log('  async function run(prompt, resume) {');
+console.log('    let sessionId;');
+console.log('    for await (const m of query({');
+console.log('      prompt,');
+console.log('      options: { sessionStore: store, resume, maxTurns: 1 },');
+console.log('    })) {');
+console.log('      if (m.type === "system" && m.subtype === "init") sessionId = m.session_id;');
+console.log('      if (m.type === "result") {');
+console.log('        console.log(`[${m.subtype}]`, "result" in m ? m.result : "");');
+console.log('      }');
+console.log('    }');
+console.log('    return sessionId;');
+console.log('  }');

package/examples/18-session-store-redis.js

@@ -0,0 +1,65 @@
+/**
+ * 18-session-store-redis.js
+ *
+ * Equivalent of the official examples/session-stores/redis/demo.ts
+ *
+ * Official version:
+ *   import Redis from 'ioredis';
+ *   import { query } from '@anthropic-ai/claude-agent-sdk';
+ *   import { RedisSessionStore } from './src/RedisSessionStore.ts';
+ *
+ *   const client = new Redis(url);
+ *   const store = new RedisSessionStore({ client, prefix: 'demo' });
+ *
+ *   for await (const m of query({
+ *     prompt, options: { sessionStore: store, resume, maxTurns: 1 }
+ *   })) { ... }
+ *
+ * This elwood version shows how to use a Redis-backed session store
+ * with elwood's query() function. The session store adapter is identical
+ * to the official example since it is a pure Redis adapter.
+ *
+ * Prerequisites:
+ *   - ANTHROPIC_API_KEY set in environment
+ *   - Claude Code CLI installed
+ *   - Redis server running
+ *   - SESSION_STORE_REDIS_URL set (default: redis://localhost:6379/0)
+ *   - npm install ioredis
+ *
+ * Run:
+ *   SESSION_STORE_REDIS_URL=redis://localhost:6379/0 node examples/18-session-store-redis.js
+ */
+
+import { query } from '../src/index.js';
+
+// Note: You would need to implement or import a RedisSessionStore adapter.
+// The adapter is identical to the official example since it is pure Redis logic.
+// See: https://github.com/anthropics/claude-agent-sdk-typescript/tree/main/examples/session-stores/redis
+
+const url = process.env.SESSION_STORE_REDIS_URL ?? 'redis://localhost:6379/0';
+
+console.log('To use this example, implement or import a RedisSessionStore adapter.');
+console.log('The adapter is identical to the official claude-agent-sdk example.');
+console.log('');
+console.log('Usage pattern with elwood:');
+console.log('');
+console.log('  import { query } from "elwood";');
+console.log('  // import Redis from "ioredis";');
+console.log('  // import { RedisSessionStore } from "./RedisSessionStore.js";');
+console.log('');
+console.log(`  const client = new Redis("${url}");`);
+console.log('  const store = new RedisSessionStore({ client, prefix: "demo" });');
+console.log('');
+console.log('  async function run(prompt, resume) {');
+console.log('    let sessionId;');
+console.log('    for await (const m of query({');
+console.log('      prompt,');
+console.log('      options: { sessionStore: store, resume, maxTurns: 1 },');
+console.log('    })) {');
+console.log('      if (m.type === "system" && m.subtype === "init") sessionId = m.session_id;');
+console.log('      if (m.type === "result") {');
+console.log('        console.log(`[${m.subtype}]`, "result" in m ? m.result : "");');
+console.log('      }');
+console.log('    }');
+console.log('    return sessionId;');
+console.log('  }');