gcf-harness-aif-ext 0.13.0 → 0.14.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.
- package/README.md +151 -149
- package/commands/harness.js +46 -6
- package/commands/run.js +29 -18
- package/extension.json +1 -1
- package/node_modules/gcf-session/lib/activity.js +12 -4
- package/node_modules/gcf-session/lib/chat.js +2 -0
- package/node_modules/gcf-session/lib/thread.js +9 -6
- package/node_modules/gcf-session/package.json +1 -1
- package/node_modules/gcf-session/types/index.d.ts +4 -0
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,149 +1,151 @@
|
|
|
1
|
-
# gcf-harness-aif-ext
|
|
2
|
-
|
|
3
|
-
Claude-Code-specific orchestration for the [Game Context Framework](../gcf-aif-ext). Optional: GCF works without it, by hand.
|
|
4
|
-
|
|
5
|
-
> **Claude Code only.** Codex and the other AI Factory runtimes are not supported: the harness is built on Claude Code
|
|
6
|
-
> dynamic workflows and `PreToolUse` hooks, which they do not have. AI Factory still copies the `gcf-run` skills into
|
|
7
|
-
> every runtime the project is configured for, where they do not work — on a project without Claude Code, do not
|
|
8
|
-
> install the harness. GCF itself keeps working on any runtime.
|
|
9
|
-
|
|
10
|
-
The harness turns policy-as-text into an executable pipeline. The game's state is on disk in `gcf/` and git, so a run killed at any point restarts and reaches the same state. The runs' own state is in `.gcf-session/`: the agent sessions a rerun resumes, the item worktrees with their uncommitted work, locks and logs. Losing it never breaks the game's model, but it loses those resumes, that work and the diagnosis: delete a single stale file, never the folder.
|
|
11
|
-
|
|
12
|
-
## Requirements
|
|
13
|
-
|
|
14
|
-
- [`gcf-aif-ext`](../gcf-aif-ext) `^0.7.14 || ^0.8.0 || ^0.9.0 || ^0.10.0` installed (the peer range of `package.json`), with a `gcf/` tree in the project — declared as a peer dependency, and `gcf-harness init` refuses when the `gcf` command is not registered
|
|
15
|
-
- Claude Code 2.1.270+ (hooks, dynamic workflows) — the only supported runtime
|
|
16
|
-
- AI Factory 2.x, Node.js ≥ 22.14
|
|
17
|
-
|
|
18
|
-
## Install
|
|
19
|
-
|
|
20
|
-
The shortest way is from the core: `ai-factory gcf init` asks whether to install the harness too, and on yes runs both steps below. It asks only in a terminal and only when the project has the Claude Code agent; `gcf init --harness` installs it without asking, `--no-harness` skips the question.
|
|
21
|
-
|
|
22
|
-
By hand, into a project that already has the core, from npm or a local checkout:
|
|
23
|
-
|
|
24
|
-
```bash
|
|
25
|
-
ai-factory extension add gcf-aif-ext # the core, if not yet installed
|
|
26
|
-
ai-factory extension add gcf-harness-aif-ext # npm
|
|
27
|
-
# ai-factory extension add ../GCF/packages/gcf-harness-aif-ext # local checkout
|
|
28
|
-
```
|
|
29
|
-
|
|
30
|
-
This installs the `gcf-run` and `gcf-run-ingest` skills and registers the `gcf-harness` command. Then initialize the harness in the project — like `gcf init`, once per project:
|
|
31
|
-
|
|
32
|
-
```bash
|
|
33
|
-
ai-factory gcf-harness init # per project: .claude/settings.json + .gitignore
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
It is **per project**, not global — run it again in every game repository: it adds the readset-guard and implement-guard entries to the project's `.claude/settings.json` (never `~/.claude`) and `.gcf-session/` to `.gitignore`. It also allows what an unattended `claude -p` run needs at least — `Edit`, `Write`, `Bash(git *)`, `Bash(ai-factory *)`, and the same two as `PowerShell(…)` rules, the tool the agent runs commands with on Windows — because print mode cannot ask and denies the rest; add your engine's tools yourself (for example `mcp__<editor-server>` for an editor driven over MCP). Commit `.claude/settings.json`: the rules apply to every Claude session in the project. It is idempotent — a re-run after moving or cloning the project repoints the hook at the new path — refuses when the `gcf` command is not registered, and refuses to rewrite a `settings.json` it cannot parse. It is a separate step for the same reason as `gcf hooks-install`: an AI Factory manifest cannot install Claude Code hooks.
|
|
37
|
-
|
|
38
|
-
## Upgrade
|
|
39
|
-
|
|
40
|
-
```bash
|
|
41
|
-
ai-factory extension update gcf-harness-aif-ext
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
Updating keeps the hook entry valid — it points into the extension's install directory, which an update refreshes in place.
|
|
45
|
-
|
|
46
|
-
0.5.0 drives work items (`gcf/work/<id>.md`, schema 3) instead of cards and requires `gcf-aif-ext` 0.4.0 — update both together; against an older core the gate refuses with `gcf-aif-ext >= 0.4.0 is required`. A project still holding schema 2 cards in `gcf/cards/` re-creates them first (see the core's "Upgrading from 0.3.x"). What changes for you: `/gcf-run` takes ids of items in `ready`; it no longer stops at `built` but ends each item with `submit`, `close` or `block`; the plan is improved in passes until it converges; the WIP cap counts only items that end waiting for a verdict.
|
|
47
|
-
|
|
48
|
-
0.5.1 is a fix release. During a run, `gcf/config.yml` is always readable, and a Grep inside `gcf/` reads only readset files. An import breaks a `depends:` cycle the pair checks closed and asks a D1 about it. It cuts a section longer than a segment at paragraphs, and lens and pair prompts carry a window around the quote. `/gcf-run` checks the plan against each pillar's invariant and asks each pillar's review question over the diff. Use it with core 0.4.1, which brings the parent feature into the readset.
|
|
49
|
-
|
|
50
|
-
0.
|
|
51
|
-
|
|
52
|
-
0.
|
|
53
|
-
|
|
54
|
-
0.12.
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
- **
|
|
58
|
-
-
|
|
59
|
-
- `
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
-
|
|
65
|
-
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
0.
|
|
70
|
-
|
|
71
|
-
0.9.
|
|
72
|
-
|
|
73
|
-
0.9.
|
|
74
|
-
|
|
75
|
-
0.9.
|
|
76
|
-
|
|
77
|
-
0.9.
|
|
78
|
-
|
|
79
|
-
0.9.
|
|
80
|
-
|
|
81
|
-
0.9.
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
- `/gcf-run
|
|
85
|
-
-
|
|
86
|
-
-
|
|
87
|
-
|
|
88
|
-
0.
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
- A
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
-
|
|
97
|
-
-
|
|
98
|
-
-
|
|
99
|
-
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
- `
|
|
105
|
-
-
|
|
106
|
-
- `
|
|
107
|
-
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
0.
|
|
112
|
-
|
|
113
|
-
0.6.
|
|
114
|
-
|
|
115
|
-
0.
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
```
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
**`ai-factory gcf-harness
|
|
132
|
-
|
|
133
|
-
**`ai-factory gcf-harness
|
|
134
|
-
|
|
135
|
-
**`ai-factory gcf-harness
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
**
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
1
|
+
# gcf-harness-aif-ext
|
|
2
|
+
|
|
3
|
+
Claude-Code-specific orchestration for the [Game Context Framework](../gcf-aif-ext). Optional: GCF works without it, by hand.
|
|
4
|
+
|
|
5
|
+
> **Claude Code only.** Codex and the other AI Factory runtimes are not supported: the harness is built on Claude Code
|
|
6
|
+
> dynamic workflows and `PreToolUse` hooks, which they do not have. AI Factory still copies the `gcf-run` skills into
|
|
7
|
+
> every runtime the project is configured for, where they do not work — on a project without Claude Code, do not
|
|
8
|
+
> install the harness. GCF itself keeps working on any runtime.
|
|
9
|
+
|
|
10
|
+
The harness turns policy-as-text into an executable pipeline. The game's state is on disk in `gcf/` and git, so a run killed at any point restarts and reaches the same state. The runs' own state is in `.gcf-session/`: the agent sessions a rerun resumes, the item worktrees with their uncommitted work, locks and logs. Losing it never breaks the game's model, but it loses those resumes, that work and the diagnosis: delete a single stale file, never the folder.
|
|
11
|
+
|
|
12
|
+
## Requirements
|
|
13
|
+
|
|
14
|
+
- [`gcf-aif-ext`](../gcf-aif-ext) `^0.7.14 || ^0.8.0 || ^0.9.0 || ^0.10.0` installed (the peer range of `package.json`), with a `gcf/` tree in the project — declared as a peer dependency, and `gcf-harness init` refuses when the `gcf` command is not registered
|
|
15
|
+
- Claude Code 2.1.270+ (hooks, dynamic workflows) — the only supported runtime
|
|
16
|
+
- AI Factory 2.x, Node.js ≥ 22.14
|
|
17
|
+
|
|
18
|
+
## Install
|
|
19
|
+
|
|
20
|
+
The shortest way is from the core: `ai-factory gcf init` asks whether to install the harness too, and on yes runs both steps below. It asks only in a terminal and only when the project has the Claude Code agent; `gcf init --harness` installs it without asking, `--no-harness` skips the question.
|
|
21
|
+
|
|
22
|
+
By hand, into a project that already has the core, from npm or a local checkout:
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
ai-factory extension add gcf-aif-ext # the core, if not yet installed
|
|
26
|
+
ai-factory extension add gcf-harness-aif-ext # npm
|
|
27
|
+
# ai-factory extension add ../GCF/packages/gcf-harness-aif-ext # local checkout
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
This installs the `gcf-run` and `gcf-run-ingest` skills and registers the `gcf-harness` command. Then initialize the harness in the project — like `gcf init`, once per project:
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
ai-factory gcf-harness init # per project: .claude/settings.json + .gitignore
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
It is **per project**, not global — run it again in every game repository: it adds the readset-guard and implement-guard entries to the project's `.claude/settings.json` (never `~/.claude`) and `.gcf-session/` to `.gitignore`. It also allows what an unattended `claude -p` run needs at least — `Edit`, `Write`, `Bash(git *)`, `Bash(ai-factory *)`, and the same two as `PowerShell(…)` rules, the tool the agent runs commands with on Windows — because print mode cannot ask and denies the rest; add your engine's tools yourself (for example `mcp__<editor-server>` for an editor driven over MCP). Commit `.claude/settings.json`: the rules apply to every Claude session in the project. It is idempotent — a re-run after moving or cloning the project repoints the hook at the new path — refuses when the `gcf` command is not registered, and refuses to rewrite a `settings.json` it cannot parse. It is a separate step for the same reason as `gcf hooks-install`: an AI Factory manifest cannot install Claude Code hooks.
|
|
37
|
+
|
|
38
|
+
## Upgrade
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
ai-factory extension update gcf-harness-aif-ext
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Updating keeps the hook entry valid — it points into the extension's install directory, which an update refreshes in place.
|
|
45
|
+
|
|
46
|
+
0.5.0 drives work items (`gcf/work/<id>.md`, schema 3) instead of cards and requires `gcf-aif-ext` 0.4.0 — update both together; against an older core the gate refuses with `gcf-aif-ext >= 0.4.0 is required`. A project still holding schema 2 cards in `gcf/cards/` re-creates them first (see the core's "Upgrading from 0.3.x"). What changes for you: `/gcf-run` takes ids of items in `ready`; it no longer stops at `built` but ends each item with `submit`, `close` or `block`; the plan is improved in passes until it converges; the WIP cap counts only items that end waiting for a verdict.
|
|
47
|
+
|
|
48
|
+
0.5.1 is a fix release. During a run, `gcf/config.yml` is always readable, and a Grep inside `gcf/` reads only readset files. An import breaks a `depends:` cycle the pair checks closed and asks a D1 about it. It cuts a section longer than a segment at paragraphs, and lens and pair prompts carry a window around the quote. `/gcf-run` checks the plan against each pillar's invariant and asks each pillar's review question over the diff. Use it with core 0.4.1, which brings the parent feature into the readset.
|
|
49
|
+
|
|
50
|
+
0.14.0 needs gcf-aif-ext 0.14.0 (docs/Base-A-Plan.md). Without `--timeout` a session's limit is `session_timeout_min` of `gcf/config.yml` (120 without it); an item without its own `model:` / `effort:` runs on the project's `agent.model` / `agent.effort` (the run's override still goes over both); `ai-factory gcf-harness gate --each [<id>…] --json` gives the gate of each named item (none: every ready one) run alone now, from one audit, `{items: {<id>: {pass, reason}}}`, exit 0: the board shows a refusal before the click. The bundled session engine offers Always for one MCP tool, marked `always_wide`.
|
|
51
|
+
|
|
52
|
+
0.13.0 keeps its past runs for the board (docs/Board-V2-Data-Plan.md) and needs gcf-aif-ext 0.13.0 for the moves' `GCF-By`. `run-log.csv` lines get six columns at their end (`run_id, started, model, effort, log_from, log_to`; older lines still read); `ai-factory gcf-harness runs [--item <id>] [--limit <n>] --json` lists the runs; `run --model <m> --effort <e>` runs every item on another model for that run only, the item unchanged; a run sets `GCF_MOVE_BY=run` for its core calls and its agents.
|
|
53
|
+
|
|
54
|
+
0.12.2 reads an item as it starts it: in a main-mode batch, an item the run has yet to reach takes a model or effort set meanwhile (`ai-factory gcf item agent`, core 0.12.3; a worktree run locks its items first). A stored `default` gives no `--model` or `--effort` flag.
|
|
55
|
+
|
|
56
|
+
0.12.0 moves the session mechanics into the bundled session engine `gcf-session` (docs/Session-Engine.md) and needs gcf-aif-ext 0.12.0: a core without neutral rules (`agent.rules`) is refused before any item is claimed. The hooks keep their files and matchers: no new `init` is needed.
|
|
57
|
+
- **The usage limit waits.** A session cut by the limit with a known reset waits for it (plus 60 s) and goes on in the same session. Before the wait its record is written (`<id>.agent.json`, `ended: limit`, `resets` as ISO), so a run killed meanwhile resumes the same session; the chat gets `limit {until}`; the wait does not count against `--timeout`; `gcf-harness stop` ends it. It does not wait for the week's limit, an unknown reset, a reset over 6 h away, an item's third limit in a run, or a lessons turn: those end `paused` as before. `--wait-limit` (a queued start from the board) also holds each session while a known reset is ahead. `--json` says `limit_wait: true`.
|
|
58
|
+
- **Owners.** The handoff flag and the readset manifest name their owner and item: the guards act only on that session, so a project chat or an interactive claude in the same folder goes on. The guards are each a neutral decision and a claude shim, with the same files and input as before.
|
|
59
|
+
- **Milestones from what the work left:** the DoD's `ok` comes from the item's row of main's `gcf/.metrics/verify-log.csv` between the call and its result (`null` with none or two), a commit's from the new HEAD; a worktree's move is main's to record.
|
|
60
|
+
- A background subagent keeps the session open with no timer and no default answer (`background`, then `working`); the context window is known from the first turn (the live `modelUsage`), and the chat shows the share during a turn (`context`).
|
|
61
|
+
- `GCF_SESSION_AGENT` puts another agent in place of `claude` (tests); `GCF_RUN_AGENT` still works.
|
|
62
|
+
|
|
63
|
+
0.11.1 reworks the chat (docs/Chat-Plan.md) and needs gcf-aif-ext 0.11.1 for its settings (an older core gives the defaults):
|
|
64
|
+
- `chat:` of `gcf/config.yml` decides who waits for whom: `ask` (`d1` by default: only the human's decisions by a question card; `all`; `none`: each card is denied, the agent decides) goes to the skill as `/gcf-run <id> --ask d1|all`; `answer_timeout_min` (15) is how long a question waits, 0 when nobody watches (then `ask` is `none`). `--chat-timeout` has no default any more: it overrides the setting for one run, 0 allowed.
|
|
65
|
+
- `ai-factory gcf-harness chat <id> say [text] [--text-file <path|->] [--image <path>]…`, `answer <request_id> [text] [--answers-file <path|->]`, `interrupt` writes the operator's input: checked (text up to 64 000 characters, up to 10 png/jpg/gif/webp pictures of 5 MB each, an answer to an open card only), never through a link, and only while a live session reads it. Exit 1: bad input; 3: no live chat session; 4: the write failed. A picture is copied into `.gcf-session/runs/<id>.att/`, not git; `chat-in.jsonl` names it by path.
|
|
66
|
+
- `<id>.chat.jsonl` adds the run's milestones from the main agent's tool calls (`step`: the plan converged with its passes, the DoD, the review subagent the skill names `gcf review`, a commit, the item's move; in a worktree the move main recorded), each session's start and end, the handoff flag, the context share at each turn's end, and an `error` for input that reached no one (a dropped card, a missing picture, a message after the item's last session).
|
|
67
|
+
- A turn whose messages the agent never echoed as read frees the session after 10 s with no new turn. After the operator's interrupt the session waits for them with no default answer, while the session's timeout runs on. A session flagged for a handoff closes at its turn's end, as without the chat: no more reminder to hand over. A card a session took with it at its end is dropped.
|
|
68
|
+
|
|
69
|
+
0.10.0 adds the chat (docs/Chat-Plan.md, stage 1): `run --chat` keeps each agent session open to the operator. The prompt goes in as the session's first stream-json message on stdin. The operator writes into `.gcf-session/runs/<id>.chat-in.jsonl`, one JSON a line: `{"type":"say","text":…,"images":[{media_type,data}]}`, `{"type":"interrupt"}` (stops the agent's step, the session stays), `{"type":"answer","request_id":…,"answers":{…}}` (a question card). What the operator reads goes to `<id>.chat.jsonl`: the agent's text, each message sent and when the agent read it, question cards and their answers, the end of each turn. A question waits `--chat-timeout` minutes (15 by default), and the session's own timeout stands still meanwhile; then the run answers: the card's recommended option, or `take your safe default, or block the item`. A turn that ends without the item's move waits the same way, once. Without `--chat` nothing changes. A session flagged for a handoff closes once it went on past its flag, and the fresh one takes the chat on; flagged on its turn's last message, it is first told to hand over. A message sent while a question card is open leaves the card its timeout. `--chat` adds `claude`'s stream-json flags to the agent's command: another `--agent` must take them. Any other tool approval the agent asks for is denied: the run's permissions decide. Checked live with `claude` (Haiku): the prompt on stdin, an interrupt, the operator's message, the item blocked, the session closed.
|
|
70
|
+
|
|
71
|
+
0.9.10 makes a main run's session marks its own (with core 0.10.2): the run sets `GCF_RUN_OWNER=run:<pid>`, its core calls and every agent session it starts (a fresh one after a handoff too) inherit it, and the core refuses the mark to anyone else. An item another session has claimed is refused with `worked by another agent session`. `/gcf-run` reports a refused claim and goes on with the next item; it never releases another session's mark, and neither does the run (`gcf-harness stop` still does: that is the human's). The readset-guard hook keeps only its own session's marks fresh (and marks that name nobody), so another session's mark expires when that session stops.
|
|
72
|
+
|
|
73
|
+
0.9.9 changes no code: its peer range adds core 0.10.0, whose board read is schema 3 and names this harness as the domain's runner (the harness reads neither).
|
|
74
|
+
|
|
75
|
+
0.9.8 changes no code: its peer range adds core 0.9.0, whose board read is schema 2 (the harness does not read it).
|
|
76
|
+
|
|
77
|
+
0.9.6 (with core 0.7.14, now the peer range): `/gcf-run-ingest` hands its workflow the sections with their bodies, gets the same delta again after a failed run and ends the import with `gcf anchor --done`; it takes the text of a changed section as `/gcf-ingest` does, and adds resources, entities and measurable constraints by the sequential pass. The workflow marks the GDD as data in every prompt and asks a lens's D2 as a D1. `/gcf-run` reads only `INDEX.md` and `config.yml` beyond the readset, hands fresh subagents the context's graveyard and D2 lines, counts a re-verify after review against `dod_attempts`, files a D1 for a design question on main, never widens the readset by a false `depends:`, and runs in Claude Code only.
|
|
78
|
+
|
|
79
|
+
0.9.5: `gcf-harness metrics` also sums the cost per item over all its runs and per day and week (`items`, `by_day`, `by_week` in `--json`, a `weeks:` line in the text); `gcf-board` 0.2.18 shows them in its Metrics tab. A resumed session's cost no longer counts twice: `claude` reports a resumed session's whole dollar total, so the lessons turn and a rerun after a limit or a cut now count from what the session had already spent (it is kept in `<id>.agent.json`); before, a lessons turn added its session's cost again. The `done in …` line of the log still shows claude's own figure. A core refusal reads as its whole message: a failed `git worktree add` names its cause, not only git's first line.
|
|
80
|
+
|
|
81
|
+
0.9.4 keeps run metrics (Harness-PRD §11) and adds `ai-factory gcf-harness metrics`. Use it with core 0.7.13, which logs the plan checks and the DoD attempts, and refuses `close` and `submit` without a green `gcf verify` of the code as it is. `/gcf-run` runs the verify again after a review fix; implement-guard refuses `gcf close` or `gcf submit` with `--unverified` in a `/gcf-run` session, since a move past the DoD gate is the human's call. A main-mode item whose move went past it anyway (the commit says `(unverified: …)`) reads `— moved without a green gcf verify` on its report line, and `gcf-harness metrics` counts such moves.
|
|
82
|
+
|
|
83
|
+
0.9.2 holds `/gcf-run` to aif-implement. Run `ai-factory gcf-harness init` again after the update: it registers the new hook.
|
|
84
|
+
- The implement guard: in a session that runs `/gcf-run`, a write to a code file is denied until the session invokes the aif-implement skill (gcf-run step 13), and so is a plan tick, which only aif-implement sets. Planning stays free: `gcf/`, `.ai-factory/`, `.gcf-session/` and any markdown file. After aif-implement every write is free, the fixes of a red DoD and of the review included. It works in the harness's runs and in an interactive `/gcf-run` alike, and touches no other session.
|
|
85
|
+
- `/gcf-run` converges a plan when an improve pass finds nothing blocking: a wrong or missing behavior or task, a broken pillar invariant, a rule conflict, a task no check can prove. Polish (wording, splitting tasks, order) is applied, but no longer keeps the loop going. Before, a pass that changed any task asked for one more, and a fresh reviewer almost always changes something. The report row per pass gives the blocking and polish counts.
|
|
86
|
+
- `/gcf-run` answers aif-plan's own questions (tests, logging, docs) itself, from the item, its DoD and the project's rules.
|
|
87
|
+
- The run report marks an item whose session wrote code without aif-implement: `— code written outside aif-implement` on its line, `process` in `--json` and in its kept record. It reads the session's own events, its subagents' included, so it also covers a project without the guard registered. A write through Bash is seen by neither: the review of the diff is the check there.
|
|
88
|
+
- Lessons (with core 0.7.10): after each agent session the run asks the same session, resumed, what got in its way - tools, rules, the framework, the project template - with the questions of `ai-factory gcf lessons prompt`. Its answers go to the inbox on main as lessons (`gcf lessons add`), and the board shows them on the card, in the drawer and in the inbox. The run passes `--no-lessons` to `/gcf-run`, so the agent carries no lessons instruction while it works. The turn follows a result, a handoff (before the fresh session), a timeout or an error; not a usage limit or a stop, and only for a `claude` agent with a session id. Another agent asks its lessons itself at the end of a run on main; in a worktree it records none. It takes up to 10 minutes; its cost goes on the item, and the report line says `, N lessons`. A failed lessons turn is logged and changes nothing else. A project that turns lessons off, or a core before 0.7.10, gets no turn and no flag.
|
|
89
|
+
|
|
90
|
+
0.9.1 is a fix release:
|
|
91
|
+
- A stopped session reads as `no result (stopped)`, and its kept record as `ended: stopped`: before, the kill's exit code (`agent exit 1` on Windows).
|
|
92
|
+
- `gcf-harness stop <id>` never kills the run: a stop before the item's session starts (or between two sessions of a handoff) leaves `.gcf-session/runs/<id>.stop`, and that session is stopped as it starts. Before, a stop then killed the whole run with the other items of its batch. A run hung before its first session (in its worktree setup) is not stopped. On main, a stop marks the item too once the run has reached it. Known limit: a stop in the moment between a worktree run's claim of the item and its clearing of an old mark is lost.
|
|
93
|
+
- A stop that comes while the session starts no longer misses it.
|
|
94
|
+
|
|
95
|
+
0.9.0, to update together with core 0.7.6:
|
|
96
|
+
- 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>`.
|
|
97
|
+
- 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.
|
|
98
|
+
- 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. The sessions of an item share one timeout, and their costs add up; `--json` gives `handoffs`.
|
|
99
|
+
- `auto_compact_pct` sets the agent's `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`, at least 15 points above the handoff share.
|
|
100
|
+
- The readset-guard reads the manifest of the directory the session started in (`CLAUDE_PROJECT_DIR`): an agent's `cd` no longer lifts the readset.
|
|
101
|
+
- `/gcf-run` writes a plan task's code through aif-implement, so the plan ticks show the item's progress, and answers aif-implement's questions itself: no commit, stash or merge.
|
|
102
|
+
|
|
103
|
+
0.8.0, to update together with core 0.7.0:
|
|
104
|
+
- `run_mode: main` in `gcf/config.yml` (or `run --mode main`): items run one after another in the main checkout, for an agent that works through an editor bound to the project folder. The item carries the core's session mark (`gcf claim`), not a run lock, so the agent records its own move; one run works the checkout at a time (`.gcf-session/runs/.main-run.lock`).
|
|
105
|
+
- `gcf-harness next [N] --json`: the ready items that can run together now, by priority; each is taken while the batch with it passes the gate.
|
|
106
|
+
- `gcf-harness stop <id>`: stops the session that works the item (its run lock names it); the run records no result for it and goes on with the rest. The item stays ready and its work is kept. Known limit: the session is killed at once, so a `gcf` move it was in the middle of may leave `.gcf-session/main.lock` behind (taken over once its pid is gone).
|
|
107
|
+
- A run on main refreshes its item's mark every 5 minutes, and the readset-guard hook refreshes live marks on each read: a long build without a gcf command does not expire it.
|
|
108
|
+
- `run` refuses an id that is not a slug before it names a lock file or builds the agent's command line.
|
|
109
|
+
- The gate lets a session through for the item its own run marked (`GCF_RUN_ITEM`); `/gcf-run` outside a worktree claims each item after its gate and releases one it leaves without a move.
|
|
110
|
+
|
|
111
|
+
0.7.0, to update together with core 0.6.0: an item's `model:` and `effort:` (`gcf item new --model <m> --effort <e>`) go to its agent as `--model <m> --effort <e>`, read from `gcf board --json`; a value that is not one plain word fails that item and starts no session. `--timeout <minutes>` (120 by default) stops a session that runs longer, with every process it started; its item stays ready, and its run lock is freed. The gate counts the items other runs drive now: their places under the WIP limit, and their systems — a board starts one run per click. Requires `gcf-aif-ext` 0.6.
|
|
112
|
+
|
|
113
|
+
0.6.1 is a fix release, to update together with core 0.5.3. The run lock `.gcf-session/runs/<id>.lock` is created exclusively, and a lock left by a dead run is taken over; while it is live, the gate refuses the item to another run and the core refuses any move on it, `/gcf-run` on main included. A session whose log cannot open ends as an error and releases its claim.
|
|
114
|
+
|
|
115
|
+
0.6.0 adds `ai-factory gcf-harness run` (a batch at once, a worktree and an agent session per item, then the integrator) and the `--worktree` mode of `/gcf-run`, whose session ritual now integrates the verified branches a dead run left. It requires `gcf-aif-ext` 0.5.0 (`gcf worktree`, `gcf integrate`, `gcf verify`) — update both together and run `ai-factory gcf init`. The DoD of `/gcf-run` is `ai-factory gcf verify <id>`, and the item's `live:` delta is written before it.
|
|
116
|
+
|
|
117
|
+
0.4.1 is a patch release. `/gcf-run` now commits the implementation first, then flips the card to `built` in a second commit, with `built_at` set to the implementation commit's hash. Update the core to 0.3.1 together with the harness: without it, an audit run before a verdict makes the pre-commit gate refuse that verdict.
|
|
118
|
+
|
|
119
|
+
To remove the extension:
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
ai-factory extension remove gcf-harness-aif-ext
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
Removal does not touch `.claude/settings.json`: delete the entries whose command ends in `# gcf-readset-guard` or `# gcf-implement-guard` (under `PreToolUse` and `UserPromptSubmit`) by hand, or the tools they match will report a hook error.
|
|
126
|
+
|
|
127
|
+
## What it adds
|
|
128
|
+
|
|
129
|
+
**`/gcf-run <item-id…>`** — drives work items through plan, implementation and DoD, with every gate checked *before* the tokens are spent: the audit ritual, the gate below, the context budget. The plan is written by `aif-plan`, then improved in passes, each by a fresh subagent that reads only the plan and the readset and records every default it picks; `ai-factory gcf plan check <id>` runs after each pass, and a pass with no blocking finding (a wrong or missing behavior or task, a broken pillar invariant, a rule conflict, an unprovable task) ends the loop. A blocking finding left after `plan_passes` passes (3 by default), or a question only the human can answer (a save format, a public API, a new dependency, a pillar conflict), blocks the item before any code is written. The DoD is `ai-factory gcf verify <id>` — the gate's checks, the item's `live:` delta, and the project's `dod.build` and `dod.test` commands from `gcf/config.yml` — plus a review by a fresh subagent, up to `dod_attempts` attempts. Every item ends in a state the core records: `gcf submit` (gate `verdict` or `decision` — waits for the human), `gcf close` (gate `auto` — done, or a soft unit closed as `unplayed`) or `gcf block` with the reason. The verdict and the decision belong to the human: the pipeline stops at `submit` and prints the playtest list.
|
|
130
|
+
|
|
131
|
+
**`ai-factory gcf-harness gate <item-id…>`** — the `/gcf-run` gate as code (`--each`: each item alone, see 0.14.0 above). It reads one `gcf audit --json` report and exits 1 with a one-line reason when the items may not go: a core older than 0.4.0, a `schema:` other than 1 in `gcf/config.yml`, an id with no work item, a feature (run its children; the feature closes when they are finished), an item that is not `ready`, an unplayed dependency, no WIP room for the batch (items awaiting a verdict + the batch's `gate: verdict` items over `wip_built_limit`), or two items of the batch touching the same system unless both say `parallel: ok`. The tune limit is not a gate rule: `verdict tune` itself refuses at the limit, and an item tuned up to it still gets its last build. The skill runs it and stops on a non-zero exit — no model compares the numbers.
|
|
132
|
+
|
|
133
|
+
**`ai-factory gcf-harness run <item-id…> [--agent "<cmd>"]`** — runs a batch at once, each item in its own worktree (`gcf worktree <id>`) with its own agent session: `claude -p --output-format stream-json --verbose "/gcf-run <id> --worktree"` by default, or the command in `--agent` / `GCF_RUN_AGENT`. The sessions run unattended, so set the agent's permissions for print mode first. A session ends with a commit and `gcf verify <id> --mark` (the `GCF-Verified` trailer); a question for the human goes into `.gcf-session/outcome.json` in its worktree, and `run` records the block on main. Then `gcf integrate` merges the verified branches and records each move, and `run` prints the playtest session. Its first step, like `/gcf-run`'s, integrates the verified branches a dead run left. A session that ended with no result leaves its item `ready`; the next `run` resumes its worktree and the agent's own session (`--resume <session_id>`, kept in `.gcf-session/runs/<id>.agent.json`), in either run mode; `--fresh` starts a new session instead. A session cut off by Claude's usage limit reports `paused (usage limit, resets 3am (…))` and `limit_resets`. Logs: `.gcf-session/runs/<id>.log`, written as the session works: a `start:` line, then one stamped line per agent message, tool call (`tool: Edit <file>`, `tool: Bash <command>`) and failed tool result, and at the end the agent's final text and `done in 34m, 212 turns, $3.41 (…tokens)`; stderr goes in as it is, and a non-Claude `--agent` keeps its own lines. With `--json`, each item carries the session's `cost_usd`, `tokens`, `turns` and `duration_ms` when the agent reported them, what it ran on (`model`, `effort`; null: the agent's own) and `log: {from, to}`, the bytes of its log this run wrote. `--model <m>` and `--effort <e>` set the model and effort of every item for this run only, over the item's own `model:` and `effort:` (`default` or none: the item's); the item file is not changed. A run sets `GCF_MOVE_BY=run` for its core calls and every agent it starts, in either mode, so the core's moves name the run as their maker. One run drives an item at a time (`.gcf-session/runs/<id>.lock`), and a resumed worktree first gets main merged in, so the answer from an `unblock` reaches the session. A worktree sees only what is committed: keep `.ai-factory.json`, the installed extensions with their `node_modules` (a `node_modules/` line in `.gitignore` drops the core's `yaml` and `cnlp-kit`, and `ai-factory gcf` fails in the worktree) and `.claude/` (skills, the readset-guard hook) in git, or the session has no `/gcf-run` and no `ai-factory gcf`. On Windows a project in a deep folder needs `git config core.longpaths true`, or `git worktree add` fails on `Filename too long`.
|
|
134
|
+
|
|
135
|
+
**`ai-factory gcf-harness metrics [--since <date>] [--json]`** — the run metrics of Harness-PRD §11 from `gcf/.metrics`: how many item runs reached `submit` or `close` (a run the usage limit paused or a session cut short does not count as finished), the block reasons, what the runs cost (dollars, minutes, turns, handoffs, code written outside aif-implement), the plan checks per item (the improve passes), the DoD attempts per item and the checks that failed them, and the guard firings by hook and by item. The logs: `run-log.csv` (one line per item of each `run`: `at, item, mode, result, reason, cost_usd, input, output, cache_read, turns, duration_ms, handoffs, process, run_id, started, model, effort, log_from, log_to`; `result` is `submit`, `close`, `block`, `error`, `conflict`, `skipped`, `paused` for the usage limit, `no-result` for a session cut short, `not-started`; `run_id` is `<started>-<pid>` of the run; `model` and `effort` what the item ran on, empty for the agent's own; `log_from`, `log_to` the bytes of `.gcf-session/runs/<id>.log` this run wrote; older lines end at `process`), `guard-log.csv` (each denial of readset-guard and implement-guard, by hook: `readset`, `implement`, or `verify` for a move past the verify gate), and the core's `plan-log.csv` and `verify-log.csv`. A worktree session's lines go to the main checkout's logs; the next `gcf integrate` commits them.
|
|
136
|
+
|
|
137
|
+
**`ai-factory gcf-harness runs [--item <id>] [--limit <n>] [--json]`** — the past runs in `run-log.csv`, the latest first, at most `--limit` (50 by default); `--item` keeps the runs that hold that item. `--json` gives `{runs: [{id, started, ended, mode, cost_usd, items: [{id, result, reason, cost_usd, tokens: {input, output, cache_read}, turns, duration_ms, handoffs, process, model, effort, log: {from, to} | null}]}]}`. A run's lines share its `run_id`; a line older than it is grouped by its `at` (all lines of one run share it), with `id` and `started` null and `log` null (the whole log). Known limits: two such older runs that ended in the same millisecond read as one; a reason's commas read as `;` (the csv turns them so). A run that fails as a whole (its gate refused it, an error of `run` itself) or whose process was killed leaves no lines, so it is not listed. A stop (`gcf-harness stop`, the board's Stop) ends only the item's session: the run writes its line, `no-result` with reason `stopped`; a stop while the session waits for the usage limit's reset writes `paused` with `usage limit; resets <when>; stopped during the wait`.
|
|
138
|
+
|
|
139
|
+
**`/gcf-run-ingest <gdd.md>`** — imports a design document as a fan-out workflow: parallel aspect extraction, provenance verified by code rather than by an agent (a quote either is a verbatim substring of its section or it is not), completeness lenses per candidate, and an interaction matrix computed from the candidates that write the same state.
|
|
140
|
+
|
|
141
|
+
**readset-guard** — a `PreToolUse` hook on Read/Grep/Glob. While a run manifest exists at `.gcf-session/readset.json`, a path inside `gcf/` that is not in the readset is denied, and so is a Grep from the project root (no `path`, or a `path` above `gcf/`) unless its `glob` starts with a literal directory other than `gcf` (`src/**`, not `**/*.md`), because such a content search would read the whole tree past the gate. Glob and Greps scoped to the game code are never restricted. No manifest means no restriction: manual work is never gated. An honest limit — `cat` through Bash still bypasses it. This is a discipline tool, not a security perimeter.
|
|
142
|
+
|
|
143
|
+
**implement-guard** — a `UserPromptSubmit` and `PreToolUse` hook (Skill, the write tools, Bash and PowerShell). A session that starts `/gcf-run` (typed, passed to `claude -p`, or invoked as a skill) gets a state in `.gcf-session/guard/<session_id>.json`; until it invokes the aif-implement skill, Edit, Write, MultiEdit and NotebookEdit are denied outside `gcf/`, `.ai-factory/`, `.gcf-session/` and markdown, and a markdown write that adds a `- [x]` tick is denied too. Any other session is never touched, and an error lets the call through. A `gcf submit` or `gcf close` with `--unverified` is refused in such a session, after its end move too (a close the core refused does not free it for a skip): only the human moves an item past the DoD gate, from a terminal of their own. Such a refusal is logged with the hook name `verify`. The move that ends the item (`gcf block`, `submit` or `close`, through Bash or PowerShell) lets the session go, so the operator's own edits after a blocked run are free again. A plugin's skill (`<plugin>:aif-implement`) counts too. Limits: the flag is per session, so in a batch the first item's aif-implement frees the rest; a write through Bash is not seen, by the run report either.
|
|
144
|
+
|
|
145
|
+
## Docs
|
|
146
|
+
|
|
147
|
+
[Harness-PRD](https://github.com/VirtualMaestro/GCF/blob/main/docs/Harness-PRD.md) is the spec: pipeline stages, gates, execution surfaces, the guard's contract.
|
|
148
|
+
|
|
149
|
+
## License
|
|
150
|
+
|
|
151
|
+
MIT
|
package/commands/harness.js
CHANGED
|
@@ -323,7 +323,41 @@ async function init(program) {
|
|
|
323
323
|
await ignoreSession(projectDir);
|
|
324
324
|
}
|
|
325
325
|
|
|
326
|
+
/**
|
|
327
|
+
* The gate of each item run alone now, from one report: the named ones, or every ready item
|
|
328
|
+
* (Board-PRD §5.3: a board shows a refusal before the click). A batch of several is still gated
|
|
329
|
+
* when it starts: two items of one subsystem pass alone.
|
|
330
|
+
*/
|
|
331
|
+
export function gateEach(report, ids) {
|
|
332
|
+
const named = ids.length
|
|
333
|
+
? ids
|
|
334
|
+
: (report.items ?? [])
|
|
335
|
+
.filter((i) => i.status === 'ready' && !i.running && i.type !== 'feature')
|
|
336
|
+
.map((i) => i.id);
|
|
337
|
+
|
|
338
|
+
return { items: Object.fromEntries(named.map((id) => [id, gate(report, [id])])) };
|
|
339
|
+
}
|
|
340
|
+
|
|
326
341
|
function runGate(ids, opts) {
|
|
342
|
+
if (opts.each) {
|
|
343
|
+
const result = gateEach(auditReport(), [...new Set(ids)]);
|
|
344
|
+
if (opts.json) console.log(JSON.stringify(result));
|
|
345
|
+
else
|
|
346
|
+
for (const [id, v] of Object.entries(result.items))
|
|
347
|
+
console.log(v.pass ? `${id}: pass` : `${id}: ${v.reason}`);
|
|
348
|
+
|
|
349
|
+
return;
|
|
350
|
+
}
|
|
351
|
+
|
|
352
|
+
if (!ids.length) {
|
|
353
|
+
const reason = 'name the items to gate, or --each for every ready one';
|
|
354
|
+
if (opts.json) console.log(JSON.stringify({ pass: false, reason }));
|
|
355
|
+
console.error(`gcf gate: ${reason}`);
|
|
356
|
+
process.exitCode = 1;
|
|
357
|
+
|
|
358
|
+
return;
|
|
359
|
+
}
|
|
360
|
+
|
|
327
361
|
const result = gate(auditReport(), [...new Set(ids)]);
|
|
328
362
|
if (opts.json) console.log(JSON.stringify(result));
|
|
329
363
|
else if (result.pass) console.log('gate: pass');
|
|
@@ -345,9 +379,14 @@ export function register(program) {
|
|
|
345
379
|
.action(() => init(program));
|
|
346
380
|
|
|
347
381
|
harness
|
|
348
|
-
.command('gate
|
|
382
|
+
.command('gate [ids...]')
|
|
349
383
|
.description('Gate work items before the paid stages of /gcf-run: exit 1 with the reason')
|
|
350
384
|
.option('--json', 'machine output: {pass, reason}')
|
|
385
|
+
.option(
|
|
386
|
+
'--each',
|
|
387
|
+
'gate each item alone (the named ones, else every ready one); exit 0, ' +
|
|
388
|
+
'machine output {items: {<id>: {pass, reason}}}',
|
|
389
|
+
)
|
|
351
390
|
.action(runGate);
|
|
352
391
|
|
|
353
392
|
registerRun(harness);
|
|
@@ -392,8 +431,8 @@ function registerRun(harness) {
|
|
|
392
431
|
)
|
|
393
432
|
.option(
|
|
394
433
|
'--timeout <minutes>',
|
|
395
|
-
'stop a session that runs longer; its item stays ready'
|
|
396
|
-
|
|
434
|
+
'stop a session that runs longer; its item stays ready (default: session_timeout_min of ' +
|
|
435
|
+
`gcf/config.yml, else ${DEFAULT_TIMEOUT_MIN})`,
|
|
397
436
|
)
|
|
398
437
|
.option('--mode <mode>', 'worktree | main (default: run_mode of gcf/config.yml)')
|
|
399
438
|
.option('--fresh', 'start new agent sessions: an interrupted one is not resumed')
|
|
@@ -530,8 +569,9 @@ const failed = (r) =>
|
|
|
530
569
|
|
|
531
570
|
async function runItems(ids, opts) {
|
|
532
571
|
try {
|
|
533
|
-
const minutes = Number(opts.timeout);
|
|
534
|
-
if (
|
|
572
|
+
const minutes = opts.timeout === undefined ? undefined : Number(opts.timeout);
|
|
573
|
+
if (minutes !== undefined && !(minutes > 0))
|
|
574
|
+
throw new Error('--timeout is a number of minutes above 0');
|
|
535
575
|
if (opts.mode && !['worktree', 'main'].includes(opts.mode))
|
|
536
576
|
throw new Error('--mode is worktree or main');
|
|
537
577
|
const answer = opts.chatTimeout === undefined ? null : Number(opts.chatTimeout);
|
|
@@ -542,7 +582,7 @@ async function runItems(ids, opts) {
|
|
|
542
582
|
const r = await run(realpathSync.native(process.cwd()), [...new Set(ids)], {
|
|
543
583
|
agent: opts.agent,
|
|
544
584
|
gate: (batch) => gate(auditReport(), batch),
|
|
545
|
-
timeoutMs: minutes * 60_000,
|
|
585
|
+
timeoutMs: minutes === undefined ? undefined : minutes * 60_000,
|
|
546
586
|
mode: opts.mode,
|
|
547
587
|
fresh: Boolean(opts.fresh),
|
|
548
588
|
waitLimit: Boolean(opts.waitLimit),
|
package/commands/run.js
CHANGED
|
@@ -107,18 +107,21 @@ const RUN_WORD = /^[A-Za-z0-9][\w.-]*$/;
|
|
|
107
107
|
|
|
108
108
|
/**
|
|
109
109
|
* What one item runs on: the run's override (`run --model|--effort`, this run only) over the
|
|
110
|
-
* item's own `model:` and `effort
|
|
111
|
-
*
|
|
112
|
-
*
|
|
110
|
+
* item's own `model:` and `effort:`, over the project's (`agent.model|effort` of
|
|
111
|
+
* gcf/config.yml); null or `default` at one level falls to the next, none at all leaves it to
|
|
112
|
+
* the agent. The values go into a
|
|
113
|
+
* shell command, and an item file can be edited by hand: a value that is not one plain word is
|
|
114
|
+
* refused.
|
|
113
115
|
* @param {any} item
|
|
114
116
|
* @param {{model?: string | null, effort?: string | null}} [override]
|
|
117
|
+
* @param {{model?: string | null, effort?: string | null}} [project]
|
|
115
118
|
*/
|
|
116
|
-
export function choiceOf(item, override = {}) {
|
|
119
|
+
export function choiceOf(item, override = {}, project = {}) {
|
|
117
120
|
const set = (v) => (v === null || v === undefined || v === 'default' ? null : String(v));
|
|
118
121
|
/** @type {{model: string | null, effort: string | null}} */
|
|
119
122
|
const out = { model: null, effort: null };
|
|
120
123
|
for (const k of /** @type {const} */ (['model', 'effort'])) {
|
|
121
|
-
const v = set(override?.[k]) ?? set(item?.[k]);
|
|
124
|
+
const v = set(override?.[k]) ?? set(item?.[k]) ?? set(project?.[k]);
|
|
122
125
|
if (v !== null && !RUN_WORD.test(v)) throw new Error(`${k}: ${v} is not one plain word`);
|
|
123
126
|
out[k] = v;
|
|
124
127
|
}
|
|
@@ -132,9 +135,10 @@ export function choiceOf(item, override = {}) {
|
|
|
132
135
|
* @param {string} agent
|
|
133
136
|
* @param {any} item
|
|
134
137
|
* @param {{model?: string | null, effort?: string | null}} [override]
|
|
138
|
+
* @param {{model?: string | null, effort?: string | null}} [project]
|
|
135
139
|
*/
|
|
136
|
-
export function agentFor(agent, item, override = {}) {
|
|
137
|
-
const flags = Object.entries(choiceOf(item, override))
|
|
140
|
+
export function agentFor(agent, item, override = {}, project = {}) {
|
|
141
|
+
const flags = Object.entries(choiceOf(item, override, project))
|
|
138
142
|
.filter(([, v]) => v !== null)
|
|
139
143
|
.map(([k, v]) => `--${k} ${v}`);
|
|
140
144
|
|
|
@@ -1064,28 +1068,33 @@ async function runWorktrees(claims, ctx) {
|
|
|
1064
1068
|
|
|
1065
1069
|
/**
|
|
1066
1070
|
* The agent command of each item and what it runs on (`{agent, choice}`), the run's override
|
|
1067
|
-
* over the item's own: `agentOf` (main) reads the
|
|
1068
|
-
* items take a model or effort set meanwhile (`gcf item agent
|
|
1069
|
-
*
|
|
1071
|
+
* over the item's own over the project's: `agentOf` (main) reads the board as each item starts,
|
|
1072
|
+
* so a main run's later items take a model or effort set meanwhile (`gcf item agent`,
|
|
1073
|
+
* `gcf config set agent.model`), and a board that cannot be read leaves the run's first read;
|
|
1074
|
+
* `agentFirst` (worktree) takes the run's first read.
|
|
1070
1075
|
*/
|
|
1071
1076
|
function commandsOf(core, agent, board, override) {
|
|
1072
1077
|
const itemOf = (items, id) => (items ?? []).find((i) => i.id === id);
|
|
1073
|
-
const commandOf = (
|
|
1074
|
-
|
|
1075
|
-
|
|
1076
|
-
|
|
1078
|
+
const commandOf = (b, id) => {
|
|
1079
|
+
const item = itemOf(b.items, id);
|
|
1080
|
+
|
|
1081
|
+
return {
|
|
1082
|
+
agent: agentFor(agent, item, override, b.agent),
|
|
1083
|
+
choice: choiceOf(item, override, b.agent),
|
|
1084
|
+
};
|
|
1085
|
+
};
|
|
1077
1086
|
const agentOf = async (id) => {
|
|
1078
1087
|
let now = null;
|
|
1079
1088
|
try {
|
|
1080
|
-
now =
|
|
1089
|
+
now = json(await core(['board', '--json']), 'board');
|
|
1081
1090
|
} catch {
|
|
1082
1091
|
// The first read below.
|
|
1083
1092
|
}
|
|
1084
1093
|
|
|
1085
|
-
return commandOf(now
|
|
1094
|
+
return commandOf(now && itemOf(now.items, id) ? now : board, id);
|
|
1086
1095
|
};
|
|
1087
1096
|
|
|
1088
|
-
return { agentOf, agentFirst: (id) => commandOf(
|
|
1097
|
+
return { agentOf, agentFirst: (id) => commandOf(board, id) };
|
|
1089
1098
|
}
|
|
1090
1099
|
|
|
1091
1100
|
/** The mode a run takes: the one asked for, else the project's. */
|
|
@@ -1119,7 +1128,8 @@ async function runBatch(
|
|
|
1119
1128
|
core = cliCore(projectDir),
|
|
1120
1129
|
agent = DEFAULT_AGENT,
|
|
1121
1130
|
gate,
|
|
1122
|
-
|
|
1131
|
+
// None: `session_timeout_min` of gcf/config.yml, else DEFAULT_TIMEOUT_MIN.
|
|
1132
|
+
timeoutMs = undefined,
|
|
1123
1133
|
mode = undefined,
|
|
1124
1134
|
fresh = false,
|
|
1125
1135
|
// A queued start: each session first waits while the usage limit's reset is ahead (AD-19).
|
|
@@ -1147,6 +1157,7 @@ async function runBatch(
|
|
|
1147
1157
|
await mkdir(logs, { recursive: true });
|
|
1148
1158
|
const board = json(await core(['board', '--json']), 'board');
|
|
1149
1159
|
const runMode = modeOf(mode, board);
|
|
1160
|
+
timeoutMs ??= (board.session_timeout_min ?? DEFAULT_TIMEOUT_MIN) * 60_000;
|
|
1150
1161
|
// Before any item is claimed: a refusal here leaves no lock behind.
|
|
1151
1162
|
const launch = await launchOf(logs, managed, board, chat);
|
|
1152
1163
|
// The gate counts the items other runs hold locks on, so this run's locks go in with its gate.
|
package/extension.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://raw.githubusercontent.com/lee-to/ai-factory/2.x/schemas/extension.schema.json",
|
|
3
3
|
"name": "gcf-harness-aif-ext",
|
|
4
|
-
"version": "0.
|
|
4
|
+
"version": "0.14.0",
|
|
5
5
|
"description": "GCF orchestration harness for Claude Code: one-command card pipeline, readset guard",
|
|
6
6
|
"skills": [
|
|
7
7
|
"skills/gcf-run",
|
|
@@ -260,24 +260,32 @@ function requested(e) {
|
|
|
260
260
|
input,
|
|
261
261
|
title: String(title),
|
|
262
262
|
reason: typeof e.request.description === 'string' ? e.request.description : null,
|
|
263
|
-
|
|
263
|
+
...alwaysOf(e.request.permission_suggestions),
|
|
264
264
|
},
|
|
265
265
|
];
|
|
266
266
|
}
|
|
267
267
|
|
|
268
|
+
// One tool of one MCP server, as claude names it (letters, digits, - and _): it suggests it
|
|
269
|
+
// bare, with no content to narrow it.
|
|
270
|
+
const MCP_TOOL = /^mcp__[A-Za-z0-9-][\w-]*__[A-Za-z0-9-][\w-]*$/;
|
|
271
|
+
|
|
268
272
|
/**
|
|
269
273
|
* The rule "always" would save (AD-2): claude's suggestion of an allow rule for the local
|
|
270
|
-
* settings, as `Tool(content)`; null for none,
|
|
274
|
+
* settings, as `Tool(content)`; `always: null` for none, a bare `*`, or a bare tool, which is too
|
|
275
|
+
* wide, except one tool of an MCP server: the operator sees its name and decides, and the card
|
|
276
|
+
* says it holds for any arguments (`always_wide`).
|
|
271
277
|
*/
|
|
272
278
|
function alwaysOf(suggestions) {
|
|
273
279
|
const add = (Array.isArray(suggestions) ? suggestions : []).find(
|
|
274
280
|
(s) => s?.type === 'addRules' && s.behavior === 'allow' && s.destination === 'localSettings',
|
|
275
281
|
);
|
|
276
282
|
const r = add?.rules?.[0];
|
|
283
|
+
const tool = typeof r?.toolName === 'string' ? r.toolName : '';
|
|
277
284
|
const content = typeof r?.ruleContent === 'string' ? r.ruleContent.trim() : '';
|
|
278
|
-
if (
|
|
285
|
+
if (!tool || /^\*+$/.test(content)) return { always: null };
|
|
286
|
+
if (!content) return MCP_TOOL.test(tool) ? { always: tool, always_wide: true } : { always: null };
|
|
279
287
|
|
|
280
|
-
return `${
|
|
288
|
+
return { always: `${tool}(${content})` };
|
|
281
289
|
}
|
|
282
290
|
|
|
283
291
|
/** @returns {Neutral[]} */
|
|
@@ -624,6 +624,8 @@ function permit(c, e) {
|
|
|
624
624
|
title: e.title,
|
|
625
625
|
...(e.reason ? { reason: e.reason } : {}),
|
|
626
626
|
...(always ? { always } : {}),
|
|
627
|
+
// The rule holds for any arguments of the tool: the card says so before Always.
|
|
628
|
+
...(always && e.always_wide ? { always_wide: true } : {}),
|
|
627
629
|
});
|
|
628
630
|
waitCards(c);
|
|
629
631
|
}
|
|
@@ -109,12 +109,14 @@ const pickFile = (td) => path.join(td, 'agent.json');
|
|
|
109
109
|
const wordOf = (v) =>
|
|
110
110
|
typeof v === 'string' && v !== AGENT_DEFAULT && PICK_WORD.test(v) ? v : null;
|
|
111
111
|
|
|
112
|
+
/** The plain words of a pick, `{model?, effort?}`; a bad word left out. */
|
|
113
|
+
const wordsOf = (v) =>
|
|
114
|
+
Object.fromEntries(PICKS.flatMap((k) => (wordOf(v?.[k]) ? [[k, v[k]]] : [])));
|
|
115
|
+
|
|
112
116
|
/** What `agent.json` of folder `td` picks, `{model?, effort?}`; a hand edit's bad word left out. */
|
|
113
117
|
function pickIn(td) {
|
|
114
118
|
try {
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
return Object.fromEntries(PICKS.flatMap((k) => (wordOf(v?.[k]) ? [[k, v[k]]] : [])));
|
|
119
|
+
return wordsOf(JSON.parse(readFileSync(pickFile(td), 'utf8')));
|
|
118
120
|
} catch {
|
|
119
121
|
return {};
|
|
120
122
|
}
|
|
@@ -341,8 +343,8 @@ function flagsOf({ dir, td, spec, adapter }, settings) {
|
|
|
341
343
|
* Run thread `t` of project `dir` until its session idles out, is stopped, or ends: a job of
|
|
342
344
|
* sessions (AD-41), each resumed from the one before, a fresh one after a handoff (AD-42).
|
|
343
345
|
* `spec` (its `spec.json`): `agent`, `rules` `{deny, ask, allow}`, `mcp` (config files),
|
|
344
|
-
* `answerMin`, `handoffPct`, `window`, `skill`, `mainLock`, `timeoutMin
|
|
345
|
-
* operator stopped it.
|
|
346
|
+
* `answerMin`, `handoffPct`, `window`, `skill`, `mainLock`, `timeoutMin`, `pick` (the project's
|
|
347
|
+
* model and effort, under the thread's own). `stopped()` says the operator stopped it.
|
|
346
348
|
* @param {{stopped?: () => boolean}} [opts]
|
|
347
349
|
*/
|
|
348
350
|
export async function runThread(dir, t, spec, opts = {}) {
|
|
@@ -578,7 +580,8 @@ function jobOf(s, record) {
|
|
|
578
580
|
prompt: (kind, _caps, rec) => (rec?.ended === 'limit' ? AFTER_LIMIT : null),
|
|
579
581
|
// The flags come before the chat of each session (job.js): the chat says what they picked.
|
|
580
582
|
flags: (kind) => {
|
|
581
|
-
s.pick
|
|
583
|
+
// The thread's own pick over the project's (`spec.pick`, as the thread's agent started).
|
|
584
|
+
s.pick = { ...wordsOf(spec.pick), ...pickIn(s.td) };
|
|
582
585
|
|
|
583
586
|
return s.flags(kind, s.summary, s.pick);
|
|
584
587
|
},
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "gcf-session",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.14.0",
|
|
4
4
|
"private": true,
|
|
5
5
|
"description": "The session engine of GCF: one agent session and a run as a chain of them, the chat protocol, the provider adapters. Bundled by gcf-harness-aif-ext and gcf-board, never published.",
|
|
6
6
|
"type": "module",
|
|
@@ -71,6 +71,8 @@ export type ChatEvent = At &
|
|
|
71
71
|
title: string;
|
|
72
72
|
reason?: string;
|
|
73
73
|
always?: string;
|
|
74
|
+
/** `always` holds for any arguments of the tool (one MCP tool, bare). */
|
|
75
|
+
always_wide?: boolean;
|
|
74
76
|
}
|
|
75
77
|
| { type: 'allowed'; request_id: string; by: 'operator'; always: boolean; rule?: string }
|
|
76
78
|
| {
|
|
@@ -150,6 +152,8 @@ export interface ThreadSpec {
|
|
|
150
152
|
skill?: string;
|
|
151
153
|
mainLock?: string | null;
|
|
152
154
|
timeoutMin?: number;
|
|
155
|
+
/** The project's model and effort: a session takes them where the thread picked none. */
|
|
156
|
+
pick?: AgentPick;
|
|
153
157
|
}
|
|
154
158
|
|
|
155
159
|
/** The model and effort an operator picked, `chats/<t>/agent.json`: none, the agent's own. */
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "gcf-harness-aif-ext",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.14.0",
|
|
4
4
|
"description": "GCF orchestration harness for Claude Code: one-command card pipeline, readset guard",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -28,7 +28,7 @@
|
|
|
28
28
|
"prepack": "node -e \"const p=require('./package.json'),e=require('./extension.json');if(p.version!==e.version)throw new Error('version mismatch: package.json '+p.version+' vs extension.json '+e.version);require('node:fs').statSync('node_modules/gcf-session/lib/index.js')\""
|
|
29
29
|
},
|
|
30
30
|
"peerDependencies": {
|
|
31
|
-
"gcf-aif-ext": "^0.
|
|
31
|
+
"gcf-aif-ext": "^0.14.0"
|
|
32
32
|
},
|
|
33
33
|
"dependencies": {
|
|
34
34
|
"gcf-session": "file:../gcf-session"
|