cli-jaw 2.17.41 → 2.17.42

package/dist/src/browser/occlusion.js

@@ -0,0 +1,148 @@
+/**
+ * src/browser/occlusion.ts — what will actually receive a click at a point.
+ *
+ * A coordinate click dispatches wherever the point lands. If a cookie banner,
+ * modal or sticky header covers the target, that element receives the click
+ * and the call still reports success — the most common silent failure in
+ * coordinate-based automation, because nothing in the response says the wrong
+ * thing was clicked.
+ *
+ * Ported from BrowserOS's hit test. Relatedness is decided IN THE PAGE against
+ * the actual node, because that is the only place element identity is
+ * knowable: comparing a reconciled ref's ARIA role against a DOM tag name is a
+ * category error, since a `link` is an `a`, a `textbox` is an `input`, and a
+ * `button` is often a `div`.
+ */
+/**
+ * Decide whether a hit means the click would go somewhere unintended.
+ *
+ * With no marked target — a pure coordinate click into canvas — there is
+ * nothing to contradict, so the verdict is `unknown` rather than `clear`.
+ * No evidence of a problem is not evidence of no problem, and collapsing the
+ * two would let an unchecked click report as a verified one.
+ */
+export function judgeHit(hit) {
+    // The hit test could not run — an unreadable cross-origin frame, a page
+    // that navigated mid-check. Fail OPEN: an infrastructure failure must not
+    // block a legitimate click, and pretending to know is worse than saying
+    // we do not.
+    if (!hit)
+        return { blocked: false, reason: 'unknown' };
+    // The walk stopped at a frame it could not see into. Whatever is behind it
+    // is unknowable, and a target inside that frame would look identical to a
+    // cover. Refusing on that evidence would block legitimate clicks into
+    // every cross-origin embed.
+    if (hit.opaqueFrame)
+        return { blocked: false, reason: 'unknown' };
+    if (hit.relatesToTarget === undefined)
+        return { blocked: false, reason: 'unknown' };
+    if (hit.relatesToTarget)
+        return { blocked: false, reason: 'clear' };
+    return {
+        blocked: true,
+        blocker: hit.descriptor,
+        reason: hit.crossedFrame
+            ? `the point resolves into an iframe, to ${hit.descriptor}, not the intended target`
+            : `${hit.descriptor} covers the target at this point`,
+    };
+}
+/**
+ * The page-side hit test. **A real function, deliberately not a source string.**
+ *
+ * Playwright sets `isFunction: typeof pageFunction === "function"`. Pass a
+ * string and the page evaluates the expression, obtains a function object, and
+ * never calls it — the result serializes to `undefined`. An earlier version of
+ * this shipped as a string, which made the entire check a permanent no-op. It
+ * was invisible precisely because the guard fails open: `undefined` became
+ * `null` became "unknown", indistinguishable from the intended safe path.
+ *
+ * Everything below runs in the page, so it may only use DOM globals.
+ */
+export function hitTestInPage(arg) {
+    const describe = (el) => {
+        if (!el || !el.tagName)
+            return 'element';
+        const tag = String(el.tagName).toLowerCase();
+        if (el.id)
+            return tag + '#' + el.id;
+        if (typeof el.className === 'string' && el.className.trim()) {
+            return tag + '.' + el.className.trim().split(/\s+/)[0];
+        }
+        return tag;
+    };
+    const up = (node) => {
+        if (!node)
+            return null;
+        return node.parentNode || node.host || (node.getRootNode ? node.getRootNode().host ?? null : null) || null;
+    };
+    const reaches = (from, to) => {
+        for (let node = from, guard = 0; node && guard < 200; node = up(node), guard++) {
+            if (node === to)
+                return true;
+        }
+        return false;
+    };
+    let target = null;
+    if (arg.targetPoint) {
+        target = document.elementFromPoint(arg.targetPoint.x, arg.targetPoint.y);
+    }
+    let doc = document;
+    let x = arg.x;
+    let y = arg.y;
+    let crossedFrame = false;
+    let opaqueFrame = false;
+    let hit = doc.elementFromPoint(x, y);
+    // Bounded: a frame chain should be shallow, and a cycle must not hang the page.
+    for (let depth = 0; depth < 16; depth++) {
+        if (!hit || (hit.tagName !== 'IFRAME' && hit.tagName !== 'FRAME'))
+            break;
+        if (target && (hit === target || reaches(target, hit)))
+            break;
+        let childDoc = null;
+        try {
+            childDoc = hit.contentDocument ?? null;
+        }
+        catch {
+            childDoc = null;
+        }
+        if (!childDoc) {
+            opaqueFrame = true;
+            break;
+        }
+        const rect = hit.getBoundingClientRect();
+        // elementFromPoint in the child is relative to the child's own
+        // viewport, so subtract the frame's position and its border.
+        x -= rect.left + hit.clientLeft;
+        y -= rect.top + hit.clientTop;
+        doc = childDoc;
+        crossedFrame = true;
+        const next = doc.elementFromPoint(x, y);
+        if (!next)
+            break;
+        hit = next;
+    }
+    if (!hit)
+        return null;
+    const ancestry = [];
+    for (let node = up(hit), guard = 0; node && guard < 24; node = up(node), guard++) {
+        if (node.tagName)
+            ancestry.push(describe(node));
+    }
+    const result = { descriptor: describe(hit), ancestry, crossedFrame };
+    if (opaqueFrame)
+        result.opaqueFrame = true;
+    if (target) {
+        // The hit is the target, inside it, or contains it. Clicking a
+        // button's inner span is clicking the button. A label forwarding to
+        // this control counts too.
+        let related = hit === target || reaches(hit, target) || reaches(target, hit);
+        if (!related && hit.closest) {
+            const lbl = hit.closest('label');
+            if (lbl && (lbl.control === target || (lbl.contains ? lbl.contains(target) : false)))
+                related = true;
+        }
+        result.relatesToTarget = related;
+    }
+    return result;
+}
+//# sourceMappingURL=occlusion.js.map

