@capybara-hq/kernel 0.1.0-rc.4 → 0.1.0-rc.5

package/dist/runtime/run-worker.js

@@ -10,7 +10,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 import { Inject, Injectable, Optional } from "@nestjs/common";
 import { DelayedError } from "bullmq";
 import { sql } from "kysely";
-import { conversationTopic, EventLog, } from "../conversations/event-log.js";
+import { EventLog } from "../conversations/event-log.js";
 import { isAbsorbable, } from "../conversations/events.js";
 import { effectiveDefinition, NO_SELECTION, readSelection, sameModel, sameSelection, } from "../conversations/selection.js";
 import { TitleQueue } from "../conversations/titles.js";
@@ -32,10 +32,11 @@ import { ConversationLock } from "./conversation-lock.js";
 import { RunError } from "./model-call.js";
 import { ProviderListError, ProviderRegistry } from "./providers.js";
 import { ORG_QUOTA_LEASE_MS, orgRunLimit, RUN_QUOTA } from "./quota.js";
+import { RunDrafts, streamSink } from "./run-drafts.js";
 import { RunFinish, TERMINAL_STATUSES } from "./run-finish.js";
 import { RunQueue } from "./run-queue.js";
 import { AgentLoops, RunSteps } from "./run-steps.js";
-import { dispatchOfChildRun } from "./subagents/child.js";
+import { dispatchOfChildRun, rootConversationOf } from "./subagents/child.js";
 import { childRunDefinition } from "./subagents/definition.js";
 import { forkBoundary } from "./subagents/skill-fork.js";
 import { Waits } from "./waits.js";
