@fitchmultz/pi-subagents 0.0.0-stage → 0.44.4

package/dist/runs/shared/session-cwd-preload.js

@@ -0,0 +1,33 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { realpathSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+// Node loads this before Pi selects its session and creates cwd-bound services.
+// Use the SDK beside the actual CLI (bundled or unbundled), never our dev peer.
+const configuration = process.env.PI_SUBAGENT_SESSION_CWD;
+if (configuration) {
+    const { sessionFile, cwd, nodeOptions } = JSON.parse(configuration);
+    const sdkUrl = pathToFileURL(join(dirname(realpathSync(process.argv[1])), "index.js"));
+    const { SessionManager } = await import(__rewriteRelativeImportExtension(sdkUrl.href));
+    const open = SessionManager.open;
+    SessionManager.open = (file, sessionDir, cwdOverride) => {
+        if (resolve(file) !== sessionFile)
+            return open(file, sessionDir, cwdOverride);
+        SessionManager.open = open;
+        // Keep the preload through a native launcher, then clear it before tools or nested children start.
+        delete process.env.PI_SUBAGENT_SESSION_CWD;
+        if (nodeOptions === undefined)
+            delete process.env.NODE_OPTIONS;
+        else
+            process.env.NODE_OPTIONS = nodeOptions;
+        // Public Pi SDK override preserves the file, header, identity and history.
+        return open(file, sessionDir, cwd);
+    };
+}

package/dist/runs/shared/single-output.js

@@ -0,0 +1,222 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+export function normalizeSingleOutputOverride(output, defaultOutput) {
+    if (output === false || output === "false")
+        return false;
+    if (output === true || output === "true")
+        return defaultOutput;
+    if (typeof output === "string" && output.length > 0)
+        return output;
+    return undefined;
+}
+export function resolveSingleOutputPath(output, runtimeCwd, requestedCwd) {
+    if (typeof output !== "string" || !output || output === "false" || output === "true")
+        return undefined;
+    if (path.isAbsolute(output))
+        return output;
+    const baseCwd = requestedCwd
+        ? (path.isAbsolute(requestedCwd) ? requestedCwd : path.resolve(runtimeCwd, requestedCwd))
+        : runtimeCwd;
+    return path.resolve(baseCwd, output);
+}
+function safeOutputSegment(value, fallback) {
+    const sanitized = value.replace(/[^\w.-]/g, "_").replace(/^\.+$/, "");
+    return sanitized || fallback;
+}
+export function materializeAgentDefaultOutputPath(params) {
+    if (typeof params.output !== "string" || !params.output || params.output === "false" || params.output === "true")
+        return params.output;
+    if (path.isAbsolute(params.output))
+        return params.output;
+    const suffix = params.index !== undefined ? `_${safeOutputSegment(String(params.index), "index")}` : "";
+    const safeAgent = safeOutputSegment(params.agent, "agent");
+    const safeBaseName = safeOutputSegment(path.basename(params.output), "output.md");
+    return path.join(params.artifactsDir, "requested-outputs", `${params.runId}_${safeAgent}${suffix}_${safeBaseName}`);
+}
+export function injectSingleOutputInstruction(task, outputPath) {
+    if (!outputPath)
+        return task;
+    return `${task}\n\n---\n**Output:** Write your findings to: ${outputPath}`;
+}
+function countLines(text) {
+    if (!text)
+        return 0;
+    const newlineMatches = text.match(/\r\n|\r|\n/g);
+    return (newlineMatches?.length ?? 0) + (/[\r\n]$/.test(text) ? 0 : 1);
+}
+function formatByteSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    const units = ["KB", "MB", "GB", "TB"];
+    let value = bytes / 1024;
+    let unitIndex = 0;
+    while (value >= 1024 && unitIndex < units.length - 1) {
+        value /= 1024;
+        unitIndex++;
+    }
+    return `${value.toFixed(1)} ${units[unitIndex]}`;
+}
+export function formatSavedOutputReference(savedPath, fullOutput) {
+    const absolutePath = path.resolve(savedPath);
+    const bytes = Buffer.byteLength(fullOutput, "utf-8");
+    const lines = countLines(fullOutput);
+    return {
+        path: absolutePath,
+        bytes,
+        lines,
+        message: `Output saved to: ${absolutePath} (${formatByteSize(bytes)}, ${lines} ${lines === 1 ? "line" : "lines"}). Read this file if needed.`,
+    };
+}
+export function formatConsumedOutputReference(outputPath, fullOutput, cleanup) {
+    const absolutePath = path.resolve(outputPath);
+    const bytes = Buffer.byteLength(fullOutput, "utf-8");
+    const lines = countLines(fullOutput);
+    const status = cleanup.action === "deleted"
+        ? "removed after capture"
+        : cleanup.action === "already-missing"
+            ? "already absent after capture"
+            : `not removed${cleanup.reason ? `: ${cleanup.reason}` : ""}`;
+    return {
+        path: absolutePath,
+        bytes,
+        lines,
+        message: `Output file consumed: ${absolutePath} (${formatByteSize(bytes)}, ${lines} ${lines === 1 ? "line" : "lines"}); ${status}.`,
+    };
+}
+export function findDuplicateOutputPath(items) {
+    const seen = new Map();
+    for (let index = 0; index < items.length; index++) {
+        const outputPath = items[index]?.outputPath;
+        if (!outputPath)
+            continue;
+        const previous = seen.get(outputPath);
+        if (previous) {
+            return `Parallel tasks ${previous.index + 1} (${previous.agent}) and ${index + 1} (${items[index].agent}) resolve output to the same path: ${outputPath}. Use distinct output paths.`;
+        }
+        seen.set(outputPath, { index, agent: items[index].agent });
+    }
+    return undefined;
+}
+export function validateFileOnlyOutputMode(outputMode, outputPath, context) {
+    if (outputMode === "file-only" && !outputPath) {
+        return `${context} sets outputMode: "file-only" but does not configure an output file. Set output to a path or use outputMode: "inline".`;
+    }
+    return undefined;
+}
+export function captureSingleOutputSnapshot(outputPath) {
+    if (!outputPath)
+        return undefined;
+    try {
+        const stat = fs.statSync(outputPath);
+        return { exists: true, mtimeMs: stat.mtimeMs, ctimeMs: stat.ctimeMs, size: stat.size, ino: stat.ino };
+    }
+    catch {
+        // The snapshot is advisory; resolveSingleOutput reports concrete read/write failures.
+        return { exists: false };
+    }
+}
+function matchesSnapshot(stat, snapshot) {
+    return snapshot?.exists === true
+        && stat.mtimeMs === snapshot.mtimeMs
+        && stat.ctimeMs === snapshot.ctimeMs
+        && stat.size === snapshot.size
+        && stat.ino === snapshot.ino;
+}
+function persistSingleOutput(outputPath, fullOutput) {
+    if (!outputPath)
+        return {};
+    try {
+        fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+        fs.writeFileSync(outputPath, fullOutput, "utf-8");
+        return { savedPath: outputPath };
+    }
+    catch (err) {
+        return { error: err instanceof Error ? err.message : String(err) };
+    }
+}
+export function resolveSingleOutput(outputPath, fallbackOutput, beforeRun) {
+    if (!outputPath)
+        return { fullOutput: fallbackOutput };
+    try {
+        const stat = fs.statSync(outputPath);
+        if (!matchesSnapshot(stat, beforeRun)) {
+            // ponytail: acceptance and downstream prompts explicitly request this full
+            // individual output; it must fit their heap. Inspection uses readOutputPage.
+            return { fullOutput: fs.readFileSync(outputPath, "utf-8"), savedPath: outputPath };
+        }
+    }
+    catch (error) {
+        const code = error && typeof error === "object" && "code" in error ? error.code : undefined;
+        if (code !== "ENOENT" && code !== "ENOTDIR") {
+            return {
+                fullOutput: fallbackOutput,
+                saveError: `Failed to read changed output file: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    const save = persistSingleOutput(outputPath, fallbackOutput);
+    if (save.savedPath)
+        return { fullOutput: fallbackOutput, savedPath: save.savedPath, writtenSnapshot: captureSingleOutputSnapshot(save.savedPath) };
+    return { fullOutput: fallbackOutput, saveError: save.error };
+}
+export function cleanupSingleOutputFile(outputPath, fullOutput, beforeRun) {
+    if (!outputPath)
+        return undefined;
+    const absolutePath = path.resolve(outputPath);
+    try {
+        const stat = fs.statSync(outputPath);
+        const fd = fs.openSync(outputPath, "r");
+        let equal = stat.size === Buffer.byteLength(fullOutput);
+        try {
+            let position = 0;
+            for (let start = 0; equal && start < fullOutput.length;) {
+                let end = Math.min(start + 16384, fullOutput.length);
+                if (end < fullOutput.length && /[\uD800-\uDBFF]/.test(fullOutput[end - 1]))
+                    end--;
+                const expected = Buffer.from(fullOutput.slice(start, end));
+                const actual = Buffer.allocUnsafe(expected.length);
+                equal = fs.readSync(fd, actual, 0, actual.length, position) === actual.length && actual.equals(expected);
+                position += expected.length;
+                start = end;
+            }
+            const current = fs.fstatSync(fd), located = fs.statSync(outputPath);
+            equal &&= current.ino === stat.ino && current.size === stat.size && current.ctimeMs === stat.ctimeMs
+                && located.ino === current.ino && located.dev === current.dev && located.ctimeMs === current.ctimeMs;
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        if (!equal) {
+            return { path: absolutePath, action: "skipped", reason: "file changed after capture" };
+        }
+        if (matchesSnapshot(stat, beforeRun)) {
+            return { path: absolutePath, action: "skipped", reason: "file preexisted and was unchanged" };
+        }
+        fs.unlinkSync(outputPath);
+        return { path: absolutePath, action: "deleted" };
+    }
+    catch (error) {
+        const code = error && typeof error === "object" && "code" in error ? error.code : undefined;
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return { path: absolutePath, action: "already-missing" };
+        return { path: absolutePath, action: "skipped", error: error instanceof Error ? error.message : String(error) };
+    }
+}
+export function finalizeSingleOutput(params) {
+    let displayOutput = params.truncatedOutput || params.fullOutput;
+    if (params.exitCode === 0 && params.savedPath) {
+        const outputReference = params.outputReference ?? (params.cleanup && params.outputMode !== "file-only"
+            ? formatConsumedOutputReference(params.savedPath, params.fullOutput, params.cleanup)
+            : formatSavedOutputReference(params.savedPath, params.fullOutput));
+        if (params.outputMode === "file-only") {
+            return { displayOutput: outputReference.message, savedPath: params.savedPath, outputReference };
+        }
+        displayOutput += `\n\n${outputReference.message}`;
+        return { displayOutput, savedPath: params.cleanup ? undefined : params.savedPath, outputReference };
+    }
+    if (params.exitCode === 0 && params.saveError && params.outputPath) {
+        displayOutput += `\n\nOutput file error: ${params.outputPath}\n${params.saveError}`;
+        return { displayOutput, saveError: params.saveError };
+    }
+    return { displayOutput };
+}

package/dist/runs/shared/streaming-text.js

@@ -0,0 +1,15 @@
+/** Native JSON stdout sends text deltas, not cumulative message/partial snapshots. */
+export function updateStreamingText(current, event) {
+    if (event.type === "agent_start" || event.type === "message_end" && event.message?.role === "assistant")
+        return undefined;
+    if (event.type === "message_start" && event.message?.role === "assistant")
+        return "";
+    if (event.type !== "message_update")
+        return current;
+    const update = event.assistantMessageEvent;
+    if (update?.type === "text_start")
+        return current ? `${current}\n\n` : "";
+    if (update?.type === "text_delta")
+        return ((current ?? "") + update.delta).slice(-8192);
+    return current;
+}

package/dist/runs/shared/structured-output.js

@@ -0,0 +1,55 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { Compile } from "../../shared/native-typebox.js";
+export const STRUCTURED_OUTPUT_SCHEMA_ENV = "PI_SUBAGENT_STRUCTURED_OUTPUT_SCHEMA";
+export const STRUCTURED_OUTPUT_CAPTURE_ENV = "PI_SUBAGENT_STRUCTURED_OUTPUT_CAPTURE";
+export function assertJsonSchemaObject(schema, label = "outputSchema") {
+    if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+        throw new Error(`${label} must be a JSON Schema object.`);
+    }
+}
+export function createStructuredOutputRuntime(schema, baseDir) {
+    assertJsonSchemaObject(schema);
+    const rootDir = baseDir ?? os.tmpdir();
+    fs.mkdirSync(rootDir, { recursive: true });
+    const dir = fs.mkdtempSync(path.join(rootDir, "pi-subagent-structured-"));
+    const schemaPath = path.join(dir, "schema.json");
+    const outputPath = path.join(dir, "output.json");
+    fs.writeFileSync(schemaPath, JSON.stringify(schema), { mode: 0o600 });
+    return { schema, schemaPath, outputPath };
+}
+export function validateStructuredOutputValue(schema, value) {
+    let validator;
+    try {
+        validator = Compile(schema);
+    }
+    catch (error) {
+        return { status: "invalid", message: `invalid outputSchema: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    if (validator.Check(value))
+        return { status: "valid" };
+    const errors = [...validator.Errors(value)]
+        .slice(0, 8)
+        .map((error) => {
+        const pathText = error.instancePath ? error.instancePath.replace(/^\//, "").replace(/\//g, ".") : "root";
+        return `${pathText}: ${error.message}`;
+    });
+    return { status: "invalid", message: errors.join("; ") || "schema validation failed" };
+}
+export function readStructuredOutput(runtime) {
+    if (!fs.existsSync(runtime.outputPath)) {
+        return { error: "Missing structured_output call; this step has outputSchema and must finish by calling structured_output." };
+    }
+    let value;
+    try {
+        value = JSON.parse(fs.readFileSync(runtime.outputPath, "utf-8"));
+    }
+    catch (error) {
+        return { error: `Failed to read structured output: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    const validation = validateStructuredOutputValue(runtime.schema, value);
+    if (validation.status === "invalid")
+        return { error: `Structured output validation failed: ${validation.message}` };
+    return { value };
+}

package/dist/runs/shared/subagent-control.js

@@ -0,0 +1,179 @@
+import {} from "../../shared/types.js";
+import { formatRunAction } from "../../shared/status-format.js";
+import { readStatus } from "../../shared/utils.js";
+import { getRunMetadataDir } from "./supervisor-questions.js";
+export function isObsoleteIdleNotice(details) {
+    const event = details?.event;
+    if (!event || event.reason !== "idle" || event.supervisorQuestion)
+        return false;
+    let status;
+    try {
+        status = readStatus(details.asyncDir ?? getRunMetadataDir(event.runId));
+    }
+    catch {
+        // Without readable terminal evidence, retain the actionable notice.
+        return false;
+    }
+    if (!status || status.runId !== event.runId)
+        return false;
+    const child = event.index === undefined ? undefined : status.steps?.[event.index];
+    return ["complete", "failed", "blocked", "paused"].includes(status.state)
+        || Boolean(child && ["complete", "completed", "failed", "blocked", "paused", "timed-out"].includes(child.status));
+}
+const CONTROL_EVENT_TYPES = ["needs_attention"];
+const CONTROL_NOTIFICATION_CHANNELS = ["event", "async", "intercom"];
+const DEFAULT_NOTIFY_ON = ["needs_attention"];
+export const DEFAULT_CONTROL_CONFIG = {
+    enabled: true,
+    needsAttentionAfterMs: 10 * 60_000,
+    failedToolAttemptsBeforeAttention: 3,
+    notifyOn: DEFAULT_NOTIFY_ON,
+    notifyChannels: CONTROL_NOTIFICATION_CHANNELS,
+};
+function parsePositiveInt(value) {
+    if (typeof value !== "number")
+        return undefined;
+    if (!Number.isFinite(value) || !Number.isInteger(value) || value < 1)
+        return undefined;
+    return value;
+}
+function parseControlList(value, allowed) {
+    if (!Array.isArray(value))
+        return undefined;
+    if (value.length === 0)
+        return [];
+    const allowedSet = new Set(allowed);
+    const parsed = value.filter((entry) => typeof entry === "string" && allowedSet.has(entry));
+    return parsed.length > 0 ? Array.from(new Set(parsed)) : undefined;
+}
+export function resolveControlConfig(globalConfig, override) {
+    const enabled = override?.enabled ?? globalConfig?.enabled ?? DEFAULT_CONTROL_CONFIG.enabled;
+    const needsAttentionAfterMs = parsePositiveInt(override?.needsAttentionAfterMs)
+        ?? parsePositiveInt(globalConfig?.needsAttentionAfterMs)
+        ?? DEFAULT_CONTROL_CONFIG.needsAttentionAfterMs;
+    const failedToolAttemptsBeforeAttention = parsePositiveInt(override?.failedToolAttemptsBeforeAttention)
+        ?? parsePositiveInt(globalConfig?.failedToolAttemptsBeforeAttention)
+        ?? DEFAULT_CONTROL_CONFIG.failedToolAttemptsBeforeAttention;
+    const notifyOn = parseControlList(override?.notifyOn, CONTROL_EVENT_TYPES)
+        ?? parseControlList(globalConfig?.notifyOn, CONTROL_EVENT_TYPES)
+        ?? DEFAULT_CONTROL_CONFIG.notifyOn;
+    const notifyChannels = parseControlList(override?.notifyChannels, CONTROL_NOTIFICATION_CHANNELS)
+        ?? parseControlList(globalConfig?.notifyChannels, CONTROL_NOTIFICATION_CHANNELS)
+        ?? DEFAULT_CONTROL_CONFIG.notifyChannels;
+    return {
+        enabled,
+        needsAttentionAfterMs,
+        failedToolAttemptsBeforeAttention,
+        notifyOn: [...notifyOn],
+        notifyChannels: [...notifyChannels],
+    };
+}
+export function deriveActivityState(input) {
+    if (!input.config.enabled)
+        return undefined;
+    const now = input.now ?? Date.now();
+    const lastActivity = input.lastActivityAt ?? input.startedAt;
+    const ageMs = Math.max(0, now - lastActivity);
+    return ageMs > input.config.needsAttentionAfterMs ? "needs_attention" : undefined;
+}
+export function buildControlEvent(input) {
+    const ts = input.ts ?? Date.now();
+    const type = input.type ?? "needs_attention";
+    const elapsedMs = input.elapsedMs ?? (input.lastActivityAt !== undefined ? Math.max(0, ts - input.lastActivityAt) : undefined);
+    const elapsedSeconds = elapsedMs !== undefined ? Math.floor(elapsedMs / 1000) : undefined;
+    const question = input.supervisorQuestion;
+    const observation = input.currentTool
+        ? `${input.currentTool} still active${input.currentToolDurationMs !== undefined ? ` for ${Math.floor(input.currentToolDurationMs / 1000)}s` : ""}${elapsedSeconds !== undefined ? `; no observed output/events for ${elapsedSeconds}s` : ""}`
+        : elapsedSeconds !== undefined ? `no observed activity for ${elapsedSeconds}s` : undefined;
+    const signal = question
+        ? question.state === "awaiting_input" ? `Waiting for supervisor input (question ${question.questionId})` : `Supervisor answer saved for question ${question.questionId}; delivery unconfirmed`
+        : `${input.agent} needs attention`;
+    const message = input.message ?? `${signal}${observation ? ` (${observation})` : ""}`;
+    return {
+        type,
+        ...(input.from ? { from: input.from } : {}),
+        to: input.to,
+        ts,
+        runId: input.runId,
+        agent: input.agent,
+        ...(input.index !== undefined ? { index: input.index } : {}),
+        message,
+        reason: input.reason ?? "idle",
+        ...(input.turns !== undefined ? { turns: input.turns } : {}),
+        ...(input.tokens !== undefined ? { tokens: input.tokens } : {}),
+        ...(input.toolCount !== undefined ? { toolCount: input.toolCount } : {}),
+        ...(input.currentTool ? { currentTool: input.currentTool } : {}),
+        ...(input.currentToolDurationMs !== undefined ? { currentToolDurationMs: input.currentToolDurationMs } : {}),
+        ...(input.currentPath ? { currentPath: input.currentPath } : {}),
+        ...(elapsedMs !== undefined ? { elapsedMs } : {}),
+        ...(input.recentFailureSummary ? { recentFailureSummary: input.recentFailureSummary } : {}),
+        ...(question ? { supervisorQuestion: question } : {}),
+    };
+}
+export function shouldNotifyControlEvent(config, event) {
+    return config.enabled && config.notifyOn.includes(event.type);
+}
+export function controlNotificationKey(event, childIntercomTarget) {
+    const childKey = childIntercomTarget ?? (event.index !== undefined ? `${event.runId}:${event.index}` : event.runId);
+    return `${childKey}:${event.type}:${event.reason ?? "idle"}`;
+}
+export function claimControlNotification(config, event, seenKeys, childIntercomTarget) {
+    if (!shouldNotifyControlEvent(config, event))
+        return false;
+    const key = controlNotificationKey(event, childIntercomTarget);
+    if (seenKeys.has(key))
+        return false;
+    seenKeys.add(key);
+    return true;
+}
+export function formatControlNoticeMessage(event, childIntercomTarget, childSafe = false) {
+    const runTarget = event.runId;
+    if (event.reason === "completion_guard") {
+        return [
+            `Subagent failed: ${event.agent}`,
+            `Run: ${runTarget}${event.index !== undefined ? ` step ${event.index + 1}` : ""}`,
+            `Signal: ${event.message}`,
+            "Next: read the output artifact or session from the subagent result, then retry with a more explicit implementation prompt or handle the fix directly.",
+            childIntercomTarget ? `Run intercom target (may be inactive): ${childIntercomTarget}` : undefined,
+        ].filter((line) => Boolean(line)).join("\n");
+    }
+    const nudgeCommand = formatRunAction("nudge", runTarget, { ...(event.index !== undefined ? { index: event.index } : {}), message: "What are you blocked on? Reply with the smallest next step, or state the exact decision you need." }, childSafe);
+    const question = event.supervisorQuestion;
+    const askCommand = childIntercomTarget
+        ? `intercom({ action: "ask", to: "${childIntercomTarget}", delivery: "steer", message: "What are you blocked on? Reply with the smallest next step, or state the exact decision you need." })`
+        : undefined;
+    return [
+        `Subagent needs attention: ${event.agent}`,
+        `Run: ${runTarget}${event.index !== undefined ? ` step ${event.index + 1}` : ""}`,
+        `Signal: ${event.message}`,
+        event.recentFailureSummary ? `Recent failures: ${event.recentFailureSummary}` : undefined,
+        ...(question ? [
+            `Question ID: ${question.questionId}`,
+            question.state === "answer_pending" ? "The saved answer has not been confirmed delivered. Inspect the child and retry the same answer; do not assume it resumed." : "Answer the saved question so the child can continue.",
+            `Questions: ${formatRunAction("questions", runTarget, {}, childSafe)}`,
+            `Answer: ${formatRunAction("answer", runTarget, { questionId: question.questionId, message: question.answer ?? "..." }, childSafe)}`,
+        ] : [
+            event.reason === "idle" && event.currentTool ? "Hint: Inspect command progress. A long-running tool may still be running or hung; elapsed time alone does not prove either." : "Hint: Inspect status first unless the run is clearly blocked.",
+            `Nudge (preferred live coordination): ${nudgeCommand}`,
+            childIntercomTarget
+                ? `Ask (blocking wait only; parent must remain alive): ${askCommand}`
+                : "Ask (blocking wait only): no child message route registered",
+        ]),
+        `Status: ${formatRunAction("status", runTarget, {}, childSafe)}`,
+        `${childSafe ? "Interrupt" : "Stop"}: ${formatRunAction("interrupt", runTarget, {}, childSafe)}`,
+    ].filter((line) => Boolean(line)).join("\n");
+}
+export function formatControlIntercomMessage(event, childIntercomTarget, childSafe = false) {
+    const statusLabel = event.reason === "completion_guard"
+        ? "subagent failed"
+        : "subagent needs attention";
+    return [
+        statusLabel,
+        "",
+        event.reason === "completion_guard"
+            ? `${event.agent} failed in run ${event.runId}.`
+            : `${event.agent} needs attention in run ${event.runId}.`,
+        "",
+        formatControlNoticeMessage(event, childIntercomTarget, childSafe),
+    ].join("\n");
+}