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

package/dist/pointer.d.ts

@@ -0,0 +1,128 @@
+import type { WorkerResult } from "./protocol.js";
+export declare const pointerTools: {
+    action: string;
+    parameters: {
+        required?: string[] | undefined;
+        type: string;
+        additionalProperties: boolean;
+        properties: {
+            dispatch?: {
+                type: string;
+                enum: string[];
+                default: string;
+            } | undefined;
+            button?: {
+                type: string;
+                enum: string[];
+                default: string;
+            } | undefined;
+            path: {
+                type: string;
+                items: {
+                    type: string;
+                    additionalProperties: boolean;
+                    properties: {
+                        x: {
+                            type: string;
+                        };
+                        y: {
+                            type: string;
+                        };
+                    };
+                    required: string[];
+                };
+                minItems: number;
+                maxItems: number;
+            };
+            holdMs?: {
+                type: string;
+                minimum: number;
+                maximum: number;
+            } | undefined;
+            timeoutMs?: {
+                type: string;
+                minimum: number;
+                maximum: number;
+            } | undefined;
+            windowRef: {
+                type: string;
+                minLength: number;
+            };
+            windowTitle: {
+                type: string;
+            };
+            processId: {
+                minimum: number;
+                type: string;
+            };
+            nativeWindowHandle: {
+                minimum: number;
+                type: string;
+            };
+            activate: {
+                type: string;
+            };
+        } | {
+            dispatch?: {
+                type: string;
+                enum: string[];
+                default: string;
+            } | undefined;
+            button?: {
+                type: string;
+                enum: string[];
+                default: string;
+            } | undefined;
+            elementId: {
+                type: string;
+                minLength: number;
+            };
+            x: {
+                type: string;
+            };
+            y: {
+                type: string;
+            };
+            viewMode: {
+                type: string;
+                enum: string[];
+                default: string;
+            };
+            includeOffscreen: {
+                type: string;
+                default: boolean;
+            };
+            holdMs?: {
+                type: string;
+                minimum: number;
+                maximum: number;
+            } | undefined;
+            timeoutMs?: {
+                type: string;
+                minimum: number;
+                maximum: number;
+            } | undefined;
+            windowRef: {
+                type: string;
+                minLength: number;
+            };
+            windowTitle: {
+                type: string;
+            };
+            processId: {
+                minimum: number;
+                type: string;
+            };
+            nativeWindowHandle: {
+                minimum: number;
+                type: string;
+            };
+            activate: {
+                type: string;
+            };
+        };
+    };
+}[];
+export declare function validatePointer(action: string, args: Record<string, unknown>): WorkerResult | undefined;
+export declare function awaitPointerCleanup(): Promise<void>;
+export declare function executePointer(action: string, args: Record<string, unknown>, cancelEvent: string, operationId: string, listenerProcessId?: number, signal?: AbortSignal): Promise<WorkerResult>;

package/dist/pointer.js

