humanish 0.104.3 → 0.106.0

package/dist/guest/bootstrap.js

@@ -0,0 +1,348 @@
+import { desktopRecordingConfigSchema, } from "../evidence/desktop-recording-types.js";
+import { validateBrowserControlIdentity, sameBrowserControlIdentity, } from "../browser-control/protocol.js";
+import { CuaExecutorError } from "../actors/computer-use/executor-error.js";
+import { createBrowserControlClient } from "../browser-control/client.js";
+import { guestMediaConfigSchema } from "./media-config.js";
+export const GUEST_BOOTSTRAP_VERSION = 1;
+export const GUEST_BOOTSTRAP_LIMITS = Object.freeze({
+    bytes: 65_536 + 1024,
+    readyBytes: 1024,
+    initialUrlBytes: 65_536,
+    admissionMs: 5000,
+    readyMs: 35_000,
+    navigationMs: 30_000,
+    paintMs: 5000,
+    connectMs: 3000,
+    port: 5251,
+});
+const refused = () => new CuaExecutorError("protocol_mismatch", "not_dispatched");
+/** Same entry authority as the local desktop's opaque app-port forward. */
+export function validateGuestInitialUrl(value) {
+    try {
+        if (typeof value !== "string")
+            throw refused();
+        const url = new URL(value);
+        if (!["http:", "https:"].includes(url.protocol) ||
+            !["localhost", "127.0.0.1"].includes(url.hostname) ||
+            url.username ||
+            url.password ||
+            !/^\d+$/.test(url.port) ||
+            Number(url.port) < 1024 ||
+            Buffer.byteLength(url.href) > GUEST_BOOTSTRAP_LIMITS.initialUrlBytes)
+            throw refused();
+        return url.href;
+    }
+    catch {
+        throw refused();
+    }
+}
+export function guestReadyTimeoutMs(initialUrl) {
+    return (GUEST_BOOTSTRAP_LIMITS.readyMs +
+        (initialUrl === undefined
+            ? 0
+            : GUEST_BOOTSTRAP_LIMITS.navigationMs + GUEST_BOOTSTRAP_LIMITS.paintMs));
+}
+function canonical(identity, ready, initialUrl, media, recording) {
+    const { generation, challenge, runtimeRevision } = validateBrowserControlIdentity(identity);
+    const fixed = { generation, challenge, runtimeRevision };
+    if (initialUrl !== undefined && (ready || validateGuestInitialUrl(initialUrl) !== initialUrl))
+        throw refused();
+    if (media !== undefined && (ready || !guestMediaConfigSchema.safeParse(media).success))
+        throw refused();
+    if (recording !== undefined &&
+        (ready || !desktopRecordingConfigSchema.safeParse(recording).success))
+        throw refused();
+    return JSON.stringify(ready
+        ? { version: 1, ready: true, identity: fixed }
+        : {
+            version: 1,
+            identity: fixed,
+            ...(initialUrl === undefined ? {} : { initialUrl }),
+            ...(media === undefined ? {} : { media: guestMediaConfigSchema.parse(media) }),
+            ...(recording === undefined
+                ? {}
+                : { recording: desktopRecordingConfigSchema.parse(recording) }),
+        });
+}
+export function encodeGuestBootstrap(identity, ready = false, initialUrl, media, recording) {
+    const bytes = Buffer.from(canonical(identity, ready, initialUrl, media, recording));
+    if (bytes.length > (ready ? GUEST_BOOTSTRAP_LIMITS.readyBytes : GUEST_BOOTSTRAP_LIMITS.bytes))
+        throw refused();
+    const frame = Buffer.alloc(4 + bytes.length);
+    frame.writeUInt32BE(bytes.length);
+    bytes.copy(frame, 4);
+    return frame;
+}
+export function parseGuestBootstrap(bytes, revision, ready = false) {
+    return parseBootstrap(bytes, revision, ready).identity;
+}
+function parseBootstrap(bytes, revision, ready) {
+    if (!bytes.length ||
+        bytes.length > (ready ? GUEST_BOOTSTRAP_LIMITS.readyBytes : GUEST_BOOTSTRAP_LIMITS.bytes) ||
+        bytes.some((byte) => byte > 127))
+        throw refused();
+    try {
+        const value = JSON.parse(bytes.toString("ascii"));
+        if (typeof value !== "object" || value === null || !("identity" in value))
+            throw refused();
+        const identity = validateBrowserControlIdentity(value.identity);
+        const initialUrl = "initialUrl" in value ? value.initialUrl : undefined;
+        const media = "media" in value ? guestMediaConfigSchema.parse(value.media) : undefined;
+        const recording = "recording" in value ? desktopRecordingConfigSchema.parse(value.recording) : undefined;
+        if (initialUrl !== undefined && typeof initialUrl !== "string")
+            throw refused();
+        if (identity.runtimeRevision !== revision ||
+            canonical(identity, ready, initialUrl, media, recording) !== bytes.toString("ascii"))
+            throw refused();
+        return {
+            identity,
+            ...(initialUrl === undefined ? {} : { initialUrl }),
+            ...(media === undefined ? {} : { media }),
+            ...(recording === undefined ? {} : { recording }),
+        };
+    }
+    catch {
+        throw refused();
+    }
+}
+/** Own the first frame and continue refusing early bytes until synchronous handoff. */
+export class GuestBootstrapReader {
+    stream;
+    revision;
+    signal;
+    ready;
+    onFailure;
+    identity;
+    initialUrl;
+    media;
+    recording;
+    resolve;
+    reject;
+    header = Buffer.alloc(4);
+    headerUsed = 0;
+    body;
+    used = 0;
+    admitted = false;
+    terminal = false;
+    timer;
+    constructor(stream, revision, signal, ready = false, onFailure = () => { }, readyTimeoutMs = GUEST_BOOTSTRAP_LIMITS.readyMs) {
+        this.stream = stream;
+        this.revision = revision;
+        this.signal = signal;
+        this.ready = ready;
+        this.onFailure = onFailure;
+        this.identity = new Promise((resolve, reject) => {
+            this.resolve = resolve;
+            this.reject = reject;
+        });
+        // A later factory rejection must not leave the admission rejection unconsumed.
+        void this.identity.catch(() => { });
+        this.timer = setTimeout(() => this.fail("deadline_exceeded"), ready ? readyTimeoutMs : GUEST_BOOTSTRAP_LIMITS.admissionMs);
+        stream.on("error", this.error);
+        stream.on("close", this.end);
+        stream.on("end", this.end);
+        stream.on("data", this.data);
+        signal.addEventListener("abort", this.abort, { once: true });
+        if (signal.aborted ||
+            stream.destroyed ||
+            stream.readableEnded ||
+            stream.writableEnded ||
+            stream.readableObjectMode ||
+            stream.writableObjectMode)
+            this.abort();
+        else
+            stream.resume();
+    }
+    data = (value) => {
+        if (this.terminal)
+            return;
+        if (!Buffer.isBuffer(value) || this.admitted) {
+            this.fail();
+            return;
+        }
+        let offset = 0;
+        if (!this.body) {
+            const count = Math.min(4 - this.headerUsed, value.length);
+            value.copy(this.header, this.headerUsed, 0, count);
+            this.headerUsed += count;
+            offset += count;
+            if (this.headerUsed < 4)
+                return;
+            const length = this.header.readUInt32BE(0);
+            if (!length ||
+                length > (this.ready ? GUEST_BOOTSTRAP_LIMITS.readyBytes : GUEST_BOOTSTRAP_LIMITS.bytes)) {
+                this.fail();
+                return;
+            }
+            this.body = Buffer.alloc(length);
+        }
+        const count = Math.min(value.length - offset, this.body.length - this.used);
+        value.copy(this.body, this.used, offset, offset + count);
+        this.used += count;
+        offset += count;
+        if (offset !== value.length) {
+            this.fail();
+            return;
+        }
+        if (this.used === this.body.length) {
+            try {
+                const parsed = parseBootstrap(this.body, this.revision, this.ready);
+                this.initialUrl = parsed.initialUrl;
+                this.media = parsed.media;
+                this.recording = parsed.recording;
+                this.admitted = true;
+                clearTimeout(this.timer);
+                this.resolve(parsed.identity);
+            }
+            catch {
+                this.fail();
+            }
+        }
+    };
+    error = () => this.fail("transport_failed");
+    end = () => this.fail("transport_failed");
+    abort = () => this.fail("session_revoked");
+    release() {
+        clearTimeout(this.timer);
+        this.stream.off("data", this.data);
+        this.stream.off("end", this.end);
+        this.stream.off("close", this.end);
+        this.signal.removeEventListener("abort", this.abort);
+        // Retain a safe listener until queued native error/close events have drained.
+        const stream = this.stream, error = this.error;
+        const off = () => {
+            stream.off("error", error);
+            stream.off("close", off);
+        };
+        stream.once("close", off);
+        if (stream.closed)
+            setImmediate(off);
+    }
+    fail(code = "protocol_mismatch") {
+        if (this.terminal)
+            return;
+        this.terminal = true;
+        this.release();
+        this.reject(new CuaExecutorError(code, "not_dispatched"));
+        this.stream.destroy();
+        this.onFailure();
+    }
+    /** Must be followed synchronously by installing the sole next stream owner. */
+    handoff() {
+        if (this.terminal ||
+            !this.admitted ||
+            this.signal.aborted ||
+            this.stream.destroyed ||
+            this.stream.readableLength !== 0)
+            throw refused();
+        this.stream.pause();
+        this.terminal = true;
+        this.release();
+    }
+    close() {
+        this.fail("session_revoked");
+    }
+}
+/** Fixed preface on an already acquired Firecracker stream; no path discovery/retry. */
+export async function connectGuestBootstrap(stream, identity, signal, initialUrl, media, recording) {
+    validateBrowserControlIdentity(identity);
+    const request = encodeGuestBootstrap(identity, false, initialUrl, media, recording);
+    await new Promise((resolve, reject) => {
+        let bytes = Buffer.alloc(0), done = false;
+        const timer = setTimeout(() => finish(new CuaExecutorError("deadline_exceeded", "not_dispatched")), GUEST_BOOTSTRAP_LIMITS.connectMs);
+        const finish = (error) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            stream.pause();
+            stream.off("data", data);
+            stream.off("end", end);
+            stream.off("close", end);
+            signal.removeEventListener("abort", abort);
+            const release = () => {
+                stream.off("error", end);
+                stream.off("close", release);
+            };
+            stream.once("close", release);
+            if (stream.closed)
+                setImmediate(release);
+            if (error) {
+                stream.destroy();
+                reject(error);
+            }
+            else
+                resolve();
+        };
+        const end = () => {
+            if (done)
+                stream.destroy();
+            finish(new CuaExecutorError("transport_failed", "not_dispatched"));
+        };
+        const abort = () => finish(new CuaExecutorError("session_revoked", "not_dispatched"));
+        const data = (chunk) => {
+            if (!Buffer.isBuffer(chunk) || bytes.length + chunk.length > 64 + 1028) {
+                finish(refused());
+                return;
+            }
+            bytes = Buffer.concat([bytes, chunk]);
+            const newline = bytes.indexOf(10);
+            if (newline < 0) {
+                if (bytes.length > 64)
+                    finish(refused());
+                return;
+            }
+            const line = bytes.subarray(0, newline + 1).toString("ascii");
+            if (newline >= 64 ||
+                bytes.subarray(0, newline + 1).some((byte) => byte > 127) ||
+                !/^OK [1-9][0-9]{0,9}\n$/.test(line) ||
+                Number(line.slice(3)) > 0xffffffff) {
+                finish(refused());
+                return;
+            }
+            const tail = bytes.subarray(newline + 1);
+            if (tail.length) {
+                stream.pause();
+                stream.unshift(tail);
+            }
+            finish();
+        };
+        stream.on("error", end);
+        stream.on("end", end);
+        stream.on("close", end);
+        stream.on("data", data);
+        signal.addEventListener("abort", abort, { once: true });
+        if (signal.aborted || stream.destroyed)
+            abort();
+        else {
+            stream.resume();
+            stream.write("CONNECT 5251\n", (error) => {
+                if (error)
+                    end();
+            });
+        }
+    });
+    const reader = new GuestBootstrapReader(stream, identity.runtimeRevision, signal, true, undefined, guestReadyTimeoutMs(initialUrl));
+    try {
+        stream.write(request, (error) => {
+            if (error)
+                reader.close();
+        });
+        const actual = await reader.identity;
+        if (!sameBrowserControlIdentity(actual, identity))
+            throw refused();
+        reader.handoff();
+    }
+    catch (error) {
+        reader.close();
+        stream.destroy();
+        throw error;
+    }
+    const client = createBrowserControlClient({
+        transport: stream,
+        identity,
+        ...(media?.microphone?.source === "speech" ? { speechEnabled: true } : {}),
+    });
+    stream.resume();
+    return client;
+}

