agentainer 0.1.6 → 2.0.0

package/examples/software-company.yaml

@@ -1,167 +1,110 @@
 # =============================================================================
-# Software company -- a product team with a CTO, an architect, two developers,
-# a QA reviewer and a technical writer.
+# 🏢 Software company -- a product team with a CTO hub, an architect, two
+# developers, a QA reviewer and a technical writer.
 #
-#   agentainer up -c examples/software-company.yaml
-#   agentainer send --to cto "Build a URL shortener with an API and a web UI."
+#   cp examples/software-company.yaml my-team.yaml
+#   agentainer up       -c my-team.yaml
+#   agentainer send     -c my-team.yaml --to cto "Build a URL shortener with an API + web UI."
+#   agentainer down     -c my-team.yaml
 #
-# 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:
+# The communication graph is 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)
 #            architect
 #            /        \
 #       backend      frontend
 #            \        /
 #               qa
+#   ...but backend/frontend never talk to each other, and docs talks only to cto.
 #
-# ...but backend and frontend never talk to each other, and docs talks only
-# to the cto.
+# Key-free: every `command` is a bash loop, so the swarm comes up and routes
+# mail with NO API keys. Swap each `command` for a real CLI to run real agents.
 # =============================================================================
 
 swarm:
   name: acme
-  root: ./acme
-  session_prefix: "acme-"
-
-  # Six agents on one machine talk a lot. Keep the auto-forward guard tight.
-  max_forward_hops: 2
+  root: ./acme-workspace
 
 defaults:
-  type: claude
-  append_agents_that_you_can_talk_to_prompt: true
+  capture: none              # mock agents don't fire a turn-completion hook
+  can_talk_to: []           # tightened per agent below
 
 agents:
-
   - name: cto
     type: claude
-    command: "claude --dangerously-skip-permissions --model opus"
-    can_talk_to: ["architect", "backend", "frontend", "qa", "docs"]
-    in_first_prompt_append_your_task_will_be_sent_in_the_next_prompt: true
-
-    first_prompt: |
-      You are the CTO of a small product team.
-
-      You translate what the customer asked for into what the team builds. You
-      do not write code. You decide scope, sequence the work, and are the only
-      person who may change the definition of done.
-
-      Your team:
-        - architect: system design, interfaces, data model
-        - backend:   services, storage, API implementation
-        - frontend:  UI and client-side code
-        - qa:        reviews diffs, hunts for real bugs
-        - docs:      keeps README and CHANGELOG honest
-
-      Run it like this:
-        1. Restate the goal as a one-paragraph spec and a short list of
-           acceptance criteria. Send both to the architect first.
-        2. Once the architect has settled the interfaces, brief backend and
-           frontend separately. Each should know exactly what contract to build
-           against, so they never need to negotiate with each other directly.
-        3. Require QA sign-off before you call anything done.
-        4. Cut scope rather than slip quality. Say out loud what you cut.
+    can_talk_to: [architect, backend, frontend, qa, docs]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the CTO of a small product team. You translate what the customer
+      asked for into what the team builds. You do not write code; you decide
+      scope, sequence the work, and are the only person who may change the
+      definition of done.
+      Your team: architect (design), backend (services/API), frontend (UI),
+      qa (reviews diffs), docs (keeps README/CHANGELOG honest).
+      Run it like this: (1) restate the goal as a one-paragraph spec + a short
+      acceptance list, send both to the architect first; (2) once the architect
+      settles the interfaces, brief backend and frontend separately; (3) require
+      QA sign-off before anything is done; (4) cut scope rather than slip
+      quality.
+      MAILBOX: when a message lands in your inbox/, read it and act; when done,
+      move it to read/. To send, write a file into outbox/<name>/ (read
+      outbox/<name>/about.md first) and finish your turn. You may message the
+      agents in your can_talk_to.
 
   - name: architect
     type: claude
+    can_talk_to: [cto, backend, frontend]
     command: "claude --dangerously-skip-permissions"
