@oar-sh/oar 0.9.23 → 0.9.24

package/CHANGELOG.md

@@ -3,6 +3,171 @@
 All notable changes to OAR are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow semver.
 
+## [0.9.24] — 2026-11-08
+
+Highlights: a much smaller install. The Claude and Cursor agent SDKs leave
+the package, and the relay downloads the one a provider needs from npm when
+it is set up or first used: the package takes about 50 MB on Linux x64
+instead of about 650 MB, plus the SDKs of the providers you use. Neither the
+start nor a first chat waits for the download; the chat shows "Installing
+the … SDK" and runs when it ends. Copilot needs nothing downloaded. The
+relay also checks each provider for new models on its own, every 24 hours
+by default, announces new ones with a toast and a "New" tag, and lets you
+choose per provider whether new models start on; OpenAI models can now be
+picked as well. gpt-image replies above about 3 MB are no longer lost.
+
+### Added
+
+- **Check for new models.** The relay now asks each switched-on provider
+  for its model list on its own: a minute after it starts for the
+  providers that are due, then every 24 hours. Claude and Grok are asked
+  only when their CLI is installed or they are signed in. Settings →
+  General has a new Models section with the switch, how often (every 6 h,
+  12 h, 24 h, 3 days or 7 days) and one "Check <provider>" box per
+  provider, each with its last check or "Not set up". A provider whose
+  list was refreshed some other way (Refresh in Select Models, a settings
+  save, a sign-in, and for Copilot the look it takes when the relay
+  starts) waits a full interval again, and a failed check is tried again
+  after an hour at the earliest.
+- **New models are announced.** A refresh that finds models it has not
+  seen before shows a toast, such as "2 new Cursor models (on)", whose Show
+  opens Select Models on that provider. The chat menu's Select Models has a
+  dot, and each new model a "New" tag, until Select Models is opened.
+- **Agent SDK rows in Settings.** The Claude, Claude API, DeepSeek and
+  Cursor tabs show their SDK's state, the pinned and the installed version,
+  the install log and the next automatic retry, with Install, Cancel, Retry
+  and Reinstall. On a Windows relay, Settings → General → This relay has a
+  "Windows helper" row for koffi, with Retry.
+- **`oar sdk`, and the agent SDKs in `oar doctor`.** `oar doctor` shows the
+  SDK folder and, per SDK, the pinned version, the installed one and its
+  state; `oar sdk` prints the same lines. `oar sdk install
+  claude|cursor|koffi [--reinstall]` installs one without the relay, for a
+  headless host whose web UI is the problem.
+
+### Changed
+
+- **The agent SDKs are downloaded on demand.** The Claude Agent SDK (Claude,
+  Claude API and DeepSeek chats) and the Cursor SDK are no longer in the
+  package, which is smaller by roughly their size: about 50 MB installed
+  on Linux x64 instead of about 650 MB. The relay downloads the one a
+  provider needs from npm, at the version this release pins: when you
+  set the provider up (a Claude login, a provider switched on, a key saved),
+  at the provider's first chat, and at start for the providers in use. The
+  start never waits for it, and neither does a first chat: it opens at
+  once, shows "Installing the … SDK" and delivers the message when the
+  install ends; a failed install shows its cause in the chat and keeps the
+  message queued until a Retry in Settings, or the automatic retry,
+  installs the SDK. The SDKs live in `sdks/` in the state root
+  (`OAR_SDK_DIR` moves it; on Windows it must be a local folder of at most
+  120 characters): about 360–370 MB for Claude on Windows and Linux x64
+  and 345–350 MB on macOS arm64, most of it the Claude Code binary, and
+  40–50 MB for Cursor. The pinned version and the one before are kept, and
+  any folder a running session uses. An install's progress (npm's output,
+  the bytes it downloads) is checked every 15 seconds: 5 minutes without
+  any counts as a network failure. An install takes at most 2 hours,
+  enough for the Claude SDK on links down to about 0.4 Mbit/s. A download
+  that fails for want of a connection, or stalls like that, is tried again
+  after 1, 5 and 15 minutes. OAR needs the npm registry once per SDK
+  version and does not work offline; the host's npm config (registry,
+  proxy, cafile, cache, offline settings) applies. Where a vendor has no
+  build, the row says "Not available on this platform": the Cursor SDK on
+  Windows arm64, both SDKs on Android under Termux (run OAR in a proot
+  Debian there), 32-bit ARM and FreeBSD. See docs/install.md, Agent SDKs.
+- **How an SDK is installed.** `npm ci` from a lockfile that ships with OAR,
+  at exact versions, into a folder of its own that counts as installed only
+  once its marker, which lists the files and their sizes, checks out.
+  Installs run with scripts disabled, koffi's included. A git checkout runs
+  the same agent SDK versions as devDependencies, as long as they are
+  installed there (not after `npm install --omit=dev`, for example);
+  otherwise, or with `OAR_AGENT_SDK_SOURCE=store`, it downloads them like
+  an install. Below the pinned packages the versions can differ: the
+  Claude SDK's own lockfile has newer releases of eight of them than the
+  package's lockfile (@babel/runtime 7.29.13, encodeurl 2.0.1,
+  eventsource-parser 3.1.1, express-rate-limit 8.7.3, jose 6.2.15,
+  on-finished 2.4.2, range-parser 1.3.0, standardwebhooks 1.1.1).
+- **The Copilot SDK leaves the package.** No server code used
+  `@github/copilot-sdk`: Copilot workers run on the SDK that comes with the
+  Copilot CLI, and the CLI resolves the extension's
+  `@github/copilot-sdk/extension` import itself. Copilot needs nothing
+  downloaded.
+- **A plain `npm install -g @oar-sh/oar`.** koffi went with the Copilot
+  SDK, so no shipped dependency has an install script any more: npm 12
+  needs no `--allow-scripts`, and the **Update** button and `oar update`
+  pass none. On Windows the relay downloads koffi itself (about 3 MB) for
+  its lock check, with scripts disabled like the SDKs: its binary comes
+  prebuilt in `@koromix/koffi-win32-<arch>`.
+- **The Windows lock check without koffi.** Until koffi is there, a relay
+  lock whose owner's start time is unknown counts as stale when it was
+  written before the last boot, or when its process id now runs a program
+  other than Node. A lock left by a crash or a reboot, whose process id
+  Windows has handed on, no longer keeps the relay from starting, which
+  matters most for a relay started at boot after an update reboot. The
+  take-over of an earlier database uses the same rule. The start after
+  koffi arrived has the full check again.
+- `engine.io` 6.6.11 (was 6.6.9) under socket.io, from a lockfile refresh:
+  a new version of a package already in the tree.
+- In the Claude SDK's install: `@modelcontextprotocol/sdk` 1.32.2 (was
+  1.30.0), pinned there as the SDK's peer, with `hono` 4.13.17 (was
+  4.13.9), `@hono/node-server` 2.1.6 (was 2.1.0), `fast-uri` 3.1.9 (was
+  3.1.8) and `ip-address` 10.7.6 (was 10.4.0). All are new versions of
+  packages that were already in the tree; no package was added.
+- **Whether a new model starts on is yours to choose.** Every Select
+  Models tab, Copilot and OpenAI included, starts with "Turn new models on
+  automatically", on by default. Models that are off today stay off; only
+  models found from now on follow the switch. A new effort level of a
+  Copilot model follows the model's other levels.
+- **A model you turn off stays off.** Each provider now remembers every
+  model it has offered and whether it is on. Unticking everything leaves
+  the default model on instead of turning every model back on; a model that
+  leaves the list and comes back keeps its state; removing a Cursor,
+  DeepSeek, Claude API or OpenAI key and adding one again finds the models
+  as they were. When every model you turned on has left the list, the
+  default model stands in and the provider's tab says so. The pickers show
+  the same models after the upgrade as before.
+- **OpenAI models can be picked.** The Select Models OpenAI tab lists the
+  key's models with checkboxes, like the other providers; after the
+  upgrade all of them stay on.
+
+### Fixed
+
+- **gpt-image replies above about 3 MB were lost, and the turn was billed up
+  to five times.** The relay checked the base64 of a generated image with a
+  regular expression over the whole string. V8 stops optimising regexps once
+  a process has generated more than 1 MB of regexp code and holds more than
+  16 MB of executable memory, which a relay reaches after some uptime; the
+  unoptimised check then overflows V8's regexp stack at 4,194,304 characters
+  with "Maximum call stack size exceeded", the reply was answered as a
+  provider outage, and the queue retried the paid generation four more times
+  before "Relay timeout after 5 attempts". The base64 and data-URL checks on
+  the relay's image paths (OpenAI replies, generated images, edit
+  attachments) are character loops now; a reply the relay cannot process
+  after the provider answered 2xx fails the message at once, with the reason
+  and a note that the generation was billed, instead of being requeued, and
+  the error is logged with its stack.
+
+### Upgrade notes
+
+- **The first Claude or Cursor chat after the update may wait.** The new
+  relay downloads the agent SDKs of the providers in use at its first start,
+  in the background, once: about 360–370 MB for Claude (345–350 MB on
+  macOS arm64) and 40–50 MB for Cursor. A chat that comes first shows
+  "Installing the … SDK" and runs once the download is done. A host that
+  cannot reach the npm registry, or a mirror set in its npm config, cannot
+  run Claude, Claude API, DeepSeek or Cursor chats on this version.
+- **Sessions still on 0.9.23's worker wait one worker start.** A session
+  whose worker still runs the old code is given a new worker before its
+  next message, so the first message after the update waits for that start
+  instead of failing.
+- **No migration.** As before, the relay copies its database to the
+  backups folder before the first start of a new version.
+- **Going back to 0.9.23** needs no database step. Install it with
+  `npm install -g --allow-scripts=koffi @oar-sh/oar@0.9.23` (in a git
+  checkout: `git checkout v0.9.23`, then `npm ci`). 0.9.23 does not use
+  `sdks/` in the state root; delete it once no 0.9.24 relay runs. Model
+  choices made on 0.9.24 do not go back with it: for Claude, Claude API,
+  Cursor, Grok and DeepSeek, 0.9.23 shows the models that were on at the
+  update, and OpenAI offers every model again; Copilot keeps its choices.
+
 ## [0.9.23] — 2026-11-07
 
 Highlights: a dependency round. The Copilot, Claude and Cursor SDKs, zod,

