@ai-agent-forge/agent-forge 0.85.0

package/dist/share/session-share.d.ts

@@ -0,0 +1,98 @@
+/**
+ * session-share contract (2.6c) — an explicit, revocable share contract with
+ * a permission context, scope whitelist, and artifact references.
+ *
+ * A share contract is created for one session with a read-only permission
+ * context and an explicit scope (messages on/off, artifact whitelist).
+ * Resolution fails structurally for revoked, expired, out-of-scope, or
+ * unknown requests — nothing is implicitly included. Revocation is the
+ * cancellation path and is terminal. Transports are injected explicitly by
+ * the caller (the kernel ships none); HTML/viewer integration is 2.6d.
+ */
+import type { JsonValue } from "@agent-forge/ai";
+export interface ShareScopeV1 {
+    readonly messages: boolean;
+    /** Exact artifact references shareable under this contract. */
+    readonly artifacts: readonly string[];
+    readonly diagnostics: boolean;
+}
+export interface ShareContractV1 {
+    readonly shareId: string;
+    readonly sessionId: string;
+    readonly permission: "read_only";
+    readonly scope: ShareScopeV1;
+    readonly createdAt: number;
+    readonly expiresAt?: number;
+}
+export interface ShareArtifactInputV1 {
+    readonly artifactId: string;
+    readonly mediaType: string;
+    readonly bytesBase64: string;
+}
+export type ShareResolveRequestV1 = {
+    readonly kind: "messages";
+} | {
+    readonly kind: "diagnostics";
+} | {
+    readonly kind: "artifact";
+    readonly artifactId: string;
+};
+export type ShareResolveResultV1 = {
+    readonly status: "resolved";
+    readonly kind: "messages";
+    readonly content: JsonValue;
+} | {
+    readonly status: "resolved";
+    readonly kind: "diagnostics";
+    readonly content: JsonValue;
+} | {
+    readonly status: "resolved";
+    readonly kind: "artifact";
+    readonly artifact: ShareArtifactInputV1;
+} | {
+    readonly status: "denied";
+    readonly reason: string;
+} | {
+    readonly status: "not_found";
+    readonly shareId: string;
+};
+export type ShareTransportPayloadV1 = JsonValue | ShareResolveResultV1;
+export interface ShareTransportV1 {
+    readonly id: string;
+    send(input: {
+        readonly contract: ShareContractV1;
+        readonly payload: ShareTransportPayloadV1;
+    }): {
+        readonly accepted: boolean;
+    };
+}
+export interface SessionShareManagerV1 {
+    createShare(input: {
+        readonly sessionId: string;
+        readonly scope: ShareScopeV1;
+        readonly expiresAt?: number;
+    }): ShareContractV1;
+    resolve(input: {
+        readonly shareId: string;
+        readonly request: ShareResolveRequestV1;
+        readonly now?: number;
+    }): ShareResolveResultV1;
+    revoke(shareId: string, input: {
+        readonly reason: string;
+    }): ShareContractV1;
+    readonly transport: ShareTransportV1;
+}
+export declare function createSessionShare(options: {
+    /** Provider for the session's message transcript (JSON-safe). */
+    readonly readMessages: (sessionId: string) => JsonValue;
+    /** Provider for the session's diagnostics (JSON-safe). */
+    readonly readDiagnostics: (sessionId: string) => JsonValue;
+    /** Provider for artifact bytes (base64); wired to the 2.6a store by the caller. */
+    readonly readArtifact: (input: {
+        readonly sessionId: string;
+        readonly artifactId: string;
+    }) => ShareArtifactInputV1;
+    readonly transport: ShareTransportV1;
+    readonly now?: () => number;
+}): SessionShareManagerV1;
+//# sourceMappingURL=session-share.d.ts.map

package/dist/share/session-share.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-share.d.ts","sourceRoot":"","sources":["../../src/share/session-share.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * session-share contract (2.6c) — an explicit, revocable share contract with\n * a permission context, scope whitelist, and artifact references.\n *\n * A share contract is created for one session with a read-only permission\n * context and an explicit scope (messages on/off, artifact whitelist).\n * Resolution fails structurally for revoked, expired, out-of-scope, or\n * unknown requests — nothing is implicitly included. Revocation is the\n * cancellation path and is terminal. Transports are injected explicitly by\n * the caller (the kernel ships none); HTML/viewer integration is 2.6d.\n */\nimport type { JsonValue } from \"@agent-forge/ai\";\n\nexport interface ShareScopeV1 {\n\treadonly messages: boolean;\n\t/** Exact artifact references shareable under this contract. */\n\treadonly artifacts: readonly string[];\n\treadonly diagnostics: boolean;\n}\n\nexport interface ShareContractV1 {\n\treadonly shareId: string;\n\treadonly sessionId: string;\n\treadonly permission: \"read_only\";\n\treadonly scope: ShareScopeV1;\n\treadonly createdAt: number;\n\treadonly expiresAt?: number;\n}\n\nexport interface ShareArtifactInputV1 {\n\treadonly artifactId: string;\n\treadonly mediaType: string;\n\treadonly bytesBase64: string;\n}\n\nexport type ShareResolveRequestV1 =\n\t| { readonly kind: \"messages\" }\n\t| { readonly kind: \"diagnostics\" }\n\t| { readonly kind: \"artifact\"; readonly artifactId: string };\n\nexport type ShareResolveResultV1 =\n\t| { readonly status: \"resolved\"; readonly kind: \"messages\"; readonly content: JsonValue }\n\t| { readonly status: \"resolved\"; readonly kind: \"diagnostics\"; readonly content: JsonValue }\n\t| { readonly status: \"resolved\"; readonly kind: \"artifact\"; readonly artifact: ShareArtifactInputV1 }\n\t| { readonly status: \"denied\"; readonly reason: string }\n\t| { readonly status: \"not_found\"; readonly shareId: string };\n\nexport type ShareTransportPayloadV1 = JsonValue | ShareResolveResultV1;\n\nexport interface ShareTransportV1 {\n\treadonly id: string;\n\tsend(input: { readonly contract: ShareContractV1; readonly payload: ShareTransportPayloadV1 }): {\n\t\treadonly accepted: boolean;\n\t};\n}\n\nexport interface SessionShareManagerV1 {\n\tcreateShare(input: {\n\t\treadonly sessionId: string;\n\t\treadonly scope: ShareScopeV1;\n\t\treadonly expiresAt?: number;\n\t}): ShareContractV1;\n\tresolve(input: {\n\t\treadonly shareId: string;\n\t\treadonly request: ShareResolveRequestV1;\n\t\treadonly now?: number;\n\t}): ShareResolveResultV1;\n\trevoke(shareId: string, input: { readonly reason: string }): ShareContractV1;\n\treadonly transport: ShareTransportV1;\n}\n\nexport function createSessionShare(options: {\n\t/** Provider for the session's message transcript (JSON-safe). */\n\treadonly readMessages: (sessionId: string) => JsonValue;\n\t/** Provider for the session's diagnostics (JSON-safe). */\n\treadonly readDiagnostics: (sessionId: string) => JsonValue;\n\t/** Provider for artifact bytes (base64); wired to the 2.6a store by the caller. */\n\treadonly readArtifact: (input: { readonly sessionId: string; readonly artifactId: string }) => ShareArtifactInputV1;\n\treadonly transport: ShareTransportV1;\n\treadonly now?: () => number;\n}): SessionShareManagerV1 {\n\tconst now = options.now ?? (() => Date.now());\n\tconst contracts = new Map<string, { contract: ShareContractV1; revokedReason?: string }>();\n\tlet shareSequence = 0;\n\n\tconst shareIdOf = (sessionId: string): string => {\n\t\tshareSequence += 1;\n\t\tlet hash = 0x811c9dc5;\n\t\tconst value = `${sessionId}#${shareSequence}`;\n\t\tfor (let index = 0; index < value.length; index += 1) {\n\t\t\thash ^= value.charCodeAt(index);\n\t\t\thash = Math.imul(hash, 0x01000193);\n\t\t}\n\t\treturn `share-${(hash >>> 0).toString(36)}`;\n\t};\n\n\treturn {\n\t\ttransport: options.transport,\n\t\tcreateShare(input) {\n\t\t\tconst contract: ShareContractV1 = {\n\t\t\t\tshareId: shareIdOf(input.sessionId),\n\t\t\t\tsessionId: input.sessionId,\n\t\t\t\tpermission: \"read_only\",\n\t\t\t\tscope: input.scope,\n\t\t\t\tcreatedAt: now(),\n\t\t\t\t...(input.expiresAt === undefined ? {} : { expiresAt: input.expiresAt }),\n\t\t\t};\n\t\t\tcontracts.set(contract.shareId, { contract });\n\t\t\treturn contract;\n\t\t},\n\t\tresolve({ shareId, request, now: at }) {\n\t\t\tconst record = contracts.get(shareId);\n\t\t\tif (!record) return { status: \"not_found\", shareId };\n\t\t\tconst currentTime = at ?? now();\n\t\t\tif (record.revokedReason !== undefined) {\n\t\t\t\treturn { status: \"denied\", reason: `Share ${shareId} is revoked: ${record.revokedReason}` };\n\t\t\t}\n\t\t\tif (record.contract.expiresAt !== undefined && currentTime > record.contract.expiresAt) {\n\t\t\t\treturn { status: \"denied\", reason: `Share ${shareId} expired at ${record.contract.expiresAt}` };\n\t\t\t}\n\t\t\tconst { scope } = record.contract;\n\t\t\tswitch (request.kind) {\n\t\t\t\tcase \"messages\":\n\t\t\t\t\tif (!scope.messages) {\n\t\t\t\t\t\treturn { status: \"denied\", reason: \"Messages are outside the share scope\" };\n\t\t\t\t\t}\n\t\t\t\t\treturn {\n\t\t\t\t\t\tstatus: \"resolved\",\n\t\t\t\t\t\tkind: \"messages\",\n\t\t\t\t\t\tcontent: options.readMessages(record.contract.sessionId),\n\t\t\t\t\t};\n\t\t\t\tcase \"diagnostics\":\n\t\t\t\t\tif (!scope.diagnostics) {\n\t\t\t\t\t\treturn { status: \"denied\", reason: \"Diagnostics are outside the share scope\" };\n\t\t\t\t\t}\n\t\t\t\t\treturn {\n\t\t\t\t\t\tstatus: \"resolved\",\n\t\t\t\t\t\tkind: \"diagnostics\",\n\t\t\t\t\t\tcontent: options.readDiagnostics(record.contract.sessionId),\n\t\t\t\t\t};\n\t\t\t\tcase \"artifact\":\n\t\t\t\t\tif (!scope.artifacts.includes(request.artifactId)) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tstatus: \"denied\",\n\t\t\t\t\t\t\treason: `Artifact ${request.artifactId} is not in the share whitelist`,\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\treturn {\n\t\t\t\t\t\tstatus: \"resolved\",\n\t\t\t\t\t\tkind: \"artifact\",\n\t\t\t\t\t\tartifact: options.readArtifact({\n\t\t\t\t\t\t\tsessionId: record.contract.sessionId,\n\t\t\t\t\t\t\tartifactId: request.artifactId,\n\t\t\t\t\t\t}),\n\t\t\t\t\t};\n\t\t\t}\n\t\t},\n\t\trevoke(shareId, input) {\n\t\t\tconst record = contracts.get(shareId);\n\t\t\tif (!record) throw new Error(`Share not found: ${shareId}`);\n\t\t\tif (record.revokedReason !== undefined) {\n\t\t\t\tthrow new Error(`Share ${shareId} has already been revoked`);\n\t\t\t}\n\t\t\trecord.revokedReason = input.reason;\n\t\t\treturn record.contract;\n\t\t},\n\t};\n}\n"]}

