@allternit/computer-driver 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.2.0 — 2026-10-10
+
+### Added
+
+- **Contract v2 (`allternit.computer.v2`) structured members.** Typed client methods for all ten driver-backed members — `read_ui`, `act`, `run_batch`, `verify`, `request_human`, `use_credential`, `run_subtask`, `run_parallel`, `run_skill`, `skills` — on the new `ComputerV2Driver` (exported from the package root). Input and result types are generated from `contracts/computer-toolset/allternit-computer-v2.json` (`src/v2-generated.ts`, emitted by `contracts/computer-toolset/generate.mjs`), so they cannot drift from the server contract.
+- **`computer_v2` function tool next to the pixel tool in every adapter**, with the same steering guidance gizzi sends: `computerV2AnthropicTool` + `runAnthropicComputerV2` (anthropic subpath), `openaiComputerV2Tool` + `runOpenAIV2Call`, `geminiComputerV2Declaration` + `runGeminiV2Call`, plus the provider-neutral `computerV2Tool()`.
+- **Approval flow helper.** `client.toolsetWithApproval(id, call, onApproval)` answers a 409 `approval_required` hold (approve + resend with the single-use `approval_grant`) for any member, pixel or structured.
+- **Typed errors.** `ComputerV2Error` (a structured member answered `is_error`), `ComputerBusyError` (423 `computer_busy` / `computer_controlled_elsewhere`), `SandboxRequiredError` (409 `sandbox_required`) and `ComputerConflictError` (409 `computer_conflict`).
+
+### Notes
+
+- Requires the Allternit Driver sidecar on the computer for the structured members (this-device today). The 17 pixel members are unchanged.

package/README.md

@@ -1,3 +1,105 @@
-# 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" })
+```
+
+## Structured UI driving (allternit.computer.v2)
+
+Contract v2 adds ten driver-backed structured members — `read_ui`, `act`, `run_batch`, `verify`, `request_human`, `use_credential`, `run_subtask`, `run_parallel`, `run_skill`, `skills` — typed end to end. `ComputerV2Driver` calls them directly; every adapter also exposes them to the model as the `computer_v2` function tool. The structured members need the Allternit Driver on the computer (this-device today).
+
+```ts
+import { ComputerV2Driver } from "@allternit/computer-driver"
+const v2 = new ComputerV2Driver({ client, computerId: computer.id, onApproval: async (a) => askAPerson(a) })
+
+// Read the UI as an element tree — no screenshots.
+const ui = await v2.read_ui({ app: "Safari" })
+const field = ui.elements?.find((e) => e.role === "textfield")
+if (field) await v2.act({ id: field.id, op: "set_value", value: "hello@example.com", version: ui.version })
+
+// Hand a bounded step sequence to the fast decision loop instead of clicking through it yourself.
+const sub = await v2.run_subtask({
+  goal: "Fill the signup form and submit it",
+  inputs: [{ name: "email", value: "hello@example.com" }],
+  success: [{ role: "button", name: "Submit" }],
+})
+if (sub.status !== "done") console.log(sub.status, sub.next)
+```
+
+### Subtask safety statuses
+
+`run_subtask` / `run_skill` / `run_parallel` results end with a `status`:
+
+- `done` — the goal is met.
+- `escalated` — handed back with a `reason` and the current `screen`; continue from there yourself.
+- `needs_confirmation` — the next step (`held_step`) needs the person's confirmation; run it yourself with `act`/`run_batch` and the server asks them.
+- `paused` — the safety monitor paused the subtask; stop and call `request_human`.
+- `denied` — the step isn't allowed on this computer (app/domain lists or a credential binding); find another way.
+- `use_api` — make the named API/MCP call yourself (`api.tool`); the screen is untouched.
+- `failed` — ran out of steps, budget or a hard error.
+
+### The computer_v2 function tool in a model loop
+
+Each adapter exposes the structured members with the same steering guidance gizzi sends:
+
+```ts
+import { computerV2AnthropicTool, runAnthropicComputerV2 } from "@allternit/computer-driver/anthropic"
+import { openaiComputerV2Tool, runOpenAIV2Call } from "@allternit/computer-driver"
+import { geminiComputerV2Declaration, runGeminiV2Call } from "@allternit/computer-driver"
+
+// Anthropic: put computerV2AnthropicTool() next to the toolset in tools, and answer
+// tool_use blocks whose name is "computer_v2" with runAnthropicComputerV2({ client, computerId, onApproval }, name, input).
+// OpenAI: put openaiComputerV2Tool() in tools and answer function_call items with
+// runOpenAIV2Call({ client, computerId }, call.call_id, JSON.parse(call.arguments)).
+// Gemini: put geminiComputerV2Declaration() in functionDeclarations and answer
+// functionCall parts with runGeminiV2Call({ client, computerId }, part.functionCall.name, part.functionCall.args).
+```
+
+`computerV2Tool()` returns the provider-neutral `{ name, description, schema }` if you wire tools yourself.
+
+## 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, computerV2AnthropicTool()], ... })
+```
+
+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 pixel adapters let `ApprovalRequiredError` propagate; catch it, call `client.approve()`, and resend the action.
+
+## Errors
+
+- `ApprovalRequiredError` — 409 `approval_required`; carries `approval` (id, member, `approve_url`) and the held `result`. `client.toolsetWithApproval(id, call, onApproval)` approves and resends with the `approval_grant` for you.
+- `ComputerV2Error` — a structured member answered `is_error: true`; carries the member name and raw `result`.
+- `ComputerBusyError` — 423 `computer_busy` / `computer_controlled_elsewhere`.
+- `SandboxRequiredError` — 409 `sandbox_required` (the call needs a sandbox computer).
+- `ComputerConflictError` — 409 `computer_conflict` (another subtask or lease conflicts).
+- `AllternitApiError` — everything else, with `status`, `code`, `type`.

