pi-keeper 0.0.0-stage → 0.1.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.
Files changed (52) hide show
  1. package/CHANGELOG.md +141 -0
  2. package/LICENSE +201 -0
  3. package/NOTICE +36 -0
  4. package/README.md +71 -2
  5. package/extensions/ask-heartbeat.ts +55 -0
  6. package/extensions/ask-mailbox.ts +515 -0
  7. package/extensions/ask-server.ts +461 -0
  8. package/extensions/attention.ts +24 -0
  9. package/extensions/cc-extensions-compat.ts +103 -0
  10. package/extensions/child-auto.ts +32 -0
  11. package/extensions/child-cwd.ts +78 -0
  12. package/extensions/child-default.ts +32 -0
  13. package/extensions/child-lane.ts +134 -0
  14. package/extensions/child-plan.ts +12 -0
  15. package/extensions/config.ts +359 -0
  16. package/extensions/dialog-lock.ts +70 -0
  17. package/extensions/dialog.ts +420 -0
  18. package/extensions/index.ts +3639 -0
  19. package/extensions/modes.ts +1382 -0
  20. package/extensions/options.ts +118 -0
  21. package/extensions/perf.ts +54 -0
  22. package/extensions/plan-approval.ts +345 -0
  23. package/extensions/preview.ts +234 -0
  24. package/extensions/project-rules.ts +634 -0
  25. package/extensions/prompt-blocks.ts +163 -0
  26. package/extensions/remote-relay.ts +168 -0
  27. package/extensions/rtk-rewrite.ts +60 -0
  28. package/extensions/rulebook.ts +362 -0
  29. package/extensions/rules-line.ts +71 -0
  30. package/extensions/rules-view.ts +187 -0
  31. package/extensions/rules.ts +579 -0
  32. package/extensions/secure-file.ts +157 -0
  33. package/extensions/session-grant-store.ts +157 -0
  34. package/extensions/session-grants.ts +160 -0
  35. package/extensions/settings-panel.ts +252 -0
  36. package/extensions/shell-highlight-bridge.ts +50 -0
  37. package/extensions/subagents-bridge.ts +129 -0
  38. package/extensions/telemetry.ts +310 -0
  39. package/extensions/thinking.ts +62 -0
  40. package/extensions/title.ts +80 -0
  41. package/extensions/ui-relay.ts +154 -0
  42. package/extensions/utils.ts +4984 -0
  43. package/package.json +67 -5
  44. package/prompt-templates/new-rule.md +30 -0
  45. package/prompts/auto-mode.md +16 -0
  46. package/prompts/child-auto.md +26 -0
  47. package/prompts/child-default.md +21 -0
  48. package/prompts/child-plan.md +16 -0
  49. package/prompts/contract.md +29 -0
  50. package/prompts/default-mode.md +8 -0
  51. package/prompts/plan-mode.md +45 -0
  52. package/prompts/rule-warning.md +8 -0
