humanish 0.105.0 → 0.106.0

package/dist/analysis/job.js

@@ -0,0 +1,311 @@
+import { randomUUID } from "node:crypto";
+import { lstat, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { physicalCwdOf, runIdOf, validatePreparedRunRootIdentity, } from "../run/paths.js";
+import { assertPreparedSelectedOutputDirectory, bindExistingManagedHumanishOutputDirectory, prepareContainedOutputDirectoryRoot, writeContainedOutputFile, } from "../run/contained-output.js";
+import { pathMissing, readBoundedStudyFile } from "../run/study-files.js";
+import { containsSensitive } from "../evidence/redaction.js";
+import { readStudyAnalysisVersion } from "./store.js";
+import { readStudyAnalysisExecution } from "./store-executions.js";
+import { hashAnalysisValue } from "./validation.js";
+import { ANALYSIS_ID_PATTERN, SHA256_HEX_PATTERN } from "./types.js";
+export const AUTOMATIC_ANALYSIS_DIRECTORY = "analysis-automatic";
+const AUTOMATIC_ANALYSIS_SCHEMA = "humanish.automatic-study-analysis.v1";
+export const AUTOMATIC_ANALYSIS_STALE_MS = 15_000;
+/** Execution metadata only. Never a participant outcome or permission to dispatch. */
+const JOB_STATES = [
+    "queued",
+    "running",
+    "complete",
+    "partial",
+    "failed",
+    "cancelled",
+    "skipped",
+    "unknown",
+];
+const JOB_FILE = "job.json";
+const CANCEL_FILE = "cancel.json";
+const MAX_JOB_BYTES = 8192;
+const MAX_CANCEL_BYTES = 1024;
+const CANCEL_SCHEMA = "humanish.automatic-study-analysis-cancellation.v1";
+const reasons = [
+    "AUTOMATIC_ANALYSIS_ALREADY_REQUESTED",
+    "AUTOMATIC_ANALYSIS_STORAGE_UNAVAILABLE",
+    "AUTOMATIC_ANALYSIS_OUTCOME_UNKNOWN",
+    "AUTOMATIC_ANALYSIS_SOURCE_UNAVAILABLE",
+    "AUTOMATIC_ANALYSIS_KEY_MISSING",
+    "AUTOMATIC_ANALYSIS_CODEX_UNAVAILABLE",
+    "AUTOMATIC_ANALYSIS_ADMISSION_REFUSED",
+    "AUTOMATIC_ANALYSIS_BUSY",
+    "AUTOMATIC_ANALYSIS_CANCELLED",
+    "AUTOMATIC_ANALYSIS_CANCELLATION_UNAVAILABLE",
+    "AUTOMATIC_ANALYSIS_FAILED",
+    "AUTOMATIC_ANALYSIS_PUBLICATION_FAILED",
+    "AUTOMATIC_ANALYSIS_REUSED",
+    "AUTOMATIC_ANALYSIS_LIMITATIONS",
+    "AUTOMATIC_ANALYSIS_ADMISSION_EXCEEDED",
+    "AUTOMATIC_ANALYSIS_ACTOR_CANCELLED",
+    "AUTOMATIC_ANALYSIS_NO_PARTICIPANT_EVIDENCE",
+];
+const id = z.string().regex(ANALYSIS_ID_PATTERN);
+const date = z.iso.datetime();
+const digest = z.string().regex(SHA256_HEX_PATTERN);
+const jobSchema = z.strictObject({
+    schema: z.literal(AUTOMATIC_ANALYSIS_SCHEMA),
+    runId: id,
+    claimId: z.uuid(),
+    attemptId: id,
+    state: z.enum(JOB_STATES),
+    analysisId: id.nullable(),
+    reason: z.enum(reasons).nullable(),
+    createdAt: date,
+    updatedAt: date,
+    configDigest: digest,
+    promptVersion: z.string().regex(/^[A-Za-z0-9_.-]{1,80}$/),
+    sourceRunSha256: digest.nullable(),
+    inputDigest: digest.nullable(),
+    analysisSha256: digest.nullable(),
+    receiptSha256: digest.nullable(),
+    startedAt: date.nullable(),
+    finishedAt: date.nullable(),
+});
+const cancelSchema = z.strictObject({
+    schema: z.literal(CANCEL_SCHEMA),
+    runId: id,
+    claimId: z.uuid(),
+    requestedAt: date,
+});
+const pending = (state) => state === "queued" || state === "running";
+const iso = () => new Date().toISOString();
+const unknown = (updatedAt = iso()) => ({
+    state: "unknown",
+    analysisId: null,
+    reason: "AUTOMATIC_ANALYSIS_OUTCOME_UNKNOWN",
+    updatedAt,
+});
+function parseJob(bytes, runId) {
+    const record = jobSchema.parse(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)));
+    if (containsSensitive(JSON.stringify(record)) ||
+        record.runId !== runId ||
+        Date.parse(record.updatedAt) < Date.parse(record.createdAt) ||
+        (pending(record.state) && record.finishedAt !== null) ||
+        (!pending(record.state) && record.finishedAt === null) ||
+        (record.analysisId !== null &&
+            record.reason !== "AUTOMATIC_ANALYSIS_REUSED" &&
+            record.analysisId !== record.attemptId) ||
+        (record.reason === "AUTOMATIC_ANALYSIS_REUSED" &&
+            (!["complete", "partial"].includes(record.state) ||
+                record.startedAt !== null ||
+                record.analysisId === null)) ||
+        (record.state === "running" && record.startedAt === null) ||
+        (record.startedAt !== null && Date.parse(record.startedAt) < Date.parse(record.createdAt)) ||
+        (record.finishedAt !== null && Date.parse(record.finishedAt) < Date.parse(record.createdAt))) {
+        throw new Error("AUTOMATIC_ANALYSIS_STORAGE_UNAVAILABLE");
+    }
+    return record;
+}
+/** Also guards direct HTML projection callers, not only the contained-file reader. */
+export function projectAutomaticStudyAnalysisView(value) {
+    if (value === undefined)
+        return undefined;
+    const parsed = jobSchema
+        .pick({ state: true, analysisId: true, reason: true, updatedAt: true })
+        .safeParse(value);
+    if (!parsed.success || containsSensitive(JSON.stringify(parsed.data)))
+        return unknown();
+    return parsed.data;
+}
+async function bindJob(prepared) {
+    await validatePreparedRunRootIdentity(prepared);
+    const cwd = physicalCwdOf(prepared);
+    const root = await bindExistingManagedHumanishOutputDirectory(cwd, "runs", runIdOf(prepared), AUTOMATIC_ANALYSIS_DIRECTORY);
+    return root ? Object.freeze({ ...root, parentRun: prepared }) : null;
+}
+/** Minimal historical accounting, without source validation, execution or liveness inference. */
+export async function readAutomaticStudyAnalysisAccounting(prepared) {
+    try {
+        const root = await bindJob(prepared);
+        if (!root)
+            return undefined;
+        const bytes = await readBoundedStudyFile(root, JOB_FILE, MAX_JOB_BYTES);
+        if (!bytes)
+            return "unknown";
+        const record = parseJob(bytes, runIdOf(prepared));
+        return {
+            attemptId: record.attemptId,
+            analysisId: record.analysisId,
+            started: record.startedAt !== null,
+            reused: record.reason === "AUTOMATIC_ANALYSIS_REUSED",
+            uncertain: record.state === "unknown",
+        };
+    }
+    catch {
+        return "unknown";
+    }
+}
+/** Read-only projection. A stale timestamp or persisted claim never authorizes execution. */
+export async function readAutomaticStudyAnalysisPrepared(prepared, now = Date.now()) {
+    try {
+        const root = await bindJob(prepared);
+        if (!root) {
+            const missing = await pathMissing(path.join(prepared.physicalRunRoot, AUTOMATIC_ANALYSIS_DIRECTORY));
+            return missing ? undefined : unknown();
+        }
+        const bytes = await readBoundedStudyFile(root, JOB_FILE, MAX_JOB_BYTES);
+        if (!bytes)
+            return unknown();
+        const record = parseJob(bytes, runIdOf(prepared));
+        const view = {
+            state: record.state,
+            analysisId: record.analysisId,
+            reason: record.reason,
+            updatedAt: record.updatedAt,
+        };
+        const updated = Date.parse(record.updatedAt);
+        if (updated > now || (pending(record.state) && now - updated > AUTOMATIC_ANALYSIS_STALE_MS)) {
+            return { ...view, state: "unknown", reason: "AUTOMATIC_ANALYSIS_OUTCOME_UNKNOWN" };
+        }
+        if (!(await terminalResultMatches(prepared, record)))
+            return { ...view, state: "unknown", reason: "AUTOMATIC_ANALYSIS_OUTCOME_UNKNOWN" };
+        return view;
+    }
+    catch {
+        return unknown();
+    }
+}
+async function terminalResultMatches(prepared, record) {
+    if (pending(record.state) || record.state === "unknown" || record.state === "skipped")
+        return true;
+    if (record.analysisId === null)
+        return record.state === "cancelled" || record.state === "failed";
+    const matches = (value) => value.id === record.analysisId &&
+        value.runId === record.runId &&
+        value.sourceRunSha256 === record.sourceRunSha256 &&
+        value.inputDigest === record.inputDigest &&
+        value.configDigest === record.configDigest &&
+        value.promptVersion === record.promptVersion;
+    const receipt = await readStudyAnalysisExecution(prepared, record.analysisId);
+    if (!receipt || !matches(receipt) || hashAnalysisValue(receipt) !== record.receiptSha256)
+        return false;
+    if (record.state === "failed" && record.reason === "AUTOMATIC_ANALYSIS_PUBLICATION_FAILED")
+        return true;
+    if (receipt.status !== record.state)
+        return false;
+    if (record.state === "failed" || record.state === "cancelled")
+        return true;
+    const entry = await readStudyAnalysisVersion(prepared, record.analysisId);
+    return (entry?.state === "ready" &&
+        entry.analysis !== null &&
+        matches(entry.analysis) &&
+        entry.analysis.status === record.state &&
+        hashAnalysisValue(entry.analysis) === record.analysisSha256);
+}
+/** The directory is permanent, including after interrupted/failed writes. Never re-open it as a writer. */
+export async function claimAutomaticStudyAnalysis(prepared, metadata) {
+    await validatePreparedRunRootIdentity(prepared);
+    const target = path.join(prepared.physicalRunRoot, AUTOMATIC_ANALYSIS_DIRECTORY);
+    try {
+        await mkdir(target, { mode: 0o700 });
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            return null;
+        throw error;
+    }
+    const identity = await lstat(target, { bigint: true });
+    const root = await prepareContainedOutputDirectoryRoot(prepared, AUTOMATIC_ANALYSIS_DIRECTORY);
+    if (root.identity.dev !== identity.dev ||
+        root.identity.ino !== identity.ino ||
+        root.identity.birthtimeNs !== identity.birthtimeNs) {
+        throw new Error("AUTOMATIC_ANALYSIS_STORAGE_UNAVAILABLE");
+    }
+    const createdAt = iso();
+    let record = {
+        schema: AUTOMATIC_ANALYSIS_SCHEMA,
+        runId: runIdOf(prepared),
+        claimId: randomUUID(),
+        attemptId: `analysis-${randomUUID()}`,
+        state: "queued",
+        analysisId: null,
+        reason: null,
+        createdAt,
+        updatedAt: createdAt,
+        ...metadata,
+        sourceRunSha256: null,
+        inputDigest: null,
+        analysisSha256: null,
+        receiptSha256: null,
+        startedAt: null,
+        finishedAt: null,
+    };
+    let writes = Promise.resolve();
+    const write = async (next) => {
+        const bytes = Buffer.from(JSON.stringify(next) + "\n");
+        parseJob(bytes, record.runId);
+        if (bytes.length > MAX_JOB_BYTES)
+            throw new Error("AUTOMATIC_ANALYSIS_STORAGE_UNAVAILABLE");
+        await writeContainedOutputFile(root, JOB_FILE, bytes);
+        record = next;
+    };
+    await write(record);
+    const update = (change) => {
+        writes = writes.then(async () => {
+            if (!pending(record.state))
+                return;
+            const now = iso();
+            const state = change.state ?? record.state;
+            await write({
+                ...record,
+                ...change,
+                state,
+                updatedAt: now,
+                finishedAt: pending(state) ? null : now,
+            });
+        });
+        return writes;
+    };
+    return {
+        attemptId: record.attemptId,
+        update,
+        touch: () => update({}),
+        async cancellationRequested() {
+            await assertPreparedSelectedOutputDirectory(root);
+            const bytes = await readBoundedStudyFile(root, CANCEL_FILE, MAX_CANCEL_BYTES);
+            if (!bytes) {
+                if (!(await pathMissing(path.join(root.physicalPath, CANCEL_FILE))))
+                    throw new Error("AUTOMATIC_ANALYSIS_CANCELLATION_UNAVAILABLE");
+                return false;
+            }
+            const cancel = cancelSchema.parse(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)));
+            if (cancel.runId !== record.runId || cancel.claimId !== record.claimId)
+                throw new Error("AUTOMATIC_ANALYSIS_CANCELLATION_UNAVAILABLE");
+            return true;
+        },
+    };
+}
+/** A scoped cancellation request, never a PID signal and never permission to create a new job. */
+export async function requestAutomaticStudyAnalysisCancellationPrepared(prepared) {
+    try {
+        const root = await bindJob(prepared);
+        if (!root)
+            return { requested: false, reason: "AUTOMATIC_ANALYSIS_SOURCE_UNAVAILABLE" };
+        const bytes = await readBoundedStudyFile(root, JOB_FILE, MAX_JOB_BYTES);
+        if (!bytes)
+            throw new Error("Unavailable job.");
+        const record = parseJob(bytes, runIdOf(prepared));
+        if (!pending(record.state))
+            return { requested: false, reason: null };
+        const cancellation = {
+            schema: CANCEL_SCHEMA,
+            runId: record.runId,
+            claimId: record.claimId,
+            requestedAt: iso(),
+        };
+        await writeContainedOutputFile(root, CANCEL_FILE, JSON.stringify(cancellation) + "\n");
+        return { requested: true, reason: null };
+    }
+    catch {
+        return { requested: false, reason: "AUTOMATIC_ANALYSIS_CANCELLATION_UNAVAILABLE" };
+    }
+}

