@agentorg/computer 0.0.11 → 0.0.13

package/README.md

@@ -22,7 +22,7 @@ That prints the computer's `computerID`, its endpoints and its `accessToken`, on
 `agentcomputer serve --isolation container` makes each computer a container of its own, which needs Docker on the same machine. The service follows your `DOCKER_HOST` or current context and never changes them.
 
 - The image holds AgentExec, Playwright MCP and a headless Chromium. It is `ghcr.io/uniac-ai/agentcomputer/computer` at the service's version; `--image` names another.
-- `--workspace` is mounted at `/workspace`, read-only at `--access read`, and nothing else of the machine is visible. Docker has to be able to share that folder. Without `--workspace`, the service makes one.
+- `--workspace` is mounted at `/workspace`, read-only at `--access read`, and nothing else of the machine is visible. The computer is told that folder's path on the machine and the machine's name, which `about` answers. Docker has to be able to share that folder. Without `--workspace`, the service makes one.
 - It runs as the user who started the service, with no capabilities.
 - `stop` stops the container and keeps it, so what was installed in it is there at `start`. `kill` removes it. Starting a stopped computer uses the image it was made from.
 
@@ -30,11 +30,29 @@ That prints the computer's `computerID`, its endpoints and its `accessToken`, on
 
 | `--access` | Tools at the `computer` endpoint                          |
 | ---------- | --------------------------------------------------------- |
-| `read`     | `read`, `list`, `search`                                  |
+| `read`     | `about`, `read`, `list`, `search`                         |
 | `files`    | Those, and `edit`                                         |
 | `terminal` | Those, and `exec_command`, `write_stdin`, `list_sessions` |
 | `none`     | No `computer` endpoint; needs `--browser`                 |
 
+`read` answers a text file as numbered lines, and a PNG, JPEG, GIF or WebP of up to 3 MiB as the picture itself: an image an MCP client can pass on to a model. The browser's `browser_take_screenshot` answers an image too, of whatever size it comes to: a `fullPage` one of a long page can be many megabytes. A container made by an earlier version keeps the program it was made with, and refuses a picture as a binary file until it is killed and made again.
+
+`about` tells the agent what a person looking at the computer reads. It takes nothing and answers JSON text, `{"rows": [...]}`, each row a `label` and a `value`, with `"path": true` on a value that is a path and `"caution": true` on one to be read as a caution; a row that is neither has neither. The rows come in this order:
+
+| `label`     | `value`                                                                                   |
+| ----------- | ----------------------------------------------------------------------------------------- |
+| `Where`     | The machine's own name                                                                    |
+| `Folder`    | The workspace's path on that machine, as a path                                           |
+| `Reaches`   | `Read-only files`, `Files`, or `Files and terminal`; with a browser, `, Browser` after it |
+| `Isolation` | `None: it acts as you`, as a caution, or `A container of its own`                         |
+| `CPU`       | Used, of all the machine's CPUs, as a whole percentage: `37%`                             |
+| `Memory`    | Used of the machine's total, counted in 1024s and written GB: `9.2 of 16 GB`              |
+| `Disk`      | Used of total, of the volume the workspace is on, counted in 1000s: `212 of 494 GB`       |
+
+- **In a container** the agent's commands find the folder somewhere else, so `Folder` says both and is not marked as a path: `/home/me/Research on the machine, mounted at /workspace in it`. CPU and Memory there are the computer's own; with no isolation they are the whole machine's.
+- **The last three** are a reading of its load taken over half a second when it is asked, in the same way the `load` surface reads. They come together, or not at all where a reading can't be taken.
+- **Not every computer has it.** One with no `computer` endpoint has no `about`. One in a container made by an earlier version keeps the program it was made with: `about` is listed among its tools and isn't there until it is killed and made again.
+
 The file tools stay inside the workspace. That's a check, not a boundary. Below `terminal`, the browser's `browser_run_code_unsafe` tool is hidden and refused, because it would otherwise be a terminal. The service enforces all of this, whatever the client does.
 
 `--browser` drives the Google Chrome installed on the machine, in a profile of the computer's own. `serve --browser-name` and `--browser-path` choose another. The browser has no debug port: a small host process starts it and shares it on a Unix socket in a folder only its user can enter, which the agent's tools and the live view both use. It lives as long as its computer does: a client that ends its session or goes away leaves the browser and its pages as they are, and the agent's `browser_close` is refused. Only an agent with `--access terminal` can stop it, with `browser_run_code_unsafe` or from its terminal.
