@nxisai/agent-harness 0.7.0 → 0.8.0

package/dist/ui/result-pick.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Search results as an answer: a recommended pick with its reasons, the
+ * others to compare against, or, when there is nothing to recommend, a short
+ * list that opens up per result.
+ *
+ * The pick comes from the harness (`recommend`): the model chose it and wrote
+ * the lead and reasons, and only reasons the record backs survived. Those are
+ * the only lines marked with a tick. Comparing another result shows that
+ * result's own facts, plainly, without a tick: the agent did not recommend it.
+ *
+ * Plain DOM, every string set as text.
+ *
+ * @module
+ */
+import type { ResultPick } from '../harness/recommend.js';
+/** One result, as the answer shows it. */
+export interface AnswerCard {
+    title: string;
+    stars?: number;
+    reviews?: number;
+    status?: {
+        open: boolean;
+        label: string;
+    };
+    phone?: string;
+    page?: {
+        url: string;
+        label: string;
+    };
+    /** What the record states, short: hours, rating, services, since when. */
+    facts: string[];
+    /** A site form that can be sent to it, and what to ask the agent to start it. */
+    form?: {
+        label: string;
+        message: string;
+    };
+}
+/** What the answer can ask the conversation to do. */
+export interface AnswerHandlers {
+    /** Send a message as the visitor: "Get a quote from Hatzel & Sons Plumbing". */
+    ask(text: string): void;
+}
+/**
+ * Draw the answer.
+ *
+ * @param cards - The results, in order.
+ * @param pick - The recommendation, when the harness made one.
+ */
+export declare function resultsAnswer(cards: AnswerCard[], pick: ResultPick | undefined, handlers: AnswerHandlers): HTMLElement;
+/** Styles, on the widget's tokens. */
+export declare const RESULTS_ANSWER_CSS = "\n      .results-answer { align-self: flex-start; width: min(100%, 440px); box-sizing: border-box; padding: 12px 14px; background: var(--surface); border: 1px solid var(--border); border-radius: 16px 16px 16px 4px; font-size: 14px; line-height: 1.5; color: var(--ink); white-space: normal; }\n      .ra-body { display: flex; flex-direction: column; gap: 12px; }\n      .ra-lead { margin: 0; }\n      .ra-pick { background: var(--bg); border: 1px solid var(--border-strong); border-radius: 14px; padding: 12px; display: flex; flex-direction: column; gap: 10px; }\n      .ra-pick.is-pick { border: 1.5px solid var(--blue); box-shadow: 0 0 0 4px var(--blue-tint); }\n      .ra-head { display: flex; align-items: center; gap: 10px; }\n      .ra-avatar { flex-shrink: 0; display: grid; place-items: center; color: #fff; font-weight: 700; letter-spacing: .02em; }\n      .ra-avatar.lg { width: 40px; height: 40px; border-radius: 12px; font-size: 13px; }\n      .ra-avatar.sm { width: 30px; height: 30px; border-radius: 9px; font-size: 11px; }\n      .ra-who { display: flex; flex-direction: column; gap: 1px; min-width: 0; flex-grow: 1; text-align: left; }\n      .ra-who strong { font-size: 14.5px; font-weight: 650; }\n      .ra-meta { font-size: 12.5px; color: var(--ink-2); }\n      .ra-meta strong { color: var(--ink); font-size: 12.5px; font-weight: 600; }\n      .ra-faint { color: var(--ink-3); }\n      .ra-open { color: var(--green-strong); font-weight: 600; }\n      .ra-reasons { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 6px; font-size: 13px; color: var(--ink-2); }\n      .ra-reasons li { display: flex; gap: 8px; align-items: flex-start; }\n      .ra-mark { width: 18px; height: 18px; flex-shrink: 0; border-radius: 50%; display: grid; place-items: center; font-size: 11px; font-weight: 700; color: var(--ink-3); }\n      .ra-reasons.ticked .ra-mark { background: var(--green-tint); color: var(--green-strong); }\n      .ra-actions { display: flex; flex-wrap: wrap; gap: 8px; }\n      .ra-btn { min-height: 40px; padding: 0 14px; border-radius: var(--radius-sm); border: 1px solid var(--border-strong); background: var(--bg); color: var(--ink); font: 600 13.5px var(--sans); display: inline-flex; align-items: center; justify-content: center; text-decoration: none; cursor: pointer; }\n      .ra-btn.primary { flex-grow: 1; border: 0; background: var(--blue); color: #fff; }\n      .ra-btn.primary:hover { background: var(--blue-strong); }\n      .ra-also { display: flex; flex-direction: column; gap: 6px; }\n      .ra-eyebrow { font-family: var(--mono); font-size: 10.5px; font-weight: 500; letter-spacing: .1em; text-transform: uppercase; color: var(--ink-3); }\n      .ra-row { display: flex; align-items: center; gap: 10px; width: 100%; padding: 8px 10px; border: 1px solid var(--border); border-radius: 10px; background: var(--bg); color: var(--ink); font: inherit; cursor: pointer; }\n      .ra-row:hover { border-color: var(--border-strong); }\n      .ra-row.plain { border: 0; border-radius: 0; padding: 10px 12px; }\n      .ra-chev { color: var(--ink-3); font-size: 17px; line-height: 1; }\n      .ra-link { align-self: flex-start; border: 0; background: none; padding: 0; font: 600 13px var(--sans); color: var(--blue-strong); cursor: pointer; }\n      .ra-list { background: var(--bg); border: 1px solid var(--border); border-radius: 12px; overflow: hidden; }\n      .ra-item + .ra-item { border-top: 1px solid var(--border); }\n      .ra-more { padding: 0 12px 12px 52px; display: flex; flex-direction: column; gap: 8px; }\n      .ra-showmore { width: 100%; min-height: 40px; border: 0; border-top: 1px solid var(--border); background: var(--bg); color: var(--blue-strong); font: 600 13px var(--sans); cursor: pointer; }\n      .ra-btn:focus-visible, .ra-row:focus-visible, .ra-link:focus-visible, .ra-showmore:focus-visible { outline: 2px solid var(--blue); outline-offset: 2px; }\n";
+//# sourceMappingURL=result-pick.d.ts.map

