@letta-ai/letta-code 0.31.9 → 0.31.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.31.9",
+  "version": "0.31.11",
   "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

@@ -2,7 +2,7 @@
   "src/agent/client-skills.test.ts": 1134,
   "src/agent/memory-git.ts": 2090,
   "src/backend/local-backend.test.ts": 2532,
-  "src/backend/local/local-backend.ts": 1014,
+  "src/backend/local/local-backend.ts": 1012,
   "src/backend/local/local-store.ts": 3459,
   "src/backend/pi-stream-adapter.test.ts": 1304,
   "src/cli/app/AppCoordinator.tsx": 5188,
@@ -23,7 +23,7 @@
   "src/cli/subcommands/skills.ts": 1264,
   "src/headless.ts": 4994,
   "src/hooks/integration.test.ts": 1147,
-  "src/index.ts": 2775,
+  "src/index.ts": 2773,
   "src/mods/learning-harness.ts": 2434,
   "src/mods/mod-engine.test.ts": 2153,
   "src/mods/mod-engine.ts": 1838,
@@ -44,7 +44,6 @@
   "src/websocket/listener/file-commands.ts": 1053,
   "src/websocket/listener/lifecycle.ts": 1048,
   "src/websocket/listener/protocol-inbound.ts": 2207,
-
   "src/websocket/listener/protocol-outbound.ts": 1047,
   "src/websocket/listener/turn.ts": 1058
 }

package/skills/submitting-feedback/SKILL.md

@@ -9,13 +9,23 @@ When the user appears upset with the agent, acknowledge the problem and ask whet
 
 If the user says yes, or directly asks you to submit feedback:
 
-1. Write a short factual message in the user's voice. Include what happened, what the user expected, and any useful error or behavior detail already present in the conversation. Do not add claims the user did not make.
-2. Submit it with:
+1. Gather the relevant context already available in the conversation and environment. If a detail essential to understanding or reproducing the problem is missing, ask the user one focused question before submitting. Do not invent missing details.
+2. Write a concise, factual report in your own voice as the agent. Do not impersonate the user or make the report sound user-authored. The first line must disclose: `Agent-submitted feedback on behalf of the user.`
+
+   Include:
+   - Your agent name.
+   - Who you are working with (the user's name or role, if known; otherwise say `user not identified`).
+   - The task or goal underway when the problem occurred and enough surrounding context to understand why it mattered.
+   - What actually happened, what the user expected, and the impact on the task.
+   - Concrete evidence already available, such as exact error text, the failed command or action, relevant paths or links, and reliable reproduction steps. Distinguish what the user reported from what you observed or inferred.
+
+   Prefer specific nouns and observable behavior over generic judgments. Do not submit context-free summaries such as “the feature is broken,” “the UX should be improved,” or polished product-language filler. Keep unknowns explicit rather than guessing.
+3. Submit it with:
 
 ```bash
 letta feedback --message '<feedback>'
 ```
 
-3. Tell the user whether submission succeeded. If it failed, report the safe CLI error and do not claim the team received it.
+4. Tell the user whether submission succeeded. If it failed, report the safe CLI error and do not claim the team received it.
 
 Do not include secrets, credentials, unrelated conversation content, or private file contents. The command adds the current agent and conversation identifiers so the team can find the relevant run.

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

@@ -0,0 +1,44 @@
+---
+name: using-mcp-tools
+description: Reference for the `letta mcp` CLI, which finds and invokes MCP tools available to this agent. A system reminder already lists your connected MCP servers and the basic search/schema/call commands; invoke this skill when you need more — browsing a server's tools, passing large or file-based arguments, tuning search, or troubleshooting missing servers, tools, and errors.
+---
+
+# Using MCP tools
+
+`letta mcp` gives the agent one unified view of every MCP server it can reach: servers connected to the agent in Letta Cloud and servers configured locally on this machine. It works from any surface where the agent runs — cloud sandboxes (chat.letta.com), Letta Desktop, and terminals. All output is JSON.
+
+## Commands
+
+```bash
+letta mcp list                                # servers: [{name, transport}]
+letta mcp get <server>                        # one server's connection configuration (credentials redacted)
+letta mcp tools [server]                      # tool names + descriptions only
+letta mcp tools [server] --full               # ...including every tool's complete schema
+letta mcp schema <tool-name>                  # one tool's complete schema
+letta mcp search <query> [--mode] [--limit]   # ranked tool schemas: [{tool, rank, score}]
+letta mcp call <tool-name> [--args | --args-file]  # run a tool, print a CallToolResult
+```
+
+Every command accepts `--agent <id>`, defaulting to `LETTA_AGENT_ID`/`AGENT_ID` — do not pass it unless targeting another agent.
+
+## Search options
+
+- `--mode <hybrid|vector|fts>` — default `hybrid`. `vector` uses server-side embeddings and covers only cloud-connected servers; `fts` and `hybrid` also rank local tools lexically. Agents on a local backend cannot use `vector`.
+- `--limit <n>` — result count, 1-100 (default 5).
+- Rank order is meaningful; absolute scores are not comparable across queries. When even the top results look unrelated to the query, no relevant tool likely exists — do not force the best-ranked one.
+
+## Call arguments and results
+
+- `--args '<json>'` — inline JSON object.
+- `--args-file <path>` — read the JSON object from a file; `--args-file -` reads stdin. Use these for large or shell-quoting-hostile payloads.
+- Output is an MCP CallToolResult: `content` (array of typed blocks), optional `structuredContent`, and `isError`.
+- Exit codes: `0` success, `1` CLI/usage error (JSON on stderr: `{error: {code, message, hint?}}`), `2` the tool ran and returned an error result — read `content` for the server's message, fix the arguments, and retry.
+- Summarize relevant results instead of pasting large raw payloads.
+
+## Troubleshooting
+
+- `list` empty → no MCP servers are available. Ask the user to connect one on the Letta Cloud MCP servers page or configure a local one in the Letta Code app.
+- Cloud server with no tools (or `0 tools` in the reminder) → tools were never synced. Ask the user to resync it from the MCP servers page; the CLI has no refresh action.
+- `unauthorized` or another auth error on `call` → the server's stored credentials are missing or stale (`tools` can still list from previously synced rows). Ask the user to re-authenticate the server: cloud servers on the MCP servers page, local OAuth servers by connecting once in the Letta Code app — this CLI is non-interactive and only reuses persisted credentials.
+- `ambiguous_server_name` → two servers share a name; the error hint explains how to disambiguate.
+- Duplicate tool names across servers get a numeric suffix (`_2`); the printed name is always the callable one.

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

@@ -1,37 +0,0 @@
----
-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.