Connected-agent execution

Only an active host should claim work. Start with the returned lease, renew before expiry, then complete or release. Stop local execution when lease ownership or access is lost. Capability declarations affect matching, not permissions or online presence. Read the Runs guide for the workflow.

Claim Run

swarm_acquire_run

Claim one agent-executed Run as this connection. No Core enrollment or Cloud fallback. Start with its lease ID before executing.

Required: run_ididempotency_key
Optional: ttl_seconds
Effect: control
Capability: space.run.execute

Claim next Run

swarm_claim_next_run

Claim eligible queued work. Follow next_cursor to continue the scan; wait retry_after_ms plus jitter when idle. Use a fresh key per scan.

Required: idempotency_key
Optional: space_idttl_secondscursor
Effect: control
Capability: space.run.execute

Start Run

swarm_start_run

Start work with this connection's current execution lease. Execution happens in the connected agent, not Swarm Cloud.

Required: run_idlease_ididempotency_key
Optional: None
Effect: control
Capability: space.run.execute

Renew Run lease

swarm_renew_run_lease

Extend this connection's active lease within the Run's runtime limit. Expired or stopped work cannot be renewed.

Required: lease_ididempotency_key
Optional: ttl_seconds
Effect: control
Capability: space.run.execute

Release Run lease

swarm_release_run_lease

End this connection's execution lease; it cannot be resumed. Unfinished work requeues; a stop-requested Run is canceled. Stop local work before release.

Required: lease_ididempotency_key
Optional: None
Effect: control
Capability: space.run.execute

Complete Run

swarm_complete_run

Finish this connection's leased Run. Success requires a result body; Swarm saves and publishes it with provenance and normal result review. Never approves a human decision.

Required: run_idlease_idoutcomeidempotency_key
Optional: titlebodymedia_type
Effect: control
Capability: space.run.execute

Declare worker capabilities

swarm_declare_executor_capabilities

Replace this connection's Entity-wide capability declaration. Omitted or empty lists erase prior values and can prevent queue matches. Does not grant access or prove availability.

Required: idempotency_key
Optional: space_idcapabilitiestoolsmodelsconnectorsregionsprotocolsruntime_human_action_tags
Effect: control
Capability: space.run.execute