@secemp/elwood 0.1.0

package/examples/19-session-store-s3.js

@@ -0,0 +1,67 @@
+/**
+ * 19-session-store-s3.js
+ *
+ * Equivalent of the official examples/session-stores/s3/demo.ts
+ *
+ * Official version:
+ *   import { S3Client } from '@aws-sdk/client-s3';
+ *   import { query } from '@anthropic-ai/claude-agent-sdk';
+ *   import { S3SessionStore } from './src/S3SessionStore.ts';
+ *
+ *   const client = new S3Client({ region, endpoint, forcePathStyle });
+ *   const store = new S3SessionStore({ bucket, prefix: 'demo', client });
+ *
+ *   for await (const m of query({
+ *     prompt, options: { sessionStore: store, resume, maxTurns: 1 }
+ *   })) { ... }
+ *
+ * This elwood version shows how to use an S3-backed session store
+ * with elwood's query() function. The session store adapter is identical
+ * to the official example since it is a pure S3 adapter.
+ *
+ * Prerequisites:
+ *   - ANTHROPIC_API_KEY set in environment
+ *   - Claude Code CLI installed
+ *   - S3-compatible endpoint (e.g. MinIO)
+ *   - SESSION_STORE_S3_BUCKET set
+ *   - AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY set
+ *   - npm install @aws-sdk/client-s3
+ *
+ * Run:
+ *   SESSION_STORE_S3_ENDPOINT=http://localhost:9000 \
+ *   SESSION_STORE_S3_BUCKET=claude-sessions \
+ *   AWS_ACCESS_KEY_ID=minioadmin AWS_SECRET_ACCESS_KEY=minioadmin \
+ *     node examples/19-session-store-s3.js
+ */
+
+import { query } from '../src/index.js';
+
+// Note: You would need to implement or import an S3SessionStore adapter.
+// The adapter is identical to the official example since it is pure S3 logic.
+// See: https://github.com/anthropics/claude-agent-sdk-typescript/tree/main/examples/session-stores/s3
+
+const bucket = process.env.SESSION_STORE_S3_BUCKET;
+if (!bucket) {
+  console.error('Set SESSION_STORE_S3_BUCKET (see header for MinIO setup)');
+  console.error(
+    '\nFor local testing with MinIO:\n' +
+    '  docker run -d -p 9000:9000 minio/minio server /data\n' +
+    '  docker run --rm --network host minio/mc \\\n' +
+    '    sh -c \'mc alias set local http://localhost:9000 minioadmin minioadmin && mc mb local/claude-sessions\''
+  );
+  process.exit(1);
+}
+
+console.log('To use this example, implement or import an S3SessionStore 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 { S3Client } from "@aws-sdk/client-s3";');
+console.log('  // import { S3SessionStore } from "./S3SessionStore.js";');
+console.log('');
+console.log('  const client = new S3Client({ region, endpoint, forcePathStyle });');
+console.log(`  const store = new S3SessionStore({ bucket: "${bucket}", prefix: "demo", client });`);
+console.log('');
+console.log('  // Then use query() exactly as with the official SDK');

package/examples/20-session-list.js

