@artooi/ag-ui-web-component 0.35.2 → 0.37.0

package/dist/index.js

@@ -41,6 +41,11 @@ var TOOL_CALL_STATUS = {
   ERROR: "error",
   DECLINED: "declined"
 };
+var TOOL_OUTCOME = {
+  SUCCESS: "success",
+  FAILED: "failed",
+  DENIED: "denied"
+};
 var ATTACHMENT_STATUS = {
   UPLOADING: "uploading",
   READY: "ready",
@@ -824,6 +829,8 @@ var DEFAULT_UI_STRINGS = {
   runInterrupted: "The previous response didn\u2019t finish \u2014 the page changed before it arrived.",
   pageMoved: "The page changed since you last looked at it. Call read_page to see the current page, then retry.",
   attachmentsStillUploading: "{n} file still uploading \u2014 it was not sent with this message and is still attached.",
+  notConnected: "This chat isn\u2019t connected to an agent, so the message wasn\u2019t sent.",
+  continueNeedsTurn: "Type the next turn in the composer first, then pick a run to continue.",
   skillNeeds: "\u201C{title}\u201D needs {fields} \u2014 fill it in below, then send.",
   message: "Message",
   inputPlaceholder: "Ask anything\u2026",
@@ -10779,6 +10786,25 @@ var AgUiClient = class {
    * set would miss entirely.
    */
   #closedMessageIds = /* @__PURE__ */ new Set();
+  /**
+   * How each tool call ended, keyed by call id, for the transcript this client
+   * persists.
+   *
+   * A side table rather than a field written onto the message, because neither
+   * producer of a tool message will carry it. `@ag-ui/client` builds the
+   * server-side one by destructuring five named fields off the event, so an
+   * `outcome` beside them is dropped before the message exists; and writing it
+   * back onto that message afterwards would put it in `agent.messages`, which is
+   * what the *next* request sends to the server. This keeps the annotation on
+   * the copy handed to the store and off the wire.
+   *
+   * Per client, not per run: `saveMessages` rewrites the whole transcript on
+   * every persist, so an outcome recorded in round one has to still be here in
+   * round five or the earlier card silently reverts to a green one. Bounded by
+   * the number of tool calls in the conversation, which the transcript beside it
+   * already is.
+   */
+  #outcomes = /* @__PURE__ */ new Map();
   #connectionLostMessage;
   #maxToolRounds;
   // Set by cancel(); reset at the top of each #run(). Checked by the loop so
@@ -10839,7 +10865,7 @@ var AgUiClient = class {
       message.attachments = attachments;
     }
     this.#agent.addMessage(message);
-    this.#onPersist(this.#agent.messages);
+    this.#persist();
     await this.#run();
   }
   /**
@@ -10874,7 +10900,7 @@ var AgUiClient = class {
     }
     const kept = messages.slice(0, lastUser + 1);
     this.#agent.setMessages(kept);
-    this.#onPersist(this.#agent.messages);
+    this.#persist();
     return kept;
   }
   /**
@@ -10888,7 +10914,7 @@ var AgUiClient = class {
   /** Append a frontend tool result to history (used by the resume path). */
   addToolResult(toolCallId, content) {
     this.#agent.addMessage({ id: randomUUID2(), role: "tool", content, toolCallId });
-    this.#onPersist(this.#agent.messages);
+    this.#persist();
   }
   /**
    * Cancel the in-flight run (AG-UI has no server cancel route — aborting the
@@ -10919,9 +10945,33 @@ var AgUiClient = class {
     }
   }
   #onCancelled() {
-    this.#onPersist(this.#agent.messages);
+    this.#persist();
     this.#handlers.onCancelled();
   }
+  /**
+   * Hand the transcript to the host's store, annotated with what {@link #outcomes}
+   * knows about how each tool call ended.
+   *
+   * Every persist in this class goes through here, because the store keeps only
+   * the most recent list: annotating one call site would mean the next
+   * unannotated save quietly threw the annotations away.
+   */
+  #persist() {
+    const messages = this.#agent.messages;
+    if (this.#outcomes.size === 0) {
+      this.#onPersist(messages);
+      return;
+    }
+    this.#onPersist(
+      messages.map((message) => {
+        if (message.role !== "tool") {
+          return message;
+        }
+        const outcome = this.#outcomes.get(message.toolCallId);
+        return outcome === void 0 ? message : { ...message, outcome };
+      })
+    );
+  }
   async #runLoop() {
     let resume;
     for (let round = 0; round < this.#maxToolRounds; round += 1) {
@@ -10939,7 +10989,7 @@ var AgUiClient = class {
       }
       await this.#agent.runAgent(params, this.#buildSubscriber(pending, runState));
       resume = void 0;
-      this.#onPersist(this.#agent.messages);
+      this.#persist();
       if (this.#cancelled) {
         return;
       }
@@ -10972,13 +11022,16 @@ var AgUiClient = class {
         if (result.halt === true) {
           return;
         }
+        if (result.outcome !== void 0) {
+          this.#outcomes.set(call.id, result.outcome);
+        }
         this.#agent.addMessage({
           id: randomUUID2(),
           role: "tool",
           content: result.content,
           toolCallId: call.id
         });
