gcf-board 0.8.2 → 0.9.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 +106 -104
- package/dist/server/app.js +137 -9
- package/dist/server/chat.js +21 -9
- package/dist/server/cli.js +5 -0
- package/dist/server/files.js +17 -0
- package/dist/server/runs.js +22 -6
- package/dist/server/talks.js +22 -1
- package/dist/web/assets/{index-aCBpVSeA.css → index-UzVgbCWq.css} +1 -1
- package/dist/web/assets/index-m10Wkvhe.js +39 -0
- package/dist/web/index.html +2 -2
- package/node_modules/gcf-session/lib/index.js +1 -0
- package/node_modules/gcf-session/lib/thread.js +71 -21
- package/node_modules/gcf-session/package.json +1 -1
- package/node_modules/gcf-session/types/index.d.ts +7 -1
- package/package.json +1 -1
- package/dist/web/assets/index-D8JZaQgt.js +0 -39
package/README.md
CHANGED
|
@@ -1,104 +1,106 @@
|
|
|
1
|
-
# gcf-board
|
|
2
|
-
|
|
3
|
-
A local web board for game projects on [GCF](../gcf-aif-ext): the items by status, the phase, WIP, the inbox, the playtest session, what was accepted and what was killed — and buttons that run the same `ai-factory gcf` commands an operator runs in a console. The board is a view: it stores nothing, and without it the work goes on in the console unchanged (Methodology §11).
|
|
4
|
-
|
|
5
|
-
## Requirements
|
|
6
|
-
|
|
7
|
-
- Node.js ≥ 22.18
|
|
8
|
-
- [`ai-factory`](https://www.npmjs.com/package/ai-factory) installed globally, and in each project [`gcf-aif-ext`](../gcf-aif-ext) ≥ 0.10 (`gcf board --json` with `schema: 3`: the columns, the moves, the item's fields, the blocks and the Help terms come from it as data)
|
|
9
|
-
- for runs: [`gcf-harness-aif-ext`](../gcf-harness-aif-ext) ≥ 0.11 (every board run opens its chat: `--chat`, `gcf-harness chat`; it waits the project's answer time) and Claude Code (`claude -p`); ≥ 0.12 to wait for the usage limit's reset and for queued runs (`--wait-limit`)
|
|
10
|
-
- for the project chat: `gcf-aif-ext` ≥ 0.12 (`domain.chat`, `agent.rules`) and Claude Code
|
|
11
|
-
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
gcf-board
|
|
18
|
-
gcf-board
|
|
19
|
-
gcf-board --
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
- **
|
|
38
|
-
- **
|
|
39
|
-
- **
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
- a card
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
- **
|
|
53
|
-
- **
|
|
54
|
-
- **
|
|
55
|
-
- **
|
|
56
|
-
- **
|
|
57
|
-
- **
|
|
58
|
-
- **
|
|
59
|
-
- **
|
|
60
|
-
- **
|
|
61
|
-
- **
|
|
62
|
-
- **
|
|
63
|
-
- **
|
|
64
|
-
- **
|
|
65
|
-
- **
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
-
|
|
77
|
-
-
|
|
78
|
-
-
|
|
79
|
-
-
|
|
80
|
-
- A
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
npm
|
|
102
|
-
npm
|
|
103
|
-
|
|
104
|
-
|
|
1
|
+
# gcf-board
|
|
2
|
+
|
|
3
|
+
A local web board for game projects on [GCF](../gcf-aif-ext): the items by status, the phase, WIP, the inbox, the playtest session, what was accepted and what was killed — and buttons that run the same `ai-factory gcf` commands an operator runs in a console. The board is a view: it stores nothing, and without it the work goes on in the console unchanged (Methodology §11).
|
|
4
|
+
|
|
5
|
+
## Requirements
|
|
6
|
+
|
|
7
|
+
- Node.js ≥ 22.18
|
|
8
|
+
- [`ai-factory`](https://www.npmjs.com/package/ai-factory) installed globally, and in each project [`gcf-aif-ext`](../gcf-aif-ext) ≥ 0.10 (`gcf board --json` with `schema: 3`: the columns, the moves, the item's fields, the blocks and the Help terms come from it as data)
|
|
9
|
+
- for runs: [`gcf-harness-aif-ext`](../gcf-harness-aif-ext) ≥ 0.11 (every board run opens its chat: `--chat`, `gcf-harness chat`; it waits the project's answer time) and Claude Code (`claude -p`); ≥ 0.12 to wait for the usage limit's reset and for queued runs (`--wait-limit`)
|
|
10
|
+
- for the project chat: `gcf-aif-ext` ≥ 0.12 (`domain.chat`, `agent.rules`) and Claude Code
|
|
11
|
+
- for board v2 (0.9): `gcf-aif-ext` ≥ 0.13 for an item's History, `needs`, the design units, filters and lanes; `gcf-harness-aif-ext` ≥ 0.13 for past runs and a run's model and effort. On older ones these hide or say which version they need
|
|
12
|
+
- gcf-board 0.2 needs `gcf-aif-ext` ≥ 0.7 (priority, questions, session marks, `run_mode`)
|
|
13
|
+
|
|
14
|
+
## Run
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
npm i -g gcf-board
|
|
18
|
+
gcf-board # http://127.0.0.1:4317
|
|
19
|
+
gcf-board --port 4400
|
|
20
|
+
gcf-board --version # the installed version
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
It opens the board in your browser (the URL with the token, `http://127.0.0.1:4317/?t=<token>`, is printed too; `--no-open` skips the browser). Started again while it runs, it just opens the running board. Add a project by its folder (one that has `gcf/`) under **Projects**.
|
|
24
|
+
|
|
25
|
+
**Desktop shortcut**: run once
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
gcf-board shortcut # or: gcf-board shortcut --port 4400
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
It puts **GCF Board** on the desktop (Windows: a shortcut whose server console starts minimized; macOS: `GCF Board.command`; Linux: an application entry). Double-click it: the board starts and opens, or opens if it already runs. Run the command again after moving Node.js.
|
|
32
|
+
|
|
33
|
+
## What it does
|
|
34
|
+
|
|
35
|
+
The board knows no domain by name: the project's board read gives its columns, moves with their forms, item fields, blocks and Help terms (`domain`, Board-PRD decision 16). The page follows design B (`docs/design/mockup`): a left nav with the project switcher (add a project, take one off the board), the screens **Command**, **Board**, **Chat**, **Inbox**, **Runs**, **Playtest**, **Ended**, **Agent**, **Settings** and **Metrics** (a domain without a block has no screen for it, a project without a harness no Runs and no Metrics), and a header with the phase, the runs, the limit wait, the quota, WIP, the release, **waiting for me**, **+ item** and **?**. The project and the screen are in the URL hash. On a phone a bottom bar holds Command, Board, Chat, Inbox and More. When the server is gone, the page says so and reconnects by itself. For a GCF project:
|
|
36
|
+
|
|
37
|
+
- **Command**: **waiting for me**, what only the operator moves on (Board-PRD §1.3), by group: failed run reports and a paused queue, a card waiting in a chat (a permission is answered right there, **Always** naming the rule it saves), D1 questions, the items to play and judge, to decide, to unblock (the columns the domain marks `human`), and a `paused: limit` item to resume. Beside it **Live**: the runs going on with their plan progress, **Follow** and **Stop**, the console runs and sessions, **Run next**, the queue, the run reports, and what the board did by itself.
|
|
38
|
+
- **Board**: columns ready, running, blocked, awaiting-verdict, awaiting-decision, unplayed, parked. A card shows the type, the gate, the plan progress (`2/5`), the severity, `verified`, the model, **needs N** and **needed by N**. A running card shows when its run log was last written (`active 12 s ago`), and `quiet 6 min` when the log has been silent for 5 minutes or more. A run's end report gives each item's cost when the agent reported it. Pointing at a card (or focusing it from the keyboard) lights up the cards it needs and the cards that need it, each saying how, and dims the rest. The toolbar (board 0.9.0, core 0.13.0) searches ids and titles, keeps **waiting for me**, filters by the fields the domain marks `filter` (GCF: type, gate, severity, system, milestone; several values at once, each a chip to take off) and lays the board out in lanes by a field it marks `group` (system, parent, milestone): an item with two systems stands in both lanes, one with none in **none**, a parent lane is named by the feature's title. The mouse drags the board sideways from its empty space; the wheel over a column with no scroll of its own pans it.
|
|
39
|
+
- **An item**: its file, its plan and its run log as it grows, its fields, and the moves the core offers for it (`items[].moves`, Methodology §4.1): run, verdict, decide, block, unblock, drop, close, submit, depends. Each move's form comes from the core; the core still checks the rest itself, and the board shows its answer. **Dependencies**: what it needs that has not ended in history (an item with its column, a design unit with its TBDs or the questions that block it, a graveyard line, an unknown id) and the items that need it, each a link; **Edit…** opens the picker of the board's items and design units (search by id and title, or type an id), and Save sends the `depends` move's adds and removes. **History** (core 0.13.0): its moves newest first, when, which, who (a run, your session, you; unknown on a commit older than the framework's marks), the commit and its subject; then its runs, as on the Runs screen. **Related**: its feature's other children, and the graveyard lines tagged with its system ("did we kill this before?"). An item that ended opens from **Ended** with its History.
|
|
40
|
+
- **Runs** (harness 0.13.0): what runs now with the run's model and effort, its last log lines, **Whole log** and **Stop**; the queue with what each item will run on; the past runs of the harness's run log, newest first, 50 at a time: start, end, mode, cost, and per item its result word, the reason word for word, cost, tokens, turns, handoffs, a broken step and what it ran on. **log** opens the part of the item's log that run wrote, **chat** that run's chat. Every start the operator asks for (Run selected, Run next, a drop on running, this screen) asks first with a model and effort picker for that run only (**default: each item's own**); the drawer's Run is one click. An older harness shows the active runs only, and the dialog has no pickers. The API: `GET /api/p/<project>/runs/past?limit=` (`gcf-harness runs --json`; 404 without a harness that keeps them), `GET …/item/<id>/history` (`{id, moves, runs}`), `GET …/log/<id>?from=&to=` (a past run's part, once: `{text, cut}`, at most its last 2 MB; without `from` and `to` the log as it grows), `POST …/run` with `model` and `effort`, `POST …/inbox/<entry>/draft` (`{thread, created}`).
|
|
41
|
+
- **Drag**:
|
|
42
|
+
- a ready card into **running** starts its run;
|
|
43
|
+
- a blocked or parked card into **ready** unblocks it;
|
|
44
|
+
- a card onto **graveyard** drops it.
|
|
45
|
+
|
|
46
|
+
Every other move is a button.
|
|
47
|
+
- **Run**: **run** on an item, or select ready cards and **Run selected**. It starts `ai-factory gcf-harness run <ids> --json` in the project's run mode:
|
|
48
|
+
- `run_mode: worktree`: one worktree and one agent session per item, all at once, then the integrator;
|
|
49
|
+
- `run_mode: main`: one item at a time in the project folder. A run asked for meanwhile waits in the board's **queue**; **remove from queue** takes it out.
|
|
50
|
+
|
|
51
|
+
A run asks first: it spends the subscription. **Stop** on a running item ends its session; the item stays ready and its work is kept. **Stop** during the wait for the usage limit's reset leaves the item **paused: limit** with its reset, and the queue goes on. A queued main run that the next one would repeat (the harness did not start, or another run works the checkout) pauses the queue: the header shows **queue paused — resume**; fix the cause, then resume. A card marked **interrupted** had a run that stopped (a timeout, a stop, a crash, the usage limit): **resume** continues its agent session with all its context, **start fresh** drops it. After the usage limit the run itself waits for the reset and goes on in the same session (harness 0.12): the card reads **limit: resumes HH:MM**, and **Stop** ends the wait. A run that could not wait (the week's limit, an unknown reset) ends **paused: limit** and pauses the main queue; **resume** on the header goes on after the reset. When a run ends, a report card lists each item's result and stays until closed, across page reloads. **What the board did by itself** lists its automatic acts with their times: a usage limit, a context handoff, the queue paused, resumed or started. A run confirmation names what each interrupted item picks up. The header shows the usage limit as the last run read it, from the newest `.gcf-session/runs/quota.json` of the board's projects: `quota 19% left · resets 03:00`, the window with the least left, every window in its tooltip; `quota ?` before any reading, or once every window has reset since. The queue, the reports and that list live in the board's memory: a board restart forgets them. A run itself outlives the board: closing it or Ctrl+C in its console leaves the run going, and the board started again shows it running, then its report (a run in flight keeps its record in `~/.gcf/runs/`).
|
|
52
|
+
- **Who runs it** (core 0.7.13): a running card tells a console run and **your session** (a `gcf claim` mark) from the board's own run; a session offers **release mark** instead of **stop**. A ready card whose dependencies are not built yet shows **waits for <dep>**; the drawer shows when an item began to wait (`since_at`).
|
|
53
|
+
- **Run next N independent**: the framework's gate picks the ready items that can run together now, by priority, and the board runs them after asking.
|
|
54
|
+
- **Priority**: drop a ready card on another to put it before; the column's ranks are committed (`gcf prioritize`).
|
|
55
|
+
- **Questions**: each D1 shows its question and proposed answer; **Answer** writes yours into its record (`gcf question answer`), and the next agent on its units puts it in place.
|
|
56
|
+
- **New item**: `gcf item new … --commit`, its form from the core: a bug asks its severity, a release its version and channel. The item's `model` and `effort` go to its run.
|
|
57
|
+
- **Help** (**?**): the domain's terms, columns, moves and field values with what each means, and the words of runs, under one filter.
|
|
58
|
+
- **Settings**: the keys of `gcf/config.yml` and the agents' language (`language.ui`, `language.artifacts` of `.ai-factory/config.yaml`), by the core's groups, each a `gcf config set` commit.
|
|
59
|
+
- **Agent**: the deny groups to tick, the rules the ticked groups add, the operator's own deny rules (add, remove) and the allow rules of `agent.allow`, apart; the context limits, read only.
|
|
60
|
+
- **An item's chat** (its drawer's **Chat** tab; harness 0.11.1, core 0.11.1): every run the board starts keeps its agent sessions open; the project's `chat:` settings (Settings: `chat.ask`, `chat.answer_timeout_min`) say what the agent asks and how long a question waits. The tab shows the run's chat, then the item's own thread of the project chat: the talk, question cards (picks, several questions, **Submit**), the run's milestones, its sessions, the limit wait, the context share. A message goes where the server puts it: the live run (its limit wait too), else the item's thread, and the line under the box says where it went. `GET /api/p/<project>/chat/<id>` follows the item's chat from its start, in raw chunks of JSON lines (the page splits them). `POST` there sends `{type: 'say', text, images?, attach?}`, `{type: 'interrupt'}` or `{type: 'answer', request_id, answers}` through `gcf-harness chat`; with no live run a message goes to the item's thread (answer `{talk}`), else a message with no session to read it gets 409, bad input 400. `attach` (`[{kind: item | unit | file, ref}]`) goes into the message's text as a line the agent reads; a design unit (the composer's **+ unit**, from the board read's `units`) goes as `unit <id> (<file>)`. `GET /api/p/<project>/chat/<id>/att/<file>` serves a chat picture; **attach to item…** under a picture gives it to an item (`gcf item attach`).
|
|
61
|
+
- **Model and effort** (board 0.8.0, core 0.12.3): pickers in the New item form, in the drawer (**change** beside the model and effort, and **model / effort** under **More**) and in a thread's composer: **default** (the agent picks), the agent's presets, or an own word. An item's next run takes them; a thread's next session does (`chats/<t>/agent.json`), and its line in the chat says so.
|
|
62
|
+
- **Project chat** (the **Chat** screen; core 0.12): threads of an agent in the project's folder, listed newest first and filtered by their item; a new thread is made when its first message is sent. Each thread is run by the bundled session engine (`gcf-session`) through the same detached relay as runs. It asks a card before each edit, git command and framework move (**allow once**, **always** — saved in `.claude/settings.local.json`; the card says saved only when it was — or **deny**); a new item it proposes through the board's MCP server `gcf` (tool `propose_item_new`, asked with no card: the proposal card is the question), the proposal card shows every field it proposed, and the operator's **Create** makes it with `POST /move` (`proposal: {talk, id}`), **Edit…** first in the new-item form. A thread's list entry names the card that waits in it and its limit wait (`card`, `limit_until`); a running item names the card of its run's chat (`chat_card`). A long talk hands over to a fresh agent from a summary; an idle agent closes after `chat.answer_timeout_min` (0 means 15) and the next message resumes it. Each item has at most one thread: a message to an item with no live run goes there. `GET /api/p/<project>/talks[?item=]` lists the threads with their proposals' states; `POST` there makes one (`{item?}`); `GET /api/p/<project>/talk/<t>` follows a thread's events; `POST` there sends `say`, `interrupt`, `answer`, `allow`, `deny` or `handoff`; `POST …/talk/<t>/stop` is the composer's **close agent** (board 0.8.1): the thread's agent ends with everything it started, or its limit wait does, and what it had not taken in is dropped with a "not sent" line; the next message resumes the talk; `GET …/talk/<t>/att/<file>` serves its pictures. The files live in `.gcf-session/chats/` (docs/Chat-Plan.md §3).
|
|
63
|
+
- **Inbox**: add an entry (Enter adds, Shift+Enter breaks the line; its source and tags), tag it, erase it, or turn it into an item (its first line the title, the rest the note); search the entries, filter them by tag and by lesson kind. The D1 questions and the agent's D2 assumptions are listed there too. **Draft with agent** opens a project chat thread bound to the entry and sends "Draft an item from inbox entry <id>:" with its text; a second click opens the same thread. The first proposal's **Create** takes the entry (it is erased); a later one makes an item with no entry. Off while the usage limit holds.
|
|
64
|
+
- **Keys**: `/` search, `i` a new inbox entry, `n` a new item, `j` / `k` between cards, Enter opens one, `r` runs the focused card (it asks), `1`–`7` a column, `?` Help, Esc closes a dialog, Help or the drawer; none while a field has the focus.
|
|
65
|
+
- **Lessons** (core 0.7.10, harness 0.9.2): what got in an agent's way, asked at the end of each session, lands in the inbox with its kind (`tool`, `rules`, `framework`, `template`, `other`) and its item. The inbox filters them; a card shows `N lessons`, and the drawer lists the item's lessons with the inbox's buttons. A run's report line ends with `, N lessons`, and with `— code written outside aif-implement` when a session skipped that skill.
|
|
66
|
+
- **Playtest**: `gcf playtest session` with the checklist grouped by subsystem; keep, tune or kill each item from the list. **Build** runs `dod.build`. A note goes to the inbox as `--source playtest`.
|
|
67
|
+
- **Ended**: history (accepted) and graveyard (killed, dropped, won't-fix); a line opens the item's History.
|
|
68
|
+
- **Metrics**: `gcf-harness metrics --json` of the project — how many runs reached submit or close, what they cost, handoffs, plan checks, DoD attempts, guard firings, block reasons — and, with harness 0.9.5, the cost per item over all its runs and per week and day.
|
|
69
|
+
|
|
70
|
+
The page updates by itself: the server watches each project's `gcf/` and `.gcf-session/runs/`.
|
|
71
|
+
|
|
72
|
+
## Security
|
|
73
|
+
|
|
74
|
+
The board starts agents that write code and commit: whoever can talk to it runs code on this machine.
|
|
75
|
+
|
|
76
|
+
- It listens on `127.0.0.1` only.
|
|
77
|
+
- The token, kept in `~/.gcf/board-token`, opens the board once per server start; delete that file to make a new one. The browser then holds a session cookie that dies with the server: a browser sends a `127.0.0.1` cookie to every local port, so the cookie is never the token.
|
|
78
|
+
- Started while another program holds its port, it refuses rather than hand the token to that program.
|
|
79
|
+
- A request must also name host `127.0.0.1` or `localhost` with the board's port.
|
|
80
|
+
- A change must come from the board's own page (`Origin`). This blocks another site in the same browser.
|
|
81
|
+
- Commands run without a shell: the operator's text reaches `ai-factory` as one argument, never as a command line.
|
|
82
|
+
- The API shows only item files, plans and run logs inside a project.
|
|
83
|
+
- A project chat's agent may not read the board's folder (`~/.gcf`, the token's): not by read, search or a shell command that names it. A command that spells the path another way still could; a separate secret for a card's answer comes with remote access.
|
|
84
|
+
|
|
85
|
+
Do not put the port on a network. Remote and phone access is planned for v2, behind its own authentication.
|
|
86
|
+
|
|
87
|
+
## Files
|
|
88
|
+
|
|
89
|
+
- `~/.gcf/projects.json`: the projects on the board, `{projects: [{name, path}]}`.
|
|
90
|
+
- `~/.gcf/board-token`: the token.
|
|
91
|
+
- `~/.gcf/runs/`: the record of each run in flight, which a board started again finds.
|
|
92
|
+
- `GCF_BOARD_HOME` moves them all; `GCF_BOARD_AIF` points at another `ai-factory` entry script; `GCF_SESSION_AGENT` puts another agent command in place of `claude` in project chats (tests).
|
|
93
|
+
|
|
94
|
+
## Roadmap (v2)
|
|
95
|
+
|
|
96
|
+
- **Phone and remote access**: Tailscale or Claude Remote Control, with their own authentication; push notifications when an item blocks or waits for a verdict.
|
|
97
|
+
|
|
98
|
+
## Develop
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
npm install
|
|
102
|
+
npm test # server and web tests on Node's type stripping
|
|
103
|
+
npm run typecheck
|
|
104
|
+
npm run build # vite → dist/web, tsc → dist/server
|
|
105
|
+
node dist/server/main.js --port 4318
|
|
106
|
+
```
|
package/dist/server/app.js
CHANGED
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
// (`ai-factory <harness> metrics`, the domain's harness), the project chat's threads. Writes: a
|
|
4
4
|
// project on the board, a move, a run, a project chat message. Every write of the project is a
|
|
5
5
|
// command of the framework; a project chat's agent asks the operator for each one (talks.ts).
|
|
6
|
+
import { execFile } from 'node:child_process';
|
|
6
7
|
import { randomBytes } from 'node:crypto';
|
|
7
8
|
import { createServer } from 'node:http';
|
|
8
9
|
import { existsSync, statSync, writeFileSync } from 'node:fs';
|
|
@@ -13,14 +14,14 @@ import { BOARD_SCHEMA, } from '../shared/board.js';
|
|
|
13
14
|
import { admit, cookieName, hostAllowed, tokenInUrl } from './auth.js';
|
|
14
15
|
import { briefError, runCli } from './cli.js';
|
|
15
16
|
import { broadcast, planRev, subscribe, watchProject } from './events.js';
|
|
16
|
-
import { CHAT_BODY_MAX, chatInput, IMAGE_EXT, talkInput } from './chat.js';
|
|
17
|
-
import { follow, followLog, readShown, shownShape } from './files.js';
|
|
17
|
+
import { attachesUnit, CHAT_BODY_MAX, chatInput, IMAGE_EXT, talkInput, } from './chat.js';
|
|
18
|
+
import { follow, followLog, logPart, readShown, shownShape } from './files.js';
|
|
18
19
|
import { HttpError } from './http-error.js';
|
|
19
20
|
import { isCenterMove, moveArgs, moveInput, runIds } from './moves.js';
|
|
20
21
|
import { addProject, listProjects, projectOf, removeProject } from './registry.js';
|
|
21
22
|
import { adoptRuns, closeReport, forgetProject, resumeQueue, runsOf, startRun, unqueue, } from './runs.js';
|
|
22
|
-
import { acceptProposal, agentPresets, chatCard, chatOf, listTalks, openTalk, pickTalk, prepareTalk, startTalk, stopTalk, talkId, talkLive, talkWaits, watchTalks, writeTalk, } from './talks.js';
|
|
23
|
-
import { threadDir } from 'gcf-session';
|
|
23
|
+
import { acceptProposal, agentPresets, chatCard, chatOf, entryTalk, listTalks, openTalk, pickTalk, prepareTalk, startTalk, stopTalk, talkEntry, talkId, talkLive, talkSaid, talkWaits, watchTalks, writeTalk, } from './talks.js';
|
|
24
|
+
import { threadDir, threadOfEntry } from 'gcf-session';
|
|
24
25
|
const send = (res, status, body) => {
|
|
25
26
|
res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
|
|
26
27
|
res.end(JSON.stringify(body));
|
|
@@ -62,6 +63,27 @@ const idsOf = (b) => new Set([
|
|
|
62
63
|
...(b.graveyard ?? []).map((g) => g.id),
|
|
63
64
|
]);
|
|
64
65
|
const SLUG = /^[a-z0-9][a-z0-9-]*$/;
|
|
66
|
+
// A model or effort word for one run: plain, as the harness takes it.
|
|
67
|
+
const WORD = /^[A-Za-z0-9][\w.-]{0,63}$/;
|
|
68
|
+
/** A run's pick of model and effort from a request body (Board-PRD §5.9); none: each item's own. */
|
|
69
|
+
function runAgent(body) {
|
|
70
|
+
const pick = { model: null, effort: null };
|
|
71
|
+
for (const k of ['model', 'effort']) {
|
|
72
|
+
const v = body[k];
|
|
73
|
+
if (v === undefined || v === null || v === '' || v === 'default')
|
|
74
|
+
continue;
|
|
75
|
+
if (typeof v !== 'string' || !WORD.test(v))
|
|
76
|
+
throw new HttpError(400, `${k} is one plain word: ${String(v)}`);
|
|
77
|
+
pick[k] = v;
|
|
78
|
+
}
|
|
79
|
+
return pick.model || pick.effort ? pick : undefined;
|
|
80
|
+
}
|
|
81
|
+
// The Drafts whose first message goes now, `<project path> <entry>`: a second click sends none.
|
|
82
|
+
const drafting = new Set();
|
|
83
|
+
/** The project's HEAD commit, or null: a new commit (a move, a merge) tells an open History. */
|
|
84
|
+
const headOf = (dir) => new Promise((resolve) => execFile('git', ['rev-parse', 'HEAD'], { cwd: dir, windowsHide: true }, (e, out) => resolve(e ? null : out.trim())));
|
|
85
|
+
/** Whether the usage limit holds for the account now (decision 22): Draft waits for its reset. */
|
|
86
|
+
const limitHolds = (q) => q?.info.status === 'rejected' && (q.info.resetsAt ?? 0) * 1000 > Date.now();
|
|
65
87
|
/** The ISO time a file was last written, or null when it is not there. */
|
|
66
88
|
const activeAt = (file) => {
|
|
67
89
|
try {
|
|
@@ -188,6 +210,23 @@ export function createApp(o) {
|
|
|
188
210
|
* the board read knows the item: the answer that says so (the thread, the input line's id),
|
|
189
211
|
* else null.
|
|
190
212
|
*/
|
|
213
|
+
/** The design units of the board read, when a message attaches one; else none to read. */
|
|
214
|
+
const unitsFor = async (p, body) => attachesUnit(body)
|
|
215
|
+
? new Map(((await boardOf(p)).units ?? []).map((u) => [u.id, u.file]))
|
|
216
|
+
: undefined;
|
|
217
|
+
/**
|
|
218
|
+
* A harness reading of past runs (`runs --json`, board v2): null when the project has no
|
|
219
|
+
* harness or its harness is older than the command.
|
|
220
|
+
*/
|
|
221
|
+
const pastRuns = async (p, args) => {
|
|
222
|
+
const harness = await harnessOf(p).catch(() => null);
|
|
223
|
+
if (!harness)
|
|
224
|
+
return null;
|
|
225
|
+
const r = await cli(p, [harness, 'runs', '--json', ...args]);
|
|
226
|
+
if (!r.ok && /unknown command/.test(r.err))
|
|
227
|
+
return null;
|
|
228
|
+
return jsonOf(r, `${harness} runs`).runs;
|
|
229
|
+
};
|
|
191
230
|
const toThread = async (p, item, line) => {
|
|
192
231
|
const board = await boardOf(p).catch(() => null);
|
|
193
232
|
if (!board?.domain.chat || !board.agent?.rules || !idsOf(board).has(item))
|
|
@@ -237,6 +276,7 @@ export function createApp(o) {
|
|
|
237
276
|
board_version: o.version,
|
|
238
277
|
quota: await lastQuota(),
|
|
239
278
|
presets: agentPresets(),
|
|
279
|
+
head: await headOf(p.path),
|
|
240
280
|
};
|
|
241
281
|
const board = await boardOf(p);
|
|
242
282
|
// A running item's last log write tells a working session from a stuck one; a run's
|
|
@@ -272,8 +312,16 @@ export function createApp(o) {
|
|
|
272
312
|
[
|
|
273
313
|
'GET',
|
|
274
314
|
/^\/api\/p\/([^/]+)\/log\/([a-z0-9][a-z0-9-]*)$/,
|
|
275
|
-
async (_req, res, m) => {
|
|
276
|
-
|
|
315
|
+
async (_req, res, m, url) => {
|
|
316
|
+
const root = (await projectOf(m[1])).path;
|
|
317
|
+
const [from, to] = ['from', 'to'].map((k) => url.searchParams.get(k));
|
|
318
|
+
// Without a part: the log as it grows. With one: the bytes a past run wrote, once.
|
|
319
|
+
if (from === null && to === null)
|
|
320
|
+
return followLog(root, m[2], res);
|
|
321
|
+
const [a, b] = [from, to].map((v) => (/^\d{1,15}$/.test(v ?? '') ? Number(v) : NaN));
|
|
322
|
+
if (Number.isNaN(a) || Number.isNaN(b) || a > b)
|
|
323
|
+
throw new HttpError(400, 'a log part is from and to, whole numbers, 0 ≤ from ≤ to');
|
|
324
|
+
send(res, 200, await logPart(root, m[2], a, b));
|
|
277
325
|
},
|
|
278
326
|
],
|
|
279
327
|
[
|
|
@@ -312,7 +360,8 @@ export function createApp(o) {
|
|
|
312
360
|
// and that a live session takes it, so a message nobody would read is refused (409).
|
|
313
361
|
async (req, res, m) => {
|
|
314
362
|
const p = await projectOf(m[1]);
|
|
315
|
-
const
|
|
363
|
+
const body = await bodyOf(req, CHAT_BODY_MAX);
|
|
364
|
+
const line = chatInput(body, await unitsFor(p, body));
|
|
316
365
|
let harness;
|
|
317
366
|
try {
|
|
318
367
|
harness = await harnessOf(p);
|
|
@@ -408,7 +457,8 @@ export function createApp(o) {
|
|
|
408
457
|
const t = talkId(m[2]);
|
|
409
458
|
if (!existsSync(threadDir(p.path, t)))
|
|
410
459
|
throw new HttpError(404, `no thread ${t}`);
|
|
411
|
-
const
|
|
460
|
+
const body = await bodyOf(req, CHAT_BODY_MAX);
|
|
461
|
+
const line = await sendTalk(p, t, talkInput(body, await unitsFor(p, body)));
|
|
412
462
|
send(res, 202, { ok: true, ...(typeof line.id === 'string' ? { id: line.id } : {}) });
|
|
413
463
|
},
|
|
414
464
|
],
|
|
@@ -497,6 +547,20 @@ export function createApp(o) {
|
|
|
497
547
|
const domain = isCenterMove(body.cmd)
|
|
498
548
|
? undefined
|
|
499
549
|
: (domains.get(p.name) ?? (await boardOf(p)).domain);
|
|
550
|
+
// A proposal of a Draft thread makes the entry's item (Board-V2-Data-Plan §2.7): the
|
|
551
|
+
// entry goes with it while it is there; a second proposal, or one after it went, has none.
|
|
552
|
+
const proposal = (body.proposal ?? {});
|
|
553
|
+
if (typeof proposal.talk === 'string' && body.from === undefined) {
|
|
554
|
+
// A thread that is not there has no entry: acceptProposal says it is not there.
|
|
555
|
+
const entry = existsSync(threadDir(p.path, talkId(proposal.talk)))
|
|
556
|
+
? talkEntry(p, proposal.talk)
|
|
557
|
+
: null;
|
|
558
|
+
const board = entry ? await boardOf(p) : null;
|
|
559
|
+
if (board &&
|
|
560
|
+
board.domain.new_item === body.cmd &&
|
|
561
|
+
board.inbox?.some((e) => e.id === entry))
|
|
562
|
+
body.from = entry;
|
|
563
|
+
}
|
|
500
564
|
const args = moveArgs(body, domain?.moves);
|
|
501
565
|
const run = () => cli(p, args, undefined, moveInput(body, domain?.moves));
|
|
502
566
|
// An agent's proposal made (AD-16, AD-33): its record goes with the move.
|
|
@@ -524,6 +588,69 @@ export function createApp(o) {
|
|
|
524
588
|
/^\/api\/p\/([^/]+)\/runs$/,
|
|
525
589
|
async (_req, res, m) => send(res, 200, runsOf((await projectOf(m[1])).name)),
|
|
526
590
|
],
|
|
591
|
+
[
|
|
592
|
+
// The past runs, newest first (Board-PRD §5.9): the harness's run log; none without one.
|
|
593
|
+
'GET',
|
|
594
|
+
/^\/api\/p\/([^/]+)\/runs\/past$/,
|
|
595
|
+
async (_req, res, m, url) => {
|
|
596
|
+
const p = await projectOf(m[1]);
|
|
597
|
+
const limit = String(Math.max(1, Math.min(1000, Number(url.searchParams.get('limit')) || 50)));
|
|
598
|
+
const runs = await pastRuns(p, ['--limit', limit]);
|
|
599
|
+
if (!runs)
|
|
600
|
+
throw new HttpError(404, 'no past runs: the project has no harness that keeps them');
|
|
601
|
+
send(res, 200, { runs });
|
|
602
|
+
},
|
|
603
|
+
],
|
|
604
|
+
[
|
|
605
|
+
// An item's moves and runs (Board-PRD §5.3 History): an ended item keeps them too.
|
|
606
|
+
'GET',
|
|
607
|
+
/^\/api\/p\/([^/]+)\/item\/([a-z0-9][a-z0-9-]*)\/history$/,
|
|
608
|
+
async (_req, res, m) => {
|
|
609
|
+
const p = await projectOf(m[1]);
|
|
610
|
+
const read = await cli(p, ['gcf', 'item', 'history', m[2], '--json']);
|
|
611
|
+
if (!read.ok)
|
|
612
|
+
throw new HttpError(read.code === 1 ? 400 : 500, briefError(read.err || read.out));
|
|
613
|
+
const { moves } = jsonOf(read, 'gcf item history');
|
|
614
|
+
// A run log the harness cannot read leaves the moves shown: no runs then.
|
|
615
|
+
const runs = (await pastRuns(p, ['--item', m[2], '--limit', '1000']).catch(() => null)) ?? [];
|
|
616
|
+
send(res, 200, { id: m[2], moves, runs });
|
|
617
|
+
},
|
|
618
|
+
],
|
|
619
|
+
[
|
|
620
|
+
// Draft with agent (decision 22): the entry's own thread asks an agent for an item. A
|
|
621
|
+
// second click opens the same thread and sends nothing.
|
|
622
|
+
'POST',
|
|
623
|
+
/^\/api\/p\/([^/]+)\/inbox\/([a-z0-9][a-z0-9-]*)\/draft$/,
|
|
624
|
+
async (_req, res, m) => {
|
|
625
|
+
const p = await projectOf(m[1]);
|
|
626
|
+
const board = await boardOf(p);
|
|
627
|
+
chatOf(board);
|
|
628
|
+
const e = board.inbox?.find((x) => x.id === m[2]);
|
|
629
|
+
if (!e)
|
|
630
|
+
throw new HttpError(404, `no inbox entry ${m[2]}`);
|
|
631
|
+
const key = `${p.path} ${e.id}`;
|
|
632
|
+
const had = threadOfEntry(p.path, e.id);
|
|
633
|
+
// A thread whose first message never went (a failed send) takes it now; a second
|
|
634
|
+
// click while the first one sends takes the same thread and sends nothing.
|
|
635
|
+
const fresh = (!had || !talkSaid(p, had)) && !drafting.has(key);
|
|
636
|
+
if (fresh && limitHolds(await lastQuota()))
|
|
637
|
+
throw new HttpError(409, 'the usage limit holds for the account: draft after its reset');
|
|
638
|
+
const { id, created } = entryTalk(p, e.id);
|
|
639
|
+
// Asked again after the quota's read: a click that sent meanwhile said it already.
|
|
640
|
+
if (fresh && !drafting.has(key) && !talkSaid(p, id)) {
|
|
641
|
+
drafting.add(key);
|
|
642
|
+
try {
|
|
643
|
+
await prepareTalk(p, board, id);
|
|
644
|
+
await sendTalk(p, id, { type: 'say', text: `Draft an item from inbox entry ${e.id}:\n${e.text}` }, board);
|
|
645
|
+
}
|
|
646
|
+
finally {
|
|
647
|
+
drafting.delete(key);
|
|
648
|
+
}
|
|
649
|
+
}
|
|
650
|
+
broadcast({ type: 'talks', project: p.name });
|
|
651
|
+
send(res, created ? 201 : 200, { thread: id, created });
|
|
652
|
+
},
|
|
653
|
+
],
|
|
527
654
|
[
|
|
528
655
|
'POST',
|
|
529
656
|
/^\/api\/p\/([^/]+)\/run$/,
|
|
@@ -535,7 +662,8 @@ export function createApp(o) {
|
|
|
535
662
|
throw new HttpError(400, 'this project has no harness: its items run from a console');
|
|
536
663
|
const ids = runIds(body);
|
|
537
664
|
const fresh = body.fresh === true;
|
|
538
|
-
|
|
665
|
+
const agent = runAgent(body);
|
|
666
|
+
send(res, 202, startRun(o.entry, p, ids, mode, fresh, domain.harness, agent));
|
|
539
667
|
},
|
|
540
668
|
],
|
|
541
669
|
[
|
package/dist/server/chat.js
CHANGED
|
@@ -30,10 +30,11 @@ function images(v) {
|
|
|
30
30
|
}
|
|
31
31
|
const SLUG = /^[a-z0-9][a-z0-9-]*$/;
|
|
32
32
|
/**
|
|
33
|
-
* What a message attaches (Round2-review §3): an item, a file of the project
|
|
34
|
-
* message's text, as a line the agent reads: it
|
|
33
|
+
* What a message attaches (Round2-review §3): an item, a file of the project, a design unit of
|
|
34
|
+
* `units` (Board-PRD §5.13). They go into the message's text, as a line the agent reads: it
|
|
35
|
+
* opens them itself.
|
|
35
36
|
*/
|
|
36
|
-
function attachLine(v) {
|
|
37
|
+
function attachLine(v, units) {
|
|
37
38
|
if (v === undefined)
|
|
38
39
|
return '';
|
|
39
40
|
if (!Array.isArray(v) || v.length > 10)
|
|
@@ -42,6 +43,11 @@ function attachLine(v) {
|
|
|
42
43
|
const { kind, ref } = (a ?? {});
|
|
43
44
|
if (kind === 'item' && typeof ref === 'string' && SLUG.test(ref))
|
|
44
45
|
return `item ${ref} (gcf/work/${ref}.md)`;
|
|
46
|
+
// A unit the board read lists: its file is the core's, not the page's word.
|
|
47
|
+
if (kind === 'unit' && typeof ref === 'string' && units?.has(ref))
|
|
48
|
+
return `unit ${ref} (${units.get(ref)})`;
|
|
49
|
+
if (kind === 'unit')
|
|
50
|
+
throw bad(`no design unit ${String(ref)} on the board`);
|
|
45
51
|
// A project path, as the operator names it: relative, inside the project, nothing a shell
|
|
46
52
|
// would expand (`~`, `%VAR%`, `$VAR`) and no drive or scheme (`:`).
|
|
47
53
|
const file = typeof ref === 'string' ? ref.trim() : '';
|
|
@@ -52,16 +58,22 @@ function attachLine(v) {
|
|
|
52
58
|
!/[:%$]/.test(file) &&
|
|
53
59
|
!file.split(/[\\/]/).some((part) => part.trim() === '..'))
|
|
54
60
|
return `file ${file}`;
|
|
55
|
-
throw bad('an attachment is {kind: item, ref: <id>} or {kind: file, ref: <project path>}');
|
|
61
|
+
throw bad('an attachment is {kind: item, ref: <id>}, {kind: unit, ref: <id>} or {kind: file, ref: <project path>}');
|
|
56
62
|
});
|
|
57
63
|
return refs.length ? `\n\n[attached: ${refs.join('; ')}]` : '';
|
|
58
64
|
}
|
|
59
|
-
/**
|
|
60
|
-
export
|
|
65
|
+
/** Whether a body attaches a design unit: its route reads the board's units for it. */
|
|
66
|
+
export const attachesUnit = (body) => Array.isArray(body.attach) &&
|
|
67
|
+
body.attach.some((a) => a?.kind === 'unit');
|
|
68
|
+
/**
|
|
69
|
+
* The line a request writes into the chat input: a message, a stop of the step, an answer.
|
|
70
|
+
* `units`: the design units an attachment may name.
|
|
71
|
+
*/
|
|
72
|
+
export function chatInput(body, units) {
|
|
61
73
|
if (body.type === 'interrupt')
|
|
62
74
|
return { type: 'interrupt' };
|
|
63
75
|
if (body.type === 'say') {
|
|
64
|
-
const text = typeof body.text === 'string' ? body.text + attachLine(body.attach) : body.text;
|
|
76
|
+
const text = typeof body.text === 'string' ? body.text + attachLine(body.attach, units) : body.text;
|
|
65
77
|
if (typeof text !== 'string' || !text.trim() || text.length > TEXT_MAX)
|
|
66
78
|
throw bad(`a message is text, up to ${TEXT_MAX} characters`);
|
|
67
79
|
const list = images(body.images);
|
|
@@ -81,11 +93,11 @@ export function chatInput(body) {
|
|
|
81
93
|
throw bad('type is say, interrupt or answer');
|
|
82
94
|
}
|
|
83
95
|
/** The line a request writes into a project chat thread: an item chat's, a card's, a handoff. */
|
|
84
|
-
export function talkInput(body) {
|
|
96
|
+
export function talkInput(body, units) {
|
|
85
97
|
if (body.type === 'handoff')
|
|
86
98
|
return { type: 'handoff' };
|
|
87
99
|
if (body.type !== 'allow' && body.type !== 'deny')
|
|
88
|
-
return chatInput(body);
|
|
100
|
+
return chatInput(body, units);
|
|
89
101
|
const id = body.request_id;
|
|
90
102
|
if (typeof id !== 'string' || !/^[A-Za-z0-9_][\w-]*$/.test(id))
|
|
91
103
|
throw bad(`${body.type} names its request_id`);
|
package/dist/server/cli.js
CHANGED
|
@@ -56,9 +56,14 @@ export function briefError(err) {
|
|
|
56
56
|
* `input` goes to its stdin: a text longer than a command line may be.
|
|
57
57
|
*/
|
|
58
58
|
export function runCli(entry, cwd, args, timeoutMs = 120_000, input) {
|
|
59
|
+
// A move from the board is the operator's: a board started inside a Claude Code session or a
|
|
60
|
+
// run would otherwise pass as the owner of that session's mark (Methodology §4), and its
|
|
61
|
+
// commits as the session's or the run's moves (`GCF-By`).
|
|
62
|
+
const { CLAUDE_CODE_SESSION_ID: _, GCF_RUN_OWNER: __, GCF_MOVE_BY: ___, GCF_RUN_ITEM: ____, ...env } = process.env;
|
|
59
63
|
return new Promise((resolve) => {
|
|
60
64
|
const child = spawn(process.execPath, [entry, ...args], {
|
|
61
65
|
cwd,
|
|
66
|
+
env,
|
|
62
67
|
shell: false,
|
|
63
68
|
stdio: ['pipe', 'pipe', 'pipe'],
|
|
64
69
|
});
|