@artooi/ag-ui-web-component 0.19.0 → 0.20.0

package/src/core/ag_ui_chat.ts

@@ -42,6 +42,12 @@ import {
   requestQuestion,
 } from "../ui/question_card.js";
 import { renderMarkdown } from "../ui/render_markdown.js";
+import {
+  createResizeHandle,
+  type ResizeAnchor,
+  type ResizeAxis,
+  type ResizeSize,
+} from "../ui/resize_handle.js";
 import { wrapWords } from "../ui/reveal_words.js";
 import { renderRunNotice } from "../ui/run_notice.js";
 import { SkillsMenu } from "../ui/skills_menu.js";
@@ -130,6 +136,9 @@ const CONNECT_TIME_ATTRIBUTES = [
 /** Per-tab persistence key for the collapsed state (survives MPA reloads). */
 const COLLAPSED_KEY = "ag-ui-chat:collapsed";
 
+/** Per-tab persistence key for a dragged panel size. */
+const SIZE_KEY = "ag-ui-chat:size";
+
 /** Per-tab persistence key for the built-in theme toggle. */
 const THEME_KEY = "ag-ui-chat:theme";
 
@@ -524,10 +533,16 @@ export class AgUiChat extends HTMLElement {
 
   /** Attributes the element reacts to after it has been connected. */
   static get observedAttributes(): string[] {
-    return ["title-text", ...CONNECT_TIME_ATTRIBUTES];
+    return ["title-text", "placement", ...CONNECT_TIME_ATTRIBUTES];
   }
 
   attributeChangedCallback(name: string, previous: string | null, value: string | null): void {
+    if (name === "placement") {
+      // Placement moves the panel, so the edges its layout holds still change
+      // with it. Deferred a frame so the new rules have applied.
+      requestAnimationFrame(() => this.#syncResizeAnchor());
+      return;
+    }
     if (name === "title-text") {
       // `#strings` is the resolved table once connected, the English defaults
       // before then.
@@ -787,6 +802,14 @@ export class AgUiChat extends HTMLElement {
     // key read/write, so this instance doesn't share collapsed/theme/thread
     // state with another on the same origin.
     this.#storageNs = this.id !== "" ? this.id : this.endpoint;
+    // Restore a dragged size before the panel paints, so it does not snap from
+    // the placement default to the user's width on the first frame.
+    this.#applySize(this.#readSize());
+    // Position the grip at the corner this layout grows toward. Deferred to a
+    // frame so the host's own stylesheet has applied; re-measured on every drag
+    // anyway, so a wrong first guess costs a grip in the wrong corner and never
+    // a wrong resize.
+    requestAnimationFrame(() => this.#syncResizeAnchor());
     // Resolve the string table before rendering any chrome (defaults are the
     // floor; `data-strings` then the `strings` property layer over them).
     this.#strings = mergeUiStrings({ ...this.#readStringOverrides(), ...this.strings });
@@ -1098,23 +1121,69 @@ export class AgUiChat extends HTMLElement {
     this.#skillsMenu.setSkills([...merged.values()]);
   }
 
-  /** Pre-fill (or send) a picked skill's prompt, filling its placeholders. */
+  /**
+   * Act on a picked skill.
+   *
+   * A skill that ships no `prompt` is **server-resolved**: the catalog carries
+   * only its name and label, and picking it sends the bare `/name` token for
+   * the agent to expand — from the harness `Skills` capability, or from the
+   * server's own instructions. That is the shape to prefer, because the prompt
+   * then never reaches the browser at all: a skill is often where a project's
+   * internal workflow is written down most plainly, and a catalog endpoint is a
+   * plain GET.
+   *
+   * A skill that does carry a `prompt` keeps the older behaviour — the client
+   * fills its `{placeholder}`s from the page and sends (or pre-fills) the text.
+   * Right for a user-facing convenience, and for placeholders only the page can
+   * supply.
+   *
+   * Either way a pick now **sends**, rather than parking text in the composer
+   * for a second click; `sendImmediately: false` opts back into pre-filling.
+   */
   #applySkill(skill: Skill): void {
+    if (skill.prompt === undefined) {
+      this.#skillHint.hidden = true;
+      void this.sendMessage(`/${skill.name}`);
+      return;
+    }
     const { text, missing } = fillTemplate(skill.prompt, this.skillContext());
     if (missing.length > 0) {
+      // Hand the user something to work with rather than only a refusal. The
+      // partially-filled template goes into the composer with its unresolved
+      // `{placeholder}`s intact and the first one selected, so the next
+      // keystroke replaces it. Blocking with a hint alone left whatever the
+      // user had typed to open the palette — a lone "/" — sitting there, which
+      // says nothing about what the skill wanted or how to give it.
       this.#skillHint.textContent = this.#strings.skillNeeds
         .replace("{title}", skill.title)
         .replace("{fields}", missing.join(", "));
       this.#skillHint.hidden = false;
+      this.#input.value = text;
+      this.#input.focus();
+      this.#selectFirstPlaceholder(text);
       return;
     }
     this.#skillHint.hidden = true;
     this.#input.value = text;
-    if (skill.sendImmediately === true) {
-      void this.#submit();
-    } else {
+    if (skill.sendImmediately === false) {
       this.#input.focus();
+      return;
     }
+    void this.#submit();
+  }
+
+  /**
+   * Put the caret on the first unresolved placeholder, selected.
+   *
+   * Typing then replaces it, which is the shortest path from "this skill needs
+   * a topic" to a sendable prompt.
+   */
+  #selectFirstPlaceholder(text: string): void {
+    // The first surviving brace *is* the first unresolved placeholder — a
+    // resolved one was substituted away — so this needs no search through the
+    // missing keys and no not-found branch to defend.
+    const start = text.indexOf("{");
+    this.#input.setSelectionRange(start, text.indexOf("}", start) + 1);
   }
 
   /** Whether the widget is collapsed (reflected as the `collapsed` attribute). */
@@ -1168,6 +1237,113 @@ export class AgUiChat extends HTMLElement {
     this.#syncThemeGlyph();
   }
 
+  /**
+   * Which axes the current placement allows.
+   *
+   * A full-bleed layout is `100vw`/`100vh` by definition and cannot be resized
+   * at all; a docked panel owns its height, leaving only its inner edge. Read
+   * per interaction, because `placement` is a live attribute.
+   */
+  #resizeAxis(): ResizeAxis {
+    switch (this.getAttribute("placement")) {
+      case "full":
+      case "page":
+        return "none";
+      case "sidebar":
+      case "side":
+        return "width";
+      default:
+        return "both";
+    }
+  }
+
+  /**
+   * Which edges the layout is holding still, by measuring rather than guessing.
+   *
+   * A resize has to be computed from the edge that does not move, and which
+   * edge that is belongs to the **host's layout**, not to `placement`: a
+   * floating panel is pinned bottom-right, while an embedded one goes wherever
+   * the page's own CSS puts it — flex-start, flex-end, a grid cell. Mapping
+   * placement to a corner got this wrong for any host that right-aligns the
+   * element, and the symptom is bad enough to read as a broken control: the
+   * panel shrinks when dragged outward, travelling by its opposite corner.
+   *
+   * So: nudge the size by a pixel, see which edges stayed put, and undo. One
+   * forced reflow per drag, which is cheap next to being wrong.
+   */
+  #measureAnchor(): ResizeAnchor {
+    const before = this.getBoundingClientRect();
+    const width = this.style.getPropertyValue("--ag-ui-width");
+    const height = this.style.getPropertyValue("--ag-ui-height");
+    this.#applySize({ width: before.width + 1, height: before.height + 1 });
+    const after = this.getBoundingClientRect();
+    // Restore exactly what was there, including "nothing" — leaving a probe
+    // value behind would pin a panel that had been sizing itself.
+    this.#restoreProperty("--ag-ui-width", width);
+    this.#restoreProperty("--ag-ui-height", height);
+    return {
+      x: Math.abs(after.left - before.left) < 0.5 ? "left" : "right",
+      y: Math.abs(after.top - before.top) < 0.5 ? "top" : "bottom",
+    };
+  }
+
+  /** Stamp the measured anchor so the shadow CSS can place the grip. */
+  #syncResizeAnchor(): void {
+    if (!this.#connected) {
+      return;
+    }
+    const anchor = this.#measureAnchor();
+    this.setAttribute("data-resize-anchor", `${anchor.y}-${anchor.x}`);
+  }
+
+  /** Put a custom property back to a previous value, or remove it if there was none. */
+  #restoreProperty(name: string, value: string): void {
+    if (value === "") {
+      this.style.removeProperty(name);
+      return;
+    }
+    this.style.setProperty(name, value);
+  }
+
+  /**
+   * Write a dragged size onto the host as custom properties.
+   *
+   * Properties rather than inline `width` / `height`: the placement rules set
+   * those same properties, so an inline dimension would outrank them and a
+   * panel dragged while floating would keep that width after switching to
+   * fullscreen.
+   */
+  #applySize(size: ResizeSize): void {
+    if (size.width !== undefined) {
+      this.style.setProperty("--ag-ui-width", `${size.width}px`);
+    }
+    if (size.height !== undefined) {
+      this.style.setProperty("--ag-ui-height", `${size.height}px`);
+    }
+  }
+
+  /** Persist a dragged size per tab, alongside the collapsed/theme preferences. */
+  #persistSize(size: ResizeSize): void {
+    const stored = { ...this.#readSize(), ...size };
+    sessionStorage.setItem(this.#storageKey(SIZE_KEY), JSON.stringify(stored));
+  }
+
+  /** The persisted size for this instance, or an empty record. */
+  #readSize(): ResizeSize {
+    const raw = this.#readScopedItem(SIZE_KEY);
+    if (raw === null) {
+      return {};
+    }
+    try {
+      const parsed: unknown = JSON.parse(raw);
+      return typeof parsed === "object" && parsed !== null ? (parsed as ResizeSize) : {};
+    } catch {
+      // A corrupt entry is not worth failing a mount over; fall back to the
+      // placement's own size.
+      return {};
+    }
+  }
+
   /** This instance's namespaced form of an origin-scoped storage key. */
   #storageKey(base: string): string {
     return this.#storageNs === "" ? base : `${base}:${this.#storageNs}`;
@@ -1652,6 +1828,22 @@ export class AgUiChat extends HTMLElement {
     this.#rail.append(this.#iconElement("launcher", "launcher-icon", "💬"));
     this.#rail.addEventListener("click", () => this.setCollapsed(false));
 
+    this.#chat.append(
+      createResizeHandle({
+        axis: () => this.#resizeAxis(),
+        anchor: () => this.#measureAnchor(),
+        rect: () => this.getBoundingClientRect(),
+        apply: (size) => this.#applySize(size),
+        commit: (size) => {
+          this.#persistSize(size);
+          // Re-stamp after the drag: a host whose layout changed underneath us
+          // would otherwise keep the grip in the old corner, which reads as the
+          // control being in the wrong place even though the drag was right.
+          this.#syncResizeAnchor();
+        },
+        label: this.#strings.resizePanel,
+      }),
+    );
     this.#root.append(style, this.#chat, this.#rail);
   }
 
