@touchcastllc/napster-companion-api-dev 1.0.0-alpha.71 → 1.0.0-alpha.72

package/lib/services/webmcp/index.d.ts

@@ -0,0 +1,5 @@
+export { WebMcpBridge } from "./webmcp-bridge";
+export type { WebMcpBridgeOptions } from "./webmcp-bridge";
+export { normalizeFunctionCallEvent } from "./normalizeFunctionCallEvent";
+export { getModelContext, discoverModelContext } from "./webmcp-discovery";
+export type { WebMcpModelContext, WebMcpToolInfo, WebMcpResourceUpdate, FunctionCallEvent, SendCommand, } from "./webmcp-types";

package/lib/services/{edge-mcp → webmcp}/normalizeFunctionCallEvent.d.ts

@@ -1,8 +1,8 @@
-import type { FunctionCallEvent } from "./edge-mcp-types";
+import type { FunctionCallEvent } from "./webmcp-types";
 /**
  * Returns a normalized `FunctionCallEvent` if `message` represents a function
  * call, otherwise `null`. Callers route a non-null result to
- * `EdgeMcpBridge.dispatchFunctionCall` and skip normal chat handling.
+ * `WebMcpBridge.dispatchFunctionCall` and skip normal chat handling.
  *
  * Requires `name` and `call_id`. `arguments` is passed through as-is (object
  * for `function_implicitly_called`, JSON string for realtime protocols, or

package/lib/services/webmcp/webmcp-bridge.d.ts

@@ -0,0 +1,89 @@
+import type { FunctionCallEvent, SendCommand, WebMcpModelContext } from "./webmcp-types";
+export interface WebMcpBridgeOptions {
+    /**
+     * The SDK's `sendCommand`, bound to the live instance so the bridge can emit
+     * `send_message` (state relays) and `send_function_output` (tool results).
+     */
+    sendCommand: SendCommand;
+    /** Mirror the SDK's `debug` flag. Default: `false`. */
+    debug?: boolean;
+    /** How long `attach()` polls for `document.modelContext`. Default: `1500` ms. */
+    attachTimeoutMs?: number;
+    /**
+     * Forward toolkit state pushes (`resourceupdated`) to the agent as
+     * `role: 'system'` messages. Set false to handle state yourself. Default: `true`.
+     */
+    relayStatePushes?: boolean;
+    /**
+     * Register the page's WebMCP tools with the agent mid-session by pushing them
+     * as `set_settings.inline_functions` on attach and on every `toolchange`. Set
+     * false to manage the agent's function list yourself. Default: `true`.
+     */
+    registerInlineFunctions?: boolean;
+}
+export declare class WebMcpBridge {
+    private mc;
+    private tools;
+    private onToolChange;
+    private onResourceUpdated;
+    private lastInlineSig;
+    private sessionReady;
+    private disposed;
+    private readonly options;
+    constructor(options: WebMcpBridgeOptions);
+    /**
+     * Discover `document.modelContext` in the page, cache its tools, and wire up
+     * the `toolchange` / `resourceupdated` listeners. Returns the model context,
+     * or `null` if none appears within the timeout. Safe to fire from `init()` —
+     * failure is silent and non-fatal.
+     */
+    attach(): Promise<WebMcpModelContext | null>;
+    /** Attach to a known model context: cache tools and subscribe to events. */
+    private bind;
+    /** Re-read the tool catalog from the model context. */
+    private refreshTools;
+    /** Map the current WebMCP tools to `set_settings.inline_functions` definitions. */
+    private buildInlineFunctions;
+    /**
+     * Called by the SDK when the session reaches the "ready" state
+     * (`avatar_state_changed` → `state: "ready"`). This is the only safe moment to
+     * register tools — the realtime session silently drops `inline_functions` sent
+     * before it's ready (e.g. on data-channel open). Marks the session ready,
+     * resets the dedupe, and pushes the current tools. Re-fires on reconnect (a
+     * fresh "ready").
+     */
+    onSessionReady(): void;
+    /**
+     * Register the page's WebMCP tools with the agent by sending the complete
+     * current catalog as `set_settings.inline_functions`. Called on attach, on
+     * every toolchange, and on data-channel open, so tools registered mid-session
+     * reach the agent. No-op when not attached, when `registerInlineFunctions` is
+     * disabled, or when the catalog is unchanged since the last successful push.
+     */
+    private pushInlineFunctions;
+    /** True if `attach()` succeeded and the bridge has a live model context. */
+    get isAttached(): boolean;
+    /**
+     * Dispatch a normalized agent function call. Handles it only when the name
+     * matches a tool the page currently exposes. The name can arrive as the
+     * top-level `event.name` (direct call, args in `event.arguments`) or nested in
+     * a wrapper tool's `tool_name` (args under `arguments`/`args`). Anything else
+     * is ignored so the bridge coexists with other tool paths. Matched calls
+     * always reply via `send_function_output`.
+     */
+    dispatchFunctionCall(event: FunctionCallEvent): Promise<void>;
+    /** Tear down listeners and drop the model-context ref. Idempotent. */
+    dispose(): void;
+    /**
+     * Forward a toolkit resource update to the agent as a system message.
+     * `trigger_response: false` keeps the avatar from speaking on every change;
+     * `delay: true` waits for it to finish its current speech first.
+     */
+    private relayResourceUpdate;
+    /**
+     * Emit a `send_function_output` for a `call_id`. When `raw` is true the
+     * payload is already the output string; otherwise it is JSON-encoded.
+     */
+    private sendOutput;
+    private log;
+}

