humanish 0.108.0 → 0.109.0

package/dist/comms/setup.js

@@ -8,11 +8,10 @@ import { discoverProviderKeys, listUserKeys, probeKeySources, } from "../keys/ke
 import { COMMS_PROVIDERS, commsProviderLabel, DEFAULT_COMMS_PROVIDER, } from "./providers.js";
 import { createReceivingAdapter } from "./receiving-runtime.js";
 import { RECEIVING_SCOPE_UNSUPPORTED } from "./receiving-types.js";
-import { parseLabConfig } from "../lab/config.js";
-import { resolveLabManifest } from "../lab/discover.js";
+import { parseStudy } from "../study/config.js";
+import { resolveStudyManifest } from "../study/discover.js";
 import { assertPreparedSelectedOutputDirectory, prepareManagedHumanishOutputDirectory, prepareSelectedOutputDirectory, readContainedRegularFile, writeContainedOutputFile, } from "../run/contained-output.js";
 import { otherStudyFiles } from "../study/files.js";
-import { convertStudyText, isStudyV3 } from "../study/convert.js";
 import { isNodeError } from "../run/type-guards.js";
 export async function checkCommsConnection(args) {
     const base = {
@@ -109,65 +108,63 @@ export async function receivingRequiredKey(cwd, connectionName) {
     }
 }
 /** Save a local copy, never rewrite a committed manifest or silently shadow it by handle. */
-export async function configureCommsLab(args) {
+export async function configureCommsStudy(args) {
     const base = { schema: "humanish.comms-configure.v1", ok: false, applied: false };
     try {
         const connection = (await readCommsConnections(args.cwd)).connections[args.connection];
         if (!connection)
             return { ...base, message: "Save the selected connection first." };
-        const source = await resolveLabManifest(args.cwd, args.lab);
-        if (!source.ok)
-            return { ...base, message: "The selected lab could not be read safely." };
+        const source = await resolveStudyManifest(args.cwd, args.study);
+        if (!source.ok) {
+            // A v2 source or a labs/ file gets discovery's refusal, which names the fix.
+            const named = source.error.code === "HUMANISH_STUDY_V2_UNSUPPORTED" ||
+                source.error.code === "HUMANISH_STUDY_RETIRED_DIRECTORY";
+            return {
+                ...base,
+                message: named ? source.error.message : "The selected study could not be read safely.",
+            };
+        }
         const root = await prepareSelectedOutputDirectory(args.cwd, args.cwd);
         const rel = path
             .relative(root.requestedPath, path.resolve(args.cwd, source.path))
             .replace(/\\/g, "/");
         const bytes = await readContainedRegularFile(root, rel);
         if (!bytes || bytes.length > 1024 * 1024)
-            return { ...base, message: "The lab is missing or too large." };
+            return { ...base, message: "The study file is missing or too large." };
         const text = bytes.toString("utf8");
         const raw = parse(text);
         if (!raw || typeof raw !== "object" || Array.isArray(raw))
-            return { ...base, message: "The lab must be a mapping." };
-        const lab = raw;
-        const existing = lab.comms;
+            return { ...base, message: "The study file must be a mapping." };
+        const studyRecord = raw;
+        const existing = studyRecord.comms;
         if (existing?.email && existing.email.connection === undefined)
             return {
                 ...base,
-                message: "This lab uses local capture. Preserve it or make a separate lab before selecting real email.",
+                message: "This study uses local capture. Preserve it or make a separate study before selecting real email.",
             };
-        // The copy is a v3 study. A v2 source is converted first, so the copy keeps its comments.
-        let studyText = text;
-        if (!isStudyV3(raw)) {
-            const converted = convertStudyText(text, args.cwd);
-            if (!converted.ok)
-                return {
-                    ...base,
-                    message: `This lab could not be converted to a v3 study: ${converted.reason}`,
-                };
-            studyText = converted.conversion.text;
-        }
-        const study = parseDocument(studyText);
+        // Discovery resolved the source, so it is a v3 study, and the copy keeps its comments.
+        const study = parseDocument(text);
         study.setIn(["comms", "email", "connection"], args.connection);
-        const validated = parseLabConfig(study.toJS());
+        const validated = parseStudy(study.toJS());
         if (!validated.ok)
             return {
                 ...base,
-                message: "This lab does not support real email receiving. Use a hosted computer-use app-url, clone or local-tree route; shared-world must be concurrent.",
+                message: "This study does not support real email receiving. Use a hosted computer-use app-url, clone or local-tree route; shared-world must be concurrent.",
             };
         const filename = path
             .basename(source.path)
             .replace(/\.ya?ml$/, "")
             .replace(/-receiving$/, "") + "-receiving.yaml";
         if (!/^[A-Za-z0-9_][A-Za-z0-9._-]{0,110}\.yaml$/.test(filename))
-            return { ...base, message: "Use a simple lab filename before configuring email." };
+            return { ...base, message: "Use a simple study filename before configuring email." };
         const destination = `.humanish/local/studies/${filename}`;
         if (path.basename(rel) === filename)
             return {
                 ...base,
-                message: "This is already the local receiving copy. Select its original lab to configure a separate copy, or edit this manifest directly.",
+                message: "This is already the local receiving copy. Select its original study to configure a separate copy, or edit this study file directly.",
             };
-        // A second file with this name in another study directory would make discovery refuse both.
+        // A second file with this name in another study directory would shadow it, or take the name
+        // migrate needs to move a labs/ file.
         const stem = filename.replace(/\.yaml$/, "");
         const others = await otherStudyFiles(stem, 
         // Any directory entry counts, a dangling symbolic link included: discovery would see it too.
@@ -215,7 +212,7 @@ export async function configureCommsLab(args) {
         if (args.planToken !== undefined && args.planToken !== token)
             return {
                 ...base,
-                message: "The lab or destination changed since preview. Preview again before saving.",
+                message: "The study or destination changed since preview. Preview again before saving.",
             };
         const directory = await prepareManagedHumanishOutputDirectory(args.cwd, "local", "studies");
         const lockPath = path.join(directory.physicalPath, ".comms-configure.lock");
@@ -239,13 +236,13 @@ export async function configureCommsLab(args) {
         return {
             ...plan,
             applied: true,
-            message: `Saved ${destination}. Start that exact lab path; the original manifest was preserved.`,
+            message: `Saved ${destination}. Start that exact study path; the original file was preserved.`,
         };
     }
     catch {
         return {
             ...base,
-            message: "Could not configure this lab safely. Check configuration, paths and permissions; no provider resources were created.",
+            message: "Could not configure this study safely. Check configuration, paths and permissions; no provider resources were created.",
         };
     }
 }

package/dist/feedback/draft.js

@@ -100,7 +100,7 @@ export function buildDraft(bundle, bundlePath, candidateId) {
         proposed_next_state: "study-quality-review",
         acceptance_proof: [
             feedbackProofCommands(bundle.runId).verify,
-            feedbackProofCommands(bundle.runId).watch,
+            feedbackProofCommands(bundle.runId).observe,
         ],
     };
 }
@@ -192,7 +192,7 @@ export async function buildAnalysisDraft(context, options) {
         proposed_next_state: "study-quality-review",
         acceptance_proof: [
             feedbackProofCommands(bundle.runId).verify,
-            feedbackProofCommands(bundle.runId).watch,
+            feedbackProofCommands(bundle.runId).observe,
         ],
     };
 }

package/dist/feedback/export.js

@@ -23,6 +23,7 @@ import { analysisSharingProblems } from "../analysis/sharing.js";
 import { EVIDENCE_LIMITS, validateAnalysisEvidence } from "../analysis/evidence.js";
 import { readBoundedFile } from "../run/evidence-files.js";
 import { shellQuote } from "../substrates/shell.js";
+import { plural } from "../run/text.js";
 const EXPORT_SCHEMA = "humanish.export-result.v1";
 /** Past this the file stops being a thing you attach to an email. Declared, never silent. */
 export const DEFAULT_EXPORT_MAX_BYTES = 25 * 1024 * 1024;
@@ -361,7 +362,7 @@ export function formatExportHuman(result) {
     if (result.format === "bundle") {
         return [
             `humanish export ${result.runId}`,
-            `workspace: ${result.path} (${(result.bytes / 1024).toFixed(0)} KB, ${result.embeddedImages} blurred image(s))`,
+            `workspace: ${result.path} (${(result.bytes / 1024).toFixed(0)} KB, ${plural(result.embeddedImages, "blurred image")})`,
             `share safety: ${result.shareSafety.status}`,
             `verify: humanish verify --cwd ${shellQuote(result.path)} --run ${shellQuote(result.runId)}`,
             `feedback: humanish feedback draft --cwd ${shellQuote(result.path)} --run ${shellQuote(result.runId)}`,
@@ -371,7 +372,7 @@ export function formatExportHuman(result) {
     }
     const lines = [
         `humanish export ${result.runId}`,
-        `file: ${result.path} (${(result.bytes / 1024).toFixed(0)} KB, ${result.embeddedImages} image(s) embedded)`,
+        `file: ${result.path} (${(result.bytes / 1024).toFixed(0)} KB, ${plural(result.embeddedImages, "image")} embedded)`,
         `share safety: ${result.shareSafety.status}${result.watermarked ? " (watermarked: local only)" : ""}`,
         ...result.warnings.map((warning) => `warning: ${warning}`),
     ];

package/dist/feedback/proof.d.ts

@@ -2,7 +2,7 @@ import type { RunBundle, RunFeedbackCandidate } from "../run/bundle.js";
 /** Commands run from the evidence workspace using an installed humanish CLI. */
 export declare function feedbackProofCommands(runId: string): {
     verify: string;
-    watch: string;
+    observe: string;
 };
 /** Legacy command compatibility belongs in the draft, never in the source receipt. */
 export declare function projectFeedbackAcceptanceProof(bundle: RunBundle, candidate: RunFeedbackCandidate): string[];

package/dist/feedback/proof.js

@@ -5,7 +5,7 @@ export function feedbackProofCommands(runId) {
     const argument = /^[a-z0-9][a-z0-9._-]*$/i.test(runId) ? runId : shellQuote(runId);
     return {
         verify: `humanish verify --run ${argument} --json`,
-        watch: `humanish watch --run ${argument} --no-open`,
+        observe: `humanish observe --run ${argument} --no-open`,
     };
 }
 /** Legacy command compatibility belongs in the draft, never in the source receipt. */
@@ -17,7 +17,7 @@ export function projectFeedbackAcceptanceProof(bundle, candidate) {
         if (instruction === `pnpm humanish -- verify --run ${bundle.runId} --json`)
             return commands.verify;
         if (instruction === `pnpm humanish -- watch --run ${bundle.runId} --no-open`)
-            return commands.watch;
+            return commands.observe;
         return instruction;
     });
 }

package/dist/guest/bootstrap.js

@@ -1,6 +1,6 @@
 import { desktopRecordingConfigSchema, } from "../evidence/desktop-recording-types.js";
 import { validateBrowserControlIdentity, sameBrowserControlIdentity, } from "../browser-control/protocol.js";
-import { CuaExecutorError } from "../actors/computer-use/executor-error.js";
+import { ComputerUseExecutorError } from "../actors/computer-use/executor-error.js";
 import { createBrowserControlClient } from "../browser-control/client.js";
 import { guestMediaConfigSchema } from "./media-config.js";
 export const GUEST_BOOTSTRAP_VERSION = 1;
@@ -15,7 +15,7 @@ export const GUEST_BOOTSTRAP_LIMITS = Object.freeze({
     connectMs: 3000,
     port: 5251,
 });
-const refused = () => new CuaExecutorError("protocol_mismatch", "not_dispatched");
+const refused = () => new ComputerUseExecutorError("protocol_mismatch", "not_dispatched");
 /** Same entry authority as the local desktop's opaque app-port forward. */
 export function validateGuestInitialUrl(value) {
     try {
@@ -223,7 +223,7 @@ export class GuestBootstrapReader {
             return;
         this.terminal = true;
         this.release();
-        this.reject(new CuaExecutorError(code, "not_dispatched"));
+        this.reject(new ComputerUseExecutorError(code, "not_dispatched"));
         this.stream.destroy();
         this.onFailure();
     }
@@ -249,7 +249,7 @@ export async function connectGuestBootstrap(stream, identity, signal, initialUrl
     const request = encodeGuestBootstrap(identity, false, initialUrl, media, recording);
     await new Promise((resolve, reject) => {
         let bytes = Buffer.alloc(0), done = false;
-        const timer = setTimeout(() => finish(new CuaExecutorError("deadline_exceeded", "not_dispatched")), GUEST_BOOTSTRAP_LIMITS.connectMs);
+        const timer = setTimeout(() => finish(new ComputerUseExecutorError("deadline_exceeded", "not_dispatched")), GUEST_BOOTSTRAP_LIMITS.connectMs);
         const finish = (error) => {
             if (done)
                 return;
@@ -277,9 +277,9 @@ export async function connectGuestBootstrap(stream, identity, signal, initialUrl
         const end = () => {
             if (done)
                 stream.destroy();
-            finish(new CuaExecutorError("transport_failed", "not_dispatched"));
+            finish(new ComputerUseExecutorError("transport_failed", "not_dispatched"));
         };
-        const abort = () => finish(new CuaExecutorError("session_revoked", "not_dispatched"));
+        const abort = () => finish(new ComputerUseExecutorError("session_revoked", "not_dispatched"));
         const data = (chunk) => {
             if (!Buffer.isBuffer(chunk) || bytes.length + chunk.length > 64 + 1028) {
                 finish(refused());

package/dist/guest/browser-tools.js

@@ -1,5 +1,5 @@
 import { BROWSER_CONTROL_LIMITS } from "../browser-control/protocol.js";
-import { CuaExecutorError, isCuaExecutorError } from "../actors/computer-use/executor-error.js";
+import { ComputerUseExecutorError, isComputerUseExecutorError, } from "../actors/computer-use/executor-error.js";
 /** Owner-only composition for a single headed Chromium page. Never an actor API. */
 export function createGuestBrowserTools(native, content) {
     let addressBarArmed = false;
@@ -11,7 +11,7 @@ export function createGuestBrowserTools(native, content) {
             const inputGeneration = ++generation;
             await native.input(args, signal);
             if (signal.aborted || inputGeneration !== generation)
-                throw new CuaExecutorError("session_revoked", "outcome_uncertain");
+                throw new ComputerUseExecutorError("session_revoked", "outcome_uncertain");
             // Positive navigation intent, not an inference from document.hasFocus().
             addressBarArmed =
                 args.length === 3 &&
@@ -28,15 +28,15 @@ export function createGuestBrowserTools(native, content) {
             // separate qualification. Do not silently switch routes or transliterate.
             if (!/^[\x20-\x7e]+$/.test(text) ||
                 Buffer.byteLength(text) > BROWSER_CONTROL_LIMITS.textBytes) {
-                throw new CuaExecutorError("action_rejected", "not_dispatched");
+                throw new ComputerUseExecutorError("action_rejected", "not_dispatched");
             }
             const preparedGeneration = generation;
             let used = false;
             function check() {
                 if (signal.aborted)
-                    throw new CuaExecutorError("session_revoked", "not_dispatched");
+                    throw new ComputerUseExecutorError("session_revoked", "not_dispatched");
                 if (used || preparedGeneration !== generation)
-                    throw new CuaExecutorError("action_rejected", "not_dispatched");
+                    throw new ComputerUseExecutorError("action_rejected", "not_dispatched");
             }
             check();
             await content.assertReady(signal);
@@ -52,15 +52,15 @@ export function createGuestBrowserTools(native, content) {
                     try {
                         await native.input(["key", "--clearmodifiers", "ctrl+l"], signal);
                         if (signal.aborted)
-                            throw new CuaExecutorError("session_revoked", "outcome_uncertain");
+                            throw new ComputerUseExecutorError("session_revoked", "outcome_uncertain");
                         await content.assertReady(signal);
                         if (signal.aborted || preparedGeneration !== generation)
-                            throw new CuaExecutorError("session_revoked", "outcome_uncertain");
+                            throw new ComputerUseExecutorError("session_revoked", "outcome_uncertain");
                         await native.typeAscii(text, signal);
                     }
                     catch (error) {
                         // Ctrl+L itself is input. No content fallback after that dispatch.
-                        throw new CuaExecutorError(isCuaExecutorError(error) ? error.code : "execution_failed", "outcome_uncertain");
+                        throw new ComputerUseExecutorError(isComputerUseExecutorError(error) ? error.code : "execution_failed", "outcome_uncertain");
                     }
                 },
                 async close() {

package/dist/guest/chromium-text.js

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { CuaExecutorError, isCuaExecutorError } from "../actors/computer-use/executor-error.js";
+import { ComputerUseExecutorError, isComputerUseExecutorError, } from "../actors/computer-use/executor-error.js";
 const DEADLINE_MS = 5_000;
 // These expressions execute only in this port's isolated world. Actor text is
 // never interpolated into JavaScript, a selector, a world name, or a CDP method.
@@ -103,16 +103,16 @@ function unwatchTargetEvents(settings, handlers) {
 function checkScope(settings, state, expected) {
     const { context, page } = settings;
     if (state.closed || state.unusable)
-        throw new CuaExecutorError("executor_closed", "not_dispatched");
+        throw new ComputerUseExecutorError("executor_closed", "not_dispatched");
     if (state.generation !== expected)
-        throw new CuaExecutorError("session_revoked", "not_dispatched");
+        throw new ComputerUseExecutorError("session_revoked", "not_dispatched");
     const pages = context.pages();
     if (state.dialogSeen ||
         page.isClosed() ||
         page.context() !== context ||
         pages.length !== 1 ||
         pages[0] !== page)
-        throw new CuaExecutorError("action_rejected", "not_dispatched");
+        throw new ComputerUseExecutorError("action_rejected", "not_dispatched");
 }
 /**
  * One bounded operation: a 5 s deadline, the caller's abort, and any interrupt race every step.
@@ -133,7 +133,7 @@ async function runOperation(settings, state, signal, expected, body) {
             return;
         stopped = code;
         controller.abort();
-        rejectStop(new CuaExecutorError(code, dispatched ? "outcome_uncertain" : "not_dispatched"));
+        rejectStop(new ComputerUseExecutorError(code, dispatched ? "outcome_uncertain" : "not_dispatched"));
     };
     const abort = () => interrupt("cancelled");
     const timer = setTimeout(() => interrupt("deadline_exceeded"), DEADLINE_MS);
@@ -143,7 +143,7 @@ async function runOperation(settings, state, signal, expected, body) {
         if (signal.aborted)
             abort();
         if (stopped)
-            throw new CuaExecutorError(stopped, dispatched ? "outcome_uncertain" : "not_dispatched");
+            throw new ComputerUseExecutorError(stopped, dispatched ? "outcome_uncertain" : "not_dispatched");
         checkScope(settings, state, expected);
     };
     try {
@@ -165,8 +165,8 @@ async function runOperation(settings, state, signal, expected, body) {
         controller.abort();
         if (dispatched)
             state.unusable = true;
-        const code = stopped ?? (isCuaExecutorError(error) ? error.code : "transport_failed");
-        throw new CuaExecutorError(code, dispatched ? "outcome_uncertain" : "not_dispatched");
+        const code = stopped ?? (isComputerUseExecutorError(error) ? error.code : "transport_failed");
+        throw new ComputerUseExecutorError(code, dispatched ? "outcome_uncertain" : "not_dispatched");
     }
     finally {
         clearTimeout(timer);
@@ -187,13 +187,13 @@ function sessionDetacher(state) {
                 await Promise.race([
                     session.detach(),
                     new Promise((_resolve, reject) => {
-                        timer = setTimeout(() => reject(new CuaExecutorError("deadline_exceeded", "not_dispatched")), DEADLINE_MS);
+                        timer = setTimeout(() => reject(new ComputerUseExecutorError("deadline_exceeded", "not_dispatched")), DEADLINE_MS);
                     }),
                 ]);
             }
             catch {
                 state.unusable = true;
-                throw new CuaExecutorError("transport_failed", "not_dispatched");
+                throw new ComputerUseExecutorError("transport_failed", "not_dispatched");
             }
             finally {
                 clearTimeout(timer);
@@ -215,7 +215,7 @@ async function assertOwnerReady(settings, op) {
 async function probeElement(op, session, contextId, expression) {
     const result = await op.step(() => session.send("Runtime.evaluate", evaluateParams(expression, contextId)));
     if (!probeAccepted(result))
-        throw new CuaExecutorError("action_rejected", "not_dispatched");
+        throw new ComputerUseExecutorError("action_rejected", "not_dispatched");
 }
 /**
  * Preparation: the owner check, a CDP session (recorded on the handle as soon as it exists, so
@@ -233,14 +233,14 @@ async function acquireIsolatedWorld(settings, state, detach, prepared, op) {
     const tree = await op.step(() => prepared.session.send("Page.getFrameTree"));
     const frameId = ownedFrameId(tree);
     if (frameId === undefined)
-        throw new CuaExecutorError("invalid_response", "not_dispatched");
+        throw new ComputerUseExecutorError("invalid_response", "not_dispatched");
     const world = await op.step(() => prepared.session.send("Page.createIsolatedWorld", {
         frameId,
         worldName: settings.worldName,
     }));
     prepared.contextId = world.executionContextId;
     if (!isExecutionContextId(prepared.contextId))
-        throw new CuaExecutorError("invalid_response", "not_dispatched");
+        throw new ComputerUseExecutorError("invalid_response", "not_dispatched");
     await probeElement(op, prepared.session, prepared.contextId, PREPARE);
 }
 /** Disposes a prepared handle once: aborts its lifetime, detaches its session, releases busy. */
@@ -255,7 +255,7 @@ function disposePrepared(state, detach, prepared, self) {
                     await detach(prepared.session);
             }
             catch (error) {
-                throw new CuaExecutorError(isCuaExecutorError(error) ? error.code : "transport_failed", prepared.dispatchedText ? "outcome_uncertain" : "not_dispatched");
+                throw new ComputerUseExecutorError(isComputerUseExecutorError(error) ? error.code : "transport_failed", prepared.dispatchedText ? "outcome_uncertain" : "not_dispatched");
             }
             finally {
                 state.busy = false;
@@ -274,7 +274,7 @@ function preparedHandle(settings, state, prepared, dispose) {
     return {
         async paste() {
             if (prepared.used || prepared.disposed)
-                throw new CuaExecutorError("action_rejected", "not_dispatched");
+                throw new ComputerUseExecutorError("action_rejected", "not_dispatched");
             prepared.used = true; // A failed attempt cannot be retried through this handle.
             await runOperation(settings, state, prepared.lifetime.signal, prepared.expected, async (op) => {
                 await assertOwnerReady(settings, op);
@@ -345,10 +345,10 @@ export function createGuestChromiumText(options) {
         },
         async prepareText(text, signal) {
             if (!isAdmissibleText(text))
-                throw new CuaExecutorError("invalid_request", "not_dispatched");
+                throw new ComputerUseExecutorError("invalid_request", "not_dispatched");
             checkScope(settings, state, state.generation);
             if (state.busy)
-                throw new CuaExecutorError("executor_busy", "not_dispatched");
+                throw new ComputerUseExecutorError("executor_busy", "not_dispatched");
             state.busy = true;
             const expected = state.generation;
             const lifetime = new AbortController();

package/dist/guest/desktop-executor.d.ts

@@ -1,5 +1,5 @@
 import type { CuaAction, CuaExecutor } from "../actors/computer-use/loop.js";
-import { CuaExecutorError } from "../actors/computer-use/executor-error.js";
+import { ComputerUseExecutorError } from "../actors/computer-use/executor-error.js";
 /** Internal guest port. Implementations recheck signal synchronously before native dispatch. */
 export interface GuestDesktopTools {
     capture(signal: AbortSignal): Promise<Buffer>;
@@ -48,7 +48,7 @@ export declare function failureEndsSession(progress: Pick<ActionProgress, "prepa
  * session_revoked when the signal aborted, then the executor's own error or execution_failed. It
  * reads signal.aborted only for an undispatched failure, as the inline mapping did.
  */
-export declare function failureError(dispatched: boolean, error: unknown, signal: Pick<AbortSignal, "aborted">): CuaExecutorError;
+export declare function failureError(dispatched: boolean, error: unknown, signal: Pick<AbortSignal, "aborted">): ComputerUseExecutorError;
 /**
  * The native commands for an action, wrapped in keydown/keyup when it holds modifiers. It throws
  * the refusal for an action the desktop cannot take, before anything is sent.

package/dist/guest/desktop-executor.js

@@ -1,13 +1,13 @@
 import { perceptualSignature } from "../evidence/frame-signature.js";
 import { setTimeout as delay } from "node:timers/promises";
 import { BROWSER_CONTROL_LIMITS, validateBrowserControlAction, validateBrowserControlPng, } from "../browser-control/protocol.js";
-import { CuaExecutorError, isCuaExecutorError } from "../actors/computer-use/executor-error.js";
+import { ComputerUseExecutorError, isComputerUseExecutorError, } from "../actors/computer-use/executor-error.js";
 import { xdotoolChord, xdotoolHeldModifiers } from "./desktop-keys.js";
 /** Headed X11 input and full-frame captures. Browser metadata is deliberately absent. */
 export function createGuestDesktopExecutor(options) {
     const { width, height, tools, authoritySignal } = options;
     if (!isValidFrameSize(width, height))
-        throw new CuaExecutorError("invalid_request", "not_dispatched");
+        throw new ComputerUseExecutorError("invalid_request", "not_dispatched");
     const context = {
         width,
         height,
@@ -40,12 +40,12 @@ function terminate(state, context) {
 }
 function assertOpen(state, signal, dispatched = false) {
     if (state.terminal || signal.aborted)
-        throw new CuaExecutorError("session_revoked", dispatched ? "outcome_uncertain" : "not_dispatched");
+        throw new ComputerUseExecutorError("session_revoked", dispatched ? "outcome_uncertain" : "not_dispatched");
 }
 function begin(state, signal) {
     assertOpen(state, signal);
     if (state.busy)
-        throw new CuaExecutorError("executor_busy", "not_dispatched");
+        throw new ComputerUseExecutorError("executor_busy", "not_dispatched");
     state.busy = true;
 }
 /** Captures one full frame and checks it is a PNG of the executor's size. */
@@ -57,15 +57,15 @@ async function observeFrame(context, state) {
         assertOpen(state, authoritySignal);
         validateBrowserControlPng(screenshot);
         if (screenshot.readUInt32BE(16) !== width || screenshot.readUInt32BE(20) !== height) {
-            throw new CuaExecutorError("invalid_response", "not_dispatched");
+            throw new ComputerUseExecutorError("invalid_response", "not_dispatched");
         }
         return { screenshot, stateSignature: perceptualSignature(screenshot) };
     }
     catch (error) {
         terminate(state, context);
-        throw isCuaExecutorError(error)
+        throw isComputerUseExecutorError(error)
             ? error
-            : new CuaExecutorError("execution_failed", "not_dispatched");
+            : new ComputerUseExecutorError("execution_failed", "not_dispatched");
     }
     finally {
         state.busy = false;
@@ -99,7 +99,7 @@ async function executeAction(context, state, value, callerSignal) {
             catch (error) {
                 // This transaction has no earlier input. Its private bridge can
                 // prove that no insertion or native input was sent.
-                if (isCuaExecutorError(error) && error.disposition === "not_dispatched")
+                if (isComputerUseExecutorError(error) && error.disposition === "not_dispatched")
                     progress.dispatched = false;
                 throw error;
             }
@@ -143,7 +143,7 @@ async function executeAction(context, state, value, callerSignal) {
         catch {
             terminate(state, context);
             // oxlint-disable-next-line no-unsafe-finally -- a text channel that fails to close makes the action outcome unknowable
-            throw new CuaExecutorError("execution_failed", progress.dispatched ? "outcome_uncertain" : "not_dispatched");
+            throw new ComputerUseExecutorError("execution_failed", progress.dispatched ? "outcome_uncertain" : "not_dispatched");
         }
         finally {
             state.busy = false;
@@ -157,12 +157,12 @@ async function executeAction(context, state, value, callerSignal) {
  */
 export function failureEndsSession(progress, error, signal) {
     return ((progress.preparing &&
-        !(isCuaExecutorError(error) &&
+        !(isComputerUseExecutorError(error) &&
             error.code === "action_rejected" &&
             error.disposition === "not_dispatched")) ||
         progress.dispatched ||
         signal.aborted ||
-        !isCuaExecutorError(error));
+        !isComputerUseExecutorError(error));
 }
 /**
  * The error a failed action throws: outcome_uncertain once anything was dispatched, then
@@ -171,12 +171,12 @@ export function failureEndsSession(progress, error, signal) {
  */
 export function failureError(dispatched, error, signal) {
     if (dispatched)
-        return new CuaExecutorError(isCuaExecutorError(error) ? error.code : "execution_failed", "outcome_uncertain");
+        return new ComputerUseExecutorError(isComputerUseExecutorError(error) ? error.code : "execution_failed", "outcome_uncertain");
     if (signal.aborted)
-        return new CuaExecutorError("session_revoked", "not_dispatched");
-    return isCuaExecutorError(error)
+        return new ComputerUseExecutorError("session_revoked", "not_dispatched");
+    return isComputerUseExecutorError(error)
         ? error
-        : new CuaExecutorError("execution_failed", "not_dispatched");
+        : new ComputerUseExecutorError("execution_failed", "not_dispatched");
 }
 /**
  * The native commands for an action, wrapped in keydown/keyup when it holds modifiers. It throws
@@ -194,7 +194,7 @@ function framePoint(frame, x, y) {
     const { width, height } = frame;
     // Reject out-of-frame input instead of clicking a clamped, unintended target.
     if (x < 0 || y < 0 || x >= width || y >= height)
-        throw new CuaExecutorError("action_rejected", "not_dispatched");
+        throw new ComputerUseExecutorError("action_rejected", "not_dispatched");
     return [String(Math.min(width - 1, Math.round(x))), String(Math.min(height - 1, Math.round(y)))];
 }
 /** The native commands for an action, before any held modifiers. */
@@ -219,13 +219,13 @@ function actionCommands(frame, action) {
             // must be refused instead of silently changing the requested text.
             if (action.text.includes("\0") ||
                 Buffer.from(action.text, "utf8").toString("utf8") !== action.text)
-                throw new CuaExecutorError("action_rejected", "not_dispatched");
+                throw new ComputerUseExecutorError("action_rejected", "not_dispatched");
             return [];
         }
         case "drag": {
             const points = action.path.map((p) => framePoint(frame, p.x, p.y));
             if (points.length < 2)
-                throw new CuaExecutorError("action_rejected", "not_dispatched");
+                throw new ComputerUseExecutorError("action_rejected", "not_dispatched");
             return [
                 ["mousemove", ...points[0]],
                 ["mousedown", "1"],
@@ -238,7 +238,7 @@ function actionCommands(frame, action) {
             // Native X11 wheel steps do not promise exact pixel scroll distances.
             const horizontal = Math.ceil(Math.abs(action.dx) / 120), vertical = Math.ceil(Math.abs(action.dy) / 120);
             if (horizontal + vertical > 100)
-                throw new CuaExecutorError("action_rejected", "not_dispatched");
+                throw new ComputerUseExecutorError("action_rejected", "not_dispatched");
             return horizontal + vertical === 0
                 ? []
                 : [
@@ -251,6 +251,6 @@ function actionCommands(frame, action) {
         case "screenshot":
             return [];
         case "speak":
-            throw new CuaExecutorError("action_rejected", "not_dispatched");
+            throw new ComputerUseExecutorError("action_rejected", "not_dispatched");
     }
 }

package/dist/guest/desktop-keys.js

@@ -1,4 +1,4 @@
-import { CuaExecutorError } from "../actors/computer-use/executor-error.js";
+import { ComputerUseExecutorError } from "../actors/computer-use/executor-error.js";
 // Key names for the xdotool-driven desktops: the guest's headed display and the E2B sandbox. Both
 // hand these strings to xdotool, which has a command language, so only names from these tables
 // ever reach it. The guest runtime ships this module, so it lives in src/guest/, which CI's
@@ -56,7 +56,7 @@ function lookup(table, key) {
 }
 function chord(names) {
     if (new Set(names).size !== names.length)
-        throw new CuaExecutorError("action_rejected", "not_dispatched");
+        throw new ComputerUseExecutorError("action_rejected", "not_dispatched");
     return names.join("+");
 }
 /** A keypress chord in xdotool syntax. Unknown or repeated keys are refused before dispatch. */
@@ -68,7 +68,7 @@ export function xdotoolChord(keys) {
             return key.toUpperCase();
         const name = lookup(keyNames, key);
         if (!name)
-            throw new CuaExecutorError("action_rejected", "not_dispatched");
+            throw new ComputerUseExecutorError("action_rejected", "not_dispatched");
         return name;
     }));
 }
@@ -83,7 +83,7 @@ export function xdotoolHeldModifiers(keys) {
     return chord(keys.map((key) => {
         const name = lookup(modifierNames, key);
         if (!name)
-            throw new CuaExecutorError("action_rejected", "not_dispatched");
+            throw new ComputerUseExecutorError("action_rejected", "not_dispatched");
         return name;
     }));
 }

package/dist/guest/desktop-media.d.ts

@@ -1,6 +1,6 @@
 import type { CuaExecutor } from "../actors/computer-use/loop.js";
 import { type HeardSpeech } from "../actors/computer-use/speech.js";
-import { CuaExecutorError } from "../actors/computer-use/executor-error.js";
+import { ComputerUseExecutorError } from "../actors/computer-use/executor-error.js";
 interface GuestDesktopMediaDeclaration {
     camera?: {
         source: string;
@@ -64,7 +64,7 @@ export declare function classifyWorkerMessage(value: unknown, ready: boolean): W
 /** Once a speak command is written, its outcome is unknown unless the worker replies. */
 export declare function dispositionAfterWrite(written: boolean): "outcome_uncertain" | "not_dispatched";
 /** A failed speak keeps its own executor error; anything else is an execution failure. */
-export declare function speakFailure(error: unknown, written: boolean): CuaExecutorError;
+export declare function speakFailure(error: unknown, written: boolean): ComputerUseExecutorError;
 /** Starts optional native guest media before Chromium and later decorates its finite executor. */
 export declare function startDesktopMedia(options: GuestDesktopMediaOptions): Promise<GuestDesktopMedia>;
 export {};