@letta-ai/letta-code 0.27.17 → 0.27.19

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,92 @@ 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`
+
+`order` is a signed coordinate around the input:
+
+- `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.
 
-## Status values
+A panel whose `render` is empty (`""`, `[]`, or only blank lines) is hidden.
+
+### Render context
 
 ```ts
-if (letta.capabilities.ui.statusValues) {
-  letta.ui.setStatus("branch", "main");
-}
+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[]
 ```
 
-Clear status values in disposers if they are owned by timers, events, or external state:
+`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.
+
+### Commands that open panels
+
+If a command's `run()` opens a panel, guard the command **registration** on `letta.capabilities.ui.panels` — not just the `openPanel` call:
 
 ```ts
-return () => {
-  letta.ui.clearStatus("branch");
-};
+export default function activate(letta) {
+  if (!letta.capabilities.commands) return;
+  if (!letta.capabilities.ui.panels) return; // panel-only command: skip where panels are unsupported
+
+  return letta.commands.register({
+    id: "mycommand",
+    description: "…",
+    run() {
+      const panel = letta.ui.openPanel({ /* … */ });
+      // …
+      return { type: "handled" };
+    },
+  });
+}
 ```
 
+Guarding only the `openPanel` call is not enough. The desktop listener has `commands: true` but `ui.panels: false`, so a command registered there is advertised in the command picker while its panel work no-ops — the user sees a command that runs and does nothing. Gating the registration keeps panel-only commands out of hosts that can't render 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

package/skills/customizing-statusline/references/api.md

@@ -12,48 +12,74 @@ This is a trusted, user-owned global mod file. Project mods are intentionally un
 
 ## Activation
 
-Export a default function or named `activate` function:
+Export a default function or named `activate` function. The statusline is a panel at `order: 0`:
 
 ```tsx
 export default function activate(letta) {
-  if (!letta.capabilities.ui.customStatuslineRenderer) return;
-
-  letta.ui.setStatuslineRenderer((context) => {
-    const { Text } = context.components;
-    return <Text>{context.agent.name} · {context.model.displayName}</Text>;
+  if (!letta.capabilities.ui.panels) return;
+
+  const panel = letta.ui.openPanel({
+    id: "statusline",
+    order: 0, // primary line: overrides the built-in agent · model
+    render: ({ width, agent, model, row, chalk }) => {
+      const left = chalk.cyan(agent.name ?? "Letta");
+      const right = chalk.dim(model.displayName ?? "no model");
+      return row(left, right, width);
+    },
   });
+
+  return () => panel.close();
 }
 ```
 
 ## API
 
 ```ts
-letta.capabilities.ui.statusValues: boolean
-letta.capabilities.ui.customStatuslineRenderer: boolean
+letta.capabilities.ui.panels: boolean
 
-letta.ui.setStatus(key: string, value: string | null | undefined | ((context) => string | null)): void
-letta.ui.clearStatus(key: string): void
-letta.ui.setStatuslineRenderer(renderer: StatuslineRenderer | ((context) => ReactNode | null)): void
+letta.ui.openPanel(options: {
+  id: string;
+  order?: number; // default 100
+  render: (ctx) => string | string[];
+}): { close(): void; update(opts?: { order?: number }): void }
+
+letta.ui.closePanel(id: string): void
 ```
 
-`setStatus` stores named string values. Renderers read evaluated values from `context.statuses`.
+`openPanel` registers (or replaces, by `id`) a panel. `render` returns the panel body as a string or an array of strings (one per line). Call the returned handle's `update()` to re-render after state changes, and `close()` to remove it.
 
-```tsx
-letta.ui.setStatus("branch", "main");
+## Order placement
+
+`order` is a signed coordinate around the input:
+
+- `order > 0` — above the input. Higher numbers render nearer the top. Default when omitted is `100`.
+- `order === 0` — the primary line just below the input. Overrides the built-in `agent · model`. Use this for the statusline.
+- `order < 0` — stacks below the primary line. `-1` sits closest to it, more-negative lower.
+
+A panel whose `render` returns empty (`""` or `[]`, or only blank lines) is hidden entirely — no blank row.
 
-letta.ui.setStatuslineRenderer((context) => {
-  const { Text } = context.components;
-  return <Text>{context.statuses.branch}</Text>;
-});
+## Render context
+
+```ts
+render(ctx: {
+  width: number;            // visible columns available to the panel
+  agent: { id, name };      // live at render time
+  model: { id, displayName, provider, reasoningEffort };
+  row(left, right, width): string;     // left + right, right-aligned, ANSI-aware
+  columns(parts: string[], width): string; // spread parts evenly, ANSI-aware
+  chalk: ChalkInstance;     // color helper
+}): string | string[]
 ```
 
-## Renderer rules
+- `row`/`columns` measure visible width with ANSI stripped, so chalk-colored segments align correctly.
+- The host clips each line to `width` and caps total height; the mod owns layout within that.
+
+## Render rules
 
-- Renderer owns the entire idle bottom row.
-- Renderer must be synchronous.
-- Do not run shell commands, network requests, file reads, or awaits inside render.
-- Do async work in setup code or intervals, store results with `setStatus`, then render `context.statuses`.
-- Return `null` only when intentionally rendering nothing.
+- `render` must be synchronous and side-effect-free.
+- Do not run shell commands, network requests, file reads, or awaits inside `render`.
+- Do async work in setup code or intervals, store the result in a closure variable, then call `panel.update()`.
+- Return `""` (or `[]`) to render nothing.
 
 ## Async state pattern
 
@@ -66,92 +92,54 @@ import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
 
 export default function activate(letta) {
-  if (!letta.capabilities.ui.customStatuslineRenderer) return;
+  if (!letta.capabilities.ui.panels) return;
+
+  let branch = "";
+
+  const panel = letta.ui.openPanel({
+    id: "statusline",
+    order: 0,
+    render: ({ width, agent, row, chalk }) => {
+      const left = branch ? chalk.green(`\u2442 ${branch}`) : (agent.name ?? "Letta");
+      return row(left, "", width);
+    },
+  });
 
   const update = async () => {
     try {
       const { stdout } = await execFileAsync("git", ["branch", "--show-current"], {
         cwd: process.cwd(),
       });
-      if (letta.capabilities.ui.statusValues) {
-        letta.ui.setStatus("branch", stdout.trim());
-      }
+      branch = stdout.trim();
     } catch {
-      if (letta.capabilities.ui.statusValues) {
-        letta.ui.clearStatus("branch");
-      }
+      branch = "";
     }
+    panel.update();
   };
 
-  letta.ui.setStatuslineRenderer((context) => {
-    const { Text } = context.components;
-    const branch = context.statuses.branch;
-    return <Text>{branch ? `branch ${branch}` : context.agent.name}</Text>;
-  });
-
   void update();
   const timer = setInterval(update, 30_000);
 
   return () => {
     clearInterval(timer);
-    if (letta.capabilities.ui.statusValues) {
-      letta.ui.clearStatus("branch");
-    }
+    panel.close();
   };
 }
 ```
 
-## Context fields
-
-The app statusline render context source types live near:
-
-```text
-src/cli/display/statusline/types.ts
-src/cli/display/statusline/context.ts
-```
+## Full-row layout
 
-Common fields:
+There is no host left/right API. Build left/right alignment inside `render` with `row`:
 
-```ts
-context.components      // Display components such as Text, Box, Spacer
-context.statuses        // evaluated mod status strings
-context.app.version
-context.workspace.cwd
-context.workspace.currentDir
-context.workspace.projectDir
-context.agent.name
-context.agent.id
-context.model.id
-context.model.displayName
-context.model.provider
-context.model.reasoningEffort
-context.permissionMode
-context.terminalWidth
-context.contextWindow.usedPercentage
-context.contextWindow.remainingPercentage
-context.cost.totalDurationMs
-context.cost.totalCostUsd
-context.reflection
-context.memfs
-context.backgroundAgents
-context.rawPayload      // compatibility payload for advanced cases
+```tsx
+render: ({ width, agent, model, row, chalk }) =>
+  row(chalk.dim("Press / for commands"), `${agent.name ?? "Letta"} \u00b7 ${model.displayName ?? ""}`, width),
 ```
 
-Prefer semantic fields over `rawPayload` unless migrating old command statuslines.
-
-## Full-row layout
-
-New statuslines do not have a host left/right API. To create left/right visual alignment, do it inside the renderer:
+Use `columns` for three or more evenly-spread segments:
 
 ```tsx
-return (
-  <Box flexDirection="row">
-    <Box flexGrow={1}>
-      <Text>left content</Text>
-    </Box>
-    <Text>right content</Text>
-  </Box>
-);
+render: ({ width, columns }) => columns(["left", "middle", "right"], width),
 ```
 
 ## Reload behavior
@@ -162,4 +150,4 @@ After editing `~/.letta/mods/statusline.tsx`, tell the user to run:
 /reload
 ```
 
-The runtime tracks mod loading separately from “no custom statusline,” so a custom statusline should not flash back to the built-in default during reload.
+The runtime tracks mod loading so a custom statusline does not flash back to the built-in default during reload.

package/skills/customizing-statusline/references/examples.md

@@ -1,17 +1,25 @@
 # Statusline Examples
 
-Use these as patterns, not mandatory templates. Keep the final mod focused on the user's request.
+Use these as patterns, not mandatory templates. Keep the final mod focused on the user's request. All register at `order: 0` (the primary line) and return text composed with `row`/`columns`/`chalk`.
 
 ## Agent and model
 
 ```tsx
 export default function activate(letta) {
-  if (!letta.capabilities.ui.customStatuslineRenderer) return;
-
-  letta.ui.setStatuslineRenderer((context) => {
-    const { Text } = context.components;
-    return <Text>{context.agent.name ?? "Letta"} · {context.model.displayName ?? "no model"}</Text>;
+  if (!letta.capabilities.ui.panels) return;
+
+  const panel = letta.ui.openPanel({
+    id: "statusline",
+    order: 0,
+    render: ({ width, agent, model, row, chalk }) =>
+      row(
+        chalk.cyan(agent.name ?? "Letta"),
+        chalk.dim(model.displayName ?? "no model"),
+        width,
+      ),
   });
+
+  return () => panel.close();
 }
 ```
 
@@ -24,28 +32,35 @@ import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
 
 export default function activate(letta) {
-  if (!letta.capabilities.ui.customStatuslineRenderer) return;
+  if (!letta.capabilities.ui.panels) return;
+
+  let branch = "";
+
+  const panel = letta.ui.openPanel({
+    id: "statusline",
+    order: 0,
+    render: ({ width, agent, row, chalk }) =>
+      row(branch ? chalk.green(`git ${branch}`) : (agent.name ?? "Letta"), "", width),
+  });
 
   const update = async () => {
     try {
       const { stdout } = await execFileAsync("git", ["branch", "--show-current"], {
         cwd: process.cwd(),
       });
-      letta.ui.setStatus("branch", stdout.trim());
+      branch = stdout.trim();
     } catch {
-      letta.ui.clearStatus("branch");
+      branch = "";
     }
+    panel.update();
   };
 
-  letta.ui.setStatuslineRenderer((context) => {
-    const { Text } = context.components;
-    const branch = context.statuses.branch;
-    return <Text>{branch ? `git ${branch}` : context.agent.name}</Text>;
-  });
-
   void update();
   const timer = setInterval(update, 30_000);
-  return () => clearInterval(timer);
+  return () => {
+    clearInterval(timer);
+    panel.close();
+  };
 }
 ```
 
@@ -53,21 +68,20 @@ export default function activate(letta) {
 
 ```tsx
 export default function activate(letta) {
-  if (!letta.capabilities.ui.customStatuslineRenderer) return;
-
-  letta.ui.setStatuslineRenderer((context) => {
-    const { Box, Text } = context.components;
-    const model = context.model.displayName ?? "no model";
-
-    return (
-      <Box flexDirection="row">
-        <Box flexGrow={1}>
-          <Text dimColor>Press / for commands</Text>
-        </Box>
-        <Text>{context.agent.name ?? "Letta"} · {model}</Text>
-      </Box>
-    );
+  if (!letta.capabilities.ui.panels) return;
+
+  const panel = letta.ui.openPanel({
+    id: "statusline",
+    order: 0,
+    render: ({ width, agent, model, row, chalk }) =>
+      row(
+        chalk.dim("Press / for commands"),
+        `${agent.name ?? "Letta"} \u00b7 ${model.displayName ?? "no model"}`,
+        width,
+      ),
   });
+
+  return () => panel.close();
 }
 ```
 
@@ -80,7 +94,15 @@ import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
 
 export default function activate(letta) {
-  if (!letta.capabilities.ui.customStatuslineRenderer) return;
+  if (!letta.capabilities.ui.panels) return;
+
+  let pr = "";
+
+  const panel = letta.ui.openPanel({
+    id: "statusline",
+    order: 0,
+    render: ({ width, model, row }) => row(pr || (model.displayName ?? ""), "", width),
+  });
 
   const update = async () => {
     try {
@@ -89,21 +111,19 @@ export default function activate(letta) {
         ["pr", "view", "--json", "number,title", "--jq", "\"#\\(.number) \\(.title)\""],
         { cwd: process.cwd() },
       );
-      const pr = stdout.trim();
-      pr ? letta.ui.setStatus("pr", pr) : letta.ui.clearStatus("pr");
+      pr = stdout.trim();
     } catch {
-      letta.ui.clearStatus("pr");
+      pr = "";
     }
+    panel.update();
   };
 
-  letta.ui.setStatuslineRenderer((context) => {
-    const { Text } = context.components;
-    return <Text>{context.statuses.pr ?? context.model.displayName}</Text>;
-  });
-
   void update();
   const timer = setInterval(update, 60_000);
-  return () => clearInterval(timer);
+  return () => {
+    clearInterval(timer);
+    panel.close();
+  };
 }
 ```
 
@@ -116,26 +136,34 @@ import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
 
 export default function activate(letta) {
-  if (!letta.capabilities.ui.customStatuslineRenderer) return;
+  if (!letta.capabilities.ui.panels) return;
+
+  let music = "";
+
+  const panel = letta.ui.openPanel({
+    id: "statusline",
+    order: 0,
+    render: ({ width, agent, row, chalk }) =>
+      row(music ? chalk.magenta(music) : (agent.name ?? "Letta"), "", width),
+  });
 
   const update = async () => {
     try {
-      const script = 'tell application "Music" to if it is running then artist of current track & " - " & name of current track';
+      const script =
+        'tell application "Music" to if it is running then artist of current track & " - " & name of current track';
       const { stdout } = await execFileAsync("osascript", ["-e", script]);
-      const music = stdout.trim();
-      music ? letta.ui.setStatus("music", music) : letta.ui.clearStatus("music");
+      music = stdout.trim();
     } catch {
-      letta.ui.clearStatus("music");
+      music = "";
     }
+    panel.update();
   };
 
-  letta.ui.setStatuslineRenderer((context) => {
-    const { Text } = context.components;
-    return <Text>{context.statuses.music ?? context.agent.name}</Text>;
-  });
-
   void update();
   const timer = setInterval(update, 15_000);
-  return () => clearInterval(timer);
+  return () => {
+    clearInterval(timer);
+    panel.close();
+  };
 }
 ```