package/dist/ui/result-pick.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-pick.d.ts","sourceRoot":"","sources":["../../src/ui/result-pick.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAE1D,0CAA0C;AAC1C,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACtC,0EAA0E;IAC1E,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,iFAAiF;IACjF,IAAI,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3C;AAED,sDAAsD;AACtD,MAAM,WAAW,cAAc;IAC7B,gFAAgF;IAChF,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAuDD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE,UAAU,GAAG,SAAS,EAAE,QAAQ,EAAE,cAAc,GAAG,WAAW,CAuDtH;AA6CD,sCAAsC;AACtC,eAAO,MAAM,kBAAkB,i3HAoC9B,CAAC"}

package/dist/ui/result-pick.js

@@ -0,0 +1,196 @@
+function h(tag, attrs = {}, ...children) {
+    const el = document.createElement(tag);
+    for (const [k, v] of Object.entries(attrs)) {
+        if (v === undefined)
+            continue;
+        if (k === 'class')
+            el.className = v;
+        else
+            el.setAttribute(k, v);
+    }
+    for (const c of children)
+        if (c)
+            el.append(c);
+    return el;
+}
+const PALETTE = ['#0E4F5C', '#1D4ED8', '#6D28D9', '#9A3412', '#0F766E', '#B45309', '#334155'];
+/** Up to two letters, and a colour that stays the same for a name. */
+function avatar(name, size) {
+    const words = name.split(/\s+/).filter((w) => /^[\p{L}\p{N}]/u.test(w));
+    const ini = (words.slice(0, 2).map((w) => w[0]).join('') || '?').toUpperCase();
+    let hash = 0;
+    for (const ch of name)
+        hash = (hash * 31 + ch.charCodeAt(0)) >>> 0;
+    const el = h('span', { class: `ra-avatar ${size}`, 'aria-hidden': 'true' }, ini);
+    el.style.background = PALETTE[hash % PALETTE.length];
+    return el;
+}
+/** "★ 4.7 (412) · Open now · 24/7". */
+function meta(c) {
+    const line = h('span', { class: 'ra-meta' });
+    if (c.stars !== undefined) {
+        line.append(h('span', {}, `★ `, h('strong', {}, String(c.stars))));
+        if (c.reviews !== undefined)
+            line.append(h('span', { class: 'ra-faint' }, ` (${c.reviews})`));
+    }
+    if (c.status) {
+        if (line.childNodes.length)
+            line.append(' · ');
+        line.append(h('span', { class: c.status.open ? 'ra-open' : '' }, c.status.label));
+    }
+    return line;
+}
+function actions(c, handlers, primary) {
+    const row = h('div', { class: 'ra-actions' });
+    const tel = c.phone ? c.phone.replace(/[^\d+]/g, '') : '';
+    if (tel)
+        row.append(h('a', { class: `ra-btn ${primary ? 'primary' : ''}`, href: `tel:${tel}` }, `Call ${c.phone}`));
+    if (c.form) {
+        const b = h('button', { type: 'button', class: `ra-btn ${primary && !tel ? 'primary' : ''}` }, c.form.label);
+        b.addEventListener('click', () => handlers.ask(c.form.message));
+        row.append(b);
+    }
+    if (c.page)
+        row.append(h('a', { class: 'ra-btn', href: c.page.url }, 'Their page'));
+    return row;
+}
+/**
+ * Draw the answer.
+ *
+ * @param cards - The results, in order.
+ * @param pick - The recommendation, when the harness made one.
+ */
+export function resultsAnswer(cards, pick, handlers) {
+    const wrap = h('div', { class: 'msg assistant results-answer' });
+    const valid = pick && cards[pick.index] ? pick : undefined;
+    if (!valid) {
+        wrap.append(list(cards, handlers, 0));
+        return wrap;
+    }
+    let showing = valid.index;
+    const body = h('div', { class: 'ra-body' });
+    const draw = () => {
+        const c = cards[showing];
+        const mine = showing === valid.index;
+        const box = h('div', { class: `ra-pick ${mine ? 'is-pick' : ''}` });
+        const head = h('div', { class: 'ra-head' }, avatar(c.title, 'lg'), h('div', { class: 'ra-who' }, h('strong', {}, c.title), meta(c)));
+        box.append(head);
+        // Ticks only for what the agent recommended, and could back from the record.
+        const lines = mine ? valid.reasons : c.facts;
+        if (lines.length) {
+            const ul = h('ul', { class: `ra-reasons ${mine ? 'ticked' : ''}` });
+            lines.forEach((l) => ul.append(h('li', {}, h('span', { class: 'ra-mark', 'aria-hidden': 'true' }, mine ? '✓' : '•'), h('span', {}, l))));
+            box.append(ul);
+        }
+        box.append(actions(c, handlers, true));
+        const lead = mine ? h('p', { class: 'ra-lead' }, valid.lead) : h('p', { class: 'ra-lead' }, `Comparing ${c.title} with my pick, ${cards[valid.index].title}. `);
+        if (!mine) {
+            const back = h('button', { type: 'button', class: 'ra-link' }, 'Back to my pick');
+            back.addEventListener('click', () => {
+                showing = valid.index;
+                draw();
+            });
+            lead.append(back);
+        }
+        const others = cards.map((o, i) => ({ o, i })).filter(({ i }) => i !== showing).slice(0, 3);
+        const also = h('div', { class: 'ra-also' }, h('div', { class: 'ra-eyebrow' }, mine ? 'Also good · tap to compare' : 'Others'));
+        for (const { o, i } of others) {
+            const row = h('button', { type: 'button', class: 'ra-row' }, avatar(o.title, 'sm'), h('span', { class: 'ra-who' }, h('strong', {}, o.title), meta(o)), h('span', { class: 'ra-chev', 'aria-hidden': 'true' }, '›'));
+            row.addEventListener('click', () => {
+                showing = i;
+                draw();
+            });
+            also.append(row);
+        }
+        body.replaceChildren(lead, box, ...(others.length ? [also] : []));
+        if (cards.length > 4) {
+            const all = h('button', { type: 'button', class: 'ra-link' }, `Show all ${cards.length}`);
+            all.addEventListener('click', () => body.replaceChildren(list(cards, handlers, valid.index)));
+            body.append(all);
+        }
+    };
+    draw();
+    wrap.append(body);
+    return wrap;
+}
+/** The plain list: one line per result, each opening to its facts and actions. */
+function list(cards, handlers, open) {
+    const box = h('div', { class: 'ra-list' });
+    const SHOWN = 5;
+    let all = cards.length <= SHOWN + 1;
+    let openIndex = open;
+    const draw = () => {
+        box.replaceChildren();
+        cards.slice(0, all ? cards.length : SHOWN).forEach((c, i) => {
+            const expanded = openIndex === i;
+            const item = h('div', { class: 'ra-item' });
+            const id = `ra-${i}-${Math.random().toString(36).slice(2, 7)}`;
+            const row = h('button', { type: 'button', class: 'ra-row plain', 'aria-expanded': String(expanded), 'aria-controls': id }, avatar(c.title, 'sm'), h('span', { class: 'ra-who' }, h('strong', {}, c.title), meta(c)), h('span', { class: 'ra-chev', 'aria-hidden': 'true' }, expanded ? '−' : '+'));
+            row.addEventListener('click', () => {
+                openIndex = expanded ? null : i;
+                draw();
+            });
+            item.append(row);
+            if (expanded) {
+                const more = h('div', { class: 'ra-more', id });
+                if (c.facts.length) {
+                    const ul = h('ul', { class: 'ra-reasons' });
+                    c.facts.forEach((f) => ul.append(h('li', {}, h('span', { class: 'ra-mark', 'aria-hidden': 'true' }, '•'), h('span', {}, f))));
+                    more.append(ul);
+                }
+                more.append(actions(c, handlers, false));
+                item.append(more);
+            }
+            box.append(item);
+        });
+        if (!all) {
+            const more = h('button', { type: 'button', class: 'ra-showmore' }, `Show ${cards.length - SHOWN} more`);
+            more.addEventListener('click', () => {
+                all = true;
+                draw();
+            });
+            box.append(more);
+        }
+    };
+    draw();
+    return box;
+}
+/** Styles, on the widget's tokens. */
+export const RESULTS_ANSWER_CSS = `
+      .results-answer { align-self: flex-start; width: min(100%, 440px); box-sizing: border-box; padding: 12px 14px; background: var(--surface); border: 1px solid var(--border); border-radius: 16px 16px 16px 4px; font-size: 14px; line-height: 1.5; color: var(--ink); white-space: normal; }
+      .ra-body { display: flex; flex-direction: column; gap: 12px; }
+      .ra-lead { margin: 0; }
+      .ra-pick { background: var(--bg); border: 1px solid var(--border-strong); border-radius: 14px; padding: 12px; display: flex; flex-direction: column; gap: 10px; }
+      .ra-pick.is-pick { border: 1.5px solid var(--blue); box-shadow: 0 0 0 4px var(--blue-tint); }
+      .ra-head { display: flex; align-items: center; gap: 10px; }
+      .ra-avatar { flex-shrink: 0; display: grid; place-items: center; color: #fff; font-weight: 700; letter-spacing: .02em; }
+      .ra-avatar.lg { width: 40px; height: 40px; border-radius: 12px; font-size: 13px; }
+      .ra-avatar.sm { width: 30px; height: 30px; border-radius: 9px; font-size: 11px; }
+      .ra-who { display: flex; flex-direction: column; gap: 1px; min-width: 0; flex-grow: 1; text-align: left; }
+      .ra-who strong { font-size: 14.5px; font-weight: 650; }
+      .ra-meta { font-size: 12.5px; color: var(--ink-2); }
+      .ra-meta strong { color: var(--ink); font-size: 12.5px; font-weight: 600; }
+      .ra-faint { color: var(--ink-3); }
+      .ra-open { color: var(--green-strong); font-weight: 600; }
+      .ra-reasons { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 6px; font-size: 13px; color: var(--ink-2); }
+      .ra-reasons li { display: flex; gap: 8px; align-items: flex-start; }
+      .ra-mark { width: 18px; height: 18px; flex-shrink: 0; border-radius: 50%; display: grid; place-items: center; font-size: 11px; font-weight: 700; color: var(--ink-3); }
+      .ra-reasons.ticked .ra-mark { background: var(--green-tint); color: var(--green-strong); }
+      .ra-actions { display: flex; flex-wrap: wrap; gap: 8px; }
+      .ra-btn { min-height: 40px; padding: 0 14px; border-radius: var(--radius-sm); border: 1px solid var(--border-strong); background: var(--bg); color: var(--ink); font: 600 13.5px var(--sans); display: inline-flex; align-items: center; justify-content: center; text-decoration: none; cursor: pointer; }
+      .ra-btn.primary { flex-grow: 1; border: 0; background: var(--blue); color: #fff; }
+      .ra-btn.primary:hover { background: var(--blue-strong); }
+      .ra-also { display: flex; flex-direction: column; gap: 6px; }
+      .ra-eyebrow { font-family: var(--mono); font-size: 10.5px; font-weight: 500; letter-spacing: .1em; text-transform: uppercase; color: var(--ink-3); }
+      .ra-row { display: flex; align-items: center; gap: 10px; width: 100%; padding: 8px 10px; border: 1px solid var(--border); border-radius: 10px; background: var(--bg); color: var(--ink); font: inherit; cursor: pointer; }
+      .ra-row:hover { border-color: var(--border-strong); }
+      .ra-row.plain { border: 0; border-radius: 0; padding: 10px 12px; }
+      .ra-chev { color: var(--ink-3); font-size: 17px; line-height: 1; }
+      .ra-link { align-self: flex-start; border: 0; background: none; padding: 0; font: 600 13px var(--sans); color: var(--blue-strong); cursor: pointer; }
+      .ra-list { background: var(--bg); border: 1px solid var(--border); border-radius: 12px; overflow: hidden; }
+      .ra-item + .ra-item { border-top: 1px solid var(--border); }
+      .ra-more { padding: 0 12px 12px 52px; display: flex; flex-direction: column; gap: 8px; }
+      .ra-showmore { width: 100%; min-height: 40px; border: 0; border-top: 1px solid var(--border); background: var(--bg); color: var(--blue-strong); font: 600 13px var(--sans); cursor: pointer; }
+      .ra-btn:focus-visible, .ra-row:focus-visible, .ra-link:focus-visible, .ra-showmore:focus-visible { outline: 2px solid var(--blue); outline-offset: 2px; }
+`;
+//# sourceMappingURL=result-pick.js.map

