@letta-ai/letta-code 0.30.19 → 0.30.21

package/package.json

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

package/scripts/isolated-unit-tests.json

@@ -165,6 +165,11 @@
       "timeoutMs": 30000,
       "reason": "Exercises real WebSockets while mutating listener, settings, HOME, and process environment state."
     },
+    {
+      "path": "src/websocket/listener/auth-lifecycle-approval-reconnect.test.ts",
+      "timeoutMs": 30000,
+      "reason": "Exercises real WebSockets while mutating listener, settings, HOME, and process environment state."
+    },
     {
       "path": "src/websocket/listener/control-inputs.test.ts",
       "timeoutMs": 15000,

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": 5253,
+  "src/headless.ts": 5054,
   "src/hooks/integration.test.ts": 1147,
-  "src/index.ts": 2773,
+  "src/index.ts": 2775,
   "src/mods/learning-harness.ts": 2434,
   "src/mods/mod-engine.test.ts": 2153,
   "src/mods/mod-engine.ts": 1838,
@@ -44,7 +44,7 @@
   "src/websocket/listener/commands/memory.ts": 1114,
   "src/websocket/listener/file-commands.ts": 1053,
   "src/websocket/listener/lifecycle.ts": 1051,
-  "src/websocket/listener/protocol-inbound.ts": 2264,
+  "src/websocket/listener/protocol-inbound.ts": 2244,
   "src/websocket/listener/protocol-outbound.ts": 1072,
-  "src/websocket/listener/turn.ts": 1010
+  "src/websocket/listener/turn.ts": 1009
 }

package/skills/creating-mods/references/tools.md

@@ -22,6 +22,7 @@ For tools that are part of a larger mod with commands, UI, local state, or event
 - Use `ctx.cwd` as the invocation workspace.
 - Use the dynamic context passed to `run(ctx)` (`ctx.agent`, `ctx.model`, `ctx.toolset`, `ctx.permissionMode`) instead of reading global app context.
 - Use `await ctx.conversation.getHistory()` when a tool needs recent conversation context. It returns the most recent messages in chronological order by default.
+- Use `await ctx.conversation.updateTitle(title)` to persist a conversation title and refresh active local UI consumers when the host supports it.
 - Respect `ctx.signal` for long-running work when practical.
 - Tools should return information for the model to use; they should not start hidden model runs.
 

package/skills/scheduling-tasks/SKILL.md

@@ -31,7 +31,7 @@ The CLI reports its placement in the command output. If it warns that the schedu
 Two patterns cover most schedules:
 
 - **Fast follow-ups** ("check on the PR in 5m"): the default is right — same computer as the active conversation. If the session dies before it fires, the follow-up usually died with the task anyway.
-- **Recurring jobs** ("every Monday 11am, start the lunch order"): prefer durability. If the CLI warned that a recurring schedule is local, that's usually wrong for the user's intent — recreate it with `--runner cloud`, or `--computer` if the job needs a specific always-on computer. Also consider whether the job should post into a dedicated conversation rather than this one (continuity in one thread vs a fresh context per run).
+- **Recurring jobs** ("every Monday 11am, start the lunch order"): prefer durability. If the CLI warned that a recurring schedule is local, that's usually wrong for the user's intent — recreate it with `--runner cloud`, or `--computer` if the job needs a specific always-on computer. A fresh conversation per run is the default; pass a conversation explicitly when the job needs continuity in one thread.
 
 ## CLI Usage
 
@@ -64,7 +64,7 @@ letta cron add --name <short-name> --description <text> --prompt <text> <schedul
 | Flag | Description |
 |------|-------------|
 | `--agent <id>` | Agent ID (defaults to `LETTA_AGENT_ID` from the current shell/session) |
-| `--conversation <id>` | Conversation ID (defaults to `LETTA_CONVERSATION_ID` from the current shell/session, otherwise `"default"`) |
+| `--conversation <id>` | Conversation target: omit or pass `new` for a fresh conversation per fire; pass `self` for the current conversation; pass `default` for the agent default; or pass a concrete ID |
 | `--runner <runner>` | `cloud` or `local` — normally omit; see "Where Schedules Run" above |
 | `--computer <id>` | Execute on a specific connected computer — normally omit |
 | `--once` | Mark `--at` as one-shot (already the default for `--at`) |
@@ -97,7 +97,7 @@ For local run history, `--run-id <id>` selects one run. Cloud history ignores th
 
 If exact routing matters, pass both `--agent` and `--conversation` explicitly.
 
-`letta cron add` will otherwise fall back to `LETTA_AGENT_ID` and `LETTA_CONVERSATION_ID` from the current shell/session. Those values may be correct for the current chat, but they can also be inherited from surrounding tooling, another conversation, or an older shell.
+`letta cron add` falls back to `LETTA_AGENT_ID` for the agent. An omitted `--conversation` means `"new"`, so every fire gets a fresh conversation. Pass `--conversation self` to capture the current `LETTA_CONVERSATION_ID`, `--conversation default` for the agent default, or a concrete conversation ID.
 
 Safest pattern:
 
@@ -107,14 +107,14 @@ letta cron add \
   --description "Daily email summary in this conversation" \
   --prompt "Check the user's email and post a summary here." \
   --cron "0 10 * * *" \
-  --agent "$AGENT_ID" \
-  --conversation "$CONVERSATION_ID"
+  --agent "$LETTA_AGENT_ID" \
+  --conversation self
 ```
 
 Then verify the binding explicitly:
 
 ```bash
