@nxisai/agent-harness 0.8.0 → 0.10.0

package/src/index.ts

@@ -50,6 +50,9 @@ export type { Slot, Resolution, ResolveSources } from './harness/slots.js';
 
 export { buildPlan } from './harness/plan.js';
 
+export { actionCta } from './harness/cta.js';
+export type { CardAction } from './harness/cta.js';
+
 export { AgentCoordinator } from './harness/router/coordinator.js';
 export type { CoordinatorOptions, RoutedTurn, RouteSource } from './harness/router/coordinator.js';
 export { matchRoute } from './harness/router/rules.js';
@@ -134,6 +137,16 @@ export {
 export type { AgentStep, AgentStepId, AgentStepStatus } from './harness/steps.js';
 export { resumePendingAction } from './harness/tools/resume.js';
 export type { ResumeOutcome, ResumeOptions } from './harness/tools/resume.js';
+// Arriving from the NxisAI app to use one of this page's forms.
+export {
+  HANDOFF_PARAM,
+  INTENT_PARAM,
+  readInboundHandoff,
+  takeInboundHandoff,
+  handoffUrl,
+  findHandoffForm,
+} from './harness/tools/inbound.js';
+export type { InboundHandoff, ArrivalOutcome, ArrivalOptions } from './harness/tools/inbound.js';
 export {
   loadSitePages,
   parsePage,
@@ -145,6 +158,7 @@ export {
 export type { SitePage, SitePagesOptions } from './harness/tools/site-pages.js';
 export { buildOpenPageTool, registerOpenPageTool, resolveDestination, visitFor, OPEN_PAGE_TOOL } from './harness/tools/open-page.js';
 export { isRateLimited, retryAfterMs, withRetry } from './harness/tools/retry.js';
+export { setSiteActionReporter, TRACK_TOOL, type PageFormRun, type SiteActionReport, type SiteActionReporter } from './harness/tools/report.js';
 export type { RetryOptions } from './harness/tools/retry.js';
 export {
   applyTrails,

package/src/ui/agent-fullscreen.ts

@@ -22,6 +22,7 @@
  */
 import { mountSurface, type MountedSurface } from '../a2ui/host.js';
 import { emitCardsSurface, type ResultCardData } from '../a2ui/cards.js';
+import { actionCta, type CardAction } from '../harness/cta.js';
 import { emitToolForm } from '../a2ui/form.js';
 import { A2UI_THEME_CSS } from '../a2ui/theme.js';
 // Compiled from agent.tw.css at build time (scripts/css-to-ts.mjs). It is a
@@ -46,6 +47,7 @@ import {
   formsFor,
   handoffFor,
   isSiteTool,
+  siteFormFor,
   withoutSiteSuffix,
   HANDOFF_RESULT,
 } from '../harness/tools/action-tools.js';
@@ -64,6 +66,7 @@ import { resultsAnswer, RESULTS_ANSWER_CSS, type AnswerCard } from './result-pic
 import { extractRecords, openStatus, recordFacts } from '../harness/records.js';
 import type { ResultPick } from '../harness/recommend.js';
 import { resumePendingAction } from '../harness/tools/resume.js';
+import { findHandoffForm, startFormMessage, startMessage, takeInboundHandoff } from '../harness/tools/inbound.js';
 import { savePendingVisit, setConversationSource, takePendingVisit } from '../harness/tools/pending-action.js';
 import { pageForEntity, type SitePage } from '../harness/tools/site-pages.js';
 import { OPEN_PAGE_TOOL } from '../harness/tools/open-page.js';
@@ -341,6 +344,8 @@ interface ResultCard {
   phone?: string;
   /** What the record states, short, for comparing it. */
   facts?: string[];
+  /** The action the record itself offers (its potentialAction), as a button. */
+  action?: CardAction;
 }
 
 type ThreadItem =
@@ -682,6 +687,8 @@ class NxisAgentFullscreen extends HTMLElement {
     // belongs to is the one open.
     void this._resumePendingAction();
     this._resumePendingVisit();
+    // Sent here from the NxisAI app to use one of this page's forms.
+    void this._arriveFromHandoff();
 
     this._els.launcher.addEventListener('click', () => this._open());
     this._els.handoffBack.addEventListener('click', () => void this._endHandoff());
@@ -1589,7 +1596,14 @@ class NxisAgentFullscreen extends HTMLElement {
   }
 
   // ── Turn loop ──────────────────────────────────────────────────────────────
-  private async _onSend(): Promise<void> {
+  /**
+   * Send what is in the composer.
+   *
+   * @param call - A tool call already decided, run without asking the model
+   *   (a handoff names its form). Falls back to an ordinary turn when no agent
+   *   here holds the tool.
+   */
+  private async _onSend(call?: { name: string; args: Record<string, unknown> }): Promise<void> {
     const goal = this._els.input.value.trim();
     if (!goal || this._turnActive) return;
     this._els.input.value = '';
@@ -1626,7 +1640,9 @@ class NxisAgentFullscreen extends HTMLElement {
       await this._connectTools();
       this._syncProfileContext();
       // One agent, or several with a router in front: the signatures match.
-      await (this._coordinator ?? this._harness).turn(goal, conv!.messages);
+      const engine = this._coordinator ?? this._harness;
+      const begun = call ? await engine.begin(goal, call.name, call.args, conv!.messages) : null;
+      if (!begun || begun.decision === 'unavailable') await engine.turn(goal, conv!.messages);
       // A remote endpoint reports which model answered; the name beside the
       // input follows it rather than keeping whatever was configured.
       this._paintProvenance();
@@ -2673,6 +2689,7 @@ class NxisAgentFullscreen extends HTMLElement {
       facts.since ? `In business since ${facts.since}` : '',
       facts.reviews[0] ? `\u201c${facts.reviews[0].text}\u201d${facts.reviews[0].author ? ` \u2014 ${facts.reviews[0].author}` : ''}` : '',
     ].filter((l): l is string => !!l);
+    const action = actionCta(entity, title);
     return {
       title,
       type,
@@ -2686,6 +2703,7 @@ class NxisAgentFullscreen extends HTMLElement {
       ...(facts.reviewCount !== undefined ? { reviews: facts.reviewCount } : {}),
       ...(status ? { status: { open: status.open, label: status.label } } : {}),
       ...(facts.phone ? { phone: facts.phone } : {}),
+      ...(action ? { action } : {}),
       facts: lines,
     };
   }
@@ -2714,7 +2732,9 @@ class NxisAgentFullscreen extends HTMLElement {
     const things = item.cards.filter((c) => c.stars !== undefined || c.status || c.phone || c.page);
     if (!item.pick && !things.length) return null;
     const cards: AnswerCard[] = item.cards.map((c) => {
-      const form = formsFor(c.title)[0];
+      // The record's own action first: the same map and prompt as the Typed Retrieval skill and the NxisAI
+      // app. A record that states none falls back to a form found on this page for it.
+      const form = c.action ? undefined : formsFor(c.title)[0];
       const quote = form && /quote/.test(form.noun);
       return {
         title: c.title,
@@ -2724,7 +2744,9 @@ class NxisAgentFullscreen extends HTMLElement {
         phone: c.phone,
         page: c.page,
         facts: c.facts ?? [],
-        ...(form
+        ...(c.action
+          ? { form: { label: c.action.label, message: c.action.message } }
+          : form
           ? {
               form: quote
                 ? { label: 'Get a quote', message: `Get a quote from ${c.title}` }
@@ -2762,6 +2784,7 @@ class NxisAgentFullscreen extends HTMLElement {
         ...(c.emergency ? [{ label: '24/7' }] : []),
       ],
       rows: c.rows.map((r) => ({ label: r.label, value: r.value })),
+      actions: c.action ? [c.action] : [],
     }));
   }
 
@@ -2775,7 +2798,15 @@ class NxisAgentFullscreen extends HTMLElement {
     }
     try {
       const messages = emitCardsSurface(item.note, this._toA2uiCards(item.cards));
-      const mounted = mountSurface(wrap, messages);
+      const mounted = mountSurface(wrap, messages, (event: any) => {
+        const name = event?.event?.name ?? event?.name ?? '';
+        const ctx = (event?.event?.context ?? event?.context ?? {}) as Record<string, unknown>;
+        // A card's action button: send its message as the visitor, as the inline card does.
+        if (name === 'nxis.ask' && typeof ctx.message === 'string' && !this._turnActive) {
+          this._els.input.value = ctx.message;
+          void this._onSend();
+        }
+      });
       if (!mounted) throw new Error('no surface produced');
       this._surfaces.push(mounted);
     } catch (err) {
@@ -3503,6 +3534,42 @@ class NxisAgentFullscreen extends HTMLElement {
     if (this.mode !== 'fullscreen') this._open();
   }
 
+  /**
+   * Open on the form a link from the NxisAI app names.
+   *
+   * In a new conversation: the person arrives from another app, and nothing
+   * on this site led here. The agent starts the form in its own words, so the
+   * link only chooses which form; what the person wanted waits in the
+   * composer for them to send, change or delete.
+   */
+  private async _arriveFromHandoff(): Promise<void> {
+    const handoff = takeInboundHandoff();
+    if (!handoff) return;
+    this._newConversation();
+    this._open();
+    this._setStatus('Opening the form…');
+    // The site's own tools first: they reach a form from any page, from the
+    // site's records, so they work where the page registers nothing itself.
+    await this._connectTools();
+    const site = siteFormFor(handoff.actionId);
+    const start = site
+      ? startFormMessage(site.noun, site.choice)
+      : await findHandoffForm(handoff).then((o) => (o.status === 'ready' ? startMessage(o.tool) : null));
+    this._setStatus('');
+    if (!start) {
+      this._appendMsg('assistant', "I couldn't find that form on this page. Tell me what you need and I'll help from here.");
+    } else if (!this._turnActive) {
+      this._els.input.value = start;
+      // The form is known, so it opens without the model choosing it: left to
+      // choose, a model sometimes asks for the details in prose instead.
+      await this._onSend(site ? { name: site.tool, args: site.args } : undefined);
+    }
+    if (handoff.intent && !this._els.input.value) {
+      this._els.input.value = handoff.intent;
+      this._autosize();
+    }
+  }
+
   private async _resumePendingAction(): Promise<void> {
     const outcome = await resumePendingAction({
       onStart: (pending) => {