@stalwart-agents/agent-ui 0.0.0-stage → 1.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stalwart Technologies Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,48 @@
-# Temporary Holding Version
+# @stalwart-agents/agent-ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A white-label interface for an agent Stalwart routes and checks: streamed replies,
+confirmations that show where each argument came from, refusals with their rule,
+rollbacks with what was undone and what could not be, and questions to a person when an
+outcome is unknown or an undo is stuck.
+
+```sh
+npm install @stalwart-agents/agent-ui
+```
+
+```html
+<script type="module" src="https://your.host/agent-ui/index.js"></script>
+<stalwart-chat thread="u-17" base="/agent"></stalwart-chat>
+```
+
+```jsx
+import { StalwartChat } from "@stalwart-agents/agent-ui/react";
+<StalwartChat thread="u-17" base="/agent" />
+```
+
+- **Talks to your backend only**: the resume server (`stalwart_agents.langchain.server`, or
+  `stalwart serve`). No telemetry, no font, no request to any other host.
+- **White-label**: every colour and size is a `--stalwart-*` CSS custom property, every
+  region a `::part`, `header` and `footer` slots, no brand of ours, both colour schemes
+  (or `theme="light|dark"`).
+- **Every string replaceable**: `setStrings({ send: "Enviar", approve: "Aprovar" })`.
+- **Small**: under 45 kB compressed, without React (`npm run size` checks it).
+- **Thumbs, where you turn them on**: `<stalwart-chat thumbs>` puts a thumb up and a thumb
+  down under each reply and each question the bot asks, with one line saying that a
+  rated message is kept to improve the assistant and nothing else of the conversation. A
+  pressed thumb shows as pressed and can be changed once (up, then down, posts down). The
+  thumb goes to `POST /threads/{id}/feedback` with the reply's id, from the session that
+  was shown it (`stalwart serve` takes it). Off where `thumbs` is not set.
+
+```html
+<stalwart-chat thread="u-17" base="/agent" thumbs></stalwart-chat>
+```
+
+| Element | Shows |
+|---|---|
+| `<stalwart-chat>` | the conversation, and whatever waits for a decision |
+| `<stalwart-confirm>` | one call that waits: its arguments with their origins, the reasons, the irreversible warning, and *approve / skip / cancel all* |
+| `<stalwart-decision>` | a refusal in one sentence, its rule on disclosure |
+| `<stalwart-rollback>` | what a run undid, and what it could not |
+| `<stalwart-trace>` | a thread's steps |
+
+MIT licensed.

package/index.d.ts