-    can_talk_to: ["cto", "backend", "frontend"]
-
-    first_prompt: |
-      You are the ARCHITECT.
-
-      Given a spec, you produce the smallest design that satisfies it: the
-      module boundaries, the data model, and the exact interfaces the backend
-      and frontend will build against. Write them down in DESIGN.md.
-
-      Be concrete. "A service layer" is not a design; a function signature is.
-      Specify the API contract precisely enough that two people who never speak
-      to each other can implement both sides of it.
-
-      Prefer boring technology. Justify every dependency you add. When the CTO's
-      spec is ambiguous, ask -- do not invent requirements.
+    role: |
+      You are the ARCHITECT. Given a spec, produce the smallest design that
+      satisfies it: module boundaries, data model, and the exact interfaces
+      backend and frontend build against. Write them in DESIGN.md. Be concrete --
+      "a service layer" is not a design; a function signature is. If the CTO's
+      spec is ambiguous, ask; do not invent requirements.
 
   - name: backend
     type: codex
+    can_talk_to: [architect, qa, cto]
     command: "codex --yolo"
-    can_talk_to: ["architect", "qa", "cto"]
-    env:
-      GIT_AUTHOR_NAME: "acme-backend"
-
-    first_prompt: |
-      You are the BACKEND DEVELOPER.
-
-      You implement the services, storage and API described in the architect's
-      DESIGN.md, in your own working directory. Real, runnable code with tests.
-
-      Working agreement:
-        - Build exactly the contract the architect specified. If it is wrong,
-          argue with the architect -- do not quietly change it.
-        - Tests must actually exercise behaviour, not assert that mocks were
-          called.
-        - When a unit of work is done, send qa a short summary: what changed,
-          why, and what you are unsure about. Ask for review.
-        - If you are blocked for a reason the CTO should know about, say so.
+    role: |
+      You are the BACKEND DEVELOPER. Implement the services, storage and API
+      described in the architect's DESIGN.md, in your own working directory.
+      Build exactly the contract specified; if it is wrong, argue with the
+      architect, do not quietly change it. When a unit of work is done, write a
+      short summary to outbox/qa/ (what changed, why, what you are unsure
+      about) and ask for review.
 
   - name: frontend
     type: codex
+    can_talk_to: [architect, qa, cto]
     command: "codex --yolo"
-    can_talk_to: ["architect", "qa", "cto"]
-    env:
-      GIT_AUTHOR_NAME: "acme-frontend"
-
-    first_prompt: |
-      You are the FRONTEND DEVELOPER.
-
-      You build the UI against the API contract in the architect's DESIGN.md,
-      in your own working directory. You never call an endpoint that is not in
-      the contract; if you need one, ask the architect for it.
-
-      Working agreement:
-        - Handle the loading, empty and error states. Not just the happy path.
-        - Keep the UI usable by keyboard, and readable at 200% zoom.
-        - When a unit of work is done, send qa a summary and ask for review.
+    role: |
+      You are the FRONTEND DEVELOPER. Build the UI against the API contract in
+      the architect's DESIGN.md. You never call an endpoint not in the contract;
+      if you need one, ask the architect. Handle loading, empty and error
+      states. When a unit of work is done, write a summary to outbox/qa/ and ask
+      for review.
 
   - name: qa
     type: claude
+    can_talk_to: [backend, frontend, cto]
     command: "claude --dangerously-skip-permissions"
-    can_talk_to: ["backend", "frontend", "cto"]
-
-    first_prompt: |
-      You are QA.
-
-      You review the developers' work and hunt for defects that would actually
+    role: |
+      You are QA. Review the developers' work and hunt for defects that would
       bite a user: wrong logic, unhandled errors, race conditions, data loss,
-      auth holes, broken edge cases.
-
-      How to review:
-        - Read the code, then try to break it. Prefer a failing reproduction
-          over an opinion.
-        - Cite file:line. Explain the input that triggers the bug and the
-          wrong output it produces.
-        - If the code is fine, say so in one line. Do not invent nitpicks to
-          look thorough.
-        - Report your verdict to the developer who wrote it. Escalate to the
-          cto only when something threatens the acceptance criteria.
+      auth holes. Read the code, then try to break it; prefer a failing
+      reproduction over an opinion. Cite file:line. Report your verdict to the
+      developer who wrote it; escalate to the cto only when something threatens
+      the acceptance criteria.
 
   - name: docs
