gcf-harness-aif-ext 0.27.0 → 0.28.1
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.
- package/README.md +1 -1
- package/commands/harness.js +141 -53
- package/commands/plan-review.js +8 -2
- package/commands/run.js +370 -182
- package/extension.json +1 -1
- package/hooks/implement-guard.js +2 -0
- package/hooks/metrics.js +1 -0
- package/node_modules/gcf-session/lib/chat.js +34 -16
- package/node_modules/gcf-session/lib/proc.js +5 -1
- package/node_modules/gcf-session/lib/session.js +39 -19
- package/node_modules/gcf-session/lib/store.js +14 -9
- package/node_modules/gcf-session/lib/thread.js +9 -3
- package/node_modules/gcf-session/lib/usage.js +12 -1
- package/node_modules/gcf-session/package.json +1 -1
- package/package.json +1 -1
- package/skills/gcf-run/SKILL.md +3 -0
package/README.md
CHANGED
|
@@ -123,7 +123,7 @@ Updating keeps the hook entry valid — it points into the extension's install d
|
|
|
123
123
|
- A stop that comes while the session starts no longer misses it.
|
|
124
124
|
|
|
125
125
|
0.9.0, to update together with core 0.7.6:
|
|
126
|
-
- The harness's own agent runs with `--permission-mode bypassPermissions`: it may do everything but the project's deny rules, which hold in every mode. The rules come from the deny groups of `gcf/config.yml` (`ai-factory gcf permissions`, or the board): git history and uncommitted work, recursive delete, publishing, the human's GCF moves and the guards are on by default; secrets, changes outside the project and killing processes are off. `git push` is allowed. Deny rules match the command as written: they catch accidents, not a rewording, and `/gcf-run` makes a refused command a stop with `needs permission: <command>`.
|
|
126
|
+
- The harness's own agent runs with `--permission-mode bypassPermissions`: it may do everything but the project's deny rules, which hold in every mode. The rules come from the deny groups of `gcf/config.yml` (`ai-factory gcf permissions`, or the board): git history and uncommitted work, recursive delete, publishing, the human's GCF moves and the guards are on by default; secrets, changes outside the project and killing processes are off. `git push` is allowed. Deny rules match the command as written: they catch accidents, not a rewording, and `/gcf-run` makes a refused command a stop with `needs permission: <command>`. `gcf-harness run <id> --allow "<rule>"` reruns it with that one rule off for this run only (the rule as the refusal names it, `edit: .claude/**`; repeat for more): its sessions get a settings file of their own, removed at the end, and a run beside it keeps the rule. A rule not in force is refused. The run report of an item so blocked prints that rerun line.
|
|
127
127
|
- A run loads the project's settings and MCP servers only (`--setting-sources project,local --strict-mcp-config --mcp-config .mcp.json`): the operator's plugins, hooks and claude.ai connectors stay out. So does `env` or `apiKeyHelper` in `~/.claude/settings.json`: an operator who logs in through them, not `claude login`, names the agent with `--agent`. The deny rules and the handoff guard come in `.gcf-session/runs/agent-settings.json` (`--settings`), so a worktree gets them without a commit.
|
|
128
128
|
- Context handoff: past `context_handoff_pct` (60 by default) of the window, or at a compaction, the run flags the session; the handoff guard then denies every call of the main agent but the plan's read and edit with the instruction to write `## Handoff` into the plan and end. The run starts a fresh session with `/gcf-run <id> --handoff`, which goes on from the plan: the ticked tasks stay done. A session that works on past its flag is stopped; after 3 handoffs in a row the item is blocked with `context handoff limit`. The window is `context_window`, else the one a result of the same model reported (`.gcf-session/runs/windows.json`); with neither, the first session of a model runs without a handoff and says so. A fresh session already over the share at its first turn (claude's own prompt and the skills hold about 40k tokens) is not handed over by the share, for a fresh one would start there too: its log says `handoff: off, the session starts at N% of the window, over context_handoff_pct P`; a compaction still hands it over (0.21.0). The sessions of an item share one timeout, and their costs add up; `--json` gives `handoffs`.
|
|
129
129
|
- `auto_compact_pct` sets the agent's `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`, at least 15 points above the handoff share.
|
package/commands/harness.js
CHANGED
|
@@ -33,7 +33,15 @@ import {
|
|
|
33
33
|
queueOf,
|
|
34
34
|
stopOf,
|
|
35
35
|
} from './run.js';
|
|
36
|
-
import {
|
|
36
|
+
import {
|
|
37
|
+
CHAT_TIMEOUT_MIN,
|
|
38
|
+
ChatRefusal,
|
|
39
|
+
alive,
|
|
40
|
+
chatInput,
|
|
41
|
+
chatOut,
|
|
42
|
+
killTree,
|
|
43
|
+
readText,
|
|
44
|
+
} from 'gcf-session';
|
|
37
45
|
|
|
38
46
|
const EXT_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
|
|
39
47
|
const SCHEMA = 1; // the only gcf/config.yml schema this harness drives
|
|
@@ -189,22 +197,7 @@ function milestoneStop(report) {
|
|
|
189
197
|
export function nextPlan(report, count, skip = []) {
|
|
190
198
|
const stop = milestoneStop(report);
|
|
191
199
|
if (stop) return { ids: [], mode: null, units: [], stop };
|
|
192
|
-
const
|
|
193
|
-
const batch = [];
|
|
194
|
-
const ready = (report.items ?? [])
|
|
195
|
-
.filter((i) => i.status === 'ready' && !i.running && i.type !== 'feature')
|
|
196
|
-
.filter((i) => i.type !== 'release' && (!scope || scope.has(i.id)) && !skip.includes(i.id))
|
|
197
|
-
.sort((a, b) => rank(a) - rank(b));
|
|
198
|
-
// One run mode a batch: an autopilot starts it as one run, a main one in the checkout.
|
|
199
|
-
let mode = null;
|
|
200
|
-
for (const i of ready) {
|
|
201
|
-
if (batch.length >= count) break;
|
|
202
|
-
if (mode && (i.run_mode ?? mode) !== mode) continue;
|
|
203
|
-
if (gate(report, [...batch, i.id]).pass) {
|
|
204
|
-
batch.push(i.id);
|
|
205
|
-
mode ??= i.run_mode ?? null;
|
|
206
|
-
}
|
|
207
|
-
}
|
|
200
|
+
const { batch, mode } = takeBatch(report, readyOf(report, inScope(report), skip), count);
|
|
208
201
|
|
|
209
202
|
const building = (report.milestones ?? []).find((m) => m.name === report.build_milestone);
|
|
210
203
|
const units = (building?.units ?? [])
|
|
@@ -224,6 +217,30 @@ export function nextPlan(report, count, skip = []) {
|
|
|
224
217
|
return { ids: batch, mode, units, stop: empty };
|
|
225
218
|
}
|
|
226
219
|
|
|
220
|
+
/** The ready items an autopilot may take, in scope and not skipped, by priority. */
|
|
221
|
+
const readyOf = (report, scope, skip) =>
|
|
222
|
+
(report.items ?? [])
|
|
223
|
+
.filter((i) => i.status === 'ready' && !i.running && i.type !== 'feature')
|
|
224
|
+
.filter((i) => i.type !== 'release' && (!scope || scope.has(i.id)) && !skip.includes(i.id))
|
|
225
|
+
.sort((a, b) => rank(a) - rank(b));
|
|
226
|
+
|
|
227
|
+
/** Up to `count` of `ready`, each while the batch with it still passes the gate. */
|
|
228
|
+
function takeBatch(report, ready, count) {
|
|
229
|
+
const batch = [];
|
|
230
|
+
// One run mode a batch: an autopilot starts it as one run, a main one in the checkout.
|
|
231
|
+
let mode = null;
|
|
232
|
+
for (const i of ready) {
|
|
233
|
+
if (batch.length >= count) break;
|
|
234
|
+
if (mode && (i.run_mode ?? mode) !== mode) continue;
|
|
235
|
+
if (gate(report, [...batch, i.id]).pass) {
|
|
236
|
+
batch.push(i.id);
|
|
237
|
+
mode ??= i.run_mode ?? null;
|
|
238
|
+
}
|
|
239
|
+
}
|
|
240
|
+
|
|
241
|
+
return { batch, mode };
|
|
242
|
+
}
|
|
243
|
+
|
|
227
244
|
/** The ids of `nextPlan`: what a board's Run offers. */
|
|
228
245
|
export const nextBatch = (report, count) => nextPlan(report, count).ids;
|
|
229
246
|
|
|
@@ -287,7 +304,7 @@ export function withMainQueue(report, runs) {
|
|
|
287
304
|
function auditReport() {
|
|
288
305
|
// Re-enter the same ai-factory CLI that is running this command: no PATH or .cmd lookup.
|
|
289
306
|
const args = [process.argv[1], 'gcf', 'audit', '--json'];
|
|
290
|
-
const res = spawnSync(process.execPath, args, { encoding: 'utf8' });
|
|
307
|
+
const res = spawnSync(process.execPath, args, { windowsHide: true, encoding: 'utf8' });
|
|
291
308
|
try {
|
|
292
309
|
return withMainQueue(JSON.parse(res.stdout), path.join(process.cwd(), '.gcf-session', 'runs'));
|
|
293
310
|
} catch (err) {
|
|
@@ -549,7 +566,32 @@ export function register(program) {
|
|
|
549
566
|
.action(runGate);
|
|
550
567
|
|
|
551
568
|
registerRun(harness);
|
|
569
|
+
registerNext(harness);
|
|
570
|
+
registerCard(harness);
|
|
571
|
+
harness
|
|
572
|
+
.command('metrics')
|
|
573
|
+
.description('Run metrics from gcf/.metrics: reached moves, cost, plan checks, DoD, guards')
|
|
574
|
+
.option('--since <date>', 'only lines at or after this ISO date or time')
|
|
575
|
+
.option('--json', 'machine output')
|
|
576
|
+
.action(metricsCommand);
|
|
577
|
+
harness
|
|
578
|
+
.command('runs')
|
|
579
|
+
.description('Past runs from gcf/.metrics/run-log.csv, the latest first: items, results, cost')
|
|
580
|
+
.option('--item <id>', 'only the runs that hold this item')
|
|
581
|
+
.option('--limit <n>', 'at most this many runs', '50')
|
|
582
|
+
.option('--json', 'machine output: {runs: [...]}')
|
|
583
|
+
.action(runsCommand);
|
|
584
|
+
harness
|
|
585
|
+
.command('stop <id>')
|
|
586
|
+
.description('Stop the session that works an item; the run goes on, the item stays ready')
|
|
587
|
+
.action((id) => console.log(stopRun(process.cwd(), id)));
|
|
588
|
+
registerHold(harness);
|
|
589
|
+
registerPlanReview(harness);
|
|
590
|
+
registerChat(harness);
|
|
591
|
+
}
|
|
552
592
|
|
|
593
|
+
/** `gcf-harness next`: what can run together now, or an autopilot's plan. */
|
|
594
|
+
function registerNext(harness) {
|
|
553
595
|
harness
|
|
554
596
|
.command('next [count]')
|
|
555
597
|
.description('The ready items that can run together now, by priority (the gate decides)')
|
|
@@ -580,6 +622,10 @@ export function register(program) {
|
|
|
580
622
|
o.json ? JSON.stringify(ids) : ids.join('\n') || plan.stop?.text || 'nothing can run now',
|
|
581
623
|
);
|
|
582
624
|
});
|
|
625
|
+
}
|
|
626
|
+
|
|
627
|
+
/** `gcf-harness card`: design units into work, one agent session on main. */
|
|
628
|
+
function registerCard(harness) {
|
|
583
629
|
harness
|
|
584
630
|
.command('card <units...>')
|
|
585
631
|
.description(
|
|
@@ -607,26 +653,6 @@ export function register(program) {
|
|
|
607
653
|
process.exitCode = 1;
|
|
608
654
|
}
|
|
609
655
|
});
|
|
610
|
-
harness
|
|
611
|
-
.command('metrics')
|
|
612
|
-
.description('Run metrics from gcf/.metrics: reached moves, cost, plan checks, DoD, guards')
|
|
613
|
-
.option('--since <date>', 'only lines at or after this ISO date or time')
|
|
614
|
-
.option('--json', 'machine output')
|
|
615
|
-
.action(metricsCommand);
|
|
616
|
-
harness
|
|
617
|
-
.command('runs')
|
|
618
|
-
.description('Past runs from gcf/.metrics/run-log.csv, the latest first: items, results, cost')
|
|
619
|
-
.option('--item <id>', 'only the runs that hold this item')
|
|
620
|
-
.option('--limit <n>', 'at most this many runs', '50')
|
|
621
|
-
.option('--json', 'machine output: {runs: [...]}')
|
|
622
|
-
.action(runsCommand);
|
|
623
|
-
harness
|
|
624
|
-
.command('stop <id>')
|
|
625
|
-
.description('Stop the session that works an item; the run goes on, the item stays ready')
|
|
626
|
-
.action((id) => console.log(stopRun(process.cwd(), id)));
|
|
627
|
-
registerHold(harness);
|
|
628
|
-
registerPlanReview(harness);
|
|
629
|
-
registerChat(harness);
|
|
630
656
|
}
|
|
631
657
|
|
|
632
658
|
/** `gcf-harness plan-review`: the outside reviewer's pass of a plan (Hold-Plan d17). */
|
|
@@ -684,6 +710,13 @@ function registerRun(harness) {
|
|
|
684
710
|
)
|
|
685
711
|
.option('--mode <mode>', 'worktree | main (default: run_mode of gcf/config.yml)')
|
|
686
712
|
.option('--fresh', 'start new agent sessions: an interrupted one is not resumed')
|
|
713
|
+
.option(
|
|
714
|
+
'--allow <rule>',
|
|
715
|
+
'go without this deny rule in force for this run only, as a refusal names it ' +
|
|
716
|
+
'(`edit: .claude/**`); repeat for more',
|
|
717
|
+
(v, all) => [...all, v],
|
|
718
|
+
[],
|
|
719
|
+
)
|
|
687
720
|
.option(
|
|
688
721
|
'--wait-limit',
|
|
689
722
|
'a queued start: each session first waits while the usage limit is known to reset ahead',
|
|
@@ -884,21 +917,68 @@ export const itemLine = (i) =>
|
|
|
884
917
|
i.process,
|
|
885
918
|
i.shelved && `${i.shelved.id}'s work went to ${i.shelved.branch}`,
|
|
886
919
|
i.returned && `its work came back with ${i.conflicts?.length ?? 0} conflict(s)`,
|
|
887
|
-
i
|
|
888
|
-
!i.build.ok &&
|
|
889
|
-
!i.build.moved_on &&
|
|
890
|
-
`no build to play: ${i.build.problem.split('\n')[0]}`,
|
|
891
|
-
i.build?.dirtied?.length && `its build changed ${i.build.dirtied.join(', ')}`,
|
|
920
|
+
...buildNotes(i),
|
|
892
921
|
]
|
|
893
922
|
.filter(Boolean)
|
|
894
|
-
.join(' — ') + (i
|
|
923
|
+
.join(' — ') + lessonsNote(i);
|
|
924
|
+
|
|
925
|
+
/** What an item's line says of its build: none to play, or the files it changed. */
|
|
926
|
+
const buildNotes = (i) => [
|
|
927
|
+
i.build &&
|
|
928
|
+
!i.build.ok &&
|
|
929
|
+
!i.build.moved_on &&
|
|
930
|
+
`no build to play: ${i.build.problem.split('\n')[0]}`,
|
|
931
|
+
i.build?.dirtied?.length && `its build changed ${i.build.dirtied.join(', ')}`,
|
|
932
|
+
];
|
|
933
|
+
|
|
934
|
+
/** The lessons an item's sessions left, at its line's end; empty without any. */
|
|
935
|
+
const lessonsNote = (i) => (i.lessons ? `, ${i.lessons} lesson${i.lessons > 1 ? 's' : ''}` : '');
|
|
936
|
+
|
|
937
|
+
/**
|
|
938
|
+
* The deny rule the last refusal in an item's run chat named (`kind: pattern`), or null: the
|
|
939
|
+
* one `--allow` takes (docs/Permission-Stop-Plan.md, d5).
|
|
940
|
+
*/
|
|
941
|
+
export function deniedRuleOf(projectDir, id) {
|
|
942
|
+
const file = chatOut(path.join(projectDir, '.gcf-session', 'runs'), id);
|
|
943
|
+
const text = existsSync(file) ? readFileSync(file, 'utf8') : '';
|
|
944
|
+
const events = text.split('\n').flatMap((l) => {
|
|
945
|
+
try {
|
|
946
|
+
return l ? [JSON.parse(l)] : [];
|
|
947
|
+
} catch {
|
|
948
|
+
return [];
|
|
949
|
+
}
|
|
950
|
+
});
|
|
951
|
+
// The last session's last rule refusal, as the board's deniedRuleOf: none from an older
|
|
952
|
+
// session, none when two rules held (it names none), none of a group no run goes without.
|
|
953
|
+
const start = events.findLastIndex((e) => e.type === 'session' && e.kind === 'start');
|
|
954
|
+
const last = events
|
|
955
|
+
.slice(Math.max(0, start))
|
|
956
|
+
.findLast((e) => e.type === 'denied' && e.by === 'rule');
|
|
957
|
+
if (!last?.rule || NEVER_ALLOWED.includes(last.group)) return null;
|
|
958
|
+
|
|
959
|
+
return last.rule;
|
|
960
|
+
}
|
|
961
|
+
|
|
962
|
+
// The groups whose rules no run goes without: history, the operator's moves, the play build.
|
|
963
|
+
const NEVER_ALLOWED = ['git-history', 'git-destroy', 'human-moves', 'run-play'];
|
|
964
|
+
|
|
965
|
+
/** How to rerun an item a refused call blocked, without that rule, or null. */
|
|
966
|
+
export function rerunHint(projectDir, i) {
|
|
967
|
+
const rule = /^needs permission/.test(i.reason ?? '') ? deniedRuleOf(projectDir, i.id) : null;
|
|
968
|
+
|
|
969
|
+
return rule
|
|
970
|
+
? ` rerun without it: ai-factory gcf unblock ${i.id}, then ` +
|
|
971
|
+
`ai-factory gcf-harness run ${i.id} --allow "${rule}"`
|
|
972
|
+
: null;
|
|
973
|
+
}
|
|
895
974
|
|
|
896
975
|
/** The run report a human reads, then the playtest sheet of what now waits for play. */
|
|
897
976
|
function printRun(r) {
|
|
898
977
|
for (const o of r.orphans)
|
|
899
978
|
console.log(`orphan ${o.id}: ${o.move ?? o.conflict ?? o.error ?? o.skipped}`);
|
|
900
979
|
if (r.gate) console.error(`gcf gate: ${r.gate}`);
|
|
901
|
-
for (const i of r.items)
|
|
980
|
+
for (const i of r.items)
|
|
981
|
+
console.log([itemLine(i), rerunHint(process.cwd(), i)].filter(Boolean).join('\n'));
|
|
902
982
|
for (const f of r.features ?? [])
|
|
903
983
|
console.log(`feature ${f.id}: ${f.result}${f.error ? ` — ${f.error}` : ''}`);
|
|
904
984
|
|
|
@@ -910,16 +990,23 @@ const failed = (r) =>
|
|
|
910
990
|
r.items.some((i) => ['conflict', 'error'].includes(i.result)) ||
|
|
911
991
|
r.orphans.some((o) => o.conflict || o.error);
|
|
912
992
|
|
|
993
|
+
/** The minutes of `--timeout` and `--chat-timeout`; a bad option, `--mode` too, throws. */
|
|
994
|
+
function runMinutes(opts) {
|
|
995
|
+
const minutes = opts.timeout === undefined ? undefined : Number(opts.timeout);
|
|
996
|
+
if (minutes !== undefined && !(minutes > 0))
|
|
997
|
+
throw new Error('--timeout is a number of minutes above 0');
|
|
998
|
+
if (opts.mode && !['worktree', 'main'].includes(opts.mode))
|
|
999
|
+
throw new Error('--mode is worktree or main');
|
|
1000
|
+
const answer = opts.chatTimeout === undefined ? null : Number(opts.chatTimeout);
|
|
1001
|
+
if (answer !== null && !(answer >= 0))
|
|
1002
|
+
throw new Error('--chat-timeout is a number of minutes, 0 or more');
|
|
1003
|
+
|
|
1004
|
+
return { minutes, answer };
|
|
1005
|
+
}
|
|
1006
|
+
|
|
913
1007
|
async function runItems(ids, opts) {
|
|
914
1008
|
try {
|
|
915
|
-
const minutes
|
|
916
|
-
if (minutes !== undefined && !(minutes > 0))
|
|
917
|
-
throw new Error('--timeout is a number of minutes above 0');
|
|
918
|
-
if (opts.mode && !['worktree', 'main'].includes(opts.mode))
|
|
919
|
-
throw new Error('--mode is worktree or main');
|
|
920
|
-
const answer = opts.chatTimeout === undefined ? null : Number(opts.chatTimeout);
|
|
921
|
-
if (answer !== null && !(answer >= 0))
|
|
922
|
-
throw new Error('--chat-timeout is a number of minutes, 0 or more');
|
|
1009
|
+
const { minutes, answer } = runMinutes(opts);
|
|
923
1010
|
// The true-case path: Claude Code trusts a folder by its exact path, and a shell or a board
|
|
924
1011
|
// may hand over c: for C:, which turns off every allow rule of the project.
|
|
925
1012
|
const r = await run(realpathSync.native(process.cwd()), [...new Set(ids)], {
|
|
@@ -928,6 +1015,7 @@ async function runItems(ids, opts) {
|
|
|
928
1015
|
timeoutMs: minutes === undefined ? undefined : minutes * 60_000,
|
|
929
1016
|
mode: opts.mode,
|
|
930
1017
|
fresh: Boolean(opts.fresh),
|
|
1018
|
+
allow: opts.allow,
|
|
931
1019
|
waitLimit: Boolean(opts.waitLimit),
|
|
932
1020
|
chat: opts.chat ? { answerMin: answer } : null,
|
|
933
1021
|
model: opts.model,
|
package/commands/plan-review.js
CHANGED
|
@@ -45,13 +45,15 @@ export function planReview(projectDir, o) {
|
|
|
45
45
|
...['--output-schema', FINDINGS_SCHEMA, '-o', out],
|
|
46
46
|
];
|
|
47
47
|
const res = spawnSync(exe, [...pre, ...args], {
|
|
48
|
+
windowsHide: true,
|
|
48
49
|
cwd: projectDir,
|
|
49
50
|
input: reviewPrompt(o.id, o.plan),
|
|
50
51
|
encoding: 'utf8',
|
|
51
52
|
timeout: o.timeoutMs ?? REVIEW_TIMEOUT_MS,
|
|
52
53
|
shell,
|
|
53
54
|
});
|
|
54
|
-
if (res.error?.code === 'ETIMEDOUT')
|
|
55
|
+
if (/** @type {NodeJS.ErrnoException | undefined} */ (res.error)?.code === 'ETIMEDOUT')
|
|
56
|
+
return { failed: 'the review timed out' };
|
|
55
57
|
// A flag the CLI no longer takes is named as it said it (Hold-Plan risk 11).
|
|
56
58
|
if (res.status !== 0)
|
|
57
59
|
return { failed: `codex exit ${res.status}: ${firstLine(res.stderr || res.stdout)}` };
|
|
@@ -66,7 +68,11 @@ export function planReview(projectDir, o) {
|
|
|
66
68
|
function reviewerMissing(cfg, exe, pre, shell) {
|
|
67
69
|
if (cfg.agent === 'none') return 'plan_review.agent is none';
|
|
68
70
|
if (cfg.agent !== 'codex') return `no reviewer named ${cfg.agent}: only codex runs`;
|
|
69
|
-
const version = spawnSync(exe, [...pre, '--version'], {
|
|
71
|
+
const version = spawnSync(exe, [...pre, '--version'], {
|
|
72
|
+
windowsHide: true,
|
|
73
|
+
encoding: 'utf8',
|
|
74
|
+
shell,
|
|
75
|
+
});
|
|
70
76
|
|
|
71
77
|
return version.error || version.status !== 0 ? 'no codex in PATH' : null;
|
|
72
78
|
}
|