@oharness/engine 0.9.2 → 0.10.0

package/dist/computer/arbiter.js

@@ -0,0 +1,128 @@
+import { ComputerError } from "./target.js";
+export class ComputerArbiter {
+    windows = new Map();
+    apps = new Map();
+    control;
+    queue = [];
+    clipboardChain = Promise.resolve();
+    leaseMs;
+    controlWaitMs;
+    now;
+    listeners = new Set();
+    constructor(opts = {}) {
+        this.leaseMs = opts.leaseMs ?? 60_000;
+        this.controlWaitMs = opts.controlWaitMs ?? 30_000;
+        this.now = opts.now ?? Date.now;
+    }
+    /** Take or refresh the lease on a window; throws `busy` when someone else holds it. */
+    claimWindow(holder, window) {
+        this.claim(this.windows, window, holder, "window");
+    }
+    /** Take or refresh the lease on an app's keyboard focus. */
+    claimApp(holder, pid) {
+        this.claim(this.apps, pid, holder, "app");
+    }
+    claim(map, key, holder, what) {
+        const now = this.now();
+        const lease = map.get(key);
+        if (lease && lease.sessionId !== holder.sessionId && lease.until > now) {
+            throw new ComputerError("busy", `This ${what} is in use by another conversation ("${lease.label}"). Work on something else, or try again in a minute.`);
+        }
+        // The foreground holder owns the whole screen while it drives it.
+        if (this.control && this.control.sessionId !== holder.sessionId) {
+            throw new ComputerError("busy", `Another conversation ("${this.control.label}") is controlling the computer right now. Try again shortly.`);
+        }
+        map.set(key, { ...holder, until: now + this.leaseMs });
+    }
+    /** The person started using this window: every lease on it lapses. */
+    yieldWindow(window) {
+        this.windows.delete(window);
+    }
+    /** Who holds foreground control, if anyone. */
+    controller() {
+        return this.control;
+    }
+    holdsControl(sessionId) {
+        return this.control?.sessionId === sessionId;
+    }
+    /**
+     * Take the real cursor and keyboard, waiting in line behind any other
+     * conversation that has them. `onWait` fires once when the wait starts, so
+     * the page can say "waiting for control".
+     */
+    async takeControl(holder, signal, onWait) {
+        if (!this.control || this.control.sessionId === holder.sessionId) {
+            this.control = holder;
+            this.changed();
+            return;
+        }
+        onWait?.(this.control);
+        await new Promise((resolve, reject) => {
+            const entry = {
+                holder,
+                resolve,
+                reject,
+                timer: setTimeout(() => {
+                    this.dequeue(entry);
+                    reject(new ComputerError("busy", `Another conversation ("${this.control?.label ?? "?"}") kept control of the computer for too long. Try again later.`));
+                }, this.controlWaitMs),
+            };
+            this.queue.push(entry);
+            signal?.addEventListener("abort", () => {
+                this.dequeue(entry);
+                reject(new ComputerError("refused", "stopped while waiting for control"));
+            }, { once: true });
+        });
+    }
+    dequeue(entry) {
+        clearTimeout(entry.timer);
+        const index = this.queue.indexOf(entry);
+        if (index >= 0)
+            this.queue.splice(index, 1);
+    }
+    releaseControl(sessionId) {
+        if (this.control?.sessionId !== sessionId)
+            return false;
+        this.control = undefined;
+        const next = this.queue.shift();
+        if (next) {
+            clearTimeout(next.timer);
+            this.control = next.holder;
+            next.resolve();
+        }
+        this.changed();
+        return true;
+    }
+    /** Release everything a conversation holds: its turn ended or its tab closed. */
+    releaseAll(sessionId) {
+        for (const [key, lease] of this.windows)
+            if (lease.sessionId === sessionId)
+                this.windows.delete(key);
+        for (const [key, lease] of this.apps)
+            if (lease.sessionId === sessionId)
+                this.apps.delete(key);
+        for (const entry of [...this.queue]) {
+            if (entry.holder.sessionId !== sessionId)
+                continue;
+            this.dequeue(entry);
+            entry.reject(new ComputerError("refused", "the conversation ended"));
+        }
+        this.releaseControl(sessionId);
+    }
+    /** Run `fn` with the clipboard to itself: save, use, restore happen as one. */
+    withClipboard(fn) {
+        const run = this.clipboardChain.then(fn, fn);
+        this.clipboardChain = run.catch(() => undefined);
+        return run;
+    }
+    /** Told when foreground control changes hands, for the overlay and the page. */
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    changed() {
+        for (const listener of this.listeners)
+            listener();
+    }
+}
+//# sourceMappingURL=arbiter.js.map

package/dist/computer/arbiter.js.map

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

package/dist/computer/cua-driver.d.ts

