@standardagents/spec 0.12.9 → 0.13.0

package/dist/index.d.ts

@@ -207,6 +207,33 @@ interface ThreadMetadata {
     /** Creation timestamp (microseconds since epoch) */
     created_at: number;
 }
+/**
+ * Registry entry for a subagent child thread.
+ */
+interface SubagentRegistryEntry {
+    /** Child thread UUID used as stable reference address */
+    reference: string;
+    /** Child agent 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) */
+    threadName?: string;
+    /** 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) */
+    status: string;
+    /** How this child reports information back to its parent thread */
+    parentCommunication?: 'implicit' | 'explicit';
+}
 /**
  * Options for retrieving messages.
  */
@@ -257,12 +284,35 @@ interface Message {
     depth?: number;
     /** Whether this message is silent (not shown in UI) */
     silent?: boolean;
-    /** Custom metadata */
+    /**
+     * Custom metadata.
+     *
+     * Runtimes may attach lifecycle metadata for synthesized status messages
+     * (for example: `status_kind`, `subagent_event`).
+     */
     metadata?: Record<string, unknown>;
     /** Message processing status */
     status?: 'pending' | 'completed' | 'failed' | null;
     /** Tool execution status (for tool result messages) */
     tool_status?: 'success' | 'error' | null;
+    /** Subagent reference UUID associated with this message */
+    subagent_id?: string | null;
+    /** Subagent agent name projected from runtime registry (when available) */
+    subagent_name?: string | null;
+    /** Subagent agent title projected from runtime registry (when available) */
+    subagent_title?: string | null;
+    /** Subagent description projected from runtime registry (when available) */
+    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;
+    /** Whether the associated subagent is blocking (when available) */
+    subagent_blocking?: boolean | null;
+    /** Optional subagent instance thread name (when available) */
+    subagent_thread_name?: string | null;
+    /** Spawn group identifier for related subagent instances (when available) */
+    subagent_spawn_group_id?: string | null;
 }
 /**
  * Input for injecting a new message.
@@ -277,6 +327,25 @@ interface InjectMessageInput {
     /** Custom metadata */
     metadata?: Record<string, unknown>;
 }
+/**
+ * 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
+ */
+interface QueueMessageInput {
+    /** Message role (`user` queues side_b perspective, `assistant` queues side_a perspective) */
+    role: 'user' | 'assistant';
+    /** Message content */
+    content: string;
+    /** Optional file attachments (new files or existing refs) */
+    attachments?: Array<ToolAttachment | AttachmentRef>;
+    /** Whether to hide the queued message from normal UI display */
+    silent?: boolean;
+    /** Optional structured metadata */
+    metadata?: Record<string, unknown>;
+}
 /**
  * Updates to apply to an existing message.
  */
