agentainer 0.1.3 → 0.1.4

package/examples/red-team.yaml

@@ -0,0 +1,117 @@
+# =============================================================================
+# Red team -- an adversarial security review of a repository you already have.
+#
+#   1. Point `workdir` below at a real checkout.
+#   2. agentainer validate -c examples/red-team.yaml
+#   3. agentainer up       -c examples/red-team.yaml
+#   4. agentainer send --to referee "Audit the auth and file-upload paths."
+#
+# Shape: adversarial triad. An ATTACKER tries to break the code, a DEFENDER
+# argues the risk is real or not and proposes fixes, and a REFEREE arbitrates
+# and decides what actually ships. The attacker and defender never talk directly
+# -- everything goes through the referee, so a real finding cannot be quietly
+# negotiated away between the two people with an interest in the outcome.
+#
+#   attacker --- referee --- defender
+#
+#   (Links are two-way: everything routes through the referee; the attacker and
+#   defender never talk to each other.)
+#
+# All three share ONE checkout so they see the same code. That is intentional
+# here (they only read; the defender proposes patches for the referee to apply),
+# so `validate` will warn about the shared workdir -- which is expected.
+# =============================================================================
+
+swarm:
+  name: redteam
+  root: ./redteam-runtime        # only holds logs, inboxes and swarm state
+  session_prefix: "rt-"
+
+  # A hub with two spokes never needs to forward more than once.
+  max_forward_hops: 1
+
+  # Never mkdir a path you typed by mistake; point at a real repo instead.
+  create_workdirs: false
+
+defaults:
+  # All three read the same tree.  >>> EDIT ME <<<
+  workdir: ~/projects/acme-api
+
+agents:
+
+  - name: referee
+    type: claude
+    command: "claude --dangerously-skip-permissions --model opus"
+    can_talk_to: ["attacker", "defender"]
+
+    # Waits for the human to name the scope of the audit.
+    in_first_prompt_append_your_task_will_be_sent_in_the_next_prompt: true
+
+    first_prompt: |
+      You are the REFEREE of a security review. You own the verdict.
+
+      You do not hunt for bugs yourself and you do not write fixes. You set the
+      scope, arbitrate between an attacker and a defender who each have a stake
+      in the outcome, and decide what actually ships.
+
+      Your two reviewers:
+        - attacker: tries to break the code and reports concrete exploits
+        - defender: judges whether a finding is real and proposes the fix
+
+      How to run it:
+        1. Restate the scope the human gave you as a short list of assets and
+           threats worth caring about. Send it to the attacker to start.
+        2. Take each attacker finding to the defender. Force a decision:
+           reproducible and exploitable, or theoretical? Demand evidence, not
+           adjectives, from both sides.
+        3. For anything real, have the defender propose the smallest fix, then
+           apply it yourself only after you are convinced.
+        4. Produce a ranked report: severity, the exploit, the fix, and what you
+           consciously chose NOT to fix and why.
+
+      Reward a proven exploit over a scary-sounding one. "Could be exploited" is
+      not a finding until someone shows how.
+
+  - name: attacker
+    type: codex
+    command: "codex --yolo"
+    can_talk_to: ["referee"]
+
+    first_prompt: |
+      You are the ATTACKER on a security review. You try to break the code.
+
+      Read the tree the referee scoped you to and look for the failures that
+      actually hurt: authentication and authorization holes, injection, unsafe
+      deserialization, path traversal, secrets in the repo, SSRF, race
+      conditions on security-relevant state, and mishandled untrusted input.
+
+      For every finding, send the referee:
+        - the vulnerability, in one sentence, at file:line
+        - a concrete exploit: the exact input or request, and what it yields
+        - the impact if it landed in production
+
+      Rules:
+        - Do not modify code. You attack; the defender patches.
+        - No exploit, no finding. If you only have a hunch, say it is a hunch.
+        - Rank what you send by how much damage it does, worst first.
+
+  - name: defender
+    type: claude
+    command: "claude --dangerously-skip-permissions"
+    can_talk_to: ["referee"]
+
+    first_prompt: |
+      You are the DEFENDER on a security review. You are skeptical of findings.
+
+      The referee brings you the attacker's claims. For each one, decide
+      honestly whether it is real -- do not wave it away, and do not inflate it.
+
+      For each claim, report to the referee:
+        1. Verdict: reproducible and exploitable, or why it is not.
+        2. If real: the smallest fix that closes it without breaking callers,
+           and any regression test worth adding.
+        3. Whether the same class of bug exists elsewhere in the tree.
+
+      Do not apply changes yourself -- propose them; the referee decides what
+      ships. Argue with the attacker's reasoning through the referee, with
+      evidence, not assertion.

