@letta-ai/letta-code 0.14.4 → 0.14.6

package/skills/syncing-memory-filesystem/SKILL.md

@@ -9,82 +9,63 @@ When memFS is enabled, your memory blocks are mirrored as `.md` files on disk at
 
 **Conflicts** occur when both the file and the block are modified since the last sync (e.g., user edits a file in their editor while the block is also updated manually by the user via the API). Non-conflicting changes (only one side changed) are resolved automatically during the next sync.
 
-## Scripts
+## CLI Commands
 
-Three scripts provide a git-like interface for managing sync status:
+Use the built-in CLI subcommands. They use the same auth flow as the CLI
+(OAuth/keychain + refresh), and default to `LETTA_AGENT_ID` when available.
 
-### 1. `memfs-status.ts` — Check sync status (like `git status`)
+```bash
+letta memfs status --agent <agent-id>
+letta memfs diff --agent <agent-id>
+letta memfs resolve --agent <agent-id> --resolutions '<JSON>'
+```
 
+Auth overrides (optional):
 ```bash
-npx tsx <SKILL_DIR>/scripts/memfs-status.ts $LETTA_AGENT_ID
+LETTA_API_KEY=... letta memfs status --agent <agent-id>
+LETTA_BASE_URL=http://localhost:8283 LETTA_API_KEY=... letta memfs status --agent <agent-id>
 ```
 
-**Output**: JSON object with:
-- `conflicts` — blocks where both file and block changed (need manual resolution)
-- `pendingFromFile` — file changed, block didn't (resolved on next sync)
-- `pendingFromBlock` — block changed, file didn't (resolved on next sync)
+**Output**: JSON only.
+
+**Status output fields**:
+- `conflicts` — blocks where both file and block changed
+- `pendingFromFile` — file changed, block didn’t (auto-resolved on sync)
+- `pendingFromBlock` — block changed, file didn’t (auto-resolved on sync)
 - `newFiles` — files without corresponding blocks
 - `newBlocks` — blocks without corresponding files
+- `locationMismatches` — file location doesn’t match attachment state
 - `isClean` — true if everything is in sync
 - `lastSync` — timestamp of last sync
 
-Read-only, safe to run anytime.
-
-### 2. `memfs-diff.ts` — View conflict details (like `git diff`)
-
-```bash
-npx tsx <SKILL_DIR>/scripts/memfs-diff.ts $LETTA_AGENT_ID
-```
-
-**Output**: Writes a formatted markdown diff file showing both the file version and block version of each conflicting label. The path to the diff file is printed to stdout.
-
-Use the `Read` tool to review the diff file content.
-
-### 3. `memfs-resolve.ts` — Resolve conflicts (like `git merge`)
-
-```bash
-npx tsx <SKILL_DIR>/scripts/memfs-resolve.ts $LETTA_AGENT_ID --resolutions '<JSON>'
-```
-
-**Arguments**:
-- `--resolutions` — JSON array of resolution objects
-
-**Resolution format**:
-```json
-[
-  {"label": "persona/soul", "resolution": "block"},
-  {"label": "human/prefs", "resolution": "file"}
-]
-```
-
-**Resolution options**:
-- `"file"` — Overwrite the memory block with the file contents
-- `"block"` — Overwrite the file with the memory block contents
+**Diff output**:
+- Writes a markdown diff file and returns `{ diffPath, conflicts, metadataOnly }`
 
-All resolutions must be provided in a single call (stateless).
+**Resolve output**:
+- Returns the sync result from `syncMemoryFilesystem` (created/updated/deleted blocks/files, conflicts).
 
 ## Typical Workflow
 
 1. You receive a system reminder about memFS conflicts
-2. Run `memfs-diff.ts` to see the full content of both sides
+2. Run `letta memfs diff` to see the full content of both sides
 3. Read the diff file to understand the changes
 4. Decide for each conflict: keep the file version or the block version
-5. Run `memfs-resolve.ts` with all resolutions at once
+5. Run `letta memfs resolve` with all resolutions at once
 
 ## Example
 
 ```bash
 # Step 1: Check status (optional — the system reminder already tells you about conflicts)
-npx tsx <SKILL_DIR>/scripts/memfs-status.ts $LETTA_AGENT_ID
+letta memfs status --agent $LETTA_AGENT_ID
 
 # Step 2: View the diffs
-npx tsx <SKILL_DIR>/scripts/memfs-diff.ts $LETTA_AGENT_ID
+letta memfs diff --agent $LETTA_AGENT_ID
 # Output: "Diff (2 conflicts) written to: /path/to/diff.md"
 
 # Step 3: Read the diff file (use Read tool on the path from step 2)
 
 # Step 4: Resolve all conflicts
-npx tsx <SKILL_DIR>/scripts/memfs-resolve.ts $LETTA_AGENT_ID --resolutions '[{"label":"persona/soul","resolution":"block"},{"label":"human/prefs","resolution":"file"}]'
+letta memfs resolve --agent $LETTA_AGENT_ID --resolutions '[{"label":"persona/soul","resolution":"block"},{"label":"human/prefs","resolution":"file"}]'
 ```
 
 ## How Conflicts Arise

