@arnilo/prism 0.3.2 → 0.5.0

package/dist/rpc.d.ts

@@ -8,7 +8,7 @@ export interface RpcRequest {
     readonly params?: Record<string, unknown>;
 }
 export interface RpcSessionFactory {
-    createSession(id?: string): AgentSession;
+    createSession(id?: string): AgentSession | Promise<AgentSession>;
     readonly commands?: readonly CommandDefinition[];
     /** Host-opt-in driver capabilities forwarded to contributed commands on the
      *  `command` execution context. Absent ⇒ context shape unchanged. */

package/dist/rpc.js

@@ -2,7 +2,7 @@ import { createInterface } from "node:readline";
 import { resolveInstructionInjectors } from "./instruction-injection.js";
 import { errorToErrorInfo } from "./redaction.js";
 export async function runRpcServer(options) {
-    const first = options.createSession();
+    const first = await options.createSession();
     const state = {
         current: first,
         currentHandleId: first.id,
@@ -140,7 +140,7 @@ async function handleRequest(request, state, stdout, activeRuns) {
             const handleId = stringParam(request.params, "handleId") ?? stringParam(request.params, "sessionId") ?? stringParam(request.params, "id");
             if (!handleId)
                 throw new Error("switchSession requires params.handleId (or sessionId)");
-            const session = state.sessions.get(handleId) ?? makeSession(state, handleId);
+            const session = state.sessions.get(handleId) ?? (await makeSession(state, handleId));
             state.current = session;
             state.currentHandleId = handleId;
             write(stdout, { id: request.id, ok: true, result: { sessionId: session.id, leafId: session.leafId, handleId } });
@@ -220,8 +220,8 @@ function registerSession(state, session, preferredHandleId) {
     state.sessions.set(handleId, session);
     return handleId;
 }
-function makeSession(state, id) {
-    const session = state.createSession(id);
+async function makeSession(state, id) {
+    const session = await state.createSession(id);
     state.sessions.set(session.id, session);
     return session;
 }

package/dist/testing/persistence-schema.d.ts

@@ -1,6 +1,6 @@
 import type { PersistencePage, SessionEntry, SessionEntryQuery } from "../contracts.js";
 /** Current shared persistence schema version for production database adapters. */
-export declare const PERSISTENCE_SCHEMA_VERSION = 8;
+export declare const PERSISTENCE_SCHEMA_VERSION = 9;
 export type PersistenceTableName = "prism_tenants" | "prism_accounts" | "prism_users" | "prism_agent_definitions" | "prism_sessions" | "prism_branches" | "prism_session_entries" | "prism_session_append_idempotency" | "prism_runs" | "prism_agent_events" | "prism_agent_event_streams" | "prism_tool_calls" | "prism_usage" | "prism_run_feedback" | "prism_retention_policies" | "prism_legal_holds" | "prism_tenant_quotas" | "prism_migrations";
 export type PersistenceColumnType = "text" | "integer" | "number" | "boolean" | "json" | "timestamp";
 export interface PersistenceColumnDefinition {

package/dist/testing/persistence-schema.js

@@ -4,7 +4,7 @@ import { createHash } from "node:crypto";
 // this module defines the shared table/index/pagination/migration expectations
 // adapter authors implement and test against before shipping dialect-specific DDL.
 /** Current shared persistence schema version for production database adapters. */
-export const PERSISTENCE_SCHEMA_VERSION = 8;
+export const PERSISTENCE_SCHEMA_VERSION = 9;
 /** Guidance adapters must follow: values are bound parameters, never interpolated. */
 export const PARAMETERIZED_QUERY_GUIDANCE = "Bind every user-supplied value (session ids, idempotency keys, tenant ids, timestamps, JSON payloads) as a query parameter. Quote/validate schema and table identifiers only; never interpolate untrusted strings into SQL text.";
 const TENANT_COLUMNS = [
@@ -157,6 +157,7 @@ export function createPersistenceSchemaModel() {
                     { name: "error", type: "json", nullable: true },
                     ...TENANT_COLUMNS,
                     { name: "metadata", type: "json", nullable: true },
+                    { name: "prompt_version", type: "json", nullable: true },
                 ],
                 foreignKeys: [{ columns: ["session_id"], referencesTable: "prism_sessions", referencesColumns: ["id"] }],
             },
@@ -502,33 +503,35 @@ function migrationStep(version, name, description) {
             ? { indexes: ["prism_agent_events_owner_timestamp_sequence_idx"] }
             : version === 8
                 ? { table: "prism_sessions", columns: ["version"] }
-                : version === 6
-                    ? {
-                        tables: ["prism_agent_event_streams"],
-                        indexes: ["prism_agent_events_run_sequence_idx"],
-                    }
-                    : version === 2
-                        ? { table: "prism_usage", columns: ["scope", "turn", "attempt"], indexes: ["prism_usage_session_scope_recorded_idx"] }
-                        : version === 3
-                            ? {
-                                tables: ["prism_run_feedback"],
-                                indexes: model.indexes.filter((index) => index.name.startsWith("prism_run_feedback_")).map((index) => index.name),
-                            }
-                            : version === 4
-                                ? // Adapter-local FTS objects (SQLite FTS5 / Postgres tsvector) map to this canonical name.
-                                    { search: ["prism_session_search"], indexes: ["prism_sessions_updated_id_idx"] }
-                                : version === 5
-                                    ? {
-                                        tables: ["prism_legal_holds", "prism_tenant_quotas"],
-                                        indexes: [
-                                            "prism_legal_holds_owner_resource_idx",
-                                            "prism_legal_holds_created_id_idx",
-                                            "prism_tenant_quotas_owner_kind_idx",
-                                        ],
-                                    }
-                                    : (() => {
-                                        throw new Error(`Unknown migration version ${version}`);
-                                    })();
+                : version === 9
+                    ? { table: "prism_runs", columns: ["prompt_version"] }
+                    : version === 6
+                        ? {
+                            tables: ["prism_agent_event_streams"],
+                            indexes: ["prism_agent_events_run_sequence_idx"],
+                        }
+                        : version === 2
+                            ? { table: "prism_usage", columns: ["scope", "turn", "attempt"], indexes: ["prism_usage_session_scope_recorded_idx"] }
+                            : version === 3
+                                ? {
+                                    tables: ["prism_run_feedback"],
+                                    indexes: model.indexes.filter((index) => index.name.startsWith("prism_run_feedback_")).map((index) => index.name),
+                                }
+                                : version === 4
+                                    ? // Adapter-local FTS objects (SQLite FTS5 / Postgres tsvector) map to this canonical name.
+                                        { search: ["prism_session_search"], indexes: ["prism_sessions_updated_id_idx"] }
+                                    : version === 5
+                                        ? {
+                                            tables: ["prism_legal_holds", "prism_tenant_quotas"],
+                                            indexes: [
+                                                "prism_legal_holds_owner_resource_idx",
+                                                "prism_legal_holds_created_id_idx",
+                                                "prism_tenant_quotas_owner_kind_idx",
+                                            ],
+                                        }
+                                        : (() => {
+                                            throw new Error(`Unknown migration version ${version}`);
+                                        })();
     return {
         version,
         name,
@@ -550,6 +553,7 @@ export function createPersistenceMigrationContract() {
             migrationStep(6, "006_agent_event_source", "Add transactional per-run event counters and unique durable event sequencing."),
             migrationStep(7, "007_agent_event_retention_index", "Add an exact-owner durable-event retention cleanup index."),
             migrationStep(8, "008_session_version", "Add a NOT NULL DEFAULT 0 version column to prism_sessions for appendSession metadata CAS."),
+            migrationStep(9, "009_run_prompt_version", "Add a nullable prompt_version JSON provenance ref column to prism_runs."),
         ],
         lockGuidance: "Acquire a dialect-specific migration lock before applying steps (PostgreSQL advisory lock; SQLite exclusive transaction). Only one process should migrate at a time.",
         leastPrivilegeGuidance: "Run migrations with a DDL-capable role; use a separate least-privilege runtime role limited to INSERT/SELECT/UPDATE on adapter tables. Never grant migration credentials to the agent runtime.",

package/dist/testing/provider-conformance.d.ts

@@ -1,4 +1,4 @@
-import type { AIProvider, ContentBlock, JsonObject, ProviderEvent, ProviderRequest, ToolCallContent, Usage } from "../contracts.js";
+import type { AIProvider, BatchJobsProvider, BatchRequestItem, ContentBlock, EmbeddingsProvider, EmbeddingsResult, ImageGenerationProvider, ImageGenerationResult, JsonObject, ModerationProvider, ModerationResult, ProviderEvent, ProviderRequest, SpeechProvider, SpeechResult, ToolCallContent, TranscriptionProvider, TranscriptionResult, Usage, VideoGenerationJob, VideoGenerationProvider } from "../contracts.js";
 export interface ProviderStreamConformanceOptions {
     readonly provider: AIProvider;
     readonly request: ProviderRequest;
@@ -29,10 +29,6 @@ export interface ProviderHeaderOwnershipConformanceOptions {
     /** Caller-supplied headers, including attempts to override owned names and non-owned additions. */
     readonly caller: Readonly<Record<string, string>>;
 }
-export interface ProviderSecretLeakConformanceOptions {
-    readonly events: readonly ProviderEvent[];
-    readonly secrets: readonly string[];
-}
 export declare function collectProviderEvents(provider: AIProvider, request: ProviderRequest): Promise<readonly ProviderEvent[]>;
 export declare function assertProviderStreamConforms(options: ProviderStreamConformanceOptions): Promise<readonly ProviderEvent[]>;
 export declare function assertAbortIsObserved(options: ProviderAbortConformanceOptions): Promise<void>;
@@ -51,3 +47,116 @@ export declare function assertNoForeignCacheFields(body: unknown, allowed?: read
 /** Provider construction and setup must perform zero network calls; discovery and streams are caller-gated. */
 export declare function assertNoFetches(calls: readonly unknown[]): void;
 export declare function assertUsageAccounting(events: readonly ProviderEvent[], expected: Usage): Usage;
+export interface EmbeddingsConformanceOptions {
+    readonly provider: EmbeddingsProvider;
+    readonly model: string;
+    /** When set, an oversized batch must fail with `EmbeddingsError("batch_too_large")`. */
+    readonly maxBatchSize?: number;
+    /** Happy-path mapping probe: inputs to embed and the expected vector count/dimensions. */
+    readonly sample?: {
+        readonly inputs: readonly string[];
+        readonly dimensions?: number;
+    };
+}
+/** Offline conformance for any `EmbeddingsProvider` (plan 061): typed empty-input
+ *  error, typed oversized-batch error, and input-order vector mapping with finite
+ *  coordinates. No network — the caller supplies the provider (real adapter with a
+ *  fake transport, or a fake provider). */
+export declare function runEmbeddingsConformance(options: EmbeddingsConformanceOptions): Promise<EmbeddingsResult | undefined>;
+export interface SpeechConformanceOptions {
+    readonly provider: SpeechProvider;
+    readonly model: string;
+    /** When set, an oversized input must fail with `SpeechError("input_too_large")`. */
+    readonly maxInputChars?: number;
+    /** Happy-path probe: text to synthesize, optional voice/format. */
+    readonly sample?: {
+        readonly input?: string;
+        readonly voice?: string;
+        readonly format?: string;
+    };
+}
+/** Offline conformance for any `SpeechProvider` (plan 061): typed empty-input and
+ *  oversized-input errors, byte results, and stream ordering — the stream must emit
+ *  at least one chunk before closing. Asserts event order, never wall clock. */
+export declare function runSpeechConformance(options: SpeechConformanceOptions): Promise<SpeechResult | undefined>;
+export interface TranscriptionConformanceOptions {
+    readonly provider: TranscriptionProvider;
+    readonly model: string;
+    /** When set, oversized audio must fail with `TranscriptionError("audio_too_large")`. */
+    readonly maxAudioBytes?: number;
+    /** Happy-path probe: audio bytes and the expected transcript prefix. */
+    readonly sample?: {
+        readonly audio?: Uint8Array;
+        readonly format?: string;
+        readonly textIncludes?: string;
+    };
+}
+/** Offline conformance for any `TranscriptionProvider` (plan 061): typed empty-audio
+ *  and oversized-audio errors, one-shot text, and stream ordering — at least one
+ *  `transcript_delta` partial, then exactly one `done` terminal event. */
+export declare function runTranscriptionConformance(options: TranscriptionConformanceOptions): Promise<TranscriptionResult | undefined>;
+export interface ImageGenerationConformanceOptions {
+    readonly provider: ImageGenerationProvider;
+    readonly model: string;
+    /** When set, an oversized prompt must fail with `ImageGenerationError("input_too_large")`. */
+    readonly maxPromptChars?: number;
+    /** Happy-path probe: prompt, requested image count, expected provenance. */
+    readonly sample?: {
+        readonly prompt?: string;
+        readonly size?: string;
+        readonly count?: number;
+    };
+}
+/** Offline conformance for any `ImageGenerationProvider` (plan 061): typed empty-input
+ *  and oversized-prompt errors, plus image shape — non-empty bytes, an `image/*` mime
+ *  type, and preserved provenance (`provider`/`model`) on every image. */
+export declare function runImageGenerationConformance(options: ImageGenerationConformanceOptions): Promise<ImageGenerationResult | undefined>;
+export interface VideoGenerationConformanceOptions {
+    readonly provider: VideoGenerationProvider;
+    readonly model: string;
+    /** When set, an oversized prompt must fail with `VideoGenerationError("input_too_large")`. */
+    readonly maxPromptChars?: number;
+    /** Happy-path lifecycle probe: submit, poll to terminal state, assert result shape. */
+    readonly sample?: {
+        readonly prompt?: string;
+        readonly maxPolls?: number;
+    };
+}
+/** Offline conformance for any `VideoGenerationProvider` (plan 061): typed
+ *  empty-input and oversized-prompt errors, plus the submit→status lifecycle —
+ *  a job id is returned, polling reaches a terminal state, and succeeded jobs
+ *  carry a video with provenance (`provider`/`model`) and at least one source
+ *  (`bytes` or `url`). */
+export declare function runVideoGenerationConformance(options: VideoGenerationConformanceOptions): Promise<VideoGenerationJob | undefined>;
+export interface ModerationConformanceOptions {
+    readonly provider: ModerationProvider;
+    readonly model: string;
+    /** When set, an oversized input must fail with `ModerationError("input_too_large")`. */
+    readonly maxInputChars?: number;
+    /** Happy-path probe: a benign string classification. */
+    readonly sample?: {
+        readonly input?: string;
+    };
+}
+/** Offline conformance for any `ModerationProvider` (plan 061): typed empty-input
+ *  and oversized-input errors, plus a classification probe — every category
+ *  verdict carries a numeric score in [0,1], a boolean `flagged`, and the
+ *  top-level `flagged` boolean is present. Scores are provider output; conformance
+ *  asserts no local policy decisions are baked in. */
+export declare function runModerationConformance(options: ModerationConformanceOptions): Promise<ModerationResult | undefined>;
+export interface BatchJobsConformanceOptions {
+    readonly provider: BatchJobsProvider;
+    /** Sample lifecycle driver: submitted via `submit` and expected to reach `completed`. */
+    readonly sample?: {
+        readonly model: string;
+        readonly requests: readonly BatchRequestItem[];
+    };
+    /** When set, a submit over this count must fail with `BatchJobsError("too_many_requests")`. */
+    readonly maxRequests?: number;
+}
+/** Offline conformance for any `BatchJobsProvider` (plan 061): typed empty/oversized
+ *  submit errors, opaque job ids, status returning members of the neutral state
+ *  union, terminal resolution via `pollBatch` (plain utility), and paged results
+ *  that walk to exhaustion with cursor continuity. Failure/cancel terminal
+ *  transitions are covered by provider fakes in adapter test suites. */
+export declare function runBatchJobsConformance(options: BatchJobsConformanceOptions): Promise<void>;

package/dist/testing/provider-conformance.js

@@ -1,3 +1,4 @@
+import { BatchJobsError, EmbeddingsError, ImageGenerationError, ModerationError, pollBatch, SpeechError, TranscriptionError, VideoGenerationError, } from "../contracts.js";
 import { reconstructToolCallDeltas } from "../provider-events.js";
 import { canonicalizeJsonSchema } from "../providers/schema.js";
 export async function collectProviderEvents(provider, request) {
@@ -194,4 +195,345 @@ function jsonPrimitives(value) {
 function textFrom(events) {
     return events.map((event) => (event.type === "content_delta" && event.content.type === "text" ? event.content.text : "")).join("");
 }
+/** Offline conformance for any `EmbeddingsProvider` (plan 061): typed empty-input
+ *  error, typed oversized-batch error, and input-order vector mapping with finite
+ *  coordinates. No network — the caller supplies the provider (real adapter with a
+ *  fake transport, or a fake provider). */
+export async function runEmbeddingsConformance(options) {
+    await assertEmbeddingsErrorCode(() => options.provider.embedMany({ model: options.model, inputs: [] }), "empty_input", "empty inputs must reject with EmbeddingsError(empty_input)");
+    if (options.maxBatchSize !== undefined) {
+        const inputs = Array.from({ length: options.maxBatchSize + 1 }, (_, i) => `input-${i}`);
+        await assertEmbeddingsErrorCode(() => options.provider.embedMany({ model: options.model, inputs }), "batch_too_large", `batches over ${options.maxBatchSize} must reject with EmbeddingsError(batch_too_large)`);
+    }
+    if (!options.sample)
+        return undefined;
+    const result = await options.provider.embedMany({ model: options.model, inputs: options.sample.inputs });
+    if (result.vectors.length !== options.sample.inputs.length)
+        throw new Error(`vector count ${result.vectors.length} must match input count ${options.sample.inputs.length}`);
+    for (const vector of result.vectors) {
+        if (!Array.isArray(vector) || vector.length === 0 || !vector.every(Number.isFinite))
+            throw new Error("vectors must be non-empty arrays of finite numbers");
+    }
+    if (!(result.dimensions > 0))
+        throw new Error("result.dimensions must be positive");
+    if (options.sample.dimensions !== undefined && result.dimensions !== options.sample.dimensions)
+        throw new Error(`result.dimensions ${result.dimensions} must match expected ${options.sample.dimensions}`);
+    return result;
+}
+async function assertEmbeddingsErrorCode(run, code, label) {
+    let error;
+    try {
+        await run();
+    }
+    catch (caught) {
+        error = caught;
+    }
+    if (!(error instanceof EmbeddingsError))
+        throw new Error(`${label}; got ${error === undefined ? "a successful result" : String(error)}`);
+    if (error.code !== code)
+        throw new Error(`${label}; got code ${error.code} (${error.message})`);
+}
+/** Offline conformance for any `SpeechProvider` (plan 061): typed empty-input and
+ *  oversized-input errors, byte results, and stream ordering — the stream must emit
+ *  at least one chunk before closing. Asserts event order, never wall clock. */
+export async function runSpeechConformance(options) {
+    const input = options.sample?.input ?? "conformance";
+    await assertSpeechErrorCode(() => options.provider.synthesize({ model: options.model, input: "" }), "empty_input", "empty input must reject with SpeechError(empty_input)");
+    if (options.maxInputChars !== undefined) {
+        await assertSpeechErrorCode(() => options.provider.synthesize({ model: options.model, input: "x".repeat(options.maxInputChars + 1) }), "input_too_large", `inputs over ${options.maxInputChars} chars must reject with SpeechError(input_too_large)`);
+    }
+    if (!options.sample)
+        return undefined;
+    const request = {
+        model: options.model,
+        input,
+        ...(options.sample.voice ? { voice: options.sample.voice } : {}),
+        ...(options.sample.format ? { format: options.sample.format } : {}),
+    };
+    const result = await options.provider.synthesize(request);
+    if (!(result.audio instanceof Uint8Array) || result.audio.byteLength === 0)
+        throw new Error("synthesize must return non-empty audio bytes");
+    if (typeof result.format !== "string" || result.format.length === 0)
+        throw new Error("result.format must be a non-empty string");
+    const streamed = await options.provider.synthesizeStream(request);
+    const reader = streamed.audio.getReader();
+    let chunks = 0;
+    let firstChunkBeforeClose = false;
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        if (chunks === 0 && value.byteLength > 0)
+            firstChunkBeforeClose = true;
+        chunks += 1;
+    }
+    if (chunks === 0 || !firstChunkBeforeClose)
+        throw new Error("synthesizeStream must emit at least one non-empty chunk before closing");
+    return result;
+}
+async function assertSpeechErrorCode(run, code, label) {
+    let error;
+    try {
+        await run();
+    }
+    catch (caught) {
+        error = caught;
+    }
+    if (!(error instanceof SpeechError))
+        throw new Error(`${label}; got ${error === undefined ? "a successful result" : String(error)}`);
+    if (error.code !== code)
+        throw new Error(`${label}; got code ${error.code} (${error.message})`);
+}
+/** Offline conformance for any `TranscriptionProvider` (plan 061): typed empty-audio
+ *  and oversized-audio errors, one-shot text, and stream ordering — at least one
+ *  `transcript_delta` partial, then exactly one `done` terminal event. */
+export async function runTranscriptionConformance(options) {
+    const audio = options.sample?.audio ?? new Uint8Array([1, 2, 3]);
+    await assertTranscriptionErrorCode(() => options.provider.transcribe({ model: options.model, audio: new Uint8Array(0) }), "empty_input", "empty audio must reject with TranscriptionError(empty_input)");
+    if (options.maxAudioBytes !== undefined) {
+        await assertTranscriptionErrorCode(() => options.provider.transcribe({ model: options.model, audio: new Uint8Array(options.maxAudioBytes + 1) }), "audio_too_large", `audio over ${options.maxAudioBytes} bytes must reject with TranscriptionError(audio_too_large)`);
+    }
+    if (!options.sample)
+        return undefined;
+    const request = {
+        model: options.model,
+        audio,
+        ...(options.sample.format ? { format: options.sample.format } : {}),
+    };
+    const result = await options.provider.transcribe(request);
+    if (typeof result.text !== "string")
+        throw new Error("transcribe must return string text");
+    if (options.sample.textIncludes !== undefined && !result.text.includes(options.sample.textIncludes))
+        throw new Error(`transcript ${JSON.stringify(result.text)} must include ${JSON.stringify(options.sample.textIncludes)}`);
+    let deltas = 0;
+    let doneEvents = 0;
+    for await (const event of options.provider.transcribeStream(request)) {
+        if (event.type === "transcript_delta") {
+            if (typeof event.text !== "string")
+                throw new Error("transcript_delta must carry string text");
+            deltas += 1;
+        }
+        else if (event.type === "done") {
+            doneEvents += 1;
+            if (typeof event.text !== "string")
+                throw new Error("done must carry string text");
+        }
+        else {
+            throw new Error(`unexpected transcript event ${event.type}`);
+        }
+    }
+    if (deltas === 0)
+        throw new Error("transcribeStream must yield at least one transcript_delta before done");
+    if (doneEvents !== 1)
+        throw new Error(`transcribeStream must yield exactly one done event; got ${doneEvents}`);
+    return result;
+}
+async function assertTranscriptionErrorCode(run, code, label) {
+    let error;
+    try {
+        await run();
+    }
+    catch (caught) {
+        error = caught;
+    }
+    if (!(error instanceof TranscriptionError))
+        throw new Error(`${label}; got ${error === undefined ? "a successful result" : String(error)}`);
+    if (error.code !== code)
+        throw new Error(`${label}; got code ${error.code} (${error.message})`);
+}
+/** Offline conformance for any `ImageGenerationProvider` (plan 061): typed empty-input
+ *  and oversized-prompt errors, plus image shape — non-empty bytes, an `image/*` mime
+ *  type, and preserved provenance (`provider`/`model`) on every image. */
+export async function runImageGenerationConformance(options) {
+    await assertImageGenerationErrorCode(() => options.provider.generate({ model: options.model, prompt: "" }), "empty_input", "empty prompts must reject with ImageGenerationError(empty_input)");
+    if (options.maxPromptChars !== undefined) {
+        await assertImageGenerationErrorCode(() => options.provider.generate({ model: options.model, prompt: "x".repeat(options.maxPromptChars + 1) }), "input_too_large", `prompts over ${options.maxPromptChars} chars must reject with ImageGenerationError(input_too_large)`);
+    }
+    if (!options.sample)
+        return undefined;
+    const result = await options.provider.generate({
+        model: options.model,
+        prompt: options.sample.prompt ?? "conformance cube",
+        ...(options.sample.size ? { size: options.sample.size } : {}),
+        ...(options.sample.count ? { count: options.sample.count } : {}),
+    });
+    if (result.images.length === 0)
+        throw new Error("generate must return at least one image");
+    if (options.sample.count !== undefined && result.images.length !== options.sample.count)
+        throw new Error(`image count ${result.images.length} must match requested ${options.sample.count}`);
+    for (const image of result.images) {
+        if (!(image.bytes instanceof Uint8Array) || image.bytes.byteLength === 0)
+            throw new Error("generated images must carry non-empty bytes");
+        if (typeof image.mimeType !== "string" || !image.mimeType.startsWith("image/"))
+            throw new Error(`image mime type ${image.mimeType} must be image/*`);
+        if (image.provider !== options.provider.id)
+            throw new Error(`image provenance provider ${image.provider} must be preserved (${options.provider.id})`);
+        if (image.model !== options.model)
+            throw new Error(`image provenance model ${image.model} must be preserved (${options.model})`);
+    }
+    return result;
+}
+async function assertImageGenerationErrorCode(run, code, label) {
+    let error;
+    try {
+        await run();
+    }
+    catch (caught) {
+        error = caught;
+    }
+    if (!(error instanceof ImageGenerationError))
+        throw new Error(`${label}; got ${error === undefined ? "a successful result" : String(error)}`);
+    if (error.code !== code)
+        throw new Error(`${label}; got code ${error.code} (${error.message})`);
+}
+/** Offline conformance for any `VideoGenerationProvider` (plan 061): typed
+ *  empty-input and oversized-prompt errors, plus the submit→status lifecycle —
+ *  a job id is returned, polling reaches a terminal state, and succeeded jobs
+ *  carry a video with provenance (`provider`/`model`) and at least one source
+ *  (`bytes` or `url`). */
+export async function runVideoGenerationConformance(options) {
+    await assertVideoGenerationErrorCode(() => options.provider.submit({ model: options.model, prompt: "" }), "empty_input", "empty prompts must reject with VideoGenerationError(empty_input)");
+    if (options.maxPromptChars !== undefined) {
+        await assertVideoGenerationErrorCode(() => options.provider.submit({ model: options.model, prompt: "x".repeat(options.maxPromptChars + 1) }), "input_too_large", `prompts over ${options.maxPromptChars} chars must reject with VideoGenerationError(input_too_large)`);
+    }
+    if (!options.sample)
+        return undefined;
+    const { jobId } = await options.provider.submit({ model: options.model, prompt: options.sample.prompt ?? "conformance clip" });
+    if (typeof jobId !== "string" || jobId.length === 0)
+        throw new Error("submit must return a non-empty job id");
+    const maxPolls = options.sample.maxPolls ?? 10;
+    let job;
+    for (let poll = 0; poll < maxPolls; poll += 1) {
+        job = await options.provider.status(jobId);
+        if (!job)
+            throw new Error("status must return a job");
+        if (job.state === "succeeded" || job.state === "failed")
+            break;
+    }
+    if (!job || (job.state !== "succeeded" && job.state !== "failed"))
+        throw new Error(`status did not reach a terminal state within ${maxPolls} polls`);
+    if (job.state === "failed")
+        return job;
+    const video = job.video;
+    if (!video)
+        throw new Error("succeeded jobs must carry a video");
+    if (!video.bytes && !video.url)
+        throw new Error("generated videos must carry bytes or a url");
+    if (video.provider !== options.provider.id)
+        throw new Error(`video provenance provider ${video.provider} must be preserved (${options.provider.id})`);
+    if (video.model !== options.model)
+        throw new Error(`video provenance model ${video.model} must be preserved (${options.model})`);
+    return job;
+}
+async function assertVideoGenerationErrorCode(run, code, label) {
+    let error;
+    try {
+        await run();
+    }
+    catch (caught) {
+        error = caught;
+    }
+    if (!(error instanceof VideoGenerationError))
+        throw new Error(`${label}; got ${error === undefined ? "a successful result" : String(error)}`);
+    if (error.code !== code)
+        throw new Error(`${label}; got code ${error.code} (${error.message})`);
+}
+/** Offline conformance for any `ModerationProvider` (plan 061): typed empty-input
+ *  and oversized-input errors, plus a classification probe — every category
+ *  verdict carries a numeric score in [0,1], a boolean `flagged`, and the
+ *  top-level `flagged` boolean is present. Scores are provider output; conformance
+ *  asserts no local policy decisions are baked in. */
+export async function runModerationConformance(options) {
+    await assertModerationErrorCode(() => options.provider.moderate({ input: "", model: options.model }), "empty_input", "empty inputs must reject with ModerationError(empty_input)");
+    if (options.maxInputChars !== undefined) {
+        await assertModerationErrorCode(() => options.provider.moderate({ input: "x".repeat(options.maxInputChars + 1), model: options.model }), "input_too_large", `inputs over ${options.maxInputChars} chars must reject with ModerationError(input_too_large)`);
+    }
+    if (!options.sample)
+        return undefined;
+    const classified = await options.provider.moderate({ input: options.sample.input ?? "conformance probe", model: options.model });
+    if (Array.isArray(classified))
+        throw new Error("single-string input must classify to one ModerationResult, not a batch");
+    const result = classified;
+    if (typeof result.flagged !== "boolean")
+        throw new Error("moderation results must carry a top-level flagged boolean");
+    const entries = Object.entries(result.categories);
+    if (entries.length === 0)
+        throw new Error("moderation results must expose at least one category verdict");
+    for (const [name, verdict] of entries) {
+        if (typeof verdict.score !== "number" || !(verdict.score >= 0 && verdict.score <= 1))
+            throw new Error(`category ${name} score ${verdict.score} must be a number in [0,1]`);
+        if (typeof verdict.flagged !== "boolean")
+            throw new Error(`category ${name} verdict must carry a flagged boolean`);
+    }
+    return result;
+}
+async function assertModerationErrorCode(run, code, label) {
+    let error;
+    try {
+        await run();
+    }
+    catch (caught) {
+        error = caught;
+    }
+    if (!(error instanceof ModerationError))
+        throw new Error(`${label}; got ${error === undefined ? "a successful result" : String(error)}`);
+    if (error.code !== code)
+        throw new Error(`${label}; got code ${error.code} (${error.message})`);
+}
+/** Offline conformance for any `BatchJobsProvider` (plan 061): typed empty/oversized
+ *  submit errors, opaque job ids, status returning members of the neutral state
+ *  union, terminal resolution via `pollBatch` (plain utility), and paged results
+ *  that walk to exhaustion with cursor continuity. Failure/cancel terminal
+ *  transitions are covered by provider fakes in adapter test suites. */
+export async function runBatchJobsConformance(options) {
+    await assertBatchJobsErrorCode(() => options.provider.submit({ model: "batch-model", requests: [] }), "empty_requests", "empty submits must reject with BatchJobsError(empty_requests)");
+    if (options.maxRequests !== undefined) {
+        await assertBatchJobsErrorCode(() => options.provider.submit({ model: "batch-model", requests: Array.from({ length: options.maxRequests + 1 }, () => ({ body: {} })) }), "too_many_requests", `submits over ${options.maxRequests} requests must reject with BatchJobsError(too_many_requests)`);
+    }
+    if (!options.sample)
+        return;
+    const submitted = await options.provider.submit({ model: options.sample.model, requests: options.sample.requests });
+    if (typeof submitted.id !== "string" || submitted.id.length === 0)
+        throw new Error("submit must return an opaque non-empty job id");
+    const status = await options.provider.status(submitted.id);
+    if (typeof status.state !== "string")
+        throw new Error("status must return a typed job state");
+    const terminal = await pollBatch(options.provider, submitted.id, { intervalMs: 1, maxAttempts: 10 });
+    if (terminal.state !== "completed")
+        throw new Error(`sample job must reach completed; got ${terminal.state}`);
+    const seen = [];
+    let cursor = null;
+    let pages = 0;
+    while (pages < 10) {
+        const page = await options.provider.results(submitted.id, { cursor: cursor ?? null });
+        for (const item of page.items) {
+            if (typeof item.customId !== "string" || item.customId.length === 0)
+                throw new Error("result items must carry non-empty custom ids");
+            seen.push(item.customId);
+        }
+        if (!page.nextCursor)
+            break;
+        if (page.nextCursor === cursor)
+            throw new Error("results cursor must advance between pages");
+        cursor = page.nextCursor;
+        pages += 1;
+    }
+    if (seen.length === 0)
+        throw new Error("completed job must expose at least one result item");
+    if (new Set(seen).size !== seen.length)
+        throw new Error("result paging must not duplicate items across pages");
+}
+async function assertBatchJobsErrorCode(run, code, label) {
+    let error;
+    try {
+        await run();
+    }
+    catch (caught) {
+        error = caught;
+    }
+    if (!(error instanceof BatchJobsError))
+        throw new Error(`${label}; got ${error === undefined ? "a successful result" : String(error)}`);
+    if (error.code !== code)
+        throw new Error(`${label}; got code ${error.code} (${error.message})`);
+}
 //# sourceMappingURL=provider-conformance.js.map

package/dist/testing/tool-conformance.d.ts

@@ -37,3 +37,28 @@ export declare function dispatchAndCollect(probe: ToolDispatchProbeOptions): Pro
     result: ToolResult;
     events: AgentEvent[];
 }>;
+export interface ToolDisclosureConformanceOptions {
+    /** Host-active tool definitions; may include schema-bearing and oversized-description tools. */
+    readonly tools: readonly ToolDefinition[];
+    /** Host allow/deny bounds applied before disclosure (same input the runtime narrows). */
+    readonly filter?: ToolFilterInput;
+    /** Search options under test (topK). */
+    readonly search?: {
+        readonly topK?: number;
+    };
+    /** Turn text used for the relevance query. Defaults to a zero-match probe. */
+    readonly input?: string;
+    /** Secret values that must never appear in model-facing search output. */
+    readonly secrets?: readonly (string | undefined)[];
+}
+/**
+ * Assert the tool-disclosure contract (plan 041) against the same narrowing the
+ * runtime applies: search mode only narrows (disclosed set is a subset of the
+ * allow/deny-filtered input, never wider, never zero, deterministic order); a
+ * denied tool is never described; the generated `search_tools` tool is always
+ * kept and its output is inert — names plus byte-truncated descriptions only,
+ * no JSON structure, no secret values — and activation stays disclosed beside
+ * the turn top-k next turn. Fails closed: an index over the hard cap discloses
+ * the full eligible list. Throws on the first violation.
+ */
+export declare function assertToolDisclosureConforms(options: ToolDisclosureConformanceOptions): void;