@kortix/agent-tunnel 0.13.52 → 0.13.54

package/README.md

@@ -27,11 +27,36 @@ Connecting the same computer again reuses its entry. The agent sends a SHA-256
 hash of the hardware ID (IOPlatformUUID, `/etc/machine-id`, or `MachineGuid`);
 the raw ID never leaves the computer.
 
-After approval, the interactive flow asks whether it should install a persistent background service. The default answer is yes.
+After approval, `connect` in a terminal installs the background service, the
+same way the desktop app does, and prints the commands that pause, resume,
+and remove it. It asks no question. `--foreground` keeps the connection in the
+terminal instead. A script without a TTY, or `--json`, stays in the foreground
+unless it passes `--daemon`.
+
+## One runtime with the desktop app (macOS)
+
+When the Kortix desktop app is installed (`/Applications/Kortix.app` or
+`~/Applications/Kortix.app`), the service a CLI install writes runs on the
+app's own agent and driver: `Kortix.app/Contents/MacOS/Kortix` with
+`ELECTRON_RUN_AS_NODE=1` and `Contents/Resources/agent-tunnel/agent-cli.js`.
+A CLI install and an app install are then the same connection. macOS grants
+Accessibility and Screen Recording to Kortix once, never to `node` or a
+terminal, and **Your computer** in the app controls it.
+
+This CLI is the one control surface of the computer. The desktop app runs
+these same commands (`status --json`, `access`, `keep-awake`, `stop`,
+`start`, `logout`) and never edits the agent's files itself. A change made
+in the app, in the terminal, or through Kortix is the same change. Without the app,
+the service runs on `node`, and Computer Use needs a separately installed
+`cua-driver`.
+
+The service restarts itself when its code changes on disk (an app update or
+a new vendored bundle). macOS refuses every permission to a process whose
+binary was replaced under it, so a stale process would lose Computer Use.
 
 ## Run in the background
 
