gcf-board 0.16.9 → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -6,16 +6,17 @@
6
6
  // In `run_mode: main` the checkout takes one run at a time: a run asked for meanwhile waits in
7
7
  // the project's queue and starts when the one before it ends. The queue, its pause, the reports
8
8
  // and the trace live in `<board home>/queue.json` too: a board started again goes on with them.
9
- import { spawn } from 'node:child_process';
10
- import { randomUUID } from 'node:crypto';
9
+ import { spawn, spawnSync } from 'node:child_process';
10
+ import { createHash, randomUUID } from 'node:crypto';
11
11
  import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
12
12
  import path from 'node:path';
13
13
  import { fileURLToPath } from 'node:url';
14
14
  import { writeAtomicSync } from './atomic.js';
15
- import { briefError } from './cli.js';
15
+ import { briefError, runCli } from './cli.js';
16
16
  import { alive, broadcast } from './events.js';
17
17
  import { HttpError } from './http-error.js';
18
18
  import { homeDir } from './registry.js';
19
+ import { askUsage } from './usage.js';
19
20
  // The source runs relay.ts, the package its build beside this file.
20
21
  const RELAY = fileURLToPath(new URL(import.meta.url.endsWith('.ts') ? 'relay.ts' : 'relay.js', import.meta.url));
21
22
  const flightsDir = () => path.join(homeDir(), 'runs');
@@ -62,7 +63,13 @@ let loaded = null;
62
63
  */
