@letta-ai/letta-code 0.30.26 → 0.30.28

package/scripts/claude-watch/runtime-sandbox.ts

@@ -0,0 +1,170 @@
+import { spawn } from "node:child_process";
+
+const RUNTIME_SANDBOX_IMAGE =
+  "node:22.18.0-bookworm@sha256:3266bc9e8bee1acc8a77386eefaf574987d2729b8c5ec35b0dbd6ddbc40b0ce2";
+const AUTH_ENV_KEYS = ["ANTHROPIC_API_KEY", "CLAUDE_CODE_OAUTH_TOKEN"] as const;
+
+export interface CommandSpec {
+  command: string;
+  args: string[];
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+  timeoutMs: number;
+  outputCapBytes: number;
+  stdin?: string;
+  label: string;
+}
+
+export interface CommandResult {
+  exitCode: number | null;
+  stdout: string;
+  stderr: string;
+  timedOut: boolean;
+  truncated: boolean;
+  signal?: NodeJS.Signals | null;
+}
+
+export type CommandRunner = (spec: CommandSpec) => Promise<CommandResult>;
+
+/**
+ * Runs untrusted package install scripts and the closed-source Claude binary in
+ * a container that can see only its disposable probe root. The Docker client
+ * receives only the already-minimized command environment; secret values are
+ * inherited by name rather than placed in argv.
+ */
+export function sandboxClaudeCommand(
+  spec: CommandSpec,
+  root: string,
+): CommandSpec {
+  const containerRoot = "/watch";
+  const mapPath = (value: string): string =>
+    value === root || value.startsWith(`${root}/`)
+      ? `${containerRoot}${value.slice(root.length)}`
+      : value;
+  const args = [
+    "run",
+    "--rm",
+    "--network",
+    "bridge",
+    "--read-only",
+    "--tmpfs",
+    "/tmp:rw,nosuid,nodev,size=128m",
+    "--cap-drop",
+    "ALL",
+    "--security-opt",
+    "no-new-privileges",
+    "--pids-limit",
+    "256",
+    "--user",
+    `${process.getuid?.() ?? 1000}:${process.getgid?.() ?? 1000}`,
+    "--memory",
+    "2g",
+    "--cpus",
+    "2",
+    "--volume",
+    `${root}:${containerRoot}:rw`,
+    "--workdir",
+    mapPath(spec.cwd),
+  ];
+  for (const [key, value] of Object.entries(spec.env)) {
+    if (value === undefined || key === "PATH") continue;
+    args.push(
+      "--env",
+      AUTH_ENV_KEYS.includes(key as (typeof AUTH_ENV_KEYS)[number])
+        ? key
+        : `${key}=${mapPath(value)}`,
+    );
+  }
+  args.push(
+    RUNTIME_SANDBOX_IMAGE,
+    mapPath(spec.command),
+    ...spec.args.map(mapPath),
+  );
+  return {
+    ...spec,
+    command: "/usr/bin/docker",
+    args,
+    cwd: root,
+  };
+}
+
+/** Spawn with bounded output and terminate the whole process group on timeout/cap. */
+export const runBoundedCommand: CommandRunner = (spec) =>
+  new Promise((resolvePromise, reject) => {
+    const child = spawn(spec.command, spec.args, {
+      cwd: spec.cwd,
+      env: spec.env,
+      stdio: ["pipe", "pipe", "pipe"],
+      detached: process.platform !== "win32",
+      windowsHide: true,
+    });
+    const chunks: { stdout: Buffer[]; stderr: Buffer[] } = {
+      stdout: [],
+      stderr: [],
+    };
+    let bytes = 0;
+    let timedOut = false;
+    let truncated = false;
+    let settled = false;
+    const terminate = () => {
+      if (child.pid === undefined) return;
+      try {
+        if (process.platform === "win32") child.kill("SIGTERM");
+        else process.kill(-child.pid, "SIGTERM");
+      } catch {
+        child.kill("SIGTERM");
+      }
+      const killTimer = setTimeout(() => {
+        try {
+          if (process.platform === "win32") child.kill("SIGKILL");
+          else if (child.pid !== undefined) process.kill(-child.pid, "SIGKILL");
+        } catch {
+          child.kill("SIGKILL");
+        }
+      }, 500);
+      killTimer.unref();
+    };
+    const timer = setTimeout(() => {
+      timedOut = true;
+      terminate();
+    }, spec.timeoutMs);
+    const collect = (which: "stdout" | "stderr", value: Buffer) => {
+      const remaining = spec.outputCapBytes - bytes;
+      if (remaining > 0) {
+        const kept = value.subarray(0, remaining);
+        chunks[which].push(kept);
+        bytes += kept.length;
+      }
+      if (value.length > remaining) {
+        truncated = true;
+        terminate();
+      }
+    };
+    child.stdout.on("data", (value: Buffer) => collect("stdout", value));
+    child.stderr.on("data", (value: Buffer) => collect("stderr", value));
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      if (!settled) {
+        settled = true;
+        reject(
+          new Error(`Command ${spec.label} could not start: ${error.message}`),
+        );
+      }
+    });
+    child.on("close", (exitCode, signal) => {
+      clearTimeout(timer);
+      if (!settled) {
+        settled = true;
+        resolvePromise({
+          exitCode,
+          signal,
+          stdout: Buffer.concat(chunks.stdout).toString("utf8"),
+          stderr: Buffer.concat(chunks.stderr).toString("utf8"),
+          timedOut,
+          truncated,
+        });
+      }
+    });
+    if (spec.stdin !== undefined) child.stdin.end(spec.stdin);
+    else child.stdin.end();
+  });