@@ -501,6 +570,17 @@ interface ThreadState {
     readonly userId: string | null;
     /** Thread creation timestamp (microseconds since epoch) */
     readonly createdAt: number;
+    /**
+     * Registry of subagent child instances owned by this thread.
+     *
+     * Includes both resumable and non-resumable instances.
+     */
+    readonly children: SubagentRegistryEntry[];
+    /**
+     * Termination timestamp (microseconds) if this thread has been terminated.
+     * Null when the thread is active.
+     */
+    readonly terminated: number | null;
     /**
      * Get messages from the thread.
      *
@@ -543,6 +623,13 @@ interface ThreadState {
      * @returns true if the message was found and deleted, false if not found
      */
     deleteMessage(messageId: string): Promise<boolean>;
+    /**
+     * Queue a message for delivery on the thread's next step.
+     *
+     * If the thread is executing, the message is delivered before the next LLM call.
+     * If idle, queueing forces execution by the queued side.
+     */
+    queueMessage(message: QueueMessageInput): Promise<void>;
     /**
      * Load a model definition by name.
      *
@@ -585,6 +672,64 @@ interface ThreadState {
      * @returns Array of model names that can be loaded
      */
     getModelNames(): string[];
+    /**
+     * Get a child thread by its subagent reference ID.
+     *
+     * @param referenceId - Child thread UUID
+     * @returns Child ThreadState or null if not found
+     */
+    getChildThread(referenceId: string): Promise<ThreadState | null>;
+    /**
+     * Get this thread's parent thread (if any).
+     *
+     * @returns Parent ThreadState, or null for top-level threads
+     */
+    getParentThread(): Promise<ThreadState | null>;
+    /**
+     * Resolve an environment value for this thread by property name.
+     *
+     * Resolution order:
+     * 1. Thread
+     * 2. User account
+     * 3. AgentBuilder instance
+     * 4. Agent definition
+     * 5. Prompt definition
+     *
+     * @throws If the variable is not defined in any source
+     */
+    env(propertyName: string): Promise<string>;
+    /**
+     * Set a thread-scoped environment variable.
+     *
+     * This writes to thread env storage and propagates the updated thread env
+     * to all active descendant threads recursively. Terminated descendants are
+     * not modified.
+     *
+     * @param propertyName - Environment variable name
+     * @param value - Environment variable value
+     */
+    setEnv(propertyName: string, value: string): Promise<void>;
+    /**
+     * Queue a silent message to this thread's parent, if one exists.
+     *
+     * This is useful for explicit child-to-parent escalation paths where tools or
+     * hooks decide when the parent should be notified.
+     *
+     * Implementations SHOULD tag the queued message with the current thread's
+     * `subagent_id` metadata so the parent can attribute the notification.
+     *
+     * @throws If the thread has no parent or the runtime does not support parent messaging
+     */
+    notifyParent(content: string): Promise<void>;
+    /**
+     * Update this thread's status in its parent registry entry.
+     *
+     * Useful for long-lived watcher/observer children that want to expose their
+     * current state without sending a parent message.
+     *
+     * @throws If the thread has no parent or the runtime does not support parent status updates
+     */
+    setStatus(status: string): Promise<void>;
     /**
      * Queue a tool for execution.
      *
@@ -671,6 +816,13 @@ interface ThreadState {
      * ```
      */
     runAgent(agentName: string): Promise<void>;
+    /**
+     * Soft-terminate the thread.
+     *
+     * Implementations should mark the thread as terminated, abort in-flight
+     * execution, and reject subsequent execution/message queue operations.
+     */
+    terminate(): Promise<void>;
     /**
      * Emit a custom event to connected clients.
      *
@@ -903,6 +1055,19 @@ interface ToolResult {
     result?: string;
     /** Error message if status is 'error'. */
     error?: string;
+    /**
+     * Machine-readable error code for structured handling.
+     *
+     * Example: `subagent_env_required` indicates the client must provide
+     * scoped subagent env values before execution can continue.
+     */
+    error_code?: string;
+    /**
+     * Structured error payload for machine handling.
+     *
+     * Implementations should keep this JSON-serializable.
+     */
+    error_data?: Record<string, unknown>;
     /** Stack trace for error debugging. */
     stack?: string;
     /**
@@ -948,8 +1113,37 @@ type ToolArgsRawShape<D extends number = 7> = Record<string, ToolArgsNode<D>>;
  */
 type ToolArgs<D extends number = 7> = z.ZodObject<ToolArgsRawShape<D>>;
 /**
- * Raw shape for tenv schema - uses same pattern as ToolArgsRawShape.
- * Each key is a tenv name, value is a Zod schema for validation.
+ * Variable declaration type.
+ *
+ * - `text`: Plain string configuration value
+ * - `secret`: Sensitive value that should be encrypted at rest
+ */
+type VariableType = 'text' | 'secret';
+/**
+ * Declares a variable required or optionally consumed by a tool or prompt.
+ */
+interface VariableDefinition {
+    /** Environment variable/property name */
+    name: string;
+    /** Value type */
+    type: VariableType;
+    /** Whether this variable is required to execute */
+    required: boolean;
+    /**
+     * Whether this variable is scoped to the declarer subtree.
+     *
+     * Scoped variables do not inherit parent thread env values. Descendants of
+     * the declarer still inherit scoped values from that declarer thread.
+     *
+     * @default false
+     */
+    scoped?: boolean;
+    /** Human-readable description (empty string when not provided) */
+    description: string;
+}
+/**
+ * Legacy raw shape for `tenvs` schema - uses same pattern as ToolArgsRawShape.
+ * Each key is an environment variable name and each value is a Zod schema.
  *
  * @template D - Maximum nesting depth (default: 7)
  */
@@ -958,19 +1152,23 @@ type TenvRawShape<D extends number = 7> = Record<string, ToolArgsNode<D>>;
  * Top-level thread environment variable schema.
  *
  * Defines which thread environment variables a tool requires.
- * Required tenvs are non-optional fields, optional tenvs use .optional().
+ * Required values are non-optional fields, optional values use `.optional()`.
  *
  * @example
  * ```typescript
  * z.object({
- *   vectorStoreId: z.string().describe('OpenAI Vector Store ID'),        // Required
- *   userLocation: z.string().optional().describe('User location'),       // Optional
+ *   VECTOR_STORE_ID: z.string().describe('OpenAI Vector Store ID'),  // Required
+ *   USER_LOCATION: z.string().optional().describe('User location'),   // Optional
  * })
  * ```
  *
  * @template D - Maximum nesting depth (default: 7)
  */
 type ToolTenvs<D extends number = 7> = z.ZodObject<TenvRawShape<D>>;
+/**
+ * @deprecated Use VariableDefinition[] via the `variables` property instead.
+ */
+type ToolVariables = VariableDefinition[];
 /**
  * Tool function signature.
  *
@@ -1058,7 +1256,14 @@ interface DefineToolOptions<State = ThreadState, Args extends ToolArgs | null =
     args?: Args;
     /** The tool implementation function. */
     execute: UsesAwareExecute<State, Args, Uses>;
-    /** Zod schema for thread environment variables the tool requires. */
+    /**
+     * Variable declarations required/optionally used by this tool.
+     */
+    variables?: VariableDefinition[];
+    /**
+     * @deprecated Use `variables` instead.
+     * Zod schema for thread environment variables the tool requires.
+     */
     tenvs?: Tenvs;
     /**
      * Where this tool is executed:
@@ -1126,7 +1331,12 @@ interface ToolDefinition<State = ThreadState, Args extends ToolArgs | null = nul
     args: Args;
     /** The tool implementation function. */
     execute: UsesAwareExecute<State, Args, Uses>;
-    /** Zod schema for thread environment variables, or null if none. */
+    /** Declared variables for this tool. */
+    variables: VariableDefinition[];
+    /**
+     * @deprecated Use `variables` instead.
+     * Zod schema for thread environment variables, or null if none.
+     */
     tenvs: Tenvs;
     /**
      * Where this tool is executed:
@@ -1160,7 +1370,7 @@ interface ToolDefinition<State = ThreadState, Args extends ToolArgs | null = nul
  * Tools are the primary way agents interact with external systems.
  * Each tool has a description (shown to the LLM), optional argument
  * schema (validated at runtime), an implementation function, and
- * optional thread environment variable (tenv) requirements.
+ * optional variable requirements.
  *
  * @example
  * ```typescript
@@ -1188,14 +1398,19 @@ interface ToolDefinition<State = ThreadState, Args extends ToolArgs | null = nul
  *   },
  * });
  *
- * // Tool with tenvs (thread environment variables)
+ * // Tool with declared variables
  * export default defineTool({
  *   description: 'Search through uploaded files',
  *   args: z.object({ query: z.string() }),
  *   execute: async (state, args) => ({ status: 'success', result: 'done' }),
- *   tenvs: z.object({
- *     vectorStoreId: z.string().describe('OpenAI Vector Store ID'),
- *   }),
+ *   variables: [
+ *     {
+ *       name: 'VECTOR_STORE_ID',
+ *       type: 'text',
+ *       required: true,
+ *       description: 'OpenAI Vector Store ID',
+ *     },
+ *   ],
  * });
  *
  * // Provider-executed tool (e.g., OpenAI built-in tools)
@@ -1304,7 +1519,7 @@ interface LLMProviderInterface {
      * Optional - providers may implement this to expose built-in tools
      * (e.g., OpenAI's web_search, file_search, code_interpreter).
      *
-     * These tools are defined using defineTool() with optional tenv requirements.
+     * These tools are defined using defineTool() with optional variable requirements.
      * Tools returned here can be referenced by name in model/prompt definitions.
      *
      * @param modelId - Optional filter to get tools available for a specific model
@@ -2037,11 +2252,21 @@ interface PromptIncludePart {
     /** The name of the prompt to include */
     prompt: StandardAgentSpec.Prompts;
 }
