@allternit/computer-driver 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,45 @@
-# Temporary Holding Version
+# @allternit/computer-driver
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Drive an Allternit hosted computer (`/v1/computers`) from Claude, OpenAI computer use, or Gemini computer use. Needs a project key with the `computers` scope and the project's hosted driver turned on.
+
+```ts
+import { AllternitComputers } from "@allternit/computer-driver"
+const client = new AllternitComputers({ apiKey: process.env.ALLTERNIT_API_KEY })
+const computer = await client.create({ name: "agent-1" })
+```
+
+## Claude (`computer_toolset_20260801` / `browser_toolset_20260801`)
+
+Requires `@anthropic-ai/sdk` >= 0.132.0 (optional peer).
+
+```ts
+import { AllternitComputerToolset } from "@allternit/computer-driver/anthropic"
+const toolset = new AllternitComputerToolset({
+  client, computerId: computer.id,
+  onApproval: async (approval) => askAPerson(approval), // server-held risky calls
+})
+// pass `toolset` to client.beta.messages.toolRunner({ tools: [toolset], ... })
+```
+
+Every member runs on the server through `POST /v1/computers/{id}/toolset`. When the server holds a call (409 `approval_required`), `onApproval` decides: `true` approves it and resends with the grant, `false` returns the held result to the model as an error. The SDK's own `confirm` option still runs first. Approving with an API key needs the project's `approval_mode` set to `api_key`.
+
+## OpenAI computer use
+
+```ts
+import { runOpenAIAction } from "@allternit/computer-driver"
+const { output } = await runOpenAIAction({ client, computerId, display: { width: 1280, height: 800 } }, call.call_id, call.action)
+// push `output` into the next responses.create input
+```
+
+## Gemini computer use
+
+```ts
+import { runGeminiCall } from "@allternit/computer-driver"
+const { functionResponse, inlineData } = await runGeminiCall({ client, computerId }, part.functionCall)
+```
+
+Gemini's 0–999 coordinates are sent as `coordinate_space: "normalized_1000"`; the server scales them.
+
+The OpenAI and Gemini adapters let `ApprovalRequiredError` propagate; catch it, call `client.approve()`, and resend the action.
+
+Errors: `ApprovalRequiredError` (409, carries `approval` and `result`) and `AllternitApiError` (everything else, with `status`, `code`, `type`).

package/dist/anthropic.d.ts

@@ -0,0 +1,25 @@
+import { BetaAbstractBrowserToolset20260801, BetaAbstractComputerToolset20260801, type BetaBrowserMemberResult, type BetaBrowserToolsetOptions, type BetaComputerMemberResult, type BetaComputerToolsetOptions, type BetaToolsetCallContext } from "@anthropic-ai/sdk/helpers/beta/toolsets";
+import { type AllternitComputers, type Approval } from "./client.ts";
+export interface DriverOptions {
+    client: AllternitComputers;
+    computerId: string;
+    /** Called when the server holds a call for approval. true → approve() and resend with the grant. */
+    onApproval?: (approval: Approval) => Promise<boolean>;
+    /** run_id / turn_id / call_index for this call, if your loop tracks them. */
+    callIds?: (ctx: BetaToolsetCallContext, member: string) => {
+        run_id?: string;
+        turn_id?: string;
+        call_index?: number;
+    };
+    browserSessionId?: string;
+}
+export declare class AllternitComputerToolset extends BetaAbstractComputerToolset20260801 {
+    #private;
+    constructor(o: DriverOptions & BetaComputerToolsetOptions);
+    protected execute(ctx: BetaToolsetCallContext, name: string, input: unknown): Promise<BetaComputerMemberResult>;
+}
+export declare class AllternitBrowserToolset extends BetaAbstractBrowserToolset20260801 {
+    #private;
+    constructor(o: DriverOptions & Omit<BetaBrowserToolsetOptions, "browserState"> & Partial<Pick<BetaBrowserToolsetOptions, "browserState">>);
+    protected execute(ctx: BetaToolsetCallContext, name: string, input: unknown): Promise<BetaBrowserMemberResult>;
+}