-        this.#onPersist(this.#agent.messages);
+        this.#persist();
         executed = true;
       }
       if (!executed) {
@@ -10989,6 +11042,7 @@ var AgUiClient = class {
   #buildSubscriber(pending, runState) {
     const h = this.#handlers;
     const closed = this.#closedMessageIds;
+    const outcomes = this.#outcomes;
     const cancelled = () => this.#cancelled;
     const pendingDeltas = /* @__PURE__ */ new Set();
     return {
@@ -11019,7 +11073,11 @@ var AgUiClient = class {
         h.onToolCall(call);
       },
       onToolCallResultEvent({ event }) {
-        h.onToolResult(event.toolCallId, event.content);
+        const outcome = event["outcome"];
+        if (typeof outcome === "string") {
+          outcomes.set(event.toolCallId, outcome);
+        }
+        h.onToolResult(event.toolCallId, event.content, outcome);
       },
       onActivitySnapshotEvent({ event, messages }) {
         const known = messages.some(
@@ -11644,6 +11702,17 @@ var RunIndex = class {
   }
 };
 
+// src/core/tool_outcome.ts
+function toolStatusFromOutcome(outcome) {
+  if (outcome === TOOL_OUTCOME.FAILED) {
+    return TOOL_CALL_STATUS.ERROR;
+  }
+  if (outcome === TOOL_OUTCOME.DENIED) {
+    return TOOL_CALL_STATUS.DECLINED;
+  }
+  return TOOL_CALL_STATUS.DONE;
+}
+
 // src/core/transcribe_audio.ts
 async function transcribeAudio(audio, options) {
   const form = new FormData();
@@ -12187,7 +12256,17 @@ var AgUiChat = class extends HTMLElement {
   #checkpoints;
   /** Built lazily from `data-runs-url`; `null` when the host didn't opt in. */
   #runIndex = null;
-  #skillHint;
+  /**
+   * The one-line hint above the composer, cleared by the next keystroke.
+   *
+   * Two things write it -- a skill whose template is short of a field, and a
+   * run continuation picked with nothing typed -- and both say the same kind of
+   * thing: what the composer still needs before this can go. Its `part` stays
+   * `skill-hint`, which the skills feature named and the README documents;
+   * renaming a part is breaking, and a second hint element in the same slot
+   * would be worse than one whose name is a release older than its job.
+   */
+  #composerHint;
   /** File-picker button + hidden input + tray slot; the tray mounts on connect. */
   #attachButton;
   #fileInput;
@@ -12377,7 +12456,7 @@ var AgUiChat = class extends HTMLElement {
     this.#input = document.createElement("textarea");
     this.#send = document.createElement("button");
     this.#title = document.createElement("span");
-    this.#skillHint = document.createElement("div");
+    this.#composerHint = document.createElement("div");
     this.#attachButton = document.createElement("button");
     this.#fileInput = document.createElement("input");
     this.#attachSlot = document.createElement("div");
@@ -12461,6 +12540,9 @@ var AgUiChat = class extends HTMLElement {
     }
     const content = this.#input.value.trim();
     if (content === "") {
+      this.#composerHint.textContent = this.#strings.continueNeedsTurn;
+      this.#composerHint.hidden = false;
+      this.#input.focus();
       return;
     }
     this.#input.value = "";
@@ -12983,20 +13065,37 @@ var AgUiChat = class extends HTMLElement {
     const value = this.getAttribute(name);
     return value !== null && value !== "false";
   }
-  /** Parse the inline `data-strings` JSON overrides (empty when absent/malformed). */
-  #readStringOverrides() {
-    const raw = this.getAttribute("data-strings");
+  /**
+   * Parse a JSON-valued attribute, saying so when it will not parse.
+   *
+   * `null` for an absent attribute, and `null` again for one that is not JSON --
+   * but not quietly the second time. Quoting JSON inside an HTML attribute is
+   * fiddly, and the result of getting it wrong is indistinguishable from the
+   * feature being switched off: no chips appear, or the strings stay English,
+   * with nothing anywhere saying why. That is the same failure `data-paste-attach`
+   * already reports for a value it cannot read.
+   *
+   * Console only. A page author's typo is not the reader's business, nothing the
+   * reader did was refused, and the degraded widget is still perfectly usable.
+   */
+  #readJsonAttribute(name) {
+    const raw = this.getAttribute(name);
     if (raw === null) {
-      return {};
+      return null;
     }
     try {
-      const parsed = JSON.parse(raw);
-      if (typeof parsed === "object" && parsed !== null) {
-        return parsed;
-      }
+      return JSON.parse(raw);
     } catch {
+      console.warn(
+        `<ag-ui-chat>: ${name} is not valid JSON, so it was ignored entirely and the built-in default is being used. Check the quoting -- JSON inside an HTML attribute needs single quotes around the attribute value, or its own double quotes escaped.`
+      );
+      return null;
     }
-    return {};
+  }
+  /** Parse the inline `data-strings` JSON overrides (empty when absent/malformed). */
+  #readStringOverrides() {
+    const parsed = this.#readJsonAttribute("data-strings");
+    return typeof parsed === "object" && parsed !== null ? parsed : {};
   }
   /**
    * Enable the composer's file-upload tray when uploads are possible — either a
@@ -13407,15 +13506,7 @@ ${quoted}`;
   }
   /** Parse the inline `data-skills` JSON catalog (empty when absent/malformed). */
   #readEmbeddedSkills() {
-    const raw = this.getAttribute("data-skills");
-    if (raw === null) {
-      return [];
-    }
-    try {
-      return parseSkills(JSON.parse(raw));
-    } catch {
-      return [];
-    }
+    return parseSkills(this.#readJsonAttribute("data-skills"));
   }
   /** Fetch the backend skills catalog from `data-skills-url`, if set. */
   async #fetchSkills() {
@@ -13454,21 +13545,21 @@ ${quoted}`;
    */
   #applySkill(skill) {
     if (skill.prompt === void 0) {
-      this.#skillHint.hidden = true;
+      this.#composerHint.hidden = true;
       void this.sendMessage(`/${skill.name}`);
       return;
     }
     const { text: text4, missing } = fillTemplate(skill.prompt, this.skillContext());
     if (missing.length > 0) {
-      this.#skillHint.textContent = this.#strings.skillNeeds.replace("{title}", skill.title).replace("{fields}", missing.join(", "));
-      this.#skillHint.hidden = false;
+      this.#composerHint.textContent = this.#strings.skillNeeds.replace("{title}", skill.title).replace("{fields}", missing.join(", "));
+      this.#composerHint.hidden = false;
       this.#input.value = text4;
       this.#autoGrow();
       this.#input.focus();
       this.#selectFirstPlaceholder(text4);
       return;
     }
-    this.#skillHint.hidden = true;
+    this.#composerHint.hidden = true;
     this.#input.value = text4;
     this.#autoGrow();
     if (skill.sendImmediately === false) {
@@ -14770,7 +14861,10 @@ ${quoted}`;
     if (message.role === "tool") {
       const card = this.#toolCards.get(message.toolCallId);
       if (card !== void 0) {
-        card.settle(TOOL_CALL_STATUS.DONE, message.content);
+        card.settle(
+          toolStatusFromOutcome(message.outcome),
+          message.content
+        );
       }
     }
   }
@@ -14988,9 +15082,9 @@ ${quoted}`;
       }
       void this.#submit();
     });
-    this.#skillHint.className = "skill-hint";
-    this.#skillHint.setAttribute("part", "skill-hint");
-    this.#skillHint.hidden = true;
+    this.#composerHint.className = "skill-hint";
+    this.#composerHint.setAttribute("part", "skill-hint");
+    this.#composerHint.hidden = true;
     this.#attachButton.className = "attach-btn";
     this.#attachButton.type = "button";
     this.#attachButton.setAttribute("part", "attach-button");
@@ -15018,7 +15112,7 @@ ${quoted}`;
       this.#messagesWrap,
       this.#skillsMenu.palette,
       this.#skillsMenu.chips,
-      this.#skillHint,
+      this.#composerHint,
       this.#queuedRow,
       this.#attachSlot,
       inputRow,
@@ -15291,10 +15385,16 @@ ${quoted}`;
   #updateEmptyState() {
     this.#emptyWrap.hidden = this.#messages.childElementCount > 1;
   }
-  /** Forward input changes to the skills palette and clear any stale hint. */
+  /**
+   * Forward input changes to the skills palette and clear any stale hint.
+   *
+   * Typing is the answer to every hint that surface carries -- a skill short of
+   * a field, a continuation short of its next turn -- so the keystroke that
+   * starts answering it is the right moment to take it down.
+   */
   #onInput() {
     this.#skillsMenu.onInput(this.#input.value);
-    this.#skillHint.hidden = true;
+    this.#composerHint.hidden = true;
     this.#autoGrow();
     this.#recallIndex = null;
   }
@@ -15531,8 +15631,36 @@ ${quoted}`;
       })
     );
   }