package/dist/share/session-share.js

@@ -0,0 +1,89 @@
+export function createSessionShare(options) {
+    const now = options.now ?? (() => Date.now());
+    const contracts = new Map();
+    let shareSequence = 0;
+    const shareIdOf = (sessionId) => {
+        shareSequence += 1;
+        let hash = 0x811c9dc5;
+        const value = `${sessionId}#${shareSequence}`;
+        for (let index = 0; index < value.length; index += 1) {
+            hash ^= value.charCodeAt(index);
+            hash = Math.imul(hash, 0x01000193);
+        }
+        return `share-${(hash >>> 0).toString(36)}`;
+    };
+    return {
+        transport: options.transport,
+        createShare(input) {
+            const contract = {
+                shareId: shareIdOf(input.sessionId),
+                sessionId: input.sessionId,
+                permission: "read_only",
+                scope: input.scope,
+                createdAt: now(),
+                ...(input.expiresAt === undefined ? {} : { expiresAt: input.expiresAt }),
+            };
+            contracts.set(contract.shareId, { contract });
+            return contract;
+        },
+        resolve({ shareId, request, now: at }) {
+            const record = contracts.get(shareId);
+            if (!record)
+                return { status: "not_found", shareId };
+            const currentTime = at ?? now();
+            if (record.revokedReason !== undefined) {
+                return { status: "denied", reason: `Share ${shareId} is revoked: ${record.revokedReason}` };
+            }
+            if (record.contract.expiresAt !== undefined && currentTime > record.contract.expiresAt) {
+                return { status: "denied", reason: `Share ${shareId} expired at ${record.contract.expiresAt}` };
+            }
+            const { scope } = record.contract;
+            switch (request.kind) {
+                case "messages":
+                    if (!scope.messages) {
+                        return { status: "denied", reason: "Messages are outside the share scope" };
+                    }
+                    return {
+                        status: "resolved",
+                        kind: "messages",
+                        content: options.readMessages(record.contract.sessionId),
+                    };
+                case "diagnostics":
+                    if (!scope.diagnostics) {
+                        return { status: "denied", reason: "Diagnostics are outside the share scope" };
+                    }
+                    return {
+                        status: "resolved",
+                        kind: "diagnostics",
+                        content: options.readDiagnostics(record.contract.sessionId),
+                    };
+                case "artifact":
+                    if (!scope.artifacts.includes(request.artifactId)) {
+                        return {
+                            status: "denied",
+                            reason: `Artifact ${request.artifactId} is not in the share whitelist`,
+                        };
+                    }
+                    return {
+                        status: "resolved",
+                        kind: "artifact",
+                        artifact: options.readArtifact({
+                            sessionId: record.contract.sessionId,
+                            artifactId: request.artifactId,
+                        }),
+                    };
+            }
+        },
+        revoke(shareId, input) {
+            const record = contracts.get(shareId);
+            if (!record)
+                throw new Error(`Share not found: ${shareId}`);
+            if (record.revokedReason !== undefined) {
+                throw new Error(`Share ${shareId} has already been revoked`);
+            }
+            record.revokedReason = input.reason;
+            return record.contract;
+        },
+    };
+}
+//# sourceMappingURL=session-share.js.map

