@standardagents/cli 0.9.13 → 0.9.16

package/dist/index.js

@@ -28,214 +28,995 @@ var logger = {
     console.log(message);
   }
 };
-var WRANGLER_TEMPLATE = (name) => `{
-  "$schema": "node_modules/wrangler/config-schema.json",
-  "name": "${name}",
-  "main": "worker/index.ts",
-  "compatibility_date": "2025-01-01",
-  "compatibility_flags": ["nodejs_compat"],
-  "observability": {
-    "enabled": true
-  },
-  "assets": {
-    "directory": "dist",
-    "not_found_handling": "single-page-application",
-    "binding": "ASSETS",
-    "run_worker_first": ["/**"]
-  },
-  "durable_objects": {
-    "bindings": [
-      {
-        "name": "AGENT_BUILDER_THREAD",
-        "class_name": "DurableThread"
-      },
-      {
-        "name": "AGENT_BUILDER",
-        "class_name": "DurableAgentBuilder"
-      }
-    ]
-  },
-  "migrations": [
-    {
-      "tag": "v1",
-      "new_sqlite_classes": ["DurableThread"]
-    },
-    {
-      "tag": "v2",
-      "new_sqlite_classes": ["DurableAgentBuilder"]
-    }
-  ]
+
+// src/templates/root.ts
+var ROOT_CLAUDE_MD = `# Standard Agents
+
+This project uses Standard Agents - a framework for building AI agents on Cloudflare Workers.
+
+## Architecture Overview
+
+Standard Agents uses a **composition model** where four core components work together:
+
+\`\`\`
+Model \u2192 Prompt \u2192 Agent \u2192 Thread
+  \u2502        \u2502        \u2502        \u2502
+  \u2502        \u2502        \u2502        \u2514\u2500 Conversation instance (Durable Object)
+  \u2502        \u2502        \u2514\u2500 Orchestrates conversation flow
+  \u2502        \u2514\u2500 System instructions + tools
+  \u2514\u2500 LLM provider configuration
+\`\`\`
+
+**Models** define which LLM to use (provider, model ID, pricing, fallbacks).
+**Prompts** define what the LLM should do (system instructions, available tools).
+**Agents** orchestrate conversations (which prompt, stop conditions, turn limits).
+**Threads** are individual conversation instances with persistent storage.
+
+## How Components Compose
+
+### Basic Flow
+1. User creates a thread with an agent
+2. Agent uses its configured prompt
+3. Prompt specifies the model and tools
+4. LLM responds, potentially calling tools
+5. Tools execute and return results
+6. Loop continues until stop condition
+
+### Sub-Prompts (Prompts as Tools)
+Prompts can call other prompts as tools. This enables:
+- **Specialized reasoning**: A main prompt delegates to expert sub-prompts
+- **Structured outputs**: Sub-prompt validates and formats data
+- **Context isolation**: Sub-prompt gets fresh context without full history
+
+\`\`\`typescript
+// Main prompt can call 'data_extractor' as a tool
+definePrompt({
+  name: 'main_assistant',
+  tools: ['data_extractor'],  // Another prompt exposed as tool
+  // ...
+});
+\`\`\`
+
+### Agent Handoffs (Agents as Tools)
+Agents can delegate to other agents entirely:
+- **Specialization**: Route to domain-specific agents
+- **Escalation**: Hand off to more capable agents
+- **Workflows**: Chain agents for multi-step processes
+
+\`\`\`typescript
+defineAgent({
+  name: 'triage_agent',
+  exposeAsTool: true,
+  toolDescription: 'Hand off to triage for initial assessment',
+  // ...
+});
+\`\`\`
+
+## File Structure
+
+\`\`\`
+agents/
+\u251C\u2500\u2500 CLAUDE.md              # This file
+\u251C\u2500\u2500 Thread.ts              # Durable Object for conversation threads
+\u251C\u2500\u2500 AgentBuilder.ts        # Durable Object for metadata
+\u251C\u2500\u2500 agents/                # Agent definitions (defineAgent)
+\u2502   \u2514\u2500\u2500 CLAUDE.md
+\u251C\u2500\u2500 prompts/               # Prompt definitions (definePrompt)
+\u2502   \u2514\u2500\u2500 CLAUDE.md
+\u251C\u2500\u2500 models/                # Model configurations (defineModel)
+\u2502   \u2514\u2500\u2500 CLAUDE.md
+\u251C\u2500\u2500 tools/                 # Custom tools (defineTool)
+\u2502   \u2514\u2500\u2500 CLAUDE.md
+\u251C\u2500\u2500 hooks/                 # Lifecycle hooks (defineHook)
+\u2502   \u2514\u2500\u2500 CLAUDE.md
+\u2514\u2500\u2500 api/                   # Thread API endpoints (defineThreadEndpoint)
+    \u2514\u2500\u2500 CLAUDE.md
+\`\`\`
+
+Files are **auto-discovered** at runtime. No manual registration needed.
+
+## FlowState
+
+\`FlowState\` is the central state object available in tools and hooks:
+
+\`\`\`typescript
+interface FlowState {
+  thread: {
+    id: string;           // Thread identifier
+    instance: DurableThread;  // Durable Object instance
+  };
+  agent: AgentConfig;     // Current agent configuration
+  prompt: PromptConfig;   // Current prompt configuration
+  model: ModelConfig;     // Current model configuration
+  messages: Message[];    // Conversation history
+  env: Env;               // Cloudflare Worker environment
+  rootState: FlowState;   // Parent state (for sub-prompts)
 }
+\`\`\`
+
+Access in tools:
+\`\`\`typescript
+export default defineTool('...', schema, async (flow, args) => {
+  const threadId = flow.thread.id;
+  const messages = flow.messages;
+  // ...
+});
+\`\`\`
+
+## Quick Reference
+
+| Function | Purpose | Directory |
+|----------|---------|-----------|
+| \`defineModel()\` | Configure LLM provider | \`agents/models/\` |
+| \`definePrompt()\` | System instructions + tools | \`agents/prompts/\` |
+| \`defineAgent()\` | Conversation orchestration | \`agents/agents/\` |
+| \`defineTool()\` | Custom tool functions | \`agents/tools/\` |
+| \`defineHook()\` | Lifecycle interception | \`agents/hooks/\` |
+| \`defineThreadEndpoint()\` | Custom API routes | \`agents/api/\` |
+
+## Runtime Utilities
+
+Import from \`@standardagents/builder\`:
+
+\`\`\`typescript
+import {
+  queueTool,        // Queue another tool for execution
+  injectMessage,    // Add message without triggering execution
+  getMessages,      // Retrieve message history
+  emitThreadEvent,  // Send custom WebSocket events
+} from '@standardagents/builder';
+\`\`\`
+
+## Documentation
+
+Full documentation: https://docs.standardagentbuilder.com
+
+- [Architecture Overview](https://docs.standardagentbuilder.com/introduction/architecture)
+- [Models](https://docs.standardagentbuilder.com/core-concepts/models)
+- [Prompts](https://docs.standardagentbuilder.com/core-concepts/prompts)
+- [Agents](https://docs.standardagentbuilder.com/core-concepts/agents)
+- [Tools](https://docs.standardagentbuilder.com/core-concepts/tools)
+- [Hooks](https://docs.standardagentbuilder.com/core-concepts/hooks)
+- [FlowState](https://docs.standardagentbuilder.com/core-concepts/flowstate)
+- [Thread API](https://docs.standardagentbuilder.com/core-concepts/api)
 `;
