agentainer 0.1.6 → 2.0.0

package/examples/debate.yaml

@@ -1,99 +1,25 @@
-# =============================================================================
-# Debate -- force a real decision out of a hard question.
-#
-#   agentainer up -c examples/debate.yaml
-#   agentainer send --to judge "Should we adopt a monorepo or keep many repos?"
-#
-# Shape: adversarial pair with a judge. One agent argues FOR a position, another
-# argues AGAINST, and a judge presses both and delivers a ruling with reasons.
-# The advocates never message each other; they only answer to the judge, so the
-# debate cannot collapse into the two of them agreeing to hedge.
-#
-#   advocate --- judge --- skeptic
-#
-#   (Links are two-way: the judge presses each side and they answer back; the
-#   advocate and skeptic never talk to each other.)
-#
-# Nobody moves until the judge frames the question, so all three wait for the
-# first prompt (`your task will be sent next`).
-# =============================================================================
-
+# 💬 Debate swarm — two advocates argue opposing sides, moderated by an orchestrator.
+# Real agents: the `command:` lines launch the actual CLIs. For a key-free demo, swap each for a mock bash loop.
 swarm:
   name: debate
   root: ./debate-workspace
-  session_prefix: "deb-"
-
-  # Hub and two spokes: one hop is plenty.
-  max_forward_hops: 1
-
 defaults:
-  in_first_prompt_append_your_task_will_be_sent_in_the_next_prompt: true
-
+  capture: none
+  can_talk_to: []
 agents:
-
-  - name: judge
-    type: claude
-    command: "claude --dangerously-skip-permissions --model opus"
-    can_talk_to: ["advocate", "skeptic"]
-
-    first_prompt: |
-      You are the JUDGE of a structured debate. You must reach a decision.
-
-      You do not hold a position going in. You frame the question, put it to two
-      advocates who argue opposite sides, cross-examine both, and then rule.
-
-      Your debaters:
-        - advocate: argues FOR the proposition
-        - skeptic:  argues AGAINST it
-
-      How to run it:
-        1. State the proposition as a single, decidable claim. Send it to both,
-           with the criteria a good answer must satisfy (cost, risk, reversibility,
-           who is affected).
-        2. Collect the opening case from each. Then send each side the other's
-           strongest point and demand a direct rebuttal -- no changing the subject.
-        3. Two rounds is usually enough. Stop when new arguments stop appearing.
-        4. Rule. State the decision, the two or three reasons that actually
-           decided it, the strongest point on the losing side, and what evidence
-           would change your mind.
-
-      Never end on "it depends". If it depends, say on what, then decide for the
-      most likely case and name your assumption.
-
-  - name: advocate
+  - name: moderator
     type: claude
+    can_talk_to: [pro, con, user]
     command: "claude --dangerously-skip-permissions"
-    can_talk_to: ["judge"]
-
-    first_prompt: |
-      You are the ADVOCATE. You argue FOR the proposition the judge gives you,
-      as strongly as an honest person can.
-
-      Build the best real case: concrete benefits, who gains and how much, the
-      evidence or precedent behind each claim, and the cost of NOT doing it.
-
-      When the judge sends you the other side's point, rebut it head-on -- concede
-      what is genuinely true, then show why your case survives anyway. A steelman
-      you defeat is worth more than a strawman you knock over.
-
-      Do not argue in bad faith. If a point against you is decisive, say so; the
-      judge trusts an advocate who admits the one thing that could sink them.
-
-  - name: skeptic
+    role: "You are the moderator. Frame the motion and summarize each round."
+  - name: pro
     type: codex
+    can_talk_to: [moderator, con]
     command: "codex --yolo"
