@touchcastllc/napster-companion-api-dev 1.0.0-alpha.73 → 1.0.0-alpha.75

package/lib/services/edge-mcp/edge-mcp-bridge.d.ts

@@ -20,17 +20,30 @@ export interface EdgeMcpBridgeOptions {
      * false to manage the agent's function list yourself. Default: `true`.
      */
     registerInlineFunctions?: boolean;
+    /**
+     * Read tools from a same-origin child iframe's `document.modelContext` instead of
+     * this window's. Used by the persistent-agent shell: the avatar + bridge live in the
+     * top-level document while the SITE (and its tools) live in the wrapped iframe. The
+     * bridge re-discovers on each iframe `load` (navigation) and routes tool calls into
+     * it (`executeTool` runs in the iframe's realm, so the site operates itself).
+     */
+    iframe?: HTMLIFrameElement;
 }
 export declare class EdgeMcpBridge {
     private mc;
     private tools;
     private onToolChange;
     private onResourceUpdated;
+    private onResourceListChanged;
+    private onIframeLoad;
+    private readonly seededUris;
     private lastInlineSig;
     private sessionReady;
     private disposed;
     private readonly options;
     constructor(options: EdgeMcpBridgeOptions);
+    /** The document whose `modelContext` we read — the target iframe's, or this window's. */
+    private targetDoc;
     /**
      * Discover `document.modelContext` in the page, cache its tools, and wire up
      * the `toolchange` / `resourceupdated` listeners. Returns the model context,
@@ -38,8 +51,34 @@ export declare class EdgeMcpBridge {
      * failure is silent and non-fatal.
      */
     attach(): Promise<EdgeMcpModelContext | null>;
+    /** Remove listeners from the current model context and drop the ref (no state reset). */
+    private unbind;
+    /**
+     * Re-discover and re-bind after the target iframe navigated to a NEW document (its old
+     * `document.modelContext` is dead). Keeps `sessionReady` (the avatar session in the parent
+     * survives), but resets the per-document dedupe so tools + resources re-register for the
+     * new page.
+     */
+    private reattach;
     /** Attach to a known model context: cache tools and subscribe to events. */
     private bind;
+    /**
+     * Relay the current value of every registered resource to the agent once, as
+     * an initial state seed — batched into a SINGLE `send_message` rather than one
+     * per resource, so the agent gets the whole starting state in one context
+     * injection. Feature-detects the toolkit's resource extension (`getResources` /
+     * `readResource`) — a bare WebMCP surface has neither, so this is a no-op there.
+     * Already-seeded URIs are skipped so a `resourcelistchanged` re-seed only emits
+     * genuinely new resources. (Ongoing changes still relay per-resource via
+     * `relayResourceUpdate`, since they happen one at a time.)
+     */
+    private seedResources;
+    /**
+     * Send the whole initial state set to the agent as ONE `role: 'system'`
+     * message (one line per resource). `trigger_response: false` so the avatar
+     * doesn't speak on the seed; `delay: true` to wait for any current speech.
+     */
+    private relayInitialState;
     /** Re-read the tool catalog from the model context. */
     private refreshTools;
     /** Map the current WebMCP tools to `set_settings.inline_functions` definitions. */

package/lib/services/edge-mcp/edge-mcp-discovery.d.ts

@@ -1,14 +1,21 @@
 import type { EdgeMcpModelContext } from "./edge-mcp-types";
-/** Read `document.modelContext`, falling back to the deprecated navigator alias. */
-export declare function getModelContext(): EdgeMcpModelContext | null;
+/**
+ * Read `modelContext` from a document, falling back to the deprecated navigator alias.
+ *
+ * `doc` defaults to the ambient `document`. Pass a same-origin child frame's
+ * `contentDocument` to read ITS surface instead (the shell targets the wrapped
+ * iframe this way). Cross-origin access throws — caught and returned as `null`.
+ */
+export declare function getModelContext(doc?: Document | null): EdgeMcpModelContext | null;
 /**
  * Discover `document.modelContext`, polling briefly if it is not present yet.
  *
  * Resolves with the model context if found, or `null` after `timeoutMs` if no
  * WebMCP surface shows up. Never rejects.
  *
- * @param timeoutMs How long to wait for a late-installing polyfill. Default
- *                  1500ms — long enough to cover normal hydration ordering,
- *                  short enough not to delay the SDK noticeably.
+ * @param timeoutMs How long to wait for a late-installing polyfill. Default 1500ms.
+ * @param getDoc    Optional getter for the document to read (re-evaluated each poll,
+ *                  since a targeted iframe's `contentDocument` changes as it navigates).
+ *                  Omit to use the ambient `document`.
  */
-export declare function discoverModelContext(timeoutMs?: number): Promise<EdgeMcpModelContext | null>;
+export declare function discoverModelContext(timeoutMs?: number, getDoc?: () => Document | null): Promise<EdgeMcpModelContext | null>;

package/lib/services/edge-mcp/edge-mcp-types.d.ts

@@ -12,6 +12,29 @@ export interface EdgeMcpToolInfo {
     inputSchema?: Record<string, unknown> | string;
     /** Optional human-readable label. */
     title?: string;
+    /**
+     * Standard WebMCP/MCP annotation hints, surfaced by the polyfill's
+     * `getTools()`. The bridge reads these to gate agent behavior — most
+     * importantly, `destructiveHint` ⇒ the agent must confirm with the user before
+     * calling. A bare WebMCP surface (or older polyfill) may omit this entirely, so
+     * every field is optional and the bridge treats a missing object as "no hints."
+     */
+    annotations?: EdgeMcpToolAnnotations;
+}
+/** The standard MCP tool annotation hints the bridge understands. */
+export interface EdgeMcpToolAnnotations {
+    /** Tool only reads state — safe to call freely, no confirmation. */
+    readOnlyHint?: boolean;
+    /**
+     * Tool performs a destructive / final action. Bridge convention: treat this as
+     * "confirm with the user before calling" (covers additive-but-final actions
+     * like submit / send / place-order too).
+     */
+    destructiveHint?: boolean;
+    /** Safe to retry with the same args (no extra effect). */
+    idempotentHint?: boolean;
+    /** Output may contain untrusted / third-party content (injection risk). */
+    untrustedContentHint?: boolean;
 }
 /**
  * Payload of the toolkit's `resourceupdated` event (live-state extension).

package/lib/services/edge-mcp/index.d.ts

@@ -2,4 +2,4 @@ export { EdgeMcpBridge } from "./edge-mcp-bridge";
 export type { EdgeMcpBridgeOptions } from "./edge-mcp-bridge";
 export { normalizeFunctionCallEvent } from "./normalizeFunctionCallEvent";
 export { getModelContext, discoverModelContext } from "./edge-mcp-discovery";
-export type { EdgeMcpModelContext, EdgeMcpToolInfo, EdgeMcpResourceUpdate, FunctionCallEvent, SendCommand, } from "./edge-mcp-types";
+export type { EdgeMcpModelContext, EdgeMcpToolInfo, EdgeMcpToolAnnotations, EdgeMcpResourceUpdate, FunctionCallEvent, SendCommand, } from "./edge-mcp-types";

package/lib/shell/mount-shell.d.ts

@@ -0,0 +1,88 @@
+import type { NapsterCompanionApiConfig, NapsterCompanionApiInstance } from "../types";
+export interface ShellOptions {
+    /**
+     * Returns a fresh connection token. The site implements this (typically a POST to
+     * its own endpoint that mints a token server-side). Required.
+     */
+    getToken: () => Promise<string>;
+    /**
+     * Persist the session across page navigation by wrapping the current page in a
+     * same-origin iframe on connect (needed for multi-page apps). Default: `false` —
+     * the avatar mounts inline in the current page and a full page navigation ends the
+     * session (a normal in-page widget). Turn on only when you need cross-navigation
+     * persistence.
+     */
+    persist?: boolean;
+    /**
+     * The ONLY URLs that break out of the iframe (open at the top window and end the session).
+     * A link is opened inside the iframe unless it matches this denylist — use it for URLs that
+     * can't be framed, e.g. an identity / SSO subdomain, or same-origin paths that redirect
+     * off-site. Everything not listed (including other cross-origin links) navigates in the iframe.
+     */
+    persistConfig?: {
+        /**
+         * Hostnames to force out of the iframe. Matched as the exact host OR a parent domain —
+         * e.g. `"napster.com"` also matches `"identity.napster.com"`.
+         */
+        domains?: string[];
+        /**
+         * URLs to force out of the iframe: an absolute `"https://…"` (exact or prefix match), or a
+         * same-origin path prefix like `"/signout"`.
+         */
+        urls?: string[];
+    };
+    /**
+     * SECOND persistence variant (no iframe). When a session is active and the user navigates
+     * (a normal full page load), automatically start a NEW session on the next page — so the
+     * avatar "follows" the user across pages. Each page is a fresh connection (the backend can
+     * resume the conversation by externalClientId). The intent is remembered in sessionStorage
+     * and cleared when the user ends the session. Ignored when `persist` (the iframe variant)
+     * is on. Default: `false`.
+     */
+    reconnectOnNavigation?: boolean;
+    /** When `persist` is on, the URL to load in the iframe. Default: the current page (`location.href`). */
+    siteUrl?: string;
+    /** Element to build the launcher/iframe into. Default: `document.body`. */
+    mount?: HTMLElement;
+    /** Avatar config forwarded to `init()`. `mountContainer`/`layout` are managed by the shell. */
+    avatar?: Partial<NapsterCompanionApiConfig>;
+    /** The iframe `allow` attribute (Permissions Policy for the site). Default: `"autoplay; clipboard-write"`. */
+    iframeAllow?: string;
+    /** Launcher button label. Default: `"Talk to an agent"`. */
+    launcherLabel?: string;
+    /** Start a session immediately instead of showing a launcher. Default: `false`. */
+    autoConnect?: boolean;
+    /**
+     * While a session is active, mirror the iframe's path into the address bar (so inner
+     * pages stay shareable/bookmarkable) and follow parent back/forward into the iframe.
+     * Same-origin only. Default: `true`.
+     */
+    syncHistory?: boolean;
+    /** Log shell lifecycle to the console. Default: `false`. */
+    debug?: boolean;
+}
+export interface ShellController {
+    /** `true` if this call built the launcher (top-level); `false` if it no-oped (framed content). */
+    isShell: boolean;
+    /** The live avatar instance once connected, else `null`. */
+    getInstance(): NapsterCompanionApiInstance | null;
+    /** The site iframe while a session is active, else `null`. */
+    getIframe(): HTMLIFrameElement | null;
+    /** Start a session: connect the avatar (and, with `persist`, wrap the current page in the iframe). */
+    connect(): Promise<void>;
+    /** End the session (and, if wrapped, unwrap back to the plain site). */
+    disconnect(): void;
+    /** Remove the launcher and any active session/iframe. */
+    destroy(): void;
+}
+type InitFn = (token: string, config?: Partial<NapsterCompanionApiConfig>) => Promise<NapsterCompanionApiInstance>;
+/**
+ * Build the lazy persistent-agent shell. Returns a {@link ShellController}.
+ *
+ * A no-op (returns a controller with `isShell: false`) when run inside the shell
+ * iframe (framed content), so the same snippet is safe to include on every page.
+ *
+ * `init` is the SDK's `init` method, wired by the SDK.
+ */
+export declare function mountShell(init: InitFn, options: ShellOptions): ShellController;
+export {};

