@nxisai/agent-harness 0.5.0 → 0.7.0

package/src/ui/agent-fullscreen.ts

@@ -41,18 +41,40 @@ import {
 import type { ModelProvider } from '../providers/types.js';
 import { connectTools } from '../harness/tools/source.js';
 import {
+  chooserOf,
+  formOptions,
   handoffFor,
   isSiteTool,
   withoutSiteSuffix,
   HANDOFF_RESULT,
 } from '../harness/tools/action-tools.js';
+import { resolveSlots, type Slot } from '../harness/slots.js';
+import { isHandoffTool } from '../handoff/tools.js';
+import {
+  actionCard,
+  fieldLabel,
+  fieldsFromSlots,
+  ACTION_CARD_CSS,
+  type ActionHandlers,
+  type ActionItem,
+  type ActionStep,
+} from './action-card.js';
 import { resumePendingAction } from '../harness/tools/resume.js';
 import { savePendingVisit, setConversationSource, takePendingVisit } from '../harness/tools/pending-action.js';
 import { pageForEntity, type SitePage } from '../harness/tools/site-pages.js';
 import { OPEN_PAGE_TOOL } from '../harness/tools/open-page.js';
-import { onJourneyChange, recordStep, restoreJourney, type AgentStep } from '../harness/steps.js';
+import { currentJourney, onJourneyChange, recordStep, restoreJourney, type AgentStep } from '../harness/steps.js';
 import { viewJourney } from './journey.js';
 import { AgentCoordinator } from '../harness/router/coordinator.js';
+import {
+  HandoffController,
+  isHandoffOver,
+  type HandoffConfig,
+  type HandoffEvent,
+  type HandoffSession,
+  type HandoffTarget,
+} from '../handoff/controller.js';
+import { registerHandoffTools, HANDOFF_SESSION_RESULT } from '../handoff/tools.js';
 import type { RouteRule } from '../harness/router/rules.js';
 import type { AskRequest, ConfirmRequest, HarnessRenderer, StreamingBubble as HStreamingBubble } from '../harness/renderer.js';
 import {
@@ -143,6 +165,12 @@ const fmt = (n: number) => 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 = 10_000;
+
 const THINKING_MARKUP =
   '<span class="think-row">' +
   '<span class="think-dots" aria-hidden="true"><i></i><i></i><i></i></span>' +
@@ -319,7 +347,44 @@ type ThreadItem =
    * so a second request does not erase the first, and so a card survives the
    * page change a cross-page action makes.
    */
-  | { kind: 'journey'; id: string; steps: AgentStep[] };
+  | { kind: 'journey'; id: string; steps: AgentStep[] }
+  /** Something a handoff target said: an agent, or a person at a desk. */
+  | { kind: 'remote'; from: string; fromKind: 'agent' | 'person'; text: string }
+  /** Where a handoff stands, as a quiet line in the thread. */
+  | { kind: 'handoff'; text: string; tone: 'info' | 'done' | 'error' }
+  /** A form or a handoff, asked for, confirmed and sent in one card. See ./action-card.ts. */
+  | ActionItem;
+
+/**
+ * A handoff's state as a line in the thread, or '' for a state the bar alone
+ * shows.
+ */
+function handoffLine(session: HandoffSession): string {
+  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: number): string {
+  const s = ['th', 'st', 'nd', 'rd'];
+  const v = n % 100;
+  return `${n}${s[(v - 20) % 10] || s[v] || s[0]}`;
+}
 
 interface Conversation {
   id: string;
@@ -344,6 +409,10 @@ interface FullscreenEls {
   bar: HTMLElement;
   /** Names the running step while its card is scrolled out of view. */
   jstatus: HTMLButtonElement;
+  /** Shown while the conversation is handed off: who to, and the way back. */
+  handoffBar: HTMLElement;
+  handoffLabel: HTMLElement;
+  handoffBack: HTMLButtonElement;
   input: HTMLTextAreaElement;
   go: HTMLButtonElement;
   /** Opens the list of tools the agent can use. */
@@ -410,6 +479,12 @@ class NxisAgentFullscreen extends HTMLElement {
   };
   /** Watches whether the running journey's card is on screen. */
   private _journeyObserver: IntersectionObserver | null = null;
+  /** The journey the status line is about, while one is running. */
+  private _jstatusJourney: string | null = null;
+  /** Journeys whose status line was opened once or timed out: it does not come back. */
+  private _jstatusDismissed = new Set<string>();
+  /** Dismisses the status line a while after the thread moves on past the card. */
+  private _jstatusTimer: ReturnType<typeof setTimeout> | null = null;
   /** The turn loop. This element is only its renderer. */
   private _harness!: AgentHarness;
   /** Built only when the host defines agents — otherwise there is one harness. */
@@ -419,6 +494,22 @@ class NxisAgentFullscreen extends HTMLElement {
   private _fallbackAgent = '';
   /** The live ask/confirm surface, if one is open. */
   private _prompt: MountedSurface | null = 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.
+   */
+  private _live: {
+    item: ActionItem;
+    tool: ModelContextToolInfo;
+    ask?: AskRequest;
+    confirm?: ConfirmRequest;
+    run?: (values: Record<string, unknown>) => Promise<void>;
+    sent: boolean;
+    declining: boolean;
+  } | null = null;
+  /** Handoff targets as the relay last reported them, for a card's availability line. */
+  private _handoffTargets = new Map<string, HandoffTarget>();
   private _profile: Record<string, string>;
   private _persistPrefs = false;
   private _systemPrompt: string = DEFAULT_SYSTEM_PROMPT;
@@ -455,6 +546,9 @@ class NxisAgentFullscreen extends HTMLElement {
   private toolSource!: WebMcpTools;
   /** A provider the host supplied, used instead of the local model. */
   private _provider: ModelProvider | null = null;
+  /** Runs handoffs to agents and people, when the host configured any. */
+  private _handoff: HandoffController | null = null;
+  private _offHandoff: (() => void) | null = null;
 
   constructor() {
     super();
@@ -489,6 +583,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')!,
@@ -526,13 +623,7 @@ class NxisAgentFullscreen extends HTMLElement {
 
     // 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 as JsonSchema),
-      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
@@ -567,6 +658,8 @@ class NxisAgentFullscreen extends HTMLElement {
     this._els.jstatus.addEventListener('click', () => {
       const cards = this._els.thread.querySelectorAll<HTMLElement>('.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
@@ -579,6 +672,10 @@ class NxisAgentFullscreen extends HTMLElement {
     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.
@@ -658,6 +755,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). */
@@ -729,6 +829,7 @@ class NxisAgentFullscreen extends HTMLElement {
       this._renderHistory();
       this._renderThread();
       this._saveConversations();
+      this._paintHandoffBar();
     }
     if (this._els.input) this._els.input.focus();
   }
@@ -742,6 +843,8 @@ class NxisAgentFullscreen extends HTMLElement {
     this._setNav(false);
     this._renderHistory();
     this._renderThread();
+    this._paintHandoffBar();
+    void this._handoff?.resume(id);
   }
 
   private _renderHistory(): void {
@@ -841,7 +944,11 @@ class NxisAgentFullscreen extends HTMLElement {
       else if (it.kind === 'detail') this._els.thread.appendChild(this._detailEl(it));
       else if (it.kind === 'results') 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();
@@ -1225,6 +1332,15 @@ class NxisAgentFullscreen extends HTMLElement {
       conv.items.push(item);
     }
 
+    // A request with an action card: the steps belong in the card.
+    const action = conv.items.find((it): it is ActionItem => 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)}"]`);
@@ -1256,7 +1372,12 @@ class NxisAgentFullscreen extends HTMLElement {
     if (!bar) return;
     const cards = this._els.thread.querySelectorAll<HTMLElement>('.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;
     }
@@ -1270,6 +1391,36 @@ class NxisAgentFullscreen extends HTMLElement {
     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.
+   */
+  private _noteThreadGrew(): void {
+    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. */
+  private _dismissJourneyStatus(): void {
+    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;
+  }
+
+  private _clearJourneyStatusTimer(): void {
+    if (this._jstatusTimer) clearTimeout(this._jstatusTimer);
+    this._jstatusTimer = null;
+  }
+
   private _paintToolResult(name: string, text: string, isError: boolean): HTMLElement {
     this._clearEmpty();
     const el = this._toolEl(name, text, isError);
@@ -1328,6 +1479,7 @@ class NxisAgentFullscreen extends HTMLElement {
     const el = this._paintMsg(role, text, conv.items.length - 1);
     this._saveConversations();
     this._scroll();
+    this._noteThreadGrew();
     return el;
   }
 
@@ -1348,6 +1500,7 @@ class NxisAgentFullscreen extends HTMLElement {
     // without the focus moving to it.
     el.setAttribute('aria-live', 'polite');
     this._scroll();
+    this._noteThreadGrew();
 
     const setLabel = (label?: string) => {
       const node = el.querySelector('.think-label');
@@ -1438,6 +1591,18 @@ class NxisAgentFullscreen extends HTMLElement {
       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 as Error)?.message || err);
+        this._appendHandoffItem(this._activeId, { kind: 'handoff', text: why, tone: 'error' });
+      }
+      return;
+    }
+
     this._turnActive = true;
     this._setStoppable(true);
     let settle!: () => void;
@@ -1477,8 +1642,10 @@ class NxisAgentFullscreen extends HTMLElement {
       message: (role, text) => this._appendMsg(role, text),
       streaming: (): HStreamingBubble => 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);
@@ -1500,6 +1667,7 @@ 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);
@@ -1523,8 +1691,23 @@ 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.
@@ -1673,6 +1856,390 @@ class NxisAgentFullscreen extends HTMLElement {
     this._scroll();
   }
 
+  // ── Action cards ─────────────────────────────────────────────────────────────
+
+  /** `prompt-style="classic"`: the separate ask, review and submitted cards of earlier versions. */
+  private get _classicPrompts(): boolean {
+    return this.getAttribute('prompt-style') === 'classic';
+  }
+
+  /** Whether a prompt for this tool is drawn as an action card: every write and handoff. */
+  private _usesCard(tool: ModelContextToolInfo): boolean {
+    return !this._classicPrompts && (isHandoffTool(tool.name) || !tool.annotations?.readOnlyHint);
+  }
+
+  /** Details are missing: the card asks for them, beside what it already has. */
+  private _cardAsk(req: AskRequest): void {
+    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. */
+  private _cardConfirm(req: ConfirmRequest): void {
+    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.
+   */
+  private _liveCard(
+    tool: ModelContextToolInfo,
+    slots: Slot[],
+    values: Record<string, unknown>,
+    needed: Set<string>,
+    destination?: string,
+  ): ActionItem {
+    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: ActionItem = { 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.
+   */
+  private _narrowed(tool: ModelContextToolInfo, slots: Slot[], values: Record<string, unknown>): Slot[] {
+    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. */
+  private _describeAction(
+    tool: ModelContextToolInfo,
+    values: Record<string, unknown>,
+    destination?: string,
+  ): {
+    view: Pick<ActionItem, 'variant' | 'noun' | 'identity' | 'sentence' | 'note' | 'sendLabel'>;
+    hidden: Set<string>;
+    labels: Record<string, string>;
+  } {
+    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. */
+  private _pageName(): string {
+    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. */
+  private async _refreshHandoffTargets(item: ActionItem): Promise<void> {
+    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 } as ModelContextToolInfo, values).view);
+    this._paintAction(item);
+  }
+
+  /** What the live card's buttons do. */
+  private _actionHandlers(): 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. */
+  private _paintAction(item: ActionItem): void {
+    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. */
+  private _actionFollows(item: ActionItem, all: AgentStep[]): void {
+    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): ActionStep => ({
+        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. */
+  private _cardLeft(tool: ModelContextToolInfo, destination: string | null): void {
+    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. */
+  private _cardDone(tool: ModelContextToolInfo, values: Record<string, unknown>, text: string): boolean {
+    const conv = this._active();
+    const id = currentJourney();
+    const item = conv?.items.find((it): it is ActionItem => 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. */
+  private _cardFailed(tool: ModelContextToolInfo, message: string): boolean {
+    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.
+   */
+  private _resumedCard(journeyId: string | undefined): ActionItem | null {
+    if (!journeyId || this._classicPrompts) return null;
+    return this._active()?.items.find((it): it is ActionItem => 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. */
+  private _reviveCard(item: ActionItem, tool: ModelContextToolInfo, values: Record<string, unknown>, needed: string[]): void {
+    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 as Error)?.message || err));
+        }
+      },
+    };
+  }
+
   // ── Inline generated form (from JSON-Schema) ───────────────────────────────
   private _renderForm(tool: ModelContextToolInfo, args: Record<string, unknown>): void {
     if (this._useA2ui) {
@@ -1905,6 +2472,20 @@ 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] as { label?: string } | undefined;
+      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.
@@ -2603,6 +3184,17 @@ 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. */
+  private _singleHarness(): AgentHarness {
+    return new AgentHarness({
+      provider: this.provider,
+      toolSource: this.toolSource,
+      renderer: this._renderer(),
+      profile: (schema) => this._profileForSchema(schema as JsonSchema),
+      onMessages: () => this._saveConversations(),
+    });
+  }
+
   private _buildAgents(): void {
     if (!this.provider || !this._agentDefs) {
       this._coordinator = null;
@@ -2644,6 +3236,172 @@ class NxisAgentFullscreen extends HTMLElement {
     });
   }
 
+  // ── 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(): HandoffConfig | null {
+    return this._handoff?.config ?? null;
+  }
+  set handoff(next: HandoffConfig | null) {
+    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: Event) => this._onHandoffEvent((e as CustomEvent<HandoffEvent>).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. */
+  private _registerHandoffBounded(): Promise<void> {
+    return Promise.race([this._registerHandoff(), new Promise<void>((r) => setTimeout(r, 4000))]).catch((err) =>
+      console.warn('[nxis-agent] handoff tools unavailable:', err),
+    );
+  }
+
+  /** Offer the handoff tools on the page's registry. */
+  private async _registerHandoff(): Promise<void> {
+    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. */
+  private _transcript(): { role: 'visitor' | 'assistant'; text: string }[] {
+    const conv = this._active();
+    if (!conv) return [];
+    return conv.items
+      .filter((it): it is Extract<ThreadItem, { kind: 'msg' }> => it.kind === 'msg' && (it.role === 'user' || it.role === 'assistant'))
+      .slice(-10)
+      .map((it) => ({ role: it.role === 'user' ? ('visitor' as const) : ('assistant' as const), text: it.text }));
+  }
+
+  /** What a handoff reported, into the conversation it belongs to. */
+  private _onHandoffEvent(e: HandoffEvent): void {
+    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') as
+        | Extract<ThreadItem, { kind: 'handoff' }>
+        | undefined;
+      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. */
+  private _appendHandoffItem(conversationId: string, item: Extract<ThreadItem, { kind: 'remote' | 'handoff' }>): void {
+    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();
+    }
+  }
+
+  private _paintHandoffItem(item: Extract<ThreadItem, { kind: 'remote' | 'handoff' }>): HTMLElement {
+    this._clearEmpty();
+    let el: HTMLElement;
+    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. */
+  private _paintHandoffBar(): void {
+    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. */
+  private async _endHandoff(): Promise<void> {
+    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. */
   private async countTokens(text: string): Promise<number> {
     return (await this.provider.countTokens?.(text)) ?? 0;
@@ -2737,6 +3495,44 @@ 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;
@@ -2836,7 +3632,10 @@ class NxisAgentFullscreen extends HTMLElement {
           if (this._toolsOpen) 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;
   }
 
@@ -3091,6 +3890,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();
     }
   }
@@ -3294,6 +4096,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;
@@ -3745,6 +4550,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
@@ -3958,6 +4780,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>