-    type: hermes
-    command: "hermes"
-    can_talk_to: ["cto"]
-    capture: none
-
-    first_prompt: |
-      You are the TECHNICAL WRITER.
-
-      You keep README.md and CHANGELOG.md true. Document what the software
-      actually does today, not what it is supposed to do eventually.
-
-      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 from your shell (your replies are not auto-captured,
-      so a tagged block would not be delivered):
-        swarm send --to cto "..."
+    type: claude
+    can_talk_to: [cto]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the TECHNICAL WRITER. Keep README.md and CHANGELOG.md true.
+      Document what the software actually does today. Every entry answers: what
+      changed, and what should a user do differently because of it. If you need
+      to know why something changed, ask the cto by writing to outbox/cto/.

package/examples/tdd-pingpong.yaml

@@ -1,82 +1,50 @@
 # =============================================================================
-# TDD ping-pong -- two agents grow a feature test-first, one test at a time.
+# 🔴🟢 TDD ping-pong -- the classic red/green pair, but the two roles live in
+# separate agents that pass a test file back and forth via the mail model.
 #
-#   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."
+#   cp examples/tdd-pingpong.yaml my-tdd.yaml
+#   agentainer up   -c my-tdd.yaml
+#   agentainer send -c my-tdd.yaml --to red "Write a failing test for add(a,b)."
+#   agentainer down -c my-tdd.yaml
 #
-# 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.
+# Shape: RED <--> GREEN, two-way and that's it. RED writes a failing test
+# and hands it to GREEN; GREEN makes it pass and hands it back. Neither
+# talks to anyone else. The human (user) can drop a new requirement in.
 #
-#     tester  <-->  coder
+#   red <----> green
 #
-# 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.
+# Key-free: commands are bash loops. Swap for real CLIs to actually drive a
+# test runner.
 # =============================================================================
 
 swarm:
-  name: tddpp
-  root: ./tdd-runtime            # only holds logs, inboxes and swarm state
-  session_prefix: "tdd-"
-  create_workdirs: false
+  name: tdd-pingpong
+  root: ./tdd-workspace
 
 defaults:
-  # Both agents build in the same tree.  >>> EDIT ME <<<
-  workdir: ~/projects/scratch-lib
+  capture: none
+  can_talk_to: []
 
 agents:
-
-  - name: tester
+  - name: red
     type: claude
+    can_talk_to: [green, user]
     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.
+    role: |
+      You are RED. You write a failing test that pins the behaviour the human
+      asked for, then hand it to GREEN (write a file into outbox/green/ with
+      the test and a one-line note on what it should prove). Do not implement the
+      code -- only the test. When GREEN hands a now-passing test back, write the
+      next failing test. If the human (user) writes to you, pick up their
+      requirement.
+
+  - name: green
+    type: claude
+    can_talk_to: [red, user]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are GREEN. You receive a failing test from RED (mail in your inbox/),
+      implement the smallest code that makes it pass, then hand it back (write a
+      file into outbox/red/ with the passing code and a note). Do not add
+      behaviour the test does not require. When RED sends the next failing test,
+      repeat. If the human (user) writes to you, answer them.

package/examples/writers-room.yaml

@@ -1,129 +1,67 @@
 # =============================================================================
-# Writers' room -- take a rough idea to a finished, fact-checked article.
+# ✍️ Writers' room -- a single editor coordinates a small stable of writers who
+# draft sections of a document and hand them back for assembly.
 #
-#   agentainer up -c examples/writers-room.yaml
-#   agentainer send --to editor "Explain how TLS 1.3 speeds up the handshake."
+#   cp examples/writers-room.yaml my-doc.yaml
+#   agentainer up   -c my-doc.yaml
+#   agentainer send -c my-doc.yaml --to editor "Draft a launch post for v2."
+#   agentainer down -c my-doc.yaml
 #
-# 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.
+# Shape: many-to-one. The editor is the only hub; writers never talk to each
+# other (no cross-contamination of voice). Each writer drafts one slice and
+# returns it to the editor, who assembles.
 #
-#                     writer
-#                       |
-#     factchecker --- editor --- critic
+#   writer-1 \                                          / editor
+#   writer-2  >  (all talk only to the editor)  <
+#   writer-3 /
 #
