@zeph-to/mcp-server 1.11.3 → 1.13.0

package/README.md

@@ -186,6 +186,10 @@ timeout:     120    (seconds, default: 120, max: 600)
 
 Returns: `{ value: "feat: add clipboard sync", timedOut: false }`
 
+### Client timeouts
+
+`zeph_ask`, `zeph_prompt`, and `zeph_input` block until the user responds, up to their `timeout` (max 600s). That whole time the MCP request stays open. To keep the client from giving up early, the server emits a `notifications/progress` every 5s while waiting. Clients must either set a per-request timeout above the tool's `timeout`, or reset their timeout on progress notifications. Claude Code does the latter by default.
+
 ## Resources
 
 ### zeph://devices

package/dist/api-client.d.ts

@@ -1,5 +1,5 @@
 import type { McpServerConfig } from './config.js';
-import type { PushResponse, HookTriggerResponse, HookEventResponse, DevicesResponse, PushListResponse, DismissResponse, ChannelsResponse, UploadRequestResponse } from './types.js';
+import type { PushResponse, HookTriggerResponse, HookEventResponse, DevicesResponse, PushListResponse, DismissResponse, ChannelsResponse, UploadRequestResponse, AttachedFile } from './types.js';
 export declare class ApiError extends Error {
     readonly code: string;
     readonly status: number;
@@ -18,14 +18,7 @@ export declare class ZephApiClient {
         targetDeviceId?: string;
         channelId?: string;
         sessionId?: string;
-        files?: {
-            fileKey: string;
-            fileName: string;
-            fileSize: number;
-            fileType: string;
-            iv?: string;
-            encryptedKey?: string;
-        }[];
+        files?: AttachedFile[];
         isEncrypted?: boolean;
         encryptedKey?: string;
         senderPublicKey?: string;
@@ -41,14 +34,7 @@ export declare class ZephApiClient {
         fallback?: string;
         metadata?: Record<string, unknown>;
         hookType?: 'one-way' | 'interactive' | 'input' | 'combo';
-        files?: {
-            fileKey: string;
-            fileName: string;
-            fileSize: number;
-            fileType: string;
-            iv?: string;
-            encryptedKey?: string;
-        }[];
+        files?: AttachedFile[];
         sessionId?: string;
     }): Promise<HookTriggerResponse>;
     getHookEvent(hookId: string, eventId: string): Promise<HookEventResponse>;

package/dist/api-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAEV,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAEpB,qBAAa,QAAS,SAAQ,KAAK;aAGf,IAAI,EAAE,MAAM;aACZ,MAAM,EAAE,MAAM;gBAF9B,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM;CAKjC;AAKD,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,MAAM,EAAE,eAAe;IAK7B,QAAQ,CAAC,MAAM,EAAE;QACrB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAC;YAAC,EAAE,CAAC,EAAE,MAAM,CAAC;YAAC,YAAY,CAAC,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;QACxH,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B,GAAG,OAAO,CAAC,YAAY,CAAC;IAInB,WAAW,CACf,MAAM,EAAE,MAAM,EACd,MAAM,EAAE;QACN,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;QAC1C,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACnC,QAAQ,CAAC,EAAE,SAAS,GAAG,aAAa,GAAG,OAAO,GAAG,OAAO,CAAC;QACzD,KAAK,CAAC,EAAE;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAC;YAAC,EAAE,CAAC,EAAE,MAAM,CAAC;YAAC,YAAY,CAAC,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;QACxH,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GACA,OAAO,CAAC,mBAAmB,CAAC;IAIzB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAIzE,WAAW,IAAI,OAAO,CAAC,eAAe,CAAC;IAIvC,UAAU,CAAC,MAAM,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAQjF,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAIrD,gBAAgB,IAAI,OAAO,CAAC,eAAe,CAAC;IAI5C,YAAY,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAIzC,aAAa,CAAC,MAAM,EAAE;QAC1B,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAI5B,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAc7E,OAAO;CA0CtB"}
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAEV,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,qBAAqB,EACrB,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,qBAAa,QAAS,SAAQ,KAAK;aAGf,IAAI,EAAE,MAAM;aACZ,MAAM,EAAE,MAAM;gBAF9B,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM;CAKjC;AAKD,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,MAAM,EAAE,eAAe;IAK7B,QAAQ,CAAC,MAAM,EAAE;QACrB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;QACvB,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B,GAAG,OAAO,CAAC,YAAY,CAAC;IAInB,WAAW,CACf,MAAM,EAAE,MAAM,EACd,MAAM,EAAE;QACN,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;QAC1C,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACnC,QAAQ,CAAC,EAAE,SAAS,GAAG,aAAa,GAAG,OAAO,GAAG,OAAO,CAAC;QACzD,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;QACvB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GACA,OAAO,CAAC,mBAAmB,CAAC;IAIzB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAIzE,WAAW,IAAI,OAAO,CAAC,eAAe,CAAC;IAIvC,UAAU,CAAC,MAAM,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAQjF,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAIrD,gBAAgB,IAAI,OAAO,CAAC,eAAe,CAAC;IAI5C,YAAY,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAIzC,aAAa,CAAC,MAAM,EAAE;QAC1B,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAI5B,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAc7E,OAAO;CA0CtB"}

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;AAgGF,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

@@ -43,22 +43,27 @@ const loadFileConfig = () => {
         return {};
     }
 };
