@hwip/mcp-server 0.0.0-stage → 0.1.0

package/dist/error-format.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatToolError = exports.hookNotConfiguredError = exports.errorResult = exports.textResult = void 0;
+const api_client_js_1 = require("./api-client.js");
+const poll_js_1 = require("./poll.js");
+const textResult = (obj) => ({
+    content: [{ type: 'text', text: JSON.stringify(obj) }],
+});
+exports.textResult = textResult;
+const errorResult = (obj) => ({
+    content: [{ type: 'text', text: JSON.stringify(obj) }],
+    isError: true,
+});
+exports.errorResult = errorResult;
+const hookNotConfiguredError = () => (0, exports.errorResult)({
+    error: 'HOOK_NOT_CONFIGURED',
+    message: 'No hook id: neither HWIP_HOOK_ID nor hookId in ~/.hwip/config.json is set, so a question cannot reach the phone',
+    suggestion: 'Ask in this chat instead, and use hwip_notify if the user should be pinged about it. '
+        + 'To enable hwip_ask, the user runs `hwip login` (it writes hookId to ~/.hwip/config.json) or sets HWIP_HOOK_ID.',
+});
+exports.hookNotConfiguredError = hookNotConfiguredError;
+/** What the agent should do after each way an ask can end unanswered. */
+const ASK_SUGGESTIONS = {
+    CANCELLED: 'The user dismissed this question on purpose. Do not ask it again — carry on without it, or ask something different.',
+    POLL_FAILED: 'Do not re-ask blindly — the question may still be on the phone and a repeat pushes a duplicate. Tell the user in the terminal what you were waiting on.',
+    ABORTED: 'The tool call was cancelled before the user answered.',
+};
+const formatToolError = (err) => {
+    const toolError = {
+        error: 'UNKNOWN',
+        message: err instanceof Error ? err.message : String(err),
+    };
+    if (err instanceof poll_js_1.AskError) {
+        toolError.error = err.code;
+        if (err.eventId)
+            toolError.eventId = err.eventId;
+        toolError.suggestion = ASK_SUGGESTIONS[err.code];
+    }
+    else if (err instanceof api_client_js_1.ApiError) {
+        toolError.error = err.code;
+        toolError.message = err.message;
+        if (err.code === 'QUOTA_EXCEEDED') {
+            toolError.suggestion = 'Monthly quota exceeded. Upgrade plan for higher limits';
+        }
+        else if (err.code === 'UNAUTHORIZED') {
+            toolError.suggestion = 'Check HWIP_API_KEY environment variable or ~/.hwip/config.json';
+        }
+        else if (err.code === 'HOOK_DISABLED') {
+            toolError.suggestion = 'Enable the Hook in Settings → Hooks';
+        }
+        else if (err.code === 'NETWORK_ERROR') {
+            toolError.suggestion = err.causeCode === 'ERR_INVALID_URL'
+                ? 'Do not retry. The configured API base URL is not an address; the user has to correct HWIP_BASE_URL (or baseUrl in ~/.hwip/config.json)'
+                : 'No connection to the hwip API. Retry once later; if it keeps failing, carry on in the chat';
+        }
+        else if (err.code === 'INVALID_UPLOAD_URL') {
+            toolError.suggestion = 'Do not retry, and do not correct HWIP_BASE_URL for it — the upload address came from the hwip API\'s own reply, not from the configuration. Tell the user in the terminal which file was not uploaded';
+        }
+        else if (err.code === 'REDIRECT_REFUSED') {
+            toolError.suggestion = 'Do not retry. The configured API base URL redirects somewhere else; the user has to correct HWIP_BASE_URL (or baseUrl in ~/.hwip/config.json)';
+        }
+        else if (err.code === 'API_TIMEOUT') {
+            toolError.suggestion = 'The hwip API was slow, not the user. If this was a send, check hwip_list before sending again — it may have gone out';
+        }
+        else if (err.code === 'BAD_RESPONSE') {
+            toolError.suggestion = 'The answer was not the hwip API\'s own reply. If this was a send, check hwip_list before sending again — it may have gone out';
+        }
+        else if (err.code === 'SEND_UNCONFIRMED') {
+            toolError.suggestion = 'Check hwip_list before asking again — the question may have gone out';
+        }
+        else if (err.code === 'FORBIDDEN') {
+            toolError.suggestion = 'Check the API key scopes — a key made with the MCP preset covers every tool';
+        }
+    }
+    return (0, exports.errorResult)(toolError);
+};
+exports.formatToolError = formatToolError;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const config_js_1 = require("./config.js");
+const crypto_js_1 = require("./crypto.js");
+const server_js_1 = require("./server.js");
+const ws_wait_js_1 = require("./ws-wait.js");
+const main = async () => {
+    const config = (0, config_js_1.loadConfig)();
+    // Read only to report: the variable used to outrank the config file, and
+    // removing it without a word would leave the same silence behind.
+    const staleWsEnv = (0, config_js_1.legacyWsEnvNotice)();
+    if (staleWsEnv)
+        console.error(staleWsEnv);
+    const noFastPath = (0, ws_wait_js_1.wsFastPathNotice)(config.wsUrl);
+    if (noFastPath)
+        console.error(noFastPath);
+    // Load or create this host's keypair. Runs once per process and caches.
+    // Not awaited: a send waits for it instead (`cryptoReady`).
+    (0, crypto_js_1.initCrypto)(config.apiKey).then(() => console.error((0, crypto_js_1.cryptoStatusLine)()), (err) => console.error('[Crypto] E2E encryption unavailable:', err));
+    const server = (0, server_js_1.createServer)(config);
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error('Hwip MCP Server running on stdio');
+};
+main().catch((err) => {
+    console.error('Fatal error:', err);
+    process.exit(1);
+});

