@letta-ai/letta-code 0.30.27 → 0.30.28

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

@@ -0,0 +1,148 @@
+import { describe, expect, test } from "bun:test";
+import {
+  emptyTrackerState,
+  hasProcessedCandidate,
+  parseTrackerState,
+  recordAnalysis,
+  renderTrackerBody,
+  serializeTrackerState,
+  TRACKER_ATTEMPT_HISTORY_LIMIT,
+  TRACKER_HISTORY_LIMIT,
+} from "./tracker.ts";
+import type { ClaudeWatchAnalysis } from "./types.ts";
+
+function analysis(candidateId = "2.1.0"): ClaudeWatchAnalysis {
+  return {
+    schema_version: 1,
+    candidate_id: candidateId,
+    previous_candidate_id: "2.0.0",
+    previous_version: "2.0.0",
+    current_version: candidateId,
+    is_bootstrap: false,
+    release_url: `https://example.test/releases/${candidateId}`,
+    release_notes_md: "notes",
+    npm_integrity: `sha512-package-${candidateId}`,
+    npm_published_at: "2026-08-01T00:00:00Z",
+    release_published_at: "2026-08-01T00:00:00Z",
+    dist_tags: { latest: candidateId, stable: candidateId, next: null },
+    docs_digest: `docs-${candidateId}`,
+    runtime_digest: `runtime-${candidateId}`,
+    docs_diff: {
+      added_pages: [],
+      removed_pages: [],
+      changed_pages: [],
+      watched_page_diffs: [],
+      tools: { added: [], removed: [], changed: [] },
+      cli: { added: [], removed: [], changed: [] },
+      settings: { added: [], removed: [], changed: [] },
+      env_vars: { added: [], removed: [], changed: [] },
+      permission_rules: { added: [], removed: [], changed: [] },
+    },
+    previous_runtime_snapshot: null,
+    runtime_snapshot: null,
+    runtime_diff: null,
+    verdict: "no-op",
+    verdict_reasons: [],
+    errors: [],
+    workflow_run_url: "https://example.test/actions/1",
+    state_base_sha: null,
+    state_snapshot_candidate_id: "2.0.0",
+  };
+}
+
+describe("Claude tracker", () => {
+  test("uses a Claude-only hidden marker and parses malformed state safely", () => {
+    expect(parseTrackerState("plain text")).toEqual(emptyTrackerState());
+    expect(
+      parseTrackerState("<!-- claude-watch-tracker-state\n{nope}\n-->"),
+    ).toEqual(emptyTrackerState());
+    expect(
+      parseTrackerState('<!-- codex-agent-watch-state\n{"processed":[]}\n-->'),
+    ).toEqual(emptyTrackerState());
+  });
+
+  test("round trips digests and terminal state", () => {
+    const state = recordAnalysis(emptyTrackerState(), {
+      analysis: analysis(),
+      outcome: "recorded_noop",
+      notes: "nothing watched changed",
+      stateCommitSha: "abc123",
+      processedAt: "2026-08-01T01:00:00Z",
+    });
+    expect(parseTrackerState(serializeTrackerState(state))).toEqual(state);
+    expect(state.processed[0]).toMatchObject({
+      candidate_id: "2.1.0",
+      package_digest: "sha512-package-2.1.0",
+      docs_digest: "docs-2.1.0",
+      runtime_digest: "runtime-2.1.0",
+      state_commit_sha: "abc123",
+    });
+    expect(hasProcessedCandidate(state, "2.1.0")).toBe(true);
+  });
+
+  test("keeps errors nonterminal and accumulates bounded retry history", () => {
+    let state = emptyTrackerState();
+    for (
+      let attempt = 0;
+      attempt < TRACKER_ATTEMPT_HISTORY_LIMIT + 4;
+      attempt++
+    ) {
+      state = recordAnalysis(state, {
+        analysis: analysis(),
+        outcome: "error",
+        notes: "retryable",
+        error: `failure ${attempt}`,
+        processedAt: `2026-08-01T01:${String(attempt).padStart(2, "0")}:00Z`,
+      });
+    }
+    expect(state.processed).toHaveLength(1);
+    expect(state.processed[0]?.attempts).toHaveLength(
+      TRACKER_ATTEMPT_HISTORY_LIMIT,
+    );
+    expect(state.processed[0]?.errors).toHaveLength(
+      TRACKER_ATTEMPT_HISTORY_LIMIT,
+    );
+    expect(hasProcessedCandidate(state, "2.1.0")).toBe(false);
+
+    state = recordAnalysis(state, {
+      analysis: { ...analysis(), verdict: "tool contract review needed" },
+      outcome: "pr_created",
+      notes: "fixed",
+      prUrl: "https://example.test/pull/1",
+      stateCommitSha: "def456",
+    });
+    expect(state.processed).toHaveLength(1);
+    expect(state.processed[0]?.attempts).toHaveLength(
+      TRACKER_ATTEMPT_HISTORY_LIMIT,
+    );
+    expect(hasProcessedCandidate(state, "2.1.0")).toBe(true);
+  });
+
+  test("bounds candidate history and shows only actionable non-noops", () => {
+    let state = emptyTrackerState();
+    for (let index = 0; index < TRACKER_HISTORY_LIMIT + 5; index++) {
+      state = recordAnalysis(state, {
+        analysis: analysis(`2.${index}.0`),
+        outcome: "recorded_noop",
+        notes: `noop ${index}`,
+      });
+    }
+    expect(state.processed).toHaveLength(TRACKER_HISTORY_LIMIT);
+    expect(renderTrackerBody(state)).toContain(
+      "_No actionable Claude changes recorded yet._",
+    );
+    expect(renderTrackerBody(state)).not.toContain("| 2.54.0 | no-op |");
+
+    const actionable = recordAnalysis(state, {
+      analysis: {
+        ...analysis("3.0.0"),
+        verdict: "harness behavior review needed",
+      },
+      outcome: "needs_human_review",
+      notes: "inspect hooks | carefully",
+    });
+    const body = renderTrackerBody(actionable);
+    expect(body).toContain("| 3.0.0 | harness behavior review needed |");
+    expect(body).toContain("inspect hooks \\| carefully");
+  });
+});