package/README.md

@@ -45,29 +45,29 @@ flowchart LR
 <table>
 <tr>
 <td width="42%" rowspan="4" valign="top">
-<a href="https://oar.sh/assets/shots/cfmail-mobile.png?v=0.9.23"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-mobile.light.png?v=0.9.23"><img src="https://oar.sh/assets/shots/cfmail-mobile.png?v=0.9.23" alt="OAR on a phone: a finished agent turn in a conversation, with the composer below"></picture></a>
+<a href="https://oar.sh/assets/shots/cfmail-mobile.png?v=0.9.24"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-mobile.light.png?v=0.9.24"><img src="https://oar.sh/assets/shots/cfmail-mobile.png?v=0.9.24" alt="OAR on a phone: a finished agent turn in a conversation, with the composer below"></picture></a>
 <br><sub>On a phone: the same conversations, installable as an app.</sub>
 </td>
 <td width="58%" valign="top">
-<a href="https://oar.sh/assets/shots/cfmail-agents.png?v=0.9.23"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-agents.light.png?v=0.9.23"><img src="https://oar.sh/assets/shots/cfmail-agents.png?v=0.9.23" alt="Background subagents running in parallel in the task panel, each with live token counts, elapsed time, and its own Stop button"></picture></a>
+<a href="https://oar.sh/assets/shots/cfmail-agents.png?v=0.9.24"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-agents.light.png?v=0.9.24"><img src="https://oar.sh/assets/shots/cfmail-agents.png?v=0.9.24" alt="Background subagents running in parallel in the task panel, each with live token counts, elapsed time, and its own Stop button"></picture></a>
 <br><sub>Agents working in parallel, each with live token counts and its own Stop.</sub>
 </td>
 </tr>
 <tr>
 <td valign="top">
