gcf-board 0.32.0 → 0.36.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.
@@ -13,7 +13,7 @@ import path from 'node:path';
13
13
  import { fileURLToPath } from 'node:url';
14
14
  import { writeAtomicSync } from './atomic.js';
15
15
  import { briefError, runCli, startOf } from './cli.js';
16
- import { alive, broadcast } from './events.js';
16
+ import { alive, broadcast, movesWaiting } from './events.js';
17
17
  import { HttpError } from './http-error.js';
18
18
  import { homeDir } from './registry.js';
19
19
  import { accountSettings, lastReading, reserveOfReading } from 'gcf-session';
@@ -123,16 +123,21 @@ const paused = new Set();
123
123
  // operator's own Run goes at once. Apart from `paused`: Release resumes the queue, nothing else.
124
124
  const projectHolds = new Set();
125
125
  // Projects where the operator's "Allow for one run" unblocks a card (Permission-Stop-Plan d3):
126
- // no autopilot run starts in the gap, or it would take the card without the allowance.
127
- const allowing = new Set();
126
+ // no autopilot run starts in the gap, or it would take the card without the allowance. A count:
127
+ // two such steps at once hold it until both end.
128
+ const allowing = new Map();
128
129
  /** Hold off the autopilot while `fn` unblocks and starts a card with its allowance. */
129
130
  export async function whileAllowing(project, fn) {
130
- allowing.add(project);
131
+ allowing.set(project, (allowing.get(project) ?? 0) + 1);
131
132
  try {
132
133
  return await fn();
133
134
  }
134
135
  finally {
135
- allowing.delete(project);
136
+ const left = (allowing.get(project) ?? 1) - 1;
137
+ if (left)
138
+ allowing.set(project, left);
139
+ else
140
+ allowing.delete(project);
136
141
  }
137
142
  }
138
143
  // The paused projects whose pause the usage limit set: a run that ended paused by it (AD-19).
