@genesislcap/ai-assistant 14.434.0 → 14.435.0

package/dist/ai-assistant.d.ts

@@ -129,6 +129,22 @@ export declare interface AgenticActivityEvents {
     'chat-popin': undefined;
 }
 
+/**
+ * Context passed to `onActivate` / `onDeactivate` lifecycle hooks on an agent.
+ *
+ * @beta
+ */
+export declare interface AgentLifecycleContext {
+    /** The agent the hook is firing for. */
+    agentName: string;
+    /** The assistant session key — stable across reloads, unique per assistant instance. */
+    sessionKey: string;
+    /** The agent that was active immediately before this one, if any. Only set on `onActivate`. */
+    previousAgentName?: string;
+    /** Aborted if the session disconnects mid-activation. */
+    signal: AbortSignal;
+}
+
 /**
  * User-facing agent picker rendered above the chat input.
  *
@@ -317,6 +333,13 @@ export declare interface AiDriver extends EventTarget {
      * Get query suggestions from the AI.
      */
     getSuggestions(history: ChatMessage[], prompt: string, count: number, allAgentInfo?: AllAgentSummary[]): Promise<string[]>;
+    /**
+     * Per-LLM-call snapshots — what the model saw each turn (prompt, tools,
+     * agent state). Used by the host's debug-log exporter. Optional because the
+     * interface is implemented by both leaf and orchestrating drivers; the
+     * orchestrator just delegates to its inner `ChatDriver`.
+     */
+    getTurnSnapshots?(): ReadonlyArray<TurnSnapshot>;
 }
 
 /**
@@ -357,12 +380,21 @@ declare interface BaseAgentConfig {
     name: string;
     /**
      * System prompt injected into every conversation turn for this agent.
+     *
+     * Either a string (resolved once) or a function resolved each tool-loop
+     * iteration — pick the function form when the prompt depends on per-turn state
+     * (e.g. a state machine's current step). See {@link SystemPromptInput}.
      */
-    systemPrompt?: string;
+    systemPrompt?: SystemPromptInput;
     /**
      * Tool definitions (JSON Schema) passed to the AI provider for this agent.
+     *
+     * Either a static array or a function resolved each tool-loop iteration —
+     * pick the function form to narrow the tool surface per turn (e.g. expose
+     * only the tools valid in the current state of a state machine).
+     * See {@link ToolDefinitionsInput}.
      */
-    toolDefinitions?: ChatToolDefinition[];
+    toolDefinitions?: ToolDefinitionsInput;
     /**
      * Tool handler implementations for this agent.
      */
@@ -387,6 +419,40 @@ declare interface BaseAgentConfig {
      * disabled. See {@link ManualSelectionConfig}.
      */
     manualSelection?: ManualSelectionConfig;
+    /**
+     * Fires when this agent becomes the active specialist (including being pinned).
+     * Use to instantiate per-agent state that should outlive a single turn — e.g.
+     * a state machine the agent owns across the conversation. Awaited before the
+     * agent's first turn runs.
+     *
+     * Capture dependencies (services, redux store refs, etc.) via closure on the
+     * host element rather than expecting them on the context.
+     *
+     * @beta
+     */
+    onActivate?: (ctx: AgentLifecycleContext) => void | Promise<void>;
+    /**
+     * Fires when this agent is being deactivated (the user switches to another
+     * agent, the session is torn down, or the agent is unpinned and replaced).
+     * Use to dispose per-agent state created in `onActivate`. Awaited before the
+     * incoming agent's `onActivate` runs.
+     *
+     * @beta
+     */
+    onDeactivate?: (ctx: AgentLifecycleContext) => void | Promise<void>;
+    /**
+     * Returns an agent-supplied debug payload for the export log. Called once per
+     * LLM call by the driver (alongside the resolved prompt and tool list) and
+     * once at log-export time for the latest snapshot. Stateful agents should
+     * return their machine state and captured context so the exported timeline
+     * captures what drove each turn.
+     *
+     * Return value must be JSON-serializable. {@link defineStatefulAgent} wires a
+     * sensible default that snapshots any machine-shaped state automatically.
+     *
+     * @beta
+     */
+    getDebugSnapshot?: () => unknown;
 }
 
 /**
@@ -406,7 +472,19 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
     private busy;
     private pendingInteractions;
     private systemPrompt?;
+    /**
+     * Resolved tool definitions visible to the LLM. Folds mutate this in place
+     * (push/pop on open/close). When `toolDefinitionsFactory` is set, this is
+     * overwritten each tool-loop iteration with the factory's output.
+     */
     private toolDefinitions;