-/** Detect Claude Code session ID from ~/.claude/projects/{projectHash}/{sessionId}/ */
-const detectClaudeSessionId = () => {
+const SESSION_UUID_RE = /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/;
+/**
+ * Detect the Claude Code session ID for `projectDir`. Claude Code writes
+ * one transcript per session at `~/.claude/projects/<projectHash>/<uuid>.jsonl`
+ * where the hash is the project path with `/` replaced by `-`. We pick the
+ * most recently modified transcript — that's the live session.
+ */
+const detectClaudeSessionId = (projectDir) => {
     try {
-        const projectDir = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
         const projectHash = projectDir.replace(/\//g, '-');
         const sessionsDir = (0, path_1.join)((0, os_1.homedir)(), '.claude', 'projects', projectHash);
         let latest;
-        for (const name of (0, fs_1.readdirSync)(sessionsDir)) {
-            if (!/^[0-9a-f]{8}-[0-9a-f]{4}-/.test(name))
+        for (const entry of (0, fs_1.readdirSync)(sessionsDir)) {
+            const match = SESSION_UUID_RE.exec(entry);
+            if (!match)
                 continue;
-            const fullPath = (0, path_1.join)(sessionsDir, name);
-            const stat = (0, fs_1.statSync)(fullPath);
-            if (!stat.isDirectory())
+            const stat = (0, fs_1.statSync)((0, path_1.join)(sessionsDir, entry));
+            if (!stat.isFile())
                 continue;
             if (!latest || stat.mtimeMs > latest.mtime) {
-                latest = { name, mtime: stat.mtimeMs };
+                latest = { name: match[1], mtime: stat.mtimeMs };
             }
         }
         return latest?.name;
@@ -125,16 +130,17 @@ const loadConfig = () => {
     if (!apiKey) {
         throw new Error('ZEPH_API_KEY not found. Run "npx @zeph-to/cli install" or set ZEPH_API_KEY env var.');
     }
-    const sessionId = resolvedEnv('ZEPH_SESSION_ID') ?? detectClaudeSessionId() ?? `sess_${(0, crypto_1.randomBytes)(12).toString('base64url')}`;
-    const projectDir = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+    const projectDir = detectProjectDir();
+    const sessionId = resolvedEnv('ZEPH_SESSION_ID') ?? detectClaudeSessionId(projectDir) ?? `sess_${(0, crypto_1.randomBytes)(12).toString('base64url')}`;
     writeSessionCache(sessionId, projectDir);
     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,
-        projectName: projectNameFromDir(detectProjectDir()),
+        projectName: projectNameFromDir(projectDir),
     };
 };
 exports.loadConfig = loadConfig;

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");
@@ -22,7 +23,7 @@ const channels_js_1 = require("./resources/channels.js");
 const getVersion = () => {
     try {
         const pkg = JSON.parse((0, fs_1.readFileSync)((0, path_1.join)(__dirname, '..', 'package.json'), 'utf-8'));
-        return pkg.version;
+        return typeof pkg.version === 'string' ? pkg.version : '0.0.0';
     }
     catch {
         return '0.0.0';
@@ -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,10 +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: any) => Promise<void>;
+    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,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;IAE5C,gBAAgB,EAAE,CAAC,YAAY,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACxD;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;AAGtD,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/types.d.ts

@@ -86,6 +86,14 @@ export interface UploadRequestResponse {
         uploadUrl: string;
     };
 }
+export interface AttachedFile {
+    fileKey: string;
+    fileName: string;
+    fileSize: number;
+    fileType: string;
+    iv?: string;
+    encryptedKey?: string;
+}
 export interface ToolError {
     error: string;
     message: string;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE;QACJ,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE;QACJ,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE;QACJ,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC;QAC5D,QAAQ,CAAC,EAAE;YACT,QAAQ,CAAC,EAAE,MAAM,CAAC;YAClB,KAAK,CAAC,EAAE,MAAM,CAAC;YACf,iBAAiB,CAAC,EAAE,MAAM,CAAC;SAC5B,CAAC;KACH,CAAC;CACH;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,YAAY,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,UAAU,EAAE,CAAC;IACnB,UAAU,EAAE;QACV,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,OAAO,CAAC;KAClB,CAAC;CACH;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE;QACJ,SAAS,EAAE,OAAO,GAAG,MAAM,CAAC;QAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,aAAa,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE;QACJ,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

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.11.3",
+  "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",