package/scripts/claude-watch/tracker.ts

@@ -0,0 +1,325 @@
+import type {
+  ClaudeWatchAnalysis,
+  ClaudeWatchOutcome,
+  ClaudeWatchVerdict,
+} from "./types.ts";
+
+/** Deliberately different from the Codex watcher marker. */
+export const CLAUDE_TRACKER_STATE_START = "<!-- claude-watch-tracker-state";
+export const CLAUDE_TRACKER_STATE_END = "-->";
+export const TRACKER_HISTORY_LIMIT = 50;
+export const TRACKER_ATTEMPT_HISTORY_LIMIT = 10;
+export const TRACKER_ERROR_HISTORY_LIMIT = 10;
+export const VISIBLE_ACTIONABLE_LIMIT = 20;
+
+const TERMINAL_OUTCOMES: ReadonlySet<ClaudeWatchOutcome> = new Set([
+  "recorded_noop",
+  "no_local_impact",
+  "pr_created",
+  "needs_human_review",
+]);
+
+export interface ClaudeTrackerAttempt {
+  attempted_at: string;
+  workflow_run_url: string;
+  outcome: ClaudeWatchOutcome;
+  error: string | null;
+}
+
+export interface ClaudeTrackerError {
+  occurred_at: string;
+  workflow_run_url: string;
+  message: string;
+}
+
+export interface ClaudeTrackerEntry {
+  candidate_id: string;
+  package_digest: string;
+  docs_digest: string;
+  runtime_digest: string | null;
+  verdict: ClaudeWatchVerdict;
+  outcome: ClaudeWatchOutcome;
+  pr_url: string | null;
+  notes: string;
+  processed_at: string;
+  workflow_run_url: string;
+  attempts: ClaudeTrackerAttempt[];
+  errors: ClaudeTrackerError[];
+  state_commit_sha: string | null;
+}
+
+export interface ClaudeTrackerState {
+  last_checked_candidate_id: string | null;
+  last_checked_at: string | null;
+  processed: ClaudeTrackerEntry[];
+}
+
+export interface RecordClaudeAnalysisOptions {
+  analysis: ClaudeWatchAnalysis;
+  outcome: ClaudeWatchOutcome;
+  notes: string;
+  prUrl?: string | null;
+  stateCommitSha?: string | null;
+  error?: string | null;
+  processedAt?: string;
+}
+
+export function emptyTrackerState(): ClaudeTrackerState {
+  return {
+    last_checked_candidate_id: null,
+    last_checked_at: null,
+    processed: [],
+  };
+}
+
+export function isTerminalOutcome(outcome: ClaudeWatchOutcome): boolean {
+  return TERMINAL_OUTCOMES.has(outcome);
+}
+
+export function findTrackerEntry(
+  state: ClaudeTrackerState,
+  candidateId: string,
+): ClaudeTrackerEntry | undefined {
+  return state.processed.find((entry) => entry.candidate_id === candidateId);
+}
+
+/** Errors are retryable and therefore do not count as processed. */
+export function hasProcessedCandidate(
+  state: ClaudeTrackerState,
+  candidateId: string,
+): boolean {
+  const entry = findTrackerEntry(state, candidateId);
+  return entry !== undefined && isTerminalOutcome(entry.outcome);
+}
+
+export function parseTrackerState(body: string): ClaudeTrackerState {
+  const start = body.indexOf(CLAUDE_TRACKER_STATE_START);
+  if (start < 0) return emptyTrackerState();
+  const jsonStart = start + CLAUDE_TRACKER_STATE_START.length;
+  const end = body.indexOf(CLAUDE_TRACKER_STATE_END, jsonStart);
+  if (end < 0) return emptyTrackerState();
+  try {
+    return normalizeState(JSON.parse(body.slice(jsonStart, end).trim()));
+  } catch {
+    return emptyTrackerState();
+  }
+}
+
+export function serializeTrackerState(state: ClaudeTrackerState): string {
+  return `${CLAUDE_TRACKER_STATE_START}\n${JSON.stringify(normalizeState(state), null, 2)}\n${CLAUDE_TRACKER_STATE_END}`;
+}
+
+export function recordAnalysis(
+  state: ClaudeTrackerState,
+  options: RecordClaudeAnalysisOptions,
+): ClaudeTrackerState {
+  const processedAt = options.processedAt ?? new Date().toISOString();
+  const previous = findTrackerEntry(state, options.analysis.candidate_id);
+  const error = options.error ?? options.analysis.errors.at(-1) ?? null;
+  const attempt: ClaudeTrackerAttempt = {
+    attempted_at: processedAt,
+    workflow_run_url: options.analysis.workflow_run_url,
+    outcome: options.outcome,
+    error,
+  };
+  const errors = error
+    ? [
+        {
+          occurred_at: processedAt,
+          workflow_run_url: options.analysis.workflow_run_url,
+          message: error,
+        },
+        ...(previous?.errors ?? []),
+      ].slice(0, TRACKER_ERROR_HISTORY_LIMIT)
+    : (previous?.errors ?? []);
+
+  return upsertTrackerEntry(state, {
+    candidate_id: options.analysis.candidate_id,
+    package_digest: options.analysis.npm_integrity,
+    docs_digest: options.analysis.docs_digest,
+    runtime_digest: options.analysis.runtime_digest,
+    verdict: options.analysis.verdict,
+    outcome: options.outcome,
+    pr_url: options.prUrl ?? previous?.pr_url ?? null,
+    notes: options.notes,
+    processed_at: processedAt,
+    workflow_run_url: options.analysis.workflow_run_url,
+    attempts: [attempt, ...(previous?.attempts ?? [])].slice(
+      0,
+      TRACKER_ATTEMPT_HISTORY_LIMIT,
+    ),
+    errors,
+    state_commit_sha:
+      options.stateCommitSha ?? previous?.state_commit_sha ?? null,
+  });
+}
+
+/** Upserts by candidate id, so retries never create duplicate history rows. */
+export function upsertTrackerEntry(
+  state: ClaudeTrackerState,
+  entry: ClaudeTrackerEntry,
+): ClaudeTrackerState {
+  const normalizedEntry = normalizeEntry(entry);
+  if (!normalizedEntry) return normalizeState(state);
+  return {
+    last_checked_candidate_id: normalizedEntry.candidate_id,
+    last_checked_at: normalizedEntry.processed_at,
+    processed: [
+      normalizedEntry,
+      ...normalizeState(state).processed.filter(
+        (item) => item.candidate_id !== normalizedEntry.candidate_id,
+      ),
+    ].slice(0, TRACKER_HISTORY_LIMIT),
+  };
+}
+
+/** True only for entries useful to a human; no-op and transient errors stay hidden. */
+export function isActionableEntry(entry: ClaudeTrackerEntry): boolean {
+  return (
+    entry.outcome === "pr_created" ||
+    entry.outcome === "needs_human_review" ||
+    (entry.outcome === "no_local_impact" && entry.verdict !== "no-op")
+  );
+}
+
+export function renderTrackerBody(state: ClaudeTrackerState): string {
+  const normalized = normalizeState(state);
+  const rows = normalized.processed
+    .filter(isActionableEntry)
+    .slice(0, VISIBLE_ACTIONABLE_LIMIT);
+  const table =
+    rows.length === 0
+      ? "_No actionable Claude changes recorded yet._"
+      : [
+          "| Candidate | Verdict | Outcome | PR | Notes |",
+          "|---|---|---|---|---|",
+          ...rows.map(
+            (entry) =>
+              `| ${escapeTable(entry.candidate_id)} | ${escapeTable(entry.verdict)} | ${escapeTable(entry.outcome)} | ${entry.pr_url ? `[PR](${entry.pr_url})` : "-"} | ${escapeTable(entry.notes)} |`,
+          ),
+        ].join("\n");
+  const checked =
+    normalized.last_checked_candidate_id && normalized.last_checked_at
+      ? `_Last checked: ${normalized.last_checked_candidate_id} at ${normalized.last_checked_at}._`
+      : "_Last checked: never._";
+  return [
+    "Central tracker for Claude upstream drift monitoring.",
+    "",
+    checked,
+    "",
+    "## Recent actionable candidates",
+    "",
+    table,
+    "",
+    "## Hidden state",
+    "",
+    "The workflow uses the Claude-specific hidden JSON block below for dedupe and retries.",
+    "",
+    serializeTrackerState(normalized),
+    "",
+  ].join("\n");
+}
+
+function normalizeState(value: unknown): ClaudeTrackerState {
+  if (!isRecord(value)) return emptyTrackerState();
+  const processed = Array.isArray(value.processed)
+    ? value.processed
+        .map(normalizeEntry)
+        .filter((entry): entry is ClaudeTrackerEntry => entry !== null)
+        .filter(
+          (entry, index, all) =>
+            all.findIndex(
+              (candidate) => candidate.candidate_id === entry.candidate_id,
+            ) === index,
+        )
+        .slice(0, TRACKER_HISTORY_LIMIT)
+    : [];
+  return {
+    last_checked_candidate_id:
+      typeof value.last_checked_candidate_id === "string"
+        ? value.last_checked_candidate_id
+        : null,
+    last_checked_at:
+      typeof value.last_checked_at === "string" ? value.last_checked_at : null,
+    processed,
+  };
+}
+
+function normalizeEntry(value: unknown): ClaudeTrackerEntry | null {
+  if (
+    !isRecord(value) ||
+    typeof value.candidate_id !== "string" ||
+    typeof value.package_digest !== "string" ||
+    typeof value.docs_digest !== "string" ||
+    !(
+      typeof value.runtime_digest === "string" || value.runtime_digest === null
+    ) ||
+    !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.workflow_run_url !== "string" ||
+    !(
+      typeof value.state_commit_sha === "string" ||
+      value.state_commit_sha === null
+    )
+  ) {
+    return null;
+  }
+  const attempts = Array.isArray(value.attempts)
+    ? value.attempts.filter(isAttempt).slice(0, TRACKER_ATTEMPT_HISTORY_LIMIT)
+    : [];
+  const errors = Array.isArray(value.errors)
+    ? value.errors.filter(isError).slice(0, TRACKER_ERROR_HISTORY_LIMIT)
+    : [];
+  return { ...value, attempts, errors } as ClaudeTrackerEntry;
+}
+
+function isAttempt(value: unknown): value is ClaudeTrackerAttempt {
+  return (
+    isRecord(value) &&
+    typeof value.attempted_at === "string" &&
+    typeof value.workflow_run_url === "string" &&
+    isOutcome(value.outcome) &&
+    (typeof value.error === "string" || value.error === null)
+  );
+}
+
+function isError(value: unknown): value is ClaudeTrackerError {
+  return (
+    isRecord(value) &&
+    typeof value.occurred_at === "string" &&
+    typeof value.workflow_run_url === "string" &&
+    typeof value.message === "string"
+  );
+}
+
+function isVerdict(value: unknown): value is ClaudeWatchVerdict {
+  return (
+    value === "no-op" ||
+    value === "prompt review needed" ||
+    value === "tool contract review needed" ||
+    value === "tool surface review needed" ||
+    value === "harness behavior review needed" ||
+    value === "manual review required"
+  );
+}
+
+function isOutcome(value: unknown): value is ClaudeWatchOutcome {
+  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;
+}
+
+function escapeTable(value: string): string {
+  return value.replaceAll("|", "\\|").replaceAll("\n", " ");
+}

