@letta-ai/letta-code 0.28.11 → 0.28.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.28.11",
+  "version": "0.28.12",
   "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/creating-mods/references/events.md

@@ -12,7 +12,7 @@ Use events when trusted local code should react to app/session changes or transf
 - Conversation status example
 - Rules
 
-This is the first slice of the hooks-v2 direction. The long-term goal is for typed mod events to replace settings-based hooks. Existing hooks still own blocking decisions and model feedback injection until each event has a typed return contract.
+Mod events are typed local extension points. Use the event's documented return contract for transformations, cancellation, or result replacement; otherwise treat the event as notification-only.
 
 ## Capabilities
 
@@ -124,7 +124,7 @@ Lifecycle handlers are notification-only and should not return values. `turn_sta
 }
 ```
 
-`tool_start` fires immediately before a client-side tool executes. This includes built-in tools, mod tools, and external tools executed through the local tool manager. It runs after permission/approval classification and before `PreToolUse` hooks, so trusted local mods can change the actual executed arguments after the approval UI has already classified the original request. Mod permission overlays are rechecked after `tool_start` on the final args.
+`tool_start` fires immediately before a client-side tool executes. This includes built-in tools, mod tools, and external tools executed through the local tool manager. It runs after permission/approval classification, so trusted local mods can change the actual executed arguments after the approval UI has already classified the original request. Mod permission overlays are rechecked after `tool_start` on the final args.
 
 Handlers can inspect `event.args`, mutate it directly, or return replacement args:
 