@@ -0,0 +1,198 @@
+import { pressTiming, timingMilliseconds } from "./input-timing.js";
+import { confirmInputCleanup, nativeDesktop, retainInput } from "./native.js";
+const integer = { type: "integer" };
+const target = {
+    windowRef: { type: "string", minLength: 1 },
+    windowTitle: { type: "string" },
+    processId: { ...integer, minimum: 1 },
+    nativeWindowHandle: { ...integer, minimum: 1 },
+    activate: { type: "boolean" },
+};
+const point = {
+    type: "object",
+    additionalProperties: false,
+    properties: { x: integer, y: integer },
+    required: ["x", "y"],
+};
+export const pointerTools = ["click", "double_click", "move", "drag"].map((action) => ({
+    action,
+    parameters: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+            ...target,
+            ...(action === "click"
+                ? { holdMs: timingMilliseconds, timeoutMs: timingMilliseconds }
+                : {}),
+            ...(action === "drag"
+                ? {
+                    path: {
+                        type: "array",
+                        items: point,
+                        minItems: 2,
+                        maxItems: 1000,
+                    },
+                }
+                : {
+                    elementId: { type: "string", minLength: 1 },
+                    x: integer,
+                    y: integer,
+                    viewMode: {
+                        type: "string",
+                        enum: ["control", "content", "raw"],
+                        default: "control",
+                    },
+                    includeOffscreen: { type: "boolean", default: false },
+                }),
+            ...(action !== "move"
+                ? {
+                    button: {
+                        type: "string",
+                        enum: ["left", "right", "middle"],
+                        default: "left",
+                    },
+                }
+                : {}),
+            ...(["click", "double_click"].includes(action)
+                ? {
+                    dispatch: {
+                        type: "string",
+                        enum: ["auto", "background", "foreground"],
+                        default: "auto",
+                    },
+                }
+                : {}),
+        },
+        ...(action === "drag" ? { required: ["path"] } : {}),
+    },
+}));
+export function validatePointer(action, args) {
+    const bad = (message) => ({
+        ok: false,
+        action,
+        error: `INVALID_ARGUMENTS: ${message}`,
+    });
+    const keys = new Set([
+        "windowRef",
+        "windowTitle",
+        "processId",
+        "nativeWindowHandle",
+        "activate",
+        ...(action === "drag"
+            ? ["path", "button"]
+            : [
+                "elementId",
+                "x",
+                "y",
+                "viewMode",
+                "includeOffscreen",
+                ...(action === "move" ? [] : ["button", "dispatch"]),
+            ]),
+        ...(action === "click" ? ["holdMs", "timeoutMs"] : []),
+        ...(action === "scroll" ? ["deltaX", "deltaY", "browserTab"] : []),
+    ]);
+    if (args.windowRef !== undefined &&
+        (typeof args.windowRef !== "string" || !args.windowRef.trim()))
+        return bad("windowRef must be nonempty");
+    for (const key of Object.keys(args))
+        if (!keys.has(key))
+            return bad(`unknown option ${key}`);
+    for (const key of ["processId", "nativeWindowHandle"])
+        if (args[key] !== undefined &&
+            (!Number.isSafeInteger(args[key]) || Number(args[key]) < 1))
+            return bad(`${key} must be a positive integer`);
+    for (const key of ["x", "y", "deltaX", "deltaY"])
+        if (args[key] !== undefined &&
+            (!Number.isSafeInteger(args[key]) ||
+                Math.abs(Number(args[key])) > 2147483647))
+            return bad(`${key} must be a 32-bit integer`);
+    for (const key of ["activate", "includeOffscreen"])
+        if (args[key] !== undefined && typeof args[key] !== "boolean")
+            return bad(`${key} must be boolean`);
+    if (args.windowTitle !== undefined && typeof args.windowTitle !== "string")
+        return bad("windowTitle must be a string");
+    if (args.viewMode !== undefined &&
+        !["control", "content", "raw"].includes(String(args.viewMode)))
+        return bad("unsupported viewMode");
+    if (args.button !== undefined &&
+        !["left", "right", "middle"].includes(String(args.button)))
+        return bad("unsupported button");
+    if (args.dispatch !== undefined &&
+        !["auto", "background", "foreground"].includes(String(args.dispatch)))
+        return bad("unsupported dispatch");
+    if (action === "click") {
+        try {
+            pressTiming(args, 90_000);
+        }
+        catch (cause) {
+            return {
+                ok: false,
+                action,
+                error: cause instanceof Error ? cause.message : String(cause),
+            };
+        }
+        if ((args.holdMs !== undefined || args.timeoutMs !== undefined) &&
+            (args.dispatch === "background" || args.activate === false))
+            return {
+                ok: false,
+                action,
+                error: "TIMING_UNSUPPORTED: click timing requires native foreground dispatch without explicit activate: false",
+            };
+    }
+    if (action === "drag") {
+        if (!Array.isArray(args.path) ||
+            args.path.length < 2 ||
+            args.path.length > 1000)
+            return bad("path needs 2–1000 screen points");
+        for (const p of args.path)
+            if (!p ||
+                typeof p !== "object" ||
+                Object.keys(p).some((k) => k !== "x" && k !== "y") ||
+                !Number.isInteger(p.x) ||
+                !Number.isInteger(p.y) ||
+                Math.abs(p.x) > 2147483647 ||
+                Math.abs(p.y) > 2147483647)
+                return bad("path requires integer x/y screen points");
+    }
+    else {
+        if (args.elementId !== undefined &&
+            (typeof args.elementId !== "string" || !args.elementId.length))
+            return bad("elementId must be nonempty");
+        if (!args.elementId && (args.x === undefined || args.y === undefined))
+            return bad("provide elementId or both x and y");
+        if ((args.x === undefined) !== (args.y === undefined))
+            return bad("provide both x and y");
+    }
+    return undefined;
+}
+// A missing native acknowledgment keeps the lease held. Never kill a bridge that
+// could still have a button down, including after a timeout/transport failure.
+let cleanup;
+let cleanupFailure;
+export async function awaitPointerCleanup() {
+    await cleanup;
+    if (cleanupFailure)
+        throw cleanupFailure;
+}
+export async function executePointer(action, args, cancelEvent, operationId, listenerProcessId, signal) {
+    await awaitPointerCleanup();
+    if (!cancelEvent)
+        return nativeDesktop.execute(action, { ...args, _cancelEvent: "" }, signal, operationId);
+    retainInput();
+    const execution = nativeDesktop.execute(action, { ...args, _cancelEvent: cancelEvent, _stopProcessId: listenerProcessId }, undefined, operationId);
+    cleanup = execution
+        .then((result) => {
+        if (result.cleanupConfirmed !== true)
+            throw new Error("INPUT_CLEANUP_UNCONFIRMED: retain desktop ownership");
+        confirmInputCleanup();
+    })
+        .catch((error) => {
+        cleanupFailure = error;
+        throw error;
+    });
+    // Attach immediately; dispatch will await the same completion below.
+    void cleanup.catch(() => undefined);
+    const result = await execution;
+    await cleanup;
+    return result;
+}