package/scripts/claude-watch/state-branch.test.ts

@@ -0,0 +1,211 @@
+import { describe, expect, test } from "bun:test";
+import { spawnSync } from "node:child_process";
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  CLAUDE_WATCH_STATE_BRANCH,
+  CLAUDE_WATCH_STATE_FILE,
+  finalizeStateBranch,
+  loadStateSnapshot,
+  loadStateSnapshotAtCommit,
+  materializeStateFiles,
+  resolveStateBranchTip,
+} from "./state-branch.ts";
+import {
+  CLAUDE_WATCH_STATE_SCHEMA_VERSION,
+  type ClaudeWatchStateSnapshot,
+} from "./types.ts";
+
+function git(cwd: string, ...args: string[]): string {
+  const result = spawnSync("git", ["-C", cwd, ...args], {
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      GIT_AUTHOR_NAME: "Test",
+      GIT_AUTHOR_EMAIL: "test@example.test",
+      GIT_COMMITTER_NAME: "Test",
+      GIT_COMMITTER_EMAIL: "test@example.test",
+    },
+  });
+  if (result.status !== 0) {
+    throw new Error(result.stderr || `git ${args.join(" ")} failed`);
+  }
+  return result.stdout.trim();
+}
+
+function snapshot(candidateId: string): ClaudeWatchStateSnapshot {
+  return {
+    schema_version: CLAUDE_WATCH_STATE_SCHEMA_VERSION,
+    candidate_id: candidateId,
+    package_version: candidateId,
+    npm_integrity: `sha512-${candidateId}`,
+    npm_published_at: "2026-08-01T00:00:00Z",
+    release_url: `https://example.test/releases/${candidateId}`,
+    release_notes_md: "release notes",
+    release_published_at: "2026-08-01T00:00:00Z",
+    dist_tags: { latest: candidateId, stable: candidateId, next: null },
+    docs: {
+      index_url: "https://example.test/docs",
+      index_hash: "index-hash",
+      digest: `docs-${candidateId}`,
+      full_scan: true,
+      scanned_at: "2026-08-01T00:00:00Z",
+      pages: {},
+    },
+    runtime: null,
+    fetched_at: "2026-08-01T00:00:00Z",
+    workflow_run_url: "https://example.test/actions/1",
+    state_commit_parent: null,
+    analysis_parent_sha: null,
+  };
+}
+
+function repository(): { root: string; remote: string; clone: string } {
+  const root = mkdtempSync(join(tmpdir(), "claude-state-test-"));
+  const remote = join(root, "remote.git");
+  const clone = join(root, "clone");
+  git(root, "init", "--bare", remote);
+  git(root, "clone", remote, clone);
+  git(clone, "checkout", "-b", "main");
+  git(clone, "commit", "--allow-empty", "-m", "initial main");
+  git(clone, "push", "-u", "origin", "main");
+  return { root, remote, clone };
+}
+
+describe("Claude state branch", () => {
+  test("materializes and safely loads a deterministic snapshot", () => {
+    const value = snapshot("2.1.0");
+    const files = materializeStateFiles(value, {
+      "runtime/output.json": "{}\n",
+      "docs/index.json": "[]\n",
+      [CLAUDE_WATCH_STATE_FILE]: "must be replaced",
+    });
+    expect(Object.keys(files)).toEqual([
+      "docs/index.json",
+      "runtime/output.json",
+      CLAUDE_WATCH_STATE_FILE,
+    ]);
+    expect(loadStateSnapshot(files)).toEqual(value);
+    expect(loadStateSnapshot({ [CLAUDE_WATCH_STATE_FILE]: "{" })).toBeNull();
+    expect(() => materializeStateFiles(value, { "../escape": "no" })).toThrow(
+      "Unsafe state file path",
+    );
+  });
+
+  test("creates an orphan state branch, advances by parent, and is idempotent", () => {
+    const repo = repository();
+    try {
+      const mainBefore = git(repo.clone, "rev-parse", "main");
+      const first = finalizeStateBranch({
+        repoPath: repo.clone,
+        snapshot: snapshot("2.1.0"),
+        files: { "docs/page.txt": "first\n" },
+        expectedBaseSha: null,
+      });
+      expect(first.created).toBe(true);
+      expect(first.parentSha).toBeNull();
+      expect(
+        git(repo.clone, "rev-list", "--parents", "-n", "1", first.commitSha),
+      ).toBe(first.commitSha);
+      expect(resolveStateBranchTip(repo.clone)).toBe(first.commitSha);
+      expect(
+        loadStateSnapshotAtCommit(repo.clone, first.commitSha),
+      ).toMatchObject({
+        candidate_id: "2.1.0",
+        state_commit_parent: null,
+      });
+
+      const retry = finalizeStateBranch({
+        repoPath: repo.clone,
+        snapshot: snapshot("2.1.0"),
+        expectedBaseSha: null,
+      });
+      expect(retry).toEqual({
+        commitSha: first.commitSha,
+        created: false,
+        parentSha: first.commitSha,
+      });
+
+      const second = finalizeStateBranch({
+        repoPath: repo.clone,
+        snapshot: snapshot("2.2.0"),
+        expectedBaseSha: first.commitSha,
+      });
+      expect(second.parentSha).toBe(first.commitSha);
+      expect(
+        git(repo.clone, "rev-list", "--parents", "-n", "1", second.commitSha),
+      ).toBe(`${second.commitSha} ${first.commitSha}`);
+      expect(
+        loadStateSnapshotAtCommit(repo.clone, second.commitSha),
+      ).toMatchObject({
+        candidate_id: "2.2.0",
+        state_commit_parent: first.commitSha,
+        analysis_parent_sha: null,
+      });
+      expect(git(repo.clone, "rev-parse", "main")).toBe(mainBefore);
+      expect(git(repo.clone, "branch", "--show-current")).toBe("main");
+      expect(
+        git(repo.clone, "ls-remote", "--heads", "origin", "main"),
+      ).toContain(mainBefore);
+      expect(
+        git(
+          repo.clone,
+          "ls-remote",
+          "--heads",
+          "origin",
+          CLAUDE_WATCH_STATE_BRANCH,
+        ),
+      ).toContain(second.commitSha);
+    } finally {
+      rmSync(repo.root, { recursive: true, force: true });
+    }
+  });
+
+  test("rejects a stale base for a different candidate", () => {
+    const repo = repository();
+    try {
+      const first = finalizeStateBranch({
+        repoPath: repo.clone,
+        snapshot: snapshot("2.1.0"),
+        expectedBaseSha: null,
+      });
+      expect(() =>
+        finalizeStateBranch({
+          repoPath: repo.clone,
+          snapshot: snapshot("2.2.0"),
+          expectedBaseSha: null,
+        }),
+      ).toThrow(`found ${first.commitSha}`);
+    } finally {
+      rmSync(repo.root, { recursive: true, force: true });
+    }
+  });
+
+  test("a rejected push leaves main and the durable state tip unchanged", () => {
+    const repo = repository();
+    try {
+      const first = finalizeStateBranch({
+        repoPath: repo.clone,
+        snapshot: snapshot("2.1.0"),
+        expectedBaseSha: null,
+      });
+      const mainBefore = git(repo.clone, "rev-parse", "main");
+      const hook = join(repo.remote, "hooks", "pre-receive");
+      writeFileSync(hook, "#!/bin/sh\necho rejected >&2\nexit 1\n");
+      chmodSync(hook, 0o755);
+
+      expect(() =>
+        finalizeStateBranch({
+          repoPath: repo.clone,
+          snapshot: snapshot("2.2.0"),
+          expectedBaseSha: first.commitSha,
+        }),
+      ).toThrow("rejected");
+      expect(resolveStateBranchTip(repo.clone)).toBe(first.commitSha);
+      expect(git(repo.clone, "rev-parse", "main")).toBe(mainBefore);
+    } finally {
+      rmSync(repo.root, { recursive: true, force: true });
+    }
+  });
+});