package/lib/services/webmcp/webmcp-discovery.d.ts

@@ -0,0 +1,14 @@
+import type { WebMcpModelContext } from "./webmcp-types";
+/** Read `document.modelContext`, falling back to the deprecated navigator alias. */
+export declare function getModelContext(): WebMcpModelContext | 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.
+ */
+export declare function discoverModelContext(timeoutMs?: number): Promise<WebMcpModelContext | null>;

package/lib/services/webmcp/webmcp-types.d.ts

@@ -0,0 +1,76 @@
+/** Tool metadata as returned by `document.modelContext.getTools()`. */
+export interface WebMcpToolInfo {
+    /** Domain-named identifier, e.g. `'docs.search'` or `'cart.add'`. */
+    name: string;
+    /** One-sentence description the agent uses to decide WHEN to invoke. */
+    description?: string;
+    /**
+     * JSON Schema describing valid arguments. NOTE: the WebMCP polyfill returns
+     * this as a JSON **string** (per the spec's `ModelContextToolInfo`); a native
+     * implementation may return an object. Callers must handle both.
+     */
+    inputSchema?: Record<string, unknown> | string;
+    /** Optional human-readable label. */
+    title?: string;
+}
+/**
+ * Payload of the toolkit's `resourceupdated` event (live-state extension).
+ * Mirrors MCP's `notifications/resources/updated`, but carries the value
+ * inline so the SDK can relay it without a follow-up read.
+ */
+export interface WebMcpResourceUpdate {
+    uri: string;
+    value: unknown;
+}
+/**
+ * The subset of `document.modelContext` this bridge consumes.
+ *
+ * `getTools()` / `executeTool()` are the standard read/invoke methods (named in
+ * the WebMCP spec; implemented by the polyfill and Chrome). The `resource*`
+ * members are the Napster toolkit's live-state extension and are OPTIONAL — a
+ * bare WebMCP site won't have them, so the bridge feature-detects before use.
+ * `document.modelContext` is an `EventTarget`: it dispatches `toolchange` when
+ * the tool list changes and (with the toolkit) `resourceupdated` on state push.
+ */
+export interface WebMcpModelContext extends EventTarget {
+    getTools(): Promise<WebMcpToolInfo[]>;
+    executeTool(tool: WebMcpToolInfo, inputArgsJson: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<string | null>;
+    getResources?: () => Array<{
+        uri: string;
+        name: string;
+    }>;
+    readResource?: (uri: string) => Promise<unknown>;
+    subscribeResource?: (uri: string, handler: (update: WebMcpResourceUpdate) => void) => () => void;
+}
+/**
+ * Normalized shape of an incoming function-call event.
+ *
+ * The server signals an agent tool call with a `function_implicitly_called`
+ * event; the SDK's data-channel handler extracts these three fields before
+ * calling `WebMcpBridge.dispatchFunctionCall`.
+ */
+export interface FunctionCallEvent {
+    /** The tool/function name the agent invoked. */
+    name: string;
+    /**
+     * The arguments the agent produced — an already-parsed object for
+     * `function_implicitly_called`, a JSON string for realtime protocols, or
+     * absent for no-arg calls. The bridge accepts all three.
+     */
+    arguments: unknown;
+    /** Unique identifier the server uses to pair the call with its output. */
+    call_id: string;
+}
+/**
+ * Minimal `sendCommand` signature. Mirrors
+ * `NapsterCompanionApiInstance.sendCommand` without coupling the bridge to the
+ * full `DataChannelCommand` union — the bridge only sends two command types:
+ *   - `{ type: 'send_message', data: { role, text, trigger_response, delay } }`
+ *   - `{ type: 'send_function_output', data: { call_id, output } }`
+ */
+export type SendCommand = (command: {
+    type: string;
+    data: Record<string, unknown>;
+}) => boolean | void;

package/lib/types/index.d.ts

@@ -30,6 +30,34 @@ export interface CompanionFunction {
     /** JSON-Schema style parameter definitions. */
     parameters?: Record<string, unknown>;
 }
+/**
+ * A full function definition registered inline at runtime via
+ * `set_settings.inline_functions`. Mirrors the backend's function record: a
+ * top-level `id` and `flow`, with name/description/parameters nested under
+ * `data`. Used to register tools MID-SESSION (the WebMCP bridge maps the page's
+ * live `document.modelContext` tools to this shape).
+ */
+export interface InlineFunction {
+    /** Unique identifier for the function record. */
+    id: string;
+    /**
+     * Invocation mode. `"implicit"` = invoked client-side (the client returns the
+     * result); `"explicit"` = server-handled. WebMCP tools are `"implicit"`.
+     */
+    flow: "implicit" | "explicit";
+    /**
+     * The connection modality the function operates in (e.g. `"video"`). Required
+     * so the server doesn't reject the WebRTC connection with "Modalities other
+     * than video are not supported".
+     */
+    modality?: string;
+    /** The function definition, same fields as a registered function. */
+    data: {
+        name: string;
+        description?: string;
+        parameters?: Record<string, unknown>;
+    };
+}
 export interface SendMessageData {
     /** The text message to send */
     text: string;
@@ -55,7 +83,18 @@ export type CancelCommand = {
 export type SetSettingsCommand = {
     type: DataChannelMessageType.SET_SETTINGS;
     data: {
-        functions: CompanionFunction[];
+        /** Session/connection modality (e.g. `"video"` for the avatar connection). */
+        modality?: string;
+        /** Functions configured at session start. */
+        functions?: CompanionFunction[];
+        /**
+         * Full function definitions provided inline at runtime. Used to register
+         * tools MID-SESSION — e.g. the WebMCP bridge pushes the page's live
+         * `document.modelContext` tools here, and re-pushes whenever the tool
+         * catalog changes. Merged with existing settings: send the complete current
+         * list each time.
+         */
+        inline_functions?: InlineFunction[];
     };
 };
 export type StartVideoCommand = {

package/package.json

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

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

@@ -1,9 +0,0 @@
-import type { CompanionFunction } from "../../types";
-import type { EdgeMcpApi } from "./edge-mcp-types";
-/**
- * Construct the `invokeCapability` function definition from a live Edge MCP
- * api ref. Returns `null` when no capabilities are published — in that case
- * there is nothing for the agent to call and the SDK should not register the
- * function at all.
- */
-export declare function buildInvokeCapabilityFunction(api: EdgeMcpApi): CompanionFunction | null;

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

@@ -1,57 +0,0 @@
-import type { EdgeMcpApi, FunctionCallEvent, SendCommand } from "./edge-mcp-types";
-export interface EdgeMcpBridgeOptions {
-    /**
-     * The SDK's `sendCommand`, bound to the live instance so the bridge can emit
-     * `send_message` (state relays) and `send_function_output` (invoke results).
-     */
-    sendCommand: SendCommand;
-    /** Mirror the SDK's `debug` flag. Default: `false`. */
-    debug?: boolean;
-    /** How long `attach()` waits for an Edge MCP to publish. Default: `1500` ms. */
-    attachTimeoutMs?: number;
-    /**
-     * Forward Edge MCP state pushes to the agent as `role: 'system'` messages.
-     * Set false to control state delivery yourself. Default: `true`.
-     */
-    relayStatePushes?: boolean;
-}
-export declare class EdgeMcpBridge {
-    private api;
-    private unsubStateChange;
-    private disposed;
-    private readonly options;
-    constructor(options: EdgeMcpBridgeOptions);
-    /**
-     * Discover an Edge MCP in the page and subscribe to its state changes.
-     * Returns the api ref, or `null` if none publishes within the timeout.
-     * Safe to fire from `init()` — failure is silent and non-fatal.
-     */
-    attach(): Promise<EdgeMcpApi | null>;
-    /** True if `attach()` succeeded and the bridge has a live api ref. */
-    get isAttached(): boolean;
-    /** The attached Edge MCP api ref, or `null` if not attached. */
-    getApi(): EdgeMcpApi | null;
-    /**
-     * Dispatch a normalized agent function call. Handles it only when the name
-     * matches a capability the attached Edge MCP currently exposes. The name can
-     * arrive as the top-level `event.name` (direct call, args in
-     * `event.arguments`) or nested in a wrapper tool's `tool_name` (args under
-     * `arguments`/`args`). Anything else is ignored so the bridge coexists with
-     * other tool paths. Matched calls always reply via `send_function_output`.
-     */
-    dispatchFunctionCall(event: FunctionCallEvent): Promise<void>;
-    /** Tear down subscriptions and drop the api ref. Idempotent. */
-    dispose(): void;
-    /**
-     * Forward an Edge MCP state push to the agent as a system message.
-     * `trigger_response: false` keeps the avatar from speaking on every change;
-     * `delay: true` waits for it to finish its current speech first.
-     */
-    private relayStateChange;
-    /**
-     * Emit a `send_function_output` for a `call_id`. `output` is JSON-encoded per
-     * the Realtime protocol convention.
-     */
-    private sendOutput;
-    private log;
-}

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

@@ -1,13 +0,0 @@
-import type { EdgeMcpApi } from "./edge-mcp-types";
-/**
- * Discover an Edge MCP instance published at the well-known global slot.
- *
- * Resolves with the api ref if found; resolves with `null` after the
- * timeout if no Edge MCP shows up. Never rejects.
- *
- * @param timeoutMs How long to wait for a producer if none is published
- *                  yet. Default: 1500ms — short enough not to delay the
- *                  SDK noticeably, long enough to cover normal hydration
- *                  ordering.
- */
-export declare function discoverEdgeMcp(timeoutMs?: number): Promise<EdgeMcpApi | null>;

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

@@ -1,94 +0,0 @@
-/**
- * Metadata exposed for one capability the agent can invoke.
- * Returned by `EdgeMcpApi.listCapabilities()`.
- */
-export interface EdgeMcpCapabilityMeta {
-    /** Domain-named identifier, e.g. `'docs.search'` or `'cart.add'`. */
-    name: string;
-    /** One-sentence description used by the agent to decide WHEN to invoke. */
-    description: string;
-    /** JSON Schema describing valid arguments. Always present. */
-    inputSchema: Record<string, unknown>;
-    /** JSON Schema describing the return value, or `null`. */
-    outputSchema: Record<string, unknown> | null;
-    /** Governance tier — `'read' | 'reversible' | 'irreversible'`. */
-    sideEffect: "read" | "reversible" | "irreversible";
-    /** True if re-running with the same args is safe. */
-    idempotent: boolean;
-}
-/** Result returned by `EdgeMcpApi.invoke()`. */
-export type EdgeMcpInvokeResult = {
-    ok: true;
-    result: unknown;
-    sideEffect: string;
-} | {
-    ok: false;
-    error: string;
-};
-/** Payload delivered to `onStateChange` handlers. */
-export interface EdgeMcpDelta {
-    name: string;
-    value: unknown;
-}
-/**
- * The subset of the Edge MCP API this bridge consumes.
- *
- * The actual `EdgeMcp` interface defined in the `@napster/edge-mcp` package
- * also includes `registerCapability` / `registerStateProvider` / `dispose`,
- * but those are app-side concerns the SDK never calls. Keeping the shape
- * minimal makes the structural type easier to satisfy for alternative
- * implementations.
- */
-export interface EdgeMcpApi {
-    listCapabilities: () => EdgeMcpCapabilityMeta[];
-    invoke: (name: string, args?: unknown) => Promise<EdgeMcpInvokeResult>;
-    getState?: (name: string) => Promise<unknown>;
-    snapshot?: () => Promise<Record<string, unknown>>;
-    /**
-     * Optional — present in any v1-compliant implementation. The SDK uses it
-     * to relay state pushes to the agent as system messages.
-     */
-    onStateChange?: (handler: (delta: EdgeMcpDelta) => void) => () => void;
-}
-/**
- * Shape of the object published to the well-known global slot.
- * Defined in Edge MCP spec §4.2.
- */
-export interface PublishedEdgeMcp {
-    version: 1;
-    api: EdgeMcpApi;
-}
-/**
- * Normalized shape of an incoming function-call event.
- *
- * The exact wire shape varies by upstream protocol (Azure OpenAI Realtime
- * uses `response.function_call_arguments.done`); the SDK's data-channel
- * handler is responsible for extracting these three fields before calling
- * `EdgeMcpBridge.dispatchFunctionCall`.
- */
-export interface FunctionCallEvent {
-    /** The tool/function name the agent invoked. */
-    name: string;
-    /**
-     * The arguments the agent produced. The server's
-     * `function_implicitly_called` event delivers these as an already-parsed
-     * object (`{ tool_name, arguments }`); other protocols may deliver a
-     * JSON-encoded string. The bridge accepts both.
-     */
-    arguments: unknown;
-    /** Unique identifier the server uses to pair the call with its output. */
-    call_id: string;
-}
-/**
- * Minimal `sendCommand` signature.
- *
- * Mirrors the existing `NapsterCompanionApiInstance.sendCommand` without
- * coupling the bridge to the full `DataChannelCommand` union — the bridge
- * only sends two command types:
- *   - `{ type: 'send_message', data: { role, text, trigger_response, delay } }`
- *   - `{ type: 'send_function_output', data: { call_id, output } }`
- */
-export type SendCommand = (command: {
-    type: string;
-    data: Record<string, unknown>;
-}) => void;

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

@@ -1,5 +0,0 @@
-export { EdgeMcpBridge } from "./edge-mcp-bridge";
-export type { EdgeMcpBridgeOptions } from "./edge-mcp-bridge";
-export { buildInvokeCapabilityFunction } from "./buildInvokeCapabilityFunction";
-export { normalizeFunctionCallEvent } from "./normalizeFunctionCallEvent";
-export type { EdgeMcpApi, EdgeMcpCapabilityMeta, EdgeMcpInvokeResult, EdgeMcpDelta, FunctionCallEvent, } from "./edge-mcp-types";