@noodleseed/assistant 1.19.0 → 1.21.0

package/README.md

@@ -202,6 +202,81 @@ claims, or tool input. The endpoint key must match the authored name. Noodle val
 only in private short-lived session state, and an omitted route leaves only dependent tools unavailable.
 Mint a new session when the user's selected account or cluster changes.
 
+#### Public website embeds
+
+Everything above serves a signed-in user through your backend. A `publicWebsite(...)` surface serves the
+same assistant to anonymous visitors — a marketing site, docs, or landing page — with a **required**
+capability allowlist, per-surface daily budgets, and a kill switch. `noodle deploy` provisions a stable
+embed id and prints a one-line snippet; the embed id is deliberately not a credential:
+
+```html
+<script src="https://cloud.noodleseed.dev/v1/assistant/embed.js"
+        data-embed-id="pub_7f2q4k9x" async></script>
+```
+
+In a bundled app, the same public surface mounts through the element or React wrapper with `embedId`
+instead of `sessionEndpoint` — the two are mutually exclusive, and a public embed needs no backend route:
+
+```tsx
+<AssistantWidget embedId="pub_7f2q4k9x" serviceUrl="https://cloud.noodleseed.dev" />
+```
+
+A public embed opens its session on **first open**, never on mount — every mount would otherwise spend
+one of the surface's daily admission budget. Add `signIn: true` to the surface and it becomes **mixed**:
+anonymous visitors start immediately, and identity-dependent capabilities raise the sign-in flow below.
+Before shipping, preflight the host with `noodle assistant embed --check --surface public` (or `mixed`) —
+it verifies `script-src` too, the one CSP directive whose failure runs no widget code at all.
+
+#### Mid-conversation sign-in (mixed surfaces)
+
+On a `publicWebsite({ signIn: true })` surface, an anonymous visitor who reaches an identity-dependent
+capability sees a "Sign in to continue" card, and the widget raises `assistant-sign-in-requested` with a
+single-use `signInTicket` in its detail. The page signs the visitor in however it already does, then its
+backend spends the ticket with the **same** helper and its own client credentials — same endpoint, same
+`user` shape, plus the ticket:
+
+```ts
+const session = await createAssistantSession({
+  serviceUrl: process.env.NOODLE_SERVICE_URL!,
+  clientId: process.env.NOODLE_ASSISTANT_CLIENT_ID!,
+  clientSecret: process.env.NOODLE_ASSISTANT_CLIENT_SECRET!,
+  origin: process.env.PUBLIC_APP_ORIGIN!,
+  user: { id: user.id, email: user.email, roles: user.roles },
+  signInTicket, // from the widget's assistant-sign-in-requested event, via your page
+});
+```
+
+The visitor keeps the same conversation with a new token; the anonymous token dies at that moment —
+and by default **the assistant answers the pending question itself**: the service re-attempts the
+intercepted tool under the signed-in principal and streams the result as the session's first turn,
+so the panel's first content after sign-in is the answer the visitor asked for. It is one-shot
+(consumed by that turn, or mooted the moment the visitor types first), confirm-gated tools stop at
+their normal confirmation card — sign-in is never implicit consent for a write — and the turn counts
+against the surface's daily budget like any other. Pass `resume: false` beside the ticket if your
+application provides its own post-login affordance.
+`signInTicket` and `context` are mutually exclusive — an elevation continues an existing session.
+`routing` IS accepted here, and this is the moment to send it: elevation is the first authenticated
+exchange, so it is the only chance a routed connector's session gets its backend-verified customer
+routes. Possession of a ticket alone elevates nothing:
+spending it also requires your client credentials, and the service checks your tenant owns that
+conversation. (The ticket is deliberately **not** called a continuation: the server-held interaction
+continuation described below must never reach browser code, while this value's whole job is to travel
+through the page.)
+
+A refused spend throws `AssistantSessionExchangeError`; branch on `error.elevationRefusal`:
+
+| Code | What happened | What to do |
+| :-- | :-- | :-- |
+| `elevation_ticket_expired` | The visitor took too long (tickets live 10 minutes) | Re-prompt; the widget raises a fresh ticket when they retry the action |
+| `elevation_ticket_invalid` | Stale, spent, or double-submitted ticket | Same recovery; log it — a burst is a replay signal |
+| `elevation_tenant_mismatch` | Your credentials do not own that conversation | Alert someone; never retry |
+| `elevation_already_signed_in` / `elevation_session_unavailable` | The conversation moved on | Ask the visitor to refresh |
+
+`error.detail.serviceCode === "elevation_unavailable"` (a 503) means the deployment has no elevation
+store configured — page the operator, not the visitor. Failures without a code (fresh-mint refusals,
+proxy errors) carry `error.detail.status`, and `error.detail.retryable` is `true` only for
+infrastructure 5xx responses.
+
 Then add the framework-neutral element:
 
 ```ts
@@ -426,6 +501,21 @@ element.addEventListener("assistant-view-available", (event) => {
 });
 ```
 
