@ycheung5/pi-computer-use 0.0.0-stage → 0.1.0

package/dist/worker.js

@@ -0,0 +1,540 @@
+import { randomUUID } from "node:crypto";
+import { createInterface } from "node:readline";
+import { controlTools, executeAccessibility, observationTools, } from "./accessibility.js";
+import { browse, browserListing, clearBrowserIndicators, configureBrowser, disposeBrowser, isBrowserRequest, } from "./browser.js";
+import { browserActionTools } from "./browser-actions.js";
+import { screenshot, screenshotParameters } from "./capture.js";
+import { disposeDesktop, listWindows, listWindowsParameters, retireDesktop, } from "./desktop.js";
+import { runNativeOperation } from "./native.js";
+import { disposeOcr, ocrDesktop, ocrParameters } from "./ocr.js";
+import { acquireDesktop, disposeOwnership, releaseDesktop, } from "./ownership.js";
+import { awaitPointerCleanup, executePointer, pointerTools, validatePointer, } from "./pointer.js";
+import { PersonalSettingsManager } from "./settings.js";
+import { StopListener } from "./stop.js";
+import { executeText, prepareTextInput, textTools, validateText, } from "./text.js";
+import { waitDesktop, waitTools } from "./waits.js";
+import { manageWindow, windowTools } from "./window-management.js";
+const settings = new PersonalSettingsManager(new Map([
+    [
+        "health",
+        {
+            description: "Check automation worker health",
+            parameters: {
+                type: "object",
+                properties: {},
+                additionalProperties: false,
+            },
+        },
+    ],
+    [
+        "list_windows",
+        {
+            description: "Discover native windows and browser tabs",
+            parameters: listWindowsParameters,
+        },
+    ],
+    [
+        "screenshot",
+        {
+            description: "Capture desktop, native window or browser page",
+            parameters: screenshotParameters,
+        },
+    ],
+    [
+        "ocr",
+        {
+            description: "Read literal screen text and coordinates",
+            parameters: ocrParameters,
+        },
+    ],
+    ...[
+        ...observationTools,
+        ...controlTools,
+        ...pointerTools,
+        ...textTools,
+        ...waitTools,
+        ...windowTools,
+        ...browserActionTools,
+    ].map((tool) => [
+        tool.action,
+        {
+            description: `Windows computer use ${tool.action}`,
+            parameters: tool.parameters,
+        },
+    ]),
+]));
+const input = createInterface({ input: process.stdin, crlfDelay: Infinity });
+let queue = Promise.resolve();
+const requests = new Map();
+const blocked = new Set();
+const lastTargets = new Map();
+function rememberTarget(operationId, result) {
+    const activated = result.action === "activate_window" && result.activated === true;
+    const handle = activated
+        ? result.nativeWindowHandle
+        : result.inputTargetHandle;
+    const owner = activated ? result.processId : result.inputTargetProcessId;
+    if (result.ok && Number.isSafeInteger(handle) && Number.isSafeInteger(owner))
+        lastTargets.set(operationId, {
+            nativeWindowHandle: Number(handle),
+            processId: Number(owner),
+            ...(typeof result.windowRef === "string"
+                ? { windowRef: result.windowRef }
+                : {}),
+        });
+}
+let stopping = Promise.resolve();
+const stopListener = new StopListener((operationId) => {
+    void stopOperation(operationId).catch((error) => process.stderr.write(`${String(error)}\n`));
+});
+let presentationUpdating = false;
+let presentationError;
+const presentationPoll = setInterval(() => {
+    if (!stopListener.hasStarted || presentationUpdating)
+        return;
+    presentationUpdating = true;
+    void settings
+        .synchronize()
+        .then(async ({ settings: current }) => {
+        await stopListener.configure(current);
+        presentationError = undefined;
+    })
+        .catch((error) => {
+        const operation = stopListener.currentOperation;
+        if (operation)
+            void stopOperation(operation).catch(() => undefined);
+        const message = String(error);
+        if (message !== presentationError)
+            process.stderr.write(`PRESENTATION_SETTINGS_FAILED: ${message}\n`);
+        presentationError = message;
+    })
+        .finally(() => {
+        presentationUpdating = false;
+    });
+}, 250);
+presentationPoll.unref();
+async function stopOperation(operationId) {
+    if (blocked.has(operationId))
+        return stopping;
+    blocked.add(operationId);
+    process.stdout.write(`${JSON.stringify({ event: "stopped", operationId })}\n`);
+    stopping = stopping.then(async () => {
+        try {
+            await stopListener.signal(operationId);
+        }
+        finally {
+            for (const request of requests.values())
+                if (request.operationId === operationId &&
+                    request.action !== "operation_end")
+                    request.controller.abort(new Error("COMPUTER_USE_STOPPED"));
+            await awaitPointerCleanup();
+            await clearBrowserIndicators();
+            await retireDesktop();
+        }
+    });
+    return stopping;
+}
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+const inputPreparations = new Map();
+async function acknowledgeInputPreparation(requestId, operationId, signal) {
+    signal.throwIfAborted();
+    const token = randomUUID();
+    await new Promise((resolve, reject) => {
+        const cleanup = () => {
+            inputPreparations.delete(requestId);
+            signal.removeEventListener("abort", abort);
+            input.removeListener("close", abort);
+        };
+        const abort = () => {
+            cleanup();
+            process.stdout.write(`${JSON.stringify({ event: "input_state", active: false })}\n`);
+            reject(signal.reason ?? new Error("COMPUTER_USE_STOPPED"));
+        };
+        inputPreparations.set(requestId, {
+            token,
+            accept: () => {
+                cleanup();
+                resolve();
+            },
+        });
+        signal.addEventListener("abort", abort, { once: true });
+        input.once("close", abort);
+        process.stdout.write(`${JSON.stringify({ event: "input_prepare", requestId, operationId, token })}\n`);
+        if (signal.aborted)
+            abort();
+    });
+}
+async function guardedInput(action, args, operationId, signal, requestId, quietScroll = false) {
+    if (quietScroll)
+        return executeAccessibility(action, args, signal, (normalized) => guardedInput(action, { ...normalized, _quietScroll: true }, operationId, signal, requestId));
+    const armed = await stopListener.arm(operationId, signal);
+    if (!armed.ok || typeof armed.cancelEvent !== "string")
+        return { ...armed, action };
+    const prepared = ["type_text", "keypress"].includes(action)
+        ? await prepareTextInput(action, args, signal)
+        : args;
+    await acknowledgeInputPreparation(requestId, operationId, signal);
+    try {
+        signal.throwIfAborted();
+        if (prepared._quietScroll !== true) {
+            const control = await stopListener.acquire(operationId, signal);
+            if (!control.ok) {
+                process.stdout.write(`${JSON.stringify({ event: "input_state", active: false })}\n`);
+                return { ...control, action, cleanupConfirmed: true };
+            }
+            signal.throwIfAborted();
+        }
+    }
+    catch (error) {
+        process.stdout.write(`${JSON.stringify({ event: "input_state", active: false })}\n`);
+        throw error;
+    }
+    let result;
+    try {
+        result = await executePointer(action, prepared, armed.cancelEvent, operationId, Number(armed.listenerProcessId), signal);
+    }
+    catch (error) {
+        void stopOperation(operationId).catch(() => undefined);
+        throw error;
+    }
+    // Failure leaves the input lease pending; only the native cleanup ACK permits
+    // this notification, worker retirement and eventual desktop ownership release.
+    process.stdout.write(`${JSON.stringify({ event: "input_state", active: false })}\n`);
+    if (!result.ok &&
+        /^(COMPUTER_USE_STOPPED|EXCLUSIVE_CONTROL_LOST|STOP_LISTENER_UNAVAILABLE)/.test(String(result.error)))
+        await stopOperation(operationId);
+    return result;
+}
+async function dispatch(request, signal) {
+    signal.throwIfAborted();
+    const operationId = request.operationId ?? `worker-${process.pid}`;
+    if (request.action === "operation_end") {
+        await stopping;
+        await awaitPointerCleanup();
+        await stopListener.disarm(operationId);
+        await clearBrowserIndicators();
+        const result = await releaseDesktop(operationId);
+        if (result.ok)
+            lastTargets.delete(operationId);
+        process.stdout.write(`${JSON.stringify({ id: request.id, result })}\n`);
+        return;
+    }
+    if (request.action === "indicator_preview") {
+        if (Object.keys(request.args).some((key) => key !== "show") ||
+            (request.args.show !== undefined &&
+                typeof request.args.show !== "boolean")) {
+            process.stdout.write(`${JSON.stringify({ id: request.id, result: { ok: false, action: request.action, error: "INVALID_ARGUMENTS: preview accepts boolean show only" } })}\n`);
+            return;
+        }
+        const current = await settings.synchronize();
+        const result = await stopListener.preview(current.settings, request.args.show !== false);
+        process.stdout.write(`${JSON.stringify({ id: request.id, result: { ...result, action: request.action } })}\n`);
+        return;
+    }
+    if (["settings_get", "settings_update", "tools"].includes(request.action)) {
+        await stopListener.configure((await settings.synchronize()).settings);
+        const result = await settings.handle(request.action, request.args);
+        if (result.ok && settings.currentSettings)
+            await stopListener.configure(settings.currentSettings);
+        process.stdout.write(`${JSON.stringify({ id: request.id, result })}\n`);
+        return;
+    }
+    if (request.args.windowRef !== undefined &&
+        (typeof request.args.windowRef !== "string" ||
+            !request.args.windowRef.trim() ||
+            isBrowserRequest(request.args) ||
+            request.args.scope === "desktop")) {
+        process.stdout.write(`${JSON.stringify({ id: request.id, result: { ok: false, action: request.action, error: "INVALID_ARGUMENTS: windowRef requires a nonempty native-window reference and cannot target desktop/browser channel" } })}\n`);
+        return;
+    }
+    const denial = await settings.authorize(request.action);
+    if (denial) {
+        process.stdout.write(`${JSON.stringify({ id: request.id, result: { ok: false, action: request.action, error: denial } })}\n`);
+        return;
+    }
+    const configuration = settings.currentSettings;
+    if (configuration)
+        await stopListener.configure(configuration);
+    if (configuration &&
+        process.platform === "win32" &&
+        settings.currentFileExists)
+        await configureBrowser({
+            browserApp: configuration.browserApp,
+            browserVisible: configuration.browserVisible,
+            browserSignIn: configuration.browserSignIn,
+        });
+    const suspendCapture = !isBrowserRequest(request.args) &&
+        ["screenshot", "snapshot", "ocr", "find", "wait_for"].includes(request.action);
+    if (suspendCapture)
+        await stopListener.suspendCapture(true);
+    try {
+        if (request.action !== "health" && blocked.has(operationId)) {
+            process.stdout.write(`${JSON.stringify({ id: request.id, result: { ok: false, action: request.action, error: "COMPUTER_USE_STOPPED: wait for a new user operation" } })}\n`);
+            return;
+        }
+        if (request.action !== "health" && process.platform === "win32") {
+            const ownership = await acquireDesktop(operationId, signal);
+            if (!ownership.ok) {
+                process.stdout.write(`${JSON.stringify({ id: request.id, result: { ...ownership, action: request.action } })}\n`);
+                return;
+            }
+        }
+        const previous = lastTargets.get(operationId);
+        if (previous &&
+            !isBrowserRequest(request.args) &&
+            request.args.scope !== "desktop" &&
+            ![
+                "list_windows",
+                "health",
+                "operation_end",
+                "wait",
+                "launch_app",
+                "activate_window",
+                "move_window",
+                "close_window",
+            ].includes(request.action) &&
+            ![
+                "windowRef",
+                "windowTitle",
+                "processId",
+                "nativeWindowHandle",
+                "elementId",
+            ].some((key) => request.args[key] !== undefined))
+            request.args = { ...request.args, ...previous };
+        if (request.action === "prepare_input") {
+            const result = await stopListener.arm(operationId, signal);
+            process.stdout.write(`${JSON.stringify({ id: request.id, result })}\n`);
+            return;
+        }
+        if (["type_text", "keypress"].includes(request.action) &&
+            !isBrowserRequest(request.args)) {
+            const invalid = validateText(request.action, request.args);
+            if (invalid) {
+                process.stdout.write(`${JSON.stringify({ id: request.id, result: invalid })}\n`);
+                return;
+            }
+            let result;
+            if ((request.action === "type_text" &&
+                ["auto", "background"].includes(String(request.args.method ?? "auto"))) ||
+                request.args.dispatch === "background") {
+                result = await executeText(request.action, request.args, "", operationId, undefined, signal);
+                if (result.inputRequired !== true) {
+                    rememberTarget(operationId, result);
+                    process.stdout.write(`${JSON.stringify({ id: request.id, result })}\n`);
+                    return;
+                }
+            }
+            result = await guardedInput(request.action, request.args, operationId, signal, request.id);
+            rememberTarget(operationId, result);
+            process.stdout.write(`${JSON.stringify({ id: request.id, result })}\n`);
+            return;
+        }
+        if (!isBrowserRequest(request.args) &&
+            (["click", "double_click", "move", "drag"].includes(request.action) ||
+                (request.action === "scroll" && !request.args.elementId))) {
+            const invalid = validatePointer(request.action, request.args);
+            if (invalid) {
+                process.stdout.write(`${JSON.stringify({ id: request.id, result: invalid })}\n`);
+                return;
+            }
+            // Only the explicit needs-input result permits escalation/retry. No timeout,
+            // stale/disabled/covered-point error can trigger replay.
+            if ((request.args.dispatch === "background" ||
+                (request.action === "click" &&
+                    request.args.elementId &&
+                    (request.args.button ?? "left") === "left" &&
+                    !request.args.activate &&
+                    request.args.dispatch !== "foreground")) &&
+                ["click", "double_click"].includes(request.action)) {
+                const quiet = await executePointer(request.action, request.args, "", operationId, undefined, signal);
+                if (!quiet.inputRequired || request.args.dispatch === "background") {
+                    rememberTarget(operationId, quiet);
+                    process.stdout.write(`${JSON.stringify({ id: request.id, result: quiet })}\n`);
+                    return;
+                }
+            }
+            const result = await guardedInput(request.action, request.args, operationId, signal, request.id);
+            rememberTarget(operationId, result);
+            process.stdout.write(`${JSON.stringify({ id: request.id, result })}\n`);
+            return;
+        }
+        const response = {
+            id: request.id,
+            result: request.action === "health"
+                ? {
+                    ok: true,
+                    action: "health",
+                    processId: process.pid,
+                    platform: process.platform,
+                    nodeVersion: process.version,
+                    control: await stopListener.status(),
+                    settings: {
+                        preset: settings.currentSettings?.toolPreset,
+                        notices: settings.currentNotices,
+                        source: settings.currentSource,
+                    },
+                }
+                : isBrowserRequest(request.args)
+                    ? await browse(request.action, request.args, signal)
+                    : windowTools.some((tool) => tool.action === request.action)
+                        ? await manageWindow(request.action, request.args, signal)
+                        : ["wait", "wait_for"].includes(request.action)
+                            ? await waitDesktop(request.action, request.args, signal)
+                            : request.action === "list_windows"
+                                ? {
+                                    ...(await listWindows(request.args, signal)),
+                                    browserLane: await browserListing(),
+                                }
+                                : request.action === "ocr"
+                                    ? await ocrDesktop(request.args, signal)
+                                    : request.action === "screenshot"
+                                        ? await screenshot(request.args, signal)
+                                        : [
+                                            "snapshot",
+                                            "accessibility_tree",
+                                            "find",
+                                            "element_info",
+                                            "focus",
+                                            "invoke",
+                                            "set_value",
+                                            "scroll",
+                                        ].includes(request.action)
+                                            ? request.action === "scroll"
+                                                ? await guardedInput(request.action, request.args, operationId, signal, request.id, true)
+                                                : await executeAccessibility(request.action, request.args, signal)
+                                            : {
+                                                ok: false,
+                                                action: request.action,
+                                                error: "UNKNOWN_ACTION",
+                                            },
+        };
+        if (!isBrowserRequest(request.args) &&
+            response.result.inputRequired === true &&
+            ["invoke", "scroll"].includes(request.action)) {
+            const pointerAction = request.action === "invoke" ? "click" : "scroll";
+            const result = await guardedInput(pointerAction, { ...request.args, dispatch: "foreground" }, operationId, signal, request.id);
+            response.result = {
+                ...result,
+                action: request.action,
+                method: result.ok ? `fallback:${String(result.method)}` : result.method,
+            };
+        }
+        if (!isBrowserRequest(request.args) &&
+            request.action === "set_value" &&
+            response.result.inputRequired === true) {
+            const textArgs = {
+                text: request.args.value,
+                method: "clipboard",
+                focusMode: "preserve",
+                restoreClipboard: request.args.restoreClipboard ?? true,
+                _elementId: request.args.elementId,
+                _replaceAll: true,
+            };
+            for (const key of [
+                "windowRef",
+                "windowTitle",
+                "processId",
+                "nativeWindowHandle",
+                "activate",
+            ])
+                if (request.args[key] !== undefined)
+                    textArgs[key] = request.args[key];
+            const result = await guardedInput("type_text", textArgs, operationId, signal, request.id);
+            response.result = {
+                ...result,
+                action: "set_value",
+                method: result.ok ? `fallback:${String(result.method)}` : result.method,
+            };
+        }
+        rememberTarget(operationId, response.result);
+        process.stdout.write(`${JSON.stringify(response)}\n`);
+    }
+    finally {
+        if (suspendCapture)
+            await stopListener.suspendCapture(false);
+    }
+}
+input.on("line", (line) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        process.stderr.write("WORKER_PROTOCOL_ERROR: invalid JSON\n");
+        return;
+    }
+    if (isObject(parsed) &&
+        typeof parsed.inputAck === "string" &&
+        Number.isSafeInteger(parsed.requestId)) {
+        const preparation = inputPreparations.get(Number(parsed.requestId));
+        if (preparation && preparation.token === parsed.inputAck)
+            preparation.accept();
+        return;
+    }
+    if (isObject(parsed) && typeof parsed.stop === "string") {
+        void stopOperation(parsed.stop).catch((error) => process.stderr.write(`${String(error)}\n`));
+        return;
+    }
+    if (isObject(parsed) && "cancel" in parsed) {
+        if (typeof parsed.cancel === "number") {
+            const request = requests.get(parsed.cancel);
+            if (request)
+                void stopOperation(request.operationId).catch((error) => process.stderr.write(`${String(error)}\n`));
+        }
+        return;
+    }
+    if (!isObject(parsed) || !Number.isSafeInteger(parsed.id)) {
+        process.stderr.write("WORKER_PROTOCOL_ERROR: request requires a numeric id\n");
+        return;
+    }
+    if (typeof parsed.action !== "string" ||
+        !isObject(parsed.args) ||
+        (parsed.operationId !== undefined &&
+            (typeof parsed.operationId !== "string" ||
+                parsed.operationId.length < 1 ||
+                parsed.operationId.length > 200))) {
+        process.stdout.write(`${JSON.stringify({ id: parsed.id, result: { ok: false, action: typeof parsed.action === "string" ? parsed.action : "invalid_request", error: "INVALID_REQUEST: action must be a string and args must be an object" } })}\n`);
+        return;
+    }
+    const request = parsed;
+    if (requests.has(request.id)) {
+        process.stderr.write("WORKER_PROTOCOL_ERROR: duplicate request id\n");
+        return;
+    }
+    const controller = new AbortController();
+    requests.set(request.id, {
+        controller,
+        operationId: request.operationId ?? `worker-${process.pid}`,
+        action: request.action,
+    });
+    queue = queue
+        .then(() => runNativeOperation(request.operationId ?? `worker-${process.pid}`, () => dispatch(request, controller.signal)))
+        .catch((error) => {
+        process.stdout.write(`${JSON.stringify({ id: request.id, result: { ok: false, action: request.action, error: controller.signal.aborted ? "COMPUTER_USE_STOPPED" : String(error) } })}\n`);
+    })
+        .finally(() => {
+        requests.delete(request.id);
+    });
+});
+input.on("close", () => {
+    clearInterval(presentationPoll);
+    process.stdout.write(`${JSON.stringify({ event: "shutdown_state", phase: "started" })}\n`);
+    void queue
+        .then(async () => {
+        await stopping;
+        await disposeBrowser();
+        await awaitPointerCleanup();
+        await disposeDesktop();
+        await disposeOcr();
+        await stopListener.dispose();
+        await disposeOwnership();
+        process.stdout.write(`${JSON.stringify({ event: "shutdown_state", phase: "complete" })}\n`);
+    })
+        .catch((error) => {
+        // Keep native handles and ownership alive if safe exit cannot be proved.
+        process.stderr.write(`CLEANUP_UNCONFIRMED: ${String(error)}\n`);
+        process.stdout.write(`${JSON.stringify({ event: "shutdown_state", phase: "failed", error: String(error) })}\n`);
+    });
+});