+/**
+ * An environment variable insertion part.
+ *
+ * Loads a thread variable by property name at interpolation time.
+ */
+interface PromptEnvPart {
+    type: 'env';
+    /** Variable property name to resolve from thread env */
+    property: string;
+}
 /**
  * A single part of a structured prompt.
  * Discriminated union on `type` field for TypeScript narrowing.
  */
-type PromptPart = PromptTextPart | PromptIncludePart;
+type PromptPart = PromptTextPart | PromptIncludePart | PromptEnvPart;
 /**
  * A structured prompt is an array of prompt parts.
  * Provides composition with other prompts via includes.
@@ -2136,12 +2361,12 @@ interface SubpromptConfig<T extends string = StandardAgentSpec.Callables> {
 type ToolConfig<T extends string = string> = SubpromptConfig<T>;
 /**
  * Configuration for a tool used in a prompt.
- * Allows specifying tenv values and static options for the tool.
+ * Allows specifying environment values and static options for the tool.
  *
  * @example
  * ```typescript
- * // Tool with tenv values
- * { name: 'file_search', tenvs: { vectorStoreId: 'vs_abc123' } }
+ * // Tool with environment values
+ * { name: 'file_search', env: { VECTOR_STORE_ID: 'vs_abc123' } }
  *
  * // Tool with options
  * { name: 'web_search', options: { searchContextSize: 'high' } }
@@ -2153,8 +2378,11 @@ interface PromptToolConfig {
      */
     name: StandardAgentSpec.Callables;
     /**
-     * Thread environment variable values for this tool.
-     * These values are merged with agent and thread tenvs (prompt tenvs are lowest priority).
+     * Environment variable values for this tool.
+     */
+    env?: Record<string, string>;
+    /**
+     * @deprecated Use `env` instead.
      */
     tenvs?: Record<string, unknown>;
     /**
@@ -2163,6 +2391,146 @@ 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.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   name: 'browser_agent',
+ *   blocking: false,
+ *   resumable: {
+ *     receives_messages: 'side_a',
+ *     maxInstances: 1,
+ *   },
+ * }
+ * ```
+ */
+interface SubagentToolConfig<T extends string = StandardAgentSpec.Callables> {
+    /**
+     * Agent callable name.
+     *
+     * Must reference a `dual_ai` agent with `exposeAsTool: true`.
+     */
+    name: 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()` when they choose to escalate.
+         */
+        parentCommunication?: 'implicit' | 'explicit';
+    };
+}
 /**
  * Reasoning configuration for models that support extended thinking.
  * Applies to models like OpenAI o1/o3, Anthropic Claude with extended thinking,
@@ -2288,12 +2656,17 @@ interface PromptDefinition<N extends string = string, S extends ToolArgs = ToolA
      * Zod schema for validating inputs when this prompt is called as a tool.
      */
     requiredSchema?: S;
+    /**
+     * Declared variables for this prompt.
+     */
+    variables?: VariableDefinition[];
     /**
      * Tools available to this prompt.
      * Can be:
      * - string: Simple tool name (custom or provider tool)
      * - SubpromptConfig: Sub-prompt used as a tool
-     * - PromptToolConfig: Tool with tenv values and/or options
+     * - 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.
      *
@@ -2302,23 +2675,18 @@ interface PromptDefinition<N extends string = string, S extends ToolArgs = ToolA
      * tools: [
      *   'custom_tool',                                    // Simple tool name
      *   { name: 'other_prompt' },                         // Sub-prompt as tool
-     *   { name: 'file_search', tenvs: { vectorStoreId: 'vs_123' } },  // Tool with tenvs
+     *   { name: 'file_search', env: { VECTOR_STORE_ID: 'vs_123' } },  // Tool with env values
      * ]
      * ```
      */
-    tools?: (StandardAgentSpec.Callables | SubpromptConfig | PromptToolConfig)[];
+    tools?: (StandardAgentSpec.Callables | SubpromptConfig | PromptToolConfig | SubagentToolConfig)[];
     /**
-     * Thread environment variables for this prompt.
-     * These values are merged with agent and thread tenvs when creating a thread.
-     * Prompt tenvs have lowest priority (overridden by agent and thread tenvs).
-     *
-     * @example
-     * ```typescript
-     * tenvs: {
-     *   vectorStoreId: 'vs_default_123',
-     *   apiEndpoint: 'https://api.example.com',
-     * }
-     * ```
+     * Environment values provided by this prompt.
+     * Prompt values are the lowest-precedence source in runtime resolution.
+     */
+    env?: Record<string, string>;
+    /**
+     * @deprecated Use `env` instead.
      */
     tenvs?: Record<string, unknown>;
     /**
@@ -2816,6 +3184,40 @@ declare function defineHook<K extends HookName>(options: HookDefinitionOptions<K
  * - `dual_ai`: Two AI participants conversing with each other
  */
 type AgentType = 'ai_human' | 'dual_ai';
+/**
+ * Configuration for a session lifecycle tool.
+ *
+ * Used by side-level 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
+ *
+ * @template Callable - Callable name type
+ */
+interface SessionToolConfig<Callable extends string = StandardAgentSpec.Callables> {
+    /**
+     * Tool name for this session lifecycle action.
+     */
+    name: Callable;
+    /**
+     * Optional tool-argument property used as lifecycle message text.
+     */
+    messageProperty?: string;
+    /**
+     * Optional tool-argument property containing attachment path(s).
+     * Supports a single path string or an array of path strings.
+     */
+    attachmentsProperty?: string;
+}
+/**
+ * Session lifecycle tool reference.
+ *
+ * Can be either:
+ * - a plain tool name string (legacy/simple form)
+ * - a {@link SessionToolConfig} object (explicit mapping form)
+ */
+type SessionToolBinding<Callable extends string = StandardAgentSpec.Callables> = Callable | SessionToolConfig<Callable>;
 /**
  * Configuration for one side of an agent conversation.
  *
@@ -2875,10 +3277,62 @@ interface SideConfig<Prompt extends string = StandardAgentSpec.Prompts, Callable
     maxSteps?: number;
     /**
      * Tool that ends the entire session when called.
-     * Different from stopTool - this ends the session for both sides,
+     *
+     * 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.
+     *
+     * In subagent runtimes, mapped message/attachments are the canonical
+     * completion payload returned from child -> parent.
+     */
+    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 object form to explicitly map message/attachment argument fields.
+     *
+     * In subagent runtimes, mapped message/attachments are the canonical
+     * failure payload returned from child -> parent.
+     */
+    sessionFail?: SessionToolBinding<Callable>;
+    /**
+     * Tool that publishes status updates to the parent thread when used 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.
+     *
+     * @example
+     * ```typescript
+     * sideA: {
+     *   prompt: 'research_worker',
+     *   sessionStatus: { name: 'update_status', messageProperty: 'status' },
+     * }
+     * ```
+     */
+    sessionStatus?: SessionToolBinding<Callable>;
+    /**
+     * @deprecated Use sessionStop instead.
      */
     endSessionTool?: Callable;
+    /**
+     * @deprecated Use sessionFail instead.
+     */
+    failSessionTool?: Callable;
+    /**
+     * @deprecated Use sessionStatus instead.
+     */
+    statusTool?: Callable;
 }
 /**
  * Agent definition configuration.
@@ -2971,21 +3425,12 @@ interface AgentDefinition<N extends string = string, Prompt extends string = Sta
      */
     icon?: string;
     /**
-     * Thread environment variables for this agent.
-     * These values are merged with prompt and thread tenvs when creating a thread.
-     *
-     * Merge priority (later wins):
-     * 1. Prompt tenvs (lowest)
-     * 2. Agent tenvs (this field)
-     * 3. Thread tenvs (highest)
-     *
-     * @example
-     * ```typescript
-     * tenvs: {
-     *   vectorStoreId: 'vs_agent_default',
-     *   apiEndpoint: 'https://api.example.com',
-     * }
-     * ```
+     * Environment values provided by this agent.
+     * Agent values are lower priority than thread/account/instance values.
+     */
+    env?: Record<string, string>;
+    /**
+     * @deprecated Use `env` instead.
      */
     tenvs?: Record<string, unknown>;
     /**
@@ -3054,7 +3499,7 @@ interface AgentDefinition<N extends string = string, Prompt extends string = Sta
  *     label: 'Support',
  *     prompt: 'customer_support',
  *     stopOnResponse: true,
- *     endSessionTool: 'close_ticket',
+ *     sessionStop: 'close_ticket',
  *   },
  *   exposeAsTool: true,
  *   toolDescription: 'Hand off to customer support',
@@ -3078,7 +3523,7 @@ interface AgentDefinition<N extends string = string, Prompt extends string = Sta
  *     label: 'Con',
  *     prompt: 'debate_con',
  *     stopOnResponse: true,
- *     endSessionTool: 'conclude_debate',
+ *     sessionStop: 'conclude_debate',
  *   },
  * });
  * ```
@@ -3479,8 +3924,23 @@ interface PackedExports {
     models: Record<string, DefinitionLoader<ModelDefinition>>;
     /** Hook definitions, keyed by name */
     hooks: Record<string, DefinitionLoader<HookSignatures[keyof HookSignatures]>>;
