@ai-agent-forge/agent-forge 0.85.0

package/dist/core/extensions/capability-runtime.js

@@ -0,0 +1,2170 @@
+import { randomUUID } from "node:crypto";
+import { performance } from "node:perf_hooks";
+import { createLifecycleRuntime } from "./capability-runtime-events.js";
+import { guardedComposition, guardedCredentials, guardedInteraction, guardedOutput, guardedSession, RuntimeAgentTask, withNormalizedToolResultExecute, } from "./capability-runtime-guards.js";
+import { createRuntimeInspector } from "./capability-runtime-inspect.js";
+import { assertManifest, assertPluginCapabilityDeclarations, assertPluginCapabilityId, assertPluginCapabilityVersion, capabilityKey, createPluginConfig, isPluginConfigValue, resolvePluginCapabilityOrder, } from "./capability-runtime-manifest.js";
+import { OutputArtifactError, RuntimeOperation } from "./capability-runtime-operation.js";
+import { definitionSnapshot, detachedSnapshot } from "./capability-runtime-snapshot.js";
+import { assertRegisteredCapabilityActive as assertRegisteredCapabilityState, cancelOwnedOperations as cancelOwnedOperationsState, createCapabilityRuntimeState, createRevokedCapabilityError, invokePluginCapability as invokePluginCapabilityState, invokeRegisteredCapability as invokeRegisteredCapabilityState, invokeRegisteredCapabilityWithSignal as invokeRegisteredCapabilityWithSignalState, isRevokedCapabilityError, observeUnexpectedAsyncCleanup, trackOperation as trackOperationState, } from "./capability-runtime-store.js";
+import { invokeCapabilityTool } from "./capability-runtime-tool.js";
+import { asHandler, assertAgentTaskRequest, assertHost, capabilityName, contributionPointKey, lifecycleEventKey, lifecycleRegistrationKinds, stableTextCompare, toolReadonlySafe, validateCommandDefinition, validateCommandResult, validateContributionPointDefinition, validateExecutionFactsV1, validateLifecycleEventDefinition, validateProviderHeaders, validateRetryScheduleV1, } from "./capability-runtime-validation.js";
+import { PLUGIN_REJECTED_EVENT_ID, PLUGIN_REJECTED_EVENT_VERSION } from "./lifecycle-catalog.js";
+import { createLifecycleDeliveryQueue } from "./lifecycle-delivery-queue.js";
+import { createDisposableRegistration, createEventEnvelope, } from "./public-api.js";
+export { resolvePluginCapabilityOrder } from "./capability-runtime-manifest.js";
+export { validateExecutionFactsV1, validateRetryScheduleV1 } from "./capability-runtime-validation.js";
+/**
+ * 慢事件订阅者观测阈值（毫秒）：publish 对单个订阅者的投递耗时超过该值时记一条
+ * warn 日志（事件类型 + 订阅 id + 耗时，pluginId 归属订阅者）。纯观测面，不改投递
+ * 行为：仍顺序 await、等待完成、不超时打断、不丢弃。每个订阅者在单个 publish 周期
+ * 内至多被投递一次，因此天然至多记一条。计时用 performance.now 而非可注入 clock：
+ * clock 缺省恒 0（生产不注入），不能作为耗时来源。
+ */
+const SLOW_EVENT_SUBSCRIBER_WARN_MS = 100;
+export function createCapabilityRuntime(inputHost, options = {}) {
+    // D-075 S4 third batch: the communication/turnContext host services carry
+    // host-owned callbacks. They must ride by reference (like the trace
+    // service in CapabilityRuntimeOptions) instead of through the structured
+    // clone below, which cannot clone functions. Strip them before the
+    // snapshot and re-attach to the exposed host afterwards. S4 fourth batch:
+    // memoryStorage joins — its store/ledger factories and vector components
+    // are host-owned runtime services with the same non-cloneable shape.
+    // Validate BEFORE destructuring: destructuring a null/non-object host would
+    // surface a TypeError instead of the contract's validation error.
+    assertHost(inputHost);
+    const { communication, turnContext, memoryStorage, ...cloneableHost } = inputHost;
+    const host = detachedSnapshot(cloneableHost);
+    assertHost(host);
+    const hostWithServices = communication === undefined && turnContext === undefined && memoryStorage === undefined
+        ? host
+        : Object.freeze({
+            ...host,
+            ...(communication === undefined ? {} : { communication }),
+            ...(turnContext === undefined ? {} : { turnContext }),
+            ...(memoryStorage === undefined ? {} : { memoryStorage }),
+        });
+    const hasSession = host.features.includes("session");
+    const hasSessionExport = host.features.includes("session-export");
+    const hasSessionRevision = host.features.includes("session-revision-v1");
+    if (hasSession && !options.session) {
+        throw new Error("Host declares session capability without a SessionAPI");
+    }
+    if (!hasSession && options.session) {
+        throw new Error("Host provides a SessionAPI without the session capability");
+    }
+    if (hasSessionExport && !hasSession) {
+        throw new Error("Host declares session-export capability without the session capability");
+    }
+    if (hasSessionExport && !options.session?.exportArtifact) {
+        throw new Error("Host declares session-export capability without SessionAPI.exportArtifact");
+    }
+    if (hasSessionRevision && !hasSession) {
+        throw new Error("Host declares session-revision-v1 capability without the session capability");
+    }
+    if (hasSessionRevision && !options.session?.getRevision) {
+        throw new Error("Host declares session-revision-v1 capability without SessionAPI.getRevision");
+    }
+    if (host.features.includes("agents") && !options.session) {
+        throw new Error("Host declares agents capability without a parent SessionAPI");
+    }
+    if (host.features.includes("agents") &&
+        !options.agents &&
+        options.agentSessionReader === undefined &&
+        options.agentSessionLister === undefined) {
+        throw new Error("Host declares agents capability without an AgentTaskAdapter or a session reader/lister");
+    }
+    if (options.agents && !host.features.includes("agents")) {
+        throw new Error("Host provides an AgentTaskAdapter without the agents capability");
+    }
+    if (options.agentResults && !host.features.includes("agent-result-replay-v1")) {
+        throw new Error("Host provides an agentResults option without the agent-result-replay-v1 capability");
+    }
+    if (host.features.includes("agent-result-replay-v1") && !options.agentResults) {
+        throw new Error("Host declares agent-result-replay-v1 capability without an agentResults option");
+    }
+    if (host.features.includes("credentials") && !options.credentials) {
+        throw new Error("Host declares credentials capability without a CredentialAPI");
+    }
+    if (options.credentials && !host.features.includes("credentials")) {
+        throw new Error("Host provides a CredentialAPI without the credentials capability");
+    }
+    if (host.features.includes("interaction") && !options.interaction) {
+        throw new Error("Host declares interaction capability without an InteractionHostV1");
+    }
+    if (options.interaction && !host.features.includes("interaction")) {
+        throw new Error("Host provides an InteractionHostV1 without the interaction capability");
+    }
+    if (host.features.includes("agent-result-replay-v1") && !host.features.includes("agents")) {
+        throw new Error("Host declares the agent-result-replay-v1 feature without the agents capability");
+    }
+    const clock = options.clock ?? (() => 0);
+    // Per-runtime unique segment for generated agent task ids: without an
+    // idFactory the id is otherwise a deterministic per-instance sequence, so a
+    // rebuilt runtime reusing the same owner and sequence would replay over the
+    // previous generation's durable records under the same key.
+    const runtimeInstanceSegment = randomUUID().slice(0, 8);
+    const onOutputArtifactCommit = options.onOutputArtifactCommit;
+    const toolExecutionContext = options.toolExecutionContext;
+    const state = createCapabilityRuntimeState();
+    const { tools, skills, retryPolicies, compactionPolicies, overflowPolicies, branchSummaryPolicies, runLoopStrategies, loopHooks, commands, operations, rpcMethods, contextStrategies, pluginCapabilities, providerHeaderTransforms, contributionPoints, lifecycleDefinitions, lifecycleRegistrations, subscribers, statuses, pluginRegistrations, apiStates, activeOwnerTokens, outputArtifacts, stateByOwner, stateRevisionsByOwner, stateWatchers, stateByInstance, stateRevisionsByInstance, stateWatchersByInstance, logs, spans, lifecycleDeliveryQueues, pluginRejections, } = state;
+    const runtimeState = state;
+    let subscriptionSequence = 0;
+    let operationSequence = 0;
+    let agentTaskSequence = 0;
+    let artifactSequence = 0;
+    let contributionSubscriptionSequence = 0;
+    let lifecycleRegistrationSequence = 0;
+    let stateWatcherSequence = 0;
+    let spanSequence = 0;
+    let traceSequence = 0;
+    let loopHookSequence = 0;
+    const createRuntimeId = (kind, sequence, fallback) => {
+        if (!options.idFactory)
+            return fallback;
+        const id = options.idFactory(kind, sequence);
+        if (typeof id !== "string" || !id.trim()) {
+            throw new Error(`Runtime idFactory must return a non-empty string for ${kind}`);
+        }
+        return id;
+    };
+    const { dispatchLifecycle, reportCapabilityCall, reportOperationCancel, reportOperationEnd, reportOperationStart, reportOperationStep, } = createLifecycleRuntime({
+        state,
+        clock,
+        createRuntimeId,
+        onLifecycleDispatch: options.onLifecycleDispatch,
+    });
+    const inspect = createRuntimeInspector({ state, host });
+    const assertRegisteredCapabilityActive = (registered) => assertRegisteredCapabilityState(state, registered);
+    const invokeRegisteredCapability = async (registered, invoke) => invokeRegisteredCapabilityState(state, registered, invoke);
+    const invokeRegisteredCapabilityWithSignal = async (registered, signal, invoke) => invokeRegisteredCapabilityWithSignalState(state, registered, signal, invoke);
+    const invokePluginCapability = async (registered, input, signal) => invokePluginCapabilityState(state, registered, input, signal);
+    const trackOperation = (ownerTokens, handle) => trackOperationState(state, ownerTokens, handle);
+    const cancelOwnedOperations = (ownerToken, owner) => cancelOwnedOperationsState(state, ownerToken, owner);
+    const cleanupArtifacts = (ownerToken) => {
+        for (const [artifactId, artifact] of outputArtifacts) {
+            if (artifact.ownerToken === ownerToken)
+                outputArtifacts.delete(artifactId);
+        }
+    };
+    const cleanupPluginCapabilities = (ownerToken) => {
+        for (const [key, capability] of pluginCapabilities) {
+            if (capability.ownerToken === ownerToken)
+                pluginCapabilities.delete(key);
+        }
+    };
+    const cleanupRegisteredCapabilities = (ownerToken) => {
+        for (const registry of [
+            tools,
+            skills,
+            retryPolicies,
+            compactionPolicies,
+            overflowPolicies,
+            branchSummaryPolicies,
+            runLoopStrategies,
+            commands,
+            operations,
+            rpcMethods,
+            contextStrategies,
+            providerHeaderTransforms,
+        ]) {
+            for (const [name, entry] of registry) {
+                if (entry.ownerToken === ownerToken) {
+                    registry.delete(name);
+                    if (registry === tools)
+                        notifyToolRegistryChange(entry.owner, name);
+                }
+            }
+        }
+        for (const [position, entries] of loopHooks) {
+            const remaining = entries.filter((entry) => entry.ownerToken !== ownerToken);
+            if (remaining.length === 0)
+                loopHooks.delete(position);
+            else if (remaining.length !== entries.length)
+                loopHooks.set(position, remaining);
+        }
+        for (const [type, handlers] of subscribers) {
+            for (const [id, handler] of handlers) {
+                if (handler.ownerToken === ownerToken)
+                    handlers.delete(id);
+            }
+            if (handlers.size === 0)
+                subscribers.delete(type);
+        }
+        // 替换链清扫：链中只应存活 owner 的注册。revokeState 先 activeOwnerTokens.delete
+        // 再调用本清理，故此处能正确判定本 owner 已死；死条目在 restoreReplacedTool 弹栈
+        // 时本就会被跳过（同样按 activeOwnerTokens 判定），提前删除不改变任何可观测行为，
+        // 只消除陈旧状态——替换方长期不 dispose 且被替换 owner 已撤销时，链项会一直滞留。
+        for (const [name, chain] of toolReplacementChains) {
+            const remaining = chain.filter((entry) => activeOwnerTokens.has(entry.ownerToken));
+            if (remaining.length === 0)
+                toolReplacementChains.delete(name);
+            else if (remaining.length !== chain.length)
+                toolReplacementChains.set(name, remaining);
+        }
+    };
+    const revokeState = (api, state) => {
+        state.active = false;
+        activeOwnerTokens.delete(state.ownerToken);
+        for (const instance of state.compositionInstances ?? [])
+            void instance.dispose();
+        state.compositionInstances?.clear();
+        const definitionBinding = options.composition;
+        definitionBinding?.disposeDefinitions?.(Array.from(state.compositionDefinitions ?? []));
+        state.compositionDefinitions?.clear();
+        cancelOwnedOperations(state.ownerToken, state.owner);
+        cleanupArtifacts(state.ownerToken);
+        cleanupStateWatchers(state.ownerToken);
+        cleanupDiagnostics(state.owner);
+        cleanupPluginCapabilities(state.ownerToken);
+        cleanupContributionPoints(state.ownerToken);
+        cleanupLifecycle(state.ownerToken);
+        cleanupRegisteredCapabilities(state.ownerToken);
+        apiStates.delete(api);
+    };
+    const cleanupContributionPoints = (ownerToken) => {
+        for (const [key, point] of contributionPoints) {
+            if (point.ownerToken === ownerToken)
+                contributionPoints.delete(key);
+            for (const [id, entry] of point.entries) {
+                if (entry.ownerToken === ownerToken)
+                    point.entries.delete(id);
+            }
+            for (const [id, subscriber] of point.subscribers) {
+                if (subscriber.ownerToken === ownerToken)
+                    point.subscribers.delete(id);
+            }
+        }
+    };
+    const closeLifecycleRegistrationQueue = (registration) => {
+        const queue = registration.queue;
+        if (!queue)
+            return;
+        queue.close();
+        void queue
+            .drain()
+            .then(() => lifecycleDeliveryQueues.delete(queue));
+    };
+    const cleanupLifecycle = (ownerToken) => {
+        for (const [key, stored] of lifecycleDefinitions) {
+            if (stored.ownerToken === ownerToken)
+                lifecycleDefinitions.delete(key);
+        }
+        for (const [key, registrations] of lifecycleRegistrations) {
+            for (const [id, registration] of registrations) {
+                if (registration.ownerToken === ownerToken) {
+                    closeLifecycleRegistrationQueue(registration);
+                    registrations.delete(id);
+                }
+            }
+            if (registrations.size === 0)
+                lifecycleRegistrations.delete(key);
+        }
+    };
+    const cleanupStateWatchers = (ownerToken) => {
+        for (const [owner, watchers] of stateWatchers) {
+            for (const [id, watcher] of watchers)
+                if (watcher.ownerToken === ownerToken)
+                    watchers.delete(id);
+            if (watchers.size === 0)
+                stateWatchers.delete(owner);
+        }
+    };
+    const cleanupDiagnostics = (owner) => {
+        for (const span of spans.values()) {
+            if (span.pluginId === owner && span.status === "running") {
+                span.status = "cancelled";
+                span.endedAt = clock();
+            }
+        }
+    };
+    const assertStateKey = (key) => {
+        if (typeof key !== "string" || !key.trim())
+            throw new Error("State key must be a non-empty string");
+    };
+    const assertStateOptions = (options) => {
+        if (options?.expectedRevision !== undefined &&
+            (!Number.isSafeInteger(options.expectedRevision) || options.expectedRevision < 0)) {
+            throw new Error("State expectedRevision must be a non-negative safe integer");
+        }
+    };
+    const stateSnapshot = (key, state) => detachedSnapshot({ key, revision: state.revision, value: state.value });
+    const dispatchStateChange = (watchers, owner, change) => {
+        if (!watchers)
+            return;
+        for (const watcher of watchers.values()) {
+            if (watcher.prefix !== undefined && !change.key.startsWith(watcher.prefix))
+                continue;
+            if (!activeOwnerTokens.has(watcher.ownerToken))
+                continue;
+            try {
+                watcher.handler(detachedSnapshot(change));
+            }
+            catch (error) {
+                recordLog("error", owner, "State watcher failed", { key: change.key }, error);
+            }
+        }
+    };
+    const notifyStateWatchers = (owner, change) => dispatchStateChange(stateWatchers.get(owner), owner, change);
+    const recordLog = (level, owner, message, fields, cause) => {
+        if (typeof message !== "string" || !message.trim())
+            throw new Error("Logger message must be non-empty");
+        if (fields !== undefined && !isPluginConfigValue(fields))
+            throw new Error("Logger fields must be serializable");
+        const record = {
+            version: 1,
+            level,
+            message,
+            pluginId: owner,
+            timestamp: clock(),
+            ...(options.session === undefined ? {} : { sessionId: options.session.getSessionId() }),
+            ...(fields === undefined ? {} : { fields: detachedSnapshot(fields) }),
+            ...(cause === undefined ? {} : { cause: detachedSnapshot(cause) }),
+        };
+        logs.push(record);
+        // 插件日志宿主转发（设计 §7.2）：入环后同步转发一次。回调抛错直接吞掉——
+        // 与 notifyToolRegistryChange 同守"观察者故障不打断调用方"的边界，但错误
+        // 通道不同：不引入无读者的计数，也绝不经 recordLog 再记录（回调契约禁止
+        // 内部调用 LoggerAPI，防自递归）。
+        if (options.onLogRecord) {
+            try {
+                options.onLogRecord(record);
+            }
+            catch {
+                // Swallowed by contract: a failing host sink must never break the
+                // logger contract nor recurse back through recordLog.
+            }
+        }
+    };
+    /**
+     * 工具表变更钩子：宿主注入 onToolRegistryChange 后，工具表每次变更（注册、
+     * 同名替换、卸载、替换链恢复）同步调用一次。回调失败只记运行时日志，不回传
+     * 注册/卸载路径——宿主观察者故障不得打断注册本身（与 onOutputArtifactCommit
+     * 的观察者容错通道一致）。缺省不传 = 行为不变。
+     */
+    const notifyToolRegistryChange = (owner, name) => {
+        if (!options.onToolRegistryChange)
+            return;
+        try {
+            options.onToolRegistryChange();
+        }
+        catch (error) {
+            recordLog("error", owner, "Tool registry change observer failed", { tool: name }, error);
+        }
+    };
+    const ownerStateViewFor = (owner) => ({
+        conflictScope: owner,
+        pluginId: owner,
+        watchScope: owner,
+        readStored: (key) => stateByOwner.get(owner)?.get(key),
+        listEntries: () => Array.from(stateByOwner.get(owner)?.entries() ?? []),
+        ensureNamespace: () => {
+            const namespace = stateByOwner.get(owner) ?? new Map();
+            stateByOwner.set(owner, namespace);
+            return namespace;
+        },
+        ensureRevisions: () => {
+            const revisions = stateRevisionsByOwner.get(owner) ?? new Map();
+            stateRevisionsByOwner.set(owner, revisions);
+            return revisions;
+        },
+        ensureWatchers: () => {
+            const watchers = stateWatchers.get(owner) ?? new Map();
+            stateWatchers.set(owner, watchers);
+            return watchers;
+        },
+        removeWatcher: (watchers, id) => {
+            watchers.delete(id);
+            if (watchers.size === 0)
+                stateWatchers.delete(owner);
+        },
+        notify: (change) => notifyStateWatchers(owner, change),
+    });
+    const instanceStateViewFor = (owner, instanceId) => ({
+        conflictScope: `${owner}/${instanceId}`,
+        pluginId: owner,
+        watchScope: `${owner}/${instanceId}`,
+        readStored: (key) => stateByInstance.get(owner)?.get(instanceId)?.get(key),
+        listEntries: () => Array.from(stateByInstance.get(owner)?.get(instanceId)?.entries() ?? []),
+        ensureNamespace: () => {
+            const ownerNamespaces = stateByInstance.get(owner) ?? new Map();
+            stateByInstance.set(owner, ownerNamespaces);
+            const namespace = ownerNamespaces.get(instanceId) ?? new Map();
+            ownerNamespaces.set(instanceId, namespace);
+            return namespace;
+        },
+        ensureRevisions: () => {
+            const ownerRevisions = stateRevisionsByInstance.get(owner) ?? new Map();
+            stateRevisionsByInstance.set(owner, ownerRevisions);
+            const revisions = ownerRevisions.get(instanceId) ?? new Map();
+            ownerRevisions.set(instanceId, revisions);
+            return revisions;
+        },
+        ensureWatchers: () => {
+            const ownerWatchers = stateWatchersByInstance.get(owner) ?? new Map();
+            stateWatchersByInstance.set(owner, ownerWatchers);
+            const watchers = ownerWatchers.get(instanceId) ?? new Map();
+            ownerWatchers.set(instanceId, watchers);
+            return watchers;
+        },
+        removeWatcher: (watchers, id) => {
+            watchers.delete(id);
+            if (watchers.size === 0)
+                stateWatchersByInstance.get(owner)?.delete(instanceId);
+        },
+        notify: (change) => dispatchStateChange(stateWatchersByInstance.get(owner)?.get(instanceId), owner, change),
+    });
+    /**
+     * One StateAPI implementation shared by the owner namespace and every
+     * composition instance namespace: the same key validation, CAS, detached
+     * snapshots, watcher notification, and registration lifecycle.
+     */
+    const createStateApiFor = (view, ownerToken, assertUsable, own) => ({
+        get: (key) => {
+            assertUsable();
+            assertStateKey(key);
+            const value = view.readStored(key);
+            return value ? stateSnapshot(key, value) : undefined;
+        },
+        set: (key, value, options) => {
+            assertUsable();
+            assertStateKey(key);
+            assertStateOptions(options);
+            if (!isPluginConfigValue(value))
+                throw new Error("State value must be serializable");
+            const namespace = view.ensureNamespace();
+            const revisions = view.ensureRevisions();
+            const currentRevision = revisions.get(key) ?? 0;
+            if (options?.expectedRevision !== undefined && options.expectedRevision !== currentRevision)
+                throw new Error(`State revision conflict: ${view.conflictScope}/${key}`);
+            const revision = currentRevision + 1;
+            revisions.set(key, revision);
+            namespace.set(key, { revision, value: detachedSnapshot(value) });
+            view.notify({
+                pluginId: view.pluginId,
+                key,
+                revision,
+                value: detachedSnapshot(value),
+                ...(options?.operationId === undefined ? {} : { operationId: options.operationId }),
+                ...(options?.correlationId === undefined ? {} : { correlationId: options.correlationId }),
+            });
+            return revision;
+        },
+        delete: (key, options) => {
+            assertUsable();
+            assertStateKey(key);
+            assertStateOptions(options);
+            const namespace = view.ensureNamespace();
+            const revisions = view.ensureRevisions();
+            const currentRevision = revisions.get(key) ?? 0;
+            if (options?.expectedRevision !== undefined && options.expectedRevision !== currentRevision)
+                throw new Error(`State revision conflict: ${view.conflictScope}/${key}`);
+            const revision = currentRevision + 1;
+            revisions.set(key, revision);
+            namespace.delete(key);
+            view.notify({
+                pluginId: view.pluginId,
+                key,
+                revision,
+                ...(options?.operationId === undefined ? {} : { operationId: options.operationId }),
+                ...(options?.correlationId === undefined ? {} : { correlationId: options.correlationId }),
+            });
+            return revision;
+        },
+        list: (prefix) => {
+            assertUsable();
+            if (prefix !== undefined && typeof prefix !== "string")
+                throw new Error("State prefix must be a string");
+            return view
+                .listEntries()
+                .filter(([key]) => prefix === undefined || key.startsWith(prefix))
+                .sort(([a], [b]) => a.localeCompare(b))
+                .map(([key, value]) => stateSnapshot(key, value));
+        },
+        watch: (prefix, handler) => {
+            assertUsable();
+            if (prefix !== undefined && typeof prefix !== "string")
+                throw new Error("State prefix must be a string");
+            if (typeof handler !== "function")
+                throw new Error("State watcher requires a handler");
+            const watchers = view.ensureWatchers();
+            const sequence = ++stateWatcherSequence;
+            const id = createRuntimeId("state-watcher", sequence, `state-watcher:${view.watchScope}:${sequence}`);
+            watchers.set(id, { owner: view.pluginId, ownerToken, prefix, handler });
+            return own(createDisposableRegistration("state-watcher", () => {
+                view.removeWatcher(watchers, id);
+            }, id));
+        },
+    });
+    /**
+     * Drop one instance namespace (data, revisions, watchers); instance ids are
+     * unique per composition runtime. Clearing the watch table is defense in
+     * depth: registrations are tracked to the operation lifecycle and normally
+     * dispose themselves before the instance does, so the table is usually
+     * empty here — keep the cleanup in case that tracking ever changes.
+     */
+    const clearInstanceState = (owner, instanceId) => {
+        const namespaces = stateByInstance.get(owner);
+        namespaces?.delete(instanceId);
+        if (namespaces?.size === 0)
+            stateByInstance.delete(owner);
+        const revisions = stateRevisionsByInstance.get(owner);
+        revisions?.delete(instanceId);
+        if (revisions?.size === 0)
+            stateRevisionsByInstance.delete(owner);
+        const watchers = stateWatchersByInstance.get(owner);
+        watchers?.delete(instanceId);
+        if (watchers?.size === 0)
+            stateWatchersByInstance.delete(owner);
+    };
+    // Instance ids are unique per composition runtime, so one runtime-level
+    // id-to-owner index lets every registered clearer resolve the namespace that
+    // must be dropped; clearers from unrelated runtimes find no entry and no-op.
+    const instanceStateOwners = new Map();
+    const clearRegisteredInstanceState = (instanceId) => {
+        const owner = instanceStateOwners.get(instanceId);
+        if (owner === undefined)
+            return;
+        instanceStateOwners.delete(instanceId);
+        clearInstanceState(owner, instanceId);
+    };
+    if (options.composition) {
+        options.composition.addInstanceStateClearer?.(clearRegisteredInstanceState);
+    }
+    const validateOutputInput = (input) => {
+        if (!input || typeof input !== "object")
+            throw new OutputArtifactError("invalid_ref", "Artifact input is required");
+        for (const [name, value] of [
+            ["sessionId", input.sessionId],
+            ["operationId", input.operationId],
+            ["kind", input.kind],
+            ["mediaType", input.mediaType],
+        ]) {
+            if (typeof value !== "string" || !value.trim()) {
+                throw new OutputArtifactError("invalid_ref", `Artifact ${name} must be a non-empty string`);
+            }
+        }
+        if (typeof input.truncated !== "boolean") {
+            throw new OutputArtifactError("invalid_ref", "Artifact truncated must be a boolean");
+        }
+        if (!(input.data instanceof Uint8Array) &&
+            (!input.data || typeof input.data[Symbol.asyncIterator] !== "function")) {
+            throw new OutputArtifactError("invalid_ref", "Artifact data must be Uint8Array or AsyncIterable<Uint8Array>");
+        }
+    };
+    const validateOutputRef = (ref) => {
+        if (!ref || typeof ref !== "object" || typeof ref.artifactId !== "string" || !ref.artifactId) {
+            throw new OutputArtifactError("invalid_ref", "Artifact reference requires a non-empty artifactId");
+        }
+    };
+    /**
+     * 工具表同名替换链：name → 被替换的历史注册（栈，栈顶是最近被替换者）。
+     * 跨 owner 的重注册把现表项压栈，替换方注册 dispose 时弹出栈顶恢复（多层替换
+     * 成链，逐层恢复）；owner 已失效的记录直接跳过，不把已撤销的注册放回工具表。
+     */
+    const toolReplacementChains = new Map();
+    const restoreReplacedTool = (registry, name) => {
+        const chain = toolReplacementChains.get(name);
+        while (chain !== undefined && chain.length > 0) {
+            const restored = chain.pop();
+            if (restored === undefined)
+                break;
+            if (chain.length === 0)
+                toolReplacementChains.delete(name);
+            if (activeOwnerTokens.has(restored.ownerToken)) {
+                registry.set(name, restored);
+                return true;
+            }
+        }
+        return false;
+    };
+    const register = (kind, name, value, owner, ownerToken, registry, options) => {
+        const replaceable = options?.replaceable === true;
+        const tracksToolRegistry = registry === tools;
+        const entry = { owner, ownerToken, value };
+        if (registry.has(name)) {
+            if (!replaceable)
+                throw new Error(`${kind} is already registered: ${name}`);
+            const replaced = registry.get(name);
+            // 同 owner 重注册 = 更新自身注册，不进替换链；恢复语义只跨 owner 生效。
+            if (replaced.ownerToken !== ownerToken) {
+                const chain = toolReplacementChains.get(name) ?? [];
+                chain.push(replaced);
+                toolReplacementChains.set(name, chain);
+            }
+        }
+        registry.set(name, entry);
+        if (tracksToolRegistry)
+            notifyToolRegistryChange(owner, name);
+        const id = `registration:${owner}:${kind}:${name}`;
+        return createDisposableRegistration(kind, () => {
+            const current = registry.get(name);
+            // 已被后续注册接手：恢复责任随表项转移，本注册不再动表。
+            if (current !== undefined && current !== entry)
+                return;
+            let changed = current !== undefined;
+            registry.delete(name);
+            if (replaceable &&
+                restoreReplacedTool(registry, name)) {
+                changed = true;
+            }
+            if (changed && tracksToolRegistry)
+                notifyToolRegistryChange(owner, name);
+        }, id);
+    };
+    const listPluginCapabilities = (options) => Array.from(pluginCapabilities.values())
+        .filter((entry) => options?.kind === undefined || entry.declaration.kind === options.kind)
+        .sort((left, right) => {
+        const leftKey = capabilityKey(left.declaration.id, left.declaration.version);
+        const rightKey = capabilityKey(right.declaration.id, right.declaration.version);
+        return leftKey < rightKey ? -1 : leftKey > rightKey ? 1 : 0;
+    })
+        .map((entry) => Object.freeze({ declaration: detachedSnapshot(entry.declaration), owner: entry.owner }));
+    const assertRequiredPluginCapabilities = (manifest) => {
+        for (const requirement of manifest.requires ?? []) {
+            if (pluginCapabilities.has(capabilityKey(requirement.id, requirement.version)))
+                continue;
+            if (requirement.optional)
+                continue;
+            throw new Error(`Plugin capability is required but unavailable: ${requirement.id}@${requirement.version} (${manifest.id})`);
+        }
+    };
+    const listContributionEntries = (point) => Array.from(point.entries.values())
+        .filter((entry) => activeOwnerTokens.has(entry.ownerToken))
+        .sort((left, right) => stableTextCompare(left.id, right.id) || stableTextCompare(left.owner, right.owner))
+        .map(({ ownerToken: _, ...entry }) => detachedSnapshot(entry));
+    const notifyContributionSubscribers = async (point, event) => {
+        const results = await Promise.allSettled(Array.from(point.subscribers.values(), (subscriber) => {
+            if (!activeOwnerTokens.has(subscriber.ownerToken))
+                return Promise.resolve();
+            return Promise.resolve().then(() => subscriber.handler(detachedSnapshot(event)));
+        }));
+        const failures = results
+            .filter((result) => result.status === "rejected")
+            .map((result) => result.reason);
+        if (failures.length === 1)
+            throw failures[0];
+        if (failures.length > 1)
+            throw new AggregateError(failures, `Contribution event delivery failed: ${event.pointId}`);
+    };
+    const contributionPointFor = (point, owner, ownerToken, assertUsable, own) => {
+        const assertPointActive = () => {
+            assertUsable();
+            if (!activeOwnerTokens.has(point.ownerToken))
+                throw createRevokedCapabilityError(point.owner);
+        };
+        const pointId = point.definition.id;
+        const version = point.definition.version;
+        const lifecycle = point.definition.lifecycle ?? "observe";
+        return Object.freeze({
+            id: pointId,
+            version,
+            schema: point.definition.schema,
+            lifecycle,
+            async add(input) {
+                assertPointActive();
+                if (!input || typeof input.id !== "string" || !input.id.trim()) {
+                    throw new Error(`Contribution requires a non-empty id: ${pointId}`);
+                }
+                if (point.entries.has(input.id)) {
+                    throw new Error(`Contribution is already registered: ${pointId}@${version}:${input.id}`);
+                }
+                const value = detachedSnapshot(point.definition.validate(detachedSnapshot(input.value)));
+                const entry = Object.freeze({ id: input.id, pointId, version, owner, ownerToken, lifecycle, value });
+                point.entries.set(input.id, entry);
+                const registration = own(createDisposableRegistration("contribution", () => {
+                    if (point.entries.get(input.id) !== entry)
+                        return;
+                    point.entries.delete(input.id);
+                    if (point.subscribers.size === 0)
+                        return;
+                    return notifyContributionSubscribers(point, {
+                        pointId,
+                        version,
+                        action: "removed",
+                        contributionId: input.id,
+                        owner,
+                    });
+                }, `registration:${owner}:contribution:${pointId}@${version}:${input.id}`));
+                await notifyContributionSubscribers(point, {
+                    pointId,
+                    version,
+                    action: "added",
+                    contributionId: input.id,
+                    owner,
+                    entry: detachedSnapshot({
+                        id: entry.id,
+                        pointId: entry.pointId,
+                        version: entry.version,
+                        owner: entry.owner,
+                        lifecycle: entry.lifecycle,
+                        value: entry.value,
+                    }),
+                });
+                return Object.freeze({ id: input.id, pointId, version, owner, dispose: () => registration.dispose() });
+            },
+            async remove(id) {
+                assertPointActive();
+                const entry = point.entries.get(id);
+                if (!entry)
+                    throw new Error(`Contribution is not registered: ${pointId}@${version}:${id}`);
+                if (entry.ownerToken !== ownerToken)
+                    throw new Error(`Contribution can only be removed by its owner: ${pointId}@${version}:${id}`);
+                point.entries.delete(id);
+                await notifyContributionSubscribers(point, {
+                    pointId,
+                    version,
+                    action: "removed",
+                    contributionId: id,
+                    owner,
+                });
+            },
+            list: () => {
+                assertPointActive();
+                return listContributionEntries(point);
+            },
+            subscribe: (handler) => {
+                assertPointActive();
+                if (typeof handler !== "function")
+                    throw new Error(`Contribution subscriber must be callable: ${pointId}`);
+                const sequence = ++contributionSubscriptionSequence;
+                const id = createRuntimeId("contribution-subscription", sequence, `contribution-subscription:${owner}:${pointId}@${version}:${sequence}`);
+                point.subscribers.set(id, { ownerToken, handler });
+                return own(createDisposableRegistration("contribution-subscription", () => {
+                    point.subscribers.delete(id);
+                }, id));
+            },
+        });
+    };
+    const lifecycleReference = (event, version) => {
+        if (typeof event === "string") {
+            if (typeof version !== "number" || !Number.isSafeInteger(version) || version < 1) {
+                throw new Error("Lifecycle event version must be provided as a positive safe integer");
+            }
+            return { id: event, version };
+        }
+        if (!event || typeof event !== "object" || typeof event.id !== "string" || !event.id.trim()) {
+            throw new Error("Lifecycle event reference requires a non-empty id");
+        }
+        if (!Number.isSafeInteger(event.version) || event.version < 1) {
+            throw new Error("Lifecycle event version must be a positive safe integer");
+        }
+        return { id: event.id, version: event.version };
+    };
+    const lifecycleDefinitionFor = (event, version) => {
+        const reference = lifecycleReference(event, version);
+        const stored = lifecycleDefinitions.get(lifecycleEventKey(reference.id, reference.version));
+        if (!stored || !activeOwnerTokens.has(stored.ownerToken)) {
+            throw new Error(`Lifecycle event is not defined: ${reference.id}@${reference.version}`);
+        }
+        return stored;
+    };
+    const lifecycleRegistration = (kind, event, handler, version, owner, ownerToken, assertUsable, own, deliveryOptions) => {
+        assertUsable();
+        if (!lifecycleRegistrationKinds.has(kind) || typeof handler !== "function") {
+            throw new Error(`Lifecycle ${kind} registration requires a callable handler`);
+        }
+        const stored = lifecycleDefinitionFor(event, version);
+        if (stored.definition.allowedRegistrationKinds?.includes(kind) === false) {
+            throw new Error(`Lifecycle ${kind} registration is not allowed: ${stored.definition.id}`);
+        }
+        if (kind === "transform" &&
+            !(stored.definition.allowedPhases ?? [stored.definition.phase]).includes("candidate")) {
+            throw new Error(`Lifecycle transform requires a candidate event: ${stored.definition.id}`);
+        }
+        if (kind === "execute" && !(stored.definition.allowedPhases ?? [stored.definition.phase]).includes("committed")) {
+            throw new Error(`Lifecycle execute requires a committed event: ${stored.definition.id}`);
+        }
+        if (kind === "after-commit" &&
+            !(stored.definition.allowedPhases ?? [stored.definition.phase]).includes("committed")) {
+            throw new Error(`Lifecycle after-commit requires a committed event: ${stored.definition.id}`);
+        }
+        if (deliveryOptions !== undefined && kind !== "observe" && kind !== "after-commit") {
+            throw new Error(`Lifecycle delivery options are only supported for observation registrations: ${stored.definition.id}`);
+        }
+        const key = lifecycleEventKey(stored.definition.id, stored.definition.version);
+        const sequence = ++lifecycleRegistrationSequence;
+        const id = createRuntimeId("lifecycle-registration", sequence, `lifecycle:${owner}:${kind}:${key}:${sequence}`);
+        const registration = {
+            id,
+            owner,
+            ownerToken,
+            kind,
+            sequence: lifecycleRegistrationSequence,
+            handler,
+            delivery: Object.freeze({
+                mode: deliveryOptions === undefined ? "inline" : "bounded-queue",
+                ...deliveryOptions,
+            }),
+        };
+        if (deliveryOptions !== undefined) {
+            const queue = createLifecycleDeliveryQueue({
+                maxPendingEvents: deliveryOptions.maxPendingEvents,
+                maxPendingBytes: deliveryOptions.maxPendingBytes,
+                measureBytes: (delivery) => {
+                    const serialized = JSON.stringify(delivery.event);
+                    if (serialized === undefined)
+                        throw new Error("Lifecycle event is not serializable");
+                    return new TextEncoder().encode(serialized).byteLength || 1;
+                },
+                deliver: (delivery) => {
+                    const registered = {
+                        owner: registration.owner,
+                        ownerToken: registration.ownerToken,
+                        value: registration.handler,
+                    };
+                    return invokeRegisteredCapabilityWithSignal(registered, delivery.signal, (value) => value(detachedSnapshot(delivery.event), delivery.signal));
+                },
+                overflowCode: stored.definition.id === "model.stream"
+                    ? "model_stream_backpressure_overflow"
+                    : "lifecycle_delivery_backpressure_overflow",
+            });
+            registration.queue = queue;
+            lifecycleDeliveryQueues.add(queue);
+        }
+        const registrations = lifecycleRegistrations.get(key) ?? new Map();
+        registrations.set(id, registration);
+        lifecycleRegistrations.set(key, registrations);
+        return own(createDisposableRegistration(`lifecycle-${kind}`, () => {
+            if (registrations.get(id) !== registration)
+                return;
+            const queue = registration.queue;
+            queue?.close();
+            if (queue)
+                void queue
+                    .drain()
+                    .then(() => lifecycleDeliveryQueues.delete(queue));
+            registrations.delete(id);
+            if (registrations.size === 0)
+                lifecycleRegistrations.delete(key);
+        }, id));
+    };
+    const apiFor = (manifest) => {
+        // Snapshot the caller-owned manifest before validation so later mutation
+        // cannot alter capability declarations or required-capability checks.
+        const manifestSnapshot = detachedSnapshot(manifest);
+        assertManifest(manifestSnapshot, host);
+        assertRequiredPluginCapabilities(manifestSnapshot);
+        const config = createPluginConfig(manifestSnapshot.config);
+        const apiManifest = detachedSnapshot({ ...manifestSnapshot, config });
+        const owner = manifestSnapshot.id;
+        const ownerToken = Symbol(owner);
+        const state = {
+            active: true,
+            owner,
+            ownerToken,
+            compositionInstances: new Set(),
+            compositionDefinitions: new Set(),
+        };
+        activeOwnerTokens.add(ownerToken);
+        const assertUsable = () => {
+            if (!state.active)
+                throw new Error(`Capability API is revoked: ${owner}`);
+        };
+        const compositionLifecycleDispatcher = (event) => {
+            // The dispatcher is captured by this API state and passed to each
+            // instance it creates. Never resolve ownership by searching the shared
+            // composition runtime: another CapabilityRuntime may use the same one.
+            if (!state.active || !activeOwnerTokens.has(ownerToken) || event.owner !== owner)
+                return;
+            if (event.event === "start") {
+                statuses.set(event.operationId, "running");
+                reportOperationStart(event.operationId, event.operationKind, [ownerToken]);
+            }
+            else if (event.event === "step") {
+                if (event.progress === undefined || event.step === undefined)
+                    return;
+                reportOperationStep(event.operationId, event.operationKind, [ownerToken], event.progress, event.step);
+            }
+            else if (event.event === "cancel") {
+                statuses.set(event.operationId, "cancelled");
+                reportOperationCancel(event.operationId, event.operationKind, [ownerToken]);
+            }
+            else {
+                const status = event.status ?? "failed";
+                statuses.set(event.operationId, status);
+                reportOperationEnd(event.operationId, event.operationKind, status, [ownerToken]);
+            }
+        };
+        const own = (registration) => {
+            assertUsable();
+            const registrations = pluginRegistrations.get(owner) ?? new Set();
+            registrations.add(registration);
+            pluginRegistrations.set(owner, registrations);
+            return registration;
+        };
+        /**
+         * Counterpart of {@link own} for registrations released by their own
+         * lifecycle (a disposed agent task): a registration set that still holds
+         * them would pin the released resource for the rest of the plugin's life.
+         */
+        const unown = (registration) => {
+            const registrations = pluginRegistrations.get(owner);
+            if (!registrations)
+                return;
+            registrations.delete(registration);
+            if (registrations.size === 0)
+                pluginRegistrations.delete(owner);
+        };
+        const logger = {
+            debug: (message, fields) => {
+                assertUsable();
+                recordLog("debug", owner, message, fields);
+            },
+            info: (message, fields) => {
+                assertUsable();
+                recordLog("info", owner, message, fields);
+            },
+            warn: (message, fields) => {
+                assertUsable();
+                recordLog("warn", owner, message, fields);
+            },
+            error: (message, fields, cause) => {
+                assertUsable();
+                recordLog("error", owner, message, fields, cause);
+            },
+        };
+        const diagnostics = {
+            start: (name, attributes, parentSpanId) => {
+                assertUsable();
+                if (typeof name !== "string" || !name.trim())
+                    throw new Error("Diagnostic span name must be non-empty");
+                if (attributes !== undefined && !isPluginConfigValue(attributes))
+                    throw new Error("Diagnostic attributes must be serializable");
+                if (parentSpanId !== undefined && (typeof parentSpanId !== "string" || !parentSpanId.trim()))
+                    throw new Error("Diagnostic parentSpanId must be non-empty");
+                const spanSequenceValue = ++spanSequence;
+                const spanId = createRuntimeId("span", spanSequenceValue, `span:${owner}:${spanSequenceValue}`);
+                const traceId = parentSpanId
+                    ? (spans.get(parentSpanId)?.traceId ??
+                        (() => {
+                            const sequence = ++traceSequence;
+                            return createRuntimeId("trace", sequence, `trace:${sequence}`);
+                        })())
+                    : (() => {
+                        const sequence = ++traceSequence;
+                        return createRuntimeId("trace", sequence, `trace:${sequence}`);
+                    })();
+                const snapshot = {
+                    version: 1,
+                    traceId,
+                    spanId,
+                    ...(parentSpanId === undefined ? {} : { parentSpanId }),
+                    name,
+                    pluginId: owner,
+                    ...(options.session === undefined ? {} : { sessionId: options.session.getSessionId() }),
+                    startedAt: clock(),
+                    status: "running",
+                    attributes: detachedSnapshot(attributes ?? {}),
+                };
+                spans.set(spanId, snapshot);
+                let ended = false;
+                const span = {
+                    traceId,
+                    spanId,
+                    annotate(fields) {
+                        assertUsable();
+                        if (ended)
+                            throw new Error(`Diagnostic span is already ended: ${spanId}`);
+                        if (!fields || typeof fields !== "object" || Array.isArray(fields) || !isPluginConfigValue(fields))
+                            throw new Error("Diagnostic annotations must be a plain object");
+                        const current = spans.get(spanId);
+                        if (!current)
+                            throw new Error(`Diagnostic span is not available: ${spanId}`);
+                        current.attributes = detachedSnapshot({
+                            ...current.attributes,
+                            ...fields,
+                        });
+                    },
+                    end(outcome = { status: "ok" }) {
+                        assertUsable();
+                        if (ended)
+                            throw new Error(`Diagnostic span is already ended: ${spanId}`);
+                        if (!["ok", "error", "cancelled"].includes(outcome.status))
+                            throw new Error("Diagnostic span status is invalid");
+                        if (outcome.result !== undefined && !isPluginConfigValue(outcome.result))
+                            throw new Error("Diagnostic span result must be serializable");
+                        const current = spans.get(spanId);
+                        if (!current)
+                            throw new Error(`Diagnostic span is not available: ${spanId}`);
+                        ended = true;
+                        current.status = outcome.status;
+                        current.endedAt = clock();
+                        if (outcome.result !== undefined)
+                            current.result = detachedSnapshot(outcome.result);
+                        if (outcome.cause !== undefined)
+                            current.cause = detachedSnapshot(outcome.cause);
+                    },
+                };
+                own(createDisposableRegistration("diagnostic-span", () => {
+                    if (!ended) {
+                        const current = spans.get(spanId);
+                        if (current?.status === "running") {
+                            current.status = "cancelled";
+                            current.endedAt = clock();
+                        }
+                    }
+                }, `registration:${owner}:diagnostic-span:${spanId}`));
+                return span;
+            },
+        };
+        const stateApi = createStateApiFor(ownerStateViewFor(owner), ownerToken, assertUsable, own);
+        /** Instance-private state namespace view for one composition instance; cleared on its disposal. */
+        const createInstanceStateApi = (instanceOwner, instanceId) => createStateApiFor(instanceStateViewFor(instanceOwner, instanceId), ownerToken, assertUsable, own);
+        const capabilities = {
+            provide(declaration, handler) {
+                assertUsable();
+                assertPluginCapabilityDeclarations([declaration], `Plugin capability declaration: ${owner}`);
+                if (typeof handler !== "function")
+                    throw new Error("Plugin capability provider requires a callable handler");
+                const declared = manifestSnapshot.provides?.some((item) => item.id === declaration.id && item.version === declaration.version && item.kind === declaration.kind);
+                if (!declared) {
+                    throw new Error(`Plugin capability must be declared by its manifest: ${declaration.id}@${declaration.version} (${owner})`);
+                }
+                const key = capabilityKey(declaration.id, declaration.version);
+                if (pluginCapabilities.has(key)) {
+                    throw new Error(`Plugin capability is already provided: ${declaration.id}@${declaration.version}`);
+                }
+                const registered = {
+                    declaration: detachedSnapshot(declaration),
+                    owner,
+                    ownerToken,
+                    handler: handler,
+                };
+                pluginCapabilities.set(key, registered);
+                return own(createDisposableRegistration("plugin-capability", () => {
+                    if (pluginCapabilities.get(key)?.ownerToken === ownerToken)
+                        pluginCapabilities.delete(key);
+                }, `registration:${owner}:plugin-capability:${declaration.id}@${declaration.version}`));
+            },
+            require(id, requireOptions) {
+                assertUsable();
+                assertPluginCapabilityId(id, "Plugin capability id");
+                const version = requireOptions?.version;
+                assertPluginCapabilityVersion(version, "Plugin capability version");
+                const registered = pluginCapabilities.get(capabilityKey(id, version));
+                if (!registered)
+                    throw new Error(`Plugin capability is not available: ${id}@${version}`);
+                const declaration = detachedSnapshot(registered.declaration);
+                return Object.freeze({
+                    declaration,
+                    owner: registered.owner,
+                    call: (input, callOptions) => {
+                        assertUsable();
+                        if (!activeOwnerTokens.has(registered.ownerToken)) {
+                            throw createRevokedCapabilityError(registered.owner);
+                        }
+                        const sequence = ++operationSequence;
+                        const operationId = createRuntimeId("capability-operation", sequence, `capability:${owner}:${id}@${version}:${sequence}`);
+                        const handle = trackOperation([ownerToken, registered.ownerToken], new RuntimeOperation(operationId, (value, context) => invokePluginCapability(registered, value, context.signal), detachedSnapshot(input), (status) => {
+                            statuses.set(operationId, status);
+                            if (status === "running") {
+                                reportCapabilityCall("start", operationId, owner, registered, [
+                                    ownerToken,
+                                    registered.ownerToken,
+                                ]);
+                            }
+                            else if (status === "cancelled") {
+                                reportCapabilityCall("cancel", operationId, owner, registered, [
+                                    ownerToken,
+                                    registered.ownerToken,
+                                ]);
+                            }
+                        }, (status) => reportCapabilityCall("end", operationId, owner, registered, [ownerToken, registered.ownerToken], status), () => false));
+                        statuses.set(operationId, handle.status());
+                        const signal = callOptions?.signal;
+                        if (signal) {
+                            if (signal.aborted)
+                                void handle.cancel(signal.reason);
+                            else
+                                signal.addEventListener("abort", () => void handle.cancel(signal.reason), { once: true });
+                        }
+                        return handle;
+                    },
+                });
+            },
+            list: listPluginCapabilities,
+        };
+        const contributions = {
+            define: (definition) => {
+                assertUsable();
+                const validated = validateContributionPointDefinition(definition);
+                const key = contributionPointKey(validated.id, validated.version);
+                if (contributionPoints.has(key))
+                    throw new Error(`Contribution point is already defined: ${key}`);
+                const point = {
+                    owner,
+                    ownerToken,
+                    definition: validated,
+                    entries: new Map(),
+                    subscribers: new Map(),
+                };
+                contributionPoints.set(key, point);
+                own(createDisposableRegistration("contribution-point", () => {
+                    if (contributionPoints.get(key) === point)
+                        contributionPoints.delete(key);
+                }, `registration:${owner}:contribution-point:${key}`));
+                return contributionPointFor(point, owner, ownerToken, assertUsable, own);
+            },
+            get: (id, version) => {
+                assertUsable();
+                const point = contributionPoints.get(contributionPointKey(id, version));
+                if (!point)
+                    throw new Error(`Contribution point is not defined: ${id}@${version}`);
+                return contributionPointFor(point, owner, ownerToken, assertUsable, own);
+            },
+            list: () => Array.from(contributionPoints.values())
+                .filter((point) => activeOwnerTokens.has(point.ownerToken))
+                .sort((left, right) => stableTextCompare(contributionPointKey(left.definition.id, left.definition.version), contributionPointKey(right.definition.id, right.definition.version)))
+                .map((point) => Object.freeze({
+                id: point.definition.id,
+                version: point.definition.version,
+                schema: point.definition.schema,
+                lifecycle: point.definition.lifecycle ?? "observe",
+                owner: point.owner,
+            })),
+        };
+        const agentTasks = new Set();
+        const createAgentTask = async (request) => {
+            assertUsable();
+            assertAgentTaskRequest(request);
+            const adapter = options.agents;
+            const session = options.session;
+            if (!adapter || !session)
+                throw new Error("Agent task capability is not available from this host");
+            const hostTask = await adapter.create(request);
+            try {
+                assertUsable();
+            }
+            catch (error) {
+                await hostTask.dispose();
+                throw error;
+            }
+            let task;
+            let registration;
+            let detachParentCascade = () => { };
+            try {
+                task = new RuntimeAgentTask(createRuntimeId("agent-task", ++agentTaskSequence, `agent-task:${owner}:${agentTaskSequence}:${runtimeInstanceSegment}`), session.getSessionId(), request, hostTask, assertUsable, host.features.includes("session-revision-v1"), options.agentResults, 
+                // Task disposal releases every runtime-side reference — the
+                // live-task set, the parent fence listener and the owner
+                // registration — so a long-lived parent session does not
+                // accumulate settled tasks (and their child session graphs)
+                // until runtime disposal.
+                () => {
+                    agentTasks.delete(task);
+                    detachParentCascade();
+                    if (registration)
+                        unown(registration);
+                });
+            }
+            catch (error) {
+                await hostTask.dispose();
+                throw error;
+            }
+            agentTasks.add(task);
+            detachParentCascade = attachParentCascade(task);
+            registration = own(createDisposableRegistration("agent-task", () => task.dispose(), `registration:${owner}:agent-task:${task.id}`));
+            return task;
+        };
+        // Parent-session cancel fence (D-044 §4.2): bind each task once to the
+        // signal current at creation time. Tasks created after the fence already
+        // fired are cancelled immediately; the host refreshes the fence epoch so
+        // later tasks bind to a fresh signal instead of the spent one.
+        const attachParentCascade = (task) => {
+            const signal = options.parentSignal?.();
+            if (!signal)
+                return () => { };
+            const cancelForParent = () => {
+                void task.cancel("parent session aborted").catch(() => { });
+            };
+            if (signal.aborted) {
+                cancelForParent();
+                return () => { };
+            }
+            signal.addEventListener("abort", cancelForParent, { once: true });
+            // The fence signal lives as long as its epoch, so the listener must be
+            // removable: an unremoved closure would retain the task for the whole
+            // epoch even after the task settled and was disposed.
+            return () => signal.removeEventListener("abort", cancelForParent);
+        };
+        /**
+         * Durable replay read: loads the terminal record persisted at settle from
+         * the host-injected durable store. The guarded option pair guarantees the
+         * agentResults option is present whenever the replay feature is declared,
+         * so a missing store only means the host never opted into replay.
+         */
+        const createAgentResultReader = async (taskId) => {
+            const record = options.agentResults?.store.loadArtifact({
+                artifactId: `agent-task:${taskId}`,
+            });
+            return record ? record.data : undefined;
+        };
+        /**
+         * 父→子引导（D-060 S4，程序面）：对运行中的 agent task 投递一条有界引导消息。
+         * 只在**本 runtime 的活跃任务**里定位（越界即"不存在"）；宿主会话无 steer 面
+         * 时按任务侧结构化错误透传。
+         */
+        const createAgentTaskSteer = async (request) => {
+            assertUsable();
+            const task = Array.from(agentTasks).find((candidate) => candidate.id === request.taskId);
+            if (task === undefined) {
+                throw Object.assign(new Error(`no live agent task ${request.taskId} in this runtime`), {
+                    code: "subagent_unknown_task",
+                });
+            }
+            await task.steer(request.text);
+        };
+        const output = {
+            put: async (input, options) => {
+                assertUsable();
+                validateOutputInput(input);
+                const signal = options?.signal;
+                const throwIfAborted = () => {
+                    if (signal?.aborted) {
+                        throw new OutputArtifactError("cancelled", `Artifact write cancelled: ${String(signal.reason ?? "cancelled")}`);
+                    }
+                };
+                throwIfAborted();
+                const chunks = [];
+                let sizeBytes = 0;
+                if (input.data instanceof Uint8Array) {
+                    chunks.push(new Uint8Array(input.data));
+                    sizeBytes = input.data.byteLength;
+                }
+                else {
+                    for await (const chunk of input.data) {
+                        throwIfAborted();
+                        if (!(chunk instanceof Uint8Array)) {
+                            throw new OutputArtifactError("invalid_ref", "Artifact stream yielded a non-Uint8Array chunk");
+                        }
+                        const copy = new Uint8Array(chunk);
+                        chunks.push(copy);
+                        sizeBytes += copy.byteLength;
+                    }
+                }
+                throwIfAborted();
+                const bytes = new Uint8Array(sizeBytes);
+                let offset = 0;
+                for (const chunk of chunks) {
+                    bytes.set(chunk, offset);
+                    offset += chunk.byteLength;
+                }
+                // A stream may yield after the plugin has been revoked. Never commit
+                // bytes after the lifecycle boundary has closed.
+                assertUsable();
+                const sequence = ++artifactSequence;
+                const artifactId = createRuntimeId("artifact", sequence, `artifact:${owner}:${sequence}`);
+                const ref = {
+                    sessionId: input.sessionId,
+                    operationId: input.operationId,
+                    artifactId,
+                    kind: input.kind,
+                    mediaType: input.mediaType,
+                    sizeBytes,
+                    truncated: input.truncated,
+                    createdAt: clock(),
+                };
+                outputArtifacts.set(artifactId, { ref, bytes, ownerToken });
+                // Durable mirroring is a host concern, not a runtime one: the commit
+                // observer receives the same bytes reachable through stat/read. An
+                // observer failure is recorded but never fails the committed artifact,
+                // and cleanup/revoke intentionally do not re-emit (durable records are
+                // meant to outlive the in-memory lifecycle boundary).
+                if (onOutputArtifactCommit) {
+                    try {
+                        onOutputArtifactCommit({ ref: { ...ref }, bytes });
+                    }
+                    catch (error) {
+                        recordLog("error", owner, "Output artifact commit observer failed", { artifactId }, error);
+                    }
+                }
+                return { ...ref };
+            },
+            stat: async (ref) => {
+                assertUsable();
+                validateOutputRef(ref);
+                const artifact = outputArtifacts.get(ref.artifactId);
+                if (!artifact) {
+                    throw new OutputArtifactError("not_found", `Output artifact is not available: ${ref.artifactId}`);
+                }
+                if (ref.sessionId !== artifact.ref.sessionId ||
+                    ref.operationId !== artifact.ref.operationId ||
+                    ref.kind !== artifact.ref.kind ||
+                    ref.mediaType !== artifact.ref.mediaType ||
+                    ref.sizeBytes !== artifact.ref.sizeBytes ||
+                    ref.truncated !== artifact.ref.truncated ||
+                    ref.createdAt !== artifact.ref.createdAt) {
+                    throw new OutputArtifactError("invalid_ref", `Output artifact reference does not match: ${ref.artifactId}`);
+                }
+                return { ...artifact.ref };
+            },
+            read: async (ref, options) => {
+                assertUsable();
+                const stored = await output.stat(ref);
+                const artifact = outputArtifacts.get(stored.artifactId);
+                if (!artifact)
+                    throw new OutputArtifactError("not_found", `Output artifact is not available: ${stored.artifactId}`);
+                const offset = options?.offset ?? 0;
+                const maxBytes = options?.maxBytes ?? artifact.bytes.byteLength;
+                if (!Number.isInteger(offset) || offset < 0) {
+                    throw new OutputArtifactError("invalid_ref", "Artifact read offset must be a non-negative integer");
+                }
+                if (!Number.isInteger(maxBytes) || maxBytes <= 0) {
+                    throw new OutputArtifactError("invalid_ref", "Artifact read maxBytes must be a positive integer");
+                }
+                const end = Math.min(offset + maxBytes, artifact.bytes.byteLength);
+                const data = artifact.bytes.slice(Math.min(offset, artifact.bytes.byteLength), end);
+                const eof = end >= artifact.bytes.byteLength;
+                return { data, ...(eof ? {} : { nextOffset: end }), eof };
+            },
+        };
+        const compositionHostPrimitives = ({ instance, operationId, signal }) => {
+            const sessionApi = options.session;
+            const session = sessionApi
+                ? Object.freeze({
+                    version: 1,
+                    getSessionId: () => sessionApi.getSessionId(),
+                    ...(sessionApi.getRevision ? { getRevision: () => sessionApi.getRevision() } : {}),
+                    getMessages: () => sessionApi.getMessages(),
+                    getBranchEntries: () => sessionApi.getBranchEntries(),
+                    isIdle: () => sessionApi.isIdle(),
+                    prompt: (text) => sessionApi.prompt(text),
+                    ...(sessionApi.steer ? { steer: (text) => sessionApi.steer(text) } : {}),
+                    abort: () => sessionApi.abort(),
+                    waitForIdle: () => sessionApi.waitForIdle(),
+                    appendEntry: (customType, data) => sessionApi.appendEntry(customType, data),
+                })
+                : undefined;
+            const context = host.features.includes("context") && sessionApi?.getContextSnapshot && sessionApi.commitContext
+                ? Object.freeze({
+                    version: 1,
+                    get: () => sessionApi.getContextSnapshot(),
+                    commit: async (request) => {
+                        if (request.operationId !== operationId) {
+                            throw new Error(`Agent context operationId must match active operation: ${operationId}`);
+                        }
+                        return sessionApi.commitContext({ ...request, signal: request.signal ?? signal });
+                    },
+                })
+                : undefined;
+            const state = host.features.includes("plugin-state-v1")
+                ? Object.freeze({
+                    ...stateApi,
+                    set: (key, value, options) => {
+                        if (options?.operationId !== undefined && options.operationId !== operationId) {
+                            throw new Error(`Agent state operationId must match active operation: ${operationId}`);
+                        }
+                        return stateApi.set(key, value, { ...options, operationId });
+                    },
+                    delete: (key, options) => {
+                        if (options?.operationId !== undefined && options.operationId !== operationId) {
+                            throw new Error(`Agent state operationId must match active operation: ${operationId}`);
+                        }
+                        return stateApi.delete(key, { ...options, operationId });
+                    },
+                })
+                : undefined;
+            const instanceState = host.features.includes("plugin-state-v1")
+                ? createInstanceStateApi(owner, instance.id)
+                : undefined;
+            const sessionId = options.session?.getSessionId();
+            const scopedOutput = guardedOutput(output, assertUsable);
+            const artifact = host.features.includes("output-artifacts") && sessionId !== undefined
+                ? Object.freeze({
+                    put: (input, putOptions) => {
+                        if (input.sessionId !== sessionId || input.operationId !== operationId) {
+                            throw new OutputArtifactError("invalid_ref", `Agent artifact must use active session and operation: ${operationId}`);
+                        }
+                        return scopedOutput.put(input, putOptions);
+                    },
+                    stat: async (ref) => {
+                        if (ref.sessionId !== sessionId || ref.operationId !== operationId) {
+                            throw new OutputArtifactError("invalid_ref", `Agent artifact must use active session and operation: ${operationId}`);
+                        }
+                        return scopedOutput.stat(ref);
+                    },
+                    read: async (ref, readOptions) => {
+                        if (ref.sessionId !== sessionId || ref.operationId !== operationId) {
+                            throw new OutputArtifactError("invalid_ref", `Agent artifact must use active session and operation: ${operationId}`);
+                        }
+                        return scopedOutput.read(ref, readOptions);
+                    },
+                })
+                : undefined;
+            const modelFacade = options.modelRuntime && sessionApi
+                ? Object.freeze({
+                    version: 1,
+                    get facts() {
+                        const runtime = options.modelRuntime;
+                        const resolved = runtime.getModelFacts();
+                        if (!resolved)
+                            throw new Error("No model is set on this session's agent");
+                        return resolved;
+                    },
+                    invocation: {
+                        invoke: async (input, signal) => {
+                            const runtime = options.modelRuntime;
+                            if (!runtime)
+                                throw new Error("Agent model runtime is not available");
+                            return runtime.invoke({
+                                ...(input.systemPrompt === undefined ? {} : { systemPrompt: input.systemPrompt }),
+                                prompt: input.prompt,
+                                ...(input.maxTokens === undefined ? {} : { maxTokens: input.maxTokens }),
+                                ...(input.thinkingLevel === undefined ? {} : { thinkingLevel: input.thinkingLevel }),
+                            }, { signal });
+                        },
+                    },
+                })
+                : undefined;
+            const toolFacade = host.features.includes("tools")
+                ? Object.freeze({
+                    version: 1,
+                    listTools: () => {
+                        assertUsable();
+                        return [...tools.entries()]
+                            .filter(([, entry]) => activeOwnerTokens.has(entry.ownerToken))
+                            .sort(([left], [right]) => stableTextCompare(left, right))
+                            .map(([name, entry]) => ({
+                            name,
+                            definition: definitionSnapshot(entry.value),
+                            source: entry.owner,
+                            readonlySafe: toolReadonlySafe(entry.value),
+                        }));
+                    },
+                    invokeTool: (name, input, invokeOptions) => {
+                        assertUsable();
+                        const registered = tools.get(name);
+                        if (!registered || !activeOwnerTokens.has(registered.ownerToken)) {
+                            throw new Error(`Agent tool is not registered: ${name}`);
+                        }
+                        return invokeRegisteredCapability(registered, (value) => invokeCapabilityTool(asHandler(value, "Tool"), input, toolExecutionContext, invokeOptions?.signal));
+                    },
+                })
+                : undefined;
+            return Object.freeze({
+                version: 1,
+                ...(session ? { session } : {}),
+                ...(context ? { context } : {}),
+                ...(state ? { state } : {}),
+                ...(instanceState ? { instanceState } : {}),
+                ...(artifact ? { artifact } : {}),
+                ...(modelFacade ? { model: modelFacade } : {}),
+                ...(toolFacade ? { tool: toolFacade } : {}),
+            });
+        };
+        const lifecycle = {
+            define(definition) {
+                assertUsable();
+                const normalized = validateLifecycleEventDefinition(definition);
+                const key = lifecycleEventKey(normalized.id, normalized.version);
+                if (lifecycleDefinitions.has(key))
+                    throw new Error(`Lifecycle event is already defined: ${key}`);
+                lifecycleDefinitions.set(key, { owner, ownerToken, definition: normalized });
+                const registration = own(createDisposableRegistration("lifecycle-definition", () => {
+                    const current = lifecycleDefinitions.get(key);
+                    if (current?.ownerToken !== ownerToken)
+                        return;
+                    lifecycleDefinitions.delete(key);
+                    const registrations = lifecycleRegistrations.get(key);
+                    if (registrations) {
+                        for (const registration of registrations.values())
+                            closeLifecycleRegistrationQueue(registration);
+                        lifecycleRegistrations.delete(key);
+                    }
+                }, `registration:${owner}:lifecycle-definition:${key}`));
+                void registration;
+                return normalized;
+            },
+            get(id, version) {
+                assertUsable();
+                return lifecycleDefinitionFor({ id, version }).definition;
+            },
+            registerObserve(event, handler, version, options) {
+                return lifecycleRegistration("observe", event, handler, version, owner, ownerToken, assertUsable, own, options);
+            },
+            registerTransform(event, handler, version) {
+                return lifecycleRegistration("transform", event, handler, version, owner, ownerToken, assertUsable, own);
+            },
+            registerExecute(event, handler, version) {
+                return lifecycleRegistration("execute", event, handler, version, owner, ownerToken, assertUsable, own);
+            },
+            registerAfterCommit(event, handler, version, options) {
+                return lifecycleRegistration("after-commit", event, handler, version, owner, ownerToken, assertUsable, own, options);
+            },
+        };
+        const api = {
+            manifest: apiManifest,
+            host: hostWithServices,
+            config,
+            ...(host.features.includes("logger-v1") ? { logger } : {}),
+            ...(host.features.includes("diagnostics-v1") ? { diagnostics } : {}),
+            ...(host.features.includes("plugin-state-v1") ? { state: stateApi } : {}),
+            ...(host.features.includes("runtime-inspector-v1")
+                ? { inspector: { snapshot: () => inspect() } }
+                : {}),
+            capabilities,
+            contributions,
+            lifecycle,
+            ...(hasSession && options.session
+                ? {
+                    session: guardedSession(options.session, assertUsable, {
+                        allowExport: hasSessionExport,
+                        allowRevision: hasSessionRevision,
+                    }),
+                }
+                : {}),
+            ...(host.features.includes("output-artifacts") ? { output: guardedOutput(output, assertUsable) } : {}),
+            ...(host.features.includes("credentials") && options.credentials
+                ? { credentials: guardedCredentials(options.credentials, assertUsable) }
+                : {}),
+            // agents 成员随 feature 在场即构建（构造期断言已保证 feature/选项配对），
+            // 各成员再按宿主注入逐项条件化：任务面跟 adapter，durable replay 跟
+            // agentResults 存储，回读面跟 reader/lister。
+            ...(host.features.includes("agents")
+                ? {
+                    agents: {
+                        // 任务面（create/steer）只在宿主注入 adapter 时存在；reader/lister-only
+                        // 宿主（承载退役切片 2：pooled 叶子/只读回读）的 agents 只承载回读，
+                        // 委派面由 delegate 的池化装配或宿主 adapter 提供。
+                        ...(options.agents === undefined
+                            ? {}
+                            : {
+                                create: createAgentTask,
+                                // 父→子引导（D-060 S4，程序面）：运行中任务的有界 steer。
+                                steer: createAgentTaskSteer,
+                            }),
+                        // durable replay 读取跟随 agentResults 存储（与 adapter 无关）：
+                        // serve 装配的重建读取面没有 adapter 也必须可用。
+                        ...(options.agentResults === undefined ? {} : { result: createAgentResultReader }),
+                        // 会话回读（D-060 S3）：宿主注入读取器才暴露；作用域由宿主强制。
+                        ...(options.agentSessionReader === undefined
+                            ? {}
+                            : {
+                                session: async (sessionId) => {
+                                    assertUsable();
+                                    return options.agentSessionReader?.(sessionId);
+                                },
+                            }),
+                        // 子会话盘点（D-060 模型面）：宿主注入列举器才暴露；只回本会话的子会话。
+                        ...(options.agentSessionLister === undefined
+                            ? {}
+                            : {
+                                list: async () => {
+                                    assertUsable();
+                                    return options.agentSessionLister?.() ?? [];
+                                },
+                            }),
+                    },
+                }
+                : {}),
+            // Session cancel fence (D-044 §4.2) as a public getter: consulted per
+            // call so plugins cascade against the current epoch signal, never a
+            // signal captured at API creation time. Absent when the host injects
+            // no parentSignal (behavior unchanged).
+            ...(options.parentSignal === undefined ? {} : { sessionAbortSignal: () => options.parentSignal?.() }),
+            // Host trace service (D-075 S4 second batch): the adapter rides
+            // `api.trace`, its budget overrides ride `api.traceSinkOptions`.
+            // Absent when the host injects no trace service.
+            ...(options.trace === undefined
+                ? {}
+                : {
+                    trace: options.trace.adapter,
+                    ...(options.trace.options === undefined ? {} : { traceSinkOptions: options.trace.options }),
+                }),
+            ...(host.features.includes("interaction") && options.interaction
+                ? { interaction: guardedInteraction(options.interaction, owner, assertUsable, own) }
+                : {}),
+            ...(host.features.includes("agent-composition-v1") && options.composition
+                ? {
+                    composition: guardedComposition(options.composition, assertUsable, (instance) => {
+                        state.compositionInstances?.add(instance);
+                        instanceStateOwners.set(instance.id, owner);
+                    }, (definition) => state.compositionDefinitions?.add(definition), compositionHostPrimitives, compositionLifecycleDispatcher, manifestSnapshot),
+                }
+                : {}),
+            registerTool(definition) {
+                assertUsable();
+                const name = capabilityName(definition, "Tool");
+                // 工具是唯一可替换的注册面：同名重注册 = 替换生效（后装载者赢），
+                // 被替换者入链，替换方 dispose 时逐层恢复（bootstrap 内建与第三方
+                // 插件因此可共存）。
+                return own(register("tool", name, definition, owner, ownerToken, tools, { replaceable: true }));
+            },
+            registerCommand(definition) {
+                assertUsable();
+                const command = validateCommandDefinition(definition);
+                return own(register("command", command.name, command, owner, ownerToken, commands));
+            },
+            registerOperation(name, handler) {
+                assertUsable();
+                if (!name)
+                    throw new Error("Operation requires a non-empty name");
+                return own(register("operation", name, handler, owner, ownerToken, operations));
+            },
+            registerRpcMethod(name, handler) {
+                assertUsable();
+                if (!name)
+                    throw new Error("RPC method requires a non-empty name");
+                return own(register("rpc", name, handler, owner, ownerToken, rpcMethods));
+            },
+            registerContextStrategy(name, strategy) {
+                assertUsable();
+                if (!name)
+                    throw new Error("Context strategy requires a non-empty name");
+                return own(register("context-strategy", name, strategy, owner, ownerToken, contextStrategies));
+            },
+            registerEntryProjection(projection) {
+                assertUsable();
+                if (!projection?.customType)
+                    throw new Error("Entry projection requires a non-empty customType");
+                if (typeof projection.project !== "function") {
+                    throw new Error("Entry projection requires a callable project");
+                }
+                // 转发到宿主 SessionAPI（SessionManager 持有注册表并应用于上下文投影）。
+                // 宿主未支持时显式失败——第三方与第一方看到同一个错误。
+                const register = options.session?.registerEntryProjection;
+                if (register === undefined) {
+                    throw new Error("Entry projections require a host with entry projection support");
+                }
+                const wrapped = {
+                    customType: projection.customType,
+                    project: (entries) => projection.project(entries),
+                };
+                const dispose = register(wrapped);
+                return own({
+                    id: `entry-projection:${projection.customType}`,
+                    kind: "entry-projection",
+                    dispose: () => {
+                        dispose();
+                    },
+                });
+            },
+            registerProviderHeaderTransform(name, transform) {
+                assertUsable();
+                if (!name)
+                    throw new Error("Provider header transform requires a non-empty name");
+                if (typeof transform !== "function") {
+                    throw new Error("Provider header transform requires a callable transform");
+                }
+                return own(register("provider-header-transform", name, transform, owner, ownerToken, providerHeaderTransforms));
+            },
+            registerSkill(definition) {
+                assertUsable();
+                const name = capabilityName(definition, "Skill");
+                if (typeof definition.description !== "string" || !definition.description.trim()) {
+                    throw new Error("Skill definition requires a non-empty description");
+                }
+                if (typeof definition.filePath !== "string" || !definition.filePath) {
+                    throw new Error("Skill definition requires a filePath");
+                }
+                if (typeof definition.baseDir !== "string" || !definition.baseDir) {
+                    throw new Error("Skill definition requires a baseDir");
+                }
+                return own(register("skill", name, definition, owner, ownerToken, skills));
+            },
+            registerRetryPolicy(name, policy) {
+                assertUsable();
+                if (!name)
+                    throw new Error("Retry policy requires a non-empty name");
+                if (!policy || typeof policy.decide !== "function") {
+                    throw new Error("Retry policy requires a decide function");
+                }
+                return own(register("retry-policy", name, policy, owner, ownerToken, retryPolicies));
+            },
+            registerCompactionPolicy(name, policy) {
+                assertUsable();
+                if (!name)
+                    throw new Error("Compaction policy requires a non-empty name");
+                if (!policy || typeof policy.decide !== "function") {
+                    throw new Error("Compaction policy requires a decide function");
+                }
+                return own(register("compaction-policy", name, policy, owner, ownerToken, compactionPolicies));
+            },
+            registerOverflowPolicy(name, policy) {
+                assertUsable();
+                if (!name)
+                    throw new Error("Overflow policy requires a non-empty name");
+                if (!policy || typeof policy.decide !== "function") {
+                    throw new Error("Overflow policy requires a decide function");
+                }
+                return own(register("overflow-policy", name, policy, owner, ownerToken, overflowPolicies));
+            },
+            registerBranchSummaryPolicy(name, policy) {
+                assertUsable();
+                if (!name)
+                    throw new Error("Branch summary policy requires a non-empty name");
+                if (!policy || typeof policy.summarize !== "function") {
+                    throw new Error("Branch summary policy requires a summarize function");
+                }
+                return own(register("branch-summary-policy", name, policy, owner, ownerToken, branchSummaryPolicies));
+            },
+            registerLoopHook(position, handler) {
+                assertUsable();
+                const positions = [
+                    "beforeInput",
+                    "beforeToolCall",
+                    "afterToolCall",
+                    "transformContext",
+                    "prepareNextTurn",
+                    "shouldStopAfterTurn",
+                ];
+                if (!positions.includes(position)) {
+                    throw new Error(`Agent loop hook position is invalid: ${String(position)}`);
+                }
+                if (typeof handler !== "function") {
+                    throw new Error("Agent loop hook requires a callable handler");
+                }
+                const entries = loopHooks.get(position) ?? [];
+                loopHooks.set(position, entries);
+                const entry = { owner, ownerToken, value: handler };
+                entries.push(entry);
+                const id = `registration:${owner}:loop-hook:${position}:${++loopHookSequence}`;
+                return own(createDisposableRegistration("loop-hook", () => {
+                    const current = loopHooks.get(position);
+                    if (!current)
+                        return;
+                    const index = current.indexOf(entry);
+                    if (index >= 0)
+                        current.splice(index, 1);
+                    if (current.length === 0)
+                        loopHooks.delete(position);
+                }, id));
+            },
+            registerRunLoopStrategy(name, strategy) {
+                assertUsable();
+                if (!name)
+                    throw new Error("Run loop strategy requires a non-empty name");
+                if (!strategy || typeof strategy.decideNextCycle !== "function") {
+                    throw new Error("Run loop strategy requires a decideNextCycle function");
+                }
+                return own(register("run-loop-strategy", name, strategy, owner, ownerToken, runLoopStrategies));
+            },
+            subscribe(type, handler) {
+                assertUsable();
+                if (!type)
+                    throw new Error("Event type requires a non-empty name");
+                const handlers = subscribers.get(type) ?? new Map();
+                subscribers.set(type, handlers);
+                const sequence = ++subscriptionSequence;
+                const id = createRuntimeId("subscription", sequence, `subscription:${owner}:${type}:${sequence}`);
+                handlers.set(id, { owner, ownerToken, value: handler });
+                return own(createDisposableRegistration("subscription", () => {
+                    handlers.delete(id);
+                    if (handlers.size === 0)
+                        subscribers.delete(type);
+                }, id));
+            },
+            async publish(event) {
+                assertUsable();
+                const envelope = detachedSnapshot(createEventEnvelope({ ...event, source: owner }, {
+                    id: createRuntimeId("event", ++runtimeState.eventSequence, `event:${owner}:${runtimeState.eventSequence}`),
+                    timestamp: clock(),
+                }));
+                const results = [];
+                for (const [subscriptionId, subscriber] of subscribers.get(envelope.type)?.entries() ?? []) {
+                    const startedAt = performance.now();
+                    try {
+                        await invokeRegisteredCapability(subscriber, (handler) => handler(detachedSnapshot(envelope)));
+                        results.push({ status: "fulfilled", value: undefined });
+                    }
+                    catch (reason) {
+                        results.push({ status: "rejected", reason });
+                    }
+                    finally {
+                        // 慢订阅者观测：成功与异常路径都记（异常本身仍走原有隔离通道）。
+                        const durationMs = performance.now() - startedAt;
+                        if (durationMs > SLOW_EVENT_SUBSCRIBER_WARN_MS) {
+                            recordLog("warn", subscriber.owner, "Slow event subscriber", {
+                                eventType: envelope.type,
+                                subscriptionId,
+                                durationMs: Math.round(durationMs),
+                            });
+                        }
+                    }
+                }
+                assertUsable();
+                const failures = results
+                    .filter((result) => result.status === "rejected")
+                    .map((result) => result.reason)
+                    .filter((error) => !isRevokedCapabilityError(error));
+                if (failures.length === 1)
+                    throw failures[0];
+                if (failures.length > 1)
+                    throw new AggregateError(failures, `Capability event delivery failed: ${envelope.type}`);
+                return envelope;
+            },
+            call(operation, input, options) {
+                assertUsable();
+                const registered = operations.get(operation);
+                if (!registered)
+                    throw new Error(`Operation is not registered: ${operation}`);
+                assertRegisteredCapabilityActive(registered);
+                const sequence = ++operationSequence;
+                const id = createRuntimeId("operation", sequence, `operation:${owner}:${operation}:${sequence}`);
+                const handle = trackOperation([ownerToken, registered.ownerToken], new RuntimeOperation(id, (value, context) => invokeRegisteredCapability(registered, (handler) => handler(value, context)), input, (status) => {
+                    statuses.set(id, status);
+                    if (status === "running") {
+                        reportOperationStart(id, operation, [ownerToken, registered.ownerToken]);
+                    }
+                    else if (status === "cancelled") {
+                        reportOperationCancel(id, operation, [ownerToken, registered.ownerToken]);
+                    }
+                }, (status) => reportOperationEnd(id, operation, status, [ownerToken, registered.ownerToken]), (() => {
+                    let step = 0;
+                    return (progress) => reportOperationStep(id, operation, [ownerToken, registered.ownerToken], progress, ++step);
+                })()));
+                statuses.set(id, handle.status());
+                const signal = options?.signal;
+                if (signal) {
+                    if (signal.aborted)
+                        void handle.cancel(signal.reason);
+                    else
+                        signal.addEventListener("abort", () => void handle.cancel(signal.reason), {
+                            once: true,
+                        });
+                }
+                return handle;
+            },
+        };
+        apiStates.set(api, state);
+        return api;
+    };
+    return {
+        host: hostWithServices,
+        resolvePluginCapabilityOrder,
+        createAPI: apiFor,
+        revokeAPI(api) {
+            const state = apiStates.get(api);
+            if (state)
+                revokeState(api, state);
+        },
+        revokeAllAPIs() {
+            for (const [api, state] of apiStates)
+                revokeState(api, state);
+        },
+        async disposeAll() {
+            const owners = [...pluginRegistrations.keys()];
+            this.revokeAllAPIs();
+            const failures = [];
+            for (const owner of owners) {
+                try {
+                    await this.disposePlugin(owner);
+                }
+                catch (error) {
+                    failures.push(error);
+                }
+            }
+            await this.drainLifecycleDeliveries();
+            if (failures.length === 1)
+                throw failures[0];
+            if (failures.length > 1)
+                throw new AggregateError(failures, "Capability runtime disposal failed");
+        },
+        disposePluginSync(id) {
+            for (const [api, state] of apiStates)
+                if (state.owner === id)
+                    revokeState(api, state);
+            const registrations = pluginRegistrations.get(id);
+            if (!registrations)
+                return;
+            pluginRegistrations.delete(id);
+            const failures = [];
+            for (const registration of registrations) {
+                try {
+                    const result = registration.dispose();
+                    if (result && typeof result.then === "function") {
+                        observeUnexpectedAsyncCleanup(result, id);
+                        throw new Error(`Capability plugin ${id} has asynchronous cleanup; use the async loader`);
+                    }
+                }
+                catch (error) {
+                    failures.push(error);
+                }
+            }
+            if (failures.length === 1)
+                throw failures[0];
+            if (failures.length > 1)
+                throw new AggregateError(failures, `Capability plugin disposal failed: ${id}`);
+        },
+        async disposePlugin(id) {
+            for (const [api, state] of apiStates)
+                if (state.owner === id)
+                    revokeState(api, state);
+            const registrations = pluginRegistrations.get(id);
+            if (!registrations)
+                return;
+            pluginRegistrations.delete(id);
+            const failures = [];
+            for (const registration of registrations) {
+                try {
+                    await registration.dispose();
+                }
+                catch (error) {
+                    failures.push(error);
+                }
+            }
+            if (failures.length === 1)
+                throw failures[0];
+            if (failures.length > 1)
+                throw new AggregateError(failures, `Capability plugin disposal failed: ${id}`);
+        },
+        listTools: () => Object.freeze(Array.from(tools.entries())
+            .filter(([, entry]) => activeOwnerTokens.has(entry.ownerToken))
+            .sort(([left], [right]) => stableTextCompare(left, right))
+            .map(([name, entry]) => Object.freeze({
+            name,
+            definition: withNormalizedToolResultExecute(definitionSnapshot(entry.value)),
+            source: entry.owner,
+            readonlySafe: toolReadonlySafe(entry.value),
+        }))),
+        listCommands: () => Object.freeze(Array.from(commands.values())
+            .filter((entry) => activeOwnerTokens.has(entry.ownerToken))
+            .sort((left, right) => stableTextCompare(left.value.name, right.value.name) || stableTextCompare(left.owner, right.owner))
+            .map((entry) => Object.freeze({ definition: definitionSnapshot(entry.value), source: entry.owner }))),
+        listSkills: () => Object.freeze(Array.from(skills.values())
+            .filter((entry) => activeOwnerTokens.has(entry.ownerToken))
+            .sort((left, right) => stableTextCompare(left.value.name, right.value.name) || stableTextCompare(left.owner, right.owner))
+            .map((entry) => Object.freeze({ definition: definitionSnapshot(entry.value), source: entry.owner }))),
+        listContributionPoints: () => Array.from(contributionPoints.values())
+            .filter((point) => activeOwnerTokens.has(point.ownerToken))
+            .sort((left, right) => stableTextCompare(contributionPointKey(left.definition.id, left.definition.version), contributionPointKey(right.definition.id, right.definition.version)))
+            .map((point) => ({
+            id: point.definition.id,
+            version: point.definition.version,
+            schema: point.definition.schema,
+            lifecycle: point.definition.lifecycle ?? "observe",
+            owner: point.owner,
+        })),
+        listContributions: (pointId, version) => {
+            const point = contributionPoints.get(contributionPointKey(pointId, version));
+            if (!point || !activeOwnerTokens.has(point.ownerToken))
+                throw new Error(`Contribution point is not defined: ${pointId}@${version}`);
+            return listContributionEntries(point);
+        },
+        hasLifecycleEvent: (id, version) => {
+            const definition = lifecycleDefinitions.get(lifecycleEventKey(id, version));
+            return definition !== undefined && activeOwnerTokens.has(definition.ownerToken);
+        },
+        dispatchLifecycle,
+        async recordPluginRejection(rejection) {
+            const detached = Object.freeze({
+                code: rejection.code,
+                manifestPath: rejection.manifestPath,
+                ...(rejection.pluginId === undefined ? {} : { pluginId: rejection.pluginId }),
+                message: rejection.message,
+            });
+            pluginRejections.push(detached);
+            const rejectedEventDefinition = lifecycleDefinitions.get(lifecycleEventKey(PLUGIN_REJECTED_EVENT_ID, PLUGIN_REJECTED_EVENT_VERSION));
+            if (!rejectedEventDefinition || !activeOwnerTokens.has(rejectedEventDefinition.ownerToken)) {
+                return;
+            }
+            try {
+                await dispatchLifecycle({
+                    type: PLUGIN_REJECTED_EVENT_ID,
+                    version: PLUGIN_REJECTED_EVENT_VERSION,
+                    phase: "committed",
+                    data: {
+                        version: 1,
+                        ...(detached.pluginId === undefined ? {} : { pluginId: detached.pluginId }),
+                        manifestPath: detached.manifestPath,
+                        code: detached.code,
+                        message: detached.message,
+                    },
+                    source: "capability-runtime",
+                });
+            }
+            catch {
+                // The inspector record above is authoritative; lifecycle delivery failures
+                // surface through runtime reports, never through the startup path.
+            }
+        },
+        listPluginCapabilities,
+        validateExecutionFacts: validateExecutionFactsV1,
+        validateRetrySchedule: validateRetryScheduleV1,
+        hasRetryPolicy: (name) => retryPolicies.has(name),
+        async classifyRetry(name, request) {
+            const policy = retryPolicies.get(name);
+            if (!policy)
+                throw new Error(`Retry policy is not registered: ${name}`);
+            if (!policy.value.classify)
+                throw new Error(`Retry policy does not support classification: ${name}`);
+            const retryable = await invokeRegisteredCapabilityWithSignal(policy, request.signal, (value) => value.classify?.(request));
+            if (typeof retryable !== "boolean") {
+                throw new Error(`Retry policy returned an invalid classification: ${name}`);
+            }
+            return retryable;
+        },
+        async decideRetry(name, request) {
+            const policy = retryPolicies.get(name);
+            if (!policy)
+                throw new Error(`Retry policy is not registered: ${name}`);
+            const decision = await invokeRegisteredCapabilityWithSignal(policy, request.signal, (value) => value.decide(request));
+            if (!decision || typeof decision.retry !== "boolean") {
+                throw new Error(`Retry policy returned an invalid decision: ${name}`);
+            }
+            if (decision.delayMs !== undefined && (!Number.isFinite(decision.delayMs) || decision.delayMs < 0)) {
+                throw new Error(`Retry policy returned an invalid delayMs: ${name}`);
+            }
+            return decision;
+        },
+        hasCompactionPolicy: (name) => compactionPolicies.has(name),
+        async prepareCompaction(name, request) {
+            const policy = compactionPolicies.get(name);
+            if (!policy)
+                throw new Error(`Compaction policy is not registered: ${name}`);
+            if (!policy.value.prepare)
+                throw new Error(`Compaction policy does not support preparation: ${name}`);
+            return invokeRegisteredCapabilityWithSignal(policy, request.signal, (value) => value.prepare?.(request));
+        },
+        hasBranchSummaryPolicy: (name) => branchSummaryPolicies.has(name),
+        async summarizeBranch(name, request) {
+            const policy = branchSummaryPolicies.get(name);
+            if (!policy)
+                throw new Error(`Branch summary policy is not registered: ${name}`);
+            const result = await invokeRegisteredCapabilityWithSignal(policy, request.signal, (value) => value.summarize(request));
+            if (!result || typeof result !== "object") {
+                throw new Error(`Branch summary policy returned an invalid result: ${name}`);
+            }
+            return result;
+        },
+        getLoopHookChain: (position) => {
+            const entries = loopHooks.get(position);
+            if (!entries)
+                return [];
+            return entries
+                .filter((entry) => activeOwnerTokens.has(entry.ownerToken))
+                .map((entry) => entry.value);
+        },
+        hasRunLoopStrategy: (name) => runLoopStrategies.has(name),
+        async decideRunLoop(name, request) {
+            const strategy = runLoopStrategies.get(name);
+            if (!strategy)
+                throw new Error(`Run loop strategy is not registered: ${name}`);
+            const decision = await invokeRegisteredCapabilityWithSignal(strategy, request.signal, (value) => value.decideNextCycle(request));
+            if (!decision || typeof decision.continueLoop !== "boolean") {
+                throw new Error(`Run loop strategy returned an invalid decision: ${name}`);
+            }
+            return decision;
+        },
+        async decideCompaction(name, request) {
+            const policy = compactionPolicies.get(name);
+            if (!policy)
+                throw new Error(`Compaction policy is not registered: ${name}`);
+            const decision = await invokeRegisteredCapabilityWithSignal(policy, request.signal, (value) => value.decide(request));
+            if (!decision || typeof decision.compact !== "boolean") {
+                throw new Error(`Compaction policy returned an invalid decision: ${name}`);
+            }
+            if (decision.retry !== undefined && typeof decision.retry !== "boolean") {
+                throw new Error(`Compaction policy returned an invalid retry value: ${name}`);
+            }
+            if (decision.failureMessage !== undefined && typeof decision.failureMessage !== "string") {
+                throw new Error(`Compaction policy returned an invalid failureMessage: ${name}`);
+            }
+            return decision;
+        },
+        async summarizeCompaction(name, request) {
+            const policy = compactionPolicies.get(name);
+            if (!policy)
+                throw new Error(`Compaction policy is not registered: ${name}`);
+            if (!policy.value.summarize)
+                throw new Error(`Compaction policy does not support summaries: ${name}`);
+            const result = await invokeRegisteredCapabilityWithSignal(policy, request.signal, (value) => value.summarize?.(request));
+            if (!result ||
+                typeof result.summary !== "string" ||
+                !result.summary ||
+                typeof result.firstKeptEntryId !== "string" ||
+                !Number.isFinite(result.tokensBefore)) {
+                throw new Error(`Compaction policy returned an invalid summary: ${name}`);
+            }
+            return result;
+        },
+        hasOverflowPolicy: (name) => overflowPolicies.has(name),
+        async decideOverflow(name, request) {
+            const policy = overflowPolicies.get(name);
+            if (!policy)
+                throw new Error(`Overflow policy is not registered: ${name}`);
+            const decision = await invokeRegisteredCapabilityWithSignal(policy, request.signal, (value) => value.decide(request));
+            if (!decision ||
+                typeof decision.contextOverflow !== "boolean" ||
+                typeof decision.recoverableLength !== "boolean") {
+                throw new Error(`Overflow policy returned an invalid decision: ${name}`);
+            }
+            return decision;
+        },
+        async invokeTool(name, input, options) {
+            const registered = tools.get(name);
+            if (!registered)
+                throw new Error(`Tool is not registered: ${name}`);
+            return invokeRegisteredCapability(registered, (value) => invokeCapabilityTool(asHandler(value, "Tool"), input, toolExecutionContext, options?.signal));
+        },
+        hasCommand: (name) => commands.has(name),
+        async invokeCommand(name, args, options) {
+            const registered = commands.get(name);
+            if (!registered)
+                throw new Error(`Command is not registered: ${name}`);
+            return validateCommandResult(await invokeRegisteredCapability(registered, (value) => value.execute(args, options ?? { signal: new AbortController().signal })), name);
+        },
+        hasRpcMethod: (name) => rpcMethods.has(name),
+        async dispatchRpc(name, input) {
+            const registered = rpcMethods.get(name);
+            if (!registered)
+                throw new Error(`RPC method is not registered: ${name}`);
+            return invokeRegisteredCapability(registered, (value) => value(input));
+        },
+        hasContextStrategy: (name) => contextStrategies.has(name),
+        async transformContext(name, context, options) {
+            const strategy = contextStrategies.get(name);
+            if (!strategy)
+                throw new Error(`Context strategy is not registered: ${name}`);
+            return invokeRegisteredCapability(strategy, (value) => value.transform(context, options));
+        },
+        async snapshotContext(name, context, options) {
+            const registered = contextStrategies.get(name);
+            if (!registered)
+                throw new Error(`Context strategy is not registered: ${name}`);
+            if (!registered.value.snapshot)
+                throw new Error(`Context strategy does not support snapshots: ${name}`);
+            return invokeRegisteredCapability(registered, (value) => value.snapshot?.(context, options));
+        },
+        async restoreContext(name, snapshot, options) {
+            const registered = contextStrategies.get(name);
+            if (!registered)
+                throw new Error(`Context strategy is not registered: ${name}`);
+            if (!registered.value.restore)
+                throw new Error(`Context strategy does not support restore: ${name}`);
+            return invokeRegisteredCapability(registered, (value) => value.restore?.(snapshot, options));
+        },
+        async replaceContext(name, context, options) {
+            const registered = contextStrategies.get(name);
+            if (!registered)
+                throw new Error(`Context strategy is not registered: ${name}`);
+            if (!registered.value.replace)
+                throw new Error(`Context strategy does not support replacement: ${name}`);
+            return invokeRegisteredCapability(registered, (value) => value.replace?.(context, options));
+        },
+        async transformProviderHeaders(request) {
+            let headers = validateProviderHeaders(request.headers, "request");
+            for (const [name, transform] of providerHeaderTransforms) {
+                headers = validateProviderHeaders(await invokeRegisteredCapability(transform, (value) => value({
+                    model: request.model,
+                    ...(request.sessionId === undefined ? {} : { sessionId: request.sessionId }),
+                    headers: { ...headers },
+                })), name);
+            }
+            return headers;
+        },
+        getOperationStatus: (id) => statuses.get(id),
+        drainLifecycleDeliveries: async () => {
+            while (true) {
+                const queues = [...lifecycleDeliveryQueues];
+                if (queues.length === 0)
+                    return;
+                await Promise.all(queues.map((queue) => queue.drain()));
+                if (queues.every((queue) => queue.snapshot().pendingEvents === 0))
+                    return;
+            }
+        },
+        inspect,
+    };
+}
+//# sourceMappingURL=capability-runtime.js.map