@artooi/agents-web-components 0.0.0-stage → 0.1.1

package/src/ui/interrupts/approval_styles.ts

@@ -0,0 +1,52 @@
+// The approval card that gates a server-side tool call.
+export const APPROVAL_STYLES: string = `
+/* Approval card — the server-side-tool gate (approve/deny an interrupt). */
+.approval {
+  align-self: stretch;
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 12px;
+  background: var(--_bg);
+  border: 1px solid var(--_accent);
+  border-radius: 10px;
+}
+
+.approval[data-resolved] {
+  opacity: 0.7;
+  border-color: var(--_border);
+}
+
+.approval-body {
+  font-weight: 600;
+}
+
+.approval-actions {
+  display: flex;
+  gap: 8px;
+  justify-content: flex-end;
+}
+
+.approval-btn {
+  border: 1px solid var(--_border);
+  border-radius: 8px;
+  padding: 8px 14px;
+  font: inherit;
+  font-weight: 600;
+  cursor: pointer;
+  background: var(--_bg);
+  color: var(--_fg);
+}
+
+.approval-btn:disabled {
+  cursor: default;
+  opacity: 0.6;
+}
+
+.approval-btn--approve {
+  border-color: var(--_accent);
+  background: var(--_accent);
+  color: var(--_on-accent);
+}
+`;

package/src/ui/interrupts/confirmation_card.ts

