@letta-ai/letta-code 0.31.10 → 0.31.12

package/package.json

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

@@ -21,9 +21,9 @@
   "src/cli/mods/local-mod-loader.test.ts": 1043,
   "src/cli/reflection-transcript.test.ts": 1084,
   "src/cli/subcommands/skills.ts": 1264,
-  "src/headless.ts": 4994,
+  "src/headless.ts": 4986,
   "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,

package/skills/browser-use/SKILL.md

@@ -19,66 +19,30 @@ Protocol reference: https://chromedevtools.github.io/devtools-protocol/.
 The running browser's exact schema is at `http://127.0.0.1:<port>/json/protocol`;
 tip-of-tree docs can differ from the installed version.
 
-## Managed cloud sandbox default: visible browser
-
-When running in a cloud sandbox, default every browser task to the visible
-managed desktop, even when the user did not explicitly ask to watch. Most
-browser tasks exist because plain HTTP is not enough; a headless browser is
-more likely to trigger bot protection and gives the user no way to observe or
-take over. This matters especially for clicking or typing, forms, sign-in,
-checkout/payment, CAPTCHAs or bot protection, and user handoff.
-
-For the first managed-sandbox browser window, use the skill's launcher instead
-of assembling Chrome, DISPLAY, or Xvfb commands yourself:
-
-```bash
-/root/.letta/cloud-skills/browser-use/scripts/open-visible-browser.sh 'https://example.com'
-```
-
-It starts the managed desktop and launches Chrome through the persistent Cua
-Driver with its required root flag. Then load `computer-use` for visible
-interaction. If protocol-level control is necessary, use Cua Driver's explicit
-`browser_prepare` flow after binding the exact visible window; do not pass
-remote-debugging flags through `launch_app`. The launcher exits zero only
-after Cua Driver reports an on-screen browser window. If it exits nonzero, stop
-and report the launch failure instead of claiming the browser opened.
+## Visible by default when a display exists
+
+When the computer has a display, prefer a visible (headful) browser for any
+task the user might watch or take over: clicking or typing, forms, sign-in,
+checkout/payment, CAPTCHAs or bot protection, and user handoff. Most browser
+tasks exist because plain HTTP is not enough; a headless browser is more
+likely to trigger bot protection and gives the user no way to observe or step
+in. Visible does not mean pixel-driven: keep operating the page over CDP, and
+the user sees every action in the window.
+
+Use headless mode only for work the user explicitly wants in the background
+and that cannot require interaction or handoff, such as read-only scraping,
+CI, or screenshot/PDF generation, or when no display exists. A headless page
+does not satisfy a request to open or reopen a site in a browser the user can
+see.
 
 When the user asks to review, watch, or take over, leave that browser window
 open after the task. Do not kill or close it before replying.
 
-1. Run `start-letta-desktop` and use its exit status as the result. Warnings
-   from optional services do not mean startup failed when the command exits 0.
-   If it exits nonzero, stop and report that the managed desktop is
-   unavailable. Never create another Xvfb, VNC server, or private display: the
-   Computer viewer only shows the managed desktop.
-2. Load `computer-use`, inspect the managed desktop, and use Cua Driver to
-   operate an existing Chrome window or launch Chrome there. When launching,
-   round-trip Chrome's `launch_path` from `cua-driver call list_apps '{}'
-   instead of rebuilding it; the managed launch path carries required flags.
-   For forms, sign-in, checkout, CAPTCHA, and bot-protected pages, keep using
-   Cua Driver so the interaction remains visible and available for user
-   takeover.
-3. Use CDP only when protocol-level inspection or deterministic automation is
-   needed. Bind the exact visible browser window with Cua Driver, then use its
-   explicit `browser_prepare` flow. Do not pass remote-debugging flags
-   through `launch_app`. Include `--no-sandbox` when running Chrome as
-   root. Do not add `--headless` or override `DISPLAY`.
-4. Use headless mode only for work the user explicitly wants in the background
-   and that cannot require interaction or handoff, such as read-only scraping,
-   CI, or screenshot/PDF generation.
-5. Verify the result through the managed desktop window (Cua Driver window
-   state or screenshot), not only through DOM output or a screenshot from a
-   separate process.
-
-A headless page does not satisfy a request to open or reopen a site in the
-user-visible browser.
-
 ## Workflow
 
 1. Find a Chromium-based browser (below). If none exists, see "No Chrome installed".
-2. In a managed cloud sandbox, follow the visible-browser default above.
-   Otherwise, launch with a dedicated profile and remote debugging. Never
-   attach to the user's normal profile unless explicitly asked.
+2. Launch with a dedicated profile and remote debugging. Never attach to the
+   user's normal profile unless explicitly asked.
 3. Discover targets via `/json/list`; pick the `"page"` target by URL or title.
 4. Connect to its `webSocketDebuggerUrl` and enable only the domains you need
    (usually `Page`, `Runtime`, `DOM`, `Input`; add `Network`, `Log` when debugging).
@@ -124,7 +88,7 @@ Tell the user that browser use requires Chrome or another Chromium-based
 browser and recommend either:
 
 1. Install Chrome on the current computer, then retry the browser task.
