@ai-agent-forge/agent-forge 0.85.0

package/dist/testing/runtime-delivery-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-delivery-queue.d.ts","sourceRoot":"","sources":["../../src/testing/runtime-delivery-queue.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,eAAO,MAAM,uCAAuC,sCAAgD,CAAC;AAErG,MAAM,MAAM,8BAA8B,GAAG,QAAQ,GAAG,YAAY,GAAG,QAAQ,CAAC;AAEhF,MAAM,WAAW,gCAAgC;IAChD,QAAQ,CAAC,MAAM,EAAE,8BAA8B,CAAC;IAChD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,+BAA+B,CAAC,CAAC;IACjD,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,uCAAuC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,wBAAwB,CAAC,CAAC;IAC1C,OAAO,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,KAAK,IAAI,IAAI,CAAC;IACd,QAAQ,IAAI,gCAAgC,CAAC;CAC7C;AAED,qBAAa,oCAAqC,SAAQ,KAAK;IAC9D,QAAQ,CAAC,IAAI,uCAA2C;IACxD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,YAAY,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAQ/D;CACD;AAeD;;;;;;;;;;;;GAYG;AACH,wBAAgB,8BAA8B,CAAC,CAAC,EAC/C,OAAO,EAAE,+BAA+B,CAAC,CAAC,CAAC,GACzC,wBAAwB,CAAC,CAAC,CAAC,CAsH7B","sourcesContent":["/** Stable error code required by the model.stream backpressure contract. */\nexport const MODEL_STREAM_BACKPRESSURE_OVERFLOW_CODE = \"model_stream_backpressure_overflow\" as const;\n\nexport type RuntimeOnlyDeliveryQueueStatus = \"active\" | \"overflowed\" | \"closed\";\n\nexport interface RuntimeOnlyDeliveryQueueSnapshot {\n\treadonly status: RuntimeOnlyDeliveryQueueStatus;\n\treadonly capacity: number;\n\t/** Weight of in-flight and queued values that have not finished delivery. */\n\treadonly pending: number;\n\treadonly accepted: number;\n\treadonly delivered: number;\n\treadonly rejected: number;\n}\n\nexport interface RuntimeOnlyDeliveryQueueOptions<T> {\n\t/** Maximum pending weight for this subscription. */\n\treadonly capacity: number;\n\t/** Defaults to one event per value. */\n\treadonly measure?: (value: T) => number;\n\treadonly deliver: (value: T) => void | Promise<void>;\n}\n\nexport interface RuntimeOnlyDeliveryQueue<T> {\n\tenqueue(value: T): Promise<void>;\n\tdrain(): Promise<void>;\n\tclose(): void;\n\tsnapshot(): RuntimeOnlyDeliveryQueueSnapshot;\n}\n\nexport class RuntimeOnlyBackpressureOverflowError extends Error {\n\treadonly code = MODEL_STREAM_BACKPRESSURE_OVERFLOW_CODE;\n\treadonly capacity: number;\n\treadonly pending: number;\n\treadonly attempted: number;\n\n\tconstructor(capacity: number, pending: number, attempted: number) {\n\t\tsuper(\n\t\t\t`Runtime-only delivery queue overflow: pending ${pending} + attempted ${attempted} exceeds capacity ${capacity}`,\n\t\t);\n\t\tthis.name = \"RuntimeOnlyBackpressureOverflowError\";\n\t\tthis.capacity = capacity;\n\t\tthis.pending = pending;\n\t\tthis.attempted = attempted;\n\t}\n}\n\ninterface QueueEntry<T> {\n\treadonly value: T;\n\treadonly weight: number;\n\treadonly resolve: () => void;\n\treadonly reject: (error: unknown) => void;\n}\n\nfunction assertPositiveSafeInteger(value: number, name: string): void {\n\tif (!Number.isSafeInteger(value) || value < 1) {\n\t\tthrow new Error(`Runtime-only delivery queue ${name} must be a positive safe integer`);\n\t}\n}\n\n/**\n * Creates a deterministic host-side subscription queue for runtime-only tests.\n *\n * Overflow rejects only the new enqueue, permanently terminates this queue,\n * and leaves already accepted values in order for delivery. Other queues are\n * independent and are not affected.\n *\n * Test-only divergence from the production lifecycle delivery queue: a handler\n * failure closes this whole queue and rejects every pending value with the\n * same error, while the production queue isolates the failure to that single\n * delivery and keeps accepting. Tests that need production semantics must use\n * the production runtime, not this fixture.\n */\nexport function createRuntimeOnlyDeliveryQueue<T>(\n\toptions: RuntimeOnlyDeliveryQueueOptions<T>,\n): RuntimeOnlyDeliveryQueue<T> {\n\tassertPositiveSafeInteger(options.capacity, \"capacity\");\n\tconst measure = options.measure ?? (() => 1);\n\tconst entries: QueueEntry<T>[] = [];\n\tlet status: RuntimeOnlyDeliveryQueueStatus = \"active\";\n\tlet pending = 0;\n\tlet accepted = 0;\n\tlet delivered = 0;\n\tlet rejected = 0;\n\tlet processing = false;\n\tlet drainPromise: Promise<void> | undefined;\n\tlet resolveDrain: (() => void) | undefined;\n\n\tconst ensureDrainPromise = (): Promise<void> => {\n\t\tif (drainPromise === undefined) {\n\t\t\tdrainPromise = new Promise<void>((resolve) => {\n\t\t\t\tresolveDrain = resolve;\n\t\t\t});\n\t\t}\n\t\treturn drainPromise;\n\t};\n\n\tconst settleDrainIfIdle = (): void => {\n\t\tif (processing || entries.length > 0) return;\n\t\tresolveDrain?.();\n\t\tdrainPromise = undefined;\n\t\tresolveDrain = undefined;\n\t};\n\n\tconst pump = async (): Promise<void> => {\n\t\tif (processing) return;\n\t\tprocessing = true;\n\t\ttry {\n\t\t\twhile (entries.length > 0) {\n\t\t\t\tconst entry = entries.shift();\n\t\t\t\t// v8 ignore next -- 循环条件保证 shift 必有元素\n\t\t\t\tif (entry === undefined) continue;\n\t\t\t\ttry {\n\t\t\t\t\tawait options.deliver(entry.value);\n\t\t\t\t\tdelivered += 1;\n\t\t\t\t\tentry.resolve();\n\t\t\t\t} catch (error) {\n\t\t\t\t\tstatus = \"closed\";\n\t\t\t\t\trejected += 1;\n\t\t\t\t\tentry.reject(error);\n\t\t\t\t\twhile (entries.length > 0) {\n\t\t\t\t\t\tconst pendingEntry = entries.shift();\n\t\t\t\t\t\t// v8 ignore next -- 循环条件保证 shift 必有元素\n\t\t\t\t\t\tif (pendingEntry === undefined) continue;\n\t\t\t\t\t\tpending -= pendingEntry.weight;\n\t\t\t\t\t\trejected += 1;\n\t\t\t\t\t\tpendingEntry.reject(error);\n\t\t\t\t\t}\n\t\t\t\t} finally {\n\t\t\t\t\tpending -= entry.weight;\n\t\t\t\t}\n\t\t\t\tif (status === \"closed\") break;\n\t\t\t}\n\t\t} finally {\n\t\t\tprocessing = false;\n\t\t\tsettleDrainIfIdle();\n\t\t}\n\t};\n\n\tconst enqueue = (value: T): Promise<void> => {\n\t\tif (status !== \"active\") {\n\t\t\trejected += 1;\n\t\t\tif (status === \"overflowed\") {\n\t\t\t\treturn Promise.reject(new RuntimeOnlyBackpressureOverflowError(options.capacity, pending, 0));\n\t\t\t}\n\t\t\treturn Promise.reject(new Error(`Runtime-only delivery queue is ${status}`));\n\t\t}\n\t\tconst weight = measure(value);\n\t\tassertPositiveSafeInteger(weight, \"measure result\");\n\t\tif (pending + weight > options.capacity) {\n\t\t\tstatus = \"overflowed\";\n\t\t\trejected += 1;\n\t\t\treturn Promise.reject(new RuntimeOnlyBackpressureOverflowError(options.capacity, pending, weight));\n\t\t}\n\t\taccepted += 1;\n\t\tpending += weight;\n\t\tconst result = new Promise<void>((resolve, reject) => {\n\t\t\tentries.push({ value, weight, resolve, reject });\n\t\t});\n\t\tensureDrainPromise();\n\t\tvoid pump();\n\t\treturn result;\n\t};\n\n\treturn {\n\t\tenqueue,\n\t\tdrain: () => {\n\t\t\tif (!processing && entries.length === 0) return Promise.resolve();\n\t\t\treturn ensureDrainPromise();\n\t\t},\n\t\tclose: () => {\n\t\t\tif (status === \"closed\") return;\n\t\t\tstatus = \"closed\";\n\t\t\twhile (entries.length > 0) {\n\t\t\t\tconst entry = entries.shift();\n\t\t\t\t// v8 ignore next -- 循环条件保证 shift 必有元素\n\t\t\t\tif (entry === undefined) continue;\n\t\t\t\tpending -= entry.weight;\n\t\t\t\trejected += 1;\n\t\t\t\tentry.reject(new Error(\"Runtime-only delivery queue was closed\"));\n\t\t\t}\n\t\t\tsettleDrainIfIdle();\n\t\t},\n\t\tsnapshot: () =>\n\t\t\tObject.freeze({\n\t\t\t\tstatus,\n\t\t\t\tcapacity: options.capacity,\n\t\t\t\tpending,\n\t\t\t\taccepted,\n\t\t\t\tdelivered,\n\t\t\t\trejected,\n\t\t\t}),\n\t};\n}\n"]}

