@nxisai/agent-harness 0.7.0 → 0.9.0

package/src/harness/tools/inbound.ts

@@ -0,0 +1,189 @@
+/**
+ * Arriving from somewhere else to use one of this page's forms.
+ *
+ * The NxisAI app in Claude or ChatGPT cannot fill a form that runs in the
+ * browser, so for such an action it sends the person to the page instead:
+ * `?nxis_handoff=<the action's @id>`, and optionally `&nxis_intent=<what they
+ * want>`. On arrival the agent opens on that form.
+ *
+ * In the query, so the fragment, which some sites route by, is left alone. A
+ * page's structured data is found by its registered address, so the site tag
+ * leaves these two parameters out of the address it asks for.
+ *
+ * A link can be written by anyone, so it only ever chooses which of the page's
+ * own forms to start. The words that start it are the agent's own, built from
+ * the form; the intent is left in the composer for the person to send, change
+ * or delete, never sent on their behalf. Neither parameter carries anything
+ * personal, and both are taken out of the address bar once read.
+ *
+ * @module
+ */
+import { awaitPageTool, withoutSiteSuffix } from './action-tools.js';
+import { waitForModelContext } from './source.js';
+import type { ModelContext, ModelContextToolInfo } from '../../types.js';
+
+/** The action to open on: its `@id`. */
+export const HANDOFF_PARAM = 'nxis_handoff';
+/** What the person wants, in a few words. Optional. */
+export const INTENT_PARAM = 'nxis_intent';
+
+/** Longer than any `@id` the crawler writes; a longer value is not one. */
+const MAX_ID = 512;
+/** A few words: enough for "a quote for a panel upgrade", not a message. */
+export const MAX_INTENT = 120;
+
+/** How long to wait for the registry, and then for the form's own tool. */
+const WAIT_MS = 8000;
+
+/** A handoff read from the address. */
+export interface InboundHandoff {
+  /** The `@id` of the action whose form to open. */
+  actionId: string;
+  /** What the person wants, cleaned up; absent when none was given. */
+  intent?: string;
+}
+
+/**
+ * The handoff in an address, if there is one.
+ *
+ * @param href - The page's address.
+ * @returns The handoff, or null when there is none or it is malformed.
+ */
+export function readInboundHandoff(href: string): InboundHandoff | null {
+  let url: URL;
+  try {
+    url = new URL(href);
+  } catch {
+    return null;
+  }
+  const actionId = (url.searchParams.get(HANDOFF_PARAM) ?? '').trim();
+  if (!actionId || actionId.length > MAX_ID || /\s/.test(actionId)) return null;
+  const intent = cleanIntent(url.searchParams.get(INTENT_PARAM) ?? '');
+  return intent ? { actionId, intent } : { actionId };
+}
+
+/** One line of plain text, at most {@link MAX_INTENT} characters. */
+export function cleanIntent(raw: string): string {
+  // Control characters, newlines included, become spaces: a draft is one line.
+  const flat = raw.replace(/[\u0000-\u001f\u007f]+/g, ' ').replace(/\s+/g, ' ').trim();
+  return flat.length > MAX_INTENT ? flat.slice(0, MAX_INTENT - 1).trimEnd() + '…' : flat;
+}
+
+/**
+ * The address without the handoff parameters, everything else kept.
+ *
+ * A reload, a bookmark or a copied link would otherwise open the form again.
+ */
+export function withoutHandoff(href: string): string {
+  const url = new URL(href);
+  if (!url.search) return url.toString();
+  // Pair by pair on the raw text: re-serializing would re-encode the other
+  // parameters, and the address would no longer be the one the page had.
+  const kept = url.search
+    .slice(1)
+    .split('&')
+    .filter((pair) => ![HANDOFF_PARAM, INTENT_PARAM].includes(decodeName(pair.split('=')[0])));
+  url.search = kept.length ? `?${kept.join('&')}` : '';
+  return url.toString();
+}
+
+/** A query parameter's name, decoded; as written when it can't be. */
+function decodeName(raw: string): string {
+  try {
+    return decodeURIComponent(raw.replace(/\+/g, ' '));
+  } catch {
+    return raw;
+  }
+}
+
+/**
+ * The address that hands someone to an action's page.
+ *
+ * @param pageUrl - The page the action's form is on.
+ * @param actionId - The action's `@id`.
+ * @param intent - What they want, in a few words. Nothing personal.
+ */
+export function handoffUrl(pageUrl: string, actionId: string, intent?: string): string {
+  const url = new URL(pageUrl);
+  // Appended to the raw query, so the page's own parameters keep their encoding.
+  const added = new URLSearchParams({ [HANDOFF_PARAM]: actionId });
+  const said = intent ? cleanIntent(intent) : '';
+  if (said) added.set(INTENT_PARAM, said);
+  url.search = url.search ? `${url.search}&${added}` : `?${added}`;
+  return url.toString();
+}
+
+/**
+ * Read the handoff from this page's address and take it out.
+ *
+ * @param opts - The address and the history to rewrite; the browser's by default.
+ */
+export function takeInboundHandoff(
+  opts: { href?: string; replace?: (href: string) => void } = {},
+): InboundHandoff | null {
+  const href = opts.href ?? (typeof location !== 'undefined' ? location.href : '');
+  const handoff = href ? readInboundHandoff(href) : null;
+  if (!handoff) return null;
+  const replace =
+    opts.replace ??
+    ((next: string) => {
+      try {
+        history.replaceState(history.state, '', next);
+      } catch {
+        // A sandboxed frame can refuse; the handoff is still taken once, below.
+      }
+    });
+  replace(withoutHandoff(href));
+  return handoff;
+}
+
+/** What the agent says to start a form: "Start the quote form". */
+export function startMessage(tool: ModelContextToolInfo): string {
+  return startFormMessage(withoutSiteSuffix(tool.name).replace(/[_-]+/g, ' ').trim().toLowerCase());
+}
+
+/**
+ * What the agent says to start a site form for one business, in the words a
+ * result card's button uses: "Get a quote from McManus Electric".
+ */
+export function startFormMessage(noun: string, choice?: string): string {
+  const named = noun || 'form';
+  const form = /\bform\b/.test(named) ? named : `${named} form`;
+  if (!choice) return `Start the ${form}`;
+  return /quote/.test(named) ? `Get a quote from ${choice}` : `Start the ${form} for ${choice}`;
+}
+
+/** Where the form a handoff names stands, once the page has loaded. */
+export type ArrivalOutcome =
+  /** WebMCP never appeared, so the page's forms cannot be reached. */
+  | { status: 'no-registry' }
+  /** The page has no form for that action. */
+  | { status: 'no-tool' }
+  /** The form is here. */
+  | { status: 'ready'; tool: ModelContextToolInfo };
+
+/** Overrides, so this can be exercised without a page. */
+export interface ArrivalOptions {
+  /** How long to wait for the registry, and then for the tool. */
+  timeoutMs?: number;
+  /** Wait for a WebMCP registry. */
+  registry?(timeoutMs: number): Promise<ModelContext | null>;
+  /** Wait for the page's own tool for this action. */
+  pageTool?(mc: ModelContext, ref: { id: string; name: string }, timeoutMs: number): Promise<ModelContextToolInfo | null>;
+}
+
+/**
+ * Find the form a handoff names, waiting for the page to register it.
+ *
+ * Runs while the page is still loading, as the cross-page resume does: the
+ * registry and the form's tool usually appear a moment after the agent.
+ */
+export async function findHandoffForm(handoff: InboundHandoff, opts: ArrivalOptions = {}): Promise<ArrivalOutcome> {
+  const timeoutMs = opts.timeoutMs ?? WAIT_MS;
+  const mc = await (opts.registry ?? ((ms: number) => waitForModelContext(ms)))(timeoutMs);
+  if (!mc) return { status: 'no-registry' };
+  // By id only: a name match could be a different form on this page.
+  const find = opts.pageTool ?? ((c, ref, ms) => awaitPageTool(c, ref, ms));
+  const tool = await find(mc, { id: handoff.actionId, name: '' }, timeoutMs);
+  return tool ? { status: 'ready', tool } : { status: 'no-tool' };
+}

