@letta-ai/letta-code 0.30.27 → 0.30.29

package/scripts/claude-watch/update-tracker.ts

@@ -0,0 +1,201 @@
+#!/usr/bin/env bun
+
+import { readFileSync } from "node:fs";
+import { editIssueBody, getIssueBody, ghJson } from "./github.ts";
+import {
+  loadStateSnapshotAtCommit,
+  resolveStateBranchTip,
+} from "./state-branch.ts";
+import {
+  findTrackerEntry,
+  hasProcessedCandidate,
+  isTerminalOutcome,
+  parseTrackerState,
+  recordAnalysis,
+  renderTrackerBody,
+} from "./tracker.ts";
+import type { ClaudeWatchAnalysis, ClaudeWatchOutcome } from "./types.ts";
+
+const DEFAULT_REPO = "letta-ai/letta-code";
+
+interface Args {
+  repo: string;
+  trackerIssue: number | null;
+  analysisFile: string | null;
+  candidateId: string | null;
+  stateCommitSha: string | null;
+  outcome: ClaudeWatchOutcome | null;
+  notes: string;
+  prUrl: string | null;
+  assertTerminal: boolean;
+  dryRun: boolean;
+}
+
+export function parseArgs(argv: string[]): Args {
+  const args: Args = {
+    repo: DEFAULT_REPO,
+    trackerIssue: null,
+    analysisFile: null,
+    candidateId: null,
+    stateCommitSha: null,
+    outcome: null,
+    notes: "",
+    prUrl: null,
+    assertTerminal: false,
+    dryRun: false,
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "--repo") args.repo = argv[++index] ?? args.repo;
+    else if (argument === "--tracker-issue")
+      args.trackerIssue = Number(argv[++index]);
+    else if (argument === "--analysis-file")
+      args.analysisFile = argv[++index] ?? null;
+    else if (argument === "--candidate-id")
+      args.candidateId = argv[++index] ?? null;
+    else if (argument === "--state-commit-sha")
+      args.stateCommitSha = argv[++index] ?? null;
+    else if (argument === "--outcome")
+      args.outcome = parseOutcome(argv[++index]);
+    else if (argument === "--notes") args.notes = argv[++index] ?? "";
+    else if (argument === "--pr-url") args.prUrl = argv[++index] ?? null;
+    else if (argument === "--assert-terminal") args.assertTerminal = true;
+    else if (argument === "--dry-run") args.dryRun = true;
+    else throw new Error(`Unknown argument: ${argument}`);
+  }
+  if (!args.trackerIssue || Number.isNaN(args.trackerIssue))
+    throw new Error("--tracker-issue is required");
+  if (args.assertTerminal) {
+    if (!args.candidateId || !args.stateCommitSha)
+      throw new Error(
+        "--candidate-id and --state-commit-sha are required with --assert-terminal",
+      );
+  } else {
+    if (!args.analysisFile) throw new Error("--analysis-file is required");
+    if (!args.outcome) throw new Error("--outcome is required");
+    if (isTerminalOutcome(args.outcome) && !args.stateCommitSha)
+      throw new Error("terminal outcomes require --state-commit-sha");
+    if (args.outcome === "pr_created" && !args.prUrl)
+      throw new Error("--pr-url is required for pr_created");
+  }
+  return args;
+}
+
+function parseOutcome(value: string | undefined): ClaudeWatchOutcome {
+  if (
+    value === "recorded_noop" ||
+    value === "no_local_impact" ||
+    value === "pr_created" ||
+    value === "needs_human_review" ||
+    value === "error"
+  ) {
+    return value;
+  }
+  throw new Error(`Unknown outcome: ${value}`);
+}
+
+export function verifyStateCandidate(
+  candidateId: string,
+  stateCommitSha: string,
+  repoPath = process.cwd(),
+): void {
+  const tip = resolveStateBranchTip(repoPath);
+  if (tip !== stateCommitSha) {
+    throw new Error(
+      `Claude state tip ${tip ?? "missing"} does not match ${stateCommitSha}`,
+    );
+  }
+  const snapshot = loadStateSnapshotAtCommit(repoPath, stateCommitSha);
+  if (snapshot?.candidate_id !== candidateId) {
+    throw new Error(
+      `Claude state candidate ${snapshot?.candidate_id ?? "missing"} does not match ${candidateId}`,
+    );
+  }
+}
+
+function verifyParityPr(
+  repo: string,
+  prUrl: string,
+  candidateId: string,
+): void {
+  const pr = ghJson<{
+    isDraft: boolean;
+    author: { login: string };
+    body: string | null;
+  }>(["pr", "view", prUrl, "--repo", repo, "--json", "isDraft,author,body"]);
+  if (!pr.isDraft || pr.author.login !== "carenthomas") {
+    throw new Error(
+      `Parity PR must be a draft authored by carenthomas (got draft=${pr.isDraft}, author=${pr.author.login})`,
+    );
+  }
+  if (!pr.body?.includes(`Claude-watch: ${candidateId}`)) {
+    throw new Error("Parity PR body is missing the exact Claude-watch marker");
+  }
+}
+
+export function main(argv = process.argv.slice(2)): void {
+  const args = parseArgs(argv);
+  const issue = args.trackerIssue as number;
+  const state = parseTrackerState(getIssueBody(args.repo, issue));
+
+  if (args.assertTerminal) {
+    verifyStateCandidate(
+      args.candidateId as string,
+      args.stateCommitSha as string,
+    );
+    const entry = findTrackerEntry(state, args.candidateId as string);
+    if (
+      !entry ||
+      !hasProcessedCandidate(state, args.candidateId as string) ||
+      entry.state_commit_sha !== args.stateCommitSha
+    ) {
+      throw new Error(
+        `Candidate ${args.candidateId} does not have a matching terminal tracker outcome`,
+      );
+    }
+    console.log(`Verified terminal Claude outcome for ${args.candidateId}`);
+    return;
+  }
+
+  const analysis = JSON.parse(
+    readFileSync(args.analysisFile as string, "utf8"),
+  ) as ClaudeWatchAnalysis;
+  if (isTerminalOutcome(args.outcome as ClaudeWatchOutcome)) {
+    verifyStateCandidate(analysis.candidate_id, args.stateCommitSha as string);
+  }
+  if (args.outcome === "pr_created") {
+    verifyParityPr(args.repo, args.prUrl as string, analysis.candidate_id);
+  }
+  const next = recordAnalysis(state, {
+    analysis,
+    outcome: args.outcome as ClaudeWatchOutcome,
+    notes: args.notes || defaultNotes(args.outcome as ClaudeWatchOutcome),
+    prUrl: args.prUrl,
+    stateCommitSha: args.stateCommitSha,
+    error:
+      args.outcome === "error" ? (analysis.errors.at(-1) ?? args.notes) : null,
+  });
+  const nextBody = renderTrackerBody(next);
+  if (args.dryRun) console.log(nextBody);
+  else editIssueBody(args.repo, issue, nextBody);
+  console.log(
+    `Recorded ${analysis.candidate_id} as ${args.outcome} in #${issue}`,
+  );
+}
+
+function defaultNotes(outcome: ClaudeWatchOutcome): string {
+  switch (outcome) {
+    case "recorded_noop":
+      return "no watched Claude surface changed";
+    case "no_local_impact":
+      return "reviewed; no local Letta Code mirror impact";
+    case "pr_created":
+      return "opened a focused local mirror PR";
+    case "needs_human_review":
+      return "public evidence needs human review";
+    case "error":
+      return "retryable watcher error";
+  }
+}
+
+if (import.meta.main) main();

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

