@oar-sh/oar 0.9.2 → 0.9.4

package/bin/oar.js

@@ -17,7 +17,7 @@ function resolvePackageRoot(metaUrl = import.meta.url) {
   return path.resolve(path.dirname(fileURLToPath(metaUrl)), '..');
 }
 
-function parsePort(argv = []) {
+function parsePort(argv = [], fallback = 3333) {
   const args = Array.isArray(argv) ? argv : [];
   for (let index = 0; index < args.length; index += 1) {
     const arg = String(args[index] || '');
@@ -30,7 +30,12 @@ function parsePort(argv = []) {
       if (Number.isInteger(parsed) && parsed > 0 && parsed <= 65535) return parsed;
     }
   }
-  return 3333;
+  return fallback;
+}
+
+function normalizePort(value) {
+  const parsed = Number.parseInt(String(value ?? ''), 10);
+  return Number.isInteger(parsed) && parsed > 0 && parsed <= 65535 ? parsed : null;
 }
 
 function readRelayLock(lockPath) {
@@ -184,7 +189,7 @@ function createDefaultConfig({ port = 3333, token = '' } = {}) {
   };
 }
 
-function resolveLauncherConfig({ packageRoot, env = process.env, relayToken = '', relayPort = 3333, layout = null } = {}) {
+function resolveConfigPaths({ packageRoot, env = process.env, layout = null } = {}) {
   const envConfigPath = String(env.COPILOT_WEB_RELAY_CONFIG || '').trim();
   const repoConfigPath = path.join(packageRoot, 'server', 'config.json');
   const oarConfigPath = layout && !layout.checkout ? path.join(layout.configDir, 'config.json') : null;
@@ -195,7 +200,11 @@ function resolveLauncherConfig({ packageRoot, env = process.env, relayToken = ''
     || null
   );
   const managedPath = oarConfigPath || path.join(getLegacyManagedConfigDir(env), 'config.json');
-  const configPath = seedPath || managedPath;
+  return { seedPath, configPath: seedPath || managedPath };
+}
+
+function resolveLauncherConfig({ packageRoot, env = process.env, relayToken = '', relayPort = 3333, portOverride = null, layout = null } = {}) {
+  const { seedPath, configPath } = resolveConfigPaths({ packageRoot, env, layout });
   const seedConfig = readJsonFile(seedPath) || {};
   const runtimeConfig = {
     ...createDefaultConfig({ port: relayPort }),
@@ -203,10 +212,9 @@ function resolveLauncherConfig({ packageRoot, env = process.env, relayToken = ''
   };
   if (relayToken) runtimeConfig.authToken = relayToken;
   if (!String(runtimeConfig.authToken || '').trim()) runtimeConfig.authToken = randomUUID();
-  const parsedPort = Number.parseInt(String(runtimeConfig.port || relayPort || 3333), 10);
-  runtimeConfig.port = Number.isInteger(parsedPort) && parsedPort > 0 && parsedPort <= 65535
-    ? parsedPort
-    : 3333;
+  // An explicit --port wins over the config for this run: the server gets it
+  // on argv, and only a config this command creates saves it.
+  runtimeConfig.port = normalizePort(portOverride) ?? normalizePort(runtimeConfig.port) ?? normalizePort(relayPort) ?? 3333;
   return {
     configPath,
     managed: !seedPath,
@@ -262,7 +270,7 @@ export async function launchRelay({
   const forwardedArgs = separatorIdx === -1 ? [] : args.slice(separatorIdx + 1);
   if (args.includes('--help') || args.includes('-h')) {
     logger.log([
-      'Usage: oar [--port <port>] [--token <token>] [--migrate-from <old-checkout>] [--install-extension] [--no-install-extension] [-- [gh copilot args...]]',
+      'Usage: oar [--port <port>] [--migrate-from <old-checkout>] [--install-extension] [--no-install-extension] [-- [gh copilot args...]]',
       '',
       'Starts the web relay server if needed, then launches gh copilot in the current shell.',
       '--install-extension installs/updates a user-global web-relay wrapper extension and exits.',
@@ -284,7 +292,7 @@ export async function launchRelay({
     return { code: 0, reason: 'extension-installed' };
   }
 
-  const port = parsePort(launcherArgs);
+  const cliPort = parsePort(launcherArgs, null);
   const serverDir = path.join(packageRoot, 'server');
   const layout = resolveStateLayout({ packageRoot, env });
 
@@ -311,6 +319,12 @@ export async function launchRelay({
   const lockPath = layout.checkout
     ? path.join(serverDir, 'data', 'relay-server.lock')
     : path.join(layout.dataDir, 'relay-server.lock');
+  // One port finds, launches and probes the relay: an explicit --port for this
+  // run, else the config's, else 3333. The probe used to take --port (or 3333)
+  // while the server started on the config's port, so any mismatch waited out
+  // the readiness deadline and killed the relay it had just started.
+  const { seedPath } = resolveConfigPaths({ packageRoot, env, layout });
+  const port = cliPort ?? normalizePort(readJsonFile(seedPath)?.port) ?? 3333;
   const statusUrl = `http://localhost:${port}/api/status`;
   const running = await detectRunningRelay({
     lockPath,
@@ -323,6 +337,7 @@ export async function launchRelay({
     env,
     relayToken: running?.lock?.token || '',
     relayPort: port,
+    portOverride: cliPort,
     layout,
   });
   if (runtimeConfig.managed || !fs.existsSync(runtimeConfig.configPath)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oar-sh/oar",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "type": "module",
   "description": "OAR — Open Agent Relay: drive your local coding agents from any browser",
   "license": "MIT",
@@ -20,6 +20,8 @@
     "bin/",
     "server/",
     "!server/**/*.test.mjs",
+    "!server/**/*-test-harness.mjs",
+    "!server/**/fixtures/",
     "!server/data/",
     "!server/logs/",
     "!server/config.json",
@@ -28,6 +30,7 @@
     "server/uploads/image_input.md",
     "shared/",
     "!shared/**/*.test.mjs",
+    "!shared/**/fixtures/",
     ".github/extensions/web-relay/",
     "!.github/extensions/web-relay/**/*.test.mjs",
     "README.md",
@@ -37,15 +40,18 @@
   "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": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.261",
-    "@cursor/sdk": "^1.0.27",
-    "@github/copilot-sdk": "^1.0.13",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.283",
+    "@cursor/sdk": "^1.0.32",
+    "@github/copilot-sdk": "^1.0.14",
     "better-sqlite3": "^12.10.0",
     "express": "^4.18.2",
     "qrcode-terminal": "^0.12.0",

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.
 
@@ -773,7 +798,7 @@ Queue metrics include `parkedCount` for turns deferred behind restart/rebind gat
 | GET | `/api/search/messages` | Search message text across all conversations (`q`, `limit`, `offset`) |
 | PATCH | `/api/conversation/:id` | Update a conversation title |
 | POST | `/api/conversation/:id/compact` | Compact a conversation into a new one with carry-over summary seed |
-| DELETE | `/api/conversation/:id` | Delete a conversation |
+| DELETE | `/api/conversation/:id` | Delete a conversation: stops its session worker, deletes its CLI session, removes its rows. A Copilot session the relay only imported and never ran is hidden and tombstoned instead: nothing is stopped and its CLI session is kept. `409 conversation-active` (`reason: turn-running` / `background-tasks`) while it is still working; `409 worker-stop-failed` when its worker survives the stop (nothing deleted) |
 | GET | `/api/sdk-session-delete/pending` | (CLI relay) Fetch next pending SDK session delete request |
 | POST | `/api/sdk-session-delete/result` | (CLI relay) Report SDK session delete result |
 | POST | `/api/session-sync` | (CLI relay) Sync conversation↔SDK binding and optionally confirm orchestrator rebind completion |
@@ -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,