@reticlehq/server 3.7.0 → 3.8.1

package/dist/command/cli/hook/tool-hook.js

@@ -0,0 +1,259 @@
+/**
+ * `reticle hook tool --agent <id>`: keep one of the coding agent's own tool calls.
+ *
+ * The agent's shell commands, file edits and web fetches never pass through Reticle's MCP tools,
+ * so the daemon's episode log never saw them. The agent's post-tool hook hands each one over here.
+ * It goes into the same `.reticle/episodes/` folder, one file per agent session
+ * (`agent-<session>.jsonl`): the tool, its arguments, a head of its result and the result's size,
+ * whether it failed, its exit code, and its timing. Every string passes the secret redaction first.
+ *
+ * LOCAL ONLY, under the same rules as the episode log: gitignored, swept by retention, never sent
+ * as a file (a synced run takes only the model and the closing message from it). Off with the
+ * one agent-capture switch (`RETICLE_PROMPT_CAPTURE=0`, `"promptCapture": false`), and off with the
+ * journal (`RETICLE_JOURNAL=0`, `"journal": false`). Reticle's own MCP tools are skipped, because
+ * the daemon already keeps them in full. Never throws.
+ */
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { ReticleDir, ReticleEnv } from '@reticlehq/core';
+import { projectSetting, redactSecrets } from '../../../memory/intent/record-request.js';
+import { AGENT_FILE_PREFIX, AgentRecordKind, EPISODE_FILE_VERSION, } from '../../../memory/journal/episode-log.js';
+import { agentCaptureOff, agentCaptureOffIn, captureRoots } from './prompt-hook.js';
+import { CODEX_AGENT, codexHome, codexTranscriptPath, codexWebSearches, newCodexSearches, readTranscript, } from './codex-transcript.js';
+/** The `kind` of a record this hook writes, beside the daemon's `start` and `call`. */
+export const AGENT_TOOL_RECORD = AgentRecordKind.TOOL;
+/** The `kind` of a record that only names the agent's model (Claude Code's session start). */
+export const AGENT_MODEL_RECORD = AgentRecordKind.MODEL;
+/** The `kind` of the agent's closing message at the end of a turn. */
+export const AGENT_STOP_RECORD = AgentRecordKind.STOP;
+/**
+ * The end-of-turn events whose payload carries the final message, and the field that holds it,
+ * from each vendor's hook reference (2026-10-18). Copilot CLI's `agentStop` and Factory Droid's
+ * `Stop` carry no message text, so they are not here.
+ */
+const STOP_MESSAGE_FIELD = {
+    // Claude Code and Codex.
+    Stop: 'last_assistant_message',
+    // Cursor.
+    afterAgentResponse: 'text',
+    // Gemini CLI.
+    AfterAgent: 'prompt_response',
+};
+/** Windsurf names its event in `agent_action_name`, and puts the text in `response`. */
+const WINDSURF_STOP = 'post_cascade_response';
+/** A result keeps this many characters; its full size is kept beside it. */
+export const MAX_TOOL_TEXT = 4_000;
+/** One argument string (a whole file a Write sends) keeps this many characters. */
+const MAX_ARG_TEXT = 100_000;
+/** Reticle's own tools, by the MCP name prefix every agent gives them. */
+const RETICLE_TOOL = /^mcp__reticle/i;
+const EXIT_CODE = /^Exit code (\d+)/;
+const OFF_VALUES = new Set(['0', 'false', 'off', 'no']);
+const JOURNAL_SETTING = 'journal';
+const UNKNOWN_SESSION = 'unknown';
+const BASH = 'Bash';
+/**
+ * Codex documents no error field on PostToolUse (2026-10-19): a failed shell command arrives like a
+ * passing one, so the absence of an error says nothing about its exit code.
+ */
+const NO_FAILURE_SIGNAL = new Set(['codex']);
+const COPILOT_SUCCESS = 'success';
+const UNKNOWN_MODEL = 'Unknown';
+const isObject = (value) => 'object' === typeof value && null !== value && !Array.isArray(value);
+const text = (value) => 'string' === typeof value && 0 < value.length ? value : undefined;
+/**
+ * Every string redacted and capped, at any depth. Says whether any string was cut. Paths inside the
+ * project are made relative to it first: the redaction removes an absolute path whole, because a
+ * home folder names a person, and the file an edit touched is the point of the record.
+ */
+function redacted(value, cut, base) {
+    if ('string' === typeof value) {
+        if (value.length > MAX_ARG_TEXT) {
+            cut.any = true;
+        }
+        return redactSecrets(value.split(`${base}/`).join(''), MAX_ARG_TEXT);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => redacted(item, cut, base));
+    }
+    if (!isObject(value)) {
+        return value;
+    }
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, redacted(v, cut, base)]));
+}
+/** A result as kept: its redacted head, its full size, and whether the head is all of it. */
+function resultOf(value, base) {
+    const full = 'string' === typeof value ? value : JSON.stringify(value ?? null);
+    return {
+        head: redactSecrets(full.split(`${base}/`).join(''), MAX_TOOL_TEXT),
+        chars: full.length,
+        truncated: full.length > MAX_TOOL_TEXT,
+    };
+}
+/**
+ * The fields each agent names differently, read into one shape. From each vendor's hook reference
+ * on 2026-10-18: Claude Code (`tool_response`, `error`, `duration_ms`, `session_id`), Cursor
+ * (`tool_output`, `error_message`, `failure_type`, `duration` with no stated unit,
+ * `conversation_id`, `model` on every hook), Codex (`tool_response`, `model` on every hook) and
+ * Gemini CLI (`tool_response` with an optional `error` inside it; no model).
+ */
+function readPayload(payload) {
+    // Copilot CLI's camelCase result: `{ resultType, textResultForLlm }`, a failure unless `success`.
+    const copilot = isObject(payload['toolResult']) ? payload['toolResult'] : undefined;
+    const response = payload['tool_response'] ?? payload['tool_output'] ?? copilot;
+    const inner = isObject(response) ? response['error'] : undefined;
+    const innerError = text(inner) ?? (isObject(inner) ? text(inner['message']) : undefined);
+    const copilotError = copilot !== undefined && COPILOT_SUCCESS !== copilot['resultType']
+        ? (text(copilot['textResultForLlm']) ?? String(copilot['resultType']))
+        : undefined;
+    // Windsurf names the action, not a tool, and says "Unknown" when it does not know the model.
+    const windsurfModel = text(payload['model_name']);
+    const windsurfTool = isObject(payload['tool_info'])
+        ? text(payload['agent_action_name'])
+        : undefined;
+    return {
+        session: text(payload['session_id']) ??
+            text(payload['conversation_id']) ??
+            text(payload['sessionId']) ??
+            text(payload['trajectory_id']),
+        // `to_model` is Claude Code's PostModelSwitch; `model` is everyone else's.
+        model: text(payload['model']) ??
+            text(payload['to_model']) ??
+            (UNKNOWN_MODEL === windsurfModel ? undefined : windsurfModel),
+        tool: text(payload['tool_name']) ?? text(payload['toolName']) ?? windsurfTool,
+        input: payload['tool_input'] ?? payload['toolArgs'] ?? payload['tool_info'] ?? {},
+        response,
+        error: text(payload['error']) ?? text(payload['error_message']) ?? innerError ?? copilotError,
+    };
+}
+/** One record from a post-tool payload, or from a payload that only names the model. */
+export function toolRecordFrom(agent, payload, now, base) {
+    if (!isObject(payload)) {
+        return undefined;
+    }
+    const { session, model, tool, input, response, error } = readPayload(payload);
+    const who = {
+        v: EPISODE_FILE_VERSION,
+        agent,
+        ...(session === undefined ? {} : { agentSession: session }),
+        ...(model === undefined ? {} : { model }),
+    };
+    const event = text(payload['hook_event_name']);
+    const field = event === undefined ? undefined : STOP_MESSAGE_FIELD[event];
+    const info = isObject(payload['tool_info']) ? payload['tool_info'] : {};
+    const windsurfStop = WINDSURF_STOP === payload['agent_action_name'];
+    if (field !== undefined || windsurfStop) {
+        const message = windsurfStop
+            ? (text(payload['response']) ?? text(info['response']))
+            : text(field === undefined ? undefined : payload[field]);
+        // A stop with no message (Codex sends null when it has none) is still the end of the turn.
+        return {
+            ...who,
+            kind: AGENT_STOP_RECORD,
+            ...(message === undefined ? {} : { message: resultOf(message, base) }),
+            at: now,
+        };
+    }
+    if (tool === undefined) {
+        // Claude Code names its model only at session start and on a switch, with no tool.
+        return model === undefined ? undefined : { ...who, kind: AGENT_MODEL_RECORD, at: now };
+    }
+    if (RETICLE_TOOL.test(tool)) {
+        return undefined;
+    }
+    const ok = error === undefined;
+    const duration = payload['duration_ms'];
+    const durationMs = 'number' === typeof duration && duration >= 0 ? duration : undefined;
+    const reported = payload['duration'];
+    const exit = error === undefined ? undefined : EXIT_CODE.exec(error)?.[1];
+    const cut = { any: false };
+    const args = redacted(input, cut, base);
+    // A payload that carries no result (Windsurf's) gets none: an invented `null` reads as an answer.
+    let outcome = {};
+    if (!ok) {
+        outcome = { error: resultOf(error, base) };
+    }
+    else if (response !== undefined) {
+        outcome = { result: resultOf(response, base) };
+    }
+    let exitCode = {};
+    if (exit !== undefined) {
+        exitCode = { exitCode: Number(exit) };
+    }
+    else if (ok && BASH === tool && !NO_FAILURE_SIGNAL.has(agent)) {
+        exitCode = { exitCode: 0 };
+    }
+    return {
+        ...who,
+        kind: AGENT_TOOL_RECORD,
+        ...(text(payload['tool_use_id']) === undefined ? {} : { toolUseId: payload['tool_use_id'] }),
+        tool,
+        args,
+        ...(cut.any ? { argsTruncated: true } : {}),
+        ok,
+        ...outcome,
+        ...(text(payload['failure_type']) === undefined
+            ? {}
+            : { failureType: payload['failure_type'] }),
+        ...exitCode,
+        ...(true === payload['is_interrupt'] ? { interrupted: true } : {}),
+        ...(durationMs === undefined ? {} : { startedAt: now - durationMs, durationMs }),
+        // A duration whose unit the vendor does not state is kept as given, never converted.
+        ...('number' === typeof reported ? { reportedDuration: reported } : {}),
+        endedAt: now,
+    };
+}
+export { toolHookAck } from './hook-fast.js';
+/** Keep one tool call. Never throws: the `.reticle` roots it wrote to, or none. */
+export function captureToolCall(agent, raw, io) {
+    try {
+        if (agentCaptureOff(io.env) ||
+            OFF_VALUES.has((io.env[ReticleEnv.JOURNAL] ?? '').toLowerCase())) {
+            return { written: [] };
+        }
+        const payload = JSON.parse(raw);
+        if (!isObject(payload)) {
+            return { written: [] };
+        }
+        const roots = Array.isArray(payload['workspace_roots']) ? payload['workspace_roots'] : [];
+        // Windsurf puts the folder inside `tool_info` for a command, and nowhere for an edit: its hook
+        // runs in the workspace root, which is `io.cwd`.
+        const info = isObject(payload['tool_info']) ? payload['tool_info'] : {};
+        const cwd = text(payload['cwd']) ?? text(roots[0]) ?? text(info['cwd']) ?? io.cwd;
+        const record = toolRecordFrom(agent, payload, io.now(), cwd);
+        const given = readPayload(payload).session;
+        // Codex's web search reaches no hook: any Codex hook imports it from Codex's own transcript.
+        const transcript = CODEX_AGENT === agent && given !== undefined
+            ? codexTranscriptPath(payload, codexHome(io.env))
+            : undefined;
+        const body = transcript === undefined ? undefined : readTranscript(transcript);
+        const searches = given === undefined || body === undefined ? [] : codexWebSearches(body, given, cwd);
+        if (record === undefined && 0 === searches.length) {
+            return { written: [] };
+        }
+        const session = (given ?? UNKNOWN_SESSION).replace(/[^\w-]/g, '_');
+        const written = [];
+        for (const root of captureRoots(cwd)) {
+            const projectDir = dirname(root);
+            if (agentCaptureOffIn(projectDir) || false === projectSetting(projectDir, JOURNAL_SETTING)) {
+                continue;
+            }
+            const dir = join(root, ReticleDir.EPISODES_SUBDIR);
+            mkdirSync(dir, { recursive: true });
+            const file = join(dir, `${AGENT_FILE_PREFIX}${session}.jsonl`);
+            const lines = [
+                ...newCodexSearches(searches, file),
+                ...(record === undefined ? [] : [record]),
+            ];
+            if (0 === lines.length) {
+                continue;
+            }
+            appendFileSync(file, lines.map((line) => `${JSON.stringify(line)}\n`).join(''));
+            written.push(root);
+        }
+        return { written };
+    }
+    catch {
+        return { written: [] };
+    }
+}

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

