@nxisai/agent-harness 0.5.0 → 0.7.0

package/dist/ui/agent-fullscreen.js

@@ -34,14 +34,19 @@ import { AgentHarness, isAbort } from '../harness/harness.js';
 import { WebMcpTools } from '../harness/tools/webmcp.js';
 import { extractResult, proseAnswer, missingRequired, toolSchema, } from '../harness/tools/schema.js';
 import { connectTools } from '../harness/tools/source.js';
-import { handoffFor, isSiteTool, withoutSiteSuffix, HANDOFF_RESULT, } from '../harness/tools/action-tools.js';
+import { chooserOf, formOptions, handoffFor, isSiteTool, withoutSiteSuffix, HANDOFF_RESULT, } from '../harness/tools/action-tools.js';
+import { resolveSlots } from '../harness/slots.js';
+import { isHandoffTool } from '../handoff/tools.js';
+import { actionCard, fieldLabel, fieldsFromSlots, ACTION_CARD_CSS, } from './action-card.js';
 import { resumePendingAction } from '../harness/tools/resume.js';
 import { savePendingVisit, setConversationSource, takePendingVisit } from '../harness/tools/pending-action.js';
 import { pageForEntity } from '../harness/tools/site-pages.js';
 import { OPEN_PAGE_TOOL } from '../harness/tools/open-page.js';
-import { onJourneyChange, recordStep, restoreJourney } from '../harness/steps.js';
+import { currentJourney, onJourneyChange, recordStep, restoreJourney } from '../harness/steps.js';
 import { viewJourney } from './journey.js';
 import { AgentCoordinator } from '../harness/router/coordinator.js';
+import { HandoffController, isHandoffOver, } from '../handoff/controller.js';
+import { registerHandoffTools, HANDOFF_SESSION_RESULT } from '../handoff/tools.js';
 import { LocalGemmaProvider, humanize, escapeHtml, NXIS_LOGO_SVG, NXIS_SITE_URL, ICON_CHECK, ICON_WARN, ICON_ARROW, ICON_PLUS, ICON_MENU, ICON_TRASH, ICON_STOP, ICON_COPY, ICON_PENCIL, ICON_REDO, ICON_CHECK_MARK, } from '../engine.js';
 import { DEFAULT_SYSTEM_PROMPT, DEFAULT_SUGGESTIONS, DEFAULT_EMPTY_STATE, DEFAULT_AGENT_NAME, DEFAULT_LOGO, THEME_TOKENS, PROFILE_ALIASES, } from './config.js';
 // Prefixed keys so state never collides with other Nxis examples on the same origin.
@@ -76,6 +81,11 @@ const fmt = (n) => n.toLocaleString();
  * be disabled under `prefers-reduced-motion` while the bubble still reads as
  * pending. The label and byte spans are filled per phase and hidden while empty.
  */
+/**
+ * How long the running-step line stays once the conversation moves on past
+ * its card. A glance's worth: long enough to notice and open it.
+ */
+const JSTATUS_TIMEOUT_MS = 10000;
 const THINKING_MARKUP = '<span class="think-row">' +
     '<span class="think-dots" aria-hidden="true"><i></i><i></i><i></i></span>' +
     '<span class="think-label"></span>' +
@@ -186,6 +196,35 @@ function fillMessage(el, text) {
         }
     }
 }