@@ -0,0 +1,115 @@
+import type { Logger } from "../util/logger.ts";
+import type { AppInfo, AxAction, AxNode, ComputerInputEvent, ComputerPermissions, ComputerTarget, HelperInfo, Shot, WindowInfo } from "./target.ts";
+/**
+ * A `ComputerTarget` backed by Cua Driver (github.com/trycua/cua, MIT).
+ *
+ * Cua Driver is the platform layer: ScreenCaptureKit and AX with SkyLight
+ * background input on macOS; UIA, MSAA, PostMessage and WGC on Windows. We
+ * drive its MCP server over stdio and keep everything above it — the tools
+ * the model sees, per-app approval, tiers, the arbiter — our own. The model
+ * never talks to Cua Driver directly: only this adapter does, and it calls a
+ * fixed handful of its 58 tools.
+ *
+ * How it is run matters:
+ *
+ * - Embedded (`CUA_DRIVER_EMBEDDED=1`) and spawned by the app itself, so
+ *   macOS charges its TCC requests to OHarness and the person grants
+ *   OHarness, not a second app. The driver never prompts in this mode; the
+ *   host asks (see `requestPermissions`).
+ * - Telemetry and the update check off. Both default on, embedded or not.
+ * - `mcp --direct`: no daemon and no Cua cursor. The desktop app draws its
+ *   own, per conversation, and keeps it out of captures.
+ *
+ * Coordinates: Cua takes pointer x/y in pixels of the window screenshot it
+ * last returned. The engine works in screen units (each screenshot's frame
+ * says where its pixels sit), so pointer events are mapped back through the
+ * last screenshot of that window here. Element frames already come in screen
+ * units.
+ */
+export interface CuaDriverOptions {
+    /** The cua-driver executable. */
+    path: string;
+    /** The host app's bundle id, for Cua's own identity checks. */
+    hostBundleId?: string;
+    /** Where the driver may keep state; telemetry is off either way. */
+    stateDir?: string;
+    /**
+     * The Rego policy the driver enforces on every call: only the tools this
+     * adapter uses, and none that write files (desktop/computer-helper/cua/policy.rego).
+     */
+    policyFile?: string;
+    logger?: Logger;
+    /**
+     * Ask the OS for Screen Recording or Accessibility. Embedded, the driver
+     * never prompts: the host app has to, as itself.
+     */
+    requestPermissions?: (grant?: keyof ComputerPermissions) => Promise<void>;
+    /** Milliseconds since the person's last real input, from the host. */
+    idle?: () => Promise<number>;
+}
+export declare class CuaDriverTarget implements ComputerTarget {
+    private readonly client;
+    private readonly opts;
+    private readonly pids;
+    private readonly shots;
+    private readonly refs;
+    /** The field typing goes to, per window, set by `axAction focus`. */
+    private readonly targets;
+    private appIds;
+    private version;
+    private constructor();
+    static start(opts: CuaDriverOptions): Promise<CuaDriverTarget>;
+    private call;
+    private refusal;
+    private pidOf;
+    /** Screen point → pixels of the last screenshot of this window, taking one if needed. */
+    private toWindowPixels;
+    info(): Promise<HelperInfo>;
+    permissions(): Promise<ComputerPermissions>;
+    requestPermissions(grant?: keyof ComputerPermissions): Promise<void>;
+    apps(): Promise<AppInfo[]>;
+    windows(opts?: {
+        pid?: number;
+    }): Promise<WindowInfo[]>;
+    screenshot(opts: {
+        window?: string;
+        display?: string;
+        maxWidth?: number;
+    }): Promise<Shot>;
+    axTree(opts: {
+        window: string;
+        depth?: number;
+        maxNodes?: number;
+    }): Promise<{
+        nodes: AxNode[];
+        truncated: boolean;
+    }>;
+    private refInfo;
+    /**
+     * Run an action on a ref, re-finding the element once if its token went
+     * stale. Any snapshot of a window — a screenshot included — supersedes the
+     * tokens of the one before, and the model reasonably reads the tree, looks
+     * at the window, then clicks.
+     */
+    private onRef;
+    axAction(ref: string, action: AxAction, value?: string): Promise<void>;
+    input(event: ComputerInputEvent, opts: {
+        window?: string;
+        foreground: boolean;
+    }): Promise<void>;
+    invokeMenu(window: string, path: string[]): Promise<void>;
+    open(app: string): Promise<{
+        pid?: number;
+    }>;
+    frontmost(): Promise<{
+        pid: number;
+        appId: string;
+        window?: string;
+    }>;
+    activate(pid: number): Promise<void>;
+    idle(): Promise<number>;
+    pointVisible(window: string, x: number, y: number): Promise<boolean>;
+    clipboardRead(): Promise<string>;
+    clipboardWrite(text: string): Promise<void>;
+    close(): Promise<void>;
+}