humanish 0.141.0 → 0.143.0

package/dist/analysis/gemini-wire.js

@@ -0,0 +1,166 @@
+// The Gemini API generateContent wire format of one analysis request
+// (ai.google.dev/api/generate-content, read 2026-10-21): what the request body says and how a
+// response becomes an AnalysisProviderResult. provider.ts owns the transport around it.
+import { isRecord } from "../run/type-guards.js";
+import { INPUT_IMAGE_DATA_URL } from "./image-tokens.js";
+const record = (value) => (isRecord(value) ? value : {});
+const count = (value) => Number.isSafeInteger(value) && value >= 0 && value <= 1e12;
+/**
+ * The response schema as Gemini accepts it, and the array limits it leaves out. Gemini refuses the
+ * analysis schemas with a 400 while they carry `maxItems`: its constrained decoder counts the
+ * states each nested array limit adds, and its structured-output guide names large nested
+ * `maxItems` as a cause of that refusal. So any Gemini model can return an array past its limit;
+ * validation.ts checks every response against the full schema and refuses that one as
+ * analysis_validation_failed_schema_invalid. The limits go to the model as instructions instead.
+ */
+function withoutArrayLimits(schema) {
+    const limits = [];
+    const strip = (value, path) => {
+        if (Array.isArray(value))
+            return value.map((item) => strip(item, path));
+        if (!isRecord(value))
+            return value;
+        if (typeof value.maxItems === "number")
+            limits.push(`${path || "the answer"}: ${value.maxItems}`);
+        return Object.fromEntries(Object.entries(value)
+            .filter(([key]) => key !== "maxItems")
+            .map(([key, child]) => [
+            key,
+            key === "properties" && isRecord(child)
+                ? Object.fromEntries(Object.entries(child).map(([name, field]) => [
+                    name,
+                    strip(field, path ? `${path}.${name}` : name),
+                ]))
+                : strip(child, key === "items" ? `${path}[]` : path),
+        ]));
+    };
+    return { schema: strip(schema, ""), limits };
+}
+/**
+ * Proto3 JSON leaves out a count that is zero, so an absent thoughts, candidates or cached count is
+ * 0. promptTokenCount is never zero for a request that carries evidence, so it must be present.
+ * Thoughts bill as output (ai.google.dev/gemini-api/docs/pricing: "Output price (including
+ * thinking tokens)"). totalTokenCount must equal the parts, or none of them is trusted.
+ */
+function usageOf(raw) {
+    const usage = record(record(raw).usageMetadata);
+    const counted = (key) => {
+        const value = usage[key] ?? 0;
+        return count(value) ? value : null;
+    };
+    const prompt = usage.promptTokenCount;
+    const toolPrompt = counted("toolUsePromptTokenCount");
+    const candidates = counted("candidatesTokenCount");
+    const thoughts = counted("thoughtsTokenCount");
+    const cached = counted("cachedContentTokenCount");
+    if (!count(prompt) ||
+        toolPrompt === null ||
+        candidates === null ||
+        thoughts === null ||
+        cached === null)
+        return null;
+    const input = prompt + toolPrompt;
+    const output = candidates + thoughts;
+    if (cached > input ||
+        (usage.totalTokenCount !== undefined && usage.totalTokenCount !== input + output))
+        return null;
+    return { input, output, ...(cached > 0 ? { cachedInput: cached } : {}) };
+}
+/** The finish reasons that end a candidate without a usable answer, by what they mean. The
+ * provider declined to answer: its safety, recitation, language, blocklist or policy filters. */
+const DECLINED = new Set([
+    "SAFETY",
+    "RECITATION",
+    "LANGUAGE",
+    "BLOCKLIST",
+    "PROHIBITED_CONTENT",
+    "SPII",
+    "IMAGE_SAFETY",
+    "IMAGE_PROHIBITED_CONTENT",
+    "IMAGE_RECITATION",
+    "ESCALATION",
+    "PUP_LIMITED_DISABLED",
+]);
+/** The answer stopped at the output limit, or at a long-decode hop this one request never
+ * follows. */
+const CUT_OFF = new Set(["MAX_TOKENS", "CONTINUATION"]);
+/** One candidate whose only non-thought part is the JSON answer; anything else fails closed. */
+function parseGenerateContent(raw) {
+    const root = record(raw);
+    const base = { output: null, usage: usageOf(raw), dispatched: true };
+    if (record(root.promptFeedback).blockReason !== undefined)
+        return { ...base, status: "refused", errorCode: "refusal" };
+    const candidates = Array.isArray(root.candidates) ? root.candidates : [];
+    if (candidates.length !== 1)
+        return { ...base, status: "failed", errorCode: "invalid_response" };
+    const candidate = record(candidates[0]);
+    const reason = String(candidate.finishReason);
+    if (DECLINED.has(reason))
+        return { ...base, status: "refused", errorCode: "refusal" };
+    if (CUT_OFF.has(reason))
+        return { ...base, status: "incomplete", errorCode: "output_incomplete" };
+    const parts = record(candidate.content).parts;
+    // A thought summary is never part of the answer; thoughtSignature on a text part is metadata.
+    const answer = Array.isArray(parts) ? parts.filter((part) => record(part).thought !== true) : [];
+    const text = record(answer[0]).text;
+    if (reason !== "STOP" ||
+        answer.length !== 1 ||
+        typeof text !== "string" ||
+        Object.keys(record(answer[0])).some((key) => key !== "text" && key !== "thoughtSignature"))
+        return { ...base, status: "failed", errorCode: "invalid_response" };
+    try {
+        return { ...base, status: "completed", output: JSON.parse(text), errorCode: null };
+    }
+    catch {
+        return { ...base, status: "failed", errorCode: "invalid_response" };
+    }
+}
+/**
+ * One stateless request: no tools, the analysis's reasoning effort as its thinking level (the
+ * ThinkingLevel enum spells the same names in capitals), JSON constrained to the schema, the standard
+ * service tier, and `store: false` so the request stays out of the project's request logs. Each
+ * capture goes at MEDIA_RESOLUTION_HIGH, the setting the media-resolution guide recommends for
+ * image analysis, after a text part naming its evidence key.
+ */
+export const geminiWire = {
+    url: (model) => `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(model)}:generateContent`,
+    headers: (apiKey) => ({ "x-goog-api-key": apiKey, "Content-Type": "application/json" }),
+    body: (request) => {
+        const { schema, limits } = withoutArrayLimits(request.schema);
+        const limitText = limits.length === 0
+            ? ""
+            : `\n\nThe response schema sent with this request omits its array limits. Keep each array at or under its limit, by field path: ${limits.join("; ")}.`;
+        return {
+            systemInstruction: { parts: [{ text: request.instructions + limitText }] },
+            contents: [
+                {
+                    // The API leaves role optional outside a multi-turn conversation.
+                    parts: [
+                        { text: request.evidence },
+                        ...request.images.flatMap((image) => {
+                            const [, type, data] = INPUT_IMAGE_DATA_URL.exec(image.dataUrl);
+                            return [
+                                { text: JSON.stringify({ captureEvidenceId: image.evidenceId }) },
+                                {
+                                    inlineData: { mimeType: `image/${type}`, data },
+                                    mediaResolution: { level: "MEDIA_RESOLUTION_HIGH" },
+                                },
+                            ];
+                        }),
+                    ],
+                },
+            ],
+            generationConfig: {
+                candidateCount: 1,
+                maxOutputTokens: request.maxOutputTokens,
+                thinkingConfig: { thinkingLevel: request.reasoningEffort.toUpperCase() },
+                responseFormat: {
+                    text: { mimeType: "APPLICATION_JSON", schema },
+                },
+            },
+            serviceTier: "standard",
+            store: false,
+        };
+    },
+    parse: parseGenerateContent,
+};

