salt-agent-sdk 0.21.0 → 0.23.0

package/dist/device/host.d.ts

@@ -1,5 +1,6 @@
-import { DeviceProtocolError, type AppsResult, type ClickArgs, type DeviceCountClass, type DeviceErrorCode, type DeviceOp, type DevicePauseReason, type FileResult, type KeyArgs, type ObservationResult, type ObserveArgs, type Progress, type ScrollArgs, type SubmitArgs, type TaskArgs, type TaskResult } from "./protocol.js";
+import { DeviceProtocolError, type AppsResult, type ClickArgs, type DeviceCountClass, type DeviceErrorCode, type DeviceOp, type DevicePauseReason, type FileResult, type KeyArgs, type ObservationResult, type ObserveArgs, type PointedBody, type Progress, type ScrollArgs, type StillBody, type SubmitArgs, type TaskArgs, type TaskResult } from "./protocol.js";
 import type { LaneReaders } from "./client.js";
+import { type HelpRequest, type HelpViewer } from "../help.js";
 import { type SaltId } from "../ids.js";
 /** The seams. The desktop app implements every method; the host calls one only
  *  after it has passed every gate below. A handler may throw -- the host turns
@@ -30,7 +31,24 @@ export interface DeviceHostHandlers {
      *  extra field never reaches the agent. Let a `DeviceBudgetSpentError` from `ctx.spend`
      *  bubble: it ends the task and the session. */
     task?(args: TaskArgs, ctx: DeviceTaskContext): Promise<TaskResult>;
+    /** Show Me: what is under the spot a person pointed at? Optional: a host without it answers a
+     *  point `refused: "not_allowed"`. Called only after the host accepted the point (a person over
+     *  the device, a help request or watch still open, a fresh point id). `x` and `y` are fractions
+     *  of the picture the person tapped (`obs` names the still; absent = the live frame). Return the
+     *  `screen` spot, the frontmost `app`, the `element` under it and, when the answer must be withheld,
+     *  `refused`. The host drops the element of a refused answer and of any never-allowed app, so a
+     *  handler that forgets cannot leak a name. A throw is answered `not_allowed`. */
+    resolvePoint?(args: ResolvePointArgs): Promise<ResolvedPoint>;
 }
+export interface ResolvePointArgs {
+    help_id: string;
+    obs?: string;
+    x: number;
+    y: number;
+    words: string;
+}
+/** What `resolvePoint` hands back; the host adds `help_id`, `x`, `y` and `words` itself. */
+export type ResolvedPoint = Pick<PointedBody, "screen" | "app" | "element" | "refused">;
 /** What `ctx.spend` counts a task step as. `act` is counted as a `click` (the closest of the
  *  existing classes: a press of a control) and `apps` as `app_focus`. */
 export type TaskSpendClass = "command" | "look" | "act" | "observe" | "apps";
@@ -126,7 +144,9 @@ export interface DeviceHostTransport {
      *  endpoint's shape lives is httpDeviceHostTransport (http.ts). */
     pause?(sessionId: SaltId, reason: DevicePauseReason): Promise<void>;
     /** POST /device_sessions/:sid/resume (device key). */
-    resume?(sessionId: SaltId): Promise<void>;
+    resume?(sessionId: SaltId, opts?: {
+        local?: boolean;
+    }): Promise<void>;
 }
 /** The optional body of a beat: when the device last executed a command
  *  (ISO8601) and that command's seq. Sent on every beat once one has run. */