package/dist/testing/runtime-delivery-queue.js

@@ -0,0 +1,158 @@
+/** Stable error code required by the model.stream backpressure contract. */
+export const MODEL_STREAM_BACKPRESSURE_OVERFLOW_CODE = "model_stream_backpressure_overflow";
+export class RuntimeOnlyBackpressureOverflowError extends Error {
+    code = MODEL_STREAM_BACKPRESSURE_OVERFLOW_CODE;
+    capacity;
+    pending;
+    attempted;
+    constructor(capacity, pending, attempted) {
+        super(`Runtime-only delivery queue overflow: pending ${pending} + attempted ${attempted} exceeds capacity ${capacity}`);
+        this.name = "RuntimeOnlyBackpressureOverflowError";
+        this.capacity = capacity;
+        this.pending = pending;
+        this.attempted = attempted;
+    }
+}
+function assertPositiveSafeInteger(value, name) {
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new Error(`Runtime-only delivery queue ${name} must be a positive safe integer`);
+    }
+}
+/**
+ * Creates a deterministic host-side subscription queue for runtime-only tests.
+ *
+ * Overflow rejects only the new enqueue, permanently terminates this queue,
+ * and leaves already accepted values in order for delivery. Other queues are
+ * independent and are not affected.
+ *
+ * Test-only divergence from the production lifecycle delivery queue: a handler
+ * failure closes this whole queue and rejects every pending value with the
+ * same error, while the production queue isolates the failure to that single
+ * delivery and keeps accepting. Tests that need production semantics must use
+ * the production runtime, not this fixture.
+ */
+export function createRuntimeOnlyDeliveryQueue(options) {
+    assertPositiveSafeInteger(options.capacity, "capacity");
+    const measure = options.measure ?? (() => 1);
+    const entries = [];
+    let status = "active";
+    let pending = 0;
+    let accepted = 0;
+    let delivered = 0;
+    let rejected = 0;
+    let processing = false;
+    let drainPromise;
+    let resolveDrain;
+    const ensureDrainPromise = () => {
+        if (drainPromise === undefined) {
+            drainPromise = new Promise((resolve) => {
+                resolveDrain = resolve;
+            });
+        }
+        return drainPromise;
+    };
+    const settleDrainIfIdle = () => {
+        if (processing || entries.length > 0)
+            return;
+        resolveDrain?.();
+        drainPromise = undefined;
+        resolveDrain = undefined;
+    };
+    const pump = async () => {
+        if (processing)
+            return;
+        processing = true;
+        try {
+            while (entries.length > 0) {
+                const entry = entries.shift();
+                // v8 ignore next -- 循环条件保证 shift 必有元素
+                if (entry === undefined)
+                    continue;
+                try {
+                    await options.deliver(entry.value);
+                    delivered += 1;
+                    entry.resolve();
+                }
+                catch (error) {
+                    status = "closed";
+                    rejected += 1;
+                    entry.reject(error);
+                    while (entries.length > 0) {
+                        const pendingEntry = entries.shift();
+                        // v8 ignore next -- 循环条件保证 shift 必有元素
+                        if (pendingEntry === undefined)
+                            continue;
+                        pending -= pendingEntry.weight;
+                        rejected += 1;
+                        pendingEntry.reject(error);
+                    }
+                }
+                finally {
+                    pending -= entry.weight;
+                }
+                if (status === "closed")
+                    break;
+            }
+        }
+        finally {
+            processing = false;
+            settleDrainIfIdle();
+        }
+    };
+    const enqueue = (value) => {
+        if (status !== "active") {
+            rejected += 1;
+            if (status === "overflowed") {
+                return Promise.reject(new RuntimeOnlyBackpressureOverflowError(options.capacity, pending, 0));
+            }
+            return Promise.reject(new Error(`Runtime-only delivery queue is ${status}`));
+        }
+        const weight = measure(value);
+        assertPositiveSafeInteger(weight, "measure result");
+        if (pending + weight > options.capacity) {
+            status = "overflowed";
+            rejected += 1;
+            return Promise.reject(new RuntimeOnlyBackpressureOverflowError(options.capacity, pending, weight));
+        }
+        accepted += 1;
+        pending += weight;
+        const result = new Promise((resolve, reject) => {
+            entries.push({ value, weight, resolve, reject });
+        });
+        ensureDrainPromise();
+        void pump();
+        return result;
+    };
+    return {
+        enqueue,
+        drain: () => {
+            if (!processing && entries.length === 0)
+                return Promise.resolve();
+            return ensureDrainPromise();
+        },
+        close: () => {
+            if (status === "closed")
+                return;
+            status = "closed";
+            while (entries.length > 0) {
+                const entry = entries.shift();
+                // v8 ignore next -- 循环条件保证 shift 必有元素
+                if (entry === undefined)
+                    continue;
+                pending -= entry.weight;
+                rejected += 1;
+                entry.reject(new Error("Runtime-only delivery queue was closed"));
+            }
+            settleDrainIfIdle();
+        },
+        snapshot: () => Object.freeze({
+            status,
+            capacity: options.capacity,
+            pending,
+            accepted,
+            delivered,
+            rejected,
+        }),
+    };
+}
+//# sourceMappingURL=runtime-delivery-queue.js.map