@@ -2068,6 +2260,12 @@ export class AgUiChat extends HTMLElement {
           : await requestApproval(this.#ensureGroup(), request, { signal, strings: this.#strings });
       this.#updateEmptyState();
       this.#messages.scrollTop = this.#messages.scrollHeight;
+      // Same annotation as the client-side confirmation gate. Without it the
+      // two gates read differently for the same act: a locally-confirmed call
+      // said who let it through and a server-gated one said nothing, which is
+      // backwards, since the server-side gate is the one guarding the tools
+      // that actually run on the backend.
+      card?.recordDecision(approved ? "approved" : "declined");
       if (approved) {
         responses[interrupt.id] = { status: "resolved", payload: { approved: true } };
       } else {

package/src/core/agui_client.ts

@@ -181,6 +181,13 @@ export class AgUiClient {
   readonly #executeTool: ExecuteTool | null;
   readonly #resolveInterrupts: ResolveInterrupts | null;
   readonly #onPersist: (messages: readonly Message[]) => void;
+  /**
+   * Message ids the server has already closed, so a reuse can be reported.
+   *
+   * Per client rather than per run: the merge happens across runs, which is the
+   * case a per-run set would miss entirely.
+   */
+  readonly #closedMessageIds = new Set<string>();
   readonly #connectionLostMessage: string;
   // Set by cancel(); reset at the top of each #run(). Checked by the loop so
   // a cancel between frontend-tool rounds doesn't start another round.
@@ -397,14 +404,33 @@ export class AgUiClient {
 
   #buildSubscriber(pending: AgUiToolCall[], runState: RunState): AgentSubscriber {
     const h = this.#handlers;
+    const closed = this.#closedMessageIds;
     return {
       onRunInitialized() {
         h.onRunStart();
       },
+      onTextMessageStartEvent({ event }) {
+        // A server that reuses a message id gets its two answers merged into
+        // one transcript entry, silently, and that merged entry is what gets
+        // persisted. The protocol has no rule to enforce here and refusing the
+        // event would be worse than the merge, so this warns and continues —
+        // but it should not be silent, because the corruption outlives the
+        // session and reads as a client bug. Found by a demo harness doing
+        // exactly this.
+        if (closed.has(event.messageId)) {
+          console.warn(
+            `<ag-ui-chat>: the server reused message id "${event.messageId}", which was ` +
+              "already closed. Its content will be appended to that earlier message rather " +
+              "than starting a new one, and the merged result is what gets persisted. " +
+              "Issue a fresh id per message.",
+          );
+        }
+      },
       onTextMessageContentEvent({ textMessageBuffer }) {
         h.onTextDelta(textMessageBuffer);
       },
-      onTextMessageEndEvent({ textMessageBuffer }) {
+      onTextMessageEndEvent({ event, textMessageBuffer }) {
+        closed.add(event.messageId);
         h.onTextEnd(textMessageBuffer);
       },
       onToolCallEndEvent({ event, toolCallName, toolCallArgs }) {

package/src/skills/parse_skills.ts

@@ -1,6 +1,12 @@
 import type { Skill } from "./skill.js";
 
-/** Whether ``value`` has the required string fields of a {@link Skill}. */
+/**
+ * Whether ``value`` has the required string fields of a {@link Skill}.
+ *
+ * `prompt` is optional and must stay so: a server-resolved skill deliberately
+ * omits it, and requiring it here would silently drop exactly the skills whose
+ * wording was kept off the client.
+ */
 function isSkill(value: unknown): value is Skill {
   if (typeof value !== "object" || value === null) {
     return false;
@@ -9,7 +15,7 @@ function isSkill(value: unknown): value is Skill {
   return (
     typeof record["name"] === "string" &&
     typeof record["title"] === "string" &&
-    typeof record["prompt"] === "string"
+    (record["prompt"] === undefined || typeof record["prompt"] === "string")
   );
 }
 

package/src/skills/skill.ts

@@ -12,11 +12,21 @@ export interface Skill {
   /** Secondary line shown in the palette. */
   readonly description?: string;
   /**
-   * The prompt inserted (or sent). May contain `{placeholder}`s filled from the
-   * host's skill context before send; an unfilled placeholder blocks send.
+   * The prompt to send. May contain `{placeholder}`s filled from the host's
+   * skill context before send; an unfilled placeholder blocks send.
+   *
+   * **Omit it to keep the prompt on the server.** The skill then sends the bare
+   * `/name` token and the agent resolves what it means, so the wording never
+   * reaches the browser — worth preferring for anything internal, since a
+   * fetched catalog is a plain GET and an embedded one sits in the page source.
+   */
+  readonly prompt?: string;
+  /**
+   * Set `false` to pre-fill the composer instead of sending on pick. Only
+   * meaningful for a skill that carries its own `prompt`; a server-resolved one
+   * always sends. Defaults to sending — a chip that needs a second click to do
+   * anything is a two-step shortcut.
    */
-  readonly prompt: string;
-  /** Send immediately on pick instead of pre-filling the input (default false). */
   readonly sendImmediately?: boolean;
   /** Also surface this skill as a chip (default false; the palette shows all). */
   readonly chip?: boolean;

package/src/ui/resize_handle.ts

@@ -0,0 +1,176 @@
+/** Which edges the layout holds still while the panel changes size. */
+export interface ResizeAnchor {
+  /** The horizontal edge that does not move. */
+  readonly x: "left" | "right";
+  /** The vertical edge that does not move. */
+  readonly y: "top" | "bottom";
+}
+
+/**
+ * What the current placement allows: both axes, width only, or nothing.
+ *
+ * Which *corner* the grip sits on is not part of this — that follows the host's
+ * layout, which the component measures rather than assumes.
+ */
+export type ResizeAxis = "none" | "width" | "both";
+
+/** Persisted size, in CSS pixels. Either axis may be absent. */
+export interface ResizeSize {
+  readonly width?: number;
+  readonly height?: number;
+}
+
+/** The panel's position on screen at the moment a drag starts. */
+export interface PanelRect {
+  readonly left: number;
+  readonly top: number;
+  readonly right: number;
+  readonly bottom: number;
+}
+
+/** What the handle needs from its host to do its job. */
+export interface ResizeOptions {
+  /**
+   * Which axes the current placement allows, read **per interaction**.
+   *
+   * A getter rather than a value because `placement` is a live attribute: read
+   * once at construction, a handle built while floating kept its axes after the
+   * host switched to a docked or full-bleed layout.
+   */
+  readonly axis: () => ResizeAxis;
+  /**
+   * Which edges the layout is holding still, measured at the moment of the
+   * drag.
+   *
+   * **Measured, not derived from `placement`.** A floating panel is pinned
+   * bottom-right and an embedded one goes wherever the host's own CSS puts it —
+   * the demo playground drops it in a right-aligned flex slot, so "embedded"
+   * alone says nothing. Guessing produced a panel that shrank when dragged
+   * outward and travelled by its opposite corner.
+   */
+  readonly anchor: () => ResizeAnchor;
+  /** The panel's current bounding box. */
+  readonly rect: () => PanelRect;
+  /** Apply a size (the host writes the custom properties). */
+  readonly apply: (size: ResizeSize) => void;
+  /** Called once per completed drag, for persistence. */
+  readonly commit: (size: ResizeSize) => void;
+  /** Accessible label. */
+  readonly label: string;
+}
+
+/** Smallest usable panel; below this the composer and header collide. */
+const MIN_WIDTH = 280;
+const MIN_HEIGHT = 240;
+
+/**
+ * A drag handle that resizes the chat panel.
+ *
+ * The size was previously fixed by whatever the host set `--ag-ui-width` /
+ * `--ag-ui-height` to: themeable by the page, immovable by the person reading a
+ * long answer in a 380px column.
+ *
+ * **The new size is measured from the edge that is not moving, never from a
+ * delta**, and which edge that is is **measured rather than assumed**. A
+ * floating panel is pinned bottom-right; an embedded one goes wherever the
+ * host's CSS puts it, so `placement` does not answer the question. Getting it
+ * wrong is very visible: the panel shrinks when dragged outward and travels by
+ * its opposite corner.
+ *
+ * **It writes the custom properties rather than inline `width` / `height`.**
+ * The placement rules set those same properties, so an inline dimension would
+ * fight them — a sidebar would keep a dragged width after switching to
+ * fullscreen. Writing the property means placement still has the final say.
+ *
+ * The axes are read per interaction, so switching `placement` at runtime takes
+ * effect immediately rather than leaving whichever ones the element happened to
+ * mount with.
+ */
+export function createResizeHandle(options: ResizeOptions): HTMLDivElement {
+  const handle = document.createElement("div");
+  handle.className = "resize-handle";
+  handle.setAttribute("part", "resize-handle");
+  handle.setAttribute("role", "separator");
+  handle.setAttribute("aria-label", options.label);
+  handle.tabIndex = 0;
+
+  /** The size implied by a pointer at (x, y), given which edges are pinned. */
+  const sizeAt = (
+    axis: ResizeAxis,
+    anchor: ResizeAnchor,
+    rect: PanelRect,
+    x: number,
+    y: number,
+  ): ResizeSize => {
+    const width = anchor.x === "right" ? rect.right - x : x - rect.left;
+    const clamped: ResizeSize = { width: Math.max(MIN_WIDTH, width) };
+    if (axis !== "both") {
+      return clamped;
+    }
+    const height = anchor.y === "bottom" ? rect.bottom - y : y - rect.top;
+    return { ...clamped, height: Math.max(MIN_HEIGHT, height) };
+  };
+
+  handle.addEventListener("pointerdown", (event: PointerEvent) => {
+    const axis = options.axis();
+    if (axis === "none") {
+      return;
+    }
+    // Captured once: the fixed edges cannot move during the drag, and reading
+    // them live would chase the panel as it resizes.
+    const anchor = options.anchor();
+    const rect = options.rect();
+
+    const onMove = (move: PointerEvent): void => {
+      options.apply(sizeAt(axis, anchor, rect, move.clientX, move.clientY));
+    };
+
+    const onUp = (up: PointerEvent): void => {
+      window.removeEventListener("pointermove", onMove);
+      window.removeEventListener("pointerup", onUp);
+      handle.removeAttribute("data-dragging");
+      options.commit(sizeAt(axis, anchor, rect, up.clientX, up.clientY));
+    };
+
+    handle.setAttribute("data-dragging", "true");
+    // Listeners on `window`, not the handle: a fast drag outruns the pointer
+    // and would otherwise strand the panel mid-resize with no pointerup.
+    window.addEventListener("pointermove", onMove);
+    window.addEventListener("pointerup", onUp);
+    event.preventDefault();
+  });
+
+  // Keyboard parity. A pointer-only resize is unreachable without a mouse, and
+  // this control has no equivalent elsewhere in the UI.
+  handle.addEventListener("keydown", (event: KeyboardEvent) => {
+    const axis = options.axis();
+    if (axis === "none") {
+      return;
+    }
+    const anchor = options.anchor();
+    const rect = options.rect();
+    const step = event.shiftKey ? 64 : 16;
+    // An arrow moves the grip, and whether that grows or shrinks depends on
+    // which side the grip is on — the same asymmetry the pointer path handles.
+    const outward = anchor.x === "right" ? -1 : 1;
+    const width = rect.right - rect.left;
+    const height = rect.bottom - rect.top;
+    let next: ResizeSize | null = null;
+    if (event.key === "ArrowLeft") {
+      next = { width: Math.max(MIN_WIDTH, width - step * outward) };
+    } else if (event.key === "ArrowRight") {
+      next = { width: Math.max(MIN_WIDTH, width + step * outward) };
+    } else if (axis === "both" && (event.key === "ArrowUp" || event.key === "ArrowDown")) {
+      const grow = event.key === (anchor.y === "bottom" ? "ArrowUp" : "ArrowDown");
+      next = { height: Math.max(MIN_HEIGHT, height + (grow ? step : -step)) };
+    }
+    if (next === null) {
+      return;
+    }
+    event.preventDefault();
+    options.apply(next);
+    options.commit(next);
+  });
+
+  return handle;
+}

package/src/ui/skills_menu.ts

@@ -141,6 +141,10 @@ export class SkillsMenu {
       button.className = "skill-chip";
       button.setAttribute("part", "skill-chip");
       button.textContent = skill.title;
+      // The chip stays a label — it is a one-click affordance, not something to
+      // memorise — but naming the command it stands for makes the two
+      // discoverable as the same thing.
+      button.title = `/${skill.name}`;
       button.addEventListener("click", () => this.#pick(skill));
       this.chips.appendChild(button);
     }
@@ -159,7 +163,15 @@ export class SkillsMenu {
       const title = document.createElement("span");
       title.className = "skill-item-title";
       title.setAttribute("part", "skill-item-title");
-      title.textContent = skill.title;
+
+      // The token leads, because it is the thing the user has to type. A row
+      // showing only the label taught the label and not the command, so the
+      // palette could not be used to learn its own vocabulary.
+      const token = document.createElement("code");
+      token.className = "skill-item-token";
+      token.setAttribute("part", "skill-item-token");
+      token.textContent = `/${skill.name}`;
+      title.append(token, document.createTextNode(` ${skill.title}`));
       item.appendChild(title);
 
       if (skill.description !== undefined) {