@spinabot/brigade 0.1.2 → 1.0.1

package/dist/agents/subagent-completion-bridge.js

@@ -0,0 +1,338 @@
+/**
+ * Sub-agent completion bridge.
+ *
+ * Closes the loop that the audit caught: Step 10's `markSubagentRunCompleted`
+ * was exported but never called. Without this listener, every sub-agent
+ * spawn left a permanent in-memory registry entry until process restart —
+ * registry leak under normal usage.
+ *
+ * Wiring:
+ *
+ *   1. Subscribes to the unified agent-events bus (Step 18).
+ *   2. Watches `lifecycle` stream events with `phase: "end"`.
+ *   3. Looks up the sub-agent run by `runId` via Step 10's registry.
+ *   4. Calls `markSubagentRunCompleted({runId, outcome, reason, …})` so the
+ *      registry stamps `endedAt` + fires the (idempotent) `subagent_ended`
+ *      hook — Step 18's bridge then emits a `subagent_lifecycle` event
+ *      for downstream listeners.
+ *   5. Enqueues a completion announce into the PARENT session's inbox
+ *      (`session-inbox.ts:enqueueSystemEvent`) so the parent's next turn
+ *      sees "your sub-agent <label> completed: …" — fills the producer
+ *      gap Audit 11 flagged.
+ *
+ * Cleanly idempotent: `markSubagentRunCompleted` short-circuits when
+ * the entry already has `endedAt`, and `emitSubagentEndedHookOnce` (used
+ * inside) double-gates with `endedHookEmittedAt`. Two `phase: "end"`
+ * events for the same runId — possible during a retry storm — both
+ * resolve to a single completion stamp.
+ *
+ * Boot wiring: `installSubagentCompletionBridge()` returns a disposer.
+ * `agents/agent-events.ts:wireAgentEventsBridge()` installs this bridge
+ * alongside the sub-agent ended hook + heartbeat hook + session-state
+ * listener so all four flow from one call at gateway boot.
+ */
+import { createSubsystemLogger } from "../logging/subsystem-logger.js";
+import { resolveGlobalSingleton } from "../shared/global-singleton.js";
+import { onAgentEvent } from "./agent-events.js";
+import { requestHeartbeatNow } from "./heartbeat-wake.js";
+import { deliverSubagentCompletionAnnounce, pickReplyTextFromRegistryEntry, } from "./subagent-announce-delivery.js";
+import { getSubagentRun, markSubagentRunCompleted, } from "./subagent-registry.js";
+import { SUBAGENT_ENDED_OUTCOME_ABORT, SUBAGENT_ENDED_OUTCOME_ERROR, SUBAGENT_ENDED_OUTCOME_OK, SUBAGENT_ENDED_OUTCOME_TIMEOUT, } from "./subagent-lifecycle-events.js";
+const log = createSubsystemLogger("agents/subagent-completion-bridge");
+const BRIDGE_STATE_KEY = Symbol.for("brigade.subagentCompletionBridge.state");
+const WAKE_DEBOUNCE_MS = 25;
+function getState() {
+    return resolveGlobalSingleton(BRIDGE_STATE_KEY, () => ({
+        disposeListener: null,
+        chainsByParent: new Map(),
+        completionSeq: 0,
+        pendingWakes: new Map(),
+    }));
+}
+/**
+ * Wave O0.8 GAP 10 — schedule a synthetic heartbeat wake for the parent
+ * session, debounced so a burst of sibling completions collapses to one
+ * wake. The wake is scoped per-parent so unrelated parents don't see
+ * spurious turns. Each scheduled timer is unref'd so it never blocks
+ * process exit.
+ */
+function scheduleParentWake(parentSessionKey) {
+    const state = getState();
+    const existing = state.pendingWakes.get(parentSessionKey);
+    if (existing) {
+        // Within the debounce window — keep the existing timer; it will
+        // pick up this completion's inbox entry on fire.
+        return;
+    }
+    const timer = setTimeout(() => {
+        state.pendingWakes.delete(parentSessionKey);
+        try {
+            requestHeartbeatNow({
+                reason: "subagent-completion",
+                sessionKey: parentSessionKey,
+            });
+        }
+        catch (err) {
+            log.warn("scheduleParentWake requestHeartbeatNow threw", {
+                parentSessionKey,
+                error: err?.message,
+            });
+        }
+    }, WAKE_DEBOUNCE_MS);
+    if (typeof timer.unref === "function")
+        timer.unref();
+    state.pendingWakes.set(parentSessionKey, timer);
+}
+/**
+ * Wave O0.8 GAP 12 — append `task` to the per-parent serialization chain.
+ * Returns a promise that resolves when the task completes; failures are
+ * logged but never propagate (the chain MUST stay alive for siblings).
+ */
+function enqueueOnParentChain(parentSessionKey, task) {
+    const state = getState();
+    const previous = state.chainsByParent.get(parentSessionKey) ?? Promise.resolve();
+    const next = previous
+        .catch(() => undefined)
+        .then(() => task())
+        .catch((err) => {
+        log.warn("per-parent completion chain task threw", {
+            parentSessionKey,
+            error: err?.message,
+        });
+    })
+        .finally(() => {
+        // Garbage-collect the chain entry once it settles AND no
+        // follow-up enqueue has replaced it. Without this the Map
+        // grows linearly with the number of distinct parents over the
+        // process lifetime.
+        if (state.chainsByParent.get(parentSessionKey) === next) {
+            state.chainsByParent.delete(parentSessionKey);
+        }
+    });
+    state.chainsByParent.set(parentSessionKey, next);
+    return next;
+}
+function deriveOutcomes(data) {
+    const ok = data.ok;
+    const error = typeof data.error === "string" ? data.error : undefined;
+    const timedOut = data.timedOut === true || data.reason === "timeout";
+    const aborted = data.aborted === true || data.reason === "abort" || data.reason === "aborted";
+    // Wave O0.7 - lifecycle producers (agent-dispatcher) now thread the
+    // child's final assistant text on the `phase:"end"` payload as
+    // `reply`. The completion bridge plucks it here so the announce-
+    // delivery payload carries the actual child output to the parent.
+    const replyText = typeof data.reply === "string" ? data.reply : undefined;
+    if (aborted) {
+        return {
+            runOutcome: { status: "abort", ...(replyText ? { text: replyText } : {}) },
+            lifecycleOutcome: SUBAGENT_ENDED_OUTCOME_ABORT,
+            reason: "abort",
+            ...(error ? { error } : {}),
+            ...(replyText ? { replyText } : {}),
+        };
+    }
+    if (timedOut) {
+        return {
+            runOutcome: { status: "timeout", ...(replyText ? { text: replyText } : {}) },
+            lifecycleOutcome: SUBAGENT_ENDED_OUTCOME_TIMEOUT,
+            reason: "timeout",
+            ...(error ? { error } : {}),
+            ...(replyText ? { replyText } : {}),
+        };
+    }
+    if (ok === false || error) {
+        return {
+            runOutcome: {
+                status: "error",
+                error: error ?? "unknown error",
+                ...(replyText ? { text: replyText } : {}),
+            },
+            lifecycleOutcome: SUBAGENT_ENDED_OUTCOME_ERROR,
+            reason: "error",
+            error: error ?? "unknown error",
+            ...(replyText ? { replyText } : {}),
+        };
+    }
+    return {
+        runOutcome: { status: "ok", ...(replyText ? { text: replyText } : {}) },
+        lifecycleOutcome: SUBAGENT_ENDED_OUTCOME_OK,
+        reason: "complete",
+        ...(replyText ? { replyText } : {}),
+    };
+}
+// Wave O0.7 - the rich announce text now lives in
+// `subagent-announce-delivery.ts`; the bridge just passes the entry and
+// the lifecycle outcome through. Keep the legacy short-form helper
+// available for callers that only want the headline (e.g. log lines).
+function formatLegacyAnnounceHeadline(params) {
+    const tag = params.label?.trim() ? ` "${params.label.trim()}"` : "";
+    if (params.outcome === SUBAGENT_ENDED_OUTCOME_OK) {
+        return `Sub-agent${tag} completed successfully.`;
+    }
+    if (params.outcome === SUBAGENT_ENDED_OUTCOME_TIMEOUT) {
+        return `Sub-agent${tag} timed out.`;
+    }
+    if (params.outcome === SUBAGENT_ENDED_OUTCOME_ABORT) {
+        return `Sub-agent${tag} was aborted.`;
+    }
+    const detail = params.error?.trim() ? `: ${params.error.trim()}` : "";
+    return `Sub-agent${tag} failed${detail}`;
+}
+// Local alias kept so the inbox-fallback branch below (Wave O0.7) can
+// fall back to the short-form when `enqueueSystemEvent` is bypassed.
+const formatAnnounceText = formatLegacyAnnounceHeadline;
+/**
+ * Install the bridge. Returns a disposer that unsubscribes from the
+ * agent-events bus. Idempotent — re-installing replaces the previous
+ * listener.
+ */
+export function installSubagentCompletionBridge() {
+    const state = getState();
+    if (state.disposeListener) {
+        state.disposeListener();
+        state.disposeListener = null;
+    }
+    const dispose = onAgentEvent((event) => {
+        if (event.stream !== "lifecycle")
+            return;
+        const data = event.data ?? {};
+        if (data.phase !== "end")
+            return;
+        const runId = event.runId?.trim();
+        if (!runId)
+            return;
+        const entry = getSubagentRun(runId);
+        if (!entry)
+            return;
+        // Already stamped — Step 10's `markSubagentRunCompleted` is
+        // idempotent, but skipping the call avoids needless work + log noise.
+        if (entry.endedAt)
+            return;
+        const { runOutcome, lifecycleOutcome, error, reason, replyText } = deriveOutcomes(data);
+        // Wave O0.8 GAP 12 — tag this completion with a monotonic sequence
+        // number at the moment the lifecycle event was OBSERVED, not when
+        // the async delivery runs. Two siblings finishing in the same
+        // microtask thereby preserve their event-arrival order regardless
+        // of microtask scheduler quirks.
+        const bridgeState = getState();
+        bridgeState.completionSeq += 1;
+        const completionSeqAtEmit = bridgeState.completionSeq;
+        const parentSessionKey = entry.requesterSessionKey?.trim() || entry.controllerSessionKey?.trim();
+        const deliveryTask = async () => {
+            try {
+                await markSubagentRunCompleted({
+                    runId,
+                    outcome: runOutcome,
+                    reason,
+                    lifecycleOutcome,
+                    ...(error ? { error } : {}),
+                });
+            }
+            catch (err) {
+                log.warn("markSubagentRunCompleted threw", {
+                    runId,
+                    error: err?.message,
+                });
+            }
+            // Wave O0.7 - announce-delivery into the parent's session inbox so
+            // the parent's next turn sees "child X finished, here is the
+            // reply". The dedicated module formats the rich message body
+            // (status + duration + truncated reply) and gates the enqueue
+            // idempotently on `subagent:ended:<runId>`.
+            if (!parentSessionKey || parentSessionKey === "main") {
+                // Parent is the operator's main session or unknown - the TUI
+                // sees lifecycle events directly via Step 18's agent-events
+                // stream, no inbox needed.
+                return;
+            }
+            try {
+                // Prefer the reply text carried on the lifecycle event, else
+                // pull whatever the registry already captured for the run.
+                const fallbackReply = replyText ?? pickReplyTextFromRegistryEntry(entry);
+                const durationMs = typeof entry.createdAt === "number"
+                    ? Math.max(0, Date.now() - entry.createdAt)
+                    : undefined;
+                const enqueued = deliverSubagentCompletionAnnounce({
+                    parentSessionKey,
+                    childSessionKey: entry.childSessionKey,
+                    runId,
+                    outcome: lifecycleOutcome,
+                    completionSeq: completionSeqAtEmit,
+                    ...(entry.label ? { label: entry.label } : {}),
+                    ...(error ? { error } : {}),
+                    ...(fallbackReply ? { replyText: fallbackReply } : {}),
+                    ...(durationMs !== undefined ? { durationMs } : {}),
+                });
+                if (!enqueued) {
+                    // Fall back to the short-form text if the rich announce
+                    // was deduped or the inbox dropped it. The headline is
+                    // still useful for observability.
+                    const text = formatAnnounceText({
+                        label: entry.label,
+                        outcome: lifecycleOutcome,
+                        error,
+                    });
+                    log.debug("subagent announce inbox enqueue dropped; headline only", {
+                        runId,
+                        parentSessionKey,
+                        text,
+                    });
+                }
+                // Wave O0.8 GAP 10 — fire a synthetic heartbeat wake for the
+                // parent IF the registry entry opted in. Debounced per-parent
+                // so a burst of sibling completions collapses to one wake.
+                if (entry.wakeOnDescendantSettle && enqueued) {
+                    scheduleParentWake(parentSessionKey);
+                }
+            }
+            catch (err) {
+                log.warn("subagent completion announce enqueue failed", {
+                    runId,
+                    parentSessionKey,
+                    error: err?.message,
+                });
+            }
+        };
+        // Wave O0.8 GAP 12 — route through the per-parent serialization
+        // chain when a parentSessionKey is present. Two siblings finishing
+        // in the same tick thereby land in the inbox in the order their
+        // lifecycle events arrived. When parent is "main" / undefined, we
+        // fall back to a plain `void` wrapper (the inbox path is skipped
+        // inside `deliveryTask` anyway).
+        if (parentSessionKey && parentSessionKey !== "main") {
+            void enqueueOnParentChain(parentSessionKey, deliveryTask);
+        }
+        else {
+            void deliveryTask();
+        }
+    });
+    state.disposeListener = dispose;
+    return () => {
+        const current = getState();
+        if (current.disposeListener === dispose) {
+            dispose();
+            current.disposeListener = null;
+        }
+        else {
+            dispose();
+        }
+    };
+}
+/** Test-only — clear bridge state. */
+export function resetSubagentCompletionBridgeForTests() {
+    const state = getState();
+    if (state.disposeListener) {
+        state.disposeListener();
+        state.disposeListener = null;
+    }
+    // Wave O0.8 GAP 12 — clear per-parent serialization chains + seq counter
+    // + pending wake timers so a test's bridge wiring is independent of any
+    // prior test's leftover state.
+    state.chainsByParent.clear();
+    state.completionSeq = 0;
+    for (const timer of state.pendingWakes.values()) {
+        clearTimeout(timer);
+    }
+    state.pendingWakes.clear();
+}
+//# sourceMappingURL=subagent-completion-bridge.js.map