+  /**
+   * Hand the message to the client, or say why it is going nowhere.
+   *
+   * With no `endpoint` there is nothing to send to, and this used to return
+   * here in silence. That is the worst shape the failure can take, because the
+   * two halves of a send that *did* work have already happened by now: the
+   * user's bubble is on screen and {@link SUBMIT_EVENT} has been dispatched. So
+   * the message looks sent, the composer is empty, the Send button never turns
+   * into Stop, and no request is ever made -- an unanswered question rather
+   * than a broken widget. Nothing reached the console either, so the developer
+   * had no thread to pull and the user had no reason to think anything was
+   * wrong with the page.
+   *
+   * Both audiences are told, because they need different things. The console
+   * carries the developer's version -- the attribute is missing, here is what
+   * to set -- since a missing attribute is a page's mistake and not the
+   * reader's. The transcript carries the reader's, because they are looking at
+   * their own message waiting for a reply that cannot come, and the honest
+   * alternative to one muted line is an indefinite wait.
+   *
+   * Said on every attempt rather than once. Each send is a separate thing the
+   * user asked for and did not get, and a once-only report is silence for every
+   * attempt after the first -- which is the defect again, just later.
+   */
   async #client_send(content, attachments) {
     if (this.endpoint === "") {
+      console.error(
+        '<ag-ui-chat>: no endpoint is set, so this message was not sent and no request was made. Point the element at your AG-UI mount with the endpoint attribute (endpoint="/agent/"), or assign chat.endpoint before sending.'
+      );
+      this.#appendNotice("\u26A0", this.#strings.notConnected, "not-connected");
       return;
     }
     await this.#ensureClient().send(content, attachments);
