pilotswarm-sdk 0.5.76 → 0.5.78

package/dist/orchestration_1_0_78/agents.js

@@ -0,0 +1,894 @@
+import { clearPendingChildDigest, publishStatus, queueFollowup, writeCommandResponse, } from "./lifecycle.js";
+import { MAX_NESTING_LEVEL, MAX_SUB_AGENTS, SHUTDOWN_POLL_INTERVAL_MS, SHUTDOWN_TIMEOUT_MS, } from "./state.js";
+// ─── Pure helpers ───────────────────────────────────────────
+export function isSubAgentTerminalStatus(status) {
+    return status === "completed" || status === "failed" || status === "cancelled";
+}
+/** Preserve child answers when a status probe only has orchestration exit output. */
+export function getChildResultFromStatus(child, previous) {
+    if (typeof child.result !== "string" || !child.result)
+        return previous;
+    if (child.resultSource === "orchestration")
+        return previous;
+    return child.result;
+}
+/**
+ * A status that satisfies a parent's wait: the child either finished
+ * (terminal) or will never speak again on its own — idle after answering, or
+ * blocked asking for input. "running" and "waiting" (child on a timer) stay
+ * pending: those children will still act without help. Without the idle
+ * mapping a wait_for_agents parent polls an idle child forever (observed
+ * live: 70+ minutes of 30s polls until a human poked).
+ */
+export function isAgentWaitSettledStatus(status) {
+    return isSubAgentTerminalStatus(status) || status === "idle" || status === "input_required";
+}
+export function parseChildUpdate(promptText) {
+    if (typeof promptText !== "string")
+        return null;
+    const match = promptText.match(/^\[CHILD_UPDATE\s+([^\]]+)\]/);
+    if (!match)
+        return null;
+    const fields = new Map();
+    for (const token of match[1].split(/\s+/)) {
+        const [key, ...rest] = token.split("=");
+        if (!key || rest.length === 0)
+            continue;
+        fields.set(key, rest.join("="));
+    }
+    const cycle = fields.get("cycle");
+    const status = fields.get("status");
+    const verdictField = fields.get("verdict");
+    const sessionId = fields.get("from") ?? "";
+    const updateType = fields.get("type") ?? "";
+    if (!sessionId || !updateType)
+        return null;
+    const cycleOrigin = cycle === "cron" || cycle === "cron_at" ? cycle : undefined;
+    const cycleStatus = status === "quiet" || status === "material" || status === "blocked" ? status : undefined;
+    const verdict = verdictField === "success" || verdictField === "partial" || verdictField === "blocked" || verdictField === "failed" || verdictField === "cancelled" || verdictField === "timed_out"
+        ? verdictField
+        : undefined;
+    return {
+        sessionId,
+        updateType,
+        content: promptText.split("\n").slice(1).join("\n").trim(),
+        ...(cycleOrigin ? { cycleOrigin } : {}),
+        ...(cycleStatus ? { cycleStatus } : {}),
+        ...(verdict ? { verdict } : {}),
+    };
+}
+export function defaultShutdownReason(mode) {
+    switch (mode) {
+        case "done":
+            return "Completed by user";
+        case "cancel":
+            return "Cancelled by user";
+        case "delete":
+            return "Deleted by user";
+    }
+}
+export function buildShutdownWaitReason(shutdown) {
+    switch (shutdown.mode) {
+        case "done":
+            return `Waiting for ${shutdown.targetAgentIds.length} child session(s) to complete before closing.`;
+        case "cancel":
+            return `Waiting for ${shutdown.targetAgentIds.length} child session(s) to cancel before closing.`;
+        case "delete":
+            return `Waiting for ${shutdown.targetAgentIds.length} child session(s) to cancel before deletion.`;
+    }
+}
+export function findTrackedAgentByOrchId(subAgents, orchId) {
+    return subAgents.find((agent) => agent.orchId === orchId);
+}
+export function areTrackedAgentsTerminal(subAgents, agentIds) {
+    return agentIds.every((agentId) => {
+        const agent = findTrackedAgentByOrchId(subAgents, agentId);
+        return Boolean(agent && isSubAgentTerminalStatus(agent.status));
+    });
+}
+export function getStillRunningAgentIds(subAgents, agentIds) {
+    return agentIds.filter((agentId) => {
+        const agent = findTrackedAgentByOrchId(subAgents, agentId);
+        return agent && !isSubAgentTerminalStatus(agent.status);
+    });
+}
+export function buildWaitForAgentsFollowup(subAgents, targetIds) {
+    const describeStatus = (agent) => {
+        if (agent.status === "idle") {
+            return "idle — went quiet after answering; treat its last message as its result (message_agent to re-task it, complete_agent to finish it)";
+        }
+        if (agent.status === "input_required") {
+            return "input_required — blocked waiting for an answer; relay the question to the user or answer it via message_agent";
+        }
+        return agent.status;
+    };
+    const summaries = targetIds
+        .map((targetId) => subAgents.find((agent) => agent.orchId === targetId))
+        .filter((agent) => Boolean(agent))
+        .map((agent) => `  - Agent ${agent.orchId}\n` +
+        `    Task: "${agent.task.slice(0, 120)}"\n` +
+        `    Status: ${describeStatus(agent)}\n` +
+        `    Result: ${agent.result ?? "(no result)"}`);
+    if (summaries.length === 0) {
+        return `[SYSTEM: No tracked sub-agents produced a completion summary.]`;
+    }
+    if (summaries.length === 1) {
+        return `[SYSTEM: Sub-agent completed. If the user asked you to relay the child's final output, return the single sub-agent Result text verbatim.\n${summaries[0]}]`;
+    }
+    return `[SYSTEM: Sub-agents completed:\n${summaries.join("\n")}]`;
+}
+export function buildSubAgentSystemMessage(options) {
+    const { parentSessionId, childNestingLevel, maxNestingLevel, agentTask, agentIsSystem, parentSystemMessage, } = options;
+    const canSpawnMore = childNestingLevel < maxNestingLevel;
+    const timingInstruction = agentIsSystem
+        ? `- For recurring or periodic work, use the \`cron\` or \`cron_at\` tool instead of ending every cycle with \`wait\`. ` +
+            `Call \`cron(seconds=<N>, reason="...")\` to start or update the durable recurring schedule, ` +
+            `or \`cron_at(minute=<M>, hour=<H>, tz="...", reason="...")\` for wall-clock schedules. ` +
+            `then finish turns normally so the orchestration wakes you automatically on each cron cycle. ` +
+            `Use \`wait\` only for one-shot delays inside a turn. ` +
+            `Call \`cron(action="cancel")\` or \`cron_at(action="cancel")\` only when you intentionally want to stop the recurring loop.\n`
+        : `- For ANY waiting, sleeping, delaying, or scheduling, you MUST use the \`wait\`, \`wait_on_worker\`, \`cron\`, or \`cron_at\` tools. ` +
+            `Use \`wait\` or \`wait_on_worker\` for one-shot delays. Use \`cron\` for fixed intervals and \`cron_at\` for wall-clock schedules. ` +
+            `Do NOT burn tokens polling inside one LLM turn; after a brief immediate re-check at most, yield with a durable timer. ` +
+            `NEVER use setTimeout, sleep, setInterval, or any other timing mechanism. ` +
+            `Durable waits survive process restarts.\n`;
+    const subAgentPreamble = `[SUB-AGENT CONTEXT]\n` +
+        `You are a sub-agent spawned by a parent session (ID: session-${parentSessionId}).\n` +
+        `Your nesting level: ${childNestingLevel} (max: ${maxNestingLevel}).\n` +
+        `Your task: "${agentTask.slice(0, 500)}"\n\n` +
+        `Instructions:\n` +
+        `- Focus exclusively on your assigned task.\n` +
+        `- Your final response will be automatically forwarded to the parent agent.\n` +
+        `- Be thorough but concise — the parent will synthesize results from multiple agents.\n` +
+        `- Do NOT ask the user for input — you are autonomous.\n` +
+        `- You are autonomous and goal-driven. If the task implies ongoing monitoring or follow-through until done, keep yourself alive with durable timers until the goal is complete or you can no longer make progress.\n` +
+        `- If it is ambiguous whether the task should become a long-running recurring workflow, report that ambiguity back to the parent instead of guessing or asking the user directly.\n` +
+        `- When your task is complete, provide a clear summary of your findings/results. Your final assistant message is automatically forwarded to the parent.\n` +
+        `- After you finish a task you stay ALIVE and idle, ready for the parent to send you a follow-up via \`message_agent\`. You are NOT auto-terminated when you produce a final answer.\n` +
+        `- Only the parent decides when you are no longer needed. The parent will close you with \`complete_agent\`, \`cancel_agent\`, or \`delete_agent\`. Do not assume you have been shut down just because you produced a final reply.\n` +
+        `- Prefer using \`store_fact\` for larger structured context handoffs across your spawn tree. Put the durable details in facts, then pass fact keys or \`read_facts\` pointers in messages/prompts instead of pasting large context blobs. Sibling and cousin agents under the same root can read your session-scoped facts directly via \`read_facts\` — you do NOT need to mark them \`shared=true\` just to share with peers.\n` +
+        `- FILESYSTEM ISOLATION: your parent, siblings, and sub-agents each run on their own worker pod — they can NEVER see your local files, and yours may vanish on the next turn, after a durable wait, or on worker restart. The artifact store is the ONLY shared byte channel. To hand off any file (especially binaries/archives): \`write_artifact({fromFile: "<path>"})\` on the producing side, \`read_artifact({toFile: "<path>"})\` on the consuming side. Bytes move server-side with a SHA-256 in every result — never read a file just to re-type its bytes as inline content, and never base64 payloads through messages.\n` +
+        `- \`write_artifact\` returns the artifact:// link — include it in your response whenever the user or your parent should see the file. Use \`store_fact\` for structured state, artifacts for files.\n` +
+        `- If you override a sub-agent model, you MUST first call list_available_models in this session and use only an exact provider:model value returned there. ` +
+        `NEVER invent, guess, shorten, or reuse a stale model name.\n` +
+        `- Worker-managed system agents are not valid spawn targets. If you expect one and it is missing, report that the workers likely need to be restarted.\n` +
+        timingInstruction +
+        (canSpawnMore
+            ? `- If your parent task explicitly asks you to spawn sub-agents, delegate, fan out, or parallelize work, you SHOULD do so within runtime limits instead of collapsing the task into a direct answer. ` +
+                `If delegation was not explicitly requested, use your judgment and avoid unnecessary fan-out. ` +
+                `You have ${maxNestingLevel - childNestingLevel} level(s) of nesting remaining. ` +
+                `After spawning, finish the turn normally and let qualifying child updates wake you according to contract.wakeOn. ` +
+                `Do not schedule wait or cron solely to poll check_agents; use wait_for_agents only when you need an explicit synchronization barrier.\n`
+            : `- You CANNOT spawn sub-agents — you are at the maximum nesting depth. Handle everything directly.\n`);
+    return subAgentPreamble + (parentSystemMessage ? "\n\n" + parentSystemMessage : "");
+}
+// ─── Child agent tracking ───────────────────────────────────
+export function* applyChildUpdate(runtime, update) {
+    runtime.ctx.traceInfo(`[orch] child update from=${update.sessionId} type=${update.updateType}`);
+    const agent = runtime.state.subAgents.find(a => a.sessionId === update.sessionId);
+    if (!agent) {
+        runtime.ctx.traceInfo(`[orch] ignoring child update from untracked session ${update.sessionId}`);
+        return false;
+    }
+    if (update.content) {
+        agent.result = update.content.slice(0, 2000);
+    }
+    // Any substantive update from the child satisfies the spawn-time
+    // report expectation.
+    agent.expectsReport = false;
+    if (update.updateType === "completed") {
+        agent.status = "completed";
+    }
+    else if (update.updateType === "cancelled" || update.updateType === "deleted") {
+        agent.status = "cancelled";
+    }
+    else if (update.updateType === "failed") {
+        agent.status = "failed";
+    }
+    try {
+        const rawStatus = yield runtime.manager.getSessionStatus(agent.sessionId);
+        const parsed = JSON.parse(rawStatus);
+        if (parsed.status === "failed") {
+            agent.status = "failed";
+        }
+        else if (parsed.status === "completed") {
+            agent.status = "completed";
+        }
+        else if (parsed.status === "cancelled") {
+            agent.status = "cancelled";
+        }
+        else if (parsed.status === "waiting" && update.updateType !== "completed") {
+            // A "completed" update means the child turn ended with a final
+            // answer; a concurrent "waiting" probe at that moment is almost
+            // always the auto-resumed remainder of a wait timer the parent's
+            // own message interrupted. Downgrading on it deadlocks
+            // wait_for_agents: the idle child may never speak again, and the
+            // fallback poll cannot re-derive "completed" from an idle probe.
+            // Deliberate continuation waits arrive as updateType "wait" and
+            // still downgrade here.
+            agent.status = "waiting";
+        }
+        else if (parsed.status === "idle" && !isSubAgentTerminalStatus(agent.status) && update.updateType !== "completed") {
+            // Quiescent child: answered and parked. Not terminal (it can be
+            // re-tasked), but it satisfies a parent wait.
+            agent.status = "idle";
+        }
+        else if (parsed.status === "input_required" && !isSubAgentTerminalStatus(agent.status)) {
+            // Blocked asking for input — it will never act unprompted; the
+            // parent must be told so it can answer or re-task.
+            agent.status = "input_required";
+        }
+        agent.result = getChildResultFromStatus(parsed, agent.result)?.slice(0, 2000);
+    }
+    catch { }
+    return true;
+}
+export function* refreshTrackedSubAgents(runtime, options = {}) {
+    const preserveTerminalTaskStatus = options.preserveTerminalTaskStatus !== false;
+    try {
+        const rawChildren = yield runtime.manager.listChildSessions(runtime.input.sessionId);
+        const directChildren = JSON.parse(rawChildren);
+        runtime.state.subAgents = directChildren
+            .filter(child => !child.isSystem)
+            .map((child) => {
+            const existing = runtime.state.subAgents.find(agent => agent.sessionId === child.sessionId || agent.orchId === child.orchId);
+            const contract = child.contract ?? existing?.contract;
+            const localStatus = existing?.status;
+            if (preserveTerminalTaskStatus && localStatus && isSubAgentTerminalStatus(localStatus)) {
+                return {
+                    orchId: child.orchId,
+                    sessionId: child.sessionId,
+                    task: existing?.task ?? child.title ?? "(spawned sub-agent)",
+                    status: localStatus,
+                    result: getChildResultFromStatus(child, existing?.result),
+                    agentId: child.agentId ?? existing?.agentId,
+                    contract,
+                };
+            }
+            const rawStatus = child.status ?? localStatus ?? "running";
+            const normalizedStatus = rawStatus === "failed" ? "failed"
+                : rawStatus === "cancelled" ? "cancelled"
+                    : rawStatus === "waiting" ? "waiting"
+                        : rawStatus === "completed" ? "completed"
+                            : "running";
+            return {
+                orchId: child.orchId,
+                sessionId: child.sessionId,
+                task: existing?.task ?? child.title ?? "(spawned sub-agent)",
+                status: normalizedStatus,
+                result: getChildResultFromStatus(child, existing?.result),
+                agentId: child.agentId ?? existing?.agentId,
+                contract,
+            };
+        });
+    }
+    catch (err) {
+        runtime.ctx.traceInfo(`[orch] refreshTrackedSubAgents failed (non-fatal): ${err.message ?? err}`);
+    }
+}
+// ─── Graceful shutdown cascade ──────────────────────────────
+export function* notifyParentOfTerminalState(runtime, updateType, reason, commandId, requestedBy) {
+    if (!runtime.options.parentSessionId)
+        return;
+    try {
+        // Acknowledge the parent's own cleanup without delivering another
+        // CHILD_UPDATE prompt. That prompt replaced real child results in a
+        // digest and woke an already-finished parent for no new work. Keep the
+        // lifecycle in CMS and an audit event; check_agents/wait_for_agents and
+        // graceful-shutdown polling still observe the actual terminal state.
+        // Only runtime-stamped provenance matching the direct parent qualifies.
+        // A user-supplied reason such as "Completed by parent" is not evidence.
+        if (commandId && requestedBy === runtime.options.parentSessionId) {
+            yield runtime.manager.recordSessionEvent(runtime.options.parentSessionId, [{
+                    eventType: "session.child_cleanup_completed",
+                    data: {
+                        childSessionId: runtime.input.sessionId,
+                        commandId,
+                        requestedBy,
+                        status: updateType,
+                    },
+                }]);
+            return;
+        }
+        const verdict = updateType === "completed" ? "success" : "cancelled";
+        yield runtime.manager.sendToSession(runtime.options.parentSessionId, `[CHILD_UPDATE from=${runtime.input.sessionId} type=${updateType} iter=${runtime.state.iteration} verdict=${verdict}]\n${reason}`);
+    }
+    catch (err) {
+        runtime.ctx.traceInfo(`[orch] parent notification on ${updateType} failed: ${err.message} (non-fatal)`);
+    }
+}
+export function* completeSession(runtime, reason, commandId, requestedBy) {
+    runtime.state.pendingShutdown = null;
+    runtime.state.waitingForAgentIds = null;
+    clearPendingChildDigest(runtime);
+    runtime.state.activeTimer = null;
+    yield runtime.manager.updateCmsState(runtime.input.sessionId, "completed", null, null);
+    publishStatus(runtime, "completed");
+    yield* notifyParentOfTerminalState(runtime, "completed", reason, commandId, requestedBy);
+    try {
+        yield runtime.session.destroy();
+    }
+    catch { }
+    if (commandId) {
+        const resp = {
+            id: commandId,
+            cmd: "done",
+            result: { ok: true, message: "Session completed" },
+        };
+        yield* writeCommandResponse(runtime, resp);
+    }
+    runtime.state.orchestrationResult = "done";
+}
+export function* cancelSession(runtime, reason, commandId, deleteAfterCancel = false, requestedBy) {
+    runtime.state.pendingShutdown = null;
+    runtime.state.waitingForAgentIds = null;
+    clearPendingChildDigest(runtime);
+    runtime.state.activeTimer = null;
+    const commandName = deleteAfterCancel ? "delete" : "cancel";
+    if (!deleteAfterCancel) {
+        yield runtime.manager.updateCmsState(runtime.input.sessionId, "cancelled", null, null);
+        publishStatus(runtime, "cancelled");
+    }
+    yield* notifyParentOfTerminalState(runtime, "cancelled", reason, commandId, requestedBy);
+    try {
+        yield runtime.session.destroy();
+    }
+    catch { }
+    if (commandId) {
+        const resp = {
+            id: commandId,
+            cmd: commandName,
+            result: {
+                ok: true,
+                message: deleteAfterCancel ? "Session deleted" : "Session cancelled",
+            },
+        };
+        yield* writeCommandResponse(runtime, resp);
+    }
+    if (deleteAfterCancel) {
+        const deleteReason = reason || "Deleted by user";
+        let descendants = [];
+        try {
+            descendants = yield runtime.manager.getDescendantSessionIds(runtime.input.sessionId);
+        }
+        catch (err) {
+            runtime.ctx.traceInfo(`[orch] delete: failed to enumerate descendants: ${err.message}`);
+        }
+        for (const descendantId of descendants) {
+            try {
+                yield runtime.manager.deleteSession(descendantId, `Ancestor ${runtime.input.sessionId} deleted: ${deleteReason}`);
+            }
+            catch (err) {
+                runtime.ctx.traceInfo(`[orch] delete: failed to delete descendant ${descendantId}: ${err.message} (non-fatal)`);
+            }
+        }
+        try {
+            yield runtime.manager.deleteSession(runtime.input.sessionId, deleteReason);
+        }
+        catch (err) {
+            runtime.ctx.traceInfo(`[orch] delete: failed to delete ${runtime.input.sessionId}: ${err.message}`);
+        }
+        runtime.state.orchestrationResult = "deleted";
+        return;
+    }
+    runtime.state.orchestrationResult = "cancelled";
+}
+export function* failPendingShutdown(runtime, errorMessage) {
+    const shutdown = runtime.state.pendingShutdown;
+    runtime.state.pendingShutdown = null;
+    runtime.state.waitingForAgentIds = null;
+    clearPendingChildDigest(runtime);
+    runtime.state.activeTimer = null;
+    try {
+        yield runtime.session.destroy();
+    }
+    catch { }
+    if (shutdown?.commandId) {
+        const resp = {
+            id: shutdown.commandId,
+            cmd: shutdown.mode,
+            error: errorMessage,
+        };
+        yield* writeCommandResponse(runtime, resp);
+    }
+    publishStatus(runtime, "failed", { error: errorMessage });
+    yield runtime.manager.updateCmsState(runtime.input.sessionId, "failed", errorMessage, null);
+    runtime.state.orchestrationResult = "failed";
+}
+/**
+ * Best-effort cancel of a distiller SERVICE SESSION still running when its
+ * regen is torn down (cancel_regen, a pre-flip failure, or the served session
+ * shutting down). Without this the distiller finishes its LLM turn then parks
+ * idle forever — the sweeper never reclaims a LIVE session, so each abort leaks
+ * one (adversarial-review finding). The cancel is a queued cmd (the activity
+ * swallows its own errors), so it is safe to yield from any teardown path.
+ */
+export function* cancelInFlightDistiller(runtime) {
+    const regen = runtime.state.regen;
+    if (regen?.stage === "distilling" && regen.distillerSessionId) {
+        yield runtime.manager.runRegenCancelDistiller(regen.distillerSessionId);
+    }
+}
+export function* finalizePendingShutdown(runtime) {
+    if (!runtime.state.pendingShutdown)
+        return;
+    yield* cancelInFlightDistiller(runtime);
+    const shutdown = runtime.state.pendingShutdown;
+    if (shutdown.mode === "done") {
+        yield* completeSession(runtime, shutdown.reason, shutdown.commandId, shutdown.requestedBy);
+        return;
+    }
+    yield* cancelSession(runtime, shutdown.reason, shutdown.commandId, shutdown.mode === "delete", shutdown.requestedBy);
+}
+export function* maybeResolveAgentWaitCompletion(runtime) {
+    const { state } = runtime;
+    const allSettled = state.waitingForAgentIds?.every((targetId) => {
+        const agent = state.subAgents.find((entry) => entry.orchId === targetId);
+        return agent ? isAgentWaitSettledStatus(agent.status) : true;
+    });
+    if (!state.waitingForAgentIds || !allSettled) {
+        return false;
+    }
+    if (state.pendingShutdown) {
+        yield* finalizePendingShutdown(runtime);
+        return true;
+    }
+    queueFollowup(runtime, buildWaitForAgentsFollowup(state.subAgents, state.waitingForAgentIds));
+    state.waitingForAgentIds = null;
+    clearPendingChildDigest(runtime);
+    state.activeTimer = null;
+    return true;
+}
+export function* beginGracefulShutdown(runtime, mode, cmdMsg) {
+    const { state } = runtime;
+    if (state.pendingShutdown) {
+        const now = yield runtime.ctx.utcNow();
+        const resp = {
+            id: cmdMsg.id,
+            cmd: cmdMsg.cmd,
+            result: {
+                ok: true,
+                message: `Shutdown already in progress (${state.pendingShutdown.mode}).`,
+            },
+        };
+        yield* writeCommandResponse(runtime, resp);
+        publishStatus(runtime, "waiting", {
+            waitReason: buildShutdownWaitReason(state.pendingShutdown),
+            waitStartedAt: state.pendingShutdown.startedAtMs,
+            waitSeconds: Math.max(0, Math.ceil((state.pendingShutdown.deadlineAtMs - now) / 1000)),
+        });
+        return;
+    }
+    // Task completion does not make a child session terminal: non-system
+    // children stay alive for follow-up messages. During parent shutdown the
+    // CMS session lifecycle is authoritative, so an idle child must still
+    // receive done/cancel even if its last tracked task status was completed.
+    yield* refreshTrackedSubAgents(runtime, { preserveTerminalTaskStatus: false });
+    const shutdownReason = String(cmdMsg.args?.reason || defaultShutdownReason(mode));
+    const requestedBy = typeof cmdMsg.requestedBy === "string"
+        && cmdMsg.requestedBy === runtime.options.parentSessionId
+        && typeof cmdMsg.id === "string" && cmdMsg.id.trim()
+        ? cmdMsg.requestedBy : undefined;
+    const targetAgents = state.subAgents.filter((agent) => !isSubAgentTerminalStatus(agent.status));
+    if (targetAgents.length === 0) {
+        if (mode === "done") {
+            yield* completeSession(runtime, shutdownReason, cmdMsg.id, requestedBy);
+            return;
+        }
+        yield* cancelSession(runtime, shutdownReason, cmdMsg.id, mode === "delete", requestedBy);
+        return;
+    }
+    const childCmd = mode === "done" ? "done" : "cancel";
+    const childReason = mode === "done"
+        ? "Parent session completing"
+        : shutdownReason;
+    runtime.ctx.traceInfo(`[orch] ${cmdMsg.cmd}: cascading ${childCmd} to ${targetAgents.length} child session(s)`);
+    for (const child of targetAgents) {
+        try {
+            const childCmdId = `${cmdMsg.cmd}-cascade-${state.iteration}-${child.sessionId.slice(0, 8)}`;
+            yield runtime.manager.sendCommandToSession(child.sessionId, { type: "cmd", cmd: childCmd, id: childCmdId, args: { reason: childReason }, requestedBy: runtime.input.sessionId });
+        }
+        catch (err) {
+            runtime.ctx.traceInfo(`[orch] ${cmdMsg.cmd}: failed to signal child ${child.sessionId}: ${err.message} (non-fatal)`);
+        }
+    }
+    const startedAtMs = yield runtime.ctx.utcNow();
+    state.pendingShutdown = {
+        mode,
+        reason: shutdownReason,
+        startedAtMs,
+        deadlineAtMs: startedAtMs + SHUTDOWN_TIMEOUT_MS,
+        targetAgentIds: targetAgents.map((agent) => agent.orchId),
+        commandId: cmdMsg.id,
+        ...(requestedBy ? { requestedBy } : {}),
+    };
+    state.waitingForAgentIds = [...state.pendingShutdown.targetAgentIds];
+    clearPendingChildDigest(runtime);
+    state.activeTimer = {
+        deadlineMs: startedAtMs + SHUTDOWN_POLL_INTERVAL_MS,
+        originalDurationMs: SHUTDOWN_POLL_INTERVAL_MS,
+        reason: buildShutdownWaitReason(state.pendingShutdown),
+        type: "agent-poll",
+        agentIds: state.waitingForAgentIds,
+    };
+    publishStatus(runtime, "waiting", {
+        waitReason: buildShutdownWaitReason(state.pendingShutdown),
+        waitStartedAt: startedAtMs,
+        waitSeconds: Math.ceil(SHUTDOWN_TIMEOUT_MS / 1000),
+    });
+}
+// ─── Sub-agent tool actions (spawn/message/check/wait/etc.) ─
+export function* handleSubAgentAction(runtime, result) {
+    const { ctx, state } = runtime;
+    switch (result.type) {
+        case "spawn_agent": {
+            const childNestingLevel = runtime.options.nestingLevel + 1;
+            if (childNestingLevel > MAX_NESTING_LEVEL) {
+                ctx.traceInfo(`[orch] spawn_agent denied: nesting level ${runtime.options.nestingLevel} is at max (${MAX_NESTING_LEVEL})`);
+                queueFollowup(runtime, `[SYSTEM: spawn_agent failed — you are already at nesting level ${runtime.options.nestingLevel} (max ${MAX_NESTING_LEVEL}). ` +
+                    `Sub-agents at this depth cannot spawn further sub-agents. Handle the task directly instead.]`);
+                return true;
+            }
+            const activeCount = state.subAgents.filter(a => a.status === "running").length;
+            if (activeCount >= MAX_SUB_AGENTS) {
+                ctx.traceInfo(`[orch] spawn_agent denied: ${activeCount}/${MAX_SUB_AGENTS} agents running`);
+                queueFollowup(runtime, `[SYSTEM: spawn_agent failed — you already have ${activeCount} running sub-agents (max ${MAX_SUB_AGENTS}). ` +
+                    `Wait for some to complete before spawning more.]`);
+                return true;
+            }
+            let agentTask = result.task;
+            let agentSystemMessage = result.systemMessage;
+            let agentToolNames = result.toolNames;
+            const agentModel = result.model;
+            const agentReasoningEffort = result.reasoningEffort;
+            let agentIsSystem = false;
+            const explicitAgentTitle = typeof result.title === "string" && result.title.trim() ? result.title.trim() : undefined;
+            let agentTitle = explicitAgentTitle;
+            let agentTitleIsExplicit = Boolean(explicitAgentTitle);
+            let agentId;
+            let agentSplash;
+            let bootstrapRequiredTool;
+            let boundAgentName;
+            let boundAgentPackageId;
+            let promptLayeringKind;
+            let resolvedAgentName = result.agentName;
+            if (Object.hasOwn(result, "requiredTool") || Object.hasOwn(result, "required_tool")) {
+                queueFollowup(runtime, `[SYSTEM: spawn_agent failed — required_tool is no longer supported by spawn_agent. Use ps_list_agents to find a suitable named agent, then pass its exact agent_name and your assignment in task.]`);
+                return true;
+            }
+            const applyAgentDef = (agentDef) => {
+                agentTask = result.task || agentDef.initialPrompt || `You are the ${agentDef.name} agent. Begin your work.`;
+                agentSystemMessage = undefined;
+                // A named child's package owns its complete extra-tool surface.
+                // Explicit [] also prevents inheriting a parent's specialist tools.
+                agentToolNames = agentDef.tools ?? [];
+                agentIsSystem = agentDef.system ?? false;
+                if (!agentTitleIsExplicit)
+                    agentTitle = agentDef.title;
+                agentId = agentDef.id ?? agentDef.name;
+                agentSplash = agentDef.splash;
+                bootstrapRequiredTool = agentDef.initialRequiredTool;
+                boundAgentName = !agentDef.packageId && agentDef.namespace ? `${agentDef.namespace}:${agentDef.name}` : agentDef.name;
+                boundAgentPackageId = agentDef.packageId;
+                promptLayeringKind = agentDef.promptLayerKind
+                    ?? (agentDef.system
+                        ? ((agentDef.namespace || "pilotswarm") === "pilotswarm"
+                            ? "pilotswarm-system-agent"
+                            : "app-system-agent")
+                        : "app-agent");
+            };
+            let agentDef = null;
+            if (resolvedAgentName) {
+                ctx.traceInfo(`[orch] resolving agent config for: ${resolvedAgentName}`);
+                agentDef = yield runtime.manager.resolveAgentConfig(resolvedAgentName, runtime.input.sessionId);
+                if (!agentDef) {
+                    queueFollowup(runtime, `[SYSTEM: spawn_agent failed — agent "${resolvedAgentName}" not found. Use ps_list_agents to see available agents.]`);
+                    return true;
+                }
+            }
+            if (agentDef) {
+                if (agentDef.system && agentDef.creatable === false) {
+                    queueFollowup(runtime, `[SYSTEM: spawn_agent failed — agent "${resolvedAgentName}" is a worker-managed system agent and cannot be spawned from a session. ` +
+                        `If it is missing, the workers likely need to be restarted.]`);
+                    return true;
+                }
+                if (result.toolNames !== undefined) {
+                    queueFollowup(runtime, `[SYSTEM: spawn_agent failed — tool_names cannot override a bound named-agent definition. Use a custom task without agent_name, or remove tool_names.]`);
+                    return true;
+                }
+                if (result.systemMessage !== undefined) {
+                    queueFollowup(runtime, `[SYSTEM: spawn_agent failed — system_message cannot override a bound named-agent definition. Put the bounded assignment in task instead.]`);
+                    return true;
+                }
+                // The named definition owns its startup requirement.
+                applyAgentDef(agentDef);
+            }
+            // NOTE: a system parent does NOT make its children system.
+            // agentIsSystem stays purely definition-driven (agentDef.system —
+            // the worker-managed agents). Ad-hoc children of system sessions
+            // are ordinary deletable sessions that inherit the SYSTEM user as
+            // their OWNER instead (resolveEffectiveSpawnOwner in the
+            // spawnChildSession activity), which is how they reach the
+            // admin-stored System GitHub Copilot key.
+            if (agentModel && !agentModel.includes(":")) {
+                ctx.traceInfo(`[orch] spawn_agent denied: unqualified model override "${agentModel}"`);
+                queueFollowup(runtime, `[SYSTEM: spawn_agent failed — model "${agentModel}" is not allowed. ` +
+                    `When overriding a sub-agent model, first call list_available_models and then use the exact provider:model value from that list. ` +
+                    `If you are unsure, omit model so the sub-agent inherits your current model.]`);
+                return true;
+            }
+            if (!agentTitle && agentIsSystem) {
+                const text = agentTask || "";
+                const titleMatch = text.match(/You are the \*{0,2}([^*\n]+?)\*{0,2}\s*[—–-]/i)
+                    || text.match(/You are the \*{0,2}([^*\n]+?Agent)\*{0,2}/i);
+                if (titleMatch) {
+                    agentTitle = titleMatch[1].trim();
+                }
+            }
+            ctx.traceInfo(`[orch] spawning sub-agent via SDK: task="${agentTask.slice(0, 80)}" model=${agentModel || "inherit"} agent=${resolvedAgentName || "custom"} nestingLevel=${childNestingLevel}`);
+            const { boundAgentName: _parentBoundAgentName, boundAgentPackageId: _parentBoundAgentPackageId, boundAgentSource: _parentBoundAgentSource, namedAgentToolAdditions: _parentNamedAgentToolAdditions, childContract: _parentChildContract, detachedPackageToolPolicy: _parentDetachedPackageToolPolicy, promptLayering: _parentPromptLayering, agentIdentity: _parentAgentIdentity, isCrawler: _parentIsCrawler, isHarvester: _parentIsHarvester, ...parentConfig } = state.config;
+            const childConfig = {
+                ...parentConfig,
+                // Pass the assignment and sub-agent context to named children,
+                // not the parent's custom persona competing with their own.
+                ...(boundAgentName ? { systemMessage: undefined } : {}),
+                ...(agentModel ? { model: agentModel } : {}),
+                ...(agentReasoningEffort ? { reasoningEffort: agentReasoningEffort } : {}),
+                ...(result.contextTier !== undefined ? { contextTier: result.contextTier } : {}),
+                ...(agentSystemMessage ? { systemMessage: agentSystemMessage } : {}),
+                ...(boundAgentName ? { boundAgentName } : {}),
+                ...(boundAgentPackageId ? { boundAgentPackageId } : {}),
+                ...(boundAgentName && !boundAgentPackageId ? { boundAgentSource: "deployment" } : {}),
+                detachedPackageToolPolicy: boundAgentName || result.toolNames?.length ? "reject" : "drop",
+                ...(promptLayeringKind ? { promptLayering: { kind: promptLayeringKind } } : {}),
+                ...(agentToolNames ? { toolNames: agentToolNames } : {}),
+                ...(result.contract ? { childContract: result.contract } : {}),
+            };
+            const parentSystemMsg = typeof childConfig.systemMessage === "string"
+                ? childConfig.systemMessage
+                : childConfig.systemMessage?.content ?? "";
+            childConfig.systemMessage = buildSubAgentSystemMessage({
+                parentSessionId: runtime.input.sessionId,
+                childNestingLevel,
+                maxNestingLevel: MAX_NESTING_LEVEL,
+                agentTask,
+                agentIsSystem,
+                parentSystemMessage: parentSystemMsg,
+            });
+            let childSessionId;
+            try {
+                childSessionId = yield runtime.manager.spawnChildSession(runtime.input.sessionId, childConfig, agentTask, childNestingLevel, agentIsSystem, agentTitle, agentId, agentSplash, agentTitleIsExplicit, bootstrapRequiredTool);
+            }
+            catch (err) {
+                ctx.traceInfo(`[orch] spawnChildSession failed: ${err.message}`);
+                queueFollowup(runtime, `[SYSTEM: spawn_agent failed: ${err.message}]`);
+                return true;
+            }
+            const childOrchId = `session-${childSessionId}`;
+            yield runtime.manager.recordSessionEvent(runtime.input.sessionId, [{
+                    eventType: "session.agent_spawned",
+                    data: { childSessionId, agentId: agentId || undefined, task: agentTask.slice(0, 500) },
+                }]);
+            state.subAgents.push({
+                orchId: childOrchId,
+                sessionId: childSessionId,
+                task: agentTask.slice(0, 500),
+                status: "running",
+                agentId: agentId || undefined,
+                contract: result.contract,
+                expectsReport: true,
+            });
+            queueFollowup(runtime, `[SYSTEM: Sub-agent spawned successfully.\n` +
+                `  Agent ID: ${childOrchId}\n` +
+                `  ${resolvedAgentName ? `Agent: ${resolvedAgentName}\n  ` : ``}Task: "${agentTask.slice(0, 200)}"\n` +
+                `  The agent is now running autonomously. Continue your work in this SAME turn and keep following the user's remaining steps. ` +
+                `Do NOT stop just because the child started. If you need to pause, call wait or wait_for_agents explicitly. ` +
+                `You can also use check_agents to poll status, ` +
+                `or message_agent to send instructions.]`);
+            return true;
+        }
+        case "message_agent": {
+            const targetOrchId = result.agentId;
+            const agentEntry = state.subAgents.find(a => a.orchId === targetOrchId);
+            if (!agentEntry) {
+                ctx.traceInfo(`[orch] message_agent: unknown agent ${targetOrchId}`);
+                queueFollowup(runtime, `[SYSTEM: message_agent failed — agent "${targetOrchId}" not found. ` +
+                    `Known agents: ${state.subAgents.map(a => a.orchId).join(", ") || "none"}]`);
+                return true;
+            }
+            ctx.traceInfo(`[orch] message_agent via SDK: ${agentEntry.sessionId} msg="${result.message.slice(0, 60)}"`);
+            if (result.contractPatch && typeof result.contractPatch === "object") {
+                agentEntry.contract = {
+                    ...(agentEntry.contract ?? {}),
+                    ...result.contractPatch,
+                };
+            }
+            try {
+                yield runtime.manager.sendToSession(agentEntry.sessionId, result.message);
+            }
+            catch (err) {
+                ctx.traceInfo(`[orch] message_agent failed: ${err.message}`);
+                queueFollowup(runtime, `[SYSTEM: message_agent failed: ${err.message}]`);
+                return true;
+            }
+            queueFollowup(runtime, `[SYSTEM: Message sent to sub-agent ${targetOrchId}: "${result.message.slice(0, 200)}". ` +
+                `Continue your work in this SAME turn. If you are waiting on the child, call wait_for_agents explicitly rather than stopping here.]`);
+            return true;
+        }
+        case "check_agents": {
+            ctx.traceInfo(`[orch] check_agents: ${state.subAgents.length} agents tracked`);
+            if (state.subAgents.length === 0) {
+                queueFollowup(runtime, `[SYSTEM: No sub-agents have been spawned yet.]`);
+                return true;
+            }
+            const statusLines = [];
+            for (const agent of state.subAgents) {
+                try {
+                    const rawStatus = yield runtime.manager.getSessionStatus(agent.sessionId);
+                    const parsed = JSON.parse(rawStatus);
+                    if (parsed.status === "completed" || parsed.status === "failed" || parsed.status === "idle") {
+                        agent.status = parsed.status === "failed" ? "failed" : "completed";
+                        agent.result = getChildResultFromStatus(parsed, agent.result)?.slice(0, 1000);
+                    }
+                    statusLines.push(`  - Agent ${agent.orchId}\n` +
+                        `    Task: "${agent.task.slice(0, 120)}"\n` +
+                        `    Status: ${parsed.status}\n` +
+                        `    Iterations: ${parsed.iterations ?? 0}\n` +
+                        `    Output: ${getChildResultFromStatus(parsed, agent.result) ?? "(no output yet)"}`);
+                }
+                catch (err) {
+                    statusLines.push(`  - Agent ${agent.orchId}\n` +
+                        `    Task: "${agent.task.slice(0, 120)}"\n` +
+                        `    Status: unknown (error: ${err.message})`);
+                }
+            }
+            queueFollowup(runtime, `[SYSTEM: Sub-agent status report (${state.subAgents.length} agents):\n${statusLines.join("\n")}]`);
+            return true;
+        }
+        case "list_sessions": {
+            ctx.traceInfo(`[orch] list_sessions`);
+            const rawSessions = yield runtime.manager.listSessions({
+                includeSystem: result.includeSystem,
+                ownerQuery: result.ownerQuery,
+                ownerKind: result.ownerKind,
+            });
+            const sessions = JSON.parse(rawSessions);
+            if (!Array.isArray(sessions) || sessions.length === 0) {
+                queueFollowup(runtime, "[SYSTEM: Active sessions (0). No sessions matched the requested filters.]");
+                return true;
+            }
+            const lines = sessions.map((s) => `  - ${s.sessionId}${s.sessionId === runtime.input.sessionId ? " (this session)" : ""}\n` +
+                `    Title: ${s.title ?? "(untitled)"}\n` +
+                `    Owner: ${s.ownerKind === "system"
+                    ? "system"
+                    : s.ownerKind === "unowned"
+                        ? "unowned"
+                        : (s.owner?.displayName || s.owner?.email || [s.owner?.provider, s.owner?.subject].filter(Boolean).join(":") || "user")}\n` +
+                `    Status: ${s.status}, Iterations: ${s.iterations ?? 0}\n` +
+                `    Parent: ${s.parentSessionId ?? "none"}`);
+            queueFollowup(runtime, `[SYSTEM: Active sessions (${sessions.length}):\n${lines.join("\n")}]`);
+            return true;
+        }
+        case "wait_for_agents": {
+            let targetIds = result.agentIds;
+            if (!targetIds || targetIds.length === 0) {
+                const runningAgentIds = state.subAgents.filter(a => a.status === "running").map(a => a.orchId);
+                targetIds = runningAgentIds.length > 0
+                    ? runningAgentIds
+                    : state.subAgents.map(a => a.orchId);
+            }
+            if (targetIds.length === 0) {
+                ctx.traceInfo(`[orch] wait_for_agents: no running agents to wait for`);
+                queueFollowup(runtime, `[SYSTEM: No running sub-agents to wait for. All agents have already completed.]`);
+                return true;
+            }
+            const stillRunning = targetIds.filter((id) => {
+                const agent = state.subAgents.find(a => a.orchId === id);
+                return agent && !isSubAgentTerminalStatus(agent.status);
+            });
+            if (stillRunning.length === 0) {
+                queueFollowup(runtime, buildWaitForAgentsFollowup(state.subAgents, targetIds));
+                return true;
+            }
+            ctx.traceInfo(`[orch] wait_for_agents: waiting for ${targetIds.length} agents`);
+            state.waitingForAgentIds = targetIds;
+            const agentPollNow = yield ctx.utcNow();
+            // The turn is over and the session is parked (interruptible — an
+            // interactive prompt preempts the poll), so surface "waiting" with
+            // a reason like every other durable wait. Publishing "running"
+            // here made the UI spin "Working…" for the whole agent wait.
+            publishStatus(runtime, "waiting", {
+                waitReason: `waiting for ${targetIds.length} agent(s)`,
+                waitStartedAt: agentPollNow,
+            });
+            state.activeTimer = {
+                deadlineMs: agentPollNow + 30_000,
+                originalDurationMs: 30_000,
+                reason: `waiting for ${targetIds.length} agent(s)`,
+                type: "agent-poll",
+                agentIds: targetIds,
+            };
+            return true;
+        }
+        case "complete_agent": {
+            const targetOrchId = result.agentId;
+            const agentEntry = state.subAgents.find(a => a.orchId === targetOrchId);
+            if (!agentEntry) {
+                ctx.traceInfo(`[orch] complete_agent: unknown agent ${targetOrchId}`);
+                queueFollowup(runtime, `[SYSTEM: complete_agent failed — agent "${targetOrchId}" not found. ` +
+                    `Known agents: ${state.subAgents.map(a => a.orchId).join(", ") || "none"}]`);
+                return true;
+            }
+            ctx.traceInfo(`[orch] complete_agent: sending /done to ${agentEntry.sessionId}`);
+            try {
+                const cmdId = `done-${state.iteration}`;
+                yield runtime.manager.sendCommandToSession(agentEntry.sessionId, { type: "cmd", cmd: "done", id: cmdId, args: { reason: "Completed by parent" }, requestedBy: runtime.input.sessionId });
+            }
+            catch (err) {
+                ctx.traceInfo(`[orch] complete_agent failed: ${err.message}`);
+                queueFollowup(runtime, `[SYSTEM: complete_agent failed: ${err.message}]`);
+                return true;
+            }
+            queueFollowup(runtime, `[SYSTEM: Graceful completion requested for sub-agent ${targetOrchId}. ` +
+                `Use check_agents or wait_for_agents to observe final completion.]`);
+            return true;
+        }
+        case "cancel_agent": {
+            const targetOrchId = result.agentId;
+            const agentEntry = state.subAgents.find(a => a.orchId === targetOrchId);
+            if (!agentEntry) {
+                ctx.traceInfo(`[orch] cancel_agent: unknown agent ${targetOrchId}`);
+                queueFollowup(runtime, `[SYSTEM: cancel_agent failed — agent "${targetOrchId}" not found. ` +
+                    `Known agents: ${state.subAgents.map(a => a.orchId).join(", ") || "none"}]`);
+                return true;
+            }
+            const cancelReason = result.reason ?? "Cancelled by parent";
+            ctx.traceInfo(`[orch] cancel_agent: sending cancel to ${agentEntry.sessionId} reason="${cancelReason}"`);
+            try {
+                const cmdId = `cancel-${state.iteration}-${agentEntry.sessionId.slice(0, 8)}`;
+                yield runtime.manager.sendCommandToSession(agentEntry.sessionId, { type: "cmd", cmd: "cancel", id: cmdId, args: { reason: cancelReason }, requestedBy: runtime.input.sessionId });
+            }
+            catch (err) {
+                ctx.traceInfo(`[orch] cancel_agent failed: ${err.message}`);
+                queueFollowup(runtime, `[SYSTEM: cancel_agent failed: ${err.message}]`);
+                return true;
+            }
+            queueFollowup(runtime, `[SYSTEM: Graceful cancellation requested for sub-agent ${targetOrchId}. ` +
+                `Use check_agents or wait_for_agents to observe final termination.${result.reason ? ` Reason: ${result.reason}` : ""}]`);
+            return true;
+        }
+        case "delete_agent": {
+            const targetOrchId = result.agentId;
+            const agentEntry = state.subAgents.find(a => a.orchId === targetOrchId);
+            if (!agentEntry) {
+                ctx.traceInfo(`[orch] delete_agent: unknown agent ${targetOrchId}`);
+                queueFollowup(runtime, `[SYSTEM: delete_agent failed — agent "${targetOrchId}" not found. ` +
+                    `Known agents: ${state.subAgents.map(a => a.orchId).join(", ") || "none"}]`);
+                return true;
+            }
+            const deleteReason = result.reason ?? "Deleted by parent";
+            ctx.traceInfo(`[orch] delete_agent: deleting ${agentEntry.sessionId} reason="${deleteReason}"`);
+            try {
+                if (isSubAgentTerminalStatus(agentEntry.status)) {
+                    yield runtime.manager.deleteSession(agentEntry.sessionId, deleteReason);
+                    state.subAgents = state.subAgents.filter((agent) => agent.orchId !== targetOrchId);
+                    queueFollowup(runtime, `[SYSTEM: Sub-agent ${targetOrchId} has been deleted.${result.reason ? ` Reason: ${result.reason}` : ""}]`);
+                    return true;
+                }
+                const cmdId = `delete-${state.iteration}-${agentEntry.sessionId.slice(0, 8)}`;
+                yield runtime.manager.sendCommandToSession(agentEntry.sessionId, { type: "cmd", cmd: "delete", id: cmdId, args: { reason: deleteReason }, requestedBy: runtime.input.sessionId });
+            }
+            catch (err) {
+                ctx.traceInfo(`[orch] delete_agent failed: ${err.message}`);
+                queueFollowup(runtime, `[SYSTEM: delete_agent failed: ${err.message}]`);
+                return true;
+            }
+            queueFollowup(runtime, `[SYSTEM: Graceful deletion requested for sub-agent ${targetOrchId}. ` +
+                `It will cancel its descendants first and then delete itself.${result.reason ? ` Reason: ${result.reason}` : ""}]`);
+            return true;
+        }
+        default:
+            return false;
+    }
+}
+//# sourceMappingURL=agents.js.map