@@ -0,0 +1,138 @@
+import { fillUiString } from "../fill_ui_string.js";
+import { DEFAULT_UI_STRINGS, type UiStrings } from "../ui_strings.js";
+
+/** What the inline confirmation card displays. */
+export interface ConfirmationRequest {
+  toolName: string;
+  args: Record<string, unknown>;
+  /**
+   * Human-readable prompt (from the tool's `x-confirm` metadata), e.g.
+   * "Activate this project?". Falls back to the generic `confirmRun` template.
+   */
+  message?: string;
+}
+
+/** Build a labelled action button. */
+function actionButton(modifier: string, label: string): HTMLButtonElement {
+  const button = document.createElement("button");
+  button.type = "button";
+  button.className = `confirm-btn confirm-btn--${modifier}`;
+  button.setAttribute("part", `confirm-button confirm-${modifier}`);
+  button.textContent = label;
+  return button;
+}
+
+/** Options for {@link requestConfirmation}. */
+export interface ConfirmationOptions {
+  /**
+   * Aborting this signal resolves the card as declined, with buttons disabled
+   * and `data-resolved="declined"` — how a Stop control dismisses a pending
+   * confirmation.
+   */
+  signal?: AbortSignal;
+  /** Localized strings; defaults to the English {@link DEFAULT_UI_STRINGS}. */
+  strings?: UiStrings;
+  /**
+   * Offer a third button — "always allow, this session" — and call this when
+   * the user picks it. The card still resolves `true`: the extra decision is
+   * *in addition to* approving this call, not instead of it.
+   *
+   * Absent means no button, which is deliberate: presence of the handler is
+   * what enables it, so the affordance can never be rendered with nothing
+   * listening. A caller that cannot honour the waiver simply does not pass one.
+   */
+  onAlwaysAllow?: () => void;
+}
+
+/**
+ * Append an inline confirmation card to `host` (the chat message list) and
+ * resolve `true` on confirm, `false` on cancel.
+ *
+ * The card lives in the transcript rather than in a modal overlay, so it reads
+ * after the assistant's explanation and never steals focus from the page.
+ *
+ * Answering it removes it: the record of the decision belongs to the tool card
+ * this gates, which settles to `done` or `declined` and carries it. A spent
+ * form left in place reads as still outstanding.
+ *
+ * With `onAlwaysAllow` set the card offers a third button. A prompt that is
+ * approved nearly every time is not a decision, it is a speed bump — and the
+ * reflex it trains is what makes the rare refusal easy to miss. Letting the
+ * user say "not this one again, this session" is the affordance that keeps the
+ * remaining prompts meaningful.
+ */
+export function requestConfirmation(
+  host: Node & ParentNode,
+  request: ConfirmationRequest,
+  options: ConfirmationOptions = {},
+): Promise<boolean> {
+  const strings = options.strings ?? DEFAULT_UI_STRINGS;
+  return new Promise<boolean>((resolve) => {
+    const card = document.createElement("div");
+    card.className = "confirm";
+    card.setAttribute("part", "confirm");
+    card.setAttribute("data-tool-name", request.toolName);
+    card.setAttribute("role", "group");
+    card.setAttribute("aria-label", strings.confirmAction);
+
+    const body = document.createElement("div");
+    body.className = "confirm-body";
+    body.setAttribute("part", "confirm-body");
+    body.textContent =
+      request.message ?? fillUiString(strings.confirmRun, { tool: request.toolName });
+
+    const args = document.createElement("pre");
+    args.className = "confirm-args";
+    args.setAttribute("part", "confirm-args");
+    args.textContent = JSON.stringify(request.args, null, 2);
+    // A call with no arguments rendered the string "{}" in a box of its own.
+    args.hidden = Object.keys(request.args).length === 0;
+
+    const actions = document.createElement("div");
+    actions.className = "confirm-actions";
+    actions.setAttribute("part", "confirm-actions");
+
+    const cancel = actionButton("cancel", strings.cancel);
+    const always =
+      options.onAlwaysAllow === undefined
+        ? null
+        : actionButton("always", fillUiString(strings.confirmAlways, { tool: request.toolName }));
+    const confirm = actionButton("confirm", strings.confirm);
+
+    let settled = false;
+    const close = (accepted: boolean): void => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      // The prompt leaves once it has been answered. What stays is the tool
+      // card next to it, which settles to the outcome and scrolls with the rest
+      // of the transcript -- a record of the action rather than a spent form
+      // sitting there as a standing reminder of one.
+      card.remove();
+      resolve(accepted);
+    };
+
+    cancel.addEventListener("click", () => close(false));
+    confirm.addEventListener("click", () => close(true));
+    always?.addEventListener("click", () => {
+      // Recorded before resolving, so a caller that reads its own allowlist
+      // synchronously on the next call already sees this one.
+      options.onAlwaysAllow?.();
+      close(true);
+    });
+    options.signal?.addEventListener("abort", () => close(false), { once: true });
+
+    // Confirm stays last, and rightmost: the waiver is the wider decision, and
+    // putting it where the eye lands for "yes" is how it gets taken by accident.
+    actions.append(cancel, ...(always === null ? [] : [always]), confirm);
+    card.append(body, args, actions);
+    host.appendChild(card);
+    if (options.signal?.aborted === true) {
+      // The run was cancelled before the card could ask; record the decline.
+      close(false);
+      return;
+    }
+    confirm.focus();
+  });
+}

package/src/ui/interrupts/confirmation_styles.ts

