gcf-board 0.4.1 → 0.6.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.
Files changed (36) hide show
  1. package/README.md +9 -8
  2. package/dist/server/app.js +259 -25
  3. package/dist/server/chat.js +67 -0
  4. package/dist/server/cli.js +11 -4
  5. package/dist/server/desktop.js +17 -3
  6. package/dist/server/events.js +15 -1
  7. package/dist/server/files.js +8 -4
  8. package/dist/server/mcp.js +28 -0
  9. package/dist/server/moves.js +11 -0
  10. package/dist/server/propose.js +96 -0
  11. package/dist/server/relay.js +50 -0
  12. package/dist/server/runs.js +237 -166
  13. package/dist/server/talks.js +498 -0
  14. package/dist/web/assets/{index-DCkdSzDJ.css → index-BYAEKw51.css} +1 -1
  15. package/dist/web/assets/index-D_F7OEyk.js +36 -0
  16. package/dist/web/index.html +2 -2
  17. package/node_modules/gcf-session/lib/activity.js +371 -0
  18. package/node_modules/gcf-session/lib/adapter/claude.js +226 -0
  19. package/node_modules/gcf-session/lib/adapter/index.js +33 -0
  20. package/node_modules/gcf-session/lib/chat-input.js +260 -0
  21. package/node_modules/gcf-session/lib/chat.js +832 -0
  22. package/node_modules/gcf-session/lib/cli.js +52 -0
  23. package/node_modules/gcf-session/lib/cost.js +29 -0
  24. package/node_modules/gcf-session/lib/index.js +58 -0
  25. package/node_modules/gcf-session/lib/job.js +417 -0
  26. package/node_modules/gcf-session/lib/limit.js +132 -0
  27. package/node_modules/gcf-session/lib/lock.js +81 -0
  28. package/node_modules/gcf-session/lib/proc.js +93 -0
  29. package/node_modules/gcf-session/lib/session.js +320 -0
  30. package/node_modules/gcf-session/lib/store.js +28 -0
  31. package/node_modules/gcf-session/lib/thread.js +423 -0
  32. package/node_modules/gcf-session/lib/windows.js +46 -0
  33. package/node_modules/gcf-session/package.json +23 -0
  34. package/node_modules/gcf-session/types/index.d.ts +152 -0
  35. package/package.json +10 -3
  36. package/dist/web/assets/index-CCeftHBL.js +0 -34
package/README.md CHANGED
@@ -6,7 +6,8 @@ A local web board for game projects on [GCF](../gcf-aif-ext): the items by statu
6
6
 
7
7
  - Node.js ≥ 22.18
8
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.8 and Claude Code (`claude -p`)
9
+ - for runs: [`gcf-harness-aif-ext`](../gcf-harness-aif-ext) ≥ 0.11 (every board run opens its chat: `--chat`, `--chat-timeout`, `gcf-harness chat`) 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
10
11
  - gcf-board 0.2 needs `gcf-aif-ext` ≥ 0.7 (priority, questions, session marks, `run_mode`)
11
12
 
12
13
  ## Run
@@ -44,7 +45,7 @@ The board knows no domain by name: the project's board read gives its columns, m
44
45
  - `run_mode: worktree`: one worktree and one agent session per item, all at once, then the integrator;
45
46
  - `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.
46
47
 
47
- 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. 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 card reads **paused: limit** and the board resumes it by itself at the reset time; the header shows **resumes HH:MM** with **cancel**, and a queue the limit paused resumes only by that clock until the operator cancels it; a pause after a failure keeps its **resume** button. 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 or started, a resume run or cancelled. A run confirmation names what each interrupted item picks up. The queue, the reports and that list live in the board's memory: a board restart forgets them.
48
+ 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. 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/`).
48
49
  - **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`).
49
50
  - **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.
50
51
  - **Priority**: drop a ready card on another to put it before; the column's ranks are committed (`gcf prioritize`).
@@ -52,6 +53,8 @@ The board knows no domain by name: the project's board read gives its columns, m
52
53
  - **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.
53
54
  - **Help** (**?**): the domain's terms, columns, moves and field values with what each means, and the words of runs, under one filter.
54
55
  - **Settings**: the keys of `gcf/config.yml` and the agents' language (`language.ui`, `language.artifacts` of `.ai-factory/config.yaml`), each a `gcf config set` commit.
56
+ - **Chat** (data only, the page waits for its design; harness 0.11.1, core 0.11.1): every run the board starts keeps its agent sessions open; the project's `chat:` settings (Settings tab: `chat.ask`, `chat.answer_timeout_min`) say what the agent asks and how long a question waits. `GET /api/p/<project>/chat/<id>` follows the item's chat from its start, in raw chunks of JSON lines (the page splits them): the talk, the questions, the run's milestones, its sessions and context share. `POST` there sends `{type: 'say', text, images?}`, `{type: 'interrupt'}` or `{type: 'answer', request_id, answers}` through `gcf-harness chat`: a message with no live session to read it gets 409, bad input 400. Until the chat screen ships, a board run waits for no answer (`--chat-timeout 0`). `GET /api/p/<project>/chat/<id>/att/<file>` serves a chat picture; the item move **attach** (`gcf item attach`) gives a file to the item.
57
+ - **Project chat** (data only, the page waits for its design; core 0.12): threads of an agent in the project's folder, 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**, **always** — saved in `.claude/settings.local.json` — or **deny**); a new item it proposes through the board's MCP server `gcf` (tool `propose_item_new`), and the operator's **Create** makes it with `POST /move` (`proposal: {talk, id}`). 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`; `GET …/talk/<t>/att/<file>` serves its pictures. The files live in `.gcf-session/chats/` (docs/Chat-Plan.md §3).
55
58
  - **Inbox**: add, erase, or turn an entry into an item. Open questions are listed there too.
