@letta-ai/letta-code 0.34.5 → 0.34.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.34.5",
+  "version": "0.34.6",
   "lettaStartupLogProtocol": 1,
   "description": "Letta Code is a CLI tool for interacting with stateful Letta agents from the terminal.",
   "type": "module",
@@ -13,6 +13,7 @@
     "README.md",
     "letta.js",
     "image-resize-worker.js",
+    "npm-shrinkwrap.json",
     "assets/tutor-profile.png",
     "scripts",
     "skills",
@@ -209,14 +210,17 @@
     "check:test-coverage": "node scripts/check-test-coverage.cjs",
     "check:skill-frontmatter": "node scripts/check-skill-frontmatter.js",
     "check:bundled-skill-scripts": "node scripts/check-bundled-skill-scripts.js",
+    "runtime-graph:generate": "bun run scripts/runtime-graph.ts generate",
+    "runtime-graph:verify": "bun run scripts/runtime-graph.ts verify",
     "check": "bun run scripts/check.js",
     "dev": "node scripts/dev.cjs",
     "build": "node scripts/postinstall-patches.js && bun run build.js",
     "test:update-chain:manual": "bun run src/test-utils/update-chain-smoke.ts --mode manual",
     "test:update-chain:startup": "bun run src/test-utils/update-chain-smoke.ts --mode startup",
-    "prepublishOnly": "bun run build",
+    "prepublishOnly": "bun run runtime-graph:verify && bun run build",
     "postinstall": "node scripts/postinstall-patches.js || echo letta: vendor patches skipped && node -e \"try{require('fs').chmodSync(require('path').join(require.resolve('node-pty/package.json'),'../prebuilds/darwin-arm64/spawn-helper'),0o755)}catch(e){}\" || true",
-    "mod-learning:memory-citations": "bun scripts/mod-learning/learn-mod.ts --env docs/examples/mods/learning/memory-citations.env.json"
+    "mod-learning:memory-citations": "bun scripts/mod-learning/learn-mod.ts --env docs/examples/mods/learning/memory-citations.env.json",
+    "test:built-entrypoints": "LETTA_TEST_CLI_BUNDLE=\"$PWD/letta.js\" LETTA_TEST_BUILT_ARTIFACT=1 bun test src/cli/subcommands/lifecycle-output.test.ts src/websocket/app-server-dream.test.ts --timeout 60000"
   },
   "lint-staged": {
     "*.{ts,tsx,js,jsx,json}": [
@@ -268,5 +272,8 @@
         "./dist/types/types/protocol.d.ts"
       ]
     }
-  }
+  },
+  "lettaLifecycleProtocol": 1,
+  "lettaRuntimeGraphProtocol": 1,
+  "lettaRuntimeGraphSha512": "sha512-XLLoGDBuKF5JywIzS03nqOmcuSbwY1oGBwkINW2htdSGxlMnDVGIKq6HZLoE6hDMudNN3mzVIBUhdIYIlj2zzw=="
 }

package/scripts/check.js

@@ -23,6 +23,7 @@ const checks = [
   { name: "test coverage", script: ["check:test-coverage"] },
   { name: "skill frontmatter", script: ["check:skill-frontmatter"] },
   { name: "bundled skill scripts", script: ["check:bundled-skill-scripts"] },
+  { name: "runtime dependency graph", script: ["runtime-graph:verify"] },
   { name: "biome", script: ["lint"] },
   { name: "typescript", script: ["typecheck"] },
 ];

package/scripts/runtime-graph.test.ts