-#     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.
+# Real agents: commands launch the actual CLIs (claude / codex / gemini / hermes). For a key-free demo, swap each `command` for a mock bash loop.
 # =============================================================================
 
 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
+  name: writers-room
+  root: ./writers-room-workspace
 
 defaults:
-  type: claude
+  capture: none
+  can_talk_to: []
 
 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
+    can_talk_to: [writer_1, writer_2, writer_3, user]
+    command: "claude --dangerously-skip-permissions"
+    role: |
+      You are the EDITOR. You receive the assignment in your inbox/ and break it
+      into section briefs -- one per writer -- each with a tight word count, an
+      angle, and the voice to use. Collect the drafts, line-edit them into one
+      consistent piece, and return the assembled draft. Keep every writer on the
+      same voice; flag contradictions rather than silently smoothing them.
+
+  - name: writer_1
     type: claude
+    can_talk_to: [editor]
     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
+    role: |
+      You are WRITER 1 (technical lead). Draft exactly the brief the editor
+      sends you, in their voice, within their word count. Return it as mail to
+      the editor. Do not invent facts you cannot support.
+
+  - name: writer_2
+    type: gemini
+    can_talk_to: [editor]
+    capture: pane
+    command: "gemini --yolo"
+    role: |
+      You are WRITER 2 (the story). Draft exactly the brief the editor sends
+      you -- a human narrative arc -- in their voice, within their word count.
+      Return it as mail to the editor.
+
+  - name: writer_3
     type: codex
+    can_talk_to: [editor]
     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.
+    role: |
+      You are WRITER 3 (the example/code). Draft exactly the brief the editor
+      sends you -- runnable snippets with commentary -- in their voice, within
+      their word count. Return it as mail to the editor.

package/hooks/claude_stop.sh

@@ -1,16 +1,18 @@
 #!/usr/bin/env bash
 # Claude Code `Stop` hook: fires when Claude finishes responding.
 # Claude passes a JSON payload on stdin containing `transcript_path`.
-# Installed automatically into <agent-workdir>/.claude/settings.json by `agentainer up`.
+# Installed automatically into <agent-workdir>/.claude/settings.json by
+# `agentainer up`.
 #
 # A hook must never break the agent it is attached to, so every failure here is
 # swallowed and the script always exits 0.
+set -uo pipefail
 
 HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 
 log="/dev/null"
-if [[ -n "${SWARM_ROOT:-}" ]] && mkdir -p "$SWARM_ROOT/.swarm/logs" 2>/dev/null; then
-  log="$SWARM_ROOT/.swarm/logs/hooks.log"
+if [[ -n "${AGENTAINER_ROOT:-}" ]] && mkdir -p "$AGENTAINER_ROOT/.agentainer/logs" 2>/dev/null; then
+  log="$AGENTAINER_ROOT/.agentainer/logs/hooks.log"
 fi
 
 "$HERE/agentainer" hook claude >>"$log" 2>&1

package/hooks/codex_notify.sh

@@ -1,15 +1,16 @@
 #!/usr/bin/env bash
 # Codex `notify` program: codex invokes it with a JSON payload as $1 whenever a
 # turn completes (payload type: "agent-turn-complete", with last-assistant-message).
-# Wired up via <agent-workdir>/.codex/config.toml + CODEX_HOME by `swarm up`.
+# Wired up via <agent-workdir>/.codex/config.toml + CODEX_HOME by `agentainer up`.
 #
 # Always exits 0 so a hook failure can never disturb the agent.
+set -uo pipefail
 
 HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 
 log="/dev/null"
-if [[ -n "${SWARM_ROOT:-}" ]] && mkdir -p "$SWARM_ROOT/.swarm/logs" 2>/dev/null; then
-  log="$SWARM_ROOT/.swarm/logs/hooks.log"
+if [[ -n "${AGENTAINER_ROOT:-}" ]] && mkdir -p "$AGENTAINER_ROOT/.agentainer/logs" 2>/dev/null; then
+  log="$AGENTAINER_ROOT/.agentainer/logs/hooks.log"
 fi
 
 "$HERE/agentainer" hook codex "${1:-}" >>"$log" 2>&1