@letta-ai/letta-code 0.27.5 → 0.27.6

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

@@ -1,57 +1,12 @@
 # Extension provider recipes
 
-Use provider extensions when the user wants Letta Code local agents to use a model provider that is not built into `/connect` and `/model`.
+Use provider extensions when the user wants a **local agent** to use a model provider that is not built into `/connect` and `/model`.
 
-**Important scope:** custom provider extensions are for **local agents only**. They register local provider metadata used by the local backend/TUI/desktop listener. They do not add providers for Constellation/cloud agents.
+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`.
 
-## Contents
-
-- When to use
-- Surface behavior and limitations
-- Capability guard
-- Basic API-key provider
-- Config fields
-- Dynamic model discovery
-- Connect behavior
-- Review checklist
-
-## When to use
-
-Use a provider extension when:
-
-- the provider API is supported by the local pi-ai adapter stack; OpenAI-compatible providers usually use `api: "openai-completions"` or `api: "openai-responses"`
-- the user wants the provider to appear in local `/connect` / desktop Connect model providers
-- local `/model` should show static or dynamically listed models from that provider
-- local turns should resolve model handles like `kilo/kilo-code`
-
-Do **not** use a provider extension when the user is asking to configure a Constellation/cloud provider. For cloud agents, use the product's normal provider configuration path instead.
-
-## Surface behavior and limitations
-
-- TUI/headless local agents can load provider extensions along with other extension capabilities.
-- The desktop listener loads provider extensions so desktop's local provider UI can list and connect them.
-- Listener provider loading is provider-only. Do not rely on commands, tools, UI, events, or `letta.client` while registering a provider.
-- Provider extensions should use local data, environment variables, local provider connections, and direct `fetch`/Node APIs. They should not use Constellation-specific APIs to make a local provider work.
-
-## Capability guard
-
-Always guard provider registration:
-
-```ts
-export default function activate(letta) {
-  if (!letta.capabilities.providers) return;
-
-  return letta.providers.register("kilo", {
-    // provider config
-  });
-}
-```
-
-`letta.registerProvider(id, config)` is also supported, but prefer `letta.providers.register(...)` so the capability being used is explicit.
-
-## Basic API-key provider
+## Quick pattern
 
 ```ts
 // ~/.letta/extensions/kilo.ts
@@ -63,7 +18,8 @@ export default function activate(letta) {
     description: "Connect to Kilo's OpenAI-compatible API",
     api: "openai-completions",
     baseUrl: "https://api.kilo.example/v1",
-    apiKey: "KILO_API_KEY",
+    apiKey: "KILO_API_KEY", // env var name, not the raw secret
+    authHeader: true,
     models: [
       {
         id: "kilo-code",
@@ -73,136 +29,82 @@ export default function activate(letta) {
         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 },
-      ],
+      fields: [{ key: "apiKey", label: "Kilo API Key", secret: true }],
     },
   });
 }
 ```
 
-After `/reload`, this provider appears in local `/connect` and in the desktop local provider page. The model handle is `<provider-id>/<model-id>`, for example `kilo/kilo-code`.
+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`.
 
-## Config fields
+## Key rules
 
-Common provider config fields:
+- 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.
 
-```ts
-{
-  name?: string;
-  description?: string;
-  api?: string;             // common: "openai-completions", "openai-responses", "anthropic-messages", "bedrock-converse-stream"
-  baseUrl?: string;
-  apiKey?: string;          // env var name to resolve, e.g. "KILO_API_KEY"
-  headers?: Record<string, string>; // values resolve through process.env when present
-  authHeader?: boolean;     // add Authorization: Bearer <apiKey>
-  models?: Array<model>;
-  listModels?: (connection) => Promise<Array<model>> | Array<model>;
-  connect?: boolean | { fields?: Array<field> };
-}
-```
+## Model metadata
 
-Check `src/backend/dev/pi-provider-extension-types.ts` and pi-ai model types before documenting or using an uncommon `api` value.
-
-Model entries must include useful local runtime metadata:
+Each model needs enough local runtime metadata for selection and context display:
 
 ```ts
 {
   id: "model-id-without-provider-prefix",
   name: "Display Name",
-  api?: "openai-completions",
   reasoning: false,
-  input: ["text"],          // or ["text", "image"]
+  input: ["text"], // or ["text", "image"]
   cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
   contextWindow: 128000,
   maxTokens: 8192,
-  headers?: {},
+  // 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 will be ignored. Use it only when a specific model intentionally needs a different endpoint.
+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)` when the provider exposes a models endpoint or the model list depends on connected credentials:
+Use `listModels(connection)` only when the provider exposes a models endpoint or the model list depends on credentials:
 
 ```ts
-export default function activate(letta) {
-  if (!letta.capabilities.providers) return;
-
-  return letta.providers.register("kilo", {
-    name: "Kilo",
-    api: "openai-completions",
-    baseUrl: "https://api.kilo.example/v1",
-    apiKey: "KILO_API_KEY",
-    async listModels(connection) {
-      const response = await fetch(`${connection.baseUrl}/models`, {
-        headers: {
-          Authorization: `Bearer ${connection.apiKey}`,
-          ...connection.headers,
-        },
-      });
-      if (!response.ok) {
-        throw new Error(`Kilo 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,
-      }));
+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` contains the provider id/name plus resolved local connection details:
-
-```ts
-{
-  id: string;
-  providerName: string;
-  baseUrl?: string;
-  apiKey?: string;
-  headers?: Record<string, string>;
-}
-```
-
-Keep dynamic listing lightweight and fail with short actionable errors. If listing is flaky, provide a static `models` fallback instead.
-
-## Connect behavior
-
-- `connect: undefined` or `connect: 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 environment variables or local code.
-- `apiKey: "ENV_VAR_NAME"` resolves from `process.env.ENV_VAR_NAME` when available. Do not hardcode real secrets.
-- Custom fields are currently required. `placeholder` is display-only, not a default value.
-- If the provider has a normal fixed `baseUrl`, set provider-level `baseUrl` and omit `baseUrl` from `connect.fields`; the local runtime will use the provider-level URL after the API key is saved.
-- Include `{ key: "baseUrl", ... }` only when the user must enter or override the endpoint during connect.
-
-Default custom fields use these keys when possible because the local provider store understands them:
-
-```ts
-{ key: "apiKey", label: "API Key", secret: true }
-{ key: "baseUrl", label: "Base URL" }
-```
-
-## Review checklist
-
-- The extension says or implies the provider is local-agent only when reporting back to the user.
-- `letta.capabilities.providers` is checked before registration.
-- Provider id is stable, lowercase, and suitable as the model-handle prefix.
-- Model ids are unprefixed; Letta Code exposes them as `<provider-id>/<model-id>`.
-- `contextWindow`, `maxTokens`, `input`, and `reasoning` metadata are accurate enough for local selection and context display.
-- Model-level `baseUrl` is omitted unless the model intentionally needs a different endpoint from the provider/connection.
-- `connect.fields` contains only fields the user must type; placeholders are not treated as defaults.
-- Secrets are read from environment/local provider connections, not hardcoded.
-- Provider registration does not depend on commands/tools/UI/events or `letta.client`.
-- The user is told to run `/reload`, then configure the provider through local `/connect` or desktop Connect model providers.
+`connection` has `{ id, providerName, baseUrl?, apiKey?, headers? }`. Keep dynamic listing lightweight; if it is flaky, prefer static `models`.

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.