humanish 0.111.0 → 0.111.2

package/dist/evidence/encoded-text.d.ts

@@ -4,8 +4,8 @@ export declare function decodeEscapes(text: string): string;
 export interface EncodedTextScanOptions {
     /** Do not count an encoded binary run as opaque. */
     readonly allowOpaqueBase64?: boolean;
-    /** Match secret shapes only, leaving local paths out, as a URL's path may look like one. */
-    readonly secretsOnly?: boolean;
+    /** What counts as sensitive in the text and in each decoding of it; containsSensitive by default. */
+    readonly matches?: (text: string) => boolean;
 }
 export interface EncodedTextScan {
     /** A secret or private path, in the text or in a decoding of it. */
@@ -27,4 +27,4 @@ export declare function scanEncodedText(text: string, options?: EncodedTextScanO
  * scan of the same string would give. Repeated verifies of an unchanged file, as serve admission
  * and the Observer render do, skip the scan.
  */
-export declare function scanEncodedTextCached(text: string, options?: EncodedTextScanOptions): EncodedTextScan;
+export declare function scanEncodedTextCached(text: string, options?: Pick<EncodedTextScanOptions, "allowOpaqueBase64">): EncodedTextScan;

package/dist/evidence/encoded-text.js

@@ -4,7 +4,7 @@
 // judge the same decoded text.
 import { createHash } from "node:crypto";
 import { readPlainText } from "./plain-text.js";
-import { containsSecret, containsSensitive } from "./redaction.js";
+import { containsSensitive } from "./redaction.js";
 // HTML5 named references that stand for printable ASCII. Letters and digits have only numeric
 // references, which decodeEscapes handles.
 const ASCII_ENTITIES = {
@@ -189,7 +189,7 @@ function decodeTransferEscapes(text) {
         .replace(/=\r?\n/g, "")
         .replace(/=([0-9A-F]{2})/g, (match, hex) => codePoint(Number.parseInt(hex, 16), match));
 }
-const matcherOf = (options) => options.secretsOnly === true ? containsSecret : containsSensitive;
+const matcherOf = (options) => options.matches ?? containsSensitive;
 const CLEAN = Object.freeze({ sensitive: false, opaque: false });
 const SENSITIVE = Object.freeze({ sensitive: true, opaque: false });
 function inspectDecoded(bytes, run, options, depth) {
@@ -261,7 +261,13 @@ export function scanEncodedText(text, options = {}, depth = 0) {
     for (const bytes of slashStarts)
         if (inspectDecoded(bytes, "", { ...options, allowOpaqueBase64: true }, depth).sensitive)
             return SENSITIVE;
-    for (const [match] of expanded.matchAll(HEX_RUN)) {
+    // Hex is read before transfer escapes too: the quoted-printable pass reads `=68` in `state=6874...`
+    // as one byte, which shifts every hex pair after it.
+    const hexRuns = new Set([
+        ...[...expanded.matchAll(HEX_RUN)].map(([match]) => match),
+        ...(expanded === decoded ? [] : [...decoded.matchAll(HEX_RUN)].map(([match]) => match)),
+    ]);
+    for (const match of hexRuns) {
         const plain = readPlainText(Buffer.from(match, "hex"));
         if (plain.ok && depth < MAX_DEPTH && scanEncodedText(plain.text, options, depth + 1).sensitive)
             return SENSITIVE;
@@ -271,7 +277,7 @@ export function scanEncodedText(text, options = {}, depth = 0) {
 // Bump when scanEncodedText, decodeEscapes or the sensitive patterns change what they return. The
 // cache lives in one process, so the version guards results across a hot reload or a test that
 // swaps the scanner.
-const ENCODED_SCAN_VERSION = 2;
+const ENCODED_SCAN_VERSION = 3;
 // Distinct files one process verifies in a burst (a run's files, a serve library's runs).
 const SCAN_CACHE_LIMIT = 256;
 const scanCache = new Map();
@@ -286,7 +292,6 @@ export function scanEncodedTextCached(text, options = {}) {
     const key = [
         ENCODED_SCAN_VERSION,
         options.allowOpaqueBase64 === true ? "opaque-allowed" : "opaque-unscanned",
-        options.secretsOnly === true ? "secrets-only" : "secrets-and-paths",
         createHash("sha256").update(Buffer.from(text, "utf16le")).digest("hex"),
     ].join(":");
     const cached = scanCache.get(key);

package/dist/evidence/redaction.d.ts

@@ -1,7 +1,7 @@
 /** Every pattern containsSensitive tests. A test pins each to ASCII, which scanEncodedText relies on. */
 export declare function sensitivePatterns(): readonly RegExp[];
-/** True if the text contains a secret-shaped token. Local paths do not count. */
-export declare function containsSecret(text: string): boolean;
+/** True if the text contains a credential. Local paths and a URL on an E2B host alone do not count. */
+export declare function containsCredential(text: string): boolean;
 /** True if the text contains any secret-shaped token or known local path. */
 export declare function containsSensitive(text: string): boolean;
 /**

package/dist/evidence/redaction.js

@@ -68,6 +68,14 @@ const E2B_PUBLIC_PAGE = [
     String.raw `(?:www\.)?e2b\.dev\/dashboard\/?(?:\?tab=[a-z]{1,16})?`,
     String.raw `(?:docs\.e2b\.dev|(?:www\.)?e2b\.dev\/docs)(?:\/[a-z][a-z-]{0,39}){0,8}\/?`,
 ].join("|");
+// Any URL on an E2B host: a sandbox host names its sandbox, and a stream URL carries its auth
+// key. The slashes may be JSON-escaped (`https:\/\/`). User info runs to its last `@`, as a URL
+// parser reads it, and may hold any character but a slash or space. The host part stops at a
+// backslash, quote or angle bracket, so a URL followed by an escaped line break and an `E2B_...`
+// variable in JSON text is not read as an E2B host. A public page followed by `)@` is user info.
+// A stream URL's auth key rides its `password` parameter, 16 characters from the SDK, which the
+// credential parameter pattern matches as well.
+const SANDBOX_URL = new RegExp(String.raw `(?!https:\/\/(?:${E2B_PUBLIC_PAGE})[.,;:!?'")]*(?:\s|$))https?:\\?\/\\?\/(?:[^/\s@]*@)*[^/\s\\"'<>@]*e2b[^)\s]+`, "gi");
 // A pattern that matches a credential by its context puts the context in a `keep` group, which
 // redaction leaves in place: `?token=[REDACTED_SECRET]`. Context goes in a group and not in a
 // lookbehind, because a pattern that starts with a lookbehind is tried at every position of the
@@ -115,12 +123,7 @@ const SECRET_PATTERNS = [
     // such as humanish-egress-auth-placeholder and JSON numbers do not count. The lookaheads are
     // bounded, so a long run of `TOKEN=` costs linear time.
     new RegExp(String.raw `(?<keep>${CREDENTIAL_VARIABLE}${QUOTE}[ \t]{0,4}[:=][ \t]{0,4}${QUOTE})${notAPlaceholder(VARIABLE_END)}${NOT_A_NUMBER}(?=[^\s"'\\,;&]{0,255}[0-9])(?=[^\s"'\\,;&]{0,255}[A-Za-z])[^\s"'\\,;&]{16}[^\s"'\\,;&]*`, "g"),
-    // Any URL on an E2B host: a sandbox host names its sandbox, and a stream URL carries its auth
-    // key. The slashes may be JSON-escaped (`https:\/\/`). User info runs to its last `@`, as a URL
-    // parser reads it, and may hold any character but a slash or space. The host part stops at a
-    // backslash, quote or angle bracket, so a URL followed by an escaped line break and an `E2B_...`
-    // variable in JSON text is not read as an E2B host. A public page followed by `)@` is user info.
-    new RegExp(String.raw `(?!https:\/\/(?:${E2B_PUBLIC_PAGE})[.,;:!?'")]*(?:\s|$))https?:\\?\/\\?\/(?:[^/\s@]*@)*[^/\s\\"'<>@]*e2b[^)\s]+`, "gi"),
+    SANDBOX_URL,
     /BEGIN (RSA|OPENSSH|PRIVATE) KEY/gi,
 ];
 const LOCAL_PATH_PATTERNS = [
@@ -148,9 +151,17 @@ function matchesPattern(pattern, text) {
     return pattern.test(text);
 }
 /** True if the text contains a secret-shaped token. Local paths do not count. */
-export function containsSecret(text) {
+function containsSecret(text) {
     return SECRET_PATTERNS.some((pattern) => matchesPattern(pattern, text));
 }
+// Every secret pattern but the sandbox URL. A URL on an E2B host names a sandbox, which verify
+// keeps out of a shared run, but the host is no credential: a key, token, password or signature in
+// such a URL matches one of these patterns on its own.
+const CREDENTIAL_PATTERNS = SECRET_PATTERNS.filter((pattern) => pattern !== SANDBOX_URL);
+/** True if the text contains a credential. Local paths and a URL on an E2B host alone do not count. */
+export function containsCredential(text) {
+    return CREDENTIAL_PATTERNS.some((pattern) => matchesPattern(pattern, text));
+}
 /** True if the text contains any secret-shaped token or known local path. */
 export function containsSensitive(text) {
     return (containsSecret(text) || LOCAL_PATH_PATTERNS.some(([pattern]) => matchesPattern(pattern, text)));

package/dist/guest/browser-tools.js

@@ -60,7 +60,11 @@ export function createGuestBrowserTools(native, content) {
                     }
                     catch (error) {
                         // Ctrl+L itself is input. No content fallback after that dispatch.
-                        throw new ComputerUseExecutorError(isComputerUseExecutorError(error) ? error.code : "execution_failed", "outcome_uncertain");
+                        throw isComputerUseExecutorError(error)
+                            ? new ComputerUseExecutorError(error.code, "outcome_uncertain", {
+                                diagnostic: error.diagnostic,
+                            })
+                            : new ComputerUseExecutorError("execution_failed", "outcome_uncertain");
                     }
                 },
                 async close() {

package/dist/guest/chromium-text.js

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { ComputerUseExecutorError, isComputerUseExecutorError, } from "../actors/computer-use/executor-error.js";
+import { classifyExecutorFailure, } from "../actors/computer-use/executor-diagnostic.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.
@@ -107,20 +108,26 @@ function checkScope(settings, state, expected) {
     if (state.generation !== expected)
         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)
+    if (state.dialogSeen || page.isClosed() || page.context() !== context || !pages.includes(page))
         throw new ComputerUseExecutorError("action_rejected", "not_dispatched");
+    // Playwright emulates focus in every page it drives, so the focus probe passes in a background
+    // tab too and cannot say which tab is in front. The participant learns why, and can close the
+    // other tab.
+    if (pages.length !== 1)
+        throw new ComputerUseExecutorError("action_rejected", "not_dispatched", {
+            reason: "extra_tab",
+        });
 }
 /**
  * One bounded operation: a 5 s deadline, the caller's abort, and any interrupt race every step.
- * A failure after a dispatching step makes the port unusable and reports outcome_uncertain.
+ * A failure after a dispatching step makes the port unusable and reports outcome_uncertain. An
+ * undeclared error becomes transport_failed with a diagnostic naming the failing step and a
+ * category; its message is classified and dropped.
  */
 async function runOperation(settings, state, signal, expected, body) {
     let dispatched = false;
     let stopped;
+    let phase;
     const controller = new AbortController();
     let rejectStop;
     const stop = new Promise((_resolve, reject) => {
@@ -151,11 +158,13 @@ async function runOperation(settings, state, signal, expected, body) {
         return await body({
             signal: controller.signal,
             check,
-            async step(call, dispatch = false) {
+            async step(name, call, dispatch = false) {
                 check();
                 if (dispatch)
                     dispatched = true;
+                phase = name;
                 const value = await Promise.race([call(), stop]);
+                phase = undefined;
                 check();
                 return value;
             },
@@ -165,8 +174,18 @@ async function runOperation(settings, state, signal, expected, body) {
         controller.abort();
         if (dispatched)
             state.unusable = true;
-        const code = stopped ?? (isComputerUseExecutorError(error) ? error.code : "transport_failed");
-        throw new ComputerUseExecutorError(code, dispatched ? "outcome_uncertain" : "not_dispatched");
+        const declared = isComputerUseExecutorError(error);
+        const code = stopped ?? (declared ? error.code : "transport_failed");
+        const reason = !dispatched && stopped === undefined && declared ? error.reason : undefined;
+        const diagnostic = stopped !== undefined
+            ? undefined
+            : declared
+                ? error.diagnostic
+                : classifyExecutorFailure(phase ?? "text_port", error);
+        throw new ComputerUseExecutorError(code, dispatched ? "outcome_uncertain" : "not_dispatched", {
+            reason,
+            diagnostic,
+        });
     }
     finally {
         clearTimeout(timer);
@@ -191,9 +210,11 @@ function sessionDetacher(state) {
                     }),
                 ]);
             }
-            catch {
+            catch (error) {
                 state.unusable = true;
-                throw new ComputerUseExecutorError("transport_failed", "not_dispatched");
+                throw new ComputerUseExecutorError("transport_failed", "not_dispatched", {
+                    diagnostic: classifyExecutorFailure("cdp_detach", error),
+                });
             }
             finally {
                 clearTimeout(timer);
@@ -209,11 +230,11 @@ function sessionDetacher(state) {
 /** The owner's native window check, as one step of an operation. */
 async function assertOwnerReady(settings, op) {
     const { assertFocusedWindow } = settings;
-    await op.step(() => assertFocusedWindow(op.signal));
+    await op.step("owner_window_check", () => assertFocusedWindow(op.signal));
 }
 /** One fixed probe in the isolated world; anything but a boolean true refuses the action. */
 async function probeElement(op, session, contextId, expression) {
-    const result = await op.step(() => session.send("Runtime.evaluate", evaluateParams(expression, contextId)));
+    const result = await op.step("focus_probe", () => session.send("Runtime.evaluate", evaluateParams(expression, contextId)));
     if (!probeAccepted(result))
         throw new ComputerUseExecutorError("action_rejected", "not_dispatched");
 }
@@ -224,17 +245,17 @@ async function probeElement(op, session, contextId, expression) {
  */
 async function acquireIsolatedWorld(settings, state, detach, prepared, op) {
     await assertOwnerReady(settings, op);
-    prepared.session = await op.step(() => settings.context.newCDPSession(settings.page).then((acquired) => {
+    prepared.session = await op.step("cdp_session", () => settings.context.newCDPSession(settings.page).then((acquired) => {
         state.sessions.add(acquired);
         if (op.signal.aborted || state.closed)
             void detach(acquired).catch(() => { });
         return acquired;
     }));
-    const tree = await op.step(() => prepared.session.send("Page.getFrameTree"));
+    const tree = await op.step("frame_tree", () => prepared.session.send("Page.getFrameTree"));
     const frameId = ownedFrameId(tree);
     if (frameId === undefined)
         throw new ComputerUseExecutorError("invalid_response", "not_dispatched");
-    const world = await op.step(() => prepared.session.send("Page.createIsolatedWorld", {
+    const world = await op.step("isolated_world", () => prepared.session.send("Page.createIsolatedWorld", {
         frameId,
         worldName: settings.worldName,
     }));
@@ -255,7 +276,10 @@ function disposePrepared(state, detach, prepared, self) {
                     await detach(prepared.session);
             }
             catch (error) {
-                throw new ComputerUseExecutorError(isComputerUseExecutorError(error) ? error.code : "transport_failed", prepared.dispatchedText ? "outcome_uncertain" : "not_dispatched");
+                const declared = isComputerUseExecutorError(error);
+                throw new ComputerUseExecutorError(declared ? error.code : "transport_failed", prepared.dispatchedText ? "outcome_uncertain" : "not_dispatched", {
+                    diagnostic: declared ? error.diagnostic : classifyExecutorFailure("cdp_detach", error),
+                });
             }
             finally {
                 state.busy = false;
@@ -281,7 +305,7 @@ function preparedHandle(settings, state, prepared, dispose) {
                 await probeElement(op, prepared.session, prepared.contextId, RECHECK);
                 await assertOwnerReady(settings, op);
                 op.check();
-                await op.step(() => {
+                await op.step("insert_text", () => {
                     prepared.dispatchedText = true;
                     return prepared.session.send("Input.insertText", { text: prepared.text });
                 }, true);

package/dist/guest/desktop-executor.js

@@ -171,7 +171,11 @@ export function failureEndsSession(progress, error, signal) {
  */
 export function failureError(dispatched, error, signal) {
     if (dispatched)
-        return new ComputerUseExecutorError(isComputerUseExecutorError(error) ? error.code : "execution_failed", "outcome_uncertain");
+        return isComputerUseExecutorError(error)
+            ? new ComputerUseExecutorError(error.code, "outcome_uncertain", {
+                diagnostic: error.diagnostic,
+            })
+            : new ComputerUseExecutorError("execution_failed", "outcome_uncertain");
     if (signal.aborted)
         return new ComputerUseExecutorError("session_revoked", "not_dispatched");
     return isComputerUseExecutorError(error)

package/dist/keys/key-resolution.d.ts

@@ -33,6 +33,9 @@ export interface KeySourceProbe {
     source: string | null;
     /** The command/path that would fill it when missing. */
     hint: string;
+    /** Set when the env holds the inert value a terminal study's sandbox gets in place of a key, and
+     *  no other source supplies one. `source` is then null. */
+    placeholder?: true;
 }
 /** The nearest fill instruction for a missing key. Doctor rows use it, and it is appended to
  *  *_KEYS_MISSING errors so the failure names the fix. */

package/dist/keys/key-resolution.js

@@ -22,6 +22,7 @@ import { homedir } from "node:os";
 import path from "node:path";
 import { loadEnvFile } from "./env-file.js";
 import { cli } from "../cli/invocation.js";
+import { OPENAI_EGRESS_PLACEHOLDER } from "../routes/terminal/runtime-auth.js";
 /** The only names implicit discovery may fill (and `humanish keys set` may store). Everything
  *  else in an overlay/store file is ignored-and-named: a repo-planted NODE_OPTIONS/LD_PRELOAD
  *  must never enter process env off a file the operator did not explicitly pass (an explicit
@@ -263,7 +264,14 @@ export function describeMissingKeys(names, env) {
  * Runs the same chain against a scratch copy of env so nothing observable changes.
  */
 export async function probeKeySources(names, args) {
+    // A terminal study's sandbox sets CODEX_API_KEY to an inert placeholder so Codex starts; the key
+    // itself stays in the host-side egress proxy. The placeholder is no key, so it counts as unset and
+    // discovery may still find a real one.
+    const placeholder = (name) => args.env[name]?.trim() === OPENAI_EGRESS_PLACEHOLDER;
     const scratch = { ...args.env };
+    for (const name of names)
+        if (placeholder(name))
+            delete scratch[name];
     const fills = await discoverProviderKeys({
         cwd: args.cwd,
         env: scratch,
@@ -272,7 +280,7 @@ export async function probeKeySources(names, args) {
     });
     const bySource = new Map(fills.map((fill) => [fill.name, fill.source]));
     return names.map((name) => {
-        const inEnv = args.env[name] !== undefined && args.env[name]?.trim() !== "";
+        const inEnv = args.env[name] !== undefined && args.env[name]?.trim() !== "" && !placeholder(name);
         // GH_TOKEN and GITHUB_TOKEN are one credential with two spellings; a doctor row that says
         // "missing" while GITHUB_TOKEN sits in the env would be wrong.
         const aliasInEnv = name === "GH_TOKEN" &&
@@ -285,7 +293,12 @@ export async function probeKeySources(names, args) {
             : aliasInEnv
                 ? "process env (GITHUB_TOKEN)"
                 : (bySource.get(name) ?? null);
-        return { name, source, hint: missingKeyHint(name) };
+        return {
+            name,
+            source,
+            hint: missingKeyHint(name),
+            ...(source === null && placeholder(name) ? { placeholder: true } : {}),
+        };
     });
 }
 const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;