+    /**
+     * Optional dynamic-tools source. When set, called each tool-loop iteration
+     * to recompute `toolDefinitions` before the LLM call. `defineStatefulAgent`
+     * forbids folds when this is set, so the fold-mutation path is unreachable
+     * in that case.
+     */
+    private toolDefinitionsFactory?;
     private toolHandlers;
     private primerHistory?;
     private activeAgentName?;
@@ -438,7 +516,28 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * `undefined` means the loop has not been stopped early.
      */
     private subAgentCompletion;
-    constructor(aiProvider: AIProvider, toolHandlers?: ChatToolHandlers, toolDefinitions?: ChatToolDefinition[], systemPrompt?: string, primerHistory?: ChatMessage[], maxToolIterations?: number, maxFoldOperations?: number);
+    /**
+     * Set by `releaseAgent` inside a top-level tool handler — typically a stateful
+     * agent's terminal-state handler signalling that its flow is complete and the
+     * auto-pin lock can release. Checked by the orchestrator after `sendMessage`
+     * returns; the orchestrator fires `onDeactivate` and clears the pin.
+     *
+     * Reset at the start of each `sendMessage` so a release from a previous turn
+     * doesn't leak forward.
+     */
+    private agentReleaseRequested;
+    /**
+     * Ring buffer of per-LLM-call snapshots. Cap is configurable via
+     * `chatConfig.agent.maxTurnSnapshots`; older entries drop off as new ones
+     * arrive. See {@link TurnSnapshot} for the captured shape.
+     */
+    private turnSnapshots;
+    /** Monotonic counter that survives agent swaps — useful for cross-referencing with history. */
+    private globalTurnIndex;
+    /** Captured from `applyAgent` so we don't store the whole `AgentConfig`. */
+    private debugSnapshotter?;
+    private readonly maxTurnSnapshots;
+    constructor(aiProvider: AIProvider, toolHandlers?: ChatToolHandlers, toolDefinitions?: ToolDefinitionsInput, systemPrompt?: SystemPromptInput, primerHistory?: ChatMessage[], maxToolIterations?: number, maxFoldOperations?: number, maxTurnSnapshots?: number);
     /**
      * Swap in a new agent's configuration. Called by OrchestratingDriver before
      * each specialist turn so the shared driver runs with the right tools and prompt.
@@ -451,6 +550,25 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
     getSubAgentCompletion(): {
         result: unknown;
     } | undefined;
+    /**
+     * Returns true if `releaseAgent` was called during the most recent turn.
+     * Consumed by the orchestrator to trigger the auto-pin release path.
+     */
+    getAgentReleaseRequested(): boolean;
+    /**
+     * Return the per-turn snapshots captured so far. Used by the host's debug
+     * log exporter to show what the LLM saw on each turn — system prompt, tool
+     * surface, and agent-supplied state (e.g. a machine snapshot).
+     *
+     * Ring-buffered at `MAX_TURN_SNAPSHOTS`; older entries are dropped.
+     */
+    getTurnSnapshots(): ReadonlyArray<TurnSnapshot>;
+    /**
+     * Push one snapshot to the ring buffer. Called inside `runToolLoop` just
+     * before each LLM call — that's the latest point where the prompt, tool
+     * surface, and agent state line up with what the model is about to see.
+     */
+    private recordTurnSnapshot;
     /**
      * Optional transform applied to conversation history immediately before each LLM request.
      * Cleared when `undefined`. Does not alter stored history.
@@ -631,6 +749,33 @@ export declare function createToolFold(config: {
  */
 export declare function defineAgent<const T extends AgentConfig>(config: T): T;
 
