agentainer 0.1.0

package/agents.example.yaml

@@ -0,0 +1,257 @@
+# =============================================================================
+# AgentSwarm example configuration
+#
+#   cp agents.example.yaml agents.yaml
+#   ./swarm.sh validate --show-prompts     # check it without launching anything
+#   ./swarm.sh up                          # launch the swarm
+#
+# Every key is documented inline. Anything marked (optional) can be omitted.
+# =============================================================================
+
+swarm:
+  name: dev-swarm
+
+  # Where agent working directories are created. One folder per agent, named
+  # after the agent. Relative paths resolve against this file's directory.
+  root: ./workspace
+
+  # (optional) Create missing agent folders automatically. Default true.
+  # Set to false to point agents at directories that must already exist, so a
+  # typo in a path fails loudly instead of silently creating an empty folder.
+  create_workdirs: true
+
+  # (optional) Prefix for tmux session names. With `swarm-`, the agent named
+  # `developer` lives in the tmux session `swarm-developer`.
+  session_prefix: ""
+
+  # (optional) Timing knobs, all in milliseconds.
+  send_delay_ms: 150      # pause before pasting text into a pane
+  enter_delay_ms: 250     # pause between pasting text and pressing Enter
+  max_forward_hops: 3     # stops auto-forward loops (A -> B -> A -> ...)
+
+  # (optional) How long to keep probing an agent's input box for a response
+  # before giving up and typing the first prompt anyway. Some CLIs (Claude Code)
+  # silently discard keystrokes for several seconds partway through startup, so
+  # AgentSwarm waits for the input box to echo a throwaway token before typing.
+  ready_timeout_ms: 60000
+
+  # (optional) An agent is "busy" from when a message is submitted to it until its
+  # next captured turn end; senders are refused meanwhile and told to --queue or
+  # --wait. If a capture never fires (crashed CLI, bad hook) the agent would look
+  # busy forever, so after this long it is treated as idle again, with a warning.
+  busy_timeout_ms: 900000
+
+  # (optional) How messages look on the wire.
+  #   tagged -- messages arrive inside <swarm-message from=".." id=".."> ... </swarm-message>,
+  #             and an agent sends one by writing <swarm-send to="..."> ... </swarm-send>
+  #             in its reply. No shell quoting, so multi-line bodies survive intact.
+  #   plain  -- the older "[swarm] message from <sender>:" header.
+  message_format: tagged
+
+  # (optional) An agent that answers a question as plain prose sends nothing: only a
+  # <swarm-send> block is delivered. When it owes a reply and its turn ends without
+  # one, AgentSwarm messages it explaining how to send. This is how many times.
+  max_reply_reminders: 1
+
+  # (optional) Reattach agents to their previous conversations on `up`, using the ids
+  # recorded in <root>/.swarm/sessions.yaml. Same as passing `up --resume` every time.
+  # Useful after a reboot. `up --no-resume` overrides it.
+  resume: false
+
+  # (optional) Only used by agents with `capture: pane` (gemini, hermes).
+  pane_idle_ms: 2500      # pane must be unchanged this long to count as "done"
+  pane_poll_ms: 700       # how often the watcher samples the pane
+  pane_scrollback: 400    # lines of scrollback to diff
+
+  # (optional) tmux comfort settings for when you `swarm attach <agent>`.
+  # The default tmux scrollback (2000 lines) is too small to hold a long
+  # multi-agent conversation, so AgentSwarm raises it before creating sessions.
+  # mouse mode lets you wheel-scroll the backlog; press q to leave copy mode.
+  # Both are applied to the tmux server, so they also affect your other sessions.
+  tmux_history_limit: 50000   # lines of scrollback per agent pane (0 = leave tmux's default)
+  tmux_mouse: true            # enable mouse wheel scrolling in the panes
+
+# -----------------------------------------------------------------------------
+# defaults (optional) -- applied to every agent that does not override them.
+# -----------------------------------------------------------------------------
+defaults:
+  type: claude
+  append_agents_that_you_can_talk_to_prompt: true
+  in_first_prompt_append_your_task_will_be_sent_in_the_next_prompt: false
+  env:
+    SWARM_DEMO: "1"
+
+# -----------------------------------------------------------------------------
+# agent_types (optional) -- override the built-in launch commands, or define
+# entirely new agent types. Built-ins are: claude, codex, gemini, hermes.
+#
+#   capture: how AgentSwarm learns that an agent finished a turn.
+#     hook -- the CLI can run an external program on turn completion.
+#             Supported for claude (Stop hook) and codex (notify program).
+#     pane -- no such facility: poll the tmux pane and diff it. Heuristic.
+#     none -- do not capture at all.
+#
+#   boot_delay_ms: a grace period before AgentSwarm starts probing the input
+#     box. It does NOT need to cover the full startup time -- delivery of the
+#     first prompt is verified and retried, so a small value is fine.
+# -----------------------------------------------------------------------------
+agent_types:
+  claude:
+    command: "claude --dangerously-skip-permissions"
+    capture: hook
+    boot_delay_ms: 3000
+  codex:
+    command: "codex --yolo"
+    capture: hook
+    boot_delay_ms: 3000
+  gemini:
+    command: "gemini --yolo"
+    capture: pane
+    boot_delay_ms: 4000
+  hermes:
+    command: "hermes"
+    capture: pane
+    boot_delay_ms: 3000
+
+# -----------------------------------------------------------------------------
+# agents -- one tmux session and one directory each.
+# -----------------------------------------------------------------------------
+agents:
+
+  - name: orchestrator
+    type: claude
+    # (optional) Override the type's command, e.g. to pin a model.
+    command: "claude --dangerously-skip-permissions --model opus"
+
+    # Who this agent is allowed to message. Use "*" for "everyone else".
+    # An agent that tries to message anyone not listed here is refused.
+    can_talk_to: ["researcher", "developer", "reviewer"]
+
+    first_prompt: |
+      You are the ORCHESTRATOR of a small software team.
+
+      Your job is to break the user's goal into concrete pieces of work, hand
+      each piece to the right specialist, and assemble their answers into a
+      final result. You do not write production code yourself.
+
+      Team:
+        - researcher: investigates prior art, APIs and docs
+        - developer:  writes the implementation
+        - reviewer:   critiques diffs and finds bugs
+
+      Start by asking the researcher what they can find, then brief the developer.
+
+    # This agent is told its task arrives in a follow-up prompt, so it will
+    # acknowledge and wait rather than inventing work.
+    in_first_prompt_append_your_task_will_be_sent_in_the_next_prompt: true
+
+  - name: researcher
+    type: gemini
+    command: "gemini --yolo"
+    can_talk_to: ["orchestrator", "developer"]
+
+    # Whenever this agent finishes a turn, its final message is automatically
+    # relayed to these agents. Every name here must also be in can_talk_to.
+    # Leave it out (the default) to let the agent decide when to speak.
+    forward_responses_to: ["orchestrator"]
+
+    first_prompt: |
+      You are the RESEARCHER. You investigate libraries, APIs, prior art and
+      documentation, then report findings concisely with sources.
+
+      You never write production code. When you have an answer, state it plainly:
+      what exists, what it costs, and what you recommend.
+
+  - name: developer
+    type: codex
+    command: "codex --yolo"
+    can_talk_to: ["orchestrator", "reviewer"]
+
+    # (optional) Per-agent environment variables, exported into its tmux session.
+    env:
+      GIT_AUTHOR_NAME: "swarm-developer"
+
+    # (optional) Before typing the first prompt, type a throwaway token and wait
+    # for the input box to echo it back. Defaults to true; turn it off only for
+    # a command that is not an interactive TUI.
+    ready_probe: true
+
+    # (optional) Refuse incoming messages while this agent is mid-turn, so a second
+    # agent is told "developer is busy, --queue it or --wait" instead of interrupting.
+    # Needs a capture to know when a turn ends; forced off when capture: none.
+    busy_check: true
+
+    # (optional) Read <swarm-send> blocks out of this agent's replies and deliver
+    # them. Needs a capture; forced off when capture: none or message_format: plain.
+    parse_outbound_tags: true
+
+    # (optional) Nudge this agent when it owes a reply but sent nothing, or when the
+    # block it wrote could not be delivered. Off when its tags are not parsed.
+    reply_reminder: true
+
+    # (optional) How to reattach this agent to a previous conversation. `resume_args`
+    # is appended to `command`; `resume_command` replaces it outright, which you need
+    # when the command goes through an alias or wrapper. {session_id} is substituted.
+    #
+    # resume_args: "resume {session_id}"                       # -> codex --yolo resume <id>
+    # resume_command: "bash -ic 'mywrapper --resume {session_id}'"
+
+    first_prompt: |
+      You are the DEVELOPER. You implement what the orchestrator asks for, in
+      the working directory you were started in.
+
+      Write real, runnable code. When you finish a unit of work, send the
+      reviewer a short summary of what you changed and why, and ask for review.
+
+  - name: reviewer
+    type: claude
+    command: "claude --dangerously-skip-permissions"
+    can_talk_to: ["developer", "orchestrator"]
+
+    # (optional) Run this agent somewhere specific instead of <root>/<name>.
+    # Relative paths resolve against this file. `~` is expanded. The
+    # placeholders {name}, {root}, {swarm} and {type} are substituted, so a
+    # single `defaults.workdir` can serve every agent, e.g. "{root}/{name}-wt".
+    #
+    # Several agents may share one directory (they then see each other's edits;
+    # AgentSwarm warns you). Pair `create_workdir: false` with an existing
+    # project so a bad path is an error, not a new empty folder.
+    #
+    # workdir: ~/projects/acme-api
+    # create_workdir: false
+
+    # (optional) Read the prompt from a file instead of inlining it here.
+    # first_prompt_file: ./prompts/reviewer.md
+    first_prompt: |
+      You are the REVIEWER. You read the developer's changes and hunt for real
+      bugs: wrong logic, unhandled errors, race conditions, security problems.
+
+      Be specific and cite file:line. If a change is fine, say so briefly rather
+      than inventing nitpicks. Report your verdict back to the developer.
+
+  - name: scribe
+    type: hermes
+    command: "hermes"
+
+    # This agent listens only: nobody can be messaged by it, and its own
+    # responses are not captured.
+    can_talk_to: []
+    capture: none
+
+    # Turn off the auto-appended communication block, since it has no peers.
+    append_agents_that_you_can_talk_to_prompt: false
+
+    first_prompt: |
+      You are the SCRIBE. Keep a running changelog of the project in NOTES.md.
+
+# -----------------------------------------------------------------------------
+# templates (optional) -- override the text AgentSwarm appends to first prompts.
+# Available placeholders: {agent} {swarm} {peers} {prefix} {inbox} {workdir}
+# -----------------------------------------------------------------------------
+#
+# templates:
+#   comms: |
+#     You are {agent}. You may message: {peers}.
+#     Send with: swarm send --to <agent> "message"
+#   task_notice: |
+#     Stand by. Your real task arrives in the next message.

