@letta-ai/letta-code 0.27.23 → 0.27.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.27.23",
+  "version": "0.27.25",
   "description": "Letta Code is a CLI tool for interacting with stateful Letta agents from the terminal.",
   "type": "module",
   "packageManager": "bun@1.3.0",
@@ -97,6 +97,7 @@
     "check:filename-casing": "node scripts/check-filename-casing.js",
     "check:test-mock-isolation": "bun run scripts/check-test-mock-isolation.js",
     "check:test-coverage": "node scripts/check-test-coverage.cjs",
+    "check:skill-frontmatter": "node scripts/check-skill-frontmatter.js",
     "check:bundled-skill-scripts": "node scripts/check-bundled-skill-scripts.js",
     "check": "bun run scripts/check.js",
     "dev": "node scripts/dev.cjs",

package/scripts/check-skill-frontmatter.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+
+const isStagedOnly = process.argv.includes("--staged");
+
+function git(args) {
+  const result = spawnSync("git", args, {
+    cwd: process.cwd(),
+    encoding: "utf8",
+    maxBuffer: 20 * 1024 * 1024,
+  });
+
+  if (result.status !== 0) {
+    throw new Error(
+      (result.stderr || result.stdout || "git command failed").trim(),
+    );
+  }
+
+  return result.stdout;
+}
+
+function splitNul(output) {
+  return output.split("\0").filter(Boolean);
+}
+
+function isSkillMarkdownFile(file) {
+  return file.split(/[\\/]/).pop() === "SKILL.md";
+}
+
+function getCandidateFiles() {
+  if (isStagedOnly) {
+    return splitNul(
+      git(["diff", "--cached", "--name-only", "--diff-filter=ACMR", "-z"]),
+    ).filter(isSkillMarkdownFile);
+  }
+
+  return splitNul(git(["ls-files", "-z"])).filter(isSkillMarkdownFile);
+}
+
+function readStagedFile(file) {
+  return git(["show", `:${file}`]);
+}
+
+function readCurrentFile(file) {
+  if (!existsSync(file)) {
+    return null;
+  }
+  return readFileSync(file, "utf8");
+}
+
+function checkSkillFrontmatterName(content) {
+  const normalized = content.replace(/^\uFEFF/, "").replace(/\r\n/g, "\n");
+  const match = normalized.match(/^---\n([\s\S]*?)\n---(?:\n|$)/);
+  if (!match) {
+    return "missing YAML frontmatter";
+  }
+
+  const frontmatter = match[1] ?? "";
+  const nameLine = frontmatter
+    .split("\n")
+    .find((line) => /^\s*name\s*:/.test(line));
+
+  if (!nameLine) {
+    return "missing name frontmatter";
+  }
+
+  const nameValue = nameLine.replace(/^\s*name\s*:\s*/, "").trim();
+  if (!nameValue) {
+    return "empty name frontmatter";
+  }
+
+  return null;
+}
+
+let violations = [];
+let files = [];
+try {
+  files = getCandidateFiles();
+  violations = files.flatMap((file) => {
+    const content = isStagedOnly ? readStagedFile(file) : readCurrentFile(file);
+    if (content === null) {
+      return [];
+    }
+
+    const reason = checkSkillFrontmatterName(content);
+    return reason ? [{ file, reason }] : [];
+  });
+} catch (error) {
+  console.error(
+    `Failed to check skill frontmatter: ${error instanceof Error ? error.message : String(error)}`,
+  );
+  process.exit(1);
+}
+
+if (violations.length > 0) {
+  console.error("\n❌ Skill frontmatter violations found:\n");
+  for (const violation of violations) {
+    console.error(`${violation.file}`);
+    console.error(`  ${violation.reason}`);
+    console.error(
+      "  ↳ Add a non-empty `name:` field to SKILL.md frontmatter.\n",
+    );
+  }
+  console.error(
+    `Found ${violations.length} skill frontmatter violation${violations.length === 1 ? "" : "s"}.`,
+  );
+  process.exit(1);
+}
+
+if (!isStagedOnly) {
+  console.log(
+    `✅ Skill frontmatter name headers present (${files.length} SKILL.md file${files.length === 1 ? "" : "s"}).`,
+  );
+}

package/scripts/check.js

