pennyrouter 0.3.0 → 0.3.1

package/src/statusline.js

@@ -11,6 +11,10 @@
 // authed with the pr- key already in Claude Code's settings). The gateway keys that
 // endpoint on the CC session uuid it sees in every request's metadata.user_id — the
 // same uuid Claude Code hands the statusline script on stdin.
+//
+// A wrapped user statusline command is cached the same way: it can be slow to spawn
+// (npx especially, and especially on Windows — see WRAP_REFRESH_MS below), so it's never
+// run inline on Claude Code's ~1s render loop.
 
 import { statePath, atomicWrite, readJsonFile, writeJsonFile } from "./state.js";
 
@@ -46,6 +50,7 @@ export async function configureClaudeCodeStatusline(current) {
   current.statusLine = {
     type: "command",
     command: `node "${statuslineScriptPath()}"`,
+    refreshInterval: 1,
     ...(existing?.padding !== undefined ? { padding: existing.padding } : {}),
   };
   return { script_path: statuslineScriptPath(), wrapped: Boolean(config.wrap_command) };
@@ -86,6 +91,14 @@ const stateDir = join(
   "pennyrouter",
 );
 const cacheDir = join(stateDir, "statusline-cache");
+// A wrapped user statusline command can be slow to spawn (npx especially: on Windows
+// it goes through an extra cmd.exe/npx.cmd hop and can take 2-4s per invocation, vs
+// well under 1s on macOS/Linux). Claude Code re-invokes this script every ~1s
+// (refreshInterval), so running the wrap command inline on every render blocked past
+// that interval on Windows, renders piled up, and the statusline never finished in
+// time to display at all. Cache its output and refresh it out-of-band instead, same
+// as the Penny gateway segment below.
+const WRAP_REFRESH_MS = 2000;
 
 function readJson(path) {
   try { return JSON.parse(readFileSync(path, "utf8")); } catch { return null; }
@@ -108,6 +121,8 @@ function claudeEnv() {
   return { base, key };
 }
 
+const config = readJson(join(stateDir, "claude-statusline.json")) || {};
+
 // --refresh <sessionId>: fetch gateway status into the cache file, then exit.
 if (process.argv[2] === "--refresh") {
   const sessionId = process.argv[3];
@@ -120,6 +135,9 @@ if (process.argv[2] === "--refresh") {
     });
     if (resp.ok) {
       const data = await resp.json();
+      if (data.cache_expires_at && typeof data.cache_expires_at === "number") {
+        data.cache_expires_at = Math.round(data.cache_expires_at / 10) * 10;
+      }
       mkdirSync(cacheDir, { recursive: true });
       writeFileSync(join(cacheDir, sessionId + ".json"), JSON.stringify(data));
     }
@@ -127,11 +145,28 @@ if (process.argv[2] === "--refresh") {
   process.exit(0);
 }
 
+// --refresh-wrap <sessionId>: run the (possibly slow) wrapped statusline command out of
+// band and cache its output. Reads the stdin JSON the main render last saw, persisted to
+// a per-session file since a detached child has no stdin of its own to read.
+if (process.argv[2] === "--refresh-wrap") {
+  const sessionId = process.argv[3];
+  if (!sessionId || !config.wrap_command) process.exit(0);
+  let wrapInput = "{}";
+  try { wrapInput = readFileSync(join(cacheDir, sessionId + ".wrap-input.json"), "utf8"); } catch { /* none yet */ }
+  const run = spawnSync(config.wrap_command, {
+    shell: true, input: wrapInput, encoding: "utf8", timeout: 20000, windowsHide: true,
+  });
+  let wrapLines = (run.stdout || "").replace(/\\n$/, "").split("\\n");
+  if (wrapLines.length === 1 && wrapLines[0] === "") wrapLines = [];
+  mkdirSync(cacheDir, { recursive: true });
+  writeFileSync(join(cacheDir, sessionId + ".wrap.json"), JSON.stringify({ lines: wrapLines, at: Date.now() }));
+  process.exit(0);
+}
+
 const raw = readFileSync(0, "utf8");
 let input = {};
 try { input = JSON.parse(raw); } catch { /* keep {} */ }
 const sessionId = input.session_id || "";
-const config = readJson(join(stateDir, "claude-statusline.json")) || {};
 const refreshMs = (config.refresh_seconds ?? 15) * 1000;
 
 const cachePath = join(cacheDir, sessionId + ".json");
@@ -144,7 +179,7 @@ const { base, key } = claudeEnv();
 const pennyInstalled = Boolean(base) && Boolean(key);
 if (sessionId && pennyInstalled && cacheAge > refreshMs) {
   spawn(process.execPath, [process.argv[1], "--refresh", sessionId], {
-    detached: true, stdio: "ignore",
+    detached: true, stdio: "ignore", windowsHide: true,
   }).unref();
 }
 
@@ -164,19 +199,52 @@ function askBadges(c) {
   return out;
 }
 
+// Cache warmth countdown: when a prompt cache prefix is live, show time remaining.
+// The gateway sends cache_expires_at (absolute Unix timestamp); we interpolate locally
+// so it ticks down smoothly every statusline render (every ~1s), only "jumping" when
+// the gateway refreshes (~15s) with a fresh timestamp. Show ❄️ cold when expired.
+function cacheWarmth(c) {
+  if (!c || typeof c.cache_expires_at !== "number" || c.cache_expires_at <= 0) {
+    return "";
+  }
+  const remaining = c.cache_expires_at - Date.now() / 1000;
+  if (remaining <= 0) return " · ❄️ cold";
+  const minutes = Math.floor(remaining / 60);
+  const seconds = Math.floor(remaining % 60);
+  return " · 🔥 warm " + minutes + ":" + String(seconds).padStart(2, "0");
+}
+
 let penny;
 if (!pennyInstalled) {
   penny = "🪙 penny off";
 } else if (cache && cache.known && cache.bypass) {
   penny = "🪙 penny off";
 } else {
-  penny = "🪙 penny" + authSuffix(cache && cache.auth_mode) + askBadges(cache);
+  penny = "🪙 penny" + authSuffix(cache && cache.auth_mode) + askBadges(cache) + cacheWarmth(cache);
 }
 
 let lines;
-if (config.wrap_command) {
+if (config.wrap_command && sessionId) {
+  const wrapCachePath = join(cacheDir, sessionId + ".wrap.json");
+  const wrapCache = readJson(wrapCachePath);
+  const wrapAge = wrapCache && typeof wrapCache.at === "number" ? Date.now() - wrapCache.at : Infinity;
+  if (wrapAge > WRAP_REFRESH_MS) {
+    mkdirSync(cacheDir, { recursive: true });
+    writeFileSync(join(cacheDir, sessionId + ".wrap-input.json"), raw);
+    // Bump the cache timestamp before spawning: Claude Code polls every ~1s, so
+    // without this every render in the next couple seconds would see a still-stale
+    // cache and fire its own overlapping refresh while the first one is still running.
+    writeFileSync(wrapCachePath, JSON.stringify({ lines: (wrapCache && wrapCache.lines) || [], at: Date.now() }));
+    spawn(process.execPath, [process.argv[1], "--refresh-wrap", sessionId], {
+      detached: true, stdio: "ignore", windowsHide: true,
+    }).unref();
+  }
+  lines = (wrapCache && wrapCache.lines) || [];
+} else if (config.wrap_command) {
+  // No session id (e.g. a manual/interactive invocation outside Claude Code): there's
+  // no cache key to keep state under, so run inline like before caching existed.
   const run = spawnSync(config.wrap_command, {
-    shell: true, input: raw, encoding: "utf8", timeout: 5000,
+    shell: true, input: raw, encoding: "utf8", timeout: 5000, windowsHide: true,
   });
   lines = (run.stdout || "").replace(/\\n$/, "").split("\\n");
   if (lines.length === 1 && lines[0] === "") lines = [];

package/src/thread-session-codex.js

@@ -0,0 +1,218 @@
+/* Write a canonical thread into a Codex rollout it will resume from.
+
+   `penny codex resume <session-id>` reads ~/.codex/sessions/YYYY/MM/DD/rollout-<stamp>-<uuid>.jsonl,
+   so a synthesized rollout in that tree resumes like any other session. Verified end-to-end on
+   codex-cli 0.147.0: a file written by this shape resumed and the model answered from history it
+   never lived.
+
+   The format differs from Claude Code's in every structural respect, which is why this is a
+   separate writer rather than a flag on the other one:
+
+     - Records are an ordinal-bearing {timestamp, type, payload} envelope, not flat messages.
+     - Paginated history uses task and item events grouped by turn id; response_item records alone
+       produce an empty thread in 0.147 even though the file itself can be found.
+     - The first record is a `session_meta` header carrying cwd, cli_version and the id.
+     - User content is `input_text`; assistant content is `output_text`. Using the wrong key
+       for a role is the one mistake that produces a file which loads but renders empty.
+     - Ids are UUIDv7 (time-ordered), and both the filename stamp and the id encode when the
+       session began. Codex sorts its picker by these, so a random v4 sorts to 1970.
+
+   THE FORMAT IS UNDOCUMENTED, exactly as with Claude Code, and the same three rules apply:
+   never overwrite, version-gate, and fail loudly rather than write something that only reveals
+   itself as broken at resume time. */
+
+import { randomBytes } from "node:crypto";
+import { mkdirSync, existsSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { orientation, renderMessage } from "./thread-session.js";
+
+/** Versions this writer has been verified against. */
+export const VERIFIED_MIN = "0.147.0";
+export const VERIFIED_MAX = "0.999.999";
+
+/** UUIDv7: 48-bit big-endian millisecond timestamp, then version/variant bits, then random.
+    Codex orders sessions by this, so a v4 would sort as if it began in 1970. */
+export function uuidv7(now = Date.now()) {
+  const bytes = randomBytes(16);
+  const ms = BigInt(now);
+  for (let i = 0; i < 6; i += 1) {
+    bytes[i] = Number((ms >> BigInt(8 * (5 - i))) & 0xffn);
+  }
+  bytes[6] = (bytes[6] & 0x0f) | 0x70;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const hex = bytes.toString("hex");
+  return [
+    hex.slice(0, 8),
+    hex.slice(8, 12),
+    hex.slice(12, 16),
+    hex.slice(16, 20),
+    hex.slice(20),
+  ].join("-");
+}
+
+function compare(a, b) {
+  const pa = String(a).split(".").map((n) => parseInt(n, 10) || 0);
+  const pb = String(b).split(".").map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i += 1) {
+    if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) < (pb[i] || 0) ? -1 : 1;
+  }
+  return 0;
+}
+
+export function versionSupported(version) {
+  if (!version) return false;
+  // `codex --version` prints "codex-cli 0.147.0"; take the numeric field wherever it sits.
+  const match = String(version).match(/(\d+\.\d+\.\d+)/);
+  if (!match) return false;
+  return compare(match[1], VERIFIED_MIN) >= 0 && compare(match[1], VERIFIED_MAX) <= 0;
+}
+
+/** ~/.codex/sessions/YYYY/MM/DD — Codex partitions rollouts by local date. */
+export function sessionDirFor(date = new Date()) {
+  const yyyy = String(date.getFullYear());
+  const mm = String(date.getMonth() + 1).padStart(2, "0");
+  const dd = String(date.getDate()).padStart(2, "0");
+  return join(homedir(), ".codex", "sessions", yyyy, mm, dd);
+}
+
+/** The local-wall-time stamp embedded in a rollout filename: 2026-08-09T22-15-30. */
+export function fileStamp(date = new Date()) {
+  const pad = (value) => String(value).padStart(2, "0");
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}` +
+    `T${pad(date.getHours())}-${pad(date.getMinutes())}-${pad(date.getSeconds())}`;
+}
+
+export function buildRecords(thread, { cwd, sessionId, version, timestamp = new Date() }) {
+  const ts = timestamp.toISOString();
+  const epochSeconds = Math.floor(timestamp.getTime() / 1000);
+  let ordinal = 0;
+  const envelope = (type, payload) => ({ timestamp: ts, ordinal: ordinal++, type, payload });
+
+  const message = (role, text, turnId, { final = false } = {}) => ({
+    type: "message",
+    id: `msg_${uuidv7(timestamp.getTime())}`,
+    role,
+    content: [{ type: role === "assistant" ? "output_text" : "input_text", text }],
+    ...(final ? { phase: "final_answer" } : {}),
+    internal_chat_message_metadata_passthrough: { turn_id: turnId },
+  });
+
+  // Keep the import handoff out of the visible conversation. Codex accepts a developer
+  // response_item in a rollout; it is injected as context but is not rendered as a user turn.
+  // The imported transcript should begin with the source's actual first user message.
+  const turns = [];
+  for (const entry of thread.messages || []) {
+    const text = renderMessage(entry);
+    if (!text) continue;
+    if (entry.role === "user") turns.push({ user: text, assistants: [] });
+    else if (entry.role === "assistant") {
+      if (!turns.length) turns.push({ user: "Continue the imported conversation.", assistants: [] });
+      turns.at(-1).assistants.push(text);
+    }
+  }
+
+  const records = [
+    envelope("session_meta", {
+      session_id: sessionId,
+      id: sessionId,
+      timestamp: ts,
+      cwd,
+      originator: "pennyrouter",
+      cli_version: String(version || "").match(/(\d+\.\d+\.\d+)/)?.[1] || "0.0.0",
+      source: "cli",
+      thread_source: "user",
+      model_provider: "pennyrouter",
+      history_mode: "paginated",
+    }),
+  ];
+
+  for (const [turnIndex, turn] of turns.entries()) {
+    const turnId = uuidv7(timestamp.getTime());
+    records.push(envelope("event_msg", {
+      type: "task_started",
+      turn_id: turnId,
+      started_at: epochSeconds,
+      model_context_window: null,
+      collaboration_mode_kind: "default",
+    }));
+    if (turnIndex === 0) {
+      records.push(envelope("response_item", message("developer", orientation(thread), turnId)));
+    }
+    const userMessage = message("user", turn.user, turnId);
+    records.push(envelope("response_item", userMessage));
+    records.push(envelope("event_msg", {
+      type: "item_completed",
+      thread_id: sessionId,
+      turn_id: turnId,
+      item: {
+        type: "UserMessage",
+        id: uuidv7(timestamp.getTime()),
+        content: [{ type: "text", text: turn.user, text_elements: [] }],
+      },
+      started_at_ms: timestamp.getTime(),
+      completed_at_ms: timestamp.getTime(),
+    }));
+
+    let lastAssistant = "";
+    for (const text of turn.assistants) {
+      lastAssistant = text;
+      const assistantMessage = message("assistant", text, turnId, { final: true });
+      records.push(envelope("event_msg", {
+        type: "item_completed",
+        thread_id: sessionId,
+        turn_id: turnId,
+        item: {
+          type: "AgentMessage",
+          id: assistantMessage.id,
+          content: [{ type: "Text", text }],
+          phase: "final_answer",
+        },
+        started_at_ms: timestamp.getTime(),
+        completed_at_ms: timestamp.getTime(),
+      }));
+      records.push(envelope("response_item", assistantMessage));
+    }
+    records.push(envelope("event_msg", {
+      type: "task_complete",
+      turn_id: turnId,
+      last_agent_message: lastAssistant,
+      started_at: epochSeconds,
+      completed_at: epochSeconds,
+      duration_ms: 0,
+      time_to_first_token_ms: 0,
+    }));
+  }
+
+  return records;
+}
+
+/**
+ * Write `thread` as a resumable Codex rollout.
+ * Returns { sessionId, path, messageCount }.
+ */
+export function writeSession(thread, { cwd, version, timestamp = new Date() }) {
+  if (!versionSupported(version)) {
+    throw new Error(
+      `Codex ${version || "(unknown version)"} is outside the range this importer has been ` +
+        `verified against (${VERIFIED_MIN}–${VERIFIED_MAX}). Refusing to write a rollout that ` +
+        `may not resume.`,
+    );
+  }
+
+  const dir = sessionDirFor(timestamp);
+  mkdirSync(dir, { recursive: true });
+
+  const sessionId = uuidv7(timestamp.getTime());
+  const path = join(dir, `rollout-${fileStamp(timestamp)}-${sessionId}.jsonl`);
+  if (existsSync(path)) throw new Error("session id collision; try again");
+
+  const records = buildRecords(thread, { cwd, sessionId, version, timestamp });
+  writeFileSync(path, records.map((r) => JSON.stringify(r)).join("\n") + "\n", {
+    encoding: "utf8",
+    flag: "wx", // fail rather than clobber, even against a race
+  });
+
+  return { sessionId, path, messageCount: records.length };
+}

package/src/thread-session-codex.test.js

@@ -0,0 +1,151 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  buildRecords,
+  fileStamp,
+  sessionDirFor,
+  uuidv7,
+  versionSupported,
+  writeSession,
+} from "./thread-session-codex.js";
+
+const thread = {
+  title: "Kickplate removal",
+  source: "perplexity_share",
+  origin_app: "Perplexity",
+  source_url: "https://www.perplexity.ai/search/x",
+  messages: [
+    { role: "user", blocks: [{ type: "text", text: "USER-TURN" }] },
+    {
+      role: "assistant",
+      blocks: [
+        { type: "thinking", text: "REASONING-TRACE" },
+        { type: "text", text: "ASSISTANT-TURN" },
+      ],
+    },
+    { role: "system", blocks: [{ type: "text", text: "SYSTEM-PREAMBLE" }] },
+  ],
+};
+
+// -- uuidv7 ---------------------------------------------------------------
+// Codex sorts its session picker by these ids. A random v4 would sort as if the session began
+// in 1970, so the timestamp prefix is not cosmetic.
+{
+  const when = Date.UTC(2026, 7, 9, 22, 15, 30);
+  const id = uuidv7(when);
+  assert.match(id, /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/);
+  assert.equal(parseInt(id.slice(0, 8) + id.slice(9, 13), 16), when, "ms timestamp is encoded");
+  assert.notEqual(uuidv7(when), uuidv7(when), "the random tail still varies");
+  // Time-ordering is the property Codex depends on.
+  assert.ok(uuidv7(when) < uuidv7(when + 1000));
+}
+
+// -- paths ----------------------------------------------------------------
+{
+  const originalTz = process.env.TZ;
+  process.env.TZ = "America/New_York";
+  try {
+    // Codex filenames use local wall time, including when UTC crossed into the next day.
+    const date = new Date(Date.UTC(2026, 7, 10, 2, 15, 30));
+    assert.ok(sessionDirFor(date).endsWith(join(".codex", "sessions", "2026", "08", "09")));
+    assert.equal(fileStamp(date), "2026-08-09T22-15-30");
+  } finally {
+    if (originalTz === undefined) delete process.env.TZ;
+    else process.env.TZ = originalTz;
+  }
+}
+
+// -- version gate ---------------------------------------------------------
+// `codex --version` prints "codex-cli 0.147.0", so the number has to be found, not assumed.
+assert.equal(versionSupported("codex-cli 0.147.0"), true);
+assert.equal(versionSupported("0.146.0"), false);
+assert.equal(versionSupported("1.0.0"), false);
+assert.equal(versionSupported("not-a-version"), false);
+assert.equal(versionSupported(null), false);
+
+// -- record construction --------------------------------------------------
+{
+  const records = buildRecords(thread, {
+    cwd: "/tmp/ws",
+    sessionId: "sid-1",
+    version: "codex-cli 0.147.0",
+  });
+
+  // Codex 0.147 uses an ordinal-bearing paginated rollout envelope.
+  for (const record of records) {
+    assert.deepEqual(Object.keys(record).sort(), ["ordinal", "payload", "timestamp", "type"]);
+  }
+
+  const [meta, ...rest] = records;
+  assert.equal(meta.type, "session_meta");
+  assert.equal(meta.payload.session_id, "sid-1");
+  assert.equal(meta.payload.cwd, "/tmp/ws");
+  assert.equal(meta.payload.cli_version, "0.147.0", "the bare number, not the whole string");
+  assert.equal(meta.payload.history_mode, "paginated");
+
+  // Content key is role-dependent. Getting this wrong yields a rollout that loads and renders
+  // empty, which is the failure mode least likely to be noticed before a user hits it.
+  const messages = rest.filter((record) => record.type === "response_item");
+  for (const record of messages) {
+    assert.equal(record.payload.type, "message");
+    const key = record.payload.content[0].type;
+    assert.equal(key, record.payload.role === "assistant" ? "output_text" : "input_text");
+    assert.match(record.payload.id, /^msg_/);
+    assert.ok(record.payload.internal_chat_message_metadata_passthrough.turn_id);
+  }
+
+  assert.deepEqual(
+    messages.map((r) => r.payload.role),
+    ["developer", "user", "assistant"],
+  );
+  assert.equal(messages[0].payload.role, "developer");
+  assert.ok(messages[0].payload.content[0].text.includes("Perplexity"), "handoff is developer context");
+  assert.equal(messages[1].payload.role, "user");
+  assert.equal(rest.filter((r) => r.payload.type === "task_started").length, 1);
+  assert.equal(rest.filter((r) => r.payload.type === "task_complete").length, 1);
+  assert.equal(rest.filter((r) => r.payload.type === "item_completed").length, 2);
+
+  const serialized = JSON.stringify(records);
+  assert.ok(!serialized.includes("REASONING-TRACE"), "thinking must never reach a handoff");
+  assert.ok(!serialized.includes("SYSTEM-PREAMBLE"), "system turns are not replayed");
+  assert.ok(serialized.includes("USER-TURN") && serialized.includes("ASSISTANT-TURN"));
+  assert.ok(!messages.some((r) => r.payload.role === "user" && r.payload.content[0].text.includes("This session was imported")));
+}
+
+// -- writing --------------------------------------------------------------
+{
+  const home = mkdtempSync(join(tmpdir(), "pr-codex-home-"));
+  const originalHome = process.env.HOME;
+  process.env.HOME = home;
+  try {
+    const result = writeSession(thread, { cwd: "/tmp/ws", version: "codex-cli 0.147.0" });
+
+    // The filename carries both the stamp and the id; Codex's picker reads both.
+    assert.match(result.path, /rollout-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-[0-9a-f-]{36}\.jsonl$/);
+    assert.ok(result.path.includes(result.sessionId));
+
+    const lines = readFileSync(result.path, "utf8").trim().split("\n");
+    assert.equal(lines.length, result.messageCount);
+    const parsed = lines.map((l) => JSON.parse(l));
+    assert.equal(parsed[0].type, "session_meta");
+    assert.equal(parsed[0].payload.id, result.sessionId);
+
+    // Never overwrite an existing session.
+    const again = writeSession(thread, { cwd: "/tmp/ws", version: "codex-cli 0.147.0" });
+    assert.notEqual(again.sessionId, result.sessionId);
+    assert.notEqual(again.path, result.path);
+
+    assert.throws(
+      () => writeSession(thread, { cwd: "/tmp/ws", version: "codex-cli 2.0.0" }),
+      /outside the range/,
+    );
+    assert.throws(() => writeSession(thread, { cwd: "/tmp/ws", version: null }), /outside the range/);
+  } finally {
+    process.env.HOME = originalHome;
+  }
+}
+
+console.log("thread-session-codex tests passed");