@@ -0,0 +1,114 @@
+// The confirmation card for a destructive client tool, and the editable
+// arguments an approval shares with it.
+export const CONFIRMATION_STYLES: string = `
+/* Inline confirmation card — lives in the transcript, no focus-stealing overlay. */
+.confirm {
+  align-self: stretch;
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 12px;
+  background: var(--_bg);
+  border: 1px solid var(--_accent);
+  border-radius: 10px;
+}
+
+.confirm[data-resolved] {
+  opacity: 0.7;
+  border-color: var(--_border);
+}
+
+.confirm-body {
+  font-weight: 600;
+}
+
+.confirm-args {
+  margin: 0;
+  padding: 8px 10px;
+  max-height: 140px;
+  overflow: auto;
+  font-size: 12px;
+  font-family: ui-monospace, "SF Mono", Menlo, monospace;
+  background: var(--_assistant-bg);
+  border-radius: 8px;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+.confirm-actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  justify-content: flex-end;
+}
+
+.confirm-btn {
+  border: 1px solid var(--_border);
+  border-radius: 8px;
+  padding: 8px 14px;
+  font: inherit;
+  font-weight: 600;
+  cursor: pointer;
+  background: var(--_bg);
+  color: var(--_fg);
+}
+
+.confirm-btn:disabled {
+  cursor: default;
+  opacity: 0.6;
+}
+
+.confirm-btn--confirm {
+  border-color: var(--_accent);
+  background: var(--_accent);
+  color: var(--_on-accent);
+}
+
+/* The session waiver. Deliberately the quietest of the three: it is the widest
+   decision on the card, so it should be reachable without being the one the eye
+   lands on when the user means to say yes once. */
+.confirm-btn--always {
+  font-weight: 500;
+  opacity: 0.85;
+}
+
+.confirm-btn--always:hover,
+.confirm-btn--always:focus-visible {
+  opacity: 1;
+}
+
+/* Editable arguments on an approval card. A plain field rather than a code
+   editor: it holds the JSON a card already displays, and the only interaction
+   is correcting a value before letting the call run. */
+.approval-edit {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.approval-args {
+  box-sizing: border-box;
+  width: 100%;
+  resize: vertical;
+  border: 1px solid var(--_border);
+  border-radius: 8px;
+  padding: 8px;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 0.85em;
+  background: var(--_bg);
+  color: var(--_fg);
+}
+
+.approval-args:focus-visible {
+  border-color: var(--_accent);
+  outline: none;
+}
+
+.approval-error {
+  font-size: 0.85em;
+  color: var(--_danger);
+}
+
+/* Message action row. Sits under a finished assistant bubble.
+`;

package/src/ui/interrupts/pending_decision.ts

@@ -0,0 +1,33 @@
+/**
+ * The decision a run is suspended on, and the one way to abandon it.
+ *
+ * A run pauses on a person in three places -- a client-side confirmation, a
+ * batch of server interrupts, and the `ask_user` question -- and a Stop has to
+ * reach whichever of them is open. Holding the abort controller here gives
+ * it one owner: a wait opens, the Stop aborts what is open, and the wait closes
+ * when it is answered.
+ *
+ * Owned one-to-one by an `<ag-ui-chat>`, and holding no state outside the
+ * instance.
+ */
+export class PendingDecision {
+  // Aborting this dismisses (declines) an open confirmation card when the run
+  // is cancelled while the card awaits a decision. One controller per wait.
+  #controller: AbortController | null = null;
+
+  /** Start waiting on a person; aborting the returned signal abandons the wait. */
+  open(): AbortSignal {
+    this.#controller = new AbortController();
+    return this.#controller.signal;
+  }
+
+  /** The wait was answered; a later Stop has nothing of this wait's to abandon. */
+  close(): void {
+    this.#controller = null;
+  }
+
+  /** Abandon whatever wait is open, resolving it as declined. A no-op when none is. */
+  abort(): void {
+    this.#controller?.abort();
+  }
+}

package/src/ui/interrupts/question_card.ts

