@phnx-labs/agents-cli 1.20.63 → 1.20.65

package/dist/lib/serve/control.js

@@ -0,0 +1,260 @@
+import { createServer } from 'http';
+import fs from 'fs';
+import { spawn } from 'child_process';
+import { randomUUID, randomBytes } from 'crypto';
+import { getAgentsInvocation } from '../daemon.js';
+import { handleServeGet, resolveServeContext } from './server.js';
+import { verifyControlToken } from './token.js';
+import { readNewEvents, streamDir, streamLogPath } from './stream.js';
+const MAX_BODY_BYTES = 64 * 1024;
+const DEFAULT_STREAM_POLL_MS = 300;
+/** Pull the presented bearer token from either header form. */
+function presentedToken(req) {
+    const auth = req.headers['authorization'];
+    if (typeof auth === 'string' && auth.toLowerCase().startsWith('bearer ')) {
+        return auth.slice(7).trim();
+    }
+    const x = req.headers['x-agents-token'];
+    return typeof x === 'string' ? x.trim() : undefined;
+}
+/** Read a JSON request body with a hard size cap. Rejects on overflow/parse error. */
+function readJsonBody(req) {
+    return new Promise((resolve, reject) => {
+        let size = 0;
+        const chunks = [];
+        req.on('data', (c) => {
+            size += c.length;
+            if (size > MAX_BODY_BYTES) {
+                reject(new Error('request body too large'));
+                req.destroy();
+                return;
+            }
+            chunks.push(c);
+        });
+        req.on('end', () => {
+            const raw = Buffer.concat(chunks).toString('utf-8').trim();
+            if (!raw)
+                return resolve({});
+            try {
+                resolve(JSON.parse(raw));
+            }
+            catch {
+                reject(new Error('invalid JSON body'));
+            }
+        });
+        req.on('error', reject);
+    });
+}
+function sendJson(res, code, obj) {
+    res.writeHead(code, { 'content-type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify(obj));
+}
+/**
+ * SSE stream of a session's normalized NDJSON events, offset-tailed from its
+ * capture file. Resumes from `?offset=<bytes>` or the `Last-Event-ID` header
+ * (each event's `id:` is its exact byte offset, so resume neither loses nor
+ * duplicates). Closes when a terminal (`result`/`error`) event is seen or the
+ * client disconnects. A not-yet-created file simply yields nothing until the
+ * run starts writing — the phone can open the stream the instant it dispatches.
+ */
+export function startSessionStream(file, req, res, pollMs) {
+    res.writeHead(200, {
+        'content-type': 'text/event-stream',
+        'cache-control': 'no-cache',
+        connection: 'keep-alive',
+    });
+    const params = new URL(req.url ?? '/', 'http://anchor').searchParams;
+    const qOffset = Number.parseInt(params.get('offset') ?? '', 10);
+    const lastId = Number.parseInt(Array.isArray(req.headers['last-event-id'])
+        ? req.headers['last-event-id'][0]
+        : req.headers['last-event-id'] ?? '', 10);
+    // Clamp at the source: a negative/garbage offset (or Last-Event-ID) is
+    // meaningless and, worse, `Buffer.subarray(neg)` indexes from the END — so an
+    // unclamped negative offset would read nothing and never self-correct. A bad
+    // resume value replays from the start, the EventSource-friendly behavior.
+    const wanted = Number.isFinite(qOffset) ? qOffset : Number.isFinite(lastId) ? lastId : 0;
+    let offset = Math.max(0, wanted);
+    let closed = false;
+    let timer;
+    const stop = () => {
+        closed = true;
+        if (timer)
+            clearInterval(timer);
+    };
+    req.on('close', stop);
+    const tick = () => {
+        if (closed)
+            return;
+        const { events, newOffset, done } = readNewEvents(file, offset);
+        for (const { event, offset: at } of events) {
+            // `at` is the per-event resume point the CLIENT echoes as Last-Event-ID.
+            res.write(`id: ${at}\nevent: ${event.type}\ndata: ${JSON.stringify(event.raw)}\n\n`);
+        }
+        // The SERVER cursor always adopts newOffset — past every complete line,
+        // including trailing blank/non-JSON lines after the last event — so the
+        // stream always makes progress (even on an empty read) and never re-scans.
+        offset = newOffset;
+        if (done && !closed) {
+            res.write('event: end\ndata: {"ok":true}\n\n');
+            stop();
+            res.end();
+        }
+    };
+    tick(); // immediate catch-up from the resume offset
+    if (!closed)
+        timer = setInterval(tick, pollMs);
+}
+/**
+ * Spawn a detached child and settle once it has either successfully spawned or
+ * failed to. Attaching an `'error'` listener is mandatory: a `ChildProcess` is
+ * an `EventEmitter`, so an `'error'` event (e.g. ENOENT from a stale/missing
+ * `agents` binary — a real condition `validateDaemonBinary` guards against)
+ * with no listener throws and would take down the whole anchor process, not
+ * just the one request. Mirrors the `once('spawn') / once('error')` pattern in
+ * `teams/agents.ts`. The `'error'` listener registered by `once` survives after
+ * a successful spawn, so a later error is absorbed rather than crashing.
+ */
+export function spawnDetached(command, args, stdio = 'ignore') {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, { detached: true, stdio, env: process.env });
+        child.once('spawn', () => {
+            child.unref();
+            resolve();
+        });
+        child.once('error', (err) => reject(err instanceof Error ? err : new Error(String(err))));
+    });
+}
+/**
+ * Default run dispatcher: re-invoke `agents run` with a server-minted id so the
+ * run is addressable, detached so it outlives this request (and the anchor
+ * process). Local runs detach here; `--host` runs detach on the executor via
+ * the existing dispatch path.
+ */
+export const defaultRunner = async (req) => {
+    if (!req.agent?.trim())
+        throw new Error('agent is required');
+    if (!req.prompt?.trim())
+        throw new Error('prompt is required');
+    const name = `ios-${randomBytes(3).toString('hex')}`;
+    // claude accepts an explicit session UUID; other agents resolve by --name.
+    const sessionId = req.agent === 'claude' ? randomUUID() : name;
+    const argv = ['run', req.agent, req.prompt, '--json', '--headless', '--quiet', '--name', name];
+    if (req.agent === 'claude')
+        argv.push('--session-id', sessionId);
+    if (req.mode)
+        argv.push('--mode', req.mode);
+    if (req.host)
+        argv.push('--host', req.host);
+    if (req.cwd)
+        argv.push('--cwd', req.cwd);
+    const inv = getAgentsInvocation(argv);
+    // Await spawn/error so a failed launch becomes a clean 400, never an
+    // unhandled 'error' that crashes the anchor for every other session.
+    //
+    // For an anchor-local run, capture the `--json` NDJSON to a per-session file
+    // so `GET /api/session/:id/stream` can offset-tail it. A `--host` run emits
+    // its NDJSON on the remote box (streaming that reuses pullRemoteLogDelta — a
+    // follow-up), so we don't capture the local dispatcher's output.
+    if (req.host) {
+        await spawnDetached(inv.command, inv.args);
+    }
+    else {
+        fs.mkdirSync(streamDir(), { recursive: true });
+        const fd = fs.openSync(streamLogPath(sessionId), 'a');
+        try {
+            await spawnDetached(inv.command, inv.args, ['ignore', fd, fd]);
+        }
+        finally {
+            // The child inherited the fd; the parent's copy is no longer needed.
+            fs.closeSync(fd);
+        }
+    }
+    return { sessionId, name };
+};
+/** Default messenger: re-invoke `agents message <id> <text>` and await its exit. */
+export const defaultMessenger = async (id, text, from) => {
+    const argv = ['message', id, text];
+    if (from)
+        argv.push('--from', from);
+    const inv = getAgentsInvocation(argv);
+    const code = await new Promise((resolve) => {
+        const child = spawn(inv.command, inv.args, { stdio: 'ignore', env: process.env });
+        child.on('exit', (c) => resolve(c ?? 1));
+        child.on('error', () => resolve(1));
+    });
+    if (code !== 0)
+        throw new Error(`agents message exited with code ${code}`);
+};
+/**
+ * Create (but do not start) the authenticated control server. Caller invokes
+ * `.listen(port, bind)`.
+ */
+export function createControlServer(opts = {}) {
+    const ctx = resolveServeContext(opts);
+    const verify = opts.verifyToken ?? verifyControlToken;
+    const runner = opts.runner ?? defaultRunner;
+    const messenger = opts.messenger ?? defaultMessenger;
+    const streamPollMs = opts.streamPollMs ?? DEFAULT_STREAM_POLL_MS;
+    const streamLogPathFor = opts.streamLogPathFor ?? streamLogPath;
+    return createServer(async (req, res) => {
+        // Auth gates EVERY request — this server may be reachable off-box.
+        if (!verify(presentedToken(req))) {
+            res.writeHead(401, { 'content-type': 'application/json', 'www-authenticate': 'Bearer' });
+            res.end(JSON.stringify({ error: 'unauthorized' }));
+            return;
+        }
+        const method = req.method ?? 'GET';
+        const url = (req.url || '/').split('?')[0];
+        if (method === 'GET') {
+            const streamMatch = /^\/api\/session\/([^/]+)\/stream$/.exec(url);
+            if (streamMatch) {
+                const id = decodeURIComponent(streamMatch[1]);
+                startSessionStream(streamLogPathFor(id), req, res, streamPollMs);
+                return;
+            }
+            const handled = await handleServeGet(url, req, res, ctx);
+            if (!handled)
+                sendJson(res, 404, { error: 'not found' });
+            return;
+        }
+        if (method === 'POST' && url === '/api/run') {
+            try {
+                const body = (await readJsonBody(req));
+                const result = await runner(body);
+                sendJson(res, 200, result);
+            }
+            catch (err) {
+                sendJson(res, 400, { error: String(err?.message ?? err) });
+            }
+            return;
+        }
+        const msgMatch = method === 'POST' && /^\/api\/session\/([^/]+)\/message$/.exec(url);
+        if (msgMatch) {
+            const id = decodeURIComponent(msgMatch[1]);
+            try {
+                const body = (await readJsonBody(req));
+                if (!body.text?.trim())
+                    throw new Error('text is required');
+                await messenger(id, body.text, body.from);
+                sendJson(res, 200, { ok: true, id });
+            }
+            catch (err) {
+                sendJson(res, 400, { error: String(err?.message ?? err) });
+            }
+            return;
+        }
+        sendJson(res, 404, { error: 'not found' });
+    });
+}
+/** Start the control server on `port`, bound to `bind`. Resolves the bound port. */
+export function startControlServer(port, bind, opts = {}) {
+    const server = createControlServer(opts);
+    return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, bind, () => {
+            const addr = server.address();
+            const boundPort = typeof addr === 'object' && addr ? addr.port : port;
+            resolve({ server, port: boundPort });
+        });
+    });
+}