@@ -0,0 +1,88 @@
+/** An interrupt the resume server lists: what waits for a person. */
+export interface Interrupt {
+  id: string;
+  kind: "confirm" | "outcome_unknown" | "saga_stuck" | "ask" | "delegate";
+  tool: string;
+  /** Each argument with the origin it came from: `typed`, `reply`, `context`, `computed`, `model`, `result:<step>`, `agent:<name>`. */
+  arguments: { name: string; value: unknown; origin: string }[];
+  reasons: string[];
+  irreversible: boolean;
+  wording: string;
+  token?: string;
+  decisions: string[];
+  /** What the kind adds: a `delegate`'s `turn`, a stuck undo's `remaining`. */
+  detail?: Record<string, unknown>;
+}
+
+/** What a turn or a resume answers. */
+export interface Answer {
+  thread: string;
+  reply: string | null;
+  interrupts: Interrupt[];
+  /** The router's refusal of the turn, with its rule; null where it did not refuse. */
+  refusal?: { sentence: string; rule: string } | null;
+  /** What a rollback of the turn's run undid, and what it could not; null where nothing was rolled back. */
+  rollback?: { failed: string | null; summary: string; undone: string[]; not_undoable: string[] } | null;
+  /** The new interrupts a webhook could not be told of; the turn ran all the same. */
+  not_notified?: { id: string; error: string }[];
+  /** The reply's id, which a thumb on it names (`stalwart serve`). */
+  message?: string;
+  /** The session the reply was shown to; the client sends it back as `Stalwart-Session`. */
+  session?: string;
+}
+
+/** What a thumb answers: the reply rated, the thumb, and the service's answer to the record. */
+export interface Rated {
+  thread: string;
+  message: string;
+  thumb: "up" | "down";
+  recorded?: Record<string, unknown>;
+}
+
+/** The team's backend, by its base address: the resume server's routes, and no other host. */
+export declare function backend(
+  base?: string,
+  fetcher?: typeof fetch,
+): {
+  turn(thread: string, text: string): Promise<Answer>;
+  interrupts(thread: string): Promise<{ thread: string; interrupts: Interrupt[] }>;
+  resume(thread: string, interrupt: Interrupt, decision: string): Promise<Answer>;
+  rollback(thread: string): Promise<Answer>;
+  /** A person's thumb on a reply, by the id its answer named. */
+  feedback(thread: string, message: string, thumb: "up" | "down"): Promise<Rated>;
+  streamUrl(thread: string): string;
+};
+
+/** The strings as shipped, by key. */
+export declare const DEFAULT_STRINGS: Readonly<Record<string, string>>;
+/** Replaces any of the interface's strings. */
+export declare function setStrings(replacements: Partial<Record<string, string>>): void;
+/** A string by its key, its `{name}`s filled. */
+export declare function t(key: string, values?: Record<string, unknown>): string;
+/** Defines the five elements under their names, once. Importing the module does it. */
+export declare function define(): void;
+
+/** `<stalwart-chat base="" thread="" thumbs>`: the whole interaction; `thumbs` shows a thumb up and down under each reply. */
+export declare class StalwartChat extends HTMLElement {
+  readonly thread: string;
+  /** Makes the step stream's connection; the page's own `EventSource` where not set. */
+  eventSource?: (url: string) => EventSource;
+  submit(text: string): Promise<void>;
+  decide(interrupt: Interrupt, decision: string): Promise<void>;
+  /** Posts a thumb on the reply `message` names; a pressed thumb is not posted again, and a thumb changes once. */
+  rate(message: string, thumb: "up" | "down"): Promise<void>;
+}
+/** `<stalwart-confirm>`: a call that waits for a person; dispatches `stalwart-decision`. */
+export declare class StalwartConfirm extends HTMLElement {
+  interrupt: Interrupt | undefined;
+}
+/** `<stalwart-decision sentence="" rule="">`: a refusal and its rule. */
+export declare class StalwartDecision extends HTMLElement {}
+/** `<stalwart-rollback>`: what a run undid, and what it could not. */
+export declare class StalwartRollback extends HTMLElement {
+  report: { undone?: string[]; notUndoable?: string[]; summary?: string };
+}
+/** `<stalwart-trace>`: a thread's steps. */
+export declare class StalwartTrace extends HTMLElement {
+  events: { id: number; step: number; nodes: string[] }[];
+}

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@stalwart-agents/agent-ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.3",
+  "description": "A white-label interface for an agent run by Stalwart: chat, confirmations with each argument's origin, refusals with their rule, rollbacks and resumes, against your own backend.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./react": {
+      "types": "./react.d.ts",
+      "default": "./src/react.js"
+    }
+  },
+  "files": [
+    "src",
+    "index.d.ts",
+    "react.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": [
+    "./src/index.js"
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "happy-dom": "20.14.5"
+  },
+  "scripts": {
+    "test": "node --test test/elements.test.mjs",
+    "size": "node scripts/size.mjs",
+    "vendor": "node scripts/vendor.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Stalwart-Holdings/quasilinear-solver.git",
+    "directory": "packages/agent-ui"
+  },
+  "homepage": "https://stalwart.it",
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/react.d.ts

@@ -0,0 +1,4 @@
+/** `<stalwart-chat>` as a React component. */
+export declare function StalwartChat(props: { thread?: string; base?: string; theme?: "light" | "dark"; children?: unknown }): unknown;
+/** `<stalwart-decision>` as a React component: a refusal and its rule. */
+export declare function StalwartDecision(props: { sentence: string; rule?: string }): unknown;

package/src/client.js

@@ -0,0 +1,56 @@
+/**
+ * The calls the interface makes: to the team's own backend, the resume server, and nowhere else.
+ *
+ * Every request goes to `base` + one of the server's routes. Nothing is sent to any
+ * other host -- no telemetry, no font, no script. Each request names the page's session
+ * (`Stalwart-Session`) once the server has handed one out, so a thumb is taken only from
+ * the session that was shown the reply.
+ */
+
+/**
+ * The team's backend, by its base address.
+ * @param {string} base where the resume server is mounted ("" for the same origin).
+ * @param {typeof fetch} [fetcher] the fetch to use; the page's own where not given.
+ * @returns {{turn: Function, interrupts: Function, resume: Function, rollback: Function, feedback: Function, streamUrl: Function}}
+ */
+export function backend(base = "", fetcher = globalThis.fetch.bind(globalThis)) {
+  const root = base.replace(/\/$/, "");
+  const at = (thread, what) => `${root}/threads/${encodeURIComponent(thread)}/${what}`;
+  let session = "";
+
+  async function send(url, method, body) {
+    const headers = body === undefined ? {} : { "Content-Type": "application/json" };
+    if (session) headers["Stalwart-Session"] = session;
+    const answer = await fetcher(url, {
+      method,
+      headers,
+      body: body === undefined ? undefined : JSON.stringify(body),
+      credentials: "same-origin",
+    });
+    const document = await answer.json().catch(() => ({}));
+    if (!answer.ok) {
+      const failure = new Error(document.message || `${answer.status}`);
+      failure.status = answer.status;
+      failure.code = document.code;
+      throw failure;
+    }
+    if (typeof document.session === "string" && document.session) session = document.session;
+    return document;
+  }
+
+  return {
+    /** One turn: `{reply, interrupts}`. */
+    turn: (thread, text) => send(at(thread, "messages"), "POST", { text }),
+    /** What waits for a person: `{interrupts}`. */
+    interrupts: (thread) => send(at(thread, "interrupts"), "GET"),
+    /** A person's decision on one interrupt, by its id: `{reply, interrupts}`. */
+    resume: (thread, interrupt, decision) =>
+      send(at(thread, "resume"), "POST", { interrupt_id: interrupt.id, decision, token: interrupt.token }),
+    /** An operator's rollback. */
+    rollback: (thread) => send(at(thread, "rollback"), "POST", {}),
+    /** A person's thumb on a reply, by the id its answer named: `up` or `down`. */
+    feedback: (thread, message, thumb) => send(at(thread, "feedback"), "POST", { message, thumb }),
+    /** The address of the thread's step stream, for an EventSource. */
+    streamUrl: (thread) => at(thread, "stream"),
+  };
+}

package/src/elements.js

@@ -0,0 +1,456 @@
+/**
+ * The custom elements: `<stalwart-chat>`, `<stalwart-confirm>`, `<stalwart-decision>`,
+ * `<stalwart-rollback>` and `<stalwart-trace>`.
+ *
+ * White-label by design: no brand of ours, every colour and size a CSS custom property
+ * (`--stalwart-*`), every region a `::part`, every string from the table in `strings.js`,
+ * both colour schemes. They talk to the team's backend only.
+ */
+
+import { backend } from "./client.js";
+import { t } from "./strings.js";
+
+const BASE_STYLE = `
+:host {
+  --stalwart-bg: #ffffff; --stalwart-fg: #1a1a1a; --stalwart-muted: #595959; --stalwart-line: #d0d0d0;
+  --stalwart-accent: #0b57d0; --stalwart-accent-fg: #ffffff; --stalwart-warn: #8a4b00; --stalwart-bad: #b3261e;
+  --stalwart-radius: 8px; --stalwart-gap: 12px; --stalwart-font: system-ui, sans-serif;
+  display: block; color: var(--stalwart-fg); background: var(--stalwart-bg); font: 1rem/1.5 var(--stalwart-font);
+  box-sizing: border-box; max-width: 100%;
+}
+@media (prefers-color-scheme: dark) {
+  :host { --stalwart-bg: #121212; --stalwart-fg: #f1f1f1; --stalwart-muted: #bdbdbd; --stalwart-line: #3c3c3c;
+          --stalwart-accent: #8ab4f8; --stalwart-accent-fg: #0b0b0b; --stalwart-warn: #ffb74d; --stalwart-bad: #f28b82; }
+}
+:host([theme="light"]) { color-scheme: light; }
+:host([theme="dark"]) { --stalwart-bg: #121212; --stalwart-fg: #f1f1f1; --stalwart-muted: #bdbdbd; --stalwart-line: #3c3c3c;
+          --stalwart-accent: #8ab4f8; --stalwart-accent-fg: #0b0b0b; --stalwart-warn: #ffb74d; --stalwart-bad: #f28b82; }
+*, *::before, *::after { box-sizing: inherit; }
+button { font: inherit; min-height: 44px; padding: 8px 16px; border-radius: var(--stalwart-radius);
+         border: 1px solid var(--stalwart-line); background: transparent; color: inherit; cursor: pointer; }
+button.primary { background: var(--stalwart-accent); color: var(--stalwart-accent-fg); border-color: var(--stalwart-accent); }
+button:focus-visible, input:focus-visible, summary:focus-visible { outline: 3px solid var(--stalwart-accent); outline-offset: 2px; }
+.muted { color: var(--stalwart-muted); }
+.warn { color: var(--stalwart-warn); }
+.bad { color: var(--stalwart-bad); }
+`;
+
+function element(tag, attributes = {}, children = []) {
+  const node = document.createElement(tag);
+  for (const [name, value] of Object.entries(attributes)) {
+    if (value === undefined || value === null || value === false) continue;
+    if (name === "text") node.textContent = String(value);
+    else node.setAttribute(name, value === true ? "" : String(value));
+  }
+  for (const child of children) if (child) node.append(child);
+  return node;
+}
+
+function shadow(host, css) {
+  const root = host.shadowRoot || host.attachShadow({ mode: "open" });
+  root.replaceChildren(element("style", { text: BASE_STYLE + css }));
+  return root;
+}
+
+function originLabel(origin) {
+  const head = String(origin || "model").split(":")[0];
+  return t(`origin_${head}`);
+}
+
+/**
+ * `<stalwart-confirm>`: a call that waits for a person.
+ *
+ * Property `interrupt`: the payload the server lists -- `{id, kind, tool, arguments,
+ * reasons, irreversible, wording, token, decisions}`. Each argument is shown with where
+ * it came from. Answering dispatches `stalwart-decision` with `{interrupt, decision}`:
+ * `approve`, `skip` or `cancel_all` for a confirmation; the kind's own decisions for an
+ * unknown outcome or a stuck undo.
+ */
+export class StalwartConfirm extends HTMLElement {
+  set interrupt(value) {
+    this._interrupt = value;
+    this.render();
+  }
+
+  get interrupt() {
+    return this._interrupt;
+  }
+
+  connectedCallback() {
+    this.render();
+  }
+
+  render() {
+    const interrupt = this._interrupt;
+    const root = shadow(this, `
+      section { border: 1px solid var(--stalwart-line); border-radius: var(--stalwart-radius); padding: var(--stalwart-gap); }
+      h2 { font-size: 1.1rem; margin: 0 0 8px; }
+      dl { display: grid; grid-template-columns: minmax(0, max-content) minmax(0, 1fr); gap: 4px 12px; margin: 8px 0; }
+      dt { font-weight: 600; overflow-wrap: anywhere; } dd { margin: 0; overflow-wrap: anywhere; }
+      .choices { display: flex; flex-wrap: wrap; gap: 8px; margin-top: 12px; }`);
+    if (!interrupt) return;
+    const kind = interrupt.kind || "confirm";
+    const titles = { confirm: "confirmTitle", outcome_unknown: "unknownTitle", saga_stuck: "stuck", delegate: "delegateTitle" };
+    const heading = element("h2", { id: "title", text: t(titles[kind] || "confirmTitle", { tool: interrupt.tool }) });
+    const section = element("section", { part: "confirm", role: "group", "aria-labelledby": "title" }, [heading]);
+    if (interrupt.wording && kind !== "delegate") section.append(element("p", { text: interrupt.wording }));
+    if (kind === "delegate" && interrupt.detail && interrupt.detail.turn) {
+      section.append(element("blockquote", { part: "turn", text: interrupt.detail.turn }));
+    }
+    const args = interrupt.arguments || [];
+    if (args.length) {
+      const list = element("dl", { part: "arguments", "aria-label": t("argumentsTitle") });
+      for (const argument of args) {
+        list.append(element("dt", { text: argument.name }));
+        list.append(element("dd", {}, [
+          element("span", { text: typeof argument.value === "string" ? argument.value : JSON.stringify(argument.value) }),
+          element("span", { class: "muted", text: ` (${originLabel(argument.origin)})` }),
+        ]));
+      }
+      section.append(element("h3", { class: "muted", text: t("argumentsTitle") }), list);
+    }
+    if ((interrupt.reasons || []).length) {
+      const reasons = element("ul", { part: "reasons" });
+      for (const reason of interrupt.reasons) reasons.append(element("li", { text: reason }));
+      section.append(element("h3", { class: "muted", text: t("reasonsTitle") }), reasons);
+    }
+    if (interrupt.irreversible) section.append(element("p", { class: "warn", part: "irreversible", text: t("irreversible") }));
+    const labels = { approve: kind === "delegate" ? "delegateApprove" : "approve", skip: "skip", cancel_all: "cancelAll",
+                     happened: "happened", did_not_happen: "didNotHappen", retry: "retry", done_by_hand: "doneByHand",
+                     abandon: "abandon", decline: "decline" };
+    const choices = element("div", { class: "choices", part: "choices" });
+    for (const decision of interrupt.decisions || ["approve", "skip", "cancel_all"]) {
+      const button = element("button", { type: "button", class: decision === "approve" ? "primary" : undefined,
+                                          "data-decision": decision, text: t(labels[decision] || decision) });
+      button.addEventListener("click", () => this.dispatchEvent(new CustomEvent("stalwart-decision", {
+        bubbles: true, composed: true, detail: { interrupt, decision },
+      })));
+      choices.append(button);
+    }
+    section.append(choices);
+    root.append(section);
+  }
+}
+
+/**
+ * `<stalwart-decision>`: a refusal, in one sentence, with the rule's name on disclosure.
+ * Attributes: `sentence`, `rule`.
+ */
+export class StalwartDecision extends HTMLElement {
+  static get observedAttributes() {
+    return ["sentence", "rule"];
+  }
+
+  attributeChangedCallback() {
+    this.render();
+  }
+
+  connectedCallback() {
+    this.render();
+  }
+
+  render() {
+    const root = shadow(this, `p { margin: 0; } details { margin-top: 4px; } summary { cursor: pointer; }`);
+    const box = element("div", { part: "decision", role: "status" }, [
+      element("p", {}, [element("strong", { class: "bad", text: `${t("refused")}: ` }), document.createTextNode(this.getAttribute("sentence") || "")]),
+    ]);
+    const rule = this.getAttribute("rule");
+    if (rule) {
+      box.append(element("details", { part: "rule" }, [element("summary", { text: t("showRule") }),
+                                                      element("p", { class: "muted", text: `${t("rule")}: ${rule}` })]));
+    }
+    root.append(box);
+  }
+}
+
+/**
+ * `<stalwart-rollback>`: what a run undid, and what it could not.
+ * Property `report`: `{undone: [tool, ...], notUndoable: [tool, ...], summary}`.
+ */
+export class StalwartRollback extends HTMLElement {
+  set report(value) {
+    this._report = value;
+    this.render();
+  }
+
+  connectedCallback() {
+    this.render();
+  }
+
+  render() {
+    const report = this._report || {};
+    const root = shadow(this, `ul { margin: 4px 0; padding-left: 20px; }`);
+    const box = element("section", { part: "rollback", "aria-label": t("rollbackTitle") }, [element("h3", { text: t("rollbackTitle") })]);
+    if (report.summary) box.append(element("p", { text: report.summary }));
+    for (const [key, items] of [["undone", report.undone], ["notUndoable", report.notUndoable]]) {
+      if (!items || !items.length) continue;
+      const list = element("ul");
+      for (const item of items) list.append(element("li", { text: item }));
+      box.append(element("p", { class: key === "notUndoable" ? "warn" : "muted", text: t(key) }), list);
+    }
+    root.append(box);
+  }
+}
+
+/**
+ * `<stalwart-trace>`: a thread's steps, as the stream reports them.
+ * Property `events`: the stream's events, `{id, step, nodes, messages, interrupts}`.
+ */
+export class StalwartTrace extends HTMLElement {
+  set events(value) {
+    this._events = value || [];
+    this.render();
+  }
+
+  connectedCallback() {
+    this.render();
+  }
+
+  render() {
+    const root = shadow(this, `ol { padding-left: 20px; } li { margin: 2px 0; overflow-wrap: anywhere; }`);
+    const list = element("ol", { part: "trace", "aria-label": t("traceTitle") });
+    for (const event of this._events || []) {
+      const text = `${t("step", { step: event.step })}: ${(event.nodes || []).join(", ")}`;
+      list.append(element("li", { text }));
+    }
+    root.append(element("h3", { text: t("traceTitle") }), list);
+  }
+}
+
+/**
+ * `<stalwart-chat>`: the whole interaction against the team's backend.
+ *
+ * Attributes: `base` (where the resume server is mounted; the same origin where not
+ * set), `thread` (the conversation's id), `thumbs` (a thumb up and a thumb down under
+ * each reply and each question the bot asks, with one line saying what a rating keeps;
+ * off where not set). A pressed thumb shows as pressed and can be changed once. Shows each
+ * confirmation with its arguments'
+ * origins, each refusal with its rule and each rollback with what it undid -- from the
+ * answer's `refusal` and `rollback`, never from the reply's words -- and asks the person
+ * when an outcome is unknown, an undo is stuck, or a turn may go to the assistant. Follows
+ * the thread's step stream while a run goes on; a dropped stream reconnects from the
+ * last step it saw, and what waits is read again from the server.
+ *
+ * Property `eventSource`: makes the stream's connection, `(url) => EventSource`; the
+ * page's own `EventSource` where not set.
+ */
+export class StalwartChat extends HTMLElement {
+  constructor() {
+    super();
+    this._log = [];
+    this._pending = [];
+    this._busy = false;
+    this._events = [];
+    this._reconnecting = false;
+    this._thumbs = new Map();
+    this._asking = null;
+  }
+
+  disconnectedCallback() {
+    this.closeStream();
+  }
+
+  /** Follows the thread's steps while a run goes on, into `<stalwart-trace>`. */
+  openStream() {
+    const make = this.eventSource || (globalThis.EventSource ? (url) => new globalThis.EventSource(url) : null);
+    if (!make || this._stream) return;
+    const source = make(this.api.streamUrl(this.thread));
+    this._stream = source;
+    source.addEventListener("step", (event) => {
+      this._reconnecting = false;
+      try {
+        const step = JSON.parse(event.data);
+        if (!this._events.some((seen) => seen.id === step.id)) this._events.push(step);
+      } catch {
+        return;
+      }
+      this.render();
+    });
+    source.addEventListener("end", () => this.closeStream());
+    // EventSource reconnects by itself and sends the last step's id: the stream goes on from there.
+    source.onerror = () => {
+      this._reconnecting = true;
+      this.render();
+      this.refresh();
+    };
+  }
+
+  closeStream() {
+    if (this._stream) this._stream.close();
+    this._stream = null;
+    if (this._reconnecting) {
+      this._reconnecting = false;
+      this.render();
+    }
+  }
+
+  connectedCallback() {
+    this.api = backend(this.getAttribute("base") || "", this.fetcher);
+    this.render();
+    this.refresh();
+  }
+
+  get thread() {
+    return this.getAttribute("thread") || "default";
+  }
+
+  async refresh() {
+    try {
+      const listed = await this.api.interrupts(this.thread);
+      this._pending = listed.interrupts || [];
+      this.render();
+    } catch {
+      /* no thread yet: nothing waits */
+    }
+  }
+
+  async submit(text) {
+    if (!text.trim() || this._busy) return;
+    this._log.push({ who: "user", text });
+    this._busy = true;
+    this.render();
+    this.openStream();
+    try {
+      this.show(await this.api.turn(this.thread, text));
+    } catch (failure) {
+      this._log.push({ who: "error", text: t("error", { message: failure.message }) });
+    }
+    this._busy = false;
+    this.render();
+  }
+
+  async decide(interrupt, decision) {
+    this._busy = true;
+    this.render();
+    this.openStream();
+    try {
+      this.show(await this.api.resume(this.thread, interrupt, decision));
+    } catch (failure) {
+      if (failure.code === "interrupt_stale") await this.refresh();
+      else this._log.push({ who: "error", text: t("error", { message: failure.message }) });
+    }
+    this._busy = false;
+    this.render();
+  }
+
+  show(answer) {
+    const message = answer.message;
+    const before = this._log.length;
+    if (answer.refusal) {
+      this._log.push({ who: "refusal", text: answer.refusal.sentence || answer.reply || "", rule: answer.refusal.rule, message });
+    } else if (answer.rollback) {
+      this._log.push({ who: "rollback", message, report: { summary: answer.rollback.summary || answer.reply,
+                                                           undone: answer.rollback.undone, notUndoable: answer.rollback.not_undoable } });
+    } else if (answer.reply) {
+      this._log.push({ who: "assistant", text: answer.reply, message });
+    }
+    this._pending = answer.interrupts || [];
+    // A question with no reply of its own (a confirmation, a hand-over) is rated under the question.
+    this._asking = this._log.length === before && this._pending.length ? message || null : null;
+  }
+
+  /** Posts a thumb on the reply @p message names; a pressed thumb is not posted again, and a thumb changes once. */
+  async rate(message, thumb) {
+    const held = this._thumbs.get(message);
+    if (!message || (held && (held.thumb === thumb || held.changed))) return;
+    try {
+      await this.api.feedback(this.thread, message, thumb);
+      this._thumbs.set(message, { thumb, changed: Boolean(held) });
+    } catch (failure) {
+      this._log.push({ who: "error", text: t("error", { message: failure.message }) });
+    }
+    this.render();
+  }
+
+  thumbsFor(message) {
+    if (!this.hasAttribute("thumbs") || !message) return null;
+    const held = this._thumbs.get(message) || {};
+    const bar = element("div", { part: "thumbs", class: "thumbs" });
+    for (const thumb of ["up", "down"]) {
+      const button = element("button", { type: "button", "data-thumb": thumb, "aria-pressed": held.thumb === thumb ? "true" : "false",
+                                         disabled: Boolean(held.changed), text: t(thumb === "up" ? "thumbUp" : "thumbDown") });
+      button.addEventListener("click", () => this.rate(message, thumb));
+      bar.append(button);
+    }
+    bar.append(element("p", { class: "muted", part: "thumbs-notice", text: t("thumbsNotice") }));
+    return bar;
+  }
+
+  render() {
+    const root = shadow(this, `
+      .log { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 8px; }
+      .log li { padding: 8px 12px; border-radius: var(--stalwart-radius); max-width: 100%; overflow-wrap: anywhere; }
+      .user { align-self: flex-end; background: var(--stalwart-accent); color: var(--stalwart-accent-fg); }
+      .assistant { align-self: flex-start; border: 1px solid var(--stalwart-line); }
+      form { display: flex; gap: 8px; margin-top: var(--stalwart-gap); }
+      input { flex: 1; min-width: 0; font: inherit; padding: 8px; border-radius: var(--stalwart-radius);
+              border: 1px solid var(--stalwart-line); background: var(--stalwart-bg); color: var(--stalwart-fg); min-height: 44px; }
+      .visually-hidden { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); }
+      stalwart-confirm { margin-top: var(--stalwart-gap); }
+      .thumbs { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; margin-top: 8px; }
+      .thumbs p { margin: 0; font-size: 0.875rem; }
+      .thumbs button[aria-pressed="true"] { background: var(--stalwart-accent); color: var(--stalwart-accent-fg); }`);
+    const log = element("ol", { class: "log", part: "log", "aria-live": "polite", "aria-label": t("conversation") });
+    for (const entry of this._log) {
+      if (entry.who === "refusal") {
+        const decision = element("stalwart-decision", { sentence: entry.text, rule: entry.rule });
+        log.append(element("li", { class: "assistant" }, [decision, this.thumbsFor(entry.message)]));
+      } else if (entry.who === "rollback") {
+        const rollback = element("stalwart-rollback");
+        rollback.report = entry.report;
+        log.append(element("li", { class: "assistant" }, [rollback, this.thumbsFor(entry.message)]));
+      } else {
+        const item = element("li", { class: entry.who === "user" ? "user" : entry.who === "error" ? "assistant bad" : "assistant",
+                                     text: entry.text });
+        if (entry.who === "assistant") {
+          const bar = this.thumbsFor(entry.message);
+          if (bar) item.append(bar);
+        }
+        log.append(item);
+      }
+    }
+    root.append(element("slot", { name: "header" }), log);
+    if (this._reconnecting) root.append(element("p", { class: "muted", role: "status", part: "status", text: t("reconnecting") }));
+    if (this._events.length) {
+      const trace = element("stalwart-trace");
+      trace.events = this._events;
+      root.append(element("details", { part: "steps" }, [element("summary", { text: t("traceTitle") }), trace]));
+    }
+    for (const interrupt of this._pending) {
+      const confirm = element("stalwart-confirm");
+      confirm.interrupt = interrupt;
+      confirm.addEventListener("stalwart-decision", (event) => this.decide(event.detail.interrupt, event.detail.decision));
+      root.append(confirm);
+    }
+    const asked = this._pending.length ? this.thumbsFor(this._asking) : null;
+    if (asked) root.append(asked);
+    const input = element("input", { id: "message", name: "message", autocomplete: "off", placeholder: t("placeholder"),
+                                     disabled: this._busy || this._pending.length > 0 });
+    const form = element("form", { part: "composer" }, [
+      element("label", { for: "message", class: "visually-hidden", text: t("placeholder") }),
+      input,
+      element("button", { type: "submit", class: "primary", disabled: this._busy || this._pending.length > 0,
+                          text: this._busy ? t("sending") : t("send") }),
+    ]);
+    form.addEventListener("submit", (event) => {
+      event.preventDefault();
+      const text = input.value;
+      input.value = "";
+      this.submit(text);
+    });
+    root.append(form, element("slot", { name: "footer" }));
+  }
+}
+
+/**
+ * Defines the elements under their names, once.
+ * @returns {void}
+ */
+export function define() {
+  const registry = globalThis.customElements;
+  for (const [name, type] of [["stalwart-chat", StalwartChat], ["stalwart-confirm", StalwartConfirm],
+                              ["stalwart-decision", StalwartDecision], ["stalwart-rollback", StalwartRollback],
+                              ["stalwart-trace", StalwartTrace]]) {
+    if (!registry.get(name)) registry.define(name, type);
+  }
+}

package/src/index.js

@@ -0,0 +1,19 @@
+/**
+ * @stalwart-agents/agent-ui: a white-label interface for an agent run by Stalwart.
+ *
+ * Importing this module defines `<stalwart-chat>`, `<stalwart-confirm>`,
+ * `<stalwart-decision>`, `<stalwart-rollback>` and `<stalwart-trace>`. They talk to the
+ * team's own backend -- the resume server -- and to nothing else.
+ *
+ * @example
+ *   <script type="module" src="/agent-ui.js"></script>
+ *   <stalwart-chat thread="u-17"></stalwart-chat>
+ */
+
+import { define } from "./elements.js";
+
+export { backend } from "./client.js";
+export { StalwartChat, StalwartConfirm, StalwartDecision, StalwartRollback, StalwartTrace, define } from "./elements.js";
+export { DEFAULT_STRINGS, setStrings, t } from "./strings.js";
+
+if (globalThis.customElements) define();

package/src/react.js

@@ -0,0 +1,29 @@
+/**
+ * The React entry point: the custom elements as components.
+ *
+ * @example
+ *   import { StalwartChat } from "@stalwart-agents/agent-ui/react";
+ *   <StalwartChat thread="u-17" base="/agent" />
+ */
+
+import { createElement } from "react";
+
+import "./index.js";
+
+/**
+ * `<stalwart-chat>` as a React component.
+ * @param {{thread?: string, base?: string, theme?: "light" | "dark", children?: unknown}} props
+ * @returns {unknown} the element.
+ */
+export function StalwartChat(props) {
+  return createElement("stalwart-chat", { thread: props.thread, base: props.base, theme: props.theme }, props.children);
+}
+
+/**
+ * `<stalwart-decision>` as a React component: a refusal and its rule.
+ * @param {{sentence: string, rule?: string}} props
+ * @returns {unknown} the element.
+ */
+export function StalwartDecision(props) {
+  return createElement("stalwart-decision", { sentence: props.sentence, rule: props.rule });
+}

package/src/strings.js

@@ -0,0 +1,78 @@
+/**
+ * Every string the interface shows, in one table the team can replace.
+ *
+ * `setStrings({...})` replaces any of them; a `{name}` in a string is filled from the
+ * moment it is shown. Nothing the interface renders is written anywhere else.
+ *
+ * @example
+ *   import { setStrings } from "@stalwart-agents/agent-ui";
+ *   setStrings({ send: "Enviar", approve: "Aprovar" });
+ */
+
+/** @type {Record<string, string>} The strings as shipped. */
+export const DEFAULT_STRINGS = Object.freeze({
+  conversation: "Conversation",
+  placeholder: "Write a message",
+  send: "Send",
+  sending: "Sending…",
+  waiting: "Waiting for your decision",
+  confirmTitle: "Confirm {tool}?",
+  argumentsTitle: "What it will use",
+  origin_typed: "you typed it",
+  origin_reply: "you answered it",
+  origin_context: "from your account",
+  origin_computed: "calculated",
+  origin_model: "the assistant wrote it",
+  origin_result: "from an earlier step",
+  origin_agent: "from another assistant",
+  reasonsTitle: "Why this needs you",
+  irreversible: "Nothing can undo this step once it runs.",
+  approve: "Approve",
+  skip: "Skip this step",
+  cancelAll: "Cancel everything",
+  refused: "Not done",
+  rule: "Rule",
+  showRule: "Which rule?",
+  rollbackTitle: "Undoing what this run did",
+  undone: "Undone",
+  notUndoable: "Could not be undone",
+  stuck: "Undoing {tool} failed. What should happen?",
+  retry: "Try again",
+  doneByHand: "I undid it myself",
+  abandon: "Leave it",
+  unknownTitle: "Did {tool} take effect?",
+  happened: "Yes, it happened",
+  didNotHappen: "No, it did not",
+  delegateTitle: "I couldn't work that out. Shall I pass it to the assistant?",
+  delegateApprove: "Yes, pass it on",
+  decline: "No",
+  reconnecting: "Reconnecting…",
+  traceTitle: "What happened",
+  step: "Step {step}",
+  error: "Something went wrong: {message}",
+  thumbUp: "Helpful",
+  thumbDown: "Not helpful",
+  thumbsNotice: "A rated message is kept to improve the assistant, and nothing else of the conversation.",
+});
+
+let current = { ...DEFAULT_STRINGS };
+
+/**
+ * Replaces any of the interface's strings.
+ * @param {Partial<Record<string, string>>} replacements the strings to use instead, by key.
+ * @returns {void}
+ */
+export function setStrings(replacements) {
+  current = { ...current, ...replacements };
+}
+
+/**
+ * A string by its key, its `{name}`s filled from @p values.
+ * @param {string} key the string's key in the table.
+ * @param {Record<string, unknown>} [values] what fills its placeholders.
+ * @returns {string} the string, or the key itself where the table has none.
+ */
+export function t(key, values = {}) {
+  const text = current[key] ?? key;
+  return text.replace(/\{(\w+)\}/g, (_, name) => (values[name] === undefined ? `{${name}}` : String(values[name])));
+}