package/dist/anthropic.d.ts

@@ -0,0 +1,43 @@
+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>;
+}
+/**
+ * The `computer_v2` function tool for Anthropic models: the ten structured
+ * members (read_ui … skills) next to the native pixel toolset. The Anthropic
+ * wire hook only rewrites tools carrying the v1 pixel marker, so this passes
+ * through untouched.
+ */
+export declare function computerV2AnthropicTool(): {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+};
+/**
+ * Run one `computer_v2` function call (`{action, ...fields}`) and return the
+ * tool-result content blocks, like any toolset member. Throws ToolError on a
+ * failed action; without `onApproval`, a held call (409 approval_required)
+ * resolves its held result as an error, the same rule as the toolsets.
+ */
+export declare function runAnthropicComputerV2(o: DriverOptions, name: string, input: unknown): Promise<any[]>;

package/dist/anthropic.js

@@ -0,0 +1,157 @@
+// 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";
+import { computerV2Tool, runComputerV2Member } from "./v2.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);
+        }
+    }
+}
+// ------------------------------------------------------------------ computer_v2
+/**
+ * The `computer_v2` function tool for Anthropic models: the ten structured
+ * members (read_ui … skills) next to the native pixel toolset. The Anthropic
+ * wire hook only rewrites tools carrying the v1 pixel marker, so this passes
+ * through untouched.
+ */
+export function computerV2AnthropicTool() {
+    const t = computerV2Tool();
+    return { name: t.name, description: t.description, input_schema: t.schema };
+}
+/**
+ * Run one `computer_v2` function call (`{action, ...fields}`) and return the
+ * tool-result content blocks, like any toolset member. Throws ToolError on a
+ * failed action; without `onApproval`, a held call (409 approval_required)
+ * resolves its held result as an error, the same rule as the toolsets.
+ */
+export async function runAnthropicComputerV2(o, name, input) {
+    const { action, ...fields } = (input ?? {});
+    if (!action)
+        throw new ToolError("The computer_v2 call needs an action.");
+    const res = await runComputerV2Member({ client: o.client, computerId: o.computerId, onApproval: o.onApproval }, action, fields);
+    if (res.is_error)
+        throw new ToolError(toAnthropicBlocks(res));
+    return toAnthropicBlocks(res);
+}

