@touchcastllc/napster-companion-api-dev 1.0.0-alpha.65 → 1.0.0-alpha.67

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

@@ -0,0 +1,9 @@
+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

@@ -0,0 +1,95 @@
+import type { EdgeMcpApi, FunctionCallEvent, SendCommand } from "./edge-mcp-types";
+export interface EdgeMcpBridgeOptions {
+    /**
+     * The SDK's `sendCommand` method, bound to the live instance so the
+     * bridge can emit `send_message` (for state relays) and
+     * `function_call_output` (for invoke results).
+     */
+    sendCommand: SendCommand;
+    /**
+     * When true, the bridge logs attach status, every dispatched function
+     * call, and every state push relay to the developer console. Match the
+     * SDK's own `debug` flag.
+     *
+     * Default: `false`.
+     */
+    debug?: boolean;
+    /**
+     * How long `attach()` waits for a producer publication before giving up.
+     * The SDK is not blocked beyond this duration even when no Edge MCP
+     * exists in the page.
+     *
+     * Default: `1500` (ms).
+     */
+    attachTimeoutMs?: number;
+    /**
+     * When true, Edge MCP state pushes are forwarded to the agent as
+     * `role: 'system'` messages. Set false if the consuming application
+     * wants to control state delivery itself.
+     *
+     * Default: `true`.
+     */
+    relayStatePushes?: boolean;
+}
+export declare class EdgeMcpBridge {
+    private api;
+    private unsubStateChange;
+    private disposed;
+    private readonly options;
+    constructor(options: EdgeMcpBridgeOptions);
+    /**
+     * Discover an Edge MCP instance in the page and subscribe to state
+     * changes. Returns the discovered api ref, or `null` if no Edge MCP
+     * publishes within the timeout.
+     *
+     * Safe to await from the SDK's `init()` path. Failure is silent — the
+     * SDK continues to run exactly as it would without Edge MCP present.
+     */
+    attach(): Promise<EdgeMcpApi | null>;
+    /** True if `attach()` succeeded and the bridge has a live api ref. */
+    get isAttached(): boolean;
+    /**
+     * Direct access to the attached Edge MCP api ref, for callers that need
+     * to read `listCapabilities()` themselves (for example, to build the
+     * `invokeCapability` function definition for `set_settings.functions`).
+     *
+     * Returns `null` if not attached.
+     */
+    getApi(): EdgeMcpApi | null;
+    /**
+     * Dispatch an incoming function call from the agent. The SDK's
+     * data-channel message handler is responsible for normalizing the
+     * upstream event shape into `FunctionCallEvent` before calling this.
+     *
+     * Only the Edge MCP wrapper function (see
+     * `INVOKE_CAPABILITY_FUNCTION_NAMES`) is handled. Anything else is silently
+     * ignored so the bridge can coexist with other tool paths (vendor-registered
+     * tools, customer's own `onFunctionCall`, etc.).
+     *
+     * Always responds via `function_call_output` — success, validation
+     * failure, and unexpected error all produce a structured result the
+     * agent can read and narrate back to the user.
+     */
+    dispatchFunctionCall(event: FunctionCallEvent): Promise<void>;
+    /**
+     * Tear down subscriptions and drop the Edge MCP api ref. Call from the
+     * SDK's `destroy()` path. Idempotent.
+     */
+    dispose(): void;
+    /**
+     * Forward an Edge MCP state push to the agent as a system message.
+     *
+     * `role: 'system'` injects context without rendering to the user.
+     * `trigger_response: false` keeps the avatar from speaking on every
+     * state change. `delay: true` waits for the agent to finish its current
+     * speech before delivering, so it doesn't interrupt mid-sentence.
+     */
+    private relayStateChange;
+    /**
+     * Emit a `function_call_output` command carrying the bridge's result for
+     * a given `call_id`. The `output` field is a JSON-encoded string per the
+     * Realtime protocol convention.
+     */
+    private sendOutput;
+    private log;
+}

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

@@ -0,0 +1,13 @@
+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

@@ -0,0 +1,94 @@
+/**
+ * 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: 'function_call_output', data: { call_id, output } }`
+ */
+export type SendCommand = (command: {
+    type: string;
+    data: Record<string, unknown>;
+}) => void;

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

@@ -0,0 +1,5 @@
+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";

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

@@ -0,0 +1,11 @@
+import type { FunctionCallEvent } from "./edge-mcp-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.
+ *
+ * Requires `name` and `call_id`. `arguments` is passed through as-is (object
+ * for `function_implicitly_called`, JSON string for realtime protocols, or
+ * absent for no-arg calls) — the bridge handles both shapes.
+ */
+export declare function normalizeFunctionCallEvent(message: unknown): FunctionCallEvent | null;

package/lib/types/index.d.ts

@@ -66,7 +66,18 @@ export type StopVideoCommand = {
     type: DataChannelMessageType.STOP_VIDEO;
     data: null;
 };
-export type DataChannelCommand = SendMessageCommand | CancelCommand | SetSettingsCommand | StartVideoCommand | StopVideoCommand;
+/** Result of an agent function call, paired with its originating `call_id`. */
+export interface FunctionCallOutputData {
+    /** Identifier the server uses to pair the call with its output. */
+    call_id: string;
+    /** JSON-encoded string of the function result. */
+    output: string;
+}
+export type FunctionCallOutputCommand = {
+    type: DataChannelMessageType.FUNCTION_CALL_OUTPUT;
+    data: FunctionCallOutputData;
+};
+export type DataChannelCommand = SendMessageCommand | CancelCommand | SetSettingsCommand | StartVideoCommand | StopVideoCommand | FunctionCallOutputCommand;
 export declare const maxInactiveTimeoutDuration = 180000;
 export declare const defaultCountdownDuration = 30;
 export interface EventMessage {

package/lib/utils/InactiveOverlayManager.d.ts

@@ -42,6 +42,7 @@ export declare class InactiveOverlayManager {
     private currentTrigger;
     private isVisible;
     private readonly mountElement;
+    private pipTarget;
     private readonly callbacks;
     constructor(mountElement: HTMLElement, callbacks?: InactiveOverlayCallbacks);
     /**
@@ -62,6 +63,17 @@ export declare class InactiveOverlayManager {
      * Get the current trigger type if overlay is visible
      */
     getCurrentTrigger(): InactiveOverlayTrigger | null;
+    /**
+     * Set the PiP window body as the overlay target (or null when PiP closes).
+     * Relocates a visible overlay so it stays in front of the user.
+     */
+    setPipTarget(target: HTMLElement | null): void;
+    private getMountTarget;
+    /**
+     * Move a visible overlay into the current target document. The countdown
+     * keeps running since the same DOM node (and its timer) is preserved.
+     */
+    private relocate;
     /**
      * Handle continue button click
      */

package/lib/utils/PiPManager.d.ts

@@ -17,4 +17,8 @@ export declare function createPiPManager(handlers: {
     onScreenShareToggle: () => void;
     isScreenShareSupported: () => boolean;
     onInteraction?: () => void;
+    /** PiP window opened — receives its body so callers can render into it. */
+    onOpen?: (pipBody: HTMLElement) => void;
+    /** PiP window closed (by user or programmatically). */
+    onClose?: () => void;
 }): PiPController;

package/package.json

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