@nxisai/agent-harness 0.4.1 → 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;
+}