@anhlp/alp-daemon 0.0.1-beta.3 → 0.0.1-beta.4

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 (51) hide show
  1. package/README.md +4 -0
  2. package/dist/alpd.js +10350 -3346
  3. package/dist/attachments.d.ts +211 -0
  4. package/dist/attachments.js +819 -0
  5. package/dist/build-manifest.json +21 -1
  6. package/dist/conversation.d.ts +119 -0
  7. package/dist/conversation.js +672 -0
  8. package/dist/files.d.ts +13 -0
  9. package/dist/files.js +15 -0
  10. package/dist/git.d.ts +87 -0
  11. package/dist/git.js +1093 -0
  12. package/dist/gitignore.d.ts +5 -0
  13. package/dist/gitignore.js +7 -1
  14. package/dist/history.d.ts +24 -0
  15. package/dist/history.js +149 -0
  16. package/dist/index.d.ts +6 -0
  17. package/dist/index.js +18 -1
  18. package/dist/lifecycle.d.ts +101 -0
  19. package/dist/lifecycle.js +239 -0
  20. package/dist/main.js +9 -3
  21. package/dist/registry.d.ts +89 -0
  22. package/dist/registry.js +343 -0
  23. package/dist/scheduler.d.ts +96 -0
  24. package/dist/scheduler.js +290 -0
  25. package/dist/schedules.d.ts +69 -0
  26. package/dist/schedules.js +244 -0
  27. package/dist/server.d.ts +11 -1
  28. package/dist/server.js +698 -76
  29. package/dist/store.d.ts +69 -1
  30. package/dist/store.js +109 -3
  31. package/dist/terminals.d.ts +157 -0
  32. package/dist/terminals.js +487 -0
  33. package/dist/worktrees.d.ts +41 -0
  34. package/dist/worktrees.js +246 -0
  35. package/package.json +64 -5
  36. package/src/attachments.ts +870 -0
  37. package/src/conversation.ts +837 -0
  38. package/src/files.ts +23 -2
  39. package/src/git.ts +1045 -0
  40. package/src/gitignore.ts +10 -0
  41. package/src/history.ts +118 -0
  42. package/src/index.ts +6 -0
  43. package/src/lifecycle.ts +283 -0
  44. package/src/main.ts +9 -3
  45. package/src/registry.ts +238 -0
  46. package/src/scheduler.ts +422 -0
  47. package/src/schedules.ts +294 -0
  48. package/src/server.ts +810 -86
  49. package/src/store.ts +115 -3
  50. package/src/terminals.ts +591 -0
  51. package/src/worktrees.ts +287 -0
