gcf-harness-aif-ext 0.9.10 → 0.11.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +8 -0
- package/commands/chat-input.js +224 -0
- package/commands/chat.js +415 -0
- package/commands/harness.js +64 -5
- package/commands/milestones.js +102 -0
- package/commands/run.js +198 -45
- package/extension.json +1 -1
- package/package.json +2 -2
- package/skills/gcf-run/SKILL.md +93 -86
package/README.md
CHANGED
|
@@ -47,6 +47,14 @@ Updating keeps the hook entry valid — it points into the extension's install d
|
|
|
47
47
|
|
|
48
48
|
0.5.1 is a fix release. During a run, `gcf/config.yml` is always readable, and a Grep inside `gcf/` reads only readset files. An import breaks a `depends:` cycle the pair checks closed and asks a D1 about it. It cuts a section longer than a segment at paragraphs, and lens and pair prompts carry a window around the quote. `/gcf-run` checks the plan against each pillar's invariant and asks each pillar's review question over the diff. Use it with core 0.4.1, which brings the parent feature into the readset.
|
|
49
49
|
|
|
50
|
+
0.11.1 reworks the chat (docs/Chat-Plan.md) and needs gcf-aif-ext 0.11.1 for its settings (an older core gives the defaults):
|
|
51
|
+
- `chat:` of `gcf/config.yml` decides who waits for whom: `ask` (`d1` by default: only the human's decisions by a question card; `all`; `none`: each card is denied, the agent decides) goes to the skill as `/gcf-run <id> --ask d1|all`; `answer_timeout_min` (15) is how long a question waits, 0 when nobody watches (then `ask` is `none`). `--chat-timeout` has no default any more: it overrides the setting for one run, 0 allowed.
|
|
52
|
+
- `ai-factory gcf-harness chat <id> say [text] [--text-file <path|->] [--image <path>]…`, `answer <request_id> [text] [--answers-file <path|->]`, `interrupt` writes the operator's input: checked (text up to 64 000 characters, up to 10 png/jpg/gif/webp pictures of 5 MB each, an answer to an open card only), never through a link, and only while a live session reads it. Exit 1: bad input; 3: no live chat session; 4: the write failed. A picture is copied into `.gcf-session/runs/<id>.att/`, not git; `chat-in.jsonl` names it by path.
|
|
53
|
+
- `<id>.chat.jsonl` adds the run's milestones from the main agent's tool calls (`step`: the plan converged with its passes, the DoD, the review subagent the skill names `gcf review`, a commit, the item's move; in a worktree the move main recorded), each session's start and end, the handoff flag, the context share at each turn's end, and an `error` for input that reached no one (a dropped card, a missing picture, a message after the item's last session).
|
|
54
|
+
- A turn whose messages the agent never echoed as read frees the session after 10 s with no new turn. After the operator's interrupt the session waits for them with no default answer, while the session's timeout runs on. A session flagged for a handoff closes at its turn's end, as without the chat: no more reminder to hand over. A card a session took with it at its end is dropped.
|
|
55
|
+
|
|
56
|
+
0.10.0 adds the chat (docs/Chat-Plan.md, stage 1): `run --chat` keeps each agent session open to the operator. The prompt goes in as the session's first stream-json message on stdin. The operator writes into `.gcf-session/runs/<id>.chat-in.jsonl`, one JSON a line: `{"type":"say","text":…,"images":[{media_type,data}]}`, `{"type":"interrupt"}` (stops the agent's step, the session stays), `{"type":"answer","request_id":…,"answers":{…}}` (a question card). What the operator reads goes to `<id>.chat.jsonl`: the agent's text, each message sent and when the agent read it, question cards and their answers, the end of each turn. A question waits `--chat-timeout` minutes (15 by default), and the session's own timeout stands still meanwhile; then the run answers: the card's recommended option, or `take your safe default, or block the item`. A turn that ends without the item's move waits the same way, once. Without `--chat` nothing changes. A session flagged for a handoff closes once it went on past its flag, and the fresh one takes the chat on; flagged on its turn's last message, it is first told to hand over. A message sent while a question card is open leaves the card its timeout. `--chat` adds `claude`'s stream-json flags to the agent's command: another `--agent` must take them. Any other tool approval the agent asks for is denied: the run's permissions decide. Checked live with `claude` (Haiku): the prompt on stdin, an interrupt, the operator's message, the item blocked, the session closed.
|
|
57
|
+
|
|
50
58
|
0.9.10 makes a main run's session marks its own (with core 0.10.2): the run sets `GCF_RUN_OWNER=run:<pid>`, its core calls and every agent session it starts (a fresh one after a handoff too) inherit it, and the core refuses the mark to anyone else. An item another session has claimed is refused with `worked by another agent session`. `/gcf-run` reports a refused claim and goes on with the next item; it never releases another session's mark, and neither does the run (`gcf-harness stop` still does: that is the human's). The readset-guard hook keeps only its own session's marks fresh (and marks that name nobody), so another session's mark expires when that session stops.
|
|
51
59
|
|
|
52
60
|
0.9.9 changes no code: its peer range adds core 0.10.0, whose board read is schema 3 and names this harness as the domain's runner (the harness reads neither).
|
|
@@ -0,0 +1,224 @@
|
|
|
1
|
+
// `gcf-harness chat <id> say|answer|interrupt` (docs/Chat-Plan.md): the operator writes into an
|
|
2
|
+
// item's live session, from a console or through the board, which calls this command. The input
|
|
3
|
+
// is checked here and lands as one line of `.gcf-session/runs/<id>.chat-in.jsonl`, which the
|
|
4
|
+
// run's chat reads on; pictures are copied beside it into `<id>.att/` (not git). Only a session
|
|
5
|
+
// that is live takes input: nothing written is lost without a word.
|
|
6
|
+
import { appendFileSync, copyFileSync, lstatSync, mkdirSync, readFileSync } from 'node:fs';
|
|
7
|
+
import { randomBytes } from 'node:crypto';
|
|
8
|
+
import path from 'node:path';
|
|
9
|
+
import { chatIn, chatOut, IMAGE_TYPES } from './chat.js';
|
|
10
|
+
|
|
11
|
+
export const TEXT_MAX = 64_000;
|
|
12
|
+
export const IMAGES_MAX = 10;
|
|
13
|
+
export const IMAGE_MAX = 5 * 1024 * 1024;
|
|
14
|
+
/** A question card's id as claude gives it (`toolu_…`, a uuid): never an option's spelling. */
|
|
15
|
+
export const REQUEST_ID = /^[A-Za-z0-9_][\w-]*$/;
|
|
16
|
+
|
|
17
|
+
/** Bad input: exit 1. No live session: exit 3 (the board answers 409). */
|
|
18
|
+
export class ChatRefusal extends Error {
|
|
19
|
+
constructor(message, code = 1) {
|
|
20
|
+
super(message);
|
|
21
|
+
this.code = code;
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
// The first bytes of each picture type: a renamed file is not a picture.
|
|
26
|
+
const MAGIC = {
|
|
27
|
+
'.png': (b) => b.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 13, 10, 26, 10])),
|
|
28
|
+
'.jpg': (b) => b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff,
|
|
29
|
+
'.jpeg': (b) => b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff,
|
|
30
|
+
'.gif': (b) => b.subarray(0, 4).toString('latin1') === 'GIF8',
|
|
31
|
+
'.webp': (b) =>
|
|
32
|
+
b.subarray(0, 4).toString('latin1') === 'RIFF' &&
|
|
33
|
+
b.subarray(8, 12).toString('latin1') === 'WEBP',
|
|
34
|
+
};
|
|
35
|
+
|
|
36
|
+
const lstatOr = (f) => {
|
|
37
|
+
try {
|
|
38
|
+
return lstatSync(f);
|
|
39
|
+
} catch {
|
|
40
|
+
return null;
|
|
41
|
+
}
|
|
42
|
+
};
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* A link planted in place of a file or a folder on its way would take the write elsewhere, a
|
|
46
|
+
* link to a file not there yet too; a hard link shares the file with another name: none is
|
|
47
|
+
* written through.
|
|
48
|
+
*/
|
|
49
|
+
function refuseLinks(id, dirs, files) {
|
|
50
|
+
for (const f of [...dirs, ...files]) {
|
|
51
|
+
const st = lstatOr(f);
|
|
52
|
+
if (st?.isSymbolicLink() || (files.includes(f) && st?.isFile() && st.nlink > 1))
|
|
53
|
+
throw new ChatRefusal(`${id}'s chat goes through a link: refused`);
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* Whether item `id` has a live chat session: a run that lives drives it (its lock), and its
|
|
59
|
+
* chat's last session event is a start, not an end. Between two sessions of a handoff, before
|
|
60
|
+
* the first and after the last, input would reach no one.
|
|
61
|
+
* shortcut: a line written in the instant between the session's last read and its end reaches
|
|
62
|
+
* no one and gets no error either; drainChat catches it only after the item's last session.
|
|
63
|
+
*/
|
|
64
|
+
export function liveSession(runs, id, lockFor) {
|
|
65
|
+
if (!lockFor(id)) return false;
|
|
66
|
+
let text;
|
|
67
|
+
try {
|
|
68
|
+
text = readFileSync(chatOut(runs, id), 'utf8');
|
|
69
|
+
} catch {
|
|
70
|
+
return false;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
const lines = text.split('\n').filter(Boolean);
|
|
74
|
+
for (let i = lines.length - 1; i >= 0; i--) {
|
|
75
|
+
const type = /"type":"(session|session_end)"/.exec(lines[i])?.[1];
|
|
76
|
+
if (type) return type === 'session';
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
return false;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/** The question card `requestId` still waiting for an answer, from the chat, or null. */
|
|
83
|
+
function openCard(runs, id, requestId) {
|
|
84
|
+
let card = null;
|
|
85
|
+
for (const line of readFileSync(chatOut(runs, id), 'utf8').split('\n')) {
|
|
86
|
+
let e;
|
|
87
|
+
try {
|
|
88
|
+
e = JSON.parse(line);
|
|
89
|
+
} catch {
|
|
90
|
+
continue;
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
if (e.request_id !== requestId) continue;
|
|
94
|
+
if (e.type === 'question') card = e;
|
|
95
|
+
else if (e.type === 'answer' || e.type === 'dropped') card = null;
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
return card;
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/** The text of a message: its words, or a file of it (`-`: stdin, `read(path)`). */
|
|
102
|
+
function textOf(words, file, read) {
|
|
103
|
+
let text;
|
|
104
|
+
try {
|
|
105
|
+
text = file === undefined ? words.join(' ') : read(file);
|
|
106
|
+
} catch (e) {
|
|
107
|
+
throw new ChatRefusal(`--text-file ${file}: ${e.message}`);
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
if (!text.trim()) throw new ChatRefusal('say what: the message is empty');
|
|
111
|
+
if (text.length > TEXT_MAX)
|
|
112
|
+
throw new ChatRefusal(`a message is up to ${TEXT_MAX} characters, this one ${text.length}`);
|
|
113
|
+
|
|
114
|
+
return text;
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
/** Each picture checked, then copied into `<id>.att/`: their paths, relative to the runs dir. */
|
|
118
|
+
function picturesOf(runs, id, files) {
|
|
119
|
+
if (files.length > IMAGES_MAX) throw new ChatRefusal(`up to ${IMAGES_MAX} pictures a message`);
|
|
120
|
+
const checked = files.map((f) => {
|
|
121
|
+
const ext = path.extname(f).toLowerCase();
|
|
122
|
+
const st = lstatOr(f);
|
|
123
|
+
if (!IMAGE_TYPES[ext]) throw new ChatRefusal(`${f}: a picture is png, jpg, gif or webp`);
|
|
124
|
+
if (!st?.isFile()) throw new ChatRefusal(`${f} is not a file (a link is refused)`);
|
|
125
|
+
if (st.size > IMAGE_MAX) throw new ChatRefusal(`${f} is over 5 MB`);
|
|
126
|
+
let head;
|
|
127
|
+
try {
|
|
128
|
+
head = readFileSync(f).subarray(0, 12);
|
|
129
|
+
} catch (e) {
|
|
130
|
+
throw new ChatRefusal(`${f}: ${e.message}`);
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
if (!MAGIC[ext](head))
|
|
134
|
+
throw new ChatRefusal(`${f} is not the ${ext.slice(1)} picture its name says`);
|
|
135
|
+
|
|
136
|
+
return { f, ext };
|
|
137
|
+
});
|
|
138
|
+
const att = path.join(runs, `${id}.att`);
|
|
139
|
+
refuseLinks(id, [att], []);
|
|
140
|
+
if (checked.length) mkdirSync(att, { recursive: true });
|
|
141
|
+
|
|
142
|
+
return checked.map(({ f, ext }) => {
|
|
143
|
+
const name = `${randomBytes(4).toString('hex')}${ext}`;
|
|
144
|
+
copyFileSync(f, path.join(att, name));
|
|
145
|
+
|
|
146
|
+
return `${id}.att/${name}`;
|
|
147
|
+
});
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
/** The answers of a card: one text for a card of one question, or a map of them all. */
|
|
151
|
+
function answersOf(card, words, file, read) {
|
|
152
|
+
const questions = (card.questions ?? []).map((q) => q.question);
|
|
153
|
+
if (file === undefined) {
|
|
154
|
+
if (questions.length !== 1)
|
|
155
|
+
throw new ChatRefusal(
|
|
156
|
+
`this card asks ${questions.length} questions: give --answers-file with each`,
|
|
157
|
+
);
|
|
158
|
+
const text = words.join(' ');
|
|
159
|
+
if (!text.trim()) throw new ChatRefusal('answer what: the answer is empty');
|
|
160
|
+
|
|
161
|
+
return { [questions[0]]: text };
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
let answers;
|
|
165
|
+
try {
|
|
166
|
+
answers = JSON.parse(read(file));
|
|
167
|
+
} catch {
|
|
168
|
+
throw new ChatRefusal('--answers-file is JSON: {"<question>": "<answer>", …}');
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
const keys = Object.keys(answers ?? {});
|
|
172
|
+
const ok =
|
|
173
|
+
typeof answers === 'object' &&
|
|
174
|
+
!Array.isArray(answers) &&
|
|
175
|
+
keys.length === questions.length &&
|
|
176
|
+
keys.every((k) => questions.includes(k) && typeof answers[k] === 'string');
|
|
177
|
+
if (!ok)
|
|
178
|
+
throw new ChatRefusal(`answer each question of the card, as text: ${questions.join(' | ')}`);
|
|
179
|
+
|
|
180
|
+
return answers;
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
/**
|
|
184
|
+
* Write the operator's `action` into item `id`'s chat: `say` (`words` or `textFile`, `image`
|
|
185
|
+
* paths), `answer` (`words[0]` the request id, the rest its text, or `answersFile`), `interrupt`.
|
|
186
|
+
* `lockFor(id)` is the live run lock that drives it; `read(file)` reads a text file or stdin.
|
|
187
|
+
*/
|
|
188
|
+
export function chatInput(projectDir, id, { action, words = [], ...opts }, { lockFor, read }) {
|
|
189
|
+
if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(id)) throw new ChatRefusal(`${id} is not an item id`);
|
|
190
|
+
const session = path.join(path.resolve(projectDir), '.gcf-session');
|
|
191
|
+
const runs = path.join(session, 'runs');
|
|
192
|
+
const file = chatIn(runs, id);
|
|
193
|
+
if (!['say', 'answer', 'interrupt'].includes(action))
|
|
194
|
+
throw new ChatRefusal(`${action}: the action is say, answer or interrupt`);
|
|
195
|
+
refuseLinks(id, [session, runs], [file, chatOut(runs, id)]);
|
|
196
|
+
if (!liveSession(runs, id, lockFor))
|
|
197
|
+
throw new ChatRefusal(`${id} has no live chat session: nothing sent`, 3);
|
|
198
|
+
|
|
199
|
+
let line;
|
|
200
|
+
if (action === 'interrupt') line = { type: 'interrupt' };
|
|
201
|
+
else if (action === 'say') {
|
|
202
|
+
const text = textOf(words, opts.textFile, read);
|
|
203
|
+
const images = picturesOf(runs, id, opts.image ?? []);
|
|
204
|
+
line = { type: 'say', text, ...(images.length ? { images } : {}) };
|
|
205
|
+
} else {
|
|
206
|
+
const [requestId, ...rest] = words;
|
|
207
|
+
if (!requestId) throw new ChatRefusal('answer which question: name its request id');
|
|
208
|
+
if (!REQUEST_ID.test(requestId)) throw new ChatRefusal(`${requestId} is not a request id`);
|
|
209
|
+
const card = openCard(runs, id, requestId);
|
|
210
|
+
if (!card) throw new ChatRefusal(`no open question ${requestId}: nothing sent`);
|
|
211
|
+
line = {
|
|
212
|
+
type: 'answer',
|
|
213
|
+
request_id: requestId,
|
|
214
|
+
answers: answersOf(card, rest, opts.answersFile, read),
|
|
215
|
+
};
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
appendFileSync(file, `${JSON.stringify(line)}\n`);
|
|
219
|
+
|
|
220
|
+
return line;
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
/** A file's text, or stdin's for `-`. */
|
|
224
|
+
export const readText = (file) => readFileSync(file === '-' ? 0 : file, 'utf8');
|
package/commands/chat.js
ADDED
|
@@ -0,0 +1,415 @@
|
|
|
1
|
+
// The chat of a run's live session (docs/Chat-Plan.md, Harness-PRD §10 "чат"): the session reads
|
|
2
|
+
// stream-json on stdin and stays open between turns. The operator writes into
|
|
3
|
+
// `.gcf-session/runs/<id>.chat-in.jsonl` (`gcf-harness chat`, which the board calls); what the
|
|
4
|
+
// operator reads goes to `<id>.chat.jsonl`, one event a line: the talk, the questions, the
|
|
5
|
+
// steps of the run, the sessions. The raw stream stays in `<id>.log`.
|
|
6
|
+
import {
|
|
7
|
+
appendFileSync,
|
|
8
|
+
closeSync,
|
|
9
|
+
lstatSync,
|
|
10
|
+
openSync,
|
|
11
|
+
readFileSync,
|
|
12
|
+
readSync,
|
|
13
|
+
statSync,
|
|
14
|
+
} from 'node:fs';
|
|
15
|
+
import path from 'node:path';
|
|
16
|
+
import { milestones } from './milestones.js';
|
|
17
|
+
|
|
18
|
+
/** What a chat session adds to the agent's command. */
|
|
19
|
+
export const CHAT_FLAGS =
|
|
20
|
+
'--input-format stream-json --permission-prompt-tool stdio --replay-user-messages';
|
|
21
|
+
|
|
22
|
+
/** How long a question waits for the operator when neither the flag nor the config says. */
|
|
23
|
+
export const CHAT_TIMEOUT_MIN = 15;
|
|
24
|
+
|
|
25
|
+
/** What the operator's silence says, past the answer timeout. */
|
|
26
|
+
export const DEFAULT_ANSWER =
|
|
27
|
+
'No answer came in time: take your safe default, or block the item with your question.';
|
|
28
|
+
|
|
29
|
+
/** The denial of a question card in a run that asks the operator nothing (`chat.ask: none`). */
|
|
30
|
+
export const ASK_NONE =
|
|
31
|
+
'answer it yourself and write your choice into the plan: this run asks the operator nothing';
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* A turn ended with messages the agent has not echoed as read: past this with no new turn, they
|
|
35
|
+
* count as read. An echo that never comes must not hold the session for good.
|
|
36
|
+
*/
|
|
37
|
+
export const READ_GRACE_MS = 10_000;
|
|
38
|
+
|
|
39
|
+
/** The pictures a message may carry, by extension: what claude takes as an image block. */
|
|
40
|
+
export const IMAGE_TYPES = {
|
|
41
|
+
'.png': 'image/png',
|
|
42
|
+
'.jpg': 'image/jpeg',
|
|
43
|
+
'.jpeg': 'image/jpeg',
|
|
44
|
+
'.gif': 'image/gif',
|
|
45
|
+
'.webp': 'image/webp',
|
|
46
|
+
};
|
|
47
|
+
|
|
48
|
+
const RECOMMENDED = / \(Recommended\)$/;
|
|
49
|
+
const POLL_MS = 500;
|
|
50
|
+
|
|
51
|
+
export const chatIn = (logs, id) => path.join(logs, `${id}.chat-in.jsonl`);
|
|
52
|
+
export const chatOut = (logs, id) => path.join(logs, `${id}.chat.jsonl`);
|
|
53
|
+
|
|
54
|
+
/** The size of a file, 0 when it is not there: where the operator's next input starts. */
|
|
55
|
+
export function sizeOf(file) {
|
|
56
|
+
try {
|
|
57
|
+
return statSync(file).size;
|
|
58
|
+
} catch {
|
|
59
|
+
return 0;
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/** The new whole lines of `file` from `from` on, and where the next read starts. */
|
|
64
|
+
export function readFrom(file, from) {
|
|
65
|
+
let fd;
|
|
66
|
+
try {
|
|
67
|
+
fd = openSync(file, 'r');
|
|
68
|
+
} catch {
|
|
69
|
+
return { lines: [], next: from };
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
try {
|
|
73
|
+
const buf = Buffer.alloc(Math.max(sizeOf(file) - from, 0));
|
|
74
|
+
const n = readSync(fd, buf, 0, buf.length, from);
|
|
75
|
+
// A line still being written waits for its newline; the offset counts bytes, not letters.
|
|
76
|
+
const end = buf.subarray(0, n).lastIndexOf(10) + 1;
|
|
77
|
+
const lines = buf.subarray(0, end).toString('utf8').split('\n').filter(Boolean);
|
|
78
|
+
|
|
79
|
+
return { lines, next: from + end };
|
|
80
|
+
} finally {
|
|
81
|
+
closeSync(fd);
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/** A question card's answers past the timeout: each one's recommended option, or the default. */
|
|
86
|
+
export function defaultAnswers(questions = []) {
|
|
87
|
+
return Object.fromEntries(
|
|
88
|
+
questions.map((q) => {
|
|
89
|
+
const pick = (q.options ?? []).find((o) => RECOMMENDED.test(o.label ?? ''));
|
|
90
|
+
|
|
91
|
+
return [q.question, pick ? pick.label.replace(RECOMMENDED, '') : DEFAULT_ANSWER];
|
|
92
|
+
}),
|
|
93
|
+
);
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
const parse = (line) => {
|
|
97
|
+
try {
|
|
98
|
+
return JSON.parse(line);
|
|
99
|
+
} catch {
|
|
100
|
+
return null;
|
|
101
|
+
}
|
|
102
|
+
};
|
|
103
|
+
|
|
104
|
+
/** Add an event to what the operator reads of item `id`; a file that cannot be written loses it. */
|
|
105
|
+
export function postTo(file, e) {
|
|
106
|
+
try {
|
|
107
|
+
appendFileSync(file, `${JSON.stringify({ at: new Date().toISOString(), ...e })}\n`);
|
|
108
|
+
} catch {
|
|
109
|
+
// The chat file is the operator's view: the session goes on without it.
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
const post = (c, e) => postTo(c.out, e);
|
|
114
|
+
|
|
115
|
+
const send = (c, e) => {
|
|
116
|
+
if (!c.stdin.writableEnded) c.stdin.write(`${JSON.stringify(e)}\n`);
|
|
117
|
+
};
|
|
118
|
+
|
|
119
|
+
const respond = (c, requestId, response) =>
|
|
120
|
+
send(c, {
|
|
121
|
+
type: 'control_response',
|
|
122
|
+
response: { subtype: 'success', request_id: requestId, response },
|
|
123
|
+
});
|
|
124
|
+
|
|
125
|
+
/** Wait for the operator; `onTimeout` answers for them when the answer time passes. */
|
|
126
|
+
function waitFor(c, kind, onTimeout) {
|
|
127
|
+
if (c.wait) return;
|
|
128
|
+
c.pause(true);
|
|
129
|
+
post(c, { type: 'waiting', kind });
|
|
130
|
+
c.wait = setTimeout(() => {
|
|
131
|
+
c.wait = null;
|
|
132
|
+
c.pause(false);
|
|
133
|
+
post(c, { type: 'timeout', kind });
|
|
134
|
+
onTimeout();
|
|
135
|
+
}, c.answerMs);
|
|
136
|
+
// The session's own process keeps the run alive; a wait alone must not.
|
|
137
|
+
c.wait.unref();
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
function stopWaiting(c) {
|
|
141
|
+
if (!c.wait) return;
|
|
142
|
+
clearTimeout(c.wait);
|
|
143
|
+
c.wait = null;
|
|
144
|
+
c.pause(false);
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
/**
|
|
148
|
+
* The image blocks of a message's pictures, each a path inside the runs directory (`<id>.att/…`,
|
|
149
|
+
* where `gcf-harness chat` put it); null when one is not there or not a picture.
|
|
150
|
+
*/
|
|
151
|
+
function imagesOf(c, paths) {
|
|
152
|
+
const blocks = [];
|
|
153
|
+
for (const p of paths) {
|
|
154
|
+
const file = path.resolve(c.logs, String(p));
|
|
155
|
+
const type = IMAGE_TYPES[path.extname(file).toLowerCase()];
|
|
156
|
+
// Only the runs directory's own files, never through a link.
|
|
157
|
+
const inside = file.startsWith(path.resolve(c.logs) + path.sep);
|
|
158
|
+
/** @type {string | null} */
|
|
159
|
+
let data = null;
|
|
160
|
+
try {
|
|
161
|
+
if (inside && type && lstatSync(file).isFile()) data = readFileSync(file).toString('base64');
|
|
162
|
+
} catch {
|
|
163
|
+
// Gone: refused below.
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
if (!data) return null;
|
|
167
|
+
blocks.push({ type: 'image', source: { type: 'base64', media_type: type, data } });
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
return blocks;
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
/** A message into the session; `by` is the operator, the run (its prompt) or the timeout. */
|
|
174
|
+
function say(c, text, by, paths = []) {
|
|
175
|
+
if (c.stdin.writableEnded)
|
|
176
|
+
return post(c, {
|
|
177
|
+
type: 'error',
|
|
178
|
+
text: `the session is closing, not sent: ${text.slice(0, 80)}`,
|
|
179
|
+
});
|
|
180
|
+
const images = imagesOf(c, paths);
|
|
181
|
+
if (!images)
|
|
182
|
+
return post(c, { type: 'error', text: `a picture is missing, not sent: ${text.slice(0, 80)}` });
|
|
183
|
+
c.sent++;
|
|
184
|
+
c.stopped = false;
|
|
185
|
+
const content = images.length ? [{ type: 'text', text }, ...images] : text;
|
|
186
|
+
send(c, { type: 'user', message: { role: 'user', content } });
|
|
187
|
+
post(c, { type: 'say', by, text, ...(paths.length ? { images: paths } : {}), n: c.sent });
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
/** Answer a question card; the wait ends with the last one. */
|
|
191
|
+
function answer(c, requestId, answers, by) {
|
|
192
|
+
const input = c.cards.get(requestId);
|
|
193
|
+
if (!input)
|
|
194
|
+
return post(c, {
|
|
195
|
+
type: 'error',
|
|
196
|
+
text: `no open question ${requestId}: the answer is not sent`,
|
|
197
|
+
});
|
|
198
|
+
c.cards.delete(requestId);
|
|
199
|
+
respond(c, requestId, { behavior: 'allow', updatedInput: { ...input, answers } });
|
|
200
|
+
post(c, { type: 'answer', by, request_id: requestId, answers });
|
|
201
|
+
if (!c.cards.size) stopWaiting(c);
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
/** One line of the operator's input file: a message, a stop of the step, or an answer. */
|
|
205
|
+
function take(c, line) {
|
|
206
|
+
const e = parse(line);
|
|
207
|
+
if (!e) return post(c, { type: 'error', text: `not JSON, skipped: ${line.slice(0, 80)}` });
|
|
208
|
+
if (e.type === 'say' && typeof e.text === 'string' && e.text.trim()) {
|
|
209
|
+
// An open card still waits for its answer: its timeout holds.
|
|
210
|
+
if (!c.cards.size) stopWaiting(c);
|
|
211
|
+
c.defaulted = false;
|
|
212
|
+
say(c, e.text, 'operator', Array.isArray(e.images) ? e.images : []);
|
|
213
|
+
} else if (e.type === 'interrupt') {
|
|
214
|
+
send(c, {
|
|
215
|
+
type: 'control_request',
|
|
216
|
+
request_id: `interrupt-${Date.now()}`,
|
|
217
|
+
request: { subtype: 'interrupt' },
|
|
218
|
+
});
|
|
219
|
+
// The operator stopped it to say something: no default answer goes after this turn.
|
|
220
|
+
c.stopped = true;
|
|
221
|
+
post(c, { type: 'interrupt' });
|
|
222
|
+
// Stopped while the session waited for an answer to its text: no turn ends, the wait does.
|
|
223
|
+
if (c.wait && !c.cards.size) {
|
|
224
|
+
stopWaiting(c);
|
|
225
|
+
post(c, { type: 'waiting', kind: 'stop' });
|
|
226
|
+
}
|
|
227
|
+
} else if (e.type === 'answer' && e.answers) {
|
|
228
|
+
answer(c, e.request_id, e.answers, 'operator');
|
|
229
|
+
}
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
/** A question card the agent dropped (an interrupt ended its turn): no answer goes to it. */
|
|
233
|
+
function dropCard(c, requestId) {
|
|
234
|
+
if (!c.cards.delete(requestId)) return;
|
|
235
|
+
post(c, { type: 'dropped', request_id: requestId });
|
|
236
|
+
if (!c.cards.size) stopWaiting(c);
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
/** Messages it has not echoed as read count as read once the grace passes with no new turn. */
|
|
240
|
+
function graceRead(c) {
|
|
241
|
+
clearTimeout(c.grace);
|
|
242
|
+
c.grace = setTimeout(() => {
|
|
243
|
+
c.grace = null;
|
|
244
|
+
c.read = c.sent;
|
|
245
|
+
post(c, { type: 'read', n: c.read, assumed: true });
|
|
246
|
+
void settle(c);
|
|
247
|
+
}, c.graceMs);
|
|
248
|
+
c.grace.unref();
|
|
249
|
+
}
|
|
250
|
+
|
|
251
|
+
/**
|
|
252
|
+
* What follows a turn: a message it has not taken in yet starts its next one; a session flagged
|
|
253
|
+
* for a handoff, or whose item moved, closes; one the operator stopped waits for them with no
|
|
254
|
+
* default; else the operator gets the answer time, then the default, once.
|
|
255
|
+
*/
|
|
256
|
+
async function settle(c) {
|
|
257
|
+
if (c.closed) return;
|
|
258
|
+
if (c.read < c.sent) return graceRead(c);
|
|
259
|
+
if (c.handoff().flagged) return c.stdin.end();
|
|
260
|
+
const moved = await c.done?.();
|
|
261
|
+
// The operator may have written meanwhile, or the session ended.
|
|
262
|
+
if (c.closed || c.read < c.sent) return;
|
|
263
|
+
if (moved) return c.stdin.end();
|
|
264
|
+
// The operator's Stop holds even after a default answer went: they are at the screen.
|
|
265
|
+
if (c.stopped) return post(c, { type: 'waiting', kind: 'stop' });
|
|
266
|
+
if (c.defaulted) return c.stdin.end();
|
|
267
|
+
waitFor(c, 'text', () => {
|
|
268
|
+
c.defaulted = true;
|
|
269
|
+
say(c, DEFAULT_ANSWER, 'timeout');
|
|
270
|
+
});
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
/** A turn ended: what it cost the session so far, how full its context is, then what follows. */
|
|
274
|
+
function turnEnd(c, e) {
|
|
275
|
+
// claude's `total_cost_usd`: the session's so far, not the turn's.
|
|
276
|
+
post(c, {
|
|
277
|
+
type: 'turn',
|
|
278
|
+
subtype: e.subtype,
|
|
279
|
+
total_cost_usd: e.total_cost_usd ?? null,
|
|
280
|
+
...c.context(),
|
|
281
|
+
});
|
|
282
|
+
for (const id of [...c.cards.keys()]) dropCard(c, id);
|
|
283
|
+
void settle(c);
|
|
284
|
+
}
|
|
285
|
+
|
|
286
|
+
/** The agent asks to use a tool: a question card waits for the operator, the rest is denied. */
|
|
287
|
+
function toolAsked(c, e) {
|
|
288
|
+
const { tool_name: tool, input = {} } = e.request;
|
|
289
|
+
if (tool !== 'AskUserQuestion' || c.ask === 'none') {
|
|
290
|
+
// The run's permissions decide (bypass with its deny rules); nobody approves here.
|
|
291
|
+
const message =
|
|
292
|
+
tool === 'AskUserQuestion' ? ASK_NONE : `${tool} needs an approval no one gives in a run`;
|
|
293
|
+
respond(c, e.request_id, { behavior: 'deny', message });
|
|
294
|
+
|
|
295
|
+
return post(c, { type: 'denied', tool });
|
|
296
|
+
}
|
|
297
|
+
|
|
298
|
+
c.cards.set(e.request_id, input);
|
|
299
|
+
post(c, { type: 'question', request_id: e.request_id, questions: input.questions ?? [] });
|
|
300
|
+
waitFor(c, 'card', () => {
|
|
301
|
+
for (const [rid, q] of c.cards) answer(c, rid, defaultAnswers(q.questions), 'timeout');
|
|
302
|
+
});
|
|
303
|
+
}
|
|
304
|
+
|
|
305
|
+
// What the operator reads of each event the agent prints, by its type.
|
|
306
|
+
const SEEN = {
|
|
307
|
+
// The main agent's text; a subagent's is the raw log's.
|
|
308
|
+
assistant: (c, e) => {
|
|
309
|
+
if (e.parent_tool_use_id) return;
|
|
310
|
+
// It works on by itself (a read it was assumed not to need): no answer is waited for.
|
|
311
|
+
if (!c.cards.size) stopWaiting(c);
|
|
312
|
+
const text = (e.message?.content ?? []).filter((b) => b.type === 'text').map((b) => b.text);
|
|
313
|
+
if (text.join('').trim()) post(c, { type: 'agent', text: text.join('\n') });
|
|
314
|
+
},
|
|
315
|
+
// A message echoed as the agent takes it in (`--replay-user-messages`): read.
|
|
316
|
+
user: (c, e) => {
|
|
317
|
+
if (!e.isReplay) return;
|
|
318
|
+
// An echo late after the grace assumed it read counts once.
|
|
319
|
+
c.read = Math.min(c.read + 1, c.sent);
|
|
320
|
+
post(c, { type: 'read', n: c.read });
|
|
321
|
+
},
|
|
322
|
+
control_request: (c, e) => e.request?.subtype === 'can_use_tool' && toolAsked(c, e),
|
|
323
|
+
control_cancel_request: (c, e) => dropCard(c, e.request_id),
|
|
324
|
+
result: (c, e) => turnEnd(c, e),
|
|
325
|
+
};
|
|
326
|
+
|
|
327
|
+
/** One line the agent printed. */
|
|
328
|
+
function see(c, line) {
|
|
329
|
+
const e = parse(line);
|
|
330
|
+
if (!e) return;
|
|
331
|
+
// A new turn has begun: the messages it echoes count themselves.
|
|
332
|
+
if (c.grace && (e.type === 'assistant' || e.type === 'user')) {
|
|
333
|
+
clearTimeout(c.grace);
|
|
334
|
+
c.grace = null;
|
|
335
|
+
}
|
|
336
|
+
|
|
337
|
+
for (const step of c.steps.see(e)) post(c, step);
|
|
338
|
+
if (Object.hasOwn(SEEN, e.type)) SEEN[e.type](c, e);
|
|
339
|
+
}
|
|
340
|
+
|
|
341
|
+
/**
|
|
342
|
+
* The chat of one session. `stdin` is the agent's; `input.at` is where the operator's input is
|
|
343
|
+
* read from, kept across the item's sessions; `answerMs` is how long a question waits; `ask`
|
|
344
|
+
* what the agent may ask by a card (`none`: each card is denied); `done()` says the item made
|
|
345
|
+
* its move, so the session may close; `handoff()` is the handoff watch's state (`{flagged}`):
|
|
346
|
+
* a flagged session closes at its turn's end; `context()` the context it holds
|
|
347
|
+
* (`{context, context_pct}`); `pause(on)` stops the session's timeout while it waits for the
|
|
348
|
+
* operator; `prompt` is the first message; `kind` how the session started (`start`, `resume`,
|
|
349
|
+
* `handoff`). `see(line)` takes each line the agent prints; `event(e)` posts one the run saw;
|
|
350
|
+
* `close(code, seen)` stops reading and posts the session's end.
|
|
351
|
+
*/
|
|
352
|
+
export function openChat({
|
|
353
|
+
logs,
|
|
354
|
+
id,
|
|
355
|
+
stdin,
|
|
356
|
+
input,
|
|
357
|
+
answerMs,
|
|
358
|
+
ask = 'd1',
|
|
359
|
+
done,
|
|
360
|
+
pause,
|
|
361
|
+
prompt,
|
|
362
|
+
handoff,
|
|
363
|
+
context = () => ({}),
|
|
364
|
+
kind = 'start',
|
|
365
|
+
graceMs = READ_GRACE_MS,
|
|
366
|
+
steps = milestones(),
|
|
367
|
+
}) {
|
|
368
|
+
const c = {
|
|
369
|
+
...{ out: chatOut(logs, id), logs, stdin, answerMs, ask, done, pause, handoff, context },
|
|
370
|
+
...{ sent: 0, read: 0, cards: new Map(), wait: null, defaulted: false, closed: false },
|
|
371
|
+
...{ stopped: false, grace: null, graceMs, steps },
|
|
372
|
+
};
|
|
373
|
+
const poll = setInterval(() => {
|
|
374
|
+
const { lines, next } = readFrom(chatIn(logs, id), input.at);
|
|
375
|
+
input.at = next;
|
|
376
|
+
for (const l of lines) take(c, l);
|
|
377
|
+
}, POLL_MS);
|
|
378
|
+
// A session that ended under a write to its stdin breaks the pipe: the end is its close.
|
|
379
|
+
stdin.on('error', () => {});
|
|
380
|
+
post(c, { type: 'session', kind });
|
|
381
|
+
say(c, prompt, 'run');
|
|
382
|
+
|
|
383
|
+
return {
|
|
384
|
+
see: (line) => see(c, line),
|
|
385
|
+
event: (e) => post(c, e),
|
|
386
|
+
close: (code, seen = {}) => {
|
|
387
|
+
c.closed = true;
|
|
388
|
+
clearInterval(poll);
|
|
389
|
+
clearTimeout(c.grace ?? undefined);
|
|
390
|
+
// A card the session took with it can be answered no more.
|
|
391
|
+
for (const rid of [...c.cards.keys()]) dropCard(c, rid);
|
|
392
|
+
stopWaiting(c);
|
|
393
|
+
post(c, {
|
|
394
|
+
type: 'session_end',
|
|
395
|
+
code,
|
|
396
|
+
cost_usd: seen.cost?.cost_usd ?? null,
|
|
397
|
+
...(seen.limit ? { limit_resets: seen.limit.resets } : {}),
|
|
398
|
+
});
|
|
399
|
+
},
|
|
400
|
+
};
|
|
401
|
+
}
|
|
402
|
+
|
|
403
|
+
/**
|
|
404
|
+
* The operator's input no session read: written after the item's last one ended. Each line gets
|
|
405
|
+
* an `error` event, so nothing is lost without a word.
|
|
406
|
+
*/
|
|
407
|
+
export function drainChat(logs, id, input) {
|
|
408
|
+
const { lines, next } = readFrom(chatIn(logs, id), input.at);
|
|
409
|
+
input.at = next;
|
|
410
|
+
for (const l of lines)
|
|
411
|
+
postTo(chatOut(logs, id), {
|
|
412
|
+
type: 'error',
|
|
413
|
+
text: `the item's session has ended, not sent: ${l.slice(0, 80)}`,
|
|
414
|
+
});
|
|
415
|
+
}
|