package/dist/key-changes.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Devices whose key changed since this computer pinned them, kept until a person has been shown it (twin of the cli's
+ * `src/key-changes.ts`, same contract).
+ *
+ * Whoever replaces a pin — the cli's notify, ask, agent send and listener, and this server — writes the change here,
+ * under the trust file's lock (`withTrustLock`). This server's stderr reaches nobody, and once the pin holds the new
+ * key no one sees the change again. So it waits beside the pins until a surface a person reads takes it: here that
+ * is the result of `hwip_notify`, `hwip_file`, `hwip_ask` and `hwip_agent_send`, which ends with a `Note:` line.
+ *
+ * THE CONTRACT (cli and mcp-server write and read it, the plugin reads it — changing it is a cross-repo change):
+ *
+ *   path  key-changes.json beside trusted-devices.json (~/.hwip/key-changes.json), 0600
+ *   body  {"v":1,"changes":[{"deviceId":"<device id>","at":"<ISO 8601 UTC>","name":"<nickname, optional>"}]}
+ *         one entry per device, updated in place; at most 64, the oldest dropped
+ *   take  under the same lock as the writers (trusted-devices.lock), rename to key-changes.json.<pid>.taken, read,
+ *         delete: a writer cannot put back what was taken, and of two readers only the one whose rename wins shows
+ *         the changes. A record that does not parse, or another `v`, reads as none.
+ */
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+export interface KeyChange {
+    deviceId: string;
+    /** When the pin was replaced, ISO 8601 UTC. */
+    at: string;
+    /** The device's nickname as the account lists it. */
+    name?: string;
+}
+export declare const MAX_KEY_CHANGES = 64;
+export declare const keyChangesPath: (trustPath: string) => string;
+/**
+ * Add `changes` to the record. Call it inside the `withTrustLock` section that replaced the pins: that lock is what
+ * keeps two writers from dropping each other's entry, and a taker from seeing an entry twice. Throws nothing: false
+ * means the record could not be written, and the caller holds the changes instead (`holdKeyChanges`).
+ */
+export declare const recordKeyChanges: (trustPath: string, changes: KeyChange[]) => boolean;
+export declare const holdKeyChanges: (changes: KeyChange[]) => void;
+/** The changes nobody has been shown yet, and the record gone. A lock that cannot be had leaves the record for the next result. */
+export declare const takeKeyChanges: (trustPath: string, opts?: {
+    waitMs?: number;
+}) => KeyChange[];
+export declare const noteOnce: (text: string) => void;
+/** One line for a person; the caller adds its prefix. */
+export declare const describeKeyChange: (change: KeyChange) => string;
+/**
+ * `result` ending with one `Note:` text block per change not shown yet and per `noteOnce` line, which are then cleared.
+ * Only text: a tool's JSON keeps its keys.
+ */
+export declare const withKeyChangeNote: (result: CallToolResult, trustPath?: string) => CallToolResult;
+/** A tool handler whose result carries the key changes not shown yet (`withKeyChangeNote`). */
+export declare const notingKeyChanges: <A extends unknown[]>(handler: (...args: A) => Promise<CallToolResult>) => (...args: A) => Promise<CallToolResult>;
+//# sourceMappingURL=key-changes.d.ts.map

