llmist 9.1.1 → 9.2.0

package/dist/index.d.ts

@@ -7739,14 +7739,30 @@ declare class GadgetCallParser {
 }
 
 /**
- * Helper functions for gadget authors to easily return media outputs.
+ * Helper functions for gadget authors.
  *
- * These functions provide type-specific conveniences while using the
- * generic GadgetMediaOutput system underneath.
+ * This module provides:
+ * 1. Response formatting helpers (gadgetSuccess, gadgetError, withErrorHandling)
+ * 2. Media output helpers (resultWithImage, resultWithAudio, etc.)
  *
- * @example
+ * @example Response helpers
+ * ```typescript
+ * import { gadgetSuccess, gadgetError, withErrorHandling } from "llmist";
+ *
+ * // Simple response formatting
+ * return gadgetSuccess({ url: "https://example.com", title: "Example" });
+ * return gadgetError("Element not found", { selector: ".missing" });
+ *
+ * // Automatic error handling wrapper
+ * const safeExecute = withErrorHandling(async (params) => {
+ *   // your code here - errors are automatically caught and formatted
+ *   return gadgetSuccess({ result: "done" });
+ * });
+ * ```
+ *
+ * @example Media output helpers
  * ```typescript
- * import { resultWithImage } from "llmist/gadgets";
+ * import { resultWithImage } from "llmist";
  *
  * const screenshotGadget = createGadget({
  *   name: "Screenshot",
@@ -7763,6 +7779,72 @@ declare class GadgetCallParser {
  * ```
  */
 
