@oar-sh/oar 0.9.0

package/server/public/manifest.webmanifest

@@ -0,0 +1,32 @@
+{
+  "name": "OAR",
+  "short_name": "OAR",
+  "description": "OAR — Open Agent Relay: drive your local coding agents from any browser.",
+  "id": "./__copilot_remote_pwa__",
+  "start_url": "./",
+  "scope": "./",
+  "display_override": ["standalone"],
+  "display": "standalone",
+  "background_color": "#161b22",
+  "theme_color": "#161b22",
+  "icons": [
+    {
+      "src": "app-icon.svg?v=25",
+      "sizes": "any",
+      "type": "image/svg+xml",
+      "purpose": "any"
+    },
+    {
+      "src": "app-icon-192.png",
+      "sizes": "192x192",
+      "type": "image/png",
+      "purpose": "any"
+    },
+    {
+      "src": "app-icon-512.png",
+      "sizes": "512x512",
+      "type": "image/png",
+      "purpose": "any"
+    }
+  ]
+}

package/server/public/sw.js

@@ -0,0 +1,307 @@
+const SW_URL = new URL(self.location.href);
+const SW_VERSION = String(SW_URL.searchParams.get('v') || '').trim() || '0';
+const CACHE_NAME = `copilot-remote-shell-v${SW_VERSION}`;
+const REGISTRATION_SCOPE_PATH = (() => {
+  const path = new URL(self.registration.scope).pathname || '/';
+  return path.endsWith('/') ? path : `${path}/`;
+})();
+const STATIC_ASSETS = [
+  './',
+  'index.html',
+  'manifest.webmanifest',
+  'app-icon-192.png',
+  'app-icon-512.png',
+  'favicon.ico',
+  'app-icon.svg',
+];
+
+function sameOrigin(url) {
+  return url.origin === self.location.origin;
+}
+
+function isApiRequest(url) {
+  return /\/api(?:\/|$)/.test(url.pathname) || /\/socket\.io(?:\/|$)/.test(url.pathname);
+}
+
+function isPwaMetadataRequest(url) {
+  if (!url.pathname.startsWith(REGISTRATION_SCOPE_PATH)) return false;
+  const relativePath = url.pathname.slice(REGISTRATION_SCOPE_PATH.length);
+  return /^(?:manifest\.webmanifest|app-icon(?:-\d+)?\.png|app-icon\.svg|favicon\.ico)$/.test(relativePath);
+}
+
+function isApplicationModuleRequest(url) {
+  if (!url.pathname.startsWith(`${REGISTRATION_SCOPE_PATH}app/`)) return false;
+  return /\.(?:m?js)$/i.test(url.pathname);
+}
+
+async function cacheShell() {
+  const cache = await caches.open(CACHE_NAME);
+  const assets = STATIC_ASSETS.map((asset) => new URL(asset, self.registration.scope).href);
+  await cache.addAll(assets);
+}
+
+async function networkFirst(request, cacheKey) {
+  const cache = await caches.open(CACHE_NAME);
+  try {
+    const response = await fetch(request);
+    if (response && response.ok) {
+      cache.put(cacheKey, response.clone());
+    }
+    return response;
+  } catch {
+    const cached = await cache.match(cacheKey);
+    if (cached) return cached;
+    throw new Error('Offline');
+  }
+}
+
+async function cacheFirst(request, cacheKey) {
+  const cache = await caches.open(CACHE_NAME);
+  const cached = await cache.match(cacheKey);
+  if (cached) return cached;
+  const response = await fetch(request);
+  if (response && response.ok) {
+    cache.put(cacheKey, response.clone());
+  }
+  return response;
+}
+
+self.addEventListener('install', (event) => {
+  event.waitUntil((async () => {
+    await cacheShell();
+    self.skipWaiting();
+  })());
+});
+
+self.addEventListener('activate', (event) => {
+  event.waitUntil((async () => {
+    const keys = await caches.keys();
+    await Promise.all(keys.map((key) => (key === CACHE_NAME ? Promise.resolve() : caches.delete(key))));
+    await self.clients.claim();
+  })());
+});
+
+self.addEventListener('fetch', (event) => {
+  const { request } = event;
+  if (request.method !== 'GET') return;
+
+  const url = new URL(request.url);
+  if (!sameOrigin(url) || isApiRequest(url)) return;
+
+  if (request.mode === 'navigate') {
+    event.respondWith(networkFirst(request, new URL('./', self.registration.scope).href));
+    return;
+  }
+
+  if (isPwaMetadataRequest(url)) {
+    event.respondWith(networkFirst(request, request.url));
+    return;
+  }
+
+  if (isApplicationModuleRequest(url)) {
+    event.respondWith(networkFirst(request, request.url));
+    return;
+  }
+
+  event.respondWith(cacheFirst(request, request.url));
+});
+
+// ─── Web Push ────────────────────────────────────────────────────────────────
+
+function scopeUrl(relative) {
+  return new URL(relative, self.registration.scope).href;
+}
+
+async function handlePushEvent(event) {
+  let payload = null;
+  try {
+    payload = event.data ? event.data.json() : null;
+  } catch {
+    payload = null;
+  }
+  const data = payload?.data && typeof payload.data === 'object' ? payload.data : {};
+  const choices = Array.isArray(data.choices) ? data.choices : [];
+  const maxActions = Number(Notification.maxActions || 0);
+  const actions = choices.slice(0, maxActions).map((choice, index) => ({
+    action: `choice-${index}`,
+    title: String(choice).slice(0, 40),
+  }));
+  await self.registration.showNotification(payload?.title || 'OAR', {
+    body: payload?.body || '',
+    tag: payload?.tag || undefined,
+    // Carried so a delivery delayed by doze is not misread as current.
+    timestamp: Number(payload?.timestamp) || Date.now(),
+    data,
+    icon: scopeUrl('app-icon-192.png'),
+    badge: scopeUrl('app-icon-192.png'),
+    actions,
+  });
+}
+
+self.addEventListener('push', (event) => {
+  event.waitUntil(handlePushEvent(event));
+});
+
+async function answerQuestionFromNotification(questionId, answer) {
+  // Same-origin POST with credentials so the HttpOnly auth cookie applies.
+  const response = await fetch(scopeUrl(`api/relay-question/${encodeURIComponent(questionId)}/answer`), {
+    method: 'POST',
+    credentials: 'include',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ answer }),
+  });
+  return response.ok;
+}
+
+async function focusOrOpenConversation(conversationId) {
+  const clients = await self.clients.matchAll({ type: 'window', includeUncontrolled: true });
+  const scopePath = new URL(self.registration.scope).pathname;
+  const appClient = clients.find((client) => new URL(client.url).pathname.startsWith(scopePath));
+  if (appClient) {
+    try {
+      await appClient.focus();
+    } catch {}
+    if (conversationId) {
+      appClient.postMessage({ type: 'copilot-open-conversation', conversationId });
+    }
+    return;
+  }
+  const target = conversationId
+    ? scopeUrl(`?push_conv=${encodeURIComponent(conversationId)}`)
+    : scopeUrl('./');
+  await self.clients.openWindow(target);
+}
+
+async function handleNotificationClick(event) {
+  const data = event.notification?.data || {};
+  const action = String(event.action || '');
+  const choiceMatch = action.match(/^choice-(\d+)$/);
+  if (choiceMatch && data.questionId) {
+    const choice = (Array.isArray(data.choices) ? data.choices : [])[Number(choiceMatch[1])];
+    if (choice) {
+      event.notification.close();
+      const ok = await answerQuestionFromNotification(data.questionId, String(choice));
+      // If the answer did not land (expired, already answered, offline), fall
+      // through to opening the conversation so the user can see why.
+      if (ok) return;
+    }
+  }
+  event.notification.close();
+  await focusOrOpenConversation(String(data.conversationId || ''));
+}
+
+self.addEventListener('notificationclick', (event) => {
+  event.waitUntil(handleNotificationClick(event));
+});
+
+// ─── Background Sync outbox ──────────────────────────────────────────────────
+// Mirror of the IndexedDB layout in app/sync-outbox.mjs (this worker is a
+// classic script and cannot import it). The page enqueues failed sends,
+// ask_user answers, and pagehide draft flushes; this handler replays them in
+// order when connectivity returns.
+
+const SYNC_DB_NAME = 'copilot-remote-sync';
+const SYNC_DB_VERSION = 1;
+const SYNC_STORE_NAME = 'outbox';
+const SYNC_TAG = 'copilot-outbox';
+const SYNC_MAX_REPLAY_ATTEMPTS = 10;
+
+function openSyncDb() {
+  return new Promise((resolve, reject) => {
+    const request = indexedDB.open(SYNC_DB_NAME, SYNC_DB_VERSION);
+    request.onupgradeneeded = () => {
+      const db = request.result;
+      if (!db.objectStoreNames.contains(SYNC_STORE_NAME)) {
+        db.createObjectStore(SYNC_STORE_NAME, { autoIncrement: true });
+      }
+    };
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error || new Error('IndexedDB unavailable'));
+  });
+}
+
+function syncRequestAsPromise(request) {
+  return new Promise((resolve, reject) => {
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error || new Error('IndexedDB request failed'));
+  });
+}
+
+async function readSyncEntries(db) {
+  const store = db.transaction(SYNC_STORE_NAME, 'readonly').objectStore(SYNC_STORE_NAME);
+  const [keys, values] = await Promise.all([
+    syncRequestAsPromise(store.getAllKeys()),
+    syncRequestAsPromise(store.getAll()),
+  ]);
+  return keys.map((key, index) => ({ key, value: values[index] }));
+}
+
+function deleteSyncEntry(db, key) {
+  const tx = db.transaction(SYNC_STORE_NAME, 'readwrite');
+  tx.objectStore(SYNC_STORE_NAME).delete(key);
+  return new Promise((resolve) => {
+    tx.oncomplete = resolve;
+    tx.onerror = resolve;
+    tx.onabort = resolve;
+  });
+}
+
+function updateSyncEntry(db, key, value) {
+  const tx = db.transaction(SYNC_STORE_NAME, 'readwrite');
+  tx.objectStore(SYNC_STORE_NAME).put(value, key);
+  return new Promise((resolve) => {
+    tx.oncomplete = resolve;
+    tx.onerror = resolve;
+    tx.onabort = resolve;
+  });
+}
+
+// A 4xx (other than 408/429) is a server decision about this exact request —
+// including the 409 DUPLICATE_MESSAGE_ID a replayed send gets when the first
+// ambiguous attempt actually landed — so the entry is finished either way.
+function isFinalSyncResponse(response) {
+  if (!response) return false;
+  if (response.ok) return true;
+  return response.status >= 400 && response.status < 500
+    && response.status !== 408 && response.status !== 429;
+}
+
+async function replaySyncOutbox() {
+  const db = await openSyncDb();
+  try {
+    const entries = await readSyncEntries(db);
+    for (const { key, value } of entries) {
+      let response = null;
+      try {
+        response = await fetch(scopeUrl(String(value.path || '').replace(/^\//, '')), {
+          method: value.method || 'POST',
+          credentials: 'include',
+          headers: { 'Content-Type': 'application/json' },
+          body: value.body,
+        });
+      } catch {
+        response = null;
+      }
+      if (isFinalSyncResponse(response)) {
+        await deleteSyncEntry(db, key);
+        continue;
+      }
+      const attempts = Number(value.attempts || 0) + 1;
+      if (attempts >= SYNC_MAX_REPLAY_ATTEMPTS) {
+        await deleteSyncEntry(db, key);
+        continue;
+      }
+      await updateSyncEntry(db, key, { ...value, attempts });
+      // Rejecting keeps ordering intact and makes the browser retry the sync
+      // with its own backoff.
+      throw new Error('outbox replay incomplete');
+    }
+  } finally {
+    try { db.close(); } catch {}
+  }
+}
+
+self.addEventListener('sync', (event) => {
+  if (event.tag !== SYNC_TAG) return;
+  event.waitUntil(replaySyncOutbox());
+});

package/server/relay-exit-codes.mjs

@@ -0,0 +1,4 @@
+'use strict';
+
+// Intentional relay restart requested via authenticated localhost API.
+export const RELAY_RESTART_EXIT_CODE = 75;

package/server/relay-self-restart.mjs

@@ -0,0 +1,170 @@
+import { spawn } from 'child_process';
+import path from 'path';
+import { RELAY_RESTART_EXIT_CODE } from './relay-exit-codes.mjs';
+
+// Role selection travels on argv, never in the environment. The runtime's env is
+// inherited by tmux worker sessions and by the Copilot CLI it launches, and the
+// CLI extension spawns the next server from that same env — so an env-based role
+// flag silently decided the role of unrelated future servers.
+export const RELAY_RUNTIME_FLAG = '--relay-runtime';
+export const RELAY_SUPERVISED_FLAG = '--supervised';
+
+function hasFlag(argv, flag) {
+  return Array.isArray(argv) && argv.includes(flag);
+}
+
+/** True for the child this supervisor spawned: run the runtime in-process. */
+export function isRelayRuntimeInvocation(argv = process.argv.slice(2)) {
+  return hasFlag(argv, RELAY_RUNTIME_FLAG);
+}
+
+/** True when an outer supervisor owns restarts and wants the runtime here. */
+export function isExternallySupervised(argv = process.argv.slice(2)) {
+  return hasFlag(argv, RELAY_SUPERVISED_FLAG);
+}
+
+export function spawnRelayRuntime({
+  env = process.env,
+  cwd = process.cwd(),
+  scriptPath,
+  args = [],
+  execArgv = process.execArgv,
+  spawnImpl = spawn,
+  stdio = ['ignore', 'pipe', 'pipe'],
+  detached = false,
+  windowsHide = true,
+  logger = console,
+} = {}) {
+  const child = spawnImpl(process.execPath, [...execArgv, scriptPath, RELAY_RUNTIME_FLAG, ...args], {
+    cwd,
+    env,
+    detached,
+    stdio,
+    windowsHide,
+  });
+  logger?.log?.(`[relay] launched runtime pid=${child.pid || 'none'} script=${path.basename(String(scriptPath || ''))}`);
+  return child;
+}
+
+function stopChildProcess(child, { signal = 'SIGTERM', killAfterMs = 1200 } = {}) {
+  if (!child || child.exitCode !== null) return;
+  try {
+    child.kill(signal);
+  } catch {
+    return;
+  }
+  setTimeout(() => {
+    if (!child || child.exitCode !== null) return;
+    try { child.kill('SIGKILL'); } catch {}
+  }, killAfterMs);
+}
+
+function waitForChildExit(child) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      resolve(result);
+    };
+    child.once?.('error', (error) => finish({ code: null, signal: null, error }));
+    child.once?.('exit', (code, signal) => finish({ code, signal, error: null }));
+  });
+}
+
+export async function runDirectRelaySupervisor({
+  scriptPath,
+  args = [],
+  cwd = process.cwd(),
+  env = process.env,
+  execArgv = process.execArgv,
+  spawnImpl = spawn,
+  stdio = ['ignore', 'pipe', 'pipe'],
+  delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  exitImpl = (code) => process.exit(code),
+  logger = console,
+  installSignalHandlers = true,
+  restartDelayMs = 500,
+  maxCrashRestarts = 3,
+} = {}) {
+  let runtimeProc = null;
+  let shuttingDown = false;
+  let shutdownExitCode = 0;
+
+  const requestShutdown = (signal = 'SIGTERM', exitCode = 0) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    shutdownExitCode = exitCode;
+    stopChildProcess(runtimeProc, { signal });
+  };
+
+  const handleSigInt = () => requestShutdown('SIGINT', 0);
+  const handleSigTerm = () => requestShutdown('SIGTERM', 0);
+
+  if (installSignalHandlers) {
+    process.on('SIGINT', handleSigInt);
+    process.on('SIGTERM', handleSigTerm);
+  }
+
+  try {
+    let crashCount = 0;
+    while (true) {
+      runtimeProc = spawnRelayRuntime({
+        env,
+        cwd,
+        scriptPath,
+        args,
+        execArgv,
+        spawnImpl,
+        stdio,
+        detached: false,
+        logger,
+      });
+      if (runtimeProc.stdout?.on) {
+        runtimeProc.stdout.on('data', (chunk) => process.stdout.write(chunk));
+      }
+      if (runtimeProc.stderr?.on) {
+        runtimeProc.stderr.on('data', (chunk) => process.stderr.write(chunk));
+      }
+
+      const result = await waitForChildExit(runtimeProc);
+      runtimeProc = null;
+
+      if (shuttingDown) {
+        return await exitImpl(shutdownExitCode);
+      }
+
+      if (result.error) {
+        logger?.error?.(`[relay] runtime launch failed: ${result.error?.message || result.error}`);
+        return await exitImpl(1);
+      }
+
+      const exitCode = Number.isInteger(Number(result.code)) ? Number(result.code) : null;
+      if (exitCode === RELAY_RESTART_EXIT_CODE) {
+        logger?.log?.(`[relay] runtime requested restart; relaunching ${path.basename(String(scriptPath || ''))}...`);
+        crashCount = 0;
+        await delay(restartDelayMs);
+        continue;
+      }
+
+      if (exitCode === 0) {
+        return await exitImpl(0);
+      }
+
+      const attempt = crashCount + 1;
+      logger?.error?.(`[relay] runtime crashed with exit code ${exitCode ?? 'null'} (crash ${attempt}/${maxCrashRestarts}).`);
+      if (attempt >= maxCrashRestarts) {
+        logger?.error?.('[relay] crash limit reached; supervisor stopping.');
+        return await exitImpl(1);
+      }
+      crashCount = attempt;
+      await delay(restartDelayMs);
+    }
+
+  } finally {
+    if (installSignalHandlers) {
+      process.off('SIGINT', handleSigInt);
+      process.off('SIGTERM', handleSigTerm);
+    }
+  }
+}