package/dist/src/browser/occlusion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"occlusion.js","sourceRoot":"","sources":["../../../src/browser/occlusion.ts"],"names":[],"mappings":"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"}

package/dist/src/browser/verify-candidate.js

@@ -0,0 +1,162 @@
+/**
+ * src/browser/verify-candidate.ts — a second look that can actually disagree.
+ *
+ * The option this replaces re-ran the identical query against the identical
+ * screenshot and then discarded the coordinates, keeping only whether the
+ * second answer still found something. Same input, same question: the only way
+ * it could fail was model non-determinism, and the only thing it reliably
+ * bought was a second round-trip. Its test asserted the string
+ * `verifyBeforeClick` appeared in the source, so a guard that guarded nothing
+ * passed a suite that checked nothing.
+ *
+ * A verification that can disagree has to change the input. Cropping tightly
+ * around the candidate and asking again does that: the target now dominates
+ * the frame, so a model that was guessing has to guess differently, and an
+ * answer landing far from the original candidate is evidence it was wrong.
+ *
+ * Geometry only. The capture and the model call belong to the caller.
+ */
+/** Default crop around a candidate, in CSS pixels. */
+export const VERIFY_CROP = { width: 280, height: 200 };
+/**
+ * How far from the original candidate a second answer may land, as a fraction
+ * of the crop. Beyond this the two answers point at different things, and the
+ * disagreement matters more than either one.
+ *
+ * It is a fraction per axis, so on the default 280x200 crop it permits 126px
+ * horizontally and 90px vertically — one number, two distances.
+ */
+export const VERIFY_DRIFT_LIMIT = 0.45;
+/**
+ * A crop centred on the candidate, kept inside the viewport.
+ *
+ * Being outside the viewport is fixed by SHIFTING the rectangle, so a
+ * candidate near an edge still gets a full-size crop and the drift threshold
+ * means the same thing everywhere. A viewport smaller than the crop is the one
+ * case that genuinely shrinks it, since there is nothing else to do.
+ */
+export function cropAroundPoint(point, viewport, size = VERIFY_CROP) {
+    const width = Math.min(size.width, viewport.width);
+    const height = Math.min(size.height, viewport.height);
+    const x = Math.max(0, Math.min(Math.round(point.x - width / 2), viewport.width - width));
+    const y = Math.max(0, Math.min(Math.round(point.y - height / 2), viewport.height - height));
+    return { x, y, width, height };
+}
+/**
+ * How long an observation may be trusted before the click it informs.
+ *
+ * Verification adds a second model round-trip, which roughly doubles the
+ * interval between seeing the page and acting on it. The freshness guard on
+ * the reconciliation path catches navigation, but nothing catches scroll,
+ * reflow or animation — so a long enough gap means the coordinate describes a
+ * page that no longer exists.
+ *
+ * This does not detect movement. It bounds how long we are willing to assume
+ * there was none, which is a weaker claim and the honest one.
+ */
+export const OBSERVATION_MAX_AGE_MS = 30_000;
+export function isObservationStale(observedAt, now, maxAgeMs = OBSERVATION_MAX_AGE_MS) {
+    // A clock that ran backwards tells us nothing, so treat it as unusable
+    // rather than as freshness.
+    if (!Number.isFinite(observedAt) || !Number.isFinite(now))
+        return true;
+    return now - observedAt > maxAgeMs || now < observedAt;
+}
+/**
+ * How much of the freshness budget is left, in milliseconds.
+ *
+ * A provider child was given a flat 60s while the observation it works from
+ * expired at 30s, so two round-trips could spend two minutes producing an
+ * answer the very next line was guaranteed to refuse. Deriving the child's
+ * timeout from what remains kills it at the moment its answer stops being
+ * usable instead of at an unrelated constant.
+ *
+ * Never negative, and never above `cap`: the existing 60s ceiling still
+ * applies when the budget is larger than it.
+ */
+export function remainingObservationBudget(observedAt, now, cap, maxAgeMs = OBSERVATION_MAX_AGE_MS) {
+    if (!Number.isFinite(observedAt) || !Number.isFinite(now) || !Number.isFinite(cap))
+        return 0;
+    const spent = now - observedAt;
+    if (spent < 0)
+        return 0;
+    return Math.max(0, Math.min(cap, maxAgeMs - spent));
+}
+/**
+ * Fit a requested capture rectangle inside the viewport.
+ *
+ * Playwright trims a clip to the viewport before capturing, so a rectangle
+ * extending past the edge yields a smaller image than asked for — and one
+ * lying entirely outside fails with an opaque assertion about the clipped area
+ * being empty. Neither says which rectangle was wrong or what the viewport was.
+ *
+ * Clamping here means the caller learns the capture was truncated, and a
+ * genuinely impossible rectangle gets a named error instead.
+ */
+export function clampClipToViewport(clip, viewport) {
+    if (clip.x >= viewport.width || clip.y >= viewport.height) {
+        throw new Error(`clip (${clip.x}, ${clip.y}) starts outside the ${viewport.width}x${viewport.height} viewport`);
+    }
+    const width = Math.min(clip.width, viewport.width - clip.x);
+    const height = Math.min(clip.height, viewport.height - clip.y);
+    if (width <= 0 || height <= 0) {
+        throw new Error(`clip ${clip.width}x${clip.height} at (${clip.x}, ${clip.y}) has no area inside the ${viewport.width}x${viewport.height} viewport`);
+    }
+    return {
+        clip: { x: clip.x, y: clip.y, width, height },
+        truncated: width !== clip.width || height !== clip.height,
+    };
+}
+/**
+ * Judge a second answer taken inside `crop`.
+ *
+ * `localPoint` is where the re-run landed within the crop, in CSS pixels
+ * relative to the crop's own origin. The returned point is back in page
+ * coordinates, so a caller that agrees can use it directly — the second look
+ * replaces the first estimate rather than merely blessing it.
+ *
+ * Drift is measured from the ORIGINAL CANDIDATE, not from the crop centre.
+ * Those coincide in the middle of a viewport but not near an edge, where the
+ * crop clamps: a candidate 5px from the left sits 5px into its crop while the
+ * crop centre is 140px in. Measuring from the centre there would refuse a
+ * second answer that re-found the exact same point — the one case that should
+ * agree most strongly.
+ */
+export function judgeVerification(localPoint, crop, candidate, driftLimit = VERIFY_DRIFT_LIMIT) {
+    // The target is not in a crop centred on where we thought it was. That is
+    // the first answer being wrong, which is exactly what this is for.
+    if (!localPoint)
+        return { agreed: false, reason: 'the target was not in the verification crop' };
+    // The model answered about an image of exactly this size, so a point
+    // outside it is impossible by construction and means the scaling was
+    // wrong. Without this, a candidate near a shifted crop's edge can drift
+    // the permitted fraction and land off the far side — and off the viewport,
+    // since the returned point is clicked directly.
+    if (localPoint.x < 0 || localPoint.y < 0
+        || localPoint.x > crop.width || localPoint.y > crop.height) {
+        return {
+            agreed: false,
+            reason: `the second answer (${Math.round(localPoint.x)}, ${Math.round(localPoint.y)}) is outside the ${crop.width}x${crop.height} verification crop`,
+        };
+    }
+    // Fall back to the crop centre only when no candidate was supplied, which
+    // is the same point whenever the crop was not clamped.
+    const cx = candidate ? candidate.x - crop.x : crop.width / 2;
+    const cy = candidate ? candidate.y - crop.y : crop.height / 2;
+    const dx = Math.abs(localPoint.x - cx) / crop.width;
+    const dy = Math.abs(localPoint.y - cy) / crop.height;
+    const drift = Math.max(dx, dy);
+    if (drift > driftLimit) {
+        return {
+            agreed: false,
+            reason: `the second answer drifted ${Math.round(drift * 100)}% from the original candidate`,
+            drift,
+        };
+    }
+    return {
+        agreed: true,
+        point: { x: crop.x + localPoint.x, y: crop.y + localPoint.y },
+        drift,
+    };
+}
+//# sourceMappingURL=verify-candidate.js.map

