Runner connectivity and observation lifecycle

Successful registration, Edge connection, execution admission, and compute dependency installation each have independent states. Each step needs its own decision criteria.

Registration, recovery, and refresh

Runner creation first saves a pending record and encrypted connection-command delivery, then registers ownership, and finally advances the internal lifecycle to active. Failure may leave a recoverable intent. Ordinary reads display only active records; an empty list after failure does not prove all writes rolled back.

Replaying with the same workspace, request ID, Principal, and Effective Role can retrieve the delivered command for 30 minutes. Current replay does not establish new payload consistency checks from name. Changing name with the same request ID still returns the original Runner; this is not a rename method. Explicit refresh invalidates the old delivery. An expired window, deleting record, or identity mismatch may return 409 or other errors.

Refresh requires agent_runner.manage, retains Runner/Edge IDs, and returns a new connection command. It competes with active Edge renewal for the current JTI. Limited internal reread/retry does not permit unlimited client refresh. If the response is lost, retain the Runner ID and verify. Ordinary GET cannot retrieve the connection command.

Deregistration first submits a deleting barrier, then handles associated plugin native sessions, credential revocation, ownership, and record cleanup. Existing recovery can continue after failure. This does not guarantee stopping the host astra-edge process, uninstalling software, deleting user files, or immediately canceling every task.

Connection state and permissions

health builds a visible set from readable Runners and enabled Sandboxes, then reads Edge states under the caller’s mapping. Connection state is cached for 5 seconds. Without visible objects, Astra is not called. With objects but an Astra failure, the response contains the object list and astra_reachable=false; this does not establish definite disconnection.

Current connected/ready both derive from a connection match; phase comes from persisted records. Execution still revalidates agent_runner.use or agent_sandbox.use and agent.use on the actual Agent. Health results are not authorization credentials.

Compute dependency observations

Limits reads return current deployment parameters. A missing service returns 503; loading failure returns 500, without fabricated defaults. Installation observations come from saved cloud instances and retain only the current SHA and nonterminal records. An empty list can mean no dependencies, no matching observations, or no assembled service.

Instance READY can coexist with py_requirements_status=FAILED; they describe different layers. Aggregation prioritizes failure, then installation, then readiness. Failed aggregate loading in resource details may omit py_deps. An absent object does not automatically mean installation succeeded.

Errors and recovery

Guide

Main error contract

Runner list/details/create/refresh/delete

String code/msg. 400 INVALID_PARAMS, 404 RUNNER_NOT_FOUND, 403 RUNNER_FORBIDDEN, and 503 RUNNER_IAM_UNAVAILABLE. Name, request identity, in-progress operation, and unavailable delivery conditions have distinct 409 codes.

Edge renewal

Numeric code equals the HTTP status. 401 means invalid old registration credentials or current binding; 503 means unavailable revocation/binding dependencies; other internal failures return 500. Runner string error mappings do not apply.

Executor health

Ordinary success uses string OK/msg. Missing-workspace API errors use numeric 2; service errors use shared mappings. Astra state read failure can still return HTTP 200.

Dependency limits

503 LIMITS_UNAVAILABLE, 500 LIMITS_READ_FAILED; missing workspace returns 400 INVALID_PARAMS.

Worker observations

Any resource precheck error collapses to 404 NOT_FOUND. Other observation-read errors return 500 INTERNAL_ERROR. An absent read service returns an empty array early.

A 404 does not establish global object absence, and an empty array does not establish successful permission/object checks.

Last updated on