salt-agent-sdk 0.1.0 → 0.19.0

package/dist/device/host.js

@@ -0,0 +1,891 @@
+"use strict";
+// The DEVICE side of device control: createDeviceHost.
+//
+// It runs ON the controlled machine, inside the signed desktop app. It takes a
+// decrypted command off the lane, decides whether it is allowed, and -- only
+// if it is -- calls the matching HANDLER. It then encrypts the result for the
+// lane readers and posts it, beats while the session is live, and reports
+// per-class counts (never content) to the server.
+//
+// ============================================================================
+// THE SEAM BOUNDARY (deliberately NOT implemented here).
+// ============================================================================
+// This module performs NO observation and NO input of any kind. It calls the
+// `DeviceHostHandlers` the desktop app injects:
+//   - observe()                      -> a UI observation
+//   - click/type/key/scroll()        -> acting on the UI
+//   - focusApp/listApps/readFile/writeFile() -> app + filesystem access
+// The host decides IF a handler may run (capability, scope, approval mode,
+// never-allowed floor, budget, rate limit, ordering) and what the device tells
+// the server afterwards (per-class counts only, never content). The handler
+// decides HOW.
+//
+// On the device side (salt-device) each handler is an ORCHESTRATOR over two OS
+// primitives, a preferred one and a sensitive fallback, kept in separate files
+// so either can be replaced on its own:
+//   - observe -> a structured UI snapshot (accessibility tree)   [preferred]
+//                falling back to a raw framebuffer grab           [sensitive]
+//   - act     -> semantic accessibility actions (press/setValue) [preferred]
+//                falling back to raw input-event synthesis        [sensitive]
+// The two sensitive primitives (framebuffer grab, event synthesis) are the only
+// pieces a safety review scrutinises, and the split keeps them small, isolated
+// and swappable while the authority model here stays reviewable on its own.
+// ============================================================================
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NEVER_ALLOWED_APPS = exports.sharedDeviceLock = exports.DeviceLock = exports.DeviceBeatOverError = exports.DeviceBudgetSpentError = void 0;
+exports.ackBody = ackBody;
+exports.createDeviceHost = createDeviceHost;
+const protocol_js_1 = require("./protocol.js");
+const node_path_1 = __importDefault(require("node:path"));
+const ids_js_1 = require("../ids.js");
+const SPEND_COUNT = {
+    command: "command",
+    look: "look",
+    act: "click",
+    observe: "observe",
+    apps: "app_focus",
+};
+/** `ctx.spend` when the grant's `max_actions` is already spent. A `DeviceProtocolError` with
+ *  code `out_of_scope`, so a handler that lets it bubble answers the agent "action budget
+ *  spent" and the host ends the session `budget_exhausted`. */
+class DeviceBudgetSpentError extends protocol_js_1.DeviceProtocolError {
+    constructor() {
+        super("out_of_scope", "action budget spent");
+        this.name = "DeviceBudgetSpentError";
+    }
+}
+exports.DeviceBudgetSpentError = DeviceBudgetSpentError;
+const ACK_NOTE_MAX = 300;
+/** The ack body: the allow-listed handler fields (typed: finite number, method: string,
+ *  verified: boolean, note: string capped at 300), then `ok: true` (which a handler cannot
+ *  override, so an old agent that only reads `ok` sees the same wire it always did). */
+function ackBody(result) {
+    const out = {};
+    if (result && typeof result === "object" && !Array.isArray(result)) {
+        const r = result;
+        if (typeof r.typed === "number" && Number.isFinite(r.typed))
+            out.typed = r.typed;
+        if (typeof r.method === "string")
+            out.method = r.method.length > ACK_NOTE_MAX ? r.method.slice(0, ACK_NOTE_MAX) : r.method;
+        if (typeof r.verified === "boolean")
+            out.verified = r.verified;
+        if (typeof r.note === "string")
+            out.note = r.note.length > ACK_NOTE_MAX ? r.note.slice(0, ACK_NOTE_MAX) : r.note;
+    }
+    out.ok = true;
+    return out;
+}
+class DeviceBeatOverError extends Error {
+}
+exports.DeviceBeatOverError = DeviceBeatOverError;
+/** A FIFO async mutex. One of these guards every mutating command (click /
+ *  type / key / scroll / focus_app) on the machine, whichever session sent it.
+ *  `sharedDeviceLock` is the process-wide instance every host uses by default,
+ *  so two sessions on one machine can never interleave input. salt-device may
+ *  pass its own via `options.deviceLock` (e.g. to also hold it around local
+ *  tray actions that inject input). */
+class DeviceLock {
+    tail = Promise.resolve();
+    /** Resolves with a release function once every earlier holder released. */
+    acquire() {
+        let release;
+        const gate = new Promise((r) => (release = r));
+        const ready = this.tail.then(() => release_once(release));
+        this.tail = this.tail.then(() => gate);
+        return ready;
+    }
+    /** Run `fn` while holding the lock. */
+    async run(fn) {
+        const release = await this.acquire();
+        try {
+            return await fn();
+        }
+        finally {
+            release();
+        }
+    }
+}
+exports.DeviceLock = DeviceLock;
+function release_once(release) {
+    let done = false;
+    return () => {
+        if (done)
+            return;
+        done = true;
+        release();
+    };
+}
+/** The process-wide device mutex (default for every host). */
+exports.sharedDeviceLock = new DeviceLock();
+/** Apps the floor never allows a command to target, whatever a mandate says:
+ *  password managers and keychains. The desktop app extends this with its own
+ *  Salt windows (which it also blanks in the capture handler). Browsers are
+ *  deliberately NOT here (owner: browsers full, no deny-list). */
+exports.NEVER_ALLOWED_APPS = [
+    "com.1password.1password",
+    "com.agilebits.onepassword7",
+    "com.apple.keychainaccess",
+    "com.apple.passwords",
+    "com.bitwarden.desktop",
+    "com.dashlane.dashlane",
+    "org.keepassxc.keepassxc",
+    "1password",
+    "bitwarden",
+    "keepassxc",
+    "keychain access",
+    "passwords",
+    "dashlane",
+];
+function createDeviceHost(snapshot, handlers, transport, callbacks = {}, options = {}) {
+    const deviceLock = options.deviceLock ?? exports.sharedDeviceLock;
+    const clock = options.now ?? Date.now;
+    const beatIntervalMs = options.beatIntervalMs ?? 5_000;
+    const progressMinIntervalMs = options.progressMinIntervalMs ?? protocol_js_1.PROGRESS_MIN_INTERVAL_MS;
+    const taskGraceMs = options.taskGraceMs ?? protocol_js_1.TASK_DEVICE_GRACE_MS;
+    const neverAllowed = (options.neverAllowedApps ?? exports.NEVER_ALLOWED_APPS).map((s) => s.toLowerCase());
+    let lastSeq = 0;
+    // Newest command this host actually executed (for lease reports).
+    let lastRanAt = null;
+    let lastRanSeq = null;
+    let pausedReason = null;
+    // One command at a time per session: every command runs behind this tail.
+    let tail = Promise.resolve();
+    // Ids received and not yet started / ids a `cancel` asked us to drop.
+    const queuedIds = new Map();
+    // Ids a `cancel` named (even before the command arrived). Bounded: oldest dropped.
+    const cancelledIds = new Set();
+    const CANCELLED_CAP = 256;
+    // What Salt has been told about our pause state (null = running).
+    let reportedPause = null;
+    let pauseSync = Promise.resolve();
+    // A device whose clock runs ahead of the sender's may see an `exp` this far in the future.
+    const EXP_SKEW_MS = 5_000;
+    // The last RESULT_CACHE_SIZE results by command id (insertion order = age).
+    const resultCache = new Map();
+    let spent = 0; // budgeted actions used
+    let ended = false;
+    const startedAt = Date.now();
+    let beatTimer = null;
+    let durationTimer = null;
+    // Rate windows: timestamps of recent commands / observes.
+    const cmdTimes = [];
+    const obsTimes = [];
+    // Pending counts to flush to the server, coalesced.
+    const pendingCounts = {};
+    let countsFlushQueued = false;
+    // Tasks being run right now, by command id: `cancel` and the end of the session abort them.
+    const runningTasks = new Map();
+    // Callers of ctx.waitWhilePaused(), released by resume().
+    const resumeWaiters = new Set();
+    function audit(entry) {
+        callbacks.onAudit?.({ at: Date.now(), ...entry });
+    }
+    function bump(cls) {
+        pendingCounts[cls] = (pendingCounts[cls] ?? 0) + 1;
+        if (countsFlushQueued || ended)
+            return;
+        countsFlushQueued = true;
+        // Flush on the next tick so a burst of commands coalesces into one PATCH.
+        queueMicrotask(async () => {
+            countsFlushQueued = false;
+            const batch = { ...pendingCounts };
+            for (const k of Object.keys(pendingCounts))
+                delete pendingCounts[k];
+            if (Object.keys(batch).length === 0)
+                return;
+            try {
+                // last_seq only rides with real work: a batch of nothing but handler
+                // failures must not look like progress (Salt extends the lease on it).
+                const work = Object.keys(batch).some((k) => k !== "error");
+                await transport.reportCounts(snapshot.sessionId, batch, work && lastRanSeq !== null ? { last_seq: lastRanSeq } : undefined);
+            }
+            catch {
+                /* counts are metadata; a failed PATCH never stops control */
+            }
+        });
+    }
+    function withinRate(op, now) {
+        while (cmdTimes.length && now - cmdTimes[0] >= 1000)
+            cmdTimes.shift();
+        while (obsTimes.length && now - obsTimes[0] >= 1000)
+            obsTimes.shift();
+        if (cmdTimes.length >= protocol_js_1.MAX_COMMANDS_PER_SECOND)
+            return false;
+        if (op === "observe" && obsTimes.length >= protocol_js_1.MAX_OBSERVE_PER_SECOND)
+            return false;
+        cmdTimes.push(now);
+        if (op === "observe")
+            obsTimes.push(now);
+        return true;
+    }
+    async function reply(header, op, body) {
+        const id = (0, protocol_js_1.deviceMessageId)();
+        const plaintext = (0, protocol_js_1.encodeDeviceMessage)({ v: protocol_js_1.DEVICE_PROTOCOL_VERSION, id, seq: nextOutSeq(), op, session: snapshot.sessionId, re: header.id }, body);
+        if (Buffer.byteLength(plaintext, "utf8") > protocol_js_1.MAX_DEVICE_PLAINTEXT_BYTES) {
+            // The result itself is too big (a huge screenshot or file). Answer the
+            // small error instead; never post an over-cap message.
+            const small = (0, protocol_js_1.encodeDeviceMessage)({ v: protocol_js_1.DEVICE_PROTOCOL_VERSION, id: (0, protocol_js_1.deviceMessageId)(), seq: nextOutSeq(), op: "error", session: snapshot.sessionId, re: header.id }, { code: "too_large", message: "result exceeds the per-message limit" });
+            await transport.postResult(small, snapshot.readers);
+            return { op: "error", body: { code: "too_large", message: "result exceeds the per-message limit" } };
+        }
+        await transport.postResult(plaintext, snapshot.readers);
+        return { op, body };
+    }
+    function remember(id, r) {
+        resultCache.delete(id);
+        resultCache.set(id, r);
+        while (resultCache.size > protocol_js_1.RESULT_CACHE_SIZE) {
+            resultCache.delete(resultCache.keys().next().value);
+        }
+    }
+    let outSeq = 0;
+    function nextOutSeq() {
+        outSeq += 1;
+        return outSeq;
+    }
+    async function refuse(header, code, message, extra = {}) {
+        audit({ commandId: header.id, op: header.op, decision: code === "needs_approval" ? "needs_approval" : "refused", code, reason: message });
+        // Refusals are not actions and are not reported as counts (they would
+        // otherwise extend the lease and spend the budget server-side).
+        return reply(header, "error", { code, message, ...extra });
+    }
+    /** Why a path is refused, or null when it is inside a root. Only absolute,
+     *  already-normalised paths are accepted (`..`, `.`, doubled or trailing
+     *  slashes are refused, never resolved), compared to the resolved roots on
+     *  segment boundaries. The device re-checks against the real filesystem
+     *  (symlinks) at I/O time. */
+    function fileScopeProblem(rule, p) {
+        if (!rule)
+            return "no files capability";
+        if (!rule.fileRoots || rule.fileRoots.length === 0)
+            return "files need an explicit root";
+        if (typeof p !== "string" || p.length === 0 || p.includes("\0"))
+            return "path must be a non-empty string";
+        if (!node_path_1.default.isAbsolute(p) || node_path_1.default.resolve(p) !== p)
+            return "path must be absolute and normalised";
+        const inside = rule.fileRoots.some((root) => {
+            const r = node_path_1.default.resolve(root);
+            return p === r || p.startsWith(r.endsWith(node_path_1.default.sep) ? r : r + node_path_1.default.sep);
+        });
+        return inside ? null : "path is outside the allowed roots";
+    }
+    /** The floor: an app named by id OR by a longer name that contains a never-allowed one
+     *  ("1Password 7 - Password Manager") is refused whatever the mandate says. */
+    function isNeverAllowed(app) {
+        const a = app.toLowerCase();
+        return neverAllowed.some((n) => a === n || a.includes(n));
+    }
+    function appInScope(rule, app) {
+        if (isNeverAllowed(app))
+            return false;
+        if (!rule)
+            return false;
+        if (!rule.apps || rule.apps.length === 0)
+            return true; // any app the floor allows
+        return rule.apps.some((a) => a.toLowerCase() === app.toLowerCase());
+    }
+    /** Entry point. Sync part: decode, drop what is not ours, handle `cancel`
+     *  immediately. Everything else queues behind the session's tail so commands
+     *  run strictly one at a time, in arrival order. */
+    async function handleCommand(plaintext) {
+        if (ended)
+            return false;
+        let decoded;
+        try {
+            decoded = (0, protocol_js_1.decodeDeviceMessage)(plaintext);
+        }
+        catch (e) {
+            // A line that looked like a device message but is malformed: we cannot
+            // trust its id to answer, so drop it. (A well-formed bad_args is answered
+            // below, once we have a header to reply to.)
+            void e;
+            return false;
+        }
+        if (!decoded)
+            return false;
+        const { header, body } = decoded;
+        // Only our active session; anything else is dropped silently.
+        if (!(0, ids_js_1.sameId)(header.session, snapshot.sessionId))
+            return false;
+        if (header.op === "cancel" && header.v === protocol_js_1.DEVICE_PROTOCOL_VERSION) {
+            // Out of band: never queued, consumes no seq. Drops a command that has
+            // not started; a started or finished one keeps its stored result.
+            // Remembered even when the command has not arrived yet (messages can
+            // reorder); processed on arrival, so a long action never delays it.
+            // The target is body `{id}` (a command) or the header's `re` (a task); a running task is
+            // aborted, which ends it `stopped`.
+            const bodyId = body?.id;
+            const id = typeof bodyId === "string" ? bodyId : header.re;
+            const running = typeof id === "string" ? runningTasks.get(id) : undefined;
+            if (running)
+                running.abort("cancelled");
+            else if (typeof id === "string" && id.length <= 64) {
+                cancelledIds.delete(id);
+                cancelledIds.add(id);
+                while (cancelledIds.size > CANCELLED_CAP)
+                    cancelledIds.delete(cancelledIds.values().next().value);
+            }
+            audit({ commandId: typeof id === "string" ? id : "-", op: "cancel", decision: "ran" });
+            return true;
+        }
+        // `stop` waits its turn like any command, but a running task must not make it wait up to
+        // `timeout_s`: tell the task now, so the stop is reached as soon as it unwinds.
+        if (header.op === "stop" && header.v === protocol_js_1.DEVICE_PROTOCOL_VERSION) {
+            for (const ac of runningTasks.values())
+                ac.abort("session_ended");
+        }
+        queuedIds.set(header.id, (queuedIds.get(header.id) ?? 0) + 1);
+        // The deadline runs on THIS device's clock from arrival: the sender's `exp`
+        // can only shorten it, never extend it.
+        const receivedAt = clock();
+        const run = tail.then(() => processCommand(header, body, receivedAt));
+        tail = run.catch(() => undefined);
+        return run;
+    }
+    async function processCommand(header, body, receivedAt) {
+        const left = (queuedIds.get(header.id) ?? 1) - 1;
+        if (left > 0)
+            queuedIds.set(header.id, left);
+        else
+            queuedIds.delete(header.id);
+        if (ended)
+            return true;
+        if (header.v !== protocol_js_1.DEVICE_PROTOCOL_VERSION) {
+            await refuse(header, "unsupported", `protocol v=${header.v}`);
+            return true;
+        }
+        // Idempotency: a repeated id returns the stored result, never re-executes.
+        const stored = resultCache.get(header.id);
+        if (stored) {
+            await reply(header, stored.op, stored.body);
+            return true;
+        }
+        if (cancelledIds.delete(header.id)) {
+            audit({ commandId: header.id, op: header.op, decision: "refused", reason: "cancelled before start" });
+            return true;
+        }
+        // Expiry: `exp` is required, and the deadline is the device's own: the
+        // sooner of the sender's `exp` and arrival + the TTL. Not executed,
+        // consumes no seq.
+        if (header.exp === undefined) {
+            await refuse(header, "bad_args", "exp is required", { expected_seq: lastSeq + 1 });
+            return true;
+        }
+        if (header.exp > receivedAt + protocol_js_1.COMMAND_TTL_MS + EXP_SKEW_MS) {
+            // Distinct from bad_args: the sender's clock is behind ours. Carries our
+            // `now` so the client can correct its offset and resend the same id.
+            await refuse(header, "clock_skew", "exp is further ahead than a command may live", { expected_seq: lastSeq + 1, now: clock() });
+            return true;
+        }
+        const deadline = Math.min(header.exp, receivedAt + protocol_js_1.COMMAND_TTL_MS);
+        if (clock() >= deadline) {
+            await refuse(header, "expired", "command expired before it started", { expected_seq: lastSeq + 1, now: clock() });
+            return true;
+        }
+        // Paused: the person (or a secure field) has the device. `stop` still works.
+        if (pausedReason !== null && header.op !== "stop") {
+            await refuse(header, "paused", `paused: ${pausedReason}`, { expected_seq: lastSeq + 1, reason: pausedReason });
+            return true;
+        }
+        // Ordering: strictly increasing seq per sender. A repeat of a KNOWN id was
+        // answered from the cache above; any other seq that is not exactly the next
+        // one (a gap, or a stale seq from a client that lost its place) is
+        // out_of_order, and the agent resyncs to expected_seq.
+        if (header.seq !== lastSeq + 1) {
+            await refuse(header, "out_of_order", `expected seq ${lastSeq + 1}, got ${header.seq}`, { expected_seq: lastSeq + 1 });
+            return true;
+        }
+        lastSeq = header.seq;
+        const op = header.op;
+        if (!AGENT_OP_SET.has(op)) {
+            await refuse(header, "unsupported", `op ${header.op}`);
+            return true;
+        }
+        if (op === "stop") {
+            await reply(header, "ended", { reason: "stopped_by_agent" });
+            await stop("stopped_by_agent");
+            return true;
+        }
+        if (op === "shell") {
+            await refuse(header, "forbidden", "shell is not available");
+            return true;
+        }
+        // Expiry / duration.
+        if (snapshot.expiresAt && Date.now() >= Date.parse(snapshot.expiresAt)) {
+            await refuse(header, "out_of_scope", "mandate expired");
+            await stop("mandate_expired");
+            return true;
+        }
+        // Capability present?
+        const capName = protocol_js_1.CAPABILITY_FOR_OP[op];
+        const rule = capName ? snapshot.caps[capName] : undefined;
+        if (capName && !rule) {
+            await refuse(header, "out_of_scope", `no ${capName} in this mandate`);
+            return true;
+        }
+        // A task needs a handler, and arguments the device would run: checked here so a task that
+        // cannot run never takes the approval, the budget or the lock.
+        let taskArgs;
+        if (op === "task") {
+            if (!handlers.task) {
+                await refuse(header, "unsupported", "this computer cannot run whole tasks");
+                return true;
+            }
+            try {
+                taskArgs = (0, protocol_js_1.parseTaskArgs)(body);
+            }
+            catch (e) {
+                await refuse(header, "bad_args", e instanceof Error ? e.message : "bad task arguments");
+                return true;
+            }
+        }
+        // Selector scope: apps and file roots.
+        if ((op === "focus_app") && !appInScope(rule, body?.app ?? "")) {
+            const app = body?.app ?? "";
+            await refuse(header, isNeverAllowed(app) ? "forbidden" : "out_of_scope", `app not in scope: ${app}`);
+            return true;
+        }
+        // Observing a named app is looking at it: the same floor applies.
+        if (op === "observe") {
+            const app = body?.app;
+            if (typeof app === "string" && isNeverAllowed(app)) {
+                await refuse(header, "forbidden", `app not in scope: ${app}`);
+                return true;
+            }
+        }
+        if (op === "read_file" || op === "write_file") {
+            const path = body?.path ?? "";
+            const problem = fileScopeProblem(rule, path);
+            if (problem) {
+                const malformed = problem.startsWith("path must be");
+                await refuse(header, malformed ? "forbidden" : "out_of_scope", `path not in scope: ${problem}`);
+                return true;
+            }
+        }
+        if (op === "write_file") {
+            const content = body?.content_b64 ?? "";
+            if (content.length > protocol_js_1.MAX_DEVICE_PLAINTEXT_BYTES) {
+                await refuse(header, "too_large", "file exceeds the per-message limit");
+                return true;
+            }
+        }
+        // Rate limit.
+        const now = Date.now();
+        if (!withinRate(op, now)) {
+            await refuse(header, "busy", "rate limit");
+            return true;
+        }
+        // Approval mode.
+        // A task is not asked about as a whole: the handler asks before each command (ctx.mode).
+        const mode = rule?.mode ?? "auto";
+        if (mode === "ask" && op !== "task") {
+            // Never wait past the command's own deadline.
+            let timer;
+            const timedOut = new Promise((resolve) => {
+                timer = setTimeout(() => resolve("timeout"), Math.max(0, deadline - clock()));
+            });
+            const asked = callbacks.requestLocalApproval
+                ? callbacks.requestLocalApproval(op, body, { timeoutMs: Math.max(0, deadline - clock()) }).catch(() => false)
+                : Promise.resolve(false);
+            const outcome = await Promise.race([asked, timedOut]);
+            if (timer)
+                clearTimeout(timer);
+            if (outcome === "timeout") {
+                await refuse(header, "expired", "command expired while waiting for approval", { expected_seq: lastSeq + 1 });
+                return true;
+            }
+            const approved = outcome;
+            if (!approved) {
+                await refuse(header, "needs_approval", "waiting for the person at the machine");
+                return true;
+            }
+        }
+        // Budget: a budgeted action is any counted op. Check BEFORE running so a
+        // spent budget never runs one more.
+        const cls = (0, protocol_js_1.countClassForOp)(op);
+        // A task is not itself an action: its steps are (ctx.spend), so it is counted but not charged.
+        const budgeted = cls !== null && cls !== "error" && op !== "task";
+        const checksBudget = budgeted || op === "task";
+        if (checksBudget && snapshot.budget?.maxActions !== undefined && spent >= snapshot.budget.maxActions) {
+            await refuse(header, "out_of_scope", "action budget spent");
+            await stop("budget_exhausted");
+            return true;
+        }
+        // Run the handler (the seam). Mutating ops hold the device-wide mutex so
+        // two sessions on one machine never interleave input.
+        try {
+            // Everything that waited (approval, the device lock, other sessions'
+            // actions) can have changed the world: re-check the session, the pause,
+            // the mandate and the deadline at the last moment, INSIDE the lock.
+            const checked = async () => {
+                const gate = lastChance(header, deadline);
+                if (gate)
+                    return gate;
+                return dispatch(op, body, header, taskArgs, rule);
+            };
+            const out = protocol_js_1.MUTATING_OPS.includes(op) ? await deviceLock.run(checked) : await checked();
+            if (isGate(out)) {
+                // Not executed: give the seq back so the sender can resend this command.
+                lastSeq = header.seq - 1;
+                if (out.silent)
+                    return true;
+                await refuse(header, out.code, out.message, { expected_seq: header.seq, reason: out.reason });
+                return true;
+            }
+            const result = out;
+            if (budgeted)
+                spent += 1;
+            lastRanAt = new Date(clock()).toISOString();
+            lastRanSeq = header.seq;
+            if (cls)
+                bump(cls);
+            audit({ commandId: header.id, op: header.op, decision: "ran" });
+            if (mode === "notify")
+                callbacks.onNotify?.(op, body);
+            remember(header.id, { op: result.op, body: result.body });
+            await reply(header, result.op, result.body);
+        }
+        catch (e) {
+            if (e instanceof DeviceBudgetSpentError) {
+                // A task spent the last of the budget and did not finish: nothing to count as an error.
+                remember(header.id, { op: "error", body: { code: e.code, message: e.message } });
+                await refuse(header, e.code, e.message);
+                await stop("budget_exhausted");
+                return true;
+            }
+            const code = e instanceof protocol_js_1.DeviceProtocolError ? e.code : "failed";
+            const message = e instanceof Error ? e.message : String(e);
+            // The person guard (paused / busy) refused INSIDE the handler: nothing
+            // ran, so report it as what it is, do not cache it and give the seq back.
+            const duck = e;
+            if (!(e instanceof protocol_js_1.DeviceProtocolError) && (duck?.code === "paused" || duck?.code === "busy")) {
+                lastSeq = header.seq - 1;
+                await refuse(header, duck.code, message, {
+                    expected_seq: header.seq,
+                    reason: typeof duck.reason === "string" ? duck.reason : undefined,
+                });
+                return true;
+            }
+            // The handler ran (or tried to): a retry by id must not run it again.
+            remember(header.id, { op: "error", body: { code, message } });
+            bump("error");
+            await refuse(header, code, message);
+            return true;
+        }
+        // End the session the moment the last budgeted action is spent.
+        if (checksBudget && snapshot.budget?.maxActions !== undefined && spent >= snapshot.budget.maxActions) {
+            await stop("budget_exhausted");
+        }
+        return true;
+    }
+    function isGate(x) {
+        return typeof x === "object" && x !== null && x.gate === true;
+    }
+    /** The last look before a handler runs. */
+    function lastChance(header, deadline) {
+        if (ended)
+            return { gate: true, code: "forbidden", message: "session ended", silent: true };
+        if (cancelledIds.delete(header.id)) {
+            audit({ commandId: header.id, op: header.op, decision: "refused", reason: "cancelled before start" });
+            return { gate: true, code: "forbidden", message: "cancelled", silent: true };
+        }
+        if (pausedReason !== null) {
+            return { gate: true, code: "paused", message: `paused: ${pausedReason}`, reason: pausedReason };
+        }
+        if (snapshot.expiresAt && clock() >= Date.parse(snapshot.expiresAt)) {
+            return { gate: true, code: "out_of_scope", message: "mandate expired" };
+        }
+        if (clock() >= deadline) {
+            return { gate: true, code: "expired", message: "command expired before it could run" };
+        }
+        return null;
+    }
+    async function dispatch(op, body, header, taskArgs, rule) {
+        switch (op) {
+            case "observe":
+                return { op: "observation", body: await handlers.observe(body ?? { target: "screen" }) };
+            case "click":
+                return { op: "ack", body: ackBody(await handlers.click(body)) };
+            case "type":
+                return { op: "ack", body: ackBody(await handlers.type(body)) };
+            case "key":
+                return { op: "ack", body: ackBody(await handlers.key(body)) };
+            case "scroll":
+                return { op: "ack", body: ackBody(await handlers.scroll(body)) };
+            case "submit":
+                return { op: "ack", body: ackBody(await handlers.submit(body)) };
+            case "focus_app":
+                return { op: "ack", body: ackBody(await handlers.focusApp(body)) };
+            case "list_apps":
+                return { op: "apps", body: await handlers.listApps() };
+            case "read_file":
+                return { op: "file", body: await handlers.readFile(body) };
+            case "write_file":
+                return { op: "ack", body: ackBody(await handlers.writeFile(body)) };
+            case "task":
+                return { op: "task_result", body: await runTask(header, taskArgs, rule) };
+            default:
+                throw new protocol_js_1.DeviceProtocolError("unsupported", op);
+        }
+    }
+    /** Note that something ran just now, so the next beat carries it and Salt moves the lease. */
+    function touchLease(header) {
+        lastRanAt = new Date(clock()).toISOString();
+        lastRanSeq = header.seq;
+    }
+    /** Run a task handler under the device lock the caller already holds. Progress goes out as
+     *  non-final results with the task's `re`, always before the final one. */
+    async function runTask(header, args, rule) {
+        const handler = handlers.task;
+        const ac = new AbortController();
+        runningTasks.set(header.id, ac);
+        const startedAt = clock();
+        const timeoutMs = args.timeout_s * 1000;
+        let over = false;
+        let lastProgressAt = Number.NEGATIVE_INFINITY;
+        let pendingProgress = null;
+        let progressTimer;
+        let postChain = Promise.resolve();
+        const sendProgress = (p) => {
+            lastProgressAt = clock();
+            touchLease(header);
+            postChain = postChain
+                .then(() => reply(header, "progress", p))
+                .then(() => undefined)
+                .catch(() => undefined); // a failed progress line never stops the task
+        };
+        const ctx = {
+            signal: ac.signal,
+            progress(p) {
+                if (over || ended)
+                    return;
+                const n = (0, protocol_js_1.normalizeProgress)(p);
+                if (!n)
+                    return;
+                const wait = progressMinIntervalMs - (clock() - lastProgressAt);
+                if (wait <= 0) {
+                    if (progressTimer)
+                        clearTimeout(progressTimer);
+                    progressTimer = undefined;
+                    pendingProgress = null;
+                    sendProgress(n);
+                    return;
+                }
+                // Too soon: keep only the newest and send it when the gap is over.
+                pendingProgress = n;
+                if (!progressTimer) {
+                    progressTimer = setTimeout(() => {
+                        progressTimer = undefined;
+                        const q = pendingProgress;
+                        pendingProgress = null;
+                        if (q && !over && !ended)
+                            sendProgress(q);
+                    }, wait);
+                }
+            },
+            spend(cls) {
+                if (over)
+                    throw new Error("the task is over");
+                if (ended)
+                    throw new protocol_js_1.DeviceProtocolError("failed", "session ended");
+                const counted = SPEND_COUNT[cls];
+                if (!counted)
+                    throw new protocol_js_1.DeviceProtocolError("bad_args", `unknown step class ${String(cls)}`);
+                const max = snapshot.budget?.maxActions;
+                if (max !== undefined && spent >= max)
+                    throw new DeviceBudgetSpentError();
+                spent += 1;
+                touchLease(header);
+                bump(counted);
+            },
+            paused: () => pausedReason,
+            waitWhilePaused() {
+                if (pausedReason === null)
+                    return Promise.resolve("running");
+                const outcome = () => (ac.signal.reason === "timeout" ? "paused_out" : "stopped");
+                if (ac.signal.aborted)
+                    return Promise.resolve(outcome());
+                return new Promise((resolve) => {
+                    const done = (v) => {
+                        resumeWaiters.delete(onResume);
+                        ac.signal.removeEventListener("abort", onAbort);
+                        resolve(v);
+                    };
+                    const onResume = () => done("running");
+                    const onAbort = () => done(outcome());
+                    resumeWaiters.add(onResume);
+                    ac.signal.addEventListener("abort", onAbort, { once: true });
+                });
+            },
+            mode: rule?.mode ?? "auto",
+            caps: Object.freeze({ ...snapshot.caps }),
+        };
+        const timers = [];
+        timers.push(setTimeout(() => ac.abort("timeout"), timeoutMs));
+        if (snapshot.expiresAt) {
+            const until = Date.parse(snapshot.expiresAt) - clock();
+            if (until < timeoutMs)
+                timers.push(setTimeout(() => ac.abort("session_ended"), Math.max(0, until)));
+        }
+        let hardTimer;
+        let outcome;
+        try {
+            const ran = (async () => handler(args, ctx))().then((value) => ({ kind: "ok", value }), (error) => ({ kind: "err", error }));
+            const hard = new Promise((resolve) => {
+                hardTimer = setTimeout(() => resolve({ kind: "hard" }), timeoutMs + taskGraceMs);
+            });
+            outcome = await Promise.race([ran, hard]);
+        }
+        finally {
+            for (const t of timers)
+                clearTimeout(t);
+            if (hardTimer)
+                clearTimeout(hardTimer);
+        }
+        over = true;
+        if (progressTimer)
+            clearTimeout(progressTimer);
+        pendingProgress = null;
+        runningTasks.delete(header.id);
+        if (outcome.kind === "hard")
+            ac.abort("timeout"); // a handler that ignored the signal is let go
+        await postChain; // every progress line goes out before the final result
+        const elapsed = Math.max(0, clock() - startedAt);
+        const cut = (status, summary) => ({
+            task_id: (0, protocol_js_1.newTaskId)(),
+            status,
+            summary,
+            checked: null,
+            steps: [],
+            commands: 0,
+            duration_ms: elapsed,
+        });
+        if (outcome.kind === "ok")
+            return (0, protocol_js_1.normalizeTaskResult)(outcome.value, { duration_ms: elapsed });
+        if (outcome.kind === "hard")
+            return cut("timeout", "The task ran out of time.");
+        if (outcome.error instanceof DeviceBudgetSpentError)
+            throw outcome.error;
+        if (ac.signal.aborted) {
+            // The handler gave up because it was told to: that is a stop or a timeout, not a failure.
+            return ac.signal.reason === "timeout" ? cut("timeout", "The task ran out of time.") : cut("stopped", "The task was stopped.");
+        }
+        throw outcome.error;
+    }
+    function start() {
+        if (ended || beatTimer)
+            return;
+        beatTimer = setInterval(async () => {
+            void syncPause(); // retry a pause/resume report that failed
+            try {
+                // Beats keep running while paused: Salt ends a paused session that stops
+                // beating after 15 s. After a command has run, every beat says so.
+                const report = {
+                    ...(lastRanAt !== null ? { last_command_at: lastRanAt, last_seq: lastRanSeq ?? undefined } : {}),
+                    ...(runningTasks.size > 0 ? { task_running: true } : {}),
+                };
+                await transport.beat(snapshot.sessionId, Object.keys(report).length ? report : undefined);
+            }
+            catch (e) {
+                if (e instanceof DeviceBeatOverError) {
+                    await stop("lost_contact");
+                }
+                // any other beat error: keep trying until the dead-man sweep ends us.
+            }
+        }, beatIntervalMs);
+        if (typeof beatTimer.unref === "function")
+            beatTimer.unref();
+        if (snapshot.budget?.maxDurationS !== undefined) {
+            const ms = Math.max(0, snapshot.budget.maxDurationS * 1000 - (Date.now() - startedAt));
+            durationTimer = setTimeout(() => void stop("duration_limit"), ms);
+            if (typeof durationTimer.unref === "function")
+                durationTimer.unref();
+        }
+    }
+    async function stop(reason = "stopped_by_device") {
+        if (ended)
+            return;
+        ended = true;
+        if (beatTimer)
+            clearInterval(beatTimer);
+        if (durationTimer)
+            clearTimeout(durationTimer);
+        beatTimer = durationTimer = null;
+        for (const ac of runningTasks.values())
+            ac.abort("session_ended");
+        audit({ commandId: "-", op: "stop", decision: "ended", reason });
+        callbacks.onEnded?.(reason);
+        try {
+            await transport.stop(snapshot.sessionId, reason);
+        }
+        catch {
+            /* subtract-only + idempotent; a failed stop still ends us locally */
+        }
+    }
+    /** Make Salt's picture of our pause state match ours. Salt only accepts a
+     *  pause from `active`, so a reason CHANGE is resume-then-pause. A failed
+     *  report is retried on the next beat (the local pause stands meanwhile). */
+    function syncPause() {
+        pauseSync = pauseSync.then(async () => {
+            if (ended)
+                return;
+            const want = pausedReason;
+            if (reportedPause === want)
+                return;
+            try {
+                if (reportedPause !== null) {
+                    await transport.resume?.(snapshot.sessionId);
+                    reportedPause = null;
+                }
+                if (want !== null) {
+                    await transport.pause?.(snapshot.sessionId, want);
+                    reportedPause = want;
+                }
+            }
+            catch {
+                /* retried on the next beat */
+            }
+        });
+        return pauseSync;
+    }
+    async function pause(reason) {
+        if (ended)
+            return;
+        const changed = pausedReason !== reason;
+        pausedReason = reason;
+        audit({ commandId: "-", op: "pause", decision: "refused", reason });
+        if (!changed)
+            return;
+        await syncPause();
+    }
+    async function resume() {
+        if (ended || pausedReason === null)
+            return;
+        pausedReason = null;
+        audit({ commandId: "-", op: "resume", decision: "ran" });
+        for (const release of [...resumeWaiters])
+            release();
+        await syncPause();
+    }
+    return { handleCommand, start, stop, actionsSpent: () => spent, pause, resume, pausedReason: () => pausedReason };
+}
+const AGENT_OP_SET = new Set([
+    "observe",
+    "click",
+    "type",
+    "key",
+    "scroll",
+    "submit",
+    "focus_app",
+    "list_apps",
+    "read_file",
+    "write_file",
+    "task",
+    "stop",
+    "cancel",
+    "shell",
+]);
+//# sourceMappingURL=host.js.map