@rome-os/node-core 0.1.2 → 0.1.4

package/README.md

@@ -121,6 +121,30 @@ same environment to `nodeConfigFromEnvironment()` as the CLI to honor
 `ROME_NODE_CONFIG_DIR`, `ROME_NODE_DAEMON_PORT`, and platform defaults.
 The library does not select an environment implicitly.
 
+## Activity console
+
+The daemon records the actions it sends in `observe.db`. Read them with
+`node.status`, `log.query`, `log.stats`, and the `node` event topic of the
+[local protocol](../../docs/rome-node.md#activity-log).
+
+A backend that serves a browser console puts `openConsoleBridge` between the
+browser socket and the daemon:
+
+```ts
+import { nodeConfigFromEnvironment, openConsoleBridge } from "@rome-os/node-core/client";
+
+const bridge = openConsoleBridge(nodeConfigFromEnvironment(process.env), {
+  send: (text) => socket.send(text),
+  close: () => socket.close(),
+});
+socket.on("message", (data) => bridge.receive(data.toString()));
+socket.on("close", () => bridge.close());
+```
+
+The bridge never starts the daemon. It forwards only the observation methods.
+When no daemon answers, it sends `console.daemon` with state `not_configured`,
+`not_running`, `incompatible`, or `disconnected`, then closes.
+
 ## Caller authorization
 
 ```ts
@@ -166,7 +190,9 @@ await running;
 ```
 
 `showAuthorizationUrl` and `updateApplicationState` are application callbacks.
-A custom credential store implements `load`, `save`, and `clear`. The built-in
+A custom credential store implements `load`, `save`, and `clear`. A stored token
+is either a computer credential from `loginDevice` or `loginDeviceCode`, or the
+Rome desktop app's own Rome Cloud sign-in. The built-in
 login adapter uses a temporary loopback callback listener. Applications can
 supply their own authorization function returning a device session.
 

package/dist/connect.js

@@ -15,7 +15,7 @@ export async function connectHost(options) {
     let session = isRecord(stored) &&
         stored.cloudUrl === cloudUrl &&
         typeof stored.token === "string" &&
-        /^romedev_[A-Za-z0-9_-]{43}$/.test(stored.token) &&
+        /^(?:romedev|romemob)_[A-Za-z0-9_-]{43}$/.test(stored.token) &&
         validId(stored.deviceId) &&
         typeof stored.name === "string"
         ? { cloudUrl, token: stored.token, deviceId: stored.deviceId, name: stored.name }

package/dist/console.d.ts

@@ -0,0 +1,12 @@
+import { type NodeConfig } from "./local.js";
+export declare const MAX_CONSOLE_MESSAGE_BYTES: number;
+export type ConsoleDaemonState = "not_configured" | "not_running" | "incompatible" | "disconnected";
+export interface ConsoleTransport {
+    send(text: string): void;
+    close(): void;
+}
+export interface ConsoleBridge {
+    receive(text: string): void;
+    close(): void;
+}
+export declare function openConsoleBridge(config: NodeConfig, transport: ConsoleTransport): ConsoleBridge;

package/dist/console.js

@@ -0,0 +1,101 @@
+import { isRecord } from "./actions.js";
+import { findDaemon } from "./daemon-control.js";
+import { DaemonVersionError, RpcError } from "./daemon-rpc.js";
+import { readOptionalCallerCredential } from "./local.js";
+export const MAX_CONSOLE_MESSAGE_BYTES = 64 * 1024;
+const READ_METHODS = new Set(["node.status", "log.query", "log.stats"]);
+export function openConsoleBridge(config, transport) {
+    let closed = false;
+    let rpc;
+    const queued = [];
+    const lifetime = new AbortController();
+    const finish = (state) => {
+        if (closed)
+            return;
+        closed = true;
+        lifetime.abort();
+        if (state)
+            transport.send(JSON.stringify({ jsonrpc: "2.0", method: "console.daemon", params: { state } }));
+        rpc?.close();
+        transport.close();
+    };
+    const reply = (id, body) => {
+        if (!closed)
+            transport.send(JSON.stringify({ jsonrpc: "2.0", id, ...body }));
+    };
+    function forward(text) {
+        let message;
+        try {
+            message = JSON.parse(text);
+        }
+        catch {
+            reply(null, { error: { code: -32700, message: "Parse error" } });
+            return;
+        }
+        if (!isRecord(message) ||
+            message.jsonrpc !== "2.0" ||
+            typeof message.method !== "string" ||
+            (typeof message.id !== "string" && typeof message.id !== "number")) {
+            reply(null, { error: { code: -32600, message: "Invalid Request" } });
+            return;
+        }
+        const { id, method } = message;
+        const params = message.params ?? {};
+        const allowed = READ_METHODS.has(method) ||
+            ((method === "events.subscribe" || method === "events.unsubscribe") &&
+                isRecord(params) &&
+                params.topic === "node");
+        if (!allowed) {
+            reply(id, { error: { code: -32601, message: "Method not found" } });
+            return;
+        }
+        rpc.request(method, params, 15_000).then((result) => reply(id, { result }), (error) => reply(id, {
+            error: error instanceof RpcError
+                ? { code: error.code, message: error.message }
+                : { code: -32000, message: "The rome-node daemon did not answer." },
+        }));
+    }
+    void (async () => {
+        try {
+            const found = await findDaemon(config, lifetime.signal);
+            if (closed) {
+                found?.rpc.close();
+                return;
+            }
+            if (!found) {
+                finish((await readOptionalCallerCredential(config)) ? "not_running" : "not_configured");
+                return;
+            }
+            rpc = found.rpc;
+            rpc.onNotification = (method, params) => {
+                if (method === "events.node" && !closed)
+                    transport.send(JSON.stringify({ jsonrpc: "2.0", method, params }));
+            };
+            rpc.onClose = () => finish("disconnected");
+            for (const text of queued.splice(0))
+                forward(text);
+        }
+        catch (error) {
+            if (closed)
+                return;
+            finish(error instanceof DaemonVersionError ? "incompatible" : "not_running");
+        }
+    })();
+    return {
+        receive(text) {
+            if (closed)
+                return;
+            if (Buffer.byteLength(text) > MAX_CONSOLE_MESSAGE_BYTES) {
+                finish();
+                return;
+            }
+            if (rpc)
+                forward(text);
+            else if (queued.length < 16)
+                queued.push(text);
+            else
+                finish();
+        },
+        close: () => finish(),
+    };
+}

package/dist/daemon-client.d.ts

@@ -7,6 +7,8 @@ export { daemonStatus, startDaemon, stopDaemon } from "./daemon-control.js";
 export { DaemonRequestError, DaemonVersionError } from "./daemon-rpc.js";
 export type { DaemonStatus, ConnectionEvent, CopyProgress, CopyRequest, CopySummary, } from "./daemon-protocol.js";
 export type { DevicesStatus, DeviceStatus } from "./devices-status.js";
+export { openConsoleBridge, MAX_CONSOLE_MESSAGE_BYTES, type ConsoleBridge, type ConsoleDaemonState, type ConsoleTransport, } from "./console.js";
+export type { ActionRow, LogQuery, LogResult, NodeEvent, NodeStatus, Outcome, RoleStatus, } from "./observe-protocol.js";
 export type { ActionResponse, BinaryActionResult } from "./actions.js";
 export declare class DeviceActionError extends Error {
     readonly response: Extract<ActionResponse, {

package/dist/daemon-client.js

@@ -8,6 +8,7 @@ import { ensureDaemon, findDaemon } from "./daemon-control.js";
 export { createNodeConfig, nodeConfigFromEnvironment, readOptionalCallerCredential, CallerConfigurationError, } from "./local.js";
 export { daemonStatus, startDaemon, stopDaemon } from "./daemon-control.js";
 export { DaemonRequestError, DaemonVersionError } from "./daemon-rpc.js";
+export { openConsoleBridge, MAX_CONSOLE_MESSAGE_BYTES, } from "./console.js";
 export class DeviceActionError extends Error {
     response;
     code;

package/dist/daemon-protocol.d.ts

@@ -1,5 +1,5 @@
 import type { ConnectionStatus } from "./client.js";
-export declare const DAEMON_PROTOCOL_VERSION = 3;
+export declare const DAEMON_PROTOCOL_VERSION = 4;
 export declare const MAX_LOCAL_MESSAGE_BYTES: number;
 export interface DaemonStatus {
     pid: number;

package/dist/daemon-protocol.js

@@ -1,5 +1,5 @@
 import { isRecord } from "./actions.js";
-export const DAEMON_PROTOCOL_VERSION = 3;
+export const DAEMON_PROTOCOL_VERSION = 4;
 export const MAX_LOCAL_MESSAGE_BYTES = 64 * 1024 * 1024;
 export function parseDaemonStatus(value) {
     if (!isRecord(value) ||

package/dist/daemon.js

@@ -1,7 +1,10 @@
 import { randomBytes, timingSafeEqual } from "node:crypto";
 import { createServer } from "node:http";
+import { createRequire } from "node:module";
+import { join } from "node:path";
 import WebSocket, { WebSocketServer } from "ws";
 import { actionError, isRecord } from "./actions.js";
+import { ObserveStore, QueryError } from "./observe.js";
 import { DeviceConnector } from "./connector.js";
 import { daemonStatePath, readCallerCredential } from "./local.js";
 import { writePrivateJson } from "./storage.js";
@@ -11,6 +14,8 @@ import { RpcError } from "./daemon-rpc.js";
 import { isAbsolute } from "node:path";
 import { isUuid } from "./frame.js";
 import { copyWithDevice, TRANSFER_VERSION, TransferError } from "./transfer.js";
+const PRUNE_INTERVAL_MS = 60 * 60 * 1000;
+const { version: NODE_CORE_VERSION } = createRequire(import.meta.url)("../package.json");
 function copyRequest(params) {
     const { direction, localPath, deviceId, remotePath } = params;
     if ((direction !== "push" && direction !== "pull") ||
@@ -24,6 +29,50 @@ function copyRequest(params) {
         return null;
     return { direction, localPath, deviceId: deviceId.toLowerCase(), remotePath };
 }
+function byteCount(value) {
+    return typeof value === "string" ? Buffer.byteLength(value) : 0;
+}
+function actionStart(deviceId, action, args, mode, stdinBytes = 0) {
+    const exec = action === "exec" && isRecord(args) && typeof args.command === "string";
+    let text = null;
+    if (!exec)
+        try {
+            text = JSON.stringify(args ?? {});
+        }
+        catch { }
+    return {
+        direction: "out",
+        peer: deviceId.toLowerCase(),
+        action,
+        mode,
+        command: exec ? args.command : null,
+        args: exec ? (Array.isArray(args.args) ? args.args.map(String) : []) : text,
+        cwd: exec && typeof args.cwd === "string" ? args.cwd : null,
+        stdinBytes,
+    };
+}
+function actionEnd(response, stdoutBytes) {
+    if (!response.ok) {
+        const code = response.error.code;
+        return {
+            outcome: code === "unknown_outcome" ? "unknown_outcome" : code === "canceled" ? "aborted" : "error",
+            errorCode: code,
+        };
+    }
+    const result = isRecord(response.result) ? response.result : {};
+    return {
+        outcome: "ok",
+        exitCode: Number.isSafeInteger(result.exitCode) ? result.exitCode : null,
+        signal: typeof result.signal === "string" ? result.signal : null,
+        stdoutBytes: stdoutBytes ?? byteCount(result.stdout),
+        stderrBytes: byteCount(result.stderr),
+    };
+}
+function logQuery(params) {
+    if (params.kind !== "actions")
+        throw new RpcError(-32602, "log.query requires kind actions.");
+    return params;
+}
 export async function serveDaemon(config, signal) {
     if (signal.aborted)
         return;
@@ -35,14 +84,37 @@ export async function serveDaemon(config, signal) {
         protocolVersion: DAEMON_PROTOCOL_VERSION,
         token: `romenode_${randomBytes(32).toString("base64url")}`,
     };
+    const startedAt = Date.now();
     let closing = false;
+    const store = new ObserveStore({
+        path: join(config.directory, "observe.db"),
+        secrets: [credential.token, state.token],
+    });
+    const caller = {
+        connection: "stopped",
+        since: startedAt,
+        onlineOnce: false,
+        reconnects: 0,
+        running: 0,
+    };
     const connector = new DeviceConnector({
         credential,
-        onStatus: () => {
+        onStatus: (status) => {
             deviceStatus.invalidate();
             for (const peer of peers)
                 if (peer.subscribed)
                     notify(peer);
+            if (status === caller.connection)
+                return;
+            const at = Date.now();
+            caller.connection = status;
+            caller.since = at;
+            if (status === "online") {
+                if (caller.onlineOnce)
+                    caller.reconnects++;
+                caller.onlineOnce = true;
+            }
+            broadcast({ type: "connection", role: "caller", status, at });
         },
     });
     const deviceStatus = new DeviceStatusReader(connector);
@@ -51,6 +123,39 @@ export async function serveDaemon(config, signal) {
         protocolVersion: DAEMON_PROTOCOL_VERSION,
         connection: connector.getStatus(),
     });
+    const nodeStatus = () => ({
+        version: NODE_CORE_VERSION,
+        startedAt,
+        roles: {
+            caller: {
+                auth: caller.connection === "revoked" ? "revoked" : "authorized",
+                connection: caller.connection,
+                since: caller.since,
+                reconnects: caller.reconnects,
+                running: caller.running,
+            },
+        },
+    });
+    async function observed(start, work, end) {
+        if (!start)
+            return work();
+        caller.running++;
+        const row = store.startAction(start);
+        if (row)
+            broadcast({ type: "action", id: row.id, phase: "start", row });
+        let ended = { outcome: "error", errorCode: "daemon_error" };
+        try {
+            const value = await work();
+            ended = end(value);
+            return value;
+        }
+        finally {
+            caller.running--;
+            const done = row && store.endAction(row.id, ended);
+            if (done)
+                broadcast({ type: "action", id: done.id, phase: "end", row: done });
+        }
+    }
     function authorized(req) {
         const actual = Buffer.from(req.headers.authorization ?? "");
         const expected = Buffer.from(`Bearer ${state.token}`);
@@ -102,17 +207,21 @@ export async function serveDaemon(config, signal) {
         });
     }
     function notify(peer) {
+        emit(peer, "events.connection", snapshot());
+    }
+    function broadcast(event) {
+        for (const peer of peers)
+            if (peer.observing)
+                emit(peer, "events.node", event);
+    }
+    function emit(peer, method, params) {
         if (peer.eventBytes > 1024 * 1024) {
             peer.socket.terminate();
             return;
         }
         if (peer.socket.readyState !== WebSocket.OPEN)
             return;
-        const text = JSON.stringify({
-            jsonrpc: "2.0",
-            method: "events.connection",
-            params: snapshot(),
-        });
+        const text = JSON.stringify({ jsonrpc: "2.0", method, params });
         const size = Buffer.byteLength(text);
         peer.eventBytes += size;
         peer.socket.send(text, (error) => {
@@ -137,6 +246,48 @@ export async function serveDaemon(config, signal) {
         }, 1000);
         timer.unref();
     };
+    async function copyFile(peer, id, request) {
+        const controller = new AbortController();
+        peer.copies.add(controller);
+        if (peer.socket.readyState !== WebSocket.OPEN)
+            controller.abort();
+        const canceled = () => actionError("canceled", "The client disconnected. The copy did not start.");
+        let last = 0;
+        try {
+            if (controller.signal.aborted)
+                return canceled();
+            const info = await connector.run(request.deviceId, "system.info", {});
+            if (controller.signal.aborted)
+                return canceled();
+            if (!info.ok)
+                return info;
+            if (!isRecord(info.result) || info.result.transferVersion !== TRANSFER_VERSION)
+                return actionError("unsupported_device", "The device runs a rome-node version without file transfers. Update rome-node on that device.");
+            const summary = await copyWithDevice((events) => connector.openChannel(request.deviceId, events), request, {
+                signal: controller.signal,
+                onProgress: ({ bytes, total }) => {
+                    const now = Date.now();
+                    if (now - last < 250 && bytes !== total)
+                        return;
+                    last = now;
+                    send(peer, {
+                        jsonrpc: "2.0",
+                        method: "events.transfer",
+                        params: { requestId: id, bytes, total },
+                    });
+                },
+            });
+            return { type: "response", ok: true, result: summary };
+        }
+        catch (cause) {
+            if (!(cause instanceof TransferError))
+                throw cause;
+            return actionError(cause.code, cause.message);
+        }
+        finally {
+            peer.copies.delete(controller);
+        }
+    }
     function error(id, code, message) {
         return { jsonrpc: "2.0", id, error: { code, message } };
     }
@@ -184,6 +335,29 @@ export async function serveDaemon(config, signal) {
                         result = { stopped: true };
                         setImmediate(close);
                         break;
+                    case "node.status":
+                        result = nodeStatus();
+                        break;
+                    case "log.query":
+                        try {
+                            result = store.query(logQuery(params));
+                        }
+                        catch (cause) {
+                            if (cause instanceof QueryError)
+                                throw new RpcError(-32602, cause.message);
+                            throw cause;
+                        }
+                        break;
+                    case "log.stats":
+                        try {
+                            result = store.stats(params);
+                        }
+                        catch (cause) {
+                            if (cause instanceof QueryError)
+                                throw new RpcError(-32602, cause.message);
+                            throw cause;
+                        }
+                        break;
                     case "devices.status":
                         result = await deviceStatus.read();
                         break;
@@ -193,12 +367,19 @@ export async function serveDaemon(config, signal) {
                     case "devices.run":
                         if (typeof params.deviceId !== "string" || typeof params.action !== "string")
                             throw new RpcError(-32602, "A device ID and action are required.");
-                        result = await connector.run(params.deviceId, params.action, params.args ?? {});
+                        {
+                            const { deviceId, action } = params;
+                            const args = params.args ?? {};
+                            result = await observed(action === "system.info" ? null : actionStart(deviceId, action, args, "json"), () => connector.run(deviceId, action, args), (response) => actionEnd(response));
+                        }
                         break;
                     case "devices.runBinary": {
                         if (typeof params.deviceId !== "string" || typeof params.action !== "string")
                             throw new RpcError(-32602, "A device ID and action are required.");
-                        const reply = await connector.runBinary(params.deviceId, params.action, params.args ?? {}, input ?? new Uint8Array());
+                        const { deviceId, action } = params;
+                        const args = params.args ?? {};
+                        const stdin = input ?? new Uint8Array();
+                        const reply = await observed(actionStart(deviceId, action, args, "binary", stdin.byteLength), () => connector.runBinary(deviceId, action, args, stdin), ({ response, body }) => actionEnd(response, body.byteLength));
                         result = reply.response;
                         body = reply.body;
                         break;
@@ -207,65 +388,48 @@ export async function serveDaemon(config, signal) {
                         const request = copyRequest(params);
                         if (!request)
                             throw new RpcError(-32602, "files.copy requires direction push or pull, an absolute localPath, a device UUID, and remotePath.");
-                        const controller = new AbortController();
-                        peer.copies.add(controller);
-                        if (peer.socket.readyState !== WebSocket.OPEN)
-                            controller.abort();
-                        const canceled = () => actionError("canceled", "The client disconnected. The copy did not start.");
-                        let last = 0;
-                        try {
-                            if (controller.signal.aborted) {
-                                result = canceled();
-                                break;
-                            }
-                            const info = await connector.run(request.deviceId, "system.info", {});
-                            if (controller.signal.aborted) {
-                                result = canceled();
-                                break;
-                            }
-                            if (!info.ok) {
-                                result = info;
-                                break;
-                            }
-                            if (!isRecord(info.result) || info.result.transferVersion !== TRANSFER_VERSION) {
-                                result = actionError("unsupported_device", "The device runs a rome-node version without file transfers. Update rome-node on that device.");
-                                break;
-                            }
-                            const summary = await copyWithDevice((events) => connector.openChannel(request.deviceId, events), request, {
-                                signal: controller.signal,
-                                onProgress: ({ bytes, total }) => {
-                                    const now = Date.now();
-                                    if (now - last < 250 && bytes !== total)
-                                        return;
-                                    last = now;
-                                    send(peer, {
-                                        jsonrpc: "2.0",
-                                        method: "events.transfer",
-                                        params: { requestId: id, bytes, total },
-                                    });
-                                },
-                            });
-                            result = { type: "response", ok: true, result: summary };
-                        }
-                        catch (cause) {
-                            if (!(cause instanceof TransferError))
-                                throw cause;
-                            result = actionError(cause.code, cause.message);
-                        }
-                        finally {
-                            peer.copies.delete(controller);
-                        }
+                        result = await observed({
+                            direction: "out",
+                            peer: request.deviceId,
+                            action: "copy",
+                            mode: "copy",
+                            transfer: {
+                                direction: request.direction,
+                                localPath: request.localPath,
+                                remotePath: request.remotePath,
+                            },
+                        }, () => copyFile(peer, id, request), (response) => {
+                            const summary = response.ok && isRecord(response.result) ? response.result : {};
+                            return {
+                                ...actionEnd(response),
+                                transferBytes: typeof summary.bytes === "number" ? summary.bytes : null,
+                                sha256: typeof summary.sha256 === "string" ? summary.sha256 : null,
+                            };
+                        });
                         break;
                     }
                     case "events.subscribe":
-                    case "events.unsubscribe":
-                        if (params.topic !== "connection")
+                    case "events.unsubscribe": {
+                        const on = value.method === "events.subscribe";
+                        if (params.topic === "connection") {
+                            peer.subscribed = on;
+                            if (on)
+                                notify(peer);
+                        }
+                        else if (params.topic === "node") {
+                            peer.observing = on;
+                            if (on)
+                                emit(peer, "events.node", {
+                                    type: "snapshot",
+                                    status: nodeStatus(),
+                                    running: store.running(),
+                                });
+                        }
+                        else
                             throw new RpcError(-32602, "Unknown event topic.");
-                        peer.subscribed = value.method === "events.subscribe";
-                        if (peer.subscribed)
-                            notify(peer);
-                        result = { subscribed: peer.subscribed };
+                        result = { subscribed: on };
                         break;
+                    }
                     default:
                         throw new RpcError(-32601, "Method not found");
                 }
@@ -291,6 +455,7 @@ export async function serveDaemon(config, signal) {
             socket,
             ready: false,
             subscribed: false,
+            observing: false,
             alive: true,
             pending: new Set(),
             eventBytes: 0,
@@ -353,6 +518,9 @@ export async function serveDaemon(config, signal) {
             resolve();
         });
     });
+    store.open();
+    const pruner = setInterval(() => store.prune(), PRUNE_INTERVAL_MS);
+    pruner.unref();
     const heartbeat = setInterval(() => {
         for (const peer of peers) {
             if (!peer.alive) {
@@ -376,6 +544,8 @@ export async function serveDaemon(config, signal) {
     finally {
         close();
         clearInterval(heartbeat);
+        clearInterval(pruner);
+        store.close();
         signal.removeEventListener("abort", close);
     }
 }

package/dist/observe-protocol.d.ts

@@ -0,0 +1,100 @@
+import type { ConnectionStatus } from "./client.js";
+export type Outcome = "ok" | "error" | "aborted" | "unknown_outcome" | "interrupted";
+export declare const OUTCOMES: readonly Outcome[];
+export interface ActionRow {
+    id: number;
+    direction: "in" | "out";
+    peer: string | null;
+    action: string;
+    mode: "json" | "binary" | "copy";
+    command: string | null;
+    args: string[] | string | null;
+    cwd: string | null;
+    startedAt: number;
+    endedAt: number | null;
+    outcome: Outcome | null;
+    errorCode: string | null;
+    exitCode: number | null;
+    signal: string | null;
+    stdinBytes: number;
+    stdoutBytes: number;
+    stderrBytes: number;
+    transfer: {
+        direction: "push" | "pull";
+        localPath: string;
+        remotePath: string;
+        bytes: number | null;
+        sha256: string | null;
+    } | null;
+    truncated?: true;
+}
+export interface RoleStatus {
+    deviceId?: string;
+    name?: string;
+    auth: "required" | "authorized" | "revoked";
+    connection: ConnectionStatus;
+    since: number;
+    reconnects: number;
+    running: number;
+}
+export interface NodeStatus {
+    version: string;
+    startedAt: number;
+    roles: {
+        caller?: RoleStatus;
+        host?: RoleStatus;
+    };
+}
+export type NodeEvent = {
+    type: "snapshot";
+    status: NodeStatus;
+    running: ActionRow[];
+} | {
+    type: "connection";
+    role: "caller" | "host";
+    status: ConnectionStatus;
+    at: number;
+} | {
+    type: "action";
+    id: number;
+    phase: "start" | "end";
+    row: ActionRow;
+};
+export type ActionResult = "running" | "succeeded" | "failed" | "no_result";
+export declare const ACTION_RESULTS: readonly ActionResult[];
+export interface LogQuery {
+    kind: "actions";
+    before?: number;
+    limit?: number;
+    direction?: "in" | "out";
+    peer?: string;
+    outcome?: Outcome[];
+    result?: ActionResult[];
+    since?: number;
+    until?: number;
+    text?: string;
+}
+export interface LogStatsQuery {
+    since: number;
+    until?: number;
+    bucketMs: number;
+    direction?: "in" | "out";
+    peer?: string;
+}
+interface LogStatsGroup {
+    peer: string | null;
+    bucket: number;
+    result: ActionResult;
+    count: number;
+}
+export interface LogStats {
+    since: number;
+    until: number;
+    bucketMs: number;
+    groups: LogStatsGroup[];
+}
+export interface LogResult<T> {
+    rows: T[];
+    hasMore: boolean;
+}
+export {};

package/dist/observe-protocol.js

@@ -0,0 +1,13 @@
+export const OUTCOMES = [
+    "ok",
+    "error",
+    "aborted",
+    "unknown_outcome",
+    "interrupted",
+];
+export const ACTION_RESULTS = [
+    "running",
+    "succeeded",
+    "failed",
+    "no_result",
+];

package/dist/observe.d.ts

@@ -0,0 +1,67 @@
+import { type ActionRow, type LogQuery, type LogResult, type LogStats, type LogStatsQuery, type Outcome } from "./observe-protocol.js";
+export declare const MAX_ROW_CHARS: number;
+export interface ObserveStoreOptions {
+    path: string;
+    secrets?: string[];
+    retentionMs?: number;
+    maxBytes?: number;
+    now?: () => number;
+}
+export interface ActionStart {
+    direction: "in" | "out";
+    peer: string | null;
+    action: string;
+    mode: ActionRow["mode"];
+    command?: string | null;
+    args?: string[] | string | null;
+    cwd?: string | null;
+    stdinBytes?: number;
+    transfer?: {
+        direction: "push" | "pull";
+        localPath: string;
+        remotePath: string;
+    } | null;
+}
+export interface ActionEnd {
+    outcome: Exclude<Outcome, "interrupted">;
+    errorCode?: string | null;
+    exitCode?: number | null;
+    signal?: string | null;
+    stdoutBytes?: number;
+    stderrBytes?: number;
+    transferBytes?: number | null;
+    sha256?: string | null;
+}
+export declare class QueryError extends Error {
+}
+export declare class ObserveStore {
+    private readonly options;
+    private db?;
+    private statements;
+    private readonly secrets;
+    private readonly retentionMs;
+    private readonly maxBytes;
+    private readonly now;
+    constructor(options: ObserveStoreOptions);
+    open(): void;
+    private attach;
+    private connect;
+    private discard;
+    private guard;
+    private statement;
+    private run;
+    private all;
+    private mask;
+    startAction(start: ActionStart): ActionRow | null;
+    endAction(id: number, end: ActionEnd): ActionRow | null;
+    private action;
+    running(): ActionRow[];
+    query(query: LogQuery): LogResult<ActionRow>;
+    private limit;
+    private queryActions;
+    stats(query: LogStatsQuery): LogStats;
+    prune(): void;
+    private compact;
+    private usedBytes;
+    close(): void;
+}

package/dist/observe.js

@@ -0,0 +1,457 @@
+import { closeSync, existsSync, openSync, readdirSync, renameSync, rmSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { ACTION_RESULTS, OUTCOMES, } from "./observe-protocol.js";
+const SCHEMA_VERSION = 1;
+const DAY_MS = 24 * 60 * 60 * 1000;
+export const MAX_ROW_CHARS = 16 * 1024;
+const MAX_RESULT_BYTES = 768 * 1024;
+const MAX_LIMIT = 500;
+const MAX_BUCKETS = 1000;
+const RESULT_SQL = `CASE
+  WHEN a.ended_at IS NULL THEN 'running'
+  WHEN a.outcome = 'ok' AND coalesce(a.exit_code, 0) = 0 AND a.signal IS NULL THEN 'succeeded'
+  WHEN a.outcome IN ('ok', 'error') THEN 'failed'
+  ELSE 'no_result' END`;
+export class QueryError extends Error {
+}
+class CorruptDatabaseError extends Error {
+}
+class SchemaVersionError extends Error {
+}
+function isCorruption(error) {
+    if (error instanceof CorruptDatabaseError)
+        return true;
+    const code = error?.errcode;
+    return typeof code === "number" && ((code & 0xff) === 11 || (code & 0xff) === 26);
+}
+const SCHEMA = `
+CREATE TABLE actions (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  direction TEXT NOT NULL,
+  peer TEXT,
+  action TEXT NOT NULL,
+  mode TEXT NOT NULL,
+  command TEXT,
+  args TEXT,
+  cwd TEXT,
+  started_at INTEGER NOT NULL,
+  ended_at INTEGER,
+  outcome TEXT,
+  error_code TEXT,
+  exit_code INTEGER,
+  signal TEXT,
+  stdin_bytes INTEGER NOT NULL DEFAULT 0,
+  stdout_bytes INTEGER NOT NULL DEFAULT 0,
+  stderr_bytes INTEGER NOT NULL DEFAULT 0,
+  transfer_direction TEXT,
+  local_path TEXT,
+  remote_path TEXT,
+  transfer_bytes INTEGER,
+  sha256 TEXT
+);
+CREATE INDEX actions_started_at ON actions(started_at);
+CREATE INDEX actions_direction ON actions(direction, id);
+CREATE INDEX actions_peer ON actions(peer, id);
+CREATE INDEX actions_outcome ON actions(outcome, id);
+CREATE INDEX actions_open ON actions(id) WHERE ended_at IS NULL;
+CREATE VIRTUAL TABLE actions_fts USING fts5(
+  command, args, cwd, content='actions', content_rowid='id', tokenize='trigram'
+);
+CREATE TRIGGER actions_fts_insert AFTER INSERT ON actions BEGIN
+  INSERT INTO actions_fts(rowid, command, args, cwd)
+  VALUES (new.id, coalesce(new.command, ''), coalesce(new.args, ''), coalesce(new.cwd, ''));
+END;
+CREATE TRIGGER actions_fts_delete AFTER DELETE ON actions BEGIN
+  INSERT INTO actions_fts(actions_fts, rowid, command, args, cwd)
+  VALUES ('delete', old.id, coalesce(old.command, ''), coalesce(old.args, ''), coalesce(old.cwd, ''));
+END;
+`;
+function cut(value, budget) {
+    if (value === null)
+        return value;
+    if (value.length <= budget.remaining) {
+        budget.remaining -= value.length;
+        return value;
+    }
+    budget.truncated = true;
+    const kept = value.slice(0, budget.remaining);
+    budget.remaining = 0;
+    return kept;
+}
+function toActionRow(row) {
+    const state = { remaining: MAX_ROW_CHARS, truncated: false };
+    const command = cut(row.command, state);
+    const cwd = cut(row.cwd, state);
+    let args = null;
+    if (typeof row.args === "string") {
+        let parsed;
+        try {
+            parsed = row.command === null ? undefined : JSON.parse(row.args);
+        }
+        catch { }
+        if (Array.isArray(parsed)) {
+            args = [];
+            for (const arg of parsed) {
+                if (!state.remaining) {
+                    state.truncated = true;
+                    break;
+                }
+                args.push(cut(String(arg), state) ?? "");
+            }
+        }
+        else
+            args = cut(row.args, state);
+    }
+    const value = {
+        id: Number(row.id),
+        direction: row.direction,
+        peer: row.peer,
+        action: row.action,
+        mode: row.mode,
+        command,
+        args,
+        cwd,
+        startedAt: Number(row.started_at),
+        endedAt: row.ended_at === null ? null : Number(row.ended_at),
+        outcome: row.outcome,
+        errorCode: row.error_code,
+        exitCode: row.exit_code === null ? null : Number(row.exit_code),
+        signal: row.signal,
+        stdinBytes: Number(row.stdin_bytes),
+        stdoutBytes: Number(row.stdout_bytes),
+        stderrBytes: Number(row.stderr_bytes),
+        transfer: row.transfer_direction === null
+            ? null
+            : {
+                direction: row.transfer_direction,
+                localPath: cut(row.local_path, state) ?? "",
+                remotePath: cut(row.remote_path, state) ?? "",
+                bytes: row.transfer_bytes === null ? null : Number(row.transfer_bytes),
+                sha256: row.sha256,
+            },
+    };
+    if (state.truncated)
+        value.truncated = true;
+    return value;
+}
+const optionalId = (value, name) => {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
+        throw new QueryError(`${name} must be a non-negative integer.`);
+    return value;
+};
+function commonFilters(query, where, params) {
+    if (query.direction !== undefined) {
+        if (query.direction !== "in" && query.direction !== "out")
+            throw new QueryError("direction must be in or out.");
+        where.push("a.direction = ?");
+        params.push(query.direction);
+    }
+    if (query.peer !== undefined) {
+        if (typeof query.peer !== "string")
+            throw new QueryError("peer must be a string.");
+        where.push("a.peer = ?");
+        params.push(query.peer);
+    }
+    const since = optionalId(query.since, "since");
+    const until = optionalId(query.until, "until");
+    if (since !== undefined)
+        where.push("a.started_at >= ?"), params.push(since);
+    if (until !== undefined)
+        where.push("a.started_at < ?"), params.push(until);
+}
+export class ObserveStore {
+    options;
+    db;
+    statements = new Map();
+    secrets;
+    retentionMs;
+    maxBytes;
+    now;
+    constructor(options) {
+        this.options = options;
+        this.secrets = (options.secrets ?? []).filter(Boolean);
+        this.retentionMs = options.retentionMs ?? 30 * DAY_MS;
+        this.maxBytes = options.maxBytes ?? 64 * 1024 * 1024;
+        this.now = options.now ?? Date.now;
+    }
+    open() {
+        this.db = this.attach();
+        if (!this.db)
+            return;
+        this.guard(() => {
+            this.run("UPDATE actions SET ended_at = ?, outcome = 'interrupted' WHERE ended_at IS NULL", this.now());
+        });
+        this.prune();
+    }
+    attach() {
+        try {
+            return this.connect();
+        }
+        catch (error) {
+            if (error instanceof SchemaVersionError) {
+                if (!this.discard(false))
+                    return undefined;
+            }
+            else if (isCorruption(error)) {
+                if (!this.discard(true))
+                    return undefined;
+            }
+            else
+                return undefined;
+        }
+        try {
+            return this.connect();
+        }
+        catch {
+            return undefined;
+        }
+    }
+    connect() {
+        const { path } = this.options;
+        if (!existsSync(path))
+            closeSync(openSync(path, "a", 0o600));
+        const db = new DatabaseSync(path);
+        try {
+            db.exec("PRAGMA busy_timeout = 1000");
+            const check = db.prepare("PRAGMA quick_check").get();
+            if (check?.quick_check !== "ok")
+                throw new CorruptDatabaseError();
+            const version = Number(db.prepare("PRAGMA user_version").get()?.user_version ?? 0);
+            if (version === 0) {
+                db.exec("PRAGMA auto_vacuum = INCREMENTAL");
+                db.exec("PRAGMA journal_mode = WAL");
+                db.exec(`BEGIN; ${SCHEMA} PRAGMA user_version = ${SCHEMA_VERSION}; COMMIT;`);
+            }
+            else if (version !== SCHEMA_VERSION) {
+                throw new SchemaVersionError();
+            }
+            else
+                db.exec("PRAGMA journal_mode = WAL");
+            db.exec("PRAGMA synchronous = NORMAL");
+            return db;
+        }
+        catch (error) {
+            db.close();
+            throw error;
+        }
+    }
+    discard(keepCopy) {
+        const { path } = this.options;
+        this.statements.clear();
+        try {
+            this.db?.close();
+        }
+        catch { }
+        this.db = undefined;
+        try {
+            if (keepCopy) {
+                const prefix = `${basename(path)}.corrupt-`;
+                for (const name of readdirSync(dirname(path)))
+                    if (name.startsWith(prefix))
+                        rmSync(join(dirname(path), name), { force: true });
+                if (existsSync(path))
+                    renameSync(path, `${path}.corrupt-${this.now()}`);
+            }
+            else
+                rmSync(path, { force: true });
+            for (const suffix of ["-wal", "-shm"])
+                rmSync(`${path}${suffix}`, { force: true });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    guard(work, fallback) {
+        if (!this.db)
+            return fallback;
+        try {
+            return work();
+        }
+        catch (error) {
+            if (isCorruption(error))
+                this.db = this.discard(true) ? this.attach() : undefined;
+            return fallback;
+        }
+    }
+    statement(sql) {
+        let statement = this.statements.get(sql);
+        if (!statement) {
+            statement = this.db.prepare(sql);
+            this.statements.set(sql, statement);
+        }
+        return statement;
+    }
+    run(sql, ...params) {
+        return this.statement(sql).run(...params);
+    }
+    all(sql, ...params) {
+        return this.statement(sql).all(...params);
+    }
+    mask(value) {
+        if (value === null || value === undefined)
+            return null;
+        let masked = value;
+        for (const secret of this.secrets)
+            masked = masked.split(secret).join("*".repeat(secret.length));
+        return masked;
+    }
+    startAction(start) {
+        return (this.guard(() => {
+            const args = start.args === undefined || start.args === null
+                ? null
+                : typeof start.args === "string"
+                    ? this.mask(start.args)
+                    : JSON.stringify(start.args.map((arg) => this.mask(arg)));
+            const result = this.run(`INSERT INTO actions (direction, peer, action, mode, command, args, cwd, started_at,
+             stdin_bytes, transfer_direction, local_path, remote_path)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, start.direction, this.mask(start.peer), start.action, start.mode, this.mask(start.command), args, this.mask(start.cwd), this.now(), start.stdinBytes ?? 0, start.transfer?.direction ?? null, this.mask(start.transfer?.localPath), this.mask(start.transfer?.remotePath));
+            return this.action(Number(result.lastInsertRowid));
+        }, null) ?? null);
+    }
+    endAction(id, end) {
+        return (this.guard(() => {
+            this.run(`UPDATE actions SET ended_at = ?, outcome = ?, error_code = ?, exit_code = ?, signal = ?,
+             stdout_bytes = ?, stderr_bytes = ?, transfer_bytes = ?, sha256 = ?
+           WHERE id = ? AND ended_at IS NULL`, this.now(), end.outcome, end.errorCode ?? null, end.exitCode ?? null, end.signal ?? null, end.stdoutBytes ?? 0, end.stderrBytes ?? 0, end.transferBytes ?? null, end.sha256 ?? null, id);
+            return this.action(id);
+        }, null) ?? null);
+    }
+    action(id) {
+        const row = this.all("SELECT * FROM actions WHERE id = ?", id)[0];
+        return row ? toActionRow(row) : null;
+    }
+    running() {
+        return (this.guard(() => this.all("SELECT * FROM actions WHERE ended_at IS NULL ORDER BY id LIMIT ?", MAX_LIMIT).map(toActionRow), []) ?? []);
+    }
+    query(query) {
+        if (query.kind !== "actions")
+            throw new QueryError("Unknown query kind.");
+        return this.queryActions(query);
+    }
+    limit(value, fallback) {
+        if (value === undefined)
+            return fallback;
+        if (typeof value !== "number" || !Number.isInteger(value) || value < 1)
+            throw new QueryError("limit must be a positive integer.");
+        return Math.min(value, MAX_LIMIT);
+    }
+    queryActions(query) {
+        const where = [];
+        const params = [];
+        const before = optionalId(query.before, "before");
+        const limit = this.limit(query.limit, 100);
+        if (before !== undefined)
+            where.push("a.id < ?"), params.push(before);
+        commonFilters(query, where, params);
+        if (query.outcome !== undefined) {
+            if (!Array.isArray(query.outcome) ||
+                !query.outcome.length ||
+                !query.outcome.every((outcome) => OUTCOMES.includes(outcome)))
+                throw new QueryError("outcome must list known outcomes.");
+            where.push(`a.outcome IN (${query.outcome.map(() => "?").join(", ")})`);
+            params.push(...query.outcome);
+        }
+        if (query.result !== undefined) {
+            if (!Array.isArray(query.result) ||
+                !query.result.length ||
+                !query.result.every((result) => ACTION_RESULTS.includes(result)))
+                throw new QueryError("result must list known results.");
+            where.push(`${RESULT_SQL} IN (${query.result.map(() => "?").join(", ")})`);
+            params.push(...query.result);
+        }
+        let join = "";
+        if (query.text !== undefined) {
+            if (typeof query.text !== "string" || [...query.text].length < 3)
+                throw new QueryError("text must have at least three characters.");
+            join = "JOIN actions_fts ON actions_fts.rowid = a.id";
+            where.push("actions_fts MATCH ?");
+            params.push(`"${query.text.replaceAll('"', '""')}"`);
+        }
+        const sql = `SELECT a.* FROM actions a ${join} ${where.length ? `WHERE ${where.join(" AND ")}` : ""} ORDER BY a.id DESC LIMIT ?`;
+        return (this.guard(() => {
+            const raw = this.all(sql, ...params, limit + 1);
+            const rows = [];
+            let bytes = 0;
+            let hasMore = raw.length > limit;
+            for (const item of raw.slice(0, limit)) {
+                const row = toActionRow(item);
+                bytes += Buffer.byteLength(JSON.stringify(row));
+                if (rows.length && bytes > MAX_RESULT_BYTES) {
+                    hasMore = true;
+                    break;
+                }
+                rows.push(row);
+            }
+            return { rows, hasMore };
+        }, { rows: [], hasMore: false }) ?? { rows: [], hasMore: false });
+    }
+    stats(query) {
+        const since = optionalId(query.since, "since");
+        if (since === undefined)
+            throw new QueryError("since is required.");
+        const until = optionalId(query.until, "until") ?? this.now();
+        const bucketMs = query.bucketMs;
+        if (typeof bucketMs !== "number" || !Number.isSafeInteger(bucketMs) || bucketMs < 1000)
+            throw new QueryError("bucketMs must be an integer of at least 1000.");
+        if (until <= since || Math.ceil((until - since) / bucketMs) > MAX_BUCKETS)
+            throw new QueryError(`The range must hold between 1 and ${MAX_BUCKETS} buckets.`);
+        const where = [];
+        const params = [];
+        commonFilters({ ...query, since, until }, where, params);
+        const sql = `SELECT a.peer AS peer, CAST((a.started_at - ?) / ? AS INTEGER) AS bucket,
+        ${RESULT_SQL} AS result, count(*) AS count
+      FROM actions a WHERE ${where.join(" AND ")}
+      GROUP BY peer, bucket, result ORDER BY bucket`;
+        const groups = this.guard(() => this.all(sql, since, bucketMs, ...params).map((row) => ({
+            peer: row.peer,
+            bucket: Number(row.bucket),
+            result: row.result,
+            count: Number(row.count),
+        })), []) ?? [];
+        return { since, until, bucketMs, groups };
+    }
+    prune() {
+        this.guard(() => {
+            const cutoff = this.now() - this.retentionMs;
+            let deleted = Number(this.run("DELETE FROM actions WHERE started_at < ? AND ended_at IS NOT NULL", cutoff)
+                .changes);
+            if (this.usedBytes() > this.maxBytes) {
+                this.compact();
+                for (let round = 0; round < 64 && this.usedBytes() > this.maxBytes; round++) {
+                    const count = Number(this.all("SELECT count(*) AS n FROM actions")[0]?.n ?? 0);
+                    if (!count)
+                        break;
+                    deleted += Number(this.run(`DELETE FROM actions WHERE id IN (SELECT id FROM actions WHERE ended_at IS NOT NULL
+                 ORDER BY id LIMIT ?)`, Math.max(1, Math.ceil(count / 10))).changes);
+                    this.compact();
+                }
+            }
+            if (!deleted)
+                return;
+            this.db.exec("PRAGMA incremental_vacuum");
+            this.db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+        });
+    }
+    compact() {
+        this.db.exec("INSERT INTO actions_fts(actions_fts) VALUES ('optimize')");
+        this.db.exec("PRAGMA incremental_vacuum");
+    }
+    usedBytes() {
+        const pages = Number(this.all("PRAGMA page_count")[0]?.page_count ?? 0);
+        const free = Number(this.all("PRAGMA freelist_count")[0]?.freelist_count ?? 0);
+        const size = Number(this.all("PRAGMA page_size")[0]?.page_size ?? 4096);
+        return (pages - free) * size;
+    }
+    close() {
+        this.statements.clear();
+        try {
+            this.db?.close();
+        }
+        catch { }
+        this.db = undefined;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rome-os/node-core",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "JavaScript APIs for Rome device hosts and shared caller daemons",
   "license": "MIT",
   "type": "module",