@letta-ai/letta-code 0.34.26 → 0.34.27

package/skills/customizing-commands/SKILL.md

@@ -10,10 +10,10 @@ Use this as the command-specific entrypoint for local mod slash commands. For br
 Mod files live in:
 
 ```text
-~/.letta/mods/
+${LETTA_CONFIG_DIR:-$HOME/.letta}/mods/
 ```
 
-Use a focused file name, e.g. `~/.letta/mods/review.ts` or `~/.letta/mods/commands.ts`.
+Use a focused file name, e.g. `${LETTA_CONFIG_DIR:-$HOME/.letta}/mods/review.ts` or `${LETTA_CONFIG_DIR:-$HOME/.letta}/mods/commands.ts`.
 
 ## First decide whether a command is right
 
@@ -29,7 +29,7 @@ If the command is a reusable workflow like `/goal`, put the workflow instruction
 
 ## Workflow
 
-1. Inspect `~/.letta/mods/` for related command files.
+1. Inspect `${LETTA_CONFIG_DIR:-$HOME/.letta}/mods/` for related command files.
 2. Preserve unrelated mod code; create a focused new file if merging is messy.
 3. Register with `letta.commands.register()` and guard with `letta.capabilities.commands`.
 4. Return the unregister function, or a disposer that calls it plus any timer/panel cleanup.

package/skills/customizing-statusline/SKILL.md

@@ -8,7 +8,7 @@ description: Creates, edits, and migrates Letta Code statusline mods. Use when h
 Use this skill to create or update the global Letta Code statusline mod:
 
 ```text
-~/.letta/mods/statusline.tsx
+${LETTA_CONFIG_DIR:-$HOME/.letta}/mods/statusline.tsx
 ```
 
 The statusline is a panel registered at `order: 0` — the primary line just below the input. It overrides the built-in `agent · model` line. Host UI can still temporarily preempt it for safety confirmations and transient hints.
@@ -26,14 +26,14 @@ The order-0 panel owns the whole primary row. It renders text (not React) and ow
 
 ## Workflow
 
-1. Check whether `~/.letta/mods/statusline.tsx` exists.
+1. Check whether `${LETTA_CONFIG_DIR:-$HOME/.letta}/mods/statusline.tsx` exists.
 2. If it exists, read it before editing and preserve unrelated code.
 3. If it does not exist, synthesize a focused starter for the user's request.
 4. If the user asks to migrate, import a `.sh` file, or match a shell prompt, read `references/migration.md`.
 5. If API details or concrete patterns are needed, read `references/api.md` and `references/examples.md`.
 6. If the request combines statusline work with commands, tools, events, other panels, or stateful mod behavior, also use `creating-mods` and its `references/architecture.md`.
 7. Guard panel work with `letta.capabilities.ui.panels` when writing new files.
-8. Edit `~/.letta/mods/statusline.tsx`.
+8. Edit `${LETTA_CONFIG_DIR:-$HOME/.letta}/mods/statusline.tsx`.
 9. Summarize the absolute file path changed and tell the user to run `/reload` unless the command can reload automatically.
 
 ## Bare `/statusline` behavior

package/skills/customizing-statusline/references/api.md

@@ -1,11 +1,11 @@
 # Statusline Mod API
 
-Use this reference when creating or editing `~/.letta/mods/statusline.tsx`.
+Use this reference when creating or editing `${LETTA_CONFIG_DIR:-$HOME/.letta}/mods/statusline.tsx`.
 
 ## Location
 
 ```text
-~/.letta/mods/statusline.tsx
+${LETTA_CONFIG_DIR:-$HOME/.letta}/mods/statusline.tsx
 ```
 
 This is a trusted, user-owned global mod file. Project mods are intentionally unsupported for now.
@@ -147,7 +147,7 @@ render: ({ width, columns }) => columns(["left", "middle", "right"], width),
 
 ## Reload behavior
 
-After editing `~/.letta/mods/statusline.tsx`, tell the user to run:
+After editing `${LETTA_CONFIG_DIR:-$HOME/.letta}/mods/statusline.tsx`, tell the user to run:
 
 ```text
 /reload

package/skills/customizing-statusline/references/migration.md

@@ -1,13 +1,13 @@
 # Statusline Migration
 
-Use this reference when migrating legacy command statuslines, standalone `.sh` statusline scripts, or shell PS1 prompts into `~/.letta/mods/statusline.tsx`.
+Use this reference when migrating legacy command statuslines, standalone `.sh` statusline scripts, or shell PS1 prompts into `${LETTA_CONFIG_DIR:-$HOME/.letta}/mods/statusline.tsx`.
 
 ## Legacy Letta command statusline
 
 Inspect these files for old config:
 
 ```text