package/dist/anthropic.js

@@ -0,0 +1,130 @@
+// Anthropic toolset drivers: subclasses of the SDK's abstract computer and browser
+// toolsets (computer_toolset_20260801 / browser_toolset_20260801) that run every
+// member on an Allternit hosted computer via POST /v1/computers/{id}/toolset.
+import { BetaAbstractBrowserToolset20260801, BetaAbstractComputerToolset20260801, ToolError, } from "@anthropic-ai/sdk/helpers/beta/toolsets";
+import { ApprovalRequiredError, resultImage, resultText, } from "./client.js";
+/**
+ * Default SDK `confirm`: let the call through. The Allternit server is the gate: it applies the
+ * project's member policy and holds risky calls with a 409, which `onApproval` answers. Pass your
+ * own `confirm` to also prompt locally before the call leaves the process.
+ */
+const serverDecides = () => true;
+async function callMember(o, toolset, ctx, member, input) {
+    const call = {
+        toolset,
+        member,
+        input: (input ?? {}),
+        // The SDK only calls members its toolset config turned on, which is the
+        // opt-in the executor asks for on off-by-default members.
+        enable: [member],
+        ...(o.callIds?.(ctx, member) ?? {}),
+        ...(o.browserSessionId ? { browser_session_id: o.browserSessionId } : {}),
+    };
+    let res;
+    try {
+        res = await o.client.toolset(o.computerId, call);
+    }
+    catch (e) {
+        if (!(e instanceof ApprovalRequiredError))
+            throw e;
+        if (!o.onApproval || !(await o.onApproval(e.approval)))
+            res = e.result;
+        else {
+            await o.client.approve(o.computerId, e.approval.id);
+            res = await o.client.toolset(o.computerId, { ...call, approval_grant: e.approval.id });
+        }
+    }
+    if (res.is_error)
+        throw new ToolError(toAnthropicBlocks(res));
+    return res;
+}
+function toAnthropicBlocks(r) {
+    const blocks = r.content.map((b) => b.type === "text"
+        ? { type: "text", text: b.text }
+        : { type: "image", source: { type: "base64", media_type: b.media_type, data: b.data } });
+    return blocks.length ? blocks : [{ type: "text", text: "The action failed." }];
+}
+function shot(r) {
+    const img = resultImage(r);
+    if (!img)
+        throw new ToolError("The computer returned no screenshot.");
+    return { data: img.data, mediaType: img.media_type };
+}
+function textOrVoid(r) {
+    const t = resultText(r);
+    return t ? t : undefined;
+}
+function jsonOf(r) {
+    try {
+        return JSON.parse(resultText(r));
+    }
+    catch {
+        return undefined;
+    }
+}
+export class AllternitComputerToolset extends BetaAbstractComputerToolset20260801 {
+    #o;
+    constructor(o) {
+        const { client: _c, computerId: _i, onApproval: _a, callIds: _d, browserSessionId: _b, ...sdk } = o;
+        super({ ...sdk, confirm: sdk.confirm ?? serverDecides });
+        this.#o = o;
+    }
+    async execute(ctx, name, input) {
+        const r = await callMember(this.#o, "computer", ctx, name, input);
+        if (name === "screenshot" || name === "zoom")
+            return shot(r);
+        if (name === "cursor_position") {
+            const j = jsonOf(r);
+            if (j && typeof j.x === "number")
+                return { x: j.x, y: j.y };
+            const m = /(-?\d+)\D+(-?\d+)/.exec(resultText(r));
+            if (!m)
+                throw new ToolError("The computer returned no cursor position.");
+            return { x: Number(m[1]), y: Number(m[2]) };
+        }
+        return textOrVoid(r);
+    }
+}
+export class AllternitBrowserToolset extends BetaAbstractBrowserToolset20260801 {
+    #o;
+    #state;
+    constructor(o) {
+        const { client: _c, computerId: _i, onApproval: _a, callIds: _d, browserSessionId: _b, ...sdk } = o;
+        const self = {};
+        super({ ...sdk, confirm: sdk.confirm ?? serverDecides, browserState: sdk.browserState ?? ((ctx) => self.t.#currentState(ctx)) });
+        this.#o = o;
+        self.t = this;
+    }
+    async #currentState(ctx) {
+        if (this.#state)
+            return this.#state;
+        const r = await callMember(this.#o, "browser", ctx, "list_tabs", {});
+        return (this.#state = r.browser_state ?? { tabs: jsonOf(r) ?? [] });
+    }
+    async execute(ctx, name, input) {
+        const r = await callMember(this.#o, "browser", ctx, name, input);
+        if (r.browser_state)
+            this.#state = r.browser_state;
+        if (name === "screenshot" || name === "zoom")
+            return shot(r);
+        const j = jsonOf(r);
+        const tabs = this.#state?.tabs ?? [];
+        switch (name) {
+            case "navigate":
+                return j?.url ? j : { url: tabs[0]?.url ?? String(input?.url ?? "") };
+            case "list_tabs":
+                return Array.isArray(j) ? j : tabs;
+            case "new_tab":
+            case "switch_tab":
+                if (j?.tab_id)
+                    return j;
+                if (tabs[0])
+                    return tabs[0];
+                throw new ToolError("The browser returned no tab.");
+            case "close_tab":
+                return undefined;
+            default:
+                return textOrVoid(r);
+        }
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,137 @@
+export declare const DEFAULT_BASE_URL = "https://api.allternit.com";
+export type ToolsetName = "computer" | "browser";
+export type CoordinateSpace = "pixels" | "normalized_1000";
+export type ComputerStatus = "provisioning" | "running" | "stopped" | "starting" | "stopping" | "error" | "deleted";
+export interface Computer {
+    id: string;
+    object: "computer";
+    name: string | null;
+    status: ComputerStatus;
+    account_id: string | null;
+    key_id: string;
+    created_at: string;
+    started_at: string | null;
+    metadata: Record<string, unknown>;
+}
+export interface Page<T> {
+    data: T[];
+    has_more: boolean;
+    next_cursor: string | null;
+}
+export type ContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    media_type: string;
+    data: string;
+};
+export interface Screen {
+    width: number;
+    height: number;
+    scale: number;
+    frame_width: number;
+    frame_height: number;
+}
+export interface ToolsetResult {
+    is_error: boolean;
+    content: ContentBlock[];
+    browser_state?: unknown;
+    screen?: Screen;
+    error?: unknown;
+}
+export interface ToolsetCall {
+    toolset: ToolsetName;
+    member: string;
+    input?: Record<string, unknown>;
+    run_id?: string;
+    turn_id?: string;
+    call_index?: number;
+    model_frame?: {
+        width: number;
+        height: number;
+    };
+    coordinate_space?: CoordinateSpace;
+    approval_grant?: string;
+    browser_session_id?: string;
+    /** Off-by-default members (file_upload, read_console, read_network, javascript_exec) to allow for this call. */
+    enable?: string[];
+}
+export interface Approval {
+    id: string;
+    action_hash: string;
+    member: string;
+    toolset: ToolsetName;
+    risk: string;
+    confirmation_class: string;
+    approve_url: string;
+}
+export interface ComputerEvent {
+    id: string;
+    type: "computer.action";
+    ts: string;
+    data: Record<string, unknown>;
+}
+export interface ApiErrorBody {
+    type: string;
+    code: string;
+    message: string;
+    param: string | null;
+}
+export declare class AllternitApiError extends Error {
+    readonly status: number;
+    readonly type: string;
+    readonly code: string;
+    readonly param: string | null;
+    readonly body: unknown;
+    constructor(status: number, err: Partial<ApiErrorBody>, body: unknown);
+}
+/** 409 approval_required: the call was held until someone approves it. */
+export declare class ApprovalRequiredError extends AllternitApiError {
+    readonly approval: Approval;
+    readonly result: ToolsetResult;
+    constructor(err: Partial<ApiErrorBody>, approval: Approval, result: ToolsetResult, body: unknown);
+}
+export interface ClientOptions {
+    /** Project key (alt_live_… / alt_test_…). Defaults to ALLTERNIT_API_KEY. */
+    apiKey?: string;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+}
+export declare class AllternitComputers {
+    #private;
+    readonly baseUrl: string;
+    constructor(opts?: ClientOptions);
+    create(body?: {
+        name?: string;
+        account_id?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<Computer>;
+    list(q?: {
+        limit?: number;
+        after?: string;
+    }): Promise<Page<Computer>>;
+    get(id: string): Promise<Computer>;
+    start(id: string): Promise<Computer>;
+    stop(id: string): Promise<Computer>;
+    delete(id: string): Promise<Computer>;
+    /** Run one toolset member. Action failures resolve with is_error:true; a held call throws ApprovalRequiredError. */
+    toolset(id: string, call: ToolsetCall): Promise<ToolsetResult>;
+    schema(id: string, toolset?: ToolsetName): Promise<Record<string, unknown>>;
+    events(id: string, q?: {
+        after?: string;
+        limit?: number;
+    }): Promise<Page<ComputerEvent>>;
+    approve(id: string, approvalId: string): Promise<{
+        approval_id: string;
+        approved: true;
+        approval_grant: string;
+    }>;
+}
+/** Text of a result, joined. */
+export declare function resultText(r: ToolsetResult): string;
+/** First image of a result, if any. */
+export declare function resultImage(r: ToolsetResult): {
+    media_type: string;
+    data: string;
+} | undefined;

package/dist/client.js

@@ -0,0 +1,118 @@
+// Plain client for the Allternit hosted computer API (/v1/computers).
+// Standard fetch only; every adapter in this package goes through it.
+export const DEFAULT_BASE_URL = "https://api.allternit.com";
+export class AllternitApiError extends Error {
+    status;
+    type;
+    code;
+    param;
+    body;
+    constructor(status, err, body) {
+        super(err.message ?? `Allternit API error ${status}`);
+        this.name = "AllternitApiError";
+        this.status = status;
+        this.type = err.type ?? "api_error";
+        this.code = err.code ?? "unknown";
+        this.param = err.param ?? null;
+        this.body = body;
+    }
+}
+/** 409 approval_required: the call was held until someone approves it. */
+export class ApprovalRequiredError extends AllternitApiError {
+    approval;
+    result;
+    constructor(err, approval, result, body) {
+        super(409, err, body);
+        this.name = "ApprovalRequiredError";
+        this.approval = approval;
+        this.result = result;
+    }
+}
+export class AllternitComputers {
+    baseUrl;
+    #apiKey;
+    #fetch;
+    constructor(opts = {}) {
+        const env = globalThis.process?.env;
+        const key = opts.apiKey ?? env?.ALLTERNIT_API_KEY;
+        if (!key)
+            throw new Error("AllternitComputers: apiKey is required (or set ALLTERNIT_API_KEY).");
+        this.#apiKey = key;
+        this.baseUrl = (opts.baseUrl ?? env?.ALLTERNIT_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.#fetch = opts.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    create(body = {}) {
+        return this.#req("POST", "/v1/computers", body);
+    }
+    list(q = {}) {
+        return this.#req("GET", `/v1/computers${qs(q)}`);
+    }
+    get(id) {
+        return this.#req("GET", `/v1/computers/${enc(id)}`);
+    }
+    start(id) {
+        return this.#req("POST", `/v1/computers/${enc(id)}/start`, {});
+    }
+    stop(id) {
+        return this.#req("POST", `/v1/computers/${enc(id)}/stop`, {});
+    }
+    delete(id) {
+        return this.#req("DELETE", `/v1/computers/${enc(id)}`);
+    }
+    /** Run one toolset member. Action failures resolve with is_error:true; a held call throws ApprovalRequiredError. */
+    toolset(id, call) {
+        return this.#req("POST", `/v1/computers/${enc(id)}/toolset`, call);
+    }
+    schema(id, toolset = "computer") {
+        return this.#req("GET", `/v1/computers/${enc(id)}/toolset/schema${qs({ toolset })}`);
+    }
+    events(id, q = {}) {
+        return this.#req("GET", `/v1/computers/${enc(id)}/events${qs(q)}`);
+    }
+    approve(id, approvalId) {
+        return this.#req("POST", `/v1/computers/${enc(id)}/approvals/${enc(approvalId)}`, {});
+    }
+    async #req(method, path, body) {
+        const headers = { Authorization: `Bearer ${this.#apiKey}`, Accept: "application/json" };
+        if (body !== undefined)
+            headers["Content-Type"] = "application/json";
+        if (method === "POST")
+            headers["Idempotency-Key"] = crypto.randomUUID();
+        const res = await this.#fetch(this.baseUrl + path, {
+            method,
+            headers,
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        const text = await res.text();
+        let json = undefined;
+        try {
+            json = text ? JSON.parse(text) : undefined;
+        }
+        catch {
+            json = { error: { message: text } };
+        }
+        if (res.ok)
+            return json;
+        const err = json?.error ?? {};
+        if (res.status === 409 && err.code === "approval_required" && json?.approval) {
+            throw new ApprovalRequiredError(err, json.approval, json.result ?? { is_error: true, content: [] }, json);
+        }
+        throw new AllternitApiError(res.status, err, json);
+    }
+}
+/** Text of a result, joined. */
+export function resultText(r) {
+    return r.content.flatMap((b) => (b.type === "text" ? [b.text] : [])).join("\n");
+}
+/** First image of a result, if any. */
+export function resultImage(r) {
+    const img = r.content.find((b) => b.type === "image");
+    return img && img.type === "image" ? { media_type: img.media_type, data: img.data } : undefined;
+}
+function enc(s) {
+    return encodeURIComponent(s);
+}
+function qs(q) {
+    const p = Object.entries(q).filter(([, v]) => v !== undefined && v !== "");
+    return p.length ? "?" + new URLSearchParams(p.map(([k, v]) => [k, String(v)])).toString() : "";
+}

package/dist/gemini.d.ts

@@ -0,0 +1,32 @@
+import { type AllternitComputers, type ToolsetCall, type ToolsetResult } from "./client.ts";
+export interface GeminiFunctionCall {
+    name: string;
+    args?: Record<string, unknown>;
+}
+export interface GeminiAdapterOptions {
+    client: AllternitComputers;
+    computerId: string;
+    /** URL used by the `search` function. Default https://www.google.com. */
+    searchUrl?: string;
+}
+type Step = Pick<ToolsetCall, "member" | "input">;
+/** "Control+Shift+T" → "ctrl+shift+t". */
+export declare function geminiKeys(keys: string): string;
+/** Contract calls for one Gemini computer_use function call, in order. */
+export declare function geminiToCalls(fc: GeminiFunctionCall, searchUrl?: string): Step[];
+export interface GeminiStepResult {
+    /** A `functionResponse` part for the next turn. */
+    functionResponse: {
+        name: string;
+        response: Record<string, unknown>;
+    };
+    /** The screenshot after the action, as an `inlineData` part. */
+    inlineData: {
+        mimeType: string;
+        data: string;
+    };
+    error?: ToolsetResult;
+}
+/** Run one Gemini function call and return the parts Gemini expects back. */
+export declare function runGeminiCall(o: GeminiAdapterOptions, fc: GeminiFunctionCall): Promise<GeminiStepResult>;
+export {};

package/dist/gemini.js

@@ -0,0 +1,81 @@
+// Gemini computer_use adapter: runs one predefined function call on an Allternit
+// hosted computer. Gemini coordinates are 0–999 normalized, so every call is sent
+// with coordinate_space "normalized_1000" and the server scales to the screen.
+import { resultImage } from "./client.js";
+const pt = (x, y) => [Math.round(Number(x)), Math.round(Number(y))];
+const key = (text) => ({ member: "key", input: { text } });
+const typed = (text) => ({ member: "type", input: { text } });
+const goTo = (url) => [key("ctrl+l"), typed(url), key("Return")];
+/** "Control+Shift+T" → "ctrl+shift+t". */
+export function geminiKeys(keys) {
+    const map = { control: "ctrl", meta: "super", command: "super", enter: "Return", escape: "Escape", backspace: "BackSpace", tab: "Tab", delete: "Delete" };
+    return keys.split("+").map((k) => k.trim()).map((k) => map[k.toLowerCase()] ?? (k.length === 1 ? k.toLowerCase() : k)).join("+");
+}
+/** Contract calls for one Gemini computer_use function call, in order. */
+export function geminiToCalls(fc, searchUrl = "https://www.google.com") {
+    const a = fc.args ?? {};
+    const dir = String(a.direction ?? "down");
+    switch (fc.name) {
+        case "open_web_browser":
+            return [];
+        case "wait_5_seconds":
+            return [{ member: "wait", input: { duration: 5 } }];
+        case "go_back":
+            return [key("alt+Left")];
+        case "go_forward":
+            return [key("alt+Right")];
+        case "search":
+            return goTo(searchUrl);
+        case "navigate":
+            return goTo(String(a.url ?? ""));
+        case "click_at":
+            return [{ member: "left_click", input: { coordinate: pt(a.x, a.y) } }];
+        case "hover_at":
+            return [{ member: "mouse_move", input: { coordinate: pt(a.x, a.y) } }];
+        case "type_text_at": {
+            const steps = [{ member: "left_click", input: { coordinate: pt(a.x, a.y) } }];
+            if (a.clear_before_typing !== false)
+                steps.push(key("ctrl+a"), key("BackSpace"));
+            steps.push(typed(String(a.text ?? "")));
+            if (a.press_enter !== false)
+                steps.push(key("Return"));
+            return steps;
+        }
+        case "key_combination":
+            return [key(geminiKeys(String(a.keys ?? "")))];
+        case "scroll_document":
+            return [{ member: "scroll", input: { coordinate: [500, 500], scroll_direction: dir, scroll_amount: 5 } }];
+        case "scroll_at": {
+            const amount = Math.max(1, Math.round(Number(a.magnitude ?? 800) / 160));
+            return [{ member: "scroll", input: { coordinate: pt(a.x, a.y), scroll_direction: dir, scroll_amount: amount } }];
+        }
+        case "drag_and_drop":
+            return [{ member: "left_click_drag", input: { start_coordinate: pt(a.x, a.y), coordinate: pt(a.destination_x, a.destination_y) } }];
+        default:
+            throw new Error(`Unsupported Gemini computer_use function: ${fc.name}`);
+    }
+}
+/** Run one Gemini function call and return the parts Gemini expects back. */
+export async function runGeminiCall(o, fc) {
+    const base = { toolset: "computer", coordinate_space: "normalized_1000" };
+    let error;
+    for (const step of geminiToCalls(fc, o.searchUrl)) {
+        const r = await o.client.toolset(o.computerId, { ...base, ...step });
+        if (r.is_error) {
+            error = r;
+            break;
+        }
+    }
+    const s = await o.client.toolset(o.computerId, { ...base, member: "screenshot", input: {} });
+    const img = resultImage(s);
+    if (!img)
+        throw new Error("Allternit computer returned no screenshot.");
+    const response = { url: "" };
+    if (error)
+        response.error = error.content.flatMap((b) => (b.type === "text" ? [b.text] : [])).join("\n");
+    return {
+        functionResponse: { name: fc.name, response },
+        inlineData: { mimeType: img.media_type, data: img.data },
+        ...(error ? { error } : {}),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./client.ts";
+export * from "./openai.ts";
+export * from "./gemini.ts";

package/dist/index.js

@@ -0,0 +1,6 @@
+// @allternit/computer-driver: drive Allternit hosted computers from any model loop.
+// The Anthropic toolsets live on the "@allternit/computer-driver/anthropic" subpath
+// so this entry never loads the optional @anthropic-ai/sdk peer.
+export * from "./client.js";
+export * from "./openai.js";
+export * from "./gemini.js";

package/dist/openai.d.ts

@@ -0,0 +1,70 @@
+import { type AllternitComputers, type ToolsetCall, type ToolsetResult } from "./client.ts";
+type Pt = {
+    x: number;
+    y: number;
+};
+export type OpenAIComputerAction = {
+    type: "click";
+    x: number;
+    y: number;
+    button?: "left" | "right" | "wheel" | "back" | "forward";
+} | {
+    type: "double_click";
+    x: number;
+    y: number;
+} | {
+    type: "drag";
+    path: Pt[];
+} | {
+    type: "keypress";
+    keys: string[];
+} | {
+    type: "move";
+    x: number;
+    y: number;
+} | {
+    type: "scroll";
+    x: number;
+    y: number;
+    scroll_x: number;
+    scroll_y: number;
+} | {
+    type: "type";
+    text: string;
+} | {
+    type: "wait";
+    ms?: number;
+} | {
+    type: "screenshot";
+};
+export interface OpenAIAdapterOptions {
+    client: AllternitComputers;
+    computerId: string;
+    /** display_width / display_height you declared on the computer_use_preview tool. */
+    display?: {
+        width: number;
+        height: number;
+    };
+    /** Pixels of scroll per wheel click when converting scroll_x / scroll_y. Default 100. */
+    pixelsPerScrollClick?: number;
+}
+/** ["CTRL","C"] → "ctrl+c" (the contract's xdotool-style key text). */
+export declare function openaiKeys(keys: string[]): string;
+/** Contract calls for one OpenAI action, in order. */
+export declare function openaiToCalls(a: OpenAIComputerAction, perClick?: number): Array<Pick<ToolsetCall, "member" | "input">>;
+export interface OpenAIStepResult {
+    /** Ready for the Responses API `input`: `{type:"computer_call_output", call_id, output}`. */
+    output: {
+        type: "computer_call_output";
+        call_id: string;
+        output: {
+            type: "computer_screenshot";
+            image_url: string;
+        };
+    };
+    /** The last failed action result, if any action failed. */
+    error?: ToolsetResult;
+}
+/** Run one OpenAI `computer_call` (its `call_id` and `action`) and return the output item. */
+export declare function runOpenAIAction(o: OpenAIAdapterOptions, callId: string, action: OpenAIComputerAction): Promise<OpenAIStepResult>;
+export {};

package/dist/openai.js

@@ -0,0 +1,87 @@
+// OpenAI computer-use adapter: runs one `computer_call` action on an Allternit
+// hosted computer and returns a `computer_call_output` with the next screenshot.
+import { resultImage } from "./client.js";
+const KEYS = {
+    CTRL: "ctrl", CONTROL: "ctrl", ALT: "alt", OPTION: "alt", SHIFT: "shift", CMD: "super", META: "super", SUPER: "super",
+    WIN: "super", ENTER: "Return", RETURN: "Return", ESC: "Escape", ESCAPE: "Escape", TAB: "Tab", SPACE: "space",
+    BACKSPACE: "BackSpace", DELETE: "Delete", UP: "Up", DOWN: "Down", LEFT: "Left", RIGHT: "Right",
+    ARROWUP: "Up", ARROWDOWN: "Down", ARROWLEFT: "Left", ARROWRIGHT: "Right", HOME: "Home", END: "End",
+    PAGEUP: "Page_Up", PAGEDOWN: "Page_Down",
+};
+/** ["CTRL","C"] → "ctrl+c" (the contract's xdotool-style key text). */
+export function openaiKeys(keys) {
+    return keys.map((k) => KEYS[k.toUpperCase()] ?? (k.length === 1 ? k.toLowerCase() : k)).join("+");
+}
+/** Contract calls for one OpenAI action, in order. */
+export function openaiToCalls(a, perClick = 100) {
+    const c = (x, y) => [Math.round(x), Math.round(y)];
+    switch (a.type) {
+        case "click": {
+            const b = a.button ?? "left";
+            if (b === "back")
+                return [{ member: "key", input: { text: "alt+Left" } }];
+            if (b === "forward")
+                return [{ member: "key", input: { text: "alt+Right" } }];
+            const member = b === "right" ? "right_click" : b === "wheel" ? "middle_click" : "left_click";
+            return [{ member, input: { coordinate: c(a.x, a.y) } }];
+        }
+        case "double_click":
+            return [{ member: "double_click", input: { coordinate: c(a.x, a.y) } }];
+        case "drag": {
+            const p = a.path;
+            if (p.length < 2)
+                return [];
+            if (p.length === 2)
+                return [{ member: "left_click_drag", input: { start_coordinate: c(p[0].x, p[0].y), coordinate: c(p[1].x, p[1].y) } }];
+            return [
+                { member: "mouse_move", input: { coordinate: c(p[0].x, p[0].y) } },
+                { member: "left_mouse_down", input: {} },
+                ...p.slice(1).map((q) => ({ member: "mouse_move", input: { coordinate: c(q.x, q.y) } })),
+                { member: "left_mouse_up", input: {} },
+            ];
+        }
+        case "keypress":
+            return [{ member: "key", input: { text: openaiKeys(a.keys) } }];
+        case "move":
+            return [{ member: "mouse_move", input: { coordinate: c(a.x, a.y) } }];
+        case "scroll": {
+            const out = [];
+            const amt = (v) => Math.max(1, Math.round(Math.abs(v) / perClick));
+            if (a.scroll_y)
+                out.push({ member: "scroll", input: { coordinate: c(a.x, a.y), scroll_direction: a.scroll_y > 0 ? "down" : "up", scroll_amount: amt(a.scroll_y) } });
+            if (a.scroll_x)
+                out.push({ member: "scroll", input: { coordinate: c(a.x, a.y), scroll_direction: a.scroll_x > 0 ? "right" : "left", scroll_amount: amt(a.scroll_x) } });
+            return out;
+        }
+        case "type":
+            return [{ member: "type", input: { text: a.text } }];
+        case "wait":
+            return [{ member: "wait", input: { duration: Math.max(1, Math.round((a.ms ?? 2000) / 1000)) } }];
+        case "screenshot":
+            return [];
+    }
+}
+/** Run one OpenAI `computer_call` (its `call_id` and `action`) and return the output item. */
+export async function runOpenAIAction(o, callId, action) {
+    const frame = o.display ? { model_frame: o.display, coordinate_space: "pixels" } : {};
+    let error;
+    for (const step of openaiToCalls(action, o.pixelsPerScrollClick)) {
+        const r = await o.client.toolset(o.computerId, { toolset: "computer", ...step, ...frame });
+        if (r.is_error) {
+            error = r;
+            break;
+        }
+    }
+    const s = await o.client.toolset(o.computerId, { toolset: "computer", member: "screenshot", input: {}, ...frame });
+    const img = resultImage(s);
+    if (!img)
+        throw new Error("Allternit computer returned no screenshot.");
+    return {
+        output: {
+            type: "computer_call_output",
+            call_id: callId,
+            output: { type: "computer_screenshot", image_url: `data:${img.media_type};base64,${img.data}` },
+        },
+        ...(error ? { error } : {}),
+    };
+}

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@allternit/computer-driver",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Drop-in drivers for Allternit hosted computers: a plain client plus Anthropic (computer/browser toolset), OpenAI computer-use and Gemini computer_use adapters.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./anthropic": {
+      "types": "./dist/anthropic.d.ts",
+      "import": "./dist/anthropic.js"
+    },
+    "./openai": {
+      "types": "./dist/openai.d.ts",
+      "import": "./dist/openai.js"
+    },
+    "./gemini": {
+      "types": "./dist/gemini.d.ts",
+      "import": "./dist/gemini.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/sdk": ">=0.132.0"
+  },
+  "peerDependenciesMeta": {
+    "@anthropic-ai/sdk": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@anthropic-ai/sdk": "0.132.0",
+    "typescript": "^5.9.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Allternit/allternit-platform.git",
+    "directory": "sdk/computer-driver"
+  },
+  "homepage": "https://docs.allternit.com/api/platform/sdks/typescript",
+  "publishConfig": {
+    "access": "public"
+  }
+}