package/dist/client.d.ts

@@ -0,0 +1,157 @@
+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);
+}
+/** 423 computer_busy / computer_controlled_elsewhere: someone else holds the computer right now; retry shortly or request_human. */
+export declare class ComputerBusyError extends AllternitApiError {
+    constructor(status: number, err: Partial<ApiErrorBody>, body: unknown);
+}
+/** 409 sandbox_required: the call only runs on a sandbox (cloud/bot) computer. */
+export declare class SandboxRequiredError extends AllternitApiError {
+    constructor(status: number, err: Partial<ApiErrorBody>, body: unknown);
+}
+/** 409 computer_conflict: the call conflicts with another subtask or lease on the computer. */
+export declare class ComputerConflictError extends AllternitApiError {
+    constructor(status: number, err: Partial<ApiErrorBody>, 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>;
+    /**
+     * Run one toolset member, answering a 409 approval_required hold. When the
+     * server holds the call and `onApproval` returns true, the approval is
+     * granted (POST /approvals/{id}) and the same call resent with the
+     * single-use `approval_grant`. When `onApproval` is missing or returns
+     * false, the held result resolves (is_error:true) so the model sees it.
+     */
+    toolsetWithApproval(id: string, call: ToolsetCall, onApproval?: (approval: Approval) => boolean | Promise<boolean>): 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,173 @@
+// 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;
+    }
+}
+/** 423 computer_busy / computer_controlled_elsewhere: someone else holds the computer right now; retry shortly or request_human. */
+export class ComputerBusyError extends AllternitApiError {
+    constructor(status, err, body) {
+        super(status, err, body);
+        this.name = "ComputerBusyError";
+    }
+}
+/** 409 sandbox_required: the call only runs on a sandbox (cloud/bot) computer. */
+export class SandboxRequiredError extends AllternitApiError {
+    constructor(status, err, body) {
+        super(status, err, body);
+        this.name = "SandboxRequiredError";
+    }
+}
+/** 409 computer_conflict: the call conflicts with another subtask or lease on the computer. */
+export class ComputerConflictError extends AllternitApiError {
+    constructor(status, err, body) {
+        super(status, err, body);
+        this.name = "ComputerConflictError";
+    }
+}
+/** Maps a toolset error body onto the typed error for its code, if one exists. */
+function typedApiError(status, err, body) {
+    switch (err.code) {
+        case "computer_busy":
+        case "computer_controlled_elsewhere":
+            return new ComputerBusyError(status, err, body);
+        case "sandbox_required":
+            return new SandboxRequiredError(status, err, body);
+        case "computer_conflict":
+            return new ComputerConflictError(status, err, body);
+        default:
+            return new AllternitApiError(status, err, body);
+    }
+}
+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);
+    }
+    /**
+     * Run one toolset member, answering a 409 approval_required hold. When the
+     * server holds the call and `onApproval` returns true, the approval is
+     * granted (POST /approvals/{id}) and the same call resent with the
+     * single-use `approval_grant`. When `onApproval` is missing or returns
+     * false, the held result resolves (is_error:true) so the model sees it.
+     */
+    async toolsetWithApproval(id, call, onApproval) {
+        try {
+            return await this.toolset(id, call);
+        }
+        catch (e) {
+            if (!(e instanceof ApprovalRequiredError))
+                throw e;
+            if (!onApproval || !(await onApproval(e.approval)))
+                return e.result;
+            await this.approve(id, e.approval.id);
+            return this.toolset(id, { ...call, approval_grant: e.approval.id });
+        }
+    }
+    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 typedApiError(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() : "";
+}