@letta-ai/letta-code 0.27.4 → 0.27.6

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

@@ -0,0 +1,285 @@
+# Plan mode extension example
+
+Use this as the canonical multi-capability extension example. It composes a slash command, model-callable tools, turn reminders, permission overlays, and local state to recreate the old built-in plan-mode flow with extension APIs.
+
+This is a pattern reference, not a full product implementation. Keep local extensions self-contained and avoid importing Letta Code internals.
+
+## Contents
+
+- Flow
+- Capabilities used
+- State
+- Entry command and tool
+- Turn reminder
+- Permission overlay
+- Exit tool
+- Notes
+
+## Flow
+
+```text
+/plan or enter_plan_mode
+-> create ~/.letta/plans/<random>.md
+-> remember active plan state for this conversation
+-> remind the agent that only read-only tools and plan-file writes are allowed
+-> permission overlay denies mutations outside ~/.letta/plans/*.md
+-> agent writes the plan with normal Write/Edit/ApplyPatch tools
+-> agent reads the plan and calls AskUserQuestion with Approve / Revise
+-> if approved, agent calls exit_plan_mode
+-> exit_plan_mode clears state and returns the approved-plan execution handoff
+```
+
+Plan files are normal markdown files. Do not add a special `update_plan_file` tool unless the user explicitly wants that abstraction. Let the agent use normal write tools and constrain those tools with permissions.
+
+## Capabilities used
+
+Guard each registration with the matching capability:
+
+- `commands`: `/plan` for explicit human entry
+- `tools`: `enter_plan_mode` and `exit_plan_mode` for model-driven entry/exit
+- `events.turns`: append a focused plan-mode reminder while active
+- `permissions`: block mutating tools except 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.
+
+## State
+
+Use small local state under `~/.letta/extensions/`, keyed by conversation ID:
+
+```ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, relative } from "node:path";
+
+const PLANS_DIR = join(homedir(), ".letta", "plans");
+const STATE_PATH = join(homedir(), ".letta", "extensions", "plan-mode.state.json");
+const GLOBAL_CONVERSATION_ID = "__global__";
+
+type PlanSession = {
+  conversationId: string;
+  planFilePath: string;
+  startedAt: number;
+  cwd: string;
+};
+
+type PlanState = { sessions: Record<string, PlanSession> };
+
+function conversationKey(id: string | null | undefined): string {
+  return id || GLOBAL_CONVERSATION_ID;
+}
+
+function readState(): PlanState {
+  try {
+    if (!existsSync(STATE_PATH)) return { sessions: {} };
+    const parsed = JSON.parse(readFileSync(STATE_PATH, "utf8"));
+    return parsed?.sessions ? { sessions: parsed.sessions } : { sessions: {} };
+  } catch {
+    return { sessions: {} };
+  }
+}
+
+function writeState(state: PlanState): void {
+  mkdirSync(join(homedir(), ".letta", "extensions"), { recursive: true });
+  writeFileSync(STATE_PATH, JSON.stringify(state, null, 2));
+}
+```
+
+Generate plan paths under `~/.letta/plans/`. The old built-in used random adjective/adjective/noun names like `zesty-dazzling-coral.md`; any collision-resistant readable name is fine.
+
+## Entry command and tool
+
+`/plan` and `enter_plan_mode` should call the same activation helper. The command returns a prompt/system reminder so the agent receives the path. The tool returns the same text as a tool result.
+
+```ts
+function buildEnterPlanModeMessage(session, cwd) {
+  const relativePatchPath = relative(cwd, session.planFilePath).replace(/\\/g, "/");
+  return `Entered plan mode. You should now focus on exploring the codebase and designing an implementation approach.
+
+In plan mode, you should:
+1. Thoroughly explore the codebase to understand existing patterns
+2. Identify similar features and architectural approaches
+3. Consider multiple approaches and their trade-offs
+4. Use AskUserQuestion if you need to clarify the approach
+5. Design a concrete implementation strategy
+6. When ready, write the plan to the plan file, use AskUserQuestion to present the full plan for approval, and call exit_plan_mode after the user approves
+
+Remember: DO NOT write or edit any files except the plan file. This is a read-only exploration and planning phase.
+
+Plan file path: ${session.planFilePath}
+If using apply_patch, use this exact relative patch path: ${relativePatchPath}`;
+}
+
+export default function activate(letta) {
+  const disposers = [];
+
+  if (letta.capabilities.commands) {
+    disposers.push(letta.commands.register({
+      id: "plan",
+      description: "Enter plan mode",
+      override: true,
+      run(ctx) {
+        const session = activatePlanMode(ctx.conversation.id, ctx.cwd);
+        return {
+          type: "prompt",
+          systemReminder: true,
+          content: buildEnterPlanModeMessage(session, ctx.cwd),
+        };
+      },
+    }));
+  }
+
+  if (letta.capabilities.tools) {
+    disposers.push(letta.tools.register({
+      name: "enter_plan_mode",
+      description:
+        "Enter plan mode before a non-trivial implementation task. Use this for new features, multi-file changes, architectural decisions, unclear requirements, or tasks where the user should approve the approach before implementation.",
+      parameters: { type: "object", properties: {}, additionalProperties: false },
+      requiresApproval: true,
+      parallelSafe: false,
+      run(ctx) {
+        const session = activatePlanMode(ctx.conversation.id, ctx.cwd);
+        return buildEnterPlanModeMessage(session, ctx.cwd);
+      },
+    }));
+  }
+
+  return () => disposers.reverse().forEach((dispose) => dispose());
+}
+```
+
+## Turn reminder
+
+Append a reminder while plan mode is active. Keep it narrow and explicit about the allowed plan-file exception:
+
+```ts
+function buildActiveReminder(session, cwd) {
+  const relativePatchPath = relative(cwd, session.planFilePath).replace(/\\/g, "/");
+  return `<system-reminder>
+Plan mode is active. The user indicated that they do not want you to execute yet -- you MUST NOT make any edits (with the exception of the plan file mentioned below), run any non-readonly tools (including changing configs or making commits), or otherwise make any changes to the system. This supersedes any other instructions you have received. Instead, you should:
+1. Answer the user's query comprehensively, using the AskUserQuestion tool if you need to ask the user clarifying questions.
+2. Write your implementation plan to the plan file. Plan file path: ${session.planFilePath}
+3. If using apply_patch, use this exact relative path in patch headers: ${relativePatchPath}
+4. When the plan is complete, read the plan file and present the full plan to the user with AskUserQuestion. The question should offer at least "Approve" and "Revise" options.
+5. If the user approves, call exit_plan_mode immediately. If the user asks to revise, stay in plan mode and update the plan file.
+Do NOT make any file changes outside the plan file or run any tools that modify the system state until the user has approved the plan and you have called exit_plan_mode.
+</system-reminder>`;
+}
+
+if (letta.capabilities.events.turns) {
+  disposers.push(letta.events.on("turn_start", (event) => {
+    const session = getSession(event.conversationId);
+    if (!session) return;
+    return { input: [{ role: "user", content: buildActiveReminder(session, session.cwd) }, ...event.input] };
+  }));
+}
+```
+
+## Permission overlay
+
+Use a permission overlay, not `tool_start`, for policy. Normalize tool names by family; UI display names and provider-specific tool names drift (`Read`, `read`, `read_file`, `ReadFile`, `SearchFileContent`, etc.).
+
+```ts
+const readOnlyToolNames = new Set([
+  "askuserquestion",
+  "ask_user_question",
+  "glob",
+  "grep",
+  "listdir",
+  "list_directory",
+  "ls",
+  "read",
+  "read_file",
+  "readfile",
+  "search",
+  "search_file_content",
+  "skill",
+  "taskoutput",
+  "update_plan",
+  "view_image",
+]);
+
+function normalizedToolName(toolName) {
+  return toolName.replace(/[\s-]/g, "").toLowerCase();
+}
+
+function isReadOnlyToolName(toolName) {
+  const raw = toolName.toLowerCase();
+  return readOnlyToolNames.has(raw) || readOnlyToolNames.has(normalizedToolName(toolName));
+}
+
+function isPlanFileWrite(toolName, args, cwd) {
+  // For Write/Edit-style tools, check file_path/path/notebook_path.
+  // For ApplyPatch-style tools, parse *** Add/Update/Delete File and *** Move to directives.
+  // Allow only if every target resolves to a .md file under ~/.letta/plans/.
+}
+
+if (letta.capabilities.permissions) {
+  disposers.push(letta.permissions.register({
+    id: "plan-mode",
+    description: "Allow read-only tools and writes only to ~/.letta/plans/*.md while plan mode is active.",
+    check(event) {
+      const session = getSession(event.conversationId);
+      if (!session) return;
+
+      if (isReadOnlyToolName(event.toolName)) return { decision: "allow" };
+      if (isPlanFileWrite(event.toolName, event.args, event.workingDirectory || event.cwd)) {
+        return { decision: "allow", reason: "plan file" };
+      }
+
+      return {
+        decision: "deny",
+        reason:
+          `Plan mode is active. You can only use read-only tools (Read, Grep, Glob, etc.) and write to the plan file. ` +
+          `Write your plan to: ${session.planFilePath}. ` +
+          `Use AskUserQuestion when your plan is ready for user approval, then call exit_plan_mode after approval.`,
+      };
+    },
+  }));
+}
+```
+
+Shell allowlists are easy to get wrong. Start conservative: allow clearly read-only shell commands if needed, plus a narrow plan-file heredoc or `mv old.md new.md` only when every target is inside `~/.letta/plans/*.md`. Deny mutating shell patterns such as `sed -i`, `find -delete`, `rm`, `cp`, `touch`, package installs, and arbitrary interpreters.
+
+## Exit tool
+
+In the extension version, `exit_plan_mode` is not the approval UI. The agent should present the plan with `AskUserQuestion` first, then call `exit_plan_mode` only after the user approves.
+
+```ts
+if (letta.capabilities.tools) {
+  disposers.push(letta.tools.register({
+    name: "exit_plan_mode",
+    description:
+      "Exit plan mode only after the plan file has been written, the full plan has been presented with AskUserQuestion, and the user has approved it.",
+    parameters: { type: "object", properties: {}, additionalProperties: false },
+    requiresApproval: false,
+    parallelSafe: false,
+    run(ctx) {
+      const session = getSession(ctx.conversation.id);
+      if (!session) {
+        return { status: "error", content: "Plan mode is not active for this conversation." };
+      }
+      if (!planFileExists(session)) {
+        return {
+          status: "error",
+          content:
+            `You must write your plan to a plan file before exiting plan mode.\n` +
+            `Plan file path: ${session.planFilePath}\n` +
+            `Use a write tool to create your plan in ${PLANS_DIR}, then use AskUserQuestion to present the plan to the user.`,
+        };
+      }
+
+      clearSession(ctx.conversation.id);
+      return (
+        "User has approved your plan. You can now start coding.\n" +
+        "Start with updating your todo list if applicable.\n\n" +
+        "Tip: If this plan will be referenced in the future by your future-self, other agents, or humans, consider renaming the plan file to something easily identifiable with a timestamp (e.g., `2026-01-auth-refactor.md`) rather than the random name."
+      );
+    },
+  }));
+}
+```
+
+## Notes
+
+- Keep `exit_plan_mode` as the final state transition and execution handoff. The approved-plan text in its tool return is useful model context.
+- If the user renames the plan file, exit logic can use the newest non-empty `~/.letta/plans/*.md` modified after plan mode started, or accept an optional plan path. Keep the user-facing flow normal: write plan file, ask approval, then exit.

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