-~/.letta/settings.json
+${LETTA_CONFIG_DIR:-$HOME/.letta}/settings.json
 <project>/.letta/settings.json
 <project>/.letta/settings.local.json
 ```

package/skills/initializing-memory/SKILL.md

@@ -159,7 +159,7 @@ You — not the subagents — decide what becomes memory, and you write it. Synt
 
 ```bash
 node <SKILL_DIR>/scripts/history-coverage.mjs --prepared /tmp/letta-init-history \
-  --journal ~/.letta/workflows/executions/<id>/journal.jsonl \
+  --journal "${LETTA_CONFIG_DIR:-$HOME/.letta}/workflows/executions/<id>/journal.jsonl" \
   --retry-out /tmp/letta-init-history/retry.json
 ```
 

package/skills/self-configuration/SKILL.md

@@ -17,7 +17,7 @@ The important part is choosing the right layer. Do not smear a preference into d
 | Memory and identity | Facts worth retaining, style preferences, persona changes, project knowledge, reusable skills | Edit `$MEMORY_DIR` files and sync the memory repo |
 | Server agent fields | Agent default model (only on explicit request), context limit, system prompt, compaction, agent name, description | Patch `/v1/agents/{agent_id}` |
 | Server conversation fields | Model/context changes for the current conversation (the normal target) | Patch `/v1/conversations/{conversation_id}` |
-| Local settings | Permissions, environment variables, UI/runtime preferences, pinned agents, toolset overrides, reflection cadence | Edit `~/.letta/settings.json`, `./.letta/settings.json`, or `./.letta/settings.local.json` |
+| Local settings | Permissions, environment variables, UI/runtime preferences, pinned agents, toolset overrides, reflection cadence | Edit `$LETTA_CONFIG_DIR/settings.json` when configured (otherwise `~/.letta/settings.json`), `./.letta/settings.json`, or `./.letta/settings.local.json` |
 | Mods | New deterministic tools, slash commands, providers, statusline behavior, or lightweight UI | Load `creating-mods`, `customizing-commands`, or `customizing-statusline` |
 | Skills | Reusable procedural knowledge or bundled scripts | Load `creating-skills` or `acquiring-skills` |
 | Channels | Slack/Discord/Telegram/WhatsApp/Signal accounts, pairing, routing, listener state | Use `letta channels` or channel commands |
@@ -232,7 +232,7 @@ Settings scopes:
 
 | File | Scope | Typical contents |
 | --- | --- | --- |
-| `~/.letta/settings.json` | User/global | Permissions, env keys, experiments, UI/runtime preferences, agents[] entries |
+| `$LETTA_CONFIG_DIR/settings.json` when configured; otherwise `~/.letta/settings.json` | User/global | Permissions, env keys, experiments, UI/runtime preferences, agents[] entries |
 | `./.letta/settings.json` | Project/shared | Project settings committed with the repo |
 | `./.letta/settings.local.json` | Project-local | Personal project overrides, usually gitignored |
 
@@ -347,7 +347,7 @@ Use skills when the user wants you to become good at a repeatable workflow. Sour
 
 1. Project skills: `.agents/skills/` with `.skills/` as legacy fallback
 2. Agent skills: `$MEMORY_DIR/skills/`
-3. Global skills: `~/.letta/skills/`
+3. Global skills: `$LETTA_CONFIG_DIR/skills/` when configured; otherwise `~/.letta/skills/`
 4. Bundled skills
 
 Load `creating-skills` to create or edit a skill. Load `acquiring-skills` when the user asks for a capability you do not already have. Project, global, bundled, and agent-owned skills have different visibility; verify the target scope before changing skills another agent may load.
@@ -385,7 +385,7 @@ letta channels pair --channel <channel> --code <code> --agent <agent-id> --conve
 letta server --channels <channel>
 ```
 
