@agentorg/computer 0.0.10 → 0.0.12

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,27 @@ 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`                 |
 
+`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.
@@ -148,7 +164,7 @@ A computer at `--access terminal` has a surface you can open live, as a WebSocke
 A computer at `--access read` or above has another, and at `read` it is the only one:
 
 - **`files`** (protocol `files@1`): its workspace's files, for a file window. Text messages are JSON, and each request has an `id` of your choosing, which its answer repeats. `openapi.yaml` has each one's fields.
-  - **`list`** is answered with `entries`: a folder's entries with their kind, size and date, folders first, the first thousand.
+  - **`list`** is answered with `entries`: a folder's entries with their kind, size and date, folders first, the first thousand. With them come `path`, the folder as it was asked for, and `workspace`, what the workspace is called: its folder's own name, and nothing of where it is. The two together name the folder, `Research/src`; a workspace the service made is called `workspace`, and one at the top of a disk has an empty name. A computer in a container made before `workspace` was added sends none, and then `path` alone names the folder.
   - **`read`** is answered with `data` and then one binary message, a range of a file's bytes. A file larger than one range is read by asking again from where the last ended.
   - **`changed`** is answered with `changes`: the files modified after a time, the newest thousand, the newest first. It skips what `.gitignore` files ignore, `.git`, `node_modules` and links, and a file that was removed isn't one of them. Each one asked walks the workspace once, a computer walks for one at a time, and nothing is walked that wasn't asked for.
   - **`write`**, on an `operate` socket, puts a file there a part at a time, each followed at once by one binary message, its bytes. Nothing is at the path until the part marked `last`, which puts the file there whole and is answered with `written`; the parts before it are answered only if one is refused. It makes no folders, and nothing removes or renames a file. A file not finished when the socket closes is given up.
@@ -169,7 +185,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.6 (Apache-2.0)
 
 Apache License
                            Version 2.0, January 2004

package/dist/agentcomputer.js

