@standardagents/spec 0.40.12 → 0.41.0

package/dist/index.d.ts

@@ -60,6 +60,13 @@ declare global {
          */
         interface HookIdRegistry {
         }
+        /**
+         * Registry of handler names from agents/handlers/.
+         * Generated types add properties: interface HandlerRegistry { 'relay_pipe': true; }
+         * This gives us: type Handlers = keyof HandlerRegistry = 'relay_pipe'
+         */
+        interface HandlerRegistry {
+        }
         /**
          * Registry mapping prompt/agent names to their requiredSchema field names.
          * For agents, this maps to the side_a prompt's requiredSchema fields.
@@ -117,6 +124,11 @@ declare global {
          * Hook IDs are the unique identifiers defined in agents/hooks/ files.
          */
         type HookIds = keyof HookIdRegistry extends never ? string : keyof HookIdRegistry;
+        /**
+         * Union of all handler names, or string when registry is empty.
+         * Handler names are the file-derived identifiers from agents/handlers/.
+         */
+        type Handlers = keyof HandlerRegistry extends never ? string : keyof HandlerRegistry;
     }
 }
 
@@ -1068,18 +1080,29 @@ interface ThreadMetadata {
 }
 /**
  * Registry entry for a subagent child thread.
+ *
+ * Every child instance is a persistent thread. Session end — stop, fail,
+ * error, or turn-cap — never terminates a thread: the entry's status
+ * transitions (e.g. `running` → `idle` / `failed`), the thread remains
+ * addressable, and a later message starts a new session with history intact.
+ * Only explicit termination destroys an instance.
  */
 interface SubagentRegistryEntry {
     /** Child thread UUID used as stable reference address */
     reference: string;
-    /** Child agent name */
+    /**
+     * The relationship name this instance was spawned under — the `as` name
+     * (defaulting to the agent name) of the owning side's declaration. This is
+     * the name lifecycle tools address; `name` is the implementing agent
+     * definition.
+     */
+    relationship: string;
+    /** Child agent definition name */
     name: string;
     /** Child agent title (human-readable) */
     title?: string;
     /** Tool description shown to the parent LLM */
     description: string;
-    /** Whether this subagent instance is resumable */
-    resumable?: boolean;
     /** Whether parent execution blocks on this subagent */
     blocking?: boolean;
     /** Optional human-readable thread name (for example from `name:` tag) */
@@ -1087,24 +1110,34 @@ interface SubagentRegistryEntry {
     /**
      * Initial argument values supplied when the child was created.
      *
-     * For resumable subagents, these values persist for the lifetime of the
-     * child thread and are visible to both child sides. Runtimes SHOULD source
-     * this object from the receiving side's prompt argument schema. The registry
-     * copy is parent-visible metadata; the durable child-side source SHOULD live
-     * with the child thread metadata/properties and be restored into
+     * These values persist for the lifetime of the child thread and are
+     * visible to both child sides. Runtimes SHOULD source this object from the
+     * child's side A prompt argument schema. The registry copy is
+     * parent-visible metadata; the durable child-side source SHOULD live with
+     * the child thread metadata/properties and be restored into
      * `ThreadState.arguments` during execution and endpoint access. Top-level
-     * keys SHOULD also be exposed to prompt variable interpolation for whichever
-     * child side is currently rendering.
+     * keys SHOULD also be exposed to prompt variable interpolation for
+     * whichever child side is currently rendering.
      */
     initialArguments?: Record<string, unknown>;
     /** Spawn group identifier used for grouping instances created together */
     spawnGroupId?: string;
     /** Instance creation timestamp (microseconds) */
     createdAt?: number;
-    /** Current status (`running`, `idle`, `terminated`, or custom text) */
+    /**
+     * Current status (`running`, `idle`, `failed`, `awaiting_human`,
+     * `terminated`, or custom text). A child whose human-backed side is due to
+     * take a turn parks in `awaiting_human`.
+     */
     status: string;
     /** How this child reports information back to its parent thread */
     parentCommunication?: 'implicit' | 'explicit';
+    /**
+     * @deprecated Removed in 0.2.0 — every child instance is a persistent
+     * thread, so there is no resumable/non-resumable distinction. See:
+     * https://standardagentspec.com/0.2.0/getting-started/changelog
+     */
+    resumable?: never;
 }
 /**
  * Options for retrieving messages.
@@ -1163,6 +1196,13 @@ interface Message {
      * (for example: `status_kind`, `subagent_event`). Message APIs may also
      * mark send-message and durable queue entries with `queued: true` until
      * they are injected into stored history.
+     *
+     * Provenance conventions (OPTIONAL, runtimes SHOULD set them): when a
+     * message originates from a child instance, `metadata.subagent_id` carries
+     * the child's reference UUID; when code forwards a message across threads,
+     * `metadata.forwarded_from` carries the source thread id. These are
+     * conventions, not requirements — userland must not need bracket-tag
+     * prefixes in message text to recover provenance.
      */
     metadata?: Record<string, unknown>;
     /** Message processing status */
@@ -1205,10 +1245,16 @@ interface Message {
     subagent_description?: string | null;
     /** Subagent status projected from runtime registry (when available) */
     subagent_status?: string | null;
-    /** Whether the associated subagent is resumable (when available) */
-    subagent_resumable?: boolean | null;
+    /** Subagent relationship name (`as`) projected from runtime registry (when available) */
+    subagent_relationship?: string | null;
     /** Whether the associated subagent is blocking (when available) */
     subagent_blocking?: boolean | null;
+    /**
+     * @deprecated Removed in 0.2.0 — every child instance is a persistent
+     * thread, so there is no resumable/non-resumable distinction. See:
+     * https://standardagentspec.com/0.2.0/getting-started/changelog
+     */
+    subagent_resumable?: never;
     /** Optional subagent instance thread name (when available) */
     subagent_thread_name?: string | null;
     /** Spawn group identifier for related subagent instances (when available) */
@@ -1230,12 +1276,13 @@ interface InjectMessageInput {
 /**
  * Input for queueing a message for delivery on the thread's next step.
  *
- * Role mapping follows dual_ai conventions:
- * - `assistant` maps to side_a
- * - `user` maps to side_b
+ * Role mapping is the single source of perspective truth, uniform across
+ * queueing, injection, and rendering:
+ * - `role: 'user'` — side B perspective (side A acts on it)
+ * - `role: 'assistant'` — side A perspective (side B acts on it)
  */
 interface QueueMessageInput {
-    /** Message role (`user` queues side_b perspective, `assistant` queues side_a perspective) */
+    /** Message role (`user` queues side B perspective, `assistant` queues side A perspective) */
     role: 'user' | 'assistant';
     /** Message content */
     content: string;
@@ -1635,7 +1682,7 @@ interface CodeExecutionResult {
 interface ExecutionState {
     /** Current flow ID (unique per execution) */
     readonly flowId: string;
-    /** Current side in dual_ai agents ('a' or 'b') */
+    /** Which side is currently taking its turn ('a' or 'b') */
     readonly currentSide: 'a' | 'b';
     /** Total steps executed in this flow */
     readonly stepCount: number;
@@ -1652,7 +1699,8 @@ interface ExecutionState {
     /**
      * Force a specific side to play the next turn.
      *
-     * Only valid for dual_ai agents. Has no effect on ai_human agents.
+     * Only meaningful when the forced side is prompt- or handler-backed;
+     * forcing a human-backed side parks execution awaiting that side's input.
      *
      * @param side - The side to force ('a' or 'b')
      */
@@ -1703,6 +1751,9 @@ interface SetEnvOptions {
 }
 /**
  * Options for {@link ThreadState.stopSession}.
+ *
+ * Ending a session never terminates the thread — the thread stays
+ * addressable and a later message starts a new session with history intact.
  */
 interface StopSessionOptions {
     /**
@@ -1828,7 +1879,8 @@ interface ThreadState {
     /**
      * Registry of subagent child instances owned by this thread.
      *
-     * Includes both resumable and non-resumable instances.
+     * Every entry is a persistent thread; session end never removes an entry,
+     * it only transitions the entry's status.
      */
     readonly children: SubagentRegistryEntry[];
     /**
@@ -1839,7 +1891,7 @@ interface ThreadState {
     /**
      * Arguments supplied when this thread was created or invoked.
      *
-     * For resumable subagent child threads, this is the durable
+     * For subagent child threads, this is the durable
      * `subagent_create.arguments` object restored from child thread
      * metadata/properties. Both child sides see the same object. Runtimes also
      * expose these keys to prompt variable interpolation, including included
@@ -2048,6 +2100,10 @@ interface ThreadState {
      * `sessionStop` tool call. By default it has no parent-message or status side
      * effects. Pass `notifyParent` and/or `status` when those effects are desired.
      *
+     * Stopping a session MUST NOT terminate the thread: the thread remains
+     * addressable with its history intact, and a later message starts a new
+     * session. Only `terminate()` destroys a thread.
+     *
      * @throws If called outside an active execution context
      */
     stopSession(options?: StopSessionOptions): Promise<void>;
@@ -3823,236 +3879,18 @@ interface PromptToolConfig {
     options?: Record<string, unknown>;
 }
 /**
- * Configuration for invoking a `dual_ai` agent as a subagent tool.
- *
- * Subagent tools are always autonomous `dual_ai` agents and support both:
- * - Blocking vs non-blocking execution
- * - Resumable vs non-resumable lifecycles
- *
- * Non-resumable subagents behave like normal tool calls.
- * Resumable subagents are created/messaged through runtime-injected lifecycle
- * tools (for example `subagent_create` and `subagent_message`) and tracked in
- * the parent thread registry. The injected `subagent_create` tool MUST require
- * a non-empty human-readable `name` argument and runtimes SHOULD persist it as
- * a child thread display name.
- *
- * Lifecycle tools manage resumable relationships exclusively: runtimes MUST
- * reject a `subagent_create` invocation that targets a relationship without
- * `resumable` configuration, without creating a child, and the rejection
- * SHOULD direct the model to invoke that tool directly instead. Runtimes
- * SHOULD constrain the injected tool's target argument to the exposed names
- * of the prompt's resumable relationships. Lifecycle tool references use the
- * relationship's exposed tool `name`, never an internal agent identifier that
- * differs from it.
- *
- * ### Pull-based child visibility
- *
- * Whenever resumable subagent configs exist, runtimes MUST also inject a
- * `subagents` query tool that returns the model-visible registry snapshot
- * (reference id, name, status, working-status text, initial arguments) as a
- * tool result on demand. Runtimes MUST NOT additionally inject an ambient
- * registry system message into request context when the query tool is
- * available: child state is pull-based (plus completion messages), because a
- * registry block that mutates between requests both invalidates provider
- * prefix caches and reads as out-of-dialogue state to agentic-tuned models.
- * The injected tool descriptions SHOULD direct the model to call `subagents`
- * before `subagent_create` so existing instances are reused instead of
- * duplicated.
- *
- * ### Persistent invocation arguments
- *
- * The child side that receives parent messages dictates initial invocation
- * arguments through that side's prompt `requiredSchema`
- * (`resumable.receives_messages`, defaulting to `side_a`). The invoking parent
- * supplies them when calling the subagent tool or `subagent_create` as a
- * structured `arguments` object.
- *
- * Unlike a plain tool call, these arguments are NOT ephemeral: runtimes MUST
- * persist the validated arguments for the life of the child thread and make
- * them available to BOTH `side_a` and `side_b` through `ThreadState.arguments`
- * and prompt variable interpolation on every activation. This lets a system
- * prompt reference spawn-time context for as long as the thread lives.
- *
- * If required arguments are missing or invalid, runtimes MUST reject creation
- * with a `subagent_arguments_required` error rather than spawning the child.
- *
- * @example
- * ```typescript
- * {
- *   name: 'browser_agent',
- *   blocking: false,
- *   resumable: {
- *     receives_messages: 'side_a',
- *     maxInstances: 1,
- *   },
- * }
- * ```
- *
- * @example
- * ```typescript
- * // The same agent exposed under a task-specific tool name.
- * {
- *   name: 'summarize_document',
- *   agent: 'document_agent',
- *   blocking: true,
- *   initUserMessageProperty: 'message',
- * }
- * ```
+ * @deprecated Removed in 0.2.0 — subagent relationships are no longer
+ * declared in a prompt's `tools` array. Declare them on the owning side's
+ * `subagents` array instead (see `SubagentRelationship`): the tool's `name`
+ * becomes `as` (or is dropped when it equals the agent name), `agent` stays
+ * `agent`, and the `resumable` wrapper is unwrapped — `maxInstances` and
+ * `parentCommunication` move to the relationship top level and
+ * `receives_messages` is deleted (declare the relationship on the side that
+ * received the messages). The owning side's prompt automatically receives the
+ * lifecycle tools (`subagents`, `subagent_create`, `subagent_message`).
+ * https://standardagentspec.com/0.2.0/getting-started/changelog
  */
-interface SubagentToolConfig<T extends string = StandardAgentSpec.Callables> {
-    /**
-     * Exposed tool name — the name the model invokes this subagent by.
-     *
-     * When `agent` is absent, this MUST reference a `dual_ai` agent with
-     * `exposeAsTool: true` directly. When `agent` is present, this may be any
-     * valid tool identifier; the runtime MUST expose the tool under this name
-     * and MUST resolve invocations to the agent named by `agent`.
-     */
-    name: T | (string & {});
-    /**
-     * The `dual_ai` agent this tool invokes, when the tool is exposed under a
-     * name other than the agent's own. Must reference a `dual_ai` agent with
-     * `exposeAsTool: true`. Defaults to `name`.
-     *
-     * The same agent may be exposed under different tool names by different
-     * prompts. Everything model-facing — the tool schema, instance registries,
-     * and subagent lifecycle tool references — uses the exposed `name`;
-     * runtimes resolve the implementing agent internally as `agent ?? name`.
-     */
-    agent?: T;
-    /**
-     * Whether parent execution blocks until the subagent returns a result.
-     *
-     * - `true`: Parent waits for completion (tool-call style)
-     * - `false`: Parent continues immediately and receives results asynchronously
-     *
-     * @default true
-     */
-    blocking?: boolean;
-    /**
-     * Property from tool-call arguments used as the initial message sent to the
-     * subagent on invocation.
-     *
-     * Uses the same semantics as {@link SubpromptConfig.initUserMessageProperty}.
-     */
-    initUserMessageProperty?: StandardAgentSpec.SchemaFields<T>;
-    /**
-     * Property from tool-call arguments containing attachment path(s) that should
-     * be sent to the subagent on invocation.
-     *
-     * Uses the same semantics as {@link SubpromptConfig.initAttachmentsProperty}.
-     */
-    initAttachmentsProperty?: StandardAgentSpec.SchemaFields<T>;
-    /**
-     * Property from tool-call arguments used to assign a human-readable name for
-     * each spawned child thread instance.
-     *
-     * Implementations SHOULD store this as a thread tag in the form
-     * `name:<value>` so UIs can render a concise per-instance title.
-     */
-    initAgentNameProperty?: StandardAgentSpec.SchemaFields<T>;
-    /**
-     * Execute this tool immediately when the prompt becomes active.
-     *
-     * - `true`: Execute immediately using runtime defaults.
-     * - Object: Execute immediately with explicit per-instance env relationships.
-     *
-     * When the object form is used:
-     * - `scopedEnv` names the per-instance env values copied into the child thread.
-     * - `nameEnv` and `descriptionEnv` identify the only per-instance env values
-     *   that runtimes may expose to an internal bootstrap model when deriving
-     *   initial child arguments.
-     *
-     * Runtimes MUST NOT expose `scopedEnv` values to the model unless the same env
-     * name is explicitly designated by `nameEnv` or `descriptionEnv`.
-     *
-     * Immediate tools run before the first LLM step for that activation.
-     */
-    immediate?: boolean | {
-        /**
-         * Scoped env name whose value may be used as the safe per-instance name
-         * hint for child bootstrap.
-         */
-        nameEnv?: string;
-        /**
-         * Scoped env name whose value may be used as the safe per-instance
-         * description hint for child bootstrap.
-         */
-        descriptionEnv?: string;
-        /**
-         * Scoped env names that should be copied into the child thread for each
-         * immediate instance group.
-         */
-        scopedEnv?: string[];
-    };
-    /**
-     * Optional branch flag env name.
-     *
-     * When set, this subagent is only enabled when the named env resolves to
-     * `true`, `1`, or `yes` (case-insensitive).
-     */
-    optional?: string;
-    /**
-     * Resumability configuration.
-     *
-     * - `false` (default): Non-resumable subagent
-     * - Object: Resumable subagent with message routing and instance limits
-     *
-     * When resumable mode is enabled, runtimes SHOULD provide a built-in create
-     * and message lifecycle interface instead of exposing raw agent callables for
-     * new instance creation.
-     */
-    resumable?: false | {
-        /**
-         * Which side of the child `dual_ai` conversation receives parent messages.
-         *
-         * - `side_a`: Messages are queued as `role: 'user'`
-         * - `side_b`: Messages are queued as `role: 'assistant'`
-         */
-        receives_messages: 'side_a' | 'side_b';
-        /**
-         * Maximum concurrent instances for this subagent tool.
-         *
-         * When reached, implementations may remove this tool from subsequent LLM
-         * requests and route new messages to existing instances.
-         *
-         * @default unlimited
-         */
-        maxInstances?: number;
-        /**
-         * How this child reports back to its parent.
-         *
-         * - `implicit` (default): Child completion is automatically queued to the parent.
-         * - `explicit`: The runtime does not auto-queue child completion; tools/hooks may
-         *   use thread APIs such as `state.notifyParent()` or `state.stopSession()` when
-         *   they choose to escalate or terminally end the session.
-         */
-        parentCommunication?: 'implicit' | 'explicit';
-    };
-    /**
-     * How this subagent reports completion back to its parent. Applies to
-     * non-resumable subagents; resumable subagents may instead set
-     * `resumable.parentCommunication`, which takes precedence when present.
-     *
-     * - `implicit` (default): the child's completion is auto-queued to the parent,
-     *   which triggers a parent turn.
-     * - `explicit`: the runtime does NOT auto-queue the child's completion, so the
-     *   parent is not woken. Use for background subagents that deliver their result
-     *   another way (e.g. writing to the parent's thread KV) and should be "picked
-     *   up" on the parent's next natural turn rather than forcing one.
-     */
-    parentCommunication?: 'implicit' | 'explicit';
-    /**
-     * Hide this subagent tool from the LLM's tool list while keeping the
-     * relationship declared, so runtime code (hooks calling
-     * `state.invokeTool()` / `queueTool()`) can still spawn it. Use for
-     * infrastructure subagents the model must never call itself (e.g. a
-     * background context-compaction agent).
-     *
-     * @default false
-     */
-    hidden?: boolean;
-}
+type SubagentToolConfig<T extends string = string> = never;
 /**
  * Reasoning configuration for models that support extended thinking.
  * Applies to models like OpenAI o1/o3, Anthropic Claude with extended thinking,
@@ -4177,13 +4015,12 @@ interface PromptDefinition<N extends string = string, S extends ToolArgs = ToolA
     /**
      * Zod schema for validating inputs when this prompt is called as a tool.
      *
-     * When this prompt is the `side_a` prompt of a `dual_ai` agent exposed as a
-     * subagent, this schema also dictates the invocation arguments accepted by
-     * the subagent tool (and the runtime-injected `subagent_create` tool).
-     * Required fields are mandatory; optional fields are treated as suggested.
-     * Runtimes persist the validated arguments for the life of the child thread
-     * and expose them to both sides' prompt interpolation (see
-     * {@link SubagentToolConfig} "Persistent invocation arguments").
+     * When this prompt backs side A of an agent composed as a subagent, this
+     * schema also dictates the invocation arguments accepted by the
+     * runtime-injected `subagent_create` tool. Required fields are mandatory;
+     * optional fields are treated as suggested. Runtimes persist the validated
+     * arguments for the life of the child thread and expose them to both
+     * sides' prompt interpolation through `ThreadState.arguments`.
      */
     requiredSchema?: S;
     /**
@@ -4196,9 +4033,14 @@ interface PromptDefinition<N extends string = string, S extends ToolArgs = ToolA
      * - string: Simple tool name (custom or provider tool)
      * - SubpromptConfig: Sub-prompt used as a tool
      * - PromptToolConfig: Tool with environment values and/or options
-     * - SubagentToolConfig: `dual_ai` subagent invocation behavior
      *
-     * To enable handoffs, include ai_human agent names in this array.
+     * To enable handoffs, include exposed agent names in this array.
+     *
+     * Subagent relationships are NOT declared here — they live on the owning
+     * side's `subagents` array, and the runtime injects the lifecycle tools
+     * (`subagents`, `subagent_create`, `subagent_message`) for the side's
+     * non-hidden relationships automatically. Handlers may never appear in
+     * this array.
      *
      * @example
      * ```typescript
@@ -4209,7 +4051,7 @@ interface PromptDefinition<N extends string = string, S extends ToolArgs = ToolA
      * ]
      * ```
      */
-    tools?: (StandardAgentSpec.Callables | SubpromptConfig | PromptToolConfig | SubagentToolConfig)[];
+    tools?: (StandardAgentSpec.Callables | SubpromptConfig | PromptToolConfig)[];
     /**
      * Environment values provided by this prompt.
      * Prompt values override user-account and AgentBuilder-instance defaults.
@@ -4296,21 +4138,213 @@ type PromptInput<T extends PromptDefinition<string, ToolArgs>> = T['requiredSche
 declare function definePrompt<N extends string, S extends ToolArgs = never>(options: PromptDefinition<N, S>): PromptDefinition<N, S>;
 
 /**
- * Agent definition types for Standard Agents.
+ * Subagent relationship types for Standard Agents.
+ *
+ * A subagent relationship is declared on the side of an agent that owns it
+ * (`side.subagents`), not on a prompt. The relationship is architecture:
+ * which agent may be instantiated as a child, under what name, with what
+ * lifecycle configuration. Prompts no longer declare relationships in their
+ * `tools` arrays — the owning side's prompt automatically receives the
+ * lifecycle tools (`subagents`, `subagent_create`, `subagent_message`) for
+ * the side's non-hidden relationships.
  *
- * Agents orchestrate conversations between AI models (dual_ai) or between
- * AI and human users (ai_human). They define the prompts, stop conditions,
- * and behavioral rules for each side of the conversation.
+ * https://standardagentspec.com/0.2.0/specification/subagents
  *
  * @module
  */
 /**
- * Agent conversation type.
+ * A side-owned subagent relationship.
+ *
+ * Ownership rules:
+ * - The relationship belongs to the side that declares it. Inbound child
+ *   traffic (completions, `notifyParent`, messages queued toward the parent)
+ *   lands on the owning side's perspective.
+ * - A relationship name (`as`, defaulted or explicit) may appear on at most
+ *   ONE side of an agent — a definition-time error otherwise.
+ * - Relationship names share the tool namespace. A name colliding with a
+ *   tool name, or with the reserved lifecycle tool names (`subagents`,
+ *   `subagent_create`, `subagent_message`), is a definition-time error.
+ * - Two relationships may target the same `agent` under different `as`
+ *   names, each with independent configuration.
+ *
+ * Instance lifecycle: every child instance is a persistent thread. Session
+ * end — stop, fail, error, or turn-cap — never terminates a thread; only
+ * explicit termination destroys an instance. With `blocking: true`,
+ * `maxInstances: 1`, and a live instance, `subagent_create` means
+ * create-or-continue: message the existing instance and await that session's
+ * close.
  *
- * - `ai_human`: AI conversing with a human user (most common)
- * - `dual_ai`: Two AI participants conversing with each other
+ * @template Agent - The agent name type (string or type-safe union)
+ *
+ * @example
+ * ```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 },
+ *   ],
+ * }
+ * ```
  */
-type AgentType = 'ai_human' | 'dual_ai';
+interface SubagentRelationship<Agent extends string = StandardAgentSpec.Agents> {
+    /**
+     * Which agent definition to instantiate. Must reference an agent with
+     * `exposeAsTool: true`.
+     */
+    readonly agent: Agent;
+    /**
+     * Relationship name; defaults to `agent`.
+     *
+     * This is the tool-surface name, the registry identity, and the name the
+     * lifecycle tools' `agent` argument enumerates. Aliasing lets the same
+     * child agent be composed twice under one side with independent
+     * configuration.
+     */
+    readonly as?: string;
+    /**
+     * Model-facing description override for this relationship. Falls back to
+     * the child agent's `toolDescription`.
+     */
+    readonly description?: string;
+    /**
+     * Maximum concurrent instances for this relationship. Unset = unbounded.
+     */
+    readonly maxInstances?: number;
+    /**
+     * Spawn an instance at THREAD CREATION, before any side takes a turn.
+     *
+     * - `true`: spawn immediately using runtime defaults.
+     * - Object: spawn immediately with explicit per-instance env wiring.
+     *
+     * When the object form is used:
+     * - `scopedEnv` names the per-instance env values copied into the child
+     *   thread.
+     * - `nameEnv` and `descriptionEnv` identify the only per-instance env
+     *   values that runtimes may expose to an internal bootstrap model when
+     *   deriving initial child arguments.
+     *
+     * Runtimes MUST NOT expose `scopedEnv` values to a model unless the same
+     * env name is explicitly designated by `nameEnv` or `descriptionEnv`.
+     */
+    readonly immediate?: boolean | {
+        /**
+         * Scoped env name whose value may be used as the safe per-instance
+         * name hint for child bootstrap.
+         */
+        readonly nameEnv?: string;
+        /**
+         * Scoped env name whose value may be used as the safe per-instance
+         * description hint for child bootstrap.
+         */
+        readonly descriptionEnv?: string;
+        /**
+         * Scoped env names copied into the child thread for each immediate
+         * instance group.
+         */
+        readonly scopedEnv?: readonly string[];
+    };
+    /**
+     * Whether `subagent_create` awaits the child session's close and returns
+     * its result.
+     *
+     * - `true`: the invoking turn waits for the session result.
+     * - `false` (default): the parent continues immediately and receives
+     *   results asynchronously.
+     */
+    readonly blocking?: boolean;
+    /**
+     * How this child reports back to its parent.
+     *
+     * - `implicit` (default): child completion/failure is automatically queued
+     *   to the owning side's perspective, which triggers a parent turn.
+     * - `explicit`: the runtime does not auto-queue child completion; child
+     *   code escalates via `state.notifyParent()` / `state.setStatus()` when
+     *   it chooses.
+     */
+    readonly parentCommunication?: 'implicit' | 'explicit';
+    /**
+     * Env names copied from the parent into each spawned child thread.
+     * Runtime-only; never model-visible unless designated by the `immediate`
+     * object form's `nameEnv`/`descriptionEnv`.
+     */
+    readonly scopedEnv?: readonly string[];
+    /**
+     * Property from `subagent_create` arguments used as the initial user
+     * message when spawning an instance.
+     */
+    readonly initUserMessageProperty?: StandardAgentSpec.SchemaFields<Agent>;
+    /**
+     * Property from `subagent_create` arguments containing attachment path(s)
+     * to include with the initial message.
+     */
+    readonly initAttachmentsProperty?: StandardAgentSpec.SchemaFields<Agent>;
+    /**
+     * Property from `subagent_create` arguments used as a human-readable name
+     * for each spawned instance. Implementations SHOULD store this as a thread
+     * tag in the form `name:<value>`.
+     */
+    readonly initAgentNameProperty?: StandardAgentSpec.SchemaFields<Agent>;
+    /**
+     * Optional branch flag env name. When set, this relationship is only
+     * enabled when the named env resolves to `true`, `1`, or `yes`
+     * (case-insensitive).
+     */
+    readonly optional?: string;
+    /**
+     * Keep the relationship declared and spawnable by runtime code while
+     * excluding it from every model request and from the injected `subagents`
+     * registry snapshot. Use for infrastructure children the model must never
+     * call or manage itself.
+     *
+     * @default false
+     */
+    readonly hidden?: boolean;
+    /**
+     * @deprecated Removed in 0.2.0 — the exposed tool name is now `as`, and
+     * the target agent is `agent`. See the migration guide:
+     * https://standardagentspec.com/0.2.0/getting-started/changelog
+     */
+    readonly name?: never;
+    /**
+     * @deprecated Removed in 0.2.0 — every child instance is a persistent
+     * thread; the `resumable` wrapper is gone. Move `maxInstances` and
+     * `parentCommunication` to the relationship top level and delete
+     * `receives_messages` (declare the relationship on the side that received
+     * the messages). See the migration guide:
+     * https://standardagentspec.com/0.2.0/getting-started/changelog
+     */
+    readonly resumable?: never;
+    /**
+     * @deprecated Removed in 0.2.0 — child traffic lands on the perspective of
+     * the side that OWNS the relationship. Declare the relationship on the
+     * side that should receive the messages. See the migration guide:
+     * https://standardagentspec.com/0.2.0/getting-started/changelog
+     */
+    readonly receives_messages?: never;
+}
+
+/**
+ * Agent definition types for Standard Agents.
+ *
+ * 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" —
+ * everything that used to hang off a type enum is derived from what backs
+ * each side.
+ *
+ * https://standardagentspec.com/0.2.0/specification/agents
+ *
+ * @module
+ */
+
+/**
+ * @deprecated Removed in 0.2.0 — there is no agent "type". Sides are
+ * backings: declare both sides explicitly with `human`, `prompt`, or
+ * `handler`. See the migration guide:
+ * https://standardagentspec.com/0.2.0/getting-started/changelog
+ */
+type AgentType = never;
 /**
  * Ordering position for a child agent's required hook on its parent.
  */
@@ -4319,22 +4353,23 @@ type ParentHookStage = 'before_parent' | 'after_parent';
  * A thread-scoped hook that a child agent requires on every direct parent.
  *
  * Downloading a package is inert. The hook becomes active automatically when
- * an enabled parent prompt exposes this `dual_ai` agent as a child tool, and
- * remains active for exactly the lifetime of that relationship.
+ * an enabled parent side declares a subagent relationship targeting this
+ * exposed agent, and remains active for exactly the lifetime of that
+ * relationship. Any exposed agent may declare parent hooks.
  */
 interface ParentHookRequirement<Hook extends string = StandardAgentSpec.HookIds> {
     /** Child-local hook ID from `defineHook({ id })`. */
-    hook: Hook;
+    readonly hook: Hook;
     /** Human-facing explanation shown by installers and composition UIs. */
-    reason: string;
+    readonly reason: string;
     /** Whether the hook runs before or after the parent's own hook set. */
-    stage?: ParentHookStage;
+    readonly stage?: ParentHookStage;
 }
 /**
  * Configuration for a session lifecycle tool.
  *
- * Used by side-level lifecycle options (`sessionStop`, `sessionFail`, `sessionStatus`)
- * to declare:
+ * Used by prompt-side lifecycle options (`sessionStop`, `sessionFail`,
+ * `sessionStatus`) to declare:
  * - which tool controls that lifecycle action
  * - which tool-argument field should be forwarded as message text
  * - which tool-argument field contains attachment path(s) to forward
@@ -4345,118 +4380,138 @@ interface SessionToolConfig<Callable extends string = StandardAgentSpec.Callable
     /**
      * Tool name for this session lifecycle action.
      */
-    name: Callable;
+    readonly name: Callable;
     /**
      * Optional tool-argument property used as lifecycle message text.
      */
-    messageProperty?: string;
+    readonly messageProperty?: string;
     /**
      * Optional tool-argument property containing attachment path(s).
      * Supports a single path string or an array of path strings.
      */
-    attachmentsProperty?: string;
+    readonly attachmentsProperty?: string;
 }
 /**
  * Session lifecycle tool reference.
  *
- * Can be either:
- * - a plain tool name string (legacy/simple form)
- * - a {@link SessionToolConfig} object (explicit mapping form)
+ * Object form only — the bare-string binding was removed in 0.2.0. Use
+ * `{ name: 'tool_name' }` in place of `'tool_name'`.
  */
-type SessionToolBinding<Callable extends string = StandardAgentSpec.Callables> = Callable | SessionToolConfig<Callable>;
+type SessionToolBinding<Callable extends string = StandardAgentSpec.Callables> = SessionToolConfig<Callable>;
 /**
- * Configuration for one side of an agent conversation.
+ * A side backed by a human: a person takes this side's turns, through
+ * whatever interface the runtime provides.
+ *
+ * The specification defines only the waiting state — execution parks
+ * awaiting human input, fulfilled by an inbound message on this side's
+ * perspective. Who the person is and how their input arrives is the
+ * runtime's concern.
  *
- * Each side has a prompt, stop conditions, and turn limits.
- * For `ai_human` agents, only sideA (the AI) needs configuration.
- * For `dual_ai` agents, both sides need configuration.
+ * Human-backed sides cannot own subagent relationships (nothing there can
+ * invoke them) and have no step, stop, or session-binding options.
+ */
+interface HumanSide {
+    /** Marks this side as human-backed. */
+    readonly human: true;
+    /**
+     * Custom label for this side of the conversation.
+     * Used in UI and logs for clarity.
+     */
+    readonly label?: string;
+    readonly prompt?: never;
+    readonly handler?: never;
+    readonly subagents?: never;
+    readonly stopOnResponse?: never;
+    readonly stopTool?: never;
+    readonly stopToolResponseProperty?: never;
+    readonly maxSteps?: never;
+    readonly sessionStop?: never;
+    readonly sessionFail?: never;
+    readonly sessionStatus?: never;
+}
+/**
+ * A side backed by a prompt: a model takes this side's turns.
  *
  * @template Prompt - The prompt reference type (string or type-safe union)
  * @template Callable - The callable reference type (string or type-safe union)
- *
- * @example
- * ```typescript
- * const sideConfig: SideConfig = {
- *   label: 'Support Agent',
- *   prompt: 'customer_support',
- *   stopOnResponse: true,
- *   maxSteps: 10,
- * };
- * ```
  */
-interface SideConfig<Prompt extends string = StandardAgentSpec.Prompts, Callable extends string = StandardAgentSpec.Callables> {
+interface PromptSide<Prompt extends string = StandardAgentSpec.Prompts, Callable extends string = StandardAgentSpec.Callables> {
+    /**
+     * The prompt to use for this side.
+     * Must reference a prompt defined in agents/prompts/.
+     */
+    readonly prompt: Prompt;
     /**
      * Custom label for this side of the conversation.
      * Used in UI and logs for clarity.
      *
      * @example 'Support Agent', 'Customer', 'ATC', 'Pilot'
      */
-    label?: string;
+    readonly label?: string;
     /**
-     * The prompt to use for this side.
-     * Must reference a prompt defined in agents/prompts/.
+     * Subagent relationships OWNED by this side.
+     *
+     * The owning side's prompt automatically receives the lifecycle tools
+     * (`subagents`, `subagent_create`, `subagent_message`) for the side's
+     * non-hidden relationships — the side's declaration is the grant. Inbound
+     * child traffic lands on this side's perspective.
      */
-    prompt: Prompt;
+    readonly subagents?: readonly SubagentRelationship[];
     /**
      * Stop this side's turn when it returns a text response (no tool calls).
      * When true, the side's turn ends after producing a message without tools.
      * @default true
      */
-    stopOnResponse?: boolean;
+    readonly stopOnResponse?: boolean;
     /**
      * Stop this side's turn when a specific tool is called.
      * Overrides stopOnResponse when the named tool is invoked.
      * Requires stopToolResponseProperty to extract the result.
      */
-    stopTool?: Callable;
+    readonly stopTool?: Callable;
     /**
      * Property to extract from the stop tool's result.
      * Required when stopTool is set.
      * The extracted value is used to determine the conversation outcome.
      */
-    stopToolResponseProperty?: string;
+    readonly stopToolResponseProperty?: string;
     /**
      * Maximum steps for this side before forcing a stop.
      * Safety limit to prevent runaway execution.
      * A step is one complete LLM request/response cycle.
      */
-    maxSteps?: number;
+    readonly maxSteps?: number;
     /**
      * Tool that ends the entire session when called.
      *
      * Different from stopTool: this ends the session for both sides,
-     * not just this side's turn.
-     *
-     * Use object form to explicitly map message/attachment argument fields.
+     * not just this side's turn. Ending a session never terminates the thread.
      *
      * In subagent runtimes, mapped message/attachments are the canonical
      * completion payload returned from child -> parent.
      */
-    sessionStop?: SessionToolBinding<Callable>;
+    readonly sessionStop?: SessionToolBinding<Callable>;
     /**
      * Tool that fails the entire session when called.
      *
-     * Use this when the side cannot fulfill the request and needs to terminate
-     * the session with an error outcome.
-     *
-     * When used inside a subagent, this failure is propagated back to the parent
-     * as a terminal failure result.
+     * Use this when the side cannot fulfill the request and needs to end
+     * the session with an error outcome. Failing a session never terminates
+     * the thread.
      *
-     * Use object form to explicitly map message/attachment argument fields.
+     * When used inside a subagent, this failure is propagated back to the
+     * parent as a terminal failure result.
      *
      * In subagent runtimes, mapped message/attachments are the canonical
      * failure payload returned from child -> parent.
      */
-    sessionFail?: SessionToolBinding<Callable>;
+    readonly sessionFail?: SessionToolBinding<Callable>;
     /**
-     * Tool that publishes status updates to the parent thread when used as a subagent.
+     * Tool that publishes status updates to the parent thread when this agent
+     * runs as a subagent.
      *
-     * When called from a `dual_ai` subagent, message text is forwarded to
-     * the parent thread's subagent registry as this instance's current status.
-     *
-     * Use object form to explicitly map message/attachment argument fields.
-     *
-     * Status updates do not terminate the session.
+     * Message text is forwarded to the parent thread's subagent registry as
+     * this instance's current working status. Status updates do not end the
+     * session.
      *
      * @example
      * ```typescript
@@ -4466,14 +4521,66 @@ interface SideConfig<Prompt extends string = StandardAgentSpec.Prompts, Callable
      * }
      * ```
      */
-    sessionStatus?: SessionToolBinding<Callable>;
+    readonly sessionStatus?: SessionToolBinding<Callable>;
+    readonly human?: never;
+    readonly handler?: never;
+}
+/**
+ * A side backed by a handler: deterministic code takes this side's turns.
+ *
+ * A handler turn has no steps to cap and ends when `execute` returns, so
+ * step, stop, and session-binding options are not legal here — handlers end
+ * sessions explicitly via `state.stopSession()`.
+ *
+ * @template Handler - The handler reference type (string or type-safe union)
+ */
+interface HandlerSide<Handler extends string = StandardAgentSpec.Handlers> {
+    /**
+     * The handler that takes this side's turns.
+     * Must reference a handler defined in agents/handlers/.
+     */
+    readonly handler: Handler;
+    /**
+     * Custom label for this side of the conversation.
+     * Used in UI and logs for clarity.
+     */
+    readonly label?: string;
+    /**
+     * Subagent relationships OWNED by this side.
+     *
+     * Handlers need no tool grant; they reach children through `ThreadState`.
+     * The declaration's job for a handler side is existence and lifecycle.
+     * Inbound child traffic lands on this side's perspective.
+     */
+    readonly subagents?: readonly SubagentRelationship[];
+    readonly human?: never;
+    readonly prompt?: never;
+    readonly stopOnResponse?: never;
+    readonly stopTool?: never;
+    readonly stopToolResponseProperty?: never;
+    readonly maxSteps?: never;
+    readonly sessionStop?: never;
+    readonly sessionFail?: never;
+    readonly sessionStatus?: never;
 }
+/**
+ * Configuration for one side of an agent conversation.
+ *
+ * Exactly one backing per side: `human`, `prompt`, or `handler`. Both sides
+ * human is reserved — runtimes MUST reject it in this version.
+ *
+ * @template Prompt - The prompt reference type (string or type-safe union)
+ * @template Callable - The callable reference type (string or type-safe union)
+ * @template Handler - The handler reference type (string or type-safe union)
+ */
+type SideConfig<Prompt extends string = StandardAgentSpec.Prompts, Callable extends string = StandardAgentSpec.Callables, Handler extends string = StandardAgentSpec.Handlers> = HumanSide | PromptSide<Prompt, Callable> | HandlerSide<Handler>;
 /**
  * Agent definition configuration.
  *
  * @template N - The agent name as a string literal type
  * @template Prompt - The prompt reference type (string or type-safe union)
  * @template Callable - The callable reference type (string or type-safe union)
+ * @template Handler - The handler reference type (string or type-safe union)
  *
  * @example
  * ```typescript
@@ -4481,63 +4588,65 @@ interface SideConfig<Prompt extends string = StandardAgentSpec.Prompts, Callable
  *
  * export default defineAgent({
  *   name: 'support_agent',
- *   title: 'Customer Support Agent',
- *   type: 'ai_human',
  *   sideA: {
  *     label: 'Support',
  *     prompt: 'customer_support',
  *     stopOnResponse: true,
  *   },
+ *   sideB: { human: true },
  * });
  * ```
  */
-interface AgentDefinition<N extends string = string, Prompt extends string = StandardAgentSpec.Prompts, Callable extends string = StandardAgentSpec.Callables> {
+interface AgentDefinition<N extends string = string, Prompt extends string = StandardAgentSpec.Prompts, Callable extends string = StandardAgentSpec.Callables, Handler extends string = StandardAgentSpec.Handlers> {
     /**
      * Unique name for this agent.
      * Used as the identifier for thread creation and handoffs.
      * Should be snake_case (e.g., 'support_agent', 'research_flow').
      */
-    name: N;
+    readonly name: N;
     /**
      * Human-readable title for the agent.
      * Optional - if not provided, the name will be used.
      * @deprecated Use name instead. Title will be removed in a future version.
      */
-    title?: string;
+    readonly title?: string;
     /**
-     * Agent conversation type.
-     *
-     * - `ai_human`: AI conversing with a human user (default)
-     * - `dual_ai`: Two AI participants conversing
-     *
-     * @default 'ai_human'
+     * @deprecated Removed in 0.2.0 — there is no agent "type". Delete this
+     * field and declare both sides explicitly: what used to be
+     * `type: 'ai_human'` is `sideB: { human: true }`; what used to be
+     * `type: 'dual_ai'` is two prompt-backed sides. See the migration guide:
+     * https://standardagentspec.com/0.2.0/getting-started/changelog
      */
-    type?: AgentType;
+    readonly type?: never;
     /**
-     * Maximum total turns across both sides.
-     * Only applies to `dual_ai` agents.
-     * Prevents infinite loops in AI-to-AI conversations.
+     * Maximum total exchanges across both sides before the runtime ends the
+     * session.
+     *
+     * Optional on every side combination — a voluntary safety valve, not a
+     * requirement. Exchange counting is uniform across backings: a handler
+     * turn counts exactly like a prompt turn. Reaching the cap ends the
+     * session; it never terminates the thread.
      */
-    maxSessionTurns?: number;
+    readonly maxSessionTurns?: number;
     /**
-     * Configuration for Side A.
-     * For `ai_human`: This is the AI side.
-     * For `dual_ai`: This is the first AI participant.
+     * Configuration for side A. Backed by exactly one of `human`, `prompt`,
+     * or `handler`.
      */
-    sideA: SideConfig<Prompt, Callable>;
+    readonly sideA: SideConfig<Prompt, Callable, Handler>;
     /**
-     * Configuration for Side B.
-     * For `ai_human`: Optional, the human side doesn't need config.
-     * For `dual_ai`: Required, the second AI participant.
+     * Configuration for side B. Backed by exactly one of `human`, `prompt`,
+     * or `handler`. Both sides are always explicit — for a chat agent this is
+     * `sideB: { human: true }`.
      */
-    sideB?: SideConfig<Prompt, Callable>;
+    readonly sideB: SideConfig<Prompt, Callable, Handler>;
     /**
      * Expose this agent as a tool for other prompts.
      * Enables agent composition and handoffs.
-     * When true, other prompts can invoke this agent as a tool.
+     * When true, other prompts can invoke this agent as a tool and sides can
+     * declare subagent relationships targeting it.
      * @default false
      */
-    exposeAsTool?: boolean;
+    readonly exposeAsTool?: boolean;
     /**
      * Whether this agent is a PRIMARY, user-facing entry point (default true).
      *
@@ -4548,36 +4657,36 @@ interface AgentDefinition<N extends string = string, Prompt extends string = Sta
      * visible; UIs use this flag to keep them out of top-level agent lists
      * and pickers so one logical product agent doesn't show up N times.
      */
-    primary?: boolean;
+    readonly primary?: boolean;
     /**
      * Description shown when agent is used as a tool.
      * Required if exposeAsTool is true.
      * Should clearly describe what this agent does.
      */
-    toolDescription?: string;
+    readonly toolDescription?: string;
     /**
      * Brief description of what this agent does.
      * Useful for UIs and documentation.
      *
      * @example 'Handles customer support inquiries and resolves issues'
      */
-    description?: string;
+    readonly description?: string;
     /**
      * Icon URL or absolute path for the agent.
      * Absolute paths (starting with `/`) are converted to full URLs in API responses.
      *
      * @example 'https://example.com/icon.svg' or '/icons/support.svg'
      */
-    icon?: string;
+    readonly icon?: string;
     /**
      * Environment values provided by this agent.
      * Agent values are lower priority than thread/account/instance values.
      */
-    env?: Record<string, string>;
+    readonly env?: Readonly<Record<string, string>>;
     /**
      * @deprecated Use `env` instead.
      */
-    tenvs?: Record<string, unknown>;
+    readonly tenvs?: Readonly<Record<string, unknown>>;
     /**
      * npm package name for this agent when packed.
      * Used by the packing system to maintain consistent package identity
@@ -4585,7 +4694,7 @@ interface AgentDefinition<N extends string = string, Prompt extends string = Sta
      *
      * @example 'standardagent-support-agent', '@myorg/support-agent'
      */
-    packageName?: string;
+    readonly packageName?: string;
     /**
      * Package version (semver format).
      * Used by the packing system to track versions across pack/unpack cycles.
@@ -4593,21 +4702,21 @@ interface AgentDefinition<N extends string = string, Prompt extends string = Sta
      *
      * @example '1.0.0', '2.3.1-beta.1'
      */
-    version?: string;
+    readonly version?: string;
     /**
      * Package author/copyright holder.
      * Used by the packing system for the LICENSE file and package.json author field.
      *
      * @example 'John Doe', 'Acme Corp'
      */
-    author?: string;
+    readonly author?: string;
     /**
      * License identifier (SPDX format).
      * Used by the packing system for LICENSE file generation.
      *
      * @example 'MIT', 'Apache-2.0', 'ISC'
      */
-    license?: string;
+    readonly license?: string;
     /**
      * Hook IDs to run for this agent.
      * References hooks by their unique `id` property from defineHook().
@@ -4618,15 +4727,15 @@ interface AgentDefinition<N extends string = string, Prompt extends string = Sta
      * hooks: ['log_messages', 'track_tool_usage']
      * ```
      */
-    hooks?: StandardAgentSpec.HookIds[];
+    readonly hooks?: readonly StandardAgentSpec.HookIds[];
     /**
-     * Hooks this agent requires on a direct parent when composed as a `dual_ai`
-     * child tool.
+     * Hooks this agent requires on a direct parent when composed as a child.
      *
-     * Adding an enabled relationship activates these hooks automatically;
-     * downloading the package alone does not. Hooks execute against the
-     * parent's ThreadState and are resolved in this agent's package namespace.
-     * `reason` is required so composition tooling can disclose the behavior.
+     * Legal on any exposed agent. Adding an enabled relationship activates
+     * these hooks automatically; downloading the package alone does not.
+     * Hooks execute against the parent's ThreadState and are resolved in this
+     * agent's package namespace. `reason` is required so composition tooling
+     * can disclose the behavior.
      *
      * @example
      * ```typescript
@@ -4637,14 +4746,18 @@ interface AgentDefinition<N extends string = string, Prompt extends string = Sta
      * }]
      * ```
      */
-    parentHooks?: ParentHookRequirement[];
+    readonly parentHooks?: readonly ParentHookRequirement[];
 }
 /**
  * Defines an agent configuration.
  *
- * Agents orchestrate conversations between AI models, or between AI and
- * human users. They use prompts to configure each side of the conversation
- * and define stop conditions to control conversation flow.
+ * An agent has exactly two sides; each side is backed by a human, a prompt,
+ * or a handler. Prompts and handlers own turns; humans park execution
+ * awaiting input.
+ *
+ * Definition-time validation runs {@link validateAgentDefinition} and throws
+ * with every error found, so a stale 0.1.0 shape fails with messages naming
+ * exactly what to change.
  *
  * @template N - The agent name as a string literal type
  * @param options - Agent configuration options
@@ -4652,19 +4765,15 @@ interface AgentDefinition<N extends string = string, Prompt extends string = Sta
  *
  * @example
  * ```typescript
- * // agents/agents/support_agent.ts
- * import { defineAgent } from '@standardagents/spec';
- *
+ * // Chat agent: model on side A, person on side B
  * export default defineAgent({
  *   name: 'support_agent',
- *   title: 'Customer Support Agent',
- *   type: 'ai_human',
  *   sideA: {
  *     label: 'Support',
  *     prompt: 'customer_support',
- *     stopOnResponse: true,
- *     sessionStop: 'close_ticket',
+ *     sessionStop: { name: 'close_ticket' },
  *   },
+ *   sideB: { human: true },
  *   exposeAsTool: true,
  *   toolDescription: 'Hand off to customer support',
  * });
@@ -4672,22 +4781,28 @@ interface AgentDefinition<N extends string = string, Prompt extends string = Sta
  *
  * @example
  * ```typescript
- * // Dual AI agent (two AIs conversing)
+ * // Relay agent: deterministic code on side A, person on side B
  * export default defineAgent({
- *   name: 'debate_agent',
- *   title: 'AI Debate',
- *   type: 'dual_ai',
- *   maxSessionTurns: 10,
+ *   name: 'relay_agent',
  *   sideA: {
- *     label: 'Pro',
- *     prompt: 'debate_pro',
- *     stopOnResponse: true,
+ *     handler: 'relay_pipe',
+ *     subagents: [{ agent: 'assistant_agent', maxInstances: 1 }],
  *   },
+ *   sideB: { human: true },
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Two models conversing
+ * export default defineAgent({
+ *   name: 'debate_agent',
+ *   maxSessionTurns: 10,
+ *   sideA: { label: 'Pro', prompt: 'debate_pro' },
  *   sideB: {
  *     label: 'Con',
  *     prompt: 'debate_con',
- *     stopOnResponse: true,
- *     sessionStop: 'conclude_debate',
+ *     sessionStop: { name: 'conclude_debate' },
  *   },
  * });
  * ```
@@ -4853,6 +4968,10 @@ interface ControllerContext {
     tools?: VirtualModuleRegistry<unknown>;
     /** Registry of hook definitions (injected at runtime) */
     hooks?: VirtualModuleRegistry<unknown>;
+    /** Registry of handler definitions (injected at runtime) */
+    handlers?: VirtualModuleRegistry<unknown>;
+    /** Available handler names */
+    handlerNames?: string[];
     /** Additional configuration (injected at runtime) */
     config?: Record<string, unknown>;
 }
@@ -5825,4 +5944,202 @@ interface HookDefinitionResult<K extends HookName> {
  */
 declare function defineHook<K extends HookName>(options: HookDefinitionOptions<K>): HookDefinitionResult<K>;
 
-export { type AgentDefinition, type AgentType, type AttachmentRef, type CodeExecution, type CodeExecutionError, type CodeExecutionLog, type CodeExecutionOptions, type CodeExecutionResult, type CodeExecutionStatus, type ContentPart, type Controller, type ControllerContext, type ControllerReturn, type CreateFetch, type CredentialGrant, type DefineToolOptions, type DefinitionLoader, ENDPOINT_ACCESS_SYMBOL, type Effect, type EffectDefinition, type EmptyUsesState, type EndpointAccess, type EndpointOptions, type EnvValueType, type ErrorOrigin, type ExecutionState, type FetchLike, type FileChunk, type FilePart, type FileRecord, type FileStats, type FileStorage, type FindResult, type GetMessagesOptions, type GlobalNamespaceContext, type GrepResult, type HookContext, type HookDefinition, type HookDefinitionOptions, type HookDefinitionResult, type HookExecutionContext, type HookExecutionSource, type HookMessage, type HookName, type HookSignatures, type HookToolCall, type HookToolResult, type ImageContent, type ImagePart, type ImageUrlPart, type InferProviderOptions, type InjectMessageInput, type InspectedRequest, type LLMMessage, type LLMProviderInterface, type ListUserThreadsOptions, type ListUserValuesOptions, type MarkedThreadEndpoint, type MarkedUserEndpoint, type Message, type MessageUpdates, type MessagesResult, type ModelCapabilities, type ModelDefinition, type ModelProvider, type NamespaceContext, type PackageSignature, type PackedExports, type PackedMeta, type PackedMetadata, type PackedNamespaceContext, type ParentHookRequirement, type ParentHookStage, type PromptContent, type PromptDefinition, type PromptEnvPart, type PromptIncludePart, type PromptInput, type PromptPart, type PromptTextPart, type PromptToolConfig, type ProviderAssistantMessage, type ProviderAttachment, type ProviderConfigSlot, type ProviderConfigSlots, type ProviderConfigValueSource, type ProviderDefinition, ProviderError, type ProviderErrorCode, type ProviderErrorOptions, type ProviderExecutedToolResult, type ProviderFactory, type ProviderFactoryConfig, type ProviderFactoryWithOptions, type ProviderFinishReason, type ProviderGeneratedImage, type ProviderInstance, type ProviderMessage, type ProviderMessageContent, type ProviderMethodOverrides, type ProviderModelInfo, type ProviderModelsPage, type ProviderModelsQuery, type ProviderOverride, type ProviderOverrideContext, type ProviderReasoningDetail, type ProviderRequest, type ProviderResponse, type ProviderStreamChunk, type ProviderSyncOverride, type ProviderSystemMessage, type ProviderTool, type ProviderToolCallPart, type ProviderToolMessage, type ProviderToolResultContent, type ProviderUsage, type ProviderUsagePricing, type ProviderUserMessage, type ProviderWebSearchResult, type QueueMessageInput, type ReadFileStreamOptions, type ReaddirResult, type ReasoningConfig, type ResolveUsesState, type ResponseSummary, type RuntimeByteStream, type RuntimeStreamErrorCode, type RuntimeStreamRequest, type RuntimeStreamResult, type RuntimeStreams, type ScheduledEffect, type SessionToolBinding, type SessionToolConfig, type SetEnvOptions, type SideConfig, type SkillFileInput, type SkillMetadata, type SkillsNamespace, type StopSessionOptions, type StructuredPrompt, type SubagentRegistryEntry, type SubagentToolConfig, type SubpromptConfig, THREAD_ENDPOINT_SYMBOL, THREAD_STREAM_REASONING_PARAM, type TenvRawShape, type TextContent, type TextPart, type ThreadEndpointAuth, type ThreadEndpointHandler, type ThreadEndpointRouteParams, type ThreadHookName, type ThreadMessageChunkEvent, type ThreadMetadata, type ThreadReasoningChunkEvent, type ThreadState, type ThreadUser, type Tool, type ToolArgs, type ToolArgsNode, type ToolArgsRawShape, type ToolAttachment, type ToolConfig, type ToolContent, type ToolDefinition, type ToolResult, type ToolTenvs, type ToolVariables, USER_ENDPOINT_SYMBOL, type UserClientInfo, type UserEndpointHandler, type UserEndpointRouteParams, type UserHandle, type UserIdentity, type UserState, type UserThreadSummary, type UserValueEntry, type UsesAwareExecute, type UsesConstrainedState, type VariableDefinition, type VariableType, type VirtualModuleLoader, type VirtualModuleRegistry, type WriteFileOptions, belongsToPackage, defineAgent, defineController, defineEffect, defineHook, defineModel, definePrompt, defineProvider, defineThreadEndpoint, defineTool, defineUserEndpoint, getEndpointAccess, isPacked, isThreadEndpoint, isUserEndpoint, isVisibleInNamespace, mapReasoningLevel, providerConst, providerEnv, providerValue, validateToolName };
+/**
+ * Handler definition types for Standard Agents.
+ *
+ * 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 — 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 seat is backing a side of an agent: handlers
+ * MUST NOT be referenced by prompt `tools` arrays, hook lists, or effect
+ * schedules, and implementations MUST reject such references at definition
+ * time.
+ *
+ * https://standardagentspec.com/0.2.0/specification/handlers
+ *
+ * @module
+ */
+
+/**
+ * Brand marking a value as a handler definition.
+ *
+ * The brand makes `HandlerDefinition` structurally unassignable to tool,
+ * hook, and effect positions, so a handler referenced where those are
+ * expected fails to compile wherever TypeScript can see the reference.
+ * Implementations additionally reject by-name references that types cannot
+ * catch during their definition-registry pass.
+ */
+declare const HANDLER_SYMBOL: unique symbol;
+/**
+ * A handler definition — deterministic code that owns one side's turns.
+ *
+ * Execution model (one turn):
+ * 1. An inbound message arrives on the side's perspective.
+ * 2. The runtime invokes `execute` 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 a
+ * handler-backed side. When the agent sets `maxSessionTurns`, a handler turn
+ * counts toward the exchange cap exactly like a prompt turn.
+ *
+ * Delivery is exactly-once per message, in message persistence order, one
+ * invocation at a time per thread; messages that arrive while a turn is in
+ * flight wait in the queue. A failed invocation is never automatically
+ * redelivered — retry is a userland decision.
+ *
+ * Errors are fatal to the turn, and only the turn: the turn is marked failed
+ * as a runtime-origin failure, the inbound message stays persisted, and the
+ * session continues. A handler ends sessions explicitly via
+ * `state.stopSession()`.
+ *
+ * @template State - The thread state type (defaults to {@link ThreadState})
+ */
+interface HandlerDefinition<State = ThreadState> {
+    /** Optional human-facing summary of what this handler does. */
+    readonly description?: string;
+    /**
+     * The turn implementation.
+     *
+     * Receives the full `ThreadState` — it may forward (`queueMessage` toward a
+     * child), respond (`injectMessage` as its own side's role), spawn children,
+     * stop the session, and read/write thread values: anything tools can do.
+     *
+     * The `message` parameter is the full persisted {@link Message} — id, role,
+     * content, silent flag, metadata, timestamps — not a narrowed view:
+     * handlers are trusted definition code, like tools.
+     *
+     * There is no auto-reply channel: the runtime routes inbound; userland
+     * decides outbound. If the handler wants to speak outward, that is code in
+     * this function.
+     */
+    readonly execute: (state: State, message: Message) => Promise<void>;
+    readonly [HANDLER_SYMBOL]: true;
+}
+/**
+ * Options accepted by {@link defineHandler}.
+ *
+ * @template State - The thread state type (defaults to {@link ThreadState})
+ */
+interface DefineHandlerOptions<State = ThreadState> {
+    /** Optional human-facing summary of what this handler does. */
+    readonly description?: string;
+    /** The turn implementation. See {@link HandlerDefinition.execute}. */
+    readonly execute: (state: State, message: Message) => Promise<void>;
+}
+/**
+ * Defines a handler — deterministic code that backs one side of an agent and
+ * takes that side's turns in place of a model.
+ *
+ * Handlers live in their own definition directory (`agents/handlers/` in the
+ * conventional layout). The handler's name is derived from its file name and
+ * referenced from exactly one place: the `handler` property of a side
+ * configuration.
+ *
+ * @template State - The thread state type (defaults to {@link ThreadState})
+ * @param options - Handler configuration options
+ * @returns The branded handler definition for registration
+ *
+ * @example
+ * ```typescript
+ * // agents/handlers/relay_pipe.ts
+ * import { defineHandler } from '@standardagents/spec';
+ *
+ * export default defineHandler({
+ *   description: 'Forwards inbound user traffic to the assistant child and relays answers back.',
+ *   execute: async (state, message) => {
+ *     const assistant = state.children.find(c => c.relationship === 'assistant_agent');
+ *     if (!assistant) return;
+ *     const child = await state.getChildThread(assistant.reference);
+ *     await child?.queueMessage({ role: 'user', content: message.content ?? '' });
+ *   },
+ * });
+ * ```
+ */
+declare function defineHandler<State = ThreadState>(options: DefineHandlerOptions<State>): HandlerDefinition<State>;
+/**
+ * Type guard: is this value a handler definition created by
+ * {@link defineHandler}?
+ */
+declare function isHandler(value: unknown): value is HandlerDefinition;
+
+/**
+ * Pure definition-time validation for Standard Agents.
+ *
+ * `validateAgentDefinition` covers everything the type system cannot express
+ * structurally: the single-owner rule across sides, reserved relationship
+ * names, the both-sides-human gate, parentHooks shape, and legible rejection
+ * of removed 0.1.0 fields. Implementations wire it into definition loading
+ * so a stale 0.1.0 project's boot failure doubles as its migration
+ * checklist.
+ *
+ * Existence checks (does the referenced prompt/handler/agent actually
+ * exist?) and real tool-name collision checks require the definition
+ * registry and are the implementation's responsibility; this module is pure
+ * and dependency-free.
+ *
+ * @module
+ */
+/**
+ * Every issue code `validateAgentDefinition` can emit.
+ */
+declare const DEFINITION_ISSUE_CODES: readonly ["agent_name_missing", "agent_name_invalid", "agent_side_missing", "agent_side_invalid", "agent_side_backing_missing", "agent_side_backing_conflict", "agent_side_option_invalid_for_backing", "agent_subagents_on_human_side", "agent_both_sides_human", "agent_legacy_type", "agent_session_binding_legacy_string", "agent_session_binding_invalid", "agent_stop_tool_response_property_missing", "agent_max_steps_invalid", "agent_max_session_turns_invalid", "agent_tool_description_missing", "agent_parent_hooks_invalid", "agent_tenvs_deprecated", "subagent_agent_missing", "subagent_relationship_invalid", "subagent_relationship_duplicate", "subagent_relationship_reserved_name", "subagent_max_instances_invalid", "subagent_legacy_name", "subagent_legacy_resumable", "subagent_legacy_receives_messages"];
+/**
+ * Union of all definition issue codes.
+ */
+type DefinitionIssueCode = (typeof DEFINITION_ISSUE_CODES)[number];
+/**
+ * One problem found in a definition.
+ */
+interface DefinitionIssue {
+    /** Stable machine-readable code for this issue. */
+    readonly code: DefinitionIssueCode;
+    /** Errors block loading; warnings should be reported once, loudly. */
+    readonly severity: 'error' | 'warning';
+    /** Human-facing message naming exactly what to change. */
+    readonly message: string;
+    /** Dot/bracket path to the offending field (e.g. `sideA.subagents[1].as`). */
+    readonly path: string;
+}
+/**
+ * Relationship names reserved for the runtime-injected subagent lifecycle
+ * tools. A relationship `as` name colliding with one of these is a
+ * definition-time error.
+ */
+declare const RESERVED_RELATIONSHIP_NAMES: readonly ["subagents", "subagent_create", "subagent_message"];
+/**
+ * Validates one agent definition, purely and without a registry.
+ *
+ * Accepts `unknown` so removed 0.1.0 shapes — which no longer typecheck —
+ * can still be diagnosed with legible, field-naming errors at load time.
+ *
+ * @param def - The candidate agent definition
+ * @returns Every issue found; empty when the definition is valid
+ */
+declare function validateAgentDefinition(def: unknown): DefinitionIssue[];
+
+/**
+ * @standardagents/spec
+ *
+ * Standard Agents Specification - TypeScript types and definitions.
+ *
+ * This package provides the canonical type definitions and helper functions
+ * for the Standard Agents specification. It serves as the source of truth
+ * for all agent, model, prompt, tool, hook, and endpoint definitions.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The Standard Agent Specification version these types implement.
+ * Implementations report conformance against exactly one version.
+ */
+declare const SPEC_VERSION = "0.2.0";
+
+export { type AgentDefinition, type AgentType, type AttachmentRef, type CodeExecution, type CodeExecutionError, type CodeExecutionLog, type CodeExecutionOptions, type CodeExecutionResult, type CodeExecutionStatus, type ContentPart, type Controller, type ControllerContext, type ControllerReturn, type CreateFetch, type CredentialGrant, DEFINITION_ISSUE_CODES, type DefineHandlerOptions, type DefineToolOptions, type DefinitionIssue, type DefinitionIssueCode, type DefinitionLoader, ENDPOINT_ACCESS_SYMBOL, type Effect, type EffectDefinition, type EmptyUsesState, type EndpointAccess, type EndpointOptions, type EnvValueType, type ErrorOrigin, type ExecutionState, type FetchLike, type FileChunk, type FilePart, type FileRecord, type FileStats, type FileStorage, type FindResult, type GetMessagesOptions, type GlobalNamespaceContext, type GrepResult, HANDLER_SYMBOL, type HandlerDefinition, type HandlerSide, type HookContext, type HookDefinition, type HookDefinitionOptions, type HookDefinitionResult, type HookExecutionContext, type HookExecutionSource, type HookMessage, type HookName, type HookSignatures, type HookToolCall, type HookToolResult, type HumanSide, type ImageContent, type ImagePart, type ImageUrlPart, type InferProviderOptions, type InjectMessageInput, type InspectedRequest, type LLMMessage, type LLMProviderInterface, type ListUserThreadsOptions, type ListUserValuesOptions, type MarkedThreadEndpoint, type MarkedUserEndpoint, type Message, type MessageUpdates, type MessagesResult, type ModelCapabilities, type ModelDefinition, type ModelProvider, type NamespaceContext, type PackageSignature, type PackedExports, type PackedMeta, type PackedMetadata, type PackedNamespaceContext, type ParentHookRequirement, type ParentHookStage, type PromptContent, type PromptDefinition, type PromptEnvPart, type PromptIncludePart, type PromptInput, type PromptPart, type PromptSide, type PromptTextPart, type PromptToolConfig, type ProviderAssistantMessage, type ProviderAttachment, type ProviderConfigSlot, type ProviderConfigSlots, type ProviderConfigValueSource, type ProviderDefinition, ProviderError, type ProviderErrorCode, type ProviderErrorOptions, type ProviderExecutedToolResult, type ProviderFactory, type ProviderFactoryConfig, type ProviderFactoryWithOptions, type ProviderFinishReason, type ProviderGeneratedImage, type ProviderInstance, type ProviderMessage, type ProviderMessageContent, type ProviderMethodOverrides, type ProviderModelInfo, type ProviderModelsPage, type ProviderModelsQuery, type ProviderOverride, type ProviderOverrideContext, type ProviderReasoningDetail, type ProviderRequest, type ProviderResponse, type ProviderStreamChunk, type ProviderSyncOverride, type ProviderSystemMessage, type ProviderTool, type ProviderToolCallPart, type ProviderToolMessage, type ProviderToolResultContent, type ProviderUsage, type ProviderUsagePricing, type ProviderUserMessage, type ProviderWebSearchResult, type QueueMessageInput, RESERVED_RELATIONSHIP_NAMES, type ReadFileStreamOptions, type ReaddirResult, type ReasoningConfig, type ResolveUsesState, type ResponseSummary, type RuntimeByteStream, type RuntimeStreamErrorCode, type RuntimeStreamRequest, type RuntimeStreamResult, type RuntimeStreams, SPEC_VERSION, type ScheduledEffect, type SessionToolBinding, type SessionToolConfig, type SetEnvOptions, type SideConfig, type SkillFileInput, type SkillMetadata, type SkillsNamespace, type StopSessionOptions, type StructuredPrompt, type SubagentRegistryEntry, type SubagentRelationship, type SubagentToolConfig, type SubpromptConfig, THREAD_ENDPOINT_SYMBOL, THREAD_STREAM_REASONING_PARAM, type TenvRawShape, type TextContent, type TextPart, type ThreadEndpointAuth, type ThreadEndpointHandler, type ThreadEndpointRouteParams, type ThreadHookName, type ThreadMessageChunkEvent, type ThreadMetadata, type ThreadReasoningChunkEvent, type ThreadState, type ThreadUser, type Tool, type ToolArgs, type ToolArgsNode, type ToolArgsRawShape, type ToolAttachment, type ToolConfig, type ToolContent, type ToolDefinition, type ToolResult, type ToolTenvs, type ToolVariables, USER_ENDPOINT_SYMBOL, type UserClientInfo, type UserEndpointHandler, type UserEndpointRouteParams, type UserHandle, type UserIdentity, type UserState, type UserThreadSummary, type UserValueEntry, type UsesAwareExecute, type UsesConstrainedState, type VariableDefinition, type VariableType, type VirtualModuleLoader, type VirtualModuleRegistry, type WriteFileOptions, belongsToPackage, defineAgent, defineController, defineEffect, defineHandler, defineHook, defineModel, definePrompt, defineProvider, defineThreadEndpoint, defineTool, defineUserEndpoint, getEndpointAccess, isHandler, isPacked, isThreadEndpoint, isUserEndpoint, isVisibleInNamespace, mapReasoningLevel, providerConst, providerEnv, providerValue, validateAgentDefinition, validateToolName };