-Channel state lives under `~/.letta/channels/<channel>/` (`config.yaml`, `accounts.json`, routing/pairing files, and channel runtimes). Account tokens may be plaintext in `file` mode or keyring placeholders in `keyring`/`auto` mode. Configure storage with `channelCredentialsStore` (`file`, `keyring`, `auto`) or `LETTA_CHANNEL_CREDENTIALS_STORE`; do not treat keyring placeholders as usable secrets and do not print tokens. Channel configuration and pairing can route external messages to other agents/conversations; verify IDs and get human consent for interactive authorization.
+Channel state lives under `${LETTA_CONFIG_DIR:-$HOME/.letta}/channels/<channel>/` (`config.yaml`, `accounts.json`, routing/pairing files, and channel runtimes). Account tokens may be plaintext in `file` mode or keyring placeholders in `keyring`/`auto` mode. Configure storage with `channelCredentialsStore` (`file`, `keyring`, `auto`) or `LETTA_CHANNEL_CREDENTIALS_STORE`; do not treat keyring placeholders as usable secrets and do not print tokens. Channel configuration and pairing can route external messages to other agents/conversations; verify IDs and get human consent for interactive authorization.
 
 `letta channels configure <channel>` is an interactive TTY wizard. Do not launch it as unattended work or claim setup succeeded while it is waiting for input; hand the authorization/setup step to the user.
 

package/skills/self-configuration/scripts/add_permission.py

@@ -19,10 +19,27 @@ from pathlib import Path
 from typing import Any
 
 
+def get_user_config_dir() -> Path:
+    """Resolve the product-selected global config directory."""
+    override = os.environ.get("LETTA_CONFIG_DIR", "").strip()
+    if override:
+        path = Path(override)
+        if not path.is_absolute():
+            raise ValueError("LETTA_CONFIG_DIR must be absolute")
+        return path
+    return Path.home() / ".letta"
+
+
 def get_settings_path(scope: str, working_directory: str) -> Path:
     """Get the settings file path for a given scope."""
     if scope == "user":
-        return Path.home() / ".letta" / "settings.json"
+        return get_user_config_dir() / "settings.json"
+    if os.environ.get("LETTA_CONFIG_DIR", "").strip() and (
+        Path(working_directory).resolve() == Path.home().resolve()
+    ):
+        raise ValueError(
+            f"Cannot save {scope} permissions under HOME while LETTA_CONFIG_DIR is set"
+        )
     if scope == "project":
         return Path(working_directory) / ".letta" / "settings.json"
     if scope == "local":
@@ -48,10 +65,14 @@ def load_settings(path: Path) -> dict[str, Any]:
     return parsed
 
 
-def save_settings(path: Path, settings: dict[str, Any]) -> None:
-    """Atomically save settings, preserving an existing file mode where practical."""
+def save_settings(path: Path, settings: dict[str, Any], secure: bool = False) -> None:
+    """Atomically save settings, securing the global config when requested."""
     path.parent.mkdir(parents=True, exist_ok=True)
-    mode = stat.S_IMODE(path.stat().st_mode) if path.exists() else None
+    if secure:
+        os.chmod(path.parent, 0o700)
+    mode = 0o600 if secure else (
+        stat.S_IMODE(path.stat().st_mode) if path.exists() else None
+    )
     temp_path: str | None = None
 
     try:
@@ -194,7 +215,7 @@ def main() -> None:
 
     if added:
         try:
-            save_settings(settings_path, settings)
+            save_settings(settings_path, settings, secure=args.scope == "user")
         except OSError as exc:
             print(f"Could not save {settings_path}: {exc}", file=sys.stderr)
             sys.exit(1)

package/skills/self-configuration/scripts/show_config.py

@@ -54,10 +54,25 @@ VERSION_TIMEOUT_SECONDS = 2
 MAX_VERSION_TEXT = 200
 
 
+def get_user_config_dir() -> Path:
+    """Resolve the product-selected global config directory."""
+    override = os.environ.get("LETTA_CONFIG_DIR", "").strip()
+    if override:
+        path = Path(override)
+        if not path.is_absolute():
+            raise ValueError("LETTA_CONFIG_DIR must be absolute")
+        return path
+    return Path.home() / ".letta"
+
+
 def get_settings_paths(working_directory: str) -> list[tuple[str, Path]]:
     """Return (scope, path) in precedence order (lowest to highest)."""