@@ -29,6 +29,7 @@ type OpenDecision = {
     action: 'left-as-is';
     url: string;
     requested: string;
+    sessionId?: string;
 } | {
     action: 'open';
     url: string;
@@ -53,6 +54,7 @@ type OpenDecision = {
  */
 export declare function decideOpen(all: {
     url: string;
+    sessionId?: string;
     unresponsive?: boolean;
     hidden?: boolean;
     lastSeenMs?: number;

package/dist/command/cli/launch/cli-launch.js

@@ -21,6 +21,20 @@ function statusField(payload, key) {
     const value = payload[key];
     return 'string' === typeof value && value.length > 0 ? value : undefined;
 }
+/**
+ * SDK version of each connected page, from `/status`.
+ *
+ * A missing field is an older daemon: treat it as no pages, which keeps the restart advice.
+ * A non-string entry is a page that did not report a version, and that page does not match.
+ */
+function pageSdkVersionsOf(payload) {
+    if (typeof payload !== 'object' || null === payload)
+        return [];
+    const raw = payload['pageSdkVersions'];
+    if (!Array.isArray(raw))
+        return [];
+    return raw.map((value) => ('string' === typeof value && 0 < value.length ? value : undefined));
+}
 /**
  * Warn when the daemon already on this port is a different version than this CLI, and attach anyway.
  *
@@ -46,7 +60,7 @@ export function daemonSkew(status) {
         version: daemonVersion,
         contract: statusField(status, 'contract'),
         // The daemon is the peer here and this process is the agent side.
-        fix: daemonFix(daemonVersion, SERVER_VERSION),
+        fix: daemonFix(daemonVersion, SERVER_VERSION, pageSdkVersionsOf(status)),
     }, { version: SERVER_VERSION, contract: CONTRACT_FINGERPRINT });
 }
 function sameOrigin(a, b) {
@@ -114,7 +128,13 @@ export function decideOpen(all, url) {
         return { action: 'reuse', url: exact.url };
     const onOrigin = sessions.find((s) => sameOrigin(s.url, url));
     return onOrigin !== undefined
-        ? { action: 'left-as-is', url: onOrigin.url, requested: url }
+        ? {
+            action: 'left-as-is',
+            url: onOrigin.url,
+            requested: url,
+            // Which tab, so `--navigate` can move THAT one rather than whichever the daemon picks.
+            ...(onOrigin.sessionId === undefined ? {} : { sessionId: onOrigin.sessionId }),
+        }
         : { action: 'open', url };
 }
 /**

package/dist/command/cli/lifecycle/daemon-lifecycle.js

@@ -24,7 +24,8 @@ import { readDaemonStartupCause } from '../../daemon/lifetime/startup-failure.js
 import { PortPresence, probePresence, describePresence, } from '../../daemon/binding/port-presence.js';
 import { daemonSpawnArgs } from '../daemon-start-options.js';
 import { fetchStatus } from '../../daemon/binding/daemon-status-probe.js';
-import { runKill } from '../cli-kill.js';
+import { requestShutdown, runKill } from '../cli-kill.js';
+import { RETICLE_DEFAULT_PORT } from '@reticlehq/core';
 export function handleServe(parsed) {
     void serveWithHonestExit(parsed);
 }
@@ -59,6 +60,21 @@ async function serveWithHonestExit(parsed) {
                 return;
             }
         }
+        if (undefined !== parsed.driveUrl) {
+            // `drive` deliberately does not accept --port: use its existing RETICLE_PORT input.
+            // Quote the URL so copying the suggestion preserves its query string.
+            const safeUrlArg = `'${parsed.driveUrl.replace(/'/g, String.raw `'\''`)}'`;
+            const driveCommand = `reticle drive ${safeUrlArg}`;
+            const runnableCommand = RETICLE_DEFAULT_PORT === parsed.port
+                ? driveCommand
+                : `RETICLE_PORT=${String(parsed.port)} ${driveCommand}`;
+            const reason = 'a Reticle daemon is already running. `serve --drive` cannot open a tab in it. ' +
+                `Use \`${runnableCommand}\` instead.`;
+            log('reticle_daemon_start_refused', { port: parsed.port, reason });
+            process.stderr.write(`${reason}\n`);
+            process.exit(1);
+            return;
+        }
         log('reticle_daemon_already_running', { port: parsed.port });
         return;
     }
@@ -134,7 +150,17 @@ export function handleStop(port, quiet) {
         });
         return;
     }
-    process.kill(pid, 'SIGTERM');
+    // Ask the daemon first, on every OS: on Windows a signal ends it at once, with no shutdown path
+    // and no stop event. The signal is the fallback for an older daemon or a refused request.
+    void requestShutdown(port).then((asked) => {
+        if (!asked) {
+            process.kill(pid, 'SIGTERM');
+        }
+        waitForStop(port, pid, quiet);
+    });
+}
+/** Poll until `pid` is gone: SIGKILL after the graceful window, give up after the forced one. */
+function waitForStop(port, pid, quiet) {
     const started = Date.now();
     let escalated = false;
     const poll = setInterval(() => {

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

@@ -13,6 +13,15 @@
  * person never asked for, on a port nothing records. Only the requested port gets the default.
  */
 export declare function spawnsHeadless(headless: boolean, requested: number, resolved: number): boolean;
+/**
+ * Should a proxy stop the older daemon it found, and start its own release?
+ *
+ * Only an OLDER daemon, read from `/status`, with no tab attached and no other agent attached. A
+ * tab or an agent can have a call in flight, so that daemon stays and the skew is described as
+ * before. A daemon before `MCP_PEERS_SINCE` does not report its agents, so it stays too. A status
+ * that does not parse, or a version that does not compare, keeps the daemon.
+ */
+export declare function retiresOlderDaemon(status: unknown, proxyVersion: string): boolean;
 /**
  * MCP proxy mode: ensures the daemon is running, then bridges Claude Code's
  * stdin/stdout to the daemon's SSE endpoint. This is the recommended way to