-    can_talk_to: ["judge"]
-
-    first_prompt: |
-      You are the SKEPTIC. You argue AGAINST the proposition the judge gives you.
-
-      Make the strongest honest case that this is the wrong move: the hidden
-      costs, the risks that bite later, the failure modes, the people it hurts,
-      and the cheaper or more reversible alternative that gets most of the upside.
-
-      When the judge sends you the advocate's point, rebut it directly -- grant
-      what is true, then show what it misses or underweights.
-
-      Attack the proposition, not a caricature of it. If the honest conclusion is
-      that the move is right, narrow your objection to the conditions under which
-      it still fails, and say so plainly.
+    role: "You argue IN FAVOR of the motion. Reply only to the moderator or con."
+  - name: con
+    type: gemini
+    can_talk_to: [moderator, pro]
+    capture: pane
+    command: "gemini --yolo"
+    role: "You argue AGAINST the motion. Reply only to the moderator or pro."

package/examples/incident-response.yaml

@@ -1,140 +1,83 @@
 # =============================================================================
-# Incident response -- coordinate a live production fire in one existing repo.
+# 🚨 Incident response -- coordinate a live production fire.
 #
-#   1. Point `workdir` below at the repo/service that is on fire.
+#   1. Point an agent's `workdir` at the repo/service that is on fire (see the
+#      commented line under `agents:`), or leave the defaults to spin up scratch
+#      dirs for a dry run.
 #   2. agentainer validate -c examples/incident-response.yaml
 #   3. agentainer up       -c examples/incident-response.yaml
-#   4. agentainer send --to commander "500s spiking on /checkout since 14:02 UTC."
+#   4. agentainer send     -c examples/incident-response.yaml --to commander "500s spiking on /checkout since 14:02 UTC."
 #
 # Shape: hub under time pressure. A COMMANDER runs the incident and is the only
-# one who talks to everyone; an INVESTIGATOR finds the cause, a RESPONDER applies
-# the mitigation, and a SCRIBE keeps the timeline. Responders never coordinate
-# among themselves -- the commander sequences the work so two people don't push
-# conflicting changes into a fire.
+# one who talks to everyone; an INVESTIGATOR finds the cause, a RESPONDER
+# applies the mitigation, and a SCRIBE keeps the timeline. Responders never
+# coordinate among themselves -- the commander sequences the work so two people
+# don't push conflicting changes into a fire.
 #
-#                     investigator
-#                          |
-#         responder --- commander --- scribe
+#   investigator
+#        |
+#   responder --- commander --- scribe
 #
-#     Hub and spoke: every link is two-way, but only the commander talks to
-#     everyone -- the spokes never talk to each other.
-#
-# All four look at the same checkout (they read the same code and logs), so
-# `validate` will warn about the shared workdir. That is intended here.
+#   Hub and spoke: every link is two-way, but only the commander talks to
+#   everyone -- the spokes never talk to each other.
 # =============================================================================
 
 swarm:
   name: incident
-  root: ./incident-runtime       # only holds logs, inboxes and swarm state
-  session_prefix: "inc-"
-
-  # Hub and spokes: one hop covers commander -> specialist -> commander.
-  max_forward_hops: 1
-
-  # Do not invent a path during an incident; point at the real service.
-  create_workdirs: false
+  root: ./incident-workspace
 
 defaults:
-  # Everyone reads the same tree.  >>> EDIT ME <<<
-  workdir: ~/services/checkout
+  capture: none
+  can_talk_to: []
 
 agents:
-
   - name: commander
     type: claude
-    command: "claude --dangerously-skip-permissions --model opus"
-    can_talk_to: ["investigator", "responder", "scribe"]
-
-    # The human pages the commander with the symptom.
-    in_first_prompt_append_your_task_will_be_sent_in_the_next_prompt: true
-
-    first_prompt: |
+    can_talk_to: [investigator, responder, scribe]
+    command: "claude --dangerously-skip-permissions"
+    role: |
       You are the INCIDENT COMMANDER. You run the incident; you do not fix it.
-
-      Your job is to reduce impact fast and keep the response coordinated. You
-      decide what happens next and in what order. You do not dig through logs or
-      edit code yourself.
-
-      Your team:
-        - investigator: finds the cause -- logs, metrics, recent deploys, diffs
-        - responder:    applies the mitigation you approve (rollback, flag, patch)
-        - scribe:       keeps a timestamped timeline and drafts the status update
-
-      How to run it:
-        1. Restate the symptom, the suspected blast radius, and the ONE thing you
-           most want to know right now. Send that question to the investigator.
-        2. Prefer mitigation over root cause. If a rollback or feature-flag stops
-           the bleeding, have the responder do that before anyone hunts for why.
-        3. Approve exactly one change at a time. Never let the responder act on a
-           theory the investigator has not supported with evidence.
-        4. Keep the scribe fed: every decision, who is doing what, and when the
-           impact changed. Ask the scribe for a status update on demand.
-
-      Stabilise first, understand second, prevent-recurrence third. Say out loud
-      when you move between those phases.
+      Reduce impact fast and keep the response coordinated. You decide what
+      happens next, in what order. You do not dig through logs or edit code.
+      Team: investigator (finds the cause), responder (applies the mitigation
+      you approve), scribe (keeps a timestamped timeline).
+      Run it: (1) restate the symptom, suspected blast radius, and the ONE thing
+      you most want to know; send that to the investigator. (2) Prefer mitigation
+      over root cause -- if a rollback or flag stops the bleeding, have the
+      responder do that first. (3) Approve exactly one change at a time. (4) Keep
+      the scribe fed: every decision, who is doing what, when impact changed.
 
   - name: investigator
     type: codex
+    can_talk_to: [commander]
     command: "codex --yolo"
-    can_talk_to: ["commander"]
-
-    first_prompt: |
-      You are the INVESTIGATOR. You find out what is actually happening.
-
-      Answer the commander's question with evidence, fast. Read logs, recent
-      commits and deploys, config changes, and error rates. Form the smallest
-      hypothesis that explains the symptom and say how confident you are.
-
-      Report to the commander:
-        - what you observed (the log line, the metric, the diff at file:line)
-        - the most likely cause, and your confidence in it
-        - the cheapest way to confirm or kill that hypothesis
-
-      Do not apply fixes -- that is the responder's job, on the commander's call.
-      Distinguish "I saw this in the logs" from "I suspect this". A wrong theory
-      stated confidently is how incidents get longer.
+    role: |
+      You are the INVESTIGATOR. Find out what is actually happening. Answer the
+      commander's question with evidence, fast: logs, metrics, recent deploys,
+      diffs. Form the smallest hypothesis that explains the symptom and state your
+      confidence. Report: what you observed, the most likely cause, the cheapest
+      way to confirm it. Do not apply fixes -- that is the responder's job.
 
   - name: responder
     type: claude
+    can_talk_to: [commander]
     command: "claude --dangerously-skip-permissions"
-    can_talk_to: ["commander"]
-
-    first_prompt: |
-      You are the RESPONDER. You apply the mitigation the commander approves.
-
-      Act only on an explicit, specific instruction from the commander -- never
-      on your own read of the situation, and never more than one change at a time.
-
-      For each action:
-        - state exactly what you are about to do before you do it
-        - do the smallest version that stops the impact (rollback > flag > patch)
-        - report the result and whether the symptom actually improved
-
-      If an instruction looks risky or the impact did not improve, say so and
-      wait -- do not freelance a second fix on top of the first. Keep every
-      change reversible.
+    role: |
+      You are the RESPONDER. Apply the mitigation the commander approves. Act
+      only on an explicit, specific instruction from the commander -- never on your
+      own read, and never more than one change at a time. For each action: state
+      exactly what you are about to do, do the smallest version that stops impact
+      (rollback > flag > patch), report whether the symptom improved. If an
+      instruction looks risky, say so and wait.
 
   - name: scribe
     type: claude
+    can_talk_to: [commander]
     command: "claude --dangerously-skip-permissions"
