replicas-engine 0.1.851 → 0.1.852

package/README.md

@@ -33,6 +33,17 @@ Chats:
 - `POST /chats/:chatId/messages`
 - `POST /chats/:chatId/interrupt`
 
+Relay subagents:
+
+- `GET /chats/:parentChatId/subagents`
+- `POST /chats/:parentChatId/subagents`
+- `POST /chats/:parentChatId/subagents/:subagentId/messages`
+- `GET /chats/:parentChatId/subagents/:subagentId`
+- `GET /chats/:parentChatId/subagents/:subagentId/wait?timeoutMinutes=<minutes>` (SSE)
+- `DELETE /chats/:parentChatId/subagents/:subagentId`
+
+The `subagent_relay` MCP server exposes child work through `spawn_agent`, `message_agent`, `get_agent`, and `wait_agent`. Spawn and message calls wait by default; set `blocking: false` to return the child chat ID immediately, then use `get_agent` or `wait_agent` later. A wait timeout returns `status: "working"` with `timedOut: true` without interrupting the child; completed work returns `status: "completed"` and its response.
+
 Canvas:
 
 - `GET /canvas`

package/dist/src/{asp-host-JLTBSIYU.js → asp-host-BTHMIOWF.js}

@@ -5,11 +5,11 @@ import {
   getCodexAspHost,
   restartCodexAspHost,
   restartCodexAspHostIfRunning
-} from "./chunk-ZMZB2VED.js";
-import "./chunk-Q5TVOQAA.js";
-import "./chunk-MKFFAP4D.js";
+} from "./chunk-HPMBSWPV.js";
+import "./chunk-KCTWAJQL.js";
+import "./chunk-WABXMCX5.js";
 import "./chunk-UZSNFLDQ.js";
-import "./chunk-FEV3BCGC.js";
+import "./chunk-ICQTYE55.js";
 import "./chunk-VEQXQN22.js";
 export {
   getCodexAspHost,

package/dist/src/{chunk-IVALOOVU.js → chunk-FCGE52IS.js}

@@ -3,12 +3,12 @@ import { createRequire as __createRequire } from 'node:module';
 const require = __createRequire(import.meta.url);
 import {
   monolithRequest
-} from "./chunk-Q5TVOQAA.js";
+} from "./chunk-KCTWAJQL.js";
 import {
   extractCommandProtectionCommandText,
   findGitCommitSignals,
   findPrMergeSignals
-} from "./chunk-FEV3BCGC.js";
+} from "./chunk-ICQTYE55.js";
 
 // src/services/command-protection-service.ts
 var DEFAULT_COMMAND_PROTECTION_BLOCK_MESSAGE = "Blocked by Replicas command protection.";

package/dist/src/{chunk-ZMZB2VED.js → chunk-HPMBSWPV.js}

@@ -5,13 +5,13 @@ import {
   ENGINE_ENV,
   monolithRequest,
   setAgentCredentialSnapshot
-} from "./chunk-Q5TVOQAA.js";
+} from "./chunk-KCTWAJQL.js";
 import {
   AppServerProcess,
   SUBPROCESS_MAX_BUFFER,
   buildCodexAgentEnv,
   execFileAsync
-} from "./chunk-MKFFAP4D.js";
+} from "./chunk-WABXMCX5.js";
 import {
   isRecord
 } from "./chunk-UZSNFLDQ.js";
@@ -23,7 +23,7 @@ import {
   createSuccessResult,
   listOpenAICompatibleModels,
   resolveOpenAICompatibleModelsUrl
-} from "./chunk-FEV3BCGC.js";
+} from "./chunk-ICQTYE55.js";
 
 // src/managers/codex-token-manager.ts
 import { promises as fs } from "fs";