-2. Teleport the conversation back to its Cloud sandbox, where the managed
+2. Teleport the conversation back to its Cloud sandbox, where a
    browser is already installed.
 
 Wait for the user to choose. Do not silently replace the browser task with
@@ -132,9 +96,8 @@ plain HTTP or claim browser automation succeeded.
 
 ## Launching
 
-Outside a managed cloud sandbox, use a disposable profile and a fixed port.
-Chrome refuses to run as root without `--no-sandbox`, so add that flag when
-`id -u` is 0:
+Use a disposable profile and a fixed port. Chrome refuses to run as root
+without `--no-sandbox`, so add that flag when `id -u` is 0:
 
 ```bash
 chrome_args=( \
@@ -149,10 +112,8 @@ chrome_args=( \
 "$CHROME" "${chrome_args[@]}" https://example.com
 ```
 
-Outside a managed cloud sandbox, add `--headless=new` only for explicitly
-invisible work or when no display exists. In a managed cloud sandbox, follow
-the visible-browser rule above and never replace its managed display with a
-private one.
+Add `--headless=new` only for explicitly invisible work or when no display
+exists (see "Visible by default" above).
 With `--remote-debugging-port=0`, read the chosen port from
 `<user-data-dir>/DevToolsActivePort`. Launch in the background and poll
 `http://127.0.0.1:9222/json/version` until it responds.

package/skills/messaging-agents/SKILL.md

@@ -66,15 +66,15 @@ Results include `agent_id` for each matching message.
 letta -p --from-agent $LETTA_AGENT_ID --agent <id> "message text"
 ```
 
-When no `--environment` is specified, the target agent will run in the same
-environment as the caller agent.
+When no `--computer` is specified, the target agent will run on the same
+computer as the caller agent.
 
-To route the target agent turn through a specific remote/local environment:
+To route the target agent turn through a specific remote/local computer:
 
 ```bash
 letta -p --from-agent $LETTA_AGENT_ID \
   --agent <id> \
-  --environment <name-or-device-id-or-connection-id> \
+  --computer <name-or-device-id-or-connection-id> \
   "message text"
 ```
 
@@ -83,7 +83,7 @@ letta -p --from-agent $LETTA_AGENT_ID \
 |-----|----------|-------------|
 | `--agent <id>` | Yes | Target agent ID to message |
 | `--from-agent <id>` | Yes | Sender agent ID (injects agent-to-agent system reminder) |
-| `--environment <selector>` | No | Route through an online environment by connection name, device ID, or connection ID |
+| `--computer <selector>` | No | Route through an online computer by connection name, device ID, or connection ID |
 | `"message text"` | Yes | Message body (positional after flags) |
 
 **Example:**
@@ -109,34 +109,34 @@ letta -p --from-agent $LETTA_AGENT_ID \
 letta -p --from-agent $LETTA_AGENT_ID --conversation <id> "message text"
 ```
 
-Add `--environment <selector>` to continue the conversation on a specific environment.
+Add `--computer <selector>` to continue the conversation on a specific computer.
 
-### Discovering Environments
+### Discovering Computers
 
 ```bash
-letta environments list --online-only
+letta computers list --online-only
 # alias:
 letta envs list --online-only
 ```
 
 Use `connectionName`, `deviceId`, or `connectionId` from the JSON output as the
-`--environment` selector. If a name is ambiguous, prefer `deviceId` or
-`connectionId`. In `environments list`, the current local runtime is marked with
+`--computer` selector. If a name is ambiguous, prefer `deviceId` or
+`connectionId`. In `computers list`, the current local runtime is marked with
 `"isCurrent": true`.
 
-To force the target agent onto the current registered Letta Code environment,
-resolve the current environment and pass its `connectionId`:
+To force the target agent onto the current registered Letta Code computer,
+resolve the current computer and pass its `connectionId`:
 
 ```bash
-CURRENT_ENV=$(letta environments current | jq -r .connectionId)
+CURRENT_COMPUTER=$(letta computers current | jq -r .connectionId)
 letta -p --from-agent $LETTA_AGENT_ID \
   --agent agent-abc123 \
-  --environment "$CURRENT_ENV" \
-  "Run on my same machine/environment."
+  --computer "$CURRENT_COMPUTER" \
+  "Run on my same computer."
 ```
 
-Omit `--environment` when you want the target agent to run in the same
-environment as the caller agent.
+Omit `--computer` when you want the target agent to run on the same computer as
+the caller agent.
 
 **Arguments:**
 | Arg | Required | Description |

package/skills/scheduling-tasks/SKILL.md

