gcf-board 0.5.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.
@@ -0,0 +1,423 @@
1
+ // A project chat thread (docs/Session-Engine.md AD-41…AD-47): a chain of agent sessions in the
2
+ // project's folder, run as a job with a chat policy. Its files live in `.gcf-session/chats/<t>/`:
3
+ // `thread.json` (its sessions), `chat.jsonl` (what the operator reads), `chat-in.jsonl` (what
4
+ // the operator writes), `att/` (pictures), `context.md` (what the center gives it to read),
5
+ // `handoff-<n>.md` (the summaries its sessions handed over by), `spec.json` (how it runs).
6
+ import { randomBytes } from 'node:crypto';
7
+ import {
8
+ closeSync,
9
+ existsSync,
10
+ mkdirSync,
11
+ openSync,
12
+ readFileSync,
13
+ readdirSync,
14
+ rmSync,
15
+ writeFileSync,
16
+ } from 'node:fs';
17
+ import path from 'node:path';
18
+ import { createHash } from 'node:crypto';
19
+ import { adapterFor } from './adapter/index.js';
20
+ import { runJob } from './job.js';
21
+ import { alive, killTree } from './proc.js';
22
+ import { chatsDir, runsDir, writeAtomic } from './store.js';
23
+ import { readWindows, windowFor } from './windows.js';
24
+
25
+ /** A thread's id: `t` and eight hex digits. */
26
+ export const THREAD_ID = /^t[0-9a-f]{8}$/;
27
+
28
+ /** The share of the window a thread hands over at when the domain names none (AD-43). */
29
+ export const HANDOFF_PCT = 60;
30
+
31
+ /** How often a live session's thread looks for its stop mark. */
32
+ const STOP_POLL_MS = 1000;
33
+
34
+ /** How long a summary turn may take before it counts as failed (AD-42). */
35
+ export const SUMMARY_MS = 2 * 60_000;
36
+
37
+ /** A thread's answer time: `0` (nobody watches a run) means 15 minutes for a chat (AD-11). */
38
+ export const answerMsOf = (min) => (Number(min) > 0 ? Number(min) : 15) * 60_000;
39
+
40
+ /** What the engine asks a session for at a handoff (AD-42). */
41
+ export const SUMMARY_PROMPT =
42
+ 'Write down the state of this conversation for a fresh agent that goes on from it: the ' +
43
+ 'decisions made, the open questions, what comes next, and the files that matter. At most ' +
44
+ '6000 characters. This is your last turn: a fresh session continues from your text.';
45
+
46
+ // The git commands that change the checkout: a chat asks for them, and refuses them while a
47
+ // main run works in the folder (AD-29).
48
+ const GIT_VERBS = [
49
+ 'commit|add|rm|mv|stash|checkout|switch|restore|reset|merge|rebase|cherry-pick|revert',
50
+ 'clean|push|pull|apply|am',
51
+ ].join('|');
52
+ // Global options may come before the verb: `git -C . commit`, `git -c k=v commit`,
53
+ // `git --work-tree . add`.
54
+ const GIT_OPT = [
55
+ String.raw`-[Cc]\s+\S+`,
56
+ String.raw`--(?:work-tree|git-dir|namespace)\s+\S+`,
57
+ String.raw`--?[\w-]+(?:=\S+)?`,
58
+ ].join('|');
59
+ const GIT_OPTS = String.raw`(?:(?:${GIT_OPT})\s+)*`;
60
+ const GIT_CHANGES = new RegExp(String.raw`\bgit\s+${GIT_OPTS}(?:${GIT_VERBS})\b`);
61
+
62
+ export const threadDir = (dir, t) => path.join(chatsDir(dir), t);
63
+ const itemMark = (dir, item) => path.join(chatsDir(dir), 'items', item);
64
+
65
+ /** The thread `t`'s record, `{id, item, sessions, created_at, in_at}`. */
66
+ export function readThread(dir, t) {
67
+ return JSON.parse(readFileSync(path.join(threadDir(dir, t), 'thread.json'), 'utf8'));
68
+ }
69
+
70
+ const writeThread = (dir, t, rec) =>
71
+ writeAtomic(path.join(threadDir(dir, t), 'thread.json'), `${JSON.stringify(rec, null, 2)}\n`);
72
+
73
+ /**
74
+ * The record written while a session runs (its input read, its operator heard): a scanner that
75
+ * holds the file up must not end the session; the next write carries the same state.
76
+ */
77
+ function keepTrying(dir, t, rec) {
78
+ try {
79
+ writeThread(dir, t, rec);
80
+ } catch {
81
+ // Written again at the next ack, or as the session ends.
82
+ }
83
+ }
84
+
85
+ /** The thread bound to `item`, or null (AD-46). */
86
+ export function threadOf(dir, item) {
87
+ try {
88
+ const t = readFileSync(itemMark(dir, item), 'utf8').trim();
89
+
90
+ return THREAD_ID.test(t) && existsSync(threadDir(dir, t)) ? t : null;
91
+ } catch {
92
+ return null;
93
+ }
94
+ }
95
+
96
+ /**
97
+ * A new thread, its id; bound to `item`, the one it already has (AD-46). Ids and the item's
98
+ * mark are made exclusively: two at once never take one id, nor give an item two threads.
99
+ */
100
+ export function createThread(dir, { item = null } = {}) {
101
+ if (item && threadOf(dir, item)) return /** @type {string} */ (threadOf(dir, item));
102
+ mkdirSync(path.join(chatsDir(dir), 'items'), { recursive: true });
103
+ const t = newDir(dir);
104
+ if (item) {
105
+ try {
106
+ writeFileSync(itemMark(dir, item), t, { flag: 'wx' });
107
+ } catch (e) {
108
+ rmSync(threadDir(dir, t), { recursive: true, force: true });
109
+ if (/** @type {any} */ (e).code === 'EEXIST') return createThread(dir, { item });
110
+ throw e;
111
+ }
112
+ }
113
+
114
+ const now = new Date().toISOString();
115
+ writeThread(dir, t, { id: t, item, sessions: [], created_at: now, in_at: 0 });
116
+
117
+ return t;
118
+ }
119
+
120
+ /** A thread's folder made exclusively under a fresh id: the id. */
121
+ function newDir(dir) {
122
+ for (;;) {
123
+ const t = `t${randomBytes(4).toString('hex')}`;
124
+ try {
125
+ mkdirSync(threadDir(dir, t));
126
+
127
+ return t;
128
+ } catch (e) {
129
+ if (/** @type {any} */ (e).code !== 'EEXIST') throw e;
130
+ }
131
+ }
132
+ }
133
+
134
+ /** The threads of the project, newest first. */
135
+ export function listThreads(dir) {
136
+ let names;
137
+ try {
138
+ names = readdirSync(chatsDir(dir)).filter((n) => THREAD_ID.test(n));
139
+ } catch {
140
+ return [];
141
+ }
142
+
143
+ return names
144
+ .flatMap((t) => {
145
+ try {
146
+ return [readThread(dir, t)];
147
+ } catch {
148
+ return [];
149
+ }
150
+ })
151
+ .sort((a, b) => String(b.created_at).localeCompare(String(a.created_at)));
152
+ }
153
+
154
+ /**
155
+ * Whether a neutral rule `{kind, pattern}` holds for a call: its kind, its glob on the title; a
156
+ * shell rule on each command of a chain too (`cd x && git push` is a `git *`).
157
+ */
158
+ function ruleHolds(rule, e) {
159
+ if (rule.kind !== e.kind) return false;
160
+ if (!rule.pattern) return true;
161
+ const glob = rule.pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replaceAll('*', '.*');
162
+ const re = new RegExp(`^${glob}$`);
163
+ const title = String(e.title ?? '');
164
+ const parts = e.kind === 'shell' ? title.split(/\s*(?:&&|\|\||[;|\n])\s*/) : [];
165
+
166
+ return [title, ...parts].some((x) => re.test(x.trim()));
167
+ }
168
+
169
+ /** Whether the main run's lock (`runs/<main>.lock`) names a live process. */
170
+ function mainBusy(file) {
171
+ if (!file) return false;
172
+ try {
173
+ return alive(Number(readFileSync(file, 'utf8').split('\n')[0]));
174
+ } catch {
175
+ return false;
176
+ }
177
+ }
178
+
179
+ const hashOf = (text) => createHash('sha256').update(text).digest('hex').slice(0, 16);
180
+ const readOr = (file, or = '') => {
181
+ try {
182
+ return readFileSync(file, 'utf8');
183
+ } catch {
184
+ return or;
185
+ }
186
+ };
187
+
188
+ /**
189
+ * The prompt file a session starts with (AD-44): the skill line, the thread's `context.md`, and
190
+ * at a handoff the summary it goes on from. A resumed session keeps the one it started with.
191
+ */
192
+ function promptFile(td, spec, summary) {
193
+ const file = path.join(td, 'prompt.md');
194
+ const parts = [
195
+ spec.skill ? `Follow the ${spec.skill} skill in this conversation.` : '',
196
+ readOr(path.join(td, 'context.md')),
197
+ summary
198
+ ? `The conversation so far, as the last session wrote it down:\n\n${readOr(summary)}`
199
+ : '',
200
+ ].filter((x) => x.trim());
201
+ writeFileSync(file, `${parts.join('\n\n')}\n`);
202
+
203
+ return file;
204
+ }
205
+
206
+ /**
207
+ * The flags of a thread's session: ask mode with the spec's rules (AD-5), the project's settings,
208
+ * the MCP servers (the project's and the center's), and the prompt file at a start or a handoff.
209
+ * shortcut: claude's flags written out here; move them into the adapter with a second provider.
210
+ */
211
+ function flagsOf(dir, td, spec, settings) {
212
+ const mcp = [
213
+ ...(existsSync(path.join(dir, '.mcp.json')) ? ['.mcp.json'] : []),
214
+ ...(spec.mcp ?? []),
215
+ ];
216
+
217
+ return (kind, summary) =>
218
+ [
219
+ '--permission-mode default --setting-sources project,local',
220
+ `--settings "${settings}"`,
221
+ ...(mcp.length ? ['--strict-mcp-config', ...mcp.map((f) => `--mcp-config "${f}"`)] : []),
222
+ kind === 'resume' ? '' : `--append-system-prompt-file "${promptFile(td, spec, summary)}"`,
223
+ ]
224
+ .filter(Boolean)
225
+ .join(' ');
226
+ }
227
+
228
+ /**
229
+ * Run thread `t` of project `dir` until its session idles out, is stopped, or ends: a job of
230
+ * sessions (AD-41), each resumed from the one before, a fresh one after a handoff (AD-42).
231
+ * `spec` (its `spec.json`): `agent`, `rules` `{deny, ask, allow}`, `mcp` (config files),
232
+ * `answerMin`, `handoffPct`, `window`, `skill`, `mainLock`, `timeoutMin`. `stopped()` says the
233
+ * operator stopped it.
234
+ * @param {{stopped?: () => boolean}} [opts]
235
+ */
236
+ export async function runThread(dir, t, spec, opts = {}) {
237
+ const { stopped = () => false } = opts;
238
+ const td = threadDir(dir, t);
239
+ const rec = readThread(dir, t);
240
+ const adapter = adapterFor(spec.agent);
241
+ const last = rec.sessions.at(-1) ?? null;
242
+ const s = {
243
+ ...{ dir, t, td, rec, spec, adapter, stopped },
244
+ flags: flagsOf(dir, td, spec, settingsOf(td, adapter, spec.rules)),
245
+ learned: readWindows(runsDir(dir)),
246
+ input: inputOf(dir, t, rec),
247
+ // The newest summary: a fresh start after a lost resume goes on from it too.
248
+ summary: rec.sessions.findLast((x) => x.summary)?.summary ?? null,
249
+ saved: /** @type {string | null} */ (null),
250
+ started: contextHash(td),
251
+ pid: 0,
252
+ fd: openSync(path.join(td, 'thread.log'), 'a'),
253
+ };
254
+ // A stop ends the live session too, not only a wait between sessions.
255
+ const watchStop = setInterval(() => {
256
+ if (s.pid && stopped()) killTree(s.pid);
257
+ }, STOP_POLL_MS);
258
+ watchStop.unref();
259
+ try {
260
+ // The last session: resumed, or a fresh one from its summary after a handoff.
261
+ const ran = await runJob(jobOf(s, goesOn(last)));
262
+
263
+ // The session it resumed is gone: a fresh one takes the operator's message.
264
+ return ran.lost && !stopped() ? await runJob(jobOf(s, null)) : ran;
265
+ } finally {
266
+ clearInterval(watchStop);
267
+ closeSync(s.fd);
268
+ }
269
+ }
270
+
271
+ const CHANGED = "The thread's context changed since this session began:";
272
+
273
+ // The first message of a session the usage limit cut, after its reset: the operator's last
274
+ // message got no answer.
275
+ const AFTER_LIMIT =
276
+ "The usage limit cut your last turn and has reset now. If your reply to the operator's " +
277
+ 'last message was cut off, finish it; if it was not, say in one line that you are back.';
278
+
279
+ /** The session a thread goes on from: its last, resumed, or a fresh one after a handoff. */
280
+ const goesOn = (last) =>
281
+ last?.session_id || last?.ended === 'handoff' ? { ...last, counted: true } : null;
282
+
283
+ /** The agent's settings file of a thread's sessions: its rules (AD-5). */
284
+ function settingsOf(td, adapter, rules) {
285
+ const file = path.join(td, 'settings.json');
286
+ const permissions = adapter.permissions?.(rules) ?? {};
287
+ writeFileSync(file, `${JSON.stringify({ permissions }, null, 2)}\n`);
288
+
289
+ return file;
290
+ }
291
+
292
+ const contextHash = (td) => hashOf(readOr(path.join(td, 'context.md')));
293
+
294
+ /**
295
+ * Where the thread's input is done, and how far a session read it: a message past the first
296
+ * that the next session takes again is marked `retry` (AD-35).
297
+ */
298
+ function inputOf(dir, t, rec) {
299
+ const input = {
300
+ at: Number(rec.in_at) || 0,
301
+ retryTo: Number(rec.in_read) || 0,
302
+ onAck: () => {
303
+ if (rec.in_at === input.acked && rec.in_read >= input.at) return;
304
+ rec.in_at = input.acked;
305
+ rec.in_read = Math.max(Number(rec.in_read) || 0, input.at);
306
+ keepTrying(dir, t, rec);
307
+ },
308
+ };
309
+
310
+ return input;
311
+ }
312
+
313
+ /** Keep a session in the thread's record as it ends; a handoff's summary with it. */
314
+ function keep(s, ran, kind) {
315
+ const { rec, input } = s;
316
+ rec.sessions.push({
317
+ ...(ran.session_id ? { session_id: ran.session_id } : {}),
318
+ ended: String(ran.code),
319
+ kind,
320
+ context: s.started,
321
+ ...(ran.code === 'handoff' && s.saved ? { summary: s.saved } : {}),
322
+ });
323
+ // A fresh session after a handoff hands over again only once the operator spoke to it.
324
+ if (ran.code === 'handoff') rec.unheard = true;
325
+ rec.in_at = input.at;
326
+ rec.in_read = Math.max(Number(rec.in_read) || 0, input.retryTo ?? 0);
327
+ writeThread(s.dir, s.t, rec);
328
+ if (ran.code === 'handoff') s.summary = s.saved;
329
+ s.saved = null;
330
+ }
331
+
332
+ /** The engine's refusal of a call while a main run works in the checkout (AD-29), or null. */
333
+ const gateOf = (spec) => (e) =>
334
+ mainBusy(spec.mainLock) &&
335
+ (e.kind === 'edit' || (e.kind === 'shell' && GIT_CHANGES.test(e.title)))
336
+ ? 'a main run is working in this checkout: ask again after it ends'
337
+ : null;
338
+
339
+ /** The summary turn of a handoff (AD-42): its prompt, its time, where its text goes. */
340
+ const handoverOf = (s) => ({
341
+ prompt: SUMMARY_PROMPT,
342
+ timeoutMs: SUMMARY_MS,
343
+ save: async (text) => {
344
+ const n = s.rec.sessions.filter((x) => x.summary).length + 1;
345
+ const file = path.join(s.td, `handoff-${n}.md`);
346
+ writeFileSync(file, `${text}\n`);
347
+ s.saved = file;
348
+
349
+ return file;
350
+ },
351
+ });
352
+
353
+ /** The chat of a thread's session of `kind`, after the session `prev`. */
354
+ function chatOf(s, kind, prev) {
355
+ const { dir, td, rec, spec } = s;
356
+ const now = contextHash(td);
357
+ // A resumed session's context changed since it started: the first message carries it.
358
+ const was = rec.sessions.findLast((x) => x.session_id === prev?.session_id)?.context;
359
+ const changed = kind === 'resume' && was && was !== now;
360
+ // A changed context goes in the first message; the session knows it once that went.
361
+ s.started = changed ? was : now;
362
+
363
+ return {
364
+ logs: td,
365
+ id: 'chat',
366
+ files: { in: path.join(td, 'chat-in.jsonl'), out: path.join(td, 'chat.jsonl') },
367
+ input: s.input,
368
+ answerMs: answerMsOf(spec.answerMin),
369
+ done: async () => false,
370
+ kind,
371
+ approvals: true,
372
+ gate: gateOf(spec),
373
+ asks: (e) => (spec.rules?.ask ?? []).some((r) => ruleHolds(r, e)),
374
+ saveAlways: (rule) => s.adapter.saveAlways(dir, rule),
375
+ handover: handoverOf(s),
376
+ summary: kind === 'handoff' ? s.summary : null,
377
+ fresh: kind === 'handoff' || Boolean(rec.unheard),
378
+ onHeard: () => {
379
+ rec.unheard = false;
380
+ keepTrying(dir, s.t, rec);
381
+ },
382
+ prefix: changed ? `${CHANGED}\n\n${readOr(path.join(td, 'context.md'))}` : null,
383
+ onPrefix: () => {
384
+ s.started = now;
385
+ },
386
+ };
387
+ }
388
+
389
+ /** The job of a thread's sessions from `record` (AD-41). */
390
+ function jobOf(s, record) {
391
+ const { dir, spec } = s;
392
+
393
+ return {
394
+ adapter: s.adapter,
395
+ agent: spec.agent,
396
+ dir,
397
+ id: s.t,
398
+ logs: runsDir(dir),
399
+ fd: s.fd,
400
+ timeoutMs: (Number(spec.timeoutMin) || 24 * 60) * 60_000,
401
+ record,
402
+ // A thread starts on the operator's message; after the usage limit's wait, on this.
403
+ prompt: (kind, _caps, rec) => (rec?.ended === 'limit' ? AFTER_LIMIT : null),
404
+ flags: (kind) => s.flags(kind, s.summary),
405
+ onSpawn: (p) => {
406
+ s.pid = p;
407
+ },
408
+ onIdle: () => {
409
+ s.pid = 0;
410
+ },
411
+ stopped: s.stopped,
412
+ chatFile: path.join(s.td, 'chat.jsonl'),
413
+ handoff: {
414
+ pct: Number(spec.handoffPct) > 0 ? Number(spec.handoffPct) : HANDOFF_PCT,
415
+ soft: true,
416
+ windowOf: (model, live) => windowFor(model, spec.window, s.learned, live),
417
+ },
418
+ onSession: (ran, kind) => keep(s, ran, kind),
419
+ quota: path.join(runsDir(dir), 'quota.json'),
420
+ learned: s.learned,
421
+ chat: (kind, prev) => chatOf(s, kind, prev),
422
+ };
423
+ }
@@ -0,0 +1,46 @@
1
+ // The context window a session's share is taken of, and the windows learned from results.
2
+ import { readFileSync } from 'node:fs';
3
+ import path from 'node:path';
4
+ import { writeAtomic } from './store.js';
5
+
6
+ // The window of a model a run met before: `<model>: tokens`, from the result of its sessions.
7
+ export const windowsOf = (logs) => path.join(logs, 'windows.json');
8
+
9
+ /**
10
+ * The context window a session's share is taken of (fix C): the project's `context_window`, the
11
+ * one this session's own result reported (`live`), the one a result of the same model reported
12
+ * before, then a `[1m]` model; null when none says it.
13
+ */
14
+ export function windowFor(model, configured, learned, live = 0) {
15
+ if (configured > 0) return configured;
16
+ if (live > 0) return live;
17
+ if (model && learned?.[model] > 0) return learned[model];
18
+
19
+ return /\[1m\]$/i.test(model ?? '') ? 1_000_000 : null;
20
+ }
21
+
22
+ /** The windows learned so far, `{}` when there are none. */
23
+ export function readWindows(logs) {
24
+ try {
25
+ return JSON.parse(readFileSync(windowsOf(logs), 'utf8')) ?? {};
26
+ } catch {
27
+ return {};
28
+ }
29
+ }
30
+
31
+ /**
32
+ * Keep the window a session's result reported for its model. The file is read again and merged
33
+ * first: another run may have learned another model meanwhile (AD-34).
34
+ */
35
+ export async function learnWindow(logs, learned, ran) {
36
+ if (!ran.model || !(ran.window > 0) || learned[ran.model] === ran.window) return;
37
+ learned[ran.model] = ran.window;
38
+ try {
39
+ writeAtomic(
40
+ windowsOf(logs),
41
+ `${JSON.stringify({ ...readWindows(logs), ...learned }, null, 2)}\n`,
42
+ );
43
+ } catch {
44
+ // Not kept: the next session learns it again.
45
+ }
46
+ }
@@ -0,0 +1,23 @@
1
+ {
2
+ "name": "gcf-session",
3
+ "version": "0.12.0",
4
+ "private": true,
5
+ "description": "The session engine of GCF: one agent session and a run as a chain of them, the chat protocol, the provider adapters. Bundled by gcf-harness-aif-ext and gcf-board, never published.",
6
+ "type": "module",
7
+ "license": "MIT",
8
+ "author": "Oleg (VirtualMaestro)",
9
+ "engines": {
10
+ "node": ">=22.14"
11
+ },
12
+ "exports": {
13
+ ".": "./lib/index.js"
14
+ },
15
+ "types": "./types/index.d.ts",
16
+ "files": [
17
+ "lib",
18
+ "types"
19
+ ],
20
+ "scripts": {
21
+ "test": "node --test \"test/*.test.js\""
22
+ }
23
+ }
@@ -0,0 +1,152 @@
1
+ // The chat events of gcf-session (docs/design/chat-events.md, AD-24): one JSON object a line in
2
+ // a run's `<id>.chat.jsonl` and a thread's `chat.jsonl`. Versions only add fields and types; a
3
+ // reader skips what it does not know. The board checks its own union against this one.
4
+
5
+ /** Every event carries its time. */
6
+ interface At {
7
+ /** UTC, ISO. */
8
+ at: string;
9
+ }
10
+
11
+ export type ChatEvent = At &
12
+ (
13
+ | { type: 'session'; kind: 'start' | 'resume' | 'handoff'; v?: number; summary?: string }
14
+ | {
15
+ type: 'session_end';
16
+ code: number | 'timeout' | 'handoff' | 'idle' | string;
17
+ cost_usd: number | null;
18
+ limit_resets?: string | null;
19
+ }
20
+ | { type: 'limit'; until: string }
21
+ | {
22
+ type: 'say';
23
+ by: 'run' | 'operator' | 'timeout' | 'engine';
24
+ text: string;
25
+ images?: string[];
26
+ n: number;
27
+ id?: string;
28
+ retry?: boolean;
29
+ }
30
+ | { type: 'read'; n: number; assumed?: boolean }
31
+ | { type: 'agent'; text: string }
32
+ | { type: 'working' }
33
+ | { type: 'waiting'; kind: 'card' | 'text' | 'stop' }
34
+ | { type: 'timeout'; kind: 'card' | 'text' }
35
+ | { type: 'interrupt' }
36
+ | { type: 'error'; text: string }
37
+ | { type: 'background'; tasks: { id: string; description: string }[] }
38
+ | {
39
+ type: 'question';
40
+ request_id: string;
41
+ questions: {
42
+ question: string;
43
+ header?: string;
44
+ multiSelect?: boolean;
45
+ options?: { label: string; description?: string }[];
46
+ }[];
47
+ }
48
+ | {
49
+ type: 'answer';
50
+ by: 'operator' | 'timeout';
51
+ request_id: string;
52
+ answers: Record<string, string>;
53
+ }
54
+ | { type: 'dropped'; request_id: string }
55
+ | {
56
+ type: 'approval';
57
+ request_id: string;
58
+ kind: string;
59
+ tool: string;
60
+ title: string;
61
+ reason?: string;
62
+ always?: string;
63
+ }
64
+ | { type: 'allowed'; request_id: string; by: 'operator'; always: boolean; rule?: string }
65
+ | {
66
+ type: 'denied';
67
+ tool: string;
68
+ by?: 'operator' | 'rule' | 'timeout' | 'engine';
69
+ request_id?: string;
70
+ title?: string;
71
+ reason?: string;
72
+ }
73
+ | { type: 'proposal'; id: string; move: string; fields: Record<string, unknown> }
74
+ | { type: 'context'; context: number; context_pct: number | null; window: number | null }
75
+ | {
76
+ type: 'turn';
77
+ subtype?: string;
78
+ total_cost_usd: number | null;
79
+ context?: number;
80
+ context_pct?: number | null;
81
+ }
82
+ | { type: 'compacted' }
83
+ | {
84
+ type: 'handoff';
85
+ pct?: number | null;
86
+ tokens?: number;
87
+ window?: number | null;
88
+ compacted?: boolean;
89
+ by?: 'operator' | 'threshold' | 'compacted';
90
+ error?: string;
91
+ }
92
+ | { type: 'step'; step: 'plan'; passes: number }
93
+ | {
94
+ type: 'step';
95
+ step: 'dod' | 'review' | 'commit';
96
+ ok: boolean | null;
97
+ text?: string;
98
+ }
99
+ | {
100
+ type: 'step';
101
+ step: 'move';
102
+ move: 'submit' | 'close' | 'block';
103
+ ok: boolean | null;
104
+ text?: string;
105
+ }
106
+ );
107
+
108
+ /** The `type` of every chat event. */
109
+ export type ChatEventType = ChatEvent['type'];
110
+
111
+ /** The version of the chat events this package writes on each `session` event. */
112
+ export declare const EVENTS_V: number;
113
+
114
+ /** A neutral permission rule (AD-4). */
115
+ export interface Rule {
116
+ kind: string;
117
+ pattern: string;
118
+ }
119
+
120
+ /** A project chat thread's record, `chats/<t>/thread.json` (AD-45). */
121
+ export interface Thread {
122
+ id: string;
123
+ item: string | null;
124
+ sessions: { session_id?: string; ended: string; kind: string; summary?: string }[];
125
+ created_at: string;
126
+ in_at: number;
127
+ }
128
+
129
+ /** How a thread runs, `chats/<t>/spec.json`: the center writes it. */
130
+ export interface ThreadSpec {
131
+ agent: string;
132
+ rules: { deny: Rule[]; ask: Rule[]; allow: Rule[] };
133
+ mcp?: string[];
134
+ answerMin?: number;
135
+ handoffPct?: number;
136
+ window?: number;
137
+ skill?: string;
138
+ mainLock?: string | null;
139
+ timeoutMin?: number;
140
+ }
141
+
142
+ export declare function createThread(dir: string, opts?: { item?: string | null }): string;
143
+ export declare function threadOf(dir: string, item: string): string | null;
144
+ export declare function threadDir(dir: string, t: string): string;
145
+ export declare function readThread(dir: string, t: string): Thread;
146
+ export declare function listThreads(dir: string): Thread[];
147
+ export declare const THREAD_ID: RegExp;
148
+ export declare function answerMsOf(min: number | undefined): number;
149
+
150
+ // The rest of the engine is used from the harness's JavaScript: typed where TypeScript reads it.
151
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
152
+ export declare const runThread: (...args: any[]) => Promise<any>;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "gcf-board",
3
- "version": "0.5.1",
3
+ "version": "0.6.0",
4
4
  "description": "A local web board for GCF game projects: shows `gcf board --json` and runs the same ai-factory gcf commands an operator runs in a console",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -32,7 +32,7 @@
32
32
  "typecheck": "tsc -p tsconfig.json --noEmit",
33
33
  "test": "node --test \"server/**/*.test.ts\" \"web/**/*.test.ts\"",
34
34
  "start": "node dist/server/main.js",
35
- "prepack": "npm run build"
35
+ "prepack": "npm run build && node -e \"require('node:fs').statSync('node_modules/gcf-session/lib/index.js')\""
36
36
  },
37
37
  "devDependencies": {
38
38
  "@dnd-kit/core": "^6.3.1",
@@ -45,5 +45,12 @@
45
45
  "react-markdown": "^10.1.0",
46
46
  "typescript": "^7.0.2",
47
47
  "vite": "^8.3.4"
48
- }
48
+ },
49
+ "dependencies": {
50
+ "@modelcontextprotocol/server": "2.3.1",
51
+ "gcf-session": "file:../gcf-session"
52
+ },
53
+ "bundleDependencies": [
54
+ "gcf-session"
55
+ ]
49
56
  }