@fiodos/web-core 0.1.10 → 0.1.11

package/dist/esm/controller/AgentController.js

@@ -15,18 +15,19 @@
  *    deliberate modal tap; a loose "yes" never confirms them.
  *  - The agent only ever executes actions declared in the manifest.
  */
-import { combineContexts, createActionExecutor, createConsentManager, createSafeTelemetry, createSanitizer, createConversationSession, defaultRouteContextText, formatMessage, prepareConversationForTurn, recordConversationExchange, resolveConfirmationLexicon, resolveMessages, validateManifest, } from '@fiodos/core';
+import { combineContexts, createActionExecutor, createConsentManager, createSafeTelemetry, createSanitizer, buildBubbleExchangeWindow, BUBBLE_PAGE_EXCHANGES, conversationRetentionOptions, createConversationSession, persistConversationSession, restoreConversationSession, defaultRouteContextText, formatMessage, prepareConversationForTurn, recordConversationExchange, resolveConfirmationLexicon, resolveMessages, validateManifest, } from '@fiodos/core';
 import { AgentApiError } from '../api/errors.js';
 import { formatAgentTurnError } from '../api/formatTurnError.js';
 import { buildManifestPayload } from '../api/backendClient.js';
 import { createScreenContextStore, } from '../context/screenContextStore.js';
 import { createSpeechSession } from '../speech/speechSession.js';
 import { classifyPendingReply, decideAction, } from '../core/turnEngine.js';
-import { DEFAULT_AGENT_TIMINGS, } from '../config/types.js';
+import { DEFAULT_AGENT_TIMINGS, DEFAULT_AGENT_CHAINING, } from '../config/types.js';
 import { resolveUiMessages } from '../ui/messages.js';
 function randomSessionId() {
     return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
 }
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 export class AgentController {
     constructor(config) {
         this.enabled = true;
@@ -55,6 +56,21 @@ export class AgentController {
         // audio), skip the extra /preview-tts round-trip and speak via device voice.
         this.serverTtsUnavailable = false;
         this.pendingConsentIntent = null;
+        /** Parked chain state (set when a chain pauses on a sensitive action). */
+        this.chainState = null;
+        /** REAL live activity for the panel (replaces the old canned walk-through). */
+        this.liveActivity = null;
+        this.chainActive = false;
+        /** How many exchanges the bubble currently mounts (grows one page at a time). */
+        this.bubbleWindowSize = BUBBLE_PAGE_EXCHANGES;
+        /** Raw dashboard retention (minutes; 0 = never; null = default). Persisted
+         *  with the session so a restore applies the same expiry rule. */
+        this.conversationRetentionMinutes = null;
+        /** Persistence scope: internal orbs keep their memory under a separate key
+         *  so a public orb sharing the same appId can never read it. */
+        this.conversationScope = 'public';
+        this.loadingOlderExchanges = false;
+        this.loadOlderTimer = null;
         this.listeners = new Set();
         this.unsubscribeSpeech = null;
         // Fail fast on an invalid manifest — same contract as every platform.
@@ -81,6 +97,13 @@ export class AgentController {
             isAuthenticated: config.isAuthenticated,
         });
         this.timings = { ...DEFAULT_AGENT_TIMINGS, ...config.timings };
+        // Chaining OFF by default; clamp to the same safe bounds as react/react-native.
+        const chainingMerged = { ...DEFAULT_AGENT_CHAINING, ...config.chaining };
+        this.chaining = {
+            enabled: chainingMerged.enabled === true,
+            maxSteps: Math.max(1, Math.min(6, Math.floor(chainingMerged.maxSteps || 6))),
+            dwellMs: Math.max(0, Math.min(3000, Math.floor(chainingMerged.dwellMs ?? 450))),
+        };
         this.ttsLocale = config.ttsLocale ?? config.sttLocale;
         this.notifyError =
             config.notifyError ??
@@ -105,12 +128,34 @@ export class AgentController {
         });
         // Re-emit combined state whenever the speech machine advances.
         this.unsubscribeSpeech = this.speech.subscribe(() => this.emit());
+        // Rehydrate the previous conversation (page reloads): the persisted blob
+        // carries its own retention rule, so expiry is decided correctly even
+        // before the published config arrives. Best-effort and non-blocking.
+        void this.restorePersistedConversation();
+    }
+    // ── Conversation persistence (survives page reloads) ───────────────────────
+    async restorePersistedConversation() {
+        const restored = await restoreConversationSession(this.config.storage, this.config.manifest.appId, Date.now(), this.conversationScope);
+        if (!restored)
+            return;
+        // Never clobber turns the user already made while the restore resolved.
+        if (this.conversation.turns.length > 0 || this.conversation.uiArchive?.length)
+            return;
+        this.conversation.turns = restored.turns;
+        this.conversation.summary = restored.summary;
+        this.conversation.uiArchive = restored.uiArchive;
+        this.conversation.lastActivityAt = restored.lastActivityAt;
+        this.emit();
+    }
+    persistConversation() {
+        void persistConversationSession(this.config.storage, this.config.manifest.appId, this.conversation, this.conversationRetentionMinutes, this.conversationScope);
     }
     // ── Subscription / state ───────────────────────────────────────────────────
     getState() {
         const speech = this.speech.getSnapshot();
         const showWaveform = (this.phase === 'listening' || this.phase === 'confirming') && speech.state === 'recording';
         const showThinking = this.phase === 'thinking' || (this.phase === 'listening' && speech.state === 'transcribing');
+        const bubbleWindow = buildBubbleExchangeWindow(this.conversation, this.lastExchange, this.bubbleWindowSize, this.conversationOptions);
         return {
             phase: this.phase,
             interimText: speech.interimText,
@@ -120,12 +165,32 @@ export class AgentController {
             isBusy: showThinking || this.phase === 'speaking',
             isListening: this.phase === 'listening' && speech.state !== 'idle',
             lastExchange: this.lastExchange,
+            recentExchanges: bubbleWindow.exchanges,
+            hasOlderExchanges: bubbleWindow.hasOlder,
+            loadingOlderExchanges: this.loadingOlderExchanges,
             confirmationMessage: this.confirmationMessage,
             confirmationVoiceHint: this.confirmationVoiceHint,
             consentModalVisible: this.consentModalVisible,
             voiceBlocked: this.voiceBlocked,
+            liveActivity: this.liveActivity,
+            chainActive: this.chainActive,
         };
     }
+    /** Update the REAL live activity and re-render (no-op when unchanged). */
+    setActivity(next) {
+        const prev = this.liveActivity;
+        if (prev === next || (prev && next && prev.kind === next.kind && prev.label === next.label)) {
+            return;
+        }
+        this.liveActivity = next;
+        this.emit();
+    }
+    setChainActive(value) {
+        if (this.chainActive === value)
+            return;
+        this.chainActive = value;
+        this.emit();
+    }
     /** Whether speech recognition can actually run (API present AND mic not denied). */
     get voiceAvailable() {
         return this.config.voice.isRecognitionAvailable() && !this.voiceBlocked;
@@ -144,6 +209,53 @@ export class AgentController {
         this.voiceBlocked = blocked;
         this.emit();
     }
+    /**
+     * Page one more block of older session messages into the bubble (scroll-to-top).
+     * The mount is deferred behind a short loading state so old messages stream in
+     * on demand instead of all rendering at once (keeps the open bubble light).
+     */
+    loadOlderExchanges() {
+        if (this.loadingOlderExchanges)
+            return;
+        const win = buildBubbleExchangeWindow(this.conversation, this.lastExchange, this.bubbleWindowSize, this.conversationOptions);
+        if (!win.hasOlder)
+            return;
+        this.loadingOlderExchanges = true;
+        this.emit();
+        this.loadOlderTimer = setTimeout(() => {
+            this.loadOlderTimer = null;
+            this.bubbleWindowSize += BUBBLE_PAGE_EXCHANGES;
+            this.loadingOlderExchanges = false;
+            this.emit();
+        }, 350);
+    }
+    /**
+     * Apply the dashboard's context-retention setting (minutes; 0 = never clear,
+     * null/undefined = the 30-minute default). Called when the published config
+     * arrives/refreshes, so the developer's choice is live without a reload.
+     * `expandedMemory` = INTERNAL orb profile: use the expanded conversation
+     * memory window (more literal turns + longer rolling summary per request).
+     */
+    setConversationRetention(minutes, expandedMemory = false) {
+        this.conversationOptions = conversationRetentionOptions(minutes, expandedMemory);
+        this.conversationRetentionMinutes = typeof minutes === 'number' ? minutes : null;
+        const scope = expandedMemory ? 'internal' : 'public';
+        if (scope !== this.conversationScope) {
+            this.conversationScope = scope;
+            // The published profile arrived after the constructor's restore attempt:
+            // retry under the right storage key (guarded — never clobbers live turns).
+            void this.restorePersistedConversation();
+        }
+    }
+    /** Collapse the bubble history back to the initial page (bubble closed). */
+    resetBubbleWindow() {
+        if (this.loadOlderTimer) {
+            clearTimeout(this.loadOlderTimer);
+            this.loadOlderTimer = null;
+        }
+        this.loadingOlderExchanges = false;
+        this.bubbleWindowSize = BUBBLE_PAGE_EXCHANGES;
+    }
     subscribe(listener) {
         this.listeners.add(listener);
         return () => {
@@ -302,6 +414,11 @@ export class AgentController {
         if (this.phase === 'confirming')
             this.setPhase('idle');
         this.emit();
+        // REAL activity: the confirmed action is executing right now.
+        this.setActivity({
+            kind: 'executing',
+            label: this.actionLabel(pending.intent) ?? pending.intent,
+        });
         const result = await this.executor.execute(pending.action, pending.context);
         this.telemetry.logEvent({
             eventType: result.success ? 'action_executed' : 'action_failed',
@@ -315,6 +432,39 @@ export class AgentController {
             this.emit();
             await this.speakReply(result.message, null);
         }
+        // RESUME the autonomous chain if this sensitive action paused one — the
+        // human confirmation requirement is fully preserved: the chain only
+        // advances past a sensitive step AFTER the user confirmed and it executed.
+        const chainState = this.chainState;
+        if (chainState) {
+            this.chainState = null;
+            if (result.success && this.chaining.enabled) {
+                this.telemetry.logEvent({
+                    eventType: 'agent_chain_step',
+                    intentDetected: pending.intent,
+                    sessionId: this.sessionId,
+                    chainStep: chainState.step,
+                });
+                if (chainState.pendingKey)
+                    chainState.visitedKeys.add(chainState.pendingKey);
+                await this.runChainLoop({
+                    userMessage: chainState.userMessage,
+                    step: chainState.step,
+                    lastStep: chainState.pendingStep ?? chainState.lastStep,
+                    visitedKeys: chainState.visitedKeys,
+                });
+            }
+            else if (!result.success) {
+                this.telemetry.logEvent({
+                    eventType: 'agent_chain_aborted',
+                    sessionId: this.sessionId,
+                    chainAbortReason: 'error',
+                });
+            }
+        }
+        // The confirmed action (and any resumed chain) finished: clear the live row.
+        if (!this.pending)
+            this.setActivity(null);
     }
     cancelPendingAction() {
         this.clearConfirmWindow();
@@ -322,9 +472,20 @@ export class AgentController {
         this.pending = null;
         this.confirmationMessage = null;
         this.confirmationVoiceHint = null;
+        this.setActivity(null);
         if (this.phase === 'confirming')
             this.setPhase('idle');
         this.emit();
+        // Declining a sensitive action stops any chain it was part of, cleanly.
+        const chainState = this.chainState;
+        this.chainState = null;
+        if (chainState) {
+            this.telemetry.logEvent({
+                eventType: 'agent_chain_aborted',
+                sessionId: this.sessionId,
+                chainAbortReason: 'user_interrupt',
+            });
+        }
         if (!pending)
             return;
         this.telemetry.logEvent({
@@ -368,6 +529,286 @@ export class AgentController {
                 this.beginConfirmationVoiceWindow();
         }
     }
+    routeLabel(intent) {
+        return this.config.manifest.routes.find((r) => r.intent === intent)?.label;
+    }
+    actionLabel(intent) {
+        return this.config.manifest.actions.find((a) => a.intent === intent)?.label;
+    }
+    /**
+     * Resolve ONE backend turn into user-facing reply/audio: run its action (or
+     * stage its confirmation), emit telemetry, and report whether the autonomous
+     * chain may take another step. Shared by the first turn and every
+     * continuation so both follow the exact same security path — disabled
+     * capabilities, confidentiality and sensitive confirmations apply per step.
+     */
+    async applyOutcome(turn, routeAtSend, snapshotContext, userMessage) {
+        let outReply = turn.reply;
+        let outAudio = turn.audioBase64;
+        if (outReply)
+            this.serverTtsUnavailable = !outAudio;
+        const decision = await decideAction({
+            action: turn.action,
+            manifest: this.config.manifest,
+            executor: this.executor,
+            context: snapshotContext,
+            messages: this.messages,
+            userMessage,
+        });
+        let canContinue = false;
+        let lastStep;
+        let actionKey;
+        let hasPending = false;
+        let pendingInProgress = false;
+        let pendingStep;
+        let pendingKey;
+        if (decision.kind === 'executed') {
+            const r = decision.result;
+            // REAL activity for the panel: this action actually just ran — the
+            // label comes from the manifest, never invented.
+            if (r.success && turn.action?.type === 'navigate') {
+                this.setActivity({
+                    kind: 'navigating',
+                    label: this.routeLabel(turn.action.intent ?? '') ?? turn.action.intent ?? '',
+                });
+            }
+            else if (r.success && !r.recoverable && turn.action?.type === 'execute') {
+                this.setActivity({
+                    kind: 'executing',
+                    label: this.actionLabel(turn.action.intent ?? '') ?? turn.action.intent ?? '',
+                });
+            }
+            if (turn.action?.type === 'navigate') {
+                this.telemetry.logEvent({
+                    eventType: r.success ? 'navigation_executed' : 'navigation_failed',
+                    intentDetected: turn.action.intent,
+                    sessionId: this.sessionId,
+                    currentRoute: routeAtSend ?? undefined,
+                });
+            }
+            else if (turn.action?.type === 'execute') {
+                this.telemetry.logEvent({
+                    eventType: r.recoverable
+                        ? 'action_needs_context'
+                        : r.success
+                            ? 'action_executed'
+                            : 'action_failed',
+                    intentDetected: turn.action.intent,
+                    sessionId: this.sessionId,
+                    actionExecuted: { intent: turn.action.intent, confirmed: false },
+                });
+            }
+            if (r.recoverable) {
+                /* keep the assistant's guiding reply; never speak a refusal. */
+            }
+            else if (r.message) {
+                outReply = r.message;
+                outAudio = null;
+            }
+            // Chain signal: only a cleanly EXECUTED, non-recoverable step may advance,
+            // and only when the backend asked to continue (task_status=in_progress).
+            if (turn.action &&
+                (turn.action.type === 'navigate' || turn.action.type === 'execute') &&
+                r.success &&
+                !r.recoverable) {
+                const intent = turn.action.intent ?? '';
+                lastStep = {
+                    type: turn.action.type,
+                    intent,
+                    label: turn.action.type === 'navigate' ? this.routeLabel(intent) : this.actionLabel(intent),
+                    success: true,
+                };
+                actionKey = `${turn.action.type}:${intent}`;
+                canContinue = turn.taskStatus === 'in_progress';
+            }
+        }
+        else if (decision.kind === 'precheck-resolved') {
+            if (decision.result.message && !decision.result.recoverable) {
+                outReply = decision.result.message;
+                outAudio = null;
+            }
+        }
+        else if (decision.kind === 'needs-confirmation') {
+            // A sensitive action ALWAYS pauses (chaining or not): stage the
+            // confirmation and stop advancing. Resumes after the user confirms.
+            this.pending = { ...decision.pending, silent: this.silentTurn };
+            this.confirmationReasked = false;
+            this.confirmationMessage = decision.pending.question;
+            this.confirmationVoiceHint =
+                decision.pending.voiceMode === 'strict' &&
+                    decision.pending.strictPhrase &&
+                    !this.silentTurn
+                    ? formatMessage(this.messages.strictConfirmationModalHint, {
+                        phrase: decision.pending.strictPhrase,
+                    })
+                    : null;
+            this.emit();
+            this.telemetry.logEvent({
+                eventType: 'action_confirmation_requested',
+                intentDetected: decision.pending.intent,
+                sessionId: this.sessionId,
+            });
+            // REAL activity: the agent is genuinely waiting for the human now.
+            this.setActivity({ kind: 'waiting_confirmation' });
+            hasPending = true;
+            pendingInProgress = turn.taskStatus === 'in_progress';
+            const pIntent = decision.pending.intent || '';
+            pendingStep = { type: 'execute', intent: pIntent, label: this.actionLabel(pIntent), success: true };
+            pendingKey = `execute:${pIntent}`;
+        }
+        return {
+            reply: outReply,
+            audioBase64: outAudio,
+            hasPending,
+            canContinue,
+            lastStep,
+            actionKey,
+            pendingInProgress,
+            pendingStep,
+            pendingKey,
+        };
+    }
+    /**
+     * The autonomous continuation loop. Extracted so confirmPendingAction can
+     * RESUME the SAME chain after a sensitive step is confirmed. Capped at
+     * maxSteps, with no-progress detection and sensitive-confirmation pauses.
+     */
+    async runChainLoop(state) {
+        let step = state.step;
+        let lastStep = state.lastStep;
+        const visitedKeys = state.visitedKeys;
+        // Keep the panel's live row visible for the WHOLE chain (including the
+        // dwell between steps), so the real narration never flickers away.
+        this.setChainActive(true);
+        try {
+            while (step < this.chaining.maxSteps) {
+                step += 1;
+                if (this.chaining.dwellMs > 0)
+                    await sleep(this.chaining.dwellMs);
+                if (this.pending != null)
+                    return; // paused / interrupted elsewhere
+                const routeNow = this.config.navigation.getCurrentRoute();
+                const snap = this.screenStore.getSnapshot();
+                const rawCtx = combineContexts(this.config.getUserContextText?.() ?? null, this.screenStore.getText(), {
+                    truncationSuffix: this.messages.contextTruncationSuffix,
+                    maxChars: this.config.contextMaxChars,
+                });
+                const san = rawCtx ? this.sanitizer(rawCtx).sanitized : undefined;
+                const conv = prepareConversationForTurn(this.conversation, Date.now(), this.conversationOptions);
+                this.setPhase('thinking');
+                // Honest state: the model is choosing the next step right now.
+                this.setActivity({ kind: 'thinking' });
+                const controller = new AbortController();
+                this.abort = controller;
+                let oc;
+                try {
+                    const turn = await this.config.backend.sendTurn({
+                        message: state.userMessage,
+                        language: this.config.locale,
+                        voice: this.getTtsVoice(),
+                        screenContext: san,
+                        currentRoute: routeNow ?? undefined,
+                        conversationHistory: conv.history,
+                        conversationSummary: conv.summary ?? undefined,
+                        sessionId: this.sessionId,
+                        isContinuation: true,
+                        chainStep: step,
+                        lastStep,
+                        ...buildManifestPayload(this.config.manifest),
+                    }, { signal: controller.signal });
+                    oc = await this.applyOutcome(turn, routeNow, snap?.context ?? {}, state.userMessage);
+                }
+                catch (e) {
+                    this.abort = null;
+                    const interrupted = e instanceof AgentApiError && e.code === 'cancelled';
+                    if (interrupted) {
+                        if (this.phase === 'thinking')
+                            this.setPhase('idle');
+                    }
+                    else {
+                        if (e instanceof AgentApiError && e.code === 'quota_exceeded') {
+                            this.config.onQuotaExceeded?.();
+                        }
+                        const errMsg = formatAgentTurnError(e, this.config.locale);
+                        this.lastExchange = { userText: state.userMessage, replyText: errMsg };
+                        if (this.phase === 'thinking')
+                            this.setPhase('idle');
+                        this.emit();
+                        this.notifyError(errMsg);
+                    }
+                    this.telemetry.logEvent({
+                        eventType: 'agent_chain_aborted',
+                        sessionId: this.sessionId,
+                        chainStep: step,
+                        chainAbortReason: interrupted ? 'user_interrupt' : 'error',
+                    });
+                    return;
+                }
+                this.abort = null;
+                if (oc.reply) {
+                    this.lastExchange = { userText: state.userMessage, replyText: oc.reply };
+                    this.emit();
+                    recordConversationExchange(this.conversation, state.userMessage, oc.reply, Date.now(), this.conversationOptions);
+                    this.persistConversation();
+                }
+                await this.speakReply(oc.reply, oc.audioBase64);
+                this.telemetry.logEvent({
+                    eventType: 'agent_chain_step',
+                    intentDetected: oc.lastStep?.intent ?? oc.pendingStep?.intent ?? null,
+                    sessionId: this.sessionId,
+                    chainStep: step,
+                });
+                // Sensitive action → ALWAYS pause for confirmation. Park the chain so
+                // confirmPendingAction can resume it (only if the model wants to keep
+                // going); a rejection stops it cleanly.
+                if (oc.hasPending) {
+                    this.chainState = oc.pendingInProgress
+                        ? {
+                            userMessage: state.userMessage,
+                            step,
+                            lastStep,
+                            visitedKeys,
+                            pendingKey: oc.pendingKey,
+                            pendingStep: oc.pendingStep,
+                        }
+                        : null;
+                    this.beginConfirmationVoiceWindow();
+                    return;
+                }
+                if (this.phase !== 'speaking')
+                    this.setPhase('idle');
+                if (oc.actionKey && visitedKeys.has(oc.actionKey)) {
+                    this.telemetry.logEvent({
+                        eventType: 'agent_chain_aborted',
+                        sessionId: this.sessionId,
+                        chainStep: step,
+                        chainAbortReason: 'no_progress',
+                    });
+                    return;
+                }
+                if (oc.actionKey)
+                    visitedKeys.add(oc.actionKey);
+                if (!oc.canContinue) {
+                    this.telemetry.logEvent({
+                        eventType: 'agent_chain_completed',
+                        sessionId: this.sessionId,
+                        chainStep: step,
+                    });
+                    return;
+                }
+                lastStep = oc.lastStep;
+            }
+            this.telemetry.logEvent({
+                eventType: 'agent_chain_aborted',
+                sessionId: this.sessionId,
+                chainStep: step,
+                chainAbortReason: 'max_steps',
+            });
+        }
+        finally {
+            this.setChainActive(false);
+        }
+    }
     // ── Main turn ────────────────────────────────────────────────────────────────
     async handleTranscript(rawText) {
         const text = rawText.trim();
@@ -377,6 +818,8 @@ export class AgentController {
             return;
         }
         this.setPhase('thinking');
+        // REAL activity: the request is genuinely in flight from this moment.
+        this.setActivity({ kind: 'thinking' });
         this.pendingTurnText = text;
         this.lastExchange = { userText: text, replyText: '' };
         this.emit();
@@ -390,6 +833,7 @@ export class AgentController {
                     : 'The response took too long. Please try again.';
                 this.lastExchange = { userText, replyText };
                 this.pendingTurnText = null;
+                this.setActivity(null);
                 this.setPhase('idle');
                 this.emit();
             }
@@ -410,11 +854,10 @@ export class AgentController {
             maxChars: this.config.contextMaxChars,
         });
         const sanitized = rawContext ? this.sanitizer(rawContext).sanitized : undefined;
-        const conv = prepareConversationForTurn(this.conversation);
+        const conv = prepareConversationForTurn(this.conversation, Date.now(), this.conversationOptions);
         const controller = new AbortController();
         this.abort = controller;
-        let reply = '';
-        let audioBase64 = null;
+        let outcome = null;
         try {
             const turn = await this.config.backend.sendTurn({
                 message: text,
@@ -427,79 +870,12 @@ export class AgentController {
                 sessionId: this.sessionId,
                 ...buildManifestPayload(this.config.manifest),
             }, { signal: controller.signal });
-            reply = turn.reply;
-            audioBase64 = turn.audioBase64;
-            // Learn whether this backend ships server-side TTS: a non-empty reply
-            // with no audio means it doesn't — later lines then speak instantly.
-            if (reply)
-                this.serverTtsUnavailable = !audioBase64;
-            const decision = await decideAction({
-                action: turn.action,
-                manifest: this.config.manifest,
-                executor: this.executor,
-                context: snapshot?.context ?? {},
-                messages: this.messages,
-                userMessage: text,
-            });
-            if (decision.kind === 'executed') {
-                const r = decision.result;
-                if (turn.action?.type === 'navigate') {
-                    this.telemetry.logEvent({
-                        eventType: r.success ? 'navigation_executed' : 'navigation_failed',
-                        intentDetected: turn.action.intent,
-                        sessionId: this.sessionId,
-                        currentRoute,
-                    });
-                }
-                else if (turn.action?.type === 'execute') {
-                    this.telemetry.logEvent({
-                        eventType: r.recoverable
-                            ? 'action_needs_context'
-                            : r.success
-                                ? 'action_executed'
-                                : 'action_failed',
-                        intentDetected: turn.action.intent,
-                        sessionId: this.sessionId,
-                        actionExecuted: { intent: turn.action.intent, confirmed: false },
-                    });
-                }
-                if (r.recoverable) {
-                    /* keep the assistant's guiding reply; never speak a refusal. */
-                }
-                else if (r.message) {
-                    reply = r.message;
-                    audioBase64 = null;
-                }
-            }
-            else if (decision.kind === 'precheck-resolved') {
-                if (decision.result.message && !decision.result.recoverable) {
-                    reply = decision.result.message;
-                    audioBase64 = null;
-                }
-            }
-            else if (decision.kind === 'needs-confirmation') {
-                this.pending = { ...decision.pending, silent: this.silentTurn };
-                this.confirmationReasked = false;
-                this.confirmationMessage = decision.pending.question;
-                this.confirmationVoiceHint =
-                    decision.pending.voiceMode === 'strict' &&
-                        decision.pending.strictPhrase &&
-                        !this.silentTurn
-                        ? formatMessage(this.messages.strictConfirmationModalHint, {
-                            phrase: decision.pending.strictPhrase,
-                        })
-                        : null;
-                this.emit();
-                this.telemetry.logEvent({
-                    eventType: 'action_confirmation_requested',
-                    intentDetected: decision.pending.intent,
-                    sessionId: this.sessionId,
-                });
-            }
+            outcome = await this.applyOutcome(turn, currentRoute, snapshot?.context ?? {}, text);
         }
         catch (e) {
             this.clearWatchdog();
             this.abort = null;
+            this.setActivity(null);
             if (e instanceof AgentApiError && e.code === 'cancelled') {
                 if (this.phase === 'thinking')
                     this.setPhase('idle');
@@ -521,10 +897,14 @@ export class AgentController {
         this.clearWatchdog();
         this.abort = null;
         this.pendingTurnText = null;
+        if (!outcome)
+            return;
+        const reply = outcome.reply;
         if (reply) {
             this.lastExchange = { userText: text, replyText: reply };
             this.emit();
-            recordConversationExchange(this.conversation, text, reply);
+            recordConversationExchange(this.conversation, text, reply, Date.now(), this.conversationOptions);
+            this.persistConversation();
         }
         else {
             const fallback = this.config.locale.startsWith('es')
@@ -533,14 +913,53 @@ export class AgentController {
             this.lastExchange = { userText: text, replyText: fallback };
             this.emit();
         }
-        const hasPending = this.pending != null;
-        await this.speakReply(reply, audioBase64);
+        const hasPending = outcome.hasPending;
+        await this.speakReply(reply, outcome.audioBase64);
         if (hasPending) {
             this.beginConfirmationVoiceWindow();
+            // First step is a sensitive action AND the model wants to keep going:
+            // park the chain so it RESUMES after the user confirms.
+            if (this.chaining.enabled && outcome.pendingInProgress) {
+                this.telemetry.logEvent({
+                    eventType: 'agent_chain_started',
+                    sessionId: this.sessionId,
+                    chainStep: 1,
+                });
+                this.chainState = {
+                    userMessage: text,
+                    step: 1,
+                    lastStep: outcome.pendingStep,
+                    visitedKeys: new Set(),
+                    pendingKey: outcome.pendingKey,
+                    pendingStep: outcome.pendingStep,
+                };
+            }
         }
         else if (this.phase !== 'speaking') {
             this.setPhase('idle');
         }
+        // Kick off the autonomous chain when the first step executed cleanly and
+        // the backend asked to continue (no sensitive confirmation pending).
+        if (this.chaining.enabled && outcome.canContinue && !hasPending) {
+            this.telemetry.logEvent({
+                eventType: 'agent_chain_started',
+                sessionId: this.sessionId,
+                chainStep: 1,
+            });
+            const visitedKeys = new Set();
+            if (outcome.actionKey)
+                visitedKeys.add(outcome.actionKey);
+            await this.runChainLoop({
+                userMessage: text,
+                step: 1,
+                lastStep: outcome.lastStep,
+                visitedKeys,
+            });
+        }
+        // Final reply is on screen: the live narrative disappears (unless the
+        // agent is genuinely waiting for a confirmation, which stays honest).
+        if (!this.pending)
+            this.setActivity(null);
         this.config.onTurnCompleted?.();
     }
     // ── Speech session wiring ────────────────────────────────────────────────────
@@ -653,6 +1072,11 @@ export class AgentController {
         this.emit();
         this.telemetry.logEvent({ eventType: 'agent_consent_declined', sessionId: this.sessionId });
     }
+    /**
+     * Cancel everything in flight. If a first turn was still awaiting its reply,
+     * its message is removed from the panel and returned here so the UI can put
+     * it back into the input for editing; null otherwise.
+     */
     cancelAll() {
         this.abort?.abort();
         this.abort = null;
@@ -662,10 +1086,22 @@ export class AgentController {
         this.speech.cancel();
         this.config.voice.stopPlayback();
         this.pending = null;
+        this.chainState = null;
         this.confirmationMessage = null;
         this.confirmationVoiceHint = null;
+        this.liveActivity = null;
+        this.chainActive = false;
+        // A first turn was still in flight: remove its message from the panel and
+        // hand the text back for editing (the turn never completed, so nothing
+        // was recorded in the conversation).
+        const draft = this.pendingTurnText;
+        if (draft) {
+            this.pendingTurnText = null;
+            this.lastExchange = null;
+        }
         this.setPhase('idle');
         this.emit();
+        return draft;
     }
     /** Best-effort backend warm-up (cold-start mitigation). */
     warmUp() {
@@ -673,6 +1109,10 @@ export class AgentController {
     }
     dispose() {
         this.cancelAll();
+        if (this.loadOlderTimer) {
+            clearTimeout(this.loadOlderTimer);
+            this.loadOlderTimer = null;
+        }
         this.unsubscribeSpeech?.();
         this.unsubscribeSpeech = null;
         this.speech.dispose();