@standardagents/spec 0.11.12 → 0.12.0

package/dist/index.d.ts

@@ -53,6 +53,13 @@ declare global {
          */
         interface CallableRegistry {
         }
+        /**
+         * Registry of hook IDs from agents/hooks/.
+         * Generated types add properties: interface HookIdRegistry { 'limit_messages': true; }
+         * This gives us: type HookIds = keyof HookIdRegistry = 'limit_messages'
+         */
+        interface HookIdRegistry {
+        }
         /**
          * Registry mapping prompt/agent names to their requiredSchema field names.
          * For agents, this maps to the side_a prompt's requiredSchema fields.
@@ -95,6 +102,11 @@ declare global {
          * Callables include prompts, agents, and tools that can be used as tools.
          */
         type Callables = keyof CallableRegistry extends never ? string : keyof CallableRegistry;
+        /**
+         * Union of all hook IDs, or string when registry is empty.
+         * Hook IDs are the unique identifiers defined in agents/hooks/ files.
+         */
+        type HookIds = keyof HookIdRegistry extends never ? string : keyof HookIdRegistry;
     }
 }
 
@@ -969,20 +981,83 @@ type ToolTenvs<D extends number = 7> = z.ZodObject<TenvRawShape<D>>;
  * @template Args - The Zod schema for tool arguments, or null for no args
  */
 type Tool<State = ThreadState, Args extends ToolArgs | null = null> = Args extends ToolArgs ? (state: State, args: z.infer<Args>) => Promise<ToolResult> : (state: State) => Promise<ToolResult>;
+/**
+ * Helper type to check if Uses is a non-empty const array.
+ * Returns true only if Uses has literal string elements (from `as const`).
+ */
+type IsConstArray<Uses extends readonly string[]> = string extends Uses[number] ? false : true;
+/**
+ * Helper type to check if Uses array is empty.
+ */
+type IsEmptyArray<Uses extends readonly string[]> = Uses extends readonly [] ? true : false;
+/**
+ * A ThreadState with queueTool and invokeTool constrained to specific tool names.
+ *
+ * When a tool declares `uses: ['a', 'b'] as const`, the state passed to execute
+ * will only allow calling those specific tools.
+ *
+ * @template Uses - Readonly array of allowed tool names
+ */
+type UsesConstrainedState<Uses extends readonly string[]> = Omit<ThreadState, 'queueTool' | 'invokeTool'> & {
+    /**
+     * Queue a tool for execution.
+     *
+     * Constrained to only tools declared in `uses` array.
+     *
+     * @param toolName - Name of the tool to invoke (must be in uses array)
+     * @param args - Arguments to pass to the tool
+     */
+    queueTool(toolName: Uses[number], args?: Record<string, unknown>): void;
+    /**
+     * Invoke a tool directly and wait for the result.
+     *
+     * Constrained to only tools declared in `uses` array.
+     *
+     * @param toolName - Name of the tool to invoke (must be in uses array)
+     * @param args - Arguments to pass to the tool
+     * @returns The tool result
+     */
+    invokeTool(toolName: Uses[number], args?: Record<string, unknown>): Promise<ToolResult>;
+};
+/**
+ * A ThreadState where queueTool and invokeTool cannot be called (empty uses).
+ */
+type EmptyUsesState = Omit<ThreadState, 'queueTool' | 'invokeTool'>;
+/**
+ * Determines the correct state type based on the Uses array.
+ *
+ * - Empty `uses: [] as const` → EmptyUsesState (no queueTool/invokeTool)
+ * - Const `uses: ['a', 'b'] as const` → UsesConstrainedState (constrained methods)
+ * - Non-const `uses: ['a']` or no uses → ThreadState (unconstrained, backward compatible)
+ */
+type ResolveUsesState<Uses extends readonly string[]> = IsEmptyArray<Uses> extends true ? EmptyUsesState : IsConstArray<Uses> extends true ? UsesConstrainedState<Uses> : ThreadState;
+/**
+ * Tool execute function with uses-aware state.
+ *
+ * When `uses` is declared with `as const`, the state's queueTool and invokeTool
+ * are constrained to only the declared tools. When `uses` is not declared or
+ * is a regular string[], any tool name is allowed (backward compatible).
+ *
+ * @template State - Base state type
+ * @template Args - Tool arguments schema
+ * @template Uses - Readonly array of allowed tool names
+ */
+type UsesAwareExecute<State, Args extends ToolArgs | null, Uses extends readonly string[]> = Args extends ToolArgs ? (state: ResolveUsesState<Uses>, args: z.infer<Args>) => Promise<ToolResult> : (state: ResolveUsesState<Uses>) => Promise<ToolResult>;
 /**
  * Options for defining a tool.
  *
  * @template State - The state type (defaults to ThreadState)
  * @template Args - The Zod schema for tool arguments, or null for no args
  * @template Tenvs - The Zod schema for thread environment variables, or null
+ * @template Uses - Readonly array of tool names this tool can invoke
  */
