@nxisai/agent-harness 0.4.1 → 0.6.0

package/src/harness/tools/open-page.ts

@@ -0,0 +1,273 @@
+/**
+ * A tool for taking the visitor to a page on the site.
+ *
+ * "Take me to that page" is a request the agent should be able to carry out.
+ * Without a tool for it a model reaches for whatever it has — a lookup — and
+ * nothing moves. This one opens a page by name, from the pages the site
+ * reported — or home, or back to the page before — and carries the conversation
+ * across so it continues there.
+ *
+ * It reads nothing and submits nothing, so it runs without a confirmation, and
+ * it never leaves the origin.
+ *
+ * @module
+ */
+import { samePage } from './site-actions.js';
+import { findPage, type SitePage } from './site-pages.js';
+import { nameOf, navFor, parentOf, type NavLink, type SiteNav } from './site-nav.js';
+import { savePendingVisit } from './pending-action.js';
+import { HANDOFF_RESULT } from './action-tools.js';
+import { journeySteps } from '../steps.js';
+import type { JsonSchema, ModelContext, ModelContextTool, ModelContextToolInfo, ModelContextToolResponse } from '../../types.js';
+
+/** The tool's registered name. */
+export const OPEN_PAGE_TOOL = 'open_page';
+
+/** Past this many pages the names are described rather than listed. */
+const MAX_LISTED = 40;
+
+/** Where the tool takes the visitor, and how to go. */
+export interface OpenPageOptions {
+  /** The site's origin. Defaults to the page's own. */
+  origin?: string;
+  /** The current page URL. Defaults to the browser's. */
+  href?: string;
+  /** Where the visit waits while the browser moves. Defaults to `sessionStorage`. */
+  storage?: Storage | null;
+  /** How to go to another page. Defaults to assigning `location`. */
+  navigate?: (url: string) => void;
+  /** How to return to the previous page. Defaults to `history.back()`. */
+  back?: () => void;
+  /** The page the visitor came from. Defaults to `document.referrer`. Read when the tool runs. */
+  referrer?: () => string;
+  /** The conversation to continue on arrival. Read when the tool runs. */
+  conversationId?: () => string | undefined;
+  /**
+   * The site's graph, from its breadcrumb trails and page links.
+   *
+   * What makes "up a level" and "the section above" mean something, and what
+   * keeps the tool's list of destinations to the pages near this one rather
+   * than every page on the site.
+   */
+  nav?: SiteNav;
+  /**
+   * Fetch the trails the graph is missing, if they have not been fetched yet.
+   *
+   * Awaited when the tool runs, not at connect: the fetch is a read, and a
+   * site's rate limit counts reads. Going somewhere is what makes it worth one.
+   */
+  loadNav?: () => Promise<SiteNav>;
+}
+
+/** What the visitor says for the site's home page: "home", "take me to the home page". */
+const HOME =
+  /^(?:(?:go|take\s+me|return)\s+(?:to\s+)?)?(?:the\s+)?(?:home|homepage|home\s*page|start(?:\s*page)?|main\s*page|front\s*page|landing\s*page|index)$/i;
+/** What the visitor says for the page they came from: "back", "go back to the previous page". */
+const BACK =
+  /^(?:(?:go|take\s+me|return|head)\s+)?back(?:\s+to)?(?:\s+(?:the\s+)?(?:previous|last)\s+page)?$|^(?:the\s+)?(?:previous|last)\s+page$|^where\s+i\s+was$/i;
+
+/** What the visitor says for the page above this one: "up", "the section above". */
+const UP =
+  /^(?:(?:go|take\s+me|move)\s+)?(?:up|upward)(?:\s+(?:a|one)\s+level)?$|^(?:the\s+)?(?:parent|section|category)(?:\s+(?:page|above))?$|^(?:go\s+)?up\s+to\s+(?:the\s+)?(?:parent|section|category)$/i;
+
+/** A page's name compared the way a person would. */
+const normalName = (s: string): string => s.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, ' ').trim();
+
+/** Where a request to open a page resolves: a page, and whether it is reached by going back. */
+export type Destination =
+  | { kind: 'page' | 'home'; url: string; label: string }
+  | { kind: 'back'; url: string; label: string }
+  | { kind: 'none'; reason: string };
+
+/** The pages and options the tool was built with, so the harness can name a destination. */
+let known: { pages: SitePage[]; origin: string; opts: OpenPageOptions } = { pages: [], origin: '', opts: {} };
+
+const here = (href?: string): string => href ?? (typeof location === 'undefined' ? '' : location.href);
+const originOf = (origin?: string): string => origin ?? (typeof location === 'undefined' ? '' : location.origin);
+const referrerOf = (opts: OpenPageOptions): string =>
+  opts.referrer?.() ?? (typeof document === 'undefined' ? '' : document.referrer);
+
+const text = (t: string, isError = false): ModelContextToolResponse => ({
+  content: [{ type: 'text', text: t }],
+  ...(isError ? { isError: true } : {}),
+});
+
+/**
+ * Where a request to open a page goes.
+ *
+ * A page by name or address, and two that no site lists by name: "home", the
+ * site's root, and "back", the page the visitor came from — only when that was
+ * a page of this site, since going back must not leave it.
+ *
+ * @param wanted - What the visitor or model asked for.
+ * @param pages - The site's pages.
+ * @param origin - The site's origin.
+ * @param opts - The referrer seam.
+ */
+export function resolveDestination(
+  wanted: string,
+  pages: SitePage[],
+  origin: string,
+  opts: OpenPageOptions = {},
+): Destination {
+  const w = wanted.trim();
+  const named = (url: string): string | undefined => pages.find((p) => samePage(p.url, url))?.name;
+
+  // A page actually called that wins: "Back Office Plumbing" is a page, not a direction.
+  const exact = pages.filter((p) => normalName(p.name) === normalName(w));
+  if (exact.length === 1) return { kind: 'page', url: exact[0].url, label: exact[0].name };
+
+  if (UP.test(w)) {
+    const above = opts.nav && parentOf(here(opts.href), opts.nav);
+    return above
+      ? { kind: 'page', url: above, label: nameOf(above, opts.nav!) }
+      : { kind: 'none', reason: 'This page is not under a section I know of.' };
+  }
+
+  // Somewhere this page leads: a section above it, a page beside it, or a page it links to. Named
+  // by the site's own name for it, which is how the visitor heard of it.
+  const near = opts.nav ? nearby(opts.nav, here(opts.href)) : [];
+  const calledThat = near.filter((l) => normalName(l.name) === normalName(w));
+  if (calledThat.length === 1) return { kind: 'page', url: calledThat[0].url, label: calledThat[0].name };
+
+  if (BACK.test(w)) {
+    const from = referrerOf(opts);
+    let sameSite = false;
+    try {
+      sameSite = !!from && new URL(from).origin === new URL(origin).origin;
+    } catch {
+      sameSite = false;
+    }
+    return sameSite
+      ? { kind: 'back', url: from, label: named(from) ?? 'the previous page' }
+      : { kind: 'none', reason: 'There is no previous page on this site to go back to.' };
+  }
+
+  if (HOME.test(w)) {
+    const root = new URL('/', origin).href;
+    const home = pages.find((p) => ['/', '/index.html', '/index.htm'].includes(new URL(p.url).pathname));
+    return { kind: 'home', url: home?.url ?? root, label: home ? `the home page (${home.name})` : 'the home page' };
+  }
+
+  const found = findPage(w, pages, origin);
+  if (found) return { kind: 'page', url: found.url, label: found.name };
+  const loose = near.filter((l) => normalName(l.name).includes(normalName(w)));
+  if (loose.length === 1) return { kind: 'page', url: loose[0].url, label: loose[0].name };
+  const some = [...new Set([...near.map((l) => l.name), ...pages.map((p) => p.name)])].slice(0, 8).join(', ');
+  return {
+    kind: 'none',
+    reason: `There is no page called "${w}" on this site${some ? `. Pages include: ${some}` : ''}.`,
+  };
+}
+
+/**
+ * Build the page-opening tool for a site's pages.
+ *
+ * @param pages - Every page the agent may open.
+ * @param opts - Origin, current page, and the navigation seams.
+ * @returns The definition to register.
+ */
+export function buildOpenPageTool(pages: SitePage[], opts: OpenPageOptions = {}): ModelContextTool {
+  const origin = originOf(opts.origin);
+  known = { pages, origin, opts };
+  // Near first: a page's own surroundings are what a visitor asks for, and every name here reaches
+  // the prompt. The rest of the site stays reachable by name, and the description says so.
+  const near = opts.nav ? nearby(opts.nav, here(opts.href)).map((l) => l.name) : [];
+  const names = [...new Set([...near, ...pages.map((p) => p.name)])];
+  const listed = names.length <= MAX_LISTED ? names : [...new Set(near)].slice(0, MAX_LISTED);
+  const page: JsonSchema = {
+    type: 'string',
+    description:
+      (names.length <= MAX_LISTED
+        ? 'The page to open, by name.'
+        : 'The page to open: the name of the business, listing or record it is about. Any page of the site by name, not only those listed.') +
+      ' Use "home" for the home page, "back" for the page the visitor was on before, and "up" for the section above this page.',
+  };
+  if (listed.length) page.enum = ['home', 'back', ...(opts.nav || opts.loadNav ? ['up'] : []), ...listed];
+
+  return {
+    name: OPEN_PAGE_TOOL,
+    description:
+      'Take the visitor to a page on this site. Use when they ask to go to, open, visit or see a page — ' +
+      'for example the page of a result you found, the home page, or back to the previous page.',
+    inputSchema: { type: 'object', properties: { page }, required: ['page'] },
+    annotations: { readOnlyHint: true },
+    execute: async (input: Record<string, unknown>) => {
+      const filled = await opts.loadNav?.().catch(() => opts.nav);
+      const to = resolveDestination(String(input?.page ?? ''), pages, origin, {
+        ...opts,
+        nav: filled ?? opts.nav,
+      });
+      if (to.kind === 'none') return text(to.reason, true);
+      if (samePage(to.url, here(opts.href))) return text(`You are already on ${to.label}.`);
+
+      savePendingVisit(
+        { pageUrl: to.url, label: to.label, conversationId: opts.conversationId?.(), steps: journeySteps() },
+        { storage: opts.storage },
+      );
+      if (to.kind === 'back') (opts.back ?? (() => history.back()))();
+      else (opts.navigate ?? ((url: string) => location.assign(url)))(to.url);
+      return {
+        content: [{ type: 'text', text: `Opening ${to.label}…` }],
+        structuredContent: { [HANDOFF_RESULT]: { pageUrl: to.url, label: to.label } },
+      };
+    },
+  } as ModelContextTool;
+}
+
+/**
+ * Everywhere this page leads: the sections above it, the pages beside and under
+ * it, and the pages it points at. Ancestors first, because "up" and "the
+ * section" are what a visitor asks for most.
+ */
+function nearby(nav: SiteNav, href: string): NavLink[] {
+  const { ancestors, siblings, children, links } = navFor(nav, href);
+  const seen = new Set<string>();
+  return [...ancestors, ...children, ...links, ...siblings].filter((l) =>
+    seen.has(l.url) ? false : (seen.add(l.url), true),
+  );
+}
+
+/**
+ * Where a call to the page-opening tool goes, before it runs.
+ *
+ * @returns The destination, or null when the tool is another one, the page is
+ * unknown, or it is the page already open.
+ */
+export function visitFor(
+  tool: Pick<ModelContextToolInfo, 'name'>,
+  values: Record<string, unknown>,
+  href?: string,
+): { pageUrl: string; label: string } | null {
+  if (tool.name !== OPEN_PAGE_TOOL) return null;
+  const to = resolveDestination(String(values?.page ?? ''), known.pages, known.origin || originOf(), known.opts);
+  if (to.kind === 'none' || samePage(to.url, here(href ?? known.opts.href))) return null;
+  return { pageUrl: to.url, label: to.label };
+}
+
+/**
+ * Register the page-opening tool, unless the registry already holds one.
+ *
+ * @returns Whether it was registered.
+ */
+export async function registerOpenPageTool(
+  mc: ModelContext,
+  pages: SitePage[],
+  opts: OpenPageOptions = {},
+): Promise<boolean> {
+  // Registered with no pages too: "home" and "back" need no list, and a site whose page records
+  // could not be read is exactly where a visitor still wants to get home.
+  const tool = buildOpenPageTool(pages, opts);
+  try {
+    if ((await mc.getTools()).some((t) => t.name === OPEN_PAGE_TOOL)) return false;
+  } catch {
+    // A registry that cannot list may still register.
+  }
+  try {
+    await mc.registerTool(tool);
+    return true;
+  } catch (err) {
+    console.warn(`[nxis-mcp] could not register ${OPEN_PAGE_TOOL}:`, err);
+    return false;
+  }
+}

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

