docs: describe generic terminal connector

Author: serge-the-dev

docs/architecture.md

@@ -47,7 +47,7 @@ platform/
 +-- packages/
 |   +-- sdk/                 Browser/client SDK and shared UI/voice helpers
 |   +-- cli/                 pags CLI: init, publish, login, mcp, runner
-|   +-- browser-runner/      Local Playwright/tmux runtime served by `pags up`
+|   +-- browser-runner/      Local Playwright/terminal runtime served by `pags up`
 |   +-- compliance/          Policy/check tooling
 +-- agents/                  First-party catalog agents
 +-- templates/               Agent scaffolds for worker, cron, api templates
@@ -81,7 +81,7 @@ workers/mcp --------------- OAuth + tool surface, calls workers/api
 Local machine
         |
         v
-packages/browser-runner ---- Playwright browser, tmux CLIs, local files
+packages/browser-runner ---- Playwright browser, terminal CLIs, local files
         ^
         |
 RelayDO WebSocket relay ---- outbound runner connection, no inbound tunnel
@@ -129,14 +129,14 @@ Current runtime-backed surfaces:
 
 - Job Application Assistant: Cloudflare Workflow brain drives Playwright browser
   actions.
-- Coder: Cloudflare Workflow brain drives local CLI sessions in tmux. Multiple
+- Coder: Cloudflare Workflow brain drives local CLI sessions through the generic Terminal connector. Multiple
   machines can connect to the same Coder instance through node-scoped relay
   connections; see [Coder Multi-Machine Runtime](../platform-docs/coder-multi-machine.md).
 
 The key architectural pattern is "brain in cloud, hands local":
 
 ```text
-Workflow brain -> callRunner() -> RelayDO -> WebSocket -> local runner -> browser/tmux
+Workflow brain -> callRunner() -> RelayDO -> WebSocket -> local runner -> browser/terminal
 ```
 
 ## API Worker
@@ -159,7 +159,7 @@ The API worker is a Hono app. It mounts route modules for:
 - Instance storage: documents, files, collections, search, activity, summaries
 - Runtime: `/v1/relay`, runtime registration/status/task mirrors
 - Coding: `/v1/instances/:id/coding/...`
-- Connectors: `/v1/github` (GitHub App), `/v1/drive` (Google Drive), `/v1/workdrive` (Zoho WorkDrive), `/v1/email` (Gmail, apply-flow reads); registry connectors (github, http, meta, web-search, tmux, browser) are dispatched through the tool loop, not per-connector routes
+- Connectors: `/v1/github` (GitHub App), `/v1/drive` (Google Drive), `/v1/workdrive` (Zoho WorkDrive), `/v1/email` (Gmail, apply-flow reads); registry connectors (github, http, meta, web-search, terminal, tmux, browser) are dispatched through the tool loop, not per-connector routes
 - Keys: BYOK key vault and key proxy
 - Billing, notifications, push, dashboard, errors
 
@@ -331,7 +331,7 @@ The browser runner provides:
 - Runtime task endpoints.
 - CAPTCHA/handoff support.
 - File upload support.
-- tmux-backed coding sessions.
+- terminal-backed coding sessions.
 - Terminal capture and action execution.
 
 ### Assessment
@@ -393,7 +393,7 @@ source-of-truth rule.
 Recommended source-of-truth rule:
 
 - Durable Workflow owns long-running brain progress.
-- Local runner owns immediate browser/tmux execution state.
+- Local runner owns immediate browser/terminal execution state.
 - D1 `instance_runtime_tasks` is the user-visible mirror and query index.
 - `agent_events` is the timeline/audit stream.
 - Board rows are presentation and operational workflow state.
@@ -438,7 +438,8 @@ Registered connectors (`CONNECTORS`):
 | `http` | token (vault key) | read+write | generic HTTP/REST — call any API as config |
 | `web-search` | token (vault key) | read | Google Custom Search |
 | `meta` | token (`META_ACCESS_TOKEN`) | write | `whatsapp_send_message`, `instagram_send_dm` |
-| `tmux` | none (runner relay) | read+write | drive shells/CLIs on the user's machine |
+| `terminal` | none (runner relay) | read+write | drive tmux, kitty, or iTerm2 targets on the user's machine |
+| `tmux` | none (runner relay) | read+write | legacy compatibility wrapper for tmux sessions |
 | `browser` | none (runner relay) | read+write | experimental (`BROWSER_TOOLS_ENABLED`); `browser_navigate`/`browser_snapshot`/`browser_act` |
 
 Auth is minted through the single `connectorClient(env, provider, {userId, instanceId})`
@@ -650,7 +651,7 @@ Use these rules when adding new platform features:
 - R2 owns blobs.
 - Vectorize owns semantic retrieval indexes.
 - Workflows own long-running brain progress.