-interface DefineToolOptions<State = ThreadState, Args extends ToolArgs | null = null, Tenvs extends ToolTenvs | null = null> {
+interface DefineToolOptions<State = ThreadState, Args extends ToolArgs | null = null, Tenvs extends ToolTenvs | null = null, Uses extends readonly string[] = readonly string[]> {
     /** Description of what the tool does (shown to the LLM). */
     description: string;
     /** Zod schema for validating tool arguments. Omit for tools with no args. */
     args?: Args;
     /** The tool implementation function. */
-    execute: Tool<State, Args>;
+    execute: UsesAwareExecute<State, Args, Uses>;
     /** Zod schema for thread environment variables the tool requires. */
     tenvs?: Tenvs;
     /**
@@ -996,6 +1071,42 @@ interface DefineToolOptions<State = ThreadState, Args extends ToolArgs | null =
      * e.g., 'openai', 'anthropic'
      */
     executionProvider?: string;
+    /**
+     * Explicit list of tools, prompts, or agents this tool can call.
+     *
+     * When specified with `as const`, the tool's execute function's state
+     * will have queueTool() and invokeTool() constrained to only the
+     * declared tools (compile-time type safety).
+     *
+     * At runtime, attempts to call unlisted items will throw an error.
+     *
+     * This is required for packed tools to ensure namespace isolation.
+     * For unpacked tools, it's optional but recommended for clarity.
+     *
+     * @example
+     * ```typescript
+     * // Type-safe: only 'validate_input' and 'format_output' allowed
+     * defineTool({
+     *   description: 'Process data using helper tools',
+     *   uses: ['validate_input', 'format_output'] as const,
+     *   execute: async (state) => {
+     *     state.queueTool('validate_input', { data: '...' }); // ✓ OK
+     *     state.queueTool('unknown_tool', {}); // ✗ TypeScript error
+     *     // ...
+     *   },
+     * });
+     *
+     * // Without `as const`, any tool name is allowed (backward compatible)
+     * defineTool({
+     *   description: 'Flexible tool',
+     *   uses: ['some_tool'],
+     *   execute: async (state) => {
+     *     state.queueTool('any_tool', {}); // ✓ OK (no type constraint)
+     *   },
+     * });
+     * ```
+     */
+    uses?: Uses;
 }
 /**
  * Tool definition object returned by defineTool().
@@ -1006,14 +1117,15 @@ interface DefineToolOptions<State = ThreadState, Args extends ToolArgs | null =
  * @template State - The state type (defaults to ThreadState)
  * @template Args - The Zod schema for tool arguments, or null for no args
  * @template Tenvs - The Zod schema for thread environment variables, or null
+ * @template Uses - Readonly array of tool names this tool can invoke
  */
-interface ToolDefinition<State = ThreadState, Args extends ToolArgs | null = null, Tenvs extends ToolTenvs | null = null> {
+interface ToolDefinition<State = ThreadState, Args extends ToolArgs | null = null, Tenvs extends ToolTenvs | null = null, Uses extends readonly string[] = readonly string[]> {
     /** Description of what the tool does (shown to the LLM). */
     description: string;
     /** Zod schema for validating tool arguments, or null for no args. */
     args: Args;
     /** The tool implementation function. */
-    execute: Tool<State, Args>;
+    execute: UsesAwareExecute<State, Args, Uses>;
     /** Zod schema for thread environment variables, or null if none. */
     tenvs: Tenvs;
     /**
@@ -1026,6 +1138,21 @@ interface ToolDefinition<State = ThreadState, Args extends ToolArgs | null = nul
      * Which provider executes this tool (when executionMode='provider').
      */
     executionProvider?: string;
+    /**
+     * Explicit list of tools, prompts, or agents this tool can call.
+     *
+     * When specified with `as const`, TypeScript constrains queueTool()
+     * and invokeTool() at compile time. At runtime, attempts to call
+     * unlisted items throw an error.
+     *
+     * This is required for packed tools to ensure namespace isolation.
+     * For unpacked tools, it's optional but recommended for clarity.
+     *
+     * Items can be:
+     * - Simple names: Resolve within current namespace
+     * - Qualified names (e.g., 'other_pkg:agent'): Cross-package entry point
+     */
+    uses?: Uses;
 }
 /**
  * Defines a tool that agents can call during execution.
@@ -1084,7 +1211,13 @@ interface ToolDefinition<State = ThreadState, Args extends ToolArgs | null = nul
  * @param options - Tool definition options
  * @returns A tool definition object
  */
-declare function defineTool<State = ThreadState, Args extends ToolArgs | null = null, Tenvs extends ToolTenvs | null = null>(options: DefineToolOptions<State, Args, Tenvs>): ToolDefinition<State, Args, Tenvs>;
+/**
+ * Validate a tool name does not contain reserved characters.
+ * Tools are typically defined without a name field (they get the filename),
+ * but this can be called by build tools that assign names.
+ */
+declare function validateToolName(name: string): void;
+declare function defineTool<State = ThreadState, Args extends ToolArgs | null = null, Tenvs extends ToolTenvs | null = null, Uses extends readonly string[] = readonly string[]>(options: DefineToolOptions<State, Args, Tenvs, Uses>): ToolDefinition<State, Args, Tenvs, Uses>;
 
 /**
  * Provider types for Standard Agents.
@@ -2211,6 +2344,17 @@ interface PromptDefinition<N extends string = string, S extends ToolArgs = ToolA
      * ```
      */
     providerOptions?: Record<string, unknown>;
+    /**
+     * Hook IDs to run when this prompt is active.
+     * References hooks by their unique `id` property from defineHook().
+     * If not specified, falls back to agent-level hooks.
+     *
+     * @example
+     * ```typescript
+     * hooks: ['limit_to_20_messages', 'log_tool_calls']
+     * ```
+     */
+    hooks?: StandardAgentSpec.HookIds[];
 }
 /**
  * Helper type to extract the inferred input type from a prompt's Zod schema.
@@ -2316,21 +2460,37 @@ interface HookToolResult {
     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 */
-    content: string | null;
+    /** 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.
@@ -2388,22 +2548,29 @@ interface HookSignatures<State = ThreadState, Msg = HookMessage, ToolCall = Hook
     /**
      * Called before a message is created in the database.
      *
-     * Receives the message data before insertion. Return modified data
-     * to transform the message before storage.
+     * Receives the full message object before insertion. Return modified
+     * message to transform before storage.
      *
      * @param state - Thread state
-     * @param message - Message data to be created
-     * @returns Modified message data
+     * @param message - Message to be created
+     * @returns Modified message
      *
      * @example
      * ```typescript
-     * defineHook('before_create_message', async (state, message) => {
-     *   // Add metadata to all messages
-     *   return { ...message, metadata: { processed: true } };
+     * 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: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    before_create_message: (state: State, message: Msg) => Promise<Msg>;
     /**
      * Called after a message is created in the database.
      *
@@ -2411,16 +2578,20 @@ interface HookSignatures<State = ThreadState, Msg = HookMessage, ToolCall = Hook
      * message creation. Cannot modify the message.
      *
      * @param state - Thread state
-     * @param message - The created message data
+     * @param message - The created message
      *
      * @example
      * ```typescript
-     * defineHook('after_create_message', async (state, message) => {
-     *   console.log(`Message created: ${message.id}`);
+     * 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: Record<string, unknown>) => Promise<void>;
+    after_create_message: (state: State, message: Msg) => Promise<void>;
     /**
      * Called before a message is updated in the database.
      *
@@ -2466,17 +2637,25 @@ interface HookSignatures<State = ThreadState, Msg = HookMessage, ToolCall = Hook
      * @param state - Thread state
      * @param toolCall - The tool call that was executed
      * @param toolResult - The result from tool execution
-     * @returns Modified tool result data
+     * @returns Modified tool result
      *
      * @example
      * ```typescript
-     * defineHook('before_store_tool_result', async (state, toolCall, toolResult) => {
-     *   // Sanitize sensitive data from results
-     *   return { ...toolResult, result: sanitize(toolResult.result) };
+     * 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: Record<string, unknown>, toolResult: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    before_store_tool_result: (state: State, toolCall: ToolCall, toolResult: ToolResult) => Promise<ToolResult>;
     /**
      * Called after a successful tool call.
      *
@@ -2534,51 +2713,90 @@ type HookName = keyof HookSignatures;
  * @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]];
 /**
- * Define a hook with strict typing based on hook name.
+ * Options for defining a hook with explicit ID.
+ * The generic K ensures `execute` is properly typed for the specific hook type.
  *
- * Hooks intercept specific points in the agent execution lifecycle.
- * The hook name determines the function signature and when it's called.
- * All hooks receive ThreadState as their first parameter.
+ * @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];
+}
+/**
+ * Define a hook with a unique identifier and strict typing.
  *
- * @template K - The hook name (determines signature)
- * @param hookName - Name of the hook to define
- * @param implementation - Hook implementation function
- * @returns The implementation function (for registration)
+ * The hook type determines the execute function signature.
+ * TypeScript will enforce correct parameter and return types.
+ *
+ * @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
- * // Filter messages to last 10
- * export default defineHook('filter_messages', async (state, messages) => {
- *   return messages.slice(-10);
+ * // 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);
+ *   }
  * });
  * ```
  *
  * @example
  * ```typescript
- * // Log all tool successes
- * export default defineHook('after_tool_call_success', async (state, toolCall, result) => {
- *   console.log(`Tool ${toolCall.function.name} completed`);
- *   return null; // Use original result
+ * // 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;
+ *   }
  * });
  * ```
  *
  * @example
  * ```typescript
- * // Transform messages before LLM
- * export default defineHook('prefilter_llm_history', async (state, messages) => {
- *   // Add instruction to last message
- *   const last = messages[messages.length - 1];
- *   if (last?.role === 'user' && typeof last.content === 'string') {
- *     last.content += '\n\nRemember to be concise.';
+ * // 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
  *   }
- *   return messages;
  * });
  * ```
  */
-declare function defineHook<K extends keyof HookSignatures>(hookName: K, implementation: HookSignatures[K]): HookSignatures[K];
+declare function defineHook<K extends HookName>(options: HookDefinitionOptions<K>): HookDefinitionResult<K>;
 
 /**
  * Agent definition types for Standard Agents.
@@ -2768,6 +2986,47 @@ interface AgentDefinition<N extends string = string, Prompt extends string = Sta
      * ```
      */
     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[];
 }
 /**
  * Defines an agent configuration.
@@ -3033,4 +3292,193 @@ declare function defineController(controller: Controller): Controller;
  */
 declare function defineThreadEndpoint(handler: ThreadEndpointHandler): MarkedThreadEndpoint;
 
