@letta-ai/letta-code 0.30.28 → 0.30.30

package/scripts/codex-watch/tracker.ts

@@ -26,6 +26,8 @@ export interface TrackerEntry {
 }
 
 export interface TrackerState {
+  audit_cursor_tag: string | null;
+  audit_cursor_validated: boolean;
   last_checked_tag: string | null;
   last_checked_at: string | null;
   processed: TrackerEntry[];
@@ -41,6 +43,8 @@ export interface RecordAnalysisOptions {
 
 export function emptyTrackerState(): TrackerState {
   return {
+    audit_cursor_tag: null,
+    audit_cursor_validated: true,
     last_checked_tag: null,
     last_checked_at: null,
     processed: [],
@@ -49,21 +53,81 @@ export function emptyTrackerState(): TrackerState {
 
 export function parseTrackerState(body: string): TrackerState {
   const start = body.indexOf(STATE_START);
-  if (start === -1) return emptyTrackerState();
+  if (start === -1) throw new Error("Codex tracker hidden state is missing");
 
   const jsonStart = start + STATE_START.length;
   const end = body.indexOf(STATE_END, jsonStart);
-  if (end === -1) return emptyTrackerState();
+  if (end === -1) throw new Error("Codex tracker hidden state is incomplete");
 
   try {
     return normalizeState(JSON.parse(body.slice(jsonStart, end).trim()));
-  } catch {
-    return emptyTrackerState();
+  } catch (error) {
+    throw new Error("Codex tracker hidden state is invalid", { cause: error });
   }
 }
 
-export function hasProcessedTag(state: TrackerState, tag: string): boolean {
-  return state.processed.some((entry) => entry.tag === tag);
+export function isTerminalOutcome(outcome: TrackerOutcome): boolean {
+  return outcome !== "error";
+}
+
+export function hasProcessedRange(
+  state: TrackerState,
+  previousTag: string,
+  currentTag: string,
+): boolean {
+  return state.processed.some(
+    (entry) =>
+      entry.previous_tag === previousTag &&
+      entry.tag === currentTag &&
+      isTerminalOutcome(entry.outcome),
+  );
+}
+
+export function getCodexAuditCursorTag(state: TrackerState): string | null {
+  return state.audit_cursor_tag;
+}
+
+export function validateLegacyCodexAuditCursor(
+  state: TrackerState,
+  stableTags: string[],
+): TrackerState {
+  if (state.audit_cursor_validated) return state;
+
+  let tag = state.audit_cursor_tag;
+  while (tag !== null) {
+    const entry = state.processed.find(
+      (candidate) =>
+        candidate.tag === tag && isTerminalOutcome(candidate.outcome),
+    );
+    if (!entry) break;
+    const currentIndex = stableTags.indexOf(entry.tag);
+    if (
+      currentIndex < 1 ||
+      stableTags[currentIndex - 1] !== entry.previous_tag
+    ) {
+      throw new Error(
+        `Legacy Codex tracker range is not adjacent: ${entry.previous_tag}...${entry.tag}`,
+      );
+    }
+    tag = entry.previous_tag;
+  }
+
+  return { ...state, audit_cursor_validated: true };
+}
+
+export function advanceCodexAuditCursor(
+  state: TrackerState,
+  previousTag: string,
+  currentTag: string,
+  isAdjacentRelease: boolean,
+): TrackerState {
+  if (!isAdjacentRelease || state.audit_cursor_tag !== previousTag) return state;
+  if (!hasProcessedRange(state, previousTag, currentTag)) {
+    throw new Error(
+      `Cannot advance Codex audit cursor without terminal ${previousTag}...${currentTag}`,
+    );
+  }
+  return { ...state, audit_cursor_tag: currentTag };
 }
 
 export function recordAnalysis(
@@ -81,19 +145,51 @@ export function recordAnalysis(
     processed_at: processedAt,
     compare_url: options.analysis.compare_url,
     workflow_run_url: options.analysis.workflow_run_url,
-  });
+  }, options.analysis.is_adjacent_release);
 }
 
 export function upsertTrackerEntry(
   state: TrackerState,
   entry: TrackerEntry,
+  advanceAuditCursor = true,
 ): TrackerState {
-  const processed = [
+  let auditCursorTag = state.audit_cursor_tag;
+  if (auditCursorTag === null && !advanceAuditCursor) {
+    auditCursorTag = entry.previous_tag;
+  } else if (
+    advanceAuditCursor &&
+    entry.outcome === "error" &&
+    auditCursorTag === null
+  ) {
+    auditCursorTag = entry.previous_tag;
+  } else if (
+    advanceAuditCursor &&
+    isTerminalOutcome(entry.outcome) &&
+    (auditCursorTag === null || entry.previous_tag === auditCursorTag)
+  ) {
+    auditCursorTag = entry.tag;
+  }
+
+  const candidates = [
     entry,
-    ...state.processed.filter((existing) => existing.tag !== entry.tag),
-  ].slice(0, HIDDEN_STATE_LIMIT);
+    ...state.processed.filter(
+      (existing) =>
+        existing.tag !== entry.tag ||
+        existing.previous_tag !== entry.previous_tag,
+    ),
+  ];
+  let processed = candidates.slice(0, HIDDEN_STATE_LIMIT);
+  if (auditCursorTag !== null && !isSupportedAuditCursor(processed, auditCursorTag)) {
+    const support = candidates.find((candidate) =>
+      isAuditCursorSupportEntry(candidate, auditCursorTag),
+    );
+    if (!support) throw new Error("Codex audit cursor has no supporting entry");
+    processed = [...processed.slice(0, HIDDEN_STATE_LIMIT - 1), support];
+  }
 
   return {
+    audit_cursor_tag: auditCursorTag,
+    audit_cursor_validated: state.audit_cursor_validated,
     last_checked_tag: entry.tag,
     last_checked_at: entry.processed_at,
     processed,
@@ -179,28 +275,129 @@ function escapeTable(value: string): string {
 }
 
 function normalizeState(value: unknown): TrackerState {
-  if (!isRecord(value)) return emptyTrackerState();
+  if (!isRecord(value)) throw new TypeError("tracker state must be an object");
+  if (!Array.isArray(value.processed) || !value.processed.every(isTrackerEntry)) {
+    throw new TypeError("tracker processed entries are invalid");
+  }
+  if (
+    value.last_checked_tag !== null &&
+    typeof value.last_checked_tag !== "string"
+  ) {
+    throw new TypeError("tracker last_checked_tag is invalid");
+  }
+  if (
+    value.last_checked_at !== null &&
+    typeof value.last_checked_at !== "string"
+  ) {
+    throw new TypeError("tracker last_checked_at is invalid");
+  }
 
-  const processed = Array.isArray(value.processed)
-    ? value.processed.filter(isTrackerEntry).slice(0, HIDDEN_STATE_LIMIT)
-    : [];
+  const processed = value.processed.slice(
+    0,
+    HIDDEN_STATE_LIMIT,
+  ) as TrackerEntry[];
+  const lastCheckedTag = value.last_checked_tag as string | null;
+  const lastChecked =
+    lastCheckedTag === null
+      ? null
+      : processed.find((entry) => entry.tag === lastCheckedTag);
+  if (lastCheckedTag === null ? processed.length > 0 : !lastChecked) {
+    throw new TypeError("tracker last_checked_tag is inconsistent");
+  }
+
+  let auditCursorTag: string | null;
+  let auditCursorValidated: boolean;
+  if (value.audit_cursor_tag === undefined) {
+    auditCursorTag = deriveLegacyAuditCursor(processed);
+    auditCursorValidated = false;
+  } else if (
+    (value.audit_cursor_tag === null ||
+      typeof value.audit_cursor_tag === "string") &&
+    value.audit_cursor_validated === true
+  ) {
+    auditCursorTag = value.audit_cursor_tag;
+    auditCursorValidated = true;
+  } else {
+    throw new TypeError("tracker audit cursor is invalid");
+  }
+  if (auditCursorTag !== null && !isStableTag(auditCursorTag)) {
+    throw new TypeError("tracker audit_cursor_tag is invalid");
+  }
+  if (auditCursorTag === null && processed.length > 0) {
+    throw new TypeError("tracker audit_cursor_tag is missing");
+  }
+  if (
+    auditCursorTag !== null &&
+    !isSupportedAuditCursor(processed, auditCursorTag)
+  ) {
+    throw new TypeError("tracker audit_cursor_tag is inconsistent");
+  }
 
   return {
-    last_checked_tag:
-      typeof value.last_checked_tag === "string"
-        ? value.last_checked_tag
-        : null,
-    last_checked_at:
-      typeof value.last_checked_at === "string" ? value.last_checked_at : null,
+    audit_cursor_tag: auditCursorTag,
+    audit_cursor_validated: auditCursorValidated,
+    last_checked_tag: lastCheckedTag,
+    last_checked_at: value.last_checked_at as string | null,
     processed,
   };
 }
 
+function isSupportedAuditCursor(
+  processed: TrackerEntry[],
+  cursorTag: string,
+): boolean {
+  return processed.some((entry) =>
+    isAuditCursorSupportEntry(entry, cursorTag),
+  );
+}
+
+function isAuditCursorSupportEntry(
+  entry: TrackerEntry,
+  cursorTag: string,
+): boolean {
+  return (
+    (entry.tag === cursorTag && isTerminalOutcome(entry.outcome)) ||
+    entry.previous_tag === cursorTag
+  );
+}
+
+function deriveLegacyAuditCursor(processed: TrackerEntry[]): string | null {
+  const terminal = processed.filter((entry) =>
+    isTerminalOutcome(entry.outcome),
+  );
+  if (terminal.length === 0) {
+    const errorBaselines = [
+      ...new Set(
+        processed
+          .filter((entry) => entry.outcome === "error")
+          .map((entry) => entry.previous_tag),
+      ),
+    ];
+    if (errorBaselines.length > 1) {
+      throw new TypeError("legacy tracker error baselines are ambiguous");
+    }
+    return errorBaselines[0] ?? null;
+  }
+
+  const tags = terminal.map((entry) => entry.tag);
+  if (new Set(tags).size !== tags.length) {
+    throw new TypeError("legacy tracker terminal tags are duplicated");
+  }
+  const previousTags = new Set(terminal.map((entry) => entry.previous_tag));
+  const endpoints = tags.filter((tag) => !previousTags.has(tag));
+  if (endpoints.length !== 1) {
+    throw new TypeError("legacy tracker audit chain is ambiguous");
+  }
+  return endpoints[0] ?? null;
+}
+
 function isTrackerEntry(value: unknown): value is TrackerEntry {
   if (!isRecord(value)) return false;
   return (
     typeof value.tag === "string" &&
+    isStableTag(value.tag) &&
     typeof value.previous_tag === "string" &&
+    isStableTag(value.previous_tag) &&
     isVerdict(value.verdict) &&
     isOutcome(value.outcome) &&
     (typeof value.pr_url === "string" || value.pr_url === null) &&
@@ -211,6 +408,10 @@ function isTrackerEntry(value: unknown): value is TrackerEntry {
   );
 }
 
+function isStableTag(value: string): boolean {
+  return /^(?:rust-v|v)?\d+\.\d+\.\d+$/.test(value);
+}
+
 function isVerdict(value: unknown): value is Verdict {
   return (
     value === "no-op" ||

package/scripts/isolated-unit-tests.json

@@ -145,6 +145,16 @@
       "timeoutMs": 15000,
       "reason": "Uses a top-level Bun module mock for the backend client."
     },
+    {
+      "path": "src/agent/available-models.test.ts",
+      "timeoutMs": 15000,
+      "reason": "Mutates the backend singleton, shared model catalog cache, and Date.now while testing cache freshness."
+    },
+    {
+      "path": "src/tools/toolset-provider-resolution.test.ts",
+      "timeoutMs": 15000,
+      "reason": "Mutates the backend singleton and shared model catalog cache while exercising provider fallback behavior."
+    },
     {
       "path": "src/tools/toolset-client-tool-rule-cleanup.test.ts",
       "timeoutMs": 15000,
@@ -175,6 +185,11 @@
       "timeoutMs": 15000,
       "reason": "Mutates HOME and the remote-settings singleton while exercising cwd recovery persistence."
     },
+    {
+      "path": "src/websocket/listener/commands/model-toolset.test.ts",
+      "timeoutMs": 15000,
+      "reason": "Mutates the backend singleton and shared model catalog cache while asserting backend-native catalog metadata."
+    },
     {
       "path": "src/websocket/listener/protocol-ergonomics.test.ts",
       "timeoutMs": 15000,

package/scripts/pi-ai-watch/agent-watch.ts

@@ -0,0 +1,253 @@
+#!/usr/bin/env bun
+
+import { appendFileSync, writeFileSync } from "node:fs";
+import {
+  createIssueWithBody,
+  editIssueBody,
+  ensureLabels,
+  findIssueByExactTitle,
+  getIssueBody,
+  getPullRequestStatus,
+} from "./github.ts";
+import {
+  analyzePiAiRelease,
+  compareStableVersions,
+  DEFAULT_TARGET_REPO,
+  findNextStableRelease,
+  listStableReleases,
+  readInstalledVersion,
+} from "./release-analysis.ts";
+import {
+  advanceMergedPr,
+  getPendingPrForCursor,
+  hasCompletedRange,
+  initialTrackerState,
+  parseTrackerState,
+  renderTrackerBody,
+} from "./tracker.ts";
+
+const DEFAULT_TRACKER_TITLE = "pi-ai dependency upgrade tracker";
+const DEFAULT_ANALYSIS_FILE = "pi-ai-watch-analysis.json";
+
+interface Args {
+  dryRun: boolean;
+  previousVersion: string | null;
+  currentVersion: string | null;
+  repo: string;
+  trackerTitle: string;
+  analysisFile: string;
+}
+
+interface TrackerIssue {
+  number: number;
+  url: string;
+  body: string;
+}
+
+function parseArgs(argv: string[]): Args {
+  const args: Args = {
+    dryRun: false,
+    previousVersion: null,
+    currentVersion: null,
+    repo: DEFAULT_TARGET_REPO,
+    trackerTitle: DEFAULT_TRACKER_TITLE,
+    analysisFile: DEFAULT_ANALYSIS_FILE,
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "--dry-run") args.dryRun = true;
+    else if (argument === "--previous-version") {
+      args.previousVersion = argv[++index] ?? null;
+    } else if (argument === "--current-version") {
+      args.currentVersion = argv[++index] ?? null;
+    } else if (argument === "--repo") {
+      args.repo = argv[++index] ?? args.repo;
+    } else if (argument === "--tracker-title") {
+      args.trackerTitle = argv[++index] ?? args.trackerTitle;
+    } else if (argument === "--analysis-file") {
+      args.analysisFile = argv[++index] ?? args.analysisFile;
+    } else if (argument === "--help" || argument === "-h") {
+      console.log(
+        "Usage: bun scripts/pi-ai-watch/agent-watch.ts [--dry-run] [--previous-version VERSION] [--current-version VERSION] [--repo OWNER/REPO] [--tracker-title TITLE] [--analysis-file FILE]",
+      );
+      process.exit(0);
+    } else {
+      throw new Error(`Unknown argument: ${argument}`);
+    }
+  }
+  return args;
+}
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2));
+  const installedVersion = readInstalledVersion();
+  const tracker = ensureTrackerIssue(args, installedVersion);
+  let state = parseTrackerState(tracker.body);
+  const releases = await listStableReleases();
+  let previousVersion = args.previousVersion;
+  let currentVersion = args.currentVersion;
+  const isScheduledSelection = !previousVersion && !currentVersion;
+
+  if (isScheduledSelection) {
+    const pending = getPendingPrForCursor(state);
+    if (pending?.pr_url) {
+      const status = getPullRequestStatus(pending.pr_url);
+      if (status.state === "OPEN") {
+        console.log(`Waiting for pending pi-ai upgrade PR: ${status.url}`);
+        writeCommonOutputs(tracker, {
+          installedVersion,
+          previousVersion: pending.previous_version,
+          currentVersion: pending.version,
+        });
+        writeOutput("pending_pr_url", status.url);
+        writeOutput("should_run_agent", "false");
+        return;
+      }
+      if (status.state === "MERGED") {
+        if (compareStableVersions(installedVersion, pending.version) < 0) {
+          throw new Error(
+            `Merged pi-ai PR ${status.url} targets ${pending.version}, but main still declares ${installedVersion}`,
+          );
+        }
+        state = advanceMergedPr(state, pending.version);
+        if (!args.dryRun) {
+          editIssueBody(args.repo, tracker.number, renderTrackerBody(state));
+        }
+      } else {
+        console.log(
+          `Retrying ${pending.version}; prior PR was closed unmerged.`,
+        );
+      }
+    }
+
+    const next = findNextStableRelease(releases, state.audit_cursor_version);
+    if (!next) {
+      console.log(
+        `No stable pi-ai release after ${state.audit_cursor_version}.`,
+      );
+      writeCommonOutputs(tracker, {
+        installedVersion,
+        previousVersion: state.audit_cursor_version,
+        currentVersion: state.audit_cursor_version,
+      });
+      writeOutput("should_run_agent", "false");
+      return;
+    }
+    previousVersion = state.audit_cursor_version;
+    currentVersion = next.version;
+  }
+
+  const analysis = await analyzePiAiRelease({
+    previousVersion,
+    currentVersion,
+    installedVersion,
+    stableReleases: releases,
+  });
+  writeFileSync(args.analysisFile, `${JSON.stringify(analysis, null, 2)}\n`);
+  writeCommonOutputs(tracker, {
+    installedVersion,
+    previousVersion: analysis.previous_version,
+    currentVersion: analysis.current_version,
+  });
+  writeOutput("analysis_file", args.analysisFile);
+
+  if (
+    !args.dryRun &&
+    hasCompletedRange(
+      state,
+      analysis.previous_version,
+      analysis.current_version,
+    )
+  ) {
+    console.log(
+      `Already completed pi-ai review ${analysis.previous_version}...${analysis.current_version}.`,
+    );
+    writeOutput("should_run_agent", "false");
+    return;
+  }
+
+  if (args.dryRun) {
+    console.log(JSON.stringify(analysis, null, 2));
+    writeOutput("should_run_agent", "false");
+    return;
+  }
+
+  console.log(
+    `pi-ai ${analysis.previous_version}...${analysis.current_version} needs Amelia review.`,
+  );
+  writeOutput("should_run_agent", "true");
+}
+
+function ensureTrackerIssue(
+  args: Args,
+  installedVersion: string,
+): TrackerIssue {
+  const existing = args.dryRun
+    ? null
+    : findIssueByExactTitle(args.repo, args.trackerTitle);
+  if (existing) {
+    return {
+      number: existing.number,
+      url: `https://github.com/${args.repo}/issues/${existing.number}`,
+      body: getIssueBody(args.repo, existing.number),
+    };
+  }
+
+  const body = renderTrackerBody(initialTrackerState(installedVersion));
+  if (args.dryRun) {
+    return {
+      number: 0,
+      url: `https://github.com/${args.repo}/issues/0`,
+      body,
+    };
+  }
+
+  const labels = ["pi-ai-watch", "automation"];
+  ensureLabels(args.repo, labels);
+  const issueUrl = createIssueWithBody(
+    args.repo,
+    args.trackerTitle,
+    body,
+    labels,
+  );
+  return {
+    number: issueNumberFromUrl(issueUrl),
+    url: issueUrl,
+    body,
+  };
+}
+
+function issueNumberFromUrl(issueUrl: string): number {
+  const issueNumber = Number(issueUrl.trim().split("/").at(-1));
+  if (!Number.isInteger(issueNumber) || issueNumber <= 0) {
+    throw new Error(`Could not parse issue number from ${issueUrl}`);
+  }
+  return issueNumber;
+}
+
+function writeCommonOutputs(
+  tracker: TrackerIssue,
+  versions: {
+    installedVersion: string;
+    previousVersion: string;
+    currentVersion: string;
+  },
+): void {
+  writeOutput("tracker_issue", String(tracker.number));
+  writeOutput("tracker_issue_url", tracker.url);
+  writeOutput("installed_version", versions.installedVersion);
+  writeOutput("previous_version", versions.previousVersion);
+  writeOutput("current_version", versions.currentVersion);
+}
+
+function writeOutput(name: string, value: string): void {
+  const outputPath = process.env.GITHUB_OUTPUT;
+  if (!outputPath) return;
+  appendFileSync(outputPath, `${name}=${value}\n`);
+}
+
+main().catch((error) => {
+  console.error(error);
+  writeOutput("should_run_agent", "false");
+  process.exit(1);
+});