package/src/harness/tools/site-pages.ts

@@ -194,7 +194,7 @@ export function pageForEntity(entity: Obj, pages: SitePage[], origin: string): S
 /**
  * The page an id formed from it names, or null.
  *
- * nxis-sdn-api forms a page entity's id as the page URL plus a fragment, so the page is the id with
+ * The NxisAI index forms a page entity's id as the page URL plus a fragment, so the page is the id with
  * the fragment removed.
  */
 function pageOfId(id: string | undefined, origin: string): string | null {

package/src/index.ts

@@ -50,6 +50,9 @@ export type { Slot, Resolution, ResolveSources } from './harness/slots.js';
 
 export { buildPlan } from './harness/plan.js';
 
+export { actionCta } from './harness/cta.js';
+export type { CardAction } from './harness/cta.js';
+
 export { AgentCoordinator } from './harness/router/coordinator.js';
 export type { CoordinatorOptions, RoutedTurn, RouteSource } from './harness/router/coordinator.js';
 export { matchRoute } from './harness/router/rules.js';
@@ -60,6 +63,7 @@ export type {
   HarnessRenderer,
   AskRequest,
   ConfirmRequest,
+  ResultsExtra,
   StreamingBubble,
 } from './harness/renderer.js';
 
@@ -133,6 +137,16 @@ export {
 export type { AgentStep, AgentStepId, AgentStepStatus } from './harness/steps.js';
 export { resumePendingAction } from './harness/tools/resume.js';
 export type { ResumeOutcome, ResumeOptions } from './harness/tools/resume.js';
+// Arriving from the NxisAI app to use one of this page's forms.
+export {
+  HANDOFF_PARAM,
+  INTENT_PARAM,
+  readInboundHandoff,
+  takeInboundHandoff,
+  handoffUrl,
+  findHandoffForm,
+} from './harness/tools/inbound.js';
+export type { InboundHandoff, ArrivalOutcome, ArrivalOptions } from './harness/tools/inbound.js';
 export {
   loadSitePages,
   parsePage,
@@ -172,6 +186,8 @@ export {
 } from './harness/tools/pending-action.js';
 export type { PendingAction, PendingVisit } from './harness/tools/pending-action.js';
 export { findEmbeddedAction, loadSiteActions, parseAction, type EmbeddedActionQuery } from './harness/tools/site-actions.js';
+export { extractRecords, openStatus, recordFacts, factLines, type OpenStatus, type RecordFacts } from './harness/records.js';
+export { recommend, grounded, RECOMMEND_TOOL, type ResultPick, type RecommendRequest } from './harness/recommend.js';
 export type { ConnectResult, ConnectOptions, SiteActionsOptions } from './harness/tools/source.js';
 export type { BridgeOptions } from './harness/tools/bridge.js';
 

package/src/ui/agent-fullscreen.ts

@@ -22,6 +22,7 @@
  */
 import { mountSurface, type MountedSurface } from '../a2ui/host.js';
 import { emitCardsSurface, type ResultCardData } from '../a2ui/cards.js';
+import { actionCta, type CardAction } from '../harness/cta.js';
 import { emitToolForm } from '../a2ui/form.js';
 import { A2UI_THEME_CSS } from '../a2ui/theme.js';
 // Compiled from agent.tw.css at build time (scripts/css-to-ts.mjs). It is a
@@ -43,8 +44,10 @@ import { connectTools } from '../harness/tools/source.js';
 import {
   chooserOf,
   formOptions,
+  formsFor,
   handoffFor,
   isSiteTool,
+  siteFormFor,
   withoutSiteSuffix,
   HANDOFF_RESULT,
 } from '../harness/tools/action-tools.js';
@@ -59,7 +62,11 @@ import {
   type ActionItem,
   type ActionStep,
 } from './action-card.js';
+import { resultsAnswer, RESULTS_ANSWER_CSS, type AnswerCard } from './result-pick.js';
+import { extractRecords, openStatus, recordFacts } from '../harness/records.js';
+import type { ResultPick } from '../harness/recommend.js';
 import { resumePendingAction } from '../harness/tools/resume.js';
+import { findHandoffForm, startFormMessage, startMessage, takeInboundHandoff } from '../harness/tools/inbound.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';
@@ -329,6 +336,16 @@ interface ResultCard {
   id?: string;
   /** The page on this site the record came from, when it can be told. */
   page?: { url: string; label: string };
+  /** The rating and how many reviews it rests on. */
+  stars?: number;
+  reviews?: number;
+  /** Open or closed when the search ran: "Open now · 24/7", "Opens 7am". */
+  status?: { open: boolean; label: string };
+  phone?: string;
+  /** What the record states, short, for comparing it. */
+  facts?: string[];
+  /** The action the record itself offers (its potentialAction), as a button. */
+  action?: CardAction;
 }
 
 type ThreadItem =
@@ -337,7 +354,7 @@ type ThreadItem =
   | { kind: 'trace'; name: string; args: Record<string, unknown>; text: string; isError: boolean; count?: number }
   | { kind: 'route'; agent: string; via: string }
   | { kind: 'detail'; title: string; note: string; rows: DetailRow[] }
-  | { kind: 'results'; title: string; note: string; cards: ResultCard[] }
+  | { kind: 'results'; title: string; note: string; cards: ResultCard[]; pick?: ResultPick }
   | { kind: 'metrics'; rounds: MetricsRound[] }
   | { kind: 'form' }
   /** A turn the person called off. Kept so the thread explains its own gap. */
@@ -670,6 +687,8 @@ class NxisAgentFullscreen extends HTMLElement {
     // belongs to is the one open.
     void this._resumePendingAction();
     this._resumePendingVisit();
+    // Sent here from the NxisAI app to use one of this page's forms.
+    void this._arriveFromHandoff();
 
     this._els.launcher.addEventListener('click', () => this._open());
     this._els.handoffBack.addEventListener('click', () => void this._endHandoff());
@@ -1577,7 +1596,14 @@ class NxisAgentFullscreen extends HTMLElement {
   }
 
   // ── Turn loop ──────────────────────────────────────────────────────────────
-  private async _onSend(): Promise<void> {
+  /**
+   * Send what is in the composer.
+   *
+   * @param call - A tool call already decided, run without asking the model
+   *   (a handoff names its form). Falls back to an ordinary turn when no agent
+   *   here holds the tool.
+   */
+  private async _onSend(call?: { name: string; args: Record<string, unknown> }): Promise<void> {
     const goal = this._els.input.value.trim();
     if (!goal || this._turnActive) return;
     this._els.input.value = '';
@@ -1614,7 +1640,9 @@ class NxisAgentFullscreen extends HTMLElement {
       await this._connectTools();
       this._syncProfileContext();
       // One agent, or several with a router in front: the signatures match.
-      await (this._coordinator ?? this._harness).turn(goal, conv!.messages);
+      const engine = this._coordinator ?? this._harness;
+      const begun = call ? await engine.begin(goal, call.name, call.args, conv!.messages) : null;
+      if (!begun || begun.decision === 'unavailable') await engine.turn(goal, conv!.messages);
       // A remote endpoint reports which model answered; the name beside the
       // input follows it rather than keeping whatever was configured.
       this._paintProvenance();
@@ -1646,9 +1674,9 @@ class NxisAgentFullscreen extends HTMLElement {
       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) => {
+      results: (tool, res, extra) => {
         const conv = this._active();
-        const item = this._buildResultsItem(tool, res);
+        const item = this._buildResultsItem(tool, res, extra?.pick);
         // 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.
@@ -2582,61 +2610,9 @@ class NxisAgentFullscreen extends HTMLElement {
    * return the first that yields records. Shapes covered: query → results[],
    * list_types → types[], get → result{}, or a bare entity/array. */
   private _extractItems(res: ModelContextToolResponse | string | null): Record<string, unknown>[] {
-    const sources: unknown[] = [];
-    // Collect every candidate payload, recursively unwrapping tool-response
-    // envelopes. `res` can be an object, a JSON string, or (with a WebMCP browser
-    // extension in the loop) the whole `{content, structuredContent}` envelope
-    // serialized to a string, possibly more than once. Diving into both
-    // `structuredContent` and each `content[].text` covers all of them.
-    const visit = (raw: unknown, depth = 0): void => {
-      if (raw == null || depth > 5) return;
-      const val: unknown = raw;
-      if (typeof val === 'string') {
-        const t = val.trim();
-        if (!t) return;
-        let parsed: unknown;
-        try {
-          parsed = JSON.parse(t);
-        } catch {
-          return; // plain (non-JSON) text — nothing to extract
-        }
-        // Parsed value may itself be an object/array OR another JSON string
-        // (double-encoded); recurse either way.
-        return visit(parsed, depth + 1);
-      }
-      if (!val || typeof val !== 'object') return;
-      sources.push(val);
-      const v = val as Record<string, unknown>;
-      if (v.structuredContent != null) visit(v.structuredContent, depth + 1);
-      if (Array.isArray(v.content)) {
-        for (const c of v.content) {
-          if (c && typeof c === 'object') visit((c as Record<string, unknown>).text, depth + 1);
-        }
-      }
-    };
-    visit(res);
-
-    for (const data of sources) {
-      const items = this._itemsFrom(data);
-      if (items.length) return items;
-    }
-    console.warn('[nxis-mcp] no items extracted from tool result', { sourcesTried: sources.length, res });
-    return [];
-  }
-
-  /** Find the record array within one parsed payload. */
-  private _itemsFrom(data: unknown): Record<string, unknown>[] {
-    const objs = (arr: unknown[]) =>
-      arr.filter((x) => x && typeof x === 'object') as Record<string, unknown>[];
-    if (Array.isArray(data)) return objs(data);
-    if (!data || typeof data !== 'object') return [];
-    const d = data as Record<string, unknown>;
-    for (const key of ['results', 'types', 'items', 'entities', 'data']) {
-      if (Array.isArray(d[key])) return objs(d[key] as unknown[]);
-    }
-    if (d.result && typeof d.result === 'object') return [d.result as Record<string, unknown>];
-    if (d['@id'] != null || d['@type'] != null || d.name != null) return [d];
-    return [];
+    const items = extractRecords(res);
+    if (!items.length) console.warn('[nxis-mcp] no items extracted from tool result', { res });
+    return items;
   }
 
   /** Build a display card from a single record (a JSON-LD entity or a type row). */
@@ -2704,19 +2680,88 @@ class NxisAgentFullscreen extends HTMLElement {
     const id = entity['@id'] != null ? str(entity['@id']) : undefined;
     const found = pageForEntity(entity, this._sitePages, location.origin);
     const page = found ? { url: found.url, label: found.name } : undefined;
-    return { title, type, rating, emergency, sub, rows, id, ...(page ? { page } : {}) };
+
+    // What the answer view compares by, beyond the rating and hours its heading already shows.
+    const facts = recordFacts(entity);
+    const status = openStatus(entity) ?? undefined;
+    const lines = [
+      facts.services.length ? facts.services.slice(0, 3).map((x) => x.name).join(', ') : facts.knows.slice(0, 3).join(', '),
+      facts.since ? `In business since ${facts.since}` : '',
+      facts.reviews[0] ? `\u201c${facts.reviews[0].text}\u201d${facts.reviews[0].author ? ` \u2014 ${facts.reviews[0].author}` : ''}` : '',
+    ].filter((l): l is string => !!l);
+    const action = actionCta(entity, title);
+    return {
+      title,
+      type,
+      rating,
+      emergency,
+      sub,
+      rows,
+      id,
+      ...(page ? { page } : {}),
+      ...(facts.rating !== undefined ? { stars: facts.rating } : {}),
+      ...(facts.reviewCount !== undefined ? { reviews: facts.reviewCount } : {}),
+      ...(status ? { status: { open: status.open, label: status.label } } : {}),
+      ...(facts.phone ? { phone: facts.phone } : {}),
+      ...(action ? { action } : {}),
+      facts: lines,
+    };
   }
 
   private _buildResultsItem(
     tool: ModelContextToolInfo,
     res: ModelContextToolResponse,
+    pick?: ResultPick,
   ): Extract<ThreadItem, { kind: 'results' }> {
     const items = this._extractItems(res);
     const cards = items.slice(0, 12).map((e) => this._entityCard(e));
     const note = !cards.length
       ? 'No results found.'
       : `${cards.length} result${cards.length === 1 ? '' : 's'}`;
-    return { kind: 'results', title: humanize(tool.name), note, cards };
+    return { kind: 'results', title: humanize(tool.name), note, cards, ...(pick && pick.index < cards.length ? { pick } : {}) };
+  }
+
+  /**
+   * Results as an answer: the recommended pick with its reasons and the others
+   * to compare, or a short list that opens per result. Records of things
+   * only: a listing of types or counts keeps the plain cards.
+   */
+  private _answerEl(item: Extract<ThreadItem, { kind: 'results' }>): HTMLElement | null {
+    // Records of things: a pick, or at least one result with a rating, hours, a phone or a page.
+    // A sparse record beside them (an index entry with only a name) still shows, by name.
+    const things = item.cards.filter((c) => c.stars !== undefined || c.status || c.phone || c.page);
+    if (!item.pick && !things.length) return null;
+    const cards: AnswerCard[] = item.cards.map((c) => {
+      // The record's own action first: the same map and prompt as the Typed Retrieval skill and the NxisAI
+      // app. A record that states none falls back to a form found on this page for it.
+      const form = c.action ? undefined : formsFor(c.title)[0];
+      const quote = form && /quote/.test(form.noun);
+      return {
+        title: c.title,
+        stars: c.stars,
+        reviews: c.reviews,
+        status: c.status,
+        phone: c.phone,
+        page: c.page,
+        facts: c.facts ?? [],
+        ...(c.action
+          ? { form: { label: c.action.label, message: c.action.message } }
+          : form
+          ? {
+              form: quote
+                ? { label: 'Get a quote', message: `Get a quote from ${c.title}` }
+                : { label: `Use their ${form.noun}`, message: `Start the ${form.noun} for ${c.title}` },
+            }
+          : {}),
+      };
+    });
+    return resultsAnswer(cards, item.pick, {
+      ask: (text) => {
+        if (this._turnActive) return;
+        this._els.input.value = text;
+        void this._onSend();
+      },
+    });
   }
 
   /** Feature-card pattern: tinted icon chip, tags, tight Manrope headline, one
@@ -2739,6 +2784,7 @@ class NxisAgentFullscreen extends HTMLElement {
         ...(c.emergency ? [{ label: '24/7' }] : []),
       ],
       rows: c.rows.map((r) => ({ label: r.label, value: r.value })),
+      actions: c.action ? [c.action] : [],
     }));
   }
 
@@ -2752,7 +2798,15 @@ class NxisAgentFullscreen extends HTMLElement {
     }
     try {
       const messages = emitCardsSurface(item.note, this._toA2uiCards(item.cards));
-      const mounted = mountSurface(wrap, messages);
+      const mounted = mountSurface(wrap, messages, (event: any) => {
+        const name = event?.event?.name ?? event?.name ?? '';
+        const ctx = (event?.event?.context ?? event?.context ?? {}) as Record<string, unknown>;
+        // A card's action button: send its message as the visitor, as the inline card does.
+        if (name === 'nxis.ask' && typeof ctx.message === 'string' && !this._turnActive) {
+          this._els.input.value = ctx.message;
+          void this._onSend();
+        }
+      });
       if (!mounted) throw new Error('no surface produced');
       this._surfaces.push(mounted);
     } catch (err) {
@@ -2777,9 +2831,12 @@ class NxisAgentFullscreen extends HTMLElement {
    * surface; a2ui="a2ui-results" opts this element back into it for comparison.
    */
   private _resultsEl(item: Extract<ThreadItem, { kind: 'results' }>): HTMLElement {
-    return this.getAttribute('a2ui') === 'a2ui-results'
-      ? this._resultsElA2ui(item)
-      : this._resultsElLegacy(item);
+    if (this.getAttribute('a2ui') === 'a2ui-results') return this._resultsElA2ui(item);
+    if (!this._classicPrompts && item.cards.length) {
+      const answer = this._answerEl(item);
+      if (answer) return answer;
+    }
+    return this._resultsElLegacy(item);
   }
 
   private _resultsElLegacy(item: Extract<ThreadItem, { kind: 'results' }>): HTMLElement {
@@ -3477,6 +3534,42 @@ class NxisAgentFullscreen extends HTMLElement {
     if (this.mode !== 'fullscreen') this._open();
   }
 
+  /**
+   * Open on the form a link from the NxisAI app names.
+   *
+   * In a new conversation: the person arrives from another app, and nothing
+   * on this site led here. The agent starts the form in its own words, so the
+   * link only chooses which form; what the person wanted waits in the
+   * composer for them to send, change or delete.
+   */
+  private async _arriveFromHandoff(): Promise<void> {
+    const handoff = takeInboundHandoff();
+    if (!handoff) return;
+    this._newConversation();
+    this._open();
+    this._setStatus('Opening the form…');
+    // The site's own tools first: they reach a form from any page, from the
+    // site's records, so they work where the page registers nothing itself.
+    await this._connectTools();
+    const site = siteFormFor(handoff.actionId);
+    const start = site
+      ? startFormMessage(site.noun, site.choice)
+      : await findHandoffForm(handoff).then((o) => (o.status === 'ready' ? startMessage(o.tool) : null));
+    this._setStatus('');
+    if (!start) {
+      this._appendMsg('assistant', "I couldn't find that form on this page. Tell me what you need and I'll help from here.");
+    } else if (!this._turnActive) {
+      this._els.input.value = start;
+      // The form is known, so it opens without the model choosing it: left to
+      // choose, a model sometimes asks for the details in prose instead.
+      await this._onSend(site ? { name: site.tool, args: site.args } : undefined);
+    }
+    if (handoff.intent && !this._els.input.value) {
+      this._els.input.value = handoff.intent;
+      this._autosize();
+    }
+  }
+
   private async _resumePendingAction(): Promise<void> {
     const outcome = await resumePendingAction({
       onStart: (pending) => {
@@ -4099,6 +4192,9 @@ class NxisAgentFullscreen extends HTMLElement {
       /* The action card: forms and handoffs as one message. */
       ${ACTION_CARD_CSS}
 
+      /* Search results as an answer: a pick and why, or a short list. */
+      ${RESULTS_ANSWER_CSS}
+
       /* App-icon tile: chevron centered in a 56px tile, Soft Gray, hairline. */
       .launcher {
         position: fixed; right: 20px; bottom: 20px; z-index: 9998;