package/dist/src/browser/verify-candidate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-candidate.js","sourceRoot":"","sources":["../../../src/browser/verify-candidate.ts"],"names":[],"mappings":"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"}

package/dist/src/browser/vision-input.js

@@ -0,0 +1,74 @@
+/**
+ * src/browser/vision-input.ts — untrusted-input handling for the vision path.
+ *
+ * Kept separate from vision.ts so it can be tested without pulling in the CDP
+ * action layer: these are pure functions over strings, and they guard the one
+ * place where caller-supplied text reaches a child process.
+ */
+/**
+ * The target description reaches the vision path from the HTTP body of
+ * `POST /api/browser/vision-click` and is interpolated into a prompt for a
+ * child process. Treat it as untrusted text, not as instructions.
+ *
+ * Be clear about what this is worth. The prompt's delimited span is a
+ * model-behavior hint, not a security boundary; the instructions that follow
+ * the span are what actually constrain the answer. This function's job is
+ * narrower: keep the target on one line, stop it closing its own delimiter,
+ * and bound its size. It does not, and cannot, stop the text from *reading*
+ * like an instruction.
+ */
+export const MAX_TARGET_LENGTH = 200;
+/**
+ * Collapse every run of two or more double quotes to a single one.
+ *
+ * A single `replace(/"""/g, '"')` is not enough: `String.replace` scans left
+ * to right without rescanning its own output, so `n` quotes become
+ * `floor(n/3) + n%3`, and any `n >= 7` still leaves three in a row. Matching
+ * runs of length two or more removes the whole class in one pass, so there is
+ * no arity that survives.
+ */
+function collapseQuoteRuns(value) {
+    return value.replace(/"{2,}/g, '"');
+}
+/** Drop a trailing high surrogate so a truncated target stays well-formed. */
+function trimLoneSurrogate(value) {
+    return /[\uD800-\uDBFF]$/.test(value) ? value.slice(0, -1) : value;
+}
+export function sanitizeTarget(target) {
+    if (typeof target !== 'string')
+        throw new Error('vision-click target must be a string');
+    const cleaned = collapseQuoteRuns(target
+        // C0 and C1 controls, plus the Unicode line and paragraph
+        // separators, which JS \s also matches but which are line breaks
+        // rather than ordinary whitespace and belong in this class.
+        .replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]+/g, ' ')
+        // Zero-width characters can split a token invisibly and pad length.
+        .replace(/[\u200b-\u200f\u2060\ufeff]+/g, '')
+        // Bidirectional overrides can reorder the value where it is echoed
+        // back to a terminal.
+        .replace(/[\u202a-\u202e\u2066-\u2069]+/g, ''))
+        .replace(/\s+/g, ' ')
+        .trim();
+    if (!cleaned)
+        throw new Error('vision-click target is empty after sanitization');
+    return cleaned.length > MAX_TARGET_LENGTH
+        ? trimLoneSurrogate(cleaned.slice(0, MAX_TARGET_LENGTH))
+        : cleaned;
+}
+/**
+ * An agentic `codex exec` can emit command output, so its stdout is not
+ * bounded by the answer we asked for. Keep the newest units: the coordinate
+ * JSON arrives in a late event and the scan reads from the end, so a truncated
+ * head line is expected garbage and the parser already skips it.
+ *
+ * This counts UTF-16 code units, not bytes — non-ASCII output can occupy up to
+ * four bytes per unit, so treat it as an order-of-magnitude bound.
+ */
+export const MAX_CODEX_STDOUT_UNITS = 1024 * 1024;
+/** @deprecated Misnamed: this bounds code units. Use MAX_CODEX_STDOUT_UNITS. */
+export const MAX_CODEX_STDOUT_BYTES = MAX_CODEX_STDOUT_UNITS;
+export function appendBounded(buffer, chunk, limit = MAX_CODEX_STDOUT_UNITS) {
+    const next = buffer + chunk;
+    return next.length > limit ? next.slice(next.length - limit) : next;
+}
+//# sourceMappingURL=vision-input.js.map