package/dist/guest/browser-tools.d.ts

@@ -0,0 +1,8 @@
+import type { GuestDesktopTools } from "./desktop-executor.js";
+import type { GuestDesktopNativeTools } from "./desktop-native.js";
+interface BrowserTextPort extends Pick<GuestDesktopTools, "prepareText"> {
+    assertReady(signal: AbortSignal): Promise<void>;
+}
+/** Owner-only composition for a single headed Chromium page. Never an actor API. */
+export declare function createGuestBrowserTools(native: GuestDesktopNativeTools, content: BrowserTextPort): GuestDesktopTools;
+export {};

package/dist/guest/browser-tools.js

@@ -0,0 +1,72 @@
+import { BROWSER_CONTROL_LIMITS } from "../browser-control/protocol.js";
+import { CuaExecutorError, isCuaExecutorError } from "../actors/computer-use/executor-error.js";
+/** Owner-only composition for a single headed Chromium page. Never an actor API. */
+export function createGuestBrowserTools(native, content) {
+    let addressBarArmed = false;
+    let generation = 0;
+    return {
+        capture: (signal) => native.capture(signal),
+        async input(args, signal) {
+            addressBarArmed = false;
+            const inputGeneration = ++generation;
+            await native.input(args, signal);
+            if (signal.aborted || inputGeneration !== generation)
+                throw new CuaExecutorError("session_revoked", "outcome_uncertain");
+            // Positive navigation intent, not an inference from document.hasFocus().
+            addressBarArmed =
+                args.length === 3 &&
+                    args[0] === "key" &&
+                    args[1] === "--clearmodifiers" &&
+                    args[2] === "ctrl+l";
+        },
+        async prepareText(text, signal) {
+            const navigation = addressBarArmed;
+            addressBarArmed = false;
+            if (!navigation)
+                return content.prepareText(text, signal);
+            // Other browser chrome, IME composition, and Unicode omnibox text need
+            // separate qualification. Do not silently switch routes or transliterate.
+            if (!/^[\x20-\x7e]+$/.test(text) ||
+                Buffer.byteLength(text) > BROWSER_CONTROL_LIMITS.textBytes) {
+                throw new CuaExecutorError("action_rejected", "not_dispatched");
+            }
+            const preparedGeneration = generation;
+            let used = false;
+            function check() {
+                if (signal.aborted)
+                    throw new CuaExecutorError("session_revoked", "not_dispatched");
+                if (used || preparedGeneration !== generation)
+                    throw new CuaExecutorError("action_rejected", "not_dispatched");
+            }
+            check();
+            await content.assertReady(signal);
+            check();
+            return {
+                async paste() {
+                    check();
+                    await content.assertReady(signal);
+                    check();
+                    used = true;
+                    // Re-establish the explicitly requested destination immediately before
+                    // native typing; the previous page may have changed its own focus.
+                    try {
+                        await native.input(["key", "--clearmodifiers", "ctrl+l"], signal);
+                        if (signal.aborted)
+                            throw new CuaExecutorError("session_revoked", "outcome_uncertain");
+                        await content.assertReady(signal);
+                        if (signal.aborted || preparedGeneration !== generation)
+                            throw new CuaExecutorError("session_revoked", "outcome_uncertain");
+                        await native.typeAscii(text, signal);
+                    }
+                    catch (error) {
+                        // Ctrl+L itself is input. No content fallback after that dispatch.
+                        throw new CuaExecutorError(isCuaExecutorError(error) ? error.code : "execution_failed", "outcome_uncertain");
+                    }
+                },
+                async close() {
+                    used = true;
+                },
+            };
+        },
+    };
+}

