humanish 0.113.0 → 0.115.0

package/dist/actors/computer-use/openai-conversation.js

@@ -1,4 +1,4 @@
-import { PARTICIPANT_IMPRESSION_KINDS } from "../contract.js";
+import { closingReportSchema, impressionsReplySchema, strictOutputSchema, } from "../closing-report.js";
 import { CarriedConversation, estimateTokens } from "./openai-context.js";
 import { buildCallOutput, buildContinuationRequest, buildInitialRequest, hintItems, openingMessage, parseOpenAiResponse, } from "./openai-wire.js";
 /**
@@ -6,44 +6,18 @@ import { buildCallOutput, buildContinuationRequest, buildInitialRequest, hintIte
  * counts reasoning too, and leaves room for six impressions after the summary and friction reports.
  */
 const CLOSING_OUTPUT_LIMIT = 3072;
-const IMPRESSIONS_SCHEMA = {
-    type: "array",
-    items: {
-        type: "object",
-        additionalProperties: false,
-        required: ["kind", "text"],
-        properties: {
-            kind: { type: "string", enum: [...PARTICIPANT_IMPRESSION_KINDS] },
-            text: { type: "string" },
-        },
-    },
-};
 const CLOSING_FORMATS = {
     report: {
         type: "json_schema",
         name: "participant_closing_report",
         strict: true,
-        schema: {
-            type: "object",
-            additionalProperties: false,
-            required: ["summary", "frictionReports", "impressions"],
-            properties: {
-                summary: { type: "string" },
-                frictionReports: { type: "array", items: { type: "string" } },
-                impressions: IMPRESSIONS_SCHEMA,
-            },
-        },
+        schema: strictOutputSchema(closingReportSchema),
     },
     impressions: {
         type: "json_schema",
         name: "participant_impressions",
         strict: true,
-        schema: {
-            type: "object",
-            additionalProperties: false,
-            required: ["impressions"],
-            properties: { impressions: IMPRESSIONS_SCHEMA },
-        },
+        schema: strictOutputSchema(impressionsReplySchema),
     },
 };
 export class OpenAiConversation {
@@ -73,7 +47,7 @@ export class OpenAiConversation {
         const sent = this.newItems(req);
         return {
             body: () => closing === undefined ? this.turnBody(req, sent) : this.closingBody(req, sent, closing),
-            accept: (reply) => this.accept(reply, closing !== undefined, sent),
+            accept: (reply) => this.accept(reply, closing, sent),
         };
     }
     /**
@@ -171,10 +145,10 @@ export class OpenAiConversation {
     accept(reply, closing, sent) {
         // Recorded before the reply is accepted: accepting can cut the carried history, and the record
         // counts what this request carried.
-        if (!closing)
-            this.evidence.requested(this.mode, this.carried, sent);
+        if (closing !== "report")
+            this.evidence.requested(this.mode, this.carried, sent, closing);
         const parsed = parseOpenAiResponse(reply);
-        if (!closing && parsed.turn.interruption === "output_limit")
+        if (closing === undefined && parsed.turn.interruption === "output_limit")
             return parsed.turn;
         if (parsed.turn.responseId !== undefined)
             this.lastResponseId = parsed.turn.responseId;
@@ -206,10 +180,11 @@ class ConversationRecord {
         // Counted like requests[], which includes replies set aside at their output limit.
         this.switchedAtRequest = this.requests.length + 1;
     }
-    /** A participant request went out with `sent` after `conversation`. */
-    requested(mode, conversation, sent) {
+    /** A participant turn or impressions request went out with `sent` after `conversation`. */
+    requested(mode, conversation, sent, kind) {
+        const marker = kind === undefined ? {} : { kind };
         if (mode !== "explicit_context") {
-            this.requests.push({ mode: "threaded" });
+            this.requests.push({ mode: "threaded", ...marker });
             return;
         }
         const carried = conversation.size();
@@ -217,6 +192,7 @@ class ConversationRecord {
         this.summarizedTurns = carried.notedTurns;
         this.requests.push({
             mode: "explicit_context",
+            ...marker,
             carriedExchanges: carried.exchanges,
             carriedScreenshots: carried.screenshots,
             estimatedInputTokens: carried.estimatedTokens + estimateTokens(sent),

package/dist/actors/computer-use/openai-provider.js

@@ -1,4 +1,4 @@
-import { validClosingReport, validImpressionsReply } from "./loop.js";
+import { closingReportSchema, impressionsReplySchema } from "../closing-report.js";
 import { ComputerUseAdmissionLimitError, isComputerUseAdmissionLimitError, } from "./admission-limit.js";
 import { ComputerUsePromptRefusedError } from "./provider-error.js";
 import { OpenAiConversation, } from "./openai-conversation.js";
@@ -469,10 +469,16 @@ export function createOpenAiResponsesProvider(options) {
             try {
                 const reply = JSON.parse(turn.message ?? "");
                 if (asRecord(raw).status === "completed") {
-                    if (closing === "report" && validClosingReport(reply))
-                        return { ...turn, closingReport: reply };
-                    if (closing === "impressions" && validImpressionsReply(reply))
-                        return { ...turn, impressions: reply.impressions };
+                    if (closing === "report") {
+                        const report = closingReportSchema.safeParse(reply);
+                        if (report.success)
+                            return { ...turn, closingReport: report.data };
+                    }
+                    else {
+                        const impressions = impressionsReplySchema.safeParse(reply);
+                        if (impressions.success)
+                            return { ...turn, impressions: impressions.data.impressions };
+                    }
                 }
             }
             catch {

package/dist/actors/contract.d.ts

@@ -1,8 +1,10 @@
 import type { AffordanceUse } from "./affordance.js";
 import type { ActorEstimatedCost } from "../run/pricing.js";
 import type { TaskFunnel } from "../study/tasks.js";
+import type { ParticipantClosingReport, ParticipantImpression } from "./closing-report.js";
 import { type CuaProviderFailurePhase } from "./computer-use/provider-error.js";
 export declare const ACTOR_TRACE_SCHEMA = "humanish.actor-trace.v1";
+export type { ParticipantClosingReport, ParticipantImpression } from "./closing-report.js";
 /**
  * How a session ended, from the point of view of the study rather than the harness.
  *
@@ -182,25 +184,6 @@ export interface ActorProviderRequest extends ProviderRequestReceipt {
 export declare function validActorExecutionProfile(value: unknown): value is ActorExecutionProfile;
 /** Closed per-attempt evidence; dollar amounts are never part of account usage. */
 export declare function validActorProviderRequests(value: unknown): value is ActorProviderRequest[];
-/** The participant's account, not an independently confirmed product diagnosis. */
-export interface ParticipantClosingReport {
-    summary: string;
-    frictionReports: string[];
-    /** Absent when the provider did not ask for impressions; empty when the participant had none. */
-    impressions?: ParticipantImpression[];
-}
-/**
- * What a participant can say about the product at the end of a session, beyond friction.
- * `unlike_my_work` compares the screen with how the persona does the same task in its own work or
- * life.
- */
-export declare const PARTICIPANT_IMPRESSION_KINDS: readonly ["unclear", "unfinished", "untrustworthy", "liked", "missing", "unlike_my_work"];
-type ParticipantImpressionKind = (typeof PARTICIPANT_IMPRESSION_KINDS)[number];
-/** One first-person impression about something the participant saw in the session. */
-export interface ParticipantImpression {
-    kind: ParticipantImpressionKind;
-    text: string;
-}
 /** An impression as the trace keeps it, with the message that quotes it. */
 interface RecordedImpression extends ParticipantImpression {
     /** The trace message carrying the impression, which the analysis quotes and cites. */
@@ -261,11 +244,13 @@ export interface ActorConversation {
      */
     summarizedTurns: number;
     /**
-     * Per participant request, in order: its mode and, in explicit_context, what it carried and its
-     * estimated input. `tokenUsage.turns` has each request's billed input.
+     * Per participant turn or impressions request, in order: its mode and, in explicit_context,
+     * what it carried and its estimated input. `tokenUsage.turns` has each request's billed input.
      */
     requests: Array<{
         mode: "threaded" | "explicit_context";
+        /** Present for the impressions-only request; absent for participant turns and older bundles. */
+        kind?: "impressions";
         carriedExchanges?: number;
         carriedScreenshots?: number;
         estimatedInputTokens?: number;
@@ -397,4 +382,3 @@ export interface ActorSessionResult {
 export declare const CODEX_APP_SERVER_CAPABILITIES: ActorCapabilities;
 export declare const SCRIPTED_BROWSER_CAPABILITIES: ActorCapabilities;
 export declare const TERMINAL_AGENT_CAPABILITIES: ActorCapabilities;
-export {};

package/dist/actors/contract.js

@@ -168,19 +168,6 @@ export function validActorProviderRequests(value) {
                     usage.input));
     });
 }
-/**
- * What a participant can say about the product at the end of a session, beyond friction.
- * `unlike_my_work` compares the screen with how the persona does the same task in its own work or
- * life.
- */
-export const PARTICIPANT_IMPRESSION_KINDS = [
-    "unclear",
-    "unfinished",
-    "untrustworthy",
-    "liked",
-    "missing",
-    "unlike_my_work",
-];
 export const CODEX_APP_SERVER_CAPABILITIES = {
     headless: true,
     structuredTrace: true,

package/dist/analysis/admission.d.ts

@@ -0,0 +1,47 @@
+import type { ModelRate } from "../run/pricing.js";
+/** Admission compares the expected cost times this margin with the cap. */
+export declare const ADMISSION_MARGIN = 1.1;
+export interface AnalysisRequestSize {
+    /** UTF-8 bytes of the instructions, the evidence packet and the result schema. */
+    textBytes: number;
+    imageTokens: number;
+    participants: number;
+    /** The request's output limit. The worst case spends all of it. */
+    outputAllowance: number;
+}
+export interface AnalysisCostEstimate {
+    inputTokens: number;
+    expectedOutputTokens: number;
+    expectedCostUsd: number;
+    worstCaseCostUsd: number;
+    /** The expected cost with the margin, never above the worst case: what admission compares. */
+    admittedCostUsd: number;
+}
+export declare function estimateAnalysisCost(rate: ModelRate, size: AnalysisRequestSize): AnalysisCostEstimate;
+/** The numbers a cost refusal reports. */
+export interface RefusedAnalysisCost {
+    expectedCostUsd: number;
+    worstCaseCostUsd: number;
+    maxCostUsd: number;
+}
+/** A cost refusal in plain words, and the command that runs the analysis under a cap that admits it. */
+export interface CostRefusal {
+    /** The costs, the cap and that no request was sent, ending in the lead-in to `command`. */
+    text: string;
+    /** `analyze` with `--max-cost` at the worst case rounded up to a whole dollar, at least 1. */
+    command: string;
+}
+/**
+ * Words a cost refusal. `runFlags` are the `analyze` flags that select the run, such as
+ * `--run <id>`. `cli` prefixes a humanish command: the CLI passes `cli` from
+ * src/cli/invocation.ts, and the Observer, which cannot read the install, a bare `humanish`.
+ * This module keeps only type imports, so the Observer can bundle it.
+ */
+export declare function costRefusal(cost: RefusedAnalysisCost, runFlags: string, cli: (rest: string) => string): CostRefusal;
+/** The admission's refused cost, when it refused the analysis for its cost. */
+export declare function refusedCost(admission: {
+    error: string | null;
+    estimatedCostUsd: number | null;
+    worstCaseCostUsd: number | null;
+    maxCostUsd: number | null;
+}): RefusedAnalysisCost | undefined;

package/dist/analysis/admission.js

@@ -0,0 +1,65 @@
+// The admission cost model for one study analysis request: the expected cost, the worst case, the
+// figure admission compares with the cap, and the words and command a cost refusal gives.
+/**
+ * UTF-8 bytes per input token for the instructions, evidence packet and schema. On 148 billed
+ * gpt-6-astra analyses the evidence packet ran 3.1 to 3.3 bytes per token and the instructions
+ * more, so 3 stays above every billed input. Chinese, Japanese and Korean text is 3 bytes per
+ * character in UTF-8, so it also counts at least a token per character.
+ */
+const BYTES_PER_INPUT_TOKEN = 3;
+/** Request framing on top of the text and the images. */
+const FRAMING_TOKENS = 2048;
+/**
+ * The output an analysis is expected to write, reasoning included. The most any billed analysis
+ * used was 12,511 tokens for one participant and 16,722 for eight.
+ */
+const EXPECTED_OUTPUT_TOKENS = 12_000;
+const EXPECTED_OUTPUT_TOKENS_PER_PARTICIPANT = 1_000;
+/** Admission compares the expected cost times this margin with the cap. */
+export const ADMISSION_MARGIN = 1.1;
+/** Rounded up to the micro-dollar, so a small positive boundary never rounds into admission. */
+const roundUp = (usd) => Math.ceil(usd * 1e6) / 1e6;
+/** One request's cost. Input is priced at the highest input rate the model bills, cache writes
+ * included, and the long-context tier re-prices the whole request past its threshold. */
+function requestCost(rate, inputTokens, outputTokens) {
+    const long = rate.longContext !== undefined && inputTokens > rate.longContext.thresholdInputTokens;
+    const inputRate = Math.max(rate.inputUsdPerToken, rate.cacheWriteUsdPerToken ?? 0, rate.cachedInputUsdPerToken ?? 0);
+    return roundUp(inputTokens * inputRate * (long ? rate.longContext.inputMultiplier : 1) +
+        outputTokens * rate.outputUsdPerToken * (long ? rate.longContext.outputMultiplier : 1));
+}
+export function estimateAnalysisCost(rate, size) {
+    const inputTokens = Math.ceil(size.textBytes / BYTES_PER_INPUT_TOKEN) + FRAMING_TOKENS + size.imageTokens;
+    const expectedOutputTokens = Math.min(size.outputAllowance, EXPECTED_OUTPUT_TOKENS + EXPECTED_OUTPUT_TOKENS_PER_PARTICIPANT * size.participants);
+    const expectedCostUsd = requestCost(rate, inputTokens, expectedOutputTokens);
+    const worstCaseCostUsd = requestCost(rate, inputTokens, size.outputAllowance);
+    return {
+        inputTokens,
+        expectedOutputTokens,
+        expectedCostUsd,
+        worstCaseCostUsd,
+        admittedCostUsd: Math.min(worstCaseCostUsd, roundUp(expectedCostUsd * ADMISSION_MARGIN)),
+    };
+}
+/**
+ * Words a cost refusal. `runFlags` are the `analyze` flags that select the run, such as
+ * `--run <id>`. `cli` prefixes a humanish command: the CLI passes `cli` from
+ * src/cli/invocation.ts, and the Observer, which cannot read the install, a bare `humanish`.
+ * This module keeps only type imports, so the Observer can bundle it.
+ */
+export function costRefusal(cost, runFlags, cli) {
+    const margin = Math.round((ADMISSION_MARGIN - 1) * 100);
+    return {
+        text: `The expected cost is $${cost.expectedCostUsd.toFixed(2)} and the worst case is $${cost.worstCaseCostUsd.toFixed(2)}. With a ${margin}% margin the expected cost is over the $${cost.maxCostUsd} cap, so no request was sent. To run it, raise the cap:`,
+        command: cli(`analyze ${runFlags} --max-cost ${Math.max(1, Math.ceil(cost.worstCaseCostUsd))}`),
+    };
+}
+/** The admission's refused cost, when it refused the analysis for its cost. */
+export function refusedCost(admission) {
+    const { error, estimatedCostUsd, worstCaseCostUsd, maxCostUsd } = admission;
+    return error === "analysis_budget_exceeded" &&
+        estimatedCostUsd !== null &&
+        worstCaseCostUsd !== null &&
+        maxCostUsd !== null
+        ? { expectedCostUsd: estimatedCostUsd, worstCaseCostUsd, maxCostUsd }
+        : undefined;
+}

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

@@ -35,10 +35,4 @@ export declare function completeAutomaticAnalysis<T extends {
     /** The route's reason not to analyze this run; see AutomaticAnalysisDeps.refusal. */
     refusal?: AutomaticAnalysisDeps["refusal"];
 }): Promise<T & AutomaticAnalysisResult>;
-/**
- * True when an analysis the study 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

@@ -85,11 +85,11 @@ export async function completeAutomaticAnalysis(result, finished, config, input,
     }
 }
 /**
- * True when an analysis the study 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;
+ * True when an analysis the study never declared was refused because its expected cost, with the
+ * admission margin, 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) {
+function defaultAnalysisOverBudget(result) {
     const value = result.automaticAnalysis;
     return (result.automaticAnalysisTrigger === "default" &&
         value?.state === "skipped" &&

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

@@ -34,8 +34,16 @@ export interface AutomaticAnalysisBudget {
     model: string;
     maxCostUsd: number | null;
     trigger: "default" | "explicit";
+    /** The participants the expected cost range is for. */
+    participants?: number;
+    /** The expected cost, from a run that keeps no evidence to one at the evidence limits. */
+    expectedCostUsd?: {
+        low: number;
+        high: number;
+    };
 }
-/** Metadata only: resolving the future live-run budget never reads keys or dispatches. */
-export declare function automaticAnalysisBudget(raw: unknown, route: StudyRoute): AutomaticAnalysisBudget | undefined;
+/** Metadata only: resolving the future live-run budget never reads keys or dispatches. With a
+ * participant count it also gives the expected cost range for that many participants. */
+export declare function automaticAnalysisBudget(raw: unknown, route: StudyRoute, participants?: number): AutomaticAnalysisBudget | undefined;
 export declare function formatAutomaticAnalysisBudget(budget: AutomaticAnalysisBudget): string;
 export {};

package/dist/analysis/automatic-config.js

@@ -1,5 +1,7 @@
 import { CODEX_ANALYSIS_MODEL, codexAnalysisIdentity } from "./codex-config.js";
-import { DEFAULT_ANALYSIS_MAX_OUTPUT_TOKENS, MAX_ANALYSIS_OUTPUT_TOKENS, isSupportedAnalysisModel, } from "./execute.js";
+import { DEFAULT_ANALYSIS_MAX_OUTPUT_TOKENS, MAX_ANALYSIS_OUTPUT_TOKENS, analysisCostRange, isSupportedAnalysisModel, } from "./execute.js";
+import { ADMISSION_MARGIN } from "./admission.js";
+import { plural } from "../run/text.js";
 import { containsSensitive } from "../evidence/redaction.js";
 export const DEFAULT_ANALYSIS_TIMEOUT_MS = 600_000;
 const MAX_ANALYSIS_TIMEOUT_MS = 600_000;
@@ -111,25 +113,38 @@ export function resolveAutomaticAnalysis(raw) {
         ...(value.maxOutputTokens === undefined ? { preferLargerOutput: true } : {}),
     };
 }
-/** Metadata only: resolving the future live-run budget never reads keys or dispatches. */
-export function automaticAnalysisBudget(raw, route) {
+/** Metadata only: resolving the future live-run budget never reads keys or dispatches. With a
+ * participant count it also gives the expected cost range for that many participants. */
+export function automaticAnalysisBudget(raw, route, participants) {
     // 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;
+    if (!resolved.ok || !resolved.config)
+        return undefined;
+    const { config } = resolved;
+    const range = participants === undefined || config.provider === "codex"
+        ? undefined
+        : analysisCostRange(resolved.preferLargerOutput
+            ? { ...config, maxOutputTokens: MAX_ANALYSIS_OUTPUT_TOKENS }
+            : config, participants);
+    return {
+        ...(config.provider === "codex"
+            ? { provider: "codex", billing: "account-unknown" }
+            : {}),
+        model: config.model,
+        maxCostUsd: config.maxCostUsd,
+        trigger: raw === undefined ? "default" : "explicit",
+        ...(range === undefined || participants === undefined
+            ? {}
+            : { participants, expectedCostUsd: range }),
+    };
 }
 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} · refused before it starts if its estimate is over $${budget.maxCostUsd}; this is not a billing cap. Set review.analysis: false to disable.`;
+    const range = budget.expectedCostUsd === undefined || budget.participants === undefined
+        ? ""
+        : ` · expected $${budget.expectedCostUsd.low.toFixed(2)} to $${budget.expectedCostUsd.high.toFixed(2)} for ${plural(budget.participants, "participant")}, depending on how much evidence the run keeps`;
+    return `After live runs: ${budget.trigger} analysis · ${budget.model}${range} · refused before it starts if the expected cost plus a ${Math.round((ADMISSION_MARGIN - 1) * 100)}% margin is over $${budget.maxCostUsd}; this is not a billing cap. Set review.analysis: false to disable.`;
 }

package/dist/analysis/automatic.js

@@ -5,6 +5,7 @@ import { refreshObserver, analyzeRun, readCompletedAnalysisSource, resolveAnalys
 import { preferLargerAnalysisOutput, ANALYSIS_PROMPT_VERSION } from "./execute.js";
 import { captureEvidence } from "./evidence.js";
 import { hashAnalysisValue } from "./validation.js";
+import { refusedCost } from "./admission.js";
 import { claimAutomaticAnalysis, readAutomaticAnalysisPrepared, requestAutomaticAnalysisCancellationPrepared, } from "./job.js";
 import { ANALYSIS_ID_PATTERN } from "./types.js";
 import { readAnalysisVersion } from "./store.js";
@@ -105,6 +106,11 @@ async function readAutomaticSource(cwd, prepared, configInput, deps, hasKey) {
         return skipped("AUTOMATIC_ANALYSIS_SOURCE_UNAVAILABLE");
     }
 }
+/** The cost of an analysis admission refused for its cost, kept so review and Observer can say it. */
+function withRefusedCost(result) {
+    const cost = result?.admission && refusedCost(result.admission);
+    return cost ? { admission: cost } : {};
+}
 /**
  * Bind the job's terminal metadata to the exact safely published execution. Reads never promote a
  * completed-looking sidecar without rechecking these bindings. Null when storage failed.
@@ -130,6 +136,7 @@ async function persistOutcome(job, prepared, outcome) {
                     receiptSha256: hashAnalysisValue(receipt),
                 }),
             ...(entry?.analysis ? { analysisSha256: hashAnalysisValue(entry.analysis) } : {}),
+            ...withRefusedCost(outcome.result),
         });
         const persisted = await readAutomaticAnalysisPrepared(prepared);
         return persisted?.state === "unknown"

package/dist/analysis/execute.d.ts

@@ -9,9 +9,19 @@ export declare const MAX_ANALYSIS_OUTPUT_TOKENS = 32768;
 export interface AnalysisAdmission {
     allowed: boolean;
     error: string | null;
+    /** The input tokens admission priced. */
     inputTokenAllowance: number | null;
     outputTokenAllowance: number | null;
+    /** The expected cost. Admission compares it, with a margin, with maxCostUsd. */
     estimatedCostUsd: number | null;
+    /** The cost if the analyst spends its whole output allowance. */
+    worstCaseCostUsd: number | null;
+    /**
+     * The expected cost plus the margin, or the worst case when that is lower: the figure admission
+     * compares with maxCostUsd, so the smallest cap that admits this analysis.
+     */
+    admittedCostUsd: number | null;
+    maxCostUsd: number | null;
     ratesAsOf: string | null;
 }
 export interface AnalysisProgress {
@@ -23,15 +33,24 @@ export interface AnalysisProgress {
 }
 /**
  * Local admission estimate, not a provider-enforced billed-spend guarantee. No token-count API
- * call, credential, or network access. One UTF-8 byte/token for all text/schema plus framing is
- * intentionally conservative. Each high-detail image is priced from its PNG size by the vision
- * guide's patch formula (see image-tokens.ts), or at the 3,000-token ceiling when its size or the
- * model's sizing is unknown. Unknown models/rates fail closed rather than inheriting those
- * assumptions.
+ * call, credential, or network access. admission.ts holds the cost model: text at a calibrated
+ * bytes-per-token ratio, the expected output, and the worst case that spends the whole output
+ * allowance. Each high-detail image is priced from its PNG size by the vision guide's patch
+ * formula (see image-tokens.ts), or at the 3,000-token ceiling when its size or the model's sizing
+ * is unknown. Unknown models/rates fail closed rather than inheriting those assumptions.
  * Known-sensitive decoded text denies admission with analysis_input_sensitive or
  * analysis_question_sensitive. Neither error includes rejected input values.
  */
 export declare function estimateAnalysisAdmission(input: AnalysisInput, config: AnalysisConfig): AnalysisAdmission;
+/**
+ * The expected cost of an analysis for this many participants before any evidence exists: from a
+ * packet with no evidence to one at the evidence limits with every capture at the image-token
+ * ceiling. Undefined for Codex and for a model without rates.
+ */
+export declare function analysisCostRange(config: AnalysisConfig, participants: number): {
+    low: number;
+    high: number;
+} | undefined;
 /** Only for an omitted output limit. Preserve the established allowance when
  * more reasoning/report space would refuse a study its declared budget admits.
  * This is one pre-dispatch choice, never a fallback request or a budget increase. */

package/dist/analysis/execute.js

@@ -1,5 +1,6 @@
 import { validCodexAnalysisConfig } from "./codex-config.js";
-import { highDetailImageTokens } from "./image-tokens.js";
+import { HIGH_DETAIL_IMAGE_TOKEN_CEILING, highDetailImageTokens } from "./image-tokens.js";
+import { estimateAnalysisCost } from "./admission.js";
 import { createHash, randomUUID } from "node:crypto";
 import { estimateActorCost, MODEL_RATES } from "../run/pricing.js";
 import { containsSensitive } from "../evidence/redaction.js";
@@ -128,11 +129,11 @@ function inputError(input) {
 }
 /**
  * Local admission estimate, not a provider-enforced billed-spend guarantee. No token-count API
- * call, credential, or network access. One UTF-8 byte/token for all text/schema plus framing is
- * intentionally conservative. Each high-detail image is priced from its PNG size by the vision
- * guide's patch formula (see image-tokens.ts), or at the 3,000-token ceiling when its size or the
- * model's sizing is unknown. Unknown models/rates fail closed rather than inheriting those
- * assumptions.
+ * call, credential, or network access. admission.ts holds the cost model: text at a calibrated
+ * bytes-per-token ratio, the expected output, and the worst case that spends the whole output
+ * allowance. Each high-detail image is priced from its PNG size by the vision guide's patch
+ * formula (see image-tokens.ts), or at the 3,000-token ceiling when its size or the model's sizing
+ * is unknown. Unknown models/rates fail closed rather than inheriting those assumptions.
  * Known-sensitive decoded text denies admission with analysis_input_sensitive or
  * analysis_question_sensitive. Neither error includes rejected input values.
  */
@@ -143,6 +144,9 @@ export function estimateAnalysisAdmission(input, config) {
         inputTokenAllowance: 0,
         outputTokenAllowance: 0,
         estimatedCostUsd: null,
+        worstCaseCostUsd: null,
+        admittedCostUsd: null,
+        maxCostUsd: null,
         ratesAsOf: null,
     });
     if ((config.provider === "codex"
@@ -174,6 +178,9 @@ export function estimateAnalysisAdmission(input, config) {
             inputTokenAllowance: null,
             outputTokenAllowance: null,
             estimatedCostUsd: null,
+            worstCaseCostUsd: null,
+            admittedCostUsd: null,
+            maxCostUsd: null,
             ratesAsOf: null,
         };
     const rate = MODEL_RATES[config.model];
@@ -184,32 +191,57 @@ export function estimateAnalysisAdmission(input, config) {
         !Number.isFinite(rate.outputUsdPerToken) ||
         rate.outputUsdPerToken < 0)
         return denied("analysis_rate_unknown");
-    const inputTokenAllowance = Buffer.byteLength(JSON.stringify({
-        instructions: instructions(config),
-        evidence: evidenceText(input),
-        schema: analysisResultJsonSchema,
-    })) +
-        2048 +
-        input.images.reduce((sum, image) => sum + highDetailImageTokens(config.model, image.dataUrl), 0);
-    const long = rate.longContext !== undefined && inputTokenAllowance > rate.longContext.thresholdInputTokens;
-    const inputRate = Math.max(rate.inputUsdPerToken, rate.cacheWriteUsdPerToken ?? 0, rate.cachedInputUsdPerToken ?? 0);
-    const estimate = inputTokenAllowance * inputRate * (long ? rate.longContext.inputMultiplier : 1) +
-        config.maxOutputTokens *
-            rate.outputUsdPerToken *
-            (long ? rate.longContext.outputMultiplier : 1);
-    // Round upward for admission; rounding a small positive boundary down could admit an overrun.
-    const estimatedCostUsd = Math.ceil(estimate * 1e6) / 1e6;
-    if (!Number.isFinite(estimatedCostUsd))
+    const cost = estimateAnalysisCost(rate, {
+        textBytes: Buffer.byteLength(instructions(config)) +
+            Buffer.byteLength(evidenceText(input)) +
+            Buffer.byteLength(JSON.stringify(analysisResultJsonSchema)),
+        imageTokens: input.images.reduce((sum, image) => sum + highDetailImageTokens(config.model, image.dataUrl), 0),
+        participants: input.participants.length,
+        outputAllowance: config.maxOutputTokens,
+    });
+    if (!Number.isFinite(cost.worstCaseCostUsd))
         return denied("analysis_rate_unknown");
+    const allowed = cost.admittedCostUsd <= config.maxCostUsd;
     return {
-        allowed: estimatedCostUsd <= config.maxCostUsd,
-        error: estimatedCostUsd <= config.maxCostUsd ? null : "analysis_budget_exceeded",
-        inputTokenAllowance,
+        allowed,
+        error: allowed ? null : "analysis_budget_exceeded",
+        inputTokenAllowance: cost.inputTokens,
         outputTokenAllowance: config.maxOutputTokens,
-        estimatedCostUsd,
+        estimatedCostUsd: cost.expectedCostUsd,
+        worstCaseCostUsd: cost.worstCaseCostUsd,
+        admittedCostUsd: cost.admittedCostUsd,
+        maxCostUsd: config.maxCostUsd,
         ratesAsOf: rate.asOf,
     };
 }
+/** Structure each evidence entry adds to the packet: ids, kind, timestamps and flags. The largest
+ * retained packet averaged 200 bytes. */
+const ENTRY_STRUCTURE_BYTES = 256;
+/**
+ * The expected cost of an analysis for this many participants before any evidence exists: from a
+ * packet with no evidence to one at the evidence limits with every capture at the image-token
+ * ceiling. Undefined for Codex and for a model without rates.
+ */
+export function analysisCostRange(config, participants) {
+    if (config.provider === "codex")
+        return undefined;
+    const rate = MODEL_RATES[config.model];
+    if (!rate || rate.placeholder)
+        return undefined;
+    const prompt = Buffer.byteLength(instructions(config)) +
+        Buffer.byteLength(JSON.stringify(analysisResultJsonSchema));
+    const size = {
+        participants: Math.min(participants, EVIDENCE_LIMITS.participants),
+        outputAllowance: config.maxOutputTokens,
+    };
+    const low = estimateAnalysisCost(rate, { ...size, textBytes: prompt, imageTokens: 0 });
+    const high = estimateAnalysisCost(rate, {
+        ...size,
+        textBytes: prompt + EVIDENCE_LIMITS.textBytes + EVIDENCE_LIMITS.evidence * ENTRY_STRUCTURE_BYTES,
+        imageTokens: EVIDENCE_LIMITS.captures * HIGH_DETAIL_IMAGE_TOKEN_CEILING,
+    });
+    return { low: low.expectedCostUsd, high: high.expectedCostUsd };
+}
 /** Only for an omitted output limit. Preserve the established allowance when
  * more reasoning/report space would refuse a study its declared budget admits.
  * This is one pre-dispatch choice, never a fallback request or a budget increase. */
@@ -464,9 +496,11 @@ function settleCompletedOutput(artifact, input, config, admission, response, onR
     artifact.result = checked.result;
     artifact.status = input.coverage.complete ? "complete" : "partial";
     artifact.error = null;
+    // A bill above the expected cost is a normal outcome. Only one above the worst case or the cap
+    // shows the estimate was wrong.
     if (config.provider !== "codex" &&
         ((response.usage?.output ?? 0) > config.maxOutputTokens ||
-            (artifact.usage.estimatedCostUsd ?? 0) > (admission.estimatedCostUsd ?? config.maxCostUsd) ||
+            (artifact.usage.estimatedCostUsd ?? 0) > (admission.worstCaseCostUsd ?? config.maxCostUsd) ||
             (artifact.usage.estimatedCostUsd ?? 0) > config.maxCostUsd)) {
         artifact.status = "partial";
         artifact.error = "analysis_admission_estimate_exceeded";