package/dist/lib/serve/server.d.ts

@@ -9,11 +9,26 @@
  *
  * The whole thing is a viewer over data other commands already own
  * ({@link assembleState}); it writes nothing.
+ *
+ * The GET routing is exported as {@link handleServeGet} so the authenticated
+ * `--control` variant (see control.ts) can reuse it verbatim rather than
+ * duplicate the state/SSE surface.
  */
-import http from 'http';
+import type http from 'http';
 import type { ServeState } from './data.js';
 /** Loopback address — the server binds here and nowhere else. */
 export declare const SERVE_HOST = "127.0.0.1";
+/**
+ * DNS-rebinding guard. The socket binds loopback, but binding alone does not
+ * stop a remote page: an attacker can point a hostname's DNS at 127.0.0.1 and
+ * drive the victim's browser to `GET /api/state`, which exposes uncommitted
+ * `git diff HEAD` of every worktree plus routine + cloud config. A browser
+ * always sends a `Host` header naming the site it *thinks* it reached, so we
+ * trust only a Host that is itself loopback. A missing Host (HTTP/1.0 or a raw
+ * non-browser client like curl-without-Host) is not a rebind vector and is
+ * allowed; any explicit non-loopback Host is rejected.
+ */
+export declare function isAllowedServeHost(hostHeader: string | undefined): boolean;
 /** Default port for `agents serve`. */
 export declare const DEFAULT_SERVE_PORT = 4477;
 /** Default SSE push cadence. */
