@oar-sh/oar 0.9.1 → 0.9.3

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)) {
@@ -363,7 +378,10 @@ export async function launchRelay({
     const serverErrFd = openAppendFileDescriptor(serverErrPath);
     try {
       serverProc = spawnImpl(nodeBin, serverArgs, {
-        cwd: packageRoot,
+        // Global installs run from the OAR state root: on Windows a process
+        // pins its cwd, and `npm i -g` (self-update) must be able to replace
+        // the package directory. Checkouts keep the repo as cwd.
+        cwd: layout.checkout ? packageRoot : layout.root,
         env: baseEnv,
         stdio: ['ignore', serverOutFd, serverErrFd],
         windowsHide: false,
@@ -640,6 +658,118 @@ async function runDoctor({ env = process.env, logger = console } = {}) {
   return { code: 0, reason: 'doctor' };
 }
 
+/**
+ * `oar update [--beta] [--to X.Y.Z]` — the terminal twin of the web UI's
+ * Update button. Fetching the manifest here is an explicit user action, so it
+ * happens regardless of the relay's opt-in auto-check setting.
+ */
+async function runUpdate({ argv = [], env = process.env, logger = console, fetchImpl = globalThis.fetch, spawnImpl = spawn } = {}) {
+  const { channelForVersion, compareSemverIsh, parseSemverIsh } = await import('../shared/update-semver.mjs');
+  const packageRoot = resolvePackageRoot();
+  const runningVersion = readPackageVersion(packageRoot);
+
+  if (isGitCheckout(packageRoot)) {
+    logger.error('[oar] This install runs from a git checkout — update with git pull, then restart the relay.');
+    return { code: 1, reason: 'git-checkout' };
+  }
+
+  const toIdx = argv.indexOf('--to');
+  let target = toIdx !== -1 ? String(argv[toIdx + 1] || '').trim() : '';
+  if (target && !parseSemverIsh(target)) {
+    logger.error(`[oar] --to expects a release version like 0.9.2, got "${target}".`);
+    return { code: 1, reason: 'bad-target' };
+  }
+  if (!target) {
+    // The kill switch means "never phone home from this host", so it blocks
+    // the manifest fetch too — an explicit `--to X.Y.Z` still works because
+    // that path talks only to the npm registry the install already uses.
+    if (String(env.OAR_NO_UPDATE_CHECK || '').trim() === '1') {
+      logger.error('[oar] Update checks are disabled on this host (OAR_NO_UPDATE_CHECK). Use `oar update --to X.Y.Z` to update to a known version.');
+      return { code: 1, reason: 'check-killed' };
+    }
+    const manifestUrl = String(env.OAR_UPDATE_MANIFEST_URL || '').trim() || 'https://oar.sh/latest.json';
+    let manifest = null;
+    try {
+      const response = await fetchImpl(manifestUrl, { signal: AbortSignal.timeout?.(5000) });
+      manifest = response?.ok ? await response.json() : null;
+    } catch {}
+    if (!manifest) {
+      logger.error(`[oar] Could not fetch ${manifestUrl}.`);
+      return { code: 1, reason: 'manifest-unreachable' };
+    }
+    if (manifest.schemaVersion !== 1) {
+      logger.error(`[oar] ${manifestUrl} has schemaVersion ${manifest.schemaVersion}, which this oar does not understand — update manually.`);
+      return { code: 1, reason: 'manifest-unsupported' };
+    }
+    const channel = argv.includes('--beta') ? 'beta' : channelForVersion(runningVersion);
+    target = String(manifest.channels?.[channel]?.version || manifest.channels?.stable?.version || '').trim();
+    if (!parseSemverIsh(target)) {
+      logger.error('[oar] The update manifest carries no usable version.');
+      return { code: 1, reason: 'manifest-empty' };
+    }
+    if (compareSemverIsh(target, runningVersion) <= 0) {
+      logger.log(`[oar] Already up to date (${runningVersion}).`);
+      return { code: 0, reason: 'up-to-date' };
+    }
+  }
+
+  logger.log(`[oar] Updating @oar-sh/oar ${runningVersion} -> ${target} ...`);
+  const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  const exitCode = await new Promise((resolve) => {
+    const child = spawnImpl(npmCommand, ['install', '-g', `@oar-sh/oar@${target}`], {
+      stdio: 'inherit',
+      ...(process.platform === 'win32' ? { shell: true, windowsHide: true } : {}),
+    });
+    child.on('error', (error) => {
+      logger.error(`[oar] npm spawn failed: ${error?.message || error}`);
+      resolve(1);
+    });
+    child.on('close', (code) => resolve(code ?? 1));
+  });
+  if (exitCode !== 0) {
+    logger.error('[oar] npm install failed; the running install is unchanged.');
+    return { code: 1, reason: 'npm-failed' };
+  }
+  logger.log(`[oar] Installed @oar-sh/oar@${target}.`);
+
+  // A running relay picks the new code up on restart; ask for the queue-idle
+  // deferred one so no in-flight turn is cut off.
+  const layout = resolveStateLayout({ packageRoot, env });
+  const configPath = layout.checkout
+    ? path.join(packageRoot, 'server', 'config.json')
+    : path.join(layout.configDir, 'config.json');
+  const config = readJsonFile(configPath);
+  const port = Number(config?.port) || 3333;
+  const lockPath = layout.checkout
+    ? path.join(packageRoot, 'server', 'data', 'relay-server.lock')
+    : path.join(layout.dataDir, 'relay-server.lock');
+  const running = await detectRunningRelay({ lockPath, statusUrl: `http://localhost:${port}/api/status`, fetchImpl });
+  if (!running.running) {
+    logger.log('[oar] No running relay detected — the update loads on the next start.');
+    return { code: 0, reason: 'updated' };
+  }
+  const token = String(running.lock?.token || config?.authToken || '').trim();
+  try {
+    const response = await fetchImpl(`http://localhost:${port}/api/relay/shutdown`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        ...(token ? { Authorization: `Bearer ${token}` } : {}),
+      },
+      body: JSON.stringify({ reason: 'self-update-cli', requestedBy: 'oar-update', restart: true }),
+      signal: AbortSignal.timeout?.(5000),
+    });
+    if (response?.ok) {
+      logger.log('[oar] Relay restart requested — it restarts once the queue is idle.');
+    } else {
+      logger.log('[oar] Could not request a relay restart; restart it manually to load the update.');
+    }
+  } catch {
+    logger.log('[oar] Could not request a relay restart; restart it manually to load the update.');
+  }
+  return { code: 0, reason: 'updated' };
+}
+
 function main() {
   const argv = process.argv.slice(2);
   const command = String(argv[0] || '').trim();
@@ -649,6 +779,7 @@ function main() {
   }
   if (command === 'setup') return runSetup({ argv: argv.slice(1) });
   if (command === 'doctor') return runDoctor({});
+  if (command === 'update') return runUpdate({ argv: argv.slice(1) });
   return launchRelay();
 }
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@oar-sh/oar",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "type": "module",
-  "description": "OAR \u2014 Open Agent Relay: drive your local coding agents from any browser",
+  "description": "OAR — Open Agent Relay: drive your local coding agents from any browser",
   "license": "MIT",
   "homepage": "https://oar.sh",
   "repository": {
@@ -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",
@@ -43,8 +46,9 @@
     "test:e2e:raw": "node ./node_modules/@playwright/test/cli.js test --config tests/playwright.config.mjs"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.226",
-    "@cursor/sdk": "^1.0.27",
+    "@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

@@ -194,8 +194,12 @@ When opened in a regular browser tab, the in-app **Install** button remains avai
 in the chat header (shown as `⬇` on small screens).
 
 You can rename the installed app label from **⚙️ Settings → Install app name**.
-The new label is stored per browser and used for future installs; some platforms may
-require reinstalling the app before the launcher label updates.
+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
+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.
 
 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
@@ -523,25 +527,58 @@ cards with a reply box.
 The active conversation header includes a `✍️` button for renaming the conversation inline.
 Title edits are saved to the database and broadcast to other open clients immediately.
 
-## Session worker rollout flags
-
-Session-worker refactor gates are OFF by default and can be enabled per flag:
-
-- `SESSION_WORKER_ROUTING_ENABLED`
-- `SESSION_WORKER_CONTINUATION_ROUTING_ENABLED`
-- `SESSION_WORKER_FALLBACK_RESTART_ENABLED`
-
-Other flags:
-
-- `IMAGE_CONVERSATION_CONTINUITY_ENABLED` — ON by default; keeps generated-image context across turns
-  so *Edit this image* can continue from the right source image.
-
-Configuration precedence is:
-
-1. `server/config.json` → `features.{FLAG_NAME}` (`true/false`, `1/0`, `yes/no`, `on/off`)
-2. Environment override: `COPILOT_REMOTE_{FLAG_NAME}`
-
-Unknown flag names and invalid values are ignored safely.
+## Updates
+
+OAR never phones home by default. Automatic update checking is **opt-in**:
+enable **Check for updates automatically** in ⚙️ Settings (stored in app
+settings, off unless you turn it on) and the relay asks `oar.sh/latest.json`
+for the newest version about twice a day (12 h ± 1 h jitter, ETag-aware, 5 s
+timeout, failures silent). A manual **Check for updates** button works without
+opting in — that single request is the only traffic it creates. Set
+`OAR_NO_UPDATE_CHECK=1` in the relay's environment to disable even manual
+checks; `OAR_UPDATE_MANIFEST_URL` points the check at a different manifest
+(used by tests and staging).
+
+When a newer version is available, Settings shows a dismissible-per-version
+card (not dismissible if the release is marked critical — it still never
+auto-applies). On npm-global installs, **Update** runs
+`npm i -g @oar-sh/oar@<version>` with the log streamed into the card, then the
+relay restarts once the message queue is idle. After the restart the relay
+verifies the running version actually changed; if not, the npm log is surfaced
+as a failure. Git checkouts are detect-only — the card shows a "pull to
+update" hint instead of the button. `oar update [--beta] [--to X.Y.Z]` does
+the same from a terminal, and rollback is `oar update --to <previous>`.
+
+## Feature flags
+
+Feature flags are declared in one registry (`server/features.mjs`) and managed
+from the web UI's Settings → Features tab, which renders each flag with its
+user-facing description. Current flags and defaults:
+
+- `SESSION_WORKER_ROUTING_ENABLED` — ON by default; per-conversation worker
+  processes with ownership and crash recovery (off = legacy shared polling).
+- `SESSION_WORKER_CONTINUATION_ROUTING_ENABLED` — ON by default; strict
+  ownership validation when routing clarification answers back to the asking
+  worker.
+- `SESSION_WORKER_FALLBACK_RESTART_ENABLED` — OFF by default; reserved rollout
+  gate, no effect yet.
+- `IMAGE_CONVERSATION_CONTINUITY_ENABLED` — ON by default; keeps
+  generated-image context across turns so *Edit this image* can continue from
+  the right source image.
+
+Resolution happens once at relay startup, with this precedence:
+
+1. Registry defaults
+2. Stored settings (`app_settings` rows, written by the Features tab via
+   `GET/POST /api/settings/features`)
+3. Environment override: `COPILOT_REMOTE_{FLAG_NAME}` (`true/false`, `1/0`,
+   `yes/no`, `on/off`)
+
+Changes saved in the Features tab take effect after a relay restart; the tab
+shows a restart notice and offers the queue-idle-deferred restart. A legacy
+`features` key in `config.json` is migrated into `app_settings` once at boot
+and stripped from the file. Unknown flag names and invalid values are ignored
+safely.
 
 Question bridge rule:
 
@@ -736,7 +773,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 |

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

@@ -1,6 +1,7 @@
 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 { createPreviewToolDefinition } from './claude-preview-tool.mjs';
 
 // The name the in-process MCP server is registered under; it prefixes every
@@ -122,11 +123,15 @@ export function permissionModeForRelayMode(relayMode) {
 
 export function systemPromptForRelayMode(relayMode) {
   const mode = String(relayMode || 'agent').trim().toLowerCase();
-  const append = MODE_SYSTEM_PROMPT_APPEND[mode];
+  // The media-embed capability rides every session — unlike the mode nudges it
+  // is renderer knowledge the model cannot discover any other way.
+  const append = [MEDIA_EMBED_INSTRUCTION_TEXT, MODE_SYSTEM_PROMPT_APPEND[mode]]
+    .filter(Boolean)
+    .join('\n\n');
   return {
     type: 'preset',
     preset: 'claude_code',
-    ...(append ? { append } : {}),
+    append,
   };
 }