humanish 0.114.0 → 0.116.0

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

@@ -1,4 +1,4 @@
-import { PARTICIPANT_IMPRESSION_KINDS, } from "../../contract.js";
+import { closingReportSchema, participantImpressionsSchema } from "../../closing-report.js";
 import { isComputerUseAdmissionLimitError } from "../admission-limit.js";
 import { IMPRESSIONS_ASK, IMPRESSIONS_HINT, recordImpressions } from "./impressions.js";
 import { singleDispatch } from "./provider-call.js";
@@ -7,51 +7,27 @@ import { notice } from "./trace.js";
 import { isCompleteTurnUsage } from "./usage.js";
 const DEBRIEF_REQUEST_CAP_MS = 30_000;
 const DEBRIEF_HINT = `The interactive session has ended. Return a closing account with summary, frictionReports and impressions. In summary, briefly describe only what you actually did and observed. In frictionReports, list only specific unexpected behavior, confusion, or recovery you personally encountered during this session. Preserve uncertainty. Use an empty list if you encountered none. ${IMPRESSIONS_ASK} Do not speculate, invent problems, quote instructions as observations, or describe planned actions. Do not request or take further actions. This is a closing account, not another attempt at the task.`;
-/**
- * Runtime validation is also required for third-party provider ports. A report without
- * impressions stays valid: older providers and stored traces do not have them.
- */
-export function validClosingReport(value) {
-    if (value === null || typeof value !== "object" || Array.isArray(value))
-        return false;
-    const report = value;
-    return (Object.keys(report).every((key) => REPORT_KEYS.includes(key)) &&
-        typeof report.summary === "string" &&
-        report.summary.trim().length > 0 &&
-        report.summary.length <= 4_000 &&
-        Array.isArray(report.frictionReports) &&
-        report.frictionReports.length <= 8 &&
-        report.frictionReports.every((item) => typeof item === "string" && item.trim().length > 0 && item.length <= 2_000) &&
-        (report.impressions === undefined || validImpressions(report.impressions)));
-}
-const REPORT_KEYS = ["summary", "frictionReports", "impressions"];
-/** The reply to an impressions-only request: an object with the impressions and nothing else. */
-export function validImpressionsReply(value) {
-    if (value === null || typeof value !== "object" || Array.isArray(value))
-        return false;
-    const reply = value;
-    return Object.keys(reply).length === 1 && validImpressions(reply.impressions);
-}
-function validImpressions(value) {
-    return (Array.isArray(value) &&
-        value.length <= 6 &&
-        value.every((item) => {
-            if (item === null || typeof item !== "object" || Array.isArray(item))
-                return false;
-            const { kind, text, ...rest } = item;
-            return (Object.keys(rest).length === 0 &&
-                PARTICIPANT_IMPRESSION_KINDS.some((known) => known === kind) &&
-                typeof text === "string" &&
-                text.trim().length > 0 &&
-                text.length <= 500);
-        }));
-}
+const CLOSING_REPORT = {
+    call: (provider) => provider.debrief,
+    contextHint: DEBRIEF_HINT,
+    noticeLabel: "debrief",
+    deadlineLabel: "closing report",
+    read: readClosingReport,
+};
+const IMPRESSIONS_ONLY = {
+    call: (provider) => provider.requestImpressions,
+    contextHint: IMPRESSIONS_HINT,
+    noticeLabel: "impressions request",
+    deadlineLabel: "impressions request",
+    read: readImpressions,
+};
 /**
  * Ask the participant for its closing report after a structured stop, or for its impressions only
  * after it ended the session itself, or record why the request was skipped. Either way the result
  * is the trace's debrief, and the watcher gets a final flush.
  */
 export async function requestDebrief(session, context, trigger) {
+    const ask = trigger.kind === "participant_end" ? IMPRESSIONS_ONLY : CLOSING_REPORT;
     const record = (status, detail, usageReported) => {
         const debrief = {
             trigger: trigger.kind,
@@ -59,23 +35,23 @@ export async function requestDebrief(session, context, trigger) {
             reason: session.redactNarration(detail),
             ...(usageReported === undefined ? {} : { usageReported }),
         };
-        session.trace.record("notice", () => notice(status === "completed" ? "ok" : "warn", `participant ${trigger.kind === "participant_end" ? "impressions request" : "debrief"} ${status}`, session.redactNarration(detail)));
+        session.trace.record("notice", () => notice(status === "completed" ? "ok" : "warn", `participant ${ask.noticeLabel} ${status}`, session.redactNarration(detail)));
         return debrief;
     };
-    const plan = planDebrief(session, trigger);
+    const plan = planDebrief(session, ask, trigger);
     const debrief = "skip" in plan
         ? record("skipped", plan.skip)
-        : await debriefExchange(session, plan.ask, context, trigger, plan.boundMs, record);
+        : await debriefExchange(session, context, trigger, ask, plan, record);
     session.flush();
     return debrief;
 }
-function planDebrief(session, trigger) {
+function planDebrief(session, ask, trigger) {
     const { provider, signal, usage } = session;
     const { maxUsd, overRunBudget, estimateTurnCostUsd } = session.settings;
     if (session.trace.counts.turns === 0)
         return { skip: "the study stopped before any participant turn" };
-    const ask = trigger.kind === "participant_end" ? provider.requestImpressions : provider.debrief;
-    if (ask === undefined)
+    const send = ask.call(provider)?.bind(provider);
+    if (send === undefined)
         return { skip: "this provider does not support read-only closing reports" };
     if (usage.cleanupUnconfirmed)
         return { skip: "participant request cleanup is unconfirmed" };
@@ -107,9 +83,9 @@ function planDebrief(session, trigger) {
             skip: signal?.aborted ? "the study was cancelled" : "the session deadline was reached",
         };
     }
-    return { ask, boundMs };
+    return { send, boundMs };
 }
-async function debriefExchange(session, ask, context, trigger, boundMs, record) {
+async function debriefExchange(session, context, trigger, ask, { send, boundMs }, record) {
     const { signal, provider } = session;
     const scope = requestScope(signal);
     const timer = setTimeout(() => scope.end(), boundMs);
@@ -128,12 +104,12 @@ async function debriefExchange(session, ask, context, trigger, boundMs, record)
             ...(context.acknowledgedSafetyChecks === undefined
                 ? {}
                 : { acknowledgedSafetyChecks: context.acknowledgedSafetyChecks }),
-            contextHint: trigger.kind === "participant_end" ? IMPRESSIONS_HINT : DEBRIEF_HINT,
+            contextHint: ask.contextHint,
         };
         const turn = provider.requestPolicy === "fail_closed"
-            ? await singleDispatch(session, "debrief", (dispatchSignal) => ask.call(provider, request, dispatchSignal), boundMs)
-            : await raceSessionDeadline(ask.call(provider, request, scope.signal), boundMs, signal);
-        return acceptDebriefTurn(session, turn, trigger, record);
+            ? await singleDispatch(session, "debrief", (dispatchSignal) => send(request, dispatchSignal), boundMs)
+            : await raceSessionDeadline(send(request, scope.signal), boundMs, signal);
+        return acceptDebriefTurn(session, turn, ask, record);
     }
     catch (error) {
         // A failed optional report cannot rewrite the already observed structured completion.
@@ -143,7 +119,7 @@ async function debriefExchange(session, ask, context, trigger, boundMs, record)
         const detail = signal?.aborted
             ? "cancelled"
             : scope.signal.aborted || error instanceof CuaDeadlineError
-                ? `${trigger.kind === "participant_end" ? "impressions request" : "closing report"} deadline reached`
+                ? `${ask.deadlineLabel} deadline reached`
                 : error instanceof Error
                     ? error.message
                     : String(error);
@@ -156,7 +132,7 @@ async function debriefExchange(session, ask, context, trigger, boundMs, record)
         scope.end();
     }
 }
