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

package/dist/runtime/stream.controller.js

@@ -9,15 +9,18 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { Controller, Get, Headers, Inject, Param, Req, Res } from "@nestjs/common";
 import { z } from "zod";
+import { ConversationAccess } from "../conversations/access.js";
 import { ConversationsService } from "../conversations/conversations.service.js";
 import { ApiError } from "../errors.js";
 import { ApiTokenService } from "../identity/api-tokens.js";
 import { credentialCheck } from "../identity/credential-check.js";
 import { CurrentPrincipal, requireUser } from "../identity/principal.js";
 import { SessionService } from "../identity/sessions.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { createZodDto } from "../infra/validation/create-zod-dto.js";
-import { ZQuery } from "../infra/validation/zod-params.js";
+import { ZParam, ZQuery } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { RunDrafts } from "./run-drafts.js";
 import { ConversationStreams } from "./stream.js";
 const BEARER_RE = /^Bearer\s+(\S+)$/i;
 const StreamQuery = z.object({
@@ -32,12 +35,20 @@ function parseLastEventId(v) {
     }
     return n;
 }
+const DraftParams = z.object({
+    id: z.string().min(1).max(100),
+    runId: z.string().min(1).max(100),
+});
 class ConversationStreamQueryDto extends createZodDto(StreamQuery, "ConversationStreamQuery") {
 }
+class RunDraftParamsDto extends createZodDto(DraftParams, "RunDraftParams") {
+}
 /**
  * 会话事件流（SSE）：`GET /api/v1/orgs/:orgId/conversations/:id/stream?after=<seq>`，`agents.use`，只有会话所有者可用。
  * - 打开时不阻塞地调用一次 ensureRun（`ConversationsService.kickRun`），停在「运行中」的孤儿运行由此被清理；
  * - 先订阅会话频道、再回放 `after`（或优先的 `Last-Event-ID`）之后的事件：`id: <seq>` / `event: event`；
+ * - after that catch-up, one `event: draft` (`data: {"runId","step","text","thinking"}`) per step of
+ *   the running run whose `assistant_message` is not logged (live drafts, spec 2026-11-07 §3.2);
  *   之后收到 `events` 通知就补读新事件（按 seq 去重），收到增量就发 `event: delta`，收到界面刷新
  *   （插件 `ctx.ui.invalidate`）就发 `event: ui`（`data: {"plugin","contribution"}`）；
  * - 每 `runtime.sseHeartbeatMs` 发 `: ping` 注释；每 `runtime.sseRecheckMs` 复核凭据（会话未吊销 / 令牌仍有效，
@@ -50,11 +61,47 @@ let ConversationStreamController = class ConversationStreamController {
     sessions;
     tokens;
     conversations;
-    constructor(streams, sessions, tokens, conversations) {
+    access;
+    drafts;
+    log;
+    constructor(streams, sessions, tokens, conversations, access, drafts, log) {
         this.streams = streams;
         this.sessions = sessions;
         this.tokens = tokens;
         this.conversations = conversations;
+        this.access = access;
+        this.drafts = drafts;
+        this.log = log;
+    }
+    /**
+     * The live drafts of one run (spec 2026-11-07 §3.2): `{ drafts: { step, text, thinking }[] }`,
+     * the steps still streaming whose `assistant_message` is not logged (none once the run is no
+     * longer running). What a stream client asks for when a delta's `offset` is past its draft.
+     * The stream's access rule (the conversation is visible to the viewer, else 404
+     * `conversation.not_found`); a run not of this conversation → 404 `run.not_found`.
+     */
+    async draft(principal, org, params) {
+        const p = requireUser(principal);
+        if (!(await this.access.isAccessible(org.orgId, params.id, p.account.id))) {
+            throw new ApiError("conversation.not_found", "Conversation not found");
+        }
+        if (!(await this.drafts.runOf(params.id, params.runId))) {
+            throw new ApiError("run.not_found", "Run not found");
+        }
+        let live;
+        try {
+            live = await this.drafts.live(params.id, params.runId);
+        }
+        catch (err) {
+            // a convenience, like the stream's: no drafts rather than an error (the log stays the truth)
+            this.log.warn("cannot read live drafts", {
+                conversationId: params.id,
+                runId: params.runId,
+                err,
+            });
+            live = [];
+        }
+        return { drafts: live.map(({ step, text, thinking }) => ({ step, text, thinking })) };
     }
     async stream(principal, org, id, q, lastEventId, req, reply) {
         const p = requireUser(principal);
@@ -103,6 +150,13 @@ let ConversationStreamController = class ConversationStreamController {
         handle.begin();
     }
 };
+__decorate([
+    Get(":id/runs/:runId/draft"),
+    OrgAction("agents.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(RunDraftParamsDto))
+], ConversationStreamController.prototype, "draft", null);
 __decorate([
     Get(":id/stream"),
     OrgAction("agents.use"),
@@ -119,6 +173,9 @@ ConversationStreamController = __decorate([
     __param(0, Inject(ConversationStreams)),
     __param(1, Inject(SessionService)),
     __param(2, Inject(ApiTokenService)),
-    __param(3, Inject(ConversationsService))
+    __param(3, Inject(ConversationsService)),
+    __param(4, Inject(ConversationAccess)),
+    __param(5, Inject(RunDrafts)),
+    __param(6, Inject(KERNEL_LOGGER))
 ], ConversationStreamController);
 export { ConversationStreamController };

package/dist/runtime/stream.d.ts

@@ -4,6 +4,7 @@ import { EventLog } from "../conversations/event-log.js";
 import type { CredentialCheck } from "../identity/credential-check.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { GracefulShutdown } from "../infra/lifecycle/graceful-shutdown.service.js";
+import { type LiveDraft, RunDrafts } from "./run-drafts.js";
 /** 一次 SSE 连接的输出端（由 HTTP 层包装原始响应）。 */
 export interface SseOutput {
     write(chunk: string): void;
@@ -25,6 +26,8 @@ export interface ConversationStreamsDeps {
     access(orgId: string, conversationId: string, viewerAccountId: string): Promise<boolean>;
     config: Pick<KernelConfigService, "get">;
     log: Pick<Logger, "warn">;
+    /** The live drafts of the conversation's running run (sent once, after the open catch-up). */
+    drafts(conversationId: string): Promise<LiveDraft[]>;
 }
 export interface StreamParams {
     orgId: string;
@@ -60,7 +63,7 @@ export declare class ConversationStreams {
      * an event stream. Without `GracefulShutdown` (a standalone HTTP application, tests only) the
      * streams end with their connections.
      */
-    constructor(eventLog: Pick<EventLog, "readAfter">, bus: StreamBus, access: Pick<ConversationAccess, "isAccessible">, config: Pick<KernelConfigService, "get">, log: Pick<Logger, "warn">, shutdown?: Pick<GracefulShutdown, "signal">);
+    constructor(eventLog: Pick<EventLog, "readAfter">, bus: StreamBus, access: Pick<ConversationAccess, "isAccessible">, config: Pick<KernelConfigService, "get">, log: Pick<Logger, "warn">, drafts: Pick<RunDrafts, "live">, shutdown?: Pick<GracefulShutdown, "signal">);
     /**
      * 复核凭据与可见性，并先订阅会话频道（之后再回放，避免遗漏两者之间提交的事件）。
      * 凭据失效 → 对应的 `auth.*`；不可见 → `conversation.not_found`；订阅失败照常抛出。此时尚未写任何响应，调用方可以按普通错误返回。

package/dist/runtime/stream.js

@@ -15,6 +15,7 @@ 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 重连补读。 */
@@ -55,6 +56,7 @@ 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>`）流动，进程内只保存连接本身的资源
@@ -71,13 +73,14 @@ let ConversationStreams = class ConversationStreams {
      * an event stream. Without `GracefulShutdown` (a standalone HTTP application, tests only) the
      * streams end with their connections.
      */
-    constructor(eventLog, bus, access, config, log, shutdown) {
+    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();
@@ -131,8 +134,9 @@ ConversationStreams = __decorate([
     __param(2, Inject(ConversationAccess)),
     __param(3, Inject(KernelConfigService)),
     __param(4, Inject(KERNEL_LOGGER)),
-    __param(5, Optional()),
-    __param(5, Inject(GracefulShutdown))
+    __param(5, Inject(RunDrafts)),
+    __param(6, Optional()),
+    __param(6, Inject(GracefulShutdown))
 ], ConversationStreams);
 export { ConversationStreams };
 /**
@@ -176,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));
@@ -282,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,6 +1,7 @@
 import type { AppendEvent, EventLog } from "../../conversations/event-log.js";
 import type { EventPayload } from "../../conversations/events.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. */
@@ -10,29 +11,76 @@ 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: 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: KernelSchemaDb, runId: string, callId: string): Promise<DispatchRow | 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 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 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). */

package/dist/runtime/subagents/child.js

@@ -8,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,
@@ -15,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) {
@@ -25,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
@@ -35,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 = [];
@@ -49,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)
@@ -121,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,

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 AgentDefinition, type DisabledToolRef, type ModelRef } from "../../agents/definition.js";
 import type { EventPayload } from "../../conversations/events.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
@@ -38,14 +34,22 @@ export interface EffectiveDefinitionDeps {
 type Policy = "ask" | "deny";
 /**
  * `base` with `over` applied on top, the stricter value winning per key (`deny` > `ask`). Values
- * other than `ask` / `deny` (stored template data is not re-validated) are skipped on both sides.
+ * other than `ask` / `deny` (stored template data is not re-validated; an agent's connector-tool
+ * `allow`, which the policy check reads from the agent's current version) are skipped on both sides.
  */
-export declare function stricterPolicies(base: Record<string, Policy>, over: Record<string, Policy>): Record<string, Policy>;
+export declare function stricterPolicies(base: Record<string, string>, over: Record<string, string>): Record<string, Policy>;
 /** An org agent's version and definition as checked by its gates. */
 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 +60,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 +78,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 {};