@nxisai/agent-harness 0.7.0 → 0.9.0

package/src/harness/recommend.ts

@@ -0,0 +1,194 @@
+/**
+ * Recommending one result, with reasons the records support.
+ *
+ * After a search returns several records, the visitor's next question is
+ * nearly always "which one?". The model answers it in one more completion:
+ * it picks a record and gives a short lead and up to three reasons. Then the
+ * harness checks every reason against the facts of the record it picked. A
+ * number the record does not state, or a reason that shares no words with
+ * it, is dropped. A pick with no reason left is no pick at all, and the
+ * renderer shows the plain list instead.
+ *
+ * The model chooses and words it; the records decide what may be said.
+ *
+ * @module
+ */
+import type { ChatMessage } from '../engine.js';
+import type { Completion, ModelProvider } from '../providers/types.js';
+import type { ModelContextToolInfo } from '../types.js';
+import { factLines, recordFacts, type RecordFacts } from './records.js';
+
+/** The tool the model answers through. Never registered anywhere: offered for this one completion. */
+export const RECOMMEND_TOOL = 'recommend';
+
+/** A recommendation the renderer can show. */
+export interface ResultPick {
+  /** The picked record's position in the results, from 0. */
+  index: number;
+  /** Its key: `@id`, else its name. */
+  key: string;
+  /** One sentence for the visitor, naming it. */
+  lead: string;
+  /** Up to three reasons, each backed by the record. */
+  reasons: string[];
+}
+
+/** What {@link recommend} needs. */
+export interface RecommendRequest {
+  provider: ModelProvider;
+  /** What the visitor asked. */
+  goal: string;
+  /** The records, in the order the results show them. */
+  records: Record<string, unknown>[];
+  /** The time "open now" is judged at. Defaults to now. */
+  now?: Date;
+  signal?: AbortSignal;
+  /** Reads a call the model wrote out as text. */
+  transcribe?: (c: Completion) => Completion;
+  /** How many records the model compares. Defaults to eight. */
+  limit?: number;
+}
+
+const TOOL: ModelContextToolInfo = {
+  name: RECOMMEND_TOOL,
+  description: 'Recommend the one result that best fits what the visitor asked, with reasons taken from that result.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      pick: { type: 'integer', description: 'The number of the result you recommend.' },
+      lead: { type: 'string', description: 'One short sentence for the visitor, naming it and saying why.' },
+      reasons: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Two or three short reasons, each restating a fact listed for that result.',
+      },
+    },
+    required: ['pick', 'lead', 'reasons'],
+  },
+} as ModelContextToolInfo;
+
+const WEEKDAY = new Intl.DateTimeFormat('en-US', { weekday: 'long', hour: 'numeric', minute: '2-digit' });
+
+/**
+ * Ask the model which result fits, and keep only what the record supports.
+ *
+ * @returns The pick, or null when the model gave none, picked a result that
+ * does not exist, or gave no reason the record backs.
+ */
+export async function recommend(req: RecommendRequest): Promise<ResultPick | null> {
+  const now = req.now ?? new Date();
+  const records = req.records.slice(0, req.limit ?? 8);
+  if (records.length < 2) return null;
+  const facts = records.map((r) => recordFacts(r, now));
+  const listing = facts.map((f, i) => `${i + 1}. ${f.name}\n${factLines(f).map((l) => `   - ${l}`).join('\n')}`).join('\n');
+
+  const messages: ChatMessage[] = [
+    {
+      role: 'system',
+      content: [
+        'You help a website visitor choose between search results.',
+        `Call ${RECOMMEND_TOOL} once: pick is the number of the result that best fits what they asked; lead is one short sentence that names it and says why; reasons are two or three short reasons.`,
+        'Every reason must restate a fact listed for the result you pick. Do not add facts, prices, times or numbers that are not listed.',
+        'If they need help now, prefer one that is open now.',
+      ].join(' '),
+    },
+    {
+      role: 'user',
+      content: `The visitor asked: "${req.goal}"\nIt is now ${WEEKDAY.format(now)}.\n\nResults:\n${listing}`,
+    },
+  ];
+
+  let completion: Completion;
+  try {
+    completion = await req.provider.complete({ messages, tools: [TOOL], signal: req.signal, maxTokens: 300 });
+  } catch (err) {
+    if (req.signal?.aborted) throw err;
+    console.warn('[nxis-agent] recommendation failed:', err);
+    return null;
+  }
+  if (req.transcribe) completion = req.transcribe(completion);
+  const args = completion.call?.name === RECOMMEND_TOOL ? completion.call.args : readJson(completion.text);
+  if (!args) return null;
+
+  const index = Number(args.pick) - 1;
+  const picked = facts[index];
+  if (!Number.isInteger(index) || !picked) return null;
+  const others = facts.filter((_, i) => i !== index).map((f) => f.name.toLowerCase());
+  const reasons = (Array.isArray(args.reasons) ? args.reasons : [])
+    .map((r) => String(r ?? '').trim())
+    .filter((r) => r && r.length <= 200 && grounded(r, picked, others))
+    .slice(0, 3);
+  if (!reasons.length) return null;
+
+  const said = String(args.lead ?? '').trim();
+  const lead = said && said.length <= 200 && mentions(said, picked.name) && grounded(said, picked, others) ? said : `I'd go with ${picked.name}.`;
+  return { index, key: picked.key, lead, reasons };
+}
+
+/** A call written as plain JSON: `{"pick": 1, …}`. */
+function readJson(text: string): Record<string, unknown> | null {
+  const m = text.match(/\{[\s\S]*\}/);
+  if (!m) return null;
+  try {
+    const v = JSON.parse(m[0]);
+    return v && typeof v === 'object' ? (v as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+const STOP = new Set(
+  'about after also and are around been best both but can come does done each even from good great have here into just like more most much need only open other over same some than that their them then there these they this those very well were what when where which while will with would your'.split(
+    ' ',
+  ),
+);
+
+/** The words worth matching: four letters or more, not filler, roughly stemmed. */
+function words(text: string): string[] {
+  return (text.toLowerCase().match(/[a-z][a-z'-]{3,}/g) ?? []).filter((w) => !STOP.has(w)).map(stem);
+}
+
+const stem = (w: string): string => w.replace(/'s$/, '').replace(/(ing|ers|ed|es|s)$/, '').slice(0, 7);
+
+/** The record's facts as one searchable text. */
+function factText(f: RecordFacts): string {
+  return [f.name, ...factLines(f)].join(' ').toLowerCase();
+}
+
+/**
+ * Whether a sentence says only what the record says.
+ *
+ * Every number in it must appear in the record ("4.7", "412", "40", "24/7");
+ * it must share at least one meaningful word with the record; and it must
+ * not be about another result.
+ */
+export function grounded(sentence: string, f: RecordFacts, others: string[] = []): boolean {
+  const text = factText(f);
+  const lower = sentence.toLowerCase();
+  if (others.some((name) => name && lower.includes(name))) return false;
+  const numbers = lower.match(/\d+(?:[.:]\d+)?/g) ?? [];
+  const numberText = text.replace(/,/g, '');
+  if (!numbers.every((n) => numberText.includes(n))) return false;
+  // Hours are claims about now, checked against the hours rather than the words:
+  // every record says "open" somewhere, closed ones too.
+  const always = ALWAYS.test(lower);
+  const now = OPEN_NOW.test(lower);
+  if (always && !(f.status?.always || /24\/7|24 hours/.test(text))) return false;
+  if (now && !f.status?.open) return false;
+  if (always || now) return true;
+  const known = new Set(words(text));
+  return words(sentence).some((w) => known.has(w));
+}
+
+/** A claim that it never closes. */
+const ALWAYS = /24\/7|24 hours|around the clock|day (?:or|and) night|any ?time/;
+/** A claim that it is open at this moment. */
+const OPEN_NOW = /\bopen (?:right )?now\b|\bright now\b|\bopen today\b|\bstill open\b/;
+
+/** Whether a sentence names the record: its full name, or its first distinctive word. */
+function mentions(sentence: string, name: string): boolean {
+  const lower = sentence.toLowerCase();
+  if (lower.includes(name.toLowerCase())) return true;
+  const first = words(name).find((w) => w.length >= 4);
+  return !!first && words(sentence).includes(first);
+}

package/src/harness/records.ts

@@ -0,0 +1,237 @@
+/**
+ * The records a read tool returned, and what each one says as plain facts.
+ *
+ * A typed-retrieval result reaches the harness in many wrappings: structured
+ * content, JSON text, or the whole response serialized again by an extension
+ * in the loop. {@link extractRecords} digs the record list out of any of them.
+ * {@link recordFacts} then reads one schema.org record into the facts a
+ * person compares businesses by: whether it is open now, its rating, what it
+ * does, what reviewers said. Those facts are what a recommendation may cite,
+ * and nothing else.
+ *
+ * @module
+ */
+import type { ModelContextToolResponse } from '../types.js';
+
+type Obj = Record<string, unknown>;
+
+const isObj = (v: unknown): v is Obj => !!v && typeof v === 'object' && !Array.isArray(v);
+
+/**
+ * The records in a read tool's response, wherever they are.
+ *
+ * @param res - The response, or its text.
+ * @returns The records, as the server sent them; empty when there are none.
+ */
+export function extractRecords(res: ModelContextToolResponse | string | null | undefined): Obj[] {
+  const sources: unknown[] = [];
+  // Every candidate payload, unwrapping response envelopes: structured
+  // content and each text part, parsed as JSON, possibly encoded twice.
+  const visit = (raw: unknown, depth = 0): void => {
+    if (raw == null || depth > 5) return;
+    if (typeof raw === 'string') {
+      const t = raw.trim();
+      if (!t) return;
+      try {
+        visit(JSON.parse(t), depth + 1);
+      } catch {
+        // Plain text: nothing to extract.
+      }
+      return;
+    }
+    if (typeof raw !== 'object') return;
+    sources.push(raw);
+    const v = raw as Obj;
+    if (v.structuredContent != null) visit(v.structuredContent, depth + 1);
+    if (Array.isArray(v.content)) {
+      for (const c of v.content) if (isObj(c)) visit(c.text, depth + 1);
+    }
+  };
+  visit(res);
+  for (const data of sources) {
+    const items = itemsFrom(data);
+    if (items.length) return items;
+  }
+  return [];
+}
+
+/** The record array within one parsed payload. */
+function itemsFrom(data: unknown): Obj[] {
+  const objs = (arr: unknown[]) => arr.filter(isObj);
+  if (Array.isArray(data)) return objs(data);
+  if (!isObj(data)) return [];
+  for (const key of ['results', 'types', 'items', 'entities', 'data']) {
+    if (Array.isArray(data[key])) return objs(data[key] as unknown[]);
+  }
+  if (isObj(data.result)) return [data.result];
+  if (data['@id'] != null || data['@type'] != null || data.name != null) return [data];
+  return [];
+}
+
+// ── Opening hours ───────────────────────────────────────────────────────────
+
+const DAYS = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+const SHORT: Record<string, number> = { su: 0, mo: 1, tu: 2, we: 3, th: 4, fr: 5, sa: 6 };
+
+/** Minutes after midnight: "07:30" → 450. */
+function minutes(hhmm: unknown): number | null {
+  const m = String(hhmm ?? '').match(/^(\d{1,2}):(\d{2})/);
+  return m ? Number(m[1]) * 60 + Number(m[2]) : null;
+}
+
+/** "7am", "5:30pm", "noon". */
+function clock(mins: number): string {
+  const h = Math.floor(mins / 60) % 24;
+  const m = mins % 60;
+  if (h === 12 && m === 0) return 'noon';
+  const suffix = h < 12 ? 'am' : 'pm';
+  const h12 = h % 12 || 12;
+  return m ? `${h12}:${String(m).padStart(2, '0')}${suffix}` : `${h12}${suffix}`;
+}
+
+/** Each day's opening spans, [opens, closes] in minutes; index 0 is Sunday. */
+function weekOf(entity: Obj): [number, number][][] | null {
+  const week: [number, number][][] = DAYS.map(() => []);
+  let any = false;
+  const spec = entity.openingHoursSpecification;
+  for (const s of Array.isArray(spec) ? spec : spec ? [spec] : []) {
+    if (!isObj(s)) continue;
+    const opens = minutes(s.opens);
+    const closes = minutes(s.closes);
+    if (opens === null || closes === null) continue;
+    const days = Array.isArray(s.dayOfWeek) ? s.dayOfWeek : [s.dayOfWeek];
+    for (const d of days) {
+      const i = DAYS.findIndex((name) => String(d ?? '').replace(/^.*[/#]/, '').toLowerCase() === name.toLowerCase());
+      if (i >= 0) {
+        week[i].push([opens, closes]);
+        any = true;
+      }
+    }
+  }
+  // The compact form: "Mo-Fr 07:00-17:00", "Sa 08:00-13:00", "Mo-Su 00:00-23:59".
+  const compact = entity.openingHours;
+  for (const line of Array.isArray(compact) ? compact : compact ? String(compact).split(/[;,](?=\s*[A-Z][a-z])/) : []) {
+    const m = String(line).trim().match(/^([A-Za-z]{2})(?:-([A-Za-z]{2}))?\s+(\d{1,2}:\d{2})-(\d{1,2}:\d{2})$/);
+    if (!m) continue;
+    const from = SHORT[m[1].toLowerCase()];
+    const to = m[2] ? SHORT[m[2].toLowerCase()] : from;
+    if (from === undefined || to === undefined) continue;
+    for (let d = from; ; d = (d + 1) % 7) {
+      week[d].push([minutes(m[3])!, minutes(m[4])!]);
+      any = true;
+      if (d === to) break;
+    }
+  }
+  return any ? week : null;
+}
+
+/** Whether a business is open at a time, and how a visitor should read it. */
+export interface OpenStatus {
+  open: boolean;
+  /** "Open now · 24/7", "Open now · until 5pm", "Opens 7am", "Opens Mon 7am". */
+  label: string;
+  /** Open every hour of every day. */
+  always: boolean;
+}
+
+/**
+ * Whether a record's business is open at `now`, read from its opening hours.
+ *
+ * @returns Null when the record states no hours this can read.
+ */
+export function openStatus(entity: Obj, now: Date = new Date()): OpenStatus | null {
+  const week = weekOf(entity);
+  if (!week) return null;
+  const always = week.every((spans) => spans.some(([o, c]) => o === 0 && c >= 23 * 60 + 59));
+  if (always) return { open: true, label: 'Open now · 24/7', always: true };
+  const day = now.getDay();
+  const at = now.getHours() * 60 + now.getMinutes();
+  const current = week[day].find(([o, c]) => at >= o && at < c);
+  if (current) return { open: true, label: `Open now · until ${clock(current[1])}`, always: false };
+  // The next opening, today later or on a following day.
+  for (let ahead = 0; ahead < 7; ahead++) {
+    const d = (day + ahead) % 7;
+    const next = week[d].filter(([o]) => ahead > 0 || o > at).sort((a, b) => a[0] - b[0])[0];
+    if (!next) continue;
+    // Today or tomorrow reads as a time alone; further off, with the day.
+    return { open: false, label: ahead <= 1 ? `Opens ${clock(next[0])}` : `Opens ${DAYS[d].slice(0, 3)} ${clock(next[0])}`, always: false };
+  }
+  return { open: false, label: 'Closed', always: false };
+}
+
+// ── Facts ───────────────────────────────────────────────────────────────────
+
+/** One record, as the facts a visitor compares by. */
+export interface RecordFacts {
+  /** Its `@id`, else its name: what a pick refers to. */
+  key: string;
+  name: string;
+  type?: string;
+  status?: OpenStatus;
+  rating?: number;
+  reviewCount?: number;
+  phone?: string;
+  /** Services it offers, by name, with their one-line descriptions. */
+  services: { name: string; description?: string }[];
+  /** What it says it specializes in. */
+  knows: string[];
+  description?: string;
+  /** What reviewers wrote, with who wrote it. */
+  reviews: { text: string; author?: string }[];
+  /** The year it was founded. */
+  since?: number;
+  /** ZIP codes or places it serves. */
+  area: string[];
+}
+
+const str = (v: unknown): string => (v == null ? '' : String(Array.isArray(v) ? v[0] : v)).trim();
+const list = (v: unknown): unknown[] => (Array.isArray(v) ? v : v == null ? [] : [v]);
+
+/** A schema.org record as plain facts. */
+export function recordFacts(entity: Obj, now: Date = new Date()): RecordFacts {
+  const name = str(entity.name ?? entity.title ?? entity.headline) || 'This result';
+  const rating = isObj(entity.aggregateRating) ? Number(entity.aggregateRating.ratingValue) : NaN;
+  const count = isObj(entity.aggregateRating) ? Number(entity.aggregateRating.reviewCount ?? entity.aggregateRating.ratingCount) : NaN;
+  const services = list(entity.makesOffer)
+    .map((o) => (isObj(o) && isObj(o.itemOffered) ? o.itemOffered : isObj(o) ? o : null))
+    .filter(isObj)
+    .map((s) => ({ name: str(s.name), description: str(s.description) || undefined }))
+    .filter((s) => s.name);
+  const reviews = list(entity.review)
+    .filter(isObj)
+    .map((r) => ({ text: str(r.reviewBody ?? r.description), author: isObj(r.author) ? str(r.author.name) || undefined : str(r.author) || undefined }))
+    .filter((r) => r.text);
+  const founded = str(entity.foundingDate).match(/^(\d{4})/);
+  const status = openStatus(entity, now) ?? undefined;
+  return {
+    key: str(entity['@id']) || name,
+    name,
+    type: str(entity['@type']).replace(/^.*[/#]/, '') || undefined,
+    ...(status ? { status } : {}),
+    ...(Number.isFinite(rating) ? { rating } : {}),
+    ...(Number.isFinite(count) ? { reviewCount: count } : {}),
+    ...(str(entity.telephone) ? { phone: str(entity.telephone) } : {}),
+    services,
+    knows: list(entity.knowsAbout).map(str).filter(Boolean),
+    ...(str(entity.description) ? { description: str(entity.description) } : {}),
+    reviews,
+    ...(founded ? { since: Number(founded[1]) } : {}),
+    area: list(entity.areaServed).map((a) => (isObj(a) ? str(a.name ?? a.postalCode) : str(a))).filter(Boolean),
+  };
+}
+
+/** The facts as lines a model reads, and a recommendation is checked against. */
+export function factLines(f: RecordFacts): string[] {
+  const lines: string[] = [];
+  if (f.type) lines.push(f.type);
+  if (f.status) lines.push(f.status.label);
+  if (f.rating !== undefined) lines.push(`Rated ${f.rating}${f.reviewCount !== undefined ? ` from ${f.reviewCount} reviews` : ''}`);
+  if (f.since) lines.push(`In business since ${f.since}`);
+  if (f.services.length) lines.push(`Services: ${f.services.map((s) => (s.description ? `${s.name} (${s.description})` : s.name)).join('; ')}`);
+  if (f.knows.length) lines.push(`Specializes in: ${f.knows.join(', ')}`);
+  if (f.description) lines.push(f.description);
+  for (const r of f.reviews.slice(0, 2)) lines.push(`Review: "${r.text}"${r.author ? ` (${r.author})` : ''}`);
+  if (f.area.length) lines.push(`Serves: ${f.area.join(', ')}`);
+  if (f.phone) lines.push(`Phone: ${f.phone}`);
+  return lines;
+}

package/src/harness/renderer.ts

@@ -13,6 +13,7 @@ import type { ModelContextToolInfo, ModelContextToolResponse } from '../types.js
 import type { ClarificationPlan } from './plan.js';
 import type { Resolution, Slot } from './slots.js';
 import type { AgentStep } from './steps.js';
+import type { ResultPick } from './recommend.js';
 
 /** One tool call and its response, for renderers that show their work. */
 export interface TraceEntry {
@@ -81,6 +82,16 @@ export interface StreamingBubble {
   finalize(text: string): void;
 }
 
+/** What the harness adds to a search's results. */
+export interface ResultsExtra {
+  /**
+   * The record the model recommends, with reasons the record backs. Absent
+   * when there was one result, the model gave no backed reason, or
+   * recommendations are off: show the results as a list.
+   */
+  pick?: ResultPick;
+}
+
 /** A write tool with every value resolved, awaiting a human press. */
 export interface ConfirmRequest {
   /** The tool about to be called. */
@@ -162,7 +173,7 @@ export interface HarnessRenderer {
   confirm(req: ConfirmRequest): void;
 
   /** A read tool returned records. */
-  results(tool: ModelContextToolInfo, res: ModelContextToolResponse): void;
+  results(tool: ModelContextToolInfo, res: ModelContextToolResponse, extra?: ResultsExtra): void;
   /** A write tool succeeded. */
   detail(tool: ModelContextToolInfo, values: Record<string, unknown>, text: string): void;
   /** A tool failed, or returned something that cannot be rendered. */

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

@@ -520,6 +520,47 @@ export function formOptions(tool: ModelContextToolInfo, values: Record<string, u
   return out;
 }
 
+/**
+ * The site forms that can be sent to a business, by its name: the site tools
+ * on this page whose choices include it.
+ *
+ * @returns Each form's tool name and what it is called ("quote form").
+ */
+export function formsFor(name: string): { tool: string; noun: string }[] {
+  const wanted = name.trim().toLowerCase();
+  if (!wanted) return [];
+  const out: { tool: string; noun: string }[] = [];
+  for (const [toolName, t] of built) {
+    if (t.choices?.some((c) => c.toLowerCase() === wanted)) {
+      out.push({ tool: toolName, noun: withoutSiteSuffix(toolName).replace(/[_-]+/g, ' ').trim().toLowerCase() });
+    }
+  }
+  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);