package/dist/analysis/load.d.ts

@@ -0,0 +1,3 @@
+import type { PreparedRunArtifactPaths } from "../run/paths.js";
+import type { LoadedAnalysis } from "./types.js";
+export declare function loadStudyAnalysis(prepared: PreparedRunArtifactPaths, id?: string): Promise<LoadedAnalysis>;

package/dist/analysis/load.js

@@ -0,0 +1,11 @@
+// Loads a run's study analysis together with the automatic analysis job's view of it. The store
+// and the job module each stay importable without the other.
+import { readAutomaticStudyAnalysisPrepared } from "./job.js";
+import { loadStudyAnalysisRecord } from "./store.js";
+export async function loadStudyAnalysis(prepared, id) {
+    const [loaded, automatic] = await Promise.all([
+        loadStudyAnalysisRecord(prepared, id),
+        readAutomaticStudyAnalysisPrepared(prepared),
+    ]);
+    return automatic === undefined ? loaded : { ...loaded, automatic };
+}

package/dist/analysis/provider.d.ts

@@ -0,0 +1,57 @@
+import { type Dispatcher } from "undici";
+/** Deliberately separate from the stateful computer-use actor: one request, no tools or retries. */
+export interface AnalysisProviderRequest {
+    model: string;
+    instructions: string;
+    evidence: string;
+    images: {
+        evidenceId: string;
+        dataUrl: string;
+    }[];
+    schema: Record<string, unknown>;
+    maxOutputTokens: number | null;
+    timeoutMs: number;
+    signal?: AbortSignal;
+}
+interface AnalysisTokenUsage {
+    input: number;
+    output: number;
+    cachedInput?: number;
+    cacheWriteInput?: number;
+}
+export interface AnalysisProviderResult {
+    status: "completed" | "incomplete" | "refused" | "failed" | "cancelled" | "timed_out";
+    /** Parsed output is still untrusted. runAnalysis must validate its schema and evidence references. */
+    output: unknown;
+    usage: AnalysisTokenUsage | null;
+    /** Dispatch does not imply a known charge. A failed request can still have consumed tokens. */
+    dispatched: boolean;
+    /** Omitted preserves complete API-response accounting; account snapshots must state this. */
+    usageComplete?: boolean;
+    errorCode: "invalid_request" | "provider_http_error" | "provider_network_error" | "invalid_response" | "provider_headers_timeout" | "provider_body_timeout" | "provider_connect_timeout" | "provider_connection_reset" | "provider_dns_error" | "codex_busy" | "codex_unavailable" | "codex_unsupported_version" | "codex_unsupported_platform" | "codex_login_required" | "codex_unsupported_auth" | "codex_unsafe_configuration" | "codex_model_unavailable" | "codex_protocol_error" | "codex_tool_call" | "codex_process_failed" | "codex_cleanup_failed" | "response_too_large" | "output_incomplete" | "refusal" | "cancelled" | "timeout" | null;
+    httpStatus?: number;
+}
+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";
+    redirect: "error";
+    signal: AbortSignal;
+    headers: Record<string, string>;
+    body: string;
+    dispatcher: Dispatcher;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    body: ReadableStream<Uint8Array> | null;
+}>;
+/** No alternate endpoint or env-derived base URL: evidence and credentials have one destination. */
+export declare function createAnalysisProvider(options: {
+    apiKey: string;
+    fetchFn?: AnalysisFetch;
+}): AnalysisProvider;
+export {};