package/skills/finding-agents/scripts/find-agents.ts

@@ -1,177 +0,0 @@
-#!/usr/bin/env npx tsx
-/**
- * Find Agents - Search for agents with various filters
- *
- * This script is standalone and can be run outside the CLI process.
- * It reads auth from LETTA_API_KEY env var or ~/.letta/settings.json.
- *
- * Usage:
- *   npx tsx find-agents.ts [options]
- *
- * Options:
- *   --name <name>         Exact name match
- *   --query <text>        Fuzzy search by name
- *   --tags <tag1,tag2>    Filter by tags (comma-separated)
- *   --match-all-tags      Require ALL tags (default: ANY)
- *   --include-blocks      Include agent.blocks in response
- *   --limit <n>           Max results (default: 20)
- *
- * Output:
- *   Raw API response from GET /v1/agents
- */
-
-import { readFileSync } from "node:fs";
-import { createRequire } from "node:module";
-import { homedir } from "node:os";
-import { join } from "node:path";
-
-// Use createRequire for @letta-ai/letta-client so NODE_PATH is respected
-// (ES module imports don't respect NODE_PATH, but require does)
-const require = createRequire(import.meta.url);
-const Letta = require("@letta-ai/letta-client")
-  .default as typeof import("@letta-ai/letta-client").default;
-type LettaClient = InstanceType<typeof Letta>;
-
-interface FindAgentsOptions {
-  name?: string;
-  query?: string;
-  tags?: string[];
-  matchAllTags?: boolean;
-  includeBlocks?: boolean;
-  limit?: number;
-}
-
-/**
- * Get API key from env var or settings file
- */
-function getApiKey(): string {
-  // First check env var (set by CLI's getShellEnv)
-  if (process.env.LETTA_API_KEY) {
-    return process.env.LETTA_API_KEY;
-  }
-
-  // Fall back to settings file
-  const settingsPath = join(homedir(), ".letta", "settings.json");
-  try {
-    const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
-    if (settings.env?.LETTA_API_KEY) {
-      return settings.env.LETTA_API_KEY;
-    }
-  } catch {
-    // Settings file doesn't exist or is invalid
-  }
-
-  throw new Error(
-    "No LETTA_API_KEY found. Set the env var or run the Letta CLI to authenticate.",
-  );
-}
-
-/**
- * Create a Letta client with auth from env/settings
- */
-function createClient(): LettaClient {
-  return new Letta({ apiKey: getApiKey() });
-}
-
-/**
- * Find agents matching the given criteria
- * @param client - Letta client instance
- * @param options - Search options
- * @returns Array of agent objects from the API
- */
-export async function findAgents(
-  client: LettaClient,
-  options: FindAgentsOptions = {},
-): Promise<Awaited<ReturnType<typeof client.agents.list>>> {
-  const params: Parameters<typeof client.agents.list>[0] = {
-    limit: options.limit ?? 20,
-  };
-
-  if (options.name) {
-    params.name = options.name;
-  }
-
-  if (options.query) {
-    params.query_text = options.query;
-  }
-
-  if (options.tags && options.tags.length > 0) {
-    params.tags = options.tags;
-    if (options.matchAllTags) {
-      params.match_all_tags = true;
-    }
-  }
-
-  if (options.includeBlocks) {
-    params.include = ["agent.blocks"];
-  }
-
-  return await client.agents.list(params);
-}
-
-function parseArgs(args: string[]): FindAgentsOptions {
-  const options: FindAgentsOptions = {};
-
-  const nameIndex = args.indexOf("--name");
-  if (nameIndex !== -1 && nameIndex + 1 < args.length) {
-    options.name = args[nameIndex + 1];
-  }
-
-  const queryIndex = args.indexOf("--query");
-  if (queryIndex !== -1 && queryIndex + 1 < args.length) {
-    options.query = args[queryIndex + 1];
-  }
-
-  const tagsIndex = args.indexOf("--tags");
-  if (tagsIndex !== -1 && tagsIndex + 1 < args.length) {
-    options.tags = args[tagsIndex + 1]?.split(",").map((t) => t.trim());
-  }
-
-  if (args.includes("--match-all-tags")) {
-    options.matchAllTags = true;
-  }
-
-  if (args.includes("--include-blocks")) {
-    options.includeBlocks = true;
-  }
-
-  const limitIndex = args.indexOf("--limit");
-  if (limitIndex !== -1 && limitIndex + 1 < args.length) {
-    const limit = Number.parseInt(args[limitIndex + 1] as string, 10);
-    if (!Number.isNaN(limit)) {
-      options.limit = limit;
-    }
-  }
-
-  return options;
-}
-
-// CLI entry point - check if this file is being run directly
-const isMainModule = import.meta.url === `file://${process.argv[1]}`;
-if (isMainModule) {
-  (async () => {
-    try {
-      const options = parseArgs(process.argv.slice(2));
-      const client = createClient();
-      const result = await findAgents(client, options);
-      console.log(JSON.stringify(result, null, 2));
-    } catch (error) {
-      console.error(
-        "Error:",
-        error instanceof Error ? error.message : String(error),
-      );
-      console.error(`
-Usage: npx tsx find-agents.ts [options]
-
-Options:
-  --name <name>         Exact name match
-  --query <text>        Fuzzy search by name
-  --tags <tag1,tag2>    Filter by tags (comma-separated)
-  --match-all-tags      Require ALL tags (default: ANY)
-  --include-blocks      Include agent.blocks in response
-  --limit <n>           Max results (default: 20)
-`);
-      process.exit(1);
-    }
-  })();
-}

