@letta-ai/letta-code 0.30.28 → 0.30.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.30.28",
+  "version": "0.30.30",
   "description": "Letta Code is a CLI tool for interacting with stateful Letta agents from the terminal.",
   "type": "module",
   "packageManager": "bun@1.3.10",
@@ -119,14 +119,15 @@
     "access": "public"
   },
   "dependencies": {
-    "@earendil-works/pi-ai": "^0.82.1",
+    "@earendil-works/pi-ai": "0.84.2",
+    "@janhapke/sharp-electron": "0.35.3-electron.1",
     "@letta-ai/letta-client": "^1.10.2",
     "@letta-ai/trajectory": "0.2.0",
     "@modelcontextprotocol/sdk": "1.30.0",
     "@pierre/diffs": "1.2.2",
     "@scarf/scarf": "^1.4.0",
-    "cross-spawn": "^7.0.6",
     "cron-parser": "^5.6.1",
+    "cross-spawn": "^7.0.6",
     "glob": "^13.0.0",
     "ink-link": "^5.0.0",
     "node-pty": "^1.1.0",

package/scripts/codex-watch/agent-watch.ts

@@ -17,13 +17,19 @@ import {
 import {
   analyzeCodexRelease,
   DEFAULT_TARGET_REPO,
+  findNextStableRelease,
+  listStableReleases,
+  type Release,
 } from "./release-analysis.ts";
 import {
+  advanceCodexAuditCursor,
   emptyTrackerState,
-  hasProcessedTag,
+  getCodexAuditCursorTag,
+  hasProcessedRange,
   parseTrackerState,
   recordAnalysis,
   renderTrackerBody,
+  validateLegacyCodexAuditCursor,
 } from "./tracker.ts";
 
 const DEFAULT_TRACKER_TITLE = "Codex upstream drift tracker";
@@ -77,15 +83,50 @@ function parseArgs(argv: string[]): Args {
 
 async function main() {
   const args = parseArgs(process.argv.slice(2));
+  const tracker = ensureTrackerIssue(args);
+  let state = parseTrackerState(tracker.body);
+  let sinceTag = args.sinceTag;
+  let currentTag = args.currentTag;
+  let stableReleases: Release[] | undefined;
+
+  if (!state.audit_cursor_validated) {
+    stableReleases = await listStableReleases();
+    state = validateLegacyCodexAuditCursor(
+      state,
+      stableReleases.map((release) => release.tag_name),
+    );
+    if (!args.dryRun) {
+      editIssueBody(args.repo, tracker.number, renderTrackerBody(state));
+    }
+  }
+
+  if (!sinceTag && !currentTag) {
+    const cursorTag = getCodexAuditCursorTag(state);
+    if (cursorTag) {
+      stableReleases ??= await listStableReleases();
+      const nextRelease = findNextStableRelease(stableReleases, cursorTag);
+      if (!nextRelease) {
+        console.log(`No stable release after ${cursorTag}; nothing to do.`);
+        writeOutput("tracker_issue", String(tracker.number));
+        writeOutput("tracker_issue_url", tracker.url);
+        writeOutput("current_tag", cursorTag);
+        writeOutput("previous_tag", cursorTag);
+        writeOutput("verdict", "no-op");
+        writeOutput("should_run_agent", "false");
+        return;
+      }
+      sinceTag = cursorTag;
+      currentTag = nextRelease.tag_name;
+    }
+  }
+
   const analysis = await analyzeCodexRelease({
-    sinceTag: args.sinceTag,
-    currentTag: args.currentTag,
+    sinceTag,
+    currentTag,
+    stableReleases,
   });
   writeFileSync(args.analysisFile, `${JSON.stringify(analysis, null, 2)}\n`);
 
-  const tracker = ensureTrackerIssue(args);
-  const state = parseTrackerState(tracker.body);
-
   writeOutput("tracker_issue", String(tracker.number));
   writeOutput("tracker_issue_url", tracker.url);
   writeOutput("analysis_file", args.analysisFile);
@@ -93,8 +134,22 @@ async function main() {
   writeOutput("previous_tag", analysis.previous_tag);
   writeOutput("verdict", analysis.verdict);
 
-  if (!args.dryRun && hasProcessedTag(state, analysis.current_tag)) {
-    console.log(`Already processed ${analysis.current_tag}; nothing to do.`);
+  if (
+    !args.dryRun &&
+    hasProcessedRange(state, analysis.previous_tag, analysis.current_tag)
+  ) {
+    const next = advanceCodexAuditCursor(
+      state,
+      analysis.previous_tag,
+      analysis.current_tag,
+      analysis.is_adjacent_release,
+    );
+    if (next !== state) {
+      editIssueBody(args.repo, tracker.number, renderTrackerBody(next));
+    }
+    console.log(
+      `Already processed ${analysis.previous_tag}...${analysis.current_tag}; nothing to do.`,
+    );
     writeOutput("should_run_agent", "false");
     return;
   }

package/scripts/codex-watch/release-analysis.test.ts

@@ -0,0 +1,57 @@
+import {
+  areAdjacentStableReleases,
+  findNextStableRelease,
+  type Release,
+} from "./release-analysis.ts";
+
+function release(tag: string, publishedAt: string): Release {
+  return {
+    tag_name: tag,
+    draft: false,
+    prerelease: false,
+    html_url: `https://github.com/openai/codex/releases/tag/${tag}`,
+    body: null,
+    published_at: publishedAt,
+  };
+}
+
+const STABLES = [
+  release("rust-v0.1.0", "2026-08-01T00:00:00Z"),
+  release("rust-v0.2.0", "2026-08-02T00:00:00Z"),
+  release("rust-v0.3.0", "2026-08-03T00:00:00Z"),
+];
+
+describe("Codex stable release backlog", () => {
+  test("selects the first release after the durable cursor", () => {
+    expect(
+      findNextStableRelease(STABLES, "rust-v0.1.0")?.tag_name,
+    ).toBe("rust-v0.2.0");
+  });
+
+  test("identifies only adjacent stable release pairs", () => {
+    expect(
+      areAdjacentStableReleases(
+        STABLES,
+        "rust-v0.1.0",
+        "rust-v0.2.0",
+      ),
+    ).toBe(true);
+    expect(
+      areAdjacentStableReleases(
+        STABLES,
+        "rust-v0.1.0",
+        "rust-v0.3.0",
+      ),
+    ).toBe(false);
+  });
+
+  test("returns null when the durable cursor is current", () => {
+    expect(findNextStableRelease(STABLES, "rust-v0.3.0")).toBeNull();
+  });
+
+  test("fails instead of skipping an unavailable cursor", () => {
+    expect(() =>
+      findNextStableRelease(STABLES, "rust-v0.0.9"),
+    ).toThrow("Could not find terminal release rust-v0.0.9");
+  });
+});

package/scripts/codex-watch/release-analysis.ts

@@ -34,6 +34,7 @@ export interface Release {
 export interface AnalyzeCodexReleaseOptions {
   sinceTag: string | null;
   currentTag: string | null;
+  stableReleases?: Release[];
 }
 
 export interface PathChangeSummary {
@@ -44,6 +45,7 @@ export interface PathChangeSummary {
 export interface CodexWatchAnalysis {
   previous_tag: string;
   current_tag: string;
+  is_adjacent_release: boolean;
   release_url: string;
   release_notes_md: string;
   verdict: Verdict;
@@ -59,7 +61,7 @@ export interface CodexWatchAnalysis {
 export async function analyzeCodexRelease(
   options: AnalyzeCodexReleaseOptions,
 ): Promise<CodexWatchAnalysis> {
-  const stables = await listStableReleases();
+  const stables = options.stableReleases ?? (await listStableReleases());
   if (stables.length === 0) throw new Error("No stable Codex releases found");
 
   const current = options.currentTag
@@ -137,6 +139,11 @@ export async function analyzeCodexRelease(
     return {
       previous_tag: previous.tag_name,
       current_tag: current.tag_name,
+      is_adjacent_release: areAdjacentStableReleases(
+        stables,
+        previous.tag_name,
+        current.tag_name,
+      ),
       release_url: current.html_url,
       release_notes_md: current.body ?? "",
       verdict,
@@ -200,6 +207,29 @@ function findPreviousStable(
   return stables[idx - 1] ?? null;
 }
 
+export function areAdjacentStableReleases(
+  stables: Release[],
+  previousTag: string,
+  currentTag: string,
+): boolean {
+  return (
+    findPreviousStable(stables, currentTag)?.tag_name === previousTag
+  );
+}
+
+export function findNextStableRelease(
+  stables: Release[],
+  terminalTag: string,
+): Release | null {
+  const terminalIndex = stables.findIndex(
+    (release) => release.tag_name === terminalTag,
+  );
+  if (terminalIndex < 0) {
+    throw new Error(`Could not find terminal release ${terminalTag}`);
+  }
+  return stables[terminalIndex + 1] ?? null;
+}
+
 function cloneCodex(tmp: string): string {
   const dir = join(tmp, "codex");
   git([

package/scripts/codex-watch/tracker.test.ts

@@ -1,14 +1,17 @@
 import { describe, expect, test } from "bun:test";
 import type { CodexWatchAnalysis } from "./release-analysis.ts";
 import {
+  advanceCodexAuditCursor,
   emptyTrackerState,
-  hasProcessedTag,
+  getCodexAuditCursorTag,
+  hasProcessedRange,
   parseTrackerState,
   recordAnalysis,
   renderTrackerBody,
   serializeTrackerState,
   type TrackerEntry,
   upsertTrackerEntry,
+  validateLegacyCodexAuditCursor,
 } from "./tracker.ts";
 
 function analysis(
@@ -18,6 +21,7 @@ function analysis(
   return {
     previous_tag: "rust-v0.1.0",
     current_tag: tag,
+    is_adjacent_release: true,
     release_url: `https://github.com/openai/codex/releases/tag/${tag}`,
     release_notes_md: "",
     verdict,
@@ -31,6 +35,12 @@ function analysis(
   };
 }
 
+function withoutAuditCursor(body: string): string {
+  return body
+    .replace(/  "audit_cursor_tag": (?:null|"[^"]+"),\n/, "")
+    .replace('  "audit_cursor_validated": true,\n', "");
+}
+
 function entry(index: number, outcome: TrackerEntry["outcome"]): TrackerEntry {
   const verdict =
     outcome === "recorded_noop" ? "no-op" : "tool-surface review needed";
@@ -51,11 +61,38 @@ function entry(index: number, outcome: TrackerEntry["outcome"]): TrackerEntry {
 }
 
 describe("tracker state", () => {
-  test("returns empty state when hidden state is absent or malformed", () => {
-    expect(parseTrackerState("plain body")).toEqual(emptyTrackerState());
-    expect(
+  test("fails closed when hidden state is absent or malformed", () => {
+    expect(() => parseTrackerState("plain body")).toThrow(
+      "Codex tracker hidden state is missing",
+    );
+    expect(() =>
       parseTrackerState("<!-- codex-agent-watch-state\nnot json\n-->"),
-    ).toEqual(emptyTrackerState());
+    ).toThrow("Codex tracker hidden state is invalid");
+    expect(() =>
+      parseTrackerState(
+        '<!-- codex-agent-watch-state\n{"last_checked_tag":null,"last_checked_at":null,"processed":[{}]}\n-->',
+      ),
+    ).toThrow("Codex tracker hidden state is invalid");
+    expect(() =>
+      parseTrackerState(
+        '<!-- codex-agent-watch-state\n{"audit_cursor_tag":null,"last_checked_tag":"rust-v0.2.0","last_checked_at":"2026-08-20T00:00:00Z","processed":[]}\n-->',
+      ),
+    ).toThrow("Codex tracker hidden state is invalid");
+  });
+
+  test("fails closed on an unsupported durable cursor", () => {
+    const state = upsertTrackerEntry(
+      emptyTrackerState(),
+      entry(1, "no_local_impact"),
+    );
+    const body = renderTrackerBody(state).replace(
+      '"audit_cursor_tag": "rust-v0.1.0"',
+      '"audit_cursor_tag": "rust-v0.5.0"',
+    );
+
+    expect(() => parseTrackerState(body)).toThrow(
+      "Codex tracker hidden state is invalid",
+    );
   });
 
   test("round-trips hidden state through rendered body", () => {
@@ -72,6 +109,85 @@ describe("tracker state", () => {
     expect(body).toContain("upstream-only router change");
   });
 
+  test("derives the durable cursor from legacy hidden state", () => {
+    const state = recordAnalysis(emptyTrackerState(), {
+      analysis: analysis("rust-v0.2.0"),
+      outcome: "recorded_noop",
+      notes: "no watched changes",
+      processedAt: "2026-07-02T00:00:00.000Z",
+    });
+    const legacyBody = withoutAuditCursor(renderTrackerBody(state));
+
+    const legacy = parseTrackerState(legacyBody);
+    expect(legacy.audit_cursor_validated).toBe(false);
+    const migrated = validateLegacyCodexAuditCursor(legacy, [
+      "rust-v0.1.0",
+      "rust-v0.2.0",
+    ]);
+    expect(migrated.audit_cursor_validated).toBe(true);
+    expect(getCodexAuditCursorTag(migrated)).toBe("rust-v0.2.0");
+  });
+
+  test("migrates a legacy cursor independently of an older replay", () => {
+    let state = upsertTrackerEntry(
+      emptyTrackerState(),
+      entry(1, "no_local_impact"),
+    );
+    state = upsertTrackerEntry(state, entry(2, "no_local_impact"));
+    state = upsertTrackerEntry(state, entry(3, "no_local_impact"));
+    state = upsertTrackerEntry(state, entry(1, "no_local_impact"));
+
+    const legacy = parseTrackerState(
+      withoutAuditCursor(renderTrackerBody(state)),
+    );
+    const migrated = validateLegacyCodexAuditCursor(legacy, [
+      "rust-v0.0.0",
+      "rust-v0.1.0",
+      "rust-v0.2.0",
+      "rust-v0.3.0",
+    ]);
+    expect(migrated.last_checked_tag).toBe("rust-v0.1.0");
+    expect(getCodexAuditCursorTag(migrated)).toBe("rust-v0.3.0");
+  });
+
+  test("fails closed on a disconnected future legacy replay", () => {
+    let state = upsertTrackerEntry(
+      emptyTrackerState(),
+      entry(1, "no_local_impact"),
+    );
+    state = upsertTrackerEntry(state, entry(2, "no_local_impact"));
+    state = upsertTrackerEntry(state, entry(5, "no_local_impact"));
+
+    expect(() =>
+      parseTrackerState(withoutAuditCursor(renderTrackerBody(state))),
+    ).toThrow("Codex tracker hidden state is invalid");
+  });
+
+  test("fails closed on a cumulative legacy replay", () => {
+    const cumulative = {
+      ...analysis("rust-v0.5.0", "tool-surface review needed"),
+      is_adjacent_release: false,
+    };
+    const state = recordAnalysis(emptyTrackerState(), {
+      analysis: cumulative,
+      outcome: "no_local_impact",
+      notes: "legacy cumulative replay",
+    });
+    const legacy = parseTrackerState(
+      withoutAuditCursor(renderTrackerBody(state)),
+    );
+
+    expect(() =>
+      validateLegacyCodexAuditCursor(legacy, [
+        "rust-v0.1.0",
+        "rust-v0.2.0",
+        "rust-v0.3.0",
+        "rust-v0.4.0",
+        "rust-v0.5.0",
+      ]),
+    ).toThrow("Legacy Codex tracker range is not adjacent");
+  });
+
   test("records noops in hidden state without adding visible table rows", () => {
     const state = recordAnalysis(emptyTrackerState(), {
       analysis: analysis("rust-v0.2.0"),
@@ -81,11 +197,132 @@ describe("tracker state", () => {
     });
 
     const body = renderTrackerBody(state);
-    expect(hasProcessedTag(parseTrackerState(body), "rust-v0.2.0")).toBe(true);
+    expect(
+      hasProcessedRange(
+        parseTrackerState(body),
+        "rust-v0.1.0",
+        "rust-v0.2.0",
+      ),
+    ).toBe(true);
     expect(body).toContain("_No actionable releases recorded yet._");
     expect(body).toContain("no watched changes");
   });
 
+  test("retries an errored release from its previous tag", () => {
+    let state = upsertTrackerEntry(
+      emptyTrackerState(),
+      entry(1, "recorded_noop"),
+    );
+    state = upsertTrackerEntry(state, entry(2, "error"));
+
+    expect(
+      hasProcessedRange(state, "rust-v0.1.0", "rust-v0.2.0"),
+    ).toBe(false);
+    expect(getCodexAuditCursorTag(state)).toBe("rust-v0.1.0");
+
+    state = upsertTrackerEntry(state, entry(2, "no_local_impact"));
+    expect(
+      hasProcessedRange(state, "rust-v0.1.0", "rust-v0.2.0"),
+    ).toBe(true);
+    expect(getCodexAuditCursorTag(state)).toBe("rust-v0.2.0");
+  });
+
+  test("uses an errored release baseline when no terminal entry exists", () => {
+    const state = upsertTrackerEntry(
+      emptyTrackerState(),
+      entry(2, "error"),
+    );
+
+    expect(getCodexAuditCursorTag(state)).toBe("rust-v0.1.0");
+  });
+
+  test("does not regress the cursor after an older replay", () => {
+    let state = upsertTrackerEntry(
+      emptyTrackerState(),
+      entry(10, "no_local_impact"),
+    );
+    state = upsertTrackerEntry(state, entry(5, "no_local_impact"));
+
+    expect(state.last_checked_tag).toBe("rust-v0.5.0");
+    expect(getCodexAuditCursorTag(state)).toBe("rust-v0.10.0");
+  });
+
+  test("does not let a future replay skip an errored release", () => {
+    let state = upsertTrackerEntry(
+      emptyTrackerState(),
+      entry(1, "no_local_impact"),
+    );
+    state = upsertTrackerEntry(state, entry(2, "error"));
+    state = upsertTrackerEntry(state, entry(5, "no_local_impact"));
+
+    expect(getCodexAuditCursorTag(state)).toBe("rust-v0.1.0");
+
+    state = upsertTrackerEntry(state, entry(2, "no_local_impact"));
+    expect(getCodexAuditCursorTag(state)).toBe("rust-v0.2.0");
+  });
+
+  test("does not advance for an explicit non-adjacent range", () => {
+    const initial = upsertTrackerEntry(
+      emptyTrackerState(),
+      entry(1, "no_local_impact"),
+    );
+    const cumulative = {
+      ...analysis("rust-v0.5.0", "tool-surface review needed"),
+      is_adjacent_release: false,
+    };
+    const state = recordAnalysis(initial, {
+      analysis: cumulative,
+      outcome: "no_local_impact",
+      notes: "explicit cumulative replay",
+    });
+
+    expect(getCodexAuditCursorTag(state)).toBe("rust-v0.1.0");
+    expect(
+      getCodexAuditCursorTag(
+        advanceCodexAuditCursor(
+          state,
+          "rust-v0.1.0",
+          "rust-v0.5.0",
+          false,
+        ),
+      ),
+    ).toBe("rust-v0.1.0");
+  });
+
+  test("advances across an already audited adjacent range", () => {
+    let state = upsertTrackerEntry(
+      emptyTrackerState(),
+      entry(1, "no_local_impact"),
+    );
+    state = upsertTrackerEntry(state, entry(3, "no_local_impact"));
+    state = upsertTrackerEntry(state, entry(2, "no_local_impact"));
+
+    expect(getCodexAuditCursorTag(state)).toBe("rust-v0.2.0");
+    state = advanceCodexAuditCursor(
+      state,
+      "rust-v0.2.0",
+      "rust-v0.3.0",
+      true,
+    );
+    expect(getCodexAuditCursorTag(state)).toBe("rust-v0.3.0");
+  });
+
+  test("retains the durable cursor entry when history is truncated", () => {
+    let state = upsertTrackerEntry(
+      emptyTrackerState(),
+      entry(100, "no_local_impact"),
+    );
+    for (let index = 1; index <= 60; index += 1) {
+      state = upsertTrackerEntry(state, entry(index, "no_local_impact"));
+    }
+
+    expect(state.processed).toHaveLength(50);
+    expect(state.processed.some(({ tag }) => tag === "rust-v0.100.0")).toBe(
+      true,
+    );
+    expect(getCodexAuditCursorTag(state)).toBe("rust-v0.100.0");
+  });
+
   test("keeps the last 50 processed releases in hidden state", () => {
     let state = emptyTrackerState();
     for (let i = 1; i <= 60; i++) {