@@ -0,0 +1,72 @@
+/**
+ * 20-session-list.js
+ *
+ * Equivalent of the official "list sessions / get session messages" example.
+ *
+ * Official version:
+ *   import { listSessions, getSessionMessages } from "@anthropic-ai/claude-agent-sdk";
+ *
+ *   const sessions = await listSessions({ dir: "/path/to/project", limit: 10 });
+ *   for (const session of sessions) {
+ *     console.log(`${session.summary} (${session.sessionId})`);
+ *   }
+ *
+ *   const [latest] = await listSessions({ dir: "/path/to/project", limit: 1 });
+ *   if (latest) {
+ *     const messages = await getSessionMessages(latest.sessionId, {
+ *       dir: "/path/to/project", limit: 20
+ *     });
+ *     for (const msg of messages) {
+ *       console.log(`[${msg.type}] ${msg.uuid}`);
+ *     }
+ *   }
+ *
+ * This elwood version uses the file-system-based session utilities that
+ * read from ~/.claude/projects/*.jsonl directly.
+ *
+ * Prerequisites:
+ *   - Claude Code CLI installed (sessions are stored in ~/.claude/projects/)
+ *
+ * Run:
+ *   node examples/20-session-list.js
+ */
+
+import { listSessions, getSessionMessages, getSessionInfo } from '../src/index.js';
+
+// List all sessions (most recent first)
+console.log('--- Recent sessions ---');
+const sessions = await listSessions();
+
+if (sessions.length === 0) {
+  console.log('No sessions found. Run a query first to create one.');
+  process.exit(0);
+}
+
+// Show the first 10 sessions
+for (const session of sessions.slice(0, 10)) {
+  console.log(`  ${session.sessionId} (${session.mtime.toISOString()}) [${session.projectPath}]`);
+}
+
+// Get details about the most recent session
+const latest = sessions[0];
+console.log(`\n--- Session info: ${latest.sessionId} ---`);
+const info = await getSessionInfo(latest.sessionId);
+if (info) {
+  console.log(`  File: ${info.filePath}`);
+  console.log(`  Messages: ${info.messageCount}`);
+  console.log(`  Last modified: ${info.mtime.toISOString()}`);
+}
+
+// Read messages from the most recent session
+console.log(`\n--- Messages from: ${latest.sessionId} ---`);
+const messages = await getSessionMessages(latest.sessionId);
+for (const msg of messages.slice(0, 5)) {
+  const type = msg.type ?? '(unknown)';
+  const role = msg.message?.role ?? msg.role ?? '';
+  const preview = JSON.stringify(msg).slice(0, 100);
+  console.log(`  [${type}${role ? '/' + role : ''}] ${preview}...`);
+}
+
+if (messages.length > 5) {
+  console.log(`  ... and ${messages.length - 5} more messages`);
+}

package/examples/21-hooks-notification-slack.js

@@ -0,0 +1,78 @@
+/**
+ * 21-hooks-notification-slack.js
+ *
+ * Equivalent of the official "forward notifications to Slack" hooks example.
+ *
+ * Official version:
+ *   import { query, HookCallback, NotificationHookInput } from "@anthropic-ai/claude-agent-sdk";
+ *
+ *   const notificationHandler: HookCallback = async (input, toolUseID, { signal }) => {
+ *     const notification = input as NotificationHookInput;
+ *     try {
+ *       await fetch("https://hooks.slack.com/services/YOUR/WEBHOOK/URL", {
+ *         method: "POST",
+ *         headers: { "Content-Type": "application/json" },
+ *         body: JSON.stringify({ text: `Agent status: ${notification.message}` }),
+ *         signal
+ *       });
+ *     } catch (error) { ... }
+ *     return {};
+ *   };
+ *
+ * This elwood version forwards agent notifications to a Slack webhook.
+ *
+ * Prerequisites:
+ *   - ANTHROPIC_API_KEY set in environment
+ *   - Claude Code CLI installed
+ *   - SLACK_WEBHOOK_URL set to your Slack incoming webhook URL
+ *
+ * Run:
+ *   SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL \
+ *     node examples/21-hooks-notification-slack.js
+ */
+
+import { query } from '../src/index.js';
+
+const SLACK_WEBHOOK_URL = process.env.SLACK_WEBHOOK_URL;
+if (!SLACK_WEBHOOK_URL) {
+  console.error('Set SLACK_WEBHOOK_URL to your Slack incoming webhook URL');
+  process.exit(1);
+}
+
+// Define a hook callback that sends notifications to Slack
+const notificationHandler = async (input, _toolUseID, { signal }) => {
+  const message = input.message ?? '(no message)';
+
+  try {
+    await fetch(SLACK_WEBHOOK_URL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        text: `Agent status: ${message}`,
+      }),
+      signal,
+    });
+  } catch (error) {
+    if (error instanceof Error && error.name === 'AbortError') {
+      console.log('Notification cancelled');
+    } else {
+      console.error('Failed to send notification:', error);
+    }
+  }
+
+  // Return empty object. Notification hooks don't modify agent behavior.
+  return {};
+};
+
+// Register the hook for Notification events (no matcher needed)
+for await (const message of query({
+  prompt: 'Analyze this codebase',
+  options: {
+    hooks: {
+      Notification: [{ hooks: [notificationHandler] }],
+    },
+    maxTurns: 5,
+  },
+})) {
+  console.log(message);
+}

package/examples/22-hooks-webhook-posttooluse.js