package/dist/src/browser/vision-input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vision-input.js","sourceRoot":"","sources":["../../../src/browser/vision-input.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAErC;;;;;;;;GAQG;AACH,SAAS,iBAAiB,CAAC,KAAa;IACpC,OAAO,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;AACxC,CAAC;AAED,8EAA8E;AAC9E,SAAS,iBAAiB,CAAC,KAAa;IACpC,OAAO,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;AACvE,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,MAAe;IAC1C,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;IACxF,MAAM,OAAO,GAAG,iBAAiB,CAC7B,MAAM;QACF,0DAA0D;QAC1D,iEAAiE;QACjE,4DAA4D;SAC3D,OAAO,CAAC,4CAA4C,EAAE,GAAG,CAAC;QAC3D,oEAAoE;SACnE,OAAO,CAAC,+BAA+B,EAAE,EAAE,CAAC;QAC7C,mEAAmE;QACnE,sBAAsB;SACrB,OAAO,CAAC,gCAAgC,EAAE,EAAE,CAAC,CACrD;SACI,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;SACpB,IAAI,EAAE,CAAC;IACZ,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IACjF,OAAO,OAAO,CAAC,MAAM,GAAG,iBAAiB;QACrC,CAAC,CAAC,iBAAiB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,iBAAiB,CAAC,CAAC;QACxD,CAAC,CAAC,OAAO,CAAC;AAClB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,GAAG,IAAI,CAAC;AAElD,gFAAgF;AAChF,MAAM,CAAC,MAAM,sBAAsB,GAAG,sBAAsB,CAAC;AAE7D,MAAM,UAAU,aAAa,CAAC,MAAc,EAAE,KAAa,EAAE,KAAK,GAAG,sBAAsB;IACvF,MAAM,IAAI,GAAG,MAAM,GAAG,KAAK,CAAC;IAC5B,OAAO,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACxE,CAAC"}