package/dist/share/session-share.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-share.js","sourceRoot":"","sources":["../../src/share/session-share.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * session-share contract (2.6c) — an explicit, revocable share contract with\n * a permission context, scope whitelist, and artifact references.\n *\n * A share contract is created for one session with a read-only permission\n * context and an explicit scope (messages on/off, artifact whitelist).\n * Resolution fails structurally for revoked, expired, out-of-scope, or\n * unknown requests — nothing is implicitly included. Revocation is the\n * cancellation path and is terminal. Transports are injected explicitly by\n * the caller (the kernel ships none); HTML/viewer integration is 2.6d.\n */\nimport type { JsonValue } from \"@agent-forge/ai\";\n\nexport interface ShareScopeV1 {\n\treadonly messages: boolean;\n\t/** Exact artifact references shareable under this contract. */\n\treadonly artifacts: readonly string[];\n\treadonly diagnostics: boolean;\n}\n\nexport interface ShareContractV1 {\n\treadonly shareId: string;\n\treadonly sessionId: string;\n\treadonly permission: \"read_only\";\n\treadonly scope: ShareScopeV1;\n\treadonly createdAt: number;\n\treadonly expiresAt?: number;\n}\n\nexport interface ShareArtifactInputV1 {\n\treadonly artifactId: string;\n\treadonly mediaType: string;\n\treadonly bytesBase64: string;\n}\n\nexport type ShareResolveRequestV1 =\n\t| { readonly kind: \"messages\" }\n\t| { readonly kind: \"diagnostics\" }\n\t| { readonly kind: \"artifact\"; readonly artifactId: string };\n\nexport type ShareResolveResultV1 =\n\t| { readonly status: \"resolved\"; readonly kind: \"messages\"; readonly content: JsonValue }\n\t| { readonly status: \"resolved\"; readonly kind: \"diagnostics\"; readonly content: JsonValue }\n\t| { readonly status: \"resolved\"; readonly kind: \"artifact\"; readonly artifact: ShareArtifactInputV1 }\n\t| { readonly status: \"denied\"; readonly reason: string }\n\t| { readonly status: \"not_found\"; readonly shareId: string };\n\nexport type ShareTransportPayloadV1 = JsonValue | ShareResolveResultV1;\n\nexport interface ShareTransportV1 {\n\treadonly id: string;\n\tsend(input: { readonly contract: ShareContractV1; readonly payload: ShareTransportPayloadV1 }): {\n\t\treadonly accepted: boolean;\n\t};\n}\n\nexport interface SessionShareManagerV1 {\n\tcreateShare(input: {\n\t\treadonly sessionId: string;\n\t\treadonly scope: ShareScopeV1;\n\t\treadonly expiresAt?: number;\n\t}): ShareContractV1;\n\tresolve(input: {\n\t\treadonly shareId: string;\n\t\treadonly request: ShareResolveRequestV1;\n\t\treadonly now?: number;\n\t}): ShareResolveResultV1;\n\trevoke(shareId: string, input: { readonly reason: string }): ShareContractV1;\n\treadonly transport: ShareTransportV1;\n}\n\nexport function createSessionShare(options: {\n\t/** Provider for the session's message transcript (JSON-safe). */\n\treadonly readMessages: (sessionId: string) => JsonValue;\n\t/** Provider for the session's diagnostics (JSON-safe). */\n\treadonly readDiagnostics: (sessionId: string) => JsonValue;\n\t/** Provider for artifact bytes (base64); wired to the 2.6a store by the caller. */\n\treadonly readArtifact: (input: { readonly sessionId: string; readonly artifactId: string }) => ShareArtifactInputV1;\n\treadonly transport: ShareTransportV1;\n\treadonly now?: () => number;\n}): SessionShareManagerV1 {\n\tconst now = options.now ?? (() => Date.now());\n\tconst contracts = new Map<string, { contract: ShareContractV1; revokedReason?: string }>();\n\tlet shareSequence = 0;\n\n\tconst shareIdOf = (sessionId: string): string => {\n\t\tshareSequence += 1;\n\t\tlet hash = 0x811c9dc5;\n\t\tconst value = `${sessionId}#${shareSequence}`;\n\t\tfor (let index = 0; index < value.length; index += 1) {\n\t\t\thash ^= value.charCodeAt(index);\n\t\t\thash = Math.imul(hash, 0x01000193);\n\t\t}\n\t\treturn `share-${(hash >>> 0).toString(36)}`;\n\t};\n\n\treturn {\n\t\ttransport: options.transport,\n\t\tcreateShare(input) {\n\t\t\tconst contract: ShareContractV1 = {\n\t\t\t\tshareId: shareIdOf(input.sessionId),\n\t\t\t\tsessionId: input.sessionId,\n\t\t\t\tpermission: \"read_only\",\n\t\t\t\tscope: input.scope,\n\t\t\t\tcreatedAt: now(),\n\t\t\t\t...(input.expiresAt === undefined ? {} : { expiresAt: input.expiresAt }),\n\t\t\t};\n\t\t\tcontracts.set(contract.shareId, { contract });\n\t\t\treturn contract;\n\t\t},\n\t\tresolve({ shareId, request, now: at }) {\n\t\t\tconst record = contracts.get(shareId);\n\t\t\tif (!record) return { status: \"not_found\", shareId };\n\t\t\tconst currentTime = at ?? now();\n\t\t\tif (record.revokedReason !== undefined) {\n\t\t\t\treturn { status: \"denied\", reason: `Share ${shareId} is revoked: ${record.revokedReason}` };\n\t\t\t}\n\t\t\tif (record.contract.expiresAt !== undefined && currentTime > record.contract.expiresAt) {\n\t\t\t\treturn { status: \"denied\", reason: `Share ${shareId} expired at ${record.contract.expiresAt}` };\n\t\t\t}\n\t\t\tconst { scope } = record.contract;\n\t\t\tswitch (request.kind) {\n\t\t\t\tcase \"messages\":\n\t\t\t\t\tif (!scope.messages) {\n\t\t\t\t\t\treturn { status: \"denied\", reason: \"Messages are outside the share scope\" };\n\t\t\t\t\t}\n\t\t\t\t\treturn {\n\t\t\t\t\t\tstatus: \"resolved\",\n\t\t\t\t\t\tkind: \"messages\",\n\t\t\t\t\t\tcontent: options.readMessages(record.contract.sessionId),\n\t\t\t\t\t};\n\t\t\t\tcase \"diagnostics\":\n\t\t\t\t\tif (!scope.diagnostics) {\n\t\t\t\t\t\treturn { status: \"denied\", reason: \"Diagnostics are outside the share scope\" };\n\t\t\t\t\t}\n\t\t\t\t\treturn {\n\t\t\t\t\t\tstatus: \"resolved\",\n\t\t\t\t\t\tkind: \"diagnostics\",\n\t\t\t\t\t\tcontent: options.readDiagnostics(record.contract.sessionId),\n\t\t\t\t\t};\n\t\t\t\tcase \"artifact\":\n\t\t\t\t\tif (!scope.artifacts.includes(request.artifactId)) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tstatus: \"denied\",\n\t\t\t\t\t\t\treason: `Artifact ${request.artifactId} is not in the share whitelist`,\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\treturn {\n\t\t\t\t\t\tstatus: \"resolved\",\n\t\t\t\t\t\tkind: \"artifact\",\n\t\t\t\t\t\tartifact: options.readArtifact({\n\t\t\t\t\t\t\tsessionId: record.contract.sessionId,\n\t\t\t\t\t\t\tartifactId: request.artifactId,\n\t\t\t\t\t\t}),\n\t\t\t\t\t};\n\t\t\t}\n\t\t},\n\t\trevoke(shareId, input) {\n\t\t\tconst record = contracts.get(shareId);\n\t\t\tif (!record) throw new Error(`Share not found: ${shareId}`);\n\t\t\tif (record.revokedReason !== undefined) {\n\t\t\t\tthrow new Error(`Share ${shareId} has already been revoked`);\n\t\t\t}\n\t\t\trecord.revokedReason = input.reason;\n\t\t\treturn record.contract;\n\t\t},\n\t};\n}\n"]}

package/dist/share/share-viewer.d.ts

@@ -0,0 +1,43 @@
+/**
+ * session-share viewer integration (2.6d) — renders share resolution results
+ * into cross-host viewer documents with failure recovery.
+ *
+ * One deterministic render produces both an HTML view (for the interactive
+ * viewer, with all content HTML-escaped — injection can never cross the
+ * viewer boundary) and a JSON payload (for cross-host mocks and structured
+ * hosts). Denied/not-found resolutions render as explicit failure views
+ * carrying the denial reason: the viewer never crashes on a failed share
+ * and never renders an unexplained empty page. The core `/share` command
+ * path itself stays in the session layer.
+ */
+import type { JsonValue } from "@agent-forge/ai";
+import type { ShareContractV1, ShareResolveResultV1 } from "./session-share.ts";
+export interface ShareViewV1 {
+    readonly shareId: string;
+    readonly state: "resolved" | "failed";
+    readonly kind?: string;
+    readonly html: string;
+    readonly payload: JsonValue;
+}
+export interface ShareViewerV1 {
+    render(input: {
+        readonly contract: ShareContractV1;
+        readonly result: ShareResolveResultV1;
+    }): ShareViewV1;
+}
+/**
+ * Renders one already-shared transcript artifact (e.g. the session JSONL a
+ * `/share` target published) into the viewer document. This is the
+ * consumption side of 2.6d: callers hand over primitive shared-artifact
+ * facts and the synthesis of the render input stays inside the viewer
+ * module. The synthetic contract only drives the shareId into the rendered
+ * markup and payload; `createdAt` is never rendered, so callers pass no
+ * timestamp.
+ */
+export declare function renderSharedTranscriptView(input: {
+    readonly shareId: string;
+    readonly sessionId: string;
+    readonly transcriptLines: readonly string[];
+}): ShareViewV1;
+export declare function createShareViewer(): ShareViewerV1;
+//# sourceMappingURL=share-viewer.d.ts.map