package/dist/agents/subagent-completion-bridge.js.map

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

package/dist/agents/subagent-lifecycle-events.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Sub-agent lifecycle event constants.
+ *
+ * Brand-scrubbed lift of upstream's `src/agents/subagent-lifecycle-events.ts`,
+ * trimmed to the literals the registry + completion helpers need today.
+ * Step 18 (agent events + gateway-call factory) wires these to an actual
+ * emitter; today they exist so the registry's types are concrete.
+ */
+export declare const SUBAGENT_ENDED_OUTCOME_OK: "ok";
+export declare const SUBAGENT_ENDED_OUTCOME_ERROR: "error";
+export declare const SUBAGENT_ENDED_OUTCOME_TIMEOUT: "timeout";
+/**
+ * Wave O0.7 - `abort` outcome distinguishes a parent-cancelled child from
+ * the generic "error" bucket. Used by the parent-abort cascade so the
+ * announce-delivery's completion text can render "was aborted" instead of
+ * the misleading "failed".
+ */
+export declare const SUBAGENT_ENDED_OUTCOME_ABORT: "abort";
+export type SubagentLifecycleEndedOutcome = typeof SUBAGENT_ENDED_OUTCOME_OK | typeof SUBAGENT_ENDED_OUTCOME_ERROR | typeof SUBAGENT_ENDED_OUTCOME_TIMEOUT | typeof SUBAGENT_ENDED_OUTCOME_ABORT;
+export declare const SUBAGENT_TARGET_KIND_SUBAGENT: "subagent";
+export declare const SUBAGENT_TARGET_KIND_ACP: "acp";
+export type SubagentTargetKind = typeof SUBAGENT_TARGET_KIND_SUBAGENT | typeof SUBAGENT_TARGET_KIND_ACP;
+/**
+ * Reason a sub-agent run ended. Free-form on purpose — the catalogue
+ * grows as new entry-points are added (e.g. cron timeouts, manual kills,
+ * upstream provider 5xx exhaustion). Restricting the union early would
+ * just force a churn cascade across the lifecycle emitter when a new
+ * source comes online.
+ */
+export type SubagentLifecycleEndedReason = string;
+//# sourceMappingURL=subagent-lifecycle-events.d.ts.map