package/dist/analysis/image-tokens.d.ts

@@ -1,3 +1,5 @@
-/** 2,500 patches × 1.2: what any image costs on these models when its size is unknown. */
-export declare const HIGH_DETAIL_IMAGE_TOKEN_CEILING = 3000;
+/** An input image the analysis providers accept; the groups are the image type and its base64 bytes. */
+export declare const INPUT_IMAGE_DATA_URL: RegExp;
+/** The most one image can cost on `model`, whatever its size. */
+export declare const imageTokenCeiling: (model: string) => number;
 export declare function highDetailImageTokens(model: string, dataUrl: string): number;

package/dist/analysis/image-tokens.js

@@ -1,22 +1,40 @@
+/** An input image the analysis providers accept; the groups are the image type and its base64 bytes. */
+export const INPUT_IMAGE_DATA_URL = /^data:image\/(png|jpeg|webp);base64,([A-Za-z0-9+/]+={0,2})$/;
 /**
- * Input tokens one image costs at `detail: "high"`, which is what the provider request sends.
+ * Input tokens one image costs at the detail the provider request sends: `detail: "high"` on
+ * OpenAI, MEDIA_RESOLUTION_HIGH on Gemini.
  *
  * OpenAI's vision guide (https://developers.openai.com/api/docs/guides/images-vision, read
  * 2026-09-30) prices these patch-based models by 32 px patches: ceil(width / 32) × ceil(height /
  * 32), scaled down to the model's high-detail patch budget, then ceil(patches × multiplier).
  * Scaling down only removes patches, so min(patches, budget) bounds the billed count from above.
  * The guide lists a 2,500-patch high budget and a 1.2 multiplier for each model below; its own
- * examples are 1024×1024 → 1,229 tokens and 2048×2048 → 3,000.
+ * examples are 1024×1024 → 1,229 tokens and 2048×2048 → 3,000. It does not list gpt-6-luna or
+ * gpt-6.1-sol (read 2026-10-21). Their entries copy gpt-6-astra's because OpenAI billed the same
+ * image tokens on all three on 2026-10-21, within the guide's one-token rounding.
  */
 const HIGH_DETAIL_SIZING = Object.freeze({
     "gpt-6-astra": { patchBudget: 2500, multiplierTenths: 12 },
+    "gpt-6.1-sol": { patchBudget: 2500, multiplierTenths: 12 },
+    "gpt-6-luna": { patchBudget: 2500, multiplierTenths: 12 },
     "gpt-5.6-sol": { patchBudget: 2500, multiplierTenths: 12 },
     "gpt-5.6-terra": { patchBudget: 2500, multiplierTenths: 12 },
     "gpt-5.6-luna": { patchBudget: 2500, multiplierTenths: 12 },
     "gpt-5.5": { patchBudget: 2500, multiplierTenths: 12 },
 });
 /** 2,500 patches × 1.2: what any image costs on these models when its size is unknown. */
