@oharness/engine 0.9.2 → 0.10.0

package/dist/computer/target.d.ts

@@ -0,0 +1,187 @@
+/**
+ * What the computer tools need from whatever drives the machine.
+ *
+ * The engine holds no platform code. The desktop app supplies a target, which
+ * in practice is a native helper spoken to over stdio (`helper-client.ts`): a
+ * Swift binary on macOS and a Rust one on Windows, both answering the same
+ * protocol. Tests supply a fake.
+ *
+ * Units: every frame and point here is in the helper's screen coordinates —
+ * points on macOS, physical pixels on a per-monitor-DPI-aware Windows process.
+ * The engine never needs to know which: it maps a coordinate in a screenshot
+ * back through that screenshot's own `frame`, and the helper interprets the
+ * result in the unit it reported the frame in.
+ */
+export interface Rect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface AppInfo {
+    name: string;
+    /** Bundle id on macOS (`com.apple.Notes`), lower-cased exe name on Windows (`notepad.exe`). */
+    id: string;
+    pid: number;
+    active: boolean;
+}
+export interface WindowInfo {
+    /** Opaque, stable for the window's lifetime. */
+    id: string;
+    pid: number;
+    app: string;
+    appId: string;
+    title?: string;
+    frame: Rect;
+    minimized?: boolean;
+    /** False for a window on another Space or desktop: still usable, just not visible. */
+    onScreen?: boolean;
+    focused?: boolean;
+}
+export interface Shot {
+    /** Base64 image. */
+    data: string;
+    /** JPEG unless said otherwise; Cua Driver returns PNG. */
+    mimeType?: string;
+    /** Image size in pixels. */
+    width: number;
+    height: number;
+    /** Where the image sits on screen, in screen units. */
+    frame: Rect;
+}
+export interface AxNode {
+    /** Opaque, `w<window>.<n>`; valid until the window is read again. */
+    ref: string;
+    role: string;
+    name?: string;
+    value?: string;
+    frame?: Rect;
+    actions?: string[];
+    depth: number;
+    /** A password field: its value is never returned and typing into it is redacted. */
+    secure?: boolean;
+    disabled?: boolean;
+}
+export type AxAction = "press" | "focus" | "setValue" | "expand" | "collapse" | "scrollIntoView" | "showMenu";
+export type MouseButton = "left" | "right" | "middle";
+export type ComputerInputEvent = {
+    type: "click";
+    x: number;
+    y: number;
+    button?: MouseButton;
+    count?: number;
+    modifiers?: string[];
+} | {
+    type: "move";
+    x: number;
+    y: number;
+} | {
+    type: "scroll";
+    x: number;
+    y: number;
+    dx: number;
+    dy: number;
+} | {
+    type: "drag";
+    from: {
+        x: number;
+        y: number;
+    };
+    to: {
+        x: number;
+        y: number;
+    };
+    modifiers?: string[];
+} | {
+    type: "key";
+    key: string;
+    modifiers?: string[];
+} | {
+    type: "text";
+    text: string;
+};
+export interface ComputerPermissions {
+    /** Screenshots. Always true on Windows. */
+    screen: boolean;
+    /** Reading and acting on other apps. Always true on Windows. */
+    accessibility: boolean;
+}
+export interface HelperInfo {
+    platform: "darwin" | "win32";
+    version: string;
+    /** Whether pointer events can reach a window without raising it. */
+    background: boolean;
+}
+/**
+ * A refusal the model and the page can act on, rather than a stack trace.
+ *
+ * `code` is part of the helper protocol: both helpers raise the same codes.
+ */
+export declare class ComputerError extends Error {
+    readonly code: ComputerErrorCode;
+    readonly grant?: keyof ComputerPermissions;
+    constructor(code: ComputerErrorCode, message: string, grant?: keyof ComputerPermissions);
+}
+export type ComputerErrorCode = 
+/** An OS grant is missing (macOS TCC). */
+"permission"
+/** The action needs the real cursor/keyboard: call computer_take_control. */
+ | "needs_foreground"
+/** The window belongs to an elevated (administrator) process on Windows. */
+ | "elevated"
+/** A UAC prompt / secure desktop is up, or the screen is locked. */
+ | "secure_desktop" | "not_found" | "stale_ref" | "unsupported"
+/** Another conversation, or the person, holds what this call needs. */
+ | "busy" | "refused" | "failed";
+export interface ComputerTarget {
+    info(): Promise<HelperInfo>;
+    permissions(): Promise<ComputerPermissions>;
+    /** Show the OS prompt, or open the settings pane, for what is missing. */
+    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;
+    }>;
+    axAction(ref: string, action: AxAction, value?: string): Promise<void>;
+    /**
+     * Choose an item from the app's menu bar by its path — ["File", "New Note"]
+     * — through accessibility, in the background. Optional: a layer without it
+     * leaves the agent to the keyboard shortcut.
+     */
+    invokeMenu?(window: string, path: string[]): Promise<void>;
+    input(event: ComputerInputEvent, opts: {
+        window?: string;
+        foreground: boolean;
+    }): Promise<void>;
+    open(app: string): Promise<{
+        pid?: number;
+    }>;
+    frontmost(): Promise<{
+        pid: number;
+        appId: string;
+        window?: string;
+    }>;
+    /** Bring an app to the front; used to hand focus back after a takeover. */
+    activate(pid: number): Promise<void>;
+    /** Milliseconds since the person's last real (not injected) input event. */
+    idle(): Promise<number>;
+    /** Whether a screen point inside `window` is actually visible, not covered. */
+    pointVisible(window: string, x: number, y: number): Promise<boolean>;
+    clipboardRead(): Promise<string>;
+    clipboardWrite(text: string): Promise<void>;
+    close(): Promise<void>;
+}
+export type ComputerTargetFactory = () => Promise<ComputerTarget>;