package/dist/ui/result-pick.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-pick.js","sourceRoot":"","sources":["../../src/ui/result-pick.ts"],"names":[],"mappings":"AAsCA,SAAS,CAAC,CAAwC,GAAM,EAAE,QAA4C,EAAE,EAAE,GAAG,QAAiB;IAC5H,MAAM,EAAE,GAAG,QAAQ,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;IACvC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3C,IAAI,CAAC,KAAK,SAAS;YAAE,SAAS;QAC9B,IAAI,CAAC,KAAK,OAAO;YAAE,EAAE,CAAC,SAAS,GAAG,CAAC,CAAC;;YAC/B,EAAE,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC7B,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,QAAQ;QAAE,IAAI,CAAC;YAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAC9C,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,MAAM,OAAO,GAAG,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;AAE9F,sEAAsE;AACtE,SAAS,MAAM,CAAC,IAAY,EAAE,IAAiB;IAC7C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACxE,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;IAC/E,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,MAAM,EAAE,IAAI,IAAI;QAAE,IAAI,GAAG,CAAC,IAAI,GAAG,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACnE,MAAM,EAAE,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,aAAa,IAAI,EAAE,EAAE,aAAa,EAAE,MAAM,EAAE,EAAE,GAAG,CAAC,CAAC;IACjF,EAAE,CAAC,KAAK,CAAC,UAAU,GAAG,OAAO,CAAC,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,uCAAuC;AACvC,SAAS,IAAI,CAAC,CAAa;IACzB,MAAM,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;IAC7C,IAAI,CAAC,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC1B,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,QAAQ,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QACnE,IAAI,CAAC,CAAC,OAAO,KAAK,SAAS;YAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE,KAAK,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC;IAChG,CAAC;IACD,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC;QACb,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM;YAAE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC/C,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACpF,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,OAAO,CAAC,CAAa,EAAE,QAAwB,EAAE,OAAgB;IACxE,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC,CAAC;IAC9C,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1D,IAAI,GAAG;QAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,UAAU,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,GAAG,EAAE,EAAE,EAAE,QAAQ,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IACpH,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;QACX,MAAM,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC7G,CAAC,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,IAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QACjE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAChB,CAAC;IACD,IAAI,CAAC,CAAC,IAAI;QAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,YAAY,CAAC,CAAC,CAAC;IACpF,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,KAAmB,EAAE,IAA4B,EAAE,QAAwB;IACvG,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,8BAA8B,EAAE,CAAC,CAAC;IACjE,MAAM,KAAK,GAAG,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IAC3D,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC;QACtC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC;IAC1B,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;IAC5C,MAAM,IAAI,GAAG,GAAG,EAAE;QAChB,MAAM,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;QACzB,MAAM,IAAI,GAAG,OAAO,KAAK,KAAK,CAAC,KAAK,CAAC;QACrC,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,WAAW,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;QACpE,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACrI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACjB,6EAA6E;QAC7E,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;QAC7C,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;YACjB,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,cAAc,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;YACpE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACzI,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACjB,CAAC;QACD,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;QAEvC,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,aAAa,CAAC,CAAC,KAAK,kBAAkB,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;QAChK,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,iBAAiB,CAAC,CAAC;YAClF,IAAI,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE;gBAClC,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC;gBACtB,IAAI,EAAE,CAAC;YACT,CAAC,CAAC,CAAC;YACH,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC;QAED,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC5F,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,4BAA4B,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC/H,KAAK,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,MAAM,EAAE,CAAC;YAC9B,MAAM,GAAG,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;YACpN,GAAG,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE;gBACjC,OAAO,GAAG,CAAC,CAAC;gBACZ,IAAI,EAAE,CAAC;YACT,CAAC,CAAC,CAAC;YACH,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACnB,CAAC;QACD,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAClE,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,MAAM,GAAG,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,YAAY,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;YAC1F,GAAG,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAC9F,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACnB,CAAC;IACH,CAAC,CAAC;IACF,IAAI,EAAE,CAAC;IACP,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAClB,OAAO,IAAI,CAAC;AACd,CAAC;AAED,kFAAkF;AAClF,SAAS,IAAI,CAAC,KAAmB,EAAE,QAAwB,EAAE,IAAmB;IAC9E,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;IAC3C,MAAM,KAAK,GAAG,CAAC,CAAC;IAChB,IAAI,GAAG,GAAG,KAAK,CAAC,MAAM,IAAI,KAAK,GAAG,CAAC,CAAC;IACpC,IAAI,SAAS,GAAG,IAAI,CAAC;IACrB,MAAM,IAAI,GAAG,GAAG,EAAE;QAChB,GAAG,CAAC,eAAe,EAAE,CAAC;QACtB,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;YAC1D,MAAM,QAAQ,GAAG,SAAS,KAAK,CAAC,CAAC;YACjC,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;YAC5C,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;YAC/D,MAAM,GAAG,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,CAAC,QAAQ,CAAC,EAAE,eAAe,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YACnS,GAAG,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE;gBACjC,SAAS,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;gBAChC,IAAI,EAAE,CAAC;YACT,CAAC,CAAC,CAAC;YACH,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjB,IAAI,QAAQ,EAAE,CAAC;gBACb,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC;gBAChD,IAAI,CAAC,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;oBACnB,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC,CAAC;oBAC5C,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,EAAE,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;oBAC9H,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;gBAClB,CAAC;gBACD,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;gBACzC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACpB,CAAC;YACD,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACnB,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,MAAM,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,aAAa,EAAE,EAAE,QAAQ,KAAK,CAAC,MAAM,GAAG,KAAK,OAAO,CAAC,CAAC;YACxG,IAAI,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE;gBAClC,GAAG,GAAG,IAAI,CAAC;gBACX,IAAI,EAAE,CAAC;YACT,CAAC,CAAC,CAAC;YACH,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACnB,CAAC;IACH,CAAC,CAAC;IACF,IAAI,EAAE,CAAC;IACP,OAAO,GAAG,CAAC;AACb,CAAC;AAED,sCAAsC;AACtC,MAAM,CAAC,MAAM,kBAAkB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoCjC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nxisai/agent-harness",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "An on-device agent for the browser: a tool-calling harness over WebMCP and remote MCP, plus a drop-in chat UI. Decides whether to run a tool, ask for what's missing, or confirm before writing.",
   "type": "module",
   "main": "./dist/index.js",

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
@@ -834,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
@@ -974,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({

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);
+}