+/**
+ * Build an `AgentConfig` whose `systemPrompt`, `toolDefinitions`, and tool
+ * handlers all close over a long-lived state object created on activation.
+ *
+ * The framework wires the lifecycle: `init` on `onActivate`, `dispose` on
+ * `onDeactivate`. State is held inside the helper's closure — never exposed on
+ * the resulting `AgentConfig` — so the redux serializer doesn't see it.
+ *
+ * @example
+ * ```ts
+ * const guidedBooking = defineStatefulAgent<{ machine: GuidedBookingMachine }>({
+ *   name: 'Guided Booking',
+ *   description: 'Books a trade via a guided wizard.',
+ *   excludeFromClassifier: true,
+ *   manualSelection: { enabled: true, hint: 'Step-by-step trade booking' },
+ *   init: () => ({ machine: new GuidedBookingMachine() }),
+ *   dispose: ({ state }) => state.machine.stop(),
+ *   systemPrompt: ({ state }) => composeFromMachine(state.machine),
+ *   toolDefinitions: ({ state }) => toolsForState(state.machine.state),
+ *   toolHandlers: ({ machine }) => ({ ... }),
+ * });
+ * ```
+ *
+ * @beta
+ */
+export declare function defineStatefulAgent<S>(opts: StatefulAgentInit<S>): AgentConfig;
+
 /**
  * Expands a flat list of tool definitions into a nested tree by resolving fold
  * metadata from the corresponding handlers. Use this for debug output so the
@@ -830,6 +975,14 @@ export declare class FoundationAiAssistant extends GenesisElement {
      * current agent configuration. Does not wire event listeners or register in
      * the driver registry.
      */
+    /**
+     * Warn at config time if any stateful agent (one with lifecycle hooks) is
+     * configured in a way that makes it unreachable: `excludeFromClassifier`
+     * removes the classifier path, so the only entry left is manual pinning —
+     * which requires both `manualSelection.enabled` on the agent and the picker
+     * itself being enabled at the assistant level.
+     */
+    private warnUnreachableStatefulAgents;
     private createDriver;
     /**
      * Attaches event listeners to the current driver. Stores a cleanup function
@@ -888,6 +1041,21 @@ export declare class FoundationAiAssistant extends GenesisElement {
     get agentPickerEnabled(): boolean;
     /** Hint text for the currently pinned agent, if any. Used in the toggle button tooltip. */
     get pinnedAgentHint(): string | undefined;
+    /**
+     * The pin is locked when a stateful agent (one with lifecycle hooks) is
+     * *actively running* — i.e. its `onActivate` has fired and it owns live
+     * state. Until the user sends their first message, a freshly pinned stateful
+     * agent is not yet active and the picker should remain free; the user might
+     * change their mind and unpin without anything to clean up.
+     *
+     * We derive from `activeAgent` (set by the orchestrator after `onActivate`
+     * completes) rather than `pinnedAgentName` (set immediately on picker
+     * click). The serialized `activeAgent` strips lifecycle hooks, so we look
+     * up the live config from `this.agents` to check for them.
+     */
+    get pinLocked(): boolean;
+    /** Tooltip shown on the picker toggle button. */
+    get agentToggleTitle(): string;
     /**
      * Tint applied to the pin icon when an agent is pinned. Picked from the
      * brand palette by agent position (modulo the palette length), so each agent
@@ -912,23 +1080,30 @@ export declare class FoundationAiAssistant extends GenesisElement {
             timestamp: string;
             host: string;
             agentSummary: ({
-                toolDefinitions: ToolTreeNode[];
+                toolDefinitions: string | ToolTreeNode[];
                 toolHandlers: any;
+                onActivate: any;
+                onDeactivate: any;
+                getDebugSnapshot: any;
                 description: string;
                 fallback?: never;
+                excludeFromClassifier?: boolean;
                 name: string;
-                systemPrompt?: string;
+                systemPrompt?: SystemPromptInput;
                 primerHistory?: ChatMessage[];
                 subAgents?: AgentConfig[];
                 chatInputDuringExecution?: ChatInputDuringExecutionMode;
                 manualSelection?: ManualSelectionConfig;
             } | {
-                toolDefinitions: ToolTreeNode[];
+                toolDefinitions: string | ToolTreeNode[];
                 toolHandlers: any;
+                onActivate: any;
+                onDeactivate: any;
+                getDebugSnapshot: any;
                 fallback: true;
                 description?: never;
                 name: string;
-                systemPrompt?: string;
+                systemPrompt?: SystemPromptInput;
                 primerHistory?: ChatMessage[];
                 subAgents?: AgentConfig[];
                 chatInputDuringExecution?: ChatInputDuringExecutionMode;
@@ -937,6 +1112,8 @@ export declare class FoundationAiAssistant extends GenesisElement {
             activeSystemPrompt: string;
             activePrimerHistory: ChatMessage[];
             activeFoldStack: string[];
+            activeDebugSnapshot: unknown;
+            turnSnapshots: readonly TurnSnapshot[];
             debug: unknown;
         };
     };
@@ -1056,14 +1233,22 @@ export declare class OrchestratingDriver extends EventTarget implements AiDriver
     private readonly maxHandoffs;
     private readonly classifierHistoryLength;
     private readonly classifierRetries;
+    private readonly sessionKey;
+    /**
+     * Aborted on driver disposal. Threaded into `AgentLifecycleContext.signal`
+     * so long-running `onActivate` work can bail if the session disconnects.
+     */
+    private readonly lifecycleAbortController;
     private pinnedAgentName;
     activeAgent?: AgentConfig;
     constructor(aiProvider: AIProvider, agents: AgentConfig[], options?: {
+        sessionKey?: string;
         maxHandoffs?: number;
         classifierHistoryLength?: number;
         classifierRetries?: number;
         maxToolIterations?: number;
         maxFoldOperations?: number;
+        maxTurnSnapshots?: number;
     });
     resolveInteraction(interactionId: string, result: unknown): void;
     isBusy(): boolean;
