@hwip/cli 0.0.1 → 0.1.1

package/dist/ask.js

@@ -0,0 +1,551 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleAsk = exports.liveDeps = exports.liveSealDeps = exports.remoteTransition = exports.requestApproval = exports.parseActions = exports.pollIntervalMs = void 0;
+/**
+ * `hwip ask` — put a question on the user's phone and block until they answer.
+ *
+ * Why this lives in the CLI at all: hooks are shell scripts, and a shell script
+ * cannot call an MCP tool. `hwip_ask` (mcp-server) already does this for the
+ * model; a hook that needs to wait for a person — an approval gate in front of
+ * a dangerous command — has no way to reach it. This is that path.
+ *
+ * It returns ONE shape for every outcome, including failure. A hook standing in
+ * front of `rm -rf` cannot handle an exception, and an approval gate that
+ * throws has stopped being a gate: unreachable server, bad key, and silence all
+ * come back as `answered: false` so the caller makes the same decision it would
+ * have made on a refusal. `reason` says which (`cancelled`, `timeout`, `error`)
+ * for a caller that wants to tell them apart.
+ *
+ * No WebSocket fast path, unlike mcp-server's poll. A hook run is seconds long
+ * and dies with the tool call, so a socket would cost a handshake it cannot
+ * amortise; plain polling is the whole protocol here.
+ */
+const node_crypto_1 = require("node:crypto");
+const config_js_1 = require("./config.js");
+const agent_session_js_1 = require("./agent-session.js");
+const gate_js_1 = require("./gate.js");
+const http_failure_js_1 = require("./http-failure.js");
+const insecure_url_js_1 = require("./insecure-url.js");
+const args_js_1 = require("./args.js");
+const api_js_1 = require("./api.js");
+const crypto_js_1 = require("./crypto.js");
+const listener_device_id_js_1 = require("./listener-device-id.js");
+const config_js_2 = require("./config.js");
+const self_register_js_1 = require("./self-register.js");
+const ask_seal_js_1 = require("./ask-seal.js");
+const ask_pending_js_1 = require("./ask-pending.js");
+/** Server-side hook trigger + event read. Kept narrow on purpose — this
+ *  module needs two routes, not an API client. */
+const TRIGGER_PATH = (hookId) => `/hooks/${encodeURIComponent(hookId)}/trigger`;
+const EVENT_PATH = (hookId, eventId) => `/hooks/${encodeURIComponent(hookId)}/events/${encodeURIComponent(eventId)}`;
+/** Poll cadence: every second for the first 30 s, when a tap is most likely
+ *  and should feel immediate, then every 2.5 s — a 10-minute wait is about
+ *  250 requests instead of 600. Exported for tests. */
+const pollIntervalMs = (waitedMs) => (waitedMs < 30_000 ? 1_000 : 2_500);
+exports.pollIntervalMs = pollIntervalMs;
+/** Per-request bound, well under any sane overall deadline. */
+const REQUEST_TIMEOUT_MS = 10_000;
+/** The least a try at sending is waited on, however little of the window is left: one with no time to be answered is not a try. */
+const MIN_REQUEST_MS = 1_000;
+/** Failed polls in a row before the wait ends early. At the poll cadence this
+ *  is 5–13 s of outage — long enough to ride out a blip, short enough that a
+ *  gate does not sit out its whole timeout against a dead server. */
+const MAX_CONSECUTIVE_FAILURES = 5;
+/** Pauses before the tries that follow a trigger failure that may pass: four tries in all. */
+const TRIGGER_BACKOFF_MS = [1_000, 2_000, 4_000];
+/**
+ * A first request still running under the key answers a retry with 409 until it ends. One the server
+ * lost to its own timeout never ends: the key stays taken for 30 s (hwip `server/src/entities/idempotency.ts`
+ * STALE_CLAIM_MS, read 2026-10-14) and a retry after that is taken as a new request. So these tries are
+ * counted apart from the ones above, and go on until that hold has passed: seven more, 35 s of
+ * waiting from the first 409. The key was taken before that answer, so the last try comes after the
+ * hold whatever the first request took to fail.
+ */
+const IN_PROGRESS_RETRY_MS = 5_000;
+const IN_PROGRESS_RETRIES = 7;
+/**
+ * Said of a question a retry put up, unless the answer says the phone was notified. A repeat the
+ * server had already taken is answered with the question's ids alone (hwip `server/src/functions/hooks.ts`,
+ * `once.replayed`, read 2026-10-14): the push went out with the first request or not at all, and only
+ * that request's answer said which.
+ */
+const UNCONFIRMED_NOTIFY = 'the question went up on a retry, and the server did not say the phone was notified: it is in the app either way';
+/**
+ * How a 2xx to the trigger ends when it holds no event id to read by — none, or one not written as an id
+ * (`ID`), which would go into the path of every read and into the record the next run reads by. Nothing is
+ * read and nothing kept, and the caller is told not to take it for a question that never went up: asked
+ * again, it is a second card. "May": a 2xx with such a body can be a proxy's as well as the server's.
+ */
+const NOT_READ_HERE = 'the question may be on the phone, and no answer to it can be read here \u2014 check the phone first: asking again puts a second card next to it';
+/**
+ * `id:Label` pairs, comma separated. The label may contain colons — only the
+ * first one separates, so `go:Deploy: prod` keeps its punctuation. A bare
+ * segment becomes its own label, which is what someone typing `--actions ok`
+ * means.
+ */
+const parseActions = (spec) => {
+    if (!spec)
+        return [];
+    return spec
+        .split(',')
+        .map((seg) => seg.trim())
+        .filter((seg) => seg.length > 0)
+        .map((seg) => {
+        const idx = seg.indexOf(':');
+        if (idx === -1)
+            return { id: seg, label: seg };
+        const id = seg.slice(0, idx).trim();
+        const label = seg.slice(idx + 1).trim();
+        return { id, label: label || id };
+    })
+        .filter((a) => a.id.length > 0);
+};
+exports.parseActions = parseActions;
+const errorMessage = (err) => err instanceof Error ? err.message : String(err);
+/** A non-2xx reply, kept apart from a network failure so the caller can tell
+ *  a refusal that will repeat from a blip that may not. */
+class HttpError extends Error {
+    status;
+    code;
+    constructor(status, message, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+/** A 4xx other than 408 / 429 is an answer about the request itself — bad key,
+ *  hook gone — and asking again gets the same answer. */
+const isFatal = (err) => err instanceof HttpError && err.status >= 400 && err.status < 500 && err.status !== 408 && err.status !== 429;
+/**
+ * Whether a failed trigger is sent again, and after which pause. The trigger goes under an
+ * Idempotency-Key, so a second copy of one that landed opens nothing: the server answers it with the
+ * first question's ids. That leaves only a refusal not worth repeating — a 4xx about the request
+ * itself, or a redirect, which the server will answer the same way again — and an address `fetch`
+ * cannot parse or a header it will not send, which no try will send.
+ */
+const resendAfter = (err) => {
+    if (err instanceof HttpError && err.status === 409 && err.code === 'IDEMPOTENCY_IN_PROGRESS')
+        return 'in-progress';
+    if (isFatal(err) || (err instanceof TypeError && ((0, http_failure_js_1.isRedirectRefusal)(err) || (0, http_failure_js_1.isInvalidUrl)(err) || (0, http_failure_js_1.isUnsendableHeader)(err))) || (0, http_failure_js_1.isConfigFailure)(err))
+        return 'never';
+    return 'backoff';
+};
+const callApi = async (deps, opts, method, path, request = {}) => {
+    const { payload, until } = request;
+    const controller = new AbortController();
+    const patience = until === undefined ? REQUEST_TIMEOUT_MS : Math.min(REQUEST_TIMEOUT_MS, Math.max(MIN_REQUEST_MS, until - deps.now()));
+    const timer = setTimeout(() => controller.abort(new DOMException(`the request timed out after ${Math.round(patience / 1000)} s`, 'TimeoutError')), patience);
+    try {
+        const headers = { 'X-API-Key': opts.apiKey };
+        if (payload)
+            Object.assign(headers, { 'Content-Type': 'application/json' }, payload.headers);
+        const url = `${opts.baseUrl}${path}`;
+        let res;
+        try {
+            res = await deps.fetchFn(url, {
+                method,
+                headers,
+                body: payload?.body,
+                signal: controller.signal,
+                // A redirect would carry the X-API-Key header to another host.
+                redirect: 'error',
+            });
+        }
+        catch (err) {
+            // Still a TypeError, so resendAfter reads it as before — with
+            // the cause a person can act on instead of "fetch failed". A refused redirect keeps its
+            // original; an unsendable header's words quote the key whole, so its cause is dropped.
+            if (err instanceof DOMException && err.name === 'TimeoutError')
+                throw new Error(err.message, { cause: err });
+            // The cause is what `neverConnected` reads the connection from, so it is kept — except an
+            // unsendable header's, whose words quote the key whole (the sanitized message still classifies).
+            if (err instanceof TypeError && (0, http_failure_js_1.isUnsendableHeader)(err))
+                throw new TypeError((0, http_failure_js_1.networkFailureMessage)(err, url));
+            if (err instanceof TypeError)
+                throw new TypeError((0, http_failure_js_1.networkFailureMessage)(err, url), { cause: err });
+            throw err;
+        }
+        const json = (await (0, http_failure_js_1.readJsonBody)(res));
+        if (!res.ok) {
+            const message = (0, http_failure_js_1.httpFailureMessage)(res.status, json);
+            throw new HttpError(res.status, res.status === 401 ? `${message} — ${http_failure_js_1.AUTH_HINT}` : message, json?.error?.code);
+        }
+        // A 2xx that is not our JSON (a captive portal, a cut-off body) is a
+        // failed call, not an empty answer.
+        if (!json)
+            throw new Error(`unreadable response (HTTP ${res.status})`);
+        return json;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};
+/**
+ * A failed trigger the server may have taken all the same: a slow answer, one that could not be read, a
+ * 5xx (a gateway that gave up on a request already written), a first send still running. Not its own
+ * "too many", and not a connection that was never made or a header `fetch` would not send — which is
+ * not every `TypeError` of `fetch`: a socket reset after the request, or an answer that stops mid-body,
+ * is one too.
+ */
+const mayHaveLanded = (err) => err instanceof HttpError ? err.status !== 429 : !(0, http_failure_js_1.neverConnected)(err) && !(0, http_failure_js_1.isUnsendableHeader)(err);
+/**
+ * Put the question on the phone, once. Every try carries the same key and the same bytes: the server
+ * replays a retry only when its body is the first one's, and takes another body under the key as a
+ * different request (422).
+ *
+ * What the key does not cover (hwip `server/SERVER-API.md`, the trigger's `Idempotency-Key`, read
+ * 2026-10-14): a first request that wrote the question and died before it marked the key is taken
+ * over after its 30 s hold, and that try opens a second question.
+ */
+const trigger = async (deps, opts, deadline, prepared) => {
+    // The question carries its wording inside the envelope: the server gets each choice's id and nothing else of it.
+    const body = JSON.stringify({
+        isEncrypted: true,
+        ...prepared.fields,
+        actions: opts.actions?.map(({ id }) => ({ id })),
+        ...(prepared.files ? { files: prepared.files } : {}),
+        // What is left of the window, so the question ends on the phone when this wait does: sealing took
+        // some of it, and so did a question taken up first that ended unanswered.
+        timeout: Math.max(1, Math.ceil((deadline - deps.now()) / 1000)),
+        hookType: 'combo',
+        agentDeviceId: opts.agentDeviceId,
+        agentSessionName: opts.agentSessionName,
+        ...(opts.acceptsExit ? { acceptsExit: true } : {}),
+    });
+    const payload = { body, headers: { 'Idempotency-Key': (0, node_crypto_1.randomUUID)() } };
+    let backoffs = 0;
+    let inProgress = 0;
+    /** Some try so far may have reached the server, whatever the last one says. */
+    let unsure = false;
+    for (;;) {
+        try {
+            return { answer: await callApi(deps, opts, 'POST', TRIGGER_PATH(opts.hookId), { payload, until: deadline }), retried: backoffs + inProgress > 0 };
+        }
+        catch (err) {
+            const resend = resendAfter(err);
+            if (resend !== 'never')
+                unsure ||= mayHaveLanded(err);
+            const wait = resend === 'never'
+                ? undefined
+                : resend === 'in-progress'
+                    ? (inProgress++ < IN_PROGRESS_RETRIES ? IN_PROGRESS_RETRY_MS : undefined)
+                    : TRIGGER_BACKOFF_MS[backoffs++];
+            if (wait === undefined || deps.now() + wait >= deadline) {
+                // The last failure alone would have its reader ask again, for a second card next to the first.
+                throw unsure ? new Error(`${errorMessage(err)} — ${TRIGGER_MAY_BE_UP}`) : err;
+            }
+            await deps.sleep(wait);
+        }
+    }
+};
+/** What an opened answer means to the caller: the choice, or the text (with the exit when this ask offers it). */
+const sealedOutcome = (opened, acceptsExit) => {
+    if (!opened.ok)
+        return { answered: false, reason: 'error', error: (0, ask_seal_js_1.refusalMessage)(opened.cause) };
+    if (opened.actionId !== undefined)
+        return { answered: true, actionId: opened.actionId };
+    if (opened.exit === true && acceptsExit)
+        return { answered: true, value: opened.value ?? '', exitRemote: true };
+    if (opened.value)
+        return { answered: true, value: opened.value };
+    return { answered: false, reason: 'error', error: (0, ask_seal_js_1.refusalMessage)('empty-answer') };
+};
+/**
+ * Read the question's answer until there is one, the question ends without, or `until` passes — once
+ * at least, whatever the clock says: the answer may be there already.
+ */
+const awaitAnswer = async (deps, opts, asked, until, unconfirmed) => {
+    const polling = deps.now();
+    let failures = 0;
+    let unusable = 0;
+    let lastError;
+    let seen = false;
+    do {
+        try {
+            const event = await callApi(deps, opts, 'GET', EVENT_PATH(opts.hookId, asked.eventId));
+            failures = 0;
+            seen = true;
+            // The plaintext fields of a response are never read: the server refuses them on a sealed
+            // question, so any that are there were put there by something else.
+            if (event.data?.status === 'responded') {
+                const opened = await (0, ask_seal_js_1.openAnswer)(event.data.response ?? undefined, asked.askId, asked.offered, deps.seal);
+                // The device list or the trust file failing to load may pass: read again, up to the
+                // same run of failures as a failed poll (this read itself succeeded, so `failures` was reset).
+                // When it keeps failing the answer is still there, to be opened by a later run.
+                const mayPass = !opened.ok && opened.cause === 'peer-unusable';
+                if (mayPass && (unusable += 1) < MAX_CONSECUTIVE_FAILURES) {
+                    lastError = new Error((0, ask_seal_js_1.refusalMessage)(opened.cause));
+                }
+                else {
+                    return { outcome: sealedOutcome(opened, opts.acceptsExit === true), end: mayPass ? 'open' : 'over' };
+                }
+            }
+            if (event.data?.status === 'cancelled')
+                return { outcome: { answered: false, reason: 'cancelled' }, end: 'over' };
+            if (event.data?.status === 'timed_out')
+                return { outcome: { answered: false, reason: 'timeout', ...unconfirmed }, end: 'over' };
+        }
+        catch (err) {
+            // A refusal will repeat, so waiting on it only stalls the gate. A
+            // blip may pass — one failed poll is not an answer and not a
+            // refusal — but a run of them means the server is gone for now.
+            // A 404 before the first good read is the server's eventually
+            // consistent read missing the event it just wrote, not a refusal.
+            // A refusal ends the wait and not the question: a key that was
+            // rotated or mistyped is refused while the question sits on the phone.
+            const unseen404 = !seen && err instanceof HttpError && err.status === 404;
+            if (isFatal(err) && !unseen404)
+                return { outcome: { answered: false, reason: 'error', error: errorMessage(err) }, end: 'open' };
+            failures += 1;
+            lastError = err;
+            if (failures >= MAX_CONSECUTIVE_FAILURES) {
+                return { outcome: { answered: false, reason: 'error', error: errorMessage(err) }, end: 'open' };
+            }
+        }
+        const now = deps.now();
+        await deps.sleep(Math.min((0, exports.pollIntervalMs)(now - polling), Math.max(0, until - now)));
+    } while (deps.now() < until);
+    return {
+        outcome: failures > 0 || unusable > 0
+            ? { answered: false, reason: 'error', error: errorMessage(lastError) }
+            : { answered: false, reason: 'timeout', ...unconfirmed },
+        end: 'open',
+    };
+};
+/** Ends the error of a trigger that failed after a try the server may have taken. */
+const TRIGGER_MAY_BE_UP = 'the question may have gone up all the same';
+/** Said when a question that is over stays on record: the next run would take it up, and its answer with it. */
+const NOT_FORGOTTEN = 'this question is over but its record under the state directory could not be removed: '
+    + 'the same command run again before its timeout would be given this answer again';
+const forget = (slot, deps) => {
+    if (!slot.settle()) {
+        deps.seal.warn?.(NOT_FORGOTTEN);
+        return false;
+    }
+    return true;
+};
+/**
+ * Wait on the question an earlier run of the same command left. Null when it ended with nobody having
+ * answered and some of this run's window is left: that is not this run's outcome, and it asks anew.
+ */
+const takeUp = async (deps, opts, slot, kept, deadline) => {
+    // A new question loads the keys as it is sealed; this one was sealed by the run that put it up.
+    try {
+        await deps.seal.loadKeys();
+    }
+    catch {
+        // Kept: the question is still on the phone, and a later run may open its answer.
+        return { answered: false, reason: 'error', error: (0, ask_seal_js_1.refusalMessage)('keystore'), resumed: true };
+    }
+    // The buttons are this run's own: the match says they are the ones the question went up with.
+    const asked = { eventId: kept.eventId, askId: kept.askId, offered: opts.actions?.map((a) => a.id) };
+    const waited = await awaitAnswer(deps, opts, asked, Math.min(deadline, kept.deadline));
+    const ended = waited.end === 'over' || deps.now() >= kept.deadline;
+    // Before the outcome is handed over: an answer is used once.
+    const forgotten = ended ? forget(slot, deps) : true;
+    // A question the user cancelled stays cancelled.
+    const unanswered = !waited.outcome.answered && waited.outcome.reason === 'timeout';
+    if (ended && unanswered && deps.now() < deadline)
+        return null;
+    return { ...waited.outcome, resumed: true, ...(!forgotten ? { warn: NOT_FORGOTTEN } : {}) };
+};
+/**
+ * Ask, then wait. Resolves when the user answers, the question settles
+ * without an answer, or the deadline passes — never rejects. An unanswered
+ * outcome says why in `reason`, and carries the last error when there was one.
+ *
+ * A question an earlier run of the same command put up and did not see through is waited on first, and
+ * nothing is sent: the user may have answered it already, and a second card would sit next to the first.
+ */
+const requestApproval = async (opts, deps) => {
+    const deadline = deps.now() + opts.timeoutSeconds * 1000;
+    const slot = deps.pending?.of(opts);
+    const kept = slot?.claim();
+    if (slot && kept) {
+        const outcome = await takeUp(deps, opts, slot, kept, deadline);
+        if (outcome)
+            return outcome;
+    }
+    const prepared = await (0, ask_seal_js_1.prepareAsk)({ title: opts.title, body: opts.body, actions: opts.actions }, deps.seal);
+    // No plaintext fallback: a question that cannot be sealed is not sent.
+    if (prepared.kind === 'refused') {
+        const error = (0, ask_seal_js_1.refusalMessage)(prepared.cause, prepared.why, prepared.detail);
+        // On stderr too, as `hwip notify` and `hwip agent send` say it: the JSON goes to whatever parses it, not to a person.
+        if (prepared.cause === 'self-unlisted')
+            deps.seal.warn?.(error);
+        return { answered: false, reason: 'error', error };
+    }
+    // The lookups behind `prepared` count against the window but each has only its own limit: when they used it up,
+    // a question sent now would sit on the phone after this ask has ended.
+    if (deps.now() >= deadline)
+        return { answered: false, reason: 'timeout' };
+    let eventId;
+    /** Set when nobody may have been told of the question: said at once, and again if it ends unanswered. */
+    let unconfirmed;
+    try {
+        const { answer, retried } = await trigger(deps, opts, deadline, prepared);
+        const { eventId: id, pushId: push } = answer.data ?? {};
+        if (typeof id !== 'string' || !ask_pending_js_1.ID.test(id)) {
+            const missing = id === undefined || id === null || id === '';
+            // The push id is the server's string as well: quoted only when it is written as an id.
+            const named = typeof push === 'string' && ask_pending_js_1.ID.test(push) ? ` (push ${push})` : '';
+            const what = missing ? `named no event for it${named}` : 'the id it gave for it cannot be used';
+            return { answered: false, reason: 'error', error: `the server took the question, but ${what}: ${NOT_READ_HERE}` };
+        }
+        eventId = id;
+        if (retried && answer.data?.notified !== true) {
+            unconfirmed = { error: UNCONFIRMED_NOTIFY };
+            deps.seal.warn?.(UNCONFIRMED_NOTIFY);
+        }
+    }
+    catch (err) {
+        // No event id to wait on. When a try may have landed, the error says so.
+        return { answered: false, reason: 'error', error: errorMessage(err) };
+    }
+    const asked = { eventId, askId: prepared.askId, offered: prepared.offered };
+    slot?.record({ eventId, askId: prepared.askId, deadline });
+    const waited = await awaitAnswer(deps, opts, asked, deadline, unconfirmed);
+    // Kept while the question may still be answered — the wait gave up on a server it could not read, or
+    // this process dies — so that the same command run again takes it up.
+    if (slot && waited.end === 'over') {
+        const forgotten = forget(slot, deps);
+        if (!forgotten)
+            return { ...waited.outcome, warn: NOT_FORGOTTEN };
+    }
+    return waited.outcome;
+};
+exports.requestApproval = requestApproval;
+/** Action ids that end a remote session, case-insensitive — mcp-server remote-state.ts SESSION_EXIT_IDS. */
+const SESSION_EXIT_IDS = ['done', 'stop', 'exit'];
+/**
+ * What an ask outcome does to sticky REMOTE — mcp-server's
+ * `remoteTransitionFor`, for the outcomes this command can produce. A
+ * Done-like button or a send-and-exit answer ends it; any other answer enters
+ * or refreshes it. An unanswered ask changes nothing: there is no fallback id
+ * here to resolve to, and silence is not a user action.
+ */
+const remoteTransition = (outcome) => {
+    if (!outcome.answered)
+        return 'keep';
+    if ('actionId' in outcome) {
+        return SESSION_EXIT_IDS.includes(outcome.actionId.trim().toLowerCase()) ? 'exit' : 'enter';
+    }
+    return outcome.exitRemote ? 'exit' : 'enter';
+};
+exports.remoteTransition = remoteTransition;
+const settleRemote = (outcome, dir) => {
+    switch ((0, exports.remoteTransition)(outcome)) {
+        case 'exit':
+            (0, gate_js_1.clearRemoteActive)(dir);
+            return { hwipState: 'NORMAL' };
+        case 'enter':
+            (0, gate_js_1.touchRemoteActive)(dir);
+            return { hwipState: 'REMOTE' };
+        case 'keep':
+            return {};
+    }
+};
+/** The seal's world for real use: the account API, this machine's keys, the listener's trust file. */
+const liveSealDeps = (apiKey, baseUrl, deadline) => ({
+    loadKeys: async () => { await (0, crypto_js_1.initDeviceCrypto)(); },
+    self: () => {
+        const publicKey = (0, crypto_js_1.getDevicePublicKey)();
+        return publicKey ? { deviceId: (0, listener_device_id_js_1.listenerDeviceId)(), publicKey } : null;
+    },
+    listDevices: async () => {
+        const res = await (0, api_js_1.apiFetch)(fetch, (0, api_js_1.apiUrl)(baseUrl, '/devices'), apiKey, REQUEST_TIMEOUT_MS);
+        if (!res.ok)
+            throw new Error(`devices ${res.status}`);
+        const json = (await res.json());
+        if (!Array.isArray(json.data))
+            throw new Error('devices: unexpected response');
+        return json.data;
+    },
+    register: (0, self_register_js_1.registerOverApi)({ apiKey, baseUrl }),
+    trustPath: config_js_2.TRUST_FILE,
+    warn: (line) => console.error(`hwip: ${line}`),
+    // Loaded only for a question with a window to carry context for.
+    ...(deadline === undefined ? {} : {
+        attach: async (recipients) => (await import('./ask-context-attach.js'))
+            .liveAttach({ apiKey, baseUrl }, deadline, (line) => process.stderr.write(`hwip ask: ${line}\n`))(recipients),
+    }),
+});
+exports.liveSealDeps = liveSealDeps;
+/** Wall-clock deps for real use. `deadline` is when the question's window ends: with one, a sealed question carries its context. */
+const liveDeps = (account) => ({
+    fetchFn: fetch,
+    now: () => Date.now(),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    seal: (0, exports.liveSealDeps)(account.apiKey, account.baseUrl, account.deadline),
+    pending: (0, ask_pending_js_1.pendingAsks)((0, gate_js_1.stateDir)()),
+});
+exports.liveDeps = liveDeps;
+/**
+ * `hwip ask --title … [--body …] [--actions id:Label,…] [--timeout 60] [--accepts-exit]`
+ *
+ * Prints one JSON object and nothing else, so a hook can pipe it straight into
+ * `jq`. Exit code 0 means answered, 1 means not — a shell caller that only
+ * wants approve/deny can read `$?` and skip the JSON entirely.
+ */
+const handleAsk = async (args) => {
+    const config = (0, config_js_1.loadConfig)();
+    // `resolvedEnv`, not `process.env`: a hook environment can hand us a literal
+    // unexpanded `${HWIP_API_KEY}`, which is truthy and would beat the config
+    // file. Auth then fails, this returns `answered: false`, and the approval
+    // hook maps that to DENY — a command blocked for a reason that has nothing
+    // to do with the user. Every other command in cli.ts resolves env this way.
+    // Key and base URL resolve as cli.ts createHook does for every other
+    // command; `--api-key` is this command's older spelling of `--key`. A
+    // bare flag parses as `true`, which is no key and no URL.
+    const flag = (name) => (typeof args[name] === 'string' ? args[name] : undefined);
+    const apiKey = flag('key') || flag('api-key') || (0, config_js_1.resolvedEnv)('HWIP_API_KEY') || config.apiKey;
+    let baseUrl;
+    try {
+        baseUrl = (0, config_js_1.resolveBaseUrl)(flag('base-url'), config, (0, config_js_1.keyIsFromFile)(flag('key') || flag('api-key'), config));
+    }
+    catch (err) {
+        process.stdout.write(JSON.stringify({ answered: false, reason: 'error', error: err instanceof Error ? err.message : String(err) }) + '\n');
+        return 1;
+    }
+    (0, insecure_url_js_1.warnInsecureUrl)(baseUrl);
+    const hookId = args.hook || (0, config_js_1.resolveHookId)();
+    const title = args.title || '';
+    if (!apiKey || !hookId || !title) {
+        const missing = [!title && '--title', !apiKey && 'an API key', !hookId && 'a hook id']
+            .filter((m) => !!m);
+        process.stdout.write(JSON.stringify({ answered: false, reason: 'error', error: `missing ${new Intl.ListFormat('en').format(missing)}` }) + '\n');
+        return 1;
+    }
+    // A key `fetch` cannot send is said before anything is tried: the trigger would fail the same
+    // way, and its error would quote the key. The message names no secret.
+    if (!(0, api_js_1.fitsInHeader)(apiKey)) {
+        process.stdout.write(JSON.stringify({ answered: false, reason: 'error', error: 'a header could not be sent — check the API key for stray characters' }) + '\n');
+        return 1;
+    }
+    // A bare `--timeout` parses as `true`, which Number() reads as 1 second.
+    const timeoutSeconds = typeof args.timeout === 'string' ? Number(args.timeout) : 60;
+    const acceptsExit = (0, args_js_1.flagOn)(args, 'accepts-exit');
+    const windowSeconds = Number.isFinite(timeoutSeconds) && timeoutSeconds > 0 ? timeoutSeconds : 60;
+    const outcome = await (0, exports.requestApproval)({
+        apiKey,
+        baseUrl: baseUrl.replace(/\/+$/, ''),
+        hookId,
+        title,
+        body: args.body,
+        actions: (0, exports.parseActions)(args.actions),
+        timeoutSeconds: windowSeconds,
+        ...((0, agent_session_js_1.agentSessionContext)() ?? {}),
+        acceptsExit,
+    }, (0, exports.liveDeps)({ apiKey, baseUrl: baseUrl.replace(/\/+$/, ''), deadline: Date.now() + windowSeconds * 1000 }));
+    // The agent's own ask settles REMOTE as mcp-server's hwip_ask does and
+    // reports it in the same `hwipState` field; an approval gate leaves the
+    // mode alone. Keyed by the cwd, the twin of the `ctx.cwd` the pi
+    // extension hands `remote-hook pi` — pi's bash tool runs every command
+    // there. Not detectProjectDir(): a CLAUDE_PROJECT_DIR leaked into a pi
+    // launched from Claude Code would key another project's file.
+    const settled = acceptsExit ? settleRemote(outcome, process.cwd()) : {};
+    // `exitRemote` is the server's flag; the rules read `hwipState`.
+    process.stdout.write(JSON.stringify({ ...outcome, exitRemote: undefined, ...settled }) + '\n');
+    return outcome.answered ? 0 : 1;
+};
+exports.handleAsk = handleAsk;

package/dist/blocked-prompt-seal.d.ts

@@ -0,0 +1,39 @@
+import type { AgentState } from './agent-state.js';
+import type { AgentKind } from './remote-agents.js';
+import type { RecorderRecipient, SealedChunk } from './turn-recorder.js';
+/** What the session report carries: the server stores it and never opens it. */
+export interface BlockedPromptWire {
+    id: string;
+    /**
+     * When the listener first saw THIS prompt id, ISO 8601. Not the session's `stateChangedAt`: approvals that follow
+     * one another inside one blocked run, or a highlight that moves, make a new id with a later `at` while
+     * `stateChangedAt` stays. It never precedes the session's `stateChangedAt` (the state is confirmed before a prompt
+     * is read); the app compares it with the session record's `blockedPrompt.at`.
+     */
+    at: string;
+    sealed: SealedChunk;
+}
+/** After a failed seal or an empty recipient list, how long before the same prompt is tried again. */
+export declare const PROMPT_SEAL_RETRY_MS = 30000;
+export interface PromptSealerDeps {
+    deviceId: () => string;
+    recipients: () => Promise<RecorderRecipient[]>;
+    seal: (plaintext: string, recipients: RecorderRecipient[]) => Promise<SealedChunk>;
+    log?: (message: string) => void;
+    now?: () => number;
+}
+export interface PromptSealer {
+    /** The sealed prompt for this session's screen, or undefined (not blocked, not a known dialog, not sealed yet). */
+    observe: (name: string, kind: AgentKind, state: AgentState | undefined, paneText: string | null) => BlockedPromptWire | undefined;
+    /** Forget sessions that are gone. */
+    prune: (live: ReadonlySet<string>) => void;
+    /** Settles when the seals running now are done, or undefined when none is. */
+    sealing: () => Promise<void> | undefined;
+}
+export declare const createPromptSealer: (deps: PromptSealerDeps) => PromptSealer;
+/**
+ * True when the pane shows the prompt `id` right now (a fresh capture, not the one a report was made from). Capture it
+ * the way `observe` was fed (`-e`): OpenCode's highlight is in the escapes, and the id with it.
+ */
+export declare const promptStillShown: (id: string, paneText: string | null) => boolean;
+//# sourceMappingURL=blocked-prompt-seal.d.ts.map