-    return [
-        ("user", Path.home() / ".letta" / "settings.json"),
+    paths = [("user", get_user_config_dir() / "settings.json")]
+    if os.environ.get("LETTA_CONFIG_DIR", "").strip() and (
+        Path(working_directory).resolve() == Path.home().resolve()
+    ):
+        return paths
+    return paths + [
         ("project", Path(working_directory) / ".letta" / "settings.json"),
         ("local", Path(working_directory) / ".letta" / "settings.local.json"),
     ]

package/skills/video-generation/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: video-generation
+description: Generate videos from text prompts (and optional reference or frame images) using Letta's asynchronous video generation API. Use when the user asks to create, generate, or make a video or animation from a description, animate an existing image, or turn a prompt into a short video clip.
+---
+
+# Video Generation
+
+Generate videos via Letta's async `POST /v1/videos` using `curl` + `jq`. Requires `LETTA_BASE_URL` and `LETTA_API_KEY`, which the runtime provides. If either is unset, stop and ask the user to authenticate with Letta Cloud; do not ask for a video provider key.
+
+This skill is adapted from OpenRouter's `openrouter-video` skill
+([OpenRouterTeam/skills](https://github.com/OpenRouterTeam/skills/blob/83827c3f3b1200bc3b609f4ab4ec3241c0cfb7ad/skills/openrouter-video/SKILL.md)).
+Letta's endpoint forwards the request with Letta's key and charges the
+organization's Letta credits for the cost of each completed video.
+
+Build every URL relative to `${LETTA_BASE_URL%/}` and send `Authorization: Bearer $LETTA_API_KEY`. Do not hardcode `https://api.letta.com`: Desktop and remote runtimes may provide a proxy base URL, and the credential may only be valid through that URL.
+
+## The three steps
+
+Video generation is async: submit → poll → download. A single request can't return the video because generation takes 30s–a few minutes. Tell the user the job was submitted so they know the delay is expected.
+
+1. `POST /v1/videos` → `{ id, polling_url, status: "pending" }` (`polling_url` is the absolute URL of step 2)
+2. `GET /v1/videos/{id}` every ~30s until `status` is `completed` (terminal failures: `failed`, `cancelled`, `expired` — surface the `error` field verbatim)
+3. `GET /v1/videos/{id}/content?index=0` **with the auth header** → MP4 bytes
+
+A completed job also has `urls`: signed downloads that need no API key until `expires_at` (Unix seconds); anyone holding one can download the video, so prefer step 3.
+
+## Pick parameters from the models endpoint, don't guess
+
+`resolution`, `aspect_ratio`, `duration`, and `frame_images[].frame_type` are per-model. Before the first submit for a new model (or whenever the user asks for something specific), fetch the model's capabilities and only send values from the returned sets:
+
+```bash
+curl -sS "${LETTA_BASE_URL%/}/v1/videos/models" \
+  -H "Authorization: Bearer $LETTA_API_KEY" \
+  | jq '.data[] | select(.id == "MODEL_ID")'
+```
+
+Fields on each model worth knowing: `supported_resolutions`, `supported_aspect_ratios`, `supported_sizes`, `supported_durations` (often discrete like `[4,6,8]`, not a range), `supported_frame_images` (which `frame_type` values are accepted), `generate_audio` and `seed` (capability bools), `pricing_skus`, and `allowed_passthrough_parameters`. An out-of-set value returns a 400, so validate client-side.
+
+Models include `google/veo-3.1`, `bytedance/seedance-2.5`, `kwaivgi/kling-v3.0-pro`, `minimax/hailuo-3`, `minimax/hailuo-3-max`, and `heygen/avatar-iv` (a talking head from one photo); the models endpoint has the full list.
+
+## Full workflow (drop-in)
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+PROMPT="a golden retriever playing fetch on a sunny beach"
+MODEL="google/veo-3.1"
+OUTPUT="video-$(date +%Y%m%d-%H%M%S).mp4"
+base_url="${LETTA_BASE_URL%/}"
+
+# Build payload — extend with resolution/aspect_ratio/duration/etc. as needed.
+payload=$(jq -n --arg model "$MODEL" --arg prompt "$PROMPT" \
+  '{model: $model, prompt: $prompt}')
+
+submit=$(curl -sS -X POST "$base_url/v1/videos" \
+  -H "Authorization: Bearer $LETTA_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d "$payload")
+
+job_id=$(echo "$submit" | jq -r '.id // empty')
+if [ -z "$job_id" ]; then
+  echo "Submit failed: $(echo "$submit" | jq -r '.message // .')" >&2
+  exit 1
+fi
+echo "Submitted $job_id" >&2
+
+while :; do
+  sleep 30
+  resp=$(curl -sS "$base_url/v1/videos/$job_id" -H "Authorization: Bearer $LETTA_API_KEY")
+  # Avoid the name `status` — zsh treats it as read-only.
+  st=$(echo "$resp" | jq -r '.status')
+  echo "Status: $st" >&2
+  case "$st" in
+    completed) break ;;
+    failed|cancelled|expired)
+      echo "Generation $st: $(echo "$resp" | jq -r '.error // "unknown"')" >&2
+      exit 1 ;;
+  esac
+done
+
+curl -sS -f "$base_url/v1/videos/$job_id/content?index=0" \
+  -H "Authorization: Bearer $LETTA_API_KEY" \
+  --output "$OUTPUT"
+
+echo "$resp" | jq --arg out "$(realpath "$OUTPUT")" \
+  '{job_id: .id, video_saved: $out, billing}'
+```
+
+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; `billing.credits_charged` on the completed job has them.
+
+## Parameters
+
+Required: `model`. `prompt` is required by every model except those that can generate from image input alone. Common optional fields:
+
+- `duration` (int) — must be one of the model's `supported_durations`.
+- `resolution` (string) / `aspect_ratio` (string) / `size` (string, `"WxH"`) — `size` is interchangeable with resolution + aspect_ratio.
+- `generate_audio` (bool) — only meaningful if the model's `generate_audio` capability is true.
+- `seed` (int) — honored only if the model's `seed` capability is true.
+- `frame_images[]` — image-to-video; each entry is `{ type: "image_url", image_url: { url }, frame_type: "first_frame" | "last_frame" }`.
+- `input_references[]` — reference-to-video (style guidance); image entries have the same shape, no `frame_type`. Audio and video references are `{ type: "audio_url", audio_url: { url } }` and `{ type: "video_url", video_url: { url } }`; only some models (such as `bytedance/seedance-2.5`) use them, and the rest ignore them. If both arrays are present, `frame_images` wins.
+- `provider.options.<slug>.parameters.<key>` — provider passthrough, see below.
+
+Image `url` can be a public `https://` URL or a local-file data URL: `MIME=image/png; B64=$(base64 < file.png | tr -d '\n'); url="data:${MIME};base64,${B64}"`. Audio and video references take URLs the same way.
+
+## Provider passthrough
+
+Provider-specific params go under `provider.options.<slug>.parameters`. The allowed keys for a given model are listed (flat) in `allowed_passthrough_parameters` on the models endpoint — but the meaning, value range, and required combinations come from the *upstream provider's* API docs (Google Vertex, Alibaba Dashscope, Kwai, ByteDance Volc Engine, MiniMax, OpenAI, etc.). Read the upstream docs before using an unfamiliar key; casing conventions differ between providers (Google/OpenAI use camelCase, most others use snake_case).
+
+Example:
+
+```json
+{
+  "model": "google/veo-3.1",
+  "prompt": "a time-lapse of a flower blooming",
+  "provider": {
+    "options": {
+      "google-vertex": {
+        "parameters": {
+          "personGeneration": "allow",
+          "negativePrompt": "blurry, low quality"
+        }
+      }
+    }
+  }
+}
+```
+
+`heygen/avatar-iv` animates one photo into a lip-synced talking head: pass the photo as an image in `input_references` and describe the video in `prompt`. Its passthrough keys (slug `heygen`) include `voice_id`, `motion_prompt`, and `expressiveness`; take their values from HeyGen's API docs.
+
+```json
+{
+  "model": "heygen/avatar-iv",
+  "prompt": "A friendly presenter welcomes viewers to the product tour",
+  "aspect_ratio": "9:16",
+  "input_references": [
+    { "type": "image_url", "image_url": { "url": "data:image/png;base64,..." } }
+  ]
+}
+```
+
+## Chaining with other skills
+
+- **Keyframes:** generate stills with the `image-generation` skill, then pass them as `frame_images` (`first_frame` / `last_frame`) or image `input_references` as data URLs.
+- **Sound:** make a voiceover with the `speech-generation` skill or a soundtrack with the `music-generation` skill, then pass the audio as an `audio_url` input reference to a model that uses audio, or mix it onto the finished MP4 (for example with `ffmpeg`).
+
+## Notes
+
+- **Billing**: the organization needs credits for an estimate before a job is submitted; once it completes, it is charged for the video's cost. Don't resubmit needlessly.
+- **Errors**: `402` = insufficient credits (`credits_required` in body); `400`/`404`/`500` return `{ "message": "..." }` — surface it to the user.
+
+Video generation is not ZDR-eligible because the provider must temporarily retain the output for the async download step.

package/skills/workflow-authoring/SKILL.md

@@ -256,7 +256,7 @@ quick checks.
 
 Every run persists its script, args, and a `journal.jsonl` with one line per
 completed subagent call (prompt, outcome, conversation id) under
-`~/.letta/workflows/executions/<id>/`; the tool result names the paths. Before
+`${LETTA_CONFIG_DIR:-$HOME/.letta}/workflows/executions/<id>/`; the tool result names the paths. Before
 diagnosing why a workflow returned an empty or unexpected result, read that
 journal — it records each agent's actual return value and failure detail.
 A failed run is not resumable: fix the script and launch it again.