@letta-ai/letta-code 0.13.2 → 0.13.3

package/letta.js

@@ -3065,7 +3065,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@letta-ai/letta-code",
-    version: "0.13.2",
+    version: "0.13.3",
     description: "Letta Code is a CLI tool for interacting with stateful Letta agents from the terminal.",
     type: "module",
     bin: {
@@ -8619,6 +8619,8 @@ Launch a subagent to perform a task. Parameters:
 - **prompt**: Detailed, self-contained instructions for the agent (agents cannot ask questions mid-execution)
 - **description**: Short 3-5 word summary for tracking
 - **model** (optional): Override the model for this agent
+- **agent_id** (optional): Deploy an existing agent instead of creating a new one
+- **conversation_id** (optional): Resume from an existing conversation
 
 ### Refresh
 Re-scan the \`.letta/agents/\` directories to discover new or updated custom subagents:
@@ -8650,6 +8652,57 @@ Use this after creating or modifying custom subagent definitions.
 - **Parallel execution**: Launch multiple agents concurrently by calling Task multiple times in a single response
 - **Specify return format**: Tell agents exactly what information to include in their report
 
+## Deploying an Existing Agent
+
+Instead of spawning a fresh subagent from a template, you can deploy an existing agent to work in your local codebase.
+
+### Access Levels (subagent_type)
+Use subagent_type to control what tools the deployed agent can access:
+- **explore**: Read-only access (Read, Glob, Grep) - safer for exploration tasks
+- **general-purpose**: Full read-write access (Bash, Edit, Write, etc.) - for implementation tasks
+
+If subagent_type is not specified when deploying an existing agent, it defaults to "general-purpose".
+
+### Parameters
+
+- **agent_id**: The ID of an existing agent to deploy (e.g., "agent-abc123")
+  - Starts a new conversation with that agent
+  - The agent keeps its own system prompt and memory
+  - Tool access is controlled by subagent_type
+
+- **conversation_id**: Resume from an existing conversation (e.g., "conv-xyz789")
+  - Does NOT require agent_id (conversation IDs are unique and encode the agent)
+  - Continues from the conversation's existing message history
+  - Use this to continue context from:
+    - A prior Task tool invocation that returned a conversation_id
+    - A message thread started via the messaging-agents skill
+
+### Examples
+
+\`\`\`typescript
+// Deploy agent with read-only access
+Task({
+  agent_id: "agent-abc123",
+  subagent_type: "explore",
+  description: "Find auth code",
+  prompt: "Find all auth-related code in this codebase"
+})
+
+// Deploy agent with full access (default)
+Task({
+  agent_id: "agent-abc123",
+  description: "Fix auth bug",
+  prompt: "Fix the bug in auth.ts"
+})
+
+// Continue an existing conversation
+Task({
+  conversation_id: "conv-xyz789",
+  description: "Continue implementation",
+  prompt: "Now implement the fix we discussed"
+})
+\`\`\`
+
 ## Examples:
 
 \`\`\`typescript
@@ -19848,6 +19901,9 @@ function handleInitEvent(event, state, baseURL, subagentId) {
     const agentURL = `${baseURL}/agents/${event.agent_id}`;
     updateSubagent(subagentId, { agentURL });
   }
+  if (event.conversation_id) {
+    state.conversationId = event.conversation_id;
+  }
 }
 function handleApprovalRequestEvent(event, state) {
   const toolCalls = Array.isArray(event.tool_calls) ? event.tool_calls : event.tool_call ? [event.tool_call] : [];
@@ -19947,18 +20003,24 @@ function parseResultFromStdout(stdout, agentId) {
     };
   }
 }
-function buildSubagentArgs(type, config, model, userPrompt, preloadedSkillsContent) {
-  const args = [
-    "--new-agent",
-    "--system",
-    type,
-    "--model",
-    model,
-    "-p",
-    userPrompt,
-    "--output-format",
-    "stream-json"
-  ];
+function buildSubagentArgs(type, config, model, userPrompt, existingAgentId, existingConversationId, preloadedSkillsContent) {
+  const args = [];
+  const isDeployingExisting = Boolean(existingAgentId || existingConversationId);
+  if (isDeployingExisting) {
+    if (existingConversationId) {
+      args.push("--conv", existingConversationId);
+    } else if (existingAgentId) {
+      args.push("--agent", existingAgentId);
+    }
+    args.push("--no-skills");
+  } else {
+    args.push("--new-agent", "--system", type);
+    if (model) {
+      args.push("--model", model);
+    }
+  }
+  args.push("-p", userPrompt);
+  args.push("--output-format", "stream-json");
   const subagentMode = config.permissionMode;
   const parentMode = permissionMode.getMode();
   const modeToUse = subagentMode || parentMode;
@@ -19967,8 +20029,9 @@ function buildSubagentArgs(type, config, model, userPrompt, preloadedSkillsConte
   }
   const parentAllowedTools = cliPermissions.getAllowedTools();
   const sessionAllowRules = sessionPermissions.getRules().allow || [];
+  const subagentTools = config.allowedTools !== "all" && Array.isArray(config.allowedTools) ? config.allowedTools : [];
   const combinedAllowedTools = [
-    ...new Set([...parentAllowedTools, ...sessionAllowRules])
+    ...new Set([...parentAllowedTools, ...sessionAllowRules, ...subagentTools])
   ];
   if (combinedAllowedTools.length > 0) {
     args.push("--allowedTools", combinedAllowedTools.join(","));
@@ -19977,20 +20040,22 @@ function buildSubagentArgs(type, config, model, userPrompt, preloadedSkillsConte
   if (parentDisallowedTools.length > 0) {
     args.push("--disallowedTools", parentDisallowedTools.join(","));
   }
-  if (config.memoryBlocks === "none") {
-    args.push("--init-blocks", "none");
-  } else if (Array.isArray(config.memoryBlocks) && config.memoryBlocks.length > 0) {
-    args.push("--init-blocks", config.memoryBlocks.join(","));
+  if (!isDeployingExisting) {
+    if (config.memoryBlocks === "none") {
+      args.push("--init-blocks", "none");
+    } else if (Array.isArray(config.memoryBlocks) && config.memoryBlocks.length > 0) {
+      args.push("--init-blocks", config.memoryBlocks.join(","));
+    }
   }
   if (config.allowedTools !== "all" && Array.isArray(config.allowedTools) && config.allowedTools.length > 0) {
     args.push("--tools", config.allowedTools.join(","));
   }
-  if (preloadedSkillsContent) {
+  if (!isDeployingExisting && preloadedSkillsContent) {
     args.push("--block-value", `loaded_skills=${preloadedSkillsContent}`);
   }
   return args;
 }
-async function executeSubagent(type, config, model, userPrompt, baseURL, subagentId, isRetry = false, signal) {
+async function executeSubagent(type, config, model, userPrompt, baseURL, subagentId, isRetry = false, signal, existingAgentId, existingConversationId) {
   if (signal?.aborted) {
     return {
       agentId: "",
@@ -19999,14 +20064,17 @@ async function executeSubagent(type, config, model, userPrompt, baseURL, subagen
       error: INTERRUPTED_BY_USER
     };
   }
-  updateSubagent(subagentId, { model });
+  if (model) {
+    updateSubagent(subagentId, { model });
+  }
   try {
     let preloadedSkillsContent;
     if (config.skills && config.skills.length > 0) {
       preloadedSkillsContent = await preloadSkillsContent(config.skills, SKILLS_DIR);
     }
-    const cliArgs = buildSubagentArgs(type, config, model, userPrompt, preloadedSkillsContent);
-    const lettaCmd = process.env.LETTA_CODE_BIN || "letta";
+    const cliArgs = buildSubagentArgs(type, config, model, userPrompt, existingAgentId, existingConversationId, preloadedSkillsContent);
+    const currentScript = process.argv[1] || "";
+    const lettaCmd = process.env.LETTA_CODE_BIN || (currentScript.endsWith(".js") ? currentScript : null) || (currentScript.includes("src/index.ts") ? "./letta.js" : null) || "letta";
     let parentAgentId;
     try {
       parentAgentId = getCurrentAgentId();
@@ -20028,7 +20096,8 @@ async function executeSubagent(type, config, model, userPrompt, baseURL, subagen
     const stdoutChunks = [];
     const stderrChunks = [];
     const state = {
-      agentId: null,
+      agentId: existingAgentId || null,
+      conversationId: existingConversationId || null,
       finalResult: null,
       finalError: null,
       resultStats: null,
@@ -20055,6 +20124,7 @@ async function executeSubagent(type, config, model, userPrompt, baseURL, subagen
     if (wasAborted) {
       return {
         agentId: state.agentId || "",
+        conversationId: state.conversationId || undefined,
         report: "",
         success: false,
         error: INTERRUPTED_BY_USER
@@ -20070,6 +20140,7 @@ async function executeSubagent(type, config, model, userPrompt, baseURL, subagen
       }
       return {
         agentId: state.agentId || "",
+        conversationId: state.conversationId || undefined,
         report: "",
         success: false,
         error: stderr || `Subagent exited with code ${exitCode}`
@@ -20078,6 +20149,7 @@ async function executeSubagent(type, config, model, userPrompt, baseURL, subagen
     if (state.finalResult !== null) {
       return {
         agentId: state.agentId || "",
+        conversationId: state.conversationId || undefined,
         report: state.finalResult,
         success: !state.finalError,
         error: state.finalError || undefined,
@@ -20087,6 +20159,7 @@ async function executeSubagent(type, config, model, userPrompt, baseURL, subagen
     if (state.finalError) {
       return {
         agentId: state.agentId || "",
+        conversationId: state.conversationId || undefined,
         report: "",
         success: false,
         error: state.finalError,
@@ -20112,7 +20185,17 @@ function getBaseURL() {
   }
   return baseURL;
 }
-async function spawnSubagent(type, prompt, userModel, subagentId, signal) {
+function buildDeploySystemReminder(senderAgentName, senderAgentId, subagentType) {
+  const toolDescription = subagentType === "explore" ? "read-only tools (Read, Glob, Grep)" : "local tools (Bash, Read, Write, Edit, etc.)";
+  return `<system-reminder>
+This task is from "${senderAgentName}" (agent ID: ${senderAgentId}), which deployed you as a subagent inside the Letta Code CLI (docs.letta.com/letta-code).
+You have access to ${toolDescription} in their codebase.
+Your final message will be returned to the caller.
+</system-reminder>
+
+`;
+}
+async function spawnSubagent(type, prompt, userModel, subagentId, signal, existingAgentId, existingConversationId) {
   const allConfigs = await getAllSubagentConfigs();
   const config = allConfigs[type];
   if (!config) {
@@ -20123,9 +20206,20 @@ async function spawnSubagent(type, prompt, userModel, subagentId, signal) {
       error: `Unknown subagent type: ${type}`
     };
   }
-  const model = userModel || config.recommendedModel;
+  const isDeployingExisting = Boolean(existingAgentId || existingConversationId);
+  const model = isDeployingExisting ? null : userModel || config.recommendedModel;
   const baseURL = getBaseURL();
-  const result = await executeSubagent(type, config, model, prompt, baseURL, subagentId, false, signal);
+  let finalPrompt = prompt;
+  if (isDeployingExisting) {
+    try {
+      const parentAgentId = getCurrentAgentId();
+      const client = await getClient2();
+      const parentAgent = await client.agents.retrieve(parentAgentId);
+      const systemReminder = buildDeploySystemReminder(parentAgent.name, parentAgentId, type);
+      finalPrompt = systemReminder + prompt;
+    } catch {}
+  }
+  const result = await executeSubagent(type, config, model, finalPrompt, baseURL, subagentId, false, signal, existingAgentId, existingConversationId);
   return result;
 }
 var init_manager2 = __esm(async () => {
@@ -20162,19 +20256,27 @@ async function task(args) {
     const errorSuffix = errors.length > 0 ? `, ${errors.length} error(s)` : "";
     return `Refreshed subagents list: found ${totalCount} total (${customCount} custom)${errorSuffix}`;
   }
-  validateRequiredParams(args, ["subagent_type", "prompt", "description"], "Task");
-  const subagent_type = args.subagent_type;
+  const isDeployingExisting = Boolean(args.agent_id || args.conversation_id);
+  if (isDeployingExisting) {
+    validateRequiredParams(args, ["prompt", "description"], "Task");
+  } else {
+    validateRequiredParams(args, ["subagent_type", "prompt", "description"], "Task");
+  }
   const prompt = args.prompt;
   const description = args.description;
+  const subagent_type = isDeployingExisting ? args.subagent_type || "general-purpose" : args.subagent_type;
   const allConfigs = await getAllSubagentConfigs();
   if (!(subagent_type in allConfigs)) {
     const available = Object.keys(allConfigs).join(", ");
     return `Error: Invalid subagent type "${subagent_type}". Available types: ${available}`;
   }
+  if (isDeployingExisting && !VALID_DEPLOY_TYPES.has(subagent_type)) {
+    return `Error: When deploying an existing agent, subagent_type must be "explore" (read-only) or "general-purpose" (read-write). Got: "${subagent_type}"`;
+  }
   const subagentId = generateSubagentId();
   registerSubagent(subagentId, subagent_type, description, toolCallId);
   try {
-    const result = await spawnSubagent(subagent_type, prompt, model, subagentId, signal);
+    const result = await spawnSubagent(subagent_type, prompt, model, subagentId, signal, args.agent_id, args.conversation_id);
     completeSubagent(subagentId, {
       success: result.success,
       error: result.error,
@@ -20185,7 +20287,8 @@ async function task(args) {
     }
     const header = [
       `subagent_type=${subagent_type}`,
-      result.agentId ? `agent_id=${result.agentId}` : undefined
+      result.agentId ? `agent_id=${result.agentId}` : undefined,
+      result.conversationId ? `conversation_id=${result.conversationId}` : undefined
     ].filter(Boolean).join(" ");
     const fullOutput = `${header}
 
@@ -20199,11 +20302,13 @@ ${result.report}`;
     return `Error: ${errorMessage}`;
   }
 }
+var VALID_DEPLOY_TYPES;
 var init_Task2 = __esm(async () => {
   init_subagents();
   init_subagentState();
   init_truncation();
   await init_manager2();
+  VALID_DEPLOY_TYPES = new Set(["explore", "general-purpose"]);
 });
 
 // src/tools/impl/TodoWrite.ts
@@ -53417,7 +53522,8 @@ async function handleHeadlessCommand(argv, model, skillsDirectory) {
       sleeptime: { type: "boolean" },
       "init-blocks": { type: "string" },
       "base-tools": { type: "string" },
-      "from-af": { type: "string" }
+      "from-af": { type: "string" },
+      "no-skills": { type: "boolean" }
     },
     strict: false,
     allowPositionals: true
@@ -53732,7 +53838,18 @@ Usage: letta -p "..." --new-agent`);
     }
   }
   let conversationId;