@@ -169,7 +187,7 @@ 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.
+  - **Nothing depends on it.** Nothing is read while nobody watches or asks, 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`.
 

package/dist/THIRD_PARTY_LICENSES.txt

@@ -1,4 +1,4 @@
-@agentorg/exec 0.0.5 (Apache-2.0)
+@agentorg/exec 0.0.7 (Apache-2.0)
 
 Apache License
                            Version 2.0, January 2004

package/dist/agentcomputer.js

@@ -3268,7 +3268,7 @@ var require_stream = __commonJS({
       };
       duplex._final = function(callback) {
         if (ws.readyState === ws.CONNECTING) {
-          ws.once("open", function open4() {
+          ws.once("open", function open5() {
             duplex._final(callback);
           });
           return;
@@ -3289,7 +3289,7 @@ var require_stream = __commonJS({
       };
       duplex._write = function(chunk, encoding, callback) {
         if (ws.readyState === ws.CONNECTING) {
-          ws.once("open", function open4() {
+          ws.once("open", function open5() {
             duplex._write(chunk, encoding, callback);
           });
           return;
@@ -3849,7 +3849,8 @@ async function serveBrowserMcp(options) {
 import { execFile as execFile2, spawn as spawn3 } from "node:child_process";
 import { readFileSync as readFileSync3 } from "node:fs";
 import { connect } from "node:net";
-import { basename as basename3, join as join8 } from "node:path";
+import { hostname as hostname4 } from "node:os";
+import { join as join8 } from "node:path";
 import { createInterface as createInterface2 } from "node:readline";
 import { Readable as Readable3 } from "node:stream";
 import { promisify as promisify2 } from "node:util";
@@ -5806,9 +5807,9 @@ var asciiTabOrNewline = /[\t\n\r]/g;
 function stripTabAndNewline(value) {
   return value.replace(asciiTabOrNewline, "");
 }
-function urlHostnameOk(url3, hostname3) {
-  hostname3.lastIndex = 0;
-  return hostname3.test(url3.hostname);
+function urlHostnameOk(url3, hostname5) {
+  hostname5.lastIndex = 0;
+  return hostname5.test(url3.hostname);
 }
 function urlProtocolOk(url3, protocol) {
   protocol.lastIndex = 0;
@@ -24148,8 +24149,8 @@ function applyPostAuth(clientId, clientSecret, params) {
 function applyPublicAuth(clientId, params) {
   params.set("client_id", clientId);
 }
-function isLoopbackHost(hostname3) {
-  return hostname3 === "localhost" || hostname3.endsWith(".localhost") || hostname3 === "127.0.0.1" || hostname3 === "[::1]" || hostname3 === "::1";
+function isLoopbackHost(hostname5) {
+  return hostname5 === "localhost" || hostname5.endsWith(".localhost") || hostname5 === "127.0.0.1" || hostname5 === "[::1]" || hostname5 === "::1";
 }
 function assertSecureTokenEndpoint(tokenEndpoint) {
   const url3 = new URL(String(tokenEndpoint));
@@ -28158,6 +28159,7 @@ import { join as join7 } from "node:path";
 // src/runtime.ts
 import { chmodSync as chmodSync2, existsSync, statSync as statSync2 } from "node:fs";
 import { createRequire as createRequire3 } from "node:module";
+import { hostname as hostname3 } from "node:os";
 import { basename as basename2, dirname as dirname3, join as join6 } from "node:path";
 
 // node_modules/@agentorg/exec/dist/lib.js
@@ -28167,12 +28169,13 @@ import { STATUS_CODES, ServerResponse, createServer } from "node:http";
 import { Http2ServerRequest, constants } from "node:http2";
 import { Readable as Readable2 } from "node:stream";
 import { randomBytes as randomBytes3 } from "node:crypto";
-import { lstat as lstat2, open as open2, readdir as readdir2, rename as rename2, rm as rm2, stat as stat2 } from "node:fs/promises";
+import { lstat as lstat2, open as open3, readdir as readdir2, rename as rename2, rm as rm2, stat as stat2 } from "node:fs/promises";
 import { dirname as dirname2, join as join3 } from "node:path";
 import { randomBytes as randomBytes2 } from "node:crypto";
 import {
   chmod,
   lstat,
+  open as open2,
   readdir,
   readFile,
   realpath,
@@ -31928,9 +31931,9 @@ var asciiTabOrNewline2 = /[\t\n\r]/g;
 function stripTabAndNewline2(value) {
   return value.replace(asciiTabOrNewline2, "");
 }
-function urlHostnameOk2(url22, hostname3) {
-  hostname3.lastIndex = 0;
-  return hostname3.test(url22.hostname);
+function urlHostnameOk2(url22, hostname32) {
+  hostname32.lastIndex = 0;
+  return hostname32.test(url22.hostname);
 }
 function urlProtocolOk2(url22, protocol) {
   protocol.lastIndex = 0;
@@ -34316,7 +34319,7 @@ function bucketFor2(state, inst) {
   return bucket;
 }
 var handoff2;
-var open3 = [];
+var open4 = [];
 var memo3 = {
   alloc(_inst, payload, empty) {
     const bucket = handoff2;
@@ -34325,7 +34328,7 @@ var memo3 = {
     handoff2 = void 0;
     const entry = { value: empty, issues: null };
     bucket.set(payload.value, entry);
-    open3.push(entry);
+    open4.push(entry);
     return empty;
   },
   guard(inst) {
@@ -34396,10 +34399,10 @@ var memo3 = {
           return payload;
         }
         handoff2 = bucket;
-        const depth = open3.length;
+        const depth = open4.length;
         const result = base(payload, ctx);
         handoff2 = void 0;
-        const entry = open3.length > depth ? open3.pop() : void 0;
+        const entry = open4.length > depth ? open4.pop() : void 0;
         if (result instanceof Promise) {
           return result.then((r) => {
             if (entry)
@@ -66156,6 +66159,21 @@ var MAX_READ_CHARS = 28e3;
 var MAX_LINE_CHARS = 2e3;
 var MAX_ENTRIES = 1e3;
 var MAX_EDIT_BYTES = 8 * 1024 * 1024;
+var MAX_PICTURE_BYTES = 3 * 1024 * 1024;
+async function pictureKind(path) {
+  const file2 = await open2(path);
+  try {
+    const { buffer, bytesRead } = await file2.read(Buffer.alloc(12), 0, 12, 0);
+    const start = buffer.toString("latin1", 0, bytesRead);
+    if (start.startsWith("\x89PNG\r\n\n")) return "image/png";
+    if (start.startsWith("\xFF\xD8\xFF")) return "image/jpeg";
+    if (start.startsWith("GIF87a") || start.startsWith("GIF89a")) return "image/gif";
+    if (start.startsWith("RIFF") && start.slice(8) === "WEBP") return "image/webp";
+    return void 0;
+  } finally {
+    await file2.close();
+  }
+}
 var reason = (error62) => {
   const { code, path } = error62;
   if (code === "ENOENT") return `No such file or folder: ${path}`;
@@ -66211,9 +66229,19 @@ function createFiles(root) {
     return bytes.toString("utf8");
   };
   return {
-    /** Numbered lines of a file. */
+    /** Numbered lines of a file, or the file itself where it is a picture. */
     read: (input2) => refusing(async () => {
-      const lines = (await text22(await at(input2.path), input2.path)).split("\n");
+      const path = await at(input2.path);
+      const { size } = await aFile(path, input2.path);
+      const mimeType = await pictureKind(path);
+      if (mimeType) {
+        if (size > MAX_PICTURE_BYTES)
+          throw new ExecRefused(
+            `${input2.path} is too large to read as a picture: ${size.toLocaleString("en-US")} bytes, and the most is ${MAX_PICTURE_BYTES.toLocaleString("en-US")}.`
+          );
+        return { mimeType, bytes: await readFile(path) };
+      }
+      const lines = (await text22(path, input2.path)).split("\n");
       const first2 = Math.max(input2.offset ?? 1, 1);
       const shown = lines.slice(first2 - 1, first2 - 1 + (input2.limit ?? DEFAULT_LINES)).map((line, i) => `${first2 + i}	${cut(line, MAX_LINE_CHARS)}`);
       const last = first2 + shown.length - 1;
@@ -66423,7 +66451,7 @@ function createHostFiles(root, level) {
         throw new ExecRefused("A read starts at 0 or later and takes 1 to 1,048,576 bytes.");
       const real = await inside(root, path);
       const found = await aFile(real, path);
-      const file2 = await open2(real, "r");
+      const file2 = await open3(real, "r");
       try {
         const bytes = Buffer.alloc(Math.max(0, Math.min(length, found.size - offset)));
         const { bytesRead } = await file2.read(bytes, 0, bytes.length, offset);
@@ -66452,7 +66480,7 @@ function createHostFiles(root, level) {
       if (before?.isDirectory()) throw new ExecRefused(`${path} is a folder.`);
       await stat2(dirname2(target));
       const temporary = join3(dirname2(target), `.agentexec-${randomBytes3(6).toString("hex")}`);
-      const file2 = await open2(temporary, "wx");
+      const file2 = await open3(temporary, "wx");
       const discard = async () => {
         await file2.close().catch(() => {
         });
@@ -66525,6 +66553,12 @@ var answering = async (work) => {
     return refused(error62);
   }
 };
+var pictured = (path, { mimeType, bytes }) => ({
+  content: [
+    { type: "text", text: `${path}: ${mimeType}` },
+    { type: "image", mimeType, data: bytes.toString("base64") }
+  ]
+});
 var saying = async (work) => {
   try {
     return text(await work());
@@ -66541,9 +66575,30 @@ var Answered = {
 var YieldTime = external_exports.number().int().positive().optional();
 var MaxTokens = external_exports.number().int().positive().optional();
 var READ_ONLY = { readOnlyHint: true };
-function createServer2(root, sessions, version22, level) {
+var TOOLS = [
+  "exec_command",
+  "write_stdin",
+  "list_sessions",
+  "read",
+  "list",
+  "search",
+  "edit"
+];
+function createServer2(root, sessions, version22, level, extraTools = []) {
   const server = new McpServer({ name: "agentexec", version: version22 });
   const files = createFiles(root);
+  for (const { name, description, readOnly, call } of extraTools)
+    server.registerTool(
+      name,
+      { description, ...readOnly ? { annotations: READ_ONLY } : {} },
+      async () => {
+        try {
+          return text(String(await call()));
+        } catch (error62) {
+          return { isError: true, ...text(error62 instanceof Error ? error62.message : String(error62)) };
+        }
+      }
+    );
   if (level === "terminal") {
     server.registerTool(
       "exec_command",
@@ -66603,7 +66658,7 @@ function createServer2(root, sessions, version22, level) {
   server.registerTool(
     "read",
     {
-      description: "Reads a text file as numbered lines.",
+      description: "Reads a text file as numbered lines, or shows a PNG, JPEG, GIF or WebP of up to 3 MiB as an image; offset and limit are for text.",
       inputSchema: {
         path: external_exports.string().min(1).describe("Inside the workspace; relative to it, or absolute."),
         offset: external_exports.number().int().positive().optional().describe("The first line, from 1."),
@@ -66611,7 +66666,14 @@ function createServer2(root, sessions, version22, level) {
       },
       annotations: READ_ONLY
     },
-    (input2) => saying(() => files.read(input2))
+    async (input2) => {
+      try {
+        const read = await files.read(input2);
+        return typeof read === "string" ? text(read) : pictured(input2.path, read);
+      } catch (error62) {
+        return refused(error62);
+      }
+    }
   );
   server.registerTool(
     "list",
@@ -66654,7 +66716,7 @@ function createServer2(root, sessions, version22, level) {
     );
   return server;
 }
-var VERSION = "0.0.5";
+var VERSION = "0.0.7";
 function createAgentExec(options) {
   const root = realpathSync(resolve3(options.workspace));
   const level = options.level ?? "read";
@@ -66671,9 +66733,15 @@ function createAgentExec(options) {
     options.pty
   );
   const host = createHostFiles(root, level);
+  const extraTools = [...options.extraTools ?? []];
+  const names = new Set(TOOLS);
+  for (const { name } of extraTools) {
+    if (names.has(name)) throw new Error(`There is already a tool called ${name}.`);
+    names.add(name);
+  }
   return {
     async handle(request, response, body) {
-      const server = createServer2(root, sessions, VERSION, level);
+      const server = createServer2(root, sessions, VERSION, level, extraTools);
       const transport = new NodeStreamableHTTPServerTransport({ sessionIdGenerator: void 0 });
       response.once("close", () => {
         void transport.close();
@@ -66703,6 +66771,48 @@ function createAgentExec(options) {
   };
 }
 
+// src/about.ts
+var REACHES = {
+  read: "Read-only files",
+  files: "Files",
+  terminal: "Files and terminal"
+};
+var GIB = 1024 ** 3;
+var GB = 1e3 ** 3;
+var tenths = (count) => String(Math.round(count * 10) / 10);
+var whole = (count) => String(Math.round(count));
+function aboutTool(facts, load) {
+  return {
+    name: "about",
+    description: 'What this computer is, in the words a person looking at it reads: where it is, its folder, what it reaches, how it is isolated and how loaded it is. Takes nothing. Answers JSON text: {"rows": [{"label": "Where", "value": "..."}]}, with "path": true on a value that is a path and "caution": true on one to be read as a caution.',
+    readOnly: true,
+    async call() {
+      const { outside, inside: inside2 } = facts.workspace;
+      const rows = [
+        { label: "Where", value: facts.machine },
+        // In a container its commands find the folder somewhere else, so the row says both.
+        inside2 === outside ? { label: "Folder", value: outside, path: true } : { label: "Folder", value: `${outside} on the machine, mounted at ${inside2} in it` },
+        { label: "Reaches", value: REACHES[facts.access] + (facts.browser ? ", Browser" : "") },
+        facts.contained ? { label: "Isolation", value: "A container of its own" } : { label: "Isolation", value: "None: it acts as you", caution: true }
+      ];
+      const reading = await load.now();
+      if (reading)
+        rows.push(
+          { label: "CPU", value: `${whole(reading.cpuUsedPct)}%` },
+          {
+            label: "Memory",
+            value: `${tenths(reading.memUsed / GIB)} of ${tenths(reading.memTotal / GIB)} GB`
+          },
+          {
+            label: "Disk",
+            value: `${whole(reading.diskUsed / GB)} of ${whole(reading.diskTotal / GB)} GB`
+          }
+        );
+      return JSON.stringify({ rows });
+    }
+  };
+}
+
 // src/screencast.ts
 var FIRST_FRAME_MS = 500;
 var RESTARTS = 3;
@@ -67123,7 +67233,7 @@ var MAX_BUFFERED2 = 4 * 1024 * 1024;
 var MAX_UPLOADS = 64;
 var reason2 = (error62) => error62 instanceof Error ? error62.message : String(error62);
 var text2 = (value) => typeof value === "string";
-var whole = (value) => Number.isSafeInteger(value);
+var whole2 = (value) => Number.isSafeInteger(value);
 var sleep4 = (ms) => new Promise((done) => setTimeout(done, ms));
 var FilesLive = class {
   #files;
@@ -67242,7 +67352,7 @@ var FilesLive = class {
           awaited = "refused";
           if (mode !== "operate") throw new Error("This socket watches: it can't write.");
           const { path, offset, length, last } = request;
-          if (!text2(path) || !whole(offset) || offset < 0 || !whole(length) || length < 0 || length > MAX_PART || typeof last !== "boolean")
+          if (!text2(path) || !whole2(offset) || offset < 0 || !whole2(length) || length < 0 || length > MAX_PART || typeof last !== "boolean")
             throw new Error(
               "A write names a path, where it starts, 0 to 1,048,576 bytes, and last."
             );
@@ -67439,6 +67549,7 @@ 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 ONCE_MS = 500;
 var run = promisify(execFile);
 var numberOf = (text3, name) => Number(new RegExp(`^${name}\\s+(\\d+)`, "m").exec(text3)?.[1]);
 async function disk(folder) {
@@ -67477,6 +67588,18 @@ async function cgroup() {
     memUsed: Number(current) - numberOf(memory, "inactive_file")
   };
 }
+function readingOf(before, sample, volume) {
+  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
+  };
+  return Number.isFinite(reading.cpuUsedPct + reading.memUsed) ? reading : void 0;
+}
 var LoadLive = class {
   #folder;
   #contained;
@@ -67510,28 +67633,33 @@ var LoadLive = class {
     this.#timer = this.#before = this.#last = void 0;
     for (const ws of this.#sockets) ws.close(1001, "It stopped.");
   }
+  /** Its own, inside a container that can read it; else the machine's. */
+  #sample() {
+    return this.#contained ? cgroup().catch(machine) : machine();
+  }
+  /** One reading for whoever asks once, taken over half a second. None where it can't be. */
+  async now() {
+    try {
+      const before = await this.#sample();
+      await new Promise((done) => setTimeout(done, ONCE_MS));
+      return readingOf(before.cpu, await this.#sample(), await disk(this.#folder));
+    } catch {
+      return void 0;
+    }
+  }
   /** 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 sample = await this.#sample();
       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;
+      const reading = before && readingOf(before, sample, volume);
+      if (!reading) return;
       this.#last = JSON.stringify(reading);
       for (const ws of this.#sockets) if (ws.bufferedAmount === 0) ws.send(this.#last);
     } catch {
@@ -67610,7 +67738,7 @@ var ProcessRuntime = class {
   isolation = "none";
   #config;
   #contained;
-  /** `contained` is for inside a container, where load is the computer's own. */
+  /** `contained` is for inside a container, where the computer and its load are its own. */
   constructor(config3, contained = false) {
     this.#config = config3;
     this.#contained = contained;
@@ -67622,13 +67750,27 @@ var ProcessRuntime = class {
   async remove() {
   }
   async start(spec, folder, events) {
+    const load = new LoadLive(spec.workspace ?? folder, this.#contained);
     let exec;
-    if (spec.access !== "none")
+    if (spec.access !== "none") {
+      const workspace = spec.workspace;
+      const about = aboutTool(
+        {
+          machine: spec.outside?.machine ?? hostname3(),
+          workspace: { outside: spec.outside?.workspace ?? workspace, inside: workspace },
+          access: spec.access,
+          browser: spec.browser,
+          contained: this.#contained
+        },
+        load
+      );
       exec = createAgentExec({
-        workspace: spec.workspace,
+        workspace,
         level: spec.access,
-        pty: await loadPty()
+        pty: await loadPty(),
+        extraTools: [about]
       });
+    }
     let browser;
     let browserDown = false;
     if (spec.browser) {
@@ -67656,8 +67798,7 @@ var ProcessRuntime = class {
       browserLive = new BrowserLive(browser.endpoint);
       browser.gate = browserLive;
     }
-    const load = new LoadLive(spec.workspace ?? folder, this.#contained);
-    const files = exec && new FilesLive(exec.files, spec.workspaceName ?? basename2(spec.workspace));
+    const files = exec && new FilesLive(exec.files, basename2(spec.outside?.workspace ?? spec.workspace));
     const live = new Live(exec, spec.access, load, files, browserLive);
     const surfaces = live.surfaces();
     return {
@@ -67688,7 +67829,8 @@ var ProcessRuntime = class {
 // src/inside.ts
 var INNER_PORT = 8e3;
 var INNER_TOKEN_VARIABLE = "AGENTCOMPUTER_INNER_TOKEN";
-var WORKSPACE_NAME_VARIABLE = "AGENTCOMPUTER_WORKSPACE_NAME";
+var OUTSIDE_WORKSPACE_VARIABLE = "AGENTCOMPUTER_OUTSIDE_WORKSPACE";
+var OUTSIDE_MACHINE_VARIABLE = "AGENTCOMPUTER_OUTSIDE_MACHINE";
 var BROWSER = "/opt/browsers/headless-shell";
 async function serveInside(options) {
   const token = process.env[INNER_TOKEN_VARIABLE];
@@ -67699,7 +67841,11 @@ async function serveInside(options) {
     {
       id: "inside",
       ...options,
-      ...options.access === "none" ? {} : { workspace: "/workspace", workspaceName: process.env[WORKSPACE_NAME_VARIABLE] }
+      ...options.access === "none" ? {} : { workspace: "/workspace" },
+      outside: {
+        workspace: process.env[OUTSIDE_WORKSPACE_VARIABLE],
+        machine: process.env[OUTSIDE_MACHINE_VARIABLE]
+      }
     },
     privateFolder(join7(homedir(), ".agentcomputer")),
     {
@@ -67810,6 +67956,10 @@ var ContainerRuntime = class {
   }
   async #create(name, spec, token) {
     const uid = process.getuid?.();
+    const told = {
+      [INNER_TOKEN_VARIABLE]: token,
+      ...spec.workspace ? { [OUTSIDE_WORKSPACE_VARIABLE]: spec.workspace, [OUTSIDE_MACHINE_VARIABLE]: hostname4() } : {}
+    };
     await docker(
       [
         "create",
@@ -67824,12 +67974,8 @@ var ContainerRuntime = class {
         "no-new-privileges",
         "--publish",
         `127.0.0.1::${INNER_PORT}`,
-        // By name, so the value stays out of the command line other users can see.
-        "--env",
-        INNER_TOKEN_VARIABLE,
-        // What its workspace is called, which in there is only /workspace. An image from before
-        // this was told leaves it.
-        ...spec.workspace ? ["--env", WORKSPACE_NAME_VARIABLE] : [],
+        // By name, so the values stay out of the command line other users can see.
+        ...Object.keys(told).flatMap((name2) => ["--env", name2]),
         // Files it writes in the workspace belong to whoever runs the service.
         ...uid ? ["--user", `${uid}:${process.getgid?.()}`] : [],
         ...spec.workspace ? [
@@ -67842,11 +67988,7 @@ var ContainerRuntime = class {
         spec.access,
         ...spec.browser ? ["--browser"] : []
       ],
-      {
-        ...process.env,
-        [INNER_TOKEN_VARIABLE]: token,
-        ...spec.workspace ? { [WORKSPACE_NAME_VARIABLE]: basename3(spec.workspace) } : {}
-      }
+      { ...process.env, ...told }
     );
   }
   /** The token between the service and this container, which a restart has to find again. */
@@ -67990,7 +68132,7 @@ async function forward(url3, authorization, request, response) {
 }
 
 // src/handlers.ts
-var VERSION2 = "0.0.11";
+var VERSION2 = "0.0.13";
 function createHandlers(computers) {
   return {
     getInfo: async () => ({ version: VERSION2, isolation: computers.isolation }),
@@ -68574,8 +68716,8 @@ async function openLive(session, onMessage) {
 }
 var Terminals = class {
   #open;
-  constructor(open4) {
-    this.#open = open4;
+  constructor(open5) {
+    this.#open = open5;
   }
   /**
    * Each terminal as it starts, writes and exits: those already there first, each with the end of
@@ -84631,10 +84773,12 @@ var NodeStreamableHTTPServerTransport2 = class {
 import { randomBytes as randomBytes5 } from "node:crypto";
 import { appendFileSync, existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync4, rmSync as rmSync2, statSync as statSync3 } from "node:fs";
 import { isAbsolute, join as join9, resolve as resolve4 } from "node:path";
-var TOOLS = {
-  read: ["read", "list", "search"],
-  files: ["read", "list", "search", "edit"],
-  terminal: ["read", "list", "search", "edit", "exec_command", "write_stdin", "list_sessions"]
+var READ = ["about", "read", "list", "search"];
+var FILES = [...READ, "edit"];
+var TOOLS2 = {
+  read: READ,
+  files: FILES,
+  terminal: [...FILES, "exec_command", "write_stdin", "list_sessions"]
 };
 var MAX_LOG = 256 * 1024;
 var MAX_TIMER_S = 2e6;
@@ -84733,7 +84877,7 @@ var Computers = class {
       ...this.#describe(stored),
       uptimeSeconds: stored.state === "running" ? Math.round((Date.now() - Date.parse(stored.startedAt)) / 1e3) : 0,
       tools: {
-        computer: stored.access === "none" ? [] : TOOLS[stored.access],
+        computer: stored.access === "none" ? [] : TOOLS2[stored.access],
         browser: live?.running?.browserTools ?? []
       },
       surfaces: live?.running?.surfaces ?? []
@@ -84953,7 +85097,7 @@ var OPENAPI = {
   "openapi": "3.1.0",
   "info": {
     "title": "AgentComputer",
-    "version": "0.0.11",
+    "version": "0.0.13",
     "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",
@@ -85405,7 +85549,7 @@ var OPENAPI = {
           "files",
           "terminal"
         ],
-        "description": "How far it reaches into files and commands, each level containing the one before: `read` has read, list and search; `files` adds edit; `terminal` adds exec_command, write_stdin and list_sessions. Below terminal, the browser's code-running tool is hidden."
+        "description": "How far it reaches into files and commands, each level containing the one before: `read` has about, read, list and search; `files` adds edit; `terminal` adds exec_command, write_stdin and list_sessions. Below terminal, the browser's code-running tool is hidden."
       },
       "ComputerState": {
         "type": "string",
@@ -85618,7 +85762,7 @@ var OPENAPI = {
           "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. 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."
+        "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 or asks."
       },
       "LiveMode": {
         "type": "string",
@@ -86795,7 +86939,7 @@ var OPERATIONS = [
               "files",
               "terminal"
             ],
-            "description": "How far it reaches into files and commands, each level containing the one before: `read` has read, list and search; `files` adds edit; `terminal` adds exec_command, write_stdin and list_sessions. Below terminal, the browser's code-running tool is hidden."
+            "description": "How far it reaches into files and commands, each level containing the one before: `read` has about, read, list and search; `files` adds edit; `terminal` adds exec_command, write_stdin and list_sessions. Below terminal, the browser's code-running tool is hidden."
           },
           "browser": {
             "type": "boolean"
@@ -86884,7 +87028,7 @@ var OPERATIONS = [
             "files",
             "terminal"
           ],
-          "description": "How far it reaches into files and commands, each level containing the one before: `read` has read, list and search; `files` adds edit; `terminal` adds exec_command, write_stdin and list_sessions. Below terminal, the browser's code-running tool is hidden."
+          "description": "How far it reaches into files and commands, each level containing the one before: `read` has about, read, list and search; `files` adds edit; `terminal` adds exec_command, write_stdin and list_sessions. Below terminal, the browser's code-running tool is hidden."
         },
         "browser": {
           "type": "boolean",
@@ -86954,7 +87098,7 @@ var OPERATIONS = [
                 "files",
                 "terminal"
               ],
-              "description": "How far it reaches into files and commands, each level containing the one before: `read` has read, list and search; `files` adds edit; `terminal` adds exec_command, write_stdin and list_sessions. Below terminal, the browser's code-running tool is hidden."
+              "description": "How far it reaches into files and commands, each level containing the one before: `read` has about, read, list and search; `files` adds edit; `terminal` adds exec_command, write_stdin and list_sessions. Below terminal, the browser's code-running tool is hidden."
             },
             "browser": {
               "type": "boolean"
@@ -87094,7 +87238,7 @@ var OPERATIONS = [
                 "files",
                 "terminal"
               ],
-              "description": "How far it reaches into files and commands, each level containing the one before: `read` has read, list and search; `files` adds edit; `terminal` adds exec_command, write_stdin and list_sessions. Below terminal, the browser's code-running tool is hidden."
+              "description": "How far it reaches into files and commands, each level containing the one before: `read` has about, read, list and search; `files` adds edit; `terminal` adds exec_command, write_stdin and list_sessions. Below terminal, the browser's code-running tool is hidden."
             },
             "browser": {
               "type": "boolean"
@@ -87183,7 +87327,7 @@ var OPERATIONS = [
                       "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. 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."
+                    "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 or asks."
                   },
                   "protocol": {
                     "type": "string"
@@ -87325,7 +87469,7 @@ var OPERATIONS = [
             "files",
             "terminal"
           ],
-          "description": "How far it reaches into files and commands, each level containing the one before: `read` has read, list and search; `files` adds edit; `terminal` adds exec_command, write_stdin and list_sessions. Below terminal, the browser's code-running tool is hidden."
+          "description": "How far it reaches into files and commands, each level containing the one before: `read` has about, read, list and search; `files` adds edit; `terminal` adds exec_command, write_stdin and list_sessions. Below terminal, the browser's code-running tool is hidden."
         },
         "browser": {
           "type": "boolean"
@@ -87449,7 +87593,7 @@ var OPERATIONS = [
             "files",
             "terminal"
           ],
-          "description": "How far it reaches into files and commands, each level containing the one before: `read` has read, list and search; `files` adds edit; `terminal` adds exec_command, write_stdin and list_sessions. Below terminal, the browser's code-running tool is hidden."
+          "description": "How far it reaches into files and commands, each level containing the one before: `read` has about, read, list and search; `files` adds edit; `terminal` adds exec_command, write_stdin and list_sessions. Below terminal, the browser's code-running tool is hidden."
         },
         "browser": {
           "type": "boolean"
@@ -87578,7 +87722,7 @@ var OPERATIONS = [
             "files",
             "terminal"
           ],
-          "description": "How far it reaches into files and commands, each level containing the one before: `read` has read, list and search; `files` adds edit; `terminal` adds exec_command, write_stdin and list_sessions. Below terminal, the browser's code-running tool is hidden."
+          "description": "How far it reaches into files and commands, each level containing the one before: `read` has about, read, list and search; `files` adds edit; `terminal` adds exec_command, write_stdin and list_sessions. Below terminal, the browser's code-running tool is hidden."
         },
         "browser": {
           "type": "boolean"
@@ -87723,7 +87867,7 @@ var OPERATIONS = [
             "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. 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."
+          "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 or asks."
         },
         "mode": {
           "allOf": [
@@ -87770,7 +87914,7 @@ var OPERATIONS = [
             "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. 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."
+          "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 or asks."
         },
         "mode": {
           "type": "string",

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

@@ -182,7 +182,7 @@ export interface components {
             message: string;
         };
         /**
-         * @description How far it reaches into files and commands, each level containing the one before: `read` has read, list and search; `files` adds edit; `terminal` adds exec_command, write_stdin and list_sessions. Below terminal, the browser's code-running tool is hidden.
+         * @description How far it reaches into files and commands, each level containing the one before: `read` has about, read, list and search; `files` adds edit; `terminal` adds exec_command, write_stdin and list_sessions. Below terminal, the browser's code-running tool is hidden.
          * @enum {string}
          */
         Access: "none" | "read" | "files" | "terminal";
@@ -248,7 +248,7 @@ 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. 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.
+         * @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 or asks.
          * @enum {string}
          */
         Surface: "terminal" | "files" | "browser" | "load";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentorg/computer",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "description": "Computers for agents, as a service: a terminal, files and a browser over MCP",
   "license": "Apache-2.0",
   "repository": {
@@ -31,7 +31,7 @@
     "playwright-core": "1.65.0-alpha-2026-10-30"
   },
   "devDependencies": {
-    "@agentorg/exec": "0.0.5",
+    "@agentorg/exec": "0.0.7",
     "@biomejs/biome": "2.6.5",
     "@modelcontextprotocol/client": "2.4.0",
     "@modelcontextprotocol/node": "2.1.2",