@reticlehq/server 3.7.0 → 3.8.1

package/dist/command/cli/doctor/doctor-agent-link.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The agent link row of `reticle doctor`, as one pure decision (reticlehq/reticle#1710).
+ *
+ * The row used to be built inline from the attach record alone: once a client had attached,
+ * enumerated and called, it stayed green forever, and a client that had started but never listed
+ * was told to restart the client. Both answers are wrong when the port is held but `/status`
+ * does not answer: the record cannot say whether the link works now, and the daemon row above
+ * already names the one fix for the held port. So in that state this row only points back at
+ * the daemon row. It never prints a second command, and it never says "the daemon", because
+ * this state also covers a port held by a different program.
+ *
+ * The record and action strings below are copied verbatim from the inline row this replaces;
+ * this module changes their priority, not their words.
+ */
+export interface AgentLinkInput {
+    /** The split-brain sentence, when this project is served by another daemon. */
+    split: string | undefined;
+    /** The attach-record action, or undefined when the record says the link worked. */
+    attachAction: string | undefined;
+    /** True when the port is held but `/status` does not answer. */
+    foreign: boolean;
+}
+export declare function agentLinkText(input: AgentLinkInput): string;

package/dist/command/cli/doctor/doctor-agent-link.js

@@ -0,0 +1,28 @@
+/**
+ * The agent link row of `reticle doctor`, as one pure decision (reticlehq/reticle#1710).
+ *
+ * The row used to be built inline from the attach record alone: once a client had attached,
+ * enumerated and called, it stayed green forever, and a client that had started but never listed
+ * was told to restart the client. Both answers are wrong when the port is held but `/status`
+ * does not answer: the record cannot say whether the link works now, and the daemon row above
+ * already names the one fix for the held port. So in that state this row only points back at
+ * the daemon row. It never prints a second command, and it never says "the daemon", because
+ * this state also covers a port held by a different program.
+ *
+ * The record and action strings below are copied verbatim from the inline row this replaces;
+ * this module changes their priority, not their words.
+ */
+/** The healthy-record sentence, word for word as doctor printed it before. */
+const RECORD_HEALTHY = '✓ an MCP client attached here and called tools before (a record, not a live check)';
+export function agentLinkText(input) {
+    if (input.split !== undefined) {
+        return `✗ ${input.split}`;
+    }
+    if (input.foreign) {
+        return '✗ the agent link is not checked live here — follow the daemon row above.';
+    }
+    if (input.attachAction === undefined) {
+        return RECORD_HEALTHY;
+    }
+    return `✗ ${input.attachAction}`;
+}

package/dist/command/cli/doctor/doctor-coverage-line.js

@@ -36,12 +36,6 @@ export function coverageLines(status) {
                 ...tab.prompt.split('\n').map((line) => `      ${line}`),
             ]
             : [];
-        const gate = tab.harnessGate;
-        const reason = 'object' === typeof gate && null !== gate
-            ? gate['reason']
-            : undefined;
-        // The Harness gate, in the sentence a refused drive says.
-        const locked = 'string' === typeof reason ? [`    ${reason}`] : [];
-        return [doctorRow(DoctorRow.COVERAGE, parts.join(' — ')), ...locked, ...prompt];
+        return [doctorRow(DoctorRow.COVERAGE, parts.join(' — ')), ...prompt];
     });
 }

package/dist/command/cli/doctor/doctor-rows.d.ts

@@ -64,6 +64,10 @@ export declare const DoctorRow: {
     readonly COVERAGE: "coverage";
     /** A project folder holding runs the platform never got. Only when there is one. */
     readonly UNSYNCED: "unsynced";
+    /** Per agent: does its prompt hook hand prompts to Reticle, or do the MCP instructions. */
+    readonly PROMPTS: "prompts";
+    /** The daemon's background sync for this project: on or off, why, and the last push. */
+    readonly SYNC: "sync";
 };
 type DoctorRowLabel = (typeof DoctorRow)[keyof typeof DoctorRow];
 export declare const DOCTOR_ROW_LABELS: readonly DoctorRowLabel[];

