@agentorg/computer 0.0.21 → 0.0.22

package/README.md

@@ -26,7 +26,7 @@ That gives an agent this computer instead: the machine the service runs on, whol
 Each computer is this computer, attached with `attach`, or one made in a container of its own with `create`. A service started with `serve --lend` only lends this computer: it makes nothing, `info.made` is empty, and `create` is refused with 409. It listens only on loopback, as this computer is offered only there, and a container it finds in its data folder from before can't be started or removed until a service without `--lend` has the folder. A container needs Docker on the service's machine. The service follows your `DOCKER_HOST` or current context and never changes them, and comes up without Docker.
 
 - **`info` says what the service offers**, each part ready or not and why, in a line a person reads:
-  - `thisComputer`: its capabilities (`about`, `terminal`, `files` and `screen`) and the browsers that can go with it. The screen is ready where Cua Driver is installed and granted.
+  - `thisComputer`: its capabilities (`about`, `terminal`, `files` and `screen`) and the browsers that can go with it. The screen is ready where Cua Driver is installed and granted. A reading more than 10 seconds old is checked again before `info` answers, waited for up to a second, while the rest is read; a check that takes longer is answered the next time. One the person switched off isn't checked.
   - `made`, each kind it makes: today a container, ready while Docker answers, with its capabilities and browsers.
 - **A container is refused with 409 where Docker doesn't answer:** `A container needs Docker, which isn't answering on this machine.` One already made isn't started there, and isn't killed there either, since its container couldn't be removed: both are refused with the same words, and it is kept.
 - **A computer with no isolation is no longer made.** `create --isolation none` is refused with 400, and `attach` is what does that now.
@@ -58,6 +58,11 @@ This computer:
   - Once a grant changes, the app restarts its driver, which reads grants once. That ends the connections of computers using the screen, which then say Cua Driver has stopped.
 - **What the service starts of Cua Driver sends no telemetry and checks for no updates,** so no update notice reaches a computer's log. The person's own Cua Driver app follows its own settings: `cua-driver telemetry disable` turns its telemetry off.
 
+**Upgrading from 0.0.21:**
+
+- **An agent's command keeps it acting on its terminal until the command ends,** and 10 seconds after, in `presence` and `GET /v1/acting`, where it was counted for 10 seconds from the command's start. One left running keeps it there, and its `at` can be older than 10 seconds: take the list as it is sent, and drop no one by their `at`.
+- **Asking for a screen grant opens no pane of System Settings.** `POST /v1/setup/screen/ask` makes the request alone. A client that relied on the pane opening calls `POST /v1/setup/screen/settings` with the grant, on the person's own choice, such as a button they press.
+
 **Upgrading from 0.0.20:**
 
 - **Commands on this computer no longer get the service's own `AGENTCOMPUTER_` variables,** such as `AGENTCOMPUTER_API_KEY` where the shell that started the service held it. A command that read one should be given what it needs another way.
@@ -187,6 +192,7 @@ The data folder is `--data`, else `$AGENTCOMPUTER_DATA`, else `$XDG_DATA_HOME/ag
 | `GET /v1/setup`                           |                        |
 | `PUT /v1/setup/{capability}`              |                        |
 | `POST /v1/setup/{capability}/ask`         |                        |
+| `POST /v1/setup/{capability}/settings`    |                        |
 
 These take the control token, kept in the data folder. A computer's own endpoints take its `accessToken`, and neither token works for the other:
 
@@ -211,10 +217,11 @@ These take the control token, kept in the data folder. A computer's own endpoint
   - The screen needs Cua Driver, and on macOS its `screen-recording` and `accessibility` grants, each `granted`, `not-granted` or `unknown`; it is ready once both are granted. While Cua Driver isn't installed, the one item is `{ "need": "install", "state": "missing" }`. `holder` names whom System Settings lists the grants under: the outermost app Cua Driver is inside, CuaDriver for its own app, or an app that carries the driver.
   - The browser lists Chrome, then Edge, each `on` (open, with remote debugging on), `off`, or `missing` (not installed); a service given one browser's folder, with `--own-browser-data`, lists just that one as `named`. It is ready with one on. With both on, the agent's is Chrome.
 - **`POST /v1/setup/{capability}/ask`**, with `{ "need": "..." }` or no body, asks the person, on the service's machine, macOS only, for one thing the part needs, or for everything it is missing. It answers once the steps have started, with each part then:
