Skip to content

Name the app on every request, and say Update OpenBot when an app is older than its OpenBot serves - #1811

Merged
davidmckayv merged 20 commits into
mainfrom
feat/version-check
Nov 18, 2026
Merged

davidmckayv merged 20 commits into
mainfrom
feat/version-check

Conversation

@davidmckayv

@davidmckayv davidmckayv commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

What this does

Every OpenBot app now says who it is on every request, every OpenBot server says which API versions and which app releases it serves, and when an app is older than its OpenBot serves, the person reads one sentence instead of a confusing failure: Update OpenBot. When the minimum was raised for a security problem, the sentence is This version of OpenBot has a security problem. Update to keep using it.

This is the first piece of OpenBot's API versioning, for the two places where OpenBot runs both sides or the server: OpenBot Desktop with its own OpenBot, and OpenBot Cloud, where people's apps lag the server. Desktop connected to a company's own OpenBot gets nothing new: the company rolls out both, and the existing "ask whoever runs it to update" sentence stays as it was.

The contract (spec first, v2, additive)

  • OpenBot-Client: <kind>/<version> on every request, kind web, desktop, mobile or recorder. A header may name several, separated by spaces: OpenBot Desktop adds its own after its window page's (web/1.1.0 desktop/1.1.0). A program of your own sends nothing and is never refused for a version.
  • getDeployment gains api (the API versions served, ["v2"]), minimumClients (the oldest release of each app served), securityMinimumClients (the part of those raised for a security problem, only when there is one), launcherApi and extensionApi (the numbers release-policy.json keeps). It is never refused for the app's version, so an app reads it first.
  • Every other /api/v2 operation refuses an app below its minimum with 400 application/problem+json, code CLIENT_UPDATE_REQUIRED, with client, minimumVersion, security: true when the minimum is there for security, and a detail sentence. Not 426, which RFC 9110 keeps for protocol upgrades.
  • shared/client-version.ts holds the rules; shared/fixtures/client-version/cases.json holds deployment answers and what every app must decide from them. The web app, the Recorder, Desktop (a Rust port) and the phone app (a self-contained copy) each run every case.

The support window is 12 months. A server serves every app released in the last 12 months, so a release builds in a minimum for an app only at a release published more than 12 months before it. Every OpenBot release is younger than that, so the built-in minimums are empty today, and apps from before this change send no header: nothing released is refused by it. A server's minimums are raised in one place, OPENBOT_MINIMUM_CLIENTS on the server (how OpenBot Cloud raises its own), and a minimum is never lowered.

