@spinabot/brigade 0.1.2 → 1.0.1

package/dist/agents/subagent-runner.js

@@ -0,0 +1,358 @@
+/**
+ * Sub-agent runner — Primitive #6.
+ *
+ * Drives a CHILD `runSingleTurn` for an ephemeral session keyed off the
+ * parent. The child gets:
+ *
+ *   - Its own session key — `agent:<id>:subagent:<uuid>` — which lands its
+ *     transcript in a separate JSONL file, isolates its message history, and
+ *     trips the system-prompt assembler's minimal-mode switch (Commit 2).
+ *   - The parent's persona dir (single-user → shared SOUL/IDENTITY/USER).
+ *   - A linked abort signal that fires from EITHER the parent's cancellation
+ *     OR a wall-clock timeout (default 300s, override per call).
+ *   - The same hardened loop (auth, model registry, exec-gate, retry,
+ *     stream wrappers) the parent runs — by recursing into `runSingleTurn`
+ *     rather than rebuilding session wiring.
+ *
+ * Slot accounting + race-safe reservation lives in `subagent-policy.ts`;
+ * this module orchestrates: reserve → mark started → run → release → optional
+ * transcript delete → report.
+ *
+ * Pi 0.70.6 was verified safe for nested AgentSessions (per-Agent activeRun
+ * check, no global locks, per-session event subscriptions). The child's Pi
+ * session is created inside `runSingleTurn`, which always builds a fresh
+ * Agent + AgentSession — so the parent's session is never reused.
+ */
+import { randomUUID } from "node:crypto";
+import { promises as fs } from "node:fs";
+import { readConfigOrInit } from "../config/io.js";
+import { resolveSessionTranscriptPath } from "../config/paths.js";
+import { createSubsystemLogger } from "../logging/subsystem-logger.js";
+import { deleteSessionEntry, } from "../sessions/session-store.js";
+import { buildChildSessionKey, getSubagentDepthFromSessionKey, markSubagentRunStarted, releaseSubagentSlot, reserveSubagentSlot, resolveSubagentLimits, SubagentLimitError, } from "./subagent-policy.js";
+const log = createSubsystemLogger("subagent/run");
+/**
+ * Combine an arbitrary number of optional AbortSignals into one. Uses
+ * `AbortSignal.any` when the runtime exposes it (Node 22+ — Brigade's target),
+ * with a manual fallback for older runtimes. Returning the input directly when
+ * only one signal is present avoids an unnecessary controller allocation.
+ */
+function combineAbortSignals(...signals) {
+    const live = signals.filter((s) => s !== undefined);
+    if (live.length === 0)
+        return new AbortController().signal;
+    if (live.length === 1)
+        return live[0];
+    const anyFn = AbortSignal.any;
+    if (typeof anyFn === "function")
+        return anyFn(live);
+    const controller = new AbortController();
+    const onAbort = (reason) => controller.abort(reason);
+    for (const s of live) {
+        if (s.aborted) {
+            controller.abort(s.reason);
+            break;
+        }
+        s.addEventListener("abort", () => onAbort(s.reason), { once: true });
+    }
+    return controller.signal;
+}
+function resolveDefaultProvider(config) {
+    const provider = config.agents?.defaults?.provider;
+    if (typeof provider === "string" && provider.length > 0)
+        return provider;
+    return "anthropic";
+}
+function resolveDefaultModel(config) {
+    const model = config.agents?.defaults?.model?.primary;
+    if (typeof model === "string" && model.length > 0)
+        return model;
+    return "claude-opus-4-7";
+}
+/** Read the per-agent override block from `config.agents.<agentId>` — used
+ *  so a sub-agent inherits its parent agent's model rather than always
+ *  falling back to `agents.defaults`. */
+function readAgentOverride(config, agentId) {
+    if (!agentId)
+        return undefined;
+    const agents = config.agents;
+    if (!agents)
+        return undefined;
+    const ov = agents[agentId];
+    if (!ov || typeof ov !== "object")
+        return undefined;
+    return ov;
+}
+/** Per-agent provider — `cfg.agents.<agentId>.provider` wins, then defaults. */
+function resolveAgentProvider(config, agentId) {
+    const ov = readAgentOverride(config, agentId);
+    if (ov && typeof ov.provider === "string" && ov.provider.length > 0) {
+        return ov.provider;
+    }
+    return resolveDefaultProvider(config);
+}
+/** Per-agent model — `cfg.agents.<agentId>.model.primary` wins, then defaults. */
+function resolveAgentModel(config, agentId) {
+    const ov = readAgentOverride(config, agentId);
+    if (ov?.model && typeof ov.model.primary === "string" && ov.model.primary.length > 0) {
+        return ov.model.primary;
+    }
+    return resolveDefaultModel(config);
+}
+/**
+ * Build the child's first user message. Wraps the raw task in structured
+ * prefixes so the model can distinguish framing-from-system vs the actual
+ * instruction it must execute:
+ *
+ *   [Sub-agent Context] You are running as a sub-agent (depth N/M)...
+ *   [Sub-agent Task]: <verbatim task>
+ *
+ * Mirrors the proven shape: separating context from task improves task
+ * adherence on smaller models that otherwise blur the boundary.
+ */
+function buildChildFirstUserMessage(args) {
+    const lines = [
+        `[Sub-agent Context] You are running as a sub-agent (depth ${args.childDepth}/${args.maxDepth}). ` +
+            `Your final assistant reply becomes the parent's tool result; the operator will not see ` +
+            `any of your intermediate output. Do NOT poll, do NOT busy-wait — just do the task and reply once.`,
+        `[Sub-agent Task]: ${args.task}`,
+    ];
+    void args.label; // reserved for future "labeled context" expansion
+    return lines.join("\n\n");
+}
+/**
+ * Best-effort transcript file deletion. Called when `cleanup === "delete"`
+ * after the run settles. Swallows errors (missing file, permission issues)
+ * because the run already settled — failing here would obscure the real
+ * outcome with a cleanup throw, and the operator can always `rm` it manually.
+ *
+ * Takes the resolved `sessionId` (UUID) rather than the sessionKey, because
+ * `resolveSessionTranscriptPath` derives `<sessionsDir>/<sessionId>.jsonl`
+ * from the UUID — the sessionId is whatever `runSingleTurn` returned in its
+ * `result.sessionId`, so we delete the exact file the run wrote to.
+ */
+async function maybeDeleteChildTranscript(args) {
+    try {
+        const transcriptPath = resolveSessionTranscriptPath(args.parentAgentId, args.sessionId);
+        await fs.rm(transcriptPath, { force: true });
+    }
+    catch (err) {
+        log.warn("transcript cleanup failed", {
+            sessionId: args.sessionId,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+/**
+ * Run a sub-agent end-to-end:
+ *
+ *   1. Resolve limits + caller depth (from the parent's session key shape).
+ *   2. `reserveSubagentSlot` — atomic check + register; throws
+ *      `SubagentLimitError` on violation; the caller (the `spawn_agent` tool)
+ *      converts that to a refusal result.
+ *   3. Mark the slot started, arm the timeout.
+ *   4. Recurse into `runSingleTurn` with the child key + framed task. The
+ *      dynamic import breaks the registry → tool → runner → agent-loop →
+ *      session-wiring → registry cycle that a static import would create.
+ *   5. Catch abort / timeout → return a synthetic reply describing what
+ *      happened so the parent's tool result is never empty.
+ *   6. Always `releaseSubagentSlot` in `finally` with the resolved outcome
+ *      + clear the timeout. Optionally delete the child's transcript.
+ */
+export async function runSubagent(args) {
+    const config = readConfigOrInit();
+    const limits = resolveSubagentLimits(config);
+    const callerDepth = getSubagentDepthFromSessionKey(args.parentSessionKey);
+    const label = args.label ?? "sub-agent";
+    // Operator-controlled — the model never gets to set this. Reads from
+    // `agents.defaults.subagents.cleanup` (default `"keep"`).
+    const cleanup = limits.defaultCleanup;
+    // D1 — parent-abort fast-fail. A depth-1 lead that spends its whole budget on
+    // its own work before fanning out can have its run timer fire (or be cancelled)
+    // in the same tick it dispatches children. Without this guard the child would
+    // reserve a slot, log "sub-agent starting", recurse into runSingleTurn, and die
+    // on the already-aborted signal at its first abort-aware await (durationMs≈1) —
+    // surfacing as a fake `aborted` child plus a misleading "starting" log and
+    // needless session-store churn. Refuse up-front with a typed signal so the
+    // spawn envelope reports, honestly, that the parent ran out of budget instead.
+    if (args.parentSignal?.aborted) {
+        throw new SubagentLimitError(`Sub-agent "${label}" not started: the parent run was already cancelled or out of budget before this child could begin.`, "parent-aborted");
+    }
+    const childSessionKey = buildChildSessionKey(args.parentSessionKey, randomUUID());
+    // Race-safe atomic reserve. Throws SubagentLimitError on depth /
+    // concurrency violation; the spawn tool's catch converts that to a
+    // refusal tool-result.
+    reserveSubagentSlot({
+        parentSessionKey: args.parentSessionKey,
+        childSessionKey,
+        ...(args.parentRunId !== undefined ? { parentRunId: args.parentRunId } : {}),
+        label,
+        callerDepth,
+        limits,
+        cleanup,
+    });
+    // `timeoutSeconds <= 0` is a footgun: setTimeout(...,0) fires on the next
+    // tick, aborting the child before runSingleTurn can do anything useful.
+    // Clamp to a 1-second floor so a misconfigured `timeoutSeconds: 0` becomes
+    // a hard-but-survivable cap instead of an instant kill. A real "no timeout"
+    // API would be a separate flag — we deliberately don't support it because
+    // runaway child runs are the worst failure mode for an autonomous loop.
+    const requestedTimeout = args.timeoutSeconds ?? limits.defaultTimeoutSeconds;
+    const timeoutSeconds = requestedTimeout > 0 ? requestedTimeout : 1;
+    const timeoutController = new AbortController();
+    const timeoutHandle = setTimeout(() => {
+        timeoutController.abort(new Error(`sub-agent timed out after ${timeoutSeconds}s`));
+    }, timeoutSeconds * 1000);
+    // Don't keep the event loop alive solely for this timer — the parent's
+    // pending promise already keeps the process alive while the child runs.
+    if (typeof timeoutHandle.unref === "function") {
+        timeoutHandle.unref?.();
+    }
+    const combinedSignal = combineAbortSignals(args.parentSignal, timeoutController.signal);
+    // Per-agent override resolution — when the parent agent has a non-default
+    // `cfg.agents.<parentAgentId>` block, the child inherits its provider/
+    // model from there rather than falling back to `cfg.agents.defaults`.
+    const provider = args.provider ?? resolveAgentProvider(config, args.parentAgentId);
+    const modelId = args.modelId ?? resolveAgentModel(config, args.parentAgentId);
+    const startMs = Date.now();
+    const childDepth = callerDepth + 1;
+    log.info("sub-agent starting", {
+        parentSessionKey: args.parentSessionKey,
+        childSessionKey,
+        label,
+        depth: childDepth,
+        maxDepth: limits.maxDepth,
+        timeoutSeconds,
+        provider,
+        modelId,
+        cleanup,
+    });
+    const framedTask = buildChildFirstUserMessage({
+        task: args.task,
+        childDepth,
+        maxDepth: limits.maxDepth,
+        label,
+    });
+    // Primitive #6 — metadata persisted on the child's session-store entry so
+    // post-crash forensics + `brigade sessions list` can identify children +
+    // walk the ancestry chain via `spawnedBy`. Written ONCE at session
+    // creation by runSingleTurn → resolveOrCreateSession.
+    const subagentMetadata = {
+        spawnDepth: childDepth,
+        spawnedBy: args.parentSessionKey,
+        ...(args.parentRunId !== undefined ? { parentRunId: args.parentRunId } : {}),
+        label,
+        cleanup,
+        spawnedAt: new Date().toISOString(),
+    };
+    let reply = "";
+    let aborted = false;
+    let timedOut = false;
+    let runError;
+    let childSessionId;
+    try {
+        // Lazy import severs the static-import cycle:
+        //   subagent-runner → agent-loop → session-wiring → registry → spawn-agent-tool
+        // At call time `agent-loop.js` has long since finished evaluating, so the
+        // dynamic import resolves instantly from the module cache.
+        const { runSingleTurn } = await import("./agent-loop.js");
+        markSubagentRunStarted(args.parentSessionKey, childSessionKey);
+        const result = await runSingleTurn({
+            agentId: args.parentAgentId,
+            provider,
+            modelId,
+            message: framedTask,
+            sessionKey: childSessionKey,
+            ...(args.thinkingLevel !== undefined ? { thinkingLevel: args.thinkingLevel } : {}),
+            signal: combinedSignal,
+            senderIsOwner: true,
+            // Primitive #6 — surface attribution to exec-gate so any bash call
+            // the child makes shows "Sub-agent '<label>' wants to run …" to the
+            // operator instead of the default "Brigade wants to run …".
+            subagentLabel: label,
+            ...(args.parentRunId !== undefined ? { parentRunId: args.parentRunId } : {}),
+            // Primitive #6 — persist sub-agent metadata on the child's session
+            // entry so a `cat ~/.brigade/agents/<id>/sessions/sessions.json`
+            // after a crash shows what the child was, who spawned it, and what
+            // cleanup policy it ran under.
+            subagentMetadata,
+        });
+        reply = result.reply;
+        childSessionId = result.sessionId;
+    }
+    catch (err) {
+        aborted = combinedSignal.aborted;
+        timedOut = timeoutController.signal.aborted;
+        if (!aborted) {
+            runError = err instanceof Error ? err.message : String(err);
+        }
+        if (!aborted) {
+            // Genuine error from the child run — re-throw so the spawn tool can
+            // surface a "sub-agent crashed" message instead of swallowing silently.
+            // Cleanup (clearTimeout + releaseSubagentSlot + optional transcript
+            // delete) happens in the `finally` block below.
+            throw err;
+        }
+        reply = timedOut
+            ? `Sub-agent "${label}" timed out after ${timeoutSeconds}s before producing a reply.`
+            : `Sub-agent "${label}" was cancelled before producing a reply.`;
+    }
+    finally {
+        clearTimeout(timeoutHandle);
+        const outcome = runError
+            ? "error"
+            : timedOut
+                ? "timed-out"
+                : aborted
+                    ? "aborted"
+                    : "ok";
+        releaseSubagentSlot({
+            parentSessionKey: args.parentSessionKey,
+            childSessionKey,
+            outcome,
+            ...(runError !== undefined ? { error: runError } : {}),
+        });
+        // Only delete the transcript when we actually obtained a sessionId
+        // from runSingleTurn — a child that crashed BEFORE the session was
+        // opened has no file to delete and `childSessionId` stays undefined.
+        // Also drop the session-store entry so a phantom record doesn't
+        // outlive its transcript and clutter `brigade sessions list`. The
+        // helper is idempotent: a fresh-then-crashed run that wrote the
+        // entry but no JSONL still gets the entry pruned here.
+        if (cleanup === "delete") {
+            if (childSessionId !== undefined) {
+                await maybeDeleteChildTranscript({
+                    parentAgentId: args.parentAgentId,
+                    sessionId: childSessionId,
+                });
+            }
+            try {
+                deleteSessionEntry(args.parentAgentId, childSessionKey);
+            }
+            catch (err) {
+                log.warn("session-entry cleanup failed", {
+                    childSessionKey,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+    }
+    const durationMs = Date.now() - startMs;
+    log.info("sub-agent settled", {
+        parentSessionKey: args.parentSessionKey,
+        childSessionKey,
+        label,
+        durationMs,
+        aborted,
+        timedOut,
+        replyChars: reply.length,
+    });
+    return {
+        childSessionKey,
+        reply,
+        durationMs,
+        aborted,
+        timedOut,
+    };
+}
+//# sourceMappingURL=subagent-runner.js.map

package/dist/agents/subagent-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-runner.js","sourceRoot":"","sources":["../../src/agents/subagent-runner.ts"],"names":[],"mappings":"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"}

package/dist/agents/subagent-spawn-abort-marker.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Wave O0.8 GAP 9 — pending-abort marker for the spawn registration → dispatch race window.
+ *
+ * Problem: when `subagent-spawn.ts:spawnSubagentDirect` calls
+ * `registerSubagentRun` and then `await callGateway`, the live-session
+ * registry has NOT yet seen the child. If the parent aborts during this
+ * window, the cascade walks `listActiveSubagentRunsForController`, finds
+ * the run, calls `abortLiveSession(childKey)` — which returns false (no
+ * live entry) — and the child then proceeds to dispatch and run.
+ *
+ * Fix: when the cascade fires for a child that has no live entry yet, it
+ * leaves a marker keyed by `childSessionKey`. `dispatchAgentRun` consults
+ * the marker BEFORE registering the live session; if present, the child
+ * is short-circuited to an abort outcome and never invokes the adapter.
+ *
+ * Single-writer/single-reader pattern: the cascade writes via
+ * `markPendingDispatchAbort`, the dispatcher reads + clears via
+ * `consumePendingDispatchAbort`. Markers are also cleared on successful
+ * live-session registration (in dispatchAgentRun) so a later parent abort
+ * routes through `abortLiveSession` as usual.
+ *
+ * Markers carry the abort reason (operator-ctrl-c, parent-aborted,
+ * shutdown, …) so downstream classification preserves the cause.
+ */
+/**
+ * Mark `sessionKey` as pre-aborted. Idempotent — repeat calls keep the
+ * FIRST reason (the originating cascade) so a later "shutdown" sweep
+ * doesn't overwrite a more meaningful "parent-aborted".
+ */
+export declare function markPendingDispatchAbort(sessionKey: string, reason?: string): void;
+/**
+ * Atomically read + clear the marker for `sessionKey`. Returns the abort
+ * reason when a marker was present, or `null` when no marker existed.
+ */
+export declare function consumePendingDispatchAbort(sessionKey: string): string | null;
+/**
+ * Clear any marker for `sessionKey` without returning it. Used by the
+ * dispatcher after successful live-session registration so a late marker
+ * doesn't poison a subsequent legitimate run for the same key.
+ */
+export declare function clearPendingDispatchAbort(sessionKey: string): void;
+/** True iff a marker is queued for the sessionKey. */
+export declare function hasPendingDispatchAbort(sessionKey: string): boolean;
+/** Test-only — wipe every marker. */
+export declare function resetPendingDispatchAbortForTests(): void;
+//# sourceMappingURL=subagent-spawn-abort-marker.d.ts.map

package/dist/agents/subagent-spawn-abort-marker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-spawn-abort-marker.d.ts","sourceRoot":"","sources":["../../src/agents/subagent-spawn-abort-marker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAiBH;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAMlF;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQ7E;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAIlE;AAED,sDAAsD;AACtD,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAInE;AAED,qCAAqC;AACrC,wBAAgB,iCAAiC,IAAI,IAAI,CAExD"}

package/dist/agents/subagent-spawn-abort-marker.js

@@ -0,0 +1,81 @@
+/**
+ * Wave O0.8 GAP 9 — pending-abort marker for the spawn registration → dispatch race window.
+ *
+ * Problem: when `subagent-spawn.ts:spawnSubagentDirect` calls
+ * `registerSubagentRun` and then `await callGateway`, the live-session
+ * registry has NOT yet seen the child. If the parent aborts during this
+ * window, the cascade walks `listActiveSubagentRunsForController`, finds
+ * the run, calls `abortLiveSession(childKey)` — which returns false (no
+ * live entry) — and the child then proceeds to dispatch and run.
+ *
+ * Fix: when the cascade fires for a child that has no live entry yet, it
+ * leaves a marker keyed by `childSessionKey`. `dispatchAgentRun` consults
+ * the marker BEFORE registering the live session; if present, the child
+ * is short-circuited to an abort outcome and never invokes the adapter.
+ *
+ * Single-writer/single-reader pattern: the cascade writes via
+ * `markPendingDispatchAbort`, the dispatcher reads + clears via
+ * `consumePendingDispatchAbort`. Markers are also cleared on successful
+ * live-session registration (in dispatchAgentRun) so a later parent abort
+ * routes through `abortLiveSession` as usual.
+ *
+ * Markers carry the abort reason (operator-ctrl-c, parent-aborted,
+ * shutdown, …) so downstream classification preserves the cause.
+ */
+import { resolveGlobalSingleton } from "../shared/global-singleton.js";
+const PENDING_DISPATCH_ABORT_STATE_KEY = Symbol.for("brigade.subagent.pendingDispatchAbort");
+function getState() {
+    return resolveGlobalSingleton(PENDING_DISPATCH_ABORT_STATE_KEY, () => ({ markers: new Map() }));
+}
+/**
+ * Mark `sessionKey` as pre-aborted. Idempotent — repeat calls keep the
+ * FIRST reason (the originating cascade) so a later "shutdown" sweep
+ * doesn't overwrite a more meaningful "parent-aborted".
+ */
+export function markPendingDispatchAbort(sessionKey, reason) {
+    const key = sessionKey?.trim();
+    if (!key)
+        return;
+    const state = getState();
+    if (state.markers.has(key))
+        return;
+    state.markers.set(key, (reason ?? "aborted").toString());
+}
+/**
+ * Atomically read + clear the marker for `sessionKey`. Returns the abort
+ * reason when a marker was present, or `null` when no marker existed.
+ */
+export function consumePendingDispatchAbort(sessionKey) {
+    const key = sessionKey?.trim();
+    if (!key)
+        return null;
+    const state = getState();
+    const reason = state.markers.get(key);
+    if (reason === undefined)
+        return null;
+    state.markers.delete(key);
+    return reason;
+}
+/**
+ * Clear any marker for `sessionKey` without returning it. Used by the
+ * dispatcher after successful live-session registration so a late marker
+ * doesn't poison a subsequent legitimate run for the same key.
+ */
+export function clearPendingDispatchAbort(sessionKey) {
+    const key = sessionKey?.trim();
+    if (!key)
+        return;
+    getState().markers.delete(key);
+}
+/** True iff a marker is queued for the sessionKey. */
+export function hasPendingDispatchAbort(sessionKey) {
+    const key = sessionKey?.trim();
+    if (!key)
+        return false;
+    return getState().markers.has(key);
+}
+/** Test-only — wipe every marker. */
+export function resetPendingDispatchAbortForTests() {
+    getState().markers.clear();
+}
+//# sourceMappingURL=subagent-spawn-abort-marker.js.map

package/dist/agents/subagent-spawn-abort-marker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-spawn-abort-marker.js","sourceRoot":"","sources":["../../src/agents/subagent-spawn-abort-marker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAMvE,MAAM,gCAAgC,GAAG,MAAM,CAAC,GAAG,CAAC,uCAAuC,CAAC,CAAC;AAE7F,SAAS,QAAQ;IAChB,OAAO,sBAAsB,CAC5B,gCAAgC,EAChC,GAAG,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,GAAG,EAAE,EAAE,CAAC,CAC9B,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CAAC,UAAkB,EAAE,MAAe;IAC3E,MAAM,GAAG,GAAG,UAAU,EAAE,IAAI,EAAE,CAAC;IAC/B,IAAI,CAAC,GAAG;QAAE,OAAO;IACjB,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC;IACzB,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC;QAAE,OAAO;IACnC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,MAAM,IAAI,SAAS,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;AAC1D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,2BAA2B,CAAC,UAAkB;IAC7D,MAAM,GAAG,GAAG,UAAU,EAAE,IAAI,EAAE,CAAC;IAC/B,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACtB,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC;IACzB,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACtC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACtC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1B,OAAO,MAAM,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CAAC,UAAkB;IAC3D,MAAM,GAAG,GAAG,UAAU,EAAE,IAAI,EAAE,CAAC;IAC/B,IAAI,CAAC,GAAG;QAAE,OAAO;IACjB,QAAQ,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAChC,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,uBAAuB,CAAC,UAAkB;IACzD,MAAM,GAAG,GAAG,UAAU,EAAE,IAAI,EAAE,CAAC;IAC/B,IAAI,CAAC,GAAG;QAAE,OAAO,KAAK,CAAC;IACvB,OAAO,QAAQ,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACpC,CAAC;AAED,qCAAqC;AACrC,MAAM,UAAU,iCAAiC;IAChD,QAAQ,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;AAC5B,CAAC"}

package/dist/agents/subagent-spawn.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Sub-agent spawn engine (Step 20).
+ *
+ * Brand-scrubbed analogue of upstream's `src/agents/subagent-spawn.ts`,
+ * scoped to the operations Brigade can perform at this milestone. The
+ * upstream engine is 900+ LOC and references modules Brigade does not
+ * yet have (sandbox runtime status, ACP child runtime, attachment
+ * materialiser, thread-binding hooks, model-and-thinking plan resolver).
+ * Brigade's slim engine focuses on the LOAD-BEARING parts:
+ *
+ *   1. Validate target agent id + reject malformed ids before normalisation.
+ *   2. Enforce depth cap + max-children cap (read from Step 9's session
+ *      store metadata).
+ *   3. Generate the child session key (`agent:<targetAgentId>:subagent:<UUID>`).
+ *   4. Register the run in Step 10's subagent-registry.
+ *   5. Emit a `subagent_lifecycle:subagent_started` agent event (Step 18).
+ *   6. Hand off the initial child turn to the gateway via Step 18's
+ *      `callGateway` (`method: "agent"`, `lane: AGENT_LANE_SUBAGENT`).
+ *   7. On gateway error → registry cleanup + structured error result.
+ *
+ * What this engine DOES NOT do (deferred):
+ *
+ *   - Sandbox-mode validation (Brigade has no sandbox runtime yet).
+ *   - ACP runtime branching (Brigade is sub-agent-only per the locked
+ *     design's R2 Leak #10).
+ *   - Attachment materialisation (per-file copy into child workspace).
+ *   - Thread-binding hook fire-order (waits for Step 25's gateway).
+ *   - Model + thinking-level plan resolution (passes through to gateway).
+ *
+ * Adding any of those is additive — none of the public APIs here need to
+ * change for the deferred layers to slot in later.
+ */
+import type { SpawnSubagentMode, SpawnSubagentSandboxMode } from "./subagent-registry.types.js";
+/**
+ * Wave N4 — default per-call wall-clock cap for a gateway-routed sub-agent
+ * run when the caller (typically the `sessions_spawn` tool) does NOT
+ * supply `runTimeoutSeconds`. Pre-Wave-N4 the engine forwarded
+ * `runTimeoutSeconds: undefined` straight to the gateway `agent` handler,
+ * which then ran the child with NO enforced cap — three of five parallel
+ * children were observed timing out at 60s elsewhere in the stack while
+ * the harness sat idle waiting on the missing reply, masking the real
+ * timeout. 180s is generous (above the slow-path tail of any realistic
+ * tool-using turn but well below "model is hung forever") and matches the
+ * documented `agents.defaults.subagents.defaultTimeoutSeconds` knob's
+ * intent of "model can take its time but never pins a slot indefinitely".
+ *
+ * Operators override per-call by passing `runTimeoutSeconds` on the
+ * `sessions_spawn` call; the `cfg.agents.defaults.subagents.defaultTimeoutSeconds`
+ * knob in `brigade.json` is honoured by the in-process `spawn_agent`
+ * path through `resolveSubagentLimits`. The two paths read different
+ * surfaces today; an operator who genuinely wants longer-running children
+ * sets BOTH.
+ */
+export declare const DEFAULT_SUBAGENT_RUN_TIMEOUT_SECONDS = 180;
+export interface SpawnSubagentParams {
+    task: string;
+    label?: string;
+    agentId?: string;
+    model?: string;
+    thinking?: string;
+    runTimeoutSeconds?: number;
+    thread?: boolean;
+    mode?: SpawnSubagentMode;
+    cleanup?: "delete" | "keep";
+    sandbox?: SpawnSubagentSandboxMode;
+    lightContext?: boolean;
+    expectsCompletionMessage?: boolean;
+}
+export interface SpawnSubagentContext {
+    agentSessionKey?: string;
+    agentChannel?: string;
+    agentAccountId?: string;
+    agentTo?: string;
+    agentThreadId?: string | number;
+    requesterAgentIdOverride?: string;
+    workspaceDir?: string;
+    /**
+     * Per-call depth cap override (defaults to 3). Pass at most the
+     * config-resolved max-spawn-depth from the gateway.
+     */
+    maxSpawnDepth?: number;
+    /** Per-call children-per-agent cap override (defaults to 5). */
+    maxChildrenPerAgent?: number;
+    /** Caller's current depth (resolved from session store; defaults to 0). */
+    callerDepth?: number;
+}
+export interface SpawnSubagentResult {
+    status: "accepted" | "forbidden" | "error";
+    childSessionKey?: string;
+    runId?: string;
+    mode?: SpawnSubagentMode;
+    note?: string;
+    error?: string;
+}
+/**
+ * Main spawn entry point. Returns a structured result so the
+ * `sessions_spawn` tool can render success / forbidden / error cleanly.
+ *
+ * The engine NEVER throws — every failure path returns
+ * `{ status: "error" | "forbidden", error }` plus optional `childSessionKey`
+ * / `runId` if the failure happened after either was minted.
+ */
+export declare function spawnSubagentDirect(params: SpawnSubagentParams, ctx: SpawnSubagentContext): Promise<SpawnSubagentResult>;
+//# sourceMappingURL=subagent-spawn.d.ts.map

package/dist/agents/subagent-spawn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-spawn.d.ts","sourceRoot":"","sources":["../../src/agents/subagent-spawn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAoBH,OAAO,KAAK,EACX,iBAAiB,EACjB,wBAAwB,EACxB,MAAM,8BAA8B,CAAC;AAMtC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,oCAAoC,MAAM,CAAC;AAExD,MAAM,WAAW,mBAAmB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,iBAAiB,CAAC;IACzB,OAAO,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC5B,OAAO,CAAC,EAAE,wBAAwB,CAAC;IACnC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACnC;AAED,MAAM,WAAW,oBAAoB;IACpC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IACnC,MAAM,EAAE,UAAU,GAAG,WAAW,GAAG,OAAO,CAAC;IAC3C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,iBAAiB,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAgED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACxC,MAAM,EAAE,mBAAmB,EAC3B,GAAG,EAAE,oBAAoB,GACvB,OAAO,CAAC,mBAAmB,CAAC,CA6O9B"}