package/server/relay-tools.md

@@ -0,0 +1,27 @@
+# Relay Tool Guidance
+
+For any user-facing question or clarification, use the ask_user tool so the web relay can render question cards and buttons. Never ask questions in plain assistant text.
+
+When using ask_user, ALWAYS include a `choices` array with 2-6 answer options so the web relay can render clickable buttons. Example:
+```json
+{
+  "question": "<QUIZ_QUESTION_TEXT>",
+  "choices": ["<CHOICE_A>", "<CHOICE_B>", "<CHOICE_C>", "<CHOICE_D>"]
+}
+```
+At runtime, inject the question and choices from a random item in your quiz pool.
+Only omit choices when the question genuinely requires freeform text input (e.g., "What is your name?").
+
+In autopilot, still call ask_user when user input is truly blocking, because the relay bridge can surface the question even when the direct SDK question hook is bypassed.
+
+For relay restarts in extension-managed mode, require explicit user permission first, then use the authenticated localhost API `POST /api/relay/shutdown`. Do not restart by killing processes or using respawn scripts.
+
+Note: shutdown is queued and only completes when the current turn finishes, so it is pointless to wait for it to interrupt an active turn.
+
+Use `restart: true` in the request body when the user wants a real relay restart rather than a plain shutdown. Example request body: `{ "reason": "manual-restart", "requestedBy": "localhost-api", "restart": true }`.
+
+## Preview servers
+
+Publish a local web server or a static directory on a public preview URL so the user can open it from any device, or list/close existing previews. Use this whenever the user wants to see, try, or share something with a web UI — never ask them to open localhost or forward a port. For a dev server: call this FIRST with {action:"create", port} to get the basePath, then start the server configured to serve under that basePath (Vite --base, Next basePath, Express mount prefix); the proxy forwards X-Forwarded-Prefix but does not rewrite bodies, so root-absolute asset paths will not work. For plain files or a build output: pass {action:"create", dir} instead and the relay serves the directory itself — no dev server needed. Always tell the user the returned URL and that the link is public: anyone who has it can reach the app without logging in. Previews never expire on their own; close them with {action:"close"} when the user is done.
+
+There is no `preview` tool on this provider — use the authenticated localhost API (same auth as `POST /api/relay/shutdown`): `POST /api/previews` with `{ "conversationId": "<conv>", "port": 5173, "label": "web app" }` (or `"dir": "./dist"` instead of the port) publishes, `GET /api/previews` lists, `DELETE /api/previews/:token` closes the link without touching the dev server behind it. A 503 with `details` means the preview lane is disabled or misconfigured — surface those details, they are the operator's fix. See `docs/preview-servers.md`.