@nxisai/agent-harness 0.5.0 → 0.7.0

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

@@ -285,6 +285,11 @@ export interface BuildOptions {
   navigate?: (url: string) => void;
   /** The conversation a travelling call should report back to. */
   conversationId?: string;
+  /**
+   * Look up a form none of a tool's own actions matched: the site's index may
+   * hold it only inside the record it belongs to. See `findEmbeddedAction`.
+   */
+  findAction?: (query: { actionName: string; field: string; value: string }) => Promise<NxisAction | null>;
 }
 
 /**
@@ -356,6 +361,15 @@ export function isSiteTool(tool: ModelContextToolInfo): boolean {
   return coverageOf(tool) !== null;
 }
 
+/**
+ * The field that says which of a site tool's forms a call means: `business`,
+ * or the added `target`. Null for a tool that covers one form, or is not a
+ * site tool.
+ */
+export function chooserOf(tool: ModelContextToolInfo): string | null {
+  return coverageOf(tool)?.chooser || null;
+}
+
 /** A tool's coverage, from what this page built or from what it carries. */
 function coverageOf(tool: ModelContextToolInfo): Coverage | null {
   const local = built.get(tool.name);
@@ -484,6 +498,31 @@ function pickAction(
   return loose >= 0 ? tool.actions[loose] : null;
 }
 
+/**
+ * The options each field offers on the one form a call means.
+ *
+ * A site tool's schema accepts any option the same field offers on any of its
+ * pages, which for a per-business quote form is every service of every
+ * business. Once the call says which business, only that form's options mean
+ * anything, and a prompt should offer only those.
+ *
+ * @returns Option values by field name; empty when the tool is not a site
+ * tool built on this page, or the call does not yet say which form.
+ */
+export function formOptions(tool: ModelContextToolInfo, values: Record<string, unknown>): Record<string, string[]> {
+  const local = built.get(tool.name);
+  const action = local ? pickAction(local, values ?? {}) : null;
+  const out: Record<string, string[]> = {};
+  for (const spec of action?.input ?? []) {
+    const options = (spec['nxis:valueOption'] ?? []).map((o) => o.value).filter((v) => !isPlaceholder(v));
+    if (options.length) out[spec.valueName] = options;
+  }
+  return out;
+}
+
+/** 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);
+
 /** Which page tool to look for: the action's id, and the name it would have. */
 export interface PageToolRef {
   /** The action's `@id`. */
@@ -622,10 +661,12 @@ async function runSiteAction(
   input: Record<string, unknown>,
   opts: BuildOptions,
 ): Promise<ModelContextToolResponse> {
-  const action = pickAction(tool, input ?? {});
+  const wanted = tool.discriminator ? String(input?.[tool.discriminator] ?? '').trim() : '';
+  const action = pickAction(tool, input ?? {}) ?? (await lookUp(tool, wanted, opts));
   if (!action) {
-    const choices = (tool.choices ?? []).join(', ');
-    return text(`Say which one this is for. Choices: ${choices}.`, true);
+    // Said to the visitor as well as the model: the renderer shows a failed call's result.
+    if (!wanted) return text(`Say which one this is for: ${summarize(tool.choices ?? [])}.`, true);
+    return text(`I couldn't find a ${humanize(tool.actions[0].name)} for "${wanted}" on this site. It covers ${summarize(tool.choices ?? [])}.`, true);
   }
 
   const pageUrl = action.target['nxis:pageUrl'] ?? '';
@@ -633,7 +674,7 @@ async function runSiteAction(
     // Filling the form means being on its page, so the confirmed call travels:
     // held in this tab, submitted once the browser arrives.
     const index = tool.actions.indexOf(action);
-    const label = tool.choices?.[index] || pageLabel(pageUrl);
+    const label = tool.choices?.[index] || wanted || pageLabel(pageUrl);
     const here = opts.href ?? (typeof location === 'undefined' ? '' : location.href);
     if (!sameOrigin(pageUrl, here)) {
       return text(`"${action.name}" belongs to another site, so I did not open it.`, true);
@@ -684,6 +725,35 @@ async function runSiteAction(
   return executeRegistered(mc, pageTool, pageTool.name, args);
 }
 
+/**
+ * The action a call names that is not among the tool's own: found in the
+ * site's index, inside the record it belongs to. Null when there is nothing
+ * to look up, nobody to ask, or nothing found.
+ */
+async function lookUp(
+  tool: Pick<SiteActionTool, 'actions' | 'discriminator'>,
+  wanted: string,
+  opts: BuildOptions,
+): Promise<NxisAction | null> {
+  if (!wanted || !tool.discriminator || !opts.findAction) return null;
+  try {
+    return await opts.findAction({ actionName: tool.actions[0].name, field: tool.discriminator, value: wanted });
+  } catch (err) {
+    console.warn(`[nxis-mcp] could not look up "${wanted}":`, err);
+    return null;
+  }
+}
+
+/** A list of choices short enough to read: the first few, and how many more. */
+function summarize(choices: string[]): string {
+  if (!choices.length) return 'nothing yet';
+  const shown = choices.slice(0, 5).join(', ');
+  return choices.length > 5 ? `${shown}, and ${choices.length - 5} more` : shown;
+}
+
+/** `quote-form` → `quote form`. */
+const humanize = (name: string): string => name.replace(/[-_]+/g, ' ').trim();
+
 /**
  * The arguments the form itself takes.
  *

package/src/harness/tools/discovery.ts

@@ -8,7 +8,7 @@
  *
  * @module
  */
-import type { CatalogFile, McpServerInfo, ServerCard } from '../../types.js';
+import type { CatalogEntry, CatalogFile, McpServerInfo, ServerCard } from '../../types.js';
 
 async function fetchJson<T>(url: string): Promise<T> {
   const res = await fetch(url, { headers: { Accept: 'application/json' } });
@@ -16,13 +16,31 @@ async function fetchJson<T>(url: string): Promise<T> {
   return (await res.json()) as T;
 }
 
+/**
+ * The catalog entry for the MCP server card.
+ *
+ * A catalog can list more than the MCP server: an A2A Agent Card for a
+ * handoff target, say. An entry typed as an MCP server card wins; an entry
+ * typed as anything else is never taken for one; an untyped entry is taken
+ * only when nothing is typed, as older catalogs have no types at all.
+ *
+ * @returns The entry, or undefined when the catalog lists no MCP server.
+ */
+export function mcpCatalogEntry(catalog: CatalogFile): CatalogEntry | undefined {
+  const entries = (catalog.entries ?? []).filter((e) => !!e.url);
+  const typeOf = (e: CatalogEntry) => (e.type ?? e.mediaType ?? '').toLowerCase();
+  const typed = entries.find((e) => /\bmcp\b|mcp-server/.test(typeOf(e)));
+  if (typed) return typed;
+  return entries.find((e) => !typeOf(e));
+}
+
 /** Find the server-card URL by reading the well-known catalogs in order. */
 async function resolveServerCardUrl(): Promise<string> {
   const catalogs = ['/.well-known/ai-catalog.json', '/.well-known/mcp/catalog.json'];
   for (const path of catalogs) {
     try {
       const catalog = await fetchJson<CatalogFile>(path);
-      const entry = catalog.entries?.find((e) => !!e.url);
+      const entry = mcpCatalogEntry(catalog);
       if (entry?.url) return entry.url;
     } catch {
       /* try the next catalog */

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

@@ -256,6 +256,64 @@ export async function queryTypedRecords(client: Client, fragment: string): Promi
   return records;
 }
 
+/** What a form tool is looking for when none of its own actions matched. */
+export interface EmbeddedActionQuery {
+  /** The action's name, as the tool's group shares it: `quote-form`. */
+  actionName: string;
+  /** The field that chooses between the group's actions: `business`, or the added `target`. */
+  field: string;
+  /** The value the call gave it: `Hatzel & Sons Plumbing`. */
+  value: string;
+  /** The origin the action's page must be on. Defaults to the page's own. */
+  origin?: string;
+}
+
+/**
+ * Find a form the index holds only inside another record.
+ *
+ * The site's actions are fetched once, as standalone Action records. An index
+ * can lag behind its pages — a partial re-crawl leaves some forms only as the
+ * `potentialAction` of the business or page they belong to — and a call naming
+ * one of those would otherwise fail with "say which one". So a miss looks the
+ * value up by name, and takes an action embedded in what it finds when that
+ * action is the same form: the same name, on this origin, and meant for this
+ * value.
+ *
+ * @param client - A connected client for the site's MCP server.
+ * @param query - The form, the choosing field, and the value asked for.
+ * @returns The action, or null when nothing on the site matches.
+ */
+export async function findEmbeddedAction(client: Client, query: EmbeddedActionQuery): Promise<NxisAction | null> {
+  const origin = query.origin ?? location.origin;
+  const wanted = query.value.trim().toLowerCase();
+  if (!wanted) return null;
+  const result = await withRetry(() =>
+    client.callTool({
+      name: 'nxis_query',
+      arguments: {
+        filter: { schema_type: '', field_filters: [{ path: 'name', operator: 'CONTAINS', value: query.value.trim() }] },
+        limit: 20,
+      },
+    }),
+  );
+  const matches: NxisAction[] = [];
+  for (const record of readResults(result).results) {
+    if (!isObj(record)) continue;
+    const owner = (str(schemaValue(record, 'name')) ?? '').trim().toLowerCase();
+    const embedded = schemaValue(record, 'potentialAction');
+    for (const raw of Array.isArray(embedded) ? embedded : [embedded]) {
+      const action = parseAction(raw);
+      if (!action || action.name !== query.actionName || !onOrigin(action, origin)) continue;
+      // Meant for this value: the form says so itself, or it belongs to the record the value names.
+      const own = action.input?.find((i) => i.valueName === query.field)?.defaultValue?.trim().toLowerCase();
+      if (own ? own === wanted : owner === wanted) matches.push(action);
+    }
+  }
+  // Two different forms answering to one name is a question for the visitor, not a guess.
+  const pages = new Set(matches.map((a) => a.target['nxis:pageUrl']));
+  return pages.size === 1 ? matches[0] : null;
+}
+
 /** The tab's session storage, or null where it is unavailable or blocked. */
 function defaultStorage(): Storage | null {
   try {

package/src/harness/tools/source.ts

@@ -17,7 +17,7 @@ import { registerRemoteTools, type BridgeOptions } from './bridge.js';
 import { ensureModelContext } from './local-context.js';
 import { connectMcp } from './client.js';
 import { discoverMcpServer } from './discovery.js';
-import { loadSiteActions, type SiteActionsOptions } from './site-actions.js';
+import { findEmbeddedAction, loadSiteActions, type SiteActionsOptions } from './site-actions.js';
 import { registerSiteActionTools } from './action-tools.js';
 import { loadSitePages, mergePages, pagesFromActions, type SitePage } from './site-pages.js';
 import { registerOpenPageTool, OPEN_PAGE_TOOL, type OpenPageOptions } from './open-page.js';
@@ -218,7 +218,10 @@ async function connectRegistry(
   let warning: string | undefined;
   try {
     siteActions = await loadSiteActions(client, info, siteOpts);
-    siteTools = await registerSiteActionTools(mc, siteActions);
+    siteTools = await registerSiteActionTools(mc, siteActions, {
+      // A form the index holds only inside its business or page, looked up when a call names it.
+      findAction: (query) => findEmbeddedAction(client, { ...query, origin: siteOpts.origin }),
+    });
   } catch (err) {
     warning = `site actions unavailable — this page's own actions still work: ${errorText(err)}`;
     console.warn(`[nxis-mcp] ${warning}`);

package/src/index.ts

@@ -171,10 +171,13 @@ export {
   setConversationSource,
 } from './harness/tools/pending-action.js';
 export type { PendingAction, PendingVisit } from './harness/tools/pending-action.js';
-export { loadSiteActions, parseAction } from './harness/tools/site-actions.js';
+export { findEmbeddedAction, loadSiteActions, parseAction, type EmbeddedActionQuery } from './harness/tools/site-actions.js';
 export type { ConnectResult, ConnectOptions, SiteActionsOptions } from './harness/tools/source.js';
 export type { BridgeOptions } from './harness/tools/bridge.js';
 
+// Handing a conversation to another agent or a person, over A2A. See docs/handoff.md.
+export * from './handoff/index.js';
+
 export type {
   JsonSchema,
   ModelContext,