@@ -3849,6 +3849,7 @@ 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 { 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";
@@ -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,7 +28159,8 @@ 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 { dirname as dirname3, join as join6 } from "node:path";
+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
 import { realpathSync } from "node:fs";
@@ -28915,11 +28917,11 @@ var require_ignore = __commonJS2({
         const rules = this._rules;
         const { length } = rules;
         const shortcut = this._basenameCount * 2 >= length;
-        const basename2 = shortcut ? basenameOf(path) : path;
+        const basename22 = shortcut ? basenameOf(path) : path;
         for (let index = length - 1; index >= 0; index--) {
           const rule = rules[index];
           if (rule[mode].test(
-            shortcut && rule._basenameOnly ? basename2 : path
+            shortcut && rule._basenameOnly ? basename22 : path
           )) {
             const { negative } = rule;
             const ret = {
@@ -31928,9 +31930,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;
@@ -66541,9 +66543,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",
@@ -66654,7 +66677,7 @@ function createServer2(root, sessions, version22, level) {
     );
   return server;
 }
-var VERSION = "0.0.5";
+var VERSION = "0.0.6";
 function createAgentExec(options) {
   const root = realpathSync(resolve3(options.workspace));
   const level = options.level ?? "read";
@@ -66671,9 +66694,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 +66732,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;
@@ -67117,33 +67188,26 @@ var BrowserLive = class {
   }
 };
 
-// node_modules/ws/wrapper.mjs
-var import_stream2 = __toESM(require_stream(), 1);
-var import_extension = __toESM(require_extension(), 1);
-var import_permessage_deflate = __toESM(require_permessage_deflate(), 1);
-var import_receiver = __toESM(require_receiver(), 1);
-var import_sender = __toESM(require_sender(), 1);
-var import_subprotocol = __toESM(require_subprotocol(), 1);
-var import_websocket = __toESM(require_websocket(), 1);
-var import_websocket_server = __toESM(require_websocket_server(), 1);
-
 // src/files-live.ts
 var MAX_PART = 1024 * 1024;
 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;
+  #workspace;
   #sockets = /* @__PURE__ */ new Set();
   /** One walk of the workspace at a time, however many ask. */
   #walking = Promise.resolve();
   /** How many files are part written, over every socket. */
   #uploads = 0;
-  constructor(files) {
+  /** `workspace` is what the workspace is called: its folder's own name, not where it is. */
+  constructor(files, workspace) {
     this.#files = files;
+    this.#workspace = workspace;
   }
   close() {
     for (const ws of this.#sockets) ws.close(1001, "It stopped.");
@@ -67213,7 +67277,13 @@ var FilesLive = class {
           const path = request.path ?? ".";
           if (!text2(path)) throw new Error("A path is text.");
           return inTurn(
-            async () => send2({ type: "entries", id, path, ...await this.#files.list(path) })
+            async () => send2({
+              type: "entries",
+              id,
+              workspace: this.#workspace,
+              path,
+              ...await this.#files.list(path)
+            })
           );
         }
         case "read": {
@@ -67243,7 +67313,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."
             );
@@ -67294,6 +67364,16 @@ var FilesLive = class {
   }
 };
 
+// node_modules/ws/wrapper.mjs
+var import_stream2 = __toESM(require_stream(), 1);
+var import_extension = __toESM(require_extension(), 1);
+var import_permessage_deflate = __toESM(require_permessage_deflate(), 1);
+var import_receiver = __toESM(require_receiver(), 1);
+var import_sender = __toESM(require_sender(), 1);
+var import_subprotocol = __toESM(require_subprotocol(), 1);
+var import_websocket = __toESM(require_websocket(), 1);
+var import_websocket_server = __toESM(require_websocket_server(), 1);
+
 // src/text.ts
 var MAX_TEXT = 1e4;
 function* pieces(text3, most = MAX_TEXT) {
@@ -67346,7 +67426,7 @@ var Live = class {
   /** Whether a person may write files here: not where the agent can only read them. */
   #writes;
   #load;
-  constructor(exec, access, load, browser) {
+  constructor(exec, access, load, files, browser) {
     this.#load = load;
     if (exec && access === "terminal") {
       this.#terminals = exec.terminals;
@@ -67354,7 +67434,7 @@ var Live = class {
         for (const message of messages(event)) for (const ws of this.#viewers) deliver(ws, message);
       });
     }
-    this.#files = exec && new FilesLive(exec.files);
+    this.#files = files;
     this.#writes = access !== "read";
     this.#browser = browser;
   }
@@ -67430,6 +67510,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) {
@@ -67468,6 +67549,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;
@@ -67501,28 +67594,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 {
@@ -67601,7 +67699,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;
@@ -67613,13 +67711,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) {
@@ -67647,8 +67759,8 @@ var ProcessRuntime = class {
       browserLive = new BrowserLive(browser.endpoint);
       browser.gate = browserLive;
     }
-    const load = new LoadLive(spec.workspace ?? folder, this.#contained);
-    const live = new Live(exec, spec.access, load, browserLive);
+    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 {
       browserTools: browser?.tools ?? [],
@@ -67678,6 +67790,8 @@ var ProcessRuntime = class {
 // src/inside.ts
 var INNER_PORT = 8e3;
 var INNER_TOKEN_VARIABLE = "AGENTCOMPUTER_INNER_TOKEN";
+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];
@@ -67688,7 +67802,11 @@ async function serveInside(options) {
     {
       id: "inside",
       ...options,
-      ...options.access === "none" ? {} : { workspace: "/workspace" }
+      ...options.access === "none" ? {} : { workspace: "/workspace" },
+      outside: {
+        workspace: process.env[OUTSIDE_WORKSPACE_VARIABLE],
+        machine: process.env[OUTSIDE_MACHINE_VARIABLE]
+      }
     },
     privateFolder(join7(homedir(), ".agentcomputer")),
     {
@@ -67799,6 +67917,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",
@@ -67813,9 +67935,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,
+        // 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 ? [
@@ -67828,7 +67949,7 @@ var ContainerRuntime = class {
         spec.access,
         ...spec.browser ? ["--browser"] : []
       ],
-      { ...process.env, [INNER_TOKEN_VARIABLE]: token }
+      { ...process.env, ...told }
     );
   }
   /** The token between the service and this container, which a restart has to find again. */
@@ -67972,7 +68093,7 @@ async function forward(url3, authorization, request, response) {
 }
 
 // src/handlers.ts
-var VERSION2 = "0.0.10";
+var VERSION2 = "0.0.12";
 function createHandlers(computers) {
   return {
     getInfo: async () => ({ version: VERSION2, isolation: computers.isolation }),
@@ -84613,10 +84734,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;
@@ -84715,7 +84838,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 ?? []
@@ -84935,7 +85058,7 @@ var OPENAPI = {
   "openapi": "3.1.0",
   "info": {
     "title": "AgentComputer",
-    "version": "0.0.10",
+    "version": "0.0.12",
     "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",
@@ -85387,7 +85510,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",
@@ -85600,7 +85723,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",
@@ -86442,8 +86565,13 @@ var OPENAPI = {
               "id": {
                 "type": "string"
               },
+              "workspace": {
+                "type": "string",
+                "description": "What the workspace is called: its folder's own name, and nothing of where it is. It comes with every entries answer, whichever folder was asked for, so that with path it names the folder. A computer in a container made before `workspace` was added sends none, and there path alone names the folder. It is `workspace` for a workspace the service made, and empty for one at the top of a disk."
+              },
               "path": {
-                "type": "string"
+                "type": "string",
+                "description": "The folder as it was asked for: `.` for the workspace itself."
               },
               "entries": {
                 "type": "array",
@@ -86772,7 +86900,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"
@@ -86861,7 +86989,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",
@@ -86931,7 +87059,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"
@@ -87071,7 +87199,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"
@@ -87160,7 +87288,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"
@@ -87302,7 +87430,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"
@@ -87426,7 +87554,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"
@@ -87555,7 +87683,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"
@@ -87700,7 +87828,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": [
@@ -87747,7 +87875,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";
@@ -487,6 +487,9 @@ export interface components {
             /** @constant */
             type: "entries";
             id: string;
+            /** @description What the workspace is called: its folder's own name, and nothing of where it is. It comes with every entries answer, whichever folder was asked for, so that with path it names the folder. A computer in a container made before `workspace` was added sends none, and there path alone names the folder. It is `workspace` for a workspace the service made, and empty for one at the top of a disk. */
+            workspace?: string;
+            /** @description The folder as it was asked for: `.` for the workspace itself. */
             path: string;
             entries: {
                 name: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentorg/computer",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "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.6",
     "@biomejs/biome": "2.6.5",
     "@modelcontextprotocol/client": "2.4.0",
     "@modelcontextprotocol/node": "2.1.2",