-<a href="https://oar.sh/assets/shots/cfmail-question.png?v=0.9.23"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-question.light.png?v=0.9.23"><img src="https://oar.sh/assets/shots/cfmail-question.png?v=0.9.23" alt="A question card in the middle of a turn: the agent offers several choices and a free-text reply"></picture></a>
+<a href="https://oar.sh/assets/shots/cfmail-question.png?v=0.9.24"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-question.light.png?v=0.9.24"><img src="https://oar.sh/assets/shots/cfmail-question.png?v=0.9.24" alt="A question card in the middle of a turn: the agent offers several choices and a free-text reply"></picture></a>
 <br><sub>When the agent needs a decision, it asks, and waits for your answer.</sub>
 </td>
 </tr>
 <tr>
 <td valign="top">
-<a href="https://oar.sh/assets/shots/pingcf-thoughts.png?v=0.9.23"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/pingcf-thoughts.light.png?v=0.9.23"><img src="https://oar.sh/assets/shots/pingcf-thoughts.png?v=0.9.23" alt="An expanded Thoughts block showing the agent's reasoning above its reply"></picture></a>
+<a href="https://oar.sh/assets/shots/pingcf-thoughts.png?v=0.9.24"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/pingcf-thoughts.light.png?v=0.9.24"><img src="https://oar.sh/assets/shots/pingcf-thoughts.png?v=0.9.24" alt="An expanded Thoughts block showing the agent's reasoning above its reply"></picture></a>
 <br><sub>Read the reasoning, not just the answer.</sub>
 </td>
 </tr>
 <tr>
 <td valign="top">
