@nxisai/agent-harness 0.5.0 → 0.6.0

package/src/handoff/envelope.ts

@@ -0,0 +1,216 @@
+/**
+ * The handoff extension: what a handoff carries, and how it reads the answers.
+ *
+ * Everything travels as A2A `data` parts marked with {@link HANDOFF_EXTENSION},
+ * so a target that knows nothing of it still works. See `docs/handoff.md`.
+ *
+ * @module
+ */
+import { newMessageId, type A2AMessage, type A2APart } from './a2a.js';
+
+/** The extension's URI, announced in `A2A-Extensions` and on every part it adds. */
+export const HANDOFF_EXTENSION = 'https://nxis.ai/a2a/handoff/v1';
+
+/** What the first message of a handoff carries. */
+export interface HandoffEnvelope {
+  /** Why, in one line. */
+  reason: string;
+  /** What the target needs to know. The visitor has seen it. */
+  summary: string;
+  /** The page the visitor is on. */
+  page: { url: string; title: string; entity?: string };
+  /** Values the visitor gave and agreed to share. */
+  facts?: { name: string; value: string }[];
+  /** The last turns, text only. Only for a target the relay allows it for. */
+  transcript?: { role: 'visitor' | 'assistant'; text: string }[];
+  /** How to reach the visitor later, only when they asked to be contacted. */
+  contact?: { email?: string; phone?: string; name?: string };
+  /** The visitor's language. */
+  locale: string;
+  /** Where a hand-back belongs. */
+  returnTo: { conversationId: string; origin: string };
+  /** What was agreed to: the target, the fields sent, and when. */
+  consent: { target: string; shared: string[]; at: string };
+}
+
+/** How a handoff ended, from the target's `handback` part. */
+export interface HandBack {
+  outcome: 'resolved' | 'unresolved' | 'transferred';
+  note: string;
+  references: { label: string; value: string }[];
+}
+
+/** Query parameters that only describe how a page was reached or shown, never which page it is. */
+const DYNAMIC_PARAMS = /^(surface|utm_.*|gclid|fbclid|msclkid|mc_cid|mc_eid|_ga)$/i;
+
+/**
+ * A page's address without the parameters that don't identify it.
+ *
+ * `?surface=window` says how the agent is shown, and `utm_*` how the visitor
+ * arrived; neither is part of the page a target should look up.
+ */
+export function cleanPageUrl(href: string): string {
+  try {
+    const url = new URL(href);
+    for (const key of [...url.searchParams.keys()]) {
+      if (DYNAMIC_PARAMS.test(key)) url.searchParams.delete(key);
+    }
+    url.hash = '';
+    return url.href;
+  } catch {
+    return href;
+  }
+}
+
+/** The JSON-LD `@id` of what this page is about, if it declares one for itself. */
+export function pageEntity(doc: Document | undefined = typeof document === 'undefined' ? undefined : document): string | undefined {
+  if (!doc) return undefined;
+  const here = cleanPageUrl(doc.location?.href ?? '');
+  for (const script of Array.from(doc.querySelectorAll('script[type="application/ld+json"]'))) {
+    let json: unknown;
+    try {
+      json = JSON.parse(script.textContent || '');
+    } catch {
+      continue;
+    }
+    const nodes = Array.isArray(json)
+      ? json
+      : ((json as { '@graph'?: unknown[] })?.['@graph'] ?? [json]);
+    for (const node of nodes as { '@id'?: unknown }[]) {
+      const id = typeof node?.['@id'] === 'string' ? node['@id'] : '';
+      // The entity the page is about is named `<page url>#…` by the NxisAI crawler.
+      if (id && here && id.startsWith(here.split('#')[0] + '#')) return id;
+    }
+  }
+  return undefined;
+}
+
+/** What {@link buildEnvelope} needs beyond the page. */
+export interface EnvelopeInput {
+  target: string;
+  reason: string;
+  summary: string;
+  conversationId: string;
+  facts?: { name: string; value: string }[];
+  transcript?: { role: 'visitor' | 'assistant'; text: string }[];
+  contact?: { email?: string; phone?: string; name?: string };
+  /** Overrides, for tests and for hosts outside a browser. */
+  page?: { url: string; title: string; entity?: string };
+  locale?: string;
+  origin?: string;
+  now?: () => Date;
+}
+
+/** The envelope for a handoff, with its consent record filled from what is actually sent. */
+export function buildEnvelope(input: EnvelopeInput): HandoffEnvelope {
+  const doc = typeof document === 'undefined' ? undefined : document;
+  const page = input.page ?? {
+    url: cleanPageUrl(doc?.location?.href ?? ''),
+    title: doc?.title ?? '',
+    entity: pageEntity(doc),
+  };
+  if (!page.entity) delete page.entity;
+  const envelope: HandoffEnvelope = {
+    reason: input.reason.trim(),
+    summary: input.summary.trim(),
+    page,
+    locale: input.locale ?? (typeof navigator === 'undefined' ? 'en' : navigator.language || 'en'),
+    returnTo: {
+      conversationId: input.conversationId,
+      origin: input.origin ?? (typeof location === 'undefined' ? '' : location.origin),
+    },
+    consent: { target: input.target, shared: [], at: (input.now?.() ?? new Date()).toISOString() },
+  };
+  if (input.facts?.length) envelope.facts = input.facts;
+  if (input.transcript?.length) envelope.transcript = input.transcript;
+  const contact = input.contact && Object.fromEntries(Object.entries(input.contact).filter(([, v]) => !!v));
+  if (contact && Object.keys(contact).length) envelope.contact = contact;
+  envelope.consent.shared = Object.keys(envelope).filter((k) => k !== 'consent' && k !== 'returnTo' && k !== 'locale');
+  return envelope;
+}
+
+/** A data part marked with the extension. */
+export function extensionPart(data: Record<string, unknown>): A2APart {
+  return { data, mediaType: 'application/json', metadata: { extension: HANDOFF_EXTENSION } };
+}
+
+/** The first message of a handoff: the summary as text, for any target, and the envelope as data. */
+export function envelopeMessage(envelope: HandoffEnvelope): A2AMessage {
+  const lines = [envelope.summary];
+  if (envelope.page.url) lines.push(`Page: ${envelope.page.title ? `${envelope.page.title} (${envelope.page.url})` : envelope.page.url}`);
+  return {
+    messageId: newMessageId(),
+    role: 'ROLE_USER',
+    parts: [{ text: lines.join('\n\n') }, extensionPart({ handoff: 'envelope', ...envelope })],
+    extensions: [HANDOFF_EXTENSION],
+  };
+}
+
+/** A message the visitor typed during a handoff. */
+export function visitorMessage(text: string, ids: { taskId?: string; contextId?: string }): A2AMessage {
+  const message: A2AMessage = { messageId: newMessageId(), role: 'ROLE_USER', parts: [{ text }] };
+  if (ids.taskId) message.taskId = ids.taskId;
+  if (ids.contextId) message.contextId = ids.contextId;
+  return message;
+}
+
+/** The extension data in a part, and which kind it is, or null for any other part. */
+export function extensionData(part: A2APart): (Record<string, unknown> & { handoff: string }) | null {
+  const data = part.data as Record<string, unknown> | undefined;
+  if (!data || typeof data !== 'object' || typeof data.handoff !== 'string') return null;
+  // Marked parts are ours; an unmarked one with the same shape is accepted too, since some servers
+  // drop part metadata, but only for the kinds we define.
+  const marked = part.metadata?.extension === HANDOFF_EXTENSION;
+  if (!marked && !['queue', 'operator', 'handback'].includes(data.handoff)) return null;
+  return data as Record<string, unknown> & { handoff: string };
+}
+
+/** A `handback` part's contents, tidied, or null. */
+export function readHandBack(parts: A2APart[] = []): HandBack | null {
+  for (const part of parts) {
+    const data = extensionData(part);
+    if (data?.handoff !== 'handback') continue;
+    const outcome = data.outcome === 'unresolved' || data.outcome === 'transferred' ? data.outcome : 'resolved';
+    const references = Array.isArray(data.references)
+      ? (data.references as { label?: unknown; value?: unknown }[])
+          .filter((r) => r && r.value !== undefined && r.value !== null && String(r.value).trim())
+          .map((r) => ({ label: String(r.label ?? 'Reference'), value: String(r.value) }))
+      : [];
+    return { outcome, note: String(data.note ?? '').trim(), references };
+  }
+  return null;
+}
+
+/** A `queue` part's position and wait, or null. */
+export function readQueue(parts: A2APart[] = []): { position?: number; waitMinutes?: number } | null {
+  for (const part of parts) {
+    const data = extensionData(part);
+    if (data?.handoff !== 'queue') continue;
+    const num = (v: unknown) => (typeof v === 'number' && Number.isFinite(v) ? v : undefined);
+    return { position: num(data.position), waitMinutes: num(data.waitMinutes) };
+  }
+  return null;
+}
+
+/** An `operator` part's name and kind, or null. */
+export function readOperator(parts: A2APart[] = []): { name: string; kind: 'person' | 'agent' } | null {
+  for (const part of parts) {
+    const data = extensionData(part);
+    if (data?.handoff !== 'operator' || typeof data.name !== 'string' || !data.name.trim()) continue;
+    return { name: data.name.trim(), kind: data.kind === 'agent' ? 'agent' : 'person' };
+  }
+  return null;
+}
+
+/** The text a visitor should read from some parts: text parts, and files by name. Data parts are not shown. */
+export function readableText(parts: A2APart[] = []): string {
+  return parts
+    .map((p) => {
+      if (typeof p.text === 'string') return p.text;
+      if (p.url) return p.filename ? `${p.filename}: ${p.url}` : p.url;
+      return '';
+    })
+    .filter((t) => t.trim())
+    .join('\n\n')
+    .trim();
+}