@@ -0,0 +1,78 @@
+/**
+ * 22-hooks-webhook-posttooluse.js
+ *
+ * Equivalent of the official "make HTTP requests from hooks" example.
+ *
+ * Official version:
+ *   const webhookNotifier: HookCallback = async (input, toolUseID, { signal }) => {
+ *     if (input.hook_event_name !== "PostToolUse") return {};
+ *     try {
+ *       await fetch("https://api.example.com/webhook", {
+ *         method: "POST",
+ *         headers: { "Content-Type": "application/json" },
+ *         body: JSON.stringify({
+ *           tool: (input as PostToolUseHookInput).tool_name,
+ *           timestamp: new Date().toISOString()
+ *         }),
+ *         signal
+ *       });
+ *     } catch (error) { ... }
+ *     return {};
+ *   };
+ *
+ * This elwood version sends a webhook notification after each tool completes.
+ *
+ * Prerequisites:
+ *   - ANTHROPIC_API_KEY set in environment
+ *   - Claude Code CLI installed
+ *   - WEBHOOK_URL set to your webhook endpoint
+ *
+ * Run:
+ *   WEBHOOK_URL=https://api.example.com/webhook node examples/22-hooks-webhook-posttooluse.js
+ */
+
+import { query } from '../src/index.js';
+
+const WEBHOOK_URL = process.env.WEBHOOK_URL ?? 'https://httpbin.org/post';
+
+// Define a webhook notifier that fires after each tool completes
+const webhookNotifier = async (input, _toolUseID, { signal }) => {
+  // Only fire after a tool completes (PostToolUse), not before
+  if (input.hook_event_name !== 'PostToolUse') return {};
+
+  try {
+    await fetch(WEBHOOK_URL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        tool: input.tool_name,
+        timestamp: new Date().toISOString(),
+      }),
+      // Pass signal so the request cancels if the hook times out
+      signal,
+    });
+    console.log(`[webhook] Notified about tool: ${input.tool_name}`);
+  } catch (error) {
+    if (error instanceof Error && error.name === 'AbortError') {
+      console.log('[webhook] Request cancelled');
+    }
+    // Don't re-throw. A failed webhook shouldn't stop the agent.
+  }
+
+  return {};
+};
+
+// Register as a PostToolUse hook
+for await (const message of query({
+  prompt: 'Refactor the auth module',
+  options: {
+    hooks: {
+      PostToolUse: [{ hooks: [webhookNotifier] }],
+    },
+    maxTurns: 5,
+  },
+})) {
+  if (message.type === 'result') {
+    console.log(message);
+  }
+}

package/examples/23-hooks-subagent-tracker.js

@@ -0,0 +1,59 @@
+/**
+ * 23-hooks-subagent-tracker.js
+ *
+ * Equivalent of the official "track subagent activity" hooks example.
+ *
+ * Official version:
+ *   import { HookCallback, SubagentStopHookInput } from "@anthropic-ai/claude-agent-sdk";
+ *
+ *   const subagentTracker: HookCallback = async (input, toolUseID, { signal }) => {
+ *     const subInput = input as SubagentStopHookInput;
+ *     console.log(`[SUBAGENT] Completed: ${subInput.agent_id}`);
+ *     console.log(`  Transcript: ${subInput.agent_transcript_path}`);
+ *     console.log(`  Tool use ID: ${toolUseID}`);
+ *     console.log(`  Stop hook active: ${subInput.stop_hook_active}`);
+ *     return {};
+ *   };
+ *
+ * This elwood version monitors subagent lifecycle using SubagentStop hooks.
+ *
+ * Prerequisites:
+ *   - ANTHROPIC_API_KEY set in environment
+ *   - Claude Code CLI installed
+ *
+ * Run:
+ *   node examples/23-hooks-subagent-tracker.js
+ */
+
+import { query } from '../src/index.js';
+
+// Track subagent activity with a SubagentStop hook
+const subagentTracker = async (input, toolUseID, { signal }) => {
+  console.log(`[SUBAGENT] Completed: ${input.agent_id}`);
+  console.log(`  Transcript: ${input.agent_transcript_path}`);
+  console.log(`  Tool use ID: ${toolUseID}`);
+  console.log(`  Stop hook active: ${input.stop_hook_active}`);
+  return {};
+};
+
+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.',
+        prompt: 'Analyze code quality and suggest improvements.',
+        tools: ['Read', 'Glob', 'Grep'],
+      },
+    },
+    hooks: {
+      SubagentStop: [{ hooks: [subagentTracker] }],
+    },
+    maxTurns: 10,
+  },
+})) {
+  if ('result' in message) {
+    console.log(message.result);
+  }
+}