package/skills/messaging-agents/scripts/continue-conversation.ts

@@ -1,226 +0,0 @@
-#!/usr/bin/env npx tsx
-/**
- * Continue Conversation - Send a follow-up message to an existing conversation
- *
- * This script is standalone and can be run outside the CLI process.
- * It reads auth from LETTA_API_KEY env var or ~/.letta/settings.json.
- * It reads sender agent ID from LETTA_AGENT_ID env var.
- *
- * Usage:
- *   npx tsx continue-conversation.ts --conversation-id <id> --message "<text>"
- *
- * Options:
- *   --conversation-id <id>   Existing conversation ID (required)
- *   --message <text>         Message to send (required)
- *   --timeout <ms>           Max wait time in ms (default: 120000)
- *
- * Output:
- *   JSON with conversation_id, response, agent_id, agent_name
- */
-
-import { readFileSync } from "node:fs";
-import { createRequire } from "node:module";
-import { homedir } from "node:os";
-import { join } from "node:path";
-import {
-  SYSTEM_REMINDER_CLOSE,
-  SYSTEM_REMINDER_OPEN,
-} from "../../../../constants";
-
-// Use createRequire for @letta-ai/letta-client so NODE_PATH is respected
-// (ES module imports don't respect NODE_PATH, but require does)
-const require = createRequire(import.meta.url);
-const Letta = require("@letta-ai/letta-client")
-  .default as typeof import("@letta-ai/letta-client").default;
-type LettaClient = InstanceType<typeof Letta>;
-
-interface ContinueConversationOptions {
-  conversationId: string;
-  message: string;
-  timeout?: number;
-}
-
-interface ContinueConversationResult {
-  conversation_id: string;
-  response: string;
-  agent_id: string;
-  agent_name: string;
-}
-
-/**
- * Get API key from env var or settings file
- */
-function getApiKey(): string {
-  if (process.env.LETTA_API_KEY) {
-    return process.env.LETTA_API_KEY;
-  }
-
-  const settingsPath = join(homedir(), ".letta", "settings.json");
-  try {
-    const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
-    if (settings.env?.LETTA_API_KEY) {
-      return settings.env.LETTA_API_KEY;
-    }
-  } catch {
-    // Settings file doesn't exist or is invalid
-  }
-
-  throw new Error(
-    "No LETTA_API_KEY found. Set the env var or run the Letta CLI to authenticate.",
-  );
-}
-
-/**
- * Get the sender agent ID from env var
- */
-function getSenderAgentId(): string {
-  if (process.env.LETTA_AGENT_ID) {
-    return process.env.LETTA_AGENT_ID;
-  }
-  throw new Error(
-    "No LETTA_AGENT_ID found. This script should be run from within a Letta Code session.",
-  );
-}
-
-/**
- * Create a Letta client with auth from env/settings
- */
-function createClient(): LettaClient {
-  return new Letta({ apiKey: getApiKey() });
-}
-
-/**
- * Build the system reminder prefix for the message
- */
-function buildSystemReminder(
-  senderAgentName: string,
-  senderAgentId: string,
-): string {
-  return `${SYSTEM_REMINDER_OPEN}
-This message is from "${senderAgentName}" (agent ID: ${senderAgentId}), an agent currently running inside the Letta Code CLI (docs.letta.com/letta-code).
-The sender will only see the final message you generate (not tool calls or reasoning).
-If you need to share detailed information, include it in your response text.
-${SYSTEM_REMINDER_CLOSE}
-
-`;
-}
-
-/**
- * Continue an existing conversation by sending a follow-up message
- * @param client - Letta client instance
- * @param options - Options including conversation ID and message
- * @returns Conversation result with response and metadata
- */
-export async function continueConversation(
-  client: LettaClient,
-  options: ContinueConversationOptions,
-): Promise<ContinueConversationResult> {
-  const { conversationId, message } = options;
-
-  // 1. Fetch conversation to get agent_id and validate it exists
-  const conversation = await client.conversations.retrieve(conversationId);
-
-  // 2. Fetch target agent to get name
-  const targetAgent = await client.agents.retrieve(conversation.agent_id);
-
-  // 3. Fetch sender agent to get name for system reminder
-  const senderAgentId = getSenderAgentId();
-  const senderAgent = await client.agents.retrieve(senderAgentId);
-
-  // 4. Build message with system reminder prefix
-  const systemReminder = buildSystemReminder(senderAgent.name, senderAgentId);
-  const fullMessage = systemReminder + message;
-
-  // 5. Send message and consume the stream
-  // Note: conversations.messages.create always returns a Stream
-  const stream = await client.conversations.messages.create(conversationId, {
-    input: fullMessage,
-  });
-
-  // 6. Consume stream and extract final assistant message
-  let finalResponse = "";
-  for await (const chunk of stream) {
-    if (chunk.message_type === "assistant_message") {
-      // Content can be string or array of content parts
-      const content = chunk.content;
-      if (typeof content === "string") {
-        finalResponse += content;
-      } else if (Array.isArray(content)) {
-        for (const part of content) {
-          if (
-            typeof part === "object" &&
-            part !== null &&
-            "type" in part &&
-            part.type === "text" &&
-            "text" in part
-          ) {
-            finalResponse += (part as { text: string }).text;
-          }
-        }
-      }
-    }
-  }
-
-  return {
-    conversation_id: conversationId,
-    response: finalResponse,
-    agent_id: targetAgent.id,
-    agent_name: targetAgent.name,
-  };
-}
-
-function parseArgs(args: string[]): ContinueConversationOptions {
-  const conversationIdIndex = args.indexOf("--conversation-id");
-  if (conversationIdIndex === -1 || conversationIdIndex + 1 >= args.length) {
-    throw new Error(
-      "Missing required argument: --conversation-id <conversation-id>",
-    );
-  }
-  const conversationId = args[conversationIdIndex + 1] as string;
-
-  const messageIndex = args.indexOf("--message");
-  if (messageIndex === -1 || messageIndex + 1 >= args.length) {
-    throw new Error("Missing required argument: --message <text>");
-  }
-  const message = args[messageIndex + 1] as string;
-
-  const options: ContinueConversationOptions = { conversationId, message };
-
-  const timeoutIndex = args.indexOf("--timeout");
-  if (timeoutIndex !== -1 && timeoutIndex + 1 < args.length) {
-    const timeout = Number.parseInt(args[timeoutIndex + 1] as string, 10);
-    if (!Number.isNaN(timeout)) {
-      options.timeout = timeout;
-    }
-  }
-
-  return options;
-}
-
-// CLI entry point - check if this file is being run directly
-const isMainModule = import.meta.url === `file://${process.argv[1]}`;
-if (isMainModule) {
-  (async () => {
-    try {
-      const options = parseArgs(process.argv.slice(2));
-      const client = createClient();
-      const result = await continueConversation(client, options);
-      console.log(JSON.stringify(result, null, 2));
-      process.exit(0);
-    } catch (error) {
-      console.error(
-        "Error:",
-        error instanceof Error ? error.message : String(error),
-      );
-      console.error(`
-Usage: npx tsx continue-conversation.ts --conversation-id <id> --message "<text>"
-
-Options:
-  --conversation-id <id>   Existing conversation ID (required)
-  --message <text>         Message to send (required)
-  --timeout <ms>           Max wait time in ms (default: 120000)
-`);
-      process.exit(1);
-    }
-  })();
-}