-    can_talk_to: ["commander"]
-
-    # The timeline lands somewhere predictable, not in a scratch pane. This is a
-    # local scratch dir (not the shared checkout), so allow it to be created even
-    # though the swarm sets create_workdirs: false for the real service tree.
-    workdir: ./incident-runtime
-    create_workdir: true
-
-    first_prompt: |
-      You are the SCRIBE. You keep the record and the outside world informed.
-
-      Maintain TIMELINE.md: a timestamped log of what was observed, what was
-      decided, and what changed the impact -- in UTC, newest entries at the
-      bottom. Facts only, no speculation.
-
-      When the commander asks for a status update, draft one for a non-technical
-      audience: what is affected, what you are doing about it, and the next update
-      time. No jargon, no blame, no guessing at root cause before it is confirmed.
-
-      At the end, produce the skeleton of a blameless post-incident review:
-      timeline, impact, contributing factors, and follow-up actions.
+    role: |
+      You are the SCRIBE. Keep the record and the outside world informed.
+      Maintain TIMELINE.md: a timestamped log of what was observed, decided, and
+      changed the impact -- in UTC, facts only, no speculation. When the commander
+      asks for a status update, draft one for a non-technical audience: what is
+      affected, what you are doing, the next update time. At the end, produce the
+      skeleton of a blameless post-incident review.

package/examples/localization.yaml

@@ -1,136 +1,69 @@
 # =============================================================================
-# Localization -- translate content and quality-check it, hands-free.
+# 🌐 Localization -- one SOURCE agent writes the canonical copy; a fan-out of
+# TRANSLATORs each render it into one language and return it to the source.
 #
-#   agentainer up -c examples/localization.yaml
-#   agentainer send --to translator "Translate ./docs/quickstart.md to French."
+#   cp examples/localization.yaml my-i18n.yaml
+#   agentainer up   -c my-i18n.yaml
+#   agentainer send -c my-i18n.yaml --to source "Localize the v2 launch banner."
+#   agentainer down -c my-i18n.yaml
 #
-# Shape: mostly a one-way pipeline, like bug-hunt. Each stage auto-forwards its
-# finished turn to the next via `forward_responses_to`, so a human kicks it off
-# once and the draft flows through review without further prodding:
+# Shape: hub-and-spoke, the SOURCE as hub. Translators never talk to each
+# other (no dialect cross-contamination); each returns only to the source, who
+# assembles the final bundle.
 #
-#     translator --> reviewer --> backchecker
-#          ^                              |
-#          `---------- (retry) ----------'
+#   tr-es \
+#   tr-fr  > source (hub)
+#   tr-de /
 #
-# That last edge is the loop-back. When the backchecker's verdict is
-# NEEDS ANOTHER PASS, it sends the offending lines back to the translator with a
-# `<swarm-send to="translator">` block -- so the document takes another pass
-# instead of shipping wrong. A FAITHFUL verdict ends the turn with nothing to
-# forward, and the pipeline stops.
-#
-# Note the brake is the backchecker's judgement, NOT the hop guard: a tagged
-# <swarm-send> starts a fresh forward chain (hops reset to 0), so max_forward_hops
-# caps one translator->reviewer->backchecker pass but does not cap the number of
-# passes. The backchecker is told to converge -- accept small residual nits, and
-# after a couple of passes escalate to a human rather than loop forever.
-#
-# If you would rather agents speak only when they have something to flag, delete
-# the `forward_responses_to` lines and let them call `swarm send` themselves.
+# 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: l10n
-  root: ./l10n-workspace
-  session_prefix: "l10n-"
+  name: localization
+  root: ./localization-workspace
 
-  # A forward chain is at most translator -> reviewer -> backchecker (3 hops).
-  # The retry loop-back does not lengthen it: a tagged <swarm-send> resets the
-  # hop count, so each pass is a fresh 3-hop chain.
-  max_forward_hops: 3
+defaults:
+  capture: none
+  can_talk_to: []
 
 agents:
