@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.0

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

@@ -0,0 +1,34 @@
+import { type OnModuleDestroy } from "@nestjs/common";
+import type { FastifyReply, FastifyRequest } from "fastify";
+import { z } from "zod";
+import type { ConversationsService } from "../conversations/conversations.service.js";
+import type { ApiTokenService } from "../identity/api-tokens.js";
+import { type Principal } from "../identity/principal.js";
+import type { SessionService } from "../identity/sessions.js";
+import { type OrgContext } from "../orgs/org.guard.js";
+import type { ConversationStreams } from "./stream.js";
+declare const StreamQuery: z.ZodObject<{
+    after: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, 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`；
+ *   之后收到 `events` 通知就补读新事件（按 seq 去重），收到增量就发 `event: delta`，收到界面刷新
+ *   （插件 `ctx.ui.invalidate`）就发 `event: ui`（`data: {"plugin","contribution"}`）；
+ * - 每 `runtime.sseHeartbeatMs` 发 `: ping` 注释；每 `runtime.sseRecheckMs` 复核凭据（会话未吊销 / 令牌仍有效，
+ *   access token 到期本身不算失效）与可见性，失败时发 `event: error`（`data: {"code"}`）后关闭流；
+ * - 用 `@Res()` + `reply.hijack()` 直接写原始响应，绕开 Nest / Fastify 的响应处理与缓冲。
+ *   代理（Web 层）需透传 `x-accel-buffering: no`、`cache-control: no-cache`。
+ */
+export declare class ConversationStreamController implements OnModuleDestroy {
+    private readonly streams;
+    private readonly sessions;
+    private readonly tokens;
+    private readonly conversations;
+    constructor(streams: ConversationStreams, sessions: SessionService, tokens: ApiTokenService, conversations: ConversationsService);
+    stream(principal: Principal, org: OrgContext, id: string, q: z.infer<typeof StreamQuery>, lastEventId: string | undefined, req: FastifyRequest, reply: FastifyReply): Promise<void>;
+    /** 停机：关闭本进程的全部流，否则 HTTP 关闭要等到这些长连接超时。 */
+    onModuleDestroy(): void;
+}
+export {};

package/dist/runtime/stream.controller.js

@@ -0,0 +1,122 @@
+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 { Controller, Get, Headers, Inject, Param, Query, Req, Res, } from "@nestjs/common";
+import { z } from "zod";
+import { ApiError } from "../errors.js";
+import { API_TOKENS, CONVERSATION_STREAMS, CONVERSATIONS, SESSIONS } from "../http/tokens.js";
+import { ZodPipe } from "../http/zod.pipe.js";
+import { credentialCheck } from "../identity/credential-check.js";
+import { CurrentPrincipal, requireUser } from "../identity/principal.js";
+import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+const BEARER_RE = /^Bearer\s+(\S+)$/i;
+const StreamQuery = z.object({
+    after: z.coerce.number().int().min(0).max(Number.MAX_SAFE_INTEGER).default(0),
+});
+/** `Last-Event-ID`：非负整数（客户端回传的最后一条事件 seq）。 */
+function parseLastEventId(v) {
+    const t = v.trim();
+    const n = Number(t);
+    if (!/^\d+$/.test(t) || !Number.isSafeInteger(n)) {
+        throw new ApiError("validation_failed", "Last-Event-ID must be a non-negative integer");
+    }
+    return n;
+}
+/**
+ * 会话事件流（SSE）：`GET /api/v1/orgs/:orgId/conversations/:id/stream?after=<seq>`，`agents.use`，只有会话所有者可用。
+ * - 打开时不阻塞地调用一次 ensureRun（`ConversationsService.kickRun`），停在「运行中」的孤儿运行由此被清理；
+ * - 先订阅会话频道、再回放 `after`（或优先的 `Last-Event-ID`）之后的事件：`id: <seq>` / `event: event`；
+ *   之后收到 `events` 通知就补读新事件（按 seq 去重），收到增量就发 `event: delta`，收到界面刷新
+ *   （插件 `ctx.ui.invalidate`）就发 `event: ui`（`data: {"plugin","contribution"}`）；
+ * - 每 `runtime.sseHeartbeatMs` 发 `: ping` 注释；每 `runtime.sseRecheckMs` 复核凭据（会话未吊销 / 令牌仍有效，
+ *   access token 到期本身不算失效）与可见性，失败时发 `event: error`（`data: {"code"}`）后关闭流；
+ * - 用 `@Res()` + `reply.hijack()` 直接写原始响应，绕开 Nest / Fastify 的响应处理与缓冲。
+ *   代理（Web 层）需透传 `x-accel-buffering: no`、`cache-control: no-cache`。
+ */
+let ConversationStreamController = class ConversationStreamController {
+    streams;
+    sessions;
+    tokens;
+    conversations;
+    constructor(streams, sessions, tokens, conversations) {
+        this.streams = streams;
+        this.sessions = sessions;
+        this.tokens = tokens;
+        this.conversations = conversations;
+    }
+    async stream(principal, org, id, q, lastEventId, req, reply) {
+        const p = requireUser(principal);
+        const afterSeq = lastEventId !== undefined ? parseLastEventId(lastEventId) : q.after;
+        const res = reply.raw;
+        // 到这里为止的错误（不可见、订阅失败）尚未写响应，由错误过滤器按普通错误返回。
+        const handle = await this.streams.open({
+            orgId: org.orgId,
+            conversationId: id,
+            viewerAccountId: p.account.id,
+            afterSeq,
+            // 个人令牌要保留明文以便复核时重新 authenticate（只在本连接的闭包里，不落日志）
+            credential: credentialCheck(p, BEARER_RE.exec(req.headers.authorization ?? "")?.[1], {
+                sessions: this.sessions,
+                tokens: this.tokens,
+            }),
+        }, {
+            write: (chunk) => {
+                res.write(chunk);
+            },
+            backlog: () => res.writableLength,
+            end: () => {
+                res.end();
+            },
+            abort: () => {
+                res.destroy();
+            },
+        });
+        reply.hijack();
+        // 可见性已通过：不阻塞地 ensureRun（清理孤儿运行、投递等待中的消息），见 ConversationsService.kickRun。
+        this.conversations.kickRun(id);
+        res.on("close", () => handle.close());
+        // 订阅期间客户端已断开：close 事件可能已经错过
+        if (res.destroyed || !res.socket || res.socket.destroyed) {
+            handle.close();
+            res.destroy();
+            return;
+        }
+        res.writeHead(200, {
+            "content-type": "text/event-stream; charset=utf-8",
+            "cache-control": "no-cache",
+            "x-accel-buffering": "no",
+            connection: "keep-alive",
+        });
+        res.flushHeaders();
+        handle.begin();
+    }
+    /** 停机：关闭本进程的全部流，否则 HTTP 关闭要等到这些长连接超时。 */
+    onModuleDestroy() {
+        this.streams.closeAll();
+    }
+};
+__decorate([
+    Get(":id/stream"),
+    OrgAction("agents.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("id")),
+    __param(3, Query(new ZodPipe(StreamQuery))),
+    __param(4, Headers("last-event-id")),
+    __param(5, Req()),
+    __param(6, Res())
+], ConversationStreamController.prototype, "stream", null);
+ConversationStreamController = __decorate([
+    Controller("api/v1/orgs/:orgId/conversations"),
+    __param(0, Inject(CONVERSATION_STREAMS)),
+    __param(1, Inject(SESSIONS)),
+    __param(2, Inject(API_TOKENS)),
+    __param(3, Inject(CONVERSATIONS))
+], ConversationStreamController);
+export { ConversationStreamController };

package/dist/runtime/stream.d.ts

@@ -0,0 +1,63 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
+import type { KernelConfig } from "../config/schema.js";
+import { type EventLog } from "../conversations/event-log.js";
+import type { CredentialCheck } from "../identity/credential-check.js";
+/** 一次 SSE 连接的输出端（由 HTTP 层包装原始响应）。 */
+export interface SseOutput {
+    write(chunk: string): void;
+    /** 已写入但尚未发出的字节数（慢客户端积压）。 */
+    backlog(): number;
+    /** 正常结束（发完已缓冲的数据后 FIN）。 */
+    end(): void;
+    /** 立即销毁连接并释放已缓冲的数据（慢客户端、内部故障）。 */
+    abort(): void;
+}
+/** 流用到的总线：内核 bus（命名空间 `kernel`）。 */
+export interface StreamBus {
+    subscribe(topic: string, handler: (payload: unknown) => unknown): Promise<() => Promise<void>>;
+}
+export interface ConversationStreamsDeps {
+    eventLog: Pick<EventLog, "readAfter">;
+    bus: StreamBus;
+    /** 轻量可见性判定：连接建立时与每 `sseRecheckMs` 复核一次。 */
+    access(orgId: string, conversationId: string, viewerAccountId: string): Promise<boolean>;
+    config: () => KernelConfig;
+    log: Pick<Logger, "warn">;
+}
+export interface StreamParams {
+    orgId: string;
+    conversationId: string;
+    viewerAccountId: string;
+    /** 只发送 seq 大于它的事件。 */
+    afterSeq: number;
+    /** 复核建立连接时使用的凭据（会话未吊销 / 令牌仍有效），与可见性一起在建立时与每次复核时检查。 */
+    credential: CredentialCheck;
+}
+/** 一条已订阅、尚未开始输出的流：HTTP 层写完响应头后调用 `begin`。 */
+export interface StreamHandle {
+    begin(): void;
+    /**
+     * 关闭流：`end` 正常结束响应，`abort` 销毁连接。`begin()` 之前不碰输出端
+     * （响应还没开始，由 HTTP 层按普通错误返回）。
+     */
+    close(mode?: "end" | "abort"): void;
+}
+/**
+ * 会话事件流（SSE）：本进程持有的连接集合，停机时一并关闭。
+ * 跨副本的数据只经 PG（事件日志）与内核 bus（`conv.<id>`）流动，进程内只保存连接本身的资源
+ * （订阅、心跳与复核定时器）。
+ */
+export declare class ConversationStreams {
+    private readonly d;
+    private readonly active;
+    constructor(d: ConversationStreamsDeps);
+    /**
+     * 复核凭据与可见性，并先订阅会话频道（之后再回放，避免遗漏两者之间提交的事件）。
+     * 凭据失效 → 对应的 `auth.*`；不可见 → `conversation.not_found`；订阅失败照常抛出。此时尚未写任何响应，调用方可以按普通错误返回。
+     */
+    open(p: StreamParams, out: SseOutput): Promise<StreamHandle>;
+    /** 关闭本进程的全部流（停机时调用）。 */
+    closeAll(): void;
+    /** 当前打开的流数（测试用）。 */
+    get size(): number;
+}

package/dist/runtime/stream.js

@@ -0,0 +1,262 @@
+import { CONVERSATION_CHANGES, conversationTopic, } from "../conversations/event-log.js";
+import { ApiError } from "../errors.js";
+import { isUiBusMessage, uiFrame } from "../ui/registry.js";
+/** 补读事件的分页大小。 */
+const PAGE = 500;
+/** 慢客户端的积压上限：超过即关闭流，客户端带 Last-Event-ID 重连补读。 */
+const MAX_BACKLOG_BYTES = 4 * 1024 * 1024;
+/** 授权失败时随错误返回的英文说明（建立连接时作为普通错误响应）。 */
+const DENIAL_MESSAGES = {
+    "conversation.not_found": "Conversation not found",
+    "auth.session_revoked": "Session has been revoked",
+    "auth.required": "Authentication required",
+};
+/** 凭据仍有效且会话仍可见返回 null，否则返回错误码（凭据优先）。 */
+async function authorize(d, p) {
+    const denied = await p.credential();
+    if (denied !== null)
+        return denied;
+    const ok = await d.access(p.orgId, p.conversationId, p.viewerAccountId);
+    return ok ? null : "conversation.not_found";
+}
+const errorFrame = (code) => `event: error\ndata: ${JSON.stringify({ code })}\n\n`;
+function isBusMessage(m) {
+    if (typeof m !== "object" || m === null)
+        return false;
+    const k = m.kind;
+    if (k === "events")
+        return typeof m.toSeq === "number";
+    if (k === "ui")
+        return isUiBusMessage(m);
+    if (k === "changed") {
+        const what = m.what;
+        return CONVERSATION_CHANGES.includes(what);
+    }
+    if (k === "subagent_progress") {
+        const x = m;
+        return (typeof x.subagentId === "string" &&
+            typeof x.step === "number" &&
+            typeof x.toolCalls === "number");
+    }
+    return k === "delta" && typeof m.runId === "string";
+}
+const eventFrame = (e) => `id: ${e.seq}\nevent: event\ndata: ${JSON.stringify(e)}\n\n`;
+/**
+ * 会话事件流（SSE）：本进程持有的连接集合，停机时一并关闭。
+ * 跨副本的数据只经 PG（事件日志）与内核 bus（`conv.<id>`）流动，进程内只保存连接本身的资源
+ * （订阅、心跳与复核定时器）。
+ */
+export class ConversationStreams {
+    d;
+    active = new Set();
+    constructor(d) {
+        this.d = d;
+    }
+    /**
+     * 复核凭据与可见性，并先订阅会话频道（之后再回放，避免遗漏两者之间提交的事件）。
+     * 凭据失效 → 对应的 `auth.*`；不可见 → `conversation.not_found`；订阅失败照常抛出。此时尚未写任何响应，调用方可以按普通错误返回。
+     */
+    async open(p, out) {
+        const denied = await authorize(this.d, p);
+        if (denied !== null)
+            throw new ApiError(denied, DENIAL_MESSAGES[denied] ?? "Access denied");
+        const conn = new Connection(this.d, p, out, () => this.active.delete(conn));
+        this.active.add(conn);
+        try {
+            await conn.subscribe();
+        }
+        catch (e) {
+            conn.close();
+            throw e;
+        }
+        return conn;
+    }
+    /** 关闭本进程的全部流（停机时调用）。 */
+    closeAll() {
+        for (const c of [...this.active])
+            c.close();
+    }
+    /** 当前打开的流数（测试用）。 */
+    get size() {
+        return this.active.size;
+    }
+}
+class Connection {
+    d;
+    p;
+    out;
+    onClosed;
+    lastSeq;
+    closed = false;
+    chain;
+    openGate;
+    unsubscribe;
+    timers = [];
+    rechecking = false;
+    begun = false;
+    constructor(d, p, out, onClosed) {
+        this.d = d;
+        this.p = p;
+        this.out = out;
+        this.onClosed = onClosed;
+        this.lastSeq = p.afterSeq;
+        // 所有输出串行：先回放，之后按到达顺序处理频道消息；begin() 之前闸门关着。
+        this.chain = new Promise((resolve) => {
+            this.openGate = resolve;
+        });
+        this.enqueue(() => this.catchUp());
+    }
+    async subscribe() {
+        const un = await this.d.bus.subscribe(conversationTopic(this.p.conversationId), (m) => this.onMessage(m));
+        if (this.closed)
+            await un();
+        else
+            this.unsubscribe = un;
+    }
+    begin() {
+        if (this.closed)
+            return;
+        this.begun = true;
+        const { sseHeartbeatMs, sseRecheckMs } = this.d.config().runtime;
+        this.timers.push(setInterval(() => this.write(": ping\n\n"), sseHeartbeatMs), setInterval(() => void this.recheck(), sseRecheckMs));
+        this.openGate();
+    }
+    close(mode = "end") {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const t of this.timers)
+            clearInterval(t);
+        this.timers = [];
+        this.openGate();
+        const un = this.unsubscribe;
+        this.unsubscribe = undefined;
+        un?.().catch((err) => this.d.log.warn("conversation stream unsubscribe failed", {
+            conversationId: this.p.conversationId,
+            err,
+        }));
+        if (this.begun) {
+            try {
+                if (mode === "abort")
+                    this.out.abort();
+                else
+                    this.out.end();
+            }
+            catch {
+                // 连接已断开
+            }
+        }
+        this.onClosed();
+    }
+    onMessage(m) {
+        if (this.closed || !isBusMessage(m))
+            return;
+        if (m.kind === "events") {
+            const toSeq = m.toSeq;
+            this.enqueue(async () => {
+                if (toSeq > this.lastSeq)
+                    await this.catchUp();
+            });
+            return;
+        }
+        if (m.kind === "ui") {
+            // 界面刷新：只是「去重新取视图」的提示，网页按 plugin + contribution 重新请求（那里再鉴权）
+            const frame = uiFrame(m);
+            this.enqueue(() => this.write(frame));
+            return;
+        }
+        if (m.kind === "changed") {
+            // a hint to refetch that part of the conversation (the HTTP read checks access again)
+            const frame = `event: changed\ndata: ${JSON.stringify({ what: m.what })}\n\n`;
+            this.enqueue(() => this.write(frame));
+            return;
+        }
+        if (m.kind === "subagent_progress") {
+            // a sub-agent's step (spec §14.2): only on its parent's topic, which this viewer may read
+            const { kind: _k, ...progress } = m;
+            const frame = `event: subagent_progress\ndata: ${JSON.stringify(progress)}\n\n`;
+            this.enqueue(() => this.write(frame));
+            return;
+        }
+        const { kind: _kind, ...delta } = m;
+        this.enqueue(() => this.write(`event: delta\ndata: ${JSON.stringify(delta)}\n\n`));
+    }
+    enqueue(fn) {
+        this.chain = this.chain
+            .then(async () => {
+            if (!this.closed)
+                await fn();
+        })
+            .catch((err) => {
+            this.d.log.warn("conversation stream failed; closing", {
+                conversationId: this.p.conversationId,
+                err,
+            });
+            this.close("abort");
+        });
+    }
+    /** 读 lastSeq 之后的全部事件并发送（按 seq 去重：只发大于已发送值的）。 */
+    async catchUp() {
+        for (;;) {
+            const evs = await this.d.eventLog.readAfter(this.p.conversationId, this.lastSeq, PAGE);
+            for (const e of evs) {
+                if (this.closed)
+                    return;
+                if (e.seq <= this.lastSeq)
+                    continue;
+                this.write(eventFrame(e));
+                this.lastSeq = e.seq;
+            }
+            if (evs.length < PAGE || this.closed)
+                return;
+        }
+    }
+    /** 发最后一帧错误并关闭（未发完的排队输出随关闭丢弃）。 */
+    fail(code) {
+        if (this.closed)
+            return;
+        try {
+            this.out.write(errorFrame(code));
+        }
+        catch {
+            // 连接已断开
+        }
+        this.close();
+    }
+    write(chunk) {
+        if (this.closed)
+            return;
+        this.out.write(chunk);
+        if (this.out.backlog() > MAX_BACKLOG_BYTES) {
+            this.d.log.warn("conversation stream client too slow; closing", {
+                conversationId: this.p.conversationId,
+            });
+            // end() 会把 FIN 排在未发出的数据之后，零窗口的客户端会一直占着连接与缓冲区：直接销毁
+            this.close("abort");
+        }
+    }
+    /**
+     * 复核凭据与可见性；失败时先发最后一帧 `event: error`（`data: {"code"}`）再关闭。
+     * 复核本身出错按失败关闭处理（`internal`）。
+     */
+    async recheck() {
+        if (this.closed || this.rechecking)
+            return;
+        this.rechecking = true;
+        try {
+            const denied = await authorize(this.d, this.p);
+            if (denied !== null)
+                this.fail(denied);
+        }
+        catch (err) {
+            this.d.log.warn("conversation stream access re-check failed; closing", {
+                conversationId: this.p.conversationId,
+                err,
+            });
+            this.fail("internal");
+        }
+        finally {
+            this.rechecking = false;
+        }
+    }
+}

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

@@ -0,0 +1,80 @@
+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";
+/** Idempotency key of the parent's `subagent_finished` event. */
+export declare const finishedIdemKey: (childRunId: string) => string;
+/** A dispatch row, by its child run. */
+export interface DispatchRow {
+    parentRunId: string;
+    parentCallId: string;
+    parentConversationId: string;
+    childConversationId: string;
+    childRunId: string;
+}
+/** The dispatch that started `childRunId`, or null (not a sub-agent run). */
+export declare function dispatchOfChildRun(db: KernelDb, 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>;
+/**
+ * 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
+ * `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.
+ *
+ * `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?: {
+    modelGiven?: boolean;
+    forSkill?: boolean;
+}): Promise<{
+    content: string;
+    isError: boolean;
+    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>;