@letta-ai/letta-code 0.11.2-next.2 → 0.11.2-next.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.11.2-next.2",
+  "version": "0.11.2-next.4",
   "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/creating-skills/SKILL.md

@@ -263,7 +263,7 @@ When creating a new skill from scratch, always run the `init-skill.ts` script. T
 Usage:
 
 ```bash
-npx ts-node scripts/init-skill.ts <skill-name> --path <output-directory>
+npx tsx <SKILL_DIR>/scripts/init-skill.ts <skill-name> --path <output-directory>
 ```
 
 The script:
@@ -335,13 +335,13 @@ Write instructions for using the skill and its bundled resources.
 Once development of the skill is complete, it must be packaged into a distributable .skill file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements:
 
 ```bash
-npx ts-node scripts/package-skill.ts <path/to/skill-folder>
+npx tsx <SKILL_DIR>/scripts/package-skill.ts <path/to/skill-folder>
 ```
 
 Optional output directory specification:
 
 ```bash
-npx ts-node scripts/package-skill.ts <path/to/skill-folder> ./dist
+npx tsx <SKILL_DIR>/scripts/package-skill.ts <path/to/skill-folder> ./dist
 ```
 
 The packaging script will:

package/skills/finding-agents/SKILL.md

@@ -18,7 +18,7 @@ This skill helps you find other agents on the same Letta server.
 ## Script Usage
 
 ```bash
-npx ts-node scripts/find-agents.ts [options]
+npx tsx <SKILL_DIR>/scripts/find-agents.ts [options]
 ```
 
 ### Options
@@ -39,7 +39,7 @@ npx ts-node scripts/find-agents.ts [options]
 Agents created by Letta Code are tagged with `origin:letta-code`. To find only Letta Code agents:
 
 ```bash
-npx ts-node scripts/find-agents.ts --tags "origin:letta-code"
+npx tsx <SKILL_DIR>/scripts/find-agents.ts --tags "origin:letta-code"
 ```
 
 This is useful when the user is looking for agents they've worked with in Letta Code CLI sessions.
@@ -49,39 +49,39 @@ This is useful when the user is looking for agents they've worked with in Letta
 If the user has agents created outside Letta Code (via ADE, SDK, etc.), search without the tag filter:
 
 ```bash
-npx ts-node scripts/find-agents.ts
+npx tsx <SKILL_DIR>/scripts/find-agents.ts
 ```
 
 ## Examples
 
 **List all agents (up to 20):**
 ```bash
-npx ts-node scripts/find-agents.ts
+npx tsx <SKILL_DIR>/scripts/find-agents.ts
 ```
 
 **Find agent by exact name:**
 ```bash
-npx ts-node scripts/find-agents.ts --name "ProjectX-v1"
+npx tsx <SKILL_DIR>/scripts/find-agents.ts --name "ProjectX-v1"
 ```
 
 **Search agents by name (fuzzy):**
 ```bash
-npx ts-node scripts/find-agents.ts --query "project"
+npx tsx <SKILL_DIR>/scripts/find-agents.ts --query "project"
 ```
 
 **Find only Letta Code agents:**
 ```bash
-npx ts-node scripts/find-agents.ts --tags "origin:letta-code"
+npx tsx <SKILL_DIR>/scripts/find-agents.ts --tags "origin:letta-code"
 ```
 
 **Find agents with multiple tags:**
 ```bash
-npx ts-node scripts/find-agents.ts --tags "frontend,production" --match-all-tags
+npx tsx <SKILL_DIR>/scripts/find-agents.ts --tags "frontend,production" --match-all-tags
 ```
 
 **Include memory blocks in results:**
 ```bash
-npx ts-node scripts/find-agents.ts --query "project" --include-blocks
+npx tsx <SKILL_DIR>/scripts/find-agents.ts --query "project" --include-blocks
 ```
 
 ## Output

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
 
@@ -60,7 +83,7 @@ Example: "What's the ID of the agent you want to migrate memory from?"
 Inspect what memory blocks the source agent has:
 
 ```bash
-npx ts-node scripts/get-agent-blocks.ts --agent-id <source-agent-id>
+npx tsx <SKILL_DIR>/scripts/get-agent-blocks.ts --agent-id <source-agent-id>
 ```
 
 This shows each block's ID, label, description, and value.
@@ -71,14 +94,14 @@ For each block you want to migrate, choose copy or share:
 
 **To Copy (create independent block):**
 ```bash
-npx ts-node scripts/copy-block.ts --block-id <block-id> [--label <new-label>]
+npx tsx <SKILL_DIR>/scripts/copy-block.ts --block-id <block-id> [--label <new-label>]
 ```
 
 Use `--label` if you already have a block with that label (e.g., `--label project-imported`).
 
 **To Share (attach existing block):**
 ```bash
-npx ts-node scripts/attach-block.ts --block-id <block-id>
+npx tsx <SKILL_DIR>/scripts/attach-block.ts --block-id <block-id>
 ```
 
 Add `--read-only` flag to share to make this agent unable to modify the block.
@@ -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
 
@@ -113,20 +136,20 @@ Scenario: You're a new agent and want to inherit memory from an existing agent "
 
 2. **List its blocks:**
    ```bash
-   npx ts-node scripts/get-agent-blocks.ts --agent-id agent-abc123
+   npx tsx <SKILL_DIR>/scripts/get-agent-blocks.ts --agent-id agent-abc123
    # Shows: project (block-def456), human (block-ghi789), persona (block-jkl012)
    ```
 
 3. **Copy project knowledge to yourself:**
    ```bash
    # If you don't have a 'project' block yet:
-   npx ts-node scripts/copy-block.ts --block-id block-def456
+   npx tsx <SKILL_DIR>/scripts/copy-block.ts --block-id block-def456
    
    # If you already have 'project', use --label to rename:
-   npx ts-node scripts/copy-block.ts --block-id block-def456 --label project-v1
+   npx tsx <SKILL_DIR>/scripts/copy-block.ts --block-id block-def456 --label project-v1
    ```
 
 4. **Optionally share human preferences (read-only):**
    ```bash
-   npx ts-node scripts/attach-block.ts --block-id block-ghi789 --read-only
+   npx tsx <SKILL_DIR>/scripts/attach-block.ts --block-id block-ghi789 --read-only
    ```

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);