-<a href="https://oar.sh/assets/shots/pagewright-watching.png?v=0.9.23"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/pagewright-watching.light.png?v=0.9.23"><img src="https://oar.sh/assets/shots/pagewright-watching.png?v=0.9.23" alt="A session watching two other sessions: a finished reply arrives as a compact relay-event row, the watching 2 sessions list is open with Unsubscribe, and a request to also watch a session on a paired relay waits on an Allow / Deny card"></picture></a>
+<a href="https://oar.sh/assets/shots/pagewright-watching.png?v=0.9.24"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/pagewright-watching.light.png?v=0.9.24"><img src="https://oar.sh/assets/shots/pagewright-watching.png?v=0.9.24" alt="A session watching two other sessions: a finished reply arrives as a compact relay-event row, the watching 2 sessions list is open with Unsubscribe, and a request to also watch a session on a paired relay waits on an Allow / Deny card"></picture></a>
 <br><sub>Agents that watch agents: woken by events, approving nothing.</sub>
 </td>
 </tr>
@@ -118,11 +118,11 @@ API keys are entered in **⚙️ Settings** and stay on the relay host. The Clau
 <table>
 <tr>
 <td width="62%" valign="top">
-<a href="https://oar.sh/assets/shots/cfmail-steering.png?v=0.9.23"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-steering.light.png?v=0.9.23"><img src="https://oar.sh/assets/shots/cfmail-steering.png?v=0.9.23" alt="A running Claude turn with a message steered into it mid-turn, the reply streaming with its tool calls, and the Steer button in the composer"></picture></a>
+<a href="https://oar.sh/assets/shots/cfmail-steering.png?v=0.9.24"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-steering.light.png?v=0.9.24"><img src="https://oar.sh/assets/shots/cfmail-steering.png?v=0.9.24" alt="A running Claude turn with a message steered into it mid-turn, the reply streaming with its tool calls, and the Steer button in the composer"></picture></a>
 <br><sub>Send a message while the agent works, and it steers the running turn.</sub>
 </td>
 <td width="38%" valign="top">
