@nxisai/agent-harness 0.2.0

package/README.md

@@ -0,0 +1,434 @@
+# @nxisai/agent-harness
+
+An on-device agent for the browser. It runs a small model locally over WebGPU, discovers the tools your page exposes (WebMCP and remote MCP), and decides per turn whether to run a tool, ask for what is missing, or confirm before writing.
+
+No server. No API key. The model runs in the tab.
+
+```bash
+npm install @nxisai/agent-harness
+```
+
+## Quick start
+
+```js
+import '@nxisai/agent-harness/ui';
+```
+
+```html
+<nxis-agent-fullscreen></nxis-agent-fullscreen>
+```
+
+The element registers itself, finds the page's tools, and renders a chat surface with an inline launcher. That is the whole integration for a single agent.
+
+## Single agent or multiple agents
+
+The element supports two modes. The default is one agent that reads every tool on the page. The optional mode adds a coordinator and a set of specialists; each turn then loads one agent's instructions and one agent's tools instead of everyone's.
+
+![Single agent: every turn loads one system prompt and all ten tool definitions, 2,476 tokens. Specialists: a coordinator with no tools routes to one of four agents, each loading only its own prompt and tools, 506 to 611 tokens per turn.](docs/single-vs-multi-agent.svg)
+
+
+Numbers above are from one site (six forms, four retrieval tools). Tool definitions are re-sent on every turn and are most of what a small model reads; the saving comes from what each agent does not load, and the accuracy comes from choosing between two tools instead of ten.
+
+### Single agent
+
+Nothing to configure beyond the prompt:
+
+```js
+const agent = document.querySelector('nxis-agent-fullscreen');
+agent.systemPrompt = '…';
+agent.suggestions = ['Find a plumber', 'Book a visit'];
+```
+
+### Multiple agents
+
+Declare the specialists, a rule table, and a fallback. The element builds an `AgentHarness` per entry over its one engine and places an `AgentCoordinator` in front. Clear `agents` to return to single-agent mode.
+
+```js
+agent.agents = {
+  retrieval: {
+    systemPrompt: RETRIEVAL_PROMPT,
+    tools: (t) => /^nxis_(query|get)$/.test(t.name),
+    description: 'questions about services, ratings and areas',
+    unavailable: 'I cannot search the site records from here right now.',
+  },
+  booking: {
+    systemPrompt: BOOKING_PROMPT,
+    tools: (t) => /book|appointment/i.test(t.name),
+    description: 'booking a visit',
+    unavailable: 'I cannot book a visit from here. The booking page can.',
+  },
+};
+agent.routes = [
+  { route: 'booking',   match: /\b(book|schedule|appointment)\b/ },
+  { route: 'retrieval', match: /\b(hours|rated|cover|who|find)\b/ },
+];
+agent.fallback = 'retrieval';
+```
+
+Each `AgentDefinition` field:
+
+| Field | Purpose |
+|---|---|
+| `systemPrompt` | This agent's instructions. Asserted at the head of the shared transcript on every turn. |
+| `tools(tool)` | Which registered tools this agent may use. Match by name. |
+| `description` | One line for the model classifier. Read only when the classifier runs. |
+| `unavailable` | What the agent says when none of its tools are on the page. |
+
+### How a turn is routed
+
+A turn checks a rule table first and routes with no model call. If the rules are unclear, a short classification pass runs. The chosen specialist keeps handling later turns without re-routing, and can hand back once if the model asks for a tool it does not hold.
+
+![A turn checks a rule table first and routes with no model call. If the rules are unclear, a short classification pass runs. The chosen specialist keeps handling later turns without re-routing, and can hand back once if the model asks for a tool it does not hold.](docs/turn-routing.svg)
+
+
+
+Cheapest path first:
+
+| Path | When | Cost |
+|---|---|---|
+| rules | a rule matches | none |
+| sticky | rules abstain; the conversation is already with an agent | none |
+| model | rules abstain; no history; an engine is supplied | one short generation (no tools, 12-token cap) |
+| fallback | nothing decided | none |
+| hand-back | the agent's model asks for a tool it does not hold | one extra turn, at most once |
+
+Rules vote; `weight` breaks ties; a tie that nothing separates abstains rather than guessing. Stickiness is released when an agent reports `unavailable`, so a follow-up does not return to an agent that cannot act.
+
+## Models
+
+Gemma 4 on WebGPU is the default and needs no configuration. To run the agent on a remote model, implement `ModelProvider`:
+
+```ts
+interface ModelProvider {
+  readonly name: string;
+  readonly local: boolean;     // false makes the header badge read "Remote"
+  readonly ready: boolean;
+  readonly loading: boolean;
+  load?(): Promise<void>;      // omit for a provider with nothing to download
+  preload?(mode: 'eager' | 'idle'): void;
+  complete(req: CompletionRequest): Promise<Completion>;
+  countTokens?(text: string): Promise<number>;
+}
+
+interface Completion {
+  text: string;                                          // rendered verbatim
+  call?: { name: string; args: Record<string, unknown> };
+  usage?: { promptTokens: number; outputTokens: number };
+}
+```
+
+```js
+agent.modelProvider = myProvider;     // or: new AgentHarness({ provider, renderer })
+```
+
+The boundary carries a structured completion rather than a string. Gemma announces tool calls in text, so `LocalGemmaProvider` parses its own markers; Claude, Gemini and Kimi return native tool-use blocks and map them onto `call`. The harness parses nothing either way.
+
+**Put your model behind your own origin.** A vendor key in a browser is a key anyone can read from the page source, and a browser cannot rate-limit or audit itself. See [docs/remote-providers.md](docs/remote-providers.md) for a worked Claude example: a route handler that holds the key, and the provider that calls it.
+
+Three optional members are how the UI adapts. Omit `load` and the whole download treatment is skipped (no charging ring, no byte counts). Omit `countTokens` and the token metrics panel is hidden rather than rendered as zeroes. `local: false` puts `Remote` in the header, because the package's claim is that nothing leaves the tab and the exception has to be visible.
+
+### The cache hint
+
+`CompletionRequest.cache` carries `{ stableMessages, toolsStable }`: what the harness knows will repeat next turn. The harness cannot cache anything itself, and never depends on a hit. Acting on it is your endpoint's decision, and only where the vendor supports it.
+
+Both flags go false at a specialist handoff, which swaps the system prompt and the tool slice. Sticky routing therefore keeps a prefix stable within a topic and invalidates it at the boundary.
+
+## Element API
+
+### Properties
+
+| Property | Type | Default | Notes |
+|---|---|---|---|
+| `systemPrompt` | `string` | packaged prompt | See [Prompts](#prompts). |
+| `suggestions` | `string[]` | two generic chips | Empty-state chips. `[]` shows none. |
+| `emptyState` | `string` | describes the mechanism | Line above the chips. |
+| `name` | `string` | `"Nxis Agent"` | Header, launcher tooltip, dialog accessible name. |
+| `logo` | `string` | Nxis mark | Inline SVG markup, or an image URL. |
+| `theme` | `AgentTheme` | NxisAI palette | See [Theming](#theming). |
+| `agents` | `Record<string, AgentDefinition> \| null` | `null` | Enables multi-agent mode. |
+| `routes` | `RouteRule[]` | `[]` | Ignored unless `agents` is set. |
+| `fallback` | `string` | first agent declared | Ignored unless `agents` is set. |
+| `modelProvider` | `ModelProvider \| null` | `null` | A remote model. Null means local Gemma. See [Models](#models). |
+| `preload` | `'eager' \| 'idle' \| 'none'` | `'idle'` | When weights are fetched. Local provider only. Settable mid-session. |
+| `debug` | `boolean` | `false` | Shows tool receipts and route labels. |
+| `preferences` | `AgentPreferences` | session-scoped | See [Preferences](#preferences). |
+
+### Attributes
+
+| Attribute | Values | Purpose |
+|---|---|---|
+| `preload` | `eager`, `idle`, `none` (`false` also means `none`) | Same as the property. |
+| `debug` | present, or `"false"` | Same as the property. |
+| `discover` | `"false"` | Skip remote MCP discovery. |
+| `cache` | `"false"` | Do not store model files in Cache Storage. |
+| `mcp-api-key` | string | Key for private remote tools. |
+| `model-host` | URL | Fetch weights from another origin. |
+| `model-path-template` | string | Path template under `model-host`. |
+| `a2ui` | `"false"` | Use the legacy DOM renderers. |
+| `auto-open` | present | Open on connect. |
+
+### Methods
+
+```js
+agent.open();
+```
+
+### Preferences
+
+Standing values used to fill forms. Session-scoped unless `persist` is set.
+
+```js
+agent.preferences.set({ name: 'Jane Doe', email: 'jane@example.com' });
+agent.preferences.set('phone', '555-0100');
+agent.preferences.get();           // all
+agent.preferences.get('email');
+agent.preferences.keys();          // ['name', 'email', 'phone', 'address']
+agent.preferences.clear('phone');
+agent.preferences.clear();
+agent.preferences.persist = true;  // survive reloads; false deletes the stored copy
+agent.addEventListener('nxis-preferences-change', (e) => e.detail.preferences);
+```
+
+Keys map onto differently named schema fields (`name` satisfies `full_name`, `fullname`, `name`). Extend `PROFILE_ALIASES` to add one.
+
+### Theming
+
+`theme` merges over the defaults. Each key writes two custom properties (the element's own CSS and its Tailwind utilities use different names), so set colors here rather than in CSS.
+
+```js
+agent.theme = {
+  accent: '#B45309', accentStrong: '#92400E', accentTint: '#FDF3E7',
+  ink: '#0E1C2B', inkSoft: '#40566D', inkMuted: '#8A97AC',
+  bg: '#FFFFFF', surface: '#FBFAF8', border: '#E2DDD6',
+  radius: '14px',
+  fontDisplay: 'Manrope, sans-serif', fontSans: 'Inter, sans-serif', fontMono: 'JetBrains Mono, monospace',
+};
+```
+
+Green and red are not themeable. Fonts are not bundled; load them or point the font keys at faces you ship. The footer's "Powered by NxisAI" badge is not affected by `logo` or `theme`.
+
+### Prompts
+
+Two lines of the packaged prompt do real work. Keep them if you rewrite it:
+
+> Call the tool as soon as you know which one is right, even if some required fields are still unknown; include the fields you do have and omit the rest. Never ask the user to supply a missing field in prose.
+
+The harness collects missing fields as fields (one question, a stepper, or a confirm card). A prompt that tells the model to ask in prose produces a paragraph of questions instead.
+
+## What a turn does
+
+Given the tool the model picked and everything already known, the harness asks what is still unknown:
+
+| Tool | Gaps | Result |
+|---|---|---|
+| read (`readOnlyHint`) | none | runs, no UI |
+| read | some | asks only for those, then runs |
+| write | none | confirm card, one Submit |
+| write | one | asks for one field, then confirms |
+| write | several | stepper, then confirms |
+
+Values merge in this order, last wins: schema default, page context, saved preferences, model arguments.
+
+Every turn leaves three things in the history: the model's words (synthesized from the chosen tool when the model emitted only a call), the rendered UI, and, with `debug` on, a collapsed receipt showing the call and the raw response.
+
+### Stopping a turn
+
+`stop()` aborts wherever the turn currently is: tool discovery, the routing classifier, or the generation itself (the local provider interrupts Gemma mid-stream). The turn resolves as `'stopped'`.
+
+A stopped turn keeps the question and discards the partial answer, from the rendered thread and from `messages` alike. An unfinished reply is something the person has to decide whether to trust, and a model that reads it back as history will continue from it or contradict it. The question staying is what keeps the thread and the transcript in step.
+
+In the element, the send button becomes a stop button for the duration, Escape stops the turn (it does not close the panel), and every message the person sent carries a row of actions: copy, edit in place, and send again. Editing or resending discards everything below that message, because it answered a question that no longer exists.
+
+## Headless API
+
+Import from `@nxisai/agent-harness` and bring your own renderer.
+
+```ts
+import { AgentHarness, AgentCoordinator, LocalGemmaProvider, connectTools } from '@nxisai/agent-harness';
+
+await connectTools();                          // WebMCP + remote MCP
+
+const provider = new LocalGemmaProvider();     // or your own; shared between agents
+
+const retrieval = new AgentHarness({
+  provider, renderer,
+  name: 'retrieval',
+  systemPrompt: RETRIEVAL_PROMPT,
+  tools: (t) => /^nxis_/.test(t.name),
+  unavailable: 'I cannot search from here right now.',
+});
+
+const coordinator = new AgentCoordinator({
+  agents: { retrieval, booking },
+  rules: ROUTE_RULES,
+  fallback: 'retrieval',
+  provider,                                     // optional: enables the model pass
+  descriptions: { booking: 'visits and appointments' },
+  onRoute: (r) => console.debug(r.agent, r.via),
+});
+
+await coordinator.turn(goal, messages);         // same signature as harness.turn
+```
+
+### `LocalGemmaProvider`
+
+```ts
+new LocalGemmaProvider({ systemPrompt?, modelHost?, modelPathTemplate?, useBrowserCache?, onStatus?, onProgress? })
+provider.complete(req): Promise<Completion>
+provider.load(): Promise<void>
+provider.preload(mode?: 'eager' | 'idle')
+provider.countTokens(text): Promise<number>
+provider.ready: boolean
+provider.loading: boolean
+```
+
+`onProgress(pct, detail?)` reports `{ loaded, total }` in bytes. The percentage is per stage and unclamped. Exported as `AgentEngine` too, deprecated: it used to own tool discovery and schema reading, which now live on the harness.
+
+### `AgentHarness`
+
+```ts
+new AgentHarness({ renderer, provider?, toolSource?, systemPrompt?, tools?, name?, unavailable?, profile?, context?, groupRelated?, onMessages? })
+harness.turn(goal, messages): Promise<TurnResult>
+harness.owns(toolName): boolean
+harness.stop(): void                     // abandon the request in flight
+harness.provider: ModelProvider
+harness.toolSource: WebMcpTools
+```
+
+`TurnResult.decision` is one of the policy decisions, or `'none'`, `'handback'` (with `wanted`, the tool name the model asked for), `'unavailable'`, or `'stopped'`.
+
+`stop()` abandons the turn in flight and resolves it as `'stopped'`; it never rejects, so a cancellation is not reported to the person as a failure.
+
+### `HarnessRenderer`
+
+```ts
+interface HarnessRenderer {
+  message(role, text): void;
+  streaming(): StreamingBubble;          // thinking(label?), update(text), finalize(text)
+  status(text, isError?): void;
+  ask(req: AskRequest): void;
+  confirm(req: ConfirmRequest): void;
+  results(tool, res): void;
+  detail(tool, values, text): void;
+  toolError(tool, message): void;
+  trace?(entry: TraceEntry): void;       // { tool, args, text, isError, count? }
+  dismissPrompt?(): void;
+  stoppable?(canStop: boolean): void;    // false once a tool call has gone out
+}
+```
+
+`stoppable` is called with `true` when a turn starts and `false` when it ends, and also `false` the moment a tool is invoked: past that point the call may already have reached a server, so a control still offering to stop would be promising something it cannot deliver.
+
+### `AgentCoordinator`
+
+```ts
+new AgentCoordinator({ agents, rules, fallback, provider?, descriptions?, onRoute? })
+coordinator.turn(goal, messages): Promise<TurnResult>
+coordinator.stop(): void                 // the classifier and the agent that took the turn
+coordinator.turn(goal, messages): Promise<TurnResult>
+coordinator.route(goal, messages?): RoutedTurn   // decide without running
+```
+
+`RoutedTurn` carries `agent`, `via` (`'rules' | 'sticky' | 'model' | 'fallback' | 'handback'`), `fellBack`, `scores`, and the matched rules.
+
+### Routing rules
+
+```ts
+interface RouteRule {
+  route: string;
+  match: RegExp;      // tested against the lower-cased goal
+  weight?: number;    // default 1
+  because?: string;   // surfaced in the decision
+}
+matchRoute(goal, rules): RouteDecision   // { route | null, scores, matched }
+```
+
+### Tool helpers
+
+```ts
+import { WebMcpTools, toolSchema, missingRequired, reconcileArgs, extractResult } from '@nxisai/agent-harness';
+
+const tools = new WebMcpTools();         // document.modelContext, wrapped
+await tools.discoverTools();
+await tools.execTool(tool, name, args);
+```
+
+These are model agnostic, so they sit with the harness rather than behind the provider interface: a remote provider has no business knowing about `document.modelContext`.
+
+### Decision helpers
+
+```ts
+import { resolveSlots, decide, policyFor, buildPlan } from '@nxisai/agent-harness';
+const resolution = resolveSlots(schema, { modelArgs, profile });
+const action = decide(policyFor(tool), resolution.missing.length);
+const plan = buildPlan(resolution.missing);
+```
+
+### Tools
+
+```ts
+import { connectTools } from '@nxisai/agent-harness/tools';
+const { modelContext, remoteTools, warning } = await connectTools(apiKey?, { timeout?, fallback?, accept? });
+```
+
+Discovery reads `/.well-known/ai-catalog.json`, follows it to the server card, and bridges the server's tools into `document.modelContext`. When the page has no WebMCP provider, a local registry is installed so bridged tools still have a home (`fallback: false` disables this). `nxis_action` is not bridged by default; it is the server-side path for external MCP clients, and the page's own form tools cover the same actions. Pass `accept` to change which tools cross.
+
+Bridged tools are marked read-only only when their server says so. The `nxis_query` schema is flattened for the model: `{ schema_type, text, filters, sort, limit }`, where `filters` is `{ "path": ">=4.5" }` (prefixes `>=`, `>`, `<=`, `<`; a list means any-of) and `sort` is a path with `-` for descending. String and nested forms of `filters` are accepted.
+
+### A2UI
+
+```ts
+import { emitAsk, emitStep, emitConfirm, toV09 } from '@nxisai/agent-harness/a2ui';
+```
+
+Messages are authored against A2UI v1.0 and downgraded with `toV09` for the published `@a2ui/lit` renderer.
+
+## Requirements
+
+- WebGPU: Chrome or Edge 113+, or Safari 18+.
+- Model weights: fetched on first use (gigabytes on a first run, then cached).
+- Tools: `document.modelContext` from `nxis.js` or a browser extension, or a remote MCP server discoverable through `.well-known`.
+
+## Troubleshooting and gotchas
+
+**`__turbopack_context__.x is not a function` when the agent opens.**
+The engine loads Transformers.js from a CDN with a dynamic import that must not be bundled. The import carries `@vite-ignore`, `webpackIgnore`, and `turbopackIgnore`; all three are required. If you fork the engine, keep them.
+
+**The tab dies with `RESULT_CODE_KILLED_BAD_MESSAGE` when the model loads.**
+Chrome's Cache Storage can fail on entries this large and kill the renderer rather than report it. The engine records a load before it starts; if the page died mid-load, the next attempt runs without the browser cache and says so. Clearing the site's data usually fixes the cache; `cache="false"` skips it permanently.
+
+**"No tools are registered on this page yet."**
+`document.modelContext` is empty. On a local origin the site tag does not activate, so on-page form tools are absent; remote MCP tools still arrive through discovery if `.well-known/ai-catalog.json` is served. Check that `discover` is not `"false"`.
+
+**An agent answers "I cannot do that from this page".**
+That agent's `tools` filter matched nothing among the registered tools. The slice is not widened silently. Check the names your page registers against the filter, and write an `unavailable` line per agent.
+
+**The model says it cannot filter, sort, or use a field.**
+The model only knows what the tool schema shows it and will deny a capability the schema omits. Check the bridged schema (`modelContext.getTools()`), not the prompt.
+
+**A filter is ignored and results come back unfiltered.**
+The bridge accepts `filters` as an object, a JSON string, a JS-style string with bare keys, or `path >= value`. Anything unreadable is dropped, and the query still runs. Turn on `debug` to see the exact call in the receipt.
+
+**The rule table routes poorly.**
+Rules written alongside their fixtures will pass those fixtures. Measure on phrasings you did not write the rules for; people describe symptoms ("slow drain in the kitchen") where rules expect verbs ("book a visit"). Abstaining is the designed failure mode; a wrong route is not.
+
+**Routing keeps sending follow-ups to the wrong agent.**
+Stickiness holds when the rules abstain. Add a rule for the phrasing, or rely on the hand-back: when the agent's model names a tool it does not hold, the coordinator moves the turn once to the owner.
+
+
+**Colors set in CSS only apply to part of the UI.**
+The element carries two token systems (`--blue` and `--color-blue`, and so on). Use the `theme` property, which writes both.
+
+**A remote provider shows a charging ring or an empty metrics panel.**
+Omit `load` from the provider so the UI knows there is nothing to download, and omit `countTokens` so the token comparison is hidden rather than rendered as zeroes.
+
+**Requests keep running after the panel closes.**
+Pass `signal` from `CompletionRequest` into your `fetch`. The harness aborts on close and when a new turn starts, but only the provider can act on it.
+
+**Only one tool runs per turn.**
+By design: the decision table asks, confirms and runs one call. A provider that returns several tool-use blocks should send the first; the rest are ignored.
+
+
+## License
+
+Apache-2.0

package/dist/a2ui/cards.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Renders typed-retrieval results as A2UI cards.
+ *
+ * The component count is fixed regardless of how many results there are: one
+ * result and twelve emit the same components, differing only in the data at
+ * `/results`. A result arriving late is therefore a data-model patch rather
+ * than new components, which keeps rendering incremental.
+ *
+ * Conditionality lives in the data rather than the components, so an entity
+ * with no rating simply has fewer entries. The basic catalog has no conditional
+ * rendering and none is needed.
+ */
+import type { A2uiMessage } from './emit.js';
+/** One label and value line on a result card. */
+export interface CardRow {
+    label: string;
+    value: string;
+}
+/** A short pill shown on a result card. */
+export interface CardTag {
+    label: string;
+}
+/** One record, in the shape a result card renders. */
+export interface ResultCardData {
+    title: string;
+    sub: string;
+    tags: CardTag[];
+    rows: CardRow[];
+}
+/**
+ * Normalise one schema.org entity into flat card data.
+ *
+ * Mirrors `_entityCard` in agent-fullscreen.ts, with the same
+ * title/type/rating rules and 4-row cap, so the A2UI surface and inline card show
+ * the same thing. If this ships, the two should share one implementation rather
+ * than drift; this copy exists to keep the sketch self-contained.
+ */
+export declare function toCardData(entity: Record<string, unknown>): ResultCardData;
+/**
+ * Build a surface from card data that has already been normalised.
+ *
+ * agent-fullscreen has its own `_entityCard`, and it is the one that decides
+ * what a card shows. Taking its output rather than re-deriving from entities
+ * keeps the A2UI surface and the legacy inline card identical by construction.
+ */
+export declare function emitCardsSurface(heading: string, results: ResultCardData[], surfaceId?: string): A2uiMessage[];
+/**
+ * Build the A2UI messages for a set of results.
+ *
+ * @returns The messages to render, as one surface.
+ */
+export declare function emitResultsSurface(toolName: string, entities: Record<string, unknown>[], surfaceId?: string): A2uiMessage[];
+/** A late-arriving result appends to the list; no components are re-sent. */
+export declare function emitAppendResult(surfaceId: string, index: number, entity: Record<string, unknown>): A2uiMessage;
+//# sourceMappingURL=cards.d.ts.map

package/dist/a2ui/cards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cards.d.ts","sourceRoot":"","sources":["../../src/a2ui/cards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAM7C,iDAAiD;AACjD,MAAM,WAAW,OAAO;IAAG,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE;AACzD,2CAA2C;AAC3C,MAAM,WAAW,OAAO;IAAG,KAAK,EAAE,MAAM,CAAA;CAAE;AAC1C,sDAAsD;AACtD,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,IAAI,EAAE,OAAO,EAAE,CAAC;CACjB;AAQD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,cAAc,CAmD1E;AAiCD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,cAAc,EAAE,EACzB,SAAS,SAAY,GACpB,WAAW,EAAE,CASf;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EACnC,SAAS,SAAY,GACpB,WAAW,EAAE,CAMf;AAED,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChE,WAAW,CAKb"}

package/dist/a2ui/cards.js

@@ -0,0 +1,133 @@
+/**
+ * Renders typed-retrieval results as A2UI cards.
+ *
+ * The component count is fixed regardless of how many results there are: one
+ * result and twelve emit the same components, differing only in the data at
+ * `/results`. A result arriving late is therefore a data-model patch rather
+ * than new components, which keeps rendering incremental.
+ *
+ * Conditionality lives in the data rather than the components, so an entity
+ * with no rating simply has fewer entries. The basic catalog has no conditional
+ * rendering and none is needed.
+ */
+const CATALOG = 'https://a2ui.org/specification/v1_0/catalogs/basic/catalog.json';
+const str = (v) => (v == null ? '' : String(Array.isArray(v) ? v[0] : v));
+const humanize = (s) => s.replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/[_-]+/g, ' ')
+    .replace(/^\w/, c => c.toUpperCase());
+/**
+ * Normalise one schema.org entity into flat card data.
+ *
+ * Mirrors `_entityCard` in agent-fullscreen.ts, with the same
+ * title/type/rating rules and 4-row cap, so the A2UI surface and inline card show
+ * the same thing. If this ships, the two should share one implementation rather
+ * than drift; this copy exists to keep the sketch self-contained.
+ */
+export function toCardData(entity) {
+    const title = str(entity.name ?? entity.title ?? entity.headline ?? entity['@id'] ?? 'Result');
+    const tags = [];
+    const rawType = entity['@type'];
+    if (rawType)
+        tags.push({ label: humanize(str(rawType)) });
+    const ar = entity.aggregateRating;
+    if (ar && typeof ar === 'object' && ar.ratingValue != null) {
+        const stars = '★'.repeat(Math.max(1, Math.min(5, Math.round(Number(ar.ratingValue) || 0))));
+        tags.push({
+            label: ar.reviewCount != null
+                ? `${stars} ${str(ar.ratingValue)} · ${str(ar.reviewCount)}`
+                : `${stars} ${str(ar.ratingValue)}`,
+        });
+    }
+    // 24/7 is only ever implied by round-the-clock opening hours.
+    const hours = entity.openingHoursSpecification;
+    if (Array.isArray(hours) && hours.some(h => h && typeof h === 'object'
+        && String(h.opens) === '00:00'
+        && String(h.closes) === '23:59')) {
+        tags.push({ label: '24/7' });
+    }
+    const desc = str(entity.description).trim();
+    const sub = desc.length > 150 ? desc.slice(0, 147) + '…' : desc;
+    const rows = [];
+    const push = (label, value) => {
+        const v = str(value).trim();
+        if (v && rows.length < 4 && !rows.some(r => r.label === label)) {
+            rows.push({ label, value: v.length > 90 ? v.slice(0, 87) + '…' : v });
+        }
+    };
+    const addr = entity.address;
+    if (addr && typeof addr === 'object') {
+        const parts = [addr.streetAddress, addr.addressLocality, addr.addressRegion]
+            .filter(Boolean).map(str);
+        if (parts.length)
+            push('Address', parts.join(', '));
+    }
+    for (const key of ['telephone', 'email', 'url']) {
+        const v = entity[key];
+        if (typeof v === 'string' || typeof v === 'number') {
+            push(humanize(key === 'url' ? 'website' : key), v);
+        }
+    }
+    return { title, sub, tags, rows };
+}
+/** Fixed component set — independent of how many results there are. */
+function cardComponents(heading) {
+    return [
+        { id: 'root', component: 'Column', children: ['heading', 'results'] },
+        { id: 'heading', component: 'Text', text: heading, variant: 'body' },
+        // Outer list: one Card per entry in /results
+        { 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'] },
+        // 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.
+        { id: 'card_title', component: 'Text', text: '${title}', variant: 'body' },
+        // Relative paths resolve inside the current item's scope.
+        { id: 'card_tags', component: 'List',
+            children: { path: 'tags', componentId: 'tag_tpl' }, direction: 'horizontal' },
+        { id: 'tag_tpl', component: 'Text', text: '${label}', variant: 'caption' },
+        { id: 'card_sub', component: 'Text', text: '${sub}', variant: 'caption' },
+        { id: 'card_rows', component: 'List',
+            children: { path: 'rows', componentId: 'row_tpl' }, direction: 'vertical' },
+        { 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' },
+    ];
+}
+/**
+ * Build a surface from card data that has already been normalised.
+ *
+ * agent-fullscreen has its own `_entityCard`, and it is the one that decides
+ * what a card shows. Taking its output rather than re-deriving from entities
+ * keeps the A2UI surface and the legacy inline card identical by construction.
+ */
+export function emitCardsSurface(heading, results, surfaceId = 'results') {
+    return [{
+            version: 'v1.0',
+            createSurface: {
+                surfaceId, catalogId: CATALOG,
+                components: cardComponents(heading),
+                dataModel: { results: results.slice(0, 12) },
+            },
+        }];
+}
+/**
+ * Build the A2UI messages for a set of results.
+ *
+ * @returns The messages to render, as one surface.
+ */
+export function emitResultsSurface(toolName, entities, surfaceId = 'results') {
+    const results = entities.slice(0, 12).map(toCardData);
+    const heading = results.length
+        ? `${humanize(toolName)} — ${results.length} result${results.length === 1 ? '' : 's'}`
+        : `${humanize(toolName)} — no results`;
+    return emitCardsSurface(heading, results, surfaceId);
+}
+/** A late-arriving result appends to the list; no components are re-sent. */
+export function emitAppendResult(surfaceId, index, entity) {
+    return {
+        version: 'v1.0',
+        updateDataModel: { surfaceId, path: `/results/${index}`, value: toCardData(entity) },
+    };
+}
+//# sourceMappingURL=cards.js.map

package/dist/a2ui/cards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cards.js","sourceRoot":"","sources":["../../src/a2ui/cards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,MAAM,OAAO,GAAG,iEAAiE,CAAC;AAgBlF,MAAM,GAAG,GAAG,CAAC,CAAU,EAAU,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAE3F,MAAM,QAAQ,GAAG,CAAC,CAAS,EAAU,EAAE,CACrC,CAAC,CAAC,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC;KAC7D,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;AAEzC;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,MAA+B;IACxD,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,QAAQ,CAAC,CAAC;IAC/F,MAAM,IAAI,GAAc,EAAE,CAAC;IAE3B,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IAChC,IAAI,OAAO;QAAE,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAE1D,MAAM,EAAE,GAAG,MAAM,CAAC,eAAsD,CAAC;IACzE,IAAI,EAAE,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,CAAC,WAAW,IAAI,IAAI,EAAE,CAAC;QAC3D,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5F,IAAI,CAAC,IAAI,CAAC;YACR,KAAK,EAAE,EAAE,CAAC,WAAW,IAAI,IAAI;gBAC3B,CAAC,CAAC,GAAG,KAAK,IAAI,GAAG,CAAC,EAAE,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,WAAW,CAAC,EAAE;gBAC5D,CAAC,CAAC,GAAG,KAAK,IAAI,GAAG,CAAC,EAAE,CAAC,WAAW,CAAC,EAAE;SACtC,CAAC,CAAC;IACL,CAAC;IAED,8DAA8D;IAC9D,MAAM,KAAK,GAAG,MAAM,CAAC,yBAAyB,CAAC;IAC/C,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CACzC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ;WACvB,MAAM,CAAE,CAA6B,CAAC,KAAK,CAAC,KAAK,OAAO;WACxD,MAAM,CAAE,CAA6B,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC,EAAE,CAAC;QAChE,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;IAC/B,CAAC;IAED,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5C,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;IAEhE,MAAM,IAAI,GAAc,EAAE,CAAC;IAC3B,MAAM,IAAI,GAAG,CAAC,KAAa,EAAE,KAAc,EAAE,EAAE;QAC7C,MAAM,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,EAAE,CAAC;YAC/D,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACxE,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,IAAI,GAAG,MAAM,CAAC,OAA8C,CAAC;IACnE,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACrC,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,eAAe,EAAE,IAAI,CAAC,aAAa,CAAC;aACzE,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,KAAK,CAAC,MAAM;YAAE,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACtD,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC;QAChD,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QACtB,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;YACnD,IAAI,CAAC,QAAQ,CAAC,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACpC,CAAC;AAED,uEAAuE;AACvE,SAAS,cAAc,CAAC,OAAe;IACrC,OAAO;QACL,EAAE,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE;QACrE,EAAE,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE;QAEpE,6CAA6C;QAC7C,EAAE,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM;YAChC,QAAQ,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,EAAE,SAAS,EAAE,UAAU,EAAE;QAClF,EAAE,EAAE,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE;QACzD,EAAE,EAAE,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,CAAC,EAAE;QACxG,wEAAwE;QACxE,yEAAyE;QACzE,oEAAoE;QACpE,EAAE,EAAE,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE;QAE1E,0DAA0D;QAC1D,EAAE,EAAE,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM;YAClC,QAAQ,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,EAAE,SAAS,EAAE,YAAY,EAAE;QAC/E,EAAE,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,SAAS,EAAE;QAE1E,EAAE,EAAE,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE;QAEzE,EAAE,EAAE,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM;YAClC,QAAQ,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,EAAE,SAAS,EAAE,UAAU,EAAE;QAC7E,EAAE,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,WAAW,EAAE,WAAW,CAAC,EAAE;QACzE,EAAE,EAAE,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,SAAS,EAAE;QAC5E,EAAE,EAAE,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,SAAS,EAAE;KAC7E,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAe,EACf,OAAyB,EACzB,SAAS,GAAG,SAAS;IAErB,OAAO,CAAC;YACN,OAAO,EAAE,MAAM;YACf,aAAa,EAAE;gBACb,SAAS,EAAE,SAAS,EAAE,OAAO;gBAC7B,UAAU,EAAE,cAAc,CAAC,OAAO,CAAC;gBACnC,SAAS,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE;aAC7C;SACF,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAAgB,EAChB,QAAmC,EACnC,SAAS,GAAG,SAAS;IAErB,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACtD,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM;QAC5B,CAAC,CAAC,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM,OAAO,CAAC,MAAM,UAAU,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE;QACtF,CAAC,CAAC,GAAG,QAAQ,CAAC,QAAQ,CAAC,eAAe,CAAC;IACzC,OAAO,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;AACvD,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,gBAAgB,CAC9B,SAAiB,EAAE,KAAa,EAAE,MAA+B;IAEjE,OAAO;QACL,OAAO,EAAE,MAAM;QACf,eAAe,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,YAAY,KAAK,EAAE,EAAE,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,EAAE;KACrF,CAAC;AACJ,CAAC"}