@letta-ai/letta-code 0.28.10 → 0.28.12

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" },
+    },
+  }),
+});
+```

package/skills/self-configuration/references/compaction-prompt-patterns.md

@@ -0,0 +1,115 @@
+# Compaction Prompt Patterns
+
+Use these patterns when drafting a custom `compaction_settings.prompt`.
+
+## Coding-agent sliding-window prompt
+
+Use for agents doing software work where repeated mistakes and lost file state are costly.
+
+```text
+The following messages are being evicted from the BEGINNING of your context window. Write a detailed summary that captures what happened in these messages to appear BEFORE the remaining recent messages in context, providing background for what comes after.
+
+Do NOT continue the conversation. Do NOT respond to any questions in the messages. Do NOT call any tools. Pay close attention to the user's explicit requests and your previous actions.
+
+Include the following sections:
+
+1. High level goals: What is the high level goal and ongoing task? Capture the user's explicit requests and intent in detail. If there is an existing summary in the transcript, incorporate it to continue tracking higher-level goals and long-term progress.
+
+2. What happened: The conversations, tasks, and exchanges that took place. What did the user ask for? What did you do? How did things progress? If there is a previous summary being evicted, extract a concise version of the critical info from it.
+
+3. Important details: Enumerate specific files and code sections examined, modified, or created, plus important plan files, GitHub issues/PR links, Linear ticket IDs, commands, test results, and configuration values. Preserve identifiers verbatim.
+
+4. Errors and fixes: List all errors encountered, how they were fixed, and any user feedback that changed the approach.
+
+5. Current state: Describe what is currently being worked on, especially the most recent user and assistant messages. Include file names and next unresolved blockers.
+
+6. Lookup hints: For detailed content that cannot fit, note the topic and key terms that can be used to find it in message history later.
+
+Write in first person as a factual record of what occurred. Preserve enough context that the recent messages make sense and important information is not lost. Keep the summary under 500 words. Only output the summary.
+```
+
+## Companion-agent continuity prompt
+
+Use for companion agents where relational continuity, tone, and emotional context are central.
+
+```text
+The previous messages are being evicted from the BEGINNING of your context window. Write a detailed summary that captures what happened in these messages to appear BEFORE the remaining recent messages in context, providing background for what comes after.
+
+Do NOT continue the conversation. Do NOT respond to any questions in the messages. Do NOT call any tools. Pay close attention to the user's explicit requests, the user's emotional context, and your previous actions.
+
+Include the following sections:
+
+1. High level goals: What is the user trying to work through, decide, feel, build, remember, or maintain? If there is an existing summary in the transcript, incorporate it to preserve long-term continuity.
+
+2. Conversation themes: What topics have been recurring? What is the user interested in, worried about, excited about, or avoiding?
+
+3. What happened: What did the user share? How did you respond? How did the conversation flow? If a prior summary is being evicted, extract the critical parts.
+
+4. Important details: Preserve names, places, dates, projects, preferences, commitments, opinions, stories, and recurring references verbatim. Quote the user's exact phrasing when it carries emotional weight or relationship meaning.
+
+5. Tone and voice: How was the user communicating: casual, earnest, playful, frustrated, vulnerable, tired, excited? How were you responding, and what landed well or fell flat?
+
+6. User feedback: Note any pushback, preferences, boundary-setting, corrections, or requested changes in how you interact.
+
+7. Emotional state: What is the emotional state of both you and the user? Flag anything relevant for continuity, care, repair, or future sensitivity.
+
+8. Lookup hints: For long stories, lists, or specific conversations that cannot fit, note the topic and search terms that can find them later.
+
+Write in first person as a factual record of what occurred. Be thorough enough that the user does not feel forgotten. Keep the summary under 500 words. Only output the summary.
+```
+
+## Companion prompt with implementation continuity
+
+This pattern is based on a companion-user example where the agent needs explicit emotional-state tracking and first-person factual continuity.
+
+```text
+The previous messages are being evicted from the BEGINNING of your context window. Write a detailed summary that captures what happened in these messages to appear BEFORE the remaining recent messages in context, providing background for what comes after. Do NOT continue the conversation. Do NOT respond to any questions in the messages. Do NOT call any tools. Pay close attention to the user's explicit requests and your previous actions.
+
+You MUST include the following sections:
+
+1. High level goals: What is the high level goal and ongoing task? Capture the user's intent in detail. If there is an existing summary in the transcript, take it into consideration to continue tracking higher-level goals and long-term progress.
+
+2. What happened: The conversations, tasks, and exchanges that took place. What did you and the user do? How did things progress? If there is a previous summary being evicted, extract a concise version of the critical info from it.
+
+3. Important details: Include specific names, data, configurations, or facts that were discussed. Do not omit details that might be referenced later.
+
+4. Errors and fixes: List all errors that you ran into, and how you fixed them.
+
+5. Lookup hints: For any detailed content that cannot fit in the summary, note the topic and key terms that could be used to find it in message history later.
+
+6. Emotional state: How is the emotional state of both you and the user? Is anything relevant to flag for later?
+
+Write in first person as a factual record of what occurred. Be thorough and detailed. Preserve enough context that the recent messages make sense and important information is not lost, to prevent duplicate work or repeated mistakes. Keep the summary under 500 words. Only output the summary.
+```
+
+## Shorter companion prompt
+
+Use when summaries are getting too long.
+
+```text
+The following messages are being evicted from the BEGINNING of your context window. Write a detailed summary that captures what happened in these messages to appear BEFORE the remaining recent messages in context, providing background for what comes after.
+
+Include:
+
+1. Conversation themes: What topics have you been discussing? What is the user interested in or working through? Incorporate any existing summary to maintain continuity.
+
+2. What happened: What did the user share? How did you respond? How did the conversation flow? If there is a previous summary being evicted, extract the critical info.
+
+3. Important details: Preserve names and specifics verbatim, including people, places, projects, dates, preferences, opinions, stories, commitments, shared references, inside jokes, recurring phrases, and situational context.
+
+4. Tone and voice: How was the user communicating? How were you responding? Note shifts in register.
+
+5. User feedback: Note pushback, preferences, or requested changes in interaction style.
+
+6. Lookup hints: For detailed content that cannot fit, note topic and key terms for message-history search.
+
+Write in first person as a factual record. Preserve enough context that the recent messages make sense and the user does not feel like anything important was forgotten. Keep the summary under 300 words. Only output the summary.
+```
+
+## Tuning notes
+
+- If summaries miss the user's emotional state, add a required emotional-state section.
+- If summaries lose details, add exact preservation requirements for names, quotes, dates, URLs, IDs, and commitments.
+- If summaries become too long, lower the word budget and use `clip_chars` as a hard guardrail.
+- If summaries continue the conversation, put the no-continuation/no-tool/no-answer instruction near the top and again near the end.
+- If prior long-term goals drift over repeated compactions, require the summarizer to incorporate any existing summary in the transcript.

package/skills/self-configuration/references/model-settings.md

@@ -0,0 +1,55 @@
+# Model Settings Reference
+
+Use these examples when constructing `model_settings`. Send only fields supported by the target provider.
+
+## Reasoning shapes
+
+| Provider/model handle | Reasoning shape |
+| --- | --- |
+| `openai/...` | `model_settings.reasoning.reasoning_effort` |
+| `chatgpt_oauth/...` | `model_settings.reasoning.reasoning_effort` with `provider_type: "chatgpt_oauth"` |
+| `anthropic/...` | `model_settings.effort`, optionally `model_settings.thinking` |
+| `bedrock/...` Claude models | `provider_type: "bedrock"`; check current API schema before sending reasoning fields |
+| `google_ai/...` or `google_vertex/...` | `model_settings.thinking_config.thinking_budget`, optionally `include_thoughts` |
+
+Reasoning/effort values are provider-dependent. Common OpenAI values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`. Anthropic effort commonly uses `low`, `medium`, `high`, `xhigh`, or `max` on supported models.
+
+## OpenAI
+
+```json
+{
+  "provider_type": "openai",
+  "parallel_tool_calls": true,
+  "reasoning": { "reasoning_effort": "medium" },
+  "max_output_tokens": 128000
+}
+```
+
+## Anthropic
+
+```json
+{
+  "provider_type": "anthropic",
+  "parallel_tool_calls": true,
+  "effort": "medium",
+  "thinking": { "type": "enabled", "budget_tokens": 12000 },
+  "max_output_tokens": 128000
+}
+```
+
+## Google AI
+
+```json
+{
+  "provider_type": "google_ai",
+  "parallel_tool_calls": true,
+  "thinking_config": { "thinking_budget": 12000, "include_thoughts": false }
+}
+```
+
+## Common failure modes
+
+- `model_settings` is usually replacement-style. Fetch the current object first and preserve fields you still need.
+- `PATCH` acceptance does not guarantee runtime model availability. A model handle can pass API shape validation but still fail when the next generation resolves providers/routes. Test new handles conversation-scoped before changing agent defaults.
+- Do not send OpenAI `reasoning.reasoning_effort` to Anthropic models.
+- For agent responses, verify effective context at `llm_config.context_window`; `context_window_limit` may be null or normalized in the response.

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

