@ai-agent-forge/agent-forge 0.88.1 → 0.88.3

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

@@ -7,8 +7,9 @@ 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 { assertRegisteredCapabilityActive as assertRegisteredCapabilityState, cancelOwnedOperations as cancelOwnedOperationsState, createCapabilityRuntimeState, createRevokedCapabilityError, invokePluginCapability as invokePluginCapabilityState, invokeRegisteredCapability as invokeRegisteredCapabilityState, invokeRegisteredCapabilityWithSignal as invokeRegisteredCapabilityWithSignalState, isRevokedCapabilityError, observeUnexpectedAsyncCleanup, pushPluginRejection, pushRuntimeLog, setDiagnosticsSpan, setOperationStatus, trackOperation as trackOperationState, } from "./capability-runtime-store.js";
 import { invokeCapabilityTool } from "./capability-runtime-tool.js";
+import { OUTPUT_ARTIFACT_MAX_BUFFER_BYTES } from "./capability-runtime-types.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";
@@ -23,6 +24,122 @@ export { validateExecutionFactsV1, validateRetryScheduleV1 } from "./capability-
  * clock 缺省恒 0（生产不注入），不能作为耗时来源。
  */
 const SLOW_EVENT_SUBSCRIBER_WARN_MS = 100;
+/**
+ * 超限驻留视图的尾部窗口字节数：超限后驻留视图保留完整流真实末尾这么多字节。
+ */
+const OUTPUT_ARTIFACT_TAIL_BYTES = 64 * 1024;
+const truncationMarkerEncoder = new TextEncoder();
+/**
+ * 超限标记文本（ASCII）：N 是驻留视图未表示的原始流字节数（十进制）。
+ */
+const encodeTruncationMarker = (omittedBytes) => truncationMarkerEncoder.encode(`\n[agent-forge artifact truncated: ${omittedBytes} bytes omitted]\n`);
+const concatChunks = (chunks, totalBytes) => {
+    const bytes = new Uint8Array(totalBytes);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes;
+};
+/** 取 chunks 拼接后的前 length 字节（跨 chunk 切片），作为截断视图的 head。 */
+const takeLeadingBytes = (chunks, length) => {
+    const taken = [];
+    let remaining = length;
+    for (const chunk of chunks) {
+        if (remaining <= 0)
+            break;
+        if (chunk.byteLength <= remaining) {
+            taken.push(chunk);
+            remaining -= chunk.byteLength;
+        }
+        else {
+            taken.push(chunk.subarray(0, remaining));
+            remaining = 0;
+        }
+    }
+    return taken;
+};
+/**
+ * 组装 head + 截断标记 + tail 的驻留视图，总长恰为 OUTPUT_ARTIFACT_MAX_BUFFER_BYTES。
+ * 标记展示的省略字节数依赖标记自身的字节长度（head = 上限 − tail − marker），
+ * 不动点按字节数收敛（标记长度只在十进制进位处变化），两三轮内稳定。
+ */
+const buildTruncatedView = (headChunks, tailChunks, totalBytes) => {
+    const tailBytes = Math.min(OUTPUT_ARTIFACT_TAIL_BYTES, totalBytes);
+    let omitted = totalBytes - OUTPUT_ARTIFACT_MAX_BUFFER_BYTES;
+    let marker = encodeTruncationMarker(omitted);
+    let headLength = OUTPUT_ARTIFACT_MAX_BUFFER_BYTES - tailBytes - marker.byteLength;
+    while (totalBytes - headLength - tailBytes !== omitted) {
+        omitted = totalBytes - headLength - tailBytes;
+        marker = encodeTruncationMarker(omitted);
+        headLength = OUTPUT_ARTIFACT_MAX_BUFFER_BYTES - tailBytes - marker.byteLength;
+    }
+    return concatChunks([...takeLeadingBytes(headChunks, headLength), marker, ...tailChunks], OUTPUT_ARTIFACT_MAX_BUFFER_BYTES);
+};
+/**
+ * output.put 驻留缓冲（M4 双层限额的缓冲半层）：逐字节缓冲直至
+ * OUTPUT_ARTIFACT_MAX_BUFFER_BYTES，超限后停止缓冲但仍把 AsyncIterable 完整
+ * 消费完——消费端提前返回会把背压和写管道破裂转嫁给上游，语义变化，禁止；
+ * 只丢弃数据。尾部窗口始终滑动维持在完整流末尾 OUTPUT_ARTIFACT_TAIL_BYTES。
+ * 超限驻留视图 = head + 截断标记 + tail（总长恰为上限）；未超限驻留与提交
+ * 数据逐字节一致。
+ */
+const bufferOutputArtifactData = async (data, throwIfAborted) => {
+    if (data instanceof Uint8Array) {
+        if (data.byteLength <= OUTPUT_ARTIFACT_MAX_BUFFER_BYTES) {
+            return { bytes: new Uint8Array(data), totalBytes: data.byteLength, truncated: false };
+        }
+        const tailStart = data.byteLength - OUTPUT_ARTIFACT_TAIL_BYTES;
+        return {
+            bytes: buildTruncatedView([data], [data.subarray(tailStart)], data.byteLength),
+            totalBytes: data.byteLength,
+            truncated: true,
+        };
+    }
+    const headChunks = [];
+    const tailChunks = [];
+    let tailBytes = 0;
+    let headBytes = 0;
+    let totalBytes = 0;
+    let truncated = false;
+    const appendTail = (chunk) => {
+        tailChunks.push(chunk);
+        tailBytes += chunk.byteLength;
+        while (tailBytes > OUTPUT_ARTIFACT_TAIL_BYTES) {
+            const oldest = tailChunks[0];
+            const overflow = tailBytes - OUTPUT_ARTIFACT_TAIL_BYTES;
+            if (oldest.byteLength <= overflow) {
+                tailChunks.shift();
+                tailBytes -= oldest.byteLength;
+            }
+            else {
+                tailChunks[0] = oldest.subarray(overflow);
+                tailBytes -= overflow;
+            }
+        }
+    };
+    for await (const chunk of data) {
+        throwIfAborted();
+        if (!(chunk instanceof Uint8Array)) {
+            throw new OutputArtifactError("invalid_ref", "Artifact stream yielded a non-Uint8Array chunk");
+        }
+        const copy = new Uint8Array(chunk);
+        totalBytes += copy.byteLength;
+        appendTail(copy);
+        if (truncated)
+            continue;
+        headChunks.push(copy);
+        headBytes += copy.byteLength;
+        if (headBytes > OUTPUT_ARTIFACT_MAX_BUFFER_BYTES)
+            truncated = true;
+    }
+    throwIfAborted();
+    if (!truncated) {
+        return { bytes: concatChunks(headChunks, totalBytes), totalBytes, truncated };
+    }
+    return { bytes: buildTruncatedView(headChunks, tailChunks, totalBytes), totalBytes, truncated: true };
+};
 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