@@ -169,6 +189,14 @@ export interface DeviceHostCallbacks {
     /** Every gate decision, for the app's append-only on-disk audit log. Content
      *  is the caller's to redact; the host passes op + decision + reason only. */
     onAudit?(entry: DeviceAuditEntry): void;
+    /** Show Me: a help request opened on this session. The app posts a still now and then stills on
+     *  change (via `host.postStill`) for ten minutes. */
+    onHelpOpened?(req: HelpRequest): void;
+    /** Show Me: the person is looking from their phone. The app posts a still now, restarts its
+     *  ten-minute window and shows "<name> is looking from their phone". */
+    onHelpViewing?(req: HelpRequest, viewer: HelpViewer | null): void;
+    /** Show Me: the help request closed (answered, withdrawn or ended). The app stops and clears its lines. */
+    onHelpClosed?(req: HelpRequest): void;
 }
 export interface DeviceAuditEntry {
     at: number;
@@ -202,9 +230,38 @@ export interface DeviceHost {
      *  interrupt a command already executing. */
     pause(reason: DevicePauseReason): Promise<void>;
     /** Clear the pause and tell Salt. No-op when not paused. */
-    resume(): Promise<void>;
+    resume(opts?: {
+        local?: boolean;
+    }): Promise<void>;
     /** The current pause reason, or null. */
     pausedReason(): DevicePauseReason | null;
+    /** Show Me: feed a lane message in together with WHO sent it (the decrypted text and the sender's
+     *  account id). Returns true when it was a `[[SALT-POINT]]` line, consumed here whether or not it
+     *  was acted on; false for anything else (pass that to `handleCommand`). A point is accepted only
+     *  from a person `options.isPersonOverDevice` names, only while its help request is open (or
+     *  `options.isWatchLive()`), and once per point id; the answer is a `pointed` op with `re` = the
+     *  point id. Every refusal is one audit line (op `point`) and no reply. */
+    handleLaneMessage(plaintext: string, senderId: SaltId): Promise<boolean>;
+    /** Also takes `device_session_paused {reason:"phone"}` / `device_session_resumed` for this session (a person
+     *  pausing from their phone): the host pauses or resumes the PHONE pause itself, never a local guard. */
+    /** Show Me: feed a `help_request_opened|viewing|closed` delivery in (the `onDeviceDelivery` type
+     *  and body). Returns true when it was one of those for THIS session and the matching callback
+     *  ran. */
+    handleDelivery(type: string, body: unknown): boolean;
+    /** Show Me: post a still into the lane (op `still`, no `re`). Resolves `{posted: true}`, or
+     *  `{posted: false, reason}` when held back: `too_soon` (under 2 s since the last one),
+     *  `budget` (the grant's `max_actions` is spent; a still the agent receives costs one `observe`),
+     *  `too_many` (30 in the last minute), `no_help` (no help request open for that id and no live
+     *  watch), `secure_field` (the session is paused for a secure field), `ended`. Throws
+     *  `bad_args` for a malformed body and `too_large` over the per-message cap. */
+    postStill(body: StillBody): Promise<{
+        posted: true;
+    } | {
+        posted: false;
+        reason: "too_soon" | "too_many" | "no_help" | "budget" | "paused" | "not_viewed" | "not_granted" | "ended";
+    }>;
+    /** The help request ids currently open on this session. */
+    openHelpIds(): string[];
 }
 export declare function createDeviceHost(snapshot: DeviceCapsSnapshot, handlers: DeviceHostHandlers, transport: DeviceHostTransport, callbacks?: DeviceHostCallbacks, options?: {
     beatIntervalMs?: number;
@@ -218,5 +275,19 @@ export declare function createDeviceHost(snapshot: DeviceCapsSnapshot, handlers:
     progressMinIntervalMs?: number;
     /** How long past `timeout_s` a task handler may run before it is cut off (default 15 s). */
     taskGraceMs?: number;
+    /** Show Me: is this account one of the device's people (owner, chain root or the session's
+     *  grantor), per the host's cached `GET /devices/:id/grants`? A point from anyone else is ignored.
+     *  Absent, every point is ignored. */
+    isPersonOverDevice?: (accountId: SaltId) => boolean;
+    /** Show Me: is a live watch call on this device right now? While it is, a point is accepted
+     *  without an open help request. Default: never. */
+    isWatchLive?: () => boolean;
+    /** Show Me: armored public keys of the people over the device (owner, root, this session's grantor).
+     *  Used when the grant lacks `device.observe` in auto or notify mode: a still is then encrypted for
+     *  these keys ONLY, never the agent's. Absent or empty in that case, stills are refused `not_granted`. */
+    peopleReaderKeys?: () => string[];
+    /** Least gap between two stills (default STILL_MIN_INTERVAL_MS, 2 s). For tests: the 30-a-minute
+     *  cap can only be reached below the default gap. */
+    stillMinIntervalMs?: number;
 }): DeviceHost;
 //# sourceMappingURL=host.d.ts.map

package/dist/device/host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/device/host.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/device/host.ts"],"names":[],"mappings":"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"}

package/dist/device/host.js

@@ -40,6 +40,7 @@ exports.ackBody = ackBody;
 exports.createDeviceHost = createDeviceHost;
 const protocol_js_1 = require("./protocol.js");
 const node_path_1 = __importDefault(require("node:path"));
+const help_js_1 = require("../help.js");
 const ids_js_1 = require("../ids.js");
 const SPEND_COUNT = {
     command: "command",
@@ -150,7 +151,17 @@ function createDeviceHost(snapshot, handlers, transport, callbacks = {}, options
     // Newest command this host actually executed (for lease reports).
     let lastRanAt = null;
     let lastRanSeq = null;
+    // The effective pause reason is a LOCAL guard pause (person_active, secure_field, person, ...) if one
+    // holds, else "phone" while the person has paused from their phone. The two are tracked apart: a
+    // phone resume never clears a local guard, and the machine's own idle resume never clears the phone.
+    let localPause = null;
+    let phonePause = false;
     let pausedReason = null;
+    // Salt still holds a phone pause that the person at this machine released; told on the next sync.
+    let serverPhoneToClear = false;
+    const recomputePause = () => {
+        pausedReason = localPause ?? (phonePause ? "phone" : 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.
@@ -816,6 +827,8 @@ function createDeviceHost(snapshot, handlers, transport, callbacks = {}, options
         beatTimer = durationTimer = null;
         for (const ac of runningTasks.values())
             ac.abort("session_ended");
+        openHelp.clear();
+        viewedHelp.clear();
         audit({ commandId: "-", op: "stop", decision: "ended", reason });
         callbacks.onEnded?.(reason);
         try {
@@ -827,15 +840,27 @@ function createDeviceHost(snapshot, handlers, transport, callbacks = {}, options
     }
     /** 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). */
+     *  report is retried on the next beat (the local pause stands meanwhile).
+     *  Only LOCAL reasons are reported; a phone pause is Salt's own, and while it holds Salt keeps
+     *  its reason whatever we report. */
     function syncPause() {
         pauseSync = pauseSync.then(async () => {
             if (ended)
                 return;
-            const want = pausedReason;
-            if (reportedPause === want)
-                return;
             try {
+                if (serverPhoneToClear) {
+                    // The person pressed Resume at this machine: the one resume Salt accepts for a phone pause.
+                    await transport.resume?.(snapshot.sessionId, { local: true });
+                    serverPhoneToClear = false;
+                    reportedPause = null;
+                }
+                const want = localPause;
+                if (phonePause) {
+                    reportedPause = want;
+                    return;
+                }
+                if (reportedPause === want)
+                    return;
                 if (reportedPause !== null) {
                     await transport.resume?.(snapshot.sessionId);
                     reportedPause = null;
@@ -854,23 +879,248 @@ function createDeviceHost(snapshot, handlers, transport, callbacks = {}, options
     async function pause(reason) {
         if (ended)
             return;
-        const changed = pausedReason !== reason;
-        pausedReason = reason;
+        if (reason === "phone") {
+            // Not a local guard: only the phone delivery path sets it.
+            return;
+        }
+        const changed = localPause !== reason;
+        localPause = reason;
+        recomputePause();
         audit({ commandId: "-", op: "pause", decision: "refused", reason });
         if (!changed)
             return;
         await syncPause();
     }
-    async function resume() {
-        if (ended || pausedReason === null)
+    /** Clear the local pause. A phone pause is cleared only by `{local: true}`: the person pressed
+     *  Resume at the machine. An automatic resume (the idle timer, the end of a secure field) leaves it. */
+    async function resume(opts = {}) {
+        if (ended)
+            return;
+        const clearPhone = opts.local === true && phonePause;
+        if (localPause === null && !clearPhone)
             return;
-        pausedReason = null;
+        localPause = null;
+        if (clearPhone) {
+            phonePause = false;
+            serverPhoneToClear = true;
+        }
+        recomputePause();
         audit({ commandId: "-", op: "resume", decision: "ran" });
-        for (const release of [...resumeWaiters])
-            release();
+        if (pausedReason === null)
+            for (const release of [...resumeWaiters])
+                release();
         await syncPause();
     }
-    return { handleCommand, start, stop, actionsSpent: () => spent, pause, resume, pausedReason: () => pausedReason };
+    // ---- Show Me: help requests, stills and points (CONTRACT.md sections 3 and 4) ----------------
+    // Help requests open on THIS session, by id. A point is acted on only while its help id is here
+    // (or a watch is live).
+    const openHelp = new Map();
+    // Help requests the person has tapped (help_request_viewing). Stills start only then.
+    const viewedHelp = new Set();
+    // Point ids already answered, oldest dropped: a replayed or re-delivered point is answered once.
+    const seenPoints = new Set();
+    const SEEN_POINTS_CAP = 256;
+    // Times of recently posted stills (the 2 s gap and the 30-a-minute window).
+    const stillTimes = [];
+    function helpFromBody(body) {
+        const hr = body?.help_request;
+        if (!hr || typeof hr !== "object")
+            return null;
+        const r = hr;
+        if (typeof r.id !== "string" || r.id === "")
+            return null;
+        // A delivery about another session is not ours.
+        if (r.device_session_id == null || !(0, ids_js_1.sameId)(r.device_session_id, snapshot.sessionId))
+            return null;
+        return r;
+    }
+    // A person pausing or resuming from their phone reaches the device as a server delivery for THIS
+    // session: `device_session_paused {session_id, reason:"phone"}` and `device_session_resumed {session_id}`.
+    // Only the phone's own reason is taken from the wire. A phone pause never replaces a local guard
+    // (it waits underneath it), and a resume clears only the phone pause, never a local guard.
+    function handleSessionPauseDelivery(type, body) {
+        const b = (body ?? {});
+        const sid = b.session_id ?? b.session?.id ?? b.id;
+        if (sid == null || !(0, ids_js_1.sameId)(sid, snapshot.sessionId))
+            return false;
+        if (type === "device_session_paused") {
+            if ((b.reason ?? b.pause_reason) !== "phone")
+                return false;
+            phonePause = true;
+            serverPhoneToClear = false;
+            recomputePause();
+            audit({ commandId: "-", op: "pause", decision: "refused", reason: "phone" });
+            return true;
+        }
+        if (!phonePause)
+            return true;
+        phonePause = false;
+        serverPhoneToClear = false;
+        reportedPause = null; // Salt is active again; re-report any local pause that still holds
+        recomputePause();
+        if (pausedReason === null)
+            for (const release of [...resumeWaiters])
+                release();
+        void syncPause();
+        return true;
+    }
+    function handleDelivery(type, body) {
+        if (ended)
+            return false;
+        if (type === "device_session_paused" || type === "device_session_resumed")
+            return handleSessionPauseDelivery(type, body);
+        if (!help_js_1.HELP_DELIVERY_TYPES.includes(type))
+            return false;
+        if (ended)
+            return false;
+        const req = helpFromBody(body);
+        if (!req)
+            return false;
+        if (type === "help_request_opened") {
+            openHelp.set(req.id, req);
+            callbacks.onHelpOpened?.(req);
+        }
+        else if (type === "help_request_viewing") {
+            openHelp.set(req.id, req);
+            viewedHelp.add(req.id);
+            const v = body.viewer;
+            callbacks.onHelpViewing?.(req, v && typeof v === "object" && typeof v.id === "string" ? v : null);
+        }
+        else {
+            openHelp.delete(req.id);
+            viewedHelp.delete(req.id);
+            callbacks.onHelpClosed?.(req);
+        }
+        return true;
+    }
+    function helpAllowsStills(helpId) {
+        return openHelp.has(helpId) || (options.isWatchLive?.() ?? false);
+    }
+    async function postStill(raw) {
+        if (ended)
+            return { posted: false, reason: "ended" };
+        const body = (0, protocol_js_1.normalizeStill)(raw);
+        if (!body)
+            throw new protocol_js_1.DeviceProtocolError("bad_args", "malformed still");
+        if (!helpAllowsStills(body.help_id))
+            return { posted: false, reason: "no_help" };
+        // Never while paused, for any reason (the person has the computer, a secure field, the phone).
+        if (pausedReason !== null)
+            return { posted: false, reason: "paused" };
+        // Only after the person tapped (help_request_viewing), never on `opened`. A live watch is its own consent.
+        if (!viewedHelp.has(body.help_id) && !(options.isWatchLive?.() ?? false))
+            return { posted: false, reason: "not_viewed" };
+        // A picture goes to the agent only when its grant allows observing. Otherwise it goes to the people
+        // over the device alone (the lane readers minus the agent), which the transport can do because every
+        // post names its readers.
+        const observeMode = snapshot.caps["device.observe"]?.mode;
+        const agentMayObserve = observeMode === "auto" || observeMode === "notify";
+        let readers = snapshot.readers;
+        if (!agentMayObserve) {
+            const keys = options.peopleReaderKeys?.() ?? [];
+            if (keys.length === 0)
+                return { posted: false, reason: "not_granted" };
+            readers = { ...snapshot.readers, publicKeys: keys };
+        }
+        const now = clock();
+        while (stillTimes.length && now - stillTimes[0] >= 60_000)
+            stillTimes.shift();
+        if (stillTimes.length && now - stillTimes[stillTimes.length - 1] < (options.stillMinIntervalMs ?? protocol_js_1.STILL_MIN_INTERVAL_MS))
+            return { posted: false, reason: "too_soon" };
+        if (stillTimes.length >= protocol_js_1.STILL_MAX_PER_MINUTE)
+            return { posted: false, reason: "too_many" };
+        // A still the agent receives is an observation: it counts against the session's action budget and
+        // the per-second observe cap. A people-only still (agent not granted) is the agent's no business.
+        const maxActions = snapshot.budget?.maxActions;
+        if (agentMayObserve) {
+            if (maxActions !== undefined && spent >= maxActions)
+                return { posted: false, reason: "budget" };
+            while (obsTimes.length && now - obsTimes[0] >= 1000)
+                obsTimes.shift();
+            if (obsTimes.length >= protocol_js_1.MAX_OBSERVE_PER_SECOND)
+                return { posted: false, reason: "too_soon" };
+        }
+        const plaintext = (0, protocol_js_1.encodeDeviceMessage)({ v: protocol_js_1.DEVICE_PROTOCOL_VERSION, id: (0, protocol_js_1.deviceMessageId)(), seq: nextOutSeq(), op: "still", session: snapshot.sessionId }, body);
+        if (Buffer.byteLength(plaintext, "utf8") > protocol_js_1.MAX_DEVICE_PLAINTEXT_BYTES)
+            throw new protocol_js_1.DeviceProtocolError("too_large", "still exceeds the per-message limit");
+        stillTimes.push(now);
+        await transport.postResult(plaintext, readers);
+        if (agentMayObserve) {
+            spent += 1;
+            obsTimes.push(now);
+            bump("observe");
+            // Spending the last action does not end the session here: the next still is refused "budget" and
+            // the next command hits the budget gate, which ends it (budget_exhausted).
+        }
+        return { posted: true };
+    }
+    function pointRefused(pointId, why) {
+        audit({ commandId: pointId, op: "point", decision: "refused", code: "forbidden", reason: why });
+    }
+    async function handleLaneMessage(plaintext, senderId) {
+        if (!(0, protocol_js_1.isPointMessage)(plaintext))
+            return false;
+        if (ended)
+            return true;
+        let point;
+        try {
+            point = (0, protocol_js_1.decodePoint)(plaintext);
+        }
+        catch (e) {
+            pointRefused("-", `malformed point: ${e.message}`);
+            return true;
+        }
+        if (!point)
+            return true;
+        if (!options.isPersonOverDevice?.(senderId)) {
+            pointRefused(point.id, "sender is not a person over this device");
+            return true;
+        }
+        if (!helpAllowsStills(point.help)) {
+            pointRefused(point.id, "no open help request for that id");
+            return true;
+        }
+        if (seenPoints.has(point.id)) {
+            pointRefused(point.id, "point id already answered");
+            return true;
+        }
+        seenPoints.add(point.id);
+        while (seenPoints.size > SEEN_POINTS_CAP)
+            seenPoints.delete(seenPoints.values().next().value);
+        let resolved = null;
+        let refused = null;
+        if (!handlers.resolvePoint) {
+            refused = "not_allowed";
+        }
+        else {
+            try {
+                resolved = await handlers.resolvePoint({ help_id: point.help, obs: point.obs, x: point.x, y: point.y, words: point.words });
+            }
+            catch {
+                refused = "not_allowed";
+            }
+        }
+        // The floor, again: never name anything in a never-allowed app, whatever the handler said.
+        if (resolved && refused === null) {
+            refused = resolved.refused ?? null;
+            if (refused === null && resolved.app && isNeverAllowed(resolved.app))
+                refused = "forbidden_app";
+        }
+        const answer = (0, protocol_js_1.normalizePointed)({
+            help_id: point.help,
+            x: point.x,
+            y: point.y,
+            screen: resolved?.screen ?? { x: 0, y: 0 },
+            app: refused === "forbidden_app" ? null : (resolved?.app ?? null),
+            element: refused === null ? (resolved?.element ?? null) : null,
+            refused,
+            words: point.words,
+        }) ?? { help_id: point.help, x: point.x, y: point.y, screen: { x: 0, y: 0 }, app: null, element: null, refused: "not_allowed", words: "" };
+        audit({ commandId: point.id, op: "point", decision: "ran", reason: answer.refused ?? undefined });
+        await reply({ id: point.id }, "pointed", answer);
+        return true;
+    }
+    return { handleCommand, start, stop, actionsSpent: () => spent, pause, resume, pausedReason: () => pausedReason, handleLaneMessage, handleDelivery, postStill, openHelpIds: () => [...openHelp.keys()] };
 }
 const AGENT_OP_SET = new Set([
     "observe",