package/dist/key-changes.js

@@ -0,0 +1,163 @@
+"use strict";
+/**
+ * Devices whose key changed since this computer pinned them, kept until a person has been shown it (twin of the cli's
+ * `src/key-changes.ts`, same contract).
+ *
+ * Whoever replaces a pin — the cli's notify, ask, agent send and listener, and this server — writes the change here,
+ * under the trust file's lock (`withTrustLock`). This server's stderr reaches nobody, and once the pin holds the new
+ * key no one sees the change again. So it waits beside the pins until a surface a person reads takes it: here that
+ * is the result of `hwip_notify`, `hwip_file`, `hwip_ask` and `hwip_agent_send`, which ends with a `Note:` line.
+ *
+ * THE CONTRACT (cli and mcp-server write and read it, the plugin reads it — changing it is a cross-repo change):
+ *
+ *   path  key-changes.json beside trusted-devices.json (~/.hwip/key-changes.json), 0600
+ *   body  {"v":1,"changes":[{"deviceId":"<device id>","at":"<ISO 8601 UTC>","name":"<nickname, optional>"}]}
+ *         one entry per device, updated in place; at most 64, the oldest dropped
+ *   take  under the same lock as the writers (trusted-devices.lock), rename to key-changes.json.<pid>.taken, read,
+ *         delete: a writer cannot put back what was taken, and of two readers only the one whose rename wins shows
+ *         the changes. A record that does not parse, or another `v`, reads as none.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.notingKeyChanges = exports.withKeyChangeNote = exports.describeKeyChange = exports.noteOnce = exports.takeKeyChanges = exports.holdKeyChanges = exports.recordKeyChanges = exports.keyChangesPath = exports.MAX_KEY_CHANGES = void 0;
+const node_fs_1 = require("node:fs");
+const node_crypto_1 = require("node:crypto");
+const node_path_1 = require("node:path");
+const trust_pins_js_1 = require("./trust-pins.js");
+exports.MAX_KEY_CHANGES = 64;
+const NAME_MAX = 80;
+const ISO_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/;
+const keyChangesPath = (trustPath) => (0, node_path_1.join)((0, node_path_1.dirname)(trustPath), 'key-changes.json');
+exports.keyChangesPath = keyChangesPath;
+/** The relay writes nicknames: no control, direction or zero-width characters, one space per run, 80 characters at most. */
+const cleanName = (name) => {
+    if (typeof name !== 'string')
+        return undefined;
+    const plain = name.replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]|\p{Cf}/gu, '').replace(/\s+/g, ' ').trim();
+    const chars = Array.from(plain);
+    if (chars.length === 0)
+        return undefined;
+    return chars.length > NAME_MAX ? chars.slice(0, NAME_MAX).join('') : plain;
+};
+const entryOf = (raw) => {
+    if (typeof raw !== 'object' || raw === null)
+        return null;
+    const { deviceId, at, name } = raw;
+    if (typeof deviceId !== 'string' || !trust_pins_js_1.DEVICE_ID.test(deviceId) || typeof at !== 'string' || !ISO_UTC.test(at))
+        return null;
+    const clean = cleanName(name);
+    return clean === undefined ? { deviceId, at } : { deviceId, at, name: clean };
+};
+const readChanges = (path) => {
+    let raw;
+    try {
+        raw = JSON.parse((0, node_fs_1.readFileSync)(path, 'utf-8'));
+    }
+    catch {
+        return [];
+    }
+    const { v, changes } = (raw ?? {});
+    if (v !== 1 || !Array.isArray(changes))
+        return [];
+    return changes.map(entryOf).filter((c) => c !== null).slice(-exports.MAX_KEY_CHANGES);
+};
+/** One entry per device, the later one in place of the earlier. */
+const merge = (list, changes) => {
+    for (const change of changes) {
+        const entry = entryOf(change);
+        if (!entry)
+            continue;
+        const at = list.findIndex((c) => c.deviceId === entry.deviceId);
+        if (at >= 0)
+            list[at] = entry;
+        else
+            list.push(entry);
+    }
+    return list.slice(-exports.MAX_KEY_CHANGES);
+};
+/**
+ * Add `changes` to the record. Call it inside the `withTrustLock` section that replaced the pins: that lock is what
+ * keeps two writers from dropping each other's entry, and a taker from seeing an entry twice. Throws nothing: false
+ * means the record could not be written, and the caller holds the changes instead (`holdKeyChanges`).
+ */
+const recordKeyChanges = (trustPath, changes) => {
+    if (changes.length === 0)
+        return true;
+    const path = (0, exports.keyChangesPath)(trustPath);
+    const list = merge(readChanges(path), changes);
+    const temp = `${path}.${process.pid}.${(0, node_crypto_1.randomBytes)(6).toString('hex')}.tmp`;
+    try {
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true, mode: 0o700 });
+        (0, node_fs_1.writeFileSync)(temp, `${JSON.stringify({ v: 1, changes: list })}\n`, { mode: 0o600, flag: 'wx' });
+        (0, node_fs_1.renameSync)(temp, path);
+        return true;
+    }
+    catch {
+        try {
+            (0, node_fs_1.rmSync)(temp, { force: true });
+        }
+        catch { /* the folder is not there either */ }
+        return false;
+    }
+};
+exports.recordKeyChanges = recordKeyChanges;
+/** Changes this process saw but could not record (the pin or the record was not written): shown by its next result. */
+let held = [];
+const holdKeyChanges = (changes) => {
+    held = merge(held, changes);
+};
+exports.holdKeyChanges = holdKeyChanges;
+const takeRecord = (path) => {
+    const taken = `${path}.${process.pid}.taken`;
+    try {
+        (0, node_fs_1.renameSync)(path, taken);
+    }
+    catch {
+        return [];
+    }
+    try {
+        return readChanges(taken);
+    }
+    finally {
+        (0, node_fs_1.rmSync)(taken, { force: true });
+    }
+};
+/** The changes nobody has been shown yet, and the record gone. A lock that cannot be had leaves the record for the next result. */
+const takeKeyChanges = (trustPath, opts = {}) => {
+    const mine = held;
+    held = [];
+    const path = (0, exports.keyChangesPath)(trustPath);
+    // Most results find nothing: no lock for them.
+    if (!(0, node_fs_1.existsSync)(path))
+        return mine;
+    const done = (0, trust_pins_js_1.withTrustLock)(trustPath, () => takeRecord(path), opts);
+    return done.locked ? merge(mine, done.value) : mine;
+};
+exports.takeKeyChanges = takeKeyChanges;
+/** Other lines for the next result, each said once per process: a failure that repeats on every send is said the first time. */
+const said = new Set();
+let notes = [];
+const noteOnce = (text) => {
+    if (said.has(text))
+        return;
+    said.add(text);
+    notes.push(text);
+};
+exports.noteOnce = noteOnce;
+/** One line for a person; the caller adds its prefix. */
+const describeKeyChange = (change) => `${change.name ?? change.deviceId} changed its encryption key — the new key is trusted. If you did not expect this, check it with: hwip trust`;
+exports.describeKeyChange = describeKeyChange;
+/**
+ * `result` ending with one `Note:` text block per change not shown yet and per `noteOnce` line, which are then cleared.
+ * Only text: a tool's JSON keeps its keys.
+ */
+const withKeyChangeNote = (result, trustPath = trust_pins_js_1.TRUST_PATH) => {
+    const lines = [...(0, exports.takeKeyChanges)(trustPath).map(exports.describeKeyChange), ...notes];
+    notes = [];
+    if (lines.length === 0)
+        return result;
+    return { ...result, content: [...result.content, ...lines.map((line) => ({ type: 'text', text: `Note: ${line}` }))] };
+};
+exports.withKeyChangeNote = withKeyChangeNote;
+/** A tool handler whose result carries the key changes not shown yet (`withKeyChangeNote`). */
+const notingKeyChanges = (handler) => async (...args) => (0, exports.withKeyChangeNote)(await handler(...args));
+exports.notingKeyChanges = notingKeyChanges;

