@nxisai/agent-harness 0.6.0 → 0.8.0

package/src/harness/harness.ts

@@ -39,6 +39,8 @@ 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 { extractRecords } from './records.js';
+import { recommend, type ResultPick } from './recommend.js';
 import { HANDOFF_SESSION_RESULT, TALK_TO_A_PERSON_TOOL, isHandoffTool } from '../handoff/tools.js';
 import type { HarnessRenderer, StreamingBubble } from './renderer.js';
 
@@ -111,6 +113,15 @@ export interface HarnessOptions {
    * Defaults to true. Pass false to ask one question at a time.
    */
   groupRelated?: boolean;
+  /**
+   * Whether a search that finds several records ends with a recommendation:
+   * the model picks one and gives reasons, and only reasons the record backs
+   * are kept (see `recommend`). Defaults to true. Costs one more completion
+   * per search.
+   */
+  recommend?: boolean;
+  /** The clock "open now" is judged by. For tests. */
+  now?: () => Date;
   /** Called whenever the conversation changes, for hosts that persist it. */
   onMessages?(messages: ChatMessage[]): void;
 }
@@ -323,6 +334,8 @@ export class AgentHarness {
   /** The previous request's system prompt and tool names, for the cache hint. */
   private lastPrompt = '';
   private lastTools = '';
+  /** What the visitor asked this turn, for a recommendation to answer. */
+  private goal = '';
 
   constructor(opts: HarnessOptions) {
     this.provider = opts.provider ?? new LocalGemmaProvider();
@@ -434,6 +447,7 @@ export class AgentHarness {
     // rather than the previous turn's.
     this.abort?.abort();
     this.abort = new AbortController();
+    this.goal = goal;
     this.renderer.stoppable?.(true);
 
     // Opened before the model is touched: loading weights is the longest
@@ -766,12 +780,14 @@ export class AgentHarness {
       detail: resolution.missing.map((s) => humanize(s.name).toLowerCase()).join(', '),
     });
     const plan = buildPlan(resolution.missing, this.opts.groupRelated !== false);
-    this.renderer.message(
-      'assistant',
-      plan.stepped
-        ? `I need ${plan.steps.length} more details for ${humanize(tool.name)}.`
-        : `One more thing for ${humanize(tool.name)}.`,
-    );
+    if (!this.renderer.inlinePrompts) {
+      this.renderer.message(
+        'assistant',
+        plan.stepped
+          ? `I need ${plan.steps.length} more details for ${humanize(tool.name)}.`
+          : `One more thing for ${humanize(tool.name)}.`,
+      );
+    }
     this.renderer.ask({
       tool,
       plan,
@@ -832,6 +848,35 @@ export class AgentHarness {
     this.renderer.step?.(step, journeySteps());
   }
 
+  /**
+   * The record to recommend from a search's results, when there are several
+   * to choose between and the model can say why from what they state.
+   */
+  private async pickFrom(res: ModelContextToolResponse): Promise<{ pick: ResultPick; name: string } | null> {
+    if (this.opts.recommend === false || !this.goal) return null;
+    // Records of things, not rows of a type listing: something with a name and a kind.
+    const records = extractRecords(res).filter((r) => typeof r.name === 'string' && r['@type'] != null);
+    if (records.length < 2) return null;
+    const bubble = this.renderer.streaming();
+    bubble.thinking('Comparing them…');
+    try {
+      const pick = await recommend({
+        provider: this.provider,
+        goal: this.goal,
+        records,
+        now: this.opts.now?.(),
+        signal: this.abort?.signal,
+        transcribe: withTranscribedCall,
+      });
+      return pick ? { pick, name: String(records[pick.index].name) } : null;
+    } catch {
+      // Stopped, or the model failed: the results stand on their own.
+      return null;
+    } finally {
+      bubble.finalize('');
+    }
+  }
+
   /** Discard a live prompt and the values typed into it. */
   private cancel(): void {
     // A journey that stops here should say so, not sit waiting for a press
@@ -874,17 +919,23 @@ export class AgentHarness {
     // 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(
-      handing
-        ? { id: 'fill', label: 'Handing the conversation over', status: 'active' }
-        : leaving
+    const inFlight: AgentStep = handing
+      ? { id: 'fill', label: 'Handing the conversation over', status: 'active' }
+      : leaving
         ? { id: 'navigate', label: `Opening ${leaving.label}`, status: 'active' }
         : {
             id: 'fill',
             label: readOnly ? 'Looking that up' : `Filling ${humanize(tool.name)}`,
             status: 'active',
-          },
-    );
+          };
+    this.emitStep(inFlight);
+    // A failure ends the step that was running, so the card never shows it still under way.
+    const failed = (detail: string) => {
+      this.emitStep({ ...inFlight, label: 'It did not go through', status: 'failed', detail });
+      // The model reads why on its next turn, and can act on it rather than repeat the call.
+      messages.push({ role: 'user', content: `[${tool.name} did not go through: ${detail.slice(0, 400)}]` });
+      this.opts.onMessages?.(messages);
+    };
     try {
       const res: ModelContextToolResponse = await this.toolSource.execTool(tool, tool.name, values);
       const text = extractResult(res);
@@ -900,7 +951,7 @@ export class AgentHarness {
       });
 
       if (res?.isError) {
-        this.emitStep({ id: 'submit', label: 'It did not go through', status: 'failed', detail: text });
+        failed(text || 'Failed');
         this.renderer.toolError(tool, text || 'Failed');
         return;
       }
@@ -915,6 +966,11 @@ export class AgentHarness {
         // Said from what we know, not from what came back: a registry may
         // return the whole response object as JSON, and that is not a
         // sentence to put in front of anyone.
+        if (this.renderer.left) {
+          const carried = res?.structuredContent?.[HANDOFF_RESULT] as { label?: string } | undefined;
+          this.renderer.left(tool, (visiting ?? leaving)?.label ?? carried?.label ?? null);
+          return;
+        }
         this.renderer.message(
           'assistant',
           visiting
@@ -931,7 +987,10 @@ export class AgentHarness {
       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' });
+        // Handing over is where this journey ends; the conversation carries on outside it. Without a
+        // `submit` step the card would read as running for as long as the handoff lasts.
+        this.emitStep({ id: 'fill', label: 'Handed the conversation over', status: 'done' });
+        this.emitStep({ id: 'submit', 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.]`,
@@ -958,8 +1017,14 @@ export class AgentHarness {
       });
 
       if (readOnly) {
-        this.renderer.results(tool, res);
-        messages.push({ role: 'user', content: `[${tool.name} returned: ${text.slice(0, 400)}]` });
+        const picked = await this.pickFrom(res);
+        this.renderer.results(tool, res, picked ? { pick: picked.pick } : undefined);
+        messages.push({
+          role: 'user',
+          content:
+            `[${tool.name} returned: ${text.slice(0, 400)}]` +
+            (picked ? ` [You recommended ${picked.name}: ${picked.pick.reasons.join(' ')}]` : ''),
+        });
       } else {
         this.renderer.detail(tool, values, text);
         messages.push({
@@ -970,7 +1035,7 @@ export class AgentHarness {
       this.opts.onMessages?.(messages);
     } catch (err) {
       const message = String((err as Error)?.message || err);
-      this.emitStep({ id: 'submit', label: 'It did not go through', status: 'failed', detail: message });
+      failed(message);
       working.finalize('');
       this.renderer.status('');
       // A call that threw is the main reason to open a trace.

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. */
@@ -195,6 +206,28 @@ export interface HarnessRenderer {
   /** Tear down any live ask or confirm UI. */
   dismissPrompt?(): void;
 
+  /**
+   * Whether this renderer's ask and confirm prompts say for themselves what
+   * they need and where they go.
+   *
+   * When true, the harness adds no "One more thing for …" line of its own
+   * before an ask: the prompt already reads as the assistant speaking.
+   */
+  inlinePrompts?: boolean;
+
+  /**
+   * A confirmed call is leaving for the page that can submit it.
+   *
+   * Called instead of the harness's own "Opening … to submit this…" message,
+   * for a renderer that shows the departure on the prompt the visitor just
+   * confirmed. The page it opens finishes the call.
+   *
+   * @param tool - The tool whose call is travelling.
+   * @param destination - The page it is going to, named for the visitor, or
+   * null when the harness cannot tell which.
+   */
+  left?(tool: ModelContextToolInfo, destination: string | null): void;
+
   /**
    * Report whether the turn can still be stopped.
    *