@nxisai/agent-harness 0.5.0 → 0.6.0

package/src/ui/agent-fullscreen.ts

@@ -53,6 +53,14 @@ import { OPEN_PAGE_TOOL } from '../harness/tools/open-page.js';
 import { 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,
+} 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 {
@@ -319,7 +327,42 @@ 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 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 +387,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. */
@@ -455,6 +502,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 +539,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')!,
@@ -579,6 +632,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 +715,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). */
@@ -729,6 +788,7 @@ class NxisAgentFullscreen extends HTMLElement {
       this._renderHistory();
       this._renderThread();
       this._saveConversations();
+      this._paintHandoffBar();
     }
     if (this._els.input) this._els.input.focus();
   }
@@ -742,6 +802,8 @@ class NxisAgentFullscreen extends HTMLElement {
     this._setNav(false);
     this._renderHistory();
     this._renderThread();
+    this._paintHandoffBar();
+    void this._handoff?.resume(id);
   }
 
   private _renderHistory(): void {
@@ -842,6 +904,7 @@ class NxisAgentFullscreen extends HTMLElement {
       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 === 'remote' || it.kind === 'handoff') this._paintHandoffItem(it);
     }
     this._scroll();
     this._watchRunningJourney();
@@ -1438,6 +1501,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;
@@ -1905,6 +1980,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.
@@ -2644,6 +2733,171 @@ 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();
+    }
+  }
+
+  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;
@@ -2836,7 +3090,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;
   }
 
@@ -3745,6 +4002,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 +4232,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>