gcf-board 0.16.2 → 0.16.3

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 CHANGED
@@ -61,7 +61,7 @@ The board knows no domain by name: the project's board read gives its columns, m
61
61
  - **Settings** (the header's gear): 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.
62
62
  - **Theme** (board 0.11.0, Board-PRD decision 26): Settings, "Board · this browser": **Dark (built-in)**, the designer's themes the board ships (`themes/`: Paper · soft, Cream · medium, Sand · contrast, Dusk · soft dark; board 0.14.0), or a theme file of `~/.gcf/themes/<id>.json`, which replaces a shipped one of its id — `{"gcf_theme": 1, "name", "scheme": "light" | "dark", "tokens": {…}}`, the colour tokens of `web/tokens.css` without `--gcf-` over the built-in dark (a template: docs/design/theme-sample.json). Each browser keeps its own choice; a file that cannot be read is listed with its reason, and the page falls back to dark when the chosen one is gone. Reload the page after changing a file. `GET /api/themes` lists the files.
63
63
  - **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.
64
- - **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`).
64
+ - **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 file picked on the operator's machine (`{kind: file, ref: <name>, data: <base64>}`, the composer's 📎) is written into `.gcf-session/uploads/` and goes as `file <its absolute path>`; a move's `file` field (`attach`) takes `{name, data}` the same way, its copy removed after the command; 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`).
65
65
  - **Functional base A** (board 0.10.0, core and harness 0.14.0; docs/Base-A-Plan.md): Settings has `session_timeout_min` and the project's `agent.model` / `agent.effort`; the drawer shows the project's model on an item without its own, "(project)". The drawer's Run is off with the run gate's reason when the gate refuses the item now, and the start dialog marks each refused item and runs the rest (`GET /api/p/<project>/gate?ids=` runs `gcf-harness gate --each`). An item's attachments and an inbox entry's pictures are links (`GET /api/p/<project>/attachment?path=`: only `gcf/work/<id>/attachments/` and `gcf/inbox/in-<hex>/attachments/`, no `..`, no link on the way, a picture shown, any other file a download, `nosniff` and `default-src 'none'`), and a picture or link in File or Plan that points there loads through it. A permission card for one MCP tool offers Always, saying it allows every call of the tool with any arguments.
66
66
  - **Model and effort** (board 0.8.0, core 0.12.3; a closed select since board 0.15.0, Board-PRD decision 33): pickers in the New item form, in the drawer (**change** beside the model and effort, and **model / effort** under **More**), in a thread's composer and in Settings (`agent.model` / `agent.effort`). Each is one select: Default first — "Default (Opus)" / "Default (High)", or "Default - project setting (Sonnet)" when the project sets one, and "Default - each item's own" in the run dialog; Default sends `default` — then the agent's presets by name (Fable, Opus, xHigh). Nothing set anywhere runs on Opus / High (decision 36). A thread's composer has no Default row: it shows what holds, and **↺ project** takes the thread's own pick off (board 0.16.2). No own word; a value set from the console that the presets lack shows as its own row, so a form sent unchanged keeps it. 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.
