humanish 0.107.0 → 0.109.0

package/dist/actors/codex/restricted-participant.js

@@ -1,6 +1,6 @@
-import { isRecordedCodexCliVersion, } from "../contract.js";
-import { defaultCodexCliVersion } from "./qualified-versions.js";
-import { CuaProviderError, isCuaProviderError, } from "../computer-use/provider-error.js";
+import {} from "../contract.js";
+import { defaultCodexCliVersion, untestedOperatorReleaseWarning } from "./codex-admission.js";
+import { ComputerUseProviderError, isComputerUseProviderError, } from "../computer-use/provider-error.js";
 import { validateBrowserControlPng, validateHeardSpeech } from "../../browser-control/protocol.js";
 import { createRestrictedCodexSession, } from "./restricted-session.js";
 import { PARTICIPANT_PROFILE, PARTICIPANT_LIMITS as L, PARTICIPANT_FINAL_SCHEMA, participantToolSchema, parseParticipantTool, parseParticipantFinal, } from "./restricted-participant-policy.js";
@@ -38,6 +38,7 @@ function deferred() {
     void promise.catch(() => undefined);
     return { promise, resolve, reject };
 }
+// prose-check: model prompt (Codex reads this tool description, not a person)
 const toolDescription = (speechEnabled) => `Act on the participant's browser through humanish. Submit one to four UI actions${speechEnabled ? ", including speak when you need to reply aloud," : ""} and a short public comment; never private reasoning. humanish returns a JSON STRING with execution acknowledgments${speechEnabled ? ", speech heard from the actual participant speaker sink," : ""} and a fresh screenshot. In Code Mode use: const r = JSON.parse(await tools.humanish_ui({narration: "...", actions: [...]})); text({acknowledgments: r.acknowledgments${speechEnabled ? ", heardSpeech: r.heardSpeech" : ""}, contextHint: r.contextHint, closing: r.closing}); image(r.imageUrl). Call serially and inspect each returned screenshot${speechEnabled ? " and heardSpeech array" : ""} before deciding what to do next.${speechEnabled ? " Use speak only after the visible UI shows that you joined the call and your microphone is unmuted; it sends audio into that call." : ""} Acknowledged input does not prove an application outcome. If closing is true, stop calling tools and give your final account.`;
 const participantInstructions = (prompt, speechEnabled) => `${prompt}\n\nYou are the study participant throughout this conversation, including its closing account. Use only the supplied screenshots and humanish_ui tool to interact. The tool returns a JSON string: parse it, inspect acknowledgments${speechEnabled ? " and heardSpeech captured from the actual participant speaker sink" : ""}, and display imageUrl with Code Mode image(). Do not print the image data URL as text. Keep your persona and earlier observations throughout the session.${speechEnabled ? " A speak action plays into the participant microphone; use it only after the visible UI shows that you joined the call and the microphone is unmuted." : ""} Speak publicly about your experience, never reveal private reasoning. Completed inputs do not prove application outcomes; verify on the next screenshot. When the task ends, return only the required final JSON with outcome, summary and frictionReports. Report observed confusion and recovered mistakes as well as blockers. Do not invent observations.`;
 /** Turns and failures from the native run, handed in order to the next provider request. */
