Skip to content

Make agent runtime readiness a non-blocking global health service #486

Description

@luokerenx4

Problem

Retesting #481 in packaged Electron exposed the current abstraction boundary:

  • onboarding can sit in a checking state for roughly 45–60 seconds;
  • a slow or hung headless probe can hold the aggregate request open;
  • Electron eventually reports 503 Alice IPC request timed out: POST app://openalice/api/workspaces/agent-runtime-readiness/probe;
  • the page that happened to request the probe becomes responsible for a global product capability.

Agent runtime readiness is consumed by onboarding, quick chat/runtime selection, workspace creation, settings, and recovery guidance. It should not be implemented as an onboarding-owned synchronous operation.

Direction

Introduce an application-level runtime health supervisor:

  • own one current snapshot per agent independently of any page;
  • expose fast snapshot reads and publish updates over the existing event/IPC transport;
  • use stale-while-revalidate semantics instead of making UI requests await headless completion;
  • probe agents independently with bounded deadlines, cancellation, deduplication, and per-agent retry;
  • let one slow runtime time out without delaying healthy runtimes;
  • retain last-known-good state with checkedAt, expiresAt, source, repair target, and diagnostic detail;
  • run startup/background checks at low priority and let explicit Retry enqueue a check and return immediately;
  • keep probes cheap and isolated so readiness checks do not consume developer credentials or real provider quota.

Suggested per-agent states: not_installed, unknown, checking, ready, auth_required, provider_required, failed, and timed_out.

UI contract

  • Product surfaces remain interactive while a probe runs.
  • Show per-agent progress such as “Testing Pi…” instead of a page-wide indefinite spinner.
  • Continue to display last-known state while refreshing.
  • After the deadline, show a clear timeout plus Retry and configuration/install actions.
  • Onboarding, quick chat, settings, and workspace creation consume the same global snapshot rather than starting their own full probe.

Acceptance criteria

  • No renderer IPC request remains open for the lifetime of a headless probe.
  • A hung runtime cannot cause the aggregate readiness endpoint to return 503.
  • Pi can become ready in the UI while another runtime is still checking or timed out.
  • Repeated consumers deduplicate checks instead of spawning duplicate headless processes.
  • Dev/browser and packaged Electron tests cover slow, hung, ready, auth-required, and retry transitions.
  • The packaged onboarding smoke no longer depends on developer-global runtime credentials.

Context

Discovered while narrowing and retesting #481. This is intentionally separate from the onboarding/first-chat polish in that PR and from the Pi skill collision policy in #485.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions