@zeph-to/mcp-server 1.12.0 → 1.13.0

package/dist/config.d.ts

@@ -1,6 +1,9 @@
 export interface McpServerConfig {
     apiKey: string;
     baseUrl: string;
+    /** WebSocket endpoint for the hook-response fast path (§S3). Optional —
+     *  without it (or without a WebSocket global) waits are poll-only. */
+    wsUrl?: string;
     hookId?: string;
     deviceId?: string;
     sessionId?: string;

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,eAAe;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,WAAW,EAAE,MAAM,CAAC;CACvB;AAiBD;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAI,aAAa,MAAM,EAAE,OAAO,MAAM,KAAG,MAGpE,CAAC;AAsGF,eAAO,MAAM,UAAU,QAAO,eAsB7B,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,eAAe;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB;0EACsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,WAAW,EAAE,MAAM,CAAC;CACvB;AAiBD;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAI,aAAa,MAAM,EAAE,OAAO,MAAM,KAAG,MAGpE,CAAC;AAuGF,eAAO,MAAM,UAAU,QAAO,eAuB7B,CAAC"}

package/dist/config.js

@@ -136,6 +136,7 @@ const loadConfig = () => {
     return {
         apiKey,
         baseUrl: (resolvedEnv('ZEPH_BASE_URL') ?? fileConfig.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, ''),
+        wsUrl: resolvedEnv('ZEPH_WS_URL') ?? fileConfig.wsUrl,
         hookId: resolvedEnv('ZEPH_HOOK_ID') ?? fileConfig.hookId,
         deviceId: resolvedEnv('ZEPH_DEVICE_ID') ?? fileConfig.deviceId,
         sessionId,

package/dist/index.js

@@ -6,6 +6,7 @@ const path_1 = require("path");
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const config_js_1 = require("./config.js");
+const ws_wait_js_1 = require("./ws-wait.js");
 const api_client_js_1 = require("./api-client.js");
 const crypto_js_1 = require("./crypto.js");
 const notify_js_1 = require("./tools/notify.js");
@@ -30,6 +31,9 @@ const getVersion = () => {
 };
 const createServer = (config) => {
     const client = new api_client_js_1.ZephApiClient(config);
+    // Shared WS fast path for zeph_prompt/input/ask waits — degrades to
+    // pure polling when wsUrl or the WebSocket global is missing (§S3).
+    const waiter = new ws_wait_js_1.HookResponseWaiter({ wsUrl: config.wsUrl, apiKey: config.apiKey });
     const server = new mcp_js_1.McpServer({
         name: 'zeph',
         version: getVersion(),
@@ -61,9 +65,9 @@ const createServer = (config) => {
     (0, dismiss_js_1.registerDismissAllTool)(server, client);
     (0, broadcast_js_1.registerBroadcastTool)(server, client, config);
     (0, file_js_1.registerFileTool)(server, client, config);
-    (0, prompt_js_1.registerPromptTool)(server, client, config);
-    (0, input_js_1.registerInputTool)(server, client, config);
-    (0, ask_js_1.registerAskTool)(server, client, config);
+    (0, prompt_js_1.registerPromptTool)(server, client, config, waiter);
+    (0, input_js_1.registerInputTool)(server, client, config, waiter);
+    (0, ask_js_1.registerAskTool)(server, client, config, waiter);
     (0, devices_js_1.registerDevicesResource)(server, client);
     (0, channels_js_1.registerChannelsResource)(server, client);
     return server;

package/dist/poll.d.ts

@@ -1,11 +1,12 @@
 import type { ServerNotification } from '@modelcontextprotocol/sdk/types.js';
 import type { ZephApiClient } from './api-client.js';
 import type { HookEventResponse } from './types.js';
+import type { HookResponseWaiter } from './ws-wait.js';
 export interface PollContext {
     _meta?: {
         progressToken?: string | number;
     };
     sendNotification: (notification: ServerNotification) => Promise<void>;
 }
-export declare const pollForResponse: (client: ZephApiClient, hookId: string, eventId: string, timeoutSeconds: number, ctx: PollContext) => Promise<HookEventResponse | null>;
+export declare const pollForResponse: (client: ZephApiClient, hookId: string, eventId: string, timeoutSeconds: number, ctx: PollContext, waiter?: HookResponseWaiter) => Promise<HookEventResponse | null>;
 //# sourceMappingURL=poll.d.ts.map

package/dist/poll.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"poll.d.ts","sourceRoot":"","sources":["../src/poll.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAC5C,gBAAgB,EAAE,CAAC,YAAY,EAAE,kBAAkB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvE;AAOD,eAAO,MAAM,eAAe,GAC1B,QAAQ,aAAa,EACrB,QAAQ,MAAM,EACd,SAAS,MAAM,EACf,gBAAgB,MAAM,EACtB,KAAK,WAAW,KACf,OAAO,CAAC,iBAAiB,GAAG,IAAI,CA6ClC,CAAC"}
+{"version":3,"file":"poll.d.ts","sourceRoot":"","sources":["../src/poll.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,KAAK,EAAE,kBAAkB,EAAoB,MAAM,cAAc,CAAC;AAEzE,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAC5C,gBAAgB,EAAE,CAAC,YAAY,EAAE,kBAAkB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvE;AAeD,eAAO,MAAM,eAAe,GAC1B,QAAQ,aAAa,EACrB,QAAQ,MAAM,EACd,SAAS,MAAM,EACf,gBAAgB,MAAM,EACtB,KAAK,WAAW,EAChB,SAAS,kBAAkB,KAC1B,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAqElC,CAAC"}

package/dist/poll.js

@@ -3,48 +3,77 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.pollForResponse = void 0;
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 const PROGRESS_INTERVAL_SECONDS = 5;
-const pollForResponse = async (client, hookId, eventId, timeoutSeconds, ctx) => {
+// While the WS fast path is live, polling is only the consistency
+// backstop — 10s is plenty. The WS wake races the sleep, so a live
+// answer still lands in sub-second time (SPEC-AGENT-AWARENESS §S3).
+const WS_BACKSTOP_INTERVAL_MS = 10_000;
+// After a WS wake, REST may briefly still read 'pending' (DDB eventual
+// consistency) — retry tightly but boundedly.
+const POST_WAKE_RETRY_MS = 500;
+const pollForResponse = async (client, hookId, eventId, timeoutSeconds, ctx, waiter) => {
     const progressToken = ctx._meta?.progressToken;
     const startTime = Date.now();
     const timeoutMs = timeoutSeconds * 1000;
     let attempt = 0;
     let lastProgressAt = 0;
-    while (Date.now() - startTime < timeoutMs) {
-        const event = await client.getHookEvent(hookId, eventId);
-        if (event.data.status === 'responded')
-            return event;
-        if (event.data.status === 'cancelled')
-            throw new Error('User cancelled the request');
-        if (event.data.status === 'timed_out')
-            return null;
-        // Only 'pending' should keep us polling. Anything else is server
-        // contract drift — fail fast instead of spinning until the timeout.
-        if (event.data.status !== 'pending') {
-            throw new Error(`Unexpected hook event status: ${String(event.data.status)}`);
-        }
-        // Throttled progress notification (every 5s)
-        if (progressToken !== undefined) {
-            const elapsed = Math.floor((Date.now() - startTime) / 1000);
-            if (elapsed - lastProgressAt >= PROGRESS_INTERVAL_SECONDS) {
-                lastProgressAt = elapsed;
-                await ctx.sendNotification({
-                    method: 'notifications/progress',
-                    params: {
-                        progressToken,
-                        progress: elapsed,
-                        total: timeoutSeconds,
-                        message: `Waiting for user response... (${elapsed}s / ${timeoutSeconds}s)`,
-                    },
-                });
+    let sub;
+    let wsSettled = false;
+    if (waiter?.canWait()) {
+        sub = waiter.subscribe(eventId);
+        void sub.settled.then(() => { wsSettled = true; });
+    }
+    try {
+        while (Date.now() - startTime < timeoutMs) {
+            const event = await client.getHookEvent(hookId, eventId);
+            if (event.data.status === 'responded')
+                return event;
+            if (event.data.status === 'cancelled')
+                throw new Error('User cancelled the request');
+            if (event.data.status === 'timed_out')
+                return null;
+            // Only 'pending' should keep us polling. Anything else is server
+            // contract drift — fail fast instead of spinning until the timeout.
+            if (event.data.status !== 'pending') {
+                throw new Error(`Unexpected hook event status: ${String(event.data.status)}`);
+            }
+            // Throttled progress notification (every 5s)
+            if (progressToken !== undefined) {
+                const elapsed = Math.floor((Date.now() - startTime) / 1000);
+                if (elapsed - lastProgressAt >= PROGRESS_INTERVAL_SECONDS) {
+                    lastProgressAt = elapsed;
+                    await ctx.sendNotification({
+                        method: 'notifications/progress',
+                        params: {
+                            progressToken,
+                            progress: elapsed,
+                            total: timeoutSeconds,
+                            message: `Waiting for user response... (${elapsed}s / ${timeoutSeconds}s)`,
+                        },
+                    });
+                }
             }
+            if (wsSettled) {
+                // Server said settled but this read still saw 'pending' —
+                // eventual consistency. Tight bounded retry until reads agree.
+                await sleep(POST_WAKE_RETRY_MS);
+                attempt++;
+                continue;
+            }
+            // Adaptive interval: poll every 1s while the user is likely still at
+            // their device (first ~60 attempts ≈ 1 min), then back off to 3s for
+            // long waits. The tight 1s window keeps post-tap detection snappy.
+            // With a live WS subscription the cadence relaxes to a backstop and
+            // the wake race handles snappiness instead.
+            const interval = sub?.isConnected()
+                ? WS_BACKSTOP_INTERVAL_MS
+                : (attempt < 60 ? 1000 : 3000);
+            await Promise.race([sleep(interval), sub?.settled ?? new Promise(() => undefined)]);
+            attempt++;
         }
-        // Adaptive interval: poll every 1s while the user is likely still at
-        // their device (first ~60 attempts ≈ 1 min), then back off to 3s for
-        // long waits. The tight 1s window keeps post-tap detection snappy.
-        const interval = attempt < 60 ? 1000 : 3000;
-        await sleep(interval);
-        attempt++;
+        return null;
+    }
+    finally {
+        sub?.dispose();
     }
-    return null;
 };
 exports.pollForResponse = pollForResponse;

package/dist/tools/ask.d.ts

@@ -1,5 +1,6 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { ZephApiClient } from '../api-client.js';
 import { type McpServerConfig } from '../config.js';
-export declare const registerAskTool: (server: McpServer, client: ZephApiClient, config: McpServerConfig) => void;
+import type { HookResponseWaiter } from '../ws-wait.js';
+export declare const registerAskTool: (server: McpServer, client: ZephApiClient, config: McpServerConfig, waiter?: HookResponseWaiter) => void;
 //# sourceMappingURL=ask.d.ts.map

package/dist/tools/ask.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ask.d.ts","sourceRoot":"","sources":["../../src/tools/ask.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAItD,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAwBrE,eAAO,MAAM,eAAe,GAAI,QAAQ,SAAS,EAAE,QAAQ,aAAa,EAAE,QAAQ,eAAe,SAgIhG,CAAC"}
+{"version":3,"file":"ask.d.ts","sourceRoot":"","sources":["../../src/tools/ask.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAItD,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AACrE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAwBxD,eAAO,MAAM,eAAe,GAAI,QAAQ,SAAS,EAAE,QAAQ,aAAa,EAAE,QAAQ,eAAe,EAAE,SAAS,kBAAkB,SAiI7H,CAAC"}

package/dist/tools/ask.js

@@ -21,7 +21,7 @@ const buildAskMarkdown = (title, body, actions) => {
     }
     return parts.join('\n');
 };
-const registerAskTool = (server, client, config) => {
+const registerAskTool = (server, client, config, waiter) => {
     server.registerTool('zeph_ask', {
         description: 'Ask the user a question with optional quick-reply buttons and a text input field. Combines prompt (buttons) and input (text) in a single notification. The user can either tap a button or type a response. Blocks until the user responds or the timeout is reached. Requires ZEPH_HOOK_ID environment variable.',
         annotations: {
@@ -113,7 +113,7 @@ const registerAskTool = (server, client, config) => {
                 files,
                 sessionId: config.sessionId,
             });
-            const event = await (0, poll_js_1.pollForResponse)(client, config.hookId, trigger.data.eventId, timeout, ctx);
+            const event = await (0, poll_js_1.pollForResponse)(client, config.hookId, trigger.data.eventId, timeout, ctx, waiter);
             if (!event) {
                 if (fallback)
                     return (0, error_format_js_1.textResult)({ actionId: fallback, timedOut: true });

package/dist/tools/input.d.ts

@@ -1,5 +1,6 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { ZephApiClient } from '../api-client.js';
 import { type McpServerConfig } from '../config.js';
-export declare const registerInputTool: (server: McpServer, client: ZephApiClient, config: McpServerConfig) => void;
+import type { HookResponseWaiter } from '../ws-wait.js';
+export declare const registerInputTool: (server: McpServer, client: ZephApiClient, config: McpServerConfig, waiter?: HookResponseWaiter) => void;
 //# sourceMappingURL=input.d.ts.map

package/dist/tools/input.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"input.d.ts","sourceRoot":"","sources":["../../src/tools/input.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGtD,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAGrE,eAAO,MAAM,iBAAiB,GAAI,QAAQ,SAAS,EAAE,QAAQ,aAAa,EAAE,QAAQ,eAAe,SAwDlG,CAAC"}
+{"version":3,"file":"input.d.ts","sourceRoot":"","sources":["../../src/tools/input.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGtD,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAErE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAExD,eAAO,MAAM,iBAAiB,GAAI,QAAQ,SAAS,EAAE,QAAQ,aAAa,EAAE,QAAQ,eAAe,EAAE,SAAS,kBAAkB,SAyD/H,CAAC"}

package/dist/tools/input.js

@@ -6,7 +6,7 @@ const error_format_js_1 = require("../error-format.js");
 const poll_js_1 = require("../poll.js");
 const config_js_1 = require("../config.js");
 const sanitize_js_1 = require("../sanitize.js");
-const registerInputTool = (server, client, config) => {
+const registerInputTool = (server, client, config, waiter) => {
     server.registerTool('zeph_input', {
         description: 'Request text input from the user via push notification. The tool blocks until the user responds or the timeout is reached. Requires ZEPH_HOOK_ID environment variable.',
         annotations: {
@@ -41,7 +41,7 @@ const registerInputTool = (server, client, config) => {
                 metadata: { placeholder, inputType },
                 sessionId: config.sessionId,
             });
-            const event = await (0, poll_js_1.pollForResponse)(client, config.hookId, trigger.data.eventId, timeout, ctx);
+            const event = await (0, poll_js_1.pollForResponse)(client, config.hookId, trigger.data.eventId, timeout, ctx, waiter);
             if (!event)
                 return (0, error_format_js_1.timeoutError)(timeout, 'Try again with a longer timeout');
             return (0, error_format_js_1.textResult)({ value: event.data.response?.value ?? '', timedOut: false });

package/dist/tools/prompt.d.ts

@@ -1,5 +1,6 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { ZephApiClient } from '../api-client.js';
 import { type McpServerConfig } from '../config.js';
-export declare const registerPromptTool: (server: McpServer, client: ZephApiClient, config: McpServerConfig) => void;
+import type { HookResponseWaiter } from '../ws-wait.js';
+export declare const registerPromptTool: (server: McpServer, client: ZephApiClient, config: McpServerConfig, waiter?: HookResponseWaiter) => void;
 //# sourceMappingURL=prompt.d.ts.map

package/dist/tools/prompt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../src/tools/prompt.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGtD,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAGrE,eAAO,MAAM,kBAAkB,GAAI,QAAQ,SAAS,EAAE,QAAQ,aAAa,EAAE,QAAQ,eAAe,SAuEnG,CAAC"}
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../src/tools/prompt.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGtD,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAErE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAExD,eAAO,MAAM,kBAAkB,GAAI,QAAQ,SAAS,EAAE,QAAQ,aAAa,EAAE,QAAQ,eAAe,EAAE,SAAS,kBAAkB,SAwEhI,CAAC"}

package/dist/tools/prompt.js

@@ -6,7 +6,7 @@ const error_format_js_1 = require("../error-format.js");
 const poll_js_1 = require("../poll.js");
 const config_js_1 = require("../config.js");
 const sanitize_js_1 = require("../sanitize.js");
-const registerPromptTool = (server, client, config) => {
+const registerPromptTool = (server, client, config, waiter) => {
     server.registerTool('zeph_prompt', {
         description: 'Ask the user to choose from predefined options via push notification. The tool blocks until the user responds or the timeout is reached. Requires ZEPH_HOOK_ID environment variable.',
         annotations: {
@@ -51,7 +51,7 @@ const registerPromptTool = (server, client, config) => {
                 hookType: 'interactive',
                 sessionId: config.sessionId,
             });
-            const event = await (0, poll_js_1.pollForResponse)(client, config.hookId, trigger.data.eventId, timeout, ctx);
+            const event = await (0, poll_js_1.pollForResponse)(client, config.hookId, trigger.data.eventId, timeout, ctx, waiter);
             if (!event) {
                 if (fallback)
                     return (0, error_format_js_1.textResult)({ actionId: fallback, timedOut: true });

package/dist/ws-wait.d.ts

@@ -0,0 +1,61 @@
+/**
+ * WebSocket fast path for hook-response waits (SPEC-AGENT-AWARENESS §S3).
+ *
+ * The server broadcasts `hook.responded` / `hook.cancelled` the moment
+ * the user answers. This module subscribes to that feed so a wait can
+ * wake instantly instead of sitting out its poll interval.
+ *
+ * Trust model: the WS message is a WAKE-UP SIGNAL ONLY. The poll loop
+ * remains the single source of truth — on wake it immediately re-reads
+ * the event over REST and acts on that. A spoofed/garbled/duplicated
+ * frame can therefore cost at most one extra GET, never a wrong answer.
+ * The same property makes degradation trivial: no WebSocket global
+ * (Node < 21), no wsUrl configured, or a dropped socket all just mean
+ * "nobody wakes us early" and the existing poll cadence carries on.
+ *
+ * Connection lifecycle: lazy connect on first subscribe, shared across
+ * concurrent waits, app-level ping every 25 s (API GW $default route
+ * answers 'pong'; native WebSocket has no protocol-ping API), closed
+ * 30 s after the last pending wait ends.
+ */
+export interface WsLike {
+    readyState: number;
+    send(data: string): void;
+    close(): void;
+    addEventListener(type: string, listener: (event: {
+        data?: unknown;
+    }) => void): void;
+}
+export type WsFactory = (url: string) => WsLike;
+export interface WaitSubscription {
+    /** Resolves when the server says this event settled (answer or cancel). */
+    settled: Promise<void>;
+    /** Live socket right now? Drives the caller's poll cadence. */
+    isConnected(): boolean;
+    dispose(): void;
+}
+export interface HookResponseWaiterOptions {
+    wsUrl?: string;
+    apiKey: string;
+    /** Test seam. Defaults to globalThis.WebSocket when present. */
+    factory?: WsFactory;
+}
+export declare class HookResponseWaiter {
+    private readonly wsUrl?;
+    private readonly apiKey;
+    private readonly factory?;
+    private sock;
+    private connected;
+    private readonly pending;
+    private pingTimer;
+    private idleTimer;
+    constructor(opts: HookResponseWaiterOptions);
+    /** False when the fast path can't exist — caller skips subscribe(). */
+    canWait(): boolean;
+    subscribe(eventId: string): WaitSubscription;
+    private ensureSocket;
+    private handleMessage;
+    private scheduleIdleClose;
+    private teardownSocket;
+}
+//# sourceMappingURL=ws-wait.d.ts.map

package/dist/ws-wait.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-wait.d.ts","sourceRoot":"","sources":["../src/ws-wait.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,MAAM,WAAW,MAAM;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,IAAI,IAAI,CAAC;IACd,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAC;KAAE,KAAK,IAAI,GAAG,IAAI,CAAC;CACxF;AAED,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;AAMhD,MAAM,WAAW,gBAAgB;IAC7B,2EAA2E;IAC3E,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,+DAA+D;IAC/D,WAAW,IAAI,OAAO,CAAC;IACvB,OAAO,IAAI,IAAI,CAAC;CACnB;AAED,MAAM,WAAW,yBAAyB;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,OAAO,CAAC,EAAE,SAAS,CAAC;CACvB;AAQD,qBAAa,kBAAkB;IAC3B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAY;IACrC,OAAO,CAAC,IAAI,CAAuB;IACnC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;IACzD,OAAO,CAAC,SAAS,CAA+C;IAChE,OAAO,CAAC,SAAS,CAA8C;gBAEnD,IAAI,EAAE,yBAAyB;IAM3C,uEAAuE;IACvE,OAAO,IAAI,OAAO;IAIlB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB;IAgB5C,OAAO,CAAC,YAAY;IA0BpB,OAAO,CAAC,aAAa;IAerB,OAAO,CAAC,iBAAiB;IAMzB,OAAO,CAAC,cAAc;CAUzB"}

package/dist/ws-wait.js

@@ -0,0 +1,143 @@
+"use strict";
+/**
+ * WebSocket fast path for hook-response waits (SPEC-AGENT-AWARENESS §S3).
+ *
+ * The server broadcasts `hook.responded` / `hook.cancelled` the moment
+ * the user answers. This module subscribes to that feed so a wait can
+ * wake instantly instead of sitting out its poll interval.
+ *
+ * Trust model: the WS message is a WAKE-UP SIGNAL ONLY. The poll loop
+ * remains the single source of truth — on wake it immediately re-reads
+ * the event over REST and acts on that. A spoofed/garbled/duplicated
+ * frame can therefore cost at most one extra GET, never a wrong answer.
+ * The same property makes degradation trivial: no WebSocket global
+ * (Node < 21), no wsUrl configured, or a dropped socket all just mean
+ * "nobody wakes us early" and the existing poll cadence carries on.
+ *
+ * Connection lifecycle: lazy connect on first subscribe, shared across
+ * concurrent waits, app-level ping every 25 s (API GW $default route
+ * answers 'pong'; native WebSocket has no protocol-ping API), closed
+ * 30 s after the last pending wait ends.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HookResponseWaiter = void 0;
+const WS_OPEN = 1;
+const PING_INTERVAL_MS = 25_000;
+const IDLE_CLOSE_MS = 30_000;
+const defaultFactory = () => {
+    const WS = globalThis.WebSocket;
+    if (!WS)
+        return undefined;
+    return (url) => new WS(url);
+};
+class HookResponseWaiter {
+    wsUrl;
+    apiKey;
+    factory;
+    sock = null;
+    connected = false;
+    pending = new Map();
+    pingTimer = null;
+    idleTimer = null;
+    constructor(opts) {
+        this.wsUrl = opts.wsUrl;
+        this.apiKey = opts.apiKey;
+        this.factory = opts.factory ?? defaultFactory();
+    }
+    /** False when the fast path can't exist — caller skips subscribe(). */
+    canWait() {
+        return !!this.wsUrl && !!this.factory;
+    }
+    subscribe(eventId) {
+        let resolveSettled = () => undefined;
+        const settled = new Promise((resolve) => { resolveSettled = resolve; });
+        this.pending.set(eventId, resolveSettled);
+        if (this.idleTimer) {
+            clearTimeout(this.idleTimer);
+            this.idleTimer = null;
+        }
+        this.ensureSocket();
+        return {
+            settled,
+            isConnected: () => this.connected,
+            dispose: () => {
+                this.pending.delete(eventId);
+                if (this.pending.size === 0)
+                    this.scheduleIdleClose();
+            },
+        };
+    }
+    ensureSocket() {
+        if (this.sock || !this.wsUrl || !this.factory)
+            return;
+        try {
+            const sep = this.wsUrl.includes('?') ? '&' : '?';
+            const sock = this.factory(`${this.wsUrl}${sep}apiKey=${encodeURIComponent(this.apiKey)}`);
+            this.sock = sock;
+            sock.addEventListener('open', () => {
+                this.connected = true;
+                this.pingTimer = setInterval(() => {
+                    try {
+                        if (sock.readyState === WS_OPEN)
+                            sock.send(JSON.stringify({ type: 'ping' }));
+                    }
+                    catch { /* socket died mid-send — close handler cleans up */ }
+                }, PING_INTERVAL_MS);
+                // MCP servers are short-lived child processes; an unref'd
+                // timer must not keep one alive after stdio closes.
+                this.pingTimer.unref?.();
+            });
+            sock.addEventListener('message', (event) => this.handleMessage(event.data));
+            const drop = () => this.teardownSocket();
+            sock.addEventListener('close', drop);
+            sock.addEventListener('error', drop);
+        }
+        catch {
+            this.teardownSocket();
+        }
+    }
+    handleMessage(data) {
+        if (typeof data !== 'string')
+            return;
+        try {
+            const msg = JSON.parse(data);
+            if (msg.type !== 'hook.responded' && msg.type !== 'hook.cancelled')
+                return;
+            const eventId = msg.data?.eventId;
+            if (typeof eventId !== 'string')
+                return;
+            // Resolve-and-keep: the poll loop confirms over REST and then
+            // disposes; resolving a missing id is a no-op by design.
+            this.pending.get(eventId)?.();
+        }
+        catch {
+            /* non-JSON frame — ignore */
+        }
+    }
+    scheduleIdleClose() {
+        if (this.idleTimer)
+            clearTimeout(this.idleTimer);
+        this.idleTimer = setTimeout(() => this.teardownSocket(), IDLE_CLOSE_MS);
+        this.idleTimer.unref?.();
+    }
+    teardownSocket() {
+        this.connected = false;
+        if (this.pingTimer) {
+            clearInterval(this.pingTimer);
+            this.pingTimer = null;
+        }
+        if (this.idleTimer) {
+            clearTimeout(this.idleTimer);
+            this.idleTimer = null;
+        }
+        const sock = this.sock;
+        this.sock = null;
+        try {
+            sock?.close();
+        }
+        catch { /* already closed */ }
+        // Pending waits stay pending — they simply lose the fast path and
+        // their poll loops (which check isConnected) tighten back up.
+    }
+}
+exports.HookResponseWaiter = HookResponseWaiter;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeph-to/mcp-server",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "Zeph MCP server — AI agent notifications, prompts, and input via MCP protocol",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",