@letta-ai/letta-code 0.32.2 → 0.32.4

package/skills/messaging-agents/SKILL.md

@@ -1,201 +1,226 @@
 ---
 name: messaging-agents
-description: Send messages to other agents on your server. Use when you need to communicate with, query, or delegate tasks to another agent.
+description: Send a message to another Letta agent, continue a thread with one, check on it, or reply to a message another agent sent you. Use when you need to ask, inform, or coordinate with another agent, or when a message from another agent arrives.
 ---
 
 # Messaging Agents
 
-This skill enables you to send messages to other agents on the same Letta server using the thread-safe conversations API.
+## What you are addressing
+
+An **agent** is a persistent identity: its memory and configuration are shared
+by all of its conversations. A **conversation** is one message thread on an
+agent. Address a conversation ID to continue a thread; address an agent ID to
+open a new thread with that agent. When your send identifies you as the sender,
+a new thread is created hidden so agent-to-agent traffic does not clutter the
+recipient's conversation list.
+
+## Two backends
+
+Letta Code keeps agent state on one of two backends. The same CLI addresses
+agents on either; what differs is what happens after you send.
+
+**Cloud backend** (api.letta.com). Agent state lives in Cloud. Cloud can deliver
+messages to a *computer*: a machine running Letta Code connected to Cloud,
+or a Cloud sandbox. Because state and execution are
+separate, Cloud tracks which computers are online and where each conversation
+is active. That is why these exist only on this backend:
+
+- delivering your message to the harness already running the recipient's
+  conversation, or to its saved destination (a computer or Cloud sandbox)
+  when none is active;
+- a `computer` selector on sends and on the Agent tool;
+- teleporting a conversation (`letta teleport <computer>`): the same thread,
+  with its history and memory, continues on a different computer. Files and
+  working directories do not move with it.
+
+**Local backend.** Agent state lives in a store on this machine. There is no
+computer concept, so no `computer` selector and no teleport, and no Cloud
+service to deliver on your behalf: a send runs the recipient's turn inside the
+`letta -p` process you launched. Agent IDs on this backend start with
+`agent-local-`.
+
+"Local backend" describes where state is stored. It says nothing about which
+machine a Cloud-backed agent is executing on, and it is unrelated to subagents
+you launch with the Agent tool.
+
+## How a send reaches the recipient
+
+For the Cloud CLI sends below, `letta -p` hands the message to Cloud for
+delivery when you pass `--conversation`, `--from-agent`, `--no-wait`, or
+`--computer`. These commands leave the recipient's execution settings unchanged.
+`SendAgentMessage` uses the same Cloud delivery endpoint.
+
+With only `--agent`, the CLI chooses the launch settings and normally creates a
+new conversation. It runs the turn in its own process or reuses an inherited
+Cloud listener. The listener path first applies those settings to the
+conversation, then submits its input through the same Cloud delivery endpoint.
+Supported local-backend CLI sends run the turn in the launched process.
+
+`--no-wait` is one of the flags that selects Cloud delivery. On that path,
+waiting and non-waiting sends use the same delivery mechanism, but differ in
+how you receive the answer and what reply instructions the recipient gets.
+
+The recipient learns who is asking only when the send identifies a sender:
+`--from-agent`, or for the Cloud messaging recipes below, the caller IDs from
+the agent's shell environment (`AGENT_ID`/`LETTA_AGENT_ID` and
+`CONVERSATION_ID`/`LETTA_CONVERSATION_ID`). `SendAgentMessage`
+always identifies you and your conversation. An identified send attaches a
+system reminder telling the recipient how to get its answer back to you. A
+`letta -p` with neither carries no sender or reply instructions; the recipient
+receives your text as user input, plus whatever context its harness normally
+adds.
+
+An explicit `--from-agent` different from the agent identified by your
+environment does not inherit the current conversation as its return address.
+
+## Waiting or not
+
+- **Waiting send** (`letta -p` without `--no-wait`). The process normally returns
+  the recipient's final message, in `result` with JSON output. When a sender is
+  identified, the recipient is told to put its answer in that message. Works
+  on either backend.
+- **Non-waiting send** (`SendAgentMessage`, or `letta -p --no-wait`). Returns
+  a receipt once Cloud accepts the message. Ordinary assistant output is not
+  forwarded. When a sender is identified, the reminder says so and, if a return
+  conversation is supplied, asks the recipient to send an explicit reply there.
+  That explicit reply becomes a new message in your conversation. Cloud backend
+  only; acceptance does not guarantee a reply.
+
+A waiting send occupies the CLI process, not necessarily you. Run it in the
+background (your shell tool may already do this for long-running commands) and
+read its output when it finishes. That keeps you working, but it does not
+change the recipient's instructions: the answer still arrives as process
+output, not as a message to your conversation.
+
+For a managed child task with a completion notification, use the Agent tool on
+either backend. `SendAgentMessage` only sends input; it creates no task.
+
+## Send and keep working (Cloud backend)
 