package/bin/agentainer.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// Agentainer -- global CLI launcher.
+//
+// npm symlinks this file into a bin directory (e.g. /usr/local/bin/agentainer).
+// Node resolves that symlink before setting __dirname, so __dirname always
+// points at the real bin/ inside the installed package -- which makes the
+// package root, and therefore SWARM_HOME, reliable no matter where npm puts us.
+"use strict";
+
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const PKG_ROOT = path.resolve(__dirname, "..");
+const ENTRY = path.join(PKG_ROOT, "lib", "swarm.py");
+
+// `agentainer doctor` re-runs the dependency check without touching Python.
+if (process.argv[2] === "doctor") {
+  const r = spawnSync(process.execPath, [path.join(PKG_ROOT, "scripts", "check-deps.js")], {
+    stdio: "inherit",
+  });
+  process.exit(r.status === null ? 1 : r.status);
+}
+
+// Locate a Python interpreter, mirroring swarm.sh (SWARM_PYTHON, then python3,
+// then python).
+function findPython() {
+  const candidates = process.env.SWARM_PYTHON
+    ? [process.env.SWARM_PYTHON]
+    : ["python3", "python"];
+  for (const cand of candidates) {
+    const probe = spawnSync(cand, ["--version"], { stdio: "ignore" });
+    if (!probe.error && probe.status === 0) return cand;
+  }
+  return null;
+}
+
+function has(cmd, args) {
+  const probe = spawnSync(cmd, args, { stdio: "ignore" });
+  return !probe.error && probe.status === 0;
+}
+
+const python = findPython();
+if (!python) {
+  process.stderr.write(
+    "xx Agentainer needs python3 on PATH (or set SWARM_PYTHON).\n" +
+      "   Run `agentainer doctor` for install hints.\n"
+  );
+  process.exit(1);
+}
+
+// tmux is required for everything except `validate`; warn but don't block, so
+// `agentainer validate` and `agentainer doctor` still work without it.
+if (!has("tmux", ["-V"])) {
+  process.stderr.write(
+    "!! tmux was not found on PATH; every command except 'validate' will fail.\n" +
+      "   Run `agentainer doctor` for install hints.\n"
+  );
+}
+
+const result = spawnSync(python, [ENTRY, ...process.argv.slice(2)], {
+  stdio: "inherit",
+  env: { ...process.env, SWARM_HOME: PKG_ROOT },
+});
+
+if (result.error) {
+  process.stderr.write(`xx failed to launch Agentainer: ${result.error.message}\n`);
+  process.exit(1);
+}
+if (result.signal) {
+  // Re-raise the signal so the parent shell sees the real cause (e.g. Ctrl-C).
+  process.kill(process.pid, result.signal);
+  process.exit(1);
+}
+process.exit(result.status === null ? 1 : result.status);