-function acceptDebriefTurn(session, turn, trigger, record) {
+function acceptDebriefTurn(session, turn, ask, record) {
     const { maxUsd, overRunBudget, estimateTurnCostUsd } = session.settings;
     session.usage.record(turn, "debrief");
     session.lastResponseId = turn.responseId ?? session.lastResponseId;
@@ -171,22 +147,23 @@ function acceptDebriefTurn(session, turn, trigger, record) {
     if (turn.actions.length > 0 || turn.pendingSafetyChecks.length > 0) {
         return record("failed", "the closing response requested actions or safety checks; none were executed and its report was not accepted", usageReported);
     }
-    if (trigger.kind === "participant_end") {
-        if (!validImpressions(turn.impressions)) {
-            return record("failed", turn.interruption === "output_limit"
-                ? "the reply was cut off by the output limit"
-                : "the reply did not contain valid impressions", usageReported);
-        }
-        session.impressions = recordImpressions(session, turn.impressions);
-        return record("completed", "one read-only impressions request; no additional desktop actions; the participant's own ending is unchanged", usageReported);
-    }
-    if (!validClosingReport(turn.closingReport)) {
-        return record("failed", "the closing response did not contain a valid structured participant report", usageReported);
+    // First-party providers parse their replies already; these parses cover third-party ports.
+    const { status, detail, ...added } = ask.read(session, turn);
+    return { ...record(status, detail, usageReported), ...added };
+}
+/** A closing report: its summary and friction as one participant message, then its impressions. */
+function readClosingReport(session, turn) {
+    const closing = closingReportSchema.safeParse(turn.closingReport);
+    if (!closing.success) {
+        return {
+            status: "failed",
+            detail: "the closing response did not contain a valid structured participant report",
+        };
     }
     const report = {
-        summary: session.redactNarration(turn.closingReport.summary.trim()),
+        summary: session.redactNarration(closing.data.summary.trim()),
         frictionReports: [
-            ...new Set(turn.closingReport.frictionReports.map((text) => session.redactNarration(text.trim()))),
+            ...new Set(closing.data.frictionReports.map((text) => session.redactNarration(text.trim()))),
         ],
     };
     const messageId = session.trace.record("message", () => ({
@@ -195,7 +172,28 @@ function acceptDebriefTurn(session, turn, trigger, record) {
         text: [report.summary, ...report.frictionReports].join("\n\n"),
     }));
     session.trace.bump("messages");
-    session.impressions = recordImpressions(session, turn.closingReport.impressions);
-    const debrief = record("completed", "one read-only report; no additional desktop actions; original stop and task outcomes preserved", usageReported);
-    return { ...debrief, report, messageId };
+    session.impressions = recordImpressions(session, closing.data.impressions);
+    return {
+        status: "completed",
+        detail: "one read-only report; no additional desktop actions; original stop and task outcomes preserved",
+        report,
+        messageId,
+    };
+}
+/** Impressions alone, after the participant ended the session itself. */
+function readImpressions(session, turn) {
+    const impressions = participantImpressionsSchema.safeParse(turn.impressions);
+    if (!impressions.success) {
+        return {
+            status: "failed",
+            detail: turn.interruption === "output_limit"
+                ? "the reply was cut off by the output limit"
+                : "the reply did not contain valid impressions",
+        };
+    }
+    session.impressions = recordImpressions(session, impressions.data);
+    return {
+        status: "completed",
+        detail: "one read-only impressions request; no additional desktop actions; the participant's own ending is unchanged",
+    };
 }

package/dist/actors/computer-use/loop/impressions.d.ts

@@ -1,9 +1,9 @@
 import type { ActorTrace, ParticipantImpression, ParticipantImpressions } from "../../contract.js";
 import type { LoopSession } from "./session.js";
 /** The closing-account request for impressions, shared by every provider that writes one. */
-export declare const IMPRESSIONS_ASK = "In impressions, list up to six things you noticed about the product itself, each in the first person and about something you saw in this session. Give each one a kind: unclear when something looked confusing or hard to read; unfinished when something looked broken, unpolished or out of place; untrustworthy when something made you hesitate to trust the product; liked when something worked well or felt good; missing when you expected something and did not find it; unlike_my_work when the screen differs from how you do the same task in your own work or life, only if your persona does this task outside this product. Keep each under 500 characters. Use an empty list if you have none.";
+export declare const IMPRESSIONS_ASK: string;
 /** The request after the participant ended the session itself without giving impressions. */
-export declare const IMPRESSIONS_HINT = "The interactive session has ended. Return only impressions. In impressions, list up to six things you noticed about the product itself, each in the first person and about something you saw in this session. Give each one a kind: unclear when something looked confusing or hard to read; unfinished when something looked broken, unpolished or out of place; untrustworthy when something made you hesitate to trust the product; liked when something worked well or felt good; missing when you expected something and did not find it; unlike_my_work when the screen differs from how you do the same task in your own work or life, only if your persona does this task outside this product. Keep each under 500 characters. Use an empty list if you have none. Do not speculate, invent problems, quote instructions as observations, or describe planned actions. Do not request or take further actions.";
+export declare const IMPRESSIONS_HINT: string;
 /**
  * Record a closing account's impressions as quotable participant messages. They answer the
  * harness's question, so they leave counts.messages, which the hollow-completion rule reads, alone.

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

@@ -1,8 +1,13 @@
+import { CLOSING_REPORT_LIMITS } from "../../closing-report-limits.js";
 // A participant's impressions: what it says about the product at the end of a session, beyond
 // friction. Each one is recorded as its own message so the analysis can quote and cite it as a
 // participant statement, and the trace says why none were collected when a session has none.
+// The limits are spelled out in the ask, so the participant is told the numbers its reply is
+// checked against. Counts up to ten are written as words.
+const COUNT_WORDS = "zero one two three four five six seven eight nine ten".split(" ");
+const inWords = (count) => COUNT_WORDS[count] ?? String(count);
 /** The closing-account request for impressions, shared by every provider that writes one. */
-export const IMPRESSIONS_ASK = "In impressions, list up to six things you noticed about the product itself, each in the first person and about something you saw in this session. Give each one a kind: unclear when something looked confusing or hard to read; unfinished when something looked broken, unpolished or out of place; untrustworthy when something made you hesitate to trust the product; liked when something worked well or felt good; missing when you expected something and did not find it; unlike_my_work when the screen differs from how you do the same task in your own work or life, only if your persona does this task outside this product. Keep each under 500 characters. Use an empty list if you have none.";
+export const IMPRESSIONS_ASK = `In impressions, list up to ${inWords(CLOSING_REPORT_LIMITS.impressions)} things you noticed about the product itself, each in the first person and about something you saw in this session. Give each one a kind: unclear when something looked confusing or hard to read; unfinished when something looked broken, unpolished or out of place; untrustworthy when something made you hesitate to trust the product; liked when something worked well or felt good; missing when you expected something and did not find it; unlike_my_work when the screen differs from how you do the same task in your own work or life, only if your persona does this task outside this product. Keep each under ${CLOSING_REPORT_LIMITS.impressionChars} characters. Use an empty list if you have none.`;
 /** The request after the participant ended the session itself without giving impressions. */
 export const IMPRESSIONS_HINT = `The interactive session has ended. Return only impressions. ${IMPRESSIONS_ASK} Do not speculate, invent problems, quote instructions as observations, or describe planned actions. Do not request or take further actions.`;
 /**

package/dist/actors/computer-use/loop.d.ts

@@ -2,7 +2,6 @@ import type { CuaLoopOptions, CuaLoopResult, LoopRunOptions } from "./loop/types
 export type { CuaAction, CuaExecutor, CuaLiveMetadata, CuaLoopOptions, CuaLoopResult, CuaObservation, CuaProvider, CuaSafetyCheck, CuaSpendGate, CuaTurn, CuaTurnRequest, ShortenedWait, } from "./loop/types.js";
 export { describeCuaAction } from "./loop/actions.js";
 export { stableProgressKey } from "./loop/backstop.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

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

@@ -1,7 +1,8 @@
+import { closingReportSchema } from "../closing-report.js";
 import { ComputerUseProviderError } from "./provider-error.js";
 import { runActionBatch } from "./loop/actions.js";
 import { advanceBackstop, startBackstop } from "./loop/backstop.js";
-import { requestDebrief, validClosingReport } from "./loop/debrief.js";
+import { requestDebrief } from "./loop/debrief.js";
 import * as stops from "./loop/ending.js";
 import { declaredOutcomeOf } from "./loop/ending.js";
 import { notCollected, recordImpressions } from "./loop/impressions.js";
@@ -14,7 +15,6 @@ 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, 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
@@ -120,7 +120,7 @@ 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;
+            const report = closingReportSchema.safeParse(turn.closingReport).data;
             // 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 =

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 {

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 {

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. */
@@ -399,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/actors/scripted-browser/steps.js

@@ -6,7 +6,7 @@ import os from "node:os";
 import path from "node:path";
 import { assertScreenshotEvidence, stripPngMetadataChunks } from "../../evidence/image.js";
 import { digestText, redactToSecretLabel } from "../../evidence/redaction.js";
-import { assertPreparedSelectedOutputDirectory, assertSafeOutputPathSegment, prepareContainedOutputFile, prepareSelectedOutputDirectory, readContainedRegularFile, writeContainedOutputFile, } from "../../run/contained-output.js";
+import { assertPreparedSelectedOutputDirectory, assertSafeOutputPathSegment, prepareContainedOutputFile, prepareSelectedOutputDirectory, readContainedRegularFile, refusalText, RUN_ARTIFACT_MAX_BYTES, writeContainedOutputFile, } from "../../run/contained-output.js";
 import { LOOPBACK_EVIDENCE_URL_POLICY, } from "./types.js";
 export async function executeBrowserPersonaStep(args) {
     const started = Date.now();
@@ -402,11 +402,12 @@ async function captureScriptedPageScreenshot(page) {
         if (Buffer.isBuffer(returned) || returned instanceof Uint8Array) {
             return stripPngMetadataChunks(browserScreenshotBytes(returned));
         }
-        const stagedBytes = await readContainedRegularFile(stagingRoot, "capture.png");
-        if (!stagedBytes) {
+        const staged = await readContainedRegularFile(stagingRoot, "capture.png", RUN_ARTIFACT_MAX_BYTES);
+        if (staged.status === "missing")
             throw new Error("Browser screenshot did not return bytes or write a single-link staging file.");
-        }
-        return stripPngMetadataChunks(stagedBytes);
+        if (staged.status === "refused")
+            throw new Error(`Browser screenshot did not return bytes, and ${refusalText("its staging file capture.png", staged)}.`);
+        return stripPngMetadataChunks(staged.bytes);
     }
     finally {
         await assertPreparedSelectedOutputDirectory(stagingRoot)

package/dist/analysis/admission.d.ts

@@ -24,10 +24,20 @@ export interface RefusedAnalysisCost {
     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;
+/** 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;

package/dist/analysis/admission.js

@@ -1,5 +1,5 @@
-// The admission cost model for one study analysis request: the expected cost, the worst case, and
-// the figure admission compares with the cap.
+// 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
@@ -40,13 +40,18 @@ export function estimateAnalysisCost(rate, size) {
         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.`;
+/**
+ * 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) {

package/dist/analysis/analysis-limits.d.ts

@@ -0,0 +1,35 @@
+/**
+ * How much an analysis result may hold, for the fields the Observer checks as well. Characters are
+ * counted as `String.length` counts them.
+ */
+export declare const ANALYSIS_LIMITS: Readonly<{
+    /** A label: a finding's title and headline, a design finding's headline and screen, or a name. */
+    labelChars: 240;
+    experienceChars: 1200;
+    noticeChars: 1500;
+    whyItMattersChars: 1000;
+    suggestionChars: 1000;
+    /** Evidence one observation or design finding may cite. */
+    evidenceRefs: 100;
+    findings: 100;
+    designFindings: 40;
+    concernReviews: 60;
+}>;
+/** Whether text holds a control character other than tab, line feed and carriage return. */
+export declare function hasControlCharacter(text: string): boolean;
+/** The parts of an analysis result the revision boundaries read. */
+interface RevisionFields {
+    readonly concernReviews?: unknown;
+    readonly designFindings?: unknown;
+    readonly findings: ReadonlyArray<{
+        readonly headline?: unknown;
+        readonly experience?: unknown;
+    }>;
+}
+/**
+ * Whether a result carries every field its prompt revision requires: concern reviews from
+ * study-evidence-5, and headlines, experiences and design findings from study-evidence-7. A prompt
+ * version without a study-evidence revision number requires none of them.
+ */
+export declare function hasRevisionFields(promptVersion: string, result: RevisionFields): boolean;
+export {};

package/dist/analysis/analysis-limits.js

@@ -0,0 +1,41 @@
+// The analysis result's limits and prompt revision boundaries, kept apart from the zod schemas in
+// validation.ts so the Observer can read them: it bundles this module, and zod stays out of its
+// page.
+/**
+ * How much an analysis result may hold, for the fields the Observer checks as well. Characters are
+ * counted as `String.length` counts them.
+ */
+export const ANALYSIS_LIMITS = Object.freeze({
+    /** A label: a finding's title and headline, a design finding's headline and screen, or a name. */
+    labelChars: 240,
+    experienceChars: 1200,
+    noticeChars: 1500,
+    whyItMattersChars: 1000,
+    suggestionChars: 1000,
+    /** Evidence one observation or design finding may cite. */
+    evidenceRefs: 100,
+    findings: 100,
+    designFindings: 40,
+    concernReviews: 60,
+});
+/** Whether text holds a control character other than tab, line feed and carriage return. */
+export function hasControlCharacter(text) {
+    return /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(text);
+}
+// The prompt revision from which a result must carry each field. A boundary stays where it is when
+// the prompt version advances, so a later prompt cannot bring back a legacy omission.
+const CONCERN_REVIEWS_FROM = 5;
+const HEADLINES_AND_DESIGN_FINDINGS_FROM = 7;
+/**
+ * Whether a result carries every field its prompt revision requires: concern reviews from
+ * study-evidence-5, and headlines, experiences and design findings from study-evidence-7. A prompt
+ * version without a study-evidence revision number requires none of them.
+ */
+export function hasRevisionFields(promptVersion, result) {
+    const revision = Number(/^study-evidence-(\d+)$/.exec(promptVersion)?.[1] ?? 0);
+    if (revision >= CONCERN_REVIEWS_FROM && result.concernReviews === undefined)
+        return false;
+    return (revision < HEADLINES_AND_DESIGN_FINDINGS_FROM ||
+        (result.designFindings !== undefined &&
+            result.findings.every((finding) => finding.headline !== undefined && finding.experience !== undefined)));
+}

package/dist/analysis/execute.d.ts

@@ -16,6 +16,11 @@ export interface AnalysisAdmission {
     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;
 }