@letta-ai/letta-code 0.27.24 → 0.27.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.27.24",
+  "version": "0.27.26",
   "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/messaging-agents/SKILL.md

@@ -66,11 +66,24 @@ Results include `agent_id` for each matching message.
 letta -p --from-agent $LETTA_AGENT_ID --agent <id> "message text"
 ```
 
+When no `--environment` is specified, the target agent will run in the same
+environment as the caller agent.
+
+To route the target agent turn through a specific remote/local environment:
+
+```bash
+letta -p --from-agent $LETTA_AGENT_ID \
+  --agent <id> \
+  --environment <name-or-device-id-or-connection-id> \
+  "message text"
+```
+
 **Arguments:**
 | Arg | Required | Description |
 |-----|----------|-------------|
 | `--agent <id>` | Yes | Target agent ID to message |
 | `--from-agent <id>` | Yes | Sender agent ID (injects agent-to-agent system reminder) |
+| `--environment <selector>` | No | Route through an online environment by connection name, device ID, or connection ID |
 | `"message text"` | Yes | Message body (positional after flags) |
 
 **Example:**
@@ -96,6 +109,35 @@ letta -p --from-agent $LETTA_AGENT_ID \
 letta -p --from-agent $LETTA_AGENT_ID --conversation <id> "message text"
 ```
 
+Add `--environment <selector>` to continue the conversation on a specific environment.
+
+### Discovering Environments
+
+```bash
+letta environments list --online-only
+# alias:
+letta envs list --online-only
+```
+
+Use `connectionName`, `deviceId`, or `connectionId` from the JSON output as the
+`--environment` selector. If a name is ambiguous, prefer `deviceId` or
+`connectionId`. In `environments list`, the current local runtime is marked with
+`"isCurrent": true`.
+
+To force the target agent onto the current registered Letta Code environment,
+resolve the current environment and pass its `connectionId`:
+
+```bash
+CURRENT_ENV=$(letta environments current | jq -r .connectionId)
+letta -p --from-agent $LETTA_AGENT_ID \
+  --agent agent-abc123 \
+  --environment "$CURRENT_ENV" \
+  "Run on my same machine/environment."
+```
+
+Omit `--environment` when you want the target agent to run in the same
+environment as the caller agent.
+
 **Arguments:**
 | Arg | Required | Description |
 |-----|----------|-------------|
@@ -112,7 +154,8 @@ letta -p --from-agent $LETTA_AGENT_ID \
 
 ## Understanding the Response
 
-- Scripts return only the **final assistant message** (not tool calls or reasoning)
+- Text-mode scripts return only the **final assistant message** (not tool calls, reasoning, or metadata)
+- JSON and stream-json responses include `agent_id`, `conversation_id`, and `environment.source` so you can continue the same conversation/runtime. Environment-routed turns also include `environment.id`, `connection_id`, `device_id`, and `name`.
 - The target agent may use tools, think, and reason - but you only see their final response
 - To see the full conversation transcript (including tool calls), use the `searching-messages` skill with `letta messages list --agent <id>` targeting the other agent