@termfleet/core 0.1.3 → 0.2.0

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
 
@@ -102,10 +102,18 @@ const off = client.onSnapshot((snapshot) => { /* … */ });
 
 // create a fresh agent window (boot a claude/codex/gemini session)
 await client.createAgentWindow({ /* AgentWindowCreateOptions */ });
+
+// terminals + files: capture/send, and read/write through the provider filesystem
+const { content } = await client.captureTerminal("term-1", 40);
+await client.sendTerminalInput("term-1", "echo hi\n", { breakGlass: true });
+const bytes = await client.readFile("term-1", "/path/file");  // Uint8Array (browser-safe)
+const text = new TextDecoder().decode(bytes);                 // node: or Buffer.from(bytes)
 ```
 
 Pass `{ authToken }` for an authenticated/shared provider, or a `urlResolver`
-when proxying through a console; omit both for a direct connection.
+when proxying through a console; omit both for a direct connection. `readFile`
+returns a `Uint8Array` (not a node `Buffer`, since this client also runs in the
+browser) — decode with `new TextDecoder().decode(bytes)` or `Buffer.from(bytes)`.
 
 ## What's inside
 

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/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/dist/provider-client.d.ts

@@ -120,15 +120,15 @@ export declare class ProviderClient {
     }): Promise<CommandAck<T>>;
     listDirectory(terminalId: string, path: string): Promise<ProviderDirectoryList>;
     listDirectoryByFilesystem(filesystemId: string, path: string): Promise<ProviderDirectoryList>;
-    readFile(terminalId: string, path: string): Promise<Buffer>;
-    readFileByFilesystem(filesystemId: string, path: string): Promise<Buffer>;
+    readFile(terminalId: string, path: string): Promise<Uint8Array>;
+    readFileByFilesystem(filesystemId: string, path: string): Promise<Uint8Array>;
     statFile(terminalId: string, path: string): Promise<ProviderFileStat>;
     statFileByFilesystem(filesystemId: string, path: string): Promise<ProviderFileStat>;
-    writeFile(terminalId: string, path: string, data: Buffer, options?: {
+    writeFile(terminalId: string, path: string, data: Uint8Array, options?: {
         mkdirs?: boolean;
         mode?: string;
     }): Promise<ProviderFileWriteResult>;
-    writeFileByFilesystem(filesystemId: string, path: string, data: Buffer, options?: {
+    writeFileByFilesystem(filesystemId: string, path: string, data: Uint8Array, options?: {
         mkdirs?: boolean;
         mode?: string;
     }): Promise<ProviderFileWriteResult>;

package/dist/provider-client.js

@@ -385,6 +385,9 @@ export class ProviderClient {
         }
         return await response.json();
     }
+    // Returns raw bytes as a Uint8Array (browser-safe — this client also runs in the
+    // browser, where node's Buffer is absent). Node consumers decode with
+    // `Buffer.from(bytes)` or `new TextDecoder().decode(bytes)`.
     async readFile(terminalId, path) {
         const url = new URL(`${this.apiBase}/api/files`);
         url.searchParams.set("terminalId", terminalId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@termfleet/core",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "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",
@@ -37,7 +37,10 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "prepare": "tsc -p tsconfig.json"
+    "prepack": "tsc -p tsconfig.json"
+  },
+  "engines": {
+    "node": ">=20"
   },
   "dependencies": {
     "socket.io-client": "^4.8.3",