package/dist/share/share-viewer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"share-viewer.d.ts","sourceRoot":"","sources":["../../src/share/share-viewer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAEhF,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,QAAQ,CAAC;IACtC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;CAC5B;AAED,MAAM,WAAW,aAAa;IAC7B,MAAM,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAA;KAAE,GAAG,WAAW,CAAC;CAC1G;AAoBD;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE;IACjD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C,GAAG,WAAW,CAed;AAED,wBAAgB,iBAAiB,IAAI,aAAa,CA6DjD","sourcesContent":["/**\n * session-share viewer integration (2.6d) — renders share resolution results\n * into cross-host viewer documents with failure recovery.\n *\n * One deterministic render produces both an HTML view (for the interactive\n * viewer, with all content HTML-escaped — injection can never cross the\n * viewer boundary) and a JSON payload (for cross-host mocks and structured\n * hosts). Denied/not-found resolutions render as explicit failure views\n * carrying the denial reason: the viewer never crashes on a failed share\n * and never renders an unexplained empty page. The core `/share` command\n * path itself stays in the session layer.\n */\nimport type { JsonValue } from \"@agent-forge/ai\";\nimport type { ShareContractV1, ShareResolveResultV1 } from \"./session-share.ts\";\n\nexport interface ShareViewV1 {\n\treadonly shareId: string;\n\treadonly state: \"resolved\" | \"failed\";\n\treadonly kind?: string;\n\treadonly html: string;\n\treadonly payload: JsonValue;\n}\n\nexport interface ShareViewerV1 {\n\trender(input: { readonly contract: ShareContractV1; readonly result: ShareResolveResultV1 }): ShareViewV1;\n}\n\nfunction escapeHtml(value: string): string {\n\treturn value\n\t\t.replaceAll(\"&\", \"&amp;\")\n\t\t.replaceAll(\"<\", \"&lt;\")\n\t\t.replaceAll(\">\", \"&gt;\")\n\t\t.replaceAll('\"', \"&quot;\")\n\t\t.replaceAll(\"'\", \"&#39;\");\n}\n\nfunction failureView(shareId: string, reason: string): string {\n\treturn [\n\t\t`<article class=\"share-share-failure\" data-share=\"${escapeHtml(shareId)}\">`,\n\t\t`<h1>Share unavailable</h1>`,\n\t\t`<p class=\"share-reason\">${escapeHtml(reason)}</p>`,\n\t\t`</article>`,\n\t].join(\"\\n\");\n}\n\n/**\n * Renders one already-shared transcript artifact (e.g. the session JSONL a\n * `/share` target published) into the viewer document. This is the\n * consumption side of 2.6d: callers hand over primitive shared-artifact\n * facts and the synthesis of the render input stays inside the viewer\n * module. The synthetic contract only drives the shareId into the rendered\n * markup and payload; `createdAt` is never rendered, so callers pass no\n * timestamp.\n */\nexport function renderSharedTranscriptView(input: {\n\treadonly shareId: string;\n\treadonly sessionId: string;\n\treadonly transcriptLines: readonly string[];\n}): ShareViewV1 {\n\treturn createShareViewer().render({\n\t\tcontract: {\n\t\t\tshareId: input.shareId,\n\t\t\tsessionId: input.sessionId,\n\t\t\tpermission: \"read_only\",\n\t\t\tscope: { messages: true, artifacts: [], diagnostics: true },\n\t\t\tcreatedAt: 0,\n\t\t},\n\t\tresult: {\n\t\t\tstatus: \"resolved\",\n\t\t\tkind: \"messages\",\n\t\t\tcontent: { sessionId: input.sessionId, turns: [...input.transcriptLines] },\n\t\t},\n\t});\n}\n\nexport function createShareViewer(): ShareViewerV1 {\n\treturn {\n\t\trender({ contract, result }) {\n\t\t\tif (result.status !== \"resolved\") {\n\t\t\t\tconst reason = result.status === \"denied\" ? result.reason : `Unknown share: ${result.shareId}`;\n\t\t\t\treturn {\n\t\t\t\t\tshareId: contract.shareId,\n\t\t\t\t\tstate: \"failed\",\n\t\t\t\t\thtml: failureView(contract.shareId, reason),\n\t\t\t\t\tpayload: { shareId: contract.shareId, state: \"failed\", reason },\n\t\t\t\t};\n\t\t\t}\n\n\t\t\tlet bodyHtml: string;\n\t\t\tlet payload: JsonValue;\n\t\t\tswitch (result.kind) {\n\t\t\t\tcase \"messages\": {\n\t\t\t\t\tconst content = result.content as { readonly turns?: readonly string[] };\n\t\t\t\t\tconst turns = Array.isArray(content.turns) ? content.turns : [];\n\t\t\t\t\tbodyHtml = [\n\t\t\t\t\t\t`<h1>Shared messages</h1>`,\n\t\t\t\t\t\t`<ol class=\"share-turns\">`,\n\t\t\t\t\t\t...turns.map((turn) => `<li>${escapeHtml(String(turn))}</li>`),\n\t\t\t\t\t\t`</ol>`,\n\t\t\t\t\t].join(\"\\n\");\n\t\t\t\t\tpayload = { shareId: contract.shareId, state: \"resolved\", kind: \"messages\", turns: [...turns] };\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t\tcase \"diagnostics\": {\n\t\t\t\t\tbodyHtml = `<h1>Shared diagnostics</h1><pre class=\"share-diagnostics\">${escapeHtml(JSON.stringify(result.content))}</pre>`;\n\t\t\t\t\tpayload = { shareId: contract.shareId, state: \"resolved\", kind: \"diagnostics\", content: result.content };\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t\tcase \"artifact\": {\n\t\t\t\t\tbodyHtml = [\n\t\t\t\t\t\t`<h1>Shared artifact</h1>`,\n\t\t\t\t\t\t`<p class=\"share-artifact\" data-artifact=\"${escapeHtml(result.artifact.artifactId)}\">`,\n\t\t\t\t\t\t`${escapeHtml(result.artifact.mediaType)} · ${escapeHtml(result.artifact.bytesBase64)}`,\n\t\t\t\t\t\t`</p>`,\n\t\t\t\t\t].join(\"\\n\");\n\t\t\t\t\tpayload = {\n\t\t\t\t\t\tshareId: contract.shareId,\n\t\t\t\t\t\tstate: \"resolved\",\n\t\t\t\t\t\tkind: \"artifact\",\n\t\t\t\t\t\tartifact: { ...result.artifact },\n\t\t\t\t\t};\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t\tdefault:\n\t\t\t\t\tbodyHtml = failureView(contract.shareId, \"Unsupported resolution kind\");\n\t\t\t\t\tpayload = { shareId: contract.shareId, state: \"failed\", reason: \"unsupported kind\" };\n\t\t\t}\n\t\t\treturn {\n\t\t\t\tshareId: contract.shareId,\n\t\t\t\tstate: \"resolved\",\n\t\t\t\tkind: result.kind,\n\t\t\t\thtml: `<article class=\"share-view\" data-share=\"${escapeHtml(contract.shareId)}\">\\n${bodyHtml}\\n</article>`,\n\t\t\t\tpayload,\n\t\t\t};\n\t\t},\n\t};\n}\n"]}

package/dist/share/share-viewer.js

@@ -0,0 +1,103 @@
+function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#39;");
+}
+function failureView(shareId, reason) {
+    return [
+        `<article class="share-share-failure" data-share="${escapeHtml(shareId)}">`,
+        `<h1>Share unavailable</h1>`,
+        `<p class="share-reason">${escapeHtml(reason)}</p>`,
+        `</article>`,
+    ].join("\n");
+}
+/**
+ * Renders one already-shared transcript artifact (e.g. the session JSONL a
+ * `/share` target published) into the viewer document. This is the
+ * consumption side of 2.6d: callers hand over primitive shared-artifact
+ * facts and the synthesis of the render input stays inside the viewer
+ * module. The synthetic contract only drives the shareId into the rendered
+ * markup and payload; `createdAt` is never rendered, so callers pass no
+ * timestamp.
+ */
+export function renderSharedTranscriptView(input) {
+    return createShareViewer().render({
+        contract: {
+            shareId: input.shareId,
+            sessionId: input.sessionId,
+            permission: "read_only",
+            scope: { messages: true, artifacts: [], diagnostics: true },
+            createdAt: 0,
+        },
+        result: {
+            status: "resolved",
+            kind: "messages",
+            content: { sessionId: input.sessionId, turns: [...input.transcriptLines] },
+        },
+    });
+}
+export function createShareViewer() {
+    return {
+        render({ contract, result }) {
+            if (result.status !== "resolved") {
+                const reason = result.status === "denied" ? result.reason : `Unknown share: ${result.shareId}`;
+                return {
+                    shareId: contract.shareId,
+                    state: "failed",
+                    html: failureView(contract.shareId, reason),
+                    payload: { shareId: contract.shareId, state: "failed", reason },
+                };
+            }
+            let bodyHtml;
+            let payload;
+            switch (result.kind) {
+                case "messages": {
+                    const content = result.content;
+                    const turns = Array.isArray(content.turns) ? content.turns : [];
+                    bodyHtml = [
+                        `<h1>Shared messages</h1>`,
+                        `<ol class="share-turns">`,
+                        ...turns.map((turn) => `<li>${escapeHtml(String(turn))}</li>`),
+                        `</ol>`,
+                    ].join("\n");
+                    payload = { shareId: contract.shareId, state: "resolved", kind: "messages", turns: [...turns] };
+                    break;
+                }
+                case "diagnostics": {
+                    bodyHtml = `<h1>Shared diagnostics</h1><pre class="share-diagnostics">${escapeHtml(JSON.stringify(result.content))}</pre>`;
+                    payload = { shareId: contract.shareId, state: "resolved", kind: "diagnostics", content: result.content };
+                    break;
+                }
+                case "artifact": {
+                    bodyHtml = [
+                        `<h1>Shared artifact</h1>`,
+                        `<p class="share-artifact" data-artifact="${escapeHtml(result.artifact.artifactId)}">`,
+                        `${escapeHtml(result.artifact.mediaType)} · ${escapeHtml(result.artifact.bytesBase64)}`,
+                        `</p>`,
+                    ].join("\n");
+                    payload = {
+                        shareId: contract.shareId,
+                        state: "resolved",
+                        kind: "artifact",
+                        artifact: { ...result.artifact },
+                    };
+                    break;
+                }
+                default:
+                    bodyHtml = failureView(contract.shareId, "Unsupported resolution kind");
+                    payload = { shareId: contract.shareId, state: "failed", reason: "unsupported kind" };
+            }
+            return {
+                shareId: contract.shareId,
+                state: "resolved",
+                kind: result.kind,
+                html: `<article class="share-view" data-share="${escapeHtml(contract.shareId)}">\n${bodyHtml}\n</article>`,
+                payload,
+            };
+        },
+    };
+}
+//# sourceMappingURL=share-viewer.js.map