@@ -1076,10 +1261,24 @@ export declare class OrchestratingDriver extends EventTarget implements AiDriver
     setPinnedAgent(name: string | null): void;
     loadHistory(messages: ChatMessage[]): void;
     getRawHistory(): readonly ChatMessage[];
+    /** Delegates to the inner {@link ChatDriver} — turns are captured there. */
+    getTurnSnapshots(): ReadonlyArray<TurnSnapshot>;
     getSuggestions(history: ChatMessage[], prompt: string, count: number, allAgentInfo?: AllAgentSummary[]): Promise<string[]>;
     sendMessage(input: string, attachments?: ChatAttachment[]): Promise<ChatDriverResult>;
     continueFromHistory(transientPrimer?: ChatMessage[]): Promise<ChatDriverResult>;
     private applyAgent;
+    /**
+     * Release the current stateful agent: fire `onDeactivate`, clear the pin,
+     * dispatch events so the host (and Redux) reflect the unpinned state. Called
+     * automatically when a tool handler invokes `context.releaseAgent`.
+     */
+    private releaseActiveAgent;
+    /**
+     * Fire `onDeactivate` on the current active agent and abort any pending
+     * lifecycle work. Called by the host on session teardown so machines can
+     * release resources cleanly.
+     */
+    dispose(): Promise<void>;
     private classify;
     /**
      * Returns the pinned agent if `pinnedAgentName` matches a known specialist or
@@ -1118,6 +1317,106 @@ export declare interface SpecialistAgentConfig extends BaseAgentConfig {
      */
     description: string;
     fallback?: never;