-export const HIGH_DETAIL_IMAGE_TOKEN_CEILING = 3000;
+const HIGH_DETAIL_IMAGE_TOKEN_CEILING = 3000;
+/**
+ * Gemini bills an image by its media resolution, not its size. The provider sends every capture at
+ * MEDIA_RESOLUTION_HIGH, which the media-resolution guide
+ * (ai.google.dev/gemini-api/docs/media-resolution, read 2026-10-21) gives as at most 1,120 tokens
+ * for an image on Gemini 3 and Gemini 4 models. A 1x1 PNG at that setting was billed 1,089.
+ */
+const GEMINI_HIGH_RESOLUTION_IMAGE_TOKENS = Object.freeze({
+    "gemini-3.8-flash": 1120,
+});
+/** The most one image can cost on `model`, whatever its size. */
+export const imageTokenCeiling = (model) => GEMINI_HIGH_RESOLUTION_IMAGE_TOKENS[model] ?? HIGH_DETAIL_IMAGE_TOKEN_CEILING;
 const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
 /** Width and height from a PNG data URL's IHDR chunk; undefined for anything else. */
 function pngDimensions(dataUrl) {
@@ -31,6 +49,9 @@ function pngDimensions(dataUrl) {
     return width > 0 && height > 0 ? { width, height } : undefined;
 }
 export function highDetailImageTokens(model, dataUrl) {
+    const fixed = GEMINI_HIGH_RESOLUTION_IMAGE_TOKENS[model];
+    if (fixed !== undefined)
+        return fixed;
     const sizing = HIGH_DETAIL_SIZING[model];
     const size = sizing === undefined ? undefined : pngDimensions(dataUrl);
     if (sizing === undefined || size === undefined)

package/dist/analysis/job.d.ts

@@ -53,6 +53,7 @@ declare const jobSchema: z.ZodObject<{
         AUTOMATIC_ANALYSIS_CLEANUP_UNCONFIRMED: "AUTOMATIC_ANALYSIS_CLEANUP_UNCONFIRMED";
         AUTOMATIC_ANALYSIS_CODEX_UNAVAILABLE: "AUTOMATIC_ANALYSIS_CODEX_UNAVAILABLE";
         AUTOMATIC_ANALYSIS_FAILED: "AUTOMATIC_ANALYSIS_FAILED";
+        AUTOMATIC_ANALYSIS_GEMINI_KEY_MISSING: "AUTOMATIC_ANALYSIS_GEMINI_KEY_MISSING";
         AUTOMATIC_ANALYSIS_KEY_MISSING: "AUTOMATIC_ANALYSIS_KEY_MISSING";
         AUTOMATIC_ANALYSIS_LIMITATIONS: "AUTOMATIC_ANALYSIS_LIMITATIONS";
         AUTOMATIC_ANALYSIS_NO_PARTICIPANT_EVIDENCE: "AUTOMATIC_ANALYSIS_NO_PARTICIPANT_EVIDENCE";

package/dist/analysis/job.js

@@ -35,6 +35,7 @@ const reasons = [
     "AUTOMATIC_ANALYSIS_OUTCOME_UNKNOWN",
     "AUTOMATIC_ANALYSIS_SOURCE_UNAVAILABLE",
     "AUTOMATIC_ANALYSIS_KEY_MISSING",
+    "AUTOMATIC_ANALYSIS_GEMINI_KEY_MISSING",
     "AUTOMATIC_ANALYSIS_CODEX_UNAVAILABLE",
     "AUTOMATIC_ANALYSIS_ADMISSION_REFUSED",
     "AUTOMATIC_ANALYSIS_BUSY",

package/dist/analysis/models.d.ts

@@ -0,0 +1,12 @@
+import type { ReasoningEffort } from "../actors/reasoning-effort.js";
+import type { AnalysisApiVendor } from "./provider.js";
+import type { AnalysisConfig } from "./types.js";
+export declare const SUPPORTED_ANALYSIS_MODELS: readonly string[];
+export declare const GEMINI_ANALYSIS_MODELS: readonly string[];
+/** Whether the API analyst `provider` (omitted is OpenAI) analyzes with `model`. */
+export declare const isSupportedAnalysisModel: (model: string, provider?: AnalysisApiVendor) => boolean;
+/** The reasoning efforts `model` accepts from `provider`, least first; empty for an unknown model. */
+export declare const analysisEfforts: (model: string, provider?: AnalysisApiVendor) => readonly ReasoningEffort[];
+/** The effort an analysis runs at: the declared one, high for an API analysis that declares none,
+ * and the Codex account's fixed effort. */
+export declare function analysisEffort(config: AnalysisConfig): ReasoningEffort;

package/dist/analysis/models.js

@@ -0,0 +1,47 @@
+// The models each API analyst runs, and the reasoning efforts each model accepts. Config parsing,
+// admission, the CLI help and the wire formats all read this one table.
+/**
+ * `reasoning.effort` values from each model's page under developers.openai.com/api/docs/models
+ * (read 2026-10-21). None of them lists `minimal`; gpt-6-astra and gpt-6.1-sol also refuse `none`.
+ */
+const OPENAI_MODELS = {
+    "gpt-6-astra": ["low", "medium", "high", "xhigh", "max"],
+    "gpt-6.1-sol": ["low", "medium", "high", "xhigh", "max"],
+    "gpt-6-luna": ["none", "low", "medium", "high", "xhigh", "max"],
+    "gpt-5.5": ["none", "low", "medium", "high", "xhigh"],
+    "gpt-5.6": ["none", "low", "medium", "high", "xhigh", "max"],
+    "gpt-5.6-sol": ["none", "low", "medium", "high", "xhigh", "max"],
+    "gpt-5.6-terra": ["none", "low", "medium", "high", "xhigh", "max"],
+    "gpt-5.6-luna": ["none", "low", "medium", "high", "xhigh", "max"],
+};
+/**
+ * Gemini models that completed a live analysis, with the `thinkingLevel` values the thinking guide
+ * lists for each (ai.google.dev/gemini-api/docs/generate-content/thinking, read 2026-10-21):
+ * gemini-3.8-flash answers `minimal` with an error. Each model's page under
+ * ai.google.dev/gemini-api/docs/models also lists image input and JSON-schema output for
+ * gemini-3.5-flash-lite, gemini-3-flash-preview and gemini-4-argon; they join this table once a
+ * live analysis on each completes.
+ */
+const GEMINI_MODELS = {
+    "gemini-3.8-flash": ["low", "medium", "high"],
+};
+const MODELS = { openai: OPENAI_MODELS, gemini: GEMINI_MODELS };
+export const SUPPORTED_ANALYSIS_MODELS = Object.freeze(Object.keys(OPENAI_MODELS));
+export const GEMINI_ANALYSIS_MODELS = Object.freeze(Object.keys(GEMINI_MODELS));
+/** Whether the API analyst `provider` (omitted is OpenAI) analyzes with `model`. */
+export const isSupportedAnalysisModel = (model, provider = "openai") => Object.hasOwn(MODELS[provider], model);
+/** The reasoning efforts `model` accepts from `provider`, least first; empty for an unknown model. */
+export const analysisEfforts = (model, provider = "openai") => Object.hasOwn(MODELS[provider], model) ? MODELS[provider][model] : [];
+/**
+ * The effort an API analysis runs at when its configuration declares none. Every saved analysis
+ * without `reasoningEffort` ran at this effort, so it stays high: a different default must be
+ * written into the configuration it resolves, where it also changes the configuration's hash.
+ */
+const UNDECLARED_EFFORT = "high";
+/** The effort an analysis runs at: the declared one, high for an API analysis that declares none,
+ * and the Codex account's fixed effort. */
+export function analysisEffort(config) {
+    if (config.provider === "codex")
+        return config.identity.reasoningEffort;
+    return config.reasoningEffort ?? UNDECLARED_EFFORT;
+}

package/dist/analysis/openai-wire.d.ts

@@ -0,0 +1,6 @@
+import type { AnalysisProviderResult, AnalysisWire } from "./provider.js";
+/** Text and usage wire shapes reuse the captured closing-report contract; refusal fails closed. */
+export declare function parseAnalysisResponse(raw: unknown): AnalysisProviderResult;
+/** One stateless request: no stored response, no tools, the analysis's reasoning effort, strict
+ * schema. */
+export declare const openaiWire: AnalysisWire;

package/dist/analysis/openai-wire.js

@@ -0,0 +1,102 @@
+// The OpenAI Responses API wire format of one analysis request: what the request body says and how
+// a response becomes an AnalysisProviderResult. provider.ts owns the transport around it.
+import { OPENAI_RESPONSES_URL } from "../actors/openai-endpoint.js";
+import { isRecord } from "../run/type-guards.js";
+const record = (value) => (isRecord(value) ? value : {});
+const count = (value) => Number.isSafeInteger(value) && value >= 0 && value <= 1e12;
+function usageOf(raw) {
+    const usage = record(record(raw).usage);
+    const details = record(usage.input_tokens_details);
+    const input = usage.input_tokens;
+    const output = usage.output_tokens;
+    const cachedInput = details.cached_tokens;
+    const cacheWriteInput = details.cache_write_tokens;
+    if (!count(input) ||
+        !count(output) ||
+        (cachedInput !== undefined && !count(cachedInput)) ||
+        (cacheWriteInput !== undefined && !count(cacheWriteInput)) ||
+        (cachedInput ?? 0) + (cacheWriteInput ?? 0) >
+            input)
+        return null;
+    return {
+        input,
+        output,
+        ...(cachedInput === undefined ? {} : { cachedInput: cachedInput }),
+        ...(cacheWriteInput === undefined ? {} : { cacheWriteInput: cacheWriteInput }),
+    };
+}
+/** Text and usage wire shapes reuse the captured closing-report contract; refusal fails closed. */
+export function parseAnalysisResponse(raw) {
+    const root = record(raw);
+    const usage = usageOf(raw);
+    const output = Array.isArray(root.output) ? root.output : [];
+    const contents = output
+        .filter((item) => record(item).type === "message")
+        .flatMap((item) => Array.isArray(record(item).content) ? record(item).content : []);
+    const base = { output: null, usage, dispatched: true };
+    if (contents.some((item) => record(item).type === "refusal")) {
+        return { ...base, status: "refused", errorCode: "refusal" };
+    }
+    if (root.status === "incomplete")
+        return { ...base, status: "incomplete", errorCode: "output_incomplete" };
+    if (root.status !== "completed" ||
+        output.some((item) => !["message", "reasoning"].includes(String(record(item).type)))) {
+        return { ...base, status: "failed", errorCode: "invalid_response" };
+    }
+    // A single JSON answer is expected. Do not concatenate multiple answer objects or expose a
+    // refusal, reasoning item, or incomplete message as the report's prose.
+    const messages = output.filter((item) => record(item).type === "message");
+    const texts = contents.filter((item) => record(item).type === "output_text");
+    if (messages.length !== 1 ||
+        record(messages[0]).status !== "completed" ||
+        record(messages[0]).role !== "assistant" ||
+        texts.length !== 1 ||
+        contents.length !== 1 ||
+        typeof record(texts[0]).text !== "string") {
+        return { ...base, status: "failed", errorCode: "invalid_response" };
+    }
+    try {
+        return {
+            ...base,
+            status: "completed",
+            output: JSON.parse(record(texts[0]).text),
+            errorCode: null,
+        };
+    }
+    catch {
+        return { ...base, status: "failed", errorCode: "invalid_response" };
+    }
+}
+/** One stateless request: no stored response, no tools, the analysis's reasoning effort, strict
+ * schema. */
+export const openaiWire = {
+    url: () => OPENAI_RESPONSES_URL,
+    headers: (apiKey) => ({ Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" }),
+    body: (request) => ({
+        model: request.model,
+        instructions: request.instructions,
+        input: [
+            {
+                role: "user",
+                content: [
+                    { type: "input_text", text: request.evidence },
+                    ...request.images.flatMap((image) => [
+                        { type: "input_text", text: JSON.stringify({ captureEvidenceId: image.evidenceId }) },
+                        { type: "input_image", image_url: image.dataUrl, detail: "high" },
+                    ]),
+                ],
+            },
+        ],
+        store: false,
+        tools: [],
+        tool_choice: "none",
+        truncation: "disabled",
+        service_tier: "default",
+        reasoning: { effort: request.reasoningEffort },
+        max_output_tokens: request.maxOutputTokens,
+        text: {
+            format: { type: "json_schema", name: "study_analysis", strict: true, schema: request.schema },
+        },
+    }),
+    parse: parseAnalysisResponse,
+};

package/dist/analysis/provider.d.ts

@@ -1,4 +1,5 @@
 import { type Dispatcher } from "undici";
+import type { ReasoningEffort } from "../actors/reasoning-effort.js";
 /** Deliberately separate from the stateful computer-use actor: one request, no tools or retries. */
 export interface AnalysisProviderRequest {
     model: string;
@@ -10,10 +11,13 @@ export interface AnalysisProviderRequest {
     }[];
     schema: Record<string, unknown>;
     maxOutputTokens: number | null;
+    /** The effort the analysis runs at (models.ts analysisEffort). The Codex account analyst runs
+     * its fixed low effort, which this then names. */
+    reasoningEffort: ReasoningEffort;
     timeoutMs: number;
     signal?: AbortSignal;
 }
-interface AnalysisTokenUsage {
+export interface AnalysisTokenUsage {
     input: number;
     output: number;
     cachedInput?: number;
@@ -40,10 +44,6 @@ export interface AnalysisProviderResult {
     protocolAdditions?: readonly string[];
 }
 export type AnalysisProvider = (request: AnalysisProviderRequest) => Promise<AnalysisProviderResult>;
-/** An input image the provider accepts; the groups are the image type and its base64 bytes. */
-export declare const INPUT_IMAGE_DATA_URL: RegExp;
-/** Text and usage wire shapes reuse the captured closing-report contract; refusal fails closed. */
-export declare function parseAnalysisResponse(raw: unknown): AnalysisProviderResult;
 /** The part of fetch this provider uses; undici's fetch and test doubles both satisfy it. */
 export type AnalysisFetch = (url: string, init: {
     method: "POST";
@@ -62,9 +62,21 @@ export type AnalysisFetch = (url: string, init: {
     status: number;
     body: ReadableStream<Uint8Array> | null;
 }>;
-/** No alternate endpoint or env-derived base URL: evidence and credentials have one destination. */
+/** The analysts humanish calls over HTTP with an API key. Codex runs through its own CLI. */
+export type AnalysisApiVendor = "openai" | "gemini";
+/** One vendor's wire format. The transport sends `body` to `url` with `headers` and gives `parse`
+ * the response JSON only after a 2xx status, within the byte cap and the deadline. */
+export interface AnalysisWire {
+    /** A fixed endpoint: never derived from env, so evidence and credentials have one destination. */
+    url(model: string): string;
+    headers(apiKey: string): Record<string, string>;
+    body(request: AnalysisProviderRequest): unknown;
+    parse(raw: unknown): AnalysisProviderResult;
+}
+/** One request to the vendor's fixed endpoint, never retried and never sent elsewhere. */
 export declare function createAnalysisProvider(options: {
     apiKey: string;
+    /** Omitted is OpenAI, the analyst humanish has always called. */
+    vendor?: AnalysisApiVendor;
     fetchFn?: AnalysisFetch;
 }): AnalysisProvider;
-export {};

package/dist/analysis/provider.js

@@ -1,13 +1,17 @@
+// The analysis provider seam and the HTTP transport its API adapters share. Each API vendor owns
+// only its wire format (gemini-wire.ts, openai-wire.ts): the endpoint, the request body, and how a
+// response becomes a result. The transport owns what must hold for every vendor: one fixed endpoint
+// per vendor, request and response byte caps, the caller's wall-clock deadline, no retry, and a
+// closed error vocabulary that never carries provider error prose. The Codex account analyst is
+// the third adapter at the same seam (restricted-codex.ts).
 import { Agent, fetch as undiciFetch } from "undici";
-import { OPENAI_RESPONSES_URL } from "../actors/openai-endpoint.js";
+import { isRecord } from "../run/type-guards.js";
+import { INPUT_IMAGE_DATA_URL } from "./image-tokens.js";
+import { geminiWire } from "./gemini-wire.js";
+import { openaiWire } from "./openai-wire.js";
 const MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
 const MAX_REQUEST_BYTES = 32 * 1024 * 1024;
-/** An input image the provider accepts; the groups are the image type and its base64 bytes. */
-export const INPUT_IMAGE_DATA_URL = /^data:image\/(png|jpeg|webp);base64,([A-Za-z0-9+/]+={0,2})$/;
-const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
-    ? value
-    : {};
-const count = (value) => Number.isSafeInteger(value) && value >= 0 && value <= 1e12;
+const record = (value) => (isRecord(value) ? value : {});
 /** Undici's fetch has a separate response-header deadline. The caller's wall-clock
  * deadline must govern this one request, including uploads and body reads, without
  * changing transport behavior for other requests in the process. The agent is used with
@@ -41,72 +45,14 @@ function networkErrorCode(error) {
     }
     return "provider_network_error";
 }
-function usageOf(raw) {
-    const usage = record(record(raw).usage);
-    const details = record(usage.input_tokens_details);
-    const input = usage.input_tokens;
-    const output = usage.output_tokens;
-    const cachedInput = details.cached_tokens;
-    const cacheWriteInput = details.cache_write_tokens;
-    if (!count(input) ||
-        !count(output) ||
-        (cachedInput !== undefined && !count(cachedInput)) ||
-        (cacheWriteInput !== undefined && !count(cacheWriteInput)) ||
-        (cachedInput ?? 0) + (cacheWriteInput ?? 0) >
-            input)
-        return null;
-    return {
-        input,
-        output,
-        ...(cachedInput === undefined ? {} : { cachedInput: cachedInput }),
-        ...(cacheWriteInput === undefined ? {} : { cacheWriteInput: cacheWriteInput }),
-    };
-}
-/** Text and usage wire shapes reuse the captured closing-report contract; refusal fails closed. */
-export function parseAnalysisResponse(raw) {
-    const root = record(raw);
-    const usage = usageOf(raw);
-    const output = Array.isArray(root.output) ? root.output : [];
-    const contents = output
-        .filter((item) => record(item).type === "message")
-        .flatMap((item) => Array.isArray(record(item).content) ? record(item).content : []);
-    const base = { output: null, usage, dispatched: true };
-    if (contents.some((item) => record(item).type === "refusal")) {
-        return { ...base, status: "refused", errorCode: "refusal" };
-    }
-    if (root.status === "incomplete")
-        return { ...base, status: "incomplete", errorCode: "output_incomplete" };
-    if (root.status !== "completed" ||
-        output.some((item) => !["message", "reasoning"].includes(String(record(item).type)))) {
-        return { ...base, status: "failed", errorCode: "invalid_response" };
-    }
-    // A single JSON answer is expected. Do not concatenate multiple answer objects or expose a
-    // refusal, reasoning item, or incomplete message as the report's prose.
-    const messages = output.filter((item) => record(item).type === "message");
-    const texts = contents.filter((item) => record(item).type === "output_text");
-    if (messages.length !== 1 ||
-        record(messages[0]).status !== "completed" ||
-        record(messages[0]).role !== "assistant" ||
-        texts.length !== 1 ||
-        contents.length !== 1 ||
-        typeof record(texts[0]).text !== "string") {
-        return { ...base, status: "failed", errorCode: "invalid_response" };
-    }
-    try {
-        return {
-            ...base,
-            status: "completed",
-            output: JSON.parse(record(texts[0]).text),
-            errorCode: null,
-        };
-    }
-    catch {
-        return { ...base, status: "failed", errorCode: "invalid_response" };
-    }
-}
-/** No alternate endpoint or env-derived base URL: evidence and credentials have one destination. */
+const WIRES = {
+    openai: openaiWire,
+    gemini: geminiWire,
+};
+/** One request to the vendor's fixed endpoint, never retried and never sent elsewhere. */
 export function createAnalysisProvider(options) {
     const fetchFn = options.fetchFn ?? undiciFetch;
+    const wire = WIRES[options.vendor ?? "openai"];
     return async (request) => {
         const failure = (errorCode, dispatched, status = "failed") => ({
             status,
@@ -130,33 +76,7 @@ export function createAnalysisProvider(options) {
             request.images.some((image) => !INPUT_IMAGE_DATA_URL.test(image.dataUrl))) {
             return failure("invalid_request", false);
         }
-        const content = [
-            { type: "input_text", text: request.evidence },
-            ...request.images.flatMap((image) => [
-                { type: "input_text", text: JSON.stringify({ captureEvidenceId: image.evidenceId }) },
-                { type: "input_image", image_url: image.dataUrl, detail: "high" },
-            ]),
-        ];
-        const body = JSON.stringify({
-            model: request.model,
-            instructions: request.instructions,
-            input: [{ role: "user", content }],
-            store: false,
-            tools: [],
-            tool_choice: "none",
-            truncation: "disabled",
-            service_tier: "default",
-            reasoning: { effort: "high" },
-            max_output_tokens: request.maxOutputTokens,
-            text: {
-                format: {
-                    type: "json_schema",
-                    name: "study_analysis",
-                    strict: true,
-                    schema: request.schema,
-                },
-            },
-        });
+        const body = JSON.stringify(wire.body(request));
         if (Buffer.byteLength(body) > MAX_REQUEST_BYTES)
             return failure("invalid_request", false);
         const controller = new AbortController();
@@ -173,11 +93,11 @@ export function createAnalysisProvider(options) {
             if (request.signal?.aborted)
                 return failure("cancelled", false, "cancelled");
             dispatched = true;
-            const response = await fetchFn(OPENAI_RESPONSES_URL, {
+            const response = await fetchFn(wire.url(request.model), {
                 method: "POST",
                 redirect: "error",
                 signal: controller.signal,
-                headers: { Authorization: `Bearer ${options.apiKey}`, "Content-Type": "application/json" },
+                headers: wire.headers(options.apiKey),
                 body,
                 dispatcher,
                 timeout: false,
@@ -211,7 +131,7 @@ export function createAnalysisProvider(options) {
             if (controller.signal.aborted)
                 return failure(timedOut ? "timeout" : "cancelled", true, timedOut ? "timed_out" : "cancelled");
             try {
-                return parseAnalysisResponse(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+                return wire.parse(JSON.parse(Buffer.concat(chunks).toString("utf8")));
             }
             catch {
                 return failure("invalid_response", true);

package/dist/analysis/responses.d.ts

@@ -15,5 +15,8 @@ export declare function checkProviderAnalysis(input: AnalysisInput, value: unkno
  * each response as its own request, since the long-context tier re-prices one request at a time.
  */
 export declare function recordProviderUsage(artifact: AnalysisArtifact, config: AnalysisConfig, responses: readonly AnalysisProviderResult[]): void;
+/** The HTTP status an API analyst answered, for the attempt's warnings. The status code is the only
+ * part of the answer kept: the provider's error text may echo evidence or credentials. */
+export declare function httpStatusWarning(config: AnalysisConfig, response: AnalysisProviderResult): string | undefined;
 /** The warnings a Codex response carries about its CLI release and protocol. */
 export declare function codexWarnings(config: AnalysisConfig, response: AnalysisProviderResult): string[];