package/lib/types/index.d.ts

@@ -335,6 +335,13 @@ export interface NapsterCompanionApiConfig {
     functions?: CompanionFunction[];
     /** Enable debug logging throughout the SDK. When enabled, detailed logs will be output to the console. */
     debug?: boolean;
+    /**
+     * Read WebMCP tools from a same-origin child iframe's `document.modelContext` instead of
+     * this window's. Set by the persistent-agent shell (`mountShell` with `persist`) so the
+     * avatar in the top-level document operates the SITE running inside the wrapped iframe.
+     * Leave unset for a normal same-page integration.
+     */
+    edgeMcpIframe?: HTMLIFrameElement;
     /** Analytics configuration controls analytics delivery and tracking. */
     analytics?: AnalyticsConfig;
     /** Lifecycle callbacks. All are optional. */
@@ -456,6 +463,12 @@ export interface NapsterCompanionApiSDK {
      * Returns a Promise that resolves to a controllable `NapsterCompanionApiInstance`.
      */
     init(token: string, config?: Partial<NapsterCompanionApiConfig>): Promise<NapsterCompanionApiInstance>;
+    /**
+     * Mount a persistent-agent shell for multi-page apps: renders the site in a
+     * same-origin iframe with the avatar in the top-level shell, so the agent
+     * session survives navigation. No-op when run as the framed content.
+     */
+    mountShell(options: import("../shell/mount-shell").ShellOptions): import("../shell/mount-shell").ShellController;
     /** The SDK version string (useful for diagnostics). */
     version: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@touchcastllc/napster-companion-api-dev",
-  "version": "1.0.0-alpha.73",
+  "version": "1.0.0-alpha.75",
   "keywords": [
     "napster",
     "companion-api",