@letta-ai/letta-code 0.34.25 → 0.34.27

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

@@ -7,7 +7,7 @@ description: Comprehensive guide for initializing or reorganizing agent memory.
 
 Your memory is projected to a filesystem at `$MEMORY_DIR`, so you can restructure it with ordinary file tools and git. This skill applies the [Context Constitution](https://github.com/letta-ai/context-constitution/blob/main/constitution/CONSTITUTION.md)'s Progressive Disclosure and Efficiency principles to the [MemFS v2 root-first design](https://github.com/letta-ai/letta-code/blob/main/src/agent/prompts/letta_root_memfs.md).
 
-**You own this task through completion**: research, ask, synthesize, write, commit, verify. Delegate research, but integrate the results yourself — launching a background task is not completion. If a memory worker you launched is still editing this checkout, wait for it, then re-read before editing.
+**You own this task through completion**: research, ask, synthesize, write, commit, verify. Delegate research, but integrate the results yourself — launching a background task is not completion.
 
 ## Principles
 
@@ -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/managing-agent-webhooks/SKILL.md

@@ -96,11 +96,13 @@ payload as a user message.
   unreadable receipt means deletion was accepted but remains unconfirmed; list
   webhooks before treating the capability URL as removed or retrying.
 - Normal update output additionally requires the returned webhook ID and
-  `enabled` state to match the requested operation; normal rotate output
-  requires the returned webhook ID to match. Canonical but contradictory 2xx
+  `enabled` state (or `target_device_id` for `update --computer`) to match the
+  requested operation; normal rotate output requires the returned webhook ID
+  to match. Canonical but contradictory 2xx
   records receive the same accepted/reconcile envelope and are never printed as
   ordinary success.
-- Normal create output also requires returned name and enabled state to match.
+- Normal create output also requires returned name, enabled state, and
+  `target_device_id` to match.
   An explicitly supplied preprompt must round-trip exactly; when preprompt is
   omitted, the server-owned default is accepted only as a nonblank string, while
   missing, null, empty, whitespace-only, and non-string values are contradictory.
@@ -207,6 +209,24 @@ The caller sends `Authorization: Basic <base64("webhook:<security-key>")>`.
 Do not print that header or the key. The helper derives it internally for test
 requests when the same key is piped through stdin.
 
+### Run webhook turns on a connected computer
+
+By default, webhook-triggered conversations run in the agent's Cloud sandbox.
+To run them on a connected computer instead, get its device ID from
+`letta computers list` and pass it with `--computer` on `create` or `update`:
+
+```bash
+node <SKILL_DIR>/scripts/manage-agent-webhooks.mjs update \
+  --webhook-id webhook-agent-... \
+  --computer <deviceId>
+```
+
+`list` shows the target as `target_device_id` (`null` means Cloud). If the
+computer is offline when a request arrives, that delivery fails; it does not
+fall back to Cloud. An unknown device ID returns `404 targetDeviceNotFound`.
+Pass `--computer cloud` to `update` to clear the target and go back to the
+Cloud sandbox.
+
 ### Test acceptance
 
 Public webhook:

package/skills/managing-agent-webhooks/scripts/manage-agent-webhooks.mjs

@@ -15,6 +15,7 @@ const COMMANDS = new Set([
   "requests",
   "rotate",
   "test",
+  "update",
 ]);
 const BOOLEAN_FLAGS = new Set([
   "confirm",
@@ -28,6 +29,7 @@ const COMMAND_OPTIONS = new Map([
   [
     "create",
     new Set([
+      "computer",
       "credential-output",
       "disabled",
       "name",
@@ -53,12 +55,14 @@ const COMMAND_OPTIONS = new Map([
       "webhook-id",
     ]),
   ],
+  ["update", new Set(["computer", "webhook-id"])],
 ]);
 
 function usage() {
   console.error(`Usage:
   node manage-agent-webhooks.mjs list
-  node manage-agent-webhooks.mjs create --name <name> (--public | --secure --credential-output <path> | --security-key-stdin) [--preprompt <text>] [--disabled]
+  node manage-agent-webhooks.mjs create --name <name> (--public | --secure --credential-output <path> | --security-key-stdin) [--preprompt <text>] [--disabled] [--computer <deviceId>]
+  node manage-agent-webhooks.mjs update --webhook-id <id> --computer <deviceId|cloud>
   node manage-agent-webhooks.mjs test --webhook-id <id> --confirm [--payload-file <path>] [--credential-file <path> | --security-key-stdin]
   node manage-agent-webhooks.mjs requests --webhook-id <id> [--limit <1-50>] [--include-body]
   node manage-agent-webhooks.mjs enable --webhook-id <id>
@@ -144,8 +148,10 @@ export function safeAgentWebhook(webhook) {
   for (const field of ["enabled", "requires_authorization_header"]) {
     if (typeof webhook[field] === "boolean") safe[field] = webhook[field];
   }
-  if (typeof webhook.disabled_at === "string" || webhook.disabled_at === null) {
-    safe.disabled_at = webhook.disabled_at;
+  for (const field of ["disabled_at", "target_device_id"]) {
+    if (typeof webhook[field] === "string" || webhook[field] === null) {
+      safe[field] = webhook[field];
+    }
   }
   return safe;
 }
@@ -753,6 +759,15 @@ function requireWebhookId(args) {
   return requireString(args["webhook-id"], "Pass --webhook-id");
 }
 
+// "cloud" maps to null: run webhook turns in the agent's Cloud sandbox.
+function targetDeviceIdFromArgs(args) {
+  const computer = requireString(
+    args.computer,
+    "--computer must be a device ID or cloud",
+  );
+  return computer === "cloud" ? null : computer;
+}
+
 function requireConfirmation(args, action) {
   if (args.confirm !== true) {
     throw new Error(`${action} requires --confirm`);
@@ -827,6 +842,10 @@ async function runManagementCommand(params) {
         "--preprompt must contain a non-whitespace character",
       );
     }
+    if (params.args.computer !== undefined) {
+      const targetDeviceId = targetDeviceIdFromArgs(params.args);
+      if (targetDeviceId) body.target_device_id = targetDeviceId;
+    }
     if (securityKey) body.security_key = securityKey;
     const credentialReservation = usesGeneratedCredential
       ? await reserveCredentialFile(params.args["credential-output"])
@@ -914,6 +933,8 @@ async function runManagementCommand(params) {
       if (
         webhook.name !== body.name ||
         webhook.enabled !== body.enabled ||
+        (webhook.target_device_id ?? null) !==
+          (body.target_device_id ?? null) ||
         !prepromptMatches
       ) {
         throw new Error(
@@ -1048,14 +1069,22 @@ async function runManagementCommand(params) {
     return;
   }
 
-  if (params.command === "enable" || params.command === "disable") {
+  if (
+    params.command === "enable" ||
+    params.command === "disable" ||
+    params.command === "update"
+  ) {
     if (params.command === "disable") {
       requireConfirmation(params.args, "Disabling a webhook");
     }
+    const update =
+      params.command === "update"
+        ? { target_device_id: targetDeviceIdFromArgs(params.args) }
+        : { enabled: params.command === "enable" };
     const mutation = await requestSideEffect(
       itemUrl,
       {
-        body: JSON.stringify({ enabled: params.command === "enable" }),
+        body: JSON.stringify(update),
         headers: params.headers,
         method: "PATCH",
       },
@@ -1074,12 +1103,12 @@ async function runManagementCommand(params) {
         params.baseUrl,
         params.agentId,
       );
-      const expectedEnabled = params.command === "enable";
-      if (
-        webhook.id !== webhookId ||
-        typeof webhook.enabled !== "boolean" ||
-        webhook.enabled !== expectedEnabled
-      ) {
+      const stateMatches =
+        params.command === "update"
+          ? webhook.target_device_id === update.target_device_id
+          : typeof webhook.enabled === "boolean" &&
+            webhook.enabled === update.enabled;
+      if (webhook.id !== webhookId || !stateMatches) {
         throw new Error(
           "Update response does not match the requested webhook state",
         );

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 |
@@ -110,7 +110,7 @@ Use the active layout shown by the prompt and memory files. Do not create a
 `system/` directory in a root-layout repository or move existing-layout memory
 to the root as part of an unrelated self-configuration request.
 
-A requested memory or identity change is memory as the main task: make the edit directly with ordinary file tools, preserve the active layout, stage only the files you changed by explicit path, commit in the same shell call, and verify the result before reporting success. If a memory worker you launched may still be running, read its output file first (it ends with `[Task completed]` or `[Task failed]`) and reread the files before editing what it was asked to change. Delegate to the background `memory` subagent only when the change is incidental to another task the user is waiting on.
+Before editing memory, load the relevant skills: `maintaining-core-memory` for root/core files, `maintaining-deferred-memory` for deferred files, and `creating-skills` for skills. Then make the edit directly with ordinary file tools so the agent with the context applies the memory guidance. Preserve the active layout, stage only changed files by explicit path, commit in the same shell call, and verify the result before reporting success.
 
 Do not use API system-prompt replacement for ordinary learning. That can clobber the compiled prompt. Edit the memory files instead.
 
@@ -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/syncing-memory-filesystem/SKILL.md

@@ -5,15 +5,7 @@ description: Diagnose and repair MemFS repository setup, remote sync, authentica
 
 # MemFS Repository Repair
 
-Use this skill only when the Git repository behind an agent's memory is not
-setting up or syncing correctly. For ordinary memory reads and edits, use the
-memory files without loading this skill. Delegate incidental upkeep during another
-task to the background `memory` subagent. When memory repair is the user's main
-request, diagnose and repair it directly, then verify the result before reporting
-success. If a memory worker you launched may still be running, wait for it: re-read
-its output file until it ends with `[Task completed]` or `[Task failed]` before
-editing memory files or changing Git state. While the harness reports a repair in
-progress, leave both alone as well; that worker edits `$MEMORY_DIR` in place.
+Use this skill when the Git repository behind an agent's memory is not setting up or syncing correctly. Before editing memory, load the relevant skills: `maintaining-core-memory` for root/core files, `maintaining-deferred-memory` for deferred files, and `creating-skills` for skills. Then make the edit directly with ordinary file tools so the agent with the context applies the memory guidance. Stage only changed files by explicit path and commit in the same shell call. Verify the repair before reporting success. While the harness reports a repair in progress, leave memory files and Git state to that repair worker, which edits `$MEMORY_DIR` in place.
 
 ## Current Model
 
@@ -122,7 +114,7 @@ cloud-backed agent's pending commits after the turn.
 The harness first tries a fast-forward pull. When a remote push is rejected
 because the remote moved, post-turn sync tries `git pull --rebase` and retries
 the push. If that rebase conflicts, the harness launches a fresh background
-`memory` subagent to repair it. The primary conversation is not interrupted.
+internal `memory` subagent to repair it. The primary conversation is not interrupted.
 The harness retries normal sync after the worker finishes. The instructions
 below are for explicit troubleshooting; routine repairs run in the background.
 

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.

package/dist/types/agent/memory-worktree.d.ts

@@ -1,83 +0,0 @@
-export interface ReflectionMemoryWorktree {
-    id: string;
-    parentMemoryDir: string;
-    worktreeBaseDir: string;
-    worktreeDir: string;
-    branchName: string;
-    baseHead: string;
-    gitCommonDir: string;
-}
-export interface CreateReflectionMemoryWorktreeOptions {
-    parentMemoryDir: string;
-    now?: Date;
-    /** Directory and branch prefix; memory workers use "memory-worker". */
-    label?: string;
-}
-export declare function createReflectionMemoryWorktree(options: CreateReflectionMemoryWorktreeOptions): Promise<ReflectionMemoryWorktree>;
-export interface ReflectionMemoryScope {
-    primaryRoot: string;
-    writableRoots: string[];
-    readonlyRoots: string[];
-}
-export declare function buildReflectionMemoryScope(worktree: ReflectionMemoryWorktree): ReflectionMemoryScope;
-export declare function buildReflectionIntegrationMemoryScope(worktree: ReflectionMemoryWorktree): ReflectionMemoryScope;
-export type ReflectionMemoryWorktreeFinalizeStatus = "merged" | "no_changes" | "parent_dirty" | "merge_conflict" | "dirty_uncommitted" | "failed";
-export interface ReflectionMemoryWorktreeFinalizeResult {
-    status: ReflectionMemoryWorktreeFinalizeStatus;
-    parentMemoryDir: string;
-    reflectionWorktreeDir: string;
-    reflectionBranch: string;
-    commitCount: number;
-    head?: string;
-    summary: string;
-    error?: string;
-    failurePhase?: "reflection" | "integration";
-}
-export declare function reflectionIntegrationConsumesTranscript(result: ReflectionMemoryWorktreeFinalizeResult): boolean;
-export declare function reflectionIntegrationShouldRecompile(result: ReflectionMemoryWorktreeFinalizeResult): boolean;
-export declare function reflectionMemoryParentHasChanges(parentMemoryDir: string): Promise<boolean>;
-export interface ReflectionMemoryWorktreeState {
-    commitCount: number;
-    dirty: boolean;
-    head?: string;
-}
-export declare function inspectReflectionMemoryWorktree(worktree: ReflectionMemoryWorktree): Promise<ReflectionMemoryWorktreeState>;
-/** Finalize without taking the checkout lease; the caller must already hold it. */
-export declare function finalizeReflectionMemoryWorktreeUnlocked(worktree: ReflectionMemoryWorktree, options: ReflectionMemoryWorktreeFinalizeOptions): Promise<ReflectionMemoryWorktreeFinalizeResult>;
-export declare function finalizeReflectionMemoryWorktree(worktree: ReflectionMemoryWorktree, options: ReflectionMemoryWorktreeFinalizeOptions): Promise<ReflectionMemoryWorktreeFinalizeResult>;
-export type MemoryWorkerWorktreeOutcome = {
-    status: "merged";
-    commitCount: number;
-    head: string;
-} | {
-    status: "no_changes";
-} | {
-    status: "discarded";
-} | {
-    status: "merge_conflict";
-    commitCount: number;
-    branchName: string;
-} | {
-    status: "failed";
-    error: string;
-};
-/**
- * Bring a memory worker's worktree back into the parent checkout. The caller
- * must hold the checkout lease. Commits are merged (fast-forward when
- * possible); uncommitted edits in the worktree are dropped, as are all edits
- * when `discard` is set (a cancelled worker). A merge that conflicts with the
- * parent's own changes is aborted and the branch is kept so nothing is lost.
- * Unlike reflection, a dirty parent does not block the merge: Git refuses only
- * when the parent's uncommitted files overlap the worker's commits, and that
- * surfaces as a conflict here.
- */
-export declare function integrateMemoryWorkerWorktree(worktree: ReflectionMemoryWorktree, options?: {
-    discard?: boolean;
-}): Promise<MemoryWorkerWorktreeOutcome>;
-export interface ReflectionMemoryWorktreeFinalizeOptions {
-    shouldMerge: boolean;
-    knownNoChanges?: boolean;
-    failureSummary?: string;
-    requireAlreadyMerged?: boolean;
-}
-//# sourceMappingURL=memory-worktree.d.ts.map

package/dist/types/agent/memory-worktree.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"memory-worktree.d.ts","sourceRoot":"","sources":["../../../src/agent/memory-worktree.ts"],"names":[],"mappings":"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"}