package/dist/testing/runtime-delivery-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-delivery-queue.js","sourceRoot":"","sources":["../../src/testing/runtime-delivery-queue.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,MAAM,CAAC,MAAM,uCAAuC,GAAG,oCAA6C,CAAC;AA6BrG,MAAM,OAAO,oCAAqC,SAAQ,KAAK;IACrD,IAAI,GAAG,uCAAuC,CAAC;IAC/C,QAAQ,CAAS;IACjB,OAAO,CAAS;IAChB,SAAS,CAAS;IAE3B,YAAY,QAAgB,EAAE,OAAe,EAAE,SAAiB,EAAE;QACjE,KAAK,CACJ,iDAAiD,OAAO,gBAAgB,SAAS,qBAAqB,QAAQ,EAAE,CAChH,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,sCAAsC,CAAC;QACnD,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAAA,CAC3B;CACD;AASD,SAAS,yBAAyB,CAAC,KAAa,EAAE,IAAY,EAAQ;IACrE,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QAC/C,MAAM,IAAI,KAAK,CAAC,+BAA+B,IAAI,kCAAkC,CAAC,CAAC;IACxF,CAAC;AAAA,CACD;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,8BAA8B,CAC7C,OAA2C,EACb;IAC9B,yBAAyB,CAAC,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IACxD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;IAC7C,MAAM,OAAO,GAAoB,EAAE,CAAC;IACpC,IAAI,MAAM,GAAmC,QAAQ,CAAC;IACtD,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,UAAU,GAAG,KAAK,CAAC;IACvB,IAAI,YAAuC,CAAC;IAC5C,IAAI,YAAsC,CAAC;IAE3C,MAAM,kBAAkB,GAAG,GAAkB,EAAE,CAAC;QAC/C,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;YAChC,YAAY,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC;gBAC7C,YAAY,GAAG,OAAO,CAAC;YAAA,CACvB,CAAC,CAAC;QACJ,CAAC;QACD,OAAO,YAAY,CAAC;IAAA,CACpB,CAAC;IAEF,MAAM,iBAAiB,GAAG,GAAS,EAAE,CAAC;QACrC,IAAI,UAAU,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO;QAC7C,YAAY,EAAE,EAAE,CAAC;QACjB,YAAY,GAAG,SAAS,CAAC;QACzB,YAAY,GAAG,SAAS,CAAC;IAAA,CACzB,CAAC;IAEF,MAAM,IAAI,GAAG,KAAK,IAAmB,EAAE,CAAC;QACvC,IAAI,UAAU;YAAE,OAAO;QACvB,UAAU,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC;YACJ,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC3B,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;gBAC9B,0DAAsC;gBACtC,IAAI,KAAK,KAAK,SAAS;oBAAE,SAAS;gBAClC,IAAI,CAAC;oBACJ,MAAM,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;oBACnC,SAAS,IAAI,CAAC,CAAC;oBACf,KAAK,CAAC,OAAO,EAAE,CAAC;gBACjB,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBAChB,MAAM,GAAG,QAAQ,CAAC;oBAClB,QAAQ,IAAI,CAAC,CAAC;oBACd,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;oBACpB,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;wBAC3B,MAAM,YAAY,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;wBACrC,0DAAsC;wBACtC,IAAI,YAAY,KAAK,SAAS;4BAAE,SAAS;wBACzC,OAAO,IAAI,YAAY,CAAC,MAAM,CAAC;wBAC/B,QAAQ,IAAI,CAAC,CAAC;wBACd,YAAY,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;oBAC5B,CAAC;gBACF,CAAC;wBAAS,CAAC;oBACV,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC;gBACzB,CAAC;gBACD,IAAI,MAAM,KAAK,QAAQ;oBAAE,MAAM;YAChC,CAAC;QACF,CAAC;gBAAS,CAAC;YACV,UAAU,GAAG,KAAK,CAAC;YACnB,iBAAiB,EAAE,CAAC;QACrB,CAAC;IAAA,CACD,CAAC;IAEF,MAAM,OAAO,GAAG,CAAC,KAAQ,EAAiB,EAAE,CAAC;QAC5C,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;YACzB,QAAQ,IAAI,CAAC,CAAC;YACd,IAAI,MAAM,KAAK,YAAY,EAAE,CAAC;gBAC7B,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,oCAAoC,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;YAC/F,CAAC;YACD,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,kCAAkC,MAAM,EAAE,CAAC,CAAC,CAAC;QAC9E,CAAC;QACD,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;QAC9B,yBAAyB,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;QACpD,IAAI,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;YACzC,MAAM,GAAG,YAAY,CAAC;YACtB,QAAQ,IAAI,CAAC,CAAC;YACd,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,oCAAoC,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;QACpG,CAAC;QACD,QAAQ,IAAI,CAAC,CAAC;QACd,OAAO,IAAI,MAAM,CAAC;QAClB,MAAM,MAAM,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC;YACrD,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;QAAA,CACjD,CAAC,CAAC;QACH,kBAAkB,EAAE,CAAC;QACrB,KAAK,IAAI,EAAE,CAAC;QACZ,OAAO,MAAM,CAAC;IAAA,CACd,CAAC;IAEF,OAAO;QACN,OAAO;QACP,KAAK,EAAE,GAAG,EAAE,CAAC;YACZ,IAAI,CAAC,UAAU,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;YAClE,OAAO,kBAAkB,EAAE,CAAC;QAAA,CAC5B;QACD,KAAK,EAAE,GAAG,EAAE,CAAC;YACZ,IAAI,MAAM,KAAK,QAAQ;gBAAE,OAAO;YAChC,MAAM,GAAG,QAAQ,CAAC;YAClB,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC3B,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;gBAC9B,0DAAsC;gBACtC,IAAI,KAAK,KAAK,SAAS;oBAAE,SAAS;gBAClC,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC;gBACxB,QAAQ,IAAI,CAAC,CAAC;gBACd,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC,CAAC;YACnE,CAAC;YACD,iBAAiB,EAAE,CAAC;QAAA,CACpB;QACD,QAAQ,EAAE,GAAG,EAAE,CACd,MAAM,CAAC,MAAM,CAAC;YACb,MAAM;YACN,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,OAAO;YACP,QAAQ;YACR,SAAS;YACT,QAAQ;SACR,CAAC;KACH,CAAC;AAAA,CACF","sourcesContent":["/** Stable error code required by the model.stream backpressure contract. */\nexport const MODEL_STREAM_BACKPRESSURE_OVERFLOW_CODE = \"model_stream_backpressure_overflow\" as const;\n\nexport type RuntimeOnlyDeliveryQueueStatus = \"active\" | \"overflowed\" | \"closed\";\n\nexport interface RuntimeOnlyDeliveryQueueSnapshot {\n\treadonly status: RuntimeOnlyDeliveryQueueStatus;\n\treadonly capacity: number;\n\t/** Weight of in-flight and queued values that have not finished delivery. */\n\treadonly pending: number;\n\treadonly accepted: number;\n\treadonly delivered: number;\n\treadonly rejected: number;\n}\n\nexport interface RuntimeOnlyDeliveryQueueOptions<T> {\n\t/** Maximum pending weight for this subscription. */\n\treadonly capacity: number;\n\t/** Defaults to one event per value. */\n\treadonly measure?: (value: T) => number;\n\treadonly deliver: (value: T) => void | Promise<void>;\n}\n\nexport interface RuntimeOnlyDeliveryQueue<T> {\n\tenqueue(value: T): Promise<void>;\n\tdrain(): Promise<void>;\n\tclose(): void;\n\tsnapshot(): RuntimeOnlyDeliveryQueueSnapshot;\n}\n\nexport class RuntimeOnlyBackpressureOverflowError extends Error {\n\treadonly code = MODEL_STREAM_BACKPRESSURE_OVERFLOW_CODE;\n\treadonly capacity: number;\n\treadonly pending: number;\n\treadonly attempted: number;\n\n\tconstructor(capacity: number, pending: number, attempted: number) {\n\t\tsuper(\n\t\t\t`Runtime-only delivery queue overflow: pending ${pending} + attempted ${attempted} exceeds capacity ${capacity}`,\n\t\t);\n\t\tthis.name = \"RuntimeOnlyBackpressureOverflowError\";\n\t\tthis.capacity = capacity;\n\t\tthis.pending = pending;\n\t\tthis.attempted = attempted;\n\t}\n}\n\ninterface QueueEntry<T> {\n\treadonly value: T;\n\treadonly weight: number;\n\treadonly resolve: () => void;\n\treadonly reject: (error: unknown) => void;\n}\n\nfunction assertPositiveSafeInteger(value: number, name: string): void {\n\tif (!Number.isSafeInteger(value) || value < 1) {\n\t\tthrow new Error(`Runtime-only delivery queue ${name} must be a positive safe integer`);\n\t}\n}\n\n/**\n * Creates a deterministic host-side subscription queue for runtime-only tests.\n *\n * Overflow rejects only the new enqueue, permanently terminates this queue,\n * and leaves already accepted values in order for delivery. Other queues are\n * independent and are not affected.\n *\n * Test-only divergence from the production lifecycle delivery queue: a handler\n * failure closes this whole queue and rejects every pending value with the\n * same error, while the production queue isolates the failure to that single\n * delivery and keeps accepting. Tests that need production semantics must use\n * the production runtime, not this fixture.\n */\nexport function createRuntimeOnlyDeliveryQueue<T>(\n\toptions: RuntimeOnlyDeliveryQueueOptions<T>,\n): RuntimeOnlyDeliveryQueue<T> {\n\tassertPositiveSafeInteger(options.capacity, \"capacity\");\n\tconst measure = options.measure ?? (() => 1);\n\tconst entries: QueueEntry<T>[] = [];\n\tlet status: RuntimeOnlyDeliveryQueueStatus = \"active\";\n\tlet pending = 0;\n\tlet accepted = 0;\n\tlet delivered = 0;\n\tlet rejected = 0;\n\tlet processing = false;\n\tlet drainPromise: Promise<void> | undefined;\n\tlet resolveDrain: (() => void) | undefined;\n\n\tconst ensureDrainPromise = (): Promise<void> => {\n\t\tif (drainPromise === undefined) {\n\t\t\tdrainPromise = new Promise<void>((resolve) => {\n\t\t\t\tresolveDrain = resolve;\n\t\t\t});\n\t\t}\n\t\treturn drainPromise;\n\t};\n\n\tconst settleDrainIfIdle = (): void => {\n\t\tif (processing || entries.length > 0) return;\n\t\tresolveDrain?.();\n\t\tdrainPromise = undefined;\n\t\tresolveDrain = undefined;\n\t};\n\n\tconst pump = async (): Promise<void> => {\n\t\tif (processing) return;\n\t\tprocessing = true;\n\t\ttry {\n\t\t\twhile (entries.length > 0) {\n\t\t\t\tconst entry = entries.shift();\n\t\t\t\t// v8 ignore next -- 循环条件保证 shift 必有元素\n\t\t\t\tif (entry === undefined) continue;\n\t\t\t\ttry {\n\t\t\t\t\tawait options.deliver(entry.value);\n\t\t\t\t\tdelivered += 1;\n\t\t\t\t\tentry.resolve();\n\t\t\t\t} catch (error) {\n\t\t\t\t\tstatus = \"closed\";\n\t\t\t\t\trejected += 1;\n\t\t\t\t\tentry.reject(error);\n\t\t\t\t\twhile (entries.length > 0) {\n\t\t\t\t\t\tconst pendingEntry = entries.shift();\n\t\t\t\t\t\t// v8 ignore next -- 循环条件保证 shift 必有元素\n\t\t\t\t\t\tif (pendingEntry === undefined) continue;\n\t\t\t\t\t\tpending -= pendingEntry.weight;\n\t\t\t\t\t\trejected += 1;\n\t\t\t\t\t\tpendingEntry.reject(error);\n\t\t\t\t\t}\n\t\t\t\t} finally {\n\t\t\t\t\tpending -= entry.weight;\n\t\t\t\t}\n\t\t\t\tif (status === \"closed\") break;\n\t\t\t}\n\t\t} finally {\n\t\t\tprocessing = false;\n\t\t\tsettleDrainIfIdle();\n\t\t}\n\t};\n\n\tconst enqueue = (value: T): Promise<void> => {\n\t\tif (status !== \"active\") {\n\t\t\trejected += 1;\n\t\t\tif (status === \"overflowed\") {\n\t\t\t\treturn Promise.reject(new RuntimeOnlyBackpressureOverflowError(options.capacity, pending, 0));\n\t\t\t}\n\t\t\treturn Promise.reject(new Error(`Runtime-only delivery queue is ${status}`));\n\t\t}\n\t\tconst weight = measure(value);\n\t\tassertPositiveSafeInteger(weight, \"measure result\");\n\t\tif (pending + weight > options.capacity) {\n\t\t\tstatus = \"overflowed\";\n\t\t\trejected += 1;\n\t\t\treturn Promise.reject(new RuntimeOnlyBackpressureOverflowError(options.capacity, pending, weight));\n\t\t}\n\t\taccepted += 1;\n\t\tpending += weight;\n\t\tconst result = new Promise<void>((resolve, reject) => {\n\t\t\tentries.push({ value, weight, resolve, reject });\n\t\t});\n\t\tensureDrainPromise();\n\t\tvoid pump();\n\t\treturn result;\n\t};\n\n\treturn {\n\t\tenqueue,\n\t\tdrain: () => {\n\t\t\tif (!processing && entries.length === 0) return Promise.resolve();\n\t\t\treturn ensureDrainPromise();\n\t\t},\n\t\tclose: () => {\n\t\t\tif (status === \"closed\") return;\n\t\t\tstatus = \"closed\";\n\t\t\twhile (entries.length > 0) {\n\t\t\t\tconst entry = entries.shift();\n\t\t\t\t// v8 ignore next -- 循环条件保证 shift 必有元素\n\t\t\t\tif (entry === undefined) continue;\n\t\t\t\tpending -= entry.weight;\n\t\t\t\trejected += 1;\n\t\t\t\tentry.reject(new Error(\"Runtime-only delivery queue was closed\"));\n\t\t\t}\n\t\t\tsettleDrainIfIdle();\n\t\t},\n\t\tsnapshot: () =>\n\t\t\tObject.freeze({\n\t\t\t\tstatus,\n\t\t\t\tcapacity: options.capacity,\n\t\t\t\tpending,\n\t\t\t\taccepted,\n\t\t\t\tdelivered,\n\t\t\t\trejected,\n\t\t\t}),\n\t};\n}\n"]}

