@letta-ai/letta-code 0.27.16 → 0.27.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.27.16",
+  "version": "0.27.18",
   "description": "Letta Code is a CLI tool for interacting with stateful Letta agents from the terminal.",
   "type": "module",
   "packageManager": "bun@1.3.0",

package/scripts/check-layer-boundaries.js

@@ -63,6 +63,23 @@ const RULES = [
     description:
       "telemetry/ is a leaf observer — it must not import from cli/, agent/, websocket/, or tools/ (only backend/api/ for submitting data is permitted)",
   },
+  {
+    layer: "sandbox",
+    forbidden: [
+      "cli",
+      "agent",
+      "tools",
+      "websocket",
+      "backend",
+      "providers",
+      "permissions",
+      "channels",
+      "cron",
+      "telemetry",
+    ],
+    description:
+      "sandbox/ is a pure leaf — it generates sandbox argv/profiles from plain paths. It must not import from any domain layer; callers resolve paths and pass them in",
+  },
 ];
 
 // Matches: import ... from "@/forbidden/..." (static imports only)

package/scripts/check-test-coverage.cjs

@@ -80,6 +80,7 @@ const ciDirs = [
   "src/providers",
   "src/queue",
   "src/reminders",
+  "src/sandbox",
   "src/skills",
   "src/telemetry",
   "src/test-utils",

package/scripts/run-unit-tests.cjs

@@ -20,6 +20,7 @@ const dirs = [
   "src/providers",
   "src/queue",
   "src/reminders",
+  "src/sandbox",
   "src/skills",
   "src/telemetry",
   "src/test-utils",

package/skills/creating-mods/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: creating-mods
-description: Creates and edits trusted local Letta Code mods, including tools, slash commands, local-only model providers, lifecycle/turn events, scoped conversation helpers, panels, status values, and capability-gated behavior. Use when asked to make a mod, add an agent-callable tool, add a slash command, add a local provider/model adapter, transform turns, react to app events, or add lightweight mod UI outside the dedicated /statusline flow.
+description: Creates and edits trusted local Letta Code mods, including tools, slash commands, local-only model providers, lifecycle/turn events, scoped conversation helpers, panels, and capability-gated behavior. Use when asked to make a mod, add an agent-callable tool, add a slash command, add a local provider/model adapter, transform turns, react to app events, or add lightweight mod UI outside the dedicated /statusline flow.
 ---
 
 # Creating Mods
 
-Use this skill to create or update trusted Letta Code mod files. Mods are trusted local code that add small composable capabilities through mod APIs, not by importing app internals. Dynamic agent/conversation/workspace/model state is passed as `ctx` to tool, command, event, permission, status, and statusline callbacks; do not read mutable global context for model-callable behavior. Prefer scoped handles (`ctx.conversation`, `ctx.cwd`, `ctx.agent`) and guard optional UI with `letta.capabilities`.
+Use this skill to create or update trusted Letta Code mod files. Mods are trusted local code that add small composable capabilities through mod APIs, not by importing app internals. Dynamic agent/conversation/workspace/model state is passed as `ctx` to tool, command, event, and permission callbacks (panels receive live `agent`/`model` in their render context); do not read mutable global context for model-callable behavior. Prefer scoped handles (`ctx.conversation`, `ctx.cwd`, `ctx.agent`) and guard optional UI with `letta.capabilities`.
 
 Capabilities vary by surface. TUI/headless may load tools, commands, events, UI, and providers; the desktop listener loads provider-only mods for local provider discovery. Always guard optional capabilities.
 
@@ -86,11 +86,11 @@ letta.capabilities.commands
 letta.capabilities.events.lifecycle
 letta.capabilities.events.tools
 letta.capabilities.events.turns
+letta.capabilities.events.compact
+letta.capabilities.events.llm
 letta.capabilities.permissions
 letta.capabilities.providers
 letta.capabilities.ui.panels
-letta.capabilities.ui.statusValues
-letta.capabilities.ui.customStatuslineRenderer
 ```
 
 ## Scoped API model
@@ -135,7 +135,7 @@ Before finishing, verify:
 - Command/tool IDs are valid; command overrides of built-ins are intentional, and tool IDs do not collide with built-ins.
 - Tool descriptions explain when the model should call them.
 - JSON schemas are object schemas with useful descriptions.
-- Optional UI/event/statusline APIs are capability-guarded.
+- Optional UI/event APIs are capability-guarded.
 - Provider mods are capability-guarded and clearly documented as local-agent only.
 - Timers, intervals, event registrations, and panels are cleaned up in a disposer.
 - Busy commands return `{ type: "handled" }` quickly and avoid main-conversation sends.
@@ -152,7 +152,7 @@ Before finishing, verify:
 | `references/providers.md` | Adding a custom model/API provider for local agents |
 | `references/events.md` | Reacting to lifecycle/tool/turn events or transforming turns/tools |
 | `references/permissions.md` | Enforcing dynamic tool allow/ask/deny policy before approval/execution |
-| `references/ui.md` | Panels, status values, or statusline capability guards are involved |
+| `references/ui.md` | Panels (including order-0 statusline) or `ui.panels` capability guards are involved |
 | `references/plan-mode.md` | Recreating plan mode with commands, tools, events, permissions, and local state |
 | `references/analysis-mode.md` | Phrase-triggered diagnostic mode with turn reminders (simpler than plan-mode) |
 | `references/architecture.md` | Multiple capabilities, local state, cleanup, background model work, or non-trivial composition |

package/skills/creating-mods/references/architecture.md

@@ -78,14 +78,22 @@ const stream = await forked.sendMessageStream([
 
 Do not call `ctx.conversation.sendMessageStream()` on the active conversation from a busy command; direct sends can conflict with the active run.
 
-### Event + status value
+### Event + panel
 
-Use lifecycle events to maintain small status values such as active conversation state. Guard both event and status capabilities.
+Use lifecycle events to maintain a small panel such as active conversation state. Guard both event and panel capabilities, and re-render with `panel.update()`.
 
 ```ts
-if (letta.capabilities.events.lifecycle && letta.capabilities.ui.statusValues) {
+if (letta.capabilities.events.lifecycle && letta.capabilities.ui.panels) {
+  let conversation = "";
+  const panel = letta.ui.openPanel({
+    id: "conversation",
+    order: 100,
+    render: ({ width, row }) => row("conversation", conversation, width),
+  });
+  disposers.push(() => panel.close());
   disposers.push(letta.events.on("conversation_open", (event) => {
-    letta.ui.setStatus("conversation", event.reason);
+    conversation = event.reason;
+    panel.update();
   }));
 }
 ```
@@ -126,10 +134,13 @@ ctx.conversation.id                 // string | null
 ctx.conversation.getHistory(opts)   // recent messages
 ctx.conversation.fork(opts)         // returns a scoped handle
 ctx.conversation.sendMessageStream(messages, opts)
+ctx.conversation.updateLlmConfig(opts) // change model / reasoning effort / context window
 ```
 
 A forked handle keeps the same agent/backend defaults and targets the forked conversation. Use forked handles for background model work. Use `getHistory({ limit, order, includeErrors })` when local logic needs conversation context.
 
+`updateLlmConfig({ model?, reasoningEffort?, contextWindow?, scope? })` changes the model, reasoning effort, and/or context window, and works across local and Constellation backends. Only the fields you pass change; the rest are preserved, so `updateLlmConfig({ contextWindow })` adjusts just the context window without touching the model or reasoning effort. `scope` defaults to `"conversation"` (a conversation-scoped override that leaves the agent's default untouched); pass `scope: "agent"` to change the agent default. Changing reasoning effort without a model resolves the current model to rebuild provider-specific settings. The change takes effect on the next turn (the model is resolved per provider request).
+
 Tools currently receive `ctx.conversation.getHistory()` but not fork/send helpers. If a tool needs model-side follow-up, return information for the model to act on instead of starting a hidden run from the tool.
 
 ## Error handling

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

@@ -96,9 +96,10 @@ export default function activate(letta) {
         return { type: "output", output: `hello ${ctx.args || "there"}` };
       }
 
+      const greeting = `hello ${ctx.args || "there"}`;
       const panel = letta.ui.openPanel({
         id: "hello-panel",
-        content: [`hello ${ctx.args || "there"}`],
+        render: () => greeting,
       });
       setTimeout(() => panel.close(), 5_000);
       return { type: "handled" };

package/skills/creating-mods/references/events.md

@@ -20,6 +20,8 @@ This is the first slice of the hooks-v2 direction. The long-term goal is for typ
 letta.capabilities.events.lifecycle
 letta.capabilities.events.tools
 letta.capabilities.events.turns
+letta.capabilities.events.compact
+letta.capabilities.events.llm
 ```
 
 Guard events when writing portable mods:
@@ -55,9 +57,11 @@ letta.events.on("tool_start", (event, ctx) => {
 });
 ```
 
-Lifecycle, turn-start, and tool-start events are wired today.
+Lifecycle, turn, tool, compaction, and llm events are wired today.
 
-Lifecycle handlers are notification-only and should not return values. `turn_start` handlers can transform the outbound input for the next model turn. `tool_start` handlers can transform the tool arguments before execution.
+Lifecycle handlers are notification-only and should not return values. `turn_start` handlers can transform the outbound input for the next model turn. `tool_start` handlers can transform the tool arguments before execution. Compaction and llm handlers are notification-only.
+
+`compact_start`/`compact_end` and `llm_start`/`llm_end` only fire on the **local backend**, where compaction and provider requests run client-side. On the constellation backend that work happens server-side and these events do not fire, so guard with `letta.capabilities.events.compact` / `letta.capabilities.events.llm` for portable mods.
 
 ## Supported events
 
@@ -65,7 +69,12 @@ Lifecycle handlers are notification-only and should not return values. `turn_sta
 "conversation_open"
 "conversation_close"
 "tool_start"
+"tool_end"
 "turn_start"
+"compact_start"
+"compact_end"
+"llm_start"
+"llm_end"
 ```
 
 `conversation_open` event:
@@ -138,6 +147,43 @@ Handlers run in registration order. Later handlers see the current args after ea
 
 `tool_start` is intentionally a trusted local mod point: it can rewrite commands, file paths, and other tool inputs before execution. Keep transforms focused and unsurprising.
 
+`tool_end` event:
+
+```ts
+{
+  agentId: string | null;
+  conversationId: string | null;
+  toolCallId: string | null;
+  toolName: string;
+  status: "success" | "error";
+  output: string;
+}
+```
+
+`tool_end` fires immediately after a tool produces a result, before the agent sees it. Handlers can inspect the result, or return `{ result: { status, output } }` to replace it:
+
+```ts
+letta.events.on("tool_end", (event) => {
+  if (event.toolName !== "Bash" || event.status !== "success") return;
+  return { result: { status: "success", output: redactSecrets(event.output) } };
+});
+```
+
+The first handler that returns a `result` wins; later handlers are shadowed. Only string results are surfaced — multimodal/image results pass through unchanged. `tool_end` is the trusted-local-mod equivalent of the `PostToolUse` / `PostToolUseFailure` hooks for observing and rewriting tool results.
+
+A handler can also react to a specific tool completing by adjusting conversation state. For example, switch model and reasoning effort when entering and exiting plan mode (`tool_end` fires only after the tool succeeds, so a denied approval won't switch):
+
+```ts
+letta.events.on("tool_end", async (event, ctx) => {
+  if (event.status !== "success") return;
+  if (event.toolName === "enter_plan_mode") {
+    await ctx.conversation.updateLlmConfig({ model: "anthropic/claude-opus-4-8", reasoningEffort: "high" });
+  } else if (event.toolName === "exit_plan_mode") {
+    await ctx.conversation.updateLlmConfig({ model: "openai/gpt-5.5", reasoningEffort: "max" });
+  }
+});
+```
+
 `turn_start` fires before outbound turns that include a user message. In the TUI this includes normal submits and prompt-style command turns. In headless it includes one-shot prompts and bidirectional user turns.
 
 Handlers can mutate `event.input` directly or return replacement input:
@@ -170,6 +216,67 @@ Handlers run in registration order. Later handlers see the current input after e
 
 `turn_start` is intentionally a trusted local mod point: it can rewrite user messages, approval results, and ordering. Keep transforms focused and unsurprising.
 
+`compact_start` event:
+
+```ts
+{
+  agentId: string | null;
+  conversationId: string | null;
+  trigger: "manual" | "context_window_overflow" | "context_window_limit";
+}
+```
+
+`compact_start` fires before the local backend compacts a conversation, while the full message history is still in context. `trigger` distinguishes a manual `/compact` from the two automatic triggers (provider context-window overflow, and exceeding the configured context window). Use it to checkpoint state before eviction.
+
+`compact_end` event:
+
+```ts
+{
+  agentId: string | null;
+  conversationId: string | null;
+  trigger: "manual" | "context_window_overflow" | "context_window_limit";
+  messagesBefore: number;
+  messagesAfter: number;
+  contextTokensBefore: number;
+  contextTokensAfter: number;
+}
+```
+
+`compact_end` fires after compaction completes, carrying the before/after message and context-token counts. Both events are notification-only; return values are ignored. A throwing handler is isolated and never breaks compaction.
+
+`llm_start` event:
+
+```ts
+{
+  agentId: string | null;
+  conversationId: string | null;
+  model: string;
+  messageCount: number;
+  contextWindow: number;
+}
+```
+
+`llm_start` fires right before each provider request, with the model handle, the number of messages being sent, and the model's context window. It fires once per provider request, so a retry or an overflow-triggered re-request emits another `llm_start`.
+
+`llm_end` event:
+
+```ts
+{
+  agentId: string | null;
+  conversationId: string | null;
+  model: string;
+  stopReason: string;
+  usage: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+  durationMs: number;
+}
+```
+
+`llm_end` fires once a provider request produces a final message, carrying the stop reason, token usage, and wall-clock duration. A request that fails before producing a final message (e.g. a transport error that triggers a retry) emits no `llm_end`. Both events are notification-only; return values are ignored. A throwing handler is isolated and never breaks the provider request.
+
 Handlers also receive:
 
 ```ts
@@ -199,12 +306,23 @@ export default function activate(letta) {
   if (!letta.capabilities.events.lifecycle) return;
 
   const disposers = [];
-
-  disposers.push(
-    letta.events.on("conversation_open", (event) => {
-      letta.ui.setStatus("conversation", event.reason);
-    }),
-  );
+  let conversation = "";
+
+  if (letta.capabilities.ui.panels) {
+    const panel = letta.ui.openPanel({
+      id: "conversation",
+      order: 100,
+      render: ({ width, row }) => row("conversation", conversation, width),
+    });
+    disposers.push(() => panel.close());
+
+    disposers.push(
+      letta.events.on("conversation_open", (event) => {
+        conversation = event.reason;
+        panel.update();
+      }),
+    );
+  }
 
   disposers.push(
     letta.events.on("conversation_close", (event) => {
@@ -214,7 +332,6 @@ export default function activate(letta) {
 
   return () => {
     for (const dispose of disposers.reverse()) dispose();
-    letta.ui.clearStatus("conversation");
   };
 }
 ```

package/skills/creating-mods/references/plan-mode.md

@@ -42,7 +42,7 @@ Guard each registration with the matching capability:
 - `events.turns`: append a focused plan-mode reminder while active
 - `permissions`: block mutating tools except planning coordination tools and plan-file writes
 
-Do not use panels for persistent mode state. Panels are transient UI and can be noisy/fragile for mode indicators. Do not add a custom statusline renderer just to show plan mode; `setStatuslineRenderer` is a single global renderer, not an additive slot. This example intentionally keeps visible mode state out of scope.
+Do not use panels for persistent mode state. Panels are transient UI and can be noisy/fragile for mode indicators. Do not claim the order-0 statusline panel just to show plan mode; that slot is a single primary line, not an additive indicator. This example intentionally keeps visible mode state out of scope.
 
 ## State
 

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

@@ -1,6 +1,6 @@
 # Mod UI recipes
 
-UI capabilities are optional. Always guard UI work with `letta.capabilities.ui.*` when writing portable mods.
+UI capabilities are optional. Always guard UI work with `letta.capabilities.ui.panels` when writing portable mods.
 
 For UI that belongs to a larger command/event mod, also read `architecture.md` for cleanup and composition patterns.
 
@@ -8,13 +8,9 @@ For UI that belongs to a larger command/event mod, also read `architecture.md` f
 
 ```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`: text blocks placed around the input bar (the only mod UI surface). Desktop/listener disables panel UI.
 
 ## Panels
 
@@ -22,50 +18,69 @@ Panels are app/TUI-global today. Desktop/listener disables panel UI; future scop
 
 ```ts
 if (letta.capabilities.ui.panels) {
+  let status = "Working…";
   const panel = letta.ui.openPanel({
     id: "my-mod",
-    content: ["Working…"],
     order: 100,
+    render: ({ width }) => status,
   });
 
-  panel.update({ content: ["Done"] });
+  status = "Done";
+  panel.update(); // re-invokes render with the current width
   setTimeout(() => panel.close(), 5_000);
 }
 ```
 
-Panel content is plain text: a string or string array. Keep it short; use command `output` for longer text.
+`render` returns the panel body: a string or string array (one entry per line). The host owns the region — it clips each line to `width` and caps total height — so the mod owns layout: use `width`, `row(left, right, width)`, and `columns(parts, width)` to align. The host re-invokes `render` whenever you call `panel.update()` and on terminal resize. Keep `render` cheap and side-effect-free; for longer text use a command `output` instead.
 
-Close panels when they are transient, and close/replace long-lived panels from the activation disposer if reload should remove them.
+### Placement by `order`
 
-## Status values
+`order` is a signed coordinate around the input:
 
-```ts
-if (letta.capabilities.ui.statusValues) {
-  letta.ui.setStatus("branch", "main");
-}
-```
+- `order > 0` — above the input, higher nearer the top (default `100`).
+- `order === 0` — the primary line just below the input, overriding the built-in `agent · model`. This is the statusline slot; use `customizing-statusline` for that work.
+- `order < 0` — stacks below the primary line, `-1` closest.
+
+A panel whose `render` is empty (`""`, `[]`, or only blank lines) is hidden.
 
-Clear status values in disposers if they are owned by timers, events, or external state:
+### Render context
 
 ```ts
-return () => {
-  letta.ui.clearStatus("branch");
-};
+render(ctx: {
+  width: number;
+  agent: { id, name };
+  model: { id, displayName, provider, reasoningEffort };
+  row(left, right, width): string;
+  columns(parts: string[], width): string;
+  chalk: ChalkInstance;
+}): string | string[]
 ```
 
+`row`/`columns` are ANSI-aware, so chalk-colored segments align correctly.
+
+Close panels when they are transient, and close/replace long-lived panels from the activation disposer if reload should remove them.
+
 ## Timers and cleanup
 
 ```ts
 export default function activate(letta) {
-  if (!letta.capabilities.ui.statusValues) return;
+  if (!letta.capabilities.ui.panels) return;
+
+  let clock = new Date().toLocaleTimeString();
+  const panel = letta.ui.openPanel({
+    id: "clock",
+    order: 100,
+    render: ({ width, row }) => row("clock", clock, width),
+  });
 
-  const update = () => letta.ui.setStatus("clock", new Date().toLocaleTimeString());
-  update();
-  const timer = setInterval(update, 30_000);
+  const timer = setInterval(() => {
+    clock = new Date().toLocaleTimeString();
+    panel.update();
+  }, 30_000);
 
   return () => {
     clearInterval(timer);
-    letta.ui.clearStatus("clock");
+    panel.close();
   };
 }
 ```

package/skills/customizing-statusline/SKILL.md

@@ -11,28 +11,28 @@ Use this skill to create or update the global Letta Code statusline mod:
 ~/.letta/mods/statusline.tsx
 ```
 
-The statusline is a full-row idle renderer. Host UI can still temporarily preempt it for safety confirmations and transient hints.
+The statusline is a panel registered at `order: 0` — the primary line just below the input. It overrides the built-in `agent · model` line. Host UI can still temporarily preempt it for safety confirmations and transient hints.
 
 ## Statusline ownership model
 
 ```text
 safety preemption
 else transient host hint
-else custom statusline mod
+else order-0 statusline panel
 else built-in default statusline
 ```
 
-A custom statusline owns the whole idle row. Do not preserve legacy left/right split semantics in the new API.
+The order-0 panel owns the whole primary row. It renders text (not React) and owns its own layout via the `row`/`columns` helpers.
 
 ## Workflow
 
 1. Check whether `~/.letta/mods/statusline.tsx` exists.
 2. If it exists, read it before editing and preserve unrelated code.
-3. If it does not exist, start from the built-in default template or synthesize a focused starter for the user's request.
+3. If it does not exist, synthesize a focused starter for the user's request.
 4. If the user asks to migrate, import a `.sh` file, or match a shell prompt, read `references/migration.md`.
 5. If API details or concrete patterns are needed, read `references/api.md` and `references/examples.md`.
-6. If the request combines statusline work with commands, tools, events, panels, or stateful mod behavior, also use `creating-mods` and its `references/architecture.md`.
-7. Guard statusline-specific behavior with `letta.capabilities.ui.customStatuslineRenderer` when writing new files.
+6. If the request combines statusline work with commands, tools, events, other panels, or stateful mod behavior, also use `creating-mods` and its `references/architecture.md`.
+7. Guard panel work with `letta.capabilities.ui.panels` when writing new files.
 8. Edit `~/.letta/mods/statusline.tsx`.
 9. Summarize the absolute file path changed and tell the user to run `/reload` unless the command can reload automatically.
 
@@ -42,7 +42,7 @@ If the user ran `/statusline` without a specific request:
 
 - If a custom statusline file exists, summarize what it appears to do and ask what they want to change.
 - If no custom file exists, explain that Letta is using the built-in default statusline and offer focused next steps:
-  1. start from the default Letta statusline
+  1. start from a simple `agent · model` statusline
   2. add project info like git branch, worktree, or PR
   3. migrate an existing legacy statusline `.sh` file
   4. match shell prompt / PS1
@@ -56,16 +56,15 @@ Keep this conversational. Do not build a menu UI unless the product command expl
 - Keep the mod single-file for MVP.
 - Do not assume extra npm packages are available.
 - Do not use relative multi-file imports yet.
-- Keep renderers synchronous. Do not shell, fetch, or await inside render.
-- Do async work in setup code, intervals, subscriptions, or status providers.
-- Use `letta.ui.setStatus` for data and `setStatuslineRenderer` for drawing that data.
-- Guard optional APIs with `letta.capabilities.ui.statusValues` and `letta.capabilities.ui.customStatuslineRenderer` in new files.
-- Return a disposer that clears timers/subscriptions.
+- Keep `render` synchronous and side-effect-free. Do not shell, fetch, await, or read files inside render.
+- Do async work in setup code, intervals, or subscriptions, store the result in a closure variable, then call `panel.update()` to re-render.
+- Register the statusline at `order: 0`. Compose left/right with `row(left, right, width)`; color with `chalk`.
+- Guard panel work with `letta.capabilities.ui.panels` in new files.
+- Return a disposer that clears timers/subscriptions and calls `panel.close()`.
 - Preserve existing mod code unless the user asks to reset.
-- Do not delete legacy command statusline files or settings unless the user explicitly asks.
 
 ## Useful references
 
-- `references/api.md` - mod API, render context, lifecycle rules
+- `references/api.md` - panel API, render context, lifecycle rules
 - `references/examples.md` - common statusline patterns
 - `references/migration.md` - legacy command `.sh` and PS1 migration