@gredescerber/agent-crew 0.0.0-stage → 0.5.0

package/src/commands/worker.js

@@ -0,0 +1,322 @@
+// crew worker — the agent runs the task loop on its own, without a UI.
+// task next → task claim → headless agent in the task worktree → check the issue status → next task.
+// A new agent process per task = a context reset at the phase boundary.
+// Started by a human (agent: false): the agent does not need to be able to spawn other agents via MCP.
+import { spawn as nodeSpawn } from 'node:child_process';
+import { createWriteStream, mkdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { ok, warn, fail, CrewError } from '../core/output.js';
+import { run as exec } from '../core/exec.js';
+import { killTree } from '../core/proc.js';
+import { recordCommand } from '../core/metrics.js';
+import { loadConfig, machineName } from '../core/config.js';
+import { viewIssue, labelValue, TIERS } from '../core/issues.js';
+import { loadAdapter } from './adapters.js';
+import taskCommands from './task.js';
+
+const WAIT_MS = 5 * 60_000;
+const SUCCESS = ['review', 'done'];
+const HANDOFF = ['blocked', 'needs-spec'];
+
+/**
+ * Prompt for a single task. One line, without the characters " & | < > ^ % —
+ * on Windows the argument goes through cmd /c, where a newline and these characters break the command.
+ */
+export function taskPrompt({ id, branch }) {
+  return [
+    `You are an agent of a crew team. Task issue #${id} is already claimed by you: status claimed, branch ${branch ?? `crew/${id}-...`}, the current folder is its worktree.`,
+    `Work only on issue #${id} and only in this folder, strictly following the crew-workflow skill, starting with the Understand step: gh issue view ${id}.`,
+    'Do not call crew task next or crew task claim — the worker will hand out the next task.',
+    `For long work, run crew task heartbeat ${id} about every 30 minutes.`,
+    `Finish with exactly one of: crew pr open — the task goes to review; crew task status ${id} blocked --note with a description; crew task status ${id} needs-spec --note with a question.`,
+    'Then end your work.',
+  ].join(' ');
+}
+
+/** Call a crew command as a function: CrewError → a crew/v1 result, not an exception. */
+async function call(fn, opts) {
+  try {
+    return await fn(opts);
+  } catch (e) {
+    return e instanceof CrewError ? e.toResult() : fail('internal', e.message, { stop_when: 'it keeps happening — tell the human' });
+  }
+}
+
+const fmtDuration = (ms) => {
+  const s = Math.round(ms / 1000);
+  return s >= 60 ? `${Math.floor(s / 60)}m ${s % 60}s` : `${s}s`;
+};
+
+
+/** Run the agent: stdout/stderr → log file, prompt → stdin, killed on timeout. */
+export function spawnAgent(spec, { cwd, env, timeoutMs, logFile }) {
+  return new Promise((done) => {
+    let out = 'ignore';
+    if (logFile) {
+      mkdirSync(dirname(logFile), { recursive: true });
+      out = createWriteStream(logFile);
+    }
+    let child;
+    try {
+      child = nodeSpawn(spec.cmd, spec.args, {
+        cwd,
+        env: { ...process.env, ...env },
+        stdio: [spec.input != null ? 'pipe' : 'ignore', 'pipe', 'pipe'],
+        shell: false,
+        windowsHide: true,
+        detached: process.platform !== 'win32', // own process group → the whole tree can be killed
+      });
+    } catch (e) {
+      done({ code: -1, timedOut: false, error: e.message });
+      return;
+    }
+    if (out !== 'ignore') { child.stdout.pipe(out, { end: false }); child.stderr.pipe(out, { end: false }); }
+    else { child.stdout.resume(); child.stderr.resume(); }
+    if (spec.input != null) child.stdin.end(spec.input);
+    let timedOut = false;
+    const timer = setTimeout(() => { timedOut = true; killTree(child); }, timeoutMs);
+    let settled = false;
+    const finish = (r) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (out !== 'ignore') out.end();
+      done(r);
+    };
+    child.on('error', (e) => finish({ code: -1, timedOut, error: e.message }));
+    child.on('close', (code, signal) => finish({ code: code ?? -1, signal, timedOut }));
+  });
+}
+
+/**
+ * A crew command as a function + recording the event in .crew/metrics.jsonl (as in the CLI and MCP).
+ * Without this, the worker claim/release are invisible in crew metrics and the completion rate of worker agents is wrong.
+ */
+export function recorded(cmd) {
+  return async (o) => {
+    const started = Date.now();
+    try {
+      const result = await cmd.run(o);
+      recordCommand({ command: cmd.name, opts: o, result, started });
+      return result;
+    } catch (e) {
+      const result = e instanceof CrewError ? e.toResult() : fail('internal', e.message);
+      recordCommand({ command: cmd.name, opts: o, result, started });
+      throw e;
+    }
+  };
+}
+
+function defaultDeps() {
+  const byName = Object.fromEntries(taskCommands.map((c) => [c.name, c]));
+  return {
+    next: recorded(byName['task next']),
+    claim: recorded(byName['task claim']),
+    release: recorded(byName['task release']),
+    viewIssue,
+    spawn: spawnAgent,
+    adapters: { load: loadAdapter },
+    loadConfig,
+    gitCommonDir: (cwd) => {
+      const r = exec('git', ['rev-parse', '--git-common-dir'], { cwd, allowFail: true });
+      return r.code === 0 && r.stdout ? resolve(cwd, r.stdout) : null;
+    },
+    sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+    log: (line) => process.stderr.write(`[crew worker] ${line}\n`),
+    now: () => Date.now(),
+  };
+}
+
+async function getAdapter(adapters, host) {
+  if (!adapters) return null;
+  if (typeof adapters.load === 'function') return adapters.load(host);
+  return adapters[host] ?? null;
+}
+
+/** The worker loop. deps are stubbed in tests: { next, claim, release, viewIssue, spawn, adapters, ... }. */
+export async function runWorker(opts, deps = {}) {
+  const d = { ...defaultDeps(), ...deps };
+  const {
+    host, area, tier = 'high', dry_run, wait,
+    max_tasks = 5, max_failures = 3, task_timeout_min = 60,
+  } = opts;
+
+  const adapter = await getAdapter(d.adapters, host);
+  if (!adapter?.headless) {
+    return fail('unknown_host', `No adapter with headless() for: ${host}`, {
+      cause_hint: 'adapters live in adapters/<host>/adapter.js',
+      retry: 'crew worker --host codex  (or claude)',
+      stop_when: 'the required host is not among the adapters',
+    });
+  }
+  const { config, root } = d.loadConfig();
+  const model = opts.model || config.tiers?.[tier]?.[host] || undefined;
+  const agent = `${host}/${model || 'default'}`;
+
+  const done = [];
+  const failed = [];
+  const handed = [];
+  let failStreak = 0;
+  let conflicts = 0;
+  let stopped_reason = null;
+  let started = 0;
+
+  const prevAgent = process.env.CREW_AGENT;
+  const prevAgentId = process.env.CREW_AGENT_ID;
+  process.env.CREW_AGENT = agent; // the worker claim/release run as the same agent as the child process
+  // Unique id: two workers of the same model on one machine are different agents (lease, review).
+  const agentUid = `${agent}@${machineName()}-w${process.pid}`;
+  process.env.CREW_AGENT_ID = agentUid;
+  const result = (extra = {}) => ({ done, failed, blocked: handed, stopped_reason, agent, ...extra });
+
+  try {
+    while (started < max_tasks) {
+      const nx = await call(d.next, { area, tier, tasks_only: true });
+      if (nx.status === 'error') {
+        if (nx.error?.code === 'paused') { stopped_reason = 'paused'; break; }
+        return fail(nx.error?.code ?? 'next_failed', `Worker stopped: ${nx.summary}`, {
+          ...(nx.error ?? {}),
+          artifacts: result({ stopped_reason: 'next_failed' }),
+        });
+      }
+      if (nx.status === 'warning' || !nx.artifacts?.issue) {
+        if (wait) {
+          d.log(`queue is empty, waiting ${WAIT_MS / 60_000} min`);
+          await d.sleep(WAIT_MS);
+          continue;
+        }
+        stopped_reason = 'no_tasks';
+        break;
+      }
+      const id = nx.artifacts.issue;
+
+      if (dry_run) {
+        const spec = adapter.headless({ prompt: taskPrompt({ id }), model, cwd: '<worktree>', writableDirs: [] });
+        return ok(`Dry run: would take #${id} and start ${host}`, {
+          artifacts: { issue: id, agent, command: [spec.cmd, ...spec.args].join(' '), prompt: taskPrompt({ id }) },
+          next_actions: [`crew worker --host ${host}${area ? ` --area ${area}` : ''} — run for real`],
+        });
+      }
+
+      const cl = await call(d.claim, { id });
+      if (cl.status === 'error') {
+        const code = cl.error?.code;
+        if (code === 'paused') { stopped_reason = 'paused'; break; }
+        if (code === 'claim_conflict' || code === 'not_ready') {
+          if (++conflicts >= 3) { stopped_reason = 'claim_conflicts'; break; }
+          d.log(`#${id}: ${cl.summary} — taking the next one`);
+          continue;
+        }
+        if (code === 'workspace_failed') {
+          // the claim has already been rolled back (the task is ready again) — we count it as a failure and do not stop the worker.
+          failed.push(id);
+          failStreak++;
+          d.log(`#${id}: ✖ ${cl.summary}, failures in a row: ${failStreak}/${max_failures}`);
+          if (failStreak >= max_failures) { stopped_reason = 'max_failures'; break; }
+          continue;
+        }
+        return fail(code ?? 'claim_failed', `Worker stopped: ${cl.summary}`, {
+          ...(cl.error ?? {}),
+          artifacts: result({ stopped_reason: 'claim_failed', issue: id }),
+        });
+      }
+      conflicts = 0;
+      started++;
+      const worktree = cl.artifacts?.worktree ?? root;
+      const commonDir = d.gitCommonDir?.(worktree);
+      const spec = adapter.headless({
+        prompt: taskPrompt({ id, branch: cl.artifacts?.branch }),
+        model,
+        cwd: worktree,
+        writableDirs: commonDir ? [commonDir] : [],
+      });
+      const logFile = join(root, '.crew', 'logs', `worker-${id}-${new Date().toISOString().replace(/[:.]/g, '-')}.log`);
+      d.log(`#${id}: starting ${agent} in ${worktree}`);
+      const t0 = d.now();
+      const res = await d.spawn(spec, {
+        cwd: worktree,
+        env: { ...spec.env, CREW_AGENT: agent, CREW_AGENT_ID: agentUid },
+        timeoutMs: task_timeout_min * 60_000,
+        logFile,
+      });
+      const took = fmtDuration(d.now() - t0);
+
+      if (res.error) {
+        await call(d.release, { id, note: `crew worker: could not start ${host}: ${res.error}` });
+        failed.push(id);
+        d.log(`#${id}: ✖ agent failed to start (${res.error})`);
+        return fail('tool_missing', `Could not start ${host}: ${res.error}`, {
+          cause_hint: `${spec.cmd} was not found or does not start; task #${id} was returned to the queue`,
+          retry: 'crew doctor',
+          stop_when: `${host} is not installed`,
+          artifacts: result({ stopped_reason: 'spawn_failed' }),
+        });
+      }
+
+      const issue = await call(d.viewIssue, id);
+      const state = issue?.labels ? labelValue(issue, 'status') : null;
+      const closed = issue?.state === 'CLOSED';
+
+      if (closed || SUCCESS.includes(state)) {
+        done.push(id);
+        failStreak = 0;
+        d.log(`#${id}: ✔ ${closed ? 'closed' : state} in ${took}`);
+      } else if (HANDOFF.includes(state)) {
+        handed.push({ issue: id, status: state });
+        failStreak = 0;
+        d.log(`#${id}: ! ${state} in ${took} — handoff to the issue`);
+      } else {
+        const why = res.timedOut ? `timeout ${task_timeout_min} min` : `agent exited with code ${res.code}, status ${state ?? 'unknown'}`;
+        if (state === 'claimed') await call(d.release, { id, note: `crew worker: ${why}. Log: ${logFile}` });
+        failed.push(id);
+        failStreak++;
+        d.log(`#${id}: ✖ ${why} (${took}), failures in a row: ${failStreak}/${max_failures}`);
+        if (failStreak >= max_failures) { stopped_reason = 'max_failures'; break; }
+      }
+    }
+    if (!stopped_reason) stopped_reason = 'max_tasks';
+  } finally {
+    if (prevAgent === undefined) delete process.env.CREW_AGENT;
+    else process.env.CREW_AGENT = prevAgent;
+    if (prevAgentId === undefined) delete process.env.CREW_AGENT_ID;
+    else process.env.CREW_AGENT_ID = prevAgentId;
+  }
+
+  const reasonText = {
+    paused: 'paused (issue crew:pause)',
+    no_tasks: 'queue is empty',
+    max_tasks: `task limit reached (${max_tasks})`,
+    max_failures: `${max_failures} failures in a row`,
+    claim_conflicts: '3 claim conflicts in a row',
+  }[stopped_reason];
+  const summary = `Worker ${agent} stopped: ${reasonText}. Delivered: ${done.length}, failures: ${failed.length}, handoffs: ${handed.length}`;
+  const next_actions = {
+    paused: ['wait until crew:pause is lifted and run crew worker again'],
+    no_tasks: ['crew status — what is blocked', `crew worker --host ${host} --wait — wait for new tasks`],
+    max_tasks: [`crew worker --host ${host} — next batch`],
+    max_failures: ['read the logs in .crew/logs/worker-*.log and the comments on the tasks', 'crew status'],
+    claim_conflicts: ['crew status — who else is claiming tasks', 'tell the human'],
+  }[stopped_reason];
+  const bad = stopped_reason === 'max_failures' || stopped_reason === 'claim_conflicts';
+  return (bad ? warn : ok)(summary, { artifacts: result(), next_actions });
+}
+
+export default {
+  name: 'worker',
+  summary: 'Run an agent (claude/codex) without a UI: it takes tasks one at a time, a new session per task',
+  agent: false,
+  args: [
+    { name: 'host', type: 'string', required: true, description: 'which agent: claude, codex' },
+    { name: 'area', type: 'string', description: 'task area: web, api, ... (empty = any)' },
+    { name: 'tier', type: 'string', enum: TIERS, description: 'model tier (default high); the model comes from crew.config.json → tiers' },
+    { name: 'model', type: 'string', description: 'a specific model (overrides tier)' },
+    { name: 'max_tasks', type: 'number', description: 'maximum number of tasks to take (default 5)' },
+    { name: 'max_failures', type: 'number', description: 'stop after N failures in a row (default 3)' },
+    { name: 'task_timeout_min', type: 'number', description: 'kill the agent after N minutes on a task (default 60)' },
+    { name: 'wait', type: 'boolean', description: 'if the queue is empty — wait for new tasks (polls every 5 min)' },
+    { name: 'dry_run', type: 'boolean', description: 'only show which task it would take and with which command' },
+  ],
+  run(opts) {
+    return runWorker(opts);
+  },
+};