-Install the operating-system background service during connection:
+The service is the default for a person at a terminal. A script installs it with `--daemon`:
 
 ```bash
 npx --yes @kortix/agent-tunnel@latest connect \
@@ -62,8 +87,8 @@ The agent itself never stops on its own:
 - A handshake that does not reach `auth_ok` within 20 s is dropped and retried.
 - No saved credential: it waits and checks `config.json` every 60 s.
 
-It changes the computer's sleep settings only when `access.json` sets
-`keepAwake` (see below).
+It changes the computer's sleep settings only while `keep-awake` is on (see
+"Access control").
 
 ## Manage the background service
 
@@ -85,9 +110,11 @@ which removes the machine and its accounts in Kortix. It then clears the local
 credential and removes the service. If Kortix cannot be reached, the local
 sign-out still completes; `logout --json` then reports `"serverUnpaired": false`.
 
-`service-status --json` prints the pairing, the service (`installed`, `active`,
-`enabled` = not paused, `upToDate` = the unit matches what `install-service`
-writes now), the live connection state, and `access`.
+`status --json` (and its alias `service-status --json`) prints the pairing,
+the approved `capabilities`, the service (`installed`, `active`, `enabled` =
+not paused, `upToDate` = the unit matches what `install-service` writes now),
+the live connection `state` (a process that died without saying so reads as
+`offline`), and `access` (the same object `access --json` prints).
 
 Credentials are stored in `~/.agent-tunnel/config.json`. Agent Tunnel requires
 the file to be regular, owned by the current user, and mode `0600` on POSIX.
@@ -104,7 +131,7 @@ Remote API URLs must use HTTPS. Plain HTTP is accepted only for `localhost`,
 | `config.json` | Credential and local limits, mode `0600`. |
 | `state.json` | `{ tunnelId, apiUrl, status: online\|offline\|connecting\|rejected\|standby, since, agentVersion, pid }`, rewritten atomically on every connection change. No credential. |
 | `access.json` | `{ mode: ask\|always\|off, grantedUntil, deniedUntil, keepAwake }`, mode `0600`. See "Access control". |
-| `access-request.json` | `{ id, requestedAt, capability, method }`: the call waiting for the owner. |
+| `access-request.json` | `{ id, requestedAt, capability, method, change? }`: the call, or the wider access asked for through Kortix (`change`), waiting for the owner. |
 | `desktop-app.json` | Written by the Kortix desktop app: how to start it to show an access prompt. |
 | `logs/` | Service output. |
 
@@ -116,8 +143,22 @@ service definition carries `AGENT_TUNNEL_HOME` into the service environment.
 
 ## Access control
 
-The machine decides, before every call, whether an agent may use it.
-`access.json` holds the owner's answer:
+The machine decides, before every call, whether an agent may use it. Change
+it with the CLI:
+
+```bash
+npx --yes @kortix/agent-tunnel@latest access                  # show it
+npx --yes @kortix/agent-tunnel@latest access ask              # or always, off
+npx --yes @kortix/agent-tunnel@latest access --allow-for 60   # in ask: allow for 60 minutes (max 1440)
+npx --yes @kortix/agent-tunnel@latest access --revoke         # end the current allowance
+npx --yes @kortix/agent-tunnel@latest access --deny           # answer the waiting request with No
+npx --yes @kortix/agent-tunnel@latest keep-awake on           # or off (macOS and Linux)
+```
+
+Every command takes `--json` and prints `{ mode, grantedUntil, deniedUntil,
+keepAwake, keepAwakeSupported, pendingRequest }`. A wrong mode or duration
+exits `1` and changes nothing. The person at the terminal is the computer's
+owner, so these commands also widen access.
 
 | `mode` | Effect |
 | --- | --- |
@@ -125,17 +166,36 @@ The machine decides, before every call, whether an agent may use it.
 | `ask` | A call runs while `grantedUntil` is in the future (at most 24 h ahead). Otherwise the agent writes `access-request.json`, starts the desktop app if it is not running, and holds the call for 20 s. A grant runs it. No answer returns `-32010 computer_access_pending`. A denial sets `deniedUntil` 10 minutes ahead and returns `-32011 computer_access_denied`; calls fail at once until then. |
 | `off` | Every call returns `-32012 computer_access_off`. |
 
+**Through Kortix.** The owner can also change access from the Kortix web app
+or the desktop app's window (`POST /v1/tunnel/connections/:id/access`, user
+credentials only; no agent or session token reaches it). Kortix relays the
+change to the agent as `tunnel.access.set`:
+
+- A narrowing (`ask`, `off`, `--revoke`, `--deny`, keep awake) applies at once,
+  even while access is `off`.
+- A widening (`always`, or a longer allowance) needs the owner on the computer.
+  The agent writes it to `access-request.json` with `change`, and the desktop
+  app shows a native **Allow** / **Cancel** dialog. **Allow** runs the matching
+  `access` command; **Cancel** runs `access --deny`, which declines the change
+  without refusing calls. The relayed call waits up to 20 s and otherwise fails
+  with `-32014 computer_access_unconfirmed`. A computer without the desktop
+  app fails at once, naming the command to run on it.
+
 A pairing made from the Kortix desktop app starts in `ask`: the app shows the
 prompt. A pairing made with this CLI alone starts in `always`, because nothing
 on the machine could answer a prompt. This is a deliberate deviation from
 "new pairings default to ask". Every new pairing resets `access.json`, so a
 grant or `always` from an earlier pairing never carries over, and `logout`
 deletes it. The agent home (`config.json`, `access.json`, `desktop-app.json`)
-is always a blocked path: no file or shell call can change these files. The agent reports `{ mode, grantedUntil }`
-to Kortix as the signed notification `tunnel.access.state` on connect and on
-every change.
+is always a blocked path: no file or shell call can change these files.
+
+The agent reports its state to Kortix as the signed notification
+`tunnel.access.state` on connect and on every change: the access fields, the
+waiting request, and `desktopPermissions` (`{ accessibility, screenRecording }`
+as macOS answers for the agent process itself, checked every 60 s). Kortix
+shows exactly this.
 
-`keepAwake: true` keeps the computer from sleeping while the agent runs:
+`keep-awake on` keeps the computer from sleeping while the agent runs:
 `caffeinate -s` on macOS (on AC power only), `systemd-inhibit --what=sleep` on
 Linux. Windows is not supported.