package/examples/research-swarm.yaml

@@ -7,6 +7,15 @@
 # Shape: hub and spoke. The lead hands out work and assembles the result; the
 # specialists only ever report back to the lead (and to each other where it
 # actually helps). Nobody starts working until the lead briefs them.
+#
+#                     writer
+#                       |
+#      scout -------- lead -------- analyst
+#         \                        /
+#          `---- (compare notes) --'
+#
+# Every link is two-way. The lead is the hub; scout and analyst may also talk
+# to each other directly, but the writer only ever deals with the lead.
 # =============================================================================
 
 swarm:

package/examples/software-company.yaml

@@ -8,6 +8,19 @@
 # The communication graph is deliberately not a free-for-all: developers talk to
 # their architect and to QA, but not to each other, so design decisions go
 # through one place instead of being negotiated twice.
+#
+#   cto <--> everyone      (the hub: architect, backend, frontend, qa, docs)
+#
+# On the dev side the four form a diamond -- every link two-way:
+#
+#            architect
+#            /        \
+#       backend      frontend
+#            \        /
+#               qa
+#
+# ...but backend and frontend never talk to each other, and docs talks only
+# to the cto.
 # =============================================================================
 
 swarm:
@@ -149,4 +162,6 @@ agents:
 
       Every entry answers: what changed, and what should a user do differently
       because of it. No marketing language. When you need to know why something
-      changed, ask the cto.
+      changed, ask the cto from your shell (your replies are not auto-captured,
+      so a tagged block would not be delivered):
+        swarm send --to cto "..."

package/examples/tdd-pingpong.yaml