package/dist/protocol.d.ts

@@ -0,0 +1,15 @@
+export interface WorkerRequest {
+    id: number;
+    action: string;
+    args: Record<string, unknown>;
+    operationId?: string;
+}
+export interface WorkerResult {
+    ok: boolean;
+    action: string;
+    [key: string]: unknown;
+}
+export interface WorkerResponse {
+    id: number;
+    result: WorkerResult;
+}

package/dist/protocol.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime.d.ts

@@ -0,0 +1,8 @@
+export declare const WINDOWS_NODE_VERSION = "22.23.4";
+export interface RuntimeOptions {
+    directory: string;
+    architecture: string;
+    signal?: AbortSignal;
+    download?: typeof fetch;
+}
+export declare function provisionRuntime(options: RuntimeOptions): Promise<string>;

package/dist/runtime.js

@@ -0,0 +1,72 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+export const WINDOWS_NODE_VERSION = "22.23.4";
+const checksums = {
+    x64: "dccc52de28d8df2ee22d2062424f8c563070d95d8ad70c54c4bf01d590dec14f",
+    arm64: "64d9f6e69b4703870e8cd30a3477127df8b683ea04feb03660e439396549042a",
+};
+function verify(bytes, checksum) {
+    if (createHash("sha256").update(bytes).digest("hex") !== checksum) {
+        throw new Error("RUNTIME_CHECKSUM_MISMATCH: private Windows Node is corrupt; remove the runtime cache and retry on a trusted connection");
+    }
+}
+export async function provisionRuntime(options) {
+    const { architecture, directory, signal } = options;
+    if (architecture !== "x64" && architecture !== "arm64") {
+        throw new Error(`UNSUPPORTED_ARCHITECTURE: Windows ${architecture}; supported: x64, arm64`);
+    }
+    signal?.throwIfAborted();
+    const folder = join(directory, `node-${WINDOWS_NODE_VERSION}-win-${architecture}`);
+    const executable = join(folder, "node.exe");
+    const checksum = checksums[architecture];
+    try {
+        const bytes = await readFile(executable);
+        signal?.throwIfAborted();
+        verify(bytes, checksum);
+        return executable;
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+            throw error;
+    }
+    const timeout = AbortSignal.timeout(120_000);
+    const downloadSignal = signal ? AbortSignal.any([signal, timeout]) : timeout;
+    const response = await (options.download ?? fetch)(`https://nodejs.org/dist/v${WINDOWS_NODE_VERSION}/win-${architecture}/node.exe`, { signal: downloadSignal });
+    if (!response.ok || !response.body) {
+        throw new Error(`RUNTIME_DOWNLOAD_FAILED: HTTP ${response.status}; allow HTTPS access to nodejs.org and retry`);
+    }
+    const parts = [];
+    let size = 0;
+    for await (const chunk of response.body) {
+        downloadSignal.throwIfAborted();
+        size += chunk.byteLength;
+        if (size > 128 * 1024 * 1024)
+            throw new Error("RUNTIME_DOWNLOAD_FAILED: executable exceeds 128 MiB");
+        parts.push(chunk);
+    }
+    const bytes = Buffer.concat(parts);
+    verify(bytes, checksum);
+    downloadSignal.throwIfAborted();
+    await mkdir(folder, { recursive: true });
+    const temporary = join(folder, `node-${randomUUID()}.tmp`);
+    try {
+        await writeFile(temporary, bytes, { flag: "wx" });
+        signal?.throwIfAborted();
+        try {
+            await rename(temporary, executable);
+        }
+        catch (error) {
+            // A concurrent Pi session may have installed the same pinned runtime.
+            if (!(error instanceof Error &&
+                "code" in error &&
+                (error.code === "EEXIST" || error.code === "EPERM")))
+                throw error;
+            verify(await readFile(executable), checksum);
+        }
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+    return executable;
+}

package/dist/settings.d.ts

@@ -0,0 +1,85 @@
+import type { WorkerResult } from "./protocol.js";
+export declare const TOOL_PREFIX = "windows_computer_use_";
+export declare const TOOL_NAMES: string[];
+export declare const DEFAULT_SETTINGS: {
+    browserFirst: boolean;
+    browserVisible: boolean;
+    browserApp: string;
+    browserSignIn: boolean;
+    mode: string;
+    toolPreset: string;
+    enabledTools: string[];
+    indicatorEnabled: boolean;
+    cursorIndicatorEnabled: boolean;
+    remoteIndicatorVisible: boolean;
+    indicatorText: string;
+    indicatorPosition: string;
+    indicatorIdleMs: number;
+    stopShortcut: string;
+    resumeToken: number;
+    previewToken: number;
+};
+export type PersonalSettings = typeof DEFAULT_SETTINGS;
+export declare function personalSettingsPath(host?: boolean): Promise<string | undefined>;
+export declare function readPersonalSettings(host?: boolean): Promise<{
+    path: undefined;
+    exists: boolean;
+    source: string;
+    settings: PersonalSettings;
+    notices: string[];
+} | {
+    path: string;
+    exists: boolean;
+    source: string;
+    settings: PersonalSettings;
+    notices: string[];
+}>;
+export declare function allowedToolNames(settings: PersonalSettings): string[];
+export declare const managementParameters: {
+    type: string;
+    additionalProperties: boolean;
+    properties: {
+        operation: {
+            type: string;
+            enum: string[];
+            default: string;
+        };
+        names: {
+            type: string;
+            items: {
+                type: string;
+            };
+            maxItems: number;
+        };
+    };
+};
+export declare class PersonalSettingsManager {
+    private readonly available;
+    currentSettings: PersonalSettings | undefined;
+    currentFileExists: boolean;
+    currentNotices: string[];
+    currentSource: string;
+    private selection;
+    private enabled;
+    private allowed;
+    constructor(available: Map<string, {
+        description: string;
+        parameters?: unknown;
+    }>);
+    synchronize(): Promise<{
+        path: undefined;
+        exists: boolean;
+        source: string;
+        settings: PersonalSettings;
+        notices: string[];
+    } | {
+        path: string;
+        exists: boolean;
+        source: string;
+        settings: PersonalSettings;
+        notices: string[];
+    }>;
+    authorize(action: string): Promise<string | undefined>;
+    private toolList;
+    handle(action: string, args: Record<string, unknown>): Promise<WorkerResult>;
+}