@agentorg/computer 0.0.2 → 0.0.4

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,45 @@ 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.
+         * @enum {string}
+         */
+        Surface: "commands" | "terminal";
+        /**
+         * @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;
+        };
         ComputerLogs: {
             logs: {
                 /** Format: date-time */
@@ -476,4 +548,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.2",
+  "version": "0.0.4",
   "description": "Computers for agents, as a service: a terminal, files and a browser over MCP",
   "license": "Apache-2.0",
   "repository": {
@@ -31,16 +31,18 @@
     "@playwright/mcp": "0.0.84"
   },
   "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 +51,11 @@
       "types": "./dist/types/sdk.d.ts",
       "default": "./dist/sdk.js"
     }
+  },
+  "optionalDependencies": {
+    "node-pty": "1.1.0"
+  },
+  "allowScripts": {
+    "node-pty@1.1.0": true
   }
 }