-var THREAD_TS = `import { DurableThread } from 'virtual:@standardagents/builder'
 
-export default class Thread extends DurableThread {}
+// src/templates/models.ts
+var MODELS_CLAUDE_MD = `# Model Definitions
+
+Models define which LLM provider and model to use for prompts.
+
+## Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| \`name\` | \`string\` | Yes | Unique identifier for this model configuration |
+| \`provider\` | \`'openai' \\| 'anthropic' \\| 'openrouter' \\| 'google'\` | Yes | LLM provider |
+| \`model\` | \`string\` | Yes | Model ID sent to provider API |
+| \`fallbacks\` | \`string[]\` | No | Fallback model names to try if primary fails |
+| \`inputPrice\` | \`number\` | No | Cost per 1M input tokens (USD) |
+| \`outputPrice\` | \`number\` | No | Cost per 1M output tokens (USD) |
+| \`cachedPrice\` | \`number\` | No | Cost per 1M cached input tokens |
+| \`includedProviders\` | \`string[]\` | No | Provider prefixes for OpenRouter routing |
+
+## Example
+
+\`\`\`typescript
+import { defineModel } from '@standardagents/builder';
+
+export default defineModel({
+  name: 'gpt-4o',
+  provider: 'openai',
+  model: 'gpt-4o',
+  fallbacks: ['gpt-4-turbo', 'gpt-3.5-turbo'],
+  inputPrice: 2.5,
+  outputPrice: 10,
+});
+\`\`\`
+
+## Provider API Keys
+
+Set these environment variables in \`.dev.vars\` (local) or Cloudflare secrets (production):
+
+| Provider | Environment Variable |
+|----------|---------------------|
+| OpenAI | \`OPENAI_API_KEY\` |
+| Anthropic | \`ANTHROPIC_API_KEY\` |
+| OpenRouter | \`OPENROUTER_API_KEY\` |
+| Google | \`GOOGLE_API_KEY\` |
+
+## Fallback Strategy
+
+When a model fails, fallbacks are tried in order:
+1. Primary model (2 attempts)
+2. First fallback (2 attempts)
+3. Second fallback (2 attempts)
+4. ...and so on
+
+Retries occur on: network errors, rate limits (429), server errors (5xx), auth errors (401).
+
+## OpenRouter Configuration
+
+For OpenRouter, use the full model path:
+
+\`\`\`typescript
+export default defineModel({
+  name: 'claude-3-opus',
+  provider: 'openrouter',
+  model: 'anthropic/claude-3-opus',
+  includedProviders: ['anthropic'],  // Prefer Anthropic's servers
+});
+\`\`\`
+
+## Best Practices
+
+- **Name by use case**, not model ID (e.g., \`fast_reasoning\` not \`gpt-4o-mini\`)
+- **Configure fallbacks** for production reliability
+- **Set pricing** for cost tracking in logs
+- **Use environment variables** for API keys, never hardcode
+
+## Documentation
+
+Full reference: https://docs.standardagentbuilder.com/api-reference/define/model
 `;