@@ -15674,7 +15802,7 @@ ${quoted}`;
       const message = this.#strings.pageMoved;
       card.settle(TOOL_CALL_STATUS.ERROR, message);
       this.#showPending();
-      return { content: `Error: ${message}`, error: message };
+      return { content: `Error: ${message}`, error: message, outcome: TOOL_OUTCOME.FAILED };
     }
     const rule = await this.#confirmationRule(call, tool);
     if (rule !== null) {
@@ -15699,7 +15827,7 @@ ${quoted}`;
         const message = this.#strings.declinedAction;
         card.settle(TOOL_CALL_STATUS.DECLINED, message);
         this.#showPending();
-        return { content: message };
+        return { content: message, outcome: TOOL_OUTCOME.DENIED };
       }
     }
     const navigates = isNavigates(tool.parameters) && this.navigate === null;
@@ -15726,7 +15854,7 @@ ${quoted}`;
       const message = error instanceof Error ? error.message : String(error);
       card.settle(TOOL_CALL_STATUS.ERROR, message);
       this.#showPending();
-      return { content: `Error: ${message}`, error: message };
+      return { content: `Error: ${message}`, error: message, outcome: TOOL_OUTCOME.FAILED };
     }
   }
   /**
@@ -15898,12 +16026,12 @@ ${quoted}`;
       onMessagesSnapshot: () => {
         this.#appendNotice("\u{1F504}", this.#strings.historyReplaced, "history-replaced");
       },
-      onToolResult: (toolCallId, content) => {
+      onToolResult: (toolCallId, content, outcome) => {
         const card = this.#toolCards.get(toolCallId);
         if (card === void 0) {
           return;
         }
-        card.settle(TOOL_CALL_STATUS.DONE, content);
+        card.settle(toolStatusFromOutcome(outcome), content);
         this.#serverSettled.add(toolCallId);
         this.#showPending();
       },
@@ -16539,7 +16667,7 @@ function setControlValue(el2, value) {
 }
 
 // src/version.ts
-var VERSION = "0.35.2";
+var VERSION = "0.37.0";
 export {
   ATTACHMENT_EVENT,
   AgUiChat,
@@ -16575,6 +16703,7 @@ export {
   TOGGLE_EVENT,
   TOOL_CALL_STATUS,
   TOOL_DISPLAY,
+  TOOL_OUTCOME,
   ToolCallCard,
   UNREAD_EVENT,
   VERSION,
@@ -16628,6 +16757,7 @@ export {
   suggestionPrompts,
   toggleCheckbox,
   toggleControl,
+  toolStatusFromOutcome,
   transcribeAudio,
   typeInto,
   uploadAttachment