package/dist/guest/chromium-text.d.ts

@@ -0,0 +1,62 @@
+import type { BrowserContext, Page } from "playwright-core";
+interface PreparedGuestChromiumText {
+    paste(): Promise<void>;
+    close(): Promise<void>;
+}
+export interface GuestChromiumText {
+    /** Owner/window readiness only: deliberately permits a focused browser toolbar. */
+    assertReady(signal: AbortSignal): Promise<void>;
+    prepareText(text: string, signal: AbortSignal): Promise<PreparedGuestChromiumText>;
+    close(): Promise<void>;
+}
+/**
+ * Text a preparation accepts: non-empty, no NUL, at most 64 KiB of UTF-8 that round-trips.
+ * Written as the negated refusal so each comparison keeps its original form.
+ */
+export declare function isAdmissibleText(text: unknown): text is string;
+/** The owned top frame's id from Page.getFrameTree, or undefined for anything else. */
+export declare function ownedFrameId(tree: {
+    frameTree?: {
+        frame?: {
+            id?: unknown;
+            parentId?: unknown;
+        };
+    };
+}): string | undefined;
+/** An isolated world's execution context id: a positive safe integer (negated refusal form). */
+export declare function isExecutionContextId(contextId: unknown): contextId is number;
+/** The fixed Runtime.evaluate parameters for one probe in the port's isolated world. */
+export declare function evaluateParams(expression: string, contextId: number): {
+    expression: string;
+    contextId: number;
+    returnByValue: boolean;
+    awaitPromise: boolean;
+    userGesture: boolean;
+    includeCommandLineAPI: boolean;
+    silent: boolean;
+};
+/** A probe passed: no exception, and a boolean true result. */
+export declare function probeAccepted(reply: {
+    exceptionDetails?: unknown;
+    result: {
+        type: string;
+        value?: unknown;
+    };
+}): boolean;
+/**
+ * A finite text port for one owner-acquired Chromium page in a one-page context.
+ * It neither selects/activates targets nor handles browser chrome, frames or
+ * dialogs. An observed dialog poisons this port; the owner must handle it and
+ * construct a new port. A dialog already open can make preparation time out.
+ *
+ * Focus checks and insertText are separate protocol calls: page code can change
+ * focus between them. This is not atomic element binding or proof an app applied
+ * text. A lost post-send acknowledgement is uncertain and terminal for this port.
+ * The owner remains responsible for browser/session teardown.
+ */
+export declare function createGuestChromiumText(options: {
+    context: BrowserContext;
+    page: Page;
+    assertFocusedWindow: (signal: AbortSignal) => Promise<void>;
+}): GuestChromiumText;
+export {};