+    /**
+     * When `true`, the classifier never auto-routes to this agent. The user can
+     * still select it manually via the picker, provided both prerequisites are
+     * met: this agent has `manualSelection.enabled` set to `true`, *and* the
+     * assistant has the picker enabled via `chatConfig.picker.mode`.
+     *
+     * Use this for agents that overlap heavily with a sibling (e.g. a guided
+     * wizard sitting next to a free-form agent in the same domain) and should
+     * only be reached intentionally rather than via classifier routing.
+     *
+     * @beta
+     */
+    excludeFromClassifier?: boolean;
+}
+
+/**
+ * Init options for {@link defineStatefulAgent}. Generic over the state shape `S`
+ * the agent owns (a state machine, an observable controller, anything).
+ *
+ * The helper threads `state` through `systemPrompt`, `toolDefinitions`, and the
+ * `toolHandlers` factory so consumer code never has to reach for a closure or
+ * a module-level mutable.
+ *
+ * @beta
+ */
+export declare interface StatefulAgentInit<S> {
+    /** Display name — must be unique within the agents array. */
+    name: string;
+    /** Plain-language description used by the classifier. Required: stateful agents are always specialists. */
+    description: string;
+    /**
+     * Hide this agent from the classifier — only reachable via manual pinning.
+     * Stateful agents are always specialists; they cannot be the fallback (a
+     * fallback is a leaf invoked when no specialist matches, with no flow to
+     * own state for).
+     */
+    excludeFromClassifier?: boolean;
+    /** Static primer history prepended to every call (not visible to the user). */
+    primerHistory?: ChatMessage[];
+    /** Sub-agents available to this agent's tool handlers via `requestSubAgent`. */
+    subAgents?: AgentConfig[];
+    /** Opt this agent in to manual picker selection. */
+    manualSelection?: ManualSelectionConfig;
+    /** How the main chat input behaves while this agent is executing. */
+    chatInputDuringExecution?: ChatInputDuringExecutionMode;
+    /**
+     * Construct the agent-scoped state. Called by the framework when this agent
+     * becomes active (`onActivate`). Awaited before the agent's first turn runs.
+     */
+    init: (ctx: AgentLifecycleContext) => S | Promise<S>;
+    /**
+     * Tear down the agent-scoped state. Called when the agent is being replaced.
+     * Awaited before the incoming agent's `init` runs.
+     */
+    dispose?: (ctx: AgentLifecycleContext & {
+        state: S;
+    }) => void | Promise<void>;
+    /**
+     * System prompt composed from current state. Resolved each tool-loop
+     * iteration. Use this to feed the LLM whatever the current state implies
+     * (e.g. a state machine's `meta.systemPrompt` plus captured context).
+     */
+    systemPrompt?: (ctx: SystemPromptContext & {
+        state: S;
+    }) => string | Promise<string>;
+    /**
+     * Tool definitions the LLM sees. Either a static array (resolved once) or a
+     * function resolved each tool-loop iteration. The function form is how a
+     * machine-driven agent narrows the surface per state.
+     *
+     * **Constraint:** the resolved handlers (returned from {@link StatefulAgentInit.toolHandlers})
+     * must not include fold facades. Folds are an LLM-driven UX optimisation
+     * that competes with the machine for control of the tool view; one of them
+     * has to be in charge. Helper throws at init time if a fold-tagged handler
+     * is detected.
+     */
+    toolDefinitions?: ChatToolDefinition[] | ((ctx: SystemPromptContext & {
+        state: S;
+    }) => ChatToolDefinition[] | Promise<ChatToolDefinition[]>);
+    /**
+     * Factory returning the tool handler map. Called with the live `state` at
+     * `onActivate` time; the handlers it returns are cached for the lifetime of
+     * this activation. Each handler closes over `state` and any other deps you
+     * captured.
+     *
+     * The handler set returned must be the **union** of every tool name your
+     * agent might advertise across all states — `toolDefinitions` filters which
+     * are visible to the LLM per turn, but every name still needs an entry here.
+     */
+    toolHandlers?: (state: S) => ChatToolHandlers;
+    /**
+     * Optional getter for the debug-log snapshot. Defaults to auto-snapshotting
+     * any property on `state` that looks like a foundation-state-machine
+     * instance (has `state`, `context`, and `complete` fields). Override when
+     * the default doesn't capture what you need — e.g. multiple machines, or
+     * non-machine state worth recording.
+     *
+     * Return value must be JSON-serializable.
+     */
+    getDebugSnapshot?: (state: S) => unknown;
 }
 
 /**
@@ -1161,6 +1460,32 @@ export declare type SuggestionsState = {
     message: string;
 };
 
+/**
+ * Context passed to the function form of `systemPrompt` / `toolDefinitions`.
+ * Resolved each tool-loop iteration so the agent can vary what the LLM sees per turn.
+ *
+ * @beta
+ */
+export declare interface SystemPromptContext {
+    /** The active agent's name. */
+    agentName: string;
+    /** Full conversation history up to (but not including) the message being processed. */
+    history: ReadonlyArray<ChatMessage>;
+    /** 0 = first LLM call this turn; > 0 = retry or subsequent tool-loop iteration. */
+    turnIndex: number;
+    /** Aborted if the turn is cancelled. */
+    signal: AbortSignal;
+}
+
+/**
+ * System prompt for an agent. Either a static string (resolved once) or a function
+ * resolved each tool-loop iteration. The function form lets the agent compute the
+ * prompt from external state — e.g. a state machine's current step.
+ *
+ * @beta
+ */
+export declare type SystemPromptInput = string | ((ctx: SystemPromptContext) => string | Promise<string>);
+
 /**
  * Symbol used to attach ToolFold metadata to a facade handler function.
  * The ChatDriver inspects this to detect fold facades at runtime.
@@ -1169,6 +1494,16 @@ export declare type SuggestionsState = {
  */
 export declare const TOOL_FOLD_SYMBOL: unique symbol;
 
