@standardagents/agentbuilder-template 0.0.1-dev.fffff

package/dist/index.js

@@ -0,0 +1,1733 @@
+// src/docs/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.
+
+## ThreadState
+
+\`ThreadState\` is the state object available in tools and hooks:
+
+\`\`\`typescript
+interface ThreadState {
+  // Identity (readonly)
+  threadId: string;           // Thread identifier
+  agentId: string;            // Agent identifier
+  userId: string | null;      // User identifier (if set)
+  createdAt: number;          // Creation timestamp
+  children: SubagentRegistryEntry[]; // Resumable child registry
+  terminated: number | null;  // Soft-termination timestamp
+
+  // Methods
+  getMessages(options?): Promise<MessagesResult>;  // Get conversation history
+  injectMessage(input): Promise<Message>;          // Add message to thread
+  queueMessage(input): Promise<void>;              // Queue message for next step
+  loadModel(name): Promise<ModelConfig>;           // Load model definition
+  loadPrompt(name): Promise<PromptConfig>;         // Load prompt definition
+  loadAgent(name): Promise<AgentConfig>;           // Load agent definition
+  env(propertyName): Promise<string>;              // Resolve env value for this thread
+  setEnv(propertyName, value): Promise<void>;      // Set thread env + propagate to active descendants
+  getValue<T = unknown>(key: string): Promise<T | null>; // Read durable per-thread JSON value
+  setValue(key: string, value: unknown): Promise<void>;  // Write durable value; null/undefined deletes
+  notifyParent(content): Promise<void>;            // Explicitly queue a silent message to the parent
+  setStatus(status): Promise<void>;                // Update this child in the parent registry
+  getChildThread(referenceId): Promise<ThreadState | null>; // Resolve child thread
+  getParentThread(): Promise<ThreadState | null>;            // Resolve parent thread
+  terminate(): Promise<void>;                      // Soft-terminate thread
+  runCode(source, options?): CodeExecution;        // Run JS/TS in a fresh Dynamic Worker sandbox
+}
+\`\`\`
+
+\`runCode\` has no implicit access to thread state, filesystem, network, timers, or host globals. Bridge only the exact capabilities needed through \`imports\` or \`globals\`; use \`modules\` for local relative ES modules; use \`execute\` to select the export and args to run. \`modules\` keys are graph-root relative paths; entry-source imports resolve from \`filename\` when supplied, including \`../\` parent paths that stay inside the supplied graph. TypeScript input is accepted by default and erased before evaluation. In thread endpoints, \`runCode\` is forwarded into the thread Durable Object; pass plain transferable options there and keep function-backed bridges in tools or in-thread execution contexts.
+
+## Subagents
+
+\`dual_ai\` agents can be used as subagents from prompt tool configs:
+
+- Each subagent runs in its own thread (\`DurableThread\`)
+- Parent/child linkage is tracked in thread metadata
+- Resumable children are visible in \`state.children\`
+- Parent threads create/message resumable children via built-ins (\`subagent_create\`, \`subagent_message\`)
+- Child completion results are queued back to the parent when \`parentCommunication\` is \`implicit\`
+- Explicit relationships can stay idle until code calls \`state.notifyParent()\` or \`state.setStatus()\`
+
+Access in tools:
+\`\`\`typescript
+export default defineTool('...', schema, async (state, args) => {
+  const threadId = state.threadId;
+  const { messages } = await state.getMessages();
+  const count = (await state.getValue<number>('invocation_count')) ?? 0;
+  await state.setValue('invocation_count', count + 1);
+  // ...
+});
+\`\`\`
+
+Access in hooks:
+\`\`\`typescript
+export default defineHook({
+  hook: 'before_create_message',
+  id: 'my_hook',
+  execute: async (state, message) => {
+    console.log(\`Thread: \${state.threadId}, Agent: \${state.agentId}\`);
+    return message;
+  }
+});
+\`\`\`
+
+## 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)
+- [ThreadState](https://docs.standardagentbuilder.com/core-concepts/threadstate)
+- [Thread API](https://docs.standardagentbuilder.com/core-concepts/api)
+`;
+
+// src/docs/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' \\| 'cerebras' \\| 'groq' \\| 'xai'\` | 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 |
+| \`providerTools\` | \`string[]\` | No | Provider-built-in tool names to make available for prompts using this model |
+
+## Example
+
+\`\`\`typescript
+import { defineModel } from '@standardagents/builder';
+
+export default defineModel({
+  name: 'default',
+  provider: 'openrouter',
+  model: 'google/gemini-3-flash-preview',
+  fallbacks: ['fast', 'cheap-heavy'],
+});
+\`\`\`
+
+## Provider Tools
+
+Providers can expose built-in tools such as search, file search, code execution,
+or provider-specific tools through their \`getTools()\` implementation. Enable the
+provider tool names on the model with \`providerTools\`; prompts can then include
+those tools like normal tool names. Provider tools execute on the upstream
+provider, not in AgentBuilder, and successful calls are logged as provider tool
+entries.
+
+OpenRouter exposes \`web_search\`, \`web_fetch\`, \`datetime\`, and \`image_generation\`
+as provider-executed server tools. Configure optional OpenRouter parameters with
+\`providerOptions.serverTools\` on the model.
+
+## Recommended Models (OpenRouter)
+
+| Use Case | Model ID | Description |
+|----------|----------|-------------|
+| Fast/Cheap | \`z-ai/glm-4.5-air\` | Quick responses, low cost |
+| Mid-tier | \`google/gemini-3-flash-preview\` | Good balance of speed and quality |
+| Cheap Heavy | \`z-ai/glm-4.7\` | More capable, still affordable |
+| Heavy | \`google/gemini-3-pro-preview\` | Most capable, for complex tasks |
+
+**\u26A0\uFE0F Google Models**: When using Google models (\`google/gemini-*\`), you must enable \`reasoning\` in your prompt configuration or tool calls will fail. See the prompts CLAUDE.md for details.
+
+## Provider API Keys
+
+Set these environment variables in \`.dev.vars\` (local) or Cloudflare secrets (production):
+
+| Provider | Environment Variable |
+|----------|---------------------|
+| Cerebras | \`CEREBRAS_API_KEY\` |
+| Groq | \`GROQ_API_KEY\` |
+| OpenAI | \`OPENAI_API_KEY\` |
+| Anthropic | \`ANTHROPIC_API_KEY\` |
+| OpenRouter | \`OPENROUTER_API_KEY\` |
+| Google | \`GOOGLE_API_KEY\` |
+| xAI | \`XAI_API_KEY\` |
+
+If \`STANDARD_AGENTS_API_KEY\` is present and a provider-specific key is not set,
+first-party Standard Agents providers route through the hosted Standard Agents
+router. Setting a provider-specific key always uses that provider directly.
+
+## 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: 'heavy',
+  provider: 'openrouter',
+  model: 'google/gemini-3-pro-preview',
+  includedProviders: ['google'],  // Prefer Google's servers
+});
+\`\`\`
+
+## Best Practices
+
+- **Name by use case**, not model ID (e.g., \`fast\`, \`default\`, \`heavy\`)
+- **Configure fallbacks** for production reliability
+- **Set pricing** for cost tracking in logs when your provider or runtime does not supply it automatically
+- **Cerebras note:** documented Cerebras models have built-in fallback pricing for request logs, but custom/private Cerebras models should still set \`inputPrice\` and \`outputPrice\`
+- **Use environment variables** for API keys, never hardcode
+
+## Documentation
+
+Full reference: https://docs.standardagentbuilder.com/api-reference/define/model
+`;
+
+// src/docs/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 \\| SubagentToolConfig)[]\` | No | Available tools (include ai_human agent names for handoffs and dual_ai subagent configs) |
+| \`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 |
+| \`variables\` | \`VariableDefinition[]\` | No | Variable declarations (\`name\`, \`type\`, \`required\`, \`scoped\`, \`description\`) |
+| \`env\` | \`Record<string, string>\` | No | Prompt-level default values for variables |
+| \`hooks\` | \`string[]\` | No | Hook IDs to run for this prompt (overrides agent hooks) |
+| \`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: 'default',
+  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: 'default',
+  prompt: [
+    { type: 'text', content: 'You are a helpful assistant.\\n\\n' },
+    { type: 'include', prompt: 'common_rules' },  // Includes another prompt
+    { type: 'env', property: 'ASSISTANT_TONE' },  // Inject variable value
+    { type: 'text', content: '\\n\\nBe concise.' },
+  ],
+});
+\`\`\`
+
+\`type: 'env'\` inserts a resolved thread variable value. Use this only for non-secret values that are safe to expose to the LLM.
+
+The sandboxed coding prompt declares \`HTTP_HOST\` as a text variable. Its URL helper uses that value as the origin for files exposed from the thread \`public/\` directory and endpoints exposed from the thread \`api/\` directory. Public URLs should usually omit extensions; extensionless public paths resolve \`.html\`, then \`.js\`, then \`.ts\`, then matching \`index\` files in the same order. Browser pages should reference only public files, \`api/\` endpoints, or absolute external URLs, using relative asset URLs like \`./app\` and \`./api/todos\`; private \`src/\` files are not served directly. Public \`.ts\` files are transformed to browser JavaScript and are not server endpoints. Server-side endpoints live under the thread filesystem \`api/\` directory, and the \`api/\` directory name stays in the public URL: \`api/todo.ts\` is \`/api/threads/{threadId}/api/todo\`, while \`api/todo.ts\` is not \`/api/threads/{threadId}/todo\` or \`/api/threads/{threadId}/todos\`. Endpoint files default-export a function that accepts \`Request\` and returns \`Response\` or \`Promise<Response>\`. Endpoint code can import \`fetch\`, \`fs\`, and \`storage\`, and can import private helpers with relative paths such as \`../src/todo.ts\`. When the coding agent creates a site, page, or endpoint, it should call \`get_public_url\` with the created file path and use the returned URL.
+
+Sandboxed code and \`api/\` endpoints can persist small JSON-serializable runtime data through \`import { storage } from "storage"\`. Use \`storage.get\`, \`storage.set\`, \`storage.delete\`, and \`storage.has\` with stable logical keys. Do not expose, mention, or depend on internal storage key prefixes.
+
+The sandboxed coding prompt includes \`delete_file\` for removing files or empty directories from the thread filesystem. Use it to clean up obsolete implementation files, stale public assets, and abandoned endpoint routes after the replacement is working.
+
+## 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
+  },
+],
+\`\`\`
+
+Provider-built-in tools use the same \`tools\` list once the selected model enables
+them with \`providerTools\`. AgentBuilder passes them to the provider and records
+provider-reported calls in request logs; it does not execute those tools locally.
+Generated prompt files may store these selections as \`provider:<toolName>\` to
+distinguish provider tools from local tools with the same name.
+
+### Subagent Tool Configuration
+
+Use \`SubagentToolConfig\` when the tool is a \`dual_ai\` agent:
+
+\`\`\`typescript
+tools: [
+  // Blocking, non-resumable (default)
+  { name: 'data_processor_agent' },
+
+  // Non-blocking, resumable with a single instance
+  {
+    name: 'browser_agent',
+    blocking: false,
+    immediate: {
+      nameEnv: 'BROWSER_AGENT_NAME',
+      descriptionEnv: 'BROWSER_AGENT_DESCRIPTION',
+      scopedEnv: ['BROWSER_AGENT_API_KEY'],
+    },
+    optional: 'ENABLE_BROWSER_AGENT',
+    initAgentNameProperty: 'name',
+    resumable: {
+      receives_messages: 'side_a',
+      maxInstances: 1,
+      parentCommunication: 'explicit',
+    },
+  },
+]
+\`\`\`
+
+When prompt-configured resumable dual_ai subagents exist, the runtime auto-injects:
+- \`subagent_create\` for spawning new child instances
+- \`subagent_message\` for messaging active resumable instances
+
+\`subagent_create\` requires a non-empty \`name\` for human-friendly child thread labels.
+AgentBuilder stores that argument as a \`name:<value>\` thread tag.
+
+Set \`immediate: true\` to run a tool automatically when the prompt activates.
+Use \`immediate: { nameEnv, descriptionEnv, scopedEnv }\` when you want safe per-instance bootstrap hints while keeping copied scoped env runtime-only.
+Set \`optional: 'ENV_NAME'\` to enable a subagent branch only when env resolves to \`true\`, \`1\`, or \`yes\`.
+Set \`resumable.parentCommunication: 'explicit'\` when the child should stay quiet until its own tools or hooks call \`state.notifyParent()\` or \`state.setStatus()\`.
+If required scoped vars are missing, the runtime returns \`error_code: "subagent_env_required"\` with a temporary \`GET/POST /api/threads/:threadId/variables/:requestId\` endpoint in \`error_data.endpoint\`.
+
+## 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: 'default',
+  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: 'heavy',
+  prompt: 'Review the code thoroughly...',
+  reasoning: {
+    effort: 'high',      // 'low' | 'medium' | 'high'
+    maxTokens: 16000,    // Max thinking tokens
+    exclude: true,       // Don't include thinking in response
+  },
+});
+\`\`\`
+
+**\u26A0\uFE0F Google Models Require Reasoning**: When using Google models (\`google/gemini-*\`) via OpenRouter, you **must** include \`reasoning\` configuration or tool calls will fail. At minimum:
+
+\`\`\`typescript
+reasoning: {
+  effort: 'low',  // Can be 'low', 'medium', or 'high'
+},
+\`\`\`
+
+## Hooks
+
+Attach lifecycle hooks to a prompt:
+
+\`\`\`typescript
+export default definePrompt({
+  name: 'customer_support',
+  toolDescription: 'Handle customer support',
+  model: 'default',
+  prompt: 'You are a support agent...',
+  hooks: ['limit_to_20', 'redact_pii'],  // Hook IDs from agents/hooks/
+});
+\`\`\`
+
+Prompt hooks take precedence over agent hooks. See \`agents/hooks/CLAUDE.md\` for details.
+
+## 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
+`;
+
+// src/docs/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) |
+| \`env\` | \`Record<string, string>\` | No | Agent-level default variable values |
+| \`hooks\` | \`string[]\` | No | Hook IDs to run for this agent (fallback if prompt has no hooks) |
+| \`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 |
+| \`maxSteps\` | \`number\` | No | Maximum step budget for this side |
+| \`sessionStop\` | \`string \\| SessionToolBinding\` | No | Terminal success lifecycle binding |
+| \`sessionFail\` | \`string \\| SessionToolBinding\` | No | Terminal failure lifecycle binding |
+| \`sessionStatus\` | \`string \\| SessionToolBinding\` | No | Non-terminal status lifecycle binding |
+| \`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,
+    sessionStop: 'close_ticket',
+    maxSteps: 50,
+  },
+  tags: ['support', 'tier-1'],
+});
+\`\`\`
+
+## 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,
+  },
+});
+\`\`\`
+
+## Dual-AI Subagent Pattern
+
+When a \`dual_ai\` agent is used as a subagent tool, a common split is:
+- **sideA**: performs work (tools, data gathering, execution)
+- **sideB**: reflection, verification, and quality checks
+
+\`\`\`typescript
+export default defineAgent({
+  name: 'research_subagent',
+  type: 'dual_ai',
+  exposeAsTool: true,
+  toolDescription: 'Researches and validates findings autonomously',
+  maxSessionTurns: 16,
+  sideA: {
+    label: 'Worker',
+    prompt: 'research_worker',
+    sessionStatus: 'set_subagent_status',
+    sessionFail: 'fail_research_subagent',
+    sessionStop: 'finish_subagent',
+  },
+  sideB: {
+    label: 'Reviewer',
+    prompt: 'research_reviewer',
+    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 the agent name in their \`tools\` array to enable handoffs.
+
+## Stop Conditions (Priority Order)
+
+1. **sessionFail** - Ends entire conversation with a terminal failure
+2. **sessionStop** - Ends entire conversation successfully
+3. **stopTool** - Ends current side's turn
+4. **maxSteps** - Ends side execution when the safety budget is reached
+5. **stopOnResponse** - Ends turn when LLM returns text
+6. **maxSessionTurns** - Ends conversation (hard limit: 250)
+
+## Hooks
+
+Attach lifecycle hooks at the agent level:
+
+\`\`\`typescript
+export default defineAgent({
+  name: 'support_agent',
+  type: 'ai_human',
+  hooks: ['log_all_messages', 'sanitize_results'],
+  sideA: {
+    prompt: 'customer_support',
+  },
+});
+\`\`\`
+
+Agent hooks run as a fallback when the active prompt has no hooks defined. Prompt hooks always take precedence. See \`agents/hooks/CLAUDE.md\` for details.
+
+## Naming Convention
+
+Agent names **must** end with the \`_agent\` suffix (e.g., \`support_agent\`, \`research_agent\`).
+This convention is enforced by the builder UI and makes agents easily identifiable in logs and code.
+
+## Best Practices
+
+- **Use descriptive names** (\`customer_support_agent\` not \`agent1\`)
+- **Always use the _agent suffix** - names like \`support_agent\`, \`research_agent\`
+- **Always set maxSteps or maxSessionTurns** as safety limits
+- **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
+`;
+
+// src/docs/tools.ts
+var TOOLS_CLAUDE_MD = `# Custom 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.
+
+## Function Signature
+
+\`\`\`typescript
+defineTool({
+  description: string,           // What the tool does (shown to LLM)
+  args?: z.ZodObject,            // Input validation schema (optional)
+  execute: (state, args) => ToolResult,  // Implementation
+  variables?: VariableDefinition[], // Declared variables (optional)
+})
+\`\`\`
+
+## Basic Example
+
+\`\`\`typescript
+import { defineTool } from '@standardagents/builder';
+import { z } from 'zod';
+
+export default defineTool({
+  description: 'Search the knowledge base for articles matching a query',
+  args: z.object({
+    query: z.string().describe('Search query'),
+    limit: z.number().optional().default(10).describe('Max results'),
+  }),
+  execute: async (state, args) => {
+    const results = await searchKB(args.query, args.limit);
+    return {
+      status: 'success',
+      result: JSON.stringify(results),
+    };
+  },
+});
+\`\`\`
+
+## Argument Schemas
+
+Tool args must be a top-level \`z.object(...)\`. Prefer explicit, bounded schemas made from strings, numbers, booleans, nulls, literals, enums, arrays, objects, optionals, nullables, and defaults. Avoid provider-visible recursive or open-ended schemas such as \`z.unknown()\`, \`z.any()\`, and \`z.object({}).catchall(...)\`; strict tool providers can reject the generated JSON Schema. If a tool needs arbitrary JSON input, accept it as a JSON string and parse it inside \`execute\`.
+
+## 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) |
+| \`error_code\` | \`string\` | Machine-readable error code |
+| \`error_data\` | \`Record<string, unknown>\` | Structured error payload |
+| \`attachments\` | \`ToolAttachment[]\` | Files to attach (images, etc.) |
+
+## ThreadState Access
+
+The \`state\` parameter provides access to:
+
+\`\`\`typescript
+execute: async (state, args) => {
+  // Thread information
+  const threadId = state.thread.id;
+  const thread = state.thread.instance;
+
+  // Configuration
+  const agentName = state.agent.name;
+  const modelName = state.model.name;
+
+  // Message history
+  const messages = state.messages;
+
+  // Thread variable resolution
+  const apiKey = await state.env('GOOGLE_API_KEY');
+  await state.setEnv('LAST_TOOL_RUN_AT', new Date().toISOString());
+
+  // Durable per-thread JSON values
+  const runCount = (await state.getValue<number>('run_count')) ?? 0;
+  await state.setValue('run_count', runCount + 1);
+
+  // Sandboxed JS/TS execution with explicit bridge capabilities
+  const run = state.runCode('export async function main(path) { return await read(path) }', {
+    execute: { fn: 'main', args: ['/notes.txt'] },
+    globals: {
+      read: async (path: string) => {
+        const data = await state.readFile(path);
+        return data ? new TextDecoder().decode(data) : null;
+      },
+    },
+  });
+  const codeResult = await run;
+
+  // Parent state (for sub-prompts)
+  const root = state.rootState;
+}
+\`\`\`
+
+Use \`state.runCode()\` instead of \`eval\` or \`new Function\` for model- or user-authored JavaScript/TypeScript. The sandbox starts with no ambient host capabilities; provide imports/globals explicitly, use \`modules\` for local relative ES modules, use \`execute\` to select an export and pass args, use \`report\` for streamed observations, and call \`run.terminate(reason)\` from your own timeout budget when needed. \`modules\` keys are graph-root relative paths; entry-source imports resolve from \`options.filename\` when supplied. Relative module imports may use \`./\` and \`../\` as long as they resolve within the supplied module graph. In thread endpoints, \`runCode\` is forwarded into the thread Durable Object; pass plain transferable option values there, and do function-backed bridges from tools or in-thread execution contexts.
+
+## Tool Without Arguments
+
+\`\`\`typescript
+export default defineTool({
+  description: 'Get current server time',
+  execute: async (state) => {
+    return {
+      status: 'success',
+      result: new Date().toISOString(),
+    };
+  },
+});
+\`\`\`
+
+## Error Handling
+
+Return errors gracefully instead of throwing:
+
+\`\`\`typescript
+export default defineTool({
+  description: 'Fetch user data',
+  args: z.object({ userId: z.string() }),
+  execute: async (state, 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({
+  description: 'Create order and send confirmation',
+  args: z.object({ items: z.array(z.string()) }),
+  execute: async (state, args) => {
+    const order = await createOrder(args.items);
+
+    // Queue email tool to run next
+    queueTool(state, 'send_confirmation_email', {
+      orderId: order.id,
+      email: state.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({
+  description: 'Log audit event',
+  args: z.object({ event: z.string() }),
+  execute: async (state, args) => {
+    await injectMessage(state, {
+      role: 'system',
+      content: \`[AUDIT] \${args.event}\`,
+    });
+    return { status: 'success', result: 'Logged' };
+  },
+});
+\`\`\`
+
+## Variables and Env
+
+Tools can declare variable requirements with \`variables\`, including \`required\` and \`description\` metadata:
+
+\`\`\`typescript
+export default defineTool({
+  description: 'Search uploaded documents',
+  args: z.object({ query: z.string() }),
+  execute: async (state, args) => {
+    const vectorStoreId = await state.env('VECTOR_STORE_ID');
+    const results = await searchVectorStore(vectorStoreId, args.query);
+    return { status: 'success', result: JSON.stringify(results) };
+  },
+  variables: [
+    {
+      name: 'VECTOR_STORE_ID',
+      type: 'text',
+      required: true,
+      scoped: false,
+      description: 'OpenAI Vector Store ID',
+    },
+  ],
+});
+\`\`\`
+
+Use \`scoped: true\` for per-instance values that should not inherit from parent thread env (for example per-account OAuth tokens on subagents).
+
+## Returning Attachments
+
+Tools can return file attachments (e.g., generated images):
+
+\`\`\`typescript
+export default defineTool({
+  description: 'Generate a chart from data',
+  args: z.object({ data: z.array(z.number()) }),
+  execute: async (state, args) => {
+    const chartImage = await generateChart(args.data);
+    return {
+      status: 'success',
+      result: 'Chart generated successfully',
+      attachments: [{
+        name: 'chart.png',
+        mimeType: 'image/png',
+        data: chartImage.base64,
+        width: 800,
+        height: 600,
+      }],
+    };
+  },
+});
+\`\`\`
+
+## 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 \`state.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/docs/hooks.ts
+var HOOKS_CLAUDE_MD = `# Lifecycle Hooks
+
+Hooks intercept and modify agent execution at specific lifecycle points.
+
+## Available Hooks
+
+| Hook | Signature | Purpose |
+|------|-----------|---------|
+| \`after_thread_created\` | \`(state: ThreadState) => void\` | Initialize a newly created thread before execution |
+| \`after_subagent_created\` | \`(state: ThreadState, childState: ThreadState) => void\` | Run parent-side logic after a child thread is created |
+| \`after_system_message\` | \`(state: ThreadState, systemMessage: string) => string \\| null \\| undefined\` | Modify the rendered system message for a request |
+| \`filter_messages\` | \`(state: ThreadState, messages: Message[]) => Message[]\` | Filter raw messages before LLM context |
+| \`prefilter_llm_history\` | \`(state: ThreadState, messages: LLMMessage[]) => LLMMessage[]\` | Modify chat completion messages before LLM |
+| \`before_create_message\` | \`(state: ThreadState, message: Message) => Message\` | Modify message before database insert |
+| \`after_create_message\` | \`(state: ThreadState, message: Message) => void\` | Run logic after message created |
+| \`before_update_message\` | \`(state: ThreadState, id: string, updates: Record) => Record\` | Modify updates before message update |
+| \`after_update_message\` | \`(state: ThreadState, message: Message) => void\` | Run logic after message updated |
+| \`before_store_tool_result\` | \`(state: ThreadState, toolCall: HookToolCall, result: HookToolResult) => HookToolResult\` | Modify tool result before storage |
+| \`after_tool_call_success\` | \`(state: ThreadState, toolCall: HookToolCall, result: HookToolResult) => HookToolResult \\| null\` | Process successful tool execution |
+| \`after_tool_call_failure\` | \`(state: ThreadState, toolCall: HookToolCall, result: HookToolResult) => HookToolResult \\| null\` | Process failed tool execution |
+
+All hooks receive \`ThreadState\` as their first parameter, providing access to thread identity, message history, resource loading, durable per-thread values via \`getValue\` / \`setValue\`, and sandboxed JS/TS execution via \`runCode\`.
+
+## Creating a Hook
+
+Each hook file exports a default \`defineHook\` call with three properties:
+
+\`\`\`typescript
+import { defineHook } from '@standardagents/builder';
+
+export default defineHook({
+  hook: 'filter_messages',       // Hook type
+  id: 'limit_recent_messages',   // Unique ID (snake_case)
+  execute: async (state, messages) => {
+    return messages.slice(-20);
+  }
+});
+\`\`\`
+
+## Hook Scoping
+
+Hooks are scoped to **prompts** or **agents** via their ID:
+
+\`\`\`typescript
+// In a prompt definition
+definePrompt({
+  name: 'customer_support',
+  hooks: ['limit_recent_messages', 'redact_pii'],
+  // ...
+});
+
+// In an agent definition
+defineAgent({
+  name: 'support_agent',
+  hooks: ['log_all_messages'],
+  // ...
+});
+\`\`\`
+
+- **Prompt hooks** take precedence over agent hooks
+- If a prompt defines hooks, only those run (agent hooks are skipped)
+- If no prompt hooks are defined, agent hooks run as fallback
+- Hooks are filtered by type at runtime
+
+## File Naming
+
+Hook files can use **any name** \u2014 the hook type and ID are defined inside the file:
+
+\`\`\`
+agents/hooks/
+\u251C\u2500\u2500 my_filter.ts              # Could contain any hook type
+\u251C\u2500\u2500 redact_sensitive_data.ts
+\u251C\u2500\u2500 log_tool_usage.ts
+\u2514\u2500\u2500 add_metadata.ts
+\`\`\`
+
+## Examples
+
+### Filter Messages (Limit Context)
+
+\`\`\`typescript
+import { defineHook } from '@standardagents/builder';
+
+export default defineHook({
+  hook: 'filter_messages',
+  id: 'limit_to_20',
+  execute: async (state, messages) => {
+    return messages.slice(-20);
+  }
+});
+\`\`\`
+
+### Prefilter LLM History (Redact Content)
+
+\`\`\`typescript
+import { defineHook } from '@standardagents/builder';
+
+export default defineHook({
+  hook: 'prefilter_llm_history',
+  id: 'redact_pii',
+  execute: async (state, messages) => {
+    return messages.map(msg => ({
+      ...msg,
+      content: typeof msg.content === 'string'
+        ? msg.content.replace(/\\b\\d{4}-\\d{4}-\\d{4}-\\d{4}\\b/g, '[REDACTED]')
+        : msg.content,
+    }));
+  }
+});
+\`\`\`
+
+### Before Create Message (Add Metadata)
+
+\`\`\`typescript
+import { defineHook } from '@standardagents/builder';
+
+export default defineHook({
+  hook: 'before_create_message',
+  id: 'add_version_metadata',
+  execute: async (state, message) => {
+    if (message.role === 'user' && message.content) {
+      return { ...message, content: \`[v1.0] \${message.content}\` };
+    }
+    return message;
+  }
+});
+\`\`\`
+
+### Before Store Tool Result (Sanitize)
+
+\`\`\`typescript
+import { defineHook } from '@standardagents/builder';
+
+export default defineHook({
+  hook: 'before_store_tool_result',
+  id: 'sanitize_results',
+  execute: async (state, toolCall, toolResult) => {
+    // toolCall: { id, type: 'function', function: { name, arguments } }
+    // toolResult: { status, result?, error?, stack?, attachments? }
+    if (toolResult.result) {
+      return { ...toolResult, result: toolResult.result.replace(/secret/gi, '[REDACTED]') };
+    }
+    return toolResult;
+  }
+});
+\`\`\`
+
+### After Tool Call Success (Logging)
+
+\`\`\`typescript
+import { defineHook } from '@standardagents/builder';
+
+export default defineHook({
+  hook: 'after_tool_call_success',
+  id: 'log_tool_success',
+  execute: async (state, toolCall, result) => {
+    console.log(\`Tool \${toolCall.function.name} succeeded\`);
+    return null;  // Return null to use original result
+  }
+});
+\`\`\`
+
+### After Tool Call Failure (Recovery)
+
+\`\`\`typescript
+import { defineHook } from '@standardagents/builder';
+
+export default defineHook({
+  hook: 'after_tool_call_failure',
+  id: 'weather_fallback',
+  execute: async (state, toolCall, result) => {
+    if (toolCall.function.name === 'fetch_weather') {
+      return {
+        status: 'success',
+        result: JSON.stringify({ temp: 'unavailable', fallback: true }),
+      };
+    }
+    return null;  // Use original error for other tools
+  }
+});
+\`\`\`
+
+## Hook Categories
+
+**Transformation hooks** (return modified data):
+- \`after_system_message\` (return replacement string, or null/undefined for no change)
+- \`filter_messages\`
+- \`prefilter_llm_history\`
+- \`before_create_message\`
+- \`before_update_message\`
+- \`before_store_tool_result\`
+- \`after_tool_call_success\` (return modified result or null)
+- \`after_tool_call_failure\` (return modified result or null)
+
+**Event hooks** (side effects only):
+- \`after_thread_created\`
+- \`after_subagent_created\`
+- \`after_create_message\`
+- \`after_update_message\`
+
+## Best Practices
+
+- **Keep hooks fast** - target <100ms execution
+- **Wrap in try-catch** - hooks continue on error (original data preserved)
+- **Use unique IDs** - hook IDs must be snake_case and unique across the project
+- **Scope appropriately** - assign hooks to prompts or agents that need them
+- **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/docs/api.ts
+var API_CLAUDE_MD = `# Thread-Specific API Endpoints
+
+Define custom API endpoints that operate on specific threads with access to the thread's ThreadState.
+
+## File-Based Routing
+
+| File Pattern | HTTP Method | Route |
+|--------------|-------------|-------|
+| \`name.ts\` | GET | \`/api/threads/:threadId/name\` |
+| \`name.get.ts\` | GET | \`/api/threads/:threadId/name\` |
+| \`name.post.ts\` | POST | \`/api/threads/:threadId/name\` |
+| \`name.put.ts\` | PUT | \`/api/threads/:threadId/name\` |
+| \`name.delete.ts\` | DELETE | \`/api/threads/:threadId/name\` |
+| \`index.ts\` | GET | \`/api/threads/:threadId\` |
+| \`nested/route.ts\` | GET | \`/api/threads/:threadId/nested/route\` |
+| \`items/[id].ts\` | GET | \`/api/threads/:threadId/items/:id\` |
+| \`files/[*].ts\` | GET | \`/api/threads/:threadId/files/*\` |
+
+Files without a method suffix default to GET. Method suffixes are case-insensitive and support \`.get.ts\`, \`.post.ts\`, \`.put.ts\`, \`.patch.ts\`, and \`.delete.ts\`.
+
+Dynamic segments use \`[name]\` and are passed to the handler as \`params.name\`. Catch-all segments use \`[*]\` and are passed as \`params['*']\`; the catch-all value may contain \`/\` for nested paths. Static routes match before dynamic routes, and dynamic routes match before catch-all routes.
+
+## Basic Example
+
+\`\`\`typescript
+// agents/api/status.get.ts -> GET /api/threads/:threadId/status
+import { defineThreadEndpoint } from '@standardagents/spec';
+
+export default defineThreadEndpoint(async (req, state, params) => {
+  const { messages, total } = await state.getMessages();
+  return Response.json({
+    threadId: state.threadId,
+    messageCount: total,
+    status: 'active',
+    params,
+  });
+});
+\`\`\`
+
+## Handler Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| \`req\` | \`Request\` | The incoming HTTP request |
+| \`state\` | \`ThreadState\` | Thread state with messages, identity, file system, \`runCode\`, etc. |
+| \`params\` | \`Record<string, string>\` | Route parameters captured from \`[name]\` and \`[*]\` path segments |
+
+Note: \`state.execution\` is always \`null\` in endpoints since the thread is at rest. \`state.runCode()\` is available from endpoints and is forwarded into the thread runtime; pass plain transferable option values there, and do function-backed sandbox bridges from tools or in-thread execution contexts.
+
+## ThreadState Methods
+
+Access thread data through the state object:
+
+\`\`\`typescript
+import { defineThreadEndpoint } from '@standardagents/spec';
+
+export default defineThreadEndpoint(async (req, state) => {
+  // Thread identity
+  console.log('Thread ID:', state.threadId);
+  console.log('Agent ID:', state.agentId);
+  console.log('User ID:', state.userId);
+
+  // Message operations
+  const { messages, total, hasMore } = await state.getMessages({
+    limit: 100,
+    offset: 0,
+    order: 'desc',
+  });
+
+  // Thread env (thread scope + active descendants)
+  const approvalGate = await state.env('TOPDOWN_APPROVAL_GATE');
+  await state.setEnv('TOPDOWN_APPROVAL_GATE', approvalGate || 'open');
+
+  // Durable per-thread JSON values
+  const exports = (await state.getValue<number>('export_count')) ?? 0;
+  await state.setValue('export_count', exports + 1);
+
+  // File system operations
+  const files = await state.findFiles('**/*.json');
+  const data = await state.readFile('/data/config.json');
+
+  // Resource loading
+  const agent = await state.loadAgent('my-agent');
+  const prompt = await state.loadPrompt('my-prompt');
+
+  return Response.json({ messages, total });
+});
+\`\`\`
+
+## POST with Request Body
+
+\`\`\`typescript
+// agents/api/export.post.ts -> POST /api/threads/:threadId/export
+import { defineThreadEndpoint } from '@standardagents/spec';
+
+export default defineThreadEndpoint(async (req, state) => {
+  const body = await req.json();
+  const { format = 'json' } = body;
+
+  const { messages } = await state.getMessages();
+
+  if (format === 'csv') {
+    const csv = messages.map(m => \`\${m.role},\${m.content}\`).join('\\n');
+    return new Response(csv, {
+      headers: { 'Content-Type': 'text/csv' },
+    });
+  }
+
+  return Response.json(messages);
+});
+\`\`\`
+
+## Nested Routes
+
+Create directories for nested routes:
+
+\`\`\`
+agents/api/
+\u251C\u2500\u2500 status.get.ts           -> GET /api/threads/:threadId/status
+\u251C\u2500\u2500 export.post.ts          -> POST /api/threads/:threadId/export
+\u2514\u2500\u2500 messages/
+    \u251C\u2500\u2500 count.ts            -> GET /api/threads/:threadId/messages/count
+    \u251C\u2500\u2500 [id].ts             -> GET /api/threads/:threadId/messages/:id
+    \u2514\u2500\u2500 [*].ts              -> GET /api/threads/:threadId/messages/*
+\`\`\`
+
+## Error Handling
+
+\`\`\`typescript
+import { defineThreadEndpoint } from '@standardagents/spec';
+
+export default defineThreadEndpoint(async (req, state) => {
+  try {
+    const data = await riskyOperation();
+    return Response.json(data);
+  } catch (error) {
+    return Response.json({ error: error.message }, { status: 500 });
+  }
+});
+\`\`\`
+
+## File System Operations
+
+\`\`\`typescript
+import { defineThreadEndpoint } from '@standardagents/spec';
+
+export default defineThreadEndpoint(async (req, state) => {
+  // Read files
+  const content = await state.readFile('/data/file.txt');
+
+  // Write files
+  await state.writeFile('/output/result.json', JSON.stringify(data), 'application/json');
+
+  // List directory
+  const { entries } = await state.readdirFile('/data');
+
+  // Search files
+  const matches = await state.grepFiles('pattern');
+  const paths = await state.findFiles('**/*.ts');
+
+  return Response.json({ success: true });
+});
+\`\`\`
+
+## 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
+- **Import from spec** - use \`@standardagents/spec\` for \`defineThreadEndpoint\`
+
+## Documentation
+
+Full reference: https://docs.standardagentbuilder.com/core-concepts/api
+`;
+
+// src/index.ts
+var FIRST_PARTY_PROVIDER_PACKAGES = [
+  "@standardagents/cloudflare",
+  "@standardagents/cerebras",
+  "@standardagents/google",
+  "@standardagents/groq",
+  "@standardagents/openai",
+  "@standardagents/openrouter",
+  "@standardagents/xai"
+];
+var DEFAULT_TEMPLATE_VERSIONS = {
+  standardAgents: "latest",
+  sip: "latest",
+  vite: "latest",
+  typescript: "latest",
+  cloudflareVitePlugin: "latest",
+  wrangler: "latest",
+  zod: "latest"
+};
+var AGENTBUILDER_TEMPLATE_VERSION = "0.15.0";
+var DEFAULT_COMPATIBILITY_DATE = "2025-08-13";
+function ensureTrailingNewline(value) {
+  return value.endsWith("\n") ? value : `${value}
+`;
+}
+function mergeVersions(versions) {
+  return {
+    ...DEFAULT_TEMPLATE_VERSIONS,
+    ...versions
+  };
+}
+function packageNameFromProjectName(projectName) {
+  const normalized = projectName.toLowerCase().replace(/^@[^/]+\//, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return normalized || "agentbuilder-project";
+}
+function file(path, content, message) {
+  return {
+    path,
+    content: ensureTrailingNewline(content),
+    message
+  };
+}
+function renderPackageJson(options) {
+  const versions = mergeVersions(options.versions);
+  const standardAgentsVersion = versions.standardAgents;
+  const dependencies = {
+    "@standardagents/builder": standardAgentsVersion,
+    "@standardagents/spec": standardAgentsVersion,
+    "@standardagents/sip": versions.sip,
+    zod: versions.zod ?? "latest"
+  };
+  for (const providerPackage of FIRST_PARTY_PROVIDER_PACKAGES) {
+    dependencies[providerPackage] = standardAgentsVersion;
+  }
+  return `${JSON.stringify({
+    name: packageNameFromProjectName(options.projectName),
+    version: "0.0.0",
+    private: true,
+    type: "module",
+    scripts: {
+      dev: "vite --host 0.0.0.0 --port 5173",
+      build: "vite build",
+      typecheck: "tsc --noEmit",
+      "wrangler:types": "wrangler types"
+    },
+    dependencies,
+    devDependencies: {
+      "@cloudflare/vite-plugin": versions.cloudflareVitePlugin,
+      typescript: versions.typescript,
+      vite: versions.vite,
+      wrangler: versions.wrangler
+    }
+  }, null, 2)}
+`;
+}
+function renderWranglerJson(options) {
+  const compatibilityDate = options.compatibilityDate ?? DEFAULT_COMPATIBILITY_DATE;
+  const workerName = packageNameFromProjectName(options.projectName);
+  return `{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "${workerName}",
+  "main": "worker/index.ts",
+  "compatibility_date": "${compatibilityDate}",
+  "compatibility_flags": ["nodejs_compat", "enable_ctx_exports"],
+  "observability": {
+    "enabled": true
+  },
+  "worker_loaders": [
+    {
+      "binding": "AGENT_BUILDER_CODE_LOADER"
+    }
+  ],
+  "vars": {
+    "AGENT_BUILDER_CODE_COMPATIBILITY_DATE": "${compatibilityDate}"
+  },
+  "assets": {
+    "directory": "dist/client",
+    "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"]
+    }
+  ]
+}
+`;
+}
+function renderViteConfig() {
+  return `import { defineConfig } from "vite"
+import { cloudflare } from "@cloudflare/vite-plugin"
+import { agentbuilder } from "@standardagents/builder"
+
+export default defineConfig({
+  plugins: [agentbuilder({ mountPoint: "/" }), cloudflare()],
+})
+`;
+}
+function renderTsConfig() {
+  return `{
+  "compilerOptions": {
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "module": "ESNext",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "skipLibCheck": true,
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "strict": true
+  },
+  "include": ["worker", "agents"]
+}
+`;
+}
+function renderWorkerIndex() {
+  return `import { router, CodeExecutionBridge } 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, CodeExecutionBridge }
+`;
+}
+function renderDurableThread() {
+  return `import { DurableThread } from "virtual:@standardagents/builder"
+
+export default class Thread extends DurableThread {}
+`;
+}
+function renderDurableAgentBuilder() {
+  return `import { DurableAgentBuilder } from "virtual:@standardagents/builder"
+
+export default class AgentBuilder extends DurableAgentBuilder {}
+`;
+}
+function renderGitignore() {
+  return `node_modules
+dist
+.wrangler
+.env
+.dev.vars
+`;
+}
+function renderDevVarsExample() {
+  return `# Standard Agents local development environment
+# Copy to .dev.vars for local-only Worker secrets.
+
+# Local data encryption key. Generate with: openssl rand -hex 32
+ENCRYPTION_KEY=
+
+# Optional local admin password for development access.
+SUPER_ADMIN_PASSWORD=password
+
+# Platform connection. The CLI writes real values to .dev.vars for platform-created projects.
+STANDARD_AGENTS_API_KEY=
+PLATFORM_ENDPOINT=
+STANDARD_AGENTS_API_URL=
+
+# BYOK provider keys. When set, these keys override Standard Agents hosted routing for that provider.
+CLOUDFLARE_API_TOKEN=
+CLOUDFLARE_ACCOUNT_ID=
+CEREBRAS_API_KEY=
+GOOGLE_API_KEY=
+GROQ_API_KEY=
+OPENAI_API_KEY=
+OPENROUTER_API_KEY=
+XAI_API_KEY=
+`;
+}
+function renderDeployHelper() {
+  return `import fs from "node:fs";
+import path from "node:path";
+
+function findBundleInDir(dir) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  const files = entries
+    .filter((entry) => entry.isFile() && /\\.(m?js)$/.test(entry.name))
+    .sort((a, b) => {
+      const aIsIndex = a.name === "index.js" || a.name === "index.mjs" ? 0 : 1;
+      const bIsIndex = b.name === "index.js" || b.name === "index.mjs" ? 0 : 1;
+      if (aIsIndex !== bIsIndex) return aIsIndex - bIsIndex;
+      return fs.statSync(path.join(dir, b.name)).size - fs.statSync(path.join(dir, a.name)).size;
+    });
+
+  for (const file of files) {
+    const filePath = path.join(dir, file.name);
+    const content = fs.readFileSync(filePath, "utf8");
+    if (content.includes("export default") || content.includes("export {")) {
+      return { path: filePath, content };
+    }
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name === "client" || entry.name === "node_modules") continue;
+    const nested = findBundleInDir(path.join(dir, entry.name));
+    if (nested) return nested;
+  }
+  return null;
+}
+
+function findWorkerBundle() {
+  for (const dir of [".wrangler/tmp", "dist"]) {
+    if (!fs.existsSync(dir)) continue;
+    const bundle = findBundleInDir(dir);
+    if (bundle) return bundle;
+  }
+  throw new Error("Could not find a Worker bundle in .wrangler/tmp or dist");
+}
+
+const deployUrl = process.env.STANDARD_AGENTS_DEPLOY_URL;
+const deployToken = process.env.STANDARD_AGENTS_DEPLOY_TOKEN;
+const buildId = process.env.STANDARD_AGENTS_BUILD_ID;
+if (!deployUrl || !deployToken || !buildId) {
+  throw new Error("Missing Standard Agents deployment environment");
+}
+
+const bundle = findWorkerBundle();
+const response = await fetch(deployUrl, {
+  method: "POST",
+  headers: {
+    "Authorization": \`Bearer \${deployToken}\`,
+    "Content-Type": "application/json",
+  },
+  body: JSON.stringify({
+    build_id: buildId,
+    script_content: bundle.content,
+    compatibility_date: process.env.STANDARD_AGENTS_COMPATIBILITY_DATE || undefined,
+  }),
+});
+
+if (!response.ok) {
+  const text = await response.text();
+  throw new Error(\`Standard Agents deploy failed (\${response.status}): \${text}\`);
+}
+
+console.log(\`Deployed Standard Agents Worker from \${bundle.path}\`);
+`;
+}
+function renderDeployWorkflow() {
+  return `name: Standard Agents Deploy
+
+on:
+  repository_dispatch:
+    types: [standardagents-deploy]
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    env:
+      STANDARD_AGENTS_BUILD_ID: \${{ github.event.client_payload.build_id }}
+      STANDARD_AGENTS_DEPLOY_URL: \${{ github.event.client_payload.deploy_url }}
+      STANDARD_AGENTS_DEPLOY_TOKEN: \${{ github.event.client_payload.deploy_token }}
+      STANDARD_AGENTS_COMPATIBILITY_DATE: \${{ github.event.client_payload.compatibility_date }}
+      STANDARD_AGENTS_API_URL: \${{ github.event.client_payload.api_url }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: \${{ github.event.client_payload.commit_sha }}
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - name: Enable package managers
+        run: corepack enable
+      - name: Install dependencies
+        shell: bash
+        run: |
+          if [ -f pnpm-lock.yaml ]; then
+            pnpm install --frozen-lockfile || pnpm install
+          elif [ -f yarn.lock ]; then
+            yarn install --immutable || yarn install
+          elif [ -f bun.lockb ] || [ -f bun.lock ]; then
+            bun install --frozen-lockfile || bun install
+          elif [ -f package-lock.json ]; then
+            npm ci || npm install
+          else
+            npm install
+          fi
+      - name: Build
+        shell: bash
+        run: |
+          if [ -f pnpm-lock.yaml ]; then
+            pnpm run build
+          elif [ -f yarn.lock ]; then
+            yarn build
+          elif [ -f bun.lockb ] || [ -f bun.lock ]; then
+            bun run build
+          else
+            npm run build
+          fi
+      - name: Upload Worker
+        run: node .github/standardagents-deploy.mjs
+`;
+}
+function renderTemplateMetadata(options) {
+  return `${JSON.stringify({
+    generator: "@standardagents/agentbuilder-template",
+    template_version: options.templateVersion ?? AGENTBUILDER_TEMPLATE_VERSION,
+    project_name: options.projectName
+  }, null, 2)}
+`;
+}
+function renderAgentBuilderProject(options) {
+  const files = [
+    file("package.json", renderPackageJson(options), "Add AgentBuilder package manifest"),
+    file("tsconfig.json", renderTsConfig(), "Add TypeScript config"),
+    file("vite.config.ts", renderViteConfig(), "Add Vite config"),
+    file("wrangler.jsonc", renderWranglerJson(options), "Add Wrangler config"),
+    file("worker/index.ts", renderWorkerIndex(), "Add Worker entrypoint"),
+    file("agents/Thread.ts", renderDurableThread(), "Add DurableThread"),
+    file("agents/AgentBuilder.ts", renderDurableAgentBuilder(), "Add DurableAgentBuilder"),
+    file("agents/agents/CLAUDE.md", AGENTS_CLAUDE_MD, "Add agent docs"),
+    file("agents/prompts/CLAUDE.md", PROMPTS_CLAUDE_MD, "Add prompt docs"),
+    file("agents/models/CLAUDE.md", MODELS_CLAUDE_MD, "Add model docs"),
+    file("agents/tools/CLAUDE.md", TOOLS_CLAUDE_MD, "Add tool docs"),
+    file("agents/hooks/CLAUDE.md", HOOKS_CLAUDE_MD, "Add hook docs"),
+    file("agents/api/CLAUDE.md", API_CLAUDE_MD, "Add API docs"),
+    file("CLAUDE.md", ROOT_CLAUDE_MD, "Add AgentBuilder project docs"),
+    file(".dev.vars.example", renderDevVarsExample(), "Add local env example"),
+    file(".gitignore", renderGitignore(), "Add gitignore")
+  ];
+  if (options.includeTemplateMetadata) {
+    files.push(file(".standardagents/template.json", renderTemplateMetadata(options), "Add Standard Agents template metadata"));
+  }
+  if (options.includeDeployAutomation) {
+    files.push(
+      file(".github/standardagents-deploy.mjs", renderDeployHelper(), "Add Standard Agents deploy helper"),
+      file(".github/workflows/standardagents-deploy.yml", renderDeployWorkflow(), "Add Standard Agents deploy workflow")
+    );
+  }
+  return files;
+}
+export {
+  AGENTBUILDER_TEMPLATE_VERSION,
+  AGENTS_CLAUDE_MD,
+  API_CLAUDE_MD,
+  DEFAULT_COMPATIBILITY_DATE,
+  DEFAULT_TEMPLATE_VERSIONS,
+  FIRST_PARTY_PROVIDER_PACKAGES,
+  HOOKS_CLAUDE_MD,
+  MODELS_CLAUDE_MD,
+  PROMPTS_CLAUDE_MD,
+  ROOT_CLAUDE_MD,
+  TOOLS_CLAUDE_MD,
+  packageNameFromProjectName,
+  renderAgentBuilderProject,
+  renderDeployHelper,
+  renderDeployWorkflow,
+  renderDevVarsExample,
+  renderDurableAgentBuilder,
+  renderDurableThread,
+  renderGitignore,
+  renderPackageJson,
+  renderTemplateMetadata,
+  renderTsConfig,
+  renderViteConfig,
+  renderWorkerIndex,
+  renderWranglerJson
+};
+//# sourceMappingURL=index.js.map