@@ -0,0 +1,213 @@
+import { DEFAULT_UI_STRINGS, type UiStrings } from "../ui_strings.js";
+
+/** What the inline question card asks (the `ask_user` frontend tool's args). */
+export interface QuestionRequest {
+  /** The question shown to the user. */
+  question: string;
+  /**
+   * Preset choices rendered as radios. When empty/omitted the card is a plain
+   * free-text prompt.
+   */
+  options?: readonly string[];
+  /**
+   * Whether the user may type a custom answer. With `options`, adds an "other"
+   * radio revealing a text field; without options the card is free-text anyway.
+   */
+  allowCustom?: boolean;
+}
+
+/** Options for {@link requestQuestion}. */
+export interface QuestionOptions {
+  /**
+   * Aborting this signal resolves the card with an empty answer and disabled
+   * fields — how a Stop control dismisses an open question.
+   */
+  signal?: AbortSignal;
+  /** Localized strings; defaults to the English {@link DEFAULT_UI_STRINGS}. */
+  strings?: UiStrings;
+}
+
+/**
+ * A fully custom renderer for the `ask_user` question, set via
+ * `AgUiChat.askUserRenderer`. Receives the parsed {@link QuestionRequest} and an
+ * `AbortSignal` that fires when the run is stopped, and resolves with the user's
+ * answer; an empty string means no answer. Replaces the built-in
+ * {@link requestQuestion} card entirely — see {@link ApprovalRenderer} for the
+ * same seam on approvals.
+ */
+export type QuestionRenderer = (
+  request: QuestionRequest,
+  options: { signal: AbortSignal },
+) => Promise<string>;
+
+/** A single custom-answer text field. */
+function answerInput(placeholder: string): HTMLInputElement {
+  const input = document.createElement("input");
+  input.type = "text";
+  input.className = "question-input";
+  input.setAttribute("part", "question-input");
+  input.placeholder = placeholder;
+  return input;
+}
+
+/**
+ * Append an inline question card to `host` and resolve with the user's answer —
+ * the browser half of the built-in `ask_user` frontend tool.
+ *
+ * Collects a typed answer rather than the yes/no the confirmation and approval
+ * cards return: a radio pick from `options`, or free text when `allowCustom` is
+ * set or no `options` are given. Stays in the transcript as a resolved record,
+ * controls disabled and `data-resolved` set; a Stop while it is open resolves
+ * it with an empty string.
+ */
+export function requestQuestion(
+  host: Node & ParentNode,
+  request: QuestionRequest,
+  options: QuestionOptions = {},
+): Promise<string> {
+  const strings = options.strings ?? DEFAULT_UI_STRINGS;
+  const choices = request.options ?? [];
+  const hasChoices = choices.length > 0;
+  // Free text is offered when there are no preset choices, or when custom
+  // answers are explicitly allowed alongside them (via an "other" radio).
+  const allowsText = !hasChoices || request.allowCustom === true;
+
+  return new Promise<string>((resolve) => {
+    const card = document.createElement("div");
+    card.className = "question";
+    card.setAttribute("part", "question");
+    card.setAttribute("role", "group");
+    card.setAttribute("aria-label", strings.askUserAction);
+
+    const body = document.createElement("div");
+    body.className = "question-body";
+    body.setAttribute("part", "question-body");
+    body.textContent = request.question;
+
+    const form = document.createElement("div");
+    form.className = "question-options";
+    form.setAttribute("part", "question-options");
+
+    // `name` scopes the radio group to this card so multiple open cards don't
+    // interfere; a per-card token keeps it unique without module state.
+    const group = `q-${choices.length}-${request.question.length}`;
+    const radios: HTMLInputElement[] = [];
+    for (const choice of choices) {
+      const label = document.createElement("label");
+      label.className = "question-choice";
+      label.setAttribute("part", "question-choice");
+      const radio = document.createElement("input");
+      radio.type = "radio";
+      radio.name = group;
+      radio.value = choice;
+      radio.setAttribute("part", "question-radio");
+      const text = document.createElement("span");
+      text.setAttribute("part", "question-choice-text");
+      text.textContent = choice;
+      label.append(radio, text);
+      form.appendChild(label);
+      radios.push(radio);
+    }
+
+    // The "other" radio (only alongside choices) toggles the free-text field.
+    let otherRadio: HTMLInputElement | null = null;
+    let input: HTMLInputElement | null = null;
+    if (allowsText) {
+      input = answerInput(strings.answerPlaceholder);
+      if (hasChoices) {
+        const label = document.createElement("label");
+        label.className = "question-choice";
+        label.setAttribute("part", "question-choice");
+        otherRadio = document.createElement("input");
+        otherRadio.type = "radio";
+        otherRadio.name = group;
+        otherRadio.value = "";
+        otherRadio.setAttribute("part", "question-radio");
+        const text = document.createElement("span");
+        text.setAttribute("part", "question-choice-text");
+        text.textContent = strings.otherOption;
+        label.append(otherRadio, text);
+        form.appendChild(label);
+        input.disabled = true;
+      }
+      form.appendChild(input);
+    }
+
+    const actions = document.createElement("div");
+    actions.className = "question-actions";
+    actions.setAttribute("part", "question-actions");
+    const submit = document.createElement("button");
+    submit.type = "button";
+    submit.className = "question-btn";
+    submit.setAttribute("part", "question-button");
+    submit.textContent = strings.submit;
+    actions.appendChild(submit);
+
+    let settled = false;
+    const answerFor = (): string | null => {
+      const picked = radios.find((r) => r.checked);
+      if (picked !== undefined) {
+        return picked.value;
+      }
+      if (input !== null && (otherRadio === null || otherRadio.checked)) {
+        const typed = input.value.trim();
+        return typed === "" ? null : typed;
+      }
+      return null;
+    };
+    const refresh = (): void => {
+      if (input !== null && otherRadio !== null) {
+        input.disabled = !otherRadio.checked;
+      }
+      submit.disabled = answerFor() === null;
+    };
+    const close = (answer: string): void => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      submit.disabled = true;
+      for (const radio of radios) {
+        radio.disabled = true;
+      }
+      if (otherRadio !== null) {
+        otherRadio.disabled = true;
+      }
+      if (input !== null) {
+        input.disabled = true;
+      }
+      card.setAttribute("data-resolved", answer === "" ? "cancelled" : "answered");
+      resolve(answer);
+    };
+
+    for (const radio of [...radios, ...(otherRadio !== null ? [otherRadio] : [])]) {
+      radio.addEventListener("change", refresh);
+    }
+    input?.addEventListener("input", refresh);
+    input?.addEventListener("keydown", (event) => {
+      if (event.key === "Enter") {
+        event.preventDefault();
+        const answer = answerFor();
+        if (answer !== null) {
+          close(answer);
+        }
+      }
+    });
+    submit.addEventListener("click", () => {
+      const answer = answerFor();
+      if (answer !== null) {
+        close(answer);
+      }
+    });
+    options.signal?.addEventListener("abort", () => close(""), { once: true });
+
+    card.append(body, form, actions);
+    host.appendChild(card);
+    if (options.signal?.aborted === true) {
+      close("");
+      return;
+    }
+    refresh();
+    (hasChoices ? radios[0] : input)?.focus();
+  });
+}