package/dist/testing/session-plugin-testkit.d.ts

@@ -0,0 +1,144 @@
+import type { Agent } from "@agent-forge/agent-core";
+import { type FauxProviderRegistration, type FauxResponseStep } from "@agent-forge/ai/compat";
+import type { AgentSession } from "../core/agent-session.ts";
+import type { CapabilityPluginFactory } from "../core/extensions/capability-plugin.ts";
+import { type CapabilityRuntime } from "../core/extensions/capability-runtime.ts";
+import type { AgentCompositionAPI, CapabilityAPI, HostCapabilities, PluginManifest, RuntimeInspectorSnapshot } from "../core/extensions/public-api.ts";
+import type { ToolDefinition } from "../core/tools/tool-definition.ts";
+export interface SessionPluginTestKitPlugin {
+    readonly manifest: PluginManifest;
+    readonly factory: CapabilityPluginFactory;
+}
+export interface SessionPluginTestKitOptions {
+    readonly plugins: readonly SessionPluginTestKitPlugin[];
+    readonly responses?: readonly FauxResponseStep[];
+    readonly providerId?: string;
+    readonly api?: string;
+    readonly composition?: AgentCompositionAPI;
+    /** Custom tools registered on the fixture session for gated lifecycle scenarios. */
+    readonly tools?: readonly ToolDefinition[];
+    /** Post-run continuation strategy name selected through the public AgentSession config. */
+    readonly runLoopStrategyName?: string;
+}
+export interface SessionPluginTestKitInspector {
+    readonly host: HostCapabilities;
+    readonly plugins: readonly {
+        readonly id: string;
+        readonly version: string;
+        readonly active: boolean;
+        readonly provides: RuntimeInspectorSnapshot["plugins"][number]["provides"];
+        readonly requires: RuntimeInspectorSnapshot["plugins"][number]["requires"];
+    }[];
+    readonly registrations: RuntimeInspectorSnapshot["registrations"];
+    readonly contributionPoints: readonly {
+        readonly id: string;
+        readonly version: number;
+        readonly lifecycle: string;
+        readonly owner: string;
+        readonly active: boolean;
+    }[];
+    readonly contributions: readonly {
+        readonly id: string;
+        readonly pointId: string;
+        readonly version: number;
+        readonly owner: string;
+        readonly lifecycle: string;
+    }[];
+    readonly lifecycle: readonly {
+        readonly id: string;
+        readonly version: number;
+        readonly phase: string;
+        readonly schema: string;
+        readonly owner: string;
+        readonly active: boolean;
+        readonly registrations: readonly {
+            readonly id: string;
+            readonly kind: string;
+            readonly owner: string;
+        }[];
+    }[];
+    readonly lifecycleReports: readonly {
+        readonly eventId: string;
+        readonly type: string;
+        readonly version: number;
+        readonly phase: string;
+        readonly status: string;
+        readonly attempted: number;
+        readonly succeeded: number;
+        readonly queued?: number;
+        readonly failed: number;
+        readonly failures: readonly {
+            readonly pluginId: string;
+            readonly registrationId: string;
+            readonly kind: string;
+            readonly error: unknown;
+        }[];
+    }[];
+    readonly pluginRejections: RuntimeInspectorSnapshot["pluginRejections"];
+    readonly subscriptions: RuntimeInspectorSnapshot["subscriptions"];
+    readonly operations: RuntimeInspectorSnapshot["operations"];
+    readonly logs: readonly {
+        readonly version: 1;
+        readonly level: string;
+        readonly message: string;
+        readonly fields?: unknown;
+        readonly cause?: unknown;
+        readonly pluginId: string;
+        readonly sessionId?: string;
+        readonly operationId?: string;
+        readonly correlationId?: string;
+        readonly phase?: string;
+    }[];
+    readonly spans: readonly {
+        readonly version: 1;
+        readonly traceId: string;
+        readonly spanId: string;
+        readonly parentSpanId?: string;
+        readonly name: string;
+        readonly pluginId: string;
+        readonly sessionId?: string;
+        readonly status: string;
+        readonly attributes: unknown;
+        readonly result?: unknown;
+        readonly cause?: unknown;
+        readonly operationId?: string;
+        readonly correlationId?: string;
+        readonly phase?: string;
+    }[];
+}
+export interface SessionPluginTestKitTranscript {
+    readonly version: 1;
+    readonly sessionId: string;
+    readonly revision: number;
+    readonly loadOrder: readonly string[];
+    readonly fauxCallCount: number;
+    readonly messages: readonly {
+        readonly role: string;
+        readonly text: string;
+    }[];
+    readonly entries: readonly {
+        readonly type: string;
+        readonly customType?: string;
+        readonly data?: unknown;
+    }[];
+    readonly inspector: SessionPluginTestKitInspector;
+}
+export interface SessionPluginTestKit {
+    readonly ready: Promise<void>;
+    readonly session: AgentSession;
+    readonly agent: Agent;
+    readonly runtime: CapabilityRuntime;
+    readonly faux: FauxProviderRegistration;
+    api(pluginId: string): CapabilityAPI;
+    revoke(pluginId: string): void;
+    /** Throws when a scripted response was not consumed by the fixture. */
+    assertResponsesConsumed(): void;
+    inspect(): RuntimeInspectorSnapshot;
+    transcript(): SessionPluginTestKitTranscript;
+    dispose(): Promise<void>;
+}
+/** Create a complete deterministic AgentSession fixture and load inline capability plugins. */
+export declare function createSessionPluginTestKit(options: SessionPluginTestKitOptions): Promise<SessionPluginTestKit>;
+/** Runs a session fixture repeatedly and rejects on the first transcript divergence. */
+export declare function repeatSessionPluginTestKit(times: number, run: () => Promise<SessionPluginTestKitTranscript>): Promise<SessionPluginTestKitTranscript>;
+//# sourceMappingURL=session-plugin-testkit.d.ts.map