package/dist/share/share-viewer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"share-viewer.js","sourceRoot":"","sources":["../../src/share/share-viewer.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * session-share viewer integration (2.6d) — renders share resolution results\n * into cross-host viewer documents with failure recovery.\n *\n * One deterministic render produces both an HTML view (for the interactive\n * viewer, with all content HTML-escaped — injection can never cross the\n * viewer boundary) and a JSON payload (for cross-host mocks and structured\n * hosts). Denied/not-found resolutions render as explicit failure views\n * carrying the denial reason: the viewer never crashes on a failed share\n * and never renders an unexplained empty page. The core `/share` command\n * path itself stays in the session layer.\n */\nimport type { JsonValue } from \"@agent-forge/ai\";\nimport type { ShareContractV1, ShareResolveResultV1 } from \"./session-share.ts\";\n\nexport interface ShareViewV1 {\n\treadonly shareId: string;\n\treadonly state: \"resolved\" | \"failed\";\n\treadonly kind?: string;\n\treadonly html: string;\n\treadonly payload: JsonValue;\n}\n\nexport interface ShareViewerV1 {\n\trender(input: { readonly contract: ShareContractV1; readonly result: ShareResolveResultV1 }): ShareViewV1;\n}\n\nfunction escapeHtml(value: string): string {\n\treturn value\n\t\t.replaceAll(\"&\", \"&amp;\")\n\t\t.replaceAll(\"<\", \"&lt;\")\n\t\t.replaceAll(\">\", \"&gt;\")\n\t\t.replaceAll('\"', \"&quot;\")\n\t\t.replaceAll(\"'\", \"&#39;\");\n}\n\nfunction failureView(shareId: string, reason: string): string {\n\treturn [\n\t\t`<article class=\"share-share-failure\" data-share=\"${escapeHtml(shareId)}\">`,\n\t\t`<h1>Share unavailable</h1>`,\n\t\t`<p class=\"share-reason\">${escapeHtml(reason)}</p>`,\n\t\t`</article>`,\n\t].join(\"\\n\");\n}\n\n/**\n * Renders one already-shared transcript artifact (e.g. the session JSONL a\n * `/share` target published) into the viewer document. This is the\n * consumption side of 2.6d: callers hand over primitive shared-artifact\n * facts and the synthesis of the render input stays inside the viewer\n * module. The synthetic contract only drives the shareId into the rendered\n * markup and payload; `createdAt` is never rendered, so callers pass no\n * timestamp.\n */\nexport function renderSharedTranscriptView(input: {\n\treadonly shareId: string;\n\treadonly sessionId: string;\n\treadonly transcriptLines: readonly string[];\n}): ShareViewV1 {\n\treturn createShareViewer().render({\n\t\tcontract: {\n\t\t\tshareId: input.shareId,\n\t\t\tsessionId: input.sessionId,\n\t\t\tpermission: \"read_only\",\n\t\t\tscope: { messages: true, artifacts: [], diagnostics: true },\n\t\t\tcreatedAt: 0,\n\t\t},\n\t\tresult: {\n\t\t\tstatus: \"resolved\",\n\t\t\tkind: \"messages\",\n\t\t\tcontent: { sessionId: input.sessionId, turns: [...input.transcriptLines] },\n\t\t},\n\t});\n}\n\nexport function createShareViewer(): ShareViewerV1 {\n\treturn {\n\t\trender({ contract, result }) {\n\t\t\tif (result.status !== \"resolved\") {\n\t\t\t\tconst reason = result.status === \"denied\" ? result.reason : `Unknown share: ${result.shareId}`;\n\t\t\t\treturn {\n\t\t\t\t\tshareId: contract.shareId,\n\t\t\t\t\tstate: \"failed\",\n\t\t\t\t\thtml: failureView(contract.shareId, reason),\n\t\t\t\t\tpayload: { shareId: contract.shareId, state: \"failed\", reason },\n\t\t\t\t};\n\t\t\t}\n\n\t\t\tlet bodyHtml: string;\n\t\t\tlet payload: JsonValue;\n\t\t\tswitch (result.kind) {\n\t\t\t\tcase \"messages\": {\n\t\t\t\t\tconst content = result.content as { readonly turns?: readonly string[] };\n\t\t\t\t\tconst turns = Array.isArray(content.turns) ? content.turns : [];\n\t\t\t\t\tbodyHtml = [\n\t\t\t\t\t\t`<h1>Shared messages</h1>`,\n\t\t\t\t\t\t`<ol class=\"share-turns\">`,\n\t\t\t\t\t\t...turns.map((turn) => `<li>${escapeHtml(String(turn))}</li>`),\n\t\t\t\t\t\t`</ol>`,\n\t\t\t\t\t].join(\"\\n\");\n\t\t\t\t\tpayload = { shareId: contract.shareId, state: \"resolved\", kind: \"messages\", turns: [...turns] };\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t\tcase \"diagnostics\": {\n\t\t\t\t\tbodyHtml = `<h1>Shared diagnostics</h1><pre class=\"share-diagnostics\">${escapeHtml(JSON.stringify(result.content))}</pre>`;\n\t\t\t\t\tpayload = { shareId: contract.shareId, state: \"resolved\", kind: \"diagnostics\", content: result.content };\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t\tcase \"artifact\": {\n\t\t\t\t\tbodyHtml = [\n\t\t\t\t\t\t`<h1>Shared artifact</h1>`,\n\t\t\t\t\t\t`<p class=\"share-artifact\" data-artifact=\"${escapeHtml(result.artifact.artifactId)}\">`,\n\t\t\t\t\t\t`${escapeHtml(result.artifact.mediaType)} · ${escapeHtml(result.artifact.bytesBase64)}`,\n\t\t\t\t\t\t`</p>`,\n\t\t\t\t\t].join(\"\\n\");\n\t\t\t\t\tpayload = {\n\t\t\t\t\t\tshareId: contract.shareId,\n\t\t\t\t\t\tstate: \"resolved\",\n\t\t\t\t\t\tkind: \"artifact\",\n\t\t\t\t\t\tartifact: { ...result.artifact },\n\t\t\t\t\t};\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t\tdefault:\n\t\t\t\t\tbodyHtml = failureView(contract.shareId, \"Unsupported resolution kind\");\n\t\t\t\t\tpayload = { shareId: contract.shareId, state: \"failed\", reason: \"unsupported kind\" };\n\t\t\t}\n\t\t\treturn {\n\t\t\t\tshareId: contract.shareId,\n\t\t\t\tstate: \"resolved\",\n\t\t\t\tkind: result.kind,\n\t\t\t\thtml: `<article class=\"share-view\" data-share=\"${escapeHtml(contract.shareId)}\">\\n${bodyHtml}\\n</article>`,\n\t\t\t\tpayload,\n\t\t\t};\n\t\t},\n\t};\n}\n"]}

package/dist/testing/index.d.ts

