@agentorg/computer 0.0.9 → 0.0.10

package/README.md

@@ -164,6 +164,13 @@ A computer with `--browser` has another:
   - **A dialog, a file chooser and a list belong to a page.** A dialog is told to the sockets shown its page until someone answers it, you or the agent. Nothing says when the agent answers a file chooser, so when it answers one every open chooser is taken as closed: press again if yours was.
   - **A client written for the earlier `screencast@1` still connects.** Its `release` is ignored and no `driver` event comes: nobody holds the browser any more.
 
+Every running computer has one more, to watch only:
+
+- **`load`** (protocol `metrics@1`): how busy it is. The service sends a reading every two seconds while a socket is open, the first two seconds after the first socket opens, and the last one at once to a socket that opens later: `{"type":"reading","scope":"machine","cpuUsedPct":37.2,"memUsed":…,"memTotal":…,"diskUsed":…,"diskTotal":…}`, in bytes. `openapi.yaml` has each field, as `LoadReading`.
+  - **`scope` says whose numbers they are.** A computer in a container reads its own (`computer`), against the machine's totals, since a container has no limit of its own. A computer with no isolation has no edge to measure at, so it reads the whole machine's (`machine`), as every other computer of that service does; so does a container that can't read its own.
+  - **The disk is the volume its workspace is on,** not the workspace's own size.
+  - **Nothing depends on it.** Nothing is read while nobody watches, a reading that can't be taken is left out, and a socket that hasn't read the one before is not sent the next.
+
 `POST /v1/computers/{computerID}/live` with `{ "surface": "terminal", "mode": "operate" }` gives a ticket: a `url` to open once within a minute, which needs no token. A request with an `Origin` header is refused unless `serve --allow-origin` names that origin, so a page can't open one. The SDK does the same with `computer.terminals.connect({ onEvent })`, or gives the ticket alone with `computer.liveSession("files")` or `computer.liveSession("browser", "operate")`, and the CLI with `agentcomputer live <id> --surface terminal --mode operate`.
 
 A shell of your own needs [node-pty](https://github.com/microsoft/node-pty), an optional dependency installed beside the program. It comes prebuilt for macOS. On Linux it's compiled at install, which npm only does when told: `npm install -g @agentorg/computer --allow-scripts=node-pty`, with a C++ toolchain. Without it, the agent's commands run and show as ever, and only `open` is refused, saying why. The computer image has it.

package/dist/agentcomputer.js

@@ -3772,9 +3772,9 @@ var playwright = () => {
 // src/browser-host.ts
 var sandboxFor = (options) => options.sandbox ?? (process.platform !== "linux" || !options.executable && !["chromium", "chrome-for-testing"].includes(options.channel ?? "chrome"));
 async function hostBrowser(options) {
-  const run2 = mkdtempSync(join("/tmp", "agentcomputer-"));
-  process.env.XDG_RUNTIME_DIR = run2;
-  process.env.TMPDIR = run2;
+  const run3 = mkdtempSync(join("/tmp", "agentcomputer-"));
+  process.env.XDG_RUNTIME_DIR = run3;
+  process.env.TMPDIR = run3;
   const context = await playwright().chromium.launchPersistentContext(options.profile, {
     headless: true,
     chromiumSandbox: sandboxFor(options),
@@ -3783,7 +3783,7 @@ async function hostBrowser(options) {
   const browser = context.browser();
   if (!browser) throw new Error("The browser can't be shared.");
   const { endpoint } = await browser.bind("agentcomputer");
-  if (!endpoint.startsWith(run2 + sep)) {
+  if (!endpoint.startsWith(run3 + sep)) {
     await context.close();
     throw new Error(`The browser's socket isn't in its own folder: ${endpoint}`);
   }
@@ -3797,7 +3797,7 @@ async function hostBrowser(options) {
     });
     await context.close().catch(() => {
     });
-    rmSync(run2, { recursive: true, force: true });
+    rmSync(run3, { recursive: true, force: true });
     process.exit(0);
   };
   for (const signal of ["SIGINT", "SIGTERM"]) process.once(signal, () => void stop());
@@ -3846,13 +3846,13 @@ async function serveBrowserMcp(options) {
 }
 
 // src/container.ts
-import { execFile, spawn as spawn3 } from "node:child_process";
+import { execFile as execFile2, spawn as spawn3 } from "node:child_process";
 import { readFileSync as readFileSync3 } from "node:fs";
 import { connect } from "node:net";
 import { join as join8 } from "node:path";
 import { createInterface as createInterface2 } from "node:readline";
 import { Readable as Readable3 } from "node:stream";
-import { promisify } from "node:util";
+import { promisify as promisify2 } from "node:util";
 
 // src/browser.ts
 import { spawn } from "node:child_process";
@@ -28413,7 +28413,7 @@ var require_ignore = __commonJS2({
         //   ever starts again inside it -- `(\\+?) ` did, which made a long run
         //   quadratic.
         /(\\+)( ?)/g,
-        (_, run2, space) => space ? run2.slice(0, run2.length - run2.length % 2) + SPACE2 : run2,
+        (_, run3, space) => space ? run3.slice(0, run3.length - run3.length % 2) + SPACE2 : run3,
         ESCAPE + SPACE2
       ],
       // git's wildmatch() reads a run of two or more asterisks as one globstar
@@ -28599,10 +28599,10 @@ var require_ignore = __commonJS2({
     var REGEX_REPLACE_TRAILING_DOUBLESTAR = /\uE001$/;
     var replaceTrailingDoublestar = () => ".+(?=$|\\/$)";
     var WILDCARD2 = "[^\\/]*";
-    var separatorAfter = (run2, at) => {
+    var separatorAfter = (run3, at) => {
       let separator = EMPTY;
-      for (let index = at + 1; index < run2.length && !run2[index].wildcard; index++) {
-        separator += run2[index].single;
+      for (let index = at + 1; index < run3.length && !run3[index].wildcard; index++) {
+        separator += run3[index].single;
       }
       return separator;
     };
@@ -28662,26 +28662,26 @@ var require_ignore = __commonJS2({
         }
       }
       let out = EMPTY;
-      let run2 = [];
+      let run3 = [];
       const flush = () => {
         let lastWildcard;
-        run2.forEach((token, at) => {
+        run3.forEach((token, at) => {
           if (token.wildcard) {
             lastWildcard = at;
           }
         });
-        run2.forEach((token, at) => {
+        run3.forEach((token, at) => {
           if (!token.wildcard) {
             out += token.single;
             return;
           }
-          out += at === lastWildcard ? WILDCARD2 : `(?:(?!${separatorAfter(run2, at)})[^\\/])*`;
+          out += at === lastWildcard ? WILDCARD2 : `(?:(?!${separatorAfter(run3, at)})[^\\/])*`;
         });
-        run2 = [];
+        run3 = [];
       };
       tokens.forEach((token) => {
         if (token.boundary === void 0) {
-          run2.push(token);
+          run3.push(token);
           return;
         }
         flush();
@@ -48443,7 +48443,7 @@ function visit(schema, fnOrHandlers) {
     return h ? h(node22, rewritten) : node22;
   };
   const cache = /* @__PURE__ */ new Map();
-  function run2(s) {
+  function run3(s) {
     const cached22 = cache.get(s);
     if (cached22 === RESOLVING) {
       return new $ZodLazy2({
@@ -48469,21 +48469,21 @@ function visit(schema, fnOrHandlers) {
         let changed2 = false;
         const newShape = {};
         for (const k of keys) {
-          const mapped = run2(oldShape[k]);
+          const mapped = run3(oldShape[k]);
           if (mapped !== oldShape[k])
             changed2 = true;
           newShape[k] = mapped;
         }
         let newCatchall = def.catchall;
         if (def.catchall) {
-          newCatchall = run2(def.catchall);
+          newCatchall = run3(def.catchall);
           if (newCatchall !== def.catchall)
             changed2 = true;
         }
         return changed2 ? clone2(s, { ...def, shape: newShape, catchall: newCatchall }) : s;
       }
       case "array": {
-        const mapped = run2(def.element);
+        const mapped = run3(def.element);
         return mapped === def.element ? s : clone2(s, { ...def, element: mapped });
       }
       case "tuple": {
@@ -48491,14 +48491,14 @@ function visit(schema, fnOrHandlers) {
         let changed2 = false;
         const newItems = [];
         for (const item of oldItems) {
-          const mapped = run2(item);
+          const mapped = run3(item);
           if (mapped !== item)
             changed2 = true;
           newItems.push(mapped);
         }
         let newRest = def.rest;
         if (def.rest) {
-          newRest = run2(def.rest);
+          newRest = run3(def.rest);
           if (newRest !== def.rest)
             changed2 = true;
         }
@@ -48506,12 +48506,12 @@ function visit(schema, fnOrHandlers) {
       }
       case "record":
       case "map": {
-        const newKey = run2(def.keyType);
-        const newVal = run2(def.valueType);
+        const newKey = run3(def.keyType);
+        const newVal = run3(def.valueType);
         return newKey === def.keyType && newVal === def.valueType ? s : clone2(s, { ...def, keyType: newKey, valueType: newVal });
       }
       case "set": {
-        const newVal = run2(def.valueType);
+        const newVal = run3(def.valueType);
         return newVal === def.valueType ? s : clone2(s, { ...def, valueType: newVal });
       }
       case "union": {
@@ -48519,7 +48519,7 @@ function visit(schema, fnOrHandlers) {
         let changed2 = false;
         const newOptions = [];
         for (const opt of oldOptions) {
-          const mapped = run2(opt);
+          const mapped = run3(opt);
           if (mapped !== opt)
             changed2 = true;
           newOptions.push(mapped);
@@ -48527,8 +48527,8 @@ function visit(schema, fnOrHandlers) {
         return changed2 ? clone2(s, { ...def, options: newOptions }) : s;
       }
       case "intersection": {
-        const newLeft = run2(def.left);
-        const newRight = run2(def.right);
+        const newLeft = run3(def.left);
+        const newRight = run3(def.right);
         return newLeft === def.left && newRight === def.right ? s : clone2(s, { ...def, left: newLeft, right: newRight });
       }
       case "optional":
@@ -48540,23 +48540,23 @@ function visit(schema, fnOrHandlers) {
       case "nonoptional":
       case "promise":
       case "success": {
-        const newInner = run2(def.innerType);
+        const newInner = run3(def.innerType);
         return newInner === def.innerType ? s : clone2(s, { ...def, innerType: newInner });
       }
       case "pipe": {
-        const newIn = run2(def.in);
-        const newOut = run2(def.out);
+        const newIn = run3(def.in);
+        const newOut = run3(def.out);
         return newIn === def.in && newOut === def.out ? s : clone2(s, { ...def, in: newIn, out: newOut });
       }
       case "function": {
-        const newInput = run2(def.input);
-        const newOutput = run2(def.output);
+        const newInput = run3(def.input);
+        const newOutput = run3(def.output);
         return newInput === def.input && newOutput === def.output ? s : clone2(s, { ...def, input: newInput, output: newOutput });
       }
       case "lazy": {
         const original = def.getter;
         const { _cachedInner, ...rest } = def;
-        return clone2(s, { ...rest, getter: () => run2(original()) });
+        return clone2(s, { ...rest, getter: () => run3(original()) });
       }
       // A leaf by choice: `parts` are regex fragments, not data positions.
       case "template_literal":
@@ -48587,7 +48587,7 @@ function visit(schema, fnOrHandlers) {
       }
     }
   }
-  return run2(schema);
+  return run3(schema);
 }
 function deepPartial(schema) {
   return visit(schema, {
@@ -67310,7 +67310,8 @@ function* pieces(text3, most = MAX_TEXT) {
 var PROTOCOLS = {
   terminal: "terminal@1",
   files: "files@1",
-  browser: "screencast@1"
+  browser: "screencast@1",
+  load: "metrics@1"
 };
 var MAX_MESSAGE = 64 * 1024;
 var MAX_BUFFERED3 = 4 * 1024 * 1024;
@@ -67323,7 +67324,8 @@ var MAX_WORKDIR = 2e3;
 var SERVERS = {
   terminal: new import_websocket_server.default({ noServer: true, maxPayload: MAX_MESSAGE }),
   files: new import_websocket_server.default({ noServer: true, maxPayload: MAX_PART }),
-  browser: new import_websocket_server.default({ noServer: true })
+  browser: new import_websocket_server.default({ noServer: true }),
+  load: new import_websocket_server.default({ noServer: true, maxPayload: MAX_MESSAGE })
 };
 var MALFORMED = "That isn't a terminal@1 message.";
 var first = (text3, most) => {
@@ -67343,7 +67345,9 @@ var Live = class {
   #files;
   /** Whether a person may write files here: not where the agent can only read them. */
   #writes;
-  constructor(exec, access, browser) {
+  #load;
+  constructor(exec, access, load, browser) {
+    this.#load = load;
     if (exec && access === "terminal") {
       this.#terminals = exec.terminals;
       exec.onCommand((event) => {
@@ -67362,6 +67366,7 @@ var Live = class {
       surfaces.push({ surface: "files", protocol: PROTOCOLS.files, operate: this.#writes });
     if (this.#browser)
       surfaces.push({ surface: "browser", protocol: PROTOCOLS.browser, operate: true });
+    surfaces.push({ surface: "load", protocol: PROTOCOLS.load, operate: false });
     return surfaces;
   }
   /** Take an upgraded request as a socket on one surface. */
@@ -67372,6 +67377,7 @@ var Live = class {
       if (surface === "terminal" && this.#terminals) this.#view(ws, mode, this.#terminals);
       else if (surface === "files" && this.#files) this.#files.open(ws, mode);
       else if (surface === "browser" && this.#browser) this.#browser.open(ws, mode);
+      else if (surface === "load") this.#load.open(ws);
       else ws.close(1011, `There's no ${surface} here.`);
     });
   }
@@ -67379,6 +67385,7 @@ var Live = class {
   close() {
     void this.#browser?.close();
     this.#files?.close();
+    this.#load.close();
     for (const ws of this.#viewers) ws.close(1001, "It stopped.");
   }
   /**
@@ -67417,6 +67424,114 @@ var Live = class {
   }
 };
 
+// src/load-live.ts
+import { execFile } from "node:child_process";
+import { readFile as readFile2 } from "node:fs/promises";
+import { availableParallelism, cpus, freemem, totalmem } from "node:os";
+import { promisify } from "node:util";
+var EVERY_MS = 2e3;
+var run = promisify(execFile);
+var numberOf = (text3, name) => Number(new RegExp(`^${name}\\s+(\\d+)`, "m").exec(text3)?.[1]);
+async function disk(folder) {
+  const { stdout } = await run("df", ["-kP", folder], { timeout: EVERY_MS });
+  const [, total, used] = /\s(\d+)\s+(\d+)\s+\d+\s+\d+%/.exec(stdout) ?? [];
+  if (!total) throw new Error("No disk.");
+  return { diskUsed: Number(used) * 1024, diskTotal: Number(total) * 1024 };
+}
+async function machine() {
+  const cpu = { used: 0, total: 0 };
+  for (const { times } of cpus()) {
+    cpu.used += times.user + times.nice + times.sys + times.irq;
+    cpu.total += times.user + times.nice + times.sys + times.irq + times.idle;
+  }
+  if (process.platform !== "darwin")
+    return { scope: "machine", cpu, memUsed: totalmem() - freemem() };
+  const { stdout } = await run("/usr/bin/vm_stat", { timeout: EVERY_MS });
+  const pages = numberOf(stdout, "Pages active:") + numberOf(stdout, "Pages wired down:") + numberOf(stdout, "Pages occupied by compressor:");
+  return { scope: "machine", cpu, memUsed: pages * Number(/page size of (\d+)/.exec(stdout)?.[1]) };
+}
+async function cgroup() {
+  const read = (file2) => readFile2(`/sys/fs/cgroup/${file2}`, "utf8");
+  const [cpu, current, memory] = await Promise.all([
+    read("cpu.stat"),
+    read("memory.current"),
+    read("memory.stat")
+  ]);
+  return {
+    scope: "computer",
+    // No container has a limit, so the time there was is every CPU's.
+    cpu: {
+      used: numberOf(cpu, "usage_usec"),
+      total: performance.now() * 1e3 * availableParallelism()
+    },
+    // Less the files it has read and no longer uses, as `docker stats` counts it.
+    memUsed: Number(current) - numberOf(memory, "inactive_file")
+  };
+}
+var LoadLive = class {
+  #folder;
+  #contained;
+  #sockets = /* @__PURE__ */ new Set();
+  #timer;
+  #reading = false;
+  #before;
+  #last;
+  /**
+   * `folder` is on the disk that is reported. `contained` is whether the processes here are one
+   * computer's and nothing else's, as they are inside a container.
+   */
+  constructor(folder, contained) {
+    this.#folder = folder;
+    this.#contained = contained;
+  }
+  /** metrics@1: a reading every two seconds, the last one at once. What it sends is dropped. */
+  open(ws) {
+    this.#sockets.add(ws);
+    if (this.#last) ws.send(this.#last);
+    ws.on("close", () => {
+      this.#sockets.delete(ws);
+      if (this.#sockets.size === 0) this.close();
+    });
+    if (this.#timer) return;
+    this.#timer = setInterval(() => void this.#read(), EVERY_MS);
+    void this.#read();
+  }
+  close() {
+    clearInterval(this.#timer);
+    this.#timer = this.#before = this.#last = void 0;
+    for (const ws of this.#sockets) ws.close(1001, "It stopped.");
+  }
+  /** One at a time, and for the watching it began under: a reading taken too late is left. */
+  async #read() {
+    const timer = this.#timer;
+    if (this.#reading) return;
+    this.#reading = true;
+    try {
+      const sample = await (this.#contained ? cgroup().catch(machine) : machine());
+      const volume = await disk(this.#folder);
+      if (this.#timer !== timer) return;
+      const before = this.#before;
+      this.#before = sample.cpu;
+      if (!before) return;
+      const share = (sample.cpu.used - before.used) / (sample.cpu.total - before.total) || 0;
+      const reading = {
+        type: "reading",
+        scope: sample.scope,
+        cpuUsedPct: Math.round(Math.min(Math.max(share, 0), 1) * 1e3) / 10,
+        memUsed: sample.memUsed,
+        memTotal: totalmem(),
+        ...volume
+      };
+      if (!Number.isFinite(reading.cpuUsedPct + reading.memUsed)) return;
+      this.#last = JSON.stringify(reading);
+      for (const ws of this.#sockets) if (ws.bufferedAmount === 0) ws.send(this.#last);
+    } catch {
+    } finally {
+      this.#reading = false;
+    }
+  }
+};
+
 // src/store.ts
 import { createHash, randomBytes as randomBytes4, timingSafeEqual } from "node:crypto";
 import { chmodSync, mkdirSync, readFileSync as readFileSync2, renameSync, writeFileSync } from "node:fs";
@@ -67485,8 +67600,11 @@ var loadPty = () => {
 var ProcessRuntime = class {
   isolation = "none";
   #config;
-  constructor(config3) {
+  #contained;
+  /** `contained` is for inside a container, where load is the computer's own. */
+  constructor(config3, contained = false) {
     this.#config = config3;
+    this.#contained = contained;
   }
   async prepare() {
   }
@@ -67529,7 +67647,8 @@ var ProcessRuntime = class {
       browserLive = new BrowserLive(browser.endpoint);
       browser.gate = browserLive;
     }
-    const live = new Live(exec, spec.access, browserLive);
+    const load = new LoadLive(spec.workspace ?? folder, this.#contained);
+    const live = new Live(exec, spec.access, load, browserLive);
     const surfaces = live.surfaces();
     return {
       browserTools: browser?.tools ?? [],
@@ -67565,7 +67684,7 @@ async function serveInside(options) {
   if (!token) throw new Error(`${INNER_TOKEN_VARIABLE} is not set.`);
   delete process.env[INNER_TOKEN_VARIABLE];
   const digest = digestOf(token);
-  const running = new ProcessRuntime({ path: BROWSER, sandbox: false }).start(
+  const running = new ProcessRuntime({ path: BROWSER, sandbox: false }, true).start(
     {
       id: "inside",
       ...options,
@@ -67606,7 +67725,7 @@ async function serveInside(options) {
     socket.on("error", () => socket.destroy());
     const given = /^Bearer (\S+)$/.exec(request.headers.authorization ?? "")?.[1];
     const url3 = new URL(request.url ?? "/", "http://localhost");
-    const surface = /^\/live\/(terminal|files|browser)$/.exec(url3.pathname)?.[1];
+    const surface = /^\/live\/(terminal|files|browser|load)$/.exec(url3.pathname)?.[1];
     const mode = url3.searchParams.get("mode");
     if (!given || !sameToken(given, digest) || !surface || mode !== "watch" && mode !== "operate")
       return void socket.end("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
@@ -67621,7 +67740,7 @@ async function serveInside(options) {
 }
 
 // src/container.ts
-var run = promisify(execFile);
+var run2 = promisify2(execFile2);
 var START_MS2 = 6e4;
 var STOP_SECONDS = "5";
 var NOT_FORWARDED = /* @__PURE__ */ new Set([
@@ -67635,7 +67754,7 @@ var NOT_FORWARDED = /* @__PURE__ */ new Set([
 ]);
 async function docker(args, env = process.env) {
   try {
-    return (await run("docker", args, { env, maxBuffer: 16 * 1024 * 1024 })).stdout.trim();
+    return (await run2("docker", args, { env, maxBuffer: 16 * 1024 * 1024 })).stdout.trim();
   } catch (error62) {
     const { stderr, message } = error62;
     throw new Error(stderr?.trim() || message);
@@ -67853,7 +67972,7 @@ async function forward(url3, authorization, request, response) {
 }
 
 // src/handlers.ts
-var VERSION2 = "0.0.9";
+var VERSION2 = "0.0.10";
 function createHandlers(computers) {
   return {
     getInfo: async () => ({ version: VERSION2, isolation: computers.isolation }),
@@ -84816,7 +84935,7 @@ var OPENAPI = {
   "openapi": "3.1.0",
   "info": {
     "title": "AgentComputer",
-    "version": "0.0.9",
+    "version": "0.0.10",
     "description": "Computers for agents. This file is the source of truth: the HTTP API, the MCP control tools and the SDK are all generated from it. An operation with `x-mcp-tool` is also an MCP tool of that name.",
     "license": {
       "name": "Apache-2.0",
@@ -85137,7 +85256,7 @@ var OPENAPI = {
       "post": {
         "operationId": "createLiveSession",
         "x-mcp-tool": "computer_live",
-        "summary": "A one-time ticket to watch or operate one of its surfaces live: its terminals, its files, or its browser. Open its url as a WebSocket within 60 seconds.",
+        "summary": "A one-time ticket to watch or operate one of its surfaces live: its terminals, its files, its browser, or its load. Open its url as a WebSocket within 60 seconds.",
         "requestBody": {
           "required": true,
           "content": {
@@ -85478,9 +85597,10 @@ var OPENAPI = {
         "enum": [
           "terminal",
           "files",
-          "browser"
+          "browser",
+          "load"
         ],
-        "description": "terminal: every terminal on it, the agent's commands and a person's shells alike, on one socket in terminal@1: text messages are TerminalEvent one way and TerminalInput the other. Watching reads them all; operating also opens a shell, types into any of them, the agent's included, sizes and stops them. files: its workspace's files, in files@1: text messages are FilesRequest one way and FilesAnswer the other, and a file's bytes travel as binary messages of at most 1,048,576 bytes. Watching lists and reads; operating also writes, which a computer with read access doesn't offer. 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. Nobody waits for anybody: the agent's tools and a person's input act on the same browser at once. The page shown is each socket's own. A socket is shown each new tab as it opens, until it sends a tab input to show or open one; from then its page changes only when that page closes."
+        "description": "terminal: every terminal on it, the agent's commands and a person's shells alike, on one socket in terminal@1: text messages are TerminalEvent one way and TerminalInput the other. Watching reads them all; operating also opens a shell, types into any of them, the agent's included, sizes and stops them. files: its workspace's files, in files@1: text messages are FilesRequest one way and FilesAnswer the other, and a file's bytes travel as binary messages of at most 1,048,576 bytes. Watching lists and reads; operating also writes, which a computer with read access doesn't offer. 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. Nobody waits for anybody: the agent's tools and a person's input act on the same browser at once. The page shown is each socket's own. A socket is shown each new tab as it opens, until it sends a tab input to show or open one; from then its page changes only when that page closes. load: how busy it is, in metrics@1, to watch only: a LoadReading every two seconds while a socket is open, the first two seconds after the first socket opens, and the last one at once to a socket that opens later. One that can't be taken is left out, and a socket that hasn't read the one before is not sent the next. Nothing is read while nobody watches."
       },
       "LiveMode": {
         "type": "string",
@@ -86135,6 +86255,54 @@ var OPENAPI = {
           }
         ]
       },
+      "LoadReading": {
+        "description": "What the service sends on a metrics@1 socket, as JSON text. What a socket sends is dropped.",
+        "type": "object",
+        "required": [
+          "type",
+          "scope",
+          "cpuUsedPct",
+          "memUsed",
+          "memTotal",
+          "diskUsed",
+          "diskTotal"
+        ],
+        "properties": {
+          "type": {
+            "const": "reading"
+          },
+          "scope": {
+            "type": "string",
+            "enum": [
+              "computer",
+              "machine"
+            ],
+            "description": "Whose numbers these are. computer: this computer's own, which a container's are. machine: the whole machine's, which a computer with no isolation shares with whatever else runs there, so every computer of that service reads the same; and a container's where it can't read its own."
+          },
+          "cpuUsedPct": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 100,
+            "description": "Of all the machine's CPUs, since the reading before. One decimal."
+          },
+          "memUsed": {
+            "type": "integer",
+            "description": "Bytes in use."
+          },
+          "memTotal": {
+            "type": "integer",
+            "description": "Bytes the machine has: no computer has a limit."
+          },
+          "diskUsed": {
+            "type": "integer",
+            "description": "Bytes used on the volume its workspace is on, or its own folder where it has no workspace. The volume's, not the workspace's own size."
+          },
+          "diskTotal": {
+            "type": "integer",
+            "description": "Bytes on that volume."
+          }
+        }
+      },
       "FilesRequest": {
         "description": "What a socket sends on files@1, as JSON text. Each has an id of its own choosing, which the answer repeats; answers come as they are ready, in any order, and ids aren't checked for repeats. A request still unanswered when the socket closes gets no answer. A path is from the workspace, with / between its parts, or absolute inside it, and nothing outside the workspace is reached. A binary message that follows no write closes the socket, and so does any message over 1,048,576 bytes.",
         "oneOf": [
@@ -86989,9 +87157,10 @@ var OPERATIONS = [
                     "enum": [
                       "terminal",
                       "files",
-                      "browser"
+                      "browser",
+                      "load"
                     ],
-                    "description": "terminal: every terminal on it, the agent's commands and a person's shells alike, on one socket in terminal@1: text messages are TerminalEvent one way and TerminalInput the other. Watching reads them all; operating also opens a shell, types into any of them, the agent's included, sizes and stops them. files: its workspace's files, in files@1: text messages are FilesRequest one way and FilesAnswer the other, and a file's bytes travel as binary messages of at most 1,048,576 bytes. Watching lists and reads; operating also writes, which a computer with read access doesn't offer. 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. Nobody waits for anybody: the agent's tools and a person's input act on the same browser at once. The page shown is each socket's own. A socket is shown each new tab as it opens, until it sends a tab input to show or open one; from then its page changes only when that page closes."
+                    "description": "terminal: every terminal on it, the agent's commands and a person's shells alike, on one socket in terminal@1: text messages are TerminalEvent one way and TerminalInput the other. Watching reads them all; operating also opens a shell, types into any of them, the agent's included, sizes and stops them. files: its workspace's files, in files@1: text messages are FilesRequest one way and FilesAnswer the other, and a file's bytes travel as binary messages of at most 1,048,576 bytes. Watching lists and reads; operating also writes, which a computer with read access doesn't offer. 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. Nobody waits for anybody: the agent's tools and a person's input act on the same browser at once. The page shown is each socket's own. A socket is shown each new tab as it opens, until it sends a tab input to show or open one; from then its page changes only when that page closes. load: how busy it is, in metrics@1, to watch only: a LoadReading every two seconds while a socket is open, the first two seconds after the first socket opens, and the last one at once to a socket that opens later. One that can't be taken is left out, and a socket that hasn't read the one before is not sent the next. Nothing is read while nobody watches."
                   },
                   "protocol": {
                     "type": "string"
@@ -87507,7 +87676,7 @@ var OPERATIONS = [
     "method": "POST",
     "path": "/v1/computers/{computerID}/live",
     "tool": "computer_live",
-    "summary": "A one-time ticket to watch or operate one of its surfaces live: its terminals, its files, or its browser. Open its url as a WebSocket within 60 seconds.",
+    "summary": "A one-time ticket to watch or operate one of its surfaces live: its terminals, its files, its browser, or its load. Open its url as a WebSocket within 60 seconds.",
     "status": 201,
     "hasBody": true,
     "pathParameters": [
@@ -87528,9 +87697,10 @@ var OPERATIONS = [
           "enum": [
             "terminal",
             "files",
-            "browser"
+            "browser",
+            "load"
           ],
-          "description": "terminal: every terminal on it, the agent's commands and a person's shells alike, on one socket in terminal@1: text messages are TerminalEvent one way and TerminalInput the other. Watching reads them all; operating also opens a shell, types into any of them, the agent's included, sizes and stops them. files: its workspace's files, in files@1: text messages are FilesRequest one way and FilesAnswer the other, and a file's bytes travel as binary messages of at most 1,048,576 bytes. Watching lists and reads; operating also writes, which a computer with read access doesn't offer. 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. Nobody waits for anybody: the agent's tools and a person's input act on the same browser at once. The page shown is each socket's own. A socket is shown each new tab as it opens, until it sends a tab input to show or open one; from then its page changes only when that page closes."
+          "description": "terminal: every terminal on it, the agent's commands and a person's shells alike, on one socket in terminal@1: text messages are TerminalEvent one way and TerminalInput the other. Watching reads them all; operating also opens a shell, types into any of them, the agent's included, sizes and stops them. files: its workspace's files, in files@1: text messages are FilesRequest one way and FilesAnswer the other, and a file's bytes travel as binary messages of at most 1,048,576 bytes. Watching lists and reads; operating also writes, which a computer with read access doesn't offer. 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. Nobody waits for anybody: the agent's tools and a person's input act on the same browser at once. The page shown is each socket's own. A socket is shown each new tab as it opens, until it sends a tab input to show or open one; from then its page changes only when that page closes. load: how busy it is, in metrics@1, to watch only: a LoadReading every two seconds while a socket is open, the first two seconds after the first socket opens, and the last one at once to a socket that opens later. One that can't be taken is left out, and a socket that hasn't read the one before is not sent the next. Nothing is read while nobody watches."
         },
         "mode": {
           "allOf": [
@@ -87574,9 +87744,10 @@ var OPERATIONS = [
           "enum": [
             "terminal",
             "files",
-            "browser"
+            "browser",
+            "load"
           ],
-          "description": "terminal: every terminal on it, the agent's commands and a person's shells alike, on one socket in terminal@1: text messages are TerminalEvent one way and TerminalInput the other. Watching reads them all; operating also opens a shell, types into any of them, the agent's included, sizes and stops them. files: its workspace's files, in files@1: text messages are FilesRequest one way and FilesAnswer the other, and a file's bytes travel as binary messages of at most 1,048,576 bytes. Watching lists and reads; operating also writes, which a computer with read access doesn't offer. 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. Nobody waits for anybody: the agent's tools and a person's input act on the same browser at once. The page shown is each socket's own. A socket is shown each new tab as it opens, until it sends a tab input to show or open one; from then its page changes only when that page closes."
+          "description": "terminal: every terminal on it, the agent's commands and a person's shells alike, on one socket in terminal@1: text messages are TerminalEvent one way and TerminalInput the other. Watching reads them all; operating also opens a shell, types into any of them, the agent's included, sizes and stops them. files: its workspace's files, in files@1: text messages are FilesRequest one way and FilesAnswer the other, and a file's bytes travel as binary messages of at most 1,048,576 bytes. Watching lists and reads; operating also writes, which a computer with read access doesn't offer. 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. Nobody waits for anybody: the agent's tools and a person's input act on the same browser at once. The page shown is each socket's own. A socket is shown each new tab as it opens, until it sends a tab input to show or open one; from then its page changes only when that page closes. load: how busy it is, in metrics@1, to watch only: a LoadReading every two seconds while a socket is open, the first two seconds after the first socket opens, and the last one at once to a socket that opens later. One that can't be taken is left out, and a socket that hasn't read the one before is not sent the next. Nothing is read while nobody watches."
         },
         "mode": {
           "type": "string",
@@ -87682,7 +87853,7 @@ async function serve(options) {
     pattern: new RegExp(`^${operation.path.replace(/\{[^}]+\}/g, "([^/]+)")}$`),
     check: fromJsonSchema3(operation.input)
   }));
-  const run2 = async (route2, input2) => {
+  const run3 = async (route2, input2) => {
     const checked = await route2.check["~standard"].validate(input2);
     if (checked.issues)
       throw new ApiError(400, checked.issues.map((issue3) => issue3.message).join("; "));
@@ -87697,7 +87868,7 @@ async function serve(options) {
           { description: route2.operation.summary, inputSchema: route2.check },
           async (input2) => {
             try {
-              const output2 = await run2(route2, input2) ?? {};
+              const output2 = await run3(route2, input2) ?? {};
               return { content: [{ type: "text", text: JSON.stringify(output2) }] };
             } catch (error62) {
               if (!(error62 instanceof ApiError)) throw error62;
@@ -87749,7 +87920,7 @@ async function serve(options) {
         const value = url3.searchParams.get(name);
         if (value !== null) input2[name] = value;
       }
-      return send(response, operation.status, await run2(candidate, input2));
+      return send(response, operation.status, await run3(candidate, input2));
     }
     throw pathMatched ? new ApiError(405, "Not allowed.") : new ApiError(404, "Not found.");
   };
@@ -87836,7 +88007,7 @@ var USAGE = `Usage: agentcomputer <command> [--data DIR]
   stop <id>                         stop it, keeping its folder and token
   start <id> [--timeout SECONDS]    start a stopped computer again
   logs <id>                         what its servers wrote
-  live <id> --surface terminal|files|browser [--mode watch|operate]
+  live <id> --surface terminal|files|browser|load [--mode watch|operate]
                                     a one-time ticket to open one live, as a WebSocket
   kill <id>                         stop it and remove what the service made
 

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

@@ -146,7 +146,7 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** A one-time ticket to watch or operate one of its surfaces live: its terminals, its files, or its browser. Open its url as a WebSocket within 60 seconds. */
+        /** A one-time ticket to watch or operate one of its surfaces live: its terminals, its files, its browser, or its load. Open its url as a WebSocket within 60 seconds. */
         post: operations["createLiveSession"];
         delete?: never;
         options?: never;
@@ -248,10 +248,10 @@ export interface components {
             };
         };
         /**
-         * @description terminal: every terminal on it, the agent's commands and a person's shells alike, on one socket in terminal@1: text messages are TerminalEvent one way and TerminalInput the other. Watching reads them all; operating also opens a shell, types into any of them, the agent's included, sizes and stops them. files: its workspace's files, in files@1: text messages are FilesRequest one way and FilesAnswer the other, and a file's bytes travel as binary messages of at most 1,048,576 bytes. Watching lists and reads; operating also writes, which a computer with read access doesn't offer. 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. Nobody waits for anybody: the agent's tools and a person's input act on the same browser at once. The page shown is each socket's own. A socket is shown each new tab as it opens, until it sends a tab input to show or open one; from then its page changes only when that page closes.
+         * @description terminal: every terminal on it, the agent's commands and a person's shells alike, on one socket in terminal@1: text messages are TerminalEvent one way and TerminalInput the other. Watching reads them all; operating also opens a shell, types into any of them, the agent's included, sizes and stops them. files: its workspace's files, in files@1: text messages are FilesRequest one way and FilesAnswer the other, and a file's bytes travel as binary messages of at most 1,048,576 bytes. Watching lists and reads; operating also writes, which a computer with read access doesn't offer. 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. Nobody waits for anybody: the agent's tools and a person's input act on the same browser at once. The page shown is each socket's own. A socket is shown each new tab as it opens, until it sends a tab input to show or open one; from then its page changes only when that page closes. load: how busy it is, in metrics@1, to watch only: a LoadReading every two seconds while a socket is open, the first two seconds after the first socket opens, and the last one at once to a socket that opens later. One that can't be taken is left out, and a socket that hasn't read the one before is not sent the next. Nothing is read while nobody watches.
          * @enum {string}
          */
-        Surface: "terminal" | "files" | "browser";
+        Surface: "terminal" | "files" | "browser" | "load";
         /**
          * @description In watch you see and don't act: what you send is dropped, except that a files socket may still ask to list, to read and for what changed.
          * @enum {string}
@@ -433,6 +433,26 @@ export interface components {
             type: "stop";
             id: string;
         };
+        /** @description What the service sends on a metrics@1 socket, as JSON text. What a socket sends is dropped. */
+        LoadReading: {
+            /** @constant */
+            type: "reading";
+            /**
+             * @description Whose numbers these are. computer: this computer's own, which a container's are. machine: the whole machine's, which a computer with no isolation shares with whatever else runs there, so every computer of that service reads the same; and a container's where it can't read its own.
+             * @enum {string}
+             */
+            scope: "computer" | "machine";
+            /** @description Of all the machine's CPUs, since the reading before. One decimal. */
+            cpuUsedPct: number;
+            /** @description Bytes in use. */
+            memUsed: number;
+            /** @description Bytes the machine has: no computer has a limit. */
+            memTotal: number;
+            /** @description Bytes used on the volume its workspace is on, or its own folder where it has no workspace. The volume's, not the workspace's own size. */
+            diskUsed: number;
+            /** @description Bytes on that volume. */
+            diskTotal: number;
+        };
         /** @description What a socket sends on files@1, as JSON text. Each has an id of its own choosing, which the answer repeats; answers come as they are ready, in any order, and ids aren't checked for repeats. A request still unanswered when the socket closes gets no answer. A path is from the workspace, with / between its parts, or absolute inside it, and nothing outside the workspace is reached. A binary message that follows no write closes the socket, and so does any message over 1,048,576 bytes. */
         FilesRequest: {
             /** @constant */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentorg/computer",
-  "version": "0.0.9",
+  "version": "0.0.10",
   "description": "Computers for agents, as a service: a terminal, files and a browser over MCP",
   "license": "Apache-2.0",
   "repository": {