-  - `screen-recording` or `accessibility`, while it is missing: Cua Driver's own grant, its app started first, through the system, so the Mac names that app. Cua Driver asks in its own order, Accessibility first. For a driver an app hosts, the app asks, for that grant alone. Then, missing or not, that grant's own pane in System Settings opens.
+  - `screen-recording` or `accessibility`, while it is missing: Cua Driver's own grant, its app started first, through the system, so the Mac names that app. Cua Driver asks in its own order, Accessibility first. For a driver an app hosts, the app asks, for that grant alone, in its own way. The service opens no pane of System Settings. macOS shows each request once: once it has been answered, asking again shows nothing and answers the same, so a client offers `settings` while a grant stays `not-granted`.
   - `chrome` or `edge`: that browser opens at its inspect page, where remote debugging is switched on. One the service was given only the folder of, the person opens themselves.
   - With none named: the screen's grant while either is missing; the first browser installed, Chrome before Edge, while none is on.
   - What the part doesn't need, a browser that isn't installed, or steps that couldn't be started answer 409, saying why.
+- **`POST /v1/setup/{capability}/settings`**, with `{ "need": "screen-recording" }` or `{ "need": "accessibility" }`, opens that grant's pane of System Settings, under Privacy & Security, on the service's machine, macOS only, whether the grant is missing or not, for the person to switch it there. macOS lists an app there once it has asked, so this follows `ask`. It is for the person's own choice, such as a button they press: the service opens a pane nowhere else. Where an app hosts the driver, it is that app that sees the change and starts its driver again. It answers once the pane is asked to open, with each part then. A need the part doesn't have, one with no pane, a pane that couldn't be opened, or a machine other than a Mac answers 409, saying why.
 - **`PUT /v1/setup/{capability}`** with `{ "on": true }` or `{ "on": false }` sets a switch. Turning it on, or on again, also asks for everything the part is missing, as asking with no need does. Where that couldn't be started, it answers 409, saying why, and the switch stays on.
 - **`GET /v1/acting`** is who is acting now on every computer attached to this machine, in one list, as each one's `presence` surface has it. A computer in a container isn't included: its own `presence` surface has it.
 