-letta cron list --agent "$AGENT_ID" --conversation "$CONVERSATION_ID"
+letta cron list --agent "$LETTA_AGENT_ID" --conversation self
 ```
 
 ### Deleting or Replacing Tasks
@@ -156,7 +156,9 @@ letta cron add \
   --name "deploy-check" \
   --description "One-time check on deployment status" \
   --prompt "Check the deployment status and report the result here." \
-  --at "in 30m"
+  --at "in 30m" \
+  --agent "$LETTA_AGENT_ID" \
+  --conversation self
 ```
 
 ### "Every weekday at 5pm, remind me to submit my timesheet" (user in UTC−7)
@@ -203,7 +205,7 @@ Include context about what the user originally asked for, so you can give a help
 - **Minimum granularity**: 1 minute. Intervals under 60 seconds are rounded up.
 - **Recurring tasks**: No longer auto-expire. They remain active until explicitly cancelled.
 - **One-shot cleanup (local runner)**: One-shot local tasks are garbage-collected 24 hours after firing.
-- **Default binding precedence**: `letta cron add` uses `--agent` / `--conversation` first, then falls back to `LETTA_AGENT_ID` / `LETTA_CONVERSATION_ID`, then finally uses `"default"` for the conversation if no env var is present.
+- **Default binding**: `letta cron add` uses `--agent` first, then `LETTA_AGENT_ID`. Omit `--conversation` for a fresh conversation per fire; use `--conversation self` to capture `LETTA_CONVERSATION_ID` explicitly.
 - **Local scheduler requirement**: Local schedules only fire while a Letta session is running on their computer; fires while no session runs are marked as missed. Cloud schedules fire from the cloud regardless.
 - **`--at` for specific times**: `--at "3:00pm"` schedules a one-shot. If the time has already passed today, it schedules for tomorrow.
 - **Cloud schedule creation failures are loud**: if creating a cloud schedule fails, no schedule is created — a failed create never silently becomes a local schedule. (The local placement for computers the cloud scheduler can't reach is decided before creation and reported in the output.)

package/skills/teleporting-between-environments/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: teleporting-between-environments
+description: Moves the current agent conversation to Cloud or a Cloud-registered remote 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.
+---
+
+# Teleporting Between Environments
+
+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 <environment>
+```
+
+- `list`: show accessible online remote targets. Desktop Local is excluded.
+- `cloud`: create or resume this conversation’s managed Cloud sandbox.
+- `<environment>`: target a listed remote environment by its friendly selector.
+
+Teleport cannot target Desktop Local yet. Once the conversation runs in Cloud,
+the agent cannot programmatically return to Desktop Local. The user can still
+switch manually with Desktop's environment picker. Do not run or recommend
+`letta teleport back`.
+
+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
+
+The agent cannot initiate this transition. Retain the next local action and ask
+the user to select Local from Desktop's environment picker. After continuation
+locally, resume the task from the retained context.
+
+### 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 <environment>
+   ```

package/dist/types/cli/helpers/session-context.d.ts

@@ -1,25 +0,0 @@
-import type { SessionContextReason } from "../../reminders/state";
-import type { ShellContext } from "../../utils/shell-context";
-export type SessionContextSource = "interactive-cli" | "headless" | "listen";
-/**
- * Get the current local time in a human-readable format
- */
-export declare function getLocalTime(): string;
-/**
- * Get device type based on platform
- */
-export declare function getDeviceType(): string;
-export interface BuildSessionContextOptions {
-    cwd?: string;
-    source?: SessionContextSource;
-    reason?: SessionContextReason;
-    shellContext?: ShellContext;
-}
-export declare function buildWindowsShellNotes(shellContext?: ShellContext): string;
-/**
- * Build the session context system reminder (device/environment info only).
- * Agent metadata is handled separately by buildAgentMetadata().
- * Returns empty string on any failure (graceful degradation).
- */
-export declare function buildSessionContext(options?: BuildSessionContextOptions): string;
-//# sourceMappingURL=session-context.d.ts.map

package/dist/types/cli/helpers/session-context.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"session-context.d.ts","sourceRoot":"","sources":["../../../../src/cli/helpers/session-context.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAI1D,MAAM,MAAM,oBAAoB,GAAG,iBAAiB,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE7E;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAWrC;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAYtC;AAkCD,MAAM,WAAW,0BAA0B;IACzC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAmBD,wBAAgB,sBAAsB,CAAC,YAAY,CAAC,EAAE,YAAY,GAAG,MAAM,CAsB1E;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,CAAC,EAAE,0BAA0B,GACnC,MAAM,CA2ER"}

package/dist/types/utils/shell-context.d.ts

@@ -1,7 +0,0 @@
-export type ShellFamily = "powershell" | "cmd" | "bash" | "unknown";
-export interface ShellContext {
-    family: ShellFamily;
-    displayName: string;
-}
-export declare function detectShellContext(env?: NodeJS.ProcessEnv, currentPlatform?: NodeJS.Platform): ShellContext;
-//# sourceMappingURL=shell-context.d.ts.map

package/dist/types/utils/shell-context.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"shell-context.d.ts","sourceRoot":"","sources":["../../../src/utils/shell-context.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,KAAK,GAAG,MAAM,GAAG,SAAS,CAAC;AAEpE,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,WAAW,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAgDD,wBAAgB,kBAAkB,CAChC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,eAAe,GAAE,MAAM,CAAC,QAAqB,GAC5C,YAAY,CAUd"}