package/dist/testing/session-plugin-testkit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-plugin-testkit.d.ts","sourceRoot":"","sources":["../../src/testing/session-plugin-testkit.ts"],"names":[],"mappings":"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","sourcesContent":["import { mkdtemp, rm } from \"node:fs/promises\";\nimport { tmpdir } from \"node:os\";\nimport { join } from \"node:path\";\nimport type { Agent } from \"@agent-forge/agent-core\";\nimport {\n\ttype FauxProviderRegistration,\n\ttype FauxResponseStep,\n\tregisterFauxProvider,\n\tstreamSimple,\n} from \"@agent-forge/ai/compat\";\nimport type { AgentSession } from \"../core/agent-session.ts\";\nimport { AuthStorage } from \"../core/auth-storage.ts\";\nimport type { CapabilityPluginFactory, CapabilityPluginHandle } from \"../core/extensions/capability-plugin.ts\";\nimport { type CapabilityRuntime, resolvePluginCapabilityOrder } from \"../core/extensions/capability-runtime.ts\";\nimport type {\n\tAgentCompositionAPI,\n\tCapabilityAPI,\n\tHostCapabilities,\n\tPluginManifest,\n\tRuntimeInspectorSnapshot,\n} from \"../core/extensions/public-api.ts\";\nimport { ModelRuntime } from \"../core/model-runtime.ts\";\nimport { InMemoryCodingAgentModelsStore } from \"../core/models-store.ts\";\nimport { DefaultResourceLoader } from \"../core/resource-loader.ts\";\nimport { createAgentSession } from \"../core/sdk.ts\";\nimport { SessionManager } from \"../core/session-manager.ts\";\nimport { SettingsManager } from \"../core/settings-manager.ts\";\nimport type { ToolDefinition } from \"../core/tools/tool-definition.ts\";\n\nexport interface SessionPluginTestKitPlugin {\n\treadonly manifest: PluginManifest;\n\treadonly factory: CapabilityPluginFactory;\n}\n\nexport interface SessionPluginTestKitOptions {\n\treadonly plugins: readonly SessionPluginTestKitPlugin[];\n\treadonly responses?: readonly FauxResponseStep[];\n\treadonly providerId?: string;\n\treadonly api?: string;\n\treadonly composition?: AgentCompositionAPI;\n\t/** Custom tools registered on the fixture session for gated lifecycle scenarios. */\n\treadonly tools?: readonly ToolDefinition[];\n\t/** Post-run continuation strategy name selected through the public AgentSession config. */\n\treadonly runLoopStrategyName?: string;\n}\n\nexport interface SessionPluginTestKitInspector {\n\treadonly host: HostCapabilities;\n\treadonly plugins: readonly {\n\t\treadonly id: string;\n\t\treadonly version: string;\n\t\treadonly active: boolean;\n\t\treadonly provides: RuntimeInspectorSnapshot[\"plugins\"][number][\"provides\"];\n\t\treadonly requires: RuntimeInspectorSnapshot[\"plugins\"][number][\"requires\"];\n\t}[];\n\treadonly registrations: RuntimeInspectorSnapshot[\"registrations\"];\n\treadonly contributionPoints: readonly {\n\t\treadonly id: string;\n\t\treadonly version: number;\n\t\treadonly lifecycle: string;\n\t\treadonly owner: string;\n\t\treadonly active: boolean;\n\t}[];\n\treadonly contributions: readonly {\n\t\treadonly id: string;\n\t\treadonly pointId: string;\n\t\treadonly version: number;\n\t\treadonly owner: string;\n\t\treadonly lifecycle: string;\n\t}[];\n\treadonly lifecycle: readonly {\n\t\treadonly id: string;\n\t\treadonly version: number;\n\t\treadonly phase: string;\n\t\treadonly schema: string;\n\t\treadonly owner: string;\n\t\treadonly active: boolean;\n\t\treadonly registrations: readonly { readonly id: string; readonly kind: string; readonly owner: string }[];\n\t}[];\n\treadonly lifecycleReports: readonly {\n\t\treadonly eventId: string;\n\t\treadonly type: string;\n\t\treadonly version: number;\n\t\treadonly phase: string;\n\t\treadonly status: string;\n\t\treadonly attempted: number;\n\t\treadonly succeeded: number;\n\t\treadonly queued?: number;\n\t\treadonly failed: number;\n\t\treadonly failures: readonly {\n\t\t\treadonly pluginId: string;\n\t\t\treadonly registrationId: string;\n\t\t\treadonly kind: string;\n\t\t\treadonly error: unknown;\n\t\t}[];\n\t}[];\n\treadonly pluginRejections: RuntimeInspectorSnapshot[\"pluginRejections\"];\n\treadonly subscriptions: RuntimeInspectorSnapshot[\"subscriptions\"];\n\treadonly operations: RuntimeInspectorSnapshot[\"operations\"];\n\treadonly logs: readonly {\n\t\treadonly version: 1;\n\t\treadonly level: string;\n\t\treadonly message: string;\n\t\treadonly fields?: unknown;\n\t\treadonly cause?: unknown;\n\t\treadonly pluginId: string;\n\t\treadonly sessionId?: string;\n\t\treadonly operationId?: string;\n\t\treadonly correlationId?: string;\n\t\treadonly phase?: string;\n\t}[];\n\treadonly spans: readonly {\n\t\treadonly version: 1;\n\t\treadonly traceId: string;\n\t\treadonly spanId: string;\n\t\treadonly parentSpanId?: string;\n\t\treadonly name: string;\n\t\treadonly pluginId: string;\n\t\treadonly sessionId?: string;\n\t\treadonly status: string;\n\t\treadonly attributes: unknown;\n\t\treadonly result?: unknown;\n\t\treadonly cause?: unknown;\n\t\treadonly operationId?: string;\n\t\treadonly correlationId?: string;\n\t\treadonly phase?: string;\n\t}[];\n}\n\nexport interface SessionPluginTestKitTranscript {\n\treadonly version: 1;\n\treadonly sessionId: string;\n\treadonly revision: number;\n\treadonly loadOrder: readonly string[];\n\treadonly fauxCallCount: number;\n\treadonly messages: readonly { readonly role: string; readonly text: string }[];\n\treadonly entries: readonly { readonly type: string; readonly customType?: string; readonly data?: unknown }[];\n\treadonly inspector: SessionPluginTestKitInspector;\n}\n\nexport interface SessionPluginTestKit {\n\treadonly ready: Promise<void>;\n\treadonly session: AgentSession;\n\treadonly agent: Agent;\n\treadonly runtime: CapabilityRuntime;\n\treadonly faux: FauxProviderRegistration;\n\tapi(pluginId: string): CapabilityAPI;\n\trevoke(pluginId: string): void;\n\t/** Throws when a scripted response was not consumed by the fixture. */\n\tassertResponsesConsumed(): void;\n\tinspect(): RuntimeInspectorSnapshot;\n\ttranscript(): SessionPluginTestKitTranscript;\n\tdispose(): Promise<void>;\n}\n\nconst FIXED_SESSION_ID = \"session-plugin-testkit\";\nconst DEFAULT_PROVIDER_ID = \"faux-session-plugin-testkit\";\nconst DEFAULT_API = \"faux:session-plugin-testkit\";\n\nfunction stableText(message: unknown): string {\n\t// v8 ignore next -- 消息对象恒带 content 字段（AgentMessage 类型契约）\n\tif (!message || typeof message !== \"object\" || !(\"content\" in message)) return \"\";\n\tconst content = (message as { content?: unknown }).content;\n\t// v8 ignore next -- 助手消息的 content 恒为分段数组，字符串路径不会被命中\n\tif (typeof content === \"string\") return content;\n\t// v8 ignore next -- 同上：content 恒为数组\n\tif (!Array.isArray(content)) return \"\";\n\treturn content\n\t\t.filter((part): part is { type: \"text\"; text: string } => {\n\t\t\treturn (\n\t\t\t\ttypeof part === \"object\" &&\n\t\t\t\tpart !== null &&\n\t\t\t\t(part as { type?: unknown }).type === \"text\" &&\n\t\t\t\ttypeof (part as { text?: unknown }).text === \"string\"\n\t\t\t);\n\t\t})\n\t\t.map((part) => part.text)\n\t\t.join(\"\\n\");\n}\n\nfunction freezeSnapshot<T>(value: T): T {\n\tconst clone = structuredClone(value);\n\tconst freeze = (candidate: unknown): void => {\n\t\tif (!candidate || typeof candidate !== \"object\" || ArrayBuffer.isView(candidate)) return;\n\t\tfor (const child of Object.values(candidate as Record<string, unknown>)) freeze(child);\n\t\tObject.freeze(candidate);\n\t};\n\tfreeze(clone);\n\treturn clone;\n}\n\nfunction transcriptValue(value: unknown, seen = new WeakSet<object>()): unknown {\n\tif (value === null || typeof value === \"string\" || typeof value === \"boolean\") return value;\n\tif (typeof value === \"number\") return Number.isFinite(value) ? value : String(value);\n\tif (typeof value === \"bigint\") return `${value}n`;\n\tif (value === undefined) return null;\n\tif (value instanceof Error) {\n\t\t// v8 ignore next -- 错误经过 structuredClone 落盘，克隆体不可能形成循环引用\n\t\tif (seen.has(value)) return \"[Circular]\";\n\t\tseen.add(value);\n\t\tconst output: Record<string, unknown> = { name: value.name, message: value.message };\n\t\tconst code = (value as Error & { code?: unknown }).code;\n\t\tif (code !== undefined) output.code = transcriptValue(code, seen);\n\t\tconst cause = (value as Error & { cause?: unknown }).cause;\n\t\tif (cause !== undefined) output.cause = transcriptValue(cause, seen);\n\t\tfor (const key of Object.keys(value).sort()) {\n\t\t\tif (key === \"code\" || key === \"cause\") continue;\n\t\t\toutput[key] = transcriptValue((value as unknown as Record<string, unknown>)[key], seen);\n\t\t}\n\t\treturn output;\n\t}\n\t// v8 ignore next -- 值均来自 structuredClone 克隆，函数/符号无法存活\n\tif (typeof value !== \"object\") return String(value);\n\t// v8 ignore next -- 同上：克隆后的对象图无循环引用\n\tif (seen.has(value)) return \"[Circular]\";\n\tseen.add(value);\n\tif (Array.isArray(value)) return value.map((item) => transcriptValue(item, seen));\n\tconst output: Record<string, unknown> = {};\n\tfor (const key of Object.keys(value as Record<string, unknown>).sort()) {\n\t\toutput[key] = transcriptValue((value as Record<string, unknown>)[key], seen);\n\t}\n\treturn output;\n}\n\nfunction canonicalJson(value: unknown): string {\n\tconst serialized = JSON.stringify(transcriptValue(value));\n\t// v8 ignore next -- transcriptValue 已消毒全部值，JSON.stringify 不会返回 undefined\n\tif (serialized === undefined) throw new Error(\"Session plugin testkit transcript is not JSON-serializable\");\n\treturn serialized;\n}\n\n/**\n * The host's agentDir is the fixture's mkdtemp path — environment-specific and\n * random per run, not a behavioral signal. Mask it so repeated-run transcript\n * comparisons stay deterministic (D-075 S4 added agentDir to HostCapabilities).\n */\nfunction normalizeInspectorHost(host: HostCapabilities): HostCapabilities {\n\tif (typeof host.agentDir !== \"string\" || host.agentDir.length === 0) return host;\n\treturn { ...host, agentDir: \"<agentDir>\" };\n}\n\nfunction stableInspector(snapshot: RuntimeInspectorSnapshot): SessionPluginTestKitInspector {\n\treturn {\n\t\thost: normalizeInspectorHost(snapshot.host),\n\t\tplugins: snapshot.plugins.map(({ id, version, active, provides, requires }) => ({\n\t\t\tid,\n\t\t\tversion,\n\t\t\tactive,\n\t\t\tprovides,\n\t\t\trequires,\n\t\t})),\n\t\tregistrations: snapshot.registrations,\n\t\tcontributionPoints: snapshot.contributionPoints.map(({ id, version, lifecycle, owner, active }) => ({\n\t\t\tid,\n\t\t\tversion,\n\t\t\tlifecycle,\n\t\t\towner,\n\t\t\tactive,\n\t\t})),\n\t\tcontributions: snapshot.contributions.map(({ id, pointId, version, owner, lifecycle }) => ({\n\t\t\tid,\n\t\t\tpointId,\n\t\t\tversion,\n\t\t\towner,\n\t\t\tlifecycle,\n\t\t})),\n\t\tlifecycle: snapshot.lifecycle.map(({ id, version, phase, schema, owner, active, registrations }) => ({\n\t\t\tid,\n\t\t\tversion,\n\t\t\tphase,\n\t\t\tschema,\n\t\t\towner,\n\t\t\tactive,\n\t\t\tregistrations,\n\t\t})),\n\t\tlifecycleReports: snapshot.lifecycleReports.map(\n\t\t\t({ eventId, type, version, phase, status, attempted, succeeded, failed, failures }) => ({\n\t\t\t\teventId,\n\t\t\t\ttype,\n\t\t\t\tversion,\n\t\t\t\tphase,\n\t\t\t\tstatus,\n\t\t\t\tattempted,\n\t\t\t\tsucceeded,\n\t\t\t\tfailed,\n\t\t\t\tfailures: failures.map(({ pluginId, registrationId, kind, error }) => ({\n\t\t\t\t\tpluginId,\n\t\t\t\t\tregistrationId,\n\t\t\t\t\tkind,\n\t\t\t\t\terror: transcriptValue(error),\n\t\t\t\t})),\n\t\t\t}),\n\t\t),\n\t\tpluginRejections: snapshot.pluginRejections,\n\t\tsubscriptions: snapshot.subscriptions,\n\t\toperations: snapshot.operations,\n\t\tlogs: snapshot.logs.map(\n\t\t\t({ version, level, message, fields, cause, pluginId, sessionId, operationId, correlationId, phase }) => ({\n\t\t\t\tversion,\n\t\t\t\tlevel,\n\t\t\t\tmessage,\n\t\t\t\t...(fields === undefined ? {} : { fields: transcriptValue(fields) }),\n\t\t\t\t...(cause === undefined ? {} : { cause: transcriptValue(cause) }),\n\t\t\t\tpluginId,\n\t\t\t\t...(sessionId === undefined ? {} : { sessionId }),\n\t\t\t\t...(operationId === undefined ? {} : { operationId }),\n\t\t\t\t...(correlationId === undefined ? {} : { correlationId }),\n\t\t\t\t...(phase === undefined ? {} : { phase }),\n\t\t\t}),\n\t\t),\n\t\tspans: snapshot.spans.map(\n\t\t\t({\n\t\t\t\tversion,\n\t\t\t\ttraceId,\n\t\t\t\tspanId,\n\t\t\t\tparentSpanId,\n\t\t\t\tname,\n\t\t\t\tpluginId,\n\t\t\t\tsessionId,\n\t\t\t\tstatus,\n\t\t\t\tattributes,\n\t\t\t\tresult,\n\t\t\t\tcause,\n\t\t\t\toperationId,\n\t\t\t\tcorrelationId,\n\t\t\t\tphase,\n\t\t\t}) => ({\n\t\t\t\tversion,\n\t\t\t\ttraceId,\n\t\t\t\tspanId,\n\t\t\t\t...(parentSpanId === undefined ? {} : { parentSpanId }),\n\t\t\t\tname,\n\t\t\t\tpluginId,\n\t\t\t\t...(sessionId === undefined ? {} : { sessionId }),\n\t\t\t\tattributes: transcriptValue(attributes),\n\t\t\t\tstatus,\n\t\t\t\t...(result === undefined ? {} : { result: transcriptValue(result) }),\n\t\t\t\t...(cause === undefined ? {} : { cause: transcriptValue(cause) }),\n\t\t\t\t...(operationId === undefined ? {} : { operationId }),\n\t\t\t\t...(correlationId === undefined ? {} : { correlationId }),\n\t\t\t\t...(phase === undefined ? {} : { phase }),\n\t\t\t}),\n\t\t),\n\t};\n}\n\nfunction modelConfig(model: {\n\tid: string;\n\tname: string;\n\tapi: string;\n\tprovider: string;\n\tbaseUrl: string;\n\treasoning: boolean;\n\tinput: readonly (\"text\" | \"image\")[];\n\tcost: { input: number; output: number; cacheRead: number; cacheWrite: number };\n\tcontextWindow: number;\n\tmaxTokens: number;\n}) {\n\treturn {\n\t\tid: model.id,\n\t\tname: model.name,\n\t\tapi: model.api,\n\t\tprovider: model.provider,\n\t\tbaseUrl: model.baseUrl,\n\t\treasoning: model.reasoning,\n\t\tinput: [...model.input],\n\t\tcost: model.cost,\n\t\tcontextWindow: model.contextWindow,\n\t\tmaxTokens: model.maxTokens,\n\t};\n}\n\n/** Create a complete deterministic AgentSession fixture and load inline capability plugins. */\nexport async function createSessionPluginTestKit(options: SessionPluginTestKitOptions): Promise<SessionPluginTestKit> {\n\tconst tempDir = await mkdtemp(join(tmpdir(), \"agent-forge-session-plugin-testkit-\"));\n\tconst providerId = options.providerId ?? DEFAULT_PROVIDER_ID;\n\tconst apiName = options.api ?? DEFAULT_API;\n\tlet faux: FauxProviderRegistration | undefined;\n\tlet session: AgentSession | undefined;\n\ttry {\n\t\tfaux = registerFauxProvider({\n\t\t\tapi: apiName,\n\t\t\tprovider: providerId,\n\t\t\tclock: () => 0,\n\t\t\tidFactory: (prefix, sequence) => `${prefix}-${sequence}`,\n\t\t});\n\t\tif (options.responses) faux.setResponses([...options.responses]);\n\t\tconst fauxRegistration = faux;\n\t\tconst model = fauxRegistration.getModel();\n\t\tconst authStorage = AuthStorage.inMemory();\n\t\tawait authStorage.modify(providerId, async () => ({ type: \"api_key\", key: \"faux-key\" }));\n\t\tconst modelRuntime = await ModelRuntime.create({\n\t\t\tcredentials: authStorage,\n\t\t\tmodelsPath: null,\n\t\t\tmodelsStore: new InMemoryCodingAgentModelsStore(),\n\t\t\tallowModelNetwork: false,\n\t\t\trefreshOnCreate: false,\n\t\t});\n\t\tmodelRuntime.registerProvider(providerId, {\n\t\t\tbaseUrl: model.baseUrl,\n\t\t\tapi: apiName,\n\t\t\tapiKey: \"faux-key\",\n\t\t\tmodels: fauxRegistration.models.map(modelConfig),\n\t\t});\n\t\tconst settingsManager = SettingsManager.create(tempDir, tempDir);\n\t\tconst resourceLoader = new DefaultResourceLoader({\n\t\t\tcwd: tempDir,\n\t\t\tagentDir: tempDir,\n\t\t\tsettingsManager,\n\t\t\tnoSkills: true,\n\t\t\tnoPromptTemplates: true,\n\t\t\tnoThemes: true,\n\t\t\tnoContextFiles: true,\n\t\t});\n\t\tawait resourceLoader.reload();\n\t\tconst sessionManager = SessionManager.inMemory(tempDir, { id: FIXED_SESSION_ID });\n\t\tconst created = await createAgentSession({\n\t\t\tagentDir: tempDir,\n\t\t\tnoTools: \"all\",\n\t\t\t// Custom fixture tools must be allowlisted explicitly: noTools=\"all\"\n\t\t\t// clears the allowlist, which would otherwise leave them inactive.\n\t\t\t...(options.tools === undefined\n\t\t\t\t? {}\n\t\t\t\t: { tools: options.tools.map((tool) => tool.name), customTools: [...options.tools] }),\n\t\t\tdiscoverCapabilityPlugins: false,\n\t\t\tenableAgentTasks: false,\n\t\t\t...(options.runLoopStrategyName === undefined ? {} : { runLoopStrategyName: options.runLoopStrategyName }),\n\t\t\tstreamFn: streamSimple,\n\t\t\tmodel,\n\t\t\tmodelRuntime,\n\t\t\tresourceLoader,\n\t\t\tsessionManager,\n\t\t\tsettingsManager,\n\t\t\tcwd: tempDir,\n\t\t\tagentComposition: options.composition,\n\t\t}).then(({ session: createdSession }) => createdSession);\n\t\tsession = created;\n\t\tconst activeSession = session;\n\t\tconst initialRuntime = activeSession.getCapabilityRuntime();\n\t\tconst handles = new Map<string, CapabilityPluginHandle>();\n\t\tconst pluginByManifest = new Map(options.plugins.map((plugin) => [plugin.manifest, plugin]));\n\t\tlet closing = false;\n\t\tlet disposed = false;\n\t\tlet disposePromise: Promise<void> | undefined;\n\t\tconst cleanup = async (): Promise<void> => {\n\t\t\tconst failures: unknown[] = [];\n\t\t\tfor (const handle of [...handles.values()].reverse()) {\n\t\t\t\ttry {\n\t\t\t\t\tawait handle.dispose();\n\t\t\t\t} catch (error) {\n\t\t\t\t\tfailures.push(error);\n\t\t\t\t}\n\t\t\t}\n\t\t\thandles.clear();\n\t\t\ttry {\n\t\t\t\tawait session?.dispose();\n\t\t\t} catch (error) {\n\t\t\t\tfailures.push(error);\n\t\t\t}\n\t\t\ttry {\n\t\t\t\tfaux?.unregister();\n\t\t\t\tawait rm(tempDir, { recursive: true, force: true });\n\t\t\t} catch (error) {\n\t\t\t\tfailures.push(error);\n\t\t\t}\n\t\t\tif (failures.length === 1) throw failures[0];\n\t\t\tif (failures.length > 1) throw new AggregateError(failures, \"Session plugin testkit cleanup failed\");\n\t\t};\n\t\tconst ready = (async () => {\n\t\t\ttry {\n\t\t\t\tfor (const manifest of resolvePluginCapabilityOrder(options.plugins.map((plugin) => plugin.manifest))) {\n\t\t\t\t\t// v8 ignore next -- kit 仅在 ready 成功后返回，startup 期间不会调用 dispose\n\t\t\t\t\tif (closing) throw new Error(\"Session plugin testkit was disposed during startup\");\n\t\t\t\t\tconst plugin = pluginByManifest.get(manifest);\n\t\t\t\t\t// v8 ignore next -- plugins 数组同时供给加载顺序与 factory 映射，必可解析\n\t\t\t\t\tif (!plugin) throw new Error(`Session plugin testkit cannot resolve factory: ${manifest.id}`);\n\t\t\t\t\tconst handle = await activeSession.loadCapabilityPlugin(manifest, plugin.factory);\n\t\t\t\t\thandles.set(manifest.id, handle);\n\t\t\t\t}\n\t\t\t} catch (error) {\n\t\t\t\ttry {\n\t\t\t\t\tawait cleanup();\n\t\t\t\t} catch (cleanupError) {\n\t\t\t\t\tthrow new AggregateError([error, cleanupError], \"Session plugin testkit startup rollback failed\");\n\t\t\t\t}\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t})();\n\t\tconst kit: SessionPluginTestKit = {\n\t\t\tready,\n\t\t\tsession: activeSession,\n\t\t\tagent: activeSession.agent,\n\t\t\tget runtime(): CapabilityRuntime {\n\t\t\t\tif (disposed) throw new Error(\"Session plugin testkit runtime is disposed\");\n\t\t\t\treturn activeSession.getCapabilityRuntime();\n\t\t\t},\n\t\t\tfaux: fauxRegistration,\n\t\t\tapi(pluginId) {\n\t\t\t\tif (activeSession.getCapabilityRuntime() !== initialRuntime) {\n\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t\"Session plugin testkit plugin API handles expire after session reload; access the current runtime directly\",\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\tconst handle = handles.get(pluginId);\n\t\t\t\tif (!handle) throw new Error(`Session plugin testkit has no loaded plugin: ${pluginId}`);\n\t\t\t\treturn handle.api;\n\t\t\t},\n\t\t\trevoke(pluginId) {\n\t\t\t\tif (activeSession.getCapabilityRuntime() !== initialRuntime) {\n\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t\"Session plugin testkit plugin API handles expire after session reload; access the current runtime directly\",\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\tconst handle = handles.get(pluginId);\n\t\t\t\tif (!handle) throw new Error(`Session plugin testkit has no loaded plugin: ${pluginId}`);\n\t\t\t\tactiveSession.getCapabilityRuntime().revokeAPI(handle.api);\n\t\t\t},\n\t\t\tassertResponsesConsumed() {\n\t\t\t\tconst pending = fauxRegistration.getPendingResponseCount();\n\t\t\t\tif (pending !== 0) {\n\t\t\t\t\tthrow new Error(`Session plugin testkit has ${pending} unused faux response${pending === 1 ? \"\" : \"s\"}`);\n\t\t\t\t}\n\t\t\t},\n\t\t\tinspect: () => activeSession.getCapabilityRuntime().inspect(),\n\t\t\ttranscript: () => {\n\t\t\t\tconst branch = sessionManager.getBranch();\n\t\t\t\tconst transcript: SessionPluginTestKitTranscript = {\n\t\t\t\t\tversion: 1,\n\t\t\t\t\tsessionId: sessionManager.getSessionId(),\n\t\t\t\t\trevision: sessionManager.getRevision().sequence,\n\t\t\t\t\tloadOrder: [...handles.keys()],\n\t\t\t\t\tfauxCallCount: fauxRegistration.state.callCount,\n\t\t\t\t\tmessages: activeSession.agent.state.messages.map((message) => ({\n\t\t\t\t\t\trole: message.role,\n\t\t\t\t\t\ttext: stableText(message),\n\t\t\t\t\t})),\n\t\t\t\t\tentries: branch.map((entry) => ({\n\t\t\t\t\t\ttype: entry.type,\n\t\t\t\t\t\t...(entry.type === \"custom\"\n\t\t\t\t\t\t\t? {\n\t\t\t\t\t\t\t\t\tcustomType: entry.customType,\n\t\t\t\t\t\t\t\t\t...(entry.data === undefined ? {} : { data: transcriptValue(entry.data) }),\n\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t: {}),\n\t\t\t\t\t})),\n\t\t\t\t\tinspector: stableInspector(activeSession.getCapabilityRuntime().inspect()),\n\t\t\t\t};\n\t\t\t\treturn freezeSnapshot(transcript);\n\t\t\t},\n\t\t\tdispose: async () => {\n\t\t\t\tdisposePromise ??= (async () => {\n\t\t\t\t\tclosing = true;\n\t\t\t\t\ttry {\n\t\t\t\t\t\tawait ready;\n\t\t\t\t\t} catch {\n\t\t\t\t\t\t// Startup rollback already disposed the session and faux provider.\n\t\t\t\t\t\t// v8 ignore next -- ready 已在返回前 await，dispose 中不会进入该 catch\n\t\t\t\t\t\tif (session?.isDisposed) {\n\t\t\t\t\t\t\tdisposed = true;\n\t\t\t\t\t\t\treturn;\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t\ttry {\n\t\t\t\t\t\tawait cleanup();\n\t\t\t\t\t} finally {\n\t\t\t\t\t\tdisposed = true;\n\t\t\t\t\t}\n\t\t\t\t})();\n\t\t\t\treturn disposePromise;\n\t\t\t},\n\t\t};\n\t\tawait ready;\n\t\treturn kit;\n\t} catch (error) {\n\t\ttry {\n\t\t\tsession && (await session.dispose());\n\t\t} finally {\n\t\t\tfaux?.unregister();\n\t\t\tawait rm(tempDir, { recursive: true, force: true });\n\t\t}\n\t\tthrow error;\n\t}\n}\n\n/** Runs a session fixture repeatedly and rejects on the first transcript divergence. */\nexport async function repeatSessionPluginTestKit(\n\ttimes: number,\n\trun: () => Promise<SessionPluginTestKitTranscript>,\n): Promise<SessionPluginTestKitTranscript> {\n\tif (!Number.isSafeInteger(times) || times < 1)\n\t\tthrow new Error(\"Session plugin testkit repeat count must be a positive integer\");\n\tlet baseline: SessionPluginTestKitTranscript | undefined;\n\tfor (let index = 0; index < times; index += 1) {\n\t\tconst transcript = await run();\n\t\tif (baseline && canonicalJson(transcript) !== canonicalJson(baseline)) {\n\t\t\tthrow new Error(`Session plugin testkit transcript diverged on run ${index + 1}`);\n\t\t}\n\t\tbaseline = transcript;\n\t}\n\treturn baseline!;\n}\n"]}