@@ -0,0 +1,4 @@
+export { createPluginTestKit, type PluginTestKit, type PluginTestKitOptions, type PluginTestKitPlugin, type PluginTestKitTranscript, repeatPluginTestKit, } from "./plugin-testkit.ts";
+export { createRuntimeOnlyDeliveryQueue, MODEL_STREAM_BACKPRESSURE_OVERFLOW_CODE, RuntimeOnlyBackpressureOverflowError, type RuntimeOnlyDeliveryQueue, type RuntimeOnlyDeliveryQueueOptions, type RuntimeOnlyDeliveryQueueSnapshot, type RuntimeOnlyDeliveryQueueStatus, } from "./runtime-delivery-queue.ts";
+export { createSessionPluginTestKit, repeatSessionPluginTestKit, type SessionPluginTestKit, type SessionPluginTestKitInspector, type SessionPluginTestKitOptions, type SessionPluginTestKitPlugin, type SessionPluginTestKitTranscript, } from "./session-plugin-testkit.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACN,mBAAmB,EACnB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,mBAAmB,GACnB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACN,8BAA8B,EAC9B,uCAAuC,EACvC,oCAAoC,EACpC,KAAK,wBAAwB,EAC7B,KAAK,+BAA+B,EACpC,KAAK,gCAAgC,EACrC,KAAK,8BAA8B,GACnC,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACN,0BAA0B,EAC1B,0BAA0B,EAC1B,KAAK,oBAAoB,EACzB,KAAK,6BAA6B,EAClC,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,EAC/B,KAAK,8BAA8B,GACnC,MAAM,6BAA6B,CAAC","sourcesContent":["// Memory testkit moved to the @agent-forge/plugin-memory package with the\n// capability itself (D-075 S4 fourth batch); consumers import it from there.\nexport {\n\tcreatePluginTestKit,\n\ttype PluginTestKit,\n\ttype PluginTestKitOptions,\n\ttype PluginTestKitPlugin,\n\ttype PluginTestKitTranscript,\n\trepeatPluginTestKit,\n} from \"./plugin-testkit.ts\";\nexport {\n\tcreateRuntimeOnlyDeliveryQueue,\n\tMODEL_STREAM_BACKPRESSURE_OVERFLOW_CODE,\n\tRuntimeOnlyBackpressureOverflowError,\n\ttype RuntimeOnlyDeliveryQueue,\n\ttype RuntimeOnlyDeliveryQueueOptions,\n\ttype RuntimeOnlyDeliveryQueueSnapshot,\n\ttype RuntimeOnlyDeliveryQueueStatus,\n} from \"./runtime-delivery-queue.ts\";\nexport {\n\tcreateSessionPluginTestKit,\n\trepeatSessionPluginTestKit,\n\ttype SessionPluginTestKit,\n\ttype SessionPluginTestKitInspector,\n\ttype SessionPluginTestKitOptions,\n\ttype SessionPluginTestKitPlugin,\n\ttype SessionPluginTestKitTranscript,\n} from \"./session-plugin-testkit.ts\";\n"]}

package/dist/testing/index.js

@@ -0,0 +1,6 @@
+// Memory testkit moved to the @agent-forge/plugin-memory package with the
+// capability itself (D-075 S4 fourth batch); consumers import it from there.
+export { createPluginTestKit, repeatPluginTestKit, } from "./plugin-testkit.js";
+export { createRuntimeOnlyDeliveryQueue, MODEL_STREAM_BACKPRESSURE_OVERFLOW_CODE, RuntimeOnlyBackpressureOverflowError, } from "./runtime-delivery-queue.js";
+export { createSessionPluginTestKit, repeatSessionPluginTestKit, } from "./session-plugin-testkit.js";
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,6EAA6E;AAC7E,OAAO,EACN,mBAAmB,EAKnB,mBAAmB,GACnB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACN,8BAA8B,EAC9B,uCAAuC,EACvC,oCAAoC,GAKpC,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACN,0BAA0B,EAC1B,0BAA0B,GAM1B,MAAM,6BAA6B,CAAC","sourcesContent":["// Memory testkit moved to the @agent-forge/plugin-memory package with the\n// capability itself (D-075 S4 fourth batch); consumers import it from there.\nexport {\n\tcreatePluginTestKit,\n\ttype PluginTestKit,\n\ttype PluginTestKitOptions,\n\ttype PluginTestKitPlugin,\n\ttype PluginTestKitTranscript,\n\trepeatPluginTestKit,\n} from \"./plugin-testkit.ts\";\nexport {\n\tcreateRuntimeOnlyDeliveryQueue,\n\tMODEL_STREAM_BACKPRESSURE_OVERFLOW_CODE,\n\tRuntimeOnlyBackpressureOverflowError,\n\ttype RuntimeOnlyDeliveryQueue,\n\ttype RuntimeOnlyDeliveryQueueOptions,\n\ttype RuntimeOnlyDeliveryQueueSnapshot,\n\ttype RuntimeOnlyDeliveryQueueStatus,\n} from \"./runtime-delivery-queue.ts\";\nexport {\n\tcreateSessionPluginTestKit,\n\trepeatSessionPluginTestKit,\n\ttype SessionPluginTestKit,\n\ttype SessionPluginTestKitInspector,\n\ttype SessionPluginTestKitOptions,\n\ttype SessionPluginTestKitPlugin,\n\ttype SessionPluginTestKitTranscript,\n} from \"./session-plugin-testkit.ts\";\n"]}

package/dist/testing/mock-ai-server.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Mock AI server (3.1) — a deterministic, fail-closed mock model endpoint
+ * driven by scenario fixtures with fault injection.
+ *
+ * Fail-closed rules: a request that matches no fixture is an explicit
+ * `unmatched_request` error (never a guessed default response); a fixture
+ * whose scripted steps are exhausted answers `scenario_exhausted` (extra
+ * requests can never slip through); and generated IDs/timestamps come only
+ * from injected deterministic sources — the mock itself contains zero
+ * randomness. Fault injection (timeout, disconnect, server error, truncated
+ * stream) is scripted per step and surfaces as structured errors or marked
+ * responses, never as a plausible-looking success. Transport gateways are
+ * later slices (3.2-3.3); real models are always out of scope here.
+ */
+import type { JsonValue } from "@agent-forge/ai";
+export interface MockAiRequestV1 {
+    readonly model: string;
+    readonly messages: readonly JsonValue[];
+    readonly stream?: boolean;
+}
+export type MockAiPartV1 = {
+    readonly type: "text";
+    readonly text: string;
+} | {
+    readonly type: "tool_call";
+    readonly callId: string;
+    readonly toolName: string;
+    readonly arguments: JsonValue;
+} | {
+    readonly type: "finish";
+    readonly reason: string;
+};
+export type MockAiFaultV1 = "timeout" | "disconnect" | "server_error" | "truncated_stream";
+export interface MockAiStepV1 {
+    readonly response?: {
+        readonly parts: readonly MockAiPartV1[];
+    };
+    readonly fault?: MockAiFaultV1;
+}
+export interface MockAiFixtureV1 {
+    readonly scenarioId: string;
+    readonly match: {
+        readonly modelEquals?: string;
+        readonly minMessages?: number;
+        readonly streamEquals?: boolean;
+    };
+    readonly steps: readonly MockAiStepV1[];
+}
+export interface MockAiResponseV1 {
+    readonly scenarioId: string;
+    readonly stepIndex: number;
+    readonly id: string;
+    readonly at: number;
+    readonly parts: readonly MockAiPartV1[];
+    readonly truncated: boolean;
+    readonly serverError?: {
+        readonly status: 500;
+    };
+}
+export interface MockAiServerV1 {
+    handle(request: MockAiRequestV1): MockAiResponseV1;
+    /** Fails closed: unconsumed scripted steps are a test bug. */
+    verifyComplete(): void;
+    receivedRequests(): readonly {
+        readonly at: number;
+        readonly request: MockAiRequestV1;
+    }[];
+}
+export declare class MockAiError extends Error {
+    readonly code: "unmatched_request" | "scenario_exhausted" | "injected_timeout" | "injected_disconnect";
+    constructor(code: MockAiError["code"], message: string);
+}
+export declare function createMockAiServer(options: {
+    readonly fixtures: readonly MockAiFixtureV1[];
+    readonly now?: () => number;
+}): MockAiServerV1;
+//# sourceMappingURL=mock-ai-server.d.ts.map

