--- 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: 2.0.0 author: godopu license: MIT platforms: [linux, macos, windows] environments: [terminal, herdr] metadata: hermes: tags: [agent, herdr, multi-agent, delegate, mqtt, async, job] related_skills: [multi-agent-mux-create, multi-agent-mux-resume, multi-agent-mux-loop] prereq_skills: [multi-agent-mux-create] --- # 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. herdr session name 'demo') multi-agent-mux-delegate-job submit \ --agent \ --agent-session herdr: \ --prompt "Task description or instructions here" \ --role \ --timeout 3600 --idle-timeout 120 # 2) Submit a job with a feedback loop (Worker-Reviewer Loop) multi-agent-mux-delegate-job submit \ --agent --agent-session herdr: \ --type loop --reviewer --reviewer-session herdr: \ --prompt "Task description" # 3) Check job status and audit logs multi-agent-mux-delegate-job status --job multi-agent-mux-delegate-job logs # 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 --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 ":"` 3. **On Progress Update (Optional)**: Publish `progress` event. `python3 ... --job "$JOB_ID" --event progress --detail ""` 4. **On Success**: Publish `completed` event. `python3 ... --job "$JOB_ID" --event completed --detail ""` (Reviewer should include `"PASS"` in the detail to approve). 5. **On Failure/Feedback**: Publish `error` event. `python3 ... --job "$JOB_ID" --event error --detail ""` --- ## Audit Logs Job lifecycle execution events are persistently mirrored to an append-only log under `.mam/delegate_job_logs//` (containing `meta.json`, `events.ndjson`, and `status.json`). Use `multi-agent-mux-delegate-job logs ` 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. - **Prompts injected into a live agent session MUST be English, ASCII-only, and short** — this is exactly what `--prompt`/the `instructions` string sent to `run_agent()` end up as. Any Korean (or other non-ASCII) content the task needs to convey must go in a markdown brief file (e.g. `.mam/jobs//brief.md`, written in Korean is fine) that the injected prompt merely tells the agent to read. Two independent bugs in `send_keys_safe`'s paste-verification (in `lib.sh`) made this matter in practice: (a) its marker was taken with a byte-based `tail -c 24`, which can slice a multi-byte UTF-8 (e.g. Korean) character in half; (b) the rendered pane soft-wraps long lines at the terminal width, which can split the marker across two visual lines. Both are now fixed at the source (character-safe truncation + newline-stripped matching before comparison), but keeping injected prompts short/English/file-referencing is still the cheapest way to avoid ever exercising this edge case at all — it's also simply what `submit`'s own default instruction template already does (see `Core Commands` above). - **Batch Grouping**: Group non-overlapping tasks into batches to parallelize execution across multiple agent sessions, reducing overhead.