package/dist/src/browser/vision-provider.js

@@ -0,0 +1,75 @@
+/**
+ * src/browser/vision-provider.ts — how the vision provider is invoked.
+ *
+ * The invocation used to be a literal array inside the pipeline, which is why
+ * it drifted from the documented safety position without anyone noticing:
+ * `--dangerously-bypass-approvals-and-sandbox` was passed unconditionally for
+ * what is a pure image-classification call, while the skill docs stated that
+ * cli-jaw never adds it automatically. Describing the invocation here makes
+ * that disagreement visible and testable instead of buried in a spawn call.
+ *
+ * The flag cannot simply be deleted. It is documented as the only known
+ * workaround for the Windows sandbox killing `codex exec` children with exit
+ * `-1073741502` and an empty stderr. So it becomes an explicit opt-in that is
+ * off by default, and the Windows consequence is stated rather than implied.
+ *
+ * Note the contrast with `agent/args.ts`, which does add the flag when the
+ * user selected the Auto (YOLO) permission policy. That is not the same case:
+ * an agent turn exists to run commands, so choosing Auto is the user saying
+ * they accept that. A vision lookup runs none, so it starts from off.
+ */
+/** Disables the codexclaw plugin for the duration of the lookup. */
+export const CODEXCLAW_PLUGIN_DISABLE_CONFIG = 'plugins."codexclaw@personal".enabled=false';
+/**
+ * Build the argument list for a vision lookup.
+ *
+ * Pure, so the exact invocation can be asserted without spawning anything —
+ * which matters here, because the defect this replaces was a single wrong
+ * argument that no test could see.
+ */
+export function buildVisionInvocation(opts) {
+    const bypassedSandbox = opts.bypassSandbox === true;
+    const args = [
+        'exec', '-i', opts.screenshotPath, '--json',
+        // Do not persist a thread for a one-shot lookup.
+        '--ephemeral',
+        '-c', CODEXCLAW_PLUGIN_DISABLE_CONFIG,
+        '--skip-git-repo-check',
+    ];
+    if (bypassedSandbox)
+        args.push('--dangerously-bypass-approvals-and-sandbox');
+    args.push(opts.prompt);
+    return { command: 'codex', args, bypassedSandbox };
+}
+/**
+ * Explain a spawn failure in terms of the sandbox, when that is what it was.
+ *
+ * Exit `-1073741502` with no stderr is the Windows sandbox terminating the
+ * child. Without this the caller sees an empty error and reasonably concludes
+ * the model failed, which sends them looking in the wrong place entirely.
+ */
+export const WINDOWS_SANDBOX_KILL_CODE = -1073741502;
+/**
+ * The same status as an unsigned 32-bit value (`0xC0000142`).
+ *
+ * Node normally surfaces a Windows exit status as a signed integer, but the
+ * value travels through enough layers — shells, wrappers, JSON round-trips —
+ * that the unsigned form does turn up. Matching only one representation would
+ * mean the explanation silently never fires on exactly the platform it exists
+ * for, which is the failure mode this whole phase is about.
+ */
+export const WINDOWS_SANDBOX_KILL_CODE_UNSIGNED = WINDOWS_SANDBOX_KILL_CODE >>> 0;
+function isWindowsSandboxKill(code) {
+    return code === WINDOWS_SANDBOX_KILL_CODE || code === WINDOWS_SANDBOX_KILL_CODE_UNSIGNED;
+}
+export function explainExit(code, stderr, bypassedSandbox) {
+    const detail = stderr.trim().slice(0, 200);
+    if (isWindowsSandboxKill(code) && !detail) {
+        return bypassedSandbox
+            ? `codex exec was terminated (exit ${code}) even with the sandbox bypass enabled`
+            : `codex exec was terminated by the Windows sandbox (exit ${code}, no stderr). `
+                + 'Retry with the sandbox bypass only if you accept that it disables both approvals and the sandbox.';
+    }
+    return `codex exec failed (code ${code})${detail ? ': ' + detail : ''}`;
+}
+//# sourceMappingURL=vision-provider.js.map