@@ -0,0 +1,112 @@
+import { describe, expect, test } from "bun:test";
+import { createHash } from "node:crypto";
+import {
+  canonicalRuntimeGraph,
+  runtimeGraphDigest,
+  verifyRuntimeGraph,
+} from "./runtime-graph";
+
+const integrity = `sha512-${Buffer.alloc(64, 7).toString("base64")}`;
+
+function dependencyLock() {
+  return {
+    name: "@letta-ai/letta-code",
+    version: "1.2.3",
+    lockfileVersion: 3,
+    packages: {
+      "": {
+        name: "@letta-ai/letta-code",
+        version: "1.2.3",
+        dependencies: { dependency: "^4.0.0" },
+        optionalDependencies: {},
+      },
+      "node_modules/dependency": {
+        version: "4.5.6",
+        resolved:
+          "https://registry.npmjs.org/dependency/-/dependency-4.5.6.tgz",
+        integrity,
+        libc: ["musl", "glibc"],
+      },
+    },
+  };
+}
+
+describe("runtime dependency graph protocol", () => {
+  test("matches the daemon's canonical graph digest", () => {
+    const lock = dependencyLock();
+    const canonical = [
+      {
+        location: "node_modules/dependency",
+        version: "4.5.6",
+        resolved:
+          "https://registry.npmjs.org/dependency/-/dependency-4.5.6.tgz",
+        integrity,
+        optional: false,
+        os: [],
+        cpu: [],
+        libc: ["glibc", "musl"],
+      },
+    ];
+    const expected = `sha512-${createHash("sha512")
+      .update(JSON.stringify(canonical))
+      .digest("base64")}`;
+
+    expect(canonicalRuntimeGraph(lock)).toEqual(canonical);
+    expect(runtimeGraphDigest(lock)).toBe(expected);
+  });
+
+  test("includes libc compatibility in the canonical digest", () => {
+    const multiLibcLock = dependencyLock();
+    const muslOnlyLock = dependencyLock();
+    muslOnlyLock.packages["node_modules/dependency"].libc = ["musl"];
+
+    expect(runtimeGraphDigest(multiLibcLock)).not.toBe(
+      runtimeGraphDigest(muslOnlyLock),
+    );
+  });
+
+  test("verifies the release manifest declaration and shrinkwrap root", () => {
+    const lock = dependencyLock();
+    const digest = runtimeGraphDigest(lock);
+
+    expect(
+      verifyRuntimeGraph(
+        {
+          name: "@letta-ai/letta-code",
+          version: "1.2.3",
+          dependencies: { dependency: "^4.0.0" },
+          optionalDependencies: {},
+          lettaRuntimeGraphProtocol: 1,
+          lettaRuntimeGraphSha512: digest,
+        },
+        lock,
+      ),
+    ).toBe(digest);
+  });
+
+  test("rejects mutable or non-canonical dependency artifacts", () => {
+    const lock = dependencyLock();
+    lock.packages["node_modules/dependency"].resolved =
+      "https://registry.example.test/dependency.tgz";
+
+    expect(() => runtimeGraphDigest(lock)).toThrow(/not canonical/);
+  });
+
+  test("rejects a stale release declaration", () => {
+    const lock = dependencyLock();
+
+    expect(() =>
+      verifyRuntimeGraph(
+        {
+          name: "@letta-ai/letta-code",
+          version: "1.2.3",
+          dependencies: { dependency: "^4.0.0" },
+          optionalDependencies: {},
+          lettaRuntimeGraphProtocol: 1,
+          lettaRuntimeGraphSha512: `sha512-${Buffer.alloc(64).toString("base64")}`,
+        },
+        lock,
+      ),
+    ).toThrow(/declaration is stale/);
+  });
+});

package/scripts/runtime-graph.ts