package/src/handoff/index.ts

@@ -0,0 +1,53 @@
+/**
+ * Handing a conversation to another agent or a person, over A2A.
+ *
+ * See `docs/handoff.md`.
+ *
+ * @module
+ */
+export { A2AClient, A2AError, A2A_VERSION, isTerminal, normaliseResponse, taskState } from './a2a.js';
+export type {
+  A2AArtifact,
+  A2AClientOptions,
+  A2AMessage,
+  A2APart,
+  A2AReply,
+  A2AStream,
+  A2AStreamResponse,
+  A2ATask,
+  A2ATaskState,
+  A2ATaskStatus,
+} from './a2a.js';
+export {
+  HANDOFF_EXTENSION,
+  buildEnvelope,
+  cleanPageUrl,
+  envelopeMessage,
+  pageEntity,
+  readHandBack,
+  readOperator,
+  readQueue,
+  readableText,
+} from './envelope.js';
+export type { EnvelopeInput, HandBack, HandoffEnvelope } from './envelope.js';
+export { HANDOFF_KEY_HEADER, HandoffController, isHandoffOver } from './controller.js';
+export type {
+  HandoffConfig,
+  HandoffControllerOptions,
+  HandoffEvent,
+  HandoffKind,
+  HandoffSession,
+  HandoffState,
+  HandoffTarget,
+  HandoffTargetConfig,
+} from './controller.js';
+export {
+  HANDOFF_SESSION_RESULT,
+  TALK_TO_A_PERSON_TOOL,
+  TRANSFER_TO_AGENT_TOOL,
+  availability,
+  buildHandoffTools,
+  isHandoffTool,
+  registerHandoffTools,
+} from './tools.js';
+export type { HandoffToolOptions } from './tools.js';