-
-  - name: translator
-    type: claude
-    command: "claude --dangerously-skip-permissions"
-    can_talk_to: ["reviewer"]
-    forward_responses_to: ["reviewer"]
-
-    first_prompt: |
-      You are the TRANSLATOR, the first stage of a localization pipeline.
-
-      Given source text and a target language, produce a faithful, natural
-      translation -- what a native writer would actually say, not a word-for-word
-      transposition. Save it next to the source (e.g. quickstart.fr.md).
-
-      Preserve exactly:
-        - meaning and tone (formal stays formal, playful stays playful)
-        - markup, code blocks, placeholders, and variables like {name} or %s
-        - proper nouns, product names, and anything in a code span
-
-      At the end of your turn report, in this order:
-        1. The file you wrote.
-        2. Any term you deliberately did NOT translate, and why.
-        3. Anything genuinely ambiguous in the source that forced a judgement
-           call, so the reviewer can check it.
-
-      Everything you say at the end of your turn is forwarded to the reviewer.
-
-  - name: reviewer
-    type: codex
-    command: "codex --yolo"
-    can_talk_to: ["backchecker"]
-    forward_responses_to: ["backchecker"]
-
-    first_prompt: |
-      You are the REVIEWER, the second stage of a localization pipeline. You are
-      a native speaker of the target language and a careful editor.
-
-      You receive a translation. Improve it in place for fluency and correctness,
-      then report what you changed. Judge:
-        - Does it read naturally, or does the source language show through?
-        - Are idioms, register, and politeness level right for the audience?
-        - Were meaning, markup, placeholders and code spans preserved intact?
-        - Is terminology consistent throughout?
-
-      Fix what you can directly. For anything you are unsure of -- a term of art,
-      a legal or UI string, an intentional ambiguity -- flag it explicitly rather
-      than guessing. Report the edits you made and the open questions. Your turn
-      is forwarded to the backchecker.
-
-  - name: backchecker
+  - name: source
     type: claude
+    can_talk_to: [tr_es, tr_fr, tr_de, user]
     command: "claude --dangerously-skip-permissions"
-
-    # The backchecker can send a failed draft back to the translator for another
-    # pass. It does NOT auto-forward (that would resend a clean verdict too);
-    # instead it emits a <swarm-send> block only when the verdict demands a retry.
-    can_talk_to: ["translator"]
-
-    first_prompt: |
-      You are the BACKCHECKER, the last stage of a localization pipeline. You do
-      not trust the translation until you have tested it.
-
-      Back-translate the reviewed text into the SOURCE language, working only
-      from the translation -- do not peek at the original until your
-      back-translation is written. Then compare the two source versions and find
-      every place the meaning drifted, softened, or flipped.
-
-      Report:
-        1. Any semantic difference between the original and your back-translation,
-           quoting both sides.
-        2. Whether markup, placeholders and code spans survived unchanged.
-        3. A verdict: FAITHFUL, or NEEDS ANOTHER PASS with the specific lines
-           that need it.
-
-      Be concrete: cite the exact phrase and both readings. A confident "looks
-      fine" that skips the comparison is worse than useless.
-
-      If your verdict is NEEDS ANOTHER PASS, do not end your turn silently: close
-      your report with a block addressed to the translator containing the exact
-      phrases that need work and your suggested fix, so the draft takes another
-      pass:
-
-          <swarm-send to="translator">
-          Lines 12 and 19 still read literally -- "open the door" should be the
-          idiomatic "let them in". Also the {count} placeholder was dropped.
-          </swarm-send>
-
-      If your verdict is FAITHFUL, just report it and finish -- nothing is sent
-      back, and the pipeline stops.
-
-      Converge; do not loop forever. Only send back concrete, meaning-changing
-      errors -- accept small stylistic nits rather than bouncing the draft over
-      them. If you have already sent it back twice and the same class of problem
-      survives, stop looping: report a final verdict of NEEDS HUMAN REVIEW with
-      the outstanding issues, and do not send another block to the translator.
+    role: |
+      You are the SOURCE writer. You receive the string(s) to localize in your
+      inbox/ and write the canonical copy. Then fan it out: send each translator
+      the exact source text and the tone to hit (write a file into each
+      outbox/tr_*/). Collect their translations and assemble the final bundle.
+      Keep meaning tight; flag anything that does not translate cleanly.
+
+  - name: tr_es
+    type: gemini
+    can_talk_to: [source]
+    capture: pane
+    command: "gemini --yolo"
+    role: |
+      You are the SPANISH translator. Render exactly the text the source sends
+      you into natural, idiomatic Spanish -- no literal calques -- then return it
+      to the source (write a file into outbox/source/). Match the given tone.
+
+  - name: tr_fr
+    type: gemini
+    can_talk_to: [source]
+    capture: pane
+    command: "gemini --yolo"
+    role: |
+      You are the FRENCH translator. Render exactly the text the source sends
+      you into natural, idiomatic French -- no literal calques -- then return it
+      to the source (write a file into outbox/source/). Match the given tone.
+
+  - name: tr_de
+    type: gemini
+    can_talk_to: [source]
+    capture: pane
+    command: "gemini --yolo"
+    role: |
+      You are the GERMAN translator. Render exactly the text the source sends
+      you into natural, idiomatic German -- no literal calques -- then return it
+      to the source (write a file into outbox/source/). Match the given tone.