@@ -21,7 +21,7 @@ This skill lets you create, list, and manage scheduled tasks using the `letta cr
 Pass a flag only when you have a requirement the default can't infer:
 
 - **`--runner cloud`** — the schedule must fire no matter which computers are online; execute in the agent's cloud sandbox.
-- **`--computer <deviceId>`** — the work needs a specific connected computer (its filesystem, services, or credentials). Get the deviceId from `letta environments list`. If that computer is offline at fire time, execution falls back to the cloud sandbox.
+- **`--computer <deviceId>`** — the work needs a specific connected computer (its filesystem, services, or credentials). Get the deviceId from `letta computers list`. If that computer is offline at fire time, execution falls back to the cloud sandbox.
 - **`--runner local`** — the work must only ever run on the current computer, even if that means missing fires while no session is running here.
 
 The CLI reports its placement in the command output. If it warns that the schedule is local (this happens when the cloud scheduler cannot reach the current computer), the schedule only fires while a Letta session is running here — read the warning and decide whether that's acceptable.

package/skills/submitting-feedback/SKILL.md

@@ -1,21 +1,33 @@
 ---
 name: submitting-feedback
-description: Submits user-approved feedback about Letta Code or the current agent to the Letta team. Load when the user is upset, frustrated, dissatisfied, reports poor agent behavior, or asks to send feedback. Works with cloud-hosted and local agents. Ask before submitting unless the user already explicitly requested submission.
+description: Submits user-approved product feedback and bug reports about Letta Code to the Letta team. Load when the user reports a Letta Code bug, requests a product or developer change, or explicitly asks to send feedback. Do not load for corrections to the current agent's behavior or preferences; those are memory edits. Works with cloud-hosted and local agents. Ask before submitting unless the user already explicitly requested submission.
 ---
 
 # Submitting Feedback
 
-When the user appears upset with the agent, acknowledge the problem and ask whether they want you to submit feedback to the Letta team. Do not submit merely because the user expressed frustration.
+Use this skill for product and developer feedback about Letta Code: reproducible bugs, broken features, confusing product behavior, and requested changes to the software or its developer-facing behavior.
+
+Do **not** use this skill when the user corrects how the current agent should behave, communicate, remember, or work with them. Treat that as learning: make the appropriate memory edit so the correction changes the agent's future behavior. A user's frustration with the agent is not by itself product feedback and is not a reason to offer feedback submission.
 
 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/teleporting-between-environments/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: teleporting-between-environments
-description: Moves the current agent conversation to Cloud, Desktop Local, or another Cloud-registered environment while coordinating machine-local files and setup. Use when the user says "let's continue this task on cloud", asks to continue or move work on another connected computer, wants to teleport between environments, or needs to upload or download artifacts before a handoff.
+description: Moves the current agent conversation to Cloud, Desktop Local, or another connected computer while coordinating machine-local files and setup. Use when the user says "let's continue this task on cloud", asks to continue or move work on another connected computer, wants to teleport between computers, or needs to upload or download artifacts before a handoff.
 ---
 
-# Teleporting Between Environments
+# Teleporting Between Computers
 
 Teleport the current agent and conversation without losing conversational memory. Prepare machine-local state first, then let the destination continue the same task.
 
@@ -20,13 +20,13 @@ Teleport the current agent and conversation without losing conversational memory
 letta teleport list
 letta teleport cloud
 letta teleport local
-letta teleport <environment>
+letta teleport <computer>
 ```
 
 - `list`: show accessible online Cloud-registered targets.
 - `cloud`: create or resume this conversation’s managed Cloud sandbox.
-- `local`: target the one online Letta Desktop environment. Desktop Remote Access must be enabled. If several Desktop environments are online, use `list` and target one explicitly.
-- `<environment>`: target a listed remote environment by its friendly selector.
+- `local`: target the one online Letta Desktop computer. Desktop Remote Access must be enabled. If several Desktop computers are online, use `list` and target one explicitly.
+- `<computer>`: target a listed remote computer by its friendly selector.
 
 Do not run or recommend `letta teleport back`; return to Desktop with `local`.
 
@@ -79,21 +79,21 @@ If the command reports an offline, stale, unsupported, same-source, or startup e
 
 ### Return to Desktop Local
 
-1. Retain the next local action and any setup the Desktop environment needs.
-2. Confirm Desktop is open with Remote Access enabled. If more than one Desktop environment is online, use `letta teleport list` and choose one explicitly.
+1. Retain the next local action and any setup the Desktop computer needs.
+2. Confirm Desktop is open with Remote Access enabled. If more than one Desktop computer is online, use `letta teleport list` and choose one explicitly.
 3. As the final action, run:
 
    ```bash
    letta teleport local
    ```
 
-### Run a separate headless turn on an environment
+### Run a separate headless turn on a computer
 
-Use `--environment` when a separate headless invocation, rather than the current conversation handoff, should execute on Cloud or another online environment:
+Use `--computer` when a separate headless invocation, rather than the current conversation handoff, should execute on Cloud or another online computer:
 
 ```bash
-letta -p --conversation <id> --environment cloud "<prompt>"
-letta -p --conversation <id> --environment <name|device-id|connection-id> "<prompt>"
+letta -p --conversation <id> --computer cloud "<prompt>"
+letta -p --conversation <id> --computer <name|device-id|connection-id> "<prompt>"
 ```
 
 This routes that headless message only. Use `letta teleport ...` to move the currently executing conversation.
@@ -110,5 +110,5 @@ This routes that headless message only. Use `letta teleport ...` to move the cur
 3. As the final action, run:
 
    ```bash
-   letta teleport <environment>
+   letta teleport <computer>
    ```

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.