@letta-ai/letta-code 0.27.17 → 0.27.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.27.17",
+  "version": "0.27.19",
   "description": "Letta Code is a CLI tool for interacting with stateful Letta agents from the terminal.",
   "type": "module",
   "packageManager": "bun@1.3.0",
@@ -47,6 +47,7 @@
     "@earendil-works/pi-ai": "^0.79.6",
     "@letta-ai/letta-client": "^1.10.2",
     "@pierre/diffs": "1.2.2",
+    "@scarf/scarf": "^1.4.0",
     "glob": "^13.0.0",
     "ink-link": "^5.0.0",
     "node-pty": "^1.1.0",
@@ -97,7 +98,8 @@
     "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",
-    "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"
+    "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"
   },
   "lint-staged": {
     "*.{ts,tsx,js,jsx,json}": [

package/scripts/mod-learning/learn-mod.ts

@@ -0,0 +1,306 @@
+#!/usr/bin/env bun
+import { spawn } from "node:child_process";
+import { closeSync, openSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  defaultModLearningRunDirectory,
+  type ModLearningProgress,
+  type ModLearningReport,
+  readModLearningEnv,
+  runModLearning,
+} from "../../src/mods/learning-harness.ts";
+
+const DEFAULT_OPTIMIZATION_STEPS = 5;
+
+interface Args {
+  backend?: string;
+  candidate?: string;
+  candidateCount?: number;
+  candidateFileName?: string;
+  evalModel?: string;
+  generationModel?: string;
+  help: boolean;
+  env: string;
+  foreground: boolean;
+  out?: string;
+  promoteTo?: string;
+  repoRoot: string;
+  scenarioLimit?: number;
+  skipGeneration: boolean;
+}
+
+function readOptionValue(
+  argv: string[],
+  index: number,
+  optionName: string,
+): { nextIndex: number; value: string } {
+  const arg = argv[index] ?? "";
+  const equalsPrefix = `${optionName}=`;
+  if (arg.startsWith(equalsPrefix)) {
+    const value = arg.slice(equalsPrefix.length);
+    if (!value) throw new Error(`${optionName} requires a value`);
+    return { nextIndex: index, value };
+  }
+
+  const value = argv[index + 1];
+  if (!value || value.startsWith("--")) {
+    throw new Error(`${optionName} requires a value`);
+  }
+  return { nextIndex: index + 1, value };
+}
+
+function parseArgs(argv: string[]): Args {
+  const args: Args = {
+    env: "docs/examples/mods/learning/memory-citations.env.json",
+    foreground: false,
+    help: false,
+    repoRoot: process.cwd(),
+    skipGeneration: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--help" || arg === "-h") {
+      args.help = true;
+    } else if (arg === "--background") {
+      args.foreground = false;
+    } else if (arg === "--foreground") {
+      args.foreground = true;
+    } else if (arg === "--skip-generation") {
+      args.skipGeneration = true;
+    } else if (arg?.startsWith("--")) {
+      const optionName = arg.includes("=")
+        ? arg.slice(0, arg.indexOf("="))
+        : arg;
+      const { nextIndex, value } = readOptionValue(argv, index, optionName);
+      index = nextIndex;
+      switch (optionName) {
+        case "--backend":
+          args.backend = value;
+          break;
+        case "--candidate":
+          args.candidate = value;
+          break;
+        case "--candidates":
+          args.candidateCount = Number(value);
+          break;
+        case "--candidate-file-name":
+          args.candidateFileName = value;
+          break;
+        case "--eval-model":
+          args.evalModel = value;
+          break;
+        case "--env":
+          args.env = value;
+          break;
+        case "--generation-model":
+          args.generationModel = value;
+          break;
+        case "--model":
+          args.generationModel = value;
+          args.evalModel = value;
+          break;
+        case "--out":
+          args.out = value;
+          break;
+        case "--promote-to":
+          args.promoteTo = value;
+          break;
+        case "--repo-root":
+          args.repoRoot = value;
+          break;
+        case "--scenario-limit":
+          args.scenarioLimit = Number(value);
+          break;
+        default:
+          throw new Error(`Unknown argument: ${arg}`);
+      }
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  return args;
+}
+
+function printHelp(): void {
+  console.log(`Usage: bun scripts/mod-learning/learn-mod.ts [options]
+
+Runs the mod learning dogfood loop:
+  env/demo -> generate candidate mod -> headless eval with LETTA_MODS_DIR (and legacy LETTA_EXTENSIONS_DIR for pre-rename branches) -> artifacts/report
+
+Options:
+  --env <path>                  Learning env JSON (default: memory-citations env)
+  --out <dir>                   Run artifact directory (default: .letta/mod-learning-runs/<slug>-<timestamp>)
+  --candidate <path>            Use an existing candidate mod instead of generation
+  --candidates <n>              Run N optimization iterations for one learned mod (default: 5 for generated runs)
+  --candidate-file-name <name>  Candidate filename inside the eval mod directory
+  --model <handle>              Model for generation and eval
+  --generation-model <handle>   Model for candidate generation
+  --eval-model <handle>         Model for headless eval
+  --backend <mode>              Backend flag forwarded to letta (api or local)
+  --scenario-limit <n>          Evaluate only the first N scenarios (fast smoke testing)
+  --repo-root <path>            Repo root (default: cwd)
+  --foreground                  Run learning in this process and return a pass/fail exit code
+  --background                  Explicitly use the default detached mode
+  --skip-generation             Expect the candidate file to already exist in the run dir
+  --promote-to <path>           Copy passing candidate to this repo-relative path
+  -h, --help                    Show this help
+`);
+}
+
+async function launchBackground(params: {
+  argv: string[];
+  repoRoot: string;
+  runDir: string;
+  outWasProvided: boolean;
+}): Promise<void> {
+  await mkdir(params.runDir, { recursive: true });
+  const stdoutPath = path.join(params.runDir, "background.stdout");
+  const stderrPath = path.join(params.runDir, "background.stderr");
+  const metadataPath = path.join(params.runDir, "background.json");
+  const childArgv = params.argv.filter(
+    (arg) => arg !== "--background" && arg !== "--foreground",
+  );
+  childArgv.push("--foreground");
+  if (!params.outWasProvided) childArgv.push("--out", params.runDir);
+
+  const stdoutFd = openSync(stdoutPath, "a");
+  const stderrFd = openSync(stderrPath, "a");
+  let childPid: number | undefined;
+  try {
+    const child = spawn(
+      process.execPath,
+      [fileURLToPath(import.meta.url), ...childArgv],
+      {
+        cwd: params.repoRoot,
+        detached: true,
+        env: process.env,
+        stdio: ["ignore", stdoutFd, stderrFd],
+      },
+    );
+    child.unref();
+    childPid = child.pid;
+    await writeFile(
+      metadataPath,
+      `${JSON.stringify(
+        {
+          args: childArgv,
+          command: process.execPath,
+          pid: childPid,
+          runDir: params.runDir,
+          startedAt: new Date().toISOString(),
+          stderrPath,
+          stdoutPath,
+        },
+        null,
+        2,
+      )}\n`,
+      "utf8",
+    );
+  } finally {
+    closeSync(stdoutFd);
+    closeSync(stderrFd);
+  }
+
+  console.log(`BACKGROUND ${params.runDir}`);
+  console.log(`PID ${childPid ?? "unknown"}`);
+  console.log(`stdout ${stdoutPath}`);
+  console.log(`stderr ${stderrPath}`);
+  console.log(`progress tail -f ${stdoutPath}`);
+  console.log(`report ${path.join(params.runDir, "report.md")}`);
+}
+
+function formatScore(
+  score: number | undefined,
+  maxScore: number | undefined,
+): string {
+  if (score === undefined) return "";
+  if (maxScore === undefined) return ` score ${score}`;
+  const percentage = maxScore > 0 ? Math.round((score / maxScore) * 100) : 0;
+  return ` score ${score}/${maxScore} (${percentage}%)`;
+}
+
+function progressPrefix(progress: ModLearningProgress): string {
+  if (progress.candidateIndex && progress.candidateCount) {
+    return `[${progress.candidateIndex}/${progress.candidateCount}]`;
+  }
+  if (progress.candidateIndex) return `[${progress.candidateIndex}]`;
+  return `[${progress.phase}]`;
+}
+
+function formatProgressLine(progress: ModLearningProgress): string {
+  return `${progressPrefix(progress)} ${progress.message}${formatScore(progress.score, progress.maxScore)}`;
+}
+
+function candidateForPromote(report: ModLearningReport): string {
+  return report.candidatePath;
+}
+
+async function main(): Promise<void> {
+  const argv = process.argv.slice(2);
+  const args = parseArgs(argv);
+  if (args.help) {
+    printHelp();
+    return;
+  }
+
+  const repoRoot = path.resolve(args.repoRoot);
+  const learningEnv = await readModLearningEnv(
+    path.resolve(repoRoot, args.env),
+  );
+  const runDir = args.out
+    ? path.resolve(repoRoot, args.out)
+    : path.resolve(repoRoot, defaultModLearningRunDirectory(learningEnv));
+
+  if (!args.foreground) {
+    await launchBackground({
+      argv,
+      outWasProvided: args.out !== undefined,
+      repoRoot,
+      runDir,
+    });
+    return;
+  }
+
+  let lastProgressLine = "";
+  const report = await runModLearning({
+    backend: args.backend,
+    candidateCount:
+      args.candidateCount ??
+      (args.candidate || args.skipGeneration
+        ? undefined
+        : DEFAULT_OPTIMIZATION_STEPS),
+    candidateFileName: args.candidateFileName,
+    candidateSourcePath: args.candidate,
+    evalModel: args.evalModel,
+    generationModel: args.generationModel,
+    promoteToPath: args.promoteTo,
+    repoRoot,
+    runDir,
+    scenarioLimit: args.scenarioLimit,
+    skipGeneration: args.skipGeneration,
+    spec: learningEnv,
+    onProgress: (progress) => {
+      const line = formatProgressLine(progress);
+      if (line === lastProgressLine) return;
+      lastProgressLine = line;
+      console.log(line);
+    },
+  });
+
+  const status = report.passed ? "PASS" : "FAIL";
+  console.log(`${status} ${report.reportPath}`);
+  console.log(`candidate ${candidateForPromote(report)}`);
+  if (report.passed) {
+    console.log(`promote letta mods promote ${candidateForPromote(report)}`);
+  }
+  if (!report.passed) process.exit(1);
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.stack : String(error));
+  process.exit(1);
+});

package/skills/{context_doctor → context-doctor}/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: Context Doctor
-id: context_doctor
+id: context-doctor
 description: Identify and repair degradation in system prompt, external memory, and skills preventing you from following instructions or remembering information as well as you should.
 ---
 

package/skills/creating-mods/SKILL.md

@@ -1,13 +1,13 @@
 ---
 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.
+Capabilities vary by surface — not every surface loads every capability. The TUI/headless host can load tools, commands, events, UI, and providers; the desktop listener loads tools, commands, providers, and tool/turn events, but not panel UI. Always guard each registration on the capabilities its behavior needs.
 
 ## Choose where the mod file lives
 
@@ -86,13 +86,15 @@ 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
 ```
 
+Guard each registration on every capability its behavior depends on — not just the one that registers it. Surfaces load different capability subsets, so a registration that relies on another capability (a command that opens UI, emits an event, or calls a provider) must guard on that capability too. Otherwise it is advertised or activated on a host that cannot fulfill it and silently does nothing. Register where the host can actually do the work.
+
 ## Scoped API model
 
 - In commands and events, use `ctx.conversation` for conversation operations:
@@ -135,7 +137,8 @@ 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.
+- Each registration is guarded by every capability its behavior depends on, not just the one that registers it, so it isn't advertised or activated on a surface that can't fulfill it.
 - 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 +155,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 or cancel outbound user-message turns. `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,7 +147,46 @@ 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.
 
-`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.
+`tool_end` event:
+
+```ts
+{
+  agentId: string | null;
+  conversationId: string | null;
+  toolCallId: string | null;
+  toolName: string;
+  args: Record<string, unknown>;
+  status: "success" | "error";
+  output: string;
+}
+```
+
+`tool_end` fires immediately after a tool produces a result, before the agent sees it. `event.args` contains the effective tool invocation arguments after `tool_start` transforms, so handlers can react to the specific file, command, query, etc. 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;
+  if (typeof event.args.command !== "string") 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. Listener/Desktop skips approval-only continuations so mods do not rewrite approval payloads; do not rely on `turn_start` to block approval-only continuations on every surface.
 
 Handlers can mutate `event.input` directly or return replacement input:
 
@@ -166,10 +214,83 @@ letta.events.on("turn_start", (event) => {
 });
 ```
 
+Handlers can also cancel a user-message turn before it reaches the backend/model:
+
+```ts
+letta.events.on("turn_start", (event) => {
+  if (!isPlanModeActive(event.conversationId)) {
+    return { cancel: { reason: "Run /plan first." } };
+  }
+});
+```
+
+If multiple handlers cancel, the first valid cancel reason wins. A valid reason is a non-empty string after trimming. Cancellation does not synthesize an assistant response or tool result; it only tells the host not to submit this turn.
+
 Handlers run in registration order. Later handlers see the current input after earlier mutations/returns. If a handler throws, its partial `event.input` mutation is rolled back and the error is recorded as a mod diagnostic.
 
 `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 +320,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 +346,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