@@ -0,0 +1,110 @@
+# Extension provider recipes
+
+Use provider extensions when the user wants a **local agent** to use a model provider that is not built into `/connect` and `/model`.
+
+Important: provider extensions are local-backend/local-agent only. They register local provider metadata for the TUI, headless local runtime, and desktop listener. They do not add providers for Constellation/cloud agents.
+
+For multi-capability extensions that combine a provider with commands, tools, UI, or state, also read `architecture.md`.
+
+## Quick pattern
+
+```ts
+// ~/.letta/extensions/kilo.ts
+export default function activate(letta) {
+  if (!letta.capabilities.providers) return;
+
+  return letta.providers.register("kilo", {
+    name: "Kilo",
+    description: "Connect to Kilo's OpenAI-compatible API",
+    api: "openai-completions",
+    baseUrl: "https://api.kilo.example/v1",
+    apiKey: "KILO_API_KEY", // env var name, not the raw secret
+    authHeader: true,
+    models: [
+      {
+        id: "kilo-code",
+        name: "Kilo Code",
+        reasoning: true,
+        input: ["text"],
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: 128000,
+        maxTokens: 8192,
+        compat: {
+          supportsDeveloperRole: false,
+          supportsReasoningEffort: false,
+        },
+      },
+    ],
+    connect: {
+      fields: [{ key: "apiKey", label: "Kilo API Key", secret: true }],
+    },
+  });
+}
+```
+
+After `/reload`, the provider appears in local `/connect` and desktop Connect model providers. Model handles are `<provider-id>/<model-id>`, for example `kilo/kilo-code`.
+
+## Key rules
+
+- Always guard with `letta.capabilities.providers`.
+- Prefer `letta.providers.register(...)` over legacy `letta.registerProvider(...)`.
+- Keep provider registration independent from commands/tools/UI/events and `letta.client`; the desktop listener loads provider-only extensions.
+- Do not hardcode real secrets. `apiKey: "ENV_VAR"` resolves `process.env.ENV_VAR` when present, or lets `/connect` save a local key.
+- Use stable lowercase provider ids. Model ids must be unprefixed and must not contain `/`.
+- Set `api` at provider or model level. Common values include `"openai-completions"`, `"openai-responses"`, `"anthropic-messages"`, and `"bedrock-converse-stream"`; check `src/backend/dev/pi-provider-extension-types.ts` and pi-ai model types before using uncommon values.
+
+## Model metadata
+
+Each model needs enough local runtime metadata for selection and context display:
+
+```ts
+{
+  id: "model-id-without-provider-prefix",
+  name: "Display Name",
+  reasoning: false,
+  input: ["text"], // or ["text", "image"]
+  cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+  contextWindow: 128000,
+  maxTokens: 8192,
+  // Optional: compat: { supportsDeveloperRole: false, supportsReasoningEffort: false }
+}
+```
+
+Do not set `model.baseUrl` when all models use the provider-level URL. Model-level `baseUrl` overrides the connected provider base URL, so `/connect` base URL overrides are ignored. Use it only when a specific model intentionally needs a different endpoint.
+
+## Connect fields
+
+- `connect: undefined` / `true` uses default API key + base URL fields.
+- `connect: { fields: [...] }` customizes local `/connect` / desktop fields.
+- `connect: false` hides the provider from `/connect`; use only when credentials come entirely from env/local code.
+- Custom fields are currently required. TUI pre-fills non-secret placeholders for convenience, but placeholders are not backend/protocol defaults.
+- If the provider has a normal fixed `baseUrl`, set provider-level `baseUrl` and omit `baseUrl` from `connect.fields`; the local runtime uses the provider-level URL after the API key is saved.
+- Include `{ key: "baseUrl", ... }` only when the user must enter or review/override the endpoint during connect.
+
+## Dynamic model discovery
+
+Use `listModels(connection)` only when the provider exposes a models endpoint or the model list depends on credentials:
+
+```ts
+async listModels(connection) {
+  const response = await fetch(`${connection.baseUrl}/models`, {
+    headers: {
+      Authorization: `Bearer ${connection.apiKey}`,
+      ...connection.headers,
+    },
+  });
+  if (!response.ok) throw new Error(`Model list failed: ${response.status}`);
+  const body = await response.json();
+  return body.data.map((model) => ({
+    id: model.id,
+    name: model.id,
+    reasoning: false,
+    input: ["text"],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 8192,
+  }));
+}
+```
+
+`connection` has `{ id, providerName, baseUrl?, apiKey?, headers? }`. Keep dynamic listing lightweight; if it is flaky, prefer static `models`.

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