package/dist/analysis/provider.js

@@ -0,0 +1,227 @@
+import { Agent, fetch as undiciFetch } from "undici";
+import { OPENAI_RESPONSES_URL } from "../actors/openai-endpoint.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;
+/** 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
+ * fetch from the same undici package: Node's built-in fetch bundles its own undici, and an
+ * undici 8 agent fails there with "invalid onRequestStart method". */
+class AnalysisAgent extends Agent {
+    dispatch(options, handler) {
+        return super.dispatch({ ...options, headersTimeout: 0, bodyTimeout: 0 }, handler);
+    }
+}
+/** Persist only a closed vocabulary, never an exception's prose, URL or headers. */
+function networkErrorCode(error) {
+    const codes = {
+        UND_ERR_HEADERS_TIMEOUT: "provider_headers_timeout",
+        UND_ERR_BODY_TIMEOUT: "provider_body_timeout",
+        UND_ERR_CONNECT_TIMEOUT: "provider_connect_timeout",
+        ECONNRESET: "provider_connection_reset",
+        UND_ERR_SOCKET: "provider_connection_reset",
+        ENOTFOUND: "provider_dns_error",
+        EAI_AGAIN: "provider_dns_error",
+    };
+    let current = error;
+    for (let depth = 0; depth < 4; depth += 1) {
+        const value = record(current);
+        if (typeof value.code === "string" && Object.hasOwn(codes, value.code))
+            return codes[value.code];
+        current = value.cause;
+    }
+    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. */
+export function createAnalysisProvider(options) {
+    const fetchFn = options.fetchFn ?? undiciFetch;
+    return async (request) => {
+        const failure = (errorCode, dispatched, status = "failed") => ({
+            status,
+            output: null,
+            usage: null,
+            dispatched,
+            errorCode,
+        });
+        if (request.signal?.aborted)
+            return failure("cancelled", false, "cancelled");
+        if (!options.apiKey.trim() ||
+            !/^[A-Za-z0-9_.-]{1,100}$/.test(request.model) ||
+            request.maxOutputTokens === null ||
+            !Number.isSafeInteger(request.maxOutputTokens) ||
+            request.maxOutputTokens < 256 ||
+            request.maxOutputTokens > 32_768 ||
+            !Number.isSafeInteger(request.timeoutMs) ||
+            request.timeoutMs < 1 ||
+            request.timeoutMs > 600_000 ||
+            request.images.length > 128 ||
+            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,
+                },
+            },
+        });
+        if (Buffer.byteLength(body) > MAX_REQUEST_BYTES)
+            return failure("invalid_request", false);
+        const controller = new AbortController();
+        let timedOut = false;
+        let dispatched = false;
+        const onAbort = () => controller.abort();
+        request.signal?.addEventListener("abort", onAbort, { once: true });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, request.timeoutMs);
+        const dispatcher = new AnalysisAgent();
+        try {
+            if (request.signal?.aborted)
+                return failure("cancelled", false, "cancelled");
+            dispatched = true;
+            const response = await fetchFn(OPENAI_RESPONSES_URL, {
+                method: "POST",
+                redirect: "error",
+                signal: controller.signal,
+                headers: { Authorization: `Bearer ${options.apiKey}`, "Content-Type": "application/json" },
+                body,
+                dispatcher,
+            });
+            if (!response.ok) {
+                // Never read provider error prose: it may echo evidence or credentials.
+                await response.body?.cancel();
+                return { ...failure("provider_http_error", true), httpStatus: response.status };
+            }
+            if (!response.body)
+                return failure("invalid_response", true);
+            const reader = response.body.getReader();
+            const chunks = [];
+            let bytes = 0;
+            try {
+                while (true) {
+                    const chunk = await reader.read();
+                    if (chunk.done)
+                        break;
+                    bytes += chunk.value.byteLength;
+                    if (bytes > MAX_RESPONSE_BYTES) {
+                        await reader.cancel();
+                        return failure("response_too_large", true);
+                    }
+                    chunks.push(chunk.value);
+                }
+            }
+            finally {
+                reader.releaseLock();
+            }
+            if (controller.signal.aborted)
+                return failure(timedOut ? "timeout" : "cancelled", true, timedOut ? "timed_out" : "cancelled");
+            try {
+                return parseAnalysisResponse(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+            }
+            catch {
+                return failure("invalid_response", true);
+            }
+        }
+        catch (error) {
+            if (controller.signal.aborted)
+                return failure(timedOut ? "timeout" : "cancelled", dispatched, timedOut ? "timed_out" : "cancelled");
+            return failure(networkErrorCode(error), dispatched);
+        }
+        finally {
+            clearTimeout(timer);
+            request.signal?.removeEventListener("abort", onAbort);
+            await dispatcher.destroy().catch(() => undefined);
+        }
+    };
+}

