@nxisai/agent-harness 0.8.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nxisai/agent-harness",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "An on-device agent for the browser: a tool-calling harness over WebMCP and remote MCP, plus a drop-in chat UI. Decides whether to run a tool, ask for what's missing, or confirm before writing.",
   "type": "module",
   "main": "./dist/index.js",

package/src/a2ui/cards.ts

@@ -12,6 +12,7 @@
  */
 
 import type { A2uiMessage } from './emit.js';
+import { actionCta, type CardAction } from '../harness/cta.js';
 
 const CATALOG = 'https://a2ui.org/specification/v1_0/catalogs/basic/catalog.json';
 
@@ -27,6 +28,8 @@ export interface ResultCardData {
   sub: string;
   tags: CardTag[];
   rows: CardRow[];
+  /** The record's own action, as at most one button. A list so a card without one draws nothing. */
+  actions: CardAction[];
 }
 
 const str = (v: unknown): string => (v == null ? '' : String(Array.isArray(v) ? v[0] : v));
@@ -93,7 +96,8 @@ export function toCardData(entity: Record<string, unknown>): ResultCardData {
     }
   }
 
-  return { title, sub, tags, rows };
+  const action = actionCta(entity, title);
+  return { title, sub, tags, rows, actions: action ? [action] : [] };
 }
 
 /** Fixed component set — independent of how many results there are. */
@@ -106,7 +110,7 @@ function cardComponents(heading: string): Component[] {
     { id: 'results', component: 'List',
       children: { path: '/results', componentId: 'card_tpl' }, direction: 'vertical' },
     { id: 'card_tpl', component: 'Card', child: 'card_body' },
-    { id: 'card_body', component: 'Column', children: ['card_title', 'card_tags', 'card_sub', 'card_rows'] },
+    { id: 'card_body', component: 'Column', children: ['card_title', 'card_tags', 'card_sub', 'card_rows', 'card_actions'] },
     // No bold: `weight` in this catalog is a flex weight (number), and Text
     // offers only variant caption/body. Title emphasis is not expressible in
     // the basic catalog: it needs a custom catalog or renderer styling.
@@ -124,6 +128,14 @@ function cardComponents(heading: string): Component[] {
     { id: 'row_tpl', component: 'Row', children: ['row_label', 'row_value'] },
     { id: 'row_label', component: 'Text', text: '${label}', variant: 'caption' },
     { id: 'row_value', component: 'Text', text: '${value}', variant: 'caption' },
+
+    // The record's action: zero or one per card, so a card without one draws nothing. Pressing it
+    // dispatches nxis.ask with the message to send as the visitor; it never submits anything itself.
+    { id: 'card_actions', component: 'List',
+      children: { path: 'actions', componentId: 'action_tpl' }, direction: 'horizontal' },
+    { id: 'action_tpl', component: 'Button', child: 'action_label', variant: 'primary',
+      action: { event: { name: 'nxis.ask', context: { message: '${message}' } } } },
+    { id: 'action_label', component: 'Text', text: '${label}', variant: 'body' },
   ];
 }
 

package/src/harness/cta.ts