@@ -4,6 +4,13 @@ Use tools when the agent/model should call a local capability autonomously.
 
 For tools that are part of a larger extension with commands, UI, local state, or events, also read `architecture.md`.
 
+## Contents
+
+- Defaults
+- Read-only shell tool
+- Tool with arguments
+- Mutating or risky tool
+
 ## Defaults
 
 - Name: lowercase/underscore tool name, e.g. `branch_summary`.

package/skills/customizing-commands/SKILL.md

@@ -5,7 +5,7 @@ description: Creates, edits, and enables Letta Code extension-provided slash com
 
 # Customizing Commands
 
-Use this as the command-specific entrypoint for local extension slash commands. For broader extension work, recipes live in `../creating-extensions/references/commands.md`, `../creating-extensions/references/architecture.md`, `../creating-extensions/references/ui.md`, and `../creating-extensions/references/btw-command.md`.
+Use this as the command-specific entrypoint for local extension slash commands. For broader extension work, recipes live in `../creating-extensions/references/commands.md`, `../creating-extensions/references/architecture.md`, `../creating-extensions/references/ui.md`, and `../creating-extensions/references/plan-mode.md`.
 
 Extension files live in:
 
@@ -87,4 +87,4 @@ type ExtensionCommandResult =
 - Simple output command, panel command, busy-safe conversation command: `../creating-extensions/references/commands.md`
 - Complex command architecture, state, cleanup: `../creating-extensions/references/architecture.md`
 - Panel/status UI patterns: `../creating-extensions/references/ui.md`
