@fayegram-ai/decision-bridge 0.1.1 → 0.1.3

package/src/decisions.d.mts

@@ -1,12 +1,34 @@
 /** Native OpenAI Decisions types, separate from the common bridge contract. */
 export type NativeDecisionInputPart =
-    | { readonly type: 'input_text'; readonly text: string }
+    | { readonly type: 'input_text'; readonly text: string; readonly prompt_cache_breakpoint?: DecisionCacheBreakpoint | null }
     | { readonly type: 'input_image'; readonly image_url: string;
-        readonly detail?: 'low' | 'high' | 'auto' | 'original' | null };
-export interface NativeDecisionMessage {
+        readonly detail?: 'low' | 'high' | 'auto' | 'original' | null;
+        readonly prompt_cache_breakpoint?: DecisionCacheBreakpoint | null };
+export interface DecisionCacheBreakpoint { readonly mode: 'explicit'; }
+export interface DecisionCacheOptions { readonly mode?: 'implicit' | 'explicit' | null; readonly ttl?: '30m'; }
+export type NativeDecisionMessage = {
     readonly role: 'user'; readonly type?: 'message';
     readonly content: string | readonly NativeDecisionInputPart[];
+    readonly phase?: 'commentary' | 'final_answer' | null;
+} | {
+    readonly role: 'developer' | 'system'; readonly type?: 'message';
+    readonly content: string | readonly Extract<NativeDecisionInputPart, { readonly type: 'input_text' }>[];
+    readonly phase?: 'commentary' | 'final_answer' | null;
+} | {
+    readonly role: 'assistant'; readonly type?: 'message';
+    readonly content: string | readonly ({ readonly type: 'output_text'; readonly text: string }
+        | { readonly type: 'refusal'; readonly refusal: string })[];
+    readonly phase?: 'commentary' | 'final_answer' | null;
+};
+interface ToolItem {
+    readonly call_id: string; readonly id?: string | null;
+    readonly status?: 'in_progress' | 'completed' | 'incomplete' | null;
 }
+export type NativeDecisionInputItem = NativeDecisionMessage
+    | (ToolItem & { readonly type: 'function_call'; readonly name: string; readonly arguments: string; readonly namespace?: string | null })
+    | (ToolItem & { readonly type: 'custom_tool_call'; readonly name: string; readonly input: string; readonly namespace?: string | null })
+    | (ToolItem & { readonly type: 'function_call_output' | 'custom_tool_call_output';
+        readonly output: string | readonly NativeDecisionInputPart[] });
 export type NativeDecisionQuestion =
     | { readonly type: 'predicate'; readonly name?: string; readonly instructions: string }
     | { readonly type: 'choice'; readonly name?: string; readonly instructions: string;
@@ -15,9 +37,11 @@ export type NativeDecisionQuestion =
         readonly levels: readonly { readonly label: string; readonly description?: string }[] };
 export interface NativeDecisionRequest {
     readonly model?: string;
-    readonly input: string | readonly NativeDecisionMessage[];
+    readonly input: string | readonly NativeDecisionInputItem[];
     readonly questions: readonly NativeDecisionQuestion[];
     readonly safety_identifier?: string | null;
+    readonly prompt_cache_key?: string | null;
+    readonly prompt_cache_options?: DecisionCacheOptions | null;
 }
 export type NativeDecisionAnswer =
     | { readonly type: 'predicate'; readonly name: string | null; readonly probability: number }

package/src/errors.mjs