-<a href="https://oar.sh/assets/shots/usage-copilot-compact.png?v=0.9.23"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/usage-copilot-compact.light.png?v=0.9.23"><img src="https://oar.sh/assets/shots/usage-copilot-compact.png?v=0.9.23" alt="The GitHub Copilot card in Check Usage: premium requests and plan quota with reset dates, and the cost of the last turn"></picture></a>
+<a href="https://oar.sh/assets/shots/usage-copilot-compact.png?v=0.9.24"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/usage-copilot-compact.light.png?v=0.9.24"><img src="https://oar.sh/assets/shots/usage-copilot-compact.png?v=0.9.24" alt="The GitHub Copilot card in Check Usage: premium requests and plan quota with reset dates, and the cost of the last turn"></picture></a>
 <br><sub>What each plan has left, in one place.</sub>
 </td>
 </tr>
@@ -139,7 +139,7 @@ API keys are entered in **⚙️ Settings** and stay on the relay host. The Clau
 - **Share** a conversation as a read-only link, hide single messages and the host's paths from it, and see when it was opened ([Sharing](docs/web-ui.md#sharing)).
 - **On your phone**: install OAR as an app and get push notifications; back walks through the conversations you opened, a pinch zooms the whole app, and held sideways it keeps a phone's layout ([Notifications and the app](docs/web-ui.md#notifications-and-the-app), [back and forward](docs/web-ui.md#back-and-forward), [zoom](docs/web-ui.md#zoom), [a phone held sideways](docs/web-ui.md#a-phone-held-sideways)).
 
-The full tour is in [Using the web UI](docs/web-ui.md); every setting and config key is in [Settings and configuration](docs/configuration.md). What changed in each release is in the [changelog](CHANGELOG.md), with [0.9.23](CHANGELOG.md#0923--2026-11-07) as the latest.
+The full tour is in [Using the web UI](docs/web-ui.md); every setting and config key is in [Settings and configuration](docs/configuration.md). What changed in each release is in the [changelog](CHANGELOG.md), with [0.9.24](CHANGELOG.md#0924--2026-11-08) as the latest.
 
 ## Remote access
 
@@ -190,7 +190,7 @@ flowchart LR
 
 You stay in charge: per paired relay you decide whether agents may only read, also prompt, or do everything, and in the `ask` and `plan` modes every write asks you first. A subscription only notifies; it approves nothing.
 
-<p><a href="https://oar.sh/assets/shots/pagewright-cross-relay.png?v=0.9.23"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/pagewright-cross-relay.light.png?v=0.9.23"><img src="https://oar.sh/assets/shots/pagewright-cross-relay.png?v=0.9.23" alt="A session watching two sessions on a paired relay: a reply arrives as a relay-event row, and after a short outage the events the other relay kept arrive as one replayed row" width="720"></picture></a></p>
+<p><a href="https://oar.sh/assets/shots/pagewright-cross-relay.png?v=0.9.24"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/pagewright-cross-relay.light.png?v=0.9.24"><img src="https://oar.sh/assets/shots/pagewright-cross-relay.png?v=0.9.24" alt="A session watching two sessions on a paired relay: a reply arrives as a relay-event row, and after a short outage the events the other relay kept arrive as one replayed row" width="720"></picture></a></p>
 
 How pairing, permissions and limits work is in [Agents working together](docs/agents-together.md).
 

package/bin/oar.js

@@ -18,6 +18,7 @@ import { NATIVE_BUILD_COMMAND, buildBetterSqlite3, needsSourceBuild } from '../s
 import { DB_FILE_NAME, DB_FILE_NAMES, LEGACY_DB_FILE_NAME, resolveDatabaseFile } from '../server/services/database-file.mjs';
 import { BACKUP_PROGRESS_FILE, BACKUP_WAIT_FILE, backupDatabase, configWarnings, describeBackups, sanitizeReason } from '../server/services/db-backup-service.mjs';
 import { defaultIsProcessAlive, lockHolderMayRun, processIdentity } from '../server/services/relay-singleton-guard.mjs';
+import { createAgentSdkStore } from '../server/services/agent-sdk-store.mjs';
 import {
   getLauncherLogDir,
   getLegacyManagedConfigDir,
@@ -26,8 +27,9 @@ import {
   resolveStateLayout,
 } from '../server/services/oar-state-layout.mjs';
 import {
-  buildDefaultConfig, buildServicePath, buildSystemdUnit, classifySystemdUnit, describeRelayAddress, DOCTOR_PROBES, generateAuthToken,
-  listSystemdDropIns, NPM_ALLOW_SCRIPTS_ARG, parseCliArgs, parseSystemdVersion, primaryLanAddress, renderDoctorReport,
+  buildDefaultConfig, buildServicePath, buildSystemdUnit, classifySystemdUnit, describeAgentSdks, describeRelayAddress, DOCTOR_PROBES,
+  generateAuthToken, listSystemdDropIns, parseCliArgs, parseSystemdVersion, primaryLanAddress, renderAgentSdkLines,
+  renderDoctorReport,
   resolveNpmInvocation, systemdUnitMarkerRoot, systemdUnitRunsCheckout, usageText,
 } from '../server/services/oar-cli-helpers.mjs';
 import { describeConfiguredTunnel, describeTunnelState } from '../server/services/cloudflared-tunnel-service.mjs';
@@ -2256,7 +2258,6 @@ export async function runDoctor(options = {}) {
       return { id: probe.id, ok: false };
     }
   });
-  probes.push({ id: 'cursor', ok: true, version: 'bundled (@cursor/sdk)' });
 
   const port = endpointOf(paths.config).port;
   const holder = paths.config ? createWindowsPortCheck(ctx)(port) : null;
@@ -2277,10 +2278,58 @@ export async function runDoctor(options = {}) {
     warnings: holder ? [windowsPortWarning(port, holder)] : [],
     // The relay resolves a relative cloudflaredTunnel.binary against server/.
     tunnel: describeConfiguredTunnel(paths.config?.cloudflaredTunnel, { env: ctx.env, configBaseDir: path.join(ctx.packageRoot, 'server') }),
+    agentSdks: describeAgentSdks({ env: ctx.env, platform: ctx.platform }),
   }));
   return { code: 0, reason: 'doctor' };
 }
 
