@capybara-hq/kernel 0.1.0-rc.0 → 0.1.0-rc.10

package/dist/runtime/stream.js

@@ -1,6 +1,21 @@
-import { CONVERSATION_CHANGES, conversationTopic, } from "../conversations/event-log.js";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable, Optional } from "@nestjs/common";
+import { ConversationAccess } from "../conversations/access.js";
+import { CONVERSATION_CHANGES, conversationTopic, EventLog, } from "../conversations/event-log.js";
 import { ApiError } from "../errors.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { GracefulShutdown } from "../infra/lifecycle/graceful-shutdown.service.js";
+import { KERNEL_BUS, KERNEL_LOGGER } from "../infra/tokens.js";
 import { isUiBusMessage, uiFrame } from "../ui/registry.js";
+import { RunDrafts } from "./run-drafts.js";
 /** 补读事件的分页大小。 */
 const PAGE = 500;
 /** 慢客户端的积压上限：超过即关闭流，客户端带 Last-Event-ID 重连补读。 */
@@ -41,16 +56,36 @@ function isBusMessage(m) {
     return k === "delta" && typeof m.runId === "string";
 }
 const eventFrame = (e) => `id: ${e.seq}\nevent: event\ndata: ${JSON.stringify(e)}\n\n`;
+const draftFrame = (d) => `event: draft\ndata: ${JSON.stringify({ runId: d.runId, step: d.step, text: d.text, thinking: d.thinking })}\n\n`;
 /**
  * 会话事件流（SSE）：本进程持有的连接集合，停机时一并关闭。
  * 跨副本的数据只经 PG（事件日志）与内核 bus（`conv.<id>`）流动，进程内只保存连接本身的资源
  * （订阅、心跳与复核定时器）。
  */