+/**
+ * A handoff's state as a line in the thread, or '' for a state the bar alone
+ * shows.
+ */
+function handoffLine(session) {
+    const who = session.label;
+    switch (session.state) {
+        case 'connecting':
+            return `Connecting you to ${who}…`;
+        case 'queued':
+            // The bar says where they are in line; a desk usually says it in words too.
+            return '';
+        case 'active':
+            return session.operator && session.operator !== who ? `${session.operator} has joined` : `You're talking with ${who}`;
+        case 'awaiting-visitor':
+            return '';
+        case 'handed-back':
+            return 'Back with the assistant';
+        case 'ended':
+            return `${who} has finished. Back with the assistant.`;
+        case 'failed':
+            return `${session.error ?? `${who} couldn't continue.`} Back with the assistant.`;
+    }
+}
+function ordinal(n) {
+    const s = ['th', 'st', 'nd', 'rd'];
+    const v = n % 100;
+    return `${n}${s[(v - 20) % 10] || s[v] || s[0]}`;
+}
 class NxisAgentFullscreen extends HTMLElement {
     constructor() {
         super();
@@ -214,6 +253,12 @@ class NxisAgentFullscreen extends HTMLElement {
         };
         /** Watches whether the running journey's card is on screen. */
         this._journeyObserver = null;
+        /** The journey the status line is about, while one is running. */
+        this._jstatusJourney = null;
+        /** Journeys whose status line was opened once or timed out: it does not come back. */
+        this._jstatusDismissed = new Set();
+        /** Dismisses the status line a while after the thread moves on past the card. */
+        this._jstatusTimer = null;
         /** Built only when the host defines agents — otherwise there is one harness. */
         this._coordinator = null;
         this._agentDefs = null;
@@ -221,6 +266,14 @@ class NxisAgentFullscreen extends HTMLElement {
         this._fallbackAgent = '';
         /** The live ask/confirm surface, if one is open. */
         this._prompt = null;
+        /**
+         * The action card still waiting on the visitor or a result, and what it can
+         * do: the harness's ask or confirm request, or, after a page change, a call
+         * of the widget's own.
+         */
+        this._live = null;
+        /** Handoff targets as the relay last reported them, for a card's availability line. */
+        this._handoffTargets = new Map();
         this._persistPrefs = false;
         this._systemPrompt = DEFAULT_SYSTEM_PROMPT;
         this._suggestions = DEFAULT_SUGGESTIONS;
@@ -249,6 +302,9 @@ class NxisAgentFullscreen extends HTMLElement {
         this._emptyLoading = null;
         /** A provider the host supplied, used instead of the local model. */
         this._provider = null;
+        /** Runs handoffs to agents and people, when the host configured any. */
+        this._handoff = null;
+        this._offHandoff = null;
         this.attachShadow({ mode: 'open' });
         this._turnActive = false;
         this._tool = null; // tool of the live inline form (if any)
@@ -279,6 +335,9 @@ class NxisAgentFullscreen extends HTMLElement {
             status: root.querySelector('.statusline'),
             bar: root.querySelector('.prog > i'),
             jstatus: root.querySelector('.jstatus'),
+            handoffBar: root.querySelector('.handoff-bar'),
+            handoffLabel: root.querySelector('.handoff-bar .hb-label'),
+            handoffBack: root.querySelector('.handoff-bar .hb-back'),
             input: root.querySelector('.composer textarea'),
             go: root.querySelector('.composer .go'),
             toolsBtn: root.querySelector('.tools-btn'),
@@ -312,13 +371,7 @@ class NxisAgentFullscreen extends HTMLElement {
         this._buildAgents();
         // The element renders; the harness decides. Everything from choosing a
         // tool to running it happens behind harness.turn().
-        this._harness = new AgentHarness({
-            provider: this.provider,
-            toolSource: this.toolSource,
-            renderer: this._renderer(),
-            profile: (schema) => this._profileForSchema(schema),
-            onMessages: () => this._saveConversations(),
-        });
+        this._harness = this._singleHarness();
         // Preferences are supplied by the host page through `element.preferences`.
         // Anything a previous build persisted is picked up so upgrading does not
         // silently drop a user's saved details; `persist` then stays true so they
@@ -350,6 +403,8 @@ class NxisAgentFullscreen extends HTMLElement {
         this._els.jstatus.addEventListener('click', () => {
             const cards = this._els.thread.querySelectorAll('.journey.is-running');
             cards[cards.length - 1]?.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
+            // One look is what it is for; after that it would only be in the way.
+            this._dismissJourneyStatus();
         });
         // Whoever builds the tools, a call that leaves this page reports back to
         // the thread it was made in.
@@ -359,6 +414,11 @@ class NxisAgentFullscreen extends HTMLElement {
         void this._resumePendingAction();
         this._resumePendingVisit();
         this._els.launcher.addEventListener('click', () => this._open());
+        this._els.handoffBack.addEventListener('click', () => void this._endHandoff());
+        // A handoff left open on the last page carries on here.
+        this._paintHandoffBar();
+        if (this._activeId)
+            void this._handoff?.resume(this._activeId);
         this._els.close.addEventListener('click', () => {
             this._els.overlay.classList.remove('show');
             // A remote turn can outlive the panel, and its answer would go unread.
@@ -440,6 +500,9 @@ class NxisAgentFullscreen extends HTMLElement {
         this._offJourney = null;
         this._journeyObserver?.disconnect();
         this._journeyObserver = null;
+        this._clearJourneyStatusTimer();
+        // Streams stop with the element; the handoff itself stays saved, and resumes when it returns.
+        this._handoff?.dispose();
     }
     /** Programmatic open (used by pages that dock the agent full-page). */
     open() {
@@ -507,6 +570,7 @@ class NxisAgentFullscreen extends HTMLElement {
             this._renderHistory();
             this._renderThread();
             this._saveConversations();
+            this._paintHandoffBar();
         }
         if (this._els.input)
             this._els.input.focus();
@@ -521,6 +585,8 @@ class NxisAgentFullscreen extends HTMLElement {
         this._setNav(false);
         this._renderHistory();
         this._renderThread();
+        this._paintHandoffBar();
+        void this._handoff?.resume(id);
     }
     _renderHistory() {
         this._els.history.innerHTML = this._conversations
@@ -620,8 +686,15 @@ class NxisAgentFullscreen extends HTMLElement {
                 this._els.thread.appendChild(this._resultsEl(it));
             else if (it.kind === 'metrics')
                 this._els.thread.appendChild(this._metricsEl(it));
-            else if (it.kind === 'journey')
-                this._els.thread.appendChild(this._journeyEl(it));
+            else if (it.kind === 'journey') {
+                // A request drawn as an action card shows its own steps.
+                if (!conv.items.some((a) => a.kind === 'action' && a.id === it.id))
+                    this._els.thread.appendChild(this._journeyEl(it));
+            }
+            else if (it.kind === 'action')
+                this._paintAction(it);
+            else if (it.kind === 'remote' || it.kind === 'handoff')
+                this._paintHandoffItem(it);
         }
         this._scroll();
         this._watchRunningJourney();
@@ -989,6 +1062,14 @@ class NxisAgentFullscreen extends HTMLElement {
             item = { kind: 'journey', id: view.id, steps: all };
             conv.items.push(item);
         }
+        // A request with an action card: the steps belong in the card.
+        const action = conv.items.find((it) => it.kind === 'action' && it.id === view.id);
+        if (action) {
+            this._actionFollows(action, all);
+            this._watchRunningJourney();
+            this._saveConversations();
+            return;
+        }
         if (conv.id === this._activeId && this._els?.thread) {
             const fresh = this._journeyEl(item);
             const old = this._els.thread.querySelector(`[data-journey="${CSS.escape(view.id)}"]`);
@@ -1022,7 +1103,12 @@ class NxisAgentFullscreen extends HTMLElement {
             return;
         const cards = this._els.thread.querySelectorAll('.journey.is-running');
         const card = cards[cards.length - 1];
-        if (!card || typeof IntersectionObserver === 'undefined') {
+        const id = card?.dataset.journey ?? null;
+        if (id !== this._jstatusJourney) {
+            this._clearJourneyStatusTimer();
+            this._jstatusJourney = id;
+        }
+        if (!card || !id || this._jstatusDismissed.has(id) || typeof IntersectionObserver === 'undefined') {
             bar.hidden = true;
             return;
         }
@@ -1032,6 +1118,37 @@ class NxisAgentFullscreen extends HTMLElement {
         }, { root: this._els.thread, threshold: 0.2 });
         this._journeyObserver.observe(card);
     }
+    /**
+     * The thread grew: start the clock on the status line.
+     *
+     * A journey can stay running while the conversation goes on without it, and a
+     * line that spins through all of that says nothing. So once new messages
+     * arrive, the line gets a while longer, then goes.
+     */
+    _noteThreadGrew() {
+        const id = this._jstatusJourney;
+        if (!id || this._jstatusTimer || this._jstatusDismissed.has(id))
+            return;
+        this._jstatusTimer = setTimeout(() => {
+            this._jstatusTimer = null;
+            this._dismissJourneyStatus();
+        }, JSTATUS_TIMEOUT_MS);
+    }
+    /** Hide the status line for the running journey, for good. */
+    _dismissJourneyStatus() {
+        this._clearJourneyStatusTimer();
+        if (this._jstatusJourney)
+            this._jstatusDismissed.add(this._jstatusJourney);
+        this._journeyObserver?.disconnect();
+        this._journeyObserver = null;
+        if (this._els?.jstatus)
+            this._els.jstatus.hidden = true;
+    }
+    _clearJourneyStatusTimer() {
+        if (this._jstatusTimer)
+            clearTimeout(this._jstatusTimer);
+        this._jstatusTimer = null;
+    }
     _paintToolResult(name, text, isError) {
         this._clearEmpty();
         const el = this._toolEl(name, text, isError);
@@ -1088,6 +1205,7 @@ class NxisAgentFullscreen extends HTMLElement {
         const el = this._paintMsg(role, text, conv.items.length - 1);
         this._saveConversations();
         this._scroll();
+        this._noteThreadGrew();
         return el;
     }
     /**
@@ -1107,6 +1225,7 @@ class NxisAgentFullscreen extends HTMLElement {
         // without the focus moving to it.
         el.setAttribute('aria-live', 'polite');
         this._scroll();
+        this._noteThreadGrew();
         const setLabel = (label) => {
             const node = el.querySelector('.think-label');
             if (node)
@@ -1196,6 +1315,18 @@ class NxisAgentFullscreen extends HTMLElement {
             this._renderHistory();
             this._saveConversations();
         }
+        // Handed off: this message is for the target, not the assistant.
+        const handed = this._handoff?.active(this._activeId ?? undefined);
+        if (handed && this._activeId) {
+            try {
+                await this._handoff.send(this._activeId, goal);
+            }
+            catch (err) {
+                const why = this._handoff.session(this._activeId)?.error ?? String(err?.message || err);
+                this._appendHandoffItem(this._activeId, { kind: 'handoff', text: why, tone: 'error' });
+            }
+            return;
+        }
         this._turnActive = true;
         this._setStoppable(true);
         let settle;
@@ -1237,8 +1368,10 @@ class NxisAgentFullscreen extends HTMLElement {
             message: (role, text) => this._appendMsg(role, text),
             streaming: () => this._appendStreaming(),
             status: (text, isError) => this._setStatus(text, isError),
-            ask: (req) => this._renderAsk(req),
-            confirm: (req) => this._renderConfirm(req),
+            inlinePrompts: !this._classicPrompts,
+            ask: (req) => (this._usesCard(req.tool) ? this._cardAsk(req) : this._renderAsk(req)),
+            confirm: (req) => (this._usesCard(req.tool) ? this._cardConfirm(req) : this._renderConfirm(req)),
+            left: (tool, destination) => this._cardLeft(tool, destination),
             results: (tool, res) => {
                 const conv = this._active();
                 const item = this._buildResultsItem(tool, res);
@@ -1260,6 +1393,8 @@ class NxisAgentFullscreen extends HTMLElement {
                 this._scroll();
             },
             detail: (tool, values, text) => {
+                if (this._cardDone(tool, values, text))
+                    return;
                 const conv = this._active();
                 const item = this._buildDetailItem(tool, values, text);
                 conv?.items.push(item);
@@ -1284,8 +1419,24 @@ class NxisAgentFullscreen extends HTMLElement {
                 this._saveConversations();
                 this._scroll();
             },
-            toolError: (tool, message) => this._paintToolResult(tool.name, message, true),
-            dismissPrompt: () => this._dismissPrompt(),
+            toolError: (tool, message) => {
+                if (this._cardFailed(tool, message))
+                    return;
+                this._paintToolResult(tool.name, message, true);
+            },
+            dismissPrompt: () => {
+                // A sent card stays, and shows the steps; one never sent says so.
+                const live = this._live;
+                if (live) {
+                    if (live.sent && (live.item.stage === 'review' || live.item.stage === 'collect')) {
+                        live.item.stage = 'working';
+                        this._paintAction(live.item);
+                        this._saveConversations();
+                    }
+                    return;
+                }
+                this._dismissPrompt();
+            },
             // The harness says when stopping stops being possible, because it is the
             // part that knows a tool has been invoked. Once a call is out, offering
             // to stop would be offering to un-send a booking.
@@ -1417,6 +1568,378 @@ class NxisAgentFullscreen extends HTMLElement {
         this._formEl = wrap;
         this._scroll();
     }
+    // ── Action cards ─────────────────────────────────────────────────────────────
+    /** `prompt-style="classic"`: the separate ask, review and submitted cards of earlier versions. */
+    get _classicPrompts() {
+        return this.getAttribute('prompt-style') === 'classic';
+    }
+    /** Whether a prompt for this tool is drawn as an action card: every write and handoff. */
+    _usesCard(tool) {
+        return !this._classicPrompts && (isHandoffTool(tool.name) || !tool.annotations?.readOnlyHint);
+    }
+    /** Details are missing: the card asks for them, beside what it already has. */
+    _cardAsk(req) {
+        const needed = new Set(req.plan.steps.flatMap((st) => st.slots.map((sl) => sl.name)));
+        const item = this._liveCard(req.tool, req.resolution.all, req.resolution.values, needed);
+        this._live.ask = req;
+        this._live.confirm = undefined;
+        item.stage = 'collect';
+        this._paintAction(item);
+        this._saveConversations();
+    }
+    /** Everything is known: the card says what will happen, and waits for Send. */
+    _cardConfirm(req) {
+        const all = resolveSlots(toolSchema(req.tool), { modelArgs: req.values }).all;
+        const item = this._liveCard(req.tool, all, req.values, new Set(), req.destination);
+        this._live.confirm = req;
+        item.stage = 'review';
+        this._paintAction(item);
+        this._saveConversations();
+    }
+    /**
+     * The live card for a tool's prompt: the one already open for this request,
+     * or a new one, which takes over from the journey card of the same request.
+     */
+    _liveCard(tool, slots, values, needed, destination) {
+        const conv = this._active();
+        const id = currentJourney() ?? `a${Date.now().toString(36)}`;
+        const live = this._live;
+        const described = this._describeAction(tool, values, destination);
+        const fields = fieldsFromSlots(this._narrowed(tool, slots, values), values, { needed, hidden: described.hidden, labels: described.labels });
+        if (live && live.item.id === id && live.tool.name === tool.name) {
+            // The same request, a step on: keep what was typed, and anything the harness has since learned.
+            live.item.fields = fields.map((f) => {
+                const had = live.item.fields.find((o) => o.name === f.name);
+                return had && f.value === '' ? { ...f, value: had.value } : f;
+            });
+            Object.assign(live.item, described.view);
+            live.tool = tool;
+            return live.item;
+        }
+        // A request left waiting is replaced by the new one.
+        if (live && (live.item.stage === 'collect' || live.item.stage === 'review')) {
+            live.item.stage = 'declined';
+            this._paintAction(live.item);
+        }
+        const item = { kind: 'action', id, tool: tool.name, fields, stage: 'collect', ...described.view };
+        conv.items.push(item);
+        this._live = { item, tool, sent: false, declining: false };
+        this._els?.thread?.querySelector(`[data-journey="${CSS.escape(id)}"]`)?.remove();
+        this._watchRunningJourney();
+        if (isHandoffTool(tool.name))
+            void this._refreshHandoffTargets(item);
+        return item;
+    }
+    /**
+     * The slots with each field's options cut to the form the call means: one
+     * business's services rather than every business's.
+     */
+    _narrowed(tool, slots, values) {
+        const options = formOptions(tool, values);
+        return slots.map((slot) => {
+            const only = options[slot.name];
+            if (!only)
+                return slot;
+            // Keep a value the call already gave, even one the form does not list: the form decides.
+            const current = values[slot.name];
+            const list = current !== undefined && current !== '' && !only.includes(String(current)) ? [String(current), ...only] : only;
+            return { ...slot, schema: { ...slot.schema, enum: list } };
+        });
+    }
+    /** Who a request goes to, and how the card words it. */
+    _describeAction(tool, values, destination) {
+        const email = String(values.email ?? Object.entries(values).find(([k]) => /e-?mail/i.test(k))?.[1] ?? '').trim();
+        if (isHandoffTool(tool.name)) {
+            const name = String(values.target ?? '');
+            const config = this._handoff?.config?.targets[name];
+            const known = this._handoffTargets.get(name);
+            const label = known?.label ?? config?.label ?? fieldLabel(name || 'the team');
+            const person = (known?.kind ?? config?.kind) !== 'agent';
+            const away = known ? !known.available : false;
+            // "The directory team" leads a line, but mid-sentence it is "the directory team".
+            const inline = label.replace(/^The\s/, 'the ');
+            const about = known?.description ?? config?.description;
+            const status = !known
+                ? undefined
+                : away
+                    ? `Away now${known.hours ? ` · open ${known.hours}` : ''}`
+                    : person
+                        ? known.waitMinutes
+                            ? `Available · replies in ~${known.waitMinutes} min`
+                            : 'Available'
+                        : 'Available';
+            const sentence = !person
+                ? `I'll hand this conversation to ${inline}. They'll take it from here.`
+                : away
+                    ? email
+                        ? `${label} is away right now. They'll reply to ${email}.`
+                        : `${label} is away right now. Leave an email and they'll reply there.`
+                    : `I'll pass this to ${inline} so you don't have to repeat yourself.`;
+            return {
+                view: {
+                    variant: person ? 'handoff-person' : 'handoff-agent',
+                    noun: person ? 'handoff' : 'handover',
+                    identity: { name: label, sub: about ? about.charAt(0).toUpperCase() + about.slice(1) : undefined, status, tone: away ? 'away' : 'ok' },
+                    sentence,
+                    note: undefined,
+                    sendLabel: !person ? 'Hand over' : away ? `Send to ${inline}` : 'Connect me',
+                },
+                hidden: new Set(['target']),
+                labels: { reason: 'Why', summary: 'What they need to know', email: 'Where should they reply?' },
+            };
+        }
+        const noun = fieldLabel(withoutSiteSuffix(tool.name)).toLowerCase();
+        // Which business or place it is for: the site tool's own chooser, else a field the form names it in.
+        const chooser = chooserOf(tool) ?? Object.keys(values).find((k) => /^(business|company|organi[sz]ation|provider|vendor|store|restaurant|practice|venue)(_name)?$/i.test(k)) ?? null;
+        const chosen = chooser ? String(values[chooser] ?? '').trim() : '';
+        const leaving = destination ?? handoffFor(tool, values)?.label;
+        const name = chosen || leaving || this._pageName();
+        // What the conversation already showed about them: their card from a search.
+        const card = this._conversations
+            .find((c) => c.id === this._activeId)
+            ?.items.flatMap((it) => (it.kind === 'results' ? it.cards : []))
+            .find((c) => c.title.toLowerCase() === name.toLowerCase());
+        const sub = [fieldLabel(noun), card?.type && card.type !== 'Thing' ? fieldLabel(card.type) : '', card?.rating ? `★ ${card.rating}` : '']
+            .filter(Boolean)
+            .join(' · ');
+        return {
+            view: {
+                variant: 'form',
+                noun,
+                identity: { name, sub },
+                sentence: `I'll send this ${noun} to ${name}.${email ? ` They'll reply to ${email}.` : ''}`,
+                note: leaving ? 'Their form is on its own page. I’ll open it and send it from there.' : undefined,
+                sendLabel: 'Send',
+            },
+            hidden: new Set(chooser && chooser !== 'target' && chosen ? [chooser] : chooser === 'target' ? ['target'] : []),
+            labels: {},
+        };
+    }
+    /** The site's name for this page: its title, without the site's own name after it. */
+    _pageName() {
+        const title = (typeof document === 'undefined' ? '' : document.title).split(/\s+[|—–·-]\s+/)[0].trim();
+        return title || 'this page';
+    }
+    /** Read availability for a handoff card, and redraw it once known. */
+    async _refreshHandoffTargets(item) {
+        const targets = await this._handoff?.targets().catch(() => []);
+        for (const t of targets ?? [])
+            this._handoffTargets.set(t.name, t);
+        if (item.stage !== 'collect' && item.stage !== 'review')
+            return;
+        const values = Object.fromEntries(item.fields.map((f) => [f.name, f.value]));
+        Object.assign(item, this._describeAction({ name: item.tool }, values).view);
+        this._paintAction(item);
+    }
+    /** What the live card's buttons do. */
+    _actionHandlers() {
+        return {
+            continue: (values) => {
+                const live = this._live;
+                if (!live)
+                    return;
+                if (live.ask && !live.confirm) {
+                    live.ask.onComplete(values);
+                    return;
+                }
+                // Back from a change, or a card of the widget's own: review again, here.
+                Object.assign(live.item, this._describeAction(live.tool, values, live.confirm?.destination).view);
+                live.item.stage = 'review';
+                this._paintAction(live.item);
+                this._saveConversations();
+            },
+            change: () => {
+                const live = this._live;
+                if (!live)
+                    return;
+                live.item.fields.forEach((f) => {
+                    if (f.group === 'needed' && f.value.trim() !== '')
+                        f.group = 'known';
+                });
+                live.sent = false;
+                live.item.stage = 'collect';
+                live.item.open = true;
+                this._paintAction(live.item);
+                this._saveConversations();
+            },
+            send: (values) => {
+                const live = this._live;
+                if (!live)
+                    return;
+                live.sent = true;
+                if (live.confirm)
+                    live.confirm.onSubmit(values);
+                else if (live.run)
+                    void live.run(values);
+            },
+            decline: () => {
+                const live = this._live;
+                if (!live)
+                    return;
+                live.declining = true;
+                if (live.confirm)
+                    live.confirm.onCancel();
+                else if (live.ask)
+                    live.ask.onCancel();
+                // A card the harness is not waiting on declines itself.
+                if (this._live === live) {
+                    live.item.stage = 'declined';
+                    this._paintAction(live.item);
+                    this._live = null;
+                    this._saveConversations();
+                }
+            },
+        };
+    }
+    /** Draw a card where it was, or at the end of the thread. */
+    _paintAction(item) {
+        if (!this._els?.thread)
+            return;
+        const conv = this._active();
+        if (!conv?.items.includes(item))
+            return;
+        const live = this._live?.item === item;
+        const fresh = actionCard(item, live ? this._actionHandlers() : null, () => this._saveConversations());
+        const old = this._els.thread.querySelector(`[data-action="${CSS.escape(item.id)}"]`);
+        if (old)
+            old.replaceWith(fresh);
+        else {
+            this._clearEmpty();
+            this._els.thread.appendChild(fresh);
+            this._scroll();
+        }
+    }
+    /** A request's steps, as its card shows them once sent. */
+    _actionFollows(item, all) {
+        const live = this._live?.item === item ? this._live : null;
+        const failed = [...all].reverse().find((st) => st.status === 'failed');
+        const done = all.some((st) => st.id === 'submit' && st.status === 'done');
+        const running = ['navigate', 'arrive', 'collect', 'fill', 'submit'];
+        item.steps = all
+            .filter((st) => running.includes(st.id))
+            .map((st) => ({
+            label: st.id === 'fill' && st.status === 'active' && item.variant === 'form'
+                ? `Filling in the ${item.noun}`
+                : st.id === 'submit' && st.status === 'done' && item.variant === 'form'
+                    ? 'Sent'
+                    : st.label,
+            status: st.status === 'failed' ? 'failed' : st.status === 'done' ? 'done' : 'active',
+        }));
+        if (failed) {
+            if (live?.declining || failed.label === 'Cancelled') {
+                item.stage = 'declined';
+                if (live)
+                    this._live = null;
+            }
+            else {
+                item.stage = 'failed';
+                item.message = failed.detail || failed.label;
+            }
+        }
+        else if (done) {
+            item.stage = 'done';
+            if (live)
+                this._live = null;
+        }
+        else if (item.stage === 'left' || (item.stage === 'working' && item.steps.length)) {
+            item.stage = 'working';
+        }
+        this._paintAction(item);
+    }
+    /** The confirmed call is leaving for its page. The card says so, and the new page finishes it. */
+    _cardLeft(tool, destination) {
+        const live = this._live;
+        if (!live || live.tool.name !== tool.name) {
+            this._appendMsg('assistant', destination ? `Opening ${destination}…` : 'Opening the page that can submit this…');
+            return;
+        }
+        live.item.stage = 'left';
+        live.item.message = `Opening ${destination ?? live.item.identity.name}’s page to send it from there.`;
+        this._live = null;
+        this._paintAction(live.item);
+        this._saveConversations();
+    }
+    /** The form took it: the card becomes the receipt. False when no card is waiting on this tool. */
+    _cardDone(tool, values, text) {
+        const conv = this._active();
+        const id = currentJourney();
+        const item = conv?.items.find((it) => it.kind === 'action' && it.id === id && it.tool === tool.name);
+        if (!item || this._classicPrompts)
+            return false;
+        const note = this._buildDetailItem(tool, values, text).note;
+        // The default note says nothing the card's "Sent" does not.
+        item.message = /submitted successfully/.test(note) ? undefined : note;
+        item.stage = 'done';
+        item.fields.forEach((f) => {
+            if (values[f.name] !== undefined)
+                f.value = String(values[f.name]);
+        });
+        if (this._live?.item === item)
+            this._live = null;
+        this._paintAction(item);
+        this._saveConversations();
+        return true;
+    }
+    /** It did not go through: the card says why and offers to change it. False when no card is waiting. */
+    _cardFailed(tool, message) {
+        const live = this._live;
+        if (!live || live.tool.name !== tool.name)
+            return false;
+        live.sent = false;
+        live.item.stage = 'failed';
+        live.item.message = message;
+        this._paintAction(live.item);
+        this._saveConversations();
+        return true;
+    }
+    /**
+     * After a page change: the card of the request that travelled, found by its
+     * journey, now finished or asked about here.
+     */
+    _resumedCard(journeyId) {
+        if (!journeyId || this._classicPrompts)
+            return null;
+        return this._active()?.items.find((it) => it.kind === 'action' && it.id === journeyId) ?? null;
+    }
+    /** Let a resumed card be changed and sent again from this page, with the page's own tool. */
+    _reviveCard(item, tool, values, needed) {
+        const slots = resolveSlots(toolSchema(tool), { modelArgs: values }).all;
+        const hidden = new Set(item.fields.filter((f) => f.group === 'hidden').map((f) => f.name));
+        item.fields = fieldsFromSlots(slots, values, { needed: new Set(needed), hidden });
+        this._live = {
+            item,
+            tool,
+            sent: false,
+            declining: false,
+            run: async (vals) => {
+                item.stage = 'working';
+                item.steps = [{ label: `Sending the ${item.noun}`, status: 'active' }];
+                this._paintAction(item);
+                try {
+                    const res = await this.toolSource.execTool(tool, tool.name, vals);
+                    const text = extractResult(res);
+                    if (res?.isError) {
+                        this._cardFailed(tool, text || 'That form did not accept the details.');
+                        return;
+                    }
+                    this._active()?.messages.push({
+                        role: 'user',
+                        content: `[${tool.name} submitted with: ${JSON.stringify(vals)}]. Keep these unless I ask to change them.`,
+                    });
+                    this._live = null;
+                    const note = this._buildDetailItem(tool, vals, text).note;
+                    item.message = /submitted successfully/.test(note) ? undefined : note;
+                    item.stage = 'done';
+                    item.steps = [];
+                    this._paintAction(item);
+                    this._saveConversations();
+                }
+                catch (err) {
+                    this._cardFailed(tool, String(err?.message || err));
+                }
+            },
+        };
+    }
     // ── Inline generated form (from JSON-Schema) ───────────────────────────────
     _renderForm(tool, args) {
         if (this._useA2ui) {
@@ -1626,6 +2149,19 @@ class NxisAgentFullscreen extends HTMLElement {
                 submitBtn.disabled = false;
                 return;
             }
+            // A handoff started: what happens next arrives from the target, and the
+            // controller's events draw it. There is nothing to show as "Submitted".
+            const started = res?.structuredContent?.[HANDOFF_SESSION_RESULT];
+            if (started) {
+                this._dismissPrompt();
+                this._active()?.messages.push({
+                    role: 'user',
+                    content: `[${tool.name}: the conversation was handed to ${started.label ?? 'another agent'}. Their replies go to the visitor directly.]`,
+                });
+                this._saveConversations();
+                this._paintHandoffBar();
+                return;
+            }
             // A call that left for another page has filled in nothing yet, so it
             // must not become a "Submitted" card. The page it is opening finishes
             // the job and draws the card there.
@@ -2293,6 +2829,16 @@ class NxisAgentFullscreen extends HTMLElement {
      * `fallback`. Inexpensive: each agent is a role over the one shared provider,
      * so no additional model is loaded.
      */
+    /** The one agent a page without `agents` runs, on the current provider. */
+    _singleHarness() {
+        return new AgentHarness({
+            provider: this.provider,
+            toolSource: this.toolSource,
+            renderer: this._renderer(),
+            profile: (schema) => this._profileForSchema(schema),
+            onMessages: () => this._saveConversations(),
+        });
+    }
     _buildAgents() {
         if (!this.provider || !this._agentDefs) {
             this._coordinator = null;
@@ -2332,6 +2878,172 @@ class NxisAgentFullscreen extends HTMLElement {
             onRoute: (routed) => this._paintRoute(routed.agent, routed.via),
         });
     }
+    // ── Handoff ────────────────────────────────────────────────────────────────
+    /**
+     * Handing conversations to other agents and to people.
+     *
+     * Set to `{ relay, targets }` to offer `transfer_to_agent` and
+     * `talk_to_a_person` for those targets (see docs/handoff.md). While a
+     * conversation is handed off, what the visitor types goes to the target,
+     * and a bar above the input shows who is listening and the way back.
+     */
+    get handoff() {
+        return this._handoff?.config ?? null;
+    }
+    set handoff(next) {
+        this._offHandoff?.();
+        this._offHandoff = null;
+        this._handoff?.dispose();
+        this._handoff = null;
+        if (!next?.relay || !next.targets) {
+            if (this._els?.thread)
+                this._paintHandoffBar();
+            return;
+        }
+        const controller = new HandoffController(next);
+        const listener = (e) => this._onHandoffEvent(e.detail);
+        controller.addEventListener('handoff', listener);
+        this._offHandoff = () => controller.removeEventListener('handoff', listener);
+        this._handoff = controller;
+        // Tools already connecting or connected: add the handoff tools, and make the next turn wait for them.
+        if (this._connect)
+            this._connect = this._connect.then(() => this._registerHandoffBounded());
+        if (this._els?.thread) {
+            this._paintHandoffBar();
+            if (this._activeId)
+                void controller.resume(this._activeId);
+        }
+    }
+    /** {@link _registerHandoff}, given at most four seconds: a slow relay must not hold up the conversation. */
+    _registerHandoffBounded() {
+        return Promise.race([this._registerHandoff(), new Promise((r) => setTimeout(r, 4000))]).catch((err) => console.warn('[nxis-agent] handoff tools unavailable:', err));
+    }
+    /** Offer the handoff tools on the page's registry. */
+    async _registerHandoff() {
+        const controller = this._handoff;
+        const mc = this.toolSource?.modelContext();
+        if (!controller || !mc)
+            return;
+        const added = await registerHandoffTools(mc, controller, {
+            conversationId: () => this._activeId ?? undefined,
+            transcript: () => this._transcript(),
+        });
+        if (added.length)
+            void this._refreshToolCount();
+    }
+    /** The conversation's last turns, text only, for a target allowed to see them. */
+    _transcript() {
+        const conv = this._active();
+        if (!conv)
+            return [];
+        return conv.items
+            .filter((it) => it.kind === 'msg' && (it.role === 'user' || it.role === 'assistant'))
+            .slice(-10)
+            .map((it) => ({ role: it.role === 'user' ? 'visitor' : 'assistant', text: it.text }));
+    }
+    /** What a handoff reported, into the conversation it belongs to. */
+    _onHandoffEvent(e) {
+        const conv = this._conversations.find((c) => c.id === e.conversationId);
+        if (!conv)
+            return;
+        if (e.type === 'message') {
+            this._appendHandoffItem(conv.id, { kind: 'remote', from: e.from, fromKind: e.fromKind, text: e.text });
+        }
+        else if (e.type === 'handback') {
+            const { outcome, note, references } = e.handBack;
+            const refs = references.map((r) => `${r.label}: ${r.value}`).join(' · ');
+            // The assistant carries on from here, so it learns what happened: the note, and nothing else the
+            // target said. A remote reply is shown to the visitor and never read as an instruction.
+            conv.messages.push({
+                role: 'user',
+                content: `[${e.session.label} handed the conversation back (${outcome})${note ? `: ${note}` : ''}${refs ? `. ${refs}` : ''}]`,
+            });
+            if (refs)
+                this._appendHandoffItem(conv.id, { kind: 'handoff', text: refs, tone: 'done' });
+        }
+        else {
+            const text = handoffLine(e.session);
+            const last = [...conv.items].reverse().find((it) => it.kind === 'handoff');
+            if (text && last?.text !== text) {
+                const tone = e.state === 'failed' ? 'error' : isHandoffOver(e.state) ? 'done' : 'info';
+                this._appendHandoffItem(conv.id, { kind: 'handoff', text, tone });
+            }
+            if (e.state === 'ended' || e.state === 'failed') {
+                conv.messages.push({
+                    role: 'user',
+                    content: `[The conversation with ${e.session.label} ${e.state === 'failed' ? `failed${e.session.error ? `: ${e.session.error}` : ''}` : 'ended'}. You are handling it again.]`,
+                });
+            }
+        }
+        this._saveConversations();
+        if (conv.id === this._activeId)
+            this._paintHandoffBar();
+    }
+    /** Add a handoff item to a conversation, and draw it when that conversation is on screen. */
+    _appendHandoffItem(conversationId, item) {
+        const conv = this._conversations.find((c) => c.id === conversationId);
+        if (!conv)
+            return;
+        conv.items.push(item);
+        this._saveConversations();
+        if (conversationId === this._activeId && this._els?.thread) {
+            this._paintHandoffItem(item);
+            this._scroll();
+            this._noteThreadGrew();
+        }
+    }
+    _paintHandoffItem(item) {
+        this._clearEmpty();
+        let el;
+        if (item.kind === 'remote') {
+            el = document.createElement('div');
+            el.className = 'remote';
+            const who = document.createElement('div');
+            who.className = 'remote-from';
+            who.textContent = item.fromKind === 'agent' ? `${item.from} · agent` : item.from;
+            el.append(who, this._msgEl('assistant', item.text));
+        }
+        else {
+            el = document.createElement('div');
+            el.className = `handoff-note ${item.tone}`;
+            el.textContent = item.text;
+        }
+        this._els.thread.appendChild(el);
+        return el;
+    }
+    /** The bar above the input: shown while the conversation is handed off. */
+    _paintHandoffBar() {
+        if (!this._els?.handoffBar)
+            return;
+        const session = this._handoff?.active(this._activeId ?? undefined) ?? null;
+        this._els.handoffBar.hidden = !session;
+        const input = this._els.input;
+        if (!session) {
+            input.placeholder = 'Message the agent…';
+            input.setAttribute('aria-label', 'Message the agent');
+            return;
+        }
+        const who = session.operator ?? session.label;
+        const q = session.queue;
+        const inLine = q?.position ? ` · ${ordinal(q.position)} in line${q.waitMinutes ? `, about ${q.waitMinutes} min` : ''}` : ' · waiting in line';
+        const doing = session.state === 'connecting'
+            ? ' · connecting…'
+            : session.state === 'queued'
+                ? inLine
+                : session.state === 'awaiting-visitor'
+                    ? ' · waiting for your reply'
+                    : '';
+        this._els.handoffLabel.textContent = `Talking with ${who}${doing}`;
+        input.placeholder = `Message ${who}…`;
+        input.setAttribute('aria-label', `Message ${who}`);
+    }
+    /** "Back to the assistant": end the handoff for this conversation. */
+    async _endHandoff() {
+        if (!this._activeId || !this._handoff)
+            return;
+        await this._handoff.end(this._activeId);
+        this._els.input.focus();
+    }
     /** Zero when the provider cannot count, which hides the token metrics. */
     async countTokens(text) {
         return (await this.provider.countTokens?.(text)) ?? 0;
@@ -2424,6 +3136,42 @@ class NxisAgentFullscreen extends HTMLElement {
         });
         if (outcome.status !== 'none')
             this._setStatus('');
+        // The card that travelled with the request finishes here, when there is one.
+        const card = outcome.status === 'none' ? null : this._resumedCard(outcome.pending.steps?.find((st) => st.journey)?.journey);
+        if (card && outcome.status !== 'none') {
+            switch (outcome.status) {
+                case 'no-registry':
+                case 'no-tool':
+                    card.stage = 'failed';
+                    card.message = `I couldn't find the ${card.noun} on this page, so nothing was sent. Ask me again and I'll fill it in from here.`;
+                    break;
+                case 'incomplete':
+                    this._reviveCard(card, outcome.tool, outcome.pending.values, outcome.missing);
+                    card.stage = 'collect';
+                    card.message = undefined;
+                    break;
+                case 'rejected':
+                case 'failed':
+                    this._reviveCard(card, outcome.tool, outcome.pending.values, []);
+                    card.stage = 'failed';
+                    card.message = outcome.status === 'failed' ? outcome.error : outcome.text || 'That form did not accept the details.';
+                    break;
+                case 'submitted': {
+                    const note = this._buildDetailItem(outcome.tool, outcome.pending.values, outcome.text).note;
+                    card.message = /submitted successfully/.test(note) ? undefined : note;
+                    card.stage = 'done';
+                    this._active()?.messages.push({
+                        role: 'user',
+                        content: `[${outcome.tool.name} submitted with: ${JSON.stringify(outcome.pending.values)}]. ` +
+                            'Keep these unless I ask to change them.',
+                    });
+                    break;
+                }
+            }
+            this._paintAction(card);
+            this._saveConversations();
+            return;
+        }
         switch (outcome.status) {
             case 'none':
                 return;
@@ -2511,7 +3259,10 @@ class NxisAgentFullscreen extends HTMLElement {
                     void this._renderTools();
             });
         })
-            .catch((err) => console.warn('[nxis-agent] tool discovery failed:', err));
+            .catch((err) => console.warn('[nxis-agent] tool discovery failed:', err))
+            // Part of connecting, so the first turn waits for the handoff tools: a turn that ran without
+            // them could only claim, in words, to be handing the visitor over.
+            .then(() => this._registerHandoffBounded());
         return this._connect;
     }
     // ── Tools menu ─────────────────────────────────────────────────────────────
@@ -2742,6 +3493,9 @@ class NxisAgentFullscreen extends HTMLElement {
         if (this._els?.thread) {
             this.provider = next ?? this.provider;
             this._paintProvenance();
+            // Both the single agent and any configured ones: a page without `agents` kept the old
+            // provider's harness, and answered with the model it had just replaced.
+            this._harness = this._singleHarness();
             this._buildAgents();
         }
     }
@@ -2945,6 +3699,9 @@ class NxisAgentFullscreen extends HTMLElement {
       /* A2UI surfaces inherit the tokens above through --a2ui-* bridges. */
       ${A2UI_THEME_CSS}
 
+      /* The action card: forms and handoffs as one message. */
+      ${ACTION_CARD_CSS}
+
       /* App-icon tile: chevron centered in a 56px tile, Soft Gray, hairline. */
       .launcher {
         position: fixed; right: 20px; bottom: 20px; z-index: 9998;
@@ -3396,6 +4153,23 @@ class NxisAgentFullscreen extends HTMLElement {
         padding: 2px 0 6px;
         letter-spacing: .01em;
       }
+
+      /* Handoffs. A target's message is a bubble with its name above; where the
+         handoff stands is a quiet centred line; the bar says who is listening. */
+      .remote { align-self: flex-start; display: flex; flex-direction: column; gap: 4px; max-width: 76%; }
+      .remote .msg { max-width: 100%; }
+      .remote-from { font-family: var(--mono); font-size: 10.5px; letter-spacing: .04em; color: var(--ink-3); padding-left: 4px; }
+      .handoff-note { align-self: center; font-size: 12px; color: var(--ink-3); padding: 2px 12px 6px; text-align: center; letter-spacing: .01em; }
+      .handoff-note.done { color: var(--green-strong); }
+      .handoff-note.error { color: var(--red); }
+      .handoff-bar { display: flex; align-items: center; gap: 8px; margin: 0 20px 6px; padding: 6px 6px 6px 12px; border: 1px solid var(--border); border-radius: var(--radius-sm); background: var(--green-tint); color: var(--ink); font-family: var(--sans); font-size: 12.5px; }
+      .handoff-bar[hidden] { display: none; }
+      .handoff-bar .hb-dot { width: 7px; height: 7px; border-radius: 50%; background: var(--green); flex: none; }
+      .handoff-bar .hb-label { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-weight: 600; }
+      .handoff-bar .hb-back { flex: none; border: 1px solid var(--border-strong); background: var(--surface); color: var(--ink); border-radius: var(--radius-pill); padding: 4px 11px; font: inherit; font-size: 12px; font-weight: 600; cursor: pointer; }
+      .handoff-bar .hb-back:hover { border-color: var(--ink-3); }
+      .handoff-bar .hb-back:focus-visible { outline: 2px solid var(--blue); outline-offset: 2px; }
+      .overlay.window .handoff-bar, .overlay.inline .handoff-bar { margin: 0 14px 6px; }
       .composer .go svg { width: 17px; height: 17px; }
 
       /* Attribution. Quiet enough to sit under a customer's own chat surface
@@ -3609,6 +4383,10 @@ class NxisAgentFullscreen extends HTMLElement {
         </button>
         <div class="thread"></div>
         <div class="statusline"></div>
+        <div class="handoff-bar" role="status" hidden>
+          <span class="hb-dot" aria-hidden="true"></span><span class="hb-label"></span>
+          <button class="hb-back" type="button">Back to the assistant</button>
+        </div>
         <div class="composer">
           <div class="cbox">
             <textarea rows="1" placeholder="Message the agent…" aria-label="Message the agent"></textarea>