package/examples/bug-hunt.yaml

@@ -0,0 +1,112 @@
+# =============================================================================
+# Bug hunt -- an automatic pipeline: reproduce -> diagnose -> fix -> verify.
+#
+#   ./swarm.sh up -c examples/bug-hunt.yaml
+#   ./swarm.sh send --to reproducer "Uploads over 2MB fail with a 500 in prod."
+#
+# This is the one shape where `forward_responses_to` earns its keep: each stage
+# hands its finished turn to the next stage automatically, with no human in the
+# loop. Everything flows one way, so the hop guard never has to save you.
+#
+#   reproducer --> diagnoser --> fixer --> verifier
+#
+# Auto-forwarding is chatty by nature. If you want agents to speak only when
+# they have something to say, delete `forward_responses_to` and let them call
+# `swarm send` themselves.
+# =============================================================================
+
+swarm:
+  name: bughunt
+  root: ./bughunt
+  session_prefix: "bug-"
+
+  # A straight line needs exactly as many hops as it has stages.
+  max_forward_hops: 4
+
+agents:
+
+  - name: reproducer
+    type: codex
+    command: "codex --yolo"
+    can_talk_to: ["diagnoser"]
+    forward_responses_to: ["diagnoser"]
+
+    first_prompt: |
+      You are the REPRODUCER, the first stage of a bug-hunting pipeline.
+
+      Given a bug report, your only job is to turn it into a deterministic,
+      minimal reproduction: a script or test that fails now and would pass if
+      the bug were fixed.
+
+      Report, in this order:
+        1. The exact command to reproduce.
+        2. The observed output, verbatim.
+        3. The expected output.
+        4. What you had to assume, because the report did not say.
+
+      If you cannot reproduce it, say so and explain precisely what you tried.
+      Do not attempt a fix -- the next stage does that. Everything you say at
+      the end of your turn is forwarded automatically to the diagnoser.
+
+  - name: diagnoser
+    type: claude
+    command: "claude --dangerously-skip-permissions --model opus"
+    can_talk_to: ["fixer"]
+    forward_responses_to: ["fixer"]
+
+    first_prompt: |
+      You are the DIAGNOSER, the second stage of a bug-hunting pipeline.
+
+      You receive a reproduction. Find the root cause -- the specific line or
+      design decision that makes the failure inevitable. Not the symptom, and
+      not the first suspicious thing you see.
+
+      Report:
+        1. Root cause, at file:line, in one paragraph.
+        2. The causal chain from input to wrong output.
+        3. Why it was not caught: the missing test, the wrong assumption.
+        4. The smallest correct fix, and one alternative you rejected (say why).
+
+      Do not write the fix. Describe it. Your turn is forwarded to the fixer.
+
+  - name: fixer
+    type: codex
+    command: "codex --yolo"
+    can_talk_to: ["verifier"]
+    forward_responses_to: ["verifier"]
+
+    first_prompt: |
+      You are the FIXER, the third stage of a bug-hunting pipeline.
+
+      You receive a diagnosis. Implement the smallest change that fixes the root
+      cause, plus a regression test that fails without your change and passes
+      with it.
+
+      Do not refactor surrounding code, rename things, or fix unrelated bugs you
+      notice on the way. Mention them instead.
+
+      Report the diff you made, the test you added, and the test output. Your
+      turn is forwarded to the verifier, who does not trust you.
+
+  - name: verifier
+    type: claude
+    command: "claude --dangerously-skip-permissions"
+
+    # End of the line: it forwards to nobody, so the pipeline stops here.
+    can_talk_to: []
+    append_agents_that_you_can_talk_to_prompt: false
+
+    first_prompt: |
+      You are the VERIFIER, the last stage of a bug-hunting pipeline.
+
+      You receive a proposed fix. Assume it is wrong until you have checked.
+
+      Do all of these:
+        1. Run the original reproduction. Does it now pass?
+        2. Run the whole test suite. Did anything else break?
+        3. Read the fix. Does it address the root cause, or only the symptom
+           that the reproduction happened to exercise?
+        4. Find one input near the boundary of the change that would still
+           break. If you find one, the fix is not done.
+
+      Print a verdict: SHIPPABLE or NOT SHIPPABLE, then the evidence. Be blunt.

package/examples/existing-repo.yaml

@@ -0,0 +1,72 @@
+# =============================================================================
+# 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.
+#
+#   1. Point `workdir` below at a real repository.
+#   2. ./swarm.sh validate -c examples/existing-repo.yaml
+#   3. ./swarm.sh up       -c examples/existing-repo.yaml
+#   4. ./swarm.sh 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/research-swarm.yaml

@@ -0,0 +1,120 @@
+# =============================================================================
+# Research swarm -- a small team that investigates a topic and writes it up.
+#
+#   ./swarm.sh up -c examples/research-swarm.yaml
+#   ./swarm.sh 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.
+# =============================================================================
+
+swarm:
+  name: research
+  root: ./research-workspace
+  session_prefix: "r-"
+
+defaults:
+  type: claude
+
+agents:
+
+  - name: lead
+    type: claude
+    command: "bash -ic 'chy3'"
+    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: claude
+    command: "bash -ic 'chy3'"
+    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: claude
+    command: "bash -ic 'chy3'"
+    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: "bash -ic 'chy3'"
+    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.