@dreb/coding-agent 2.56.0 → 2.57.1

package/dist/core/tools/subagent.js

@@ -8,7 +8,7 @@ import { Text } from "@dreb/tui";
 import { Type } from "@sinclair/typebox";
 import { CONFIG_DIR_NAME, getPackageDir, getSubagentSessionsDir } from "../../config.js";
 import { keyHint } from "../../modes/interactive/components/keybinding-hints.js";
-import { attachJsonlLineReader } from "../../modes/rpc/jsonl.js";
+import { attachJsonlLineReader, serializeJsonLine } from "../../modes/rpc/jsonl.js";
 import { log } from "../logger.js";
 import { resolveCliModel } from "../model-resolver.js";
 import { resolveEffectiveThinkingLevel, thinkingLevelToReasoning, validateThinkingLevelForModel } from "../thinking.js";
@@ -226,7 +226,7 @@ export function handleChildJsonlLine(line, sinks) {
         sinks.onProgress(`${sinks.toolNameRef.current} done`);
     }
 }
-async function spawnSubagent(agentConfig, task, cwd, signal, onProgress, parentProvider, sessionDir, parentSessionFile, onChildEvent, thinkingOverride) {
+async function spawnSubagent(agentConfig, task, cwd, signal, onProgress, parentProvider, sessionDir, parentSessionFile, onChildEvent, thinkingOverride, onControlAvailable) {
     const drebBin = findDrebBinary();
     log.debug(`[subagent] spawn: agent=${agentConfig.name} cwd=${cwd}`);
     // Validate cwd exists — spawn() throws a misleading ENOENT blaming the
@@ -276,6 +276,12 @@ async function spawnSubagent(agentConfig, task, cwd, signal, onProgress, parentP
         args.push("--parent-session", parentSessionFile);
     }
     args.push("-p", task);
+    if (onControlAvailable) {
+        const rpcModeIndex = args.indexOf("json");
+        if (rpcModeIndex !== -1)
+            args[rpcModeIndex] = "rpc";
+        args.splice(args.length - 2, 2);
+    }
     // Early abort check — if the signal is already aborted (e.g. queued task whose
     // AbortController was aborted while waiting on bgAcquire), bail out before
     // spawning a child process that can never be killed. addEventListener("abort")
@@ -295,7 +301,7 @@ async function spawnSubagent(agentConfig, task, cwd, signal, onProgress, parentP
         try {
             proc = spawn(NODE_EXEC, [drebBin, ...args], {
                 cwd,
-                stdio: ["ignore", "pipe", "pipe"],
+                stdio: [onControlAvailable ? "pipe" : "ignore", "pipe", "pipe"],
                 env: { ...process.env },
             });
         }
@@ -313,6 +319,56 @@ async function spawnSubagent(agentConfig, task, cwd, signal, onProgress, parentP
         const toolNameRef = { current: "" };
         let resolvedModel;
         let resolvedThinking;
+        let rpcRequestId = 0;
+        let rpcCompleted = false;
+        let controlError;
+        const pendingRpc = new Map();
+        const sendRpc = (command) => {
+            if (!proc.stdin?.writable)
+                return Promise.reject(new Error("Subagent control channel is unavailable."));
+            const id = `subagent-${++rpcRequestId}`;
+            proc.stdin.write(serializeJsonLine({ ...command, id }));
+            return new Promise((resolve, reject) => pendingRpc.set(id, { resolve, reject }));
+        };
+        const controlClient = onControlAvailable
+            ? {
+                steer: async (message) => {
+                    await sendRpc({ type: "steer", message });
+                },
+                getPendingMessages: async () => sendRpc({ type: "get_pending_messages" }),
+                getState: async () => sendRpc({ type: "get_state" }),
+            }
+            : undefined;
+        // Terminally fail a controlled child: remember the first failure, reject all
+        // in-flight control requests, and stop the process (with the same SIGKILL
+        // backstop as the abort path) so the close handler settles instead of the
+        // child idling in RPC mode forever.
+        const failControlledChild = (err) => {
+            if (!controlError)
+                controlError = err;
+            for (const request of pendingRpc.values())
+                request.reject(err);
+            pendingRpc.clear();
+            try {
+                proc.kill("SIGTERM");
+            }
+            catch {
+                /* process already exited */
+            }
+            killTimer ??= setTimeout(() => {
+                try {
+                    if (!proc.killed)
+                        proc.kill("SIGKILL");
+                }
+                catch {
+                    /* process already exited */
+                }
+            }, 5000);
+        };
+        proc.stdin?.on("error", (err) => {
+            log.warn(`[subagent] stdin stream error (agent=${agentConfig.name}): ${err.message}`);
+            failControlledChild(err);
+        });
         // Drain stderr concurrently to avoid pipe deadlock (capped to prevent OOM from verbose subagents)
         proc.stderr?.on("data", (chunk) => {
             if (stderrSize < MAX_STDERR_BYTES) {
@@ -330,6 +386,36 @@ async function spawnSubagent(agentConfig, task, cwd, signal, onProgress, parentP
                 log.warn(`[subagent] stdout stream error (agent=${agentConfig.name}): ${err.message}`);
             });
             attachJsonlLineReader(proc.stdout, (line) => {
+                if (onControlAvailable) {
+                    try {
+                        const message = JSON.parse(line);
+                        if (message?.type === "agent_end" && !rpcCompleted) {
+                            rpcCompleted = true;
+                            setImmediate(() => proc.kill("SIGTERM"));
+                        }
+                        if (message?.type === "response" && typeof message.id === "string") {
+                            const pending = pendingRpc.get(message.id);
+                            if (pending) {
+                                pendingRpc.delete(message.id);
+                                if (message.success)
+                                    pending.resolve(message.data);
+                                else
+                                    pending.reject(new Error(message.error ?? "Subagent RPC command failed."));
+                            }
+                            else if (message.command === "prompt" && message.success === false && !rpcCompleted) {
+                                // Late failure of the initial prompt: the child acknowledged the
+                                // command synchronously, then failed before the agent loop started
+                                // (e.g. model/API-key validation, or the task was consumed without
+                                // starting the loop), so no agent_end will ever settle this process.
+                                failControlledChild(new Error(typeof message.error === "string" ? message.error : "Subagent prompt failed."));
+                            }
+                            return;
+                        }
+                    }
+                    catch {
+                        // The normal line handler preserves non-JSON diagnostics.
+                    }
+                }
                 handleChildJsonlLine(line, {
                     onEvent: onChildEvent,
                     onAssistantMessage: (message) => collectedMessages.push(message),
@@ -345,6 +431,16 @@ async function spawnSubagent(agentConfig, task, cwd, signal, onProgress, parentP
                 });
             });
         }
+        if (onControlAvailable && controlClient) {
+            onControlAvailable(controlClient);
+            void sendRpc({ type: "prompt", message: task }).catch((err) => {
+                const error = err instanceof Error ? err : new Error(String(err));
+                log.warn(`[subagent] initial RPC prompt failed (agent=${agentConfig.name}): ${error.message}`);
+                // A rejected initial prompt means the agent loop never starts and the
+                // child would idle in RPC mode forever — terminate it and fail loudly.
+                failControlledChild(error);
+            });
+        }
         // Handle abort signal (guard kill() against ESRCH race if process already exited)
         const onAbort = () => {
             try {
@@ -368,6 +464,10 @@ async function spawnSubagent(agentConfig, task, cwd, signal, onProgress, parentP
             if (settled)
                 return;
             settled = true;
+            onControlAvailable?.(undefined);
+            for (const request of pendingRpc.values())
+                request.reject(err);
+            pendingRpc.clear();
             if (killTimer)
                 clearTimeout(killTimer);
             signal?.removeEventListener("abort", onAbort);
@@ -377,10 +477,14 @@ async function spawnSubagent(agentConfig, task, cwd, signal, onProgress, parentP
             if (settled)
                 return;
             settled = true;
+            onControlAvailable?.(undefined);
+            for (const request of pendingRpc.values())
+                request.reject(new Error("Subagent process exited."));
+            pendingRpc.clear();
             if (killTimer)
                 clearTimeout(killTimer);
             signal?.removeEventListener("abort", onAbort);
-            const exitCode = code ?? 1;
+            const exitCode = rpcCompleted ? 0 : (code ?? 1);
             const stderr = stderrChunks.join("");
             log.debug(`[subagent] close: agent=${agentConfig.name} exit=${exitCode} messages=${collectedMessages.length}${exitCode !== 0 ? ` stderr=${stderr.slice(0, 200)} stdout=${plainStdoutLines.join("|").slice(0, 200)}` : ""}`);
             // Extract final text output from collected assistant messages
@@ -407,7 +511,10 @@ async function spawnSubagent(agentConfig, task, cwd, signal, onProgress, parentP
                 const stderrTrimmed = stderr.trim();
                 const plainOutput = plainStdoutLines.join("\n").trim();
                 errorMessage =
-                    stderrTrimmed.slice(0, 500) || plainOutput.slice(0, 500) || `Subagent exited with code ${exitCode}`;
+                    controlError?.message.slice(0, 500) ||
+                        stderrTrimmed.slice(0, 500) ||
+                        plainOutput.slice(0, 500) ||
+                        `Subagent exited with code ${exitCode}`;
             }
             else if (output.trim() === "") {
                 // Clean exit but no output — surface why instead of returning a silent empty result.
@@ -853,7 +960,7 @@ function clampCwd(defaultCwd, itemCwd) {
     }
     return { ok: true, cwd: resolved };
 }
-export async function executeSingle(agents, agentName, task, cwd, signal, onProgress, modelOverride, parentProvider, registry, sessionDir, parentModel, agentModels, parentSessionFile, onChildEvent, thinkingOverride, arbitration) {
+export async function executeSingle(agents, agentName, task, cwd, signal, onProgress, modelOverride, parentProvider, registry, sessionDir, parentModel, agentModels, parentSessionFile, onChildEvent, thinkingOverride, arbitration, onControlAvailable) {
     let name = agentName || DEFAULT_AGENT;
     let config = agents.get(name);
     if (!config) {
@@ -1086,7 +1193,7 @@ export async function executeSingle(agents, agentName, task, cwd, signal, onProg
     }
     const usedModel = effectiveConfig.model?.toString();
     onProgress?.(`Running ${name} agent${usedModel ? ` (${usedModel})` : ""}...`);
-    const result = await spawnSubagent(effectiveConfig, task, cwd, signal, onProgress, resolvedProvider, sessionDir, parentSessionFile, onChildEvent, finalThinking);
+    const result = await spawnSubagent(effectiveConfig, task, cwd, signal, onProgress, resolvedProvider, sessionDir, parentSessionFile, onChildEvent, finalThinking, onControlAvailable);
     const finalSelectedModel = result.model ?? (usedModel ? canonicalModelRef(resolvedProvider, usedModel) : undefined);
     result.output = prependModelFallbackSummary(result.output, skippedModels, arbitrationEnabled ? proposalSelectedModel : finalSelectedModel, arbitrationEnabled ? finalSelectedModel : undefined);
     if (warning) {
@@ -1095,7 +1202,7 @@ export async function executeSingle(agents, agentName, task, cwd, signal, onProg
     }
     return result;
 }
-async function executeChain(agents, chain, defaultCwd, signal, onProgress, parentProvider, registry, sessionBaseDir, defaultAgent, defaultModel, defaultThinking, parentModel, getAgentModelsForAgentFn, parentSessionFile, onChildEvent, arbitration) {
+async function executeChain(agents, chain, defaultCwd, signal, onProgress, parentProvider, registry, sessionBaseDir, defaultAgent, defaultModel, defaultThinking, parentModel, getAgentModelsForAgentFn, parentSessionFile, onChildEvent, arbitration, onControlAvailable) {
     const results = [];
     let previousOutput = "";
     for (let i = 0; i < chain.length; i++) {
@@ -1132,7 +1239,7 @@ async function executeChain(agents, chain, defaultCwd, signal, onProgress, paren
         const stepSessionDir = sessionBaseDir ? join(sessionBaseDir, `step-${i + 1}`) : undefined;
         const stepAgentName = step.agent || defaultAgent || DEFAULT_AGENT;
         const stepMach6Models = getAgentModelsForAgentFn?.(stepAgentName);
-        const result = await executeSingle(agents, step.agent || defaultAgent, task, cwdResult.cwd, signal, onProgress, step.model || defaultModel, parentProvider, registry, stepSessionDir, parentModel, stepMach6Models, parentSessionFile, onChildEvent, resolveSubagentThinkingOverride(step.thinking, defaultThinking), arbitration ? { ...arbitration, step: i + 1 } : undefined);
+        const result = await executeSingle(agents, step.agent || defaultAgent, task, cwdResult.cwd, signal, onProgress, step.model || defaultModel, parentProvider, registry, stepSessionDir, parentModel, stepMach6Models, parentSessionFile, onChildEvent, resolveSubagentThinkingOverride(step.thinking, defaultThinking), arbitration ? { ...arbitration, step: i + 1 } : undefined, onControlAvailable);
         results.push(result);
         if (result.exitCode !== 0) {
             break; // stop chain on error
@@ -1149,6 +1256,7 @@ function generateAgentId() {
 }
 const backgroundAgentRegistry = new Map();
 const backgroundAbortControllers = new Map();
+const backgroundControlClients = new Map();
 const REHYDRATED_AGENT_ID_PREFIX = "rehydrated-";
 const HEADER_READ_CHUNK_BYTES = 8192;
 const MAX_HEADER_READ_BYTES = 256 * 1024;
@@ -1440,6 +1548,27 @@ export function getBackgroundAgents() {
 export function getRunningBackgroundAgents() {
     return [...backgroundAgentRegistry.values()].filter((a) => a.status === "running").map(cloneBackgroundAgentInfo);
 }
+function getBackgroundControlClient(agentId) {
+    const info = backgroundAgentRegistry.get(agentId);
+    if (!info)
+        throw new Error(`Unknown background agent "${agentId}".`);
+    if (info.status !== "running")
+        throw new Error(`Background agent "${agentId}" is no longer running.`);
+    const client = backgroundControlClients.get(agentId);
+    if (!client)
+        throw new Error(`Background agent "${agentId}" has not started a controllable child yet.`);
+    return client;
+}
+/** Queue the user's message unchanged in the selected live child session. */
+export async function steerBackgroundAgent(agentId, message) {
+    await getBackgroundControlClient(agentId).steer(message);
+}
+/** Read pending steering messages and the effective delivery mode from the selected live child. */
+export async function getBackgroundAgentPendingSteering(agentId) {
+    const client = getBackgroundControlClient(agentId);
+    const [state, pending] = await Promise.all([client.getState(), client.getPendingMessages()]);
+    return { steeringMode: state.steeringMode, pending };
+}
 /** Abort all running background agents. */
 export function abortBackgroundAgents() {
     for (const [id, controller] of backgroundAbortControllers) {
@@ -1450,6 +1579,7 @@ export function abortBackgroundAgents() {
         }
     }
     backgroundAbortControllers.clear();
+    backgroundControlClients.clear();
 }
 /** Remove completed/failed entries older than the given age (ms). Default: 5 minutes. */
 export function pruneBackgroundAgents(maxAgeMs = 5 * 60 * 1000) {
@@ -1458,6 +1588,7 @@ export function pruneBackgroundAgents(maxAgeMs = 5 * 60 * 1000) {
         if (info.status !== "running" && now - info.startedAt > maxAgeMs) {
             backgroundAgentRegistry.delete(id);
             backgroundAbortControllers.delete(id);
+            backgroundControlClients.delete(id);
         }
     }
 }
@@ -1732,6 +1863,12 @@ export function createSubagentToolDefinition(cwd, options) {
                         onArbitration?.({ type: "subagent_arbitration", agentId, ...record });
                     };
                     const bgSignal = bgAbort.signal;
+                    const onControlAvailable = (client) => {
+                        if (client)
+                            backgroundControlClients.set(agentId, client);
+                        else
+                            backgroundControlClients.delete(agentId);
+                    };
                     const safeNotify = (result) => {
                         try {
                             onBackgroundComplete(agentId, result, bgSignal.aborted);
@@ -1743,7 +1880,7 @@ export function createSubagentToolDefinition(cwd, options) {
                     const run = async () => {
                         await bgAcquire();
                         try {
-                            const result = await runFn(bgSignal, onChildEvent, onArbitrationRecord);
+                            const result = await runFn(bgSignal, onChildEvent, onArbitrationRecord, onControlAvailable);
                             const entry = backgroundAgentRegistry.get(agentId);
                             if (entry && !bgSignal.aborted)
                                 entry.status = result.exitCode === 0 ? "completed" : "failed";
@@ -1767,6 +1904,7 @@ export function createSubagentToolDefinition(cwd, options) {
                             });
                         }
                         finally {
+                            backgroundControlClients.delete(agentId);
                             bgRelease();
                         }
                     };
@@ -1800,14 +1938,14 @@ export function createSubagentToolDefinition(cwd, options) {
                     const sessionId = generateAgentId();
                     const sessionDir = join(subagentSessionsBase, sessionId);
                     const agentModels = getAgentModelsForAgent?.(agentName || DEFAULT_AGENT);
-                    return launchBackgroundLifecycle(agentName, taskLabel, sessionDir, resolvedCwd, (signal, onChildEvent, onArbitrationRecord) => executeSingle(agents, agentName === DEFAULT_AGENT ? undefined : agentName, task, resolvedCwd, signal, undefined, modelOverride, getParentProvider(), modelRegistry, sessionDir, getParentModel(), agentModels, getParentSessionFile(), onChildEvent, thinkingOverride, arbitrate
+                    return launchBackgroundLifecycle(agentName, taskLabel, sessionDir, resolvedCwd, (signal, onChildEvent, onArbitrationRecord, onControlAvailable) => executeSingle(agents, agentName === DEFAULT_AGENT ? undefined : agentName, task, resolvedCwd, signal, undefined, modelOverride, getParentProvider(), modelRegistry, sessionDir, getParentModel(), agentModels, getParentSessionFile(), onChildEvent, thinkingOverride, arbitrate
                         ? {
                             arbitrate,
                             onRecord: onArbitrationRecord,
                             defaultThinkingLevel: getDefaultThinkingLevel?.(),
                             getAgentModelsForAgent,
                         }
-                        : undefined));
+                        : undefined, onControlAvailable));
                 };
                 if (params.task) {
                     // Single background task
@@ -1872,7 +2010,7 @@ export function createSubagentToolDefinition(cwd, options) {
                     const taskSummary = `${params.chain.length}-step chain`;
                     const chainSteps = params.chain;
                     const chainSessionDir = join(subagentSessionsBase, `chain-${generateAgentId()}`);
-                    const agentId = launchBackgroundLifecycle(agentName, taskSummary, chainSessionDir, cwd, async (signal, onChildEvent, onArbitrationRecord) => {
+                    const agentId = launchBackgroundLifecycle(agentName, taskSummary, chainSessionDir, cwd, async (signal, onChildEvent, onArbitrationRecord, onControlAvailable) => {
                         const results = await executeChain(agents, chainSteps, cwd, signal, undefined, getParentProvider(), modelRegistry, chainSessionDir, params.agent, params.model, params.thinking, getParentModel(), getAgentModelsForAgent, getParentSessionFile(), onChildEvent, arbitrate
                             ? {
                                 arbitrate,
@@ -1880,7 +2018,7 @@ export function createSubagentToolDefinition(cwd, options) {
                                 defaultThinkingLevel: getDefaultThinkingLevel?.(),
                                 getAgentModelsForAgent,
                             }
-                            : undefined);
+                            : undefined, onControlAvailable);
                         const resultText = results
                             .map((r, i) => `### Step ${i + 1}\n${formatSingleResult(r)}`)
                             .join("\n\n---\n\n");