@letta-ai/letta-code 0.30.31 → 0.31.0

package/scripts/pi-ai-watch/release-analysis.ts

@@ -42,11 +42,14 @@ export interface PiAiWatchAnalysis {
   installed_version: string;
   previous_version: string;
   current_version: string;
-  is_adjacent_release: boolean;
+  is_latest_release: boolean;
   published_at: string;
   integrity: string | null;
   tarball_url: string | null;
+  previous_git_head: string | null;
   git_head: string | null;
+  previous_tag_commit: string;
+  current_tag_commit: string;
   release_url: string;
   compare_url: string;
   changelog_md: string;
@@ -79,6 +82,11 @@ export async function analyzePiAiRelease(
       `Could not find previous pi-ai release before ${current.version}`,
     );
   }
+  if (compareStableVersions(previous.version, current.version) >= 0) {
+    throw new Error(
+      `Previous pi-ai release ${previous.version} must precede ${current.version}`,
+    );
+  }
 
   const installedVersion = options.installedVersion ?? readInstalledVersion();
   const previousTag = `v${previous.version}`;
@@ -86,11 +94,13 @@ export async function analyzePiAiRelease(
   const temp = mkdtempSync(join(tmpdir(), "pi-ai-watch-"));
   try {
     const repoDir = clonePi(temp);
-    fetchTag(repoDir, previousTag);
-    fetchTag(repoDir, currentTag);
-    verifyTagMatchesPackage(repoDir, previousTag, previous);
-    verifyTagMatchesPackage(repoDir, currentTag, current);
-    const changelog = showFile(repoDir, currentTag, "packages/ai/CHANGELOG.md");
+    const previousSource = resolveReleaseSource(repoDir, previousTag, previous);
+    const currentSource = resolveReleaseSource(repoDir, currentTag, current);
+    const changelog = showFile(
+      repoDir,
+      currentSource.sourceCommit,
+      "packages/ai/CHANGELOG.md",
+    );
     if (changelog === null) {
       throw new Error(`packages/ai/CHANGELOG.md is missing at ${currentTag}`);
     }
@@ -100,24 +110,35 @@ export async function analyzePiAiRelease(
       installed_version: installedVersion,
       previous_version: previous.version,
       current_version: current.version,
-      is_adjacent_release: areAdjacentStableReleases(
-        releases,
-        previous.version,
-        current.version,
-      ),
+      is_latest_release: current.version === releases.at(-1)?.version,
       published_at: current.published_at,
       integrity: current.integrity,
       tarball_url: current.tarball_url,
+      previous_git_head: previous.git_head,
       git_head: current.git_head,
+      previous_tag_commit: previousSource.tagCommit,
+      current_tag_commit: currentSource.tagCommit,
       release_url: `https://github.com/${PI_AI_REPO}/releases/tag/${currentTag}`,
-      compare_url: `https://github.com/${PI_AI_REPO}/compare/${previousTag}...${currentTag}`,
-      changelog_md: extractChangelogSection(changelog, current.version),
-      changed_files: changedFiles(repoDir, previousTag, currentTag),
-      diff_stat: diffStat(repoDir, previousTag, currentTag),
+      compare_url: `https://github.com/${PI_AI_REPO}/compare/${previousSource.sourceCommit}...${currentSource.sourceCommit}`,
+      changelog_md: extractChangelogRange(
+        changelog,
+        previous.version,
+        current.version,
+      ),
+      changed_files: changedFiles(
+        repoDir,
+        previousSource.sourceCommit,
+        currentSource.sourceCommit,
+      ),
+      diff_stat: diffStat(
+        repoDir,
+        previousSource.sourceCommit,
+        currentSource.sourceCommit,
+      ),
       package_json_diff: diffPreview(
         repoDir,
-        previousTag,
-        currentTag,
+        previousSource.sourceCommit,
+        currentSource.sourceCommit,
         "packages/ai/package.json",
       ),
       workflow_run_url: workflowRunUrl(),
@@ -182,7 +203,7 @@ export function readInstalledVersion(lockfilePath = "bun.lock"): string {
   return match[1];
 }
 
-export function findNextStableRelease(
+export function findLatestStableReleaseAfter(
   releases: PackageRelease[],
   cursorVersion: string,
 ): PackageRelease | null {
@@ -192,33 +213,33 @@ export function findNextStableRelease(
   if (index < 0) {
     throw new Error(`Could not find pi-ai cursor release ${cursorVersion}`);
   }
-  return releases[index + 1] ?? null;
+  return index === releases.length - 1 ? null : (releases.at(-1) ?? null);
 }
 
-export function areAdjacentStableReleases(
-  releases: PackageRelease[],
+export function extractChangelogRange(
+  changelog: string,
   previousVersion: string,
   currentVersion: string,
-): boolean {
-  return (
-    findPreviousStableRelease(releases, currentVersion)?.version ===
-    previousVersion
-  );
-}
-
-export function extractChangelogSection(
-  changelog: string,
-  version: string,
 ): string {
-  const heading = new RegExp(`^## \\[${escapeRegExp(version)}\\].*$`, "m");
-  const match = heading.exec(changelog);
-  if (!match)
-    throw new Error(`Could not find pi-ai changelog section ${version}`);
-  const start = match.index;
-  const remaining = changelog.slice(start + match[0].length);
-  const next = /^## \[/m.exec(remaining);
-  const end = next ? start + match[0].length + next.index : changelog.length;
-  return changelog.slice(start, end).trim();
+  const currentHeading = new RegExp(
+    `^## \\[${escapeRegExp(currentVersion)}\\].*$`,
+    "m",
+  ).exec(changelog);
+  if (!currentHeading) {
+    throw new Error(`Could not find pi-ai changelog section ${currentVersion}`);
+  }
+  const previousHeading = new RegExp(
+    `^## \\[${escapeRegExp(previousVersion)}\\].*$`,
+    "m",
+  ).exec(changelog.slice(currentHeading.index + currentHeading[0].length));
+  if (!previousHeading) {
+    throw new Error(
+      `Could not find pi-ai changelog section ${previousVersion}`,
+    );
+  }
+  const end =
+    currentHeading.index + currentHeading[0].length + previousHeading.index;
+  return changelog.slice(currentHeading.index, end).trim();
 }
 
 function findPreviousStableRelease(
@@ -276,18 +297,37 @@ function fetchTag(repoDir: string, tag: string): void {
   );
 }
 
-function verifyTagMatchesPackage(
+function resolveReleaseSource(
   repoDir: string,
   tag: string,
   release: PackageRelease,
-): void {
-  if (!release.git_head) return;
+): { sourceCommit: string; tagCommit: string } {
+  fetchTag(repoDir, tag);
   const tagCommit = git(["rev-list", "-n", "1", tag], repoDir).trim();
-  if (tagCommit !== release.git_head) {
+  const sourceCommit = release.git_head ?? tagCommit;
+  if (sourceCommit !== tagCommit) {
+    fetchCommit(repoDir, sourceCommit);
+  }
+  const packageJson = showFile(
+    repoDir,
+    sourceCommit,
+    "packages/ai/package.json",
+  );
+  if (packageJson === null) {
+    throw new Error(`packages/ai/package.json is missing at ${sourceCommit}`);
+  }
+  const sourceVersion = (JSON.parse(packageJson) as { version?: unknown })
+    .version;
+  if (sourceVersion !== release.version) {
     throw new Error(
-      `pi-ai npm ${release.version} gitHead ${release.git_head} does not match ${tag} commit ${tagCommit}`,
+      `pi-ai npm ${release.version} source ${sourceCommit} declares version ${String(sourceVersion)}`,
     );
   }
+  return { sourceCommit, tagCommit };
+}
+
+function fetchCommit(repoDir: string, commit: string): void {
+  git(["fetch", "--filter=blob:none", "origin", commit], repoDir);
 }
 
 function showFile(repoDir: string, tag: string, path: string): string | null {

package/scripts/pi-ai-watch/tracker.test.ts

@@ -1,7 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import type { PiAiWatchAnalysis } from "./release-analysis.ts";
 import {
-  advanceMergedPr,
   getPendingPrForCursor,
   hasCompletedRange,
   hasRecordedOutcome,
@@ -19,17 +18,18 @@ describe("pi-ai watch tracker", () => {
 
   test("advances after a no-upgrade decision", () => {
     const state = recordAnalysis(initialTrackerState("0.82.1"), {
-      analysis: analysis("0.82.1", "0.83.0"),
+      analysis: analysis("0.82.1", "0.84.0"),
       outcome: "no_upgrade",
       notes: "upstream-only provider change",
       processedAt: "2026-08-21T00:00:00Z",
     });
-    expect(state.audit_cursor_version).toBe("0.83.0");
-    expect(hasCompletedRange(state, "0.82.1", "0.83.0")).toBe(true);
-    expect(hasRecordedOutcome(state, "0.82.1", "0.83.0")).toBe(true);
+    expect(state.audit_cursor_version).toBe("0.84.0");
+    expect(hasCompletedRange(state, "0.82.1", "0.84.0")).toBe(true);
+    expect(hasRecordedOutcome(state, "0.82.1", "0.84.0")).toBe(true);
+    expect(renderTrackerBody(state)).toContain("[0.82.1...0.84.0]");
   });
 
-  test("keeps a created PR pending until it merges", () => {
+  test("advances a created PR and keeps it pending at the cursor", () => {
     const pending = recordAnalysis(initialTrackerState("0.82.1"), {
       analysis: analysis("0.82.1", "0.83.0"),
       outcome: "pr_created",
@@ -37,14 +37,18 @@ describe("pi-ai watch tracker", () => {
       prUrl: "https://github.com/letta-ai/letta-code/pull/123",
       processedAt: "2026-08-21T00:00:00Z",
     });
-    expect(pending.audit_cursor_version).toBe("0.82.1");
+    expect(pending.audit_cursor_version).toBe("0.83.0");
     expect(getPendingPrForCursor(pending)?.version).toBe("0.83.0");
-    expect(hasCompletedRange(pending, "0.82.1", "0.83.0")).toBe(false);
+    expect(hasCompletedRange(pending, "0.82.1", "0.83.0")).toBe(true);
     expect(hasRecordedOutcome(pending, "0.82.1", "0.83.0")).toBe(true);
 
-    const merged = advanceMergedPr(pending, "0.83.0");
-    expect(merged.audit_cursor_version).toBe("0.83.0");
-    expect(getPendingPrForCursor(merged)).toBeNull();
+    const later = recordAnalysis(pending, {
+      analysis: analysis("0.83.0", "0.84.0"),
+      outcome: "no_upgrade",
+      notes: "later release range",
+    });
+    expect(later.audit_cursor_version).toBe("0.84.0");
+    expect(getPendingPrForCursor(later)).toBeNull();
   });
 
   test("keeps errors retryable and replaces them with a later outcome", () => {
@@ -68,16 +72,16 @@ describe("pi-ai watch tracker", () => {
     expect(retried.processed[0]?.outcome).toBe("no_upgrade");
   });
 
-  test("advances uncertain releases but not explicit non-adjacent replays", () => {
+  test("advances cumulative reviews but not replays behind the cursor", () => {
     const human = recordAnalysis(initialTrackerState("0.82.1"), {
-      analysis: analysis("0.82.1", "0.83.0"),
+      analysis: analysis("0.82.1", "0.84.0"),
       outcome: "needs_human_review",
       notes: "product decision",
     });
-    expect(human.audit_cursor_version).toBe("0.83.0");
+    expect(human.audit_cursor_version).toBe("0.84.0");
 
     const replay = recordAnalysis(initialTrackerState("0.82.1"), {
-      analysis: analysis("0.82.1", "0.84.0", false),
+      analysis: analysis("0.82.1", "0.83.0", false),
       outcome: "no_upgrade",
       notes: "explicit replay",
     });
@@ -101,7 +105,7 @@ describe("pi-ai watch tracker", () => {
       const previous = `0.${index}.0`;
       const current = `0.${index}.1`;
       state = recordAnalysis(state, {
-        analysis: analysis(previous, current, false),
+        analysis: analysis(previous, current),
         outcome: "error",
         notes: `attempt ${index}`,
         processedAt: `2026-08-21T00:${String(index).padStart(2, "0")}:00Z`,
@@ -115,18 +119,21 @@ describe("pi-ai watch tracker", () => {
 function analysis(
   previousVersion: string,
   currentVersion: string,
-  adjacent = true,
+  isLatestRelease = true,
 ): PiAiWatchAnalysis {
   return {
     package: "@earendil-works/pi-ai",
     installed_version: "0.82.1",
     previous_version: previousVersion,
     current_version: currentVersion,
-    is_adjacent_release: adjacent,
+    is_latest_release: isLatestRelease,
     published_at: "2026-08-14T00:00:00Z",
     integrity: "sha512-test",
     tarball_url: "https://example.test/pi-ai.tgz",
+    previous_git_head: "previous123",
     git_head: "abc123",
+    previous_tag_commit: "previous123",
+    current_tag_commit: "abc123",
     release_url: `https://github.com/earendil-works/pi/releases/tag/v${currentVersion}`,
     compare_url: `https://github.com/earendil-works/pi/compare/v${previousVersion}...v${currentVersion}`,
     changelog_md: "## Added",

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

@@ -87,9 +87,9 @@ export function recordAnalysis(
   ].slice(0, HISTORY_LIMIT);
 
   const advancesCursor =
-    options.analysis.is_adjacent_release &&
+    options.analysis.is_latest_release &&
     entry.previous_version === state.audit_cursor_version &&
-    (entry.outcome === "no_upgrade" || entry.outcome === "needs_human_review");
+    entry.outcome !== "error";
 
   return {
     audit_cursor_version: advancesCursor
@@ -123,8 +123,7 @@ export function hasCompletedRange(
     (entry) =>
       entry.previous_version === previousVersion &&
       entry.version === currentVersion &&
-      (entry.outcome === "no_upgrade" ||
-        entry.outcome === "needs_human_review"),
+      entry.outcome !== "error",
   );
 }
 
@@ -134,24 +133,13 @@ export function getPendingPrForCursor(
   return (
     state.processed.find(
       (entry) =>
-        entry.previous_version === state.audit_cursor_version &&
+        entry.version === state.audit_cursor_version &&
         entry.outcome === "pr_created" &&
         entry.pr_url,
     ) ?? null
   );
 }
 
-export function advanceMergedPr(
-  state: TrackerState,
-  currentVersion: string,
-): TrackerState {
-  const pending = getPendingPrForCursor(state);
-  if (!pending || pending.version !== currentVersion) {
-    throw new Error(`No pending pi-ai PR for ${currentVersion}`);
-  }
-  return { ...state, audit_cursor_version: currentVersion };
-}
-
 export function renderTrackerBody(state: TrackerState): string {
   const normalized = normalizeState(state);
   return `${[
@@ -166,7 +154,7 @@ export function renderTrackerBody(state: TrackerState): string {
     "",
     "## Hidden state",
     "",
-    "The workflow uses the hidden JSON block below for ordered release processing and dedupe.",
+    "The workflow uses the hidden JSON block below for cumulative release processing and dedupe.",
     "",
     serializeTrackerState(normalized),
   ].join("\n")}\n`;
@@ -193,12 +181,12 @@ function renderTable(state: TrackerState): string {
   if (entries.length === 0) return "_No pi-ai releases reviewed yet._";
 
   const rows = [
-    "| Release | Installed | Outcome | PR | Notes |",
+    "| Range | Installed | Outcome | PR | Notes |",
     "|---|---|---|---|---|",
   ];
   for (const entry of entries) {
     rows.push(
-      `| [${entry.version}](${entry.compare_url}) | ${entry.installed_version} | ${entry.outcome} | ${renderPr(entry.pr_url)} | ${escapeTable(entry.notes)} |`,
+      `| [${entry.previous_version}...${entry.version}](${entry.compare_url}) | ${entry.installed_version} | ${entry.outcome} | ${renderPr(entry.pr_url)} | ${escapeTable(entry.notes)} |`,
     );
   }
   return rows.join("\n");

package/scripts/pi-ai-watch/update-tracker.ts

@@ -202,13 +202,13 @@ function parseOutcome(value: string | undefined): TrackerOutcome {
 function defaultNotes(outcome: TrackerOutcome): string {
   switch (outcome) {
     case "no_upgrade":
-      return "reviewed; no upgrade needed for this release";
+      return "reviewed; no upgrade needed for this release range";
     case "pr_created":
       return "opened pi-ai dependency upgrade PR";
     case "needs_human_review":
       return "needs human review";
     case "error":
-      return "automation hit an error; retry this release";
+      return "automation hit an error; retry this release range";
   }
 }
 

package/scripts/source-file-size-baseline.json

@@ -37,13 +37,13 @@
   "src/settings-manager.ts": 2102,
   "src/tools/manager.ts": 2993,
   "src/tools/tool-execution-context.test.ts": 1138,
-  "src/types/protocol_v2.ts": 2848,
+  "src/types/protocol_v2.ts": 2666,
   "src/websocket/listen-client-concurrency.test.ts": 2686,
   "src/websocket/listen-client-protocol.test.ts": 5819,
   "src/websocket/listener/commands/memory.ts": 1114,
   "src/websocket/listener/file-commands.ts": 1053,
   "src/websocket/listener/lifecycle.ts": 1048,
-  "src/websocket/listener/protocol-inbound.ts": 2242,
+  "src/websocket/listener/protocol-inbound.ts": 2227,
   "src/websocket/listener/protocol-outbound.ts": 1047,
-  "src/websocket/listener/turn.ts": 1070
+  "src/websocket/listener/turn.ts": 1058
 }

package/skills/dispatching-coding-agents/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dispatching-coding-agents
-description: Dispatch stateless coding agents (Claude Code or Codex) via Bash. Use when you're stuck, need a second opinion, or need parallel research on a hard problem. They have no memory — you must provide all context.
+description: Dispatch stateless coding agents through Claude Code or Codex. Model catalog checked 2026-08-25: Claude Code includes Sonnet 5, Opus 5, and Fable 5; Codex includes GPT-5.6 Luna, Terra, and Sol. Use when you're stuck, need a second opinion, or need parallel research on a hard problem. They have no memory, so you must provide all context.
 ---
 
 # Dispatching Coding Agents
@@ -43,14 +43,23 @@ Different agents have different strengths. Track what works in your memory over
 
 ### Categories
 
-**Codex:**
-- Use the configured default model. Model catalogs and account access change frequently, so only pass `--model` when the user explicitly requests one.
+**Codex (catalog checked 2026-08-25):**
+- `gpt-5.6-luna`: high-throughput, lower-latency work
+- `gpt-5.6-terra`: strong performance with a balance of intelligence and cost
+- `gpt-5.6-sol`: quality-first flagship for difficult coding and reasoning
+- Use the configured default unless the user requests a model. Pass a requested model with `-m`, for example `codex exec "YOUR PROMPT" -m gpt-5.6-sol --sandbox workspace-write`.
 - If a requested model is rejected, inspect the installed CLI and account configuration rather than guessing another model name.
 
-**Claude Code:**
-- `opus` — Excellent writer. Best for docs, refactors, open-ended tasks, and vague instructions.
-  - Strengths: Excellent writer, understands vague instructions, excellent for coding but also general-purpose
-  - Weaknesses: Tends to generate "slop", writing excessive quantities of code unnecessarily. Can hang on large repos.
+**Claude Code (catalog checked 2026-08-25):**
+- The current flagship models are Sonnet 5, Opus 5, and Fable 5. Use the configured default unless the user requests a model.
+- Claude Code's stable aliases follow its current catalog:
+  - `best`: highest-capability model available to the account, using Fable 5 when available
+  - `fable`: Fable 5 for the hardest, longest-running tasks
+  - `opus`: Opus 5 for complex reasoning, docs, refactors, and open-ended tasks
+  - `sonnet`: Sonnet 5 for everyday coding
+  - `haiku`: fast, simple tasks
+- Pass an alias with `--model`, for example `claude -p "YOUR PROMPT" --model fable --dangerously-skip-permissions`.
+- Aliases update as Claude Code's catalog changes. If an alias is rejected, inspect the installed CLI version and account access rather than guessing a versioned model name.
 
 ### Cost and speed tradeoffs
 - Use each CLI's configured default model unless the task requires a model the user explicitly requested

package/skills/self-configuration/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: self-configuration
-description: Inspect or modify Letta Code's own memory, model, context window, system prompt, compaction, permissions, toolsets, mods, skills, channels, schedules, and local runtime settings. Use when the user asks how this agent or conversation is configured, or asks you to change how you behave or how the harness runs you.
+description: Inspect or modify Letta Code's own memory, model, context window, system prompt, compaction, permissions, toolsets, mods, skills, channels, schedules, agent secrets, and local runtime settings. Use when the user asks how this agent or conversation is configured, or asks you to change how you behave or how the harness runs you.
 license: MIT
 ---
 
@@ -22,6 +22,7 @@ The important part is choosing the right layer. Do not smear a preference into d
 | Skills | Reusable procedural knowledge or bundled scripts | Load `creating-skills` or `acquiring-skills` |
 | Channels | Slack/Discord/Telegram/WhatsApp/Signal accounts, pairing, routing, listener state | Use `letta channels` or channel commands |
 | Schedules | Reminders and recurring prompts | Load `scheduling-tasks` and use `letta cron` |
+| Agent secrets | Per-agent `$NAME` credential values for shell commands | Use `letta secret` (or `/secret` in a session) |
 
 Decision rule: if the model should remember and reason about it, use memory. If the runtime must enforce it or route it before the model decides anything, use settings, API fields, mods, channels, or schedules.
 
@@ -370,6 +371,24 @@ Never print provider keys. Shell expansion such as `--api-key "$OPENAI_API_KEY"`
 
 After connecting, verify the provider/model from the same backend and process that will run the agent. Do not infer success from a saved credential alone.
 
+## Agent secrets
+
+Agent-scoped secrets hold credential values that are referenced as `$NAME` in shell commands. Cloud agents store them server-side on the agent; local agents use OS secure storage. The harness substitutes `$NAME` at exec time and scrubs values from tool output, so values never enter agent context.
+
+```bash
+letta secret list                                   # names only, never values
+letta secret set GITHUB_TOKEN --env GITHUB_TOKEN    # ingest from the environment
+openssl rand -hex 32 | letta secret set WEBHOOK_TOKEN --stdin   # generate without seeing the value
+letta secret unset GITHUB_TOKEN                     # aliases: delete | remove | rm
+```
+
+Rules:
+
+- Pass the source variable *name* to `--env`, not `$NAME`. `--env $GITHUB_TOKEN` triggers harness substitution and places the resolved value in process arguments; `--env GITHUB_TOKEN` reads it from the CLI process environment without exposure.
+- Never echo secret values into tool output. Pipe generated credentials straight into `--stdin`.
+- Inside a session, `AGENT_ID`/`LETTA_AGENT_ID` resolves the target automatically; pass `--agent <agent-id>` otherwise.
+- A running session loads its secret cache at startup; CLI-side changes apply to new sessions. The `/secret` slash command manages the same store interactively and refreshes the live cache.
+
 ## Channels
 
 Use channels when the user wants to talk through Slack, Discord, Telegram, WhatsApp, or Signal.