package/dist/mime.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared MIME-type inference for file/notify/ask payloads.
+ *
+ * Kept in one place so different tools don't produce inconsistent types
+ * for the same extension (e.g. `.csv` ending up as text/plain in one
+ * code path and text/csv in another).
+ */
+export declare const EXT_TO_MIME: Record<string, string>;
+export declare const inferMimeType: (fileName: string) => string;
+/**
+ * The Content-Type header an upload PUT has to carry, whatever its body: the address is signed for it,
+ * and S3 answers 403 to any other. It is the type as sent to `POST /files/upload-request`, with
+ * `; charset=utf-8` added to `text/*` that has no charset (the hwip server's `uploadContentType`).
+ */
+export declare const uploadContentType: (contentType: string) => string;
+//# sourceMappingURL=mime.d.ts.map

package/dist/mime.js

@@ -0,0 +1,58 @@
+"use strict";
+/**
+ * Shared MIME-type inference for file/notify/ask payloads.
+ *
+ * Kept in one place so different tools don't produce inconsistent types
+ * for the same extension (e.g. `.csv` ending up as text/plain in one
+ * code path and text/csv in another).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uploadContentType = exports.inferMimeType = exports.EXT_TO_MIME = void 0;
+exports.EXT_TO_MIME = {
+    txt: 'text/plain',
+    log: 'text/plain',
+    md: 'text/markdown',
+    json: 'application/json',
+    csv: 'text/csv',
+    yaml: 'text/yaml',
+    yml: 'text/yaml',
+    ts: 'text/typescript',
+    js: 'text/javascript',
+    py: 'text/x-python',
+    sh: 'text/x-shellscript',
+    // Keep this image set in sync with IMAGE_EXTENSIONS in the Hwip client
+    // (`libs/shared/src/utils/file.ts`) — an extension the client calls an image
+    // but this map doesn't will be labelled text/plain and decoded as UTF-8 on
+    // open, which corrupts it. Separate repos, so nothing enforces the match.
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    heic: 'image/heic',
+    heif: 'image/heif',
+    bmp: 'image/bmp',
+    avif: 'image/avif',
+    ico: 'image/x-icon',
+    tiff: 'image/tiff',
+    tif: 'image/tiff',
+    // No html, xml or svg entry on purpose: these are documents a browser runs, and the
+    // clients open decrypted attachments from a same-origin blob URL. The server also refuses
+    // them as an upload type (they would run on the bucket's origin). They fall through to
+    // text/plain, which the text viewer handles fine.
+    pdf: 'application/pdf',
+};
+const inferMimeType = (fileName) => {
+    const ext = fileName.split('.').pop()?.toLowerCase();
+    return exports.EXT_TO_MIME[ext ?? ''] ?? 'text/plain';
+};
+exports.inferMimeType = inferMimeType;
+/**
+ * The Content-Type header an upload PUT has to carry, whatever its body: the address is signed for it,
+ * and S3 answers 403 to any other. It is the type as sent to `POST /files/upload-request`, with
+ * `; charset=utf-8` added to `text/*` that has no charset (the hwip server's `uploadContentType`).
+ */
+const uploadContentType = (contentType) => contentType.startsWith('text/') && !contentType.includes('charset')
+    ? `${contentType}; charset=utf-8`
+    : contentType;
+exports.uploadContentType = uploadContentType;