@@ -244,7 +244,7 @@ var CodexTokenManager = class extends BaseRefreshManager {
     await this.applyCredentialUpdate(++this.credentialGeneration, async () => {
       await this.applyCredentialsResponse(data);
       if (data.scope) setAgentCredentialSnapshot("codex", { method: data.type, scope: data.scope, revision: data.revision });
-      const { restartCodexAspHostIfRunning: restartCodexAspHostIfRunning2 } = await import("./asp-host-JLTBSIYU.js");
+      const { restartCodexAspHostIfRunning: restartCodexAspHostIfRunning2 } = await import("./asp-host-BTHMIOWF.js");
       await restartCodexAspHostIfRunning2();
     });
     await this.start(true);
@@ -264,7 +264,7 @@ var CodexTokenManager = class extends BaseRefreshManager {
     await this.applyCredentialUpdate(generation, async () => {
       await this.applyCredentialsResponse(data);
       if (restartOnChange && CODEX_AUTH_ENV_KEYS.some((key, index) => process.env[key] !== previousEnv[index])) {
-        const { restartCodexAspHostIfRunning: restartCodexAspHostIfRunning2 } = await import("./asp-host-JLTBSIYU.js");
+        const { restartCodexAspHostIfRunning: restartCodexAspHostIfRunning2 } = await import("./asp-host-BTHMIOWF.js");
         await restartCodexAspHostIfRunning2();
       }
       if (data.scope) {

package/dist/src/{chunk-FEV3BCGC.js → chunk-ICQTYE55.js}

@@ -992,14 +992,21 @@ var spawnRelaySubagentRequestSchema = z3.object({
   ).default("all"),
   model: z3.string().min(1).optional(),
   thinkingLevel: z3.enum(VALID_THINKING_LEVELS).optional(),
-  title: z3.string().min(1).optional(),
-  timeoutMinutes: z3.number().positive().max(1440).optional()
+  title: z3.string().min(1).optional()
 });
 var messageRelaySubagentRequestSchema = z3.object({
   message: z3.string().min(1),
   model: z3.string().min(1).optional(),
-  thinkingLevel: z3.enum(VALID_THINKING_LEVELS).optional(),
-  timeoutMinutes: z3.number().positive().max(1440).optional()
+  thinkingLevel: z3.enum(VALID_THINKING_LEVELS).optional()
+});
+var waitRelaySubagentRequestSchema = z3.object({
+  timeoutMinutes: z3.coerce.number().positive().max(1440).optional()
+});
+var relaySubagentResponseSchema = z3.object({
+  chatId: z3.string().uuid(),
+  status: z3.enum(["working", "completed"]),
+  response: z3.string().optional(),
+  timedOut: z3.literal(true).optional()
 });
 var sendChatMessageRequestSchema = z3.object({
   messageId: z3.string().min(1).optional(),
@@ -1555,6 +1562,47 @@ var headlessFilesystemAgentResultSchema = z4.object({
 // ../shared/src/engine/environment.ts
 var DESKTOP_STREAM_PORT = 6080;
 
+// ../shared/src/sse.ts
+function parseSseChunk(chunk) {
+  let data = "";
+  let id = null;
+  for (const line of chunk.split("\n")) {
+    if (line.startsWith("data: ")) {
+      data += line.slice(6);
+    } else if (line.startsWith("id: ")) {
+      id = line.slice(4);
+    }
+  }
+  if (!data) return null;
+  try {
+    return { event: JSON.parse(data), id };
+  } catch {
+    return null;
+  }
+}
+async function readSseStream(body, onEvent, shouldContinue = () => true) {
+  const reader = body.getReader();
+  const decoder2 = new TextDecoder();
+  let buffer = "";
+  try {
+    while (shouldContinue()) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder2.decode(value, { stream: true });
+      const chunks = buffer.split("\n\n");
+      buffer = chunks.pop() ?? "";
+      for (const chunk of chunks) {
+        if (!shouldContinue()) break;
+        const parsed = parseSseChunk(chunk);
+        if (!parsed) continue;
+        await onEvent(parsed.event, parsed.id);
+      }
+    }
+  } finally {
+    await reader.cancel().catch(() => void 0);
+  }
+}
+
 // ../shared/src/json.ts
 function safeJsonParse(str, fallback) {
   try {
@@ -7938,6 +7986,8 @@ export {
   createChatRequestSchema,
   spawnRelaySubagentRequestSchema,
   messageRelaySubagentRequestSchema,
+  waitRelaySubagentRequestSchema,
+  relaySubagentResponseSchema,
   sendChatMessageRequestSchema,
   isChatMessageSender,
   normalizeCodexAspTranscriptStatus,
@@ -8051,5 +8101,6 @@ export {
   getChatTranscriptHistorySize,
   createChatTranscriptPages,
   parseChatTranscriptArtifact,
+  readSseStream,
   isSkillRegistryManifest
 };

package/dist/src/{chunk-UOCB4U67.js → chunk-JQDFBEAW.js}

@@ -7,7 +7,15 @@ import { existsSync } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 import { createRequire } from "module";
-var RELAY_MCP_TOOL_NAMES = ["get_providers", "spawn_agent", "message_agent", "delete_agent"];
+var RELAY_MCP_TOOLS = {
+  getProviders: "get_providers",
+  spawnAgent: "spawn_agent",
+  getAgent: "get_agent",
+  waitAgent: "wait_agent",
+  messageAgent: "message_agent",
+  deleteAgent: "delete_agent"
+};
+var RELAY_MCP_TOOL_NAMES = Object.values(RELAY_MCP_TOOLS);
 var RELAY_MCP_TOOL_TIMEOUT_MS = 24 * 60 * 60 * 1e3 + 6e4;
 function relayMcpProcessConfig(parentChatId) {
   const directory = dirname(fileURLToPath(import.meta.url));
@@ -37,6 +45,7 @@ function relayCodexMcpConfig(parentChatId) {
 }
 
 export {
+  RELAY_MCP_TOOLS,
   RELAY_MCP_TOOL_NAMES,
   RELAY_MCP_TOOL_TIMEOUT_MS,
   relayMcpProcessConfig,

package/dist/src/{chunk-Q5TVOQAA.js → chunk-KCTWAJQL.js}

@@ -15,7 +15,7 @@ import {
   isValidRelayBaseProvider,
   parsePosixEnvFile,
   readReplicasRuntimeEnv
-} from "./chunk-FEV3BCGC.js";
+} from "./chunk-ICQTYE55.js";
 
 // src/engine-env.ts
 import { readFileSync as readFileSync2 } from "fs";

package/dist/src/{chunk-MKFFAP4D.js → chunk-WABXMCX5.js}

@@ -4,7 +4,7 @@ const require = __createRequire(import.meta.url);
 import {
   HOOK_EXEC_MAX_BUFFER_BYTES,
   isVersionBelow
-} from "./chunk-FEV3BCGC.js";
+} from "./chunk-ICQTYE55.js";
 
 // src/utils/codex-agent-env.ts
 function buildCodexAgentEnv(source = process.env) {
@@ -241,7 +241,7 @@ var DEFAULT_CODEX_ARGS = [
 var MIN_CODEX_CLI_VERSION = "0.153.3";
 var CODEX_UPGRADE_TIMEOUT_MS = 12e4;
 var codexCliVersionEnsured = null;
-var ENGINE_PACKAGE_VERSION = "0.1.851";
+var ENGINE_PACKAGE_VERSION = "0.1.852";
 var INITIALIZE_METHOD = "initialize";
 var INITIALIZED_NOTIFICATION = "initialized";
 var ACCOUNT_LOGIN_START_METHOD = "account/login/start";

package/dist/src/{chunk-MTSI4DXY.js → chunk-XZ56DHQ7.js}

@@ -3,7 +3,7 @@ import { createRequire as __createRequire } from 'node:module';
 const require = __createRequire(import.meta.url);
 import {
   shouldRefreshPullRequests
-} from "./chunk-FEV3BCGC.js";
+} from "./chunk-ICQTYE55.js";
 
 // src/services/post-tool-pr-notifier.ts
 async function notifyPostToolUse(toolName, toolInput) {

package/dist/src/command-protection-hook.js

@@ -3,12 +3,12 @@ import { createRequire as __createRequire } from 'node:module';
 const require = __createRequire(import.meta.url);
 import {
   evaluateCommandProtection
-} from "./chunk-IVALOOVU.js";
-import "./chunk-Q5TVOQAA.js";
+} from "./chunk-FCGE52IS.js";
+import "./chunk-KCTWAJQL.js";
 import {
   isRecord
 } from "./chunk-UZSNFLDQ.js";
-import "./chunk-FEV3BCGC.js";
+import "./chunk-ICQTYE55.js";
 import "./chunk-VEQXQN22.js";
 
 // src/command-protection-hook.ts

package/dist/src/deepseek-command-protection-plugin.js

@@ -3,13 +3,13 @@ import { createRequire as __createRequire } from 'node:module';
 const require = __createRequire(import.meta.url);
 import {
   evaluateCommandProtection
-} from "./chunk-IVALOOVU.js";
+} from "./chunk-FCGE52IS.js";
 import {
   notifyPostToolUse
-} from "./chunk-MTSI4DXY.js";
-import "./chunk-Q5TVOQAA.js";
+} from "./chunk-XZ56DHQ7.js";
+import "./chunk-KCTWAJQL.js";
 import "./chunk-UZSNFLDQ.js";
-import "./chunk-FEV3BCGC.js";
+import "./chunk-ICQTYE55.js";
 import "./chunk-VEQXQN22.js";
 
 // src/deepseek-command-protection-plugin.ts

package/dist/src/headless-agent.js

@@ -8,12 +8,12 @@ import {
 import {
   AppServerProcess,
   buildCodexAgentEnv
-} from "./chunk-MKFFAP4D.js";
+} from "./chunk-WABXMCX5.js";
 import {
   AGENT,
   getMemoryOutputSafetyViolation,
   headlessAgentRequestSchema
-} from "./chunk-FEV3BCGC.js";
+} from "./chunk-ICQTYE55.js";
 import "./chunk-VEQXQN22.js";
 
 // src/headless-agent.ts

package/dist/src/index.js

@@ -91,7 +91,7 @@ import {
   evaluateCommandProtection,
   extractToolCommand,
   reportCommandProtectionBlock
-} from "./chunk-IVALOOVU.js";
+} from "./chunk-FCGE52IS.js";
 import {
   ACCOUNT_RATE_LIMITS_UPDATED_METHOD,
   AGENT_MESSAGE_DELTA_METHOD,
@@ -115,11 +115,12 @@ import {
   recoverCompletedTurn
 } from "./chunk-FLDA7BX3.js";
 import {
+  RELAY_MCP_TOOLS,
   RELAY_MCP_TOOL_NAMES,
   RELAY_MCP_TOOL_TIMEOUT_MS,
   relayCodexMcpConfig,
   relayMcpProcessConfig
-} from "./chunk-UOCB4U67.js";
+} from "./chunk-JQDFBEAW.js";
 import {
   BaseRefreshManager,
   CodexAspAuthMethodChangedError,
@@ -131,20 +132,20 @@ import {
   recordCredentialFallback,
   recordExhaustedCredential,
   restartCodexAspHost
-} from "./chunk-ZMZB2VED.js";
+} from "./chunk-HPMBSWPV.js";
 import {
   ENGINE_ENV,
   IS_WARMING_MODE,
   monolithRequest,
   monolithService,
   setAgentCredentialSnapshot
-} from "./chunk-Q5TVOQAA.js";
+} from "./chunk-KCTWAJQL.js";
 import {
   AspClient,
   SUBPROCESS_MAX_BUFFER,
   execAsync,
   execFileAsync
-} from "./chunk-MKFFAP4D.js";
+} from "./chunk-WABXMCX5.js";
 import {
   isRecord as isRecord2
 } from "./chunk-UZSNFLDQ.js";
@@ -355,9 +356,10 @@ import {
   shouldRefreshPullRequests,
   spawnRelaySubagentRequestSchema,
   stripAgentDiagnosticErrors,
+  waitRelaySubagentRequestSchema,
   withTimeout,
   workspaceCredentialProviderSchema
-} from "./chunk-FEV3BCGC.js";
+} from "./chunk-ICQTYE55.js";
 import {
   __commonJS,
   __export,
@@ -59912,9 +59914,9 @@ Go straight to the point. Lead with outcomes and decisions, keep updates concise
 
 Your primary constraint is context. Work directly when the task is small, tightly coupled to context you already hold, or cheaper to complete than explain. Delegate independent work that would consume substantial context, including broad investigation, multi-file implementation, iterative debugging, test-and-fix loops, and unbiased review or verification. Do not delegate trivial work or work whose full context would cost more to transfer than doing it yourself.
 
-Use the \`${RELAY_MCP_SERVER_NAME}\` MCP server exclusively for delegation; never use terminal commands or the base harness's native agent-spawning, delegation, or collaboration tools. It exposes \`get_providers\`, \`spawn_agent\`, \`message_agent\`, and \`delete_agent\`; your harness may show them with an MCP server prefix. In Pi, call them through the \`mcp\` gateway for the \`${RELAY_MCP_SERVER_NAME}\` server if direct tools are not yet visible. Check \`get_providers\` before the first delegation instead of guessing. The default timeout is 10 minutes; increase it only when the task reasonably needs longer.
+Use the \`${RELAY_MCP_SERVER_NAME}\` MCP server exclusively for delegation; never use terminal commands or the base harness's native agent-spawning, delegation, or collaboration tools. It exposes ${RELAY_MCP_TOOL_NAMES.map((name) => `\`${name}\``).join(", ")}; your harness may show them with an MCP server prefix. In Pi, call them through the \`mcp\` gateway for the \`${RELAY_MCP_SERVER_NAME}\` server if direct tools are not yet visible. Check \`${RELAY_MCP_TOOLS.getProviders}\` before the first delegation instead of guessing. Spawning and messaging block by default; use \`blocking: false\` only when you intend to continue independently, then inspect or join the child with \`${RELAY_MCP_TOOLS.getAgent}\` or \`${RELAY_MCP_TOOLS.waitAgent}\`.
 
-Choose how much parent context each child inherits with \`spawn_agent.fork_turns\`:
+Choose how much parent context each child inherits with \`${RELAY_MCP_TOOLS.spawnAgent}.fork_turns\`:
 
 - \`"all"\` (default): inherit the conversation as an extension of yourself when the task depends on prior decisions and constraints.
 - \`"none"\`: start with only the task prompt to reduce input tokens or get an independent assessment without your prior reasoning. Include all necessary requirements, paths, constraints, and evidence in the prompt; the child cannot infer omitted context.
@@ -61627,7 +61629,6 @@ var LAST_MESSAGE_PREVIEW_MAX = 200;
 var MAX_ACCEPTED_SEND_RESPONSES = 50;
 var MAX_REMOVED_MESSAGE_IDS = 6e3;
 var RELAY_SUBAGENT_POLL_INTERVAL_MS = 2e3;
-var DEFAULT_RELAY_SUBAGENT_TIMEOUT_MS = 6e5;
 async function resolveRelayBaseProvider(provider, requested) {
   if (provider !== "relay") return null;
   return requested ?? (await monolithService.getRelayConfig())?.baseProvider ?? (!ENGINE_ENV.REPLICAS_WORKSPACE_ID ? DEFAULT_RELAY_BASE_PROVIDER : null);
@@ -61845,7 +61846,7 @@ var ChatService = class {
       });
       throw error;
     }
-    return this.waitForRelaySubagent(chat.id, request.timeoutMinutes);
+    return this.getRelaySubagent(parentChatId, chat.id);
   }
   async getRelaySubagentProviders(parentChatId) {
     const parent = this.requireChat(parentChatId);
@@ -61861,7 +61862,17 @@ var ChatService = class {
       ...request.model ? { model: request.model } : {},
       ...request.thinkingLevel ? { thinkingLevel: request.thinkingLevel } : {}
     });
-    return this.waitForRelaySubagent(chatId, request.timeoutMinutes);
+    return this.getRelaySubagent(parentChatId, chatId);
+  }
+  async getRelaySubagent(parentChatId, chatId) {
+    const chat = this.requireRelayChild(parentChatId, chatId);
+    if (hasActiveChatTurn(chat)) return { chatId, status: "working" };
+    const history = await chat.provider.getHistory();
+    return {
+      chatId,
+      status: "completed",
+      response: extractFinalResponse(history, getChatExecutionProvider(chat.persisted)) ?? "[No response from subagent]"
+    };
   }
   async deleteRelaySubagent(parentChatId, chatId) {
     this.requireRelayChild(parentChatId, chatId);
@@ -61874,24 +61885,19 @@ var ChatService = class {
     if (child.persisted.parentChatId !== parentChatId) throw new Error("Chat is not a child of this Relay chat");
     return child;
   }
-  async waitForRelaySubagent(chatId, timeoutMinutes) {
-    const timeoutMs = timeoutMinutes ? timeoutMinutes * 6e4 : DEFAULT_RELAY_SUBAGENT_TIMEOUT_MS;
+  async waitForRelaySubagent(parentChatId, chatId, timeoutMinutes, signal) {
+    const timeoutMs = timeoutMinutes ? timeoutMinutes * 6e4 : null;
     const startedAt = Date.now();
     while (true) {
-      const chat = this.requireChat(chatId);
-      if (!hasActiveChatTurn(chat)) {
-        const history = await chat.provider.getHistory();
-        return {
-          chatId,
-          response: extractFinalResponse(history, getChatExecutionProvider(chat.persisted)) ?? "[No response from subagent]"
-        };
-      }
-      const remainingMs = timeoutMs - (Date.now() - startedAt);
-      if (remainingMs <= 0) {
-        await this.interrupt(chatId);
-        throw new Error(`Subagent chat ${chatId} timed out after ${timeoutMs}ms`);
-      }
-      await new Promise((resolve7) => setTimeout(resolve7, Math.min(RELAY_SUBAGENT_POLL_INTERVAL_MS, remainingMs)));
+      if (signal?.aborted) throw new Error("Relay wait was cancelled");
+      const result = await this.getRelaySubagent(parentChatId, chatId);
+      if (result.status === "completed") return result;
+      const remainingMs = timeoutMs === null ? null : timeoutMs - (Date.now() - startedAt);
+      if (remainingMs !== null && remainingMs <= 0) return { ...result, timedOut: true };
+      await new Promise((resolve7) => setTimeout(
+        resolve7,
+        remainingMs === null ? RELAY_SUBAGENT_POLL_INTERVAL_MS : Math.min(RELAY_SUBAGENT_POLL_INTERVAL_MS, remainingMs)
+      ));
     }
   }
   async sendMessage(chatId, request) {
@@ -63919,6 +63925,47 @@ var updateTextFileSchema = (maxLength) => z6.object({
 function jsonError(message, details) {
   return { error: message, details };
 }
+function createJsonEventStream(run, onError) {
+  const encoder2 = new TextEncoder();
+  const stream = new ReadableStream({
+    start(controller) {
+      let closed = false;
+      const enqueue = (chunk) => {
+        if (closed) return false;
+        try {
+          controller.enqueue(encoder2.encode(chunk));
+          return true;
+        } catch {
+          closed = true;
+          return false;
+        }
+      };
+      const send = (data, event) => {
+        enqueue(`${event ? `event: ${event}
+` : ""}data: ${JSON.stringify(data)}
+
+`);
+      };
+      const heartbeat = setInterval(() => {
+        if (!enqueue(": ping\n\n")) clearInterval(heartbeat);
+      }, 15e3);
+      enqueue(": connected\n\n");
+      run(send).catch((error) => {
+        const failure = onError(error);
+        send(failure.data, failure.event);
+      }).finally(() => {
+        clearInterval(heartbeat);
+        if (!closed) {
+          closed = true;
+          controller.close();
+        }
+      });
+    }
+  });
+  return new Response(stream, {
+    headers: { "Content-Type": "text/event-stream", "Cache-Control": "no-cache", Connection: "keep-alive" }
+  });
+}
 function createV1Routes(deps) {
   const app2 = new Hono();
   app2.post("/pull-requests/check", async (c) => {
@@ -64054,6 +64101,42 @@ function createV1Routes(deps) {
       ), 400);
     }
   });
+  app2.get("/chats/:chatId/subagents/:subagentId", async (c) => {
+    try {
+      return c.json(await deps.chatService.getRelaySubagent(
+        c.req.param("chatId"),
+        c.req.param("subagentId")
+      ));
+    } catch (error) {
+      return c.json(jsonError(
+        "Failed to load Relay subagent",
+        error instanceof Error ? error.message : "Unknown error"
+      ), 400);
+    }
+  });
+  app2.get("/chats/:chatId/subagents/:subagentId/wait", async (c) => {
+    const parsed = waitRelaySubagentRequestSchema.safeParse(c.req.query());
+    if (!parsed.success) {
+      return c.json(jsonError("Failed to wait for Relay subagent", parsed.error.message), 400);
+    }
+    return createJsonEventStream(
+      async (send) => {
+        send(await deps.chatService.waitForRelaySubagent(
+          c.req.param("chatId"),
+          c.req.param("subagentId"),
+          parsed.data.timeoutMinutes,
+          c.req.raw.signal
+        ));
+      },
+      (error) => ({
+        event: "error",
+        data: {
+          error: "Failed to wait for Relay subagent",
+          details: error instanceof Error ? error.message : "Unknown error"
+        }
+      })
+    );
+  });
   app2.delete("/chats/:chatId/subagents/:subagentId", async (c) => {
     try {
       await deps.chatService.deleteRelaySubagent(c.req.param("chatId"), c.req.param("subagentId"));
@@ -64604,56 +64687,18 @@ data: ${JSON.stringify("Terminal session not found")}
   app2.post("/warm-hooks/run/stream", async (c) => {
     try {
       const body = await c.req.json();
-      const encoder2 = new TextEncoder();
-      const stream = new ReadableStream({
-        start: (controller) => {
-          let closed = false;
-          const safeEnqueue = (chunk) => {
-            if (closed) return false;
-            try {
-              controller.enqueue(encoder2.encode(chunk));
-              return true;
-            } catch {
-              closed = true;
-              return false;
-            }
-          };
-          const heartbeat = setInterval(() => {
-            if (!safeEnqueue(": ping\n\n")) clearInterval(heartbeat);
-          }, 15e3);
-          safeEnqueue(": connected\n\n");
-          runWarmHooksStreaming({
-            globalWarmHook: body.globalWarmHook,
-            environmentWarmHook: body.environmentWarmHook,
-            organizationWarmHook: body.organizationWarmHook,
-            timeoutMs: body.timeoutMs,
-            onEvent: (event) => {
-              safeEnqueue(`data: ${JSON.stringify(event)}
-
-`);
-            }
-          }).then(() => {
-            clearInterval(heartbeat);
-            if (!closed) {
-              closed = true;
-              controller.close();
-            }
-          }).catch((err) => {
-            const message = err instanceof Error ? err.message : "Unknown error";
-            safeEnqueue(`data: ${JSON.stringify({ type: "error", data: message })}
-
-`);
-            clearInterval(heartbeat);
-            if (!closed) {
-              closed = true;
-              controller.close();
-            }
-          });
-        }
-      });
-      return new Response(stream, {
-        headers: { "Content-Type": "text/event-stream", "Cache-Control": "no-cache", Connection: "keep-alive" }
-      });
+      return createJsonEventStream(
+        (send) => runWarmHooksStreaming({
+          globalWarmHook: body.globalWarmHook,
+          environmentWarmHook: body.environmentWarmHook,
+          organizationWarmHook: body.organizationWarmHook,
+          timeoutMs: body.timeoutMs,
+          onEvent: (event) => {
+            send(event);
+          }
+        }),
+        (error) => ({ data: { type: "error", data: error instanceof Error ? error.message : "Unknown error" } })
+      );
     } catch (error) {
       return c.json(
         jsonError("Failed to run warm hooks", error instanceof Error ? error.message : "Unknown error"),
@@ -64664,54 +64709,16 @@ data: ${JSON.stringify("Terminal session not found")}
   app2.post("/start-hooks/run/stream", async (c) => {
     try {
       const body = await c.req.json();
-      const encoder2 = new TextEncoder();
-      const stream = new ReadableStream({
-        start: (controller) => {
-          let closed = false;
-          const safeEnqueue = (chunk) => {
-            if (closed) return false;
-            try {
-              controller.enqueue(encoder2.encode(chunk));
-              return true;
-            } catch {
-              closed = true;
-              return false;
-            }
-          };
-          const heartbeat = setInterval(() => {
-            if (!safeEnqueue(": ping\n\n")) clearInterval(heartbeat);
-          }, 15e3);
-          safeEnqueue(": connected\n\n");
-          replicasConfigService.runStartHooksStreaming({
-            environmentStartHook: body.environmentStartHook,
-            timeoutMs: body.timeoutMs,
-            onEvent: (event) => {
-              safeEnqueue(`data: ${JSON.stringify(event)}
-
-`);
-            }
-          }).then(() => {
-            clearInterval(heartbeat);
-            if (!closed) {
-              closed = true;
-              controller.close();
-            }
-          }).catch((err) => {
-            const message = err instanceof Error ? err.message : "Unknown error";
-            safeEnqueue(`data: ${JSON.stringify({ type: "error", data: message })}
-
-`);
-            clearInterval(heartbeat);
-            if (!closed) {
-              closed = true;
-              controller.close();
-            }
-          });
-        }
-      });
-      return new Response(stream, {
-        headers: { "Content-Type": "text/event-stream", "Cache-Control": "no-cache", Connection: "keep-alive" }
-      });
+      return createJsonEventStream(
+        (send) => replicasConfigService.runStartHooksStreaming({
+          environmentStartHook: body.environmentStartHook,
+          timeoutMs: body.timeoutMs,
+          onEvent: (event) => {
+            send(event);
+          }
+        }),
+        (error) => ({ data: { type: "error", data: error instanceof Error ? error.message : "Unknown error" } })
+      );
     } catch (error) {
       return c.json(
         jsonError("Failed to run start hooks", error instanceof Error ? error.message : "Unknown error"),

package/dist/src/post-tool-pr-hook.js

@@ -3,11 +3,11 @@ import { createRequire as __createRequire } from 'node:module';
 const require = __createRequire(import.meta.url);
 import {
   notifyPostToolUse
-} from "./chunk-MTSI4DXY.js";
+} from "./chunk-XZ56DHQ7.js";
 import {
   isRecord
 } from "./chunk-UZSNFLDQ.js";
-import "./chunk-FEV3BCGC.js";
+import "./chunk-ICQTYE55.js";
 import "./chunk-VEQXQN22.js";
 
 // src/post-tool-pr-hook.ts

package/dist/src/relay-mcp.js

@@ -1,12 +1,17 @@
 #!/usr/bin/env node
 import { createRequire as __createRequire } from 'node:module';
 const require = __createRequire(import.meta.url);
-import "./chunk-UOCB4U67.js";
+import {
+  RELAY_MCP_TOOLS
+} from "./chunk-JQDFBEAW.js";
 import {
   RELAY_MCP_SERVER_NAME,
   messageRelaySubagentRequestSchema,
-  spawnRelaySubagentRequestSchema
-} from "./chunk-FEV3BCGC.js";
+  readSseStream,
+  relaySubagentResponseSchema,
+  spawnRelaySubagentRequestSchema,
+  waitRelaySubagentRequestSchema
+} from "./chunk-ICQTYE55.js";
 import "./chunk-VEQXQN22.js";
 
 // src/relay-mcp.ts
@@ -38,14 +43,37 @@ async function request(path, method, body) {
   if (!response.ok) throw new Error(text || `Relay request failed (${response.status})`);
   return text || JSON.stringify({ success: true });
 }
+async function waitForAgent(chatId, timeoutMinutes) {
+  const query = timeoutMinutes ? `?timeoutMinutes=${timeoutMinutes}` : "";
+  const response = await fetch(`http://localhost:${enginePort}/chats/${parentChatId}/subagents/${chatId}/wait${query}`, {
+    headers: {
+      Accept: "text/event-stream",
+      "X-Replicas-Engine-Secret": engineSecret
+    }
+  });
+  if (!response.ok || !response.body) throw new Error(await response.text() || `Relay wait failed (${response.status})`);
+  let result;
+  await readSseStream(response.body, (event) => {
+    const parsed = relaySubagentResponseSchema.safeParse(event);
+    if (parsed.success) {
+      result = JSON.stringify(parsed.data);
+      return;
+    }
+    const failure = z.object({ error: z.string(), details: z.string().optional() }).safeParse(event);
+    if (failure.success) throw new Error(failure.data.details || failure.data.error);
+    throw new Error("Relay wait stream returned an invalid response");
+  });
+  if (!result) throw new Error("Relay wait stream ended without a result");
+  return result;
+}
 var server = new McpServer({ name: RELAY_MCP_SERVER_NAME, version: "1.0.0" });