-export class ConversationStreams {
-    d;
+let ConversationStreams = class ConversationStreams {
     active = new Set();
-    constructor(d) {
-        this.d = d;
+    /** Set by {@link closeAll}: streams opened afterwards end as soon as they begin. */
+    closing = false;
+    d;
+    /**
+     * Closes the streams when the shutdown begins (readiness answers 503 from that moment) and
+     * latches: streams opened afterwards end at once, so the HTTP phase of the stop never waits on
+     * an event stream. Without `GracefulShutdown` (a standalone HTTP application, tests only) the
+     * streams end with their connections.
+     */
+    constructor(eventLog, bus, access, config, log, drafts, shutdown) {
+        this.d = {
+            eventLog,
+            bus,
+            access: (orgId, conversationId, viewer) => access.isAccessible(orgId, conversationId, viewer),
+            config,
+            log,
+            drafts: (conversationId) => drafts.live(conversationId),
+        };
+        if (shutdown?.signal.aborted)
+            this.closeAll();
+        else
+            shutdown?.signal.addEventListener("abort", () => this.closeAll(), { once: true });
     }
     /**
      * 复核凭据与可见性，并先订阅会话频道（之后再回放，避免遗漏两者之间提交的事件）。
@@ -60,6 +95,8 @@ export class ConversationStreams {
         const denied = await authorize(this.d, p);
         if (denied !== null)
             throw new ApiError(denied, DENIAL_MESSAGES[denied] ?? "Access denied");
+        if (this.closing)
+            return endedStream(out);
         const conn = new Connection(this.d, p, out, () => this.active.delete(conn));
         this.active.add(conn);
         try {
@@ -69,10 +106,19 @@ export class ConversationStreams {
             conn.close();
             throw e;
         }
+        // closeAll ran while subscribing: the connection is closed, the response must still end
+        if (this.closing) {
+            conn.close();
+            return endedStream(out);
+        }
         return conn;
     }
-    /** 关闭本进程的全部流（停机时调用）。 */
+    /**
+     * Closes every stream of this process (at shutdown) and latches: a stream opened afterwards ends
+     * right after its headers, so a reconnecting client cannot hold the HTTP close open.
+     */
     closeAll() {
+        this.closing = true;
         for (const c of [...this.active])
             c.close();
     }
@@ -80,6 +126,35 @@ export class ConversationStreams {
     get size() {
         return this.active.size;
     }
+};
+ConversationStreams = __decorate([
+    Injectable(),
+    __param(0, Inject(EventLog)),
+    __param(1, Inject(KERNEL_BUS)),
+    __param(2, Inject(ConversationAccess)),
+    __param(3, Inject(KernelConfigService)),
+    __param(4, Inject(KERNEL_LOGGER)),
+    __param(5, Inject(RunDrafts)),
+    __param(6, Optional()),
+    __param(6, Inject(GracefulShutdown))
+], ConversationStreams);
+export { ConversationStreams };
+/**
+ * The handle of a stream opened after shutdown began: `begin` (the headers are written) ends the
+ * response at once; the client reconnects with `Last-Event-ID`, to a replica that is still ready.
+ */
+export function endedStream(out) {
+    return {
+        begin: () => {
+            try {
+                out.end();
+            }
+            catch {
+                // the connection is already gone
+            }
+        },
+        close: () => { },
+    };
 }
 class Connection {
     d;
@@ -105,6 +180,9 @@ class Connection {
             this.openGate = resolve;
         });
         this.enqueue(() => this.catchUp());
+        // live drafts (spec 2026-11-07 §3.2): after the catch-up, before any delta (deltas are queued
+        // behind this); a delta also in the draft is dropped by the client by its offset
+        this.enqueue(() => this.sendDrafts());
     }
     async subscribe() {
         const un = await this.d.bus.subscribe(conversationTopic(this.p.conversationId), (m) => this.onMessage(m));
@@ -117,7 +195,7 @@ class Connection {
         if (this.closed)
             return;
         this.begun = true;
-        const { sseHeartbeatMs, sseRecheckMs } = this.d.config().runtime;
+        const { sseHeartbeatMs, sseRecheckMs } = this.d.config.get().runtime;
         this.timers.push(setInterval(() => this.write(": ping\n\n"), sseHeartbeatMs), setInterval(() => void this.recheck(), sseRecheckMs));
         this.openGate();
     }
@@ -211,6 +289,23 @@ class Connection {
                 return;
         }
     }
+    /** One `event: draft` per step of the running run whose `assistant_message` is not logged. */
+    async sendDrafts() {
+        let drafts;
+        try {
+            drafts = await this.d.drafts(this.p.conversationId);
+        }
+        catch (err) {
+            // a convenience: without it the client resumes from the next delta (and asks for the draft)
+            this.d.log.warn("conversation stream cannot read live drafts", {
+                conversationId: this.p.conversationId,
+                err,
+            });
+            return;
+        }
+        for (const d of drafts)
+            this.write(draftFrame(d));
+    }
     /** 发最后一帧错误并关闭（未发完的排队输出随关闭丢弃）。 */
     fail(code) {
         if (this.closed)

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

@@ -1,10 +1,7 @@
-import type { Logger } from "@capybara-hq/plugin-sdk";
 import type { AppendEvent, EventLog } from "../../conversations/event-log.js";
 import type { EventPayload } from "../../conversations/events.js";
-import type { KernelDb } from "../../db/kernel-schema.js";
-import type { RunAbort, RunAbortDetail } from "../abort.js";
-import { type RunQueue } from "../run-queue.js";
-import type { Waits } from "../waits.js";
+import type { KernelSchemaDb } from "../../db/kernel-schema.js";
+import type { SubagentAbortedBy } from "./status.js";
 /** Idempotency key of the parent's `subagent_finished` event. */
 export declare const finishedIdemKey: (childRunId: string) => string;
 /** A dispatch row, by its child run. */
@@ -14,67 +11,77 @@ export interface DispatchRow {
     parentConversationId: string;
     childConversationId: string;
     childRunId: string;
+    /** The budget run the dispatch counts against (agent map spec §6); set when read from the row. */
+    budgetRunId?: string;
+    /**
+     * A person's fork invocation (phase D, `subagent_dispatches.for_skill`): the parent run waits on
+     * it (`subagents` wait); every other dispatch runs in the background (agent map spec §5.4).
+     */
+    forSkill?: boolean;
 }
 /** The dispatch that started `childRunId`, or null (not a sub-agent run). */
-export declare function dispatchOfChildRun(db: KernelDb, childRunId: string): Promise<DispatchRow | null>;
+export declare function dispatchOfChildRun(db: KernelSchemaDb, childRunId: string): Promise<DispatchRow | null>;
+/**
+ * The dispatch row a finished child run reports through (agent map spec §5.2: every run of a child
+ * conversation that ends appends one `finished` delivery to its parent): the run's own dispatch
+ * (`Agent`, `SendMessage`), else, for a run nobody dispatched (a wake run, §5.3), the newest dispatch
+ * of its conversation with `childRunId` set to this run, `forSkill` false (a wake run of a fork's
+ * child is delivered like any background run; no parent run waits on it) and the run's own budget
+ * run. Null when the run is unknown or its conversation was never dispatched.
+ */
+export declare function deliveryRowOfChildRun(db: KernelSchemaDb, childRunId: string): Promise<DispatchRow | null>;
 /** The dispatch of the parent call `(runId, callId)`, or null (not dispatched yet). */
-export declare function dispatchOfCall(db: KernelDb, runId: string, callId: string): Promise<DispatchRow | null>;
+export declare function dispatchOfCall(db: KernelSchemaDb, runId: string, callId: string): Promise<DispatchRow | null>;
+/**
+ * The root conversation of `conversationId`'s tree (agent map spec §6): the first ancestor without
+ * a parent, or `conversationId` itself for a root (or an unknown id).
+ */
+export declare function rootConversationOf(db: KernelSchemaDb, conversationId: string): Promise<string>;
+/** Where a sub-agent's request for a person is shown: see {@link rootSurfaceOf}. */
+export interface RootSurface {
+    /** The root conversation of the sub-agent's tree. */
+    conversationId: string;
+    /** The root run the event is logged under: the one that last dispatched the branch. */
+    runId: string;
+    /** Child conversation ids from the root's child down to the sub-agent itself. */
+    path: string[];
+}
+/**
+ * Where the sub-agent conversation `conversationId`, in its run `runId`, shows a request for a
+ * person (`subagent_waiting`: an approval, a question or a connect card; agent map spec §7): the
+ * **root** conversation of its tree, the only one a person looks at, with the path from the root's
+ * child down to it, under the root run that last dispatched (or messaged) the root's child on that
+ * path (for a child of the root, the run's own dispatch first). `parent`, when the caller knows the
+ * run's dispatch and it was made by the root (`depth` 0), answers without a read. Null for a root
+ * conversation, or a branch the root never dispatched.
+ */
+export declare function rootSurfaceOf(db: KernelSchemaDb, conversationId: string, runId: string, parent?: {
+    conversationId: string;
+    runId: string;
+    depth: number;
+}): Promise<RootSurface | null>;
 /**
- * The tool result of a finished child run (spec §4.4) and its `subagent_finished` payload, from
- * the child's log only: the status from its terminal event, the reply from its last
+ * The result of a finished child run (spec §4.4) and its `subagent_finished` payload, from the
+ * child's log only: the status from its terminal event, the reply from its last
  * `assistant_message` (text blocks), the tool call count from its `tool_result` events, the usage
  * from its `usage` events (compaction included) and the duration from `run_started` to the
- * terminal event. Null while the run has no terminal event.
+ * terminal event. Null while the run has no terminal event. `content` is the fork report's text
+ * (`agentResultText`); `reply`, `errorMessage` and `abortedBy` are what a background child's
+ * finished `subagent_delivery` carries.
  *
  * `modelGiven`: the parent's call named a `model`; for an org agent, which runs on its own model
  * (§5.4, §5.5), the status line then says `model: the agent's own`.
  */
-export declare function childResult(eventLog: EventLog, row: DispatchRow, 
-/** `forSkill`: a fork invocation's report (no resume hint, see `agentResultText`). */
-opts?: {
+export declare function childResult(eventLog: EventLog, row: DispatchRow, opts?: {
     modelGiven?: boolean;
-    forSkill?: boolean;
 }): Promise<{
     content: string;
     isError: boolean;
+    /** The text of the child's last `assistant_message`. */
+    reply: string;
+    errorMessage?: string;
+    abortedBy?: SubagentAbortedBy;
     finished: EventPayload<"subagent_finished">;
 } | null>;
 /** The parent's `subagent_finished` event for a finished child (idempotent by its key). */
 export declare const finishedEvent: (row: DispatchRow, finished: EventPayload<"subagent_finished">) => AppendEvent;
-export interface ChildDeps {
-    db: KernelDb;
-    eventLog: EventLog;
-    waits: Pick<Waits, "resume">;
-    log: Pick<Logger, "warn">;
-}
-/**
- * After a child run's terminal state committed (spec §7.3): appends `subagent_finished` to the
- * parent log (idempotent; allowed while the parent waits, it is not model-visible) and tries
- * `Waits.resume(parentRunId, childRunId)`. Every finishing child tries; the conditional resume lets
- * exactly one succeed, the last to see all its siblings terminal. A run that is not a dispatched
- * child, or not terminal yet, is left alone. A crash in between is repaired by the wait sweep and
- * by the parent's tools node, which writes a missing `subagent_finished` itself.
- */
-export declare function onChildFinished(d: ChildDeps, childRunId: string): Promise<void>;
-export interface StopChildrenDeps extends ChildDeps {
-    waits: Pick<Waits, "resume" | "abortWaiting">;
-    runQueue: Pick<RunQueue, "abortIfOrphaned">;
-    abort: Pick<RunAbort, "request">;
-}
-/**
- * Stops the active children of a parent run (sub-agents spec §12), or only those dispatched in
- * `opts.step`: a `waiting` child through its own `abortWaiting`, a `queued` / `running` one that
- * no worker holds directly (`abortIfOrphaned`), any other through `RunAbort.request` (the
- * cross-replica broadcast plus the marker key, so a child that starts later still sees it), after
- * which a child found `waiting` is stopped through `abortWaiting` too. A child stopped here is
- * reported to the parent at once (by `abortWaiting` itself, or {@link onChildFinished} after
- * `abortIfOrphaned`); one stopped by its worker is reported by that worker. Returns the number of
- * children asked to stop.
- *
- * `byAccountId` is the person whose action stops them, or null when the kernel stops them on the
- * parent's behalf; a child stopped with null reports the §4.4 "parent's stop" text.
- */
-export declare function stopChildren(d: StopChildrenDeps, parentRunId: string, byAccountId: string | null, opts?: {
-    step?: number;
-    detail?: RunAbortDetail;
-}): Promise<number>;

package/dist/runtime/subagents/child.js

@@ -1,7 +1,5 @@
 import { usageTokens } from "../../evals/budget.js";
 import { agentResultText } from "../../tools/builtins/agent.js";
-import { TERMINAL_STATUSES } from "../run-finish.js";
-import { ACTIVE_RUN_STATUSES } from "../run-queue.js";
 /** Idempotency key of the parent's `subagent_finished` event. */
 export const finishedIdemKey = (childRunId) => `subagent_finished:${childRunId}`;
 const DISPATCH_COLUMNS = [
@@ -10,6 +8,8 @@ const DISPATCH_COLUMNS = [
     "parent_conversation_id",
     "child_conversation_id",
     "child_run_id",
+    "budget_run_id",
+    "for_skill",
 ];
 const toRow = (r) => ({
     parentRunId: r.parent_run_id,
@@ -17,6 +17,8 @@ const toRow = (r) => ({
     parentConversationId: r.parent_conversation_id,
     childConversationId: r.child_conversation_id,
     childRunId: r.child_run_id,
+    budgetRunId: r.budget_run_id,
+    forSkill: r.for_skill,
 });
 /** The dispatch that started `childRunId`, or null (not a sub-agent run). */
 export async function dispatchOfChildRun(db, childRunId) {
@@ -27,6 +29,41 @@ export async function dispatchOfChildRun(db, childRunId) {
         .executeTakeFirst();
     return r ? toRow(r) : null;
 }
+/**
+ * The dispatch row a finished child run reports through (agent map spec §5.2: every run of a child
+ * conversation that ends appends one `finished` delivery to its parent): the run's own dispatch
+ * (`Agent`, `SendMessage`), else, for a run nobody dispatched (a wake run, §5.3), the newest dispatch
+ * of its conversation with `childRunId` set to this run, `forSkill` false (a wake run of a fork's
+ * child is delivered like any background run; no parent run waits on it) and the run's own budget
+ * run. Null when the run is unknown or its conversation was never dispatched.
+ */
+export async function deliveryRowOfChildRun(db, childRunId) {
+    const own = await dispatchOfChildRun(db, childRunId);
+    if (own)
+        return own;
+    const run = await db
+        .selectFrom("runs")
+        .select(["conversation_id", "budget_run_id"])
+        .where("id", "=", childRunId)
+        .executeTakeFirst();
+    if (!run)
+        return null;
+    const latest = await db
+        .selectFrom("subagent_dispatches")
+        .select(DISPATCH_COLUMNS)
+        .where("child_conversation_id", "=", run.conversation_id)
+        .orderBy("created_at", "desc")
+        .limit(1)
+        .executeTakeFirst();
+    if (!latest)
+        return null;
+    return {
+        ...toRow(latest),
+        childRunId,
+        forSkill: false,
+        ...(run.budget_run_id !== null && { budgetRunId: run.budget_run_id }),
+    };
+}
 /** The dispatch of the parent call `(runId, callId)`, or null (not dispatched yet). */
 export async function dispatchOfCall(db, runId, callId) {
     const r = await db
@@ -37,6 +74,63 @@ export async function dispatchOfCall(db, runId, callId) {
         .executeTakeFirst();
     return r ? toRow(r) : null;
 }
+/**
+ * `conversationId` and its ancestors, nearest first, ending at the root of its tree (the first
+ * conversation without a parent); just `[conversationId]` for a root or an unknown id. Walks at
+ * most 16 levels, far above `subagents.maxDepth`'s bound of 5.
+ */
+async function ancestryOf(db, conversationId) {
+    const chain = [conversationId];
+    for (let i = 0; i < 16; i++) {
+        const row = await db
+            .selectFrom("conversations")
+            .select("parent_conversation_id")
+            .where("id", "=", chain[chain.length - 1])
+            .executeTakeFirst();
+        if (!row?.parent_conversation_id)
+            return chain;
+        chain.push(row.parent_conversation_id);
+    }
+    return chain;
+}
+/**
+ * The root conversation of `conversationId`'s tree (agent map spec §6): the first ancestor without
+ * a parent, or `conversationId` itself for a root (or an unknown id).
+ */
+export async function rootConversationOf(db, conversationId) {
+    return (await ancestryOf(db, conversationId)).at(-1);
+}
+/**
+ * Where the sub-agent conversation `conversationId`, in its run `runId`, shows a request for a
+ * person (`subagent_waiting`: an approval, a question or a connect card; agent map spec §7): the
+ * **root** conversation of its tree, the only one a person looks at, with the path from the root's
+ * child down to it, under the root run that last dispatched (or messaged) the root's child on that
+ * path (for a child of the root, the run's own dispatch first). `parent`, when the caller knows the
+ * run's dispatch and it was made by the root (`depth` 0), answers without a read. Null for a root
+ * conversation, or a branch the root never dispatched.
+ */
+export async function rootSurfaceOf(db, conversationId, runId, parent) {
+    if (parent?.depth === 0) {
+        return { conversationId: parent.conversationId, runId: parent.runId, path: [conversationId] };
+    }
+    const chain = await ancestryOf(db, conversationId);
+    if (chain.length < 2)
+        return null;
+    const root = chain.at(-1);
+    const path = chain.slice(0, -1).reverse();
+    const top = path[0];
+    const own = path.length === 1 ? await dispatchOfChildRun(db, runId) : null;
+    const dispatch = own ??
+        (await db
+            .selectFrom("subagent_dispatches")
+            .select(["parent_run_id as parentRunId"])
+            .where("child_conversation_id", "=", top)
+            .where("parent_conversation_id", "=", root)
+            .orderBy("created_at", "desc")
+            .limit(1)
+            .executeTakeFirst());
+    return dispatch ? { conversationId: root, runId: dispatch.parentRunId, path } : null;
+}
 /** All events of one run of a conversation, by seq. */
 async function runEvents(eventLog, conversationId, runId) {
     const out = [];
@@ -51,18 +145,18 @@ async function runEvents(eventLog, conversationId, runId) {
     }
 }
 /**
- * The tool result of a finished child run (spec §4.4) and its `subagent_finished` payload, from
- * the child's log only: the status from its terminal event, the reply from its last
+ * The result of a finished child run (spec §4.4) and its `subagent_finished` payload, from the
+ * child's log only: the status from its terminal event, the reply from its last
  * `assistant_message` (text blocks), the tool call count from its `tool_result` events, the usage
  * from its `usage` events (compaction included) and the duration from `run_started` to the
- * terminal event. Null while the run has no terminal event.
+ * terminal event. Null while the run has no terminal event. `content` is the fork report's text
+ * (`agentResultText`); `reply`, `errorMessage` and `abortedBy` are what a background child's
+ * finished `subagent_delivery` carries.
  *
  * `modelGiven`: the parent's call named a `model`; for an org agent, which runs on its own model
  * (§5.4, §5.5), the status line then says `model: the agent's own`.
  */
-export async function childResult(eventLog, row, 
-/** `forSkill`: a fork invocation's report (no resume hint, see `agentResultText`). */
-opts = {}) {
+export async function childResult(eventLog, row, opts = {}) {
     const events = await runEvents(eventLog, row.childConversationId, row.childRunId);
     const terminal = events.find((e) => e.type === "run_finished" || e.type === "run_failed" || e.type === "run_aborted");
     if (!terminal)
@@ -123,10 +217,12 @@ opts = {}) {
         tokens: usageTokens(usage),
         ...(abortedBy !== undefined && { abortedBy }),
         ...(ownModel && { ownModel }),
-        ...(opts.forSkill === true && { noResumeHint: true }),
     });
     return {
         ...text,
+        reply,
+        ...(errorMessage !== undefined && { errorMessage }),
+        ...(abortedBy !== undefined && { abortedBy }),
         finished: {
             subagentId: row.childConversationId,
             childRunId: row.childRunId,
@@ -146,80 +242,3 @@ export const finishedEvent = (row, finished) => ({
     idemKey: finishedIdemKey(row.childRunId),
     payload: finished,
 });
-/**
- * After a child run's terminal state committed (spec §7.3): appends `subagent_finished` to the
- * parent log (idempotent; allowed while the parent waits, it is not model-visible) and tries
- * `Waits.resume(parentRunId, childRunId)`. Every finishing child tries; the conditional resume lets
- * exactly one succeed, the last to see all its siblings terminal. A run that is not a dispatched
- * child, or not terminal yet, is left alone. A crash in between is repaired by the wait sweep and
- * by the parent's tools node, which writes a missing `subagent_finished` itself.
- */
-export async function onChildFinished(d, childRunId) {
-    const row = await dispatchOfChildRun(d.db, childRunId);
-    if (!row)
-        return;
-    const run = await d.db
-        .selectFrom("runs")
-        .select("status")
-        .where("id", "=", childRunId)
-        .executeTakeFirst();
-    if (!run || !TERMINAL_STATUSES.has(run.status))
-        return;
-    const r = await childResult(d.eventLog, row);
-    if (!r) {
-        d.log.warn("sub-agent run is terminal without a terminal event", { childRunId });
-        return;
-    }
-    await d.eventLog.append(row.parentConversationId, [finishedEvent(row, r.finished)]);
-    await d.waits.resume(row.parentRunId, childRunId);
-}
-/**
- * Stops the active children of a parent run (sub-agents spec §12), or only those dispatched in
- * `opts.step`: a `waiting` child through its own `abortWaiting`, a `queued` / `running` one that
- * no worker holds directly (`abortIfOrphaned`), any other through `RunAbort.request` (the
- * cross-replica broadcast plus the marker key, so a child that starts later still sees it), after
- * which a child found `waiting` is stopped through `abortWaiting` too. A child stopped here is
- * reported to the parent at once (by `abortWaiting` itself, or {@link onChildFinished} after
- * `abortIfOrphaned`); one stopped by its worker is reported by that worker. Returns the number of
- * children asked to stop.
- *
- * `byAccountId` is the person whose action stops them, or null when the kernel stops them on the
- * parent's behalf; a child stopped with null reports the §4.4 "parent's stop" text.
- */
-export async function stopChildren(d, parentRunId, byAccountId, opts = {}) {
-    let q = d.db
-        .selectFrom("subagent_dispatches as sd")
-        .innerJoin("runs as cr", "cr.id", "sd.child_run_id")
-        .select(["sd.child_conversation_id", "sd.child_run_id", "cr.status"])
-        .where("sd.parent_run_id", "=", parentRunId)
-        .where("cr.status", "in", ACTIVE_RUN_STATUSES);
-    if (opts.step !== undefined)
-        q = q.where("sd.step", "=", opts.step);
-    const children = await q.execute();
-    for (const c of children) {
-        const conv = c.child_conversation_id;
-        const runId = c.child_run_id;
-        // abortWaiting reports the stopped child to the parent itself (Waits.subagents.finished)
-        if (c.status === "waiting" &&
-            (await d.waits.abortWaiting(conv, runId, byAccountId, opts.detail))) {
-            continue;
-        }
-        if (await d.runQueue.abortIfOrphaned(conv, runId, byAccountId, opts.detail)) {
-            await onChildFinished(d, runId);
-            continue;
-        }
-        await d.abort.request(runId, byAccountId, opts.detail);
-        // the suspend handshake (see Waits.suspend): a child that became `waiting` after the read
-        // above may have checked the marker before it was set, so check `waiting` again after setting
-        // it (review M1)
-        const now = await d.db
-            .selectFrom("runs")
-            .select("status")
-            .where("id", "=", runId)
-            .executeTakeFirst();
-        if (now?.status === "waiting") {
-            await d.waits.abortWaiting(conv, runId, byAccountId, opts.detail);
-        }
-    }
-    return children.length;
-}

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

@@ -1,16 +1,12 @@
 import { type AgentTemplateTier } from "@capybara-hq/plugin-sdk";
-import type { AgentDefinition, AgentToolRef, ModelRef } from "../../agents/definition.js";
-import type { KernelConfig } from "../../config/schema.js";
+import { type AgentDefinition, type DisabledToolRef, type ModelRef } from "../../agents/definition.js";
 import type { EventPayload } from "../../conversations/events.js";
-import type { KernelDb } from "../../db/kernel-schema.js";
+import type { KernelSchemaDb } from "../../db/kernel-schema.js";
+import type { KernelConfigService } from "../../infra/config/kernel-config.service.js";
 import type { ModelPurposesService } from "../../models/purposes.js";
 import type { ProviderRegistry } from "../providers.js";
 import type { RosterEntry } from "./roster.js";
-/**
- * Tools a sub-agent never gets (spec §5.3, §5.5): `agent` (depth 1), `ask_user` (the person does not
- * see the child), `sandbox_deliver` (delivering files is the parent's job) and `skill_write`.
- */
-export declare const CHILD_REMOVED_TOOLS: readonly ["agent", "ask_user", "sandbox_deliver", "skill_write"];
+export { CHILD_REMOVED_TOOLS } from "../../tools/builtin-names.js";
 /**
  * The roster entry's template is gone (an inline template edited away, a plugin template
  * uninstalled) between resolving the roster and reading it. The dispatch refuses the call as an
@@ -29,11 +25,11 @@ export interface EffectiveDefinition {
     warnings: string[];
 }
 export interface EffectiveDefinitionDeps {
-    db: KernelDb;
+    db: KernelSchemaDb;
     purposes: Pick<ModelPurposesService, "resolve">;
     /** Reads the resolved model's parameter declarations (a template `effort`). */
     registry: Pick<ProviderRegistry, "resolve">;
-    config: () => KernelConfig;
+    config: Pick<KernelConfigService, "get">;
 }
 type Policy = "ask" | "deny";
 /**
@@ -46,6 +42,13 @@ export interface CheckedOrgAgent {
     version: number;
     definition: AgentDefinition;
 }
+/** Where a new child sits (agent map spec §6): its depth below the root and the tree's limit. */
+export interface ChildDepth {
+    /** The child's depth: 1 for a child of a root conversation. */
+    childDepth: number;
+    /** `subagents.maxDepth` for the organization; a child at it never gets `Agent`. */
+    maxDepth: number;
+}
 /**
  * The effective definition of a sub-agent at its first dispatch (spec §5.3–§5.5):
  * - `general` / `inline` / `plugin`: the parent's definition narrowed by the template (tools by
@@ -56,10 +59,12 @@ export interface CheckedOrgAgent {
  *   (`tierFallback`); a template `effort` is set when the resolved model declares it;
  * - `agent`: the org agent's version that passed the gates (`orgAgent`, from {@link checkOrgAgent}),
  *   its own tools minus the child-removed ones, its policies with the parent's on top (stricter
- *   wins), its skills and model; `tier` ignored.
- * The `subagents` block is never part of a child's definition (depth 1).
+ *   wins), its skills, model and `subagents` block; `tier` ignored.
+ * Nesting (agent map spec §4.1): `Agent` stays unless the child is at `maxDepth`; the frozen
+ * definition keeps a `subagents` block, the roster the child dispatches from: an org agent's own,
+ * otherwise the parent definition's (a general-purpose, inline or plugin child inherits it).
  */
-export declare function effectiveDefinition(d: EffectiveDefinitionDeps, a: {
+export declare function effectiveDefinition(d: EffectiveDefinitionDeps, a: ChildDepth & {
     orgId: string;
     parent: AgentDefinition;
     parentAgentId: string;
@@ -72,32 +77,31 @@ export declare function effectiveDefinition(d: EffectiveDefinitionDeps, a: {
     tierFallback: boolean;
 }>;
 /**
- * What a follow-up (`resume`) may still use (final review I1, spec §5.3): the frozen tools and
- * org skills intersected with the current version they come from. Recorded on the follow-up's
- * task message (`user_message.dispatch.narrowed`), so the run and its replay read it from the log.
+ * What a follow-up (`resume`) may still use (final review I1, spec §5.3): the frozen definition's
+ * turned-off tools together with the current version's (it can lose tools, never gain them), and
+ * the frozen org skills intersected with the current ones. Recorded on the follow-up's task message
+ * (`user_message.dispatch.narrowed`), so the run and its replay read it from the log.
  */
 export interface FollowUpNarrowing {
-    tools: AgentToolRef[];
+    /** Absent in logs from before tools were on by default (no tool narrowing then). */
+    disabledTools?: DisabledToolRef[] | undefined;
     skills?: {
         orgSkills: string[];
         pinned?: string[] | undefined;
     } | undefined;
 }
-/**
- * The refs of `frozen` that `current` still has: a builtin or plugin tool by name, a connector by
- * id; a connector's `all` meets the other side's names (`all` on both stays `all`), and a
- * connector left with no names is dropped. Pure: a connector `current` lists is not looked up.
- */
-export declare function intersectTools(frozen: readonly AgentToolRef[], current: readonly AgentToolRef[]): AgentToolRef[];
 /**
  * The narrowing of a follow-up (final review I1): `frozen` (the child's `subagent_started`
  * definition) against `current`, the definition a fresh dispatch would read now: the dispatching
  * parent run's version for `general` / inline / plugin children, the dispatched org agent's
  * current version for an org agent child (whose tools are its own at dispatch too, §5.5). Its
- * `orgSkills` keep only those `current` still selects; a pinned id that was one of the frozen org
- * skills goes with it (the agent's own skills stay).
+ * `disabledTools` are both lists together; its `orgSkills` keep only those `current` still
+ * selects; a pinned id that was one of the frozen org skills goes with it (the agent's own skills
+ * stay).
+ */
+export declare function narrowFollowUp(frozen: Pick<AgentDefinition, "disabledTools" | "skills">, current: Pick<AgentDefinition, "disabledTools" | "skills">): FollowUpNarrowing;
+/**
+ * The definition a child run uses: the frozen one with its trigger's follow-up narrowing. A
+ * narrowing logged before tools were on by default (no `disabledTools`) narrows only skills.
  */
-export declare function narrowFollowUp(frozen: Pick<AgentDefinition, "tools" | "skills">, current: Pick<AgentDefinition, "tools" | "skills">): FollowUpNarrowing;
-/** The definition a child run uses: the frozen one with its trigger's follow-up narrowing. */
 export declare function childRunDefinition(frozen: AgentDefinition, narrowed: FollowUpNarrowing | undefined): AgentDefinition;
-export {};