package/src/handoff/tools.ts

@@ -0,0 +1,178 @@
+/**
+ * The tools that start a handoff: `transfer_to_agent` and `talk_to_a_person`.
+ *
+ * The model proposes a handoff by calling one, with a reason and a summary. The
+ * tools are consequential, so the harness shows the visitor the call (target,
+ * reason, summary) and waits for them to press Send before anything leaves the
+ * page. Each tool lists only the targets the page's config names and the relay
+ * reports, so the model can't send a conversation anywhere else.
+ *
+ * @module
+ */
+import { buildEnvelope } from './envelope.js';
+import type { HandoffController, HandoffKind, HandoffTarget } from './controller.js';
+import type { JsonSchema, ModelContext, ModelContextTool, ModelContextToolResponse } from '../types.js';
+
+export const TRANSFER_TO_AGENT_TOOL = 'transfer_to_agent';
+export const TALK_TO_A_PERSON_TOOL = 'talk_to_a_person';
+
+/** The key a started handoff is reported under in a tool result's `structuredContent`. */
+export const HANDOFF_SESSION_RESULT = 'ai.nxis/handoff-session';
+
+/** Whether a tool is one of the handoff tools. */
+export const isHandoffTool = (name: string): boolean => name === TRANSFER_TO_AGENT_TOOL || name === TALK_TO_A_PERSON_TOOL;
+
+/** What the tools need from their host. */
+export interface HandoffToolOptions {
+  /** The conversation a call belongs to. Read when the tool runs. */
+  conversationId(): string | undefined;
+  /**
+   * The conversation's recent turns, text only, for a target the relay allows
+   * a transcript for. Omit to never send one.
+   */
+  transcript?(): { role: 'visitor' | 'assistant'; text: string }[];
+}
+
+const text = (t: string, isError = false): ModelContextToolResponse => ({
+  content: [{ type: 'text', text: t }],
+  ...(isError ? { isError: true } : {}),
+});
+
+/** How a desk's availability reads, for a tool description and for the visitor. */
+export function availability(target: HandoffTarget): string {
+  if (!target.available) return `away now${target.hours ? ` (open ${target.hours})` : ''}`;
+  if (target.kind !== 'person') return 'available';
+  const wait = target.waitMinutes ? `, about ${target.waitMinutes} min wait` : '';
+  return `available${wait}`;
+}
+
+/**
+ * The handoff tools for the targets that can be offered now.
+ *
+ * @returns Up to two tools; none when the relay offers no configured target.
+ */
+export async function buildHandoffTools(
+  controller: HandoffController,
+  opts: HandoffToolOptions,
+): Promise<ModelContextTool[]> {
+  const targets = await controller.targets();
+  const tools: ModelContextTool[] = [];
+  const agents = targets.filter((t) => t.kind === 'agent');
+  const people = targets.filter((t) => t.kind === 'person');
+  if (agents.length) tools.push(buildTool('agent', agents, controller, opts));
+  if (people.length) tools.push(buildTool('person', people, controller, opts));
+  return tools;
+}
+
+function buildTool(
+  kind: HandoffKind,
+  targets: HandoffTarget[],
+  controller: HandoffController,
+  opts: HandoffToolOptions,
+): ModelContextTool {
+  const name = kind === 'agent' ? TRANSFER_TO_AGENT_TOOL : TALK_TO_A_PERSON_TOOL;
+  const menu = targets
+    .map((t) => `"${t.name}" (${t.label}${t.description ? `: ${t.description}` : ''}; ${availability(t)})`)
+    .join('; ');
+  const description =
+    kind === 'agent'
+      ? `Hand this conversation to another agent that can finish what you can't. Use only when the visitor needs something one of these handles: ${menu}. The visitor sees the summary and confirms before anything is sent.`
+      : `Hand this conversation to a person on the site's team. Use when the visitor asks for a person, or when you can't help. Targets: ${menu}. The visitor sees the summary and confirms before anything is sent. When the team is away, ask for an email so they can reply.`;
+
+  const properties: Record<string, JsonSchema> = {
+    target: {
+      type: 'string',
+      enum: targets.map((t) => t.name),
+      description: 'Who to hand the conversation to.',
+      ...(targets.length === 1 ? { default: targets[0].name } : {}),
+    },
+    reason: { type: 'string', description: "Why, in one short line, e.g. 'Wants to book a boiler inspection'." },
+    summary: {
+      type: 'string',
+      description:
+        'What they need to know to help, in two or three sentences, from what the visitor said. The visitor reads this before sending. No details the visitor did not give.',
+    },
+  };
+  if (kind === 'person') {
+    properties.email = {
+      type: 'string',
+      format: 'email',
+      description: 'Only when the team is away: an email address the visitor gave for a reply.',
+    };
+  }
+
+  return {
+    name,
+    description,
+    inputSchema: { type: 'object', properties, required: ['target', 'reason', 'summary'] },
+    // A write: what the visitor said leaves the site. The harness confirms before it runs.
+    annotations: { readOnlyHint: false, consequentialHint: true },
+    execute: async (input: Record<string, unknown>) => {
+      const conversationId = opts.conversationId();
+      if (!conversationId) return text('There is no conversation to hand off.', true);
+      const current = (await controller.targets()).find((t) => t.name === String(input?.target ?? ''));
+      if (!current || current.kind !== kind) {
+        return text(`"${String(input?.target ?? '')}" is not someone this conversation can be handed to.`, true);
+      }
+      const email = typeof input.email === 'string' ? input.email.trim() : '';
+      if (!current.available && !email) {
+        return text(
+          `${current.label} is ${availability(current)}. Ask the visitor for an email address to reply to, then call ${name} again with it.`,
+          true,
+        );
+      }
+      const envelope = buildEnvelope({
+        target: current.name,
+        reason: String(input.reason ?? ''),
+        summary: String(input.summary ?? ''),
+        conversationId,
+        contact: email ? { email } : undefined,
+        transcript: current.transcript ? opts.transcript?.() : undefined,
+      });
+      try {
+        await controller.start(conversationId, current.name, envelope);
+      } catch {
+        const session = controller.session(conversationId);
+        return text(session?.error ?? `I couldn't reach ${current.label}.`, true);
+      }
+      const waiting = current.kind === 'person' && current.available ? ` ${current.label} will reply here.` : '';
+      const later = !current.available ? ` ${current.label} will reply to ${email}.` : '';
+      return {
+        content: [{ type: 'text', text: `Connecting you to ${current.label}.${waiting}${later}` }],
+        structuredContent: {
+          [HANDOFF_SESSION_RESULT]: { target: current.name, label: current.label, kind: current.kind },
+        },
+      };
+    },
+  } as ModelContextTool;
+}
+
+/**
+ * Register the handoff tools, replacing none that are already there.
+ *
+ * @returns The names registered.
+ */
+export async function registerHandoffTools(
+  mc: ModelContext,
+  controller: HandoffController,
+  opts: HandoffToolOptions,
+): Promise<string[]> {
+  const tools = await buildHandoffTools(controller, opts);
+  let present = new Set<string>();
+  try {
+    present = new Set((await mc.getTools()).map((t) => t.name));
+  } catch {
+    // A registry that cannot list may still register.
+  }
+  const registered: string[] = [];
+  for (const tool of tools) {
+    if (present.has(tool.name)) continue;
+    try {
+      await mc.registerTool(tool);
+      registered.push(tool.name);
+    } catch (err) {
+      console.warn(`[nxis-handoff] could not register ${tool.name}:`, err);
+    }
+  }
+  return registered;
+}

