@letta-ai/letta-code 0.27.20 → 0.27.22

package/scripts/codex-watch/tracker.ts

@@ -0,0 +1,238 @@
+import type { Verdict } from "./diff-models-json.ts";
+import type { CodexWatchAnalysis } from "./release-analysis.ts";
+
+const STATE_START = "<!-- codex-agent-watch-state";
+const STATE_END = "-->";
+const HIDDEN_STATE_LIMIT = 50;
+const VISIBLE_INTERESTING_LIMIT = 20;
+
+export type TrackerOutcome =
+  | "recorded_noop"
+  | "no_local_impact"
+  | "pr_created"
+  | "needs_human_review"
+  | "error";
+
+export interface TrackerEntry {
+  tag: string;
+  previous_tag: string;
+  verdict: Verdict;
+  outcome: TrackerOutcome;
+  pr_url: string | null;
+  notes: string;
+  processed_at: string;
+  compare_url: string;
+  workflow_run_url: string;
+}
+
+export interface TrackerState {
+  last_checked_tag: string | null;
+  last_checked_at: string | null;
+  processed: TrackerEntry[];
+}
+
+export interface RecordAnalysisOptions {
+  analysis: CodexWatchAnalysis;
+  outcome: TrackerOutcome;
+  notes: string;
+  prUrl?: string | null;
+  processedAt?: string;
+}
+
+export function emptyTrackerState(): TrackerState {
+  return {
+    last_checked_tag: null,
+    last_checked_at: null,
+    processed: [],
+  };
+}
+
+export function parseTrackerState(body: string): TrackerState {
+  const start = body.indexOf(STATE_START);
+  if (start === -1) return emptyTrackerState();
+
+  const jsonStart = start + STATE_START.length;
+  const end = body.indexOf(STATE_END, jsonStart);
+  if (end === -1) return emptyTrackerState();
+
+  try {
+    return normalizeState(JSON.parse(body.slice(jsonStart, end).trim()));
+  } catch {
+    return emptyTrackerState();
+  }
+}
+
+export function hasProcessedTag(state: TrackerState, tag: string): boolean {
+  return state.processed.some((entry) => entry.tag === tag);
+}
+
+export function recordAnalysis(
+  state: TrackerState,
+  options: RecordAnalysisOptions,
+): TrackerState {
+  const processedAt = options.processedAt ?? new Date().toISOString();
+  return upsertTrackerEntry(state, {
+    tag: options.analysis.current_tag,
+    previous_tag: options.analysis.previous_tag,
+    verdict: options.analysis.verdict,
+    outcome: options.outcome,
+    pr_url: options.prUrl ?? null,
+    notes: options.notes,
+    processed_at: processedAt,
+    compare_url: options.analysis.compare_url,
+    workflow_run_url: options.analysis.workflow_run_url,
+  });
+}
+
+export function upsertTrackerEntry(
+  state: TrackerState,
+  entry: TrackerEntry,
+): TrackerState {
+  const processed = [
+    entry,
+    ...state.processed.filter((existing) => existing.tag !== entry.tag),
+  ].slice(0, HIDDEN_STATE_LIMIT);
+
+  return {
+    last_checked_tag: entry.tag,
+    last_checked_at: entry.processed_at,
+    processed,
+  };
+}
+
+export function renderTrackerBody(state: TrackerState): string {
+  const normalized = normalizeState(state);
+  const parts: string[] = [
+    "Central tracker for the Amelia-driven Codex upstream drift watch experiment.",
+    "",
+    "The legacy per-release `codex-release-watch.yml` issue workflow is still enabled as the baseline while this tracker bakes off the new automation path.",
+    "",
+    renderLastChecked(normalized),
+    "",
+    "## Recent actionable releases",
+    "",
+    renderInterestingTable(normalized),
+    "",
+    "## Hidden state",
+    "",
+    "The workflow uses the hidden JSON block below for dedupe and recent history.",
+    "",
+    serializeTrackerState(normalized),
+  ];
+  return `${parts.join("\n")}\n`;
+}
+
+export function serializeTrackerState(state: TrackerState): string {
+  const normalized = normalizeState(state);
+  return `${STATE_START}\n${JSON.stringify(normalized, null, 2)}\n${STATE_END}`;
+}
+
+export function isInterestingEntry(entry: TrackerEntry): boolean {
+  return entry.verdict !== "no-op" || entry.outcome !== "recorded_noop";
+}
+
+function renderLastChecked(state: TrackerState): string {
+  if (!state.last_checked_tag || !state.last_checked_at) {
+    return "_Last checked: never._";
+  }
+
+  const latest = state.processed.find(
+    (entry) => entry.tag === state.last_checked_tag,
+  );
+  const suffix = latest ? `, ${statusSummary(latest)}.` : ".";
+  return `_Last checked: ${state.last_checked_tag} at ${state.last_checked_at}${suffix}_`;
+}
+
+function renderInterestingTable(state: TrackerState): string {
+  const interesting = state.processed
+    .filter(isInterestingEntry)
+    .slice(0, VISIBLE_INTERESTING_LIMIT);
+
+  if (interesting.length === 0) {
+    return "_No actionable releases recorded yet._";
+  }
+
+  const rows = [
+    "| Release | Verdict | Outcome | PR | Notes |",
+    "|---|---|---|---|---|",
+  ];
+  for (const entry of interesting) {
+    rows.push(
+      `| [${escapeTable(entry.tag)}](${entry.compare_url}) | ${escapeTable(entry.verdict)} | ${escapeTable(entry.outcome)} | ${renderPr(entry.pr_url)} | ${escapeTable(entry.notes)} |`,
+    );
+  }
+  return rows.join("\n");
+}
+
+function statusSummary(entry: TrackerEntry): string {
+  if (entry.outcome === "recorded_noop") return "no watched changes";
+  if (entry.outcome === "pr_created" && entry.pr_url) {
+    return `PR created: ${entry.pr_url}`;
+  }
+  return entry.notes || entry.outcome;
+}
+
+function renderPr(prUrl: string | null): string {
+  return prUrl ? `[PR](${prUrl})` : "-";
+}
+
+function escapeTable(value: string): string {
+  return value.replaceAll("|", "\\|").replaceAll("\n", " ");
+}
+
+function normalizeState(value: unknown): TrackerState {
+  if (!isRecord(value)) return emptyTrackerState();
+
+  const processed = Array.isArray(value.processed)
+    ? value.processed.filter(isTrackerEntry).slice(0, HIDDEN_STATE_LIMIT)
+    : [];
+
+  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,
+    processed,
+  };
+}
+
+function isTrackerEntry(value: unknown): value is TrackerEntry {
+  if (!isRecord(value)) return false;
+  return (
+    typeof value.tag === "string" &&
+    typeof value.previous_tag === "string" &&
+    isVerdict(value.verdict) &&
+    isOutcome(value.outcome) &&
+    (typeof value.pr_url === "string" || value.pr_url === null) &&
+    typeof value.notes === "string" &&
+    typeof value.processed_at === "string" &&
+    typeof value.compare_url === "string" &&
+    typeof value.workflow_run_url === "string"
+  );
+}
+
+function isVerdict(value: unknown): value is Verdict {
+  return (
+    value === "no-op" ||
+    value === "prompt-only update" ||
+    value === "tool-schema update needed" ||
+    value === "tool-surface review needed" ||
+    value === "manual review required"
+  );
+}
+
+function isOutcome(value: unknown): value is TrackerOutcome {
+  return (
+    value === "recorded_noop" ||
+    value === "no_local_impact" ||
+    value === "pr_created" ||
+    value === "needs_human_review" ||
+    value === "error"
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}

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

@@ -0,0 +1,131 @@
+#!/usr/bin/env bun
+/**
+ * Records an Amelia Codex watch outcome in the central tracker issue.
+ *
+ * Usage:
+ *   bun scripts/codex-watch/update-tracker.ts --tracker-issue 123 --analysis-file /tmp/analysis.json --outcome no_local_impact --notes "upstream-only"
+ */
+
+import { readFileSync } from "node:fs";
+import { editIssueBody, getIssueBody } from "./github.ts";
+import {
+  type CodexWatchAnalysis,
+  DEFAULT_TARGET_REPO,
+} from "./release-analysis.ts";
+import {
+  parseTrackerState,
+  recordAnalysis,
+  renderTrackerBody,
+  type TrackerOutcome,
+} from "./tracker.ts";
+
+interface Args {
+  repo: string;
+  trackerIssue: number | null;
+  analysisFile: string | null;
+  outcome: TrackerOutcome | null;
+  notes: string;
+  prUrl: string | null;
+  dryRun: boolean;
+}
+
+function parseArgs(argv: string[]): Args {
+  const args: Args = {
+    repo: DEFAULT_TARGET_REPO,
+    trackerIssue: null,
+    analysisFile: null,
+    outcome: null,
+    notes: "",
+    prUrl: null,
+    dryRun: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--repo") args.repo = argv[++i] ?? args.repo;
+    else if (a === "--tracker-issue") {
+      args.trackerIssue = Number(argv[++i]);
+    } else if (a === "--analysis-file") args.analysisFile = argv[++i] ?? null;
+    else if (a === "--outcome") args.outcome = parseOutcome(argv[++i]);
+    else if (a === "--notes") args.notes = argv[++i] ?? "";
+    else if (a === "--pr-url") args.prUrl = argv[++i] ?? null;
+    else if (a === "--dry-run") args.dryRun = true;
+    else if (a === "--help" || a === "-h") {
+      console.log(
+        "Usage: bun scripts/codex-watch/update-tracker.ts --tracker-issue ISSUE --analysis-file FILE --outcome OUTCOME [--notes TEXT] [--pr-url URL] [--repo OWNER/REPO] [--dry-run]",
+      );
+      process.exit(0);
+    } else {
+      throw new Error(`Unknown argument: ${a}`);
+    }
+  }
+
+  if (!args.trackerIssue || Number.isNaN(args.trackerIssue)) {
+    throw new Error("--tracker-issue is required");
+  }
+  if (!args.analysisFile) throw new Error("--analysis-file is required");
+  if (!args.outcome) throw new Error("--outcome is required");
+  if (args.outcome === "pr_created" && !args.prUrl) {
+    throw new Error("--pr-url is required when --outcome pr_created");
+  }
+
+  return args;
+}
+
+function parseOutcome(value: string | undefined): TrackerOutcome {
+  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}`);
+}
+
+function readAnalysis(path: string): CodexWatchAnalysis {
+  return JSON.parse(readFileSync(path, "utf8")) as CodexWatchAnalysis;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const analysis = readAnalysis(args.analysisFile as string);
+  const body = getIssueBody(args.repo, args.trackerIssue as number);
+  const state = parseTrackerState(body);
+  const next = recordAnalysis(state, {
+    analysis,
+    outcome: args.outcome as TrackerOutcome,
+    notes: args.notes || defaultNotes(args.outcome as TrackerOutcome),
+    prUrl: args.prUrl,
+  });
+  const nextBody = renderTrackerBody(next);
+
+  if (args.dryRun) {
+    console.log(nextBody);
+    return;
+  }
+
+  editIssueBody(args.repo, args.trackerIssue as number, nextBody);
+  console.log(
+    `Recorded ${analysis.current_tag} as ${args.outcome} in #${args.trackerIssue}`,
+  );
+}
+
+function defaultNotes(outcome: TrackerOutcome): string {
+  switch (outcome) {
+    case "recorded_noop":
+      return "no watched tool-surface changes detected";
+    case "no_local_impact":
+      return "reviewed; no local Letta Code mirror impact";
+    case "pr_created":
+      return "opened PR for local mirror update";
+    case "needs_human_review":
+      return "needs human review";
+    case "error":
+      return "automation hit an error";
+  }
+}
+
+main();