package/dist/command/cli/doctor/doctor-rows.js

@@ -64,6 +64,10 @@ export const DoctorRow = {
     COVERAGE: 'coverage',
     /** A project folder holding runs the platform never got. Only when there is one. */
     UNSYNCED: 'unsynced',
+    /** Per agent: does its prompt hook hand prompts to Reticle, or do the MCP instructions. */
+    PROMPTS: 'prompts',
+    /** The daemon's background sync for this project: on or off, why, and the last push. */
+    SYNC: 'sync',
 };
 export const DOCTOR_ROW_LABELS = Object.values(DoctorRow);
 /** Indent every row carries, before the label. */

package/dist/command/cli/drive/drive-attach.d.ts

@@ -74,6 +74,11 @@ export declare function readAttachResponse(port: number, url: string, res: {
     status: number;
     body: string;
 }): DriveAttachResult;
+/** The drive request got no answer in time: the daemon is up and busy, which is not a shutdown. */
+export declare class DriveRequestTimeout extends Error {
+    readonly ms: number;
+    constructor(ms: number);
+}
 /** Ask the daemon on `port` to open a driveable browser at `url`. */
 export declare function requestDriveSession(port: number, url: string, post?: DrivePost): Promise<DriveAttachResult>;
 /** Which app the attached page says it is, beside the project this directory names. */

package/dist/command/cli/drive/drive-attach.js

@@ -117,6 +117,15 @@ function parseJson(body) {
         return undefined;
     }
 }