@@ -31,6 +46,25 @@ export interface ServeOptions {
      */
     snapshot?: () => Promise<ServeState>;
 }
+/**
+ * Resolved GET-route context: the snapshot source and SSE cadence, with all
+ * defaults applied. Built once by {@link resolveServeContext}.
+ */
+export interface ServeContext {
+    snapshot: () => Promise<ServeState>;
+    intervalMs: number;
+}
+/** Apply defaults to {@link ServeOptions}, producing a {@link ServeContext}. */
+export declare function resolveServeContext(opts?: ServeOptions): ServeContext;
+/**
+ * Handle the shared read-only GET surface (`/`, `/api/state`, `/events`).
+ * Returns `true` when the route was recognized and a response was written (or
+ * begun, for SSE); `false` when the path is unknown so the caller can 404 or
+ * try its own routes first. Extracted so the `--control` server reuses the
+ * exact same state/SSE behavior — including the load-bearing SSE close/timer
+ * ordering below — without duplicating it.
+ */
+export declare function handleServeGet(url: string, req: http.IncomingMessage, res: http.ServerResponse, ctx: ServeContext): Promise<boolean>;
 /**
  * Create (but do not start) the read-only serve server. Caller invokes
  * `.listen(port, SERVE_HOST)`. Returned so tests can bind an ephemeral port.

package/dist/lib/serve/server.js

@@ -1,33 +1,118 @@
-/**
- * Read-only localhost HTTP + Server-Sent-Events server for `agents serve`.
- *
- * There is deliberately NO framework and NO mutation surface:
- *  - binds 127.0.0.1 only (loopback) — never reachable off the machine;
- *  - answers GET only (every other method → 405);
- *  - routes: `GET /` → HTML page, `GET /api/state` → JSON snapshot,
- *    `GET /events` → SSE stream that re-pushes the snapshot on an interval.
- *
- * The whole thing is a viewer over data other commands already own
- * ({@link assembleState}); it writes nothing.
- */
-import http from 'http';
+import { createServer } from 'http';
 import { assembleState } from './data.js';
 import { renderPage } from './page.js';
 /** Loopback address — the server binds here and nowhere else. */
 export const SERVE_HOST = '127.0.0.1';
