@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.21

package/dist/runtime/subagents/dispatch.js

@@ -1,11 +1,12 @@
 import { randomUUID } from "node:crypto";
 import { sql } from "kysely";
-import { normalizeStoredDefinition } from "../../agents/definition.js";
 import { audit } from "../../identity/audit.js";
 import { forkAgentUnknownText } from "../../skills/invoke.js";
-import { AGENT_REFUSALS } from "../../tools/builtins/agent.js";
+import { SEND_MESSAGE } from "../../tools/builtin-names.js";
+import { AGENT_REFUSALS, AGENT_TOOL, agentStartedText, } from "../../tools/builtins/agent.js";
 import { ACTIVE_RUN_STATUSES, runJobId } from "../run-jobs.js";
-import { effectiveDefinition, narrowFollowUp, SubagentTypeGoneError, } from "./definition.js";
+import { childResult, finishedEvent } from "./child.js";
+import { effectiveDefinition, SubagentTypeGoneError, } from "./definition.js";
 import { subagentLimits } from "./limits.js";
 import { auditRefusal, checkOrgAgent, currentAgentDefinition } from "./org-agents.js";
 import { SUBAGENT_PREAMBLE } from "./preamble.js";
@@ -17,38 +18,40 @@ const GENERAL_ENTRY = {
     source: "general",
     description: GENERAL_PURPOSE_DESCRIPTION,
 };
+/**
+ * The depth of the run behind `ctx` below the root (agent map spec §6): 0 for a root
+ * conversation's run, its parent's depth plus one for a sub-agent's.
+ */
+export const runDepth = (ctx) => ctx.parent === undefined ? 0 : ctx.parent.depth + 1;
 /** Idempotency key of the parent's `subagent_dispatched` event. */
 export const dispatchedIdemKey = (runId, callId) => `subagent_dispatched:${runId}:${callId}`;
 /**
- * Dispatches the sub-agent of one `agent` call (spec §7.1), after the pipeline's validation,
- * policy, approval and `tool.preExecute` stages. A new sub-agent: resolves its type and effective
- * definition, then in one transaction (holding the parent run's row lock, so the dispatches of one
- * run serialize) inserts the child conversation, appends `subagent_started` and the task message,
- * inserts the child run (`queued`) and the `subagent_dispatches` row, appends `subagent_dispatched`
- * to the parent and audits `subagent.dispatched`. A `resume` appends the follow-up message and
- * starts the child's next run the same way. After commit the child run is enqueued; a failed
- * enqueue only logs (the dispatch is durable, the wait sweep re-enqueues it).
+ * Dispatches the sub-agent of one `Agent` call (spec §7.1, agent map spec §4.1), after the
+ * pipeline's validation, policy, approval and `tool.preExecute` stages: resolves its type and
+ * effective definition, then in one transaction (holding the parent run's row lock, so the
+ * dispatches of one run serialize) inserts the child conversation, appends `subagent_started` and
+ * the task message, inserts the child run (`queued`) and the `subagent_dispatches` row, appends
+ * `subagent_dispatched` and the call's `tool_result` ({@link agentStartedText}: the sub-agent runs
+ * in the background) to the parent and audits `subagent.dispatched` and `tool.called`. After
+ * commit the child run is enqueued; a failed enqueue only logs (the dispatch is durable, the wait
+ * sweep re-enqueues it). A fork invocation (`forSkill`) writes no `tool_result`: its run waits on
+ * the child (`advanceSkillForks`).
  *
- * Refusals (§4.5) start nothing: a call from a sub-agent, an unknown type, an org agent that fails
- * one of its gates ({@link orgAgentGates}, at every dispatch and follow-up; audited
- * `subagent.refused`), `resume` with `subagent_type` / `model`, a `resume` id that is not a
- * sub-agent of this conversation (whatever it is otherwise: no detail about other conversations),
- * or one whose run is still active.
+ * Refusals (§4.5) start nothing: a call from a run at `subagents.maxDepth` (agent map spec §4.1:
+ * its definition has no `Agent`, so only a forged call or a lowered limit gets here), an unknown
+ * type, or an org agent that fails one of its gates ({@link orgAgentGates}, checked at every
+ * level; audited `subagent.refused`).
  */
 export async function dispatchSubagent(d, a) {
     const { ctx, input } = a;
-    if (ctx.parent !== undefined)
-        return refused(AGENT_REFUSALS.notAvailableHere);
-    if (input.resume !== undefined) {
-        if (input.subagent_type !== undefined || input.model !== undefined) {
-            return refused(AGENT_REFUSALS.resumeWithType);
-        }
-        return resume(d, { ...a, id: input.resume });
-    }
+    const { maxDepth } = await subagentLimits(d.db, d.config, ctx.orgId);
+    const childDepth = runDepth(ctx) + 1;
+    if (childDepth > maxDepth)
+        return refused(AGENT_REFUSALS.depthLimit(maxDepth));
     const requested = input.subagent_type ?? "general-purpose";
     const unknown = (types) => refused(AGENT_REFUSALS.unknownType(requested, types.map((e) => e.type)));
     const fork = a.forSkill;
-    const listed = await resolveRoster(d.db, ctx.orgId, ctx.agent);
+    const listed = await resolveRoster(d.db, ctx.orgId, ctx.agent, d.log);
     const roster = fork !== undefined && !listed.some((e) => e.type === GENERAL_ENTRY.type)
         ? [GENERAL_ENTRY, ...listed]
         : listed;
@@ -75,6 +78,8 @@ export async function dispatchSubagent(d, a) {
             parent: ctx.agent,
             parentAgentId: ctx.agentId,
             entry,
+            childDepth,
+            maxDepth,
             ...(input.model !== undefined && { tier: input.model }),
             ...(orgAgent !== undefined && { orgAgent }),
         });
