@nxisai/agent-harness 0.4.1 → 0.5.0

package/src/a2ui/stepper.ts

@@ -0,0 +1,211 @@
+/**
+ * The two prompt surfaces: asking for missing values, and confirming a write.
+ *
+ * The stepper never recreates its surface. Steps arrive as component updates
+ * against a live surface whose data model already holds every answer, so moving
+ * between steps changes the components without touching the data, and nothing
+ * already entered is lost.
+ *
+ * @module
+ */
+
+import type { JsonSchema } from '../types.js';
+import type { A2uiMessage } from './emit.js';
+import type { ClarificationPlan, PlanStep } from '../harness/plan.js';
+import type { Slot } from '../harness/slots.js';
+
+const CATALOG = 'https://a2ui.org/specification/v1_0/catalogs/basic/catalog.json';
+
+interface Component { id: string; component: string; [prop: string]: unknown }
+
+const humanize = (s: string): string =>
+  s.replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/[_-]+/g, ' ')
+   .replace(/^\w/, c => c.toUpperCase());
+
+function labelFor(slot: Slot): string {
+  return slot.schema.description || humanize(slot.name);
+}
+
+function enumOptions(values: unknown[]): { label: string; value: string }[] {
+  return values
+    .map(v => String(v))
+    // A leading placeholder option is a markup convention rather than a
+    // choice, and offering it would allow it to be submitted as an answer.
+    .filter(v => !/[…:]\s*$/.test(v))
+    .map(v => ({ label: humanize(v), value: v }));
+}
+
+/** One input bound to /form/<name>. */
+function inputFor(slot: Slot): Component {
+  const id = `f_${slot.name}`;
+  const value = { path: `/form/${slot.name}` };
+  const label = labelFor(slot);
+  const spec: JsonSchema = slot.schema;
+
+  const values = spec.enum ?? spec.items?.enum;
+  if (Array.isArray(values) && values.length) {
+    return { id, component: 'ChoicePicker', label, variant: 'mutuallyExclusive',
+             options: enumOptions(values), value };
+  }
+  if (spec.type === 'boolean') return { id, component: 'CheckBox', label, value };
+
+  const variant =
+    spec.type === 'number' || spec.type === 'integer' ? 'number'
+    : /description|message|notes|details/.test(slot.name) ? 'longText'
+    : 'shortText';
+  return { id, component: 'TextField', label, variant, value };
+}
+
+function stepComponents(
+  step: PlanStep,
+  plan: ClarificationPlan,
+  toolName: string,
+): Component[] {
+  const fields = step.slots.map(inputFor);
+  const isLast = step.index === plan.steps.length - 1;
+  const isFirst = step.index === 0;
+
+  const actionIds = [
+    ...(plan.stepped && !isFirst ? ['back'] : []),
+    'cancel',
+    isLast ? 'submit' : 'next',
+  ];
+
+  // Same header shape as the review and submitted cards: an uppercase eyebrow
+  // then the detail. Uppercased in the string itself because no CSS of
+  // ours reaches inside these components.
+  //
+  // The headline is NOT Manrope. --a2ui-font-family-title applies only to
+  // markdown headings, and Text falls back to rendering the raw string unless
+  // a MarkdownRenderer is provided through Lit context, so "### Foo" renders as
+  // literal hashes. Reaching the display face here needs @a2ui/markdown-it
+  // wired into the surface, not a formatting trick.
+  const heading: Component[] = [
+    { id: 'eyebrow', component: 'Text',
+      text: plan.stepped
+        ? `STEP ${step.index + 1} OF ${plan.steps.length}`
+        : 'ONE MORE DETAIL',
+      variant: 'caption' },
+    { id: 'headline', component: 'Text', text: step.title, variant: 'body' },
+  ];
+
+  return [
+    // Every inline component is a card: the surface is a thing placed in the
+    // conversation, and the card edge is what separates it from the message
+    // bubbles either side. Card takes one child, so the content column sits
+    // inside it rather than being the root itself.
+    { id: 'root', component: 'Card', child: 'body' },
+    { id: 'body', component: 'Column',
+      children: [...heading.map(h => h.id), ...fields.map(f => f.id), 'actions'] },
+    ...heading,
+    ...fields,
+    { id: 'actions', component: 'Row', children: actionIds, justify: 'end' },
+
+    { id: 'back_label', component: 'Text', text: 'Back' },
+    { id: 'back', component: 'Button', child: 'back_label',
+      action: { event: { name: 'nxis.back', context: { tool: toolName, step: step.index } } } },
+
+    { id: 'cancel_label', component: 'Text', text: 'Cancel' },
+    { id: 'cancel', component: 'Button', child: 'cancel_label',
+      action: { event: { name: 'nxis.cancel', context: { tool: toolName } } } },
+
+    { id: 'next_label', component: 'Text', text: 'Next' },
+    { id: 'next', component: 'Button', child: 'next_label', variant: 'primary',
+      action: { event: { name: 'nxis.next', context: { tool: toolName, step: step.index } } } },
+
+    { id: 'submit_label', component: 'Text', text: 'Submit' },
+    { id: 'submit', component: 'Button', child: 'submit_label', variant: 'primary',
+      action: { event: { name: 'nxis.submit', context: { tool: toolName } } } },
+  ];
+}
+
+/** Create the surface, showing the first step. */
+export function emitAsk(
+  toolName: string,
+  plan: ClarificationPlan,
+  known: Record<string, unknown>,
+  surfaceId = 'ask',
+): A2uiMessage[] {
+  // Seed every gap so its input has a value to bind to, and carry the known
+  // values along: they are submitted with the answers even though no step
+  // ever displays them.
+  const form: Record<string, unknown> = { ...known };
+  for (const step of plan.steps) {
+    for (const slot of step.slots) {
+      if (form[slot.name] === undefined) {
+        form[slot.name] = slot.schema.type === 'boolean' ? false : '';
+      }
+    }
+  }
+
+  return [{
+    version: 'v1.0',
+    createSurface: {
+      surfaceId, catalogId: CATALOG,
+      components: stepComponents(plan.steps[0], plan, toolName),
+      dataModel: { form, step: 0 },
+    },
+  }];
+}
+
+/** Move to another step: components only, so answers already typed survive. */
+export function emitStep(
+  surfaceId: string,
+  toolName: string,
+  plan: ClarificationPlan,
+  index: number,
+): A2uiMessage[] {
+  return [
+    { version: 'v1.0',
+      updateComponents: { surfaceId, components: stepComponents(plan.steps[index], plan, toolName) } },
+    { version: 'v1.0', updateDataModel: { surfaceId, path: '/step', value: index } },
+  ];
+}
+
+/**
+ * The write confirmation: what is about to be sent, read-only.
+ *
+ * Not a form: nothing is missing, so there is nothing to fill in,
+ * showing inputs would imply otherwise and invite editing that was not asked
+ * for. Edit is available, as a button, for when it genuinely was.
+ */
+export function emitConfirm(
+  toolName: string,
+  slots: Slot[],
+  surfaceId = 'confirm',
+  submitLabel = 'Submit',
+): A2uiMessage[] {
+  const rows = slots.map(s => ({ label: labelFor(s), value: String(s.value ?? '') }));
+
+  const components: Component[] = [
+    // The review is a card for the same reason the inputs are: it is one
+    // reviewable object, and its edge is what says "this is what will be sent"
+    // rather than "this is more conversation".
+    { id: 'root', component: 'Card', child: 'body' },
+    { id: 'body', component: 'Column', children: ['eyebrow', 'headline', 'rows', 'actions'] },
+    { id: 'eyebrow', component: 'Text', text: 'READY TO SEND', variant: 'caption' },
+    { id: 'headline', component: 'Text', text: humanize(toolName), variant: 'body' },
+
+    { id: '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}' },
+
+    { id: 'actions', component: 'Row', children: ['edit', 'cancel', 'send'], justify: 'end' },
+    { id: 'edit_label', component: 'Text', text: 'Edit' },
+    { id: 'edit', component: 'Button', child: 'edit_label',
+      action: { event: { name: 'nxis.edit', context: { tool: toolName } } } },
+    { id: 'cancel_label', component: 'Text', text: 'Cancel' },
+    { id: 'cancel', component: 'Button', child: 'cancel_label',
+      action: { event: { name: 'nxis.cancel', context: { tool: toolName } } } },
+    { id: 'send_label', component: 'Text', text: submitLabel },
+    { id: 'send', component: 'Button', child: 'send_label', variant: 'primary',
+      action: { event: { name: 'nxis.submit', context: { tool: toolName } } } },
+  ];
+
+  return [{
+    version: 'v1.0',
+    createSurface: { surfaceId, catalogId: CATALOG, components, dataModel: { rows } },
+  }];
+}

