@letta-ai/letta-code 0.26.1 → 0.26.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.26.1",
+  "version": "0.26.2",
   "description": "Letta Code is a CLI tool for interacting with stateful Letta agents from the terminal.",
   "type": "module",
   "packageManager": "bun@1.3.0",
@@ -29,7 +29,7 @@
   },
   "license": "Apache-2.0",
   "engines": {
-    "node": ">=18"
+    "node": ">=22.19.0"
   },
   "publishConfig": {
     "access": "public"
@@ -40,6 +40,7 @@
     "ink-link": "^5.0.0",
     "node-pty": "^1.1.0",
     "open": "^10.2.0",
+    "react": "18.2.0",
     "sharp": "^0.34.5",
     "shiki": "^4.0.2",
     "strip-ansi": "^7.2.0",
@@ -49,7 +50,7 @@
     "@vscode/ripgrep": "^1.17.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.74.0",
+    "@earendil-works/pi-ai": "^0.75.5",
     "@slack/bolt": "^4.7.0",
     "@types/bun": "^1.3.7",
     "@types/diff": "^8.0.0",
@@ -66,7 +67,6 @@
     "madge": "^8.0.0",
     "minimatch": "^10.0.3",
     "picomatch": "^2.3.1",
-    "react": "18.2.0",
     "typescript": "^5.0.0"
   },
   "scripts": {
@@ -79,6 +79,7 @@
     "check:exported-functions": "node scripts/check-exported-functions.js",
     "check:filename-casing": "node scripts/check-filename-casing.js",
     "check:test-mock-isolation": "bun run scripts/check-test-mock-isolation.js",
+    "check:test-coverage": "node scripts/check-test-coverage.cjs",
     "check": "bun run scripts/check.js",
     "dev": "LETTA_DEBUG=${LETTA_DEBUG:-1} LETTA_RESPONSES_WS=${LETTA_RESPONSES_WS:-1} bun --loader=.md:text --loader=.mdx:text --loader=.txt:text run src/index.ts",
     "build": "node scripts/postinstall-patches.js && bun run build.js",

package/scripts/check-test-coverage.cjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+
+/**
+ * Detects test files (*.test.ts, *.test.tsx) under src/ that are NOT covered
+ * by the CI unit test runner (scripts/run-unit-tests.cjs).
+ *
+ * This catches two problems:
+ *   1. A new src/ directory gets test files but nobody updates the dirs list
+ *      in run-unit-tests.cjs, so those tests silently stop running in CI.
+ *   2. Tests are added to forbidden directories (e.g. src/tests) instead of
+ *      being collocated with their source files.
+ *
+ * Excluded by design:
+ *   src/integration-tests — API-gated, run separately in CI
+ *   src/channels — special-cased in run-unit-tests.cjs (isolation requirements)
+ */
+
+const { readdirSync, existsSync } = require("node:fs");
+const path = require("node:path");
+
+// ---- Collect all test files under src/ ----
+function findTestFiles(dir) {
+  const results = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...findTestFiles(full));
+    } else if (
+      entry.name.endsWith(".test.ts") ||
+      entry.name.endsWith(".test.tsx")
+    ) {
+      results.push(full.replace(/\\/g, "/"));
+    }
+  }
+  return results;
+}
+
+const allTestFiles = findTestFiles("src");
+
+// ---- Forbidden directories ----
+// Tests must be collocated with their source (e.g. src/cli/components/Foo.test.tsx),
+// not in a separate test directory.
+const FORBIDDEN_DIRS = ["src/tests"];
+
+const forbiddenFiles = allTestFiles.filter((f) =>
+  FORBIDDEN_DIRS.some(
+    (prefix) => f === prefix || f.startsWith(prefix + "/"),
+  ),
+);
+
+if (forbiddenFiles.length > 0) {
+  console.error(
+    `check-test-coverage: ${forbiddenFiles.length} test file(s) in forbidden directory:`,
+  );
+  for (const file of forbiddenFiles) {
+    console.error(`  ${file}`);
+  }
+  console.error(
+    "\nTests must be collocated with their source files, not in src/tests/.",
+  );
+  console.error(
+    "Move the test next to the module it tests (e.g. src/cli/components/Foo.test.tsx).",
+  );
+  process.exit(1);
+}
+
+// ---- Determine which directories/patterns CI covers ----
+// These must match scripts/run-unit-tests.cjs
+const ciDirs = [
+  "src/agent",
+  "src/auth",
+  "src/backend",
+  "src/cli",
+  "src/cron",
+  "src/experiments",
+  "src/extensions",
+  "src/hooks",
+  "src/lsp",
+  "src/permissions",
+  "src/providers",
+  "src/queue",
+  "src/reminders",
+  "src/skills",
+  "src/telemetry",
+  "src/test-utils",
+  "src/tools",
+  "src/types",
+  "src/updater",
+  "src/utils",
+  "src/web",
+  "src/websocket",
+];
+
+// Special cases: channels is run separately, integration-tests is API-gated
+const specialDirs = ["src/channels", "src/integration-tests"];
+
+// Root-level: src/*.test.ts is covered by glob
+const coveredPrefixes = [...ciDirs, ...specialDirs];
+
+function isCovered(file) {
+  // Root-level src/*.test.ts files (no subdirectory)
+  if (/^src\/[^/]+\.test\.tsx?$/.test(file)) return true;
+
+  return coveredPrefixes.some(
+    (prefix) => file === prefix || file.startsWith(prefix + "/"),
+  );
+}
+
+// ---- Report ----
+const uncovered = allTestFiles.filter((f) => !isCovered(f));
+
+if (uncovered.length === 0) {
+  console.log(
+    `check-test-coverage: all ${allTestFiles.length} test files are covered by CI`,
+  );
+  process.exit(0);
+}
+
+console.error(
+  `check-test-coverage: ${uncovered.length} test file(s) not covered by CI:`,
+);
+for (const file of uncovered) {
+  console.error(`  ${file}`);
+}
+console.error(
+  "\nAdd the parent directory to the 'dirs' list in scripts/run-unit-tests.cjs,",
+);
+console.error(
+  "or add it to 'specialDirs' in scripts/check-test-coverage.cjs if it's run separately.",
+);
+process.exit(1);