@@ -312,7 +319,7 @@ Every running computer has two more, to watch only:
   - **`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. This computer has no edge to measure at, so it reads the whole machine's (`machine`); 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 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.
-- **`presence`** (protocol `presence@1`): who is acting on it now, and on what: a terminal, the files, the browser or the screen. It sends the whole list, `{"type":"presence","acting":[…]}`, when it opens and each time someone starts or stops acting on something. Someone stops 10 seconds after they last acted there. `openapi.yaml` has each field, as `PresenceEvent` and `Acting`, with what counts as acting.
+- **`presence`** (protocol `presence@1`): who is acting on it now, and on what: a terminal, the files, the browser or the screen. It sends the whole list, `{"type":"presence","acting":[…]}`, when it opens and each time someone starts or stops acting on something. Someone stops 10 seconds after they last acted there. A command the agent started is acting on its terminal until it ends, and 10 seconds after: one left running, such as a server, keeps the agent shown there, as the terminal shows it running. The person's shell, and what runs in it, counts for 10 seconds after their last input there. `openapi.yaml` has each field, as `PresenceEvent` and `Acting`, with what counts as acting.
   - **The agent is told too.** `about` names who else is acting. The answer to the agent's call on something someone else acted on since its last call there ends with a line naming each of them: `The person used this terminal 3 s ago.`, `The person wrote a file here 2 s ago.`, `The person used the browser 4 s ago.` or `The person used the screen 1 s ago.`
   - **Computers attached to the same machine share its files and its screen.** Each is shown the person and the other computers' agents acting on them, by name, and its agent's line names each one since its last call: `The person wrote a file here 1 s ago. Helper used the files here 2 s ago.` A computer's terminals and browser stay its own; the person's own browser is shared by the computers attached with it, and each shows only its own agent acting there.
   - **Nothing is refused by it,** for the person or the agent.

package/dist/agentcomputer.js

@@ -81358,8 +81358,8 @@ var Live = class {
     if (exec2 && access === "terminal") {
       this.#terminals = exec2.terminals;
       exec2.onCommand((event) => {
-        if (event.type === "start" && event.by === "agent")
-          presence.acted("agent", { capability: "terminal", terminal: event.id });
+        if (event.type === "start" && event.by === "agent") presence.agentCommandStarted(event.id);
+        if (event.type === "exit") presence.commandEnded(event.id);
         for (const message of messages(event)) for (const ws of this.#viewers) deliver(ws, message);
       });
     }
@@ -81724,16 +81724,32 @@ var did = (actor, where) => `${label(actor)} ${actor.who === "person" ? DID[wher
 var Board = class {
   #entries = /* @__PURE__ */ new Map();
   #listeners = /* @__PURE__ */ new Set();
+  /** An act there: held still where a command runs, and otherwise its 10 s count starts again. */
   acted(actor, where) {
-    const key = `${actorKey(actor)} ${named(where)}`;
+    this.#set(actor, where, this.#entries.get(this.#key(actor, where))?.held ?? false);
+  }
+  /** A command started there: acting until it ends, whatever is done there meanwhile. */
+  hold(actor, where) {
+    this.#set(actor, where, true);
+  }
+  /** The command ended: its end is the last act there, and its 10 s count starts now. */
+  release(actor, where) {
+    if (this.#entries.get(this.#key(actor, where))?.held) this.#set(actor, where, false);
+  }
+  #key(actor, where) {
+    return `${actorKey(actor)} ${named(where)}`;
+  }
+  /** Acting now, held or counting down 10 s. */
+  #set(actor, where, held) {
+    const key = this.#key(actor, where);
     const before = this.#entries.get(key);
     clearTimeout(before?.timer);
-    const timer = setTimeout(() => {
+    const timer = held ? void 0 : setTimeout(() => {
       this.#entries.delete(key);
       this.#changed();
     }, ACTING_MS);
-    timer.unref();
-    this.#entries.set(key, { actor, where, at: Date.now(), timer });
+    timer?.unref();
+    this.#entries.set(key, { actor, where, at: Date.now(), timer, held });
     if (!before) this.#changed();
   }
   list() {
@@ -81777,6 +81793,14 @@ var Presence = class {
   acted(who, where) {
     this.#board(where).acted(who === "person" ? { who } : this.#agent, where);
   }
+  /** The agent started a command on a terminal: it acts there until the command ends. */
+  agentCommandStarted(terminal) {
+    this.#own.hold(this.#agent, { capability: "terminal", terminal });
+  }
+  /** A command ended: where the agent started it, its 10 s count starts now. */
+  commandEnded(terminal) {
+    this.#own.release(this.#agent, { capability: "terminal", terminal });
+  }
   /**
    * The agent called on `where`, acting there unless `acts` is false, as when it only waits on a
    * command: the line to add to its answer, where anyone else acted there since its last call on
@@ -98505,6 +98529,7 @@ var TOOL_SWITCH = {
   browser_run_code_unsafe: "terminal"
 };
 var MAX_CALL = 4 * 1024 * 1024;
+var SCREEN_WAIT_MS = 1e3;
 var ProcessRuntime = class {
   #config;
   #contained;
@@ -98515,9 +98540,11 @@ var ProcessRuntime = class {
   /** The person's switches for this machine; inside a container there are none. */
   #switches;
   /**
-   * Whether the screen can be reached, as last checked. Asking the driver can take seconds, which
-   * `info` doesn't wait for: it is checked when the service starts, again when it is more than 10 s
-   * old and someone asks, and afresh at every start of a computer with the screen.
+   * Whether the screen can be reached, as last checked. It is checked when the service starts,
+   * again when it is more than 10 s old and someone asks, and afresh at every start of a computer
+   * with the screen. Asking the driver can take seconds: `info` waits up to `SCREEN_WAIT_MS` for
+   * the new check, so that a reading more than 10 s old isn't answered as it was, and otherwise
+   * answers the last one.
    */
   #screen = {
     ready: false,
@@ -98549,9 +98576,18 @@ var ProcessRuntime = class {
     });
     return this.#checking;
   }
-  /** The screen's readiness as last checked, starting another check where that is old. */
-  #screenNow() {
-    if (Date.now() - this.#screen.at > 1e4) void this.#checkScreen();
+  /** The screen's readiness: checked again where the last is old, waiting a little for that. */
+  async #screenNow() {
+    if (Date.now() - this.#screen.at > 1e4) {
+      let timer;
+      await Promise.race([
+        this.#checkScreen(),
+        new Promise((done) => {
+          timer = setTimeout(done, SCREEN_WAIT_MS);
+        })
+      ]);
+      clearTimeout(timer);
+    }
     const { at: _, ...ready } = this.#screen;
     return ready;
   }
@@ -98565,23 +98601,22 @@ var ProcessRuntime = class {
       const reason3 = this.#switches?.refused(which);
       return reason3 ? { ready: false, reason: reason3 } : ready;
     };
+    const [screen, own3] = await Promise.all([
+      this.#switches?.refused("screen") ? { ready: false } : this.#screenNow(),
+      this.#contained ? void 0 : ownBrowser(this.#ownBrowserData)
+    ]);
     return {
       ready: true,
       capabilities: [
         { capability: "about", ready: true },
         { capability: "terminal", ...unless("terminal", { ready: true }) },
         { capability: "files", ...unless("files", { ready: true }) },
-        { capability: "screen", ...unless("screen", this.#screenNow()) }
+        { capability: "screen", ...unless("screen", screen) }
       ],
       browsers: [
         { kind: "headless", ...browserProgram(this.#config) },
         // The person's own, which only this computer has.
-        ...this.#contained ? [] : [
-          {
-            kind: "own",
-            ...unless("browser", readiness(await ownBrowser(this.#ownBrowserData)))
-          }
-        ]
+        ...own3 === void 0 ? [] : [{ kind: "own", ...unless("browser", readiness(own3)) }]
       ]
     };
   }
@@ -98770,7 +98805,7 @@ var ProcessRuntime = class {
 };
 
 // src/handlers.ts
-var VERSION2 = "0.0.21";
+var VERSION2 = "0.0.22";
 function createHandlers(computers, connections, setup) {
   return {
     getInfo: async () => ({ version: VERSION2, ...await computers.offers() }),
@@ -98778,6 +98813,7 @@ function createHandlers(computers, connections, setup) {
     getSetup: () => setup.capabilities(),
     setSetup: ({ capability, on }) => setup.set(capability, on),
     askSetup: ({ capability, need }) => setup.ask(capability, need),
+    openSetupSettings: ({ capability, need }) => setup.settings(capability, need),
     getActing: async () => computers.acting(),
     listComputers: async ({ state }) => computers.list(state),
     createComputer: (input3) => computers.create(input3),
@@ -100201,14 +100237,16 @@ var Computers = class {
   }
   /** What it offers: this computer, and each kind it makes, with whether it can be now. */
   async offers() {
-    const offered = await this.#runtimes.none.offer();
+    const [offered, made] = await Promise.all([
+      this.#runtimes.none.offer(),
+      Promise.all(
+        Object.keys(this.#runtimes).filter((isolation) => isolation !== "none").map(async (isolation) => ({
+          isolation,
+          ...await this.#runtime(isolation).offer()
+        }))
+      )
+    ]);
     const thisComputer = this.#notHere ? { ...offered, ready: false, reason: this.#notHere } : offered;
-    const made = await Promise.all(
-      Object.keys(this.#runtimes).filter((isolation) => isolation !== "none").map(async (isolation) => ({
-        isolation,
-        ...await this.#runtime(isolation).offer()
-      }))
-    );
     return { thisComputer, made };
   }
   /**
@@ -100698,7 +100736,7 @@ var OPENAPI = {
   "openapi": "3.1.0",
   "info": {
     "title": "AgentComputer",
-    "version": "0.0.21",
+    "version": "0.0.22",
     "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",
@@ -100721,7 +100759,7 @@ var OPENAPI = {
       "get": {
         "operationId": "getInfo",
         "x-mcp-tool": "service_info",
-        "summary": "What this service offers: this computer, the kinds of computer it can make, and the browsers that can go with each, every one ready or not and why.",
+        "summary": "What this service offers: this computer, the kinds of computer it can make, and the browsers that can go with each, every one ready or not and why. The screen's readiness is read afresh where the last reading is more than 10 seconds old, waited for up to a second; a reading that takes longer is answered the next time.",
         "responses": {
           "200": {
             "description": "The service.",
@@ -100854,7 +100892,7 @@ var OPENAPI = {
       ],
       "post": {
         "operationId": "askSetup",
-        "summary": "Ask the person, on the service's machine, macOS only, for one thing a part needs, or, with none named, for everything it is missing. screen-recording or accessibility, while it is missing: Cua Driver's own grant, its app started first, which makes the system's requests in its own order, Accessibility first. For a driver an app hosts, the app asks, for that grant alone. Then that grant's own pane in System Settings opens. chrome or edge: that browser opens at its inspect page, where remote debugging is switched on. With none named, the screen's grant while either is missing, and the first browser installed, Chrome before Edge, while none is on. It answers once the steps have started, with each part then; what the person does next is read afresh later. A browser the service was given only the folder of, the person opens. Elsewhere it asks for nothing.",
+        "summary": "Ask the person, on the service's machine, macOS only, for one thing a part needs, or, with none named, for everything it is missing. screen-recording or accessibility, while it is missing: Cua Driver's own grant, its app started first, which makes the system's requests in its own order, Accessibility first. For a driver an app hosts, the app asks, for that grant alone, in its own way. The service opens no pane of System Settings: the person opens one with settings. macOS shows each request once: once it has been answered, asking again shows nothing and answers the same, so a client offers settings while a grant stays not-granted. chrome or edge: that browser opens at its inspect page, where remote debugging is switched on. With none named, the screen's grant while either is missing, and the first browser installed, Chrome before Edge, while none is on. It answers once the steps have started, with each part then; what the person does next is read afresh later. A browser the service was given only the folder of, the person opens. Elsewhere it asks for nothing.",
         "requestBody": {
           "content": {
             "application/json": {
@@ -100897,6 +100935,66 @@ var OPENAPI = {
         }
       }
     },
+    "/v1/setup/{capability}/settings": {
+      "parameters": [
+        {
+          "name": "capability",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "$ref": "#/components/schemas/Switch"
+          }
+        }
+      ],
+      "post": {
+        "operationId": "openSetupSettings",
+        "summary": "Open the pane of System Settings for one thing a part needs, on the service's machine, macOS only, for the person to switch it there: screen-recording or accessibility, that grant's pane under Privacy & Security, whether it is missing or not. macOS lists an app there once it has asked, so this follows ask. It is for the person's own choice, such as a button they press: the service opens a pane nowhere else. Where an app hosts the driver, it is that app that sees the change and starts its driver again. It answers once the pane is asked to open, with each part then. Elsewhere it answers 409.",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "need"
+                ],
+                "properties": {
+                  "need": {
+                    "$ref": "#/components/schemas/NeedName"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Its pane asked to open.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Setup"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "409": {
+            "description": "The part doesn't need that here, it has no pane of System Settings, or the pane couldn't be opened.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/v1/acting": {
       "get": {
         "operationId": "getActing",
@@ -102738,7 +102836,7 @@ var OPENAPI = {
         }
       },
       "Acting": {
-        "description": "Someone who acted on a computer in the last 10 seconds. The person acts in a live view at operate: opening a shell, typing into or stopping a terminal, writing a file, any input to the browser but moving the pointer, or any input to the screen that Cua Driver did. Watching is not acting, and the person's own use of the screen, outside a live view, can't be seen. The agent acts by calling its endpoints: starting a command or typing into one (waiting on its output is not acting), any file tool, reads among them, any browser tool that is answered, and any screen tool. Computers attached to the same machine share its files and its screen: each is shown the person and the other computers' agents acting on them, by name.",
+        "description": "Someone who acted on a computer in the last 10 seconds, or the agent while a command it started there still runs. The person acts in a live view at operate: opening a shell, typing into or stopping a terminal, writing a file, any input to the browser but moving the pointer, or any input to the screen that Cua Driver did. Watching is not acting, and the person's own use of the screen, outside a live view, can't be seen. The person's shell, and what runs in it, counts for 10 seconds after their last input there. The agent acts by calling its endpoints: starting a command, which is acting on its terminal until the command ends, even one left running, such as a server, as the terminal shows it running; typing into one (waiting on its output adds nothing); any file tool, reads among them; any browser tool that is answered; and any screen tool. Computers attached to the same machine share its files and its screen: each is shown the person and the other computers' agents acting on them, by name.",
         "type": "object",
         "required": [
           "who",
@@ -102774,12 +102872,12 @@ var OPENAPI = {
           "at": {
             "type": "string",
             "format": "date-time",
-            "description": "When it last acted there, as of this message: one who goes on acting is sent again only when someone starts or stops."
+            "description": "When it last acted there, as of this message: one who goes on acting is sent again only when someone starts or stops. For the agent's command still running, when the agent started it or last typed into it, which can be more than 10 seconds ago; its end is its last act."
           }
         }
       },
       "PresenceEvent": {
-        "description": "What the service sends on a presence@1 socket, as JSON text: the whole list of everyone acting now, the most recent first, empty where nobody is. It is sent when the socket opens and each time someone starts acting on something, or stops: 10 seconds after they last acted there. Nothing is refused by it. What a socket sends is dropped.",
+        "description": "What the service sends on a presence@1 socket, as JSON text: the whole list of everyone acting now, the most recent first, empty where nobody is. It is sent when the socket opens and each time someone starts acting on something, or stops: 10 seconds after they last acted there, or, for the agent's command, 10 seconds after it ended. Nothing is refused by it. What a socket sends is dropped.",
         "type": "object",
         "required": [
           "type",
@@ -103293,7 +103391,7 @@ var OPERATIONS = [
     "method": "GET",
     "path": "/v1/info",
     "tool": "service_info",
-    "summary": "What this service offers: this computer, the kinds of computer it can make, and the browsers that can go with each, every one ready or not and why.",
+    "summary": "What this service offers: this computer, the kinds of computer it can make, and the browsers that can go with each, every one ready or not and why. The screen's readiness is read afresh where the last reading is more than 10 seconds old, waited for up to a second; a reading that takes longer is answered the next time.",
     "status": 200,
     "hasBody": false,
     "pathParameters": [],
@@ -103845,7 +103943,7 @@ var OPERATIONS = [
     "operationId": "askSetup",
     "method": "POST",
     "path": "/v1/setup/{capability}/ask",
-    "summary": "Ask the person, on the service's machine, macOS only, for one thing a part needs, or, with none named, for everything it is missing. screen-recording or accessibility, while it is missing: Cua Driver's own grant, its app started first, which makes the system's requests in its own order, Accessibility first. For a driver an app hosts, the app asks, for that grant alone. Then that grant's own pane in System Settings opens. chrome or edge: that browser opens at its inspect page, where remote debugging is switched on. With none named, the screen's grant while either is missing, and the first browser installed, Chrome before Edge, while none is on. It answers once the steps have started, with each part then; what the person does next is read afresh later. A browser the service was given only the folder of, the person opens. Elsewhere it asks for nothing.",
+    "summary": "Ask the person, on the service's machine, macOS only, for one thing a part needs, or, with none named, for everything it is missing. screen-recording or accessibility, while it is missing: Cua Driver's own grant, its app started first, which makes the system's requests in its own order, Accessibility first. For a driver an app hosts, the app asks, for that grant alone, in its own way. The service opens no pane of System Settings: the person opens one with settings. macOS shows each request once: once it has been answered, asking again shows nothing and answers the same, so a client offers settings while a grant stays not-granted. chrome or edge: that browser opens at its inspect page, where remote debugging is switched on. With none named, the screen's grant while either is missing, and the first browser installed, Chrome before Edge, while none is on. It answers once the steps have started, with each part then; what the person does next is read afresh later. A browser the service was given only the folder of, the person opens. Elsewhere it asks for nothing.",
     "status": 200,
     "hasBody": true,
     "pathParameters": [
@@ -103971,6 +104069,137 @@ var OPERATIONS = [
     },
     "websocket": false
   },
+  {
+    "operationId": "openSetupSettings",
+    "method": "POST",
+    "path": "/v1/setup/{capability}/settings",
+    "summary": "Open the pane of System Settings for one thing a part needs, on the service's machine, macOS only, for the person to switch it there: screen-recording or accessibility, that grant's pane under Privacy & Security, whether it is missing or not. macOS lists an app there once it has asked, so this follows ask. It is for the person's own choice, such as a button they press: the service opens a pane nowhere else. Where an app hosts the driver, it is that app that sees the change and starts its driver again. It answers once the pane is asked to open, with each part then. Elsewhere it answers 409.",
+    "status": 200,
+    "hasBody": true,
+    "pathParameters": [
+      "capability"
+    ],
+    "queryParameters": [],
+    "input": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "capability": {
+          "type": "string",
+          "enum": [
+            "terminal",
+            "files",
+            "screen",
+            "browser"
+          ],
+          "description": "A part of the service's machine an agent can use: its terminal, its files, its screen, and the person's own browser."
+        },
+        "need": {
+          "type": "string",
+          "enum": [
+            "install",
+            "screen-recording",
+            "accessibility",
+            "chrome",
+            "edge",
+            "named"
+          ],
+          "description": "install: Cua Driver, which the screen works through. screen-recording and accessibility: Cua Driver's two grants. chrome and edge: each browser, with remote debugging on or off; named: the one browser a service was given the folder of."
+        }
+      },
+      "required": [
+        "capability",
+        "need"
+      ]
+    },
+    "output": {
+      "type": "object",
+      "required": [
+        "capabilities"
+      ],
+      "properties": {
+        "capabilities": {
+          "type": "array",
+          "description": "terminal, files, screen and browser, in that order.",
+          "items": {
+            "type": "object",
+            "required": [
+              "capability",
+              "on",
+              "ready",
+              "needs"
+            ],
+            "properties": {
+              "capability": {
+                "type": "string",
+                "enum": [
+                  "terminal",
+                  "files",
+                  "screen",
+                  "browser"
+                ],
+                "description": "A part of the service's machine an agent can use: its terminal, its files, its screen, and the person's own browser."
+              },
+              "on": {
+                "type": "boolean",
+                "description": "The person's switch. Off, agents' new calls to the part refuse, saying the person turned it off, and `info` says so; what an agent already started runs on. The terminal and the screen each reach the whole machine: commands read any file, and the screen acts in any app. The browser's switch is for the person's own; any browser's code-running tool answers to the terminal's switch, and a browser call that names files, by `paths` or `filename`, to the files'. A service started with `--lend` starts with every one off; any other, with every one on."
+              },
+              "ready": {
+                "type": "boolean",
+                "description": "Whether the part has all it needs, apart from its switch: the screen, each item granted; the browser, one browser on. The terminal and files always do."
+              },
+              "needs": {
+                "type": "array",
+                "description": "Each thing the part needs, always, with its state. The terminal and files need nothing. The screen needs Cua Driver, which while it isn't installed is the one item, and on macOS its two grants. The browser lists Chrome then Edge, each on, off or missing, or the one browser named; with both on, the agent's is Chrome.",
+                "items": {
+                  "type": "object",
+                  "required": [
+                    "need",
+                    "state"
+                  ],
+                  "properties": {
+                    "need": {
+                      "type": "string",
+                      "enum": [
+                        "install",
+                        "screen-recording",
+                        "accessibility",
+                        "chrome",
+                        "edge",
+                        "named"
+                      ],
+                      "description": "install: Cua Driver, which the screen works through. screen-recording and accessibility: Cua Driver's two grants. chrome and edge: each browser, with remote debugging on or off; named: the one browser a service was given the folder of."
+                    },
+                    "name": {
+                      "type": "string",
+                      "description": "A browser's name: Chrome, Edge, or the browser."
+                    },
+                    "holder": {
+                      "type": "string",
+                      "description": "For a grant, whose it is, as System Settings lists it: the outermost app Cua Driver is inside, CuaDriver for its own app, or an app that carries the driver. None where Cua Driver is in no app."
+                    },
+                    "state": {
+                      "type": "string",
+                      "enum": [
+                        "missing",
+                        "granted",
+                        "not-granted",
+                        "unknown",
+                        "on",
+                        "off"
+                      ],
+                      "description": "missing: not installed. unknown: it can't be read now. A browser is on while it is open with its remote debugging switched on."
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "websocket": false
+  },
   {
     "operationId": "getActing",
     "method": "GET",
@@ -103989,7 +104218,7 @@ var OPERATIONS = [
     "output": {
       "type": "array",
       "items": {
-        "description": "Someone who acted on a computer in the last 10 seconds. The person acts in a live view at operate: opening a shell, typing into or stopping a terminal, writing a file, any input to the browser but moving the pointer, or any input to the screen that Cua Driver did. Watching is not acting, and the person's own use of the screen, outside a live view, can't be seen. The agent acts by calling its endpoints: starting a command or typing into one (waiting on its output is not acting), any file tool, reads among them, any browser tool that is answered, and any screen tool. Computers attached to the same machine share its files and its screen: each is shown the person and the other computers' agents acting on them, by name.",
+        "description": "Someone who acted on a computer in the last 10 seconds, or the agent while a command it started there still runs. The person acts in a live view at operate: opening a shell, typing into or stopping a terminal, writing a file, any input to the browser but moving the pointer, or any input to the screen that Cua Driver did. Watching is not acting, and the person's own use of the screen, outside a live view, can't be seen. The person's shell, and what runs in it, counts for 10 seconds after their last input there. The agent acts by calling its endpoints: starting a command, which is acting on its terminal until the command ends, even one left running, such as a server, as the terminal shows it running; typing into one (waiting on its output adds nothing); any file tool, reads among them; any browser tool that is answered; and any screen tool. Computers attached to the same machine share its files and its screen: each is shown the person and the other computers' agents acting on them, by name.",
         "type": "object",
         "required": [
           "who",
@@ -104025,7 +104254,7 @@ var OPERATIONS = [
           "at": {
             "type": "string",
             "format": "date-time",
-            "description": "When it last acted there, as of this message: one who goes on acting is sent again only when someone starts or stops."
+            "description": "When it last acted there, as of this message: one who goes on acting is sent again only when someone starts or stops. For the agent's command still running, when the agent started it or last typed into it, which can be more than 10 seconds ago; its end is its last act."
           }
         }
       }
@@ -106404,11 +106633,31 @@ var Setup = class {
     }
     return this.capabilities();
   }
-  /** Only macOS asks: elsewhere there is nothing to ask the person for. */
-  async #ask(capability, need) {
+  /**
+   * Open the pane of System Settings for one thing a part needs, whether it is missing or not: for
+   * the person's own choice, as nothing else opens one.
+   */
+  async settings(capability, need) {
+    try {
+      await this.#needs(capability, need);
+      const pane = PANE[need];
+      if (!pane) throw new Error(`"${need}" has no pane of System Settings.`);
+      await this.#machine.run("/usr/bin/open", [pane]);
+    } catch (error64) {
+      throw new ApiError(409, error64.message);
+    }
+    return this.capabilities();
+  }
+  /** What a part needs, where it needs the one named. */
+  async #needs(capability, need) {
     const { needs } = (await this.#parts())[capability];
     if (need && !needs.some((one) => one.need === need))
       throw new Error(`There's no "${need}" for ${capability} here.`);
+    return needs;
+  }
+  /** Only macOS asks: elsewhere there is nothing to ask the person for. No pane opens. */
+  async #ask(capability, need) {
+    const needs = await this.#needs(capability, need);
     if (this.#machine.platform !== "darwin") return;
     if (capability === "screen") {
       const driver = findDriver(this.#driver);
@@ -106416,8 +106665,6 @@ var Setup = class {
       const asked = needs.filter((one) => one.state !== "granted" && (!need || one.need === need)).map((one) => one.need);
       if (asked.length > 0)
         await (driver.socket ? this.#askHost(driver, asked) : this.#askScreen(driver));
-      const pane = need && PANE[need];
-      if (pane) await this.#machine.run("/usr/bin/open", [pane]);
     }
     if (capability === "browser" && (need || !needs.some((one) => one.state === "on")))
       await this.#askBrowser(need);

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

@@ -11,7 +11,7 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /** What this service offers: this computer, the kinds of computer it can make, and the browsers that can go with each, every one ready or not and why. */
+        /** What this service offers: this computer, the kinds of computer it can make, and the browsers that can go with each, every one ready or not and why. The screen's readiness is read afresh where the last reading is more than 10 seconds old, waited for up to a second; a reading that takes longer is answered the next time. */
         get: operations["getInfo"];
         put?: never;
         post?: never;
@@ -85,7 +85,7 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** Ask the person, on the service's machine, macOS only, for one thing a part needs, or, with none named, for everything it is missing. screen-recording or accessibility, while it is missing: Cua Driver's own grant, its app started first, which makes the system's requests in its own order, Accessibility first. For a driver an app hosts, the app asks, for that grant alone. Then that grant's own pane in System Settings opens. chrome or edge: that browser opens at its inspect page, where remote debugging is switched on. With none named, the screen's grant while either is missing, and the first browser installed, Chrome before Edge, while none is on. It answers once the steps have started, with each part then; what the person does next is read afresh later. A browser the service was given only the folder of, the person opens. Elsewhere it asks for nothing. */
+        /** Ask the person, on the service's machine, macOS only, for one thing a part needs, or, with none named, for everything it is missing. screen-recording or accessibility, while it is missing: Cua Driver's own grant, its app started first, which makes the system's requests in its own order, Accessibility first. For a driver an app hosts, the app asks, for that grant alone, in its own way. The service opens no pane of System Settings: the person opens one with settings. macOS shows each request once: once it has been answered, asking again shows nothing and answers the same, so a client offers settings while a grant stays not-granted. chrome or edge: that browser opens at its inspect page, where remote debugging is switched on. With none named, the screen's grant while either is missing, and the first browser installed, Chrome before Edge, while none is on. It answers once the steps have started, with each part then; what the person does next is read afresh later. A browser the service was given only the folder of, the person opens. Elsewhere it asks for nothing. */
         post: operations["askSetup"];
         delete?: never;
         options?: never;
@@ -93,6 +93,25 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/setup/{capability}/settings": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                capability: components["schemas"]["Switch"];
+            };
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Open the pane of System Settings for one thing a part needs, on the service's machine, macOS only, for the person to switch it there: screen-recording or accessibility, that grant's pane under Privacy & Security, whether it is missing or not. macOS lists an app there once it has asked, so this follows ask. It is for the person's own choice, such as a button they press: the service opens a pane nowhere else. Where an app hosts the driver, it is that app that sees the change and starts its driver again. It answers once the pane is asked to open, with each part then. Elsewhere it answers 409. */
+        post: operations["openSetupSettings"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/acting": {
         parameters: {
             query?: never;
@@ -702,7 +721,7 @@ export interface components {
                 local: boolean;
             }[];
         };
-        /** @description Someone who acted on a computer in the last 10 seconds. The person acts in a live view at operate: opening a shell, typing into or stopping a terminal, writing a file, any input to the browser but moving the pointer, or any input to the screen that Cua Driver did. Watching is not acting, and the person's own use of the screen, outside a live view, can't be seen. The agent acts by calling its endpoints: starting a command or typing into one (waiting on its output is not acting), any file tool, reads among them, any browser tool that is answered, and any screen tool. Computers attached to the same machine share its files and its screen: each is shown the person and the other computers' agents acting on them, by name. */
+        /** @description Someone who acted on a computer in the last 10 seconds, or the agent while a command it started there still runs. The person acts in a live view at operate: opening a shell, typing into or stopping a terminal, writing a file, any input to the browser but moving the pointer, or any input to the screen that Cua Driver did. Watching is not acting, and the person's own use of the screen, outside a live view, can't be seen. The person's shell, and what runs in it, counts for 10 seconds after their last input there. The agent acts by calling its endpoints: starting a command, which is acting on its terminal until the command ends, even one left running, such as a server, as the terminal shows it running; typing into one (waiting on its output adds nothing); any file tool, reads among them; any browser tool that is answered; and any screen tool. Computers attached to the same machine share its files and its screen: each is shown the person and the other computers' agents acting on them, by name. */
         Acting: {
             /** @enum {string} */
             who: "person" | "agent";
@@ -714,11 +733,11 @@ export interface components {
             terminal?: string;
             /**
              * Format: date-time
-             * @description When it last acted there, as of this message: one who goes on acting is sent again only when someone starts or stops.
+             * @description When it last acted there, as of this message: one who goes on acting is sent again only when someone starts or stops. For the agent's command still running, when the agent started it or last typed into it, which can be more than 10 seconds ago; its end is its last act.
              */
             at: string;
         };
-        /** @description What the service sends on a presence@1 socket, as JSON text: the whole list of everyone acting now, the most recent first, empty where nobody is. It is sent when the socket opens and each time someone starts acting on something, or stops: 10 seconds after they last acted there. Nothing is refused by it. What a socket sends is dropped. */
+        /** @description What the service sends on a presence@1 socket, as JSON text: the whole list of everyone acting now, the most recent first, empty where nobody is. It is sent when the socket opens and each time someone starts acting on something, or stops: 10 seconds after they last acted there, or, for the agent's command, 10 seconds after it ended. Nothing is refused by it. What a socket sends is dropped. */
         PresenceEvent: {
             /** @constant */
             type: "presence";
@@ -1020,6 +1039,44 @@ export interface operations {
             };
         };
     };
+    openSetupSettings: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                capability: components["schemas"]["Switch"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    need: components["schemas"]["NeedName"];
+                };
+            };
+        };
+        responses: {
+            /** @description Its pane asked to open. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Setup"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            /** @description The part doesn't need that here, it has no pane of System Settings, or the pane couldn't be opened. */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
     getActing: {
         parameters: {
             query?: never;

package/package.json

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