-var AGENT_BUILDER_TS = `import { DurableAgentBuilder } from 'virtual:@standardagents/builder'
 
-export default class AgentBuilder extends DurableAgentBuilder {}
+// src/templates/prompts.ts
+var PROMPTS_CLAUDE_MD = `# Prompt Definitions
+
+Prompts define system instructions, model selection, and available tools for LLM interactions.
+
+## Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| \`name\` | \`string\` | Yes | Unique identifier for this prompt |
+| \`toolDescription\` | \`string\` | Yes | Description shown when used as a tool |
+| \`prompt\` | \`string \\| StructuredPrompt\` | Yes | System instructions |
+| \`model\` | \`string\` | Yes | Model name to use (references \`agents/models/\`) |
+| \`tools\` | \`(string \\| ToolConfig)[]\` | No | Available tools for LLM |
+| \`handoffAgents\` | \`string[]\` | No | Agents this prompt can hand off to |
+| \`includeChat\` | \`boolean\` | No | Include full conversation history |
+| \`includePastTools\` | \`boolean\` | No | Include previous tool results |
+| \`parallelToolCalls\` | \`boolean\` | No | Allow multiple concurrent tool calls |
+| \`toolChoice\` | \`'auto' \\| 'none' \\| 'required'\` | No | Tool calling strategy |
+| \`requiredSchema\` | \`z.ZodObject\` | No | Input validation when called as tool |
+| \`beforeTool\` | \`string\` | No | Tool to run before LLM request |
+| \`afterTool\` | \`string\` | No | Tool to run after LLM response |
+| \`reasoning\` | \`ReasoningConfig\` | No | Extended thinking configuration |
+
+## Basic Example
+
+\`\`\`typescript
+import { definePrompt } from '@standardagents/builder';
+
+export default definePrompt({
+  name: 'customer_support',
+  toolDescription: 'Handle customer support inquiries',
+  model: 'gpt-4o',
+  prompt: \`You are a helpful customer support agent.
+Always be polite and professional.
+If you cannot help, escalate to a human.\`,
+  tools: ['search_knowledge_base', 'create_ticket'],
+  includeChat: true,
+});
+\`\`\`
+
+## Structured Prompts
+
+Include other prompts for reusable instruction blocks:
+
+\`\`\`typescript
+export default definePrompt({
+  name: 'main_assistant',
+  toolDescription: 'Primary assistant',
+  model: 'gpt-4o',
+  prompt: [
+    { type: 'text', content: 'You are a helpful assistant.\\n\\n' },
+    { type: 'include', prompt: 'common_rules' },  // Includes another prompt
+    { type: 'text', content: '\\n\\nBe concise.' },
+  ],
+});
+\`\`\`
+
+## Tool Configuration
+
+Tools can be simple names or detailed configs:
+
+\`\`\`typescript
+tools: [
+  'simple_tool',  // Just the tool name
+  {
+    name: 'complex_tool',
+    includeTextResponse: true,   // Include sub-prompt text in result
+    includeToolCalls: false,     // Exclude sub-prompt tool calls
+    includeErrors: true,         // Include error details
+    initUserMessageProperty: 'query',  // Use this arg as initial message
+  },
+],
+\`\`\`
+
+## Input Validation
+
+Validate inputs when prompt is called as a tool:
+
+\`\`\`typescript
+import { z } from 'zod';
+
+export default definePrompt({
+  name: 'data_extractor',
+  toolDescription: 'Extract structured data from text',
+  model: 'gpt-4o',
+  prompt: 'Extract the requested data from the input.',
+  requiredSchema: z.object({
+    text: z.string().describe('Text to extract from'),
+    fields: z.array(z.string()).describe('Fields to extract'),
+  }),
+});
+\`\`\`
+
+## Extended Thinking (Reasoning)
+
+Enable for complex reasoning tasks:
+
+\`\`\`typescript
+export default definePrompt({
+  name: 'code_reviewer',
+  toolDescription: 'Review code for issues',
+  model: 'claude-3-opus',
+  prompt: 'Review the code thoroughly...',
+  reasoning: {
+    effort: 'high',      // 'low' | 'medium' | 'high'
+    maxTokens: 16000,    // Max thinking tokens
+    exclude: true,       // Don't include thinking in response
+  },
+});
+\`\`\`
+
+## Best Practices
+
+- **Write clear instructions** - Structure with headers and bullet points
+- **Describe tools thoroughly** - LLMs decide based on descriptions
+- **Validate inputs with Zod** - Catch errors early
+- **Use \`includeChat\`** for conversational context
+- **Name by purpose**, not model (e.g., \`support_agent\` not \`gpt4_prompt\`)
+
+## Documentation
+
+Full reference: https://docs.standardagentbuilder.com/api-reference/define/prompt
 `;
