orchestra-agents 1.0.0 → 1.0.1

package/README.md

@@ -1,11 +1,24 @@
 # Orchestra
 
+[![npm](https://img.shields.io/npm/v/orchestra-agents)](https://www.npmjs.com/package/orchestra-agents)
+[![license](https://img.shields.io/npm/l/orchestra-agents)](./LICENSE)
+[![node](https://img.shields.io/node/v/orchestra-agents)](https://nodejs.org)
+
 A multi-agent system in one file. One conductor agent takes your goal, breaks it into independent tasks, fans out specialist sub-agents in parallel (scouts, analysts, writers), sends adversarial critics to attack their work, then synthesizes everything into one final deliverable.
 
+**Runs on your Claude subscription. No API credits required.**
+
 Built on the Claude API (`@anthropic-ai/sdk`). No framework. This is the "main agent talks to a bunch of sub-agents" pattern, owned end to end in plain JavaScript you can read in one sitting.
 
 ## Install
 
+```
+npm install -g orchestra-agents
+orchestra "your goal here"
+```
+
+Or clone it and read the source (it's three small files):
+
 ```
 git clone https://github.com/vyn-store/orchestra-agents.git
 cd orchestra-agents
@@ -31,6 +44,42 @@ node orchestra.mjs "quick test" --cheap        # haiku everywhere, costs pennies
 | `--worker M` | sub-agent model (default: same as --model) |
 | `--no-critics` | skip the adversarial pass |
 
+## What a run looks like
+
+A real run, on a Claude subscription, costing nothing in API credits:
+
+```
+$ orchestra-max "name 3 colours that work well together" --agents 2 --cheap
+
+ORCHESTRA MAX  subscription-powered · conductor=haiku workers=haiku max-agents=2
+[goal] name 3 colours that work well together
+[conductor] planning...
+[conductor] strategy: Decompose into research, evaluation, and presentation tasks to
+            identify three visually distinct, complementary colors.
+[conductor] casting 2 sub-agents
+[agent 1] scout: Research popular, distinct colors
+[agent 2] analyst: Evaluate color harmony and contrast
+[agent 1] Research popular, distinct colors done
+[agent 2] Evaluate color harmony and contrast done
+[critic 1] score 8/10
+[critic 2] score 7/10
+[conductor] synthesizing final deliverable...
+
+------------------------------------------------------------
+### 1. Navy Blue + Warm Gold + Cream White
+Why it works: complementary pair (navy and gold sit opposite on the colour wheel).
+High contrast but sophisticated, the cream softens the intensity.
+...
+------------------------------------------------------------
+
+DONE  6 agent calls · 283,593 in / 7,582 out tokens
+      $0.00 API credits (nominal value $0.27, covered by your subscription)
+saved: runs/2026-07-13T14-16-35_name-3-colours-that-work-well-together.md
+```
+
+Both agents ran at the same time, not one after the other. Swap the goal for something
+real ("research what my competitors charge and write my pricing page") and cast more agents.
+
 ## How it works (the 4 phases)
 
 1. **PLAN**: the conductor gets the goal and returns a structured JSON plan (enforced by the API's structured outputs, so it can never come back malformed): a strategy plus one self-contained prompt per sub-agent.

package/orchestra-max.mjs

@@ -20,14 +20,34 @@
 // (an ANTHROPIC_API_KEY in the environment is deliberately stripped so runs
 // can never silently bill your credit balance).
 
-import { execFile } from "node:child_process";
+import { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-import { promisify } from "node:util";
 import { fileURLToPath } from "node:url";
 import { ROLES } from "./roles.mjs";
 
-const run = promisify(execFile);
+// Spawn with stdin closed. `claude -p` waits ~3s for piped stdin and warns if it
+// never arrives, which stalls (and can fail) every agent when Orchestra runs
+// without a TTY: cron, CI, or with its output piped anywhere.
+function run(cmd, args, { cwd, env, maxBuffer = 32 * 1024 * 1024, timeout = 15 * 60 * 1000 } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "", stderr = "", settled = false;
+    const finish = (fn, arg) => { if (!settled) { settled = true; clearTimeout(timer); fn(arg); } };
+    const timer = setTimeout(() => { child.kill("SIGKILL"); finish(reject, Object.assign(new Error(`timed out after ${timeout}ms`), { stdout, stderr })); }, timeout);
+
+    child.stdout.on("data", (d) => {
+      stdout += d;
+      if (stdout.length > maxBuffer) { child.kill("SIGKILL"); finish(reject, Object.assign(new Error("stdout exceeded maxBuffer"), { stdout, stderr })); }
+    });
+    child.stderr.on("data", (d) => { stderr += d; });
+    child.on("error", (e) => finish(reject, Object.assign(e, { stdout, stderr })));
+    child.on("close", (code) => {
+      if (code === 0) finish(resolve, { stdout, stderr });
+      else finish(reject, Object.assign(new Error(`${cmd} exited with code ${code}`), { stdout, stderr }));
+    });
+  });
+}
 const DIR = path.dirname(fileURLToPath(import.meta.url));
 const AGENT_HOME = path.join(DIR, "agent-home"); // empty cwd so agents don't inherit a project CLAUDE.md
 fs.mkdirSync(AGENT_HOME, { recursive: true });
@@ -173,7 +193,9 @@ log("green", "conductor", `casting ${p.tasks.length} sub-agents`);
 
 const slug = GOAL.toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, 50).replace(/^-|-$/g, "");
 const stamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
-const runFile = path.join(DIR, "runs", `${stamp}_${slug}.md`);
+const RUNS_DIR = path.join(DIR, "runs");
+fs.mkdirSync(RUNS_DIR, { recursive: true }); // not shipped in the package: a fresh install has no runs/
+const runFile = path.join(RUNS_DIR, `${stamp}_${slug}.md`);
 let ok = [];
 let final = null;
 let runError = null;

package/orchestra.mjs

@@ -228,7 +228,9 @@ log("green", "conductor", `casting ${p.tasks.length} sub-agents`);
 // (rate limit, empty credit balance, network drop) never loses paid-for work.
 const slug = GOAL.toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, 50).replace(/^-|-$/g, "");
 const stamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
-const runFile = path.join(DIR, "runs", `${stamp}_${slug}.md`);
+const RUNS_DIR = path.join(DIR, "runs");
+fs.mkdirSync(RUNS_DIR, { recursive: true }); // not shipped in the package: a fresh install has no runs/
+const runFile = path.join(RUNS_DIR, `${stamp}_${slug}.md`);
 let ok = [];
 let final = null;
 let runError = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orchestra-agents",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Multi-agent orchestrator on the Claude API: one conductor plans, sub-agents execute in parallel, adversarial critics attack, the conductor synthesizes one deliverable.",
   "type": "module",
   "bin": {