package/src/core/config.js

@@ -0,0 +1,77 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { hostname } from 'node:os';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const HARNESS_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+export const DEFAULT_CONFIG = {
+  // Areas = directories. An agent with --area web only touches web/**.
+  // e2e: acceptance and E2E tests, including tests/pending/** (test tasks for risk:high).
+  areas: {
+    web: ['web/**'],
+    api: ['api/**'],
+    contracts: ['contracts/**'],
+    e2e: ['tests/e2e/**', 'tests/acceptance/**', 'tests/pending/**'],
+    infra: ['infra/**', '.github/**'],
+    // Not code: designer mockups and styles, researcher notes. Styles web/src/styles/** are shared with web.
+    design: ['design/**', 'web/src/styles/**'],
+    research: ['docs/research/**'],
+  },
+  // What `crew check` runs (in order). An empty string or missing entry means the step is skipped.
+  check: [],
+  // Task lease: how many minutes without activity before the task returns to the queue.
+  lease_minutes: 45,
+  // Model tiers -> concrete models per vendor (crew worker passes them to --model). Codex: Sol -> Terra -> Luna.
+  tiers: {
+    high: { claude: 'opus', codex: 'gpt-6.1-sol' },
+    mid: { claude: 'sonnet', codex: 'gpt-6.1-terra' },
+    low: { claude: 'haiku', codex: 'gpt-6-luna' },
+  },
+  hosts: ['claude', 'codex'],
+  // Agent review instead of a human approve button (checked by crew guard / the crew-guard status).
+  // Who reviews first is the review area in the PRD crew-team block (usually the captain); crew task next gives them PRs before tasks.
+  //   require: other-vendor means a reviewer from another vendor; other-agent means any other agent (team with Claude only).
+  //   Default is other-vendor when there is more than one host. If no other-vendor reviewer shows up within fallback_minutes,
+  //   any other agent counts (so PRs do not hang).
+  review: { approvals: 1, approvals_high: 1, fallback_minutes: 30 },
+  event: null, // path to events/<name>.json when a hackathon is running
+};
+
+/** Find crew.config.json walking up from cwd. Returns { config, root } (root = project root). */
+export function loadConfig(cwd = process.cwd()) {
+  let dir = resolve(cwd);
+  for (;;) {
+    const p = join(dir, 'crew.config.json');
+    if (existsSync(p)) {
+      const user = JSON.parse(readFileSync(p, 'utf8'));
+      return { config: { ...DEFAULT_CONFIG, ...user }, root: dir, path: p };
+    }
+    const up = dirname(dir);
+    if (up === dir) return { config: { ...DEFAULT_CONFIG }, root: resolve(cwd), path: null };
+    dir = up;
+  }
+}
+
+export function loadEvent(config, root) {
+  if (!config.event) return null;
+  const p = resolve(root, config.event);
+  return existsSync(p) ? JSON.parse(readFileSync(p, 'utf8')) : null;
+}
+
+/** Short machine name for the agent id: "petya-laptop". */
+export const machineName = () =>
+  (hostname().split('.')[0] || 'host').toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-|-$/g, '').slice(0, 24) || 'host';
+
+/**
+ * Agent id: <vendor>[/<model>]@<machine>, e.g. claude@petya-laptop, codex/gpt-x@masha-pc.
+ * CREW_AGENT sets vendor/model (adapters set it; for all Claude agents it is just "claude"),
+ * the machine is appended automatically, otherwise three Claudes on three laptops would be one agent
+ * (another agent's lease would be taken for your own, and review by "another agent" would be impossible).
+ * For several sessions on one machine, give each its own CREW_AGENT_ID (claude@petya-2).
+ */
+export function agentId(env = process.env) {
+  if (env.CREW_AGENT_ID) return env.CREW_AGENT_ID;
+  const base = env.CREW_AGENT || 'human';
+  return base.includes('@') ? base : `${base}@${machineName()}`;
+}