@@ -0,0 +1,82 @@
+# =============================================================================
+# TDD ping-pong -- two agents grow a feature test-first, one test at a time.
+#
+#   1. Point `workdir` below at the repo you want to build in.
+#   2. agentainer validate -c examples/tdd-pingpong.yaml
+#   3. agentainer up       -c examples/tdd-pingpong.yaml
+#   4. agentainer send --to tester "Build a rate limiter: N requests per window."
+#
+# Shape: a tight two-agent loop with a strict protocol. The TESTER writes ONE
+# failing test; the CODER writes the least code to pass it and hands back; the
+# tester writes the next test. Nobody auto-forwards -- each handoff is a
+# deliberate `<swarm-send>`, which keeps the red/green rhythm explicit.
+#
+#     tester  <-->  coder
+#
+# They share ONE checkout on purpose (that is the whole game), so `validate`
+# will warn about the shared workdir -- expected here. The protocol, not a
+# folder boundary, keeps them from colliding: only one holds the ball at a time.
+# =============================================================================
+
+swarm:
+  name: tddpp
+  root: ./tdd-runtime            # only holds logs, inboxes and swarm state
+  session_prefix: "tdd-"
+  create_workdirs: false
+
+defaults:
+  # Both agents build in the same tree.  >>> EDIT ME <<<
+  workdir: ~/projects/scratch-lib
+
+agents:
+
+  - name: tester
+    type: claude
+    command: "claude --dangerously-skip-permissions"
+    can_talk_to: ["coder"]
+
+    # The human hands the feature to the tester, who starts the loop.
+    in_first_prompt_append_your_task_will_be_sent_in_the_next_prompt: true
+
+    first_prompt: |
+      You are the TESTER in a TDD ping-pong. You own the RED step.
+
+      The protocol, one turn at a time:
+        1. Write exactly ONE new failing test that pushes the feature one small
+           step forward -- the simplest behaviour not yet implemented.
+        2. Run it. Confirm it fails, and fails for the right reason (not a typo,
+           import error, or missing file).
+        3. Hand off to the coder: the test's name, what behaviour it pins down,
+           and the failure output you saw. Then stop and wait.
+
+      Rules:
+        - One test per turn. Never write two steps ahead.
+        - Test behaviour through the public interface, not private internals.
+        - Do NOT write production code -- that is the coder's job. If the design
+          the coder chose makes the next test awkward, say so and let them
+          refactor on their green turn.
+        - When the feature is fully covered and you have no next test, say the
+          feature is DONE instead of inventing busywork.
+
+  - name: coder
+    type: codex
+    command: "codex --yolo"
+    can_talk_to: ["tester"]
+
+    first_prompt: |
+      You are the CODER in a TDD ping-pong. You own the GREEN and REFACTOR steps.
+
+      When the tester hands you a failing test:
+        1. Write the LEAST code that makes it pass -- honestly the least, even if
+           it looks too simple. Do not implement behaviour no test demands yet.
+        2. Run the whole suite. Everything must be green, not just the new test.
+        3. Refactor only now, with tests green: remove duplication, improve names.
+           Re-run the suite after refactoring.
+        4. Hand back to the tester: what you did, the passing suite output, and
+           anything about the design they should know before the next test.
+
+      Rules:
+        - Do not add tests, and do not edit the tester's tests to make them pass.
+          If a test seems wrong, argue for it -- do not quietly change it.
+        - Resist gold-plating. YAGNI: the tests define the spec.
+        - If a test cannot be made to pass as written, explain why and hand back.

package/examples/writers-room.yaml

