@hwip/cli 0.0.1 → 0.1.0

package/dist/http-failure.js

@@ -0,0 +1,349 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.webSocketProxyOptions = exports.useProxyFromEnv = exports.proxyForUrl = exports.AUTH_HINT = exports.httpFailureMessage = exports.readJsonBody = exports.networkFailureMessage = exports.isUnsendableHeader = exports.isConfigFailure = exports.isInvalidUrl = exports.neverConnected = exports.isRedirectRefusal = void 0;
+const redact_js_1 = require("./redact.js");
+const ws_url_js_1 = require("./ws-url.js");
+/**
+ * What a failed call to the account API says to a person (C13). `fetch`
+ * reports every network problem as "fetch failed" with the real cause one
+ * level down, and an outage or proxy page is HTML, which `response.json()`
+ * turns into "Unexpected token <" — both said nothing about what to do.
+ */
+/** Is any error of `err`'s cause chain one that `says` so? `fetch` wraps the reason one or two levels down, and its callers once more. */
+const somewhereInCauses = (err, says) => {
+    for (let e = err, depth = 0; e instanceof Error && depth < 4; e = e.cause, depth++) {
+        if (says(e))
+            return true;
+    }
+    return false;
+};
+/**
+ * Did `fetch` reject because the answer was a redirect (every call that carries
+ * the API key passes `redirect: 'error'`)? The reason sits in the error's cause
+ * chain, one or two levels down depending on who wrapped it.
+ */
+const isRedirectRefusal = (err) => somewhereInCauses(err, (e) => /unexpected redirect/i.test(e.message));
+exports.isRedirectRefusal = isRedirectRefusal;
+/**
+ * The errnos of a connection that could not be made, each with the call that says so. Under any other
+ * call the socket had been connected, and the request may have been written to it: a reset is reported
+ * under `read` (seen on Node 24.21), and "no route" is taken to come the same way (not reproduced).
+ */
+const BEFORE_CONNECTING = new Map([
+    ['ENOTFOUND', 'getaddrinfo'],
+    ['EAI_AGAIN', 'getaddrinfo'],
+    ['ECONNREFUSED', 'connect'],
+    ['ENETUNREACH', 'connect'],
+    ['EHOSTUNREACH', 'connect'],
+    ['ETIMEDOUT', 'connect'],
+]);
+/** undici's own "the connect got no answer", and `fetch` handed an address it could not parse: neither has a call to go by, or needs one. */
+const NEVER_STARTED = new Set(['UND_ERR_CONNECT_TIMEOUT', 'ERR_INVALID_URL']);
+const codeOf = (err) => 'code' in err && typeof err.code === 'string' ? err.code : undefined;
+/** One error of the chain: a connect or a lookup that failed, or — a host with several addresses — every one of them failing so. */
+const failedBeforeConnecting = (err) => {
+    const code = codeOf(err);
+    if (code === undefined)
+        return false;
+    if (NEVER_STARTED.has(code))
+        return true;
+    if (err instanceof AggregateError)
+        return err.errors.length > 0 && err.errors.every((e) => e instanceof Error && failedBeforeConnecting(e));
+    const call = BEFORE_CONNECTING.get(code);
+    return call !== undefined && 'syscall' in err && err.syscall === call;
+};
+/**
+ * Did `fetch` reject before the request could be sent? Any other rejection — a socket reset, a body
+ * that stops halfway — is also a `TypeError`, and may be of a request the server took. The code sits
+ * in the cause chain, as for a refused redirect. The shapes are Node 24.21's (undici 7.29), read
+ * 2026-10-14: `{ code, syscall }` on the cause, and an `AggregateError` of them for a host with two addresses.
+ */
+const neverConnected = (err) => somewhereInCauses(err, failedBeforeConnecting);
+exports.neverConnected = neverConnected;
+/** Did `fetch` reject because the address is not one? It will say so again however often it is asked. */
+const isInvalidUrl = (err) => somewhereInCauses(err, (e) => codeOf(e) === 'ERR_INVALID_URL' || /not a valid address/.test(e.message));
+exports.isInvalidUrl = isInvalidUrl;
+/**
+ * Is this failure a permanent configuration problem (bad base URL, unsendable API key) rather than a
+ * network blip? Such errors say so in fixed words — `apiFetch` throws them before any `fetch`, and
+ * `resolveBaseUrl` throws them before any request — so swallowing them as "could not fetch" or
+ * retrying them with backoff only repeats them. Matched by message, as the throwers sanitize it — so
+ * never on an error that carries an HTTP status (`HttpError`, a `HwipError` from a reply): its message
+ * is the server's own text, and a 5xx that happens to say "is unknown" is still worth another try.
+ */
+const isConfigFailure = (err) => somewhereInCauses(err, (e) => !isHttpReply(e)
+    && /not a valid address|user name or password|header could not be sent|stray characters|is not text|is unknown|belongs to/i.test(e.message));
+exports.isConfigFailure = isConfigFailure;
+const isHttpReply = (e) => {
+    const status = e.status;
+    return typeof status === 'number' && status >= 100;
+};
+/**
+ * Did `fetch` reject for a header value it cannot send? It does so before it opens a connection, and the
+ * same way however often it is asked. Two shapes (Node 24.21, read 2026-10-14 — held to a real `fetch`
+ * in http-failure.test.ts): a `TypeError` with no cause that says which value — whole for a line break
+ * or a NUL, by place for a character past U+00FF — and, for any other control character, undici's
+ * `UND_ERR_INVALID_ARG` ("invalid X-API-Key header") under "fetch failed". Looked for down the cause
+ * chain, as the callers hand on what `fetch` threw inside an error in their own words.
+ */
+const isUnsendableHeader = (err) => somewhereInCauses(err, (e) => {
+    const refusedByHeaders = e instanceof TypeError && e.cause === undefined && /is an invalid header value|to a ByteString/.test(e.message);
+    const refusedByUndici = codeOf(e) === 'UND_ERR_INVALID_ARG' && /^invalid .+ header$/.test(e.message);
+    // The sanitized rethrow (`apiFetch`, `callApi`): no cause is kept, as the original quotes the key.
+    const sanitized = /a header could not be sent/.test(e.message);
+    return refusedByHeaders || refusedByUndici || sanitized;
+});
+exports.isUnsendableHeader = isUnsendableHeader;
+/** "could not reach api.hwip.app (ENOTFOUND)" from a rejected `fetch`. */
+const networkFailureMessage = (err, url) => {
+    // Nothing was tried, and the address is the thing to fix. Not quoted: it may carry a password.
+    if ((0, exports.isInvalidUrl)(err))
+        return 'the base URL is not a valid address — check --base-url, HWIP_BASE_URL or "baseUrl" in ~/.hwip/config.json';
+    // The one header whose value is not ours is the API key, and the error's own words quote it.
+    if ((0, exports.isUnsendableHeader)(err))
+        return 'a header could not be sent — check the API key for stray characters';
+    // `fetch` refuses such an address before it tries anything, in words that are the address as it was given: a
+    // password with a quote or a space in it is not one `redactSecrets` can find the end of (C152).
+    if ((0, ws_url_js_1.carriesCredentials)(url)) {
+        return 'the base URL has a user name or password in it, and no request can be made to such an address — take it out of --base-url, HWIP_BASE_URL or "baseUrl" in ~/.hwip/config.json';
+    }
+    let host;
+    try {
+        host = new URL(url).host;
+    }
+    catch {
+        // The raw url, less what it may carry: `https://user:password@host`.
+        host = (0, redact_js_1.redactSecrets)(url);
+    }
+    const cause = err instanceof Error && err.cause instanceof Error ? err.cause : null;
+    const code = cause && 'code' in cause && typeof cause.code === 'string' ? cause.code : null;
+    // `redirect: 'error'` on every call that carries the key: say so, not "unexpected redirect".
+    if ((0, exports.isRedirectRefusal)(err)) {
+        return `${host} answered with a redirect, and hwip does not follow one with your API key — check the base URL (${host})`;
+    }
+    // The cause can quote the whole URL: `https://user:password@host` when the base URL carries credentials.
+    const why = (0, redact_js_1.redactSecrets)(code ?? cause?.message ?? (err instanceof Error ? err.message : String(err)));
+    return `could not reach ${host} (${why}) — check the network${process.env.HTTPS_PROXY || process.env.https_proxy ? ' and HTTPS_PROXY' : ''}`;
+};
+exports.networkFailureMessage = networkFailureMessage;
+/** The body as JSON when it is JSON, else null. A read that fails (an abort
+ *  mid-body) still throws: that is a timeout or a dropped connection, not a
+ *  page that is not ours. */
+const readJsonBody = async (response) => {
+    try {
+        return (await response.json());
+    }
+    catch (err) {
+        if (err instanceof SyntaxError)
+            return null;
+        throw err;
+    }
+};
+exports.readJsonBody = readJsonBody;
+/**
+ * What one line of a message is not made of: controls, line and paragraph breaks, the invisible format
+ * characters (Cf — bidi marks and overrides, zero-width space, the BOM, and the Unicode tag block, which can
+ * hide text from a reader but not from an agent reading `hwip ask`), the grapheme-join blocker U+034F, and
+ * the Hangul fillers (U+115F, U+1160, U+3164, U+FFA0 — blank letters an attacker would use as an invisible
+ * base character). U+200C ZWNJ and U+200D ZWJ are writing, not hiding (Persian, Hindi, emoji sequences), so
+ * a lone one stays — but a run of them is a bit channel, so a run collapses to its first character (C153).
+ * Selectors go by allowlist, not by run: U+FE0E/U+FE0F stay only after an emoji base (text/emoji
+ * presentation: ❤️ ☺︎ 1️⃣), U+E0100–E01EF only after a unified ideograph (IVS); every other selector —
+ * including the Mongolian FVS (U+180B–U+180D, U+180F) — goes, so spacing a run out with an invisible
+ * character no longer smuggles it past the rule. The same rule as mcp-server's `UNPRINTABLE` block
+ * (src/api-client.ts): the lines below from `const UNPRINTABLE` through `sanitizeSmuggled` are
+ * character-identical there.
+ */
+const UNPRINTABLE = /(?:[\p{Cc}\p{Zl}\p{Zp}]|(?![\u200C\u200D])\p{Cf}|[\u034F\u115F\u1160\u3164\uFFA0])+/gu;
+// Written with \u{...}: \uE0100 would read as U+E010 plus "0", turning 0-\uE01E into a range over ASCII (C153).
+const SELECTOR_ALLOW = /(\p{Emoji}|[0-9#*])([\uFE0E\uFE0F])|(\p{Unified_Ideograph})([\u{E0100}-\u{E01EF}])|[\uFE00-\uFE0F\u180B-\u180D\u180F\u{E0100}-\u{E01EF}]/gu;
+const JOINER_RUN = /([\u200C\u200D])[\u200C\u200D]+/gu;
+// '$1$2$3$4' rebuilds an allowed base + selector and erases anything else (groups that did not match are empty).
+const sanitizeSmuggled = (text) => text.replace(SELECTOR_ALLOW, '$1$2$3$4').replace(JOINER_RUN, '$1');
+const MAX_SERVER_MESSAGE_CHARS = 300;
+/**
+ * A server's own words as one line of bounded length: they go to a terminal and, through `hwip ask`, into
+ * an agent's context, and a host that is not ours could otherwise put a paragraph of instructions there.
+ * The rule is mcp-server's `serverMessage` (src/api-client.ts) — keep them in step.
+ */
+const serverWords = (sent) => {
+    const clean = sanitizeSmuggled(sent.replace(UNPRINTABLE, ' ')).trim();
+    // By code point: a cut through a surrogate pair would leave half an emoji.
+    const points = Array.from(clean);
+    return points.length > MAX_SERVER_MESSAGE_CHARS ? `${points.slice(0, MAX_SERVER_MESSAGE_CHARS - 1).join('')}…` : clean;
+};
+/** The line for a non-2xx answer whose body may not be ours at all. */
+const ERROR_CODE_SHAPE = /^[A-Za-z0-9_.:-]{1,64}$/;
+const httpFailureMessage = (status, body) => {
+    const sent = body && typeof body === 'object' ? body.error?.message : undefined; // a JSON body of any shape: read by the one path the API's errors have
+    const code = body && typeof body === 'object' ? body.error?.code : undefined;
+    const tag = typeof code === 'string' && ERROR_CODE_SHAPE.test(code) ? ` (${code})` : '';
+    const message = typeof sent === 'string' ? serverWords(sent) : '';
+    if (message)
+        return message;
+    return body === null
+        ? `the server answered ${status} with a page that is not the API's (an outage, or a proxy in the way)${tag}`
+        : `request failed with status ${status}${tag}`;
+};
+exports.httpFailureMessage = httpFailureMessage;
+/** What to do about a rejected key, appended to its message. */
+exports.AUTH_HINT = 'run `hwip login`, or check --key / HWIP_API_KEY';
+const DEFAULT_PORTS = { 'http:': 80, 'https:': 443, 'ws:': 80, 'wss:': 443 };
+const noProxyEntries = (value) => value.split(/[,\s]/).filter(Boolean).map((entry) => {
+    const parsed = entry.match(/^(.+):(\d+)$/);
+    return { hostname: (parsed ? parsed[1] : entry).toLowerCase(), port: parsed ? Number.parseInt(parsed[2], 10) : 0 };
+});
+const bypassesProxy = (url, noProxy) => {
+    const entries = noProxyEntries(noProxy);
+    if (entries.length === 0)
+        return false;
+    if (noProxy === '*')
+        return true;
+    // Not `url.hostname`: it drops the brackets round an IPv6 address.
+    const hostname = url.host.replace(/:\d*$/, '').toLowerCase();
+    const port = Number.parseInt(url.port, 10) || DEFAULT_PORTS[url.protocol] || 0;
+    return entries.some((entry) => {
+        if (entry.port && entry.port !== port)
+            return false;
+        return /^[.*]/.test(entry.hostname)
+            ? hostname.endsWith(entry.hostname.replace(/^\*/, ''))
+            : hostname === entry.hostname;
+    });
+};
+/** The proxy a request to `rawUrl` goes through, or null for a direct connection. `ws` / `wss` follow `http` / `https`. */
+const proxyForUrl = (rawUrl, env = process.env) => {
+    const url = new URL(rawUrl);
+    const secure = url.protocol === 'https:' || url.protocol === 'wss:';
+    const http = env.http_proxy ?? env.HTTP_PROXY;
+    const https = env.https_proxy ?? env.HTTPS_PROXY;
+    const proxy = (secure ? https || http : http) || null;
+    if (!proxy || bypassesProxy(url, env.no_proxy ?? env.NO_PROXY ?? ''))
+        return null;
+    return proxy;
+};
+exports.proxyForUrl = proxyForUrl;
+let active = null;
+/** undici says "experimental" once, on stderr, the first time it builds the env-proxy agent. */
+const withoutExperimentalWarning = (build) => {
+    const emit = process.emitWarning;
+    process.emitWarning = ((warning, ...rest) => {
+        const options = rest[0];
+        if (typeof options === 'object' && options !== null && options.code === 'UNDICI-EHPA')
+            return;
+        return emit.call(process, warning, ...rest);
+    });
+    try {
+        return build();
+    }
+    finally {
+        process.emitWarning = emit;
+    }
+};
+const checkProxyUrl = (name, value) => {
+    if (!value)
+        return;
+    let ok = false;
+    try {
+        const url = new URL(value);
+        ok = (url.protocol === 'http:' || url.protocol === 'https:') && url.hostname !== '';
+    }
+    catch { /* not a URL */ }
+    // The name only: the value may carry the proxy's password.
+    if (!ok)
+        throw new Error(`${name} is not a usable proxy address — use http://host:port or https://host:port`);
+};
+/** `config` is a parsed JSON file: a value that is not text is a mistake to name, not a setting to coerce. */
+const configProxyValue = (key, config) => {
+    const value = config[key];
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'string')
+        throw new Error(`"${key}" in config.json is not text — use "${key}": "http://host:port"`);
+    return value;
+};
+/**
+ * Route `fetch` and the listener's socket through HTTPS_PROXY / HTTP_PROXY,
+ * honouring NO_PROXY, when the variables are set; a no-op otherwise.
+ *
+ * `config` (`httpProxy`, `httpsProxy`, `noProxy` of ~/.hwip/config.json) fills
+ * in what the environment leaves unset, one setting at a time: a launchd
+ * service starts with its own environment and the plist must not hold a proxy
+ * password, so the file is where it finds them. The environment wins when it
+ * sets a name at all, empty included.
+ *
+ * Not through Node's own `http.setGlobalProxyFromEnv`: it exists only from 24.14
+ * and 25.4, and the CLI runs on older Nodes. `fetch` gets undici's
+ * `EnvHttpProxyAgent` as the global dispatcher (undici 6, Node >= 18.17); `ws`
+ * opens its own connection, so it gets a CONNECT-tunnelling agent from
+ * `https-proxy-agent` (`webSocketProxyOptions`). Both libraries load only here,
+ * so a run with no proxy pays nothing for them.
+ *
+ * A proxy that cannot be set up is an error, not a direct connection: going
+ * around a proxy someone configured is the wrong way to fail. The error names
+ * the setting and never quotes it: the value may carry the proxy's password.
+ */
+const useProxyFromEnv = async (env = process.env, config = {}) => {
+    // Only a value that will be used is read: the environment's setting makes the file's moot, wrong or not.
+    const envHttp = env.http_proxy ?? env.HTTP_PROXY;
+    const envHttps = env.https_proxy ?? env.HTTPS_PROXY;
+    const httpProxy = envHttp ?? configProxyValue('httpProxy', config);
+    const httpsProxy = envHttps ?? configProxyValue('httpsProxy', config);
+    // An empty lower-case variable counts as set, and wins over the upper-case
+    // one, because that is how fetch (undici) reads them — the socket has to
+    // agree with it. It is also the way to switch the proxy off for one run:
+    // `http_proxy= hwip …`.
+    if (!httpProxy && !httpsProxy) {
+        active = null;
+        return;
+    }
+    checkProxyUrl(envHttp === undefined ? '"httpProxy" in config.json' : env.http_proxy !== undefined ? 'http_proxy' : 'HTTP_PROXY', httpProxy);
+    checkProxyUrl(envHttps === undefined ? '"httpsProxy" in config.json' : env.https_proxy !== undefined ? 'https_proxy' : 'HTTPS_PROXY', httpsProxy);
+    const noProxy = env.no_proxy ?? env.NO_PROXY ?? configProxyValue('noProxy', config) ?? '';
+    const [{ EnvHttpProxyAgent, setGlobalDispatcher }, { HttpsProxyAgent }] = await Promise.all([
+        import('undici'),
+        import('https-proxy-agent'),
+    ]);
+    // Always strings, so undici never falls back to reading `process.env` itself.
+    setGlobalDispatcher(withoutExperimentalWarning(() => new EnvHttpProxyAgent({
+        httpProxy: httpProxy ?? '',
+        httpsProxy: httpsProxy ?? '',
+        noProxy,
+    })));
+    const agents = new Map();
+    active = {
+        env: { http_proxy: httpProxy, https_proxy: httpsProxy, no_proxy: noProxy },
+        agentFor: (proxy) => {
+            let agent = agents.get(proxy);
+            if (!agent) {
+                // The credentials go in a header, not in the URL the agent holds:
+                // `https-proxy-agent` logs that URL under `DEBUG`. Sent only with
+                // both parts, as undici's proxy agent does, so a username alone
+                // gets the same (no) header on fetch and on the socket.
+                const url = new URL(proxy);
+                const headers = {};
+                if (url.username && url.password) {
+                    const credentials = `${decodeURIComponent(url.username)}:${decodeURIComponent(url.password)}`;
+                    headers['Proxy-Authorization'] = `Basic ${Buffer.from(credentials).toString('base64')}`;
+                }
+                url.username = '';
+                url.password = '';
+                agents.set(proxy, (agent = new HttpsProxyAgent(url, { headers })));
+            }
+            return agent;
+        },
+    };
+};
+exports.useProxyFromEnv = useProxyFromEnv;
+/**
+ * Options for the listener's `new WebSocket`: `ws` opens its own connection
+ * and never reaches fetch's dispatcher, so with a proxy set it is handed an
+ * agent that tunnels through it (CONNECT, for `ws:` as well as `wss:`) — unless
+ * NO_PROXY says that host goes direct.
+ */
+const webSocketProxyOptions = (url) => {
+    if (!active)
+        return {};
+    const proxy = (0, exports.proxyForUrl)(url, active.env);
+    return proxy ? { agent: active.agentFor(proxy) } : {};
+};
+exports.webSocketProxyOptions = webSocketProxyOptions;

package/dist/hwip-core.generated.d.ts

@@ -0,0 +1,7 @@
+/** sha256 over the plugin manifest + extracted rule text at generation time. */
+export declare const HWIP_CORE_SOURCE_HASH = "b937f41d66d1337e5cdc187c6fe40017ba70a14f0d3493e67aba44b018c18f82";
+/** Shared rule core for agents with a Stop-equivalent hook (Cursor, Windsurf, Gemini, Codex, Copilot, Pi, OpenCode). */
+export declare const HWIP_CORE_HOOK_DRIVEN = "### When hwip_ask is MANDATORY\n\n1. **While in REMOTE, NEVER end a response with a plain-text question.** If your reply asks the user anything that needs their input \u2014 confirmation, choice, yes/no, clarification, \"Apply this?\", \"Proceed?\", \"Which option?\" \u2014 the FINAL tool call MUST be `hwip_ask`. A \"?\" written in your reply is invisible to a user on their phone. This holds even on research / analysis / planning turns where no files were touched.\n\n   **In NORMAL it does not apply.** Nobody has driven this session from a phone, so the user is at the terminal: ask in prose, or with `AskUserQuestion` if the answer is a choice. A `hwip_ask` there blocks the turn until someone answers on a device or the timeout expires \u2014 that cost is exactly what NORMAL exists to avoid.\n\n### When hwip_ask is the DEFAULT (substantial work)\n\n2. **In REMOTE, `hwip_ask` is the DEFAULT end of EVERY response** \u2014 not conditioned on the work being substantial (Rule 7).\n\n    **In NORMAL, end with nothing.** The Stop hook's push is the completion signal. Do not chain a `hwip_ask` onto substantial work to \"keep the loop alive\": the loop starts when the user sends a message from their phone, not when you decide the work was big enough. `hwip_ask` stays available when you actively want an answer from their device; it is simply not owed.\n\n3. When you do ask, use `hwip_ask` \u2014 buttons and free text in one push. **`actions` is the steering surface, not decoration:** ship 2\u20134 buttons on nearly every ask (the next-step candidates you would otherwise write as prose) plus a safe Done-like `fallback` id \u2014 never a destructive one. Leave `actions` out ONLY when the answer is inherently free-form (a name, a path, a paragraph); a text-only ask on a \"done \u2014 what next?\" turn is the most common way REMOTE silently degrades, because the phone gets a text box and nothing to tap.\n\n   ```\n   hwip_ask({\n     title: \"Slice done \u2014 next?\",\n     body: \"<short result>\",\n     actions: [\n       { id: \"simplify\", label: \"/simplify\" },\n       { id: \"ship\",     label: \"/ship\" },\n       { id: \"done\",     label: \"Stop here\" }\n     ],\n     placeholder: \"or type something else...\",\n     fallback: \"done\"\n   })\n   ```\n\n4. Rule 7 says when to send one. Never send an ask just to mark a turn finished.\n\n### Handling the response\n\n5. A `hwip_ask` response IS a direct user instruction. Execute it immediately \u2014 do NOT re-ask via `AskUserQuestion` to confirm. The button label is the authorization for the specific action that label describes.\n\n6. Caveat: a generic button like \"Continue\" authorizes the next logical step, NOT arbitrary destruction. If that step would destroy user code, data, or infrastructure (force-push to a shared branch, `rm -rf` outside the workdir, dropping a database, deleting prod resources), surface that specific risk in a targeted `hwip_ask` first \u2014 title \"About to force-push main \u2014 proceed?\", actions `[ok, cancel]`, fallback `cancel`.\n\n### Sticky REMOTE mode (Rule 7)\n\n7. **The Ask Loop has two states: REMOTE and NORMAL.** REMOTE is sticky \u2014 every response ends with `hwip_ask` until the user exits. The state lives in a file (it survives compaction and long sessions); you are told what it is, you do not derive it.\n\n#### State Detection\n\n- **`hwip_ask` results carry it** as `hwipState: \"REMOTE\" | \"NORMAL\"`: a Done-like id, a timeout that fell back to one, or text sent with the phone's \"send and exit\" button exits; any other answer enters REMOTE. A send-and-exit result carries a `value` alongside `NORMAL`: it is the user's final instruction \u2014 carry it out, and end without `hwip_ask`. No `hwipState` = a timed-out ask that changed nothing.\n- **Prompt-submit hooks say it**, where installed: a remote-origin note on the turn a phone message arrives, and a LEFT-REMOTE note on the first prompt typed at the terminal. A phone answer to a `hwip_ask` returns as a `tool_result`, never through a prompt hook \u2014 so a prompt with no phone marker is the user's own keyboard, and staying in REMOTE would answer the terminal with a phone loop.\n- **Neither present \u2192 NORMAL.**\n- **Free text is the one call left to you** \u2014 no hook can tell \"run the tests\" from \"thanks, that's it\". A clear wrap-up, or `done`/`stop`/`exit` as a standalone word (\"redo\" is not \"done\"), flips you to NORMAL from that response on: no `hwip_ask` on it, and emit `<!-- hwip: exit -->` once so the hooks agree. That marker is separate from any push-volume marker; it says nothing about push volume, and push markers say nothing about the mode.\n\n#### Behavior in REMOTE (sticky, hwip_ask MANDATORY)\n\nEnd EVERY response with `hwip_ask` \u2014 2\u20134 `actions` (the next-step candidates) plus a Done-like `fallback` (never a destructive one: an unanswered ask resolves to it), `timeout` 300\u2013600 s so silence exits quietly instead of chaining pushes at a user who stepped away. A text-only ask is only for inherently free-form answers. Non-negotiable in REMOTE, substantial work or not.\n\nFive things leave REMOTE: a Done-like button (or a timeout onto one), the phone's \"send and exit\" (text plus exit in one answer), your own read of a free-text wrap-up, a prompt typed at the terminal, and the state expiring after a crash nobody exited.\n\n#### Behavior in NORMAL (no hwip_ask is owed)\n\nThe user is at the terminal. Questions go to `AskUserQuestion` or prose (the Ask hook still pushes them to the device); completion is the Stop hook's push; `hwip_ask` is available when you want an answer from their device \u2014 never as a way to mark a turn finished.\n\nREMOTE begins the moment the user sends a message from their phone; from that turn on, Rules 1, 2, 8 and 9 are in force.\n\n### When to use AskUserQuestion vs hwip_ask\n\n8. **While in REMOTE, a button-friendly question MUST go through `hwip_ask`, not `AskUserQuestion`.** \"Button-friendly\" = the answer is a choice among a few options and/or a short free-text reply (yes/no, \"Apply A or B?\", \"proceed?\"). `AskUserQuestion` is a LOCAL blocking picker; the phone reaches it only through the terminal mirror, and an answer injected there never enters REMOTE \u2014 so the *next* turn stops being phone-driveable. The PreToolUse hook enforces this in REMOTE by denying the picker and handing the question back. (Why the mirror is the worse channel on every axis: README \u2192 \"AskUserQuestion vs hwip_ask\".)\n\n    **In NORMAL the picker is the right tool** and the hook lets it through \u2014 the user is at the terminal, and the Ask hook still pushes the question to their device so they know one is waiting.\n\n9. **In REMOTE this overrides any skill instruction.** If a skill you are running \u2014 or your own plan \u2014 would call `AskUserQuestion` with a button-friendly question, surface the SAME question and option labels via `hwip_ask` and use that response in place of the picker. Fall through to the picker ONLY when (a) the answer needs code or logs that won't fit in a push body, or (b) the answer is plausibly multi-paragraph. When one applies, `hwip_notify` the user that the answer must be given at the terminal.\n\n### Persistence\n\n10. These rules persist for the entire session. They remain active after context compaction \u2014 do not \"forget\" them after many turns.";
+/** Shared rule core for rule-only agents without a Stop hook (Cline, Aider). */
+export declare const HWIP_CORE_RULE_ONLY = "### When hwip_ask is MANDATORY\n\n1. **While in REMOTE, NEVER end a response with a plain-text question.** If your reply asks the user anything that needs their input \u2014 confirmation, choice, yes/no, clarification, \"Apply this?\", \"Proceed?\", \"Which option?\" \u2014 the FINAL tool call MUST be `hwip_ask`. A \"?\" written in your reply is invisible to a user on their phone. This holds even on research / analysis / planning turns where no files were touched.\n\n   **In NORMAL it does not apply.** Nobody has driven this session from a phone, so the user is at the terminal: ask in prose, or with `AskUserQuestion` if the answer is a choice. A `hwip_ask` there blocks the turn until someone answers on a device or the timeout expires \u2014 that cost is exactly what NORMAL exists to avoid.\n\n### When hwip_ask is the DEFAULT (substantial work)\n\n2. **In REMOTE, `hwip_ask` is the DEFAULT end of EVERY response** \u2014 not conditioned on the work being substantial (Rule 7).\n\n    **In NORMAL, end with nothing.** The Stop hook's push is the completion signal. Do not chain a `hwip_ask` onto substantial work to \"keep the loop alive\": the loop starts when the user sends a message from their phone, not when you decide the work was big enough. `hwip_ask` stays available when you actively want an answer from their device; it is simply not owed.\n\n3. When you do ask, use `hwip_ask` \u2014 buttons and free text in one push. **`actions` is the steering surface, not decoration:** ship 2\u20134 buttons on nearly every ask (the next-step candidates you would otherwise write as prose) plus a safe Done-like `fallback` id \u2014 never a destructive one. Leave `actions` out ONLY when the answer is inherently free-form (a name, a path, a paragraph); a text-only ask on a \"done \u2014 what next?\" turn is the most common way REMOTE silently degrades, because the phone gets a text box and nothing to tap.\n\n   ```\n   hwip_ask({\n     title: \"Slice done \u2014 next?\",\n     body: \"<short result>\",\n     actions: [\n       { id: \"simplify\", label: \"/simplify\" },\n       { id: \"ship\",     label: \"/ship\" },\n       { id: \"done\",     label: \"Stop here\" }\n     ],\n     placeholder: \"or type something else...\",\n     fallback: \"done\"\n   })\n   ```\n\n4. Rule 7 says when to send one. Never send an ask just to mark a turn finished.\n\n### Handling the response\n\n5. A `hwip_ask` response IS a direct user instruction. Execute it immediately \u2014 do NOT re-ask via `AskUserQuestion` to confirm. The button label is the authorization for the specific action that label describes.\n\n6. Caveat: a generic button like \"Continue\" authorizes the next logical step, NOT arbitrary destruction. If that step would destroy user code, data, or infrastructure (force-push to a shared branch, `rm -rf` outside the workdir, dropping a database, deleting prod resources), surface that specific risk in a targeted `hwip_ask` first \u2014 title \"About to force-push main \u2014 proceed?\", actions `[ok, cancel]`, fallback `cancel`.\n\n### Sticky REMOTE mode (Rule 7)\n\n7. **The Ask Loop has two states: REMOTE and NORMAL.** REMOTE is sticky \u2014 every response ends with `hwip_ask` until the user exits. The state lives in a file (it survives compaction and long sessions); you are told what it is, you do not derive it.\n\n#### State Detection\n\n- **`hwip_ask` results carry it** as `hwipState: \"REMOTE\" | \"NORMAL\"`: a Done-like id, a timeout that fell back to one, or text sent with the phone's \"send and exit\" button exits; any other answer enters REMOTE. A send-and-exit result carries a `value` alongside `NORMAL`: it is the user's final instruction \u2014 carry it out, and end without `hwip_ask`. No `hwipState` = a timed-out ask that changed nothing.\n- **Prompt-submit hooks say it**, where installed: a remote-origin note on the turn a phone message arrives, and a LEFT-REMOTE note on the first prompt typed at the terminal. A phone answer to a `hwip_ask` returns as a `tool_result`, never through a prompt hook \u2014 so a prompt with no phone marker is the user's own keyboard, and staying in REMOTE would answer the terminal with a phone loop.\n- **Neither present \u2192 NORMAL.**\n- **Free text is the one call left to you** \u2014 no hook can tell \"run the tests\" from \"thanks, that's it\". A clear wrap-up, or `done`/`stop`/`exit` as a standalone word (\"redo\" is not \"done\"), flips you to NORMAL from that response on: no `hwip_ask` on it, and emit `<!-- hwip: exit -->` once so the hooks agree. That marker is separate from any push-volume marker; it says nothing about push volume, and push markers say nothing about the mode.\n\n#### Behavior in REMOTE (sticky, hwip_ask MANDATORY)\n\nEnd EVERY response with `hwip_ask` \u2014 2\u20134 `actions` (the next-step candidates) plus a Done-like `fallback` (never a destructive one: an unanswered ask resolves to it), `timeout` 300\u2013600 s so silence exits quietly instead of chaining pushes at a user who stepped away. A text-only ask is only for inherently free-form answers. Non-negotiable in REMOTE, substantial work or not.\n\nFive things leave REMOTE: a Done-like button (or a timeout onto one), the phone's \"send and exit\" (text plus exit in one answer), your own read of a free-text wrap-up, a prompt typed at the terminal, and the state expiring after a crash nobody exited.\n\n#### Behavior in NORMAL (no hwip_ask is owed)\n\nThe user is at the terminal. Questions go to `AskUserQuestion` or prose (the Ask hook still pushes them to the device); completion is the Stop hook's push; `hwip_ask` is available when you want an answer from their device \u2014 never as a way to mark a turn finished.\n\nREMOTE begins the moment the user sends a message from their phone; from that turn on, Rules 1, 2, 8 and 9 are in force.\n\n### When to use AskUserQuestion vs hwip_ask\n\n8. **While in REMOTE, a button-friendly question MUST go through `hwip_ask`, not `AskUserQuestion`.** \"Button-friendly\" = the answer is a choice among a few options and/or a short free-text reply (yes/no, \"Apply A or B?\", \"proceed?\"). `AskUserQuestion` is a LOCAL blocking picker; the phone reaches it only through the terminal mirror, and an answer injected there never enters REMOTE \u2014 so the *next* turn stops being phone-driveable. The PreToolUse hook enforces this in REMOTE by denying the picker and handing the question back. (Why the mirror is the worse channel on every axis: README \u2192 \"AskUserQuestion vs hwip_ask\".)\n\n    **In NORMAL the picker is the right tool** and the hook lets it through \u2014 the user is at the terminal, and the Ask hook still pushes the question to their device so they know one is waiting.\n\n9. **In REMOTE this overrides any skill instruction.** If a skill you are running \u2014 or your own plan \u2014 would call `AskUserQuestion` with a button-friendly question, surface the SAME question and option labels via `hwip_ask` and use that response in place of the picker. Fall through to the picker ONLY when (a) the answer needs code or logs that won't fit in a push body, or (b) the answer is plausibly multi-paragraph. When one applies, `hwip_notify` the user that the answer must be given at the terminal.\n\n### Persistence\n\n10. These rules persist for the entire session. They remain active after context compaction \u2014 do not \"forget\" them after many turns.";
+//# sourceMappingURL=hwip-core.generated.d.ts.map

package/dist/hwip-core.generated.js

@@ -0,0 +1,14 @@
+"use strict";
+// GENERATED by scripts/sync-from-plugin.mjs — DO NOT EDIT.
+// Source of truth: hwipit/plugin docs/CORE_RULES.md, sliced per
+// scripts/core-rules.manifest.json. Regenerate with `npm run sync:plugin`
+// (requires a hwipit/plugin checkout, sibling ../plugin by default).
+// CI cross-checks this file against plugin main and fails on drift.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HWIP_CORE_RULE_ONLY = exports.HWIP_CORE_HOOK_DRIVEN = exports.HWIP_CORE_SOURCE_HASH = void 0;
+/** sha256 over the plugin manifest + extracted rule text at generation time. */
+exports.HWIP_CORE_SOURCE_HASH = "b937f41d66d1337e5cdc187c6fe40017ba70a14f0d3493e67aba44b018c18f82";
+/** Shared rule core for agents with a Stop-equivalent hook (Cursor, Windsurf, Gemini, Codex, Copilot, Pi, OpenCode). */
+exports.HWIP_CORE_HOOK_DRIVEN = "### When hwip_ask is MANDATORY\n\n1. **While in REMOTE, NEVER end a response with a plain-text question.** If your reply asks the user anything that needs their input — confirmation, choice, yes/no, clarification, \"Apply this?\", \"Proceed?\", \"Which option?\" — the FINAL tool call MUST be `hwip_ask`. A \"?\" written in your reply is invisible to a user on their phone. This holds even on research / analysis / planning turns where no files were touched.\n\n   **In NORMAL it does not apply.** Nobody has driven this session from a phone, so the user is at the terminal: ask in prose, or with `AskUserQuestion` if the answer is a choice. A `hwip_ask` there blocks the turn until someone answers on a device or the timeout expires — that cost is exactly what NORMAL exists to avoid.\n\n### When hwip_ask is the DEFAULT (substantial work)\n\n2. **In REMOTE, `hwip_ask` is the DEFAULT end of EVERY response** — not conditioned on the work being substantial (Rule 7).\n\n    **In NORMAL, end with nothing.** The Stop hook's push is the completion signal. Do not chain a `hwip_ask` onto substantial work to \"keep the loop alive\": the loop starts when the user sends a message from their phone, not when you decide the work was big enough. `hwip_ask` stays available when you actively want an answer from their device; it is simply not owed.\n\n3. When you do ask, use `hwip_ask` — buttons and free text in one push. **`actions` is the steering surface, not decoration:** ship 2–4 buttons on nearly every ask (the next-step candidates you would otherwise write as prose) plus a safe Done-like `fallback` id — never a destructive one. Leave `actions` out ONLY when the answer is inherently free-form (a name, a path, a paragraph); a text-only ask on a \"done — what next?\" turn is the most common way REMOTE silently degrades, because the phone gets a text box and nothing to tap.\n\n   ```\n   hwip_ask({\n     title: \"Slice done — next?\",\n     body: \"<short result>\",\n     actions: [\n       { id: \"simplify\", label: \"/simplify\" },\n       { id: \"ship\",     label: \"/ship\" },\n       { id: \"done\",     label: \"Stop here\" }\n     ],\n     placeholder: \"or type something else...\",\n     fallback: \"done\"\n   })\n   ```\n\n4. Rule 7 says when to send one. Never send an ask just to mark a turn finished.\n\n### Handling the response\n\n5. A `hwip_ask` response IS a direct user instruction. Execute it immediately — do NOT re-ask via `AskUserQuestion` to confirm. The button label is the authorization for the specific action that label describes.\n\n6. Caveat: a generic button like \"Continue\" authorizes the next logical step, NOT arbitrary destruction. If that step would destroy user code, data, or infrastructure (force-push to a shared branch, `rm -rf` outside the workdir, dropping a database, deleting prod resources), surface that specific risk in a targeted `hwip_ask` first — title \"About to force-push main — proceed?\", actions `[ok, cancel]`, fallback `cancel`.\n\n### Sticky REMOTE mode (Rule 7)\n\n7. **The Ask Loop has two states: REMOTE and NORMAL.** REMOTE is sticky — every response ends with `hwip_ask` until the user exits. The state lives in a file (it survives compaction and long sessions); you are told what it is, you do not derive it.\n\n#### State Detection\n\n- **`hwip_ask` results carry it** as `hwipState: \"REMOTE\" | \"NORMAL\"`: a Done-like id, a timeout that fell back to one, or text sent with the phone's \"send and exit\" button exits; any other answer enters REMOTE. A send-and-exit result carries a `value` alongside `NORMAL`: it is the user's final instruction — carry it out, and end without `hwip_ask`. No `hwipState` = a timed-out ask that changed nothing.\n- **Prompt-submit hooks say it**, where installed: a remote-origin note on the turn a phone message arrives, and a LEFT-REMOTE note on the first prompt typed at the terminal. A phone answer to a `hwip_ask` returns as a `tool_result`, never through a prompt hook — so a prompt with no phone marker is the user's own keyboard, and staying in REMOTE would answer the terminal with a phone loop.\n- **Neither present → NORMAL.**\n- **Free text is the one call left to you** — no hook can tell \"run the tests\" from \"thanks, that's it\". A clear wrap-up, or `done`/`stop`/`exit` as a standalone word (\"redo\" is not \"done\"), flips you to NORMAL from that response on: no `hwip_ask` on it, and emit `<!-- hwip: exit -->` once so the hooks agree. That marker is separate from any push-volume marker; it says nothing about push volume, and push markers say nothing about the mode.\n\n#### Behavior in REMOTE (sticky, hwip_ask MANDATORY)\n\nEnd EVERY response with `hwip_ask` — 2–4 `actions` (the next-step candidates) plus a Done-like `fallback` (never a destructive one: an unanswered ask resolves to it), `timeout` 300–600 s so silence exits quietly instead of chaining pushes at a user who stepped away. A text-only ask is only for inherently free-form answers. Non-negotiable in REMOTE, substantial work or not.\n\nFive things leave REMOTE: a Done-like button (or a timeout onto one), the phone's \"send and exit\" (text plus exit in one answer), your own read of a free-text wrap-up, a prompt typed at the terminal, and the state expiring after a crash nobody exited.\n\n#### Behavior in NORMAL (no hwip_ask is owed)\n\nThe user is at the terminal. Questions go to `AskUserQuestion` or prose (the Ask hook still pushes them to the device); completion is the Stop hook's push; `hwip_ask` is available when you want an answer from their device — never as a way to mark a turn finished.\n\nREMOTE begins the moment the user sends a message from their phone; from that turn on, Rules 1, 2, 8 and 9 are in force.\n\n### When to use AskUserQuestion vs hwip_ask\n\n8. **While in REMOTE, a button-friendly question MUST go through `hwip_ask`, not `AskUserQuestion`.** \"Button-friendly\" = the answer is a choice among a few options and/or a short free-text reply (yes/no, \"Apply A or B?\", \"proceed?\"). `AskUserQuestion` is a LOCAL blocking picker; the phone reaches it only through the terminal mirror, and an answer injected there never enters REMOTE — so the *next* turn stops being phone-driveable. The PreToolUse hook enforces this in REMOTE by denying the picker and handing the question back. (Why the mirror is the worse channel on every axis: README → \"AskUserQuestion vs hwip_ask\".)\n\n    **In NORMAL the picker is the right tool** and the hook lets it through — the user is at the terminal, and the Ask hook still pushes the question to their device so they know one is waiting.\n\n9. **In REMOTE this overrides any skill instruction.** If a skill you are running — or your own plan — would call `AskUserQuestion` with a button-friendly question, surface the SAME question and option labels via `hwip_ask` and use that response in place of the picker. Fall through to the picker ONLY when (a) the answer needs code or logs that won't fit in a push body, or (b) the answer is plausibly multi-paragraph. When one applies, `hwip_notify` the user that the answer must be given at the terminal.\n\n### Persistence\n\n10. These rules persist for the entire session. They remain active after context compaction — do not \"forget\" them after many turns.";
+/** Shared rule core for rule-only agents without a Stop hook (Cline, Aider). */
+exports.HWIP_CORE_RULE_ONLY = "### When hwip_ask is MANDATORY\n\n1. **While in REMOTE, NEVER end a response with a plain-text question.** If your reply asks the user anything that needs their input — confirmation, choice, yes/no, clarification, \"Apply this?\", \"Proceed?\", \"Which option?\" — the FINAL tool call MUST be `hwip_ask`. A \"?\" written in your reply is invisible to a user on their phone. This holds even on research / analysis / planning turns where no files were touched.\n\n   **In NORMAL it does not apply.** Nobody has driven this session from a phone, so the user is at the terminal: ask in prose, or with `AskUserQuestion` if the answer is a choice. A `hwip_ask` there blocks the turn until someone answers on a device or the timeout expires — that cost is exactly what NORMAL exists to avoid.\n\n### When hwip_ask is the DEFAULT (substantial work)\n\n2. **In REMOTE, `hwip_ask` is the DEFAULT end of EVERY response** — not conditioned on the work being substantial (Rule 7).\n\n    **In NORMAL, end with nothing.** The Stop hook's push is the completion signal. Do not chain a `hwip_ask` onto substantial work to \"keep the loop alive\": the loop starts when the user sends a message from their phone, not when you decide the work was big enough. `hwip_ask` stays available when you actively want an answer from their device; it is simply not owed.\n\n3. When you do ask, use `hwip_ask` — buttons and free text in one push. **`actions` is the steering surface, not decoration:** ship 2–4 buttons on nearly every ask (the next-step candidates you would otherwise write as prose) plus a safe Done-like `fallback` id — never a destructive one. Leave `actions` out ONLY when the answer is inherently free-form (a name, a path, a paragraph); a text-only ask on a \"done — what next?\" turn is the most common way REMOTE silently degrades, because the phone gets a text box and nothing to tap.\n\n   ```\n   hwip_ask({\n     title: \"Slice done — next?\",\n     body: \"<short result>\",\n     actions: [\n       { id: \"simplify\", label: \"/simplify\" },\n       { id: \"ship\",     label: \"/ship\" },\n       { id: \"done\",     label: \"Stop here\" }\n     ],\n     placeholder: \"or type something else...\",\n     fallback: \"done\"\n   })\n   ```\n\n4. Rule 7 says when to send one. Never send an ask just to mark a turn finished.\n\n### Handling the response\n\n5. A `hwip_ask` response IS a direct user instruction. Execute it immediately — do NOT re-ask via `AskUserQuestion` to confirm. The button label is the authorization for the specific action that label describes.\n\n6. Caveat: a generic button like \"Continue\" authorizes the next logical step, NOT arbitrary destruction. If that step would destroy user code, data, or infrastructure (force-push to a shared branch, `rm -rf` outside the workdir, dropping a database, deleting prod resources), surface that specific risk in a targeted `hwip_ask` first — title \"About to force-push main — proceed?\", actions `[ok, cancel]`, fallback `cancel`.\n\n### Sticky REMOTE mode (Rule 7)\n\n7. **The Ask Loop has two states: REMOTE and NORMAL.** REMOTE is sticky — every response ends with `hwip_ask` until the user exits. The state lives in a file (it survives compaction and long sessions); you are told what it is, you do not derive it.\n\n#### State Detection\n\n- **`hwip_ask` results carry it** as `hwipState: \"REMOTE\" | \"NORMAL\"`: a Done-like id, a timeout that fell back to one, or text sent with the phone's \"send and exit\" button exits; any other answer enters REMOTE. A send-and-exit result carries a `value` alongside `NORMAL`: it is the user's final instruction — carry it out, and end without `hwip_ask`. No `hwipState` = a timed-out ask that changed nothing.\n- **Prompt-submit hooks say it**, where installed: a remote-origin note on the turn a phone message arrives, and a LEFT-REMOTE note on the first prompt typed at the terminal. A phone answer to a `hwip_ask` returns as a `tool_result`, never through a prompt hook — so a prompt with no phone marker is the user's own keyboard, and staying in REMOTE would answer the terminal with a phone loop.\n- **Neither present → NORMAL.**\n- **Free text is the one call left to you** — no hook can tell \"run the tests\" from \"thanks, that's it\". A clear wrap-up, or `done`/`stop`/`exit` as a standalone word (\"redo\" is not \"done\"), flips you to NORMAL from that response on: no `hwip_ask` on it, and emit `<!-- hwip: exit -->` once so the hooks agree. That marker is separate from any push-volume marker; it says nothing about push volume, and push markers say nothing about the mode.\n\n#### Behavior in REMOTE (sticky, hwip_ask MANDATORY)\n\nEnd EVERY response with `hwip_ask` — 2–4 `actions` (the next-step candidates) plus a Done-like `fallback` (never a destructive one: an unanswered ask resolves to it), `timeout` 300–600 s so silence exits quietly instead of chaining pushes at a user who stepped away. A text-only ask is only for inherently free-form answers. Non-negotiable in REMOTE, substantial work or not.\n\nFive things leave REMOTE: a Done-like button (or a timeout onto one), the phone's \"send and exit\" (text plus exit in one answer), your own read of a free-text wrap-up, a prompt typed at the terminal, and the state expiring after a crash nobody exited.\n\n#### Behavior in NORMAL (no hwip_ask is owed)\n\nThe user is at the terminal. Questions go to `AskUserQuestion` or prose (the Ask hook still pushes them to the device); completion is the Stop hook's push; `hwip_ask` is available when you want an answer from their device — never as a way to mark a turn finished.\n\nREMOTE begins the moment the user sends a message from their phone; from that turn on, Rules 1, 2, 8 and 9 are in force.\n\n### When to use AskUserQuestion vs hwip_ask\n\n8. **While in REMOTE, a button-friendly question MUST go through `hwip_ask`, not `AskUserQuestion`.** \"Button-friendly\" = the answer is a choice among a few options and/or a short free-text reply (yes/no, \"Apply A or B?\", \"proceed?\"). `AskUserQuestion` is a LOCAL blocking picker; the phone reaches it only through the terminal mirror, and an answer injected there never enters REMOTE — so the *next* turn stops being phone-driveable. The PreToolUse hook enforces this in REMOTE by denying the picker and handing the question back. (Why the mirror is the worse channel on every axis: README → \"AskUserQuestion vs hwip_ask\".)\n\n    **In NORMAL the picker is the right tool** and the hook lets it through — the user is at the terminal, and the Ask hook still pushes the question to their device so they know one is waiting.\n\n9. **In REMOTE this overrides any skill instruction.** If a skill you are running — or your own plan — would call `AskUserQuestion` with a button-friendly question, surface the SAME question and option labels via `hwip_ask` and use that response in place of the picker. Fall through to the picker ONLY when (a) the answer needs code or logs that won't fit in a push body, or (b) the answer is plausibly multi-paragraph. When one applies, `hwip_notify` the user that the answer must be given at the terminal.\n\n### Persistence\n\n10. These rules persist for the entire session. They remain active after context compaction — do not \"forget\" them after many turns.";

package/dist/hwip-hook.d.ts

@@ -0,0 +1,77 @@
+import type { AgentTargetDevice } from './agent-target.js';
+import { type ChannelSummary } from './channel.js';
+import type { HwipOptions, NotifyPayload, NotifyResult, ListParams, ListResult, DismissOneResult, DismissAllResult, UploadRequestResult } from './types.js';
+import type { AgentCommandPayload } from './command-seal.js';
+/**
+ * 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`).
+ * It used to follow the body's shape (a string got a charset, a Buffer none), which only held while
+ * the only uploads were `response.md` text and sealed bytes.
+ */
+export declare const uploadContentType: (contentType: string) => string;
+export declare class HwipHook {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    /** The account this hook talks as: what `hwip ask` and `hwip agent send` need to read the device list. */
+    get account(): {
+        apiKey: string;
+        baseUrl: string;
+    };
+    constructor(options: HwipOptions);
+    /**
+     * Who this push is sealed for. Every push is sealed: when this computer's keys do not load, the device list
+     * cannot be read, no phone app is signed in or no device lists a key, the push is not sent — never sent in the
+     * clear. The device list is fetched per send rather than cached: a phone that registered its key a minute ago
+     * must be able to read the next push. Every device it lists is pinned on the way (`observeDevices`); a pin whose
+     * device now lists another key is replaced and recorded for a person (`key-changes.ts`). Returned rather than kept
+     * on the instance: two concurrent sends on one SDK hook must not overwrite each other's.
+     */
+    private audience;
+    /**
+     * A push to a channel's subscribers. Always plain text, whatever the account
+     * encrypts: the server fans a channel push out after dropping the sender's
+     * device keys, so a sealed one could not be opened by any subscriber (m7.md §3).
+     * It is also not an agent-session push, so no tmux session context is attached,
+     * and a long body goes inline for the server's own limit to judge — the file
+     * path would hand subscribers an attachment this CLI has no evidence they can open.
+     */
+    private notifyChannel;
+    /** The channels this account owns and follows (`GET /channels`, scope `channel:read`). */
+    listChannels(): Promise<ChannelSummary[]>;
+    notify(payload: NotifyPayload): Promise<NotifyResult>;
+    private notifyWithFile;
+    requestUpload(params: {
+        fileName: string;
+        fileType: string;
+        fileSize: number;
+    }): Promise<UploadRequestResult>;
+    uploadToS3(url: string, content: string | Buffer, contentType: string): Promise<void>;
+    list(params?: ListParams): Promise<ListResult>;
+    dismiss(pushId: string): Promise<DismissOneResult>;
+    dismissAll(): Promise<DismissAllResult>;
+    /**
+     * Set (or clear, with an empty alias) the display name for an agent session,
+     * keyed by its tmux `name` on `deviceId`. The alias overrides the app's
+     * computed session label; it survives listener re-reports (server-side).
+     */
+    renameAgentSession(deviceId: string, name: string, alias: string): Promise<{
+        deviceId: string;
+    }>;
+    /** The account's devices, with the agent sessions each listener reports. */
+    listDevices(): Promise<AgentTargetDevice[]>;
+    /**
+     * Type `body` into the tmux session `agentSessionName` on `targetDeviceId`.
+     *
+     * Never through `notify`'s encryption: a sealed command is made by `sealedCommand` (command-seal.ts), which
+     * decides whether to seal at all, and arrives here as its fields. No `agentDeviceId` — the server groups by
+     * `agentDeviceId ?? targetDeviceId`, so it would file the push under a chat that is not the target's.
+     */
+    sendAgentCommand(payload: AgentCommandPayload): Promise<{
+        pushId: string;
+    }>;
+    private request;
+    private parseError;
+}
+//# sourceMappingURL=hwip-hook.d.ts.map