tutti/docs/architecture/agent-provider-cli-updates.md

# Agent Provider CLI Updates

Status: current implemented architecture

## Purpose

Provider CLI update discovery and execution are daemon-owned product behavior.
They are intentionally separate from local provider readiness and from the
existing install workflow:

- readiness answers whether the current local CLI, adapter, and auth state can
  launch;
- update discovery checks a trusted remote package source for a newer release;
- install supplies a missing runtime or repairs the minimum supported runtime;
- update is an explicit user action that moves an already installed,
  source-owned runtime to a discovered newer version.

## Ownership

`packages/agent/daemon/providerregistry` owns the provider-neutral update
descriptor: capability, source, execution strategy, package, binary, optional
dependency policy, and stable unsupported reason. The registry validates that a
supported update uses the same managed npm package and binary as the provider's
installer. Shared logic never selects an update strategy by provider id.

`services/tuttid/service/agentstatus` owns local source recognition, cached npm
metadata discovery, version comparison, the explicit update action, and the
mandatory post-update probe. `services/tuttid/api` only projects those domain
results through the OpenAPI contract.

## Read And Refresh Contract

`GET /v1/agent-providers/status` remains local by default:

- no flag: local readiness only; update capability and current version are
  projected without remote discovery;
- `refresh=true`: bypass only the local readiness cache;
- `includeUpdates=true`: opt into cached remote update discovery;
- `includeUpdates=true&refreshUpdates=true`: bypass only the update-metadata
  cache;
- `refreshUpdates=true` without `includeUpdates=true`: no remote discovery.

`includeNetwork` remains an independent opt-in for network diagnostics. Neither
update flag enables it.

Update discovery uses a six-hour daemon cache, including failed outcomes. A
registry timeout, invalid response, or unavailable mirror sets a non-fatal
`reasonCode` on the provider's update status; it does not fail or replace local
readiness.

## Automatic Discovery Scheduler

The daemon owns a separate background scheduler for update discovery. It starts
only after the daemon has published its listener metadata and is ready for
clients. In production, the first check is delayed by 90 seconds (within the
60–120 second startup window), followed by a six-hour interval. These durations
are injectable in scheduler tests.

The device-global `agentCliUpdateCheckEnabled` desktop preference controls the
scheduler and defaults to `true`. A persisted `false` value starts the scheduler
without a timer or remote request. Preference changes cancel an active check or
reschedule the next check from the startup delay. Failed discovery is non-fatal
and retries with bounded exponential backoff beginning at five minutes and
capped at one hour; a successful check restores the six-hour interval. Daemon
shutdown cancels any in-flight discovery and waits for the scheduler to exit.

Scheduled work calls the dedicated managed-provider discovery path directly. It
does not call the ordinary provider readiness/status endpoint, set
`includeNetwork`, request `refresh=true` or `refreshUpdates=true`, run an update
action, or install a package. The same descriptor and local-source gates apply:
only an installed CLI proven to belong to a supported managed npm package may
reach a remote npm registry. Unsupported, missing, and unmanaged runtimes are
local-only decisions.

The update status exposes:

- `capability` and `unsupportedReason`;
- `source`;
- `currentVersion` and `latestVersion`;
- nullable `updateAvailable` (`null` means unchecked, failed, or not safely
  comparable);
- `lastCheckedAt` and non-fatal `reasonCode`.

## Safe Source Gate

A provider descriptor declaring managed npm support is necessary but not
sufficient. For an installed CLI, tuttid must also prove that the resolved
launcher belongs to the descriptor's npm package by locating and validating its
package manifest and npm prefix. A standalone binary, package-manager install,
official-script install, or otherwise unknown origin is reported as
`unsupported` with `unmanaged_install_source`; tuttid does not install a second
copy and call it an update.

Current support matrix:

| Provider                              | Descriptor source                     | Runtime ownership requirement                | Update capability |
| ------------------------------------- | ------------------------------------- | -------------------------------------------- | ----------------- |
| Codex                                 | npm (`@openai/codex`)                 | resolved CLI must belong to that npm package | supported         |
| Tutti Agent                           | managed npm (`@tutti-os/tutti-agent`) | resolved CLI must belong to that npm package | supported         |
| Claude Code, Cursor, OpenCode, Hermes | official script                       | not safely attributable to managed npm       | unsupported       |
| OpenClaw                              | shell command / unknown source        | not safely attributable to managed npm       | unsupported       |
| Nexight                               | provider unavailable                  | no supported update source                   | unsupported       |

## Explicit Update Action

`POST /v1/agent-providers/{provider}/actions/update/run` is distinct from
`install`. The action:

1. verifies the descriptor capability and the installed runtime's managed npm
   ownership;
2. refreshes update metadata and selects the exact discovered version;
3. runs the controlled managed npm executor against the owning prefix;
4. invalidates readiness and update caches;
5. performs a fresh provider probe before reporting completion.

An npm exit failure or failed post-update probe returns a failed action result.
It never reports success solely from the package manager exit code.

## Desktop Interaction And State Projection

The Agents settings table is a compact discovery surface. It may show the
current/latest version summary and open the provider's environment panel, but it
does not execute updates inline. The environment panel owns update discovery,
the explicit Update action, progress/log presentation, post-update detection,
and re-login alongside the other provider setup operations. Keeping the command
in that panel prevents table rows from changing height and gives all environment
remediation one interaction owner.

`IAgentProviderStatusService` is the renderer module seam for this workflow. It
owns request/action orchestration and exposes separate operation signals:

- `isLoading` describes ordinary provider-status query activity;
- `isCheckingUpdates()` describes the complete lifetime of update discovery;
- `isActionPending(provider, "update")` describes the complete update mutation,
  including the refresh and post-action status projection.

UI must not infer update-operation state from `isLoading`: install/update status
polling legitimately toggles query loading between requests. Manual Check for
updates remains disabled while either update discovery or any update action is
pending, while unrelated environment detection does not lock that control.