package/dist/computer/target.js

@@ -0,0 +1,31 @@
+/**
+ * What the computer tools need from whatever drives the machine.
+ *
+ * The engine holds no platform code. The desktop app supplies a target, which
+ * in practice is a native helper spoken to over stdio (`helper-client.ts`): a
+ * Swift binary on macOS and a Rust one on Windows, both answering the same
+ * protocol. Tests supply a fake.
+ *
+ * Units: every frame and point here is in the helper's screen coordinates —
+ * points on macOS, physical pixels on a per-monitor-DPI-aware Windows process.
+ * The engine never needs to know which: it maps a coordinate in a screenshot
+ * back through that screenshot's own `frame`, and the helper interprets the
+ * result in the unit it reported the frame in.
+ */
+/**
+ * A refusal the model and the page can act on, rather than a stack trace.
+ *
+ * `code` is part of the helper protocol: both helpers raise the same codes.
+ */
+export class ComputerError extends Error {
+    code;
+    grant;
+    constructor(code, message, grant) {
+        super(message);
+        this.name = "ComputerError";
+        this.code = code;
+        if (grant)
+            this.grant = grant;
+    }
+}
+//# sourceMappingURL=target.js.map

package/dist/computer/target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"target.js","sourceRoot":"","sources":["../../src/computer/target.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAmFH;;;;GAIG;AACH,MAAM,OAAO,aAAc,SAAQ,KAAK;IAC7B,IAAI,CAAoB;IACxB,KAAK,CAA6B;IAE3C,YAAY,IAAuB,EAAE,OAAe,EAAE,KAAiC;QACrF,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,KAAK;YAAE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IAChC,CAAC;CACF"}

package/dist/computer/tools.d.ts

@@ -0,0 +1,8 @@
+import type { Tool } from "../tools/types.ts";
+import type { ComputerUseSession } from "./session.ts";
+export declare function createComputerTools(session: ComputerUseSession): Tool[];
+/** `mod+shift+s` → key "s" with the platform's command key and shift. */
+export declare function parseChord(chord: string, platform: "darwin" | "win32"): {
+    key: string;
+    modifiers: string[];
+};