@@ -86,6 +87,7 @@ let RunWorker = class RunWorker {
     pipeline;
     finisher;
     txHost;
+    drafts;
     hooks;
     /** The two run queues' BullMQ workers (spec §7.4), once {@link start}ed on the worker role. */
     workers = [];
@@ -114,7 +116,9 @@ let RunWorker = class RunWorker {
      * (`stopOpenAgentCalls`; a no-op without dispatches); `fire` runs their observe hooks after the
      * commit (sub-agents spec §12, review m1: a failed or stalled parent too).
      */
-    pipeline, finisher, txHost, hooks) {
+    pipeline, finisher, txHost, 
+    /** The steps' live drafts this process writes for the runs it executes. */
+    drafts, hooks) {
         this.kdb = kdb;
         this.eventLog = eventLog;
         this.lock = lock;
@@ -134,6 +138,7 @@ let RunWorker = class RunWorker {
         this.pipeline = pipeline;
         this.finisher = finisher;
         this.txHost = txHost;
+        this.drafts = drafts;
         this.hooks = hooks;
         this.loop = loops.create(steps.deps);
     }
@@ -178,35 +183,16 @@ let RunWorker = class RunWorker {
         }
     }
     /**
-     * 流式增量发布到会话频道（与 `{ kind: "events" }` 共用 `conv.<id>`），任意副本上的订阅方都能收到。
-     * 发布失败只记日志：增量只是草稿，最终内容以日志中的 assistant_message 为准。
+     * The run's stream sink: deltas on the conversation's topic (any replica's subscribers get them)
+     * and the steps' live drafts in Redis ({@link streamSink}, spec 2026-11-07 §3.2).
      */
     sinkFor(conversationId) {
-        // 本次运行执行中推出的文本字符数（按步，step_reset 清零）：本进程正在执行的这次运行自己的计数
-        let at = { runId: "", step: -1, chars: 0 };
-        return (d) => {
-            if (at.runId !== d.runId || at.step !== d.step || d.kind === "step_reset") {
-                at = { runId: d.runId, step: d.step, chars: 0 };
-            }
-            const offset = at.chars;
-            if (d.kind === "text")
-                at.chars += d.text?.length ?? 0;
-            const msg = {
-                kind: "delta",
-                runId: d.runId,
-                step: d.step,
-                delta: d.kind,
-                ...(d.text !== undefined && { text: d.text }),
-                ...(d.kind === "text" && { offset }),
-            };
-            this.bus
-                .publish(conversationTopic(conversationId), msg)
-                .catch((err) => this.log.warn("stream delta publish failed", { conversationId, err }));
-        };
+        return streamSink(conversationId, { bus: this.bus, drafts: this.drafts, log: this.log });
     }
     /**
      * After any terminal commit of a run that is not a sub-agent's (sub-agents spec §12): stops its
-     * active children on its behalf (no account). The wait sweep is the backstop.
+     * active fork invocation child on its behalf (no account); background `Agent` children keep
+     * running (agent map spec §5.4). The wait sweep is the backstop.
      */
     async stopChildren(runId) {
         try {
@@ -228,6 +214,14 @@ let RunWorker = class RunWorker {
         catch (err) {
             this.log.error("cannot report finished sub-agent run to its parent", { runId, err });
         }
+        // a sub-agent a person stopped stops its descendants too, also one it dispatched after the
+        // tree stop read the tree (agent map spec §6); any other end leaves them running
+        try {
+            await this.waits.stopDescendantsOfStopped(runId);
+        }
+        catch (err) {
+            this.log.error("cannot stop the descendants of a stopped sub-agent", { runId, err });
+        }
     }
     /**
      * 任务结束后的 ensureRun，失败按 {@link ENSURE_RETRY_DELAYS_MS} 退避重试；停机开始后不再等待间隔
@@ -369,6 +363,7 @@ let RunWorker = class RunWorker {
             "trigger_seq",
             "started_at",
             "waited_ms",
+            "budget_run_id",
         ])
             .where("id", "=", runId)
             .executeTakeFirst();
@@ -386,7 +381,7 @@ let RunWorker = class RunWorker {
             return;
         const conv = await this.db
             .selectFrom("conversations")
-            .select(["org_id", "agent_id", "kind"])
+            .select(["org_id", "agent_id", "kind", "subagent_depth"])
             .where("id", "=", conversationId)
             .executeTakeFirst();
         if (!conv)
@@ -532,18 +527,36 @@ let RunWorker = class RunWorker {
             maxSteps = Math.min(started.payload.maxSteps, runtime.maxSteps);
             const row = await dispatchOfChildRun(this.db, runId);
             const otherAgent = started.payload.template.source === "agent";
+            const parentConversationId = row?.parentConversationId ?? started.payload.parent.conversationId;
+            // a sub-agent conversation is at depth 1 at least: one written before depths were recorded
+            // (default 0) was a child of a root
+            const depth = Math.max(conv.subagent_depth, 1) - 1;
+            const rootConversationId = depth === 0
+                ? parentConversationId
+                : await rootConversationOf(this.db, parentConversationId);
+            // the tree's budget window of THIS run (agent map spec §6): its own `budget_run_id`, set when
+            // it was created (a dispatch, or a wake run from the root's current window), else its
+            // dispatch's; never derived from the parent run, which for a wake run is the first dispatch's
+            const budgetRunId = run.budget_run_id ?? row?.budgetRunId;
             parent = row
                 ? {
                     conversationId: row.parentConversationId,
                     runId: row.parentRunId,
                     callId: row.parentCallId,
+                    depth,
+                    rootConversationId,
                     otherAgent,
+                    ...(budgetRunId !== undefined && { budgetRunId }),
+                    ...(row.forSkill === true && { forSkill: true }),
                 }
                 : {
                     conversationId: started.payload.parent.conversationId,
                     runId: started.payload.parent.runId,
                     callId: started.payload.parent.callId,
+                    depth,
+                    rootConversationId,
                     otherAgent,
+                    ...(budgetRunId !== undefined && { budgetRunId }),
                 };
         }
         else {
@@ -703,6 +716,10 @@ let RunWorker = class RunWorker {
                 });
                 return "finished";
             }
+            finally {
+                // the execution here ended: what this process held of the run's drafts goes
+                this.drafts.release(runId);
+            }
             if (state.abandoned)
                 return "abandoned";
             // 锁在运行中丢失：无论 loop 返回什么都不写终态，任务回到队列由持锁者续跑。
@@ -816,7 +833,8 @@ let RunWorker = class RunWorker {
         const agent = saved !== undefined
             ? effectiveDefinition(saved, await readSelection(t, conversationId))
             : current;
-        // a wake run's boundary is a finished background task, not a message (background Bash §3)
+        // a wake run's boundary is a finished background task (background Bash §3) or a sub-agent's
+        // delivery (agent map spec §5.3), not a message
         const boundary = await t
             .selectFrom("conversation_events")
             .select("type")
@@ -836,6 +854,10 @@ let RunWorker = class RunWorker {
                         trigger: "background_task",
                         triggerSeq: Number(run.trigger_seq),
                     }),
+                    ...(boundary?.type === "subagent_delivery" && {
+                        trigger: "subagent",
+                        triggerSeq: Number(run.trigger_seq),
+                    }),
                 },
             },
         ]);
@@ -927,7 +949,8 @@ RunWorker = __decorate([
     __param(18, Inject(ToolPipeline)),
     __param(19, Inject(RunFinish)),
     __param(20, Inject(TransactionHost)),
-    __param(21, Optional()),
-    __param(21, Inject(RUN_HOOKS))
+    __param(21, Inject(RunDrafts)),
+    __param(22, Optional()),
+    __param(22, Inject(RUN_HOOKS))
 ], RunWorker);
 export { RunWorker };

package/dist/runtime/runtime.module.js

@@ -25,6 +25,7 @@ import { MAINTENANCE_QUEUE_NAME } from "./maintenance-queue.js";
 import { ProvidersModule } from "./providers.js";
 import { EVAL_QUOTA, EVAL_QUOTA_PREFIX, OrgQuota, RUN_QUOTA, RUN_QUOTA_PREFIX } from "./quota.js";
 import { RunControl } from "./run-control.js";
+import { RunDrafts } from "./run-drafts.js";
 import { RunFinish } from "./run-finish.js";
 import { RunJobsModule } from "./run-jobs.js";
 import { RunQueue } from "./run-queue.js";
@@ -75,6 +76,7 @@ RuntimeModule = __decorate([
             Waits,
             DecisionResumer,
             RunControl,
+            RunDrafts,
             AgentLoops,
             RunSteps,
             RunWorker,
@@ -102,6 +104,7 @@ RuntimeModule = __decorate([
             RunQueue,
             Waits,
             RunControl,
+            RunDrafts,
             AgentLoops,
             RunSteps,
             RunWorker,

package/dist/runtime/step-log.d.ts

@@ -19,11 +19,16 @@ export declare class StepLog {
     constructor(kdb: KernelDb, eventLog: EventLog, txHost: TransactionHost);
     /**
      * Appends events of a sub-agent's run and adds the tokens of the usage events it newly wrote to
-     * the parent run's `subagent_tokens_used` (sub-agents spec §8.3): a usage event already in the
-     * log (an idempotent hit after a crash) adds nothing, so each call counts exactly once. Returns
-     * what was written (hits included) and the highest new seq (null: nothing new).
+     * the `subagent_tokens_used` of the tree's budget run (sub-agents spec §8.3, agent map spec §6:
+     * the whole tree counts on one run): `counter.budgetRunId`, the run's own window
+     * (`SubagentParent.budgetRunId`), else the parent run's ({@link budgetRunOf}). A usage event
+     * already in the log (an idempotent hit after a crash) adds nothing, so each call counts exactly
+     * once. Returns what was written (hits included) and the highest new seq (null: nothing new).
      */
-    appendCounted(conversationId: string, parentRunId: string, events: AppendEvent[]): Promise<{
+    appendCounted(conversationId: string, counter: {
+        parentRunId: string;
+        budgetRunId?: string | undefined;
+    }, events: AppendEvent[]): Promise<{
         written: ConversationEvent[];
         toSeq: number | null;
     }>;

package/dist/runtime/step-log.js

@@ -16,6 +16,7 @@ import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import { Transactional } from "../infra/database/transactional.decorator.js";
 import { recordToolSpecs } from "../tools/specs.js";
+import { budgetRunOf } from "./subagents/limits.js";
 /**
  * The writes of a run step that go to the event log together with another row, each in a
  * transaction of its own (the caller notifies the log after the commit): a model call with the
@@ -33,11 +34,13 @@ let StepLog = class StepLog {
     }
     /**
      * Appends events of a sub-agent's run and adds the tokens of the usage events it newly wrote to
-     * the parent run's `subagent_tokens_used` (sub-agents spec §8.3): a usage event already in the
-     * log (an idempotent hit after a crash) adds nothing, so each call counts exactly once. Returns
-     * what was written (hits included) and the highest new seq (null: nothing new).
+     * the `subagent_tokens_used` of the tree's budget run (sub-agents spec §8.3, agent map spec §6:
+     * the whole tree counts on one run): `counter.budgetRunId`, the run's own window
+     * (`SubagentParent.budgetRunId`), else the parent run's ({@link budgetRunOf}). A usage event
+     * already in the log (an idempotent hit after a crash) adds nothing, so each call counts exactly
+     * once. Returns what was written (hits included) and the highest new seq (null: nothing new).
      */
-    async appendCounted(conversationId, parentRunId, events) {
+    async appendCounted(conversationId, counter, events) {
         const t = this.kdb.db;
         // the conversation row lock the append takes anyway, taken first to read the seq before it
         const before = await t
@@ -56,7 +59,7 @@ let StepLog = class StepLog {
             await t
                 .updateTable("runs")
                 .set({ subagent_tokens_used: sql `subagent_tokens_used + ${tokens}` })
-                .where("id", "=", parentRunId)
+                .where("id", "=", counter.budgetRunId ?? (await budgetRunOf(t, counter.parentRunId)))
                 .execute();
         }
         return { written, toSeq: fresh.length > 0 ? Math.max(...fresh.map((e) => e.seq)) : null };

package/dist/runtime/stream.controller.d.ts

@@ -1,18 +1,27 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
 import type { FastifyReply, FastifyRequest } from "fastify";
 import { z } from "zod";
+import { ConversationAccess } from "../conversations/access.js";
 import { ConversationsService } from "../conversations/conversations.service.js";
 import { ApiTokenService } from "../identity/api-tokens.js";
 import { type Principal } from "../identity/principal.js";
 import { SessionService } from "../identity/sessions.js";
 import { type OrgContext } from "../orgs/org.guard.js";
+import { type RunDraft, RunDrafts } from "./run-drafts.js";
 import { ConversationStreams } from "./stream.js";
 declare const StreamQuery: z.ZodObject<{
     after: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
 }, z.core.$strip>;
+declare const DraftParams: z.ZodObject<{
+    id: z.ZodString;
+    runId: z.ZodString;
+}, z.core.$strip>;
 /**
  * 会话事件流（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` 复核凭据（会话未吊销 / 令牌仍有效，
@@ -25,7 +34,20 @@ export declare class ConversationStreamController {
     private readonly sessions;
     private readonly tokens;
     private readonly conversations;
-    constructor(streams: ConversationStreams, sessions: SessionService, tokens: ApiTokenService, conversations: ConversationsService);
+    private readonly access;
+    private readonly drafts;
+    private readonly log;
+    constructor(streams: ConversationStreams, sessions: SessionService, tokens: ApiTokenService, conversations: ConversationsService, access: ConversationAccess, drafts: RunDrafts, log: Pick<Logger, "warn">);
+    /**
+     * 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`.
+     */
+    draft(principal: Principal, org: OrgContext, params: z.infer<typeof DraftParams>): Promise<{
+        drafts: RunDraft[];
+    }>;
     stream(principal: Principal, org: OrgContext, id: string, q: z.infer<typeof StreamQuery>, lastEventId: string | undefined, req: FastifyRequest, reply: FastifyReply): Promise<void>;
 }
 export {};

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). */