package/examples/24-v2-session-api.js

@@ -0,0 +1,62 @@
+/**
+ * 24-v2-session-api.js
+ *
+ * Demonstrates the V2 Session API (UNSTABLE) for multi-turn conversations.
+ *
+ * The official SDK provides unstable_v2_createSession, unstable_v2_resumeSession,
+ * and unstable_v2_prompt. This elwood version wraps the same interface.
+ *
+ * The V2 API provides a Session object that manages state across multiple
+ * send/stream cycles, rather than using separate query() calls with resume.
+ *
+ * Prerequisites:
+ *   - ANTHROPIC_API_KEY set in environment
+ *   - Claude Code CLI installed
+ *
+ * Run:
+ *   node examples/24-v2-session-api.js
+ */
+
+import {
+  unstable_v2_createSession,
+  unstable_v2_prompt,
+} from '../src/index.js';
+
+// --- Example 1: One-shot prompt with unstable_v2_prompt ---
+console.log('--- V2 one-shot prompt ---');
+try {
+  const result = await unstable_v2_prompt('What is 2 + 2?', {
+    model: undefined, // use default model
+  });
+  console.log('Result:', result);
+} catch (err) {
+  console.log('V2 prompt requires a running session (expected in dry-run):', err.message);
+}
+
+// --- Example 2: Multi-turn session with unstable_v2_createSession ---
+console.log('\n--- V2 multi-turn session ---');
+const session = unstable_v2_createSession({});
+
+try {
+  // First turn
+  await session.send('Remember the number 42.');
+  for await (const msg of session.stream()) {
+    if (msg.type === 'result') {
+      console.log('Turn 1 result:', msg);
+      break;
+    }
+  }
+
+  // Second turn (continues with context from the first)
+  await session.send('What number did I tell you to remember?');
+  for await (const msg of session.stream()) {
+    if (msg.type === 'result') {
+      console.log('Turn 2 result:', msg);
+      break;
+    }
+  }
+} catch (err) {
+  console.log('V2 session requires API access:', err.message);
+} finally {
+  session.close();
+}

package/examples/README.md