@@ -114,7 +231,7 @@ export function createCapabilityRuntime(inputHost, options = {}) {
     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, streamFnWrappers, contributionPoints, lifecycleDefinitions, lifecycleRegistrations, subscribers, statuses, pluginRegistrations, apiStates, activeOwnerTokens, outputArtifacts, stateByOwner, stateRevisionsByOwner, stateWatchers, stateByInstance, stateRevisionsByInstance, stateWatchersByInstance, logs, spans, lifecycleDeliveryQueues, pluginRejections, } = state;
+    const { tools, skills, retryPolicies, compactionPolicies, overflowPolicies, branchSummaryPolicies, runLoopStrategies, loopHooks, commands, operations, rpcMethods, contextStrategies, pluginCapabilities, providerHeaderTransforms, streamFnWrappers, contributionPoints, lifecycleDefinitions, lifecycleRegistrations, subscribers, statuses, pluginRegistrations, apiStates, activeOwnerTokens, outputArtifacts, stateByOwner, stateRevisionsByOwner, stateWatchers, stateByInstance, stateRevisionsByInstance, stateWatchersByInstance, spans, lifecycleDeliveryQueues, } = state;
     const runtimeState = state;
     // 契约 A（D-082 批 3b）：store 字段保持基础注册结构类型（store 不感知链序），
     // 本运行时经此类型视图写入/读取链序元数据；唯一写入方是 registerStreamFnWrapper
@@ -338,7 +455,7 @@ export function createCapabilityRuntime(inputHost, options = {}) {
             ...(fields === undefined ? {} : { fields: detachedSnapshot(fields) }),
             ...(cause === undefined ? {} : { cause: detachedSnapshot(cause) }),
         };
-        logs.push(record);
+        pushRuntimeLog(state, record);
         // 插件日志宿主转发（设计 §7.2）：入环后同步转发一次。回调抛错直接吞掉——
         // 与 notifyToolRegistryChange 同守"观察者故障不打断调用方"的边界，但错误
         // 通道不同：不引入无读者的计数，也绝不经 recordLog 再记录（回调契约禁止