-var WORKER_INDEX = `import { router } from "virtual:@standardagents/builder"
-import DurableThread from '../agents/Thread';
-import DurableAgentBuilder from '../agents/AgentBuilder';
 
-export default {
-  async fetch(request, env) {
-    const res = await router(request, env)
-    return res ?? new Response(null, { status: 404 })
+// src/templates/agents.ts
+var AGENTS_CLAUDE_MD = `# Agent Definitions
+
+Agents orchestrate conversations by defining prompts, stop conditions, and turn limits.
+
+## Agent Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| \`name\` | \`string\` | Yes | Unique identifier for this agent |
+| \`type\` | \`'ai_human' \\| 'dual_ai'\` | No | Conversation type (default: \`ai_human\`) |
+| \`sideA\` | \`SideConfig\` | Yes | Configuration for side A (AI in ai_human) |
+| \`sideB\` | \`SideConfig\` | No | Configuration for side B (required for dual_ai) |
+| \`maxSessionTurns\` | \`number\` | No | Max total turns across both sides |
+| \`exposeAsTool\` | \`boolean\` | No | Allow other prompts to hand off to this agent |
+| \`toolDescription\` | \`string\` | No | Description when used as tool (required if exposeAsTool) |
+| \`tags\` | \`string[]\` | No | Tags for categorization and filtering |
+
+## Side Configuration
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| \`label\` | \`string\` | No | Display name for this side |
+| \`prompt\` | \`string\` | Yes | Prompt name to use (references \`agents/prompts/\`) |
+| \`stopOnResponse\` | \`boolean\` | No | Stop turn when LLM returns text (default: true) |
+| \`stopTool\` | \`string\` | No | Tool that stops this side's turn |
+| \`stopToolResponseProperty\` | \`string\` | No | Property to extract from stop tool result |
+| \`endConversationTool\` | \`string\` | No | Tool that ends the entire conversation |
+| \`maxTurns\` | \`number\` | No | Maximum turns for this side |
+| \`manualStopCondition\` | \`boolean\` | No | Enable custom stop handling via hooks |
+
+## Basic Example (AI-Human)
+
+\`\`\`typescript
+import { defineAgent } from '@standardagents/builder';
+
+export default defineAgent({
+  name: 'support_agent',
+  type: 'ai_human',
+  sideA: {
+    label: 'Support',
+    prompt: 'customer_support',
+    stopOnResponse: true,
+    endConversationTool: 'close_ticket',
+    maxTurns: 50,
   },
-} satisfies ExportedHandler<Env>
+  tags: ['support', 'tier-1'],
+});
+\`\`\`
 
-export { DurableThread, DurableAgentBuilder }
+## Dual-AI Example
+
+Two AI agents conversing (e.g., debate, iterative refinement):
+
+\`\`\`typescript
+export default defineAgent({
+  name: 'code_review_debate',
+  type: 'dual_ai',
+  maxSessionTurns: 20,
+  sideA: {
+    label: 'Reviewer',
+    prompt: 'code_reviewer',
+    stopOnResponse: true,
+  },
+  sideB: {
+    label: 'Developer',
+    prompt: 'code_defender',
+    stopOnResponse: true,
+  },
+});
+\`\`\`
+
+## Agent Handoffs
+
+Expose an agent for handoffs from other prompts:
+
+\`\`\`typescript
+export default defineAgent({
+  name: 'escalation_agent',
+  type: 'ai_human',
+  exposeAsTool: true,
+  toolDescription: 'Escalate to senior support for complex issues',
+  sideA: {
+    prompt: 'senior_support',
+  },
+});
+\`\`\`
+
+Other prompts can then include it in their \`handoffAgents\` array.
+
+## Stop Conditions (Priority Order)
+
+1. **endConversationTool** - Ends entire conversation (highest priority)
+2. **stopTool** - Ends current side's turn
+3. **maxTurns** - Ends side's participation when reached
+4. **stopOnResponse** - Ends turn when LLM returns text
+5. **maxSessionTurns** - Ends conversation (hard limit: 250)
+
+## Best Practices
+
+- **Use descriptive names** (\`customer_support_agent\` not \`agent1\`)
+- **Always set maxTurns** as a safety limit
+- **Match stop conditions to use case** - chat apps use stopOnResponse, workflows use stopTool
+- **Use labels** for clarity in logs and UI
+- **Organize with tags** for filtering
+
+## Documentation
+
+Full reference: https://docs.standardagentbuilder.com/api-reference/define/agent
 `;
-var TOOLS_CLAUDE_MD = `# Custom Tools
 
-This directory contains custom tools that your AI agents can call during execution.
+// src/templates/tools.ts
+var TOOLS_CLAUDE_MD = `# Custom Tools
 
-## What Are Tools?
+Tools extend agent capabilities beyond text generation. They allow LLMs to fetch data, perform calculations, execute side effects, and chain to other prompts or agents.
 
-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
+## Function Signature
 