package/src/ui/interrupts/question_styles.ts

@@ -0,0 +1,73 @@
+// The question card the agent asks the user through.
+export const QUESTION_STYLES: string = `
+/* Question card — the built-in ask_user prompt (radios and/or free text). */
+.question {
+  align-self: stretch;
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 12px;
+  background: var(--_bg);
+  border: 1px solid var(--_accent);
+  border-radius: 10px;
+}
+
+.question[data-resolved] {
+  opacity: 0.7;
+  border-color: var(--_border);
+}
+
+.question-body {
+  font-weight: 600;
+}
+
+.question-options {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.question-choice {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  cursor: pointer;
+}
+
+.question-input {
+  box-sizing: border-box;
+  width: 100%;
+  padding: 8px 10px;
+  font: inherit;
+  color: var(--_fg);
+  background: var(--_bg);
+  border: 1px solid var(--_border);
+  border-radius: 8px;
+}
+
+.question-input:disabled {
+  opacity: 0.6;
+}
+
+.question-actions {
+  display: flex;
+  justify-content: flex-end;
+}
+
+.question-btn {
+  border: 1px solid var(--_accent);
+  border-radius: 8px;
+  padding: 8px 14px;
+  font: inherit;
+  font-weight: 600;
+  cursor: pointer;
+  background: var(--_accent);
+  color: var(--_on-accent);
+}
+
+.question-btn:disabled {
+  cursor: default;
+  opacity: 0.6;
+}
+`;

package/src/ui/place/place.ts

@@ -0,0 +1,16 @@
+/**
+ * Where in the host application the user is: the page, tab or record on
+ * screen. The chip in the composer draws it and the next round sends it as one
+ * context entry, both from the same read, so the place the user sees is the
+ * place the agent is told.
+ */
+export interface Place {
+  /** Short name of the place, e.g. "Order #4821" or "Billing settings". */
+  readonly label: string;
+  /** A quieter second part, e.g. the section or the tab. */
+  readonly detail?: string;
+  /** An image URL for the chip's mark; a pin when absent. Never sent. */
+  readonly icon?: string;
+  /** Where the place lives. Sent to the agent, and what identifies the place. */
+  readonly href?: string;
+}