@@ -0,0 +1,366 @@
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export const RUNTIME_GRAPH_PROTOCOL = 1;
+export const RUNTIME_GRAPH_NPM_VERSION = "12.2.0";
+export const RUNTIME_GRAPH_BUN_VERSION = "1.3.14";
+const PACKAGE_PATH = new URL("../package.json", import.meta.url);
+const SHRINKWRAP_PATH = new URL("../npm-shrinkwrap.json", import.meta.url);
+const REGISTRY_HOST = "registry.npmjs.org";
+const SHA512_PATTERN = /^sha512-([A-Za-z0-9+/]+={0,2})$/;
+
+type PackageManifest = {
+  name: string;
+  version: string;
+  dependencies?: Record<string, string>;
+  optionalDependencies?: Record<string, string>;
+  engines?: Record<string, string>;
+  lettaRuntimeGraphProtocol?: number;
+  lettaRuntimeGraphSha512?: string;
+  [key: string]: unknown;
+};
+
+type LockEntry = {
+  version?: string;
+  resolved?: string;
+  integrity?: string;
+  optional?: boolean;
+  os?: string[];
+  cpu?: string[];
+  libc?: string[];
+  link?: boolean;
+  dependencies?: Record<string, string>;
+  optionalDependencies?: Record<string, string>;
+};
+
+type DependencyLock = {
+  name?: string;
+  version?: string;
+  lockfileVersion?: number;
+  packages?: Record<string, LockEntry>;
+};
+
+type CanonicalGraphEntry = {
+  location: string;
+  version: string;
+  resolved: string;
+  integrity: string;
+  optional: boolean;
+  os: string[];
+  cpu: string[];
+  libc: string[];
+};
+
+function hasSha512Integrity(value: unknown): value is string {
+  if (typeof value !== "string") return false;
+  const match = SHA512_PATTERN.exec(value);
+  return Boolean(match && Buffer.from(match[1], "base64").byteLength === 64);
+}
+
+export function canonicalRuntimeGraph(
+  lock: DependencyLock,
+): CanonicalGraphEntry[] {
+  if (lock.lockfileVersion !== 3 || !lock.packages) {
+    throw new Error(
+      "npm-shrinkwrap.json must contain a lockfileVersion 3 package graph",
+    );
+  }
+
+  const graph: CanonicalGraphEntry[] = [];
+  for (const [location, entry] of Object.entries(lock.packages)) {
+    if (!location) continue;
+    if (entry.link || typeof entry.version !== "string") {
+      throw new Error(`Dependency graph entry ${location} is not immutable`);
+    }
+    if (typeof entry.resolved !== "string") {
+      throw new Error(
+        `Dependency graph entry ${location} has no resolved artifact`,
+      );
+    }
+    const resolved = new URL(entry.resolved);
+    if (
+      resolved.protocol !== "https:" ||
+      resolved.hostname !== REGISTRY_HOST ||
+      resolved.username ||
+      resolved.password ||
+      resolved.port ||
+      resolved.search ||
+      resolved.hash
+    ) {
+      throw new Error(`Dependency graph entry ${location} is not canonical`);
+    }
+    if (!hasSha512Integrity(entry.integrity)) {
+      throw new Error(
+        `Dependency graph entry ${location} lacks SHA-512 integrity`,
+      );
+    }
+    graph.push({
+      location,
+      version: entry.version,
+      resolved: entry.resolved,
+      integrity: entry.integrity,
+      optional: entry.optional === true,
+      os: Array.isArray(entry.os) ? entry.os : [],
+      cpu: Array.isArray(entry.cpu) ? entry.cpu : [],
+      libc: Array.isArray(entry.libc) ? [...entry.libc].sort() : [],
+    });
+  }
+
+  graph.sort((left, right) => left.location.localeCompare(right.location));
+  return graph;
+}
+
+export function runtimeGraphDigest(lock: DependencyLock): string {
+  const graph = canonicalRuntimeGraph(lock);
+  return `sha512-${createHash("sha512").update(JSON.stringify(graph)).digest("base64")}`;
+}
+
+function productionManifest(manifest: PackageManifest): PackageManifest {
+  return {
+    name: manifest.name,
+    version: manifest.version,
+    dependencies: manifest.dependencies ?? {},
+    optionalDependencies: manifest.optionalDependencies ?? {},
+    engines: manifest.engines ?? {},
+  };
+}
+
+function sameRecord(
+  left: Record<string, string> | undefined,
+  right: Record<string, string> | undefined,
+): boolean {
+  const entries = (value: Record<string, string> | undefined) =>
+    Object.entries(value ?? {}).sort(([leftKey], [rightKey]) =>
+      leftKey.localeCompare(rightKey),
+    );
+  return JSON.stringify(entries(left)) === JSON.stringify(entries(right));
+}
+
+export function verifyRuntimeGraph(
+  manifest: PackageManifest,
+  lock: DependencyLock,
+): string {
+  const root = lock.packages?.[""];
+  if (
+    lock.name !== manifest.name ||
+    lock.version !== manifest.version ||
+    root?.name !== manifest.name ||
+    root?.version !== manifest.version ||
+    !sameRecord(root.dependencies, manifest.dependencies) ||
+    !sameRecord(root.optionalDependencies, manifest.optionalDependencies)
+  ) {
+    throw new Error("npm-shrinkwrap.json root does not match package.json");
+  }
+  const digest = runtimeGraphDigest(lock);
+  if (
+    manifest.lettaRuntimeGraphProtocol !== RUNTIME_GRAPH_PROTOCOL ||
+    manifest.lettaRuntimeGraphSha512 !== digest
+  ) {
+    throw new Error(
+      `package.json runtime graph declaration is stale (expected ${digest})`,
+    );
+  }
+  return digest;
+}
+
+async function readJson<T>(url: URL): Promise<T> {
+  return JSON.parse(await readFile(url, "utf8")) as T;
+}
+
+async function runNpm(args: string[], cwd: string): Promise<string> {
+  return new Promise<string>((resolve, reject) => {
+    const child = spawn(
+      process.platform === "win32" ? "npm.cmd" : "npm",
+      args,
+      {
+        cwd,
+        stdio: ["ignore", "pipe", "inherit"],
+        env: {
+          ...process.env,
+          npm_config_registry: "https://registry.npmjs.org",
+          npm_config_ignore_scripts: "true",
+          npm_config_audit: "false",
+          npm_config_fund: "false",
+        },
+      },
+    );
+    let stdout = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += String(chunk);
+    });
+    child.once("error", reject);
+    child.once("exit", (code, signal) => {
+      if (code === 0) resolve(stdout.trim());
+      else
+        reject(
+          new Error(`npm exited with ${signal ?? code ?? "unknown status"}`),
+        );
+    });
+  });
+}
+
+async function runBun(args: string[], cwd: string): Promise<string> {
+  return new Promise<string>((resolve, reject) => {
+    const child = spawn(
+      process.platform === "win32" ? "bun.exe" : "bun",
+      args,
+      {
+        cwd,
+        stdio: ["ignore", "pipe", "inherit"],
+      },
+    );
+    let stdout = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += String(chunk);
+    });
+    child.once("error", reject);
+    child.once("exit", (code, signal) => {
+      if (code === 0) resolve(stdout.trim());
+      else
+        reject(
+          new Error(`bun exited with ${signal ?? code ?? "unknown status"}`),
+        );
+    });
+  });
+}
+
+async function assertExactToolchain(cwd: string): Promise<void> {
+  const [npmVersion, bunVersion] = await Promise.all([
+    runNpm(["--version"], cwd),
+    runBun(["--version"], cwd),
+  ]);
+  if (npmVersion !== RUNTIME_GRAPH_NPM_VERSION) {
+    throw new Error(
+      `runtime graph generation requires npm ${RUNTIME_GRAPH_NPM_VERSION}, found ${npmVersion}`,
+    );
+  }
+  if (bunVersion !== RUNTIME_GRAPH_BUN_VERSION) {
+    throw new Error(
+      `runtime graph generation requires Bun ${RUNTIME_GRAPH_BUN_VERSION}, found ${bunVersion}`,
+    );
+  }
+}
+
+async function generateRuntimeGraph(): Promise<string> {
+  const manifest = await readJson<PackageManifest>(PACKAGE_PATH);
+  const staging = await mkdtemp(join(tmpdir(), "letta-runtime-graph-"));
+  const runtimeRoot = join(staging, "runtime");
+  const installerRoot = join(staging, "installer");
+  try {
+    await assertExactToolchain(staging);
+    await Promise.all([
+      mkdir(runtimeRoot, { recursive: true }),
+      mkdir(installerRoot, { recursive: true }),
+    ]);
+    await writeFile(
+      join(runtimeRoot, "package.json"),
+      `${JSON.stringify(productionManifest(manifest), null, 2)}\n`,
+    );
+    try {
+      const existing = await readFile(SHRINKWRAP_PATH);
+      await writeFile(join(runtimeRoot, "npm-shrinkwrap.json"), existing);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+
+    const packOutput = await runBun(
+      [
+        "pm",
+        "pack",
+        "--quiet",
+        "--ignore-scripts",
+        "--destination",
+        installerRoot,
+      ],
+      runtimeRoot,
+    );
+    const packedPath = packOutput
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .find((line) => line.endsWith(".tgz"));
+    const tarball = packedPath?.split(/[\\/]/).pop();
+    if (!tarball)
+      throw new Error("bun pm pack did not produce a runtime tarball");
+    await writeFile(
+      join(installerRoot, "package.json"),
+      `${JSON.stringify(
+        {
+          private: true,
+          dependencies: {
+            [manifest.name]: `file:${tarball}`,
+          },
+        },
+        null,
+        2,
+      )}\n`,
+    );
+    await runNpm(
+      [
+        "install",
+        "--package-lock-only",
+        "--ignore-scripts",
+        "--no-audit",
+        "--no-fund",
+      ],
+      installerRoot,
+    );
+    const outerLock = JSON.parse(
+      await readFile(join(installerRoot, "package-lock.json"), "utf8"),
+    ) as DependencyLock;
+    const runtimeLocation = `node_modules/${manifest.name}`;
+    const packages = { ...outerLock.packages };
+    delete packages[""];
+    delete packages[runtimeLocation];
+    packages[""] = {
+      name: manifest.name,
+      version: manifest.version,
+      dependencies: manifest.dependencies ?? {},
+      optionalDependencies: manifest.optionalDependencies ?? {},
+    };
+    const lock: DependencyLock = {
+      name: manifest.name,
+      version: manifest.version,
+      lockfileVersion: 3,
+      packages,
+    };
+    const digest = runtimeGraphDigest(lock);
+    manifest.lettaRuntimeGraphProtocol = RUNTIME_GRAPH_PROTOCOL;
+    manifest.lettaRuntimeGraphSha512 = digest;
+    await writeFile(SHRINKWRAP_PATH, `${JSON.stringify(lock, null, 2)}\n`);
+    await writeFile(PACKAGE_PATH, `${JSON.stringify(manifest, null, 2)}\n`);
+    return digest;
+  } finally {
+    await rm(staging, { recursive: true, force: true });
+  }
+}
+
+async function verifyFiles(): Promise<string> {
+  const [manifest, lock] = await Promise.all([
+    readJson<PackageManifest>(PACKAGE_PATH),
+    readJson<DependencyLock>(SHRINKWRAP_PATH),
+  ]);
+  return verifyRuntimeGraph(manifest, lock);
+}
+
+async function main(): Promise<void> {
+  const command = process.argv[2] ?? "verify";
+  const digest =
+    command === "generate"
+      ? await generateRuntimeGraph()
+      : command === "verify"
+        ? await verifyFiles()
+        : (() => {
+            throw new Error(`Unknown runtime graph command: ${command}`);
+          })();
+  console.log(`Runtime dependency graph verified: ${digest}`);
+}
+
+if (import.meta.main) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}

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

@@ -40,5 +40,5 @@
   "src/websocket/listen-client-protocol.test.ts": 5707,
   "src/websocket/listener/commands/memory.ts": 1114,
   "src/websocket/listener/file-commands.ts": 1053,
-  "src/websocket/listener/protocol-inbound.ts": 2062
+  "src/websocket/listener/protocol-inbound.ts": 2061
 }