@oar-sh/oar 0.9.3 → 0.9.4

package/.github/extensions/web-relay/extension.mjs

@@ -97,7 +97,12 @@ const bannerStateStore = createBannerStateStore({
 
 const buildPromptWithRelayContext = createRelayPromptBuilder({
   toolInstructions: RELAY_TOOL_INSTRUCTIONS,
-  getPreviewInstructions: createPreviewInstructionsProvider({ api }),
+  // With the OAR MCP server attached (session-worker-launch-service sets the
+  // flag), the CLI has a real `preview` tool: the HTTP-API instructions would
+  // only contradict it, so the section is dropped.
+  getPreviewInstructions: process.env.OAR_MCP_SERVER_ATTACHED === "1"
+    ? null
+    : createPreviewInstructionsProvider({ api }),
 });
 
 const managedServerLifecycle = createManagedServerLifecycle({

package/.github/extensions/web-relay/skills/tool-activity.mjs

@@ -3,6 +3,8 @@ import {
   formatToolResultActivity as formatSharedToolResultActivity,
   formatVoteMemoryActivity,
 } from "../../../../shared/tool-activity.mjs";
+import { isRemoteRelayToolName } from "../../../../shared/remote-relay-tool-core.mjs";
+import { summarizeRemoteRelayCall } from "../../../../shared/remote-relay-contract.mjs";
 
 export function normalizeActivityText(value, maxToolDetailLength = 140) {
   const text = String(value || "").trim();
@@ -133,6 +135,11 @@ export function formatToolActivity(request, maxToolDetailLength = 140) {
   if (lower.includes("report_intent")) {
     return detail ? `● ${detail}` : "● Working…";
   }
+  // The OAR MCP server's tool reaches the CLI as `oar-remote_relay`: show the
+  // same line every other engine writes for it.
+  if (isRemoteRelayToolName(rawName)) {
+    return `Tool (remote_relay): ${summarizeRemoteRelayCall(toolArgsSnapshot(request))}`;
+  }
   return detail ? `Tool (${rawName}): ${detail}` : `Tool (${rawName})`;
 }
 

package/CHANGELOG.md

@@ -5,6 +5,73 @@ All notable changes to OAR are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.9.4] — 2026-09-27
+
+Highlights: remote relays (pair OAR relays and let an agent on one work on the
+other), follow toggles for the running reply, and a Suspend host that waits for
+agents, background tasks and CI to finish.
+
+### Added
+
+- **Remote relays**: pair OAR relays in **Settings → Relays** by pasting the other
+  relay's web address; the pairing works both ways. Agents of every provider get a
+  `remote_relay` tool to list and read the other relay's sessions, prompt one, start
+  a new one, wait for its reply and relay its questions to you. A relay unlocks in a
+  conversation only once you mention it (`@` picks it from a list). Per relay, agents
+  may read, prompt or do everything; in ask and plan mode each write action asks you
+  first. The receiving relay marks such messages with a **↗ from …** badge. Tokens
+  stay on the relay; agents never see them.
+- **OAR MCP server** (`server/mcp/oar-mcp-server.mjs`): Grok and the Copilot
+  extension engine now get the `preview` and `remote_relay` tools as real tools
+  instead of instruction text.
+- **Follow the live reply**: three toggles in the running reply's header keep
+  its thoughts, its answer or its tool list pinned just above the composer as
+  the reply grows. Scrolling the transcript by hand turns it off; typing in the
+  composer does not. The choice is remembered per conversation until the page
+  reloads.
+- A queued relay restart shows a banner on every client, with a **Cancel**
+  button (a new localhost-only cancel endpoint behind it).
+
+### Changed
+
+- **Suspend host waits for the work to finish.** Instead of sleeping the
+  machine at once, the relay queues the suspend and fires it after 2 minutes
+  with nothing active: no queued, running or parked turn, no background task of
+  a live worker, and no open GitHub Actions run in a busy conversation's
+  repository (read through `gh`; a repository whose state cannot be read blocks
+  for 15 minutes, then is ignored). With nothing running at confirm time it
+  fires after a 30-second countdown. The confirmation lists what is still
+  active, every client shows a banner with the blockers or the countdown and a
+  **Cancel** button, and a push notification reports the suspend, or its drop
+  when the relay restarts. Suspend remains Windows-only;
+  `OAR_HOST_SUSPEND_DRY_RUN=1` logs instead of suspending.
+- **Stop** asks for confirmation before cancelling the running turn.
+- The **Install app name** setting is now called **Relay name**. Your value is
+  kept. It still labels the installed app, and it is the name paired relays
+  know this relay by; when it is empty, paired relays see the machine's
+  hostname.
+- Dependency updates clear all five `npm audit` findings, one of them rated
+  high: express 4.22.3, body-parser 1.20.8, qs 6.16.0, fast-uri 3.1.8 and
+  hono 4.13.9. All were inside the declared ranges, so `package.json` is
+  unchanged; a git checkout gets them with `npm ci`.
+
+### Fixed
+
+- Switching the Claude model in a conversation that already had replies no
+  longer strands the next message. The reply to the message that carried the
+  switch landed on a *continuation* row while the message itself stayed
+  processing, and every later message waited behind it for up to 5 minutes, or
+  until the session was killed.
+- **Requests on an idle connection are no longer reset.** The relay closed a
+  kept-alive connection after 5 seconds without traffic, so a request sent on
+  it a moment later could be reset before the relay read a byte. Behind a
+  reverse proxy or tunnel that pools its connections this showed up as an
+  occasional 502, and a send was not repeated. Idle connections now stay open
+  for 65 seconds.
+- After a send, the transcript stays at the newest message when the composer
+  grows (a session note or a warning banner appearing under it). It used to
+  slip up until the draft was saved.
+
 ## [0.9.3] — 2026-09-27
 
 Highlights: mid-turn steering on Claude and Copilot, Copilot background tasks on

package/README.md

@@ -78,7 +78,7 @@ curl -fsSL oar.sh/install | sh
 The script checks for Node.js 22.13 or newer, runs `npm install -g @oar-sh/oar`, and then hands off to `oar setup` (with `--defaults` when there is no terminal to ask questions in). It refuses to run as root, because OAR installs per user. `OAR_VERSION=x.y.z` pins a version, `OAR_CHANNEL=beta` follows the beta channel, and `OAR_DRY_RUN=1` only prints what it would do:
 
 ```bash
-curl -fsSL oar.sh/install | OAR_VERSION=0.9.3 sh
+curl -fsSL oar.sh/install | OAR_VERSION=0.9.4 sh
 ```
 
 Read it before you run it: [oar.sh/install](https://oar.sh/install).
@@ -89,7 +89,7 @@ Read it before you run it: [oar.sh/install](https://oar.sh/install).
 irm oar.sh/install.ps1 | iex
 ```
 
-The PowerShell installer (PowerShell 5 or newer) does the same: it checks Node.js, runs `npm install -g @oar-sh/oar`, then `oar setup`. It reads the same `OAR_VERSION`, `OAR_CHANNEL`, and `OAR_DRY_RUN` variables, for example `$env:OAR_VERSION = '0.9.3'` before the command.
+The PowerShell installer (PowerShell 5 or newer) does the same: it checks Node.js, runs `npm install -g @oar-sh/oar`, then `oar setup`. It reads the same `OAR_VERSION`, `OAR_CHANNEL`, and `OAR_DRY_RUN` variables, for example `$env:OAR_VERSION = '0.9.4'` before the command.
 
 ### npm
 
@@ -326,15 +326,15 @@ Use **🤗 Select Models** to choose which variants show up in the composer, the
 
 ## Highlights
 
-### New in 0.9.3
+### New in 0.9.4
 
-- **Mid-turn steering** for Claude, and for Copilot on the SDK engine with every model, hosted or BYOK: a message you send while a turn runs goes into that turn instead of waiting behind it. The send button reads **Steer**; while a question card, plan approval, or compaction is open it reads **Queue**, and the message steers in once that is resolved, so a question card is never bypassed. **Stop** lives on the running reply's bubble, and steered messages that a Stop cut off offer a one-tap **Resend**.
-- **Copilot background tasks** (SDK engine): background agents and detached shells appear in the task panel with the model they run on, the command they are running right now, their token count, and a **Stop** that works. The reply no longer waits for them; a background agent's result arrives afterwards as its own *continuation* reply.
-- **Multi-select question cards**: a question that allows several answers shows checkmarks and one **Reply with selection** button. Claude cards follow Claude's own flag; Copilot choice cards (SDK engine) also carry a **Select several** switch for when the model forgets to flag it.
-- **Drafts sync safely across devices**: an idle device no longer overwrites the draft you are typing on another one, and when two devices edit at once, the text that lost is offered back with **Restore**.
-- **Sidebar title filter** above the conversation list. It loads older pages while it is active, so it searches every conversation, not just the loaded ones.
-- **Deleting a conversation stops its worker and removes the CLI session OAR created for it** (Copilot's through the runtime, Claude's by deleting that session's transcript). A Copilot session OAR only imported from the host, one you started in a terminal, is hidden instead, and nothing is stopped for it. A conversation that is still working is not deleted; the sidebar tells you why, so you can stop it first.
-- The **Background task timeout** defaults to **4 hours** instead of no limit, for Claude and Copilot alike: long-running work still finishes, but a forgotten shell or agent no longer keeps its session alive forever. A value you already chose is kept.
+- **Remote relays**: pair two OAR relays in **Settings → Relays** by pasting the other relay's web address; the pairing works both ways. An agent in any session can then work on the other relay when you ask it to: list and read its sessions, prompt one, start a new one, wait for the reply, and pass a question the remote agent asks back to you. See [Remote relays](#remote-relays).
+- **You decide when a relay is in reach**: a paired relay stays locked in a conversation until you mention it (`@` picks it from a list). Per relay, **Agents may** limits agents to *read only*, *read and prompt*, or *full*, and in ask and plan mode every write action asks you first. The receiving relay marks such messages with a **↗ from …** badge.
+- **Every provider gets the same tools**: Grok and the Copilot extension engine now get `remote_relay` and `preview` as real tools through OAR's MCP server, instead of instruction text.
+- **Follow the live reply**: three toggles in the running reply's header keep its thoughts, its answer, or its tool list pinned just above the composer as the reply grows. Scrolling the transcript by hand turns it off; typing in the composer does not.
+- **Suspend host waits for the work to finish** (Windows): the relay queues the suspend and fires it after 2 minutes with no turn, background task, or GitHub Actions run active, or after a 30-second countdown when nothing was running. Every device shows a banner with what is still active and a **Cancel** button; a queued relay restart shows the same banner.
+- **Stop** asks for confirmation before it cancels the running turn.
+- **Fewer stuck and failed sends**: switching the Claude model mid-conversation no longer strands the next message, and the relay keeps idle connections open for 65 seconds, so a request sent after a short pause is no longer reset (behind a proxy or tunnel: an occasional 502).
 
 ### Everything else
 
@@ -438,7 +438,7 @@ Use **➡️ Share conversation** in the `⋯` menu to publish a read-only link.
 ### Notifications and the app
 
 - **⚙️ Settings → Notifications** turns on push notifications per device: for questions from the agent, completed or failed turns, plan boards, and the CLI going offline. They need a secure context (HTTPS, or `localhost`), are sent only while no device has the app in the foreground, and show generic text unless you opt in to message previews on that device.
-- The **⬇** button in the sidebar installs OAR as an app (PWA). **Install app name** in Settings sets its label on every device that connects to this relay.
+- The **⬇** button in the sidebar installs OAR as an app (PWA). **Relay name** in Settings sets its label on every device that connects to this relay, and is the name [paired relays](#remote-relays) know it by.
 
 ### The conversation menu
 
@@ -448,7 +448,7 @@ Besides the entries above, the `⋯` menu holds **✍️ Edit conversation title
 
 ### Settings (⚙️ in the web UI)
 
-The modal is organised into five tabs — **General**, **Providers** (with a **Copilot**, **OpenAI**, **Claude**, **Grok**, and **Cursor** sub-tab), **Previews**, **Notifications**, and **Features** — and reopens on the tab you used last. Unless noted as per browser, these settings live in the relay database rather than the config file, and apply to every browser that connects:
+The modal is organised into six tabs — **General**, **Providers** (with a **Copilot**, **OpenAI**, **Claude**, **Grok**, and **Cursor** sub-tab), **Relays**, **Previews**, **Notifications**, and **Features** — and reopens on the tab you used last. Unless noted as per browser, these settings live in the relay database rather than the config file, and apply to every browser that connects:
 
 | Tab | Setting | Default | What it does |
 | --- | ------- | ------- | ------------ |
@@ -457,7 +457,7 @@ The modal is organised into five tabs — **General**, **Providers** (with a **C
 | General | Max turn duration | `60 min` | Hard cap on how long one turn may run before the relay requeues it (0 = no limit, up to 10 h; see below) |
 | General | Background task timeout | `4 h` | How long background tasks alone may keep a Claude or Copilot session running after its reply; then they are stopped (0 = no limit, up to 10 h) |
 | General | Autostart (Windows) | Off | *At sign-in* (a visible terminal after you log on) or *At system startup* (headless, no logon needed, one admin confirmation) |
-| General | Install app name | `OAR` | Label of the installed PWA on every device |
+| General | Relay name | `OAR` (the hostname for paired relays) | Label of the installed PWA on every device, and this relay's name for [paired relays](#remote-relays) |
 | General | Check for updates automatically | off | Opt-in: the relay asks oar.sh for the latest version about twice a day. **Check for updates** works regardless; `OAR_NO_UPDATE_CHECK=1` blocks both |
 | General | Default CWD for new sessions | relay workspace root | Working directory for newly created sessions that have none of their own |
 | Providers | Copilot engine | SDK | Extension when this relay cannot run the SDK engine (see [engine choice](#github-copilot--engine-choice)) |
@@ -466,6 +466,8 @@ The modal is organised into five tabs — **General**, **Providers** (with a **C
 | Providers | Claude account (Relogin / Logout) | host login | Switches the Claude account the relay host's CLI uses, from the browser (see [Claude (Agent SDK)](#claude-agent-sdk)) |
 | Providers | Cursor API key / model | — / `composer-2.5` | Enables Cursor; plus monthly plan allowances and the optional dashboard session token |
 | Providers | Grok | off | Enables Grok; default model `grok-4.5`; **Sign in** / **Sign out**; optional monthly allowance |
+| Relays | Public address, Accept prompts from other relays' agents | browser address / on | How paired relays reach this one, and whether their agents may prompt sessions here (see [Remote relays](#remote-relays)) |
+| Relays | Remote relays | — | Pair a relay by pasting its web address; per relay **Agents may** read only, read and prompt, or do everything |
 | Previews | Live previews | — | Lists the published previews, each of which you can close |
 | Notifications | Push notifications | off | Per device: which events notify, and whether titles and message previews are included |
 | Features | Feature flags | see below | **Session worker routing** (on), **Continuation answer routing** (on), **Generated-image continuity** (on), and a reserved **Worker fallback restart** (off, no effect yet). Changes apply after a relay restart; a `COPILOT_REMOTE_<FLAG>` environment variable pins a flag, e.g. `COPILOT_REMOTE_SESSION_WORKER_ROUTING_ENABLED=0` |
@@ -638,6 +640,52 @@ covering `/api/shared/*` — shared views poll for liveness and an edge-cached r
 would pin viewers to a stale snapshot. Likewise, a Cloudflare Access application over the
 bound hostname breaks share links unless it bypasses `/shared/*` and `/api/shared/*`.
 
+## Remote relays
+
+Several OAR relays can be paired, for example the one on your workstation and the one on a
+server. An agent in any session can then work on the other relay when you ask it to: list and
+read its sessions, prompt one, start a new one, wait for the reply, and pass a question the
+remote agent asks back to you.
+
+**Pairing.** Open **Settings → Relays** and paste the other relay's web address (the URL you
+open it with in the browser). OAR checks the address with its own token, or with a
+`?token=` the pasted link carries, and asks for a token only when that fails. It reads the
+other relay's name from its API. With **Also add this relay there** checked, it introduces
+itself to the other relay using the address in **Public address**, so the pairing works in both
+directions. When the two relays use different tokens, that introduction hands over this relay's
+token, so the other relay's agents can then work here. Each side can remove the other on its own,
+but removing a relay does not revoke a token it already holds: rotate the token for that. A relay
+that is already paired keeps the address and token stored for it when it introduces itself again;
+change those in **Settings → Relays**.
+
+A relay's name is the **Relay name** under **General** (it also names the installed app); when it
+is empty, the machine's hostname is used.
+
+**Mention a relay to unlock it.** Agents can see which relays are paired, but a relay stays
+locked in a conversation until you mention it in one of your messages: type `@` and pick it
+from the list, or write its name or its host name. An IP address or `localhost` never counts as a
+host name; a relay whose name is itself an address is unlocked only with a leading `@`. The
+mention unlocks that relay for the rest of
+the conversation. Prompts that arrive from another relay's agent never unlock anything, and a
+chain of relays prompting relays stops after two hops.
+
+**What agents can do.** Every provider gets the same `remote_relay` tool (Claude, Cursor and
+Copilot directly; Grok and the Copilot extension engine through OAR's MCP server). Per paired
+relay, **Agents may** limits it to *read only*, *read and prompt* (existing sessions) or *full*
+(also create sessions, answer questions, stop turns, archive). In the *ask* and *plan* relay
+modes, every write action first asks you with a question card.
+
+When an agent prompts a session on another relay, that relay shows a **↗ from …** badge with the
+sending relay, session and model on the message, and marks sessions an agent created in the
+conversation list. The remote agent sees a one-line header saying that another agent is talking
+to it. Turns started this way do not send "reply ready" notifications on the remote relay;
+question cards still do. **Accept prompts from other relays' agents** in **Settings → Relays**
+switches incoming agent prompts off.
+
+The calls go through your own relay, which holds the other relay's token: agents never see a
+token. Remote addresses must use `https://`; plain `http://` is accepted only for loopback (an
+SSH port forward, for example) and private network ranges.
+
 ## Security notes
 
 - The auth token guards the API and the Socket.IO channel. A browser signs in once, with the token or with a URL carrying `?token=` (such as the one `oar setup` prints and puts in its QR code), and then holds an HttpOnly cookie for 30 days, marked `Secure` when the relay is reached over HTTPS. Treat the token, and that URL, like a password.
@@ -645,6 +693,7 @@ bound hostname breaks share links unless it bypasses `/shared/*` and `/api/share
 - `localhostOnly` (default `true`) keeps the relay on loopback. Beyond your LAN, use HTTPS through one of the [tunnels](#remote-access) rather than an open port.
 - Agents act with the permissions of the user the relay runs as. OAR adds reach, not a sandbox: whoever holds the token can have them run commands on the host. `workspaceRootAllowList` limits the directories conversations may start in.
 - Shared conversation links and preview links are public by design: anyone with the URL can read the shared transcript or reach the previewed app, without signing in.
+- A [paired relay](#remote-relays) holds a token that opens the other relay completely. The per-relay "Agents may" limit and the "Accept prompts from other relays' agents" switch are honoured by OAR's own traffic, but anyone holding the token can still use the full API: the token is the real boundary. A token entered for a paired relay is stored like the API keys below and never sent to browsers or agents.
 - API keys you enter (OpenAI, Cursor) are stored in the relay database on the host and never sent to browsers. Claude and Grok credentials stay with their CLIs on the host.
 - OAR has no telemetry. Its only request to oar.sh is the update check, which is off until you enable it.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oar-sh/oar",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "type": "module",
   "description": "OAR — Open Agent Relay: drive your local coding agents from any browser",
   "license": "MIT",
@@ -40,9 +40,12 @@
   "scripts": {
     "start": "node server/server.js",
     "copilot:relay": "gh copilot -- --allow-all",
-    "test": "node --test \"server/**/*.test.mjs\" \"shared/**/*.test.mjs\" \".github/extensions/web-relay/**/*.test.mjs\"",
+    "test": "node --test \"server/**/*.test.mjs\" \"shared/**/*.test.mjs\" \".github/extensions/web-relay/**/*.test.mjs\" \"scripts/**/*.test.mjs\"",
     "test:agents:smoke": "node --test \"tests/agents/**/*.test.mjs\"",
     "test:e2e": "node tests/run-e2e.mjs",
+    "setup:git": "node scripts/setup-git.mjs",
+    "land": "node scripts/land.mjs",
+    "prune:local": "node scripts/prune-local.mjs",
     "test:e2e:raw": "node ./node_modules/@playwright/test/cli.js test --config tests/playwright.config.mjs"
   },
   "dependencies": {

package/server/README.md

@@ -193,7 +193,7 @@ where supported (with standalone fallback), and hides install/fullscreen header
 When opened in a regular browser tab, the in-app **Install** button remains available
 in the chat header (shown as `⬇` on small screens).
 
-You can rename the installed app label from **⚙️ Settings → Install app name**.
+You can rename the installed app label from **⚙️ Settings → Relay name** (paired relays know this relay by the same name).
 The name is stored on the relay (app settings) and served in the web app manifest
 to every browser and origin (LAN and tunnel agree), so future installs pick it up
 immediately and already-installed Android apps receive it through Chrome's normal
@@ -201,9 +201,34 @@ manifest-update flow — one confirmation prompt showing the new name, then the
 launcher label updates. A legacy per-browser name is adopted by the relay the
 first time that browser loads the app.
 
+**💤 Suspend host** (Windows relay hosts) puts the PC into suspend-to-RAM once
+nothing is running any more. The confirmation modal first lists what is still
+active — sessions with a running turn, sessions with live background agents, and
+open GitHub Actions runs in the workspaces of those sessions (read through the
+host's `gh` CLI; an unreadable CI state blocks for 15 minutes, then is ignored).
+Confirming queues the request: the relay polls every second and suspends after
+everything has been idle for 2 minutes (or 30 seconds when nothing was running
+at confirm time). While a suspend is queued every connected client shows a
+banner with the blockers or the countdown and a **Cancel** button, the menu entry
+reads **💤 Suspend pending…**, and reopening the modal offers to cancel. A relay
+restart drops the queued suspend; a push notification (event **Host suspend**)
+reports both the actual suspend and such a drop. A queued **🌄 Restart web relay**
+gets the same banner and can be cancelled from it too.
+
+API: `GET /api/host/suspend` (state plus current blockers), `POST /api/host/suspend`,
+`POST /api/host/suspend/cancel`, and `POST /api/relay/shutdown/cancel`
+(localhost-only). Set `OAR_HOST_SUSPEND_DRY_RUN=1` to log instead of sleeping.
+
 You can also hide the **💤 Suspend host** action from **⚙️ Settings** with the
-**Show Suspend host action** checkbox. This only controls UI visibility; it does not
-change host suspend implementation behavior.
+**Show Suspend host action** checkbox. This only controls the menu entry; the
+banner for an already queued suspend still shows on every device.
+
+The live thinking bubble's header carries three follow buttons on the right —
+**💭** thoughts, **📃** streamed answer, **🛠️** tool list. Arming one keeps that
+section's last line pinned just above the composer as the reply grows; scrolling
+the transcript by hand (wheel, touch, scroll keys) disarms it, typing in the
+composer does not. The armed mode is remembered per conversation for the life of
+the page. **Stop** now asks for confirmation before cancelling the turn.
 
 If you host the relay behind a subpath, set `remotePath` in `server/config.json` to that public path prefix and open the URL with a trailing slash so the PWA scope matches correctly for install prompts. The relay serves a path-relative manifest identity (`id`, `start_url`, `scope`) so each install stays bound to its own URL subtree and avoids cross-app collisions on shared origins.
 
@@ -821,6 +846,17 @@ Queue metrics include `parkedCount` for turns deferred behind restart/rebind gat
 | POST | `/api/openai/images/generate` | Generate images for an OpenAI Image conversation |
 | POST | `/api/image-operations/:operationId/execute` | Execute a queued image generation/edit operation |
 | GET | `/api/generated-image/:conversationId/:messageId/:imageId/content` | Stream a generated image blob |
+| GET | `/api/relay/identity` | This relay's identity for paired relays: `relayId`, `name` (the PWA app name, else the hostname), `version`, `platform`, `publicUrl`, `remoteRelays.{protocol, inbound}` |
+| GET | `/api/remote-relays` | Paired remote relays with their status (`relays[]`, never a token) plus `self` |
+| POST | `/api/remote-relays` | Pair a relay from a pasted web address (`url`, optional `token`, `pairBack`, `selfUrl`); `{ needsToken: true }` when neither token works |
+| PATCH | `/api/remote-relays/:id` | Change a paired relay's `permission` (`read` / `prompt` / `full`), URL or token |
+| DELETE | `/api/remote-relays/:id` | Remove a paired relay here (the other side keeps its entry) |
+| POST | `/api/remote-relays/:id/check` | Probe a paired relay now |
+| POST | `/api/remote-relays/pair` | (Relay to relay) Another relay introduces itself after the user paired it there |
+| GET | `/api/remote-relays/summary` | (Worker) Number of paired relays; workers register `remote_relay` only when it is above zero |
+| POST | `/api/remote-relays/tool` | (Worker) One `remote_relay` tool call: `{ conversationId, action, args }`. The relay checks the mention unlock, the permission, the hop limit and (ask/plan mode) the user's approval, then forwards the call to the remote |
+| GET | `/api/remote-relays/inflight` | (Worker) Number of `remote_relay` calls running for `conversationId` |
+| GET/POST | `/api/settings/remote-relays` | This relay's `publicUrl` and `inboundEnabled` (accept prompts from other relays' agents) |
 
 ### Manual relay shutdown / self-restart
 
@@ -1378,6 +1414,10 @@ and on `messages`:
 - `hidden_from_shares` / `share_hidden_at` — per-message share visibility (see
   [Conversation sharing](#conversation-sharing-and-per-message-visibility))
 
+`0005-remote-relays.mjs` adds `origin_json` to `messages` and `conversations` (provenance of
+prompts and sessions another relay's agent created) and the table
+`conversation_remote_relay_unlocks` (the remote relays the user mentioned per conversation).
+
 New tables are likewise created at startup with `CREATE TABLE IF NOT EXISTS` in both the fresh-schema
 and migration blocks — most recently `workflow_runs` (final workflow digest per assistant message,
 keyed on `response_message_id`, cascade-deleted with the conversation; see

package/server/claude-worker/claude-remote-relay-tool.mjs

@@ -0,0 +1,99 @@
+/**
+ * The relay's `remote_relay` tool for the Claude worker, shaped as an SDK MCP
+ * tool definition (`{ name, description, inputSchema, handler }`) so the
+ * adapter can hand it to `createSdkMcpServer` next to the preview tool. On the
+ * wire it is `mcp__relay__remote_relay`; the module never imports the SDK.
+ */
+
+import * as z from 'zod';
+
+import {
+  REMOTE_RELAY_ACTIONS,
+  REMOTE_RELAY_IF_BUSY,
+  REMOTE_RELAY_MODES,
+  REMOTE_RELAY_PROVIDERS,
+  REMOTE_RELAY_SESSION_SCOPES,
+} from '../../shared/remote-relay-contract.mjs';
+import {
+  REMOTE_RELAY_CALL_FAILED,
+  REMOTE_RELAY_TOOL_DESCRIPTION,
+  REMOTE_RELAY_TOOL_INPUT_SCHEMA,
+  REMOTE_RELAY_TOOL_NAME,
+  executeRemoteRelayTool,
+  formatRemoteRelayToolResult,
+} from '../../shared/remote-relay-tool-core.mjs';
+
+const FIELDS = REMOTE_RELAY_TOOL_INPUT_SCHEMA.properties;
+
+function text(field) {
+  return z.string().optional().describe(FIELDS[field].description);
+}
+
+function choice(field, values) {
+  return z.enum([...values]).optional().describe(FIELDS[field].description);
+}
+
+function number(field) {
+  return z.number().optional().describe(FIELDS[field].description);
+}
+
+/**
+ * The contract's JSON schema mirrored as a zod raw shape (the SDK's MCP layer
+ * accepts zod only). Descriptions and enum values are read from the contract,
+ * so the model sees the same field docs on every provider. Numeric bounds are
+ * left off on purpose, as on the preview tool: the contract's validator clamps
+ * wait_seconds / limit / last / max_chars instead of failing the call.
+ */
+export const REMOTE_RELAY_TOOL_ZOD_SHAPE = {
+  action: z.enum([...REMOTE_RELAY_ACTIONS]).describe(FIELDS.action.description),
+  relay: text('relay'),
+  session: text('session'),
+  text: text('text'),
+  message_id: text('message_id'),
+  wait_seconds: number('wait_seconds'),
+  scope: choice('scope', REMOTE_RELAY_SESSION_SCOPES),
+  query: text('query'),
+  limit: number('limit'),
+  cursor: text('cursor'),
+  last: number('last'),
+  before: text('before'),
+  include_activity: z.boolean().optional().describe(FIELDS.include_activity.description),
+  max_chars: number('max_chars'),
+  provider: choice('provider', REMOTE_RELAY_PROVIDERS),
+  model: text('model'),
+  cwd: text('cwd'),
+  mode: choice('mode', REMOTE_RELAY_MODES),
+  title: text('title'),
+  question_id: text('question_id'),
+  answer: text('answer'),
+  choices: z.array(z.string()).optional().describe(FIELDS.choices.description),
+  if_busy: choice('if_busy', REMOTE_RELAY_IF_BUSY),
+};
+
+export function createRemoteRelayToolDefinition({ api, getConversationId = () => '', dbg = () => {} } = {}) {
+  return {
+    name: REMOTE_RELAY_TOOL_NAME,
+    description: REMOTE_RELAY_TOOL_DESCRIPTION,
+    inputSchema: REMOTE_RELAY_TOOL_ZOD_SHAPE,
+    // `extra.signal` is the MCP request's: the SDK aborts it when the CLI
+    // cancels the call (a Stop interrupting the turn) or the process's MCP
+    // transport closes, and the pending relay request goes with it.
+    handler: async (args, extra) => {
+      let result;
+      try {
+        result = await executeRemoteRelayTool(args, {
+          api,
+          conversationId: String(getConversationId() || ''),
+          signal: extra?.signal || null,
+        });
+      } catch (error) {
+        // A tool exception would surface as a failed MCP call and can abort
+        // the turn; a refusal the model can read cannot.
+        const message = error?.message || String(error);
+        dbg('remote_relay tool failed', message);
+        result = { ok: false, code: REMOTE_RELAY_CALL_FAILED, error: message };
+      }
+      return { content: [{ type: 'text', text: formatRemoteRelayToolResult(result) }] };
+    },
+  };
+}

package/server/claude-worker/claude-sdk-adapter.mjs

@@ -2,12 +2,23 @@ import { createSdkMcpServer, query } from '@anthropic-ai/claude-agent-sdk';
 
 import { parseThinkingDisplay } from '../../shared/claude-thinking.mjs';
 import { MEDIA_EMBED_INSTRUCTION_TEXT } from '../../shared/media-embed-instructions.mjs';
+import { REMOTE_RELAY_TOOL_CALL_TIMEOUT_MS } from '../../shared/remote-relay-tool-core.mjs';
 import { createPreviewToolDefinition } from './claude-preview-tool.mjs';
+import { createRemoteRelayToolDefinition } from './claude-remote-relay-tool.mjs';
 
 // The name the in-process MCP server is registered under; it prefixes every
-// tool it carries on the wire (`mcp__relay__preview`).
+// tool it carries on the wire (`mcp__relay__preview`, `mcp__relay__remote_relay`).
 export const RELAY_MCP_SERVER_NAME = 'relay';
 
+// The per-server tool-call timeout the CLI applies to the relay's tools.
+// Measured against CLI 2.1.283: an SDK server's calls are bounded by this
+// value, else by the MCP_TOOL_TIMEOUT environment variable, else by 1e8 ms —
+// and SDK servers are exempt from the idle timeout. Pinning it here keeps a
+// host-wide MCP_TOOL_TIMEOUT (set for some other server) from cutting off a
+// remote_relay wait: those run up to wait_seconds (≤ 600 s) plus however long
+// an approval card sits unanswered.
+export const RELAY_MCP_TOOL_TIMEOUT_MS = REMOTE_RELAY_TOOL_CALL_TIMEOUT_MS;
+
 const MODE_SYSTEM_PROMPT_APPEND = {
   ask: 'Prioritize clarification questions (AskUserQuestion) before implementation work; do not make broad assumptions when a question would materially change the result.',
   autopilot: 'Keep moving unless user input is truly blocking; avoid unnecessary questions.',
@@ -143,11 +154,19 @@ export function systemPromptForRelayMode(relayMode) {
  * which beats inventing a capability flag to plumb through the delivery
  * payload. `getConversationId` is called per tool call because a process
  * outlives the turn it was spawned for.
+ *
+ * `remote_relay` is the exception: it rides along only when the worker found
+ * at least one paired remote (`remoteRelayTool`), because a tool that can do
+ * nothing on a relay without remotes would only cost context on every turn.
  */
-export function createRelayMcpServer({ api, getConversationId, dbg } = {}) {
+export function createRelayMcpServer({ api, getConversationId, dbg, remoteRelayTool = false } = {}) {
   return createSdkMcpServer({
     name: RELAY_MCP_SERVER_NAME,
-    tools: [createPreviewToolDefinition({ api, getConversationId, dbg })],
+    timeout: RELAY_MCP_TOOL_TIMEOUT_MS,
+    tools: [
+      createPreviewToolDefinition({ api, getConversationId, dbg }),
+      ...(remoteRelayTool ? [createRemoteRelayToolDefinition({ api, getConversationId, dbg })] : []),
+    ],
   });
 }
 
@@ -215,6 +234,9 @@ export function startClaudeSession({
   pathToClaudeCodeExecutable = '',
   api = null,
   getConversationId = () => '',
+  // Whether this process carries `remote_relay` (the worker's registration
+  // decision). Fixed for the process: the tool list is part of the spawn.
+  remoteRelayTool = false,
   queryImpl = query,
   dbg = () => {},
 } = {}) {
@@ -230,7 +252,7 @@ export function startClaudeSession({
   // Relay tools need the worker's authenticated API helper; a caller that
   // passes none (tests, probes) gets a session without them.
   const relayMcpServer = typeof api === 'function'
-    ? createRelayMcpServer({ api, getConversationId, dbg })
+    ? createRelayMcpServer({ api, getConversationId, dbg, remoteRelayTool: remoteRelayTool === true })
     : null;
   const options = {
     cwd,