56
59
  - **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.
57
60
  - **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`.
@@ -71,6 +74,7 @@ The board starts agents that write code and commit: whoever can talk to it runs
71
74
  - A change must come from the board's own page (`Origin`). This blocks another site in the same browser.
72
75
  - Commands run without a shell: the operator's text reaches `ai-factory` as one argument, never as a command line.
73
76
  - The API shows only item files, plans and run logs inside a project.
77
+ - 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.
74
78
 
75
79
  Do not put the port on a network. Remote and phone access is planned for v2, behind its own authentication.
76
80
 
@@ -78,15 +82,12 @@ Do not put the port on a network. Remote and phone access is planned for v2, beh
78
82
 
79
83
  - `~/.gcf/projects.json`: the projects on the board, `{projects: [{name, path}]}`.
80
84
  - `~/.gcf/board-token`: the token.
81
- - `GCF_BOARD_HOME` moves both; `GCF_BOARD_AIF` points at another `ai-factory` entry script.
85
+ - `~/.gcf/runs/`: the record of each run in flight, which a board started again finds.
86
+ - `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).
82
87
 
83
88
  ## Roadmap (v2)
84
89
 
85
- - **Chat with Claude in a project**:
86
- - `claude -p --output-format stream-json`;
87
- - a choice of model and effort;
88
- - permission prompts answered from the board through a `PermissionRequest` hook;
89
- - resume a session.
90
+ - **The chat screens**: an item's chat and the project chat, with a choice of model and effort.
90
91
  - **Phone and remote access**: Tailscale or Claude Remote Control, with their own authentication; push notifications when an item blocks or waits for a verdict.
91
92
 
92
93
  ## Develop
@@ -1,32 +1,37 @@
1
1
  // The board's HTTP server: the page, and an API that is a thin layer over `ai-factory gcf`.
2
2
  // Reads: projects, the board, a shown file, a run log, the playtest session, the run metrics
3
- // (`ai-factory <harness> metrics`, the domain's harness). Writes: a project on the board, a
4
- // move, a run. Every write is a command of the framework.
3
+ // (`ai-factory <harness> metrics`, the domain's harness), the project chat's threads. Writes: a
4
+ // project on the board, a move, a run, a project chat message. Every write of the project is a
5
+ // command of the framework; a project chat's agent asks the operator for each one (talks.ts).
5
6
  import { randomBytes } from 'node:crypto';
6
7
  import { createServer } from 'node:http';
7
- import { existsSync, statSync } from 'node:fs';
8
- import { readFile } from 'node:fs/promises';
8
+ import { existsSync, statSync, writeFileSync } from 'node:fs';
9
+ import { lstat, mkdtemp, readFile, rm } from 'node:fs/promises';
10
+ import os from 'node:os';
9
11
  import path from 'node:path';
10
- import { BOARD_SCHEMA } from '../shared/board.js';
12
+ import { BOARD_SCHEMA, } from '../shared/board.js';
11
13
  import { admit, cookieName, hostAllowed, tokenInUrl } from './auth.js';
12
14
  import { briefError, runCli } from './cli.js';
13
15
  import { broadcast, planRev, subscribe, watchProject } from './events.js';
14
- import { followLog, readShown, shownShape } from './files.js';
16
+ import { CHAT_BODY_MAX, chatInput, IMAGE_EXT, talkInput } from './chat.js';
17
+ import { follow, followLog, readShown, shownShape } from './files.js';
15
18
  import { HttpError } from './http-error.js';
16
- import { isCenterMove, moveArgs, runIds } from './moves.js';
19
+ import { isCenterMove, moveArgs, moveInput, runIds } from './moves.js';
17
20
  import { addProject, listProjects, projectOf, removeProject } from './registry.js';