package/scripts/check.js

@@ -18,6 +18,7 @@ const checks = [
   { name: "exported function style", script: ["check:exported-functions"] },
   { name: "filename casing", script: ["check:filename-casing"] },
   { name: "test mock isolation", script: ["check:test-mock-isolation"] },
+  { name: "test coverage", script: ["check:test-coverage"] },
   { name: "biome", script: ["lint"] },
   { name: "typescript", script: ["typecheck"] },
 ];

package/scripts/run-unit-tests.cjs

@@ -13,6 +13,7 @@ const dirs = [
   "src/cli",
   "src/cron",
   "src/experiments",
+  "src/extensions",
   "src/hooks",
   "src/lsp",
   "src/permissions",
@@ -26,6 +27,7 @@ const dirs = [
   "src/types",
   "src/updater",
   "src/utils",
+  "src/web",
   "src/websocket",
   // Root-level test files (not inside a subdirectory)
   "src/*.test.ts",

package/skills/creating-extensions/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: creating-extensions
+description: Creates and edits Letta Code local extensions, including extension tools, slash commands, panels, status values, and capability-gated behavior. Use when the user asks to make an extension, add a tool the agent can call, add a slash command, or add lightweight extension UI outside the dedicated /statusline flow.
+---
+
+# Creating Extensions
+
+Use this skill to create or update trusted global Letta Code extensions in:
+
+```text
+~/.letta/extensions/
+```
+
+Extensions are local runtime capabilities, not TUI-only plugins. Prefer portable APIs and guard optional UI with `letta.capabilities`.
+
+## Choose the right capability
+
+| User wants | Build |
+| --- | --- |
+| Agent/model should autonomously call a local capability | Extension tool |
+| User wants `/foo` to send a prompt or run local UI logic | Extension command |
+| Slash command represents a reusable agent workflow | Skill + thin extension command |
+| Show transient output above input | Panel, usually from a command |
+| Show small persistent state | Status value |
+| Change the bottom statusline appearance | Use `customizing-statusline`, not this skill |
+
+Default to a **tool** when the model should decide when to use the capability. Default to a **command** when the human explicitly invokes it.
+
+## Workflow
+
+1. Inspect `~/.letta/extensions/` for related files.
+2. Preserve unrelated extension code. Prefer a focused new file if merging would be messy.
+3. Choose one capability recipe:
+   - tools: `references/tools.md`
+   - commands: `references/commands.md`
+   - panels/status/capabilities: `references/ui.md`
+4. Write a single-file extension unless the user asks for something larger.
+5. Return disposers for registered commands/tools, timers, subscriptions, and panels that should close on reload.
+6. Do a basic syntax/shape review: valid names, descriptions present, JSON schemas are object schemas, capability guards around optional UI.
+7. Tell the user the absolute file path changed and to run `/reload`.
+
+## Core extension shape
+
+```ts
+export default function activate(letta) {
+  const disposers = [];
+
+  if (letta.capabilities.tools) {
+    disposers.push(letta.tools.register(/* ... */));
+  }
+
+  if (letta.capabilities.commands) {
+    disposers.push(letta.commands.register(/* ... */));
+  }
+
+  return () => {
+    for (const dispose of disposers.reverse()) dispose();
+  };
+}
+```
+
+Use `letta.capabilities` for optional behavior:
+
+```ts
+letta.capabilities.tools
+letta.capabilities.commands
+letta.capabilities.ui.panels
+letta.capabilities.ui.statusValues
+letta.capabilities.ui.customStatuslineRenderer
+```
+
+## Rules
+
+- Global trusted code only for now. Do not create project extensions.
+- Do not import Letta Code app internals from extension files.
+- Do not assume extra npm packages are available.
+- Do not do surprising side effects on startup; extensions activate on app start and `/reload`.
+- Keep user-facing output short and intentional.
+- Prefer Node/Bun standard APIs (`node:child_process`, `node:fs`, etc.) for local work.
+- For shell execution, prefer `execFile`/`spawn` over shell strings.
+- Do not use emojis for loading states; use text or spinner-like characters if the user asks for loading UI.
+
+## References
+
+- `references/tools.md` - extension tools the model can call
+- `references/commands.md` - slash commands, command results, and skill-backed commands
+- `references/ui.md` - panels, status values, capability guards

package/skills/creating-extensions/references/btw-command.md

@@ -0,0 +1,90 @@
+# `/btw` side-question extension example
+
+This example runs while the main agent is busy because it forks the conversation, uses the SDK directly, renders progress in a panel when panels are available, and returns `{ type: "handled" }` immediately.
+
+```ts
+export default function activate(letta) {
+  if (!letta.capabilities.commands) return;
+
+  function appendAssistantText(chunk, parts) {
+    if (chunk.message_type !== "assistant_message") return;
+    const content = chunk.content;
+    if (typeof content === "string") {
+      parts.push(content);
+      return;
+    }
+    if (Array.isArray(content)) {
+      for (const part of content) {
+        if (part && typeof part === "object" && "text" in part) {
+          parts.push(String(part.text));
+        }
+      }
+    }
+  }
+
+  function openPanelOrNull(content) {
+    if (!letta.capabilities.ui.panels) return null;
+    return letta.ui.openPanel({ id: "btw", content });
+  }
+
+  return letta.commands.register({
+    id: "btw",
+    description: "Ask a side question in a forked conversation",
+    args: "<question>",
+    runWhenBusy: true,
+    showInTranscript: false,
+    run(ctx) {
+      const question = ctx.args.trim();
+      if (!question) {
+        const panel = openPanelOrNull(["/btw", "Usage: /btw <question>"]);
+        if (panel) setTimeout(() => panel.close(), 5_000);
+        return { type: "handled" };
+      }
+
+      const panel = openPanelOrNull([`/btw ${question}`, "..."]);
+
+      void (async () => {
+        try {
+          const forked = await letta.client.conversations.fork(
+            ctx.conversation.id || "default",
+            { agent_id: ctx.agent.id },
+          );
+          const stream = await letta.client.conversations.messages.create(
+            forked.id,
+            {
+              agent_id: ctx.agent.id,
+              input: `${question}
+
+Answer briefly in 1-3 short sentences.`,
+              streaming: true,
+            },
+          );
+
+          const parts = [];
+          for await (const chunk of stream) {
+            appendAssistantText(chunk, parts);
+            panel?.update({ content: [`/btw ${question}`, parts.join("") || "..."] });
+          }
+
+          panel?.update({
+            content: [`done /btw ${question}`, parts.join("").trim() || "No response."],
+          });
+          if (panel) setTimeout(() => panel.close(), 10_000);
+        } catch (error) {
+          panel?.update({
+            content: [
+              `error /btw ${question}`,
+              error instanceof Error ? error.message : String(error),
+            ],
+          });
+          if (panel) setTimeout(() => panel.close(), 15_000);
+        }
+      })();
+
+      return { type: "handled" };
+    },
+  });
+}
+```
+
+Add custom borders, right alignment, wrapping, or history only if the user asks for that polish.

package/skills/creating-extensions/references/commands.md

@@ -0,0 +1,114 @@
+# Extension command recipes
+
+Use commands when the human explicitly invokes `/foo`.
+
+## Decide command vs skill vs tool
+
+| Need | Use |
+| --- | --- |
+| `/foo` expands to a prompt | Extension command |
+| `/foo` starts a complex reusable workflow | Skill + thin extension command |
+| Model should call the capability by itself | Extension tool |
+| Command needs transient UI while doing local work | Extension command + panel |
+
+If the command represents a durable agent workflow (for example `/goal`), put the workflow instructions in a skill and keep the command as a small launcher/prompt.
+
+## Command IDs
+
+- Do not include the leading slash. Use `id: "review"`, not `id: "/review"`.
+- Use a lowercase slug with letters, numbers, and hyphens only.
+- Built-in commands like `/reload`, `/model`, `/statusline`, etc. are reserved.
+- Duplicate extension command IDs fail unless `override: true` is intentional.
+
+## Prompt command
+
+```ts
+export default function activate(letta) {
+  if (!letta.capabilities.commands) return;
+
+  return letta.commands.register({
+    id: "review",
+    description: "Review current git changes",
+    args: "[focus]",
+    run(ctx) {
+      const focus = ctx.args.trim();
+      return {
+        type: "prompt",
+        content: focus
+          ? `Review current git changes. Focus on ${focus}.`
+          : "Review current git changes. Focus on correctness issues.",
+        systemReminder: true,
+      };
+    },
+  });
+}
+```
+
+## Output-only command
+
+```ts
+export default function activate(letta) {
+  if (!letta.capabilities.commands) return;
+
+  return letta.commands.register({
+    id: "whereami",
+    description: "Show the active extension command context",
+    run(ctx) {
+      return {
+        type: "output",
+        output: `Agent: ${ctx.agent.name ?? ctx.agent.id}\nCWD: ${ctx.cwd}`,
+      };
+    },
+  });
+}
+```
+
+## Panel command
+
+Use `{ type: "handled" }` when the command owns the UI. Guard panels because they are optional on non-TUI surfaces.
+
+```ts
+export default function activate(letta) {
+  if (!letta.capabilities.commands) return;
+
+  return letta.commands.register({
+    id: "hello-panel",
+    description: "Show a short transient panel",
+    showInTranscript: false,
+    run(ctx) {
+      if (!letta.capabilities.ui.panels) {
+        return { type: "output", output: `hello ${ctx.args || "there"}` };
+      }
+
+      const panel = letta.ui.openPanel({
+        id: "hello-panel",
+        content: [`hello ${ctx.args || "there"}`],
+      });
+      setTimeout(() => panel.close(), 5_000);
+      return { type: "handled" };
+    },
+  });
+}
+```
+
+## Busy-safe SDK command
+
+For commands with `runWhenBusy: true`, do not return `prompt` while the agent is running. Use the SDK directly, update a panel if available, and return `{ type: "handled" }` quickly.
+
+Use `letta.client` or `await letta.getClient()` instead of raw `fetch`; SDK initialization is lazy and uses the current backend/auth context.
+
+Common calls:
+
+```ts
+await letta.client.conversations.fork(ctx.conversation.id || "default", {
+  agent_id: ctx.agent.id,
+});
+
+await letta.client.conversations.messages.create(conversationId, {
+  agent_id: ctx.agent.id,
+  input,
+  streaming: true,
+});
+```
+
+For a complete side-question example, see `btw-command.md`.

package/skills/creating-extensions/references/tools.md

@@ -0,0 +1,115 @@
+# Extension tool recipes
+
+Use tools when the agent/model should call a local capability autonomously.
+
+## Defaults
+
+- Name: lowercase/underscore tool name, e.g. `branch_summary`.
+- Description: explain when the model should use it.
+- Parameters: JSON Schema object. Use `additionalProperties: false` when possible.
+- `requiresApproval: false` only for read-only, low-risk local introspection.
+- `parallelSafe: true` only for read-only tools with no shared mutation or long-lived exclusive resource.
+- Use `ctx.cwd` / `ctx.workingDirectory` as the workspace.
+- Respect `ctx.signal` for long-running work when practical.
+
+## Read-only shell tool
+
+```ts
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export default function activate(letta) {
+  if (!letta.capabilities.tools) return;
+
+  return letta.tools.register({
+    name: "branch_summary",
+    description: "Summarize the current git branch, working tree status, and recent commits.",
+    parameters: {
+      type: "object",
+      properties: {},
+      additionalProperties: false,
+    },
+    requiresApproval: false,
+    parallelSafe: true,
+    async run(ctx) {
+      const [{ stdout: status }, { stdout: log }] = await Promise.all([
+        execFileAsync("git", ["status", "--short", "--branch"], { cwd: ctx.cwd }),
+        execFileAsync("git", ["log", "--oneline", "-5"], { cwd: ctx.cwd }),
+      ]);
+
+      return ["## Branch", status.trim(), "", "## Recent commits", log.trim()].join("\n");
+    },
+  });
+}
+```
+
+## Tool with arguments
+
+```ts
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export default function activate(letta) {
+  if (!letta.capabilities.tools) return;
+
+  return letta.tools.register({
+    name: "repo_notes_search",
+    description: "Search local repo notes for a query and return matching snippets.",
+    parameters: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Search query" },
+      },
+      required: ["query"],
+      additionalProperties: false,
+    },
+    requiresApproval: false,
+    parallelSafe: true,
+    async run(ctx) {
+      const query = String(ctx.args.query ?? "").trim();
+      if (!query) return { status: "error", content: "query is required" };
+
+      try {
+        const { stdout } = await execFileAsync(
+          "rg",
+          ["--line-number", "--max-count", "20", query, "notes"],
+          { cwd: ctx.cwd },
+        );
+        return stdout.trim() || "No matches.";
+      } catch (error) {
+        if (error && typeof error === "object" && "code" in error && error.code === 1) {
+          return "No matches.";
+        }
+        throw error;
+      }
+    },
+  });
+}
+```
+
+## Mutating or risky tool
+
+Set approval required and avoid `parallelSafe` unless it is truly safe:
+
+```ts
+letta.tools.register({
+  name: "format_file",
+  description: "Format a specific file in the current workspace.",
+  parameters: {
+    type: "object",
+    properties: { path: { type: "string" } },
+    required: ["path"],
+    additionalProperties: false,
+  },
+  requiresApproval: true,
+  parallelSafe: false,
+  async run(ctx) {
+    // mutate only the requested file, with clear output
+    return "formatted";
+  },
+});
+```

package/skills/creating-extensions/references/ui.md

@@ -0,0 +1,65 @@
+# Extension UI recipes
+
+UI capabilities are optional. Always guard UI work with `letta.capabilities.ui.*` when writing portable extensions.
+
+## Capabilities
+
+```ts
+letta.capabilities.ui.panels
+letta.capabilities.ui.statusValues
+letta.capabilities.ui.customStatuslineRenderer
+```
+
+- `panels`: transient text blocks above the input bar.
+- `statusValues`: small named status data that renderers or future surfaces can display.
+- `customStatuslineRenderer`: TUI-only custom bottom-row renderer. Use `customizing-statusline` for statusline work.
+
+## Panels
+
+```ts
+if (letta.capabilities.ui.panels) {
+  const panel = letta.ui.openPanel({
+    id: "my-extension",
+    content: ["Working…"],
+    order: 100,
+  });
+
+  panel.update({ content: ["Done"] });
+  setTimeout(() => panel.close(), 5_000);
+}
+```
+
+Panel content is plain text: a string or string array. Keep it short; use command `output` for longer text.
+
+## Status values
+
+```ts
+if (letta.capabilities.ui.statusValues) {
+  letta.ui.setStatus("branch", "main");
+}
+```
+
+Clear status values in disposers if they are owned by timers or external state:
+
+```ts
+return () => {
+  letta.ui.clearStatus("branch");
+};
+```
+
+## Timers and cleanup
+
+```ts
+export default function activate(letta) {
+  if (!letta.capabilities.ui.statusValues) return;
+
+  const update = () => letta.ui.setStatus("clock", new Date().toLocaleTimeString());
+  update();
+  const timer = setInterval(update, 30_000);
+
+  return () => {
+    clearInterval(timer);
+    letta.ui.clearStatus("clock");
+  };
+}
+```