67
67
  - **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 proposed item has no id: the server asks `gcf item new --dry-run` for it, records it, then creates the item with it, so a board that stops halfway does not make it twice. An inbox entry the agent proposed is filed with origin `agent`: the server adds `--origin=agent`, never from the request. With core 0.16 (board 0.12.0, Board-PRD decision 27) it also proposes a move on an item or an inbox entry already there — `block`, `drop`, `depends`, and the inbox's `add` (with its category), sort, Later and erase (sort and Later with core 0.18, board 0.15.0) — naming it in `id`: the card shows the item's id, title and status now (or the entry's first line), warns when the item does not take the move now or is not on the board, its button is the move's name (a drop or an erase asks first), and **Edit…** opens that move's 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).
@@ -15,10 +15,11 @@ import { BOARD_SCHEMA, runModeOf, } from '../shared/board.js';
15
15
  import { admit, cookieName, hostAllowed, tokenInUrl } from './auth.js';
16
16
  import { briefError, runCli } from './cli.js';
17
17
  import { broadcast, planRev, SESSION_TTL_MIN, subscribe, watchProject } from './events.js';
18
- import { attachesUnit, CHAT_BODY_MAX, chatInput, IMAGE_EXT, talkInput, } from './chat.js';
18
+ import { attachesUnit, CHAT_BODY_MAX, chatInput, IMAGE_EXT, talkInput, withUploads, } from './chat.js';
19
19
  import { attachmentOf, follow, followLog, logPart, readShown, shownShape } from './files.js';
20
20
  import { HttpError } from './http-error.js';
21
21
  import { isCenterMove, moveArgs, moveInput, runIds } from './moves.js';
22
+ import { isUpload, saveUpload, UPLOAD_MAX } from './upload.js';
22
23
  import { addProject, listProjects, projectOf, removeProject } from './registry.js';
23
24
  import { allThemes } from './themes.js';
24
25
  import { adoptRuns, busyCheck, keepProjects, sweepRuns, closeReport, forgetProject, resumeQueue, runsOf, startRun, unqueue, } from './runs.js';
@@ -448,6 +449,7 @@ export function createApp(o) {
448
449
  async (req, res, m) => {
449
450
  const p = await projectOf(m[1]);
450
451
  const body = await bodyOf(req, CHAT_BODY_MAX);
452
+ await withUploads(p.path, body);
451
453
  const line = chatInput(body, await unitsFor(p, body));
452
454
  let harness;
453
455
  try {
@@ -545,6 +547,7 @@ export function createApp(o) {
545
547
  if (!existsSync(threadDir(p.path, t)))
546
548
  throw new HttpError(404, `no thread ${t}`);
547
549
  const body = await bodyOf(req, CHAT_BODY_MAX);
550
+ await withUploads(p.path, body);
548
551
  const line = await sendTalk(p, t, talkInput(body, await unitsFor(p, body)));
549
552
  send(res, 202, { ok: true, ...(typeof line.id === 'string' ? { id: line.id } : {}) });
550
553
  },
@@ -629,59 +632,75 @@ export function createApp(o) {
629
632
  /^\/api\/p\/([^/]+)\/move$/,
630
633
  async (req, res, m) => {
631
634
  const p = await projectOf(m[1]);
632
- // A designer's bundle comes back through a move: as large as a GDD.
633
- const body = await bodyOf(req, GDD_BODY_MAX);
635
+ // A designer's bundle comes back through a move: as large as a GDD; a picked file, as
636
+ // large as an attachment.
637
+ const body = await bodyOf(req, Math.max(GDD_BODY_MAX, UPLOAD_MAX + 100_000));
634
638
  const domain = isCenterMove(body.cmd)
635
639
  ? undefined
636
640
  : (domains.get(p.name) ?? (await boardOf(p)).domain);
637
- // A proposal of a Draft thread makes the entry's item (Board-V2-Data-Plan §2.7): the
638
- // entry goes with it while it is there; a second proposal, or one after it went, has none.
639
- const proposal = (body.proposal ?? {});
640
- if (typeof proposal.talk === 'string' && body.from === undefined) {
641
- // A thread that is not there has no entry: acceptProposal says it is not there.
642
- const entry = existsSync(threadDir(p.path, talkId(proposal.talk)))
643
- ? talkEntry(p, proposal.talk)
644
- : null;
645
- const board = entry ? await boardOf(p) : null;
646
- if (board &&
647
- board.domain.new_item === body.cmd &&
648
- board.inbox?.some((e) => e.id === entry))
649
- body.from = entry;
650
- }
651
- let args = moveArgs(body, domain?.moves);
652
- const run = () => cli(p, args, undefined, moveInput(body, domain?.moves));
653
- // An agent's proposal made (AD-16, AD-33): its record goes with the move.
654
- const { talk, id } = (body.proposal ?? {});
641
+ // A file the operator picked on their machine goes to the command as its written copy.
642
+ const uploads = [];
643
+ for (const f of domain?.moves[String(body.cmd)]?.fields ?? [])
644
+ if (f.kind === 'file' && isUpload(body[f.key])) {
645
+ const file = await saveUpload(p.path, body[f.key]);
646
+ uploads.push(path.dirname(file));
647
+ body[f.key] = file;
648
+ }
655
649
  let r;
656
- if (body.proposal === undefined)
657
- r = await run();
658
- else {
659
- if (typeof talk !== 'string' || typeof id !== 'string' || !/^[\w-]+$/.test(id))
660
- throw new HttpError(400, 'a proposal names its talk and its id');
661
- // Only a move an agent may propose: a line planted in the chat is no proposal of one.
662
- if (!domain?.moves[String(body.cmd)]?.propose)
663
- throw new HttpError(400, `${String(body.cmd)} is not a move an agent proposes`);
664
- // An agent's entry is the agent's (decision 32): the server says so, never the body.
665
- if (body.cmd === domain?.sections.inbox?.add)
666
- args = [...args, '--origin=agent'];
667
- // A new item's id is the core's (decision 34): asked first, then given, so a board that
668
- // stops after the item is made finds it by that id and does not make it twice.
669
- if (body.cmd === domain?.new_item) {
670
- const dryArgs = [...args.filter((a) => a !== '--commit'), '--dry-run'];
671
- const dry = await cli(p, dryArgs, undefined, moveInput(body, domain?.moves));
672
- if (!dry.ok) {
673
- send(res, 200, { ok: false, out: dry.out.trim(), err: briefError(dry.err) });
674
- return;
650
+ try {
651
+ // A proposal of a Draft thread makes the entry's item (Board-V2-Data-Plan §2.7): the
652
+ // entry goes with it while it is there; a second proposal, or one after it went, has none.
653
+ const proposal = (body.proposal ?? {});
654
+ if (typeof proposal.talk === 'string' && body.from === undefined) {
655
+ // A thread that is not there has no entry: acceptProposal says it is not there.
656
+ const entry = existsSync(threadDir(p.path, talkId(proposal.talk)))
657
+ ? talkEntry(p, proposal.talk)
658
+ : null;
659
+ const board = entry ? await boardOf(p) : null;
660
+ if (board &&
661
+ board.domain.new_item === body.cmd &&
662
+ board.inbox?.some((e) => e.id === entry))
663
+ body.from = entry;
664
+ }
665
+ let args = moveArgs(body, domain?.moves);
666
+ const run = () => cli(p, args, undefined, moveInput(body, domain?.moves));
667
+ // An agent's proposal made (AD-16, AD-33): its record goes with the move.
668
+ const { talk, id } = (body.proposal ?? {});
669
+ if (body.proposal === undefined)
670
+ r = await run();
671
+ else {
672
+ if (typeof talk !== 'string' || typeof id !== 'string' || !/^[\w-]+$/.test(id))
673
+ throw new HttpError(400, 'a proposal names its talk and its id');
674
+ // Only a move an agent may propose: a line planted in the chat is no proposal of one.
675
+ if (!domain?.moves[String(body.cmd)]?.propose)
676
+ throw new HttpError(400, `${String(body.cmd)} is not a move an agent proposes`);
677
+ // An agent's entry is the agent's (decision 32): the server says so, never the body.
678
+ if (body.cmd === domain?.sections.inbox?.add)
679
+ args = [...args, '--origin=agent'];
680
+ // A new item's id is the core's (decision 34): asked first, then given, so a board that
681
+ // stops after the item is made finds it by that id and does not make it twice.
682
+ if (body.cmd === domain?.new_item) {
683
+ const dryArgs = [...args.filter((a) => a !== '--commit'), '--dry-run'];
684
+ const dry = await cli(p, dryArgs, undefined, moveInput(body, domain?.moves));
685
+ if (!dry.ok) {
686
+ send(res, 200, { ok: false, out: dry.out.trim(), err: briefError(dry.err) });
687
+ return;
688
+ }
689
+ body.id = dry.out.trim().split(/\s/)[0];
690
+ // Its commit names the proposal: a recovery tells it from another's of one id.
691
+ args = [...withItemId(args, String(body.id)), `--proposal=${talk}/${id}`];
675
692
  }
676
- body.id = dry.out.trim().split(/\s/)[0];
677
- // Its commit names the proposal: a recovery tells it from another's of one id.
678
- args = [...withItemId(args, String(body.id)), `--proposal=${talk}/${id}`];
693
+ const mark = body.cmd === domain?.new_item ? `${talk}/${id}` : undefined;
694
+ const item = typeof body.id === 'string' ? body.id : '';
695
+ const ids = idsOf(await boardOf(p));
696
+ r = await acceptProposal(p, talk, id, String(body.cmd), item, ids, run, mark);
697
+ broadcast({ type: 'talks', project: p.name });
679
698
  }
680
- const mark = body.cmd === domain?.new_item ? `${talk}/${id}` : undefined;
681
- const item = typeof body.id === 'string' ? body.id : '';
682
- const ids = idsOf(await boardOf(p));
683
- r = await acceptProposal(p, talk, id, String(body.cmd), item, ids, run, mark);
684
- broadcast({ type: 'talks', project: p.name });
699
+ }
700
+ finally {
701
+ // The command copied it, or it never ran: the written copy goes either way.
702
+ for (const dir of uploads)
703
+ await rm(dir, { recursive: true, force: true });
685
704
  }
686
705
  broadcast({ type: 'board', project: p.name });
687
706
  send(res, 200, { ok: r.ok, out: r.out.trim(), err: briefError(r.err) });
@@ -1,4 +1,5 @@
1
1
  import { HttpError } from './http-error.js';
2
+ import { saveUpload } from './upload.js';
2
3
  /** A chat message may carry images: a body up to 10 MB. */
3
4
  export const CHAT_BODY_MAX = 10_000_000;
4
5
  /** The file a picture of each type is handed to the harness as. */
@@ -13,6 +14,8 @@ const BASE64 = /^[A-Za-z0-9+/]+={0,2}$/;
13
14
  const TEXT_MAX = 64_000;
14
15
  // About 5 MB of image, the most one image may be.
15
16
  const IMAGE_MAX = 6_990_000;
17
+ // A picked file, as much as a picture.
18
+ const FILE_MAX = IMAGE_MAX;
16
19
  const bad = (why) => new HttpError(400, `chat: ${why}`);
17
20
  function images(v) {
18
21
  if (v === undefined)
@@ -30,8 +33,8 @@ function images(v) {
30
33
  }
31
34
  const SLUG = /^[a-z0-9][a-z0-9-]*$/;
32
35
  /**
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
36
+ * What a message attaches (Round2-review §3): an item, a file of the project or one the operator
37
+ * picked on their machine, a design unit of `units` (Board-PRD §5.13). They go into the message's text, as a line the agent reads: it
35
38
  * opens them itself.
36
39
  */
37
40
  function attachLine(v, units) {
@@ -48,6 +51,9 @@ function attachLine(v, units) {
48
51
  return `unit ${ref} (${units.get(ref)})`;
49
52
  if (kind === 'unit')
50
53
  throw bad(`no design unit ${String(ref)} on the board`);
54
+ // A file the operator picked on their machine, written by withUploads: its absolute path.
55
+ if (kind === 'upload' && typeof ref === 'string')
56
+ return `file ${ref}`;
51
57
  // A project path, as the operator names it: relative, inside the project, nothing a shell
52
58
  // would expand (`~`, `%VAR%`, `$VAR`) and no drive or scheme (`:`).
53
59
  const file = typeof ref === 'string' ? ref.trim() : '';
@@ -58,10 +64,32 @@ function attachLine(v, units) {
58
64
  !/[:%$]/.test(file) &&
59
65
  !file.split(/[\\/]/).some((part) => part.trim() === '..'))
60
66
  return `file ${file}`;
61
- throw bad('an attachment is {kind: item, ref: <id>}, {kind: unit, ref: <id>} or {kind: file, ref: <project path>}');
67
+ throw bad('an attachment is {kind: item, ref: <id>}, {kind: unit, ref: <id>}, {kind: file, ref: <project path>} or {kind: file, ref: <name>, data: <base64>}');
62
68
  });
63
69
  return refs.length ? `\n\n[attached: ${refs.join('; ')}]` : '';
64
70
  }
71
+ /**
72
+ * A message's attachments with each file the operator picked on their machine (`{kind: file,
73
+ * ref: <its name>, data}`) written into the project's uploads: the agent reads it there, by its
74
+ * absolute path, from the project folder or a worktree alike.
75
+ */
76
+ export async function withUploads(root, body) {
77
+ if (!Array.isArray(body.attach))
78
+ return;
79
+ if (body.attach.length > 10)
80
+ throw bad('attach is a list of up to 10');
81
+ body.attach = await Promise.all(body.attach.map(async (a) => {
82
+ // Only the server says a file is an upload: the page names a project path or sends bytes.
83
+ if (a?.kind === 'upload')
84
+ throw bad('an attachment is an item, a unit or a file');
85
+ if (a?.kind !== 'file' || a.data === undefined)
86
+ return a;
87
+ return {
88
+ kind: 'upload',
89
+ ref: await saveUpload(root, { name: a.ref, data: a.data }, FILE_MAX),
90
+ };
91
+ }));
92
+ }
65
93
  /** Whether a body attaches a design unit: its route reads the board's units for it. */
66
94
  export const attachesUnit = (body) => Array.isArray(body.attach) &&
67
95
  body.attach.some((a) => a?.kind === 'unit');
@@ -27,6 +27,8 @@ export function fieldSchema(f) {
27
27
  break;
28
28
  case 'text':
29
29
  case 'longtext':
30
+ // An agent names a file by its path.
31
+ case 'file':
30
32
  s = { type: 'string', ...(f.max ? { maxLength: f.max } : {}) };
31
33
  break;
32
34
  case 'choice':
@@ -0,0 +1,38 @@
1
+ // A file the operator picks on their machine (the page's file dialog): the page reads it and
2
+ // sends its bytes, as a browser never gives a path. The server writes it beside the project's
3
+ // session data (`.gcf-session/uploads/`, not in git), each under its own name in a folder of
4
+ // its own, so a command that copies it (`gcf item attach`) keeps the name.
5
+ import { randomBytes } from 'node:crypto';
6
+ import { mkdir, writeFile } from 'node:fs/promises';
7
+ import path from 'node:path';
8
+ import { HttpError } from './http-error.js';
9
+ const BASE64 = /^[A-Za-z0-9+/]*={0,2}$/;
10
+ // The core's limit of an attachment (10 MB), as base64.
11
+ export const UPLOAD_MAX = 13_990_000;
12
+ /** Whether a value is a picked file as the page sends it: `{name, data}`, data in base64. */
13
+ export const isUpload = (v) => typeof v === 'object' &&
14
+ v !== null &&
15
+ typeof v.name === 'string' &&
16
+ typeof v.data === 'string';
17
+ /** Its name as a file of its own: no folder, nothing a shell or Windows reads, 100 characters. */
18
+ export function uploadName(name) {
19
+ const base = name.split(/[\\/]/).pop() ?? '';
20
+ const safe = base
21
+ .replace(/[^\p{L}\p{N}_.\- ()]/gu, '_')
22
+ .replace(/^[.\s]+/, '')
23
+ .trim()
24
+ .slice(-100);
25
+ return safe || 'file';
26
+ }
27
+ /** Write a picked file into the project's uploads: its absolute path. */
28
+ export async function saveUpload(root, v, max = UPLOAD_MAX) {
29
+ if (!isUpload(v) || !BASE64.test(v.data))
30
+ throw new HttpError(400, 'a file is {name, data}');
31
+ if (v.data.length > max)
32
+ throw new HttpError(400, `${v.name}: over ${Math.floor((max * 3) / 4 / 1e6)} MB`);
33
+ const dir = path.join(root, '.gcf-session', 'uploads', randomBytes(4).toString('hex'));
34
+ await mkdir(dir, { recursive: true });
35
+ const file = path.join(dir, uploadName(v.name));
36
+ await writeFile(file, Buffer.from(v.data, 'base64'));
37
+ return file;
38
+ }