@letta-ai/letta-code 0.34.15 → 0.34.17

package/npm-shrinkwrap.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.34.15",
+  "version": "0.34.17",
   "lockfileVersion": 3,
   "packages": {
     "node_modules/@alcalzone/ansi-tokenize": {
@@ -5452,7 +5452,7 @@
     },
     "": {
       "name": "@letta-ai/letta-code",
-      "version": "0.34.15",
+      "version": "0.34.17",
       "dependencies": {
         "@earendil-works/pi-ai": "^0.99.1",
         "@janhapke/sharp-electron": "0.35.3-electron.1",

package/package.json

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

package/scripts/source-file-size-baseline.json

@@ -9,7 +9,7 @@
   "src/cli/app/use-approval-flow.ts": 1071,
   "src/cli/app/use-configuration-handlers.ts": 1417,
   "src/cli/app/use-conversation-loop.ts": 2860,
-  "src/cli/app/use-submit-handler.ts": 3801,
+  "src/cli/app/use-submit-handler.ts": 3797,
   "src/cli/components/AgentSelector.tsx": 1104,
   "src/cli/components/InputRich.tsx": 2116,
   "src/cli/components/ModelSelector.tsx": 1259,
@@ -19,7 +19,7 @@
   "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": 4778,
+  "src/headless.ts": 4771,
   "src/hooks/integration.test.ts": 1147,
   "src/index.ts": 2575,
   "src/mods/learning-harness.ts": 2434,
@@ -33,12 +33,14 @@
   "src/providers/chatgpt-usage-service.ts": 1112,
   "src/settings-manager.test.ts": 1635,
   "src/settings-manager.ts": 2092,
-  "src/tools/manager.ts": 2609,
+  "src/tools/manager.ts": 2606,
   "src/tools/tool-execution-context.test.ts": 1092,
-  "src/types/protocol_v2.ts": 2531,
+  "src/types/protocol_v2.ts": 2532,
+  "src/websocket/listener/message-router.ts": 1005,
   "src/websocket/listen-client-concurrency.test.ts": 2557,
   "src/websocket/listen-client-protocol.test.ts": 5664,
   "src/websocket/listener/commands/memory.ts": 1114,
   "src/websocket/listener/file-commands.ts": 1045,
-  "src/websocket/listener/protocol-inbound.ts": 2055
+  "src/websocket/listener/protocol-inbound.ts": 2054,
+  "src/websocket/listener/protocol-outbound.ts": 1001
 }

package/skills/creating-skills/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: creating-skills
-description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Letta Code's capabilities with specialized knowledge, workflows, or tool integrations.
+description: Guide for creating effective skills. Use when creating a new skill or updating an existing one that extends Letta Code's capabilities with specialized knowledge, workflows, or tool integrations, whether a user asks for it or a reusable workflow is worth capturing.
 ---
 
 # Creating Skills
@@ -206,7 +206,7 @@ Skill creation involves these steps:
 2. Plan reusable skill contents (scripts, references, assets)
 3. Initialize the skill (run init-skill.ts)
 4. Edit the skill (implement resources and write SKILL.md)
-5. Package the skill (run package-skill.ts)
+5. Package the skill if it will be distributed (run package-skill.ts)
 6. Iterate based on real usage
 
 Follow these steps in order, skipping only if there is a clear reason why they are not applicable.
@@ -215,16 +215,15 @@ Follow these steps in order, skipping only if there is a clear reason why they a
 
 Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.
 
-To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.
+To create an effective skill, clearly understand concrete examples of how the skill will be used. Draw them from the material at hand first: the conversation or transcripts that motivated the skill, the commands and tool calls that worked, and the requests that would trigger it.
 
-For example, when building an `editing-images` skill, relevant questions include:
+For example, when building an `editing-images` skill, establish:
 
-- "What functionality should the editing-images skill support? Editing, rotating, anything else?"
-- "Can you give some examples of how this skill would be used?"
-- "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?"
-- "What would a user say that should trigger this skill?"
+- What functionality the skill should support: editing, rotating, anything else?
+- What concrete requests it should handle, such as "Remove the red-eye from this image" or "Rotate this image"
+- What a user would say that should trigger the skill
 
-To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.
+If you are working with a user and these remain unclear, ask the most important questions first rather than many at once. If no one is available to ask, such as in a background or automated run, do not wait for answers: scope the skill to what the source material demonstrates and leave out functionality it does not support.
 
 Conclude this step when there is a clear sense of the functionality the skill should support.
 
@@ -265,7 +264,7 @@ Usage:
 ```bash
 npx tsx <SKILL_DIR>/scripts/init-skill.ts <skill-name> --path <output-directory>
 ```
-Where `<SKILL_DIR>` is the Skill Directory shown when the skill was loaded (visible in the injection header).
+Where `<SKILL_DIR>` is the Skill Directory shown when the skill was loaded (visible in the injection header). If no Skill Directory is shown, create the skill directory and `SKILL.md` directly instead.
 
 The script:
 
@@ -291,7 +290,7 @@ These files contain established best practices for effective skill design.
 
 #### Start with Reusable Skill Contents
 
-To begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`.
+To begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Some resources come from outside the source material. For example, a `brand-guidelines` skill may need brand assets or templates in `assets/`, or documentation in `references/`. Ask the user for them if you are working with one; otherwise include only what is available and leave out resources you cannot supply.
 
 Added scripts must be tested by actually running them to ensure there are no bugs and that the output matches what is expected. If there are many similar scripts, only a representative sample needs to be tested to ensure confidence that they all work while balancing time to completion.
 
@@ -333,7 +332,9 @@ Write instructions for using the skill and its bundled resources.
 
 ### Step 5: Packaging a Skill
 
-Once development of the skill is complete, it must be packaged into a distributable .skill file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements:
+Package the skill only when it needs to be distributed as a file, for example when sharing it with a user. Skills maintained in place, such as those under an agent's memory `skills/` directory, are used directly and need no packaging.
+
+To package a skill into a distributable .skill file, run the packaging script. The packaging process automatically validates the skill first to ensure it meets all requirements:
 
 ```bash
 npx tsx <SKILL_DIR>/scripts/package-skill.ts <path/to/skill-folder>
@@ -360,7 +361,7 @@ If validation fails, the script will report the errors and exit without creating
 
 ### Step 6: Iterate
 
-After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.
+Improve a skill when real usage shows it falling short, whether through user feedback or sessions where the skill was used. Usage with fresh context of how the skill performed is the best evidence.
 
 **Iteration workflow:**
 

package/skills/music-generation/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 ElevenLabs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/music-generation/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: music-generation
+description: Generate music using ElevenLabs Music through Letta. Use when creating instrumental tracks, songs with lyrics, background music, jingles, theme songs, or any AI-generated music composition. Supports prompt-based generation and composition plans for section-by-section control.
+license: MIT
+---
+
+# ElevenLabs Music Generation (via Letta)
+
+Generate music from text prompts: instrumental tracks, songs with lyrics, and fine-grained control via composition plans. Examples use `music_v2_5`, the most advanced ElevenLabs music model and the endpoint's default.
+
+This skill is adapted from ElevenLabs' `music` skill
+([elevenlabs/skills](https://github.com/elevenlabs/skills), MIT; see `LICENSE`).
+Instead of calling ElevenLabs with your own key, you call Letta's hosted endpoint
+`POST /v1/audio/music` (or `POST /v1/audio/music/stream`). It forwards the
+request to ElevenLabs with Letta's key and charges the organization's Letta
+credits, so you do not need an ElevenLabs API key. The request and response are
+the same as ElevenLabs "Compose music": a JSON body with the same field names,
+`output_format` as a query parameter, and the audio file as the response body.
+
+## Quick Start
+
+```bash
+base_url="${LETTA_BASE_URL%/}"
+
+curl -sS -X POST "$base_url/v1/audio/music/stream?output_format=mp3_48000_192" \
+  -H "Authorization: Bearer $LETTA_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"prompt":"A chill lo-fi hip hop beat with jazzy piano chords","music_length_ms":30000,"model_id":"music_v2_5"}' \
+  --output output.mp3 \
+  --write-out '%{http_code} %{content_type}\n'
+```
+
+A `200` with an `audio/...` content type means `output.mp3` is the song. Any
+other status means `output.mp3` holds a JSON error with a `message` instead;
+read it (see "Error Handling") and do not share the file.
+
+Use the runtime-provided `LETTA_BASE_URL` and `LETTA_API_KEY` together. Build
+URLs relative to `${LETTA_BASE_URL%/}` and do not hardcode
+`https://api.letta.com`. If either variable is missing, the user needs to
+authenticate with Letta Cloud; do not ask for an ElevenLabs key.
+
+Generation takes a while (roughly 10-30 seconds per minute of music). Prefer
+`/v1/audio/music/stream`: it sends audio as it is generated, so long songs do
+not sit on an idle connection. `/v1/audio/music` takes the same request and
+returns the same file, but may send nothing until the whole song is done, so
+use it only for short songs. Do not set a short client timeout either way.
+
+Share the saved file the way your current surface supports: attach or upload it
+to the conversation or channel you are replying in. Keep credit amounts out of
+replies unless the user asks about cost.
+
+## Length
+
+- A song is 3 seconds to 10 minutes (600,000 ms).
+- With `prompt`, `music_length_ms` is optional. Leave it out to let the model
+  choose a length that suits the prompt.
+- With `composition_plan`, the length is the sum of the chunk or section
+  `duration_ms` values; do not also send `music_length_ms`.
+- Credits are charged for the length of the audio actually returned, at
+  ElevenLabs' per-minute price. Before generating, the organization needs
+  enough credits for the longest song the request allows: `music_length_ms`,
+  the plan total, or 10 minutes when a prompt sets no length. Setting
+  `music_length_ms` lowers that requirement.
+
+## Models
+
+| Model ID | Best For |
+|----------|----------|
+| `music_v2_5` | **Default.** Most advanced: best audio quality and prompt adherence. Chunk-based composition plans. |
+| `music_v2` | Previous generation. Chunk-based composition plans. |
+| `music_v1` | Oldest. Section-based composition plans. Use only when explicitly requested. |
+
+## Prompting
+
+Describe the music the way a producer would brief a session:
+
+- Genre and mood: "melancholic indie folk", "triumphant orchestral trailer".
+- Instrumentation and vocals: "fingerpicked acoustic guitar, soft female vocals".
+- Tempo and key when they matter: "90 BPM", "D minor".
+- Structure and energy: "starts sparse, builds into a big chorus".
+- Lyrics: put them in the prompt for short songs, or use a composition plan
+  to control which lines land in which section.
+- Set `force_instrumental: true` to guarantee no vocals (prompt mode only).
+
+## Composition Plans
+
+`music_v2_5` composition plans are an ordered list of `chunks`. Each chunk specifies its own
+`text` (section label, lyrics, inline cues), `duration_ms`, `positive_styles`, `negative_styles`,
+and `context_adherence` (`low`, `medium`, or `high`, default `high`). Up to 30 chunks per plan,
+each 3,000–120,000 ms. Each chunk's `text` supports up to 6,132 characters, with up to 30 lines
+of 200 characters each. Send the plan instead of `prompt` and `music_length_ms`:
+
+```json
+{
+  "model_id": "music_v2_5",
+  "composition_plan": {
+    "chunks": [
+      {
+        "text": "[Verse]\nWalking down an empty street",
+        "duration_ms": 15000,
+        "positive_styles": ["pop", "upbeat", "female vocals", "acoustic guitar", "120 BPM", "polished production"],
+        "negative_styles": ["dark", "slow"],
+        "context_adherence": "high"
+      },
+      {
+        "text": "[Chorus]\nThis is my moment",
+        "duration_ms": 15000,
+        "positive_styles": ["powerful vocals", "full band"],
+        "negative_styles": [],
+        "context_adherence": "high"
+      }
+    ]
+  }
+}
+```
+
+- Put broader characteristics (genre, instrumentation, vocal style) in `positive_styles`, not in
+  `text`. The first chunk's styles set the overall tone — include 6–7 styles there.
+- Use later chunks' styles for progression: "bass joins in", "building intensity", "drums softening".
+- Inline cues in curly braces add moments inside a chunk: `{guitar solo}`, `{vinyl crackle}`.
+- Lower `context_adherence` lets a chunk depart from its neighbors, for a bridge or a key change.
+- `seed` works with composition plans (not with `prompt`) to make results more repeatable.
+
+For `music_v1`, plans use `positive_global_styles`, `negative_global_styles`, and `sections`
+(each with `section_name`, `positive_local_styles`, `negative_local_styles`, `duration_ms`, and
+`lines`), and `respect_sections_durations: false` lets the model adjust section lengths.
+
+Inpainting and audio references (`song_id` chunks, `conditioning_ref`, `source_from`) are not
+available through this endpoint and return 400.
+
+## Output Formats
+
+Pass `output_format` as a query parameter, not in the body. The default, `auto`,
+gives `mp3_48000_192` for `music_v2` and later (`mp3_44100_128` for `music_v1`).
+Name the file to match the format.
+
+| Format | Description |
+|--------|-------------|
+| `mp3_48000_192` | MP3 48kHz 192kbps (what `auto` picks for v2 models) |
+| `mp3_48000_320` | MP3 48kHz 320kbps - highest quality MP3 |
+| `mp3_44100_128` | MP3 44.1kHz 128kbps - smaller files |
+| `pcm_48000` | Raw 16-bit PCM 48kHz, no header - for further processing |
+| `opus_48000_128` | Opus 48kHz 128kbps in Ogg - efficient codec, small files |
+
+## Content Restrictions
+
+- Cannot reference specific artists, bands, or copyrighted lyrics. Describe the style instead
+  ("1960s British invasion rock" rather than a band name).
+- A rejected prompt returns 400 with ElevenLabs' `bad_prompt` detail, which includes a
+  `prompt_suggestion` with alternative phrasing. A rejected plan returns `bad_composition_plan`
+  with a `composition_plan_suggestion`. Retry with the suggestion.
+
+## Error Handling
+
+Errors return JSON with a `message`:
+- **400 with an ElevenLabs message**: invalid parameters or restricted content (see "Content Restrictions").
+- **400 "Provide prompt or composition_plan."**: send one of them.
+- **402**: the organization does not have enough Letta credits for the longest song the request
+  allows (`credits_required`). Setting a shorter `music_length_ms` may help; otherwise tell the user
+  and do not retry.
+- **500**: retry once, then report the failure.
+
+If the connection drops partway through `/stream`, the file is truncated; only the audio
+received is charged. Retry the request rather than sharing a partial song.

package/skills/speech-generation/SKILL.md

@@ -14,7 +14,8 @@ Instead of calling ElevenLabs with your own key, you call Letta's hosted endpoin
 `POST /v1/audio/speech`. It forwards the request to ElevenLabs with Letta's key
 and charges the organization's Letta credits, so you do not need an ElevenLabs
 API key. The request body uses the same field names as ElevenLabs "Create
-speech"; the voice ID goes in the body.
+speech" (the voice ID and `output_format` go in the body), and the response is
+the audio file itself, as with ElevenLabs.
 
 ## Quick Start
 
@@ -25,20 +26,9 @@ curl -sS -X POST "$base_url/v1/audio/speech" \
   -H "Authorization: Bearer $LETTA_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{"text":"Hello, welcome to ElevenLabs!","voice_id":"JBFqnCBsd6RMkjVDRZzb","model_id":"eleven_v4"}' \
-  > speech-response.json
-
-python3 - <<'PY'
-import base64, json
-
-with open("speech-response.json") as f:
-    response = json.load(f)
-if "audio_b64" not in response:
-    raise SystemExit(response.get("message", response))
-
-with open("output.mp3", "wb") as f:
-    f.write(base64.b64decode(response["audio_b64"]))
-print("saved output.mp3")
-PY
+  --output output.mp3 \
+  --dump-header speech-headers.txt \
+  --write-out '%{http_code} %{content_type}\n'
 ```
 
 Use the runtime-provided `LETTA_BASE_URL` and `LETTA_API_KEY` together. Build
@@ -46,9 +36,13 @@ URLs relative to `${LETTA_BASE_URL%/}` and do not hardcode
 `https://api.letta.com`. If either variable is missing, the user needs to
 authenticate with Letta Cloud; do not ask for an ElevenLabs key.
 
+A `200` with an `audio/...` content type means `output.mp3` is the speech. Any
+other status means `output.mp3` holds a JSON error with a `message` instead;
+read it (see "Error Handling") and do not share the file.
+
 Share the saved file the way your current surface supports: attach or upload it
-to the conversation or channel you are replying in. Never paste the base64 into
-a reply. Keep credit amounts out of replies unless the user asks about cost.
+to the conversation or channel you are replying in. Keep credit amounts out of
+replies unless the user asks about cost.
 
 ## Models
 
@@ -160,8 +154,9 @@ When generating long audio in multiple requests, the audio can have pops, unnatu
 {"text": "And this continues the story.", "voice_id": "JBFqnCBsd6RMkjVDRZzb", "model_id": "eleven_v4", "previous_text": "This is the first part."}
 ```
 
-Each response includes `request_id`. Instead of `previous_text`, you can pass up
-to three earlier `request_id` values in `previous_request_ids` (and later ones in
+Each response has a `request-id` header (saved by `--dump-header` above, e.g.
+`grep -i '^request-id:' speech-headers.txt`). Instead of `previous_text`, you can
+pass up to three earlier request IDs in `previous_request_ids` (and later ones in
 `next_request_ids` when regenerating a middle part). Keep the same voice, model,
 and voice settings for every part, split long text at sentence or paragraph
 boundaries (each request takes up to 10,000 characters), and concatenate the
@@ -169,7 +164,7 @@ files in order, for example with `ffmpeg -f concat`.
 
 ## Output Formats
 
-Pass `output_format` in the body.
+Pass `output_format` in the body, and name the file to match the format.
 
 | Format | Description |
 |--------|-------------|
@@ -187,22 +182,6 @@ Pass `output_format` in the body.
 | `opus_48000_64` | Opus 48kHz 64kbps - efficient codec, small files |
 | `wav_44100` | WAV 44.1kHz - uncompressed with headers |
 
-The Letta endpoint returns the whole file at once (as `audio_b64`); it does not stream.
-
-## Response
-
-```json
-{
-  "model_id": "eleven_v4",
-  "voice_id": "JBFqnCBsd6RMkjVDRZzb",
-  "output_format": "mp3_44100_128",
-  "audio_b64": "<base64>",
-  "request_id": "Frhov0LQNC3M9HcHKY3t",
-  "characters": 46,
-  "billing": { "credits_charged": 4, "transaction_id": "...", "new_credit_balance": "..." }
-}
-```
-
 ## Error Handling
 
 Errors return JSON with a `message`:

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

@@ -28,6 +28,10 @@ For remote subagents, set `computer` and pass source paths and destination conve
 
 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).
 
+## Keep active Monitors on their computer
+
+A Monitor belongs to the computer where it started. While this conversation has an active Monitor, use a subagent on the requested computer instead of teleporting the parent conversation. If the user explicitly insists on moving the parent conversation, explain that they must stop the Monitor before teleporting the parent conversation; do not retry teleport while the Monitor remains active.
+
 ## 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.