@@ -84,7 +89,7 @@ export async function dispatchSubagent(d, a) {
         // the template went away since the roster was read (spec §13: refuse, never fail the run);
         // the list offered instead is read again, without it
         if (e instanceof SubagentTypeGoneError) {
-            return unknown(await resolveRoster(d.db, ctx.orgId, ctx.agent));
+            return unknown(await resolveRoster(d.db, ctx.orgId, ctx.agent, d.log));
         }
         throw e;
     }
@@ -116,6 +121,7 @@ export async function dispatchSubagent(d, a) {
             kind: "subagent",
             parent_conversation_id: ctx.conversationId,
             subagent_type: entry.type,
+            subagent_depth: childDepth,
         })
             .execute();
         const [, task] = await d.eventLog.appendIn(childId, [
@@ -155,91 +161,6 @@ export async function dispatchSubagent(d, a) {
     // a new sub-agent's writer never refuses
     return out ?? refused(AGENT_REFUSALS.notAvailableHere);
 }
-/**
- * A follow-up to an existing sub-agent of this conversation (§4.2 `resume`). It keeps the frozen
- * definition's instructions and model (replay), but is checked against what the parent may use
- * now (final review I1): a `general` / inline / plugin child's type must still be in the roster
- * of the dispatching run's version (a plugin template by its template id), else the call is
- * refused as an unknown type; an org agent child passes its gates. Its tools and org skills are
- * intersected with the current version ({@link narrowFollowUp}: the dispatching run's version,
- * or the org agent's current version as the gates read it under the lock), and the result is
- * recorded on the follow-up's task message for the run and for replay.
- */
-async function resume(d, a) {
-    const { ctx } = a;
-    const child = await d.db
-        .selectFrom("conversations")
-        .select(["id", "subagent_type"])
-        .where("id", "=", a.id)
-        .where("org_id", "=", ctx.orgId)
-        .where("kind", "=", "subagent")
-        .where("parent_conversation_id", "=", ctx.conversationId)
-        .executeTakeFirst();
-    if (!child)
-        return refused(AGENT_REFUSALS.noSuchAgent(a.id));
-    const started = await d.eventLog.findByIdem(child.id, "subagent_started");
-    if (started?.type !== "subagent_started")
-        return refused(AGENT_REFUSALS.noSuchAgent(a.id));
-    const { template } = started.payload;
-    const agentType = child.subagent_type ?? started.payload.agentType;
-    // an org agent's gates hold for every follow-up too (§5.5); it keeps its frozen version
-    if (template.source === "agent") {
-        const gates = await orgAgentGates(d.db, a, template.id ?? "", agentType, true);
-        if ("refused" in gates)
-            return gates.refused;
-    }
-    else {
-        const roster = await resolveRoster(d.db, ctx.orgId, ctx.agent);
-        const entry = template.source === "plugin"
-            ? roster.find((e) => e.source === "plugin" && e.templateId === template.id)
-            : findType(roster, agentType);
-        if (entry?.source !== template.source) {
-            return refused(AGENT_REFUSALS.unknownType(agentType, roster.map((e) => e.type)));
-        }
-    }
-    const frozen = normalizeStoredDefinition(started.payload.definition);
-    const plan = {
-        childConversationId: child.id,
-        agentType,
-        source: template.source,
-        agentId: template.source === "agent" ? (template.id ?? "") : ctx.agentId,
-        agentVersion: template.source === "agent" ? (template.version ?? ctx.agentVersion) : ctx.agentVersion,
-        resumed: true,
-        model: started.payload.definition.model,
-        tierFallback: false,
-    };
-    return commit(d, a, plan, async (t, checked) => {
-        const current = template.source === "agent" ? checked?.definition : ctx.agent;
-        if (current === undefined)
-            throw new Error("org agent follow-up without its checked version");
-        const activeRun = () => t
-            .selectFrom("runs")
-            .select("id")
-            .where("conversation_id", "=", child.id)
-            .where("status", "in", ACTIVE_RUN_STATUSES)
-            .executeTakeFirst();
-        // An active child is refused before its row is locked: a running child's token append locks
-        // its conversation row and then this parent run's row, which `commit` already holds, so
-        // waiting for the child's row here would be a lock-order cycle (review I1). The parent row
-        // lock serializes this parent's dispatches, so an earlier follow-up's run is visible here.
-        if (await activeRun())
-            return null;
-        // the child's row lock serializes follow-ups to one sub-agent; no run holds it now, so it is
-        // never held by an append waiting for the parent row
-        await t
-            .selectFrom("conversations")
-            .select("id")
-            .where("id", "=", child.id)
-            .forUpdate()
-            .executeTakeFirst();
-        if (await activeRun())
-            return null;
-        const [task] = await d.eventLog.appendIn(child.id, [
-            taskMessage(ctx, a.callId, a.input.prompt, narrowFollowUp(frozen, current)),
-        ]);
-        return task;
-    }).then((r) => r ?? refused(AGENT_REFUSALS.stillRunning(a.id)));
-}
 /**
  * The gates of an org agent sub-agent (§5.5) for this call: the allowlist of the parent agent's
  * **current** version (R5), the agent's `dispatchable`, its visibility to the person who started
@@ -248,7 +169,7 @@ async function resume(d, a) {
  * sub-agent freezes the definition read here) and again inside it under the parent run's row lock
  * ({@link commit}), so a gate revoked in between refuses (batch 9 review M1).
  */
-async function orgAgentGates(db, a, agentId, agentType, resumed) {
+export async function orgAgentGates(db, a, agentId, agentType, resumed) {
     const { ctx } = a;
     const parentDefinition = (await currentAgentDefinition(db, ctx.agentId)) ?? {};
     const check = await checkOrgAgent(db, {
@@ -272,13 +193,19 @@ async function orgAgentGates(db, a, agentId, agentType, resumed) {
     });
     return { refused: refused(AGENT_REFUSALS.agentNotAvailable(agentType)) };
 }
-const taskMessage = (ctx, callId, prompt, narrowed, 
 /**
- * A fork invocation's record: the child's log then holds the invocation, so its `skill_load`
+ * A sub-agent's task message, or (`message`) a `SendMessage` from its parent (agent map spec
+ * §5.1: `dispatch.kind: "message"`, idempotent by the sending call, with the follow-up narrowing
+ * the run it triggers uses).
+ */
+export const taskMessage = (ctx, callId, prompt, narrowed, 
+/**
+ * A fork invocation's record: the child's log then holds the invocation, so its `Skill`
  * is offered and resolves the invoked version (phase D).
  */
-skill) => ({
+skill, message = false) => ({
     type: "user_message",
+    ...(message && { idemKey: sentMessageIdemKey(ctx.runId, callId) }),
     payload: {
         content: [{ type: "text", text: prompt }],
         ...(skill !== undefined && { skill }),
@@ -287,10 +214,39 @@ skill) => ({
             parentConversationId: ctx.conversationId,
             parentRunId: ctx.runId,
             callId,
+            ...(message && { kind: "message" }),
             ...(narrowed !== undefined && { narrowed }),
         },
     },
 });
+/** Idempotency key of a `SendMessage`'s `user_message` in the sub-agent's log. */
+export const sentMessageIdemKey = (runId, callId) => `send_message:${runId}:${callId}`;
+const isActiveStatus = (status) => ACTIVE_RUN_STATUSES.includes(status);
+/**
+ * The result text of a child run that ended before its parent's call got a result and was never
+ * delivered (agent map spec, rc upgrade: a foreground-era dispatch whose rc finisher wrote
+ * `subagent_finished` and resumed the parent): the child's report (`childResult`), with the
+ * parent's `subagent_finished` appended in this transaction when it is missing (idempotent by its
+ * key), so the undelivered sweep never delivers it a second time. Null when the parent already
+ * has a delivery for the run (it carries the result) or the run has no terminal event yet.
+ */
+async function rcFinishedResult(d, row) {
+    const delivered = await d.db
+        .selectFrom("conversation_events")
+        .select("seq")
+        .where("conversation_id", "=", row.parentConversationId)
+        .where("type", "=", "subagent_delivery")
+        .where(sql `payload ->> 'childRunId'`, "=", row.childRunId)
+        .limit(1)
+        .executeTakeFirst();
+    if (delivered)
+        return null;
+    const r = await childResult(d.eventLog, row);
+    if (!r)
+        return null;
+    await d.eventLog.appendIn(row.parentConversationId, [finishedEvent(row, r.finished)]);
+    return r.content;
+}
 /**
  * {@link commit}'s transaction (run by `SubagentsService.commitDispatch`, `d.db` its handle).
  * Null when `child` refused.
@@ -310,7 +266,7 @@ export async function commitDispatchIn(d, a, plan, child) {
         .executeTakeFirst();
     const parent = await t
         .selectFrom("runs")
-        .select(["status", "subagent_tokens_used"])
+        .select(["status", "subagent_tokens_used", "budget_run_id"])
         .where("id", "=", ctx.runId)
         .forUpdate()
         .executeTakeFirst();
@@ -322,9 +278,41 @@ export async function commitDispatchIn(d, a, plan, child) {
         .where("sd.parent_call_id", "=", callId)
         .executeTakeFirst();
     if (existing) {
+        // An `Agent` call's result was written with its first dispatch (this returns it). A call
+        // dispatched before `Agent` ran in the background (a foreground wait in flight across the
+        // upgrade) gets the immediate result now, so the log never keeps it unpaired; such a call
+        // reaches here again through the pipeline's policy stages, so it may ask for approval again.
+        let result = null;
+        if (a.forSkill === undefined) {
+            // an rc child that already ended under the foreground wait, whose rc finisher wrote
+            // `subagent_finished` and resumed this run (no delivery; the sweep never delivers a run with
+            // `subagent_finished`): its report is this call's result, as the rc gave it, or it is lost.
+            // Only while the call has no result: a call that has one (a background dispatch's second
+            // holder) keeps it, and its child's finish stays to its delivery or the undelivered sweep.
+            const resultKey = resultEvent(ctx, callId, AGENT_TOOL, "").idemKey;
+            const finished = a.sent === undefined &&
+                existing.status !== null &&
+                !isActiveStatus(existing.status) &&
+                (await d.eventLog.findByIdem(ctx.conversationId, resultKey)) === undefined
+                ? await rcFinishedResult(d, {
+                    parentRunId: ctx.runId,
+                    parentCallId: callId,
+                    parentConversationId: ctx.conversationId,
+                    childConversationId: existing.child_conversation_id,
+                    childRunId: existing.child_run_id,
+                })
+                : null;
+            const [ev] = await d.eventLog.appendIn(ctx.conversationId, [
+                resultEvent(ctx, callId, a.call?.toolKey ?? AGENT_TOOL, finished ?? a.sent?.content ?? agentStartedText(existing.child_conversation_id)),
+            ]);
+            if (ev?.type === "tool_result")
+                result = { content: ev.payload.content, seq: ev.seq };
+        }
         return {
             kind: "existing",
             childRunId: existing.child_run_id,
+            childConversationId: existing.child_conversation_id,
+            result,
             // still queued: the first holder may have died before its enqueue (review M4)
             requeue: existing.status === "queued" && existing.trigger_seq !== null
                 ? {
@@ -336,7 +324,18 @@ export async function commitDispatchIn(d, a, plan, child) {
     }
     if (parent?.status !== "running")
         return { kind: "stopped" };
-    const limit = await limitRefusal(t, d, ctx, parent.subagent_tokens_used);
+    // the tree's budget run (agent map spec §6), locked after the parent run so the dispatches of
+    // every run of one tree serialize on it; the parent run itself when it opened the window
+    const budgetRunId = parent.budget_run_id ?? ctx.runId;
+    const tokensUsed = budgetRunId === ctx.runId
+        ? parent.subagent_tokens_used
+        : ((await t
+            .selectFrom("runs")
+            .select("subagent_tokens_used")
+            .where("id", "=", budgetRunId)
+            .forUpdate()
+            .executeTakeFirst())?.subagent_tokens_used ?? 0);
+    const limit = await limitRefusal(t, d, ctx, budgetRunId, tokensUsed, a.sent?.refusals ?? AGENT_REFUSALS);
     if (limit !== null)
         return { kind: "limit", content: limit };
     let checked;
@@ -367,6 +366,7 @@ export async function commitDispatchIn(d, a, plan, child) {
         agent_version: plan.agentVersion,
         trigger_account_id: ctx.accountId,
         trigger_seq: task.seq,
+        budget_run_id: budgetRunId,
     })
         .execute();
     await t
@@ -379,9 +379,14 @@ export async function commitDispatchIn(d, a, plan, child) {
         child_conversation_id: plan.childConversationId,
         child_run_id: childRunId,
         resumed: plan.resumed,
+        budget_run_id: budgetRunId,
+        for_skill: a.forSkill !== undefined,
     })
         .execute();
-    const [dispatched] = await d.eventLog.appendIn(ctx.conversationId, [
+    // an org agent runs on its own model (§5.4): a `model` on the call was ignored
+    const ownModel = plan.source === "agent" && input.model !== undefined;
+    const content = a.sent?.content ?? agentStartedText(plan.childConversationId, { ownModel });
+    const parentEvents = await d.eventLog.appendIn(ctx.conversationId, [
         {
             type: "subagent_dispatched",
             runId: ctx.runId,
@@ -399,6 +404,11 @@ export async function commitDispatchIn(d, a, plan, child) {
                 ...(a.forSkill !== undefined && { invokedSeq: a.forSkill.seq }),
             },
         },
+        // an `Agent` call's result is immediate (agent map spec §4.1): the sub-agent works in the
+        // background and reports through `subagent_delivery`; a fork invocation has no tool call
+        ...(a.forSkill === undefined
+            ? [resultEvent(ctx, callId, a.call?.toolKey ?? AGENT_TOOL, content)]
+            : []),
     ]);
     await audit(t, {
         actorAccountId: ctx.accountId,
@@ -419,14 +429,44 @@ export async function commitDispatchIn(d, a, plan, child) {
             childRunId,
         },
     });
+    if (a.forSkill === undefined) {
+        await audit(t, {
+            actorAccountId: ctx.accountId,
+            orgId: ctx.orgId,
+            action: "tool.called",
+            target: ctx.conversationId,
+            detail: {
+                toolKey: a.sent !== undefined ? SEND_MESSAGE : AGENT_TOOL,
+                isError: false,
+                durationMs: a.call === undefined ? null : Math.max(0, Date.now() - a.call.startedAt),
+                agentId: ctx.agentId,
+                agentVersion: ctx.agentVersion,
+                conversationId: ctx.conversationId,
+                runId: ctx.runId,
+                callId,
+                ...a.call?.authorization,
+            },
+        });
+    }
     return {
         kind: "written",
         childRunId,
         childSeq: task.seq,
-        parentSeq: dispatched.seq,
+        parentSeq: Math.max(...parentEvents.map((e) => e.seq)),
+        content,
     };
 }
-async function commit(d, a, plan, 
+/**
+ * The immediate `tool_result` of an `Agent` call ({@link agentStartedText}) or of a `SendMessage`
+ * that started an idle sub-agent, idempotent by the call.
+ */
+const resultEvent = (ctx, callId, toolKey, content) => ({
+    type: "tool_result",
+    runId: ctx.runId,
+    idemKey: `tool_result:${ctx.runId}:${callId}`,
+    payload: { step: ctx.step, callId, toolKey, content, isError: false },
+});
+export async function commit(d, a, plan, 
 /** Writes the child's events; `checked` is the org agent version the in-lock gates passed. */
 child) {
     const { ctx } = a;
@@ -447,11 +487,19 @@ child) {
                 err,
             }));
         }
-        return { kind: "dispatched", childRunId: out.childRunId };
+        if (out.result !== null)
+            await d.eventLog.notify(ctx.conversationId, out.result.seq);
+        return {
+            kind: "dispatched",
+            childRunId: out.childRunId,
+            childConversationId: out.childConversationId,
+            content: out.result?.content ?? a.sent?.content ?? agentStartedText(out.childConversationId),
+        };
     }
     // the result is never read: the run is over
-    if (out.kind === "stopped")
-        return refused(AGENT_REFUSALS.notAvailableHere);
+    if (out.kind === "stopped") {
+        return refused((a.sent?.refusals ?? AGENT_REFUSALS).notAvailableHere);
+    }
     if (out.kind === "limit")
         return refused(out.content);
     if (out.kind === "gate")
@@ -467,31 +515,54 @@ child) {
         // the dispatch is committed: the wait sweep re-enqueues the queued child run
         d.log.error("cannot enqueue sub-agent run; the sweep retries", { childRunId, jobId, err });
     }
-    return { kind: "dispatched", childRunId };
+    return {
+        kind: "dispatched",
+        childRunId,
+        childConversationId: plan.childConversationId,
+        content: out.content,
+    };
 }
 /**
- * The §4.5 refusal of a dispatch the parent run's limits forbid, or null. Runs under the parent
- * run's row lock; `tokensUsed` is the counter read with that lock.
+ * The §4.5 refusal of a dispatch the limits forbid, or null (agent map spec §6). Runs under the
+ * parent conversation's, the parent run's and the budget run's row locks; `tokensUsed` is the
+ * budget run's counter read with its lock. A dispatch from a run at `maxDepth` is refused (the
+ * limit may have been lowered since the call's definition was frozen); tokens and dispatches
+ * (follow-ups included) count the whole tree on its budget run; concurrency counts the child
+ * conversations of the parent conversation that have an active run, whatever started that run.
  */