Each app

  • Web app: the header on the one fetch in lib/client.ts (so the generated client too), the CopilotKit provider, sign-in and the consent verifier. A gate at the root, before sign-in as well as after, reads deployment and any CLIENT_UPDATE_REQUIRED refusal, and replaces the app with the sign-in screen's own frame: "Update OpenBot" with Update (loads the new page), or inside the Desktop window, when the refusal names Desktop, its own Update and restart. A tab left open across an upgrade gets the sentence on its next request.
  • OpenBot Desktop: the header on every request the shell makes, and the relay adds it to the page's. With its own OpenBot, the shell reads that OpenBot's deployment before opening the window and shows "Update OpenBot" with Update and restart when the app is too old; a local OpenBot from an older release that still serves v2 opens exactly as before. Connected to OpenBot Cloud, the same check runs when the person connects and on every launch: "The OpenBot at {host} needs a newer version of this app. Update OpenBot, then connect again.", with Update and restart.
  • Phone app: the header (the OpenBot release it was built from, not Expo's own version) on every request and on sign-in, and a root gate with the update sentence.
  • Recorder: the header on every request, and a refusal now reaches the person as the update sentence on the popup, the Connect page and Connect with OpenBot Desktop, where before it read "OpenBot did not answer" or "This connect request has expired".

Tests

Each new test was seen failing before its change and passing after.

  • shared/tests/client-version.test.ts: release order, the header, every fixture case, the empty built-in minimum.
  • app/tests/client-name-header.test.ts, app/tests/client-version-gate.test.tsx: the header reaches a real local server; the app's real root, sign-in gate and screens against a local server answering the fixture's deployments and the spec's own refusals, the security one included.
  • Desktop: client_version.rs runs every fixture case; connected/address.rs, relay.rs, sign_in.rs and main.rs through the real HTTP path with the fake OpenBot; the window's React tests and layout test.
  • mobile/tests/*, extension/tests/openbot-client.test.ts, connection.test.ts, recording.test.ts.
  • Every existing suite still passes: app, extension, Desktop crate and window, root copy and boundary tests.

End to end

On the all-in-one cluster (two server replicas, the backend in the cluster, Keycloak sign-in), from images built from this branch:

  • Nothing built in, nothing refused. deployment answers api: ["v2"], minimumClients: {}, launcherApi: 1, extensionApi: 1; /api/capabilities answers exactly its previous fields. Every app version (desktop/0.0.1 to desktop/1.1.0, web/1.0.0, mobile/0.1.0, recorder/1.0.0), no header, curl/8.7.1 and desktop/main-ci go on to sign-in as before. 17 of 17 checks.
  • Matching versions unaffected. The sign-in screen and home, light and dark, at 1440px and 390px, as before; every request the page makes to /api carries OpenBot-Client: web/1.1.0 (27 of 27; the identity provider's redirect back is a navigation and carries no page header).
  • Minimums raised, as Cloud raises its own (OPENBOT_MINIMUM_CLIENTS=web=1.1.0,desktop=1.2.0,mobile=1.2.0,recorder=1.2.0): deployment publishes them; desktop/1.1.0, mobile/1.1.0, recorder/1.1.0, web/1.0.0 and web/1.1.0 desktop/1.1.0 are refused with 400 application/problem+json, CLIENT_UPDATE_REQUIRED, the app, its minimum and the sentence ("This OpenBot needs OpenBot Desktop 1.2.0 or later. Update OpenBot, then try again."); desktop/1.2.0, no header and curl go on. 24 of 24.
  • A tab left open across an upgrade. Four tabs (light and dark, desktop and phone width) signed in on release 1.1.0; the server rolled to a 1.2.0 build whose admin raised every app to 1.2.0. Moving around the app without reloading, each tab's next request was refused and the page showed "Update OpenBot" / "This page is from an older version of OpenBot." with Update, no sideways scroll; Update loaded the 1.2.0 page, which works and names itself web/1.2.0. 28 of 28.

OpenBot Desktop on a Mac and on Windows

The pass of record ran on the tested head 0fe5a14. The installers came from that head, with the server built from the same change, and every check passed on both:

  • An update over v1.1.0 opens OpenBot, and so does Quit and reopen.
  • With the minimum raised, Start shows Update OpenBot. A relaunch that finds OpenBot running shows the same screen, never "stopped". With the minimum removed, OpenBot opens again.
  • Connected to a real OpenBot for Business server: the sentence with no Connect when the minimum is raised, and the API-version refusal. Sign-in works when the minimum isn't raised. A relaunch after the minimum is raised says so, and opens again once it's removed.

On the Mac, the last of these showed OpenBot's relay page instead of OpenBot. That's a separate, earlier fault in connected Desktop on macOS, with its own fix; the version check's part of the step passed.

The merge head differs from the tested head only by #1826 (pinning the LangGraph harness's Python dependencies), which landed on main in between:

 agent-langgraph-agui/requirements-test.txt             |  1 -
 agent-langgraph-agui/requirements.txt                  | 16 ++++++++++++----
 agent-langgraph-agui/tests/test_provider_boundaries.py | 10 +++++++---
 3 files changed, 19 insertions(+), 8 deletions(-)

davidmckayv and others added 20 commits November 17, 2026 19:52
…e app on every request

The deployment answer gains api (the API versions served), minimumClients (the oldest release of
each app served), launcherApi and extensionApi. Apps name themselves in an OpenBot-Client header,
and an app below its minimum is refused with CLIENT_UPDATE_REQUIRED. shared/client-version.ts holds
the rules every app decides by, and shared/fixtures/client-version the cases each app runs.
…OpenBot when OpenBot refuses them

The phone app sends OpenBot-Client: mobile/<release> on every request it makes to OpenBot: the API
calls, sign-in and the screen socket. The release is the root package.json version, which
app.config.ts reads into extra.openbotRelease as the app is built; Expo's own app version is a
store number and says nothing about which OpenBot this is. Before sign-in the root layout reads the
deployment and decides with the app's own copy of the compatibility rule (Metro bundles only
mobile/), held to every case in shared/fixtures/client-version. An app below the server's minimum,
or a CLIENT_UPDATE_REQUIRED refusal on any request, covers the app with "Update OpenBot". An
OpenBot that answers no deployment but answers /api/capabilities as an OpenBot is from before the
v2 API, and covers it with "Ask whoever runs your OpenBot to update it".

The Recorder sends OpenBot-Client: recorder/<release> from openbotRaw, which every request it makes
to OpenBot goes through, from the service worker and the offscreen document. A CLIENT_UPDATE_REQUIRED
refusal now reaches the popup, the Connect page and Connect with OpenBot Desktop as the Recorder's
own update sentence, built from the app and release the refusal names. Before, the Connect page said
the connect request had expired and the popup that OpenBot did not answer.
…d its OpenBot don't fit

Every request the web app makes to its OpenBot now carries OpenBot-Client: web/<release>: the one
fetch in lib/client.ts (which the generated client's mutator uses too), the CopilotKit runtime's
headers, sign-in's requests and the consent verifier. Headers a caller gives, as a record, Headers or
pairs, are kept beside it.

At the root, around every route, the app decides whether it and its OpenBot can work together, two
ways: from the OpenBot's deployment (compatibility in shared/client-version.ts, read again every
minute and on focus), and from any request the OpenBot refused with CLIENT_UPDATE_REQUIRED, which the
client notes before the request fails. When they don't fit, one screen replaces the app, before
sign-in as well as after, in the sign-in screen's frame:

- this page too old: "Update OpenBot", and Update loads the new page;
- inside OpenBot Desktop, when the refusal names OpenBot Desktop: "Update OpenBot" with Desktop's own
  Update and restart, or, on a build that never updates itself, what to do instead;
- the OpenBot too old: "Ask whoever runs your OpenBot to update it", with Try again.

Tests: a real local HTTP server sees the header on a client request and a generated operation; the
real root, sign-in gate and sign-in screen, served the fixture's deployment answers and the spec's
refusal by a real local server, show the right sentence or none.
… pages at

An admin can't raise the web app's minimum above the server's own release, since every page it
serves would then be refused. The raised answer now names web 1.1.0, and a separate next answer is
what a tab left open across an upgrade to a 1.2.0 server meets.
… needs an update

Every request the shell makes to an OpenBot now carries OpenBot-Client: desktop/<version>: the
connect check, sign-in, refresh and revocation, the readiness and capability pings, host access,
the connection watcher and the Recorder handoff. The relay adds desktop/<version> after whatever
the window's page named, so the OpenBot sees both apps a request came through. The version is the
one the app was packaged as (package_info), set at launch.

Connected to a company's OpenBot, the deployment answer is now read with the shared contract's
rules (client_version.rs, a port of shared/client-version.ts tested against every case in
shared/fixtures/client-version/cases.json), when the person connects and on every launch:

- This app too old (the OpenBot's minimum for desktop is above it, or it serves only a newer API):
  a new app-too-old problem, "The OpenBot at <host> needs a newer version of this app. Update
  OpenBot, then connect again.", and the screen offers this app's own Update and restart.
- The OpenBot too old: the existing too-old problem now says "Ask whoever runs your OpenBot to
  update it, or open it in your browser." An address with no deployment that still answers
  /api/capabilities as an OpenBot (1.0.3 and older, before the v2 API) is too old, not "no OpenBot".

With its own OpenBot on this computer, the window reads that OpenBot's deployment before opening
it. When it needs a newer app, the window says "Update OpenBot" with Update and restart instead
of opening it, and Show Window keeps setup. An OpenBot from an older release, such as 1.1.0 with
no version fields, opens exactly as before.

Wherever setup shows a problem, app-too-old is drawn as a calm notice with the update, not as a
failure, and the update offer at the top stands back while it shows so the window offers one
Update and restart. The Desktop workflow now runs when the shared fixture changes.
…ot older than the app

A server serves every app released in the last 12 months, and every OpenBot
release is younger than that, so no release may be named a built-in minimum
yet. MINIMUM_CLIENTS is now empty; an admin of a server, such as OpenBot
Cloud's, raises it with OPENBOT_MINIMUM_CLIENTS. The fixture's `current`
answer names no minimum, the cases that expected `app` from it now expect
`ok`, and `raised` and `next` keep app-too-old covered. The spec examples read
as a server whose admin raised Desktop to 1.2.0.

An OpenBot older than the app only happens with a company's own OpenBot, and
the company keeps its apps and server matched, so nothing is added for it.
Removed: the "before-v2" deployment from compatibility() in shared and the
phone app, its fixture cases and capabilities answer, Desktop's and the phone
app's /api/capabilities probe and its boundary allowance, the phone app's
"ask whoever runs your OpenBot" screen, and Desktop's server-too-old layout
state. Desktop's too-old sentence is back to its earlier words, and an
OpenBot that serves only an older API maps to it as before. The app-too-old
checks, the OpenBot-Client header and the API-majors rule stay.
A server can raise an app's minimum because older releases have a security
problem. The person should read that, not the plain "Update OpenBot", and
get the same update.

The contract, additive: a CLIENT_UPDATE_REQUIRED problem gains `security`
(true when the minimum was raised for a security problem), and the
deployment gains `securityMinimumClients`, the part of minimumClients raised
for one, with a second refusal example. compatibility() answers
`security: true` when the app is below both its minimum and its security
minimum, and clientUpdateDetail() then gives "This version of OpenBot has a
security problem. Update to keep using it." The fixture gains a `security`
answer and its cases; the phone app and OpenBot Desktop carry the same rule
and run every case.

Each app shows that sentence where it would say "Update OpenBot", with the
same update: the web app's update screen (from the deployment or a refusal),
OpenBot Desktop's connect notice and its screen for the OpenBot on this
computer (a new problem kind, app-too-old-security), the phone app's update
screen, and the Recorder's refusal and Connect with OpenBot Desktop
sentences. Without security nothing changes.
…deprecation count

countedClients now reads the header through client-version's clientTokens, the reading
parseClientHeader is built on, and a test holds the two to the same apps for every header. The
refusal's client is an open enum, as answers that may grow now are. The phone app's tolerant-reader
test gives the mutator the release expo-constants would.
FIRST_ONE_API_RELEASES (1.1.0 for every app: nothing in 1.0.3 calls /api/v2) is what the support
window is measured from, beside the minimums.
…r app

A launch that found this computer's OpenBot already running, and the app
too old for it, said "OpenBot is stopped" with Start OpenBot, the Update
OpenBot card under it, and the tray said "Not running", while the server
was up and answering. show_openbot refused before holding the deployment,
and the window set its running state only after a show that succeeded.

The shell now holds the deployment it found before refusing to show it,
as Start holds the one it raised, so the tray says Running and Stop and
Quit act on it. The window takes an app-too-old refusal from that show as
running, and shows the same Update OpenBot screen as when Start finds it,
with Show OpenBot and Stop OpenBot.

On the connect screen, a build that never updates itself said so under
the notice in body type. The update now draws the notice itself when it
is given the sentence, so the line sits inside it in the notice's type,
as on the screen for the OpenBot on this computer.
@davidmckayv
davidmckayv marked this pull request as ready for review November 18, 2026 17:58
@davidmckayv
davidmckayv merged commit 1e15cfe into main Nov 18, 2026
31 checks passed
@davidmckayv
davidmckayv deleted the feat/version-check branch November 18, 2026 17:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant