replicas-engine 0.1.96 → 0.1.98

package/dist/src/index.js

@@ -1091,7 +1091,7 @@ function parseReplicasConfigString(content, filename) {
 }
 
 // ../shared/src/engine/environment.ts
-var DAYTONA_SNAPSHOT_ID = "12-04-2026-royal-york";
+var DAYTONA_SNAPSHOT_ID = "13-04-2026-phantom-subagent-fix";
 
 // ../shared/src/engine/types.ts
 var DEFAULT_CHAT_TITLES = {
@@ -2998,7 +2998,7 @@ var CodexManager = class extends CodingAgentManager {
 import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
 import { z } from "zod";
 var POLL_INTERVAL_MS = 2e3;
-var SUBAGENT_TIMEOUT_MS = 6e5;
+var DEFAULT_SUBAGENT_TIMEOUT_MS = 6e5;
 async function engineFetch(path4, options) {
   const baseUrl = `http://localhost:${ENGINE_ENV.REPLICAS_ENGINE_PORT}`;
   return fetch(`${baseUrl}${path4}`, {
@@ -3010,28 +3010,38 @@ async function engineFetch(path4, options) {
     }
   });
 }
-async function waitForChatCompletion(chatId) {
+async function waitForChatCompletion(chatId, timeoutMs = DEFAULT_SUBAGENT_TIMEOUT_MS) {
   const start = Date.now();
   await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
-  while (Date.now() - start < SUBAGENT_TIMEOUT_MS) {
+  while (Date.now() - start < timeoutMs) {
     const res = await engineFetch(`/chats/${chatId}`);
     if (!res.ok) {
       throw new Error(`Failed to poll chat ${chatId}: ${res.status}`);
     }
-    const data = await res.json();
+    let data;
+    try {
+      data = await res.json();
+    } catch {
+      throw new Error(`Failed to parse poll response for chat ${chatId} (chat may have been interrupted)`);
+    }
     if (!data.chat.processing) {
       return;
     }
     await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
   }
-  throw new Error(`Subagent chat ${chatId} timed out after ${SUBAGENT_TIMEOUT_MS}ms`);
+  throw new Error(`Subagent chat ${chatId} timed out after ${timeoutMs}ms`);
 }
 async function getChatFinalResponse(chatId) {
   const res = await engineFetch(`/chats/${chatId}/history`);
   if (!res.ok) {
     return "[Failed to retrieve subagent history]";
   }
-  const history = await res.json();
+  let history;
+  try {
+    history = await res.json();
+  } catch {
+    return "[Failed to parse subagent history (response may have been interrupted)]";
+  }
   const events = history.events || [];
   for (let i = events.length - 1; i >= 0; i--) {
     const event = events[i];
@@ -3083,7 +3093,8 @@ You will also receive the chatId so you can send follow-up messages or clean up
       provider: z.enum(["claude", "codex", "relay"]).describe("Which agent to use. Prefer codex for code writing, claude for exploration/analysis, relay for complex multi-step orchestration."),
       prompt: z.string().describe("The full prompt/instructions for the subagent. Be detailed - it has no context from your conversation."),
       model: z.string().optional().describe("Model override. Claude: opus, sonnet, haiku. Codex: gpt-5.4, gpt-5.3-codex, etc."),
-      title: z.string().optional().describe("Optional title for the subagent chat (for identification).")
+      title: z.string().optional().describe("Optional title for the subagent chat (for identification)."),
+      timeout_minutes: z.number().positive().optional().describe("Timeout in minutes for the subagent to complete (default: 10). Set higher for large tasks to avoid losing work.")
     },
     async (args) => {
       try {
@@ -3116,7 +3127,8 @@ You will also receive the chatId so you can send follow-up messages or clean up
           const err = await sendRes.text();
           return { content: [{ type: "text", text: `Failed to send message to subagent: ${err}` }], isError: true };
         }
-        await waitForChatCompletion(chatId);
+        const timeoutMs = args.timeout_minutes ? args.timeout_minutes * 6e4 : DEFAULT_SUBAGENT_TIMEOUT_MS;
+        await waitForChatCompletion(chatId, timeoutMs);
         const response = await getChatFinalResponse(chatId);
         return {
           content: [{
@@ -3142,7 +3154,8 @@ The tool blocks until the subagent completes and returns its response.`,
   {
     chatId: z.string().describe("The chat ID of the subagent (returned by spawn_agent)."),
     message: z.string().describe("The follow-up message to send."),
-    model: z.string().optional().describe("Optional model override for this message.")
+    model: z.string().optional().describe("Optional model override for this message."),
+    timeout_minutes: z.number().positive().optional().describe("Timeout in minutes for the subagent to complete (default: 10). Set higher for large tasks to avoid losing work.")
   },
   async (args) => {
     try {
@@ -3158,7 +3171,8 @@ The tool blocks until the subagent completes and returns its response.`,
         const err = await sendRes.text();
         return { content: [{ type: "text", text: `Failed to send message: ${err}` }], isError: true };
       }
-      await waitForChatCompletion(args.chatId);
+      const timeoutMs = args.timeout_minutes ? args.timeout_minutes * 6e4 : DEFAULT_SUBAGENT_TIMEOUT_MS;
+      await waitForChatCompletion(args.chatId, timeoutMs);
       const response = await getChatFinalResponse(args.chatId);
       return {
         content: [{
@@ -3305,15 +3319,41 @@ function getDelegationSection() {
 
 You have three subagent tools for spawning and managing agents that run in separate context windows:
 
-- **spawn_agent**: Create a new subagent with a specific provider (claude or codex), send it a prompt, and wait for its response. Returns the chatId and the agent's final response.
+- **spawn_agent**: Create a new subagent with a specific provider (claude or codex), send it a prompt, and wait for its response. Returns the chatId and the agent's final response. You can set a custom timeout via the timeout_minutes parameter (default: 10 minutes).
 - **message_agent**: Send a follow-up message to an existing subagent by chatId. Use for iteration, corrections, or additional requests in the same context.
 - **delete_agent**: Delete a subagent chat when you no longer need it.
 
-## When to delegate vs work directly
+## When to delegate vs work directly \u2014 the context efficiency rule
+
+Your primary resource is your context window. Every tool call result, every code snippet, every debug log you read consumes context that you cannot reclaim. The key question when deciding whether to delegate is: **will doing this work myself cost more context than delegating it?**
+
+**Do it directly** when the task is simple and context-light: a small edit, a quick search, running a single command, reading one file, answering a question from brief investigation. These cost little context and the overhead of explaining the task to a subagent would be greater.
+
+**Delegate to a subagent** when the work would pollute your context with large amounts of intermediate output. Examples:
+- Testing and debugging: Running a server, curling endpoints, reading error output, iterating on fixes \u2014 this cycle consumes enormous context. Delegate the entire test-and-fix loop to a subagent.
+- Large code writing across multiple files.
+- Exploring a large codebase where you'd need to read many files.
+- Any iterative work (trial-and-error debugging, running tests repeatedly, build-fix cycles).
+
+**The tradeoff**: Subagents start with zero context, so they may produce lower quality work if the task requires deep understanding of the project. Weigh this: is it more context-efficient for you to do the work directly (because explaining the full context to a subagent would be lengthy and the task itself is small), or is it more efficient to spend tokens on a thorough subagent prompt and keep your own context clean? When in doubt, if the work involves more than a few tool calls of iterative output (e.g., running commands and reacting to results), delegate it.
+
+## Parallel execution
+
+You can spawn multiple subagents in parallel by making multiple spawn_agent tool calls in a single response. Do this whenever you have independent tasks \u2014 do NOT call them sequentially if they don't depend on each other. For example, if you need to test three endpoints, spawn three subagents in one response, not one after another.
+
+## Testing your work
+
+After implementing changes, verify they work. Scale testing to the complexity of the task:
+
+- **Small changes** (updating one endpoint, fixing a bug): A quick direct verification is sufficient.
+- **Medium changes** (new feature, multiple files): Spawn a subagent to run tests or verify the feature works end-to-end.
+- **Large/complex changes** (new system, many features, full application): Spawn multiple parallel subagents to test different aspects thoroughly. For example, test each endpoint or feature independently via separate subagents. Do not skip testing on complex work \u2014 missing features and broken functionality are worse than the token cost of verification.
+
+Do not burn tokens for the sake of it. Match testing depth to the risk and complexity of the change.
 
-Do it directly when the task is simple: a small edit, a quick search, running a single command, answering a question that needs brief investigation.
+## Subagent timeouts
 
-Spawn subagents when the task involves writing substantial code across multiple files, exploring a large codebase, running extensive tests, or any work that would consume significant context. Use subagents to parallelize independent pieces of work.
+The default subagent timeout is 10 minutes. For tasks you expect to take longer (large implementations, extensive test suites, complex debugging), set a generous timeout using the timeout_minutes parameter on spawn_agent. For example, a subagent building a full feature might need 20-30 minutes. If a subagent times out, you lose all of its work, so err on the side of generous timeouts for substantial tasks.
 
 ## Agent selection
 
@@ -3326,7 +3366,7 @@ Use provider 'claude' for codebase exploration, code review, planning, complex d
 - Subagents start with a blank context. Include all relevant file paths, code snippets, requirements, and constraints in the prompt.
 - Give each subagent a focused, specific task. Don't ask one agent to do everything.
 - After a subagent completes, review its output. Send follow-up messages for corrections, or verify changes with your direct tools.
-- Delete subagent chats with delete_agent when done to free resources.
+- Do NOT proactively delete subagent chats. Only use delete_agent when the user explicitly asks you to clean up or delete agents. Keeping subagents around allows the user to inspect their work and allows you to send follow-up messages if needed.
 - Use provider 'relay' for complex multi-step tasks that themselves benefit from orchestration and delegation.
 - Do not over-delegate. Spawning an agent for a trivial edit wastes time.`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "replicas-engine",
-  "version": "0.1.96",
+  "version": "0.1.98",
   "description": "Lightweight API server for Replicas workspaces",
   "type": "module",
   "main": "dist/src/index.js",