-- The local runner owns local browser/tmux execution.
+- The local runner owns local browser/terminal execution.
 - MCP should call platform APIs, not reimplement platform behavior.
 - User-facing LLM spend must be BYOK unless the billing model explicitly
   changes.

docs/connector-manifest.md

@@ -86,7 +86,7 @@ A connector manifest is JSON (built-in ones committed as data; later, creator-su
 | `api-key` | user's BYOK vault (`user_api_keys`), injected into header/query per the tool | http, web-search |
 | `oauth2` | refresh→access exchange; refresh token envelope-encrypted; `secretRef` server-side | Slack, Google Sheets, Notion, Linear |
 | `app` | installation token (GitHub-App style) | github |
-| `none` | reached over the runner relay (machine-owned) | tmux, browser |
+| `none` | reached over the runner relay (machine-owned) | terminal, tmux, browser |
 
 The one new capability is a **generic OAuth2 handler** driven by `auth` config — today Drive/Gmail/
 GitHub each hand-roll their flow. Consolidating them into one manifest-driven `authorize` +

platform-docs/architecture.md

@@ -17,7 +17,7 @@ platform/
   packages/
     sdk/                 Browser/client SDK and shared helpers
     cli/                 pags CLI: init, publish, login, mcp, runner
-    browser-runner/      Local Playwright/tmux runtime served by `pags up`
+    browser-runner/      Local Playwright/terminal runtime served by `pags up`
     compliance/          Policy/check tooling
   agents/                First-party catalog agents
   templates/             Agent scaffolds
@@ -50,7 +50,7 @@ workers/mcp --------------- OAuth + tool surface, calls workers/api
 Local machine
         |
         v
-packages/browser-runner ---- Playwright browser, tmux CLIs, local files
+packages/browser-runner ---- Playwright browser, terminal CLIs, local files
         ^
         |
 RelayDO WebSocket relay ---- outbound runner connection, no inbound tunnel
@@ -82,7 +82,7 @@ Runtime-backed agents use `pags up`, which runs a local browser/CLI runtime from
 Current runtime-backed surfaces:
 
 - Job Application Assistant: Cloudflare Workflow brain drives Playwright browser actions.
-- Coder: Cloudflare Workflow brain drives local CLI sessions in tmux. Coder sessions can route to node-scoped runners when multiple machines are connected to the same instance.
+- Coder: Cloudflare Workflow brain drives local CLI sessions through the generic Terminal connector. Coder sessions can route to node-scoped runners when multiple machines are connected to the same instance.
 
 ## Docs Plane
 

platform-docs/browser-runtime.md

@@ -5,7 +5,7 @@ Runtime-backed agents use `pags up`, which runs local browser and CLI capabiliti
 The current PAGS runtime pattern is:
 
 ```text
-Workflow brain -> callRunner() -> RelayDO -> WebSocket -> local runner -> browser/tmux
+Workflow brain -> callRunner() -> RelayDO -> WebSocket -> local runner -> browser/terminal
 ```
 
 The cloud-hosted workflow is the brain. The local runner is the hands. This keeps account state, audit, and orchestration in ProAgentStore while browser sessions, local files, and CLI sessions stay on the user's machine.
@@ -19,7 +19,7 @@ ProAgentStore Workflow
   -> RelayDO
   -> outbound WebSocket
   -> local browser runner
-  -> Playwright browser or tmux CLI
+  -> Playwright browser or terminal CLI
 ```
 
 The outbound WebSocket relay is the only transport. The earlier Cloudflare Tunnel / cloudflared modes were removed — there is no tunnel fallback, no `--tunnel` flag, and no public inbound server. The runner mints a short-lived, instance-scoped relay token and opens `wss://…/v1/relay/:instanceId/connect`; the relay DO is keyed per (instance, node) and hibernates when idle.
@@ -32,7 +32,7 @@ The workflow brain runs in ProAgentStore. The hands run locally.
 | --- | --- | --- |
 | Brain | Cloudflare Workflow | Plans steps, manages durable task state, checks policy, requests approval |
 | Relay | RelayDO WebSocket relay | Carries scoped calls between the cloud workflow and local runner |
-| Hands | Local `pags up` runner | Drives Playwright browser actions or tmux CLI sessions |
+| Hands | Local `pags up` runner | Drives Playwright browser actions or terminal CLI sessions |
 | Browser/session | User machine | Keeps cookies, local files, active logins, and interactive handoff state |
 
 ## Browser-Capable Agents
@@ -50,10 +50,10 @@ The Job Application Assistant is the reference browser-capable agent. Its Cloudf
 
 ## Coder Agents
 
-Coder agents use the same runtime idea, but the local capability is a tmux-backed CLI session rather than a browser.
+Coder agents use the same runtime idea, but the local capability is a terminal-backed CLI session rather than a browser. The default backend remains tmux; the generic terminal connector can also address kitty and iTerm2 targets when those apps expose local control APIs.
 
 ```text
-Workflow brain -> RelayDO -> local runner -> tmux CLI session
+Workflow brain -> RelayDO -> local runner -> terminal CLI session
 ```
 
 This allows long-running coding sessions while preserving the account-level control plane and audit model.

platform-docs/coder-multi-machine.md

@@ -9,7 +9,7 @@ Each machine runs `pags up`. ProAgentStore records the machine as a runner node,
 - Keep a desktop and laptop connected to the same Coder instance.
 - Run different repo sessions on different machines at the same time.
 - Preserve account-level authorization, audit, and workflow state in ProAgentStore.
-- Keep local files, browser profiles, CLI auth, and tmux sessions on the machine where they run.
+- Keep local files, browser profiles, CLI auth, and terminal sessions on the machine where they run.
 
 One repo still has at most one active session. That prevents two coding CLIs from fighting over the same working tree and git index.
 
@@ -21,7 +21,7 @@ Coder session
   -> node-scoped RelayDO
   -> outbound WebSocket
   -> local pags up runner
-  -> tmux CLI session
+  -> terminal CLI session
 ```
 
 The legacy instance runtime row remains the default runtime for browser/apply behavior and older clients. Coder adds node-level runtime rows for machine-specific routing.

platform-docs/connectors.md

@@ -8,8 +8,9 @@ ProAgentStore has two connector layers, for two different jobs.
    integration used by the apply flow to read verification emails; it is not a knowledge-ingest
    connector.)
 2. **Registry connectors** (the tool framework, issues #84–#90): a declared registry of
-   integrations an agent drives as **tools** — GitHub, HTTP/REST, Web Search, Meta, tmux, and
-   the experimental browser. See [Registry connectors](#registry-connectors) below.
+   integrations an agent drives as **tools** — GitHub, HTTP/REST, Web Search, Meta, Terminal,
+   legacy tmux, and the experimental browser. See [Registry connectors](#registry-connectors)
+   below.
 
 ## Registry connectors
 
@@ -24,14 +25,16 @@ An agent gets a connector's tools only when it declares them in `capabilities.to
 | `http` | vault API key | read + write | `http_request` (call any REST API as configuration) |
 | `web-search` | vault API key | read | `web_search` (Google Custom Search) |
 | `meta` | platform token (`META_ACCESS_TOKEN`) | write | `whatsapp_send_message`, `instagram_send_dm` |
-| `tmux` | none (runner relay) | read + write | `tmux_list_sessions`, `tmux_capture_pane`, `tmux_run_command` (write) |
+| `terminal` | none (runner relay) | read + write | `terminal_list_targets`, `terminal_capture`, `terminal_run_command` (write), `terminal_send_keys` (write) |
+| `tmux` | none (runner relay) | read + write | Legacy compatibility: `tmux_list_sessions`, `tmux_capture_pane`, `tmux_run_command` (write) |
 | `browser` | none (runner relay) | read + write | `browser_snapshot`, `browser_navigate` (write), `browser_act` (write) — experimental |
 
 **Auth** is minted through one path — `connectorClient(env, provider, {userId, instanceId})`:
 a GitHub-App installation token, an OAuth refresh→access exchange, a key from the user's BYOK
-vault (`user_api_keys`), or none for local relay connectors (tmux/browser reach the user's
-machine over the WebSocket relay — machine ownership is already enforced by the relay-token
-handshake).
+vault (`user_api_keys`), or none for local relay connectors (terminal/tmux/browser reach the
+user's machine over the WebSocket relay — machine ownership is already enforced by the relay-token
+handshake). The generic Terminal connector targets `tmux:<session>`, `kitty:<window-id>`, or
+`iterm2:<window>:<tab>:<session>`.
 
 **Write-consent gating (#90).** Every `scope:"write"` connector tool is refused unless the
 instance has explicit write-consent for that connector (`instance_connector_consent`, migration

platform-docs/index.md

@@ -6,7 +6,7 @@ Creators publish agent templates. Users subscribe to private agent instances. Ea
 
 ## Start Here
 
-- [Connectors](connectors.md): two layers — *ingest* connectors (Google Drive, Google Docs, Zoho WorkDrive) imported into knowledge via per-folder grants, and *registry* connectors an agent drives as tools (GitHub, HTTP/REST, Web Search, Meta, tmux, and the experimental browser), with per-instance write-consent gating.
+- [Connectors](connectors.md): two layers — *ingest* connectors (Google Drive, Google Docs, Zoho WorkDrive) imported into knowledge via per-folder grants, and *registry* connectors an agent drives as tools (GitHub, HTTP/REST, Web Search, Meta, Terminal, legacy tmux, and the experimental browser), with per-instance write-consent gating.
 - [Triggers](triggers.md): configure webhooks and cron schedules for private agent instances.
 - [MCP](mcp.md): connect Codex, Claude Code, Cursor, and other MCP clients to the official ProAgentStore MCP server.
 - [Browser Runtime](browser-runtime.md): run local browser and CLI capabilities with `pags up`.