package/src/a2ui/theme.ts

@@ -0,0 +1,134 @@
+/**
+ * Theme tokens for A2UI surfaces.
+ *
+ * The Lit renderer styles its components entirely through `--a2ui-*` custom
+ * properties. Those inherit across shadow boundaries, so setting them on the
+ * element containing `<a2ui-surface>` restyles everything inside it without
+ * `::part()`, a forked catalog, or a patched package.
+ *
+ * Values map onto the tokens the packaged element already declares, so surfaces
+ * follow the same palette rather than carrying a second copy of it.
+ *
+ * The rules encoded here:
+ *   - sans first: Manrope for the title, Inter for everything readable
+ *   - mono for labels only: field labels and tags, never body copy
+ *   - blue for trust and action: the primary button and focus ring
+ *   - light by default
+ */
+export const A2UI_THEME_CSS = `
+  .a2ui-scope {
+    /* Core roles */
+    --a2ui-color-primary: var(--blue);
+    --a2ui-color-primary-hover: var(--blue-strong);
+    --a2ui-color-primary-dark: var(--blue-strong);
+    --a2ui-color-primary-light: var(--blue-tint);
+    --a2ui-color-on-primary: #FFFFFF;
+    --a2ui-color-secondary: var(--surface);
+    --a2ui-color-secondary-hover: var(--surface-2);
+    --a2ui-color-on-secondary: var(--ink);
+    --a2ui-color-surface: var(--bg);
+    --a2ui-color-on-surface: var(--ink);
+    --a2ui-color-on-background: var(--ink);
+    --a2ui-color-border: var(--border);
+    --a2ui-color-input: var(--bg);
+    --a2ui-color-on-input: var(--ink);
+
+    /* Type — Manrope displays, Inter reads (design.md §1) */
+    --a2ui-font-family-title: var(--display);
+    --a2ui-font-size-xs: 11px;   /* eyebrow / label size, matching .dc-row dt */
+    --a2ui-font-size-s: 13px;
+    --a2ui-font-size-m: 14px;
+    --a2ui-font-size-l: 18px;   /* markdown ### → .dc-title size */
+    --a2ui-font-size-xl: 22px;
+    --a2ui-font-size-2xl: 31px;
+    --a2ui-line-height-body: 1.65;
+    --a2ui-line-height-headings: 1.25;
+    --a2ui-text-color-text: var(--ink);
+    --a2ui-text-caption-color: var(--ink-3);  /* same muted label ink as .dc-row dt */
+    --a2ui-text-a-color: var(--blue);
+    --a2ui-text-a-font-weight: 600;
+
+    /* Radii — 14px cards, 10px buttons, 999px pills (design.md §1) */
+    --a2ui-border-radius: var(--radius-sm);
+    --a2ui-border: 1px solid var(--border);
+    --a2ui-border-width: 1px;
+
+    --a2ui-card-background: var(--bg);
+    --a2ui-card-border: 1px solid var(--border);
+    --a2ui-card-border-radius: var(--radius);
+    --a2ui-card-box-shadow: var(--shadow-sm);
+    /* 22px matches .detailcard, so an input card and a review card sitting in
+       the same thread share one rhythm rather than three inherited paddings. */
+    --a2ui-card-padding: 22px;
+    --a2ui-card-margin: 0;
+
+    /* Buttons: radius 10, weight 600, one primary per view (design.md §4) */
+    --a2ui-button-border-radius: var(--radius-sm);
+    --a2ui-button-font-weight: 600;
+    --a2ui-button-padding: 11px 20px;
+    --a2ui-button-border: 1px solid var(--border-strong);
+    --a2ui-button-background: var(--bg);
+    --a2ui-button-box-shadow: none;
+    /* Buttons sit in a Row with its own gap; a margin here would double it. */
+    --a2ui-button-margin: 0;
+    /* The label is a Text child, so the button's own colour comes from the
+       secondary text token — this is what makes a default A2UI button read as
+       .btn.ghost rather than as unstyled chrome. */
+    --a2ui-color-on-secondary: var(--ink);
+    --a2ui-color-secondary-hover: var(--surface-2);
+
+    /* Inputs */
+    --a2ui-textfield-border: 1px solid var(--border);
+    --a2ui-textfield-border-radius: var(--radius-sm);
+    --a2ui-textfield-padding: 10px 12px;
+    --a2ui-textfield-color-border-focus: var(--blue);
+    --a2ui-textfield-color-error: var(--red);
+    --a2ui-textfield-label-font-size: 11px;
+    --a2ui-textfield-label-font-weight: 500;
+
+    --a2ui-checkbox-border: 1px solid var(--border-strong);
+    --a2ui-checkbox-border-radius: 6px;
+    --a2ui-checkbox-background: var(--bg);
+    --a2ui-checkbox-color-error: var(--red);
+    --a2ui-checkbox-size: 18px;
+    --a2ui-checkbox-gap: 10px;
+    --a2ui-checkbox-label-font-size: 14px;
+    --a2ui-checkbox-label-font-weight: 400;
+
+    /* Tags render as ChoicePicker chips / caption Text — pill radius */
+    --a2ui-choicepicker-chip-border-radius: var(--radius-pill);
+    --a2ui-choicepicker-chip-padding: 6px 12px;
+    --a2ui-choicepicker-label-color: var(--ink-3);
+    --a2ui-choicepicker-label-font-size: 11px;
+    --a2ui-choicepicker-label-font-weight: 500;
+
+    /* Rhythm */
+    --a2ui-spacing-xs: 4px;
+    --a2ui-spacing-s: 8px;
+    --a2ui-spacing-m: 12px;
+    --a2ui-spacing-l: 18px;
+    --a2ui-column-gap: 12px;
+    --a2ui-row-gap: 10px;
+    --a2ui-list-gap: 12px;
+    --a2ui-list-padding: 0;
+
+    font-family: var(--sans);
+    color: var(--ink);
+  }
+
+  /*
+   * Mono for labels only (design.md §3.2). The renderer has no token for label
+   * *family*, only size and weight, so the eyebrow treatment is applied to the
+   * label elements directly. Scoped to .a2ui-scope so it cannot leak.
+   */
+  .a2ui-scope a2ui-surface::part(label),
+  .a2ui-scope label {
+    font-family: var(--mono);
+    letter-spacing: .14em;
+    text-transform: uppercase;
+    color: var(--ink-3);
+  }
+`;
+
+/** Signal Blue — the one theme value A2UI itself carries on createSurface. */
+export const NXIS_PRIMARY = '#2563EB';

