@letta-ai/letta-code 0.27.17 → 0.27.18

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();
+  };
 }
 ```

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

@@ -1,6 +1,6 @@
 # Statusline Migration
 
-Use this reference when migrating legacy command statuslines, standalone `.sh` statusline scripts, or shell PS1 prompts.
+Use this reference when migrating legacy command statuslines, standalone `.sh` statusline scripts, or shell PS1 prompts into `~/.letta/mods/statusline.tsx`.
 
 ## Legacy Letta command statusline
 
@@ -40,10 +40,10 @@ When migrating:
 
 - Preserve old config and referenced files unless the user explicitly asks to delete them.
 - If `command` references a `.sh` file, read it before writing the new mod.
-- Translate polling (`refreshIntervalMs`) to `setInterval`.
-- Translate direct command output into cached status plus synchronous rendering.
-- If the command output used `\x1e` to split left/right output, convert it to internal full-row layout with `Box`; do not create a new left/right API.
-- Treat old prompt customization separately. The new statusline controls the bottom row, not necessarily the input prompt.
+- Translate polling (`refreshIntervalMs`) to `setInterval` + `panel.update()`.
+- Translate direct command output into a cached closure variable plus synchronous rendering.
+- If the command output used `\x1e` to split left/right output, convert it to `row(left, right, width)`; there is no separate left/right API.
+- Treat old prompt customization separately. The statusline controls the primary row, not necessarily the input prompt.
 
 Old model:
 
@@ -59,17 +59,36 @@ import { promisify } from "node:util";
 
 const execFileAsync = promisify(execFile);
 
-const update = async () => {
-  const { stdout } = await execFileAsync("git", ["branch", "--show-current"], {
-    cwd: process.cwd(),
+export default function activate(letta) {
+  if (!letta.capabilities.ui.panels) return;
+
+  let branch = "";
+
+  const panel = letta.ui.openPanel({
+    id: "statusline",
+    order: 0,
+    render: ({ width, row }) => row(branch, "", width),
   });
-  letta.ui.setStatus("branch", stdout.trim());
-};
 
-letta.ui.setStatuslineRenderer((context) => {
-  const { Text } = context.components;
-  return <Text>{context.statuses.branch ?? ""}</Text>;
-});
+  const update = async () => {
+    try {
+      const { stdout } = await execFileAsync("git", ["branch", "--show-current"], {
+        cwd: process.cwd(),
+      });
+      branch = stdout.trim();
+    } catch {
+      branch = "";
+    }
+    panel.update();
+  };
+
+  void update();
+  const timer = setInterval(update, 30_000);
+  return () => {
+    clearInterval(timer);
+    panel.close();
+  };
+}
 ```
 
 ## Standalone `.sh` file migration
@@ -79,11 +98,11 @@ If the user provides a `.sh` path:
 1. Read the script.
 2. Identify commands, expected stdin JSON, environment variables, and output shape.
 3. Port shell commands to async setup/update code.
-4. Store results with `letta.ui.setStatus(key, value)`.
-5. Render cached status synchronously.
-6. Preserve graceful fallbacks for missing tools, not-a-git-repo, no PR, etc.
+4. Store results in closure variables.
+5. Render cached state synchronously and call `panel.update()` after each refresh.
+6. Preserve graceful fallbacks for missing tools, not-a-git-repo, no PR, etc. (return `""` to hide the line).
 
-If a script depends heavily on stdin JSON, use `context.rawPayload` as a temporary migration aid, but prefer semantic context fields for new code.
+Map the script's stdin JSON to the render context's semantic fields (`agent`, `model`, `width`); compute anything else in setup/update code.
 
 ## Shell PS1 import
 
@@ -127,4 +146,4 @@ If no PS1 is found and the user did not provide other instructions, ask for one
 2. a description of what their prompt shows
 3. the current prompt output as it appears in their terminal
 
-Preserve colors where practical using display components. If the PS1 is too dynamic to port exactly, ask whether to approximate it or port specific commands.
+Preserve colors where practical with `chalk`. If the PS1 is too dynamic to port exactly, ask whether to approximate it or port specific commands.