@letta-ai/letta-code 0.31.2 → 0.31.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.31.2",
+  "version": "0.31.4",
   "description": "Letta Code is a CLI tool for interacting with stateful Letta agents from the terminal.",
   "type": "module",
   "packageManager": "bun@1.3.10",

package/scripts/source-file-size-baseline.json

@@ -17,7 +17,7 @@
   "src/cli/components/ProviderSelector.tsx": 1692,
   "src/cli/components/ToolCallMessageRich.tsx": 1109,
   "src/cli/helpers/accumulator.ts": 1592,
-  "src/cli/helpers/reflection-transcript.ts": 1956,
+  "src/cli/helpers/reflection-transcript.ts": 1929,
   "src/cli/mods/local-mod-loader.test.ts": 1043,
   "src/cli/reflection-transcript.test.ts": 1084,
   "src/cli/subcommands/skills.ts": 1264,
@@ -35,7 +35,7 @@
   "src/providers/chatgpt-usage-service.ts": 1112,
   "src/settings-manager.test.ts": 1635,
   "src/settings-manager.ts": 2102,
-  "src/tools/manager.ts": 2993,
+  "src/tools/manager.ts": 2969,
   "src/tools/tool-execution-context.test.ts": 1138,
   "src/types/protocol_v2.ts": 2666,
   "src/websocket/listen-client-concurrency.test.ts": 2686,

package/skills/editing-letta-code-desktop-preferences/SKILL.md

@@ -15,12 +15,22 @@ The Desktop preferences file is:
 ~/.letta/desktop_preferences.json
 ```
 
-Known preference keys:
+User-editable preference keys:
 
 - `defaultWorkingDirectory`: default folder for new local sessions.
 - `theme`: `auto`, `light`, or `dark`.
 - `allowRemoteAccess`: boolean for whether remote access should be enabled in preferences.
-- `remoteEnvName`: environment name shown for remote access.
+- `runInBackground`: boolean for whether Desktop stays alive in tray/menu bar when all windows close.
+- `startAtLogin`: boolean for whether Desktop starts hidden at login.
+- `remoteEnvName`: environment name shown in the Letta Cloud environment picker for the cloud listener.
+- `localBackendDirectory`: directory containing local backend agents, conversations, and memory.
+- `allowLocalAgentsWhenSignedIn`: boolean for whether signed-in Desktop sessions can see local/offline agents.
+
+System-managed keys (do not edit directly):
+- `artifactsByAgent`: per-agent artifacts panel state, written by Desktop UI.
+- `debugPanelEnabled`: developer debug panel, controlled via app menus.
+- `remoteAppServerEnabled`: Remote App Server toggle, applied at startup.
+- `remoteAppServerUrl`: Remote App Server URL, configured via preferences UI.
 
 ## Workflow
 
@@ -29,7 +39,7 @@ Known preference keys:
 3. Merge only the requested preference updates.
 4. Write pretty JSON with a trailing newline.
 5. Do not edit token, provider, secret, agent, conversation, memory, or unrelated state files.
-6. Tell the user that the change applies live only if their Desktop build watches preference-file changes; otherwise they should reload/restart Desktop or use Preferences → General.
+6. Changes apply live within ~100ms via Desktop's file watcher; if Desktop is not running, changes take effect on next startup.
 
 ## Safe edit command
 

package/skills/finding-agents/SKILL.md

@@ -96,19 +96,17 @@ Returns the raw API response with full agent details. Key fields:
 ## Related Skills
 
 - **migrating-memory** - Once you find an agent, use this skill to copy/share memory blocks
-- **searching-messages** - Search messages across all agents to find which agent discussed a topic. Use `--all-agents` to get `agent_id` values, then use this skill to get full agent details.
 
 ### Finding Agents by Topic
 
 If you need to find which agent worked on a specific topic:
 
-1. Load both skills: `searching-messages` and `finding-agents`
-2. Search messages across all agents:
+1. Search messages across all agents:
    ```bash
    letta messages search --query "topic" --all-agents --limit 10
    ```
-3. Note the `agent_id` values from matching messages
-4. Get agent details:
+2. Note the `agent_id` values from matching messages
+3. Get agent details:
    ```bash
    letta agents list --query "partial-name"
    ```

package/skills/messaging-agents/SKILL.md

@@ -52,7 +52,7 @@ letta agents list --tags "origin:letta-code"
 ```
 
 ### By Topic They Discussed
-Load the `searching-messages` skill to find which agent worked on something:
+Search messages across all agents to find which agent worked on something:
 ```bash
 letta messages search --query "topic" --all-agents
 ```
@@ -157,7 +157,7 @@ letta -p --from-agent $LETTA_AGENT_ID \
 - Text-mode scripts return only the **final assistant message** (not tool calls, reasoning, or metadata)
 - JSON and stream-json responses include `agent_id`, `conversation_id`, and `environment.source` so you can continue the same conversation/runtime. Environment-routed turns also include `environment.id`, `connection_id`, `device_id`, and `name`.
 - The target agent may use tools, think, and reason - but you only see their final response
-- To see the full conversation transcript (including tool calls), use the `searching-messages` skill with `letta messages list --agent <id>` targeting the other agent
+- To see the full conversation transcript (including tool calls), use `letta messages list --agent <id>` targeting the other agent
 
 ## How It Works
 
@@ -186,4 +186,3 @@ Continuing a hidden conversation with `--conversation <id>` keeps it hidden —
 ## Related Skills
 
 - **finding-agents**: Find agents by name, tags, or fuzzy search
-- **searching-messages**: Search past messages across agents, or view full conversation transcripts

package/skills/self-configuration/SKILL.md