package/src/a2ui/to-v09.ts

@@ -0,0 +1,118 @@
+/**
+ * Downgrades A2UI v1.0 messages to v0.9.
+ *
+ * The emitters target v1.0, which is the documented spec and the one with
+ * published JSON Schemas, but available renderers support v0.9 and earlier, so
+ * messages are downgraded before rendering.
+ *
+ * Two mechanical differences:
+ *
+ *  1. `version` is the string "v0.9", not "v1.0".
+ *  2. v0.9's `createSurface` carries only surfaceId/catalogId: it rejects
+ *     inline `components` and `dataModel` as additional properties. They have
+ *     to follow as separate `updateComponents` / `updateDataModel` messages for
+ *     the same surfaceId. So one v1.0 message becomes up to three.
+ *
+ * No longer needed once a v1.0 renderer is available.
+ *
+ * @module
+ */
+
+import type { A2uiMessage } from './emit.js';
+import { NXIS_PRIMARY } from './theme.js';
+
+type Msg = Record<string, any>;
+
+/**
+ * The catalog is versioned alongside the protocol, and the renderer looks it up
+ * by exact id, so a v1.0 id against a v0.9 catalog registry throws
+ * "Catalog not found" rather than falling back.
+ */
+const CATALOG_V1 = 'https://a2ui.org/specification/v1_0/catalogs/basic/catalog.json';
+const CATALOG_V09 = 'https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json';
+
+const downgradeCatalog = (id: string | undefined): string | undefined =>
+  id === CATALOG_V1 ? CATALOG_V09 : id;
+
+/**
+ * v1.0 interpolates with `${expr}` inside a string. v0.9 has no interpolation
+ * at all: a dynamic value is a DataBinding object, `{ path }`. A `${title}`
+ * left as-is is not an error: it renders as the literal characters, which is
+ * how it first showed up on the verification page.
+ *
+ * Only a string that is *entirely* one expression can convert. "Hi ${name}"
+ * has no v0.9 equivalent, so it is left alone and will render literally; the
+ * emitters avoid mixed interpolation for that reason.
+ */
+const INTERPOLATION = /^\$\{([^}]+)\}$/;
+
+function bindStrings(value: unknown): unknown {
+  if (typeof value === 'string') {
+    const m = INTERPOLATION.exec(value);
+    return m ? { path: m[1] } : value;
+  }
+  if (Array.isArray(value)) return value.map(bindStrings);
+  if (value && typeof value === 'object') {
+    const out: Msg = {};
+    for (const [k, v] of Object.entries(value as Msg)) {
+      // Identity and structure keys are never data-bound.
+      out[k] = k === 'id' || k === 'component' || k === 'componentId' ? v : bindStrings(v);
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Downgrade v1.0 messages to v0.9.
+ *
+ * @param messages - The messages as authored by the emitters.
+ * @returns The equivalent v0.9 messages, which may be more numerous because a
+ * v1.0 surface creation splits into separate component and data updates.
+ */
+export function toV09(messages: A2uiMessage[]): Msg[] {
+  const out: Msg[] = [];
+
+  for (const msg of messages as unknown as Msg[]) {
+    if (msg.createSurface) {
+      const { surfaceId, catalogId, components, dataModel } = msg.createSurface;
+
+      // `theme` exists in v0.9 and was dropped in v1.0, so it is set here
+      // rather than in the emitters, which must stay v1.0-valid. The CSS
+      // custom properties do the real styling; this carries the accent for any
+      // renderer that never sees our stylesheet.
+      out.push({
+        version: 'v0.9',
+        createSurface: {
+          surfaceId,
+          catalogId: downgradeCatalog(catalogId),
+          theme: { primaryColor: NXIS_PRIMARY },
+        },
+      });
+
+      if (components) {
+        out.push({ version: 'v0.9', updateComponents: { surfaceId, components: bindStrings(components) } });
+      }
+      // v0.9 patches one path at a time, so a whole-model seed becomes one
+      // message per top-level key rather than a single root write. The payload
+      // key is `value` and the object is additionalProperties:false, so a
+      // wrong name here is rejected outright rather than ignored.
+      if (dataModel) {
+        for (const [key, value] of Object.entries(dataModel)) {
+          out.push({ version: 'v0.9', updateDataModel: { surfaceId, path: `/${key}`, value } });
+        }
+      }
+      continue;
+    }
+
+    if (msg.updateDataModel) {
+      const { surfaceId, path, value } = msg.updateDataModel;
+      out.push({ version: 'v0.9', updateDataModel: { surfaceId, path, value } });
+      continue;
+    }
+
+    out.push({ ...msg, version: 'v0.9' });
+  }
+
+  return out;
+}