+/**
+ * DNS-rebinding guard. The socket binds loopback, but binding alone does not
+ * stop a remote page: an attacker can point a hostname's DNS at 127.0.0.1 and
+ * drive the victim's browser to `GET /api/state`, which exposes uncommitted
+ * `git diff HEAD` of every worktree plus routine + cloud config. A browser
+ * always sends a `Host` header naming the site it *thinks* it reached, so we
+ * trust only a Host that is itself loopback. A missing Host (HTTP/1.0 or a raw
+ * non-browser client like curl-without-Host) is not a rebind vector and is
+ * allowed; any explicit non-loopback Host is rejected.
+ */
+export function isAllowedServeHost(hostHeader) {
+    if (!hostHeader)
+        return true;
+    const host = hostHeader.replace(/:\d+$/, '').toLowerCase().replace(/^\[|\]$/g, '');
+    return host === 'localhost' || host === '127.0.0.1' || host === '::1';
+}
 /** Default port for `agents serve`. */
 export const DEFAULT_SERVE_PORT = 4477;
 /** Default SSE push cadence. */
 export const DEFAULT_INTERVAL_MS = 3000;
+/** Apply defaults to {@link ServeOptions}, producing a {@link ServeContext}. */
+export function resolveServeContext(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    return {
+        snapshot: opts.snapshot ?? (() => assembleState(cwd)),
+        intervalMs: opts.intervalMs ?? DEFAULT_INTERVAL_MS,
+    };
+}
+/**
+ * Handle the shared read-only GET surface (`/`, `/api/state`, `/events`).
+ * Returns `true` when the route was recognized and a response was written (or
+ * begun, for SSE); `false` when the path is unknown so the caller can 404 or
+ * try its own routes first. Extracted so the `--control` server reuses the
+ * exact same state/SSE behavior — including the load-bearing SSE close/timer
+ * ordering below — without duplicating it.
+ */
+export async function handleServeGet(url, req, res, ctx) {
+    if (url === '/' || url === '/index.html') {
+        const html = renderPage();
+        res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+        res.end(html);
+        return true;
+    }
+    if (url === '/api/state') {
+        try {
+            const state = await ctx.snapshot();
+            res.writeHead(200, { 'content-type': 'application/json; charset=utf-8' });
+            res.end(JSON.stringify(state));
+        }
+        catch (err) {
+            res.writeHead(500, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({ error: String(err?.message ?? err) }));
+        }
+        return true;
+    }
+    if (url === '/events') {
+        res.writeHead(200, {
+            'content-type': 'text/event-stream',
+            'cache-control': 'no-cache',
+            connection: 'keep-alive',
+        });
+        let closed = false;
+        // Declare the timer first and register the disconnect cleanup BEFORE the
+        // first `await push()`. `assembleState()` (team scan + git diffs) can be
+        // slow; if the client disconnects during it, the one-shot 'close' must
+        // already have a listener — otherwise it fires into the void, the interval
+        // starts anyway, and we leak a timer writing to a destroyed socket forever.
+        let timer;
+        req.on('close', () => {
+            closed = true;
+            if (timer)
+                clearInterval(timer);
+        });
+        const push = async () => {
+            if (closed)
+                return;
+            try {
+                const state = await ctx.snapshot();
+                if (closed)
+                    return;
+                res.write(`event: state\ndata: ${JSON.stringify(state)}\n\n`);
+            }
+            catch (err) {
+                if (!closed)
+                    res.write(`event: error\ndata: ${JSON.stringify({ error: String(err) })}\n\n`);
+            }
+        };
+        await push(); // immediate first frame
+        // Only arm the interval if the client is still connected. If 'close' fired
+        // during the first push, `closed` is already true (and the handler ran
+        // while `timer` was undefined), so starting an interval here would leak.
+        if (!closed)
+            timer = setInterval(push, ctx.intervalMs);
+        return true;
+    }
+    return false;
+}
 /**
  * Create (but do not start) the read-only serve server. Caller invokes
  * `.listen(port, SERVE_HOST)`. Returned so tests can bind an ephemeral port.
  */
 export function createServeServer(opts = {}) {
-    const cwd = opts.cwd ?? process.cwd();
-    const intervalMs = opts.intervalMs ?? DEFAULT_INTERVAL_MS;
-    const snapshot = opts.snapshot ?? (() => assembleState(cwd));
-    const server = http.createServer(async (req, res) => {
+    const ctx = resolveServeContext(opts);
+    const server = createServer(async (req, res) => {
+        // DNS-rebind guard: reject any explicit non-loopback Host before doing work.
+        if (!isAllowedServeHost(req.headers.host)) {
+            res.writeHead(403, { 'content-type': 'text/plain' });
+            res.end('forbidden: non-local Host');
+            return;
+        }
         // Read-only: reject anything that could mutate. Only GET is served.
         if (req.method !== 'GET') {
             res.writeHead(405, { 'content-type': 'text/plain', allow: 'GET' });
@@ -35,66 +120,11 @@ export function createServeServer(opts = {}) {
             return;
         }
         const url = (req.url || '/').split('?')[0];
-        if (url === '/' || url === '/index.html') {
-            const html = renderPage();
-            res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
-            res.end(html);
-            return;
-        }
-        if (url === '/api/state') {
-            try {
-                const state = await snapshot();
-                res.writeHead(200, { 'content-type': 'application/json; charset=utf-8' });
-                res.end(JSON.stringify(state));
-            }
-            catch (err) {
-                res.writeHead(500, { 'content-type': 'application/json' });
-                res.end(JSON.stringify({ error: String(err?.message ?? err) }));
-            }
-            return;
-        }
-        if (url === '/events') {
-            res.writeHead(200, {
-                'content-type': 'text/event-stream',
-                'cache-control': 'no-cache',
-                connection: 'keep-alive',
-            });
-            let closed = false;
-            // Declare the timer first and register the disconnect cleanup BEFORE the
-            // first `await push()`. `assembleState()` (team scan + git diffs) can be
-            // slow; if the client disconnects during it, the one-shot 'close' must
-            // already have a listener — otherwise it fires into the void, the interval
-            // starts anyway, and we leak a timer writing to a destroyed socket forever.
-            let timer;
-            req.on('close', () => {
-                closed = true;
-                if (timer)
-                    clearInterval(timer);
-            });
-            const push = async () => {
-                if (closed)
-                    return;
-                try {
-                    const state = await snapshot();
-                    if (closed)
-                        return;
-                    res.write(`event: state\ndata: ${JSON.stringify(state)}\n\n`);
-                }
-                catch (err) {
-                    if (!closed)
-                        res.write(`event: error\ndata: ${JSON.stringify({ error: String(err) })}\n\n`);
-                }
-            };
-            await push(); // immediate first frame
-            // Only arm the interval if the client is still connected. If 'close' fired
-            // during the first push, `closed` is already true (and the handler ran
-            // while `timer` was undefined), so starting an interval here would leak.
-            if (!closed)
-                timer = setInterval(push, intervalMs);
-            return;
+        const handled = await handleServeGet(url, req, res, ctx);
+        if (!handled) {
+            res.writeHead(404, { 'content-type': 'text/plain' });
+            res.end('not found');
         }
-        res.writeHead(404, { 'content-type': 'text/plain' });
-        res.end('not found');
     });
     return server;
 }

package/dist/lib/serve/stream.d.ts

@@ -0,0 +1,43 @@
+/** Directory holding per-session NDJSON capture files. */
+export declare function streamDir(): string;
+/** Capture-file path for a session id (id is sanitized to a safe filename). */
+export declare function streamLogPath(sessionId: string): string;
+/** A normalized event handed to the phone. `raw` is the untouched harness line. */
+export interface StreamEvent {
+    /** UI-facing discriminator: message | tool_use | tool_result | result | error | system | unknown. */
+    type: string;
+    raw: unknown;
+}
+/**
+ * Normalize one harness JSON line to a {@link StreamEvent}. Schemas differ per
+ * agent (there is no unified enum in the CLI), so we key off the common `type`
+ * field (Claude stream-json: `assistant` | `user` | `result` | `system`; a
+ * tool-use lives inside an `assistant` message's content) and carry `raw`
+ * through untouched so the client can render richer detail without the anchor
+ * having to model every agent.
+ */
+export declare function normalizeEvent(obj: unknown): StreamEvent;
+/** A parsed event paired with the byte offset immediately AFTER its line. */
+export interface OffsetEvent {
+    event: StreamEvent;
+    /** Resume point: absolute byte offset just past this event's newline. */
+    offset: number;
+}
+/** Result of one offset-tail read of a capture file. */
+export interface ReadResult {
+    events: OffsetEvent[];
+    /** Byte offset advanced ONLY past complete newline-terminated lines. */
+    newOffset: number;
+    /** True once a terminal event (result/error) has been parsed. */
+    done: boolean;
+}
+/**
+ * Read complete NDJSON lines from `fromOffset`, byte-accurately. Each event
+ * carries the exact byte offset past its own newline so an SSE client can set
+ * `Last-Event-ID` per event and resume with neither loss nor duplication even
+ * if the connection drops mid-batch. A trailing partial line (no newline yet)
+ * is left unconsumed so the offset never splits a multi-byte event — the next
+ * read picks it up once the harness flushes the newline. Non-JSON preamble
+ * lines are skipped, not fatal.
+ */
+export declare function readNewEvents(file: string, fromOffset: number): ReadResult;

package/dist/lib/serve/stream.js

@@ -0,0 +1,116 @@
+/**
+ * Live NDJSON event bridge for the iOS cockpit (RUSH-1732).
+ *
+ * A control-mode run (`defaultRunner`) is launched with `--json`, so the agent
+ * harness emits one JSON event per line. We capture that stream to a per-session
+ * logfile and replay it to the phone over SSE at `GET /api/session/:id/stream`,
+ * normalized to the small event set the UI needs. The read is **offset-tailed**
+ * — the same resumable pattern `hosts/progress.ts` uses for remote logs — so a
+ * phone that drops mid-run reconnects with `?offset=<bytes>` (or the standard
+ * `Last-Event-ID` header) and never loses or double-counts an event.
+ *
+ * Scope: this streams runs whose executor is the anchor itself (no `--host`).
+ * Streaming a run offloaded to another box reuses `pullRemoteLogDelta` and is a
+ * follow-up; see the changelog fragment.
+ */
+import fs from 'fs';
+import path from 'path';
+import { getCacheDir } from '../state.js';
+/** Directory holding per-session NDJSON capture files. */
+export function streamDir() {
+    return path.join(getCacheDir(), 'serve', 'streams');
+}
+/** Capture-file path for a session id (id is sanitized to a safe filename). */
+export function streamLogPath(sessionId) {
+    const safe = sessionId.replace(/[^a-zA-Z0-9._-]/g, '_');
+    return path.join(streamDir(), `${safe}.ndjson`);
+}
+/** Event types that terminate a run's stream (close the SSE). */
+const TERMINAL = new Set(['result', 'error']);
+/**
+ * Whether the run has ended — i.e. the file's LAST complete (newline-terminated)
+ * line is a terminal event. This is independent of any read offset, so a client
+ * that resumes from an offset already at/past the terminal event still learns
+ * the run is done and the SSE closes (instead of hanging on a `done:false` read
+ * that finds no new lines). Cheap: `readNewEvents` already has the full buffer.
+ */
+function fileIsDone(buf) {
+    const lastNl = buf.lastIndexOf(0x0a);
+    if (lastNl < 0)
+        return false;
+    const lines = buf.subarray(0, lastNl + 1).toString('utf-8').split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const s = lines[i].trim();
+        if (!s)
+            continue; // skip trailing blank lines
+        try {
+            return TERMINAL.has(normalizeEvent(JSON.parse(s)).type);
+        }
+        catch {
+            return false; // last complete line is a partial/non-JSON write — not done
+        }
+    }
+    return false;
+}
+/**
+ * Normalize one harness JSON line to a {@link StreamEvent}. Schemas differ per
+ * agent (there is no unified enum in the CLI), so we key off the common `type`
+ * field (Claude stream-json: `assistant` | `user` | `result` | `system`; a
+ * tool-use lives inside an `assistant` message's content) and carry `raw`
+ * through untouched so the client can render richer detail without the anchor
+ * having to model every agent.
+ */
+export function normalizeEvent(obj) {
+    const rec = obj;
+    const t = rec && typeof rec.type === 'string' ? rec.type : 'unknown';
+    return { type: t, raw: obj };
+}
+/**
+ * Read complete NDJSON lines from `fromOffset`, byte-accurately. Each event
+ * carries the exact byte offset past its own newline so an SSE client can set
+ * `Last-Event-ID` per event and resume with neither loss nor duplication even
+ * if the connection drops mid-batch. A trailing partial line (no newline yet)
+ * is left unconsumed so the offset never splits a multi-byte event — the next
+ * read picks it up once the harness flushes the newline. Non-JSON preamble
+ * lines are skipped, not fatal.
+ */
+export function readNewEvents(file, fromOffset) {
+    let buf;
+    try {
+        buf = fs.readFileSync(file);
+    }
+    catch {
+        // File not created yet (run still starting) — nothing to read, hold offset.
+        return { events: [], newOffset: fromOffset, done: false };
+    }
+    // `done` reflects the whole file's terminal state, so a resume at/past the
+    // terminal event still closes the stream rather than hanging forever.
+    const done = fileIsDone(buf);
+    if (fromOffset >= buf.length)
+        return { events: [], newOffset: fromOffset, done };
+    const slice = buf.subarray(fromOffset);
+    const lastNl = slice.lastIndexOf(0x0a);
+    if (lastNl < 0)
+        return { events: [], newOffset: fromOffset, done }; // no complete line yet
+    const events = [];
+    let lineStart = 0; // byte index within slice
+    for (let i = 0; i <= lastNl; i++) {
+        if (slice[i] !== 0x0a)
+            continue;
+        const lineBuf = slice.subarray(lineStart, i); // excludes the newline
+        const endOffset = fromOffset + i + 1; // absolute byte offset just past '\n'
+        lineStart = i + 1;
+        const s = lineBuf.toString('utf-8').trim();
+        if (!s)
+            continue;
+        let obj;
+        try {
+            obj = JSON.parse(s);
+        }
+        catch {
+            continue; // skip non-JSON (banner/preamble) lines
+        }
+        events.push({ event: normalizeEvent(obj), offset: endOffset });
+    }
+    return { events, newOffset: fromOffset + lastNl + 1, done };
+}