@@ -257,7 +257,11 @@ Selected global settings keys:
 | `preferredBackendMode` | Startup backend preference, `api` or `local` |
 | `channelCredentialsStore` | Channel token storage, `file`, `keyring`, or `auto` |
 | `reflectionTrigger` / `reflectionStepCount` | Default reflection cadence |
+| `reflectionMerge` / `reflectionMergeInstructions` | Reflection change integration policy |
 | `reflectionSettingsByAgent` | Per-agent reflection cadence |
+| `conversationSwitchAlertEnabled` | Send system-reminder when switching conversations/agents |
+| `createDefaultAgents` | Create Memo/Incognito default agents on startup (default: true) |
+| `windowTitle` | Configurable terminal window title fields |
 | `permissions` | Allow/deny/ask/alwaysAsk rules |
 | `env` | User-wide environment variables for Letta Code |
 | `experiments` | Feature flags |
@@ -271,7 +275,7 @@ Toolset values currently include `auto`, `default`, `codex`, `codex_snake`, `gem
 
 ## Permissions
 
-Permissions decide whether tool calls are allowed, denied, or require approval. User/global permission rules affect all agents using that settings file: `allow` can weaken review, while `deny` and `alwaysAsk` can brick workflows. Valid modes are `standard`, `acceptEdits`, and `unrestricted`; legacy `default` maps to `standard`, while `bypassPermissions` and `fullAccess` map to `unrestricted`. The default mode is `unrestricted` unless startup flags or settings override it.
+Permissions decide whether tool calls are allowed, denied, or require approval. User/global permission rules affect all agents using that settings file: `allow` can weaken review, while `deny` and `alwaysAsk` can brick workflows. Valid modes are `standard`, `acceptEdits`, `unrestricted`, and `strict`; legacy `default` maps to `standard`, while `bypassPermissions` and `fullAccess` map to `unrestricted`. The default mode is `unrestricted` unless startup flags or settings override it.
 
 The removed `memory` mode is invalid; memory access is governed by normal tool permissions plus the server/filesystem checks on the path used. These helper guardrails do not restrict raw Bash/API access. `permissions.mode` supplies a persisted startup default, rule lists still take precedence, and channel accounts have their own `defaultPermissionMode`. Inspect all three when channel approvals differ from the interactive CLI.
 

package/skills/using-cloud-mcp/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: using-cloud-mcp
+description: Uses MCP servers connected to the current Letta Cloud agent (cloud MCP). Load when the user asks to use a connected MCP server, list the agent's MCP servers or MCP tools, run an MCP tool connected in ADE/chat, or mentions cloud MCP, server-side MCP, agent MCP, or `letta cloud-mcp`.
+---
+
+# Using Cloud MCP
+
+Letta Cloud stores MCP server connections per agent. The `letta cloud-mcp` CLI lists and runs those servers' tools through the Letta API, so it works from any surface where the agent runs: cloud sandboxes (chat.letta.com), Letta Desktop, and terminals.
+
+## Workflow
+
+1. List MCP servers connected to this agent:
+
+```bash
+letta cloud-mcp list
+```
+
+2. Pick the relevant `id` from the JSON output, then list its tools:
+
+```bash
+letta cloud-mcp tools <mcp-server-id>
+```
+
+3. Pick a tool `id`, inspect its name and description, and run it with a JSON object:
+
+```bash
+letta cloud-mcp run <mcp-server-id> <tool-id> --args '{"key":"value"}'
+```
+
+## Rules
+
+- Do not ask for an agent ID unless the user wants another agent. The CLI reads `LETTA_AGENT_ID`/`AGENT_ID` from the environment.
+- Treat command output as JSON. Summarize relevant results instead of pasting large raw payloads.
+- If `list` is empty, ask the user to connect an MCP server to the agent on the MCP servers page.
+- If `tools` is empty for a connected server, the server's tools were never synced. Ask the user to resync the server from the MCP servers page; the CLI has no refresh action.
+- If a connected server has type `stdio`, its tools cannot run on hosted Letta Cloud. Tell the user instead of retrying.
+- This requires a signed-in Letta Cloud agent. MCP servers configured locally in the terminal (`/mcp`) are unrelated to this CLI.

package/skills/using-server-mcp/SKILL.md

@@ -1,36 +0,0 @@
----
-name: using-server-mcp
-description: Uses MCP servers that are already connected to the current Letta Cloud agent through server-side MCP associations. Load when the user asks to use an associated MCP server, list an agent's MCP servers or MCP tools, run an MCP tool connected in ADE/chat, or mentions server-side MCP, agent MCP, or `letta server-mcp`.
----
-
-# Using Server-Side MCP
-
-Use this skill when the current Letta Cloud agent has MCP servers connected in Letta and you need to discover or run their tools.
-
-## Workflow
-
-1. List connected MCP servers:
-
-```bash
-letta server-mcp list
-```
-
-2. Pick the relevant `id` from the JSON output, then list its tools:
-
-```bash
-letta server-mcp tools <mcp-server-id>
-```
-
-3. Pick a tool `id`, inspect the tool name/description, and run it with a JSON object:
-
-```bash
-letta server-mcp run <mcp-server-id> <tool-id> --args '{"key":"value"}'
-```
-
-## Rules
-
-- Prefer the `letta server-mcp ...` CLI over model-facing MCP tools. There is no dedicated `agent_mcp` tool.
-- Do not ask for an agent ID unless the user wants another agent. In normal Letta Code sessions the CLI reads `LETTA_AGENT_ID`/`AGENT_ID` from the environment.
-- Treat command output as JSON. Summarize relevant results instead of pasting large raw payloads.
-- If no servers are listed, tell the user to connect an MCP server to the agent in the MCP servers page first.
-- This only works for signed-in Letta Cloud agents with server-side MCP support. It is separate from local MCP transport testing or converting arbitrary MCP servers into skills.