package/scripts/claude-watch/state-branch.ts

@@ -0,0 +1,316 @@
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, posix } from "node:path";
+import type { ClaudeWatchStateSnapshot } from "./types.ts";
+
+export const CLAUDE_WATCH_STATE_BRANCH = "claude-watch-state";
+export const CLAUDE_WATCH_STATE_FILE = "snapshot.json";
+
+export interface FinalizeStateBranchOptions {
+  repoPath: string;
+  snapshot: ClaudeWatchStateSnapshot;
+  files?: Readonly<Record<string, string>>;
+  /** The SHA observed when analysis started; null means no state branch existed. */
+  expectedBaseSha: string | null;
+  remote?: string;
+  branch?: string;
+  commitMessage?: string;
+}
+
+export interface FinalizeStateBranchResult {
+  commitSha: string;
+  created: boolean;
+  parentSha: string | null;
+}
+
+/**
+ * Produces the complete, deterministic file set for a state commit. This is
+ * intentionally pure so callers can inspect or test a snapshot before git is
+ * involved.
+ */
+export function materializeStateFiles(
+  snapshot: ClaudeWatchStateSnapshot,
+  files: Readonly<Record<string, string>> = {},
+): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const path of Object.keys(files).sort()) {
+    assertSafeStatePath(path);
+    if (path === CLAUDE_WATCH_STATE_FILE) continue;
+    result[path] = files[path] as string;
+  }
+  result[CLAUDE_WATCH_STATE_FILE] = `${JSON.stringify(snapshot, null, 2)}\n`;
+  return result;
+}
+
+/** Safely loads the canonical snapshot from an already materialized file map. */
+export function loadStateSnapshot(
+  files: Readonly<Record<string, string>>,
+): ClaudeWatchStateSnapshot | null {
+  const source = files[CLAUDE_WATCH_STATE_FILE];
+  if (typeof source !== "string") return null;
+  try {
+    const value: unknown = JSON.parse(source);
+    return isStateSnapshot(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Reads a snapshot at a commit without checking out or changing any branch. */
+export function loadStateSnapshotAtCommit(
+  repoPath: string,
+  commitSha: string,
+): ClaudeWatchStateSnapshot | null {
+  const result = git(
+    repoPath,
+    ["show", `${commitSha}:${CLAUDE_WATCH_STATE_FILE}`],
+    false,
+  );
+  if (!result.ok) return null;
+  return loadStateSnapshot({ [CLAUDE_WATCH_STATE_FILE]: result.stdout });
+}
+
+/** Reads the complete sanitized state tree at a commit without checking it out. */
+export function loadStateFilesAtCommit(
+  repoPath: string,
+  commitSha: string,
+): Record<string, string> {
+  const listed = git(
+    repoPath,
+    ["ls-tree", "-r", "--name-only", commitSha],
+    false,
+  );
+  if (!listed.ok) return {};
+  const files: Record<string, string> = {};
+  for (const path of listed.stdout.split("\n").filter(Boolean).sort()) {
+    assertSafeStatePath(path);
+    const contents = git(repoPath, ["show", `${commitSha}:${path}`], false);
+    if (contents.ok) files[path] = contents.stdout;
+  }
+  return files;
+}
+
+/** Returns the remote state tip, or null when the branch has not been created. */
+export function resolveStateBranchTip(
+  repoPath: string,
+  remote = "origin",
+  branch = CLAUDE_WATCH_STATE_BRANCH,
+): string | null {
+  assertBranchName(branch);
+  const result = git(repoPath, [
+    "ls-remote",
+    "--heads",
+    remote,
+    `refs/heads/${branch}`,
+  ]);
+  const line = result.stdout.trim();
+  if (!line) return null;
+  const sha = line.split(/\s+/, 1)[0];
+  if (!sha || !/^[0-9a-f]{40,64}$/.test(sha)) {
+    throw new Error(`Unexpected state branch response for ${branch}`);
+  }
+  return sha;
+}
+
+/** Fetches the current state tip into a remote-tracking ref without checkout. */
+export function fetchStateBranchTip(
+  repoPath: string,
+  remote = "origin",
+  branch = CLAUDE_WATCH_STATE_BRANCH,
+): string | null {
+  const tip = resolveStateBranchTip(repoPath, remote, branch);
+  if (!tip) return null;
+  git(repoPath, [
+    "fetch",
+    "--no-tags",
+    "--depth=2",
+    remote,
+    `refs/heads/${branch}:refs/remotes/${remote}/${branch}`,
+  ]);
+  return tip;
+}
+
+/**
+ * Commits and pushes a snapshot using git plumbing only. No branch is checked
+ * out, so the caller's current branch (especially main) is never touched.
+ * Pushes have no force refspec and therefore receive normal fast-forward
+ * protection from git.
+ */
+export function finalizeStateBranch(
+  options: FinalizeStateBranchOptions,
+): FinalizeStateBranchResult {
+  const remote = options.remote ?? "origin";
+  const branch = options.branch ?? CLAUDE_WATCH_STATE_BRANCH;
+  assertBranchName(branch);
+
+  const currentTip = resolveStateBranchTip(options.repoPath, remote, branch);
+  if (currentTip) fetchStateBranchTip(options.repoPath, remote, branch);
+  const currentSnapshot = currentTip
+    ? loadStateSnapshotAtCommit(options.repoPath, currentTip)
+    : null;
+
+  // A retry after a successful push is a no-op, even if its remembered base is
+  // now stale. This check is what makes partial workflow reconciliation safe.
+  if (
+    currentTip &&
+    currentSnapshot?.candidate_id === options.snapshot.candidate_id
+  ) {
+    return { commitSha: currentTip, created: false, parentSha: currentTip };
+  }
+
+  if (currentTip !== options.expectedBaseSha) {
+    throw new Error(
+      `Claude state branch advanced: expected ${options.expectedBaseSha ?? "no branch"}, found ${currentTip ?? "no branch"}`,
+    );
+  }
+
+  const snapshot: ClaudeWatchStateSnapshot = {
+    ...options.snapshot,
+    state_commit_parent: currentTip,
+  };
+  const files = materializeStateFiles(snapshot, options.files);
+  const temporaryDirectory = mkdtempSync(join(tmpdir(), "claude-watch-state-"));
+  const indexFile = join(temporaryDirectory, "index");
+  const env = {
+    ...process.env,
+    GIT_INDEX_FILE: indexFile,
+    GIT_AUTHOR_NAME: process.env.GIT_AUTHOR_NAME ?? "Claude Watch",
+    GIT_AUTHOR_EMAIL:
+      process.env.GIT_AUTHOR_EMAIL ?? "claude-watch@users.noreply.github.com",
+    GIT_COMMITTER_NAME: process.env.GIT_COMMITTER_NAME ?? "Claude Watch",
+    GIT_COMMITTER_EMAIL:
+      process.env.GIT_COMMITTER_EMAIL ??
+      "claude-watch@users.noreply.github.com",
+  };
+
+  try {
+    git(options.repoPath, ["read-tree", "--empty"], true, env);
+    for (const [path, contents] of Object.entries(files)) {
+      const blob = git(
+        options.repoPath,
+        ["hash-object", "-w", "--stdin"],
+        true,
+        env,
+        contents,
+      ).stdout.trim();
+      git(
+        options.repoPath,
+        ["update-index", "--add", "--cacheinfo", "100644", blob, path],
+        true,
+        env,
+      );
+    }
+    const tree = git(options.repoPath, ["write-tree"], true, env).stdout.trim();
+    const commitArgs = [
+      "commit-tree",
+      tree,
+      ...(currentTip ? ["-p", currentTip] : []),
+      "-m",
+      options.commitMessage ??
+        `chore(claude-watch): record ${snapshot.candidate_id}`,
+    ];
+    const commitSha = git(
+      options.repoPath,
+      commitArgs,
+      true,
+      env,
+    ).stdout.trim();
+
+    // No leading '+' and no --force: the remote enforces normal FF updates.
+    git(options.repoPath, [
+      "push",
+      remote,
+      `${commitSha}:refs/heads/${branch}`,
+    ]);
+    return { commitSha, created: true, parentSha: currentTip };
+  } finally {
+    rmSync(temporaryDirectory, { recursive: true, force: true });
+  }
+}
+
+interface GitResult {
+  ok: boolean;
+  stdout: string;
+}
+
+function git(
+  repoPath: string,
+  args: string[],
+  required = true,
+  env: NodeJS.ProcessEnv = process.env,
+  input?: string,
+): GitResult {
+  const result = spawnSync("git", ["-C", repoPath, ...args], {
+    encoding: "utf8",
+    env,
+    input,
+  });
+  const stdout = result.stdout ?? "";
+  if (required && result.status !== 0) {
+    const detail = (result.stderr ?? stdout).trim();
+    throw new Error(`git ${args[0]} failed${detail ? `: ${detail}` : ""}`);
+  }
+  return { ok: result.status === 0, stdout };
+}
+
+function assertSafeStatePath(path: string): void {
+  if (
+    !path ||
+    path.includes("\\") ||
+    posix.isAbsolute(path) ||
+    posix.normalize(path) !== path ||
+    path === ".." ||
+    path.startsWith("../")
+  ) {
+    throw new Error(`Unsafe state file path: ${path}`);
+  }
+}
+
+function assertBranchName(branch: string): void {
+  if (
+    !branch ||
+    branch.startsWith("-") ||
+    branch.includes("..") ||
+    !/^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(branch)
+  ) {
+    throw new Error(`Unsafe state branch name: ${branch}`);
+  }
+}
+
+function isStateSnapshot(value: unknown): value is ClaudeWatchStateSnapshot {
+  if (!isRecord(value)) return false;
+  return (
+    typeof value.schema_version === "number" &&
+    typeof value.candidate_id === "string" &&
+    typeof value.package_version === "string" &&
+    typeof value.npm_integrity === "string" &&
+    typeof value.npm_published_at === "string" &&
+    typeof value.release_url === "string" &&
+    typeof value.release_notes_md === "string" &&
+    typeof value.release_published_at === "string" &&
+    isDistTags(value.dist_tags) &&
+    isRecord(value.docs) &&
+    (isRecord(value.runtime) || value.runtime === null) &&
+    typeof value.fetched_at === "string" &&
+    typeof value.workflow_run_url === "string" &&
+    (typeof value.state_commit_parent === "string" ||
+      value.state_commit_parent === null) &&
+    (value.analysis_parent_sha === undefined ||
+      typeof value.analysis_parent_sha === "string" ||
+      value.analysis_parent_sha === null)
+  );
+}
+
+function isDistTags(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.latest === "string" &&
+    (typeof value.stable === "string" || value.stable === null) &&
+    (typeof value.next === "string" || value.next === null)
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}