@letta-ai/letta-code 0.31.5 → 0.31.7

package/scripts/builtin-skills-watch/update-tracker.ts

@@ -37,6 +37,7 @@ export interface PullRequestView {
   files: Array<{ path: string }>;
   headRefOid: string;
   isDraft: boolean;
+  mergedAt?: string | null;
   state: string;
   url: string;
 }
@@ -337,19 +338,35 @@ export function parseReviewResult(
       "notes",
       "pr_url",
       "evidence",
-    ]) ||
-    value.schema_version !== 1 ||
+    ])
+  ) {
+    throw new Error("Review result has unknown or missing fields");
+  }
+  if (value.schema_version !== 1) {
+    throw new Error("Review result must use schema version 1");
+  }
+  if (
     value.candidate_id !== analysis.candidate_id ||
-    value.skill !== analysis.skill ||
-    (value.outcome !== "no_drift" &&
-      value.outcome !== "pr_created" &&
-      value.outcome !== "needs_human_review") ||
+    value.skill !== analysis.skill
+  ) {
+    throw new Error("Review result does not match the pending candidate");
+  }
+  if (
+    value.outcome !== "no_drift" &&
+    value.outcome !== "pr_created" &&
+    value.outcome !== "needs_human_review"
+  ) {
+    throw new Error("Review result outcome is invalid");
+  }
+  if (
     typeof value.notes !== "string" ||
     value.notes.length === 0 ||
-    value.notes.length > 120 ||
-    (value.pr_url !== null && typeof value.pr_url !== "string")
+    value.notes.length > 120
   ) {
-    throw new Error("Review result does not match the pending candidate");
+    throw new Error("Review result notes must contain 1 to 120 characters");
+  }
+  if (value.pr_url !== null && typeof value.pr_url !== "string") {
+    throw new Error("Review result pr_url must be a string or null");
   }
   if (
     (value.outcome === "pr_created") !==
@@ -381,28 +398,61 @@ export function verifyPullRequest(
   analysis: BuiltinSkillWatchAnalysis,
   expectedGithubLogin: string,
 ): void {
+  verifyPullRequestIdentity(expectedGithubLogin);
+  const pullRequest = getPullRequest(repo, prUrl);
+  validatePullRequestView(pullRequest, prUrl, analysis, expectedGithubLogin);
+  verifyPullRequestAncestry(repo, pullRequest, analysis);
+}
+
+export function verifyReconciledPullRequest(
+  repo: string,
+  prUrl: string,
+  analysis: BuiltinSkillWatchAnalysis,
+  expectedGithubLogin: string,
+): void {
+  verifyPullRequestIdentity(expectedGithubLogin);
+  const pullRequest = getPullRequest(repo, prUrl);
+  validateReconciledPullRequestView(
+    pullRequest,
+    prUrl,
+    analysis,
+    expectedGithubLogin,
+  );
+  verifyPullRequestAncestry(repo, pullRequest, analysis);
+}
+
+function verifyPullRequestIdentity(expectedGithubLogin: string): void {
   const authenticatedLogin = ghJson<{ login: string }>(["api", "user"]).login;
   if (authenticatedLogin !== expectedGithubLogin) {
     throw new Error(
       `Authenticated GitHub login ${authenticatedLogin} does not match ${expectedGithubLogin}`,
     );
   }
+}
+
+function getPullRequest(repo: string, prUrl: string): PullRequestView {
   const match = prUrl.match(
     /^https:\/\/github\.com\/([^/]+\/[^/]+)\/pull\/(\d+)\/?$/,
   );
   if (!match || match[1] !== repo) {
     throw new Error(`PR URL must belong to https://github.com/${repo}`);
   }
-  const pullRequest = ghJson<PullRequestView>([
+  return ghJson<PullRequestView>([
     "pr",
     "view",
     match[2] as string,
     "--repo",
     repo,
     "--json",
-    "author,baseRefName,body,files,headRefOid,isDraft,state,url",
+    "author,baseRefName,body,files,headRefOid,isDraft,mergedAt,state,url",
   ]);
-  validatePullRequestView(pullRequest, prUrl, analysis, expectedGithubLogin);
+}
+
+function verifyPullRequestAncestry(
+  repo: string,
+  pullRequest: PullRequestView,
+  analysis: BuiltinSkillWatchAnalysis,
+): void {
   const comparison = ghJson<{
     status: string;
     merge_base_commit: { sha: string };
@@ -423,6 +473,33 @@ export function validatePullRequestView(
   prUrl: string,
   analysis: BuiltinSkillWatchAnalysis,
   expectedGithubLogin: string,
+): void {
+  validatePullRequestScope(pullRequest, prUrl, analysis, expectedGithubLogin);
+  if (pullRequest.state !== "OPEN" || !pullRequest.isDraft) {
+    throw new Error("Watcher PR must be open and draft");
+  }
+}
+
+export function validateReconciledPullRequestView(
+  pullRequest: PullRequestView,
+  prUrl: string,
+  analysis: BuiltinSkillWatchAnalysis,
+  expectedGithubLogin: string,
+): void {
+  validatePullRequestScope(pullRequest, prUrl, analysis, expectedGithubLogin);
+  const isOpenDraft = pullRequest.state === "OPEN" && pullRequest.isDraft;
+  const isMerged =
+    pullRequest.state === "MERGED" && typeof pullRequest.mergedAt === "string";
+  if (!isOpenDraft && !isMerged) {
+    throw new Error("Reconciled watcher PR must be an open draft or merged");
+  }
+}
+
+function validatePullRequestScope(
+  pullRequest: PullRequestView,
+  prUrl: string,
+  analysis: BuiltinSkillWatchAnalysis,
+  expectedGithubLogin: string,
 ): void {
   if (pullRequest.url !== prUrl.replace(/\/$/, "")) {
     throw new Error(`PR URL mismatch: ${pullRequest.url}`);
@@ -432,9 +509,6 @@ export function validatePullRequestView(
       `PR author ${pullRequest.author.login} does not match ${expectedGithubLogin}`,
     );
   }
-  if (pullRequest.state !== "OPEN" || !pullRequest.isDraft) {
-    throw new Error("Watcher PR must be open and draft");
-  }
   if (pullRequest.baseRefName !== "main") {
     throw new Error("Watcher PR must target main");
   }

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

@@ -0,0 +1,30 @@
+import { describe, expect, test } from "bun:test";
+import { parseArgs } from "./update-tracker.ts";
+
+describe("parseArgs", () => {
+  const required = [
+    "--tracker-issue",
+    "123",
+    "--analysis-file",
+    "/tmp/analysis.json",
+    "--state-commit-sha",
+    "abc123",
+    "--outcome",
+    "pr_created",
+    "--pr-url",
+    "https://github.com/letta-ai/letta-code/pull/456",
+  ];
+
+  test("requires the expected GitHub login for a PR", () => {
+    expect(() => parseArgs(required)).toThrow(
+      "--expected-github-login is required for pr_created",
+    );
+  });
+
+  test("accepts the expected GitHub login for a PR", () => {
+    expect(
+      parseArgs([...required, "--expected-github-login", "amelia-letta"])
+        .expectedGithubLogin,
+    ).toBe("amelia-letta");
+  });
+});

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

@@ -27,6 +27,7 @@ interface Args {
   outcome: ClaudeWatchOutcome | null;
   notes: string;
   prUrl: string | null;
+  expectedGithubLogin: string | null;
   assertTerminal: boolean;
   dryRun: boolean;
 }
@@ -41,6 +42,7 @@ export function parseArgs(argv: string[]): Args {
     outcome: null,
     notes: "",
     prUrl: null,
+    expectedGithubLogin: null,
     assertTerminal: false,
     dryRun: false,
   };
@@ -59,6 +61,8 @@ export function parseArgs(argv: string[]): Args {
       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 === "--expected-github-login")
+      args.expectedGithubLogin = 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}`);
@@ -75,8 +79,12 @@ export function parseArgs(argv: string[]): Args {
     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");
+    if (args.outcome === "pr_created") {
+      if (!args.prUrl) throw new Error("--pr-url is required for pr_created");
+      if (!args.expectedGithubLogin) {
+        throw new Error("--expected-github-login is required for pr_created");
+      }
+    }
   }
   return args;
 }
@@ -117,15 +125,16 @@ function verifyParityPr(
   repo: string,
   prUrl: string,
   candidateId: string,
+  expectedGithubLogin: 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") {
+  if (!pr.isDraft || pr.author.login !== expectedGithubLogin) {
     throw new Error(
-      `Parity PR must be a draft authored by carenthomas (got draft=${pr.isDraft}, author=${pr.author.login})`,
+      `Parity PR must be a draft authored by ${expectedGithubLogin} (got draft=${pr.isDraft}, author=${pr.author.login})`,
     );
   }
   if (!pr.body?.includes(`Claude-watch: ${candidateId}`)) {
@@ -164,7 +173,12 @@ export function main(argv = process.argv.slice(2)): void {
     verifyStateCandidate(analysis.candidate_id, args.stateCommitSha as string);
   }
   if (args.outcome === "pr_created") {
-    verifyParityPr(args.repo, args.prUrl as string, analysis.candidate_id);
+    verifyParityPr(
+      args.repo,
+      args.prUrl as string,
+      analysis.candidate_id,
+      args.expectedGithubLogin as string,
+    );
   }
   const next = recordAnalysis(state, {
     analysis,

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

@@ -0,0 +1,28 @@
+import { describe, expect, test } from "bun:test";
+import { parseArgs } from "./update-tracker.ts";
+
+describe("parseArgs", () => {
+  const required = [
+    "--tracker-issue",
+    "123",
+    "--analysis-file",
+    "/tmp/analysis.json",
+    "--outcome",
+    "pr_created",
+    "--pr-url",
+    "https://github.com/letta-ai/letta-code/pull/456",
+  ];
+
+  test("requires the expected GitHub login for a PR", () => {
+    expect(() => parseArgs(required)).toThrow(
+      "--expected-github-login is required for pr_created",
+    );
+  });
+
+  test("accepts the expected GitHub login for a PR", () => {
+    expect(
+      parseArgs([...required, "--expected-github-login", "amelia-letta"])
+        .expectedGithubLogin,
+    ).toBe("amelia-letta");
+  });
+});

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

@@ -7,7 +7,7 @@
  */
 
 import { readFileSync } from "node:fs";
-import { editIssueBody, getIssueBody } from "./github.ts";
+import { editIssueBody, getIssueBody, ghJson } from "./github.ts";
 import {
   type CodexWatchAnalysis,
   DEFAULT_TARGET_REPO,
@@ -26,10 +26,11 @@ interface Args {
   outcome: TrackerOutcome | null;
   notes: string;
   prUrl: string | null;
+  expectedGithubLogin: string | null;
   dryRun: boolean;
 }
 
-function parseArgs(argv: string[]): Args {
+export function parseArgs(argv: string[]): Args {
   const args: Args = {
     repo: DEFAULT_TARGET_REPO,
     trackerIssue: null,
@@ -37,6 +38,7 @@ function parseArgs(argv: string[]): Args {
     outcome: null,
     notes: "",
     prUrl: null,
+    expectedGithubLogin: null,
     dryRun: false,
   };
 
@@ -49,10 +51,12 @@ function parseArgs(argv: string[]): Args {
     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 === "--expected-github-login") {
+      args.expectedGithubLogin = 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]",
+        "Usage: bun scripts/codex-watch/update-tracker.ts --tracker-issue ISSUE --analysis-file FILE --outcome OUTCOME [--notes TEXT] [--pr-url URL --expected-github-login LOGIN] [--repo OWNER/REPO] [--dry-run]",
       );
       process.exit(0);
     } else {
@@ -65,8 +69,13 @@ function parseArgs(argv: string[]): Args {
   }
   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");
+  if (args.outcome === "pr_created") {
+    if (!args.prUrl) {
+      throw new Error("--pr-url is required when --outcome pr_created");
+    }
+    if (!args.expectedGithubLogin) {
+      throw new Error("--expected-github-login is required for pr_created");
+    }
   }
 
   return args;
@@ -94,6 +103,14 @@ function main() {
   const analysis = readAnalysis(args.analysisFile as string);
   const body = getIssueBody(args.repo, args.trackerIssue as number);
   const state = parseTrackerState(body);
+  if (args.outcome === "pr_created") {
+    verifyParityPr(
+      args.repo,
+      args.prUrl as string,
+      args.expectedGithubLogin as string,
+      analysis.current_tag,
+    );
+  }
   const next = recordAnalysis(state, {
     analysis,
     outcome: args.outcome as TrackerOutcome,
@@ -113,6 +130,41 @@ function main() {
   );
 }
 
+function verifyParityPr(
+  repo: string,
+  prUrl: string,
+  expectedGithubLogin: string,
+  currentTag: string,
+): void {
+  const pullRequest = ghJson<{
+    author: { login: string };
+    body: string | null;
+    isDraft: boolean;
+    state: string;
+  }>([
+    "pr",
+    "view",
+    prUrl,
+    "--repo",
+    repo,
+    "--json",
+    "author,body,isDraft,state",
+  ]);
+  if (
+    pullRequest.author.login !== expectedGithubLogin ||
+    !pullRequest.isDraft ||
+    pullRequest.state !== "OPEN"
+  ) {
+    throw new Error(
+      `Codex PR must be an open draft authored by ${expectedGithubLogin} (got author=${pullRequest.author.login}, draft=${pullRequest.isDraft}, state=${pullRequest.state})`,
+    );
+  }
+  const marker = `Codex-watch: openai/codex ${currentTag}`;
+  if (!pullRequest.body?.includes(marker)) {
+    throw new Error(`Codex PR body is missing marker: ${marker}`);
+  }
+}
+
 function defaultNotes(outcome: TrackerOutcome): string {
   switch (outcome) {
     case "recorded_noop":
@@ -128,4 +180,4 @@ function defaultNotes(outcome: TrackerOutcome): string {
   }
 }
 
-main();
+if (import.meta.main) main();

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

@@ -1,6 +1,6 @@
 {
   "src/agent/client-skills.test.ts": 1134,
-  "src/agent/memory-git.ts": 2122,
+  "src/agent/memory-git.ts": 2090,
   "src/backend/local-backend.test.ts": 2532,
   "src/backend/local/local-backend.ts": 1014,
   "src/backend/local/local-store.ts": 3459,

package/skills/letta-guide/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: letta-guide
-description: Answer questions about Letta itself from the official documentation. Use whenever the user asks how Letta works, what Letta (or you) can do, or how to set up or configure providers, models, channels, skills, memory, schedules, permissions, self-hosting, pricing, or billing — any "how do I…" or "can Letta…" question about the Letta product. Fetch the docs before answering; never answer Letta product questions from memory alone.
+description: Read the official Letta documentation (docs.letta.com) through its cached, ETag-checked fetch route. Load before ANY docs.letta.com retrieval — answering how Letta works, what Letta (or you) can do, setting up providers, models, channels, skills, memory, schedules, permissions, self-hosting, pricing, or billing, AND looking up Letta API, Agent SDK, or Letta Code reference while writing code. Do not use fetch_webpage or web_search on docs.letta.com; this skill's helper is the docs route. Never answer Letta product questions from memory alone.
 ---
 
 # Letta Guide
@@ -8,7 +8,11 @@ description: Answer questions about Letta itself from the official documentation
 You are running inside Letta, but your training data about Letta's commands,
 flags, settings, UI, pricing, and providers is out of date. Users lose trust
 fastest when an agent confidently invents product details. This skill defines
-how to answer questions about Letta correctly.
+how to read the Letta docs correctly — both when answering questions about
+Letta and when looking up API, Agent SDK, or Letta Code reference during
+development. Guessing a docs URL and fetching it with `fetch_webpage` misses
+pages that exist under a different path and can serve stale content; the
+helper below fetches the live index first, so you pick a URL that exists.
 
 ## Source route (in order)
 

package/skills/managing-shared-memory/SKILL.md

@@ -7,7 +7,7 @@ description: Create and manage shared memory — git-tracked repositories hosted
 
 Shared memory is memory created independently of any single agent, designed to be dynamically attached to or detached from multiple agents. Each unit of shared memory is a **shared memory repository**: a git repository hosted on Letta Cloud, owned by your organization rather than by one agent, reachable from any environment (sandboxes, remote machines, sessions).
 
-Shared memory works exactly like your MemFS: attached repositories are real git checkouts on disk, and you read, edit, commit, and push them with ordinary git. The only differences are that each repository has its own projection root (next to your memory directory, not inside it) and its own remote origin, and other agents may be writing to it too.
+Shared memory works like your MemFS: attached repositories are real git checkouts on disk, and you read, edit, and commit with ordinary git. The harness pushes clean committed changes after each turn. Each repository has its own projection root (next to your memory directory, not inside it) and its own remote origin, and other agents may be writing to it too.
 
 Create a shared memory repository when:
 - You have context an agent should be able to access that doesn't belong in its own MemFS (input files, datasets, docs, working artifacts)
@@ -23,16 +23,15 @@ ls "$MEMORY_DIR/../"                      # attached repositories appear here by
 cat "$MEMORY_DIR/../<repo-name>/<path>"   # read like any file
 ```
 
-Edit files with your normal file tools, then commit and push with git — the mount's origin and credentials are already configured:
+Edit files with your normal file tools, then commit with git. The mount's origin and credentials are already configured:
 
 ```bash
 cd "$MEMORY_DIR/../<repo-name>"
 git add <files>
 git commit -m "describe the change"
-git push
 ```
 
-Unlike MemFS, the harness does not auto-push shared memory after turns — a commit you don't push is not visible to other agents or environments. Always push after committing.
+The harness pushes clean commits from read/write attached repositories after the turn. If a push collides with another agent's work, it pulls with rebase and retries once. Dirty files and conflicts are not changed automatically; the harness adds a reminder to the next turn instead.
 
 To pick up other agents' changes:
 
@@ -84,7 +83,7 @@ letta shared-memory history shared-notes --path docs/plan.md
 - **`sync` reports "mount path already exists and is not a git repository"** — a plain directory (usually created by hand before the mount existed) is occupying the mount path. Inspect it, salvage anything worth keeping, move or delete it, then re-run `letta shared-memory sync`.
 - **Never hand-clone the repository to another location (e.g. /tmp) to work around a broken mount** — fix the mount with `letta shared-memory sync` so every session and other agents see the same checkout.
 - **Permission denied under another agent's directory** — shared repositories mount per-agent. Only your own mount (under your agent directory) is accessible; another agent's mount of the same repository is walled off by the cross-agent guard. Run `letta shared-memory sync` to get your own mount.
-- **Push rejected (non-fast-forward)** — another agent pushed first: `git pull --rebase`, resolve any conflicts, push again.
+- **Shared-memory conflict reminder** — resolve the conflict in the named repository, finish the rebase or commit, and leave the repository clean. The harness retries the push after a future turn.
 
 ## Notes and Limits
 

package/skills/submitting-feedback/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: submitting-feedback
+description: Submits user-approved feedback about Letta Code or the current agent to the Letta team. Load when the user is upset, frustrated, dissatisfied, reports poor agent behavior, or asks to send feedback. Works with cloud-hosted and local agents. Ask before submitting unless the user already explicitly requested submission.
+---
+
+# Submitting Feedback
+
+When the user appears upset with the agent, acknowledge the problem and ask whether they want you to submit feedback to the Letta team. Do not submit merely because the user expressed frustration.
+
+If the user says yes, or directly asks you to submit feedback:
+
+1. Write a short factual message in the user's voice. Include what happened, what the user expected, and any useful error or behavior detail already present in the conversation. Do not add claims the user did not make.
+2. Submit it with:
+
+```bash
+letta feedback --message '<feedback>'
+```
+
+3. Tell the user whether submission succeeded. If it failed, report the safe CLI error and do not claim the team received it.
+
+Do not include secrets, credentials, unrelated conversation content, or private file contents. The command adds the current agent and conversation identifiers so the team can find the relevant run.