agentainer 0.1.7 → 2.0.0

package/examples/code-review-broadcast.yaml

@@ -1,109 +0,0 @@
-# =============================================================================
-# Code review by broadcast -- one PR, several specialist lenses at once.
-#
-#   1. agentainer validate -c examples/code-review-broadcast.yaml
-#   2. agentainer up       -c examples/code-review-broadcast.yaml
-#   3. agentainer send --to coordinator "Review PR #42 (git diff main...HEAD)."
-#
-# Shape: a hub built on `broadcast`. The COORDINATOR fans the diff out to
-# every reviewer in one message; each REVIEWER owns one concern (correctness,
-# security, performance) and reports back to the coordinator, who synthesizes a
-# single review. The reviewers never talk to each other -- cross-cutting findings
-# are the coordinator's job to merge.
-#
-#        coordinator
-#            |  (broadcast the PR to all)
-#            v
-#     +-------+--------+
-#     |       |        |
-#  correctness security  perf
-#     |       |        |
-#     +--- coordinator ---+   (each reviewer replies to the coordinator)
-#
-# `broadcast` is the point of the example: the coordinator reaches several
-# peers with one message and does not care which are mid-task. Every link is
-# two-way. The change under review is passed in the prompt, so the swarm
-# validates and runs without pointing at any repo.
-# =============================================================================
-
-swarm:
-  name: review
-  root: ./review-runtime        # only holds logs, inboxes and swarm state
-  session_prefix: "rv-"
-
-  # Broadcasts don't auto-forward, so one hop is all the guard ever needs.
-  max_forward_hops: 1
-
-  # Each agent gets its own scratch folder under `root` for logs and state.
-  # The change under review is passed in the prompt (a `git diff`), so the agents
-  # never need to read a repo off disk -- point `workdir` here only if you want
-  # them to read the tree directly.
-  create_workdirs: true
-
-agents:
-
-  - name: coordinator
-    type: claude
-    command: "claude --dangerously-skip-permissions --model opus"
-    can_talk_to: ["correctness", "security", "perf"]
-
-    in_first_prompt_append_your_task_will_be_sent_in_the_next_prompt: true
-
-    first_prompt: |
-      You are the REVIEW COORDINATOR. You do not review code yourself; you run
-      the review and merge the findings.
-
-      When the human gives you a change (a PR or a `git diff`), broadcast it to
-      every reviewer at once, each with the one concern they own:
-
-          <swarm-broadcast>
-          Review this change (PR #42, git diff main...HEAD):
-            - correctness: does it do what it claims? logic, edge cases, regressions
-            - security:    injection, authz, secrets, unsafe deserialization
-            - perf:        hot paths, N+1s, allocations, unbounded growth
-          Reply to me (the coordinator) with findings only for your lane.
-          </swarm-broadcast>
-
-      Collect the three replies. Merge overlapping findings, dedupe, and rank by
-      severity. Produce ONE consolidated review: a short verdict (Approve / Request
-      changes) followed by a bullet list of findings with file:line and the lane
-      that raised each. Do not invent findings the reviewers did not make.
-
-  - name: correctness
-    type: claude
-    command: "claude --dangerously-skip-permissions"
-    can_talk_to: ["coordinator"]
-    first_prompt: |
-      You are the CORRECTNESS reviewer. You receive a change broadcast by the
-      coordinator; review ONLY whether it does what it claims.
-
-      Look for: logic errors, off-by-one and boundary mistakes, wrong types or
-      null handling, missing or wrong edge-case handling, and silent regressions
-      in behaviour. Quote the offending line. When done, reply to the coordinator
-      with findings for this lane only -- nothing about security or performance.
-
-  - name: security
-    type: claude
-    command: "claude --dangerously-skip-permissions"
-    can_talk_to: ["coordinator"]
-    first_prompt: |
-      You are the SECURITY reviewer. You receive a change broadcast by the
-      coordinator; review ONLY for security risk.
-
-      Look for: injection (SQL/command/HTML), broken or missing authz, secrets
-      committed or logged, unsafe deserialization, path traversal, and trust of
-      unvalidated input. Quote the offending line and the abuse scenario. When done,
-      reply to the coordinator with findings for this lane only.
-
-  - name: perf
-    type: codex
-    command: "codex --yolo"
-    can_talk_to: ["coordinator"]
-    first_prompt: |
-      You are the PERFORMANCE reviewer. You receive a change broadcast by the
-      coordinator; review ONLY for performance.
-
-      Look for: accidental O(n^2) or N+1 patterns, allocations in hot loops,
-      unbounded growth (caches, lists), missing batching or indexes, and blocking
-      calls on the request path. Quote the offending line and the expected cost.
-      When done, reply to the coordinator with findings for this lane only.

package/examples/existing-repo.yaml

@@ -1,74 +0,0 @@
-# =============================================================================
-# Pair programming on a repository you already have.
-#
-# This example does NOT create any folders. Both agents are started inside one
-# existing checkout, so they see each other's edits immediately -- a driver who
-# writes the code and a navigator who reads it as it lands.
-#
-#   driver <--> navigator      (a two-way pair sharing one checkout)
-#
-#   1. Point `workdir` below at a real repository.
-#   2. agentainer validate -c examples/existing-repo.yaml
-#   3. agentainer up       -c examples/existing-repo.yaml
-#   4. agentainer send --to driver "Add retry-with-backoff to the HTTP client."
-#
-# Until you edit the paths, `validate` will refuse to run and tell you so --
-# that is the point of `create_workdir: false`.
-# =============================================================================
-
-swarm:
-  name: pair
-  root: ./pair-runtime      # only holds logs, inboxes and swarm state
-  session_prefix: "pair-"
-
-  # Never silently mkdir a path the user typed. If it does not exist, that is a
-  # typo, not an instruction to create it.
-  create_workdirs: false
-
-defaults:
-  # Both agents share one checkout. Every agent inherits this unless it
-  # overrides `workdir` itself.
-  #
-  #   >>> EDIT ME <<<
-  workdir: ~/projects/acme-api
-
-agents:
-
-  - name: driver
-    type: claude
-    command: "claude --dangerously-skip-permissions"
-    can_talk_to: ["navigator"]
-
-    first_prompt: |
-      You are the DRIVER in a pairing session. You have the keyboard.
-
-      You are working in a real repository that someone cares about. Before you
-      change anything, read enough of it to match its conventions.
-
-      Working agreement:
-        - Make one coherent change at a time, then tell the navigator what you
-          did and why, so they can review it while you continue.
-        - Run the tests before you claim something works. Paste real output.
-        - Never commit, push, or rewrite git history unless explicitly asked.
-        - If the navigator finds a real bug, fix it before moving on.
-
-  - name: navigator
-    type: codex
-    command: "codex --yolo"
-    can_talk_to: ["driver"]
-
-    first_prompt: |
-      You are the NAVIGATOR in a pairing session. You do not have the keyboard.
-
-      You read what the driver writes, in the same working tree, and you think
-      one step ahead of them. Do not edit files -- your job is to catch what
-      they cannot see while typing.
-
-      Watch for:
-        - logic that is wrong on an edge case the tests do not cover
-        - error paths that swallow failures
-        - a change that breaks an existing caller elsewhere in the repo
-        - drifting away from how the rest of this codebase does things
-
-      Report findings to the driver, citing file:line, with the concrete input
-      that goes wrong. If a change looks correct, say so briefly and move on.

package/examples/multi-language-broadcast.yaml

@@ -1,127 +0,0 @@
-# =============================================================================
-# Multi-language broadcast -- one source, several translations in parallel.
-#
-#   agentainer up -c examples/multi-language-broadcast.yaml
-#   agentainer send --to translator "Translate ./docs/quickstart.md to es, fr, de."
-#
-# Shape: a fan-out built on `broadcast`, not `forward_responses_to`. One
-# TRANSLATOR holds the source and fans it out to every reviewer at once; the
-# REVIEWERS each own one language and report back to a single CONSOLIDATOR,
-# who compiles the finished set and broadcasts it back to the translator.
-#
-#        translator
-#            |  (broadcast source to all)
-#            v
-#     +-------+--------+
-#     |       |        |
-#   es-rev  fr-rev  de-rev
-#     |       |        |
-#     +--- consolidator ---+   (each reviewer replies to the consolidator)
-#            |
-#        translator          (consolidator broadcasts the compiled piece back)
-#
-# `broadcast` is the point of this example: the translator reaches several
-# peers with one message and does not care who is busy. Every link is two-way,
-# and the reviewers never talk to each other -- all coordination runs through
-# the translator and the consolidator.
-# =============================================================================
-
-swarm:
-  name: l10n-multi
-  root: ./l10n-multi-workspace
-  session_prefix: "ml-"
-
-  # Broadcasts don't auto-forward, so one hop is all the guard ever needs.
-  max_forward_hops: 1
-
-agents:
-
-  - name: translator
-    type: claude
-    command: "claude --dangerously-skip-permissions"
-
-    # Can reach everyone: broadcasts the source out, and receives the compiled
-    # piece back from the consolidator.
-    can_talk_to: ["es-rev", "fr-rev", "de-rev", "consolidator"]
-
-    first_prompt: |
-      You are the TRANSLATOR and keeper of the source. You start each job with
-      one source document and a list of target languages.
-
-      Produce a single faithful, natural rendering of the source per language, as a
-      native writer would actually say it -- not a word-for-word transposition.
-      Preserve exactly: meaning and tone, markup, code blocks, and placeholders
-      like {name} or %s.
-
-      Then fan it out: broadcast the source text to every reviewer at once so they
-      each translate their own language in parallel. Use:
-
-          <swarm-broadcast>
-          Source (English):
-          ...
-          Translate to your language only. es-rev -> Spanish, fr-rev -> French,
-          de-rev -> German.
-          </swarm-broadcast>
-
-      Wait for the consolidator to return the compiled set, then save each
-      language next to the source (e.g. quickstart.es.md) and finish.
-
-  - name: es-rev
-    type: claude
-    command: "claude --dangerously-skip-permissions"
-    can_talk_to: ["consolidator", "translator"]
-    first_prompt: |
-      You are the SPANISH reviewer. You receive a source text broadcast by the
-      translator and return a faithful, natural Spanish translation of it.
-
-      Preserve meaning, tone, markup, code blocks and placeholders exactly. Read
-      naturally; if the source language shows through, fix it. When done, reply to
-      the consolidator (not the group) with your Spanish text and any term you
-      deliberately did not translate and why.
-
-  - name: fr-rev
-    type: claude
-    command: "claude --dangerously-skip-permissions"
-    can_talk_to: ["consolidator", "translator"]
-    first_prompt: |
-      You are the FRENCH reviewer. You receive a source text broadcast by the
-      translator and return a faithful, natural French translation of it.
-
-      Preserve meaning, tone, markup, code blocks and placeholders exactly. Read
-      naturally; if the source language shows through, fix it. When done, reply to
-      the consolidator (not the group) with your French text and any term you
-      deliberately did not translate and why.
-
-  - name: de-rev
-    type: claude
-    command: "claude --dangerously-skip-permissions"
-    can_talk_to: ["consolidator", "translator"]
-    first_prompt: |
-      You are the GERMAN reviewer. You receive a source text broadcast by the
-      translator and return a faithful, natural German translation of it.
-
-      Preserve meaning, tone, markup, code blocks and placeholders exactly. Read
-      naturally; if the source language shows through, fix it. When done, reply to
-      the consolidator (not the group) with your German text and any term you
-      deliberately did not translate and why.
-
-  - name: consolidator
-    type: claude
-    command: "claude --dangerously-skip-permissions"
-    can_talk_to: ["translator", "es-rev", "fr-rev", "de-rev"]
-    first_prompt: |
-      You are the CONSOLIDATOR. You collect one translation per language from the
-      reviewers and assemble the finished set.
-
-      You will receive several replies -- keep them straight by language. Compile
-      them into one message that lists each language's text. When the set is
-      complete, broadcast it back to the translator so they can save the files:
-
-          <swarm-broadcast>
-          Compiled translations:
-          Spanish:  ...
-          French:   ...
-          German:   ...
-          </swarm-broadcast>
-
-      Do not edit the translations; your job is to gather, not to re-translate.

package/examples/ping-pong.yaml

@@ -1,89 +0,0 @@
-# =============================================================================
-# Ping-pong -- two agents trade a unit of work back and forth, in turn.
-#
-#   1. Point `workdir` below at the repo you want to build in.
-#   2. agentainer validate -c examples/ping-pong.yaml
-#   3. agentainer up       -c examples/ping-pong.yaml
-#   4. agentainer send --to runner "Build a rate limiter: N requests per window."
-#
-# Shape: a round-robin built on BROADCAST. This is deliberately different from
-# tdd-pingpong.yaml, which uses `forward_responses_to` (one fixed next step):
-# here every handoff is a broadcast that names who is up next, so the same
-# group can rotate any number of roles in any order.
-#
-#        runner  <-->  coder
-#        (each broadcasts to the group, naming the next agent in the @-tag)
-#
-# 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: pingpong
-  root: ./pingpong-runtime        # only holds logs, inboxes and swarm state
-  session_prefix: "pp-"
-
-  # Broadcasts don't auto-forward, so one hop is all the guard ever needs.
-  max_forward_hops: 1
-
-  # Never mkdir a path you typed by mistake; point at a real repo instead.
-  create_workdirs: false
-
-defaults:
-  # Both agents build in the same tree.  >>> EDIT ME <<<
-  workdir: ~/projects/scratch-lib
-
-  type: claude
-  command: "claude --dangerously-skip-permissions"
-  # They can each reach the other, so either can broadcast the handoff.
-  can_talk_to: ["runner", "coder"]
-
-agents:
-
-  - name: runner
-    # Override: the runner starts the job and holds the spec.
-    command: "claude --dangerously-skip-permissions"
-    can_talk_to: ["coder"]
-
-    in_first_prompt_append_your_task_will_be_sent_in_the_next_prompt: true
-
-    first_prompt: |
-      You are the RUNNER. You own the task and the spec; the CODER implements
-      it. You two trade the work back and forth, exactly one of you active at a
-      time.
-
-      To hand off, broadcast to the group but name the coder explicitly as up
-      next, and sign your turn so the other agent knows who just spoke:
-
-          <swarm-broadcast>
-          @coder: your turn. Implement step 1 -- a token bucket with N
-          requests per window and a refill rate. Don't exceed the spec.
-          -- runner
-          </swarm-broadcast>
-
-      When the coder hands back ("@runner: your turn -- done, here's what I
-      built"), review it against the spec. If it meets the bar, broadcast a
-      final "done" and stop. If not, broadcast the next instruction to the
-      coder. Never both work at once; the ball is always with one of you.
-
-  - name: coder
-    command: "claude --dangerously-skip-permissions"
-    can_talk_to: ["runner"]
-
-    first_prompt: |
-      You are the CODER. You implement what the RUNNER specifies, one step at a
-      time, and hand each step back for review.
-
-      When the runner broadcasts a turn ending in "@coder: your turn", do exactly
-      that step -- no more, no freelancing. When done, broadcast back naming the
-      runner and reporting what you built:
-
-          <swarm-broadcast>
-          @runner: your turn -- done. Token bucket with N=100 per 60s window,
-          lazy refill on read. Tests pass.
-          -- coder
-          </swarm-broadcast>
-
-      Wait for the runner's next instruction or a "done". Do not start the next
-      step on your own, and do not edit while the runner holds the ball.

package/examples/red-team.yaml

@@ -1,117 +0,0 @@
-# =============================================================================
-# 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

@@ -1,129 +0,0 @@
-# =============================================================================
-# Research swarm -- a small team that investigates a topic and writes it up.
-#
-#   agentainer up -c examples/research-swarm.yaml
-#   agentainer send --to lead "Research the state of WebGPU compute shaders."
-#
-# 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:
-  name: research
-  root: ./research-workspace
-  session_prefix: "r-"
-
-defaults:
-  type: claude
-
-agents:
-
-  - name: lead
-    type: claude
-    command: "claude --dangerously-skip-permissions"
-    can_talk_to: ["scout", "analyst", "writer"]
-
-    # The lead waits for the human to supply the research question.
-    in_first_prompt_append_your_task_will_be_sent_in_the_next_prompt: true
-
-    first_prompt: |
-      You are the RESEARCH LEAD.
-
-      You own the research question end to end. You do not gather sources or
-      write prose yourself -- you decompose the question, delegate, challenge
-      what comes back, and assemble the final answer.
-
-      Your team:
-        - scout:   finds primary sources, docs, papers, prior art
-        - analyst: reads code and data, runs experiments, checks claims
-        - writer:  turns findings into a clear written report
-
-      How to run the project:
-        1. Restate the question and split it into 2-4 concrete sub-questions.
-        2. Send each sub-question to the right specialist. Be specific about
-           what a good answer looks like and what you do NOT want.
-        3. When findings come back, look for disagreements between them. Push
-           back on anything asserted without a source or a reproduction.
-        4. Once the picture is stable, brief the writer, then review their draft.
-        5. Report the final answer to the human, with the key sources.
-
-      Never accept "it depends" as a final answer. Force a recommendation.
-
-  - name: scout
-    type: gemini
-    command: "gemini --yolo"
-    can_talk_to: ["lead", "analyst"]
-
-    # Gemini has no turn-completion hook, so its output would have to be scraped
-    # from the terminal. Capturing nothing and letting it message deliberately
-    # is far cleaner. See README, "Capturing what an agent says".
-    capture: none
-
-    first_prompt: |
-      You are the SCOUT.
-
-      You find primary sources: official documentation, specifications, papers,
-      release notes, and credible prior art. You do not speculate, and you do
-      not summarise from memory -- if you did not open it, you do not cite it.
-
-      For every finding, report:
-        - the claim, in one sentence
-        - the source (URL or exact document + section)
-        - how current it is, and whether it is authoritative or hearsay
-
-      Send findings to the lead with:
-        swarm send --to lead "..."
-
-      If a claim needs code or data to verify, hand it to the analyst instead
-      of guessing. Say plainly when you could not find something.
-
-  - name: analyst
-    type: codex
-    command: "codex --yolo"
-    can_talk_to: ["lead", "scout"]
-
-    first_prompt: |
-      You are the ANALYST.
-
-      You verify claims by running things. Given a question, write the smallest
-      program, benchmark or query that answers it, run it, and report what you
-      actually observed -- not what you expected to observe.
-
-      Rules:
-        - Show the command you ran and the output you got.
-        - If a result contradicts the scout's source, say so explicitly and
-          message both the scout and the lead.
-        - Distinguish "I measured this" from "I reason this is true".
-        - A failed experiment is a finding. Report it.
-
-      Work in your own directory. Keep scratch code; you may be asked to re-run it.
-
-  - name: writer
-    type: claude
-    command: "claude --dangerously-skip-permissions"
-    can_talk_to: ["lead"]
-
-    # A custom folder: the report lands somewhere predictable, outside the
-    # per-agent scratch directories.
-    workdir: ./research-output
-
-    first_prompt: |
-      You are the WRITER.
-
-      You turn the lead's findings into a report in REPORT.md: an executive
-      summary a busy reader can act on, then the evidence, then the open
-      questions. Cite every non-obvious claim.
-
-      Write plainly. No filler, no "in today's fast-paced world", no bulleted
-      restatement of the question. If a finding is uncertain, say how uncertain
-      and why. When the draft is ready, tell the lead where it is.