+/**
+ * Tool definitions for an agent. Either a static array (the conventional shape) or
+ * a function resolved each tool-loop iteration. The function form lets the agent
+ * narrow the tool surface per turn — e.g. expose only the tools valid in the
+ * current state of a state machine.
+ *
+ * @beta
+ */
+export declare type ToolDefinitionsInput = ChatToolDefinition[] | ((ctx: SystemPromptContext) => ChatToolDefinition[] | Promise<ChatToolDefinition[]>);
+
 /**
  * Internal metadata for a tool fold. Attached to the facade handler via TOOL_FOLD_SYMBOL.
  *
@@ -1224,4 +1559,29 @@ export declare interface ToolTreeNode extends ChatToolDefinition {
     tools?: ToolTreeNode[];
 }
 
+/**
+ * One captured frame of what the LLM saw on a single tool-loop iteration.
+ * The driver records these as a ring buffer (cap: configurable via
+ * `chatConfig.agent.maxTurnSnapshots`, default 40) so the export log can show,
+ * per turn: which agent was active, the resolved system prompt, the tool names
+ * visible to the LLM, and any agent-supplied debug snapshot (e.g. machine
+ * state for stateful agents).
+ *
+ * @beta
+ */
+export declare interface TurnSnapshot {
+    /** Monotonic counter across the driver's lifetime (does not reset on agent swap). */
+    turnIndex: number;
+    /** ISO timestamp captured just before the LLM call. */
+    timestamp: string;
+    /** Name of the agent active when this LLM call ran. */
+    agentName?: string;
+    /** Final system prompt sent to the LLM (post-fold-suffix, post-retry hint). */
+    systemPrompt?: string;
+    /** Tool names sent to the LLM, in order — definitions are static per name so names alone suffice. */
+    toolNames: string[];
+    /** Agent-supplied snapshot — machine state/context for stateful agents, undefined otherwise. */
+    agentSnapshot?: unknown;
+}
+
 export { }

package/dist/dts/components/ai-driver/ai-driver.d.ts

@@ -1,4 +1,5 @@
 import type { ChatAttachment, ChatDriverResult, ChatMessage, ChatToolDefinition } from '@genesislcap/foundation-ai';
