@standardagents/cli 0.8.1

package/dist/index.js

@@ -0,0 +1,1328 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import path3 from 'path';
+import fs from 'fs';
+import { parse, modify, applyEdits } from 'jsonc-parser';
+import chalk from 'chalk';
+
+function findWranglerConfig(cwd) {
+  const jsonc = path3.join(cwd, "wrangler.jsonc");
+  const json = path3.join(cwd, "wrangler.json");
+  if (fs.existsSync(jsonc)) {
+    return jsonc;
+  }
+  if (fs.existsSync(json)) {
+    return json;
+  }
+  return null;
+}
+function readWranglerConfig(filePath) {
+  const text = fs.readFileSync(filePath, "utf-8");
+  const config = parse(text);
+  return { config, text };
+}
+function updateWranglerConfig(filePath, text, updates) {
+  let result = text;
+  if (updates.durable_objects) {
+    const edits = modify(result, ["durable_objects"], updates.durable_objects, {});
+    result = applyEdits(result, edits);
+  }
+  if (updates.migrations) {
+    const edits = modify(result, ["migrations"], updates.migrations, {});
+    result = applyEdits(result, edits);
+  }
+  if (updates.env) {
+    for (const [envName, envConfig] of Object.entries(updates.env)) {
+      if (envConfig.durable_objects) {
+        const edits = modify(result, ["env", envName, "durable_objects"], envConfig.durable_objects, {});
+        result = applyEdits(result, edits);
+      }
+      if (envConfig.migrations) {
+        const edits = modify(result, ["env", envName, "migrations"], envConfig.migrations, {});
+        result = applyEdits(result, edits);
+      }
+    }
+  }
+  return result;
+}
+function writeWranglerConfig(filePath, content) {
+  fs.writeFileSync(filePath, content, "utf-8");
+}
+var logger = {
+  success: (message) => {
+    console.log(chalk.green("\u2713"), message);
+  },
+  error: (message) => {
+    console.log(chalk.red("\u2717"), message);
+  },
+  warning: (message) => {
+    console.log(chalk.yellow("\u26A0"), message);
+  },
+  info: (message) => {
+    console.log(chalk.blue("\u2139"), message);
+  },
+  log: (message) => {
+    console.log(message);
+  }
+};
+
+// src/commands/init.ts
+async function init(options = {}) {
+  var _a, _b, _c, _d, _e;
+  const cwd = process.cwd();
+  logger.info("Initializing Standard Agents configuration...");
+  const configPath = findWranglerConfig(cwd);
+  if (!configPath) {
+    logger.error("No wrangler.jsonc or wrangler.json found in current directory");
+    logger.log("\nTo use Standard Agents, you need a Cloudflare Workers project with wrangler configuration.");
+    logger.log("\nExample wrangler.jsonc:");
+    logger.log(`
+{
+  "name": "my-agent",
+  "main": "server/index.ts",
+  "compatibility_date": "2025-08-13",
+  "compatibility_flags": ["nodejs_compat"],
+
+  "durable_objects": {
+    "bindings": [
+      {
+        "name": "AGENT_BUILDER_THREAD",
+        "class_name": "DurableThread"
+      },
+      {
+        "name": "AGENT_BUILDER",
+        "class_name": "DurableAgentBuilder"
+      }
+    ]
+  },
+
+  "migrations": [
+    {
+      "tag": "v1",
+      "new_sqlite_classes": ["DurableThread", "DurableAgentBuilder"]
+    }
+  ]
+}
+`);
+    process.exit(1);
+  }
+  logger.success(`Found configuration: ${path3.relative(cwd, configPath)}`);
+  const { config, text } = readWranglerConfig(configPath);
+  const hasAgentBuilderThread = (_b = (_a = config.durable_objects) == null ? void 0 : _a.bindings) == null ? void 0 : _b.some(
+    (binding) => binding.name === "AGENT_BUILDER_THREAD"
+  );
+  const hasAgentBuilder = (_d = (_c = config.durable_objects) == null ? void 0 : _c.bindings) == null ? void 0 : _d.some(
+    (binding) => binding.name === "AGENT_BUILDER"
+  );
+  if (hasAgentBuilderThread && hasAgentBuilder && !options.force) {
+    logger.success("Standard Agents is already configured!");
+    logger.info("Use --force to overwrite existing configuration");
+    return;
+  }
+  const updates = {};
+  updates.durable_objects = config.durable_objects || { bindings: [] };
+  if (options.force) {
+    updates.durable_objects.bindings = updates.durable_objects.bindings.filter(
+      (binding) => binding.name !== "AGENT_BUILDER_THREAD" && binding.name !== "AGENT_BUILDER"
+    );
+  }
+  if (!hasAgentBuilderThread || options.force) {
+    updates.durable_objects.bindings.push({
+      name: "AGENT_BUILDER_THREAD",
+      class_name: "DurableThread"
+    });
+    logger.info("Added AGENT_BUILDER_THREAD binding");
+  }
+  if (!hasAgentBuilder || options.force) {
+    updates.durable_objects.bindings.push({
+      name: "AGENT_BUILDER",
+      class_name: "DurableAgentBuilder"
+    });
+    logger.info("Added AGENT_BUILDER binding");
+  }
+  if (!config.migrations || config.migrations.length === 0) {
+    updates.migrations = [
+      {
+        tag: "v1",
+        new_sqlite_classes: ["DurableThread", "DurableAgentBuilder"]
+      }
+    ];
+    logger.info("Added Durable Object migrations");
+  }
+  if ((_e = config.env) == null ? void 0 : _e.test) {
+    updates.env = updates.env || {};
+    updates.env.test = config.env.test;
+    if (!updates.env.test.durable_objects) {
+      updates.env.test.durable_objects = { bindings: [] };
+    }
+    const hasTestThread = updates.env.test.durable_objects.bindings.some(
+      (binding) => binding.name === "AGENT_BUILDER_THREAD"
+    );
+    const hasTestBuilder = updates.env.test.durable_objects.bindings.some(
+      (binding) => binding.name === "AGENT_BUILDER"
+    );
+    if (!hasTestThread) {
+      updates.env.test.durable_objects.bindings.push({
+        name: "AGENT_BUILDER_THREAD",
+        class_name: "DurableThread"
+      });
+      logger.info("Added test environment AGENT_BUILDER_THREAD binding");
+    }
+    if (!hasTestBuilder) {
+      updates.env.test.durable_objects.bindings.push({
+        name: "AGENT_BUILDER",
+        class_name: "DurableAgentBuilder"
+      });
+      logger.info("Added test environment AGENT_BUILDER binding");
+    }
+    if (!updates.env.test.migrations) {
+      updates.env.test.migrations = [
+        {
+          tag: "v1",
+          new_sqlite_classes: ["DurableThread", "DurableAgentBuilder"]
+        }
+      ];
+      logger.info("Added test environment Durable Object migrations");
+    }
+  }
+  const updatedText = updateWranglerConfig(configPath, text, updates);
+  writeWranglerConfig(configPath, updatedText);
+  logger.success("Configuration updated successfully!");
+  logger.log("\nNext steps:");
+  logger.log("1. Create your agent definitions in agents/agents/");
+  logger.log("2. Start your development server");
+}
+var TOOLS_CLAUDE_MD = `# Custom Tools
+
+This directory contains custom tools that your AI agents can call during execution.
+
+## What Are Tools?
+
+Tools are functions that extend your agent's capabilities beyond text generation. They allow agents to:
+- Fetch external data (APIs, databases)
+- Perform calculations
+- Execute side effects (send emails, create records)
+- Chain to other prompts or agents
+
+## Creating a Tool
+
+Create a new file in this directory following the naming convention:
+
+\`\`\`
+agents/tools/
+\u251C\u2500\u2500 my_tool.ts           # \u2713 snake_case recommended
+\u251C\u2500\u2500 another_tool.ts      # \u2713 Valid
+\u2514\u2500\u2500 CamelCaseTool.ts     # \u26A0 Works but triggers warning
+\`\`\`
+
+### Tool File Structure
+
+Each tool file should export a default function created with \`defineTool\`:
+
+\`\`\`typescript
+import { defineTool } from '@standardagents/builder';
+import { z } from 'zod';
+
+// With arguments
+export default defineTool(
+  'Description of what this tool does',
+  z.object({
+    param1: z.string().describe('Description of param1'),
+    param2: z.number().optional().describe('Optional parameter'),
+  }),
+  async (flow, args) => {
+    // Tool implementation
+    const result = await doSomething(args.param1, args.param2);
+
+    return {
+      status: 'success',
+      result: JSON.stringify(result)
+    };
+  }
+);
+
+// Without arguments
+export default defineTool(
+  'Simple tool with no parameters',
+  async (flow) => {
+    return {
+      status: 'success',
+      result: 'Done!'
+    };
+  }
+);
+\`\`\`
+
+### FlowState Object
+
+The \`flow\` parameter provides execution context:
+
+\`\`\`typescript
+interface FlowState {
+  env: Env;                    // Cloudflare bindings (KV, R2, etc.)
+  storage: DurableObjectStorage; // Thread's SQLite storage
+  threadId: string;            // Current thread ID
+  agentId: string;             // Current agent ID
+  currentSide: 'a' | 'b';      // Which side is executing
+  turnCount: number;           // Current turn number
+  context: Record<string, any>; // Arbitrary state data
+  // ... and more
+}
+\`\`\`
+
+### Return Value
+
+Tools must return a ToolResult object:
+
+\`\`\`typescript
+interface ToolResult {
+  status: 'success' | 'error';
+  result?: string;    // Success data
+  error?: string;     // Error message
+}
+\`\`\`
+
+## Tool Discovery
+
+Tools are **auto-discovered** at runtime. No manual registration needed!
+
+1. Vite plugin scans this directory on startup
+2. Generates virtual module with dynamic imports
+3. Tools become available to all agents
+4. HMR (Hot Module Replacement) works in development
+
+## Examples
+
+### API Fetch Tool
+
+\`\`\`typescript
+import { defineTool } from '@standardagents/builder';
+import { z } from 'zod';
+
+export default defineTool(
+  'Fetch weather data for a city',
+  z.object({
+    city: z.string().describe('City name'),
+    units: z.enum(['metric', 'imperial']).optional(),
+  }),
+  async (flow, args) => {
+    try {
+      const response = await fetch(
+        \`https://api.weather.com/\${args.city}\`
+      );
+      const data = await response.json();
+
+      return {
+        status: 'success',
+        result: JSON.stringify(data),
+      };
+    } catch (error) {
+      return {
+        status: 'error',
+        error: error.message,
+      };
+    }
+  }
+);
+\`\`\`
+
+### Thread Storage Tool
+
+\`\`\`typescript
+import { defineTool } from '@standardagents/builder';
+import { z } from 'zod';
+
+export default defineTool(
+  'Get custom data from thread storage',
+  z.object({
+    key: z.string().describe('Storage key to look up'),
+  }),
+  async (flow, args) => {
+    try {
+      // Use thread's SQLite storage
+      const result = await flow.storage.sql.exec(
+        \`SELECT value FROM custom_data WHERE key = ?\`,
+        args.key
+      ).toArray();
+
+      if (result.length === 0) {
+        return {
+          status: 'error',
+          error: 'Data not found',
+        };
+      }
+
+      return {
+        status: 'success',
+        result: JSON.stringify(result[0]),
+      };
+    } catch (error) {
+      return {
+        status: 'error',
+        error: error.message,
+      };
+    }
+  }
+);
+\`\`\`
+
+## Best Practices
+
+1. **Descriptive Names**: Use clear, action-oriented names (e.g., \`fetch_weather\`, not \`weather\`)
+2. **Detailed Descriptions**: The description helps the LLM understand when to use the tool
+3. **Zod Descriptions**: Add \`.describe()\` to all schema fields for better LLM understanding
+4. **Error Handling**: Always wrap in try/catch and return proper error status
+5. **Type Safety**: Use Zod for runtime validation and TypeScript inference
+6. **Keep It Simple**: Each tool should do one thing well
+7. **Stateless**: Don't rely on global state; use FlowState for context
+
+## Debugging
+
+- Check console output for tool execution logs
+- Tool errors appear in the logs table
+- Use \`console.log\` within tools (visible in dev mode)
+- Check message history to see tool calls and responses
+
+## Testing
+
+Tools can be tested independently:
+
+\`\`\`typescript
+import myTool from './my_tool';
+
+const [description, schema, handler] = myTool;
+
+// Mock FlowState
+const mockFlow = {
+  env: mockEnv,
+  storage: mockStorage,
+  threadId: 'test-123',
+  // ...
+};
+
+const result = await handler(mockFlow, { param1: 'test' });
+console.log(result);
+\`\`\`
+
+## Limitations
+
+- No nested directories (tools must be directly in this folder)
+- Tool execution is **sequential** (no parallel execution)
+- Tool results must be JSON-serializable strings
+- Maximum execution time limited by Workers CPU time
+
+## Related
+
+- **Hooks**: \`agents/hooks/CLAUDE.md\` - Lifecycle hooks
+- **APIs**: \`agents/api/CLAUDE.md\` - Thread-specific endpoints
+- **Documentation**: Project root \`CLAUDE.md\` for architecture overview
+`;
+var HOOKS_CLAUDE_MD = `# Lifecycle Hooks
+
+This directory contains lifecycle hooks that intercept and modify agent execution at key points.
+
+## What Are Hooks?
+
+Hooks are optional functions that run at specific points during agent execution:
+- **Before** LLM requests (prefilter messages)
+- **After** LLM responses (post-process messages)
+- At other lifecycle events (message creation, tool execution, etc.)
+
+Unlike tools (which agents explicitly call), hooks run **automatically** when their trigger point occurs.
+
+## Using defineHook for Type Safety
+
+All hooks should use the \`defineHook\` utility for strict typing:
+
+\`\`\`typescript
+import { defineHook } from '@standardagents/builder';
+
+export default defineHook('filter_messages', async (state, rows) => {
+  // TypeScript knows exactly what state and rows are!
+  return rows;
+});
+\`\`\`
+
+The \`defineHook\` function provides:
+- **Strict typing** for hook parameters based on the hook name
+- **IntelliSense** support in your editor
+- **Type checking** to catch errors before runtime
+- **Better documentation** through type hints
+
+## Available Hooks
+
+### \`filter_messages\`
+
+**When**: Before message history is transformed to chat completion format
+**Purpose**: Filter or modify SQL row data with access to ALL database columns
+
+\`\`\`typescript
+import { defineHook, type MessageRow } from '@standardagents/builder';
+
+export default defineHook('filter_messages', async (state, rows) => {
+  // rows contains ALL columns from messages table:
+  // id, role, content, name, tool_calls, tool_call_id, log_id,
+  // created_at, request_sent_at, response_completed_at, status,
+  // silent, tool_status
+
+  // Your filtering logic here
+  return rows;
+});
+\`\`\`
+
+**Common Use Cases**:
+- Filter out failed tool messages (\`tool_status = 'error'\`)
+- Remove messages older than a certain time
+- Filter by status (pending, completed, failed)
+- Access columns not available in chat format
+- Filter based on database-specific metadata
+
+**Example - Filter Out Failed Tools**:
+\`\`\`typescript
+export default defineHook('filter_messages', async (state, rows) => {
+  // Remove tool messages that failed execution
+  return rows.filter(row => {
+    if (row.role === 'tool' && row.tool_status === 'error') {
+      return false;
+    }
+    return true;
+  });
+});
+\`\`\`
+
+**Important**: This hook runs **before** messages are transformed to Message objects and receives raw SQL data. Use this when you need access to database columns like \`tool_status\`, \`silent\`, or \`status\`.
+
+### \`prefilter_llm_history\`
+
+**When**: Immediately after message transformation, before sending to LLM
+**Purpose**: Modify, filter, or limit message history in chat completion format
+
+\`\`\`typescript
+import { defineHook } from '@standardagents/builder';
+
+export default defineHook('prefilter_llm_history', async (state, messages) => {
+  // messages are in chat completion format (already transformed from SQL rows)
+  // Available fields: role, content, tool_calls, tool_call_id, name
+
+  // Your filtering logic here
+  return messages;
+});
+\`\`\`
+
+**Common Use Cases**:
+- Limit conversation history to last N messages
+- Remove old tool messages to reduce token usage
+- Summarize old messages before sending
+- Add dynamic context based on message patterns
+- Filter out sensitive information
+
+**Example - Limit to Last 10 Messages**:
+\`\`\`typescript
+import { defineHook } from '@standardagents/builder';
+
+export default defineHook('prefilter_llm_history', async (state, messages) => {
+  // Keep all system messages
+  const systemMessages = messages.filter(m => m.role === 'system');
+
+  // Take only last 10 non-system messages
+  const otherMessages = messages
+    .filter(m => m.role !== 'system')
+    .slice(-10);
+
+  return [...systemMessages, ...otherMessages];
+});
+\`\`\`
+
+**Example - Remove Old Tool Messages**:
+\`\`\`typescript
+import { defineHook } from '@standardagents/builder';
+
+export default defineHook('prefilter_llm_history', async (state, messages) => {
+  // Keep messages from last 5 turns, remove old tool messages
+  const recentThreshold = messages.length - 10;
+
+  return messages.filter((m, index) => {
+    if (m.role === 'tool' && index < recentThreshold) {
+      return false; // Remove old tool messages
+    }
+    return true;
+  });
+});
+\`\`\`
+
+**Important**: The **filtered messages are logged**, so you can see exactly what was sent to the LLM in the logs table.
+
+### \`post_process_message\`
+
+**When**: After receiving a response from the LLM
+**Purpose**: Modify or enhance the assistant's message
+
+\`\`\`typescript
+import { defineHook } from '@standardagents/builder';
+
+export default defineHook('post_process_message', async (state, message) => {
+  // Your post-processing logic here
+  return message;
+});
+\`\`\`
+
+**Common Use Cases**:
+- Format or clean up LLM output
+- Add metadata or tracking information
+- Inject additional context into responses
+- Transform tool call formats
+
+**Example - Add Metadata**:
+\`\`\`typescript
+import { defineHook } from '@standardagents/builder';
+
+export default defineHook('post_process_message', async (state, message) => {
+  if (message.content) {
+    message.content += \`\\n\\n_Generated at turn \${state.turnCount}_\`;
+  }
+  return message;
+});
+\`\`\`
+
+**Note**: This hook is currently defined but **not yet invoked** in FlowEngine. It will be activated in a future update.
+
+### Message Lifecycle Hooks
+
+The following hooks run for **ANY** message being created or updated in the database, whether it's an agent message, tool message, user message, or system message.
+
+#### \`before_create_message\`
+
+**When**: Immediately before a message is inserted into the database
+**Purpose**: Modify message data before it's stored
+
+\`\`\`typescript
+import { defineHook } from '@standardagents/builder';
+
+export default defineHook('before_create_message', async (state, message) => {
+  // Your modification logic here
+  return message;
+});
+\`\`\`
+
+**Message Structure**:
+\`\`\`typescript
+{
+    id: string;
+    role: string;
+    content: string | null;
+    tool_calls?: string | null;
+    tool_call_id?: string | null;
+    name?: string | null;
+    created_at: number;
+    status?: string;
+    silent?: boolean;
+}
+\`\`\`
+
+**Common Use Cases**:
+- Add prefixes or metadata to message content
+- Modify message based on agent configuration
+- Add tracking IDs or identifiers
+- Transform message format before storage
+
+**Example - Add Metadata**:
+\`\`\`typescript
+import { defineHook } from '@standardagents/builder';
+
+export default defineHook('before_create_message', async (state, message) => {
+  // Add agent ID to all messages
+  if (message.content && message.role === 'assistant') {
+    message.name = state.agentConfig.title;
+  }
+  return message;
+});
+\`\`\`
+
+#### \`after_create_message\`
+
+**When**: Immediately after a message is inserted into the database
+**Purpose**: Perform actions based on newly created messages
+
+\`\`\`typescript
+import { defineHook } from '@standardagents/builder';
+
+export default defineHook('after_create_message', async (state, message) => {
+  // Your post-creation logic here
+  // No return value needed
+});
+\`\`\`
+
+**Common Use Cases**:
+- Log messages to external systems
+- Trigger webhooks or notifications
+- Update analytics or metrics
+- Send real-time updates to monitoring services
+
+**Example - Log to External Service**:
+\`\`\`typescript
+import { defineHook } from '@standardagents/builder';
+
+export default defineHook('after_create_message', async (state, message) => {
+  // Log all assistant messages to analytics
+  if (message.role === 'assistant' && message.content) {
+    try {
+      await fetch('https://analytics.example.com/message', {
+        method: 'POST',
+        body: JSON.stringify({
+          threadId: state.threadId,
+          messageId: message.id,
+          contentLength: message.content.length,
+        })
+      });
+    } catch (error) {
+      console.error('Analytics logging failed:', error);
+    }
+  }
+});
+\`\`\`
+
+#### \`before_update_message\`
+
+**When**: Immediately before a message is updated in the database
+**Purpose**: Modify update data before it's applied
+
+\`\`\`typescript
+import { defineHook } from '@standardagents/builder';
+
+export default defineHook('before_update_message', async (state, messageId, updates) => {
+  // Your modification logic here
+  return updates;
+});
+\`\`\`
+
+**Common Use Cases**:
+- Validate or sanitize updated content
+- Add completion timestamps
+- Transform status values
+- Inject metadata into updates
+
+**Example - Add Completion Timestamp**:
+\`\`\`typescript
+import { defineHook } from '@standardagents/builder';
+
+export default defineHook('before_update_message', async (state, messageId, updates) => {
+  // Add custom completion timestamp for completed messages
+  if (updates.status === 'completed' && !updates.response_completed_at) {
+    updates.response_completed_at = Date.now() * 1000; // microseconds
+  }
+  return updates;
+});
+\`\`\`
+
+#### \`after_update_message\`
+
+**When**: Immediately after a message is updated in the database
+**Purpose**: Perform actions based on message updates
+
+\`\`\`typescript
+import { defineHook } from '@standardagents/builder';
+
+export default defineHook('after_update_message', async (state, messageId, updates) => {
+  // Your post-update logic here
+  // No return value needed
+});
+\`\`\`
+
+**Common Use Cases**:
+- Track message status changes
+- Trigger notifications on completion
+- Update external systems
+- Log state transitions
+
+**Example - Notify on Failure**:
+\`\`\`typescript
+import { defineHook } from '@standardagents/builder';
+
+export default defineHook('after_update_message', async (state, messageId, updates) => {
+  // Send notification when message is marked as failed
+  if (updates.status === 'failed') {
+    console.log(\`[Alert] Message \${messageId} failed in thread \${state.threadId}\`);
+  }
+});
+\`\`\`
+
+**Important**:
+- \`before_*\` hooks must return the modified data object
+- \`after_*\` hooks don't need to return anything
+- All 4 hooks run for ANY message operation (agent, tool, user, system messages)
+- Updates passed to update hooks contain only the fields being updated
+
+## Creating a Hook
+
+1. Create a file named exactly as the hook (e.g., \`prefilter_llm_history.ts\`)
+2. Use \`defineHook\` to ensure correct typing
+3. Return the modified data (or original if no changes)
+
+\`\`\`typescript
+// agents/hooks/prefilter_llm_history.ts
+import { defineHook } from '@standardagents/builder';
+
+export default defineHook('prefilter_llm_history', async (state, messages) => {
+  console.log(\`Processing \${messages.length} messages\`);
+
+  // Your logic here
+
+  return messages; // Return modified or original
+});
+\`\`\`
+
+## Hook Lifecycle
+
+1. **Discovery**: Vite plugin scans this directory on startup
+2. **Virtual Module**: Generates \`virtual:agent-hooks\` with lazy imports
+3. **Lazy Loading**: Hooks are loaded on first use (not at startup)
+4. **Caching**: Once loaded, hooks are cached for performance
+5. **HMR**: Changes trigger hot reload in development
+
+## Error Handling
+
+Hooks are designed to be **safe**:
+- If hook file doesn't exist \u2192 Silently skipped (no error)
+- If hook throws error \u2192 Logged to console, original data returned
+- If hook returns invalid data \u2192 Original data used as fallback
+
+This ensures hooks never break agent execution.
+
+## FlowState Object
+
+All hooks receive the FlowState context:
+
+\`\`\`typescript
+interface FlowState {
+  threadId: string;           // Current thread ID
+  flowId: string;             // Unique execution ID
+  agentConfig: Agent;         // Full agent configuration
+  currentSide: 'a' | 'b';     // Which side is executing (dual_ai)
+  turnCount: number;          // Current turn number
+  stopped: boolean;           // Whether execution should stop
+  messageHistory: Message[];  // Full conversation history
+  env: Env;                   // Cloudflare bindings
+  storage: DurableObjectStorage; // Thread's SQLite storage
+  context: Record<string, any>;  // Arbitrary state data
+  // ... and more
+}
+\`\`\`
+
+Use this to make context-aware decisions in your hooks.
+
+## Best Practices
+
+1. **Keep Hooks Fast**: They run on every execution, avoid heavy operations
+2. **Always Return Data**: Never return \`undefined\` or \`null\`
+3. **Log Thoughtfully**: Use \`console.log\` sparingly (visible in logs)
+4. **Handle Errors**: Wrap risky operations in try/catch
+5. **Document Behavior**: Add comments explaining what your hook does
+6. **Test Thoroughly**: Hooks affect ALL agent executions
+
+## Debugging
+
+- Check console output for hook loading/execution logs
+- Hook errors are logged with \`[Hooks] \u2717\` prefix
+- Inspect logs table to see filtered messages (for prefilter hook)
+- Use \`console.log\` within hooks for debugging
+
+## Performance Considerations
+
+Hooks run on **every turn**, so:
+- Avoid expensive operations (heavy computation, slow APIs)
+- Cache results when possible
+- Consider using FlowState context to skip unnecessary work
+- Use async operations efficiently
+
+## Message Data & Tool Status
+
+The \`filter_messages\` hook receives SQL row data with ALL columns from the messages table:
+
+\`\`\`typescript
+interface MessageRow {
+  id: string;
+  role: 'system' | 'user' | 'assistant' | 'tool';
+  content: string | null;
+  name: string | null;
+  tool_calls: string | null;          // JSON string of tool calls
+  tool_call_id: string | null;        // For role='tool' messages
+  log_id: string | null;              // Reference to logs table
+  created_at: number;                 // Microseconds timestamp
+  request_sent_at: number | null;     // When request was sent to LLM
+  response_completed_at: number | null; // When response completed
+  status: 'pending' | 'completed' | 'failed' | null;
+  silent: number | null;              // 1 if message should be hidden, 0/null otherwise
+  tool_status: 'success' | 'error' | null; // Status of tool execution (tool messages only)
+}
+\`\`\`
+
+The \`tool_status\` column is automatically set when tool messages are created:
+- \`'success'\` - Tool executed successfully
+- \`'error'\` - Tool execution failed or threw an error
+- \`null\` - Not a tool message (role !== 'tool')
+
+## Testing
+
+Example test for a hook:
+
+\`\`\`typescript
+import { defineHook } from '@standardagents/builder';
+import prefilterHook from './prefilter_llm_history';
+
+const mockState = {
+  turnCount: 5,
+  currentSide: 'a',
+  // ... other FlowState fields
+};
+
+const mockMessages = [
+  { role: 'system', content: 'You are helpful' },
+  { role: 'user', content: 'Hello' },
+  { role: 'assistant', content: 'Hi there!' },
+  // ... more messages
+];
+
+const result = await prefilterHook(mockState, mockMessages);
+console.log('Filtered:', result.length, 'messages');
+\`\`\`
+
+## Hook File Naming
+
+**Critical**: Hook files must be named **exactly** as expected:
+- \u2713 \`filter_messages.ts\`
+- \u2713 \`prefilter_llm_history.ts\`
+- \u2713 \`post_process_message.ts\`
+- \u2713 \`before_create_message.ts\`
+- \u2713 \`after_create_message.ts\`
+- \u2713 \`before_update_message.ts\`
+- \u2713 \`after_update_message.ts\`
+- \u2717 \`filterMessages.ts\` (wrong case)
+- \u2717 \`prefilterLLMHistory.ts\` (wrong case)
+- \u2717 \`before-create-message.ts\` (wrong separator)
+
+The file name determines which hook point it intercepts.
+
+## Available Hooks
+
+Currently implemented hooks:
+- \`filter_messages\` - Filter SQL row data before transformation to chat format (access to all DB columns including tool_status)
+- \`prefilter_llm_history\` - Filter messages before sending to LLM (after transformation to chat format)
+- \`before_create_message\` - Before inserting message into database
+- \`after_create_message\` - After message is created in database
+- \`before_update_message\` - Before updating message in database
+- \`after_update_message\` - After message is updated in database
+- \`after_tool_call_success\` - After successful tool execution (can modify result or return null to remove)
+- \`after_tool_call_failure\` - After failed tool execution (can modify error or return null to remove)
+
+## Related
+
+- **Tools**: \`agents/tools/CLAUDE.md\` - Custom tools
+- **APIs**: \`agents/api/CLAUDE.md\` - Thread endpoints
+- **Documentation**: Project root \`CLAUDE.md\` for architecture
+`;
+var API_CLAUDE_MD = `# Thread-Specific API Endpoints
+
+This directory contains custom API endpoints that operate on specific threads.
+
+## What Are Thread Endpoints?
+
+Thread endpoints are API routes that:
+- Automatically receive a specific thread's Durable Object instance
+- Can access thread-local SQLite storage
+- Perform operations in the context of a conversation
+- Use file-based routing for automatic discovery
+
+## File-Based Routing
+
+Create files following this naming convention:
+
+\`\`\`
+agents/api/
+\u251C\u2500\u2500 summary.get.ts          # GET /agents/api/threads/:id/summary
+\u251C\u2500\u2500 export.post.ts          # POST /agents/api/threads/:id/export
+\u251C\u2500\u2500 metadata.put.ts         # PUT /agents/api/threads/:id/metadata
+\u2514\u2500\u2500 archive.delete.ts       # DELETE /agents/api/threads/:id/archive
+\`\`\`
+
+**Pattern**: \`{name}.{method}.ts\`
+
+**Methods**: \`get\`, \`post\`, \`put\`, \`delete\`, \`patch\`
+
+**URL**: \`/agents/api/threads/:id/{name}\`
+
+## Creating a Thread Endpoint
+
+Use \`defineThreadEndpoint\` from \`@standardagents/builder\`:
+
+\`\`\`typescript
+import { defineThreadEndpoint } from '@standardagents/builder';
+
+export default defineThreadEndpoint(async (thread, request, env) => {
+  // thread is the DurableObject stub for the requested thread
+  // request is the incoming Request object
+  // env is the Cloudflare environment with bindings
+
+  // Access thread's storage directly
+  const messages = await thread.getMessages();
+
+  // Perform operations
+  const summary = generateSummary(messages);
+
+  // Return response
+  return new Response(JSON.stringify({ summary }), {
+    headers: { 'Content-Type': 'application/json' }
+  });
+});
+\`\`\`
+
+## Thread Object
+
+The \`thread\` parameter is a DurableObject stub with RPC methods:
+
+\`\`\`typescript
+interface DurableThread {
+  // Get messages from thread's SQLite storage
+  getMessages(limit?: number, offset?: number): Promise<Message[]>;
+
+  // Get execution logs
+  getLogs(limit?: number, offset?: number): Promise<Log[]>;
+
+  // Process a new message (starts agent execution)
+  processMessage(content: string, role?: string): Promise<Response>;
+
+  // Get thread metadata
+  getThreadMeta(threadId: string): Promise<ThreadMetadata>;
+
+  // Direct storage access (advanced)
+  storage: DurableObjectStorage;
+}
+\`\`\`
+
+## Examples
+
+### GET Summary Endpoint
+
+\`\`\`typescript
+// agents/api/summary.get.ts
+import { defineThreadEndpoint } from '@standardagents/builder';
+
+export default defineThreadEndpoint(async (thread, request, env) => {
+  // Fetch messages from thread
+  const messages = await thread.getMessages();
+
+  // Generate summary
+  const userMessages = messages.filter(m => m.role === 'user');
+  const assistantMessages = messages.filter(m => m.role === 'assistant');
+
+  return new Response(JSON.stringify({
+    total_messages: messages.length,
+    user_messages: userMessages.length,
+    assistant_messages: assistantMessages.length,
+    first_message: messages[0]?.content,
+    last_message: messages[messages.length - 1]?.content,
+  }), {
+    headers: { 'Content-Type': 'application/json' }
+  });
+});
+\`\`\`
+
+**Usage**: \`GET /agents/api/threads/{threadId}/summary\`
+
+### POST Export Endpoint
+
+\`\`\`typescript
+// agents/api/export.post.ts
+import { defineThreadEndpoint } from '@standardagents/builder';
+
+export default defineThreadEndpoint(async (thread, request, env) => {
+  const { format } = await request.json();
+
+  // Get messages
+  const messages = await thread.getMessages();
+
+  // Export based on format
+  let content: string;
+  let contentType: string;
+
+  if (format === 'json') {
+    content = JSON.stringify(messages, null, 2);
+    contentType = 'application/json';
+  } else if (format === 'markdown') {
+    content = messages
+      .map(m => \`**\${m.role}**: \${m.content}\`)
+      .join('\\n\\n');
+    contentType = 'text/markdown';
+  } else {
+    return new Response('Invalid format', { status: 400 });
+  }
+
+  return new Response(content, {
+    headers: {
+      'Content-Type': contentType,
+      'Content-Disposition': \`attachment; filename="thread-export.\${format}"\`
+    }
+  });
+});
+\`\`\`
+
+**Usage**: \`POST /agents/api/threads/{threadId}/export\`
+
+### Direct Storage Access
+
+\`\`\`typescript
+// agents/api/stats.get.ts
+import { defineThreadEndpoint } from '@standardagents/builder';
+
+export default defineThreadEndpoint(async (thread, request, env) => {
+  // Access SQLite storage directly
+  const storage = (thread as any).storage;
+
+  const cursor = await storage.sql.exec(\`
+    SELECT
+      COUNT(*) as count,
+      role,
+      AVG(LENGTH(content)) as avg_length
+    FROM messages
+    GROUP BY role
+  \`);
+
+  const stats = cursor.toArray();
+
+  return new Response(JSON.stringify({ stats }), {
+    headers: { 'Content-Type': 'application/json' }
+  });
+});
+\`\`\`
+
+## Request Handling
+
+### Reading Request Body
+
+\`\`\`typescript
+export default defineThreadEndpoint(async (thread, request, env) => {
+  // JSON
+  const body = await request.json();
+
+  // FormData
+  const formData = await request.formData();
+
+  // Text
+  const text = await request.text();
+
+  // ...
+});
+\`\`\`
+
+### Query Parameters
+
+\`\`\`typescript
+export default defineThreadEndpoint(async (thread, request, env) => {
+  const url = new URL(request.url);
+  const limit = url.searchParams.get('limit') || '10';
+
+  const messages = await thread.getMessages(parseInt(limit));
+
+  // ...
+});
+\`\`\`
+
+### Headers
+
+\`\`\`typescript
+export default defineThreadEndpoint(async (thread, request, env) => {
+  const authHeader = request.headers.get('Authorization');
+
+  if (!authHeader) {
+    return new Response('Unauthorized', { status: 401 });
+  }
+
+  // ...
+});
+\`\`\`
+
+## Error Handling
+
+Always wrap in try/catch for robust error handling:
+
+\`\`\`typescript
+export default defineThreadEndpoint(async (thread, request, env) => {
+  try {
+    // Your endpoint logic
+    const result = await doSomething();
+
+    return new Response(JSON.stringify(result), {
+      headers: { 'Content-Type': 'application/json' }
+    });
+  } catch (error) {
+    console.error('Endpoint error:', error);
+
+    return new Response(
+      JSON.stringify({
+        error: error.message
+      }),
+      {
+        status: 500,
+        headers: { 'Content-Type': 'application/json' }
+      }
+    );
+  }
+});
+\`\`\`
+
+## Environment Bindings
+
+Access Cloudflare bindings via \`env\`:
+
+\`\`\`typescript
+export default defineThreadEndpoint(async (thread, request, env) => {
+  // Durable Objects
+  const agentBuilder = env.AGENT_BUILDER.get(env.AGENT_BUILDER.idFromName("singleton"));
+  const threadData = await agentBuilder.getThread(threadId);
+
+  // KV (if configured)
+  const cache = await env.MY_KV.get('cache-key');
+
+  // R2 (if configured)
+  const object = await env.MY_BUCKET.get('file.txt');
+
+  // ...
+});
+\`\`\`
+
+## Auto-Discovery
+
+Thread endpoints are **auto-discovered**:
+
+1. Vite plugin scans this directory on startup
+2. Generates virtual module with dynamic imports
+3. Routes registered in the main router
+4. HMR works in development
+
+No manual registration needed!
+
+## URL Structure
+
+All thread endpoints follow this pattern:
+
+\`\`\`
+/agents/api/threads/:id/{endpoint-name}
+\`\`\`
+
+Examples:
+- \`GET /agents/api/threads/abc-123/summary\`
+- \`POST /agents/api/threads/abc-123/export\`
+- \`PUT /agents/api/threads/abc-123/metadata\`
+
+The \`:id\` is automatically used to fetch the correct Durable Object.
+
+## Built-In Endpoints
+
+Standard Agents includes built-in thread endpoints (these are in the framework, not this directory):
+
+- \`GET /agents/api/threads/:id/messages\` - Get message history
+- \`POST /agents/api/threads/:id/messages\` - Send a message
+- \`DELETE /agents/api/threads/:id\` - Delete thread
+- \`GET /agents/api/threads/:id/logs\` - Get execution logs
+
+Your custom endpoints extend these built-in routes.
+
+## Best Practices
+
+1. **Descriptive Names**: Use clear endpoint names (e.g., \`summary\`, \`export\`)
+2. **Proper HTTP Methods**: Use GET for reads, POST for creates, etc.
+3. **Error Handling**: Always wrap in try/catch
+4. **Type Safety**: Use TypeScript interfaces for request/response
+5. **Performance**: Be mindful of SQLite query performance
+6. **Authentication**: Add auth checks if endpoints are sensitive
+7. **CORS**: Add CORS headers if accessed from browser
+
+## Testing
+
+Test endpoints with curl or any HTTP client:
+
+\`\`\`bash
+# GET summary
+curl http://localhost:8787/agents/api/threads/abc-123/summary
+
+# POST export
+curl -X POST http://localhost:8787/agents/api/threads/abc-123/export \\
+  -H "Content-Type: application/json" \\
+  -d '{"format": "json"}'
+\`\`\`
+
+## Limitations
+
+- No nested directories (endpoints must be directly in this folder)
+- Thread ID must be in URL path (handled automatically)
+- No support for multiple path parameters beyond thread ID
+- Response must be a Web API \`Response\` object
+
+## Related
+
+- **Tools**: \`agents/tools/CLAUDE.md\` - Custom tools
+- **Hooks**: \`agents/hooks/CLAUDE.md\` - Lifecycle hooks
+- **Built-in APIs**: \`packages/builder/src/api/\` - Framework endpoints
+- **Documentation**: Project root \`CLAUDE.md\` for architecture
+`;
+async function scaffold() {
+  const cwd = process.cwd();
+  logger.info("Scaffolding Standard Agents directories...");
+  const directories = [
+    {
+      path: path3.join(cwd, "agents", "tools"),
+      claudeMd: TOOLS_CLAUDE_MD,
+      name: "tools"
+    },
+    {
+      path: path3.join(cwd, "agents", "hooks"),
+      claudeMd: HOOKS_CLAUDE_MD,
+      name: "hooks"
+    },
+    {
+      path: path3.join(cwd, "agents", "api"),
+      claudeMd: API_CLAUDE_MD,
+      name: "api"
+    }
+  ];
+  let created = 0;
+  let skipped = 0;
+  for (const dir of directories) {
+    if (!fs.existsSync(dir.path)) {
+      fs.mkdirSync(dir.path, { recursive: true });
+      logger.success(`Created directory: agents/${dir.name}`);
+      created++;
+    } else {
+      logger.info(`Directory already exists: agents/${dir.name}`);
+    }
+    const claudeMdPath = path3.join(dir.path, "CLAUDE.md");
+    if (!fs.existsSync(claudeMdPath)) {
+      fs.writeFileSync(claudeMdPath, dir.claudeMd, "utf-8");
+      logger.success(`Created documentation: agents/${dir.name}/CLAUDE.md`);
+      created++;
+    } else {
+      logger.info(`Documentation already exists: agents/${dir.name}/CLAUDE.md (not overwriting)`);
+      skipped++;
+    }
+  }
+  logger.log("");
+  if (created > 0) {
+    logger.success(`Scaffolding complete! Created ${created} file(s).`);
+  }
+  if (skipped > 0) {
+    logger.info(`Skipped ${skipped} existing file(s).`);
+  }
+  logger.log("\nNext steps:");
+  logger.log("1. Read the CLAUDE.md files in each directory for detailed documentation");
+  logger.log("2. Create your first tool in agents/tools/");
+  logger.log("3. Add lifecycle hooks in agents/hooks/ (optional)");
+  logger.log("4. Create custom thread endpoints in agents/api/ (optional)");
+}
+
+// src/index.ts
+var program = new Command();
+program.name("agentbuilder").description("CLI tool for AgentBuilder initialization").version("0.0.0");
+program.command("init").description("Initialize AgentBuilder configuration in wrangler.jsonc").option("--force", "Overwrite existing configuration").action(init);
+program.command("scaffold").description("Create agentbuilder directories (tools, hooks, api) with documentation").action(scaffold);
+program.parse();
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map