@letta-ai/letta-code 0.11.2-next.3 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.11.2-next.3",
+  "version": "0.12.0",
   "description": "Letta Code is a CLI tool for interacting with stateful Letta agents from the terminal.",
   "type": "module",
   "bin": {

package/skills/acquiring-skills/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: acquiring-skills
+description: Guide for safely discovering and installing skills from external repositories. Use when a user asks for something where a specialized skill likely exists (browser testing, PDF processing, document generation, etc.) and you want to bootstrap your understanding rather than starting from scratch.
+---
+
+# Acquiring New Skills
+
+This skill teaches you how to safely discover and install skills from external sources.
+
+## SAFETY - READ THIS FIRST
+
+Skills can contain:
+- **Markdown files** (.md) - Risk: prompt injection, misleading instructions
+- **Scripts** (Python, TypeScript, Bash) - Risk: malicious code execution
+
+### Trusted Sources (no user approval needed for download)
+- `https://github.com/letta-ai/skills` - Letta's community skills
+- `https://github.com/anthropics/skills` - Anthropic's official skills
+
+### Untrusted Sources (ALWAYS verify with user)
+For ANY source other than letta-ai or anthropics:
+1. Ask the user before downloading
+2. Explain where the skill comes from
+3. Get explicit approval
+
+### Script Safety
+Even for skills from trusted sources, ALWAYS:
+1. Read and inspect any scripts before executing them
+2. Understand what the script does
+3. Be wary of network calls, file operations, or system commands
+
+## When to Use This Skill
+
+**DO use** when:
+- User asks for something where a skill likely exists (e.g., "help me test this webapp", "generate a PDF report")
+- You think "there's probably a skill that would bootstrap my understanding"
+- User explicitly asks about available skills or extending capabilities
+
+**DON'T use** for:
+- General coding tasks you can already handle
+- Simple bug fixes or feature implementations
+- Tasks where you have sufficient knowledge
+
+## Ask Before Searching (Interactive Mode)
+
+If you recognize a task that might have an associated skill, **ask the user first**:
+
+> "This sounds like something where a community skill might help (e.g., webapp testing with Playwright). Would you like me to look for available skills in the Letta or Anthropic repositories? This might take a minute, or I can start coding right away if you prefer."
+
+The user may prefer to start immediately rather than wait for skill discovery.
+
+Only proceed with skill acquisition if the user agrees.
+
+## Skill Repositories
+
+| Repository | Description |
+|------------|-------------|
+| https://github.com/letta-ai/skills | Community skills for Letta agents |
+| https://github.com/anthropics/skills | Anthropic's official Agent Skills |
+
+Browse these repositories to discover available skills. Check the README for skill listings.
+
+## Installation Locations
+
+| Location | Path | When to Use |
+|----------|------|-------------|
+| **Global** | `~/.letta/skills/<skill>/` | General-purpose skills useful across projects |
+| **Project** | `.skills/<skill>/` | Project-specific skills |
+
+**Rule**: If useful across multiple projects, install globally. If project-specific, install in `.skills/`.
+
+## How to Download Skills
+
+Skills are directories containing SKILL.md and optionally scripts/, references/, examples/.
+
+### Method: Clone to /tmp, then copy
+
+```bash
+# 1. Clone the repo (shallow)
+git clone --depth 1 https://github.com/anthropics/skills /tmp/skills-temp
+
+# 2. Copy the skill to your skills directory
+# For global:
+cp -r /tmp/skills-temp/skills/webapp-testing ~/.letta/skills/
+# For project:
+cp -r /tmp/skills-temp/skills/webapp-testing .skills/
+
+# 3. Cleanup
+rm -rf /tmp/skills-temp
+```
+
+### Alternative: rsync (preserves permissions)
+
+```bash
+git clone --depth 1 https://github.com/anthropics/skills /tmp/skills-temp
+rsync -av /tmp/skills-temp/skills/webapp-testing/ ~/.letta/skills/webapp-testing/
+rm -rf /tmp/skills-temp
+```
+
+## Registering New Skills
+
+After downloading, refresh the skills list:
+
+```
+Skill(command: "refresh")
+```
+
+This scans `~/.letta/skills/` and `.skills/` and updates your `skills` memory block.
+
+## Complete Example
+
+User asks: "Can you help me test my React app's UI?"
+
+1. **Recognize opportunity**: Browser/webapp testing - likely has a skill
+2. **Ask user**: "Would you like me to look for webapp testing skills, or start coding right away?"
+3. **If user agrees, find skill**: Check anthropics/skills for webapp-testing
+4. **Download** (trusted source):
+   ```bash
+   git clone --depth 1 https://github.com/anthropics/skills /tmp/skills-temp
+   cp -r /tmp/skills-temp/skills/webapp-testing ~/.letta/skills/
+   rm -rf /tmp/skills-temp
+   ```
+5. **Refresh**: `Skill(command: "refresh")`
+6. **Inspect scripts**: Read any .py or .ts files before using them
+7. **Load**: `Skill(command: "load", skills: ["webapp-testing"])`
+8. **Use**: Follow the skill's instructions for the user's task

package/skills/migrating-memory/SKILL.md

@@ -29,7 +29,6 @@ Best for: Extracting sections, cleaning up messy content, selective migration.
 
 Creates new blocks with the same content using `copy-block.ts`. After copying:
 - You own the copy - changes don't sync
-- Use `--label` flag if you already have a block with that label
 - Best for: One-time migration, forking an agent
 
 ### 3. Share (Linked Blocks)
@@ -40,7 +39,31 @@ Attaches the same block to multiple agents using `attach-block.ts`. After sharin
 - Can be read-only (target can read but not modify)
 - Best for: Shared knowledge bases, synchronized state
 
-**Note:** You cannot have two blocks with the same label. When copying, use `--label` to rename if needed.
+## Handling Duplicate Label Errors
+
+**You cannot have two blocks with the same label.** If you try to copy/attach a block and you already have one with that label, you'll get a `duplicate key value violates unique constraint` error.
+
+**Solutions:**
+
+1. **Use `--label` (copy only):** Rename the block when copying:
+   ```bash
+   npx tsx <SKILL_DIR>/scripts/copy-block.ts --block-id <id> --label project-imported
+   ```
+
+2. **Use `--override` (copy or attach):** Automatically detach your existing block first:
+   ```bash
+   npx tsx <SKILL_DIR>/scripts/copy-block.ts --block-id <id> --override
+   npx tsx <SKILL_DIR>/scripts/attach-block.ts --block-id <id> --override
+   ```
+   If the operation fails, the original block is automatically reattached.
+
+3. **Manual detach first:** Use the `memory` tool to detach your existing block:
+   ```
+   memory(agent_state, "delete", path="/memories/<label>")
+   ```
+   Then run the copy/attach script.
+
+**Note:** `attach-block.ts` does NOT support `--label` because attached blocks keep their original label (they're shared, not copied).
 
 ## Workflow
 
@@ -92,8 +115,8 @@ All scripts are located in the `scripts/` directory and output raw API responses
 | Script | Purpose | Args |
 |--------|---------|------|
 | `get-agent-blocks.ts` | Get blocks from an agent | `--agent-id` |
-| `copy-block.ts` | Copy block to current agent | `--block-id`, optional `--label` |
-| `attach-block.ts` | Attach existing block to current agent | `--block-id`, optional `--read-only` |
+| `copy-block.ts` | Copy block to current agent | `--block-id`, optional `--label`, `--override` |
+| `attach-block.ts` | Attach existing block to current agent | `--block-id`, optional `--read-only`, `--override` |
 
 ## Authentication
 

package/skills/migrating-memory/scripts/attach-block.ts

@@ -7,7 +7,7 @@
  * It reads agent ID from LETTA_AGENT_ID env var or --agent-id arg.
  *
  * Usage:
- *   npx tsx attach-block.ts --block-id <block-id> [--agent-id <agent-id>] [--read-only]
+ *   npx tsx attach-block.ts --block-id <block-id> [--agent-id <agent-id>] [--read-only] [--override]
  *
  * This attaches an existing block to another agent, making it shared.
  * Changes to the block will be visible to all agents that have it attached.
@@ -15,6 +15,8 @@
  * Options:
  *   --agent-id   Target agent ID (overrides LETTA_AGENT_ID env var)
  *   --read-only  Target agent can read but not modify the block
+ *   --override   If you already have a block with the same label, detach it first
+ *                (on error, the original block is reattached)
  *
  * Output:
  *   Raw API response from the attach operation
@@ -75,49 +77,109 @@ function createClient(): LettaClient {
   return new Letta({ apiKey: getApiKey() });
 }
 
+interface AttachBlockResult {
+  attachResult: Awaited<ReturnType<LettaClient["agents"]["blocks"]["attach"]>>;
+  detachedBlock?: Awaited<ReturnType<LettaClient["blocks"]["retrieve"]>>;
+}
+
 /**
  * Attach an existing block to the current agent (sharing it)
  * @param client - Letta client instance
  * @param blockId - The block ID to attach
- * @param readOnly - Whether this agent should have read-only access
- * @param targetAgentId - Optional target agent ID (defaults to current agent)
+ * @param options - readOnly, targetAgentId, override (detach existing block with same label)
  * @returns API response from the attach operation
  */
 export async function attachBlock(
   client: LettaClient,
   blockId: string,
-  readOnly = false,
-  targetAgentId?: string,
-): Promise<Awaited<ReturnType<typeof client.agents.blocks.attach>>> {
-  // Get current agent ID (the agent calling this script) or use provided ID
-  const currentAgentId = getAgentId(targetAgentId);
-
-  const result = await client.agents.blocks.attach(blockId, {
-    agent_id: currentAgentId,
-  });
-
-  // If read-only is requested, update the block's read_only flag for this agent
-  // Note: This may require a separate API call depending on how read_only works
-  if (readOnly) {
-    // The read_only flag is per-block, not per-agent attachment
-    // For now, we'll note this in the output
+  options?: { readOnly?: boolean; targetAgentId?: string; override?: boolean },
+): Promise<AttachBlockResult> {
+  const currentAgentId = getAgentId(options?.targetAgentId);
+  let detachedBlock:
+    | Awaited<ReturnType<LettaClient["blocks"]["retrieve"]>>
+    | undefined;
+
+  // If override is requested, check for existing block with same label and detach it
+  if (options?.override) {
+    // Get the block we're trying to attach to find its label
+    const sourceBlock = await client.blocks.retrieve(blockId);
+    const sourceLabel = sourceBlock.label;
+
+    // Get current agent's blocks to check for label conflict
+    const currentBlocksResponse =
+      await client.agents.blocks.list(currentAgentId);
+    // The response may be paginated or an array depending on SDK version
+    const currentBlocks = Array.isArray(currentBlocksResponse)
+      ? currentBlocksResponse
+      : (currentBlocksResponse as { items?: unknown[] }).items || [];
+    const conflictingBlock = currentBlocks.find(
+      (b: { label?: string }) => b.label === sourceLabel,
+    );
+
+    if (conflictingBlock) {
+      console.error(
+        `Detaching existing block with label "${sourceLabel}" (${conflictingBlock.id})...`,
+      );
+      detachedBlock = conflictingBlock;
+      try {
+        await client.agents.blocks.detach(conflictingBlock.id, {
+          agent_id: currentAgentId,
+        });
+      } catch (detachError) {
+        throw new Error(
+          `Failed to detach existing block "${sourceLabel}": ${detachError instanceof Error ? detachError.message : String(detachError)}`,
+        );
+      }
+    }
+  }
+
+  // Attempt to attach the new block
+  let attachResult: Awaited<ReturnType<typeof client.agents.blocks.attach>>;
+  try {
+    attachResult = await client.agents.blocks.attach(blockId, {
+      agent_id: currentAgentId,
+    });
+  } catch (attachError) {
+    // If attach failed and we detached a block, try to reattach it
+    if (detachedBlock) {
+      console.error(
+        `Attach failed, reattaching original block "${detachedBlock.label}"...`,
+      );
+      try {
+        await client.agents.blocks.attach(detachedBlock.id, {
+          agent_id: currentAgentId,
+        });
+        console.error("Original block reattached successfully.");
+      } catch {
+        console.error(
+          `WARNING: Failed to reattach original block! Block ID: ${detachedBlock.id}`,
+        );
+      }
+    }
+    throw attachError;
+  }
+
+  // If read-only is requested, note the limitation
+  if (options?.readOnly) {
     console.warn(
       "Note: read_only flag is set on the block itself, not per-agent. " +
         "Use the block update API to set read_only if needed.",
     );
   }
 
-  return result;
+  return { attachResult, detachedBlock };
 }
 
 function parseArgs(args: string[]): {
   blockId: string;
   readOnly: boolean;
+  override: boolean;
   agentId?: string;
 } {
   const blockIdIndex = args.indexOf("--block-id");
   const agentIdIndex = args.indexOf("--agent-id");
   const readOnly = args.includes("--read-only");
+  const override = args.includes("--override");
 
   if (blockIdIndex === -1 || blockIdIndex + 1 >= args.length) {
     throw new Error("Missing required argument: --block-id <block-id>");
@@ -126,6 +188,7 @@ function parseArgs(args: string[]): {
   return {
     blockId: args[blockIdIndex + 1] as string,
     readOnly,
+    override,
     agentId:
       agentIdIndex !== -1 && agentIdIndex + 1 < args.length
         ? (args[agentIdIndex + 1] as string)
@@ -138,9 +201,15 @@ const isMainModule = import.meta.url === `file://${process.argv[1]}`;
 if (isMainModule) {
   (async () => {
     try {
-      const { blockId, readOnly, agentId } = parseArgs(process.argv.slice(2));
+      const { blockId, readOnly, override, agentId } = parseArgs(
+        process.argv.slice(2),
+      );
       const client = createClient();
-      const result = await attachBlock(client, blockId, readOnly, agentId);
+      const result = await attachBlock(client, blockId, {
+        readOnly,
+        override,
+        targetAgentId: agentId,
+      });
       console.log(JSON.stringify(result, null, 2));
     } catch (error) {
       console.error(
@@ -152,7 +221,7 @@ if (isMainModule) {
         error.message.includes("Missing required argument")
       ) {
         console.error(
-          "\nUsage: npx tsx attach-block.ts --block-id <block-id> [--agent-id <agent-id>] [--read-only]",
+          "\nUsage: npx tsx attach-block.ts --block-id <block-id> [--agent-id <agent-id>] [--read-only] [--override]",
         );
       }
       process.exit(1);

package/skills/migrating-memory/scripts/copy-block.ts

@@ -7,11 +7,13 @@
  * It reads agent ID from LETTA_AGENT_ID env var or --agent-id arg.
  *
  * Usage:
- *   npx tsx copy-block.ts --block-id <block-id> [--label <new-label>] [--agent-id <agent-id>]
+ *   npx tsx copy-block.ts --block-id <block-id> [--label <new-label>] [--agent-id <agent-id>] [--override]
  *
  * Options:
- *   --label      Override the block label (required if you already have a block with that label)
+ *   --label      Override the block label (useful to avoid duplicate label errors)
  *   --agent-id   Target agent ID (overrides LETTA_AGENT_ID env var)
+ *   --override   If you already have a block with the same label, detach it first
+ *                (on error, the original block is reattached)
  *
  * This creates a new block with the same content as the source block,
  * then attaches it to the current agent. Changes to the new block
@@ -37,6 +39,7 @@ interface CopyBlockResult {
   sourceBlock: Awaited<ReturnType<LettaClient["blocks"]["retrieve"]>>;
   newBlock: Awaited<ReturnType<LettaClient["blocks"]["create"]>>;
   attachResult: Awaited<ReturnType<LettaClient["agents"]["blocks"]["attach"]>>;
+  detachedBlock?: Awaited<ReturnType<LettaClient["blocks"]["retrieve"]>>;
 }
 
 /**
@@ -86,44 +89,125 @@ function createClient(): LettaClient {
  * Copy a block's content to a new block and attach to the current agent
  * @param client - Letta client instance
  * @param blockId - The source block ID to copy from
- * @param options - Optional settings: labelOverride, targetAgentId
+ * @param options - Optional settings: labelOverride, targetAgentId, override
  * @returns Object containing source block, new block, and attach result
  */
 export async function copyBlock(
   client: LettaClient,
   blockId: string,
-  options?: { labelOverride?: string; targetAgentId?: string },
+  options?: {
+    labelOverride?: string;
+    targetAgentId?: string;
+    override?: boolean;
+  },
 ): Promise<CopyBlockResult> {
-  // Get current agent ID (the agent calling this script) or use provided ID
   const currentAgentId = getAgentId(options?.targetAgentId);
+  let detachedBlock:
+    | Awaited<ReturnType<LettaClient["blocks"]["retrieve"]>>
+    | undefined;
 
   // 1. Get source block details
   const sourceBlock = await client.blocks.retrieve(blockId);
+  const targetLabel =
+    options?.labelOverride || sourceBlock.label || "migrated-block";
 
-  // 2. Create new block with same content (optionally override label)
-  const newBlock = await client.blocks.create({
-    label: options?.labelOverride || sourceBlock.label || "migrated-block",
-    value: sourceBlock.value,
-    description: sourceBlock.description || undefined,
-    limit: sourceBlock.limit,
-  });
+  // 2. If override is requested, check for existing block with same label and detach it
+  if (options?.override) {
+    const currentBlocksResponse =
+      await client.agents.blocks.list(currentAgentId);
+    // The response may be paginated or an array depending on SDK version
+    const currentBlocks = Array.isArray(currentBlocksResponse)
+      ? currentBlocksResponse
+      : (currentBlocksResponse as { items?: unknown[] }).items || [];
+    const conflictingBlock = currentBlocks.find(
+      (b: { label?: string }) => b.label === targetLabel,
+    );
 
-  // 3. Attach new block to current agent
-  const attachResult = await client.agents.blocks.attach(newBlock.id, {
-    agent_id: currentAgentId,
-  });
+    if (conflictingBlock) {
+      console.error(
+        `Detaching existing block with label "${targetLabel}" (${conflictingBlock.id})...`,
+      );
+      detachedBlock = conflictingBlock;
+      try {
+        await client.agents.blocks.detach(conflictingBlock.id, {
+          agent_id: currentAgentId,
+        });
+      } catch (detachError) {
+        throw new Error(
+          `Failed to detach existing block "${targetLabel}": ${detachError instanceof Error ? detachError.message : String(detachError)}`,
+        );
+      }
+    }
+  }
 
-  return { sourceBlock, newBlock, attachResult };
+  // 3. Create new block with same content
+  let newBlock: Awaited<ReturnType<LettaClient["blocks"]["create"]>>;
+  try {
+    newBlock = await client.blocks.create({
+      label: targetLabel,
+      value: sourceBlock.value,
+      description: sourceBlock.description || undefined,
+      limit: sourceBlock.limit,
+    });
+  } catch (createError) {
+    // If create failed and we detached a block, try to reattach it
+    if (detachedBlock) {
+      console.error(
+        `Create failed, reattaching original block "${detachedBlock.label}"...`,
+      );
+      try {
+        await client.agents.blocks.attach(detachedBlock.id, {
+          agent_id: currentAgentId,
+        });
+        console.error("Original block reattached successfully.");
+      } catch {
+        console.error(
+          `WARNING: Failed to reattach original block! Block ID: ${detachedBlock.id}`,
+        );
+      }
+    }
+    throw createError;
+  }
+
+  // 4. Attach new block to current agent
+  let attachResult: Awaited<ReturnType<typeof client.agents.blocks.attach>>;
+  try {
+    attachResult = await client.agents.blocks.attach(newBlock.id, {
+      agent_id: currentAgentId,
+    });
+  } catch (attachError) {
+    // If attach failed and we detached a block, try to reattach it
+    if (detachedBlock) {
+      console.error(
+        `Attach failed, reattaching original block "${detachedBlock.label}"...`,
+      );
+      try {
+        await client.agents.blocks.attach(detachedBlock.id, {
+          agent_id: currentAgentId,
+        });
+        console.error("Original block reattached successfully.");
+      } catch {
+        console.error(
+          `WARNING: Failed to reattach original block! Block ID: ${detachedBlock.id}`,
+        );
+      }
+    }
+    throw attachError;
+  }
+
+  return { sourceBlock, newBlock, attachResult, detachedBlock };
 }
 
 function parseArgs(args: string[]): {
   blockId: string;
   label?: string;
   agentId?: string;
+  override: boolean;
 } {
   const blockIdIndex = args.indexOf("--block-id");
   const labelIndex = args.indexOf("--label");
   const agentIdIndex = args.indexOf("--agent-id");
+  const override = args.includes("--override");
 
   if (blockIdIndex === -1 || blockIdIndex + 1 >= args.length) {
     throw new Error("Missing required argument: --block-id <block-id>");
@@ -139,6 +223,7 @@ function parseArgs(args: string[]): {
       agentIdIndex !== -1 && agentIdIndex + 1 < args.length
         ? (args[agentIdIndex + 1] as string)
         : undefined,
+    override,
   };
 }
 
@@ -147,11 +232,14 @@ const isMainModule = import.meta.url === `file://${process.argv[1]}`;
 if (isMainModule) {
   (async () => {
     try {
-      const { blockId, label, agentId } = parseArgs(process.argv.slice(2));
+      const { blockId, label, agentId, override } = parseArgs(
+        process.argv.slice(2),
+      );
       const client = createClient();
       const result = await copyBlock(client, blockId, {
         labelOverride: label,
         targetAgentId: agentId,
+        override,
       });
       console.log(JSON.stringify(result, null, 2));
     } catch (error) {
@@ -164,7 +252,7 @@ if (isMainModule) {
         error.message.includes("Missing required argument")
       ) {
         console.error(
-          "\nUsage: npx tsx copy-block.ts --block-id <block-id> [--label <new-label>] [--agent-id <agent-id>]",
+          "\nUsage: npx tsx copy-block.ts --block-id <block-id> [--label <new-label>] [--agent-id <agent-id>] [--override]",
         );
       }
       process.exit(1);