Skip to content

Read a release's launcher contract before laying it out or starting it - #1813

Merged
davidmckayv merged 28 commits into
mainfrom
feat/launcher-api-skew
Nov 18, 2026
Merged

davidmckayv merged 28 commits into
mainfrom
feat/launcher-api-skew

Conversation

@davidmckayv

@davidmckayv davidmckayv commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

What this does

OpenBot Desktop now reads a release's launcher contract (compatibility.launcherApi in its release-manifest.json) before it lays out or starts that release, so an app never starts an OpenBot it can't launch.

  • First install. When the latest release needs a newer launcher contract than this app speaks, the app lays out its own release instead and the existing update bar offers the newer app. Same or lower: the latest, as before. A manifest that can't be read: the app's own release.
  • Start. When the installation's release needs a newer launcher contract than this app speaks, the app doesn't start it and doesn't move the installation back. The window shows "Update OpenBot" with "The OpenBot on this computer needs a newer version of this app. Update OpenBot to keep going." and Update and restart (the same screen the version check shows). Same or lower: starts as before. Offline, when the manifest can't be read: starts as before, and a too-new OpenBot then says so itself.
  • launcherApi is not raised here: raising it is a release decision, since the upgrade planner compares it exactly.

Builds on OpenBot PR 1811 (the version check), now merged.

Tests

Each seen failing first.

  • deployment_release.rs: three new tests (a latest release beyond this app's contract lays out the app's own; one at or below lays out the latest; an unreadable manifest lays out the app's own), 19 of 19 pass, with the real v1.1.0 manifest as a fixture (test-fixtures/release-manifest-v1.1.0.json).
  • App.test.tsx: the stopped screen shows only the update card, no failed row, Retry or Repair; the browser layout test's update states, light and dark.
  • cargo fmt, clippy (--all-targets -D warnings), the crate's lib and main tests, the window's tests and typecheck, format and lint: clean.

Mac and Windows pass

The pass of record ran on the tested head 6209b9a, on both a Mac and Windows. The installers came from that head, with the server built from the same change.

  • A fresh install starts normally, with no "Update OpenBot", and so does Quit and reopen.
  • With the minimum raised, Start shows Update OpenBot. With it removed, OpenBot opens again. The Mac also shows the same screen in dark mode.
  • The released 1.0.3 app, against a server of this release:
    • The page reads "This OpenBot needs a newer version of the OpenBot app", and the server stays up with the missing input logged.
    • Every other request is refused, while /health and /api/capabilities answer.
    • 1.0.3's host-access poll stays quiet, and the page is dark when the system is.

Not runnable live, because they need a published release whose manifest says launcherApi 2 (none exists, and none was published for a test):

  • A first install against such a release, and an update offered to one. Covered by a_first_install_lays_out_the_apps_own_release_when_the_latest_needs_a_newer_app, a_release_that_needs_a_newer_app_is_not_started_and_says_update_openbot, and the window test above.
  • Its offline leg, covered by that test's start-launcher-unknown case.

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(-)

…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.
What Desktop writes and hands the back end it starts is a contract with a
number, compatibility.launcherApi in release-policy.json, published in every
release's release-manifest.json. Desktop never read it: it picked a release
by version alone, so an app could lay out, and try to start, a release that
needs settings the app does not write. That is how a 1.0.3 app laid out 1.1.0
for a first install and its server exited for want of the install token.

The app is now built with its release's launcherApi and compares it with the
release's:

- A first install lays out the latest release only when its launcherApi is
  not above the app's. Otherwise, or when its manifest cannot be read, it lays
  out the app's own release, which the app can always start, and the app's
  update offer brings both forward.
- Start does not start a deployment newer than the app whose release names a
  higher launcherApi. It leaves the deployment as it is (never moved back) and
  the window says "Update OpenBot" with Update and restart, through the same
  card the app uses when the OpenBot on this computer names a minimum above
  it. Only a release newer than the app is asked about, once, with no
  retries; with no answer it starts as before.
- A release at the same launcherApi or one behind starts as it always has.

The stopped screen shows that state as the running screen already does: the
heading says Update OpenBot and the card offers the update, with no failed
row, Retry, logs or Repair.

Tests: the first-install choice and the Start refusal against v1.1.0's real
release manifest and a raised copy of it (red before, green after), the
window's Start refusal in App.test.tsx, and the layout of both states, light
and dark, in setupLayout.browser.test.ts.
Takes the version check's 12-month window, its removals and its security
variant. Where they met the launcherApi work:

- client_version.rs: local_problem keeps the security problem (its own
  sentence and app-too-old-security) and builds the ordinary one through
  local_app_too_old, which Start's launcherApi refusal shares.
- App.tsx: the stopped screen's heading takes the same rule as the running
  screen's, the security sentence in place of Update OpenBot.
- App.test.tsx and setupLayout.browser.test.ts keep both the security cases
  and the launcherApi-ahead cases.
…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.
# Conflicts:
#	desktop/src/App.test.tsx
#	desktop/src/setupLayout.browser.test.ts
Base automatically changed from feat/version-check to main November 18, 2026 17:58
# Conflicts:
#	desktop/src-tauri/src/client_version.rs
#	desktop/src/App.test.tsx
#	desktop/src/setupLayout.browser.test.ts
@davidmckayv
davidmckayv marked this pull request as ready for review November 18, 2026 18:17
@davidmckayv
davidmckayv merged commit e254fa3 into main Nov 18, 2026
30 checks passed
@davidmckayv
davidmckayv deleted the feat/launcher-api-skew branch November 18, 2026 18:17
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