Skip to content

[agent] Hydrate durable Environment status from Parsar retrieve API #16

Description

@sam2tom

Context

Parsar Core at immutable commit 0438880ab21aa16d05cb91a4c7f91cc0abc12358
now exposes:

GET /v1/agents/environments/{environment_id}

for the supported self_hosted profile. The response carries durable
pending, connected, disconnected, expired, or failed status plus safe
API-managed installation metadata arrays.

The merged Environment UI in #5 is pinned to Parsar 8cc2898c. It can show
Session Environment identity and Workspace fields, and it can project supported
live SSE states, but after reload/reconnect it cannot recover connection status
durably. It deliberately treats expired as unknown because the old pin did not
expose the public Environment resource.

Observable outcome: selecting, refreshing, or reconnecting a self-hosted Session
shows the latest durable Environment status, including expired, without
inferring executor or provider readiness.

Acceptance criteria

  • Add a typed Environment resource projection with exact fields id,
    object, type, status, files, plugins, and skills.
  • Keep resource status (pending, connected, disconnected, expired,
    failed) distinct from Session Environment event status (pending,
    ready, connected, disconnected, failed); do not combine them through
    an unchecked string cast.
  • Add a client retrieve method for
    GET /agents/environments/{encoded_environment_id} using the existing
    authentication, beta header, error, and abort contracts.
  • Retrieve durable Environment state only for a valid self_hosted
    Environment ID after the current Session identity is known; do not query
    none or unknown Environment variants.
  • Integrate retrieval with stream recovery: buffer accepted live events,
    apply the durable Session/Items/Environment snapshot, then apply newer
    buffered events.
  • Fence late reads and events by Core generation, Session ID, Environment ID,
    request revision, and abort signal.
  • Render durable expired as a distinct terminal state after initial load,
    refresh, and reconnect, even when no corresponding SSE event exists.
  • Preserve ready as a live-event-only state.
  • Clear stale connected/ready claims when Environment retrieval returns
    missing, unsupported, malformed, unauthorized, or network failure; keep
    the conversation usable and show Environment status as unavailable.
  • Never treat status, empty files/plugins/skills, HTTP health, or an
    open SSE stream as proof that an executor, native runtime, model, or
    provider is ready.
  • Treat empty installation arrays as "no API-managed installations", not as
    host filesystem or capability inventory.
  • Add raw fixtures derived from Parsar
    0438880ab21aa16d05cb91a4c7f91cc0abc12358, including every resource status,
    unknown/malformed variants, and exact empty-array projection.
  • Update the protocol coverage baseline and immutable documentation links to
    the audited Parsar revision. Record the Environment retrieve delta without
    advertising unrelated newly added Parsar APIs as Web-supported.

Validation

  • Client tests for encoded IDs, headers, exact response shape, abort, 400, 401,
    404, 405, 500, malformed payload, and no write/retry behavior.
  • Recovery tests for durable expired after reload, live-only ready, a buffered
    newer event winning over an earlier durable read, stale terminal/live state,
    Session switch, Core switch, and Environment identity change.
  • UI tests for every durable status, unavailable/error states, accessibility, and
    narrow layout.
  • Fixture or local-Core read-only verification of Environment retrieval; no Turn
    or paid model request is required.
  • Run pnpm check, git diff --check, and the repository private-state ignore
    check.

Non-goals

  • Do not create, list, update, delete, provision, or connect Environments.
  • Do not add Files, Plugins, Skills, Artifacts, Vault, or Workspace browsing UI.
  • Do not connect the browser to daemon or executor transports.
  • Do not modify Parsar Core.
  • Do not claim executor/model/provider readiness.
  • Do not make a paid model call, deploy, merge, or delete a branch/Worktree.

Dependencies

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions