@fiodos/web-core 0.1.18 → 0.1.20

package/dist/esm/api/backendClient.js

@@ -57,7 +57,13 @@ async function errorFromResponse(res) {
         return new AgentApiError('unauthorized', detail, res.status);
     }
     if (res.status === 429) {
-        const quotaSignal = typeof body.remaining === 'number' || (detail ?? '').toLowerCase().includes('quota');
+        // The backend marks plan/budget 429s with error:"quota_exceeded" (rate
+        // limits carry error:"rate_limited"); the detail/remaining checks cover
+        // older backends. Getting this right matters: a quota 429 shown as "too
+        // many requests" sends the developer chasing rate limits that are fine.
+        const quotaSignal = body.error === 'quota_exceeded' ||
+            typeof body.remaining === 'number' ||
+            (detail ?? '').toLowerCase().includes('quota');
         return new AgentApiError(quotaSignal ? 'quota_exceeded' : 'rate_limited', detail, res.status);
     }
     if (res.status === 404)

package/dist/esm/api/backendTelemetry.js

@@ -1,3 +1,5 @@
+/** Bound on the technical error string shipped with action_failed events. */
+const MAX_ERROR_DETAIL_CHARS = 200;
 function mapEvent(params) {
     const intent = params.intentDetected ?? null;
     const sessionId = params.sessionId ?? null;
@@ -13,6 +15,19 @@ function mapEvent(params) {
             }
             return events;
         }
+        // Failures are the events that make field reports diagnosable: without
+        // them, "the orb said it couldn't do it" leaves the developer blind. Only
+        // the technical error string travels (HTTP status + path, template
+        // param…), never any message content.
+        case 'action_failed':
+            return [
+                {
+                    type: 'action_failed',
+                    intent,
+                    session_id: sessionId,
+                    error: (params.errorDetail ?? '').slice(0, MAX_ERROR_DETAIL_CHARS) || null,
+                },
+            ];
         case 'action_confirmation_requested':
             return [{ type: 'confirmation_requested', intent, session_id: sessionId }];
         default:

package/dist/esm/config/types.d.ts

@@ -18,14 +18,20 @@ export interface AgentTimings {
 }
 export declare const DEFAULT_AGENT_TIMINGS: AgentTimings;
 /**
- * Autonomous multi-step chaining. OFF by default: with `enabled: false` the orb
- * behaves exactly as before (one action per turn). When ON, after a successful
+ * Autonomous multi-step chaining. ON by default: after a successful
  * navigate/execute whose backend `task_status` is "in_progress", the orb takes
  * the next step on its own — capped at `maxSteps` and guarded by no-progress
  * detection and sensitive-confirmation pauses (which always require the human).
+ *
+ * Default ON is a product invariant, not a tuning choice: data actions
+ * (search, get-cart…) are INVISIBLE — without the continuation turn the orb
+ * runs them and then goes silent ("I'll look for products…" and nothing
+ * happens). Every install (embeds included, which pass no config) must get
+ * the full act→observe→act loop. Pass `chaining: { enabled: false }` to opt
+ * out and return to one-action-per-turn.
  */
 export interface AgentChaining {
-    /** Master switch. Default false (retrocompatible, one action per turn). */
+    /** Master switch. Default true (the agent completes multi-step tasks). */
     enabled: boolean;
     /** Hard cap on steps per user request (safety). Default 6. */
     maxSteps: number;

package/dist/esm/config/types.js

@@ -5,7 +5,7 @@ export const DEFAULT_AGENT_TIMINGS = {
     minTranscriptChars: 2,
 };
 export const DEFAULT_AGENT_CHAINING = {
-    enabled: false,
+    enabled: true,
     maxSteps: 6,
     dwellMs: 450,
 };

package/dist/esm/controller/AgentController.d.ts

@@ -104,6 +104,12 @@ export declare class AgentController {
     private pendingConsentIntent;
     /** Parked chain state (set when a chain pauses on a sensitive action). */
     private chainState;
+    /**
+     * Intent whose showcase escort was DEFERRED mid-chain (suppressEscort):
+     * flushed when the chain ends so the user is walked to where the last
+     * action's effect is visible — never in the middle of a running chain.
+     */
+    private deferredEscortIntent;
     /** REAL live activity for the panel (replaces the old canned walk-through). */
     private liveActivity;
     private chainActive;
@@ -221,6 +227,13 @@ export declare class AgentController {
      * maxSteps, with no-progress detection and sensitive-confirmation pauses.
      */
     private runChainLoop;
+    /**
+     * Runs the showcase escort that was deferred while the chain was executing
+     * (see suppressEscort in applyOutcome). Skipped while a confirmation is
+     * pending: the chain may resume after the user answers, and the confirmed
+     * action escorts on its own.
+     */
+    private flushDeferredEscort;
     private handleTranscript;
     private onTranscript;
     private onSpeechError;

package/dist/esm/controller/AgentController.js

@@ -60,6 +60,12 @@ export class AgentController {
         this.pendingConsentIntent = null;
         /** Parked chain state (set when a chain pauses on a sensitive action). */
         this.chainState = null;
+        /**
+         * Intent whose showcase escort was DEFERRED mid-chain (suppressEscort):
+         * flushed when the chain ends so the user is walked to where the last
+         * action's effect is visible — never in the middle of a running chain.
+         */
+        this.deferredEscortIntent = null;
         /** REAL live activity for the panel (replaces the old canned walk-through). */
         this.liveActivity = null;
         this.chainActive = false;
@@ -485,7 +491,11 @@ export class AgentController {
             intentDetected: pending.intent,
             sessionId: this.sessionId,
             actionExecuted: { intent: pending.intent, confirmed: true },
+            ...(!result.success ? { errorDetail: result.error ?? null } : {}),
         });
+        if (!result.success) {
+            console.warn(`[fyodos] action "${pending.intent}" failed: ${result.error ?? 'unknown error'}`);
+        }
         if (result.message) {
             if (this.lastExchange)
                 this.lastExchange = { ...this.lastExchange, replyText: result.message };
@@ -539,6 +549,7 @@ export class AgentController {
         // Declining a sensitive action stops any chain it was part of, cleanly.
         const chainState = this.chainState;
         this.chainState = null;
+        this.deferredEscortIntent = null;
         if (chainState) {
             this.telemetry.logEvent({
                 eventType: 'agent_chain_aborted',
@@ -658,6 +669,10 @@ export class AgentController {
         let outAudio = turn.audioBase64;
         if (outReply)
             this.serverTtsUnavailable = !outAudio;
+        // Mid-chain: hold the showcase escort. On multi-page hosts (Shopify
+        // embeds) the escort is a full page load that would kill the chain
+        // before its continuation turn; the chain escorts once when it ends.
+        const escortDeferred = this.chaining.enabled && turn.taskStatus === 'in_progress';
         const decision = await decideAction({
             action: turn.action,
             manifest: this.config.manifest,
@@ -665,6 +680,7 @@ export class AgentController {
             context: snapshotContext,
             messages: this.messages,
             userMessage,
+            suppressEscort: escortDeferred,
         });
         let canContinue = false;
         let lastStep;
@@ -707,6 +723,7 @@ export class AgentController {
                     intentDetected: turn.action.intent,
                     sessionId: this.sessionId,
                     actionExecuted: { intent: turn.action.intent, confirmed: false },
+                    ...(!r.success && !r.recoverable ? { errorDetail: r.error ?? null } : {}),
                 });
             }
             if (r.recoverable) {
@@ -729,12 +746,27 @@ export class AgentController {
                 outReply = this.messages.actionFailed;
                 outAudio = null;
             }
+            if (!r.success) {
+                // Developer signal: the user only hears a generic failure phrase; the
+                // TECHNICAL cause (HTTP status + path, missing template param…) must
+                // be findable in the console or every field report is undebuggable.
+                console.warn(`[fyodos] action "${turn.action?.intent ?? '?'}" failed: ${r.error ?? 'unknown error'}`);
+            }
             // 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) {
+                // Deferred-escort bookkeeping: remember the intent whose escort was
+                // held (flushed at chain end); a navigate — or an execute whose escort
+                // already ran inside the executor — supersedes any earlier deferral.
+                if (turn.action.type === 'execute') {
+                    this.deferredEscortIntent = escortDeferred ? (turn.action.intent ?? null) : null;
+                }
+                else {
+                    this.deferredEscortIntent = null;
+                }
                 const intent = turn.action.intent ?? '';
                 // Feed the step's RESULT DATA back to the next chain turn (bounded):
                 // it is how the model reads real technical values (variant ids, line
@@ -938,8 +970,23 @@ export class AgentController {
         }
         finally {
             this.setChainActive(false);
+            this.flushDeferredEscort();
         }
     }
+    /**
+     * Runs the showcase escort that was deferred while the chain was executing
+     * (see suppressEscort in applyOutcome). Skipped while a confirmation is
+     * pending: the chain may resume after the user answers, and the confirmed
+     * action escorts on its own.
+     */
+    flushDeferredEscort() {
+        if (this.pending != null)
+            return;
+        const intent = this.deferredEscortIntent;
+        this.deferredEscortIntent = null;
+        if (intent)
+            this.executor.escortForIntent(intent);
+    }
     // ── Main turn ────────────────────────────────────────────────────────────────
     async handleTranscript(rawText) {
         const text = rawText.trim();
@@ -1223,6 +1270,7 @@ export class AgentController {
         this.config.voice.stopPlayback();
         this.pending = null;
         this.chainState = null;
+        this.deferredEscortIntent = null;
         this.confirmationMessage = null;
         this.confirmationVoiceHint = null;
         this.liveActivity = null;

package/dist/esm/core/turnEngine.d.ts

@@ -52,6 +52,12 @@ export interface DecideActionParams {
     context: AgentScreenContext;
     messages: AgentMessages;
     userMessage: string;
+    /**
+     * Skip the post-action showcase escort (mid-chain steps): on multi-page
+     * hosts the escort is a full page load that would kill the running chain.
+     * The orchestrator escorts once at the END of the chain.
+     */
+    suppressEscort?: boolean;
 }
 /**
  * Decides what to do with a backend-proposed action. Sensitive actions are

package/dist/esm/core/turnEngine.js

@@ -27,7 +27,7 @@ function findManifestAction(manifest, intent) {
  * never executed here — they return `needs-confirmation`.
  */
 export async function decideAction(params) {
-    const { action, manifest, executor, context, messages, userMessage } = params;
+    const { action, manifest, executor, context, messages, userMessage, suppressEscort } = params;
     if (!action || action.type === 'none') {
         return { kind: 'noop' };
     }
@@ -39,7 +39,7 @@ export async function decideAction(params) {
         const manifestAction = findManifestAction(manifest, action.intent);
         const needsConfirmation = manifestAction?.requireConfirmation === true;
         if (!needsConfirmation) {
-            const result = await executor.execute(action, context);
+            const result = await executor.execute(action, context, { suppressEscort });
             return { kind: 'executed', result };
         }
         // Precheck (context + idempotency) BEFORE asking: applying an already-applied

package/dist/esm/embed/global.d.ts

@@ -27,7 +27,7 @@ import { createScreenContextStore } from '../context/screenContextStore.js';
 import { connectDynamicsFormContext, dynamicsFormSnapshot, normalizeDynamicsId } from './dynamics.js';
 import { buildApiActionRegistries, validateManifest } from '@fiodos/core';
 declare const api: {
-    readonly version: "0.1.18";
+    readonly version: "0.1.20";
     readonly createFiodosAgent: typeof createFiodosAgent;
     readonly mountOrb: typeof mountOrb;
     readonly AgentController: typeof AgentController;

package/dist/esm/orb/mountOrb.js

@@ -16,7 +16,7 @@
  *  - CONFIRMATIONS: the same security model (manifest decides; strict phrase /
  *    deliberate tap for payment-grade; loose "yes" never resolves strict).
  */
-import { DEFAULT_ORB_SCREEN_POSITION, createWebOrbHaptics, matchRouteIntent, resolveBubblePrompt, bubblePromptToAffirmative, resolveBubbleTheme, resolveBubblePadding, bubbleShapeToCss, applyBubbleShapeCss, resolveOrbAnchorPx, resolveOrbDeployment, snapOrbScreenPositionToSide, viewportPixelsToOrbScreenPosition, fiodosInputInkColor, fiodosInputMutedInkColor, shouldHideInternalOrb, } from '@fiodos/core';
+import { DEFAULT_ORB_SCREEN_POSITION, createWebOrbHaptics, matchRouteIntent, resolveBubblePrompt, resolveBubbleTheme, resolveBubblePadding, bubbleShapeToCss, applyBubbleShapeCss, resolveOrbAnchorPx, resolveOrbDeployment, snapOrbScreenPositionToSide, viewportPixelsToOrbScreenPosition, fiodosInputInkColor, fiodosInputMutedInkColor, shouldHideInternalOrb, } from '@fiodos/core';
 import { buildKeyboardChip, createOrbVisual, DEFAULT_ORB_APPEARANCE, } from './orbView.js';
 import { watchPublishedConfig } from './publishedConfig.js';
 import { createBubbleDictation, scrollTextInputToEnd } from '../speech/bubbleDictation.js';
@@ -54,6 +54,8 @@ const CSS = `
 .fyodos-bubble-exchange:first-child .fyodos-bubble-user{padding-right:22px;}
 .fyodos-bubble-user{flex:1;min-width:0;font-size:13px;line-height:18px;opacity:.75;}
 .fyodos-bubble-reply{font-size:15px;line-height:21px;white-space:pre-wrap;}
+.fyodos-bubble-greeting{font-size:15px;line-height:21px;white-space:pre-wrap;animation:fyodos-fade-in .18s ease-out;}
+.fyodos-bubble--expanded .fyodos-bubble-greeting{font-size:17px;line-height:25px;}
 .fyodos-bubble-busy{display:flex;gap:5px;padding:8px 14px;align-items:center;}
 .fyodos-bubble-busy span{width:6px;height:6px;border-radius:50%;opacity:.5;animation:fyodos-blink 1s infinite;}
 .fyodos-bubble-busy span:nth-child(2){animation-delay:.18s;}
@@ -207,13 +209,9 @@ export function mountOrb(controller, options = {}) {
         haptics.trigger('orbTap');
         controller.primeAudio();
         if (enableTextInput) {
-            const prompt = resolveCurrentBubblePrompt();
-            openTextPanel(prompt
-                ? bubblePromptToAffirmative(prompt, {
-                    locale: currentBubbleLocale(),
-                    messages: controller.messages,
-                })
-                : undefined);
+            // The bubble's question moves INTO the panel as an assistant greeting
+            // (openTextPanel shows it) — never pre-typed into the user's input.
+            openTextPanel();
             return;
         }
         userTriedVoice = true;
@@ -455,7 +453,30 @@ export function mountOrb(controller, options = {}) {
     loaderRow.style.display = 'none';
     const exchangeList = document.createElement('div');
     exchangeList.className = 'fyodos-bubble-exchanges';
-    exchangeScroll.append(loaderRow, exchangeList);
+    // Screen-aware GREETING: the thought bubble's question, shown INSIDE the
+    // panel as an assistant message when it opens (tapping the bubble or opening
+    // the chat traditionally). Ephemeral by design: it never enters the
+    // conversation history and disappears the moment the user sends a message.
+    const greetingEl = document.createElement('div');
+    greetingEl.className = 'fyodos-bubble-greeting';
+    greetingEl.style.display = 'none';
+    exchangeScroll.append(loaderRow, exchangeList, greetingEl);
+    function showPanelGreeting() {
+        const prompt = resolveCurrentBubblePrompt();
+        if (!prompt) {
+            greetingEl.style.display = 'none';
+            return;
+        }
+        const t = { ...DEFAULT_MODAL_THEME, ...(modalTheme ?? {}) };
+        greetingEl.textContent = prompt;
+        greetingEl.style.color = t.titleColor;
+        greetingEl.style.display = '';
+        exchangeScroll.scrollTop = exchangeScroll.scrollHeight;
+    }
+    function hidePanelGreeting() {
+        if (greetingEl.style.display !== 'none')
+            greetingEl.style.display = 'none';
+    }
     // Signature of the rendered list so state emits that do not change the
     // transcript (volume, phase…) never re-render it nor fight the user's scroll.
     let renderedSignature = '';
@@ -749,6 +770,8 @@ export function mountOrb(controller, options = {}) {
         else {
             bubbleDictation.stop();
             syncMicButton();
+            // Ephemeral greeting never survives a close (recomputed on next open).
+            hidePanelGreeting();
             // Collapse the paged history back to the initial page for the next open.
             controller.resetBubbleWindow();
             // Closing the panel returns the orb to idle (also clears mic fallback).
@@ -778,6 +801,9 @@ export function mountOrb(controller, options = {}) {
         syncMicButton();
         haptics.trigger('send');
         textInput.value = '';
+        // The greeting is a welcome, not part of the conversation: the user's
+        // first real message replaces it.
+        hidePanelGreeting();
         // Silent turn: the reply is SHOWN in the bubble (not spoken), and the bubble
         // STAYS OPEN. This is the unified, reference-matching behaviour.
         void controller.submitTextTurn(value);
@@ -790,6 +816,11 @@ export function mountOrb(controller, options = {}) {
         const draft = explicitSeed || cancelled || '';
         textInput.value = draft;
         setBubble(true);
+        // Welcome the user with this screen's bubble question as an assistant
+        // message (both open paths: bubble tap AND traditional open). It vanishes
+        // with the user's first message — never enters the history.
+        if (!draft)
+            showPanelGreeting();
         // Only an explicit seed may auto-send; a restored cancelled message must
         // wait for the user to edit/resend it.
         if (autoSend && explicitSeed) {
@@ -1153,6 +1184,9 @@ export function mountOrb(controller, options = {}) {
         syncActivityStep(rowBusy, state);
         // Text bubble: show recent exchanges + busy state.
         if (bubbleOpen) {
+            // A turn in flight (typed OR voice) replaces the ephemeral greeting.
+            if (state.isBusy)
+                hidePanelGreeting();
             loaderRow.style.display = state.loadingOlderExchanges ? 'flex' : 'none';
             renderBubbleExchanges(state.recentExchanges);
             exchangeScroll.style.display = 'flex';

package/dist/esm/speech/bubbleDictation.js

@@ -25,12 +25,29 @@ export function createBubbleDictation(locale) {
     let listening = false;
     let baseText = '';
     const stop = () => {
-        recognition?.stop();
+        const rec = recognition;
+        if (!rec)
+            return;
+        // DISCARD-ON-STOP: recognition engines fire one last consolidated
+        // `onresult` AFTER stop() is requested. If the user hits send while still
+        // dictating, that late result would rewrite the input we just cleared and
+        // the message would reappear (duplicate-send bug). Once a stop is
+        // requested, nothing may ever write to the input again.
+        rec.onresult = null;
+        recognition = null;
+        listening = false;
+        try {
+            if (typeof rec.abort === 'function')
+                rec.abort();
+            else
+                rec.stop();
+        }
+        catch {
+            /* already stopped */
+        }
     };
     const dispose = () => {
         stop();
-        recognition = null;
-        listening = false;
     };
     return {
         isSupported: () => Ctor != null,
@@ -68,11 +85,18 @@ export function createBubbleDictation(locale) {
                     : dictated;
                 setValue(combined);
             };
+            // Identity-guarded teardown: a session stopped via stop() may fire its
+            // onend AFTER the user already started a NEW dictation — it must never
+            // tear down the new session.
             rec.onend = () => {
+                if (recognition !== rec)
+                    return;
                 listening = false;
                 recognition = null;
             };
             rec.onerror = () => {
+                if (recognition !== rec)
+                    return;
                 listening = false;
                 recognition = null;
             };

package/dist/esm/version.d.ts

@@ -5,5 +5,5 @@
  * Auto-generated by scripts/sync-sdk-version.mjs from package.json. Do not edit
  * by hand — change package.json `version` and re-run the sync/release script.
  */
-export declare const SDK_VERSION = "0.1.18";
+export declare const SDK_VERSION = "0.1.20";
 export declare const SDK_PACKAGE = "@fiodos/web-core";

package/dist/esm/version.js

@@ -5,5 +5,5 @@
  * Auto-generated by scripts/sync-sdk-version.mjs from package.json. Do not edit
  * by hand — change package.json `version` and re-run the sync/release script.
  */
-export const SDK_VERSION = '0.1.18';
+export const SDK_VERSION = '0.1.20';
 export const SDK_PACKAGE = '@fiodos/web-core';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiodos/web-core",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "Framework-agnostic browser layer for the Fiodos agent: a vanilla AgentController (orchestrator), DOM adapters (navigation/voice/storage), HTTP client and decision engine over @fiodos/core. Shared base for @fiodos/vue, @fiodos/svelte and @fiodos/angular (no framework imports).",
   "license": "SEE LICENSE IN LICENSE",
   "publishConfig": {