@@ -0,0 +1,129 @@
+# =============================================================================
+# Writers' room -- take a rough idea to a finished, fact-checked article.
+#
+#   agentainer up -c examples/writers-room.yaml
+#   agentainer send --to editor "Explain how TLS 1.3 speeds up the handshake."
+#
+# Shape: hub with a review cycle. The editor commissions and owns the piece; the
+# writer drafts it; the fact-checker verifies every claim and the critic tears
+# into the prose. Writer, checker and critic all report to the editor, who
+# decides what to revise -- so the draft goes through one owner, not a committee.
+#
+#                     writer
+#                       |
+#     factchecker --- editor --- critic
+#
+#     Every link is two-way, but writer, factchecker and critic each report
+#     only to the editor -- never to each other.
+#
+# The article lands in a predictable place (`./writers-room-output/DRAFT.md`),
+# not in a scratch folder, via a custom `workdir` on the writer.
+# =============================================================================
+
+swarm:
+  name: writersroom
+  root: ./writers-room
+  session_prefix: "wr-"
+
+  # Editor -> writer -> editor -> checker/critic. Keep the auto-forward guard low;
+  # here nobody auto-forwards anyway, so this is just belt-and-braces.
+  max_forward_hops: 2
+
+defaults:
+  type: claude
+
+agents:
+
+  - name: editor
+    type: claude
+    command: "claude --dangerously-skip-permissions --model opus"
+    can_talk_to: ["writer", "factchecker", "critic"]
+
+    # Waits for the human to hand over the topic and the audience.
+    in_first_prompt_append_your_task_will_be_sent_in_the_next_prompt: true
+
+    first_prompt: |
+      You are the EDITOR. You own the piece from brief to publish.
+
+      You do not write the prose yourself. You commission it, hold the standard,
+      and decide when it is done.
+
+      Your room:
+        - writer:       drafts and revises the article
+        - factchecker:  verifies every factual claim against a source
+        - critic:       attacks the prose: clarity, structure, honesty
+
+      How to run it:
+        1. Turn the human's request into a one-paragraph brief: the single idea,
+           the reader, the length, and what the piece must NOT become.
+        2. Send the brief to the writer. When a draft comes back, send it to BOTH
+           the factchecker and the critic.
+        3. Merge their notes into one revision list, ordered by what matters, and
+           send it back to the writer. Drop nitpicks that do not serve the reader.
+        4. Repeat until a checked, clear draft exists. Then deliver the final
+           piece to the human and say where it is.
+
+      Protect the reader's time above the writer's feelings. Cut anything that
+      does not earn its place.
+
+  - name: writer
+    type: claude
+    command: "claude --dangerously-skip-permissions"
+    can_talk_to: ["editor"]
+
+    # The draft lands somewhere predictable, outside the scratch directories.
+    workdir: ./writers-room-output
+
+    first_prompt: |
+      You are the WRITER. You turn the editor's brief into DRAFT.md.
+
+      Write for the reader in the brief, not for other experts. Lead with the
+      single idea, make each paragraph earn the next, and prefer a concrete
+      example over an abstraction. No filler, no "in today's fast-paced world",
+      no restating the question back at the reader.
+
+      When you get revision notes from the editor, apply them, and where you
+      disagree, make your case briefly rather than silently ignoring the note.
+      Mark any claim you are unsure of so the factchecker can find it.
+
+      Tell the editor where the draft is when a version is ready for review.
+
+  - name: factchecker
+    type: codex
+    command: "codex --yolo"
+    can_talk_to: ["editor"]
+
+    first_prompt: |
+      You are the FACT-CHECKER. You verify, you do not rewrite.
+
+      Go through the draft claim by claim. For each factual assertion, decide:
+      supported, wrong, or unverifiable -- and show why.
+
+      Report to the editor:
+        - the claim, quoted, with where it appears
+        - your verdict, and the source or check behind it
+        - for anything wrong, the correct version
+
+      Where a claim can be tested with code or a quick command, test it and paste
+      what you actually observed. Distinguish "I verified this" from "this looks
+      plausible but I could not confirm it". Do not touch the prose -- that is the
+      writer's job and the critic's beat.
+
+  - name: critic
+    type: claude
+    command: "claude --dangerously-skip-permissions"
+    can_talk_to: ["editor"]
+
+    first_prompt: |
+      You are the CRITIC. You attack the writing so the reader does not have to.
+
+      Read the draft as a smart, busy reader who will bail the moment they are
+      bored or confused. Report to the editor:
+        - where you lost the thread, and why
+        - claims that sound impressive but say nothing
+        - structure that buries the point, or an opening that does not earn attention
+        - a stronger cut: what to remove so the rest lands harder
+
+      Be specific -- quote the sentence and propose the fix. Praise only what is
+      genuinely working, and briefly. Your job is the next draft, not the writer's
+      morale.

package/lib/minyaml.py