-  const isolatedBlockLabels = initBlocks === undefined ? [...ISOLATED_BLOCK_LABELS] : ISOLATED_BLOCK_LABELS.filter((label) => initBlocks.includes(label));
+  const noSkillsFlag = values["no-skills"];
+  const isSubagent = process.env.LETTA_CODE_AGENT_ROLE === "subagent";
+  if (!noSkillsFlag && !isSubagent) {
+    const createdBlocks = await ensureSkillsBlocks(agent.id);
+    if (createdBlocks.length > 0) {
+      console.log("Created missing skills blocks for agent compatibility");
+    }
+  }
+  let isolatedBlockLabels = [];
+  if (!noSkillsFlag) {
+    isolatedBlockLabels = initBlocks === undefined ? [...ISOLATED_BLOCK_LABELS] : ISOLATED_BLOCK_LABELS.filter((label) => initBlocks.includes(label));
+  }
   if (specifiedConversationId) {
     if (specifiedConversationId === "default") {
       conversationId = "default";
@@ -53778,7 +53895,6 @@ Usage: letta -p "..." --new-agent`);
     conversationId = conversation.id;
   }
   markMilestone("HEADLESS_CONVERSATION_READY");
-  const isSubagent = process.env.LETTA_CODE_AGENT_ROLE === "subagent";
   if (!isSubagent) {
     await settingsManager.loadLocalProjectSettings();
     settingsManager.setLocalLastSession({ agentId: agent.id, conversationId }, process.cwd());
@@ -53787,24 +53903,22 @@ Usage: letta -p "..." --new-agent`);
       conversationId
     });
   }