63
64
  function save() {
64
65
  loaded ??= readSaved();
65
- const names = new Set([...queues.keys(), ...paused, ...reports.keys(), ...acts.keys()]);
66
+ const names = new Set([
67
+ ...queues.keys(),
68
+ ...paused,
69
+ ...reports.keys(),
70
+ ...acts.keys(),
71
+ ...pilots.keys(),
72
+ ]);
66
73
  const projects = loaded !== 'bad' ? { ...loaded } : {};
67
74
  for (const name of names) {
68
75
  const where = paths.get(name);
@@ -75,6 +82,7 @@ function save() {
75
82
  paused_until: pausedUntil.get(name) ?? null,
76
83
  reports: reports.get(name) ?? [],
77
84
  acts: acts.get(name) ?? [],
85
+ ...(pilots.has(name) ? { autopilot: savedPilot(pilots.get(name)) } : {}),
78
86
  };
79
87
  }
80
88
  try {
@@ -210,6 +218,7 @@ function restore(entry, p) {
210
218
  const did = list(s.acts).filter((a) => isObject(a) && typeof a.act === 'string' && typeof a.text === 'string');
211
219
  if (did.length)
212
220
  acts.set(p.name, did);
221
+ restorePilot(entry, p, s.autopilot);
213
222
  // Report ids go on after the kept ones, as after a file before `seq`.
214
223
  for (const r of kept)
215
224
  reportSeq = Math.max(reportSeq, Number(r.id.slice(1)) || 0);
@@ -238,6 +247,7 @@ export function runsOf(project) {
238
247
  paused_until: paused.has(project) ? (pausedUntil.get(project) ?? null) : null,
239
248
  reports: reports.get(project) ?? [],
240
249
  acts: acts.get(project) ?? [],
250
+ autopilot: autopilotOf(project),
241
251
  };
242
252
  }
243
253
  /** A project left the board: nothing of it may run any more. */
@@ -251,6 +261,7 @@ export function forgetProject(project) {
251
261
  reports.delete(project);
252
262
  acts.delete(project);
253
263
  paths.delete(project);
264
+ pilots.delete(project);
254
265
  save();
255
266
  }
256
267
  /**
@@ -358,22 +369,28 @@ function spawnRun(q, mode) {
358
369
  const effort = q.agent?.effort ?? null;
359
370
  const run = { project: p.name, ids, started: new Date().toISOString(), mode, model, effort };
360
371
  active.add(run);
361
- // The board says where it goes: it queued it by that mode (an item's own, the run's pick).
362
- const args = [entry, harness, 'run', ...ids, '--json', '--mode', mode];
363
- if (q.fresh)
364
- args.push('--fresh');
365
- // This run's pick: the items keep their own (Board-V2-Data-Plan §2.5).
366
- if (model)
367
- args.push('--model', model);
368
- if (effort)
369
- args.push('--effort', effort);
370
- if (q.waitLimit)
371
- args.push('--wait-limit');
372
- // A board's run is always open to the operator: its chat waits the project's answer time
373
- // (`chat.answer_timeout_min`), which the harness reads. GCF_BOARD_CHAT_TIMEOUT: the tests'.
374
- args.push('--chat');
375
- if (process.env.GCF_BOARD_CHAT_TIMEOUT)
376
- args.push('--chat-timeout', process.env.GCF_BOARD_CHAT_TIMEOUT);
372
+ // The board says where it goes: it queued it by that mode (an item's own, the run's pick). A
373
+ // card session works the main checkout too, with no item yet.
374
+ const args = q.kind === 'card'
375
+ ? [entry, harness, 'card', ...ids, '--json']
376
+ : [entry, harness, 'run', ...ids, '--json', '--mode', mode];
377
+ // A card session takes none of a run's flags: `gcf-harness card` knows only --agent, --json.
378
+ if (q.kind !== 'card') {
379
+ if (q.fresh)
380
+ args.push('--fresh');
381
+ // This run's pick: the items keep their own (Board-V2-Data-Plan §2.5).
382
+ if (model)
383
+ args.push('--model', model);
384
+ if (effort)
385
+ args.push('--effort', effort);
386
+ if (q.waitLimit)
387
+ args.push('--wait-limit');
388
+ // A board's run is always open to the operator: its chat waits the project's answer time
389
+ // (`chat.answer_timeout_min`), which the harness reads. GCF_BOARD_CHAT_TIMEOUT: the tests'.
390
+ args.push('--chat');
391
+ if (process.env.GCF_BOARD_CHAT_TIMEOUT)
392
+ args.push('--chat-timeout', process.env.GCF_BOARD_CHAT_TIMEOUT);
393
+ }
377
394
  const rid = randomUUID();
378
395
  const relay = spawn(process.execPath, [RELAY, recordOf(rid), endOf(rid), ...args], {
379
396
  cwd: p.path,
@@ -393,6 +410,8 @@ function spawnRun(q, mode) {
393
410
  pid: relay.pid ?? 0,
394
411
  model,
395
412
  effort,
413
+ ...(q.kind ? { kind: q.kind } : {}),
414
+ ...(q.pilot ? { pilot: true } : {}),
396
415
  };
397
416
  try {
398
417
  if (relay.pid) {
@@ -454,6 +473,8 @@ function land(q, run, rid, live, message = '') {
454
473
  // Held by a scanner: its id is no other run's, so it only stays behind.
455
474
  }
456
475
  active.delete(run);
476
+ // A run spent some of the limit: the bar reads it again.
477
+ void askUsage();
457
478
  const { p, ids, mode } = q;
458
479
  const ok = end?.code === 0;
459
480
  const result = harnessReport(end?.out ?? '');
@@ -506,7 +527,12 @@ function land(q, run, rid, live, message = '') {
506
527
  // The checkout is free now, for whatever queue the name has: a project added back meanwhile.
507
528
  if (mode === 'main')
508
529
  advance(p.name);
530
+ if (kept && q.pilot)
531
+ piloted(p.name, ok, result);
509
532
  changed(p.name);
533
+ // Every end may let the autopilot go on: its own, and one the operator started.
534
+ if (kept)
535
+ setImmediate(() => void pilot(p.name));
510
536
  }
511
537
  /**
512
538
  * Whether the relay of a run found on adoption still goes: its pid lives and it touched its
@@ -592,7 +618,11 @@ export function adoptRuns(entry, p) {
592
618
  continue;
593
619
  const agent = { model: f.model ?? null, effort: f.effort ?? null };
594
620
  const run = { project: p.name, ids: f.ids, started: f.started, mode: f.mode, ...agent };
595
- const q = { entry, p, ids: f.ids, mode: f.mode, harness: f.harness, agent };
621
+ const q = {
622
+ ...{ entry, p, ids: f.ids, mode: f.mode, harness: f.harness, agent },
623
+ ...(f.kind === 'card' ? { kind: 'card' } : {}),
624
+ ...(f.pilot ? { pilot: true } : {}),
625
+ };
596
626
  active.add(run);
597
627
  flights.set(rid, run);
598
628
  // shortcut: off Windows a dead relay leaves its harness going (no job object), reported
@@ -622,6 +652,7 @@ export function adoptRuns(entry, p) {
622
652
  advance(p.name);
623
653
  }
624
654
  changed(p.name);
655
+ void pilot(p.name);
625
656
  }
626
657
  /** A 409 for the ids a run of this board drives or queues: a second click on the same card. */
627
658
  export function busyCheck(p, ids) {
@@ -653,3 +684,224 @@ export function startRun(entry, p, ids, mode = 'worktree', fresh = false, harnes
653
684
  }
654
685
  return { started: spawnRun({ entry, p, ids, mode, fresh, harness, agent }, mode) };
655
686
  }
687
+ const pilots = new Map();
688
+ // The projects whose autopilot is asking the harness now: one ask at a time.
689
+ const piloting = new Set();
690
+ // The batch size the autopilot asks for.
691
+ const PILOT_BATCH = 3;
692
+ const STOPS = ['play', 'empty', 'idle', 'dirty', 'no-move', 'error'];
693
+ const savedPilot = ({ on, stop, guard, harness }) => ({
694
+ on,
695
+ stop,
696
+ guard,
697
+ harness,
698
+ });
699
+ /** The autopilot `queue.json` kept for project `p`, when it reads as one. */
700
+ function restorePilot(entry, p, v) {
701
+ if (!isObject(v) || typeof v.harness !== 'string' || !SLUG.test(v.harness))
702
+ return;
703
+ const guard = Object.fromEntries(Object.entries(isObject(v.guard) ? v.guard : {}).filter((e) => SLUG.test(e[0]) && typeof e[1] === 'string'));
704
+ const s = v.stop;
705
+ const stop = isObject(s) && STOPS.includes(String(s.kind)) && typeof s.text === 'string'
706
+ ? s
707
+ : null;
708
+ pilots.set(p.name, { on: v.on === true, stop, guard, entry, p, harness: v.harness });
709
+ }
710
+ /**
711
+ * A unit's section of gcf/design/ (`## <id>` to the next `## `) as it is now; '' when no design
712
+ * file holds it.
713
+ */
714
+ function unitText(dir, id) {
715
+ const design = path.join(dir, 'gcf', 'design');
716
+ let files = [];
717
+ try {
718
+ files = readdirSync(design).filter((f) => f.endsWith('.md'));
719
+ }
720
+ catch {
721
+ return '';
722
+ }
723
+ for (const f of files) {
724
+ const lines = readFileSync(path.join(design, f), 'utf8').split(/\r?\n/);
725
+ const at = lines.findIndex((l) => l.trim() === `## ${id}`);
726
+ if (at < 0)
727
+ continue;
728
+ const end = lines.findIndex((l, i) => i > at && l.startsWith('## '));
729
+ return lines.slice(at, end < 0 ? lines.length : end).join('\n');
730
+ }
731
+ return '';
732
+ }
733
+ /** An item's file as it is, or else its unit's section of the design: what a guard compares. */
734
+ function guardHash(dir, id) {
735
+ const sha = (t) => createHash('sha1').update(t).digest('hex');
736
+ try {
737
+ return sha(readFileSync(path.join(dir, 'gcf', 'work', `${id}.md`)));
738
+ }
739
+ catch {
740
+ return `unit:${sha(unitText(dir, id))}`;
741
+ }
742
+ }
743
+ /** The ids the guard still holds: their file is as their last run left it. */
744
+ function guardedOf(s) {
745
+ for (const [id, hash] of Object.entries(s.guard))
746
+ if (guardHash(s.p.path, id) !== hash)
747
+ delete s.guard[id];
748
+ return Object.keys(s.guard);
749
+ }
750
+ export function autopilotOf(project) {
751
+ const s = pilots.get(project);
752
+ return { on: s?.on ?? false, stop: s?.stop ?? null, guarded: s ? Object.keys(s.guard) : [] };
753
+ }
754
+ /** Why it stands now; said once in the trace. */
755
+ function stand(project, stop) {
756
+ const s = pilots.get(project);
757
+ if (!s || JSON.stringify(s.stop) === JSON.stringify(stop))
758
+ return;
759
+ s.stop = stop;
760
+ if (stop)
761
+ trace(project, `autopilot-${stop.kind}`, stop.text);
762
+ changed(project);
763
+ }
764
+ /** The operator turns the autopilot on or off. */
765
+ export function setAutopilot(entry, p, harness, on) {
766
+ paths.set(p.name, p.path);
767
+ // The one object an ask in flight holds too: off now reads off after its awaits.
768
+ const s = pilots.get(p.name);
769
+ if (s)
770
+ Object.assign(s, { on, stop: null, entry, p, harness });
771
+ else
772
+ pilots.set(p.name, { on, stop: null, guard: {}, entry, p, harness });
773
+ const said = on ? 'on' : 'off';
774
+ trace(p.name, `autopilot-${said}`, `the operator turned the autopilot ${said}`);
775
+ changed(p.name);
776
+ if (on)
777
+ void pilot(p.name);
778
+ return autopilotOf(p.name);
779
+ }
780
+ // A run's result that is a move: what its item or unit now is. None: an orphan, merged.
781
+ const MOVED = /^(submit|close|block|decide|deferred|card|drop|question|merged)$/;
782
+ /**
783
+ * An autopilot run ended: each item or unit with no move goes into the guard, unless a usage
784
+ * limit or a timeout cut it (a rerun is meant there). A batch with no move at all turns it off.
785
+ */
786
+ function piloted(project, ok, result) {
787
+ const s = pilots.get(project);
788
+ if (!s)
789
+ return;
790
+ const items = result?.items ?? [];
791
+ const off = (kind, text) => {
792
+ s.on = false;
793
+ stand(project, { kind, text: `${text}: the autopilot is off — see its report` });
794
+ };
795
+ // No report, a refused gate: the next ask would start the same again.
796
+ if (!items.length)
797
+ return off('error', `its run ended with no result${result?.gate ? ` (${result.gate})` : ''}`);
798
+ // A stop is the operator's word: the autopilot takes it, it does not start the item again.
799
+ const stopped = items.filter((i) => /stopped/.test(`${i.result ?? ''} ${i.error ?? ''}`));
800
+ // A timeout or a usage limit cut a session a rerun is meant to go on with.
801
+ const cut = (i) => i.limit_resets !== undefined || /timed out/.test(`${i.result ?? ''} ${i.error ?? ''}`);
802
+ const none = items.filter((i) => !MOVED.test(i.result ?? 'merged') && !cut(i));
803
+ for (const i of none)
804
+ s.guard[i.id] = guardHash(s.p.path, i.id);
805
+ if (stopped.length)
806
+ return off('no-move', `you stopped ${stopped.map((i) => i.id).join(', ')}`);
807
+ const failed = items.filter((i) => ['error', 'conflict'].includes(i.result ?? ''));
808
+ if (!ok || failed.length)
809
+ return off('error', `a run failed${failed.length ? `: ${failed.map((i) => i.id).join(', ')}` : ''}`);
810
+ if (none.length === items.length)
811
+ off('no-move', `a run of ${items.map((i) => i.id).join(', ')} made no move`);
812
+ }
813
+ /** Whether the project is idle for the autopilot: no run, no queue, no pause. */
814
+ const idle = (project) => !paused.has(project) && !activeRuns(project).length && !queues.get(project)?.length;
815
+ /** Main's loose work outside gcf/ a main batch would carry; none when the gate cannot say. */
816
+ async function looseOf(s, ids) {
817
+ const g = await runCli(s.entry, s.p.path, [s.harness, 'gate', '--each', ...ids, '--json']);
818
+ let read = null;
819
+ try {
820
+ read = JSON.parse(g.out);
821
+ }
822
+ catch {
823
+ // No answer: below.
824
+ }
825
+ // A gate that cannot say is no clean main: a main run would land among loose work unwarned.
826
+ if (!g.ok || !read)
827
+ throw new Error(`gate --each: ${briefError(g.err || g.out)}`);
828
+ return read.dirty ?? [];
829
+ }
830
+ /** Ask the harness what goes now, and start it; or stand, with why. */
831
+ async function pilot(project) {
832
+ const s = pilots.get(project);
833
+ if (!s?.on || piloting.has(project) || adopting.has(project) || !idle(project))
834
+ return;
835
+ piloting.add(project);
836
+ try {
837
+ const skip = guardedOf(s);
838
+ const args = [s.harness, 'next', String(PILOT_BATCH), '--plan'];
839
+ if (skip.length)
840
+ args.push('--skip', skip.join(','));
841
+ const r = await runCli(s.entry, s.p.path, args);
842
+ let plan;
843
+ try {
844
+ plan = JSON.parse(r.out);
845
+ }
846
+ catch {
847
+ stand(project, { kind: 'error', text: `${s.harness} next: ${briefError(r.err || r.out)}` });
848
+ return;
849
+ }
850
+ // Something else started meanwhile: its end asks again.
851
+ if (!s.on || !idle(project))
852
+ return;
853
+ if (plan.stop)
854
+ return stand(project, plan.stop);
855
+ const { entry, p, harness } = s;
856
+ if (plan.units.length) {
857
+ stand(project, null);
858
+ trace(project, 'autopilot-card', `the autopilot cards ${plan.units.join(', ')}`);
859
+ const q = { entry, p, ids: plan.units, mode: 'main', harness };
860
+ spawnRun({ ...q, kind: 'card', pilot: true }, 'main');
861
+ changed(project);
862
+ return;
863
+ }
864
+ if (!plan.ids.length) {
865
+ stand(project, {
866
+ kind: 'idle',
867
+ text: 'nothing to take now: what is left waits for you, for a decision, or is blocked',
868
+ });
869
+ return;
870
+ }
871
+ const mode = plan.mode ?? 'worktree';
872
+ let loose = [];
873
+ try {
874
+ loose = mode === 'main' ? await looseOf(s, plan.ids) : [];
875
+ }
876
+ catch (e) {
877
+ s.on = false;
878
+ stand(project, { kind: 'error', text: `${e.message}: the autopilot is off` });
879
+ return;
880
+ }
881
+ if (loose.length) {
882
+ stand(project, {
883
+ kind: 'dirty',
884
+ text: `uncommitted work outside gcf/ (${loose.slice(0, 3).join(', ')}): commit it or set ` +
885
+ 'it aside; the autopilot goes on then',
886
+ });
887
+ return;
888
+ }
889
+ if (!s.on || !idle(project))
890
+ return;
891
+ stand(project, null);
892
+ trace(project, 'autopilot-run', `the autopilot runs ${plan.ids.join(', ')}`);
893
+ spawnRun({ entry, p, ids: plan.ids, mode, harness, pilot: true, waitLimit: true }, mode);
894
+ changed(project);
895
+ }
896
+ finally {
897
+ piloting.delete(project);
898
+ }
899
+ }
900
+ // A standing autopilot looks again now and then: the operator's play and keep, an answer, a
901
+ // fix outside the board move nothing it hears of.
902
+ const PILOT_LOOK_MS = Number(process.env.GCF_BOARD_PILOT_LOOK_MS ?? 30_000);
903
+ setInterval(() => {
904
+ for (const [project, s] of pilots)
905
+ if (s.on)
906
+ void pilot(project);
907
+ }, PILOT_LOOK_MS).unref();