humanish 0.104.3 → 0.106.0

package/dist/actors/scripted-browser/types.d.ts

@@ -0,0 +1,135 @@
+export interface ScriptedLocatorLike {
+    first(): ScriptedLocatorLike;
+    fill(value: string, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    click(options?: {
+        timeout?: number;
+    }): Promise<void>;
+    count(): Promise<number>;
+    waitFor(options?: {
+        state?: "visible";
+        timeout?: number;
+    }): Promise<void>;
+    isVisible(options?: {
+        timeout?: number;
+    }): Promise<boolean>;
+}
+export interface ScriptedPageLike {
+    goto(url: string, options?: {
+        waitUntil?: "domcontentloaded";
+        timeout?: number;
+    }): Promise<unknown>;
+    locator(selector: string): ScriptedLocatorLike;
+    waitForTimeout(ms: number): Promise<void>;
+    waitForFunction(fn: string, arg: unknown, options?: {
+        timeout?: number;
+    }): Promise<unknown>;
+    screenshot(options: {
+        path: string;
+        fullPage: boolean;
+    }): Promise<unknown>;
+    url(): string;
+    evaluate<T>(pageFunction: string): Promise<T>;
+}
+export interface ScriptedBrowserLike {
+    newContext(options: {
+        deviceScaleFactor: number;
+        isMobile: boolean;
+        viewport: {
+            width: number;
+            height: number;
+        };
+    }): Promise<{
+        newPage(): Promise<ScriptedPageLike>;
+    }>;
+    close(): Promise<void>;
+}
+export interface ScriptedBrowserLaunchArgs {
+    browserCommand: string;
+    timeoutMs: number;
+}
+export type ScriptedBrowserEvidenceUrlPolicy = {
+    kind: "loopback";
+} | {
+    kind: "provisioned-subject";
+    evidenceOrigin: string;
+};
+export declare const LOOPBACK_EVIDENCE_URL_POLICY: ScriptedBrowserEvidenceUrlPolicy;
+export interface BrowserSurface {
+    id: "desktop" | "mobile";
+    label: string;
+    viewport: {
+        width: number;
+        height: number;
+        deviceScaleFactor: number;
+        isMobile: boolean;
+    };
+}
+export interface BrowserSurfaceCapture {
+    capturedAt: string;
+    durationMs: number;
+    httpStatus?: number;
+    ok: boolean;
+    reason: string;
+    /**
+     * Surface-level screenshot the producer wrote (the last step's screenshot).
+     * Omitted for a blocked capture whose evidence is the failure itself, so the
+     * stream never claims a screenshot embed/ui reference that does not exist.
+     * verifyRun fails closed on a referenced local artifact that is missing or empty.
+     */
+    screenshotPath?: string;
+    steps: BrowserPersonaStepCapture[];
+    surface: BrowserSurface;
+    tracePath: string;
+}
+export type BrowserPersonaAction = "goto" | "click" | "fill" | "assertText" | "waitForText" | "waitForSelector";
+export interface BrowserPersonaAssertionCapture {
+    id: string;
+    reason: string;
+    status: "passed" | "blocked";
+}
+export interface BrowserPersonaStepCapture {
+    action: string;
+    assertions?: BrowserPersonaAssertionCapture[];
+    completedAt: string;
+    durationMs: number;
+    id: string;
+    label: string;
+    reason: string;
+    /**
+     * Path to the step screenshot the producer actually wrote. Omitted for blocked
+     * steps where the failure itself is the recorded evidence and no screenshot was
+     * written — the bundle must not reference an artifact that does not exist. A step that
+     * ran and attempted a screenshot keeps this even when its assertions failed, so a broken
+     * producer still fails verify.
+     */
+    screenshotPath?: string;
+    status: "passed" | "blocked";
+    url: string;
+}
+export interface BrowserPersonaStepExpectation {
+    selectorVisible?: string;
+    stateChanged?: boolean;
+    text?: string;
+    urlIncludes?: string;
+}
+export interface BrowserPersonaStepManifest {
+    action: BrowserPersonaAction;
+    expectation?: BrowserPersonaStepExpectation;
+    id: string;
+    label: string;
+    path?: string;
+    selector?: string;
+    value?: string;
+}
+export interface BrowserPersonaJourney {
+    goal: string;
+    scenarioId: string;
+    scenarioTitle: string;
+    source: string;
+    sourceDigest: string;
+    startPath: string;
+    steps: BrowserPersonaStepManifest[];
+}
+export declare const browserSurfaces: BrowserSurface[];

package/dist/actors/scripted-browser/types.js

@@ -0,0 +1,26 @@
+// The scripted-browser actor's types: the structural seams that playwright's Browser and Page satisfy
+// (tests inject fakes behind them and still run the real step executor), the evidence URL policy,
+// and the journey and capture types the parser, step executor and session share.
+export const LOOPBACK_EVIDENCE_URL_POLICY = { kind: "loopback" };
+export const browserSurfaces = [
+    {
+        id: "desktop",
+        label: "Desktop browser surface",
+        viewport: {
+            width: 1440,
+            height: 960,
+            deviceScaleFactor: 1,
+            isMobile: false,
+        },
+    },
+    {
+        id: "mobile",
+        label: "Mobile browser surface",
+        viewport: {
+            width: 390,
+            height: 844,
+            deviceScaleFactor: 2,
+            isMobile: true,
+        },
+    },
+];

package/dist/actors/stop-cause.d.ts

@@ -0,0 +1,9 @@
+import type { ActorStopCause, ActorTrace } from "./contract.js";
+export interface ActorEnding {
+    cause: ActorStopCause | "unspecified_limit";
+    label: string;
+}
+/** Shared wording for consumers that already hold a validated, finite stop cause. */
+export declare function actorStopCauseLabel(cause: ActorEnding["cause"]): string;
+/** Project recorded control evidence, never participant prose. Leave the actor untouched. */
+export declare function actorEnding(actor: ActorTrace | undefined): ActorEnding | undefined;

package/dist/actors/stop-cause.js

@@ -0,0 +1,42 @@
+const labels = {
+    provider_output_limit: "provider output limit",
+    provider_token_limit: "provider token limit",
+    time_limit: "time limit",
+    spend_limit: "estimated spend limit",
+    study_spend_limit: "study spend limit",
+    adapter_limit: "adapter admission limit",
+    usage_unreported: "provider usage unavailable",
+    provider_incomplete: "provider response incomplete",
+    provider_status: "unexpected provider status",
+    provider_refused_prompt: "provider refused the prompt under its usage policy",
+    harness_aborted: "stopped by harness",
+    unspecified_limit: "limit reached",
+};
+/** Shared wording for consumers that already hold a validated, finite stop cause. */
+export function actorStopCauseLabel(cause) {
+    return labels[cause];
+}
+/** Project recorded control evidence, never participant prose. Leave the actor untouched. */
+export function actorEnding(actor) {
+    if (!actor)
+        return undefined;
+    const explicit = actor.stopCause;
+    if (typeof explicit === "string" && Object.hasOwn(labels, explicit))
+        return { cause: explicit, label: actorStopCauseLabel(explicit) };
+    // These exact machine-generated notices predate stopCause. Their text is not parsed and a
+    // provider token notice cannot retrospectively establish output versus context exhaustion.
+    const notice = (title) => actor.items.some((item) => item.kind === "notice" && item.title === title);
+    let cause;
+    if (actor.completionReason === "budget_reached") {
+        cause = notice("provider token limit reached") ? "provider_token_limit" : "unspecified_limit";
+    }
+    else if (actor.completionReason === "timed_out")
+        cause = "time_limit";
+    else if (actor.completionReason === "harness_error") {
+        if (notice("provider response incomplete"))
+            cause = "provider_incomplete";
+        else if (notice("unexpected provider response status"))
+            cause = "provider_status";
+    }
+    return cause === undefined ? undefined : { cause, label: actorStopCauseLabel(cause) };
+}

package/dist/actors/stop-conditions.d.ts

@@ -0,0 +1,40 @@
+export type StopConditionPrimitive = string | number | boolean | null;
+interface StopWhenAppStatePathEquals {
+    path: string;
+    equals: StopConditionPrimitive;
+}
+export interface StopWhenRule {
+    id?: string;
+    urlIncludes?: string;
+    urlPathEquals?: string;
+    textIncludes?: string;
+    appStatePathEquals?: StopWhenAppStatePathEquals;
+}
+export interface StopWhen {
+    any: StopWhenRule[];
+}
+/**
+ * A declared observation window (#510): once `when` matches (or at the start, when `when` is
+ * absent), the harness holds the page for `ms`, captures a frame every `everyMs`, takes no action
+ * and requests no model turn, then hands control back to the participant (`then: continue`) or
+ * ends the session (`then: stop`). Bounded by the session budget: a window that would outlast it
+ * is cut to fit. The study is observing; the participant is not "waiting".
+ */
+export interface DwellWindow {
+    when?: StopWhen;
+    ms: number;
+    everyMs: number;
+    then: "continue" | "stop";
+}
+export interface StopConditionObservation {
+    url?: string;
+    text?: string;
+    appState?: Record<string, unknown>;
+}
+export interface StopConditionMatch {
+    id: string;
+    ruleIndex: number;
+    kinds: string[];
+}
+export declare function evaluateStopWhen(stopWhen: StopWhen | undefined, observation: StopConditionObservation): StopConditionMatch | undefined;
+export {};

package/dist/actors/stop-conditions.js

@@ -0,0 +1,65 @@
+export function evaluateStopWhen(stopWhen, observation) {
+    if (!stopWhen)
+        return undefined;
+    for (const [ruleIndex, rule] of stopWhen.any.entries()) {
+        const kinds = [];
+        if (rule.urlIncludes !== undefined) {
+            if (observation.url === undefined || !observation.url.includes(rule.urlIncludes)) {
+                continue;
+            }
+            kinds.push("urlIncludes");
+        }
+        if (rule.urlPathEquals !== undefined) {
+            if (pathOfUrl(observation.url) !== rule.urlPathEquals) {
+                continue;
+            }
+            kinds.push("urlPathEquals");
+        }
+        if (rule.textIncludes !== undefined) {
+            if (observation.text === undefined || !observation.text.includes(rule.textIncludes)) {
+                continue;
+            }
+            kinds.push("textIncludes");
+        }
+        if (rule.appStatePathEquals !== undefined) {
+            const actual = valueAtPath(observation.appState, rule.appStatePathEquals.path);
+            if (actual !== rule.appStatePathEquals.equals) {
+                continue;
+            }
+            kinds.push("appStatePathEquals");
+        }
+        if (kinds.length === 0)
+            continue;
+        return {
+            id: rule.id ?? `rule-${String(ruleIndex + 1).padStart(2, "0")}`,
+            ruleIndex,
+            kinds,
+        };
+    }
+    return undefined;
+}
+function pathOfUrl(url) {
+    if (!url)
+        return undefined;
+    try {
+        return new URL(url, "http://humanish.local").pathname;
+    }
+    catch {
+        return undefined;
+    }
+}
+function valueAtPath(source, path) {
+    if (!source)
+        return undefined;
+    const parts = path.split(".").filter(Boolean);
+    let current = source;
+    for (const part of parts) {
+        if (!isRecord(current))
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/analysis/automatic-completion.d.ts

@@ -0,0 +1,38 @@
+import { FinishedRun } from "../run/run.js";
+import type { AnalysisConfig } from "./types.js";
+import { runAutomaticStudyAnalysis, type AutomaticAnalysisDeps } from "./automatic.js";
+import type { AutomaticAnalysisOutcome } from "./job.js";
+export interface AutomaticAnalysisHooks {
+    /** Provider/test dependencies apply only to analysis, never to the participant. */
+    deps?: AutomaticAnalysisDeps;
+    /** Called after the source is finalized; the returned cleanup always runs. */
+    onStart?: () => void | (() => void);
+    run?: typeof runAutomaticStudyAnalysis;
+}
+export interface AutomaticAnalysisResult {
+    automaticAnalysis?: AutomaticAnalysisOutcome;
+    /** Distinguishes the default missing-key skip from failure of an explicit request. */
+    automaticAnalysisTrigger?: "default" | "explicit";
+}
+/**
+ * One post-completion boundary shared by all live recording producers. `finished` is the token
+ * the producer's run scope issued when the run published its final bundle; without it, or when it
+ * names another run than the result, there is no source to analyze.
+ */
+export declare function completeAutomaticAnalysis<T extends {
+    cwd: string;
+    runId: string;
+    dryRun: boolean;
+}>(result: T, finished: FinishedRun | undefined, config: AnalysisConfig | undefined, hooks?: AutomaticAnalysisHooks, { trigger, preferLargerOutput, }?: {
+    /** "default" when the lab declared no analysis; its missing-key skip is not a failure. */
+    trigger?: "default" | "explicit";
+    /** The lab omitted an output limit, so a larger one may be used within the admission budget. */
+    preferLargerOutput?: boolean;
+}): Promise<T & AutomaticAnalysisResult>;
+/**
+ * True when an analysis the lab never declared was refused because its conservative estimate is
+ * over the default cap. The author did not ask for it, so the refusal does not fail the run;
+ * `humanish analyze --max-cost` can still run it.
+ */
+export declare function defaultAnalysisOverBudget(result: AutomaticAnalysisResult): boolean;
+export declare function automaticAnalysisSucceeded(result: AutomaticAnalysisResult): boolean;

package/dist/analysis/automatic-completion.js

@@ -0,0 +1,90 @@
+import { physicalCwdOf, validatePreparedRunRootIdentity } from "../run/paths.js";
+import { FinishedRun } from "../run/run.js";
+import { runAutomaticStudyAnalysis } from "./automatic.js";
+/**
+ * One post-completion boundary shared by all live recording producers. `finished` is the token
+ * the producer's run scope issued when the run published its final bundle; without it, or when it
+ * names another run than the result, there is no source to analyze.
+ */
+export async function completeAutomaticAnalysis(result, finished, config, hooks, { trigger = "explicit", preferLargerOutput = false, } = {}) {
+    if (config === undefined)
+        return result;
+    const origin = trigger === "default" ? { automaticAnalysisTrigger: trigger } : {};
+    if (result.dryRun)
+        return {
+            ...result,
+            ...origin,
+            automaticAnalysis: { state: "skipped", reason: "AUTOMATIC_ANALYSIS_DRY_RUN" },
+        };
+    // An early refusal can echo a caller-supplied ID belonging to an older run, so the ID alone
+    // proves nothing. Only this invocation's own publication token names a source.
+    if (!FinishedRun.isIssued(finished) || finished.runId !== result.runId) {
+        return {
+            ...result,
+            ...origin,
+            automaticAnalysis: { state: "skipped", reason: "AUTOMATIC_ANALYSIS_SOURCE_UNAVAILABLE" },
+        };
+    }
+    const prepared = finished.paths;
+    let cleanup = undefined;
+    try {
+        cleanup = hooks?.onStart?.();
+        try {
+            await validatePreparedRunRootIdentity(prepared);
+        }
+        catch {
+            return {
+                ...result,
+                ...origin,
+                automaticAnalysis: { state: "failed", reason: "AUTOMATIC_ANALYSIS_SOURCE_CHANGED" },
+            };
+        }
+        const sourceCwd = physicalCwdOf(prepared);
+        const automaticAnalysis = await (hooks?.run ?? runAutomaticStudyAnalysis)(sourceCwd, finished.runId, config, {
+            ...hooks?.deps,
+            preferLargerOutput,
+            ...(trigger === "default" ? { defaultRequest: true } : {}),
+            expectedRun: prepared,
+        });
+        return { ...result, ...origin, automaticAnalysis };
+    }
+    catch {
+        // Preserve the producer result. Never put a hook exception or provider response in the envelope.
+        return {
+            ...result,
+            ...origin,
+            automaticAnalysis: { state: "failed", reason: "AUTOMATIC_ANALYSIS_FAILED" },
+        };
+    }
+    finally {
+        try {
+            cleanup?.();
+        }
+        catch {
+            /* Cleanup cannot erase accounting or the completed recording. */
+        }
+    }
+}
+/**
+ * True when an analysis the lab never declared was refused because its conservative estimate is
+ * over the default cap. The author did not ask for it, so the refusal does not fail the run;
+ * `humanish analyze --max-cost` can still run it.
+ */
+export function defaultAnalysisOverBudget(result) {
+    const value = result.automaticAnalysis;
+    return (result.automaticAnalysisTrigger === "default" &&
+        value?.state === "skipped" &&
+        value.reason === "AUTOMATIC_ANALYSIS_ADMISSION_REFUSED" &&
+        value.result?.error?.code === "analysis_budget_exceeded");
+}
+export function automaticAnalysisSucceeded(result) {
+    const value = result.automaticAnalysis;
+    if (value === undefined)
+        return true;
+    if (value.state === "skipped")
+        return (value.reason === "AUTOMATIC_ANALYSIS_DRY_RUN" ||
+            (result.automaticAnalysisTrigger === "default" &&
+                ["AUTOMATIC_ANALYSIS_KEY_MISSING", "AUTOMATIC_ANALYSIS_NO_PARTICIPANT_EVIDENCE"].includes(value.reason ?? "")) ||
+            defaultAnalysisOverBudget(result));
+    return (value.state === "complete" || value.state === "partial") && value.result?.ok === true;
+}

package/dist/analysis/automatic-config.d.ts

@@ -0,0 +1,41 @@
+import type { LabRoute } from "../lab/plan.js";
+import type { AnalysisConfig } from "./types.js";
+export declare const DEFAULT_ANALYSIS_TIMEOUT_MS = 600000;
+export declare const DEFAULT_ANALYSIS_MODEL = "gpt-6-astra";
+interface LabAnalysisSettings {
+    model?: string;
+    question?: string;
+    timeoutMs?: number;
+}
+/** The lab's review.analysis: a provider selection for a separate review after a live study. */
+export type LabAnalysis = LabAnalysisSettings & ({
+    provider?: "openai";
+    maxCostUsd: number;
+    maxOutputTokens?: number;
+} | {
+    provider: "codex";
+    maxCostUsd?: null;
+    maxOutputTokens?: null;
+});
+/** The spend cap on an analysis the lab did not declare. */
+export declare const DEFAULT_ANALYSIS_MAX_COST_USD = 3;
+/** Called for parsed manifests AND direct library configs, before participant execution. */
+export declare function resolveAutomaticAnalysis(raw: unknown): {
+    ok: true;
+    config: AnalysisConfig | undefined;
+    preferLargerOutput?: boolean;
+} | {
+    ok: false;
+    message: string;
+};
+export interface AutomaticAnalysisBudget {
+    provider?: "openai" | "codex";
+    billing?: "api-estimate" | "account-unknown";
+    model: string;
+    maxCostUsd: number | null;
+    trigger: "default" | "explicit";
+}
+/** Metadata only: resolving the future live-run budget never reads keys or dispatches. */
+export declare function automaticAnalysisBudget(raw: unknown, route: LabRoute): AutomaticAnalysisBudget | undefined;
+export declare function formatAutomaticAnalysisBudget(budget: AutomaticAnalysisBudget): string;
+export {};

package/dist/analysis/automatic-config.js

@@ -0,0 +1,135 @@
+import { CODEX_ANALYSIS_MODEL, codexAnalysisIdentity } from "./codex-config.js";
+import { DEFAULT_ANALYSIS_MAX_OUTPUT_TOKENS, MAX_ANALYSIS_OUTPUT_TOKENS, isSupportedAnalysisModel, } from "./execute.js";
+import { containsSensitive } from "../evidence/redaction.js";
+export const DEFAULT_ANALYSIS_TIMEOUT_MS = 600_000;
+const MAX_ANALYSIS_TIMEOUT_MS = 600_000;
+export const DEFAULT_ANALYSIS_MODEL = "gpt-6-astra";
+const FIELDS = new Set([
+    "provider",
+    "maxCostUsd",
+    "model",
+    "question",
+    "timeoutMs",
+    "maxOutputTokens",
+]);
+const validTimeout = (value) => typeof value === "number" &&
+    Number.isSafeInteger(value) &&
+    value >= 1 &&
+    value <= MAX_ANALYSIS_TIMEOUT_MS;
+/** An absent question is valid; a present one must be a string of at most 4000 characters. */
+const validQuestion = (value) => value === undefined || (typeof value === "string" && value.length <= 4000);
+const SENSITIVE_QUESTION = {
+    ok: false,
+    message: "review.analysis.question contains sensitive text and cannot be sent for analysis.",
+};
+/** The spend cap on an analysis the lab did not declare. */
+export const DEFAULT_ANALYSIS_MAX_COST_USD = 3;
+/** Called for parsed manifests AND direct library configs, before participant execution. */
+export function resolveAutomaticAnalysis(raw) {
+    if (raw === false)
+        return { ok: true, config: undefined };
+    if (raw === undefined)
+        raw = { maxCostUsd: DEFAULT_ANALYSIS_MAX_COST_USD };
+    if (raw === null ||
+        typeof raw !== "object" ||
+        Array.isArray(raw) ||
+        Object.keys(raw).some((key) => !FIELDS.has(key))) {
+        return {
+            ok: false,
+            message: "review.analysis must be false or a mapping containing only provider, maxCostUsd, model, question, timeoutMs and maxOutputTokens.",
+        };
+    }
+    const value = raw;
+    if (value.provider !== undefined && value.provider !== "openai" && value.provider !== "codex") {
+        return { ok: false, message: "review.analysis.provider must be openai or codex." };
+    }
+    if (value.provider === "codex") {
+        const model = value.model === undefined ? CODEX_ANALYSIS_MODEL : value.model;
+        const timeoutMs = value.timeoutMs === undefined ? DEFAULT_ANALYSIS_TIMEOUT_MS : value.timeoutMs;
+        const question = value.question === undefined ? null : value.question;
+        if (model !== CODEX_ANALYSIS_MODEL ||
+            (value.maxCostUsd !== undefined && value.maxCostUsd !== null) ||
+            (value.maxOutputTokens !== undefined && value.maxOutputTokens !== null) ||
+            !validTimeout(timeoutMs) ||
+            !validQuestion(value.question)) {
+            return {
+                ok: false,
+                message: `Codex analysis requires the qualified ${CODEX_ANALYSIS_MODEL} model and timeoutMs 1–${MAX_ANALYSIS_TIMEOUT_MS}. Dollar and output-token caps are unavailable; omit them. The optional question is limited to 4000 characters.`,
+            };
+        }
+        if (question !== null && containsSensitive(question))
+            return SENSITIVE_QUESTION;
+        return {
+            ok: true,
+            config: {
+                provider: "codex",
+                model,
+                question: question,
+                timeoutMs,
+                maxCostUsd: null,
+                maxOutputTokens: null,
+                identity: codexAnalysisIdentity(model),
+            },
+        };
+    }
+    const { maxCostUsd } = value;
+    const model = value.model === undefined ? DEFAULT_ANALYSIS_MODEL : value.model;
+    const question = value.question === undefined ? null : value.question;
+    const timeoutMs = value.timeoutMs === undefined ? DEFAULT_ANALYSIS_TIMEOUT_MS : value.timeoutMs;
+    const maxOutputTokens = value.maxOutputTokens === undefined
+        ? DEFAULT_ANALYSIS_MAX_OUTPUT_TOKENS
+        : value.maxOutputTokens;
+    if (typeof maxCostUsd !== "number" ||
+        !Number.isFinite(maxCostUsd) ||
+        maxCostUsd <= 0 ||
+        maxCostUsd > 1000 ||
+        typeof model !== "string" ||
+        !isSupportedAnalysisModel(model) ||
+        !validTimeout(timeoutMs) ||
+        typeof maxOutputTokens !== "number" ||
+        !Number.isSafeInteger(maxOutputTokens) ||
+        maxOutputTokens < 256 ||
+        maxOutputTokens > MAX_ANALYSIS_OUTPUT_TOKENS ||
+        !validQuestion(value.question)) {
+        return {
+            ok: false,
+            message: `review.analysis requires a positive maxCostUsd up to 1000, a supported analysis model, timeoutMs 1–${MAX_ANALYSIS_TIMEOUT_MS}, maxOutputTokens 256–${MAX_ANALYSIS_OUTPUT_TOKENS}, and an optional question of at most 4000 characters.`,
+        };
+    }
+    if (question !== null && containsSensitive(question))
+        return SENSITIVE_QUESTION;
+    return {
+        ok: true,
+        config: {
+            ...(value.provider === undefined ? {} : { provider: "openai" }),
+            model,
+            maxCostUsd,
+            timeoutMs,
+            maxOutputTokens,
+            question: question,
+        },
+        ...(value.maxOutputTokens === undefined ? { preferLargerOutput: true } : {}),
+    };
+}
+/** Metadata only: resolving the future live-run budget never reads keys or dispatches. */
+export function automaticAnalysisBudget(raw, route) {
+    // The synthetic preview has no participants, so nothing is analyzed after it.
+    if (route === "preview")
+        return undefined;
+    const resolved = resolveAutomaticAnalysis(raw);
+    return resolved.ok && resolved.config
+        ? {
+            ...(resolved.config.provider === "codex"
+                ? { provider: "codex", billing: "account-unknown" }
+                : {}),
+            model: resolved.config.model,
+            maxCostUsd: resolved.config.maxCostUsd,
+            trigger: raw === undefined ? "default" : "explicit",
+        }
+        : undefined;
+}
+export function formatAutomaticAnalysisBudget(budget) {
+    if (budget.provider === "codex")
+        return `After live runs: Codex account analysis · ${budget.model} · separate restricted analyst with remote inference. Account limits apply; dollar cost and output-token ceiling are unknown. Set review.analysis: false to disable.`;
+    return `After live runs: ${budget.trigger} analysis · ${budget.model} · separate $${budget.maxCostUsd} admission estimate limit (not a provider billing cap). Set review.analysis: false to disable.`;
+}

package/dist/analysis/automatic.d.ts

@@ -0,0 +1,17 @@
+import { type AnalyzeDeps } from "./service.js";
+import { type AutomaticAnalysisView, type AutomaticAnalysisOutcome, type AutomaticAnalysisCancellation } from "./job.js";
+import { type AnalysisConfig } from "./types.js";
+export type { AutomaticAnalysisView, AutomaticAnalysisOutcome, AutomaticAnalysisCancellation, } from "./job.js";
+export type AutomaticAnalysisDeps = Omit<AnalyzeDeps, "analysisId" | "beforeDispatch"> & {
+    /** A missing default key records a skip before admission, preserving a successful recording. */
+    defaultRequest?: boolean;
+    /** Expand an omitted output limit only within the existing admission budget. */
+    preferLargerOutput?: boolean;
+};
+/** Small read-only TUI/CLI projection. Neither this nor Observer can resume a job. */
+export declare function readAutomaticStudyAnalysis(cwd: string, runId: string): Promise<AutomaticAnalysisView | undefined>;
+export declare function requestAutomaticStudyAnalysisCancellation(cwd: string, runId: string): Promise<AutomaticAnalysisCancellation>;
+/** One permanent claim per completed run, consumed even when preparation/cancellation fails.
+ * Only the original producer calls this after all recording writes return.
+ * No file reader, restart recovery, Observer poll or export calls this function. */
+export declare function runAutomaticStudyAnalysis(cwdInput: string, runId: string, configInput: AnalysisConfig, deps?: AutomaticAnalysisDeps): Promise<AutomaticAnalysisOutcome>;