+/** The drive request got no answer in time: the daemon is up and busy, which is not a shutdown. */
+export class DriveRequestTimeout extends Error {
+    ms;
+    constructor(ms) {
+        super(`no answer within ${String(ms)}ms`);
+        this.ms = ms;
+        this.name = 'DriveRequestTimeout';
+    }
+}
 /** Ask the daemon on `port` to open a driveable browser at `url`. */
 export async function requestDriveSession(port, url, post = postJson) {
     let res;
@@ -124,6 +133,17 @@ export async function requestDriveSession(port, url, post = postJson) {
         res = await post(port, DRIVE_PATH, JSON.stringify({ url }));
     }
     catch (error) {
+        // A timeout is not a shutdown (#1535). The daemon took the request and said nothing for the
+        // whole window, so it is alive and busy: telling the user it stopped sends them to restart a
+        // healthy daemon, and an agent into a retry loop that hits the same wait.
+        if (error instanceof DriveRequestTimeout) {
+            return {
+                ok: false,
+                reason: `the Reticle daemon on :${String(port)} took the drive request but gave no answer within ` +
+                    `${String(error.ms / 1000)}s. It is running; a cold browser launch can take this long. ` +
+                    'Check `reticle status`, then retry.',
+            };
+        }
         // The daemon answered /status a moment ago and is gone now — a shutdown, a crash, a `stop` from
         // another terminal. Retrying is the whole answer, and it is the one thing an errno never says.
         const message = error instanceof Error ? error.message : String(error);
@@ -281,7 +301,7 @@ function postJson(port, path, body) {
         req.on('error', reject);
         req.on('timeout', () => {
             req.destroy();
-            reject(new Error(`no answer within ${String(DRIVE_REQUEST_TIMEOUT_MS)}ms`));
+            reject(new DriveRequestTimeout(DRIVE_REQUEST_TIMEOUT_MS));
         });
         req.end(body);
     });

package/dist/command/cli/hook/codex-transcript.d.ts

@@ -0,0 +1,20 @@
+export declare const CODEX_AGENT = "codex";
+/** The `source` of a record imported from Codex's transcript rather than handed over by a hook. */
+export declare const CODEX_TRANSCRIPT_SOURCE = "codex-transcript";
+export declare const WEB_SEARCH_TOOL = "web_search";
+type Json = Record<string, unknown>;
+/** Codex's home: `$CODEX_HOME`, else `~/.codex`. */
+export declare function codexHome(env: NodeJS.ProcessEnv): string;
+/**
+ * The session's transcript: the payload's `transcript_path`, else the rollout file under
+ * `<codexHome>/sessions/` whose name ends with the session id.
+ * ponytail: walks every dated folder; a home with years of sessions would want the newest first.
+ */
+export declare function codexTranscriptPath(payload: Json, home: string): string | undefined;
+/** The web searches in a transcript's text, oldest first. */
+export declare function codexWebSearches(transcript: string, session: string, base: string): Json[];
+/** The searches not yet in `sessionFile`, by their `toolUseId`. */
+export declare function newCodexSearches(searches: readonly Json[], sessionFile: string): Json[];
+/** The transcript's text, or undefined when it is missing or too large to read now. */
+export declare function readTranscript(path: string): string | undefined;
+export {};

package/dist/command/cli/hook/codex-transcript.js

@@ -0,0 +1,224 @@
+/**
+ * Codex's web search, imported from Codex's own session transcript.
+ *
+ * Codex's `web_search` is a hosted tool: it never reaches PostToolUse (stated in the Codex hooks
+ * docs, and seen live on 2026-10-19). Codex does write it to its session transcript, which every
+ * hook payload names in `transcript_path` (else `$CODEX_HOME/sessions/**` holds it, named by the
+ * session id). So any Codex hook that fires (a tool call, the turn's Stop) reads that file and
+ * appends each search it has not kept yet to the same `agent-<session>.jsonl`, as an `agent_tool`
+ * record with `tool: "web_search"`.
+ *
+ * Two shapes, both read from real transcripts on this machine (structure only):
+ * - Codex 0.160.0: `event_msg` → `item_completed` whose `item` is `{ type: "Extension",
+ *   kind: "web.search", id, query, action, results[] }`, with `started_at_ms`/`completed_at_ms`.
+ * - Older builds: `response_item` → `web_search_call` `{ status, action }`: no result, no id, and
+ *   the line's `timestamp` is the only time.
+ *
+ * Idempotent: a search is keyed by its item id, else by its line number (the transcript is
+ * append-only), and a key already in the session file is skipped. Read-only on Codex's files.
+ */
+import { closeSync, fstatSync, openSync, readFileSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { redactSecrets } from '../../../memory/intent/record-request.js';
+import { AgentRecordKind, EPISODE_FILE_VERSION } from '../../../memory/journal/episode-log.js';
+export const CODEX_AGENT = 'codex';
+/** The `source` of a record imported from Codex's transcript rather than handed over by a hook. */
+export const CODEX_TRANSCRIPT_SOURCE = 'codex-transcript';
+export const WEB_SEARCH_TOOL = 'web_search';
+const CODEX_HOME_ENV = 'CODEX_HOME';
+const CODEX_DIR = '.codex';
+const SESSIONS_DIR = 'sessions';
+const ITEM_COMPLETED = 'item_completed';
+const EXTENSION_ITEM = 'Extension';
+const WEB_SEARCH_KIND = 'web.search';
+const WEB_SEARCH_CALL = 'web_search_call';
+const RESPONSE_ITEM = 'response_item';
+const FAILED = 'failed';
+/** A result keeps this many characters, as the hook's own records do. */
+const MAX_RESULT_TEXT = 4_000;
+const MAX_ARG_TEXT = 2_000;
+/** Codex's transcript holds the whole session. Past this size it is not read on a hook's time. */
+const MAX_TRANSCRIPT_BYTES = 64 * 1024 * 1024;
+const isObject = (value) => 'object' === typeof value && null !== value && !Array.isArray(value);
+const text = (value) => 'string' === typeof value && 0 < value.length ? value : undefined;
+/** Codex's home: `$CODEX_HOME`, else `~/.codex`. */
+export function codexHome(env) {
+    return text(env[CODEX_HOME_ENV]) ?? join(homedir(), CODEX_DIR);
+}
+/**
+ * The session's transcript: the payload's `transcript_path`, else the rollout file under
+ * `<codexHome>/sessions/` whose name ends with the session id.
+ * ponytail: walks every dated folder; a home with years of sessions would want the newest first.
+ */
+export function codexTranscriptPath(payload, home) {
+    const given = text(payload['transcript_path']);
+    if (given !== undefined) {
+        return given;
+    }
+    const session = text(payload['session_id']);
+    if (session === undefined) {
+        return undefined;
+    }
+    const suffix = `-${session}.jsonl`;
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return undefined;
+        }
+        for (const entry of entries) {
+            const path = join(dir, entry.name);
+            if (entry.isFile() && entry.name.endsWith(suffix)) {
+                return path;
+            }
+            if (entry.isDirectory()) {
+                const found = walk(path);
+                if (found !== undefined) {
+                    return found;
+                }
+            }
+        }
+        return undefined;
+    };
+    return walk(join(home, SESSIONS_DIR));
+}
+/** Every string redacted and cut, project paths made relative, as the hook's own args are. */
+function clean(value, base) {
+    if ('string' === typeof value) {
+        return redactSecrets(value.split(`${base}/`).join(''), MAX_ARG_TEXT);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => clean(item, base));
+    }
+    if (!isObject(value)) {
+        return value;
+    }
+    return Object.fromEntries(Object.entries(value)
+        .filter(([, v]) => null !== v && v !== undefined)
+        .map(([k, v]) => [k, clean(v, base)]));
+}
+/** One web search as an `agent_tool` record, or undefined when the line is not one. */
+function searchFrom(line, lineNo, session, base) {
+    const payload = isObject(line['payload']) ? line['payload'] : undefined;
+    if (payload === undefined) {
+        return undefined;
+    }
+    const who = {
+        v: EPISODE_FILE_VERSION,
+        agent: CODEX_AGENT,
+        agentSession: session,
+        kind: AgentRecordKind.TOOL,
+        source: CODEX_TRANSCRIPT_SOURCE,
+        tool: WEB_SEARCH_TOOL,
+    };
+    const item = isObject(payload['item']) ? payload['item'] : undefined;
+    if (ITEM_COMPLETED === payload['type'] &&
+        item !== undefined &&
+        EXTENSION_ITEM === item['type'] &&
+        WEB_SEARCH_KIND === item['kind']) {
+        const started = payload['started_at_ms'];
+        const ended = payload['completed_at_ms'];
+        const action = isObject(item['action']) ? item['action'] : { query: item['query'] };
+        const results = item['results'];
+        const full = results === undefined ? undefined : JSON.stringify(results);
+        return {
+            ...who,
+            toolUseId: text(item['id']) ?? `L${String(lineNo)}`,
+            args: clean(action, base),
+            ok: true,
+            ...(full === undefined
+                ? {}
+                : {
+                    result: {
+                        head: redactSecrets(full, MAX_RESULT_TEXT),
+                        chars: full.length,
+                        truncated: full.length > MAX_RESULT_TEXT,
+                    },
+                }),
+            ...('number' === typeof started ? { startedAt: started } : {}),
+            ...('number' === typeof ended ? { endedAt: ended } : {}),
+            ...('number' === typeof started && 'number' === typeof ended
+                ? { durationMs: ended - started }
+                : {}),
+        };
+    }
+    if (RESPONSE_ITEM === line['type'] && WEB_SEARCH_CALL === payload['type']) {
+        const at = Date.parse(String(line['timestamp']));
+        return {
+            ...who,
+            toolUseId: text(payload['id']) ?? `L${String(lineNo)}`,
+            args: clean(isObject(payload['action']) ? payload['action'] : {}, base),
+            ok: FAILED !== payload['status'],
+            ...(Number.isFinite(at) ? { endedAt: at } : {}),
+        };
+    }
+    return undefined;
+}
+/** The web searches in a transcript's text, oldest first. */
+export function codexWebSearches(transcript, session, base) {
+    return transcript.split('\n').flatMap((raw, index) => {
+        if (!raw.includes(WEB_SEARCH_KIND) && !raw.includes(WEB_SEARCH_CALL)) {
+            return [];
+        }
+        try {
+            const line = JSON.parse(raw);
+            const record = isObject(line) ? searchFrom(line, index + 1, session, base) : undefined;
+            return record === undefined ? [] : [record];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+/** The searches not yet in `sessionFile`, by their `toolUseId`. */
+export function newCodexSearches(searches, sessionFile) {
+    if (0 === searches.length) {
+        return [];
+    }
+    const kept = new Set();
+    let text = '';
+    try {
+        text = readFileSync(sessionFile, 'utf8');
+    }
+    catch {
+        // No session file yet: nothing is kept.
+    }
+    for (const raw of text.split('\n')) {
+        if (!raw.includes(CODEX_TRANSCRIPT_SOURCE)) {
+            continue;
+        }
+        try {
+            const line = JSON.parse(raw);
+            if (isObject(line)) {
+                kept.add(line['toolUseId']);
+            }
+        }
+        catch {
+            // A torn line names nothing.
+        }
+    }
+    return searches.filter((s) => !kept.has(s['toolUseId']));
+}
+/** The transcript's text, or undefined when it is missing or too large to read now. */
+export function readTranscript(path) {
+    let fd;
+    try {
+        fd = openSync(path, 'r');
+    }
+    catch {
+        return undefined;
+    }
+    // One open file for the size and the read, so the file cannot change between the two.
+    try {
+        return fstatSync(fd).size > MAX_TRANSCRIPT_BYTES ? undefined : readFileSync(fd, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        closeSync(fd);
+    }
+}

package/dist/command/cli/hook/episode-structure.d.ts

@@ -0,0 +1,24 @@
+export interface StructureNode {
+    depth: number;
+    role: string;
+    ref?: string;
+    /** Had an accessible name. The name itself is never kept. */
+    named?: boolean;
+    /** Had a form value. */
+    valued?: boolean;
+    /** Had its own text. */
+    texted?: boolean;
+    /** A grid container's track signature (CSS, not page text). */
+    layout?: string;
+    states?: string[];
+}
+/** One snapshot tree as text-free nodes. Lines that are not snapshot lines are dropped. */
+export declare function structureOfTree(tree: string): StructureNode[];
+/**
+ * Every snapshot step in a project's episodes, as structure lines handed to `write`. A result the
+ * episode cut short holds no whole tree and is counted, never guessed at.
+ */
+export declare function exportStructure(reticleRoot: string, write: (line: string) => void): {
+    steps: number;
+    skippedCut: number;
+};

package/dist/command/cli/hook/episode-structure.js

@@ -0,0 +1,138 @@
+/**
+ * The page's structure at each step, without its text: what a dataset can carry.
+ *
+ * The episode log keeps each `reticle_snapshot` result whole, on the machine. An export needs the
+ * shape of the page (roles, nesting, refs, layout, form state) and none of its words: accessible
+ * names, values and text are the customer's data. `structureOfTree` reads the snapshot's line format
+ * from the END of each line, and copies only what it can check against a fixed vocabulary or a
+ * fixed pattern (a role token, `e<n>`, a grid layout, a known state). Everything else becomes a
+ * boolean, so a word can never pass through, however a line is shaped.
+ *
+ * `reticle hook export --structure` writes one JSON line per snapshot step to stdout.
+ */
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { ElementState, ReticleDir } from '@reticlehq/core';
+const LINE = /^((?: {2})*)- ([a-z][a-z-]*)(.*)$/;
+const INDENT = 2;
+const STATES = new Set([
+    ElementState.DISABLED,
+    ElementState.CHECKED,
+    ElementState.EXPANDED,
+    ElementState.PRESSED,
+    ElementState.FOCUSED,
+]);
+const STATE_SUFFIX = / \[([a-zA-Z,]+)\]$/;
+const LAYOUT_SUFFIX = / \[(grid(?:-cols:[^\]"]*)?)\]$/;
+const REF_SUFFIX = / \(ref=(e\d+)\)$/;
+const TEXT_FIELD = ' [text="';
+const VALUE_FIELD = ' [value="';
+const FIELD_END = '"]';
+/** The snapshot role for a generic container's bare text line. */
+const TEXT_ROLE = 'text';
+const SNAPSHOT_TOOL = 'reticle_snapshot';
+/** One snapshot tree as text-free nodes. Lines that are not snapshot lines are dropped. */
+export function structureOfTree(tree) {
+    const nodes = [];
+    for (const line of tree.split('\n')) {
+        const match = LINE.exec(line);
+        if (null === match) {
+            continue;
+        }
+        const [, indent = '', role = '', tail = ''] = match;
+        const node = { depth: indent.length / INDENT, role };
+        let rest = tail;
+        const states = STATE_SUFFIX.exec(rest);
+        const named = states?.[1]?.split(',') ?? [];
+        if (states !== null && 0 < named.length && named.every((s) => STATES.has(s))) {
+            node.states = named;
+            rest = rest.slice(0, states.index);
+        }
+        const layout = LAYOUT_SUFFIX.exec(rest);
+        if (layout !== null) {
+            node.layout = layout[1] ?? '';
+            rest = rest.slice(0, layout.index);
+        }
+        for (const [field, flag] of [
+            [TEXT_FIELD, 'texted'],
+            [VALUE_FIELD, 'valued'],
+        ]) {
+            const at = rest.lastIndexOf(field);
+            if (-1 !== at && rest.endsWith(FIELD_END)) {
+                node[flag] = true;
+                rest = rest.slice(0, at);
+            }
+        }
+        const ref = REF_SUFFIX.exec(rest);
+        if (ref !== null) {
+            node.ref = ref[1] ?? '';
+            rest = rest.slice(0, ref.index);
+        }
+        if (rest.startsWith(' "')) {
+            if (TEXT_ROLE === role) {
+                node.texted = true;
+            }
+            else {
+                node.named = true;
+            }
+        }
+        nodes.push(node);
+    }
+    return nodes;
+}
+const isObject = (value) => 'object' === typeof value && null !== value && !Array.isArray(value);
+/**
+ * Every snapshot step in a project's episodes, as structure lines handed to `write`. A result the
+ * episode cut short holds no whole tree and is counted, never guessed at.
+ */
+export function exportStructure(reticleRoot, write) {
+    const dir = join(reticleRoot, ReticleDir.EPISODES_SUBDIR);
+    let files;
+    try {
+        files = readdirSync(dir).filter((file) => file.endsWith('.jsonl'));
+    }
+    catch {
+        return { steps: 0, skippedCut: 0 };
+    }
+    let steps = 0;
+    let skippedCut = 0;
+    for (const file of files) {
+        let episodeId;
+        for (const line of readFileSync(join(dir, file), 'utf8').split('\n')) {
+            let record;
+            try {
+                record = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (!isObject(record)) {
+                continue;
+            }
+            if (record['episodeId'] !== undefined) {
+                episodeId = record['episodeId'];
+            }
+            if (SNAPSHOT_TOOL !== record['tool']) {
+                continue;
+            }
+            const result = record['result'];
+            const tree = isObject(result) ? result['tree'] : undefined;
+            if ('string' !== typeof tree) {
+                if (Array.isArray(record['truncated'])) {
+                    skippedCut += 1;
+                }
+                continue;
+            }
+            steps += 1;
+            write(JSON.stringify({
+                episodeId,
+                n: record['n'],
+                tool: record['tool'],
+                sessionId: record['sessionId'],
+                startedAt: record['startedAt'],
+                structure: structureOfTree(tree),
+            }));
+        }
+    }
+    return { steps, skippedCut };
+}

package/dist/command/cli/hook/hook-command.d.ts

@@ -0,0 +1,9 @@
+/** The project folder `cwd` belongs to: the nearest `.reticle.json` above it, else `cwd`. */
+export declare function projectDirOf(cwd: string): string;
+export declare function claudeCliHere(): boolean;
+/**
+ * One row per agent: does it capture prompts here, through its hook or the MCP instructions, or is
+ * capture off. `reticle doctor` prints the same rows.
+ */
+export declare function promptCaptureRows(projectDir: string, env: NodeJS.ProcessEnv, claudeCli: boolean, home?: string): string[];
+export declare function handleHook(argv: readonly string[], print?: (line: string) => void): Promise<number>;