+/**
+ * Create a success response as JSON string.
+ *
+ * This is a convenience helper for gadgets that return JSON-formatted responses.
+ * It automatically adds `success: true` and stringifies the result.
+ *
+ * @param data - Additional data to include in the response
+ * @returns JSON string with success: true and provided data
+ *
+ * @example
+ * ```typescript
+ * return gadgetSuccess({ url: page.url(), title: await page.title() });
+ * // Returns: '{"success":true,"url":"...","title":"..."}'
+ * ```
+ */
+declare function gadgetSuccess(data?: Record<string, unknown>): string;
+/**
+ * Create an error response as JSON string.
+ *
+ * This is a convenience helper for gadgets that return JSON-formatted errors.
+ * It stringifies the error message and any additional details.
+ *
+ * @param message - Error message
+ * @param details - Additional error details (e.g., suggestions, context)
+ * @returns JSON string with error message and details
+ *
+ * @example
+ * ```typescript
+ * return gadgetError("Element not found", { selector: ".missing", suggestions: ["Try #id instead"] });
+ * // Returns: '{"error":"Element not found","selector":".missing","suggestions":[...]}'
+ * ```
+ */
+declare function gadgetError(message: string, details?: Record<string, unknown>): string;
+/**
+ * Safely extract error message from unknown error type.
+ *
+ * Handles both Error instances and other thrown values.
+ *
+ * @param error - Unknown error value
+ * @returns String error message
+ */
+declare function getErrorMessage(error: unknown): string;
+/**
+ * Wrap a gadget execute function with automatic error handling.
+ *
+ * This higher-order function catches any errors thrown during execution
+ * and converts them to properly formatted error responses.
+ *
+ * @param execute - The execute function to wrap
+ * @returns A wrapped function that catches errors and returns gadgetError responses
+ *
+ * @example
+ * ```typescript
+ * const safeExecute = withErrorHandling(async (params: MyParams) => {
+ *   // Your code here - if it throws, error is caught and formatted
+ *   const result = await riskyOperation(params.id);
+ *   return gadgetSuccess({ result });
+ * });
+ *
+ * // In gadget:
+ * execute(params) {
+ *   return safeExecute(params);
+ * }
+ * ```
+ */
+declare function withErrorHandling<TParams>(execute: (params: TParams, ctx?: ExecutionContext) => Promise<string> | string): (params: TParams, ctx?: ExecutionContext) => Promise<string>;
 /**
  * Create a GadgetMediaOutput from raw data.
  *
@@ -8534,6 +8616,793 @@ declare class OpenAIChatProvider extends BaseProviderAdapter {
 }
 declare function createOpenAIProviderFromEnv(): OpenAIChatProvider | null;
 
+/**
+ * Formatting utilities for gadget authors and CLI output.
+ *
+ * Provides common formatting functions for:
+ * - Text truncation
+ * - Byte size formatting
+ * - Date formatting
+ * - Duration formatting
+ *
+ * @module utils/format
+ *
+ * @example
+ * ```typescript
+ * import { format } from "llmist";
+ *
+ * format.truncate("Long text...", 10);  // "Long tex..."
+ * format.bytes(1536);                    // "1.5 KB"
+ * format.date("2024-01-15T10:30:00Z");  // "Jan 15, 2024 10:30 AM"
+ * format.duration(125000);               // "2m 5s"
+ * ```
+ */
+/**
+ * Truncate text to a maximum length, adding suffix if truncated.
+ *
+ * @param text - Text to truncate
+ * @param maxLength - Maximum length including suffix
+ * @param suffix - Suffix to append when truncated (default: "...")
+ * @returns Truncated text
+ *
+ * @example
+ * ```typescript
+ * truncate("Hello, World!", 10);  // "Hello, ..."
+ * truncate("Short", 10);          // "Short"
+ * truncate("Custom", 6, "…");     // "Custo…"
+ * ```
+ */
+declare function truncate(text: string, maxLength: number, suffix?: string): string;
+/**
+ * Format bytes as human-readable string.
+ *
+ * @param bytes - Number of bytes
+ * @param decimals - Number of decimal places (default: 1)
+ * @returns Formatted string (e.g., "1.5 KB", "2.3 MB")
+ *
+ * @example
+ * ```typescript
+ * formatBytes(0);        // "0 B"
+ * formatBytes(1024);     // "1 KB"
+ * formatBytes(1536);     // "1.5 KB"
+ * formatBytes(1048576);  // "1 MB"
+ * ```
+ */
+declare function formatBytes(bytes: number, decimals?: number): string;
+/**
+ * Format ISO date string as human-readable date.
+ *
+ * @param isoDate - ISO date string (e.g., "2024-01-15T10:30:00Z")
+ * @param options - Intl.DateTimeFormat options
+ * @returns Formatted date string
+ *
+ * @example
+ * ```typescript
+ * formatDate("2024-01-15T10:30:00Z");
+ * // "Jan 15, 2024, 10:30 AM" (in local timezone)
+ *
+ * formatDate("2024-01-15T10:30:00Z", { dateStyle: "short" });
+ * // "1/15/24"
+ * ```
+ */
+declare function formatDate(isoDate: string, options?: Intl.DateTimeFormatOptions): string;
+/**
+ * Format duration in milliseconds as human-readable string.
+ *
+ * @param ms - Duration in milliseconds
+ * @param options - Formatting options
+ * @returns Formatted duration string
+ *
+ * @example
+ * ```typescript
+ * formatDuration(500);      // "500ms"
+ * formatDuration(1500);     // "1.5s"
+ * formatDuration(65000);    // "1m 5s"
+ * formatDuration(3725000);  // "1h 2m 5s"
+ * ```
+ */
+declare function formatDuration(ms: number, options?: {
+    compact?: boolean;
+}): string;
+/**
+ * Format namespace object for convenient access.
+ *
+ * @example
+ * ```typescript
+ * import { format } from "llmist";
+ *
+ * format.truncate("text", 5);
+ * format.bytes(1024);
+ * format.date("2024-01-15");
+ * format.duration(5000);
+ * ```
+ */
+declare const format: {
+    readonly truncate: typeof truncate;
+    readonly bytes: typeof formatBytes;
+    readonly date: typeof formatDate;
+    readonly duration: typeof formatDuration;
+};
+
+/**
+ * Timing utilities for gadget authors.
+ *
+ * Provides common timing functions for:
+ * - Random delays (human-like timing)
+ * - Timeout handling
+ * - Retry logic with backoff
+ *
+ * @module utils/timing
+ *
+ * @example
+ * ```typescript
+ * import { timing } from "llmist";
+ *
+ * // Human-like delays for browser automation
+ * await timing.humanDelay(50, 150);
+ *
+ * // Add timeout to async operations
+ * const result = await timing.withTimeout(
+ *   () => fetchData(),
+ *   5000,
+ *   signal
+ * );
+ *
+ * // Retry with exponential backoff
+ * const data = await timing.withRetry(
+ *   () => unreliableApi(),
+ *   { maxRetries: 3, delay: 1000, backoff: "exponential" }
+ * );
+ * ```
+ */
+/**
+ * Generate a random delay within a range.
+ *
+ * @param min - Minimum delay in milliseconds
+ * @param max - Maximum delay in milliseconds
+ * @returns Random integer between min and max (inclusive)
+ *
+ * @example
+ * ```typescript
+ * const delay = randomDelay(50, 150);  // e.g., 87
+ * ```
+ */
+declare function randomDelay(min: number, max: number): number;
+/**
+ * Sleep for a random duration (for human-like timing).
+ *
+ * Useful for browser automation to appear more human-like.
+ *
+ * @param min - Minimum delay in milliseconds (default: 50)
+ * @param max - Maximum delay in milliseconds (default: 150)
+ * @returns Promise that resolves after the random delay
+ *
+ * @example
+ * ```typescript
+ * // Default human-like delay (50-150ms)
+ * await humanDelay();
+ *
+ * // Custom range for slower actions
+ * await humanDelay(100, 300);
+ * ```
+ */
+declare function humanDelay(min?: number, max?: number): Promise<void>;
+/**
+ * Execute an async function with a timeout.
+ *
+ * @param fn - Async function to execute
+ * @param timeoutMs - Timeout in milliseconds
+ * @param signal - Optional AbortSignal for early cancellation
+ * @returns Promise that resolves with the function result or rejects on timeout
+ * @throws Error with "Operation timed out" message if timeout is exceeded
+ *
+ * @example
+ * ```typescript
+ * const result = await withTimeout(
+ *   () => fetch("https://api.example.com/data"),
+ *   5000
+ * );
+ *
+ * // With abort signal
+ * const controller = new AbortController();
+ * const result = await withTimeout(
+ *   () => longRunningTask(),
+ *   30000,
+ *   controller.signal
+ * );
+ * ```
+ */
+declare function withTimeout<T>(fn: () => Promise<T>, timeoutMs: number, signal?: AbortSignal): Promise<T>;
+/**
+ * Options for retry logic.
+ */
+interface RetryOptions {
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Initial delay between retries in milliseconds (default: 1000) */
+    delay?: number;
+    /** Backoff strategy: "linear" adds delay, "exponential" doubles it (default: "exponential") */
+    backoff?: "linear" | "exponential";
+    /** Maximum delay cap in milliseconds (default: 30000) */
+    maxDelay?: number;
+    /** Optional function to determine if error is retryable (default: all errors) */
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+    /** Optional callback on each retry attempt */
+    onRetry?: (error: unknown, attempt: number, delay: number) => void;
+}
+/**
+ * Execute an async function with retry logic.
+ *
+ * @param fn - Async function to execute
+ * @param options - Retry options
+ * @returns Promise that resolves with the function result or rejects after all retries exhausted
+ *
+ * @example
+ * ```typescript
+ * // Basic retry with defaults (3 retries, exponential backoff)
+ * const result = await withRetry(() => unreliableApi());
+ *
+ * // Custom retry configuration
+ * const result = await withRetry(
+ *   () => fetchWithErrors(),
+ *   {
+ *     maxRetries: 5,
+ *     delay: 500,
+ *     backoff: "exponential",
+ *     shouldRetry: (error) => error.status === 429 || error.status >= 500,
+ *     onRetry: (error, attempt, delay) => {
+ *       console.log(`Retry ${attempt} after ${delay}ms`);
+ *     }
+ *   }
+ * );
+ * ```
+ */
+declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+/**
+ * Timing namespace object for convenient access.
+ *
+ * @example
+ * ```typescript
+ * import { timing } from "llmist";
+ *
+ * await timing.humanDelay();
+ * const result = await timing.withTimeout(() => fetch(url), 5000);
+ * const data = await timing.withRetry(() => api.call(), { maxRetries: 3 });
+ * ```
+ */
+declare const timing: {
+    readonly randomDelay: typeof randomDelay;
+    readonly humanDelay: typeof humanDelay;
+    readonly withTimeout: typeof withTimeout;
+    readonly withRetry: typeof withRetry;
+};
+
+/**
+ * Session management interface and base class for gadget packages.
+ *
+ * Provides a standardized way to manage sessions (browser instances, API clients, etc.)
+ * across gadgets. This enables:
+ * - Consistent session lifecycle management
+ * - Per-agent session isolation
+ * - Automatic cleanup
+ *
+ * @module session/manager
+ *
+ * @example
+ * ```typescript
+ * import { BaseSessionManager, ISessionManager } from "llmist";
+ *
+ * // Extend for browser sessions
+ * class BrowserSessionManager extends BaseSessionManager<Page, BrowserConfig> {
+ *   async createSession(config?: BrowserConfig): Promise<string> {
+ *     const browser = await launchBrowser(config);
+ *     const page = await browser.newPage();
+ *     const id = this.generateId("p");
+ *     this.sessions.set(id, page);
+ *     return id;
+ *   }
+ *
+ *   async closeSession(id: string): Promise<void> {
+ *     const page = this.sessions.get(id);
+ *     if (page) {
+ *       await page.close();
+ *       this.sessions.delete(id);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Interface for session managers.
+ *
+ * Session managers track and manage external resources (browser pages, API connections, etc.)
+ * that need to be shared across multiple gadgets and properly cleaned up.
+ *
+ * @typeParam TSession - Type of session object (e.g., Page, APIClient)
+ * @typeParam TConfig - Configuration type for creating sessions
+ */
+interface ISessionManager<TSession = unknown, TConfig = unknown> {
+    /**
+     * Create a new session.
+     *
+     * @param config - Optional configuration for the session
+     * @returns Promise resolving to the session ID
+     */
+    createSession(config?: TConfig): Promise<string>;
+    /**
+     * Get a session by ID.
+     *
+     * @param id - Session ID
+     * @returns Session object or undefined if not found
+     */
+    getSession(id: string): TSession | undefined;
+    /**
+     * Get a session by ID, throwing if not found.
+     *
+     * @param id - Session ID
+     * @returns Session object
+     * @throws Error if session not found
+     */
+    requireSession(id: string): TSession;
+    /**
+     * Close and remove a session.
+     *
+     * @param id - Session ID to close
+     */
+    closeSession(id: string): Promise<void>;
+    /**
+     * Close all sessions.
+     */
+    closeAll(): Promise<void>;
+    /**
+     * List all active session IDs.
+     *
+     * @returns Array of session IDs
+     */
+    listSessions(): string[];
+    /**
+     * Check if a session exists.
+     *
+     * @param id - Session ID
+     * @returns True if session exists
+     */
+    hasSession(id: string): boolean;
+}
+/**
+ * Base implementation of session manager with common functionality.
+ *
+ * Extend this class to create domain-specific session managers.
+ * You only need to implement `createSession` and `closeSession`.
+ *
+ * @typeParam TSession - Type of session object
+ * @typeParam TConfig - Configuration type for creating sessions
+ *
+ * @example
+ * ```typescript
+ * class APIClientManager extends BaseSessionManager<APIClient, APIConfig> {
+ *   async createSession(config?: APIConfig): Promise<string> {
+ *     const client = new APIClient(config);
+ *     const id = this.generateId("api");
+ *     this.sessions.set(id, client);
+ *     return id;
+ *   }
+ *
+ *   async closeSession(id: string): Promise<void> {
+ *     const client = this.sessions.get(id);
+ *     if (client) {
+ *       await client.disconnect();
+ *       this.sessions.delete(id);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare abstract class BaseSessionManager<TSession, TConfig = unknown> implements ISessionManager<TSession, TConfig> {
+    /** Map of session ID to session object */
+    protected sessions: Map<string, TSession>;
+    /** Counter for generating unique session IDs */
+    protected idCounter: number;
+    /**
+     * Generate a unique session ID with the given prefix.
+     *
+     * @param prefix - Prefix for the ID (e.g., "p" for pages, "b" for browsers)
+     * @returns Unique ID like "p1", "p2", etc.
+     */
+    protected generateId(prefix: string): string;
+    /**
+     * Create a new session.
+     * Must be implemented by subclasses.
+     */
+    abstract createSession(config?: TConfig): Promise<string>;
+    /**
+     * Close and remove a session.
+     * Must be implemented by subclasses.
+     */
+    abstract closeSession(id: string): Promise<void>;
+    /**
+     * Get a session by ID.
+     */
+    getSession(id: string): TSession | undefined;
+    /**
+     * Get a session by ID, throwing if not found.
+     */
+    requireSession(id: string): TSession;
+    /**
+     * List all active session IDs.
+     */
+    listSessions(): string[];
+    /**
+     * Check if a session exists.
+     */
+    hasSession(id: string): boolean;
+    /**
+     * Close all sessions.
+     * Closes sessions in reverse order (most recent first).
+     */
+    closeAll(): Promise<void>;
+}
+/**
+ * Simple in-memory session manager for testing or lightweight use cases.
+ *
+ * Sessions are just stored objects with no special cleanup logic.
+ *
+ * @example
+ * ```typescript
+ * const manager = new SimpleSessionManager<MyData>();
+ * const id = await manager.createSession({ value: 42 });
+ * const data = manager.requireSession(id);  // { value: 42 }
+ * await manager.closeSession(id);
+ * ```
+ */
+declare class SimpleSessionManager<TSession> extends BaseSessionManager<TSession, TSession> {
+    /**
+     * Create a session by storing the provided data.
+     */
+    createSession(data?: TSession): Promise<string>;
+    /**
+     * Close a session by removing it from the map.
+     */
+    closeSession(id: string): Promise<void>;
+    /**
+     * Set session data directly.
+     */
+    setSession(id: string, data: TSession): void;
+}
+
+/**
+ * Subagent creation helper for gadget authors.
+ *
+ * Simplifies the common pattern of creating subagents from within gadgets.
+ * Handles:
+ * - Getting host exports (AgentBuilder, LLMist) from context
+ * - Model resolution with "inherit" support
+ * - Parent context sharing for cost tracking
+ * - Common configuration options
+ *
+ * @module agent/subagent
+ *
+ * @example
+ * ```typescript
+ * import { createSubagent, Gadget, z } from "llmist";
+ * import type { ExecutionContext } from "llmist";
+ *
+ * class BrowseWeb extends Gadget({
+ *   name: "BrowseWeb",
+ *   schema: z.object({
+ *     task: z.string(),
+ *     url: z.string().url(),
+ *     model: z.string().optional(),
+ *   }),
+ * }) {
+ *   async execute(params: this["params"], ctx?: ExecutionContext) {
+ *     const agent = createSubagent(ctx!, {
+ *       name: "BrowseWeb",
+ *       gadgets: [Navigate, Click, Screenshot],
+ *       systemPrompt: BROWSER_SYSTEM_PROMPT,
+ *       model: params.model,  // Optional override
+ *       maxIterations: 15,
+ *     }).ask(params.task);
+ *
+ *     for await (const event of agent.run()) {
+ *       // Process events...
+ *     }
+ *
+ *     return result;
+ *   }
+ * }
+ * ```
+ */
+
+/**
+ * Options for creating a subagent.
+ */
+interface SubagentOptions {
+    /**
+     * Name of the subagent (used for config resolution).
+     * Should match the gadget name in CLI config, e.g., "BrowseWeb".
+     */
+    name: string;
+    /**
+     * Gadgets to register with the subagent.
+     */
+    gadgets: AbstractGadget[];
+    /**
+     * System prompt for the subagent.
+     */
+    systemPrompt?: string;
+    /**
+     * Model to use. If not provided, inherits from parent or uses default.
+     * Can be a runtime parameter from gadget params.
+     */
+    model?: string;
+    /**
+     * Default model if no other source provides one.
+     * @default "sonnet"
+     */
+    defaultModel?: string;
+    /**
+     * Maximum iterations for the agent loop.
+     */
+    maxIterations?: number;
+    /**
+     * Default max iterations if not specified.
+     * @default 15
+     */
+    defaultMaxIterations?: number;
+    /**
+     * Agent hooks for observers, interceptors, controllers.
+     */
+    hooks?: AgentHooks;
+    /**
+     * Temperature for LLM calls.
+     */
+    temperature?: number;
+}
+/**
+ * Create a subagent from within a gadget.
+ *
+ * This helper simplifies the common pattern of creating nested agents.
+ * It automatically:
+ * - Gets the correct AgentBuilder from host exports
+ * - Resolves model with "inherit" support from CLI config
+ * - Shares the parent's execution tree for cost tracking
+ * - Forwards the abort signal for proper cancellation
+ *
+ * @param ctx - ExecutionContext passed to gadget's execute()
+ * @param options - Subagent configuration options
+ * @returns Configured AgentBuilder ready for .ask()
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const agent = createSubagent(ctx, {
+ *   name: "BrowseWeb",
+ *   gadgets: [Navigate, Click],
+ * }).ask("Go to google.com");
+ *
+ * // With all options
+ * const agent = createSubagent(ctx, {
+ *   name: "BrowseWeb",
+ *   gadgets: [Navigate, Click, Screenshot],
+ *   systemPrompt: "You are a browser automation agent...",
+ *   model: params.model,  // Runtime override
+ *   defaultModel: "sonnet",
+ *   maxIterations: 20,
+ *   hooks: {
+ *     observers: {
+ *       onLLMCallReady: () => refreshPageState(),
+ *     },
+ *   },
+ * }).ask(params.task);
+ *
+ * for await (const event of agent.run()) {
+ *   // Events flow through shared tree automatically
+ * }
+ * ```
+ */
+declare function createSubagent(ctx: ExecutionContext, options: SubagentOptions): AgentBuilder;
+/**
+ * Check if an execution context has valid host exports.
+ *
+ * Useful for conditional logic when gadgets may run standalone or via agent.
+ *
+ * @param ctx - Execution context
+ * @returns True if host exports are available
+ */
+declare function hasHostExports(ctx?: ExecutionContext): boolean;
+
+/**
+ * Package manifest types for llmist gadget packages.
+ *
+ * These types define the structure of the `llmist` field in package.json
+ * for gadget packages. This enables:
+ * - Preset-based gadget loading
+ * - Subagent discovery
+ * - Factory function support
+ * - Session management metadata
+ *
+ * @module package/manifest
+ *
+ * @example package.json
+ * ```json
+ * {
+ *   "name": "dhalsim",
+ *   "llmist": {
+ *     "gadgets": "./dist/index.js",
+ *     "factory": "./dist/index.js",
+ *     "presets": {
+ *       "minimal": ["Navigate", "GetFullPageContent"],
+ *       "readonly": ["Navigate", "GetFullPageContent", "Screenshot"],
+ *       "all": "*"
+ *     },
+ *     "subagents": {
+ *       "BrowseWeb": {
+ *         "entryPoint": "./dist/index.js",
+ *         "export": "Dhalsim",
+ *         "description": "Autonomous web browser agent",
+ *         "defaultModel": "sonnet",
+ *         "maxIterations": 15
+ *       }
+ *     },
+ *     "session": {
+ *       "factory": "getSessionManager",
+ *       "type": "browser"
+ *     }
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Subagent definition in the manifest.
+ */
+interface SubagentManifestEntry {
+    /**
+     * Entry point file path relative to package root.
+     * @example "./dist/index.js"
+     */
+    entryPoint: string;
+    /**
+     * Export name from the entry point.
+     * @example "Dhalsim" or "BrowseWeb"
+     */
+    export: string;
+    /**
+     * Human-readable description of what this subagent does.
+     */
+    description?: string;
+    /**
+     * List of gadget names this subagent uses internally.
+     * Useful for documentation and dependency tracking.
+     */
+    uses?: string[];
+    /**
+     * Default model for this subagent.
+     * Can be "inherit" to use parent's model.
+     * @default "inherit"
+     */
+    defaultModel?: string;
+    /**
+     * Default maximum iterations.
+     * @default 15
+     */
+    maxIterations?: number;
+}
+/**
+ * Session factory metadata in the manifest.
+ */
+interface SessionManifestEntry {
+    /**
+     * Export name of the session factory function.
+     * @example "getSessionManager"
+     */
+    factory: string;
+    /**
+     * Type of session for categorization.
+     * @example "browser", "api", "database"
+     */
+    type: string;
+}
+/**
+ * Preset definition - either an array of gadget names or "*" for all.
+ */
+type PresetDefinition = string[] | "*";
+/**
+ * llmist package manifest structure.
+ *
+ * This is the shape of the `llmist` field in package.json
+ * for gadget packages.
+ */
+interface LLMistPackageManifest {
+    /**
+     * Entry point for all gadgets.
+     * The module should export gadgets or a gadgets array.
+     * @example "./dist/index.js"
+     */
+    gadgets?: string;
+    /**
+     * Entry point for factory functions.
+     * Should export `createGadgetsByPreset(preset)` and/or `createGadgetsByName(names)`.
+     * @example "./dist/index.js"
+     */
+    factory?: string;
+    /**
+     * Subagent definitions.
+     * Key is the subagent name as it appears in CLI config.
+     */
+    subagents?: Record<string, SubagentManifestEntry>;
+    /**
+     * Preset definitions.
+     * Key is preset name, value is array of gadget names or "*" for all.
+     * @example { "minimal": ["Navigate", "Screenshot"], "all": "*" }
+     */
+    presets?: Record<string, PresetDefinition>;
+    /**
+     * Session factory metadata.
+     */
+    session?: SessionManifestEntry;
+}
+/**
+ * Factory function types that packages can export.
+ */
+interface GadgetFactoryExports {
+    /**
+     * Create gadgets by preset name.
+     */
+    createGadgetsByPreset?: (preset: string, config?: unknown) => unknown;
+    /**
+     * Create gadgets by specific names.
+     */
+    createGadgetsByName?: (names: string[], config?: unknown) => unknown;
+    /**
+     * Create all gadgets with optional config.
+     */
+    createGadgets?: (config?: unknown) => unknown;
+}
+/**
+ * Read and parse the llmist manifest from a package.json object.
+ *
+ * @param packageJson - Parsed package.json object
+ * @returns Manifest or undefined if not present
+ *
+ * @example
+ * ```typescript
+ * import { readFileSync } from "fs";
+ *
+ * const pkg = JSON.parse(readFileSync("package.json", "utf-8"));
+ * const manifest = parseManifest(pkg);
+ *
+ * if (manifest?.presets?.minimal) {
+ *   console.log("Minimal preset:", manifest.presets.minimal);
+ * }
+ * ```
+ */
+declare function parseManifest(packageJson: Record<string, unknown>): LLMistPackageManifest | undefined;
+/**
+ * Check if a manifest has a specific preset.
+ */
+declare function hasPreset(manifest: LLMistPackageManifest | undefined, presetName: string): boolean;
+/**
+ * Get gadget names for a preset.
+ * Returns undefined if preset not found, empty array if preset is invalid.
+ */
+declare function getPresetGadgets(manifest: LLMistPackageManifest | undefined, presetName: string): string[] | "*" | undefined;
+/**
+ * Check if a manifest has subagent definitions.
+ */
+declare function hasSubagents(manifest: LLMistPackageManifest | undefined): boolean;
+/**
+ * Get subagent entry by name.
+ */
+declare function getSubagent(manifest: LLMistPackageManifest | undefined, name: string): SubagentManifestEntry | undefined;
+/**
+ * List all subagent names in a manifest.
+ */
+declare function listSubagents(manifest: LLMistPackageManifest | undefined): string[];
+/**
+ * List all preset names in a manifest.
+ */
+declare function listPresets(manifest: LLMistPackageManifest | undefined): string[];
+
 /**
  * Get host llmist exports from execution context.
  *
@@ -8573,4 +9442,4 @@ declare function createOpenAIProviderFromEnv(): OpenAIChatProvider | null;
  */
 declare function getHostExports(ctx: ExecutionContext): HostExports;
 