package/dist/agents/subagent-lifecycle-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-lifecycle-events.d.ts","sourceRoot":"","sources":["../../src/agents/subagent-lifecycle-events.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,eAAO,MAAM,yBAAyB,EAAG,IAAa,CAAC;AACvD,eAAO,MAAM,4BAA4B,EAAG,OAAgB,CAAC;AAC7D,eAAO,MAAM,8BAA8B,EAAG,SAAkB,CAAC;AACjE;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,EAAG,OAAgB,CAAC;AAE7D,MAAM,MAAM,6BAA6B,GACtC,OAAO,yBAAyB,GAChC,OAAO,4BAA4B,GACnC,OAAO,8BAA8B,GACrC,OAAO,4BAA4B,CAAC;AAEvC,eAAO,MAAM,6BAA6B,EAAG,UAAmB,CAAC;AACjE,eAAO,MAAM,wBAAwB,EAAG,KAAc,CAAC;AAEvD,MAAM,MAAM,kBAAkB,GAC3B,OAAO,6BAA6B,GACpC,OAAO,wBAAwB,CAAC;AAEnC;;;;;;GAMG;AACH,MAAM,MAAM,4BAA4B,GAAG,MAAM,CAAC"}

package/dist/agents/subagent-lifecycle-events.js

@@ -0,0 +1,21 @@
+/**
+ * Sub-agent lifecycle event constants.
+ *
+ * Brand-scrubbed lift of upstream's `src/agents/subagent-lifecycle-events.ts`,
+ * trimmed to the literals the registry + completion helpers need today.
+ * Step 18 (agent events + gateway-call factory) wires these to an actual
+ * emitter; today they exist so the registry's types are concrete.
+ */
+export const SUBAGENT_ENDED_OUTCOME_OK = "ok";
+export const SUBAGENT_ENDED_OUTCOME_ERROR = "error";
+export const SUBAGENT_ENDED_OUTCOME_TIMEOUT = "timeout";
+/**
+ * Wave O0.7 - `abort` outcome distinguishes a parent-cancelled child from
+ * the generic "error" bucket. Used by the parent-abort cascade so the
+ * announce-delivery's completion text can render "was aborted" instead of
+ * the misleading "failed".
+ */
+export const SUBAGENT_ENDED_OUTCOME_ABORT = "abort";
+export const SUBAGENT_TARGET_KIND_SUBAGENT = "subagent";
+export const SUBAGENT_TARGET_KIND_ACP = "acp";
+//# sourceMappingURL=subagent-lifecycle-events.js.map