@@ -19,6 +19,7 @@ const checks = [
   { name: "filename casing", script: ["check:filename-casing"] },
   { name: "test mock isolation", script: ["check:test-mock-isolation"] },
   { name: "test coverage", script: ["check:test-coverage"] },
+  { name: "skill frontmatter", script: ["check:skill-frontmatter"] },
   { name: "bundled skill scripts", script: ["check:bundled-skill-scripts"] },
   { name: "biome", script: ["lint"] },
   { name: "typescript", script: ["typecheck"] },

package/skills/context-doctor/SKILL.md

@@ -116,7 +116,8 @@ Review changes, then commit with a descriptive message:
 cd $MEMORY_DIR
 git status                # Review what changed before staging
 git add <specific files>  # Stage targeted paths — avoid blind `git add -A`
-git commit --author="<AGENT_NAME> <<ACTUAL_AGENT_ID>@letta.com>" -m "fix(doctor): <summary> 🏥
+author_name="${AGENT_NAME:-$AGENT_ID}"
+git commit --author="$author_name <$AGENT_ID@letta.com>" -m "fix(doctor): <summary> 🏥
 
 <identified issues and implemented solutions>"
 

package/skills/creating-mods/SKILL.md

@@ -155,7 +155,7 @@ Before finishing, verify:
 | `references/providers.md` | Adding a custom model/API provider for local agents |
 | `references/events.md` | Reacting to lifecycle/tool/turn events or transforming turns/tools |
 | `references/permissions.md` | Enforcing dynamic tool allow/ask/deny policy before approval/execution |
-| `references/ui.md` | Panels (including order-0 statusline) or `ui.panels` capability guards are involved |
+| `references/ui.md` | Panels (including order-0 statusline and order-1 dreaming indicator) or `ui.panels` capability guards are involved |
 | `references/plan-mode.md` | Recreating plan mode with commands, tools, events, permissions, and local state |
 | `references/analysis-mode.md` | Phrase-triggered diagnostic mode with turn reminders (simpler than plan-mode) |
 | `references/architecture.md` | Multiple capabilities, local state, cleanup, background model work, or non-trivial composition |

package/skills/creating-mods/references/ui.md

@@ -38,7 +38,7 @@ if (letta.capabilities.ui.panels) {
 `order` is a signed coordinate around the input:
 
 - `order > 1` — additive panels above the input, higher nearer the top (default `100`).
-- `order === 1` — replaces the default product-status row (currently dreaming/reflection status). Use this only when intentionally overriding that row; otherwise use `order > 1`.
+- `order === 1` — replaces the default dreaming/reflection indicator above the input. Use this only when intentionally overriding that row; otherwise use `order > 1`.
 - `order === 0` — the primary line just below the input, overriding the built-in `agent · model`. This is the statusline slot; use `customizing-statusline` for that work.
 - `order < 0` — stacks below the primary line, `-1` closest.
 
@@ -51,6 +51,12 @@ render(ctx: {
   width: number;
   agent: { id, name };
   model: { id, displayName, provider, reasoningEffort };
+  backgroundAgents: Array<{
+    type: string;
+    status: string;
+    durationMs: number;
+    agentId: string | null;
+  }>;
   subagents: { list(): SubagentLifecycleItem[] };
   row(left, right, width): string;
   columns(parts: string[], width): string;
@@ -63,6 +69,39 @@ render(ctx: {
 
 Close panels when they are transient, and close/replace long-lived panels from the activation disposer if reload should remove them.
 
+### Panel use case: dreaming indicator overrides
+
+When a user asks to change the "dreaming" UI/indicator, the reflection status above the input, or to add the full background-agent URL, use an `order: 1` panel replacement. The user should not need to know any internal row/component name.
+
+Checklist:
+
+- Open a panel with `order: 1`, not an additive panel.
+- Read active hidden background agents from `ctx.backgroundAgents`; filter by `status` (`pending`/`running`).
+- Use `agent.agentId` to build `https://app.letta.com/chat/${agent.agentId}`.
+- If the user asks for the full URL, render visible text; do not use `ctx.link()` because it hides the URL behind OSC-8.
+- If preserving animation, own the timer and call `panel.update()`; clean up timer and panel in the disposer.
+- Keep `render()` pure: do not call diagnostics or mutate external state from render.
+
+Critical shape:
+
+```ts
+const panel = letta.ui.openPanel({
+  id: "dreaming-url",
+  order: 1,
+  render(ctx) {
+    const agent = ctx.backgroundAgents.find(
+      (a) => a.status === "pending" || a.status === "running",
+    );
+    if (!agent) return "";
+
+    const url = agent.agentId
+      ? `https://app.letta.com/chat/${agent.agentId}`
+      : null;
+    // Render spinner/label/elapsed, plus visible URL if requested.
+  },
+});
+```
+
 ### Commands that open panels
 
 If a command's `run()` opens a panel, guard the command **registration** on `letta.capabilities.ui.panels` — not just the `openPanel` call:

package/skills/initializing-memory/SKILL.md

@@ -706,7 +706,8 @@ Check if they're satisfied or want further refinement. Then commit and push memo
 cd $MEMORY_DIR
 git status                # Review what changed before staging
 git add <specific files>  # Stage targeted paths — avoid blind `git add -A`
-git commit --author="<AGENT_NAME> <<ACTUAL_AGENT_ID>@letta.com>" -m "feat(init): <summary> ✨
+author_name="${AGENT_NAME:-$AGENT_ID}"
+git commit --author="$author_name <$AGENT_ID@letta.com>" -m "feat(init): <summary> ✨
 
 <what was initialized and key decisions made>"