-export { type AgentDefinition, type AgentType, type AttachmentRef, type ContentPart, type Controller, type ControllerContext, type ControllerReturn, type DefineToolOptions, type Effect, type EffectDefinition, type ExecutionState, type FileChunk, type FilePart, type FileRecord, type FileStats, type FileStorage, type FindResult, type GetMessagesOptions, type GrepResult, type HookContext, type HookDefinition, type HookMessage, type HookName, type HookSignatures, type HookToolCall, type HookToolResult, type ImageContent, type ImagePart, type ImageUrlPart, type InferProviderOptions, type InjectMessageInput, type InspectedRequest, type LLMMessage, type LLMProviderInterface, type MarkedThreadEndpoint, type Message, type MessageUpdates, type MessagesResult, type ModelCapabilities, type ModelDefinition, type ModelProvider, type PromptContent, type PromptDefinition, type PromptIncludePart, type PromptInput, type PromptPart, type PromptTextPart, type PromptToolConfig, type ProviderAssistantMessage, type ProviderAttachment, ProviderError, type ProviderErrorCode, type ProviderFactory, type ProviderFactoryConfig, type ProviderFactoryWithOptions, type ProviderFinishReason, type ProviderGeneratedImage, type ProviderInstance, type ProviderMessage, type ProviderMessageContent, type ProviderModelInfo, type ProviderReasoningDetail, type ProviderRequest, type ProviderResponse, type ProviderStreamChunk, type ProviderSystemMessage, type ProviderTool, type ProviderToolCallPart, type ProviderToolMessage, type ProviderToolResultContent, type ProviderUsage, type ProviderUserMessage, type ProviderWebSearchResult, type ReadFileStreamOptions, type ReaddirResult, type ReasoningConfig, type ResponseSummary, type ScheduledEffect, type SideConfig, type StructuredPrompt, type SubpromptConfig, THREAD_ENDPOINT_SYMBOL, type TenvRawShape, type TextContent, type TextPart, type ThreadEndpointHandler, type ThreadMetadata, type ThreadState, type Tool, type ToolArgs, type ToolArgsNode, type ToolArgsRawShape, type ToolAttachment, type ToolConfig, type ToolContent, type ToolDefinition, type ToolResult, type ToolTenvs, type VirtualModuleLoader, type VirtualModuleRegistry, type WriteFileOptions, defineAgent, defineController, defineEffect, defineHook, defineModel, definePrompt, defineThreadEndpoint, defineTool, isThreadEndpoint, mapReasoningLevel };
+/**
+ * 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.
+ *
+ * @module
+ */
+/**
+ * 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(),
+ * };
+ * ```
+ */
+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;
+}
+/**
+ * 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)
+ */
+interface GlobalNamespaceContext {
+    type: 'global';
+}
+/**
+ * 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
+ */
+interface PackedNamespaceContext {
+    type: 'packed';
+    /** Package ID this code belongs to */
+    packageId: string;
+}
+/**
+ * Namespace context for execution.
+ * Determines what items are visible during execution.
+ *
+ * @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 NamespaceContext = GlobalNamespaceContext | PackedNamespaceContext;
+/**
+ * Extended metadata for packed definitions.
+ *
+ * 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 PackedMetadata {
+    /**
+     * Package signature if this definition is part of a packed agent.
+     * Undefined for unpacked (global) definitions.
+     */
+    __package?: PackageSignature;
+    /**
+     * Whether this definition is readonly (cannot be edited in UI).
+     * Packed definitions are typically readonly.
+     */
+    __readonly?: boolean;
+}
+/**
+ * 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.
+ *
+ * @param metadata - The definition's packed metadata
+ * @param namespace - The current namespace context
+ * @param isEntryPoint - Whether this is an agent with exposeAsTool: true
+ */
+declare function isVisibleInNamespace(metadata: PackedMetadata | undefined, namespace: NamespaceContext, isEntryPoint?: boolean): boolean;
+/**
+ * Metadata export for packed packages.
+ *
+ * This is exported as `__meta` from the packed package's index.ts,
+ * replacing the manifest.json file from the old format.
+ *
+ * @example
+ * ```typescript
+ * export const __meta: PackedMeta = {
+ *   packageId: 'standardagent-my-workflow',
+ *   version: '1.0.0',
+ *   entryAgents: ['my_agent'],
+ *   packedAt: 1705012800000,
+ * };
+ * ```
+ */
+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;
+ * ```
+ */
+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();
+ * ```
+ */
+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]>>;
+    /** Package metadata */
+    __meta: PackedMeta;
+}
+
+export { type AgentDefinition, type AgentType, type AttachmentRef, type ContentPart, type Controller, type ControllerContext, type ControllerReturn, type DefineToolOptions, type DefinitionLoader, type Effect, type EffectDefinition, type EmptyUsesState, type ExecutionState, type FileChunk, type FilePart, type FileRecord, type FileStats, type FileStorage, type FindResult, type GetMessagesOptions, type GlobalNamespaceContext, type GrepResult, type HookContext, type HookDefinition, type HookDefinitionOptions, type HookDefinitionResult, type HookMessage, type HookName, type HookSignatures, type HookToolCall, type HookToolResult, type ImageContent, type ImagePart, type ImageUrlPart, type InferProviderOptions, type InjectMessageInput, type InspectedRequest, type LLMMessage, type LLMProviderInterface, type MarkedThreadEndpoint, type Message, type MessageUpdates, type MessagesResult, type ModelCapabilities, type ModelDefinition, type ModelProvider, type NamespaceContext, type PackageSignature, type PackedExports, type PackedMeta, type PackedMetadata, type PackedNamespaceContext, type PromptContent, type PromptDefinition, type PromptIncludePart, type PromptInput, type PromptPart, type PromptTextPart, type PromptToolConfig, type ProviderAssistantMessage, type ProviderAttachment, ProviderError, type ProviderErrorCode, type ProviderFactory, type ProviderFactoryConfig, type ProviderFactoryWithOptions, type ProviderFinishReason, type ProviderGeneratedImage, type ProviderInstance, type ProviderMessage, type ProviderMessageContent, type ProviderModelInfo, type ProviderReasoningDetail, type ProviderRequest, type ProviderResponse, type ProviderStreamChunk, type ProviderSystemMessage, type ProviderTool, type ProviderToolCallPart, type ProviderToolMessage, type ProviderToolResultContent, type ProviderUsage, type ProviderUserMessage, type ProviderWebSearchResult, type ReadFileStreamOptions, type ReaddirResult, type ReasoningConfig, type ResolveUsesState, type ResponseSummary, type ScheduledEffect, type SideConfig, type StructuredPrompt, type SubpromptConfig, THREAD_ENDPOINT_SYMBOL, type TenvRawShape, type TextContent, type TextPart, type ThreadEndpointHandler, type ThreadMetadata, type ThreadState, type Tool, type ToolArgs, type ToolArgsNode, type ToolArgsRawShape, type ToolAttachment, type ToolConfig, type ToolContent, type ToolDefinition, type ToolResult, type ToolTenvs, type UsesAwareExecute, type UsesConstrainedState, type VirtualModuleLoader, type VirtualModuleRegistry, type WriteFileOptions, belongsToPackage, defineAgent, defineController, defineEffect, defineHook, defineModel, definePrompt, defineThreadEndpoint, defineTool, isPacked, isThreadEndpoint, isVisibleInNamespace, mapReasoningLevel, validateToolName };