@@ -2,8 +2,8 @@
 /**
  * Amelia-driven Codex release watcher entrypoint.
  *
- * This runs alongside the legacy per-release issue workflow. It uses a central
- * tracker issue for state and only asks Amelia to review non-noop releases.
+ * Uses a central tracker issue for state and only asks Amelia to review
+ * non-noop releases.
  */
 
 import { appendFileSync, writeFileSync } from "node:fs";
@@ -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

@@ -9,7 +9,6 @@ import {
   type ModelsJson,
   type Verdict,
 } from "./diff-models-json.ts";
-import type { PathChangeSummary, RenderInput } from "./render-issue.ts";
 
 export const CODEX_REPO = "openai/codex";
 export const DEFAULT_TARGET_REPO =
@@ -35,11 +34,26 @@ export interface Release {
 export interface AnalyzeCodexReleaseOptions {
   sinceTag: string | null;
   currentTag: string | null;
+  stableReleases?: Release[];
 }
 
-export interface CodexWatchAnalysis extends RenderInput {
+export interface PathChangeSummary {
+  path: string;
+  commits: string[];
+}
+
+export interface CodexWatchAnalysis {
+  previous_tag: string;
+  current_tag: string;
+  is_adjacent_release: boolean;
+  release_url: string;
+  release_notes_md: string;
   verdict: Verdict;
   models_diff: ModelsDiff | null;
+  prompt_md_changed: boolean;
+  prompt_md_diff_preview: string | null;
+  path_changes: PathChangeSummary[];
+  workflow_run_url: string;
   compare_url: string;
   changed_files: string[];
 }
@@ -47,7 +61,7 @@ export interface CodexWatchAnalysis extends RenderInput {
 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
@@ -125,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,
@@ -188,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([