@ai-agent-forge/plugin-subagent-delegate 0.85.0

package/dist/subagent-runtime.js

@@ -0,0 +1,849 @@
+/**
+ * 子代理运行时调度器（D-044，《子代理运行时设计》§4-§6）——插件级 `SubagentRuntime`：
+ * 队列 / 准入 / 预算 / 终态 / 权限的唯一编排入口。
+ *
+ * - 只组合既有 primitive，不重建生命周期：`AgentTaskAdapter`
+ *   （../core/extensions/public-api.ts，裸执行 primitive，仅 admitted 之后调用）
+ *   与 `createAgentTaskRegistry`（./multi-agent-tasks.ts，状态注册表 primitive，
+ *   作为调度终态的投影写入，不作为第二权威；timed_out 经 checkDeadlines 原生直映，
+ *   例外路径见 projectTerminalToRegistry，§4.3）。
+ * - 生命周期：submit -> queued -> admitted -> allocated（此刻才 `adapter.create`，
+ *   之前零 child session、零模型资源）-> running -> 终态。
+ * - 预算执行点是调度器本身：submit 拒绝（prompt/metadata UTF-8 字节上限、队列深度），
+ *   settle 截断（maxMessages/maxResultBytes + `truncated` 标志）。registry 自建时显式传
+ *   Infinity 预算：并发与结果预算不得依赖 registry 缺省，也不能让 registry 成为第二准入权威。
+ * - 终态不可覆盖：settle 先查终态守卫，迟到的 `host.run` 结算一律抑制；取消是幂等 fence，
+ *   running 取消走有界 drain，超时终态 `drain_timeout`（reasonCode `subagent_drain_timeout`）。
+ * - 权限：`result(taskId, requester)` 仅在 owner 与 parentSessionId 均匹配时返回记录，
+ *   不区分"不存在"与"无权"；durable 回读走结构化校验，不做裸断言。persist 失败不吞终态：
+ *   内存记录已捕获，persist 错误经 cancel()/drain() 的 reject 挂 cause 暴露。
+ * - 父栅栏（§4.2）：宿主注入 `parentSignal` getter，每次 admitted 时读取当前信号
+ *   （epoch 正确）；信号已 aborted 的任务 admitted 即取消；abort 监听触发 cancelAll 语义。
+ * - 确定性：deadline 由显式 `tick()` 推进（无隐藏定时器）；drain 超时是对 `host.run`
+ *   promise 的定时 race（契约允许 "clock 推进或 race" 二选一，race 便于注入测试）。
+ *   共享 globalAdmission 的跨实例推进同样由显式 `tick()`（或任意实例的 submit/settle）
+ *   驱动，不引入轮询。
+ * - `runner_lost` 为 pooled 切片保留值，本实现不产生；`outputArtifactRef` /
+ *   `messagesArtifactRef` 为 artifact 分页保留字段，本切片不产出。
+ *
+ * 迁自宿主 `src/plugins/subagent-runtime.ts`（D-075 S4 第三批）；除 import 来源外
+ * 逐字保持：公共契约（AgentTaskAdapter/JsonValue/durable 类型）改自 plugin-sdk。
+ */
+import { randomUUID } from "node:crypto";
+import { AgentTaskError, createAgentTaskRegistry } from "./multi-agent-tasks.js";
+export class SubagentRuntimeError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "SubagentRuntimeError";
+        this.code = code;
+    }
+}
+/** 状态投影（§4.3）：调度器权威状态 -> `AgentTaskStatus` DTO 词汇；不产生映射表之外的值。 */
+export function toAgentTaskStatusProjection(status) {
+    switch (status) {
+        case "queued":
+        case "admitted":
+            return "created";
+        case "running":
+            return "running";
+        case "succeeded":
+            return "succeeded";
+        case "failed":
+            return "failed";
+        case "cancelled":
+            return "cancelled";
+        case "timed_out":
+        case "drain_timeout":
+        case "runner_lost":
+            return "failed";
+    }
+}
+function createDeferred() {
+    let resolve;
+    const promise = new Promise((res) => {
+        resolve = res;
+    });
+    return { promise, resolve };
+}
+/** 可取消的定时 deferred（wait 的超时臂）；cancel 同时清定时器并立即 resolve。 */
+function sleepDeferred(ms) {
+    let timer;
+    let resolve;
+    const promise = new Promise((res) => {
+        resolve = res;
+        timer = setTimeout(res, ms);
+    });
+    return {
+        promise,
+        cancel: () => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            resolve();
+        },
+    };
+}
+function createSlotGate(capacity) {
+    let held = 0;
+    return {
+        tryAcquire() {
+            if (held >= capacity)
+                return "limit";
+            held += 1;
+            return "claimed";
+        },
+        release() {
+            held -= 1;
+        },
+    };
+}
+const textEncoder = new TextEncoder();
+function utf8ByteLength(value) {
+    return textEncoder.encode(value).length;
+}
+/** JSON 序列化用于字节预算计算；不可序列化的值按空串计，不因预算计算抛错。 */
+function safeStringify(value) {
+    try {
+        const serialized = JSON.stringify(value);
+        return serialized === undefined ? "" : serialized;
+    }
+    catch {
+        return "";
+    }
+}
+function errorText(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === "string")
+        return error;
+    return safeStringify(error);
+}
+/**
+ * settle 有界化：先按 maxMessages 截断条数，再逐条累计 UTF-8 字节、超出 maxResultBytes
+ * 停止；任一截断发生即置 truncated（信封只持有有界快照，原文分页属后续 artifact 切片）。
+ */
+function boundMessages(messages, maxMessages, maxResultBytes) {
+    let truncated = false;
+    let selected = messages;
+    if (selected.length > maxMessages) {
+        selected = selected.slice(0, maxMessages);
+        truncated = true;
+    }
+    const bounded = [];
+    let used = 0;
+    for (const message of selected) {
+        const size = utf8ByteLength(safeStringify(message));
+        if (used + size > maxResultBytes) {
+            truncated = true;
+            break;
+        }
+        used += size;
+        bounded.push(message);
+    }
+    return { messages: bounded, truncated };
+}
+const RUNTIME_STATUSES = [
+    "queued",
+    "admitted",
+    "running",
+    "succeeded",
+    "failed",
+    "cancelled",
+    "timed_out",
+    "drain_timeout",
+    "runner_lost",
+];
+function isRuntimeStatus(value) {
+    return RUNTIME_STATUSES.includes(value);
+}
+/**
+ * 终态子集：`result()` 是**终态**回读契约，记录只在 settle 时落库，因此持久层里出现
+ * 非终态状态（queued/admitted/running）只能是脏数据或别的写入者——按不合格处理，
+ * 绝不把它当成"任务已完成"返回给调用方。
+ */
+const TERMINAL_RUNTIME_STATUSES = [
+    "succeeded",
+    "failed",
+    "cancelled",
+    "timed_out",
+    "drain_timeout",
+    "runner_lost",
+];
+function isTerminalRuntimeStatus(value) {
+    return TERMINAL_RUNTIME_STATUSES.includes(value);
+}
+/**
+ * durable 回读的结构化校验（不做裸断言）：字段类型逐一核对后显式重建记录，
+ * 不合格按 undefined 处理，与"不存在/无权"同型返回。
+ */
+function parseSchedulerRecord(value) {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const candidate = value;
+    if (candidate.schedulerVersion !== 1)
+        return undefined;
+    const taskId = candidate.taskId;
+    if (typeof taskId !== "string" || taskId.length === 0)
+        return undefined;
+    const owner = candidate.owner;
+    if (typeof owner !== "string" || owner.length === 0)
+        return undefined;
+    const parentSessionId = candidate.parentSessionId;
+    if (typeof parentSessionId !== "string" || parentSessionId.length === 0)
+        return undefined;
+    const status = candidate.status;
+    if (typeof status !== "string" || !isRuntimeStatus(status) || !isTerminalRuntimeStatus(status))
+        return undefined;
+    const truncated = candidate.truncated;
+    if (typeof truncated !== "boolean")
+        return undefined;
+    const sessionId = candidate.sessionId;
+    if (typeof sessionId !== "string" || sessionId.length === 0)
+        return undefined;
+    const messages = candidate.messages;
+    if (!Array.isArray(messages))
+        return undefined;
+    const reasonCode = candidate.reasonCode;
+    if (reasonCode !== undefined && typeof reasonCode !== "string")
+        return undefined;
+    const reason = candidate.reason;
+    if (reason !== undefined && typeof reason !== "string")
+        return undefined;
+    const outputArtifactRef = candidate.outputArtifactRef;
+    if (outputArtifactRef !== undefined && typeof outputArtifactRef !== "string")
+        return undefined;
+    const messagesArtifactRef = candidate.messagesArtifactRef;
+    if (messagesArtifactRef !== undefined && typeof messagesArtifactRef !== "string")
+        return undefined;
+    return {
+        schedulerVersion: 1,
+        taskId,
+        owner,
+        parentSessionId,
+        status,
+        ...(reasonCode === undefined ? {} : { reasonCode }),
+        ...(reason === undefined ? {} : { reason }),
+        truncated,
+        sessionId,
+        messages: Object.freeze([...messages]),
+        ...(outputArtifactRef === undefined ? {} : { outputArtifactRef }),
+        ...(messagesArtifactRef === undefined ? {} : { messagesArtifactRef }),
+    };
+}
+function matchesRequester(record, requester) {
+    return record.owner === requester.owner && record.parentSessionId === requester.parentSessionId;
+}
+export function createSubagentRuntime(options) {
+    const clock = options.clock ?? (() => Date.now());
+    const limits = options.limits ?? {};
+    const maxConcurrentSubagents = limits.maxConcurrentSubagents ?? 8;
+    const maxQueueDepth = limits.maxQueueDepth ?? 200;
+    const maxPromptBytes = limits.maxPromptBytes ?? 65536;
+    const maxMetadataBytes = limits.maxMetadataBytes ?? 16384;
+    const maxResultBytes = limits.maxResultBytes ?? 524288;
+    const maxMessages = limits.maxMessages ?? 2000;
+    const drainTimeoutMs = limits.drainTimeoutMs ?? 30000;
+    const maxRetainedRecords = limits.maxRetainedRecords ?? 256;
+    const results = options.results;
+    // registry 是状态投影 primitive，不是第二准入/预算权威：并发与结果预算由调度器
+    // 自己的 gate 与 settle 截断执行，因此自建时显式传 Infinity（不依赖其缺省值）。
+    const registry = options.registry ??
+        createAgentTaskRegistry({
+            now: clock,
+            maxConcurrent: Number.POSITIVE_INFINITY,
+            maxResultBytes: Number.POSITIVE_INFINITY,
+        });
+    const localAdmission = createSlotGate(maxConcurrentSubagents);
+    const admission = () => options.globalAdmission ?? localAdmission;
+    const tasks = new Map();
+    const records = new Map();
+    const queue = [];
+    let seq = 0;
+    let disposed = false;
+    let pumping = false;
+    // ---------------------------------------------------------------------------
+    // 终态 settle：终态守卫 -> 有界消息 -> 信封 -> 释放 -> 投影 -> 持久化
+    // ---------------------------------------------------------------------------
+    function settleEntry(entry, status, reasonCode, reason) {
+        // 终态守卫：settle 一律先查此标志，迟到结算（迟到的 host.run 结算、重复 fence）抑制。
+        if (entry.settled)
+            return;
+        entry.settled = true;
+        const bounded = entry.host
+            ? boundMessages(entry.host.session.getMessages(), maxMessages, maxResultBytes)
+            : { messages: [], truncated: false };
+        // 子会话身份（D-060 S1）：优先取"agent 会话自身的 id"（池化下宿主可见的 id 是 wire 任务 id），
+        // 退回宿主会话 id；两者都在终态前读取（settle 之后 host 被清空）。
+        const sessionId = entry.host?.session.getAgentSessionId?.() ?? entry.host?.session.getSessionId() ?? entry.taskId;
+        const record = Object.freeze({
+            schedulerVersion: 1,
+            taskId: entry.taskId,
+            owner: options.owner,
+            parentSessionId: options.parentSessionId,
+            status,
+            ...(reasonCode === undefined ? {} : { reasonCode }),
+            ...(reason === undefined ? {} : { reason }),
+            truncated: bounded.truncated,
+            sessionId,
+            messages: Object.freeze([...bounded.messages]),
+        });
+        entry.status = status;
+        records.set(entry.taskId, record);
+        // 有界保留：Map 按插入序迭代，淘汰最旧的终态记录。
+        while (records.size > maxRetainedRecords) {
+            const oldest = records.keys().next();
+            if (oldest.done === true)
+                break;
+            records.delete(oldest.value);
+        }
+        if (entry.gate !== undefined) {
+            const gate = entry.gate;
+            entry.gate = undefined;
+            gate.release();
+        }
+        if (entry.parentSignal !== undefined && entry.parentListener !== undefined) {
+            entry.parentSignal.removeEventListener("abort", entry.parentListener);
+            entry.parentSignal = undefined;
+            entry.parentListener = undefined;
+        }
+        if (entry.host !== undefined) {
+            // 终态后释放子会话（§5.2：cleanup 失败终态仍必须落库）——消息快照已在上方读取。
+            const host = entry.host;
+            entry.host = undefined;
+            void host.dispose().catch(() => {
+                // dispose 失败不改变已落的调度终态，任务记录已捕获。
+            });
+        }
+        entry.settleDeferred.resolve(record);
+        projectTerminalToRegistry(record);
+        persistRecord(entry, record);
+        // 槽位已释放：FIFO 推进队列（pumping 守卫保证与进行中的准入循环互斥）。
+        pump();
+    }
+    function projectTerminalToRegistry(record) {
+        // registry 抛 AgentTaskError（如 duplicate_terminal / unknown_task）不得让调度器
+        // 崩溃，也不得覆盖调度终态：调度记录是权威，投影失败按忽略处理。
+        try {
+            if (record.status === "succeeded") {
+                registry.complete(record.taskId, record.messages);
+            }
+            else if (record.status === "cancelled") {
+                registry.cancel(record.taskId, record.reason ?? "cancelled");
+            }
+            else if (record.status === "timed_out") {
+                // §4.3：timed_out 直映 registry 原生 timed_out——正常路径下注入的 registry 已在
+                // tick() 的 checkDeadlines 原生置 timed_out，此处不得再改写（会 duplicate_terminal）；
+                // 仅当仍未终态（过期降级创建等例外路径，原生 checkDeadlines 覆盖不到）才以
+                // fail + reason "deadline_passed" 落投影。
+                const projected = registry.get(record.taskId);
+                if (projected !== undefined && (projected.status === "pending" || projected.status === "running")) {
+                    registry.fail(record.taskId, record.reason ?? record.reasonCode ?? "deadline_passed");
+                }
+            }
+            else {
+                registry.fail(record.taskId, record.reason ?? record.reasonCode ?? record.status);
+            }
+        }
+        catch {
+            // 投影失败不改变调度终态。
+        }
+    }
+    function persistRecord(entry, record) {
+        if (results === undefined) {
+            entry.persistDone.resolve();
+            return;
+        }
+        void (async () => {
+            try {
+                await results.store.persistArtifact({
+                    writerId: results.writerId,
+                    artifactId: `subagent-task:${entry.taskId}`,
+                    sessionId: options.parentSessionId,
+                    data: record,
+                });
+            }
+            catch (error) {
+                // persist 失败不吞任务终态：内存记录已捕获；错误挂 cause 经 cancel()/drain()
+                // 的 reject 通道暴露（对齐 capability-runtime-guards 的 cause 模式）。
+                entry.persistFailed = true;
+                entry.persistError = error;
+            }
+            finally {
+                entry.persistDone.resolve();
+            }
+        })();
+    }
+    // ---------------------------------------------------------------------------
+    // 运行与取消
+    // ---------------------------------------------------------------------------
+    function startRun(entry, host) {
+        const runPromise = host.run(entry.request.prompt, entry.controller.signal);
+        void runPromise.then(() => onRunSettled(entry, undefined), (error) => onRunSettled(entry, error));
+    }
+    /**
+     * adapter 抛出的结构化 `code` → 调度器 reasonCode。纪律：只接受保留前缀 `subagent_`
+     * 与既有特例 `runner_lost`（映射为 `subagent_runner_lost`，D-044 §4.3）——记录里的
+     * reasonCode 沿用调度器词汇表，不让第三方错误码污染 §4.3 的映射表。
+     */
+    function adapterReasonCode(error) {
+        if (typeof error !== "object" || error === null)
+            return undefined;
+        const code = error.code;
+        if (typeof code !== "string" || code.length === 0)
+            return undefined;
+        if (code === "runner_lost")
+            return "subagent_runner_lost";
+        return code.startsWith("subagent_") ? code : undefined;
+    }
+    function onRunSettled(entry, error) {
+        entry.runSettled.resolve();
+        if (entry.settled)
+            return; // 迟到结算：终态已落，抑制
+        if (entry.cancelRequested)
+            return; // fence 已落：由取消/drain 路径按 pendingTerminal 结算
+        if (error !== undefined) {
+            // failed 取原始错误 message（含字符串 throw 的原始文本）；
+            // adapter 可用结构化 code 声明原因（见 adapterReasonCode 的白名单纪律）。
+            settleEntry(entry, "failed", adapterReasonCode(error), errorText(error));
+            return;
+        }
+        settleEntry(entry, "succeeded", undefined, undefined);
+    }
+    /**
+     * 有界 drain：对 host.run promise 的定时 race（真实定时器，不依赖 scheduler clock；
+     * 测试可用小 drainTimeoutMs 或 fake timers）。runSettled 已决时立即返回。
+     */
+    function raceDrain(entry, timeoutMs) {
+        let settleOutcome;
+        const outcomePromise = new Promise((resolve) => {
+            settleOutcome = resolve;
+        });
+        const timer = setTimeout(() => settleOutcome("timeout"), timeoutMs);
+        void entry.runSettled.promise.then(() => settleOutcome("settled"));
+        void outcomePromise.then(() => clearTimeout(timer));
+        return outcomePromise;
+    }
+    /** 每个任务至多一个 drain driver：首个启动者的预算生效，后续调用只共享其结果。 */
+    function startDrainDriver(entry, timeoutMs) {
+        if (entry.drainDriverStarted)
+            return;
+        entry.drainDriverStarted = true;
+        void (async () => {
+            const outcome = await raceDrain(entry, timeoutMs);
+            if (entry.settled)
+                return;
+            if (outcome === "timeout") {
+                // 执行体未在预算内结束：终态 drain_timeout（reasonCode subagent_drain_timeout），
+                // 仍按 settle 路径保留现场消息快照，并尽力 abort + dispose 清理。
+                entry.controller.abort("subagent drain timeout");
+                settleEntry(entry, "drain_timeout", "subagent_drain_timeout", entry.cancelReason);
+                return;
+            }
+            if (entry.pendingTerminal !== undefined) {
+                settleEntry(entry, entry.pendingTerminal, entry.pendingReasonCode, entry.cancelReason);
+            }
+            // 无 fence 的 drain()：in-time 结算已由 onRunSettled 自然完成。
+        })();
+    }
+    /** 取消 fence（幂等）：queued 直接出队终态；admitted 由分配路径结算；running 有界 drain。 */
+    function cancelEntry(entry, reason) {
+        if (entry.settled || entry.cancelRequested)
+            return;
+        entry.cancelRequested = true;
+        entry.pendingTerminal = "cancelled";
+        entry.pendingReasonCode = undefined;
+        entry.cancelReason = reason;
+        entry.controller.abort(reason);
+        applyFence(entry);
+    }
+    /** deadline fence：终态方向为 timed_out（reasonCode deadline_passed）。 */
+    function deadlineFence(entry) {
+        if (entry.settled || entry.cancelRequested)
+            return;
+        entry.cancelRequested = true;
+        entry.pendingTerminal = "timed_out";
+        entry.pendingReasonCode = "deadline_passed";
+        entry.cancelReason = undefined;
+        entry.controller.abort("deadline passed");
+        applyFence(entry);
+    }
+    function applyFence(entry) {
+        switch (entry.status) {
+            case "queued": {
+                const index = queue.indexOf(entry);
+                if (index >= 0)
+                    queue.splice(index, 1);
+                settleEntry(entry, entry.pendingTerminal ?? "cancelled", entry.pendingReasonCode, entry.cancelReason);
+                return;
+            }
+            case "admitted":
+                // 分配进行中：admitEntry 在 create 结算后按 fence 终态（终态守卫保证只结算一次）。
+                return;
+            case "running":
+                startDrainDriver(entry, drainTimeoutMs);
+                return;
+            default:
+                // 已终态：fence 幂等 no-op（entry.settled 守卫已挡住重复进入）。
+                return;
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // 准入（严格 FIFO）
+    // ---------------------------------------------------------------------------
+    function pump() {
+        if (pumping)
+            return;
+        pumping = true;
+        void admitNext();
+    }
+    async function admitNext() {
+        try {
+            while (queue.length > 0) {
+                const gate = admission();
+                if (gate.tryAcquire() === "limit")
+                    break;
+                const entry = queue.shift();
+                if (entry === undefined) {
+                    gate.release();
+                    break;
+                }
+                if (entry.settled) {
+                    gate.release();
+                    continue;
+                }
+                await admitEntry(entry, gate);
+            }
+        }
+        finally {
+            pumping = false;
+        }
+    }
+    async function admitEntry(entry, gate) {
+        entry.status = "admitted";
+        entry.gate = gate;
+        bindParentSignal(entry);
+        if (entry.cancelRequested) {
+            settleEntry(entry, entry.pendingTerminal ?? "cancelled", entry.pendingReasonCode, entry.cancelReason);
+            return;
+        }
+        try {
+            registry.start(entry.taskId);
+        }
+        catch (error) {
+            // registry 抛 AgentTaskError 不得让调度器崩溃：包装为调度终态 failed。
+            settleEntry(entry, "failed", undefined, errorText(error));
+            return;
+        }
+        // 延迟分配（§4.1）：只有 admitted 才 adapter.create；queued 任务零 child session。
+        let host;
+        try {
+            host = await options.adapter.create({
+                prompt: entry.request.prompt,
+                ...(entry.request.metadata === undefined ? {} : { metadata: entry.request.metadata }),
+            });
+        }
+        catch (error) {
+            settleEntry(entry, "failed", adapterReasonCode(error), errorText(error));
+            return;
+        }
+        if (entry.cancelRequested) {
+            // 分配期间 fence 落下：host 立即进入 settle（dispose）路径，不启动 run。
+            entry.host = host;
+            settleEntry(entry, entry.pendingTerminal ?? "cancelled", entry.pendingReasonCode, entry.cancelReason);
+            return;
+        }
+        entry.host = host;
+        // 子会话 id 即刻捕获（D-060 S4）：steer/resume 需要在运行期按 sessionId 定位任务。
+        entry.recordSessionId = host.session.getAgentSessionId?.() ?? host.session.getSessionId();
+        entry.status = "running";
+        startRun(entry, host);
+    }
+    /** 父栅栏（§4.2）：每次 admitted 读取当前信号（epoch 正确）；已 aborted 立即按 fence 处理。 */
+    function bindParentSignal(entry) {
+        const signal = options.parentSignal?.();
+        if (signal === undefined)
+            return;
+        if (signal.aborted) {
+            entry.cancelRequested = true;
+            entry.pendingTerminal = "cancelled";
+            entry.pendingReasonCode = undefined;
+            entry.cancelReason = "parent signal aborted";
+            return;
+        }
+        const listener = () => {
+            // 父栅栏级联（§5.2）：cancel fence 全量子任务（queued 移除 + running 有界 drain）。
+            // runtime 实例绑定单一 owner/parentSessionId，cancelAll 即该父的全部任务；
+            // abort 之后以新 epoch 信号提交的任务不受本次级联影响。
+            void cancelAllEntries("parent signal aborted").catch(() => {
+                // 无调用方的级联路径：persist 失败等收尾错误已在各任务 cancel()/drain() 的
+                // reject 通道暴露，这里不能也不需要再抛。
+            });
+        };
+        entry.parentSignal = signal;
+        entry.parentListener = listener;
+        signal.addEventListener("abort", listener, { once: true });
+    }
+    // ---------------------------------------------------------------------------
+    // 公共 API
+    // ---------------------------------------------------------------------------
+    function handleOf(entry) {
+        return {
+            id: entry.taskId,
+            status: () => entry.status,
+            signal: entry.controller.signal,
+            result: () => awaitTerminalRecord(entry),
+            cancel: (reason) => {
+                cancelEntry(entry, reason);
+                return awaitTerminalVoid(entry);
+            },
+            drain: (drainOptions) => {
+                // queued/admitted 尚无执行体可 drain：等待其自然终态；running 才挂有界预算。
+                if (!entry.settled && entry.status === "running") {
+                    startDrainDriver(entry, drainOptions?.timeoutMs ?? drainTimeoutMs);
+                }
+                return awaitTerminalRecord(entry);
+            },
+        };
+    }
+    async function awaitTerminalRecord(entry) {
+        const record = await entry.settleDeferred.promise;
+        await entry.persistDone.promise;
+        if (entry.persistFailed) {
+            throw new Error("Subagent task result could not be persisted", { cause: entry.persistError });
+        }
+        return record;
+    }
+    async function awaitTerminalVoid(entry) {
+        await entry.settleDeferred.promise;
+        await entry.persistDone.promise;
+        if (entry.persistFailed) {
+            throw new Error("Subagent task result could not be persisted", { cause: entry.persistError });
+        }
+    }
+    async function cancelAllEntries(reason) {
+        const pending = [...tasks.values()].filter((entry) => !entry.settled);
+        for (const entry of pending)
+            cancelEntry(entry, reason);
+        await Promise.all(pending.map((entry) => awaitTerminalVoid(entry)));
+    }
+    return {
+        submit(request) {
+            if (disposed) {
+                throw new SubagentRuntimeError("subagent_invalid_request", "Subagent runtime has been disposed; submit is revoked");
+            }
+            if (typeof request !== "object" || request === null || typeof request.prompt !== "string") {
+                throw new SubagentRuntimeError("subagent_invalid_request", "Subagent submit request requires a string prompt");
+            }
+            if (utf8ByteLength(request.prompt) > maxPromptBytes) {
+                throw new SubagentRuntimeError("subagent_prompt_too_large", `Prompt of ${utf8ByteLength(request.prompt)} UTF-8 bytes exceeds the ${maxPromptBytes}-byte limit`);
+            }
+            if (request.metadata !== undefined) {
+                let serialized;
+                try {
+                    serialized = JSON.stringify(request.metadata);
+                }
+                catch {
+                    throw new SubagentRuntimeError("subagent_invalid_request", "Subagent submit metadata is not JSON-serializable");
+                }
+                if (utf8ByteLength(serialized) > maxMetadataBytes) {
+                    throw new SubagentRuntimeError("subagent_metadata_too_large", `Metadata of ${utf8ByteLength(serialized)} UTF-8 bytes exceeds the ${maxMetadataBytes}-byte limit`);
+                }
+            }
+            if (queue.length >= maxQueueDepth) {
+                throw new SubagentRuntimeError("subagent_queue_full", `Subagent queue depth ${queue.length} reached the ${maxQueueDepth}-entry limit`);
+            }
+            seq += 1;
+            const taskId = `subagent:${options.owner}:${seq}:${randomUUID().slice(0, 8)}`;
+            const deadlineAt = request.deadlineAt;
+            // §4.3：deadline 优先写入 registry 投影（原生 checkDeadlines 可直映 timed_out）。
+            // registry 对已过期 deadline fail fast（deadline_passed 类 AgentTaskError），此时
+            // 降级为不带 deadline 的 createTask：过期任务由调度器 tick 结算，registry 投影
+            // 走 fail + reason 的例外路径（projectTerminalToRegistry）。
+            try {
+                registry.createTask({
+                    taskId,
+                    parentSessionId: options.parentSessionId,
+                    ...(deadlineAt === undefined ? {} : { deadlineAt }),
+                });
+            }
+            catch (error) {
+                if (!(error instanceof AgentTaskError && error.code === "deadline_passed"))
+                    throw error;
+                registry.createTask({ taskId, parentSessionId: options.parentSessionId });
+            }
+            const entry = {
+                taskId,
+                request,
+                deadlineAt,
+                controller: new AbortController(),
+                status: "queued",
+                gate: undefined,
+                settled: false,
+                cancelRequested: false,
+                pendingTerminal: undefined,
+                pendingReasonCode: undefined,
+                cancelReason: undefined,
+                drainDriverStarted: false,
+                host: undefined,
+                recordSessionId: undefined,
+                runSettled: createDeferred(),
+                parentSignal: undefined,
+                parentListener: undefined,
+                settleDeferred: createDeferred(),
+                persistDone: createDeferred(),
+                persistFailed: false,
+                persistError: undefined,
+            };
+            tasks.set(taskId, entry);
+            queue.push(entry);
+            pump();
+            return Promise.resolve(handleOf(entry));
+        },
+        result(taskId, requester) {
+            const cached = records.get(taskId);
+            if (cached !== undefined) {
+                return Promise.resolve(matchesRequester(cached, requester) ? cached : undefined);
+            }
+            if (results === undefined)
+                return Promise.resolve(undefined);
+            let loaded;
+            try {
+                loaded = results.store.loadArtifact({ artifactId: `subagent-task:${taskId}` });
+            }
+            catch (error) {
+                // 存储故障必须作为 **rejected promise** 冒泡：result 的签名是 Promise，
+                // 同步抛出会让 `runtime.result(...).catch(...)` 直接崩在调用点。
+                return Promise.reject(error);
+            }
+            if (loaded === undefined)
+                return Promise.resolve(undefined);
+            const record = parseSchedulerRecord(loaded.data);
+            if (record === undefined || !matchesRequester(record, requester))
+                return Promise.resolve(undefined);
+            return Promise.resolve(record);
+        },
+        findBySession(sessionId, requester) {
+            if (requester.owner !== options.owner || requester.parentSessionId !== options.parentSessionId) {
+                return undefined;
+            }
+            for (const entry of tasks.values()) {
+                if (entry.recordSessionId !== sessionId)
+                    continue;
+                return { taskId: entry.taskId, settled: entry.settled };
+            }
+            return undefined;
+        },
+        async steer(taskId, text, requester) {
+            if (requester.owner !== options.owner || requester.parentSessionId !== options.parentSessionId) {
+                throw new SubagentRuntimeError("subagent_unknown_task", `no task ${taskId} in this scheduler scope`);
+            }
+            const entry = tasks.get(taskId);
+            if (entry === undefined) {
+                throw new SubagentRuntimeError("subagent_unknown_task", `no task ${taskId} in this scheduler scope`);
+            }
+            const host = entry.settled ? undefined : entry.host;
+            if (host === undefined) {
+                throw new SubagentRuntimeError("subagent_not_running", `task ${taskId} is not running (queued or settled)`);
+            }
+            const steerFn = host.session.steer;
+            if (typeof steerFn !== "function") {
+                throw new SubagentRuntimeError("subagent_steer_unsupported", `task ${taskId}'s host session exposes no steer`);
+            }
+            await steerFn.call(host.session, text);
+        },
+        async wait(taskId, timeoutMs, requester) {
+            const entry = tasks.get(taskId);
+            if (entry === undefined ||
+                requester.owner !== options.owner ||
+                requester.parentSessionId !== options.parentSessionId) {
+                return undefined;
+            }
+            if (entry.settled)
+                return records.get(taskId);
+            const boundedTimeout = Math.max(0, Math.min(timeoutMs, 120_000));
+            const timer = sleepDeferred(boundedTimeout);
+            const settled = Promise.race([entry.settleDeferred.promise, timer.promise]);
+            await settled.catch(() => { });
+            timer.cancel();
+            // settle 后记录必已落（settleEntry 先 records.set 再 resolve settleDeferred）。
+            return entry.settled ? records.get(taskId) : undefined;
+        },
+        peek(taskId, requester) {
+            const entry = tasks.get(taskId);
+            if (entry === undefined ||
+                requester.owner !== options.owner ||
+                requester.parentSessionId !== options.parentSessionId) {
+                return undefined;
+            }
+            return { settled: entry.settled, status: entry.status };
+        },
+        stats() {
+            let queued = 0;
+            let admitted = 0;
+            let running = 0;
+            let terminal = 0;
+            for (const entry of tasks.values()) {
+                if (entry.status === "queued")
+                    queued += 1;
+                else if (entry.status === "admitted")
+                    admitted += 1;
+                else if (entry.status === "running")
+                    running += 1;
+                else
+                    terminal += 1;
+            }
+            return { queued, admitted, running, terminal };
+        },
+        async cancelAll(reason) {
+            await cancelAllEntries(reason);
+        },
+        tick() {
+            const now = clock();
+            // §4.3：先推进注入 registry 的原生 deadline（running 任务原生直映 timed_out），
+            // 再与调度器自身计算的过期任务取并集；原生先行保证后续调度终态投影不会把
+            // 原生 timed_out 改写为 duplicate_terminal 失败。
+            let registryExpired = [];
+            try {
+                if (typeof registry.checkDeadlines === "function")
+                    registryExpired = registry.checkDeadlines();
+            }
+            catch {
+                // 注入 registry 的原生推进失败不得让调度器崩溃：调度器自身计算仍会兜底。
+            }
+            const expired = new Set(registryExpired);
+            for (const entry of tasks.values()) {
+                if (entry.deadlineAt !== undefined && !entry.settled && now >= entry.deadlineAt) {
+                    expired.add(entry.taskId);
+                }
+            }
+            const converted = [];
+            for (const id of expired) {
+                const entry = tasks.get(id);
+                if (entry === undefined || entry.settled || entry.cancelRequested)
+                    continue;
+                if (entry.status === "queued") {
+                    // queued 过期：直接出队终态 timed_out。
+                    const index = queue.indexOf(entry);
+                    if (index >= 0)
+                        queue.splice(index, 1);
+                    settleEntry(entry, "timed_out", "deadline_passed", undefined);
+                }
+                else {
+                    // running/admitted 过期：走 cancel fence + 有界 drain，终态 timed_out
+                    //（drain 自身再超时则按 drain_timeout 收敛）。
+                    deadlineFence(entry);
+                }
+                converted.push(id);
+            }
+            // 共享 globalAdmission 时，其他实例的槽位释放无法回调本实例；与其他显式推进
+            // 一致，由 tick()/submit/settle 的 pump 重试准入，不引入隐藏轮询。
+            pump();
+            return Object.freeze(converted);
+        },
+        async dispose() {
+            disposed = true;
+            await cancelAllEntries("subagent runtime disposed");
+        },
+    };
+}
+//# sourceMappingURL=subagent-runtime.js.map