-export { AbortException, AbstractGadget, type AddGadgetParams, type AddLLMCallParams, type AfterGadgetExecutionAction, type AfterGadgetExecutionControllerContext, type AfterLLMCallAction, type AfterLLMCallControllerContext, type AfterLLMErrorAction, Agent, AgentBuilder, type AgentHooks, type AgentOptions, AnthropicMessagesProvider, type AudioContentPart, type AudioMimeType, type AudioSource, type BaseExecutionEvent, type BeforeGadgetExecutionAction, type BeforeLLMCallAction, type ChunkInterceptorContext, type CompactionConfig, type CompactionContext, type CompactionEvent, CompactionManager, type CompactionResult, type CompactionStats, type CompactionStrategy, type CompleteGadgetParams, type CompleteLLMCallParams, type ContentPart, type Controllers, ConversationManager, type CostEstimate, type CostReportingLLMist, type CreateGadgetConfig, DEFAULT_COMPACTION_CONFIG, DEFAULT_HINTS, DEFAULT_PROMPTS, DEFAULT_RETRY_CONFIG, DEFAULT_SUMMARIZATION_PROMPT, type EventHandlers, type ExecutionContext, type ExecutionEvent, type ExecutionEventType, type ExecutionNode, type ExecutionNodeType, ExecutionTree, FALLBACK_CHARS_PER_TOKEN, GADGET_ARG_PREFIX, GADGET_END_PREFIX, GADGET_START_PREFIX, Gadget, type GadgetCallEvent, GadgetCallParser, type GadgetClass, type GadgetCompleteEvent, type GadgetConfig, type GadgetErrorEvent, type GadgetEvent, type GadgetExample, type GadgetExecuteResult, type GadgetExecuteResultWithMedia, type GadgetExecuteReturn, type GadgetExecutionControllerContext, type GadgetExecutionResult, GadgetExecutor, type GadgetMediaOutput, type GadgetNode, type GadgetOrClass, GadgetOutputStore, type GadgetParameterInterceptorContext, GadgetRegistry, type GadgetResultInterceptorContext, type GadgetSkippedEvent, type GadgetStartEvent, type GadgetState, GeminiGenerativeProvider, type HintContext, type HintTemplate, type HintsConfig, type HistoryMessage, HookPresets, type HostExports, type HumanInputRequiredEvent, HumanInputRequiredException, HybridStrategy, type IConversationManager, type ImageBase64Source, type ImageContentPart, type ImageGenerationOptions, type ImageGenerationResult, type ImageMimeType, type ImageModelSpec, type ImageSource, type ImageUrlSource, type Interceptors, type IterationHintOptions, type LLMCallCompleteEvent, type LLMCallControllerContext, type LLMCallErrorEvent, type LLMCallInfo, type LLMCallNode, type LLMCallStartEvent, type LLMCallStreamEvent, type LLMErrorControllerContext, type LLMEvent, type LLMGenerationOptions, type LLMMessage, LLMMessageBuilder, type LLMStream, type LLMStreamChunk, LLMist, type LLMistOptions, type LoggerOptions, type LoggingOptions, MODEL_ALIASES, type MediaKind, type MediaMetadata, MediaStore, type MessageContent, type MessageInterceptorContext, type MessageRole, type MessageTurn, type ModelDescriptor, type ModelFeatures, ModelIdentifierParser, type ModelLimits, type ModelPricing, ModelRegistry, type ModelSpec, type NodeId, type ObserveChunkContext, type ObserveCompactionContext, type ObserveGadgetCompleteContext, type ObserveGadgetStartContext, type ObserveLLMCallContext, type ObserveLLMCompleteContext, type ObserveLLMErrorContext, type Observers, OpenAIChatProvider, type ParallelGadgetHintOptions, type ParsedGadgetCall, type PromptContext, type PromptTemplate, type PromptTemplateConfig, type ProviderAdapter, type ProviderIdentifier, type ResolveValueOptions, type ResolvedCompactionConfig, type ResolvedRetryConfig, type RetryConfig, SlidingWindowStrategy, type SpeechGenerationOptions, type SpeechGenerationResult, type SpeechModelSpec, type StoredMedia, type StoredOutput, type StreamCompleteEvent, type StreamEvent, type StreamProcessingResult, StreamProcessor, type StreamProcessorOptions, type SubagentConfig, type SubagentConfigMap, type SubagentContext, type SubagentEvent, type SubagentStreamEvent, SummarizationStrategy, TaskCompletionSignal, type TextContentPart, type TextEvent, type TextGenerationOptions, type TextOnlyAction, type TextOnlyContext, type TextOnlyCustomHandler, type TextOnlyGadgetConfig, type TextOnlyHandler, type TextOnlyStrategy, TimeoutException, type TokenUsage, type TrailingMessage, type TrailingMessageContext, type CompactionEvent$1 as TreeCompactionEvent, type GadgetSkippedEvent$1 as TreeGadgetSkippedEvent, type ValidationIssue, type ValidationResult, type VisionAnalyzeOptions, type VisionAnalyzeResult, audioFromBase64, audioFromBuffer, collectEvents, collectText, complete, createAnthropicProviderFromEnv, createGadget, createGadgetOutputViewer, createGeminiProviderFromEnv, createHints, createLogger, createMediaOutput, createOpenAIProviderFromEnv, defaultLogger, detectAudioMimeType, detectImageMimeType, discoverProviderAdapters, extractMessageText, filterByDepth, filterByParent, filterRootEvents, formatLLMError, getHostExports, getModelId, getProvider, groupByParent, hasProviderPrefix, imageFromBase64, imageFromBuffer, imageFromUrl, isAbortError, isAudioPart, isDataUrl, isGadgetEvent, isImagePart, isLLMEvent, isRetryableError, isRootEvent, isSubagentEvent, isTextPart, iterationProgressHint, normalizeMessageContent, parallelGadgetHint, parseDataUrl, resolveConfig, resolveHintTemplate, resolveModel, resolvePromptTemplate, resolveRetryConfig, resolveRulesTemplate, resolveSubagentModel, resolveValue, resultWithAudio, resultWithFile, resultWithImage, resultWithImages, resultWithMedia, runWithHandlers, schemaToJSONSchema, stream, text, toBase64, validateAndApplyDefaults, validateGadgetParams, validateGadgetSchema };
+export { AbortException, AbstractGadget, type AddGadgetParams, type AddLLMCallParams, type AfterGadgetExecutionAction, type AfterGadgetExecutionControllerContext, type AfterLLMCallAction, type AfterLLMCallControllerContext, type AfterLLMErrorAction, Agent, AgentBuilder, type AgentHooks, type AgentOptions, AnthropicMessagesProvider, type AudioContentPart, type AudioMimeType, type AudioSource, type BaseExecutionEvent, BaseSessionManager, type BeforeGadgetExecutionAction, type BeforeLLMCallAction, type ChunkInterceptorContext, type CompactionConfig, type CompactionContext, type CompactionEvent, CompactionManager, type CompactionResult, type CompactionStats, type CompactionStrategy, type CompleteGadgetParams, type CompleteLLMCallParams, type ContentPart, type Controllers, ConversationManager, type CostEstimate, type CostReportingLLMist, type CreateGadgetConfig, DEFAULT_COMPACTION_CONFIG, DEFAULT_HINTS, DEFAULT_PROMPTS, DEFAULT_RETRY_CONFIG, DEFAULT_SUMMARIZATION_PROMPT, type EventHandlers, type ExecutionContext, type ExecutionEvent, type ExecutionEventType, type ExecutionNode, type ExecutionNodeType, ExecutionTree, FALLBACK_CHARS_PER_TOKEN, GADGET_ARG_PREFIX, GADGET_END_PREFIX, GADGET_START_PREFIX, Gadget, type GadgetCallEvent, GadgetCallParser, type GadgetClass, type GadgetCompleteEvent, type GadgetConfig, type GadgetErrorEvent, type GadgetEvent, type GadgetExample, type GadgetExecuteResult, type GadgetExecuteResultWithMedia, type GadgetExecuteReturn, type GadgetExecutionControllerContext, type GadgetExecutionResult, GadgetExecutor, type GadgetFactoryExports, type GadgetMediaOutput, type GadgetNode, type GadgetOrClass, GadgetOutputStore, type GadgetParameterInterceptorContext, GadgetRegistry, type GadgetResultInterceptorContext, type GadgetSkippedEvent, type GadgetStartEvent, type GadgetState, GeminiGenerativeProvider, type HintContext, type HintTemplate, type HintsConfig, type HistoryMessage, HookPresets, type HostExports, type HumanInputRequiredEvent, HumanInputRequiredException, HybridStrategy, type IConversationManager, type ISessionManager, type ImageBase64Source, type ImageContentPart, type ImageGenerationOptions, type ImageGenerationResult, type ImageMimeType, type ImageModelSpec, type ImageSource, type ImageUrlSource, type Interceptors, type IterationHintOptions, type LLMCallCompleteEvent, type LLMCallControllerContext, type LLMCallErrorEvent, type LLMCallInfo, type LLMCallNode, type LLMCallStartEvent, type LLMCallStreamEvent, type LLMErrorControllerContext, type LLMEvent, type LLMGenerationOptions, type LLMMessage, LLMMessageBuilder, type LLMStream, type LLMStreamChunk, LLMist, type LLMistOptions, type LLMistPackageManifest, type LoggerOptions, type LoggingOptions, MODEL_ALIASES, type MediaKind, type MediaMetadata, MediaStore, type MessageContent, type MessageInterceptorContext, type MessageRole, type MessageTurn, type ModelDescriptor, type ModelFeatures, ModelIdentifierParser, type ModelLimits, type ModelPricing, ModelRegistry, type ModelSpec, type NodeId, type ObserveChunkContext, type ObserveCompactionContext, type ObserveGadgetCompleteContext, type ObserveGadgetStartContext, type ObserveLLMCallContext, type ObserveLLMCompleteContext, type ObserveLLMErrorContext, type Observers, OpenAIChatProvider, type ParallelGadgetHintOptions, type ParsedGadgetCall, type PresetDefinition, type PromptContext, type PromptTemplate, type PromptTemplateConfig, type ProviderAdapter, type ProviderIdentifier, type ResolveValueOptions, type ResolvedCompactionConfig, type ResolvedRetryConfig, type RetryConfig, type RetryOptions, type SessionManifestEntry, SimpleSessionManager, SlidingWindowStrategy, type SpeechGenerationOptions, type SpeechGenerationResult, type SpeechModelSpec, type StoredMedia, type StoredOutput, type StreamCompleteEvent, type StreamEvent, type StreamProcessingResult, StreamProcessor, type StreamProcessorOptions, type SubagentConfig, type SubagentConfigMap, type SubagentContext, type SubagentEvent, type SubagentManifestEntry, type SubagentOptions, type SubagentStreamEvent, SummarizationStrategy, TaskCompletionSignal, type TextContentPart, type TextEvent, type TextGenerationOptions, type TextOnlyAction, type TextOnlyContext, type TextOnlyCustomHandler, type TextOnlyGadgetConfig, type TextOnlyHandler, type TextOnlyStrategy, TimeoutException, type TokenUsage, type TrailingMessage, type TrailingMessageContext, type CompactionEvent$1 as TreeCompactionEvent, type GadgetSkippedEvent$1 as TreeGadgetSkippedEvent, type ValidationIssue, type ValidationResult, type VisionAnalyzeOptions, type VisionAnalyzeResult, audioFromBase64, audioFromBuffer, collectEvents, collectText, complete, createAnthropicProviderFromEnv, createGadget, createGadgetOutputViewer, createGeminiProviderFromEnv, createHints, createLogger, createMediaOutput, createOpenAIProviderFromEnv, createSubagent, defaultLogger, detectAudioMimeType, detectImageMimeType, discoverProviderAdapters, extractMessageText, filterByDepth, filterByParent, filterRootEvents, format, formatBytes, formatDate, formatDuration, formatLLMError, gadgetError, gadgetSuccess, getErrorMessage, getHostExports, getModelId, getPresetGadgets, getProvider, getSubagent, groupByParent, hasHostExports, hasPreset, hasProviderPrefix, hasSubagents, humanDelay, imageFromBase64, imageFromBuffer, imageFromUrl, isAbortError, isAudioPart, isDataUrl, isGadgetEvent, isImagePart, isLLMEvent, isRetryableError, isRootEvent, isSubagentEvent, isTextPart, iterationProgressHint, listPresets, listSubagents, normalizeMessageContent, parallelGadgetHint, parseDataUrl, parseManifest, randomDelay, resolveConfig, resolveHintTemplate, resolveModel, resolvePromptTemplate, resolveRetryConfig, resolveRulesTemplate, resolveSubagentModel, resolveValue, resultWithAudio, resultWithFile, resultWithImage, resultWithImages, resultWithMedia, runWithHandlers, schemaToJSONSchema, stream, text, timing, toBase64, truncate, validateAndApplyDefaults, validateGadgetParams, validateGadgetSchema, withErrorHandling, withRetry, withTimeout };