@zeph-to/cli 2.15.0 → 2.17.0

package/dist/turn-ring.js

@@ -0,0 +1,280 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diskTurnRing = exports.removeTurnRing = exports.sweepTurnRings = exports.readTurnRing = exports.appendTurnRing = exports.turnRingPath = exports.turnRingDir = exports.TURN_RING_TTL_MS = exports.MAX_TURN_RING_FILES = exports.MAX_TURN_RING_BYTES = void 0;
+const fs_1 = require("fs");
+const crypto_1 = require("crypto");
+const path_1 = require("path");
+const gate_js_1 = require("./gate.js");
+/**
+ * What the daemon has already sent a chat viewer, kept on disk so a
+ * re-subscribe can replay it.
+ *
+ * Why this exists at all: the live lane is ephemeral, and the transcript
+ * backfill deliberately replays only since the last prompt — finished turns are
+ * supposed to already exist in the chat as their completion pushes. Under the
+ * `quiet` push dial they do not exist, because that dial suppresses every
+ * auto-push without a `high` marker. A turn's closing words were therefore
+ * visible while it ran and gone the moment the viewer re-armed, with no record
+ * on the phone, on the server, or in the 256KB backfill window.
+ *
+ * Re-deriving those turns from the transcript is not an option: measured over
+ * this machine's transcripts larger than the window, the last 256KB holds a
+ * median of one human prompt and none at all in 8 of 19 files — a single
+ * `tool_result` line can be most of a megabyte. Projected events are a tool
+ * name, a short label and a verdict, so the same bytes hold turns rather than
+ * fragments of one.
+ *
+ * It lives beside `known-sessions.json` under `stateDir()` rather than in
+ * `~/.zeph`, for the same reason that file does: this is derived session state
+ * that expires, not configuration or keys.
+ *
+ * Everything here is best-effort. A ring that cannot be written costs the
+ * scrollback, never the live send — the daemon's job is to keep talking.
+ */
+/**
+ * One ring file. Trimming is by bytes and not by event count on purpose: a
+ * prose event carries up to `MAX_EVENT_TEXT_CHARS` (5000) while a tool event's
+ * label is clamped at `MAX_EVENT_FIELD_CHARS` (512), so a count would bound two
+ * things an order of magnitude apart.
+ */
+exports.MAX_TURN_RING_BYTES = 256 * 1024;
+/** Sessions with a ring. Past this the oldest by mtime are dropped. */
+exports.MAX_TURN_RING_FILES = 20;
+/** A week unwatched. Scrollback older than that is history, not context. */
+exports.TURN_RING_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+const turnRingDir = () => (0, path_1.join)((0, gate_js_1.stateDir)(), 'turns');
+exports.turnRingDir = turnRingDir;
+/**
+ * The session name is chosen by whoever sent the watch request, so it never
+ * reaches the filesystem — a hash does. Same move as `hashListenerId`, at twice
+ * the width: 64 bits, because these names collide within one machine's
+ * directory rather than identifying one device.
+ */
+const turnRingPath = (sessionName) => (0, path_1.join)((0, exports.turnRingDir)(), `${(0, crypto_1.createHash)('sha256').update(sessionName).digest('hex').slice(0, 16)}.jsonl`);
+exports.turnRingPath = turnRingPath;
+const isExpired = (path, now) => {
+    try {
+        return now - (0, fs_1.statSync)(path).mtimeMs > exports.TURN_RING_TTL_MS;
+    }
+    catch {
+        return false;
+    }
+};
+const removeQuietly = (path) => {
+    try {
+        (0, fs_1.unlinkSync)(path);
+    }
+    catch {
+        /* already gone, or not ours to delete */
+    }
+};
+/**
+ * How far under the cap a trim cuts.
+ *
+ * Trimming exactly to the cap would leave the file one event below it, so the
+ * next append crosses again and rewrites the whole thing — a full read, split
+ * and rename per event for the rest of the session. Cutting deeper buys roughly
+ * a quarter of the ring's worth of appends between rewrites.
+ */
+const TRIM_TARGET_BYTES = Math.floor(exports.MAX_TURN_RING_BYTES * 0.75);
+/** Keep the newest lines that fit under `MAX_TURN_RING_BYTES`. False when the cap still stands broken. */
+const trimToCap = (path) => {
+    let raw;
+    try {
+        if ((0, fs_1.statSync)(path).size <= exports.MAX_TURN_RING_BYTES)
+            return true;
+        raw = (0, fs_1.readFileSync)(path, 'utf-8');
+    }
+    catch {
+        return false;
+    }
+    const lines = raw.split('\n').filter((line) => line.length > 0);
+    let bytes = 0;
+    let start = lines.length;
+    // Newest first, until the next line would not fit.
+    while (start > 0) {
+        const size = Buffer.byteLength(lines[start - 1], 'utf-8') + 1;
+        if (bytes + size > TRIM_TARGET_BYTES)
+            break;
+        bytes += size;
+        start--;
+    }
+    // A single line longer than the whole cap takes nothing, which would empty
+    // the ring — and empty it again on every later append. The newest line
+    // always survives; the one after it trims this one away in turn.
+    start = Math.min(start, lines.length - 1);
+    const kept = lines
+        .slice(start)
+        .map((line) => `${line}\n`)
+        .join('');
+    // Through a temp file, unlike the append: a kill mid-append costs the last
+    // line, a kill mid-rewrite would cost the whole ring.
+    // Random name, exclusive create: a predictable `${path}.tmp` is a file
+    // another process on this machine can pre-create as a symlink and have this
+    // write follow. `wx` fails instead of following one.
+    const tmp = `${path}.${(0, crypto_1.randomBytes)(6).toString('hex')}.tmp`;
+    try {
+        (0, fs_1.writeFileSync)(tmp, kept, { mode: 0o600, flag: 'wx' });
+        (0, fs_1.renameSync)(tmp, path);
+        return true;
+    }
+    catch {
+        removeQuietly(tmp);
+        // The append landed but the cap did not. Saying the write succeeded
+        // would let the file grow past its bound with nothing ever noticing.
+        return false;
+    }
+};
+/**
+ * Record events this watch just sent. Call it with the same array that went out
+ * — the ring's whole meaning is "what the viewer already received", and a replay
+ * is that array sent again.
+ */
+const appendTurnRing = (sessionName, events) => {
+    if (!events.length)
+        return true;
+    let path;
+    try {
+        // Inside the guard: the name arrives off the wire, and a non-string one
+        // makes `createHash().update()` throw where "best-effort" is the whole
+        // contract — a ring that cannot be written must never take a tick down.
+        path = (0, exports.turnRingPath)(sessionName);
+        (0, fs_1.mkdirSync)((0, exports.turnRingDir)(), { recursive: true, mode: 0o700 });
+        (0, fs_1.appendFileSync)(path, events.map((event) => `${JSON.stringify(event)}\n`).join(''), { mode: 0o600 });
+        // `mode` on mkdir/append applies only when the entry is created, so a
+        // directory or file that already exists keeps whatever it had — a
+        // pre-created 0755 `turns/` would never become 0700 on its own. The
+        // modes are the only thing standing between another local account and a
+        // week of tool targets, prompts and URLs, so they are set every time
+        // (`config.ts:84` chmods its own file for the same reason).
+        (0, fs_1.chmodSync)((0, exports.turnRingDir)(), 0o700);
+        (0, fs_1.chmodSync)(path, 0o600);
+    }
+    catch {
+        // The caller says so once per session rather than per tick: a full disk
+        // costs the scrollback, and silence about it costs the diagnosis.
+        return false;
+    }
+    return trimToCap(path);
+};
+exports.appendTurnRing = appendTurnRing;
+/**
+ * What this session's viewers have already been sent, oldest first.
+ *
+ * An expired ring is deleted here rather than merely ignored: returning an empty
+ * array and leaving the file would let the next append land on top of pre-expiry
+ * content, and the TTL would bound nothing.
+ */
+const readTurnRing = (sessionName, now = Date.now()) => {
+    let raw;
+    let path;
+    try {
+        // Same reason as the append: the name is wire input, and hashing a
+        // non-string throws.
+        path = (0, exports.turnRingPath)(sessionName);
+        if (isExpired(path, now)) {
+            removeQuietly(path);
+            return [];
+        }
+        raw = (0, fs_1.readFileSync)(path, 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    const events = [];
+    for (const line of raw.split('\n')) {
+        if (!line)
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            // `null`, `5`, `[]` and `{}` are all valid JSON. Without a shape
+            // check a hand-edited or planted ring hands slice 02 a non-event to
+            // seal and send. `kind` is what every branch downstream switches on,
+            // so that is what makes a line an event — the same row-level filter
+            // `session-registry.ts:52-62` applies to its own file.
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+                continue;
+            if (typeof parsed.kind !== 'string')
+                continue;
+            events.push(parsed);
+        }
+        catch {
+            // A line the daemon was killed halfway through: skip it, keep the
+            // rest — again the transcript reader's rule.
+        }
+    }
+    return events;
+};
+exports.readTurnRing = readTurnRing;
+/** Drop expired rings, then the oldest ones past `MAX_TURN_RING_FILES`. */
+const sweepTurnRings = (now = Date.now()) => {
+    const dir = (0, exports.turnRingDir)();
+    let names;
+    try {
+        names = (0, fs_1.readdirSync)(dir);
+    }
+    catch {
+        return;
+    }
+    const live = [];
+    for (const name of names) {
+        const path = (0, path_1.join)(dir, name);
+        // A kill between the trim's write and its rename strands a temp file.
+        // Nothing else would ever remove it, and left in place it counts
+        // against MAX_TURN_RING_FILES and evicts a live ring early. Matching the
+        // ring's own name shape rather than just the extension also means a
+        // stray file dropped in here is cleaned up rather than counted.
+        if (!/^[0-9a-f]{16}\.jsonl$/.test(name)) {
+            removeQuietly(path);
+            continue;
+        }
+        let mtimeMs;
+        try {
+            mtimeMs = (0, fs_1.statSync)(path).mtimeMs;
+        }
+        catch {
+            continue;
+        }
+        if (now - mtimeMs > exports.TURN_RING_TTL_MS)
+            removeQuietly(path);
+        else
+            live.push({ path, mtimeMs });
+    }
+    if (live.length <= exports.MAX_TURN_RING_FILES)
+        return;
+    live.sort((a, b) => a.mtimeMs - b.mtimeMs);
+    for (const stale of live.slice(0, live.length - exports.MAX_TURN_RING_FILES))
+        removeQuietly(stale.path);
+};
+exports.sweepTurnRings = sweepTurnRings;
+/**
+ * Forget one session's scrollback outright — the machine was told to forget the
+ * session. False when the file is still there, which the caller has to say out
+ * loud: answering "forgotten" while a week of prompts and tool targets sits on
+ * disk is the one wrong answer here.
+ */
+const removeTurnRing = (sessionName) => {
+    let path;
+    try {
+        path = (0, exports.turnRingPath)(sessionName);
+    }
+    catch {
+        return true; // a name that cannot even be hashed has no ring
+    }
+    try {
+        (0, fs_1.unlinkSync)(path);
+        return true;
+    }
+    catch (err) {
+        // Already gone is the outcome the caller asked for. Checking existence
+        // first and then unlinking would call a file that vanished in between a
+        // failure, and answer "your scrollback is still there" about nothing.
+        return err?.code === 'ENOENT';
+    }
+};
+exports.removeTurnRing = removeTurnRing;
+exports.diskTurnRing = {
+    read: (sessionName) => (0, exports.readTurnRing)(sessionName),
+    append: (sessionName, events) => (0, exports.appendTurnRing)(sessionName, events),
+    sweep: () => (0, exports.sweepTurnRings)(),
+};

package/dist/turn-watch.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Live agent-chat timeline: tail this machine's Claude Code transcripts and push
+ * the small events off them over the relay the daemon already holds open.
+ *
+ * Sibling of the tmux mirror in `listener.ts`, deliberately not the same thing.
+ * The mirror sends a picture of a terminal; this sends what the agent *did*, so
+ * a phone can read a session the way the Claude app reads one — without the
+ * viewer having to parse ANSI, and without any of it becoming a push (no quota,
+ * no notification).
+ *
+ * Registry, lifecycle and framing mirror `activeStreams`/`stopStream`, because
+ * a second shape for the same job is a second set of leaks to find. What differs
+ * is the source: a file that grows, not a pane that repaints. `transcript-tail`
+ * owns that difference and stays pure; this file owns the socket and the clock.
+ *
+ * Every dependency that touches the world arrives through `TurnWatchDeps`, so
+ * the tests drive real ticks with a fake transcript and no WebSocket at all.
+ */
+import { type TurnEvent } from './transcript-tail.js';
+import type { TurnRing } from './turn-ring.js';
+/**
+ * Watchers this daemon will run at once — the same ceiling, for the same reason,
+ * as `MAX_CONCURRENT_STREAMS`. One machine can host a dozen tmux sessions, and
+ * a viewer that opened them all would otherwise have every one polling forever.
+ */
+export declare const MAX_TURN_WATCHERS = 3;
+/**
+ * Poll cadence. The plan's user-visible bar is "a tool call shows up within 2s";
+ * at 500 ms the read itself is never the reason it misses. Slower than the
+ * mirror's 400 ms on purpose — this loop answers "what happened", not "what does
+ * the screen look like", and nothing here is animated.
+ */
+export declare const TURN_POLL_INTERVAL_MS = 500;
+/**
+ * How long a watch survives without a renew.
+ *
+ * `watch.stop` is best-effort by construction: a swiped-away native sheet, a
+ * killed tab, or a dropped socket destroys the viewer before it can say
+ * anything. The lease — not the stop message — is what guarantees this daemon
+ * stops reading. Matches the terminal stream's `STREAM_SUB_TTL_SECONDS`.
+ */
+export declare const TURN_LEASE_MS = 60000;
+/**
+ * How often a live watch re-asks which transcript its session is writing.
+ *
+ * `/clear` and a compaction start a new session file under a new name; the old
+ * one simply stops growing, so a watcher pinned to the path it resolved at
+ * `start` goes quiet forever and looks exactly like an idle agent. Nothing in
+ * the file itself can signal this — the answer lives in the session registry —
+ * so it is asked for on a cadence rather than discovered.
+ *
+ * This is not a cheap question, and the number is chosen against its real cost:
+ * `resolveTranscript` runs `readPaneInfo`, an uncached blocking
+ * `spawnSync('tmux', …)` (`listener.ts`), and the pid-record memo behind it
+ * expires every 4s (`remote-agents.ts` SNAPSHOT_TTL_MS), so a recheck is one
+ * tmux spawn plus a real directory read — not a memo hit. At 10s per watcher and
+ * at most three watchers that stays under what the session report already spends
+ * on its own (`SESSION_REPORT_INTERVAL_MS` = 5s, one sweep for the whole
+ * machine), while keeping how long a cleared session stays dark to one interval.
+ */
+export declare const TRANSCRIPT_RECHECK_MS = 10000;
+/**
+ * Consecutive seal failures before the watch gives up and says so.
+ *
+ * Dropping a batch that will not seal is right; dropping every batch forever is
+ * an empty timeline the viewer cannot tell from an idle session. The mirror
+ * draws the same line with `STREAM_MAX_ENCRYPT_FAILURES`: fail closed, then stop
+ * and send an error the other side can render.
+ */
+export declare const MAX_TURN_SEAL_FAILURES = 3;
+/**
+ * Ceiling on one replay, in events.
+ *
+ * The viewer keeps a bounded window of live turns, and a replay that filled it
+ * on its own would push the turn actually in flight out of the very screen the
+ * replay exists to fill. Below the web cap on purpose, so the live tail still
+ * has room after a full replay.
+ */
+export declare const MAX_REPLAY_EVENTS = 400;
+/**
+ * Plaintext bytes per frame. Ephemeral frames ride API Gateway's 32KB WebSocket
+ * limit, and sealing base64-expands what goes in it — so this is deliberately
+ * below `SCREEN_PEEK_MAX_BYTES` (24KB, `listener.ts`), which bounds frames that
+ * are never sealed.
+ */
+export declare const MAX_TURN_FRAME_BYTES: number;
+/** Wire shape of one batch of timeline events. */
+export type TurnDeltaFrame = {
+    subtype: 'agent.turn.delta';
+    sessionName: string;
+    /** Incarnation of this watch. See `AgentTurnDeltaFrame` (zeph `libs/feed-ui`)
+     *  for why the pair exists; the mirror stamps frames the same way
+     *  (`StreamFramePayload.epoch`). */
+    epoch: number;
+    seq: number;
+    /** Plaintext batch — present only when the subscriber supplied no key. */
+    events?: TurnEvent[];
+    /** Sealed batch — the same array, encrypted for the subscriber. */
+    encrypted?: unknown;
+};
+/** What a viewer sends to start, keep, or end a watch. */
+export interface TurnWatchControl {
+    subtype?: string;
+    targetDeviceId?: string;
+    sessionName?: string;
+    /**
+     * The viewer's device public key. Present when that device can open what it
+     * asks to be sealed; absent on a device with no keypair, which then reads
+     * the same events in the clear — the convention `useAgentDiff` and
+     * `TerminalStreamView` already follow on the web side. Encryption is a paid
+     * feature, so refusing to serve an unsealed viewer would quietly make the
+     * whole timeline paid too.
+     */
+    subscriberPublicKey?: string;
+}
+export type SendTurnFrame = (data: Record<string, unknown>) => void;
+export interface TurnWatchDeps {
+    /** This machine's listener device id — control messages that name another are not ours. */
+    deviceId: () => string;
+    /** tmux session name → transcript file, or null when this session has none (a non-Claude agent). */
+    resolveTranscript: (sessionName: string) => string | null;
+    /** Whether tmux still holds this session. A watch outlives its pane otherwise. */
+    sessionExists: (sessionName: string) => boolean;
+    /**
+     * Load-or-create this device's keypair. Rejecting means this daemon cannot
+     * seal at all, which a viewer that asked for a seal must be told about
+     * rather than discovering three dropped batches later.
+     */
+    initCrypto: () => Promise<void>;
+    /** Seal a batch for the subscriber. Rejecting drops the batch; it never falls back to plaintext. */
+    seal: (plaintext: string, subscriberPublicKey: string) => Promise<unknown>;
+    log: (message: string) => void;
+    /** Where a watch's events are kept so a later watch can replay them. */
+    ring: TurnRing;
+    now?: () => number;
+}
+/**
+ * A registry of transcript watchers plus the control handler that drives it.
+ *
+ * A factory rather than module state so a test can hold its own, and so two of
+ * them never share a clock or a socket by accident.
+ */
+export declare const createTurnWatchers: (deps: TurnWatchDeps) => {
+    handle: (req: TurnWatchControl, send: SendTurnFrame) => boolean;
+    stop: (sessionName: string, reason: string) => void;
+    stopAll: (reason: string) => void;
+    tick: (sessionName: string) => Promise<void>;
+    size: () => number;
+};
+export type TurnWatchers = ReturnType<typeof createTurnWatchers>;
+//# sourceMappingURL=turn-watch.d.ts.map

package/dist/turn-watch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-watch.d.ts","sourceRoot":"","sources":["../src/turn-watch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAKH,KAAK,SAAS,EACjB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,QAAS,CAAC;AAEpC;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,qBAAqB,QAAS,CAAC;AAE5C;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,QAAY,CAAC;AAE9C,kDAAkD;AAClD,MAAM,MAAM,cAAc,GAAG;IACzB,OAAO,EAAE,kBAAkB,CAAC;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB;;wCAEoC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,0EAA0E;IAC1E,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC;IACrB,mEAAmE;IACnE,SAAS,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,0DAA0D;AAC1D,MAAM,WAAW,gBAAgB;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;AAEpE,MAAM,WAAW,aAAa;IAC1B,2FAA2F;IAC3F,QAAQ,EAAE,MAAM,MAAM,CAAC;IACvB,oGAAoG;IACpG,iBAAiB,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IAC1D,kFAAkF;IAClF,aAAa,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC;IAChD;;;;OAIG;IACH,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,oGAAoG;IACpG,IAAI,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3E,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,wEAAwE;IACxE,IAAI,EAAE,QAAQ,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACtB;AAuDD;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,MAAM,aAAa;kBA2N7B,gBAAgB,QAAQ,aAAa,KAAG,OAAO;wBAvNzC,MAAM,UAAU,MAAM,KAAG,IAAI;sBAe/B,MAAM,KAAG,IAAI;wBASL,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;;CAoX1D,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC"}