@nxisai/agent-harness 0.7.0 → 0.9.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.9.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/a2ui/cards.ts

@@ -12,6 +12,7 @@
  */
 
 import type { A2uiMessage } from './emit.js';
+import { actionCta, type CardAction } from '../harness/cta.js';
 
 const CATALOG = 'https://a2ui.org/specification/v1_0/catalogs/basic/catalog.json';
 
@@ -27,6 +28,8 @@ export interface ResultCardData {
   sub: string;
   tags: CardTag[];
   rows: CardRow[];
+  /** The record's own action, as at most one button. A list so a card without one draws nothing. */
+  actions: CardAction[];
 }
 
 const str = (v: unknown): string => (v == null ? '' : String(Array.isArray(v) ? v[0] : v));
@@ -93,7 +96,8 @@ export function toCardData(entity: Record<string, unknown>): ResultCardData {
     }
   }
 
-  return { title, sub, tags, rows };
+  const action = actionCta(entity, title);
+  return { title, sub, tags, rows, actions: action ? [action] : [] };
 }
 
 /** Fixed component set — independent of how many results there are. */
@@ -106,7 +110,7 @@ function cardComponents(heading: string): Component[] {
     { id: 'results', component: 'List',
       children: { path: '/results', componentId: 'card_tpl' }, direction: 'vertical' },
     { id: 'card_tpl', component: 'Card', child: 'card_body' },
-    { id: 'card_body', component: 'Column', children: ['card_title', 'card_tags', 'card_sub', 'card_rows'] },
+    { id: 'card_body', component: 'Column', children: ['card_title', 'card_tags', 'card_sub', 'card_rows', 'card_actions'] },
     // No bold: `weight` in this catalog is a flex weight (number), and Text
     // offers only variant caption/body. Title emphasis is not expressible in
     // the basic catalog: it needs a custom catalog or renderer styling.
@@ -124,6 +128,14 @@ function cardComponents(heading: string): Component[] {
     { id: 'row_tpl', component: 'Row', children: ['row_label', 'row_value'] },
     { id: 'row_label', component: 'Text', text: '${label}', variant: 'caption' },
     { id: 'row_value', component: 'Text', text: '${value}', variant: 'caption' },
+
+    // The record's action: zero or one per card, so a card without one draws nothing. Pressing it
+    // dispatches nxis.ask with the message to send as the visitor; it never submits anything itself.
+    { id: 'card_actions', component: 'List',
+      children: { path: 'actions', componentId: 'action_tpl' }, direction: 'horizontal' },
+    { id: 'action_tpl', component: 'Button', child: 'action_label', variant: 'primary',
+      action: { event: { name: 'nxis.ask', context: { message: '${message}' } } } },
+    { id: 'action_label', component: 'Text', text: '${label}', variant: 'body' },
   ];
 }
 

package/src/harness/cta.ts

@@ -0,0 +1,54 @@
+/**
+ * The action a result card offers, chosen from the record's own `potentialAction`.
+ *
+ * One map, shared with the Typed Retrieval skill (nxis-skills) and the NxisAI app's widgets (nxis-mcp
+ * `HubWidgets`): the action's `@type` alone decides the button, and the button sends the same prompt
+ * everywhere ("Get a quote from Hatzel & Sons Plumbing"), so the funnel cannot tell which surface it came
+ * from. Commerce, read and search actions get no button here.
+ *
+ * On the site's own page every mapped action sends the prompt, a self-page form included: the on-page agent
+ * is what runs that form. Only the NxisAI app, which cannot reach the page, opens it instead.
+ *
+ * @module
+ */
+
+/** What a card's action button says and sends. */
+export interface CardAction {
+  label: string;
+  /** The message sent as the visitor when the button is pressed. */
+  message: string;
+}
+
+const MAP: Record<string, { label: string; message: (name: string) => string }> = {
+  QuoteAction: { label: 'Get a quote', message: (n) => `Get a quote from ${n}` },
+  AskAction: { label: 'Contact', message: (n) => `Contact ${n}` },
+  ReserveAction: { label: 'Reserve', message: (n) => `Reserve at ${n}` },
+  ScheduleAction: { label: 'Book an appointment', message: (n) => `Book an appointment at ${n}` },
+  ApplyAction: { label: 'Apply', message: (n) => `Apply to ${n}` },
+};
+
+/** When a record carries several, the first of these wins. */
+const ORDER = Object.keys(MAP);
+
+const shortType = (t: unknown): string =>
+  typeof t === 'string' ? t.replace(/^https?:\/\/schema\.org\//, '') : '';
+
+const list = (v: unknown): unknown[] => (v == null ? [] : Array.isArray(v) ? v : [v]);
+
+/**
+ * The button for a record, or none.
+ *
+ * @param record - The record as a tool returned it; action `@type`s may be full IRIs.
+ * @param name - What to call it in the message; the record's own name by default.
+ */
+export function actionCta(record: Record<string, unknown>, name?: string): CardAction | undefined {
+  const types = list(record.potentialAction)
+    .filter((a): a is Record<string, unknown> => !!a && typeof a === 'object')
+    .flatMap((a) => list(a['@type']).map(shortType))
+    .filter((t) => t in MAP)
+    .sort((a, b) => ORDER.indexOf(a) - ORDER.indexOf(b));
+  if (!types.length) return undefined;
+  const who = (name ?? (typeof record.name === 'string' ? record.name : '')).trim() || 'them';
+  const entry = MAP[types[0]];
+  return { label: entry.label, message: entry.message(who) };
+}

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
@@ -561,6 +575,48 @@ export class AgentHarness {
     return this.act(tool, call.args, messages);
   }
 
+  /**
+   * Run a turn whose tool call is already decided, without asking the model.
+   *
+   * For a request that names its own action, such as a link from the NxisAI
+   * app to one business's quote form: the tool and the business are known, so
+   * the model has nothing to choose, and a model left to choose sometimes
+   * asks for the details in prose instead of opening the form. What follows
+   * the call is an ordinary turn's: the same slots, prompts and confirmation,
+   * and the call goes into the transcript as if the model had made it.
+   *
+   * @param goal - The request as the person would have said it, for the thread and transcript.
+   * @param name - The tool to call.
+   * @param args - Its arguments, e.g. which business.
+   * @param messages - The live conversation, appended to in place.
+   * @returns The decision taken, or `'unavailable'` when this agent has no such tool.
+   */
+  async begin(goal: string, name: string, args: Record<string, unknown>, messages: ChatMessage[]): Promise<TurnResult> {
+    this.abort?.abort();
+    this.abort = new AbortController();
+    this.goal = goal;
+    this.renderer.stoppable?.(true);
+    this.applySystemPrompt(messages);
+    beginJourney();
+
+    const bubble = this.renderer.streaming();
+    bubble.thinking('Finding tools…');
+    const tools = this.visibleTools(await this.toolSource.discoverTools(this.abort.signal), goal);
+    if (this.stopped) return this.stopTurn(bubble, messages, goal);
+    const tool = tools.find((t) => t.name === name);
+    if (!tool) {
+      bubble.finalize('');
+      return this.finished({ decision: 'unavailable' as const });
+    }
+
+    const call = { name, args };
+    messages.push({ role: 'user', content: goal });
+    bubble.finalize(narrateCall(call, tools));
+    messages.push({ role: 'assistant', content: this.transcribe({ text: '', call } as Completion) });
+    this.opts.onMessages?.(messages);
+    return this.act(tool, args, messages);
+  }
+
   /**
    * Narrow the page's tools to this agent's slice.
    *
@@ -834,6 +890,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 +1059,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({