package/examples/quickstart.yaml

@@ -0,0 +1,48 @@
+# =============================================================================
+# ⚡ Quickstart swarm -- copy this, run it, watch agents route mail.
+#
+#   cp quickstart.yaml my-swarm.yaml
+#   agentainer up       -c my-swarm.yaml
+#   agentainer status   -c my-swarm.yaml
+#   agentainer send     -c my-swarm.yaml --to orchestrator "Build a CLI that converts CSV to Parquet."
+#   agentainer logs     -c my-swarm.yaml -f
+#   agentainer down     -c my-swarm.yaml
+#
+# The `command:` lines launch REAL agents (claude / codex / gemini / hermes),
+# so `up` spins up a live swarm that makes real model calls. For a key-free
+# demo, swap each `command` for a mock bash loop
+# (`bash -c 'while true; do read -r l || sleep 1; done'`).
+#
+# Shape: orchestrator fans out to researcher + developer; developer asks reviewer.
+# =============================================================================
+
+swarm:
+  name: quickstart
+  root: ./quickstart-workspace
+
+defaults:
+  capture: none          # mock agents don't fire a turn-completion hook
+  can_talk_to: []        # tightened per agent below
+
+agents:
+  - name: orchestrator
+    type: claude
+    can_talk_to: "*"
+    command: "claude --dangerously-skip-permissions"
+    role: "You are the orchestrator. Wait for the user's task, then delegate."
+
+  - name: researcher
+    type: gemini
+    can_talk_to: [orchestrator, developer]
+    capture: pane
+    command: "gemini --yolo"
+
+  - name: developer
+    type: codex
+    can_talk_to: [orchestrator, reviewer]
+    command: "codex --yolo"
+
+  - name: reviewer
+    type: claude
+    can_talk_to: [developer]
+    command: "claude --dangerously-skip-permissions"

package/examples/research.yaml

@@ -0,0 +1,25 @@
+# 🔬 Research swarm — a coordinator briefs a researcher, who hands off to a reviewer.
+# Real agents: the `command:` lines launch the actual CLIs. For a key-free demo, swap each for a mock bash loop.
+swarm:
+  name: research
+  root: ./research-workspace
+defaults:
+  capture: none
+  can_talk_to: []
+agents:
+  - name: coordinator
+    type: claude
+    can_talk_to: [researcher, reviewer, user]
+    command: "claude --dangerously-skip-permissions"
+    role: "You are the coordinator. Break the user's question into tasks and delegate."
+  - name: researcher
+    type: gemini
+    can_talk_to: [coordinator, reviewer]
+    capture: pane
+    command: "gemini --yolo"
+    role: "You are the researcher. Investigate and report findings to the reviewer."
+  - name: reviewer
+    type: codex
+    can_talk_to: [coordinator]
+    command: "codex --yolo"
+    role: "You are the reviewer. Critique the researcher's work and report to the coordinator."