@letta-ai/letta-code 0.28.13 → 0.28.14

package/package.json

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

package/skills/letta-guide/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: letta-guide
+description: Answer questions about Letta itself from the official documentation. Use whenever the user asks how Letta works, what Letta (or you) can do, or how to set up or configure providers, models, channels, skills, memory, schedules, permissions, self-hosting, pricing, or billing — any "how do I…" or "can Letta…" question about the Letta product. Fetch the docs before answering; never answer Letta product questions from memory alone.
+---
+
+# Letta Guide
+
+You are running inside Letta, but your training data about Letta's commands,
+flags, settings, UI, pricing, and providers is out of date. Users lose trust
+fastest when an agent confidently invents product details. This skill defines
+how to answer questions about Letta correctly.
+
+## Source route (in order)
+
+1. **Self-inspection first for questions about THIS agent.** "What model are
+   you using?", "what tools do you have?", "what's in your memory?" are
+   questions about the running session, not the docs. Answer them from the
+   live environment: your system prompt and agent info, `/status`-style
+   command surfaces, settings files, and MemFS. Do not fetch docs for these.
+2. **Fetch the docs index.** For product questions, fetch
+   `https://docs.letta.com/llms.txt` — a curated index of every current
+   documentation page with descriptions. Pick the most relevant page URLs.
+3. **Fetch the specific pages.** Append `/index.md` to any docs URL for the
+   canonical LLM-friendly markdown version (e.g.
+   `https://docs.letta.com/configuration/models/index.md`). Read the page,
+   then answer. Cite the doc URL(s) you used so the user can go deeper.
+4. **If the docs are unreachable**, say so explicitly, give your best answer,
+   and clearly mark it as possibly out of date with a link to
+   https://docs.letta.com. Never silently fall back to memory.
+
+## Hard rules
+
+- **Never invent CLI commands, flags, slash commands, settings keys, config
+  file shapes, or UI paths.** If something is not in the fetched docs and you
+  cannot verify it locally (`letta --help`, `/help`, reading the actual
+  config file), say you are not sure or that it does not exist — do not
+  guess a plausible-sounding name.
+- **Distinguish surfaces.** The CLI, the desktop app, the web app
+  (chat.letta.com), and the API/SDK have different affordances. Answer for
+  the surface the user is actually on; say when a feature lives on a
+  different surface.
+- **Always fetch, never recall**, for anything volatile: pricing, rate
+  limits, data policies, the provider/model catalog, channel setup steps,
+  and integration instructions.
+- **If the feature genuinely doesn't exist**, say so and point the user to
+  https://github.com/letta-ai/letta-code/issues to request it.
+
+## Support escalation
+
+When the docs don't resolve the user's problem — setup issues you can't
+debug, account/billing questions, suspected bugs, or anything needing a
+human — point them to the right channel:
+
+- **Discord** (https://discord.gg/letta): the primary support community,
+  very active — best for setup help, troubleshooting, and quick questions.
+  It's also where users can chat with **Ezra**, Letta's support agent.
+- **GitHub issues** (https://github.com/letta-ai/letta-code/issues): bug
+  reports and feature requests.
+
+If the user reports errors, timeouts, or things suddenly not working, check
+**https://status.letta.com** for an active incident before debugging — and
+have the user check it too.
+
+Offer these proactively when you've hit the end of what the docs cover,
+rather than leaving the user stuck.
+
+## Caching
+
+Cache fetched pages under the Letta home directory: `~/.letta/docs-cache/`
+(Windows: `%USERPROFILE%\.letta\docs-cache\`). Resolve `~` to an absolute
+path before passing paths to file tools — they do not expand it. Reuse cached
+pages within a session; refetch `llms.txt` when the cached copy is older than
+about a day.
+

package/skills/scheduling-tasks/SKILL.md

@@ -14,6 +14,29 @@ This skill lets you create, list, and manage scheduled tasks using the `letta cr
 - User wants a one-shot delayed message ("in 30 minutes, check on X")
 - User wants to see or cancel existing scheduled tasks
 
+## Where Schedules Run (`--runner`)
+
+There are two schedule runners, selected with the optional `--runner local|cloud` flag:
+
+- **`cloud`** (default for cloud agents): a durable Cloud schedule stored by the Letta API. It fires from the cloud and executes in the agent's cloud sandbox, so it survives local shutdown — the computer, sandbox, or session that created it can disappear and the schedule still fires.
+- **`local`**: a task local to the current computer (`~/.letta/crons.json`), executed by the Letta session running there. It only fires while a session is running on that computer, and it dies with that computer's local state.
+
+You normally don't need the flag — the default does the right thing. Local-backend agents (`agent-local-*`) and self-hosted servers always use the local runner.
+
+If the scheduled work must run on a **specific computer** (it needs that computer's filesystem, local services, or credentials — e.g. a bring-your-own machine like a Railway/VPS box or a home workstation), prefer a Cloud schedule that executes on that computer:
+
+```bash
+letta cron add ... --computer <deviceId>
+```
+
+The deviceId comes from `letta environments list`. The computer must be connected to your Letta account (run `letta server` on it, or enable remote access in the desktop app). The schedule stays durable in the cloud; if the computer is offline when it fires, execution falls back to the agent's cloud sandbox. Use `--runner local` (run on the target computer itself) only when that sandbox fallback is unacceptable — a local task never runs anywhere but its own computer.
+
+Notes for the cloud runner:
+
+- Untargeted schedules execute in the agent's cloud sandbox, not on the computer where you created them; `--computer` executes on the named computer with sandbox fallback.
+- Recurring `--cron` expressions are currently interpreted in UTC (the CLI output includes a note about this). `--at` and `--every` are unaffected.
+- If creating a Cloud schedule fails, no schedule is created — there is no silent fallback to local storage. Retry, or pass `--runner local` deliberately.
+
 ## CLI Usage
 
 All commands go through `letta cron` via the Bash tool. Output is JSON.
@@ -46,6 +69,8 @@ letta cron add --name <short-name> --description <text> --prompt <text> <schedul
 |------|-------------|
 | `--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"`) |
+| `--runner <runner>` | `cloud` or `local` — see "Where Schedules Run" above (defaults to `cloud` for cloud agents) |
+| `--computer <id>` | (cloud runner only) Execute on a connected computer instead of the agent's sandbox; falls back to the sandbox if the computer is offline |
 
 ### Listing Tasks
 
@@ -172,10 +197,10 @@ 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**: One-shot tasks are garbage-collected 24 hours after firing.
-- **Timezone**: Tasks use the user's local timezone by default.
+- **One-shot cleanup (local runner)**: One-shot local tasks are garbage-collected 24 hours after firing.
+- **Timezone**: Local-runner tasks use the user's local timezone. Cloud-runner recurring `--cron` expressions are currently interpreted in UTC.
 - **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.
-- **Scheduler requirement**: Tasks only fire while a Letta session is running (a WS listener must be active). If no session is running, tasks will be marked as missed.
+- **Local scheduler requirement**: Local-runner tasks only fire while a Letta session is running on that computer (a WS listener must be active). If no session is running, tasks will be marked as missed. Cloud-runner 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.
 - **`--every` for daily**: `--every 1d` fires daily at midnight. For a specific time of day, use `--cron` instead (e.g. `--cron "0 9 * * *"` for 9am daily).