+#### Readiness and call ordering
+
+`assistant-ready` fires **once per element lifetime**, when the element's shadow DOM is rendered and its
+imperative API (`sendMessage`, `confirmTool`, …) is callable. It does **not** mean a session exists — that
+is the `assistant-event` with `event: 'session_started'`. A DOM move (router reparent, portal) re-runs the
+element's connection lifecycle but never re-fires the event. The React wrapper's `onReady` mirrors this:
+at most once per component instance, whether the element upgraded before or after the component mounted;
+the first callback identity wins, and a `console.debug('[noodle-assistant] ready')` breadcrumb marks the
+moment for field diagnosis.
+
+`sendMessage` awaits an in-flight eager session exchange and never opens a second session — a message sent
+while the panel is still connecting is delivered on the session that exchange produces. It does **not**
+queue: a `sendMessage` issued while another send or response is in flight rejects with a retryable
+`request_in_progress` error before touching the transcript.
+
 Assistant text renders as provider deltas arrive. If a turn finds an expired session, the component calls
 the same authenticated session endpoint and retries that unprocessed message once. Confirmations never
 replay across sessions. React applications may observe recovery and structured failures:

package/dist/{chunk-RFETV5KQ.js → chunk-LEKEIHJV.js}

@@ -4,7 +4,7 @@ import {
   copyAssistantPageContext,
   createAssistantClient,
   sessionSourceKey
-} from "./chunk-S373FCAI.js";
+} from "./chunk-ZPZHPXIQ.js";
 import {
   _enum,
   _null,
@@ -6824,6 +6824,11 @@ var AssistantElementEventController = class {
       this.#completedTool = void 0;
       return;
     }
+    if (name === "resume_started") {
+      this.#startStream("message");
+      this.#host.element.dispatchEvent(new CustomEvent("assistant-message-started"));
+      return;
+    }
     if (name === "interaction_completed") {
       if (this.#streamKind !== "interaction") return;
       this.#finishInteraction(String(data.id ?? ""), String(data.action ?? "accept"));
@@ -6844,11 +6849,11 @@ var AssistantElementEventController = class {
       );
       return;
     }
-    if (name === "auth_requested" && typeof data.continuation === "string") {
+    if (name === "auth_requested" && typeof data.signInTicket === "string") {
       this.#appendSignInRequest(
         String(data.id ?? ""),
         String(data.tool ?? "this"),
-        data.continuation,
+        data.signInTicket,
         String(data.expiresAt ?? "")
       );
       return;
@@ -6941,15 +6946,15 @@ var AssistantElementEventController = class {
   /**
    * The host application owns the login. This renders the prompt and raises
    * `assistant-sign-in-requested`; the page signs the visitor in however it already does, then its
-   * backend spends the continuation. Nothing here talks to an identity provider.
+   * backend spends the sign-in ticket. Nothing here talks to an identity provider.
    */
-  #appendSignInRequest(id, tool, continuation, expiresAt) {
+  #appendSignInRequest(id, tool, signInTicket, expiresAt) {
     const messages = this.#host.messages();
     if (!messages) return;
     this.#proposalCards.get(id)?.remove();
     const card = createSignInCard({
       tool,
-      continuation,
+      signInTicket,
       expiresAt,
       labels: {
         heading: "Sign in to continue",
@@ -6957,7 +6962,7 @@ var AssistantElementEventController = class {
       },
       onSignIn: () => this.#host.element.dispatchEvent(
         new CustomEvent("assistant-sign-in-requested", {
-          detail: { id, tool, continuation, expiresAt },
+          detail: { id, tool, signInTicket, expiresAt },
           bubbles: true,
           composed: true
         })
@@ -6968,7 +6973,7 @@ var AssistantElementEventController = class {
     this.#host.revealLatest();
     this.#host.element.dispatchEvent(
       new CustomEvent("assistant-sign-in-required", {
-        detail: { id, tool, continuation, expiresAt }
+        detail: { id, tool, signInTicket, expiresAt }
       })
     );
   }
@@ -7042,6 +7047,36 @@ function queryRequired(root, selector) {
   if (!element) throw new Error(`assistant renderer is missing ${selector}`);
   return element;
 }
+function assistantElementMarkup(appearance, open, styles) {
+  return `${styles}
+      <button class="launcher" type="button" aria-label="${escapeAttribute(appearance.labels.open)}" aria-controls="assistant-panel" aria-expanded="${String(open)}"><slot name="launcher-icon"></slot><span class="visually-hidden" data-session-status aria-live="polite" hidden></span></button>
+      <section class="panel" id="assistant-panel" role="dialog" aria-label="${escapeAttribute(appearance.brand.name)}">
+        <header><slot name="header-leading"></slot><img class="brand-logo" alt=""><strong></strong><slot name="header-actions"></slot><button class="close" type="button" aria-label="${escapeAttribute(appearance.labels.close)}"></button></header>
+        <div class="welcome"><slot name="empty-state"></slot></div>
+        <div class="suggested-prompts"></div>
+        <div class="messages-region">
+          <div class="messages" aria-live="polite"></div>
+          <button class="new-messages" type="button" aria-label="${escapeAttribute(appearance.labels.newMessages)}" hidden></button>
+        </div>
+        <form><slot name="composer-leading"></slot><textarea rows="1"></textarea><button class="send" type="submit"></button><slot name="composer-trailing"></slot></form>
+        <nav class="legal" aria-label="Legal"></nav>
+        <slot name="conversation-footer"></slot>
+      </section>`;
+}
+function appendLegalLinks(legal, appearance) {
+  for (const [label, href] of [
+    ["Privacy", appearance.privacyUrl],
+    ["Terms", appearance.termsUrl]
+  ]) {
+    if (!href) continue;
+    const link = document.createElement("a");
+    link.href = href;
+    link.target = "_blank";
+    link.rel = "noopener noreferrer";
+    link.textContent = label;
+    legal.append(link);
+  }
+}
 
 // src/element-page-context-controller.ts
 var AssistantElementPageContextController = class {
@@ -7829,6 +7864,8 @@ var NoodleAssistantElement = class extends HTMLElementBase {
   #pendingUserEcho;
   #sessionState = "idle";
   #startOpenApplied = false;
+  #readyDispatched = false;
+  #turnInFlight = false;
   #hostAppearance;
   #appearanceWarningKeys = /* @__PURE__ */ new Set();
   #appearanceStyleSnapshot = /* @__PURE__ */ new Map();
@@ -7900,7 +7937,10 @@ var NoodleAssistantElement = class extends HTMLElementBase {
     document.addEventListener("pointerdown", this.#handleDocumentPointerDown);
     if (this.#appearance.behavior.startOpen) this.#applyStartOpenPolicy();
     this.#render();
-    this.dispatchEvent(new CustomEvent("assistant-ready"));
+    if (!this.#readyDispatched) {
+      this.#readyDispatched = true;
+      this.dispatchEvent(new CustomEvent("assistant-ready"));
+    }
     if (this.hasAttribute("start-open")) {
       this.setAttribute("open", "");
       this.#startOpenApplied = true;
@@ -8014,7 +8054,14 @@ var NoodleAssistantElement = class extends HTMLElementBase {
   async sendMessage(text2) {
     const message = text2.trim();
     if (!message) return;
+    if (this.#turnInFlight) {
+      throw new AssistantClientError(
+        { code: "request_in_progress", retryable: true },
+        "an assistant request is already in progress"
+      );
+    }
     const generation = this.#conversationGeneration;
+    this.#turnInFlight = true;
     this.#pendingUserEcho = message;
     this.#appendMessage("user", message);
     this.#setBusy(true);
@@ -8031,6 +8078,7 @@ var NoodleAssistantElement = class extends HTMLElementBase {
       this.#dispatchClientError(error, "turn_failed");
       throw error;
     } finally {
+      this.#turnInFlight = false;
       if (this.#pendingUserEcho === message) this.#pendingUserEcho = void 0;
       if (generation === this.#conversationGeneration) this.#setBusy(false);
     }
@@ -8099,6 +8147,7 @@ var NoodleAssistantElement = class extends HTMLElementBase {
   #primeSession() {
     if (!this.sessionEndpoint && !this.embedId) return;
     if (this.#sessionBootstrap || this.#client?.hasSession()) return;
+    if (this.#client?.isBusy?.() === true) return;
     if (this.embedId && !this.#pageContext) void this.#automaticPageContext.refresh();
     const client = this.#ensureClient();
     const generation = this.#conversationGeneration;
@@ -8128,6 +8177,8 @@ var NoodleAssistantElement = class extends HTMLElementBase {
     if (event.event === "content" || event.event === "message_completed" || event.event === "interaction_completed" || event.event === "error") {
       this.#removeThinking();
     }
+    if (event.event === "resume_started") this.#setBusy(true);
+    if (event.event === "message_completed" || event.event === "error") this.#setBusy(false);
   }
   #setBusy(busy) {
     this.toggleAttribute("busy", busy);
@@ -8336,7 +8387,7 @@ var NoodleAssistantElement = class extends HTMLElementBase {
     queryRequired(this.shadowRoot, "header").hidden = !appearance.behavior.showHeader;
     const legal = queryRequired(this.shadowRoot, ".legal");
     legal.replaceChildren();
-    this.#appendLegalLinks(legal);
+    appendLegalLinks(legal, this.#appearance);
     this.#applyTheme();
   }
   #render() {
@@ -8352,20 +8403,11 @@ var NoodleAssistantElement = class extends HTMLElementBase {
     this.dataset.position = appearance.layout.position;
     this.dataset.density = appearance.layout.density;
     this.toggleAttribute("mobile-fullscreen", appearance.layout.mobileFullscreen);
-    this.shadowRoot.innerHTML = `${ASSISTANT_ELEMENT_STYLES}${presentationStyles}
-      <button class="launcher" type="button" aria-label="${escapeAttribute(appearance.labels.open)}" aria-controls="assistant-panel" aria-expanded="${String(this.hasAttribute("open"))}"><slot name="launcher-icon"></slot><span class="visually-hidden" data-session-status aria-live="polite" hidden></span></button>
-      <section class="panel" id="assistant-panel" role="dialog" aria-label="${escapeAttribute(appearance.brand.name)}">
-        <header><slot name="header-leading"></slot><img class="brand-logo" alt=""><strong></strong><slot name="header-actions"></slot><button class="close" type="button" aria-label="${escapeAttribute(appearance.labels.close)}"></button></header>
-        <div class="welcome"><slot name="empty-state"></slot></div>
-        <div class="suggested-prompts"></div>
-        <div class="messages-region">
-          <div class="messages" aria-live="polite"></div>
-          <button class="new-messages" type="button" aria-label="${escapeAttribute(appearance.labels.newMessages)}" hidden></button>
-        </div>
-        <form><slot name="composer-leading"></slot><textarea rows="1"></textarea><button class="send" type="submit"></button><slot name="composer-trailing"></slot></form>
-        <nav class="legal" aria-label="Legal"></nav>
-        <slot name="conversation-footer"></slot>
-      </section>`;
+    this.shadowRoot.innerHTML = assistantElementMarkup(
+      appearance,
+      this.hasAttribute("open"),
+      `${ASSISTANT_ELEMENT_STYLES}${presentationStyles}`
+    );
     queryRequired(this.shadowRoot, "strong").textContent = appearance.brand.name;
     const logo = queryRequired(this.shadowRoot, ".brand-logo");
     const logoUrl = appearance.brand.logo[this.#resolvedMode()];
@@ -8392,7 +8434,7 @@ var NoodleAssistantElement = class extends HTMLElementBase {
     if (!appearance.behavior.showHeader)
       queryRequired(this.shadowRoot, "header").hidden = true;
     const legal = queryRequired(this.shadowRoot, ".legal");
-    this.#appendLegalLinks(legal);
+    appendLegalLinks(legal, this.#appearance);
     this.#messages = this.shadowRoot.querySelector(".messages") ?? void 0;
     this.#messages?.append(...conversation);
     this.#thinking = this.#messages?.querySelector(".thinking") ?? void 0;
@@ -8431,20 +8473,6 @@ var NoodleAssistantElement = class extends HTMLElementBase {
     });
     this.#applyTheme();
   }
-  #appendLegalLinks(legal) {
-    for (const [label, href] of [
-      ["Privacy", this.#appearance.privacyUrl],
-      ["Terms", this.#appearance.termsUrl]
-    ]) {
-      if (!href) continue;
-      const link = document.createElement("a");
-      link.href = href;
-      link.target = "_blank";
-      link.rel = "noopener noreferrer";
-      link.textContent = label;
-      legal.append(link);
-    }
-  }
 };
 function registerNoodleAssistant() {
   if (globalThis.customElements && !customElements.get(ASSISTANT_TAG_NAME)) {
@@ -8465,4 +8493,4 @@ export {
 dompurify/dist/purify.es.mjs:
   (*! @license DOMPurify 3.4.11 | (c) Cure53 and other contributors | Released under the Apache license 2.0 and Mozilla Public License 2.0 | github.com/cure53/DOMPurify/blob/3.4.11/LICENSE *)
 */
-//# sourceMappingURL=chunk-RFETV5KQ.js.map
+//# sourceMappingURL=chunk-LEKEIHJV.js.map