@@ -184,7 +189,8 @@ function save() {
184
189
  projects[name] = {
185
190
  path: where,
186
191
  // `waiting` stays behind: a board started again tries it, the dependency may have ended.
187
- queue: (queues.get(name) ?? []).map(({ entry: _e, p: _p, waiting: _w, ...q }) => q),
192
+ // An unblock going now is kept as not begun: a board started again tries it again.
193
+ queue: (queues.get(name) ?? []).map(({ entry: _e, p: _p, waiting: _w, busy: _b, ...q }) => q),
188
194
  // The queue's own pause; the hold beside it, so a restart keeps both.
189
195
  paused_by: paused.has(name) ? (limitPaused.has(name) ? 'limit' : 'failure') : null,
190
196
  held: projectHolds.has(name),
@@ -292,6 +298,11 @@ function queuedOf(v) {
292
298
  const agent = isObject(v.agent)
293
299
  ? { model: pick(v.agent.model), effort: pick(v.agent.effort) }
294
300
  : undefined;
301
+ // Its unblock goes to a command line too; one that does not read would start a blocked card.
302
+ const unblock = list(v.unblock);
303
+ const slugs = unblock.length > 0 && unblock.every((id) => typeof id === 'string' && SLUG.test(id));
304
+ if (v.unblock !== undefined && !(Array.isArray(v.unblock) && slugs))
305
+ return null;
295
306
  return {
296
307
  ids: ids,
297
308
  mode: v.mode,
@@ -301,6 +312,7 @@ function queuedOf(v) {
301
312
  ...(v.waitLimit === true ? { waitLimit: true } : {}),
302
313
  ...(typeof v.waited === 'string' ? { waited: v.waited } : {}),
303
314
  ...(agent ? { agent } : {}),
315
+ ...(unblock.length ? { unblock: unblock } : {}),
304
316
  };
305
317
  }
306
318
  /** The state a board before this one kept of project `p`: its queue, pause, reports and trace. */
@@ -374,6 +386,11 @@ export function runsOf(project) {
374
386
  reports: reports.get(project) ?? [],
375
387
  acts: acts.get(project) ?? [],
376
388
  autopilot: autopilotOf(project),
389
+ moves_waiting: paths.has(project)
390
+ ? movesWaiting(paths.get(project))
391
+ .filter((w) => !w.going)
392
+ .map(({ cancel: _, going: __, ...w }) => w)
393
+ : [],
377
394
  };
378
395
  }
379
396
  /** A project left the board: nothing of it may run any more. */
@@ -422,7 +439,7 @@ function limited(run, result) {
422
439
  }
423
440
  /** Start the next queued batch when the checkout is free: after a run, or on the operator's resume. */
424
441
  function advance(project) {
425
- if (adopting.has(project))
442
+ if (adopting.has(project) || unblocking.has(project))
426
443
  return;
427
444
  if (paused.has(project) || projectHolds.has(project) || clickBuilding(project))
428
445
  return;
@@ -441,11 +458,87 @@ function advance(project) {
441
458
  return;
442
459
  }
443
460
  reserveWaits.delete(project);
444
- const [next] = queue.splice(at, 1);
461
+ const next = queue[at];
462
+ // It stays queued while it unblocks: a second click is busy, a restart keeps it.
463
+ if (next.unblock) {
464
+ void unblockAndRun(next);
465
+ return;
466
+ }
467
+ queue.splice(at, 1);
445
468
  trace(project, 'queue-run', `the queue starts ${next.ids.join(', ')}`);
446
469
  // Nobody clicked it now: it waits while the usage limit's reset is ahead.
447
470
  spawnRun({ ...next, waitLimit: true, queued: true }, next.mode);
448
471
  }
472
+ // The projects whose queue unblocks a card now: nothing else of it starts meanwhile.
473
+ const unblocking = new Set();
474
+ /** Whether a main run has the checkout, or a queued unblock takes it next (d10). */
475
+ export const mainTaken = (project) => unblocking.has(project) || activeRuns(project).some((r) => r.mode === 'main');
476
+ /**
477
+ * The unblock of item `id` by the domain's move: null when it went, or the card is unblocked
478
+ * already; else why not. The board's server sets it (app.ts): the move is the domain's.
479
+ */
480
+ let unblocker = async (_p, id) => `unblock ${id}: no board server to make it`;
481
+ export function setUnblocker(fn) {
482
+ unblocker = fn;
483
+ }
484
+ /**
485
+ * "Allow for one run" queued behind a main run (Main-Run-Moves-Plan d10): its unblock, then its
486
+ * start, the autopilot held off between them; the queue waits for both. A refused unblock is a
487
+ * refused start: the entry goes, its report says why.
488
+ */
489
+ async function unblockAndRun(q) {
490
+ const project = q.p.name;
491
+ unblocking.add(project);
492
+ // The entry as the queue holds it now: the operator may take a card out meanwhile (unqueue).
493
+ const mark = randomUUID();
494
+ q.busy = mark;
495
+ const entry = () => (queues.get(project) ?? []).find((x) => x.busy === mark);
496
+ let why = null;
497
+ try {
498
+ await whileAllowing(project, async () => {
499
+ for (const id of q.unblock ?? [])
500
+ if (entry()?.unblock?.includes(id) && (why = await unblocker(q.p, id)))
501
+ return;
502
+ const now = entry();
503
+ // Taken out of the queue meanwhile: nothing to start.
504
+ if (!now)
505
+ return;
506
+ // A main run that came meanwhile has the checkout: it waits where it is, its unblock made
507
+ // (an unblocked card is no refusal of the next try).
508
+ if (now.mode === 'main' && activeRuns(project).some((r) => r.mode === 'main'))
509
+ return;
510
+ const queue = queues.get(project) ?? [];
511
+ queue.splice(queue.indexOf(now), 1);
512
+ const { unblock: _, busy: __, ...go } = now;
513
+ trace(project, 'queue-run', `the queue unblocks and starts ${now.ids.join(', ')}`);
514
+ spawnRun({ ...go, waitLimit: true, queued: true }, now.mode);
515
+ });
516
+ }
517
+ catch (e) {
518
+ why = `unblock ${q.ids.join(', ')}: ${e.message}`;
519
+ }
520
+ finally {
521
+ unblocking.delete(project);
522
+ const left = entry();
523
+ const queue = queues.get(project) ?? [];
524
+ // A refused unblock is a refused start: the entry goes; one waiting on is free again.
525
+ if (left && why)
526
+ queue.splice(queue.indexOf(left), 1);
527
+ else if (left)
528
+ delete left.busy;
529
+ }
530
+ if (why) {
531
+ trace(project, 'queue-refused', why);
532
+ const report = { id: `r${++reportSeq}`, at: new Date().toISOString(), ids: q.ids };
533
+ reports.set(project, [
534
+ ...(reports.get(project) ?? []),
535
+ { ...report, ok: false, result: null, err: why, note: '' },
536
+ ].slice(-KEEP_REPORTS));
537
+ }
538
+ changed(project);
539
+ // A worktree run, or none, leaves the checkout free: what queues behind it goes now.
540
+ advance(project);
541
+ }
449
542
  // The projects a run reported stopped by the reserve: the board does not know the run's model,
450
543
  // so it judges every model's week until a reading under the reserve in all (Codex review).
451
544
  const reserveStrict = new Set();
@@ -570,8 +663,10 @@ export function resumeQueue(project) {
570
663
  }
571
664
  /** Take an item out of the queue before its run starts. */
572
665
  export function unqueue(project, id) {
666
+ const without = (ids) => ids.filter((x) => x !== id);
667
+ // An "Allow for one run" entry unblocks only the cards it still starts.
573
668
  const queue = (queues.get(project) ?? [])
574
- .map((q) => ({ ...q, ids: q.ids.filter((x) => x !== id) }))
669
+ .map((q) => ({ ...q, ids: without(q.ids), ...(q.unblock && { unblock: without(q.unblock) }) }))
575
670
  .filter((q) => q.ids.length);
576
671
  queues.set(project, queue);
577
672
  changed(project);
@@ -963,18 +1058,30 @@ export function busyCheck(p, ids) {
963
1058
  * `harness` is the domain's (`domain.harness`); the tests take GCF's. Its sessions are open to
964
1059
  * the operator's chat. `agent`: a model and effort for this run only, over each item's own.
965
1060
  * `allow`: deny rules in force this run goes without (docs/Permission-Stop-Plan.md, d2).
1061
+ * `unblock`: these ids are unblocked first, in the queue, in any mode (Main-Run-Moves-Plan d10).
966
1062
  */
967
- export function startRun(entry, p, ids, mode = 'main', { fresh = false, harness = 'gcf-harness', agent, allow, } = {}) {
1063
+ export function startRun(entry, p, ids, mode = 'main', { fresh = false, harness = 'gcf-harness', agent, allow, unblock, } = {}) {
968
1064
  // A second click on the same card: the harness would refuse it on its lock, noisily.
969
1065
  paths.set(p.name, p.path);
970
1066
  busyCheck(p, ids);
971
1067
  const { active: going } = runsOf(p.name);
972
1068
  // A paused queue holds a new main run too: it would repeat the failure, and jump the queue.
973
- const held = paused.has(p.name) || clickBuilding(p.name);
974
- if (mode === 'main' && (held || going.some((r) => r.mode === 'main'))) {
1069
+ // A queued "Allow for one run" unblocking now takes the checkout next: a main run waits for it.
1070
+ const held = paused.has(p.name) || clickBuilding(p.name) || unblocking.has(p.name);
1071
+ if (unblock?.length || (mode === 'main' && (held || going.some((r) => r.mode === 'main')))) {
975
1072
  queues.set(p.name, [
976
1073
  ...(queues.get(p.name) ?? []),
977
- { entry, p, ids, mode, fresh, harness, agent, ...(allow?.length ? { allow } : {}) },
1074
+ {
1075
+ entry,
1076
+ p,
1077
+ ids,
1078
+ mode,
1079
+ fresh,
1080
+ harness,
1081
+ agent,
1082
+ ...(allow?.length ? { allow } : {}),
1083
+ ...(unblock?.length ? { unblock } : {}),
1084
+ },
978
1085
  ]);
979
1086
  changed(p.name);
980
1087
  return { queued: ids };
@@ -15,7 +15,7 @@ import { THREAD_ID, createThread, defaultsOf, listThreads, presetsOf, readThread
15
15
  import { runModeOf, toolOf } from '../shared/board.js';
16
16
  import { writeAtomic } from './atomic.js';
17
17
  import { briefError, refusalOf } from './cli.js';
18
- import { alive } from './events.js';
18
+ import { alive, movesWaiting } from './events.js';
19
19
  import { HttpError } from './http-error.js';
20
20
  import { IMAGE_EXT, saysPast } from './chat.js';
21
21
  import { homeDir, yoloFile } from './registry.js';
@@ -38,6 +38,14 @@ const OWN_FILES = ['.claude/**', 'CLAUDE.md', 'AGENTS.md', '.ai-factory/**'].map
38
38
  export const agentPresets = () => presetsOf(process.env.GCF_SESSION_AGENT ?? DEFAULT_AGENT);
39
39
  /** What a thread or a run runs on when neither it nor the project picks (decision 36). */
40
40
  export const agentDefaults = () => defaultsOf(process.env.GCF_SESSION_AGENT ?? DEFAULT_AGENT);
41
+ /**
42
+ * The defaults of the agent a run of this board launches: the harness's `--agent` default, as
43
+ * the board spawns it with its own environment (Plan-Review-Rework-Plan d10). GCF's phase default
44
+ * sets only a flag these have.
45
+ * shortcut: read at the board read, not at the run; a GCF_RUN_AGENT changed in between is not
46
+ * seen; pass the run's agent along if a board ever starts runs with another one.
47
+ */
48
+ export const runDefaults = () => defaultsOf(process.env.GCF_SESSION_AGENT ?? process.env.GCF_RUN_AGENT ?? DEFAULT_AGENT);
41
49
  /**
42
50
  * Pick thread `t`'s model and effort (`default` or none: the project's setting, else the agent's default); its next session
43
51
  * takes them. A word that is not plain is a 400.
@@ -146,6 +154,8 @@ export function talkSpec(p, board, mcp, start = null) {
146
154
  ...rules.deny.filter((r) => !r.run_only),
147
155
  { kind: 'edit', pattern: '.gcf-session/**' },
148
156
  ...homeRules(),
157
+ // The start's own (a lessons review's: no edit of the agent's instructions).
158
+ ...(own?.deny ?? []),
149
159
  ],
150
160
  // Claude holds ask over allow: the blanket edit ask would shadow the start's edits. The
151
161
  // agent's own instructions and settings still ask, whatever the project allows. A start
@@ -391,9 +401,13 @@ export function designTalk(p, board, start, given) {
391
401
  const systems = board.design && !('error' in board.design) ? board.design.systems : {};
392
402
  if (s.takes === 'system' && !Object.hasOwn(systems, given.system ?? ''))
393
403
  throw new HttpError(400, `${start} takes a subsystem of the design: ${String(given.system)}`);
394
- const text = String(given.text ?? '').trim();
404
+ const text = s.entries
405
+ ? entriesOf(board, s.entries, String(given.text ?? ''))
406
+ : String(given.text ?? '').trim();
395
407
  if (s.takes === 'text' && !text)
396
- throw new HttpError(400, `${start} takes the change in words`);
408
+ throw new HttpError(400, s.entries
409
+ ? `${start} takes inbox entries of category ${s.entries}: none of these is one`
410
+ : `${start} takes the change in words`);
397
411
  const t = createThread(p.path, { start: { id: start } });
398
412
  let file = '';
399
413
  if (given.file && name) {
@@ -417,6 +431,14 @@ export function designTalk(p, board, start, given) {
417
431
  .replaceAll('{text}', () => text);
418
432
  return { id: t, say };
419
433
  }
434
+ /**
435
+ * The ids of `asked` (comma or space separated) that are inbox entries of `category` on the
436
+ * board, each once, as `in-a, in-b`: an id the page sent of another kind, or gone, is left out.
437
+ */
438
+ export function entriesOf(board, category, asked) {
439
+ const of = new Set((board.inbox ?? []).filter((e) => e.category === category).map((e) => e.id));
440
+ return [...new Set(asked.split(/[\s,]+/).filter((id) => of.has(id)))].join(', ');
441
+ }
420
442
  /**
421
443
  * Design start `start` (designTalk), its first message sent by `send`: the thread's id. A send
422
444
  * that fails takes the thread away with it, so no empty thread stays in the list.
@@ -638,6 +660,11 @@ function addRecord(td, id, rec) {
638
660
  }
639
661
  // The proposals whose move runs now, `<td> <id>`: a second click waits for none.
640
662
  const accepting = new Set();
663
+ /**
664
+ * The GCF_MOVE_TAG of proposal `id` of thread `t`'s move (Main-Run-Moves-Plan d7, d9): a board
665
+ * started again finds it waiting by it. The dot keeps it apart from a page's tag.
666
+ */
667
+ export const proposalTag = (t, id) => `${t}.${id}`;
641
668
  /**
642
669
  * Make proposal `id` of thread `t` by its move (AD-16, AD-33): `accepting` is written first,
643
670
  * with the item it makes, whether that id was taken already and HEAD before it; then `accepted`
@@ -669,6 +696,9 @@ export async function acceptProposal(p, t, id, move, item, ids, run, mark, quest
669
696
  const made = await settled(td, id, readRecords(td)[id], async () => ids, true);
670
697
  if (made?.state === 'accepted')
671
698
  throw new HttpError(409, `proposal ${id} is made already: ${made.item ?? ''}`);
699
+ // Its move of a board before this one waits behind a main run (d9).
700
+ if (made?.state === 'accepting')
701
+ throw new HttpError(409, `proposal ${id} is being made already`);
672
702
  const head = git(projectOf(td), 'rev-parse', 'HEAD');
673
703
  await setRecord(td, id, {
674
704
  state: 'accepting',
@@ -734,14 +764,21 @@ async function settled(td, id, rec, ids, mine = false) {
734
764
  if (latest?.state !== 'accepting' || (!mine && accepting.has(`${td} ${id}`)))
735
765
  return latest;
736
766
  const projectDir = projectOf(td);
767
+ // Its move waits behind a main run still, outliving the board that made it (d9): not over.
768
+ const tag = proposalTag(path.basename(td), id);
769
+ if (movesWaiting(projectDir).some((w) => w.tag === tag))
770
+ return latest;
737
771
  const ours = !rec.mark ||
738
772
  git(projectDir, 'log', '-1', '--format=%H', `--grep=^GCF-Proposal: ${rec.mark}$`) !== '';
739
773
  // A new item: there now and not before, by its own commit. A move on what is already there
740
- // (an item, a question): its commit since the HEAD the record kept, by the trailers.
774
+ // (an item, a question): its commit since the HEAD the record kept, by the trailers. A marked
775
+ // move on what is there (an amend, a group of entries): only its own commit says so; entries
776
+ // gone may be another move's doing.
741
777
  const made = (!rec.existed && Boolean(rec.item) && board.has(rec.item ?? '') && ours) ||
742
778
  (!rec.mark &&
743
779
  Boolean(rec.head && rec.cmd) &&
744
- movedSince(projectDir, rec.head ?? '', rec.cmd ?? '', rec.item ?? ''));
780
+ movedSince(projectDir, rec.head ?? '', rec.cmd ?? '', rec.item ?? '')) ||
781
+ (Boolean(rec.mark) && (rec.existed || !rec.item) && ours);
745
782
  const next = made
746
783
  ? { state: 'accepted', item: rec.item, at: now() }
747
784
  : { state: 'refused', error: 'the board stopped while it was made: try again', at: now() };
@@ -1,6 +1,6 @@
1
1
  // The read model of `ai-factory gcf board --json` (Methodology §11): the board refuses a schema
2
2
  // it does not know. Types only, plus the version this board reads.
3
- export const BOARD_SCHEMA = 6;
3
+ export const BOARD_SCHEMA = 7;
4
4
  // Where a project keeps files given to an item or an inbox entry (Board-PRD §5.3, §5.6): only
5
5
  // there may the board hand out a file that is not text. One list: a later kind is one line.
6
6
  const ATTACHED = [