+    /**
+     * Effect definitions, keyed by name.
+     *
+     * Optional for backward compatibility with previously packed packages.
+     */
+    effects?: Record<string, DefinitionLoader<EffectDefinition<any, any>>>;
+    /**
+     * Thread endpoint handlers, keyed by packed route key (for example, `status.get`).
+     *
+     * Runtimes typically mount these under a package namespace (for example:
+     * `/api/packages/:packageId/threads/:id/...`) to avoid collisions.
+     *
+     * Optional for backward compatibility with previously packed packages.
+     */
+    threadEndpoints?: Record<string, DefinitionLoader<MarkedThreadEndpoint | Controller>>;
     /** Package metadata */
     __meta: PackedMeta;
 }
 
-export { type AgentDefinition, type AgentType, type AttachmentRef, type ContentPart, type Controller, type ControllerContext, type ControllerReturn, type DefineToolOptions, type DefinitionLoader, type Effect, type EffectDefinition, type EmptyUsesState, type ExecutionState, 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 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 MarkedThreadEndpoint, 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 PromptContent, type PromptDefinition, type PromptIncludePart, type PromptInput, type PromptPart, type PromptTextPart, type PromptToolConfig, type ProviderAssistantMessage, type ProviderAttachment, ProviderError, type ProviderErrorCode, type ProviderFactory, type ProviderFactoryConfig, type ProviderFactoryWithOptions, type ProviderFinishReason, type ProviderGeneratedImage, type ProviderInstance, type ProviderMessage, type ProviderMessageContent, type ProviderModelInfo, type ProviderReasoningDetail, type ProviderRequest, type ProviderResponse, type ProviderStreamChunk, type ProviderSystemMessage, type ProviderTool, type ProviderToolCallPart, type ProviderToolMessage, type ProviderToolResultContent, type ProviderUsage, type ProviderUserMessage, type ProviderWebSearchResult, type ReadFileStreamOptions, type ReaddirResult, type ReasoningConfig, type ResolveUsesState, type ResponseSummary, type ScheduledEffect, type SideConfig, type StructuredPrompt, type SubpromptConfig, THREAD_ENDPOINT_SYMBOL, type TenvRawShape, type TextContent, type TextPart, type ThreadEndpointHandler, type ThreadMetadata, type ThreadState, type Tool, type ToolArgs, type ToolArgsNode, type ToolArgsRawShape, type ToolAttachment, type ToolConfig, type ToolContent, type ToolDefinition, type ToolResult, type ToolTenvs, type UsesAwareExecute, type UsesConstrainedState, type VirtualModuleLoader, type VirtualModuleRegistry, type WriteFileOptions, belongsToPackage, defineAgent, defineController, defineEffect, defineHook, defineModel, definePrompt, defineThreadEndpoint, defineTool, isPacked, isThreadEndpoint, isVisibleInNamespace, mapReasoningLevel, validateToolName };
+export { type AgentDefinition, type AgentType, type AttachmentRef, type ContentPart, type Controller, type ControllerContext, type ControllerReturn, type DefineToolOptions, type DefinitionLoader, type Effect, type EffectDefinition, type EmptyUsesState, type ExecutionState, 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 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 MarkedThreadEndpoint, 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 PromptContent, type PromptDefinition, type PromptEnvPart, type PromptIncludePart, type PromptInput, type PromptPart, type PromptTextPart, type PromptToolConfig, type ProviderAssistantMessage, type ProviderAttachment, ProviderError, type ProviderErrorCode, type ProviderFactory, type ProviderFactoryConfig, type ProviderFactoryWithOptions, type ProviderFinishReason, type ProviderGeneratedImage, type ProviderInstance, type ProviderMessage, type ProviderMessageContent, type ProviderModelInfo, type ProviderReasoningDetail, type ProviderRequest, type ProviderResponse, type ProviderStreamChunk, type ProviderSystemMessage, type ProviderTool, type ProviderToolCallPart, type ProviderToolMessage, type ProviderToolResultContent, type ProviderUsage, type ProviderUserMessage, type ProviderWebSearchResult, type QueueMessageInput, type ReadFileStreamOptions, type ReaddirResult, type ReasoningConfig, type ResolveUsesState, type ResponseSummary, type ScheduledEffect, type SessionToolBinding, type SessionToolConfig, type SideConfig, type StructuredPrompt, type SubagentRegistryEntry, type SubagentToolConfig, type SubpromptConfig, THREAD_ENDPOINT_SYMBOL, type TenvRawShape, type TextContent, type TextPart, type ThreadEndpointHandler, type ThreadMetadata, type ThreadState, type Tool, type ToolArgs, type ToolArgsNode, type ToolArgsRawShape, type ToolAttachment, type ToolConfig, type ToolContent, type ToolDefinition, type ToolResult, type ToolTenvs, type ToolVariables, type UsesAwareExecute, type UsesConstrainedState, type VariableDefinition, type VariableType, type VirtualModuleLoader, type VirtualModuleRegistry, type WriteFileOptions, belongsToPackage, defineAgent, defineController, defineEffect, defineHook, defineModel, definePrompt, defineThreadEndpoint, defineTool, isPacked, isThreadEndpoint, isVisibleInNamespace, mapReasoningLevel, validateToolName };