ansible

# Ansible - MeshOps Coordination Skill ## What This Is Ansible is a distributed coordination layer that lets you operate across multiple OpenClaw gateways as one coordinated mesh. Four pillars: 1. Ring of Trust: invite/join handshake, auth-gate WebSocket tickets, ed25519-signed capability manifests, per-action safety gates, and token lifecycle. 2. Mesh Sync: Yjs CRDT replication over Tailscale. Messages, tasks, context, and pulse remain durable across reconnects and restarts. 3. Capability Routing: publish/unpublish capability contracts. Each contract references a delegation skill (requester) and an execution skill (executor). 4. Lifecycle Ops: lock sweep, retention/pruning, coordinator sweep, and deployment hygiene. ## Relationship Modes - Friends/Employees (default): other nodes are different agents. Provide context and communicate explicitly. - Hemispheres (advanced): mirrored instances of the same identity. Shared intent and direct communication. Default to Friends/Employees unless explicitly told a node is a hemisphere. ## Node Topology - Backbone: always-on nodes (VPS/servers) that host Yjs WebSocket. - Edge: intermittent nodes (laptops/desktops) that connect to backbone. ## Human Visibility Contract (Required on Pickup) When taking coordination work, maintain explicit lifecycle updates: 1. ACK: confirm receipt and summarize intent. 2. IN_PROGRESS: emit progress updates at meaningful checkpoints. 3. DONE or BLOCKED: close with evidence, next action, and owner. Use `conversation_id` consistently for all related updates. ## Ring of Trust - Behavioral Rules - Unknown nodes require invite-based admission. Do not bypass. - High-risk capability publishes require human approval artifacts. - Respect caller gates (`OPENCLAW_ALLOWED_CALLERS`) and high-risk flags. - Never expose tokens in plaintext messages/logs/shared state. - When signature enforcement is on, only accept manifests signed by trusted publisher keys. ## Gateway Compatibility Contract - Validate plugin is installed and readable before assuming tool availability. - Verify tier assumptions (backbone vs edge) before mutating coordination settings. - Treat gateway runtime as source of truth for active topology and health. ## Reliability Model ### Source of Truth Shared Yjs state is authoritative. ### Delivery Semantics - Durable: messages/tasks persist in shared state. - Auto-dispatch: best-effort realtime injection into sessions. - Heartbeat reconcile: periodic rescan recovers missed injections. - Retry: transient dispatch failures retry with bounded backoff. - Send receipts: notify configured operators when work is placed on mesh. ### Operating Rules - Verify pending work with `ansible_status` and `ansible_read_messages`. - If polling mode is used, always reply via `ansible_send_message`. - Use `corr:<messageId>` for thread continuity. - Listener behavior is optimization; sweep/reconcile is the backstop. ## Capability Contracts - A capability is a contract, not just a label. - Contract includes delegation and execution skill references. - Publishing updates routing eligibility mesh-wide. - Provenance is verified against trusted publisher keys when configured. - High-risk contracts require explicit approval artifacts. - Unpublish removes eligibility immediately. - Lifecycle evidence must capture install/wire outcomes. ## Delegation Protocol 1. Requester creates task with objective, context, acceptance criteria, and target policy (`to_agents` or capability). 2. Executor claims task and sends acceptance/ETA signal. 3. Executor performs work, emits progress, and completes with structured result. 4. Requester reports final outcome to human and/or downstream agents. ## Coordinator Behavior - Run sweep loops for stale locks, SLA drift, and backlog reconciliation. - Prefer record-only escalation by default when blast radius is unclear. - If DEGRADED, prioritize containment, visibility, and deterministic recovery. ## Available Tools ### Communication | Tool | Purpose | |------|---------| | `ansible_send_message` | Send targeted or broadcast message across mesh | | `ansible_read_messages` | Read unread messages (or full history) | | `ansible_mark_read` | Mark messages as read | | `ansible_delete_messages` | Admin-only emergency purge | ### Task Delegation | Tool | Purpose | |------|---------| | `ansible_delegate_task` | Create task for another node/agent set | | `ansible_claim_task` | Claim pending task | | `ansible_update_task` | Update task status/progress | | `ansible_complete_task` | Complete task and notify requester | | `ansible_find_task` | Resolve task by ID/title | ### Context and Status | Tool | Purpose | |------|---------| | `ansible_status` | Mesh health, unread, pending, and topology summary | | `ansible_update_context` | Update shared context/threads/decisions | ### Coordination and Governance | Tool | Purpose | |------|---------| | `ansible_get_coordination` | Read coordinator configuration | | `ansible_set_coordination_preference` | Set node coordinator preference | | `ansible_set_coordination` | Switch coordinator (guarded) | | `ansible_set_retention` | Configure closed-task retention/pruning | | `ansible_get_delegation_policy` | Read delegation policy plus ACKs | | `ansible_set_delegation_policy` | Publish/update delegation policy | | `ansible_ack_delegation_policy` | Acknowledge policy version | | `ansible_lock_sweep_status` | Inspect lock sweep health | ### Capability Lifecycle | Tool | Purpose | |------|---------| | `ansible_list_capabilities` | List published capability contracts | | `ansible_capability_publish` | Publish/upgrade capability contract | | `ansible_capability_unpublish` | Remove capability from routing | | `ansible_capability_lifecycle_evidence` | Show install/wire evidence for version | | `ansible_capability_health_summary` | Show success/error/latency summary | ## When to Use Ansible Use Ansible when work crosses gateways, needs durable coordination, or requires auditable delegation contracts. ## Session Behavior - Start by checking status and pending work. - Prefer explicit delegation for capability-matched work. - Keep humans in loop via lifecycle messages. ## Message Protocol v1 - Always include enough context for independent execution. - Use stable correlation IDs (`corr`) and conversation IDs. - Prefer structured payloads over freeform-only messaging. ## Setup Playbooks Follow plugin setup and gateway runbooks for topology bootstrap, auth-gate, and trust settings. ## Delegation Management - Keep delegation policy current and acknowledged across nodes. - Treat capability publishes as contract releases. - Roll back quickly when lifecycle evidence indicates drift or misfire.