@noodleseed/assistant 1.19.0 → 1.21.0

package/dist/react.d.cts

@@ -1,7 +1,7 @@
 import { ReactElement, RefAttributes } from 'react';
 import { a as AssistantThemeMode } from './appearance-Cc-eqSbp.cjs';
 import { AssistantAppearance, AssistantAppearanceWarning, NoodleAssistantElement } from './index.cjs';
-import { c as AssistantClient, d as AssistantViewAvailableDetail, A as AssistantPageContext, a as AssistantContext, e as AssistantModelContextUpdate, f as AssistantClientEvent, g as AssistantErrorDetail } from './client-BQ30Fq-c.cjs';
+import { c as AssistantClient, d as AssistantViewAvailableDetail, A as AssistantPageContext, a as AssistantContext, e as AssistantModelContextUpdate, f as AssistantClientEvent, g as AssistantErrorDetail } from './client-BZ7xPwfW.cjs';
 import 'ai';
 
 interface NoodleAppViewProps {
@@ -37,6 +37,13 @@ interface NoodleAssistantProps<TPageContext extends AssistantPageContext = Assis
     readonly pageContext?: TPageContext;
     readonly modelContext?: AssistantModelContextUpdate;
     readonly onEvent?: (event: AssistantClientEvent) => void;
+    /**
+     * Fires at most once per component instance, when the element's shadow DOM is rendered and its
+     * imperative API (`sendMessage`, `confirmTool`, …) is callable — NOT when a session exists (listen
+     * for the `session_started` client event via `onEvent` for that). It fires whether the element
+     * upgraded before or after this component mounted, and the first callback identity wins: a later
+     * re-render with a different `onReady` is never invoked.
+     */
     readonly onReady?: () => void;
     readonly onError?: (error: AssistantErrorDetail) => void;
     readonly onAppearanceWarning?: (warning: AssistantAppearanceWarning) => void;

package/dist/react.d.ts

@@ -1,7 +1,7 @@
 import { ReactElement, RefAttributes } from 'react';
 import { a as AssistantThemeMode } from './appearance-Cc-eqSbp.js';
 import { AssistantAppearance, AssistantAppearanceWarning, NoodleAssistantElement } from './index.js';
-import { c as AssistantClient, d as AssistantViewAvailableDetail, A as AssistantPageContext, a as AssistantContext, e as AssistantModelContextUpdate, f as AssistantClientEvent, g as AssistantErrorDetail } from './client-B6pnBmF8.js';
+import { c as AssistantClient, d as AssistantViewAvailableDetail, A as AssistantPageContext, a as AssistantContext, e as AssistantModelContextUpdate, f as AssistantClientEvent, g as AssistantErrorDetail } from './client-BkJlpN5N.js';
 import 'ai';
 
 interface NoodleAppViewProps {
@@ -37,6 +37,13 @@ interface NoodleAssistantProps<TPageContext extends AssistantPageContext = Assis
     readonly pageContext?: TPageContext;
     readonly modelContext?: AssistantModelContextUpdate;
     readonly onEvent?: (event: AssistantClientEvent) => void;
+    /**
+     * Fires at most once per component instance, when the element's shadow DOM is rendered and its
+     * imperative API (`sendMessage`, `confirmTool`, …) is callable — NOT when a session exists (listen
+     * for the `session_started` client event via `onEvent` for that). It fires whether the element
+     * upgraded before or after this component mounted, and the first callback identity wins: a later
+     * re-render with a different `onReady` is never invoked.
+     */
     readonly onReady?: () => void;
     readonly onError?: (error: AssistantErrorDetail) => void;
     readonly onAppearanceWarning?: (warning: AssistantAppearanceWarning) => void;

package/dist/react.js

@@ -3,8 +3,8 @@ import {
   registerNoodleAssistant,
   unmountAssistantApp,
   updateAssistantAppTheme
-} from "./chunk-RFETV5KQ.js";
-import "./chunk-S373FCAI.js";
+} from "./chunk-LEKEIHJV.js";
+import "./chunk-ZPZHPXIQ.js";
 import "./chunk-3YYTUJPJ.js";
 import "./chunk-5FUTL2UF.js";
 
@@ -79,6 +79,7 @@ var NoodleAssistantWithRef = forwardRef(
       const ready = () => {
         if (readyNotified.current) return;
         readyNotified.current = true;
+        console.debug("[noodle-assistant] ready");
         props.onReady?.();
       };
       const error = (event) => props.onError?.(event.detail);

package/dist/react.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/react.ts","../src/react-app-view.ts"],"sourcesContent":["import {\n  createElement,\n  forwardRef,\n  type ReactElement,\n  type RefAttributes,\n  useEffect,\n  useImperativeHandle,\n  useRef,\n} from 'react';\nimport type { AssistantThemeMode } from './appearance.js';\nimport type { AssistantAppearance, AssistantAppearanceWarning } from './host-appearance.js';\n\nexport type { AssistantAppearance, AssistantAppearanceWarning } from './host-appearance.js';\n\nimport type {\n  AssistantClientEvent,\n  AssistantContext,\n  AssistantModelContextUpdate,\n  AssistantPageContext,\n} from './client.js';\nimport { type NoodleAssistantElement, registerNoodleAssistant } from './element.js';\nimport type { AssistantErrorDetail } from './transport.js';\n\nexport { NoodleAppView, type NoodleAppViewProps } from './react-app-view.js';\n\nexport interface NoodleAssistantProps<\n  TPageContext extends AssistantPageContext = AssistantContext,\n> {\n  /** In-app mount: the customer backend route that exchanges an embed secret for a session. */\n  readonly sessionEndpoint?: string;\n  /** Public mount: the non-secret embed id `noodle deploy` printed. Exclusive with `sessionEndpoint`. */\n  readonly embedId?: string;\n  /** Only for a dev or self-hosted service; a published page needs no origin. */\n  readonly serviceUrl?: string;\n  readonly theme?: AssistantThemeMode;\n  readonly appearance?: AssistantAppearance;\n  readonly open?: boolean;\n  readonly className?: string;\n  readonly context?: AssistantContext;\n  readonly pageContext?: TPageContext;\n  readonly modelContext?: AssistantModelContextUpdate;\n  readonly onEvent?: (event: AssistantClientEvent) => void;\n  readonly onReady?: () => void;\n  readonly onError?: (error: AssistantErrorDetail) => void;\n  readonly onAppearanceWarning?: (warning: AssistantAppearanceWarning) => void;\n  readonly onSessionExpired?: () => void;\n}\n\nconst NoodleAssistantWithRef = forwardRef<NoodleAssistantElement, NoodleAssistantProps>(\n  function NoodleAssistant(props, forwardedRef): ReactElement {\n    const ref = useRef<NoodleAssistantElement>(null);\n    const readyNotified = useRef(false);\n    useImperativeHandle(forwardedRef, () => ref.current as NoodleAssistantElement, []);\n    useEffect(() => {\n      const element = ref.current;\n      if (!element) return;\n      const ready = () => {\n        if (readyNotified.current) return;\n        readyNotified.current = true;\n        props.onReady?.();\n      };\n      const error = (event: Event) =>\n        props.onError?.((event as CustomEvent<AssistantErrorDetail>).detail);\n      const expired = () => props.onSessionExpired?.();\n      const assistantEvent = (event: Event) =>\n        props.onEvent?.((event as CustomEvent<AssistantClientEvent>).detail);\n      const appearanceWarning = (event: Event) =>\n        props.onAppearanceWarning?.((event as CustomEvent<AssistantAppearanceWarning>).detail);\n      element.addEventListener('assistant-ready', ready);\n      element.addEventListener('assistant-error', error);\n      element.addEventListener('assistant-session-expired', expired);\n      element.addEventListener('assistant-event', assistantEvent);\n      element.addEventListener('assistant-appearance-warning', appearanceWarning);\n      registerNoodleAssistant();\n      element.sessionEndpoint = props.sessionEndpoint ?? '';\n      element.embedId = props.embedId ?? '';\n      element.serviceUrl = props.serviceUrl ?? '';\n      element.appearance = props.appearance;\n      element.toggleAttribute('open', props.open === true);\n      if (props.context) element.updateContext(props.context);\n      if (props.pageContext) element.updatePageContext(props.pageContext);\n      if (props.modelContext) element.updateModelContext(props.modelContext);\n      // The canonical entry may have registered and upgraded the element before this effect ran.\n      // Readiness is sticky once the shadow root exists, so late React listeners still fire once.\n      if (element.shadowRoot) ready();\n      return () => {\n        element.removeEventListener('assistant-ready', ready);\n        element.removeEventListener('assistant-error', error);\n        element.removeEventListener('assistant-session-expired', expired);\n        element.removeEventListener('assistant-event', assistantEvent);\n        element.removeEventListener('assistant-appearance-warning', appearanceWarning);\n      };\n    }, [\n      props.context,\n      props.appearance,\n      props.modelContext,\n      props.onError,\n      props.onAppearanceWarning,\n      props.onEvent,\n      props.onReady,\n      props.onSessionExpired,\n      props.open,\n      props.pageContext,\n      props.sessionEndpoint,\n      props.embedId,\n      props.serviceUrl,\n    ]);\n    return createElement('noodle-assistant', {\n      ref,\n      class: props.className,\n      ...(props.sessionEndpoint ? { 'session-endpoint': props.sessionEndpoint } : {}),\n      ...(props.embedId ? { 'embed-id': props.embedId } : {}),\n      ...(props.serviceUrl ? { 'service-url': props.serviceUrl } : {}),\n      ...(props.theme ? { theme: props.theme } : {}),\n    });\n  },\n);\n\nexport const NoodleAssistant = NoodleAssistantWithRef as <\n  TPageContext extends AssistantPageContext = AssistantContext,\n>(\n  props: NoodleAssistantProps<TPageContext> & RefAttributes<NoodleAssistantElement>,\n) => ReactElement;\n","import { createElement, type ReactElement, useEffect, useRef } from 'react';\nimport { mountAssistantApp, unmountAssistantApp, updateAssistantAppTheme } from './app-host.js';\nimport type { AssistantClient, AssistantViewAvailableDetail } from './client.js';\n\nexport interface NoodleAppViewProps {\n  readonly client: AssistantClient;\n  readonly view: AssistantViewAvailableDetail;\n  readonly theme?: 'light' | 'dark';\n  readonly className?: string;\n  readonly onError?: (failure: {\n    readonly code: 'view_render_timeout';\n    readonly retryable: false;\n  }) => void;\n}\n\n/**\n * Securely hosts one service-resolved MCP App inside a customer-owned React renderer.\n *\n * The bridge lifetime follows semantic view identity, so ordinary parent rerenders cannot reset an\n * in-progress App interaction.\n */\nexport function NoodleAppView({\n  client,\n  view,\n  theme = 'light',\n  className,\n  onError,\n}: NoodleAppViewProps): ReactElement {\n  const container = useRef<HTMLDivElement>(null);\n  const mounted = useRef<HTMLElement>(null);\n  const current = useRef({ view, theme, onError });\n  const viewId = view.id;\n  const resourceUri = view.resourceUri;\n\n  useEffect(() => {\n    current.current = { view, theme, onError };\n  });\n\n  useEffect(() => {\n    const host = container.current;\n    if (!host) return;\n    const initialView = { ...current.current.view, id: viewId, resourceUri };\n    const sandboxUrl = client.appSandboxUrl?.();\n    const card = mountAssistantApp(\n      initialView,\n      {\n        client,\n        sendMessage: (message) => client.sendMessage(message),\n        updateModelContext: (update) => client.updateModelContext(update),\n        theme: current.current.theme,\n      },\n      {\n        ...(sandboxUrl ? { sandboxUrl } : {}),\n        getDetail: () => current.current.view,\n        onRenderFailure: (failure) => current.current.onError?.(failure),\n      },\n    );\n    if (!card) return;\n    mounted.current = card;\n    host.replaceChildren(card);\n    return () => {\n      if (mounted.current === card) mounted.current = null;\n      void unmountAssistantApp(card);\n    };\n  }, [client, resourceUri, viewId]);\n\n  useEffect(() => {\n    if (mounted.current) updateAssistantAppTheme(mounted.current, theme);\n  }, [theme]);\n\n  return createElement('div', { ref: container, className });\n}\n"],"mappings":"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","names":["createElement","useEffect","useRef","useRef","useEffect","createElement","NoodleAssistant"]}
+{"version":3,"sources":["../src/react.ts","../src/react-app-view.ts"],"sourcesContent":["import {\n  createElement,\n  forwardRef,\n  type ReactElement,\n  type RefAttributes,\n  useEffect,\n  useImperativeHandle,\n  useRef,\n} from 'react';\nimport type { AssistantThemeMode } from './appearance.js';\nimport type { AssistantAppearance, AssistantAppearanceWarning } from './host-appearance.js';\n\nexport type { AssistantAppearance, AssistantAppearanceWarning } from './host-appearance.js';\n\nimport type {\n  AssistantClientEvent,\n  AssistantContext,\n  AssistantModelContextUpdate,\n  AssistantPageContext,\n} from './client.js';\nimport { type NoodleAssistantElement, registerNoodleAssistant } from './element.js';\nimport type { AssistantErrorDetail } from './transport.js';\n\nexport { NoodleAppView, type NoodleAppViewProps } from './react-app-view.js';\n\nexport interface NoodleAssistantProps<\n  TPageContext extends AssistantPageContext = AssistantContext,\n> {\n  /** In-app mount: the customer backend route that exchanges an embed secret for a session. */\n  readonly sessionEndpoint?: string;\n  /** Public mount: the non-secret embed id `noodle deploy` printed. Exclusive with `sessionEndpoint`. */\n  readonly embedId?: string;\n  /** Only for a dev or self-hosted service; a published page needs no origin. */\n  readonly serviceUrl?: string;\n  readonly theme?: AssistantThemeMode;\n  readonly appearance?: AssistantAppearance;\n  readonly open?: boolean;\n  readonly className?: string;\n  readonly context?: AssistantContext;\n  readonly pageContext?: TPageContext;\n  readonly modelContext?: AssistantModelContextUpdate;\n  readonly onEvent?: (event: AssistantClientEvent) => void;\n  /**\n   * Fires at most once per component instance, when the element's shadow DOM is rendered and its\n   * imperative API (`sendMessage`, `confirmTool`, …) is callable — NOT when a session exists (listen\n   * for the `session_started` client event via `onEvent` for that). It fires whether the element\n   * upgraded before or after this component mounted, and the first callback identity wins: a later\n   * re-render with a different `onReady` is never invoked.\n   */\n  readonly onReady?: () => void;\n  readonly onError?: (error: AssistantErrorDetail) => void;\n  readonly onAppearanceWarning?: (warning: AssistantAppearanceWarning) => void;\n  readonly onSessionExpired?: () => void;\n}\n\nconst NoodleAssistantWithRef = forwardRef<NoodleAssistantElement, NoodleAssistantProps>(\n  function NoodleAssistant(props, forwardedRef): ReactElement {\n    const ref = useRef<NoodleAssistantElement>(null);\n    const readyNotified = useRef(false);\n    useImperativeHandle(forwardedRef, () => ref.current as NoodleAssistantElement, []);\n    useEffect(() => {\n      const element = ref.current;\n      if (!element) return;\n      const ready = () => {\n        if (readyNotified.current) return;\n        readyNotified.current = true;\n        // The one observable breadcrumb for the readiness path: integrators could previously\n        // neither convict nor exonerate this callback for a field failure.\n        console.debug('[noodle-assistant] ready');\n        props.onReady?.();\n      };\n      const error = (event: Event) =>\n        props.onError?.((event as CustomEvent<AssistantErrorDetail>).detail);\n      const expired = () => props.onSessionExpired?.();\n      const assistantEvent = (event: Event) =>\n        props.onEvent?.((event as CustomEvent<AssistantClientEvent>).detail);\n      const appearanceWarning = (event: Event) =>\n        props.onAppearanceWarning?.((event as CustomEvent<AssistantAppearanceWarning>).detail);\n      element.addEventListener('assistant-ready', ready);\n      element.addEventListener('assistant-error', error);\n      element.addEventListener('assistant-session-expired', expired);\n      element.addEventListener('assistant-event', assistantEvent);\n      element.addEventListener('assistant-appearance-warning', appearanceWarning);\n      registerNoodleAssistant();\n      element.sessionEndpoint = props.sessionEndpoint ?? '';\n      element.embedId = props.embedId ?? '';\n      element.serviceUrl = props.serviceUrl ?? '';\n      element.appearance = props.appearance;\n      element.toggleAttribute('open', props.open === true);\n      if (props.context) element.updateContext(props.context);\n      if (props.pageContext) element.updatePageContext(props.pageContext);\n      if (props.modelContext) element.updateModelContext(props.modelContext);\n      // The canonical entry may have registered and upgraded the element before this effect ran.\n      // Readiness is sticky once the shadow root exists, so late React listeners still fire once.\n      if (element.shadowRoot) ready();\n      return () => {\n        element.removeEventListener('assistant-ready', ready);\n        element.removeEventListener('assistant-error', error);\n        element.removeEventListener('assistant-session-expired', expired);\n        element.removeEventListener('assistant-event', assistantEvent);\n        element.removeEventListener('assistant-appearance-warning', appearanceWarning);\n      };\n    }, [\n      props.context,\n      props.appearance,\n      props.modelContext,\n      props.onError,\n      props.onAppearanceWarning,\n      props.onEvent,\n      props.onReady,\n      props.onSessionExpired,\n      props.open,\n      props.pageContext,\n      props.sessionEndpoint,\n      props.embedId,\n      props.serviceUrl,\n    ]);\n    return createElement('noodle-assistant', {\n      ref,\n      class: props.className,\n      ...(props.sessionEndpoint ? { 'session-endpoint': props.sessionEndpoint } : {}),\n      ...(props.embedId ? { 'embed-id': props.embedId } : {}),\n      ...(props.serviceUrl ? { 'service-url': props.serviceUrl } : {}),\n      ...(props.theme ? { theme: props.theme } : {}),\n    });\n  },\n);\n\nexport const NoodleAssistant = NoodleAssistantWithRef as <\n  TPageContext extends AssistantPageContext = AssistantContext,\n>(\n  props: NoodleAssistantProps<TPageContext> & RefAttributes<NoodleAssistantElement>,\n) => ReactElement;\n","import { createElement, type ReactElement, useEffect, useRef } from 'react';\nimport { mountAssistantApp, unmountAssistantApp, updateAssistantAppTheme } from './app-host.js';\nimport type { AssistantClient, AssistantViewAvailableDetail } from './client.js';\n\nexport interface NoodleAppViewProps {\n  readonly client: AssistantClient;\n  readonly view: AssistantViewAvailableDetail;\n  readonly theme?: 'light' | 'dark';\n  readonly className?: string;\n  readonly onError?: (failure: {\n    readonly code: 'view_render_timeout';\n    readonly retryable: false;\n  }) => void;\n}\n\n/**\n * Securely hosts one service-resolved MCP App inside a customer-owned React renderer.\n *\n * The bridge lifetime follows semantic view identity, so ordinary parent rerenders cannot reset an\n * in-progress App interaction.\n */\nexport function NoodleAppView({\n  client,\n  view,\n  theme = 'light',\n  className,\n  onError,\n}: NoodleAppViewProps): ReactElement {\n  const container = useRef<HTMLDivElement>(null);\n  const mounted = useRef<HTMLElement>(null);\n  const current = useRef({ view, theme, onError });\n  const viewId = view.id;\n  const resourceUri = view.resourceUri;\n\n  useEffect(() => {\n    current.current = { view, theme, onError };\n  });\n\n  useEffect(() => {\n    const host = container.current;\n    if (!host) return;\n    const initialView = { ...current.current.view, id: viewId, resourceUri };\n    const sandboxUrl = client.appSandboxUrl?.();\n    const card = mountAssistantApp(\n      initialView,\n      {\n        client,\n        sendMessage: (message) => client.sendMessage(message),\n        updateModelContext: (update) => client.updateModelContext(update),\n        theme: current.current.theme,\n      },\n      {\n        ...(sandboxUrl ? { sandboxUrl } : {}),\n        getDetail: () => current.current.view,\n        onRenderFailure: (failure) => current.current.onError?.(failure),\n      },\n    );\n    if (!card) return;\n    mounted.current = card;\n    host.replaceChildren(card);\n    return () => {\n      if (mounted.current === card) mounted.current = null;\n      void unmountAssistantApp(card);\n    };\n  }, [client, resourceUri, viewId]);\n\n  useEffect(() => {\n    if (mounted.current) updateAssistantAppTheme(mounted.current, theme);\n  }, [theme]);\n\n  return createElement('div', { ref: container, className });\n}\n"],"mappings":"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","names":["createElement","useEffect","useRef","useRef","useEffect","createElement","NoodleAssistant"]}

package/dist/server.cjs

@@ -20,10 +20,53 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/server.ts
 var server_exports = {};
 __export(server_exports, {
+  ASSISTANT_ELEVATION_REFUSAL_CODES: () => ASSISTANT_ELEVATION_REFUSAL_CODES,
+  AssistantSessionExchangeError: () => AssistantSessionExchangeError,
   createAssistantSession: () => createAssistantSession
 });
 module.exports = __toCommonJS(server_exports);
+var ASSISTANT_ELEVATION_REFUSAL_CODES = [
+  "elevation_ticket_invalid",
+  "elevation_ticket_expired",
+  "elevation_tenant_mismatch",
+  "elevation_session_unavailable",
+  "elevation_already_signed_in"
+];
+var AssistantSessionExchangeError = class extends Error {
+  detail;
+  constructor(detail, message) {
+    super(message);
+    this.name = "AssistantSessionExchangeError";
+    this.detail = detail;
+  }
+  /**
+   * The narrowed sign-in refusal, when this failure is one. `elevation_ticket_expired` means the
+   * visitor took too long — re-prompt; `elevation_tenant_mismatch` means a client reached for a
+   * conversation it does not own — alert someone, never retry.
+   */
+  get elevationRefusal() {
+    const code = this.detail.serviceCode;
+    return code !== void 0 && ASSISTANT_ELEVATION_REFUSAL_CODES.includes(code) ? code : void 0;
+  }
+};
+async function exchangeError(response) {
+  const body = await response.json().catch(() => void 0);
+  const serviceCode = typeof body?.code === "string" ? body.code : void 0;
+  return new AssistantSessionExchangeError(
+    {
+      code: "session_exchange_failed",
+      status: response.status,
+      // `elevation_unavailable` is a 503 an operator has to fix; retrying cannot help.
+      retryable: response.status >= 500 && serviceCode !== "elevation_unavailable",
+      ...serviceCode === void 0 ? {} : { serviceCode }
+    },
+    `Assistant session exchange failed (${response.status})`
+  );
+}
 async function createAssistantSession(input, dependencies = {}) {
+  if (input.signInTicket !== void 0 && input.context !== void 0) {
+    throw new Error("context does not apply when spending a sign-in ticket");
+  }
   const request = dependencies.fetch ?? fetch;
   const serviceUrl = input.serviceUrl.replace(/\/$/, "");
   const credentials = Buffer.from(`${input.clientId}:${input.clientSecret}`, "utf8").toString(
@@ -39,17 +82,21 @@ async function createAssistantSession(input, dependencies = {}) {
     body: JSON.stringify({
       origin: input.origin,
       user: input.user,
+      ...input.signInTicket === void 0 ? {} : { signInTicket: input.signInTicket },
+      ...input.signInTicket !== void 0 && input.resume !== void 0 ? { resume: input.resume } : {},
       ...input.claims ? { claims: input.claims } : {},
       ...input.context ? { context: input.context } : {},
       ...input.preferences ? { preferences: input.preferences } : {},
       ...input.routing ? { routing: input.routing } : {}
     })
   });
-  if (!response.ok) throw new Error(`Assistant session exchange failed (${response.status})`);
+  if (!response.ok) throw await exchangeError(response);
   return await response.json();
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ASSISTANT_ELEVATION_REFUSAL_CODES,
+  AssistantSessionExchangeError,
   createAssistantSession
 });
 //# sourceMappingURL=server.cjs.map

package/dist/server.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/server.ts"],"sourcesContent":["import type { AssistantConfiguration } from './appearance.js';\n\nexport interface CreateAssistantSessionInput {\n  readonly serviceUrl: string;\n  readonly clientId: string;\n  readonly clientSecret: string;\n  /** Browser origin to bind into the short-lived assistant session. */\n  readonly origin: string;\n  readonly user: {\n    readonly id: string;\n    readonly email?: string;\n    readonly name?: string;\n    readonly tenant?: string;\n    readonly roles?: readonly string[];\n    readonly scopes?: readonly string[];\n  };\n  readonly context?: Readonly<Record<string, string | number | boolean | null>>;\n  /** Backend-verified user preferences; these outrank untrusted browser presentation hints. */\n  readonly preferences?: {\n    readonly locale?: string;\n    readonly timeZone?: string;\n  };\n  /** Backend-verified connector routes keyed by authored `customerEndpoint` name. */\n  readonly routing?: {\n    readonly endpoints: Readonly<Record<string, string>>;\n  };\n  /**\n   * Verified session claims from your authenticated backend. Only claims the server declares in\n   * `embeddedAssistant({ sessionClaims })` reach tools (`\\${user.claims.<key>}`) and, when marked\n   * `exposeToModel`, the assistant's identity context. Flat scalars only.\n   */\n  readonly claims?: Readonly<Record<string, string | number | boolean | null>>;\n}\n\nexport interface AssistantSession {\n  readonly token: string;\n  readonly expiresAt: string;\n  readonly endpoints: {\n    readonly turns: string;\n    readonly toolConfirmations: string;\n    readonly interactions?: string;\n    readonly apps?: string;\n    /** Additive hosted sandbox document for widget frames; absent on older services. */\n    readonly sandbox?: string;\n  };\n  readonly configuration?: AssistantConfiguration;\n}\n\nexport async function createAssistantSession(\n  input: CreateAssistantSessionInput,\n  dependencies: { readonly fetch?: typeof fetch } = {},\n): Promise<AssistantSession> {\n  const request = dependencies.fetch ?? fetch;\n  const serviceUrl = input.serviceUrl.replace(/\\/$/, '');\n  const credentials = Buffer.from(`${input.clientId}:${input.clientSecret}`, 'utf8').toString(\n    'base64',\n  );\n  const response = await request(`${serviceUrl}/v1/assistant/sessions`, {\n    method: 'POST',\n    headers: {\n      Authorization: `Basic ${credentials}`,\n      Accept: 'application/json',\n      'Content-Type': 'application/json',\n    },\n    body: JSON.stringify({\n      origin: input.origin,\n      user: input.user,\n      ...(input.claims ? { claims: input.claims } : {}),\n      ...(input.context ? { context: input.context } : {}),\n      ...(input.preferences ? { preferences: input.preferences } : {}),\n      ...(input.routing ? { routing: input.routing } : {}),\n    }),\n  });\n  if (!response.ok) throw new Error(`Assistant session exchange failed (${response.status})`);\n  return (await response.json()) as AssistantSession;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAgDA,eAAsB,uBACpB,OACA,eAAkD,CAAC,GACxB;AAC3B,QAAM,UAAU,aAAa,SAAS;AACtC,QAAM,aAAa,MAAM,WAAW,QAAQ,OAAO,EAAE;AACrD,QAAM,cAAc,OAAO,KAAK,GAAG,MAAM,QAAQ,IAAI,MAAM,YAAY,IAAI,MAAM,EAAE;AAAA,IACjF;AAAA,EACF;AACA,QAAM,WAAW,MAAM,QAAQ,GAAG,UAAU,0BAA0B;AAAA,IACpE,QAAQ;AAAA,IACR,SAAS;AAAA,MACP,eAAe,SAAS,WAAW;AAAA,MACnC,QAAQ;AAAA,MACR,gBAAgB;AAAA,IAClB;AAAA,IACA,MAAM,KAAK,UAAU;AAAA,MACnB,QAAQ,MAAM;AAAA,MACd,MAAM,MAAM;AAAA,MACZ,GAAI,MAAM,SAAS,EAAE,QAAQ,MAAM,OAAO,IAAI,CAAC;AAAA,MAC/C,GAAI,MAAM,UAAU,EAAE,SAAS,MAAM,QAAQ,IAAI,CAAC;AAAA,MAClD,GAAI,MAAM,cAAc,EAAE,aAAa,MAAM,YAAY,IAAI,CAAC;AAAA,MAC9D,GAAI,MAAM,UAAU,EAAE,SAAS,MAAM,QAAQ,IAAI,CAAC;AAAA,IACpD,CAAC;AAAA,EACH,CAAC;AACD,MAAI,CAAC,SAAS,GAAI,OAAM,IAAI,MAAM,sCAAsC,SAAS,MAAM,GAAG;AAC1F,SAAQ,MAAM,SAAS,KAAK;AAC9B;","names":[]}
+{"version":3,"sources":["../src/server.ts"],"sourcesContent":["import type { AssistantConfiguration } from './appearance.js';\n\ninterface AssistantSessionExchangeBase {\n  readonly serviceUrl: string;\n  readonly clientId: string;\n  readonly clientSecret: string;\n  /** Browser origin to bind into the short-lived assistant session. */\n  readonly origin: string;\n  /** The signed-in person your backend vouches for — on both arms: an elevation IS this vouching. */\n  readonly user: {\n    readonly id: string;\n    readonly email?: string;\n    readonly name?: string;\n    readonly tenant?: string;\n    readonly roles?: readonly string[];\n    readonly scopes?: readonly string[];\n  };\n  /** Backend-verified user preferences; these outrank untrusted browser presentation hints. */\n  readonly preferences?: {\n    readonly locale?: string;\n    readonly timeZone?: string;\n  };\n  /**\n   * Verified session claims from your authenticated backend. Only claims the server declares in\n   * `embeddedAssistant({ sessionClaims })` reach tools (`\\${user.claims.<key>}`) and, when marked\n   * `exposeToModel`, the assistant's identity context. Flat scalars only.\n   */\n  readonly claims?: Readonly<Record<string, string | number | boolean | null>>;\n}\n\n/**\n * Fresh mint XOR mid-conversation sign-in, exclusive rather than merged for the same reason the\n * client's `sessionEndpoint`/`embedId` pair is: the two are different operations, and the wrong\n * combination should fail to typecheck instead of silently picking a meaning.\n *\n * `context` applies only when a session is being created; an elevation keeps the existing\n * conversation, so it is excluded rather than silently ignored. `routing` is allowed on both arms —\n * elevation is the first authenticated moment, so it is the only chance a routed connector's\n * session ever gets its backend-verified customer routes.\n */\nexport type CreateAssistantSessionInput =\n  | (AssistantSessionExchangeBase & {\n      readonly signInTicket?: undefined;\n      readonly context?: Readonly<Record<string, string | number | boolean | null>>;\n      /** Backend-verified connector routes keyed by authored `customerEndpoint` name. */\n      readonly routing?: {\n        readonly endpoints: Readonly<Record<string, string>>;\n      };\n      /** Resume applies only when spending a sign-in ticket; a fresh mint has nothing pending. */\n      readonly resume?: undefined;\n    })\n  | (AssistantSessionExchangeBase & {\n      /**\n       * Single-use sign-in ticket from the widget's `assistant-sign-in-requested` event\n       * (ADR 0201, 5.6b). Spending it binds this signed-in user to the visitor's existing\n       * anonymous conversation instead of minting a new one. Unrelated to the server-held\n       * interaction continuation, which never reaches browser code.\n       */\n      readonly signInTicket: string;\n      readonly context?: undefined;\n      /** Backend-verified connector routes keyed by authored `customerEndpoint` name. */\n      readonly routing?: {\n        readonly endpoints: Readonly<Record<string, string>>;\n      };\n      /**\n       * Whether the service resumes the intercepted tool call as the elevated session's first\n       * turn (issue #1177). ON by default — omit it and the visitor's pending question answers\n       * itself after sign-in; pass `false` if your application provides its own affordance.\n       */\n      readonly resume?: boolean;\n    });\n\nexport interface AssistantSession {\n  readonly token: string;\n  readonly expiresAt: string;\n  readonly endpoints: {\n    readonly turns: string;\n    readonly toolConfirmations: string;\n    readonly interactions?: string;\n    readonly apps?: string;\n    /** Additive hosted sandbox document for widget frames; absent on older services. */\n    readonly sandbox?: string;\n  };\n  /**\n   * Present only on an elevation that armed the one-shot resume of the intercepted tool. Forward\n   * the response body unchanged and the widget answers with one automatic turn.\n   */\n  readonly resume?: { readonly tool: string };\n  readonly configuration?: AssistantConfiguration;\n}\n\n/** The service's refusal codes for a sign-in ticket the exchange would not honour. */\nexport const ASSISTANT_ELEVATION_REFUSAL_CODES = [\n  'elevation_ticket_invalid',\n  'elevation_ticket_expired',\n  'elevation_tenant_mismatch',\n  'elevation_session_unavailable',\n  'elevation_already_signed_in',\n] as const;\nexport type AssistantElevationRefusalCode = (typeof ASSISTANT_ELEVATION_REFUSAL_CODES)[number];\n\n/**\n * Structurally mirrors the browser client's `AssistantErrorDetail` (declared locally: the backend\n * entry must not pull the browser transport module into its graph). `code` is a closed union owned\n * by this package; `serviceCode` passes the service's machine code through additively.\n */\nexport interface AssistantSessionExchangeErrorDetail {\n  readonly code: 'session_exchange_failed';\n  readonly status: number;\n  /** 5xx infrastructure failures may be retried; a refused exchange must not be — tickets are single-use. */\n  readonly retryable: boolean;\n  /** The service's machine code when the body carried one, e.g. `elevation_ticket_expired`. */\n  readonly serviceCode?: string;\n}\n\nexport class AssistantSessionExchangeError extends Error {\n  readonly detail: AssistantSessionExchangeErrorDetail;\n\n  constructor(detail: AssistantSessionExchangeErrorDetail, message: string) {\n    super(message);\n    this.name = 'AssistantSessionExchangeError';\n    this.detail = detail;\n  }\n\n  /**\n   * The narrowed sign-in refusal, when this failure is one. `elevation_ticket_expired` means the\n   * visitor took too long — re-prompt; `elevation_tenant_mismatch` means a client reached for a\n   * conversation it does not own — alert someone, never retry.\n   */\n  get elevationRefusal(): AssistantElevationRefusalCode | undefined {\n    const code = this.detail.serviceCode;\n    return code !== undefined &&\n      (ASSISTANT_ELEVATION_REFUSAL_CODES as readonly string[]).includes(code)\n      ? (code as AssistantElevationRefusalCode)\n      : undefined;\n  }\n}\n\n/** Never throws while reading the body — a proxy can answer with HTML instead of JSON. */\nasync function exchangeError(response: Response): Promise<AssistantSessionExchangeError> {\n  const body = (await response.json().catch(() => undefined)) as\n    | { readonly error?: unknown; readonly code?: unknown }\n    | undefined;\n  const serviceCode = typeof body?.code === 'string' ? body.code : undefined;\n  return new AssistantSessionExchangeError(\n    {\n      code: 'session_exchange_failed',\n      status: response.status,\n      // `elevation_unavailable` is a 503 an operator has to fix; retrying cannot help.\n      retryable: response.status >= 500 && serviceCode !== 'elevation_unavailable',\n      ...(serviceCode === undefined ? {} : { serviceCode }),\n    },\n    `Assistant session exchange failed (${response.status})`,\n  );\n}\n\nexport async function createAssistantSession(\n  input: CreateAssistantSessionInput,\n  dependencies: { readonly fetch?: typeof fetch } = {},\n): Promise<AssistantSession> {\n  if (input.signInTicket !== undefined && (input as { context?: unknown }).context !== undefined) {\n    // Mirrors resolveSessionSource: silently dropping what the service ignores would pick a\n    // meaning the developer did not intend.\n    throw new Error('context does not apply when spending a sign-in ticket');\n  }\n  const request = dependencies.fetch ?? fetch;\n  const serviceUrl = input.serviceUrl.replace(/\\/$/, '');\n  const credentials = Buffer.from(`${input.clientId}:${input.clientSecret}`, 'utf8').toString(\n    'base64',\n  );\n  const response = await request(`${serviceUrl}/v1/assistant/sessions`, {\n    method: 'POST',\n    headers: {\n      Authorization: `Basic ${credentials}`,\n      Accept: 'application/json',\n      'Content-Type': 'application/json',\n    },\n    body: JSON.stringify({\n      origin: input.origin,\n      user: input.user,\n      ...(input.signInTicket === undefined ? {} : { signInTicket: input.signInTicket }),\n      ...(input.signInTicket !== undefined && input.resume !== undefined\n        ? { resume: input.resume }\n        : {}),\n      ...(input.claims ? { claims: input.claims } : {}),\n      ...(input.context ? { context: input.context } : {}),\n      ...(input.preferences ? { preferences: input.preferences } : {}),\n      ...(input.routing ? { routing: input.routing } : {}),\n    }),\n  });\n  // A fresh mint answers 201, an elevation 200; both are the same wire shape (ADR 0151).\n  if (!response.ok) throw await exchangeError(response);\n  return (await response.json()) as AssistantSession;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA4FO,IAAM,oCAAoC;AAAA,EAC/C;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAiBO,IAAM,gCAAN,cAA4C,MAAM;AAAA,EAC9C;AAAA,EAET,YAAY,QAA6C,SAAiB;AACxE,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,SAAS;AAAA,EAChB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,IAAI,mBAA8D;AAChE,UAAM,OAAO,KAAK,OAAO;AACzB,WAAO,SAAS,UACb,kCAAwD,SAAS,IAAI,IACnE,OACD;AAAA,EACN;AACF;AAGA,eAAe,cAAc,UAA4D;AACvF,QAAM,OAAQ,MAAM,SAAS,KAAK,EAAE,MAAM,MAAM,MAAS;AAGzD,QAAM,cAAc,OAAO,MAAM,SAAS,WAAW,KAAK,OAAO;AACjE,SAAO,IAAI;AAAA,IACT;AAAA,MACE,MAAM;AAAA,MACN,QAAQ,SAAS;AAAA;AAAA,MAEjB,WAAW,SAAS,UAAU,OAAO,gBAAgB;AAAA,MACrD,GAAI,gBAAgB,SAAY,CAAC,IAAI,EAAE,YAAY;AAAA,IACrD;AAAA,IACA,sCAAsC,SAAS,MAAM;AAAA,EACvD;AACF;AAEA,eAAsB,uBACpB,OACA,eAAkD,CAAC,GACxB;AAC3B,MAAI,MAAM,iBAAiB,UAAc,MAAgC,YAAY,QAAW;AAG9F,UAAM,IAAI,MAAM,uDAAuD;AAAA,EACzE;AACA,QAAM,UAAU,aAAa,SAAS;AACtC,QAAM,aAAa,MAAM,WAAW,QAAQ,OAAO,EAAE;AACrD,QAAM,cAAc,OAAO,KAAK,GAAG,MAAM,QAAQ,IAAI,MAAM,YAAY,IAAI,MAAM,EAAE;AAAA,IACjF;AAAA,EACF;AACA,QAAM,WAAW,MAAM,QAAQ,GAAG,UAAU,0BAA0B;AAAA,IACpE,QAAQ;AAAA,IACR,SAAS;AAAA,MACP,eAAe,SAAS,WAAW;AAAA,MACnC,QAAQ;AAAA,MACR,gBAAgB;AAAA,IAClB;AAAA,IACA,MAAM,KAAK,UAAU;AAAA,MACnB,QAAQ,MAAM;AAAA,MACd,MAAM,MAAM;AAAA,MACZ,GAAI,MAAM,iBAAiB,SAAY,CAAC,IAAI,EAAE,cAAc,MAAM,aAAa;AAAA,MAC/E,GAAI,MAAM,iBAAiB,UAAa,MAAM,WAAW,SACrD,EAAE,QAAQ,MAAM,OAAO,IACvB,CAAC;AAAA,MACL,GAAI,MAAM,SAAS,EAAE,QAAQ,MAAM,OAAO,IAAI,CAAC;AAAA,MAC/C,GAAI,MAAM,UAAU,EAAE,SAAS,MAAM,QAAQ,IAAI,CAAC;AAAA,MAClD,GAAI,MAAM,cAAc,EAAE,aAAa,MAAM,YAAY,IAAI,CAAC;AAAA,MAC9D,GAAI,MAAM,UAAU,EAAE,SAAS,MAAM,QAAQ,IAAI,CAAC;AAAA,IACpD,CAAC;AAAA,EACH,CAAC;AAED,MAAI,CAAC,SAAS,GAAI,OAAM,MAAM,cAAc,QAAQ;AACpD,SAAQ,MAAM,SAAS,KAAK;AAC9B;","names":[]}

package/dist/server.d.cts

@@ -1,11 +1,12 @@
 import { A as AssistantConfiguration } from './appearance-Cc-eqSbp.cjs';
 
-interface CreateAssistantSessionInput {
+interface AssistantSessionExchangeBase {
     readonly serviceUrl: string;
     readonly clientId: string;
     readonly clientSecret: string;
     /** Browser origin to bind into the short-lived assistant session. */
     readonly origin: string;
+    /** The signed-in person your backend vouches for — on both arms: an elevation IS this vouching. */
     readonly user: {
         readonly id: string;
         readonly email?: string;
@@ -14,16 +15,11 @@ interface CreateAssistantSessionInput {
         readonly roles?: readonly string[];
         readonly scopes?: readonly string[];
     };
-    readonly context?: Readonly<Record<string, string | number | boolean | null>>;
     /** Backend-verified user preferences; these outrank untrusted browser presentation hints. */
     readonly preferences?: {
         readonly locale?: string;
         readonly timeZone?: string;
     };
-    /** Backend-verified connector routes keyed by authored `customerEndpoint` name. */
-    readonly routing?: {
-        readonly endpoints: Readonly<Record<string, string>>;
-    };
     /**
      * Verified session claims from your authenticated backend. Only claims the server declares in
      * `embeddedAssistant({ sessionClaims })` reach tools (`\${user.claims.<key>}`) and, when marked
@@ -31,6 +27,45 @@ interface CreateAssistantSessionInput {
      */
     readonly claims?: Readonly<Record<string, string | number | boolean | null>>;
 }
+/**
+ * Fresh mint XOR mid-conversation sign-in, exclusive rather than merged for the same reason the
+ * client's `sessionEndpoint`/`embedId` pair is: the two are different operations, and the wrong
+ * combination should fail to typecheck instead of silently picking a meaning.
+ *
+ * `context` applies only when a session is being created; an elevation keeps the existing
+ * conversation, so it is excluded rather than silently ignored. `routing` is allowed on both arms —
+ * elevation is the first authenticated moment, so it is the only chance a routed connector's
+ * session ever gets its backend-verified customer routes.
+ */
+type CreateAssistantSessionInput = (AssistantSessionExchangeBase & {
+    readonly signInTicket?: undefined;
+    readonly context?: Readonly<Record<string, string | number | boolean | null>>;
+    /** Backend-verified connector routes keyed by authored `customerEndpoint` name. */
+    readonly routing?: {
+        readonly endpoints: Readonly<Record<string, string>>;
+    };
+    /** Resume applies only when spending a sign-in ticket; a fresh mint has nothing pending. */
+    readonly resume?: undefined;
+}) | (AssistantSessionExchangeBase & {
+    /**
+     * Single-use sign-in ticket from the widget's `assistant-sign-in-requested` event
+     * (ADR 0201, 5.6b). Spending it binds this signed-in user to the visitor's existing
+     * anonymous conversation instead of minting a new one. Unrelated to the server-held
+     * interaction continuation, which never reaches browser code.
+     */
+    readonly signInTicket: string;
+    readonly context?: undefined;
+    /** Backend-verified connector routes keyed by authored `customerEndpoint` name. */
+    readonly routing?: {
+        readonly endpoints: Readonly<Record<string, string>>;
+    };
+    /**
+     * Whether the service resumes the intercepted tool call as the elevated session's first
+     * turn (issue #1177). ON by default — omit it and the visitor's pending question answers
+     * itself after sign-in; pass `false` if your application provides its own affordance.
+     */
+    readonly resume?: boolean;
+});
 interface AssistantSession {
     readonly token: string;
     readonly expiresAt: string;
@@ -42,10 +77,43 @@ interface AssistantSession {
         /** Additive hosted sandbox document for widget frames; absent on older services. */
         readonly sandbox?: string;
     };
+    /**
+     * Present only on an elevation that armed the one-shot resume of the intercepted tool. Forward
+     * the response body unchanged and the widget answers with one automatic turn.
+     */
+    readonly resume?: {
+        readonly tool: string;
+    };
     readonly configuration?: AssistantConfiguration;
 }
+/** The service's refusal codes for a sign-in ticket the exchange would not honour. */
+declare const ASSISTANT_ELEVATION_REFUSAL_CODES: readonly ["elevation_ticket_invalid", "elevation_ticket_expired", "elevation_tenant_mismatch", "elevation_session_unavailable", "elevation_already_signed_in"];
+type AssistantElevationRefusalCode = (typeof ASSISTANT_ELEVATION_REFUSAL_CODES)[number];
+/**
+ * Structurally mirrors the browser client's `AssistantErrorDetail` (declared locally: the backend
+ * entry must not pull the browser transport module into its graph). `code` is a closed union owned
+ * by this package; `serviceCode` passes the service's machine code through additively.
+ */
+interface AssistantSessionExchangeErrorDetail {
+    readonly code: 'session_exchange_failed';
+    readonly status: number;
+    /** 5xx infrastructure failures may be retried; a refused exchange must not be — tickets are single-use. */
+    readonly retryable: boolean;
+    /** The service's machine code when the body carried one, e.g. `elevation_ticket_expired`. */
+    readonly serviceCode?: string;
+}
+declare class AssistantSessionExchangeError extends Error {
+    readonly detail: AssistantSessionExchangeErrorDetail;
+    constructor(detail: AssistantSessionExchangeErrorDetail, message: string);
+    /**
+     * The narrowed sign-in refusal, when this failure is one. `elevation_ticket_expired` means the
+     * visitor took too long — re-prompt; `elevation_tenant_mismatch` means a client reached for a
+     * conversation it does not own — alert someone, never retry.
+     */
+    get elevationRefusal(): AssistantElevationRefusalCode | undefined;
+}
 declare function createAssistantSession(input: CreateAssistantSessionInput, dependencies?: {
     readonly fetch?: typeof fetch;
 }): Promise<AssistantSession>;
 
-export { type AssistantSession, type CreateAssistantSessionInput, createAssistantSession };
+export { ASSISTANT_ELEVATION_REFUSAL_CODES, type AssistantElevationRefusalCode, type AssistantSession, AssistantSessionExchangeError, type AssistantSessionExchangeErrorDetail, type CreateAssistantSessionInput, createAssistantSession };

package/dist/server.d.ts

@@ -1,11 +1,12 @@
 import { A as AssistantConfiguration } from './appearance-Cc-eqSbp.js';
 
-interface CreateAssistantSessionInput {
+interface AssistantSessionExchangeBase {
     readonly serviceUrl: string;
     readonly clientId: string;
     readonly clientSecret: string;
     /** Browser origin to bind into the short-lived assistant session. */
     readonly origin: string;
+    /** The signed-in person your backend vouches for — on both arms: an elevation IS this vouching. */
     readonly user: {
         readonly id: string;
         readonly email?: string;
@@ -14,16 +15,11 @@ interface CreateAssistantSessionInput {
         readonly roles?: readonly string[];
         readonly scopes?: readonly string[];
     };
-    readonly context?: Readonly<Record<string, string | number | boolean | null>>;
     /** Backend-verified user preferences; these outrank untrusted browser presentation hints. */
     readonly preferences?: {
         readonly locale?: string;
         readonly timeZone?: string;
     };
-    /** Backend-verified connector routes keyed by authored `customerEndpoint` name. */
-    readonly routing?: {
-        readonly endpoints: Readonly<Record<string, string>>;
-    };
     /**
      * Verified session claims from your authenticated backend. Only claims the server declares in
      * `embeddedAssistant({ sessionClaims })` reach tools (`\${user.claims.<key>}`) and, when marked
@@ -31,6 +27,45 @@ interface CreateAssistantSessionInput {
      */
     readonly claims?: Readonly<Record<string, string | number | boolean | null>>;
 }
+/**
+ * Fresh mint XOR mid-conversation sign-in, exclusive rather than merged for the same reason the
+ * client's `sessionEndpoint`/`embedId` pair is: the two are different operations, and the wrong
+ * combination should fail to typecheck instead of silently picking a meaning.
+ *
+ * `context` applies only when a session is being created; an elevation keeps the existing
+ * conversation, so it is excluded rather than silently ignored. `routing` is allowed on both arms —
+ * elevation is the first authenticated moment, so it is the only chance a routed connector's
+ * session ever gets its backend-verified customer routes.
+ */
+type CreateAssistantSessionInput = (AssistantSessionExchangeBase & {
+    readonly signInTicket?: undefined;
+    readonly context?: Readonly<Record<string, string | number | boolean | null>>;
+    /** Backend-verified connector routes keyed by authored `customerEndpoint` name. */
+    readonly routing?: {
+        readonly endpoints: Readonly<Record<string, string>>;
+    };
+    /** Resume applies only when spending a sign-in ticket; a fresh mint has nothing pending. */
+    readonly resume?: undefined;
+}) | (AssistantSessionExchangeBase & {
+    /**
+     * Single-use sign-in ticket from the widget's `assistant-sign-in-requested` event
+     * (ADR 0201, 5.6b). Spending it binds this signed-in user to the visitor's existing
+     * anonymous conversation instead of minting a new one. Unrelated to the server-held
+     * interaction continuation, which never reaches browser code.
+     */
+    readonly signInTicket: string;
+    readonly context?: undefined;
+    /** Backend-verified connector routes keyed by authored `customerEndpoint` name. */
+    readonly routing?: {
+        readonly endpoints: Readonly<Record<string, string>>;
+    };
+    /**
+     * Whether the service resumes the intercepted tool call as the elevated session's first
+     * turn (issue #1177). ON by default — omit it and the visitor's pending question answers
+     * itself after sign-in; pass `false` if your application provides its own affordance.
+     */
+    readonly resume?: boolean;
+});
 interface AssistantSession {
     readonly token: string;
     readonly expiresAt: string;
@@ -42,10 +77,43 @@ interface AssistantSession {
         /** Additive hosted sandbox document for widget frames; absent on older services. */
         readonly sandbox?: string;
     };
+    /**
+     * Present only on an elevation that armed the one-shot resume of the intercepted tool. Forward
+     * the response body unchanged and the widget answers with one automatic turn.
+     */
+    readonly resume?: {
+        readonly tool: string;
+    };
     readonly configuration?: AssistantConfiguration;
 }
+/** The service's refusal codes for a sign-in ticket the exchange would not honour. */
+declare const ASSISTANT_ELEVATION_REFUSAL_CODES: readonly ["elevation_ticket_invalid", "elevation_ticket_expired", "elevation_tenant_mismatch", "elevation_session_unavailable", "elevation_already_signed_in"];
+type AssistantElevationRefusalCode = (typeof ASSISTANT_ELEVATION_REFUSAL_CODES)[number];
+/**
+ * Structurally mirrors the browser client's `AssistantErrorDetail` (declared locally: the backend
+ * entry must not pull the browser transport module into its graph). `code` is a closed union owned
+ * by this package; `serviceCode` passes the service's machine code through additively.
+ */
+interface AssistantSessionExchangeErrorDetail {
+    readonly code: 'session_exchange_failed';
+    readonly status: number;
+    /** 5xx infrastructure failures may be retried; a refused exchange must not be — tickets are single-use. */
+    readonly retryable: boolean;
+    /** The service's machine code when the body carried one, e.g. `elevation_ticket_expired`. */
+    readonly serviceCode?: string;
+}
+declare class AssistantSessionExchangeError extends Error {
+    readonly detail: AssistantSessionExchangeErrorDetail;
+    constructor(detail: AssistantSessionExchangeErrorDetail, message: string);
+    /**
+     * The narrowed sign-in refusal, when this failure is one. `elevation_ticket_expired` means the
+     * visitor took too long — re-prompt; `elevation_tenant_mismatch` means a client reached for a
+     * conversation it does not own — alert someone, never retry.
+     */
+    get elevationRefusal(): AssistantElevationRefusalCode | undefined;
+}
 declare function createAssistantSession(input: CreateAssistantSessionInput, dependencies?: {
     readonly fetch?: typeof fetch;
 }): Promise<AssistantSession>;
 
-export { type AssistantSession, type CreateAssistantSessionInput, createAssistantSession };
+export { ASSISTANT_ELEVATION_REFUSAL_CODES, type AssistantElevationRefusalCode, type AssistantSession, AssistantSessionExchangeError, type AssistantSessionExchangeErrorDetail, type CreateAssistantSessionInput, createAssistantSession };

package/dist/server.js

@@ -1,7 +1,48 @@
 import "./chunk-5FUTL2UF.js";
 
 // src/server.ts
+var ASSISTANT_ELEVATION_REFUSAL_CODES = [
+  "elevation_ticket_invalid",
+  "elevation_ticket_expired",
+  "elevation_tenant_mismatch",
+  "elevation_session_unavailable",
+  "elevation_already_signed_in"
+];
+var AssistantSessionExchangeError = class extends Error {
+  detail;
+  constructor(detail, message) {
+    super(message);
+    this.name = "AssistantSessionExchangeError";
+    this.detail = detail;
+  }
+  /**
+   * The narrowed sign-in refusal, when this failure is one. `elevation_ticket_expired` means the
+   * visitor took too long — re-prompt; `elevation_tenant_mismatch` means a client reached for a
+   * conversation it does not own — alert someone, never retry.
+   */
+  get elevationRefusal() {
+    const code = this.detail.serviceCode;
+    return code !== void 0 && ASSISTANT_ELEVATION_REFUSAL_CODES.includes(code) ? code : void 0;
+  }
+};
+async function exchangeError(response) {
+  const body = await response.json().catch(() => void 0);
+  const serviceCode = typeof body?.code === "string" ? body.code : void 0;
+  return new AssistantSessionExchangeError(
+    {
+      code: "session_exchange_failed",
+      status: response.status,
+      // `elevation_unavailable` is a 503 an operator has to fix; retrying cannot help.
+      retryable: response.status >= 500 && serviceCode !== "elevation_unavailable",
+      ...serviceCode === void 0 ? {} : { serviceCode }
+    },
+    `Assistant session exchange failed (${response.status})`
+  );
+}
 async function createAssistantSession(input, dependencies = {}) {
+  if (input.signInTicket !== void 0 && input.context !== void 0) {
+    throw new Error("context does not apply when spending a sign-in ticket");
+  }
   const request = dependencies.fetch ?? fetch;
   const serviceUrl = input.serviceUrl.replace(/\/$/, "");
   const credentials = Buffer.from(`${input.clientId}:${input.clientSecret}`, "utf8").toString(
@@ -17,16 +58,20 @@ async function createAssistantSession(input, dependencies = {}) {
     body: JSON.stringify({
       origin: input.origin,
       user: input.user,
+      ...input.signInTicket === void 0 ? {} : { signInTicket: input.signInTicket },
+      ...input.signInTicket !== void 0 && input.resume !== void 0 ? { resume: input.resume } : {},
       ...input.claims ? { claims: input.claims } : {},
       ...input.context ? { context: input.context } : {},
       ...input.preferences ? { preferences: input.preferences } : {},
       ...input.routing ? { routing: input.routing } : {}
     })
   });
-  if (!response.ok) throw new Error(`Assistant session exchange failed (${response.status})`);
+  if (!response.ok) throw await exchangeError(response);
   return await response.json();
 }
 export {
+  ASSISTANT_ELEVATION_REFUSAL_CODES,
+  AssistantSessionExchangeError,
   createAssistantSession
 };
 //# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/server.ts"],"sourcesContent":["import type { AssistantConfiguration } from './appearance.js';\n\nexport interface CreateAssistantSessionInput {\n  readonly serviceUrl: string;\n  readonly clientId: string;\n  readonly clientSecret: string;\n  /** Browser origin to bind into the short-lived assistant session. */\n  readonly origin: string;\n  readonly user: {\n    readonly id: string;\n    readonly email?: string;\n    readonly name?: string;\n    readonly tenant?: string;\n    readonly roles?: readonly string[];\n    readonly scopes?: readonly string[];\n  };\n  readonly context?: Readonly<Record<string, string | number | boolean | null>>;\n  /** Backend-verified user preferences; these outrank untrusted browser presentation hints. */\n  readonly preferences?: {\n    readonly locale?: string;\n    readonly timeZone?: string;\n  };\n  /** Backend-verified connector routes keyed by authored `customerEndpoint` name. */\n  readonly routing?: {\n    readonly endpoints: Readonly<Record<string, string>>;\n  };\n  /**\n   * Verified session claims from your authenticated backend. Only claims the server declares in\n   * `embeddedAssistant({ sessionClaims })` reach tools (`\\${user.claims.<key>}`) and, when marked\n   * `exposeToModel`, the assistant's identity context. Flat scalars only.\n   */\n  readonly claims?: Readonly<Record<string, string | number | boolean | null>>;\n}\n\nexport interface AssistantSession {\n  readonly token: string;\n  readonly expiresAt: string;\n  readonly endpoints: {\n    readonly turns: string;\n    readonly toolConfirmations: string;\n    readonly interactions?: string;\n    readonly apps?: string;\n    /** Additive hosted sandbox document for widget frames; absent on older services. */\n    readonly sandbox?: string;\n  };\n  readonly configuration?: AssistantConfiguration;\n}\n\nexport async function createAssistantSession(\n  input: CreateAssistantSessionInput,\n  dependencies: { readonly fetch?: typeof fetch } = {},\n): Promise<AssistantSession> {\n  const request = dependencies.fetch ?? fetch;\n  const serviceUrl = input.serviceUrl.replace(/\\/$/, '');\n  const credentials = Buffer.from(`${input.clientId}:${input.clientSecret}`, 'utf8').toString(\n    'base64',\n  );\n  const response = await request(`${serviceUrl}/v1/assistant/sessions`, {\n    method: 'POST',\n    headers: {\n      Authorization: `Basic ${credentials}`,\n      Accept: 'application/json',\n      'Content-Type': 'application/json',\n    },\n    body: JSON.stringify({\n      origin: input.origin,\n      user: input.user,\n      ...(input.claims ? { claims: input.claims } : {}),\n      ...(input.context ? { context: input.context } : {}),\n      ...(input.preferences ? { preferences: input.preferences } : {}),\n      ...(input.routing ? { routing: input.routing } : {}),\n    }),\n  });\n  if (!response.ok) throw new Error(`Assistant session exchange failed (${response.status})`);\n  return (await response.json()) as AssistantSession;\n}\n"],"mappings":";;;AAgDA,eAAsB,uBACpB,OACA,eAAkD,CAAC,GACxB;AAC3B,QAAM,UAAU,aAAa,SAAS;AACtC,QAAM,aAAa,MAAM,WAAW,QAAQ,OAAO,EAAE;AACrD,QAAM,cAAc,OAAO,KAAK,GAAG,MAAM,QAAQ,IAAI,MAAM,YAAY,IAAI,MAAM,EAAE;AAAA,IACjF;AAAA,EACF;AACA,QAAM,WAAW,MAAM,QAAQ,GAAG,UAAU,0BAA0B;AAAA,IACpE,QAAQ;AAAA,IACR,SAAS;AAAA,MACP,eAAe,SAAS,WAAW;AAAA,MACnC,QAAQ;AAAA,MACR,gBAAgB;AAAA,IAClB;AAAA,IACA,MAAM,KAAK,UAAU;AAAA,MACnB,QAAQ,MAAM;AAAA,MACd,MAAM,MAAM;AAAA,MACZ,GAAI,MAAM,SAAS,EAAE,QAAQ,MAAM,OAAO,IAAI,CAAC;AAAA,MAC/C,GAAI,MAAM,UAAU,EAAE,SAAS,MAAM,QAAQ,IAAI,CAAC;AAAA,MAClD,GAAI,MAAM,cAAc,EAAE,aAAa,MAAM,YAAY,IAAI,CAAC;AAAA,MAC9D,GAAI,MAAM,UAAU,EAAE,SAAS,MAAM,QAAQ,IAAI,CAAC;AAAA,IACpD,CAAC;AAAA,EACH,CAAC;AACD,MAAI,CAAC,SAAS,GAAI,OAAM,IAAI,MAAM,sCAAsC,SAAS,MAAM,GAAG;AAC1F,SAAQ,MAAM,SAAS,KAAK;AAC9B;","names":[]}
+{"version":3,"sources":["../src/server.ts"],"sourcesContent":["import type { AssistantConfiguration } from './appearance.js';\n\ninterface AssistantSessionExchangeBase {\n  readonly serviceUrl: string;\n  readonly clientId: string;\n  readonly clientSecret: string;\n  /** Browser origin to bind into the short-lived assistant session. */\n  readonly origin: string;\n  /** The signed-in person your backend vouches for — on both arms: an elevation IS this vouching. */\n  readonly user: {\n    readonly id: string;\n    readonly email?: string;\n    readonly name?: string;\n    readonly tenant?: string;\n    readonly roles?: readonly string[];\n    readonly scopes?: readonly string[];\n  };\n  /** Backend-verified user preferences; these outrank untrusted browser presentation hints. */\n  readonly preferences?: {\n    readonly locale?: string;\n    readonly timeZone?: string;\n  };\n  /**\n   * Verified session claims from your authenticated backend. Only claims the server declares in\n   * `embeddedAssistant({ sessionClaims })` reach tools (`\\${user.claims.<key>}`) and, when marked\n   * `exposeToModel`, the assistant's identity context. Flat scalars only.\n   */\n  readonly claims?: Readonly<Record<string, string | number | boolean | null>>;\n}\n\n/**\n * Fresh mint XOR mid-conversation sign-in, exclusive rather than merged for the same reason the\n * client's `sessionEndpoint`/`embedId` pair is: the two are different operations, and the wrong\n * combination should fail to typecheck instead of silently picking a meaning.\n *\n * `context` applies only when a session is being created; an elevation keeps the existing\n * conversation, so it is excluded rather than silently ignored. `routing` is allowed on both arms —\n * elevation is the first authenticated moment, so it is the only chance a routed connector's\n * session ever gets its backend-verified customer routes.\n */\nexport type CreateAssistantSessionInput =\n  | (AssistantSessionExchangeBase & {\n      readonly signInTicket?: undefined;\n      readonly context?: Readonly<Record<string, string | number | boolean | null>>;\n      /** Backend-verified connector routes keyed by authored `customerEndpoint` name. */\n      readonly routing?: {\n        readonly endpoints: Readonly<Record<string, string>>;\n      };\n      /** Resume applies only when spending a sign-in ticket; a fresh mint has nothing pending. */\n      readonly resume?: undefined;\n    })\n  | (AssistantSessionExchangeBase & {\n      /**\n       * Single-use sign-in ticket from the widget's `assistant-sign-in-requested` event\n       * (ADR 0201, 5.6b). Spending it binds this signed-in user to the visitor's existing\n       * anonymous conversation instead of minting a new one. Unrelated to the server-held\n       * interaction continuation, which never reaches browser code.\n       */\n      readonly signInTicket: string;\n      readonly context?: undefined;\n      /** Backend-verified connector routes keyed by authored `customerEndpoint` name. */\n      readonly routing?: {\n        readonly endpoints: Readonly<Record<string, string>>;\n      };\n      /**\n       * Whether the service resumes the intercepted tool call as the elevated session's first\n       * turn (issue #1177). ON by default — omit it and the visitor's pending question answers\n       * itself after sign-in; pass `false` if your application provides its own affordance.\n       */\n      readonly resume?: boolean;\n    });\n\nexport interface AssistantSession {\n  readonly token: string;\n  readonly expiresAt: string;\n  readonly endpoints: {\n    readonly turns: string;\n    readonly toolConfirmations: string;\n    readonly interactions?: string;\n    readonly apps?: string;\n    /** Additive hosted sandbox document for widget frames; absent on older services. */\n    readonly sandbox?: string;\n  };\n  /**\n   * Present only on an elevation that armed the one-shot resume of the intercepted tool. Forward\n   * the response body unchanged and the widget answers with one automatic turn.\n   */\n  readonly resume?: { readonly tool: string };\n  readonly configuration?: AssistantConfiguration;\n}\n\n/** The service's refusal codes for a sign-in ticket the exchange would not honour. */\nexport const ASSISTANT_ELEVATION_REFUSAL_CODES = [\n  'elevation_ticket_invalid',\n  'elevation_ticket_expired',\n  'elevation_tenant_mismatch',\n  'elevation_session_unavailable',\n  'elevation_already_signed_in',\n] as const;\nexport type AssistantElevationRefusalCode = (typeof ASSISTANT_ELEVATION_REFUSAL_CODES)[number];\n\n/**\n * Structurally mirrors the browser client's `AssistantErrorDetail` (declared locally: the backend\n * entry must not pull the browser transport module into its graph). `code` is a closed union owned\n * by this package; `serviceCode` passes the service's machine code through additively.\n */\nexport interface AssistantSessionExchangeErrorDetail {\n  readonly code: 'session_exchange_failed';\n  readonly status: number;\n  /** 5xx infrastructure failures may be retried; a refused exchange must not be — tickets are single-use. */\n  readonly retryable: boolean;\n  /** The service's machine code when the body carried one, e.g. `elevation_ticket_expired`. */\n  readonly serviceCode?: string;\n}\n\nexport class AssistantSessionExchangeError extends Error {\n  readonly detail: AssistantSessionExchangeErrorDetail;\n\n  constructor(detail: AssistantSessionExchangeErrorDetail, message: string) {\n    super(message);\n    this.name = 'AssistantSessionExchangeError';\n    this.detail = detail;\n  }\n\n  /**\n   * The narrowed sign-in refusal, when this failure is one. `elevation_ticket_expired` means the\n   * visitor took too long — re-prompt; `elevation_tenant_mismatch` means a client reached for a\n   * conversation it does not own — alert someone, never retry.\n   */\n  get elevationRefusal(): AssistantElevationRefusalCode | undefined {\n    const code = this.detail.serviceCode;\n    return code !== undefined &&\n      (ASSISTANT_ELEVATION_REFUSAL_CODES as readonly string[]).includes(code)\n      ? (code as AssistantElevationRefusalCode)\n      : undefined;\n  }\n}\n\n/** Never throws while reading the body — a proxy can answer with HTML instead of JSON. */\nasync function exchangeError(response: Response): Promise<AssistantSessionExchangeError> {\n  const body = (await response.json().catch(() => undefined)) as\n    | { readonly error?: unknown; readonly code?: unknown }\n    | undefined;\n  const serviceCode = typeof body?.code === 'string' ? body.code : undefined;\n  return new AssistantSessionExchangeError(\n    {\n      code: 'session_exchange_failed',\n      status: response.status,\n      // `elevation_unavailable` is a 503 an operator has to fix; retrying cannot help.\n      retryable: response.status >= 500 && serviceCode !== 'elevation_unavailable',\n      ...(serviceCode === undefined ? {} : { serviceCode }),\n    },\n    `Assistant session exchange failed (${response.status})`,\n  );\n}\n\nexport async function createAssistantSession(\n  input: CreateAssistantSessionInput,\n  dependencies: { readonly fetch?: typeof fetch } = {},\n): Promise<AssistantSession> {\n  if (input.signInTicket !== undefined && (input as { context?: unknown }).context !== undefined) {\n    // Mirrors resolveSessionSource: silently dropping what the service ignores would pick a\n    // meaning the developer did not intend.\n    throw new Error('context does not apply when spending a sign-in ticket');\n  }\n  const request = dependencies.fetch ?? fetch;\n  const serviceUrl = input.serviceUrl.replace(/\\/$/, '');\n  const credentials = Buffer.from(`${input.clientId}:${input.clientSecret}`, 'utf8').toString(\n    'base64',\n  );\n  const response = await request(`${serviceUrl}/v1/assistant/sessions`, {\n    method: 'POST',\n    headers: {\n      Authorization: `Basic ${credentials}`,\n      Accept: 'application/json',\n      'Content-Type': 'application/json',\n    },\n    body: JSON.stringify({\n      origin: input.origin,\n      user: input.user,\n      ...(input.signInTicket === undefined ? {} : { signInTicket: input.signInTicket }),\n      ...(input.signInTicket !== undefined && input.resume !== undefined\n        ? { resume: input.resume }\n        : {}),\n      ...(input.claims ? { claims: input.claims } : {}),\n      ...(input.context ? { context: input.context } : {}),\n      ...(input.preferences ? { preferences: input.preferences } : {}),\n      ...(input.routing ? { routing: input.routing } : {}),\n    }),\n  });\n  // A fresh mint answers 201, an elevation 200; both are the same wire shape (ADR 0151).\n  if (!response.ok) throw await exchangeError(response);\n  return (await response.json()) as AssistantSession;\n}\n"],"mappings":";;;AA4FO,IAAM,oCAAoC;AAAA,EAC/C;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAiBO,IAAM,gCAAN,cAA4C,MAAM;AAAA,EAC9C;AAAA,EAET,YAAY,QAA6C,SAAiB;AACxE,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,SAAS;AAAA,EAChB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,IAAI,mBAA8D;AAChE,UAAM,OAAO,KAAK,OAAO;AACzB,WAAO,SAAS,UACb,kCAAwD,SAAS,IAAI,IACnE,OACD;AAAA,EACN;AACF;AAGA,eAAe,cAAc,UAA4D;AACvF,QAAM,OAAQ,MAAM,SAAS,KAAK,EAAE,MAAM,MAAM,MAAS;AAGzD,QAAM,cAAc,OAAO,MAAM,SAAS,WAAW,KAAK,OAAO;AACjE,SAAO,IAAI;AAAA,IACT;AAAA,MACE,MAAM;AAAA,MACN,QAAQ,SAAS;AAAA;AAAA,MAEjB,WAAW,SAAS,UAAU,OAAO,gBAAgB;AAAA,MACrD,GAAI,gBAAgB,SAAY,CAAC,IAAI,EAAE,YAAY;AAAA,IACrD;AAAA,IACA,sCAAsC,SAAS,MAAM;AAAA,EACvD;AACF;AAEA,eAAsB,uBACpB,OACA,eAAkD,CAAC,GACxB;AAC3B,MAAI,MAAM,iBAAiB,UAAc,MAAgC,YAAY,QAAW;AAG9F,UAAM,IAAI,MAAM,uDAAuD;AAAA,EACzE;AACA,QAAM,UAAU,aAAa,SAAS;AACtC,QAAM,aAAa,MAAM,WAAW,QAAQ,OAAO,EAAE;AACrD,QAAM,cAAc,OAAO,KAAK,GAAG,MAAM,QAAQ,IAAI,MAAM,YAAY,IAAI,MAAM,EAAE;AAAA,IACjF;AAAA,EACF;AACA,QAAM,WAAW,MAAM,QAAQ,GAAG,UAAU,0BAA0B;AAAA,IACpE,QAAQ;AAAA,IACR,SAAS;AAAA,MACP,eAAe,SAAS,WAAW;AAAA,MACnC,QAAQ;AAAA,MACR,gBAAgB;AAAA,IAClB;AAAA,IACA,MAAM,KAAK,UAAU;AAAA,MACnB,QAAQ,MAAM;AAAA,MACd,MAAM,MAAM;AAAA,MACZ,GAAI,MAAM,iBAAiB,SAAY,CAAC,IAAI,EAAE,cAAc,MAAM,aAAa;AAAA,MAC/E,GAAI,MAAM,iBAAiB,UAAa,MAAM,WAAW,SACrD,EAAE,QAAQ,MAAM,OAAO,IACvB,CAAC;AAAA,MACL,GAAI,MAAM,SAAS,EAAE,QAAQ,MAAM,OAAO,IAAI,CAAC;AAAA,MAC/C,GAAI,MAAM,UAAU,EAAE,SAAS,MAAM,QAAQ,IAAI,CAAC;AAAA,MAClD,GAAI,MAAM,cAAc,EAAE,aAAa,MAAM,YAAY,IAAI,CAAC;AAAA,MAC9D,GAAI,MAAM,UAAU,EAAE,SAAS,MAAM,QAAQ,IAAI,CAAC;AAAA,IACpD,CAAC;AAAA,EACH,CAAC;AAED,MAAI,CAAC,SAAS,GAAI,OAAM,MAAM,cAAc,QAAQ;AACpD,SAAQ,MAAM,SAAS,KAAK;AAC9B;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noodleseed/assistant",
-  "version": "1.19.0",
+  "version": "1.21.0",
   "description": "Embed the Noodle Seed customer-branded assistant in your web app with a Web Component, managed or custom React UI, DOM-free client, and backend session helper. Authoring and deploying the server is @noodleseed/one.",
   "license": "Apache-2.0",
   "repository": {