package/dist/peer-key.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Which key to believe for a device that signs something with its own key
+ * (twin of the cli's `src/peer-key.ts`, same rules).
+ *
+ * An envelope that opens only shows its sender held *a* key (push v1 carries
+ * the sender's public key unsigned), so the reader must say whose key it
+ * expects. This answers that for one device id: the key the account's device
+ * list registers for it. Trust never refuses (F16): the key is pinned the first
+ * time it is seen, and a changed key replaces its pin with one warning
+ * (`observeDevices`, `~/.hwip/trusted-devices.json`).
+ */
+export type PeerKeyRefusal = 
+/** Not a device id, or not in the account's device list. */
+'unlisted'
+/** The device list could not be fetched. */
+ | 'devices_unavailable';
+export type PeerKey = {
+    key: string;
+} | {
+    refused: PeerKeyRefusal;
+};
+export interface PeerKeyDeps {
+    /** The key the account's device list registers for `deviceId`: null when none is listed, a rejection when the list cannot be had. */
+    registeredKey: (deviceId: string) => Promise<string | null>;
+    /** The listener's state file. Defaults to `~/.hwip/trusted-devices.json`. */
+    trustPath?: string;
+    /** This machine. Asking about oneself needs no list. */
+    self?: {
+        deviceId: string;
+        publicKey: string;
+    };
+    /** This machine's id when `self` is left out so its key cannot vouch: it is still never pinned. */
+    selfId?: string;
+}
+export declare const peerKeyOf: (deviceId: string, deps: PeerKeyDeps) => Promise<PeerKey>;
+//# sourceMappingURL=peer-key.d.ts.map

package/dist/peer-key.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * Which key to believe for a device that signs something with its own key
+ * (twin of the cli's `src/peer-key.ts`, same rules).
+ *
+ * An envelope that opens only shows its sender held *a* key (push v1 carries
+ * the sender's public key unsigned), so the reader must say whose key it
+ * expects. This answers that for one device id: the key the account's device
+ * list registers for it. Trust never refuses (F16): the key is pinned the first
+ * time it is seen, and a changed key replaces its pin with one warning
+ * (`observeDevices`, `~/.hwip/trusted-devices.json`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.peerKeyOf = void 0;
+const crypto_js_1 = require("./crypto.js");
+const trust_pins_js_1 = require("./trust-pins.js");
+const peerKeyOf = async (deviceId, deps) => {
+    if (!trust_pins_js_1.DEVICE_ID.test(deviceId))
+        return { refused: 'unlisted' };
+    if (deps.self?.deviceId === deviceId)
+        return { key: deps.self.publicKey };
+    let registered;
+    try {
+        registered = await deps.registeredKey(deviceId);
+    }
+    catch {
+        return { refused: 'devices_unavailable' };
+    }
+    // A listed key that is no device key in the one spelling is as good as none.
+    if (!registered || !(0, crypto_js_1.samePublicKey)(registered, registered))
+        return { refused: 'unlisted' };
+    (0, trust_pins_js_1.observeDevices)(deps.trustPath ?? trust_pins_js_1.TRUST_PATH, [{ deviceId, publicKey: registered }], { selfId: deps.self?.deviceId ?? deps.selfId });
+    return { key: registered };
+};
+exports.peerKeyOf = peerKeyOf;

package/dist/poll.d.ts

@@ -0,0 +1,24 @@
+import type { ServerNotification } from '@modelcontextprotocol/sdk/types.js';
+import { type HwipApiClient } 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>;
+    /** Fires when the agent cancels the tool call — the wait ends with it. */
+    signal?: AbortSignal;
+}
+/**
+ * How a wait ended without an answer, other than the deadline. Each code tells
+ * the agent something different to do next, which is the point of having them.
+ */
+export type AskFailure = 'CANCELLED' | 'POLL_FAILED' | 'ABORTED';
+export declare class AskError extends Error {
+    readonly code: AskFailure;
+    readonly eventId: string;
+    constructor(code: AskFailure, message: string, eventId: string);
+}
+export declare const pollForResponse: (client: HwipApiClient, hookId: string, eventId: string, timeoutSeconds: number, ctx: PollContext, waiter?: HookResponseWaiter) => Promise<HookEventResponse | null>;
+//# sourceMappingURL=poll.d.ts.map

package/dist/poll.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pollForResponse = exports.AskError = void 0;
+const api_client_js_1 = require("./api-client.js");
+class AskError extends Error {
+    code;
+    eventId;
+    constructor(code, message, eventId) {
+        super(message);
+        this.code = code;
+        this.eventId = eventId;
+        this.name = 'AskError';
+    }
+}
+exports.AskError = AskError;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Never settles — the stand-in for a race arm that is absent. */
+const never = new Promise(() => undefined);
+/** Rejects once `signal` aborts; never settles without one. `release` drops the listener. */
+const abortOf = (signal, eventId) => {
+    if (!signal)
+        return { aborted: never, release: () => undefined };
+    let fail = () => undefined;
+    const aborted = new Promise((_, reject) => {
+        fail = () => reject(new AskError('ABORTED', 'The tool call was cancelled', eventId));
+    });
+    aborted.catch(() => undefined);
+    if (signal.aborted)
+        fail();
+    else
+        signal.addEventListener('abort', fail, { once: true });
+    return { aborted, release: () => signal.removeEventListener('abort', fail) };
+};
+/** Backoff after `failures` consecutive failed reads: 1s, 2s, 4s … capped at 15s. */
+const RETRY_BASE_MS = 1_000;
+const RETRY_CAP_MS = 15_000;
+const retryDelay = (failures) => Math.min(RETRY_BASE_MS * 2 ** (failures - 1), RETRY_CAP_MS);
+const PROGRESS_INTERVAL_SECONDS = 5;
+// 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;
+    let sub;
+    let wsSettled = false;
+    if (waiter?.canWait()) {
+        sub = waiter.subscribe(eventId);
+        void sub.settled.then(() => { wsSettled = true; });
+    }
+    const { aborted, release } = abortOf(ctx.signal, eventId);
+    // Raced so a cancelled call returns now, not after an in-flight read.
+    const untilAborted = (p) => Promise.race([p, aborted]);
+    const wake = sub?.settled ?? never;
+    // Throttled progress notification (every 5s) — sent through outages too, so
+    // a client that keeps the call alive on progress does not give up mid-retry.
+    const reportProgress = async () => {
+        if (progressToken === undefined)
+            return;
+        const elapsed = Math.floor((Date.now() - startTime) / 1000);
+        if (elapsed - lastProgressAt < PROGRESS_INTERVAL_SECONDS)
+            return;
+        lastProgressAt = elapsed;
+        await ctx.sendNotification({
+            method: 'notifications/progress',
+            params: {
+                progressToken,
+                progress: elapsed,
+                total: timeoutSeconds,
+                message: `Waiting for user response... (${elapsed}s / ${timeoutSeconds}s)`,
+            },
+        });
+    };
+    let failures = 0;
+    let seen = false;
+    let lastReadAt;
+    let lastError;
+    try {
+        while (Date.now() - startTime < timeoutMs) {
+            let event;
+            try {
+                event = await untilAborted(client.getHookEvent(hookId, eventId));
+            }
+            catch (err) {
+                // A 404 before the first good read is the server's eventually
+                // consistent read missing the event the trigger just wrote.
+                const unseen404 = !seen && err instanceof api_client_js_1.ApiError && err.status === 404;
+                if (err instanceof AskError || !((0, api_client_js_1.isTransient)(err) || unseen404))
+                    throw err;
+                // One failed read is not the end of the question: it is still on the
+                // phone, and giving up here would leave the answer with nobody to
+                // receive it while the agent asks again. Back off and read again.
+                failures++;
+                lastError = err;
+                await reportProgress();
+                const remaining = timeoutMs - (Date.now() - startTime);
+                await untilAborted(Promise.race([sleep(Math.max(0, Math.min(retryDelay(failures), remaining))), wake]));
+                continue;
+            }
+            failures = 0;
+            seen = true;
+            lastReadAt = Date.now();
+            if (event.data.status === 'responded')
+                return event;
+            if (event.data.status === 'cancelled') {
+                throw new AskError('CANCELLED', 'The user cancelled this question on their phone', eventId);
+            }
+            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: ${(0, api_client_js_1.serverMessage)(String(event.data.status), 'unreadable')}`);
+            }
+            await reportProgress();
+            if (wsSettled) {
+                // Server said settled but this read still saw 'pending' —
+                // eventual consistency. Tight bounded retry until reads agree.
+                await untilAborted(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 untilAborted(Promise.race([sleep(interval), wake]));
+            attempt++;
+        }
+        // The deadline passed with the server unreadable for a while (not one
+        // stray failure after minutes of clean reads): that is not a timeout the
+        // user caused, and the answer may have landed unseen.
+        const blind = lastReadAt === undefined || Date.now() - lastReadAt > RETRY_CAP_MS;
+        if (failures > 0 && blind) {
+            const reason = lastError instanceof Error ? lastError.message : String(lastError);
+            throw new AskError('POLL_FAILED', `Lost contact with the hwip server while waiting (${reason}). The user may have answered, or the question expired, without this call seeing it.`, eventId);
+        }
+        return null;
+    }
+    finally {
+        release();
+        sub?.dispose();
+    }
+};
+exports.pollForResponse = pollForResponse;