@letta-ai/letta-code 0.32.2 → 0.32.3

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

@@ -0,0 +1,88 @@
+---
+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.
+
+## 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/teleporting-between-environments/SKILL.md

@@ -1,114 +0,0 @@
----
-name: teleporting-between-environments
-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 Computers
-
-Teleport the current agent and conversation without losing conversational memory. Prepare machine-local state first, then let the destination continue the same task.
-
-## Mental model
-
-- **Memory follows the agent; filesystem access does not.** Files, working directories, credentials, running processes, and local services belong to the computer currently executing the conversation.
-- Upload and download paths are relative to the current computer. Cloud cannot read a laptop path until the conversation teleports to that laptop.
-- The conversation’s managed Cloud sandbox remains alive while the conversation runs elsewhere.
-- Filesystem paths and cwd do not transfer between computers. Re-establish the destination’s repository, working directory, dependencies, credentials, and services after arrival.
-
-## Commands
-
-```bash
-letta teleport list
-letta teleport cloud
-letta teleport local
-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 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`.
-
-Transfer files with the existing sandbox commands:
-
-```bash
-letta sandbox upload <local-path>
-letta sandbox download <sandbox-path> [--to <local-path>]
-```
-
-Do not invent `letta teleport push`, `pull`, or remote file-listing commands. No sandbox ID or wake command is needed.
-
-## Prepare the handoff
-
-Before teleporting:
-
-1. Identify the target and every file, repository state, credential, service, or setup step the task needs there.
-2. Finish work that requires the current computer. Verify relevant files exist before transferring them.
-3. Upload current-computer artifacts needed in Cloud and retain the returned `/root/downloads/...` paths in context.
-4. Retain enough context to recreate destination-local setup, including the repository, branch or revision, working directory, dependency commands, and next action.
-5. Run teleport only after all source-side preparation is complete.
-
-## Teleport is the final action
-
-Run the teleport command as the only command in the final Bash tool call. Do not chain later commands, poll the teleport operation, or invoke another source-side tool after it.
-
-The CLI intentionally returns after the server accepts the handoff. Once the Bash result is persisted, the source yields at a clean turn or tool boundary and the destination resumes with no synthetic user message.
-
-If the command reports an offline, stale, unsupported, same-source, or startup error, the conversation remains on the source. Surface the concrete error, correct it if possible, and retry only after the target is available.
-
-## Common workflows
-
-### Continue local work in Cloud
-
-1. Inspect the local task state and identify local-only artifacts or setup.
-2. Upload each artifact Cloud needs:
-
-   ```bash
-   letta sandbox upload <local-path>
-   ```
-
-3. Retain each returned sandbox path.
-4. As the final action, run:
-
-   ```bash
-   letta teleport cloud
-   ```
-
-5. After continuation in Cloud, establish the Cloud-local cwd and repository setup before using the uploaded paths.
-
-### Return to Desktop Local
-
-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 a computer
-
-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> --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.
-
-### Continue on another connected computer
-
-1. Discover available targets if needed:
-
-   ```bash
-   letta teleport list
-   ```
-
-2. Prepare or upload everything the current computer owns.
-3. As the final action, run:
-
-   ```bash
-   letta teleport <computer>
-   ```