@@ -0,0 +1,232 @@
+/**
+ * Carries one confirmed action across a page change.
+ *
+ * An action is run by filling the form on its own page, so a call made from
+ * anywhere else has to travel: the values are collected and confirmed where
+ * the visitor is, held here, and submitted once the browser arrives.
+ *
+ * What is held is what someone typed — a name, an email, a phone number — so
+ * it is kept in the tab's own session storage, expires in two minutes, and is
+ * read exactly once.
+ *
+ * @module
+ */
+import { samePage } from './site-actions.js';
+import type { AgentStep } from '../steps.js';
+
+/** A confirmed call waiting for its page to load. */
+export interface PendingAction {
+  /** The `@id` of the action to run on arrival. */
+  actionId: string;
+  /** What the page's own tool is expected to be called, if the id is not recorded. */
+  pageToolName: string;
+  /** The site tool the call was made through, for the card it produces. */
+  toolName: string;
+  /** The values to submit. */
+  values: Record<string, unknown>;
+  /** The page to submit on. */
+  pageUrl: string;
+  /** The conversation to return the result to. */
+  conversationId?: string;
+  /**
+   * The journey so far, so a surface can show it after the page has changed.
+   *
+   * The steps that led here happened on a page that no longer exists.
+   */
+  steps?: AgentStep[];
+  /** When it was stored, in epoch milliseconds. */
+  savedAt: number;
+}
+
+const KEY = 'nxis:pending-action:v1';
+
+/** How long a confirmed call stays good. Long enough for a page load, no longer. */
+export const PENDING_TTL_MS = 2 * 60 * 1000;
+
+/** Overrides for tests and for callers that manage their own storage. */
+export interface PendingOptions {
+  /** Where the call is held. Defaults to `sessionStorage`; null disables. */
+  storage?: Storage | null;
+  /** The clock. */
+  now?: () => number;
+}
+
+/** The tab's session storage, or null where it is unavailable or blocked. */
+function defaultStorage(): Storage | null {
+  try {
+    return typeof sessionStorage === 'undefined' ? null : sessionStorage;
+  } catch {
+    return null;
+  }
+}
+
+/** Where the id of the conversation in progress is read from. */
+let conversationSource: (() => string | undefined) | null = null;
+
+/**
+ * Say which conversation a call or visit that leaves this page belongs to.
+ *
+ * Set by whatever owns the conversation — the element, or a host's own UI —
+ * rather than passed where tools are built, because the tools are built by
+ * whichever script connects first, and on most sites that is not the UI.
+ *
+ * @param source - Returns the id of the conversation in progress; null to stop.
+ */
+export function setConversationSource(source: (() => string | undefined) | null): void {
+  conversationSource = source;
+}
+
+/** The conversation in progress, as its owner reports it. */
+function currentConversation(): string | undefined {
+  try {
+    return conversationSource?.() ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+const store = (opts: PendingOptions): Storage | null =>
+  opts.storage === undefined ? defaultStorage() : opts.storage;
+
+/**
+ * Hold a confirmed call until its page loads.
+ *
+ * @returns Whether it could be stored. A page that cannot store it must not
+ * navigate, or the values would be lost in transit.
+ */
+export function savePendingAction(
+  pending: Omit<PendingAction, 'savedAt'>,
+  opts: PendingOptions = {},
+): boolean {
+  const storage = store(opts);
+  if (!storage) return false;
+  const now = (opts.now ?? Date.now)();
+  try {
+    const conversationId = pending.conversationId ?? currentConversation();
+    storage.setItem(KEY, JSON.stringify({ ...pending, conversationId, savedAt: now }));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Take the call waiting for this page, if there is one.
+ *
+ * Reads once: a call this returns is removed, so a reload cannot submit the
+ * same form twice. An expired call is discarded wherever it is found. A call
+ * for another page is left alone, since the browser may still be on its way
+ * there.
+ *
+ * @param href - The page now open. Defaults to the browser's.
+ * @returns The call to submit here, or null.
+ */
+export function takePendingAction(href?: string, opts: PendingOptions = {}): PendingAction | null {
+  const storage = store(opts);
+  if (!storage) return null;
+  let pending: PendingAction | null;
+  try {
+    pending = JSON.parse(storage.getItem(KEY) || 'null') as PendingAction | null;
+  } catch {
+    pending = null;
+  }
+  if (!pending || typeof pending.savedAt !== 'number' || !pending.actionId) {
+    clearPendingAction(opts);
+    return null;
+  }
+
+  const now = (opts.now ?? Date.now)();
+  if (now - pending.savedAt > PENDING_TTL_MS || pending.savedAt > now) {
+    clearPendingAction(opts);
+    return null;
+  }
+
+  const here = href ?? (typeof location === 'undefined' ? undefined : location.href);
+  if (!samePage(pending.pageUrl, here)) return null;
+
+  clearPendingAction(opts);
+  return pending;
+}
+
+/** Forget any waiting call. */
+export function clearPendingAction(opts: PendingOptions = {}): void {
+  try {
+    store(opts)?.removeItem(KEY);
+  } catch {
+    /* nothing held, or storage gone */
+  }
+}
+
+/**
+ * A page the agent opened, waiting to pick the conversation up on arrival.
+ *
+ * Carries no values, only where the visitor was taken and the conversation
+ * that took them, so the thread they were in is the one they find there.
+ */
+export interface PendingVisit {
+  /** The page being opened. */
+  pageUrl: string;
+  /** What to call it. */
+  label: string;
+  /** The conversation to continue. */
+  conversationId?: string;
+  /** The journey so far. */
+  steps?: AgentStep[];
+  /** When it was stored, in epoch milliseconds. */
+  savedAt: number;
+}
+
+const VISIT_KEY = 'nxis:pending-visit:v1';
+
+/**
+ * Remember a page being opened, so the conversation follows the visitor.
+ *
+ * @returns Whether it could be stored. Unlike a pending action, nothing is lost
+ * when it cannot: the page still opens, in a fresh thread.
+ */
+export function savePendingVisit(visit: Omit<PendingVisit, 'savedAt'>, opts: PendingOptions = {}): boolean {
+  const storage = store(opts);
+  if (!storage) return false;
+  try {
+    const conversationId = visit.conversationId ?? currentConversation();
+    storage.setItem(VISIT_KEY, JSON.stringify({ ...visit, conversationId, savedAt: (opts.now ?? Date.now)() }));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Take the visit that brought the browser to this page, if there is one.
+ *
+ * Read once and discarded when stale, as a pending action is; a visit for
+ * another page is left, since the browser may still be on its way.
+ *
+ * @param href - The page now open. Defaults to the browser's.
+ */
+export function takePendingVisit(href?: string, opts: PendingOptions = {}): PendingVisit | null {
+  const storage = store(opts);
+  if (!storage) return null;
+  let visit: PendingVisit | null;
+  try {
+    visit = JSON.parse(storage.getItem(VISIT_KEY) || 'null') as PendingVisit | null;
+  } catch {
+    visit = null;
+  }
+  const drop = () => {
+    try {
+      storage.removeItem(VISIT_KEY);
+    } catch {
+      /* storage gone */
+    }
+  };
+  const now = (opts.now ?? Date.now)();
+  if (!visit || typeof visit.savedAt !== 'number' || !visit.pageUrl || now - visit.savedAt > PENDING_TTL_MS || visit.savedAt > now) {
+    drop();
+    return null;
+  }
+  const here = href ?? (typeof location === 'undefined' ? undefined : location.href);
+  if (!samePage(visit.pageUrl, here)) return null;
+  drop();
+  return visit;
+}

package/src/harness/tools/resume.ts

@@ -0,0 +1,134 @@
+/**
+ * Finishing, on arrival, a call that was confirmed on another page.
+ *
+ * The decisions here are the awkward ones — is there a call waiting, did the
+ * page's script ever register the form, does the live form want more than the
+ * record said — and they are worth testing without a browser. So the work is
+ * a function that returns what happened, and the caller draws it.
+ *
+ * @module
+ */
+import { takePendingAction, type PendingAction, type PendingOptions } from './pending-action.js';
+import { awaitPageTool } from './action-tools.js';
+import { extractResult, missingRequired } from './schema.js';
+import { recordStep, restoreJourney } from '../steps.js';
+import { waitForModelContext } from './source.js';
+import { WebMcpTools } from './webmcp.js';
+import type { ModelContext, ModelContextToolInfo, ModelContextToolResponse } from '../../types.js';
+
+/** How long to wait for the registry, and then for the form's own tool. */
+const WAIT_MS = 8000;
+
+/** What became of the call that was waiting for this page. */
+export type ResumeOutcome =
+  /** Nothing was waiting for this page. The ordinary case. */
+  | { status: 'none' }
+  /** WebMCP never appeared, so the form's tool could not be reached. */
+  | { status: 'no-registry'; pending: PendingAction }
+  /** The page never registered a tool for this action. */
+  | { status: 'no-tool'; pending: PendingAction }
+  /** The live form requires values the record did not carry. */
+  | { status: 'incomplete'; pending: PendingAction; tool: ModelContextToolInfo; missing: string[] }
+  /** Submitted. */
+  | { status: 'submitted'; pending: PendingAction; tool: ModelContextToolInfo; text: string }
+  /** The tool ran and reported a failure. */
+  | { status: 'rejected'; pending: PendingAction; tool: ModelContextToolInfo; text: string }
+  /** The call threw. */
+  | { status: 'failed'; pending: PendingAction; tool: ModelContextToolInfo; error: string };
+
+/** Overrides, so this can be exercised without a page. */
+export interface ResumeOptions extends PendingOptions {
+  /** The page now open. Defaults to the browser's. */
+  href?: string;
+  /** How long to wait for the registry and 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>;
+  /** Run the tool. */
+  exec?(
+    tool: ModelContextToolInfo,
+    values: Record<string, unknown>,
+  ): Promise<ModelContextToolResponse>;
+  /**
+   * Called once a waiting call is found, before the waits begin.
+   *
+   * The page has just loaded and the registry may take seconds to appear, so
+   * this is where a UI opens the conversation the call came from rather than
+   * leaving the visitor looking at an unrelated thread.
+   */
+  onStart?(pending: PendingAction): void;
+}
+
+/**
+ * Submit the call waiting for this page, if there is one.
+ *
+ * Runs while the page is still loading, so neither the registry nor the
+ * page's tools exist yet — the script that installs them is usually still
+ * being fetched. Both waits are needed, and in this order.
+ *
+ * @param opts - Page, timeouts, and the seams tests replace.
+ * @returns What happened, for the caller to render.
+ */
+export async function resumePendingAction(opts: ResumeOptions = {}): Promise<ResumeOutcome> {
+  const pending = takePendingAction(opts.href, opts);
+  if (!pending) return { status: 'none' };
+  // The journey continues from where the other page left it.
+  restoreJourney(pending.steps);
+  recordStep({ id: 'navigate', label: 'Opened the page', status: 'done' });
+  recordStep({ id: 'arrive', label: 'Found the form', status: 'active' });
+  opts.onStart?.(pending);
+
+  const timeoutMs = opts.timeoutMs ?? WAIT_MS;
+  const waitForRegistry = opts.registry ?? ((ms: number) => waitForModelContext(ms));
+  const mc = await waitForRegistry(timeoutMs);
+  if (!mc) {
+    recordStep({ id: 'arrive', label: 'This page has no agent tools', status: 'failed' });
+    return { status: 'no-registry', pending };
+  }
+
+  const findTool = opts.pageTool ?? ((c, ref, ms) => awaitPageTool(c, ref, ms));
+  const tool = await findTool(mc, { id: pending.actionId, name: pending.pageToolName }, timeoutMs);
+  if (!tool) {
+    recordStep({ id: 'arrive', label: 'Could not find the form here', status: 'failed' });
+    return { status: 'no-tool', pending };
+  }
+  recordStep({ id: 'arrive', label: 'Found the form', status: 'done' });
+
+  // The record says only what the crawler recorded; the form in front of us
+  // says what it actually insists on. Now that its page is open, ask rather
+  // than submit a half-filled form on someone's behalf.
+  const missing = missingRequired(tool, pending.values);
+  if (missing.length) {
+    recordStep({
+      id: 'collect',
+      label: 'This form needs more',
+      status: 'active',
+      detail: missing.join(', '),
+    });
+    return { status: 'incomplete', pending, tool, missing };
+  }
+
+  recordStep({ id: 'fill', label: 'Filling the form', status: 'active' });
+  const run = opts.exec ?? ((t, values) => new WebMcpTools().execTool(t, t.name, values));
+  try {
+    const res = await run(tool, pending.values);
+    const text = extractResult(res);
+    if (res?.isError) {
+      recordStep({ id: 'submit', label: 'It did not go through', status: 'failed', detail: text });
+      return { status: 'rejected', pending, tool, text };
+    }
+    recordStep({ id: 'fill', label: 'Filled the form', status: 'done' });
+    recordStep({ id: 'submit', label: 'Submitted', status: 'done' });
+    return { status: 'submitted', pending, tool, text };
+  } catch (err) {
+    const error = String((err as Error)?.message || err);
+    recordStep({ id: 'submit', label: 'It did not go through', status: 'failed', detail: error });
+    return { status: 'failed', pending, tool, error };
+  }
+}