@@ -0,0 +1,54 @@
+/**
+ * The action a result card offers, chosen from the record's own `potentialAction`.
+ *
+ * One map, shared with the Typed Retrieval skill (nxis-skills) and the NxisAI app's widgets (nxis-mcp
+ * `HubWidgets`): the action's `@type` alone decides the button, and the button sends the same prompt
+ * everywhere ("Get a quote from Hatzel & Sons Plumbing"), so the funnel cannot tell which surface it came
+ * from. Commerce, read and search actions get no button here.
+ *
+ * On the site's own page every mapped action sends the prompt, a self-page form included: the on-page agent
+ * is what runs that form. Only the NxisAI app, which cannot reach the page, opens it instead.
+ *
+ * @module
+ */
+
+/** What a card's action button says and sends. */
+export interface CardAction {
+  label: string;
+  /** The message sent as the visitor when the button is pressed. */
+  message: string;
+}
+
+const MAP: Record<string, { label: string; message: (name: string) => string }> = {
+  QuoteAction: { label: 'Get a quote', message: (n) => `Get a quote from ${n}` },
+  AskAction: { label: 'Contact', message: (n) => `Contact ${n}` },
+  ReserveAction: { label: 'Reserve', message: (n) => `Reserve at ${n}` },
+  ScheduleAction: { label: 'Book an appointment', message: (n) => `Book an appointment at ${n}` },
+  ApplyAction: { label: 'Apply', message: (n) => `Apply to ${n}` },
+};
+
+/** When a record carries several, the first of these wins. */
+const ORDER = Object.keys(MAP);
+
+const shortType = (t: unknown): string =>
+  typeof t === 'string' ? t.replace(/^https?:\/\/schema\.org\//, '') : '';
+
+const list = (v: unknown): unknown[] => (v == null ? [] : Array.isArray(v) ? v : [v]);
+
+/**
+ * The button for a record, or none.
+ *
+ * @param record - The record as a tool returned it; action `@type`s may be full IRIs.
+ * @param name - What to call it in the message; the record's own name by default.
+ */
+export function actionCta(record: Record<string, unknown>, name?: string): CardAction | undefined {
+  const types = list(record.potentialAction)
+    .filter((a): a is Record<string, unknown> => !!a && typeof a === 'object')
+    .flatMap((a) => list(a['@type']).map(shortType))
+    .filter((t) => t in MAP)
+    .sort((a, b) => ORDER.indexOf(a) - ORDER.indexOf(b));
+  if (!types.length) return undefined;
+  const who = (name ?? (typeof record.name === 'string' ? record.name : '')).trim() || 'them';
+  const entry = MAP[types[0]];
+  return { label: entry.label, message: entry.message(who) };
+}

package/src/harness/harness.ts

@@ -575,6 +575,48 @@ export class AgentHarness {
     return this.act(tool, call.args, messages);
   }
 
+  /**
+   * Run a turn whose tool call is already decided, without asking the model.
+   *
+   * For a request that names its own action, such as a link from the NxisAI
+   * app to one business's quote form: the tool and the business are known, so
+   * the model has nothing to choose, and a model left to choose sometimes
+   * asks for the details in prose instead of opening the form. What follows
+   * the call is an ordinary turn's: the same slots, prompts and confirmation,
+   * and the call goes into the transcript as if the model had made it.
+   *
+   * @param goal - The request as the person would have said it, for the thread and transcript.
+   * @param name - The tool to call.
+   * @param args - Its arguments, e.g. which business.
+   * @param messages - The live conversation, appended to in place.
+   * @returns The decision taken, or `'unavailable'` when this agent has no such tool.
+   */
+  async begin(goal: string, name: string, args: Record<string, unknown>, messages: ChatMessage[]): Promise<TurnResult> {
+    this.abort?.abort();
+    this.abort = new AbortController();
+    this.goal = goal;
+    this.renderer.stoppable?.(true);
+    this.applySystemPrompt(messages);
+    beginJourney();
+
+    const bubble = this.renderer.streaming();
+    bubble.thinking('Finding tools…');
+    const tools = this.visibleTools(await this.toolSource.discoverTools(this.abort.signal), goal);
+    if (this.stopped) return this.stopTurn(bubble, messages, goal);
+    const tool = tools.find((t) => t.name === name);
+    if (!tool) {
+      bubble.finalize('');
+      return this.finished({ decision: 'unavailable' as const });
+    }
+
+    const call = { name, args };
+    messages.push({ role: 'user', content: goal });
+    bubble.finalize(narrateCall(call, tools));
+    messages.push({ role: 'assistant', content: this.transcribe({ text: '', call } as Completion) });
+    this.opts.onMessages?.(messages);
+    return this.act(tool, args, messages);
+  }
+
   /**
    * Narrow the page's tools to this agent's slice.
    *

package/src/harness/router/coordinator.ts

@@ -188,6 +188,20 @@ export class AgentCoordinator {
     return this.working.turn(goal, messages);
   }
 
+  /**
+   * Run a turn whose tool call is already decided, on the agent that holds the tool.
+   *
+   * @see AgentHarness.begin
+   */
+  async begin(goal: string, name: string, args: Record<string, unknown>, messages: ChatMessage[]): Promise<TurnResult> {
+    const owner = this.ownerOf(name, '');
+    if (!owner) return { decision: 'unavailable' };
+    this.opts.onRoute?.({ ...this.route(goal, messages), agent: owner, via: 'handback', fellBack: false });
+    this.sticky.set(messages, owner);
+    this.working = this.opts.agents[owner];
+    return this.working.begin(goal, name, args, messages);
+  }
+
   /** The agent holding a tool, ignoring the one that handed the turn back. */
   private ownerOf(tool: string, except: string): string | null {
     for (const [name, agent] of Object.entries(this.opts.agents)) {

package/src/harness/tools/action-tools.ts

@@ -538,6 +538,29 @@ export function formsFor(name: string): { tool: string; noun: string }[] {
   return out;
 }
 
+/**
+ * The site form that runs an action, by the action's `@id`: the site-wide tool
+ * built on this page that covers it, and which business it is for.
+ *
+ * @returns The tool's name, what the form is called ("quote form"), the
+ * choice that picks this action when the tool covers several, and the
+ * arguments that make a call to it this action; null when no site tool built
+ * here covers it.
+ */
+export function siteFormFor(
+  actionId: string,
+): { tool: string; noun: string; choice?: string; args: Record<string, unknown> } | null {
+  for (const [toolName, t] of built) {
+    const index = t.actions.findIndex((a) => a['@id'] === actionId);
+    if (index < 0) continue;
+    const noun = withoutSiteSuffix(toolName).replace(/[_-]+/g, ' ').trim().toLowerCase();
+    const choice = t.choices?.[index];
+    const args = choice && t.discriminator ? { [t.discriminator]: choice } : {};
+    return choice ? { tool: toolName, noun, choice, args } : { tool: toolName, noun, args };
+  }
+  return null;
+}
+
 /** An option that only asks to choose: "Select…", "Choose a service…". */
 export const isPlaceholder = (value: string): boolean => /^\s*(select|choose|pick)\b/i.test(value) || /…\s*$|\.\.\.\s*$/.test(value);
 

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/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';
@@ -134,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,

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
@@ -46,6 +47,7 @@ import {
   formsFor,
   handoffFor,
   isSiteTool,
+  siteFormFor,
   withoutSiteSuffix,
   HANDOFF_RESULT,
 } from '../harness/tools/action-tools.js';
@@ -64,6 +66,7 @@ import { resultsAnswer, RESULTS_ANSWER_CSS, type AnswerCard } from './result-pic
 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';
@@ -341,6 +344,8 @@ interface ResultCard {
   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 =
@@ -682,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());
@@ -1589,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 = '';
@@ -1626,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();
@@ -2673,6 +2689,7 @@ class NxisAgentFullscreen extends HTMLElement {
       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,
@@ -2686,6 +2703,7 @@ class NxisAgentFullscreen extends HTMLElement {
       ...(facts.reviewCount !== undefined ? { reviews: facts.reviewCount } : {}),
       ...(status ? { status: { open: status.open, label: status.label } } : {}),
       ...(facts.phone ? { phone: facts.phone } : {}),
+      ...(action ? { action } : {}),
       facts: lines,
     };
   }
@@ -2714,7 +2732,9 @@ class NxisAgentFullscreen extends HTMLElement {
     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) => {
-      const form = formsFor(c.title)[0];
+      // 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,
@@ -2724,7 +2744,9 @@ class NxisAgentFullscreen extends HTMLElement {
         phone: c.phone,
         page: c.page,
         facts: c.facts ?? [],
-        ...(form
+        ...(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}` }
@@ -2762,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] : [],
     }));
   }
 
@@ -2775,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) {
@@ -3503,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) => {