package/dist/src/browser/vision-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vision-provider.js","sourceRoot":"","sources":["../../../src/browser/vision-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,oEAAoE;AACpE,MAAM,CAAC,MAAM,+BAA+B,GAAG,4CAA4C,CAAC;AAwB5F;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAA6B;IAC/D,MAAM,eAAe,GAAG,IAAI,CAAC,aAAa,KAAK,IAAI,CAAC;IACpD,MAAM,IAAI,GAAG;QACT,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,cAAc,EAAE,QAAQ;QAC3C,iDAAiD;QACjD,aAAa;QACb,IAAI,EAAE,+BAA+B;QACrC,uBAAuB;KAC1B,CAAC;IACF,IAAI,eAAe;QAAE,IAAI,CAAC,IAAI,CAAC,4CAA4C,CAAC,CAAC;IAC7E,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACvB,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC;AACvD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,UAAU,CAAC;AAErD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAAG,yBAAyB,KAAK,CAAC,CAAC;AAElF,SAAS,oBAAoB,CAAC,IAAmB;IAC7C,OAAO,IAAI,KAAK,yBAAyB,IAAI,IAAI,KAAK,kCAAkC,CAAC;AAC7F,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAmB,EAAE,MAAc,EAAE,eAAwB;IACrF,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC3C,IAAI,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;QACxC,OAAO,eAAe;YAClB,CAAC,CAAC,mCAAmC,IAAI,wCAAwC;YACjF,CAAC,CAAC,0DAA0D,IAAI,gBAAgB;kBAC5E,mGAAmG,CAAC;IAChH,CAAC;IACD,OAAO,2BAA2B,IAAI,IAAI,MAAM,CAAC,CAAC,CAAC,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;AAC5E,CAAC"}