package/dist/testing/mock-ai-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-ai-server.d.ts","sourceRoot":"","sources":["../../src/testing/mock-ai-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,SAAS,SAAS,EAAE,CAAC;IACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,MAAM,YAAY,GACrB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;CAAE,GACjH;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAExD,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,YAAY,GAAG,cAAc,GAAG,kBAAkB,CAAC;AAE3F,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE;QACnB,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;KAExC,CAAC;IACF,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE;QACf,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAC9B,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;KAChC,CAAC;IACF,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;CACxC;AAED,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IACxC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAA;KAAE,CAAC;CAChD;AAED,MAAM,WAAW,cAAc;IAC9B,MAAM,CAAC,OAAO,EAAE,eAAe,GAAG,gBAAgB,CAAC;IACnD,8DAA8D;IAC9D,cAAc,IAAI,IAAI,CAAC;IACvB,gBAAgB,IAAI,SAAS;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;KAAE,EAAE,CAAC;CAC1F;AAED,qBAAa,WAAY,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,GAAG,oBAAoB,GAAG,kBAAkB,GAAG,qBAAqB,CAAC;IAEvG,YAAY,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,EAIrD;CACD;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE;IAC3C,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;IAC9C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC5B,GAAG,cAAc,CA0EjB","sourcesContent":["/**\n * Mock AI server (3.1) — a deterministic, fail-closed mock model endpoint\n * driven by scenario fixtures with fault injection.\n *\n * Fail-closed rules: a request that matches no fixture is an explicit\n * `unmatched_request` error (never a guessed default response); a fixture\n * whose scripted steps are exhausted answers `scenario_exhausted` (extra\n * requests can never slip through); and generated IDs/timestamps come only\n * from injected deterministic sources — the mock itself contains zero\n * randomness. Fault injection (timeout, disconnect, server error, truncated\n * stream) is scripted per step and surfaces as structured errors or marked\n * responses, never as a plausible-looking success. Transport gateways are\n * later slices (3.2-3.3); real models are always out of scope here.\n */\nimport type { JsonValue } from \"@agent-forge/ai\";\n\nexport interface MockAiRequestV1 {\n\treadonly model: string;\n\treadonly messages: readonly JsonValue[];\n\treadonly stream?: boolean;\n}\n\nexport type MockAiPartV1 =\n\t| { readonly type: \"text\"; readonly text: string }\n\t| { readonly type: \"tool_call\"; readonly callId: string; readonly toolName: string; readonly arguments: JsonValue }\n\t| { readonly type: \"finish\"; readonly reason: string };\n\nexport type MockAiFaultV1 = \"timeout\" | \"disconnect\" | \"server_error\" | \"truncated_stream\";\n\nexport interface MockAiStepV1 {\n\treadonly response?: {\n\t\treadonly parts: readonly MockAiPartV1[];\n\t\t/** Stream truncation is also expressible by omitting the finish part. */\n\t};\n\treadonly fault?: MockAiFaultV1;\n}\n\nexport interface MockAiFixtureV1 {\n\treadonly scenarioId: string;\n\treadonly match: {\n\t\treadonly modelEquals?: string;\n\t\treadonly minMessages?: number;\n\t\treadonly streamEquals?: boolean;\n\t};\n\treadonly steps: readonly MockAiStepV1[];\n}\n\nexport interface MockAiResponseV1 {\n\treadonly scenarioId: string;\n\treadonly stepIndex: number;\n\treadonly id: string;\n\treadonly at: number;\n\treadonly parts: readonly MockAiPartV1[];\n\treadonly truncated: boolean;\n\treadonly serverError?: { readonly status: 500 };\n}\n\nexport interface MockAiServerV1 {\n\thandle(request: MockAiRequestV1): MockAiResponseV1;\n\t/** Fails closed: unconsumed scripted steps are a test bug. */\n\tverifyComplete(): void;\n\treceivedRequests(): readonly { readonly at: number; readonly request: MockAiRequestV1 }[];\n}\n\nexport class MockAiError extends Error {\n\treadonly code: \"unmatched_request\" | \"scenario_exhausted\" | \"injected_timeout\" | \"injected_disconnect\";\n\n\tconstructor(code: MockAiError[\"code\"], message: string) {\n\t\tsuper(message);\n\t\tthis.name = \"MockAiError\";\n\t\tthis.code = code;\n\t}\n}\n\nexport function createMockAiServer(options: {\n\treadonly fixtures: readonly MockAiFixtureV1[];\n\treadonly now?: () => number;\n}): MockAiServerV1 {\n\tconst now = options.now ?? (() => 0);\n\tconst consumed = new Map<string, number>();\n\tconst received: Array<{ at: number; request: MockAiRequestV1 }> = [];\n\tconst declaredScenarioIds = new Set(options.fixtures.map((fixture) => fixture.scenarioId));\n\n\tconst matches = (fixture: MockAiFixtureV1, request: MockAiRequestV1): boolean => {\n\t\tif (fixture.match.modelEquals !== undefined && request.model !== fixture.match.modelEquals) return false;\n\t\tif (fixture.match.minMessages !== undefined && request.messages.length < fixture.match.minMessages) return false;\n\t\tif (fixture.match.streamEquals !== undefined && (request.stream ?? false) !== fixture.match.streamEquals)\n\t\t\treturn false;\n\t\treturn true;\n\t};\n\n\treturn {\n\t\thandle(request) {\n\t\t\tconst at = now();\n\t\t\treceived.push({ at, request: { ...request, messages: [...request.messages] } });\n\t\t\tconst fixture = options.fixtures.find((candidate) => matches(candidate, request));\n\t\t\tif (!fixture) {\n\t\t\t\tthrow new MockAiError(\n\t\t\t\t\t\"unmatched_request\",\n\t\t\t\t\t`No fixture matches model=${request.model} messages=${request.messages.length} stream=${request.stream ?? false}; the mock is fail-closed`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst stepIndex = consumed.get(fixture.scenarioId) ?? 0;\n\t\t\tif (stepIndex >= fixture.steps.length) {\n\t\t\t\tthrow new MockAiError(\n\t\t\t\t\t\"scenario_exhausted\",\n\t\t\t\t\t`Scenario ${fixture.scenarioId} has no scripted step ${stepIndex + 1}; extra requests fail closed`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tconsumed.set(fixture.scenarioId, stepIndex + 1);\n\t\t\tconst step = fixture.steps[stepIndex]!;\n\t\t\tif (step.fault === \"timeout\") {\n\t\t\t\tthrow new MockAiError(\n\t\t\t\t\t\"injected_timeout\",\n\t\t\t\t\t`Scenario ${fixture.scenarioId} step ${stepIndex} injected a timeout`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tif (step.fault === \"disconnect\") {\n\t\t\t\tthrow new MockAiError(\n\t\t\t\t\t\"injected_disconnect\",\n\t\t\t\t\t`Scenario ${fixture.scenarioId} step ${stepIndex} injected a disconnect`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst parts = step.response?.parts ?? [];\n\t\t\tconst truncated = step.fault === \"truncated_stream\" || !parts.some((part) => part.type === \"finish\");\n\t\t\treturn {\n\t\t\t\tscenarioId: fixture.scenarioId,\n\t\t\t\tstepIndex,\n\t\t\t\tid: `mock-${fixture.scenarioId}-${stepIndex}`,\n\t\t\t\tat,\n\t\t\t\tparts: Object.freeze([...parts]),\n\t\t\t\ttruncated,\n\t\t\t\t...(step.fault === \"server_error\" ? { serverError: { status: 500 as const } } : {}),\n\t\t\t};\n\t\t},\n\t\tverifyComplete() {\n\t\t\tfor (const fixture of options.fixtures) {\n\t\t\t\tconst consumedCount = consumed.get(fixture.scenarioId) ?? 0;\n\t\t\t\tif (consumedCount !== fixture.steps.length) {\n\t\t\t\t\tthrow new MockAiError(\n\t\t\t\t\t\t\"scenario_exhausted\",\n\t\t\t\t\t\t`Scenario ${fixture.scenarioId} has ${fixture.steps.length - consumedCount} unconsumed scripted step(s)`,\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t}\n\t\t\tvoid declaredScenarioIds;\n\t\t},\n\t\treceivedRequests() {\n\t\t\treturn Object.freeze([...received]);\n\t\t},\n\t};\n}\n"]}

package/dist/testing/mock-ai-server.js

@@ -0,0 +1,69 @@
+export class MockAiError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "MockAiError";
+        this.code = code;
+    }
+}
+export function createMockAiServer(options) {
+    const now = options.now ?? (() => 0);
+    const consumed = new Map();
+    const received = [];
+    const declaredScenarioIds = new Set(options.fixtures.map((fixture) => fixture.scenarioId));
+    const matches = (fixture, request) => {
+        if (fixture.match.modelEquals !== undefined && request.model !== fixture.match.modelEquals)
+            return false;
+        if (fixture.match.minMessages !== undefined && request.messages.length < fixture.match.minMessages)
+            return false;
+        if (fixture.match.streamEquals !== undefined && (request.stream ?? false) !== fixture.match.streamEquals)
+            return false;
+        return true;
+    };
+    return {
+        handle(request) {
+            const at = now();
+            received.push({ at, request: { ...request, messages: [...request.messages] } });
+            const fixture = options.fixtures.find((candidate) => matches(candidate, request));
+            if (!fixture) {
+                throw new MockAiError("unmatched_request", `No fixture matches model=${request.model} messages=${request.messages.length} stream=${request.stream ?? false}; the mock is fail-closed`);
+            }
+            const stepIndex = consumed.get(fixture.scenarioId) ?? 0;
+            if (stepIndex >= fixture.steps.length) {
+                throw new MockAiError("scenario_exhausted", `Scenario ${fixture.scenarioId} has no scripted step ${stepIndex + 1}; extra requests fail closed`);
+            }
+            consumed.set(fixture.scenarioId, stepIndex + 1);
+            const step = fixture.steps[stepIndex];
+            if (step.fault === "timeout") {
+                throw new MockAiError("injected_timeout", `Scenario ${fixture.scenarioId} step ${stepIndex} injected a timeout`);
+            }
+            if (step.fault === "disconnect") {
+                throw new MockAiError("injected_disconnect", `Scenario ${fixture.scenarioId} step ${stepIndex} injected a disconnect`);
+            }
+            const parts = step.response?.parts ?? [];
+            const truncated = step.fault === "truncated_stream" || !parts.some((part) => part.type === "finish");
+            return {
+                scenarioId: fixture.scenarioId,
+                stepIndex,
+                id: `mock-${fixture.scenarioId}-${stepIndex}`,
+                at,
+                parts: Object.freeze([...parts]),
+                truncated,
+                ...(step.fault === "server_error" ? { serverError: { status: 500 } } : {}),
+            };
+        },
+        verifyComplete() {
+            for (const fixture of options.fixtures) {
+                const consumedCount = consumed.get(fixture.scenarioId) ?? 0;
+                if (consumedCount !== fixture.steps.length) {
+                    throw new MockAiError("scenario_exhausted", `Scenario ${fixture.scenarioId} has ${fixture.steps.length - consumedCount} unconsumed scripted step(s)`);
+                }
+            }
+            void declaredScenarioIds;
+        },
+        receivedRequests() {
+            return Object.freeze([...received]);
+        },
+    };
+}
+//# sourceMappingURL=mock-ai-server.js.map

package/dist/testing/mock-ai-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-ai-server.js","sourceRoot":"","sources":["../../src/testing/mock-ai-server.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Mock AI server (3.1) — a deterministic, fail-closed mock model endpoint\n * driven by scenario fixtures with fault injection.\n *\n * Fail-closed rules: a request that matches no fixture is an explicit\n * `unmatched_request` error (never a guessed default response); a fixture\n * whose scripted steps are exhausted answers `scenario_exhausted` (extra\n * requests can never slip through); and generated IDs/timestamps come only\n * from injected deterministic sources — the mock itself contains zero\n * randomness. Fault injection (timeout, disconnect, server error, truncated\n * stream) is scripted per step and surfaces as structured errors or marked\n * responses, never as a plausible-looking success. Transport gateways are\n * later slices (3.2-3.3); real models are always out of scope here.\n */\nimport type { JsonValue } from \"@agent-forge/ai\";\n\nexport interface MockAiRequestV1 {\n\treadonly model: string;\n\treadonly messages: readonly JsonValue[];\n\treadonly stream?: boolean;\n}\n\nexport type MockAiPartV1 =\n\t| { readonly type: \"text\"; readonly text: string }\n\t| { readonly type: \"tool_call\"; readonly callId: string; readonly toolName: string; readonly arguments: JsonValue }\n\t| { readonly type: \"finish\"; readonly reason: string };\n\nexport type MockAiFaultV1 = \"timeout\" | \"disconnect\" | \"server_error\" | \"truncated_stream\";\n\nexport interface MockAiStepV1 {\n\treadonly response?: {\n\t\treadonly parts: readonly MockAiPartV1[];\n\t\t/** Stream truncation is also expressible by omitting the finish part. */\n\t};\n\treadonly fault?: MockAiFaultV1;\n}\n\nexport interface MockAiFixtureV1 {\n\treadonly scenarioId: string;\n\treadonly match: {\n\t\treadonly modelEquals?: string;\n\t\treadonly minMessages?: number;\n\t\treadonly streamEquals?: boolean;\n\t};\n\treadonly steps: readonly MockAiStepV1[];\n}\n\nexport interface MockAiResponseV1 {\n\treadonly scenarioId: string;\n\treadonly stepIndex: number;\n\treadonly id: string;\n\treadonly at: number;\n\treadonly parts: readonly MockAiPartV1[];\n\treadonly truncated: boolean;\n\treadonly serverError?: { readonly status: 500 };\n}\n\nexport interface MockAiServerV1 {\n\thandle(request: MockAiRequestV1): MockAiResponseV1;\n\t/** Fails closed: unconsumed scripted steps are a test bug. */\n\tverifyComplete(): void;\n\treceivedRequests(): readonly { readonly at: number; readonly request: MockAiRequestV1 }[];\n}\n\nexport class MockAiError extends Error {\n\treadonly code: \"unmatched_request\" | \"scenario_exhausted\" | \"injected_timeout\" | \"injected_disconnect\";\n\n\tconstructor(code: MockAiError[\"code\"], message: string) {\n\t\tsuper(message);\n\t\tthis.name = \"MockAiError\";\n\t\tthis.code = code;\n\t}\n}\n\nexport function createMockAiServer(options: {\n\treadonly fixtures: readonly MockAiFixtureV1[];\n\treadonly now?: () => number;\n}): MockAiServerV1 {\n\tconst now = options.now ?? (() => 0);\n\tconst consumed = new Map<string, number>();\n\tconst received: Array<{ at: number; request: MockAiRequestV1 }> = [];\n\tconst declaredScenarioIds = new Set(options.fixtures.map((fixture) => fixture.scenarioId));\n\n\tconst matches = (fixture: MockAiFixtureV1, request: MockAiRequestV1): boolean => {\n\t\tif (fixture.match.modelEquals !== undefined && request.model !== fixture.match.modelEquals) return false;\n\t\tif (fixture.match.minMessages !== undefined && request.messages.length < fixture.match.minMessages) return false;\n\t\tif (fixture.match.streamEquals !== undefined && (request.stream ?? false) !== fixture.match.streamEquals)\n\t\t\treturn false;\n\t\treturn true;\n\t};\n\n\treturn {\n\t\thandle(request) {\n\t\t\tconst at = now();\n\t\t\treceived.push({ at, request: { ...request, messages: [...request.messages] } });\n\t\t\tconst fixture = options.fixtures.find((candidate) => matches(candidate, request));\n\t\t\tif (!fixture) {\n\t\t\t\tthrow new MockAiError(\n\t\t\t\t\t\"unmatched_request\",\n\t\t\t\t\t`No fixture matches model=${request.model} messages=${request.messages.length} stream=${request.stream ?? false}; the mock is fail-closed`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst stepIndex = consumed.get(fixture.scenarioId) ?? 0;\n\t\t\tif (stepIndex >= fixture.steps.length) {\n\t\t\t\tthrow new MockAiError(\n\t\t\t\t\t\"scenario_exhausted\",\n\t\t\t\t\t`Scenario ${fixture.scenarioId} has no scripted step ${stepIndex + 1}; extra requests fail closed`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tconsumed.set(fixture.scenarioId, stepIndex + 1);\n\t\t\tconst step = fixture.steps[stepIndex]!;\n\t\t\tif (step.fault === \"timeout\") {\n\t\t\t\tthrow new MockAiError(\n\t\t\t\t\t\"injected_timeout\",\n\t\t\t\t\t`Scenario ${fixture.scenarioId} step ${stepIndex} injected a timeout`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tif (step.fault === \"disconnect\") {\n\t\t\t\tthrow new MockAiError(\n\t\t\t\t\t\"injected_disconnect\",\n\t\t\t\t\t`Scenario ${fixture.scenarioId} step ${stepIndex} injected a disconnect`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst parts = step.response?.parts ?? [];\n\t\t\tconst truncated = step.fault === \"truncated_stream\" || !parts.some((part) => part.type === \"finish\");\n\t\t\treturn {\n\t\t\t\tscenarioId: fixture.scenarioId,\n\t\t\t\tstepIndex,\n\t\t\t\tid: `mock-${fixture.scenarioId}-${stepIndex}`,\n\t\t\t\tat,\n\t\t\t\tparts: Object.freeze([...parts]),\n\t\t\t\ttruncated,\n\t\t\t\t...(step.fault === \"server_error\" ? { serverError: { status: 500 as const } } : {}),\n\t\t\t};\n\t\t},\n\t\tverifyComplete() {\n\t\t\tfor (const fixture of options.fixtures) {\n\t\t\t\tconst consumedCount = consumed.get(fixture.scenarioId) ?? 0;\n\t\t\t\tif (consumedCount !== fixture.steps.length) {\n\t\t\t\t\tthrow new MockAiError(\n\t\t\t\t\t\t\"scenario_exhausted\",\n\t\t\t\t\t\t`Scenario ${fixture.scenarioId} has ${fixture.steps.length - consumedCount} unconsumed scripted step(s)`,\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t}\n\t\t\tvoid declaredScenarioIds;\n\t\t},\n\t\treceivedRequests() {\n\t\t\treturn Object.freeze([...received]);\n\t\t},\n\t};\n}\n"]}