Core X agent operations

Available operations

The discovery catalog of the revision you connect to is authoritative. Core X operations cover readiness (agent.preflight), profile-scoped console state (agent.console_get), leases (sessions.ensure, sessions.agent_attach, sessions.lease_release, operations.get), human handoff (sessions.handoff_request, sessions.handoff_resume), measured identity (profiles.effective_fingerprint, profiles.consistency_report), persona creation (personas.contexts_list, profiles.create_from_context), drift (profiles.drift_list, profiles.drift_accept), noise (profiles.noise_status, profiles.noise_upgrade), exit diagnostics (profiles.exit_diagnostics), host health/provisioning (workers.health_get, workers.provision_preview, workers.provision_run) and core delivery (core.freshness_get, workers.core_channel_set). Each reference is generated from the same input/output contract. MCP names replace dots with underscores; the CLI uses browlix call <operation> key=value --json. The SDK uses the same catalog, not a separate database connection.

An agent lease reservation is not a CDP ticket. Existing sessions.attach still issues the same-machine CDP ticket; sessions.agent_attach reserves the reader/writer lease. Writer mode also requires agent.act. Send the same explicit idempotency_key on retries. Ordinary noise/provision commands use command_id. Never generate a new retry key after losing a reply.

A measured fingerprint can be null: that means unmeasured, not enforced. Noise upgrade requires session.start, a closed profile and expected_epoch; drift approval remains required afterwards. Provisioning queues a consented Linux operation, not a completed installation.

Outcomes and permissions

Agent results preserve ok, operation_id, state_version, retryable and next. Refusals include code, remediation_key and outcome; REST additionally carries the conventional error object for existing clients. ACTION_OUTCOME_UNKNOWN returns HTTP 202 and a lookup step: read operations.get or resend the same retry key. Do not treat 202 as completion. SESSION_LEASE_HELD, SESSION_EPOCH_CHANGED, HUMAN_CONTROL_ACTIVE and IDEMPOTENCY_KEY_REUSED are refusals, not reasons to blindly retry. FORBIDDEN and NOT_FOUND preserve scope boundaries. Revoked keys are refused at request level.

Preflight, handoff, host-health, drift and exit reads are present in the current catalog. Availability is not proof of a completed worker action. Page snapshot/state tools remain unavailable until their worker-backed adapter is integrated; never substitute a null report for a successful observation.

Feedback

After using tools, report a distinct bug, friction or missing documentation with feedback_submit; use feedback_list, feedback_get and feedback_comment to follow up. Include a correlation ID and redacted evidence, never tokens, cookies or credentials. Agent feedback.

Readiness and human handoff

agent.preflight requires agent.preflight, not merely session.read. A successful response can have ready=false; inspect every blocker before starting. Empty, missing or stale measurements are not proof of readiness. The console returns only visible profiles, lease state, operation state and allow-listed budget fields; it never returns request hashes, holder identifiers, stored outcomes or page contents.

Handoff request and resume require explicit command_id, idempotency_key and the last-read epoch. Retrying retains both keys. PAUSING and RESUME_PENDING are pending states, not proof of control. Poll the operation and console until signed worker acknowledgement is complete. Returning control currently requires a signed-in human session: an API key is refused with HUMAN_CONTROL_ACTIVE, even for its owner. An agent must ask the operator to resume in the console; it cannot forge human verification.

Persona, drift and host changes

List fresh measured contexts, then use their ID in profiles.create_from_context. The database validates that the context belongs to the workspace and is still fresh; never send an invented hardware observation. A drift acceptance identifies an event as well as the profile, preventing a mismatched path from accepting another profile's drift. Noise upgrades require a closed profile and expected epoch. Provisioning preview has no queue side effect; provisioning run requires explicit consent. A queued command means work is accepted, not installed. Stable/beta channel choices remain subject to the core release gate.

Incomplete observations and recovery

A null fingerprint, health report or exit diagnostic is a successful read of an unmeasured state, not a measured browser result. Page snapshot/state tools are not part of this revision until their worker-backed adapter is integrated. An unknown action outcome remains an error: CLI exit 10, SDK rejection, and an operation lookup next step. Never send a new key to repeat a potentially completed action.

Read-only Core X replies have operation_id=null; this is not a fabricated durable receipt. If transport fails before an operation ID arrives, the SDK preserves the explicit idempotency_key with ACTION_OUTCOME_UNKNOWN. Reconcile by resending that same request, then use the returned operation ID for lookup. Never invent an ID or a new retry key.