@standardagents/agentbuilder-template 0.40.12 → 0.41.0

package/dist/index.js

@@ -18,7 +18,7 @@ Model \u2192 Prompt \u2192 Agent \u2192 Thread
 
 **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).
+**Agents** orchestrate conversations. An agent has exactly two sides; each side is backed by a human (\`{ human: true }\`), a prompt (\`{ prompt: 'name' }\`), or a handler (\`{ handler: 'name' }\` \u2014 deterministic code from \`agents/handlers/\`).
 **Threads** are individual conversation instances with persistent storage.
 
 ## Packability and Runtime Portability
@@ -96,6 +96,9 @@ agents/
 \u251C\u2500\u2500 prompts/               # Prompt definitions (definePrompt)
 \u2502   \u251C\u2500\u2500 AGENTS.md
 \u2502   \u2514\u2500\u2500 CLAUDE.md -> AGENTS.md
+\u251C\u2500\u2500 handlers/              # Handler definitions (defineHandler)
+\u2502   \u251C\u2500\u2500 AGENTS.md
+\u2502   \u2514\u2500\u2500 CLAUDE.md -> AGENTS.md
 \u251C\u2500\u2500 models/                # Model configurations (defineModel)
 \u2502   \u251C\u2500\u2500 AGENTS.md
 \u2502   \u2514\u2500\u2500 CLAUDE.md -> AGENTS.md
@@ -137,7 +140,7 @@ interface ThreadState {
   agentId: string;            // Agent identifier
   userId: string | null;      // User identifier (if set)
   createdAt: number;          // Creation timestamp
-  children: SubagentRegistryEntry[]; // Resumable child registry
+  children: SubagentRegistryEntry[]; // Child instance registry
   terminated: number | null;  // Soft-termination timestamp
   arguments: Record<string, unknown>; // Invocation or subagent creation args
   context: Record<string, unknown>;   // Current-execution scratch data
@@ -182,16 +185,16 @@ reconnecting.
 
 ## Subagents
 
-\`dual_ai\` agents can be used as subagents from prompt tool configs:
+A subagent is any agent composed as a child of another agent. Relationships are declared in the \`subagents\` array of a prompt- or handler-backed agent side (never inside a prompt's \`tools\` array):
 
 - 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\`)
-- \`subagent_create.arguments\` is validated from the receiving child side's prompt schema and persists as \`ThreadState.arguments\` plus prompt variables for the life of the child thread
+- Parent/child linkage is tracked in thread metadata; instances are visible in \`state.children\`
+- The relationship's owning side is where child traffic lands; parent\u2192child traffic enters in the child's side B perspective (\`role: 'user'\`), so the child's side A acts on it
+- For a prompt-backed owning side, the runtime injects the lifecycle tools \`subagents\`, \`subagent_create\`, and \`subagent_message\`; handler-backed sides reach children through \`ThreadState\` directly
+- \`subagent_create.arguments\` is validated from the receiving child's side A prompt schema and persists as \`ThreadState.arguments\` plus prompt variables for the life of the child thread
 - 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()\`; use \`state.stopSession({ result, notifyParent, status })\` when a tool should also terminally end the child session
-- A resumable child's session ending never terminates its thread. The same reference remains addressable for later \`subagent_message\` calls; only explicit \`state.terminate()\` tears the thread down.
+- Persistence is universal: a child's session ending never terminates its thread. The same reference remains addressable for later \`subagent_message\` calls; only explicit \`state.terminate()\` tears the thread down.
 
 Access in tools:
 \`\`\`typescript
@@ -224,6 +227,7 @@ export default defineHook({
 | \`defineModel()\` | Configure LLM provider | \`agents/models/\` |
 | \`defineProvider()\` | Custom provider endpoints and overrides | \`agents/providers/\` |
 | \`definePrompt()\` | System instructions + tools | \`agents/prompts/\` |
+| \`defineHandler()\` | Deterministic side turns | \`agents/handlers/\` |
 | \`defineAgent()\` | Conversation orchestration | \`agents/agents/\` |
 | \`defineTool()\` | Custom tool functions | \`agents/tools/\` |
 | \`defineHook()\` | Lifecycle interception | \`agents/hooks/\` |
@@ -357,7 +361,7 @@ other provider behavior.
 
 \`\`\`typescript
 // agents/providers/darkbloom.ts
-import { defineProvider, providerEnv } from '@standardagents/builder';
+import { defineProvider, providerEnv } from '@standardagents/spec';
 import { openai } from '@standardagents/openai';
 
 export default defineProvider({
@@ -441,7 +445,7 @@ package with connection config and optional method overrides.
 Use \`defineProvider()\` and export the result as the default export:
 
 \`\`\`typescript
-import { defineProvider, providerEnv, providerValue } from '@standardagents/builder';
+import { defineProvider, providerEnv, providerValue } from '@standardagents/spec';
 import { openai } from '@standardagents/openai';
 
 export default defineProvider({
@@ -516,7 +520,7 @@ Prompts define system instructions, model selection, and available tools for LLM
 | \`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) |
+| \`tools\` | \`(string \\| ToolConfig)[]\` | No | Available tools: tool names, sub-prompt names, provider tools, and exposed agent names for handoffs. Subagent relationships never appear here \u2014 they are declared on the agent side's \`subagents\` array |
 | \`includeChat\` | \`boolean\` | No | Include full conversation history |
 | \`includePastTools\` | \`boolean\` | No | Include previous tool results |
 | \`parallelToolCalls\` | \`boolean\` | No | Allow multiple concurrent tool calls |
@@ -595,60 +599,40 @@ 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
+### Subagents Come From the Side, Not the Tools Array
 
-Use \`SubagentToolConfig\` when the tool is a \`dual_ai\` agent:
+Composition into a child thread is not a prompt-tools concern. A subagent relationship is part of the agent's structure: it is declared in the \`subagents\` array of the agent side this prompt backs, never inside the prompt's \`tools\` array (a \`tools\` entry attempting to configure a subagent relationship is a definition-time error). The side's declaration is the grant:
 
 \`\`\`typescript
-tools: [
-  // Blocking, non-resumable (default)
-  { name: 'data_processor_agent' },
+// agents/agents/assistant_agent.ts
+sideA: {
+  prompt: 'coordinator',
+  subagents: [
+    { agent: 'calendar_agent', as: 'work_calendar',     scopedEnv: ['WORK_CAL_ID'] },
+    { agent: 'calendar_agent', as: 'personal_calendar', scopedEnv: ['PERSONAL_CAL_ID'] },
+    { agent: 'research_agent', blocking: true, maxInstances: 1 },
+    { agent: 'compaction_agent', hidden: true },
+    { agent: 'browser_agent', optional: 'ENABLE_BROWSER_AGENT' },
+  ],
+},
+\`\`\`
 
-  // The same agent exposed under a task-specific tool name: \`name\` is what
-  // the model calls; \`agent\` is the dual_ai agent that implements it.
-  { name: 'summarize_report', agent: 'data_processor_agent', blocking: true },
+For a prompt-backed side with non-hidden relationships, the runtime automatically injects three lifecycle tools scoped to that side's declarations:
+
+- \`subagents\` \u2014 pull-based visibility: returns the registry snapshot (reference, relationship name, agent name, status, initial arguments, creation time). Call it before \`subagent_create\` so existing instances are reused rather than duplicated.
+- \`subagent_create\` \u2014 creates (or continues) an instance. Its \`agent\` argument enumerates the side's enabled relationship *names* (\`as\`, defaulting to \`agent\`), never internal agent identifiers. It requires a non-empty \`name\` for the spawned instance; AgentBuilder stores that as a \`name:<value>\` thread tag for human-friendly labels.
+- \`subagent_message\` \u2014 queues a message to an existing instance by reference.
+
+These three names are reserved; a relationship \`as\` that collides with them (or with any other tool name) is a definition-time error.
+
+\`subagent_create.arguments\` is shaped by the \`requiredSchema\` of the receiving child's side A prompt (parent traffic enters the child in the side B perspective, \`role: 'user'\`, so side A acts on it exactly as for an external caller). AgentBuilder validates and persists those arguments for the life of the child thread, exposes them as \`ThreadState.arguments\` and prompt variables to **both** child sides, and rehydrates them on every later activation. Missing required arguments fail creation with a structured \`subagent_arguments_required\` error.
+
+Persistence is universal: every child instance is a persistent thread. Session end never terminates a child \u2014 a later \`subagent_message\` starts a new session with history intact; only explicit \`state.terminate()\` destroys an instance. \`blocking: true\` makes \`subagent_create\` await the child session's close and return its result; combined with \`maxInstances: 1\` and an existing instance it behaves as create-or-continue.
 
-  // 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.
-\`subagent_create.arguments\` is shaped by the prompt schema on the child side selected by \`resumable.receives_messages\`.
-AgentBuilder persists those initial arguments with the child thread, exposes them as \`ThreadState.arguments\` and prompt variables, and keeps them visible to both child sides for later resumptions.
-
-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()\`, \`state.setStatus()\`, or \`state.stopSession({ result, notifyParent, status })\`.
-Set top-level \`parentCommunication: 'explicit'\` on a NON-resumable subagent when its completion should not be auto-queued to the parent (so it never wakes the parent) \u2014 for background children that deliver results through another channel, e.g. the parent's thread KV. \`resumable.parentCommunication\` takes precedence when both are set.
-Set \`hidden: true\` to keep a subagent relationship declared and spawnable by runtime code (\`state.invokeTool()\`/\`queueTool()\` from hooks) while excluding its tool from every LLM request \u2014 the model can never call it (for infrastructure children like a background compaction agent).
-Adding an enabled child relationship automatically activates the child's
-disclosed \`parentHooks\` on this parent. Disabled optional relationships do
-not; hidden enabled relationships do. \`name\` is the relationship provenance
-and \`agent ?? name\` identifies the implementing child.
 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\`.
 
+See \`agents/agents/AGENTS.md\` for the full \`SubagentRelationship\` option list (\`immediate\`, \`optional\`, \`hidden\`, \`parentCommunication\`, init mappings) and the ownership rules.
+
 ## Input Validation
 
 Validate inputs when prompt is called as a tool:
@@ -726,135 +710,207 @@ Full reference: https://docs.standardagentbuilder.com/api-reference/define/promp
 // src/docs/agents.ts
 var AGENT_DEFINITIONS_AGENTS_MD = `# Agent Definitions
 
-Agents orchestrate conversations by defining prompts, stop conditions, and turn limits.
+An agent is the top-level conversation orchestrator. An agent has **exactly two sides**, and each side is **backed** by exactly one of three things: a human, a prompt, or a handler. There is no agent "type" \u2014 everything about how an agent converses, composes, and terminates is derived from the backings of its two sides.
+
+| Backing | Who takes this side's turns | Declared as |
+|---------|-----------------------------|-------------|
+| **Human** | A person, via whatever interface the runtime provides | \`{ human: true }\` |
+| **Prompt** | A model, driven by a prompt from \`agents/prompts/\` | \`{ prompt: 'name', ... }\` |
+| **Handler** | Deterministic code from \`agents/handlers/\` | \`{ handler: 'name', ... }\` |
+
+Both sides are explicit. There is no implicit "missing side B is a human" default \u2014 if a person takes side B's turns, write \`sideB: { human: true }\`.
 
 ## 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 |
+| \`sideA\` | \`SideConfig\` | Yes | Side A configuration (backing-discriminated) |
+| \`sideB\` | \`SideConfig\` | Yes | Side B configuration (backing-discriminated) |
+| \`maxSessionTurns\` | \`number\` | No | Session exchange safety cap \u2014 optional on every agent shape |
+| \`title\` | \`string\` | No | Human-readable label |
+| \`description\` | \`string\` | No | Agent summary |
+| \`icon\` | \`string\` | No | Display icon (see Icons below) |
+| \`exposeAsTool\` | \`boolean\` | No | Expose a callable entrypoint for handoffs and composition |
 | \`primary\` | \`boolean\` | No | Default true. Set false on internal handoff-target agents (e.g. domain-gearbox variants) to hide them from top-level UI agent lists; they stay fully addressable for handoffs and thread resumption |
-| \`toolDescription\` | \`string\` | No | Description when used as tool (required if exposeAsTool) |
+| \`toolDescription\` | \`string\` | No | Default model-facing description when this agent is composed or handed off to (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) |
-| \`parentHooks\` | \`ParentHookRequirement[]\` | No | Hooks an exposed dual-AI child automatically contributes to each direct parent |
+| \`parentHooks\` | \`ParentHookRequirement[]\` | No | Required hooks automatically contributed to a direct parent composition (legal on any exposed agent) |
 | \`tags\` | \`string[]\` | No | Tags for categorization and filtering |
 
 ## Side Configuration
 
+A side's configuration is discriminated by its backing: exactly one of \`human\`, \`prompt\`, or \`handler\` must be present.
+
+**Human side** \u2014 \`{ human: true, label? }\`. No other properties are legal on a human side. In particular, \`subagents\` on a human side is a definition-time error (nothing there can invoke them), and stop/session bindings are meaningless.
+
+**Prompt side**
+
 | 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) |
+| \`label\` | \`string\` | No | Display name for this side |
+| \`subagents\` | \`SubagentRelationship[]\` | No | Side-owned child relationships (see Subagent Relationships below) |
+| \`stopOnResponse\` | \`boolean\` | No | Stop side turn on text response without tool calls (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 |
+| \`sessionStop\` | \`SessionToolBinding\` | No | Terminal success lifecycle binding (object form only) |
+| \`sessionFail\` | \`SessionToolBinding\` | No | Terminal failure lifecycle binding (object form only) |
+| \`sessionStatus\` | \`SessionToolBinding\` | No | Non-terminal status lifecycle binding (object form only) |
+
+**Handler side**
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| \`handler\` | \`string\` | Yes | Handler name for this side (references \`agents/handlers/\`) |
+| \`label\` | \`string\` | No | Display name for this side |
+| \`subagents\` | \`SubagentRelationship[]\` | No | Side-owned child relationships |
+
+Handler sides have no \`maxSteps\`, \`stopOnResponse\`, or session bindings: a handler turn is a single invocation, and handlers end sessions through \`state.stopSession()\` rather than declarative bindings. See \`agents/handlers/AGENTS.md\`.
 
-## Basic Example (AI-Human)
+Session lifecycle bindings use the object form only:
+
+\`\`\`typescript
+sessionStop: {
+  name: 'complete_work',          // tool that controls the lifecycle action
+  messageProperty: 'summary',     // arg field that becomes lifecycle message text
+  attachmentsProperty: 'files',   // arg field containing attachment path(s)
+}
+\`\`\`
+
+## Derivations
+
+These follow from the backings and are never declared separately:
+
+- **Chat surface** \u2014 the primary conversational interface renders wherever a \`human\` backing is.
+- **Perspective** \u2014 \`role: 'user'\` is the side B perspective, \`role: 'assistant'\` is the side A perspective, for queueing, injection, and rendering alike.
+- **Subagent eligibility** \u2014 any agent may be composed as a subagent. Composing a child with a human side puts a person's step inside the composition (the child parks \`awaiting_human\` until that person responds).
+- **Termination discipline** \u2014 \`maxSessionTurns\` is optional on every agent shape, with uniform exchange counting across backings (a handler turn counts like a prompt turn). Two prompt-backed sides can ping-pong indefinitely \u2014 the cap is a voluntary safety valve, and prompt and handler authors own their termination discipline.
+
+## Example: Assistant (human \xD7 prompt)
+
+The everyday user-facing assistant \u2014 a person on side B, a model on side A:
 
 \`\`\`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',
+    sessionStop: { name: 'close_ticket' },
     maxSteps: 50,
   },
+  sideB: { human: true },
   tags: ['support', 'tier-1'],
 });
 \`\`\`
 
-## Dual-AI Example
+## Example: Worker / Reviewer (prompt \xD7 prompt)
 
-Two AI agents conversing (e.g., debate, iterative refinement):
+Two models converse; each side sees itself as \`assistant\` and the other as \`user\`. \`maxSessionTurns\` is optional but strongly recommended here \u2014 nothing external stops two models:
 
 \`\`\`typescript
 export default defineAgent({
-  name: 'code_review_debate',
-  type: 'dual_ai',
+  name: 'research_agent',
   maxSessionTurns: 20,
+  exposeAsTool: true,
+  toolDescription: 'Researches and validates findings autonomously',
   sideA: {
-    label: 'Reviewer',
-    prompt: 'code_reviewer',
+    label: 'Worker',
+    prompt: 'research_worker',
     stopOnResponse: true,
+    sessionStatus: { name: 'set_research_status', messageProperty: 'status' },
+    sessionFail: { name: 'fail_research', messageProperty: 'reason' },
   },
   sideB: {
-    label: 'Developer',
-    prompt: 'code_defender',
+    label: 'Reviewer',
+    prompt: 'research_reviewer',
     stopOnResponse: true,
+    sessionStop: { name: 'approve_research', messageProperty: 'summary' },
   },
 });
 \`\`\`
 
-## Dual-AI Subagent Pattern
+## Example: Relay (handler \xD7 human)
 
-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
+A deterministic, model-less surface: a person talks to a handler that forwards traffic to a composed child and relays answers back. Zero LLM calls happen on this thread:
 
 \`\`\`typescript
 export default defineAgent({
-  name: 'research_subagent',
-  type: 'dual_ai',
-  exposeAsTool: true,
-  toolDescription: 'Researches and validates findings autonomously',
-  maxSessionTurns: 16,
+  name: 'relay_agent',
   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,
+    handler: 'relay_pipe',
+    subagents: [{ agent: 'assistant_agent', maxInstances: 1 }],
   },
+  sideB: { human: true },
 });
 \`\`\`
 
+The \`relay_pipe\` handler lives in \`agents/handlers/relay_pipe.ts\` \u2014 the full worked example is in \`agents/handlers/AGENTS.md\`.
+
+## Subagent Relationships
+
+Composition into a child thread is declared on the side that owns it \u2014 never inside a prompt's \`tools\` array. The side's declaration is the grant:
+
+\`\`\`typescript
+sideA: {
+  prompt: 'coordinator',
+  subagents: [
+    { agent: 'calendar_agent', as: 'work_calendar',     scopedEnv: ['WORK_CAL_ID'] },
+    { agent: 'calendar_agent', as: 'personal_calendar', scopedEnv: ['PERSONAL_CAL_ID'] },
+    { agent: 'research_agent', blocking: true, maxInstances: 1 },
+  ],
+},
+\`\`\`
+
+- The owning side is where child traffic lands: completion, failure, and status messages arrive on the owning side's perspective. Parent\u2192child traffic enters in the child's side B perspective (\`role: 'user'\`), so the child's side A acts on it.
+- A relationship name (\`as\`, defaulting to \`agent\`) may appear on at most one side, must not collide with another tool name, and must not collide with the reserved lifecycle tool names \`subagents\`, \`subagent_create\`, \`subagent_message\`.
+- For a prompt-backed owning side, the runtime injects those lifecycle tools automatically. Handler-backed owning sides need no tool grant \u2014 handlers reach children through \`ThreadState\` directly.
+- **Persistence is universal**: every child instance is a persistent thread. Session end never terminates a thread; only explicit \`state.terminate()\` destroys an instance. \`blocking\` is purely a waiting style.
+
+See \`agents/prompts/AGENTS.md\` for the lifecycle tools from the prompt's point of view, and the relationship option list (\`immediate\`, \`optional\`, \`hidden\`, \`parentCommunication\`, init mappings).
+
 ## Agent Handoffs
 
-Expose an agent for handoffs from other prompts:
+When \`exposeAsTool: true\`, an agent referenced directly in a prompt's \`tools\` array is a **handoff**: the tool call transfers control of the *same thread* to the target agent, preserving history. Handoff requires the target agent to have a human side matching the thread's conversational surface.
 
 \`\`\`typescript
 export default defineAgent({
   name: 'escalation_agent',
-  type: 'ai_human',
   exposeAsTool: true,
   toolDescription: 'Escalate to senior support for complex issues',
-  sideA: {
-    prompt: 'senior_support',
-  },
+  sideA: { prompt: 'senior_support' },
+  sideB: { human: true },
 });
 \`\`\`
 
-Other prompts can then include the agent name in their \`tools\` array to enable handoffs.
+## Stop Semantics
+
+Runtime stop evaluation order for prompt-backed sides:
+
+1. **sessionStop / sessionFail** \u2014 end the session (success / terminal failure)
+2. **stopTool** \u2014 ends the current side's turn
+3. **stopOnResponse** \u2014 ends the turn when the LLM returns text without tool calls
+4. **Safety limits** \u2014 \`maxSteps\` (per side), \`maxSessionTurns\` (per session, hard limit: 250)
 
-## Stop Conditions (Priority Order)
+A handler-backed side's turn ends when its handler invocation returns. A human-backed side's turn ends when the human's inbound message is persisted.
 
-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)
+## Definition-Time Errors
+
+These shapes are rejected when definitions load:
+
+1. Both sides human (reserved \u2014 may lift in a later version)
+2. \`subagents\` declared on a human-backed side
+3. A side with zero backings, or more than one of \`human\` / \`prompt\` / \`handler\`
+4. A handler side referencing an undefined handler; a prompt side referencing an undefined prompt
+5. A relationship name (\`as\`) appearing on both sides, colliding with another tool name, or colliding with a reserved lifecycle tool name
+6. Session bindings, \`maxSteps\`, or stop bindings on a non-prompt side
+7. A session binding that is not in object form
 
 ## Hooks
 
@@ -863,17 +919,15 @@ 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',
-  },
+  sideA: { prompt: 'customer_support' },
+  sideB: { human: true },
 });
 \`\`\`
 
 Agent hooks run as a fallback when the active prompt has no hooks defined. Prompt hooks always take precedence. See \`agents/hooks/AGENTS.md\` for details.
 
-An exposed \`dual_ai\` child can declare required parent integration hooks:
+Any exposed agent can declare required parent integration hooks:
 
 \`\`\`typescript
 parentHooks: [{
@@ -883,12 +937,13 @@ parentHooks: [{
 }],
 \`\`\`
 
-Installing the package is inert. Adding this child to a prompt activates the
-hook automatically on that direct parent and composition UIs can show the
-\`reason\` first. Disabled optional relationships contribute nothing; enabled
-hidden relationships still contribute hooks. Required hooks run with the
-parent's \`ThreadState\`, load from the child's package namespace, and fail
-composition closed if missing. User-scope hooks cannot be listed.
+Installing the package is inert. Declaring a relationship targeting this agent
+(or adding it to a prompt as a handoff) activates the hook automatically on
+that direct parent, and composition UIs disclose the \`reason\` first. Disabled
+optional relationships contribute nothing; enabled hidden relationships still
+contribute hooks. Required hooks run with the parent's \`ThreadState\`, load
+from the child's package namespace, and fail composition closed if missing.
+User-scope hooks cannot be listed.
 
 ## Naming Convention
 
@@ -908,7 +963,8 @@ and the dashboard warns when a site-relative icon path has no matching file.
 
 - **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
+- **Write sideB explicitly** - there is no implicit default; a user-facing agent ends with \`sideB: { human: true }\`
+- **Cap prompt \xD7 prompt agents** - set \`maxSessionTurns\` when both sides are prompt-backed; nothing external stops two models
 - **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
@@ -918,6 +974,150 @@ and the dashboard warns when a site-relative icon path has no matching file.
 Full reference: https://docs.standardagentbuilder.com/api-reference/define/agent
 `;
 
+// src/docs/handlers.ts
+var HANDLERS_AGENTS_MD = `# Handler Definitions
+
+A handler is a function that takes one side's turns in a conversation. When a side of an agent is backed by a handler, the runtime does not call a model to answer an inbound message \u2014 it calls the handler function once, with the thread state and the message, and whatever that function does is the side's turn.
+
+A handler is **not** a hook (hooks decorate turns owned by something else, and their failures are non-fatal), **not** a tool (tools are capabilities a turn-owner chooses to invoke), and **not** an effect (effects run outside the conversation flow). Its only role is backing a side of an agent. Handlers may not be referenced by prompt \`tools\` arrays, hook lists, or effect schedules \u2014 such references are definition-time errors.
+
+## Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| \`description\` | \`string\` | No | Human-facing summary |
+| \`execute\` | \`(state: ThreadState, message: Message) => Promise<void>\` | Yes | The turn implementation |
+
+The handler's name comes from its filename: \`agents/handlers/relay_pipe.ts\` defines the handler \`relay_pipe\`. The \`message\` parameter is the full persisted message \u2014 id, role, content, silent flag, metadata, timestamps. Handlers are trusted definition code, like tools.
+
+## Basic Example
+
+\`\`\`typescript
+// agents/handlers/relay_pipe.ts
+import { defineHandler } from '@standardagents/builder';
+
+export default defineHandler({
+  description: 'Forwards inbound user traffic to the assistant child and relays answers back.',
+  execute: async (state, message) => {
+    // full ThreadState \u2014 forward, respond, spawn, stop, read/write KV
+  },
+});
+\`\`\`
+
+Reference it from exactly one place: the \`handler\` property of an agent side:
+
+\`\`\`typescript
+export default defineAgent({
+  name: 'relay_agent',
+  sideA: { handler: 'relay_pipe', subagents: [{ agent: 'assistant_agent', maxInstances: 1 }] },
+  sideB: { human: true },
+});
+\`\`\`
+
+## Execution Model
+
+A handler-backed side's turn is:
+
+1. An inbound message arrives on the side's perspective.
+2. The runtime invokes the handler once with the thread's \`ThreadState\` and that message.
+3. The invocation returns (or throws). The turn is complete.
+
+There are no steps, no tool-choice loop, and no model requests for this side. \`maxSteps\`, \`stopOnResponse\`, \`stopTool\`, and session bindings are not legal on handler sides \u2014 a handler turn has no steps to cap and ends when \`execute\` returns. Handlers end sessions explicitly via \`state.stopSession()\`. When the agent sets \`maxSessionTurns\`, a handler turn counts toward the exchange cap exactly like a prompt turn.
+
+## Delivery Semantics
+
+Delivery to a handler is **exactly-once per message**:
+
+- The handler is invoked exactly once for each inbound message on the side's perspective, in message persistence order.
+- The handler is never invoked concurrently for the same thread. Messages that arrive while a handler turn is in flight wait in the queue and are delivered one at a time, in order.
+- A message whose handler invocation failed is not automatically redelivered. Retry is a userland decision (re-send the message).
+
+**Warning:** Because queued messages wait behind the in-flight turn, a long-running handler stalls its thread. A handler that awaits a \`blocking\` child session holds the delivery slot for that session's entire duration \u2014 and if that child can only finish after *another* inbound message on this thread, the thread deadlocks. Relay-style handlers should forward without blocking (\`queueMessage\` toward the child) and treat the child's replies as ordinary later turns.
+
+## Error Semantics
+
+A handler that throws is **fatal to the turn, and only the turn**:
+
+- The turn is marked failed and the error is surfaced in the runtime's request/execution log as a runtime-origin failure \u2014 a throwing handler never silently swallows a message.
+- The inbound message stays persisted. Nothing is rolled back.
+- The **session continues**: the failure does not end the session, terminate the thread, or poison the queue. The next inbound message gets a fresh handler invocation.
+
+If an error should end the session, the handler must do so explicitly with \`state.stopSession()\`.
+
+## Capabilities
+
+A handler receives the full \`ThreadState\` and may do anything tools can do:
+
+- **Forward** \u2014 \`(await state.getChildThread(ref)).queueMessage(...)\` toward a child, or \`state.notifyParent(...)\` toward a parent.
+- **Respond** \u2014 \`state.injectMessage({ role, content })\` in its own side's role (\`assistant\` for side A, \`user\` for side B).
+- **Spawn** \u2014 create child instances of the side's declared \`subagents\` relationships via lifecycle APIs.
+- **Control** \u2014 \`state.stopSession()\`, \`state.setStatus()\`, effects, environment, key-value store, filesystem.
+
+Handlers need no tool grants for children: the side's \`subagents\` declarations establish existence and lifecycle, and the handler reaches children through \`ThreadState\` directly. (The injected lifecycle *tools* exist for prompts \u2014 a handler calls the same operations as code.)
+
+## The Outbound Boundary
+
+Handlers get no auto-injected reply channel. If a handler (or the side it feeds) should speak to a user or an external surface, that is userland code \u2014 a tool or handler calling the messaging surface it chooses (the \`message_user\` pattern). **The runtime routes inbound; userland decides outbound.**
+
+## Livelock Discipline
+
+Handler sides do not run away on their own \u2014 a handler runs only when a message arrives. But a handler that *replies to every inbound message* paired with a prompt-backed side creates a message ping-pong with no natural stop. Handler authors own their termination discipline:
+
+- reply conditionally, not unconditionally;
+- or set \`maxSessionTurns\` on the agent (available on every shape) as a hard safety valve;
+- or end the session explicitly with \`state.stopSession()\` when the work is done.
+
+## Worked Example: the Relay
+
+A user-facing thread that does **zero model work**: every inbound user message is forwarded verbatim to a composed assistant child; every child answer is relayed back out through userland messaging. One handler expresses the entire surface:
+
+\`\`\`typescript
+// agents/handlers/relay_pipe.ts
+import { defineHandler } from '@standardagents/builder';
+
+export default defineHandler({
+  description: 'Pipe user traffic to the assistant child; relay answers outward.',
+  execute: async (state, message) => {
+    const child = state.children.find(c => c.relationship === 'assistant_agent');
+    if (child) {
+      const thread = await state.getChildThread(child.reference);
+      await thread?.queueMessage({ role: 'user', content: message.content ?? '' });
+    }
+  },
+});
+
+// agents/agents/relay_agent.ts
+import { defineAgent } from '@standardagents/builder';
+
+export default defineAgent({
+  name: 'relay_agent',
+  sideA: {
+    handler: 'relay_pipe',
+    subagents: [{
+      agent: 'assistant_agent',
+      maxInstances: 1,
+      immediate: true,              // spawned at thread creation
+      parentCommunication: 'explicit',
+    }],
+  },
+  sideB: { human: true },
+});
+\`\`\`
+
+The child's answers arrive as inbound messages on side A (the owning side) and get their own handler turns, where the handler calls the project's outbound messaging tool. No model participates at any point.
+
+## Best Practices
+
+- **Forward without blocking** \u2014 queue toward children and treat their replies as later turns; never hold the delivery slot on a child session
+- **Reply conditionally** \u2014 an unconditional reply opposite a prompt side is a ping-pong
+- **End sessions explicitly** \u2014 \`state.stopSession()\` when the work is done; there are no declarative session bindings on handler sides
+- **Keep handlers deterministic** \u2014 code that wants a model writes a prompt; code that wants a capability writes a tool; code that decorates writes a hook
+
+## Documentation
+
+Full reference: https://docs.standardagentbuilder.com/api-reference/define/handler
+`;
+
 // src/docs/tools.ts
 var TOOLS_AGENTS_MD = `# Custom Tools
 
@@ -1845,7 +2045,7 @@ var DEFAULT_TEMPLATE_VERSIONS = {
   typescript: "latest",
   zod: "latest"
 };
-var AGENTBUILDER_TEMPLATE_VERSION = "0.40.12";
+var AGENTBUILDER_TEMPLATE_VERSION = "0.41.0";
 function ensureTrailingNewline(value) {
   return value.endsWith("\n") ? value : `${value}
 `;
@@ -2028,6 +2228,8 @@ function renderAgentBuilderProject(options) {
     symlink("agents/agents/CLAUDE.md", "AGENTS.md", "Add Claude agent docs symlink"),
     file("agents/prompts/AGENTS.md", PROMPTS_AGENTS_MD, "Add prompt docs"),
     symlink("agents/prompts/CLAUDE.md", "AGENTS.md", "Add Claude prompt docs symlink"),
+    file("agents/handlers/AGENTS.md", HANDLERS_AGENTS_MD, "Add handler docs"),
+    symlink("agents/handlers/CLAUDE.md", "AGENTS.md", "Add Claude handler docs symlink"),
     file("agents/models/AGENTS.md", MODELS_AGENTS_MD, "Add model docs"),
     symlink("agents/models/CLAUDE.md", "AGENTS.md", "Add Claude model docs symlink"),
     file("agents/providers/AGENTS.md", PROVIDERS_AGENTS_MD, "Add provider docs"),
@@ -2055,6 +2257,8 @@ export {
   APPROVED_DEPENDENCY_BUILD_SCRIPTS,
   DEFAULT_TEMPLATE_VERSIONS,
   FIRST_PARTY_PROVIDER_PACKAGES,
+  HANDLERS_AGENTS_MD,
+  HANDLERS_AGENTS_MD as HANDLERS_CLAUDE_MD,
   HOOKS_AGENTS_MD,
   HOOKS_AGENTS_MD as HOOKS_CLAUDE_MD,
   MODELS_AGENTS_MD,