@oar-sh/oar 0.9.23 → 0.9.25

package/.github/extensions/web-relay/skills/reasoning-stream.mjs

@@ -168,7 +168,9 @@ export function createReasoningStreamHandlers({
     const reasoningId = reasoningIdFor(event);
     const deltaContent = String(event?.data?.deltaContent ?? event?.data?.delta ?? "");
     if (!deltaContent) return;
-    const accumulated = (reasoningAccum.get(reasoningId) || "") + deltaContent;
+    // Capped before the gate: past the cap the text stops changing, so the
+    // same 16 KiB is not posted again and the accumulator stops growing.
+    const accumulated = capThought((reasoningAccum.get(reasoningId) || "") + deltaContent);
     reasoningAccum.set(reasoningId, accumulated);
     const lastSent = reasoningLastSent.get(reasoningId) || "";
     if (!shouldEmitDelta(accumulated, lastSent)) return;

package/CHANGELOG.md

@@ -3,6 +3,313 @@
 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.25] — 2026-11-09
+
+Highlights: a media gallery, and agents that make images. Every picture,
+video and file of a session is now in one place, the Media tab of the 🧠
+modal, and 🖼️ Media in the ︙ menu shows those of every session of the
+relay, with filters and a search; the file viewer moves through the whole
+gallery. Agents drive OpenAI Image sessions through `relay_tool`: they send
+pictures to edit and set the size, quality, count, format and background.
+While gpt-image works, the reply shows partial previews; the composer gets
+a custom size, a count, a format, a background and presets, and the
+gpt-image-2.5 and 2.6 models take xhigh and max quality. Every image turn
+shows what it cost, a daily cap of USD 5 per relay unless you change it
+keeps image spend in check, and a failed image turn costs at most two calls
+instead of up to five. The relay's memory no longer grows while several
+agents stream long thinking at once.
+
+### Added
+
+- **Media gallery.** The 🧠 modal has two tabs, Context (where it opens)
+  and Media: the session's pictures and videos as a square grid under month
+  headers, three columns on a phone, with a Files tab for attached PDFs,
+  audio and documents. **🖼️ Media** in the ︙ menu shows the media of every
+  session of the relay, with filters (All, Mine, Agent, Generated, a
+  provider, a session, Hide archived) and a search. It collects uploads,
+  `@file:` pictures, generated images and the pictures agents put in their
+  replies; a picture shown in several messages appears once, at its newest
+  message, and a deleted local file is left out. A tap opens the file
+  viewer, which now moves through the whole gallery (it loads more at the
+  end) and offers **Open in session** and **Copy path / link**. The pictures
+  on screen that could not load while the relay was away load again once it
+  is back; one scrolled out of view waits for the next reconnect.
+  Owner only: not in shared views, and no agent reads it through
+  `relay_tool`, on this relay or a paired one.
+- **Media index.** The relay keeps the gallery's index in its database
+  (migration 0039) and fills it for older messages in the background after
+  the upgrade, in short slices.
+- **Agents drive OpenAI Image sessions.** `relay_tool`'s `send` and
+  `create_session` take `images`, up to 4 absolute paths of PNG, JPEG or
+  WebP files on the target relay, and `image`, the turn's size (any W×H
+  within the model's limits), quality, count (1 to 4), output format and
+  background; `update_session` with `image` sets a session's own defaults
+  (migration 0040). The target relay takes only files inside the session's
+  working directory or images one of its sessions generated, follows links
+  to the real file, and checks each file's first bytes. Replies list the
+  pictures as `images` with their paths there, and a reply without text
+  reads like `1 image · 1536x1024 · gpt-image-2`. A paired relay must run
+  this version (`imageInputs` in `relay_info`); an older one is refused
+  before anything is sent. A new image session without a model starts on
+  gpt-image-2.5-flare (else its dated snapshot, else gpt-image-2, else the
+  first gpt-image model listed), and is refused when none is listed.
+
+- **Image previews.** While a gpt-image model makes an image, the reply's
+  bubble shows a timer with the size and quality, then two partial previews
+  as OpenAI streams them, then the final image. Previews reach your open
+  clients only, never the transcript, shared views, the media gallery or
+  agents, and their files go when the turn ends.
+- **Image composer.** An image chat's composer has a Custom… size (any
+  W×H the model takes, checked as you type), a Count (1 to 4), a Format
+  and a Background for gpt-image models.
+
+- **What image turns cost.** Every try of an OpenAI image turn is priced
+  as it ends, from the usage OpenAI reports and its published rates, and
+  estimated where OpenAI reports no usage for a try that may have been
+  billed; a model the relay has no price for counts at the dearest listed
+  price. The reply line ends with the cost, the chat menu shows what a
+  chat's images cost, and Check Usage has an OpenAI images card.
+- **A daily cap for OpenAI images.** USD 5 per relay and day unless you
+  change it (Settings → Providers → OpenAI; 0 is no cap). A request that
+  would pass it is not sent, and once it is reached new image messages are
+  refused, from you and from agents alike; estimates count toward it. A
+  warning shows from 80 %. Allow for today lifts it until midnight.
+- **Image presets.** Five built-in bundles of size, quality, format and
+  background, and your own (Save as preset… in the composer); agents name
+  one as image.preset.
+- **xhigh and max image quality.** The gpt-image-2.5 and 2.6 models take
+  the two higher qualities, in the composer and for agents; other models
+  keep auto, low, medium and high. Sizes for gpt-image-2 and later need at
+  least 655,360 pixels (1024x640), as OpenAI requires.
+
+### Changed
+
+- **OpenAI Image turns.** All attached images go to the edit, in order,
+  not only the first, and the format and background reach OpenAI. Quality
+  is checked per model family before the call (gpt-image: auto, low,
+  medium, high). OpenAI gets 3 minutes for a new image and 5 for
+  an edit (`openaiImageGenerateTimeoutMs`, `openaiImageEditTimeoutMs`).
+- **Copilot hides image models.** Copilot's `gpt-image-*` and `dall-e-*`
+  ids, which its runtime cannot serve, are left out of its model list; a
+  Copilot chat on one is refused with a pointer to OpenAI Image.
+
+### Fixed
+
+- **An image turn costs at most two calls.** A timeout, a server error or
+  a broken connection is tried once more, then the turn ends with a note
+  that says whether the request may have been billed; before, the turn went
+  back into the queue up to five times and ended as "Relay timeout after 5
+  attempts", each attempt a new billed request. When the second try works,
+  the reply notes that the first may have been billed as well. A relay
+  restart during the call no longer repeats it either.
+- **The relay's own image route is local only.** A paired relay's token can
+  no longer call it directly, past the queue.
+- **An agent's prompt header no longer reaches the image model.**
+- **Relay memory no longer grows while several agents stream long thinking
+  at the same time.** A few sessions thinking at length at once could make
+  the relay hold more and more memory until it ran out. Thinking still shows
+  live; a slow connection may skip some of the updates in between, and the
+  whole thought arrives when it ends and after a reconnect, as before.
+
+### Upgrade notes
+
+- **The first start takes a little longer on a big database.** Before it
+  listens, the relay copies its database to the backups folder, as before,
+  and migration 0039 creates the media index and queues every message for
+  it once: about 0.2 s per 200,000 messages on a small server. Migration
+  0040 adds two columns. Nothing else waits.
+- **The gallery fills in the background.** After the start the relay
+  indexes the older messages in slices of about 20 ms every half second,
+  in no particular order: about 3 minutes per 200,000 messages on a small
+  server, longer on a phone or with long messages. Until it ends, the
+  gallery shows what is indexed and "Indexing older messages… (N left)". A
+  restart picks up where it stopped.
+- **The daily cap for OpenAI images is on after the update**: USD 5 per
+  relay and day, in Settings → Providers → OpenAI (0 is no cap). Without an
+  OpenAI key nothing changes, and Check Usage shows no OpenAI images card
+  until something was booked in the month.
+- **Sessions still on 0.9.24's worker wait one worker start.** A session
+  whose worker still runs the old code is given a new worker before its
+  next message, as in 0.9.24. A Claude session's agent gets `images` and
+  `image` in `relay_tool` with its new worker.
+- **Mixed versions work together**, except for images across relays: a
+  0.9.25 relay refuses to send `images` or `image` to a paired 0.9.24 relay
+  and sends nothing, and a 0.9.24 relay cannot send them.
+- **Going back to 0.9.24** needs no database step. Install it with
+  `npm install -g @oar-sh/oar@0.9.24` (in a git checkout:
+  `git checkout v0.9.24`, then a relay restart). 0.9.24 ignores the media
+  index and the image defaults and has no daily image cap, so image turns
+  are not limited there. The index's triggers stay in the database and
+  queue the messages written on 0.9.24, which a later 0.9.25 indexes. To
+  remove the index, drop its two triggers first, then its three tables, as
+  `server/migrations/0039-media-index.mjs` describes; a table dropped
+  before its trigger breaks every new message.
+
+## [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.25"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-mobile.light.png?v=0.9.25"><img src="https://oar.sh/assets/shots/cfmail-mobile.png?v=0.9.25" 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.25"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-agents.light.png?v=0.9.25"><img src="https://oar.sh/assets/shots/cfmail-agents.png?v=0.9.25" 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.25"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-question.light.png?v=0.9.25"><img src="https://oar.sh/assets/shots/cfmail-question.png?v=0.9.25" 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.25"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/pingcf-thoughts.light.png?v=0.9.25"><img src="https://oar.sh/assets/shots/pingcf-thoughts.png?v=0.9.25" 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.25"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/pagewright-watching.light.png?v=0.9.25"><img src="https://oar.sh/assets/shots/pagewright-watching.png?v=0.9.25" 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>
@@ -100,7 +100,7 @@ The runtime (the *provider* in the UI) is chosen in **New Chat** and stays fixed
 | ------- | ---------- | ------------- |
 | [**GitHub Copilot**](docs/providers.md#github-copilot--engine-choice) (default) | GitHub's coding agent, with every model your Copilot plan offers | The Copilot CLI, signed in on the relay host |
 | [**OpenAI (BYOK)**](docs/providers.md#openai-byok-and-openai-image) | Copilot's agent against OpenAI or a compatible endpoint | Your own API key |
-| [**OpenAI Image**](docs/providers.md#openai-byok-and-openai-image) | A chat whose replies are images | The same key |
+| [**OpenAI Image**](docs/providers.md#openai-byok-and-openai-image) | A chat whose replies are images, with a daily spending cap; agents can use it too | The same key |
 | [**Claude**](docs/providers.md#claude-agent-sdk) | Claude Code on your machine | A Claude login, made from **⚙️ Settings** |
 | [**Claude API**](docs/providers.md#claude-api) | Claude Code on your machine, billed to a Claude Console API key; a Claude chat can switch between the two | A Claude Console API key |
 | [**Claude Cloud**](docs/providers.md#claude-cloud) (experimental) | Claude Code in a sandbox at Anthropic, on a GitHub repository | A claude.ai account with GitHub connected |
@@ -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.25"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-steering.light.png?v=0.9.25"><img src="https://oar.sh/assets/shots/cfmail-steering.png?v=0.9.25" 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.25"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/usage-copilot-compact.light.png?v=0.9.25"><img src="https://oar.sh/assets/shots/usage-copilot-compact.png?v=0.9.25" 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>
@@ -134,12 +134,13 @@ API keys are entered in **⚙️ Settings** and stay on the relay host. The Clau
 - **Background work**: a task panel lists the commands and sub-agents that outlive a reply, each with its own **Stop** and its full record; a command's console shows its output live, says when it has gone quiet and counts a test run's passes and failures; the panel and its consoles come back after a relay restart, and a queued restart shows what it waits for and asks after a maximum wait ([Background tasks](docs/web-ui.md#background-tasks), [After a relay restart](docs/web-ui.md#after-a-relay-restart)).
 - **Choose how the agent works**: `ask`, `plan`, `agent` or `autopilot`, plus model and reasoning effort, per message, from the composer's **⚙** ([The composer](docs/web-ui.md#the-composer), [Relay modes](docs/web-ui.md#relay-modes)).
 - **Files and git**: browse the workspace, preview files, review git changes in a diff viewer, and publish a dev server as a preview link ([Files, git, and previews](docs/web-ui.md#files-git-and-previews), [preview servers](docs/preview-servers.md)).
-- **Usage and context**: plan limits and credits of every provider, the estimated spend of DeepSeek and Claude API keys, and what fills the model's context window ([Usage and context](docs/web-ui.md#usage-and-context)).
+- **Media**: the pictures and videos of a session, or of every session, in one gallery, with a file viewer that moves through all of them ([Media](docs/web-ui.md#media)).
+- **Usage and context**: plan limits and credits of every provider, the estimated spend of DeepSeek and Claude API keys and of OpenAI images, and what fills the model's context window ([Usage and context](docs/web-ui.md#usage-and-context)).
 - **Your conversations everywhere**: the history lives on the relay, drafts follow you from device to device, and conversations can be searched, archived, grouped and pinned ([The conversation list](docs/web-ui.md#the-conversation-list), [drafts](docs/web-ui.md#drafts-across-devices), [session groups](docs/web-ui.md#session-groups), [pins](docs/web-ui.md#pinned-messages)).
 - **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.25](CHANGELOG.md#0925--2026-11-09) as the latest.
 
 ## Remote access
 
@@ -190,7 +191,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.25"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/pagewright-cross-relay.light.png?v=0.9.25"><img src="https://oar.sh/assets/shots/pagewright-cross-relay.png?v=0.9.25" 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.25",
   "type": "module",
   "description": "OAR — Open Agent Relay: drive your local coding agents from any browser",
   "license": "MIT",
@@ -25,6 +25,7 @@
     "server/",
     "!server/**/*.test.mjs",
     "!server/**/*-test-harness.mjs",
+    "!server/**/*-test-fixtures.mjs",
     "!server/**/fixtures/",
     "!server/README.md",
     "!server/data/",
@@ -36,6 +37,7 @@
     "shared/",
     "!shared/**/*.test.mjs",
     "!shared/**/*-test-harness.mjs",
+    "!shared/**/*-test-fixtures.mjs",
     "!shared/**/fixtures/",
     ".github/extensions/web-relay/",
     "!.github/extensions/web-relay/**/*.test.mjs",
@@ -58,20 +60,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"