package/dist/agents/subagent-lifecycle-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-lifecycle-events.js","sourceRoot":"","sources":["../../src/agents/subagent-lifecycle-events.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,CAAC,MAAM,yBAAyB,GAAG,IAAa,CAAC;AACvD,MAAM,CAAC,MAAM,4BAA4B,GAAG,OAAgB,CAAC;AAC7D,MAAM,CAAC,MAAM,8BAA8B,GAAG,SAAkB,CAAC;AACjE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,OAAgB,CAAC;AAQ7D,MAAM,CAAC,MAAM,6BAA6B,GAAG,UAAmB,CAAC;AACjE,MAAM,CAAC,MAAM,wBAAwB,GAAG,KAAc,CAAC"}

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

@@ -0,0 +1,206 @@
+/**
+ * Sub-agent runtime policy + run registry — Primitive #6.
+ *
+ * Three concerns live here:
+ *
+ *   1. **Depth detection from the session key.** We encode "this session IS a
+ *      sub-agent" in the key shape itself — `agent:<id>:subagent:<uuid>`.
+ *      Counting the `":subagent:"` markers in the key tells us the depth
+ *      without a process-global Map that could leak across crashes / restarts.
+ *      Top-level sessions (`agent:<id>:main`) have depth 0; a first-level
+ *      child has depth 1; a grandchild would have depth 2 (but the runner
+ *      refuses to spawn one because the leaf-filter drops `spawn_agent`
+ *      from the child's tools).
+ *
+ *   2. **Run registry with lifecycle timings + outcomes.** A process-scoped
+ *      Map keyed by parent session key tracks every child run with
+ *      createdAt / startedAt / endedAt / outcome / error / label / cleanup
+ *      policy — not just "is this child active?". Lets the gateway answer
+ *      "what's running right now?" and "what was the last child's outcome?"
+ *      without spelunking through transcript files. Persisted to disk is a
+ *      v2 concern; in-memory is enough for the single-user / single-process
+ *      v1 footprint.
+ *
+ *   3. **Race-safe slot reservation.** Two concurrent `spawn_agent` calls
+ *      from the same parent must NOT both pass the limit check and then
+ *      both register, blowing past `maxChildrenPerParent`. `reserveSubagentSlot`
+ *      does the count check and the registration in one synchronous step,
+ *      closing the TOCTOU window that an "assert then register" pair leaves
+ *      open. The reserved slot starts in `"reserved"` state and transitions
+ *      to `"running"` once the child's run actually begins.
+ *
+ * Limits resolve from config (`agents.defaults.subagents`) with hardcoded
+ * defaults (max depth 1, max children per parent 5, default timeout 300s).
+ * All three are individually overridable.
+ *
+ * `SubagentLimitError` is a typed exception the spawn tool catches and
+ * converts to a tool-result with `status: "limit-refused"` so the model
+ * sees a clear refusal it can self-correct from, instead of an opaque throw.
+ */
+import type { BrigadeConfig } from "../config/io.js";
+import type { AnyBrigadeTool } from "./tools/types.js";
+/**
+ * Default max sub-agent depth. depth 0 = top-level operator turn; depth 1 = first
+ * sub-agent layer; depth 2 = grandchild; etc. Worst-case parallelism is bounded
+ * by `maxChildrenPerParent ^ maxDepth` — at default `(5, 3)` that's 125 leaf
+ * agents which is plenty for "dispatcher → coordinator → worker" patterns
+ * without recursion runaway. Operators can lift via
+ * `cfg.agents.defaults.subagents.maxDepth` or the boot env `BRIGADE_SUBAGENT_MAX_DEPTH`.
+ */
+export declare const DEFAULT_SUBAGENT_MAX_DEPTH = 3;
+export declare const DEFAULT_SUBAGENT_MAX_CHILDREN_PER_PARENT = 5;
+export declare const DEFAULT_SUBAGENT_TIMEOUT_SECONDS = 300;
+/**
+ * Default cleanup policy when neither the operator nor a per-call override
+ * supplies one. `"keep"` is the safe default: the operator never loses a
+ * child's transcript without explicitly opting in.
+ *
+ * The model NEVER sees this — `cleanup` is not in the `spawn_agent` tool
+ * schema. Only operator config can change it.
+ */
+export declare const DEFAULT_SUBAGENT_CLEANUP: "delete" | "keep";
+export interface SubagentLimits {
+    maxDepth: number;
+    maxChildrenPerParent: number;
+    defaultTimeoutSeconds: number;
+    /**
+     * Operator-pinned cleanup policy. The model can NOT override this —
+     * `cleanup` is intentionally absent from the `spawn_agent` tool schema
+     * so the model can never autonomously delete a child's transcript
+     * (a real bug we hit when a model interpreted a descriptive hint as
+     * permission to opt in to delete-mode). Operators who genuinely want
+     * transient sub-agents set `agents.defaults.subagents.cleanup: "delete"`
+     * in `brigade.json`.
+     */
+    defaultCleanup: "delete" | "keep";
+}
+/**
+ * Read the `agents.defaults.subagents` block from brigade.json, fall back to
+ * the hardcoded defaults for any missing or invalid field. Always returns a
+ * fully-populated struct so the caller never has to null-check.
+ */
+export declare function resolveSubagentLimits(config: BrigadeConfig | undefined): SubagentLimits;
+/**
+ * True if the session key indicates a sub-agent session. Used by the system-
+ * prompt assembler (to switch to minimal mode) and the registry (to drop the
+ * `spawn_agent` tool at leaf depth).
+ */
+export declare function isSubagentSessionKey(sessionKey: string | undefined): boolean;
+/**
+ * Count the `:subagent:` markers in the key to get the depth. Top-level
+ * sessions return 0; nested sub-agents would return ≥ 1.
+ */
+export declare function getSubagentDepthFromSessionKey(sessionKey: string | undefined): number;
+/**
+ * Derive a child session key from the parent's. Same algorithm regardless of
+ * whether the parent is itself a sub-agent — we always append `":subagent:"`
+ * plus a fresh uuid. Depth is then `parentDepth + 1` (which the leaf-filter
+ * rejects beyond `maxDepth`, so a grandchild key is never actually built).
+ */
+export declare function buildChildSessionKey(parentSessionKey: string, uuid: string): string;
+/** Lifecycle states a child run moves through. */
+export type ChildRunState = "reserved" | "running" | "ended";
+/** Outcome the parent's spawn tool surfaces in the tool result. */
+export type ChildRunOutcome = "ok" | "aborted" | "timed-out" | "error";
+/**
+ * Everything we know about a single sub-agent run. Lifetime: created by
+ * `reserveSubagentSlot()`, mutated by `markSubagentRunStarted()` /
+ * `releaseSubagentSlot()`, removed from the active map once `releaseSubagentSlot`
+ * fires. Snapshots remain queryable via `listRecentlyCompletedChildren()`
+ * for a bounded ring of recent results.
+ */
+export interface ChildRunRecord {
+    parentSessionKey: string;
+    childSessionKey: string;
+    parentRunId?: string;
+    label: string;
+    /** Caller's depth at spawn time. Child's own depth = callerDepth + 1. */
+    callerDepth: number;
+    /** "delete" → transcript file removed after settle. "keep" → preserved. */
+    cleanup: "delete" | "keep";
+    state: ChildRunState;
+    /** ms-epoch — set when slot is reserved (before run starts). */
+    createdAt: number;
+    /** ms-epoch — set when `markSubagentRunStarted` fires (Pi run begun). */
+    startedAt?: number;
+    /** ms-epoch — set when `releaseSubagentSlot` fires (settle, abort, timeout, error). */
+    endedAt?: number;
+    outcome?: ChildRunOutcome;
+    /** Set when outcome is "error" (unexpected throw). Otherwise undefined. */
+    error?: string;
+}
+export declare class SubagentLimitError extends Error {
+    readonly kind: "depth" | "concurrent" | "parent-aborted";
+    constructor(message: string, kind: "depth" | "concurrent" | "parent-aborted");
+}
+export interface ReserveSubagentSlotArgs {
+    parentSessionKey: string;
+    childSessionKey: string;
+    parentRunId?: string;
+    label: string;
+    callerDepth: number;
+    limits: SubagentLimits;
+    cleanup: "delete" | "keep";
+}
+/**
+ * Atomically validate limits + register the child. This is the ONLY entry
+ * point — callers must not pre-check via `countActiveChildren()` and then
+ * register later (that's the TOCTOU window we close here). Throws
+ * `SubagentLimitError` if depth or concurrency caps would be exceeded;
+ * returns the freshly-registered `ChildRunRecord` otherwise.
+ *
+ * The function is fully synchronous: Node's single-threaded event loop
+ * gives us the atomicity we need — no two `reserveSubagentSlot` calls
+ * can interleave once the function is entered.
+ */
+export declare function reserveSubagentSlot(args: ReserveSubagentSlotArgs): ChildRunRecord;
+/**
+ * Transition a reserved slot to `"running"` and stamp `startedAt`. Called
+ * by the runner immediately before delegating to `runSingleTurn`. Safe to
+ * call once per slot; subsequent calls are no-ops (so a retry that re-enters
+ * the runner doesn't double-stamp the timing).
+ */
+export declare function markSubagentRunStarted(parentSessionKey: string, childSessionKey: string): void;
+/**
+ * Release the slot + record the outcome. Moves the record into
+ * `recentlyEnded` (capped ring) so listings can still surface it briefly.
+ * Idempotent — calling twice for the same slot is a no-op so the runner's
+ * `finally` block can fire safely even when the catch block already
+ * settled the record.
+ */
+export declare function releaseSubagentSlot(args: {
+    parentSessionKey: string;
+    childSessionKey: string;
+    outcome: ChildRunOutcome;
+    error?: string;
+}): ChildRunRecord | undefined;
+/** Count children in `"reserved"` or `"running"` state for a parent. */
+export declare function countActiveChildren(parentSessionKey: string): number;
+/** Snapshot of every active child run for a parent (cloned — safe to mutate). */
+export declare function listActiveChildren(parentSessionKey: string): ChildRunRecord[];
+/** Single-record lookup. Returns undefined if the slot has already ended. */
+export declare function getChildRunRecord(parentSessionKey: string, childSessionKey: string): ChildRunRecord | undefined;
+/** Last N ended records (oldest first). Cloned. */
+export declare function listRecentlyEndedChildren(): ChildRunRecord[];
+/**
+ * Drop `spawn_agent` from a tool list when the CALLER's depth would already
+ * make `reserveSubagentSlot` refuse — the rule is `callerDepth >= maxDepth
+ * → refuse` — so the tool surface never offers a tool that can't legally be
+ * called. With the default `maxDepth = 1`:
+ *
+ *   callerDepth = 0 (top-level operator turn) → spawn_agent registered
+ *   callerDepth = 1 (running INSIDE a sub-agent) → spawn_agent dropped
+ *
+ * With `maxDepth = 2`, depth-1 sub-agents keep the tool and can spawn one more
+ * level deep; only depth-2 grandchildren see it dropped. Recursion is bounded
+ * by depth rather than by any process-global state.
+ */
+export declare function filterToolsForSubagentDepth(args: {
+    tools: AnyBrigadeTool[];
+    /** Depth of the session that would CALL `spawn_agent` / `spawn_agents`. */
+    callerDepth: number;
+    maxDepth: number;
+}): AnyBrigadeTool[];
+/** Test-only hook: clear the active-children registry + recent history between cases. */
+export declare function clearSubagentRegistryForTests(): void;
+//# sourceMappingURL=subagent-policy.d.ts.map

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

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