@@ -0,0 +1,95 @@
+# elwood examples
+
+These examples are elwood equivalents of the official `@anthropic-ai/claude-agent-sdk` examples. Each uses `import { ... } from '../src/index.js'` to import from elwood instead of the official SDK.
+
+The key difference: elwood runs the Claude Code CLI **in-process** via Babel AST instrumentation rather than spawning a subprocess. The API is the same.
+
+## Examples
+
+### Core query patterns
+
+| File | Official equivalent | Description |
+|------|-------------------|-------------|
+| `01-basic-query.js` | [Overview: basic query](https://code.claude.com/docs/en/agent-sdk/overview) | Simplest possible query with allowedTools |
+| `02-bug-fixer.js` | [Quickstart: bug fixer](https://code.claude.com/docs/en/agent-sdk/quickstart) | Agent that reads, analyzes, and fixes buggy code |
+| `03-custom-system-prompt.js` | [Quickstart: custom prompt](https://code.claude.com/docs/en/agent-sdk/quickstart) | Override the system prompt |
+| `04-read-only-agent.js` | [Overview: permissions](https://code.claude.com/docs/en/agent-sdk/overview) | Read-only agent (Read, Glob, Grep only) |
+| `05-find-todos.js` | [Overview: built-in tools](https://code.claude.com/docs/en/agent-sdk/overview) | Search codebase for TODO comments |
+
+### Sessions
+
+| File | Official equivalent | Description |
+|------|-------------------|-------------|
+| `06-session-resume.js` | [Overview: sessions](https://code.claude.com/docs/en/agent-sdk/overview) | Capture session ID and resume with full context |
+| `20-session-list.js` | [TypeScript ref: listSessions](https://code.claude.com/docs/en/agent-sdk/typescript) | List sessions and read messages from disk |
+| `24-v2-session-api.js` | V2 Session API (UNSTABLE) | Multi-turn sessions with send/stream |
+
+### Hooks
+
+| File | Official equivalent | Description |
+|------|-------------------|-------------|
+| `07-hooks-pretooluse.js` | [Hooks: protect .env files](https://code.claude.com/docs/en/agent-sdk/hooks) | PreToolUse hook that blocks writes to .env files |
+| `08-hooks-posttooluse-audit.js` | [Hooks: audit log](https://code.claude.com/docs/en/agent-sdk/hooks) | PostToolUse hook that logs file changes to audit.log |
+| `09-hooks-block-etc.js` | [Hooks: block /etc writes](https://code.claude.com/docs/en/agent-sdk/hooks) | PreToolUse hook that blocks writes to /etc |
+| `10-hooks-redirect-sandbox.js` | [Hooks: redirect to sandbox](https://code.claude.com/docs/en/agent-sdk/hooks) | PreToolUse hook that rewrites file paths to /sandbox |
+| `21-hooks-notification-slack.js` | [Hooks: forward to Slack](https://code.claude.com/docs/en/agent-sdk/hooks) | Notification hook that sends to Slack webhook |
+| `22-hooks-webhook-posttooluse.js` | [Hooks: HTTP webhook](https://code.claude.com/docs/en/agent-sdk/hooks) | PostToolUse hook that sends webhooks |
+| `23-hooks-subagent-tracker.js` | [Hooks: track subagents](https://code.claude.com/docs/en/agent-sdk/hooks) | SubagentStop hook that logs subagent completion |
+
+### Subagents
+
+| File | Official equivalent | Description |
+|------|-------------------|-------------|
+| `11-subagents.js` | [Overview: subagents](https://code.claude.com/docs/en/agent-sdk/overview) | Spawn a specialized code-reviewer subagent |
+
+### MCP servers
+
+| File | Official equivalent | Description |
+|------|-------------------|-------------|
+| `12-mcp-stdio.js` | [Overview: MCP](https://code.claude.com/docs/en/agent-sdk/overview) | Connect to Playwright MCP server via stdio |
+| `13-mcp-http.js` | [MCP: HTTP transport](https://code.claude.com/docs/en/agent-sdk/mcp) | Connect to Claude Code docs MCP server via HTTP |
+| `16-mcp-github.js` | [MCP: GitHub](https://code.claude.com/docs/en/agent-sdk/mcp) | Connect to GitHub MCP server with debug logging |
+
+### Custom tools
+
+| File | Official equivalent | Description |
+|------|-------------------|-------------|
+| `14-custom-tool.js` | [Custom tools: weather](https://code.claude.com/docs/en/agent-sdk/custom-tools) | Weather temperature tool with createSdkMcpServer() |
+| `15-custom-tool-unit-converter.js` | [Custom tools: converter](https://code.claude.com/docs/en/agent-sdk/custom-tools) | Unit converter with enum schemas and error handling |
+
+### Session stores
+
+| File | Official equivalent | Description |
+|------|-------------------|-------------|
+| `17-session-store-postgres.js` | [examples/session-stores/postgres/demo.ts](https://github.com/anthropics/claude-agent-sdk-typescript/tree/main/examples/session-stores/postgres) | Postgres-backed session store usage guide |
+| `18-session-store-redis.js` | [examples/session-stores/redis/demo.ts](https://github.com/anthropics/claude-agent-sdk-typescript/tree/main/examples/session-stores/redis) | Redis-backed session store usage guide |
+| `19-session-store-s3.js` | [examples/session-stores/s3/demo.ts](https://github.com/anthropics/claude-agent-sdk-typescript/tree/main/examples/session-stores/s3) | S3-backed session store usage guide |
+
+### Testing
+
+| File | Description |
+|------|-------------|
+| `smoke-test.js` | Verifies all exports, constants, and API shapes without API calls |
+| `basic.js` | Low-level AST instrumentation example (elwood-specific) |
+
+## Running examples
+
+Most examples require:
+- `ANTHROPIC_API_KEY` set in environment
+- Claude Code CLI installed (`npm install -g @anthropic-ai/claude-code`)
+
+The smoke test requires neither:
+```bash
+node examples/smoke-test.js
+```
+
+## API differences from official SDK
+
+| Feature | Official SDK | elwood |
+|---------|-------------|--------|
+| Import path | `@anthropic-ai/claude-agent-sdk` | `../src/index.js` (or `elwood`) |
+| Execution | Subprocess (spawns `claude` binary) | In-process (Babel AST instrumentation) |
+| Tool schemas | Zod schemas (`z.string()`, `z.number()`) | Plain JSON Schema objects |
+| Language | TypeScript (.ts) | JavaScript (.js) |
+| McpServer class | Bundled in SDK | Loaded from claude-code or @modelcontextprotocol/sdk |
+| Session stores | SessionStore interface (typed) | Same interface, used via options.sessionStore |