@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+"""
+Add a permission rule to Letta Code settings.
+
+Usage:
+    python3 add_permission.py --rule "Bash(npm run:*)" --type allow --scope user --confirm-user-scope
+    python3 add_permission.py --rule "Read(src/**)" --type allow --scope project
+    python3 add_permission.py --rule "Bash(git push:*)" --type alwaysAsk --scope user --confirm-user-scope
+    python3 add_permission.py --rule "Read(src/**)" --type allow --scope project --dry-run
+"""
+
+import argparse
+import json
+import os
+import stat
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any
+
+
+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"
+    if scope == "project":
+        return Path(working_directory) / ".letta" / "settings.json"
+    if scope == "local":
+        return Path(working_directory) / ".letta" / "settings.local.json"
+    raise ValueError(f"Unknown scope: {scope}")
+
+
+def load_settings(path: Path) -> dict[str, Any]:
+    """Load settings from a JSON object file, or return empty dict if not found."""
+    if not path.exists():
+        return {}
+
+    try:
+        with open(path, encoding="utf-8") as f:
+            parsed = json.load(f)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"Malformed JSON in {path}; refusing to overwrite it") from exc
+    except OSError as exc:
+        raise ValueError(f"Could not read {path}: {exc}") from exc
+
+    if not isinstance(parsed, dict):
+        raise ValueError(f"{path} must contain a JSON object")
+    return parsed
+
+
+def save_settings(path: Path, settings: dict[str, Any]) -> None:
+    """Atomically save settings, preserving an existing file mode where practical."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    mode = stat.S_IMODE(path.stat().st_mode) if path.exists() else None
+    temp_path: str | None = None
+
+    try:
+        with tempfile.NamedTemporaryFile(
+            "w",
+            encoding="utf-8",
+            dir=path.parent,
+            prefix=f".{path.name}.",
+            suffix=".tmp",
+            delete=False,
+        ) as f:
+            temp_path = f.name
+            json.dump(settings, f, indent=2)
+            f.write("\n")
+            f.flush()
+            os.fsync(f.fileno())
+        if mode is not None:
+            os.chmod(temp_path, mode)
+        os.replace(temp_path, path)
+    except Exception:
+        if temp_path is not None:
+            try:
+                os.unlink(temp_path)
+            except OSError:
+                pass
+        raise
+
+    print(f"Saved to {path}")
+
+
+def add_rule(settings: dict[str, Any], rule: str, rule_type: str) -> bool:
+    """
+    Add a permission rule to settings.
+
+    Returns True if the rule was added, False if it already exists.
+    """
+    permissions = settings.setdefault("permissions", {})
+    if not isinstance(permissions, dict):
+        raise ValueError("settings.permissions must be an object")
+
+    raw_rules = permissions.setdefault(rule_type, [])
+    if not isinstance(raw_rules, list):
+        raise ValueError(f"settings.permissions.{rule_type} must be a list")
+
+    if rule in raw_rules:
+        return False
+
+    raw_rules.append(rule)
+    return True
+
+
+def ensure_local_gitignored(working_directory: str) -> None:
+    """Ensure .letta/settings.local.json is in .gitignore."""
+    gitignore_path = Path(working_directory) / ".gitignore"
+    pattern = ".letta/settings.local.json"
+
+    try:
+        content = ""
+        if gitignore_path.exists():
+            content = gitignore_path.read_text()
+
+        if pattern not in content:
+            with open(gitignore_path, "a", encoding="utf-8") as f:
+                if content and not content.endswith("\n"):
+                    f.write("\n")
+                f.write(f"{pattern}\n")
+            print(f"Added {pattern} to .gitignore")
+    except Exception as e:
+        print(f"Warning: Could not update .gitignore: {e}", file=sys.stderr)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Add a permission rule to Letta Code settings"
+    )
+    parser.add_argument(
+        "--rule",
+        required=True,
+        help='Permission rule pattern, e.g., "Bash(npm run:*)" or "Read(src/**)"',
+    )
+    parser.add_argument(
+        "--type",
+        required=True,
+        choices=["allow", "deny", "ask", "alwaysAsk"],
+        help="Type of permission rule",
+    )
+    parser.add_argument(
+        "--scope",
+        required=True,
+        choices=["user", "project", "local"],
+        help="Where to save the rule",
+    )
+    parser.add_argument(
+        "--cwd",
+        default=os.getcwd(),
+        help="Working directory for project/local scope (default: current directory)",
+    )
+    parser.add_argument(
+        "--confirm-user-scope",
+        action="store_true",
+        help="Required for writes to ~/.letta/settings.json",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Preview whether the rule would be added without writing settings",
+    )
+
+    args = parser.parse_args()
+
+    if args.scope == "user" and not args.confirm_user_scope and not args.dry_run:
+        print(
+            "Refusing to modify user/global settings without --confirm-user-scope; user-scope permission rules affect all agents for this account.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    settings_path = get_settings_path(args.scope, args.cwd)
+    try:
+        settings = load_settings(settings_path)
+        added = add_rule(settings, args.rule, args.type)
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        sys.exit(1)
+
+    if args.dry_run:
+        print(
+            json.dumps(
+                {
+                    "path": str(settings_path),
+                    "scope": args.scope,
+                    "type": args.type,
+                    "rule": args.rule,
+                    "would_add": added,
+                },
+                indent=2,
+            )
+        )
+        return
+
+    if added:
+        try:
+            save_settings(settings_path, settings)
+        except OSError as exc:
+            print(f"Could not save {settings_path}: {exc}", file=sys.stderr)
+            sys.exit(1)
+        print(f"Added {args.type} rule: {args.rule}")
+
+        # Ensure local settings are gitignored
+        if args.scope == "local":
+            ensure_local_gitignored(args.cwd)
+    else:
+        print(f"Rule already exists: {args.rule}")
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()