-## Creating a Tool
+\`\`\`typescript
+defineTool(
+  description: string,           // What the tool does (shown to LLM)
+  args: z.ZodObject,             // Input validation schema
+  handler: (flow, args) => ToolResult,  // Implementation
+  returnSchema?: z.ZodObject     // Optional output schema
+)
+\`\`\`
 
-Create a new file in this directory:
+## Basic Example
 
 \`\`\`typescript
 import { defineTool } from '@standardagents/builder';
 import { z } from 'zod';
 
 export default defineTool(
-  'Description of what this tool does',
+  'Search the knowledge base for articles matching a query',
   z.object({
-    param1: z.string().describe('Description of param1'),
+    query: z.string().describe('Search query'),
+    limit: z.number().optional().default(10).describe('Max results'),
   }),
   async (flow, args) => {
-    // Tool implementation
+    const results = await searchKB(args.query, args.limit);
+    return {
+      status: 'success',
+      result: JSON.stringify(results),
+    };
+  }
+);
+\`\`\`
+
+## ToolResult Interface
+
+| Property | Type | Description |
+|----------|------|-------------|
+| \`status\` | \`'success' \\| 'error'\` | Whether the tool succeeded |
+| \`result\` | \`string\` | Tool output (required for success) |
+| \`error\` | \`string\` | Error message (for error status) |
+
+## FlowState Access
+
+The \`flow\` parameter provides access to:
+
+\`\`\`typescript
+async (flow, args) => {
+  // Thread information
+  const threadId = flow.thread.id;
+  const thread = flow.thread.instance;
+
+  // Configuration
+  const agentName = flow.agent.name;
+  const modelName = flow.model.name;
+
+  // Message history
+  const messages = flow.messages;
+
+  // Environment bindings
+  const env = flow.env;
+
+  // Parent state (for sub-prompts)
+  const root = flow.rootState;
+}
+\`\`\`
+
+## Tool Without Arguments
+
+\`\`\`typescript
+export default defineTool(
+  'Get current server time',
+  async (flow) => {
     return {
       status: 'success',
-      result: JSON.stringify({ data: 'result' })
+      result: new Date().toISOString(),
     };
   }
 );
 \`\`\`
 
-Tools are auto-discovered at runtime. No manual registration needed!
+## Error Handling
+
+Return errors gracefully instead of throwing:
+
+\`\`\`typescript
+export default defineTool(
+  'Fetch user data',
+  z.object({ userId: z.string() }),
+  async (flow, args) => {
+    try {
+      const user = await fetchUser(args.userId);
+      return { status: 'success', result: JSON.stringify(user) };
+    } catch (error) {
+      return {
+        status: 'error',
+        error: \`Failed to fetch user: \${error.message}\`,
+      };
+    }
+  }
+);
+\`\`\`
+
+## Queueing Additional Tools
+
+Queue another tool to run after the current one:
+
+\`\`\`typescript
+import { queueTool } from '@standardagents/builder';
+
+export default defineTool(
+  'Create order and send confirmation',
+  z.object({ items: z.array(z.string()) }),
+  async (flow, args) => {
+    const order = await createOrder(args.items);
+
+    // Queue email tool to run next
+    queueTool(flow, 'send_confirmation_email', {
+      orderId: order.id,
+      email: flow.thread.metadata.userEmail,
+    });
+
+    return { status: 'success', result: JSON.stringify(order) };
+  }
+);
+\`\`\`
+
+## Injecting Messages
+
+Add messages without triggering re-execution:
+
+\`\`\`typescript
+import { injectMessage } from '@standardagents/builder';
+
+export default defineTool(
+  'Log audit event',
+  z.object({ event: z.string() }),
+  async (flow, args) => {
+    await injectMessage(flow, {
+      role: 'system',
+      content: \`[AUDIT] \${args.event}\`,
+    });
+    return { status: 'success', result: 'Logged' };
+  }
+);
+\`\`\`
+
+## Best Practices
+
+- **Write clear descriptions** - LLMs decide tool usage based on descriptions
+- **Describe all parameters** with \`.describe()\` in Zod schemas
+- **Handle errors gracefully** - return error status, don't throw
+- **Use snake_case** for file names (\`search_knowledge_base.ts\`)
+- **Keep tools focused** - one task per tool
+- **Use \`flow.rootState\`** when queueing from sub-prompts
+
+## Supported Zod Types
+
+- Primitives: \`string\`, \`number\`, \`boolean\`, \`null\`
+- Enums: \`z.enum(['a', 'b', 'c'])\`
+- Arrays: \`z.array(z.string())\`
+- Objects: \`z.object({ ... })\`
+- Optional: \`z.string().optional()\`
+- Default: \`z.number().default(10)\`
+- Nullable: \`z.string().nullable()\`
+
+## Documentation
+
+Full reference: https://docs.standardagentbuilder.com/api-reference/define/tool
 `;