-## When to Use This Skill
-
-- You need to ask another agent a question
-- You want to query an agent that has specialized knowledge
-- You need information that another agent has in their memory
-- You want to coordinate with another agent on a task
-
-## What the Target Agent Can and Cannot Do
-
-**The target agent CANNOT:**
-- Access your local environment (read/write files in your codebase)
-- Execute shell commands on your machine
-- Use your tools (Bash, Read, Write, Edit, etc.)
-
-**The target agent CAN:**
-- Use their own tools (whatever they have configured)
-- Access their own memory blocks
-- Make API calls if they have web/API tools
-- Search the web if they have web search tools
-- Respond with information from their knowledge/memory
-
-**Important:** This skill is for *communication* with other agents, not *delegation* of local work. The target agent runs in their own environment and cannot interact with your codebase.
-
-**Need local access?** If you need the target agent to access your local environment (read/write files, run commands), use the Agent tool instead to deploy them as a subagent:
 ```typescript
-Agent({
-  agent_id: "agent-xxx",            // Deploy this existing agent
-  subagent_type: "general-purpose", // read-write access to your local tools
-  prompt: "Look at the code in src/ and tell me about the architecture"
-})
+SendAgentMessage({ conversation_id: "conv-…", message: "…" })   // continue a thread
+SendAgentMessage({ agent_id: "agent-…", message: "…" })         // open a new hidden thread
+SendAgentMessage({ agent_id: "agent-…", conversation_id: "default", message: "…" })  // the agent's default thread
 ```
-This gives the agent access to your codebase while running as a subagent.
-
-## Finding an Agent to Message
 
-If you don't have a specific agent ID, use these skills to find one:
+Success means Cloud accepted the message (`status: "queued"`), not that the
+recipient has read it. Keep working; a reply sent to your return address
+arrives in your conversation.
+Omit `computer`: the conversation continues wherever it is active, and asking
+for a different computer is rejected rather than moving it.
 
-### By Name or Tags
-Load the `finding-agents` skill to search for agents:
-```bash
-letta agents list --query "agent-name"
-letta agents list --tags "origin:letta-code"
-```
+The CLI form behaves the same when run from your agent's environment, which
+supplies the return address; use it from scripts or when the tool is absent:
 
-### By Topic They Discussed
-Search messages across all agents to find which agent worked on something:
 ```bash
-letta messages search --query "topic" --all-agents
+letta -p --conversation <conversation-id> --no-wait --output-format json "message"
+letta -p --agent <agent-id> --no-wait --output-format json "message"
 ```
-Results include `agent_id` for each matching message.
 
-## CLI Usage (agent-to-agent)
-
-### Starting a New Conversation
+## Send and wait (either backend)
 
 ```bash
-letta -p --from-agent $LETTA_AGENT_ID --agent <id> "message text"
+letta -p --from-agent $LETTA_AGENT_ID --agent <agent-id> --output-format json "message"
+letta -p --from-agent $LETTA_AGENT_ID --conversation <conversation-id> --output-format json "follow-up"
 ```
 
