pi-keeper 0.0.0-stage → 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/CHANGELOG.md +63 -0
- package/LICENSE +201 -0
- package/NOTICE +36 -0
- package/README.md +71 -2
- package/extensions/ask-heartbeat.ts +55 -0
- package/extensions/ask-mailbox.ts +497 -0
- package/extensions/ask-server.ts +452 -0
- package/extensions/attention.ts +24 -0
- package/extensions/cc-extensions-compat.ts +103 -0
- package/extensions/child-auto.ts +32 -0
- package/extensions/child-cwd.ts +76 -0
- package/extensions/child-default.ts +32 -0
- package/extensions/child-lane.ts +134 -0
- package/extensions/child-plan.ts +12 -0
- package/extensions/config.ts +347 -0
- package/extensions/dialog-lock.ts +70 -0
- package/extensions/dialog.ts +420 -0
- package/extensions/index.ts +3453 -0
- package/extensions/modes.ts +1330 -0
- package/extensions/options.ts +109 -0
- package/extensions/perf.ts +54 -0
- package/extensions/plan-approval.ts +345 -0
- package/extensions/preview.ts +232 -0
- package/extensions/project-rules.ts +565 -0
- package/extensions/prompt-blocks.ts +163 -0
- package/extensions/remote-relay.ts +163 -0
- package/extensions/rtk-rewrite.ts +60 -0
- package/extensions/rulebook.ts +302 -0
- package/extensions/rules-line.ts +71 -0
- package/extensions/rules-view.ts +168 -0
- package/extensions/rules.ts +412 -0
- package/extensions/secure-file.ts +157 -0
- package/extensions/session-grant-store.ts +139 -0
- package/extensions/session-grants.ts +154 -0
- package/extensions/settings-panel.ts +194 -0
- package/extensions/shell-highlight-bridge.ts +50 -0
- package/extensions/subagents-bridge.ts +129 -0
- package/extensions/telemetry.ts +213 -0
- package/extensions/thinking.ts +62 -0
- package/extensions/title.ts +80 -0
- package/extensions/ui-relay.ts +149 -0
- package/extensions/utils.ts +3981 -0
- package/package.json +64 -5
- package/prompts/auto-mode.md +16 -0
- package/prompts/child-auto.md +26 -0
- package/prompts/child-default.md +21 -0
- package/prompts/child-plan.md +16 -0
- package/prompts/contract.md +29 -0
- package/prompts/default-mode.md +8 -0
- package/prompts/plan-mode.md +45 -0
- package/prompts/rule-warning.md +8 -0
|
@@ -0,0 +1,497 @@
|
|
|
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" | "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", "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
|
+
/** Child: file a request. Validated first; throws on an invalid one or an unusable dir. */
|
|
257
|
+
export function writeRequest(dir: string, request: AskRequest, options: MailboxOptions = {}): void {
|
|
258
|
+
if (parseRequest(request) === undefined) throw new Error("invalid ask request");
|
|
259
|
+
ensureAskDir(dir, options);
|
|
260
|
+
remove(replyFile(dir, request.id)); // never accept a reply that predates this request
|
|
261
|
+
writeFileAtomic(requestFile(dir, request.id), JSON.stringify(request));
|
|
262
|
+
}
|
|
263
|
+
|
|
264
|
+
/**
|
|
265
|
+
* Child: the parent's reply, or undefined (none yet, or unusable: fail closed,
|
|
266
|
+
* the child keeps waiting or times out). Accepted only when the parent claimed
|
|
267
|
+
* the request (`.taken` exists) and the reply echoes this request's nonce.
|
|
268
|
+
*/
|
|
269
|
+
export function readReply(dir: string, id: string, nonce: string, options: MailboxOptions = {}): AskReply | undefined {
|
|
270
|
+
try {
|
|
271
|
+
need(id);
|
|
272
|
+
ensureAskDir(dir, options);
|
|
273
|
+
if (!isFile(takenFile(dir, id))) return undefined;
|
|
274
|
+
const reply = readValidated(replyFile(dir, id), parseReply, options);
|
|
275
|
+
return reply.id === id && reply.nonce === nonce ? reply : undefined;
|
|
276
|
+
} catch {
|
|
277
|
+
return undefined;
|
|
278
|
+
}
|
|
279
|
+
}
|
|
280
|
+
|
|
281
|
+
/** Child: ask the parent to drop this request (the child's abort signal fired). */
|
|
282
|
+
export function writeCancel(dir: string, id: string, options: MailboxOptions = {}): void {
|
|
283
|
+
need(id);
|
|
284
|
+
ensureAskDir(dir, options);
|
|
285
|
+
writeFileAtomic(cancelFile(dir, id), JSON.stringify({ v: VERSION, id } satisfies AskCancel));
|
|
286
|
+
}
|
|
287
|
+
|
|
288
|
+
/** Child: remove its request (claimed or not), reply and cancel. Never throws. */
|
|
289
|
+
export function cleanup(dir: string, id: string, options: MailboxOptions = {}): void {
|
|
290
|
+
if (!isValidId(id)) return;
|
|
291
|
+
try {
|
|
292
|
+
ensureAskDir(dir, options);
|
|
293
|
+
for (const file of [requestFile(dir, id), takenFile(dir, id), replyFile(dir, id), cancelFile(dir, id)]) remove(file);
|
|
294
|
+
} catch {
|
|
295
|
+
// the parent's sweep removes what is left
|
|
296
|
+
}
|
|
297
|
+
}
|
|
298
|
+
|
|
299
|
+
// --- parent side --------------------------------------------------------
|
|
300
|
+
|
|
301
|
+
/**
|
|
302
|
+
* Parent: claim and return the new requests. Each file is renamed to
|
|
303
|
+
* `<id>.json.taken`; rename is atomic, so across any number of takers exactly
|
|
304
|
+
* one gets each file (the others see ENOENT and skip it). `taken` also
|
|
305
|
+
* remembers every id, with the parent's own receivedAt (`now`), so an id is
|
|
306
|
+
* never returned twice. A file that is not valid is deleted and reported in
|
|
307
|
+
* `warnings`; nothing here throws.
|
|
308
|
+
*/
|
|
309
|
+
export function takeRequests(dir: string, taken: Taken, now: number, options: MailboxOptions = {}): { requests: AskRequest[]; warnings: string[] } {
|
|
310
|
+
const requests: AskRequest[] = [];
|
|
311
|
+
const warnings: string[] = [];
|
|
312
|
+
let names: string[];
|
|
313
|
+
try {
|
|
314
|
+
ready(dir, options);
|
|
315
|
+
countWork("fs");
|
|
316
|
+
names = readdirSync(join(dir, "requests"));
|
|
317
|
+
} catch (error) {
|
|
318
|
+
return { requests, warnings: [`ask mailbox unusable: ${(error as Error).message}`] };
|
|
319
|
+
}
|
|
320
|
+
const candidates = names.filter((name) => name.endsWith(".json")).sort().slice(0, MAX_PER_PASS);
|
|
321
|
+
for (const name of candidates) {
|
|
322
|
+
const id = name.slice(0, -".json".length);
|
|
323
|
+
const from = join(dir, "requests", name);
|
|
324
|
+
if (!isValidId(id)) {
|
|
325
|
+
remove(from);
|
|
326
|
+
warnings.push(`ask request ${JSON.stringify(name.slice(0, 80))}: bad file name`);
|
|
327
|
+
continue;
|
|
328
|
+
}
|
|
329
|
+
if (taken.has(id)) {
|
|
330
|
+
remove(from); // an id is claimed once; a rewrite under the same id is dropped
|
|
331
|
+
continue;
|
|
332
|
+
}
|
|
333
|
+
const to = takenFile(dir, id);
|
|
334
|
+
try {
|
|
335
|
+
countWork("fs");
|
|
336
|
+
renameSync(from, to);
|
|
337
|
+
} catch (error) {
|
|
338
|
+
if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
|
|
339
|
+
remove(from); // e.g. a directory sits at the .taken name
|
|
340
|
+
warnings.push(`ask request ${id}: cannot claim (${(error as NodeJS.ErrnoException).code ?? "error"})`);
|
|
341
|
+
}
|
|
342
|
+
continue; // ENOENT: another taker won, or the child cleaned up
|
|
343
|
+
}
|
|
344
|
+
try {
|
|
345
|
+
const request = readValidated(to, parseRequest, options);
|
|
346
|
+
if (request.id !== id) throw new Error("id does not match the file name");
|
|
347
|
+
taken.set(id, { receivedAt: now, nonce: request.nonce, answered: false });
|
|
348
|
+
requests.push(request);
|
|
349
|
+
} catch (error) {
|
|
350
|
+
remove(to);
|
|
351
|
+
warnings.push(`ask request ${id}: ${(error as Error).message}`);
|
|
352
|
+
}
|
|
353
|
+
}
|
|
354
|
+
return { requests, warnings };
|
|
355
|
+
}
|
|
356
|
+
|
|
357
|
+
/**
|
|
358
|
+
* Parent: answer a request it claimed (it is in `taken`) and has not answered.
|
|
359
|
+
* Throws for an unknown or already answered id, an invalid reply, or an
|
|
360
|
+
* unusable dir. Marks the entry answered.
|
|
361
|
+
*/
|
|
362
|
+
export function writeReply(dir: string, taken: Taken, id: string, reply: Pick<AskReply, "decision" | "reason">, options: MailboxOptions = {}): void {
|
|
363
|
+
need(id);
|
|
364
|
+
const entry = taken.get(id);
|
|
365
|
+
if (entry === undefined) throw new Error("unknown ask id");
|
|
366
|
+
if (entry.answered) throw new Error("ask already answered");
|
|
367
|
+
const full: AskReply = { v: VERSION, id, nonce: entry.nonce, decision: reply.decision, ...(reply.reason !== undefined ? { reason: reply.reason } : {}) };
|
|
368
|
+
if (parseReply(full) === undefined) throw new Error("invalid ask reply");
|
|
369
|
+
ensureAskDir(dir, options);
|
|
370
|
+
writeFileAtomic(replyFile(dir, id), JSON.stringify(full));
|
|
371
|
+
entry.answered = true;
|
|
372
|
+
}
|
|
373
|
+
|
|
374
|
+
/**
|
|
375
|
+
* Parent: ids the children want cancelled. Consumes what it returns (deletes
|
|
376
|
+
* the files); invalid files are deleted too. A cancel whose request is still
|
|
377
|
+
* unclaimed is left for a later poll, so it is not lost before the parent has
|
|
378
|
+
* seen the request.
|
|
379
|
+
*/
|
|
380
|
+
export function readCancels(dir: string, options: MailboxOptions = {}): string[] {
|
|
381
|
+
const ids: string[] = [];
|
|
382
|
+
let names: string[];
|
|
383
|
+
try {
|
|
384
|
+
ready(dir, options);
|
|
385
|
+
countWork("fs");
|
|
386
|
+
names = readdirSync(join(dir, "cancels"));
|
|
387
|
+
} catch {
|
|
388
|
+
return ids;
|
|
389
|
+
}
|
|
390
|
+
for (const name of names.filter((n) => n.endsWith(".json")).sort().slice(0, MAX_PER_PASS)) {
|
|
391
|
+
const id = name.slice(0, -".json".length);
|
|
392
|
+
const file = join(dir, "cancels", name);
|
|
393
|
+
if (!isValidId(id)) {
|
|
394
|
+
remove(file);
|
|
395
|
+
continue;
|
|
396
|
+
}
|
|
397
|
+
if (isFile(requestFile(dir, id))) continue;
|
|
398
|
+
try {
|
|
399
|
+
if (readValidated(file, parseCancel, options).id === id) ids.push(id);
|
|
400
|
+
} catch {
|
|
401
|
+
// not a cancel we can trust
|
|
402
|
+
}
|
|
403
|
+
remove(file);
|
|
404
|
+
}
|
|
405
|
+
return ids;
|
|
406
|
+
}
|
|
407
|
+
|
|
408
|
+
/**
|
|
409
|
+
* Parent: remove the leftovers of requests that are finished. A claimed
|
|
410
|
+
* request goes (with its reply and cancel) when its child pid is dead or the
|
|
411
|
+
* parent has held it longer than `ttlMs` by its own clock (`taken`; an id it
|
|
412
|
+
* has no time for, such as after a restart, starts its clock now). A reply or
|
|
413
|
+
* cancel with no request at all is an orphan and goes. Returns the ids
|
|
414
|
+
* removed. Never throws.
|
|
415
|
+
*/
|
|
416
|
+
export function sweep(dir: string, taken: Taken, now: number, ttlMs: number, alive: (pid: number) => boolean = isPidAlive, options: MailboxOptions = {}): string[] {
|
|
417
|
+
const removed: string[] = [];
|
|
418
|
+
try {
|
|
419
|
+
ready(dir, options);
|
|
420
|
+
} catch {
|
|
421
|
+
return removed;
|
|
422
|
+
}
|
|
423
|
+
let budget = MAX_PER_PASS;
|
|
424
|
+
const list = (sub: string): string[] => {
|
|
425
|
+
try {
|
|
426
|
+
countWork("fs");
|
|
427
|
+
return readdirSync(join(dir, sub));
|
|
428
|
+
} catch {
|
|
429
|
+
return [];
|
|
430
|
+
}
|
|
431
|
+
};
|
|
432
|
+
const idOf = (name: string, suffix: string): string | undefined => {
|
|
433
|
+
if (!name.endsWith(suffix)) return undefined;
|
|
434
|
+
const id = name.slice(0, -suffix.length);
|
|
435
|
+
return isValidId(id) ? id : undefined;
|
|
436
|
+
};
|
|
437
|
+
const requests = list("requests");
|
|
438
|
+
const claimed = new Set<string>();
|
|
439
|
+
for (const name of requests) {
|
|
440
|
+
const id = idOf(name, ".json.taken");
|
|
441
|
+
if (id !== undefined) claimed.add(id);
|
|
442
|
+
}
|
|
443
|
+
const unclaimed = new Set(requests.map((name) => idOf(name, ".json")).filter((id) => id !== undefined));
|
|
444
|
+
for (const id of [...claimed].sort()) {
|
|
445
|
+
if (budget-- <= 0) return removed;
|
|
446
|
+
let dead = true;
|
|
447
|
+
let nonce = "";
|
|
448
|
+
try {
|
|
449
|
+
const request = readValidated(takenFile(dir, id), parseRequest, options);
|
|
450
|
+
dead = !alive(request.childPid);
|
|
451
|
+
nonce = request.nonce;
|
|
452
|
+
} catch {
|
|
453
|
+
// unreadable: nothing to wait for
|
|
454
|
+
}
|
|
455
|
+
let entry = taken.get(id);
|
|
456
|
+
if (entry === undefined) {
|
|
457
|
+
entry = { receivedAt: now, nonce, answered: true };
|
|
458
|
+
taken.set(id, entry);
|
|
459
|
+
}
|
|
460
|
+
if (dead || now - entry.receivedAt > ttlMs) {
|
|
461
|
+
cleanup(dir, id, options);
|
|
462
|
+
taken.delete(id);
|
|
463
|
+
removed.push(id);
|
|
464
|
+
}
|
|
465
|
+
}
|
|
466
|
+
for (const sub of ["replies", "cancels"]) {
|
|
467
|
+
for (const name of list(sub)) {
|
|
468
|
+
if (name.endsWith(".tmp")) {
|
|
469
|
+
if (budget-- <= 0) return removed;
|
|
470
|
+
try {
|
|
471
|
+
countWork("fs");
|
|
472
|
+
if (now - lstatSync(join(dir, sub, name)).mtimeMs > TMP_TTL_MS) remove(join(dir, sub, name));
|
|
473
|
+
} catch {
|
|
474
|
+
// gone already
|
|
475
|
+
}
|
|
476
|
+
continue;
|
|
477
|
+
}
|
|
478
|
+
const id = idOf(name, ".json");
|
|
479
|
+
if (id === undefined || claimed.has(id) || unclaimed.has(id)) continue;
|
|
480
|
+
if (budget-- <= 0) return removed;
|
|
481
|
+
remove(join(dir, sub, name));
|
|
482
|
+
taken.delete(id);
|
|
483
|
+
if (!removed.includes(id)) removed.push(id);
|
|
484
|
+
}
|
|
485
|
+
}
|
|
486
|
+
for (const name of requests) {
|
|
487
|
+
if (!name.endsWith(".tmp")) continue;
|
|
488
|
+
if (budget-- <= 0) return removed;
|
|
489
|
+
try {
|
|
490
|
+
countWork("fs");
|
|
491
|
+
if (now - lstatSync(join(dir, "requests", name)).mtimeMs > TMP_TTL_MS) remove(join(dir, "requests", name));
|
|
492
|
+
} catch {
|
|
493
|
+
// gone already
|
|
494
|
+
}
|
|
495
|
+
}
|
|
496
|
+
return removed;
|
|
497
|
+
}
|