Files
paseo/docs
Mohamed Boudra 4d29ee415a Show provider versions and run provider updates from provider settings (#9568)
* feat(providers): show installed version and install link in provider settings

Providers can now declare `installation`: install and update links plus an
`inspect` callback that reports installed state and an opaque version string.
Built-in clients and plugin providers share one contract; plugins receive the
daemon-resolved launch with `resolved: false` when the executable is missing,
so they can report not installed instead of failing.

The daemon calls `inspect` only on the new
`provider.installation.inspect.request` RPC, never from availability probing,
discovery or session creation, so a slow version probe cannot delay agents.
Results are cached per client for 30s, deadlined at 20s, and links survive a
failed probe. The app gates the provider sheet's Installation row on
`server_info.features.providerInstallation`, so older hosts show nothing new.

* feat(providers): show available updates in provider settings

Providers can now declare `installation.checkForUpdates`, returning
`current`, `available` with opaque `versions` and `message`, or `unknown`.
The provider decides what counts as newer; Paseo shows its answer as
written and never parses or compares versions.

The check is its own RPC, `provider.installation.check_updates`, so the
installed version never waits on a network lookup. The daemon caches a
conclusive answer for an hour and an inconclusive one for 30s, shares
in-flight calls, and deadlines the call at 25s, below the plugin RPC
timeout. A throw or timeout comes back as `error`, which the app shows as
inconclusive, never as up to date. The sheet's Refresh bypasses the cache.

Codex and Claude Code read the release source their own updaters use:
the Homebrew cask for cask installs, otherwise the GitHub latest release
for Codex and the configured `autoUpdatesChannel` for Claude Code.
`codex doctor --json` reports the same answer but scans local state and
took close to a minute, so it is not used. Muse compares its build with
the launcher's channel manifest, the same rule the launcher updates by.

The install link now shows whenever the provider declares `installUrl`
and is not reported installed: the Install button for `not_installed`, a
quieter "Install instructions" link when the check failed or the
provider only links to a guide.

* feat(providers): run provider updates from provider settings

Providers can declare `update(context)`, and the Installation section shows an Update
button when an update is available. The daemon owns the operation: one per provider,
joined by later requests, kept in memory past client disconnects, streamed to subscribers
through an owned subscription, and aborted only when the daemon stops. The provider's
answer is the outcome; the daemon adds no verification. After success it drops the cached
inspection and update check and refreshes discovery, without restarting agents.

Codex and Claude run their own `update` subcommand and pass the output through. Muse has
no update subcommand, so it does not declare one.

Updater output is capped at 64 KiB per update so a chatty updater cannot grow daemon memory.
Starting an update requires daemon.manage because it runs commands on the host.

* feat(providers): report installation for the remaining providers

Copilot, OpenCode, Pi, Oh My Pi, Antigravity and Hoplite now show an
install link and the installed version in provider settings. Each one
declares only what its CLI offers:

- Update checks ask the source the CLI's own updater reads: Pi's
  latest-version endpoint, `omp update --check`, and Hoplite's
  latest.json. Copilot and OpenCode resolve their release inside the
  binary, so they declare no check.
- Updates run the CLI's own command: `copilot update`, `opencode
  upgrade`, `pi update --self` (leaves Pi packages alone), `omp update`.
  Antigravity and Hoplite document no self-update.

OpenCode's success message asks for a daemon restart, because all
OpenCode agents share one server that keeps running the old version.

* docs(providers): document the provider installation contract

Plugin authors get the contract in the provider guide, with a worked
example that reports a version, checks for an update and runs the CLI's
own updater, and every field, deadline and cache in the reference.
The internal provider and plugin docs record why the three callbacks are
separate, that versions are opaque, that Paseo adds no verification to
an update, and how the plugin bridge carries and cancels each request.

* chore(protocol): mark provider installation as shipping in v0.17.0

main is on the 0.16 beta series, and a promotion ships the tested beta's
content without pulling from main, so this lands in the next minor.

* fix(app): bound update output and show refresh failures in provider settings

The screen appended every progress chunk with no limit while open, so a
noisy updater grew memory and never showed the truncation note that a
reopened screen shows. Progress now folds with the daemon's 64 KiB limit.

A manual refresh stored its result and failure outside the queries the
screen reads, so a failed refresh brought back the old answer with no
warning. Refresh now runs through those queries. It passes staleTime 0
because the app's default staleTime of Infinity would otherwise answer
from the cache.

The not-connected error uses the translated string the i18n check
requires.

* fix(providers): keep update checks in step with the installed version

A conclusive check is cached for an hour and was not tied to the version
it answered for. After a CLI updated outside Paseo, settings showed the
new version and still offered Update to it. When an inspection reports a
different version, the cached check is dropped. Versions are compared
for equality, so they stay opaque.

The release comparison dropped prerelease suffixes, so Codex
0.200.0-alpha.1 looked current against 0.200.0. A prerelease now comes
before the release with the same numbers. Two different prereleases of
the same release are reported as unknown.

* docs(providers): say when Update instructions shows

* fix(providers): reuse a cached update check only for the version it answered

The previous fix dropped the cached check after an inspection settled
with a new version. On reopen the app sends inspect and check together,
so the check answered from the stale entry before the inspection
settled. A cached check now records the installed version it was
computed against and is reused only when the current inspection, shared
if in flight, reports the same version.

* fix(app): refresh provider version after an update settles while disconnected

The installation and update queries were invalidated only by a live
succeeded progress event. A connection dropped mid-update delivered the
settled operation as a snapshot on reconnect, which left the old version
and Update on screen. A success the view saw running now rereads them
whether it arrives as progress or as a snapshot.

* fix(providers): keep update checks within their own deadline

Tying a cached check to its version made every check wait for a fresh
inspection, which could add the 20 s inspect deadline to the 25 s check
deadline. A check now never starts an inspection. It waits on one only
when the inspection is cached or already running and the check would
reuse a cached answer. When it asks the provider, it records the version
afterwards.

* test(app): assert provider installation states are visible

* fix(providers): share one update check when two clients reopen after a version change

* fix(muse): report the build the update check compares

Paseo reuses a cached update check while inspect reports the same
version string. Muse reported 1.4.18 but compared its build
(1.4.18-R8600.1), so a new build of the same release kept the stale
"Update available" for up to an hour. The contract docs now say to
include everything the check compares in the reported version.

* test(app): scroll custom model rows into view before checking them

The provider sheet now shows an Installation section above the model
lists. At 390x1000 the custom model row sits under the sheet footer
until scrolled. The spec checks that a long model id leaves its Remove
button reachable. It had assumed the row needed no vertical scroll.

* test(app): keep the custom model check sensitive to a Remove button pushed off the sheet

scrollIntoViewIfNeeded on the Remove button scrolled the overflow-hidden model
card sideways too, so the check passed with the long-id layout fix undone.
Scroll only the Custom models heading into view, which moves the sheet
vertically and leaves the card at scrollLeft 0. With the layout fix undone the
spec now fails at 1200px and 390px again.

* feat(app): offer provider updates whether or not an update check answers

Update and Update instructions lived inside the row that appeared only after
checkForUpdates answered, so Copilot and OpenCode, which declare update but no
check, never offered either. A check is a convenience: the Updates row now
shows for an installed provider that offers an update, keeps Update or Update
instructions in place in every check state (none, checking, up to date,
available, couldn't check), and shows what the check knows as a hint beside
it. A provider that offers no update still shows the check's answer once it
has one. The daemon already ran update without a check; a test now says so.

* fix(app): let update output scroll inside the provider sheet on Android

The output box is a ScrollView nested in the sheet's scrolling body. Android hands the drag to the outer ScrollView unless the inner one sets nestedScrollEnabled, so only the last 240px of a long update's output was readable. The tool-call detail views set the same flag.

* fix(app): show one progress indicator per provider update and refresh

While an update ran, the Update button and the update's row each showed a spinner. The button's
spinner also widened it, and the row's leading spinner shifted the title when the update settled.
The update's row now owns progress from the tap until the update settles: it shows the update
starting before the host answers, so the indicator never moves, and the Update button only
disables.

Refresh blanked the Installation rows while the provider was asked again, then moved "Checking…"
from the Version row to the Updates row. The rows now keep their last answers until the new ones
arrive, and the Refresh button shows the refresh until both the models and the installation are
read again.

* fix(app): show a provider update's progress on its Update button

The pressed button carries an action's progress everywhere else in Settings: Button's own
loading state with a present-participle label, as Browser data's Clear and Project settings'
Save do. Update now does the same, reading "Updating..." from the tap until the update settles,
and the update's row holds only the output while it runs, then the result. This replaces the
row-owned spinner from the previous commit, which no other surface uses.

The installation's in-flight labels use three dots like their siblings.

* fix(app): keep a running update's progress visible whatever the inspection reads

Update carries the update's progress, but its row rendered only while the inspection read
"installed". An inspection that ran during the update (on reopen or Refresh) could read loading,
not installed or failed while the binary was replaced, and the sheet then showed nothing about the
running update. The Updates row now stays while an update runs.

* fix(server): show and update the provider CLI its agents launch

The installation contract found the CLI on the daemon's PATH, while agents
spawn the bare command with the provider's environment. A provider whose env
sets PATH could launch one copy and show and update another, so an update
succeeded while new agents kept the old version. The CLI is now resolved with
the provider's environment.

The section test's check-state table now always names the text it expects, so
no case can skip its assertion.

* test(server): name the provider PATH test for what it shows

The availability check that gates a Copilot spawn still looks on the daemon's
PATH, so the copy on the provider's PATH is not always the one agents launch.

* test(antigravity-provider): read the version from the CLI, not its acp subcommand

Antigravity now launches `agy acp --disable-telemetry`, so the launch the
installation receives ends with the ACP subcommand. The version read drops it,
since `agy acp --version` starts the ACP server.

* feat(plugin): pass the inspected version to checkForUpdates

checkForUpdates now receives installedVersion, the version inspect reported, and
the daemon keys the cached answer on it. Before, each provider read its version
a second time and the daemon recorded which version a cached check answered
for, so a check could compare a different version than the one shown, and a
plugin had to put everything its check compared into the reported version.

An update check now waits for the provider's inspection (shared with a
concurrent inspect, refreshed with it), answers Not installed or the
inspection's error without asking the provider, and is asked again once the
inspection reports a different version.

* fix(server): clear a failed provider update when the provider is refreshed

The daemon kept a provider's last update for its whole lifetime, so a failed
update stayed the current update until a later update succeeded or the daemon
restarted, and the provider looked broken after the user fixed it. A refresh
of the provider's installation or update check now drops a failed result. A
running update is never dropped.

* docs(server): say which agents look up the provider CLI on its PATH

* fix(server): tell open provider views when a refresh drops a failed update

A refresh deleted the failed update on the daemon but sent nothing, so a view
already observing the provider's updates, in this client or another one, kept
showing the failure until it observed again. The daemon now pushes
provider.installation.update.cleared with the dropped operation's id to every
subscriber, and the app clears the update it shows when the ids match.
2026-11-19 20:56:00 +07:00
..