@@ -1,6 +1,7 @@
 /** Public errors never retain raw upstream bodies, headers or original exceptions. */
 export class DecisionError extends Error {
-  constructor(message, { code = 'DECISION_ERROR', status, requestId, gatewayLogId, attempts, refusedQuestions, usage, upstreamCode } = {}) {
+  constructor(message, { code = 'DECISION_ERROR', status, requestId, gatewayLogId, attempts, refusedQuestions, usage, upstreamCode,
+    source, upstreamErrorCode, upstreamErrorType, retryAfterMs, retryable } = {}) {
     super(message);
     this.name = 'DecisionError';
     this.code = code;
@@ -11,6 +12,9 @@ export class DecisionError extends Error {
     if (refusedQuestions !== undefined) this.refusedQuestions = refusedQuestions;
     if (usage !== undefined) this.usage = usage;
     if (upstreamCode !== undefined) this.upstreamCode = upstreamCode;
+    for (const [key, value] of Object.entries({ source, upstreamErrorCode, upstreamErrorType, retryAfterMs, retryable })) {
+      if (value !== undefined) this[key] = value;
+    }
   }
 
   toJSON() {
@@ -24,6 +28,8 @@ export class DecisionError extends Error {
       ...(this.refusedQuestions === undefined ? {} : { refusedQuestions: this.refusedQuestions }),
       ...(this.usage === undefined ? {} : { usage: this.usage }),
       ...(this.upstreamCode === undefined ? {} : { upstreamCode: this.upstreamCode }),
+      ...Object.fromEntries(['source', 'upstreamErrorCode', 'upstreamErrorType', 'retryAfterMs', 'retryable']
+        .filter(key => this[key] !== undefined).map(key => [key, this[key]])),
     };
   }
 }

package/src/extraction/index.d.mts

@@ -0,0 +1,66 @@
+import type { JsonValue, TransportOptions, ProviderCallOptions, BatchOptions, ErrorDetails } from '../index.mjs';
+import type { CloudflareGatewayOptions, CloudflareBindingGatewayOptions, CloudflareTransportMetadata } from '../cloudflare-decisions.mjs';
+
+export type ExtractionFieldType = 'text' | 'number' | 'date' | 'time' | 'datetime' | 'duration' | 'list' | 'estimate' | 'forecast';
+export interface ExtractionField {
+    readonly type: ExtractionFieldType; readonly instructions?: string; readonly unit?: string;
+    readonly integer?: boolean; readonly decimals?: number; readonly items?: 'text' | 'number' | 'date';
+    readonly min?: number | string; readonly max?: number | string; readonly step?: number | 'month' | 'year';
+    readonly scale?: 'linear' | 'log'; readonly null_threshold?: number; readonly horizon?: number;
+    readonly interval?: 'step' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+}
+export type ExtractionFields = Readonly<Record<string, ExtractionField>>;
+export interface ExtractionRequest<F extends ExtractionFields = ExtractionFields> {
+    readonly model?: 'clairic' | '@cf/cloudflare/clairic'; readonly state?: string; readonly fields: F;
+    readonly images?: readonly (string | { readonly content_type: string; readonly base64: string })[];
+    readonly reference_date?: string;
+    readonly options?: { readonly include_quantiles?: boolean; readonly return_state_text?: boolean; readonly rejectIfBusy?: boolean };
+}
+export interface ExtractionAnswer {
+    readonly type: ExtractionFieldType; readonly value: JsonValue; readonly guess?: JsonValue;
+    readonly confidence?: number; readonly p_null?: number; readonly span?: readonly [number, number];
+    readonly spans?: readonly (readonly [number, number])[]; readonly mean?: JsonValue; readonly median?: JsonValue;
+    readonly p10?: JsonValue; readonly p90?: JsonValue; readonly p_below?: number; readonly p_above?: number;
+    readonly quantiles?: readonly JsonValue[]; readonly steps?: readonly JsonValue[];
+    readonly [key: string]: unknown;
+}
+// Distribute over field/item unions so unspecialized and batch values stay honest.
+type ListItemValue<I> = I extends 'number' ? number : I extends 'text' | 'date' ? string : number | string;
+type FieldValue<T extends ExtractionFieldType, I> = T extends 'number' | 'duration' ? number | null
+    : T extends 'list' ? readonly ListItemValue<I>[] | null
+    : T extends 'estimate' ? number | string | null
+    : T extends 'forecast' ? JsonValue : string | null;
+export type ExtractionValue<S extends ExtractionField> = FieldValue<S['type'], S['items']>;
+export interface ExtractionResponse<F extends ExtractionFields = ExtractionFields> {
+    readonly model: string;
+    readonly answers: { readonly [K in keyof F]: ExtractionAnswer & { readonly type: F[K]['type']; readonly value: ExtractionValue<F[K]> } };
+    readonly truncated: boolean; readonly state_text?: string;
+    readonly usage: { readonly input_tokens: number; readonly output_tokens: number; readonly state_tokens?: number;
+        readonly image_tokens?: number; readonly schema_tokens?: number; readonly passes?: number; readonly [key: string]: unknown };
+    readonly [key: string]: unknown;
+}
+export interface ExtractionResult<F extends ExtractionFields = ExtractionFields> {
+    readonly extraction: ExtractionResponse<F>;
+    readonly meta: CloudflareTransportMetadata & { readonly provider: 'cloudflare-extraction'; readonly requestedModel: string; readonly resolvedModel: string };
+}
+export interface CloudflareExtractionBinding {
+    run(model: '@cf/cloudflare/clairic', input: ExtractionRequest,
+        options?: { readonly signal?: AbortSignal; readonly returnRawResponse?: boolean; readonly rejectIfBusy?: boolean;
+            readonly gateway?: CloudflareBindingGatewayOptions }): Promise<unknown>;
+}
+type Settings = { model?: 'clairic' | '@cf/cloudflare/clairic'; rejectIfBusy?: boolean; gateway?: CloudflareGatewayOptions };
+export type CloudflareExtractionOptions = Settings & (
+    | (TransportOptions & { transport?: 'rest'; accountId?: string; apiKey?: string; baseURL?: string; ai?: never })
+    | (Omit<TransportOptions, 'fetchImpl'> & { transport: 'binding'; ai: CloudflareExtractionBinding;
+        accountId?: never; apiKey?: never; baseURL?: never; fetchImpl?: never }));
+export type ExtractionValidationOptions = Settings & { transport?: 'rest' | 'binding'; maxRequestBytes?: number; maxRetries?: number };
+export function validateExtractionRequest<const F extends ExtractionFields>(request: ExtractionRequest<F>, options?: ExtractionValidationOptions): ExtractionRequest<F> & { readonly model: 'clairic' };
+export class CloudflareExtractionProvider {
+    readonly name: 'cloudflare-extraction'; readonly kind: 'extraction'; readonly defaultModel: 'clairic';
+    constructor(options?: CloudflareExtractionOptions);
+    validate<const F extends ExtractionFields>(request: ExtractionRequest<F>): ExtractionRequest<F> & { readonly model: 'clairic' };
+    extract<const F extends ExtractionFields>(request: ExtractionRequest<F>, options?: ProviderCallOptions): Promise<ExtractionResult<F>>;
+}
+export type ExtractionBatchRecord = { readonly index: number; readonly ok: true; readonly result: ExtractionResult }
+    | { readonly index: number; readonly ok: false; readonly error: ErrorDetails };
+export function extractBatch(provider: CloudflareExtractionProvider, inputs: readonly ExtractionRequest[], options?: BatchOptions): Promise<readonly ExtractionBatchRecord[]>;

package/src/extraction/index.mjs

@@ -0,0 +1,78 @@
+import { optionsObject, TRANSPORT_FIELDS } from '../options.mjs';
+import { DecisionError, requireCondition as check, withResponseMeta } from '../errors.mjs';
+import { deadline } from '../async.mjs';
+import { cloneJson, freezeJson } from '../validation.mjs';
+import { CloudflareTransport } from '../providers/cloudflare-transport.mjs';
+import { cloudflareGateway, validateCloudflareLimits } from '../providers/cloudflare-profile.mjs';
+import { unwrapCloudflareResponse } from '../providers/cloudflare-validation.mjs';
+import { validateExtractionRequest, validateExtractionResponse, extractionModel } from './validation.mjs';
+import { evaluateBatch } from '../batch.mjs';
+
+export { validateExtractionRequest } from './validation.mjs';
+
+/** Typed extraction remains independent of the decision bridge's answer contract. */
+export class CloudflareExtractionProvider {
+    name = 'cloudflare-extraction';
+    kind = 'extraction';
+    #settings;
+    #transport;
+    #timeoutMs;
+
+    constructor(options = {}) {
+        const supplied = optionsObject(options, ['transport', 'accountId', 'apiKey', 'baseURL', 'ai', 'model',
+            'rejectIfBusy', 'gateway', ...TRANSPORT_FIELDS], 'Cloudflare extraction options');
+        const transport = supplied.transport === undefined ? 'rest' : supplied.transport;
+        check(['rest', 'binding'].includes(transport), 'Unknown Cloudflare transport.', 'CONFIGURATION_ERROR');
+        check(transport !== 'binding' || ['accountId', 'apiKey', 'baseURL', 'fetchImpl'].every(key => supplied[key] === undefined),
+            'Binding transport does not accept REST credentials or HTTP options.', 'CONFIGURATION_ERROR');
+        check(transport !== 'rest' || supplied.ai === undefined, 'REST transport does not accept an ai binding.', 'CONFIGURATION_ERROR');
+        this.defaultModel = extractionModel(supplied.model);
+        this.#timeoutMs = supplied.timeoutMs ?? 30000;
+        const gateway = cloudflareGateway(supplied.gateway);
+        this.#settings = { model: this.defaultModel, transport, gateway, ...validateCloudflareLimits({ ...supplied, gateway }) };
+        this.#transport = new CloudflareTransport({ ...supplied, ...this.#settings }, {
+            models: ['clairic'], requestLimit: (_model, ceiling) => ceiling ?? 8 * 1024 * 1024,
+        });
+    }
+
+    validate(request) { return validateExtractionRequest(request, this.#settings); }
+
+    async extract(input, options = {}) {
+        const { signal } = optionsObject(options, ['signal'], 'Extraction call options');
+        const budget = deadline(this.#timeoutMs, signal);
+        try {
+            budget.throwIfAborted();
+            const snapshot = cloneJson(input, 'extraction request');
+            const request = this.validate(snapshot);
+            const requestedModel = snapshot.model ?? this.#settings.model;
+            budget.throwIfAborted();
+            const { data, meta } = await this.#transport.request(request, { signal: budget.signal });
+            const extraction = withResponseMeta(meta, () => validateExtractionResponse(
+                unwrapCloudflareResponse(data, this.#settings.transport, meta), request));
+            budget.throwIfAborted();
+            return freezeJson({ extraction, meta: { ...meta, provider: 'cloudflare-extraction',
+                requestedModel, resolvedModel: request.model } });
+        } catch (error) {
+            const details = error instanceof DecisionError ? error.toJSON() : {};
+            if (signal?.aborted) throw new DecisionError('Extraction cancelled.', { ...details, code: 'ABORTED', source: 'client' });
+            if (budget.timedOut) throw new DecisionError('Extraction deadline exceeded.', { ...details, code: 'TIMEOUT', source: 'client' });
+            throw error;
+        } finally { budget.close(); }
+    }
+}
+
+/** Reuse the existing ordered, preflighted, caller-controlled batch implementation. */
+export function extractBatch(provider, inputs, options = {}) {
+    check(provider && typeof provider.validate === 'function' && typeof provider.extract === 'function',
+        'An extraction provider is required.', 'CONFIGURATION_ERROR');
+    return evaluateBatch({
+        validate(input) {
+            // Preflight resolves the wire model, but dispatch must retain the caller's
+            // selection for diagnostics. Snapshot before validation and async work.
+            const request = cloneJson(input, 'extraction request');
+            provider.validate(request);
+            return freezeJson(request);
+        },
+        evaluate: (input, call) => provider.extract(input, call),
+    }, inputs, options);
+}

package/src/extraction/validation.mjs

@@ -0,0 +1,105 @@
+import { requireCondition as check } from '../errors.mjs';
+import { cloneJson, freezeJson, isRecord } from '../validation.mjs';
+import { serializeRequestBody } from '../transport.mjs';
+import { optionsObject } from '../options.mjs';
+import { cloudflareBindingBody } from '../providers/cloudflare-preflight.mjs';
+import { cloudflareGateway, validateCloudflareLimits } from '../providers/cloudflare-profile.mjs';
+import { validateCloudflareImages } from '../providers/cloudflare-images.mjs';
+
+const own = (value, key) => Object.hasOwn(value, key);
+const TYPES = ['text', 'number', 'date', 'time', 'datetime', 'duration', 'list', 'estimate', 'forecast'];
+const FIELD_KEYS = ['type', 'instructions', 'unit', 'integer', 'decimals', 'items', 'min', 'max',
+    'step', 'scale', 'null_threshold', 'horizon', 'interval'];
+const isDate = value => typeof value === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(value);
+
+export function extractionModel(value = 'clairic') {
+    check(value === 'clairic' || value === '@cf/cloudflare/clairic', 'Unsupported extraction model.', 'UNSUPPORTED_CAPABILITY');
+    return 'clairic';
+}
+
+function field(spec) {
+    check(isRecord(spec) && Object.keys(spec).every(key => FIELD_KEYS.includes(key)) && TYPES.includes(spec.type), 'Invalid extraction field.');
+    for (const key of ['instructions', 'unit']) check(spec[key] === undefined || typeof spec[key] === 'string', `${key} must be text.`);
+    check(spec.integer === undefined || (['number', 'duration'].includes(spec.type) && typeof spec.integer === 'boolean'), 'Invalid integer option.');
+    check(spec.decimals === undefined || ((['number', 'duration'].includes(spec.type) || spec.type === 'list' && spec.items === 'number') &&
+        Number.isSafeInteger(spec.decimals) && spec.decimals >= 0), 'Invalid decimals option.');
+    if (spec.type === 'duration' && spec.unit !== undefined) check(['seconds', 'minutes', 'hours', 'days', 'weeks', 'months', 'years'].includes(spec.unit), 'Invalid duration unit.');
+    if (spec.type === 'list') check(['text', 'number', 'date'].includes(spec.items), 'Lists require an item type.');
+    else check(spec.items === undefined, 'items applies only to lists.');
+    if (['estimate', 'forecast'].includes(spec.type)) {
+        check((typeof spec.min === 'number' && typeof spec.max === 'number' && spec.min <= spec.max) ||
+            (isDate(spec.min) && isDate(spec.max) && spec.min <= spec.max), 'Prediction fields require ordered numeric or ISO date bounds.');
+    } else check(spec.min === undefined && spec.max === undefined && spec.step === undefined && spec.scale === undefined,
+        'Prediction bounds apply only to estimates and forecasts.');
+    check(spec.step === undefined || (typeof spec.step === 'number' && spec.step > 0) || ['month', 'year'].includes(spec.step), 'Invalid prediction grid step.');
+    check(spec.scale === undefined || ['linear', 'log'].includes(spec.scale), 'Invalid prediction scale.');
+    if (spec.scale === 'log') check(typeof spec.min === 'number' && spec.min > 0, 'Log grids require positive numeric bounds.');
+    check(spec.null_threshold === undefined || (typeof spec.null_threshold === 'number' && spec.null_threshold > 0 && spec.null_threshold <= 1), 'Invalid null threshold.');
+    if (spec.type === 'forecast') {
+        check(spec.horizon === undefined || (Number.isSafeInteger(spec.horizon) && spec.horizon > 0), 'Invalid forecast horizon.');
+        check(spec.interval === undefined || ['step', 'minute', 'hour', 'day', 'week', 'month', 'quarter', 'year'].includes(spec.interval), 'Invalid forecast interval.');
+    } else check(spec.horizon === undefined && spec.interval === undefined, 'Forecast options require a forecast field.');
+}
+
+/** Credential-free preflight shares the exact wire budget with actual dispatch. */
+export function validateExtractionRequest(input, options = {}) {
+    const settings = optionsObject(options, ['model', 'transport', 'gateway', 'maxRequestBytes', 'maxRetries', 'rejectIfBusy'], 'Extraction validation options');
+    const request = cloneJson(input, 'extraction request');
+    check(isRecord(request) && Object.keys(request).every(key => ['model', 'state', 'fields', 'images', 'reference_date', 'options'].includes(key)), 'Invalid extraction request fields.');
+    const model = extractionModel(own(request, 'model') ? request.model : settings.model);
+    check(isRecord(request.fields) && Object.keys(request.fields).length > 0, 'Extraction requires named fields.');
+    for (const [name, spec] of Object.entries(request.fields)) {
+        check(/^[A-Za-z_][A-Za-z0-9_.-]*$/.test(name), 'Invalid extraction field name.');
+        field(spec);
+    }
+    check(request.state === undefined || typeof request.state === 'string', 'Extraction state must be text.');
+    check((request.state?.length ?? 0) > 0 || (Array.isArray(request.images) && request.images.length > 0), 'Provide text or embedded images.');
+    check(request.reference_date === undefined || isDate(request.reference_date), 'reference_date must be an ISO date.');
+    const inference = own(request, 'options') ? request.options : {};
+    check(isRecord(inference) && Object.keys(inference).every(key => ['include_quantiles', 'return_state_text', 'rejectIfBusy'].includes(key)) &&
+        Object.values(inference).every(value => typeof value === 'boolean'), 'Invalid extraction options.');
+    const transport = settings.transport === undefined ? 'rest' : settings.transport;
+    check(['rest', 'binding'].includes(transport), 'Unknown Cloudflare transport.', 'CONFIGURATION_ERROR');
+    const gateway = cloudflareGateway(settings.gateway);
+    const rejectIfBusy = inference.rejectIfBusy ?? settings.rejectIfBusy ?? false;
+    validateCloudflareLimits({ ...settings, gateway, rejectIfBusy });
+    const result = { ...request, model, ...(rejectIfBusy ? { options: { ...inference, rejectIfBusy } } : {}) };
+    serializeRequestBody(transport === 'binding' ? cloudflareBindingBody(result, gateway) : result, settings.maxRequestBytes);
+    if (own(request, 'images')) validateCloudflareImages(request.images);
+    return freezeJson(result);
+}
+
+/** Validate established fields without guessing predictive structures or span units. */
+export function validateExtractionResponse(input, request) {
+    const data = cloneJson(input, 'extraction response', 'INVALID_RESPONSE');
+    const invalid = (condition, message) => check(condition, message, 'INVALID_RESPONSE');
+    invalid(isRecord(data) && typeof data.model === 'string' && data.model.trim() && isRecord(data.answers) &&
+        typeof data.truncated === 'boolean' && isRecord(data.usage), 'Invalid extraction response.');
+    invalid(Object.keys(data.answers).length === Object.keys(request.fields).length, 'Extraction answer count mismatch.');
+    invalid(data.state_text === undefined || typeof data.state_text === 'string', 'Invalid returned state text.');
+    for (const key of ['input_tokens', 'output_tokens', 'state_tokens', 'image_tokens', 'schema_tokens', 'passes']) {
+        if (['input_tokens', 'output_tokens'].includes(key) || own(data.usage, key)) {
+            invalid(Number.isSafeInteger(data.usage[key]) && data.usage[key] >= 0, 'Invalid extraction usage.');
+        }
+    }
+    for (const [name, spec] of Object.entries(request.fields)) {
+        invalid(own(data.answers, name), 'Missing extraction answer.');
+        const answer = data.answers[name];
+        invalid(isRecord(answer) && answer.type === spec.type && own(answer, 'value'), 'Extraction answer type mismatch.');
+        const value = answer.value;
+        if (value !== null && spec.type !== 'forecast') {
+            if (spec.type === 'list') invalid(Array.isArray(value) && value.every(item =>
+                typeof item === (spec.items === 'number' ? 'number' : 'string')), 'Invalid extraction list.');
+            else invalid(typeof value === (['number', 'duration'].includes(spec.type) ? 'number'
+                : spec.type === 'estimate' ? typeof spec.min : 'string'), 'Invalid extraction value.');
+        }
+        for (const key of ['confidence', 'p_null', 'p_below', 'p_above']) if (own(answer, key)) {
+            invalid(typeof answer[key] === 'number' && answer[key] >= 0 && answer[key] <= 1, 'Invalid extraction probability.');
+        }
+        const span = item => Array.isArray(item) && item.length === 2 && item.every(n => Number.isSafeInteger(n) && n >= 0) && item[1] >= item[0];
+        if (own(answer, 'span')) invalid(span(answer.span), 'Invalid extraction span.');
+        if (own(answer, 'spans')) invalid(Array.isArray(answer.spans) && answer.spans.every(span), 'Invalid extraction spans.');
+        for (const key of ['quantiles', 'steps']) if (own(answer, key)) invalid(Array.isArray(answer[key]), 'Invalid predictive array.');
+    }
+    return freezeJson(data);
+}

package/src/index.d.mts

@@ -1,7 +1,10 @@
 /** JSON values are read-only because the bridge snapshots/freezes its boundaries. */
+import type { JevDangerZone, JevQuestions, JevDecisionRequest, JevDecisionResponse, JevTransportMetadata } from './jev.d.mts';
+export type { JevDangerZone, JevImageAsset, JevQuestions, JevDecisionRequest, JevDecisionResponse, JevTransportMetadata } from './jev.d.mts';
 import type { NativeDecisionRequest, OpenAIDecisionResponse, OpenAIDecisionUsage,
     OpenAIDecisionsMetadata, OpenAIDecisionsTransportMetadata } from './decisions.d.mts';
-export type { NativeDecisionInputPart, NativeDecisionMessage, NativeDecisionQuestion, NativeDecisionRequest,
+export type { NativeDecisionInputPart, NativeDecisionInputItem, DecisionCacheBreakpoint, DecisionCacheOptions,
+    NativeDecisionMessage, NativeDecisionQuestion, NativeDecisionRequest,
     NativeDecisionAnswer, OpenAIDecisionResponse, OpenAIDecisionUsage, OpenAIDecisionsMetadata,
     OpenAIDecisionsTransportMetadata, TransportMetadata } from './decisions.d.mts';
 import type { CloudflareDecisionsOptions, CloudflareDecisionRequest, CloudflareDecisionResponse,
@@ -25,6 +28,15 @@ export interface NoulQuestion {
   readonly type: 'noul'; readonly instructions: Instructions;
   readonly criteria?: { readonly true?: Instructions; readonly false?: Instructions };
 }
+export interface BoxQuestion {
+    readonly type: 'box'; readonly instructions: Instructions; readonly criteria?: never;
+}
+export interface BoxCoordinates {
+    readonly top: number; readonly bottom: number; readonly left: number; readonly right: number;
+}
+export interface BoxAnswer {
+    readonly type: 'box'; readonly box: BoxCoordinates; readonly confidence?: number;
+}
 export interface ScoreQuestion<C extends ScoreCriteria = ScoreCriteria> {
   readonly type: 'score'; readonly instructions: Instructions; readonly criteria: C;
   readonly levels?: never;
@@ -40,12 +52,16 @@ export type ScoreLevels = readonly [ScoreLevel, ScoreLevel, ...ScoreLevel[]];
 export interface LabeledScoreQuestion<L extends ScoreLevels = ScoreLevels> {
     readonly type: 'score'; readonly instructions: Instructions; readonly levels: L; readonly criteria?: never;
 }
-export type DecisionInputPart = { readonly type: 'text'; readonly text: string }
-    | { readonly type: 'image'; readonly dataUrl: string; readonly detail?: 'low' | 'high' | 'auto' | 'original' | null }
+export type DecisionConversationItem = import('./decisions.mjs').NativeDecisionInputItem;
+export type DecisionInputPart = { readonly type: 'text'; readonly text: string;
+        readonly promptCacheBreakpoint?: import('./decisions.mjs').DecisionCacheBreakpoint | null }
+    | ({ readonly type: 'image'; readonly detail?: 'low' | 'high' | 'auto' | 'original' | null;
+        readonly promptCacheBreakpoint?: import('./decisions.mjs').DecisionCacheBreakpoint | null }
+        & ({ readonly dataUrl: string; readonly url?: never } | { readonly url: string; readonly dataUrl?: never }))
     | { readonly type: 'audio'; readonly dataUrl: string }
     | { readonly type: 'video'; readonly dataUrl: string };
 export type OrderedInput = readonly DecisionInputPart[];
-export type Question = ChoiceQuestion | TypedChoiceQuestion | NoulQuestion | ScoreQuestion | LabeledScoreQuestion;
+export type Question = ChoiceQuestion | TypedChoiceQuestion | NoulQuestion | ScoreQuestion | LabeledScoreQuestion | BoxQuestion;
 export type Questions = Readonly<Record<string, Question>>;
 export interface ChoiceAnswer<K extends string = string> {
   readonly type: 'choice'; readonly choice: K;
@@ -71,10 +87,14 @@ type ChoiceLabel<K> = K extends string ? K : K extends number ? `${K}` : never;
 export type AnswerFor<Q extends Question> = Q extends TypedChoiceQuestion<infer O> ? TypedChoiceAnswer<O[number]['value']>
   : Q extends LabeledScoreQuestion<infer L> ? LabeledScoreAnswer<L>
   : Q extends ChoiceQuestion<infer C>
-  ? ChoiceAnswer<ChoiceLabel<keyof C>> : Q extends NoulQuestion ? NoulAnswer : ScoreAnswer;
+  ? ChoiceAnswer<ChoiceLabel<keyof C>> : Q extends NoulQuestion ? NoulAnswer : Q extends BoxQuestion ? BoxAnswer : ScoreAnswer;
 export type EvaluationRequest<Q extends Questions = Questions> = {
     readonly questions: Q; readonly model?: string; readonly safetyIdentifier?: string | null;
-} & ({ readonly state: State; readonly input?: never } | { readonly input: OrderedInput; readonly state?: never });
+    readonly promptCacheKey?: string | null;
+    readonly promptCacheOptions?: import('./decisions.mjs').DecisionCacheOptions | null;
+} & ({ readonly state: State; readonly input?: never; readonly conversation?: never }
+    | { readonly input: OrderedInput; readonly state?: never; readonly conversation?: never }
+    | { readonly conversation: readonly DecisionConversationItem[]; readonly state?: never; readonly input?: never });
 export type ResolvedRequest<Q extends Questions = Questions> = EvaluationRequest<Q> & { readonly model: string };
 export interface Usage {
   /** Null means not reported, not zero tokens. */
@@ -110,7 +130,7 @@ export interface ModelList {
     readonly release_date?: string; readonly [key: string]: unknown }[];
   readonly has_more?: boolean; readonly last_id?: string;
 }
-export interface ResultValidationOptions { readonly native?: boolean; readonly probabilityDecimalPlaces?: number; }
+export interface ResultValidationOptions { readonly native?: boolean; readonly nullableUsage?: boolean; readonly probabilityDecimalPlaces?: number; }
 export type ProviderKind = 'decision' | 'generative';
 export interface Provider {
   readonly kind: ProviderKind;
@@ -125,6 +145,8 @@ export interface Provider {
 }
 export interface DecisionProvider extends Provider { readonly kind: 'decision'; }
 export interface Capabilities {
+    readonly conversation?: boolean; readonly toolHistory?: boolean; readonly remoteImages?: boolean; readonly promptCaching?: boolean;
+    readonly boxes?: boolean;
     readonly audio?: boolean; readonly videos?: boolean;
     readonly maxAudioClips?: number | null; readonly maxVideos?: number | null;
     readonly supported: boolean; readonly orderedInput: boolean; readonly images: boolean;
@@ -139,6 +161,8 @@ export interface Extension {
   name: string;
   prepareState?(state: State, context: ExtensionContext): State | undefined | Promise<State | undefined>;
   prepareInput?(input: OrderedInput, context: ExtensionContext): OrderedInput | undefined | Promise<OrderedInput | undefined>;
+  prepareConversation?(conversation: readonly DecisionConversationItem[], context: ExtensionContext):
+    readonly DecisionConversationItem[] | undefined | Promise<readonly DecisionConversationItem[] | undefined>;
   /** Observer failure is isolated in meta.observerFailures; no inference is retried. */
   onResult?(result: EvaluationResult, context: ExtensionContext): void | Promise<void>;
 }
@@ -146,7 +170,7 @@ export interface TransportOptions {
   timeoutMs?: number; maxRetries?: number; maxRequestBytes?: number; maxResponseBytes?: number;
   fetchImpl?: (input: string, init?: RequestInit) => Promise<Response>;
 }
-export interface JevOptions extends TransportOptions { apiKey?: string; model?: string; baseURL?: string; }
+export interface JevOptions extends TransportOptions { apiKey?: string; model?: string; baseURL?: string; dangerZone?: JevDangerZone; }
 export interface OpenAIDecisionsOptions extends TransportOptions { apiKey?: string; model?: string; baseURL?: string; }
 export interface Bridge {
   readonly provider: string; readonly providerKind: ProviderKind; readonly defaultModel?: string;
@@ -166,6 +190,10 @@ export class JevProvider implements DecisionProvider {
   evaluate<const Q extends Questions>(request: EvaluationRequest<Q>, options?: ProviderCallOptions): Promise<ProviderResult<Q>>;
   listModels(options?: ProviderCallOptions): Promise<ModelList>;
   getCapabilities(model?: string): Capabilities;
+  getResultValidationOptions(model?: string): ResultValidationOptions;
+  validateRequest(request: ResolvedRequest): void;
+  createDecision<const Q extends JevQuestions>(request: JevDecisionRequest<Q>, options?: ProviderCallOptions):
+      Promise<{ readonly decision: JevDecisionResponse<Q>; readonly meta: JevTransportMetadata }>;
 }
 export class OpenAIDecisionsProvider implements DecisionProvider {
     readonly kind: 'decision'; readonly name: 'openai-decisions'; readonly probabilitySource: 'native'; readonly defaultModel: string;
@@ -187,10 +215,12 @@ export class CloudflareDecisionsProvider implements DecisionProvider {
         Promise<{ readonly decision: CloudflareDecisionResponse; readonly meta: CloudflareTransportMetadata }>;
 }
 export type CloudflareDecisionsConfig = { type: 'cloudflare-decisions' } & CloudflareDecisionsOptions;
-export type ProviderConfig = ({ type: 'jev' } & JevOptions)
+export type JevConfig = { type: 'jev' } & JevOptions;
+export type ProviderConfig = JevConfig
   | ({ type: 'openai-decisions' } & OpenAIDecisionsOptions)
   | CloudflareDecisionsConfig;
 export type OpenAIDecisionsConfig = { type: 'openai-decisions' } & OpenAIDecisionsOptions;
+export function createProvider(options: JevConfig): JevProvider;
 export function createProvider(options: OpenAIDecisionsConfig): OpenAIDecisionsProvider;
 export function createProvider(options: CloudflareDecisionsConfig): CloudflareDecisionsProvider;
 export function createProvider(options: ProviderConfig | OpenAIDecisionsConfig): DecisionProvider;
@@ -200,6 +230,7 @@ export function choice<const C extends ChoiceCriteria>(instructions: Instruction
 export function noul(instructions: Instructions, criteria?: NoulQuestion['criteria']): NoulQuestion;
 export function score<const C extends ScoreCriteria>(instructions: Instructions, criteria: C): ScoreQuestion<C>;
 export function scoreLevels<const L extends ScoreLevels>(instructions: Instructions, levels: L): LabeledScoreQuestion<L>;
+export function box(instructions: Instructions): BoxQuestion;
 export interface ChoicePolicyOptions<K extends string | boolean = string> {
     minProbability: number; minMargin?: number; abstainOptions?: readonly K[];
     /** Provider-declared probability precision; omission retains the baseline tolerance. */
@@ -214,8 +245,10 @@ export function decideChoice<K extends string>(answer: ChoiceAnswer<K>, options:
 export function decideChoice<V extends string | boolean>(answer: TypedChoiceAnswer<V>, options: ChoicePolicyOptions<V>): ChoiceDecision<V>;
 export interface RefusedQuestion { readonly index: number; readonly name: string | null; }
 export interface ErrorDetails { code: string; message: string; status?: number; requestId?: string; gatewayLogId?: string; attempts?: number; upstreamCode?: number;
+  source?: 'client' | 'provider'; upstreamErrorCode?: string; upstreamErrorType?: string; retryAfterMs?: number; retryable?: boolean;
     refusedQuestions?: readonly RefusedQuestion[]; usage?: OpenAIDecisionUsage; }
 export class DecisionError extends Error {
+  source?: 'client' | 'provider'; upstreamErrorCode?: string; upstreamErrorType?: string; retryAfterMs?: number; retryable?: boolean;
   code: string; status?: number; requestId?: string; gatewayLogId?: string; attempts?: number; upstreamCode?: number;
   refusedQuestions?: readonly RefusedQuestion[]; usage?: OpenAIDecisionUsage;
   constructor(message: string, details?: Omit<ErrorDetails, 'code' | 'message'> & { code?: string });

package/src/index.mjs

@@ -1,6 +1,6 @@
 export { createBridge } from './bridge.mjs';
 export { JevProvider, OpenAIDecisionsProvider, CloudflareDecisionsProvider, createProvider } from './providers/index.mjs';
-export { choice, noul, score, scoreLevels } from './questions.mjs';
+export { choice, noul, score, scoreLevels, box } from './questions.mjs';
 export { decideChoice } from './policy.mjs';
 export { evaluateBatch } from './batch.mjs';
 export { DecisionError, publicError } from './errors.mjs';

package/src/input.mjs

@@ -20,17 +20,35 @@ export function validateImage(dataUrl, detail, code = 'VALIDATION_ERROR') {
         'Unsupported image detail.', code);
 }
 
+/** A public reference is forwarded to the provider; the SDK never fetches it. */
+export function validateImageSource(value, detail, code = 'VALIDATION_ERROR') {
+    if (typeof value === 'string' && /^https?:/i.test(value)) {
+        let url;
+        try { url = new URL(value); } catch { /* Validated below. */ }
+        check(url && ['http:', 'https:'].includes(url.protocol) && !url.username && !url.password,
+            'Images require a public HTTP(S) URL.', code);
+        check(detail === undefined || detail === null || ['low', 'high', 'auto', 'original'].includes(detail),
+            'Unsupported image detail.', code);
+    } else validateImage(value, detail, code);
+}
+
 export function validateOrderedInput(input) {
     check(Array.isArray(input) && input.length > 0, 'input must be a nonempty ordered array.');
     for (const part of input) {
         check(part !== null && typeof part === 'object' && !Array.isArray(part), 'Input parts must be objects.');
-        const fields = part.type === 'text' ? ['type', 'text'] : part.type === 'image'
-            ? ['type', 'dataUrl', 'detail'] : ['type', 'dataUrl'];
+        const fields = part.type === 'text' ? ['type', 'text', 'promptCacheBreakpoint'] : part.type === 'image'
+            ? ['type', 'dataUrl', 'url', 'detail', 'promptCacheBreakpoint'] : ['type', 'dataUrl'];
         check(Object.keys(part).every(key => fields.includes(key)), 'Unknown input part field.');
         if (part.type === 'text') check(typeof part.text === 'string', 'Text parts require text.');
         else {
             check(['image', 'audio', 'video'].includes(part.type), 'Input parts must be text, image, audio, or video.');
-            if (part.type === 'image') validateImage(part.dataUrl, part.detail);
+            if (part.type === 'image') {
+                check(Object.hasOwn(part, 'dataUrl') !== Object.hasOwn(part, 'url'), 'Image requires exactly one of dataUrl or url.');
+                if (Object.hasOwn(part, 'url')) {
+                    check(typeof part.url === 'string' && /^https?:/i.test(part.url), 'url must use HTTP(S).');
+                    validateImageSource(part.url, part.detail);
+                } else validateImage(part.dataUrl, part.detail);
+            }
             else embeddedDataUrl(part.dataUrl, part.type);
         }
     }

package/src/jev.d.mts

@@ -0,0 +1,16 @@
+/** Native Jev JSON assets; file reading and image preparation remain caller-owned. */
+import type { State, ChoiceQuestion, NoulQuestion, ScoreQuestion, BoxQuestion, ProviderResult } from './index.d.mts';
+
+export interface JevDangerZone { readonly images?: boolean; readonly longContext?: boolean; }
+export interface JevImageAsset {
+    readonly type?: 'image'; readonly format: 'png' | 'jpg' | 'jpeg'; readonly data_base64: string;
+}
+export type JevQuestions = Readonly<Record<string, ChoiceQuestion | NoulQuestion | ScoreQuestion | BoxQuestion>>;
+export interface JevDecisionRequest<Q extends JevQuestions = JevQuestions> {
+    readonly state: State; readonly questions: Q; readonly model?: string;
+    readonly assets?: Readonly<Record<string, JevImageAsset>>;
+}
+export type JevDecisionResponse<Q extends JevQuestions = JevQuestions> = Omit<ProviderResult<Q>, 'meta'>;
+export interface JevTransportMetadata {
+    readonly requestedModel: string; readonly durationMs: number; readonly attempts: number; readonly requestId?: string;
+}

package/src/live/index.d.mts

@@ -0,0 +1,73 @@
+import type { CallOptions, ErrorDetails, JsonValue } from '../index.mjs';
+import type { NativeDecisionQuestion, NativeDecisionAnswer, OpenAIDecisionResponse } from '../decisions.mjs';
+
+export type LiveTranscriptType = 'session.input_transcript.delta' | 'session.output_transcript.delta';
+export interface LiveDecisionsConfiguration {
+    readonly delegation?: { readonly type: 'decisions'; readonly decisions: {
+        readonly model?: 'gpt-6-luna'; readonly questions?: readonly NativeDecisionQuestion[] } };
+    readonly triggers?: readonly { readonly type: 'decisions'; readonly event_type: LiveTranscriptType;
+        readonly decisions: { readonly questions: readonly NativeDecisionQuestion[] } }[];
+}
+export interface LiveDecisionItem {
+    readonly id?: string | null; readonly role: 'user'; readonly type?: 'message';
+    readonly content: string | readonly ({ readonly type: 'input_text'; readonly text: string }
+        | { readonly type: 'input_image'; readonly image_url: string; readonly detail?: 'low' | 'high' | 'auto' | 'original' | null })[];
+}
+export type LiveCommand = (
+    | { readonly type: 'session.update'; readonly session: LiveDecisionsConfiguration }
+    | { readonly type: 'decision.item.create'; readonly item: LiveDecisionItem }
+    | { readonly type: 'decision.item.delete'; readonly item_id: string }
+    | { readonly type: 'session.commentary.append'; readonly delegation_id: string | null; readonly content: string }
+) & { readonly event_id?: string | null }
+    | { readonly type: 'decision.create'; readonly event_id: string };
+export type LiveNativeDecision = Omit<OpenAIDecisionResponse, 'answers'> & {
+    readonly answers: readonly (NativeDecisionAnswer | { readonly type: 'refusal'; readonly name: string | null })[];
+};
+export interface LiveDecisionEvent {
+    readonly type: 'decision.event'; readonly event_id: string; readonly delegation_id: string | null;
+    readonly trigger_id: string | null; readonly source_event_id: string | null; readonly source_event_type: LiveTranscriptType | null;
+    readonly event: { readonly type: 'decision.completed'; readonly decision: LiveNativeDecision };
+}
+export type LiveServerEvent = LiveDecisionEvent | { readonly type: string; readonly event_id: string; readonly [key: string]: unknown };
+export type LiveTransportNotification = { readonly kind: 'event'; readonly event: unknown }
+    | { readonly kind: 'close' | 'error' };
+export interface LiveTransport {
+    send(event: LiveCommand): void | Promise<void>;
+    subscribe(listener: (notification: LiveTransportNotification) => void): () => void;
+}
+interface EventMetadata { readonly eventId: string; readonly eventType: string; }
+export interface LiveCorrelation {
+    readonly matched: boolean; readonly stale: boolean; readonly sourceEventId: string | null;
+    readonly sourceEventType: LiveTranscriptType | null; readonly delegationId: string | null; readonly triggerId: string | null;
+    readonly generation?: number; readonly reason?: 'source_or_configuration_unavailable' | 'configuration_mismatch';
+}
+export type LiveConfigurationEvent = EventMetadata & { readonly type: 'configuration';
+    readonly configuration: LiveDecisionsConfiguration; readonly generation: number };
+export type LiveItemEvent = EventMetadata & { readonly type: 'item'; readonly item?: LiveDecisionItem; readonly itemId?: string };
+export type LiveNotification =
+    | LiveConfigurationEvent | LiveItemEvent
+    | (EventMetadata & { readonly type: 'decision'; readonly decision: LiveNativeDecision; readonly correlation: LiveCorrelation })
+    | (EventMetadata & { readonly type: 'transcript'; readonly direction: 'input' | 'output'; readonly delta: string; readonly sequence: number })
+    | (EventMetadata & { readonly type: 'delegation'; readonly delegationId: string })
+    | (EventMetadata & { readonly type: 'duplicate' })
+    | { readonly type: 'error' | 'observer_error' | 'closed'; readonly error?: ErrorDetails;
+        readonly eventId?: string; readonly eventType?: string; readonly clientEventId?: string };
+export interface LiveSubmissionReceipt { readonly eventId: string; readonly type: string; readonly status: 'submitted'; }
+export interface LiveDecisionsOptions {
+    readonly transport: LiveTransport; readonly configuration?: LiveDecisionsConfiguration;
+    readonly timeoutMs?: number; readonly maxPending?: number; readonly maxHistory?: number;
+    readonly maxRequestBytes?: number; readonly maxResponseBytes?: number;
+}
+export interface LiveDecisionsController {
+    configure(configuration: LiveDecisionsConfiguration, options?: CallOptions): Promise<LiveConfigurationEvent>;
+    createItem(item: LiveDecisionItem, options?: CallOptions): Promise<LiveItemEvent>;
+    deleteItem(itemId: string, options?: CallOptions): Promise<LiveItemEvent>;
+    requestDecision(options?: CallOptions): Promise<LiveSubmissionReceipt>;
+    appendCommentary(content: string, options?: CallOptions & { delegationId?: string | null }): Promise<LiveSubmissionReceipt>;
+    subscribe(observer: (event: LiveNotification) => void | Promise<void>): () => void;
+    dispose(): void;
+}
+export function createLiveDecisions(options: LiveDecisionsOptions): LiveDecisionsController;
+export function validateLiveConfiguration(input: unknown): LiveDecisionsConfiguration;
+export function validateLiveCommand(input: unknown): LiveCommand;
+export function validateLiveEvent(input: unknown): LiveServerEvent;