package/docs/README.md

@@ -0,0 +1,54 @@
+# Documentation index
+
+Read the row matching the task; follow section links before reading whole documents.
+
+| Task | Read |
+| --- | --- |
+| Requirements and scope | [Spec: solution](spec.md#solution), [user stories](spec.md#user-stories), [out of scope](spec.md#out-of-scope) |
+| Implementation contracts | [Spec: implementation decisions](spec.md#implementation-decisions) |
+| Delivery, design review and feasibility | [Design revision](implementation-plan.md#design-revision), [plan: detailed milestones](implementation-plan.md#detailed-milestones), [feasibility gates](implementation-plan.md#feasibility-gates) |
+| Test design and release validation | [Spec: testing decisions](spec.md#testing-decisions), [plan: coverage matrix](implementation-plan.md#coverage-matrix) |
+| Pi acceptance, phased testing and agent recovery | [Current phases](implementation-plan.md#detailed-milestones), [baseline audit](validation.md#baseline-identity-and-schema-evidence), [guidance inventory](validation.md#model-visible-guidance-inventory), [scenario catalog](validation.md#alignment-scenario-catalog) |
+| Release checks, capability coverage and pending acceptance | [0.1.0 release preparation](validation.md#first-release-preparation), [current release audit](validation.md#final-release-audit), [capability coverage](validation.md#capability-coverage), [validation history](validation.md) |
+| Pi interfaces and sources | [Pi extension research](pi-extension-research.md) (research context; current spec takes precedence over earlier proposals) |
+| Domain terminology | [Glossary](../GLOSSARY.md) |
+| Current Pi-first acceptance scope | [ADR 0004](adr/0004-pi-first-acceptance.md) |
+| Windows default apps, existing windows and foreground | [Accepted policy](spec.md#default-apps-workspaces-and-foreground), [ADR 0005](adr/0005-default-apps-and-workspace-reuse.md), [delivery cases](implementation-plan.md#default-app-and-workspace-delivery), [current support](windows.md#default-apps-and-workspaces) |
+| Historical reference-parity decision | [Superseded ADR 0001](adr/0001-preserve-reference-behavior.md) |
+| Stronger native window identity design | [Lifetime plan](implementation-plan.md#window-lifetime-design), [ADR 0002](adr/0002-window-lifetime-references.md) |
+| Publish or read issues | [Issue tracker](agents/issue-tracker.md), [triage labels](agents/triage-labels.md) |
+| What works, remaining outcomes, next work and cleanup decisions | [Progress summary](tickets.md#current-progress), [delivery map](tickets.md#delivery-outcomes-and-ownership), [execution queue](tickets.md#execution-queue), [cleanup dispositions](tickets.md#cleanup-dispositions), [original obligations](tickets.md#original-issue-disposition) |
+| Worker setup, protocol and test evidence | [Runtime and validation](runtime.md) |
+| Exclusive control, human handback and emergency stopping | [Control contract](spec.md#exclusive-control), [delivery/test slices](implementation-plan.md#exclusive-control-delivery), [ADR 0003](adr/0003-exclusive-desktop-control.md), [current stopping implementation](stopping.md), [control acceptance](validation.md#control-interruption-acceptance) |
+| Control indicators, preview and recording acceptance | [Indicators](indicators.md), [Snipping Tool receipt](validation.md#snipping-tool-recording-acceptance) |
+| Desktop ownership and operation lifecycle | [Ownership](ownership.md) |
+| Native window discovery and validation | [Windows discovery](windows.md), [accessibility observations](windows.md#accessibility-observations), [targeting acceptance reconciliation](validation.md#pi-targeting-and-accessibility-reconciliation), [OCR failures](validation.md#pi-ocr-failure-acceptance), [locked sessions](windows.md#locked-session-refusals) |
+| Scoped browser/mixed agent acceptance | [Held-navigation cancellation](validation.md#scoped-held-navigation-cancellation), [Partial-observation recovery](validation.md#scoped-partial-observation-recovery), [mixed outcome evidence](validation.md#scoped-mixed-browsernative-outcome), [runner prerequisites](validation.md#reproduce-automated-checks), [ordinary workspace actor outcomes](validation.md#ordinary-pi-workspace-actor-preparation) |
+| Scoped native document and visual agent acceptance | [Document workflow](validation.md#native-document-workflow), [handback continuation](validation.md#native-cancellation-and-handback-continuation), [opt-in visual runner](windows.md#scoped-visual-agent-check), [A04 evidence](validation.md#visual-ocr-association-preflight) |
+| Lifetime-bound native targeting and stale-reference behavior | [Window references](windows.md#window-lifetime-references), [accepted design](implementation-plan.md#window-lifetime-design) |
+| Native interop alternatives and tradeoffs | [Native interop research](native-interop-research.md) |
+| Guarded desktop pointer and dedicated input validation | [Pointer actions](pointer.md), [popup/menu/cross-process drop and restoration acceptance](validation.md#scoped-pointer-and-restoration-acceptance) |
+| Text, chords, clipboard preservation and validation | [Text entry](text.md), [chord/editor-focus acceptance](validation.md#pi-chords-and-editor-focus-acceptance), [clipboard acceptance](validation.md#pi-clipboard-contention-and-privacy-acceptance) |
+| Personal settings, commands and tool loading | [Settings](settings.md) |
+| Browser reads/actions, dedicated profiles, idle cleanup and fixtures | [Browser](browser.md) |
+| Domain-document consumer rules | [Domain docs](agents/domain.md) |
+
+## Repository layout
+
+```text
+README.md              project entry point
+AGENTS.md              short contributor rules and routing
+GLOSSARY.md            domain terms
+src/                   flat TypeScript modules
+tests/                 tests and native smoke fixtures
+assets/                packaged resources and runtime notices
+docs/
+  README.md            this index
+  spec.md              authoritative requirements
+  implementation-plan.md  delivery, feasibility and coverage
+  pi-extension-research.md  cited Pi interface research
+  adr/                 durable decision rationale
+  agents/              issue tracker, triage and domain configuration
+```
+
+Use the existing source, test and asset directories. Keep responsibility-named modules such as extension, launcher, worker, desktop, browser, settings and stop; split by demonstrated complexity rather than pre-creating a directory per module.

package/docs/adr/0001-preserve-reference-behavior.md

@@ -0,0 +1,9 @@
+---
+status: superseded by ADR-0004
+---
+
+# Preserve reference behavior while implementing for Pi
+
+Historical decision. [ADR 0004](0004-pi-first-acceptance.md) replaces mandatory DSH parity with Pi-first acceptance; the Pi capability and safety requirements remain in the current specification.
+
+Implement fresh TypeScript code for native Pi tools and Windows/WSL2 hosts, using dsh-computer-use-win 0.5.3 as the behavioral baseline. Preserve its safeguards, browser post-action observations and experimental installed-Firefox compatibility rather than changing behavior to fit a simpler browser library; simplification remains welcome where these contracts are retained. [ADR 0003](0003-exclusive-desktop-control.md) supersedes shared physical-user-input behavior for exclusive-control periods; other reference contracts remain the baseline. This trades some implementation freedom for a faithful Pi version and supersedes the proposed managed-Firefox and observation changes.

package/docs/adr/0002-window-lifetime-references.md

@@ -0,0 +1,11 @@
+---
+status: accepted
+---
+
+# Bind observed targets to a window lifetime
+
+The user chose stronger window-lifetime tracking beyond DSH's HWND/PID checks; this records the reviewed implementation design, not delivered feature acceptance. Keep the reference authority beside the existing native UIA cache, using a unique private window property as a lifetime witness; expose one opaque `windowRef` target field and retain raw selectors as explicit compatibility selection. This avoids a second registry and asynchronous event-delivery assumptions, at the cost of window-metadata writes, UIPI restrictions, conservative invalidation after native-child restart and possible scalar-marker residue after abrupt native-child exit.
+
+The owned-window probe confirmed marker isolation, removal and replacement behavior; it did not achieve identical-HWND reuse. [UIA RuntimeIds can be reused](https://learn.microsoft.com/en-us/windows/win32/api/uiautomationclient/nf-uiautomationclient-iuiautomationelement-getruntimeid), [WinEvent delivery can be asynchronous](https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-setwineventhook), and [SetProp requires ownership hygiene and respects UIPI](https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-setpropw). Validation cannot atomically lock a foreign window through a later action; the contract rejects already-lost proof and prevents subsequent steps rather than promising to undo racing effects. Implementation and acceptance follow [the #28 plan](../implementation-plan.md#window-lifetime-design).
+
+Unavailable binding leaves read metadata available without actionable native reference IDs. Existing desktop-image snapshots retain separate desktop provenance; stronger window identity does not change their image scope.

package/docs/adr/0003-exclusive-desktop-control.md

@@ -0,0 +1,11 @@
+---
+status: accepted
+---
+
+# Use exclusive control for physical desktop automation
+
+The user chose suppression of ordinary physical keyboard/mouse input while the agent controls the desktop, with a blue border and explicit stop or human handback. This departs from DSH's selectively handled stop keys and Pi's earlier interference-aborts behavior: accidental interaction should not disrupt an agent task. It superseded that part of [ADR 0001](0001-preserve-reference-behavior.md), trading simultaneous desktop use for a simpler control contract; full acceptance is pending and all Pi safeguards remain. [ADR 0004](0004-pi-first-acceptance.md) now governs the broader Pi-first acceptance scope.
+
+Requirements live in the [spec](../spec.md#exclusive-control); feasibility, responsibility boundaries and acceptance live in the [plan](../implementation-plan.md#exclusive-control-delivery). [BlockInput](https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-blockinput) restricts injection to its owning thread, while [keyboard hooks](https://learn.microsoft.com/en-us/windows/win32/winmsg/lowlevelkeyboardproc) can suppress events but can be removed on timeout. The candidate uses hooks in the existing independent listener, which allows separately tagged agent input. The native observer ignores physical input only when a downstream hook confirms it consumed the event and the retained listener/protection event remain valid; unconsumed or foreign injected input still invalidates the action. Tagged absolute pointer movement replaces the old expected-SetCursorPos queue.
+
+On 2026-11-01, after the grouped physical check passed and a nonelevated BlockInput probe returned access denied, the user chose hooks with documented Windows limits for the first release. This avoids requiring additional privileges or isolation. Silent hook removal can allow physical events through and make physical stop keys unavailable; neither a live listener nor a stored hook handle proves otherwise. The first release accepts that specific platform limit, without claiming absolute input blocking. Detected protection loss must still stop automation and preserve uncertain-input safeguards. The decision does not waive remaining physical, failure, host or cleanup acceptance, or make #31 complete.

package/docs/adr/0004-pi-first-acceptance.md

@@ -0,0 +1,9 @@
+---
+status: accepted
+---
+
+# Judge release readiness by Pi functionality
+
+On 2026-11-02 the user prioritized a working standalone Pi extension over copying DSH and discarded the remaining DSH manual comparisons. This supersedes ADR 0001's mandatory behavioral-parity gate: DSH remains design/source context, while the current Pi specification defines supported behavior and acceptance. DSH installation, credentials, host/model runs, side-by-side manual checks and comparative performance are no longer release prerequisites.
+
+Keep the 25 implemented tool capabilities, supported browsers/hosts, preservation and cleanup safeguards, exclusive control and the accepted Windows hook limitation. Reuse existing Pi evidence; preserve historical comparisons as historical evidence, with reference-backed developer utilities optional. Close a Pi deliverable only when its remaining Pi criteria are supported; transfer any shared Pi obligations explicitly before retiring an alignment/diagnosis umbrella. Independent Pi correctness, failure handling and useful responsiveness still matter.

package/docs/adr/0005-default-apps-and-workspace-reuse.md

@@ -0,0 +1,7 @@
+---
+status: accepted
+---
+
+# Follow Windows defaults and reuse the user's workspace
+
+On 2026-11-02 the user chose Windows default apps and a new task tab/document in the intended existing window, with coherent foreground handling, because separate browser launches and repeated focus changes disrupted normal use. This supersedes the specification's dedicated-browser-profile default: existing profile acceptance remains valid for the explicit dedicated mode, while ordinary-app reuse may require native UI rather than the current browser protocol channel. Requirements live in the [spec](../spec.md#default-apps-workspaces-and-foreground); #30 owns implementation and acceptance, with editor-focus behavior shared with #26.

package/docs/agents/domain.md

@@ -0,0 +1,9 @@
+# Domain docs
+
+This is a single-context project.
+
+Read the root [GLOSSARY.md](../../GLOSSARY.md) for domain terminology and relevant decisions in [docs/adr/](../adr/) before exploring or changing the affected behavior. Use the glossary's vocabulary and surface conflicts with existing ADRs explicitly.
+
+If a domain document is absent, proceed; create new terms or decisions through domain-modeling only when needed.
+
+Use [docs/README.md](../README.md) to find task-specific documentation.