@@ -149,15 +150,15 @@ const runReceipt = (result) => ({
  */
 function finalTurn(result, receipt, usage, stopped) {
     if (stopped.stopped)
-        throw new CuaProviderError(stopped.failedCleanup ? "cleanup_unconfirmed" : "cancelled", receipt, usage, result.failurePhase);
+        throw new ComputerUseProviderError(stopped.failedCleanup ? "cleanup_unconfirmed" : "cancelled", receipt, usage, result.failurePhase);
     if (result.status !== "completed" || result.errorCode !== null)
-        throw new CuaProviderError(codeOf(result.errorCode), receipt, usage, result.failurePhase);
+        throw new ComputerUseProviderError(codeOf(result.errorCode), receipt, usage, result.failurePhase);
     let turn;
     try {
         turn = parseParticipantFinal(result.output);
     }
     catch {
-        throw new CuaProviderError("invalid_response", receipt, usage, "response");
+        throw new ComputerUseProviderError("invalid_response", receipt, usage, "response");
     }
     return {
         ...turn,
@@ -238,8 +239,7 @@ export async function checkRestrictedCodexParticipantReadiness(options) {
  * An operator-auth session has one only once it resolved a model on a ChatGPT account.
  */
 function participantExecutionProfile(session, operator, effort) {
-    const detected = session.cliVersion;
-    const cliVersion = isRecordedCodexCliVersion(detected) ? detected : defaultCodexCliVersion();
+    const cliVersion = session.cliVersion ?? defaultCodexCliVersion();
     if (!operator)
         return { ...PARTICIPANT_PROFILE, cliVersion };
     return session.authentication === "chatgpt-account" && session.resolvedModel
@@ -284,8 +284,10 @@ function closeParticipantSession(state) {
     }));
 }
 /** What the closed native session reports beside cleanup: its run warnings and a late refusal. */
-function sessionReport(session) {
+function sessionReport(session, operator) {
     const warnings = [
+        // A resolved model means thread/start was admitted: the release actually launched.
+        untestedOperatorReleaseWarning(session.resolvedModel === undefined ? undefined : session.cliVersion, operator),
         session.protocolIncompatibilities === undefined
             ? undefined
             : protocolIncompatibilityMessage(session.cliVersion, session.protocolIncompatibilities),
@@ -338,9 +340,9 @@ function launchNativeRun(settings, state, req, imageUrl) {
         catch (error) {
             revokeParticipant(state);
             state.events.emit({
-                error: isCuaProviderError(error)
+                error: isComputerUseProviderError(error)
                     ? error
-                    : new CuaProviderError("process_failed", { dispatched: "unknown", usageComplete: false, cleanup: "unconfirmed" }, usage),
+                    : new ComputerUseProviderError("process_failed", { dispatched: "unknown", usageComplete: false, cleanup: "unconfirmed" }, usage),
             });
         }
         finally {
@@ -354,7 +356,7 @@ async function runParticipantTurn(settings, state, req, signal, debrief) {
         return state.events.next();
     if (signal.aborted) {
         revokeParticipant(state);
-        throw new CuaProviderError("cancelled", noDispatch());
+        throw new ComputerUseProviderError("cancelled", noDispatch());
     }
     const conversation = {
         instructions: state.instructions,
@@ -363,7 +365,7 @@ async function runParticipantTurn(settings, state, req, signal, debrief) {
         lastActionCount: state.lastActionCount,
     };
     if (rejectsParticipantRequest(req, conversation))
-        throw new CuaProviderError("request_rejected", noDispatch());
+        throw new ComputerUseProviderError("request_rejected", noDispatch());
     const onAbort = () => {
         revokeParticipant(state);
     };
@@ -380,7 +382,7 @@ async function runParticipantTurn(settings, state, req, signal, debrief) {
         else if (!state.active)
             launchNativeRun(settings, state, req, imageUrl);
         else
-            throw new CuaProviderError("busy", noDispatch());
+            throw new ComputerUseProviderError("busy", noDispatch());
         return await state.events.next();
     }
     finally {
@@ -424,7 +426,7 @@ function participantProvider(settings, state, start) {
 export function createRestrictedCodexParticipant(options = {}) {
     const timeoutMs = options.requestTimeoutMs ?? L.requestMs;
     if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > L.requestMs)
-        throw new CuaProviderError("request_rejected", noDispatch());
+        throw new ComputerUseProviderError("request_rejected", noDispatch());
     const operator = options.authMode === "operator";
     const speechEnabled = options.speechEnabled === true;
     const settings = {
@@ -456,9 +458,9 @@ export function createRestrictedCodexParticipant(options = {}) {
     let pending, closing;
     const start = (req, signal, debrief) => {
         if (state.closed && !state.events.waiting)
-            return Promise.reject(new CuaProviderError("request_rejected", noDispatch()));
+            return Promise.reject(new ComputerUseProviderError("request_rejected", noDispatch()));
         if (pending)
-            return Promise.reject(new CuaProviderError("busy", noDispatch()));
+            return Promise.reject(new ComputerUseProviderError("busy", noDispatch()));
         const task = runParticipantTurn(settings, state, req, signal, debrief);
         pending = task;
         void task
@@ -481,7 +483,7 @@ export function createRestrictedCodexParticipant(options = {}) {
                     state.failedCleanup = true;
                 return {
                     status: state.failedCleanup ? "unconfirmed" : "confirmed",
-                    ...sessionReport(state.session),
+                    ...sessionReport(state.session, settings.operator),
                 };
             })();
             return closing;

package/dist/actors/codex/restricted-policy.d.ts

@@ -1,8 +1,8 @@
 import type { ReasoningEffort } from "../reasoning-effort.js";
 /** Versioned, deliberately narrow profile qualified with an account-backed vision turn.
  * The CLI still advertises code-mode tools: disabling their host is the enforcement
- * boundary. Feature names alone are not proof that a tool has been removed. The admitted
- * CLI releases are per host, in qualified-versions.ts. */
+ * boundary. Feature names alone are not proof that a tool has been removed. Which CLI
+ * releases launch is decided in codex-admission.ts. */
 export declare const RESTRICTED_CODEX_ANALYSIS_IDENTITY: {
     readonly provider: "codex";
     readonly authMode: "chatgpt";

package/dist/actors/codex/restricted-policy.js

@@ -1,7 +1,7 @@
 /** Versioned, deliberately narrow profile qualified with an account-backed vision turn.
  * The CLI still advertises code-mode tools: disabling their host is the enforcement
- * boundary. Feature names alone are not proof that a tool has been removed. The admitted
- * CLI releases are per host, in qualified-versions.ts. */
+ * boundary. Feature names alone are not proof that a tool has been removed. Which CLI
+ * releases launch is decided in codex-admission.ts. */
 export const RESTRICTED_CODEX_ANALYSIS_IDENTITY = {
     provider: "codex",
     authMode: "chatgpt",

package/dist/actors/codex/restricted-session.d.ts

@@ -12,9 +12,9 @@ export interface RestrictedCodexSessionOptions {
     /** The release a caller already recorded (an analysis identity); any other release is refused. */
     cliVersion?: string;
     /**
-     * Bypasses qualification: replaces this host's admitted releases with any list. It exists only
-     * so scripts/codex-qualify.mjs can launch an unqualified candidate. No library export, lab
-     * manifest, CLI flag, RunLabOptions field or LabDeps seam reaches it
+     * Bypasses launch admission: admits exactly this list. It exists only so
+     * scripts/codex-qualify.mjs can launch a candidate admission would refuse. No library export, study
+     * manifest, CLI flag, RunStudyOptions field or StudyDeps seam reaches it
      * (tests/actors/codex/cli-versions-seam.test.ts).
      */
     cliVersions?: readonly string[];

package/dist/actors/codex/restricted-session.js

@@ -2,7 +2,7 @@ import { spawn } from "node:child_process";
 import { chmod, lstat, mkdir, mkdtemp, readdir, realpath, rm, unlink, writeFile, } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
 import path from "node:path";
-import { admittedCodexCliVersions } from "./qualified-versions.js";
+import { admitsCodexCliVersion, supportsIsolatedCodex } from "./codex-admission.js";
 import { launchAdmittedAppServer, } from "./restricted-launch.js";
 import { CODEX_IMAGE, CODEX_MAX_OUTPUT_BYTES, CODEX_MAX_REQUEST_BYTES, RESTRICTED_CODEX_ANALYSIS_MODELS, codexRecord, restrictedCodexFailure, restrictedCodexRequestError, } from "./restricted-policy.js";
 import { RestrictedCodexDeadline, RestrictedCodexStop, hasUnclosedChildren, retainUnclosedChild, } from "./restricted-transport.js";
@@ -312,11 +312,16 @@ function refusedRun(settings, state, request, busy) {
         return restrictedCodexFailure("codex_busy");
     const supportedPlatform = operatorAuth
         ? restrictedCodexNpmTarget(platform, arch) !== undefined
-        : (platform === "linux" && arch === "x64") || (platform === "darwin" && arch === "arm64");
+        : supportsIsolatedCodex(platform, arch);
     if (!supportedPlatform)
         return restrictedCodexFailure("codex_unsupported_platform");
     return undefined;
 }
+/** Which releases a session starts: launch admission, or the qualifier's exact list. */
+function launchAdmission(options) {
+    const exact = options.cliVersions;
+    return exact === undefined ? admitsCodexCliVersion : (version) => exact.includes(version);
+}
 export function createRestrictedCodexSession(options = {}) {
     // Option reads keep their old order: platform, arch, env, participant, spawnFn, cliVersions.
     const platform = options.platform ?? process.platform, arch = options.arch ?? process.arch;
@@ -331,7 +336,7 @@ export function createRestrictedCodexSession(options = {}) {
         operatorAuth: participant?.authMode === "operator",
         reasoningEffort: participant?.reasoningEffort ?? "low",
         spawnFn: options.spawnFn ?? ((file, args, spawnOptions) => spawn(file, args, spawnOptions)),
-        admittedVersions: options.cliVersions ?? admittedCodexCliVersions(platform, arch),
+        admits: launchAdmission(options),
     };
     const state = {
         work: undefined,
@@ -434,7 +439,7 @@ export async function checkRestrictedCodexSessionReadiness(input = {}, options =
  * `--version` runs with a private temporary home, removed afterwards. */
 export async function detectRestrictedCodexCliVersion(input = {}, options = {}) {
     const platform = options.platform ?? process.platform, arch = options.arch ?? process.arch;
-    if (!((platform === "linux" && arch === "x64") || (platform === "darwin" && arch === "arm64")))
+    if (!supportsIsolatedCodex(platform, arch))
         return { cliVersion: null, errorCode: "codex_unsupported_platform" };
     const sourceEnv = options.env ?? process.env;
     const deadline = new RestrictedCodexDeadline(input.timeoutMs ?? 15_000, input.signal);
@@ -444,7 +449,7 @@ export async function detectRestrictedCodexCliVersion(input = {}, options = {})
         work = await realpath(await mkdtemp(path.join(options.tempRoot ?? tmpdir(), "humanish-codex-version-")));
         const home = path.join(work, "home");
         await mkdir(home, { mode: 0o700 });
-        const cliVersion = await checkVersion(file, childEnvironment(sourceEnv, home, work), work, options.spawnFn ?? ((command, args, settings) => spawn(command, args, settings)), deadline, options.cliVersions ?? admittedCodexCliVersions(platform, arch), options.cliVersion);
+        const cliVersion = await checkVersion(file, childEnvironment(sourceEnv, home, work), work, options.spawnFn ?? ((command, args, settings) => spawn(command, args, settings)), deadline, launchAdmission(options), options.cliVersion);
         return { cliVersion, errorCode: null };
     }
     catch (error) {

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

@@ -4,13 +4,13 @@ import { type E2BDesktopExecutorOptions, type E2BDesktopLike } from "../../subst
 import { type OpenAiResponsesProviderOptions } from "./openai-provider.js";
 import { type RedactionHooks } from "../../evidence/redaction.js";
 import type { DwellWindow, StopWhen } from "../stop-conditions.js";
-import type { LabTask } from "../../lab/tasks.js";
+import type { StudyTask } from "../../study/tasks.js";
 export interface CuaActorSessionOptions {
     /** The composed mission (persona + scenario/participant instruction) handed to the model. */
     instructions: string;
     /** Provenance of the persona this actor embodies (id + applied traits + prompt digest). */
     persona: ActorPersonaRef;
-    /** Hard wall-clock runaway guard — the only count-free hard stop the loop honors. */
+    /** Hard wall-clock runaway guard: the only count-free hard stop the loop honors. */
     timeoutMs: number;
     signal?: AbortSignal;
     /** Live provider construction (used when `provider` is not injected). */
@@ -19,10 +19,10 @@ export interface CuaActorSessionOptions {
     desktop?: E2BDesktopLike;
     executorOptions?: E2BDesktopExecutorOptions;
     /**
-     * DI seams — inject to bypass live construction (CI uses these for zero-spend tests; library
-     * callers use them to drive a state-driven, non-vision flow). NOTE: a STATE executor (one
-     * whose observe() returns no screenshot — see CuaObservation.screenshot optional) MUST be
-     * paired with a NON-vision provider (requiresFrame falsey). The default OpenAI provider is
+     * DI seams: inject to bypass live construction (CI uses these for zero-spend tests; library
+     * callers use them to drive a state-driven, non-vision flow). NOTE: a state executor (one
+     * whose observe() returns no screenshot; see CuaObservation.screenshot optional) must be
+     * paired with a non-vision provider (requiresFrame falsey). The default OpenAI provider is
      * vision-based and would fail closed against a screenshot-less observation. See
      * docs/architecture/state-driven-executor.md.
      */
@@ -39,7 +39,7 @@ export interface CuaActorSessionOptions {
     idleSteps?: number;
     noProgressSteps?: number;
     /**
-     * Redact persisted screenshots (blur+downscale). Default FALSE — full fidelity for local use.
+     * Redact persisted screenshots (blur+downscale). Default `false`: full fidelity for local use.
      * Set true for unowned subjects or share-as-is bundles. The provider always sees raw frames.
      */
     redactScreenshots?: boolean;
@@ -49,29 +49,29 @@ export interface CuaActorSessionOptions {
     writeScreenshot?: (name: string, bytes: Buffer) => Promise<string>;
     /** Deterministic harness-owned stop guards evaluated between model turns. */
     stopWhen?: StopWhen;
-    /** A declared observation window (#510), forwarded to the loop. */
+    /** A declared observation window, forwarded to the loop. */
     dwell?: DwellWindow;
-    /** The lab's declared protocol; the loop records a corroborated task funnel on the trace (#414).
-     *  Only the `success` criteria are read here — the participant-facing goals are already composed
+    /** The study's declared protocol; the loop records a corroborated task funnel on the trace.
+     *  Only the `success` criteria are read here; the participant-facing goals are already composed
      *  into `instructions` upstream, and the criteria never reach the prompt. */
-    tasks?: readonly LabTask[];
-    /** FAIL-CLOSED spend cap (USD) threaded to the loop; absent = uncapped. See CuaLoopOptions.maxUsd. */
+    tasks?: readonly StudyTask[];
+    /** Fail-closed spend cap (USD) threaded to the loop; absent = uncapped. See CuaLoopOptions.maxUsd. */
     maxUsd?: number;
     /** Injected pure per-turn cost estimator paired with `maxUsd`. See CuaLoopOptions.estimateTurnCostUsd. */
     estimateTurnCostUsd?: (usage: ActorTokenUsage) => number | null;
-    /** RUN-LEVEL spend guard threaded to the loop (#299). See CuaLoopOptions.overRunBudget. */
+    /** Run-level spend guard threaded to the loop. See CuaLoopOptions.overRunBudget. */
     overRunBudget?: (usage: ActorTokenUsage) => string | null;
     /** Stricter unknown-usage policy for capped sessions (see CuaLoopOptions); it also makes the
      *  OpenAI provider send one HTTP dispatch per turn. Library-only. */
     requireReportedUsageForSpendCap?: boolean;
-    /** RUNTIME-ONLY observed-URL callback threaded to the loop; see CuaLoopOptions.onObservedUrl. Used by
-     *  the concurrent shared-world handoff barrier to latch a host seat's live /lobby/CODE URL. */
+    /** Runtime-only observed-URL callback threaded to the loop; see LoopTaps.onObservedUrl. Used by
+     *  the concurrent shared-world handoff barrier to latch a host's live /lobby/CODE URL. */
     onObservedUrl?: (url: string | undefined) => void;
-    /** RUNTIME-ONLY per-turn narration callback threaded to the loop; see CuaLoopOptions.onMessage. */
+    /** Runtime-only per-turn narration callback threaded to the loop; see LoopTaps.onMessage. */
     onMessage?: (text: string) => void;
-    /** RUNTIME-ONLY per-turn raw-frame callback threaded to the loop; see CuaLoopOptions.onScreenshot. */
+    /** Runtime-only per-turn raw-frame callback threaded to the loop; see LoopTaps.onScreenshot. */
     onScreenshot?: (frame: Buffer) => void;
-    /** Per-turn trace snapshot callback threaded to the loop (#441); see CuaLoopOptions.onTrace. */
+    /** Per-turn trace snapshot callback threaded to the loop; see CuaLoopOptions.onTrace. */
     onTrace?: (items: readonly ActorTraceItem[], usage: ActorTokenUsage, metadata?: CuaLiveMetadata) => void;
 }
 export declare function runCuaActorSession(options: CuaActorSessionOptions): Promise<CuaLoopResult>;

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

@@ -1,13 +1,13 @@
 // The registry-facing wrapper for the OpenAI Computer Use (CUA) actor. runComputerUseLoop needs
 // fully-constructed provider/executor instances; exposing that raw through the actor registry
 // would leak adapter construction to every call site. So runCuaActorSession takes intent-level
-// fields and constructs the provider/executor internally — with DI seams (provider/executor/now)
+// fields and constructs the provider/executor internally, with DI seams (provider/executor/now)
 // so CI can drive the real loop with fakes and zero network/zero spend (mirrors how the Claude
 // adapter injects its queryFn).
 //
 // The loop already returns a fully-formed ActorTrace at result.trace, so there is no separate
-// toActorTrace mapper — runCuaActorSession returns the CuaLoopResult unchanged.
-import { runComputerUseLoop, } from "./loop.js";
+// toActorTrace mapper: runCuaActorSession returns the CuaLoopResult unchanged.
+import { runComputerUseLoopWithTaps, } from "./loop.js";
 import { createE2BDesktopExecutor, } from "../../substrates/e2b/desktop-executor.js";
 import { createOpenAiResponsesProvider, } from "./openai-provider.js";
 import { defaultRedactionHooks } from "../../evidence/redaction.js";
@@ -55,7 +55,7 @@ export async function runCuaActorSession(options) {
         ...(options.onScreenshot === undefined ? {} : { onScreenshot: options.onScreenshot }),
         ...(options.onTrace === undefined ? {} : { onTrace: options.onTrace }),
     };
-    const result = await runComputerUseLoop(loopOptions);
+    const result = await runComputerUseLoopWithTaps(loopOptions);
     if (result.trace.executionProfile?.billing === "account-unknown") {
         result.trace.estimatedCost = estimateActorCostForExecution(result.trace.tokenUsage, result.trace.ids.model, result.trace.executionProfile);
     }

package/dist/actors/computer-use/admission-limit.d.ts

@@ -1,12 +1,12 @@
 /**
- * A caller's adapter refused this request BEFORE provider dispatch because a configured
+ * A caller's adapter refused this request before provider dispatch because a configured
  * local control limit was reached. This is an adapter declaration, not a provider response
  * or independent transport/billing attestation. Never use it for a dispatched request whose
  * outcome or usage is unknown. Import this class from the same humanish installation as the
  * loop/provider; names, message text and lookalike objects are not the contract.
  */
-export declare class CuaAdmissionLimitError extends Error {
+export declare class ComputerUseAdmissionLimitError extends Error {
     constructor();
 }
 /** Internal nominal check: neither a matching payload nor a forged prototype is a declaration. */
-export declare function isCuaAdmissionLimitError(error: unknown): error is CuaAdmissionLimitError;
+export declare function isComputerUseAdmissionLimitError(error: unknown): error is ComputerUseAdmissionLimitError;

package/dist/actors/computer-use/admission-limit.js

@@ -1,19 +1,19 @@
 const admissionLimits = new WeakSet();
 /**
- * A caller's adapter refused this request BEFORE provider dispatch because a configured
+ * A caller's adapter refused this request before provider dispatch because a configured
  * local control limit was reached. This is an adapter declaration, not a provider response
  * or independent transport/billing attestation. Never use it for a dispatched request whose
  * outcome or usage is unknown. Import this class from the same humanish installation as the
  * loop/provider; names, message text and lookalike objects are not the contract.
  */
-export class CuaAdmissionLimitError extends Error {
+export class ComputerUseAdmissionLimitError extends Error {
     constructor() {
         super("The adapter refused the request before provider dispatch because a local admission limit was reached.");
-        this.name = "CuaAdmissionLimitError";
+        this.name = "ComputerUseAdmissionLimitError";
         admissionLimits.add(this);
     }
 }
 /** Internal nominal check: neither a matching payload nor a forged prototype is a declaration. */
-export function isCuaAdmissionLimitError(error) {
+export function isComputerUseAdmissionLimitError(error) {
     return typeof error === "object" && error !== null && admissionLimits.has(error);
 }

package/dist/actors/computer-use/executor-error.d.ts

@@ -21,11 +21,11 @@ export declare function isCuaExecutorErrorCode(value: unknown): value is CuaExec
  * began; a lost acknowledgement or partial action is `outcome_uncertain`, never a retry.
  * Import from the same installation as the loop: names and lookalike objects do not qualify.
  */
-export declare class CuaExecutorError extends Error {
+export declare class ComputerUseExecutorError extends Error {
     readonly code: CuaExecutorErrorCode;
     readonly disposition: CuaExecutorDisposition;
     constructor(code: CuaExecutorErrorCode, disposition: CuaExecutorDisposition);
 }
 /** A forged prototype is not an executor declaration. */
-export declare function isCuaExecutorError(error: unknown): error is CuaExecutorError;
+export declare function isComputerUseExecutorError(error: unknown): error is ComputerUseExecutorError;
 export {};

package/dist/actors/computer-use/executor-error.js

@@ -22,7 +22,7 @@ const executorErrors = new WeakSet();
  * began; a lost acknowledgement or partial action is `outcome_uncertain`, never a retry.
  * Import from the same installation as the loop: names and lookalike objects do not qualify.
  */
-export class CuaExecutorError extends Error {
+export class ComputerUseExecutorError extends Error {
     code;
     disposition;
     constructor(code, disposition) {
@@ -31,7 +31,7 @@ export class CuaExecutorError extends Error {
             throw new TypeError("Invalid desktop executor error declaration.");
         }
         super(messages[code]);
-        this.name = "CuaExecutorError";
+        this.name = "ComputerUseExecutorError";
         this.code = code;
         this.disposition = disposition;
         // Keep the values used in durable diagnostics finite even for JavaScript callers.
@@ -43,6 +43,6 @@ export class CuaExecutorError extends Error {
     }
 }
 /** A forged prototype is not an executor declaration. */
-export function isCuaExecutorError(error) {
+export function isComputerUseExecutorError(error) {
     return typeof error === "object" && error !== null && executorErrors.has(error);
 }

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

@@ -3,10 +3,10 @@ import type { CuaAction, CuaTurnRequest } from "./types.js";
 /** A public-safe one-line action label. Never includes raw typed text. */
 export declare function describeCuaAction(action: CuaAction): string;
 /**
- * A public-safe fingerprint of ONE turn's actions, used only in memory to tell "trying the same
- * thing again" from "trying something new" (#383).
+ * A public-safe fingerprint of one turn's actions, used only in memory to tell "trying the same
+ * thing again" from "trying something new".
  *
- * Never includes typed text or key contents — a `type` contributes its LENGTH, exactly as
+ * Never includes typed text or key contents: a `type` contributes its length, exactly as
  * describeCuaAction does, so this can never become a keylogger. Coordinates are bucketed so that
  * re-clicking the same control counts as a repeat while moving to a different control does not.
  */

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

@@ -1,6 +1,6 @@
 import { classifyCuaAction } from "../../affordance.js";
 import { commandFailureInfo, isCommandExitError } from "../../../substrates/command-failure.js";
-import { CuaExecutorError, isCuaExecutorError } from "../executor-error.js";
+import { ComputerUseExecutorError, isComputerUseExecutorError } from "../executor-error.js";
 import { CuaAbortError, CuaDeadlineError, CuaStallError, raceCallBound, raceSessionDeadline, requestScope, } from "./race.js";
 import { notice } from "./trace.js";
 // The participant's actions: their public labels, what counts as a material action, and how one
@@ -47,10 +47,10 @@ function describeAction(action) {
     }
 }
 /**
- * A public-safe fingerprint of ONE turn's actions, used only in memory to tell "trying the same
- * thing again" from "trying something new" (#383).
+ * A public-safe fingerprint of one turn's actions, used only in memory to tell "trying the same
+ * thing again" from "trying something new".
  *
- * Never includes typed text or key contents — a `type` contributes its LENGTH, exactly as
+ * Never includes typed text or key contents: a `type` contributes its length, exactly as
  * describeCuaAction does, so this can never become a keylogger. Coordinates are bucketed so that
  * re-clicking the same control counts as a repeat while moving to a different control does not.
  */
@@ -121,8 +121,8 @@ export async function runActionBatch(session, actions) {
         if (actionHistory.recentActionTitles.length > RECENT_ACTION_TITLES)
             actionHistory.recentActionTitles.shift();
         trace.bump("actions");
-        // Classify BEFORE execute, mirroring counts.actions: the record is of what the actor
-        // CHOSE, so an action that then fails to actuate is still an honest record of the route
+        // Classify before execute, mirroring counts.actions: the record is of what the actor
+        // chose, so an action that then fails to actuate is still a record of the route
         // it reached for.
         actionHistory.affordances.push(classifyCuaAction(action));
         session.phase = `executing ${title}`;
@@ -131,7 +131,7 @@ export async function runActionBatch(session, actions) {
             status = await dispatchAction(session, action, title);
         }
         catch (error) {
-            const declared = isCuaExecutorError(error)
+            const declared = isComputerUseExecutorError(error)
                 ? error.disposition
                 : isCommandExitError(error)
                     ? "skipped"
@@ -139,7 +139,7 @@ export async function runActionBatch(session, actions) {
             if (declared !== undefined)
                 execution.actions.push({ index, status: declared });
             countAttempt(session, action, title, declared);
-            if (isCuaExecutorError(error) &&
+            if (isComputerUseExecutorError(error) &&
                 error.code === "action_rejected" &&
                 error.disposition === "not_dispatched") {
                 // Later actions may depend on this one (type, then submit). Return
@@ -150,10 +150,10 @@ export async function runActionBatch(session, actions) {
                 trace.record("notice", () => notice("warn", "action rejected before dispatch", session.redactNarration(`action: ${title}; code: action_rejected; disposition: not_dispatched; remaining batch actions not dispatched: ${actions.length - index - 1}`)));
                 return { execution, hint: rejectedActionHint(title) };
             }
-            if (isCuaExecutorError(error) || !isCommandExitError(error))
+            if (isComputerUseExecutorError(error) || !isCommandExitError(error))
                 throw error;
             // A skipped action changes nothing on screen, so a persistently-failing run makes no
-            // progress and still terminates honestly via the idle/no-progress backstop (gave_up),
+            // progress and still terminates via the idle/no-progress backstop (gave_up),
             // never a silent actor_error and never an infinite loop.
             recordCommandFailure(session, title, error);
             continue;
@@ -164,8 +164,8 @@ export async function runActionBatch(session, actions) {
             lifecycle: "completed",
             title,
             ...(action.kind === "speak" ? { text: session.redactNarration(action.text) } : {}),
-            // Structured pin coordinates (#441), exactly the click classes the Observer
-            // pins render — recorded fact instead of a title re-parse downstream.
+            // Structured pin coordinates, exactly the click classes the Observer
+            // pins render: recorded fact instead of a title re-parse downstream.
             ...(action.kind === "click" || action.kind === "double_click"
                 ? { coord: { x: action.x, y: action.y } }
                 : {}),
@@ -180,9 +180,9 @@ function countAttempt(session, action, title, status) {
     session.trace.counts.materialActions += 1;
 }
 /**
- * Execute one action. Idle actions only look (#480): a `wait` that hangs inside the SDK has in
+ * Execute one action. Idle actions only look: a `wait` that hangs inside the SDK has in
  * effect waited, so a stalled one is skipped with a notice and loses nothing the participant
- * chose. An action is recorded as completed only after execute() resolves (#248).
+ * chose. An action is recorded as completed only after execute() resolves.
  */
 async function dispatchAction(session, action, title) {
     if (!isIdleAction(action)) {
@@ -213,7 +213,7 @@ async function executeAction(session, action, title, boundMs) {
     }
     catch (error) {
         if (error instanceof CuaStallError && session.executor.stallRecovery === "fail_closed") {
-            throw new CuaExecutorError("deadline_exceeded", "outcome_uncertain");
+            throw new ComputerUseExecutorError("deadline_exceeded", "outcome_uncertain");
         }
         if (error instanceof CuaDeadlineError || error instanceof CuaAbortError) {
             // The loop's deadline/abort may win before the executor can report whether its

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

@@ -2,10 +2,10 @@ import type { CuaAction, CuaObservation } from "./types.js";
 /**
  * A deterministic, bounded, sorted-key projection of an appState object, used as the friction
  * loop's progress key. Two structurally-equal states (regardless of key insertion order) map
- * to the SAME string, so key reordering can never fabricate a progress delta; two different
+ * to the same string, so key reordering can never fabricate a progress delta; two different
  * states map to different strings (within the caps).
  *
- * Correctness-load-bearing: it MUST NOT throw on a cyclic or huge input. Cycles are detected
+ * Correctness depends on this: it must not throw on a cyclic or huge input. Cycles are detected
  * with a seen-set (a back-edge degrades to the marker "[Circular]"); depth, key count, array
  * length, string length, and total output length are all capped so an adversarial or merely
  * large appState degrades to a bounded value rather than crashing the loop. Pure: it never
@@ -14,7 +14,7 @@ import type { CuaAction, CuaObservation } from "./types.js";
 export declare function stableProgressKey(appState: Record<string, unknown>): string;
 export interface Backstop {
     readonly progressKey: string;
-    /** The last few turns' action fingerprints, in memory only, for the #383 corroboration rule. */
+    /** The last few turns' action fingerprints, in memory only, for the corroboration rule below. */
     readonly recentFingerprints: readonly string[];
     readonly consecutiveIdle: number;
     readonly consecutiveNoProgress: number;