humanish 0.112.0 → 0.114.0

package/dist/actors/computer-use/loop.js

@@ -1,9 +1,10 @@
 import { ComputerUseProviderError } from "./provider-error.js";
 import { runActionBatch } from "./loop/actions.js";
 import { advanceBackstop, startBackstop } from "./loop/backstop.js";
-import { requestDebrief } from "./loop/debrief.js";
+import { requestDebrief, validClosingReport } from "./loop/debrief.js";
 import * as stops from "./loop/ending.js";
 import { declaredOutcomeOf } from "./loop/ending.js";
+import { notCollected, recordImpressions } from "./loop/impressions.js";
 import { DesktopObserver } from "./loop/observation.js";
 import { retryAfterOutputLimit } from "./loop/output-limit.js";
 import { requestTurn } from "./loop/provider-call.js";
@@ -13,7 +14,8 @@ import { accountBillingConflicts } from "./loop/usage.js";
 import { loopResult, notice } from "./loop/trace.js";
 export { describeCuaAction } from "./loop/actions.js";
 export { stableProgressKey } from "./loop/backstop.js";
-export { validClosingReport } from "./loop/debrief.js";
+export { validClosingReport, validImpressionsReply } from "./loop/debrief.js";
+export { IMPRESSIONS_ASK } from "./loop/impressions.js";
 /**
  * Drive the loop to one explicit completion and return its CuaLoopResult: status, completion
  * reason, public reason and ActorTrace. Model-authored text passes through redactNarration before
@@ -118,8 +120,18 @@ async function runTurns(session, conversation) {
             // The declared outcome is kept even if redacting the participant's summary fails.
             session.declaredOutcome = declaredOutcomeOf(turn);
             const ended = stops.participantEnded(turn, session.declaredOutcome, (text) => session.redactNarration(text));
+            const report = validClosingReport(turn.closingReport) ? turn.closingReport : undefined;
+            // A provider that can ask for impressions alone does so after the session, like a debrief.
+            if (report?.impressions !== undefined || session.provider.requestImpressions === undefined) {
+                session.impressions =
+                    report === undefined
+                        ? notCollected("the participant ended the session without a structured closing account")
+                        : recordImpressions(session, report.impressions);
+            }
             await observer.observeFinalTasks(turnNumber);
-            return ended;
+            return session.impressions === undefined
+                ? { ...ended, debriefTrigger: { kind: "participant_end", observation } }
+                : ended;
         }
         const batch = await runActionBatch(session, turn.actions, turn.shortenedWaits);
         conversation.previousExecution = batch.execution;

package/dist/actors/computer-use/openai-conversation.d.ts

@@ -1,6 +1,6 @@
 import type { CuaTurn, CuaTurnRequest } from "./loop.js";
 import type { ReasoningEffort } from "../reasoning-effort.js";
-import type { ActorConversation } from "../contract.js";
+import { type ActorConversation } from "../contract.js";
 import { type OpenAiReasoningSummary } from "./openai-wire.js";
 /** How a conversation starts. The model settings stay fixed for the whole session. */
 export interface OpenAiConversationSettings {
@@ -30,6 +30,11 @@ export interface ConversationRequest {
 }
 /** Which answer told the provider that the organization keeps no server-side conversation. */
 export type ZdrRejection = NonNullable<ActorConversation["rejection"]>;
+/**
+ * What a closing request asks for: the closing report after a harness-owned stop, or only
+ * impressions after the participant ended the session itself.
+ */
+export type ClosingRequest = "report" | "impressions";
 export declare class OpenAiConversation {
     private readonly settings;
     private lastResponseId;
@@ -46,9 +51,9 @@ export declare class OpenAiConversation {
     constructor(settings: OpenAiConversationSettings);
     /**
      * The next request, carrying `req`'s screen: the opening request, or the outputs the latest
-     * reply's computer calls are owed. A closing report asks for a strict JSON report and no tools.
+     * reply's computer calls are owed. A closing request asks for strict JSON and no tools.
      */
-    request(req: CuaTurnRequest, closing?: boolean): ConversationRequest;
+    request(req: CuaTurnRequest, closing?: ClosingRequest): ConversationRequest;
     /**
      * The organization rejected server-side state: carry the conversation on the client from the
      * request being sent, and record which answer made the switch. False when the conversation is
@@ -80,7 +85,7 @@ export declare class OpenAiConversation {
      * ahead of `sent`.
      */
     private turnBody;
-    /** The read-only closing report: no tools, a small output limit, a strict schema. */
+    /** A read-only closing request: no tools, its own output limit, a strict schema. */
     private closingBody;
     /**
      * Move the conversation on to a reply to a request that added `sent`. A participant reply cut

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

@@ -1,7 +1,51 @@
+import { PARTICIPANT_IMPRESSION_KINDS } from "../contract.js";
 import { CarriedConversation, estimateTokens } from "./openai-context.js";
 import { buildCallOutput, buildContinuationRequest, buildInitialRequest, hintItems, openingMessage, parseOpenAiResponse, } from "./openai-wire.js";
-/** The closing report's output limit: its own cap, or the declared limit when that is lower. */
-const CLOSING_OUTPUT_LIMIT = 1024;
+/**
+ * The closing request's output limit: its own cap, or the declared limit when that is lower. It
+ * 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,
+            },
+        },
+    },
+    impressions: {
+        type: "json_schema",
+        name: "participant_impressions",
+        strict: true,
+        schema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["impressions"],
+            properties: { impressions: IMPRESSIONS_SCHEMA },
+        },
+    },
+};
 export class OpenAiConversation {
     settings;
     lastResponseId;
@@ -23,12 +67,12 @@ export class OpenAiConversation {
     }
     /**
      * The next request, carrying `req`'s screen: the opening request, or the outputs the latest
-     * reply's computer calls are owed. A closing report asks for a strict JSON report and no tools.
+     * reply's computer calls are owed. A closing request asks for strict JSON and no tools.
      */
-    request(req, closing = false) {
+    request(req, closing) {
         const sent = this.newItems(req);
         return {
-            body: () => (closing ? this.closingBody(req, sent) : this.turnBody(req, sent)),
+            body: () => closing === undefined ? this.turnBody(req, sent) : this.closingBody(req, sent, closing),
             accept: (reply) => this.accept(reply, closing, sent),
         };
     }
@@ -110,28 +154,13 @@ export class OpenAiConversation {
             ...(this.mode === "explicit_context" ? { explicitContextItems: this.carried.carried() } : {}),
         });
     }
-    /** The read-only closing report: no tools, a small output limit, a strict schema. */
-    closingBody(req, sent) {
+    /** A read-only closing request: no tools, its own output limit, a strict schema. */
+    closingBody(req, sent, closing) {
         return {
             ...this.turnBody(req, sent),
             tool_choice: "none",
             max_output_tokens: Math.min(this.settings.maxOutputTokens ?? CLOSING_OUTPUT_LIMIT, CLOSING_OUTPUT_LIMIT),
-            text: {
-                format: {
-                    type: "json_schema",
-                    name: "participant_closing_report",
-                    strict: true,
-                    schema: {
-                        type: "object",
-                        additionalProperties: false,
-                        required: ["summary", "frictionReports"],
-                        properties: {
-                            summary: { type: "string" },
-                            frictionReports: { type: "array", items: { type: "string" } },
-                        },
-                    },
-                },
-            },
+            text: { format: CLOSING_FORMATS[closing] },
         };
     }
     /**
@@ -142,10 +171,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;
@@ -177,10 +206,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();
@@ -188,6 +218,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 } from "./loop.js";
+import { validClosingReport, validImpressionsReply } from "./loop.js";
 import { ComputerUseAdmissionLimitError, isComputerUseAdmissionLimitError, } from "./admission-limit.js";
 import { ComputerUsePromptRefusedError } from "./provider-error.js";
 import { OpenAiConversation, } from "./openai-conversation.js";
@@ -455,21 +455,24 @@ export function createOpenAiResponsesProvider(options) {
             }
         }
     };
-    const requestTurn = async (req, signal, closing = false, spend) => {
+    const requestTurn = async (req, signal, closing, spend) => {
         await capture.prepareNext();
         const request = conversation.request(req, closing);
-        // A closing report makes exactly one request: no HTTP or policy-latch retries.
-        const raw = closing
-            ? await post(request.body(), signal, 0, false)
-            : await postTurn(request, signal, spend);
+        // A closing request makes exactly one request: no HTTP or policy-latch retries.
+        const raw = closing === undefined
+            ? await postTurn(request, signal, spend)
+            : await post(request.body(), signal, 0, false);
         const turn = request.accept(raw);
-        if (closing) {
+        if (closing !== undefined) {
             // Refusals, incomplete output, malformed JSON, and invalid shapes remain no-report results.
             // Never promote raw JSON or a fallback paragraph into a structured finding.
             try {
-                const report = JSON.parse(turn.message ?? "");
-                if (asRecord(raw).status === "completed" && validClosingReport(report)) {
-                    return { ...turn, closingReport: report };
+                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 };
                 }
             }
             catch {
@@ -496,15 +499,18 @@ export function createOpenAiResponsesProvider(options) {
         get interactionUsageIncomplete() {
             return interactionUsageIncomplete;
         },
-        nextTurn: (req, signal, spend) => requestTurn(req, signal, false, spend),
+        nextTurn: (req, signal, spend) => requestTurn(req, signal, undefined, spend),
         get conversation() {
             return conversation.record();
         },
         // A retrospective report reads the session the server holds; see serverHoldsSession.
         get debrief() {
             return conversation.serverHoldsSession
-                ? (req, signal) => requestTurn(req, signal, true)
+                ? (req, signal) => requestTurn(req, signal, "report")
                 : undefined;
         },
+        // Offered in both modes. An explicit_context conversation carries its newest screens whole and
+        // earlier turns as text, which serves impressions; a closing report needs the whole session.
+        requestImpressions: (req, signal) => requestTurn(req, signal, "impressions"),
     };
 }

package/dist/actors/contract.d.ts

@@ -186,7 +186,37 @@ export declare function validActorProviderRequests(value: unknown): value is Act
 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. */
+    messageId: string;
+}
+/**
+ * The impressions a session collected, or why it collected none. An empty `items` list means the
+ * participant had none to give.
+ */
+export type ParticipantImpressions = {
+    status: "collected";
+    items: RecordedImpression[];
+} | {
+    status: "not_collected";
+    reason: string;
+};
 /** Runtime declarations and executable-version observations; not provider request attestation. */
 export interface ActorRuntimeProvenance {
     schema: "humanish.actor-runtime.v1";
@@ -231,11 +261,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;
@@ -315,17 +347,27 @@ export interface ActorTrace {
      * each fixed a false refusal and each left the next shape unhandled.
      */
     declaredOutcome?: ParticipantDeclaredOutcome;
-    /** Closing report after a harness-owned stop. Does not change task outcomes or permit actions. */
+    /**
+     * The read-only closing request: a closing report after a harness-owned stop (`stop_when`,
+     * `dwell`), or impressions only after the participant ended the session itself
+     * (`participant_end`, never with `report`). Does not change task outcomes or permit actions.
+     */
     debrief?: {
-        trigger: "stop_when" | "dwell";
+        trigger: "stop_when" | "dwell" | "participant_end";
         status: "completed" | "skipped" | "failed";
         reason: string;
         /** Absent if no request was made; false means token accounting is incomplete. */
         usageReported?: boolean;
-        report?: ParticipantClosingReport;
+        /** The report's impressions are kept in `impressions`, with the messages that quote them. */
+        report?: Omit<ParticipantClosingReport, "impressions">;
         /** Links the readable projection so it is not heuristically classified a second time. */
         messageId?: string;
     };
+    /**
+     * What the participant said about the product at the end of a computer-use session, or why
+     * nothing was collected. Absent on other routes and on older traces.
+     */
+    impressions?: ParticipantImpressions;
     items: ActorTraceItem[];
     tokenUsage?: ActorTokenUsage;
     /** A stalled or adapter-reported ambiguous interaction may have additional unreported usage.

package/dist/actors/contract.js

@@ -168,6 +168,19 @@ 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,37 @@
+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;
+}
+/** The --max-cost that admits a refused analysis: its worst case, rounded up to a whole dollar. */
+export declare function admittingMaxCost(cost: RefusedAnalysisCost): number;
+/** Why admission refused an analysis, in plain words. */
+export declare function costRefusalText(cost: RefusedAnalysisCost): string;
+/** 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,60 @@
+// The admission cost model for one study analysis request: the expected cost, the worst case, and
+// the figure admission compares with the cap.
+/**
+ * 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)),
+    };
+}
+/** The --max-cost that admits a refused analysis: its worst case, rounded up to a whole dollar. */
+export function admittingMaxCost(cost) {
+    return Math.max(1, Math.ceil(cost.worstCaseCostUsd));
+}
+/** Why admission refused an analysis, in plain words. */
+export function costRefusalText(cost) {
+    return `The expected cost is $${cost.expectedCostUsd.toFixed(2)} and the worst case is $${cost.worstCaseCostUsd.toFixed(2)}. With a ${Math.round((ADMISSION_MARGIN - 1) * 100)}% margin the expected cost is over the $${cost.maxCostUsd} cap, so no request was sent.`;
+}
+/** 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/evidence-sources.d.ts

@@ -20,4 +20,6 @@ export interface SourceEntry {
 export declare function sourceEntries(bundle: RunBundle, stream: RunStream, captureVersion?: CaptureVersion): SourceEntry[];
 /** Max-min allocation; stable ID order breaks a remainder tie by at most one slot. */
 export declare function fairShares(budget: number, capacities: number[]): number[];
-export declare function sourceOrder(entries: SourceEntry[], capturesOnly: boolean): SourceEntry[];
+/** The trace messages that carry a participant's closing impressions. */
+export declare function impressionEventIds(stream: RunStream): ReadonlySet<string>;
+export declare function sourceOrder(entries: SourceEntry[], capturesOnly: boolean, impressions?: ReadonlySet<string>): SourceEntry[];