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

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

@@ -1,5 +1,5 @@
-import type { FunctionCallEvent, SendCommand, WebMcpModelContext } from "./webmcp-types";
-export interface WebMcpBridgeOptions {
+import type { FunctionCallEvent, SendCommand, EdgeMcpModelContext } 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` (tool results).
@@ -21,25 +21,44 @@ export interface WebMcpBridgeOptions {
      */
     registerInlineFunctions?: boolean;
 }
-export declare class WebMcpBridge {
+export declare class EdgeMcpBridge {
     private mc;
     private tools;
     private onToolChange;
     private onResourceUpdated;
+    private onResourceListChanged;
+    private readonly seededUris;
     private lastInlineSig;
     private sessionReady;
     private disposed;
     private readonly options;
-    constructor(options: WebMcpBridgeOptions);
+    constructor(options: EdgeMcpBridgeOptions);
     /**
      * 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(): Promise<EdgeMcpModelContext | null>;
     /** 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/{webmcp/webmcp-discovery.d.ts → edge-mcp/edge-mcp-discovery.d.ts}

@@ -1,6 +1,6 @@
-import type { WebMcpModelContext } from "./webmcp-types";
+import type { EdgeMcpModelContext } from "./edge-mcp-types";
 /** Read `document.modelContext`, falling back to the deprecated navigator alias. */
-export declare function getModelContext(): WebMcpModelContext | null;
+export declare function getModelContext(): EdgeMcpModelContext | null;
 /**
  * Discover `document.modelContext`, polling briefly if it is not present yet.
  *
@@ -11,4 +11,4 @@ export declare function getModelContext(): WebMcpModelContext | null;
  *                  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>;
+export declare function discoverModelContext(timeoutMs?: number): Promise<EdgeMcpModelContext | null>;

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

@@ -1,5 +1,5 @@
 /** Tool metadata as returned by `document.modelContext.getTools()`. */
-export interface WebMcpToolInfo {
+export interface EdgeMcpToolInfo {
     /** Domain-named identifier, e.g. `'docs.search'` or `'cart.add'`. */
     name: string;
     /** One-sentence description the agent uses to decide WHEN to invoke. */
@@ -12,13 +12,36 @@ export interface WebMcpToolInfo {
     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).
  * 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 {
+export interface EdgeMcpResourceUpdate {
     uri: string;
     value: unknown;
 }
@@ -32,9 +55,9 @@ export interface WebMcpResourceUpdate {
  * `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?: {
+export interface EdgeMcpModelContext extends EventTarget {
+    getTools(): Promise<EdgeMcpToolInfo[]>;
+    executeTool(tool: EdgeMcpToolInfo, inputArgsJson: string, options?: {
         signal?: AbortSignal;
     }): Promise<string | null>;
     getResources?: () => Array<{
@@ -42,14 +65,14 @@ export interface WebMcpModelContext extends EventTarget {
         name: string;
     }>;
     readResource?: (uri: string) => Promise<unknown>;
-    subscribeResource?: (uri: string, handler: (update: WebMcpResourceUpdate) => void) => () => void;
+    subscribeResource?: (uri: string, handler: (update: EdgeMcpResourceUpdate) => 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`.
+ * calling `EdgeMcpBridge.dispatchFunctionCall`.
  */
 export interface FunctionCallEvent {
     /** The tool/function name the agent invoked. */

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 { normalizeFunctionCallEvent } from "./normalizeFunctionCallEvent";
+export { getModelContext, discoverModelContext } from "./edge-mcp-discovery";
+export type { EdgeMcpModelContext, EdgeMcpToolInfo, EdgeMcpToolAnnotations, EdgeMcpResourceUpdate, FunctionCallEvent, SendCommand, } from "./edge-mcp-types";

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

@@ -1,8 +1,8 @@
-import type { FunctionCallEvent } from "./webmcp-types";
+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
- * `WebMcpBridge.dispatchFunctionCall` and skip normal chat handling.
+ * `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

package/package.json

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

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

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