-When no `--computer` is specified, the target agent will run on the same
-computer as the caller agent.
+`result` normally holds the recipient's final message; `conversation_id` is
+the thread to continue. `--from-agent` names you and must be an agent on the
+same backend as the recipient.
 
-To route the target agent turn through a specific remote/local computer:
+If your agent ID starts with `agent-local-`, add `--backend local` so the
+command uses the local store: `letta --backend local -p …`. The flag applies to
+that command only.
 
-```bash
-letta -p --from-agent $LETTA_AGENT_ID \
-  --agent <id> \
-  --computer <name-or-device-id-or-connection-id> \
-  "message text"
-```
+For these Cloud messaging commands, stopping the wait does not cancel accepted
+work on the recipient's computer. On the local backend the recipient's turn
+runs inside the process you launched, so
+`--tools`, `--permission-mode`, and the working directory you give it apply to
+that turn.
 
-Use `--computer cloud` to route through the target agent's cloud sandbox:
+## Replying to another agent
 
-```bash
-letta -p --from-agent $LETTA_AGENT_ID \
-  --agent <id> \
-  --computer cloud \
-  "message text"
-```
+When another agent identifies itself, its message arrives with a system
+reminder naming its agent ID and, when it had one, its conversation ID.
 
-**Arguments:**
-| Arg | Required | Description |
-|-----|----------|-------------|
-| `--agent <id>` | Yes | Target agent ID to message |
-| `--from-agent <id>` | Yes | Sender agent ID (injects agent-to-agent system reminder) |
-| `--computer <selector>` | No | Route through `cloud` (target agent's cloud sandbox) or an online computer by connection name, device ID, or connection ID |
-| `"message text"` | Yes | Message body (positional after flags) |
+- If the reminder says the sender will only see your final message: answer in
+  your response. Nothing more is needed.
+- If the reminder asks for an explicit reply: use its return address with
+  `SendAgentMessage({ agent_id, conversation_id, message })`, or
+  `letta -p --agent <sender-agent-id> --conversation <sender-conversation-id> --no-wait "reply"`.
+  Your ordinary output is not forwarded to the sender.
+- If it says no return conversation was supplied: your output is not forwarded
+  and there is no thread to reply into. Answer as you normally would.
 
-**Example:**
-```bash
-letta -p --from-agent $LETTA_AGENT_ID \
-  --agent agent-abc123 \
-  "What do you know about the authentication system?"
-```
+A message without such a reminder carries no sender or reply instructions;
+respond to it as you would to any input.
 
-**Response (JSON format with `--output json`):**
-```json
-{
-  "type": "result",
-  "subtype": "success",
-  "is_error": false,
-  "result": "The authentication system uses JWT tokens...",
-  "agent_id": "agent-abc123",
-  "conversation_id": "conversation-xyz789",
-  "environment": { "source": "same-environment" },
-  "usage": { "prompt_tokens": 120, "completion_tokens": 80, "total_tokens": 200, "step_count": 1 }
-}
-```
+## Checking on a conversation
 
-### Continuing a Conversation
+Recent messages are the quick progress check on either backend. This command
+requests recent messages and prints the returned messages oldest to newest (add
+`--backend local` in the same cases as for sends):
 
 ```bash
-letta -p --from-agent $LETTA_AGENT_ID --conversation <id> "message text"
+letta messages list --conversation <conversation-id> --limit 10
 ```
 
-Add `--computer <selector>` to continue the conversation on a specific computer.
+`letta messages status --conversation <id>` (Cloud only) reports whether the
+conversation is currently running. When `latest_super_run` is present, compare
+its `id` with the `super_run_id` on your receipt; a different ID belongs to a
+different send. Read the messages to see what was processed. Non-waiting
+receipts include ready-to-run `status_command` and `messages_command` values for the thread
+they went to. `letta messages transcript --conversation <id>` exports the
+thread; check `truncated` before treating it as complete.
+`letta messages --help` lists the options.
 
-### Discovering Computers
+## Finding an agent
 
 ```bash
-letta computers list --online-only
-# alias:
-letta envs list --online-only
+letta agents list --query "name"
+letta messages search --query "topic" --all-agents   # discovery; results include agent_id
 ```
 
-Use `connectionName`, `deviceId`, or `connectionId` from the JSON output as the
-`--computer` selector. If a name is ambiguous, prefer `deviceId` or
-`connectionId`. In `computers list`, the current local runtime is marked with
-`"isCurrent": true`.
+Load the `finding-agents` skill for more search options.
 
-To force the target agent onto the current registered Letta Code computer,
-resolve the current computer and pass its `connectionId`:
+## Choosing a computer (Cloud backend)
 
-```bash
-CURRENT_COMPUTER=$(letta computers current | jq -r .connectionId)
-letta -p --from-agent $LETTA_AGENT_ID \
-  --agent agent-abc123 \
-  --computer "$CURRENT_COMPUTER" \
-  "Run on my same computer."
-```
-
-Omit `--computer` when you want the target agent to run on the same computer as
-the caller agent.
-
-**Arguments:**
-| Arg | Required | Description |
-|-----|----------|-------------|
-| `--conversation <id>` | Yes | Existing conversation ID |
-| `--from-agent <id>` | Yes | Sender agent ID (injects agent-to-agent system reminder) |
-| `"message text"` | Yes | Follow-up message (positional after flags) |
+Only when a specific machine is required:
 
-**Example:**
 ```bash
-letta -p --from-agent $LETTA_AGENT_ID \
-  --conversation conversation-xyz789 \
-  "Can you explain more about the token refresh flow?"
-```
-
-## Understanding the Response
-
-- 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 `letta messages list --agent <id>` targeting the other agent
-
-## How It Works
-
-When you send a message, the target agent receives it with a system reminder:
-```
-<system-reminder>
-This message is from "YourAgentName" (agent ID: agent-xxx), an agent currently running inside the Letta Code CLI (docs.letta.com/letta-code).
-The sender will only see the final message you generate (not tool calls or reasoning).
-If you need to share detailed information, include it in your response text.
-</system-reminder>
+letta computers list --online-only        # connectionName and deviceId
+letta -p --agent <agent-id> --computer <name-or-device-id> --no-wait "message"
+letta -p --agent <agent-id> --computer cloud --no-wait "message"   # its Cloud sandbox
 ```
 
-This helps the target agent understand the context and format their response appropriately.
-
-## Hidden Conversations
-
-Agent-to-agent conversations (started via `--from-agent`) are created **hidden** on the target agent. They don't appear in the target's default conversation list in the ADE, so automated inter-agent chatter doesn't clutter the UI.
-
-To inspect them:
-- List hidden conversations via the API with `archive_status=archived` (or `all`)
-- Pull the transcript directly with `letta messages transcript --conversation <id>`
-- The `conversation_id` returned when you sent the message is the handle you need
-
-Continuing a hidden conversation with `--conversation <id>` keeps it hidden — only archive status is affected, messaging still works normally.
-
-## Related Skills
-
-- **finding-agents**: Find agents by name, tags, or fuzzy search
+If the conversation is active on another computer the send is rejected; to
+move a conversation, teleport it (see the `working-across-computers` skill).
+An offline saved computer does not trigger a Cloud-sandbox fallback.
+`letta computers --help` covers the selectors.
+
+## Gotchas
+
+- `SendAgentMessage`, `--no-wait`, `--computer`, and `messages status` fail on
+  the local backend even when they are offered. Check your agent ID prefix.
+- For Cloud coordination, do not rely on `--agent` alone to select message
+  delivery. Add `--from-agent $LETTA_AGENT_ID` to deliver and identify yourself;
+  pass `--conversation <id>` to reach an existing thread.
+- The Cloud messaging recipes above reject execution flags (`--tools`,
+  `--permission-mode`, `--model`, `--system`, and similar); the recipient keeps
+  its own configuration. Those flags configure a launch when using the
+  retained `--agent`-only path or local-backend execution.
+- `--conversation default` needs `--agent`; `default` is scoped to an agent.
+- A receipt means accepted, not delivered. If a send's outcome is unknown
+  (`acceptance_unknown`, a timed-out wait), read the thread before resending.
+
+## Related
+
+- `letta --help` and each subcommand's `--help` are the reference for flags;
+  this skill explains the concepts and the common recipes.
+- `finding-agents`: locate agents by name, tags, or search.
+- `working-across-computers`: teleporting and moving files between computers.
+- `dispatching-coding-agents`: driving Claude Code or Codex through their
+  CLIs, including background execution and collecting results. The same
+  pattern applies to a Letta Code instance on another backend: run the
+  waiting-send commands above inside it with a `--from-agent` that exists
+  there.

package/skills/working-across-computers/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: working-across-computers
+description: Guides work across Cloud, local, and other available computers, including teleporting the current conversation, orchestrating remote subagents, and uploading or downloading files to Cloud sandboxes. Use when moving between computers (e.g. teleporting between cloud/local) or coordinating work and files across them.
+---
+
+# Working Across Computers
+
+## Choose where to work
+
+- When running in Cloud, prefer staying there and delegating local work to subagents on the relevant computer.
+- If the user explicitly asks to move this conversation locally or elsewhere, teleport it.
+- Moving a conversation that started locally into Cloud is a normal workflow: transfer needed files first, then teleport.
+
+| Intent | Mechanism |
+|---|---|
+| Run work elsewhere while staying here | `Agent` |
+| Bring a remote file into a Cloud conversation | Remote agent: `sandbox upload` |
+| Put a Cloud file onto another computer | Remote agent: `sandbox download` |
+| Continue this conversation elsewhere | `teleport` |
+
+Conversation history and agent memory follow the conversation. Files, working directories, installed tools, credentials, and running services belong to each computer; teleporting does not copy the workspace.
+
+For remote subagents, set `computer` and pass source paths and destination conversation IDs explicitly. Use the `Agent` tool definition for invocation and resume options.
+
+If the user wants to connect a new computer, `letta teleport list` has no suitable target, or the requested local machine is missing or unreachable, read [Connect a computer for remote access](references/connect-a-computer-for-remote-access.md).
+
+## Move this conversation
+
+**Run the teleport handoff alone as the final tool call.** After success, do not poll or run more source-side tools; the same conversation resumes at the destination automatically. Set the working directory and check required setup there. If teleport fails, stay on the source and resolve the error before retrying. The Cloud sandbox remains available while you work elsewhere.
+
+### Local → Cloud
+
+Upload any files needed in Cloud:
+
+```bash
+letta sandbox upload <local-path>
+```
+
+Keep the returned paths, repository/branch, and next action in context, then create or resume this conversation's Cloud sandbox:
+
+```bash
+letta teleport cloud
+```
+
+### Cloud → other computers
+
+List available computers:
+
+```bash
+letta teleport list
+```
+
+Have a remote subagent download any needed files and verify completion before moving. Use a returned computer name, device ID, or connection ID:
+
+```bash
+letta teleport <computer>
+```
+
+With exactly one online Desktop, open with Remote Access enabled, you can use the shortcut:
+
+```bash
+letta teleport local
+```
+
+## Transfer files to or from Cloud
+
+Run upload where the local file exists; run download where the local copy should be saved.
+
+```bash
+# Use the executing conversation's Cloud sandbox
+letta sandbox upload <local-path>
+letta sandbox download <sandbox-path> --to <local-path>
+
+# Explicit Cloud conversation (sandboxes are per-conversation)
+letta sandbox upload <local-path> --conversation <destination-conversation-id>
+letta sandbox download <sandbox-path> \
+  --conversation <source-conversation-id> --to <local-path>
+
+# An agent's main/default conversation
+letta sandbox upload <local-path> --agent <agent-id>
+letta sandbox download <sandbox-path> --agent <agent-id> --to <local-path>
+```
+
+- `--agent` alone selects that agent's main/default conversation. Concrete `--conversation` IDs resolve their owning agent.
+- Target flags override the executing session without changing its identity. Do not replace the subagent's identity environment variables with the parent's.
+- The executing computer's credentials must authorize access to the target.
+- Commands return JSON. Use the exact upload path returned; never reconstruct it from the filename.
+- Download sources must be under `/root/downloads`; `--to` selects the destination path on the receiving computer. Without `--to`, download saves under the source file's basename.
+- Transfer files directly, not as base64 or file contents through model messages. Return the path and destination IDs; verify received contents or checksums.
+- These commands transfer files to/from Cloud sandboxes, not arbitrary remote filesystems. No sandbox ID or separate wake command is needed.

package/skills/working-across-computers/references/connect-a-computer-for-remote-access.md

@@ -0,0 +1,59 @@
+# Connect a computer for remote access
+
+Use this guide when the user is connecting a computer for the first time, no suitable computers are listed, or their local machine cannot be reached.
+
+Explain that the user must complete setup **on the computer they want to connect**, signed into the same Letta account they use on chat.letta.com. Remote access lets agents run commands and access files on that machine, subject to tool approvals. Local-only / “Skip login” mode is not sufficient.
+
+Recommend Desktop for a personal computer; offer the CLI for a terminal-only machine or VM. Give the relevant steps below rather than only saying the computer is unavailable. Do not run registration commands in the Cloud sandbox as a substitute for connecting the user's machine.
+
+## Option 1: Letta Desktop
+
+Ask the user to:
+
+1. [Download and install Letta Desktop](https://docs.letta.com/quickstart/) for their operating system.
+2. Open the app and sign in to their Letta account.
+3. Open **Preferences → General** and enable **Allow remote access**.
+4. Set the computer's name in the field beneath the toggle.
+5. Keep Desktop running and the computer awake and connected to the internet.
+6. Open chat.letta.com and select the named computer in the computer picker to run a conversation there.
+
+Show the bundled screenshot when explaining the toggle and name field:
+
+![Desktop Preferences showing Allow remote access and the computer-name field](../assets/allow-remote-access-from-desktop.png)
+
+Resolve `assets/allow-remote-access-from-desktop.png` relative to this skill's directory. In chat or Desktop, use the resolved absolute local path in the Markdown image you send, not this reference file's relative path. The screenshot is from the original teleportation skill; surrounding settings may differ in newer Desktop versions.
+
+## Option 2: CLI server
+
+Ask the user to install [Node.js 22.19 or newer](https://nodejs.org/en/download), then run these commands in a terminal **on the target computer**:
+
+```bash
+npm install -g @letta-ai/letta-code
+letta server --computer-name "work-laptop"
+```
+
+If not already authenticated, the server prints a login URL. Ask the user to open it in a browser and authorize with their Letta account. Do not ask them to paste credentials into chat.
+
+Keep the server process running and the computer awake and online. The named computer will appear in the picker on chat.letta.com or Desktop. For an always-on VM, use a service manager and persist the CLI's authentication state across restarts.
+
+No inbound ports, public IP, or reverse proxy are required: the server connects outward to Letta Cloud. Use plain `letta server`, not `letta server --listen`; `--listen` starts the separate App Server interface for direct application connections.
+
+## Verify access or reconnect an existing computer
+
+After the user completes setup, run:
+
+```bash
+letta teleport list
+```
+
+Use the returned computer name or ID for remote delegation or teleportation. Do not claim access is ready until the desired computer is listed. Keep the current conversation in place unless the user wants to move it; remote subagents can work there while the parent stays in Cloud.
+
+If the computer is still missing or unreachable, ask the user to check that:
+
+- The computer is awake and connected to the internet.
+- Desktop is open with **Allow remote access** enabled, or `letta server` is still running.
+- The app or CLI is signed into the same Letta account as the web session.
+
+Re-list after the user changes the relevant state, rather than repeatedly retrying an unavailable target. If it is listed but an operation still fails, use the concrete error to diagnose authentication, connectivity, or version compatibility; do not assume it needs reinstalling or bypass access controls.
+
+For current installation details, consult the [machine setup docs](https://docs.letta.com/platform/computers/byom/). Verify CLI flags with `letta server --help` if docs and the installed version disagree.