@standardagents/spec 0.39.0 → 0.40.0

package/dist/index.d.ts

@@ -1647,7 +1647,7 @@ interface ExecutionState {
     readonly stopped: boolean;
     /** Which side initiated the stop (if stopped) */
     readonly stoppedBy?: 'a' | 'b';
-    /** Message history loaded for current execution */
+    /** Live chronological persisted history for the current execution */
     readonly messageHistory: Message[];
     /**
      * Force a specific side to play the next turn.
@@ -1873,6 +1873,12 @@ interface ThreadState {
      *
      * Creates a new message in the conversation history. This can be used
      * to add context, simulate user input, or insert assistant responses.
+     * Runs `before_create_message` and `after_create_message`. If a
+     * `before_create_message` hook throws, the returned promise rejects and
+     * no message is persisted. During active execution, the persisted message
+     * becomes immediately visible through `execution.messageHistory`.
+     * `silent` controls client presentation only; silent messages remain
+     * eligible for model context.
      *
      * @param message - The message to inject
      * @returns The created message
@@ -4269,1444 +4275,1533 @@ 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>;
 
 /**
- * Hook definition types for Standard Agents.
- *
- * Hooks allow intercepting and modifying agent behavior at key points
- * in the execution lifecycle. They enable logging, validation,
- * transformation, and side effects.
+ * Agent definition types for Standard Agents.
  *
- * Hooks receive ThreadState as their first parameter, providing full
- * access to thread operations and execution state.
+ * 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.
  *
  * @module
  */
-
 /**
- * Hook context is ThreadState.
- *
- * Hooks receive the full ThreadState, which includes identity, message access,
- * resource loading, event emission, and execution state (when available).
+ * Agent conversation type.
  *
- * @example
- * ```typescript
- * const hook = defineHook({
- *   hook: 'filter_messages',
- *   id: 'keep_recent',
- *   execute: async (state, messages) => {
- *     console.log(`Thread: ${state.threadId}`);
- *     if (state.execution) {
- *       console.log(`Step: ${state.execution.stepCount}`);
- *     }
- *     return messages.slice(-10);
- *   },
- * });
- * ```
+ * - `ai_human`: AI conversing with a human user (most common)
+ * - `dual_ai`: Two AI participants conversing with each other
  */
-type HookContext = ThreadState;
+type AgentType = 'ai_human' | 'dual_ai';
 /**
- * Message structure for hook processing.
- *
- * Re-exported from threads.ts for convenience.
- * @see Message
+ * Ordering position for a child agent's required hook on its parent.
  */
-type HookMessage = Message;
+type ParentHookStage = 'before_parent' | 'after_parent';
 /**
- * Tool call structure for hook processing.
+ * 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.
  */
-interface HookToolCall {
-    /** Unique tool call identifier */
-    id: string;
-    /** Always 'function' for tool calls */
-    type: 'function';
-    /** Function details */
-    function: {
-        /** Tool name */
-        name: string;
-        /** JSON-encoded arguments */
-        arguments: string;
-    };
+interface ParentHookRequirement<Hook extends string = StandardAgentSpec.HookIds> {
+    /** Child-local hook ID from `defineHook({ id })`. */
+    hook: Hook;
+    /** Human-facing explanation shown by installers and composition UIs. */
+    reason: string;
+    /** Whether the hook runs before or after the parent's own hook set. */
+    stage?: ParentHookStage;
 }
 /**
- * Tool result structure for hook processing.
+ * 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 HookToolResult {
-    /** Execution status */
-    status: 'success' | 'error';
-    /** Result string (for successful executions) */
-    result?: string;
-    /** Error message (for failed executions) */
-    error?: string;
-    /** Stack trace (for debugging) */
-    stack?: string;
+interface SessionToolConfig<Callable extends string = StandardAgentSpec.Callables> {
     /**
-     * File attachments returned by the tool.
-     *
-     * Can contain either:
-     * - ToolAttachment: New files with base64 data to be stored
-     * - AttachmentRef: References to existing files in the thread filesystem
+     * Tool name for this session lifecycle action.
      */
-    attachments?: Array<ToolAttachment | AttachmentRef>;
+    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;
 }
 /**
- * LLM message format for prefilter hook.
+ * Session lifecycle tool reference.
  *
- * Messages passed to the prefilter_llm_history hook are in chat completion
- * format. Content can be a plain string or a multimodal array (for messages
- * with images). Additional provider-specific fields may also be present.
+ * Can be either:
+ * - a plain tool name string (legacy/simple form)
+ * - a {@link SessionToolConfig} object (explicit mapping form)
  */
-interface LLMMessage {
-    /** Message role */
-    role: string;
-    /** Message content (string for text-only, array for multimodal) */
-    content?: string | null | unknown[];
-    /** Tool calls (parsed) */
-    tool_calls?: unknown;
-    /** Tool call ID */
-    tool_call_id?: string;
-    /** Tool name */
-    name?: string;
-    /** Reasoning content (for models like o1) */
-    reasoning_content?: string;
-    /** Allow additional provider-specific fields */
-    [key: string]: unknown;
-}
+type SessionToolBinding<Callable extends string = StandardAgentSpec.Callables> = Callable | SessionToolConfig<Callable>;
 /**
- * Hook signatures for all available hooks.
+ * Configuration for one side of an agent conversation.
  *
- * Each hook has a specific signature that defines when it's called
- * and what data it receives. Hooks can modify data by returning
- * transformed values or perform side effects.
+ * 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.
  *
- * All hooks receive ThreadState as their first parameter.
+ * @template Prompt - The prompt reference type (string or type-safe union)
+ * @template Callable - The callable reference type (string or type-safe union)
  *
- * @template State - The state type (defaults to ThreadState)
- * @template Msg - The message type (defaults to HookMessage)
- * @template ToolCall - The tool call type (defaults to HookToolCall)
- * @template ToolResult - The tool result type (defaults to HookToolResult)
+ * @example
+ * ```typescript
+ * const sideConfig: SideConfig = {
+ *   label: 'Support Agent',
+ *   prompt: 'customer_support',
+ *   stopOnResponse: true,
+ *   maxSteps: 10,
+ * };
+ * ```
  */
-interface HookSignatures<State = ThreadState, Msg = HookMessage, ToolCall = HookToolCall, ToolResult = HookToolResult> {
+interface SideConfig<Prompt extends string = StandardAgentSpec.Prompts, Callable extends string = StandardAgentSpec.Callables> {
     /**
-     * Called after a thread is created, before initial message processing or LLM
-     * requests for that thread.
-     *
-     * Only ThreadState is passed. Use for initializing durable thread values,
-     * env placeholders, files, or side-effect instrumentation.
+     * Custom label for this side of the conversation.
+     * Used in UI and logs for clarity.
      *
-     * @param state - Created thread state
+     * @example 'Support Agent', 'Customer', 'ATC', 'Pilot'
      */
-    after_thread_created: (state: State) => Promise<void>;
+    label?: string;
     /**
-     * Called on the parent thread immediately after a subagent child thread is
-     * created.
-     *
-     * Receives parent ThreadState and child ThreadState. Use for copying or
-     * linking metadata, bookkeeping, or side-effect instrumentation.
-     *
-     * @param state - Parent thread state
-     * @param childState - Created child thread state
+     * The prompt to use for this side.
+     * Must reference a prompt defined in agents/prompts/.
      */
-    after_subagent_created: (state: State, childState: State) => Promise<void>;
+    prompt: Prompt;
     /**
-     * Called after the prompt system message is rendered for a model request.
-     *
-     * Return a string to replace the rendered system message. Return null or
-     * undefined to keep the original message.
-     *
-     * @param state - Thread state
-     * @param systemMessage - Rendered system message for this request
-     * @returns Replacement system message, or null/undefined for no change
+     * 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;
+    /**
+     * 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.
      */
-    after_system_message: (state: State, systemMessage: string) => string | Promise<string | null | undefined> | null | undefined;
+    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;
+    /**
+     * 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;
     /**
-     * Called before messages are filtered and sent to the LLM.
+     * Tool that ends the entire session when called.
      *
-     * Receives raw message rows from storage before any transformation.
-     * Use for filtering, sorting, or augmenting message history.
+     * Different from stopTool: this ends the session for both sides,
+     * not just this side's turn.
      *
-     * @param state - Thread state
-     * @param messages - Array of messages from storage
-     * @returns Modified message array
+     * Use object form to explicitly map message/attachment argument fields.
      *
-     * @example
-     * ```typescript
-     * defineHook({
-     *   hook: 'filter_messages',
-     *   id: 'limit_to_10',
-     *   execute: async (state, messages) => messages.slice(-10),
-     * });
-     * ```
+     * In subagent runtimes, mapped message/attachments are the canonical
+     * completion payload returned from child -> parent.
      */
-    filter_messages: (state: State, messages: Msg[]) => Promise<Msg[]>;
+    sessionStop?: SessionToolBinding<Callable>;
     /**
-     * Called after message history is loaded and before sending to LLM.
+     * Tool that fails the entire session when called.
      *
-     * Receives messages already transformed into chat completion format.
-     * Use for final adjustments before LLM request.
+     * Use this when the side cannot fulfill the request and needs to terminate
+     * the session with an error outcome.
      *
-     * @param state - Thread state
-     * @param messages - Array of LLM-formatted messages
-     * @returns Modified LLM message array
+     * When used inside a subagent, this failure is propagated back to the parent
+     * as a terminal failure result.
      *
-     * @example
-     * ```typescript
-     * defineHook({
-     *   hook: 'prefilter_llm_history',
-     *   id: 'add_reminder',
-     *   execute: async (state, messages) => messages,
-     * });
-     * ```
+     * 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.
      */
-    prefilter_llm_history: (state: State, messages: LLMMessage[]) => Promise<LLMMessage[]>;
+    sessionFail?: SessionToolBinding<Callable>;
     /**
-     * Called before a message is created in the database.
+     * Tool that publishes status updates to the parent thread when used as a subagent.
      *
-     * Receives the full message object before insertion. Return modified
-     * message to transform before storage.
+     * When called from a `dual_ai` subagent, message text is forwarded to
+     * the parent thread's subagent registry as this instance's current status.
      *
-     * @param state - Thread state
-     * @param message - Message to be created
-     * @returns Modified message
+     * Use object form to explicitly map message/attachment argument fields.
+     *
+     * Status updates do not terminate the session.
      *
      * @example
      * ```typescript
-     * defineHook({
-     *   hook: 'before_create_message',
-     *   id: 'prefix_content',
-     *   execute: async (state, message) => {
-     *     // message has full type: id, role, content, created_at, etc.
-     *     if (message.role === 'user' && message.content) {
-     *       return { ...message, content: `[user] ${message.content}` };
-     *     }
-     *     return message;
-     *   }
-     * });
-     * ```
-     */
-    before_create_message: (state: State, message: Msg) => Promise<Msg>;
-    /**
-     * Called after a message is created in the database.
-     *
-     * Use for logging, analytics, or triggering side effects after
-     * message creation. Cannot modify the message.
-     *
-     * @param state - Thread state
-     * @param message - The created message
-     *
-     * @example
-     * ```typescript
-     * defineHook({
-     *   hook: 'after_create_message',
-     *   id: 'log_creation',
-     *   execute: async (state, message) => {
-     *     console.log(`Created ${message.role} message: ${message.id}`);
-     *   }
-     * });
+     * sideA: {
+     *   prompt: 'research_worker',
+     *   sessionStatus: { name: 'update_status', messageProperty: 'status' },
+     * }
      * ```
      */
-    after_create_message: (state: State, message: Msg) => Promise<void>;
+    sessionStatus?: SessionToolBinding<Callable>;
+}
+/**
+ * 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)
+ *
+ * @example
+ * ```typescript
+ * import { defineAgent } from '@standardagents/spec';
+ *
+ * export default defineAgent({
+ *   name: 'support_agent',
+ *   title: 'Customer Support Agent',
+ *   type: 'ai_human',
+ *   sideA: {
+ *     label: 'Support',
+ *     prompt: 'customer_support',
+ *     stopOnResponse: true,
+ *   },
+ * });
+ * ```
+ */
+interface AgentDefinition<N extends string = string, Prompt extends string = StandardAgentSpec.Prompts, Callable extends string = StandardAgentSpec.Callables> {
+    /**
+     * 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;
     /**
-     * Called before a message is updated in the database.
-     *
-     * Receives the message ID and update data. Return modified updates
-     * to transform the changes before storage.
+     * 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;
+    /**
+     * Agent conversation type.
      *
-     * @param state - Thread state
-     * @param messageId - ID of message being updated
-     * @param updates - Update data
-     * @returns Modified update data
+     * - `ai_human`: AI conversing with a human user (default)
+     * - `dual_ai`: Two AI participants conversing
      *
-     * @example
-     * ```typescript
-     * defineHook({
-     *   hook: 'before_update_message',
-     *   id: 'stamp_updated_at',
-     *   execute: async (state, messageId, updates) => ({
-     *     ...updates,
-     *     updated_at: Date.now(),
-     *   }),
-     * });
-     * ```
+     * @default 'ai_human'
      */
-    before_update_message: (state: State, messageId: string, updates: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    type?: AgentType;
     /**
-     * Called after a message is updated in the database.
-     *
-     * Use for logging, analytics, or triggering side effects after
-     * message update. Cannot modify the message.
+     * Maximum total turns across both sides.
+     * Only applies to `dual_ai` agents.
+     * Prevents infinite loops in AI-to-AI conversations.
+     */
+    maxSessionTurns?: number;
+    /**
+     * Configuration for Side A.
+     * For `ai_human`: This is the AI side.
+     * For `dual_ai`: This is the first AI participant.
+     */
+    sideA: SideConfig<Prompt, Callable>;
+    /**
+     * Configuration for Side B.
+     * For `ai_human`: Optional, the human side doesn't need config.
+     * For `dual_ai`: Required, the second AI participant.
+     */
+    sideB?: SideConfig<Prompt, Callable>;
+    /**
+     * 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.
+     * @default false
+     */
+    exposeAsTool?: boolean;
+    /**
+     * Whether this agent is a PRIMARY, user-facing entry point (default true).
      *
-     * @param state - Thread state
-     * @param message - The updated message
+     * Set `primary: false` on agents that exist only as internal handoff
+     * targets or infrastructure — e.g. the specialist variants of a
+     * domain-routing gearbox. Non-primary agents remain fully addressable
+     * (handoffs, invokeTool, thread resumption) and their threads remain
+     * 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;
+    /**
+     * Description shown when agent is used as a tool.
+     * Required if exposeAsTool is true.
+     * Should clearly describe what this agent does.
+     */
+    toolDescription?: string;
+    /**
+     * Brief description of what this agent does.
+     * Useful for UIs and documentation.
      *
-     * @example
-     * ```typescript
-     * defineHook({
-     *   hook: 'after_update_message',
-     *   id: 'log_update',
-     *   execute: async (state, message) => {
-     *     console.log(`Message updated: ${message.id}`);
-     *   },
-     * });
-     * ```
+     * @example 'Handles customer support inquiries and resolves issues'
      */
-    after_update_message: (state: State, message: Msg) => Promise<void>;
+    description?: string;
     /**
-     * Called before a tool result is stored in the database.
+     * Icon URL or absolute path for the agent.
+     * Absolute paths (starting with `/`) are converted to full URLs in API responses.
      *
-     * Receives the tool call and result before storage. Return modified
-     * result to transform before storage.
+     * @example 'https://example.com/icon.svg' or '/icons/support.svg'
+     */
+    icon?: string;
+    /**
+     * 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>;
+    /**
+     * npm package name for this agent when packed.
+     * Used by the packing system to maintain consistent package identity
+     * across pack/unpack cycles.
      *
-     * @param state - Thread state
-     * @param toolCall - The tool call that was executed
-     * @param toolResult - The result from tool execution
-     * @returns Modified tool result
+     * @example 'standardagent-support-agent', '@myorg/support-agent'
+     */
+    packageName?: string;
+    /**
+     * Package version (semver format).
+     * Used by the packing system to track versions across pack/unpack cycles.
+     * When re-packing, this version is auto-incremented by the pack modal.
      *
-     * @example
-     * ```typescript
-     * defineHook({
-     *   hook: 'before_store_tool_result',
-     *   id: 'sanitize_results',
-     *   execute: async (state, toolCall, toolResult) => {
-     *     // toolCall has: id, type, function.name, function.arguments
-     *     // toolResult has: status, result?, error?, stack?, attachments?
-     *     if (toolResult.result) {
-     *       return { ...toolResult, result: sanitize(toolResult.result) };
-     *     }
-     *     return toolResult;
-     *   }
-     * });
-     * ```
+     * @example '1.0.0', '2.3.1-beta.1'
      */
-    before_store_tool_result: (state: State, toolCall: ToolCall, toolResult: ToolResult) => Promise<ToolResult>;
+    version?: string;
     /**
-     * Called after a successful tool call.
+     * Package author/copyright holder.
+     * Used by the packing system for the LICENSE file and package.json author field.
      *
-     * Receives the tool call and its result. Can return a modified result
-     * or null to use the original. Use for logging, transformation, or
-     * post-processing of successful tool executions.
+     * @example 'John Doe', 'Acme Corp'
+     */
+    author?: string;
+    /**
+     * License identifier (SPDX format).
+     * Used by the packing system for LICENSE file generation.
      *
-     * @param state - Thread state
-     * @param toolCall - The executed tool call
-     * @param toolResult - The successful result
-     * @returns Modified result or null for original
+     * @example 'MIT', 'Apache-2.0', 'ISC'
+     */
+    license?: string;
+    /**
+     * Hook IDs to run for this agent.
+     * References hooks by their unique `id` property from defineHook().
+     * These run when prompts don't specify their own hooks.
      *
      * @example
      * ```typescript
-     * defineHook({
-     *   hook: 'after_tool_call_success',
-     *   id: 'log_success',
-     *   execute: async (state, toolCall, toolResult) => {
-     *     console.log(`Tool ${toolCall.function.name} succeeded`);
-     *     return null; // use original result
-     *   },
-     * });
+     * hooks: ['log_messages', 'track_tool_usage']
      * ```
      */
-    after_tool_call_success: (state: State, toolCall: ToolCall, toolResult: ToolResult) => Promise<ToolResult | null>;
+    hooks?: StandardAgentSpec.HookIds[];
     /**
-     * Called after a failed tool call.
-     *
-     * Receives the tool call and error result. Can return a modified result
-     * or null to use the original. Use for error handling, logging, or
-     * recovery attempts.
+     * Hooks this agent requires on a direct parent when composed as a `dual_ai`
+     * child tool.
      *
-     * @param state - Thread state
-     * @param toolCall - The failed tool call
-     * @param toolResult - The error result
-     * @returns Modified result or null for original
+     * 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
-     * defineHook({
-     *   hook: 'after_tool_call_failure',
-     *   id: 'log_failure',
-     *   execute: async (state, toolCall, toolResult) => {
-     *     console.error(`Tool ${toolCall.function.name} failed: ${toolResult.error}`);
-     *     return null; // use original error
-     *   },
-     * });
+     * parentHooks: [{
+     *   hook: 'context_compaction',
+     *   reason: 'Compacts the parent history before its context limit is reached.',
+     *   stage: 'after_parent',
+     * }]
      * ```
      */
-    after_tool_call_failure: (state: State, toolCall: ToolCall, toolResult: ToolResult) => Promise<ToolResult | null>;
-    /**
-     * Called when a tool call STARTS — before the tool executes, while the model
-     * may still be generating the rest of the call. Fires exactly once per tool
-     * call. Observational: the return value is ignored.
-     *
-     * Timing depends on whether the tool declares a `progressArgument`:
-     * - **With** `progressArgument`: fires as soon as *just that argument* has
-     *   finished streaming (not the whole call), passing its value as `progress`.
-     *   This lets a UI show "fixing index.html" before a large `content` argument
-     *   finishes generating.
-     * - **Without** `progressArgument`: fires as soon as the tool call appears in
-     *   the stream — its name is known but `toolCall.function.arguments` may be an
-     *   incomplete JSON fragment (or empty), and `progress` is undefined.
-     *
-     * Conforming runtimes also broadcast a `tool_call_started` thread event to
-     * connected clients with `{ id, name, progress }` at the same moment.
-     *
-     * @param state - Thread state
-     * @param toolCall - The starting tool call; `function.arguments` may be incomplete
-     * @param progress - The declared progress-argument value, when available
-     *
-     * @example
-     * ```typescript
-     * defineHook({
-     *   hook: 'tool_call_started',
-     *   id: 'log_tool_start',
-     *   execute: async (state, toolCall, progress) => {
-     *     console.log(`▸ ${toolCall.function.name}${progress ? `: ${progress}` : ''}`);
-     *   },
-     * });
-     * ```
-     */
-    tool_call_started: (state: State, toolCall: ToolCall, progress?: string) => Promise<void>;
-    /**
-     * Called when a tool call is DONE — after it has executed, with its result,
-     * regardless of success or failure. Fires once per tool call. Observational:
-     * the return value is ignored.
-     *
-     * This complements `after_tool_call_success` / `after_tool_call_failure`,
-     * which can additionally *modify* the stored result; `tool_call_done` is a
-     * single unified observation point that always fires. Conforming runtimes
-     * also broadcast a `tool_call_done` thread event to connected clients with
-     * `{ id, name, status }` at the same moment.
-     *
-     * @param state - Thread state
-     * @param toolCall - The completed tool call
-     * @param toolResult - The tool's result (`status` is `'success'` or `'error'`)
-     */
-    tool_call_done: (state: State, toolCall: ToolCall, toolResult: ToolResult) => Promise<void>;
-    /**
-     * Called when a socket attaches to the user's event stream
-     * (`{runtime_prefix}/users/me/stream`).
-     *
-     * @param user - User scope state
-     * @param client - The attached client's id and self-declared kind
-     */
-    user_client_attached: (user: UserState, client: UserClientInfo) => Promise<void>;
-    /**
-     * Called when a socket detaches from the user's event stream.
-     *
-     * @param user - User scope state
-     * @param client - The detached client's id and self-declared kind
-     */
-    user_client_detached: (user: UserState, client: UserClientInfo) => Promise<void>;
-    /**
-     * Called after a durable user value changes, regardless of the writer
-     * (user endpoint, thread-side handle, or REST).
-     *
-     * @param user - User scope state
-     * @param key - The key that changed
-     */
-    user_value_changed: (user: UserState, key: string) => Promise<void>;
-}
-/**
- * Valid hook names.
- */
-type HookName = keyof HookSignatures;
-/**
- * Hook definition tuple.
- *
- * A hook definition is a tuple containing the hook name and implementation.
- *
- * @template K - The hook name
- * @template State - The state type (defaults to ThreadState)
- * @template Msg - The message type
- * @template ToolCall - The tool call type
- * @template ToolResult - The tool result type
- * @deprecated Use the object-based defineHook signature instead
- */
-type HookDefinition<K extends HookName = HookName, State = ThreadState, Msg = HookMessage, ToolCall = HookToolCall, ToolResult = HookToolResult> = [K, HookSignatures<State, Msg, ToolCall, ToolResult>[K]];
-/**
- * Options for defining a hook with explicit ID.
- * The generic K ensures `execute` is properly typed for the specific hook type.
- *
- * @template K - Hook type from HookSignatures (e.g., 'filter_messages')
- */
-interface HookDefinitionOptions<K extends HookName> {
-    /** The hook type (e.g., 'filter_messages', 'before_create_message') */
-    hook: K;
-    /** Unique identifier for this hook implementation (snake_case) */
-    id: string;
-    /**
-     * The hook implementation function.
-     * Type is automatically inferred from the hook type.
-     */
-    execute: HookSignatures<ThreadState, HookMessage, HookToolCall, HookToolResult>[K];
-}
-/**
- * Return type from defineHook - preserves the hook type for type-safe usage.
- *
- * @template K - Hook type from HookSignatures
- */
-interface HookDefinitionResult<K extends HookName> {
-    /** The hook type name */
-    hook: K;
-    /** The unique hook ID */
-    id: string;
-    /** The typed execute function */
-    execute: HookSignatures<ThreadState, HookMessage, HookToolCall, HookToolResult>[K];
+    parentHooks?: ParentHookRequirement[];
 }
 /**
- * Define a hook with a unique identifier and strict typing.
+ * Defines an agent configuration.
  *
- * The hook type determines the execute function signature.
- * TypeScript will enforce correct parameter and return types.
+ * 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.
  *
- * @template K - The hook type (inferred from options.hook)
- * @param options - Hook definition with hook type, ID, and execute function
- * @returns Typed hook definition for registration
+ * @template N - The agent name as a string literal type
+ * @param options - Agent configuration options
+ * @returns The agent definition for registration
  *
  * @example
  * ```typescript
- * // Filter messages - execute receives (state: ThreadState, messages: HookMessage[])
- * export default defineHook({
- *   hook: 'filter_messages',
- *   id: 'limit_to_20_messages',
- *   execute: async (state, messages) => {
- *     return messages.slice(-20);
- *   }
- * });
- * ```
+ * // agents/agents/support_agent.ts
+ * import { defineAgent } from '@standardagents/spec';
  *
- * @example
- * ```typescript
- * // Before create message - execute receives (state: ThreadState, message: Message)
- * export default defineHook({
- *   hook: 'before_create_message',
- *   id: 'prefix_content',
- *   execute: async (state, message) => {
- *     if (message.role === 'user' && message.content) {
- *       return { ...message, content: `[user] ${message.content}` };
- *     }
- *     return message;
- *   }
+ * export default defineAgent({
+ *   name: 'support_agent',
+ *   title: 'Customer Support Agent',
+ *   type: 'ai_human',
+ *   sideA: {
+ *     label: 'Support',
+ *     prompt: 'customer_support',
+ *     stopOnResponse: true,
+ *     sessionStop: 'close_ticket',
+ *   },
+ *   exposeAsTool: true,
+ *   toolDescription: 'Hand off to customer support',
  * });
  * ```
  *
  * @example
  * ```typescript
- * // After tool call success - execute receives (state, toolCall, toolResult)
- * export default defineHook({
- *   hook: 'after_tool_call_success',
- *   id: 'log_tool_usage',
- *   execute: async (state, toolCall, toolResult) => {
- *     console.log(`Tool ${toolCall.function.name} returned: ${toolResult.result}`);
- *     return null; // Use original result
- *   }
+ * // Dual AI agent (two AIs conversing)
+ * export default defineAgent({
+ *   name: 'debate_agent',
+ *   title: 'AI Debate',
+ *   type: 'dual_ai',
+ *   maxSessionTurns: 10,
+ *   sideA: {
+ *     label: 'Pro',
+ *     prompt: 'debate_pro',
+ *     stopOnResponse: true,
+ *   },
+ *   sideB: {
+ *     label: 'Con',
+ *     prompt: 'debate_con',
+ *     stopOnResponse: true,
+ *     sessionStop: 'conclude_debate',
+ *   },
  * });
  * ```
  */
-declare function defineHook<K extends HookName>(options: HookDefinitionOptions<K>): HookDefinitionResult<K>;
+declare function defineAgent<N extends string>(options: AgentDefinition<N>): AgentDefinition<N>;
 
 /**
- * Agent definition types for Standard Agents.
+ * Endpoint definition types for Standard Agents.
  *
- * 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.
+ * Endpoints expose HTTP APIs for interacting with agent threads.
+ * They can be standard controllers or thread-specific endpoints
+ * with automatic ThreadState injection.
  *
  * @module
  */
+
 /**
- * Agent conversation type.
+ * The access level of an endpoint.
  *
- * - `ai_human`: AI conversing with a human user (most common)
- * - `dual_ai`: Two AI participants conversing with each other
+ * - `authenticated` — the runtime MUST authenticate the request before
+ *   invoking the handler, and for thread endpoints MUST additionally enforce
+ *   its thread access policy. Requests that fail authentication or
+ *   authorization MUST be rejected without invoking the handler.
+ * - `public` — the runtime MUST invoke the handler regardless of the
+ *   request's authentication state. The runtime MUST still attempt caller
+ *   resolution: a request presenting credentials the runtime can verify is
+ *   attributed to that caller, and any other request is treated as anonymous
+ *   rather than rejected.
+ *
+ * When no access level is declared, the access level is `authenticated`.
  */
-type AgentType = 'ai_human' | 'dual_ai';
+type EndpointAccess = 'authenticated' | 'public';
 /**
- * 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
+ * Symbol used to carry an endpoint's declared access level.
  *
- * @template Callable - Callable name type
+ * The declaration is attached to the handler at definition time so that
+ * runtimes can read it before routing the request through their
+ * authentication layer.
  */
-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;
+declare const ENDPOINT_ACCESS_SYMBOL: unique symbol;
+/**
+ * Options accepted when defining an endpoint.
+ */
+interface EndpointOptions {
     /**
-     * Optional tool-argument property containing attachment path(s).
-     * Supports a single path string or an array of path strings.
+     * The endpoint's access level. Defaults to `authenticated`.
      */
-    attachmentsProperty?: string;
+    access?: EndpointAccess;
 }
 /**
- * Session lifecycle tool reference.
+ * Resolve the declared access level of an endpoint handler.
  *
- * Can be either:
- * - a plain tool name string (legacy/simple form)
- * - a {@link SessionToolConfig} object (explicit mapping form)
+ * Returns `authenticated` when the value carries no declaration.
  */
-type SessionToolBinding<Callable extends string = StandardAgentSpec.Callables> = Callable | SessionToolConfig<Callable>;
+declare function getEndpointAccess(value: unknown): EndpointAccess;
 /**
- * Configuration for one side of an agent conversation.
- *
- * 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.
+ * The authentication context supplied to a thread endpoint handler.
  *
- * @template Prompt - The prompt reference type (string or type-safe union)
- * @template Callable - The callable reference type (string or type-safe union)
+ * The runtime constructs this context for every invocation:
  *
- * @example
- * ```typescript
- * const sideConfig: SideConfig = {
- *   label: 'Support Agent',
- *   prompt: 'customer_support',
- *   stopOnResponse: true,
- *   maxSteps: 10,
- * };
- * ```
+ * - `caller` MUST be the authenticated identity when the request presented
+ *   credentials the runtime verified, and `null` otherwise. For an endpoint
+ *   whose access level is `authenticated`, `caller` is always non-null.
+ * - `threadAccess` MUST be `true` if and only if the runtime's thread access
+ *   policy grants the resolved caller access to the requested thread. It
+ *   MUST be `false` when `caller` is `null`. For an endpoint whose access
+ *   level is `authenticated`, `threadAccess` is always `true`.
+ *
+ * The mechanism by which a runtime authenticates requests is
+ * implementation-defined; this interface defines only the identity contract
+ * observable by endpoint code.
  */
-interface SideConfig<Prompt extends string = StandardAgentSpec.Prompts, Callable extends string = StandardAgentSpec.Callables> {
-    /**
-     * Custom label for this side of the conversation.
-     * Used in UI and logs for clarity.
-     *
-     * @example 'Support Agent', 'Customer', 'ATC', 'Pilot'
-     */
-    label?: string;
-    /**
-     * The prompt to use for this side.
-     * Must reference a prompt defined in agents/prompts/.
-     */
-    prompt: Prompt;
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * 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.
-     *
-     * In subagent runtimes, mapped message/attachments are the canonical
-     * completion payload returned from child -> parent.
-     */
-    sessionStop?: SessionToolBinding<Callable>;
+interface ThreadEndpointAuth {
+    /** The authenticated caller, or `null` for an anonymous request. */
+    caller: ThreadUser | null;
+    /** Whether the caller satisfies the runtime's access policy for the requested thread. */
+    threadAccess: boolean;
+}
+/**
+ * Symbol used to identify thread endpoint handlers.
+ *
+ * When a handler is created with defineThreadEndpoint, it's marked with this
+ * symbol so the runtime can detect it and wrap it with proper ThreadState injection.
+ */
+declare const THREAD_ENDPOINT_SYMBOL: unique symbol;
+/**
+ * A controller that has been marked as a thread endpoint.
+ *
+ * The runtime detects this marker and wraps the handler with ThreadState injection.
+ * The `__handler` property contains the original handler function that expects
+ * `(req: Request, state: ThreadState)` arguments.
+ */
+interface MarkedThreadEndpoint extends Controller {
+    /** Marker symbol indicating this is a thread endpoint */
+    [THREAD_ENDPOINT_SYMBOL]: true;
+    /** The original handler function before wrapping */
+    __handler: ThreadEndpointHandler;
+}
+/**
+ * Type guard to check if a controller is a marked thread endpoint.
+ */
+declare function isThreadEndpoint(controller: Controller): controller is MarkedThreadEndpoint;
+/**
+ * Virtual module loader function.
+ *
+ * Lazy-loads a module definition on demand.
+ */
+type VirtualModuleLoader<T> = () => Promise<T>;
+/**
+ * Registry of virtual modules by name.
+ *
+ * Maps module names to their lazy loaders.
+ */
+type VirtualModuleRegistry<T> = Record<string, VirtualModuleLoader<T>>;
+/**
+ * Controller context passed to route handlers.
+ *
+ * Contains the request, URL parameters, environment bindings,
+ * and optionally the virtual module registries injected at runtime.
+ *
+ * Note: The `env` property contains implementation-specific bindings.
+ * Its shape is defined by the runtime — typical surfaces include handles
+ * to storage, queues, key-value stores, or other platform resources the
+ * runtime chooses to expose.
+ */
+interface ControllerContext {
+    /** The incoming HTTP request */
+    req: Request;
     /**
-     * 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.
+     * The authenticated caller, or `null` for an anonymous request.
      *
-     * In subagent runtimes, mapped message/attachments are the canonical
-     * failure payload returned from child -> parent.
+     * Populated under the same contract as {@link ThreadEndpointAuth.caller}:
+     * non-null whenever the request presented credentials the runtime
+     * verified, and always non-null for a controller whose access level is
+     * `authenticated`.
      */
-    sessionFail?: SessionToolBinding<Callable>;
+    caller?: ThreadUser | null;
+    /** URL path parameters extracted by the router */
+    params: Record<string, string>;
+    /** Parsed URL object */
+    url: URL;
     /**
-     * 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.
+     * Environment bindings (implementation-specific).
      *
-     * @example
-     * ```typescript
-     * sideA: {
-     *   prompt: 'research_worker',
-     *   sessionStatus: { name: 'update_status', messageProperty: 'status' },
-     * }
-     * ```
+     * Contains platform-specific bindings — handles to storage,
+     * queues, key-value stores, or other resources the runtime exposes.
+     * The exact contents depend on the runtime implementation.
      */
-    sessionStatus?: SessionToolBinding<Callable>;
+    env: Record<string, unknown>;
+    /** Registry of agent definitions (injected at runtime) */
+    agents?: VirtualModuleRegistry<unknown>;
+    /** Available agent names */
+    agentNames?: string[];
+    /** Registry of prompt definitions (injected at runtime) */
+    prompts?: VirtualModuleRegistry<unknown>;
+    /** Available prompt names */
+    promptNames?: string[];
+    /** Registry of model definitions (injected at runtime) */
+    models?: VirtualModuleRegistry<unknown>;
+    /** Available model names */
+    modelNames?: string[];
+    /** Registry of tool definitions (injected at runtime) */
+    tools?: VirtualModuleRegistry<unknown>;
+    /** Registry of hook definitions (injected at runtime) */
+    hooks?: VirtualModuleRegistry<unknown>;
+    /** Additional configuration (injected at runtime) */
+    config?: Record<string, unknown>;
 }
 /**
- * Agent definition configuration.
+ * Controller return types.
  *
- * @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)
+ * Controllers can return various types that are automatically
+ * converted to appropriate HTTP responses.
+ */
+type ControllerReturn = string | Promise<string> | Response | Promise<Response> | ReadableStream | Promise<ReadableStream> | null | Promise<null> | void | Promise<void> | Promise<object> | object;
+/**
+ * Controller function type.
+ *
+ * Controllers handle HTTP requests and return responses.
+ * The return value is automatically converted to a Response.
  *
  * @example
  * ```typescript
- * import { defineAgent } from '@standardagents/spec';
+ * const handler: Controller = async ({ req, params, url }) => {
+ *   return { message: 'Hello, World!' };
+ * };
+ * ```
+ */
+type Controller = (context: ControllerContext) => ControllerReturn;
+/**
+ * Thread endpoint handler function.
  *
- * export default defineAgent({
- *   name: 'support_agent',
- *   title: 'Customer Support Agent',
- *   type: 'ai_human',
- *   sideA: {
- *     label: 'Support',
- *     prompt: 'customer_support',
- *     stopOnResponse: true,
- *   },
+ * Receives the HTTP request and the ThreadState for the requested thread.
+ * The supplied ThreadState includes the standard thread surface, including
+ * `runCode`. The thread is automatically looked up by ID from URL parameters. Route
+ * parameters are derived from the endpoint file path. For a dynamic segment
+ * such as `[id].ts`, `params.id` contains the matched segment. For a catch-all
+ * segment `[*].ts`, `params['*']` contains the unmatched path suffix,
+ * including `/` separators when the match spans multiple segments.
+ *
+ * Thread endpoint routes are scoped beneath the runtime's thread ID prefix.
+ * A request under that prefix that does not match any local or packed thread
+ * endpoint route MUST return HTTP 404.
+ *
+ * The fourth argument carries the request's authentication context under the
+ * contract defined by {@link ThreadEndpointAuth}. Handlers that do not
+ * consume it may omit the parameter.
+ */
+type ThreadEndpointRouteParams = Record<string, string>;
+type ThreadEndpointHandler = (req: Request, state: ThreadState, params: ThreadEndpointRouteParams, auth: ThreadEndpointAuth) => Response | Promise<Response>;
+/**
+ * Define a standard HTTP controller.
+ *
+ * Controllers handle HTTP requests and return responses. They have
+ * access to the controller context including virtual module registries.
+ *
+ * A controller's access level is declared through `options.access` and
+ * defaults to `authenticated`; see {@link EndpointAccess} for the
+ * requirements each level places on the runtime.
+ *
+ * @param controller - The controller function
+ * @param options - Endpoint options, including the access level
+ * @returns The controller for registration
+ *
+ * @example
+ * ```typescript
+ * // agents/api/health.get.ts
+ * import { defineController } from '@standardagents/spec';
+ *
+ * export default defineController(async () => {
+ *   return { status: 'ok', timestamp: Date.now() };
  * });
  * ```
- */
-interface AgentDefinition<N extends string = string, Prompt extends string = StandardAgentSpec.Prompts, Callable extends string = StandardAgentSpec.Callables> {
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * Agent conversation type.
-     *
-     * - `ai_human`: AI conversing with a human user (default)
-     * - `dual_ai`: Two AI participants conversing
-     *
-     * @default 'ai_human'
-     */
-    type?: AgentType;
-    /**
-     * Maximum total turns across both sides.
-     * Only applies to `dual_ai` agents.
-     * Prevents infinite loops in AI-to-AI conversations.
-     */
-    maxSessionTurns?: number;
-    /**
-     * Configuration for Side A.
-     * For `ai_human`: This is the AI side.
-     * For `dual_ai`: This is the first AI participant.
-     */
-    sideA: SideConfig<Prompt, Callable>;
-    /**
-     * Configuration for Side B.
-     * For `ai_human`: Optional, the human side doesn't need config.
-     * For `dual_ai`: Required, the second AI participant.
-     */
-    sideB?: SideConfig<Prompt, Callable>;
-    /**
-     * 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.
-     * @default false
-     */
-    exposeAsTool?: boolean;
-    /**
-     * Whether this agent is a PRIMARY, user-facing entry point (default true).
-     *
-     * Set `primary: false` on agents that exist only as internal handoff
-     * targets or infrastructure — e.g. the specialist variants of a
-     * domain-routing gearbox. Non-primary agents remain fully addressable
-     * (handoffs, invokeTool, thread resumption) and their threads remain
-     * 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;
-    /**
-     * Description shown when agent is used as a tool.
-     * Required if exposeAsTool is true.
-     * Should clearly describe what this agent does.
-     */
-    toolDescription?: string;
-    /**
-     * Brief description of what this agent does.
-     * Useful for UIs and documentation.
-     *
-     * @example 'Handles customer support inquiries and resolves issues'
-     */
-    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;
-    /**
-     * 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>;
-    /**
-     * npm package name for this agent when packed.
-     * Used by the packing system to maintain consistent package identity
-     * across pack/unpack cycles.
-     *
-     * @example 'standardagent-support-agent', '@myorg/support-agent'
-     */
-    packageName?: string;
-    /**
-     * Package version (semver format).
-     * Used by the packing system to track versions across pack/unpack cycles.
-     * When re-packing, this version is auto-incremented by the pack modal.
-     *
-     * @example '1.0.0', '2.3.1-beta.1'
-     */
-    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;
-    /**
-     * License identifier (SPDX format).
-     * Used by the packing system for LICENSE file generation.
-     *
-     * @example 'MIT', 'Apache-2.0', 'ISC'
-     */
-    license?: string;
-    /**
-     * Hook IDs to run for this agent.
-     * References hooks by their unique `id` property from defineHook().
-     * These run when prompts don't specify their own hooks.
-     *
-     * @example
-     * ```typescript
-     * hooks: ['log_messages', 'track_tool_usage']
-     * ```
-     */
-    hooks?: StandardAgentSpec.HookIds[];
-}
+ *
+ * @example
+ * ```typescript
+ * // agents/api/agents/index.get.ts
+ * import { defineController } from '@standardagents/spec';
+ *
+ * export default defineController(async ({ agentNames }) => {
+ *   return { agents: agentNames };
+ * });
+ * ```
+ */
+declare function defineController(controller: Controller, options?: EndpointOptions): Controller;
 /**
- * Defines an agent configuration.
+ * Define a thread-specific endpoint.
  *
- * 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.
+ * Thread endpoints automatically look up the thread by ID from URL params
+ * and provide access to the ThreadState. The handler receives full
+ * ThreadState with messages, logs, resource loading, event emission,
+ * and (when executing) execution state.
  *
- * @template N - The agent name as a string literal type
- * @param options - Agent configuration options
- * @returns The agent definition for registration
+ * Runtimes MUST return HTTP 404 for requests beneath the thread endpoint
+ * prefix that do not match any local or packed thread endpoint route.
+ *
+ * A thread endpoint's access level is declared through `options.access` and
+ * defaults to `authenticated`; see {@link EndpointAccess} for the
+ * requirements each level places on the runtime. Handlers receive the
+ * request's authentication context as their fourth argument under the
+ * contract defined by {@link ThreadEndpointAuth}.
+ *
+ * @param handler - The handler function receiving request, ThreadState, route params, and authentication context
+ * @param options - Endpoint options, including the access level
+ * @returns A Controller that can be used with the router
  *
  * @example
  * ```typescript
- * // agents/agents/support_agent.ts
- * import { defineAgent } from '@standardagents/spec';
+ * // agents/api/status.ts
+ * import { defineThreadEndpoint } from '@standardagents/spec';
  *
- * export default defineAgent({
- *   name: 'support_agent',
- *   title: 'Customer Support Agent',
- *   type: 'ai_human',
- *   sideA: {
- *     label: 'Support',
- *     prompt: 'customer_support',
- *     stopOnResponse: true,
- *     sessionStop: 'close_ticket',
- *   },
- *   exposeAsTool: true,
- *   toolDescription: 'Hand off to customer support',
+ * export default defineThreadEndpoint(async (req, state) => {
+ *   const { messages, total } = await state.getMessages({ limit: 1 });
+ *   return Response.json({
+ *     threadId: state.threadId,
+ *     agent: state.agentId,
+ *     messageCount: total,
+ *   });
  * });
  * ```
  *
  * @example
  * ```typescript
- * // Dual AI agent (two AIs conversing)
- * export default defineAgent({
- *   name: 'debate_agent',
- *   title: 'AI Debate',
- *   type: 'dual_ai',
- *   maxSessionTurns: 10,
- *   sideA: {
- *     label: 'Pro',
- *     prompt: 'debate_pro',
- *     stopOnResponse: true,
- *   },
- *   sideB: {
- *     label: 'Con',
- *     prompt: 'debate_con',
- *     stopOnResponse: true,
- *     sessionStop: 'conclude_debate',
- *   },
+ * // agents/api/export.ts
+ * import { defineThreadEndpoint } from '@standardagents/spec';
+ *
+ * export default defineThreadEndpoint(async (req, state) => {
+ *   const { messages } = await state.getMessages();
+ *   return Response.json({
+ *     thread: {
+ *       id: state.threadId,
+ *       agent: state.agentId,
+ *       user: state.userId,
+ *       createdAt: state.createdAt,
+ *     },
+ *     messages,
+ *   });
  * });
  * ```
- */
-declare function defineAgent<N extends string>(options: AgentDefinition<N>): AgentDefinition<N>;
-
-/**
- * Endpoint definition types for Standard Agents.
  *
- * Endpoints expose HTTP APIs for interacting with agent threads.
- * They can be standard controllers or thread-specific endpoints
- * with automatic ThreadState injection.
- *
- * @module
- */
-
-/**
- * The access level of an endpoint.
+ * @example
+ * ```typescript
+ * // agents/api/invoke.post.ts
+ * import { defineThreadEndpoint } from '@standardagents/spec';
  *
- * - `authenticated` — the runtime MUST authenticate the request before
- *   invoking the handler, and for thread endpoints MUST additionally enforce
- *   its thread access policy. Requests that fail authentication or
- *   authorization MUST be rejected without invoking the handler.
- * - `public` — the runtime MUST invoke the handler regardless of the
- *   request's authentication state. The runtime MUST still attempt caller
- *   resolution: a request presenting credentials the runtime can verify is
- *   attributed to that caller, and any other request is treated as anonymous
- *   rather than rejected.
+ * export default defineThreadEndpoint(async (req, state) => {
+ *   const { tool, args } = await req.json();
  *
- * When no access level is declared, the access level is `authenticated`.
- */
-type EndpointAccess = 'authenticated' | 'public';
-/**
- * Symbol used to carry an endpoint's declared access level.
+ *   // Queue a tool for execution (starts execution if not running)
+ *   state.queueTool(tool, args);
  *
- * The declaration is attached to the handler at definition time so that
- * runtimes can read it before routing the request through their
- * authentication layer.
- */
-declare const ENDPOINT_ACCESS_SYMBOL: unique symbol;
-/**
- * Options accepted when defining an endpoint.
- */
-interface EndpointOptions {
-    /**
-     * The endpoint's access level. Defaults to `authenticated`.
-     */
-    access?: EndpointAccess;
-}
-/**
- * Resolve the declared access level of an endpoint handler.
+ *   return Response.json({ queued: true });
+ * });
+ * ```
  *
- * Returns `authenticated` when the value carries no declaration.
- */
-declare function getEndpointAccess(value: unknown): EndpointAccess;
-/**
- * The authentication context supplied to a thread endpoint handler.
+ * @example
+ * ```typescript
+ * // agents/api/files/[id].ts
+ * import { defineThreadEndpoint } from '@standardagents/spec';
  *
- * The runtime constructs this context for every invocation:
+ * export default defineThreadEndpoint(async (req, state, params) => {
+ *   const file = await state.readFile(`/files/${params.id}.json`);
+ *   return Response.json({ exists: !!file });
+ * });
+ * ```
  *
- * - `caller` MUST be the authenticated identity when the request presented
- *   credentials the runtime verified, and `null` otherwise. For an endpoint
- *   whose access level is `authenticated`, `caller` is always non-null.
- * - `threadAccess` MUST be `true` if and only if the runtime's thread access
- *   policy grants the resolved caller access to the requested thread. It
- *   MUST be `false` when `caller` is `null`. For an endpoint whose access
- *   level is `authenticated`, `threadAccess` is always `true`.
+ * @example
+ * ```typescript
+ * // agents/api/status.ts
+ * import { defineThreadEndpoint } from '@standardagents/spec';
  *
- * The mechanism by which a runtime authenticates requests is
- * implementation-defined; this interface defines only the identity contract
- * observable by endpoint code.
+ * export default defineThreadEndpoint(
+ *   async (req, state, params, auth) => {
+ *     return Response.json({
+ *       threadId: state.threadId,
+ *       authorized: auth.threadAccess,
+ *     });
+ *   },
+ *   { access: 'public' }
+ * );
+ * ```
  */
-interface ThreadEndpointAuth {
-    /** The authenticated caller, or `null` for an anonymous request. */
-    caller: ThreadUser | null;
-    /** Whether the caller satisfies the runtime's access policy for the requested thread. */
-    threadAccess: boolean;
-}
+declare function defineThreadEndpoint(handler: ThreadEndpointHandler, options?: EndpointOptions): MarkedThreadEndpoint;
+
 /**
- * Symbol used to identify thread endpoint handlers.
+ * Packing types for Standard Agents.
  *
- * When a handler is created with defineThreadEndpoint, it's marked with this
- * symbol so the runtime can detect it and wrap it with proper ThreadState injection.
+ * Defines types for packaging agents with their dependencies into
+ * reusable, encapsulated packages that can be published to npm
+ * or stored locally.
+ *
+ * @module
  */
-declare const THREAD_ENDPOINT_SYMBOL: unique symbol;
 /**
- * A controller that has been marked as a thread endpoint.
+ * Package signature applied to packed definitions.
  *
- * The runtime detects this marker and wraps the handler with ThreadState injection.
- * The `__handler` property contains the original handler function that expects
- * `(req: Request, state: ThreadState)` arguments.
+ * When an agent and its dependencies are packed, each definition
+ * receives this signature marking it as belonging to a specific package.
+ * This enables namespace isolation during execution.
+ *
+ * @example
+ * ```typescript
+ * const signature: PackageSignature = {
+ *   packageId: 'standardagent-my-workflow',
+ *   version: '1.0.0',
+ *   source: 'npm',
+ *   packedAt: Date.now(),
+ * };
+ * ```
  */
-interface MarkedThreadEndpoint extends Controller {
-    /** Marker symbol indicating this is a thread endpoint */
-    [THREAD_ENDPOINT_SYMBOL]: true;
-    /** The original handler function before wrapping */
-    __handler: ThreadEndpointHandler;
+interface PackageSignature {
+    /** Unique package identifier (npm name or local identifier) */
+    packageId: string;
+    /** Package version */
+    version: string;
+    /** Source type */
+    source: 'npm' | 'local';
+    /** When packed (timestamp in milliseconds) */
+    packedAt: number;
 }
 /**
- * Type guard to check if a controller is a marked thread endpoint.
+ * Global namespace context - for unpacked code.
+ *
+ * Unpacked code sees:
+ * - All unpacked tools, prompts, models, hooks
+ * - Packed agent entry points (agents with exposeAsTool: true)
+ * - NOT internal packed tools/prompts (those are hidden)
  */
-declare function isThreadEndpoint(controller: Controller): controller is MarkedThreadEndpoint;
+interface GlobalNamespaceContext {
+    type: 'global';
+}
 /**
- * Virtual module loader function.
+ * Packed namespace context - for code inside a packed agent.
  *
- * Lazy-loads a module definition on demand.
+ * Packed code sees:
+ * - Only items within its own package (by packageId)
+ * - Other packed agent entry points (for handoffs)
+ * - NOT unpacked global code
  */
-type VirtualModuleLoader<T> = () => Promise<T>;
+interface PackedNamespaceContext {
+    type: 'packed';
+    /** Package ID this code belongs to */
+    packageId: string;
+}
 /**
- * Registry of virtual modules by name.
+ * Namespace context for execution.
+ * Determines what items are visible during execution.
  *
- * Maps module names to their lazy loaders.
+ * @example
+ * ```typescript
+ * // Global namespace (unpacked code)
+ * const globalNs: NamespaceContext = { type: 'global' };
+ *
+ * // Packed namespace (inside a packed agent)
+ * const packedNs: NamespaceContext = {
+ *   type: 'packed',
+ *   packageId: 'standardagent-my-workflow',
+ * };
+ * ```
  */
-type VirtualModuleRegistry<T> = Record<string, VirtualModuleLoader<T>>;
+type NamespaceContext = GlobalNamespaceContext | PackedNamespaceContext;
 /**
- * Controller context passed to route handlers.
- *
- * Contains the request, URL parameters, environment bindings,
- * and optionally the virtual module registries injected at runtime.
+ * Extended metadata for packed definitions.
  *
- * Note: The `env` property contains implementation-specific bindings.
- * Its shape is defined by the runtime — typical surfaces include handles
- * to storage, queues, key-value stores, or other platform resources the
- * runtime chooses to expose.
+ * This interface is added to agent, prompt, tool, model, and hook
+ * definitions when they are packed. It marks them as belonging
+ * to a specific package and optionally as readonly.
  */
-interface ControllerContext {
-    /** The incoming HTTP request */
-    req: Request;
+interface PackedMetadata {
     /**
-     * The authenticated caller, or `null` for an anonymous request.
-     *
-     * Populated under the same contract as {@link ThreadEndpointAuth.caller}:
-     * non-null whenever the request presented credentials the runtime
-     * verified, and always non-null for a controller whose access level is
-     * `authenticated`.
+     * Package signature if this definition is part of a packed agent.
+     * Undefined for unpacked (global) definitions.
      */
-    caller?: ThreadUser | null;
-    /** URL path parameters extracted by the router */
-    params: Record<string, string>;
-    /** Parsed URL object */
-    url: URL;
+    __package?: PackageSignature;
     /**
-     * Environment bindings (implementation-specific).
-     *
-     * Contains platform-specific bindings — handles to storage,
-     * queues, key-value stores, or other resources the runtime exposes.
-     * The exact contents depend on the runtime implementation.
+     * Whether this definition is readonly (cannot be edited in UI).
+     * Packed definitions are typically readonly.
      */
-    env: Record<string, unknown>;
-    /** Registry of agent definitions (injected at runtime) */
-    agents?: VirtualModuleRegistry<unknown>;
-    /** Available agent names */
-    agentNames?: string[];
-    /** Registry of prompt definitions (injected at runtime) */
-    prompts?: VirtualModuleRegistry<unknown>;
-    /** Available prompt names */
-    promptNames?: string[];
-    /** Registry of model definitions (injected at runtime) */
-    models?: VirtualModuleRegistry<unknown>;
-    /** Available model names */
-    modelNames?: string[];
-    /** Registry of tool definitions (injected at runtime) */
-    tools?: VirtualModuleRegistry<unknown>;
-    /** Registry of hook definitions (injected at runtime) */
-    hooks?: VirtualModuleRegistry<unknown>;
-    /** Additional configuration (injected at runtime) */
-    config?: Record<string, unknown>;
+    __readonly?: boolean;
 }
 /**
- * Controller return types.
+ * Helper type to check if a definition is packed.
+ */
+declare function isPacked(metadata: PackedMetadata | undefined): metadata is PackedMetadata & {
+    __package: PackageSignature;
+};
+/**
+ * Helper to check if a definition belongs to a specific package.
+ */
+declare function belongsToPackage(metadata: PackedMetadata | undefined, packageId: string): boolean;
+/**
+ * Helper to check if a definition is visible in a given namespace.
  *
- * Controllers can return various types that are automatically
- * converted to appropriate HTTP responses.
+ * @param metadata - The definition's packed metadata
+ * @param namespace - The current namespace context
+ * @param isEntryPoint - Whether this is an agent with exposeAsTool: true
  */
-type ControllerReturn = string | Promise<string> | Response | Promise<Response> | ReadableStream | Promise<ReadableStream> | null | Promise<null> | void | Promise<void> | Promise<object> | object;
+declare function isVisibleInNamespace(metadata: PackedMetadata | undefined, namespace: NamespaceContext, isEntryPoint?: boolean): boolean;
 /**
- * Controller function type.
+ * Metadata export for packed packages.
  *
- * Controllers handle HTTP requests and return responses.
- * The return value is automatically converted to a Response.
+ * This is exported as `__meta` from the packed package's index.ts,
+ * replacing the manifest.json file from the old format.
+ *
+ * A packed package's required execution behavior must use capabilities
+ * defined by the Standard Agent Specification. It must not depend on private
+ * runtime RPCs, storage schemas, bindings, undocumented events, sidecars that
+ * replace runtime primitives, or `ThreadState._notPackableRuntimeContext`.
  *
  * @example
  * ```typescript
- * const handler: Controller = async ({ req, params, url }) => {
- *   return { message: 'Hello, World!' };
+ * export const __meta: PackedMeta = {
+ *   packageId: 'standardagent-my-workflow',
+ *   version: '1.0.0',
+ *   entryAgents: ['my_agent'],
+ *   packedAt: 1705012800000,
  * };
  * ```
  */
-type Controller = (context: ControllerContext) => ControllerReturn;
-/**
- * Thread endpoint handler function.
- *
- * Receives the HTTP request and the ThreadState for the requested thread.
- * The supplied ThreadState includes the standard thread surface, including
- * `runCode`. The thread is automatically looked up by ID from URL parameters. Route
- * parameters are derived from the endpoint file path. For a dynamic segment
- * such as `[id].ts`, `params.id` contains the matched segment. For a catch-all
- * segment `[*].ts`, `params['*']` contains the unmatched path suffix,
- * including `/` separators when the match spans multiple segments.
- *
- * Thread endpoint routes are scoped beneath the runtime's thread ID prefix.
- * A request under that prefix that does not match any local or packed thread
- * endpoint route MUST return HTTP 404.
- *
- * The fourth argument carries the request's authentication context under the
- * contract defined by {@link ThreadEndpointAuth}. Handlers that do not
- * consume it may omit the parameter.
- */
-type ThreadEndpointRouteParams = Record<string, string>;
-type ThreadEndpointHandler = (req: Request, state: ThreadState, params: ThreadEndpointRouteParams, auth: ThreadEndpointAuth) => Response | Promise<Response>;
+interface PackedMeta {
+    /** Unique package identifier (npm name or local identifier) */
+    packageId: string;
+    /** Package version (semver) */
+    version: string;
+    /** Entry agents exposed as tools (visible from outside the package) */
+    entryAgents: string[];
+    /** When the package was packed (timestamp in milliseconds) */
+    packedAt: number;
+    /** Optional description from the entry agent */
+    description?: string;
+    /**
+     * Required parent-hook disclosures keyed by entry agent name.
+     * This duplicates the executable agent definitions so installers can show
+     * composition effects without importing package code.
+     */
+    parentHooks?: Record<string, ParentHookRequirement[]>;
+}
 /**
- * Define a standard HTTP controller.
- *
- * Controllers handle HTTP requests and return responses. They have
- * access to the controller context including virtual module registries.
- *
- * A controller's access level is declared through `options.access` and
- * defaults to `authenticated`; see {@link EndpointAccess} for the
- * requirements each level places on the runtime.
- *
- * @param controller - The controller function
- * @param options - Endpoint options, including the access level
- * @returns The controller for registration
- *
- * @example
- * ```typescript
- * // agents/api/health.get.ts
- * import { defineController } from '@standardagents/spec';
+ * Lazy loader type for packed definitions.
  *
- * export default defineController(async () => {
- *   return { status: 'ok', timestamp: Date.now() };
- * });
- * ```
+ * Each definition in a packed package is wrapped in a function
+ * that returns a Promise, enabling lazy loading.
  *
  * @example
  * ```typescript
- * // agents/api/agents/index.get.ts
- * import { defineController } from '@standardagents/spec';
- *
- * export default defineController(async ({ agentNames }) => {
- *   return { agents: agentNames };
- * });
+ * export const tools = {
+ *   search: async (): Promise<ToolDefinition> => ({
+ *     description: 'Search for information',
+ *     execute: async (state, args) => { ... },
+ *   }),
+ * } as const;
  * ```
  */
-declare function defineController(controller: Controller, options?: EndpointOptions): Controller;
+type DefinitionLoader<T> = () => Promise<T>;
+
 /**
- * Define a thread-specific endpoint.
- *
- * Thread endpoints automatically look up the thread by ID from URL params
- * and provide access to the ThreadState. The handler receives full
- * ThreadState with messages, logs, resource loading, event emission,
- * and (when executing) execution state.
- *
- * Runtimes MUST return HTTP 404 for requests beneath the thread endpoint
- * prefix that do not match any local or packed thread endpoint route.
- *
- * A thread endpoint's access level is declared through `options.access` and
- * defaults to `authenticated`; see {@link EndpointAccess} for the
- * requirements each level places on the runtime. Handlers receive the
- * request's authentication context as their fourth argument under the
- * contract defined by {@link ThreadEndpointAuth}.
- *
- * @param handler - The handler function receiving request, ThreadState, route params, and authentication context
- * @param options - Endpoint options, including the access level
- * @returns A Controller that can be used with the router
- *
- * @example
- * ```typescript
- * // agents/api/status.ts
- * import { defineThreadEndpoint } from '@standardagents/spec';
+ * Standard shape for packed package exports.
  *
- * export default defineThreadEndpoint(async (req, state) => {
- *   const { messages, total } = await state.getMessages({ limit: 1 });
- *   return Response.json({
- *     threadId: state.threadId,
- *     agent: state.agentId,
- *     messageCount: total,
- *   });
- * });
- * ```
+ * Every packed package exports this structure, enabling
+ * consistent discovery and loading.
  *
  * @example
  * ```typescript
- * // agents/api/export.ts
- * import { defineThreadEndpoint } from '@standardagents/spec';
+ * import type { PackedExports } from '@standardagents/spec';
  *
- * export default defineThreadEndpoint(async (req, state) => {
- *   const { messages } = await state.getMessages();
- *   return Response.json({
- *     thread: {
- *       id: state.threadId,
- *       agent: state.agentId,
- *       user: state.userId,
- *       createdAt: state.createdAt,
- *     },
- *     messages,
- *   });
- * });
+ * const pkg: PackedExports = await import('standardagent-my-workflow');
+ * const tool = await pkg.tools.search();
  * ```
+ */
+interface PackedExports {
+    /** Agent definitions, keyed by name */
+    agents: Record<string, DefinitionLoader<AgentDefinition>>;
+    /** Prompt definitions, keyed by name */
+    prompts: Record<string, DefinitionLoader<PromptDefinition>>;
+    /** Tool definitions, keyed by name */
+    tools: Record<string, DefinitionLoader<ToolDefinition<unknown, any, any>>>;
+    /** Model definitions, keyed by name */
+    models: Record<string, DefinitionLoader<ModelDefinition>>;
+    /** Hook definitions, keyed by name */
+    hooks: Record<string, DefinitionLoader<HookDefinitionResult<HookName>>>;
+    /**
+     * 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 mount these beneath the same thread ID prefix as local thread
+     * endpoints, using the packed route key to derive the endpoint path.
+     * Requests beneath that prefix that do not match any local or packed thread
+     * endpoint route MUST return HTTP 404.
+     *
+     * Optional for backward compatibility with previously packed packages.
+     */
+    threadEndpoints?: Record<string, DefinitionLoader<MarkedThreadEndpoint | Controller>>;
+    /** Package metadata */
+    __meta: PackedMeta;
+}
+
+/**
+ * Hook definition types for Standard Agents.
  *
- * @example
- * ```typescript
- * // agents/api/invoke.post.ts
- * import { defineThreadEndpoint } from '@standardagents/spec';
- *
- * export default defineThreadEndpoint(async (req, state) => {
- *   const { tool, args } = await req.json();
- *
- *   // Queue a tool for execution (starts execution if not running)
- *   state.queueTool(tool, args);
+ * Hooks allow intercepting and modifying agent behavior at key points
+ * in the execution lifecycle. They enable logging, validation,
+ * transformation, and side effects.
  *
- *   return Response.json({ queued: true });
- * });
- * ```
+ * Thread hooks receive ThreadState as their first parameter and deterministic
+ * execution provenance as their final parameter, providing full access to
+ * thread operations and the reason each hook is active.
  *
- * @example
- * ```typescript
- * // agents/api/files/[id].ts
- * import { defineThreadEndpoint } from '@standardagents/spec';
+ * @module
+ */
+
+/**
+ * Hook context is ThreadState.
  *
- * export default defineThreadEndpoint(async (req, state, params) => {
- *   const file = await state.readFile(`/files/${params.id}.json`);
- *   return Response.json({ exists: !!file });
- * });
- * ```
+ * Hooks receive the full ThreadState, which includes identity, message access,
+ * resource loading, event emission, and execution state (when available).
  *
  * @example
  * ```typescript
- * // agents/api/status.ts
- * import { defineThreadEndpoint } from '@standardagents/spec';
- *
- * export default defineThreadEndpoint(
- *   async (req, state, params, auth) => {
- *     return Response.json({
- *       threadId: state.threadId,
- *       authorized: auth.threadAccess,
- *     });
+ * const hook = defineHook({
+ *   hook: 'filter_messages',
+ *   id: 'keep_recent',
+ *   execute: async (state, messages) => {
+ *     console.log(`Thread: ${state.threadId}`);
+ *     if (state.execution) {
+ *       console.log(`Step: ${state.execution.stepCount}`);
+ *     }
+ *     return messages.slice(-10);
  *   },
- *   { access: 'public' }
- * );
+ * });
  * ```
  */
-declare function defineThreadEndpoint(handler: ThreadEndpointHandler, options?: EndpointOptions): MarkedThreadEndpoint;
-
+type HookContext = ThreadState;
 /**
- * Packing types for Standard Agents.
- *
- * Defines types for packaging agents with their dependencies into
- * reusable, encapsulated packages that can be published to npm
- * or stored locally.
+ * Describes why a thread-scoped hook is active for the current invocation.
  *
- * @module
+ * Parent hooks contributed by a child agent still receive the parent's
+ * ThreadState. The child source additionally identifies the exact relationship
+ * that activated the hook, including the exposed relationship name that may be
+ * passed to `state.invokeTool()` or `state.queueTool()`.
  */
+type HookExecutionSource = {
+    kind: 'prompt';
+    /** Active prompt whose hook list selected this hook. */
+    promptName: string;
+} | {
+    kind: 'agent';
+    /** Active agent whose fallback hook list selected this hook. */
+    agentName: string;
+} | {
+    kind: 'child';
+    /** Model/runtime-facing name of the direct parent-child relationship. */
+    relationshipName: string;
+    /** Implementing child agent reference after alias resolution. */
+    agentName: string;
+    /** Package provenance when the child came from a packed package. */
+    package?: PackageSignature;
+};
 /**
- * Package signature applied to packed definitions.
- *
- * When an agent and its dependencies are packed, each definition
- * receives this signature marking it as belonging to a specific package.
- * This enables namespace isolation during execution.
- *
- * @example
- * ```typescript
- * const signature: PackageSignature = {
- *   packageId: 'standardagent-my-workflow',
- *   version: '1.0.0',
- *   source: 'npm',
- *   packedAt: Date.now(),
- * };
- * ```
+ * Final argument supplied to every thread-scoped hook invocation.
  */
-interface PackageSignature {
-    /** Unique package identifier (npm name or local identifier) */
-    packageId: string;
-    /** Package version */
-    version: string;
-    /** Source type */
-    source: 'npm' | 'local';
-    /** When packed (timestamp in milliseconds) */
-    packedAt: number;
+interface HookExecutionContext {
+    source: HookExecutionSource;
 }
 /**
- * Global namespace context - for unpacked code.
+ * Message structure for hook processing.
  *
- * Unpacked code sees:
- * - All unpacked tools, prompts, models, hooks
- * - Packed agent entry points (agents with exposeAsTool: true)
- * - NOT internal packed tools/prompts (those are hidden)
+ * Re-exported from threads.ts for convenience.
+ * @see Message
  */
-interface GlobalNamespaceContext {
-    type: 'global';
+type HookMessage = Message;
+/**
+ * Tool call structure for hook processing.
+ */
+interface HookToolCall {
+    /** Unique tool call identifier */
+    id: string;
+    /** Always 'function' for tool calls */
+    type: 'function';
+    /** Function details */
+    function: {
+        /** Tool name */
+        name: string;
+        /** JSON-encoded arguments */
+        arguments: string;
+    };
+}
+/**
+ * Tool result structure for hook processing.
+ */
+interface HookToolResult {
+    /** Execution status */
+    status: 'success' | 'error';
+    /** Result string (for successful executions) */
+    result?: string;
+    /** Error message (for failed executions) */
+    error?: string;
+    /** Stack trace (for debugging) */
+    stack?: string;
+    /**
+     * File attachments returned by the tool.
+     *
+     * Can contain either:
+     * - ToolAttachment: New files with base64 data to be stored
+     * - AttachmentRef: References to existing files in the thread filesystem
+     */
+    attachments?: Array<ToolAttachment | AttachmentRef>;
+}
+/**
+ * LLM message format for prefilter hook.
+ *
+ * Messages passed to the prefilter_llm_history hook are in chat completion
+ * format. Content can be a plain string or a multimodal array (for messages
+ * with images). Additional provider-specific fields may also be present.
+ */
+interface LLMMessage {
+    /** Message role */
+    role: string;
+    /** Message content (string for text-only, array for multimodal) */
+    content?: string | null | unknown[];
+    /** Tool calls (parsed) */
+    tool_calls?: unknown;
+    /** Tool call ID */
+    tool_call_id?: string;
+    /** Tool name */
+    name?: string;
+    /** Reasoning content (for models like o1) */
+    reasoning_content?: string;
+    /** Allow additional provider-specific fields */
+    [key: string]: unknown;
+}
+/**
+ * Hook signatures for all available hooks.
+ *
+ * Each hook has a specific signature that defines when it's called
+ * and what data it receives. Hooks can modify data by returning
+ * transformed values or perform side effects.
+ *
+ * All thread hooks receive ThreadState as their first parameter and
+ * HookExecutionContext as their final parameter.
+ *
+ * @template State - The state type (defaults to ThreadState)
+ * @template Msg - The message type (defaults to HookMessage)
+ * @template ToolCall - The tool call type (defaults to HookToolCall)
+ * @template ToolResult - The tool result type (defaults to HookToolResult)
+ */
+interface HookSignatures<State = ThreadState, Msg = HookMessage, ToolCall = HookToolCall, ToolResult = HookToolResult, Context = HookExecutionContext> {
+    /**
+     * Called after a thread is created, before initial message processing or LLM
+     * requests for that thread.
+     *
+     * Only ThreadState is passed. Use for initializing durable thread values,
+     * env placeholders, files, or side-effect instrumentation.
+     *
+     * @param state - Created thread state
+     */
+    after_thread_created: (state: State, context: Context) => Promise<void>;
+    /**
+     * Called on the parent thread immediately after a subagent child thread is
+     * created.
+     *
+     * Receives parent ThreadState and child ThreadState. Use for copying or
+     * linking metadata, bookkeeping, or side-effect instrumentation.
+     *
+     * @param state - Parent thread state
+     * @param childState - Created child thread state
+     */
+    after_subagent_created: (state: State, childState: State, context: Context) => Promise<void>;
+    /**
+     * Called after the prompt system message is rendered for a model request.
+     *
+     * Return a string to replace the rendered system message. Return null or
+     * undefined to keep the original message.
+     *
+     * @param state - Thread state
+     * @param systemMessage - Rendered system message for this request
+     * @returns Replacement system message, or null/undefined for no change
+     */
+    after_system_message: (state: State, systemMessage: string, context: Context) => string | Promise<string | null | undefined> | null | undefined;
+    /**
+     * Called exactly once per model-context assembly on a stable snapshot of
+     * eligible persisted history.
+     *
+     * Receives raw message rows from storage before any transformation.
+     * Use for filtering, sorting, or augmenting message history.
+     * The result is the request context and does not replace
+     * `state.execution.messageHistory`. Messages injected while this hook runs
+     * become eligible for the following context assembly.
+     *
+     * @param state - Thread state
+     * @param messages - Array of messages from storage
+     * @returns Modified message array
+     *
+     * @example
+     * ```typescript
+     * defineHook({
+     *   hook: 'filter_messages',
+     *   id: 'limit_to_10',
+     *   execute: async (state, messages) => messages.slice(-10),
+     * });
+     * ```
+     */
+    filter_messages: (state: State, messages: Msg[], context: Context) => Promise<Msg[]>;
+    /**
+     * Called after filtered history is transformed into provider messages and
+     * before dispatch.
+     *
+     * Receives messages already transformed into chat completion format.
+     * Use for final request-local adjustments. Messages injected while this
+     * hook runs become eligible for the following context assembly.
+     *
+     * @param state - Thread state
+     * @param messages - Array of LLM-formatted messages
+     * @returns Modified LLM message array
+     *
+     * @example
+     * ```typescript
+     * defineHook({
+     *   hook: 'prefilter_llm_history',
+     *   id: 'add_reminder',
+     *   execute: async (state, messages) => messages,
+     * });
+     * ```
+     */
+    prefilter_llm_history: (state: State, messages: LLMMessage[], context: Context) => Promise<LLMMessage[]>;
+    /**
+     * Called before a message is created in the database.
+     *
+     * Receives the full message object before insertion. Return modified
+     * message to transform before storage.
+     *
+     * A hook that throws during `injectMessage()` rejects the injection and
+     * no message is persisted. Other runtime insertions log the failure and
+     * keep the last good message.
+     *
+     * @param state - Thread state
+     * @param message - Message to be created
+     * @returns Modified message
+     *
+     * @example
+     * ```typescript
+     * defineHook({
+     *   hook: 'before_create_message',
+     *   id: 'prefix_content',
+     *   execute: async (state, message) => {
+     *     // message has full type: id, role, content, created_at, etc.
+     *     if (message.role === 'user' && message.content) {
+     *       return { ...message, content: `[user] ${message.content}` };
+     *     }
+     *     return message;
+     *   }
+     * });
+     * ```
+     */
+    before_create_message: (state: State, message: Msg, context: Context) => Promise<Msg>;
+    /**
+     * Called after a message is created in the database.
+     *
+     * Use for logging, analytics, or triggering side effects after
+     * message creation. Cannot modify the message.
+     *
+     * @param state - Thread state
+     * @param message - The created message
+     *
+     * @example
+     * ```typescript
+     * defineHook({
+     *   hook: 'after_create_message',
+     *   id: 'log_creation',
+     *   execute: async (state, message) => {
+     *     console.log(`Created ${message.role} message: ${message.id}`);
+     *   }
+     * });
+     * ```
+     */
+    after_create_message: (state: State, message: Msg, context: Context) => Promise<void>;
+    /**
+     * Called before a message is updated in the database.
+     *
+     * Receives the message ID and update data. Return modified updates
+     * to transform the changes before storage.
+     *
+     * @param state - Thread state
+     * @param messageId - ID of message being updated
+     * @param updates - Update data
+     * @returns Modified update data
+     *
+     * @example
+     * ```typescript
+     * defineHook({
+     *   hook: 'before_update_message',
+     *   id: 'stamp_updated_at',
+     *   execute: async (state, messageId, updates) => ({
+     *     ...updates,
+     *     updated_at: Date.now(),
+     *   }),
+     * });
+     * ```
+     */
+    before_update_message: (state: State, messageId: string, updates: Record<string, unknown>, context: Context) => Promise<Record<string, unknown>>;
+    /**
+     * Called after a message is updated in the database.
+     *
+     * Use for logging, analytics, or triggering side effects after
+     * message update. Cannot modify the message.
+     *
+     * @param state - Thread state
+     * @param message - The updated message
+     *
+     * @example
+     * ```typescript
+     * defineHook({
+     *   hook: 'after_update_message',
+     *   id: 'log_update',
+     *   execute: async (state, message) => {
+     *     console.log(`Message updated: ${message.id}`);
+     *   },
+     * });
+     * ```
+     */
+    after_update_message: (state: State, message: Msg, context: Context) => Promise<void>;
+    /**
+     * Called before a tool result is stored in the database.
+     *
+     * Receives the tool call and result before storage. Return modified
+     * result to transform before storage.
+     *
+     * @param state - Thread state
+     * @param toolCall - The tool call that was executed
+     * @param toolResult - The result from tool execution
+     * @returns Modified tool result
+     *
+     * @example
+     * ```typescript
+     * defineHook({
+     *   hook: 'before_store_tool_result',
+     *   id: 'sanitize_results',
+     *   execute: async (state, toolCall, toolResult) => {
+     *     // toolCall has: id, type, function.name, function.arguments
+     *     // toolResult has: status, result?, error?, stack?, attachments?
+     *     if (toolResult.result) {
+     *       return { ...toolResult, result: sanitize(toolResult.result) };
+     *     }
+     *     return toolResult;
+     *   }
+     * });
+     * ```
+     */
+    before_store_tool_result: (state: State, toolCall: ToolCall, toolResult: ToolResult, context: Context) => Promise<ToolResult>;
+    /**
+     * Called after a successful tool call.
+     *
+     * Receives the tool call and its result. Can return a modified result
+     * or null to use the original. Use for logging, transformation, or
+     * post-processing of successful tool executions.
+     *
+     * @param state - Thread state
+     * @param toolCall - The executed tool call
+     * @param toolResult - The successful result
+     * @returns Modified result or null for original
+     *
+     * @example
+     * ```typescript
+     * defineHook({
+     *   hook: 'after_tool_call_success',
+     *   id: 'log_success',
+     *   execute: async (state, toolCall, toolResult) => {
+     *     console.log(`Tool ${toolCall.function.name} succeeded`);
+     *     return null; // use original result
+     *   },
+     * });
+     * ```
+     */
+    after_tool_call_success: (state: State, toolCall: ToolCall, toolResult: ToolResult, context: Context) => Promise<ToolResult | null>;
+    /**
+     * Called after a failed tool call.
+     *
+     * Receives the tool call and error result. Can return a modified result
+     * or null to use the original. Use for error handling, logging, or
+     * recovery attempts.
+     *
+     * @param state - Thread state
+     * @param toolCall - The failed tool call
+     * @param toolResult - The error result
+     * @returns Modified result or null for original
+     *
+     * @example
+     * ```typescript
+     * defineHook({
+     *   hook: 'after_tool_call_failure',
+     *   id: 'log_failure',
+     *   execute: async (state, toolCall, toolResult) => {
+     *     console.error(`Tool ${toolCall.function.name} failed: ${toolResult.error}`);
+     *     return null; // use original error
+     *   },
+     * });
+     * ```
+     */
+    after_tool_call_failure: (state: State, toolCall: ToolCall, toolResult: ToolResult, context: Context) => Promise<ToolResult | null>;
+    /**
+     * Called when a tool call STARTS — before the tool executes, while the model
+     * may still be generating the rest of the call. Fires exactly once per tool
+     * call. Observational: the return value is ignored.
+     *
+     * Timing depends on whether the tool declares a `progressArgument`:
+     * - **With** `progressArgument`: fires as soon as *just that argument* has
+     *   finished streaming (not the whole call), passing its value as `progress`.
+     *   This lets a UI show "fixing index.html" before a large `content` argument
+     *   finishes generating.
+     * - **Without** `progressArgument`: fires as soon as the tool call appears in
+     *   the stream — its name is known but `toolCall.function.arguments` may be an
+     *   incomplete JSON fragment (or empty), and `progress` is undefined.
+     *
+     * Conforming runtimes also broadcast a `tool_call_started` thread event to
+     * connected clients with `{ id, name, progress }` at the same moment.
+     *
+     * @param state - Thread state
+     * @param toolCall - The starting tool call; `function.arguments` may be incomplete
+     * @param progress - The declared progress-argument value, when available
+     *
+     * @example
+     * ```typescript
+     * defineHook({
+     *   hook: 'tool_call_started',
+     *   id: 'log_tool_start',
+     *   execute: async (state, toolCall, progress) => {
+     *     console.log(`▸ ${toolCall.function.name}${progress ? `: ${progress}` : ''}`);
+     *   },
+     * });
+     * ```
+     */
+    tool_call_started: (state: State, toolCall: ToolCall, progress: string | undefined, context: Context) => Promise<void>;
+    /**
+     * Called when a tool call is DONE — after it has executed, with its result,
+     * regardless of success or failure. Fires once per tool call. Observational:
+     * the return value is ignored.
+     *
+     * This complements `after_tool_call_success` / `after_tool_call_failure`,
+     * which can additionally *modify* the stored result; `tool_call_done` is a
+     * single unified observation point that always fires. Conforming runtimes
+     * also broadcast a `tool_call_done` thread event to connected clients with
+     * `{ id, name, status }` at the same moment.
+     *
+     * @param state - Thread state
+     * @param toolCall - The completed tool call
+     * @param toolResult - The tool's result (`status` is `'success'` or `'error'`)
+     */
+    tool_call_done: (state: State, toolCall: ToolCall, toolResult: ToolResult, context: Context) => Promise<void>;
+    /**
+     * Called when a socket attaches to the user's event stream
+     * (`{runtime_prefix}/users/me/stream`).
+     *
+     * @param user - User scope state
+     * @param client - The attached client's id and self-declared kind
+     */
+    user_client_attached: (user: UserState, client: UserClientInfo) => Promise<void>;
+    /**
+     * Called when a socket detaches from the user's event stream.
+     *
+     * @param user - User scope state
+     * @param client - The detached client's id and self-declared kind
+     */
+    user_client_detached: (user: UserState, client: UserClientInfo) => Promise<void>;
+    /**
+     * Called after a durable user value changes, regardless of the writer
+     * (user endpoint, thread-side handle, or REST).
+     *
+     * @param user - User scope state
+     * @param key - The key that changed
+     */
+    user_value_changed: (user: UserState, key: string) => Promise<void>;
 }
 /**
- * Packed namespace context - for code inside a packed agent.
- *
- * Packed code sees:
- * - Only items within its own package (by packageId)
- * - Other packed agent entry points (for handoffs)
- * - NOT unpacked global code
+ * Valid hook names.
  */
-interface PackedNamespaceContext {
-    type: 'packed';
-    /** Package ID this code belongs to */
-    packageId: string;
-}
+type HookName = keyof HookSignatures;
+/** Hook names that execute in thread scope and may be contributed to a parent. */
+type ThreadHookName = Exclude<HookName, 'user_client_attached' | 'user_client_detached' | 'user_value_changed'>;
 /**
- * Namespace context for execution.
- * Determines what items are visible during execution.
+ * Hook definition tuple.
  *
- * @example
- * ```typescript
- * // Global namespace (unpacked code)
- * const globalNs: NamespaceContext = { type: 'global' };
+ * A hook definition is a tuple containing the hook name and implementation.
  *
- * // Packed namespace (inside a packed agent)
- * const packedNs: NamespaceContext = {
- *   type: 'packed',
- *   packageId: 'standardagent-my-workflow',
- * };
- * ```
+ * @template K - The hook name
+ * @template State - The state type (defaults to ThreadState)
+ * @template Msg - The message type
+ * @template ToolCall - The tool call type
+ * @template ToolResult - The tool result type
+ * @deprecated Use the object-based defineHook signature instead
  */
-type NamespaceContext = GlobalNamespaceContext | PackedNamespaceContext;
+type HookDefinition<K extends HookName = HookName, State = ThreadState, Msg = HookMessage, ToolCall = HookToolCall, ToolResult = HookToolResult> = [K, HookSignatures<State, Msg, ToolCall, ToolResult>[K]];
 /**
- * Extended metadata for packed definitions.
+ * Options for defining a hook with explicit ID.
+ * The generic K ensures `execute` is properly typed for the specific hook type.
  *
- * This interface is added to agent, prompt, tool, model, and hook
- * definitions when they are packed. It marks them as belonging
- * to a specific package and optionally as readonly.
+ * @template K - Hook type from HookSignatures (e.g., 'filter_messages')
  */
-interface PackedMetadata {
-    /**
-     * Package signature if this definition is part of a packed agent.
-     * Undefined for unpacked (global) definitions.
-     */
-    __package?: PackageSignature;
+interface HookDefinitionOptions<K extends HookName> {
+    /** The hook type (e.g., 'filter_messages', 'before_create_message') */
+    hook: K;
+    /** Unique identifier for this hook implementation (snake_case) */
+    id: string;
     /**
-     * Whether this definition is readonly (cannot be edited in UI).
-     * Packed definitions are typically readonly.
+     * The hook implementation function.
+     * Type is automatically inferred from the hook type.
      */
-    __readonly?: boolean;
+    execute: HookSignatures<ThreadState, HookMessage, HookToolCall, HookToolResult>[K];
 }
 /**
- * Helper type to check if a definition is packed.
- */
-declare function isPacked(metadata: PackedMetadata | undefined): metadata is PackedMetadata & {
-    __package: PackageSignature;
-};
-/**
- * Helper to check if a definition belongs to a specific package.
- */
-declare function belongsToPackage(metadata: PackedMetadata | undefined, packageId: string): boolean;
-/**
- * Helper to check if a definition is visible in a given namespace.
+ * Return type from defineHook - preserves the hook type for type-safe usage.
  *
- * @param metadata - The definition's packed metadata
- * @param namespace - The current namespace context
- * @param isEntryPoint - Whether this is an agent with exposeAsTool: true
+ * @template K - Hook type from HookSignatures
  */
-declare function isVisibleInNamespace(metadata: PackedMetadata | undefined, namespace: NamespaceContext, isEntryPoint?: boolean): boolean;
+interface HookDefinitionResult<K extends HookName> {
+    /** The hook type name */
+    hook: K;
+    /** The unique hook ID */
+    id: string;
+    /** The typed execute function */
+    execute: HookSignatures<ThreadState, HookMessage, HookToolCall, HookToolResult>[K];
+}
 /**
- * Metadata export for packed packages.
+ * Define a hook with a unique identifier and strict typing.
  *
- * This is exported as `__meta` from the packed package's index.ts,
- * replacing the manifest.json file from the old format.
+ * The hook type determines the execute function signature.
+ * TypeScript will enforce correct parameter and return types.
  *
- * A packed package's required execution behavior must use capabilities
- * defined by the Standard Agent Specification. It must not depend on private
- * runtime RPCs, storage schemas, bindings, undocumented events, sidecars that
- * replace runtime primitives, or `ThreadState._notPackableRuntimeContext`.
+ * @template K - The hook type (inferred from options.hook)
+ * @param options - Hook definition with hook type, ID, and execute function
+ * @returns Typed hook definition for registration
  *
  * @example
  * ```typescript
- * export const __meta: PackedMeta = {
- *   packageId: 'standardagent-my-workflow',
- *   version: '1.0.0',
- *   entryAgents: ['my_agent'],
- *   packedAt: 1705012800000,
- * };
+ * // Filter messages - execute receives (state: ThreadState, messages: HookMessage[])
+ * export default defineHook({
+ *   hook: 'filter_messages',
+ *   id: 'limit_to_20_messages',
+ *   execute: async (state, messages) => {
+ *     return messages.slice(-20);
+ *   }
+ * });
  * ```
- */
-interface PackedMeta {
-    /** Unique package identifier (npm name or local identifier) */
-    packageId: string;
-    /** Package version (semver) */
-    version: string;
-    /** Entry agents exposed as tools (visible from outside the package) */
-    entryAgents: string[];
-    /** When the package was packed (timestamp in milliseconds) */
-    packedAt: number;
-    /** Optional description from the entry agent */
-    description?: string;
-}
-/**
- * Lazy loader type for packed definitions.
- *
- * Each definition in a packed package is wrapped in a function
- * that returns a Promise, enabling lazy loading.
  *
  * @example
  * ```typescript
- * export const tools = {
- *   search: async (): Promise<ToolDefinition> => ({
- *     description: 'Search for information',
- *     execute: async (state, args) => { ... },
- *   }),
- * } as const;
+ * // Before create message - execute receives (state: ThreadState, message: Message)
+ * export default defineHook({
+ *   hook: 'before_create_message',
+ *   id: 'prefix_content',
+ *   execute: async (state, message) => {
+ *     if (message.role === 'user' && message.content) {
+ *       return { ...message, content: `[user] ${message.content}` };
+ *     }
+ *     return message;
+ *   }
+ * });
  * ```
- */
-type DefinitionLoader<T> = () => Promise<T>;
-
-/**
- * Standard shape for packed package exports.
- *
- * Every packed package exports this structure, enabling
- * consistent discovery and loading.
  *
  * @example
  * ```typescript
- * import type { PackedExports } from '@standardagents/spec';
- *
- * const pkg: PackedExports = await import('standardagent-my-workflow');
- * const tool = await pkg.tools.search();
+ * // After tool call success - execute receives (state, toolCall, toolResult)
+ * export default defineHook({
+ *   hook: 'after_tool_call_success',
+ *   id: 'log_tool_usage',
+ *   execute: async (state, toolCall, toolResult) => {
+ *     console.log(`Tool ${toolCall.function.name} returned: ${toolResult.result}`);
+ *     return null; // Use original result
+ *   }
+ * });
  * ```
  */
-interface PackedExports {
-    /** Agent definitions, keyed by name */
-    agents: Record<string, DefinitionLoader<AgentDefinition>>;
-    /** Prompt definitions, keyed by name */
-    prompts: Record<string, DefinitionLoader<PromptDefinition>>;
-    /** Tool definitions, keyed by name */
-    tools: Record<string, DefinitionLoader<ToolDefinition<unknown, any, any>>>;
-    /** Model definitions, keyed by name */
-    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 mount these beneath the same thread ID prefix as local thread
-     * endpoints, using the packed route key to derive the endpoint path.
-     * Requests beneath that prefix that do not match any local or packed thread
-     * endpoint route MUST return HTTP 404.
-     *
-     * Optional for backward compatibility with previously packed packages.
-     */
-    threadEndpoints?: Record<string, DefinitionLoader<MarkedThreadEndpoint | Controller>>;
-    /** Package metadata */
-    __meta: PackedMeta;
-}
+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 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 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 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 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 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 };
+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 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 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 };