+
+// src/templates/hooks.ts
 var HOOKS_CLAUDE_MD = `# Lifecycle Hooks
 
-This directory contains lifecycle hooks that intercept and modify agent execution at key points.
+Hooks intercept and modify agent execution at specific lifecycle points.
+
+## Available Hooks
+
+| Hook | Signature | Purpose |
+|------|-----------|---------|
+| \`filter_messages\` | \`(state, rows) => Message[]\` | Filter raw message rows before LLM context |
+| \`prefilter_llm_history\` | \`(state, messages) => Message[]\` | Modify messages after filtering, before LLM |
+| \`before_create_message\` | \`(state, message) => Message\` | Modify message before database insert |
+| \`after_create_message\` | \`(state, message) => void\` | Run logic after message created |
+| \`before_update_message\` | \`(state, id, updates) => Updates\` | Modify updates before message update |
+| \`after_update_message\` | \`(state, message) => void\` | Run logic after message updated |
+| \`before_store_tool_result\` | \`(state, toolCall, result) => Result\` | Modify tool result before storage |
+| \`after_tool_call_success\` | \`(state, toolCall, result) => Result\` | Process successful tool execution |
+| \`after_tool_call_failure\` | \`(state, toolCall, result) => Result\` | Process failed tool execution |
+
+## File Naming
+
+Hook files **must** be named exactly as the hook type:
+
+\`\`\`
+agents/hooks/
+\u251C\u2500\u2500 filter_messages.ts
+\u251C\u2500\u2500 prefilter_llm_history.ts
+\u251C\u2500\u2500 before_create_message.ts
+\u251C\u2500\u2500 after_create_message.ts
+\u251C\u2500\u2500 before_update_message.ts
+\u251C\u2500\u2500 after_update_message.ts
+\u251C\u2500\u2500 before_store_tool_result.ts
+\u251C\u2500\u2500 after_tool_call_success.ts
+\u2514\u2500\u2500 after_tool_call_failure.ts
+\`\`\`
+
+## Examples
 
-## What Are Hooks?
+### Filter Messages (Limit Context)
 
-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.)
+\`\`\`typescript
+import { defineHook } from '@standardagents/builder';
 
-## Creating a Hook
+export default defineHook('filter_messages', async (state, rows) => {
+  // Only include last 20 messages
+  return rows.slice(-20);
+});
+\`\`\`
+
+### Prefilter LLM History (Modify Content)
 
 \`\`\`typescript
 import { defineHook } from '@standardagents/builder';
 
 export default defineHook('prefilter_llm_history', async (state, messages) => {
-  // Filter or modify messages before sending to LLM
-  return messages;
+  // Remove sensitive data from message content
+  return messages.map(msg => ({
+    ...msg,
+    content: msg.content?.replace(/\\b\\d{4}-\\d{4}-\\d{4}-\\d{4}\\b/g, '[REDACTED]'),
+  }));
+});
+\`\`\`
+
+### Before Create Message (Add Metadata)
+
+\`\`\`typescript
+import { defineHook } from '@standardagents/builder';
+
+export default defineHook('before_create_message', async (state, message) => {
+  return {
+    ...message,
+    metadata: {
+      ...message.metadata,
+      createdAt: Date.now(),
+      agentVersion: '1.0.0',
+    },
+  };
+});
+\`\`\`
+
+### After Tool Call Success (Logging)
+
+\`\`\`typescript
+import { defineHook } from '@standardagents/builder';
+
+export default defineHook('after_tool_call_success', async (state, toolCall, result) => {
+  console.log(\`Tool \${toolCall.function.name} succeeded:\`, result);
+  return result;  // Return result unchanged, or modify it
+});
+\`\`\`
+
+### After Tool Call Failure (Recovery)
+
+\`\`\`typescript
+import { defineHook } from '@standardagents/builder';
+
+export default defineHook('after_tool_call_failure', async (state, toolCall, result) => {
+  // Override error with fallback result
+  if (toolCall.function.name === 'fetch_weather') {
+    return {
+      status: 'success',
+      result: JSON.stringify({ temp: 'unavailable', fallback: true }),
+    };
+  }
+  return result;  // Return original error
 });
 \`\`\`
 
-Hook files must be named exactly as the hook type (e.g., \`prefilter_llm_history.ts\`).
+## Hook Categories
+
+**Transformation hooks** (return modified data):
+- \`filter_messages\`
+- \`prefilter_llm_history\`
+- \`before_create_message\`
+- \`before_update_message\`
+- \`before_store_tool_result\`
+- \`after_tool_call_success\`
+- \`after_tool_call_failure\`
+
+**Event hooks** (side effects only):
+- \`after_create_message\`
+- \`after_update_message\`
+
+## Best Practices
+
+- **Keep hooks fast** - target <100ms execution
+- **Wrap in try-catch** - hooks continue on error
+- **Validate input data** before processing
+- **Document purpose** with clear comments
+- **Use for cross-cutting concerns** - logging, redaction, enrichment
+
+## Documentation
+
+Full reference: https://docs.standardagentbuilder.com/api-reference/define/hook
 `;
