@agentorg/computer 0.0.3 → 0.0.5

package/dist/sdk.js

@@ -24640,10 +24640,67 @@ var Endpoint = class {
     await client?.close();
   }
 };
+async function openLive(session, onMessage) {
+  const ws = new WebSocket(session.url);
+  ws.binaryType = "arraybuffer";
+  const closed = new Promise((done) => {
+    ws.addEventListener("close", (event) => done({ code: event.code, reason: event.reason }));
+  });
+  await new Promise((done, failed) => {
+    ws.addEventListener("open", () => done(), { once: true });
+    ws.addEventListener(
+      "error",
+      () => failed(new ComputerError(502, "The live session didn't open.")),
+      { once: true }
+    );
+  });
+  ws.addEventListener("message", (event) => onMessage(event.data));
+  return { ws, closed };
+}
+var INPUT = 48;
+var RESIZE = 49;
+var Pty = class {
+  #open;
+  constructor(open2) {
+    this.#open = open2;
+  }
+  /** Attach to its shell, starting one if none is running. Every attachment shares it. */
+  async connect(opts) {
+    const mode = opts.mode ?? "operate";
+    const decoder = new TextDecoder();
+    const { ws, closed } = await openLive(await this.#open("terminal", mode), (data) => {
+      if (typeof data === "string") return;
+      const frame = new Uint8Array(data);
+      if (frame[0] === INPUT) opts.onData(decoder.decode(frame.subarray(1), { stream: true }));
+    });
+    const send = (type, text) => {
+      const body = new TextEncoder().encode(text);
+      const frame = new Uint8Array(body.length + 1);
+      frame[0] = type;
+      frame.set(body, 1);
+      ws.send(frame);
+    };
+    return {
+      sendInput: (data) => send(INPUT, data),
+      resize: (columns, rows) => send(RESIZE, JSON.stringify({ columns, rows })),
+      close: () => ws.close(),
+      closed
+    };
+  }
+};
 var Commands = class {
   #endpoint;
-  constructor(endpoint) {
+  #open;
+  constructor(endpoint, open2) {
     this.#endpoint = endpoint;
+    this.#open = open2;
+  }
+  /** Each of the agent's commands as it runs: the ones already heard first, then as they come. */
+  async watch(onEvent) {
+    const { ws, closed } = await openLive(await this.#open("commands", "watch"), (data) => {
+      if (typeof data === "string") onEvent(JSON.parse(data));
+    });
+    return { close: () => ws.close(), closed };
   }
   async run(cmd, opts = {}) {
     let answer = await this.#endpoint.command("exec_command", {
@@ -24720,6 +24777,7 @@ var Computer = class _Computer {
   computerID;
   commands;
   files;
+  pty;
   #connection;
   #token;
   #computer;
@@ -24730,7 +24788,9 @@ var Computer = class _Computer {
     this.#token = token;
     this.#urls = info.endpoints;
     this.#computer = new Endpoint(info.endpoints.computer, token);
-    this.commands = new Commands(this.#computer);
+    const open2 = (surface, mode) => this.liveSession(surface, mode);
+    this.commands = new Commands(this.#computer, open2);
+    this.pty = new Pty(open2);
     this.files = new Files(this.#computer);
   }
   static async create(opts) {
@@ -24790,6 +24850,15 @@ var Computer = class _Computer {
   static async getLogs(computerID, opts = {}) {
     return answered(await apiOf(opts).GET("/v1/computers/{computerID}/logs", pathOf(computerID))).logs;
   }
+  /** A one-time ticket to open one of its surfaces live, within a minute. */
+  static async createLiveSession(computerID, session, opts = {}) {
+    return answered(
+      await apiOf(opts).POST("/v1/computers/{computerID}/live", {
+        ...pathOf(computerID),
+        body: { surface: session.surface, mode: session.mode ?? "watch" }
+      })
+    );
+  }
   static async kill(computerID, opts = {}) {
     answered(await apiOf(opts).DELETE("/v1/computers/{computerID}", pathOf(computerID)));
   }
@@ -24819,6 +24888,9 @@ var Computer = class _Computer {
   start(opts = {}) {
     return _Computer.start(this.computerID, { ...this.#connection, ...opts });
   }
+  liveSession(surface, mode = "watch") {
+    return _Computer.createLiveSession(this.computerID, { surface, mode }, this.#connection);
+  }
   getLogs() {
     return _Computer.getLogs(this.computerID, this.#connection);
   }

package/dist/types/generated/schema.d.ts

@@ -135,6 +135,44 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/computers/{computerID}/live": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                computerID: components["parameters"]["computerID"];
+            };
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** A one-time ticket to watch or operate one of its surfaces live: the agent's commands as they run, or a shell of your own. Open its url as a WebSocket within 60 seconds. */
+        post: operations["createLiveSession"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/live/{liveID}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                liveID: string;
+            };
+            cookie?: never;
+        };
+        /** Open a live session as a WebSocket. The ticket in its path is its authority and works once, so it takes no token. A request with an Origin header is refused unless the service was told to allow that origin. */
+        get: operations["openLiveSession"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
 }
 export type webhooks = Record<string, never>;
 export interface components {
@@ -202,11 +240,146 @@ export interface components {
         };
         ComputerDetail: components["schemas"]["Computer"] & {
             uptimeSeconds: number;
+            /** @description What can be opened live while it runs. */
+            surfaces: components["schemas"]["SurfaceInfo"][];
             tools: {
                 computer: string[];
                 browser: string[];
             };
         };
+        /**
+         * @description commands: the agent's commands as they run, read-only, in commands@1. terminal: a shell of your own in its workspace, as its user, in pty@1. browser: its browser, in screencast@1: binary messages are JPEG frames of the page shown, text messages are ScreencastEvent one way and ScreencastInput the other. Operating it makes you the driver: the agent's browser calls wait up to 25 seconds while you are, then answer that a person has or had it. You stop being the driver when you send release, close the socket, or send nothing for 60 seconds.
+         * @enum {string}
+         */
+        Surface: "commands" | "terminal" | "browser";
+        /**
+         * @description In watch, what you send is dropped.
+         * @enum {string}
+         */
+        LiveMode: "watch" | "operate";
+        SurfaceInfo: {
+            surface: components["schemas"]["Surface"];
+            protocol: string;
+            /** @description Whether it can be operated */
+            operate: boolean;
+            /** @description Why it can't be opened here */
+            unavailable?: string;
+        };
+        NewLiveSession: {
+            surface: components["schemas"]["Surface"];
+            /** @default watch */
+            mode: components["schemas"]["LiveMode"];
+        };
+        LiveSession: {
+            /** @description The WebSocket to open */
+            url: string;
+            protocol: string;
+            surface: components["schemas"]["Surface"];
+            mode: components["schemas"]["LiveMode"];
+            /** Format: date-time */
+            expiresAt: string;
+        };
+        /** @description What the service sends on a screencast@1 socket, as JSON text. */
+        ScreencastEvent: {
+            /** @constant */
+            type: "tabs";
+            tabs: {
+                id: number;
+                url: string;
+                title: string;
+            }[];
+            shown: number | null;
+        } | {
+            /** @constant */
+            type: "viewport";
+            width: number;
+            height: number;
+        } | {
+            /** @constant */
+            type: "dialog";
+            open: boolean;
+            /** @enum {string} */
+            kind?: "alert" | "confirm" | "prompt" | "beforeunload";
+            message?: string;
+            defaultValue?: string;
+        } | {
+            /** @constant */
+            type: "file-chooser";
+            open: boolean;
+            multiple?: boolean;
+        } | {
+            /** @constant */
+            type: "choice";
+            multiple: boolean;
+            options: {
+                value: string;
+                label: string;
+                selected: boolean;
+            }[];
+        } | {
+            /** @constant */
+            type: "driver";
+            you: boolean;
+            held: boolean;
+            agentWaiting: boolean;
+        };
+        /** @description What an operate socket sends on screencast@1, as JSON text. A watch socket's is dropped. */
+        ScreencastInput: {
+            /** @constant */
+            type: "mouse";
+            /** @enum {string} */
+            action: "move" | "down" | "up" | "wheel";
+            x: number;
+            y: number;
+            /** @enum {string} */
+            button?: "left" | "right" | "middle";
+            deltaX?: number;
+            deltaY?: number;
+        } | {
+            /** @constant */
+            type: "key";
+            /** @enum {string} */
+            action: "down" | "up";
+            /** @description A key name */
+            key: string;
+        } | {
+            /** @constant */
+            type: "text";
+            text: string;
+        } | {
+            /** @constant */
+            type: "dialog";
+            accept: boolean;
+            text?: string;
+        } | {
+            /** @constant */
+            type: "files";
+            files: {
+                name: string;
+                mimeType?: string;
+                /** @description Base64. */
+                data: string;
+            }[];
+        } | {
+            /** @constant */
+            type: "choice";
+            values: string[];
+        } | {
+            /** @constant */
+            type: "tab";
+            /** @enum {string} */
+            action: "show" | "open" | "close";
+            id?: number;
+            url?: string;
+        } | {
+            /** @constant */
+            type: "navigate";
+            /** @description A URL */
+            to: string;
+        } | {
+            /** @constant */
+            type: "release";
+        };
         ComputerLogs: {
             logs: {
                 /** Format: date-time */
@@ -476,4 +649,57 @@ export interface operations {
             404: components["responses"]["Error"];
         };
     };
+    createLiveSession: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                computerID: components["parameters"]["computerID"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["NewLiveSession"];
+            };
+        };
+        responses: {
+            /** @description The ticket. */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["LiveSession"];
+                };
+            };
+            400: components["responses"]["Error"];
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["Error"];
+            409: components["responses"]["Error"];
+        };
+    };
+    openLiveSession: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                liveID: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The socket */
+            101: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            403: components["responses"]["Error"];
+            404: components["responses"]["Error"];
+            426: components["responses"]["Error"];
+        };
+    };
 }

package/dist/types/sdk.d.ts

@@ -4,6 +4,39 @@ export type ComputerInfo = Schemas["Computer"];
 export type ComputerDetail = Schemas["ComputerDetail"];
 export type ServiceInfo = Schemas["ServiceInfo"];
 export type ComputerLog = Schemas["ComputerLogs"]["logs"][number];
+export type LiveSurface = Schemas["Surface"];
+export type LiveMode = Schemas["LiveMode"];
+export type LiveSession = Schemas["LiveSession"];
+/** What happens to one of the agent's commands, as it happens. */
+export type CommandEvent = {
+    type: "start";
+    id: string;
+    cmd: string;
+    workdir: string;
+    at: string;
+} | {
+    type: "output";
+    id: string;
+    stream: "stdout" | "stderr";
+    text: string;
+} | {
+    type: "exit";
+    id: string;
+    exitCode: number;
+    at: string;
+};
+export interface LiveHandle {
+    close(): void;
+    /** Resolves when the socket closes, with why. */
+    closed: Promise<{
+        code: number;
+        reason: string;
+    }>;
+}
+export interface PtyHandle extends LiveHandle {
+    sendInput(data: string): void;
+    resize(columns: number, rows: number): void;
+}
 export interface ConnectionOpts {
     /** The control token; `AGENTCOMPUTER_API_KEY` by default. */
     apiKey?: string;
@@ -48,10 +81,23 @@ declare class Endpoint {
     command(name: string, args: Record<string, unknown>): Promise<CommandAnswer>;
     close(): Promise<void>;
 }
+type Opener = (surface: LiveSurface, mode: LiveMode) => Promise<LiveSession>;
+/** A shell of your own on the computer, beside the agent's commands. */
+declare class Pty {
+    #private;
+    constructor(open: Opener);
+    /** Attach to its shell, starting one if none is running. Every attachment shares it. */
+    connect(opts: {
+        onData: (data: string) => void;
+        mode?: LiveMode;
+    }): Promise<PtyHandle>;
+}
 /** Commands on a computer with the terminal level. */
 declare class Commands {
     #private;
-    constructor(endpoint: Endpoint);
+    constructor(endpoint: Endpoint, open: Opener);
+    /** Each of the agent's commands as it runs: the ones already heard first, then as they come. */
+    watch(onEvent: (event: CommandEvent) => void): Promise<LiveHandle>;
     /** Run a command to its end. */
     run(cmd: string, opts?: {
         cwd?: string;
@@ -98,6 +144,7 @@ export declare class Computer {
     readonly computerID: string;
     readonly commands: Commands;
     readonly files: Files;
+    readonly pty: Pty;
     private constructor();
     static create(opts: CreateOpts): Promise<Computer>;
     /** A computer made earlier. Its token was shown when it was made, and only then. */
@@ -116,6 +163,11 @@ export declare class Computer {
         timeoutMs?: number;
     }): Promise<ComputerInfo>;
     static getLogs(computerID: string, opts?: ConnectionOpts): Promise<ComputerLog[]>;
+    /** A one-time ticket to open one of its surfaces live, within a minute. */
+    static createLiveSession(computerID: string, session: {
+        surface: LiveSurface;
+        mode?: LiveMode;
+    }, opts?: ConnectionOpts): Promise<LiveSession>;
     static kill(computerID: string, opts?: ConnectionOpts): Promise<void>;
     /** The endpoint to give an MCP client. */
     getMcpUrl(endpoint?: "computer" | "browser"): string;
@@ -134,6 +186,7 @@ export declare class Computer {
         endpoints: components["schemas"]["Endpoints"];
     } & {
         uptimeSeconds: number;
+        surfaces: components["schemas"]["SurfaceInfo"][];
         tools: {
             computer: string[];
             browser: string[];
@@ -178,6 +231,13 @@ export declare class Computer {
         metadata: components["schemas"]["Metadata"];
         endpoints: components["schemas"]["Endpoints"];
     }>;
+    liveSession(surface: LiveSurface, mode?: LiveMode): Promise<{
+        url: string;
+        protocol: string;
+        surface: components["schemas"]["Surface"];
+        mode: components["schemas"]["LiveMode"];
+        expiresAt: string;
+    }>;
     getLogs(): Promise<{
         timestamp: string;
         line: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentorg/computer",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Computers for agents, as a service: a terminal, files and a browser over MCP",
   "license": "Apache-2.0",
   "repository": {
@@ -28,19 +28,22 @@
     "test": "npm run build && node --test --test-timeout=60000 \"out/test/**/*.test.js\""
   },
   "dependencies": {
-    "@playwright/mcp": "0.0.84"
+    "@playwright/mcp": "0.0.84",
+    "playwright-core": "1.65.0-alpha-2026-10-30"
   },
   "devDependencies": {
-    "@agentorg/exec": "0.0.2",
+    "@agentorg/exec": "0.0.3",
     "@biomejs/biome": "2.6.5",
     "@modelcontextprotocol/client": "2.4.0",
     "@modelcontextprotocol/node": "2.1.2",
     "@modelcontextprotocol/server": "2.4.0",
     "@types/node": "^22.20.5",
+    "@types/ws": "8.18.2",
     "ajv": "8.20.0",
     "esbuild": "0.28.2",
     "openapi-fetch": "0.17.0",
     "typescript": "^7.0.2",
+    "ws": "8.22.2",
     "yaml": "2.9.1",
     "zod": "^4.6.7"
   },
@@ -49,5 +52,11 @@
       "types": "./dist/types/sdk.d.ts",
       "default": "./dist/sdk.js"
     }
+  },
+  "optionalDependencies": {
+    "node-pty": "1.1.0"
+  },
+  "allowScripts": {
+    "node-pty@1.1.0": true
   }
 }