18
- import { cancelResume, closeReport, forgetProject, resumeQueue, runsOf, startRun, unqueue, } from './runs.js';
21
+ import { adoptRuns, closeReport, forgetProject, resumeQueue, runsOf, startRun, unqueue, } from './runs.js';
22
+ import { acceptProposal, chatOf, listTalks, openTalk, prepareTalk, startTalk, talkId, talkLive, talkWaits, watchTalks, writeTalk, } from './talks.js';
23
+ import { threadDir } from 'gcf-session';
19
24
  const send = (res, status, body) => {
20
25
  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
21
26
  res.end(JSON.stringify(body));
22
27
  };
23
- async function bodyOf(req) {
28
+ async function bodyOf(req, limit = 1_000_000) {
24
29
  // Bytes first, text once: a letter cut between two chunks stays whole.
25
30
  const chunks = [];
26
31
  let size = 0;
27
32
  for await (const chunk of req) {
28
33
  size += chunk.length;
29
- if (size > 1_000_000)
34
+ if (size > limit)
30
35
  throw new HttpError(413, 'request too large');
31
36
  chunks.push(chunk);
32
37
  }
@@ -50,6 +55,13 @@ function jsonOf(r, what) {
50
55
  throw new HttpError(502, `ai-factory ${what} gave no report: ${(r.err || r.out).trim()}`);
51
56
  }
52
57
  }
58
+ /** The ids a board read knows: its items, accepted and killed ones too. */
59
+ const idsOf = (b) => new Set([
60
+ ...b.items.map((i) => i.id),
61
+ ...(b.history ?? []).map((h) => h.id),
62
+ ...(b.graveyard ?? []).map((g) => g.id),
63
+ ]);
64
+ const SLUG = /^[a-z0-9][a-z0-9-]*$/;
53
65
  /** The ISO time a file was last written, or null when it is not there. */
54
66
  const activeAt = (file) => {
55
67
  try {
@@ -89,6 +101,20 @@ async function sendPage(res, web, pathname) {
89
101
  res.writeHead(200, { 'content-type': TYPES[path.extname(file)] ?? 'application/octet-stream' });
90
102
  res.end(await readFile(file));
91
103
  }
104
+ /**
105
+ * The usage limit is one for the account: the newest `quota.json` any project's harness wrote
106
+ * (Board-PRD decision 17), or null. A missing or broken file is no reading.
107
+ */
108
+ async function lastQuota() {
109
+ const read = (p) => readFile(path.join(p.path, '.gcf-session', 'runs', 'quota.json'), 'utf8')
110
+ .then((t) => JSON.parse(t))
111
+ .catch(() => null);
112
+ const seen = (await Promise.all((await listProjects()).map(read))).filter((q) => typeof q?.at === 'string' &&
113
+ !Number.isNaN(Date.parse(q.at)) &&
114
+ typeof q.info === 'object' &&
115
+ q.info !== null);
116
+ return seen.sort((a, b) => Date.parse(b.at) - Date.parse(a.at))[0] ?? null;
117
+ }
92
118
  export function createApp(o) {
93
119
  const watchers = new Map();
94
120
  let closed = false;
@@ -98,10 +124,17 @@ export function createApp(o) {
98
124
  if (closed)
99
125
  return;
100
126
  for (const p of projects)
101
- if (!watchers.has(p.name))
102
- watchers.set(p.name, watchProject(p));
127
+ if (!watchers.has(p.name)) {
128
+ const stops = [
129
+ watchProject(p),
130
+ watchTalks(p, () => broadcast({ type: 'talks', project: p.name }), async (t) => prepareTalk(p, await boardOf(p), t)),
131
+ ];
132
+ watchers.set(p.name, () => stops.forEach((stop) => stop()));
133
+ // The runs a board before this one started go on: show them, and their ends.
134
+ adoptRuns(o.entry, p);
135
+ }
103
136
  };
104
- const cli = (p, args, timeout) => runCli(o.entry, p.path, args, timeout);
137
+ const cli = (p, args, timeout, input) => runCli(o.entry, p.path, args, timeout, input);
105
138
  // The last domain each project's board read gave: an item move is built from its form.
106
139
  const domains = new Map();
107
140
  /**
@@ -130,6 +163,38 @@ export function createApp(o) {
130
163
  domains.set(p.name, board.domain);
131
164
  return board;
132
165
  };
166
+ /**
167
+ * The operator's input into thread `t`. A message or a fresh agent starts the thread's engine
168
+ * when no session of it lives, with what it runs by written fresh from the board read (`board`,
169
+ * or one read now); the rest needs a live session (409).
170
+ */
171
+ const sendTalk = async (p, t, input, board) => {
172
+ const live = talkLive(p, t);
173
+ if (!live && input.type !== 'say' && input.type !== 'handoff')
174
+ throw new HttpError(409, `thread ${t} has no live agent: nothing sent`);
175
+ // Nothing runs while it waits for the limit: a stop would cut the turn after the reset.
176
+ if (live && input.type !== 'say' && talkWaits(p, t))
177
+ throw new HttpError(409, `thread ${t} waits for the usage limit: only a message waits`);
178
+ if (!live)
179
+ await prepareTalk(p, board ?? (await boardOf(p)), t);
180
+ const line = writeTalk(p, t, input);
181
+ if (!live)
182
+ startTalk(p, t);
183
+ broadcast({ type: 'talks', project: p.name });
184
+ return line;
185
+ };
186
+ /**
187
+ * A message to item `item`'s thread of the project chat (AD-49), when the project has one and
188
+ * the board read knows the item: the thread's id, else null.
189
+ */
190
+ const toThread = async (p, item, line) => {
191
+ const board = await boardOf(p).catch(() => null);
192
+ if (!board?.domain.chat || !board.agent?.rules || !idsOf(board).has(item))
193
+ return null;
194
+ const t = openTalk(p, item).id;
195
+ await sendTalk(p, t, line, board);
196
+ return t;
197
+ };
133
198
  const routes = [
134
199
  ['GET', /^\/api\/events$/, async (_req, res) => subscribe(res)],
135
200
  ['GET', /^\/api\/projects$/, async (_req, res) => send(res, 200, await listProjects())],
@@ -165,7 +230,12 @@ export function createApp(o) {
165
230
  const p = await projectOf(m[1]);
166
231
  // The board's own runs ride along: what it started and what waits in its queue; and the
167
232
  // count of plan writes, which tells the page an open plan's text changed.
168
- const own = { runs: runsOf(p.name), plans_rev: planRev(p.name), board_version: o.version };
233
+ const own = {
234
+ runs: runsOf(p.name),
235
+ plans_rev: planRev(p.name),
236
+ board_version: o.version,
237
+ quota: await lastQuota(),
238
+ };
169
239
  const board = await boardOf(p);
170
240
  // A running item's last log write tells a working session from a stuck one; a run's
171
241
  // lock is this board's run or a console's.
@@ -199,6 +269,161 @@ export function createApp(o) {
199
269
  followLog((await projectOf(m[1])).path, m[2], res);
200
270
  },
201
271
  ],
272
+ [
273
+ // An item's chat as it grows: one event a line (docs/Chat-Plan.md).
274
+ 'GET',
275
+ /^\/api\/p\/([^/]+)\/chat\/([a-z0-9][a-z0-9-]*)$/,
276
+ async (_req, res, m) => {
277
+ followLog((await projectOf(m[1])).path, m[2], res, 'chat.jsonl');
278
+ },
279
+ ],
280
+ [
281
+ // A picture of an item's chat (`<id>.att/`, where `gcf-harness chat` put it); never through
282
+ // a link. "Attach to item" gives it to the item with the domain's `attach` move.
283
+ 'GET',
284
+ /^\/api\/p\/([^/]+)\/chat\/([a-z0-9][a-z0-9-]*)\/att\/([0-9a-f]{8}\.(png|jpe?g|gif|webp))$/,
285
+ async (_req, res, m) => {
286
+ const p = await projectOf(m[1]);
287
+ const session = path.join(p.path, '.gcf-session');
288
+ const att = path.join(session, 'runs', `${m[2]}.att`);
289
+ const file = path.join(att, m[3]);
290
+ for (const f of [session, path.dirname(att), att, file]) {
291
+ const st = await lstat(f).catch(() => null);
292
+ if (!st || st.isSymbolicLink())
293
+ throw new HttpError(404, `no picture ${m[3]}`);
294
+ }
295
+ const type = m[4] === 'jpg' ? 'jpeg' : m[4];
296
+ res.writeHead(200, { 'content-type': `image/${type}`, 'cache-control': 'private' });
297
+ res.end(await readFile(file));
298
+ },
299
+ ],
300
+ [
301
+ // The operator writes into an item's chat: the run's session reads it on.
302
+ 'POST',
303
+ /^\/api\/p\/([^/]+)\/chat\/([a-z0-9][a-z0-9-]*)$/,
304
+ // The harness's own command writes it (`<harness> chat`): it checks the input, the links
305
+ // and that a live session takes it, so a message nobody would read is refused (409).
306
+ async (req, res, m) => {
307
+ const p = await projectOf(m[1]);
308
+ const line = chatInput(await bodyOf(req, CHAT_BODY_MAX));
309
+ let harness;
310
+ try {
311
+ harness = await harnessOf(p);
312
+ }
313
+ catch (e) {
314
+ // No harness, so no run: a message goes to the item's thread all the same.
315
+ const t = line.type === 'say' ? await toThread(p, m[2], line) : null;
316
+ if (t)
317
+ return send(res, 202, { ok: true, talk: t });
318
+ throw e;
319
+ }
320
+ const chat = [harness, 'chat', m[2]];
321
+ const tmp = await mkdtemp(path.join(os.tmpdir(), 'gcf-board-chat-'));
322
+ try {
323
+ let args = [...chat, 'interrupt'];
324
+ let input;
325
+ if (line.type === 'say') {
326
+ const images = (line.images ?? []).map((im, i) => {
327
+ const file = path.join(tmp, `${i}${IMAGE_EXT[im.media_type]}`);
328
+ writeFileSync(file, Buffer.from(im.data, 'base64'));
329
+ return ['--image', file];
330
+ });
331
+ args = [...chat, 'say', '--text-file', '-', ...images.flat()];
332
+ input = line.text;
333
+ }
334
+ else if (line.type === 'answer') {
335
+ args = [...chat, 'answer', line.request_id, '--answers-file', '-'];
336
+ input = JSON.stringify(line.answers);
337
+ }
338
+ const r = await runCli(o.entry, p.path, args, undefined, input);
339
+ if (r.ok)
340
+ return send(res, 202, { ok: true });
341
+ // No live run session: a message goes to the item's thread of the project chat (AD-49).
342
+ // An item the board read knows: a stale or mistyped id gets no thread.
343
+ const t = r.code === 3 && line.type === 'say' ? await toThread(p, m[2], line) : null;
344
+ if (t)
345
+ return send(res, 202, { ok: true, talk: t });
346
+ const why = briefError(r.err || r.out).replace(/^[\w-]+ chat: /, '');
347
+ if (/unknown command 'chat'/.test(why))
348
+ throw new HttpError(400, 'the chat needs gcf-harness-aif-ext 0.11.0 or later');
349
+ throw new HttpError(r.code === 3 ? 409 : r.code === 1 ? 400 : 500, why);
350
+ }
351
+ finally {
352
+ await rm(tmp, { recursive: true, force: true });
353
+ }
354
+ },
355
+ ],
356
+ [
357
+ // The project chat's threads (AD-46: `?item=` its bound one), newest first.
358
+ 'GET',
359
+ /^\/api\/p\/([^/]+)\/talks$/,
360
+ async (_req, res, m, url) => {
361
+ const p = await projectOf(m[1]);
362
+ const item = url.searchParams.get('item') ?? undefined;
363
+ const talks = await listTalks(p, async () => idsOf(await boardOf(p)), item);
364
+ send(res, 200, { talks });
365
+ },
366
+ ],
367
+ [
368
+ // A new thread, or the item's one (AD-46): the same thread for two calls.
369
+ 'POST',
370
+ /^\/api\/p\/([^/]+)\/talks$/,
371
+ async (req, res, m) => {
372
+ const p = await projectOf(m[1]);
373
+ const { item = null } = await bodyOf(req);
374
+ if (item !== null && (typeof item !== 'string' || !SLUG.test(item)))
375
+ throw new HttpError(400, 'item must be an item id');
376
+ const board = await boardOf(p);
377
+ chatOf(board);
378
+ if (item && !idsOf(board).has(item))
379
+ throw new HttpError(404, `no item ${item}`);
380
+ const { id, created } = openTalk(p, item);
381
+ await prepareTalk(p, board, id);
382
+ broadcast({ type: 'talks', project: p.name });
383
+ send(res, created ? 201 : 200, { id, created });
384
+ },
385
+ ],
386
+ [
387
+ // A thread's chat as it grows, from its start: one event a line.
388
+ 'GET',
389
+ /^\/api\/p\/([^/]+)\/talk\/([^/]+)$/,
390
+ async (_req, res, m) => {
391
+ const p = await projectOf(m[1]);
392
+ follow(p.path, path.join(threadDir(p.path, talkId(m[2])), 'chat.jsonl'), res, true);
393
+ },
394
+ ],
395
+ [
396
+ // The operator writes into a thread: a message starts its agent when none lives.
397
+ 'POST',
398
+ /^\/api\/p\/([^/]+)\/talk\/([^/]+)$/,
399
+ async (req, res, m) => {
400
+ const p = await projectOf(m[1]);
401
+ const t = talkId(m[2]);
402
+ if (!existsSync(threadDir(p.path, t)))
403
+ throw new HttpError(404, `no thread ${t}`);
404
+ const line = await sendTalk(p, t, talkInput(await bodyOf(req, CHAT_BODY_MAX)));
405
+ send(res, 202, { ok: true, ...(typeof line.id === 'string' ? { id: line.id } : {}) });
406
+ },
407
+ ],
408
+ [
409
+ // A picture of a thread (`att/`, where the board put it); never through a link.
410
+ 'GET',
411
+ /^\/api\/p\/([^/]+)\/talk\/([^/]+)\/att\/([0-9a-f]{8}\.(png|jpe?g|gif|webp))$/,
412
+ async (_req, res, m) => {
413
+ const p = await projectOf(m[1]);
414
+ const td = threadDir(p.path, talkId(m[2]));
415
+ const file = path.join(td, 'att', m[3]);
416
+ const chats = path.dirname(td);
417
+ for (const f of [path.dirname(chats), chats, td, path.dirname(file), file]) {
418
+ const st = await lstat(f).catch(() => null);
419
+ if (!st || st.isSymbolicLink())
420
+ throw new HttpError(404, `no picture ${m[3]}`);
421
+ }
422
+ const type = m[4] === 'jpg' ? 'jpeg' : m[4];
423
+ res.writeHead(200, { 'content-type': `image/${type}`, 'cache-control': 'private' });
424
+ res.end(await readFile(file));
425
+ },
426
+ ],
202
427
  [
203
428
  'GET',
204
429
  /^\/api\/p\/([^/]+)\/playtest$/,
@@ -236,7 +461,24 @@ export function createApp(o) {
236
461
  const domain = isCenterMove(body.cmd)
237
462
  ? undefined
238
463
  : (domains.get(p.name) ?? (await boardOf(p)).domain);
239
- const r = await cli(p, moveArgs(body, domain?.moves));
464
+ const args = moveArgs(body, domain?.moves);
465
+ const run = () => cli(p, args, undefined, moveInput(body, domain?.moves));
466
+ // An agent's proposal made (AD-16, AD-33): its record goes with the move.
467
+ const { talk, id } = (body.proposal ?? {});
468
+ let r;
469
+ if (body.proposal === undefined)
470
+ r = await run();
471
+ else {
472
+ if (typeof talk !== 'string' || typeof id !== 'string' || !/^[\w-]+$/.test(id))
473
+ throw new HttpError(400, 'a proposal names its talk and its id');
474
+ // Only a move an agent may propose: a line planted in the chat is no proposal of one.
475
+ if (!domain?.moves[String(body.cmd)]?.propose)
476
+ throw new HttpError(400, `${String(body.cmd)} is not a move an agent proposes`);
477
+ const item = typeof body.id === 'string' ? body.id : '';
478
+ const ids = idsOf(await boardOf(p));
479
+ r = await acceptProposal(p, talk, id, String(body.cmd), item, ids, run);
480
+ broadcast({ type: 'talks', project: p.name });
481
+ }
240
482
  broadcast({ type: 'board', project: p.name });
241
483
  send(res, 200, { ok: r.ok, out: r.out.trim(), err: briefError(r.err) });
242
484
  },
@@ -256,7 +498,8 @@ export function createApp(o) {
256
498
  if (!domain.harness)
257
499
  throw new HttpError(400, 'this project has no harness: its items run from a console');
258
500
  const ids = runIds(body);
259
- send(res, 202, startRun(o.entry, p, ids, mode, body.fresh === true, domain.harness));
501
+ const fresh = body.fresh === true;
502
+ send(res, 202, startRun(o.entry, p, ids, mode, fresh, domain.harness));
260
503
  },
261
504
  ],
262
505
  [
@@ -289,15 +532,6 @@ export function createApp(o) {
289
532
  send(res, 200, { ok: true });
290
533
  },
291
534
  ],
292
- [
293
- // The resume a usage limit scheduled; the queue stays paused.
294
- 'DELETE',
295
- /^\/api\/p\/([^/]+)\/schedule$/,
296
- async (_req, res, m) => {
297
- cancelResume((await projectOf(m[1])).name);
298
- send(res, 200, { ok: true });
299
- },
300
- ],
301
535
  [
302
536
  'DELETE',
303
537
  /^\/api\/p\/([^/]+)\/reports\/(r\d+)$/,
@@ -0,0 +1,67 @@
1
+ import { HttpError } from './http-error.js';
2
+ /** A chat message may carry images: a body up to 10 MB. */
3
+ export const CHAT_BODY_MAX = 10_000_000;
4
+ /** The file a picture of each type is handed to the harness as. */
5
+ export const IMAGE_EXT = {
6
+ 'image/png': '.png',
7
+ 'image/jpeg': '.jpg',
8
+ 'image/gif': '.gif',
9
+ 'image/webp': '.webp',
10
+ };
11
+ const IMAGE_TYPES = Object.keys(IMAGE_EXT);
12
+ const BASE64 = /^[A-Za-z0-9+/]+={0,2}$/;
13
+ const TEXT_MAX = 64_000;
14
+ // About 5 MB of image, the most one image may be.
15
+ const IMAGE_MAX = 6_990_000;
16
+ const bad = (why) => new HttpError(400, `chat: ${why}`);
17
+ function images(v) {
18
+ if (v === undefined)
19
+ return [];
20
+ if (!Array.isArray(v) || v.length > 10)
21
+ throw bad('images is a list of up to 10');
22
+ return v.map((i) => {
23
+ const { media_type: type, data } = (i ?? {});
24
+ if (!IMAGE_TYPES.includes(type))
25
+ throw bad(`an image is ${IMAGE_TYPES.join(', ')}`);
26
+ if (typeof data !== 'string' || data.length > IMAGE_MAX || !BASE64.test(data))
27
+ throw bad('an image is base64 data, up to 5 MB');
28
+ return { media_type: type, data };
29
+ });
30
+ }
31
+ /** The line a request writes into the chat input: a message, a stop of the step, an answer. */
32
+ export function chatInput(body) {
33
+ if (body.type === 'interrupt')
34
+ return { type: 'interrupt' };
35
+ if (body.type === 'say') {
36
+ const { text } = body;
37
+ if (typeof text !== 'string' || !text.trim() || text.length > TEXT_MAX)
38
+ throw bad(`a message is text, up to ${TEXT_MAX} characters`);
39
+ const list = images(body.images);
40
+ return list.length ? { type: 'say', text, images: list } : { type: 'say', text };
41
+ }
42
+ if (body.type === 'answer') {
43
+ const { request_id: id, answers } = body;
44
+ const values = Object.values((answers ?? {}));
45
+ const map = typeof answers === 'object' && answers !== null && !Array.isArray(answers);
46
+ // The id goes to `gcf-harness chat` as a word: one like `--help` would be an option.
47
+ if (typeof id !== 'string' || !/^[A-Za-z0-9_][\w-]*$/.test(id) || !map)
48
+ throw bad('an answer names its request_id and its answers');
49
+ if (!values.length || values.some((x) => typeof x !== 'string'))
50
+ throw bad('each answer is text');
51
+ return { type: 'answer', request_id: id, answers: answers };
52
+ }
53
+ throw bad('type is say, interrupt or answer');
54
+ }
55
+ /** The line a request writes into a project chat thread: an item chat's, a card's, a handoff. */
56
+ export function talkInput(body) {
57
+ if (body.type === 'handoff')
58
+ return { type: 'handoff' };
59
+ if (body.type !== 'allow' && body.type !== 'deny')
60
+ return chatInput(body);
61
+ const id = body.request_id;
62
+ if (typeof id !== 'string' || !/^[A-Za-z0-9_][\w-]*$/.test(id))
63
+ throw bad(`${body.type} names its request_id`);
64
+ if (body.type === 'deny')
65
+ return { type: 'deny', request_id: id };
66
+ return { type: 'allow', request_id: id, always: body.always === true };
67
+ }
@@ -49,16 +49,23 @@ function globalRoots() {
49
49
  */
50
50
  export function briefError(err) {
51
51
  const m = err.match(/^\w*Error: ([\s\S]*?)\r?\n {4}at /m) ?? err.match(/^\w*Error: (.+)$/m);
52
- return (m?.[1] ?? err).replace(/\r/g, '').trim();
52
+ return (m?.[1] ?? err).replaceAll('\r', '').trim();
53
53
  }
54
- /** Run `ai-factory <args>` in a project; a move can wait up to a minute on gcf's main lock. */
55
- export function runCli(entry, cwd, args, timeoutMs = 120_000) {
54
+ /**
55
+ * Run `ai-factory <args>` in a project; a move can wait up to a minute on gcf's main lock.
56
+ * `input` goes to its stdin: a text longer than a command line may be.
57
+ */
58
+ export function runCli(entry, cwd, args, timeoutMs = 120_000, input) {
56
59
  return new Promise((resolve) => {
57
60
  const child = spawn(process.execPath, [entry, ...args], {
58
61
  cwd,
59
62
  shell: false,
60
- stdio: ['ignore', 'pipe', 'pipe'],
63
+ stdio: ['pipe', 'pipe', 'pipe'],
61
64
  });
65
+ // No input is an empty stdin. A command that ends before it reads it breaks the pipe: its
66
+ // exit says why.
67
+ child.stdin.on('error', () => { });
68
+ child.stdin.end(input);
62
69
  // A decoder per stream: a Cyrillic letter cut between two chunks stays one letter.
63
70
  child.stdout.setEncoding('utf8');
64
71
  child.stderr.setEncoding('utf8');
@@ -24,6 +24,19 @@ export function openInBrowser(url) {
24
24
  }
25
25
  /** A PowerShell single-quoted string: a quote inside is doubled. */
26
26
  const psQuote = (s) => `'${s.replaceAll("'", "''")}'`;
27
+ /** A POSIX shell single-quoted string: nothing inside expands; a quote closes, escapes, reopens. */
28
+ const shQuote = (s) => `'${s.replaceAll("'", `'\\''`)}'`;
29
+ /**
30
+ * A quoted .desktop Exec argument: `"`, `` ` ``, `$` and `\` escaped inside the quotes, then the
31
+ * key's own string escape doubles each backslash and writes a line break as `\n` (a raw one would
32
+ * end the key), and `%` (a field code) is written `%%`.
33
+ */
34
+ const execQuote = (s) => `"${s.replace(/["`$\\]/g, '\\$&')}"`
35
+ .replaceAll('\\', '\\\\')
36
+ .replaceAll('\n', '\\n')
37
+ .replaceAll('\r', '\\r')
38
+ .replaceAll('\t', '\\t')
39
+ .replaceAll('%', '%%');
27
40
  export function shortcutPlan(platform, node, main, port) {
28
41
  const args = ['--port', String(port)];
29
42
  if (platform === 'win32')
@@ -41,15 +54,16 @@ export function shortcutPlan(platform, node, main, port) {
41
54
  `Join-Path $d '${NAME}.lnk'`,
42
55
  ].join('; '),
43
56
  };
44
- const command = `"${node}" "${main}" ${args.join(' ')}`;
57
+ // A `$(…)` or a quote in an install path stays part of the path.
58
+ const command = (quote) => [quote(node), quote(main), ...args].join(' ');
45
59
  if (platform === 'darwin')
46
60
  return {
47
61
  file: path.join(os.homedir(), 'Desktop', `${NAME}.command`),
48
- text: `#!/bin/sh\nexec ${command}\n`,
62
+ text: `#!/bin/sh\nexec ${command(shQuote)}\n`,
49
63
  };
50
64
  return {
51
65
  file: path.join(os.homedir(), '.local', 'share', 'applications', 'gcf-board.desktop'),
52
- text: `[Desktop Entry]\nType=Application\nName=${NAME}\nExec=${command}\nTerminal=false\n` +
66
+ text: `[Desktop Entry]\nType=Application\nName=${NAME}\nExec=${command(execQuote)}\nTerminal=false\n` +
53
67
  'Categories=Development;\n',
54
68
  };
55
69
  }
@@ -30,7 +30,7 @@ export function broadcast(event) {
30
30
  // reports a mark's expiry.
31
31
  const SESSION_TTL_MS = 120 * 60_000;
32
32
  const LOG_STEP_MS = 10_000;
33
- const alive = (pid) => {
33
+ export const alive = (pid) => {
34
34
  if (!Number.isInteger(pid) || pid <= 0)
35
35
  return false;
36
36
  try {
@@ -113,11 +113,25 @@ export function watchProject(p, debounceMs = 300) {
113
113
  });
114
114
  const runs = path.join(p.path, '.gcf-session', 'runs');
115
115
  let last = runsState(runs);
116
+ const quotaAt = () => {
117
+ try {
118
+ return statSync(path.join(runs, 'quota.json')).mtimeMs;
119
+ }
120
+ catch {
121
+ return 0;
122
+ }
123
+ };
124
+ let read = quotaAt();
116
125
  const poll = setInterval(() => {
117
126
  const now = runsState(runs);
118
127
  if (now !== last)
119
128
  fire();
120
129
  last = now;
130
+ // The limit is the account's: a new reading here changes every project's top bar.
131
+ const quota = quotaAt();
132
+ if (quota !== read)
133
+ broadcast({ type: 'quota' });
134
+ read = quota;
121
135
  }, 1500);
122
136
  return () => {
123
137
  for (const w of watchers)
@@ -57,12 +57,16 @@ async function inside(root, file) {
57
57
  }
58
58
  /**
59
59
  * Follow the run log of `id` as it grows: its last 256 KB first, then every new chunk, polled
60
- * each second (a log on another disk does not always fire a watch). A log that shrank was
60
+ * each second (a log on another disk does not always fire a watch). Its chat (`ext` chat.jsonl,
61
+ * docs/Chat-Plan.md) is the conversation's history: read from its start. A log that shrank was
61
62
  * started again: a `reset` event tells the page to drop what it holds, then it is read from its
62
63
  * start. One decoder for the stream: a letter cut between two reads stays whole.
63
64
  */
64
- export function followLog(root, id, res) {
65
- const file = path.join(root, '.gcf-session', 'runs', `${id}.log`);
65
+ export function followLog(root, id, res, ext = 'log') {
66
+ follow(root, path.join(root, '.gcf-session', 'runs', `${id}.${ext}`), res, ext !== 'log');
67
+ }
68
+ /** Follow `file` of the project as it grows, as `followLog` does; `whole`: from its start. */
69
+ export function follow(root, file, res, whole) {
66
70
  openStream(res);
67
71
  let pos = -1;
68
72
  let decoder = new StringDecoder('utf8');
@@ -71,7 +75,7 @@ export function followLog(root, id, res) {
71
75
  return;
72
76
  const { size } = await stat(file);
73
77
  if (pos < 0)
74
- pos = Math.max(0, size - 256 * 1024);
78
+ pos = whole ? 0 : Math.max(0, size - 256 * 1024);
75
79
  if (size < pos) {
76
80
  pos = 0;
77
81
  decoder = new StringDecoder('utf8');