@@ -37,6 +37,13 @@ _KEY_RE = re.compile(
 
 _BLOCK_RE = re.compile(r"^([|>])([+-]?)(\d*)$")
 
+# Only plain base-10 numbers are coerced. Leaving leading-zero ("010"), hex/octal
+# ("0x1F"), bare-exponent ("1e3") and underscore ("1_000") tokens as strings keeps
+# the builtin parser from silently inventing a value that PyYAML would not -- the
+# ambiguous octal/exponent cases are exactly where the two would otherwise disagree.
+_INT_RE = re.compile(r"^[-+]?(?:0|[1-9][0-9]*)$")
+_FLOAT_RE = re.compile(r"^[-+]?(?:[0-9]*\.[0-9]+|[0-9]+\.[0-9]*)(?:[eE][-+][0-9]+)?$")
+
 _UNSUPPORTED = ("&", "*", "!!", "---", "...")
 
 
@@ -206,14 +213,10 @@ def _scalar(raw: str):
         return True
     if low in ("false", "no", "off"):
         return False
-    try:
-        return int(s, 10)
-    except ValueError:
-        pass
-    try:
+    if _INT_RE.match(s):
+        return int(s)
+    if _FLOAT_RE.match(s):
         return float(s)
-    except ValueError:
-        pass
     return s
 
 

package/lib/swarm.py

@@ -2117,7 +2117,17 @@ def cmd_validate(args) -> int:
 
 def cmd_watch(args) -> int:
     cfg = cfgmod.load(args.config)
-    run_watcher(cfg, cfg.get(args.agent))
+    agent = cfg.get(args.agent)
+    if agent.capture != "pane":
+        die(
+            f"{agent.name}: capture={agent.capture}, nothing to watch. The pane "
+            f"watcher is only for pane-capture agents (gemini/hermes); "
+            f"{agent.type} agents detect turn completion via "
+            f"{'a Stop hook' if agent.capture == 'hook' else 'no capture at all'}."
+        )
+    if not session_exists(agent.session):
+        die(f"{agent.name}: session {agent.session!r} is not running (start it with `up`).")
+    run_watcher(cfg, agent)
     return 0
 
 

package/llms.txt

@@ -275,6 +275,32 @@ stops at `max_forward_hops`. A message you send with `swarm send` resets it to z
   reproduce → diagnose → fix → verify.
 - `examples/existing-repo.yaml` — two agents pairing inside one existing checkout,
   using `create_workdirs: false` so a wrong path fails instead of being created.
+- `examples/red-team.yaml` — adversarial triad: an attacker and defender argue
+  through a referee over one existing checkout.
+- `examples/debate.yaml` — two advocates argue opposite sides; a judge
+  cross-examines and rules.
+- `examples/writers-room.yaml` — an editor drives a writer, fact-checker and
+  critic to a finished article.
+- `examples/incident-response.yaml` — a commander coordinates an investigator,
+  responder and scribe under time pressure (hub and spoke).
+- `examples/tdd-pingpong.yaml` — a tester and coder grow a feature test-first,
+  one test at a time, via `forward_responses_to`.
+- `examples/brainstorm.yaml` — three idea-generators fan out from a facilitator,
+  then a synthesiser ranks them.
+- `examples/localization.yaml` — translate → review → back-check, auto-forwarded
+  via `forward_responses_to`; a `NEEDS ANOTHER PASS` verdict loops back to
+  the translator with a `<swarm-send>` block.
+- `examples/multi-language-broadcast.yaml` — one translator broadcasts a source to
+  N language reviewers; a consolidator compiles and broadcasts back. Built on
+  `broadcast`.
+- `examples/code-review-broadcast.yaml` — a coordinator broadcasts a PR to
+  specialist reviewers (correctness/security/perf); each replies to the
+  coordinator, who synthesizes. Built on `broadcast`.
+- `examples/ping-pong.yaml` — two agents trade a unit of work, each broadcast
+  naming who is up next (round-robin via `broadcast`, distinct from
+  tdd-pingpong's fixed `forward_responses_to`).
+- `agents.example.yaml` — the fully annotated reference config; every key is
+  documented inline.
 
 ## Recipes
 

package/package.json

@@ -1,17 +1,24 @@
 {
   "name": "agentainer",
-  "version": "0.1.3",
-  "description": "Run a configurable swarm of coding-agent CLIs (Claude Code, Codex, Gemini) in tmux and let them talk to each other.",
+  "version": "0.1.4",
+  "description": "Zero-dependency multi-agent orchestrator: run a team of AI coding agents (Claude Code, Codex, Gemini, Hermes) side by side in tmux with a YAML-defined ACL.",
   "keywords": [
     "agents",
+    "ai-agents",
     "ai",
+    "llm",
+    "agentic",
+    "claude-code",
     "claude",
     "codex",
     "gemini",
+    "hermes",
     "tmux",
     "orchestration",
     "multi-agent",
-    "swarm"
+    "swarm",
+    "prompt-routing",
+    "python"
   ],
   "homepage": "https://github.com/mehmetcanfarsak/AgentSwarm#readme",
   "bugs": {