-- Complete `/btw` side-question recipe: `../creating-extensions/references/btw-command.md`
+- Worked plan-mode command/tool composition: `../creating-extensions/references/plan-mode.md`

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

@@ -1,106 +0,0 @@
-# `/btw` side-question extension example
-
-This example runs while the main agent is busy because it forks the scoped conversation, streams a response in the fork, renders progress in a panel when panels are available, and returns `{ type: "handled" }` immediately.
-
-```ts
-export default function activate(letta) {
-  if (!letta.capabilities.commands) return;
-
-  function createOtid() {
-    return (
-      globalThis.crypto?.randomUUID?.() ??
-      `btw-${Date.now()}-${Math.random().toString(16).slice(2)}`
-    );
-  }
-
-  function appendAssistantText(chunk, parts) {
-    if (chunk.message_type !== "assistant_message") return;
-    const content = chunk.content;
-    if (typeof content === "string") {
-      parts.push(content);
-      return;
-    }
-    if (Array.isArray(content)) {
-      for (const part of content) {
-        if (part && typeof part === "object" && "text" in part) {
-          parts.push(String(part.text));
-        }
-      }
-      return;
-    }
-    if (content && typeof content === "object" && "text" in content) {
-      parts.push(String(content.text));
-    }
-  }
-
-  function openPanelOrNull(content) {
-    if (!letta.capabilities.ui.panels) return null;
-    return letta.ui.openPanel({ id: "btw", content });
-  }
-
-  return letta.commands.register({
-    id: "btw",
-    description: "Ask a side question in a forked conversation",
-    args: "<question>",
-    runWhenBusy: true,
-    showInTranscript: false,
-    run(ctx) {
-      const question = ctx.args.trim();
-      if (!question) {
-        const panel = openPanelOrNull(["/btw", "Usage: /btw <question>"]);
-        if (panel) setTimeout(() => panel.close(), 5_000);
-        return { type: "handled" };
-      }
-
-      const panel = openPanelOrNull([`/btw ${question}`, "..."]);
-
-      void (async () => {
-        try {
-          const forked = await ctx.conversation.fork({ hidden: true });
-          const stream = await forked.sendMessageStream(
-            [
-              {
-                role: "user",
-                content: `${question}\n\nAnswer briefly in 1-3 short sentences.`,
-                otid: createOtid(),
-              },
-            ],
-            {
-              overrideModel: ctx.model.id ?? undefined,
-              workingDirectory: ctx.cwd,
-            },
-          );
-
-          const parts = [];
-          for await (const chunk of stream) {
-            appendAssistantText(chunk, parts);
-            panel?.update({
-              content: [`/btw ${question}`, parts.join("") || "..."],
-            });
-          }
-
-          panel?.update({
-            content: [
-              `done /btw ${question}`,
-              parts.join("").trim() || "No response.",
-            ],
-          });
-          if (panel) setTimeout(() => panel.close(), 10_000);
-        } catch (error) {
-          panel?.update({
-            content: [
-              `error /btw ${question}`,
-              error instanceof Error ? error.message : String(error),
-            ],
-          });
-          if (panel) setTimeout(() => panel.close(), 15_000);
-        }
-      })();
-
-      return { type: "handled" };
-    },
-  });
-}
-```
-
-Add custom borders, right alignment, wrapping, or history only if the user asks for that polish.