package/dist/analysis/restricted-codex.d.ts

@@ -0,0 +1,19 @@
+import { type RestrictedCodexSessionOptions } from "../actors/codex/restricted-session.js";
+import type { AnalysisConfig } from "./types.js";
+import type { RestrictedCodexAnalysisErrorCode, RestrictedCodexRequest, RestrictedCodexResult } from "../actors/codex/restricted-policy.js";
+/** Structurally implements AnalysisProvider without importing its API transport.
+ * Schema/evidence validation and transient-secret scrubbing remain in runAnalysis. */
+export declare function createRestrictedCodexAnalysisProvider(options?: RestrictedCodexSessionOptions): (request: RestrictedCodexRequest) => Promise<RestrictedCodexResult>;
+/**
+ * Record the installed release in a Codex identity when this host qualifies it. If detection
+ * fails, the requested identity stays and the launcher refuses that dispatch with its usual code.
+ */
+export declare function bindCodexAnalysisCliVersion(config: AnalysisConfig, detect?: () => Promise<string | null>): Promise<AnalysisConfig>;
+/** Does not submit a model turn. Readiness is not a quota/access guarantee. */
+export declare function checkRestrictedCodexAnalysisReadiness(input?: {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}, options?: RestrictedCodexSessionOptions): Promise<{
+    ready: boolean;
+    errorCode: RestrictedCodexAnalysisErrorCode | null;
+}>;

