gcf-board 0.22.0 → 0.23.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +5 -1
- package/dist/server/app.js +77 -8
- package/dist/server/events.js +31 -3
- package/dist/server/runs.js +165 -21
- package/dist/server/talks.js +38 -0
- package/dist/server/usage.js +49 -109
- package/dist/web/assets/index-CmVruskr.js +113 -0
- package/dist/web/assets/{index-D7HJ7-ko.css → index-D-qaIlaa.css} +1 -1
- package/dist/web/index.html +2 -2
- package/node_modules/gcf-session/lib/chat.js +39 -5
- package/node_modules/gcf-session/lib/index.js +15 -0
- package/node_modules/gcf-session/lib/job.js +133 -34
- package/node_modules/gcf-session/lib/session.js +64 -10
- package/node_modules/gcf-session/lib/usage.js +288 -0
- package/node_modules/gcf-session/package.json +1 -1
- package/node_modules/gcf-session/types/index.d.ts +60 -2
- package/package.json +1 -1
- package/dist/web/assets/index-Dhh107oY.js +0 -113
|
@@ -0,0 +1,288 @@
|
|
|
1
|
+
// The account's usage limits and the quota's reserve (docs/Hold-Plan.md d10, d11). `/usage` of
|
|
2
|
+
// claude is asked by whoever needs it - the board, a run - and its last reading kept in
|
|
3
|
+
// `<home>/usage.json`, so one ask serves all: a reading younger than `maxAgeMs` is not asked
|
|
4
|
+
// again, and two asks at once, in one process or two, make one (`usage.lock`). The reserve is
|
|
5
|
+
// a share of each window the automation leaves to the operator (`quota_reserve_pct`).
|
|
6
|
+
import { spawn, spawnSync } from 'node:child_process';
|
|
7
|
+
import { mkdirSync, readFileSync } from 'node:fs';
|
|
8
|
+
import os from 'node:os';
|
|
9
|
+
import path from 'node:path';
|
|
10
|
+
import { claim } from './lock.js';
|
|
11
|
+
import { MAX_WAIT_MS } from './limit.js';
|
|
12
|
+
import { writeAtomic } from './store.js';
|
|
13
|
+
|
|
14
|
+
/** How old a reading may be before it is asked again; how long one ask may take. */
|
|
15
|
+
export const USAGE_MAX_AGE_MS = 5 * 60_000;
|
|
16
|
+
const ASK_TIMEOUT_MS = 30_000;
|
|
17
|
+
/** The share of each window the automation leaves to the operator, by default. */
|
|
18
|
+
export const RESERVE_PCT = 10;
|
|
19
|
+
// No user or local settings, no MCP, no saved session: the user's hooks and plugins do not run
|
|
20
|
+
// for a reading, and the operator's session list gets no entry per ask. The cwd is the temp
|
|
21
|
+
// folder, whose project settings are no one's.
|
|
22
|
+
const FLAGS =
|
|
23
|
+
'-p "/usage" --output-format stream-json --verbose --no-session-persistence ' +
|
|
24
|
+
'--setting-sources project --strict-mcp-config';
|
|
25
|
+
|
|
26
|
+
/** The account's folder of the board and the runs: GCF_BOARD_HOME, else `~/.gcf`. */
|
|
27
|
+
export const gcfHome = () => process.env.GCF_BOARD_HOME ?? path.join(os.homedir(), '.gcf');
|
|
28
|
+
export const usageFile = () => path.join(gcfHome(), 'usage.json');
|
|
29
|
+
|
|
30
|
+
/** The account's settings (`<home>/settings.json`): `quota_reserve_pct`, its default when none. */
|
|
31
|
+
export function accountSettings() {
|
|
32
|
+
let raw = {};
|
|
33
|
+
try {
|
|
34
|
+
raw = JSON.parse(readFileSync(path.join(gcfHome(), 'settings.json'), 'utf8')) ?? {};
|
|
35
|
+
} catch {
|
|
36
|
+
// None yet, or broken: the defaults.
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
const pct = Number(raw.quota_reserve_pct);
|
|
40
|
+
|
|
41
|
+
return {
|
|
42
|
+
...raw,
|
|
43
|
+
quota_reserve_pct: Number.isFinite(pct) && pct >= 0 && pct <= 50 ? pct : RESERVE_PCT,
|
|
44
|
+
};
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/** Write the account's settings whole (the board's settings screen). */
|
|
48
|
+
export function saveAccountSettings(settings) {
|
|
49
|
+
mkdirSync(gcfHome(), { recursive: true });
|
|
50
|
+
writeAtomic(path.join(gcfHome(), 'settings.json'), `${JSON.stringify(settings, null, 2)}\n`);
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
const isLimit = (l) =>
|
|
54
|
+
typeof l === 'object' &&
|
|
55
|
+
l !== null &&
|
|
56
|
+
typeof l.kind === 'string' &&
|
|
57
|
+
typeof l.percent === 'number';
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* The limits of `/usage`'s stream-json answer: its assistant event's
|
|
61
|
+
* `usage_report.rate_limits.limits`; null when no line carries them (an API-key account has no
|
|
62
|
+
* plan limits, an older claude no report).
|
|
63
|
+
*/
|
|
64
|
+
export function limitsOf(out) {
|
|
65
|
+
for (const line of String(out).split(/\r?\n/)) {
|
|
66
|
+
let e;
|
|
67
|
+
try {
|
|
68
|
+
e = JSON.parse(line);
|
|
69
|
+
} catch {
|
|
70
|
+
continue;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
const limits = e?.usage_report?.rate_limits?.limits;
|
|
74
|
+
if (Array.isArray(limits)) return limits.filter(isLimit);
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
return null;
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/**
|
|
81
|
+
* Why an ask failed: a timeout, else the last two lines of its stderr (cmd's "not recognized"
|
|
82
|
+
* spans two), else the error itself.
|
|
83
|
+
*/
|
|
84
|
+
export function reasonOf(e, err, timeoutMs = ASK_TIMEOUT_MS) {
|
|
85
|
+
if (!e) return 'claude answered /usage without the plan limits (an API key has none)';
|
|
86
|
+
// A stuck ask is told by its timeout, not by a warning it printed before it hung.
|
|
87
|
+
if (e.killed) return `no answer in ${timeoutMs / 1000} s`;
|
|
88
|
+
const tail = String(err ?? '').trim();
|
|
89
|
+
if (tail) return tail.split(/\r?\n/).slice(-2).join(' ').slice(0, 300);
|
|
90
|
+
|
|
91
|
+
return e.message.slice(0, 300);
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/** End a process and all it started: a killed shell on Windows leaves its claude running. */
|
|
95
|
+
function killAll(child) {
|
|
96
|
+
if (!child.pid) return;
|
|
97
|
+
if (process.platform === 'win32')
|
|
98
|
+
spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' });
|
|
99
|
+
else
|
|
100
|
+
try {
|
|
101
|
+
process.kill(-child.pid, 'SIGKILL');
|
|
102
|
+
} catch {
|
|
103
|
+
// The group ended on its own meanwhile.
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
// A process outside the tree that holds the pipes would hold the ask for good.
|
|
107
|
+
child.stdout.destroy();
|
|
108
|
+
child.stderr.destroy();
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/**
|
|
112
|
+
* Ask `/usage` of `command` once: `{limits}`, or `{error}` with why it gave none.
|
|
113
|
+
* @param {string} command
|
|
114
|
+
* @param {number} [timeoutMs]
|
|
115
|
+
* @returns {Promise<{limits: any[]} | {error: string}>}
|
|
116
|
+
*/
|
|
117
|
+
export function askUsageOnce(command, timeoutMs = ASK_TIMEOUT_MS) {
|
|
118
|
+
return new Promise((resolve) => {
|
|
119
|
+
let late = false;
|
|
120
|
+
let out = '';
|
|
121
|
+
let err = '';
|
|
122
|
+
// Off Windows the shell leads a group of its own: a timeout signals the group.
|
|
123
|
+
const child = spawn(`${command} ${FLAGS}`, {
|
|
124
|
+
shell: true,
|
|
125
|
+
cwd: os.tmpdir(),
|
|
126
|
+
windowsHide: true,
|
|
127
|
+
detached: process.platform !== 'win32',
|
|
128
|
+
});
|
|
129
|
+
// The answer is a few KB; a runaway one keeps its last 4 MB.
|
|
130
|
+
const keep = (s, d) => (s + d).slice(-(4 << 20));
|
|
131
|
+
child.stdout.setEncoding('utf8').on('data', (d) => (out = keep(out, d)));
|
|
132
|
+
child.stderr.setEncoding('utf8').on('data', (d) => (err = keep(err, d)));
|
|
133
|
+
let ended = false;
|
|
134
|
+
const done = (e) => {
|
|
135
|
+
if (ended) return;
|
|
136
|
+
ended = true;
|
|
137
|
+
clearTimeout(timer);
|
|
138
|
+
const limits = limitsOf(out);
|
|
139
|
+
const why = e && late ? Object.assign(e, { killed: true }) : e;
|
|
140
|
+
resolve(limits ? { limits } : { error: reasonOf(why, err, timeoutMs) });
|
|
141
|
+
};
|
|
142
|
+
|
|
143
|
+
child.on('error', done);
|
|
144
|
+
child.on('close', (code, signal) =>
|
|
145
|
+
done(code === 0 ? null : new Error(`${command} /usage ended with ${code ?? signal}`)),
|
|
146
|
+
);
|
|
147
|
+
const timer = setTimeout(() => {
|
|
148
|
+
late = true;
|
|
149
|
+
killAll(child);
|
|
150
|
+
}, timeoutMs);
|
|
151
|
+
timer.unref();
|
|
152
|
+
});
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/** The kept reading, `{at, limits, failed?}`, or null. */
|
|
156
|
+
export function lastReading(file = usageFile()) {
|
|
157
|
+
try {
|
|
158
|
+
const x = JSON.parse(readFileSync(file, 'utf8'));
|
|
159
|
+
|
|
160
|
+
return x && Array.isArray(x.limits) ? x : null;
|
|
161
|
+
} catch {
|
|
162
|
+
return null;
|
|
163
|
+
}
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
const fresh = (r, maxAgeMs, now) =>
|
|
167
|
+
Boolean(r?.at) && now - Date.parse(r.at) < maxAgeMs && !r.failed;
|
|
168
|
+
|
|
169
|
+
// One ask a process: a second caller waits for it (claim gives the lock to its own pid again).
|
|
170
|
+
let inFlight = null;
|
|
171
|
+
|
|
172
|
+
/**
|
|
173
|
+
* The account's limits, from `usage.json` when it is younger than `maxAgeMs`, else asked of
|
|
174
|
+
* `command` under the account's lock and kept; a failed ask keeps the last limits with why.
|
|
175
|
+
* @param {{command: string, maxAgeMs?: number, timeoutMs?: number, now?: () => number}} o
|
|
176
|
+
*/
|
|
177
|
+
export async function readUsage({
|
|
178
|
+
command,
|
|
179
|
+
maxAgeMs = USAGE_MAX_AGE_MS,
|
|
180
|
+
timeoutMs,
|
|
181
|
+
now = Date.now,
|
|
182
|
+
}) {
|
|
183
|
+
const kept = lastReading();
|
|
184
|
+
if (fresh(kept, maxAgeMs, now())) return kept;
|
|
185
|
+
inFlight ??= askShared(command, maxAgeMs, timeoutMs, now).finally(() => {
|
|
186
|
+
inFlight = null;
|
|
187
|
+
});
|
|
188
|
+
|
|
189
|
+
return inFlight;
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
/** The ask under the account's lock: another process's fresh reading meanwhile is taken. */
|
|
193
|
+
async function askShared(command, maxAgeMs, timeoutMs, now) {
|
|
194
|
+
mkdirSync(gcfHome(), { recursive: true });
|
|
195
|
+
const lock = path.join(gcfHome(), 'usage.lock');
|
|
196
|
+
const t0 = now();
|
|
197
|
+
let release = await claim(lock);
|
|
198
|
+
// Another process asks: wait for its reading, up to one ask's time.
|
|
199
|
+
while (!release && now() - t0 < (timeoutMs ?? ASK_TIMEOUT_MS) + 5000) {
|
|
200
|
+
await new Promise((r) => setTimeout(r, 200));
|
|
201
|
+
const theirs = lastReading();
|
|
202
|
+
if (fresh(theirs, maxAgeMs, now())) return theirs;
|
|
203
|
+
release = await claim(lock);
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
// Still held: no ask and no write past its owner (Codex review); a failed reading goes.
|
|
207
|
+
if (!release) return heldReading(now);
|
|
208
|
+
|
|
209
|
+
try {
|
|
210
|
+
const got = await askUsageOnce(command, timeoutMs);
|
|
211
|
+
const at = new Date(now()).toISOString();
|
|
212
|
+
const last = lastReading();
|
|
213
|
+
const reading =
|
|
214
|
+
'limits' in got
|
|
215
|
+
? { at, limits: got.limits }
|
|
216
|
+
: { at: last?.at ?? null, limits: last?.limits ?? [], failed: { at, error: got.error } };
|
|
217
|
+
writeAtomic(usageFile(), `${JSON.stringify(reading)}\n`);
|
|
218
|
+
|
|
219
|
+
return reading;
|
|
220
|
+
} finally {
|
|
221
|
+
await release?.();
|
|
222
|
+
}
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
/** The last reading, failed: another process held the account's lock past one ask's time. */
|
|
226
|
+
function heldReading(now) {
|
|
227
|
+
const last = lastReading();
|
|
228
|
+
const at = new Date(now()).toISOString();
|
|
229
|
+
|
|
230
|
+
return {
|
|
231
|
+
at: last?.at ?? null,
|
|
232
|
+
limits: last?.limits ?? [],
|
|
233
|
+
failed: { at, error: 'another process held usage.lock past one ask' },
|
|
234
|
+
};
|
|
235
|
+
}
|
|
236
|
+
|
|
237
|
+
/** Whether a weekly limit scoped to a model is the run's model's. */
|
|
238
|
+
const scopedTo = (limit, model) => {
|
|
239
|
+
// `*`: any model's week counts - a caller that does not know the run's model (the board).
|
|
240
|
+
if (model === '*') return true;
|
|
241
|
+
const name = String(limit.scope?.model?.display_name ?? '').toLowerCase();
|
|
242
|
+
|
|
243
|
+
return (
|
|
244
|
+
Boolean(name) &&
|
|
245
|
+
String(model ?? '')
|
|
246
|
+
.toLowerCase()
|
|
247
|
+
.includes(name)
|
|
248
|
+
);
|
|
249
|
+
};
|
|
250
|
+
|
|
251
|
+
/**
|
|
252
|
+
* The reserve's gate over a reading (`usage.json`): a failed ask is no reading, so it goes
|
|
253
|
+
* (Hold-Plan d10), as does none.
|
|
254
|
+
* @param {any} reading
|
|
255
|
+
* @param {string | null | undefined} model
|
|
256
|
+
* @param {number} pct
|
|
257
|
+
* @param {number} [now]
|
|
258
|
+
*/
|
|
259
|
+
export const reserveOfReading = (reading, model, pct, now = Date.now()) =>
|
|
260
|
+
reading && !reading.failed ? reserveOf(reading.limits, model, pct, now) : { go: true };
|
|
261
|
+
|
|
262
|
+
/**
|
|
263
|
+
* The reserve's gate (Hold-Plan d10) over the limits: the 5-hour window at `100 - pct` or more
|
|
264
|
+
* waits for its reset (`{wait, until, reserve}`); the week's, all models or the run's, or a reset
|
|
265
|
+
* past the longest wait, stops (`{stop, why: 'reserve', reserve}`); else `{go}`. No limits: go.
|
|
266
|
+
* @param {any[] | null | undefined} limits
|
|
267
|
+
* @param {string | null | undefined} model
|
|
268
|
+
* @param {number} pct
|
|
269
|
+
* @param {number} [now]
|
|
270
|
+
*/
|
|
271
|
+
export function reserveOf(limits, model, pct, now = Date.now()) {
|
|
272
|
+
if (!limits?.length) return { go: true };
|
|
273
|
+
// A window whose reset has passed says nothing of now: its percent is from before it.
|
|
274
|
+
const passed = (l) => Boolean(l.resets_at) && Date.parse(l.resets_at) <= now;
|
|
275
|
+
const over = (l) => l.percent >= 100 - pct && !passed(l);
|
|
276
|
+
const weekly = limits.find(
|
|
277
|
+
(l) =>
|
|
278
|
+
over(l) && (l.kind === 'weekly_all' || (l.kind === 'weekly_scoped' && scopedTo(l, model))),
|
|
279
|
+
);
|
|
280
|
+
if (weekly) return { stop: true, why: 'reserve', reserve: { weekly: true } };
|
|
281
|
+
const session = limits.find((l) => l.kind === 'session' && over(l));
|
|
282
|
+
if (!session) return { go: true };
|
|
283
|
+
const until = session.resets_at ? new Date(session.resets_at) : null;
|
|
284
|
+
if (!until || Number.isNaN(until.getTime()) || until.getTime() - now > MAX_WAIT_MS)
|
|
285
|
+
return { stop: true, why: 'reserve', reserve: { until: session.resets_at ?? null } };
|
|
286
|
+
|
|
287
|
+
return { wait: true, until, reserve: true };
|
|
288
|
+
}
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "gcf-session",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.19.0",
|
|
4
4
|
"private": true,
|
|
5
5
|
"description": "The session engine of GCF: one agent session and a run as a chain of them, the chat protocol, the provider adapters. Bundled by gcf-harness-aif-ext and gcf-board, never published.",
|
|
6
6
|
"type": "module",
|
|
@@ -26,6 +26,8 @@ export type ChatEvent = At &
|
|
|
26
26
|
limit_resets?: string | null;
|
|
27
27
|
}
|
|
28
28
|
| { type: 'limit'; until: string }
|
|
29
|
+
/** The operator's Hold or the quota's reserve: the session hands over (Hold-Plan d4). */
|
|
30
|
+
| { type: 'held'; reason: 'hold' | 'reserve' | string }
|
|
29
31
|
/** A project chat's: the operator closed its agent; `dropped` messages it never took in. */
|
|
30
32
|
| { type: 'closed'; dropped: number }
|
|
31
33
|
| {
|
|
@@ -142,10 +144,11 @@ export type ChatEvent = At &
|
|
|
142
144
|
lessons: number;
|
|
143
145
|
process: string | null;
|
|
144
146
|
}
|
|
145
|
-
|
|
147
|
+
/** The planning phase's end: converged in `passes`, or `stalled` with each pass's count. */
|
|
148
|
+
| { type: 'step'; step: 'plan'; passes: number; stalled?: number[] }
|
|
146
149
|
| {
|
|
147
150
|
type: 'step';
|
|
148
|
-
step: 'dod' | 'review' | 'commit';
|
|
151
|
+
step: 'dod' | 'review' | 'commit' | 'build';
|
|
149
152
|
ok: boolean | null;
|
|
150
153
|
text?: string;
|
|
151
154
|
}
|
|
@@ -245,3 +248,58 @@ export declare function answerMsOf(min: number | undefined): number;
|
|
|
245
248
|
// The rest of the engine is used from the harness's JavaScript: typed where TypeScript reads it.
|
|
246
249
|
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
|
247
250
|
export declare const runThread: (...args: any[]) => Promise<any>;
|
|
251
|
+
|
|
252
|
+
/** The account's usage limits and the quota's reserve (Hold-Plan d10, d11). */
|
|
253
|
+
export interface UsageReading {
|
|
254
|
+
at: string | null;
|
|
255
|
+
limits: Array<{
|
|
256
|
+
kind: string;
|
|
257
|
+
group?: string;
|
|
258
|
+
percent: number;
|
|
259
|
+
resets_at?: string | null;
|
|
260
|
+
scope?: { model?: { display_name?: string } | null; surface?: unknown } | null;
|
|
261
|
+
severity?: string;
|
|
262
|
+
is_active?: boolean;
|
|
263
|
+
}>;
|
|
264
|
+
failed?: { at: string; error: string };
|
|
265
|
+
}
|
|
266
|
+
export type ReserveGate =
|
|
267
|
+
| { go: true }
|
|
268
|
+
| { wait: true; until: Date; reserve: true }
|
|
269
|
+
| { stop: true; why: 'reserve'; reserve: { weekly?: boolean; until?: string | null } };
|
|
270
|
+
export declare const RESERVE_PCT: number;
|
|
271
|
+
export declare const USAGE_MAX_AGE_MS: number;
|
|
272
|
+
export declare function gcfHome(): string;
|
|
273
|
+
export declare function usageFile(): string;
|
|
274
|
+
export declare function accountSettings(): Record<string, unknown> & { quota_reserve_pct: number };
|
|
275
|
+
export declare function saveAccountSettings(settings: Record<string, unknown>): void;
|
|
276
|
+
export declare function limitsOf(out: string): UsageReading['limits'] | null;
|
|
277
|
+
export declare function reasonOf(
|
|
278
|
+
e: (Error & { killed?: boolean }) | null,
|
|
279
|
+
err: string,
|
|
280
|
+
timeoutMs?: number,
|
|
281
|
+
): string;
|
|
282
|
+
export declare function askUsageOnce(
|
|
283
|
+
command: string,
|
|
284
|
+
timeoutMs?: number,
|
|
285
|
+
): Promise<{ limits: UsageReading['limits'] } | { error: string }>;
|
|
286
|
+
export declare function lastReading(file?: string): UsageReading | null;
|
|
287
|
+
export declare function readUsage(o: {
|
|
288
|
+
command: string;
|
|
289
|
+
maxAgeMs?: number;
|
|
290
|
+
timeoutMs?: number;
|
|
291
|
+
now?: () => number;
|
|
292
|
+
}): Promise<UsageReading>;
|
|
293
|
+
export declare function reserveOf(
|
|
294
|
+
limits: UsageReading['limits'] | null | undefined,
|
|
295
|
+
model: string | null | undefined,
|
|
296
|
+
pct: number,
|
|
297
|
+
now?: number,
|
|
298
|
+
): ReserveGate;
|
|
299
|
+
export declare function writeAtomic(file: string, text: string): void;
|
|
300
|
+
export declare function reserveOfReading(
|
|
301
|
+
reading: UsageReading | null | undefined,
|
|
302
|
+
model: string | null | undefined,
|
|
303
|
+
pct: number,
|
|
304
|
+
now?: number,
|
|
305
|
+
): ReserveGate;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "gcf-board",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.23.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",
|