@@ -171,7 +171,7 @@ letta.events.on("tool_end", (event) => {
 });
 ```
 
-The first handler that returns a `result` wins; later handlers are shadowed. Only string results are surfaced — multimodal/image results pass through unchanged. `tool_end` is the trusted-local-mod equivalent of the `PostToolUse` / `PostToolUseFailure` hooks for observing and rewriting tool results.
+The first handler that returns a `result` wins; later handlers are shadowed. Only string results are surfaced — multimodal/image results pass through unchanged. Use `tool_end` when trusted local code should observe or rewrite tool results before the agent sees them.
 
 A handler can also react to a specific tool completing by adjusting conversation state. For example, switch model and reasoning effort when entering and exiting plan mode (`tool_end` fires only after the tool succeeds, so a denied approval won't switch):
 
@@ -359,6 +359,6 @@ export default function activate(letta) {
 ## Rules
 
 - Do not block user flow unless the event's typed contract explicitly supports blocking.
-- Do not use lifecycle events for safety decisions yet. Existing hooks still own blocking behavior.
+- Do not use lifecycle events for safety decisions. Use permission registration or an event contract that explicitly supports blocking.
 - Catch expected local errors if the user-facing outcome matters. Uncaught errors are isolated and recorded as mod diagnostics.
 - Return disposers from activation for event registrations, timers, subscriptions, and status values.

package/skills/self-configuration/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Letta, Inc.
+
+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/self-configuration/SKILL.md

@@ -0,0 +1,432 @@
+---
+name: self-configuration
+description: Modify Letta Code's own memory, model, context window, system prompt, compaction, permissions, toolsets, mods, skills, channels, schedules, and local runtime settings. Use when the user asks you to change how you behave or how the harness runs you.
+license: MIT
+---
+
+# Self-Configuration
+
+Use this skill when the user asks you to change yourself or the Letta Code runtime around you.
+
+The important part is choosing the right layer. Do not smear a preference into deterministic config, and do not bury a deterministic safety rule in prose memory.
+
+## First choose the layer
+
+| Layer | Use it for | How to change it |
+| --- | --- | --- |
+| Memory and identity | Durable facts, style preferences, persona changes, project knowledge, reusable skills | Edit `$MEMORY_DIR` files and sync the memory repo |
+| Server agent fields | Default model, model settings, context limit, system prompt, compaction, agent name, description | Patch `/v1/agents/{agent_id}` |
+| Server conversation fields | Temporary model/context experiments for one conversation | 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` |
+| 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 |
+| Schedules | Reminders and recurring prompts | Load `scheduling-tasks` and use `letta cron` |
+
+Decision rule: if the model should remember and reason about it, use memory. If the runtime must enforce it or route it before the model decides anything, use settings, API fields, mods, channels, or schedules.
+
+## Safe workflow
+
+1. Identify scope: current conversation, current agent, project, or global user config.
+2. Inspect current state first and save the relevant safe fields as a rollback patch. Do not copy secrets or full compiled prompts into backups.
+3. Prefer a dry run for API patches and scripts.
+4. Apply the smallest change that satisfies the request.
+5. Verify the effective state after the write.
+6. Tell the user what changed and whether a restart/new conversation is needed.
+
+Never print secrets. If inspecting env settings, list keys unless the user explicitly asks for values and the values are safe to reveal.
+
+## Guardrails are not security boundaries
+
+These helper scripts reduce accidental harm. They are not a security boundary against an agent with unrestricted Bash, raw curl/SDK access, API credentials, or filesystem access. `LETTA_API_KEY` and the installed CLI may have authority over other agents visible to the same account/server.
+
+Never target another agent or conversation unless explicitly directed and verified. If `AGENT_ID` or `CONVERSATION_ID` is set, the server-setting helpers reject mismatched live/GET operations unless `--allow-other-agent` is present. If the current env ID is absent, explicit IDs remain usable for out-of-band recovery.
+
+If a broken model or prompt prevents the agent from completing a turn, recover out of band from another shell or client with the CLI/API. Do not depend on the broken model to repair itself.
+
+## Inspect effective state before changing it
+
+Local settings, server state, and the current process are different sources of truth. Inspect the layer you intend to change before writing it.
+
+Start with the secret-safe local/runtime report:
+
+```bash
+python3 <SKILL_DIR>/scripts/show_config.py --cwd "$PWD"
+```
+
+Before changing server state, read the relevant scopes without printing full system prompts or credentials:
+
+```bash
+npx tsx <SKILL_DIR>/scripts/update-agent-settings.ts \
+  --target agent --agent-id "$AGENT_ID" --show
+
+npx tsx <SKILL_DIR>/scripts/update-agent-settings.ts \
+  --target conversation --conversation-id "$CONVERSATION_ID" --show
+```
+
+Do not infer an agent default from one conversation or infer a conversation override from the agent. Report both when diagnosing model or context differences.
+
+If CLI behavior does not match the docs, stop and inspect `command -v letta`, `type -a letta`, and `letta --version`. A stale or shadowed binary is a config bug, not a reason to guess.
+
+## Memory and identity
+
+Use memory when the user wants you to remember, prefer, learn, or change your identity/personality.
+
+Common files:
+
+| Path | Purpose |
+| --- | --- |
+| `$MEMORY_DIR/system/persona.md` | Identity, voice, behavioral defaults |
+| `$MEMORY_DIR/system/human.md` | Durable notes about the person you work with |
+| `$MEMORY_DIR/projects/` | Project-specific long-term context |
+| `$MEMORY_DIR/skills/` | Agent-owned reusable skills |
+| `$MEMORY_DIR/relationships/` | Durable relationship and collaboration notes |
+
+After changing memory, inspect and commit the exact changed files. Push/sync according to the current harness reminder or the `syncing-memory-filesystem` skill; some environments sync committed memory automatically.
+
+```bash
+cd "$MEMORY_DIR" && git status
+cd "$MEMORY_DIR" && git add <changed-files> && git commit --author="$AGENT_NAME <$AGENT_ID@letta.com>" -m "memory: <summary>"
+```
+
+Do not use API system-prompt replacement for ordinary learning. That can clobber the compiled prompt. Edit memory instead.
+
+## Server-side agent and conversation settings
+
+Server fields control model execution and agent metadata. Use the agent endpoint for persistent defaults. Use the conversation endpoint for scoped experiments.
+
+Required environment for live API writes:
+
+```bash
+export LETTA_API_KEY=...
+export AGENT_ID=agent-...
+export CONVERSATION_ID=conv-...   # only needed for conversation-scoped changes
+export LETTA_BASE_URL=...         # required; use the current server, not a hard-coded Cloud URL
+```
+
+The scripts in this skill default to `AGENT_ID`, `CONVERSATION_ID`, and `LETTA_BASE_URL`. Server reads and writes require `LETTA_BASE_URL` or explicit `--base-url`; they never silently fall back to `api.letta.com`. Keep `LETTA_BASE_URL` paired with the `LETTA_API_KEY` supplied by the current runtime so local, self-hosted, and non-default Cloud environments are not accidentally redirected. Pass explicit IDs when there is any doubt. `--show` fetches the selected agent or conversation and prints only safe effective fields. Server operations reject target IDs that differ from the current env ID unless `--allow-other-agent` is passed. Dry-run output is labeled: `offline_partial_patch` means no server state was fetched; `effective_merged_patch` means the script fetched current server state and shows the merged patch that would be sent.
+
+### Dry-runable update script
+
+```bash
+npx tsx <SKILL_DIR>/scripts/update-agent-settings.ts --help
+```
+
+Patch the current conversation first when testing a risky model/settings change:
+
+```bash
+npx tsx <SKILL_DIR>/scripts/update-agent-settings.ts \
+  --target conversation \
+  --conversation-id "$CONVERSATION_ID" \
+  --model "openai/gpt-5.2" \
+  --context-window-limit 64000 \
+  --dry-run
+```
+
+Patch the agent default after the user confirms the change should persist:
+
+```bash
+npx tsx <SKILL_DIR>/scripts/update-agent-settings.ts \
+  --target agent \
+  --agent-id "$AGENT_ID" \
+  --model "openai/gpt-5.2" \
+  --context-window-limit 64000
+```
+
+### Name and description
+
+Name and description are agent-level metadata. Do not pass them with `--target conversation`. Values must be non-empty; the helper does not clear metadata by accident.
+
+```bash
+npx tsx <SKILL_DIR>/scripts/update-agent-settings.ts \
+  --target agent \
+  --agent-id "$AGENT_ID" \
+  --name "repo-maintainer" \
+  --dry-run
+
+npx tsx <SKILL_DIR>/scripts/update-agent-settings.ts \
+  --target agent \
+  --agent-id "$AGENT_ID" \
+  --description "Maintains repository configuration and review-ready PRs." \
+  --dry-run
+```
+
+Do not patch `llm_config` directly. Use `model`, `context_window_limit`, and `model_settings`. For metadata, use `name` and `description`. Then read back the agent or conversation and verify the returned `llm_config.context_window`, `model_settings`, and metadata fields.
+
+### Model settings
+
+`model_settings` is usually replacement-style. Fetch the current object first and preserve fields you still need, or pass `--merge-model-settings`. Merge dry runs fetch current state and require `LETTA_API_KEY` because they preview preserved fields, not just the local patch fragment.
+
+```bash
+cat > /tmp/model-settings.json <<'JSON'
+{
+  "provider_type": "openai",
+  "parallel_tool_calls": true,
+  "reasoning": { "reasoning_effort": "medium" }
+}
+JSON
+
+npx tsx <SKILL_DIR>/scripts/update-agent-settings.ts \
+  --target agent \
+  --agent-id "$AGENT_ID" \
+  --model "openai/gpt-5.2" \
+  --model-settings-file /tmp/model-settings.json \
+  --merge-model-settings \
+  --dry-run
+```
+
+Provider reasoning fields differ. Read [`references/model-settings.md`](references/model-settings.md) before changing reasoning or provider-specific settings.
+
+### Compaction settings
+
+Compaction controls how old messages are summarized when context is evicted. Bad compaction prompts cause delayed, progressive context loss as future compactions discard useful state. Good ones preserve goals, files, commands, test results, blockers, and current state.
+
+Use the helper for prompt changes. Even `--dry-run` fetches current compaction settings so omitted fields are preserved in the preview. Live writes require `--confirm-compaction-prompt`.
+
+```bash
+npx tsx <SKILL_DIR>/scripts/update-compaction-prompt.ts \
+  --prompt-file /tmp/compaction-prompt.txt \
+  --mode self_compact_sliding_window \
+  --clip-chars 50000 \
+  --dry-run
+```
+
+Read [`references/compaction-prompt-patterns.md`](references/compaction-prompt-patterns.md) before drafting a new prompt.
+
+### System prompt replacement
+
+This is a sharp tool. A bad system prompt can self-brick the agent. Use it only when the user explicitly asks to replace the server-side system prompt or when repairing a known server-side prompt state. Live writes require `--confirm-system-replacement`; dry runs do not.
+
+```bash
+npx tsx <SKILL_DIR>/scripts/update-agent-settings.ts \
+  --target agent \
+  --agent-id "$AGENT_ID" \
+  --system-file /tmp/new-system-prompt.txt \
+  --dry-run
+```
+
+For normal behavioral changes, edit memory. For startup preset selection, use `--system <preset>` or `--system-custom <file>` when launching Letta Code.
+
+## Local settings files
+
+Settings scopes:
+
+| File | Scope | Typical contents |
+| --- | --- | --- |
+| `~/.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 |
+
+Precedence is local > project > user. Permission rule lists are merged; scalar settings usually override. When editing JSON directly, preserve unknown fields, keep the file schema-valid, and inspect the effective config afterward instead of rewriting the whole file from a guessed shape.
+
+Inspect merged local config and the current runtime with:
+
+```bash
+python3 <SKILL_DIR>/scripts/show_config.py --cwd "$PWD"
+python3 <SKILL_DIR>/scripts/show_config.py --cwd "$PWD" --json
+python3 <SKILL_DIR>/scripts/show_config.py --cwd "$PWD" --section runtime --json
+```
+
+Selected global settings keys:
+
+| Key | Meaning |
+| --- | --- |
+| `tokenStreaming` | Stream tokens in UI |
+| `reasoningTabCycleEnabled` | Let Tab cycle reasoning tiers when enabled |
+| `showCompactions` | Show compaction activity |
+| `sessionContextEnabled` | Send device/agent context at session start |
+| `autoConversationTitles` | Generate conversation titles |
+| `autoSwapOnQuotaLimit` | Auto-switch temporary model on quota errors |
+| `includeWorktreeTool` | Include worktree tool in toolsets |
+| `preferredBackendMode` | Startup backend preference, `api` or `local` |
+| `channelCredentialsStore` | Channel token storage, `file`, `keyring`, or `auto` |
+| `reflectionTrigger` / `reflectionStepCount` | Default reflection cadence |
+| `reflectionSettingsByAgent` | Per-agent reflection cadence |
+| `permissions` | Allow/deny/ask/alwaysAsk rules |
+| `env` | User-wide environment variables for Letta Code |
+| `experiments` | Feature flags |
+| `agents[]` | Per-agent pinned/memfs/toolset/system-prompt metadata |
+
+Per-agent `agents[]` entries are keyed by `agentId` plus server. For api.letta.com, `baseUrl` may be omitted. For another server, preserve the server key.
+
+Base URL resolution is split between runtime API calls and settings lookup. Runtime API calls require `LETTA_BASE_URL` or an explicit script `--base-url`; do not replace it with a hard-coded Cloud URL. Settings server keys resolve from `LETTA_SETTINGS_BASE_URL`, `env.LETTA_SETTINGS_BASE_URL`, `LETTA_BASE_URL`, `env.LETTA_BASE_URL`, then api.letta.com. Do not move `agents[]` entries across base URLs unless the user is deliberately migrating servers.
+
+Toolset values currently include `auto`, `default`, `codex`, `codex_snake`, `gemini`, `gemini_snake`, and `none`. Use `auto` unless the user explicitly wants a manual override.
+
+## Permissions
+
+Permissions decide whether tool calls are allowed, denied, or require approval. User/global permission rules affect all agents using that settings file: `allow` can weaken review, while `deny` and `alwaysAsk` can brick workflows. Valid modes are `standard`, `acceptEdits`, and `unrestricted`; legacy `default` maps to `standard`, while `bypassPermissions` and `fullAccess` map to `unrestricted`. The default mode is `unrestricted` unless startup flags or settings override it.
+
+The removed `memory` mode is invalid; memory access is governed by normal tool permissions plus the server/filesystem checks on the path used. These helper guardrails do not restrict raw Bash/API access. `permissions.mode` supplies a persisted startup default, rule lists still take precedence, and channel accounts have their own `defaultPermissionMode`. Inspect all three when channel approvals differ from the interactive CLI.
+
+Rule examples:
+
+```json
+{
+  "permissions": {
+    "mode": "standard",
+    "allow": ["Bash(git diff:*)", "Read(src/**)"],
+    "deny": ["Bash(rm -rf:*)"],
+    "ask": ["Write(**/*.md)"],
+    "alwaysAsk": ["Bash(git push:*)"]
+  }
+}
+```
+
+Rule types:
+
+| Type | Behavior |
+| --- | --- |
+| `allow` | Approve matching calls |
+| `deny` | Block matching calls |
+| `ask` | Request approval in normal permission modes |
+| `alwaysAsk` | Request approval even in unrestricted/yolo mode |
+
+Add a rule with the helper:
+
+```bash
+python3 <SKILL_DIR>/scripts/add_permission.py \
+  --rule "Bash(git push:*)" \
+  --type alwaysAsk \
+  --scope user \
+  --confirm-user-scope
+```
+
+`add_permission.py` only adds rules. Remove rules manually for now. User/global writes require `--confirm-user-scope`; use `--dry-run` to preview. Use project or local scope only when the current working directory is deliberately the project root.
+
+## Mods
+
+Use mods when the user wants deterministic runtime behavior that cannot be represented as a simple setting. Managed mods are global for the user install, not per-agent:
+
+- new tools or command adapters
+- slash commands
+- statusline rendering
+- local model/provider adapters
+- permission overlays for mod-provided tools
+- lightweight UI panels
+
+Load `creating-mods` before implementing mods. Load `customizing-commands` for slash commands and `customizing-statusline` for statusline work.
+
+Inspect and control managed mod packages with:
+
+```bash
+letta mods list
+letta mods disable <package-spec>
+letta mods enable <package-spec>
+letta mods remove <package-spec>
+```
+
+Run `/reload` in active sessions afterward. Loose source files and agent-scoped mods are not individually registry-toggleable; move, rename, or remove the file, or use `--no-mods` / `LETTA_DISABLE_MODS=1` to disable all mods for a new process.
+
+## Skills
+
+Use skills when the user wants you to become good at a repeatable workflow. Sources are discovered in this order:
+
+1. Project skills: `.agents/skills/` with `.skills/` as legacy fallback
+2. Agent skills: `$MEMORY_DIR/skills/`
+3. Global skills: `~/.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.
+
+## Provider connections
+
+Provider connection is agent-executable through `letta connect`. This is separate from `LETTA_API_KEY`, which authenticates Letta API requests. Provider connections may be visible to the same account/server; treat that as credential scope to verify, not as a critical exploit by itself.
+
+Inspect the installed command shape first:
+
+```bash
+letta connect --help
+letta connect <provider> --help
+```
+
+Use the provider-specific command supported by the installed binary. Current examples include:
+
+```bash
+letta connect chatgpt
+letta connect codex --method device-code
+letta connect lmstudio --base-url http://127.0.0.1:1234/v1 --timeout 600s
+letta connect bedrock --method profile --profile "$AWS_PROFILE" --region "$AWS_REGION"
+```
+
+Before connecting, verify whether the target agent/backend is API/Constellation or local. A provider saved to the wrong backend does not configure the current agent.
+
+Never print provider keys. Shell expansion such as `--api-key "$OPENAI_API_KEY"` still puts the resolved secret in process argv, where process listings may expose it. Prefer the command's interactive secret prompt in a trusted TTY. If no safer input path exists, stop for explicit user approval rather than passing a provider secret autonomously. Browser login, device-code confirmation, or account consent also requires human consent; do not claim success before it completes.
+
+After connecting, verify the provider/model from the same backend and process that will run the agent. Do not infer success from a saved credential alone.
+
+## Channels
+
+Use channels when the user wants to talk through Slack, Discord, Telegram, WhatsApp, or Signal.
+
+Useful commands:
+
+```bash
+letta channels status
+letta channels configure <channel>
+letta channels install <channel>
+letta channels route list --channel <channel>
+letta channels pair --channel <channel> --code <code> --agent <agent-id> --conversation <conversation-id>
+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.
+
+`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.
+
+Changing the credential-store mode does not migrate existing tokens. A file/keyring mismatch can make an otherwise configured listener fail with `invalid_auth`; verify where credentials are stored before changing the mode.
+
+## Schedules
+
+Use `scheduling-tasks` for reminders and recurring prompts. Under the hood it uses `letta cron`.
+
+Examples:
+
+```bash
+letta cron list
+letta cron add --name "weekly-review" --description "Weekly project review" --prompt "Ask the user for the weekly project review." --cron "0 9 * * 1" --agent "$AGENT_ID" --conversation "$CONVERSATION_ID"
+```
+
+Scheduled tasks fire only while a Letta session/listener is running. Cron bindings can target other agents/conversations visible to the account; verify agent and conversation IDs explicitly when exact routing matters.
+
+## CLI startup flags
+
+Some behavior is easiest to change at startup:
+
+```bash
+letta --model <model-id-or-handle>
+letta --system <preset-id>
+letta --system-custom /path/to/system.txt
+letta --toolset auto
+letta --permission-mode standard
+letta --skills /path/to/skills
+letta --skill-sources all,bundled,global,agent,project
+letta --pre-load-skills self-configuration,creating-mods
+letta --no-mods
+letta --reflection-trigger step-count --reflection-step-count 25
+letta --backend local
+letta --memfs
+```
+
+Startup flags affect a new process only. They do not rewrite an already-running listener. Persist durable defaults in settings or server fields instead.
+
+### Existing listeners and long-running processes
+
+Before starting, replacing, or stopping a listener, inspect existing Letta processes and determine ownership: interactive shell, Desktop, launchd/systemd, supervisor, or another agent.
+
+Do not start a second listener for the same channel accounts merely to apply new flags. Never stop or restart an existing listener without explicit coordination and user approval. Prefer changing the owned service configuration and then performing one approved restart.
+
+## References
+
+- [`references/api-patch-examples.md`](references/api-patch-examples.md) — manual API and SDK patch examples
+- [`references/model-settings.md`](references/model-settings.md) — provider-specific model settings shapes
+- [`references/compaction-prompt-patterns.md`](references/compaction-prompt-patterns.md) — compaction prompt templates
+
+## Helper scripts
+
+| Script | Purpose |
+| --- | --- |
+| `scripts/update-agent-settings.ts` | Show or patch agent/conversation server settings safely |
+| `scripts/update-compaction-prompt.ts` | Preserve existing compaction settings while replacing the prompt |
+| `scripts/add_permission.py` | Add allow/deny/ask/alwaysAsk rules to a chosen settings scope |
+| `scripts/show_config.py` | Show runtime/local settings without dumping secret values |