-server.registerTool("get_providers", {
+server.registerTool(RELAY_MCP_TOOLS.getProviders, {
   description: "List the agent providers Relay is allowed to use and the configured Relay base provider."
 }, async () => ({
   content: [{ type: "text", text: await request(`/chats/${parentChatId}/subagents`, "GET") }]
 }));
-server.registerTool("spawn_agent", {
-  description: "Spawn a child agent with all, none, or the latest N turns of parent context, wait for it to finish, and return its chat ID and final response.",
+server.registerTool(RELAY_MCP_TOOLS.spawnAgent, {
+  description: "Spawn a child agent with all, none, or the latest N turns of parent context. Blocks by default; set blocking to false to return its chat ID immediately.",
   inputSchema: {
     provider: spawnRelaySubagentRequestSchema.shape.provider.describe("Provider returned by get_providers."),
     prompt: spawnRelaySubagentRequestSchema.shape.prompt.describe("The child\u2019s assigned task, scope, and expected result. Include all necessary context when fork_turns is none."),
@@ -53,43 +81,55 @@ server.registerTool("spawn_agent", {
     model: spawnRelaySubagentRequestSchema.shape.model,
     thinking_level: spawnRelaySubagentRequestSchema.shape.thinkingLevel,
     title: spawnRelaySubagentRequestSchema.shape.title,
-    timeout_minutes: spawnRelaySubagentRequestSchema.shape.timeoutMinutes
+    blocking: z.boolean().optional().describe("Wait for the child to finish. Defaults to true."),
+    timeout_minutes: waitRelaySubagentRequestSchema.shape.timeoutMinutes.describe("Maximum time to wait without interrupting the child.")
   }
-}, async ({ provider, prompt, fork_turns, model, thinking_level, title, timeout_minutes }) => ({
-  content: [{
-    type: "text",
-    text: await request(`/chats/${parentChatId}/subagents`, "POST", {
-      provider,
-      prompt,
-      forkTurns: fork_turns,
-      ...model ? { model } : {},
-      ...thinking_level ? { thinkingLevel: thinking_level } : {},
-      ...title ? { title } : {},
-      ...timeout_minutes ? { timeoutMinutes: timeout_minutes } : {}
-    })
-  }]
+}, async ({ provider, prompt, fork_turns, model, thinking_level, title, blocking, timeout_minutes }) => {
+  const created = await request(`/chats/${parentChatId}/subagents`, "POST", {
+    provider,
+    prompt,
+    forkTurns: fork_turns,
+    ...model ? { model } : {},
+    ...thinking_level ? { thinkingLevel: thinking_level } : {},
+    ...title ? { title } : {}
+  });
+  const createdAgent = relaySubagentResponseSchema.parse(JSON.parse(created));
+  return { content: [{ type: "text", text: blocking === false ? created : await waitForAgent(createdAgent.chatId, timeout_minutes) }] };
+});
+server.registerTool(RELAY_MCP_TOOLS.getAgent, {
+  description: "Get the current status and final response, if available, for one of this Relay chat\u2019s child agents.",
+  inputSchema: { chat_id: z.string().uuid() }
+}, async ({ chat_id }) => ({
+  content: [{ type: "text", text: await request(`/chats/${parentChatId}/subagents/${chat_id}`, "GET") }]
+}));
+server.registerTool(RELAY_MCP_TOOLS.waitAgent, {
+  description: "Wait for one of this Relay chat\u2019s child agents to finish over a heartbeat stream. A timeout stops waiting without interrupting the child.",
+  inputSchema: {
+    chat_id: z.string().uuid(),
+    timeout_minutes: waitRelaySubagentRequestSchema.shape.timeoutMinutes
+  }
+}, async ({ chat_id, timeout_minutes }) => ({
+  content: [{ type: "text", text: await waitForAgent(chat_id, timeout_minutes) }]
 }));
-server.registerTool("message_agent", {
-  description: "Send a follow-up to one of this Relay chat\u2019s child agents, wait for it to finish, and return its final response.",
+server.registerTool(RELAY_MCP_TOOLS.messageAgent, {
+  description: "Send a follow-up to one of this Relay chat\u2019s child agents. Blocks by default; set blocking to false to return immediately.",
   inputSchema: {
     chat_id: z.string().uuid(),
     message: messageRelaySubagentRequestSchema.shape.message,
     model: messageRelaySubagentRequestSchema.shape.model,
     thinking_level: messageRelaySubagentRequestSchema.shape.thinkingLevel,
-    timeout_minutes: messageRelaySubagentRequestSchema.shape.timeoutMinutes
+    blocking: z.boolean().optional().describe("Wait for the child to finish. Defaults to true."),
+    timeout_minutes: waitRelaySubagentRequestSchema.shape.timeoutMinutes.describe("Maximum time to wait without interrupting the child.")
   }
-}, async ({ chat_id, message, model, thinking_level, timeout_minutes }) => ({
-  content: [{
-    type: "text",
-    text: await request(`/chats/${parentChatId}/subagents/${chat_id}/messages`, "POST", {
-      message,
-      ...model ? { model } : {},
-      ...thinking_level ? { thinkingLevel: thinking_level } : {},
-      ...timeout_minutes ? { timeoutMinutes: timeout_minutes } : {}
-    })
-  }]
-}));
-server.registerTool("delete_agent", {
+}, async ({ chat_id, message, model, thinking_level, blocking, timeout_minutes }) => {
+  const accepted = await request(`/chats/${parentChatId}/subagents/${chat_id}/messages`, "POST", {
+    message,
+    ...model ? { model } : {},
+    ...thinking_level ? { thinkingLevel: thinking_level } : {}
+  });
+  return { content: [{ type: "text", text: blocking === false ? accepted : await waitForAgent(chat_id, timeout_minutes) }] };
+});
+server.registerTool(RELAY_MCP_TOOLS.deleteAgent, {
   description: "Delete one of this Relay chat\u2019s child agents.",
   inputSchema: { chat_id: z.string().uuid() }
 }, async ({ chat_id }) => ({

package/package.json

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