llmist 16.0.4 → 16.2.0

package/dist/index.d.ts

@@ -632,8 +632,6 @@ interface CompleteGadgetParams {
     storedMedia?: StoredMedia[];
 }
 
-/** Event listener function type */
-type EventListener = (event: ExecutionEvent) => void;
 /**
  * The Execution Tree - single source of truth for all execution state.
  *
@@ -668,12 +666,9 @@ type EventListener = (event: ExecutionEvent) => void;
 declare class ExecutionTree {
     private nodes;
     private rootIds;
-    private eventListeners;
-    private eventIdCounter;
     private invocationIdToNodeId;
-    private eventQueue;
-    private eventWaiters;
-    private isCompleted;
+    private emitter;
+    private aggregator;
     /**
      * Base depth for all nodes in this tree.
      * Used when this tree is a subagent's view into a parent tree.
@@ -831,11 +826,11 @@ declare class ExecutionTree {
      * });
      * ```
      */
-    on(type: ExecutionEventType, listener: EventListener): () => void;
+    on(type: ExecutionEventType, listener: (event: ExecutionEvent) => void): () => void;
     /**
      * Subscribe to all events.
      */
-    onAll(listener: EventListener): () => void;
+    onAll(listener: (event: ExecutionEvent) => void): () => void;
     /**
      * Get async iterable of all events.
      * Events are yielded as they occur.
@@ -843,6 +838,7 @@ declare class ExecutionTree {
     events(): AsyncGenerator<ExecutionEvent>;
     /**
      * Mark the tree as complete (no more events will be emitted).
+     * Wakes up any consumers waiting in the events() async generator.
      */
     complete(): void;
     /**
@@ -1127,7 +1123,6 @@ declare function Gadget<TSchema extends ZodType>(config: GadgetConfig<TSchema>):
         throwIfAborted(ctx?: ExecutionContext): void;
         onAbort(ctx: ExecutionContext | undefined, cleanup: () => void | Promise<void>): void;
         createLinkedAbortController(ctx?: ExecutionContext): AbortController;
-        get instruction(): string;
         getInstruction(optionsOrArgPrefix?: string | {
             argPrefix?: string;
             startPrefix?: string;
@@ -1138,6 +1133,253 @@ declare function Gadget<TSchema extends ZodType>(config: GadgetConfig<TSchema>):
     };
 };
 
+/**
+ * Proactive rate limiting for LLM API calls.
+ *
+ * Tracks request and token usage in sliding windows to prevent rate limit errors
+ * before they occur. Works in conjunction with reactive backoff (retry.ts) for
+ * comprehensive rate limit handling.
+ */
+/**
+ * Configuration for proactive rate limiting.
+ *
+ * Set these values based on your API tier to prevent rate limit errors.
+ * When limits are approached, requests will be automatically delayed.
+ *
+ * @example
+ * ```typescript
+ * // Gemini free tier limits
+ * const agent = LLMist.createAgent()
+ *   .withRateLimits({
+ *     requestsPerMinute: 15,
+ *     tokensPerMinute: 1_000_000,
+ *     safetyMargin: 0.8,
+ *   });
+ *
+ * // OpenAI Tier 1 limits
+ * const agent = LLMist.createAgent()
+ *   .withRateLimits({
+ *     requestsPerMinute: 500,
+ *     tokensPerMinute: 200_000,
+ *   });
+ * ```
+ */
+interface RateLimitConfig {
+    /**
+     * Maximum requests per minute.
+     * Set based on your API tier. If not set, RPM limiting is disabled.
+     */
+    requestsPerMinute?: number;
+    /**
+     * Maximum tokens per minute (input + output combined).
+     * Set based on your API tier. If not set, TPM limiting is disabled.
+     */
+    tokensPerMinute?: number;
+    /**
+     * Maximum tokens per day (optional).
+     * Useful for Gemini free tier which has daily limits.
+     * If not set, daily limiting is disabled.
+     */
+    tokensPerDay?: number;
+    /**
+     * Safety margin - start throttling at this percentage of limit.
+     * A value of 0.9 means throttling starts at 90% of the limit.
+     * Lower values provide more safety but may reduce throughput.
+     * @default 0.9
+     */
+    safetyMargin?: number;
+    /**
+     * Whether proactive rate limiting is enabled.
+     * @default true (when any limit is configured)
+     */
+    enabled?: boolean;
+}
+/**
+ * Resolved rate limit configuration with all defaults applied.
+ */
+interface ResolvedRateLimitConfig {
+    requestsPerMinute?: number;
+    tokensPerMinute?: number;
+    tokensPerDay?: number;
+    safetyMargin: number;
+    enabled: boolean;
+}
+/**
+ * Default rate limit configuration values.
+ */
+declare const DEFAULT_RATE_LIMIT_CONFIG: Pick<ResolvedRateLimitConfig, "safetyMargin" | "enabled">;
+/**
+ * Resolves a partial rate limit configuration by applying defaults.
+ *
+ * @param config - Partial configuration (optional)
+ * @returns Fully resolved configuration
+ */
+declare function resolveRateLimitConfig(config?: RateLimitConfig): ResolvedRateLimitConfig;
+/**
+ * Information about a triggered rate limit.
+ */
+interface TriggeredLimitInfo {
+    /** Current usage value */
+    current: number;
+    /** Configured limit value */
+    limit: number;
+    /** Effective limit after safety margin (limit × safetyMargin) */
+    effectiveLimit: number;
+}
+/**
+ * Usage statistics from the rate limit tracker.
+ */
+interface RateLimitStats {
+    /** Current requests per minute */
+    rpm: number;
+    /** Current tokens per minute */
+    tpm: number;
+    /** Tokens used today (UTC) */
+    dailyTokens: number;
+    /** Whether any limit is currently being approached */
+    isApproachingLimit: boolean;
+    /** Delay required before next request (0 if none) */
+    requiredDelayMs: number;
+    /** Which limit(s) triggered throttling, if any (present when requiredDelayMs > 0) */
+    triggeredBy?: {
+        rpm?: TriggeredLimitInfo;
+        tpm?: TriggeredLimitInfo;
+        daily?: TriggeredLimitInfo;
+    };
+}
+/**
+ * Tracks API usage and calculates required delays for proactive rate limiting.
+ *
+ * Uses sliding windows to track requests and token usage, automatically
+ * calculating delays needed to stay within configured limits.
+ *
+ * @example
+ * ```typescript
+ * const tracker = new RateLimitTracker({
+ *   requestsPerMinute: 60,
+ *   tokensPerMinute: 100000,
+ * });
+ *
+ * // Before each request
+ * const delay = tracker.getRequiredDelayMs();
+ * if (delay > 0) {
+ *   await sleep(delay);
+ * }
+ *
+ * // After each request
+ * tracker.recordUsage(inputTokens, outputTokens);
+ * ```
+ */
+declare class RateLimitTracker {
+    private config;
+    /** Timestamps of requests in the current minute window */
+    private requestTimestamps;
+    /** Token usage entries in the current minute window */
+    private tokenUsage;
+    /** Daily token count */
+    private dailyTokens;
+    /** Date string (YYYY-MM-DD UTC) for daily reset tracking */
+    private dailyResetDate;
+    /** Count of pending reservations (for backward compatibility) */
+    private pendingReservations;
+    constructor(config?: RateLimitConfig);
+    /**
+     * Record a completed request with its token usage.
+     *
+     * If reserveRequest() was called before the LLM call (recommended for concurrent
+     * scenarios), the request timestamp was already recorded. Otherwise, this method
+     * will add it for backward compatibility.
+     *
+     * @param inputTokens - Number of input tokens used
+     * @param outputTokens - Number of output tokens generated
+     */
+    recordUsage(inputTokens: number, outputTokens: number): void;
+    /**
+     * Calculate the delay needed before the next request.
+     *
+     * Returns 0 if no delay is needed, otherwise returns the number of
+     * milliseconds to wait to stay within rate limits.
+     *
+     * @returns Delay in milliseconds (0 if none needed)
+     */
+    getRequiredDelayMs(): number;
+    /**
+     * Check if we're approaching any configured limits.
+     *
+     * @returns true if any limit is at or above the safety margin threshold
+     */
+    isApproachingLimit(): boolean;
+    /**
+     * Get current usage statistics.
+     *
+     * @returns Current usage stats for monitoring/logging
+     */
+    getUsageStats(): RateLimitStats;
+    /**
+     * Reset all tracking state.
+     * Useful for testing or when switching API keys/tiers.
+     */
+    reset(): void;
+    /**
+     * Update configuration dynamically.
+     * Useful when API tier changes or for testing.
+     *
+     * @param config - New configuration to apply
+     */
+    updateConfig(config: RateLimitConfig): void;
+    /**
+     * Reserve a request slot before making an LLM call.
+     *
+     * This is critical for concurrent subagents sharing a rate limiter.
+     * Without reservation, multiple subagents checking getRequiredDelayMs()
+     * simultaneously would all see zero usage and proceed, causing rate limit errors.
+     *
+     * Call this AFTER waiting for getRequiredDelayMs() but BEFORE making the LLM call.
+     * The reservation ensures subsequent concurrent checks see the pending request.
+     *
+     * @example
+     * ```typescript
+     * // Proactive rate limiting with reservation
+     * const delay = tracker.getRequiredDelayMs();
+     * if (delay > 0) await sleep(delay);
+     *
+     * tracker.reserveRequest(); // Claim slot BEFORE making call
+     * try {
+     *   const result = await llm.call();
+     *   tracker.recordUsage(result.inputTokens, result.outputTokens);
+     * } catch (error) {
+     *   // Request already reserved; recordUsage updates token count
+     *   throw error;
+     * }
+     * ```
+     */
+    reserveRequest(): void;
+    /**
+     * Calculate delay needed based on RPM limit.
+     */
+    private calculateRpmDelay;
+    /**
+     * Calculate delay needed based on TPM limit.
+     */
+    private calculateTpmDelay;
+    /**
+     * Remove entries older than 1 minute from the sliding window.
+     */
+    private pruneOldEntries;
+    /**
+     * Check if the day has changed (UTC) and reset daily counters.
+     */
+    private checkDailyReset;
+    /**
+     * Get current date in YYYY-MM-DD format (UTC).
+     */
+    private getCurrentDateUTC;
+    /**
+     * Calculate milliseconds until midnight UTC.
+     */
+    private getTimeUntilMidnightUTC;
+}
+
 /**
  * Model Catalog Types
  *
@@ -1457,255 +1699,8 @@ interface ResolvedCompactionConfig {
 }
 
 /**
- * Proactive rate limiting for LLM API calls.
- *
- * Tracks request and token usage in sliding windows to prevent rate limit errors
- * before they occur. Works in conjunction with reactive backoff (retry.ts) for
- * comprehensive rate limit handling.
- */
-/**
- * Configuration for proactive rate limiting.
- *
- * Set these values based on your API tier to prevent rate limit errors.
- * When limits are approached, requests will be automatically delayed.
- *
- * @example
- * ```typescript
- * // Gemini free tier limits
- * const agent = LLMist.createAgent()
- *   .withRateLimits({
- *     requestsPerMinute: 15,
- *     tokensPerMinute: 1_000_000,
- *     safetyMargin: 0.8,
- *   });
- *
- * // OpenAI Tier 1 limits
- * const agent = LLMist.createAgent()
- *   .withRateLimits({
- *     requestsPerMinute: 500,
- *     tokensPerMinute: 200_000,
- *   });
- * ```
- */
-interface RateLimitConfig {
-    /**
-     * Maximum requests per minute.
-     * Set based on your API tier. If not set, RPM limiting is disabled.
-     */
-    requestsPerMinute?: number;
-    /**
-     * Maximum tokens per minute (input + output combined).
-     * Set based on your API tier. If not set, TPM limiting is disabled.
-     */
-    tokensPerMinute?: number;
-    /**
-     * Maximum tokens per day (optional).
-     * Useful for Gemini free tier which has daily limits.
-     * If not set, daily limiting is disabled.
-     */
-    tokensPerDay?: number;
-    /**
-     * Safety margin - start throttling at this percentage of limit.
-     * A value of 0.9 means throttling starts at 90% of the limit.
-     * Lower values provide more safety but may reduce throughput.
-     * @default 0.9
-     */
-    safetyMargin?: number;
-    /**
-     * Whether proactive rate limiting is enabled.
-     * @default true (when any limit is configured)
-     */
-    enabled?: boolean;
-}
-/**
- * Resolved rate limit configuration with all defaults applied.
- */
-interface ResolvedRateLimitConfig {
-    requestsPerMinute?: number;
-    tokensPerMinute?: number;
-    tokensPerDay?: number;
-    safetyMargin: number;
-    enabled: boolean;
-}
-/**
- * Default rate limit configuration values.
- */
-declare const DEFAULT_RATE_LIMIT_CONFIG: Pick<ResolvedRateLimitConfig, "safetyMargin" | "enabled">;
-/**
- * Resolves a partial rate limit configuration by applying defaults.
- *
- * @param config - Partial configuration (optional)
- * @returns Fully resolved configuration
- */
-declare function resolveRateLimitConfig(config?: RateLimitConfig): ResolvedRateLimitConfig;
-/**
- * Information about a triggered rate limit.
- */
-interface TriggeredLimitInfo {
-    /** Current usage value */
-    current: number;
-    /** Configured limit value */
-    limit: number;
-    /** Effective limit after safety margin (limit × safetyMargin) */
-    effectiveLimit: number;
-}
-/**
- * Usage statistics from the rate limit tracker.
- */
-interface RateLimitStats {
-    /** Current requests per minute */
-    rpm: number;
-    /** Current tokens per minute */
-    tpm: number;
-    /** Tokens used today (UTC) */
-    dailyTokens: number;
-    /** Whether any limit is currently being approached */
-    isApproachingLimit: boolean;
-    /** Delay required before next request (0 if none) */
-    requiredDelayMs: number;
-    /** Which limit(s) triggered throttling, if any (present when requiredDelayMs > 0) */
-    triggeredBy?: {
-        rpm?: TriggeredLimitInfo;
-        tpm?: TriggeredLimitInfo;
-        daily?: TriggeredLimitInfo;
-    };
-}
-/**
- * Tracks API usage and calculates required delays for proactive rate limiting.
- *
- * Uses sliding windows to track requests and token usage, automatically
- * calculating delays needed to stay within configured limits.
- *
- * @example
- * ```typescript
- * const tracker = new RateLimitTracker({
- *   requestsPerMinute: 60,
- *   tokensPerMinute: 100000,
- * });
- *
- * // Before each request
- * const delay = tracker.getRequiredDelayMs();
- * if (delay > 0) {
- *   await sleep(delay);
- * }
- *
- * // After each request
- * tracker.recordUsage(inputTokens, outputTokens);
- * ```
- */
-declare class RateLimitTracker {
-    private config;
-    /** Timestamps of requests in the current minute window */
-    private requestTimestamps;
-    /** Token usage entries in the current minute window */
-    private tokenUsage;
-    /** Daily token count */
-    private dailyTokens;
-    /** Date string (YYYY-MM-DD UTC) for daily reset tracking */
-    private dailyResetDate;
-    /** Count of pending reservations (for backward compatibility) */
-    private pendingReservations;
-    constructor(config?: RateLimitConfig);
-    /**
-     * Record a completed request with its token usage.
-     *
-     * If reserveRequest() was called before the LLM call (recommended for concurrent
-     * scenarios), the request timestamp was already recorded. Otherwise, this method
-     * will add it for backward compatibility.
-     *
-     * @param inputTokens - Number of input tokens used
-     * @param outputTokens - Number of output tokens generated
-     */
-    recordUsage(inputTokens: number, outputTokens: number): void;
-    /**
-     * Calculate the delay needed before the next request.
-     *
-     * Returns 0 if no delay is needed, otherwise returns the number of
-     * milliseconds to wait to stay within rate limits.
-     *
-     * @returns Delay in milliseconds (0 if none needed)
-     */
-    getRequiredDelayMs(): number;
-    /**
-     * Check if we're approaching any configured limits.
-     *
-     * @returns true if any limit is at or above the safety margin threshold
-     */
-    isApproachingLimit(): boolean;
-    /**
-     * Get current usage statistics.
-     *
-     * @returns Current usage stats for monitoring/logging
-     */
-    getUsageStats(): RateLimitStats;
-    /**
-     * Reset all tracking state.
-     * Useful for testing or when switching API keys/tiers.
-     */
-    reset(): void;
-    /**
-     * Update configuration dynamically.
-     * Useful when API tier changes or for testing.
-     *
-     * @param config - New configuration to apply
-     */
-    updateConfig(config: RateLimitConfig): void;
-    /**
-     * Reserve a request slot before making an LLM call.
-     *
-     * This is critical for concurrent subagents sharing a rate limiter.
-     * Without reservation, multiple subagents checking getRequiredDelayMs()
-     * simultaneously would all see zero usage and proceed, causing rate limit errors.
-     *
-     * Call this AFTER waiting for getRequiredDelayMs() but BEFORE making the LLM call.
-     * The reservation ensures subsequent concurrent checks see the pending request.
-     *
-     * @example
-     * ```typescript
-     * // Proactive rate limiting with reservation
-     * const delay = tracker.getRequiredDelayMs();
-     * if (delay > 0) await sleep(delay);
-     *
-     * tracker.reserveRequest(); // Claim slot BEFORE making call
-     * try {
-     *   const result = await llm.call();
-     *   tracker.recordUsage(result.inputTokens, result.outputTokens);
-     * } catch (error) {
-     *   // Request already reserved; recordUsage updates token count
-     *   throw error;
-     * }
-     * ```
-     */
-    reserveRequest(): void;
-    /**
-     * Calculate delay needed based on RPM limit.
-     */
-    private calculateRpmDelay;
-    /**
-     * Calculate delay needed based on TPM limit.
-     */
-    private calculateTpmDelay;
-    /**
-     * Remove entries older than 1 minute from the sliding window.
-     */
-    private pruneOldEntries;
-    /**
-     * Check if the day has changed (UTC) and reset daily counters.
-     */
-    private checkDailyReset;
-    /**
-     * Get current date in YYYY-MM-DD format (UTC).
-     */
-    private getCurrentDateUTC;
-    /**
-     * Calculate milliseconds until midnight UTC.
-     */
-    private getTimeUntilMidnightUTC;
-}
-
-/**
- * Metadata present when an event originates from a subagent.
- * Undefined for top-level agent events.
+ * Metadata present when an event originates from a subagent.
+ * Undefined for top-level agent events.
  *
  * When using subagent gadgets (like BrowseWeb), hook observers receive events
  * from both the main agent AND subagents. Check this context to distinguish.
@@ -1823,13 +1818,6 @@ interface ObserveGadgetCompleteContext {
     gadgetName: string;
     invocationId: string;
     parameters: Readonly<Record<string, unknown>>;
-    /**
-     * Original result before interceptors.
-     * @deprecated No longer populated. Use `finalResult` instead.
-     * With the unified event architecture, observers receive the final (post-interceptor)
-     * result from the ExecutionTree.
-     */
-    originalResult?: string;
     /** Final result after interceptors (the value stored in ExecutionTree) */
     finalResult?: string;
     error?: string;
