95 lines
4.9 KiB
Markdown
95 lines
4.9 KiB
Markdown
---
|
|
name: multi-agent-mux-delegate-job
|
|
description: "Delegate a unit of work to any autonomous agent (claude-code, hermes, agy, cline, codex, or a human) and observe it asynchronously over an MQTT event channel. Supported roles include orchestrator, worker, and reviewer."
|
|
version: 1.1.0
|
|
author: Multi-Agent System
|
|
license: MIT
|
|
platforms: [linux, macos, windows]
|
|
---
|
|
|
|
# multi-agent-mux-delegate-job — Async Job Delegation over MQTT
|
|
|
|
Delegate a unit of work to any autonomous agent, then **observe** it asynchronously instead of blocking. Every job gets a unique ID and a registry record. The worker agent publishes lifecycle events (`started`, `permission_required`, `progress`, `completed`, `error`) to a per-job MQTT topic, and the delegator/orchestrator subscribes to verify the final state.
|
|
|
|
This skill allows any agent (`claude-code`, `hermes`, `agy`, `cline`, etc.) to play any role: **Orchestrator/Delegator**, **Worker/Implementer**, or **Reviewer**.
|
|
|
|
---
|
|
|
|
## Roles in Multi-Agent Mux
|
|
|
|
- **Orchestrator (Delegator)**: Initiates the job, coordinates other agents, handles loops and reviews, and commits final changes.
|
|
- **Worker (Implementer)**: Receives the brief file or task prompt, performs the implementation, and emits started/completed/error events.
|
|
- **Reviewer**: Evaluates git diffs or artifacts produced by the worker, and responds with a `completed` event containing `"PASS"` or feedback.
|
|
|
|
---
|
|
|
|
## Core Commands (CLI)
|
|
|
|
The `multi-agent-mux-delegate-job` bash wrapper handles job registration, subscriber management, agent session targeting, and validation hooks:
|
|
|
|
```bash
|
|
# 1) Submit a new job to a targeted agent session (e.g. tmux session name 'demo')
|
|
multi-agent-mux-delegate-job submit \
|
|
--agent <claude-code|hermes-agent|agy-agent|cline-agent|human> \
|
|
--agent-session tmux:<session_name> \
|
|
--prompt "Task description or instructions here" \
|
|
--timeout 3600 --idle-timeout 120
|
|
|
|
# 2) Submit a job with a feedback loop (Worker-Reviewer Loop)
|
|
multi-agent-mux-delegate-job submit \
|
|
--agent <worker_agent> --agent-session tmux:<worker_session> \
|
|
--type loop --reviewer <reviewer_agent> --reviewer-session tmux:<reviewer_session> \
|
|
--prompt "Task description"
|
|
|
|
# 3) Check job status and audit logs
|
|
multi-agent-mux-delegate-job status --job <JOB_ID>
|
|
multi-agent-mux-delegate-job logs <JOB_ID> # Chronological log of events
|
|
multi-agent-mux-delegate-job list # Summary of all registered jobs
|
|
|
|
# 4) Verify job artifacts with a validation script
|
|
multi-agent-mux-delegate-job verify --job <JOB_ID> --validate ./validate.sh
|
|
```
|
|
|
|
---
|
|
|
|
## Task Delegation Types
|
|
|
|
Supported job types include:
|
|
- `direct` (default): Single agent execution (direct tasking).
|
|
- `loop` (Worker-Reviewer Loop): Alternates worker execution and reviewer evaluation until reviewer approves (`PASS`) or iterations run out.
|
|
- `discuss` (Research & Discussion): Collaboration between two agents to reach a consensus (e.g., agreeing on a design or plan).
|
|
|
|
For detailed state machine diagrams and configurations, see [DELEGATION_TYPES.md](./DELEGATION_TYPES.md).
|
|
|
|
---
|
|
|
|
## The Event Protocol Contract
|
|
|
|
Every agent participating in the delegation contract must follow the same lifecycle publishing protocol using `publish_event.py`:
|
|
|
|
1. **On Start**: Publish `started` event.
|
|
`python3 .agents/skills/multi-agent-mux-delegate-job/scripts/publish_event.py --job "$JOB_ID" --event started`
|
|
2. **On Tool/Permission Prompt**: Publish `permission_required` event.
|
|
`python3 ... --job "$JOB_ID" --event permission_required --detail "<tool>:<reason>"`
|
|
3. **On Progress Update (Optional)**: Publish `progress` event.
|
|
`python3 ... --job "$JOB_ID" --event progress --detail "<status_update>"`
|
|
4. **On Success**: Publish `completed` event.
|
|
`python3 ... --job "$JOB_ID" --event completed --detail "<summary>"` (Reviewer should include `"PASS"` in the detail to approve).
|
|
5. **On Failure/Feedback**: Publish `error` event.
|
|
`python3 ... --job "$JOB_ID" --event error --detail "<reason_or_feedback>"`
|
|
|
|
---
|
|
|
|
## Audit Logs
|
|
|
|
Job lifecycle execution events are persistently mirrored to an append-only log under `.mam/delegate_job_logs/<job_id>/` (containing `meta.json`, `events.ndjson`, and `status.json`). Use `multi-agent-mux-delegate-job logs <job_id>` to view the timeline.
|
|
|
|
---
|
|
|
|
## Best Practices and Pitfalls
|
|
|
|
- **Subscribe-Before-Publish**: The subscriber must be running before the agent starts publishing. The `submit` command handles this automatically by launching the subscriber in the background first.
|
|
- **Fresh job_id Propagation**: Make sure the worker agent receives the correct `JOB_ID` generated for the current run, rather than reusing stale IDs from previous sessions.
|
|
- **Brief delivery via file path**: For long or complex prompts, write the instructions to a file (e.g. `/tmp/task-brief.md`) and pass a short prompt pointing to the file path to prevent terminal buffer overflows.
|
|
- **Batch Grouping**: Group non-overlapping tasks into batches to parallelize execution across multiple agent sessions, reducing overhead.
|