package/dist/analysis/restricted-codex.js

@@ -0,0 +1,23 @@
+import { checkRestrictedCodexSessionReadiness, detectRestrictedCodexCliVersion, runRestrictedCodexSession, } from "../actors/codex/restricted-session.js";
+/** Structurally implements AnalysisProvider without importing its API transport.
+ * Schema/evidence validation and transient-secret scrubbing remain in runAnalysis. */
+export function createRestrictedCodexAnalysisProvider(options = {}) {
+    return (request) => runRestrictedCodexSession(request, options);
+}
+/**
+ * Record the installed release in a Codex identity when this host qualifies it. If detection
+ * fails, the requested identity stays and the launcher refuses that dispatch with its usual code.
+ */
+export async function bindCodexAnalysisCliVersion(config, detect = async () => (await detectRestrictedCodexCliVersion()).cliVersion) {
+    if (config.provider !== "codex")
+        return config;
+    const cliVersion = await detect();
+    return cliVersion === null || cliVersion === config.identity.cliVersion
+        ? config
+        : { ...config, identity: { ...config.identity, cliVersion } };
+}
+/** Does not submit a model turn. Readiness is not a quota/access guarantee. */
+export async function checkRestrictedCodexAnalysisReadiness(input = {}, options = {}) {
+    const result = await checkRestrictedCodexSessionReadiness(input, options);
+    return { ready: result.status === "completed", errorCode: result.errorCode };
+}