@@ -1908,6 +1896,8 @@ interface Observers {
     onRateLimitThrottle?: (context: ObserveRateLimitThrottleContext) => void | Promise<void>;
     /** Called when a retry attempt is made after a failed LLM call */
     onRetryAttempt?: (context: ObserveRetryAttemptContext) => void | Promise<void>;
+    /** Called when a skill is activated (via UseSkill gadget or pre-activation) */
+    onSkillActivated?: (context: ObserveSkillActivatedContext) => void | Promise<void>;
 }
 /**
  * Context provided when context compaction occurs.
@@ -1976,24 +1966,71 @@ interface ObserveRetryAttemptContext {
     subagentContext?: SubagentContext;
 }
 /**
- * Context for chunk interception.
+ * Context provided when a skill is activated.
+ * Read-only observation point.
  */
-interface ChunkInterceptorContext {
+interface ObserveSkillActivatedContext {
+    /** Name of the activated skill */
+    skillName: string;
+    /** Arguments passed to the skill (if any) */
+    arguments?: string;
+    /** Current iteration when activation occurred */
     iteration: number;
-    accumulatedText: string;
+    /** Logger instance */
     logger: Logger<ILogObj>;
 }
 /**
- * Context for message interception.
+ * Context for skill activation controller.
  */
-interface MessageInterceptorContext {
+interface SkillActivationControllerContext {
+    /** Name of the skill being activated */
+    skillName: string;
+    /** Arguments passed to the skill */
+    arguments?: string;
+    /** Current iteration */
     iteration: number;
-    /** The raw LLM response */
-    rawResponse: string;
+    /** Logger instance */
     logger: Logger<ILogObj>;
 }
 /**
- * Context for gadget parameter interception.
+ * Action returned by beforeSkillActivation controller.
+ */
+type BeforeSkillActivationAction = {
+    action: "proceed";
+} | {
+    action: "skip";
+    reason?: string;
+};
+/**
+ * Context for skill instruction interception.
+ */
+interface SkillInstructionInterceptorContext {
+    /** Name of the skill being activated */
+    skillName: string;
+    /** Arguments passed to the skill */
+    arguments?: string;
+    /** Logger instance */
+    logger: Logger<ILogObj>;
+}
+/**
+ * Context for chunk interception.
+ */
+interface ChunkInterceptorContext {
+    iteration: number;
+    accumulatedText: string;
+    logger: Logger<ILogObj>;
+}
+/**
+ * Context for message interception.
+ */
+interface MessageInterceptorContext {
+    iteration: number;
+    /** The raw LLM response */
+    rawResponse: string;
+    logger: Logger<ILogObj>;
+}
+/**
+ * Context for gadget parameter interception.
  */
 interface GadgetParameterInterceptorContext {
     iteration: number;
@@ -2067,6 +2104,14 @@ interface Interceptors {
      * @returns Transformed text (cannot be suppressed)
      */
     interceptGadgetResult?: (result: string, context: GadgetResultInterceptorContext) => string;
+    /**
+     * Intercept and transform skill instructions before they are returned to the LLM.
+     *
+     * @param instructions - The resolved skill instructions
+     * @param context - Context including skill name and arguments
+     * @returns Transformed instructions, or null to suppress the skill activation
+     */
+    interceptSkillInstructions?: (instructions: string, context: SkillInstructionInterceptorContext) => string | null;
 }
 /**
  * Context for LLM call controller.
@@ -2260,6 +2305,11 @@ interface Controllers {
      * Can override the default skip behavior to execute anyway or provide a fallback.
      */
     onDependencySkipped?: (context: DependencySkipControllerContext) => Promise<DependencySkipAction>;
+    /**
+     * Called before activating a skill.
+     * Can skip the activation (e.g., for permission checks or cost limits).
+     */
+    beforeSkillActivation?: (context: SkillActivationControllerContext) => Promise<BeforeSkillActivationAction>;
 }
 /**
  * Clean hooks system with three distinct categories:
@@ -2942,302 +2992,113 @@ declare function parseRetryAfterHeader(value: string): number | null;
 declare function extractRetryAfterMs(error: Error): number | null;
 
 /**
- * Example of gadget usage to help LLMs understand proper invocation.
- *
- * Examples are rendered alongside the schema in `getInstruction()` to provide
- * concrete usage patterns for the LLM.
+ * Subagent configuration types.
  *
- * @template TParams - Inferred parameter type from Zod schema (defaults to Record<string, unknown>)
+ * Simple config shapes passed to gadgets for subagent configuration.
+ * No external dependencies — self-contained data shapes.
  *
- * @example
- * ```typescript
- * const calculator = createGadget({
- *   schema: z.object({ a: z.number(), b: z.number() }),
- *   examples: [
- *     { params: { a: 5, b: 3 }, output: "8", comment: "Addition example" }
- *   ],
- *   // ...
- * });
- * ```
- */
-interface GadgetExample<TParams = Record<string, unknown>> {
-    /** Example parameter values (typed to match schema) */
-    params: TParams;
-    /** Optional expected output/result string */
-    output?: string;
-    /** Optional description explaining what this example demonstrates */
-    comment?: string;
-}
-/**
- * Supported media types for gadget output.
- * Extensible via union - add new types as needed.
+ * @module
  */
-type MediaKind = "image" | "audio" | "video" | "file";
 /**
- * Type-specific metadata for media outputs.
- * Extensible via index signature for future media types.
+ * Parent agent configuration passed to gadgets.
+ * Contains settings that subagents can inherit.
  */
-interface MediaMetadata {
-    /** Width in pixels (images, video) */
-    width?: number;
-    /** Height in pixels (images, video) */
-    height?: number;
-    /** Duration in milliseconds (audio, video) */
-    durationMs?: number;
-    /** Allow additional metadata for future extensions */
-    [key: string]: unknown;
+interface AgentContextConfig {
+    /** Model identifier used by the parent agent */
+    model: string;
+    /** Temperature setting used by the parent agent */
+    temperature?: number;
 }
 /**
- * Media output from a gadget execution.
- * Supports images, audio, video, and arbitrary files.
+ * Configuration for a single subagent.
+ * Can be defined globally in `[subagents.Name]` or per-profile in `[profile.subagents.Name]`.
  *
  * @example
- * ```typescript
- * // Image output
- * const imageOutput: GadgetMediaOutput = {
- *   kind: "image",
- *   data: base64EncodedPng,
- *   mimeType: "image/png",
- *   description: "Screenshot of webpage",
- *   metadata: { width: 1920, height: 1080 }
- * };
+ * ```toml
+ * [subagents.BrowseWeb]
+ * model = "inherit"      # Use parent agent's model
+ * maxIterations = 20
+ * headless = true
  * ```
  */
-interface GadgetMediaOutput {
-    /** Type of media (discriminator for type-specific handling) */
-    kind: MediaKind;
-    /** Base64-encoded media data */
-    data: string;
-    /** Full MIME type (e.g., "image/png", "audio/mp3", "video/mp4") */
-    mimeType: string;
-    /** Human-readable description of the media */
-    description?: string;
-    /** Type-specific metadata */
-    metadata?: MediaMetadata;
-    /** Optional filename to use when saving (if not provided, auto-generated) */
-    fileName?: string;
+interface SubagentConfig {
+    /**
+     * Model to use for this subagent.
+     * - "inherit": Use parent agent's model (default behavior)
+     * - Any model ID: Use specific model (e.g., "sonnet", "haiku", "gpt-4o")
+     */
+    model?: string;
+    /** Maximum iterations for the subagent loop */
+    maxIterations?: number;
+    /** Budget limit in USD for the subagent */
+    budget?: number;
+    /**
+     * Timeout for the subagent gadget execution in milliseconds.
+     * Overrides the gadget's hardcoded timeoutMs when set.
+     * Set to 0 to disable timeout for this gadget.
+     */
+    timeoutMs?: number;
+    /**
+     * Maximum number of concurrent executions allowed for this gadget.
+     * When the limit is reached, additional calls are queued and processed
+     * as earlier executions complete (FIFO order).
+     * Set to 0 or omit to allow unlimited concurrent executions (default).
+     */
+    maxConcurrent?: number;
+    /** Additional subagent-specific options */
+    [key: string]: unknown;
 }
 /**
- * Stored media item with metadata and file path.
- *
- * Created by MediaStore when a gadget returns media outputs.
- * Contains the abstract ID, file path, and metadata for display.
+ * Map of subagent names to their configurations.
  */
-interface StoredMedia {
-    /** Unique ID for this media item (e.g., "media_a1b2c3") */
-    id: string;
-    /** Type of media */
-    kind: MediaKind;
-    /** Actual file path on disk (internal use) */
-    path: string;
-    /** MIME type */
-    mimeType: string;
-    /** File size in bytes */
-    sizeBytes: number;
-    /** Human-readable description */
-    description?: string;
-    /** Type-specific metadata */
-    metadata?: MediaMetadata;
-    /** Name of the gadget that created this media */
-    gadgetName: string;
-    /** When the media was stored */
-    createdAt: Date;
-}
-interface GadgetExecutionResult {
-    gadgetName: string;
-    invocationId: string;
-    parameters: Record<string, unknown>;
-    result?: string;
-    error?: string;
-    executionTimeMs: number;
-    breaksLoop?: boolean;
-    /** Cost of gadget execution in USD. Defaults to 0 if not provided by gadget. */
-    cost?: number;
-    /** Media outputs from the gadget (images, audio, video, files) */
-    media?: GadgetMediaOutput[];
-    /** Abstract IDs for media outputs (e.g., ["media_a1b2c3"]) */
-    mediaIds?: string[];
-    /** Stored media with paths (for CLI display) */
-    storedMedia?: StoredMedia[];
-}
+type SubagentConfigMap = Record<string, SubagentConfig>;
 /**
- * Result returned by gadget execute() method.
- * Can be a simple string or an object with result and optional cost.
+ * Gadget execution mode controlling how multiple gadgets are executed.
  *
- * @example
- * ```typescript
- * // Simple string return (free gadget)
- * execute: () => "result"
+ * - `'parallel'` (default): Gadgets without dependencies execute concurrently (fire-and-forget).
+ *   This maximizes throughput but gadgets may complete in any order.
  *
- * // Object return with cost
- * execute: () => ({ result: "data", cost: 0.001 })
- * ```
- */
-interface GadgetExecuteResult {
-    /** The execution result as a string */
-    result: string;
-    /** Optional cost in USD (e.g., 0.001 for $0.001) */
-    cost?: number;
-}
-/**
- * Extended result type with media support.
- * Use this when gadget returns images, audio, video, or files.
+ * - `'sequential'`: Gadgets execute one at a time, each awaiting completion before the next starts.
+ *   Useful for:
+ *   - Gadgets with implicit ordering dependencies (e.g., file operations)
+ *   - Debugging and tracing execution flow
+ *   - Resource-constrained environments
+ *   - Ensuring deterministic execution order
+ *
+ * Note: Explicit `dependsOn` relationships are always respected regardless of mode.
+ * Sequential mode effectively enforces a global `maxConcurrent: 1` for all gadgets.
  *
  * @example
  * ```typescript
- * // Return with image
- * execute: () => ({
- *   result: "Screenshot captured",
- *   media: [{
- *     kind: "image",
- *     data: base64EncodedPng,
- *     mimeType: "image/png",
- *     description: "Screenshot"
- *   }],
- *   cost: 0.001
- * })
+ * const agent = LLMist.createAgent()
+ *   .withModel("sonnet")
+ *   .withGadgets(FileReader, FileWriter)
+ *   .withGadgetExecutionMode('sequential')  // Execute one at a time
+ *   .ask("Process files in order");
  * ```
  */
-interface GadgetExecuteResultWithMedia {
-    /** The execution result as a string */
-    result: string;
-    /** Media outputs (images, audio, video, files) */
-    media?: GadgetMediaOutput[];
-    /** Optional cost in USD (e.g., 0.001 for $0.001) */
-    cost?: number;
+type GadgetExecutionMode = "parallel" | "sequential";
+
+/**
+ * Image generation namespace with automatic cost reporting.
+ */
+interface CostReportingImageNamespace {
+    /**
+     * Generate images from a text prompt.
+     * Costs are automatically reported to the execution context.
+     */
+    generate(options: ImageGenerationOptions): Promise<ImageGenerationResult>;
 }
 /**
- * Union type for backwards-compatible execute() return type.
- * Gadgets can return:
- * - string (legacy, cost = 0)
- * - GadgetExecuteResult (result + optional cost)
- * - GadgetExecuteResultWithMedia (result + optional media + optional cost)
+ * Speech generation namespace with automatic cost reporting.
  */
-type GadgetExecuteReturn = string | GadgetExecuteResult | GadgetExecuteResultWithMedia;
-interface ParsedGadgetCall {
-    gadgetName: string;
-    invocationId: string;
-    parametersRaw: string;
-    parameters?: Record<string, unknown>;
-    parseError?: string;
-    /** List of invocation IDs this gadget depends on. Empty array if no dependencies. */
-    dependencies: string[];
-}
-
-/** Event emitted when a gadget is skipped due to a failed dependency */
-interface GadgetSkippedEvent {
-    type: "gadget_skipped";
-    gadgetName: string;
-    invocationId: string;
-    parameters: Record<string, unknown>;
-    /** The invocation ID of the dependency that failed */
-    failedDependency: string;
-    /** The error message from the failed dependency */
-    failedDependencyError: string;
-}
-/**
- * Event emitted when stream processing completes, containing metadata.
- * This allows the async generator to "return" metadata while still yielding events.
- */
-interface StreamCompletionEvent {
-    type: "stream_complete";
-    /** The reason the LLM stopped generating (e.g., "stop", "tool_use") */
-    finishReason: string | null;
-    /** Token usage statistics from the LLM call */
-    usage?: TokenUsage;
-    /** Raw response text from the LLM */
-    rawResponse: string;
-    /** Final message after all interceptors applied */
-    finalMessage: string;
-    /** Whether any gadgets were executed during this iteration */
-    didExecuteGadgets: boolean;
-    /** Whether to break the agent loop (e.g., TaskComplete was called) */
-    shouldBreakLoop: boolean;
-    /** Accumulated thinking/reasoning content from reasoning models */
-    thinkingContent?: string;
-}
-type StreamEvent = {
-    type: "text";
-    content: string;
-} | {
-    type: "thinking";
-    content: string;
-    thinkingType: "thinking" | "redacted";
-} | {
-    type: "gadget_call";
-    call: ParsedGadgetCall;
-} | {
-    type: "gadget_result";
-    result: GadgetExecutionResult;
-} | GadgetSkippedEvent | {
-    type: "human_input_required";
-    question: string;
-    gadgetName: string;
-    invocationId: string;
-} | {
-    type: "compaction";
-    event: CompactionEvent;
-} | {
-    type: "llm_response_end";
-    finishReason: string | null;
-    usage?: TokenUsage;
-} | StreamCompletionEvent;
-
-type TextOnlyHandler = TextOnlyStrategy | TextOnlyGadgetConfig | TextOnlyCustomHandler;
-/**
- * Simple strategies for common cases
- * - 'terminate': End the loop (default behavior)
- * - 'acknowledge': Continue to next iteration
- * - 'wait_for_input': Request human input
- */
-type TextOnlyStrategy = "terminate" | "acknowledge" | "wait_for_input";
-/**
- * Configuration for triggering a gadget when receiving text-only response
- */
-interface TextOnlyGadgetConfig {
-    type: "gadget";
-    name: string;
+interface CostReportingSpeechNamespace {
     /**
-     * Optional function to map text to gadget parameters.
-     * If not provided, text will be passed as { text: string }
+     * Generate speech audio from text.
+     * Costs are automatically reported to the execution context.
      */
-    parameterMapping?: (text: string) => Record<string, unknown>;
-}
-/**
- * Custom handler for complex text-only response scenarios
- */
-interface TextOnlyCustomHandler {
-    type: "custom";
-    handler: (context: TextOnlyContext) => Promise<TextOnlyAction> | TextOnlyAction;
-}
-/**
- * Context provided to custom text-only handlers
- */
-interface TextOnlyContext {
-    /** The complete text response from the LLM */
-    text: string;
-    /** Current iteration number */
-    iteration: number;
-    /** Full conversation history */
-    conversation: LLMMessage[];
-    /** Logger instance */
-    logger: Logger<ILogObj>;
+    generate(options: SpeechGenerationOptions): Promise<SpeechGenerationResult>;
 }
-/**
- * Actions that can be returned by text-only handlers
- */
-type TextOnlyAction = {
-    action: "continue";
-} | {
-    action: "terminate";
-} | {
-    action: "wait_for_input";
-    question?: string;
-} | {
-    action: "trigger_gadget";
-    name: string;
-    parameters: Record<string, unknown>;
-};
 /**
  * LLMist client interface for use within gadgets.
  *
@@ -3256,26 +3117,6 @@ type TextOnlyAction = {
  * }
  * ```
  */
-/**
- * Image generation namespace with automatic cost reporting.
- */
-interface CostReportingImageNamespace {
-    /**
-     * Generate images from a text prompt.
-     * Costs are automatically reported to the execution context.
-     */
-    generate(options: ImageGenerationOptions): Promise<ImageGenerationResult>;
-}
-/**
- * Speech generation namespace with automatic cost reporting.
- */
-interface CostReportingSpeechNamespace {
-    /**
-     * Generate speech audio from text.
-     * Costs are automatically reported to the execution context.
-     */
-    generate(options: SpeechGenerationOptions): Promise<SpeechGenerationResult>;
-}
 interface CostReportingLLMist {
     /**
      * Quick completion - returns final text response.
@@ -3759,92 +3600,347 @@ interface HostExports {
     /** Zod schema builder */
     z: typeof zod.z;
 }
+
 /**
- * Parent agent configuration passed to gadgets.
- * Contains settings that subagents can inherit.
+ * Media output types for gadgets returning images, audio, video, or files.
+ *
+ * This module contains pure data shapes with zero cross-module dependencies.
+ * Imported by execution result types, stream event types, and execution context types.
+ *
+ * @module
  */
-interface AgentContextConfig {
-    /** Model identifier used by the parent agent */
-    model: string;
-    /** Temperature setting used by the parent agent */
-    temperature?: number;
-}
 /**
- * Configuration for a single subagent.
- * Can be defined globally in `[subagents.Name]` or per-profile in `[profile.subagents.Name]`.
- *
- * @example
- * ```toml
- * [subagents.BrowseWeb]
- * model = "inherit"      # Use parent agent's model
- * maxIterations = 20
- * headless = true
- * ```
+ * Supported media types for gadget output.
+ * Extensible via union - add new types as needed.
  */
-interface SubagentConfig {
-    /**
-     * Model to use for this subagent.
-     * - "inherit": Use parent agent's model (default behavior)
-     * - Any model ID: Use specific model (e.g., "sonnet", "haiku", "gpt-4o")
-     */
-    model?: string;
-    /** Maximum iterations for the subagent loop */
-    maxIterations?: number;
-    /** Budget limit in USD for the subagent */
-    budget?: number;
-    /**
-     * Timeout for the subagent gadget execution in milliseconds.
-     * Overrides the gadget's hardcoded timeoutMs when set.
-     * Set to 0 to disable timeout for this gadget.
-     */
-    timeoutMs?: number;
-    /**
-     * Maximum number of concurrent executions allowed for this gadget.
-     * When the limit is reached, additional calls are queued and processed
-     * as earlier executions complete (FIFO order).
-     * Set to 0 or omit to allow unlimited concurrent executions (default).
-     */
-    maxConcurrent?: number;
-    /** Additional subagent-specific options */
-    [key: string]: unknown;
-}
+type MediaKind = "image" | "audio" | "video" | "file";
 /**
- * Map of subagent names to their configurations.
+ * Type-specific metadata for media outputs.
+ * Extensible via index signature for future media types.
  */
-type SubagentConfigMap = Record<string, SubagentConfig>;
+interface MediaMetadata {
+    /** Width in pixels (images, video) */
+    width?: number;
+    /** Height in pixels (images, video) */
+    height?: number;
+    /** Duration in milliseconds (audio, video) */
+    durationMs?: number;
+    /** Allow additional metadata for future extensions */
+    [key: string]: unknown;
+}
 /**
- * Gadget execution mode controlling how multiple gadgets are executed.
- *
- * - `'parallel'` (default): Gadgets without dependencies execute concurrently (fire-and-forget).
- *   This maximizes throughput but gadgets may complete in any order.
- *
- * - `'sequential'`: Gadgets execute one at a time, each awaiting completion before the next starts.
- *   Useful for:
- *   - Gadgets with implicit ordering dependencies (e.g., file operations)
- *   - Debugging and tracing execution flow
- *   - Resource-constrained environments
- *   - Ensuring deterministic execution order
- *
- * Note: Explicit `dependsOn` relationships are always respected regardless of mode.
- * Sequential mode effectively enforces a global `maxConcurrent: 1` for all gadgets.
+ * Media output from a gadget execution.
+ * Supports images, audio, video, and arbitrary files.
  *
  * @example
  * ```typescript
- * const agent = LLMist.createAgent()
- *   .withModel("sonnet")
- *   .withGadgets(FileReader, FileWriter)
- *   .withGadgetExecutionMode('sequential')  // Execute one at a time
- *   .ask("Process files in order");
+ * // Image output
+ * const imageOutput: GadgetMediaOutput = {
+ *   kind: "image",
+ *   data: base64EncodedPng,
+ *   mimeType: "image/png",
+ *   description: "Screenshot of webpage",
+ *   metadata: { width: 1920, height: 1080 }
+ * };
  * ```
  */
-type GadgetExecutionMode = "parallel" | "sequential";
-
+interface GadgetMediaOutput {
+    /** Type of media (discriminator for type-specific handling) */
+    kind: MediaKind;
+    /** Base64-encoded media data */
+    data: string;
+    /** Full MIME type (e.g., "image/png", "audio/mp3", "video/mp4") */
+    mimeType: string;
+    /** Human-readable description of the media */
+    description?: string;
+    /** Type-specific metadata */
+    metadata?: MediaMetadata;
+    /** Optional filename to use when saving (if not provided, auto-generated) */
+    fileName?: string;
+}
 /**
- * Abstract base class for gadgets. Most users should use the `Gadget()` factory
- * or `createGadget()` function instead, as they provide better type safety
- * and simpler APIs.
+ * Stored media item with metadata and file path.
  *
- * Extend this class directly only when you need advanced control over gadget behavior.
+ * Created by MediaStore when a gadget returns media outputs.
+ * Contains the abstract ID, file path, and metadata for display.
+ */
+interface StoredMedia {
+    /** Unique ID for this media item (e.g., "media_a1b2c3") */
+    id: string;
+    /** Type of media */
+    kind: MediaKind;
+    /** Actual file path on disk (internal use) */
+    path: string;
+    /** MIME type */
+    mimeType: string;
+    /** File size in bytes */
+    sizeBytes: number;
+    /** Human-readable description */
+    description?: string;
+    /** Type-specific metadata */
+    metadata?: MediaMetadata;
+    /** Name of the gadget that created this media */
+    gadgetName: string;
+    /** When the media was stored */
+    createdAt: Date;
+}
+/**
+ * Example of gadget usage to help LLMs understand proper invocation.
+ *
+ * Examples are rendered alongside the schema in `getInstruction()` to provide
+ * concrete usage patterns for the LLM.
+ *
+ * @template TParams - Inferred parameter type from Zod schema (defaults to Record<string, unknown>)
+ *
+ * @example
+ * ```typescript
+ * const calculator = createGadget({
+ *   schema: z.object({ a: z.number(), b: z.number() }),
+ *   examples: [
+ *     { params: { a: 5, b: 3 }, output: "8", comment: "Addition example" }
+ *   ],
+ *   // ...
+ * });
+ * ```
+ */
+interface GadgetExample<TParams = Record<string, unknown>> {
+    /** Example parameter values (typed to match schema) */
+    params: TParams;
+    /** Optional expected output/result string */
+    output?: string;
+    /** Optional description explaining what this example demonstrates */
+    comment?: string;
+}
+
+/**
+ * Execution result types for gadget calls.
+ *
+ * Contains result types returned by gadget `execute()` methods and the
+ * internal result type used after execution completes.
+ *
+ * @module
+ */
+
+interface GadgetExecutionResult {
+    gadgetName: string;
+    invocationId: string;
+    parameters: Record<string, unknown>;
+    result?: string;
+    error?: string;
+    executionTimeMs: number;
+    breaksLoop?: boolean;
+    /** Cost of gadget execution in USD. Defaults to 0 if not provided by gadget. */
+    cost?: number;
+    /** Media outputs from the gadget (images, audio, video, files) */
+    media?: GadgetMediaOutput[];
+    /** Abstract IDs for media outputs (e.g., ["media_a1b2c3"]) */
+    mediaIds?: string[];
+    /** Stored media with paths (for CLI display) */
+    storedMedia?: StoredMedia[];
+}
+/**
+ * Result returned by gadget execute() method.
+ * Can be a simple string or an object with result and optional cost.
+ *
+ * @example
+ * ```typescript
+ * // Simple string return (free gadget)
+ * execute: () => "result"
+ *
+ * // Object return with cost
+ * execute: () => ({ result: "data", cost: 0.001 })
+ * ```
+ */
+interface GadgetExecuteResult {
+    /** The execution result as a string */
+    result: string;
+    /** Optional cost in USD (e.g., 0.001 for $0.001) */
+    cost?: number;
+}
+/**
+ * Extended result type with media support.
+ * Use this when gadget returns images, audio, video, or files.
+ *
+ * @example
+ * ```typescript
+ * // Return with image
+ * execute: () => ({
+ *   result: "Screenshot captured",
+ *   media: [{
+ *     kind: "image",
+ *     data: base64EncodedPng,
+ *     mimeType: "image/png",
+ *     description: "Screenshot"
+ *   }],
+ *   cost: 0.001
+ * })
+ * ```
+ */
+interface GadgetExecuteResultWithMedia {
+    /** The execution result as a string */
+    result: string;
+    /** Media outputs (images, audio, video, files) */
+    media?: GadgetMediaOutput[];
+    /** Optional cost in USD (e.g., 0.001 for $0.001) */
+    cost?: number;
+}
+/**
+ * Union type for backwards-compatible execute() return type.
+ * Gadgets can return:
+ * - string (legacy, cost = 0)
+ * - GadgetExecuteResult (result + optional cost)
+ * - GadgetExecuteResultWithMedia (result + optional media + optional cost)
+ */
+type GadgetExecuteReturn = string | GadgetExecuteResult | GadgetExecuteResultWithMedia;
+interface ParsedGadgetCall {
+    gadgetName: string;
+    invocationId: string;
+    parametersRaw: string;
+    parameters?: Record<string, unknown>;
+    parseError?: string;
+    /** List of invocation IDs this gadget depends on. Empty array if no dependencies. */
+    dependencies: string[];
+}
+
+/**
+ * Stream event types emitted during agent execution.
+ *
+ * Contains all discriminated union members for `StreamEvent`, plus
+ * `StreamCompletionEvent` and `GadgetSkippedEvent`.
+ *
+ * @module
+ */
+
+/** Event emitted when a gadget is skipped due to a failed dependency */
+interface GadgetSkippedEvent {
+    type: "gadget_skipped";
+    gadgetName: string;
+    invocationId: string;
+    parameters: Record<string, unknown>;
+    /** The invocation ID of the dependency that failed */
+    failedDependency: string;
+    /** The error message from the failed dependency */
+    failedDependencyError: string;
+}
+/**
+ * Event emitted when stream processing completes, containing metadata.
+ * This allows the async generator to "return" metadata while still yielding events.
+ */
+interface StreamCompletionEvent {
+    type: "stream_complete";
+    /** The reason the LLM stopped generating (e.g., "stop", "tool_use") */
+    finishReason: string | null;
+    /** Token usage statistics from the LLM call */
+    usage?: TokenUsage;
+    /** Raw response text from the LLM */
+    rawResponse: string;
+    /** Final message after all interceptors applied */
+    finalMessage: string;
+    /** Whether any gadgets were executed during this iteration */
+    didExecuteGadgets: boolean;
+    /** Whether to break the agent loop (e.g., TaskComplete was called) */
+    shouldBreakLoop: boolean;
+    /** Accumulated thinking/reasoning content from reasoning models */
+    thinkingContent?: string;
+}
+type StreamEvent = {
+    type: "text";
+    content: string;
+} | {
+    type: "thinking";
+    content: string;
+    thinkingType: "thinking" | "redacted";
+} | {
+    type: "gadget_call";
+    call: ParsedGadgetCall;
+} | {
+    type: "gadget_result";
+    result: GadgetExecutionResult;
+} | GadgetSkippedEvent | {
+    type: "human_input_required";
+    question: string;
+    gadgetName: string;
+    invocationId: string;
+} | {
+    type: "compaction";
+    event: CompactionEvent;
+} | {
+    type: "llm_response_end";
+    finishReason: string | null;
+    usage?: TokenUsage;
+} | StreamCompletionEvent;
+
+/**
+ * Text-only response handler types.
+ *
+ * Defines the handler configuration for when the LLM returns a text-only response
+ * (no gadget calls). Supports simple strategies, gadget triggers, and custom handlers.
+ *
+ * @module
+ */
+
+type TextOnlyHandler = TextOnlyStrategy | TextOnlyGadgetConfig | TextOnlyCustomHandler;
+/**
+ * Simple strategies for common cases
+ * - 'terminate': End the loop (default behavior)
+ * - 'acknowledge': Continue to next iteration
+ * - 'wait_for_input': Request human input
+ */
+type TextOnlyStrategy = "terminate" | "acknowledge" | "wait_for_input";
+/**
+ * Configuration for triggering a gadget when receiving text-only response
+ */
+interface TextOnlyGadgetConfig {
+    type: "gadget";
+    name: string;
+    /**
+     * Optional function to map text to gadget parameters.
+     * If not provided, text will be passed as { text: string }
+     */
+    parameterMapping?: (text: string) => Record<string, unknown>;
+}
+/**
+ * Custom handler for complex text-only response scenarios
+ */
+interface TextOnlyCustomHandler {
+    type: "custom";
+    handler: (context: TextOnlyContext) => Promise<TextOnlyAction> | TextOnlyAction;
+}
+/**
+ * Context provided to custom text-only handlers
+ */
+interface TextOnlyContext {
+    /** The complete text response from the LLM */
+    text: string;
+    /** Current iteration number */
+    iteration: number;
+    /** Full conversation history */
+    conversation: LLMMessage[];
+    /** Logger instance */
+    logger: Logger<ILogObj>;
+}
+/**
+ * Actions that can be returned by text-only handlers
+ */
+type TextOnlyAction = {
+    action: "continue";
+} | {
+    action: "terminate";
+} | {
+    action: "wait_for_input";
+    question?: string;
+} | {
+    action: "trigger_gadget";
+    name: string;
+    parameters: Record<string, unknown>;
+};
+
+/**
+ * Abstract base class for gadgets. Most users should use the `Gadget()` factory
+ * or `createGadget()` function instead, as they provide better type safety
+ * and simpler APIs.
+ *
+ * Extend this class directly only when you need advanced control over gadget behavior.
  */
 declare abstract class AbstractGadget {
     /**
@@ -4041,12 +4137,6 @@ declare abstract class AbstractGadget {
      * ```
      */
     createLinkedAbortController(ctx?: ExecutionContext): AbortController;
-    /**
-     * Auto-generated instruction text for the LLM.
-     * Combines name, description, and parameter schema into a formatted instruction.
-     * @deprecated Use getInstruction() instead
-     */
-    get instruction(): string;
     /**
      * Generate instruction text for the LLM.
      * Combines name, description, and parameter schema into a formatted instruction.
@@ -4570,6 +4660,281 @@ declare class GadgetRegistry {
     clear(): void;
 }
 
+/**
+ * Core type definitions for the Skills system.
+ *
+ * Skills follow the Agent Skills open standard (agentskills.io) — markdown-based
+ * instruction packages that extend agent capabilities through prompt injection
+ * and context management, not code execution.
+ *
+ * Three-tier progressive disclosure:
+ * - Tier 1 (metadata): ~100 tokens, always loaded for discovery
+ * - Tier 2 (instructions): <5K tokens, loaded on activation
+ * - Tier 3 (resources): unlimited, loaded on demand
+ *
+ * @module skills/types
+ */
+
+/**
+ * Parsed YAML frontmatter from a SKILL.md file.
+ * Follows the Agent Skills open standard with llmist-specific extensions.
+ */
+interface SkillMetadata {
+    /** Skill identifier. Lowercase letters, numbers, hyphens only. Max 64 chars. */
+    name: string;
+    /** What the skill does and when to use it. Max 1024 chars. Used for auto-triggering. */
+    description: string;
+    /** Hint shown during autocomplete, e.g., "[issue-number]" or "<filename> [format]". */
+    argumentHint?: string;
+    /** Tools the agent can use when this skill is active. */
+    allowedTools?: string[];
+    /** Model override when skill is active, e.g., "sonnet", "flash". */
+    model?: string;
+    /** Execution context. "fork" runs in an isolated subagent. */
+    context?: "fork" | "inline";
+    /** Subagent type for fork mode, e.g., "Explore", "Plan", "general-purpose". */
+    agent?: string;
+    /** Glob patterns for auto-activation based on files being worked on. */
+    paths?: string[];
+    /** Bundled gadget specifiers loaded when skill activates. */
+    gadgets?: string[];
+    /** If true, only the user can invoke this skill (LLM cannot auto-trigger). */
+    disableModelInvocation?: boolean;
+    /** If false, skill is background knowledge only — hidden from user invocation. */
+    userInvocable?: boolean;
+    /** Shell for !`command` preprocessing. */
+    shell?: "bash" | "powershell";
+    /** Semantic version number. */
+    version?: string;
+}
+/**
+ * A resource file within a skill's directory (Tier 3).
+ */
+interface SkillResource {
+    /** Path relative to the skill directory. */
+    relativePath: string;
+    /** Absolute path on disk. */
+    absolutePath: string;
+    /** Category based on parent directory. */
+    category: "scripts" | "references" | "assets";
+}
+/**
+ * Where a skill was discovered from.
+ */
+type SkillSource = {
+    type: "project";
+    path: string;
+} | {
+    type: "user";
+    path: string;
+} | {
+    type: "npm";
+    package: string;
+} | {
+    type: "git";
+    url: string;
+} | {
+    type: "directory";
+    path: string;
+};
+/**
+ * Fully parsed skill representation (all three tiers).
+ */
+interface ParsedSkill {
+    /** Tier 1: Always-loaded metadata from frontmatter. */
+    metadata: SkillMetadata;
+    /** Tier 2: Full SKILL.md body. null if not yet loaded. */
+    instructions: string | null;
+    /** Tier 3: Discovered resource manifests. */
+    resources: SkillResource[];
+    /** Absolute path to the SKILL.md file. */
+    sourcePath: string;
+    /** Directory containing the skill. */
+    sourceDir: string;
+    /** Origin for debugging and priority resolution. */
+    source: SkillSource;
+}
+/**
+ * Result of activating a skill.
+ */
+interface SkillActivation {
+    /** The skill that was activated. */
+    skillName: string;
+    /** Resolved instructions after $ARGUMENTS substitution and !`command` preprocessing. */
+    resolvedInstructions: string;
+    /** Gadgets made available by this skill (if any). */
+    gadgets: AbstractGadget[];
+    /** Resources loaded for this activation (Tier 3). Keyed by relative path. */
+    loadedResources: Map<string, string>;
+}
+/**
+ * Options for skill activation.
+ */
+interface SkillActivationOptions {
+    /** Arguments passed to the skill (substituted into $ARGUMENTS, $0, $1, etc.). */
+    arguments?: string;
+    /** Whether to load Tier 3 resources eagerly. Default: false. */
+    eagerResources?: boolean;
+    /** Working directory for !`command` preprocessing. */
+    cwd?: string;
+    /** Whether to execute !`command` preprocessing. Default: true. */
+    enableShellPreprocessing?: boolean;
+    /** Timeout for !`command` execution in milliseconds. Default: 10000. */
+    shellTimeoutMs?: number;
+}
+
+/**
+ * Skill class with lazy-loading progressive disclosure.
+ *
+ * Tier 1 (metadata) is always available after construction.
+ * Tier 2 (instructions) and Tier 3 (resources) are loaded on demand.
+ *
+ * @module skills/skill
+ */
+
+declare class Skill {
+    readonly metadata: SkillMetadata;
+    readonly sourcePath: string;
+    readonly sourceDir: string;
+    readonly source: SkillSource;
+    private _instructions;
+    private _resources;
+    private readonly _resourceCache;
+    private readonly _resourceLoading;
+    constructor(parsed: ParsedSkill);
+    /** Skill name for registry lookup. */
+    get name(): string;
+    /** Skill description for LLM matching. */
+    get description(): string;
+    /** Whether the LLM can auto-trigger this skill. */
+    get isModelInvocable(): boolean;
+    /** Whether the user can invoke this skill via /skill-name. */
+    get isUserInvocable(): boolean;
+    /**
+     * Load and cache Tier 2 instructions.
+     * If instructions were loaded during parsing, returns the cached value.
+     */
+    getInstructions(): Promise<string>;
+    /**
+     * List Tier 3 resources.
+     * Resources are discovered at parse time but content is loaded on demand.
+     */
+    getResources(): SkillResource[];
+    /**
+     * Load a specific Tier 3 resource by relative path.
+     * Results are cached for the lifetime of this Skill instance.
+     * Concurrent calls for the same resource share a single read.
+     */
+    getResource(relativePath: string): Promise<string>;
+    /**
+     * Activate this skill with optional arguments.
+     *
+     * Performs:
+     * 1. Variable substitution (${SKILL_DIR}, etc.)
+     * 2. Argument substitution ($ARGUMENTS, $0, $1)
+     * 3. Shell preprocessing (!`command`)
+     * 4. Resource loading (if eagerResources is true)
+     */
+    activate(options?: SkillActivationOptions): Promise<SkillActivation>;
+    /**
+     * Create a Skill from a SKILL.md content string.
+     * Useful for testing or dynamic skill creation.
+     */
+    static fromContent(content: string, sourcePath: string, source?: SkillSource): Skill;
+}
+
+/**
+ * SkillRegistry — manages skill discovery, lookup, and metadata summaries.
+ *
+ * Parallel to GadgetRegistry but with different semantics: skills are not
+ * executable tools registered with the LLM directly. They are available
+ * for activation by the agent or user, surfaced via metadata summaries.
+ *
+ * @module skills/registry
+ */
+
+declare class SkillRegistry {
+    private readonly skills;
+    /**
+     * Register a skill. Overwrites any existing skill with the same name.
+     *
+     * Unlike GadgetRegistry (which throws on duplicates), SkillRegistry allows
+     * overwriting because skills are loaded from multiple sources with intentional
+     * priority ordering (project > user > default).
+     */
+    register(skill: Skill): void;
+    /** Register multiple skills. */
+    registerMany(skills: Skill[]): void;
+    /** Remove a skill by name (case-insensitive). Returns true if removed. */
+    remove(name: string): boolean;
+    /** Remove all registered skills. */
+    clear(): void;
+    /** Get a skill by name (case-insensitive). */
+    get(name: string): Skill | undefined;
+    /** Check if a skill exists by name (case-insensitive). */
+    has(name: string): boolean;
+    /** Get all registered skills. */
+    getAll(): Skill[];
+    /** Get all skill names. */
+    getNames(): string[];
+    /** Number of registered skills. */
+    get size(): number;
+    /**
+     * Get skills that are visible to the LLM for auto-triggering.
+     * Excludes skills with disableModelInvocation: true.
+     */
+    getModelInvocable(): Skill[];
+    /**
+     * Get skills that the user can invoke via /skill-name.
+     * Excludes skills with userInvocable: false.
+     */
+    getUserInvocable(): Skill[];
+    /**
+     * Generate metadata summaries for system prompt injection (Tier 1).
+     *
+     * Each skill contributes a one-line summary: "name — description".
+     * Output is truncated to fit the character budget.
+     *
+     * @param charBudget - Maximum characters for all summaries combined.
+     */
+    getMetadataSummaries(charBudget?: number): string;
+    /**
+     * Find skills whose `paths` patterns match a given file path.
+     * Used for auto-activation when the user is working on specific files.
+     */
+    findByFilePath(filePath: string): Skill[];
+    /**
+     * Merge another registry into this one.
+     * Skills from the other registry overwrite existing skills with the same name.
+     */
+    merge(other: SkillRegistry): void;
+    /** Create a registry from an array of skills. */
+    static from(skills: Skill[]): SkillRegistry;
+}
+
+/**
+ * Context available to trailing message functions.
+ * Provides iteration information for dynamic message generation.
+ */
+type TrailingMessageContext = Pick<LLMCallControllerContext, "iteration" | "maxIterations" | "budget" | "totalCost">;
+/**
+ * Trailing message can be a static string or a function that generates the message.
+ * The function receives context about the current iteration.
+ */
+type TrailingMessage = string | ((ctx: TrailingMessageContext) => string);
+
+/**
+ * Message for conversation history.
+ * User messages can be text (string) or multimodal (ContentPart[]).
+ */
+type HistoryMessage = {
+    user: string | ContentPart[];
+} | {
+    assistant: string;
+} | {
+    system: string;
+};
+
 /**
  * Event handler sugar for cleaner event processing.
  *
@@ -4681,43 +5046,8 @@ declare function collectText(agentGenerator: AsyncGenerator<StreamEvent>): Promi
 
 /**
  * Fluent builder for creating agents with delightful DX.
- *
- * @example
- * ```typescript
- * const agent = await LLMist.createAgent()
- *   .withModel("sonnet")
- *   .withSystem("You are a helpful assistant")
- *   .withGadgets(Calculator, Weather)
- *   .withMaxIterations(10)
- *   .ask("What's the weather in Paris?");
- *
- * for await (const event of agent.run()) {
- *   // process events
- * }
- * ```
  */
 
-/**
- * Message for conversation history.
- * User messages can be text (string) or multimodal (ContentPart[]).
- */
-type HistoryMessage = {
-    user: string | ContentPart[];
-} | {
-    assistant: string;
-} | {
-    system: string;
-};
-/**
- * Context available to trailing message functions.
- * Provides iteration information for dynamic message generation.
- */
-type TrailingMessageContext = Pick<LLMCallControllerContext, "iteration" | "maxIterations" | "budget" | "totalCost">;
-/**
- * Trailing message can be a static string or a function that generates the message.
- * The function receives context about the current iteration.
- */
-type TrailingMessage = string | ((ctx: TrailingMessageContext) => string);
 /**
  * Fluent builder for creating agents.
  *
@@ -4725,921 +5055,126 @@ type TrailingMessage = string | ((ctx: TrailingMessageContext) => string);
  * making the code more expressive and easier to read.
  */
 declare class AgentBuilder {
-    private client?;
-    private model?;
-    private systemPrompt?;
-    private temperature?;
-    private maxIterations?;
-    private budget?;
-    private logger?;
-    private hooks?;
-    private promptConfig?;
+    private core;
     private gadgets;
-    private initialMessages;
-    private requestHumanInput?;
-    private gadgetStartPrefix?;
-    private gadgetEndPrefix?;
-    private gadgetArgPrefix?;
-    private textOnlyHandler?;
-    private textWithGadgetsHandler?;
-    private defaultGadgetTimeoutMs?;
-    private gadgetExecutionMode?;
-    private maxGadgetsPerResponse?;
-    private gadgetOutputLimit?;
-    private gadgetOutputLimitPercent?;
-    private compactionConfig?;
-    private retryConfig?;
-    private rateLimitConfig?;
-    private signal?;
-    private trailingMessage?;
-    private subagentConfig?;
-    private parentContext?;
-    private parentObservers?;
-    private sharedRateLimitTracker?;
-    private sharedRetryConfig?;
-    private reasoningConfig?;
-    private cachingConfig?;
+    private retry;
+    private subagents;
+    private policies;
+    private skills;
     constructor(client?: LLMist);
-    /**
-     * Set the model to use.
-     * Supports aliases like "gpt4", "sonnet", "flash".
-     *
-     * @param model - Model name or alias
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * .withModel("sonnet")           // Alias
-     * .withModel("gpt-5-nano")       // Auto-detects provider
-     * .withModel("openai:gpt-5")     // Explicit provider
-     * ```
-     */
+    /** Set the model to use. Supports aliases like "sonnet", "flash". */
     withModel(model: string): this;
-    /**
-     * Set the system prompt.
-     *
-     * @param prompt - System prompt
-     * @returns This builder for chaining
-     */
+    /** Set the system prompt. */
     withSystem(prompt: string): this;
-    /**
-     * Set the temperature (0-1).
-     *
-     * @param temperature - Temperature value
-     * @returns This builder for chaining
-     */
+    /** Set the temperature (0-1). */
     withTemperature(temperature: number): this;
-    /**
-     * Set maximum iterations.
-     *
-     * @param max - Maximum number of iterations
-     * @returns This builder for chaining
-     */
+    /** Set maximum iterations. */
     withMaxIterations(max: number): this;
-    /**
-     * Set the budget limit in USD.
-     * The agent loop stops when cumulative cost reaches this limit.
-     *
-     * @param amountUSD - Maximum spend in USD
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * .withBudget(0.50)  // Stop after $0.50 spent
-     * ```
-     */
+    /** Set the budget limit in USD. */
     withBudget(amountUSD: number): this;
-    /**
-     * Set logger instance.
-     *
-     * @param logger - Logger instance
-     * @returns This builder for chaining
-     */
-    withLogger(logger: Logger<ILogObj>): this;
-    /**
-     * Add hooks for agent lifecycle events.
-     *
-     * @param hooks - Agent hooks configuration
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * import { HookPresets } from 'llmist/hooks';
-     *
-     * .withHooks(HookPresets.logging())
-     * .withHooks(HookPresets.merge(
-     *   HookPresets.logging(),
-     *   HookPresets.timing()
-     * ))
-     * ```
-     */
-    withHooks(hooks: AgentHooks): this;
-    /**
-     * Configure custom prompts for gadget system messages.
-     *
-     * @param config - Prompt configuration object
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * .withPromptTemplateConfig({
-     *   mainInstruction: "Use the gadget markers below:",
-     *   rules: ["Always use markers", "Never use function calling"]
-     * })
-     * ```
-     */
-    withPromptTemplateConfig(config: PromptTemplateConfig): this;
-    /**
-     * Add gadgets (classes or instances).
-     * Can be called multiple times to add more gadgets.
-     *
-     * @param gadgets - Gadget classes or instances
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * .withGadgets(Calculator, Weather, Email)
-     * .withGadgets(new Calculator(), new Weather())
-     * .withGadgets(createGadget({ ... }))
-     * ```
-     */
-    withGadgets(...gadgets: GadgetOrClass[]): this;
-    /**
-     * Add conversation history messages.
-     * Useful for continuing previous conversations.
-     *
-     * @param messages - Array of history messages
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * .withHistory([
-     *   { user: "Hello" },
-     *   { assistant: "Hi there!" },
-     *   { user: "How are you?" },
-     *   { assistant: "I'm doing well, thanks!" }
-     * ])
-     * ```
-     */
-    withHistory(messages: HistoryMessage[]): this;
-    /**
-     * Add a single message to the conversation history.
-     *
-     * @param message - Single history message
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * .addMessage({ user: "Hello" })
-     * .addMessage({ assistant: "Hi there!" })
-     * ```
-     */
+    /** Set logger instance. */
+    withLogger(logger: Logger<ILogObj>): this;
+    /** Add hooks for agent lifecycle events. */
+    withHooks(hooks: AgentHooks): this;
+    /** Configure custom prompts for gadget system messages. */
+    withPromptTemplateConfig(config: PromptTemplateConfig): this;
+    /** Add gadgets (classes or instances). */
+    withGadgets(...gadgets: GadgetOrClass[]): this;
+    /** Add conversation history messages. */
+    withHistory(messages: HistoryMessage[]): this;
+    /** Add a single message to the conversation history. */
     addMessage(message: HistoryMessage): this;
-    /**
-     * Clear any previously set conversation history.
-     * Used before setting new cumulative history in REPL mode.
-     *
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * // Reset history before setting new cumulative history
-     * builder.clearHistory().withHistory(cumulativeHistory);
-     * ```
-     */
+    /** Clear any previously set conversation history. */
     clearHistory(): this;
-    /**
-     * Continue conversation from a previous agent's history.
-     * Extracts full conversation history and sets it as initial messages.
-     *
-     * This is the recommended way to implement REPL session continuation.
-     * It automatically handles history extraction and format conversion.
-     *
-     * @param agent - The previous agent to continue from
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * // REPL loop with session continuity
-     * let previousAgent: Agent | null = null;
-     *
-     * while (true) {
-     *   if (previousAgent) {
-     *     builder.continueFrom(previousAgent);
-     *   }
-     *   const agent = builder.ask(prompt);
-     *   await runAgent(agent);
-     *   previousAgent = agent;
-     * }
-     * ```
-     */
+    /** Continue conversation from a previous agent's history. */
     continueFrom(agent: Agent): this;
-    /**
-     * Set the human input handler for interactive conversations.
-     *
-     * @param handler - Function to handle human input requests
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * .onHumanInput(async (question) => {
-     *   return await promptUser(question);
-     * })
-     * ```
-     */
+    /** Set the human input handler for interactive conversations. */
     onHumanInput(handler: (question: string) => Promise<string>): this;
-    /**
-     * Set custom gadget marker prefix.
-     *
-     * @param prefix - Custom start prefix for gadget markers
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * .withGadgetStartPrefix("<<GADGET_START>>")
-     * ```
-     */
+    /** Set custom gadget marker prefix. */
     withGadgetStartPrefix(prefix: string): this;
-    /**
-     * Set custom gadget marker suffix.
-     *
-     * @param suffix - Custom end suffix for gadget markers
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * .withGadgetEndPrefix("<<GADGET_END>>")
-     * ```
-     */
+    /** Set custom gadget marker suffix. */
     withGadgetEndPrefix(suffix: string): this;
-    /**
-     * Set custom argument prefix for block format parameters.
-     *
-     * @param prefix - Custom prefix for argument markers (default: "!!!ARG:")
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * .withGadgetArgPrefix("<<ARG>>")
-     * ```
-     */
+    /** Set custom argument prefix for block format parameters. */
     withGadgetArgPrefix(prefix: string): this;
-    /**
-     * Set the text-only handler strategy.
-     *
-     * Controls what happens when the LLM returns text without calling any gadgets:
-     * - "terminate": End the agent loop (default)
-     * - "acknowledge": Continue the loop for another iteration
-     * - "wait_for_input": Wait for human input
-     * - Custom handler: Provide a function for dynamic behavior
-     *
-     * @param handler - Text-only handler strategy or custom handler
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * // Simple strategy
-     * .withTextOnlyHandler("acknowledge")
-     *
-     * // Custom handler
-     * .withTextOnlyHandler({
-     *   type: "custom",
-     *   handler: async (context) => {
-     *     if (context.text.includes("?")) {
-     *       return { action: "wait_for_input", question: context.text };
-     *     }
-     *     return { action: "continue" };
-     *   }
-     * })
-     * ```
-     */
+    /** Set the text-only handler strategy. */
     withTextOnlyHandler(handler: TextOnlyHandler): this;
-    /**
-     * Set the handler for text content that appears alongside gadget calls.
-     *
-     * When set, text accompanying gadget responses will be wrapped as a
-     * synthetic gadget call before the actual gadget results in the
-     * conversation history.
-     *
-     * @param handler - Configuration for wrapping text
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * // Wrap text as TellUser gadget
-     * .withTextWithGadgetsHandler({
-     *   gadgetName: "TellUser",
-     *   parameterMapping: (text) => ({ message: text, done: false, type: "info" }),
-     *   resultMapping: (text) => `ℹ️  ${text}`,
-     * })
-     * ```
-     */
+    /** Set the handler for text content that appears alongside gadget calls. */
     withTextWithGadgetsHandler(handler: {
         gadgetName: string;
         parameterMapping: (text: string) => Record<string, unknown>;
         resultMapping?: (text: string) => string;
     }): this;
-    /**
-     * Set default timeout for gadget execution.
-     *
-     * @param timeoutMs - Timeout in milliseconds (must be non-negative)
-     * @returns This builder for chaining
-     * @throws {Error} If timeout is negative
-     *
-     * @example
-     * ```typescript
-     * .withDefaultGadgetTimeout(5000) // 5 second timeout
-     * ```
-     */
+    /** Set default timeout for gadget execution. */
     withDefaultGadgetTimeout(timeoutMs: number): this;
-    /**
-     * Set the gadget execution mode.
-     *
-     * Controls how multiple gadgets are executed when the LLM calls them:
-     * - `'parallel'` (default): Gadgets without dependencies execute concurrently
-     * - `'sequential'`: Gadgets execute one at a time, each awaiting completion
-     *
-     * @param mode - Execution mode ('parallel' or 'sequential')
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * // Sequential execution for ordered file operations
-     * .withGadgetExecutionMode('sequential')
-     *
-     * // Parallel execution (default) for independent operations
-     * .withGadgetExecutionMode('parallel')
-     * ```
-     */
+    /** Set the gadget execution mode ('parallel' or 'sequential'). */
     withGadgetExecutionMode(mode: GadgetExecutionMode): this;
-    /**
-     * Set the maximum number of gadgets to execute per LLM response.
-     *
-     * When the limit is reached, remaining gadgets are skipped with an informative
-     * message visible to the LLM, allowing it to adjust on the next iteration.
-     * Gadgets already in-flight (executing in parallel) are allowed to complete.
-     *
-     * @param max - Maximum gadgets per response (0 = unlimited, default)
-     * @returns This builder for chaining
-     * @throws {Error} If max is negative or non-integer
-     *
-     * @example
-     * ```typescript
-     * // Limit to 5 gadgets per response
-     * LLMist.createAgent()
-     *   .withModel("sonnet")
-     *   .withGadgets(ReadFile, WriteFile, Search)
-     *   .withMaxGadgetsPerResponse(5)
-     *   .ask("Process these files...");
-     * ```
-     */
+    /** Set the maximum number of gadgets to execute per LLM response. */
     withMaxGadgetsPerResponse(max: number): this;
-    /**
-     * Enable or disable gadget output limiting.
-     *
-     * When enabled, gadget outputs exceeding the configured limit are stored
-     * and can be browsed using the GadgetOutputViewer gadget.
-     *
-     * @param enabled - Whether to enable output limiting (default: true)
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * .withGadgetOutputLimit(false) // Disable output limiting
-     * ```
-     */
+    /** Enable or disable gadget output limiting. */
     withGadgetOutputLimit(enabled: boolean): this;
-    /**
-     * Set the maximum gadget output as a percentage of the model's context window.
-     *
-     * Outputs exceeding this limit are stored for later browsing with GadgetOutputViewer.
-     *
-     * @param percent - Percentage of context window (1-100, default: 15)
-     * @returns This builder for chaining
-     * @throws {Error} If percent is not between 1 and 100
-     *
-     * @example
-     * ```typescript
-     * .withGadgetOutputLimitPercent(25) // 25% of context window
-     * ```
-     */
+    /** Set the maximum gadget output as a percentage of the context window. */
     withGadgetOutputLimitPercent(percent: number): this;
-    /**
-     * Configure context compaction.
-     *
-     * Context compaction automatically manages conversation history to prevent
-     * context window overflow in long-running agent conversations.
-     *
-     * @param config - Compaction configuration options
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * // Custom thresholds
-     * .withCompaction({
-     *   triggerThresholdPercent: 70,
-     *   targetPercent: 40,
-     *   preserveRecentTurns: 10,
-     * })
-     *
-     * // Different strategy
-     * .withCompaction({
-     *   strategy: 'sliding-window',
-     * })
-     *
-     * // With callback
-     * .withCompaction({
-     *   onCompaction: (event) => {
-     *     console.log(`Saved ${event.tokensBefore - event.tokensAfter} tokens`);
-     *   }
-     * })
-     * ```
-     */
+    /** Configure context compaction. */
     withCompaction(config: CompactionConfig): this;
-    /**
-     * Disable context compaction.
-     *
-     * By default, compaction is enabled. Use this method to explicitly disable it.
-     *
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * .withoutCompaction() // Disable automatic compaction
-     * ```
-     */
+    /** Disable context compaction. */
     withoutCompaction(): this;
+    /** Register a skill registry for this agent. */
+    withSkills(registry: SkillRegistry): this;
     /**
-     * Configure retry behavior for LLM API calls.
-     *
-     * Retry is enabled by default with conservative settings (3 retries, exponential backoff).
-     * Use this method to customize retry behavior for rate limits, timeouts, and transient errors.
-     *
-     * @param config - Retry configuration options
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * // Custom retry configuration
-     * .withRetry({
-     *   retries: 5,
-     *   minTimeout: 2000,
-     *   maxTimeout: 60000,
-     * })
-     *
-     * // With monitoring callbacks
-     * .withRetry({
-     *   onRetry: (error, attempt) => {
-     *     console.log(`Retry ${attempt}: ${error.message}`);
-     *   },
-     *   onRetriesExhausted: (error, attempts) => {
-     *     alerting.warn(`Failed after ${attempts} attempts`);
-     *   }
-     * })
-     *
-     * // Custom retry logic
-     * .withRetry({
-     *   shouldRetry: (error) => error.message.includes('429'),
-     * })
-     * ```
-     */
-    withRetry(config: RetryConfig): this;
-    /**
-     * Disable automatic retry for LLM API calls.
-     *
-     * By default, retry is enabled. Use this method to explicitly disable it.
-     *
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * .withoutRetry() // Disable automatic retry
-     * ```
-     */
-    withoutRetry(): this;
-    /**
-     * Configure proactive rate limiting to prevent rate limit errors.
-     *
-     * Set limits based on your API tier to automatically throttle requests
-     * before hitting provider limits. Works in conjunction with reactive
-     * retry/backoff for comprehensive rate limit handling.
-     *
-     * @param config - Rate limit configuration
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * // Gemini free tier limits
-     * .withRateLimits({
-     *   requestsPerMinute: 15,
-     *   tokensPerMinute: 1_000_000,
-     *   safetyMargin: 0.8,  // Start throttling at 80%
-     * })
-     *
-     * // OpenAI Tier 1 limits
-     * .withRateLimits({
-     *   requestsPerMinute: 500,
-     *   tokensPerMinute: 200_000,
-     * })
-     *
-     * // With daily limit (Gemini free tier)
-     * .withRateLimits({
-     *   requestsPerMinute: 15,
-     *   tokensPerDay: 1_500_000,
-     * })
-     * ```
-     */
-    withRateLimits(config: RateLimitConfig): this;
-    /**
-     * Set an abort signal for cancelling requests mid-flight.
-     *
-     * When the signal is aborted, the current LLM request will be cancelled
-     * and the agent loop will exit gracefully.
-     *
-     * @param signal - AbortSignal from an AbortController
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * const controller = new AbortController();
-     *
-     * // Cancel after 30 seconds
-     * setTimeout(() => controller.abort(), 30000);
-     *
-     * const agent = LLMist.createAgent()
-     *   .withModel("sonnet")
-     *   .withSignal(controller.signal)
-     *   .ask("Write a long story");
-     *
-     * // Or cancel on user action
-     * document.getElementById("cancel").onclick = () => controller.abort();
-     * ```
-     */
-    withSignal(signal: AbortSignal): this;
-    /**
-     * Enable reasoning/thinking mode for reasoning-capable models.
-     *
-     * Can be called with:
-     * - No args: enables reasoning at "medium" effort
-     * - A string effort level: `withReasoning("high")`
-     * - A full config object: `withReasoning({ enabled: true, budgetTokens: 10000 })`
-     *
-     * @param config - Optional effort level or full reasoning config
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * // Simple — medium effort
-     * LLMist.createAgent()
-     *   .withModel("o3")
-     *   .withReasoning()
-     *   .ask("Solve this logic puzzle...");
-     *
-     * // Explicit effort level
-     * LLMist.createAgent()
-     *   .withModel("anthropic:claude-4-opus")
-     *   .withReasoning("high")
-     *   .ask("Analyze this complex problem");
-     *
-     * // Full config with explicit token budget
-     * LLMist.createAgent()
-     *   .withModel("anthropic:claude-4-opus")
-     *   .withReasoning({ enabled: true, budgetTokens: 16000 })
-     *   .ask("Step through this proof");
-     * ```
-     */
-    withReasoning(config?: ReasoningConfig | ReasoningEffort): this;
-    /**
-     * Explicitly disable reasoning for this agent, even if the model supports it.
-     *
-     * By default, reasoning is auto-enabled at "medium" effort for models with
-     * `features.reasoning: true`. Use this to opt out.
-     *
-     * @returns This builder for chaining
-     */
-    withoutReasoning(): this;
-    /**
-     * Enable context caching for supported providers.
-     *
-     * Can be called with:
-     * - No args: enables caching with defaults (`{ enabled: true }`)
-     * - A full config object: `withCaching({ enabled: true, scope: "system", ttl: "7200s" })`
-     *
-     * Provider behavior:
-     * - **Anthropic**: Caching is always-on by default via `cache_control` markers.
-     *   Calling `withCaching()` explicitly is a no-op (it's already enabled).
-     * - **Gemini**: Creates an explicit cache via `caches.create()` for the configured scope.
-     * - **OpenAI**: Server-side automatic caching (no-op).
-     *
-     * @param config - Optional caching configuration
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * // Simple — enable with defaults
-     * LLMist.createAgent()
-     *   .withModel("gemini:gemini-2.5-flash")
-     *   .withCaching()
-     *   .ask("Analyze this large codebase...");
-     *
-     * // Cache only system prompt with longer TTL
-     * LLMist.createAgent()
-     *   .withModel("gemini:gemini-2.5-pro")
-     *   .withCaching({ enabled: true, scope: "system", ttl: "7200s" })
-     *   .ask("...");
-     * ```
-     */
-    withCaching(config?: CachingConfig): this;
-    /**
-     * Explicitly disable context caching.
-     *
-     * For Anthropic, this removes `cache_control` markers from requests,
-     * opting out of prompt caching entirely.
-     *
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * // Disable Anthropic's automatic caching
-     * LLMist.createAgent()
-     *   .withModel("sonnet")
-     *   .withoutCaching()
-     *   .ask("...");
-     * ```
-     */
-    withoutCaching(): this;
-    /**
-     * Set subagent configuration overrides.
-     *
-     * Subagent gadgets (like BrowseWeb) can read these settings from ExecutionContext
-     * to inherit model and other options from the CLI configuration.
-     *
-     * @param config - Subagent configuration map keyed by gadget name
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * .withSubagentConfig({
-     *   BrowseWeb: { model: "inherit", maxIterations: 20, headless: true },
-     *   CodeAnalyzer: { model: "sonnet", maxIterations: 10 }
-     * })
-     * ```
-     */
-    withSubagentConfig(config: SubagentConfigMap): this;
-    /**
-     * Share parent agent's ExecutionTree for unified event visibility.
-     *
-     * When building a subagent inside a gadget, call this method to share the
-     * parent's ExecutionTree. This is the **single source of truth** for all
-     * execution events, enabling:
-     *
-     * - **Unified cost tracking** - All nested agent costs aggregate automatically
-     * - **Real-time visibility** - Parent's `tree.onAll()` subscribers see all events
-     * - **Depth tracking** - Events have correct `depth` (1 for child, 2 for grandchild, etc.)
-     * - **Parent linking** - Events have `parentId` pointing to spawning gadget
-     * - **Media aggregation** - Use `tree.getSubtreeMedia(nodeId)` after completion
-     *
-     * **Signal Forwarding** - When parent context includes a signal, it's automatically
-     * forwarded to the subagent for proper cancellation propagation.
-     *
-     * **Logger Inheritance** - When parent context includes a logger, it's inherited
-     * by the subagent for consistent structured logging.
-     *
-     * @param ctx - ExecutionContext passed to the gadget's execute() method
-     * @param depth - Nesting depth (default: 1 for direct child)
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * // In a subagent gadget like BrowseWeb:
-     * execute: async (params, ctx) => {
-     *   const agent = new AgentBuilder(client)
-     *     .withModel(model)
-     *     .withGadgets(Navigate, Click, Screenshot)
-     *     .withParentContext(ctx)  // <-- Shares parent's tree
-     *     .ask(params.task);
-     *
-     *   for await (const event of agent.run()) {
-     *     // Events automatically flow through shared tree
-     *     if (event.type === "text") {
-     *       result = event.content;
-     *     }
-     *   }
-     *
-     *   // After subagent completes, access aggregated data:
-     *   const totalCost = ctx.tree?.getSubtreeCost(ctx.nodeId!);
-     *   const allMedia = ctx.tree?.getSubtreeMedia(ctx.nodeId!);
-     * }
-     * ```
-     */
-    withParentContext(ctx: ExecutionContext, depth?: number): this;
-    /**
-     * Add an ephemeral trailing message that appears at the end of each LLM request.
+     * Pre-activate a specific skill before the agent starts.
+     * Instructions are injected into the system prompt.
      *
-     * The message is NOT persisted to conversation history - it only appears in the
-     * current LLM call. This is useful for injecting context-specific instructions
-     * or reminders without polluting the conversation history.
-     *
-     * @param message - Static string or function that generates the message
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * // Static message
-     * .withTrailingMessage("Always respond in JSON format.")
-     *
-     * // Dynamic message based on iteration
-     * .withTrailingMessage((ctx) =>
-     *   `[Iteration ${ctx.iteration}/${ctx.maxIterations}] Stay focused on the task.`
-     * )
-     * ```
+     * Note: each call replaces (not appends) the pre-activated skill for that name.
+     * This is safe for REPL loops where the same builder is reused.
      */
+    withSkill(name: string, args?: string): this;
+    /** Clear all pre-activated skills. Call between REPL iterations. */
+    clearPreActivatedSkills(): this;
+    /** Add a directory to scan for skills. */
+    withSkillsFrom(dir: string): this;
+    /** Configure retry behavior for LLM API calls. */
+    withRetry(config: RetryConfig): this;
+    /** Disable automatic retry for LLM API calls. */
+    withoutRetry(): this;
+    /** Configure proactive rate limiting to prevent rate limit errors. */
+    withRateLimits(config: RateLimitConfig): this;
+    /** Set an abort signal for cancelling requests mid-flight. */
+    withSignal(signal: AbortSignal): this;
+    /** Enable reasoning/thinking mode for reasoning-capable models. */
+    withReasoning(config?: ReasoningConfig | ReasoningEffort): this;
+    /** Explicitly disable reasoning for this agent. */
+    withoutReasoning(): this;
+    /** Enable context caching for supported providers. */
+    withCaching(config?: CachingConfig): this;
+    /** Explicitly disable context caching. */
+    withoutCaching(): this;
+    /** Set subagent configuration overrides. */
+    withSubagentConfig(config: SubagentConfigMap): this;
+    /** Share parent agent's ExecutionTree for unified event visibility. */
+    withParentContext(ctx: ExecutionContext, depth?: number): this;
+    /** Add an ephemeral trailing message that appears at the end of each LLM request. */
     withTrailingMessage(message: TrailingMessage): this;
-    /**
-     * Add a synthetic gadget call to the conversation history.
-     *
-     * This is useful for in-context learning - showing the LLM what "past self"
-     * did correctly so it mimics the pattern. The call is formatted with proper
-     * markers and parameter format, including the invocation ID so the LLM can
-     * reference previous calls when building dependencies.
-     *
-     * @param gadgetName - Name of the gadget
-     * @param parameters - Parameters passed to the gadget
-     * @param result - Result returned by the gadget
-     * @param invocationId - Invocation ID (shown to LLM so it can reference for dependencies)
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * .withSyntheticGadgetCall(
-     *   'TellUser',
-     *   {
-     *     message: '👋 Hello!\n\nHere\'s what I can do:\n- Analyze code\n- Run commands',
-     *     done: false,
-     *     type: 'info'
-     *   },
-     *   'ℹ️  👋 Hello!\n\nHere\'s what I can do:\n- Analyze code\n- Run commands',
-     *   'gc_1'
-     * )
-     * ```
-     */
+    /** Add a synthetic gadget call to the conversation history for in-context learning. */
     withSyntheticGadgetCall(gadgetName: string, parameters: Record<string, unknown>, result: string, invocationId: string): this;
-    /**
-     * Compose the final hooks, including trailing message injection if configured.
-     *
-     * Note: Subagent event visibility is now handled entirely by the ExecutionTree.
-     * When a subagent uses withParentContext(ctx), it shares the parent's tree,
-     * and all events are automatically visible to tree subscribers (like the TUI).
-     *
-     * Environment-based file logging (via LLMIST_LOG_RAW_DIRECTORY) is automatically
-     * injected if the env var is set. User-provided hooks take precedence.
-     */
     private composeHooks;
+    private resolveSkillRegistry;
     /**
-     * Format parameters as block format with JSON Pointer paths.
-     */
-    private formatBlockParameters;
-    /**
-     * Build and create the agent with the given user prompt.
-     * Returns the Agent instance ready to run.
-     *
-     * @param userPrompt - User's question or request
-     * @returns Configured Agent instance
-     *
-     * @example
-     * ```typescript
-     * const agent = await LLMist.createAgent()
-     *   .withModel("sonnet")
-     *   .withGadgets(Calculator)
-     *   .ask("What is 2+2?");
-     *
-     * for await (const event of agent.run()) {
-     *   // handle events
-     * }
-     * ```
-     */
-    /**
-     * Build AgentOptions with the given user prompt.
-     * Centralizes options construction for ask(), askWithImage(), askWithContent(), and build().
-     *
-     * @param userPrompt - Optional user prompt (omitted for build() which has no prompt)
+     * Resolve pre-activated skill instructions synchronously.
+     * Reads SKILL.md from disk via readFileSync (skills are local files).
      */
+    private resolvePreActivatedInstructions;
     private buildAgentOptions;
+    /** Create agent and start with a user prompt. */
     ask(userPrompt: string): Agent;
-    /**
-     * Build and create the agent with a multimodal user prompt (text + image).
-     * Returns the Agent instance ready to run.
-     *
-     * @param textPrompt - Text prompt describing what to do with the image
-     * @param imageData - Image data (Buffer, Uint8Array, or base64 string)
-     * @param mimeType - Optional MIME type (auto-detected if not provided)
-     * @returns Configured Agent instance
-     *
-     * @example
-     * ```typescript
-     * const agent = LLMist.createAgent()
-     *   .withModel("gpt-4o")
-     *   .withSystem("You analyze images")
-     *   .askWithImage(
-     *     "What's in this image?",
-     *     await fs.readFile("photo.jpg")
-     *   );
-     *
-     * for await (const event of agent.run()) {
-     *   // handle events
-     * }
-     * ```
-     */
+    /** Create agent with multimodal input (text + image). */
     askWithImage(textPrompt: string, imageData: Buffer | Uint8Array | string, mimeType?: ImageMimeType): Agent;
-    /**
-     * Build and return an Agent configured with multimodal content.
-     * More flexible than askWithImage - accepts any combination of content parts.
-     *
-     * @param content - Array of content parts (text, images, audio)
-     * @returns A configured Agent ready for execution
-     *
-     * @example
-     * ```typescript
-     * import { text, imageFromBuffer, audioFromBuffer } from "llmist";
-     *
-     * const agent = LLMist.createAgent()
-     *   .withModel("gemini:gemini-2.5-flash")
-     *   .askWithContent([
-     *     text("Describe this image and transcribe the audio:"),
-     *     imageFromBuffer(imageData),
-     *     audioFromBuffer(audioData),
-     *   ]);
-     *
-     * for await (const event of agent.run()) {
-     *   // handle events
-     * }
-     * ```
-     */
+    /** Create agent with flexible multimodal content parts. */
     askWithContent(content: ContentPart[]): Agent;
-    /**
-     * Build, run, and collect only the text response.
-     * Convenient for simple queries where you just want the final answer.
-     *
-     * @param userPrompt - User's question or request
-     * @returns Promise resolving to the complete text response
-     *
-     * @example
-     * ```typescript
-     * const answer = await LLMist.createAgent()
-     *   .withModel("gpt4-mini")
-     *   .withGadgets(Calculator)
-     *   .askAndCollect("What is 42 * 7?");
-     *
-     * console.log(answer); // "294"
-     * ```
-     */
+    /** Run agent and collect text response. */
     askAndCollect(userPrompt: string): Promise<string>;
-    /**
-     * Build and run with event handlers.
-     * Combines agent creation and event handling in one call.
-     *
-     * @param userPrompt - User's question or request
-     * @param handlers - Event handlers
-     *
-     * @example
-     * ```typescript
-     * await LLMist.createAgent()
-     *   .withModel("sonnet")
-     *   .withGadgets(Calculator)
-     *   .askWith("What is 2+2?", {
-     *     onText: (text) => console.log("LLM:", text),
-     *     onGadgetResult: (result) => console.log("Result:", result.result),
-     *   });
-     * ```
-     */
+    /** Run agent with event handlers. */
     askWith(userPrompt: string, handlers: EventHandlers): Promise<void>;
-    /**
-     * Build the agent without a user prompt.
-     *
-     * Returns an Agent instance that can be inspected (e.g., check registered gadgets)
-     * but cannot be run without first calling .ask(prompt).
-     *
-     * This is useful for:
-     * - Testing: Inspect the registry, configuration, etc.
-     * - Advanced use cases: Build agent configuration separately from execution
-     *
-     * @returns Configured Agent instance (without user prompt)
-     *
-     * @example
-     * ```typescript
-     * // Build agent for inspection
-     * const agent = new AgentBuilder()
-     *   .withModel("sonnet")
-     *   .withGadgets(Calculator, Weather)
-     *   .build();
-     *
-     * // Inspect registered gadgets
-     * console.log(agent.getRegistry().getNames()); // ['Calculator', 'Weather']
-     *
-     * // Note: Calling agent.run() will throw an error
-     * // Use .ask(prompt) instead if you want to run the agent
-     * ```
-     */
+    /** Build agent without a prompt (useful for testing/inspection). */
     build(): Agent;
 }
 
@@ -6258,6 +5793,109 @@ interface IConversationManager {
     getConversationHistory(): LLMMessage[];
 }
 
+/**
+ * Storage for large gadget outputs that exceed the configured limit.
+ *
+ * When a gadget returns more data than the configured limit, the output
+ * is stored here and can be browsed later using GadgetOutputViewer.
+ */
+/**
+ * Metadata and content for a stored gadget output.
+ */
+interface StoredOutput {
+    /** Unique identifier (e.g., "Search_d34db33f") */
+    id: string;
+    /** Name of the gadget that produced this output */
+    gadgetName: string;
+    /** Full output content */
+    content: string;
+    /** Size in bytes */
+    byteSize: number;
+    /** Number of lines */
+    lineCount: number;
+    /** When the output was stored */
+    timestamp: Date;
+}
+/**
+ * In-memory store for large gadget outputs.
+ *
+ * Outputs are stored with generated IDs in the format `{GadgetName}_{hex8}`.
+ * The store is tied to an agent run and cleared when the agent completes.
+ *
+ * @example
+ * ```typescript
+ * const store = new GadgetOutputStore();
+ * const id = store.store("Search", largeOutput);
+ * // id = "Search_a1b2c3d4"
+ *
+ * const stored = store.get(id);
+ * console.log(stored?.lineCount); // 4200
+ * ```
+ */
+declare class GadgetOutputStore {
+    private outputs;
+    /**
+     * Store a gadget output and return its ID.
+     *
+     * @param gadgetName - Name of the gadget that produced the output
+     * @param content - Full output content to store
+     * @returns Generated ID for retrieving the output later
+     */
+    store(gadgetName: string, content: string): string;
+    /**
+     * Retrieve a stored output by ID.
+     *
+     * @param id - The output ID (e.g., "Search_d34db33f")
+     * @returns The stored output or undefined if not found
+     */
+    get(id: string): StoredOutput | undefined;
+    /**
+     * Check if an output exists.
+     *
+     * @param id - The output ID to check
+     * @returns True if the output exists
+     */
+    has(id: string): boolean;
+    /**
+     * Get all stored output IDs.
+     *
+     * @returns Array of output IDs
+     */
+    getIds(): string[];
+    /**
+     * Get the number of stored outputs.
+     */
+    get size(): number;
+    /**
+     * Clear all stored outputs.
+     * Called when the agent run completes.
+     */
+    clear(): void;
+    /**
+     * Generate a unique ID for a stored output.
+     * Format: {GadgetName}_{8 hex chars}
+     */
+    private generateId;
+}
+
+/**
+ * OutputLimitManager - Manages gadget output size limiting.
+ *
+ * Calculates character limits from model context windows, registers
+ * GadgetOutputViewer when enabled, and chains the output limiter
+ * interceptor with user-provided hooks.
+ */
+
+/**
+ * Configuration for output limiting.
+ */
+interface OutputLimitConfig {
+    /** Whether output limiting is enabled (default: true) */
+    enabled?: boolean;
+    /** Max gadget output as % of model context window (default: 15) */
+    limitPercent?: number;
+}
+
 /**
  * Agent: Lean orchestrator using the clean hooks architecture.
  *
@@ -6265,6 +5903,46 @@ interface IConversationManager {
  * making it a simple loop orchestrator with clear responsibilities.
  */
 
+/**
+ * Configuration for the execution tree context (shared tree model with subagents).
+ */
+interface TreeConfig {
+    /**
+     * Shared execution tree for tracking all LLM calls and gadget executions.
+     * If provided (by a parent subagent), nodes are added to this tree.
+     * If not provided, the Agent creates its own tree.
+     */
+    tree?: ExecutionTree;
+    /**
+     * Parent node ID in the tree (when this agent is a subagent).
+     * Used to set parentId on all nodes created by this agent.
+     */
+    parentNodeId?: NodeId;
+    /**
+     * Base depth for nodes created by this agent.
+     * Root agents use 0; subagents use (parentDepth + 1).
+     */
+    baseDepth?: number;
+    /**
+     * Parent agent's observer hooks for subagent visibility.
+     *
+     * When a subagent is created with withParentContext(ctx), these observers
+     * are also called for gadget events (in addition to the subagent's own hooks),
+     * enabling the parent to observe subagent gadget activity.
+     */
+    parentObservers?: Observers;
+}
+/**
+ * Configuration for custom gadget block format prefixes.
+ */
+interface PrefixConfig {
+    /** Custom gadget start prefix */
+    gadgetStartPrefix?: string;
+    /** Custom gadget end prefix */
+    gadgetEndPrefix?: string;
+    /** Custom gadget argument prefix for block format parameters */
+    gadgetArgPrefix?: string;
+}
 /**
  * Configuration options for the Agent.
  */
@@ -6291,12 +5969,10 @@ interface AgentOptions {
     hooks?: AgentHooks;
     /** Callback for requesting human input during execution */
     requestHumanInput?: (question: string) => Promise<string>;
-    /** Custom gadget start prefix */
-    gadgetStartPrefix?: string;
-    /** Custom gadget end prefix */
-    gadgetEndPrefix?: string;
-    /** Custom gadget argument prefix for block format parameters */
-    gadgetArgPrefix?: string;
+    /**
+     * Gadget prefix configuration (start/end/arg prefixes for block format).
+     */
+    prefixConfig?: PrefixConfig;
     /** Initial messages. User messages support multimodal content. */
     initialMessages?: Array<{
         role: "system" | "user" | "assistant";
@@ -6322,10 +5998,10 @@ interface AgentOptions {
     gadgetExecutionMode?: GadgetExecutionMode;
     /** Custom prompt configuration for gadget system prompts */
     promptConfig?: PromptTemplateConfig;
-    /** Enable gadget output limiting (default: true) */
-    gadgetOutputLimit?: boolean;
-    /** Max gadget output as % of model context window (default: 15) */
-    gadgetOutputLimitPercent?: number;
+    /**
+     * Gadget output limit configuration.
+     */
+    outputLimitConfig?: OutputLimitConfig;
     /** Context compaction configuration (enabled by default) */
     compactionConfig?: CompactionConfig;
     /** Retry configuration for LLM API calls (enabled by default) */
@@ -6343,29 +6019,9 @@ interface AgentOptions {
     /** Maximum gadgets to execute per LLM response (0 = unlimited) */
     maxGadgetsPerResponse?: number;
     /**
-     * Shared execution tree for tracking all LLM calls and gadget executions.
-     * If provided (by a parent subagent), nodes are added to this tree.
-     * If not provided, the Agent creates its own tree.
-     */
-    parentTree?: ExecutionTree;
-    /**
-     * Parent node ID in the tree (when this agent is a subagent).
-     * Used to set parentId on all nodes created by this agent.
-     */
-    parentNodeId?: NodeId;
-    /**
-     * Base depth for nodes created by this agent.
-     * Root agents use 0; subagents use (parentDepth + 1).
-     */
-    baseDepth?: number;
-    /**
-     * Parent agent's observer hooks for subagent visibility.
-     *
-     * When a subagent is created with withParentContext(ctx), these observers
-     * are also called for gadget events (in addition to the subagent's own hooks),
-     * enabling the parent to observe subagent gadget activity.
+     * Execution tree configuration (shared tree model with subagents).
      */
-    parentObservers?: Observers;
+    treeConfig?: TreeConfig;
     /**
      * Shared rate limit tracker from parent agent.
      *
@@ -6406,19 +6062,11 @@ declare class Agent {
     private readonly hooks;
     private readonly conversation;
     private readonly registry;
-    private readonly gadgetStartPrefix?;
-    private readonly gadgetEndPrefix?;
-    private readonly gadgetArgPrefix?;
-    private readonly requestHumanInput?;
-    private readonly textOnlyHandler;
-    private readonly textWithGadgetsHandler?;
-    private readonly defaultGadgetTimeoutMs?;
-    private readonly gadgetExecutionMode;
+    private readonly prefixConfig?;
+    private readonly conversationUpdater;
     private readonly defaultMaxTokens?;
     private hasUserPrompt;
-    private readonly outputStore;
-    private readonly outputLimitEnabled;
-    private readonly outputLimitCharLimit;
+    private readonly outputLimitManager;
     private readonly compactionManager?;
     private readonly mediaStore;
     private readonly signal?;
@@ -6426,17 +6074,13 @@ declare class Agent {
     private readonly caching?;
     private readonly retryConfig;
     private readonly rateLimitTracker?;
-    private readonly agentContextConfig;
-    private readonly subagentConfig?;
-    private readonly maxGadgetsPerResponse;
-    private syntheticInvocationCounter;
     private readonly completedInvocationIds;
     private readonly failedInvocationIds;
     private readonly pendingUserMessages;
     private readonly tree;
     private readonly parentNodeId;
-    private readonly baseDepth;
-    private readonly parentObservers?;
+    private readonly streamProcessorFactory;
+    private readonly llmCallLifecycle;
     /**
      * Creates a new Agent instance.
      * @internal This constructor is private. Use LLMist.createAgent() or AgentBuilder instead.
@@ -6617,6 +6261,16 @@ declare class Agent {
      * @throws {Error} If no user prompt was provided (when using build() without ask())
      */
     run(): AsyncGenerator<StreamEvent>;
+    /**
+     * Execute a single LLM call attempt with full retry orchestration.
+     *
+     * Delegates all retry logic to RetryOrchestrator, then propagates the accumulated
+     * invocation IDs back to the agent's cross-iteration tracking sets.
+     *
+     * Yields stream events in real-time and returns the final stream completion metadata
+     * along with accumulated tracking state from the final successful attempt only.
+     */
+    private executeWithRetry;
     /**
      * Create LLM stream with proactive rate limit protection.
      *
@@ -6625,26 +6279,20 @@ declare class Agent {
      */
     private createStream;
     /**
-     * Simple sleep utility for rate limit delays.
-     */
-    private sleep;
-    /**
-     * Handle LLM error through controller.
+     * Factory method for constructing a StreamProcessor for a given iteration.
+     *
+     * Delegates to StreamProcessorFactory, which encapsulates all static
+     * StreamProcessor configuration. Cross-iteration mutable state is passed here.
      */
-    private handleLLMError;
+    private createStreamProcessor;
     /**
-     * Handle text-only response (no gadgets called).
+     * Simple sleep utility for rate limit delays.
      */
-    private handleTextOnlyResponse;
+    private sleep;
     /**
      * Resolve max tokens from model catalog.
      */
     private resolveMaxTokensFromCatalog;
-    /**
-     * Chain the output limiter interceptor with user-provided hooks.
-     * The limiter runs first, then chains to any user interceptor.
-     */
-    private chainOutputLimiterWithUserHooks;
     /**
      * Check abort signal and notify observers if aborted.
      * @returns true if agent should terminate
@@ -6655,43 +6303,6 @@ declare class Agent {
      * @returns compaction stream event if compaction occurred, null otherwise
      */
     private checkAndPerformCompaction;
-    /**
-     * Resolve reasoning configuration with auto-enable logic.
-     *
-     * Priority: explicit config > auto-enable for reasoning models > undefined
-     * When a model has `features.reasoning: true` and no explicit config is set,
-     * reasoning is automatically enabled at "medium" effort.
-     */
-    private resolveReasoningConfig;
-    /**
-     * Resolve caching configuration.
-     *
-     * Priority: explicit config > default enabled (preserves Anthropic's existing behavior)
-     * Default is `{ enabled: true }` which means:
-     * - Anthropic: `cache_control` markers are added (existing behavior preserved)
-     * - Gemini: Cache manager is consulted but skips if no explicit config was set
-     * - OpenAI: No-op (server-side automatic)
-     */
-    private resolveCachingConfig;
-    /**
-     * Prepare LLM call options, create tree node, and process beforeLLMCall controller.
-     * @returns options, node ID, and optional skipWithSynthetic response if controller wants to skip
-     */
-    private prepareLLMCall;
-    /**
-     * Calculate cost and complete LLM call in execution tree.
-     * Also records usage to rate limit tracker for proactive throttling.
-     */
-    private completeLLMCallInTree;
-    /**
-     * Process afterLLMCall controller and return modified final message.
-     */
-    private processAfterLLMCallController;
-    /**
-     * Update conversation history with gadget results or text-only response.
-     * @returns true if loop should break (text-only handler requested termination)
-     */
-    private updateConversationWithResults;
     /**
      * Run agent with named event handlers (syntactic sugar).
      *
@@ -7851,91 +7462,6 @@ declare class ConversationManager implements IConversationManager {
     getConversationHistory(): LLMMessage[];
 }
 
-/**
- * Storage for large gadget outputs that exceed the configured limit.
- *
- * When a gadget returns more data than the configured limit, the output
- * is stored here and can be browsed later using GadgetOutputViewer.
- */
-/**
- * Metadata and content for a stored gadget output.
- */
-interface StoredOutput {
-    /** Unique identifier (e.g., "Search_d34db33f") */
-    id: string;
-    /** Name of the gadget that produced this output */
-    gadgetName: string;
-    /** Full output content */
-    content: string;
-    /** Size in bytes */
-    byteSize: number;
-    /** Number of lines */
-    lineCount: number;
-    /** When the output was stored */
-    timestamp: Date;
-}
-/**
- * In-memory store for large gadget outputs.
- *
- * Outputs are stored with generated IDs in the format `{GadgetName}_{hex8}`.
- * The store is tied to an agent run and cleared when the agent completes.
- *
- * @example
- * ```typescript
- * const store = new GadgetOutputStore();
- * const id = store.store("Search", largeOutput);
- * // id = "Search_a1b2c3d4"
- *
- * const stored = store.get(id);
- * console.log(stored?.lineCount); // 4200
- * ```
- */
-declare class GadgetOutputStore {
-    private outputs;
-    /**
-     * Store a gadget output and return its ID.
-     *
-     * @param gadgetName - Name of the gadget that produced the output
-     * @param content - Full output content to store
-     * @returns Generated ID for retrieving the output later
-     */
-    store(gadgetName: string, content: string): string;
-    /**
-     * Retrieve a stored output by ID.
-     *
-     * @param id - The output ID (e.g., "Search_d34db33f")
-     * @returns The stored output or undefined if not found
-     */
-    get(id: string): StoredOutput | undefined;
-    /**
-     * Check if an output exists.
-     *
-     * @param id - The output ID to check
-     * @returns True if the output exists
-     */
-    has(id: string): boolean;
-    /**
-     * Get all stored output IDs.
-     *
-     * @returns Array of output IDs
-     */
-    getIds(): string[];
-    /**
-     * Get the number of stored outputs.
-     */
-    get size(): number;
-    /**
-     * Clear all stored outputs.
-     * Called when the agent run completes.
-     */
-    clear(): void;
-    /**
-     * Generate a unique ID for a stored output.
-     * Format: {GadgetName}_{8 hex chars}
-     */
-    private generateId;
-}
-
 /**
  * LLM Assistance Hints System
  *
@@ -8114,6 +7640,18 @@ declare function createHints(config: HintsConfig): AgentHooks;
  *
  * Replaces the complex wiring between Agent, ResponseProcessor, and GadgetRuntime.
  * Owns ALL stream processing and hook coordination with a clean, predictable flow.
+ *
+ * After refactoring, StreamProcessor is a thin orchestrator (~300 lines) that:
+ * - Iterates over raw LLM stream chunks
+ * - Applies raw-chunk and text-chunk interceptors
+ * - Delegates gadget dispatch to GadgetDispatcher
+ * - Yields events in real-time
+ * - Applies the final assistant-message interceptor
+ *
+ * Extracted classes:
+ * - GadgetLimitGuard     — maxGadgetsPerResponse enforcement
+ * - GadgetHookLifecycle  — full hook sequence for a single gadget
+ * - GadgetDispatcher     — dispatch decision tree + concurrency + dependency
  */
 
 /**
@@ -8181,6 +7719,11 @@ interface StreamProcessorOptions {
 }
 /**
  * Result of stream processing.
+ *
+ * @deprecated StreamProcessor.process() is now an async generator that yields
+ * StreamEvent items directly. Use StreamCompletionEvent (the final yielded event)
+ * to obtain the metadata formerly returned in this type. This interface is retained
+ * for backward compatibility but is not used internally.
  */
 interface StreamProcessingResult {
     /** All emitted events */
@@ -8199,21 +7742,14 @@ interface StreamProcessingResult {
     finalMessage: string;
 }
 /**
- * StreamProcessor: Coordinates all stream processing and hook execution.
+ * StreamProcessor: Thin orchestrator for stream processing and hook coordination.
  *
  * Execution order:
  * 1. Raw chunk arrives from LLM
  * 2. Interceptor: interceptRawChunk (transform raw text)
  * 3. Observer: onStreamChunk (logging)
  * 4. Parse for gadgets
- * 5. If gadget found:
- *    a. Interceptor: interceptGadgetParameters (transform params)
- *    b. Controller: beforeGadgetExecution (can skip)
- *    c. Observer: onGadgetExecutionStart
- *    d. Execute gadget
- *    e. Interceptor: interceptGadgetResult (transform result)
- *    f. Controller: afterGadgetExecution (can provide fallback)
- *    g. Observer: onGadgetExecutionComplete
+ * 5. If gadget found → delegate to GadgetDispatcher
  * 6. If text chunk:
  *    a. Interceptor: interceptTextChunk (transform display text)
  *    b. Yield to user
@@ -8225,20 +7761,13 @@ declare class StreamProcessor {
     private readonly hooks;
     private readonly logger;
     private readonly parser;
-    private readonly executor;
     private readonly tree?;
-    private readonly parentNodeId;
-    private readonly baseDepth;
-    private readonly gadgetExecutionMode;
     private responseText;
     private readonly dependencyResolver;
-    private readonly concurrencyManager;
     /** Queue of completed gadget results ready to be yielded (for real-time streaming) */
     private completedResultsQueue;
-    private readonly parentObservers?;
-    private readonly maxGadgetsPerResponse;
-    private gadgetStartedCount;
-    private limitExceeded;
+    private readonly dispatcher;
+    private readonly limitGuard;
     constructor(options: StreamProcessorOptions);
     /**
      * Process an LLM stream and yield events in real-time.
@@ -8259,30 +7788,6 @@ declare class StreamProcessor {
      * Process a text event through interceptors.
      */
     private processTextEvent;
-    /**
-     * Process a gadget call, yielding events in real-time.
-     *
-     * Yields gadget_call event IMMEDIATELY when parsed (before execution),
-     * enabling real-time UI feedback.
-     */
-    private processGadgetCallGenerator;
-    /**
-     * Start a gadget execution with concurrency tracking.
-     * Delegates tracking to GadgetConcurrencyManager; schedules queue processing on completion.
-     */
-    private startGadgetWithConcurrencyTracking;
-    /**
-     * Execute a gadget through the full hook lifecycle and yield events.
-     * Handles parameter interception, before/after controllers, observers,
-     * execution, result interception, and tree tracking.
-     */
-    private executeGadgetGenerator;
-    /**
-     * Execute a gadget and push events to the completed results queue (non-blocking).
-     * Used for fire-and-forget parallel execution of independent gadgets.
-     * Results are pushed to completedResultsQueue for real-time streaming to the caller.
-     */
-    private executeGadgetAndCollect;
     /**
      * Drain all completed results from the queue.
      * Used to yield results as they complete during stream processing.
@@ -8290,35 +7795,14 @@ declare class StreamProcessor {
      */
     private drainCompletedResults;
     /**
-     * Wait for all in-flight gadget executions to complete, yielding events in real-time.
-     * Called at stream end to ensure all parallel executions finish.
-     * Results and subagent events are pushed to completedResultsQueue during execution.
-     * This generator yields queued events while polling, enabling real-time display
-     * of subagent activity (LLM calls, nested gadgets) during long-running gadgets.
-     * Clears the inFlightExecutions map after all gadgets complete.
-     */
-    private waitForInFlightExecutions;
-    /**
-     * Handle a gadget that cannot execute because a dependency failed.
-     * Calls the onDependencySkipped controller to allow customization.
-     */
-    private handleFailedDependency;
-    /**
-     * Check if gadget execution should be skipped due to maxGadgetsPerResponse limit.
-     * If limit is exceeded, yields skip events and returns true.
-     * If execution can proceed, increments counter and returns false.
-     *
-     * @returns true if gadget should be skipped, false if execution can proceed
-     */
-    private checkGadgetLimitExceeded;
-    /**
-     * Process pending gadgets whose dependencies are now satisfied.
-     * Yields events in real-time as gadgets complete.
+     * Update gadget result tracking flags based on a stream event.
+     * Checks if the event is a gadget_result and, if so, marks gadgets as executed
+     * and sets the break-loop flag when the result requests it.
      *
-     * Gadgets are executed in parallel for efficiency,
-     * but results are yielded as they become available.
+     * @param evt - The stream event to inspect
+     * @param state - Mutable state object holding the tracking flags
      */
-    private processPendingGadgetsGenerator;
+    private trackGadgetResult;
     /**
      * Execute multiple observers in parallel.
      * All observers run concurrently and failures are tracked but don't crash.
@@ -8492,6 +7976,26 @@ declare function getProvider(model: string): string | undefined;
  * ```
  */
 declare function getModelId(model: string): string;
+/**
+ * Strip the provider prefix from a model string.
+ *
+ * Identical to {@link getModelId}: removes the `provider:` portion and returns
+ * just the model ID. If there is no prefix, the original string is returned.
+ *
+ * Use this when you need the bare model ID (e.g. for a cost-registry lookup)
+ * and the input may or may not carry a provider prefix.
+ *
+ * @param modelId - Full model string, optionally with provider prefix
+ * @returns Model ID without provider prefix
+ *
+ * @example
+ * ```typescript
+ * stripProviderPrefix('openai:gpt-4o')          // → 'gpt-4o'
+ * stripProviderPrefix('anthropic:claude-sonnet') // → 'claude-sonnet'
+ * stripProviderPrefix('gpt-4o')                 // → 'gpt-4o'  (no prefix — returned as-is)
+ * ```
+ */
+declare function stripProviderPrefix(modelId: string): string;
 
 /**
  * Signal that a gadget throws to indicate task completion and agent termination.
@@ -8656,6 +8160,51 @@ interface ErrorFormatterOptions {
     endPrefix?: string;
 }
 
+/**
+ * Options for constructing a GadgetExecutor.
+ */
+interface GadgetExecutorOptions {
+    /** Gadget registry used to look up and execute gadgets */
+    registry: GadgetRegistry;
+    /** Optional callback to request human input during gadget execution */
+    requestHumanInput?: (question: string) => Promise<string>;
+    /** Logger instance; defaults to a new "llmist:executor" logger if omitted */
+    logger?: Logger<ILogObj>;
+    /** Default timeout in milliseconds applied to all gadgets without an explicit timeout */
+    defaultGadgetTimeoutMs?: number;
+    /** Options for formatting gadget execution errors */
+    errorFormatterOptions?: ErrorFormatterOptions;
+    /** LLMist client made available to gadgets via ExecutionContext.llmist */
+    client?: LLMist;
+    /** Media store for persisting gadget media outputs */
+    mediaStore?: MediaStore;
+    /** Parent agent configuration inherited by subagents */
+    agentConfig?: AgentContextConfig;
+    /** Per-gadget configuration overrides (e.g., timeoutMs, model) */
+    subagentConfig?: SubagentConfigMap;
+    /** Execution tree for tracking LLM calls and gadget executions */
+    tree?: ExecutionTree;
+    /** Parent node ID in the execution tree */
+    parentNodeId?: NodeId | null;
+    /** Base depth for nodes created during execution */
+    baseDepth?: number;
+    /**
+     * Parent agent's observer hooks for subagent visibility.
+     * When a subagent uses withParentContext(ctx), these observers are also called
+     * for gadget events in addition to the subagent's own hooks.
+     */
+    parentObservers?: Observers;
+    /**
+     * Current agent's observers.
+     * Passed to ExecutionContext.parentObservers so gadgets creating subagents
+     * can inherit them via withParentContext(ctx).
+     */
+    currentObservers?: Observers;
+    /** Shared rate limit tracker for coordinated throttling across subagents */
+    rateLimitTracker?: RateLimitTracker;
+    /** Shared retry config for consistent backoff behavior across subagents */
+    retryConfig?: ResolvedRetryConfig;
+}
 declare class GadgetExecutor {
     private readonly registry;
     private readonly requestHumanInput?;
@@ -8674,7 +8223,7 @@ declare class GadgetExecutor {
     private readonly logger;
     private readonly errorFormatter;
     private readonly argPrefix;
-    constructor(registry: GadgetRegistry, requestHumanInput?: ((question: string) => Promise<string>) | undefined, logger?: Logger<ILogObj>, defaultGadgetTimeoutMs?: number | undefined, errorFormatterOptions?: ErrorFormatterOptions, client?: LLMist | undefined, mediaStore?: MediaStore | undefined, agentConfig?: AgentContextConfig | undefined, subagentConfig?: SubagentConfigMap | undefined, tree?: ExecutionTree | undefined, parentNodeId?: (NodeId | null) | undefined, baseDepth?: number | undefined, parentObservers?: Observers | undefined, currentObservers?: Observers | undefined, rateLimitTracker?: RateLimitTracker | undefined, retryConfig?: ResolvedRetryConfig | undefined);
+    constructor(options: GadgetExecutorOptions);
     /**
      * Creates a promise that rejects with a TimeoutException after the specified timeout.
      * Aborts the provided AbortController before rejecting, allowing gadgets to clean up.
@@ -8688,7 +8237,6 @@ declare class GadgetExecutor {
      */
     private unifyExecuteResult;
     execute(call: ParsedGadgetCall): Promise<GadgetExecutionResult>;
-    executeAll(calls: ParsedGadgetCall[]): Promise<GadgetExecutionResult[]>;
 }
 
 /**
@@ -9543,6 +9091,12 @@ interface LLMistPackageManifest {
      * Session factory metadata.
      */
     session?: SessionManifestEntry;
+    /**
+     * Skills directory relative to package root.
+     * Contains subdirectories with SKILL.md files.
+     * @example "./skills"
+     */
+    skills?: string;
 }
 /**
  * Factory function types that packages can export.
@@ -10440,6 +9994,146 @@ declare class SimpleSessionManager<TSession> extends BaseSessionManager<TSession
     setSession(id: string, data: TSession): void;
 }
 
+/**
+ * Skill activation logic.
+ *
+ * Handles $ARGUMENTS substitution and !`command` shell preprocessing
+ * to resolve skill instructions before injection into agent context.
+ *
+ * @module skills/activation
+ */
+/**
+ * Substitute $ARGUMENTS and positional $0, $1, etc. in skill instructions.
+ */
+declare function substituteArguments(instructions: string, args?: string): string;
+/**
+ * Substitute ${VARIABLE} environment-style variables in skill instructions.
+ *
+ * Supported variables:
+ * - ${CLAUDE_SKILL_DIR} / ${SKILL_DIR} - directory containing SKILL.md
+ * - ${CLAUDE_SESSION_ID} / ${SESSION_ID} - current session ID (if provided)
+ */
+declare function substituteVariables(instructions: string, variables: Record<string, string>): string;
+/**
+ * Full activation pipeline: variables -> arguments -> shell preprocessing.
+ */
+declare function resolveInstructions(instructions: string, options?: {
+    arguments?: string;
+    variables?: Record<string, string>;
+    cwd?: string;
+    shell?: "bash" | "powershell";
+    shellTimeoutMs?: number;
+    enableShellPreprocessing?: boolean;
+}): string;
+
+/**
+ * Filesystem-based skill discovery and loading.
+ *
+ * Scans directories for subdirectories containing SKILL.md files.
+ * Supports standard discovery locations and custom directories.
+ *
+ * @module skills/loader
+ */
+
+/**
+ * Load skills from a directory.
+ *
+ * Recursively scans for subdirectories containing a SKILL.md file.
+ * Each such directory is treated as a single skill.
+ *
+ * @param dir - Directory to scan
+ * @param source - Origin for all discovered skills
+ */
+declare function loadSkillsFromDirectory(dir: string, source: SkillSource, onWarning?: (msg: string) => void): Skill[];
+/**
+ * Discover skills from standard locations.
+ *
+ * Discovery order (later sources overwrite earlier on name collision):
+ * 1. User skills: ~/.llmist/skills/
+ * 2. Project skills: <projectDir>/.llmist/skills/
+ * 3. Additional directories (explicit)
+ */
+declare function discoverSkills(options?: {
+    projectDir?: string;
+    userDir?: string;
+    additionalDirs?: string[];
+}): SkillRegistry;
+
+/**
+ * SKILL.md parser for the Agent Skills open standard.
+ *
+ * Parses YAML frontmatter (between --- markers) and markdown body.
+ * Scans skill directories for Tier 3 resources (scripts/, references/, assets/).
+ *
+ * @module skills/parser
+ */
+
+/**
+ * Parse YAML frontmatter from SKILL.md content.
+ *
+ * Extracts the YAML block between the first pair of `---` markers
+ * and the remaining markdown body.
+ */
+declare function parseFrontmatter(content: string): {
+    frontmatter: Record<string, unknown>;
+    body: string;
+};
+/**
+ * Convert raw frontmatter to validated SkillMetadata.
+ *
+ * Maps kebab-case YAML keys to camelCase TypeScript properties.
+ * Falls back to directory name for missing name field.
+ */
+declare function parseMetadata(frontmatter: Record<string, unknown>, fallbackName?: string): SkillMetadata;
+/**
+ * Scan a skill directory for Tier 3 resource files.
+ */
+declare function scanResources(skillDir: string): SkillResource[];
+/**
+ * Parse a SKILL.md file from disk.
+ *
+ * This performs Tier 1 parsing (metadata) and optionally Tier 2 (instructions).
+ * Resources are discovered but not loaded.
+ *
+ * @param skillMdPath - Absolute path to SKILL.md
+ * @param source - Where this skill was discovered from
+ * @param loadInstructions - Whether to load Tier 2 body (default: false for lazy loading)
+ */
+declare function parseSkillFile(skillMdPath: string, source: SkillSource, loadInstructions?: boolean): ParsedSkill;
+/**
+ * Parse SKILL.md content from a string.
+ *
+ * Useful for testing without filesystem access.
+ */
+declare function parseSkillContent(content: string, sourcePath: string, source: SkillSource, loadInstructions?: boolean): ParsedSkill;
+/**
+ * Validate skill metadata.
+ * Returns an array of validation issues (empty if valid).
+ */
+declare function validateMetadata(metadata: SkillMetadata): string[];
+
+/**
+ * UseSkill meta-gadget — bridges the skill system into the gadget execution pipeline.
+ *
+ * When skills are registered with an agent, this gadget is auto-created and added
+ * to the gadget registry. The LLM can invoke it like any other gadget, and the
+ * skill's instructions are returned as the gadget result.
+ *
+ * This approach requires zero changes to the stream processor or agent loop.
+ *
+ * @module skills/use-skill-gadget
+ */
+
+/** Name for the auto-generated UseSkill gadget. */
+declare const USE_SKILL_GADGET_NAME = "UseSkill";
+/**
+ * Create the UseSkill meta-gadget from a skill registry.
+ *
+ * The gadget description includes a summary of all available skills,
+ * so the LLM knows what skills exist and when to use them.
+ */
+declare function createUseSkillGadget(registry: SkillRegistry): AbstractGadget;
+
 /**
  * Config resolution utility for subagent gadgets.
  *
@@ -10869,4 +10563,4 @@ declare const timing: {
  */
 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, BaseSessionManager, type BeforeGadgetExecutionAction, type BeforeLLMCallAction, BudgetPricingUnavailableError, type CachingConfig, type CachingScope, 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_RATE_LIMIT_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_SUMMARIZATION_PROMPT, type EventHandlers, type ExecutionContext, type ExecutionEvent, type ExecutionEventType, type ExecutionNode, type ExecutionNodeType, ExecutionTree, FALLBACK_CHARS_PER_TOKEN, type FileLoggingOptions, type FileLoggingState, type FileWrittenInfo, type FormatLLMErrorContext, 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 GadgetExecutionMode, 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, HuggingFaceProvider, 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 LLMCallNode, type LLMCallStartEvent, type LLMCallStreamEvent, type LLMErrorControllerContext, type LLMEvent, type LLMGenerationOptions, type LLMMessage, LLMMessageBuilder, type LLMResponseEndEvent, 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 ObserveRateLimitThrottleContext, type ObserveRetryAttemptContext, type Observers, OpenAIChatProvider, type OpenAICompatibleConfig, OpenAICompatibleProvider, type OpenRouterConfig, OpenRouterProvider, type OpenRouterRouting, type ParallelGadgetHintOptions, type ParsedGadgetCall, type PresetDefinition, type PromptContext, type PromptTemplate, type PromptTemplateConfig, type ProviderAdapter, type ProviderIdentifier, type RateLimitConfig, type RateLimitStats, RateLimitTracker, type ReasoningConfig, type ReasoningEffort, type ResolveValueOptions, type ResolvedCompactionConfig, type ResolvedRateLimitConfig, 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 SubagentManifestEntry, type SubagentOptions, SummarizationStrategy, TaskCompletionSignal, type TextContentPart, type TextEvent, type TextGenerationOptions, type TextOnlyAction, type TextOnlyContext, type TextOnlyCustomHandler, type TextOnlyGadgetConfig, type TextOnlyHandler, type TextOnlyStrategy, type ThinkingChunk, type ThinkingEvent, TimeoutException, type TokenUsage, type TrailingMessage, type TrailingMessageContext, type CompactionEvent$1 as TreeCompactionEvent, type GadgetSkippedEvent$1 as TreeGadgetSkippedEvent, type TriggeredLimitInfo, type ValidationIssue, type ValidationResult, type VisionAnalyzeOptions, type VisionAnalyzeResult, audioFromBase64, audioFromBuffer, collectEvents, collectText, complete, createAnthropicProviderFromEnv, createFileLoggingState, createGadget, createGadgetOutputViewer, createGeminiProviderFromEnv, createHints, createHuggingFaceProviderFromEnv, createLogger, createMediaOutput, createOpenAIProviderFromEnv, createOpenRouterProviderFromEnv, createSubagent, defaultLogger, detectAudioMimeType, detectImageMimeType, discoverProviderAdapters, extractMessageText, extractRetryAfterMs, filterByDepth, filterByParent, filterRootEvents, format, formatBytes, formatCallNumber, formatDate, formatDuration, formatLLMError, formatLlmRequest, 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, parseRetryAfterHeader, randomDelay, resetFileLoggingState, resolveConfig, resolveHintTemplate, resolveModel, resolvePromptTemplate, resolveRateLimitConfig, resolveRetryConfig, resolveRulesTemplate, resolveSubagentModel, resolveSubagentTimeout, resolveValue, resultWithAudio, resultWithFile, resultWithImage, resultWithImages, resultWithMedia, runWithHandlers, schemaToJSONSchema, stream, text, timing, toBase64, truncate, validateAndApplyDefaults, validateGadgetParams, validateGadgetSchema, withErrorHandling, withRetry, withTimeout };
+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 BeforeSkillActivationAction, BudgetPricingUnavailableError, type CachingConfig, type CachingScope, 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_RATE_LIMIT_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_SUMMARIZATION_PROMPT, type EventHandlers, type ExecutionContext, type ExecutionEvent, type ExecutionEventType, type ExecutionNode, type ExecutionNodeType, ExecutionTree, FALLBACK_CHARS_PER_TOKEN, type FileLoggingOptions, type FileLoggingState, type FileWrittenInfo, type FormatLLMErrorContext, 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 GadgetExecutionMode, type GadgetExecutionResult, GadgetExecutor, type GadgetExecutorOptions, 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, HuggingFaceProvider, 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 LLMCallNode, type LLMCallStartEvent, type LLMCallStreamEvent, type LLMErrorControllerContext, type LLMEvent, type LLMGenerationOptions, type LLMMessage, LLMMessageBuilder, type LLMResponseEndEvent, 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 ObserveRateLimitThrottleContext, type ObserveRetryAttemptContext, type ObserveSkillActivatedContext, type Observers, OpenAIChatProvider, type OpenAICompatibleConfig, OpenAICompatibleProvider, type OpenRouterConfig, OpenRouterProvider, type OpenRouterRouting, type OutputLimitConfig, type ParallelGadgetHintOptions, type ParsedGadgetCall, type ParsedSkill, type PrefixConfig, type PresetDefinition, type PromptContext, type PromptTemplate, type PromptTemplateConfig, type ProviderAdapter, type ProviderIdentifier, type RateLimitConfig, type RateLimitStats, RateLimitTracker, type ReasoningConfig, type ReasoningEffort, type ResolveValueOptions, type ResolvedCompactionConfig, type ResolvedRateLimitConfig, type ResolvedRetryConfig, type RetryConfig, type RetryOptions, type SessionManifestEntry, SimpleSessionManager, Skill, type SkillActivation, type SkillActivationControllerContext, type SkillActivationOptions, type SkillInstructionInterceptorContext, type SkillMetadata, SkillRegistry, type SkillResource, type SkillSource, 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 SubagentManifestEntry, type SubagentOptions, SummarizationStrategy, TaskCompletionSignal, type TextContentPart, type TextEvent, type TextGenerationOptions, type TextOnlyAction, type TextOnlyContext, type TextOnlyCustomHandler, type TextOnlyGadgetConfig, type TextOnlyHandler, type TextOnlyStrategy, type ThinkingChunk, type ThinkingEvent, TimeoutException, type TokenUsage, type TrailingMessage, type TrailingMessageContext, type CompactionEvent$1 as TreeCompactionEvent, type TreeConfig, type GadgetSkippedEvent$1 as TreeGadgetSkippedEvent, type TriggeredLimitInfo, USE_SKILL_GADGET_NAME, type ValidationIssue, type ValidationResult, type VisionAnalyzeOptions, type VisionAnalyzeResult, audioFromBase64, audioFromBuffer, collectEvents, collectText, complete, createAnthropicProviderFromEnv, createFileLoggingState, createGadget, createGadgetOutputViewer, createGeminiProviderFromEnv, createHints, createHuggingFaceProviderFromEnv, createLogger, createMediaOutput, createOpenAIProviderFromEnv, createOpenRouterProviderFromEnv, createSubagent, createUseSkillGadget, defaultLogger, detectAudioMimeType, detectImageMimeType, discoverProviderAdapters, discoverSkills, extractMessageText, extractRetryAfterMs, filterByDepth, filterByParent, filterRootEvents, format, formatBytes, formatCallNumber, formatDate, formatDuration, formatLLMError, formatLlmRequest, 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, loadSkillsFromDirectory, normalizeMessageContent, parallelGadgetHint, parseDataUrl, parseFrontmatter, parseManifest, parseMetadata, parseRetryAfterHeader, parseSkillContent, parseSkillFile, randomDelay, resetFileLoggingState, resolveConfig, resolveHintTemplate, resolveInstructions, resolveModel, resolvePromptTemplate, resolveRateLimitConfig, resolveRetryConfig, resolveRulesTemplate, resolveSubagentModel, resolveSubagentTimeout, resolveValue, resultWithAudio, resultWithFile, resultWithImage, resultWithImages, resultWithMedia, runWithHandlers, scanResources, schemaToJSONSchema, stream, stripProviderPrefix, substituteArguments, substituteVariables, text, timing, toBase64, truncate, validateAndApplyDefaults, validateGadgetParams, validateGadgetSchema, validateMetadata, withErrorHandling, withRetry, withTimeout };