@@ -0,0 +1,515 @@
1
+ /**
2
+ * File mailbox for permission asks from a background subagent. A background
3
+ * child runs in a detached runner process with no UI, so it cannot open a
4
+ * dialog. Instead it files a request carrying the raw tool call; the parent
5
+ * session polls, decides with its own rules and grants (re-deciding, never
6
+ * trusting the child), asks the user if needed, and writes back a reply with
7
+ * only allow / deny / cancelled. The child polls for the reply and can file a
8
+ * cancel (its abort signal fired). The child never sends grants.
9
+ *
10
+ * <agent dir>/pi-keeper/asks/<sha256(parent session id)>/
11
+ * requests/<id>.json child writes; parent claims by renaming to
12
+ * requests/<id>.json.taken (rename is atomic: exactly one taker wins)
13
+ * replies/<id>.json parent writes
14
+ * cancels/<id>.json child writes
15
+ *
16
+ * Polling only, no fs.watch. Directories are 0700, files 0600, written by
17
+ * tmp + rename. Everything read is hardened (secure-file.ts): lstat, regular
18
+ * file only (no symlinks), our uid, at most 64 KB, then strict validation of
19
+ * plain JSON: unknown or extra fields are rejected.
20
+ *
21
+ * receivedAt: the parent never trusts a child's clock or file mtimes. The
22
+ * caller holds a `Taken` map (id -> parent-side receivedAt in ms), filled by
23
+ * takeRequests and read by sweep. In-memory suits this: the parent process
24
+ * is the only one that takes, and if it restarts the map is gone together
25
+ * with the session, so sweep restarts the TTL clock for an unknown id.
26
+ *
27
+ * Reply authenticity. Each request carries a random nonce; the parent echoes
28
+ * it in the reply and the child accepts a reply only when the nonce matches
29
+ * AND `requests/<id>.json.taken` exists (the parent claimed the request). The
30
+ * child also deletes any stale reply before filing. That defeats blind
31
+ * pre-creation and stale reuse. It is not a defence against an active
32
+ * same-uid forger: that boundary is that `<agentDir>/**` is a protected path
33
+ * for the child's tools (isProtectedPath in utils.ts), so a child's tool calls
34
+ * cannot write here. The parent in turn trusts nothing in a request beyond
35
+ * the tool call, which it re-judges with its own rules and grants.
36
+ *
37
+ * Work per poll is bounded: takeRequests and sweep each handle at most
38
+ * MAX_PER_PASS files.
39
+ *
40
+ * Free of pi types so it is testable (like config.ts).
41
+ */
42
+
43
+ import { createHash, randomBytes, randomUUID } from "node:crypto";
44
+ import { lstatSync, readdirSync, renameSync, rmSync } from "node:fs";
45
+ import { dirname, join } from "node:path";
46
+ import { currentUid, ensureSecureDir, isPidAlive, readJsonFile, writeFileAtomic } from "./secure-file.ts";
47
+ import { countWork } from "./perf.ts";
48
+
49
+ const VERSION = 1;
50
+ /** A file larger than this is not one we wrote. */
51
+ export const MAX_BYTES = 64 * 1024;
52
+ /** Files handled per takeRequests / sweep call. */
53
+ export const MAX_PER_PASS = 64;
54
+ /** A leaked tmp file older than this is swept. */
55
+ const TMP_TTL_MS = 60_000;
56
+ const MAX_DEPTH = 16;
57
+ const MAX_KEYS = 2000;
58
+ const BAD_KEYS: readonly string[] = ["__proto__", "constructor", "prototype"];
59
+
60
+ export type ChildMode = "default" | "auto" | "plan";
61
+ export type ReplyDecision = "allow" | "deny" | "cancelled";
62
+ export type ReplyReason = "parent-session-ended" | "asks-turned-off" | "timeout" | "user" | "rules" | "no-ui";
63
+
64
+ const MODES: readonly string[] = ["default", "auto", "plan"];
65
+ const DECISIONS: readonly string[] = ["allow", "deny", "cancelled"];
66
+ const REASONS: readonly string[] = ["parent-session-ended", "asks-turned-off", "timeout", "user", "rules", "no-ui"];
67
+
68
+ const ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
69
+ const TOOL_NAME = /^[A-Za-z0-9_.:-]{1,64}$/;
70
+ // eslint-disable-next-line no-control-regex
71
+ // control characters plus line/paragraph separators, zero-width and bidi marks/overrides/isolates
72
+ const CONTROL = /[\u0000-\u001f\u007f-\u009f\u2028\u2029\u200b-\u200f\u202a-\u202e\u2066-\u2069\ufeff]/;
73
+ const NONCE = /^[0-9a-f]{32}$/;
74
+ const MAX_LABEL = 80;
75
+ const MAX_CWD = 4096;
76
+
77
+ export interface AskRequest {
78
+ v: 1;
79
+ id: string;
80
+ /** 16 random bytes, hex; the parent echoes it in the reply. */
81
+ nonce: string;
82
+ childPid: number;
83
+ childLabel: string;
84
+ childMode: ChildMode;
85
+ cwd: string;
86
+ call: { toolName: string; input: Record<string, unknown> };
87
+ }
88
+
89
+ export interface AskReply {
90
+ v: 1;
91
+ id: string;
92
+ nonce: string;
93
+ decision: ReplyDecision;
94
+ reason?: ReplyReason;
95
+ }
96
+
97
+ export interface AskCancel {
98
+ v: 1;
99
+ id: string;
100
+ }
101
+
102
+ /** What the parent remembers about a claimed request. */
103
+ export interface TakenEntry {
104
+ /** The parent's own clock when it claimed the request; the TTL runs from here. */
105
+ receivedAt: number;
106
+ /** The request's nonce, echoed in the reply. */
107
+ nonce: string;
108
+ /** A reply was written (or the request was dropped); no longer pending. */
109
+ answered: boolean;
110
+ }
111
+
112
+ /** Parent-side: id -> entry. Doubles as the exactly-once seen-set and the pending set. */
113
+ export type Taken = Map<string, TakenEntry>;
114
+
115
+ /** Child: a fresh ask id. */
116
+ export function newAskId(): string {
117
+ return randomUUID();
118
+ }
119
+
120
+ /** Child: a fresh nonce for a request. */
121
+ export function newNonce(): string {
122
+ return randomBytes(16).toString("hex");
123
+ }
124
+
125
+ /** Parent: ids claimed but not yet answered (for "deny all" on a session switch). */
126
+ export function pendingIds(taken: Taken): string[] {
127
+ return [...taken].filter(([, entry]) => !entry.answered).map(([id]) => id);
128
+ }
129
+
130
+ export interface MailboxOptions {
131
+ /** Expected owner uid; defaults to the current uid. Injectable for tests. */
132
+ uid?: number;
133
+ /**
134
+ * The caller already ran `ensureAskDir` for this pass. A poll tick checks the mailbox
135
+ * once and then calls `takeRequests`, `readCancels` and `sweep`; without this each of
136
+ * the three would re-walk the same directory chain (four levels per subdir, nine in all).
137
+ */
138
+ dirReady?: boolean;
139
+ }
140
+
141
+ /** Skip the directory check when the caller says it already did it in this pass. */
142
+ function ready(dir: string, options: MailboxOptions): void {
143
+ if (options.dirReady === true) return;
144
+ ensureAskDir(dir, options);
145
+ }
146
+
147
+ export function askDirFor(agentDir: string, parentSessionId: string): string {
148
+ return join(agentDir, "pi-keeper", "asks", createHash("sha256").update(parentSessionId).digest("hex"));
149
+ }
150
+
151
+ // --- validation ---------------------------------------------------------
152
+
153
+ function isRecord(value: unknown): value is Record<string, unknown> {
154
+ return typeof value === "object" && value !== null && !Array.isArray(value);
155
+ }
156
+
157
+ function onlyKeys(value: Record<string, unknown>, allowed: readonly string[]): boolean {
158
+ return Object.keys(value).every((key) => allowed.includes(key));
159
+ }
160
+
161
+ /** Plain JSON only, no prototype-poisoning keys, bounded depth and key count. */
162
+ function isPlainJson(value: unknown, depth: number, budget: { keys: number }): boolean {
163
+ if (value === null || typeof value === "string" || typeof value === "boolean") return true;
164
+ if (typeof value === "number") return Number.isFinite(value);
165
+ if (depth >= MAX_DEPTH) return false;
166
+ if (Array.isArray(value)) return value.every((item) => isPlainJson(item, depth + 1, budget));
167
+ if (!isRecord(value)) return false;
168
+ for (const key of Object.keys(value)) {
169
+ if (BAD_KEYS.includes(key) || ++budget.keys > MAX_KEYS) return false;
170
+ if (!isPlainJson(value[key], depth + 1, budget)) return false;
171
+ }
172
+ return true;
173
+ }
174
+
175
+ export function isValidId(id: unknown): id is string {
176
+ return typeof id === "string" && ID.test(id);
177
+ }
178
+
179
+ /** The request, or undefined when it is not exactly a v1 request. */
180
+ export function parseRequest(value: unknown): AskRequest | undefined {
181
+ if (!isRecord(value) || !onlyKeys(value, ["v", "id", "nonce", "childPid", "childLabel", "childMode", "cwd", "call"])) return undefined;
182
+ if (value.v !== VERSION || !isValidId(value.id)) return undefined;
183
+ if (typeof value.nonce !== "string" || !NONCE.test(value.nonce)) return undefined;
184
+ const { childPid, childLabel, childMode, cwd, call } = value;
185
+ if (typeof childPid !== "number" || !Number.isSafeInteger(childPid) || childPid <= 0) return undefined;
186
+ if (typeof childLabel !== "string" || childLabel.length > MAX_LABEL || CONTROL.test(childLabel)) return undefined;
187
+ if (typeof childMode !== "string" || !MODES.includes(childMode)) return undefined;
188
+ if (typeof cwd !== "string" || !cwd.startsWith("/") || cwd.length > MAX_CWD || CONTROL.test(cwd)) return undefined;
189
+ if (!isRecord(call) || !onlyKeys(call, ["toolName", "input"])) return undefined;
190
+ if (typeof call.toolName !== "string" || !TOOL_NAME.test(call.toolName) || !isRecord(call.input) || !isPlainJson(call.input, 0, { keys: 0 })) return undefined;
191
+ return { v: 1, id: value.id, nonce: value.nonce, childPid, childLabel, childMode: childMode as ChildMode, cwd, call: { toolName: call.toolName, input: call.input } };
192
+ }
193
+
194
+ export function parseReply(value: unknown): AskReply | undefined {
195
+ if (!isRecord(value) || !onlyKeys(value, ["v", "id", "nonce", "decision", "reason"])) return undefined;
196
+ if (value.v !== VERSION || !isValidId(value.id)) return undefined;
197
+ if (typeof value.nonce !== "string" || !NONCE.test(value.nonce)) return undefined;
198
+ if (typeof value.decision !== "string" || !DECISIONS.includes(value.decision)) return undefined;
199
+ if (value.reason !== undefined && (typeof value.reason !== "string" || !REASONS.includes(value.reason))) return undefined;
200
+ return {
201
+ v: 1,
202
+ id: value.id,
203
+ nonce: value.nonce,
204
+ decision: value.decision as ReplyDecision,
205
+ ...(value.reason !== undefined ? { reason: value.reason as ReplyReason } : {}),
206
+ };
207
+ }
208
+
209
+ export function parseCancel(value: unknown): AskCancel | undefined {
210
+ if (!isRecord(value) || !onlyKeys(value, ["v", "id"]) || value.v !== VERSION || !isValidId(value.id)) return undefined;
211
+ return { v: 1, id: value.id };
212
+ }
213
+
214
+ // --- paths --------------------------------------------------------------
215
+
216
+ const requestFile = (dir: string, id: string) => join(dir, "requests", `${id}.json`);
217
+ const takenFile = (dir: string, id: string) => join(dir, "requests", `${id}.json.taken`);
218
+ const replyFile = (dir: string, id: string) => join(dir, "replies", `${id}.json`);
219
+ const cancelFile = (dir: string, id: string) => join(dir, "cancels", `${id}.json`);
220
+
221
+ /** Create the mailbox (0700) and refuse one that is a symlink or not ours. Throws. */
222
+ export function ensureAskDir(dir: string, options: MailboxOptions = {}): void {
223
+ const uid = options.uid ?? currentUid();
224
+ // check every component below the agent dir (<agent>/pi-keeper/asks/<hash>/<sub>)
225
+ countWork("ensureAskDir");
226
+ const agentDir = dirname(dirname(dirname(dir)));
227
+ for (const sub of ["requests", "replies", "cancels"]) ensureSecureDir(join(dir, sub), uid, agentDir);
228
+ }
229
+
230
+ function need(id: string): void {
231
+ if (!isValidId(id)) throw new Error("invalid ask id");
232
+ }
233
+
234
+ function readValidated<T>(file: string, parse: (value: unknown) => T | undefined, options: MailboxOptions): T {
235
+ const parsed = parse(readJsonFile(file, MAX_BYTES, options.uid));
236
+ if (parsed === undefined) throw new Error("does not match the v1 schema");
237
+ return parsed;
238
+ }
239
+
240
+ function remove(file: string): void {
241
+ countWork("fs");
242
+ rmSync(file, { force: true, recursive: true });
243
+ }
244
+
245
+ function isFile(file: string): boolean {
246
+ try {
247
+ countWork("fs");
248
+ return lstatSync(file).isFile();
249
+ } catch {
250
+ return false;
251
+ }
252
+ }
253
+
254
+ // --- child side ---------------------------------------------------------
255
+
256
+ /** Thrown by writeRequest for a request the parent would drop unread: over MAX_BYTES, or over the key budget. */
257
+ export class RequestTooLargeError extends Error {
258
+ readonly code = "request-too-large";
259
+
260
+ constructor() {
261
+ super("request too large to send to the parent");
262
+ this.name = "RequestTooLargeError";
263
+ }
264
+ }
265
+
266
+ /** Child: file a request. Validated first; throws on an invalid one or an unusable dir. */
267
+ export function writeRequest(dir: string, request: AskRequest, options: MailboxOptions = {}): void {
268
+ const text = JSON.stringify(request);
269
+ // the parent's reader counts bytes, not UTF-16 units: a request of CJK text is three bytes a character
270
+ if (Buffer.byteLength(text, "utf8") > MAX_BYTES) throw new RequestTooLargeError();
271
+ if (parseRequest(request) === undefined) {
272
+ const budget = { keys: 0 };
273
+ isPlainJson((request as { call?: { input?: unknown } }).call?.input, 0, budget);
274
+ if (budget.keys > MAX_KEYS) throw new RequestTooLargeError();
275
+ throw new Error("invalid ask request");
276
+ }
277
+ ensureAskDir(dir, options);
278
+ remove(replyFile(dir, request.id)); // never accept a reply that predates this request
279
+ writeFileAtomic(requestFile(dir, request.id), text);
280
+ }
281
+
282
+ /**
283
+ * Child: the parent's reply, or undefined (none yet, or unusable: fail closed,
284
+ * the child keeps waiting or times out). Accepted only when the parent claimed
285
+ * the request (`.taken` exists) and the reply echoes this request's nonce.
286
+ */
287
+ export function readReply(dir: string, id: string, nonce: string, options: MailboxOptions = {}): AskReply | undefined {
288
+ try {
289
+ need(id);
290
+ ensureAskDir(dir, options);
291
+ if (!isFile(takenFile(dir, id))) return undefined;
292
+ const reply = readValidated(replyFile(dir, id), parseReply, options);
293
+ return reply.id === id && reply.nonce === nonce ? reply : undefined;
294
+ } catch {
295
+ return undefined;
296
+ }
297
+ }
298
+
299
+ /** Child: ask the parent to drop this request (the child's abort signal fired). */
300
+ export function writeCancel(dir: string, id: string, options: MailboxOptions = {}): void {
301
+ need(id);
302
+ ensureAskDir(dir, options);
303
+ writeFileAtomic(cancelFile(dir, id), JSON.stringify({ v: VERSION, id } satisfies AskCancel));
304
+ }
305
+
306
+ /** Child: remove its request (claimed or not), reply and cancel. Never throws. */
307
+ export function cleanup(dir: string, id: string, options: MailboxOptions = {}): void {
308
+ if (!isValidId(id)) return;
309
+ try {
310
+ ensureAskDir(dir, options);
311
+ for (const file of [requestFile(dir, id), takenFile(dir, id), replyFile(dir, id), cancelFile(dir, id)]) remove(file);
312
+ } catch {
313
+ // the parent's sweep removes what is left
314
+ }
315
+ }
316
+
317
+ // --- parent side --------------------------------------------------------
318
+
319
+ /**
320
+ * Parent: claim and return the new requests. Each file is renamed to
321
+ * `<id>.json.taken`; rename is atomic, so across any number of takers exactly
322
+ * one gets each file (the others see ENOENT and skip it). `taken` also
323
+ * remembers every id, with the parent's own receivedAt (`now`), so an id is
324
+ * never returned twice. A file that is not valid is deleted and reported in
325
+ * `warnings`; nothing here throws.
326
+ */
327
+ export function takeRequests(dir: string, taken: Taken, now: number, options: MailboxOptions = {}): { requests: AskRequest[]; warnings: string[] } {
328
+ const requests: AskRequest[] = [];
329
+ const warnings: string[] = [];
330
+ let names: string[];
331
+ try {
332
+ ready(dir, options);
333
+ countWork("fs");
334
+ names = readdirSync(join(dir, "requests"));
335
+ } catch (error) {
336
+ return { requests, warnings: [`ask mailbox unusable: ${(error as Error).message}`] };
337
+ }
338
+ const candidates = names.filter((name) => name.endsWith(".json")).sort().slice(0, MAX_PER_PASS);
339
+ for (const name of candidates) {
340
+ const id = name.slice(0, -".json".length);
341
+ const from = join(dir, "requests", name);
342
+ if (!isValidId(id)) {
343
+ remove(from);
344
+ warnings.push(`ask request ${JSON.stringify(name.slice(0, 80))}: bad file name`);
345
+ continue;
346
+ }
347
+ if (taken.has(id)) {
348
+ remove(from); // an id is claimed once; a rewrite under the same id is dropped
349
+ continue;
350
+ }
351
+ const to = takenFile(dir, id);
352
+ try {
353
+ countWork("fs");
354
+ renameSync(from, to);
355
+ } catch (error) {
356
+ if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
357
+ remove(from); // e.g. a directory sits at the .taken name
358
+ warnings.push(`ask request ${id}: cannot claim (${(error as NodeJS.ErrnoException).code ?? "error"})`);
359
+ }
360
+ continue; // ENOENT: another taker won, or the child cleaned up
361
+ }
362
+ try {
363
+ const request = readValidated(to, parseRequest, options);
364
+ if (request.id !== id) throw new Error("id does not match the file name");
365
+ taken.set(id, { receivedAt: now, nonce: request.nonce, answered: false });
366
+ requests.push(request);
367
+ } catch (error) {
368
+ remove(to);
369
+ warnings.push(`ask request ${id}: ${(error as Error).message}`);
370
+ }
371
+ }
372
+ return { requests, warnings };
373
+ }
374
+
375
+ /**
376
+ * Parent: answer a request it claimed (it is in `taken`) and has not answered.
377
+ * Throws for an unknown or already answered id, an invalid reply, or an
378
+ * unusable dir. Marks the entry answered.
379
+ */
380
+ export function writeReply(dir: string, taken: Taken, id: string, reply: Pick<AskReply, "decision" | "reason">, options: MailboxOptions = {}): void {
381
+ need(id);
382
+ const entry = taken.get(id);
383
+ if (entry === undefined) throw new Error("unknown ask id");
384
+ if (entry.answered) throw new Error("ask already answered");
385
+ const full: AskReply = { v: VERSION, id, nonce: entry.nonce, decision: reply.decision, ...(reply.reason !== undefined ? { reason: reply.reason } : {}) };
386
+ if (parseReply(full) === undefined) throw new Error("invalid ask reply");
387
+ ensureAskDir(dir, options);
388
+ writeFileAtomic(replyFile(dir, id), JSON.stringify(full));
389
+ entry.answered = true;
390
+ }
391
+
392
+ /**
393
+ * Parent: ids the children want cancelled. Consumes what it returns (deletes
394
+ * the files); invalid files are deleted too. A cancel whose request is still
395
+ * unclaimed is left for a later poll, so it is not lost before the parent has
396
+ * seen the request.
397
+ */
398
+ export function readCancels(dir: string, options: MailboxOptions = {}): string[] {
399
+ const ids: string[] = [];
400
+ let names: string[];
401
+ try {
402
+ ready(dir, options);
403
+ countWork("fs");
404
+ names = readdirSync(join(dir, "cancels"));
405
+ } catch {
406
+ return ids;
407
+ }
408
+ for (const name of names.filter((n) => n.endsWith(".json")).sort().slice(0, MAX_PER_PASS)) {
409
+ const id = name.slice(0, -".json".length);
410
+ const file = join(dir, "cancels", name);
411
+ if (!isValidId(id)) {
412
+ remove(file);
413
+ continue;
414
+ }
415
+ if (isFile(requestFile(dir, id))) continue;
416
+ try {
417
+ if (readValidated(file, parseCancel, options).id === id) ids.push(id);
418
+ } catch {
419
+ // not a cancel we can trust
420
+ }
421
+ remove(file);
422
+ }
423
+ return ids;
424
+ }
425
+
426
+ /**
427
+ * Parent: remove the leftovers of requests that are finished. A claimed
428
+ * request goes (with its reply and cancel) when its child pid is dead or the
429
+ * parent has held it longer than `ttlMs` by its own clock (`taken`; an id it
430
+ * has no time for, such as after a restart, starts its clock now). A reply or
431
+ * cancel with no request at all is an orphan and goes. Returns the ids
432
+ * removed. Never throws.
433
+ */
434
+ export function sweep(dir: string, taken: Taken, now: number, ttlMs: number, alive: (pid: number) => boolean = isPidAlive, options: MailboxOptions = {}): string[] {
435
+ const removed: string[] = [];
436
+ try {
437
+ ready(dir, options);
438
+ } catch {
439
+ return removed;
440
+ }
441
+ let budget = MAX_PER_PASS;
442
+ const list = (sub: string): string[] => {
443
+ try {
444
+ countWork("fs");
445
+ return readdirSync(join(dir, sub));
446
+ } catch {
447
+ return [];
448
+ }
449
+ };
450
+ const idOf = (name: string, suffix: string): string | undefined => {
451
+ if (!name.endsWith(suffix)) return undefined;
452
+ const id = name.slice(0, -suffix.length);
453
+ return isValidId(id) ? id : undefined;
454
+ };
455
+ const requests = list("requests");
456
+ const claimed = new Set<string>();
457
+ for (const name of requests) {
458
+ const id = idOf(name, ".json.taken");
459
+ if (id !== undefined) claimed.add(id);
460
+ }
461
+ const unclaimed = new Set(requests.map((name) => idOf(name, ".json")).filter((id) => id !== undefined));
462
+ for (const id of [...claimed].sort()) {
463
+ if (budget-- <= 0) return removed;
464
+ let dead = true;
465
+ let nonce = "";
466
+ try {
467
+ const request = readValidated(takenFile(dir, id), parseRequest, options);
468
+ dead = !alive(request.childPid);
469
+ nonce = request.nonce;
470
+ } catch {
471
+ // unreadable: nothing to wait for
472
+ }
473
+ let entry = taken.get(id);
474
+ if (entry === undefined) {
475
+ entry = { receivedAt: now, nonce, answered: true };
476
+ taken.set(id, entry);
477
+ }
478
+ if (dead || now - entry.receivedAt > ttlMs) {
479
+ cleanup(dir, id, options);
480
+ taken.delete(id);
481
+ removed.push(id);
482
+ }
483
+ }
484
+ for (const sub of ["replies", "cancels"]) {
485
+ for (const name of list(sub)) {
486
+ if (name.endsWith(".tmp")) {
487
+ if (budget-- <= 0) return removed;
488
+ try {
489
+ countWork("fs");
490
+ if (now - lstatSync(join(dir, sub, name)).mtimeMs > TMP_TTL_MS) remove(join(dir, sub, name));
491
+ } catch {
492
+ // gone already
493
+ }
494
+ continue;
495
+ }
496
+ const id = idOf(name, ".json");
497
+ if (id === undefined || claimed.has(id) || unclaimed.has(id)) continue;
498
+ if (budget-- <= 0) return removed;
499
+ remove(join(dir, sub, name));
500
+ taken.delete(id);
501
+ if (!removed.includes(id)) removed.push(id);
502
+ }
503
+ }
504
+ for (const name of requests) {
505
+ if (!name.endsWith(".tmp")) continue;
506
+ if (budget-- <= 0) return removed;
507
+ try {
508
+ countWork("fs");
509
+ if (now - lstatSync(join(dir, "requests", name)).mtimeMs > TMP_TTL_MS) remove(join(dir, "requests", name));
510
+ } catch {
511
+ // gone already
512
+ }
513
+ }
514
+ return removed;
515
+ }