aec-agent 1.0.1 → 1.0.4

package/dist/components/multi-agent-orchestration/agent/subagent-manager/subagent-manager.js

@@ -0,0 +1,661 @@
+import { randomUUID } from "node:crypto";
+import { SubagentError } from "../../../../kernel/errors/subagent-error.js";
+import { SDKEventType } from "../../../event-handler/events.js";
+import { Semaphore } from "./semaphore.js";
+import { runTypeTurn } from "./child-loop.js";
+import { buildBrief, childToolScope, describeResult, safeError, sanitizeChildOutput, validateRequest } from "./brief.js";
+import { isSubagentSession, resolveSubagentConfig, } from "./types.js";
+const ZERO_USAGE = { inputTokens: 0, outputTokens: 0 };
+/**
+ * SubagentManager (A-105) — owns everything about subagents for one agent:
+ *
+ *  - as a PARENT: spawn() validates the brief and target, takes a slot of the turn's
+ *    semaphore, creates the child's session, runs the child turn through the host's runner
+ *    (or the child's chat()), enforces the turn's shared budget and the child's deadline,
+ *    and records the run (PersistenceHub.subagentRuns) and its lifecycle events;
+ *    Design revision: the target is a subagent TYPE (a short-lived loop inside this agent,
+ *    child-loop.ts, in a side-branch session of this agent) or an existing AGENT;
+ *  - as a CHILD (subagentSide): knows which of its sessions are child runs, routes their
+ *    approvals to the parent's channel to the user, refuses their questions, scopes their
+ *    tools (read-only by default) and holds the single writer slot.
+ *
+ * It hears the child's model responses, tool calls and max-iterations events on the bus to
+ * account tokens and tool calls while the child runs.
+ */
+export class SubagentManager {
+    deps;
+    budgets = new Map();
+    active = new Map();
+    byChildSession = new Map();
+    unsubscribes = [];
+    disposed = false;
+    // Child side: this agent's sessions that are someone's child runs.
+    bindings = new Map();
+    writerRunId;
+    /** The child-side half, used by the parent's SubagentManager through SubagentTarget.subagentSide. */
+    subagentSide = {
+        bind: (sessionId, binding) => {
+            this.bindings.set(sessionId, binding);
+        },
+        unbind: (sessionId) => {
+            this.bindings.delete(sessionId);
+        },
+        tryAcquireWriter: (runId) => {
+            if (this.writerRunId && this.writerRunId !== runId)
+                return false;
+            this.writerRunId = runId;
+            return true;
+        },
+        releaseWriter: (runId) => {
+            if (this.writerRunId === runId)
+                this.writerRunId = undefined;
+        },
+    };
+    constructor(deps) {
+        this.deps = deps;
+        const bus = deps.eventBus;
+        this.unsubscribes.push(bus.on(SDKEventType.ModelResponded, (e) => {
+            const run = this.byChildSession.get(e.sessionId);
+            if (run && e.payload.usage)
+                this.addUsage(run, e.payload.usage);
+        }), bus.on(SDKEventType.ToolDispatched, (e) => {
+            const run = this.byChildSession.get(e.sessionId);
+            if (!run)
+                return;
+            run.run.toolCalls++;
+            run.budget.toolCalls++;
+            this.enforceBudget(run.budget);
+        }), bus.on(SDKEventType.MaxIterationsReached, (e) => {
+            const run = this.byChildSession.get(e.sessionId);
+            if (run)
+                run.maxIterations = true;
+        }), 
+        // A parent turn ended: its children are done (spawn waits for them), so its budget goes.
+        bus.on(SDKEventType.RunCompleted, (e) => {
+            if (e.payload.agentId === deps.agentId)
+                this.dropIdleBudgets(e.sessionId);
+        }));
+    }
+    // ---------------------------------------------------------------------------
+    // Parent side
+    // ---------------------------------------------------------------------------
+    get running() {
+        return this.active.size;
+    }
+    async targets(sessionId) {
+        const config = this.configFor(sessionId ? this.deps.getScope?.(sessionId) : undefined);
+        const out = [];
+        const hub = this.deps.getHub();
+        if (hub) {
+            for (const name of config.types) {
+                const type = await hub.get(name).catch(() => undefined);
+                if (type)
+                    out.push({ kind: "type", agentId: type.name, name: type.name, access: type.access, description: type.description });
+            }
+        }
+        const host = this.deps.getHost();
+        if (host) {
+            for (const target of config.allow) {
+                const agent = host.get(target.agentId);
+                if (!agent || agent.profile.id === this.deps.agentId)
+                    continue;
+                out.push({ kind: "agent", agentId: agent.profile.id, name: agent.profile.name, access: target.access, description: firstLine(agent.profile.systemPrompt) });
+            }
+        }
+        return out;
+    }
+    async list(parentSessionId) {
+        const runs = await this.deps.getStore().listByParentSession(parentSessionId);
+        return runs.filter((r) => r.parentAgentId === this.deps.agentId).map((r) => this.live(r));
+    }
+    async get(runId) {
+        const run = await this.deps.getStore().get(runId);
+        return run && run.parentAgentId === this.deps.agentId ? this.live(run) : null;
+    }
+    stop(runId) {
+        const run = this.active.get(runId);
+        if (!run)
+            return false;
+        this.abort(run, "cancelled");
+        return true;
+    }
+    async spawn(request, context) {
+        if (this.disposed)
+            throw new SubagentError("this agent is shutting down", "not_found");
+        // A-106: a scoped session (a group lead) delegates by its scope, not the profile's config.
+        const scope = this.deps.getScope?.(context.sessionId);
+        const config = this.configFor(scope);
+        await this.refuseNested(context.sessionId);
+        const brief = validateRequest(request);
+        const target = await this.resolveTarget(brief.agentId, config, context.sessionId);
+        const { access } = target;
+        // A type works in this agent's sandbox; an agent in its own.
+        const writerSide = target.kind === "type" ? this.subagentSide : target.agent.subagentSide;
+        const run = {
+            id: randomUUID(),
+            kind: target.kind,
+            parentAgentId: this.deps.agentId,
+            parentSessionId: context.sessionId,
+            parentRunId: context.runId ?? `session:${context.sessionId}`,
+            ...(context.toolCallId ? { parentToolCallId: context.toolCallId } : {}),
+            childAgentId: target.kind === "type" ? this.deps.agentId : target.agent.profile.id,
+            childAgentName: target.name,
+            access,
+            task: brief.task,
+            status: "running",
+            usage: { ...ZERO_USAGE },
+            toolCalls: 0,
+            startedAt: new Date().toISOString(),
+        };
+        // One writer per sandbox: refused now, before anything is queued or recorded.
+        if (access === "write" && !writerSide.tryAcquireWriter(run.id)) {
+            throw new SubagentError(target.kind === "type"
+                ? "a write-capable subagent is already working in your sandbox; wait for it, or delegate read-only work"
+                : `"${target.name}" is already running a write-capable task; wait for it, or delegate read-only work`, "write_unavailable");
+        }
+        try {
+            const budget = this.budgetFor(run.parentRunId, context.sessionId, config);
+            const refused = this.budgetRefusal(budget, config);
+            if (refused)
+                return await this.finishUnstarted(run, "budget_exhausted", refused);
+            budget.launched++;
+            budget.touchedAt = Date.now();
+            const slot = await budget.semaphore.acquire(context.signal);
+            if (!slot)
+                return await this.finishUnstarted(run, "cancelled", "the parent turn was stopped before the subagent started");
+            try {
+                const late = this.budgetRefusal(budget, config, true);
+                if (late)
+                    return await this.finishUnstarted(run, "budget_exhausted", late);
+                return await this.runChild(run, target, brief, context, budget, config, scope);
+            }
+            finally {
+                slot.release();
+            }
+        }
+        finally {
+            if (access === "write")
+                writerSide.releaseWriter(run.id);
+        }
+    }
+    /** A-106: the session's grants — spawn_subagent for a scoped session that asks for it. */
+    grantedTools(sessionId) {
+        return this.deps.getScope?.(sessionId)?.grantSpawnTool ? ["spawn_subagent"] : [];
+    }
+    /** A-106: spawn_subagent runs without asking in a scoped session that the user set up for it. */
+    preApproved(sessionId, toolName) {
+        return toolName === "spawn_subagent" && this.deps.getScope?.(sessionId)?.preApproved === true;
+    }
+    /** The profile's config, or (A-106) the scope's targets and limits over it. */
+    configFor(scope) {
+        const own = this.deps.getProfile().subagents;
+        if (!scope)
+            return resolveSubagentConfig(own);
+        return resolveSubagentConfig({ ...own, ...scope.limits, allow: scope.allow, types: [] });
+    }
+    /** Stop every running child and stop listening. Runs in progress record themselves as cancelled. */
+    dispose() {
+        this.disposed = true;
+        for (const run of this.active.values())
+            this.abort(run, "cancelled");
+        for (const off of this.unsubscribes)
+            off();
+        this.unsubscribes = [];
+    }
+    async runChild(run, target, brief, context, budget, config, scope) {
+        const parent = { runId: run.parentRunId, agentId: this.deps.agentId, sessionId: context.sessionId, subagentRunId: run.id };
+        const metadata = {
+            agentId: run.childAgentId,
+            source: "subagent",
+            kind: target.kind,
+            parentRunId: parent.runId,
+            parentSessionId: parent.sessionId,
+            parentAgentId: parent.agentId,
+            subagentRunId: run.id,
+            title: `${target.name}: ${firstLine(brief.task, 60)}`,
+        };
+        // A-106: a scope may name the child's session (a group member's own session in the group).
+        let session;
+        try {
+            session =
+                scope?.childSession && target.kind === "agent"
+                    ? { id: await scope.childSession(target.agent.profile.id) }
+                    : await this.deps.getSessions().create({ ...metadata });
+        }
+        catch (err) {
+            return this.finishUnstarted(run, "failed", `could not create the subagent's session: ${errorMessage(err)}`);
+        }
+        run.childSessionId = session.id;
+        const active = { run, controller: new AbortController(), budget, maxIterations: false };
+        this.active.set(run.id, active);
+        this.byChildSession.set(session.id, active);
+        budget.active.add(active);
+        budget.firstStartAt ??= Date.now();
+        budget.touchedAt = Date.now();
+        // The child's channel to the user: approvals go to the parent's session.
+        const interaction = this.childInteraction(context.interaction ?? this.deps.interactionFor(context.sessionId), target.name, run.childAgentId, parent);
+        // An agent child learns which of its sessions is a child run (approvals, tool scope); a
+        // type's loop is built with both, so nothing needs binding.
+        if (target.kind === "agent")
+            target.agent.subagentSide.bind(session.id, { parent, access: run.access, interaction });
+        await this.save(run);
+        this.deps.eventBus.emit({
+            type: SDKEventType.SubagentSpawned,
+            sessionId: context.sessionId,
+            payload: {
+                agentId: this.deps.agentId,
+                runId: run.id,
+                parentRunId: run.parentRunId,
+                ...(run.parentToolCallId ? { parentToolCallId: run.parentToolCallId } : {}),
+                childAgentId: run.childAgentId,
+                childSessionId: session.id,
+                access: run.access,
+            },
+        });
+        // The parent turn's stop, the child's deadline (never past the turn's elapsed budget)
+        // and stop(runId) all abort the child's signal.
+        const onParentAbort = () => this.abort(active, "cancelled");
+        if (context.signal?.aborted)
+            onParentAbort();
+        context.signal?.addEventListener("abort", onParentAbort, { once: true });
+        const remaining = budget.firstStartAt + config.maxElapsedMsPerTurn - Date.now();
+        const deadlineMs = Math.max(0, Math.min(config.childTimeoutMs, remaining));
+        const reasonAtDeadline = config.childTimeoutMs <= remaining ? "timeout" : "budget";
+        const timer = setTimeout(() => this.abort(active, reasonAtDeadline), deadlineMs);
+        let result;
+        let failure;
+        try {
+            const prompt = scope?.brief
+                ? await scope.brief(brief, { agentId: run.childAgentId, name: target.name, runId: run.id })
+                : buildBrief(brief, this.deps.getProfile().name, run.access);
+            const traceAttributes = {
+                source: "subagent",
+                subagentKind: target.kind,
+                ...(target.kind === "type" ? { subagentType: target.name } : {}),
+                parentAgentId: parent.agentId,
+                parentSessionId: parent.sessionId,
+                parentRunId: parent.runId,
+                subagentRunId: run.id,
+                ...(run.parentToolCallId ? { parentToolCallId: run.parentToolCallId } : {}),
+            };
+            const sessionId = session.id;
+            const turn = {
+                kind: target.kind,
+                agentId: run.childAgentId,
+                childAgentName: target.name,
+                sessionId,
+                prompt,
+                task: brief.task,
+                signal: active.controller.signal,
+                parent,
+                traceAttributes,
+                execute: (signal) => target.kind === "type"
+                    ? runTypeTurn(this.deps.childLoop, this.deps.getProfile(), target.type, { sessionId, parentSessionId: parent.sessionId, prompt, signal, traceAttributes, interaction })
+                    : chatTurn(target.agent, { sessionId, prompt, signal, traceAttributes }),
+            };
+            result = await (scope?.runner ?? this.deps.getRunner() ?? this.defaultRunner)(turn);
+        }
+        catch (err) {
+            failure = err;
+        }
+        finally {
+            clearTimeout(timer);
+            context.signal?.removeEventListener("abort", onParentAbort);
+            if (target.kind === "agent")
+                target.agent.subagentSide.unbind(session.id);
+            this.active.delete(run.id);
+            this.byChildSession.delete(session.id);
+            budget.active.delete(active);
+            budget.touchedAt = Date.now();
+        }
+        // Tokens: the result's total wins when the events missed some (a streamed turn reports none).
+        if (result) {
+            const reported = result.usage.inputTokens + result.usage.outputTokens;
+            const counted = run.usage.inputTokens + run.usage.outputTokens;
+            if (reported > counted) {
+                budget.tokens += reported - counted;
+                run.usage = { ...result.usage };
+            }
+        }
+        const status = this.statusOf(active, context, result, failure);
+        let output = status === "completed" ? (result?.output ?? "") : "";
+        if (status !== "completed" && status !== "cancelled")
+            output = await this.lastReport(session.id);
+        const error = status === "completed"
+            ? undefined
+            : status === "failed"
+                ? safeError(failure !== undefined ? `the subagent's run failed: ${errorMessage(failure)}` : "the model stopped the subagent's reply (refusal or content filter)")
+                : status === "partial"
+                    ? active.maxIterations
+                        ? "the subagent reached its turn limit (maxIterations)"
+                        : "the subagent's reply hit the output token limit"
+                    : status === "timed_out"
+                        ? `the subagent did not finish within ${Math.round(config.childTimeoutMs / 1000)}s`
+                        : status === "budget_exhausted"
+                            ? "the subagent budget of this turn ran out"
+                            : "the subagent was stopped";
+        return this.finish(run, status, output, error);
+    }
+    /** Default runner (no host runner): the turn itself — the child agent's chat(), or the type's loop. */
+    defaultRunner = (turn) => turn.execute(turn.signal);
+    statusOf(active, context, result, failure) {
+        // A turn that ended on its own keeps its outcome, even when a stop came in as it finished
+        // (its last response crossed the budget, the deadline fired during the final save).
+        const endedOnItsOwn = failure === undefined && result !== undefined && !result.aborted;
+        if (!endedOnItsOwn) {
+            if (active.reason === "budget")
+                return "budget_exhausted";
+            if (active.reason === "timeout")
+                return "timed_out";
+            if (active.reason === "cancelled" || context.signal?.aborted)
+                return "cancelled";
+        }
+        if (failure !== undefined || !result)
+            return "failed";
+        if (result.aborted)
+            return "cancelled";
+        if (result.stopReason === "error")
+            return "failed";
+        if (result.stopReason === "max_tokens" || active.maxIterations)
+            return "partial";
+        return "completed";
+    }
+    /** The child's last non-empty reply in its session — what a partial run hands back. */
+    async lastReport(sessionId) {
+        let messages;
+        try {
+            messages = await this.deps.getMessages().get(sessionId);
+        }
+        catch {
+            return "";
+        }
+        for (let i = messages.length - 1; i >= 0; i--) {
+            const m = messages[i];
+            if (m.role === "assistant" && !m.toolResults?.length && m.content.trim())
+                return m.content;
+        }
+        return "";
+    }
+    async finish(run, status, output, error) {
+        const finishedAt = new Date();
+        const result = {
+            ...run,
+            status,
+            ...(output.trim() ? { output: sanitizeChildOutput(output) } : {}),
+            ...(error ? { error } : {}),
+            finishedAt: finishedAt.toISOString(),
+            durationMs: Math.max(0, finishedAt.getTime() - Date.parse(run.startedAt)),
+        };
+        await this.save(result);
+        const type = status === "completed" || status === "partial"
+            ? SDKEventType.SubagentCompleted
+            : status === "cancelled"
+                ? SDKEventType.SubagentCancelled
+                : SDKEventType.SubagentFailed;
+        this.deps.eventBus.emit({
+            type,
+            sessionId: result.parentSessionId,
+            payload: {
+                agentId: this.deps.agentId,
+                runId: result.id,
+                parentRunId: result.parentRunId,
+                ...(result.parentToolCallId ? { parentToolCallId: result.parentToolCallId } : {}),
+                childAgentId: result.childAgentId,
+                ...(result.childSessionId ? { childSessionId: result.childSessionId } : {}),
+                status,
+                usage: result.usage,
+                toolCalls: result.toolCalls,
+                durationMs: result.durationMs ?? 0,
+                ...(result.error ? { error: result.error } : {}),
+            },
+        });
+        return result;
+    }
+    /** A run that ended before its child turn started. */
+    finishUnstarted(run, status, error) {
+        return this.finish(run, status, "", safeError(error));
+    }
+    async save(run) {
+        try {
+            await this.deps.getStore().save(run);
+        }
+        catch (err) {
+            console.warn(`[subagent] could not save run ${run.id}:`, errorMessage(err));
+        }
+    }
+    /** A stored record, with the live token and tool-call counts while it runs here. */
+    live(run) {
+        const active = this.active.get(run.id);
+        return active ? { ...run, usage: { ...active.run.usage }, toolCalls: active.run.toolCalls } : run;
+    }
+    /** V1 nesting depth is 1: a session that is itself a child run cannot delegate. */
+    async refuseNested(sessionId) {
+        let nested = this.bindings.has(sessionId);
+        if (!nested) {
+            try {
+                nested = isSubagentSession(await this.deps.getSessions().get(sessionId));
+            }
+            catch {
+                nested = false;
+            }
+        }
+        if (nested) {
+            throw new SubagentError("you are running as a subagent and cannot delegate further — do the work yourself", "depth_exceeded");
+        }
+    }
+    /**
+     * The target `ref` names: an enabled subagent type (by name) first, then an allowed running
+     * agent (by id or name). Throws SubagentError for anything that can't run.
+     */
+    async resolveTarget(ref, config, sessionId) {
+        const self = this.deps.getProfile();
+        if (ref === self.id || ref.toLowerCase() === self.name.toLowerCase()) {
+            throw new SubagentError("an agent cannot delegate to itself", "depth_exceeded");
+        }
+        const hub = this.deps.getHub();
+        const host = this.deps.getHost();
+        if ((!config.types.length || !hub) && (!config.allow.length || !host)) {
+            throw new SubagentError("you have no subagents configured — do the work yourself", "not_allowed");
+        }
+        const lower = ref.toLowerCase();
+        if (hub && config.types.some((t) => t === ref || t === lower)) {
+            const type = await hub.get(config.types.includes(ref) ? ref : lower);
+            if (!type)
+                throw new SubagentError(`the subagent type "${ref}" no longer exists`, "not_found");
+            return { kind: "type", type, access: type.access, name: type.name };
+        }
+        let match;
+        let configuredButStopped = false;
+        for (const target of host ? config.allow : []) {
+            const agent = host.get(target.agentId);
+            const named = target.agentId === ref || agent?.profile.name.toLowerCase() === lower;
+            if (!named)
+                continue;
+            if (!agent) {
+                configuredButStopped = true;
+                continue;
+            }
+            match = { agent, access: target.access };
+            break;
+        }
+        if (!match) {
+            const allowed = (await this.targets(sessionId)).map((t) => (t.kind === "type" ? `"${t.name}"` : `"${t.name}" (${t.agentId})`)).join(", ");
+            if (configuredButStopped)
+                throw new SubagentError(`the agent "${ref}" is not running`, "not_found");
+            throw new SubagentError(`"${ref}" is not one of your subagents${allowed ? ` — you may delegate to: ${allowed}` : ""}`, "not_allowed");
+        }
+        if (match.access === "write" && !hasOwnSandbox(match.agent.profile)) {
+            throw new SubagentError(`"${match.agent.profile.name}" is set up for write access but has no sandbox of its own — a writing subagent must not share a workspace`, "write_unavailable");
+        }
+        return { kind: "agent", agent: match.agent, access: match.access, name: match.agent.profile.name };
+    }
+    /** The child's channel to the user: approvals go to the parent's (shown in the parent's chat), questions are refused. */
+    childInteraction(parentHandler, childName, childAgentId, parent) {
+        return {
+            askUser: async () => {
+                throw new Error("you are running as a subagent and cannot ask the user — make a reasonable assumption and state it in your report");
+            },
+            requestApproval: async (request) => {
+                if (!parentHandler) {
+                    return { approved: false, reason: "no interactive user is available to approve a subagent's action" };
+                }
+                return parentHandler.requestApproval({
+                    ...request,
+                    sessionId: parent.sessionId,
+                    agentId: parent.agentId,
+                    subagent: { agentId: childAgentId, agentName: childName, sessionId: request.sessionId, runId: parent.subagentRunId },
+                });
+            },
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Budgets
+    // ---------------------------------------------------------------------------
+    budgetFor(key, parentSessionId, config) {
+        this.pruneBudgets(config);
+        let budget = this.budgets.get(key);
+        if (!budget) {
+            budget = {
+                parentSessionId,
+                maxTokens: config.maxTokensPerTurn,
+                maxToolCalls: config.maxToolCallsPerTurn,
+                semaphore: new Semaphore(config.maxConcurrent),
+                launched: 0,
+                tokens: 0,
+                toolCalls: 0,
+                active: new Set(),
+                touchedAt: Date.now(),
+            };
+            this.budgets.set(key, budget);
+        }
+        return budget;
+    }
+    /** Why no further child may start in this turn, or undefined. `started`: the run already counts in `launched`. */
+    budgetRefusal(budget, config, started = false) {
+        if (!started && budget.launched >= config.maxRunsPerTurn) {
+            return `this turn already started ${config.maxRunsPerTurn} subagents (maxRunsPerTurn)`;
+        }
+        if (budget.tokens >= config.maxTokensPerTurn)
+            return `the subagents of this turn used their ${config.maxTokensPerTurn} tokens (maxTokensPerTurn)`;
+        if (budget.toolCalls >= config.maxToolCallsPerTurn) {
+            return `the subagents of this turn made their ${config.maxToolCallsPerTurn} tool calls (maxToolCallsPerTurn)`;
+        }
+        if (budget.firstStartAt !== undefined && Date.now() - budget.firstStartAt >= config.maxElapsedMsPerTurn) {
+            return `the subagents of this turn used their ${Math.round(config.maxElapsedMsPerTurn / 1000)}s (maxElapsedMsPerTurn)`;
+        }
+        return undefined;
+    }
+    addUsage(run, usage) {
+        run.run.usage = {
+            inputTokens: run.run.usage.inputTokens + usage.inputTokens,
+            outputTokens: run.run.usage.outputTokens + usage.outputTokens,
+            ...(usage.cacheReadTokens || run.run.usage.cacheReadTokens
+                ? { cacheReadTokens: (run.run.usage.cacheReadTokens ?? 0) + (usage.cacheReadTokens ?? 0) }
+                : {}),
+            ...(usage.cacheWriteTokens || run.run.usage.cacheWriteTokens
+                ? { cacheWriteTokens: (run.run.usage.cacheWriteTokens ?? 0) + (usage.cacheWriteTokens ?? 0) }
+                : {}),
+        };
+        run.budget.tokens += usage.inputTokens + usage.outputTokens;
+        this.enforceBudget(run.budget);
+    }
+    /** Over the turn's token or tool-call budget: stop every running child of the turn. */
+    enforceBudget(budget) {
+        if (budget.tokens <= budget.maxTokens && budget.toolCalls <= budget.maxToolCalls)
+            return;
+        for (const run of budget.active)
+            this.abort(run, "budget");
+    }
+    abort(run, reason) {
+        run.reason ??= reason;
+        run.controller.abort();
+    }
+    dropIdleBudgets(sessionId) {
+        for (const [key, budget] of this.budgets) {
+            if (budget.parentSessionId === sessionId && budget.active.size === 0 && budget.semaphore.busy === 0)
+                this.budgets.delete(key);
+        }
+    }
+    /** Budgets of turns that never reported their end (a tool job's call) go once idle long enough. */
+    pruneBudgets(config) {
+        const cutoff = Date.now() - 2 * config.maxElapsedMsPerTurn;
+        for (const [key, budget] of this.budgets) {
+            if (budget.active.size === 0 && budget.semaphore.busy === 0 && budget.touchedAt < cutoff)
+                this.budgets.delete(key);
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Child side — hooks the agent loop and context manager call for this agent's sessions
+    // ---------------------------------------------------------------------------
+    /** A child session's channel to the user (the parent's, for approvals only); undefined for other sessions. */
+    interactionFor(sessionId) {
+        const binding = this.bindings.get(sessionId);
+        if (!binding)
+            return undefined;
+        return (binding.interaction ?? {
+            askUser: async () => {
+                throw new Error("you are running as a subagent and cannot ask the user");
+            },
+            requestApproval: async () => ({ approved: false, reason: "no interactive user is available to approve a subagent's action" }),
+        });
+    }
+    /**
+     * A-135: the parent session of a child run's session, whose approval mode the child uses
+     * (its approvals are asked there); undefined for other sessions.
+     */
+    parentSessionOf(sessionId) {
+        return this.bindings.get(sessionId)?.parent.sessionId;
+    }
+    /** A child session's tool scope (read-only by default); undefined for other sessions. */
+    toolScope(sessionId) {
+        const binding = this.bindings.get(sessionId);
+        return binding ? childToolScope(binding.access) : undefined;
+    }
+    /**
+     * <available_subagents> for the system prompt: the subagent types and agents this one may
+     * delegate to. None in a child run's session, or when the agent lacks spawn_subagent.
+     */
+    async buildIndex(session) {
+        const scope = this.deps.getScope?.(session.id);
+        if (this.bindings.has(session.id) || isSubagentSession(session) || (!this.deps.hasSpawnTool() && !scope?.grantSpawnTool))
+            return null;
+        const targets = await this.targets(session.id);
+        if (!targets.length)
+            return null;
+        const lines = targets.map((t) => t.kind === "type"
+            ? `- ${t.name} (subagent type, ${t.access}): ${t.description}`
+            : `- ${t.name} (agent, id: ${t.agentId}, ${t.access})${t.description ? `: ${t.description}` : ""}`);
+        return ("<available_subagents>\n" +
+            "Subagents you can delegate a bounded task to with spawn_subagent (name the subagent type, or the agent's id). " +
+            (scope?.indexIntro ??
+                "Each starts fresh: give it everything it needs in the task. A subagent type is a specialist that runs with your " +
+                    "tools and workspace; an agent is a separate agent with its own tools, memory and workspace.") +
+            " " +
+            "Delegate only independent work that benefits from a separate specialist or context — call spawn_subagent several times " +
+            "in one response for independent tasks (they run in parallel), and one after another when a task needs an earlier result.\n" +
+            `${lines.join("\n")}\n</available_subagents>`);
+    }
+}
+/** spawn_subagent's text for a finished run. Re-exported for the tool. */
+export { describeResult };
+/** One turn of an existing agent in its child session. */
+async function chatTurn(agent, turn) {
+    const result = await agent.chat(turn.prompt, undefined, { signal: turn.signal, sessionId: turn.sessionId, traceAttributes: turn.traceAttributes });
+    return {
+        output: result.message.content,
+        usage: result.usage,
+        ...(result.aborted ? { aborted: true } : {}),
+        ...(result.stopReason ? { stopReason: result.stopReason } : {}),
+    };
+}
+function hasOwnSandbox(profile) {
+    return typeof profile.sandbox === "object" && profile.sandbox !== null && "own" in profile.sandbox;
+}
+function firstLine(text, max = 160) {
+    const line = (text ?? "").split("\n").map((l) => l.trim()).find(Boolean) ?? "";
+    return line.length > max ? `${line.slice(0, max)}…` : line;
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=subagent-manager.js.map