@hwip/cli 0.0.1 → 0.1.0

package/dist/turn-recorder-wire.js

@@ -0,0 +1,165 @@
+"use strict";
+/**
+ * The world the recorder (`turn-recorder.ts`) talks to: the account API that
+ * stores chunks, the push-v1 envelope that seals them, and the list of devices
+ * the account has signed in. Kept apart so the recorder's tests need none of it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLatestSeqReader = exports.createChunkUploader = exports.accountRecipients = exports.sealChunk = exports.RECORDER_UPLOADS_PER_MINUTE = void 0;
+const api_js_1 = require("./api.js");
+const ws_url_js_1 = require("./ws-url.js");
+const http_failure_js_1 = require("./http-failure.js");
+const crypto_js_1 = require("./crypto.js");
+const subscriber_trust_js_1 = require("./subscriber-trust.js");
+const trust_pins_js_1 = require("./trust-pins.js");
+const turn_recorder_js_1 = require("./turn-recorder.js");
+const UPLOAD_TIMEOUT_MS = 15_000;
+/** The turns route has its own per-minute allowance on the server (240); chunks keep to 30, well inside it. */
+exports.RECORDER_UPLOADS_PER_MINUTE = 30;
+/** How long a session waits after a 403 before the same chunk is tried again. */
+const RECORDER_KEY_RETRY_MS = 5 * 60_000;
+/** After this many 403s in a row the chunk is dropped: the key it was sealed with is not the one on file, and will not be. */
+const RECORDER_KEY_REFUSALS = 5;
+/** Seal one plaintext body (`{sessionKey, seq, events}`) as a push-v1 envelope for the recipients. */
+const sealChunk = async (plaintext, recipients) => {
+    await (0, crypto_js_1.initDeviceCrypto)();
+    const sealed = await (0, crypto_js_1.encryptPushBodyForDevices)({ body: plaintext }, recipients);
+    return { body: sealed.body, deviceKeyMap: sealed.deviceKeyMap, senderPublicKey: sealed.senderPublicKey };
+};
+exports.sealChunk = sealChunk;
+/**
+ * This machine plus the devices the account lists with a key, the newest pins first and
+ * within the server's slot limit. The list decides who a chunk is sealed for: a device
+ * that signed in reads its history once the directory refreshes its list (a minute at most). Each listed device is pinned on
+ * the way (`observeDevices`) — the pin is what `hwip trust` shows and what the listener
+ * holds a request against, and its date orders who is cut when the list is longer than
+ * the slots. The directory keeps the last list it fetched, so a blip does not stop the
+ * history; a list never had means no
+ * recipients, and pins from an earlier run do not stand in for it. A machine with no other
+ * device has no one who could read a chunk.
+ */
+const accountRecipients = (deps) => async () => {
+    try {
+        const publicKey = await (0, crypto_js_1.initDeviceCrypto)();
+        const self = { deviceId: deps.deviceId, publicKey: (0, crypto_js_1.getDevicePublicKey)() ?? publicKey };
+        const listed = (0, crypto_js_1.selectRecipients)(await deps.devices()).filter((d) => d.deviceId !== deps.deviceId);
+        (0, trust_pins_js_1.observeDevices)(deps.trustFile, listed, { selfId: deps.deviceId, warn: (line) => deps.log(line) });
+        const loaded = (0, subscriber_trust_js_1.readTrustState)(deps.trustFile);
+        const pins = 'broken' in loaded ? undefined : loaded.state.devices;
+        return (0, turn_recorder_js_1.chooseRecipients)(self, listed.map((d) => ({ ...d, pinnedAt: pins?.get(d.deviceId)?.pinnedAt })));
+    }
+    catch (err) {
+        deps.log(`turn history: recipients unavailable (${err instanceof Error ? err.message : String(err)})`);
+        return [];
+    }
+};
+exports.accountRecipients = accountRecipients;
+const readError = async (res) => {
+    try {
+        return (await res.json()).error;
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * `POST /sessions/{key}/turns` for one stored chunk. The same bytes go out on
+ * every try, so a chunk the server already holds comes back 200 (stored) rather
+ * than 409 (a different body under the same `seq`).
+ *
+ *   201 / 200          stored.
+ *   429 RATE_LIMIT     a minute-long limit: try again after what the server says.
+ *   429 TURN_DAILY     the day's cap: leave the session alone until its reset.
+ *   408, 5xx, network  try again with the recorder's backoff.
+ *   redirect refused   the base URL sends the request elsewhere on every try (a permanent
+ *                      answer, like a wrong key): pause the session for an hour and say why.
+ *                      The chunk is kept, so a corrected base URL (a restart) sends it.
+ *   400, 409           the server will never take these bytes (a bad body, a `seq`
+ *                      that holds another): drop the chunk, or it blocks the session;
+ *                      after a 409 the next `seq` moves past what the server holds.
+ *   403                the key may only just have been registered: pause the session 5 min;
+ *                      the fifth in a row on one chunk drops it.
+ *   any other 4xx      wrong key, device or session (401, 404): pause the
+ *                      session for an hour and say why in the log.
+ */
+const createChunkUploader = (opts) => {
+    const fetchFn = opts.fetchFn ?? fetch;
+    const now = opts.now ?? Date.now;
+    const perMinute = opts.perMinute ?? exports.RECORDER_UPLOADS_PER_MINUTE;
+    let sent = [];
+    return async (sessionKey, chunk) => {
+        const at = now();
+        sent = sent.filter((t) => at - t < 60_000);
+        if (sent.length >= perMinute) {
+            return { kind: 'retry', why: 'own upload budget for this minute is spent', afterMs: Math.max(1_000, 60_000 - (at - sent[0])) };
+        }
+        sent.push(at);
+        let res;
+        try {
+            res = await (0, api_js_1.apiFetch)(fetchFn, (0, api_js_1.apiUrl)(opts.baseUrl, `/sessions/${encodeURIComponent(sessionKey)}/turns`), opts.apiKey, UPLOAD_TIMEOUT_MS, {
+                method: 'POST',
+                body: JSON.stringify({ seq: chunk.seq, firstAt: chunk.firstAt, lastAt: chunk.lastAt, sealed: chunk.sealed }),
+            });
+        }
+        catch (err) {
+            const why = err instanceof Error ? err.message : String(err);
+            // `apiFetch` refuses a redirect (it would carry the key to another host). It is a TypeError like a
+            // dropped connection, but it happens on every try: backing off and retrying only repeats it.
+            // The same holds for a configuration failure (bad key, bad base URL): retry with backoff only
+            // repeats it, so the chunk waits for a corrected configuration instead.
+            if ((0, http_failure_js_1.isRedirectRefusal)(err) || (0, http_failure_js_1.isConfigFailure)(err) || (0, http_failure_js_1.isInvalidUrl)(err) || (0, http_failure_js_1.isUnsendableHeader)(err) || (0, ws_url_js_1.carriesCredentials)(opts.baseUrl))
+                return { kind: 'pause', why };
+            return { kind: 'retry', why };
+        }
+        if (res.status === 200 || res.status === 201)
+            return { kind: 'ok' };
+        const error = await readError(res);
+        const code = typeof error?.code === 'string' ? ` ${error.code}` : '';
+        const why = `HTTP ${res.status}${code}`;
+        if (res.status === 429) {
+            if (error?.code === 'TURN_DAILY_LIMIT') {
+                const reset = typeof error.details?.resetAt === 'string' ? Date.parse(error.details.resetAt) : NaN;
+                return { kind: 'pause', why, untilMs: Number.isFinite(reset) && reset > at ? reset : at + turn_recorder_js_1.RECORDER_PAUSE_MS };
+            }
+            const header = Number(res.headers.get('retry-after'));
+            const detail = typeof error?.details?.retryAfter === 'number' ? error.details.retryAfter : NaN;
+            const seconds = Number.isFinite(header) && header > 0 ? header : detail;
+            return { kind: 'retry', why, afterMs: Number.isFinite(seconds) && seconds > 0 ? seconds * 1000 : turn_recorder_js_1.RECORDER_BACKOFF_BASE_MS * 8 };
+        }
+        if (res.status === 408 || res.status >= 500) {
+            const header = Number(res.headers.get('retry-after'));
+            return { kind: 'retry', why, ...(Number.isFinite(header) && header > 0 ? { afterMs: header * 1000 } : {}) };
+        }
+        if (res.status === 400)
+            return { kind: 'drop', why };
+        // The same `seq` already holds another body: this chunk is lost, and the numbering must move on.
+        if (res.status === 409)
+            return { kind: 'drop', why, conflict: true };
+        // The key frame and the first chunk can cross: a 403 just after the first registration passes by itself.
+        if (res.status === 403)
+            return { kind: 'pause', why, untilMs: at + RECORDER_KEY_RETRY_MS, giveUpAfter: RECORDER_KEY_REFUSALS };
+        return { kind: 'pause', why };
+    };
+};
+exports.createChunkUploader = createChunkUploader;
+/**
+ * The newest `seq` the server holds for a session (`GET .../turns?limit=1`, newest
+ * first), or null when it cannot say. Used only after a 409, to number past it.
+ */
+const createLatestSeqReader = (opts) => {
+    const fetchFn = opts.fetchFn ?? fetch;
+    return async (sessionKey) => {
+        try {
+            const res = await (0, api_js_1.apiFetch)(fetchFn, (0, api_js_1.apiUrl)(opts.baseUrl, `/sessions/${encodeURIComponent(sessionKey)}/turns?limit=1`), opts.apiKey, UPLOAD_TIMEOUT_MS);
+            if (!res.ok)
+                return null;
+            const body = (await res.json());
+            const seq = body.data?.[0]?.seq;
+            return typeof seq === 'number' && Number.isInteger(seq) && seq >= 0 ? seq : null;
+        }
+        catch {
+            return null;
+        }
+    };
+};
+exports.createLatestSeqReader = createLatestSeqReader;

package/dist/turn-recorder.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Always-on conversation recorder (I28, hwip `docs/session-history.md` §3).
+ *
+ * `turn-watch.ts` follows a transcript for a viewer who is looking. This reads
+ * the transcript of every agent session this listener knows, with nobody
+ * looking, and uploads what was said to the account so the phone can show the
+ * conversation later: the same projection (`TranscriptSource.project`), the
+ * same privacy line (a tool is a name, a label and counts — never its
+ * arguments or output), a different lifetime. The live watcher and its ring are
+ * left alone.
+ *
+ * What is uploaded, and how it stays correct:
+ *
+ * - A chunk is a page of projected events, at most 12 KB of plaintext, sealed
+ *   with push envelope v1 for the account's pinned devices plus this machine
+ *   (the relay is not a recipient; there is no plaintext upload at all). The
+ *   sealed body carries `{sessionKey, seq, events}` so the reader can check the
+ *   chunk is the one it asked for.
+ * - `seq` is per session and only goes up. It starts from the clock when a
+ *   session has no state (the server allows gaps), so a wiped state directory
+ *   cannot collide with chunks the server already holds.
+ * - Reading and uploading are decoupled by an outbox on disk. A read becomes
+ *   chunks, and the chunks, the new byte offset and `seq` are written in one
+ *   atomic replace; only then is anything uploaded, and an upload retries the
+ *   stored bytes. A crash therefore loses nothing and, because a retry sends
+ *   the same bytes under the same `seq`, duplicates nothing (the server answers
+ *   a repeated chunk 200).
+ * - The offset is the end of the last complete line that went out (inside a line
+ *   too long to read, where that line began), so the state file holds numbers and
+ *   ciphertext, never conversation text. It also names the agent kind, so a
+ *   session that is gone after a restart is still read to the end of its transcript.
+ * - A transcript that is not a file (opencode's SQLite store) is read by its
+ *   agent's own `TranscriptReader`, and where it was read to is that reader's
+ *   cursor, kept in the state file beside the offset. The cursor is the reader's
+ *   to keep free of conversation text (opencode's holds row numbers and keys).
+ *
+ * Flush rules: events wait for 2 s of quiet, or 12 KB, or a prompt in the read
+ * (a person typed — that goes out now). A transcript that changes name
+ * (`/clear`, compaction, resume) keeps the session's key; events not newer than
+ * the last one sent are dropped on every read of a new file until the first
+ * newer one, because a new file may start with a copy of the old history.
+ *
+ * Every dependency that touches the world is injected, so tests run real ticks
+ * on a temporary directory with a fake clock and no network.
+ */
+import { type TranscriptProjector, type TranscriptReader } from './transcript-tail.js';
+/** Poll cadence for every observed session; an idle transcript costs one `stat`. */
+export declare const RECORDER_TICK_MS = 1000;
+/** Quiet time after the last append before pending events go out. */
+export declare const RECORDER_QUIET_MS = 2000;
+/** Plaintext bytes that flush on their own (the live frame's budget, `MAX_TURN_FRAME_BYTES`). */
+export declare const RECORDER_FLUSH_BYTES: number;
+/** First run on a session: only the last this-many events of the transcript. */
+export declare const RECORDER_BACKFILL_EVENTS = 400;
+/** Chunks waiting to upload, per session; past it nothing more is read until some go out. */
+export declare const RECORDER_OUTBOX_MAX = 20;
+/** Recipient slots on one chunk: the server's `deviceKeyMap` limit. */
+export declare const RECORDER_MAX_RECIPIENTS = 50;
+/** Retry backoff for a failing upload: doubles from the base up to the cap. */
+export declare const RECORDER_BACKOFF_BASE_MS = 2000;
+export declare const RECORDER_BACKOFF_MAX_MS: number;
+/** How long a session is left alone after the server refused it (a daily cap, a bad key). */
+export declare const RECORDER_PAUSE_MS: number;
+/** A reader's transcript a session has left is over once it has read as nothing new this long: a reader
+ *  answers nothing also when it did not look (opencode asks its store at most once a second, and not
+ *  again at once after a failed query), so one empty read says nothing. */
+export declare const RECORDER_READER_SETTLE_MS = 3000;
+/** A session no longer in the inventory is followed this long, so its last words still go out. */
+export declare const RECORDER_LINGER_MS = 60000;
+/** State files untouched this long, with nothing waiting, are deleted at start. */
+export declare const RECORDER_STATE_TTL_MS: number;
+/** Read-but-unsealed events held in memory; past this a read waits (the transcript keeps them). */
+export declare const RECORDER_PENDING_MAX_BYTES: number;
+/** How long a tick waits to learn who a chunk is sealed for; past it nothing is read this round. */
+export declare const RECORDER_RECIPIENTS_TIMEOUT_MS = 10000;
+/** `seq` of a session with no state: seconds since the epoch × this (the server takes up to 10^12 - 1). */
+export declare const RECORDER_SEQ_PER_SECOND = 100;
+export interface RecordableSession {
+    /** The transcript this session writes right now. */
+    path: string;
+    /** `RegisteredRemoteAgent.kind` — which projector reads it. */
+    kind: string;
+}
+/** A pinned device's key, or this machine's own. */
+export interface RecorderRecipient {
+    deviceId: string;
+    publicKey: string;
+}
+/** The push-v1 envelope of one chunk, as the server stores it. */
+export interface SealedChunk {
+    body: string;
+    deviceKeyMap: Record<string, string>;
+    senderPublicKey: string;
+}
+export interface OutboxChunk {
+    seq: number;
+    firstAt: string;
+    lastAt: string;
+    sealed: SealedChunk;
+}
+export type UploadOutcome = 
+/** Stored (201) or already stored (200). */
+{
+    kind: 'ok';
+}
+/** Try again later: network, 5xx, per-minute rate limit. */
+ | {
+    kind: 'retry';
+    afterMs?: number;
+    why: string;
+}
+/** The server will not take this now (daily cap, wrong key or device): leave the session alone for a while. */
+ | {
+    kind: 'pause';
+    untilMs?: number;
+    why: string;
+    giveUpAfter?: number;
+}
+/** The server will never take these bytes (a bad body, a `seq` already holding another): drop the chunk, or it blocks the session for good. */
+ | {
+    kind: 'drop';
+    why: string;
+    conflict?: boolean;
+};
+export interface TurnRecorderDeps {
+    /** Where per-session state lives (`<stateDir>/turn-recorder`). */
+    dir: string;
+    deviceId: () => string;
+    /** The projector for an agent kind, or null when its transcript is not one this can read. */
+    projectorFor: (kind: string) => TranscriptProjector | null;
+    /** How an agent kind's transcript is read when it is not an append-only file (`TranscriptSource.read`); null reads the file. */
+    readerFor?: (kind: string) => TranscriptReader | null;
+    /** Who a chunk is sealed for. Empty = nobody could read it, so nothing is read or sent. Never rejects. */
+    recipients: () => Promise<RecorderRecipient[]>;
+    /** Seal one plaintext body for those recipients. Rejecting leaves everything as it was. */
+    seal: (plaintext: string, recipients: RecorderRecipient[]) => Promise<SealedChunk>;
+    upload: (sessionKey: string, chunk: OutboxChunk) => Promise<UploadOutcome>;
+    /** False until this machine's device key is on its device record: the server takes a chunk only
+     *  when it is sealed with that key. Chunks are still read and sealed meanwhile; they wait. */
+    uploadReady?: () => boolean;
+    /** This machine's current device public key. A stored chunk sealed with another one (the
+     *  key file was lost and made anew) can never be accepted — the server wants the key on
+     *  the device record — so it is dropped rather than refused for ever. */
+    devicePublicKey?: () => string | null;
+    /** The newest `seq` the server holds for a session, or null when it cannot be read. After a 409
+     *  (the same `seq` under another body) the next chunk is numbered past it. */
+    latestSeq?: (sessionKey: string) => Promise<number | null>;
+    log: (message: string) => void;
+    now?: () => number;
+}
+interface SessionState {
+    v: 1;
+    sessionKey: string;
+    /** The transcript the offset belongs to. */
+    path: string;
+    /** The agent kind that wrote it, so a session that is gone after a restart can still be read to its end. */
+    kind?: string;
+    ino: number;
+    /** End of the last complete line whose events are in a chunk. */
+    offset: number;
+    /** Where the agent's own reader had read to when the chunks were made (`TailState.cursor`); only a reader's transcript has one. */
+    cursor?: unknown;
+    /** The last `seq` handed out. */
+    seq: number;
+    /** Newest event time sent so far. */
+    lastAt?: string;
+    outbox: OutboxChunk[];
+}
+/** What is on disk, or null when it is missing or not ours (a bad file is a fresh start, never a crash). */
+export declare const readSessionState: (dir: string, sessionKey: string) => SessionState | null;
+/**
+ * Delete state files nothing has touched for a long while, nothing is waiting in, and whose
+ * transcript is gone. A session that is quiet but alive keeps its state: without it the next
+ * read takes the last 400 events of the transcript again and uploads them under new `seq`s.
+ */
+export declare const sweepRecorderState: (dir: string, now?: number) => void;
+export declare const createTurnRecorder: (deps: TurnRecorderDeps) => {
+    observe: (found: Readonly<Record<string, RecordableSession>>) => void;
+    tick: () => Promise<void>;
+    start: () => void;
+    stop: () => void;
+    size: () => number;
+};
+export type TurnRecorder = ReturnType<typeof createTurnRecorder>;
+/** The recipients of a chunk: this machine, then the newest pinned devices, within the server's slot limit. */
+export declare const chooseRecipients: (self: RecorderRecipient | null, pinned: ReadonlyArray<RecorderRecipient & {
+    pinnedAt?: string;
+}>) => RecorderRecipient[];
+export {};
+//# sourceMappingURL=turn-recorder.d.ts.map