Subagent Handoff

1#!/usr/bin/env node
2'use strict';
3
4// Write the handoff a fresh subagent starts from. Prints one JSON line:
5// { ok, file, round, outcome, bytes, budgetRoundsWithoutProgress }.
6
7const path = require('node:path');
8const { writeHandoff } = require('../lib/subagent-handoff.js');
9
10function usage() {
11  return `Usage:
12  node skills/wix-replatform/scripts/subagent-handoff.js write --project <dir> --stage <stage>
13      [--resource <resources/rp-...>] [--outcome done|failed|budget_exceeded|needs_decision|resume_limit|qa_findings]
14      [--reason budget_exceeded] [--findings <qa-result.json|.md>] [--changed a,b,c] [--notes <text>] [--worker-id <id>] [--cap-bytes <n>]
15
16Writes <project>/state/handoffs/<stage>-<round>.json from durable state only (write-log summary,
17completion-report status, pending user actions, QA findings), capped at 8 KB by default.
18`;
19}
20
21function parseArgs(argv) {
22  const args = { _: [] };
23  for (let i = 0; i < argv.length; i += 1) {
24    const token = argv[i];
25    if (token === '--help' || token === '-h') { args.help = true; continue; }
26    if (!token.startsWith('--')) { args._.push(token); continue; }
27    const key = token.slice(2).replace(/-([a-z])/g, (_, c) => c.toUpperCase());
28    const value = argv[i + 1];
29    if (value === undefined || value.startsWith('--')) throw new Error(`missing value for ${token}`);
30    args[key] = value;
31    i += 1;
32  }
33  return args;
34}
35
36async function main() {
37  const args = parseArgs(process.argv.slice(2));
38  if (args.help || args._[0] !== 'write') { process.stdout.write(usage()); if (!args.help) process.exitCode = 2; return; }
39  if (!args.project || !args.stage) throw new Error(`--project and --stage are required\n${usage()}`);
40  const projectDir = path.resolve(args.project);
41  const result = await writeHandoff(projectDir, {
42    stage: args.stage,
43    resource: args.resource,
44    outcome: args.outcome || args.reason,
45    findingsFile: args.findings ? path.resolve(args.findings) : null,
46    changedFiles: args.changed ? args.changed.split(',').map((s) => s.trim()).filter(Boolean) : [],
47    notes: args.notes,
48    workerId: args.workerId,
49    capBytes: args.capBytes,
50  });
51  process.stdout.write(`${JSON.stringify({
52    ok: true,
53    file: path.relative(projectDir, result.file),
54    round: result.handoff.round,
55    outcome: result.handoff.outcome,
56    bytes: result.bytes,
57    budgetRoundsWithoutProgress: result.handoff.budgetRoundsWithoutProgress,
58  })}\n`);
59}
60
61main().catch((error) => {
62  process.stderr.write(`${error && error.message ? error.message : error}\n`);
63  process.exit(1);
64});