package/skills/self-configuration/references/api-patch-examples.md

@@ -0,0 +1,161 @@
+# API Patch Examples
+
+Raw curl and SDK calls bypass the helper guardrails. They are useful for recovery, but they are not safer. Use `LETTA_BASE_URL` together with the current runtime's `LETTA_API_KEY`; never hard-code `api.letta.com` or let an SDK default redirect a local/self-hosted agent to Cloud. Verify the target agent/conversation ID, remember that the key may authorize other agents visible to the same account/server, and never paste literal secrets into commands or source files.
+
+## General updater script
+
+Use `scripts/update-agent-settings.ts` for dry-runable patches.
+
+```bash
+npx tsx <SKILL_DIR>/scripts/update-agent-settings.ts --help
+```
+
+Examples:
+
+```bash
+# Agent context window
+npx tsx <SKILL_DIR>/scripts/update-agent-settings.ts \
+  --target agent \
+  --context-window-limit 64000 \
+  --dry-run
+
+# Conversation context window
+npx tsx <SKILL_DIR>/scripts/update-agent-settings.ts \
+  --target conversation \
+  --conversation-id "$CONVERSATION_ID" \
+  --context-window-limit 64000
+
+# Agent rename and description update; values must be non-empty
+npx tsx <SKILL_DIR>/scripts/update-agent-settings.ts \
+  --target agent \
+  --agent-id "$AGENT_ID" \
+  --name "repo-maintainer" \
+  --description "Maintains repository configuration and review-ready PRs." \
+  --dry-run
+
+# Persistent model update, preserving current model_settings and merging a JSON patch
+cat >/tmp/model-settings.json <<'JSON'
+{
+  "provider_type": "openai",
+  "parallel_tool_calls": true,
+  "reasoning": { "reasoning_effort": "medium" }
+}
+JSON
+npx tsx <SKILL_DIR>/scripts/update-agent-settings.ts \
+  --target agent \
+  --model openai/gpt-5.2 \
+  --model-settings-file /tmp/model-settings.json \
+  --merge-model-settings
+
+# System prompt replacement from file; can self-brick the agent
+npx tsx <SKILL_DIR>/scripts/update-agent-settings.ts \
+  --target agent \
+  --system-file /tmp/new-system-prompt.txt \
+  --confirm-system-replacement
+```
+
+## Manual curl with preserved compaction settings
+
+Bad compaction prompts cause delayed context loss. Confirm the target agent. The `curl` header form below can expose `LETTA_API_KEY` to process-list readers on some systems; prefer a trusted shell and keep secrets out of logs and committed files.
+
+```bash
+prompt_file=/tmp/compaction-prompt.txt
+base_url="${LETTA_BASE_URL%/}"
+current=$(curl -sS "$base_url/v1/agents/$AGENT_ID" \
+  -H "Authorization: Bearer $LETTA_API_KEY")
+
+jq -n \
+  --arg prompt "$(cat "$prompt_file")" \
+  --argjson current "$(printf '%s' "$current" | jq '.compaction_settings // {}')" \
+  '{ compaction_settings: ($current + {
+      mode: "self_compact_sliding_window",
+      prompt: $prompt,
+      clip_chars: 50000
+  }) }' > /tmp/compaction-patch.json
+
+curl -sS -X PATCH "$base_url/v1/agents/$AGENT_ID" \
+  -H "Authorization: Bearer $LETTA_API_KEY" \
+  -H "Content-Type: application/json" \
+  --data-binary @/tmp/compaction-patch.json
+```
+
+## TypeScript SDK
+
+SDK calls use the same account token authority as raw API calls. Check IDs before update calls; do not hard-code provider keys or other secrets in the patch body.
+
+```typescript
+import Letta from "@letta-ai/letta-client";
+
+const client = new Letta({
+  apiKey: process.env.LETTA_API_KEY!,
+  baseURL: process.env.LETTA_BASE_URL!,
+});
+
+await client.agents.update(process.env.AGENT_ID!, {
+  model: "openai/gpt-5.2",
+  contextWindowLimit: 64000,
+  modelSettings: {
+    providerType: "openai",
+    parallelToolCalls: true,
+    reasoning: { reasoningEffort: "medium" },
+  },
+});
+```
+
+## Python SDK
+
+The Python client also bypasses helper mismatch and confirmation checks. Use it only after explicit target verification.
+
+```python
+import os
+from letta_client import Letta
+
+client = Letta(
+    api_key=os.environ["LETTA_API_KEY"],
+    base_url=os.environ["LETTA_BASE_URL"],
+)
+client.agents.update(
+    agent_id=os.environ["AGENT_ID"],
+    model="openai/gpt-5.2",
+    context_window_limit=64000,
+    model_settings={
+        "provider_type": "openai",
+        "parallel_tool_calls": True,
+        "reasoning": {"reasoning_effort": "medium"},
+    },
+)
+
+client.conversations.update(
+    conversation_id=os.environ["CONVERSATION_ID"],
+    context_window_limit=64000,
+)
+```
+
+## TypeScript fetch
+
+Fetch is raw API access. Recreate the same checks manually: current target ID, intended scope, no literal secrets, and an explicit human-approved plan for system or compaction prompt replacement.
+
+```typescript
+const baseUrl = process.env.LETTA_BASE_URL!;
+const agentId = process.env.AGENT_ID!;
+const apiKey = process.env.LETTA_API_KEY!;
+
+await fetch(`${baseUrl}/v1/agents/${agentId}`, {
+  method: "PATCH",
+  headers: {
+    Authorization: `Bearer ${apiKey}`,
+    "Content-Type": "application/json",
+  },
+  body: JSON.stringify({
+    name: "repo-maintainer",
+    description: "Maintains repository configuration and review-ready PRs.",
+    model: "openai/gpt-5.2",
+    context_window_limit: 272000,
+    model_settings: {
+      provider_type: "openai",
+      parallel_tool_calls: true,
+      reasoning: { reasoning_effort: "medium" },
+    },
+  }),
+});
+```