+import type { TurnSnapshot } from '../chat-driver/chat-driver';
 /** @internal */
 export interface AllAgentSummary {
     name: string;
@@ -48,5 +49,12 @@ export interface AiDriver extends EventTarget {
      * Get query suggestions from the AI.
      */
     getSuggestions(history: ChatMessage[], prompt: string, count: number, allAgentInfo?: AllAgentSummary[]): Promise<string[]>;
+    /**
+     * Per-LLM-call snapshots — what the model saw each turn (prompt, tools,
+     * agent state). Used by the host's debug-log exporter. Optional because the
+     * interface is implemented by both leaf and orchestrating drivers; the
+     * orchestrator just delegates to its inner `ChatDriver`.
+     */
+    getTurnSnapshots?(): ReadonlyArray<TurnSnapshot>;
 }
 //# sourceMappingURL=ai-driver.d.ts.map

package/dist/dts/components/ai-driver/ai-driver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ai-driver.d.ts","sourceRoot":"","sources":["../../../../src/components/ai-driver/ai-driver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EAChB,WAAW,EACX,kBAAkB,EACnB,MAAM,4BAA4B,CAAC;AAEpC,gBAAgB;AAChB,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,kBAAkB,EAAE,CAAC;CAC7B;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,QAAS,SAAQ,WAAW;IAC3C;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAEtF;;;;;OAKG;IACH,mBAAmB,CAAC,eAAe,CAAC,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAEhF;;OAEG;IACH,kBAAkB,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IAEjE;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IAE3C;;OAEG;IACH,aAAa,CAAC,IAAI,SAAS,WAAW,EAAE,CAAC;IAEzC;;OAEG;IACH,MAAM,IAAI,OAAO,CAAC;IAElB;;OAEG;IACH,cAAc,CACZ,OAAO,EAAE,WAAW,EAAE,EACtB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,YAAY,CAAC,EAAE,eAAe,EAAE,GAC/B,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CACtB"}
+{"version":3,"file":"ai-driver.d.ts","sourceRoot":"","sources":["../../../../src/components/ai-driver/ai-driver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EAChB,WAAW,EACX,kBAAkB,EACnB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE/D,gBAAgB;AAChB,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,kBAAkB,EAAE,CAAC;CAC7B;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,QAAS,SAAQ,WAAW;IAC3C;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAEtF;;;;;OAKG;IACH,mBAAmB,CAAC,eAAe,CAAC,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAEhF;;OAEG;IACH,kBAAkB,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IAEjE;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IAE3C;;OAEG;IACH,aAAa,CAAC,IAAI,SAAS,WAAW,EAAE,CAAC;IAEzC;;OAEG;IACH,MAAM,IAAI,OAAO,CAAC;IAElB;;OAEG;IACH,cAAc,CACZ,OAAO,EAAE,WAAW,EAAE,EACtB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,YAAY,CAAC,EAAE,eAAe,EAAE,GAC/B,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAErB;;;;;OAKG;IACH,gBAAgB,CAAC,IAAI,aAAa,CAAC,YAAY,CAAC,CAAC;CAClD"}

package/dist/dts/components/chat-driver/chat-driver.d.ts

@@ -1,5 +1,5 @@
-import type { AIProvider, ChatAttachment, ChatDriverResult, ChatMessage, ChatToolDefinition, ChatToolHandlers } from '@genesislcap/foundation-ai';
-import type { AgentConfig } from '../../config/config';
+import type { AIProvider, ChatAttachment, ChatDriverResult, ChatMessage, ChatToolHandlers } from '@genesislcap/foundation-ai';
+import type { AgentConfig, SystemPromptInput, ToolDefinitionsInput } from '../../config/config';
 import type { AiDriver, AllAgentSummary } from '../ai-driver/ai-driver';
 /** Name reserved for the cross-agent handoff tool — injected by OrchestratingDriver. */
 export declare const REQUEST_CONTINUATION_TOOL = "request_continuation";
@@ -9,6 +9,30 @@ export declare const REQUEST_CONTINUATION_TOOL = "request_continuation";
  * @beta
  */
 export type ChatHistoryUpdatedEvent = CustomEvent<ReadonlyArray<ChatMessage>>;
+/**
+ * One captured frame of what the LLM saw on a single tool-loop iteration.
+ * The driver records these as a ring buffer (cap: configurable via
+ * `chatConfig.agent.maxTurnSnapshots`, default 40) so the export log can show,
+ * per turn: which agent was active, the resolved system prompt, the tool names
+ * visible to the LLM, and any agent-supplied debug snapshot (e.g. machine
+ * state for stateful agents).
+ *
+ * @beta
+ */
+export interface TurnSnapshot {
+    /** Monotonic counter across the driver's lifetime (does not reset on agent swap). */
+    turnIndex: number;
+    /** ISO timestamp captured just before the LLM call. */
+    timestamp: string;
+    /** Name of the agent active when this LLM call ran. */
+    agentName?: string;
+    /** Final system prompt sent to the LLM (post-fold-suffix, post-retry hint). */
+    systemPrompt?: string;
+    /** Tool names sent to the LLM, in order — definitions are static per name so names alone suffice. */
+    toolNames: string[];
+    /** Agent-supplied snapshot — machine state/context for stateful agents, undefined otherwise. */
+    agentSnapshot?: unknown;
+}
 /**
  * Plain TS class that drives a multi-turn chat conversation, including the tool-call loop.
  * Owned by `FoundationAiAssistant` — created in `connectedCallback`, torn down in `disconnectedCallback`.
@@ -26,7 +50,19 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
     private busy;
     private pendingInteractions;
     private systemPrompt?;
+    /**
+     * Resolved tool definitions visible to the LLM. Folds mutate this in place
+     * (push/pop on open/close). When `toolDefinitionsFactory` is set, this is
+     * overwritten each tool-loop iteration with the factory's output.
+     */
     private toolDefinitions;
+    /**
+     * Optional dynamic-tools source. When set, called each tool-loop iteration
+     * to recompute `toolDefinitions` before the LLM call. `defineStatefulAgent`
+     * forbids folds when this is set, so the fold-mutation path is unreachable
+     * in that case.
+     */
+    private toolDefinitionsFactory?;
     private toolHandlers;
     private primerHistory?;
     private activeAgentName?;
@@ -58,7 +94,28 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * `undefined` means the loop has not been stopped early.
      */
     private subAgentCompletion;
-    constructor(aiProvider: AIProvider, toolHandlers?: ChatToolHandlers, toolDefinitions?: ChatToolDefinition[], systemPrompt?: string, primerHistory?: ChatMessage[], maxToolIterations?: number, maxFoldOperations?: number);
+    /**
+     * Set by `releaseAgent` inside a top-level tool handler — typically a stateful
+     * agent's terminal-state handler signalling that its flow is complete and the
+     * auto-pin lock can release. Checked by the orchestrator after `sendMessage`
+     * returns; the orchestrator fires `onDeactivate` and clears the pin.
+     *
+     * Reset at the start of each `sendMessage` so a release from a previous turn
+     * doesn't leak forward.
+     */
+    private agentReleaseRequested;
+    /**
+     * Ring buffer of per-LLM-call snapshots. Cap is configurable via
+     * `chatConfig.agent.maxTurnSnapshots`; older entries drop off as new ones
+     * arrive. See {@link TurnSnapshot} for the captured shape.
+     */
+    private turnSnapshots;
+    /** Monotonic counter that survives agent swaps — useful for cross-referencing with history. */
+    private globalTurnIndex;
+    /** Captured from `applyAgent` so we don't store the whole `AgentConfig`. */
+    private debugSnapshotter?;
+    private readonly maxTurnSnapshots;
+    constructor(aiProvider: AIProvider, toolHandlers?: ChatToolHandlers, toolDefinitions?: ToolDefinitionsInput, systemPrompt?: SystemPromptInput, primerHistory?: ChatMessage[], maxToolIterations?: number, maxFoldOperations?: number, maxTurnSnapshots?: number);
     /**
      * Swap in a new agent's configuration. Called by OrchestratingDriver before
      * each specialist turn so the shared driver runs with the right tools and prompt.
@@ -71,6 +128,25 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
     getSubAgentCompletion(): {
         result: unknown;
     } | undefined;
+    /**
+     * Returns true if `releaseAgent` was called during the most recent turn.
+     * Consumed by the orchestrator to trigger the auto-pin release path.
+     */
+    getAgentReleaseRequested(): boolean;
+    /**
+     * Return the per-turn snapshots captured so far. Used by the host's debug
+     * log exporter to show what the LLM saw on each turn — system prompt, tool
+     * surface, and agent-supplied state (e.g. a machine snapshot).
+     *
+     * Ring-buffered at `MAX_TURN_SNAPSHOTS`; older entries are dropped.
+     */
+    getTurnSnapshots(): ReadonlyArray<TurnSnapshot>;
+    /**
+     * Push one snapshot to the ring buffer. Called inside `runToolLoop` just
+     * before each LLM call — that's the latest point where the prompt, tool
+     * surface, and agent state line up with what the model is about to see.
+     */
+    private recordTurnSnapshot;
     /**
      * Optional transform applied to conversation history immediately before each LLM request.
      * Cleared when `undefined`. Does not alter stored history.