+
+// src/templates/api.ts
 var API_CLAUDE_MD = `# Thread-Specific API Endpoints
 
-This directory contains custom API endpoints that operate on specific threads.
+Define custom API endpoints that operate on specific threads with access to the thread's Durable Object instance and SQLite storage.
 
-## What Are Thread Endpoints?
+## File-Based Routing
 
-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 Pattern | HTTP Method | Route |
+|--------------|-------------|-------|
+| \`name.ts\` | GET | \`/api/threads/:id/name\` |
+| \`name.get.ts\` | GET | \`/api/threads/:id/name\` |
+| \`name.post.ts\` | POST | \`/api/threads/:id/name\` |
+| \`name.put.ts\` | PUT | \`/api/threads/:id/name\` |
+| \`name.delete.ts\` | DELETE | \`/api/threads/:id/name\` |
+| \`nested/route.ts\` | GET | \`/api/threads/:id/nested/route\` |
 
-## Creating an Endpoint
+## Basic Example
 
 \`\`\`typescript
-// agents/api/summary.get.ts -> GET /agents/api/threads/:id/summary
+// agents/api/status.get.ts -> GET /api/threads/:id/status
 import { defineThreadEndpoint } from '@standardagents/builder';
 
 export default defineThreadEndpoint(async (thread, request, env) => {
   const messages = await thread.getMessages();
-  return new Response(JSON.stringify({ count: messages.length }), {
-    headers: { 'Content-Type': 'application/json' }
+  return new Response(JSON.stringify({
+    messageCount: messages.length,
+    status: 'active',
+  }), {
+    headers: { 'Content-Type': 'application/json' },
   });
 });
 \`\`\`
 
-Pattern: \`{name}.{method}.ts\` (e.g., \`summary.get.ts\`, \`export.post.ts\`)
-`;
-var AGENTS_CLAUDE_MD = `# Agent Definitions
+## Handler Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| \`thread\` | \`DurableThread\` | The thread's Durable Object instance |
+| \`request\` | \`Request\` | The incoming HTTP request |
+| \`env\` | \`Env\` | Cloudflare Worker environment bindings |
 
-This directory contains your AI agent definitions.
+## Thread Methods
 
-## Creating an Agent
+Access thread data through the instance:
 
 \`\`\`typescript
-import { defineAgent } from '@standardagents/builder';
+export default defineThreadEndpoint(async (thread, request, env) => {
+  // Message operations
+  const messages = await thread.getMessages({ limit: 100, offset: 0 });
+  const count = await thread.getMessageCount();
 
-export default defineAgent({
-  name: 'my-agent',
-  type: 'ai_human',
-  title: 'My Agent',
-  defaultPrompt: 'my-prompt',
-  defaultModel: 'gpt-4o',
-  tools: ['my_tool'],
+  // Thread metadata
+  const metadata = thread.getMetadata();
+
+  // Execution control
+  await thread.stop();
+
+  // Custom SQL queries
+  const result = thread.ctx.storage.sql.exec(\`
+    SELECT * FROM messages WHERE role = 'user'
+  \`);
 });
 \`\`\`
 
-Agent types:
-- \`ai_human\`: Human interacts with AI agent
-- \`dual_ai\`: Two AI agents interact with each other
-`;
-var PROMPTS_CLAUDE_MD = `# Prompt Definitions
+## POST with Request Body
 
-This directory contains your prompt/system message definitions.
+\`\`\`typescript
+// agents/api/export.post.ts -> POST /api/threads/:id/export
+import { defineThreadEndpoint } from '@standardagents/builder';
 
-## Creating a Prompt
+export default defineThreadEndpoint(async (thread, request, env) => {
+  const body = await request.json();
+  const { format = 'json' } = body;
 
-\`\`\`typescript
-import { definePrompt } from '@standardagents/builder';
+  const messages = await thread.getMessages();
 
-export default definePrompt({
-  name: 'my-prompt',
-  model: 'gpt-4o',
-  systemPrompt: 'You are a helpful assistant...',
-  tools: ['search', 'calculate'],
+  if (format === 'csv') {
+    const csv = messages.map(m => \`\${m.role},\${m.content}\`).join('\\n');
+    return new Response(csv, {
+      headers: { 'Content-Type': 'text/csv' },
+    });
+  }
+
+  return new Response(JSON.stringify(messages), {
+    headers: { 'Content-Type': 'application/json' },
+  });
 });
 \`\`\`
-`;
-var MODELS_CLAUDE_MD = `# Model Definitions
 
-This directory contains your AI model configurations.
+## Nested Routes
 
-## Creating a Model
+Create directories for nested routes:
+
+\`\`\`
+agents/api/
+\u251C\u2500\u2500 status.get.ts           -> GET /api/threads/:id/status
+\u251C\u2500\u2500 export.post.ts          -> POST /api/threads/:id/export
+\u2514\u2500\u2500 messages/
+    \u251C\u2500\u2500 count.ts            -> GET /api/threads/:id/messages/count
+    \u2514\u2500\u2500 search.post.ts      -> POST /api/threads/:id/messages/search
+\`\`\`
+
+## Error Handling
 
 \`\`\`typescript
-import { defineModel } from '@standardagents/builder';
+export default defineThreadEndpoint(async (thread, request, env) => {
+  try {
+    const data = await riskyOperation();
+    return new Response(JSON.stringify(data), {
+      headers: { 'Content-Type': 'application/json' },
+    });
+  } catch (error) {
+    return new Response(JSON.stringify({
+      error: error.message,
+    }), {
+      status: 500,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+});
+\`\`\`
 
-export default defineModel({
-  name: 'gpt-4o',
-  model: 'gpt-4o',
-  provider: 'openai',
-  inputPrice: 2.5,
-  outputPrice: 10,
+## Using Environment Variables
+
+\`\`\`typescript
+export default defineThreadEndpoint(async (thread, request, env) => {
+  // Access secrets and bindings
+  const apiKey = env.EXTERNAL_API_KEY;
+  const kv = env.MY_KV_NAMESPACE;
+
+  const data = await fetchExternalAPI(apiKey);
+  await kv.put(\`thread:\${thread.id}\`, JSON.stringify(data));
+
+  return new Response('OK');
 });
 \`\`\`
 
-Supported providers: \`openai\`, \`anthropic\`, \`openrouter\`, \`google\`
+## Best Practices
+
+- **Keep handlers fast** - endpoints are in the request path
+- **Paginate large queries** - use limit/offset for messages
+- **Validate input data** - check request body before processing
+- **Use descriptive file names** - \`export.post.ts\` not \`ep1.ts\`
+- **Return proper status codes** - 200, 400, 404, 500
+
+## Documentation
+
+Full reference: https://docs.standardagentbuilder.com/core-concepts/api
+`;
+
+// src/commands/scaffold.ts
+var WRANGLER_TEMPLATE = (name) => `{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "${name}",
+  "main": "worker/index.ts",
+  "compatibility_date": "2025-01-01",
+  "compatibility_flags": ["nodejs_compat"],
+  "observability": {
+    "enabled": true
+  },
+  "assets": {
+    "directory": "dist",
+    "not_found_handling": "single-page-application",
+    "binding": "ASSETS",
+    "run_worker_first": ["/**"]
+  },
+  "durable_objects": {
+    "bindings": [
+      {
+        "name": "AGENT_BUILDER_THREAD",
+        "class_name": "DurableThread"
+      },
+      {
+        "name": "AGENT_BUILDER",
+        "class_name": "DurableAgentBuilder"
+      }
+    ]
+  },
+  "migrations": [
+    {
+      "tag": "v1",
+      "new_sqlite_classes": ["DurableThread"]
+    },
+    {
+      "tag": "v2",
+      "new_sqlite_classes": ["DurableAgentBuilder"]
+    }
+  ]
+}
+`;
+var THREAD_TS = `import { DurableThread } from 'virtual:@standardagents/builder'
+
+export default class Thread extends DurableThread {}
+`;
+var AGENT_BUILDER_TS = `import { DurableAgentBuilder } from 'virtual:@standardagents/builder'
+
+export default class AgentBuilder extends DurableAgentBuilder {}
+`;
+var WORKER_INDEX = `import { router } from "virtual:@standardagents/builder"
+import DurableThread from '../agents/Thread';
+import DurableAgentBuilder from '../agents/AgentBuilder';
+
+export default {
+  async fetch(request, env) {
+    const res = await router(request, env)
+    return res ?? new Response(null, { status: 404 })
+  },
+} satisfies ExportedHandler<Env>
+
+export { DurableThread, DurableAgentBuilder }
 `;
 function getProjectName(cwd) {
   const packageJsonPath = path.join(cwd, "package.json");
@@ -313,13 +1094,12 @@ async function modifyViteConfig(configPath, force) {
   }
 }
 function createOrUpdateWranglerConfig(cwd, projectName, force) {
-  var _a, _b;
   const existingConfig = findWranglerConfig(cwd);
   if (existingConfig && !force) {
     try {
       const text = fs.readFileSync(existingConfig, "utf-8");
       const config = parse(text);
-      const hasBindings = (_b = (_a = config.durable_objects) == null ? void 0 : _a.bindings) == null ? void 0 : _b.some(
+      const hasBindings = config.durable_objects?.bindings?.some(
         (b) => b.name === "AGENT_BUILDER_THREAD" || b.name === "AGENT_BUILDER"
       );
       if (hasBindings) {
@@ -485,6 +1265,12 @@ function createDurableObjects(cwd) {
   }
 }
 function createDirectoriesAndDocs(cwd) {
+  const agentsDir = path.join(cwd, "agents");
+  const rootDocPath = path.join(agentsDir, "CLAUDE.md");
+  if (!fs.existsSync(rootDocPath)) {
+    fs.writeFileSync(rootDocPath, ROOT_CLAUDE_MD, "utf-8");
+    logger.success("Created agents/CLAUDE.md");
+  }
   const directories = [
     { path: "agents/agents", doc: AGENTS_CLAUDE_MD },
     { path: "agents/prompts", doc: PROMPTS_CLAUDE_MD },
@@ -507,7 +1293,6 @@ function createDirectoriesAndDocs(cwd) {
   }
 }
 function updateTsConfig(cwd) {
-  var _a;
   const tsconfigPath = path.join(cwd, "tsconfig.json");
   if (!fs.existsSync(tsconfigPath)) {
     logger.info("No tsconfig.json found, skipping TypeScript configuration");
@@ -517,7 +1302,7 @@ function updateTsConfig(cwd) {
     const text = fs.readFileSync(tsconfigPath, "utf-8");
     const config = parse(text);
     let result = text;
-    const types = ((_a = config.compilerOptions) == null ? void 0 : _a.types) || [];
+    const types = config.compilerOptions?.types || [];
     const newTypes = [
       "./worker-configuration.d.ts",
       "./.agents/types.d.ts",
@@ -604,6 +1389,7 @@ async function scaffold(options = {}) {
   logger.log("Your project structure:");
   logger.log("");
   logger.log("  agents/");
+  logger.log("  \u251C\u2500\u2500 CLAUDE.md           # Architecture documentation");
   logger.log("  \u251C\u2500\u2500 Thread.ts           # Durable Object for threads");
   logger.log("  \u251C\u2500\u2500 AgentBuilder.ts     # Durable Object for agent state");
   logger.log("  \u251C\u2500\u2500 agents/             # Agent definitions");