Godopu
54b458d2aa
- Bump all 8 SKILL.md frontmatter version fields to 2.1.0 - Add v2.1.0 changelog in VERSIONS.md highlighting 2xK grid layout engine (B-20), explicit --agent standardization, and --herdr-session option hardening - Update skills version matrix in VERSIONS.md
103 lines
6.3 KiB
Markdown
103 lines
6.3 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: 2.1.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 <claude-code|hermes-agent|agy-agent|cline-agent|human> \
|
|
--agent-session herdr:<session_name> \
|
|
--prompt "Task description or instructions here" \
|
|
--role <Worker|Planner|Reviewer> \
|
|
--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 herdr:<worker_session> \
|
|
--type loop --reviewer <reviewer_agent> --reviewer-session herdr:<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.
|
|
- **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/<id>/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.
|