package/src/core/exec.js

@@ -0,0 +1,50 @@
+import { spawnSync } from 'node:child_process';
+import { CrewError } from './output.js';
+import { runSupervised } from './proc.js';
+
+/** Run an external command without a shell (cross-platform, no injection). */
+export function run(cmd, args = [], { cwd, allowFail = false, input } = {}) {
+  const res = spawnSync(cmd, args, {
+    cwd,
+    input,
+    encoding: 'utf8',
+    shell: false,
+    windowsHide: true,
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  if (res.error) {
+    if (allowFail) return { code: -1, stdout: '', stderr: String(res.error.message) };
+    throw new CrewError('tool_missing', `failed to run ${cmd}`, {
+      cause_hint: res.error.message,
+      retry: 'crew doctor',
+      stop_when: `${cmd} is not installed`,
+    });
+  }
+  const out = { code: res.status ?? -1, stdout: res.stdout?.trim() ?? '', stderr: res.stderr?.trim() ?? '' };
+  if (out.code !== 0 && !allowFail) {
+    throw new CrewError('command_failed', `${cmd} ${args.join(' ')} exited with code ${out.code}`, {
+      cause_hint: out.stderr.split('\n').slice(0, 5).join(' | '),
+      stop_when: 'the error repeats twice',
+    });
+  }
+  return out;
+}
+
+/**
+ * Run a config string (the user's check commands) through the shell.
+ * timeout_s is how many seconds to wait; after that the process is killed (SIGKILL), timedOut: true.
+ * Without a timeout a hung test or dev server blocks the agent forever.
+ */
+export function runShell(line, { cwd, timeout_s } = {}) {
+  const timeoutMs = Number(timeout_s) > 0 ? Math.round(Number(timeout_s) * 1000) : undefined;
+  // Via supervisor: on timeout the whole tree is killed (npm test, dev server), not just the shell.
+  const r = runSupervised({ cmd: line, shell: true, cwd, timeoutMs });
+  return { code: r.code, stdout: r.stdout ?? '', stderr: r.stderr || r.error || '', timedOut: !!r.timedOut };
+}
+
+export const git = (args, opts) => run('git', args, opts);
+
+/** Current branch; also works in a new repo with no commits (unborn HEAD). */
+export const currentBranch = (cwd) => git(['symbolic-ref', '--short', 'HEAD'], { cwd, allowFail: true }).stdout || 'HEAD';
+export const gh = (args, opts) => run('gh', args, opts);
+export const ghJson = (args, opts) => JSON.parse(gh(args, opts).stdout || 'null');