kenning-pi 0.0.0 → 0.1.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/src/spawn.ts ADDED
@@ -0,0 +1,431 @@
1
+ import {execFile, spawn as startProcess} from 'node:child_process';
2
+ import {randomUUID} from 'node:crypto';
3
+ import fs from 'node:fs';
4
+ import os from 'node:os';
5
+ import path from 'node:path';
6
+ import {
7
+ currentHost,
8
+ defaultStateDir,
9
+ KenningError,
10
+ type Kenning,
11
+ type Ownership,
12
+ type Presence,
13
+ type SpawnVia,
14
+ } from 'kenning';
15
+
16
+ /**
17
+ * The environment variable that tells a terminal child which spawn it is (D28).
18
+ * The child binds itself to the spawn at its own `session_start`, so its first
19
+ * prompt can be queued before `before_agent_start` and no session path has to
20
+ * be guessed. It can only bind a spawn that is not bound yet, to a session
21
+ * nobody owns, and binding only ever yields an `agent` message, so it cannot
22
+ * produce human input. A process that learns an unbound spawn id can bind an
23
+ * unowned session to that spawn's owner, which then owns and may stop it:
24
+ * within ADR 0003's model (it takes running pi with a forged environment).
25
+ */
26
+ export const SPAWN_ENV = 'KENNING_SPAWN';
27
+
28
+ /**
29
+ * How long session_spawn waits for a terminal child to bind itself. Measured:
30
+ * a headless `pi -p` child on the test machine binds 0.20 to 0.25 s after it is
31
+ * started (packages/kenning-pi/test/flows.test.ts logs it); a real pi with
32
+ * user packages loads more, so 30 s leaves room without hanging a turn.
33
+ */
34
+ const BIND_TIMEOUT_MS = 30_000;
35
+
36
+ /** A headless wake is leased this long: a child that never comes up is retried after it. */
37
+ export const WAKE_LEASE_MS = 60_000;
38
+
39
+ /**
40
+ * Once a woken child is up, the next wake waits at least this long after its
41
+ * start, unless it exits having read everything (D29). Without it a child that
42
+ * exits without reading its messages (a crash, a failing model) is restarted
43
+ * in a tight loop: the first version of this code did that in a test, until
44
+ * the test timed out.
45
+ */
46
+ export const WAKE_GAP_MS = 5_000;
47
+
48
+ export interface SpawnParams {
49
+ folder?: string;
50
+ prompt: string;
51
+ role?: string;
52
+ fork?: {sessionFile: string; entryId?: string};
53
+ worktree?: {repo?: string; branch: string};
54
+ }
55
+
56
+ export interface SpawnOutcome {
57
+ ownership: Ownership;
58
+ presence: Presence | null;
59
+ note: string | null;
60
+ }
61
+
62
+ export interface ProcessPlan {
63
+ kind: 'zellij' | 'headless';
64
+ command: string;
65
+ args: string[];
66
+ cwd: string;
67
+ env: Record<string, string>;
68
+ }
69
+
70
+ /**
71
+ * The pi a terminal child runs: `KENNING_SPAWN_COMMAND`, a JSON array such as
72
+ * `["pi","--model","sonnet"]`, else `pi`. kenning appends the session and
73
+ * prompt arguments. The tests use it to give children the scripted model.
74
+ */
75
+ export function piCommand(env: NodeJS.ProcessEnv): string[] {
76
+ const raw = env.KENNING_SPAWN_COMMAND;
77
+ if (!raw) return ['pi'];
78
+ let cmd: unknown;
79
+ try {
80
+ cmd = JSON.parse(raw);
81
+ } catch {}
82
+ if (
83
+ !Array.isArray(cmd) ||
84
+ !cmd.length ||
85
+ !cmd.every((x) => typeof x === 'string')
86
+ )
87
+ throw new KenningError(
88
+ 'KENNING_SPAWN_COMMAND must be a JSON array of strings, e.g. ["pi"]',
89
+ 'bad-command',
90
+ );
91
+ return cmd as string[];
92
+ }
93
+
94
+ const kickoff = (ownerLabel: string) =>
95
+ `[kenning] ${ownerLabel} started this session and owns it; its instructions follow as a kenning message (origin agent). This text is not from the human.`;
96
+
97
+ const wakeKickoff = () =>
98
+ '[kenning] New kenning messages woke this session; they follow. This text is not from the human.';
99
+
100
+ /**
101
+ * The terminal default (D19, D28): a zellij pane when $ZELLIJ is set, else a
102
+ * detached headless `pi -p`. A pane runs an interactive pi with NO prompt (an
103
+ * interactive prompt would be recorded as the human's words); kenning wakes it
104
+ * with the owner's message once it is up. `pi -p` needs a prompt, so it gets a
105
+ * fixed kickoff line that says it is not the human, and the owner's message
106
+ * joins that run at `before_agent_start`.
107
+ */
108
+ export function planTerminalSpawn(input: {
109
+ env: NodeJS.ProcessEnv;
110
+ folder: string;
111
+ spawnId: string;
112
+ sessionId: string;
113
+ ownerLabel: string;
114
+ title: string;
115
+ fork?: {sessionFile: string};
116
+ /** A fork at an entry, already written by forkAt: start from this file. */
117
+ forkFile?: string;
118
+ }): ProcessPlan {
119
+ const pi = piCommand(input.env);
120
+ const session = input.forkFile
121
+ ? ['--session', input.forkFile]
122
+ : input.fork
123
+ ? ['--fork', input.fork.sessionFile, '--session-id', input.sessionId]
124
+ : ['--session-id', input.sessionId];
125
+ if (input.env.ZELLIJ)
126
+ return {
127
+ kind: 'zellij',
128
+ command: 'zellij',
129
+ args: [
130
+ 'run',
131
+ '--name',
132
+ input.title,
133
+ '--cwd',
134
+ input.folder,
135
+ '--',
136
+ 'env',
137
+ `${SPAWN_ENV}=${input.spawnId}`,
138
+ ...pi,
139
+ ...session,
140
+ ],
141
+ cwd: input.folder,
142
+ env: {},
143
+ };
144
+ return {
145
+ kind: 'headless',
146
+ command: pi[0],
147
+ args: [...pi.slice(1), ...session, '-p', kickoff(input.ownerLabel)],
148
+ cwd: input.folder,
149
+ env: {[SPAWN_ENV]: input.spawnId},
150
+ };
151
+ }
152
+
153
+ /** D29: wake a headless child that is not running: `pi --session <path> -p`. */
154
+ export function planWake(input: {
155
+ env: NodeJS.ProcessEnv;
156
+ sessionFile: string;
157
+ folder: string;
158
+ }): ProcessPlan {
159
+ const pi = piCommand(input.env);
160
+ return {
161
+ kind: 'headless',
162
+ command: pi[0],
163
+ args: [...pi.slice(1), '--session', input.sessionFile, '-p', wakeKickoff()],
164
+ cwd: input.folder,
165
+ env: {},
166
+ };
167
+ }
168
+
169
+ /**
170
+ * Start a plan in its own process group (detached, unref'd), so the spawner's
171
+ * exit or Ctrl-C never takes it down and it can be killed as a group. A
172
+ * headless child's output goes to `<state dir>/spawn-logs/<id>.log`.
173
+ */
174
+ export function startDetached(
175
+ plan: ProcessPlan,
176
+ logName: string,
177
+ ): Promise<number> {
178
+ const env: NodeJS.ProcessEnv = {...process.env, ...plan.env};
179
+ // The spawner's own role and spawn must not pass to the child.
180
+ delete env.KENNING_ROLE;
181
+ if (!plan.env[SPAWN_ENV]) delete env[SPAWN_ENV];
182
+ let out: number | 'ignore' = 'ignore';
183
+ if (plan.kind === 'headless') {
184
+ const dir = path.join(defaultStateDir(), 'spawn-logs');
185
+ fs.mkdirSync(dir, {recursive: true});
186
+ out = fs.openSync(path.join(dir, `${logName}.log`), 'a');
187
+ }
188
+ return new Promise((resolve, reject) => {
189
+ const child = startProcess(plan.command, plan.args, {
190
+ cwd: plan.cwd,
191
+ env,
192
+ detached: true,
193
+ stdio: ['ignore', out, out],
194
+ });
195
+ if (typeof out === 'number') fs.closeSync(out);
196
+ child.once('error', (e) =>
197
+ reject(
198
+ new KenningError(
199
+ `could not start ${plan.command}: ${e.message}`,
200
+ 'spawn-failed',
201
+ ),
202
+ ),
203
+ );
204
+ child.once('spawn', () => {
205
+ child.unref();
206
+ resolve(child.pid!);
207
+ });
208
+ });
209
+ }
210
+
211
+ function git(cwd: string, args: string[]): Promise<string> {
212
+ return new Promise((resolve, reject) =>
213
+ execFile(
214
+ 'git',
215
+ ['-C', cwd, ...args],
216
+ {timeout: 30_000, encoding: 'utf8'},
217
+ (err, stdout, stderr) =>
218
+ err
219
+ ? reject(
220
+ new KenningError(
221
+ `git ${args.join(' ')}: ${(stderr || err.message).trim()}`,
222
+ 'git',
223
+ ),
224
+ )
225
+ : resolve(stdout),
226
+ ),
227
+ );
228
+ }
229
+
230
+ /**
231
+ * D32: a worktree lives at `~/dev/worktrees/<repo>/<branch>` (never beside the
232
+ * repo; `KENNING_WORKTREES_DIR` overrides the root), made with
233
+ * `git worktree add <path> <branch>`. A branch that exists neither locally nor
234
+ * as a remote branch git can track is created from HEAD (`-b`). An existing
235
+ * worktree of that branch is reused.
236
+ */
237
+ export async function ensureWorktree(
238
+ repo: string,
239
+ branch: string,
240
+ env: NodeJS.ProcessEnv,
241
+ ): Promise<string> {
242
+ await git(repo, ['check-ref-format', '--branch', branch]);
243
+ const top = (await git(repo, ['rev-parse', '--show-toplevel'])).trim();
244
+ const root =
245
+ env.KENNING_WORKTREES_DIR || path.join(os.homedir(), 'dev', 'worktrees');
246
+ const dest = path.join(root, path.basename(top), branch);
247
+ if (fs.existsSync(dest)) {
248
+ const head = (
249
+ await git(dest, ['rev-parse', '--abbrev-ref', 'HEAD']).catch(() => '')
250
+ ).trim();
251
+ if (head !== branch)
252
+ throw new KenningError(
253
+ `${dest} exists but is not a worktree of ${branch}`,
254
+ 'worktree',
255
+ );
256
+ return dest;
257
+ }
258
+ fs.mkdirSync(path.dirname(dest), {recursive: true});
259
+ try {
260
+ await git(top, ['worktree', 'add', dest, branch]);
261
+ } catch (e) {
262
+ const local = await git(top, [
263
+ 'show-ref',
264
+ '--verify',
265
+ `refs/heads/${branch}`,
266
+ ]).then(
267
+ () => true,
268
+ () => false,
269
+ );
270
+ if (local) throw e;
271
+ await git(top, ['worktree', 'add', '-b', branch, dest]);
272
+ }
273
+ return dest;
274
+ }
275
+
276
+ /**
277
+ * D34: a fork at an entry. pi's `--fork` copies a whole transcript, so the
278
+ * branch up to `entryId` is written with pi's own SessionManager (a new header
279
+ * whose parentSession is the source, cwd the new folder) and the child starts
280
+ * on that file.
281
+ */
282
+ export async function forkAt(
283
+ source: string,
284
+ entryId: string,
285
+ folder: string,
286
+ ): Promise<{file: string; sessionId: string}> {
287
+ const {SessionManager} = await import('@earendil-works/pi-coding-agent');
288
+ const dir = SessionManager.create(folder).getSessionDir();
289
+ const sm = SessionManager.open(source, dir, folder);
290
+ if (!sm.getEntry(entryId))
291
+ throw new KenningError(`no entry ${entryId} in ${source}`, 'not-found');
292
+ const file = sm.createBranchedSession(entryId)!;
293
+ return {file, sessionId: sm.getSessionId()};
294
+ }
295
+
296
+ const firstLine = (s: string) => s.trim().split('\n')[0].trim();
297
+
298
+ const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
299
+
300
+ async function until<T>(
301
+ read: () => T | null | undefined,
302
+ ms: number,
303
+ signal?: AbortSignal,
304
+ ): Promise<T | null> {
305
+ const end = Date.now() + ms;
306
+ for (;;) {
307
+ const v = read();
308
+ if (v) return v;
309
+ if (Date.now() > end || signal?.aborted) return null;
310
+ await sleep(50);
311
+ }
312
+ }
313
+
314
+ /**
315
+ * session_spawn (D23, D28): record the spawn, make the worktree, then ask the
316
+ * registered host, else start the terminal default, and return once the new
317
+ * session exists and is bound to its owner. The first prompt is never sent as
318
+ * user input: binding queues it as a `spawn` message from the owner.
319
+ */
320
+ export async function spawnSession(
321
+ k: Kenning,
322
+ owner: string,
323
+ params: SpawnParams,
324
+ opts: {cwd: string; env: NodeJS.ProcessEnv; signal?: AbortSignal},
325
+ ): Promise<SpawnOutcome> {
326
+ if (!params.prompt?.trim())
327
+ throw new KenningError('a spawn needs a prompt', 'empty');
328
+ let folder = path.resolve(opts.cwd, params.folder ?? '.');
329
+ let worktree: {repo: string; branch: string; path: string} | undefined;
330
+ if (params.worktree) {
331
+ const repo = path.resolve(opts.cwd, params.worktree.repo ?? folder);
332
+ const wt = await ensureWorktree(repo, params.worktree.branch, opts.env);
333
+ worktree = {repo, branch: params.worktree.branch, path: wt};
334
+ folder = wt;
335
+ }
336
+ if (!fs.statSync(folder, {throwIfNoEntry: false})?.isDirectory())
337
+ throw new KenningError(`no folder ${folder}`, 'not-found');
338
+ const fork = params.fork
339
+ ? {
340
+ sessionFile: path.resolve(opts.cwd, params.fork.sessionFile),
341
+ entryId: params.fork.entryId,
342
+ }
343
+ : undefined;
344
+ if (fork && !fs.existsSync(fork.sessionFile))
345
+ throw new KenningError(`no transcript ${fork.sessionFile}`, 'not-found');
346
+ const title = (params.role || firstLine(params.prompt)).slice(0, 80);
347
+ const host = currentHost();
348
+ const base = {
349
+ owner,
350
+ folder,
351
+ prompt: params.prompt,
352
+ role: params.role ?? null,
353
+ };
354
+
355
+ if (host?.spawn) {
356
+ const sp = k.beginSpawn({
357
+ ...base,
358
+ via: 'host',
359
+ detail: {fork, worktree},
360
+ });
361
+ const res = await host.spawn({
362
+ spawnId: sp.id,
363
+ owner,
364
+ folder,
365
+ title,
366
+ role: params.role,
367
+ fork,
368
+ worktree,
369
+ });
370
+ k.bindSpawn(sp.id, res.sessionFile);
371
+ // The host's session may already be up; claim its role for it. It
372
+ // re-claims it from the ownership record on every later start.
373
+ let note: string | null = null;
374
+ if (params.role) {
375
+ const r = k.claimRole(res.sessionFile, params.role);
376
+ if (!r.ok) note = `role ${params.role} is held by ${r.holder}; not taken`;
377
+ }
378
+ const presence = await until(
379
+ () => {
380
+ const p = k.presence(res.sessionFile);
381
+ return p?.live ? p : null;
382
+ },
383
+ 5_000,
384
+ opts.signal,
385
+ );
386
+ return {ownership: k.ownership(res.sessionFile)!, presence, note};
387
+ }
388
+
389
+ let sessionId: string = randomUUID();
390
+ let forkFile: string | undefined;
391
+ if (fork?.entryId) {
392
+ const f = await forkAt(fork.sessionFile, fork.entryId, folder);
393
+ forkFile = f.file;
394
+ sessionId = f.sessionId;
395
+ }
396
+ const via: SpawnVia = opts.env.ZELLIJ ? 'zellij' : 'headless';
397
+ const sp = k.beginSpawn({
398
+ ...base,
399
+ via,
400
+ detail: {sessionId, fork, worktree},
401
+ });
402
+ const plan = planTerminalSpawn({
403
+ env: opts.env,
404
+ folder,
405
+ spawnId: sp.id,
406
+ sessionId,
407
+ ownerLabel: k.labelOf(owner),
408
+ title,
409
+ fork,
410
+ forkFile,
411
+ });
412
+ const started = Date.now();
413
+ const pid = await startDetached(plan, sp.id);
414
+ const bound = await until(
415
+ () => k.spawnRecord(sp.id)?.session,
416
+ BIND_TIMEOUT_MS,
417
+ opts.signal,
418
+ );
419
+ if (!bound)
420
+ return {
421
+ ownership: k.spawnRecord(sp.id)!,
422
+ presence: null,
423
+ note: `started (${plan.kind}, pid ${pid}) but it did not come up within ${BIND_TIMEOUT_MS / 1000} s; it binds itself when its pi starts. Check ${path.join(defaultStateDir(), 'spawn-logs', sp.id + '.log')}.`,
424
+ };
425
+ const presence = k.presence(bound);
426
+ return {
427
+ ownership: k.ownership(bound)!,
428
+ presence: presence?.live ? presence : null,
429
+ note: `${plan.kind}, pid ${pid}, up in ${Date.now() - started} ms`,
430
+ };
431
+ }