@termfleet/core 0.1.4 → 0.2.1

package/README.md

@@ -22,7 +22,7 @@ this package does that standalone.
 npm install @termfleet/core
 ```
 
-Requires **Node 18+** and ESM (`"type": "module"`, or `import()`).
+Requires **Node 20+** and ESM (`"type": "module"`, or `import()`).
 
 ## Imports are explicit, per module
 

package/dist/agent-session-tail.js

@@ -1,6 +1,6 @@
 import { open, readFile, stat } from "node:fs/promises";
 import { setImmediate as yieldToEventLoop } from "node:timers/promises";
-import { codexTranscriptPath, createClaudeSessionParser, emptyClaudeSession, listLocalAgentSubagents, parseCodexSessionJsonl, parseSubagentSessionId, resolveClaudeSubagentTranscriptPath, resolveClaudeTranscriptPath } from "./agent-session.js";
+import { codexTranscriptPath, createClaudeSessionParser, emptyClaudeSession, listLocalAgentSubagents, parseCodexSessionJsonl, parseGeminiSessionJsonl, parseSubagentSessionId, resolveClaudeSubagentTranscriptPath, resolveClaudeTranscriptPath, resolveGeminiTranscriptPath } from "./agent-session.js";
 // How many transcript lines are parsed between yields back to the event
 // loop. Keeps a multi-megabyte initial catch-up from starving sockets.
 const linesPerSlice = 1_000;
@@ -145,8 +145,34 @@ function cachedTail(options) {
     }
     return tail;
 }
+const maxCachedFullParses = 64;
+const fullParseCache = new Map();
+async function readStatCachedFullParse(options) {
+    const fileStat = await stat(options.transcriptPath);
+    const signature = `${options.kind}:${fileStat.size}:${fileStat.mtimeMs}`;
+    const key = `${options.sessionId}\0${options.transcriptPath}`;
+    const cached = fullParseCache.get(key);
+    if (cached && cached.signature === signature) {
+        // Unchanged file: no re-read, no re-parse. Refresh LRU order.
+        fullParseCache.delete(key);
+        fullParseCache.set(key, cached);
+        return { details: cached.details, signature };
+    }
+    const jsonl = await readFile(options.transcriptPath, "utf8");
+    const entry = { details: options.parse(jsonl), signature };
+    fullParseCache.delete(key);
+    fullParseCache.set(key, entry);
+    if (fullParseCache.size > maxCachedFullParses) {
+        const oldest = fullParseCache.keys().next().value;
+        if (oldest !== undefined) {
+            fullParseCache.delete(oldest);
+        }
+    }
+    return { details: entry.details, signature };
+}
 export function clearAgentSessionTailCache() {
     tailCache.clear();
+    fullParseCache.clear();
 }
 export async function readLocalAgentSessionTailed(options) {
     if (options.sessionId.startsWith("codex:")) {
@@ -154,8 +180,37 @@ export async function readLocalAgentSessionTailed(options) {
         if (!transcriptPath) {
             throw new Error(`Codex session transcript was not found for ${options.sessionId} in ${options.cwd}`);
         }
-        const jsonl = await readFile(transcriptPath, "utf8");
-        return { details: parseCodexSessionJsonl({ jsonl, sessionId: options.sessionId, transcriptPath }) };
+        return readStatCachedFullParse({
+            kind: "codex",
+            parse: (jsonl) => parseCodexSessionJsonl({ jsonl, sessionId: options.sessionId, transcriptPath }),
+            sessionId: options.sessionId,
+            transcriptPath
+        });
+    }
+    if (options.sessionId.startsWith("gemini:")) {
+        const transcriptPath = resolveGeminiTranscriptPath(options);
+        if (!transcriptPath) {
+            // A just-launched Gemini chat with no transcript yet is live but empty —
+            // not a failure (mirrors readLocalGeminiSession's empty shape). The next
+            // tailed read resolves and parses once it writes messages.
+            return {
+                details: {
+                    agentSessionId: options.sessionId,
+                    endOfTurn: false,
+                    lastAssistantText: "",
+                    messages: [],
+                    provider: "gemini",
+                    sessionId: options.sessionId,
+                    timeline: []
+                }
+            };
+        }
+        return readStatCachedFullParse({
+            kind: "gemini",
+            parse: (jsonl) => parseGeminiSessionJsonl({ jsonl, sessionId: options.sessionId, transcriptPath }),
+            sessionId: options.sessionId,
+            transcriptPath
+        });
     }
     // A subagent sidechain, addressed by its composite id: tail its file directly
     // (no nested subagents to list).

package/dist/agent-session.d.ts

@@ -302,6 +302,21 @@ export declare function resolveClaudeTranscriptPath(options: {
     home?: string;
     sessionId: string;
 }): string | undefined;
+export declare function findLocalClaudeSession(sessionId: string, options?: {
+    home?: string;
+}): {
+    sessionId: string;
+    cwd: string | undefined;
+    transcriptPath: string;
+} | undefined;
+export declare function findLocalAgentSession(agentSessionId: string, options?: {
+    home?: string;
+}): {
+    agent: "claude" | "codex" | "gemini";
+    sessionId: string;
+    cwd: string | undefined;
+    transcriptPath: string;
+} | undefined;
 export declare function emptyClaudeSession(options: {
     cwd: string;
     home?: string;

package/dist/agent-session.js

@@ -74,6 +74,59 @@ export function resolveClaudeTranscriptPath(options) {
     const found = findClaudeTranscriptById(join(options.home ?? agentHome(), ".claude", "projects"), assertSafeAgentSessionId(normalizeClaudeSessionId(options.sessionId)));
     return existsSync(found) ? found : undefined;
 }
+// Read the working dir a Claude session ran in, straight from its transcript. The `cwd` is on the message
+// records, not always the first header line, so scan a bounded prefix (headers are small). undefined if absent.
+function readClaudeSessionCwd(transcriptPath, maxBytes = 65_536) {
+    let head;
+    try {
+        const fd = openSync(transcriptPath, "r");
+        try {
+            const buffer = Buffer.alloc(maxBytes);
+            const bytesRead = readSync(fd, buffer, 0, maxBytes, 0);
+            head = buffer.toString("utf8", 0, bytesRead);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch {
+        return undefined;
+    }
+    for (const line of head.split("\n")) {
+        if (!line)
+            continue;
+        try {
+            const row = JSON.parse(line);
+            if (typeof row.cwd === "string" && row.cwd)
+                return row.cwd;
+        }
+        catch { /* a truncated final line in the bounded read — ignore */ }
+    }
+    return undefined;
+}
+// Resolve a Claude session from its id ALONE (no cwd needed): find its transcript across every project dir and
+// read the session's cwd from it. Local + provider-free — the primitive any tool needs when it has a session
+// id but not its working dir (a session mirror, a resumer, a cross-project browser). undefined when the
+// transcript doesn't exist yet (a just-launched session writes it only once it produces messages).
+export function findLocalClaudeSession(sessionId, options = {}) {
+    const bareId = assertSafeAgentSessionId(normalizeClaudeSessionId(sessionId));
+    const transcriptPath = findClaudeTranscriptById(join(options.home ?? agentHome(), ".claude", "projects"), bareId);
+    if (!existsSync(transcriptPath))
+        return undefined;
+    return { sessionId: bareId, cwd: readClaudeSessionCwd(transcriptPath), transcriptPath };
+}
+// The agent-generic form: resolve a (prefixed or bare) agentSessionId → its provider, cwd, and transcript
+// path, locally. A bare id is treated as Claude. (Codex/Gemini keep transcripts elsewhere; extend here when
+// needed — non-Claude returns undefined for now.)
+export function findLocalAgentSession(agentSessionId, options = {}) {
+    const separator = agentSessionId.indexOf(":");
+    const prefix = separator > 0 ? agentSessionId.slice(0, separator) : "";
+    const agent = prefix === "codex" ? "codex" : prefix === "gemini" ? "gemini" : "claude";
+    if (agent !== "claude")
+        return undefined;
+    const resolved = findLocalClaudeSession(agentSessionId, options);
+    return resolved ? { agent, ...resolved } : undefined;
+}
 // A real, openable chat for a session that has no transcript yet — just an empty
 // conversation. Parsing empty JSONL yields a well-formed session with zero
 // messages, so a just-launched agent displays as an empty chat instead of 500ing.

package/dist/lib/exec.js

@@ -105,10 +105,27 @@ async function spawnAsync(command, args, options, input) {
         });
         const stdout = [];
         const stderr = [];
+        // Honor timeoutMs without blocking the loop (the sync `run` relied on
+        // spawnSync's timeout): SIGKILL the child and reject if it overruns.
+        const timer = options.timeoutMs === undefined
+            ? undefined
+            : setTimeout(() => {
+                child.kill("SIGKILL");
+                reject(new Error(`${command} ${args.join(" ")} timed out after ${options.timeoutMs}ms.`));
+            }, options.timeoutMs);
+        timer?.unref?.();
+        const clear = () => {
+            if (timer)
+                clearTimeout(timer);
+        };
         child.stdout?.on("data", (chunk) => stdout.push(chunk));
         child.stderr?.on("data", (chunk) => stderr.push(chunk));
-        child.on("error", reject);
+        child.on("error", (error) => {
+            clear();
+            reject(error);
+        });
         child.on("close", (code) => {
+            clear();
             if (code !== 0) {
                 const detail = Buffer.concat(stderr).toString("utf8").trim();
                 reject(new Error(`${command} ${args.join(" ")} failed with exit ${code}.${detail ? `\n${detail}` : ""}`));

package/dist/local-tunnel.js

@@ -100,7 +100,7 @@ function startLocalTunnel(src, options) {
         "--host", tunnelServerUrl,
         // The tunnel layer stays in passthrough (no tunnel-level auth); the console's
         // own remote-access gate is what requires a session for non-loopback requests.
-        // volter-tunnel's flag is --auth-not-required (there is no --no-auth).
+        // The reference tunnel client exposes this as --auth-not-required.
         "--auth-not-required"
     ];
     if (options.tunnelId) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@termfleet/core",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "description": "Termfleet core: contracts, the provider SDK, and the agent-transcript/session library (Claude Code / Codex / Gemini). The reusable layer, usable beyond the console.",
   "keywords": [
     "claude-code",
@@ -39,6 +39,9 @@
     "build": "tsc -p tsconfig.json",
     "prepack": "tsc -p tsconfig.json"
   },
+  "engines": {
+    "node": ">=20"
+  },
   "dependencies": {
     "socket.io-client": "^4.8.3",
     "yjs": "^13.6.31"