package/src/harness/harness.ts

@@ -39,6 +39,7 @@ import { decide, policyFor, type Decision } from './policy.js';
 import { buildPlan } from './plan.js';
 import { resolveSlots, summarySlots, type Resolution } from './slots.js';
 import { beginJourney, journeySteps, recordStep, type AgentStep } from './steps.js';
+import { HANDOFF_SESSION_RESULT, TALK_TO_A_PERSON_TOOL, isHandoffTool } from '../handoff/tools.js';
 import type { HarnessRenderer, StreamingBubble } from './renderer.js';
 
 /** Configuration for an {@link AgentHarness}. */
@@ -134,9 +135,11 @@ export interface TurnResult {
    * - `'handback'`, when the model named a tool this agent does not hold, with
    *   the name in {@link TurnResult.wanted};
    * - `'unavailable'`, when none of this agent's tools are on the page;
-   * - `'stopped'`, when the user cancelled the turn.
+   * - `'stopped'`, when the user cancelled the turn;
+   * - `'handoff'`, when the conversation is handed off and the message went to
+   *   the target instead (see {@link HandoffController}).
    */
-  decision: Decision | 'none' | 'handback' | 'unavailable' | 'stopped';
+  decision: Decision | 'none' | 'handback' | 'unavailable' | 'stopped' | 'handoff';
   /** The tool that was called, when one was. */
   tool?: ModelContextToolInfo;
   /** The arguments it was called with. */
@@ -180,6 +183,9 @@ export function narrateCall(
   if (!call) return WORKING_ON_IT;
   const tool = tools.find((t) => t.name === call.name);
   if (tool && policyFor(tool).readOnly) return 'Looking that up.';
+  if (isHandoffTool(call.name)) {
+    return call.name === TALK_TO_A_PERSON_TOOL ? "I can put you through to the team. Here's what I'd send them." : "I can hand you over. Here's what I'd send.";
+  }
   return `Filling in the ${humanize(call.name).toLowerCase()}.`;
 }
 
@@ -282,6 +288,8 @@ function handoffPrompt(
   tool: ModelContextToolInfo,
   values: Record<string, unknown>,
 ): { submitLabel?: string; destination?: string } {
+  // Handing the conversation to someone: what is pressed is Send, and nothing is submitted.
+  if (isHandoffTool(tool.name)) return { submitLabel: 'Send' };
   const handoff = handoffFor(tool, values);
   return handoff ? { submitLabel: 'Open & submit', destination: handoff.label } : {};
 }
@@ -865,8 +873,11 @@ export class AgentHarness {
     // Recorded before the call, because the call is what navigates: the
     // courier persists the journey as it leaves, and this step has to be in
     // it or the page it lands on shows no reason for being there.
+    const handing = isHandoffTool(tool.name);
     this.emitStep(
-      leaving
+      handing
+        ? { id: 'fill', label: 'Handing the conversation over', status: 'active' }
+        : leaving
         ? { id: 'navigate', label: `Opening ${leaving.label}`, status: 'active' }
         : {
             id: 'fill',
@@ -915,6 +926,20 @@ export class AgentHarness {
         return;
       }
 
+      // Handed off: what the target says arrives through the handoff controller's events, which the
+      // renderer draws. There is nothing to show as "Submitted"; the model learns where it went.
+      const started = res?.structuredContent?.[HANDOFF_SESSION_RESULT] as { label?: string } | undefined;
+      if (handing && started) {
+        const who = started.label ?? 'another agent';
+        this.emitStep({ id: 'fill', label: `Handed to ${who}`, status: 'done' });
+        messages.push({
+          role: 'user',
+          content: `[${tool.name}: the conversation was handed to ${who}. Their replies go to the visitor directly.]`,
+        });
+        this.opts.onMessages?.(messages);
+        return;
+      }
+
       // Opening the page already open, or one that could not be told: said
       // in words, since there are no records to draw.
       if (tool.name === OPEN_PAGE_TOOL) {

package/src/harness/router/coordinator.ts

@@ -23,6 +23,7 @@
 import type { ChatMessage } from '../../types.js';
 import type { ModelProvider } from '../../providers/types.js';
 import type { AgentHarness, TurnResult } from '../harness.js';
+import type { HandoffController } from '../../handoff/controller.js';
 import { matchRoute, type RouteDecision, type RouteRule } from './rules.js';
 
 /** How a turn's agent was chosen. */
@@ -53,6 +54,18 @@ export interface CoordinatorOptions {
   descriptions?: Record<string, string>;
   /** Called with every routing decision, including corrections. */
   onRoute?(decision: RoutedTurn): void;
+  /**
+   * Handoffs to remote agents and people.
+   *
+   * While a conversation is handed off, its turns go to the target rather than
+   * to any agent here, and resolve with `decision: 'handoff'`. Routing returns
+   * to the agents when the target finishes or the visitor ends the handoff.
+   */
+  handoff?: {
+    controller: HandoffController;
+    /** The id the controller knows this conversation by. */
+    conversationId(messages: ChatMessage[]): string | undefined;
+  };
 }
 
 /** A routing decision, reported through {@link CoordinatorOptions.onRoute}. */
@@ -135,6 +148,14 @@ export class AgentCoordinator {
    * @returns The chosen agent's {@link TurnResult}.
    */
   async turn(goal: string, messages: ChatMessage[]): Promise<TurnResult> {
+    // A handed-off conversation belongs to its target until it hands back.
+    const handoff = this.opts.handoff;
+    const conversationId = handoff?.conversationId(messages);
+    if (handoff && handoff.controller.active(conversationId)) {
+      await handoff.controller.send(conversationId!, goal);
+      return { decision: 'handoff' };
+    }
+
     let routed = this.route(goal, messages);
 
     // The model is only asked when nothing cheaper had an opinion.

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/index.ts

@@ -175,6 +175,9 @@ export { loadSiteActions, parseAction } 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,