@oar-sh/oar 0.9.22 → 0.9.24

package/CHANGELOG.md

@@ -3,6 +3,264 @@
 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,
+express, socket.io, ws and better-sqlite3 move to newer releases:
+the tree holds one zod, without CVE-2023-54404, and one express, and
+prebuild-install, which is no longer maintained, is gone. OAR's package has
+no install script any more, which package scanners flag. On Termux, 32-bit
+ARM and FreeBSD, run **`oar build-native`** once after updating to this
+version: it builds the SQLite binding, and later updates build it
+themselves.
+
+### Added
+
+- **`oar build-native`.** better-sqlite3 13 ships its SQLite binding for
+  Linux, macOS and Windows on x64 and arm64. On Android under Termux, 32-bit
+  ARM and FreeBSD, `oar build-native` compiles it in the installed package
+  (Python 3, make and a C++ compiler; on Termux `pkg install python clang
+  make`). The **Update** button and `oar update` run it there themselves
+  before the relay restarts; a build that fails ends the update in an error
+  and leaves the running relay alone. Elsewhere it has nothing to do, so an
+  installer may run it everywhere. A relay started without the binding says
+  which command to run and exits instead of printing a stack trace.
+- **What the agent SDKs contact.** docs/providers.md lists the services the
+  Copilot, Claude and Cursor SDKs and their CLIs talk to, and what the
+  Statsig client inside the Cursor SDK does.
+
+### Changed
+
+- **No install script.** OAR's package has no `preinstall` any more. From
+  0.9.14 to 0.9.22 it copied the data a relay before 0.9.14 kept inside the
+  package out before npm deleted it. npm 12 never ran it without
+  `--allow-scripts`, and package scanners flag every package that has one.
+  A copy those versions made is still taken over at the next start.
+- **`--allow-scripts=koffi`.** better-sqlite3 13 has no install script, so
+  a manual install with npm 12 is now
+  `npm install -g --allow-scripts=koffi @oar-sh/oar`; the installers, the
+  **Update** button and `oar update` pass it themselves.
+- **No terminal console.** The optional `tty-console` dependency is gone,
+  and neo-blessed with it. A relay started in a terminal prints its log
+  lines, each with its time, as under a service; routine worker lines are
+  no longer held back.
+- **Express 5.** The file routes take express 5's syntax and serve the
+  same paths. Static JavaScript is served as `text/javascript`.
+- `better-sqlite3` 13.0.3 (was 12.11.1); `prebuild-install`, which is no
+  longer maintained, and its subtree are gone. New in the tree:
+  `node-addon-api` 8.9.2, the headers of the source build.
+- `express` 5.3.0 (was 4.22.3), the major the MCP SDK already used: one
+  express instead of two, and array-flatten, mime 1 and the rest of express
+  4's subtree are gone.
+- `@anthropic-ai/claude-agent-sdk` 0.3.319 (was 0.3.304; bundled Claude
+  Code 2.1.319). The key chats (DeepSeek, Claude API) also pin the
+  cloud-sessions token and the two new switches that would let a folder's
+  settings widen which certificates Claude Code trusts.
+- `@cursor/sdk` 1.3.1 (was 1.0.38). Its context-compaction summaries are
+  not shown yet.
+- `@github/copilot-sdk` 1.0.29 (was 1.0.23; bundled Copilot CLI 1.0.107)
+  and `zod` 4.6.7 (was 4.4.3): one zod in the tree, without
+  CVE-2023-54404 (GHSA-mrhx-c7xc-m3w5).
+- `socket.io` 4.8.4 (was 4.8.3) and `ws` 8.22.1 (was 8.21.3). `uuid` is
+  gone: Node's `crypto.randomUUID()` makes the same ids.
+- package.json names its author and its bug tracker.
+
+### Upgrade notes
+
+- **From 0.9.13 or older, copy the data out of the package first.** A relay
+  before 0.9.14 could keep its database, uploads and config inside the
+  package folder, which `npm install -g` deletes, and this version no longer
+  copies them out. Copy `data/`, `uploads/` and `config.json` from the
+  installed package's `server` folder into a new folder under
+  `rescued-package-data` in the data folder (for example
+  `~/.oar/data/rescued-package-data/before-update/`); the first start takes
+  them over. From 0.9.14 on there is nothing to do.
+- **Termux, 32-bit ARM, FreeBSD: the update from 0.9.22 needs
+  `oar build-native` once.** The Update button and `oar update` of 0.9.22
+  install 0.9.23 but do not build the binding, so the relay stops at its
+  first start on 0.9.23: its log names the command, and the page cannot
+  reach the relay. In Termux run:
+
+  ```sh
+  pkg install python clang make
+  oar build-native
+  oar start
+  ```
+
+  Later updates build the binding themselves, before the relay restarts.
+- **Linux needs glibc 2.34 or newer,** for example Debian 12, Ubuntu 22.04
+  or RHEL 9. The SQLite binding better-sqlite3 13 ships for Linux on x64
+  and arm64 needs it, and a binding built with `oar build-native` would not
+  be used there. On an older system a relay that updates to 0.9.23 stays
+  down at its first start and says to update the operating system; stay on
+  0.9.22 until the system is updated.
+- **No migration.** Going back to 0.9.22 needs no database step.
+
 ## [0.9.22] — 2026-11-05
 
 Highlights: questions that don't block move into the chat header. A **📓**

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.22"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-mobile.light.png?v=0.9.22"><img src="https://oar.sh/assets/shots/cfmail-mobile.png?v=0.9.22" 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.22"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-agents.light.png?v=0.9.22"><img src="https://oar.sh/assets/shots/cfmail-agents.png?v=0.9.22" 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.22"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-question.light.png?v=0.9.22"><img src="https://oar.sh/assets/shots/cfmail-question.png?v=0.9.22" 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.22"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/pingcf-thoughts.light.png?v=0.9.22"><img src="https://oar.sh/assets/shots/pingcf-thoughts.png?v=0.9.22" 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.22"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/pagewright-watching.light.png?v=0.9.22"><img src="https://oar.sh/assets/shots/pagewright-watching.png?v=0.9.22" 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.22"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-steering.light.png?v=0.9.22"><img src="https://oar.sh/assets/shots/cfmail-steering.png?v=0.9.22" 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.22"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/usage-copilot-compact.light.png?v=0.9.22"><img src="https://oar.sh/assets/shots/usage-copilot-compact.png?v=0.9.22" 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.22](CHANGELOG.md#0922--2026-11-05) 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.22"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/pagewright-cross-relay.light.png?v=0.9.22"><img src="https://oar.sh/assets/shots/pagewright-cross-relay.png?v=0.9.22" 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

@@ -14,9 +14,11 @@ import {
 } from '../server/services/oar-state-migration-service.mjs';
 import { readConfiguredDataDir, resolveDataDir, resolveUploadDir } from '../server/services/data-dir-resolution.mjs';
 import { RESCUE_DIR_NAME, TAKEOVER_PROGRESS_FILE } from '../server/services/earlier-database-service.mjs';
+import { NATIVE_BUILD_COMMAND, buildBetterSqlite3, needsSourceBuild } from '../server/services/native-addon-build-service.mjs';
 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,
@@ -25,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';
@@ -2255,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;
@@ -2276,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
@@ -2391,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 } : {}),
@@ -2407,6 +2457,15 @@ async function runUpdate({ argv = [], env = process.env, logger = console, fetch
     return { code: 1, reason: 'npm-failed' };
   }
   logger.log(`[oar] Installed @oar-sh/oar@${target}.`);
+  // No prebuilt SQLite binding here: build it before the relay restarts on
+  // the new version (native-addon-build-service.mjs).
+  if (needsSourceBuild()) {
+    const build = await buildBetterSqlite3({ packageRoot, env: npm.env, spawnImpl, logger, onOutput: (text) => process.stdout.write(text) });
+    if (!build.ok) {
+      logger.error(`[oar] The relay keeps running the version it has loaded. Run ${NATIVE_BUILD_COMMAND}, then restart it.`);
+      return { code: 1, reason: 'native-build-failed' };
+    }
+  }
 
   // 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.
@@ -2446,6 +2505,23 @@ async function runUpdate({ argv = [], env = process.env, logger = console, fetch
   return { code: 0, reason: 'updated' };
 }
 
+/**
+ * `oar build-native [--force]`: the SQLite binding of better-sqlite3 where no
+ * prebuilt one ships (Termux, 32-bit ARM, FreeBSD); elsewhere nothing to do,
+ * so an installer may run it everywhere. `--force` builds anyway, which only
+ * tests the toolchain where a prebuilt binding ships: better-sqlite3 loads
+ * that one first.
+ */
+async function runBuildNative({ argv = [], env = process.env, logger = console, spawnImpl = spawn } = {}) {
+  const force = argv.includes('--force');
+  if (!force && !needsSourceBuild()) {
+    logger.log(`[oar] better-sqlite3 ships a prebuilt SQLite binding for ${process.platform}-${process.arch}; nothing to build.`);
+    return { code: 0, reason: 'prebuilt' };
+  }
+  const result = await buildBetterSqlite3({ packageRoot: resolvePackageRoot(), force, env, spawnImpl, logger, onOutput: (text) => process.stdout.write(text) });
+  return result.ok ? { code: 0, reason: 'built' } : { code: 1, reason: 'build-failed' };
+}
+
 /** `oar` without a command: the menu in a terminal, the status and the usage elsewhere. */
 async function runMenuCommand(options = {}) {
   const ctx = cliContext(options);
@@ -2495,6 +2571,8 @@ const COMMANDS = {
   doctor: runDoctor,
   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,14 +1,18 @@
 {
   "name": "@oar-sh/oar",
-  "version": "0.9.22",
+  "version": "0.9.24",
   "type": "module",
   "description": "OAR — Open Agent Relay: drive your local coding agents from any browser",
   "license": "MIT",
+  "author": "Simon",
   "homepage": "https://oar.sh",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/oar-sh/oar.git"
   },
+  "bugs": {
+    "url": "https://github.com/oar-sh/oar/issues"
+  },
   "engines": {
     "node": ">=22.13"
   },
@@ -41,7 +45,6 @@
     "LICENSE"
   ],
   "scripts": {
-    "preinstall": "node server/services/package-data-rescue-preinstall.mjs",
     "start": "node server/server.js",
     "copilot:relay": "gh copilot -- --allow-all",
     "test": "node --import ./scripts/node-test-keep-alive.mjs --import ./scripts/node-test-worktree-guard.mjs --test \"server/**/*.test.mjs\" \"shared/**/*.test.mjs\" \".github/extensions/web-relay/**/*.test.mjs\" \"scripts/**/*.test.mjs\"",
@@ -55,24 +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.304",
-    "@cursor/sdk": "1.0.38",
-    "@github/copilot-sdk": "1.0.23",
-    "better-sqlite3": "12.11.1",
-    "express": "4.22.3",
+    "better-sqlite3": "13.0.3",
+    "express": "5.3.0",
     "qrcode-terminal": "0.12.0",
-    "socket.io": "4.8.3",
-    "uuid": "14.0.1",
+    "socket.io": "4.8.4",
     "web-push": "3.6.7",
-    "ws": "8.21.3",
-    "zod": "4.4.3"
-  },
-  "optionalDependencies": {
-    "tty-console": "1.0.4"
+    "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"