salt-agent-sdk 0.1.0 → 0.18.0

package/dist/socket.js

@@ -0,0 +1,1038 @@
+"use strict";
+// K2 socket mode (design-fleet/runs/2026-09-17-distribution/LANES.md
+// "Socket mode contract"), now PUSH, not poll (2026-09-22, owner: "DO NOT
+// USE POLLING as a mechanic EVER"): an agent with no public URL -- OpenClaw,
+// a local LangGraph script, Claude Code on a laptop -- can't receive a
+// webhook POST. `createSocketClient` opens a real websocket to salt-api's
+// Action Cable (`AgentUpdatesChannel`) and stays connected; salt-api PUSHES
+// each envelope the instant it's written. An idle, caught-up agent makes
+// ZERO requests -- there is no interval timer anywhere in this file.
+//
+// "The same handlers" is not a promise made by convention -- it's
+// createDispatcher (webhook.ts), the one place both createWebhookServer and
+// createSocketClient end up. A consumer switches an identity from webhook
+// to socket mode by:
+//   1. calling PATCH /api/v1/agents/delivery {mode:"socket"} once (or just
+//      leaving that identity's callback blank -- salt-api treats a blank
+//      callback as socket mode regardless of this setting), and
+//   2. replacing `createWebhookServer(options).listen(port)` with
+//      `createSocketClient({...options, host, apiKey, agentId}).start()`.
+// onMessage/onCardInteraction/onInvoicePaid/onChatOpened/onHandoffConfirmed/
+// onHandoffReceived never change.
+//
+// WIRE PROTOCOL (Action Cable, `wss://<host>/cable`, the agent's own
+// `api-key` on the handshake HEADER -- never a query param, the same
+// ALB/CloudWatch-access-log-leak reasoning the REST api-key path already
+// documents -- see salt-api's ApplicationCable::Connection and
+// AgentUpdatesChannel):
+//   1. Connect. Server sends {type:"welcome"}.
+//   2. Subscribe: {command:"subscribe", identifier: JSON.stringify({channel:
+//      "AgentUpdatesChannel", after: <local cursor>})} -- `after` OMITTED
+//      entirely (not sent as 0) when there is no local cursor yet, so
+//      salt-api's own server-side ack applies instead of replaying from
+//      scratch (same convention the old poll client used).
+//   3. Server replies {type:"confirm_subscription", identifier} or
+//      {type:"reject_subscription", identifier}, then REPLAYS the backlog
+//      from the resolved cursor as ordinary envelope frames -- the same
+//      shape as a poll row, wrapped as {identifier, message: {id,
+//      delivery_id, event, headers, body, created_at}} -- ending with
+//      {identifier, message: {type:"replay_done", cursor, more?}}. Live
+//      broadcasts arrive as that identical envelope shape, interleaved with
+//      (and continuing after) the replay.
+//   4. {type:"ping", message:<unix ts>} arrives roughly every 3s -- the
+//      liveness signal. No ping for 30s means the connection is dead (a
+//      half-open TCP socket may never emit its own 'close') -- terminate
+//      and reconnect.
+//   5. {type:"disconnect", reason, reconnect} means salt-api is closing this
+//      connection on purpose (e.g. a deploy) -- always reconnect regardless
+//      of the `reconnect` value; salt-api never asks a client to stay down
+//      for good.
+//
+// CURSOR PERSISTENCE (LANES.md, fix N8): the local cursorStore is written
+// ONLY from a real poll-shaped response -- a `replay_done` frame's
+// `cursor`, a backfill GET page's `cursor`, or the ack GET's `cursor` --
+// NEVER from a live envelope frame's own `id` directly. Two different live
+// broadcasts for the same agent have no cross-broadcast ordering guarantee
+// (they can originate from two different Puma processes/transactions), so
+// persisting from whichever arrived first risks writing a cursor that's
+// ahead of one still in flight; on a later reconnect that row would never
+// be replayed again (the server's ack only ever moves forward, never
+// rewinds). Live frames are still DISPATCHED the moment they arrive (once
+// this connection has caught up) -- this restriction is only about what
+// gets written to disk / used to resume, never about delivering a message
+// to onMessage.
+//
+// A ROW THAT FAILS VERIFICATION TRANSIENTLY (a network error fetching the
+// signing key -- never a bad signature) is a harder case here than it was
+// for the poll client: a poll simply re-fetches the same un-advanced row on
+// its next round trip, but a websocket replay happens exactly once per
+// connection -- there is no "poll again" to retry a single bad row without
+// re-processing everything after it too. So this client does NOT halt the
+// rest of the stream on a transient failure (that would block every later,
+// perfectly good message behind one hiccup); instead it remembers the
+// LOWEST id that failed transiently (pendingFailureId, below) and clamps
+// every cursor persistence to stop just short of it, so the NEXT reconnect
+// naturally re-replays from that row forward -- giving it another chance
+// -- while dedupe silently no-ops whatever already succeeded the first
+// time.
+//
+// ACK: after a batch of frames is processed (replay, backfill, or live),
+// this client tells salt-api how far it got with a single, coalesced
+// `GET /api/v1/agent/updates?after=<highest processed id>&timeout=0&limit=1`
+// call -- there is no dedicated ack action on the channel; `after` on this
+// endpoint already IS salt-api's ack (see AgentUpdatesController). This is
+// event-driven: at most one ack in flight, and at most one more queued
+// behind it for whatever arrived while it was out -- never a timer. Its
+// only purpose is so a FRESH connection (a lost local cursorStore, or a
+// process that has never held one) resumes near here instead of replaying
+// up to 7 days of backlog; this client's own resume point still comes only
+// from cursorStore, per the persistence rule above.
+//
+// BACKFILL: `replay_done.more: true` means AgentUpdatesChannel's own
+// MAX_BACKLOG_REPLAY (500 rows) actually truncated the backlog. The socket
+// alone cannot deliver more than that over the wire, so this client pages
+// `GET /api/v1/agent/updates?after=<cursor>&timeout=0` (a real poll
+// response has no such cap beyond its own `limit`) until a page comes back
+// empty. This is the ONLY remaining use of the poll endpoint's `timeout`
+// parameter, and it fires only when `more` says so -- never on an
+// interval. Live frames that arrive WHILE backfill is running are buffered
+// (never dropped) and drained -- in id order RELATIVE TO EACH OTHER, never
+// interleaved with backfill's own dispatch order -- once the backfill loop
+// empties out; DedupeStore makes any overlap between a buffered live frame
+// and a backfilled row harmless either way.
+//
+// RECONNECT: on close (clean or not), a dead-ping timeout, or a rejected
+// subscription, reconnect with exponential backoff (RECONNECT_MIN_DELAY_MS
+// .. RECONNECT_MAX_DELAY_MS, jittered), resubscribing with whatever
+// cursorStore now holds. A 429 on the handshake itself (the blanket
+// api-key/ip ceiling in rack_attack.rb covers /cable the same as any other
+// path) honours Retry-After exactly like the old poll client did,
+// overriding the backoff for that one wait.
+//
+// FRAME ORDERING vs. HANDLERS THAT WAIT (fix, 2026-09-30): envelope frames are
+// still verified, deduped and dispatched strictly in arrival order through
+// one serial queue, and a handler occupies that queue until it returns. A
+// handler that does `await ctx.ask(...)` therefore blocks the queue while
+// the answer it waits for (a card tap, or the person's typed reply) is a
+// frame queued BEHIND it -- and before this fix the pings sat there too, so
+// the 30s watchdog killed the connection, the reconnect replayed the same
+// chat_opened, and every restart posted the question again. Two rules now
+// hold, and the ordering promise above is unchanged for everything else:
+//   (a) Action Cable control frames (welcome, ping, confirm/reject,
+//       disconnect) are handled the instant they arrive, never queued: they
+//       carry no ordering relative to envelopes and a busy handler must not
+//       starve the liveness watchdog.
+//   (b) An envelope that ANSWERS a pending ctx.ask (a card_interaction on
+//       its card, or the named person's plain reply -- Dispatcher.resolveAnswer)
+//       is verified and resolved at arrival, ahead of the handler queue, and
+//       is then consumed (deduped, acked) instead of queued. Everything else,
+//       including every envelope that does not answer an ask, still goes
+//       through the queue in order. Arrival itself is a second, tiny serial
+//       chain (verify + maybe decrypt only, never a handler) so relative
+//       order into the handler queue is preserved.
+// Because an early-resolved answer can be processed while an earlier row's
+// handler is still running, the ack never advances past the lowest row whose
+// handler is still in flight (ackable(), below): a crash mid-handler still
+// replays that row.
+//
+// verifyEnvelope/dispatch are unchanged from the poll-based client: every
+// envelope, however it arrived (replay, backfill page, ack response, or a
+// live frame), goes through the SAME signature check and the SAME
+// dispatcher webhook.ts uses.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PING_TIMEOUT_MS = exports.RECONNECT_MAX_DELAY_MS = exports.RECONNECT_MIN_DELAY_MS = exports.DEFAULT_DEDUPE_MAX = void 0;
+exports.MemoryCursorStore = MemoryCursorStore;
+exports.FileCursorStore = FileCursorStore;
+exports.MemoryDedupeStore = MemoryDedupeStore;
+exports.FileDedupeStore = FileDedupeStore;
+exports.createSocketClient = createSocketClient;
+const fsSync = __importStar(require("node:fs"));
+const fs = __importStar(require("node:fs/promises"));
+const node_os_1 = require("node:os");
+const path = __importStar(require("node:path"));
+const ws_1 = __importDefault(require("ws"));
+const webhook_js_1 = require("./webhook.js");
+const ask_js_1 = require("./ask.js");
+const consoleLogger = {
+    info: (msg) => console.log(msg),
+    error: (msg) => console.error(msg),
+};
+/** Lowercased, filesystem-safe form of an agent id -- used both for
+ *  defaultStateDir's own directory name and (N9) to key individual files
+ *  inside a directory that FileCursorStore/FileDedupeStore were given. */
+function safeIdSegment(agentId) {
+    return String(agentId).toLowerCase().replace(/[^a-z0-9_-]/g, "_");
+}
+/** `~/.salt/agents/<agentId>` -- the default home for BOTH the cursor and
+ *  dedupe files for one identity, unless the caller passes its own stores. */
+function defaultStateDir(agentId) {
+    return path.join((0, node_os_1.homedir)(), ".salt", "agents", safeIdSegment(agentId));
+}
+// N2/N10 (second security review, 2026-09-18): directories 0700, files
+// 0600 -- these are per-agent secrets-adjacent (a dedupe/cursor file
+// mostly isn't sensitive on its own, but the directory convention is
+// shared with sessions.ts's FileSessionStore, which DOES hold transcript
+// content, so the permission discipline is enforced once, here, for
+// every consumer of writeJsonAtomic rather than trusted to each caller).
+const DIR_MODE = 0o700;
+const FILE_MODE = 0o600;
+async function writeJsonAtomic(target, data) {
+    const dir = path.dirname(target);
+    // L3 (round 3, 2026-09-18): mkdir's return value is the path of the
+    // first directory it actually created, or undefined if the whole path
+    // already existed -- only chmod when THIS call created it. A directory
+    // that already existed is the caller's (or a previous run's) to manage;
+    // forcing 0700 on it would silently tighten permissions on something
+    // this SDK doesn't own.
+    const created = await fs.mkdir(dir, { recursive: true, mode: DIR_MODE });
+    if (created)
+        await fs.chmod(dir, DIR_MODE).catch(() => { });
+    const tmp = `${target}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
+    // The temp file is always freshly created by this call, so it's always
+    // ours to chmod.
+    await fs.writeFile(tmp, JSON.stringify(data), { mode: FILE_MODE });
+    await fs.chmod(tmp, FILE_MODE).catch(() => { });
+    await fs.rename(tmp, target);
+}
+// Creates the default state directory (0700, and only chmod'd if THIS
+// call created it -- L3, same reasoning as writeJsonAtomic above) and
+// proves it's actually writable with a probe file. Throws on failure;
+// see resolveDefaultStores below for what the caller does with that
+// (round 2 treated this as fail-closed -- refuse to start at all; round 3
+// relaxes it to a warning + in-memory fallback, since the server-side ack
+// means a lost cursor/dedupe store is no longer a replay risk).
+function ensureStateDirWritable(dir) {
+    try {
+        const created = fsSync.mkdirSync(dir, { recursive: true, mode: DIR_MODE });
+        if (created) {
+            try {
+                fsSync.chmodSync(dir, DIR_MODE);
+            }
+            catch {
+                // Best-effort; an unwritable directory still fails the probe below.
+            }
+        }
+        const probe = path.join(dir, `.writable-check-${process.pid}-${Math.random().toString(16).slice(2)}`);
+        fsSync.writeFileSync(probe, "", { mode: FILE_MODE });
+        fsSync.unlinkSync(probe);
+    }
+    catch (err) {
+        throw new Error(`state directory ${dir} could not be created or is not writable: ${err.message}`);
+    }
+}
+// Round 3 (2026-09-18): resolves the default file-backed stores for
+// whichever of cursorStore/dedupeStore the caller didn't pass explicitly,
+// falling back to in-memory stores with a clear warning log if the
+// default directory can't be created/written -- rather than round 2's
+// synchronous throw. Safe now because salt-api remembers this agent's
+// last-acked cursor server-side (the Telegram-offset model): losing the
+// local cursor/dedupe set on restart means re-fetching from the SERVER's
+// ack, at worst a small amount of re-verification/re-dedupe work, never a
+// skipped or endlessly-replayed update.
+function resolveDefaultStores(stateDir, agentId, logger) {
+    try {
+        ensureStateDirWritable(stateDir);
+        return { cursorStore: FileCursorStore(stateDir), dedupeStore: FileDedupeStore(stateDir) };
+    }
+    catch (err) {
+        logger.error(`[socket ${agentId}] WARNING: ${err.message} -- falling back to IN-MEMORY cursor/dedupe stores for ` +
+            `this run. This is safe: salt-api remembers this agent's last-acked position server-side and a subscribe/poll ` +
+            `with no local cursor resumes from there. Pass cursorStore/dedupeStore explicitly to silence this, or fix the ` +
+            `directory's permissions to restore persistence across restarts.`);
+        return { cursorStore: MemoryCursorStore(), dedupeStore: MemoryDedupeStore() };
+    }
+}
+/** In-memory cursor store. Lost on restart (a fresh process re-subscribes
+ *  from cursor 0, which resumes from salt-api's own server-side ack --
+ *  see this file's header comment). Opt in explicitly; the default is
+ *  FileCursorStore -- see createSocketClient. */
+function MemoryCursorStore() {
+    const cursors = new Map();
+    const key = (id) => String(id).toLowerCase();
+    return {
+        async get(agentId) {
+            return cursors.get(key(agentId)) ?? 0;
+        },
+        async put(agentId, cursor) {
+            cursors.set(key(agentId), cursor);
+        },
+    };
+}
+/**
+ * `<agentId>.cursor.json` inside `dir` -- written atomically (temp file +
+ * rename), the same convention sessions.ts's FileSessionStore uses. `dir`
+ * defaults to one identity's own directory (see defaultStateDir), but N9
+ * (second security review, 2026-09-18) keys the FILENAME by agent id too:
+ * a caller pointing several identities at one SHARED directory (rather
+ * than createSocketClient's per-identity default) used to collide on the
+ * same fixed `cursor.json` -- one agent's cursor silently clobbering
+ * another's. Keying by id makes a shared directory safe the same way
+ * sessions.ts's one-file-per-key convention already is.
+ */
+function FileCursorStore(dir) {
+    const fileFor = (agentId) => path.join(dir, `${safeIdSegment(agentId)}.cursor.json`);
+    return {
+        async get(agentId) {
+            try {
+                const raw = await fs.readFile(fileFor(agentId), "utf8");
+                const parsed = JSON.parse(raw);
+                return typeof parsed.cursor === "number" && Number.isFinite(parsed.cursor) ? parsed.cursor : 0;
+            }
+            catch (err) {
+                if (err.code === "ENOENT")
+                    return 0;
+                throw err;
+            }
+        },
+        async put(agentId, cursor) {
+            await writeJsonAtomic(fileFor(agentId), { cursor });
+        },
+    };
+}
+exports.DEFAULT_DEDUPE_MAX = 5000;
+/** In-memory dedupe set, bounded to the last `max` delivery ids (oldest
+ *  dropped first). Opt in explicitly; the default is FileDedupeStore. */
+function MemoryDedupeStore(max = exports.DEFAULT_DEDUPE_MAX) {
+    const seen = new Map();
+    const order = new Map();
+    const key = (id) => String(id).toLowerCase();
+    return {
+        async has(agentId, deliveryId) {
+            return seen.get(key(agentId))?.has(deliveryId) ?? false;
+        },
+        async add(agentId, deliveryId) {
+            const k = key(agentId);
+            const set = seen.get(k) ?? new Set();
+            const list = order.get(k) ?? [];
+            if (!set.has(deliveryId)) {
+                set.add(deliveryId);
+                list.push(deliveryId);
+                while (list.length > max) {
+                    const oldest = list.shift();
+                    if (oldest !== undefined)
+                        set.delete(oldest);
+                }
+            }
+            seen.set(k, set);
+            order.set(k, list);
+        },
+    };
+}
+/**
+ * `<agentId>.seen.json` inside `dir` (an ordered array of the last `max`
+ * delivery ids, oldest first) -- same atomic-write convention as
+ * FileCursorStore. N9 (second security review, 2026-09-18): the filename
+ * is keyed by agent id, same reasoning as FileCursorStore above -- a
+ * shared `dir` across identities must not let one identity's dedupe set
+ * clobber another's (or worse, let identity B's real deliveries appear
+ * "already seen" because they share a delivery_id namespace collision
+ * with identity A's file).
+ */
+function FileDedupeStore(dir, max = exports.DEFAULT_DEDUPE_MAX) {
+    const fileFor = (agentId) => path.join(dir, `${safeIdSegment(agentId)}.seen.json`);
+    const cache = new Map(); // mirrors each agent's file within one process so `has` doesn't re-read on every check
+    async function load(agentId) {
+        const key = safeIdSegment(agentId);
+        const cached = cache.get(key);
+        if (cached)
+            return cached;
+        let list;
+        try {
+            const raw = await fs.readFile(fileFor(agentId), "utf8");
+            const parsed = JSON.parse(raw);
+            list = Array.isArray(parsed) ? parsed.filter((x) => typeof x === "string") : [];
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                list = [];
+            else
+                throw err;
+        }
+        cache.set(key, list);
+        return list;
+    }
+    return {
+        async has(agentId, deliveryId) {
+            const list = await load(agentId);
+            return list.includes(deliveryId);
+        },
+        async add(agentId, deliveryId) {
+            const list = await load(agentId);
+            if (list.includes(deliveryId))
+                return;
+            list.push(deliveryId);
+            while (list.length > max)
+                list.shift();
+            cache.set(safeIdSegment(agentId), list);
+            await writeJsonAtomic(fileFor(agentId), list);
+        },
+    };
+}
+/** Exponential reconnect backoff bounds (jittered). Not a poll interval --
+ *  these only govern the wait between one dropped/closed connection and
+ *  the next connection attempt. */
+exports.RECONNECT_MIN_DELAY_MS = 1000;
+exports.RECONNECT_MAX_DELAY_MS = 60_000;
+/** No Action Cable ping for this long means the connection is presumed
+ *  dead (a half-open TCP socket may never emit its own 'close'/'error'). */
+exports.PING_TIMEOUT_MS = 30_000;
+// Honours Retry-After on a 429 -- from Rack::Attack's blanket api-key/ip
+// ceiling on the /cable handshake, or from the backfill/ack HTTP calls'
+// own throttles (N3's agent_updates_longpoll, or the blanket one on any
+// other path). Carries the parsed wait (in ms, if any) alongside the
+// thrown/returned error so the reconnect backoff can use the server's own
+// authoritative figure instead of guessing with exponential backoff, which
+// could easily be far shorter than the throttle window.
+class PollHttpError extends Error {
+    retryAfterMs;
+    constructor(message, retryAfterMs) {
+        super(message);
+        this.name = "PollHttpError";
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+// L4 (round 3, 2026-09-18): a misconfigured or hostile Retry-After must
+// not be able to park this client indefinitely -- clamp to 15 minutes,
+// comfortably above every real throttle window in rack_attack.rb (the
+// longest is the 5-minute blanket one) while still bounding the wait.
+const MAX_RETRY_AFTER_MS = 15 * 60 * 1000;
+/** Rack::Attack (and HTTP generally) sends Retry-After as either a plain
+ *  integer number of seconds or an HTTP-date; either is honoured, clamped
+ *  to MAX_RETRY_AFTER_MS. Accepts the header value however the caller's
+ *  transport hands it back (a single string, or the first of an array --
+ *  Node's http.IncomingMessage can return either for a repeated header). */
+function parseRetryAfterMs(value) {
+    const raw = Array.isArray(value) ? value[0] : value;
+    if (!raw)
+        return undefined;
+    const trimmed = raw.trim();
+    if (/^\d+$/.test(trimmed)) {
+        const seconds = Number(trimmed);
+        return Number.isFinite(seconds) ? Math.min(MAX_RETRY_AFTER_MS, Math.max(0, seconds * 1000)) : undefined;
+    }
+    const asDate = Date.parse(trimmed);
+    return Number.isNaN(asDate) ? undefined : Math.min(MAX_RETRY_AFTER_MS, Math.max(0, asDate - Date.now()));
+}
+function jitter(ms) {
+    // Half fixed, half random -- avoids a thundering herd of identical
+    // reconnect timings without making the wait unpredictably short.
+    return Math.round(ms / 2 + Math.random() * (ms / 2));
+}
+/**
+ * Drains one identity's K2 socket-mode outbox by staying connected to
+ * salt-api's `AgentUpdatesChannel` over Action Cable, verifying each
+ * envelope with the exact same check createWebhookServer applies to a
+ * webhook POST (createDispatcher's verifyEnvelope), and dispatching it to
+ * the SAME onMessage/onCardInteraction/etc. handlers. See this file's
+ * header comment for the full wire protocol, the one-line switch from
+ * createWebhookServer, and the reasoning behind cursor persistence, the
+ * ack call, backfill, and reconnect.
+ */
+function createSocketClient(options) {
+    const logger = options.logger ?? consoleLogger;
+    const dispatcher = (0, webhook_js_1.createDispatcher)(options);
+    const host = options.host.replace(/\/$/, "");
+    const wsHost = host.replace(/^http/, "ws"); // http(s):// -> ws(s)://
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const WS = options.webSocketImpl ?? ws_1.default;
+    const stateDir = defaultStateDir(options.agentId);
+    // Resolved once, synchronously, right here -- only when at least one
+    // default (file-backed) store is actually needed (a caller passing BOTH
+    // cursorStore and dedupeStore explicitly has opted out of file
+    // persistence entirely, and this directory is never touched on their
+    // behalf). Never throws on an unwritable directory -- see
+    // resolveDefaultStores.
+    const needsStateDir = options.cursorStore === undefined || options.dedupeStore === undefined;
+    const defaults = needsStateDir ? resolveDefaultStores(stateDir, options.agentId, logger) : undefined;
+    const cursorStore = options.cursorStore ?? defaults.cursorStore;
+    const dedupeStore = options.dedupeStore ?? defaults.dedupeStore;
+    const limit = options.limit ?? 100;
+    const pingTimeoutMs = options.pingTimeoutMs ?? exports.PING_TIMEOUT_MS;
+    const minBackoffMs = options.minBackoffMs ?? exports.RECONNECT_MIN_DELAY_MS;
+    const maxBackoffMs = options.maxBackoffMs ?? exports.RECONNECT_MAX_DELAY_MS;
+    const agentId = options.agentId;
+    const apiKey = options.apiKey;
+    let stopped = true;
+    let loopPromise = null;
+    let currentSocket = null;
+    let currentAbort = null;
+    let wakeSleep = null;
+    // The most recent (possibly still in-flight) ack call, so stop() can
+    // wait for it -- ack itself is deliberately fire-and-forget relative to
+    // frame dispatch (see runAck below), so nothing else awaits this chain.
+    let ackTail = Promise.resolve();
+    // See this file's header comment ("A ROW THAT FAILS VERIFICATION
+    // TRANSIENTLY..."): the lowest update id that has failed verification
+    // for a reason that might be transient and hasn't since been resolved.
+    // Every cursor persistence point clamps to stop just short of this, so
+    // the next reconnect's replay re-delivers it (and everything after --
+    // dedupe makes that overlap harmless) instead of losing it for good.
+    let pendingFailureId = null;
+    function noteTransientFailure(id) {
+        if (pendingFailureId === null || id < pendingFailureId)
+            pendingFailureId = id;
+    }
+    function noteResolved(id) {
+        if (pendingFailureId !== null && id === pendingFailureId)
+            pendingFailureId = null;
+    }
+    function clampForPersistence(candidate) {
+        return pendingFailureId === null ? candidate : Math.min(candidate, pendingFailureId - 1);
+    }
+    async function persistCursor(candidate) {
+        const safe = clampForPersistence(candidate);
+        if (safe < 0)
+            return; // nothing safe to persist yet (failure sits at/before id 0 -- can't happen in practice, guard anyway)
+        try {
+            await cursorStore.put(agentId, safe);
+        }
+        catch (err) {
+            logger.error(`[socket ${agentId}] persisting cursor ${safe} failed: ${err.message}`);
+        }
+    }
+    function sleep(ms) {
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                wakeSleep = null;
+                resolve();
+            }, ms);
+            wakeSleep = () => {
+                clearTimeout(timer);
+                wakeSleep = null;
+                resolve();
+            };
+        });
+    }
+    // Verifies + dedupes + dispatches ONE envelope, regardless of whether it
+    // arrived as a replay frame, a live frame, or a row fetched via backfill
+    // or the ack call -- all four paths funnel through here. Returns
+    // "transient" (and records pendingFailureId) for a verification failure
+    // that might resolve on retry; every other outcome ("advance") is safe
+    // to note as processed, whether that means dispatched, a deduped-skip,
+    // or a DEFINITIVE rejection (a genuinely bad signature) -- retrying a
+    // definitively bad envelope forever would just wedge this client on it.
+    async function handleOne(update) {
+        const headers = update.headers || {};
+        let result;
+        try {
+            result = await dispatcher.verifyEnvelope(headers["X-Salt-Agent-Id"], headers["X-Salt-Signature"], update.body);
+        }
+        catch (err) {
+            logger.error(`[socket ${agentId}] verifying update ${update.id} threw: ${err.message}; will retry on the next replay`);
+            noteTransientFailure(update.id);
+            return "transient";
+        }
+        if (!result.ok) {
+            if (result.transient) {
+                logger.error(`[socket ${agentId}] update ${update.id} failed verification transiently (${result.reason}); will retry on the next replay`);
+                noteTransientFailure(update.id);
+                return "transient";
+            }
+            logger.error(`[socket ${agentId}] rejected update ${update.id} (${update.event}): ${result.reason}`);
+            noteResolved(update.id);
+            return "advance";
+        }
+        noteResolved(update.id);
+        const alreadySeen = await dedupeStore.has(agentId, update.delivery_id).catch((err) => {
+            logger.error(`[socket ${agentId}] dedupe lookup for ${update.delivery_id} failed: ${err.message}`);
+            return false; // fail open on the dedupe check itself -- a lookup failure must not block real delivery
+        });
+        if (alreadySeen)
+            return "advance";
+        let body;
+        try {
+            body = JSON.parse(update.body);
+        }
+        catch (err) {
+            logger.error(`[socket ${agentId}] update ${update.id} had unparseable body: ${err.message}`);
+            return "advance";
+        }
+        // A row whose handler is still running (started on a connection that has
+        // since closed) is being handled: replaying it into a second handler is
+        // how a stuck ask used to post the same question card again per restart.
+        if (handlersInFlight.has(update.id))
+            return "advance";
+        handlersInFlight.add(update.id);
+        try {
+            await dispatcher.dispatch(body, headers["X-Salt-Agent-Id"]);
+        }
+        catch (err) {
+            logger.error(`[socket ${agentId}] unhandled error dispatching update ${update.id}: ${err.message}`);
+        }
+        finally {
+            handlersInFlight.delete(update.id);
+        }
+        await dedupeStore.add(agentId, update.delivery_id).catch((err) => {
+            logger.error(`[socket ${agentId}] recording dedupe for ${update.delivery_id} failed: ${err.message}`);
+        });
+        return "advance";
+    }
+    // --- Ack (coalesced, event-driven -- see this file's header comment) ---
+    let highestProcessed = 0;
+    // Rows whose handler is running right now (see FRAME ORDERING above).
+    const handlersInFlight = new Set();
+    function ackable() {
+        let cap = highestProcessed;
+        for (const id of handlersInFlight)
+            cap = Math.min(cap, id - 1);
+        return cap;
+    }
+    let ackInFlight = false;
+    let ackPending = false;
+    function noteProcessed(id) {
+        if (id > highestProcessed)
+            highestProcessed = id;
+    }
+    function runAck() {
+        if (stopped)
+            return;
+        if (ackable() <= 0)
+            return; // nothing processed yet (or only rows still in a handler) -- nothing to ack
+        if (ackInFlight) {
+            ackPending = true;
+            return;
+        }
+        ackInFlight = true;
+        const after = ackable();
+        ackTail = (async () => {
+            try {
+                currentAbort = new AbortController();
+                const url = `${host}/api/v1/agent/updates?timeout=0&limit=1&after=${after}`;
+                let res;
+                try {
+                    res = await fetchImpl(url, { headers: { "api-key": apiKey }, signal: currentAbort.signal });
+                }
+                finally {
+                    currentAbort = null;
+                }
+                if (!res.ok) {
+                    logger.error(`[socket ${agentId}] ack request -> ${res.status}`);
+                    return;
+                }
+                const parsed = (await res.json());
+                for (const row of parsed.updates || []) {
+                    const outcome = await handleOne(row);
+                    if (outcome === "advance")
+                        noteProcessed(row.id);
+                }
+                const finalCursor = typeof parsed.cursor === "number" ? parsed.cursor : after;
+                await persistCursor(finalCursor);
+            }
+            catch (err) {
+                if (!stopped)
+                    logger.error(`[socket ${agentId}] ack request failed: ${err.message}`);
+            }
+            finally {
+                ackInFlight = false;
+                if (ackPending) {
+                    ackPending = false;
+                    runAck();
+                }
+            }
+        })();
+    }
+    // --- Backfill (replay_done.more only -- see this file's header comment) ---
+    // Pages forward from `cursor` until a page comes back empty. Persists
+    // (clamped) after every page -- each page is a real poll-shaped response,
+    // safe to treat exactly like the old poll client's cursor advance.
+    // `isClosed` lets the CALLER's connection stop this loop promptly on an
+    // ordinary reconnect (not just the global `stopped` flag, which only
+    // stop() sets) -- see handleReplayDone's caller for why this runs
+    // detached from messageQueue in the first place.
+    async function backfillFrom(cursor, isClosed) {
+        let after = cursor;
+        let backoff = minBackoffMs;
+        while (!stopped && !isClosed()) {
+            let res;
+            try {
+                currentAbort = new AbortController();
+                const url = `${host}/api/v1/agent/updates?timeout=0&limit=${limit}&after=${after}`;
+                try {
+                    res = await fetchImpl(url, { headers: { "api-key": apiKey }, signal: currentAbort.signal });
+                }
+                finally {
+                    currentAbort = null;
+                }
+            }
+            catch (err) {
+                if (stopped || isClosed())
+                    return;
+                logger.error(`[socket ${agentId}] backfill request failed: ${err.message}; retrying in ${backoff}ms`);
+                await sleep(backoff);
+                backoff = Math.min(backoff * 2, maxBackoffMs);
+                continue;
+            }
+            if (!res.ok) {
+                if (stopped || isClosed())
+                    return;
+                logger.error(`[socket ${agentId}] backfill -> ${res.status}; retrying in ${backoff}ms`);
+                await sleep(backoff);
+                backoff = Math.min(backoff * 2, maxBackoffMs);
+                continue;
+            }
+            backoff = minBackoffMs;
+            const parsed = (await res.json());
+            const rows = parsed.updates || [];
+            for (const row of rows) {
+                const outcome = await handleOne(row);
+                if (outcome === "advance") {
+                    noteProcessed(row.id);
+                    after = row.id;
+                }
+            }
+            const finalCursor = typeof parsed.cursor === "number" ? parsed.cursor : after;
+            after = finalCursor;
+            await persistCursor(after);
+            if (rows.length === 0)
+                return; // caught up
+        }
+    }
+    // --- One websocket connection's lifecycle -----------------------------
+    // Resolves once this connection has closed (however it closed), with an
+    // optional retryAfterMs to override the next reconnect wait, and whether
+    // it ever reached confirm_subscription (a clean connection resets the
+    // exponential backoff).
+    function runConnection() {
+        return (async () => {
+            let localCursor = 0;
+            try {
+                localCursor = await cursorStore.get(agentId);
+            }
+            catch (err) {
+                logger.error(`[socket ${agentId}] loading cursor failed, starting from 0: ${err.message}`);
+            }
+            return new Promise((resolveConn) => {
+                let settled = false;
+                let subscribed = false;
+                let retryAfterMsOverride;
+                let state = "replaying";
+                let liveBuffer = [];
+                let pingTimer = null;
+                let closed = false; // this CONNECTION closed (distinct from `stopped`, the whole client) -- stops backfillTail promptly on an ordinary reconnect
+                let backfillTail = Promise.resolve();
+                // Frames must be handled strictly in arrival order, but handleOne
+                // is async -- Node's ws library can emit several buffered
+                // 'message' events synchronously before the first handler's await
+                // resolves, so without this chain two frames could be verified/
+                // dispatched out of order or concurrently. Each 'message' handler
+                // only ever appends to this chain, never awaits work directly.
+                let messageQueue = Promise.resolve();
+                function clearPingTimer() {
+                    if (pingTimer) {
+                        clearTimeout(pingTimer);
+                        pingTimer = null;
+                    }
+                }
+                function armPingWatchdog() {
+                    clearPingTimer();
+                    pingTimer = setTimeout(() => {
+                        logger.error(`[socket ${agentId}] no ping for ${pingTimeoutMs}ms; treating the connection as dead`);
+                        try {
+                            socket.terminate();
+                        }
+                        catch {
+                            // already gone
+                        }
+                    }, pingTimeoutMs);
+                }
+                function finish() {
+                    if (settled)
+                        return;
+                    settled = true;
+                    closed = true;
+                    clearPingTimer();
+                    currentSocket = null;
+                    // Wait for this connection's own backfillTail (if any) to notice
+                    // `closed` and unwind before resolving -- otherwise loop() could
+                    // start a NEW connection while this one's backfill is still
+                    // mid-flight, and stop()'s "resolves once everything has settled"
+                    // guarantee would be a lie.
+                    backfillTail.finally(() => {
+                        resolveConn({ retryAfterMs: retryAfterMsOverride, subscribed });
+                    });
+                }
+                const socket = new WS(`${wsHost}/cable`, { headers: { "api-key": apiKey } });
+                currentSocket = socket;
+                async function handleReplayDone(frame) {
+                    const serverCursor = typeof frame.cursor === "number" ? frame.cursor : localCursor;
+                    await persistCursor(serverCursor);
+                    if (frame.more) {
+                        state = "backfilling";
+                        // Deliberately NOT awaited here. This handler is one link in
+                        // messageQueue -- awaiting the whole backfill (which can take
+                        // several HTTP round trips) inside it would block every
+                        // SUBSEQUENT frame's handler from running at all until backfill
+                        // finished, since messageQueue only runs one link at a time.
+                        // That would make the `state === "backfilling"` buffering
+                        // branch below unreachable: a live frame could never actually
+                        // get buffered if its own handler never got to run in the
+                        // first place. Running it detached lets messageQueue keep
+                        // draining (buffering live frames as they arrive) while this
+                        // resolves independently; backfillTail is what finish() waits
+                        // on so stop()/reconnect still settle cleanly.
+                        backfillTail = backfillFrom(serverCursor, () => closed)
+                            .catch((err) => {
+                            logger.error(`[socket ${agentId}] backfill failed: ${err.message}`);
+                        })
+                            .then(() => {
+                            // The drain itself is routed through messageQueue too --
+                            // not just backfillFrom above -- so it can never race a
+                            // live frame that arrives (and gets appended to the
+                            // queue) in the exact window backfill just finished. Without
+                            // this, a frame queued between "snapshot the buffer" and
+                            // "flip state to live" would land in a liveBuffer nobody
+                            // ever drains again -- serializing it here means a frame
+                            // still sees state === "backfilling" (and buffers itself,
+                            // picked up by the NEXT drain -- though there is only ever
+                            // one) or runs after state flips to "live" (and takes the
+                            // ordinary live-dispatch path) -- never the gap in between.
+                            const drained = messageQueue.then(async () => {
+                                const buffered = liveBuffer.slice().sort((a, b) => a.id - b.id);
+                                liveBuffer = [];
+                                for (const row of buffered) {
+                                    const outcome = await handleOne(row);
+                                    if (outcome === "advance")
+                                        noteProcessed(row.id);
+                                }
+                                state = "live";
+                                runAck();
+                            });
+                            messageQueue = drained.catch((err) => {
+                                logger.error(`[socket ${agentId}] error draining the backfill live-frame buffer: ${err.message}`);
+                            });
+                            return messageQueue;
+                        });
+                        return;
+                    }
+                    state = "live";
+                    runAck();
+                }
+                // Control frames: handled at arrival, never queued (rule (a) in the
+                // FRAME ORDERING comment). Returns true when the frame was one.
+                function handleControl(frame) {
+                    const type = frame.type;
+                    if (type === "ping" || type === "welcome") {
+                        armPingWatchdog();
+                        return true;
+                    }
+                    if (type === "confirm_subscription") {
+                        subscribed = true;
+                        logger.info(`[socket ${agentId}] subscribed (cursor ${localCursor})`);
+                        return true;
+                    }
+                    if (type === "reject_subscription") {
+                        logger.error(`[socket ${agentId}] subscription rejected; reconnecting`);
+                        try {
+                            socket.close();
+                        }
+                        catch {
+                            // already gone
+                        }
+                        return true;
+                    }
+                    if (type === "disconnect") {
+                        // Server-initiated close (e.g. a deploy) -- the 'close' event
+                        // follows and drives reconnect the same as any other close.
+                        logger.info(`[socket ${agentId}] server requested disconnect${frame.reason ? ` (${frame.reason})` : ""}`);
+                        return true;
+                    }
+                    return false;
+                }
+                // Rule (b): settles a pending ctx.ask from an envelope that answers
+                // it, ahead of the handler queue. False for anything else (including
+                // a bad signature or a repeat delivery -- the queued path logs and
+                // skips those exactly as before).
+                async function tryEarlyAnswer(update) {
+                    if (!(0, ask_js_1.hasPendingAsks)())
+                        return false;
+                    // The row whose handler is asking must never answer itself when a
+                    // reconnect replays it.
+                    if (handlersInFlight.has(update.id))
+                        return false;
+                    const headers = update.headers || {};
+                    try {
+                        const verified = await dispatcher.verifyEnvelope(headers["X-Salt-Agent-Id"], headers["X-Salt-Signature"], update.body);
+                        if (!verified.ok)
+                            return false;
+                        if (await dedupeStore.has(agentId, update.delivery_id))
+                            return false;
+                        const body = JSON.parse(update.body);
+                        if (!(await dispatcher.resolveAnswer(body, headers["X-Salt-Agent-Id"])))
+                            return false;
+                    }
+                    catch (err) {
+                        logger.error(`[socket ${agentId}] early answer check for update ${update.id} failed: ${err.message}; queueing it normally`);
+                        return false;
+                    }
+                    noteResolved(update.id);
+                    await dedupeStore.add(agentId, update.delivery_id).catch((err) => {
+                        logger.error(`[socket ${agentId}] recording dedupe for ${update.delivery_id} failed: ${err.message}`);
+                    });
+                    noteProcessed(update.id);
+                    if (state === "live")
+                        runAck();
+                    return true;
+                }
+                async function handleFrame(frame) {
+                    const payload = frame.message;
+                    if (!payload || typeof payload !== "object")
+                        return;
+                    if (payload.type === "replay_done") {
+                        await handleReplayDone(payload);
+                        return;
+                    }
+                    if (typeof payload.id !== "number")
+                        return;
+                    const update = payload;
+                    if (state === "backfilling") {
+                        liveBuffer.push(update);
+                        return;
+                    }
+                    const outcome = await handleOne(update);
+                    if (outcome === "advance") {
+                        noteProcessed(update.id);
+                        if (state === "live")
+                            runAck();
+                    }
+                }
+                socket.on("open", () => {
+                    const identifier = localCursor > 0
+                        ? JSON.stringify({ channel: "AgentUpdatesChannel", after: localCursor })
+                        : JSON.stringify({ channel: "AgentUpdatesChannel" });
+                    socket.send(JSON.stringify({ command: "subscribe", identifier }));
+                });
+                // Arrival chain: verify + maybe decrypt an answer, never a handler, so
+                // it cannot deadlock; it only exists to keep frames entering
+                // messageQueue in arrival order while an early check is in flight.
+                let arrivalChain = Promise.resolve();
+                socket.on("message", (raw) => {
+                    let frame;
+                    try {
+                        frame = JSON.parse(raw.toString());
+                    }
+                    catch (err) {
+                        logger.error(`[socket ${agentId}] unparseable frame: ${err.message}`);
+                        return;
+                    }
+                    if (handleControl(frame))
+                        return;
+                    arrivalChain = arrivalChain
+                        .then(async () => {
+                        const payload = frame.message;
+                        if (payload && typeof payload === "object" && payload.type !== "replay_done" && typeof payload.id === "number") {
+                            if (await tryEarlyAnswer(payload))
+                                return;
+                        }
+                        messageQueue = messageQueue.then(() => handleFrame(frame)).catch((err) => {
+                            logger.error(`[socket ${agentId}] error handling frame: ${err.message}`);
+                        });
+                    })
+                        .catch((err) => {
+                        logger.error(`[socket ${agentId}] error handling frame: ${err.message}`);
+                    });
+                });
+                socket.on("unexpected-response", (_req, res) => {
+                    const status = res.statusCode;
+                    if (status === 429) {
+                        retryAfterMsOverride = parseRetryAfterMs(res.headers["retry-after"]);
+                    }
+                    logger.error(`[socket ${agentId}] handshake failed: HTTP ${status}`);
+                    res.resume(); // drain so the underlying socket can close cleanly
+                    finish(); // never wait on messageQueue: a handler parked in ctx.ask would hold the reconnect hostage
+                });
+                socket.on("close", () => {
+                    finish(); // never wait on messageQueue: a handler parked in ctx.ask would hold the reconnect hostage
+                });
+                socket.on("error", (err) => {
+                    logger.error(`[socket ${agentId}] websocket error: ${err.message}`);
+                    // 'close' normally follows an 'error' in the ws library; finish()
+                    // runs there. If it somehow doesn't, stop()'s terminate() (or a
+                    // future reconnect attempt) still recovers the process.
+                });
+            });
+        })();
+    }
+    async function loop() {
+        let backoff = minBackoffMs;
+        logger.info(`[socket ${agentId}] connecting to ${wsHost}/cable`);
+        while (!stopped) {
+            let outcome;
+            try {
+                outcome = await runConnection();
+            }
+            catch (err) {
+                logger.error(`[socket ${agentId}] connection failed: ${err.message}`);
+                outcome = { subscribed: false };
+            }
+            if (stopped)
+                break;
+            if (outcome.subscribed)
+                backoff = minBackoffMs; // a clean connection resets the failure backoff
+            const waitMs = outcome.retryAfterMs ?? jitter(backoff);
+            logger.error(`[socket ${agentId}] reconnecting in ${waitMs}ms` + (outcome.retryAfterMs !== undefined ? " (Retry-After)" : ""));
+            await sleep(waitMs);
+            backoff = Math.min(backoff * 2, maxBackoffMs);
+        }
+    }
+    return {
+        start() {
+            if (loopPromise)
+                return; // already running
+            stopped = false;
+            loopPromise = loop().catch((err) => logger.error(`[socket ${agentId}] loop exited unexpectedly: ${err.message}`));
+        },
+        async stop() {
+            stopped = true;
+            wakeSleep?.();
+            currentAbort?.abort();
+            if (currentSocket) {
+                try {
+                    currentSocket.terminate();
+                }
+                catch {
+                    // already gone
+                }
+            }
+            await loopPromise;
+            loopPromise = null;
+            await ackTail.catch(() => { });
+        },
+    };
+}
+//# sourceMappingURL=socket.js.map