@nxisai/agent-harness 0.8.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nxisai/agent-harness",
-  "version": "0.8.0",
+  "version": "0.10.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

@@ -25,6 +25,7 @@ import { samePage, sameActionPage } from './site-actions.js';
 import { savePendingAction } from './pending-action.js';
 import { journeySteps } from '../steps.js';
 import { executeRegistered } from './webmcp.js';
+import { ACTION_ID_HINT, type PageFormRun, type SiteActionReport } from './report.js';
 import type { JsonSchema, ModelContext, ModelContextTool, ModelContextToolInfo, ModelContextToolResponse } from '../../types.js';
 import type { NxisAction, NxisPropertyValueSpecification, NxisValueType } from '../../webmcp-contract.js';
 
@@ -47,8 +48,7 @@ export const HANDOFF_RESULT = 'ai.nxis/handoff';
 export const CHOOSER_HINT = 'ai.nxis/chooser';
 /** That field's values, one per covered action, in the same order. */
 export const CHOICES_HINT = 'ai.nxis/choices';
-/** The `@id` of the action a page tool came from, where the page records it. */
-export const ACTION_ID_HINT = 'ai.nxis/actionId';
+export { ACTION_ID_HINT };
 
 /** Appended to the action's own name, keeping it clear of the page's tool. */
 const NAME_SUFFIX = '_anywhere';
@@ -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);
 
@@ -956,3 +979,29 @@ export function withoutShadowedTools(
     return !coveredNames.has(tool.name);
   });
 }
