@genesislcap/ai-assistant 14.434.0 → 14.436.0

package/dist/esm/config/define-stateful-agent.js

@@ -0,0 +1,174 @@
+import { __awaiter, __rest } from "tslib";
+import { TOOL_FOLD_SYMBOL } from '../utils/tool-fold';
+/**
+ * Walk a state object and snapshot any machine-shaped values found on it.
+ * Recognises foundation-state-machine instances by structural shape rather
+ * than `instanceof`, so the helper stays free of a runtime dep on
+ * foundation-state-machine.
+ *
+ * Strips the `errors`/`error` framework noise from each machine's context —
+ * these are foundation-state-machine internals (an ErrorMap instance and its
+ * last-error pointer) that bloat the debug payload without aiding debugging.
+ */
+function defaultStatefulDebugSnapshot(state) {
+    var _a;
+    if (!state || typeof state !== 'object')
+        return state;
+    const result = {};
+    for (const [key, val] of Object.entries(state)) {
+        if (val && typeof val === 'object' && 'state' in val && 'context' in val && 'complete' in val) {
+            const m = val;
+            const ctx = (_a = m.context) !== null && _a !== void 0 ? _a : {};
+            const { errors: _e, error: _err } = ctx, userContext = __rest(ctx, ["errors", "error"]);
+            result[key] = {
+                state: m.state,
+                context: userContext,
+                complete: m.complete,
+                output: m.output,
+            };
+        }
+    }
+    return Object.keys(result).length
+        ? result
+        : '<no auto-snapshot — state has no machine-shaped properties; provide getDebugSnapshot>';
+}
+/**
+ * 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 function defineStatefulAgent(opts) {
+    let state;
+    let cachedHandlers;
+    const assertNoFolds = (handlers) => {
+        for (const [name, handler] of Object.entries(handlers)) {
+            if (handler[TOOL_FOLD_SYMBOL]) {
+                throw new Error(`Stateful agent "${opts.name}" tool "${name}" carries fold metadata. ` +
+                    `Folds and state-machine-driven tool filtering both try to control the ` +
+                    `LLM's tool view — pick one. Remove the fold or migrate this agent to ` +
+                    `a non-stateful AgentConfig.`);
+            }
+        }
+    };
+    // Wrap the optional dynamic-tools factory so it threads `state` in and asserts
+    // we never accidentally resolved a fold-tagged tool. Static arrays are passed
+    // through unchanged.
+    const wrappedTools = (() => {
+        const td = opts.toolDefinitions;
+        if (typeof td === 'function') {
+            return (ctx) => __awaiter(this, void 0, void 0, function* () {
+                if (!state) {
+                    throw new Error(`Stateful agent "${opts.name}" tools called before init`);
+                }
+                return td(Object.assign(Object.assign({}, ctx), { state }));
+            });
+        }
+        return td;
+    })();
+    // Each proxy entry calls into `cachedHandlers`, which is populated eagerly
+    // inside `onActivate` (see below). Eager population means the no-folds
+    // assertion fires at activation time — not on first tool call — so a
+    // misconfigured agent fails loud and immediately instead of silently
+    // appearing to work until the LLM happens to invoke a tool.
+    const buildHandlerProxy = (names) => {
+        const out = {};
+        for (const name of names) {
+            out[name] = (args, ctx) => __awaiter(this, void 0, void 0, function* () {
+                if (!state || !cachedHandlers) {
+                    throw new Error(`Stateful agent "${opts.name}" handler called before init`);
+                }
+                const handler = cachedHandlers[name];
+                if (!handler) {
+                    throw new Error(`Tool "${name}" has no handler on stateful agent "${opts.name}"`);
+                }
+                return handler(args, ctx);
+            });
+        }
+        return out;
+    };
+    // Static-tools case: handler names are knowable from the definitions array.
+    // Dynamic-tools case: we discover names from a sample of `toolHandlers(state)`
+    // taken inside onActivate. Until then, the handler dict is empty — fine
+    // because no tool call can happen before activation completes.
+    const staticHandlerProxy = Array.isArray(opts.toolDefinitions) && opts.toolHandlers
+        ? buildHandlerProxy(opts.toolDefinitions.map((d) => d.name))
+        : undefined;
+    // For the dynamic case we patch this object in place on activation. The
+    // driver reads `toolHandlers` by reference, so mutating in place is enough.
+    const resolvedHandlers = staticHandlerProxy !== null && staticHandlerProxy !== void 0 ? staticHandlerProxy : {};
+    const base = {
+        name: opts.name,
+        primerHistory: opts.primerHistory,
+        subAgents: opts.subAgents,
+        manualSelection: opts.manualSelection,
+        chatInputDuringExecution: opts.chatInputDuringExecution,
+        toolDefinitions: wrappedTools,
+        toolHandlers: opts.toolHandlers ? resolvedHandlers : undefined,
+        onActivate: (ctx) => __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            state = yield opts.init(ctx);
+            // Sample handlers eagerly and validate up-front. Throws here are visible
+            // at the agent-switch boundary instead of buried inside a future tool
+            // dispatch.
+            cachedHandlers = (_b = (_a = opts.toolHandlers) === null || _a === void 0 ? void 0 : _a.call(opts, state)) !== null && _b !== void 0 ? _b : {};
+            assertNoFolds(cachedHandlers);
+            // Dynamic-tools path: handler names are discovered from the sample.
+            if (!staticHandlerProxy && opts.toolHandlers) {
+                const dynamicProxy = buildHandlerProxy(Object.keys(cachedHandlers));
+                for (const key of Object.keys(resolvedHandlers))
+                    delete resolvedHandlers[key];
+                Object.assign(resolvedHandlers, dynamicProxy);
+            }
+        }),
+        onDeactivate: (ctx) => __awaiter(this, void 0, void 0, function* () {
+            if (state !== undefined && opts.dispose) {
+                yield opts.dispose(Object.assign(Object.assign({}, ctx), { state }));
+            }
+            // Orchestrator serializes onActivate/onDeactivate; concurrent calls
+            // cannot interleave the read-then-write of `state`.
+            // eslint-disable-next-line require-atomic-updates
+            state = undefined;
+            cachedHandlers = undefined;
+        }),
+        systemPrompt: opts.systemPrompt
+            ? (ctx) => __awaiter(this, void 0, void 0, function* () {
+                if (!state) {
+                    throw new Error(`Stateful agent "${opts.name}" systemPrompt called before init`);
+                }
+                return opts.systemPrompt(Object.assign(Object.assign({}, ctx), { state }));
+            })
+            : undefined,
+        // Called per LLM call by ChatDriver, and once at debug-log export time.
+        // Returns `undefined` before activation (state hasn't been built yet) and
+        // after deactivation (state was disposed) — the snapshotter is best-effort
+        // and the driver tolerates undefined.
+        getDebugSnapshot: () => {
+            if (!state)
+                return undefined;
+            return opts.getDebugSnapshot
+                ? opts.getDebugSnapshot(state)
+                : defaultStatefulDebugSnapshot(state);
+        },
+    };
+    return Object.assign(Object.assign({}, base), { description: opts.description, excludeFromClassifier: opts.excludeFromClassifier });
+}

package/dist/esm/index.js

@@ -9,6 +9,7 @@ export * from './components/popout-manager';
 export * from './channel/ai-activity-channel';
 export * from './channel/ai-activity-bus';
 export * from './config/config';
+export * from './config/define-stateful-agent';
 export * from './config/fallback-agents';
 export * from './utils/tool-fold';
 export { AiChatMarkdown } from './components/chat-markdown/chat-markdown';

package/dist/esm/main/main.js

@@ -69,11 +69,19 @@ const MODEL_CONTEXT_LIMITS = {
 };
 // Register supporting components when the main component module is imported.
 avoidTreeShaking(AiChatMarkdown, AiChatInteractionWrapper, AiHaloOverlay, AiChatBubble, AiActivityHalo, ChatSuggestions, AgentPicker);
-/** Recursively strips `toolHandlers` from an agent and all its sub-agents. */
+/**
+ * Recursively strips non-serializable fields from an agent before storing in Redux:
+ *  - `toolHandlers` (functions),
+ *  - `onActivate` / `onDeactivate` (lifecycle hooks, functions),
+ *  - function-form `systemPrompt` / `toolDefinitions` (downgraded to `undefined`
+ *    in the snapshot — the live config on the driver is still the source of
+ *    truth; the slice only stores a serializable projection).
+ */
 function stripHandlers(agent) {
-    const { toolHandlers: _, subAgents } = agent, rest = __rest(agent, ["toolHandlers", "subAgents"]);
+    const { toolHandlers: _h, onActivate: _on, onDeactivate: _off, getDebugSnapshot: _g, subAgents, systemPrompt, toolDefinitions } = agent, rest = __rest(agent, ["toolHandlers", "onActivate", "onDeactivate", "getDebugSnapshot", "subAgents", "systemPrompt", "toolDefinitions"]);
+    const stripped = Object.assign(Object.assign({}, rest), { systemPrompt: typeof systemPrompt === 'function' ? undefined : systemPrompt, toolDefinitions: typeof toolDefinitions === 'function' ? undefined : toolDefinitions });
     return (subAgents === null || subAgents === void 0 ? void 0 : subAgents.length)
-        ? Object.assign(Object.assign({}, rest), { subAgents: subAgents.map(stripHandlers) }) : rest;
+        ? Object.assign(Object.assign({}, stripped), { subAgents: subAgents.map(stripHandlers) }) : stripped;
 }
 /**
  * Foundation AI Assistant component.
@@ -443,8 +451,15 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         if (this.driver.isBusy())
             return;
         const history = (_c = (_b = (_a = this.driver).getRawHistory) === null || _b === void 0 ? void 0 : _b.call(_a)) !== null && _c !== void 0 ? _c : [];
+        const oldDriver = this.driver;
         this.unwireDriver();
         deleteDriver(key);
+        // Fire the active agent's `onDeactivate` so machines / per-agent state get
+        // torn down before the replacement driver instantiates them again. Fire
+        // and forget — the old driver is about to be GC'd, errors are non-fatal.
+        if (oldDriver && 'dispose' in oldDriver && typeof oldDriver.dispose === 'function') {
+            void oldDriver.dispose();
+        }
         this.driver = getOrCreateDriver(key, () => this.createDriver());
         this.wireDriver();
         if (history.length)
@@ -469,22 +484,64 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
      * 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.
+     */
+    warnUnreachableStatefulAgents() {
+        var _a, _b;
+        const pickerDisabled = this.agentPicker === 'disabled';
+        for (const a of (_a = this.agents) !== null && _a !== void 0 ? _a : []) {
+            const isStateful = !!(a.onActivate || a.onDeactivate);
+            if (!isStateful)
+                continue;
+            // Specialists only — defineStatefulAgent rejects fallback.
+            const excluded = 'excludeFromClassifier' in a && a.excludeFromClassifier === true;
+            if (!excluded)
+                continue;
+            const manual = ((_b = a.manualSelection) === null || _b === void 0 ? void 0 : _b.enabled) === true;
+            if (manual && !pickerDisabled)
+                continue;
+            const reason = pickerDisabled
+                ? 'the picker is disabled at chatConfig.picker.mode'
+                : 'manualSelection.enabled is not set on the agent';
+            logger.warn(`Stateful agent "${a.name}" is unreachable: excludeFromClassifier is true and ${reason}. ` +
+                'Either remove excludeFromClassifier, enable manualSelection on the agent, or enable the picker.');
+        }
+    }
     createDriver() {
-        var _a, _b, _c;
+        var _a, _b;
+        this.warnUnreachableStatefulAgents();
         const agent = (_a = this.chatConfig.agent) !== null && _a !== void 0 ? _a : {};
         const { agents } = this;
-        if (agents && agents.length > 1) {
+        // Always route through OrchestratingDriver when agents are configured —
+        // even with a single agent — so lifecycle hooks (`onActivate`/
+        // `onDeactivate`), auto-pin, and release semantics fire uniformly. The
+        // classifier short-circuits when there's only one viable candidate, so
+        // single-agent setups pay no LLM cost for routing. With no agents
+        // configured at all, fall back to a bare ChatDriver — there's nothing to
+        // orchestrate and no hooks to fire.
+        if (agents && agents.length > 0) {
+            if (agents.length === 1 && !agents[0].fallback) {
+                // Preset for getters that read activeAgent before the first turn
+                // (e.g. chatInputDuringExecution). The orchestrator will overwrite
+                // this via `agent-changed` once applyAgent fires on first sendMessage.
+                this.activeAgent = agents[0];
+            }
             return new OrchestratingDriver(this.aiProvider, agents, {
+                sessionKey: (_b = this.getStateKey()) !== null && _b !== void 0 ? _b : '',
                 maxHandoffs: agent.maxHandoffs,
                 classifierHistoryLength: agent.classifierHistoryLength,
                 classifierRetries: agent.classifierRetries,
                 maxToolIterations: agent.maxToolIterations,
                 maxFoldOperations: agent.maxFoldOperations,
+                maxTurnSnapshots: agent.maxTurnSnapshots,
             });
         }
-        const singleAgent = agents === null || agents === void 0 ? void 0 : agents[0];
-        this.activeAgent = singleAgent;
-        return new ChatDriver(this.aiProvider, (_b = singleAgent === null || singleAgent === void 0 ? void 0 : singleAgent.toolHandlers) !== null && _b !== void 0 ? _b : {}, (_c = singleAgent === null || singleAgent === void 0 ? void 0 : singleAgent.toolDefinitions) !== null && _c !== void 0 ? _c : [], singleAgent === null || singleAgent === void 0 ? void 0 : singleAgent.systemPrompt, singleAgent === null || singleAgent === void 0 ? void 0 : singleAgent.primerHistory, agent.maxToolIterations, agent.maxFoldOperations);
+        return new ChatDriver(this.aiProvider, {}, [], undefined, undefined, agent.maxToolIterations, agent.maxFoldOperations, agent.maxTurnSnapshots);
     }
     /**
      * Attaches event listeners to the current driver. Stores a cleanup function
@@ -550,10 +607,22 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
             const onAgentChanged = (e) => {
                 this.activeAgent = e.detail;
             };
+            // Orchestrator-initiated pin changes (auto-pin on stateful activation,
+            // auto-clear on release). User-initiated pins flow the other direction
+            // via the `pinnedAgentName` setter, which already calls setPinnedAgent
+            // back into the driver — guard against the redundant round-trip.
+            const onPinnedChanged = (e) => {
+                var _a, _b;
+                const name = e.detail;
+                if (((_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.store.aiAssistant.pinnedAgentName) !== name) {
+                    (_b = this._sessionRef) === null || _b === void 0 ? void 0 : _b.actions.aiAssistant.setPinnedAgentName(name);
+                }
+            };
             driver.addEventListener('orchestrating-start', onOrchStart);
             driver.addEventListener('orchestrating-stop', onOrchStop);
             driver.addEventListener('agent-changed', onAgentChanged);
-            cleanups.push(() => driver.removeEventListener('orchestrating-start', onOrchStart), () => driver.removeEventListener('orchestrating-stop', onOrchStop), () => driver.removeEventListener('agent-changed', onAgentChanged));
+            driver.addEventListener('pinned-changed', onPinnedChanged);
+            cleanups.push(() => driver.removeEventListener('orchestrating-start', onOrchStart), () => driver.removeEventListener('orchestrating-stop', onOrchStop), () => driver.removeEventListener('agent-changed', onAgentChanged), () => driver.removeEventListener('pinned-changed', onPinnedChanged));
         }
         this.driverCleanup = () => {
             for (const fn of cleanups)
@@ -570,7 +639,7 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         this.driverCleanup = undefined;
     }
     connectedCallback() {
-        var _a, _b, _c, _d, _e, _f, _g;
+        var _a, _b, _c, _d, _e, _f, _j;
         // Initialise the store reference BEFORE super.connectedCallback() so that
         // the first FAST render has access to the store. The store Proxy calls
         // Observable.track(observableStore, sliceName) whenever a slice is read,
@@ -621,7 +690,7 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
             // Subscribe once so that when the originating send() completes (possibly on a
             // different element instance that has since disconnected), this element cleans up
             // its own timer, syncs the halo, and triggers the post-response suggestion fetch.
-            this._executionCompletionUnsub = (_g = this._sessionRef) === null || _g === void 0 ? void 0 : _g.subscribeKey((s) => s.aiAssistant.state, () => {
+            this._executionCompletionUnsub = (_j = this._sessionRef) === null || _j === void 0 ? void 0 : _j.subscribeKey((s) => s.aiAssistant.state, () => {
                 var _a, _b;
                 if (((_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.store.aiAssistant.state) === 'idle') {
                     this.stopLoadingTimer();
@@ -856,6 +925,44 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
             return undefined;
         return (_c = (_b = (_a = this.agents) === null || _a === void 0 ? void 0 : _a.find((a) => a.name === this.pinnedAgentName)) === null || _b === void 0 ? void 0 : _b.manualSelection) === null || _c === void 0 ? void 0 : _c.hint;
     }
+    /**
+     * 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() {
+        var _a;
+        if (!this.activeAgent)
+            return false;
+        const live = (_a = this.agents) === null || _a === void 0 ? void 0 : _a.find((a) => a.name === this.activeAgent.name);
+        if (!live)
+            return false;
+        return !!(live.onActivate || live.onDeactivate);
+    }
+    /** Tooltip shown on the picker toggle button. */
+    get agentToggleTitle() {
+        var _a;
+        if (this.pinLocked) {
+            const name = (_a = this.pinnedAgentName) !== null && _a !== void 0 ? _a : 'This agent';
+            return `${name} is in the middle of a guided flow. Agent switching is disabled until the flow completes.`;
+        }
+        if (this.agentPickerOpen) {
+            return 'Close agent picker';
+        }
+        if (this.pinnedAgentName !== null) {
+            return this.pinnedAgentHint
+                ? `${this.pinnedAgentName} — ${this.pinnedAgentHint}`
+                : this.pinnedAgentName;
+        }
+        return 'Attempts to route messages to the correct available agent. Click to manually pin an agent.';
+    }
     /**
      * 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
@@ -897,21 +1004,46 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         this.enabledAnimations = animations;
     }
     getDebugLog() {
-        var _a, _b, _c, _d, _e, _f, _g;
+        var _a, _b, _c, _d, _e, _f, _j, _k, _l, _m, _o, _p, _q;
         const timestamp = new Date().toISOString().replace(/:/g, '-');
+        // Live agent reference — `this.activeAgent` is the redux-stripped projection,
+        // so getDebugSnapshot is not on it. Look up the live config from the agents
+        // array to get the function back.
+        const liveActiveAgent = this.activeAgent
+            ? (_a = this.agents) === null || _a === void 0 ? void 0 : _a.find((a) => a.name === this.activeAgent.name)
+            : undefined;
+        let activeDebugSnapshot;
+        try {
+            activeDebugSnapshot = (_b = liveActiveAgent === null || liveActiveAgent === void 0 ? void 0 : liveActiveAgent.getDebugSnapshot) === null || _b === void 0 ? void 0 : _b.call(liveActiveAgent);
+        }
+        catch (e) {
+            activeDebugSnapshot = `<getDebugSnapshot threw: ${e instanceof Error ? e.message : String(e)}>`;
+        }
         return {
-            messages: (_c = (_b = (_a = this.driver) === null || _a === void 0 ? void 0 : _a.getRawHistory) === null || _b === void 0 ? void 0 : _b.call(_a)) !== null && _c !== void 0 ? _c : this.messages,
+            messages: (_e = (_d = (_c = this.driver) === null || _c === void 0 ? void 0 : _c.getRawHistory) === null || _d === void 0 ? void 0 : _d.call(_c)) !== null && _e !== void 0 ? _e : this.messages,
             meta: {
                 timestamp,
                 host: window.location.host,
-                agentSummary: (_d = this.agents) === null || _d === void 0 ? void 0 : _d.map((a) => {
-                    var _a, _b;
-                    return (Object.assign(Object.assign({}, a), { toolDefinitions: expandToolTree((_a = a.toolDefinitions) !== null && _a !== void 0 ? _a : [], (_b = a.toolHandlers) !== null && _b !== void 0 ? _b : {}), toolHandlers: undefined }));
+                agentSummary: (_f = this.agents) === null || _f === void 0 ? void 0 : _f.map((a) => {
+                    var _a;
+                    return (Object.assign(Object.assign({}, a), { toolDefinitions: Array.isArray(a.toolDefinitions)
+                            ? expandToolTree(a.toolDefinitions, (_a = a.toolHandlers) !== null && _a !== void 0 ? _a : {})
+                            : typeof a.toolDefinitions === 'function'
+                                ? '<dynamic — resolved per turn>'
+                                : [], toolHandlers: undefined, onActivate: undefined, onDeactivate: undefined, getDebugSnapshot: undefined }));
                 }),
-                activeSystemPrompt: (_e = this.activeAgent) === null || _e === void 0 ? void 0 : _e.systemPrompt,
-                activePrimerHistory: (_f = this.activeAgent) === null || _f === void 0 ? void 0 : _f.primerHistory,
+                activeSystemPrompt: typeof ((_j = this.activeAgent) === null || _j === void 0 ? void 0 : _j.systemPrompt) === 'function'
+                    ? '<dynamic — resolved per turn>'
+                    : (_k = this.activeAgent) === null || _k === void 0 ? void 0 : _k.systemPrompt,
+                activePrimerHistory: (_l = this.activeAgent) === null || _l === void 0 ? void 0 : _l.primerHistory,
                 activeFoldStack: this.driver instanceof ChatDriver ? this.driver.getActiveFoldNames() : undefined,
-                debug: (_g = this.debugStateFactory) === null || _g === void 0 ? void 0 : _g.call(this),
+                // Snapshot captured fresh at log-export time — reflects state NOW, which
+                // may have transitioned since the last LLM call.
+                activeDebugSnapshot,
+                // Per-LLM-call timeline — pairs each turn with the prompt + tool surface
+                // + agent state that drove it. Capped to the most recent N entries.
+                turnSnapshots: (_p = (_o = (_m = this.driver) === null || _m === void 0 ? void 0 : _m.getTurnSnapshots) === null || _o === void 0 ? void 0 : _o.call(_m)) !== null && _p !== void 0 ? _p : [],
+                debug: (_q = this.debugStateFactory) === null || _q === void 0 ? void 0 : _q.call(this),
             },
         };
     }
@@ -1011,7 +1143,7 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
     }
     fetchSuggestions() {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b;
+            var _a;
             const suggestionsConfig = this.chatConfig.suggestions;
             if (!this.driver || !suggestionsConfig || suggestionsConfig.behavior === 'never') {
                 return;
@@ -1041,7 +1173,12 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
                     {
                         name: this.activeAgent.name,
                         description: 'description' in this.activeAgent ? this.activeAgent.description : '',
-                        tools: (_b = this.activeAgent.toolDefinitions) !== null && _b !== void 0 ? _b : [],
+                        // Dynamic-tools agents have no resolvable tool list outside a
+                        // per-turn context — suggestions just get an empty hint, matching
+                        // what `OrchestratingDriver.getSuggestions` does for them.
+                        tools: Array.isArray(this.activeAgent.toolDefinitions)
+                            ? this.activeAgent.toolDefinitions
+                            : [],
                     },
                 ]
                 : undefined;
@@ -1192,6 +1329,12 @@ __decorate([
 __decorate([
     volatile
 ], FoundationAiAssistant.prototype, "pinnedAgentHint", null);
+__decorate([
+    volatile
+], FoundationAiAssistant.prototype, "pinLocked", null);
+__decorate([
+    volatile
+], FoundationAiAssistant.prototype, "agentToggleTitle", null);
 __decorate([
     volatile
 ], FoundationAiAssistant.prototype, "pinnedAgentColour", null);

package/dist/esm/main/main.template.js

@@ -196,17 +196,8 @@ ${(tc) => { var _a; return (((_a = tc.foldPath) === null || _a === void 0 ? void
       class="agent-toggle-button"
       part="agent-toggle-button"
       appearance="stealth"
-      title=${(x) => {
-        var _a;
-        return x.agentPickerOpen
-            ? 'Close agent picker'
-            : x.pinnedAgentName !== null
-                ? x.pinnedAgentHint
-                    ? `${x.pinnedAgentName} — ${x.pinnedAgentHint}`
-                    : ((_a = x.pinnedAgentName) !== null && _a !== void 0 ? _a : '')
-                : 'Attempts to route messages to the correct available agent. Click to manually pin an agent.';
-    }}
-      ?disabled=${(x) => x.state === 'loading'}
+      title=${(x) => x.agentToggleTitle}
+      ?disabled=${(x) => x.state === 'loading' || x.pinLocked}
       @click=${(x) => x.toggleAgentPicker()}
     >
       ${when((x) => x.agentPickerOpen, html `<${iconTag} name="chevron-down"></${iconTag}>`)}

package/dist/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../src/index.ts","../src/channel/ai-activity-bus.ts","../src/channel/ai-activity-channel.ts","../src/components/halo-overlay.ts","../src/components/activity-halo/activity-halo.ts","../src/components/agent-picker/agent-picker.constants.ts","../src/components/agent-picker/agent-picker.styles.ts","../src/components/agent-picker/agent-picker.template.ts","../src/components/agent-picker/agent-picker.ts","../src/components/agent-picker/index.ts","../src/components/ai-driver/ai-driver.ts","../src/components/ai-driver/index.ts","../src/components/chat-bubble/chat-bubble.styles.ts","../src/components/chat-bubble/chat-bubble.template.ts","../src/components/chat-bubble/chat-bubble.ts","../src/components/chat-bubble/index.ts","../src/components/chat-driver/chat-driver.ts","../src/components/chat-driver/index.ts","../src/components/chat-interaction-wrapper/chat-interaction-wrapper.styles.ts","../src/components/chat-interaction-wrapper/chat-interaction-wrapper.template.ts","../src/components/chat-interaction-wrapper/chat-interaction-wrapper.ts","../src/components/chat-interaction-wrapper/index.ts","../src/components/chat-markdown/chat-markdown.ts","../src/components/chat-markdown/index.ts","../src/components/orchestrating-driver/index.ts","../src/components/orchestrating-driver/orchestrating-driver.ts","../src/components/popout-manager/index.ts","../src/components/popout-manager/popout-manager.ts","../src/config/config.ts","../src/config/fallback-agents.ts","../src/config/index.ts","../src/main/index.ts","../src/main/main.styles.ts","../src/main/main.template.ts","../src/main/main.ts","../src/main/main.types.ts","../src/state/ai-assistant-slice.ts","../src/state/driver-registry.ts","../src/state/session-store.ts","../src/styles/ai-colours.ts","../src/styles/index.ts","../src/styles/styles.ts","../src/suggestions/chat-suggestions.ts","../src/tags/index.ts","../src/types/ai-chat-widget.ts","../src/utils/animated-panel-toggle.ts","../src/utils/history-transform.ts","../src/utils/index.ts","../src/utils/logger.ts","../src/utils/tool-fold.ts"],"version":"5.9.2"}
+{"root":["../src/index.ts","../src/channel/ai-activity-bus.ts","../src/channel/ai-activity-channel.ts","../src/components/halo-overlay.ts","../src/components/activity-halo/activity-halo.ts","../src/components/agent-picker/agent-picker.constants.ts","../src/components/agent-picker/agent-picker.styles.ts","../src/components/agent-picker/agent-picker.template.ts","../src/components/agent-picker/agent-picker.ts","../src/components/agent-picker/index.ts","../src/components/ai-driver/ai-driver.ts","../src/components/ai-driver/index.ts","../src/components/chat-bubble/chat-bubble.styles.ts","../src/components/chat-bubble/chat-bubble.template.ts","../src/components/chat-bubble/chat-bubble.ts","../src/components/chat-bubble/index.ts","../src/components/chat-driver/chat-driver.ts","../src/components/chat-driver/index.ts","../src/components/chat-interaction-wrapper/chat-interaction-wrapper.styles.ts","../src/components/chat-interaction-wrapper/chat-interaction-wrapper.template.ts","../src/components/chat-interaction-wrapper/chat-interaction-wrapper.ts","../src/components/chat-interaction-wrapper/index.ts","../src/components/chat-markdown/chat-markdown.ts","../src/components/chat-markdown/index.ts","../src/components/orchestrating-driver/index.ts","../src/components/orchestrating-driver/orchestrating-driver.ts","../src/components/popout-manager/index.ts","../src/components/popout-manager/popout-manager.ts","../src/config/config.ts","../src/config/define-stateful-agent.ts","../src/config/fallback-agents.ts","../src/config/index.ts","../src/main/index.ts","../src/main/main.styles.ts","../src/main/main.template.ts","../src/main/main.ts","../src/main/main.types.ts","../src/state/ai-assistant-slice.ts","../src/state/driver-registry.ts","../src/state/session-store.ts","../src/styles/ai-colours.ts","../src/styles/index.ts","../src/styles/styles.ts","../src/suggestions/chat-suggestions.ts","../src/tags/index.ts","../src/types/ai-chat-widget.ts","../src/utils/animated-panel-toggle.ts","../src/utils/history-transform.ts","../src/utils/index.ts","../src/utils/logger.ts","../src/utils/tool-fold.ts"],"version":"5.9.2"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/ai-assistant",
   "description": "Genesis AI Assistant micro-frontend",
-  "version": "14.434.0",
+  "version": "14.436.0",
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
   "types": "dist/ai-assistant.d.ts",
@@ -64,24 +64,24 @@
     }
   },
   "devDependencies": {
-    "@genesislcap/foundation-testing": "14.434.0",
-    "@genesislcap/genx": "14.434.0",
-    "@genesislcap/rollup-builder": "14.434.0",
-    "@genesislcap/ts-builder": "14.434.0",
-    "@genesislcap/uvu-playwright-builder": "14.434.0",
-    "@genesislcap/vite-builder": "14.434.0",
-    "@genesislcap/webpack-builder": "14.434.0",
+    "@genesislcap/foundation-testing": "14.436.0",
+    "@genesislcap/genx": "14.436.0",
+    "@genesislcap/rollup-builder": "14.436.0",
+    "@genesislcap/ts-builder": "14.436.0",
+    "@genesislcap/uvu-playwright-builder": "14.436.0",
+    "@genesislcap/vite-builder": "14.436.0",
+    "@genesislcap/webpack-builder": "14.436.0",
     "@types/dompurify": "^3.0.5",
     "@types/marked": "^5.0.2"
   },
   "dependencies": {
-    "@genesislcap/foundation-ai": "14.434.0",
-    "@genesislcap/foundation-logger": "14.434.0",
-    "@genesislcap/foundation-redux": "14.434.0",
-    "@genesislcap/foundation-ui": "14.434.0",
-    "@genesislcap/foundation-utils": "14.434.0",
-    "@genesislcap/rapid-design-system": "14.434.0",
-    "@genesislcap/web-core": "14.434.0",
+    "@genesislcap/foundation-ai": "14.436.0",
+    "@genesislcap/foundation-logger": "14.436.0",
+    "@genesislcap/foundation-redux": "14.436.0",
+    "@genesislcap/foundation-ui": "14.436.0",
+    "@genesislcap/foundation-utils": "14.436.0",
+    "@genesislcap/rapid-design-system": "14.436.0",
+    "@genesislcap/web-core": "14.436.0",
     "dompurify": "^3.3.1",
     "marked": "^17.0.3"
   },
@@ -93,5 +93,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "ba7b16060050e905ef549b8eed08d67fe4e732d2"
+  "gitHead": "87ef9b53cc5f3030651cbc3126bd26f07ffd6819"
 }

package/src/components/ai-driver/ai-driver.ts

@@ -4,6 +4,7 @@ import type {
   ChatMessage,
   ChatToolDefinition,
 } from '@genesislcap/foundation-ai';
+import type { TurnSnapshot } from '../chat-driver/chat-driver';
 
 /** @internal */
 export interface AllAgentSummary {
@@ -66,4 +67,12 @@ export interface AiDriver extends EventTarget {
     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>;
 }