@ashx-j/lunr 0.2.25 → 0.2.27

package/dist/core/computer-use/workflow.js

@@ -0,0 +1,900 @@
+import { randomUUID } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
+import { DriverCallError } from "./adapter.js";
+import { prepareComputerImage, screenshotDimensions } from "./image.js";
+import { DesktopLease } from "./lease.js";
+import { computerSchemas } from "./schemas.js";
+export function driverData(reply) {
+    if (reply.structuredContent &&
+        typeof reply.structuredContent === "object" &&
+        !Array.isArray(reply.structuredContent))
+        return Object.fromEntries(Object.entries(reply.structuredContent));
+    if (Array.isArray(reply.content))
+        for (const item of reply.content) {
+            if (item.type !== "text" || typeof item.text !== "string")
+                continue;
+            try {
+                const value = JSON.parse(item.text);
+                if (value && typeof value === "object" && !Array.isArray(value))
+                    return Object.fromEntries(Object.entries(value));
+            }
+            catch { }
+        }
+    return {};
+}
+function plainLaunchReason(reply) {
+    if (reply.structuredContent || !Array.isArray(reply.content))
+        return undefined;
+    const text = reply.content.find((item) => item.type === "text")?.text;
+    if (typeof text !== "string")
+        return undefined;
+    if (/^App name lookup for .+ is (?:temporarily unavailable|unavailable).+No app was launched;/s.test(text))
+        return "app_lookup_unavailable";
+    if (/^App .+ was not found in shell:AppsFolder or by Windows PATH\/association lookup:/s.test(text))
+        return "app_not_found";
+    if (/^Launch of .+ timed out after 15s/s.test(text))
+        return "launch_timeout_unknown";
+    if (/^(?:Failed to launch|Task error): /s.test(text))
+        return "launch_native_error_unknown";
+    return undefined;
+}
+export function driverRefused(reply) {
+    const data = driverData(reply);
+    const acknowledged = data.activated === true || data.success === true || data.verified === true || data.effect === "confirmed";
+    const uncertain = [data.status, data.effect].some((value) => value === "partial" || value === "unverifiable");
+    return (reply.isError === true ||
+        plainLaunchReason(reply) !== undefined ||
+        (data.refusal !== undefined && data.refusal !== null && data.refusal !== false) ||
+        (data.error !== undefined && data.error !== null && data.error !== false) ||
+        data.effect === "refused" ||
+        data.status === "refused" ||
+        data.status === "failed" ||
+        data.success === false ||
+        [
+            "window_target_mismatch",
+            "window_target_not_found",
+            "background_unavailable",
+            "foreground_unavailable",
+            "type_text_incomplete",
+            "verification_failed",
+        ].includes(String(data.code)) ||
+        (data.status !== undefined &&
+            !acknowledged &&
+            !uncertain &&
+            !["ok", "success", "completed"].includes(String(data.status))) ||
+        (data.code !== undefined && data.code !== 0 && !acknowledged && !uncertain));
+}
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? Object.fromEntries(Object.entries(value))
+        : {};
+}
+function select(data, keys) {
+    const result = {};
+    for (const key of keys) {
+        const value = data[key];
+        if (["name", "app_name", "title"].includes(key) && typeof value === "string")
+            result[key] = value.slice(0, 240);
+        else if (["active", "running", "is_on_screen", "minimized"].includes(key) && typeof value === "boolean")
+            result[key] = value;
+        else if (["pid", "window_id", "x", "y", "width", "height"].includes(key) &&
+            typeof value === "number" &&
+            Number.isSafeInteger(value))
+            result[key] = value;
+    }
+    return result;
+}
+function typingRecovery(data, text) {
+    if (typeof text !== "string")
+        return {};
+    const requested = data.requested_chars;
+    const delivered = data.delivered_chars;
+    if (typeof requested !== "number" ||
+        !Number.isSafeInteger(requested) ||
+        requested < 0 ||
+        requested > 20000 ||
+        requested !== Array.from(text).length)
+        return {};
+    const validDelivered = typeof delivered === "number" && Number.isSafeInteger(delivered) && delivered >= 0 && delivered <= requested;
+    return {
+        requested_chars: requested,
+        delivered_chars: validDelivered ? delivered : undefined,
+        retryable: validDelivered && data.retry_from_character === delivered && typeof data.retryable === "boolean"
+            ? data.retryable
+            : undefined,
+        retry_from_character: validDelivered && data.retry_from_character === delivered ? delivered : undefined,
+    };
+}
+const nativeCodes = new Set([
+    "background_unavailable",
+    "background_occluded",
+    "background_uipi_blocked",
+    "window_target_mismatch",
+    "window_target_not_found",
+    "type_text_incomplete",
+    "foreground_unavailable",
+    "foreground_rejected",
+    "stale_target",
+    "target_not_found",
+    "verification_failed",
+    "tool_invocation_failed",
+]);
+function safeCode(value) {
+    return typeof value === "string" && nativeCodes.has(value) ? value : undefined;
+}
+function nativeReason(reply) {
+    const data = driverData(reply);
+    const code = safeCode(data.code) ??
+        safeCode(record(data.refusal).code) ??
+        safeCode(record(data.error).code) ??
+        safeCode(data.refusal) ??
+        safeCode(data.error);
+    if (code)
+        return code;
+    if (plainLaunchReason(reply))
+        return plainLaunchReason(reply);
+    return "native_error_unknown";
+}
+function outcome(reply, text) {
+    const data = driverData(reply);
+    const refused = driverRefused(reply);
+    const partial = data.effect === "partial" || data.status === "partial";
+    return {
+        phase: refused || partial ? "native_result" : "native_request",
+        code: refused || partial ? nativeReason(reply) : undefined,
+        native_code: safeCode(data.code) ?? safeCode(record(data.refusal).code) ?? safeCode(record(data.error).code),
+        status: typeof data.status === "string" &&
+            ["ok", "success", "completed", "partial", "refused", "failed"].includes(data.status)
+            ? data.status
+            : undefined,
+        effect: typeof data.effect === "string" && ["confirmed", "partial", "unverifiable", "refused"].includes(data.effect)
+            ? data.effect
+            : undefined,
+        verified: typeof data.verified === "boolean" ? data.verified : undefined,
+        success: typeof data.success === "boolean" ? data.success : undefined,
+        activated: typeof data.activated === "boolean" ? data.activated : undefined,
+        escalation: record(data.escalation).recommended === "foreground" ? "foreground" : undefined,
+        input: partial && typingRecovery(data, text).delivered_chars !== undefined
+            ? "partial"
+            : refused || partial
+                ? "uncertain"
+                : "dispatched",
+        applicationEffect: "unverified",
+        ...typingRecovery(data, text),
+    };
+}
+function abortable(pending, signal) {
+    return new Promise((resolve, reject) => {
+        const abort = () => {
+            signal.removeEventListener("abort", abort);
+            reject(signal.reason ?? new Error("Computer operation cancelled."));
+        };
+        signal.addEventListener("abort", abort, { once: true });
+        pending.then((value) => {
+            signal.removeEventListener("abort", abort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener("abort", abort);
+            reject(error);
+        });
+        if (signal.aborted)
+            abort();
+    });
+}
+const freshActionGuidance = "Get a fresh capture of the exact target before any next action, including window focus. Copy its token exactly. No input was sent by this call; earlier calls may have had an effect.";
+class CaptureError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+}
+class ObservationError extends Error {
+    code;
+    constructor(code, message) {
+        super(`Stale observation. ${message}`);
+        this.code = code;
+    }
+}
+function targetFrom(input) {
+    if (input.desktop === true) {
+        if (input.pid !== undefined || input.window_id !== undefined)
+            throw new Error("Desktop target cannot include pid/window_id.");
+        return { desktop: true };
+    }
+    if (typeof input.pid !== "number" ||
+        !Number.isInteger(input.pid) ||
+        input.pid < 1 ||
+        typeof input.window_id !== "number" ||
+        !Number.isInteger(input.window_id) ||
+        input.window_id < 1)
+        throw new Error("Window target requires positive integer pid and window_id.");
+    return { pid: input.pid, window_id: input.window_id };
+}
+function sameTarget(a, b) {
+    return a.desktop === true
+        ? b.desktop === true
+        : b.desktop !== true && a.pid === b.pid && a.window_id === b.window_id;
+}
+export class ComputerWorkflow {
+    observation;
+    lastCapture;
+    lastAction;
+    abort = new AbortController();
+    closing;
+    driver;
+    lease;
+    constructor(driver, lease = new DesktopLease()) {
+        this.driver = driver;
+        this.lease = lease;
+        this.driver.setProcessObserver?.((pid) => this.lease.trackProcess(pid));
+    }
+    fresh(input, previous) {
+        if (!previous)
+            throw new ObservationError("observation_unavailable", "No active observation is available.");
+        if (previous.token !== input.observation)
+            throw new ObservationError("observation_mismatch", "Token does not match the active observation.");
+        if (!sameTarget(previous.target, targetFrom(input)))
+            throw new ObservationError("observation_target_mismatch", "Token belongs to a different target.");
+        if (Date.now() - previous.time > 30000)
+            throw new ObservationError("observation_expired", "The active observation is older than 30 seconds.");
+        return previous;
+    }
+    async capture(target, signal, previous, crop) {
+        const time = Date.now();
+        const reply = await abortable(this.driver.call(target.desktop ? "get_desktop_state" : "get_window_state", target.desktop
+            ? {}
+            : {
+                pid: target.pid,
+                window_id: target.window_id,
+                include_accessibility_tree: false,
+                include_screenshot: true,
+                max_dimension: 2560,
+            }, signal), signal);
+        if (driverRefused(reply))
+            throw new CaptureError(nativeReason(reply));
+        const data = driverData(reply);
+        const images = Array.isArray(reply.content) ? reply.content.filter((item) => item.type === "image") : [];
+        if (images.length !== 1 || typeof images[0].data !== "string" || typeof images[0].mimeType !== "string")
+            throw new CaptureError("screenshot_unavailable");
+        const image = { type: "image", data: images[0].data, mimeType: images[0].mimeType };
+        let dimensions;
+        try {
+            dimensions = screenshotDimensions(image);
+        }
+        catch {
+            throw new CaptureError("image_decode_failed");
+        }
+        if (data.screenshot_frame_valid === false ||
+            data.screenshot_error != null ||
+            dimensions.width !== data.screenshot_width ||
+            dimensions.height !== data.screenshot_height)
+            throw new CaptureError("image_frame_invalid");
+        const geometry = JSON.stringify(select(record(data.window_bounds), ["x", "y", "width", "height"]));
+        if (crop &&
+            previous &&
+            (previous.sourceWidth !== dimensions.width ||
+                previous.sourceHeight !== dimensions.height ||
+                previous.geometry !== geometry))
+            throw new CaptureError("target_geometry_changed");
+        let prepared;
+        try {
+            prepared = await abortable(prepareComputerImage(image, crop), signal);
+        }
+        catch (error) {
+            if (signal.aborted)
+                throw error;
+            throw new CaptureError("image_decode_failed");
+        }
+        signal.throwIfAborted();
+        return { ...prepared, token: randomUUID(), target, time, fingerprint: prepared.fingerprint, geometry };
+    }
+    imageResult(observation, extra = {}) {
+        this.observation = observation;
+        const { width, height, region, sourceWidth, sourceHeight, scaleX, scaleY, target, token } = observation;
+        const failed = extra.failed === true;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        ...extra,
+                        observation: token,
+                        target,
+                        captured_at: observation.time,
+                        expires_at: observation.time + 30000,
+                        image: { width, height },
+                        mapping: { sourceWidth, sourceHeight, ...region, scaleX, scaleY },
+                        coordinates: "Use returned-image pixels; mapping is applied automatically.",
+                    }),
+                },
+                observation.image,
+            ],
+            details: { observation: token, computer: { failed, workflow: "ready" } },
+            isError: failed,
+        };
+    }
+    crop(input, previous) {
+        const crop = record(input.crop);
+        const { x, y, width, height } = crop;
+        if (typeof x !== "number" ||
+            typeof y !== "number" ||
+            typeof width !== "number" ||
+            typeof height !== "number" ||
+            ![x, y, width, height].every(Number.isFinite) ||
+            x < 0 ||
+            y < 0 ||
+            width <= 0 ||
+            height <= 0 ||
+            x + width > previous.width ||
+            y + height > previous.height ||
+            Object.keys(crop).some((key) => !["x", "y", "width", "height"].includes(key)))
+            throw new Error("Crop must fit the latest returned image.");
+        const left = Math.floor(previous.region.x + x * previous.scaleX);
+        const top = Math.floor(previous.region.y + y * previous.scaleY);
+        const right = Math.min(previous.sourceWidth, Math.ceil(previous.region.x + (x + width) * previous.scaleX));
+        const bottom = Math.min(previous.sourceHeight, Math.ceil(previous.region.y + (y + height) * previous.scaleY));
+        return { x: left, y: top, width: right - left, height: bottom - top };
+    }
+    action(name, input, previous) {
+        const args = previous.target.desktop
+            ? { scope: "desktop" }
+            : { pid: previous.target.pid, window_id: previous.target.window_id };
+        if (previous.target.desktop && input.foreground !== true)
+            throw new Error("Desktop input requires foreground=true.");
+        if (name !== "computer_window" && name !== "computer_hover")
+            args.delivery_mode = input.foreground === true ? "foreground" : "background";
+        for (const key of ["x", "y", "from_x", "from_y", "to_x", "to_y"]) {
+            if (name === "computer_window")
+                break;
+            const value = input[key];
+            if (value === undefined)
+                continue;
+            const horizontal = key.endsWith("x");
+            if (typeof value !== "number" ||
+                !Number.isFinite(value) ||
+                value < 0 ||
+                value >= (horizontal ? previous.width : previous.height))
+                throw new Error("Coordinate outside the observed image.");
+            args[key] =
+                (horizontal ? previous.region.x : previous.region.y) +
+                    value * (horizontal ? previous.scaleX : previous.scaleY);
+        }
+        if ((input.x === undefined) !== (input.y === undefined))
+            throw new Error("Provide a complete x/y pair.");
+        if (previous.target.desktop && ["computer_key", "computer_text"].includes(name) && input.x !== undefined)
+            throw new Error("Desktop keyboard input uses the observed focused field. Change focus with a separate grounded click.");
+        let operation;
+        switch (name) {
+            case "computer_hover":
+                if (process.platform !== "win32" ||
+                    !previous.target.desktop ||
+                    input.desktop !== true ||
+                    input.foreground !== true ||
+                    input.x === undefined ||
+                    input.y === undefined)
+                    throw new Error("Hover requires a Windows foreground desktop image and x/y coordinates.");
+                operation = "move_cursor";
+                break;
+            case "computer_click":
+            case "computer_scroll":
+                if (input.x === undefined || input.y === undefined)
+                    throw new Error("This action requires x/y image coordinates.");
+                operation = name === "computer_click" ? "click" : "scroll";
+                for (const key of name === "computer_click"
+                    ? ["button", "count", "modifier"]
+                    : ["direction", "amount", "by"])
+                    if (input[key] !== undefined)
+                        args[key] = input[key];
+                break;
+            case "computer_drag":
+                if (!["from_x", "from_y", "to_x", "to_y"].every((key) => typeof args[key] === "number"))
+                    throw new Error("Drag requires both endpoints.");
+                operation = "drag";
+                break;
+            case "computer_key": {
+                if ((input.key === undefined) === (input.keys === undefined))
+                    throw new Error("Provide key OR keys.");
+                const keys = Array.isArray(input.keys) ? input.keys : undefined;
+                const last = keys?.at(-1);
+                const modifiers = new Set(["ctrl", "control", "shift", "alt", "win", "windows", "cmd", "command"]);
+                const foregroundShortcut = process.platform === "win32" &&
+                    input.foreground === true &&
+                    input.x === undefined &&
+                    keys !== undefined &&
+                    keys.length >= 2 &&
+                    keys.slice(0, -1).every((key) => typeof key === "string" && modifiers.has(key.toLowerCase())) &&
+                    typeof last === "string" &&
+                    !modifiers.has(last.toLowerCase());
+                // Pinned Windows hotkey routes XAML through UIA before honoring foreground; press_key honors SendInput.
+                operation = input.keys === undefined || foregroundShortcut ? "press_key" : "hotkey";
+                if (foregroundShortcut) {
+                    args.key = last;
+                    args.modifiers = keys.slice(0, -1);
+                }
+                else
+                    args[input.keys === undefined ? "key" : "keys"] = input.keys ?? input.key;
+                break;
+            }
+            case "computer_text":
+                operation = "type_text";
+                args.text = input.text;
+                break;
+            case "computer_window":
+                if (previous.target.desktop)
+                    throw new Error("Window management requires an exact window target.");
+                if (input.action === "frame") {
+                    for (const key of ["x", "y", "width", "height"]) {
+                        const value = input[key];
+                        if (typeof value !== "number" ||
+                            !Number.isFinite(value) ||
+                            (["width", "height"].includes(key) && value <= 0))
+                            throw new Error("Frame requires valid x/y/width/height.");
+                        args[key] = value;
+                    }
+                    operation = "set_window_frame";
+                }
+                else if (input.action === "focus" &&
+                    ["x", "y", "width", "height"].every((key) => input[key] === undefined))
+                    operation = "bring_to_front";
+                else
+                    throw new Error("Use frame or focus. Minimize/restore uses a fresh image click on the visible control.");
+                break;
+            default:
+                throw new Error("Unknown computer action.");
+        }
+        return { operation, args };
+    }
+    async execute(name, input, signal) {
+        const combined = AbortSignal.any([
+            this.abort.signal,
+            this.lease.signal,
+            AbortSignal.timeout(90000),
+            ...(signal ? [signal] : []),
+        ]);
+        let inputDispatched = false;
+        let failureCode = "workflow_unavailable";
+        let phase = "validation";
+        const currentPhase = () => phase;
+        let operationName = name;
+        let actionTarget;
+        let actionOutcome;
+        try {
+            const result = await this.lease.run(async () => {
+                failureCode = "invalid_arguments";
+                const previous = this.observation;
+                if (name !== "computer_apps")
+                    this.observation = undefined;
+                if (!Object.hasOwn(computerSchemas, name))
+                    throw new Error("Unknown computer operation.");
+                const schema = computerSchemas[name];
+                if (Object.keys(input).some((key) => !Object.hasOwn(schema.properties, key)))
+                    throw new Error("Unsupported computer argument. Use image coordinates only.");
+                if (name === "computer_apps" || name === "computer_launch") {
+                    const operation = name === "computer_launch" ? "launch_app" : input.pid === undefined ? "list_apps" : "list_windows";
+                    operationName = operation;
+                    if (input.include_windows !== undefined &&
+                        (name !== "computer_apps" ||
+                            typeof input.include_windows !== "boolean" ||
+                            (input.include_windows &&
+                                (input.pid !== undefined || typeof input.query !== "string" || !input.query.trim()))))
+                        throw new Error("include_windows requires a named app query without pid.");
+                    if (input.pid !== undefined &&
+                        (typeof input.pid !== "number" || !Number.isSafeInteger(input.pid) || input.pid < 1))
+                        throw new Error("Window lookup requires a positive pid.");
+                    if (name === "computer_launch" &&
+                        (typeof input.name !== "string" || !input.name.trim() || input.name.length > 500))
+                        throw new Error("Launch requires a nonblank name.");
+                    if (input.query !== undefined &&
+                        (typeof input.query !== "string" || !input.query.trim() || Array.from(input.query).length > 240))
+                        throw new Error("Discovery query must be a nonblank string of at most 240 characters.");
+                    const query = typeof input.query === "string" ? input.query.trim() : undefined;
+                    const needle = query?.toLowerCase();
+                    const offset = input.offset ?? 0;
+                    if (typeof offset !== "number" || !Number.isSafeInteger(offset) || offset < 0)
+                        throw new Error("Discovery offset must be a nonnegative safe integer.");
+                    const args = name === "computer_launch" ? { name: input.name } : input.pid === undefined ? {} : { pid: input.pid };
+                    combined.throwIfAborted();
+                    inputDispatched = name === "computer_launch";
+                    phase = "native_request";
+                    failureCode = "discovery_failed";
+                    const reply = await abortable(this.driver.call(operation, args, combined), combined);
+                    const data = driverData(reply);
+                    const discovered = data.apps ?? data.windows;
+                    const rows = Array.isArray(discovered) && needle
+                        ? discovered.filter((row) => {
+                            const item = record(row);
+                            return [item.name, item.app_name, item.title].some((value) => typeof value === "string" && value.toLowerCase().includes(needle));
+                        })
+                        : discovered;
+                    const metadata = Array.isArray(rows)
+                        ? rows.slice(offset, offset + 50).map((row) => {
+                            const item = record(row);
+                            return {
+                                ...select(item, [
+                                    "pid",
+                                    "window_id",
+                                    "name",
+                                    "app_name",
+                                    "title",
+                                    "active",
+                                    "running",
+                                    "is_on_screen",
+                                    "minimized",
+                                ]),
+                                bounds: item.bounds ? select(record(item.bounds), ["x", "y", "width", "height"]) : undefined,
+                            };
+                        })
+                        : undefined;
+                    const remaining = Array.isArray(rows) ? Math.max(0, rows.length - offset - (metadata?.length ?? 0)) : 0;
+                    const failed = driverRefused(reply);
+                    const pid = typeof data.pid === "number" && Number.isSafeInteger(data.pid) && data.pid > 0 ? data.pid : undefined;
+                    const launchWindows = Array.isArray(data.windows)
+                        ? data.windows.slice(0, 50).map((row) => {
+                            const item = record(row);
+                            return {
+                                ...select(item, ["window_id", "title", "is_on_screen", "minimized"]),
+                                bounds: item.bounds ? select(record(item.bounds), ["x", "y", "width", "height"]) : undefined,
+                            };
+                        })
+                        : [];
+                    const returnedId = data.window_id ??
+                        (Array.isArray(data.windows) && data.windows.length === 1
+                            ? record(data.windows[0]).window_id
+                            : undefined);
+                    const windowId = typeof returnedId === "number" && Number.isSafeInteger(returnedId) && returnedId > 0
+                        ? returnedId
+                        : undefined;
+                    let windowsByPid;
+                    let guidance = remaining
+                        ? "Pass next_offset as offset with the same pid and query. Lists refresh per call."
+                        : input.pid !== undefined
+                            ? "Use computer_observe({pid,window_id}) for an exact returned window."
+                            : "App query filters app identities, not every window title. Use computer_apps({pid}) to find windows for a running app.";
+                    if (name === "computer_apps" && input.include_windows === true && !failed) {
+                        const pids = [
+                            ...new Set((Array.isArray(rows) ? rows : [])
+                                .map((row) => record(row).pid)
+                                .filter((value) => typeof value === "number" && Number.isSafeInteger(value) && value > 0)),
+                        ];
+                        if (pids.length > 5)
+                            guidance =
+                                "More than five running processes matched. Narrow the query or choose one positive pid with computer_apps({pid}); no arbitrary process was selected.";
+                        else {
+                            windowsByPid = [];
+                            let budget = 50;
+                            for (const matchingPid of pids) {
+                                combined.throwIfAborted();
+                                try {
+                                    const windowsReply = await abortable(this.driver.call("list_windows", { pid: matchingPid }, combined), combined);
+                                    const windows = driverData(windowsReply).windows;
+                                    if (driverRefused(windowsReply) || !Array.isArray(windows)) {
+                                        windowsByPid.push({
+                                            pid: matchingPid,
+                                            error: driverRefused(windowsReply)
+                                                ? nativeReason(windowsReply)
+                                                : "windows_unavailable",
+                                        });
+                                        continue;
+                                    }
+                                    const subset = windows.slice(0, budget).map((row) => {
+                                        const item = record(row);
+                                        return {
+                                            ...select(item, [
+                                                "pid",
+                                                "window_id",
+                                                "name",
+                                                "app_name",
+                                                "title",
+                                                "active",
+                                                "running",
+                                                "is_on_screen",
+                                                "minimized",
+                                            ]),
+                                            bounds: item.bounds
+                                                ? select(record(item.bounds), ["x", "y", "width", "height"])
+                                                : undefined,
+                                        };
+                                    });
+                                    const omitted = windows.length - subset.length;
+                                    windowsByPid.push({
+                                        pid: matchingPid,
+                                        windows: subset,
+                                        omitted: omitted || undefined,
+                                        next_offset: omitted ? subset.length : undefined,
+                                    });
+                                    budget -= subset.length;
+                                }
+                                catch (error) {
+                                    if (combined.aborted)
+                                        throw error;
+                                    if (error instanceof DriverCallError)
+                                        throw error;
+                                    windowsByPid.push({ pid: matchingPid, error: "window_lookup_failed" });
+                                }
+                            }
+                            guidance =
+                                "Use computer_observe({pid,window_id}) for a returned window. For omitted windows use computer_apps({pid,offset:next_offset}). Per-PID failures need a targeted lookup.";
+                        }
+                    }
+                    if (name === "computer_launch")
+                        guidance =
+                            pid && windowId && !failed
+                                ? `Use computer_observe({pid:${pid},window_id:${windowId}}) before input.`
+                                : `Launch ${failed ? "may have completed despite an unsuccessful reply" : "returned no exact window"}. Use computer_apps({${pid ? `pid:${pid}` : `query:${JSON.stringify(input.name)}`}}) before another launch or input.`;
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    kind: name === "computer_launch" ? "launch" : input.pid === undefined ? "apps" : "windows",
+                                    operation,
+                                    ...(name === "computer_launch"
+                                        ? outcome(reply)
+                                        : { phase: "native_result", code: failed ? nativeReason(reply) : undefined }),
+                                    input: name === "computer_launch" ? "not_applicable" : undefined,
+                                    launch: name === "computer_launch"
+                                        ? plainLaunchReason(reply) === "app_lookup_unavailable"
+                                            ? "not_started"
+                                            : failed
+                                                ? "completion_uncertain"
+                                                : "acknowledged"
+                                        : undefined,
+                                    ...select(data, ["pid", "window_id", "name", "title"]),
+                                    window_id: name === "computer_launch" ? windowId : select(data, ["window_id"]).window_id,
+                                    windows: name === "computer_launch" ? launchWindows : undefined,
+                                    items: name === "computer_launch" ? undefined : metadata,
+                                    windows_by_pid: windowsByPid,
+                                    query,
+                                    offset,
+                                    total: Array.isArray(rows) ? rows.length : undefined,
+                                    omitted: remaining || undefined,
+                                    next_offset: remaining ? offset + 50 : undefined,
+                                    guidance,
+                                }),
+                            },
+                        ],
+                        details: { computer: { failed, workflow: "ready" } },
+                        isError: failed,
+                    };
+                }
+                const target = targetFrom(input);
+                actionTarget = target;
+                if (name === "computer_observe") {
+                    phase = "observation_capture";
+                    const crop = input.crop === undefined ? undefined : this.crop(input, this.fresh(input, previous));
+                    failureCode = "capture_failed";
+                    const captured = await this.capture(target, combined, previous, crop);
+                    const unchanged = this.lastCapture?.fingerprint === captured.fingerprint && sameTarget(this.lastCapture.target, target);
+                    const repeats = crop ? 0 : unchanged ? (this.lastCapture?.repeats ?? 0) + 1 : 1;
+                    this.lastCapture = { fingerprint: captured.fingerprint, target, repeats };
+                    if (repeats >= 3)
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: JSON.stringify({
+                                        phase: "observation_capture",
+                                        code: "unchanged_polling_limit",
+                                        guidance: "Three captures are unchanged. Stop polling and reconsider the target or approach. No input token issued.",
+                                    }),
+                                },
+                            ],
+                            details: { computer: { failed: true, workflow: "stopped" } },
+                            isError: true,
+                        };
+                    return this.imageResult(captured, { unchanged });
+                }
+                const grounded = this.fresh(input, previous);
+                const { operation, args } = this.action(name, input, grounded);
+                const { button = "left", count = 1, modifier = [], ...clickArgs } = args;
+                const signature = JSON.stringify({
+                    operation,
+                    args: operation === "click"
+                        ? {
+                            ...clickArgs,
+                            button,
+                            count,
+                            modifier: Array.isArray(modifier) ? [...new Set(modifier)].sort() : modifier,
+                        }
+                        : args,
+                });
+                if (this.lastAction?.unchanged &&
+                    this.lastAction.signature === signature &&
+                    this.lastAction.fingerprint === grounded.fingerprint)
+                    throw new Error("The identical action had no visible change. Choose a different grounded action; never retry blindly.");
+                combined.throwIfAborted();
+                inputDispatched = true;
+                phase = "native_request";
+                operationName = operation;
+                const reply = await abortable(this.driver.call(operation, args, combined), combined);
+                combined.throwIfAborted();
+                actionOutcome = outcome(reply, name === "computer_text" ? input.text : undefined);
+                const recoveryGuidance = actionOutcome.retry_from_character !== undefined
+                    ? "Verify the field in a fresh image before considering any remaining suffix. retry_from_character is a zero-based Unicode code-point offset, not UTF-16. retryable is driver advice, not authorization to retry."
+                    : undefined;
+                const failed = driverRefused(reply) || driverData(reply).effect === "partial" || driverData(reply).status === "partial";
+                const backgroundUnavailable = actionOutcome.code === "background_unavailable";
+                if (name === "computer_hover")
+                    await delay(700, undefined, { signal: combined });
+                phase = "post_action_capture";
+                try {
+                    const after = await this.capture(target, combined);
+                    const unchanged = after.fingerprint === grounded.fingerprint;
+                    this.lastAction = { signature, fingerprint: after.fingerprint, unchanged };
+                    this.lastCapture = {
+                        fingerprint: after.fingerprint,
+                        target,
+                        repeats: failed &&
+                            this.lastCapture?.fingerprint === after.fingerprint &&
+                            sameTarget(this.lastCapture.target, target)
+                            ? this.lastCapture.repeats
+                            : 0,
+                    };
+                    return this.imageResult(after, {
+                        kind: "action",
+                        operation,
+                        target,
+                        ...actionOutcome,
+                        failed,
+                        unchanged,
+                        guidance: [
+                            "Inspect the post-action image before another action. No visible change does not prove failure; never repeat blindly.",
+                            backgroundUnavailable
+                                ? "After this fresh capture, foreground input may be considered if permitted, not another background shortcut."
+                                : undefined,
+                            recoveryGuidance,
+                        ]
+                            .filter(Boolean)
+                            .join(" "),
+                    });
+                }
+                catch (error) {
+                    combined.throwIfAborted();
+                    if (!(error instanceof CaptureError))
+                        throw error;
+                    this.lastAction = { signature, fingerprint: grounded.fingerprint, unchanged: true };
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    kind: "action",
+                                    operation,
+                                    target,
+                                    ...actionOutcome,
+                                    phase: "post_action_capture",
+                                    capture_error: error.code,
+                                    observation: "unavailable",
+                                    guidance: `Input may have taken effect. ${["target_not_found", "window_target_not_found", "window_target_mismatch"].includes(error.code)
+                                        ? "Use computer_apps({pid}) or observe the desktop to find the target."
+                                        : "Get a fresh capture of the exact target"} before another action; never repeat blindly. ${recoveryGuidance ?? ""}`,
+                                }),
+                            },
+                        ],
+                        details: { computer: { failed: true, workflow: "ready" } },
+                        isError: true,
+                    };
+                }
+            }, combined);
+            if (result.details.computer.workflow !== "ready")
+                return this.finish(result);
+            return result;
+        }
+        catch (error) {
+            if (error instanceof DriverCallError && !(currentPhase() === "post_action_capture" && actionOutcome)) {
+                phase = error.phase;
+                inputDispatched = error.dispatched;
+            }
+            const failurePhase = currentPhase();
+            const fatal = combined.aborted ||
+                this.abort.signal.aborted ||
+                this.lease.signal.aborted ||
+                error instanceof DriverCallError ||
+                !(error instanceof ObservationError ||
+                    error instanceof CaptureError ||
+                    failurePhase === "validation" ||
+                    (failurePhase === "observation_capture" && !inputDispatched));
+            const code = error instanceof ObservationError || error instanceof CaptureError
+                ? error.code
+                : inputDispatched && failurePhase === "post_action_capture"
+                    ? "capture_transport_failed"
+                    : error instanceof DriverCallError
+                        ? error.dispatched
+                            ? "input_dispatch_failed"
+                            : "adapter_preflight_failed"
+                        : inputDispatched
+                            ? "input_dispatch_failed"
+                            : failurePhase === "validation"
+                                ? "invalid_arguments"
+                                : failureCode;
+            const message = name === "computer_launch"
+                ? inputDispatched
+                    ? "Launch request began; activation may have occurred."
+                    : "No launch request was sent by this call."
+                : inputDispatched
+                    ? "Input may have taken effect; request began."
+                    : "No input was sent by this call.";
+            const guidance = inputDispatched
+                ? name === "computer_launch"
+                    ? `Use computer_apps({query:${JSON.stringify(input.name)}) before considering another launch.`
+                    : `Get a fresh capture of the exact target before another action. Input may have taken effect; inspect the field before deciding and never repeat blindly. ${actionOutcome?.retry_from_character !== undefined ? "Verify the field in a fresh image before considering any remaining suffix. retry_from_character is a zero-based Unicode code-point offset, not UTF-16." : ""}`
+                : freshActionGuidance;
+            const result = {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            kind: name === "computer_apps"
+                                ? "apps"
+                                : name === "computer_launch"
+                                    ? "launch"
+                                    : name === "computer_observe"
+                                        ? "observation"
+                                        : "action",
+                            operation: operationName,
+                            target: actionTarget,
+                            ...actionOutcome,
+                            action_outcome: actionOutcome,
+                            phase: failurePhase,
+                            code,
+                            input: name === "computer_apps"
+                                ? undefined
+                                : name === "computer_launch"
+                                    ? "not_applicable"
+                                    : inputDispatched
+                                        ? "uncertain"
+                                        : "not_dispatched",
+                            request: name === "computer_launch" ? (inputDispatched ? "sent" : "not_sent") : undefined,
+                            applicationEffect: "unverified",
+                            observation: "unavailable",
+                            capture_error: failurePhase === "post_action_capture" ? code : undefined,
+                            message,
+                            guidance,
+                        }),
+                    },
+                ],
+                details: { computer: { failed: true, workflow: fatal ? "stopped" : "ready" } },
+                isError: true,
+            };
+            return fatal ? this.finish(result) : result;
+        }
+    }
+    async finish(result) {
+        try {
+            await this.close();
+            return {
+                ...result,
+                details: { ...result.details, computer: { failed: result.details.computer.failed, workflow: "stopped" } },
+            };
+        }
+        catch {
+            return {
+                content: [
+                    ...result.content,
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            phase: "cleanup",
+                            cleanup: "unconfirmed",
+                            guidance: "Desktop ownership retained until shutdown is confirmed.",
+                        }),
+                    },
+                ],
+                details: { ...result.details, computer: { failed: true, workflow: "cleanup_unconfirmed" } },
+                isError: true,
+            };
+        }
+    }
+    close() {
+        this.abort.abort();
+        this.observation = undefined;
+        this.closing ??= this.stop();
+        return this.closing;
+    }
+    async stop() {
+        await this.driver.close();
+        await this.lease.close();
+    }
+}
+//# sourceMappingURL=workflow.js.map