+
+/**
+ * The report a page form's run makes, or none when it was no action of the
+ * site's. Matched the way {@link findPageTool} finds the form: by `@id` where
+ * the registry kept it, else by name, and then only on the action's own page —
+ * elsewhere a tool of the same name belongs to a different form.
+ *
+ * @param actions - The site's actions.
+ * @param run - The page tool that went through.
+ * @param href - The current page. Defaults to the browser's.
+ */
+export function reportFor(actions: NxisAction[], run: PageFormRun, href?: string): SiteActionReport | null {
+  const action = run.actionId
+    ? actions.find((a) => a['@id'] === run.actionId)
+    : actions.find((a) => sanitizeToolName(a.name) === run.toolName && sameActionPage(a, href));
+  const actionId = action?.['@id'] ?? run.actionId;
+  if (!actionId) return null;
+  const type = shortActionType(action?.['@type']);
+  return { outcome: 'submitted', action_id: actionId, ...(type ? { action_type: type } : {}), source: 'on_page_agent' };
+}
+
+/** `QuoteAction`, however the record spelled it. */
+function shortActionType(type: string | undefined): string | undefined {
+  const name = typeof type === 'string' ? type.split(/[/:#]/).pop() : undefined;
+  return name && /^[A-Z][A-Za-z]*Action$/.test(name) ? name : undefined;
+}

package/src/harness/tools/bridge.ts

@@ -14,6 +14,7 @@
  */
 import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { isRateLimited, retryAfterMs, withRetry } from './retry.js';
+import { TRACK_TOOL } from './report.js';
 import type {
   JsonSchema,
   McpServerInfo,
@@ -294,7 +295,7 @@ async function registeredNames(mc: ModelContext): Promise<Set<string>> {
  *
  * Override with {@link BridgeOptions.accept}.
  */
-const SERVER_ONLY_TOOLS = new Set(['nxis_action']);
+const SERVER_ONLY_TOOLS = new Set(['nxis_action', TRACK_TOOL]);
 
 /** Options for {@link registerRemoteTools}. */
 export interface BridgeOptions {

package/src/harness/tools/inbound.ts

@@ -0,0 +1,204 @@
+/**
+ * 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. None of the parameters carries
+ * anything personal, and all are taken out of the address bar once read.
+ *
+ * `&nxis_report=<token>` is the site's own signature on the answer the link came
+ * from. It is held for the form, and sent back with the report that the form
+ * went through, so the site counts the conversion as verified.
+ *
+ * @module
+ */
+import { awaitPageTool, withoutSiteSuffix } from './action-tools.js';
+import { rememberReportToken } from './report.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';
+/** The site's report token for the action, from the answer the link came from. Optional. */
+export const REPORT_PARAM = 'nxis_report';
+
+/** Longer than any `@id` the crawler writes; a longer value is not one. */
+const MAX_ID = 512;
+/** Longer than any token a site signs; a longer value is not one. */
+const MAX_TOKEN = 1024;
+/** 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 site's report token for the action; absent when the link had none. */
+  reportToken?: 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) ?? '');
+  const token = (url.searchParams.get(REPORT_PARAM) ?? '').trim();
+  const reportToken = token && token.length <= MAX_TOKEN && /^[A-Za-z0-9_.-]+$/.test(token) ? token : '';
+  return { actionId, ...(intent ? { intent } : {}), ...(reportToken ? { reportToken } : {}) };
+}
+
+/** 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, REPORT_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));
+  // Held for the form this opens, wherever it is sent from; see report.ts.
+  if (handoff.reportToken) rememberReportToken(handoff.actionId, handoff.reportToken);
+  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/report.ts

@@ -0,0 +1,119 @@
+/**
+ * Tells the site's MCP server that a form the agent filled went through.
+ *
+ * A page's own form submits to the site, not to NxisAI, so the server never
+ * sees it happen. Agent Analytics counts these reports as conversions
+ * (`nxis_track_site_action`, outcome `submitted`), next to the actions the
+ * server runs itself.
+ *
+ * A report names the action and nothing else: never a value the visitor typed.
+ * It is best effort — a site whose server cannot take it, or a report that
+ * fails, never changes what the visitor sees.
+ *
+ * @module
+ */
+import type { ModelContextToolInfo, ModelContextToolResponse } from '../../types.js';
+
+/** The server tool a report goes to. Kept from the model: it reports what happened, it is not something to do. */
+export const TRACK_TOOL = 'nxis_track_site_action';
+
+/** The `@id` of the action a page tool came from, where the page records it. */
+export const ACTION_ID_HINT = 'ai.nxis/actionId';
+
+/** What a report says. Closed fields only, so nothing the visitor typed can ride along. */
+export interface SiteActionReport {
+  outcome: 'submitted';
+  action_id: string;
+  action_type?: string;
+  source: 'on_page_agent';
+  /** The site's signature on the answer that led here, when the visitor came by a handoff link. */
+  report_token?: string;
+}
+
+/**
+ * A page tool that ran and went through. The action's `@id` when the registry
+ * kept it: a spec registry keeps only the four standard hints, so on native
+ * Chrome the tool's name, on its own page, is all there is to go on.
+ */
+export interface PageFormRun {
+  actionId?: string;
+  toolName: string;
+}
+
+/** Turns a run into a report and sends it, or ignores a run that was no action of the site's. */
+export type SiteActionReporter = (run: PageFormRun) => Promise<unknown> | unknown;
+
+let reporter: SiteActionReporter | null = null;
+
+/**
+ * Where reports go: the site's server, once it is connected. `null` stops
+ * reporting, which is the state until a server is found.
+ */
+export function setSiteActionReporter(next: SiteActionReporter | null): void {
+  reporter = next;
+}
+
+/**
+ * Report a page tool's run if it went through. Whether it was one of the
+ * site's actions is the reporter's to decide; a form that refused the input,
+ * or failed, is never reported.
+ */
+export function reportSubmitted(
+  tool: ModelContextToolInfo | null,
+  name: string,
+  res: ModelContextToolResponse | null,
+): void {
+  if (!reporter || !res || res.isError) return;
+  const hint = tool?.annotations?.[ACTION_ID_HINT];
+  const run: PageFormRun = { toolName: tool?.name || name, ...(typeof hint === 'string' && hint ? { actionId: hint } : {}) };
+  const send = reporter;
+  try {
+    void Promise.resolve(send(run)).catch(() => {});
+  } catch {
+    // The visitor's submission stands whether or not it was counted.
+  }
+}
+
+/** Where held report tokens live: the tab's session, so a form finished on another page still has its token. */
+const TOKENS_KEY = 'nxis:report-tokens';
+
+function sessionStore(): Storage | null {
+  try {
+    return typeof sessionStorage === 'undefined' ? null : sessionStorage;
+  } catch {
+    return null;
+  }
+}
+
+function readTokens(storage: Storage | null): Record<string, string> {
+  try {
+    const parsed = JSON.parse(storage?.getItem(TOKENS_KEY) ?? '{}') as unknown;
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? (parsed as Record<string, string>) : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeTokens(storage: Storage | null, tokens: Record<string, string>): void {
+  try {
+    if (Object.keys(tokens).length) storage?.setItem(TOKENS_KEY, JSON.stringify(tokens));
+    else storage?.removeItem(TOKENS_KEY);
+  } catch {
+    // Unverified is still counted; a token that cannot be held is only lost proof.
+  }
+}
+
+/** Hold the token a handoff link brought for an action, until its form is sent. */
+export function rememberReportToken(actionId: string, token: string, storage: Storage | null = sessionStore()): void {
+  writeTokens(storage, { ...readTokens(storage), [actionId]: token });
+}
+
+/** Take the token held for an action, if any: it goes with one report and is then let go. */
+export function takeReportToken(actionId: string, storage: Storage | null = sessionStore()): string | undefined {
+  const tokens = readTokens(storage);
+  const token = tokens[actionId];
+  if (token === undefined) return undefined;
+  delete tokens[actionId];
+  writeTokens(storage, tokens);
+  return typeof token === 'string' && token ? token : undefined;
+}

package/src/harness/tools/source.ts

@@ -18,7 +18,8 @@ import { ensureModelContext } from './local-context.js';
 import { connectMcp } from './client.js';
 import { discoverMcpServer } from './discovery.js';
 import { findEmbeddedAction, loadSiteActions, type SiteActionsOptions } from './site-actions.js';
-import { registerSiteActionTools } from './action-tools.js';
+import { registerSiteActionTools, reportFor } from './action-tools.js';
+import { setSiteActionReporter, takeReportToken, TRACK_TOOL } from './report.js';
 import { loadSitePages, mergePages, pagesFromActions, type SitePage } from './site-pages.js';
 import { registerOpenPageTool, OPEN_PAGE_TOOL, type OpenPageOptions } from './open-page.js';
 import {
@@ -227,10 +228,26 @@ async function connectRegistry(
     console.warn(`[nxis-mcp] ${warning}`);
   }
 
+  reportTo(client, siteActions);
+
   const site = await connectPages(mc, client, info, siteActions, siteOpts, opts.openPage);
   return { modelContext: mc, remoteTools, siteActions, siteTools, sitePages: site.pages, siteNav: site.nav, warning };
 }
 
+/**
+ * Count the site's forms the agent sends in its Agent Analytics, through its
+ * own server.
+ */
+function reportTo(client: Client, actions: NxisAction[]): void {
+  setSiteActionReporter((run) => {
+    const report = reportFor(actions, run);
+    if (!report) return undefined;
+    // A visitor handed here from the NxisAI app brings the site's token for the action: the report counts as verified.
+    const token = takeReportToken(report.action_id);
+    return client.callTool({ name: TRACK_TOOL, arguments: { ...report, ...(token ? { report_token: token } : {}) } });
+  });
+}
+
 /**
  * The site's pages, and the tool that opens them.
  *

package/src/harness/tools/webmcp.ts

@@ -7,6 +7,7 @@
  * @module
  */
 import { TOOLS_TIMEOUT_MS } from '../../engine.js';
+import { reportSubmitted } from './report.js';
 import type {
   ModelContext,
   ModelContextToolInfo,
@@ -159,7 +160,10 @@ export async function executeRegistered(
   let refused: unknown;
   for (const attempt of attempts) {
     try {
-      return asResponse(await attempt());
+      const res = asResponse(await attempt());
+      // Every page form runs through here, whichever way it was reached: the one place to count it.
+      reportSubmitted(toolObj, name, res);
+      return res;
     } catch (err) {
       if (!REFUSED_SHAPE.test(String((err as Error)?.message || err))) throw err;
       refused = err;