pi-braid 0.40.6 → 0.41.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,376 @@
1
+ /**
2
+ * A node driver that owns one pi RPC child per turn.
3
+ *
4
+ * The supervisor holds no model and no agent runtime: a node is a pi session,
5
+ * and a session exists only while a turn is being driven. That is what keeps
6
+ * the idle cost at zero and what makes the process boundary the crash
7
+ * boundary the journal has to survive.
8
+ *
9
+ * Framing is strict JSONL and records are split on LF only: a generic line
10
+ * reader also splits on U+2028/U+2029, which are legal inside a JSON string.
11
+ *
12
+ * The child is spawned detached so it gets its own process group. The group id
13
+ * is journalled with the turn, and it is the fence: a restarted supervisor
14
+ * kills the group a dead predecessor left behind before it resumes that node,
15
+ * so a stale drive cannot keep writing after its supervisor is gone.
16
+ *
17
+ * Steering is queued, not delivered. pi answers a `steer` request with the
18
+ * disposition of its queue and hands the message to the model later, if the
19
+ * turn gets that far. The one observable moment is the user message carrying
20
+ * that text arriving on this child's event stream, so that is what
21
+ * `steer_delivered` reports. A driver that reported the ack instead would be
22
+ * reporting a request the fleet made, not an event the fleet saw.
23
+ */
24
+
25
+ import { spawn } from "node:child_process";
26
+ import { fileURLToPath } from "node:url";
27
+
28
+ import { GUARD_ENV } from "./tool-guard.mjs";
29
+
30
+ const DEFAULT_REQUEST_TIMEOUT_MS = 120_000;
31
+
32
+ /**
33
+ * How many queued steer texts this driver tracks at once. A long turn can be
34
+ * steered many times; the ones that matter are the ones still waiting, so the
35
+ * list keeps the newest and forgets the oldest rather than growing with the
36
+ * turn.
37
+ */
38
+ const MAX_PENDING_STEERS = 32;
39
+
40
+ /** The text of a message's content, which is either a string or text blocks. */
41
+ function messageText(content) {
42
+ if (typeof content === "string") return content;
43
+ if (!Array.isArray(content)) return "";
44
+ return content
45
+ .filter((block) => block?.type === "text" && typeof block.text === "string")
46
+ .map((block) => block.text)
47
+ .join("\n");
48
+ }
49
+
50
+ /**
51
+ * The guard every child loads, whatever else it is or is not given.
52
+ *
53
+ * It is resolved from this module's own location rather than from a configured
54
+ * path, so a fleet root cannot point a child at a guard that is not the one
55
+ * shipped beside the driver that spawned it.
56
+ */
57
+ export const GUARD_EXTENSION = fileURLToPath(new URL("./tool-guard.mjs", import.meta.url));
58
+
59
+ /**
60
+ * The child-side contract the guard reads. Env because it is the only channel
61
+ * a spawned child inherits without a second configuration source, and because
62
+ * the values are per-turn: the driver is constructed after `beginTurn` has
63
+ * assigned the turn id, so they are known before the spawn.
64
+ *
65
+ * An incomplete contract yields an empty environment, and the guard then
66
+ * registers no hook at all rather than guarding the wrong turn.
67
+ */
68
+ export function guardEnvironment({ root, nodeId, turnId }) {
69
+ if (!root || nodeId == null || turnId == null) return {};
70
+ return {
71
+ [GUARD_ENV.root]: String(root),
72
+ [GUARD_ENV.node]: String(nodeId),
73
+ [GUARD_ENV.turn]: String(turnId),
74
+ };
75
+ }
76
+
77
+ export class RpcDriver {
78
+ /**
79
+ * @param {object} args
80
+ * @param {string} args.piBin absolute path or PATH name of the pi executable
81
+ * @param {string} args.cwd workspace root the node works in
82
+ * @param {string} args.sessionId session id the node keeps across turns
83
+ * @param {string} args.sessionDir where pi stores the session file
84
+ * @param {string} args.model provider/model string passed to the child
85
+ * @param {string[]} args.extensions extra `-e` entries (provider packages a lean child needs)
86
+ * @param {string} args.guardExtension the duplication guard every child loads
87
+ * @param {string[]} args.extraArgs additional child flags
88
+ * @param {Record<string,string>} args.env child environment
89
+ * @param {(event: object) => void} args.onEvent normalized event sink
90
+ */
91
+ constructor(args) {
92
+ this.kind = "rpc";
93
+ this.cfg = args;
94
+ this.child = null;
95
+ this.pid = null;
96
+ this.pgid = null;
97
+ this.sessionId = args.sessionId;
98
+ this.sessionFile = null;
99
+ this.exit = null;
100
+ this.pending = new Map();
101
+ this.buffer = "";
102
+ this.seq = 0;
103
+ this.messageCount = 0;
104
+ this.toolCount = 0;
105
+ this.requests = 0;
106
+ this.stderr = "";
107
+ this.settled = false;
108
+ // Steer texts the child has queued and has not yet run. A text leaves this
109
+ // list when the user message carrying it arrives, or when the ack says the
110
+ // queue will never hand it on.
111
+ this.pendingSteers = [];
112
+ }
113
+
114
+ args() {
115
+ const cfg = this.cfg;
116
+ const args = [
117
+ "--mode",
118
+ "rpc",
119
+ "--session-id",
120
+ cfg.sessionId,
121
+ "--session-dir",
122
+ cfg.sessionDir,
123
+ "--thinking",
124
+ cfg.thinking ?? "off",
125
+ "--model",
126
+ cfg.model,
127
+ "--no-mcp",
128
+ "--no-context-files",
129
+ ];
130
+ if (!cfg.fullDiscovery) {
131
+ args.push("--no-extensions", "--no-skills", "--no-prompt-templates");
132
+ for (const ext of cfg.extensions ?? []) args.push("-e", ext);
133
+ }
134
+ // The guard is not an optional extension: it loads in both resource modes,
135
+ // because a child that discovers its own extensions still needs the one
136
+ // that refuses a duplicated effect.
137
+ if (cfg.guardExtension) args.push("-e", cfg.guardExtension);
138
+ args.push(...(cfg.extraArgs ?? []));
139
+ return args;
140
+ }
141
+
142
+ async start() {
143
+ const child = spawn(this.cfg.piBin ?? "pi", this.args(), {
144
+ cwd: this.cfg.cwd,
145
+ detached: true,
146
+ env: { ...process.env, ...(this.cfg.env ?? {}) },
147
+ stdio: ["pipe", "pipe", "pipe"],
148
+ });
149
+ this.child = child;
150
+ this.pid = child.pid;
151
+ this.pgid = child.pid;
152
+ this.exit = new Promise((resolveExit) => child.once("exit", (code, signal) => resolveExit({ code, signal })));
153
+ child.stderr.on("data", (chunk) => {
154
+ this.stderr = (this.stderr + chunk.toString("utf8")).slice(-8000);
155
+ });
156
+ child.stdout.on("data", (chunk) => this._read(chunk));
157
+ child.once("error", (error) => this._failAll(error));
158
+ this.exit.then(() => this._failAll(new Error(`child exited (pid ${this.pid})`)));
159
+ const state = (await this.request({ type: "get_state" }))?.data ?? {};
160
+ this.sessionId = state.sessionId ?? this.sessionId;
161
+ this.sessionFile = state.sessionFile ?? null;
162
+ this.messageCount = state.messageCount ?? 0;
163
+ return { sessionId: this.sessionId, sessionFile: this.sessionFile };
164
+ }
165
+
166
+ _read(chunk) {
167
+ this.buffer += chunk.toString("utf8");
168
+ let index;
169
+ while ((index = this.buffer.indexOf("\n")) >= 0) {
170
+ const line = this.buffer.slice(0, index).replace(/\r$/, "");
171
+ this.buffer = this.buffer.slice(index + 1);
172
+ if (!line.trim()) continue;
173
+ let record;
174
+ try {
175
+ record = JSON.parse(line);
176
+ } catch {
177
+ this.onRaw({ type: "unparsable", line: line.slice(0, 400) });
178
+ continue;
179
+ }
180
+ if (record.type === "response") {
181
+ const entry = this.pending.get(record.id);
182
+ if (entry) {
183
+ this.pending.delete(record.id);
184
+ clearTimeout(entry.timer);
185
+ entry.resolve(record);
186
+ }
187
+ continue;
188
+ }
189
+ this._event(record);
190
+ }
191
+ }
192
+
193
+ _event(record) {
194
+ const emit = (event) => this.onRaw(event);
195
+ switch (record.type) {
196
+ case "tool_execution_start":
197
+ this.toolCount += 1;
198
+ emit({
199
+ type: "tool_start",
200
+ toolCallId: record.toolCallId,
201
+ toolName: record.toolName,
202
+ args: record.args,
203
+ });
204
+ break;
205
+ case "tool_execution_end":
206
+ emit({
207
+ type: "tool_end",
208
+ toolCallId: record.toolCallId,
209
+ toolName: record.toolName,
210
+ result: record.result,
211
+ isError: Boolean(record.isError),
212
+ });
213
+ break;
214
+ case "turn_start":
215
+ this.requests += 1;
216
+ emit({
217
+ type: "model_request",
218
+ seq: this.requests,
219
+ messageCount: this.messageCount,
220
+ toolCount: this.toolCount,
221
+ });
222
+ break;
223
+ case "message_end":
224
+ this.messageCount += 1;
225
+ emit({ type: "message_end", role: record.message?.role, message: record.message });
226
+ if (record.message?.role === "user") {
227
+ const delivered = this._takeSteer(messageText(record.message?.content));
228
+ if (delivered != null) {
229
+ emit({ type: "steer_delivered", afterEffectSeq: this.toolCount, text: delivered });
230
+ }
231
+ }
232
+ break;
233
+ case "agent_settled":
234
+ this.settled = true;
235
+ emit({ type: "settled", aborted: Boolean(record.aborted) });
236
+ break;
237
+ default:
238
+ break;
239
+ }
240
+ }
241
+
242
+ /** Installed by the supervisor; overwritten immediately after construction. */
243
+ onRaw() {}
244
+
245
+ _forgetSteer(text) {
246
+ const index = this.pendingSteers.indexOf(text);
247
+ if (index !== -1) this.pendingSteers.splice(index, 1);
248
+ }
249
+
250
+ /** The queued text this user message carries, or null when it carries none. */
251
+ _takeSteer(text) {
252
+ const index = text ? this.pendingSteers.indexOf(text) : -1;
253
+ if (index === -1) return null;
254
+ this.pendingSteers.splice(index, 1);
255
+ return text;
256
+ }
257
+
258
+ onEvent(sink) {
259
+ this.onRaw = (event) => sink(event);
260
+ }
261
+
262
+ request(message, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS) {
263
+ const id = `fleet-${++this.seq}`;
264
+ const payload = { id, ...message };
265
+ return new Promise((resolve, reject) => {
266
+ if (!this.child || this.child.killed) {
267
+ reject(new Error("child is not running"));
268
+ return;
269
+ }
270
+ const timer = setTimeout(() => {
271
+ this.pending.delete(id);
272
+ reject(new Error(`timeout waiting for ${message.type}`));
273
+ }, timeoutMs);
274
+ this.pending.set(id, { resolve, reject, timer });
275
+ this.child.stdin.write(JSON.stringify(payload) + "\n", (error) => {
276
+ if (!error) return;
277
+ this.pending.delete(id);
278
+ clearTimeout(timer);
279
+ reject(error);
280
+ });
281
+ });
282
+ }
283
+
284
+ async prompt(text) {
285
+ this.settled = false;
286
+ return this.request({ type: "prompt", message: text });
287
+ }
288
+
289
+ async steer(text) {
290
+ const body = String(text);
291
+ this.pendingSteers.push(body);
292
+ if (this.pendingSteers.length > MAX_PENDING_STEERS) this.pendingSteers.shift();
293
+ let ack;
294
+ try {
295
+ ack = await this.request({ type: "steer", message: body });
296
+ } catch (error) {
297
+ this._forgetSteer(body);
298
+ throw error;
299
+ }
300
+ // A disposition other than `queued` means an input handler consumed the
301
+ // text: no message with this body will reach the conversation, so waiting
302
+ // for one would be waiting for a delivery that cannot happen.
303
+ const disposition = ack?.data?.disposition;
304
+ if (disposition && disposition !== "queued") this._forgetSteer(body);
305
+ return ack;
306
+ }
307
+
308
+ async state() {
309
+ return (await this.request({ type: "get_state" }, 20_000))?.data ?? {};
310
+ }
311
+
312
+ async messages() {
313
+ return (await this.request({ type: "get_messages" }, 20_000))?.data ?? {};
314
+ }
315
+
316
+ /** Orderly shutdown: close stdin, then make sure the process group is gone. */
317
+ async stop({ graceMs = 5000 } = {}) {
318
+ if (!this.child) return;
319
+ try {
320
+ this.child.stdin.end();
321
+ } catch (error) {
322
+ if (!/not running|EPIPE/.test(String(error))) throw error;
323
+ }
324
+ const raced = await Promise.race([
325
+ this.exit.then(() => true),
326
+ new Promise((resolveWait) => setTimeout(() => resolveWait(false), graceMs)),
327
+ ]);
328
+ if (!raced) this.killGroup("SIGKILL");
329
+ await this.exit;
330
+ }
331
+
332
+ killGroup(signal = "SIGTERM") {
333
+ if (!this.pgid) return false;
334
+ try {
335
+ process.kill(-this.pgid, signal);
336
+ return true;
337
+ } catch (error) {
338
+ if (error.code !== "ESRCH") throw error;
339
+ return false;
340
+ }
341
+ }
342
+
343
+ _failAll(error) {
344
+ for (const [id, entry] of this.pending) {
345
+ clearTimeout(entry.timer);
346
+ entry.reject(error);
347
+ this.pending.delete(id);
348
+ }
349
+ }
350
+ }
351
+
352
+ export function createRpcDriver(args) {
353
+ return new RpcDriver(args);
354
+ }
355
+
356
+ /** True when a process group still has members (used by the orphan fence). */
357
+ export function groupIsAlive(pgid) {
358
+ if (!pgid) return false;
359
+ try {
360
+ process.kill(-pgid, 0);
361
+ return true;
362
+ } catch (error) {
363
+ return error.code === "EPERM";
364
+ }
365
+ }
366
+
367
+ /** True when a single pid is alive; a zombie counts as gone for our purposes. */
368
+ export function pidIsAlive(pid) {
369
+ if (!pid) return false;
370
+ try {
371
+ process.kill(pid, 0);
372
+ return true;
373
+ } catch (error) {
374
+ return error.code === "EPERM";
375
+ }
376
+ }
@@ -0,0 +1,239 @@
1
+ /**
2
+ * A scripted node driver: the same driver contract as the RPC one, with the
3
+ * model replaced by a fixed step list.
4
+ *
5
+ * It exists so the crash drill can be deterministic and free. Its steps
6
+ * perform real effects on a real file, so a replayed step shows up in the
7
+ * world, not only in the journal. Two instruments then measure duplication -
8
+ * the file and the journal - and neither can be satisfied by editing the
9
+ * other.
10
+ *
11
+ * Steps, all executed as one bash call each:
12
+ * { op: "append", text } append one line to the world file
13
+ * { op: "sleep", ms } hold the turn open; the kill window
14
+ * { op: "park", question, defaultAnswer } end the turn with the ask sentinel
15
+ * { op: "done" } end the turn with the done sentinel
16
+ * { op: "text", text } end the turn with plain text
17
+ *
18
+ * A recovery prompt changes what the node does, which is the point: it names
19
+ * the effects the journal already recorded, and a node that reads its
20
+ * instructions skips them. An effect listed as unknown is never re-executed -
21
+ * the node checks the world for its mark and moves on. A plain prompt (the
22
+ * charter, or a naive replay) names nothing, so the whole list runs again.
23
+ *
24
+ * A steer is delivered the way pi delivers one: after the tool call in flight
25
+ * finishes and before the next request. Text still queued when the script has
26
+ * no further tool call is never delivered, so the `steer_delivered` event says
27
+ * the model was handed the message rather than that the request was made.
28
+ */
29
+
30
+ import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
31
+ import { dirname } from "node:path";
32
+
33
+ export const ASK_SENTINEL = "FLEET-ASK:";
34
+ export const DONE_SENTINEL = "FLEET-DONE";
35
+
36
+ const COMPLETED_LINE = /^- seq (\d+) \S+ completed/m;
37
+ const UNKNOWN_LINE = /^- seq (\d+) \S+ unknown/m;
38
+
39
+ /** Effects a prompt says the journal already recorded. */
40
+ export function planFromPrompt(promptText) {
41
+ const completed = new Set();
42
+ const unknown = new Set();
43
+ for (const line of String(promptText ?? "").split("\n")) {
44
+ const done = line.match(COMPLETED_LINE);
45
+ if (done) completed.add(Number(done[1]));
46
+ const unsure = line.match(UNKNOWN_LINE);
47
+ if (unsure) unknown.add(Number(unsure[1]));
48
+ }
49
+ return { completed, unknown };
50
+ }
51
+
52
+ export class ScriptedDriver {
53
+ constructor(args) {
54
+ this.kind = "scripted";
55
+ this.cfg = args;
56
+ this.steps = args.steps ?? [];
57
+ this.worldFile = args.worldFile;
58
+ this.sessionFile = args.sessionFile ?? null;
59
+ this.sessionId = args.sessionId;
60
+ this.pid = null;
61
+ this.pgid = null;
62
+ this.stopped = false;
63
+ this.seq = 0;
64
+ this.toolCount = 0;
65
+ this.requests = 0;
66
+ this.messageCount = 0;
67
+ this.pendingSteer = null;
68
+ this.inFlight = null;
69
+ this.finalText = "";
70
+ this.skipped = [];
71
+ this.plan = { completed: new Set(), unknown: new Set() };
72
+ }
73
+
74
+ onEvent(sink) {
75
+ this.onRaw = sink;
76
+ }
77
+
78
+ async start() {
79
+ if (this.sessionFile) {
80
+ mkdirSync(dirname(this.sessionFile), { recursive: true });
81
+ writeFileSync(this.sessionFile, "");
82
+ }
83
+ mkdirSync(dirname(this.worldFile), { recursive: true });
84
+ return { sessionId: this.sessionId, sessionFile: this.sessionFile };
85
+ }
86
+
87
+ _emit(event) {
88
+ this.onRaw?.(event);
89
+ }
90
+
91
+ _worldHas(text) {
92
+ try {
93
+ return readFileSync(this.worldFile, "utf8").split("\n").includes(text);
94
+ } catch (error) {
95
+ if (error.code === "ENOENT") return false;
96
+ throw error;
97
+ }
98
+ }
99
+
100
+ async prompt(text) {
101
+ this.stopped = false;
102
+ this.toolCount = 0;
103
+ this.plan = planFromPrompt(text);
104
+ const run = this._run();
105
+ this.inFlight = run;
106
+ try {
107
+ await run;
108
+ } finally {
109
+ this.inFlight = null;
110
+ }
111
+ return { ok: true };
112
+ }
113
+
114
+ /**
115
+ * Recorded effects are skipped; an unknown effect is skipped after the world
116
+ * is checked, because re-running a non-idempotent call whose outcome is
117
+ * unknown is exactly the failure the journal exists to prevent.
118
+ */
119
+ _skip(index, step) {
120
+ if (this.plan.completed.has(index)) {
121
+ this.skipped.push({ seq: index, reason: "journal recorded completed" });
122
+ return true;
123
+ }
124
+ if (this.plan.unknown.has(index)) {
125
+ if (step.op === "append") {
126
+ const applied = this._worldHas(step.text);
127
+ this.skipped.push({ seq: index, reason: applied ? "unknown but present in the world" : "unknown, not re-executed" });
128
+ return true;
129
+ }
130
+ this.skipped.push({ seq: index, reason: "unknown, not re-executed" });
131
+ return true;
132
+ }
133
+ return false;
134
+ }
135
+
136
+ async _run() {
137
+ for (const [index, step] of this.steps.entries()) {
138
+ if (this.stopped) return;
139
+ if (this._skip(index + 1, step)) continue;
140
+ this.requests += 1;
141
+ this._emit({
142
+ type: "model_request",
143
+ seq: this.requests,
144
+ messageCount: this.messageCount,
145
+ toolCount: this.toolCount,
146
+ });
147
+ if (step.op === "append" || step.op === "sleep") {
148
+ this.toolCount += 1;
149
+ const toolCallId = `scripted-${this.sessionId}-${index + 1}`;
150
+ this._emit({
151
+ type: "tool_start",
152
+ toolCallId,
153
+ toolName: "bash",
154
+ args: step.op === "append" ? { command: `printf '${step.text}\\n' >> world.log` } : { command: `sleep ${(step.ms ?? 0) / 1000}` },
155
+ });
156
+ if (step.op === "append") {
157
+ appendFileSync(this.worldFile, step.text + "\n");
158
+ } else {
159
+ await this._wait(step.ms ?? 0);
160
+ }
161
+ if (this.stopped) return;
162
+ this._emit({ type: "tool_end", toolCallId, toolName: "bash", result: { ok: true }, isError: false });
163
+ // pi hands a queued steering message to the model after the current
164
+ // tool call finishes and before the next request. This is that moment.
165
+ // A steer that arrives after the last one is never delivered, which is
166
+ // the case no driver may report as a delivery.
167
+ this._deliverSteer(index + 1);
168
+ continue;
169
+ }
170
+ if (step.op === "park") {
171
+ const priority = step.priority == null ? "" : ` | priority: ${step.priority}`;
172
+ this.finalText = `${ASK_SENTINEL} ${step.question} | default: ${step.defaultAnswer ?? "keep the current course"}${priority}`;
173
+ this._emit({ type: "final_text", text: this.finalText });
174
+ return;
175
+ }
176
+ if (step.op === "done") {
177
+ this.finalText = DONE_SENTINEL;
178
+ this._emit({ type: "final_text", text: this.finalText });
179
+ return;
180
+ }
181
+ if (step.op === "text") {
182
+ this.finalText = step.text;
183
+ this._emit({ type: "final_text", text: this.finalText });
184
+ return;
185
+ }
186
+ throw new Error(`unknown scripted step: ${JSON.stringify(step)}`);
187
+ }
188
+ this.finalText = DONE_SENTINEL;
189
+ this._emit({ type: "final_text", text: this.finalText });
190
+ }
191
+
192
+ _wait(ms) {
193
+ return new Promise((resolveWait) => {
194
+ const timer = setTimeout(resolveWait, ms);
195
+ this._cancelWait = () => {
196
+ clearTimeout(timer);
197
+ resolveWait();
198
+ };
199
+ });
200
+ }
201
+
202
+ _deliverSteer(afterEffectSeq) {
203
+ if (!this.pendingSteer) return;
204
+ const text = this.pendingSteer;
205
+ this.pendingSteer = null;
206
+ this._emit({ type: "message_end", role: "user", message: { role: "user", content: text } });
207
+ this._emit({ type: "steer_delivered", afterEffectSeq, text });
208
+ this.finalText = `STEERED: ${text}`;
209
+ }
210
+
211
+ async steer(text) {
212
+ this.pendingSteer = text;
213
+ return { disposition: "queued" };
214
+ }
215
+
216
+ async state() {
217
+ return { sessionId: this.sessionId, sessionFile: this.sessionFile, messageCount: this.messageCount };
218
+ }
219
+
220
+ async messages() {
221
+ return { messages: [] };
222
+ }
223
+
224
+ async stop() {
225
+ this.stopped = true;
226
+ this._cancelWait?.();
227
+ if (this.inFlight) await this.inFlight.catch(() => {});
228
+ }
229
+
230
+ killGroup() {
231
+ this.stopped = true;
232
+ this._cancelWait?.();
233
+ return false;
234
+ }
235
+ }
236
+
237
+ export function createScriptedDriver(args) {
238
+ return new ScriptedDriver(args);
239
+ }