@hwip/mcp-server 0.0.0-stage → 0.1.0

package/dist/ws-wait.js

@@ -0,0 +1,200 @@
+"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 < 22), 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. A socket that drops while a wait is
+ * pending is opened again after 1 s, doubling to 30 s.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HookResponseWaiter = exports.wsFastPathNotice = void 0;
+const WS_OPEN = 1;
+const PING_INTERVAL_MS = 25_000;
+const IDLE_CLOSE_MS = 30_000;
+const RECONNECT_FIRST_MS = 1_000;
+const RECONNECT_MAX_MS = 30_000;
+const defaultFactory = () => {
+    const WS = globalThis.WebSocket;
+    if (!WS)
+        return undefined;
+    return (url) => new WS(url);
+};
+/**
+ * A start-up line when hwip_ask cannot be woken over the WebSocket, or null. Without it the
+ * fast path is off in silence and every answer waits for the next poll (`poll.ts`).
+ */
+const wsFastPathNotice = (wsUrl, hasWebSocket = !!defaultFactory()) => {
+    if (!wsUrl) {
+        return '[WS] No WebSocket URL for this API — hwip_ask waits by polling. Set "wsUrl" in ~/.hwip/config.json (`hwip login` writes it).';
+    }
+    if (!hasWebSocket) {
+        return `[WS] Node ${process.versions.node} has no WebSocket — hwip_ask waits by polling. Node 22 or later answers at once.`;
+    }
+    return null;
+};
+exports.wsFastPathNotice = wsFastPathNotice;
+class HookResponseWaiter {
+    wsUrl;
+    apiKey;
+    factory;
+    sock = null;
+    connected = false;
+    pending = new Map();
+    pingTimer = null;
+    idleTimer = null;
+    reconnectTimer = null;
+    /** Reconnects since the socket was last open: the next one waits 2^n s, up to 30 s. */
+    reconnects = 0;
+    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;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        try {
+            const sep = this.wsUrl.includes('?') ? '&' : '?';
+            // KNOWN TRADEOFF: apiKey rides the query string — the WHATWG
+            // WebSocket (Node 22+ global) can't set headers, and the API GW
+            // $connect route authenticates on the query param. It can land in
+            // gateway access logs; first-message auth needs a server change.
+            const sock = this.factory(`${this.wsUrl}${sep}apiKey=${encodeURIComponent(this.apiKey)}`);
+            this.sock = sock;
+            sock.addEventListener('open', () => {
+                if (this.sock !== sock)
+                    return; // stale socket — already replaced
+                this.connected = true;
+                this.reconnects = 0;
+                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));
+            // Guard against stale events: 'error' and 'close' both fire on a
+            // dying socket, and a new subscribe() may have already created a
+            // replacement between them — a late event from the old socket
+            // must not tear down the new one.
+            const drop = () => {
+                if (this.sock !== sock)
+                    return;
+                this.teardownSocket();
+                this.scheduleReconnect();
+            };
+            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 */
+        }
+    }
+    /** A wait still pending gets its fast path back; the poll loop covers the gap. */
+    scheduleReconnect() {
+        if (this.pending.size === 0 || this.reconnectTimer)
+            return;
+        const delay = Math.min(RECONNECT_FIRST_MS * 2 ** this.reconnects, RECONNECT_MAX_MS);
+        this.reconnects += 1;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            if (this.pending.size > 0)
+                this.ensureSocket();
+        }, delay);
+        this.reconnectTimer.unref?.();
+    }
+    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;
+        }
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = 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,72 @@
 {
   "name": "@hwip/mcp-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Hwip MCP server — AI agent notifications, prompts, and input via MCP protocol",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "hwip-mcp": "./dist/index.js"
+  },
+  "engines": {
+    "node": ">=18.17.0"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "!dist/**/*.tsbuildinfo",
+    "NOTICE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.31.0",
+    "zod": "^3.25.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.8.0",
+    "vitest": "^4.1.11"
+  },
+  "release": {
+    "branches": [
+      "main"
+    ],
+    "plugins": [
+      "@semantic-release/commit-analyzer",
+      "@semantic-release/release-notes-generator",
+      "@semantic-release/npm",
+      "@semantic-release/github"
+    ]
+  },
+  "author": "Hwip <dev@hwip.app>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hwipit/mcp-server"
+  },
+  "homepage": "https://github.com/hwipit/mcp-server",
+  "bugs": {
+    "url": "https://github.com/hwipit/mcp-server/issues"
+  },
+  "keywords": [
+    "hwip",
+    "mcp",
+    "ai",
+    "notification",
+    "prompt",
+    "model-context-protocol",
+    "claude",
+    "ai-agent",
+    "devtools",
+    "cursor",
+    "gemini"
+  ],
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}