@@ -0,0 +1,819 @@
1
+ // packages/daemon/src/attachments.ts
2
+ import { createHash, randomBytes } from "node:crypto";
3
+ import { constants } from "node:fs";
4
+ import { lstat, mkdir, open, readdir, realpath, rename, rm } from "node:fs/promises";
5
+ import path from "node:path";
6
+ import { Transform } from "node:stream";
7
+ import { ATTACHMENTS, ERROR, RPC_ERROR, attachmentChunkBytes } from "@anhlp/alp-protocol";
8
+ import { RpcError } from "./rpc-error.js";
9
+ var ID = /^[0-9a-f]{32}$/;
10
+ var UPLOAD = /^upl_([0-9a-f]{32})$/;
11
+ var ATTACHMENT = /^att_([0-9a-f]{32})$/;
12
+ var SHA256 = /^[0-9a-f]{64}$/;
13
+ var NOFOLLOW = constants.O_NOFOLLOW ?? 0;
14
+ var OPEN_READ = constants.O_RDONLY | NOFOLLOW;
15
+ var OPEN_WRITE = constants.O_RDWR | NOFOLLOW;
16
+ var OPEN_CREATE = constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | NOFOLLOW;
17
+ var MAX_META_BYTES = 64 * 1024;
18
+ var MAX_REFS_BYTES = 64 * 1024 * 1024;
19
+ var notFound = (what) => new RpcError(ERROR.notFound, what === "upload" ? "No such upload" : "No such attachment", { reason: "not_found" });
20
+ var invalid = (reason, message, extra = {}) => new RpcError(RPC_ERROR.invalidParams, message, { reason, ...extra });
21
+ var conflict = (reason, message, extra = {}) => new RpcError(ERROR.conflict, message, { reason, ...extra });
22
+ var unavailable = (reason, message, extra = {}) => new RpcError(ERROR.unavailable, message, { reason, ...extra });
23
+ var persistence = (what) => new RpcError(ERROR.failed, `alpd could not store ${what}`, { reason: "persistence_failed" });
24
+ var sha = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
25
+ var iso = (ms) => new Date(ms).toISOString();
26
+ var identity = (info) => ({ dev: String(info.dev), ino: String(info.ino) });
27
+ var same = (info, recorded) => String(info.dev) === recorded.dev && String(info.ino) === recorded.ino;
28
+ function attachmentName(raw, maxBytes = ATTACHMENTS.maxNameBytes) {
29
+ if (typeof raw !== "string") return void 0;
30
+ const name = raw.normalize("NFC").replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}/\\]/gu, "").trim();
31
+ if (!name || name === "." || name === "..") return void 0;
32
+ if (Buffer.byteLength(name, "utf8") > maxBytes) return void 0;
33
+ return name;
34
+ }
35
+ function sniffMimeType(head) {
36
+ const starts = (bytes, at = 0) => {
37
+ const expected = typeof bytes === "string" ? Buffer.from(bytes, "latin1") : Buffer.from(bytes);
38
+ return head.length >= at + expected.length && head.subarray(at, at + expected.length).equals(expected);
39
+ };
40
+ if (!head.length) return "application/octet-stream";
41
+ if (starts("%PDF-")) return "application/pdf";
42
+ if (starts([137, 80, 78, 71, 13, 10, 26, 10])) return "image/png";
43
+ if (starts([255, 216, 255])) return "image/jpeg";
44
+ if (starts("GIF87a") || starts("GIF89a")) return "image/gif";
45
+ if (starts("RIFF") && starts("WEBP", 8)) return "image/webp";
46
+ if (starts([80, 75, 3, 4]) || starts([80, 75, 5, 6])) return "application/zip";
47
+ if (starts([31, 139])) return "application/gzip";
48
+ if (head.includes(0)) return "application/octet-stream";
49
+ for (let cut = 0; cut < 4 && cut < head.length; cut++) {
50
+ try {
51
+ new TextDecoder("utf-8", { fatal: true }).decode(head.subarray(0, head.length - cut));
52
+ return "text/plain";
53
+ } catch {
54
+ }
55
+ }
56
+ return "application/octet-stream";
57
+ }
58
+ function attachmentLimits(input = {}, maxFrame) {
59
+ const out = {};
60
+ for (const key of ["maxObjectBytes", "maxPerPrompt", "maxPromptBytes", "maxChunkBytes", "maxActiveUploads", "maxPrincipalBytes", "maxDaemonBytes", "uploadTimeoutMs", "unreferencedRetentionMs", "releasedGraceMs"]) {
61
+ const value = input[key];
62
+ out[key] = typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? Math.min(value, ATTACHMENTS[key]) : ATTACHMENTS[key];
63
+ }
64
+ out.maxChunkBytes = attachmentChunkBytes(maxFrame, Math.max(1, out.maxChunkBytes));
65
+ return out;
66
+ }
67
+ function createAttachmentStore(options) {
68
+ const { root, sessionProject } = options;
69
+ const limits = attachmentLimits(options.limits);
70
+ const now = options.now ?? Date.now;
71
+ const crashPoint = options.crashPoint ?? (() => {
72
+ });
73
+ const log = options.log;
74
+ const objects = /* @__PURE__ */ new Map();
75
+ let refs = { version: 1, holders: {}, released: {} };
76
+ const beginning = /* @__PURE__ */ new Map();
77
+ const queues = /* @__PURE__ */ new Map();
78
+ let failure;
79
+ let sweeper;
80
+ const unreadable = /* @__PURE__ */ new Set();
81
+ function serial(key, run) {
82
+ const previous = queues.get(key) ?? Promise.resolve();
83
+ const result = previous.catch(() => {
84
+ }).then(run);
85
+ queues.set(key, result);
86
+ void result.finally(() => {
87
+ if (queues.get(key) === result) queues.delete(key);
88
+ }).catch(() => {
89
+ });
90
+ return result;
91
+ }
92
+ const withRefs = (run) => serial("refs", run);
93
+ const withObject = (id, run) => serial(`object:${id}`, run);
94
+ const dirOf = (id) => path.join(root, id);
95
+ const payloadOf = (id) => path.join(root, id, "payload");
96
+ const metaOf = (id) => path.join(root, id, "meta.json");
97
+ const refsFile = path.join(root, "refs.json");
98
+ async function writeAtomic(file, body) {
99
+ const temporary = `${file}.${randomBytes(6).toString("hex")}.tmp`;
100
+ let handle;
101
+ try {
102
+ handle = await open(temporary, OPEN_CREATE, 384);
103
+ await handle.writeFile(body, "utf8");
104
+ await handle.datasync();
105
+ await handle.close();
106
+ handle = void 0;
107
+ await rename(temporary, file);
108
+ } catch (error) {
109
+ await handle?.close().catch(() => {
110
+ });
111
+ await rm(temporary, { force: true }).catch(() => {
112
+ });
113
+ throw error;
114
+ }
115
+ }
116
+ async function readSmall(file, max) {
117
+ const handle = await open(file, OPEN_READ);
118
+ try {
119
+ const info2 = await handle.stat();
120
+ if (!info2.isFile() || info2.nlink !== 1 || info2.size > max) throw new Error("not a private regular file");
121
+ return await handle.readFile("utf8");
122
+ } finally {
123
+ await handle.close();
124
+ }
125
+ }
126
+ async function checkDir(meta) {
127
+ const info2 = await lstat(dirOf(meta.id));
128
+ if (!info2.isDirectory() || info2.isSymbolicLink() || !same(info2, meta.dir) || process.platform !== "win32" && (info2.mode & 63) !== 0) throw new Error("attachment directory changed");
129
+ }
130
+ async function openPayload(meta, flags) {
131
+ await checkDir(meta);
132
+ const handle = await open(payloadOf(meta.id), flags);
133
+ try {
134
+ const info2 = await handle.stat();
135
+ if (!info2.isFile() || info2.nlink !== 1 || !same(info2, meta.payload) || process.platform !== "win32" && (info2.mode & 127) !== 0) throw new Error("attachment payload changed");
136
+ return { handle, info: info2 };
137
+ } catch (error) {
138
+ await handle.close().catch(() => {
139
+ });
140
+ throw error;
141
+ }
142
+ }
143
+ function parseMeta(text, id) {
144
+ let value;
145
+ try {
146
+ value = JSON.parse(text);
147
+ } catch {
148
+ return void 0;
149
+ }
150
+ const strings = ["principalId", "principalEpoch", "project", "sessionId", "requestKey", "fingerprint", "name", "mimeType", "createdAt", "expiresAt"];
151
+ if (!value || value.version !== 1 || value.id !== id || !["uploading", "committed"].includes(value.state) || strings.some((key) => typeof value[key] !== "string")) return void 0;
152
+ if (!Number.isSafeInteger(value.size) || value.size < 0) return void 0;
153
+ for (const key of ["dir", "payload"]) if (typeof value[key]?.dev !== "string" || typeof value[key]?.ino !== "string") return void 0;
154
+ if (value.state === "committed" && (!SHA256.test(value.sha256 ?? "") || typeof value.committedAt !== "string" || typeof value.detectedMimeType !== "string")) return void 0;
155
+ return value;
156
+ }
157
+ const holdersOf = (id) => Object.values(refs.holders).filter((holder) => holder.attachments.includes(id));
158
+ const usage = (principalId) => {
159
+ let bytes = 0;
160
+ let uploads = 0;
161
+ for (const meta of objects.values()) {
162
+ if (principalId !== void 0 && meta.principalId !== principalId) continue;
163
+ bytes += meta.size;
164
+ if (meta.state === "uploading") uploads++;
165
+ }
166
+ return { bytes, uploads };
167
+ };
168
+ const info = (meta) => ({
169
+ attachmentId: `att_${meta.id}`,
170
+ sessionId: meta.sessionId,
171
+ name: meta.name,
172
+ mimeType: meta.mimeType,
173
+ detectedMimeType: meta.detectedMimeType,
174
+ size: meta.size,
175
+ sha256: meta.sha256,
176
+ createdAt: meta.createdAt,
177
+ committedAt: meta.committedAt,
178
+ referenced: holdersOf(meta.id).length > 0
179
+ });
180
+ const descriptor = (meta) => ({ type: "attachment", attachmentId: `att_${meta.id}`, name: meta.name, mimeType: meta.mimeType, detectedMimeType: meta.detectedMimeType, size: meta.size, sha256: meta.sha256 });
181
+ async function projectOfSession(sessionId) {
182
+ const project = sessionProject(sessionId);
183
+ if (typeof project !== "string" || !path.isAbsolute(project)) return void 0;
184
+ return realpath(project).catch(() => void 0);
185
+ }
186
+ async function bound(meta, principal) {
187
+ if (meta.principalId !== principal.id || meta.principalEpoch !== principal.epoch) return false;
188
+ if (principal.roots !== void 0 && !principal.roots.includes(meta.project)) return false;
189
+ return await projectOfSession(meta.sessionId) === meta.project;
190
+ }
191
+ function usable() {
192
+ if (failure) throw unavailable("attachment_unavailable", "alpd cannot use its attachment store; its log says why");
193
+ }
194
+ async function discard(meta, why) {
195
+ objects.delete(meta.id);
196
+ if (refs.released[meta.id] !== void 0) delete refs.released[meta.id];
197
+ await rm(dirOf(meta.id), { recursive: true, force: true }).catch((error) => log?.warn("could not remove an attachment directory", { code: "ALPD_ATTACHMENT_REMOVE_FAILED", why, error }));
198
+ if (meta.state === "committed") await Promise.resolve().then(() => options.onDiscard?.(`att_${meta.id}`)).catch((error) => log?.warn("could not remove the staged copy of an attachment", { code: "ALPD_ATTACHMENT_UNSTAGE_FAILED", why, error }));
199
+ }
200
+ async function upload(uploadId, principal, locked = true) {
201
+ const id = typeof uploadId === "string" ? UPLOAD.exec(uploadId)?.[1] : void 0;
202
+ const meta = id ? objects.get(id) : void 0;
203
+ if (!meta || meta.state !== "uploading" || !await bound(meta, principal)) throw notFound("upload");
204
+ if (locked && Date.parse(meta.expiresAt) <= now()) {
205
+ await discard(meta, "expired");
206
+ throw new RpcError(ERROR.notFound, "This upload expired; begin it again", { reason: "upload_expired" });
207
+ }
208
+ return meta;
209
+ }
210
+ async function attachment(attachmentId, principal) {
211
+ const id = typeof attachmentId === "string" ? ATTACHMENT.exec(attachmentId)?.[1] : void 0;
212
+ const meta = id ? objects.get(id) : void 0;
213
+ if (!meta || meta.state !== "committed" || !await bound(meta, principal)) throw notFound("attachment");
214
+ return meta;
215
+ }
216
+ async function saveRefs(next) {
217
+ await writeAtomic(refsFile, JSON.stringify(next));
218
+ refs = next;
219
+ }
220
+ async function sweep() {
221
+ if (failure) return;
222
+ await withRefs(async () => {
223
+ const at = now();
224
+ const released = { ...refs.released };
225
+ let changed = false;
226
+ for (const meta of [...objects.values()]) {
227
+ await withObject(meta.id, async () => {
228
+ if (objects.get(meta.id) !== meta) return;
229
+ if (meta.state === "uploading") {
230
+ if (Date.parse(meta.expiresAt) <= at) await discard(meta, "expired");
231
+ return;
232
+ }
233
+ if (holdersOf(meta.id).length) return;
234
+ const since = released[meta.id];
235
+ const due = since !== void 0 ? Date.parse(since) + limits.releasedGraceMs : Date.parse(meta.committedAt) + limits.unreferencedRetentionMs;
236
+ if (!(due <= at)) return;
237
+ if (since !== void 0) {
238
+ delete released[meta.id];
239
+ changed = true;
240
+ }
241
+ await discard(meta, since !== void 0 ? "released" : "unreferenced");
242
+ });
243
+ }
244
+ for (const id of Object.keys(released)) if (!objects.has(id)) {
245
+ delete released[id];
246
+ changed = true;
247
+ }
248
+ if (changed) await saveRefs({ ...refs, released }).catch((error) => log?.warn("could not record collected attachments", { code: "ALPD_ATTACHMENT_REFS_FAILED", error }));
249
+ await removeLeftovers(at);
250
+ });
251
+ }
252
+ async function removeLeftovers(at) {
253
+ for (const entry of await readdir(root, { withFileTypes: true })) {
254
+ const file = path.join(root, entry.name);
255
+ if (entry.name.startsWith("refs.json.") && entry.name.endsWith(".tmp")) {
256
+ await rm(file, { force: true });
257
+ continue;
258
+ }
259
+ if (!ID.test(entry.name) || objects.has(entry.name)) continue;
260
+ const info2 = await lstat(file).catch(() => void 0);
261
+ if (!info2) continue;
262
+ if (!info2.isDirectory() || info2.isSymbolicLink()) {
263
+ await rm(file, { force: true });
264
+ continue;
265
+ }
266
+ if (holdersOf(entry.name).length) {
267
+ if (!unreadable.has(entry.name)) {
268
+ unreadable.add(entry.name);
269
+ log?.warn("a referenced attachment's metadata cannot be read; it is kept", { code: "ALPD_ATTACHMENT_UNAVAILABLE", attachmentId: `att_${entry.name}` });
270
+ }
271
+ continue;
272
+ }
273
+ if (at - info2.mtimeMs >= limits.uploadTimeoutMs) await rm(file, { recursive: true, force: true });
274
+ }
275
+ }
276
+ async function recover() {
277
+ await mkdir(root, { recursive: true, mode: 448 });
278
+ const top = await lstat(root);
279
+ if (!top.isDirectory() || top.isSymbolicLink() || process.platform !== "win32" && ((top.mode & 63) !== 0 || top.uid !== process.getuid?.())) throw new Error("the attachment store must be a private directory of the daemon user (0700), not a link");
280
+ let conservative = false;
281
+ try {
282
+ const parsed = JSON.parse(await readSmall(refsFile, MAX_REFS_BYTES));
283
+ if (!parsed || parsed.version !== 1 || typeof parsed.holders !== "object" || typeof parsed.released !== "object") throw new Error("not a reference index");
284
+ for (const holder of Object.values(parsed.holders)) if (typeof holder?.sessionId !== "string" || !Array.isArray(holder.attachments)) throw new Error("not a reference index");
285
+ refs = { version: 1, holders: parsed.holders, released: parsed.released };
286
+ } catch (error) {
287
+ if (error?.code !== "ENOENT") {
288
+ conservative = true;
289
+ const aside = `${refsFile}.corrupt-${now()}`;
290
+ await rename(refsFile, aside).catch(() => {
291
+ });
292
+ log?.warn("the attachment reference index cannot be read; kept aside, every stored attachment is kept as referenced", { code: "ALPD_ATTACHMENT_REFS_UNREADABLE", error });
293
+ }
294
+ }
295
+ const at = now();
296
+ for (const entry of await readdir(root, { withFileTypes: true })) {
297
+ if (!ID.test(entry.name)) continue;
298
+ const directory = dirOf(entry.name);
299
+ const dirInfo = await lstat(directory).catch(() => void 0);
300
+ if (!dirInfo || !dirInfo.isDirectory() || dirInfo.isSymbolicLink()) continue;
301
+ for (const name of await readdir(directory)) if (name.startsWith("meta.json.") && name.endsWith(".tmp")) await rm(path.join(directory, name), { force: true });
302
+ const meta = parseMeta(await readSmall(metaOf(entry.name), MAX_META_BYTES).catch(() => ""), entry.name);
303
+ if (!meta) continue;
304
+ if (meta.state === "uploading" && Date.parse(meta.expiresAt) <= at) {
305
+ await rm(directory, { recursive: true, force: true });
306
+ continue;
307
+ }
308
+ objects.set(meta.id, meta);
309
+ if (meta.state === "committed") {
310
+ const opened = await openPayload(meta, OPEN_READ).catch(() => void 0);
311
+ if (opened) {
312
+ await opened.handle.chmod(256).catch(() => {
313
+ });
314
+ await opened.handle.close();
315
+ } else log?.warn("a stored attachment's payload is missing or changed; it is kept as unavailable", { code: "ALPD_ATTACHMENT_UNAVAILABLE", attachmentId: `att_${meta.id}` });
316
+ if (conservative) refs.holders[`recovered:${meta.id}`] = { sessionId: meta.sessionId, attachments: [meta.id], at: iso(at), kind: "recovered" };
317
+ }
318
+ }
319
+ if (conservative) await saveRefs(refs);
320
+ await removeLeftovers(at);
321
+ await sweep();
322
+ }
323
+ const recovered = recover().catch((error) => {
324
+ failure = error instanceof Error ? error : new Error(String(error));
325
+ log?.warn("the attachment store cannot be used", { code: "ALPD_ATTACHMENTS_UNUSABLE", error });
326
+ });
327
+ let closed = false;
328
+ if (options.sweepMs !== 0) {
329
+ void recovered.then(() => {
330
+ if (closed || failure) return;
331
+ sweeper = setInterval(() => void sweep().catch((error) => log?.warn("attachment collection failed", { code: "ALPD_ATTACHMENT_SWEEP_FAILED", error })), options.sweepMs ?? Math.min(15 * 60 * 1e3, Math.max(1e3, Math.floor(limits.uploadTimeoutMs / 4))));
332
+ sweeper.unref();
333
+ });
334
+ }
335
+ const beginResult = (meta, received2) => ({
336
+ uploadId: `upl_${meta.id}`,
337
+ state: meta.state,
338
+ received: received2,
339
+ size: meta.size,
340
+ maxChunkBytes: limits.maxChunkBytes,
341
+ ...meta.state === "uploading" ? { expiresAt: meta.expiresAt } : { attachmentId: `att_${meta.id}` }
342
+ });
343
+ async function received(meta) {
344
+ const { handle, info: info2 } = await openPayload(meta, OPEN_READ);
345
+ await handle.close();
346
+ return info2.size;
347
+ }
348
+ async function write(handle, buffer, position) {
349
+ if (options.io?.write) return options.io.write(handle, buffer, position);
350
+ let done = 0;
351
+ while (done < buffer.length) {
352
+ const { bytesWritten } = await handle.write(buffer, done, buffer.length - done, position + done);
353
+ if (!bytesWritten) throw new Error("short write");
354
+ done += bytesWritten;
355
+ }
356
+ }
357
+ return {
358
+ /** Effective limits, advertised in daemon.hello. */
359
+ limits,
360
+ /** Settles when start-up recovery is done (or failed: the methods then answer 1005). */
361
+ ready: () => recovered,
362
+ /** One collection now, after start-up recovery (as the timer's). */
363
+ async sweep() {
364
+ await recovered;
365
+ return sweep();
366
+ },
367
+ async begin(principal, params) {
368
+ await recovered;
369
+ usable();
370
+ const name = attachmentName(params.name, ATTACHMENTS.maxNameBytes);
371
+ if (!name) throw invalid("invalid_name", `A file name needs a visible character and at most ${ATTACHMENTS.maxNameBytes} UTF-8 bytes once control characters and path separators are removed`);
372
+ if (!Number.isSafeInteger(params.size) || params.size < 0) throw invalid("invalid_params", "size must be a byte count");
373
+ if (params.size > limits.maxObjectBytes) throw invalid("attachment_too_large", `An attachment is at most ${limits.maxObjectBytes} bytes`, { limit: limits.maxObjectBytes });
374
+ if (params.sha256 !== void 0 && !SHA256.test(params.sha256)) throw invalid("invalid_params", "sha256 must be 64 lowercase hex digits");
375
+ const mimeType = params.mimeType.toLowerCase();
376
+ const project = await projectOfSession(params.sessionId);
377
+ if (!project || principal.roots !== void 0 && !principal.roots.includes(project)) throw new RpcError(ERROR.notFound, "No such session", { reason: "not_found" });
378
+ const requestKey = sha(["attachment.begin", principal.id, principal.epoch, params.requestId]);
379
+ const fingerprint = sha([params.sessionId, name, params.size, mimeType, params.sha256 ?? null]);
380
+ for (; ; ) {
381
+ while (beginning.has(requestKey)) await beginning.get(requestKey).catch(() => {
382
+ });
383
+ const existing = [...objects.values()].find((meta2) => meta2.requestKey === requestKey);
384
+ if (!existing || existing.principalId !== principal.id || existing.principalEpoch !== principal.epoch) break;
385
+ if (existing.fingerprint !== fingerprint) throw conflict("request_conflict", `requestId ${params.requestId} was used for another upload`);
386
+ if (!await bound(existing, principal)) throw new RpcError(ERROR.notFound, "No such session", { reason: "not_found" });
387
+ if (existing.state === "committed") return beginResult(existing, existing.size);
388
+ if (Date.parse(existing.expiresAt) > now()) return withObject(existing.id, async () => beginResult(existing, await received(existing)));
389
+ await withObject(existing.id, () => discard(existing, "expired"));
390
+ }
391
+ const at = now();
392
+ for (const meta2 of [...objects.values()]) {
393
+ if (meta2.state !== "uploading") continue;
394
+ if (Date.parse(meta2.expiresAt) > at && !(meta2.principalId === principal.id && meta2.principalEpoch !== principal.epoch)) continue;
395
+ objects.delete(meta2.id);
396
+ void withObject(meta2.id, () => rm(dirOf(meta2.id), { recursive: true, force: true })).catch(() => {
397
+ });
398
+ }
399
+ const mine = usage(principal.id);
400
+ if (mine.uploads >= limits.maxActiveUploads) throw unavailable("quota_exceeded", `At most ${limits.maxActiveUploads} uploads may be in progress at once; commit or abort one first`, { limit: "active_uploads", max: limits.maxActiveUploads });
401
+ if (mine.bytes + params.size > limits.maxPrincipalBytes) throw unavailable("quota_exceeded", `Attachments of this principal take at most ${limits.maxPrincipalBytes} bytes, referenced ones included; delete unreferenced ones first`, { limit: "principal_bytes", max: limits.maxPrincipalBytes });
402
+ if (usage().bytes + params.size > limits.maxDaemonBytes) throw unavailable("quota_exceeded", "The daemon host keeps no more attachment bytes now", { limit: "daemon_bytes", max: limits.maxDaemonBytes });
403
+ const id = randomBytes(16).toString("hex");
404
+ const meta = {
405
+ version: 1,
406
+ id,
407
+ state: "uploading",
408
+ principalId: principal.id,
409
+ principalEpoch: principal.epoch,
410
+ project,
411
+ sessionId: params.sessionId,
412
+ requestKey,
413
+ fingerprint,
414
+ name,
415
+ mimeType,
416
+ size: params.size,
417
+ ...params.sha256 ? { declaredSha256: params.sha256 } : {},
418
+ createdAt: iso(at),
419
+ expiresAt: iso(at + limits.uploadTimeoutMs),
420
+ dir: { dev: "", ino: "" },
421
+ payload: { dev: "", ino: "" }
422
+ };
423
+ objects.set(id, meta);
424
+ const creating = withObject(id, async () => {
425
+ try {
426
+ await mkdir(dirOf(id), { mode: 448 });
427
+ const dirInfo = await lstat(dirOf(id));
428
+ if (!dirInfo.isDirectory() || dirInfo.isSymbolicLink()) throw new Error("attachment directory is not a directory");
429
+ meta.dir = identity(dirInfo);
430
+ const handle = await open(payloadOf(id), OPEN_CREATE, 384);
431
+ try {
432
+ meta.payload = identity(await handle.stat());
433
+ } finally {
434
+ await handle.close();
435
+ }
436
+ crashPoint("attachment.begin.before-meta");
437
+ await writeAtomic(metaOf(id), JSON.stringify(meta));
438
+ crashPoint("attachment.begin.after-meta");
439
+ return beginResult(meta, 0);
440
+ } catch (error) {
441
+ if (objects.get(id) === meta) objects.delete(id);
442
+ await rm(dirOf(id), { recursive: true, force: true }).catch(() => {
443
+ });
444
+ log?.warn("could not begin an attachment upload", { code: "ALPD_ATTACHMENT_BEGIN_FAILED", error });
445
+ throw persistence("the upload; it was not begun");
446
+ }
447
+ });
448
+ beginning.set(requestKey, creating);
449
+ try {
450
+ return await creating;
451
+ } finally {
452
+ if (beginning.get(requestKey) === creating) beginning.delete(requestKey);
453
+ }
454
+ },
455
+ async chunk(principal, params) {
456
+ await recovered;
457
+ usable();
458
+ const first = await upload(params.uploadId, principal, false);
459
+ return withObject(first.id, async () => {
460
+ const meta = await upload(params.uploadId, principal);
461
+ const bytes = Buffer.from(params.data, "base64");
462
+ if (!bytes.length || bytes.toString("base64") !== params.data) throw invalid("invalid_data", "data must be canonical base64 of at least one byte");
463
+ if (bytes.length > limits.maxChunkBytes) throw invalid("invalid_data", `A chunk carries at most ${limits.maxChunkBytes} decoded bytes`, { limit: limits.maxChunkBytes });
464
+ if (!Number.isSafeInteger(params.offset) || params.offset < 0) throw invalid("invalid_params", "offset must be a byte offset");
465
+ if (params.offset + bytes.length > meta.size) throw invalid("attachment_too_large", `This upload declared ${meta.size} bytes; the chunk goes beyond them`, { size: meta.size });
466
+ let opened;
467
+ try {
468
+ opened = await openPayload(meta, OPEN_WRITE);
469
+ } catch (error) {
470
+ log?.warn("an upload's files changed or vanished; it was aborted", { code: "ALPD_ATTACHMENT_TAMPERED", error });
471
+ await discard(meta, "tampered");
472
+ throw persistence("the upload; it was aborted");
473
+ }
474
+ const { handle, info: info2 } = opened;
475
+ try {
476
+ const stored = info2.size;
477
+ if (params.offset > stored) throw conflict("offset_mismatch", `The upload holds ${stored} bytes; send the chunk at offset ${stored}`, { received: stored });
478
+ const overlap = Math.min(stored - params.offset, bytes.length);
479
+ if (overlap > 0) {
480
+ const existing = Buffer.alloc(overlap);
481
+ await handle.read(existing, 0, overlap, params.offset);
482
+ if (!existing.equals(bytes.subarray(0, overlap))) throw conflict("chunk_conflict", `Bytes at offset ${params.offset} were already received with other content`, { received: stored });
483
+ }
484
+ if (overlap < bytes.length) {
485
+ try {
486
+ await write(handle, bytes.subarray(overlap), params.offset + overlap);
487
+ } catch (error) {
488
+ await handle.close().catch(() => {
489
+ });
490
+ log?.warn("could not write an upload chunk; the upload was aborted", { code: "ALPD_ATTACHMENT_WRITE_FAILED", error });
491
+ await discard(meta, "write failed");
492
+ throw persistence("the chunk; the upload was aborted and its space released");
493
+ }
494
+ }
495
+ return { received: Math.max(stored, params.offset + bytes.length), size: meta.size };
496
+ } finally {
497
+ await handle.close().catch(() => {
498
+ });
499
+ }
500
+ });
501
+ },
502
+ async commit(principal, params) {
503
+ await recovered;
504
+ usable();
505
+ const id = UPLOAD.exec(params.uploadId)?.[1];
506
+ const known = id ? objects.get(id) : void 0;
507
+ if (known?.state === "committed" && await bound(known, principal)) {
508
+ if (known.sha256 !== params.sha256) throw conflict("hash_mismatch", "This upload was committed with another SHA-256");
509
+ return { attachment: info(known) };
510
+ }
511
+ const first = await upload(params.uploadId, principal, false);
512
+ return withObject(first.id, async () => {
513
+ const again = objects.get(first.id);
514
+ if (again?.state === "committed" && await bound(again, principal)) {
515
+ if (again.sha256 !== params.sha256) throw conflict("hash_mismatch", "This upload was committed with another SHA-256");
516
+ return { attachment: info(again) };
517
+ }
518
+ const meta = await upload(params.uploadId, principal);
519
+ let opened;
520
+ try {
521
+ opened = await openPayload(meta, OPEN_READ);
522
+ } catch (error) {
523
+ log?.warn("an upload's files changed or vanished; it was aborted", { code: "ALPD_ATTACHMENT_TAMPERED", error });
524
+ await discard(meta, "tampered");
525
+ throw persistence("the upload; it was aborted");
526
+ }
527
+ const { handle, info: stat } = opened;
528
+ let digest;
529
+ let head;
530
+ try {
531
+ if (stat.size !== meta.size) throw conflict("upload_incomplete", `The upload holds ${stat.size} of ${meta.size} bytes`, { received: stat.size, size: meta.size });
532
+ const hash = createHash("sha256");
533
+ const buffer = Buffer.alloc(64 * 1024);
534
+ head = Buffer.alloc(0);
535
+ for (let position = 0; position < meta.size; ) {
536
+ const { bytesRead } = await handle.read(buffer, 0, Math.min(buffer.length, meta.size - position), position);
537
+ if (!bytesRead) throw new Error("short read");
538
+ hash.update(buffer.subarray(0, bytesRead));
539
+ if (head.length < 8192) head = Buffer.concat([head, buffer.subarray(0, Math.min(bytesRead, 8192 - head.length))]);
540
+ position += bytesRead;
541
+ }
542
+ digest = hash.digest("hex");
543
+ await handle.datasync();
544
+ } catch (error) {
545
+ await handle.close().catch(() => {
546
+ });
547
+ if (error instanceof RpcError) throw error;
548
+ log?.warn("could not read an upload back; it was aborted", { code: "ALPD_ATTACHMENT_READ_FAILED", error });
549
+ await discard(meta, "read failed");
550
+ throw persistence("the upload; it was aborted");
551
+ }
552
+ await handle.close().catch(() => {
553
+ });
554
+ if (digest !== params.sha256 || meta.declaredSha256 !== void 0 && digest !== meta.declaredSha256) {
555
+ await discard(meta, "hash mismatch");
556
+ throw conflict("hash_mismatch", "The bytes received do not have this SHA-256; the upload was aborted");
557
+ }
558
+ if (objects.get(meta.id) !== meta) throw notFound("upload");
559
+ const committed = { ...meta, state: "committed", sha256: digest, detectedMimeType: sniffMimeType(head), committedAt: iso(now()) };
560
+ crashPoint("attachment.commit.before-publish");
561
+ try {
562
+ await writeAtomic(metaOf(meta.id), JSON.stringify(committed));
563
+ } catch (error) {
564
+ log?.warn("could not publish an attachment; the upload was aborted", { code: "ALPD_ATTACHMENT_PUBLISH_FAILED", error });
565
+ await discard(meta, "publish failed");
566
+ throw persistence("the attachment; the upload was aborted and its space released");
567
+ }
568
+ if (objects.get(meta.id) !== meta) throw notFound("upload");
569
+ objects.set(meta.id, committed);
570
+ crashPoint("attachment.commit.after-publish");
571
+ const readOnly = await openPayload(committed, OPEN_READ).catch(() => void 0);
572
+ if (readOnly) {
573
+ await readOnly.handle.chmod(256).catch(() => {
574
+ });
575
+ await readOnly.handle.close();
576
+ }
577
+ return { attachment: info(committed) };
578
+ });
579
+ },
580
+ async abort(principal, params) {
581
+ await recovered;
582
+ usable();
583
+ const first = await upload(params.uploadId, principal, false);
584
+ return withObject(first.id, async () => {
585
+ const meta = await upload(params.uploadId, principal);
586
+ await discard(meta, "aborted");
587
+ return { aborted: true };
588
+ });
589
+ },
590
+ async get(principal, params) {
591
+ await recovered;
592
+ usable();
593
+ return { attachment: info(await attachment(params.attachmentId, principal)) };
594
+ },
595
+ /** Deletes an attachment nothing references; a referenced one is refused, never evicted. */
596
+ async remove(principal, params) {
597
+ await recovered;
598
+ usable();
599
+ await attachment(params.attachmentId, principal);
600
+ return withRefs(() => withObject(ATTACHMENT.exec(params.attachmentId)[1], async () => {
601
+ const meta = await attachment(params.attachmentId, principal);
602
+ if (holdersOf(meta.id).length) throw conflict("attachment_referenced", "A prompt still references this attachment; it is kept");
603
+ const released = { ...refs.released };
604
+ if (released[meta.id] !== void 0) {
605
+ delete released[meta.id];
606
+ await saveRefs({ ...refs, released }).catch(() => {
607
+ });
608
+ }
609
+ await discard(meta, "deleted");
610
+ return { deleted: true };
611
+ }));
612
+ },
613
+ /**
614
+ * The attachments of a prompt to `sessionId`, in order, checked as every other call checks them
615
+ * (bound to this principal, project and session) and within the prompt limits, with their payloads
616
+ * there. What the runtime gets in their place: ids, display metadata and digests.
617
+ */
618
+ async resolve(principal, sessionId, attachmentIds) {
619
+ await recovered;
620
+ usable();
621
+ if (attachmentIds.length > limits.maxPerPrompt) throw invalid("attachment_limit", `A prompt carries at most ${limits.maxPerPrompt} attachments`, { maxPerPrompt: limits.maxPerPrompt });
622
+ const found = [];
623
+ let total = 0;
624
+ for (const attachmentId of attachmentIds) {
625
+ const meta = await attachment(attachmentId, principal);
626
+ if (meta.sessionId !== sessionId) throw notFound("attachment");
627
+ total += meta.size;
628
+ if (total > limits.maxPromptBytes) throw invalid("attachment_limit", `The attachments of a prompt are at most ${limits.maxPromptBytes} bytes together`, { maxPromptBytes: limits.maxPromptBytes });
629
+ const opened = await openPayload(meta, OPEN_READ).catch(() => void 0);
630
+ await opened?.handle.close();
631
+ if (!opened || opened.info.size !== meta.size) throw unavailable("attachment_unavailable", `Attachment att_${meta.id} is stored but its bytes cannot be read now`, { attachmentId: `att_${meta.id}` });
632
+ found.push(descriptor(meta));
633
+ }
634
+ return found;
635
+ },
636
+ /**
637
+ * Pins `attachmentIds` for `holder` durably (a prompt's receipt key; t-15b0.4's fork adds the
638
+ * new session's holder the same way after re-authorizing the source's attachments for it). Each
639
+ * must still be committed; a write failure pins nothing.
640
+ */
641
+ async pin(holder, sessionId, attachmentIds, kind = "prompt") {
642
+ await recovered;
643
+ usable();
644
+ const ids = attachmentIds.map((attachmentId) => ATTACHMENT.exec(attachmentId)?.[1]);
645
+ return withRefs(async () => {
646
+ for (const id of ids) if (!id || objects.get(id)?.state !== "committed") throw notFound("attachment");
647
+ const kept = /* @__PURE__ */ new Set([...refs.holders[holder]?.attachments ?? [], ...ids]);
648
+ const released = { ...refs.released };
649
+ for (const id of kept) delete released[id];
650
+ crashPoint("attachment.pin.before-write");
651
+ try {
652
+ await saveRefs({ version: 1, holders: { ...refs.holders, [holder]: { sessionId, attachments: [...kept], at: iso(now()), kind } }, released });
653
+ } catch (error) {
654
+ log?.warn("could not record attachment references", { code: "ALPD_ATTACHMENT_REFS_FAILED", error });
655
+ throw persistence("the attachment references; the prompt was not sent");
656
+ }
657
+ crashPoint("attachment.pin.after-write");
658
+ });
659
+ },
660
+ /** The attachments these holders pin, as ids (a fork's kept prompts, §12.7); unknown holders hold none. */
661
+ async heldBy(holders) {
662
+ await recovered;
663
+ if (failure) return [];
664
+ const ids = /* @__PURE__ */ new Set();
665
+ for (const holder of holders) for (const id of refs.holders[holder]?.attachments ?? []) ids.add(`att_${id}`);
666
+ return [...ids];
667
+ },
668
+ /**
669
+ * Re-authorizes attachments for `principal` before another session pins them (a fork, §12.7): each
670
+ * must be committed and bound to this principal, its grant epoch and an authorized project, as every
671
+ * other call checks; otherwise refused as an unknown one.
672
+ */
673
+ async authorize(principal, attachmentIds, forks = []) {
674
+ await recovered;
675
+ usable();
676
+ for (const attachmentId of attachmentIds) {
677
+ const id = typeof attachmentId === "string" ? ATTACHMENT.exec(attachmentId)?.[1] : void 0;
678
+ const meta = id ? objects.get(id) : void 0;
679
+ if (meta?.state === "committed" && await bound(meta, principal)) continue;
680
+ if (meta?.state === "committed" && meta.principalId === principal.id && meta.principalEpoch === principal.epoch && (principal.roots === void 0 || principal.roots.includes(meta.project))) {
681
+ let held = false;
682
+ for (const fork of forks) {
683
+ if (refs.holders[`fork:${fork}`]?.sessionId === fork && refs.holders[`fork:${fork}`].attachments.includes(meta.id) && await projectOfSession(fork) === meta.project) {
684
+ held = true;
685
+ break;
686
+ }
687
+ }
688
+ if (held) continue;
689
+ }
690
+ throw notFound("attachment");
691
+ }
692
+ },
693
+ /** Drops `holder`'s references (a prompt refused before it reached the runtime). */
694
+ async release(holder) {
695
+ await recovered;
696
+ usable();
697
+ return withRefs(async () => {
698
+ if (!refs.holders[holder]) return;
699
+ const { [holder]: dropped, ...holders } = refs.holders;
700
+ const released = { ...refs.released };
701
+ for (const id of dropped.attachments) if (!Object.values(holders).some((other) => other.attachments.includes(id))) released[id] = iso(now());
702
+ await saveRefs({ version: 1, holders, released });
703
+ });
704
+ },
705
+ /**
706
+ * Releases every reference of these sessions: the seam for deleting a session's history (today
707
+ * only retention removes a tree; archive keeps it). Released objects stay `releasedGraceMs`.
708
+ */
709
+ async releaseSessions(sessionIds) {
710
+ await recovered;
711
+ if (failure) return;
712
+ const gone = new Set(sessionIds);
713
+ return withRefs(async () => {
714
+ const holders = {};
715
+ const dropped = [];
716
+ for (const [key, holder] of Object.entries(refs.holders)) {
717
+ if (gone.has(holder.sessionId)) dropped.push(...holder.attachments);
718
+ else holders[key] = holder;
719
+ }
720
+ if (!dropped.length && Object.keys(holders).length === Object.keys(refs.holders).length) return;
721
+ const released = { ...refs.released };
722
+ for (const id of dropped) if (!Object.values(holders).some((other) => other.attachments.includes(id))) released[id] = iso(now());
723
+ await saveRefs({ version: 1, holders, released });
724
+ });
725
+ },
726
+ /** The runtime's reader (AttachmentReader). */
727
+ reader: {
728
+ async open(attachmentId, sessionId) {
729
+ await recovered;
730
+ usable();
731
+ const id = ATTACHMENT.exec(attachmentId)?.[1];
732
+ const meta = id ? objects.get(id) : void 0;
733
+ if (!meta || meta.state !== "committed" || !Object.values(refs.holders).some((holder) => holder.sessionId === sessionId && holder.attachments.includes(meta.id))) throw notFound("attachment");
734
+ const { handle, info: stat } = await openPayload(meta, OPEN_READ);
735
+ if (stat.size !== meta.size) {
736
+ await handle.close();
737
+ throw unavailable("attachment_unavailable", "The attachment's bytes changed");
738
+ }
739
+ const hash = createHash("sha256");
740
+ const stream = handle.createReadStream({ start: 0, ...meta.size ? { end: meta.size - 1 } : {}, autoClose: true });
741
+ const verified = stream.pipe(new Transform({
742
+ transform(chunk, _encoding, done) {
743
+ hash.update(chunk);
744
+ done(null, chunk);
745
+ },
746
+ flush(done) {
747
+ done(hash.digest("hex") === meta.sha256 ? null : new Error("attachment bytes do not match their SHA-256"));
748
+ }
749
+ }));
750
+ stream.on("error", (error) => verified.destroy(error));
751
+ return { stream: verified, attachment: descriptor(meta) };
752
+ }
753
+ },
754
+ /** Usage, for tests and status: bytes reserved and uploads in progress, of one principal or all. */
755
+ usage,
756
+ /** The holders of the reference index, for tests. */
757
+ holders: () => structuredClone(refs.holders),
758
+ close() {
759
+ closed = true;
760
+ if (sweeper) clearInterval(sweeper);
761
+ sweeper = void 0;
762
+ }
763
+ };
764
+ }
765
+ var LIMIT_KEYS = ["maxObjectBytes", "maxPerPrompt", "maxPromptBytes", "maxChunkBytes", "maxActiveUploads", "maxPrincipalBytes", "maxDaemonBytes", "uploadTimeoutMs", "unreferencedRetentionMs", "releasedGraceMs"];
766
+ async function readAttachmentConfig(home) {
767
+ const problems = [];
768
+ const limits = {};
769
+ let text;
770
+ try {
771
+ const handle = await open(path.join(home, "attachments.json"), OPEN_READ);
772
+ try {
773
+ const stat = await handle.stat();
774
+ if (!stat.isFile() || stat.size > 64 * 1024) throw new Error("not a small regular file");
775
+ text = await handle.readFile("utf8");
776
+ } finally {
777
+ await handle.close();
778
+ }
779
+ } catch (error) {
780
+ if (error?.code !== "ENOENT") problems.push(`attachments.json cannot be read (${error?.code ?? error?.message ?? error}); the default limits hold`);
781
+ return { limits, problems };
782
+ }
783
+ let parsed;
784
+ try {
785
+ parsed = JSON.parse(text);
786
+ } catch {
787
+ problems.push("attachments.json is not JSON; the default limits hold");
788
+ return { limits, problems };
789
+ }
790
+ const given = parsed?.limits;
791
+ if (given === void 0) return { limits, problems };
792
+ if (!given || typeof given !== "object" || Array.isArray(given)) {
793
+ problems.push("attachments.json limits must be an object");
794
+ return { limits, problems };
795
+ }
796
+ for (const [key, value] of Object.entries(given)) {
797
+ if (!LIMIT_KEYS.includes(key)) {
798
+ problems.push(`attachments.json names an unknown limit ${key}`);
799
+ continue;
800
+ }
801
+ if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
802
+ problems.push(`attachments.json limit ${key} must be a non-negative integer`);
803
+ continue;
804
+ }
805
+ if (value > ATTACHMENTS[key]) {
806
+ problems.push(`attachments.json limit ${key} cannot raise the default ${ATTACHMENTS[key]}; it is ignored`);
807
+ continue;
808
+ }
809
+ limits[key] = value;
810
+ }
811
+ return { limits, problems };
812
+ }
813
+ export {
814
+ attachmentLimits,
815
+ attachmentName,
816
+ createAttachmentStore,
817
+ readAttachmentConfig,
818
+ sniffMimeType
819
+ };