package/scripts/claude-watch/types.ts

@@ -0,0 +1,186 @@
+export const CLAUDE_WATCH_STATE_SCHEMA_VERSION = 2;
+
+export type ClaudeWatchVerdict =
+  | "no-op"
+  | "prompt review needed"
+  | "tool contract review needed"
+  | "tool surface review needed"
+  | "harness behavior review needed"
+  | "manual review required";
+
+export type ClaudeWatchOutcome =
+  | "recorded_noop"
+  | "no_local_impact"
+  | "pr_created"
+  | "needs_human_review"
+  | "error";
+
+export interface ClaudeGitHubRelease {
+  tag_name: string;
+  draft: boolean;
+  prerelease: boolean;
+  html_url: string;
+  body: string | null;
+  published_at: string | null;
+}
+
+export interface ClaudeNpmVersion {
+  version: string;
+  published_at: string;
+  integrity: string;
+  tarball_url: string;
+}
+
+export interface ClaudeNpmMetadata {
+  dist_tags: {
+    latest: string;
+    stable: string | null;
+    next: string | null;
+  };
+  versions: ClaudeNpmVersion[];
+}
+
+export interface ClaudeReleaseCandidate extends ClaudeNpmVersion {
+  release_url: string;
+  release_notes_md: string;
+  release_published_at: string;
+  dist_tags: ClaudeNpmMetadata["dist_tags"];
+}
+
+export interface ClaudeDocsPageSnapshot {
+  url: string;
+  hash: string;
+  watched: boolean;
+  source_path: string | null;
+}
+
+export interface ClaudeDocsSnapshot {
+  index_url: string;
+  index_hash: string;
+  digest: string;
+  full_scan: boolean;
+  scanned_at: string;
+  pages: Record<string, ClaudeDocsPageSnapshot>;
+}
+
+export interface ClaudeNamedChange {
+  added: string[];
+  removed: string[];
+  changed: string[];
+}
+
+export interface ClaudeDocsPageDiff {
+  url: string;
+  source_path: string | null;
+  preview: string;
+  truncated: boolean;
+}
+
+export interface ClaudeDocsDiff {
+  added_pages: string[];
+  removed_pages: string[];
+  changed_pages: string[];
+  watched_page_diffs: ClaudeDocsPageDiff[];
+  tools: ClaudeNamedChange;
+  cli: ClaudeNamedChange;
+  settings: ClaudeNamedChange;
+  env_vars: ClaudeNamedChange;
+  permission_rules: ClaudeNamedChange;
+}
+
+export interface ClaudeProbeObservation {
+  name: string;
+  status: "passed" | "inconclusive" | "failed" | "skipped";
+  attempts: number;
+  assertions: Record<string, boolean | string | null>;
+  tool_calls: Array<{
+    name: string;
+    input: unknown;
+  }>;
+  tool_results: string[];
+  filesystem_changes: string[];
+  error: string | null;
+}
+
+export interface ClaudeRuntimeSnapshot {
+  probe_contract_version: number;
+  version: string;
+  version_output: string;
+  help_text: string;
+  help_hash: string;
+  doctor: {
+    exit_code: number;
+    summary: string;
+  };
+  auto_mode_defaults: unknown | null;
+  init: {
+    tools: string[];
+    model: string | null;
+    capabilities: unknown | null;
+    stable_fields: Record<string, unknown>;
+  } | null;
+  event_inventory: string[];
+  probes: ClaudeProbeObservation[];
+  digest: string;
+}
+
+export interface ClaudeRuntimeDiff {
+  tools_added: string[];
+  tools_removed: string[];
+  help_changed: boolean;
+  help_lines_added: string[];
+  help_lines_removed: string[];
+  doctor_changed: boolean;
+  init_changed: boolean;
+  auto_mode_defaults_changed: boolean;
+  event_types_added: string[];
+  event_types_removed: string[];
+  changed_probes: string[];
+}
+
+export interface ClaudeWatchStateSnapshot {
+  schema_version: number;
+  candidate_id: string;
+  package_version: string;
+  npm_integrity: string;
+  npm_published_at: string;
+  release_url: string;
+  release_notes_md: string;
+  release_published_at: string;
+  dist_tags: ClaudeNpmMetadata["dist_tags"];
+  docs: ClaudeDocsSnapshot;
+  runtime: ClaudeRuntimeSnapshot | null;
+  fetched_at: string;
+  workflow_run_url: string;
+  /** Physical parent on the durable state branch. */
+  state_commit_parent: string | null;
+  /** Snapshot used for semantic diffing; undefined legacy snapshots use the physical parent. */
+  analysis_parent_sha?: string | null;
+}
+
+export interface ClaudeWatchAnalysis {
+  schema_version: number;
+  candidate_id: string;
+  previous_candidate_id: string | null;
+  previous_version: string | null;
+  current_version: string;
+  is_bootstrap: boolean;
+  release_url: string;
+  release_notes_md: string;
+  npm_integrity: string;
+  npm_published_at: string;
+  release_published_at: string;
+  dist_tags: ClaudeNpmMetadata["dist_tags"];
+  docs_digest: string;
+  runtime_digest: string | null;
+  docs_diff: ClaudeDocsDiff;
+  previous_runtime_snapshot: ClaudeRuntimeSnapshot | null;
+  runtime_snapshot: ClaudeRuntimeSnapshot | null;
+  runtime_diff: ClaudeRuntimeDiff | null;
+  verdict: ClaudeWatchVerdict;
+  verdict_reasons: string[];
+  errors: string[];
+  workflow_run_url: string;
+  state_base_sha: string | null;
+  state_snapshot_candidate_id: string | null;
+}