@@ -895,7 +1012,7 @@ export function createCapabilityRuntime(inputHost, options = {}) {
             if (!state.active || !activeOwnerTokens.has(ownerToken) || event.owner !== owner)
                 return;
             if (event.event === "start") {
-                statuses.set(event.operationId, "running");
+                setOperationStatus(runtimeState, event.operationId, "running");
                 reportOperationStart(event.operationId, event.operationKind, [ownerToken]);
             }
             else if (event.event === "step") {
@@ -904,12 +1021,12 @@ export function createCapabilityRuntime(inputHost, options = {}) {
                 reportOperationStep(event.operationId, event.operationKind, [ownerToken], event.progress, event.step);
             }
             else if (event.event === "cancel") {
-                statuses.set(event.operationId, "cancelled");
+                setOperationStatus(runtimeState, event.operationId, "cancelled");
                 reportOperationCancel(event.operationId, event.operationKind, [ownerToken]);
             }
             else {
                 const status = event.status ?? "failed";
-                statuses.set(event.operationId, status);
+                setOperationStatus(runtimeState, event.operationId, status);
                 reportOperationEnd(event.operationId, event.operationKind, status, [ownerToken]);
             }
         };
@@ -984,7 +1101,7 @@ export function createCapabilityRuntime(inputHost, options = {}) {
                     status: "running",
                     attributes: detachedSnapshot(attributes ?? {}),
                 };
-                spans.set(spanId, snapshot);
+                setDiagnosticsSpan(runtimeState, spanId, snapshot);
                 let ended = false;
                 const span = {
                     traceId,
@@ -1091,7 +1208,7 @@ export function createCapabilityRuntime(inputHost, options = {}) {
                         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);
+                            setOperationStatus(runtimeState, operationId, status);
                             if (status === "running") {
                                 reportCapabilityCall("start", operationId, owner, registered, [
                                     ownerToken,
@@ -1105,7 +1222,7 @@ export function createCapabilityRuntime(inputHost, options = {}) {
                                 ]);
                             }
                         }, (status) => reportCapabilityCall("end", operationId, owner, registered, [ownerToken, registered.ownerToken], status), () => false));
-                        statuses.set(operationId, handle.status());
+                        setOperationStatus(runtimeState, operationId, handle.status());
                         const signal = callOptions?.signal;
                         if (signal) {
                             if (signal.aborted)
@@ -1258,30 +1375,10 @@ export function createCapabilityRuntime(inputHost, options = {}) {
                     }
                 };
                 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;
-                }
+                // M4 双层限额：驻留缓冲封顶（形态见 bufferOutputArtifactData）。
+                // sizeBytes/truncated 是运行时计算值——调用方传入的 truncated 只过
+                // 类型校验，其值在组 ref 处被计算值覆盖，不再生效。
+                const { bytes, totalBytes, truncated } = await bufferOutputArtifactData(input.data, throwIfAborted);
                 // A stream may yield after the plugin has been revoked. Never commit
                 // bytes after the lifecycle boundary has closed.
                 assertUsable();
@@ -1293,16 +1390,20 @@ export function createCapabilityRuntime(inputHost, options = {}) {
                     artifactId,
                     kind: input.kind,
                     mediaType: input.mediaType,
-                    sizeBytes,
-                    truncated: input.truncated,
+                    sizeBytes: totalBytes,
+                    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).
+                // observer receives the resident buffer reachable through stat/read.
+                // That buffer is capped at OUTPUT_ARTIFACT_MAX_BUFFER_BYTES, so for an
+                // oversized artifact the observer intentionally receives the truncated
+                // head+marker+tail view (durable mirrors persist the truncated view)
+                // while ref.sizeBytes keeps the original total. 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 });
@@ -1867,7 +1968,7 @@ export function createCapabilityRuntime(inputHost, options = {}) {
                 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);
+                    setOperationStatus(runtimeState, id, status);
                     if (status === "running") {
                         reportOperationStart(id, operation, [ownerToken, registered.ownerToken]);
                     }
@@ -1878,7 +1979,7 @@ export function createCapabilityRuntime(inputHost, options = {}) {
                     let step = 0;
                     return (progress) => reportOperationStep(id, operation, [ownerToken, registered.ownerToken], progress, ++step);
                 })()));
-                statuses.set(id, handle.status());
+                setOperationStatus(runtimeState, id, handle.status());
                 const signal = options?.signal;
                 if (signal) {
                     if (signal.aborted)
@@ -2010,6 +2111,7 @@ export function createCapabilityRuntime(inputHost, options = {}) {
             const definition = lifecycleDefinitions.get(lifecycleEventKey(id, version));
             return definition !== undefined && activeOwnerTokens.has(definition.ownerToken);
         },
+        hasLifecycleSubscribers: (type, version) => (state.lifecycleRegistrations.get(lifecycleEventKey(type, version))?.size ?? 0) > 0,
         dispatchLifecycle,
         async recordPluginRejection(rejection) {
             const detached = Object.freeze({
@@ -2018,7 +2120,7 @@ export function createCapabilityRuntime(inputHost, options = {}) {
                 ...(rejection.pluginId === undefined ? {} : { pluginId: rejection.pluginId }),
                 message: rejection.message,
             });
-            pluginRejections.push(detached);
+            pushPluginRejection(state, detached);
             const rejectedEventDefinition = lifecycleDefinitions.get(lifecycleEventKey(PLUGIN_REJECTED_EVENT_ID, PLUGIN_REJECTED_EVENT_VERSION));
             if (!rejectedEventDefinition || !activeOwnerTokens.has(rejectedEventDefinition.ownerToken)) {
                 return;