@nxisai/agent-harness 0.4.1 → 0.6.0

package/dist/ui/agent-fullscreen.js

@@ -32,7 +32,7 @@ import { TAILWIND_CSS } from './tailwind.generated.js';
 import { emitAsk, emitStep } from '../a2ui/stepper.js';
 import { AgentHarness, isAbort } from '../harness/harness.js';
 import { WebMcpTools } from '../harness/tools/webmcp.js';
-import { extractResult, missingRequired, toolSchema, } from '../harness/tools/schema.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 { resumePendingAction } from '../harness/tools/resume.js';
@@ -42,6 +42,8 @@ import { OPEN_PAGE_TOOL } from '../harness/tools/open-page.js';
 import { 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.
@@ -186,6 +188,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();
@@ -249,6 +280,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 +313,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'),
@@ -359,6 +396,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 +482,8 @@ class NxisAgentFullscreen extends HTMLElement {
         this._offJourney = null;
         this._journeyObserver?.disconnect();
         this._journeyObserver = null;
+        // 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 +551,7 @@ class NxisAgentFullscreen extends HTMLElement {
             this._renderHistory();
             this._renderThread();
             this._saveConversations();
+            this._paintHandoffBar();
         }
         if (this._els.input)
             this._els.input.focus();
@@ -521,6 +566,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
@@ -622,6 +669,8 @@ class NxisAgentFullscreen extends HTMLElement {
                 this._els.thread.appendChild(this._metricsEl(it));
             else if (it.kind === 'journey')
                 this._els.thread.appendChild(this._journeyEl(it));
+            else if (it.kind === 'remote' || it.kind === 'handoff')
+                this._paintHandoffItem(it);
         }
         this._scroll();
         this._watchRunningJourney();
@@ -1196,6 +1245,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;
@@ -1242,6 +1303,17 @@ class NxisAgentFullscreen extends HTMLElement {
             results: (tool, res) => {
                 const conv = this._active();
                 const item = this._buildResultsItem(tool, res);
+                // A read that answers in words — "you are on the home page", "already open" — has no records
+                // to draw, and an empty result card reading "No results found." contradicts the answer it
+                // just gave. Say what it said.
+                const prose = item.cards.length ? '' : proseAnswer(res);
+                if (prose) {
+                    this._appendMsg('assistant', prose);
+                    this._upsertMetrics();
+                    this._saveConversations();
+                    this._scroll();
+                    return;
+                }
                 conv?.items.push(item);
                 this._els.thread.appendChild(this._resultsEl(item));
                 this._upsertMetrics();
@@ -1615,6 +1687,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.
@@ -2321,6 +2406,171 @@ 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();
+        }
+    }
+    _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;
@@ -2500,7 +2750,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 ─────────────────────────────────────────────────────────────
@@ -3385,6 +3638,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
@@ -3598,6 +3868,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>