-  const createdBlocks = await ensureSkillsBlocks(agent.id);
-  if (createdBlocks.length > 0) {
-    console.log("Created missing skills blocks for agent compatibility");
-  }
   setAgentContext2(agent.id, skillsDirectory);
-  initializeLoadedSkillsFlag2().catch(() => {});
-  (async () => {
-    try {
-      const { syncSkillsToAgent: syncSkillsToAgent3, SKILLS_DIR: SKILLS_DIR3 } = await Promise.resolve().then(() => (init_skills2(), exports_skills));
-      const { join: join17 } = await import("node:path");
-      const resolvedSkillsDirectory = skillsDirectory || join17(process.cwd(), SKILLS_DIR3);
-      await syncSkillsToAgent3(client, agent.id, resolvedSkillsDirectory, {
-        skipIfUnchanged: true
-      });
-    } catch (error) {
-      console.warn(`[skills] Background sync failed: ${error instanceof Error ? error.message : String(error)}`);
-    }
-  })();
+  if (!noSkillsFlag && !isSubagent) {
+    initializeLoadedSkillsFlag2().catch(() => {});
+    (async () => {
+      try {
+        const { syncSkillsToAgent: syncSkillsToAgent3, SKILLS_DIR: SKILLS_DIR3 } = await Promise.resolve().then(() => (init_skills2(), exports_skills));
+        const { join: join17 } = await import("node:path");
+        const resolvedSkillsDirectory = skillsDirectory || join17(process.cwd(), SKILLS_DIR3);
+        await syncSkillsToAgent3(client, agent.id, resolvedSkillsDirectory, {
+          skipIfUnchanged: true
+        });
+      } catch (error) {
+        console.warn(`[skills] Background sync failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    })();
+  }
   const outputFormat = values["output-format"] || "text";
   const includePartialMessages = Boolean(values["include-partial-messages"]);
   if (!["text", "json", "stream-json"].includes(outputFormat)) {
@@ -75139,6 +75253,7 @@ function App2({
   const [autoDeniedApprovals, setAutoDeniedApprovals] = import_react84.useState([]);
   const executingToolCallIdsRef = import_react84.useRef([]);
   const interruptQueuedRef = import_react84.useRef(false);
+  const toolResultsInFlightRef = import_react84.useRef(false);
   const autoAllowedExecutionRef = import_react84.useRef(null);
   const queuedApprovalMetadataRef = import_react84.useRef(null);
   const queueApprovalResults = import_react84.useCallback((results, metadata) => {
@@ -76147,12 +76262,14 @@ ${newState.originalPrompt}`
               }
               setThinkingMessage(getRandomThinkingVerb());
               refreshDerived();
+              toolResultsInFlightRef.current = true;
               await processConversation([
                 {
                   type: "approval",
                   approvals: allResults
                 }
               ], { allowReentry: true });
+              toolResultsInFlightRef.current = false;
               return;
             }
             if (waitingForQueueCancelRef.current) {
@@ -76198,6 +76315,7 @@ ${newState.originalPrompt}`
               toolAbortControllerRef.current = null;
               executingToolCallIdsRef.current = [];
               autoAllowedExecutionRef.current = null;
+              toolResultsInFlightRef.current = false;
             }
           }
           if (userCancelledRef.current || abortControllerRef.current?.signal.aborted) {
@@ -76423,7 +76541,8 @@ ${newState.originalPrompt}`
     setMessageQueue([]);
   }, []);
   const handleInterrupt = import_react84.useCallback(async () => {
-    if (isExecutingTool && toolAbortControllerRef.current) {
+    const hasTrackedTools = executingToolCallIdsRef.current.length > 0 || autoAllowedExecutionRef.current?.results;
+    if (isExecutingTool && toolAbortControllerRef.current && hasTrackedTools && !toolResultsInFlightRef.current) {
       toolAbortControllerRef.current.abort();
       conversationGenerationRef.current += 1;
       processingConversationRef.current = 0;
@@ -76460,6 +76579,7 @@ ${newState.originalPrompt}`
       userCancelledRef.current = true;
       setStreaming(false);
       setIsExecutingTool(false);
+      toolResultsInFlightRef.current = false;
       refreshDerived();
       setTimeout(() => {
         userCancelledRef.current = false;
@@ -76485,6 +76605,7 @@ ${newState.originalPrompt}`
       conversationGenerationRef.current += 1;
       processingConversationRef.current = 0;
       setStreaming(false);
+      toolResultsInFlightRef.current = false;
       if (!toolsCancelled) {
         appendError(INTERRUPT_MESSAGE, true);
       }
@@ -76900,9 +77021,11 @@ ${newState.originalPrompt}`
           return { blocked: false };
         }
         if (allResults.length > 0) {
+          toolResultsInFlightRef.current = true;
           await processConversation([
             { type: "approval", approvals: allResults }
           ]);
+          toolResultsInFlightRef.current = false;
         }
       } finally {
         if (shouldTrackAutoAllowed) {
@@ -76910,6 +77033,7 @@ ${newState.originalPrompt}`
           toolAbortControllerRef.current = null;
           executingToolCallIdsRef.current = [];
           autoAllowedExecutionRef.current = null;
+          toolResultsInFlightRef.current = false;
         }
       }
       return { blocked: false };
@@ -78564,7 +78688,9 @@ DO NOT respond to these messages or otherwise consider them in your response unl
                   content: messageContent
                 }
               ];
+              toolResultsInFlightRef.current = true;
               await processConversation(initialInput2);
+              toolResultsInFlightRef.current = false;
               clearPlaceholdersInText(msg);
               return { submitted: true };
             } finally {
@@ -78573,6 +78699,7 @@ DO NOT respond to these messages or otherwise consider them in your response unl
                 toolAbortControllerRef.current = null;
                 executingToolCallIdsRef.current = [];
                 autoAllowedExecutionRef.current = null;
+                toolResultsInFlightRef.current = false;
               }
             }
           } else {
@@ -78879,18 +79006,21 @@ DO NOT respond to these messages or otherwise consider them in your response unl
         waitingForQueueCancelRef.current = false;
         queueSnapshotRef.current = [];
       } else {
+        toolResultsInFlightRef.current = true;
         await processConversation([
           {
             type: "approval",
             approvals: allResults
           }
         ]);
+        toolResultsInFlightRef.current = false;
       }
     } finally {
       setIsExecutingTool(false);
       toolAbortControllerRef.current = null;
       executingToolCallIdsRef.current = [];
       interruptQueuedRef.current = false;
+      toolResultsInFlightRef.current = false;
     }
   }, [
     approvalResults,
@@ -83936,7 +84066,8 @@ async function main() {
         "include-partial-messages": { type: "boolean" },
         skills: { type: "string" },
         sleeptime: { type: "boolean" },
-        "from-af": { type: "string" }
+        "from-af": { type: "string" },
+        "no-skills": { type: "boolean" }
       },
       strict: true,
       allowPositionals: true
@@ -84879,4 +85010,4 @@ Error during initialization: ${message}`);
 }
 main();
 
-//# debugId=32B4EFE259BB1E4B64756E2164756E21
+//# debugId=A2D04DEC6336411264756E2164756E21

package/package.json

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

package/skills/messaging-agents/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: messaging-agents
+description: Send messages to other agents on your server. Use when you need to communicate with, query, or delegate tasks to another agent.
+---
+
+# Messaging Agents
+
+This skill enables you to send messages to other agents on the same Letta server using the thread-safe conversations API.
+
+## When to Use This Skill
+
+- You need to ask another agent a question
+- You want to query an agent that has specialized knowledge
+- You need information that another agent has in their memory
+- You want to coordinate with another agent on a task
+
+## What the Target Agent Can and Cannot Do
+
+**The target agent CANNOT:**
+- Access your local environment (read/write files in your codebase)
+- Execute shell commands on your machine
+- Use your tools (Bash, Read, Write, Edit, etc.)
+
+**The target agent CAN:**
+- Use their own tools (whatever they have configured)
+- Access their own memory blocks
+- Make API calls if they have web/API tools
+- Search the web if they have web search tools
+- Respond with information from their knowledge/memory
+
+**Important:** This skill is for *communication* with other agents, not *delegation* of local work. The target agent runs in their own environment and cannot interact with your codebase.
+
+**Need local access?** If you need the target agent to access your local environment (read/write files, run commands), use the Task tool instead to deploy them as a subagent:
+```typescript
+Task({
+  agent_id: "agent-xxx",           // Deploy this existing agent
+  subagent_type: "explore",        // "explore" = read-only, "general-purpose" = read-write
+  prompt: "Look at the code in src/ and tell me about the architecture"
+})
+```
+This gives the agent access to your codebase while running as a subagent.
+
+## Finding an Agent to Message
+
+If you don't have a specific agent ID, use these skills to find one:
+
+### By Name or Tags
+Load the `finding-agents` skill to search for agents:
+```bash
+npx tsx <FINDING_AGENTS_SKILL_DIR>/scripts/find-agents.ts --query "agent-name"
+npx tsx <FINDING_AGENTS_SKILL_DIR>/scripts/find-agents.ts --tags "origin:letta-code"
+```
+
+### By Topic They Discussed
+Load the `searching-messages` skill to find which agent worked on something:
+```bash
+npx tsx <SEARCHING_MESSAGES_SKILL_DIR>/scripts/search-messages.ts --query "topic" --all-agents
+```
+Results include `agent_id` for each matching message.
+
+## Script Usage
+
+### Starting a New Conversation
+
+```bash
+npx tsx <SKILL_DIR>/scripts/start-conversation.ts --agent-id <id> --message "<text>"
+```
+
+**Arguments:**
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `--agent-id <id>` | Yes | Target agent ID to message |
+| `--message <text>` | Yes | Message to send |
+| `--timeout <ms>` | No | Max wait time in ms (default: 120000) |
+
+**Example:**
+```bash
+npx tsx <SKILL_DIR>/scripts/start-conversation.ts \
+  --agent-id agent-abc123 \
+  --message "What do you know about the authentication system?"
+```
+
+**Response:**
+```json
+{
+  "conversation_id": "conversation-xyz789",
+  "response": "The authentication system uses JWT tokens...",
+  "agent_id": "agent-abc123",
+  "agent_name": "BackendExpert"
+}
+```
+
+### Continuing a Conversation
+
+```bash
+npx tsx <SKILL_DIR>/scripts/continue-conversation.ts --conversation-id <id> --message "<text>"
+```
+
+**Arguments:**
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `--conversation-id <id>` | Yes | Existing conversation ID |
+| `--message <text>` | Yes | Follow-up message to send |
+| `--timeout <ms>` | No | Max wait time in ms (default: 120000) |
+
+**Example:**
+```bash
+npx tsx <SKILL_DIR>/scripts/continue-conversation.ts \
+  --conversation-id conversation-xyz789 \
+  --message "Can you explain more about the token refresh flow?"
+```
+
+## Understanding the Response
+
+- Scripts return only the **final assistant message** (not tool calls or reasoning)
+- 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 `--agent-id` targeting the other agent
+
+## How It Works
+
+When you send a message, the target agent receives it with a system reminder:
+```
+<system-reminder>
+This message is from "YourAgentName" (agent ID: agent-xxx), 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>
+```
+
+This helps the target agent understand the context and format their response appropriately.
+
+## Related Skills
+
+- **finding-agents**: Find agents by name, tags, or fuzzy search
+- **searching-messages**: Search past messages across agents, or view full conversation transcripts

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

@@ -0,0 +1,222 @@
+#!/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";
+
+// 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>
+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>
+
+`;
+}
+
+/**
+ * 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);
+    }
+  })();
+}

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

@@ -0,0 +1,225 @@
+#!/usr/bin/env npx tsx
+/**
+ * Start Conversation - Start a new conversation with an agent and send a message
+ *
+ * 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 start-conversation.ts --agent-id <id> --message "<text>"
+ *
+ * Options:
+ *   --agent-id <id>     Target agent ID to message (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";
+
+// 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 StartConversationOptions {
+  agentId: string;
+  message: string;
+  timeout?: number;
+}
+
+interface StartConversationResult {
+  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>
+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>
+
+`;
+}
+
+/**
+ * Start a new conversation with an agent and send a message
+ * @param client - Letta client instance
+ * @param options - Options including target agent ID and message
+ * @returns Conversation result with response and metadata
+ */
+export async function startConversation(
+  client: LettaClient,
+  options: StartConversationOptions,
+): Promise<StartConversationResult> {
+  const { agentId, message } = options;
+
+  // 1. Fetch target agent to validate existence and get name
+  const targetAgent = await client.agents.retrieve(agentId);
+
+  // 2. Fetch sender agent to get name for system reminder
+  const senderAgentId = getSenderAgentId();
+  const senderAgent = await client.agents.retrieve(senderAgentId);
+
+  // 3. Create new conversation
+  const conversation = await client.conversations.create({
+    agent_id: agentId,
+  });
+
+  // 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(conversation.id, {
+    input: fullMessage,
+  });
+
+  // 6. Consume stream and extract final assistant message
+  let finalResponse = "";
+  for await (const chunk of stream) {
+    if (process.env.DEBUG) {
+      console.error("Chunk:", JSON.stringify(chunk, null, 2));
+    }
+    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: conversation.id,
+    response: finalResponse,
+    agent_id: targetAgent.id,
+    agent_name: targetAgent.name,
+  };
+}
+
+function parseArgs(args: string[]): StartConversationOptions {
+  const agentIdIndex = args.indexOf("--agent-id");
+  if (agentIdIndex === -1 || agentIdIndex + 1 >= args.length) {
+    throw new Error("Missing required argument: --agent-id <agent-id>");
+  }
+  const agentId = args[agentIdIndex + 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: StartConversationOptions = { agentId, 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 startConversation(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 start-conversation.ts --agent-id <id> --message "<text>"
+
+Options:
+  --agent-id <id>     Target agent ID to message (required)
+  --message <text>    Message to send (required)
+  --timeout <ms>      Max wait time in ms (default: 120000)
+`);
+      process.exit(1);
+    }
+  })();
+}