-async function limitRefusal(t, d, ctx, tokensUsed) {
+async function limitRefusal(t, d, ctx, budgetRunId, tokensUsed, texts) {
     const limits = await subagentLimits(t, d.config, ctx.orgId);
-    if (Number(tokensUsed) >= limits.maxTokensPerRun) {
-        return AGENT_REFUSALS.budget(limits.maxTokensPerRun);
+    if (runDepth(ctx) >= limits.maxDepth)
+        return texts.depthLimit(limits.maxDepth);
+    // 0: no limit (the deployment config or the org's override)
+    if (limits.maxTokensPerRun > 0 && Number(tokensUsed) >= limits.maxTokensPerRun) {
+        return texts.budget(limits.maxTokensPerRun);
     }
-    const counts = await t
-        .selectFrom("subagent_dispatches as sd")
-        .innerJoin("runs as cr", "cr.id", "sd.child_run_id")
-        .select([
-        sql `count(*)`.as("total"),
-        sql `count(*) FILTER (WHERE cr.status IN (${sql.join(ACTIVE_RUN_STATUSES)}))`.as("active"),
-    ])
-        .where("sd.parent_run_id", "=", ctx.runId)
-        .executeTakeFirstOrThrow();
-    if (Number(counts.total) >= limits.maxDispatchesPerRun) {
-        return AGENT_REFUSALS.tooManyDispatches(limits.maxDispatchesPerRun);
+    if (limits.maxDispatchesPerRun > 0) {
+        const total = await t
+            .selectFrom("subagent_dispatches")
+            .select(sql `count(*)`.as("n"))
+            .where("budget_run_id", "=", budgetRunId)
+            .executeTakeFirstOrThrow();
+        if (Number(total.n) >= limits.maxDispatchesPerRun) {
+            return texts.tooManyDispatches(limits.maxDispatchesPerRun);
+        }
     }
-    if (Number(counts.active) >= limits.maxConcurrentPerRun) {
-        return AGENT_REFUSALS.tooManyConcurrent(limits.maxConcurrentPerRun);
+    // every child conversation with an active run of any origin: a dispatch, a message it never
+    // absorbed (a continuation run) or a wake run all hold its slot
+    const active = await t
+        .selectFrom("conversations as c")
+        .select(sql `count(*)`.as("n"))
+        .where("c.parent_conversation_id", "=", ctx.conversationId)
+        .where("c.kind", "=", "subagent")
+        .where("c.deleted_at", "is", null)
+        .where(({ exists, selectFrom }) => exists(selectFrom("runs as cr")
+        .select(sql `1`.as("one"))
+        .whereRef("cr.conversation_id", "=", "c.id")
+        .where("cr.status", "in", ACTIVE_RUN_STATUSES)))
+        .executeTakeFirstOrThrow();
+    if (Number(active.n) >= limits.maxConcurrentPerConversation) {
+        return texts.tooManyConcurrent(limits.maxConcurrentPerConversation);
     }
     return null;
 }

package/dist/runtime/subagents/limits.d.ts

@@ -4,9 +4,15 @@ import type { KernelSchemaDb } from "../../db/kernel-schema.js";
 export interface SubagentsConfig {
     get(): Pick<KernelConfig, "subagents">;
 }
-/** The sub-agent limits of one parent run (sub-agents spec §8.2). */
+/**
+ * The sub-agent limits of an organization (sub-agents spec §8.2, agent map spec §6): the depth
+ * below the root, the active children of one conversation, and the dispatches and tokens of one
+ * tree, counted on its budget run ({@link budgetRunOf}). `maxDispatchesPerRun` and
+ * `maxTokensPerRun` of 0 mean no limit.
+ */
 export interface SubagentLimits {
-    maxConcurrentPerRun: number;
+    maxDepth: number;
+    maxConcurrentPerConversation: number;
     maxDispatchesPerRun: number;
     maxTokensPerRun: number;
 }
@@ -21,8 +27,21 @@ export declare function subagentLimits(
 /** The pool, or the context's handle (a `@Transactional` caller's transaction). */
 db: KernelSchemaDb, config: SubagentsConfig, orgId: string): Promise<SubagentLimits>;
 /**
- * Whether the sub-agents of `parentRunId` have used their token budget (§8.3): its
- * `subagent_tokens_used`, read fresh, at or over `maxTokensPerRun`. A sub-agent's step checks it
+ * The budget run of `runId` (agent map spec §6): its `budget_run_id`, or the run itself when it has
+ * none (a person-triggered run opens its own window) or does not exist. The dispatch count and the
+ * token counter of a whole tree live on this run.
+ */
+export declare function budgetRunOf(db: KernelSchemaDb, runId: string): Promise<string>;
+/**
+ * The current budget window of the tree rooted at `rootConversationId` (agent map spec §6): its
+ * newest run that opened its own window (`budget_run_id` null: a person-triggered run), or null
+ * when it has none. A wake run of any conversation of the tree carries it as its `budget_run_id`,
+ * so a chain of wakes never opens a new window.
+ */
+export declare function budgetWindowOf(db: KernelSchemaDb, rootConversationId: string): Promise<string | null>;
+/**
+ * Whether the sub-agents of a tree have used their token budget (§8.3): the budget run's
+ * `subagent_tokens_used`, read fresh, at or over `maxTokensPerRun` (never when it is 0: no limit). A sub-agent's step checks it
  * before every model request and ends its run with `budget` when it is.
  */
-export declare function subagentBudgetUsedUp(db: KernelSchemaDb, config: SubagentsConfig, orgId: string, parentRunId: string): Promise<boolean>;
+export declare function subagentBudgetUsedUp(db: KernelSchemaDb, config: SubagentsConfig, orgId: string, budgetRunId: string): Promise<boolean>;

package/dist/runtime/subagents/limits.js

@@ -13,24 +13,58 @@ db, config, orgId) {
     const base = config.get().subagents;
     const over = await readSubagentLimitOverride(db, orgId);
     return {
-        maxConcurrentPerRun: over?.maxConcurrentPerRun ?? base.maxConcurrentPerRun,
+        maxDepth: over?.maxDepth ?? base.maxDepth,
+        maxConcurrentPerConversation: over?.maxConcurrentPerConversation ?? base.maxConcurrentPerConversation,
         maxDispatchesPerRun: over?.maxDispatchesPerRun ?? base.maxDispatchesPerRun,
         maxTokensPerRun: over?.maxTokensPerRun ?? base.maxTokensPerRun,
     };
 }
 /**
- * Whether the sub-agents of `parentRunId` have used their token budget (§8.3): its
- * `subagent_tokens_used`, read fresh, at or over `maxTokensPerRun`. A sub-agent's step checks it
+ * The budget run of `runId` (agent map spec §6): its `budget_run_id`, or the run itself when it has
+ * none (a person-triggered run opens its own window) or does not exist. The dispatch count and the
+ * token counter of a whole tree live on this run.
+ */
+export async function budgetRunOf(db, runId) {
+    const row = await db
+        .selectFrom("runs")
+        .select("budget_run_id")
+        .where("id", "=", runId)
+        .executeTakeFirst();
+    return row?.budget_run_id ?? runId;
+}
+/**
+ * The current budget window of the tree rooted at `rootConversationId` (agent map spec §6): its
+ * newest run that opened its own window (`budget_run_id` null: a person-triggered run), or null
+ * when it has none. A wake run of any conversation of the tree carries it as its `budget_run_id`,
+ * so a chain of wakes never opens a new window.
+ */
+export async function budgetWindowOf(db, rootConversationId) {
+    const row = await db
+        .selectFrom("runs")
+        .select("id")
+        .where("conversation_id", "=", rootConversationId)
+        .where("budget_run_id", "is", null)
+        .orderBy("created_at", "desc")
+        .limit(1)
+        .executeTakeFirst();
+    return row?.id ?? null;
+}
+/**
+ * Whether the sub-agents of a tree have used their token budget (§8.3): the budget run's
+ * `subagent_tokens_used`, read fresh, at or over `maxTokensPerRun` (never when it is 0: no limit). A sub-agent's step checks it
  * before every model request and ends its run with `budget` when it is.
  */
-export async function subagentBudgetUsedUp(db, config, orgId, parentRunId) {
+export async function subagentBudgetUsedUp(db, config, orgId, budgetRunId) {
+    const { maxTokensPerRun } = await subagentLimits(db, config, orgId);
+    // 0: no limit
+    if (maxTokensPerRun === 0)
+        return false;
     const row = await db
         .selectFrom("runs")
         .select("subagent_tokens_used")
-        .where("id", "=", parentRunId)
+        .where("id", "=", budgetRunId)
         .executeTakeFirst();
     if (!row)
         return false;
-    const { maxTokensPerRun } = await subagentLimits(db, config, orgId);
     return Number(row.subagent_tokens_used) >= maxTokensPerRun;
 }