+/**
+ * `oar sdk [status]`: the agent SDKs as `oar doctor` shows them.
+ * `oar sdk install <claude|cursor|koffi> [--reinstall]`: installs one through
+ * the relay's store, without the relay, for a headless host whose web UI is
+ * the problem; npm's output streams to the terminal. Exit 1 when it did not
+ * end ready.
+ */
+export async function runSdk(options = {}) {
+  const ctx = cliContext(options);
+  const argv = ctx.argv || [];
+  if (argv[0] !== 'install') {
+    ctx.logger.log(renderAgentSdkLines(describeAgentSdks({ env: ctx.env, platform: ctx.platform })).join('\n'));
+    return { code: 0, reason: 'sdk-status' };
+  }
+  const id = argv[1];
+  if (!id) {
+    ctx.logger.error('[oar] oar sdk install needs the SDK: claude, cursor or koffi.');
+    return { code: 2, reason: 'usage' };
+  }
+  const store = (ctx.createAgentSdkStore || createAgentSdkStore)({ env: ctx.env, platform: ctx.platform, logger: { log: () => {} } });
+  let shown = '';
+  const unsubscribe = store.subscribe((snapshot) => {
+    const text = snapshot.sdks[id]?.log || '';
+    // The log is the retained tail: print what is new since the last look.
+    const fresh = text.startsWith(shown) ? text.slice(shown.length) : text;
+    if (fresh) ctx.stdout.write(fresh);
+    shown = text;
+  });
+  try {
+    const started = store.install(id, { force: argv.includes('--reinstall'), reason: 'oar sdk install' });
+    if (!started.ok) {
+      ctx.logger.error(`[oar] ${started.error}`);
+      return { code: 1, reason: 'sdk-install-failed' };
+    }
+    const status = started.ready ? started.status : await store.ensure(id, { reason: 'oar sdk install', retryFailed: true });
+    if (status?.state !== 'ready') {
+      ctx.logger.error(`[oar] ${status?.label || id}: ${status?.error || 'not installed'}`);
+      return { code: 1, reason: 'sdk-install-failed' };
+    }
+    ctx.logger.log(`[oar] ${status.label} ${status.installed} is ready in ${status.dir}.`);
+    return { code: 0, reason: 'sdk-installed' };
+  } finally {
+    unsubscribe();
+    store.dispose();
+  }
+}
+
 /**
  * `oar backup [--reason <text>]`: a copy of the relay's database, online
  * (safe while the relay runs), into the backup folder with the start's
@@ -2392,7 +2441,7 @@ async function runUpdate({ argv = [], env = process.env, logger = console, fetch
   logger.log(`[oar] Updating @oar-sh/oar ${runningVersion} -> ${target} ...`);
   const npm = resolveNpmInvocation({ packageRoot, env });
   const exitCode = await new Promise((resolve) => {
-    const child = spawnImpl(npm.command, ['install', '-g', ...npm.prefixArgs, NPM_ALLOW_SCRIPTS_ARG, `@oar-sh/oar@${target}`], {
+    const child = spawnImpl(npm.command, ['install', '-g', ...npm.prefixArgs, `@oar-sh/oar@${target}`], {
       stdio: 'inherit',
       env: npm.env,
       ...(process.platform === 'win32' ? { shell: true, windowsHide: true } : {}),
@@ -2523,6 +2572,7 @@ const COMMANDS = {
   backup: runBackup,
   update: runUpdate,
   'build-native': runBuildNative,
+  sdk: runSdk,
   help: async ({ logger = console } = {}) => {
     logger.log(usageText());
     return { code: 0, reason: 'help' };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oar-sh/oar",
-  "version": "0.9.23",
+  "version": "0.9.24",
   "type": "module",
   "description": "OAR — Open Agent Relay: drive your local coding agents from any browser",
   "license": "MIT",
@@ -58,20 +58,22 @@
     "test:e2e:raw": "node ./node_modules/@playwright/test/cli.js test --config tests/playwright.config.mjs"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "0.3.319",
-    "@cursor/sdk": "1.3.1",
-    "@github/copilot-sdk": "1.0.29",
     "better-sqlite3": "13.0.3",
     "express": "5.3.0",
     "qrcode-terminal": "0.12.0",
     "socket.io": "4.8.4",
     "web-push": "3.6.7",
-    "ws": "8.22.1",
-    "zod": "4.6.7"
+    "ws": "8.22.1"
   },
   "devDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "0.3.319",
+    "@anthropic-ai/sdk": "0.116.0",
+    "@cursor/sdk": "1.3.1",
+    "@modelcontextprotocol/sdk": "1.32.2",
     "@playwright/test": "^1.60.0",
-    "jsdom": "^30.0.1"
+    "jsdom": "^30.0.1",
+    "koffi": "3.3.4",
+    "zod": "4.6.7"
   },
   "overrides": {
     "undici": "6.28.0"

package/server/agent-sdk-loader.mjs

@@ -0,0 +1,116 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import {
+  agentSdkFromCheckout,
+  getAgentSdkDescriptor,
+  isValidAgentSdkInstall,
+  writeAgentSdkLease,
+} from './services/agent-sdk-paths.mjs';
+import { currentBootId, processIdentity } from './services/relay-singleton-guard.mjs';
+
+/**
+ * Loads an agent SDK the relay installs on demand (agent-sdk-store.mjs),
+ * wherever this process has it:
+ *
+ *   1. OAR_AGENT_SDK_DIR_<SDK>: the folder the relay launched this worker
+ *      with, kept for the worker's whole life;
+ *   2. in the relay itself, the store's ready folder (setAgentSdkStore);
+ *   3. in a git checkout that has it installed, the package's devDependency.
+ *
+ * Otherwise AgentSdkMissingError. A folder is imported through its entry
+ * file by path: the bare imports in it resolve from the folder's own
+ * node_modules, so there is no NODE_PATH and no exports map to read.
+ */
+
+export const AGENT_SDK_MISSING_CODE = 'AGENT_SDK_MISSING';
+
+export class AgentSdkMissingError extends Error {
+  constructor(sdk, detail = '') {
+    const label = getAgentSdkDescriptor(sdk)?.label || sdk;
+    super(`${label} is not installed${detail ? ` (${detail})` : ''}.`);
+    this.name = 'AgentSdkMissingError';
+    this.code = AGENT_SDK_MISSING_CODE;
+    this.sdk = sdk;
+  }
+}
+
+export function agentSdkDirEnvName(sdk) {
+  return `OAR_AGENT_SDK_DIR_${String(sdk || '').toUpperCase()}`;
+}
+
+let relayStore = null;
+const cache = new Map();
+const leased = new Set();
+
+/**
+ * The relay registers its store at start. From then on the environment's
+ * folder is not looked at in this process: a relay started from inside a
+ * worker's session would otherwise take that worker's SDK.
+ */
+export function setAgentSdkStore(store) {
+  relayStore = store || null;
+  cache.clear();
+}
+
+// What a checkout's devDependency gives, in the shape of the entry files.
+const CHECKOUT_IMPORTS = {
+  claude: {
+    main: async () => ({ ...(await import('@anthropic-ai/claude-agent-sdk')), z: await import('zod') }),
+  },
+  cursor: {
+    main: () => import('@cursor/sdk'),
+    sqlite: () => import('@cursor/sdk/sqlite'),
+  },
+};
+
+function importFromDir(descriptor, dir, entry, { lease, env }) {
+  if (!isValidAgentSdkInstall(dir, { id: descriptor.id })) {
+    throw new AgentSdkMissingError(descriptor.id, `${dir} is not a finished install`);
+  }
+  if (lease && !leased.has(dir)) {
+    leased.add(dir);
+    writeAgentSdkLease(dir, {
+      holder: (() => { try { return processIdentity(process.pid); } catch { return null; } })(),
+      bootId: currentBootId(),
+    });
+  }
+  return import(pathToFileURL(path.join(dir, descriptor.entries[entry])).href);
+}
+
+/** Where loadAgentSdk would take the SDK from: { source, dir }, or null. */
+export function resolveAgentSdkSource(sdk, { env = process.env, store = relayStore, fromCheckout } = {}) {
+  const descriptor = getAgentSdkDescriptor(sdk);
+  if (!descriptor) return null;
+  if (!store) {
+    const dir = String(env?.[agentSdkDirEnvName(descriptor.id)] || '').trim();
+    if (dir) return { source: 'env', dir: path.resolve(dir) };
+  } else {
+    const dir = store.readyDir(descriptor.id);
+    if (dir) return { source: 'store', dir };
+  }
+  if (fromCheckout ?? agentSdkFromCheckout(descriptor.id, { env })) return { source: 'checkout', dir: null };
+  return null;
+}
+
+/**
+ * The SDK's module namespace (`entry`: 'main', or 'sqlite' for Cursor's
+ * local store). Claude's carries `z`, the zod its tools are written with.
+ */
+export async function loadAgentSdk(sdk, { entry = 'main', env = process.env, store = relayStore, fromCheckout } = {}) {
+  const descriptor = getAgentSdkDescriptor(sdk);
+  if (!descriptor || !descriptor.entries[entry]) throw new Error(`Unknown agent SDK entry: ${sdk}/${entry}`);
+  const found = resolveAgentSdkSource(descriptor.id, { env, store, fromCheckout });
+  if (!found) throw new AgentSdkMissingError(descriptor.id);
+  const key = `${descriptor.id}:${entry}:${found.source}:${found.dir || ''}`;
+  if (!cache.has(key)) {
+    const loading = found.source === 'checkout'
+      ? CHECKOUT_IMPORTS[descriptor.id][entry]()
+      // The relay's own import (model discovery) holds the folder for the
+      // relay's life, a worker's for its own: both lease it.
+      : importFromDir(descriptor, found.dir, entry, { lease: true, env });
+    cache.set(key, loading);
+    loading.catch(() => { if (cache.get(key) === loading) cache.delete(key); });
+  }
+  return cache.get(key);
+}

package/server/agent-sdks/claude/entry.mjs

@@ -0,0 +1,4 @@
+// Loaded by path from an installed copy of this folder (agent-sdk-loader.mjs):
+// the bare imports resolve from the folder's own node_modules.
+export * from '@anthropic-ai/claude-agent-sdk';
+export * as z from 'zod';