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

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 (95) hide show
  1. package/README.md +4 -0
  2. package/dist/THIRD-PARTY-NOTICES.txt +26 -1
  3. package/dist/alpd.js +29928 -14898
  4. package/dist/attachments.d.ts +187 -0
  5. package/dist/attachments.js +856 -0
  6. package/dist/build-manifest.json +34 -1
  7. package/dist/conversation.d.ts +119 -0
  8. package/dist/conversation.js +688 -0
  9. package/dist/disk.d.ts +67 -0
  10. package/dist/disk.js +152 -0
  11. package/dist/files.d.ts +154 -2
  12. package/dist/files.js +392 -68
  13. package/dist/git.d.ts +93 -0
  14. package/dist/git.js +1192 -0
  15. package/dist/gitignore.d.ts +5 -0
  16. package/dist/gitignore.js +7 -1
  17. package/dist/history.d.ts +24 -0
  18. package/dist/history.js +149 -0
  19. package/dist/index.d.ts +7 -0
  20. package/dist/index.js +21 -1
  21. package/dist/lifecycle.d.ts +101 -0
  22. package/dist/lifecycle.js +239 -0
  23. package/dist/main.js +43 -11
  24. package/dist/native-terminal.d.ts +45 -0
  25. package/dist/native-terminal.js +198 -0
  26. package/dist/operations.d.ts +8 -2
  27. package/dist/operations.js +20 -10
  28. package/dist/registry.d.ts +89 -0
  29. package/dist/registry.js +343 -0
  30. package/dist/scheduler.d.ts +96 -0
  31. package/dist/scheduler.js +296 -0
  32. package/dist/schedules.d.ts +70 -0
  33. package/dist/schedules.js +246 -0
  34. package/dist/server.d.ts +14 -2
  35. package/dist/server.js +836 -90
  36. package/dist/store.d.ts +72 -2
  37. package/dist/store.js +111 -4
  38. package/dist/terminal-native/README.md +201 -0
  39. package/dist/terminal-native/prebuilt/darwin-arm64/manifest.json +11 -0
  40. package/dist/terminal-native/prebuilt/darwin-arm64/terminal-owner +0 -0
  41. package/dist/terminal-native/prebuilt/darwin-x64/manifest.json +11 -0
  42. package/dist/terminal-native/prebuilt/darwin-x64/terminal-owner +0 -0
  43. package/dist/terminal-native/prebuilt/linux-arm64-glibc/manifest.json +10 -0
  44. package/dist/terminal-native/prebuilt/linux-arm64-glibc/terminal-owner +0 -0
  45. package/dist/terminal-native/prebuilt/linux-arm64-musl/manifest.json +10 -0
  46. package/dist/terminal-native/prebuilt/linux-arm64-musl/terminal-owner +0 -0
  47. package/dist/terminal-native/prebuilt/linux-x64-glibc/manifest.json +10 -0
  48. package/dist/terminal-native/prebuilt/linux-x64-glibc/terminal-owner +0 -0
  49. package/dist/terminal-native/prebuilt/linux-x64-musl/manifest.json +10 -0
  50. package/dist/terminal-native/prebuilt/linux-x64-musl/terminal-owner +0 -0
  51. package/dist/terminal-native/terminal-owner.c +389 -0
  52. package/dist/terminal-screen.d.ts +24 -0
  53. package/dist/terminal-screen.js +99 -0
  54. package/dist/terminals.d.ts +193 -0
  55. package/dist/terminals.js +570 -0
  56. package/dist/windows-terminal.d.ts +29 -0
  57. package/dist/windows-terminal.js +122 -0
  58. package/dist/worktrees.d.ts +65 -0
  59. package/dist/worktrees.js +318 -0
  60. package/native/README.md +201 -0
  61. package/native/prebuilt/darwin-arm64/manifest.json +11 -0
  62. package/native/prebuilt/darwin-arm64/terminal-owner +0 -0
  63. package/native/prebuilt/darwin-x64/manifest.json +11 -0
  64. package/native/prebuilt/darwin-x64/terminal-owner +0 -0
  65. package/native/prebuilt/linux-arm64-glibc/manifest.json +10 -0
  66. package/native/prebuilt/linux-arm64-glibc/terminal-owner +0 -0
  67. package/native/prebuilt/linux-arm64-musl/manifest.json +10 -0
  68. package/native/prebuilt/linux-arm64-musl/terminal-owner +0 -0
  69. package/native/prebuilt/linux-x64-glibc/manifest.json +10 -0
  70. package/native/prebuilt/linux-x64-glibc/terminal-owner +0 -0
  71. package/native/prebuilt/linux-x64-musl/manifest.json +10 -0
  72. package/native/prebuilt/linux-x64-musl/terminal-owner +0 -0
  73. package/native/terminal-owner.c +389 -0
  74. package/package.json +70 -7
  75. package/src/attachments.ts +908 -0
  76. package/src/conversation.ts +857 -0
  77. package/src/disk.ts +175 -0
  78. package/src/files.ts +528 -82
  79. package/src/git.ts +1140 -0
  80. package/src/gitignore.ts +10 -0
  81. package/src/history.ts +118 -0
  82. package/src/index.ts +7 -0
  83. package/src/lifecycle.ts +283 -0
  84. package/src/main.ts +37 -12
  85. package/src/native-terminal.ts +122 -0
  86. package/src/operations.ts +27 -11
  87. package/src/registry.ts +238 -0
  88. package/src/scheduler.ts +432 -0
  89. package/src/schedules.ts +297 -0
  90. package/src/server.ts +948 -102
  91. package/src/store.ts +117 -4
  92. package/src/terminal-screen.ts +74 -0
  93. package/src/terminals.ts +641 -0
  94. package/src/windows-terminal.ts +123 -0
  95. package/src/worktrees.ts +382 -0
package/src/gitignore.ts CHANGED
@@ -134,6 +134,16 @@ export function resolveGit(name = 'git', searchPath = process.env.PATH ?? proces
134
134
  return undefined;
135
135
  }
136
136
 
137
+ /**
138
+ * The absolute entries of PATH outside `root` (insideRoot), for the environment of a Git alpd runs
139
+ * in a workspace: whatever Git itself starts is then never found in the workspace either.
140
+ */
141
+ export function searchPathOutside(root: string, searchPath = process.env.PATH ?? process.env.Path ?? ''): string {
142
+ const box = rootOf(root);
143
+ if (!box) throw new IgnoreUnknown('the workspace cannot be examined');
144
+ return searchPath.split(path.delimiter).filter(directory => directory && path.isAbsolute(directory) && !insideRoot(directory, box)).join(path.delimiter);
145
+ }
146
+
137
147
  /** Whether `root` or a directory above it holds a `.git` entry: Git saying "not a git repository" there is a broken repository, not none. */
138
148
  function hasGitEntry(root: string): boolean {
139
149
  for (let directory = root; ; directory = path.dirname(directory)) {
package/src/history.ts ADDED
@@ -0,0 +1,118 @@
1
+ import { open, readFile, writeFile, rename, stat } from 'node:fs/promises';
2
+ import { createReadStream } from 'node:fs';
3
+ import { randomBytes, createHmac, timingSafeEqual } from 'node:crypto';
4
+ import type { Envelope } from '@anhlp/alp-protocol/events';
5
+
6
+ /** Derived fixed-width index: offset, byte length, stable event cursor (three u64s).
7
+ * A first-use migration scans once; subsequent pages seek at most limit index records
8
+ * and at most maxBytes timeline bytes. Metadata commits the recoverable index prefix.
9
+ */
10
+ const WIDTH = 24;
11
+ type Meta = { generation: string; secret: string; ino: number; bytes: number; count: number; tip: number };
12
+ export type HistoryItem = Envelope | { cursor: number; oversized: { bytes: number } };
13
+ export class HistoryError extends Error {
14
+ constructor(public reason: 'invalid_cursor' | 'stale_cursor', message: string) { super(message); }
15
+ }
16
+ export function createHistoryIndex(file: string) {
17
+ let pending: Promise<unknown> = Promise.resolve();
18
+ const index = `${file}.idx`;
19
+ const metadata = `${file}.history.json`;
20
+ async function sync(): Promise<Meta> {
21
+ const info = await stat(file).catch((error: any) => { if (error.code === 'ENOENT') return undefined; throw error; });
22
+ let meta: Meta | undefined;
23
+ try { meta = JSON.parse(await readFile(metadata, 'utf8')); } catch (error: any) { if (error.code !== 'ENOENT' && !(error instanceof SyntaxError)) throw error; }
24
+ if (meta && (!/^[0-9a-f]{32}$/.test(meta.generation) || !/^[0-9a-f]{64}$/.test(meta.secret) || ![meta.bytes, meta.count, meta.tip, meta.ino].every(value => Number.isSafeInteger(value) && value >= 0))) meta = undefined;
25
+ const indexInfo = await stat(index).catch((error: any) => { if (error.code === 'ENOENT') return undefined; throw error; });
26
+ if (!meta || !indexInfo || indexInfo.size < meta.count * WIDTH || (meta.ino !== 0 && meta.ino !== (info?.ino ?? 0)) || meta.bytes > (info?.size ?? 0)) {
27
+ meta = { generation: randomBytes(16).toString('hex'), secret: randomBytes(32).toString('hex'), ino: info?.ino ?? 0, bytes: 0, count: 0, tip: 0 };
28
+ await writeFile(index, '', { mode: 0o600 });
29
+ }
30
+ if (meta.ino === 0 && info) meta.ino = info.ino;
31
+ const handle = await open(index, 'a+', 0o600);
32
+ try {
33
+ await handle.truncate(meta.count * WIDTH);
34
+ if (info && info.size > meta.bytes) {
35
+ let offset = meta.bytes;
36
+ let start = offset;
37
+ let fragments: Buffer[] = [];
38
+ for await (const raw of createReadStream(file, { start: offset, end: info.size - 1, highWaterMark: 65536 })) {
39
+ const chunk = raw as Buffer;
40
+ let from = 0;
41
+ for (let at = 0; at < chunk.length; at++) if (chunk[at] === 10) {
42
+ const part = chunk.subarray(from, at);
43
+ fragments.push(part);
44
+ const length = offset + at + 1 - start;
45
+ let cursor = meta.tip + 1;
46
+ const body = Buffer.concat(fragments).toString('utf8');
47
+ try { const value = JSON.parse(body); if (Number.isSafeInteger(value.cursor) && value.cursor > meta.tip) cursor = value.cursor; }
48
+ catch { throw new Error('Unreadable history line'); }
49
+ const entry = Buffer.alloc(WIDTH);
50
+ [start, length, cursor].forEach((value, i) => entry.writeBigUInt64LE(BigInt(value), i * 8));
51
+ await handle.write(entry);
52
+ meta.count++; meta.tip = cursor; meta.bytes = offset + at + 1;
53
+ start = meta.bytes; fragments = []; from = at + 1;
54
+ }
55
+ const rest = chunk.subarray(from);
56
+ fragments.push(rest);
57
+ offset += chunk.length;
58
+ }
59
+ }
60
+ const temporary = `${metadata}.tmp`;
61
+ await writeFile(temporary, JSON.stringify(meta), { mode: 0o600 });
62
+ await rename(temporary, metadata);
63
+ return meta;
64
+ } finally { await handle.close(); }
65
+ }
66
+ return {
67
+ page(sessionId: string, options: { before?: string; limit?: number; maxBytes?: number } = {}) {
68
+ const run = pending.then(async () => {
69
+ const { before, limit = 200 } = options;
70
+ if (!Number.isInteger(limit) || limit < 1 || limit > 500) throw new Error('limit must be between 1 and 500');
71
+ const maxBytes = Math.min(512 * 1024, options.maxBytes ?? 512 * 1024);
72
+ if (maxBytes < 2048) throw new Error('history frame budget too small');
73
+ const meta = await sync();
74
+ const sign = (body: string) => createHmac('sha256', meta.secret).update(body).digest('base64url');
75
+ let position = meta.count, tip = meta.tip;
76
+ if (before !== undefined) {
77
+ if (typeof before !== 'string' || before.length > 4096) throw new HistoryError('invalid_cursor', 'Invalid history cursor');
78
+ try {
79
+ const [body, signature, extra] = before.split('.');
80
+ const value = JSON.parse(Buffer.from(body, 'base64url').toString('utf8'));
81
+ if (value.sessionId !== sessionId) throw new Error();
82
+ if (value.generation !== meta.generation) throw new HistoryError('stale_cursor', 'History generation changed');
83
+ const expected = Buffer.from(sign(body)); const received = Buffer.from(signature ?? '');
84
+ if (extra || expected.length !== received.length || !timingSafeEqual(expected, received)) throw new Error();
85
+ if (!Number.isSafeInteger(value.position) || value.position < 0 || value.position > meta.count || !Number.isSafeInteger(value.tip) || value.tip < 0 || value.tip > meta.tip) throw new Error();
86
+ position = value.position; tip = value.tip;
87
+ } catch (error) { if (error instanceof HistoryError) throw error; throw new HistoryError('invalid_cursor', 'Invalid history cursor'); }
88
+ }
89
+ const items: HistoryItem[] = [];
90
+ let bytes = 1024;
91
+ const idx = await open(index, 'r');
92
+ const timeline = meta.count ? await open(file, 'r') : undefined;
93
+ try {
94
+ while (position > 0 && items.length < limit) {
95
+ const entry = Buffer.alloc(WIDTH);
96
+ if ((await idx.read(entry, 0, WIDTH, (position - 1) * WIDTH)).bytesRead !== WIDTH) throw new Error('Incomplete history index');
97
+ const [offset, length, cursor] = [0, 8, 16].map(at => Number(entry.readBigUInt64LE(at)));
98
+ let item: HistoryItem;
99
+ if (length > maxBytes - 1024) item = { cursor, oversized: { bytes: length } };
100
+ else {
101
+ if (bytes + length > maxBytes) break;
102
+ const data = Buffer.alloc(length);
103
+ if ((await timeline!.read(data, 0, length, offset)).bytesRead !== length) throw new Error('History changed during read');
104
+ item = { ...JSON.parse(data.toString('utf8')), cursor };
105
+ }
106
+ const size = Buffer.byteLength(JSON.stringify(item)) + 1;
107
+ if (bytes + size > maxBytes) break;
108
+ items.unshift(item); bytes += size; position--;
109
+ }
110
+ } finally { await idx.close(); await timeline?.close(); }
111
+ const body = Buffer.from(JSON.stringify({ sessionId, generation: meta.generation, position, tip })).toString('base64url');
112
+ return { generation: meta.generation, items, hasOlder: position > 0, ...(position > 0 ? { olderCursor: `${body}.${sign(body)}` } : {}), tipCursor: tip };
113
+ });
114
+ pending = run.catch(() => {});
115
+ return run;
116
+ },
117
+ };
118
+ }
package/src/index.ts CHANGED
@@ -3,3 +3,10 @@ export { createDaemonServer, ERROR } from './server.js';
3
3
  export type { DaemonConnection, DaemonServer, SessionSummary } from './server.js';
4
4
  export { createStore } from './store.js';
5
5
  export type { SessionRecord, SessionStatus, Store } from './store.js';
6
+ export { createScheduleStore, PROMPT_CHARS, SCHEDULE_ID, SCHEDULE_VERSION } from './schedules.js';
7
+ export type { ScheduleRecord, ScheduleStore } from './schedules.js';
8
+ export { createScheduler, duration, renderPrompt, SCHEDULE_GRACE_MS, SCHEDULE_TICK_MS } from './scheduler.js';
9
+ export type { ScheduleDelivery, Scheduler } from './scheduler.js';
10
+ export { attachmentLimits, attachmentName, createAttachmentStore, readAttachmentConfig, sniffMimeType } from './attachments.js';
11
+ export type { AttachmentReader, AttachmentRuntime, AttachmentStore, Principal } from './attachments.js';
12
+ export { createDiskGuard, isDiskError } from './disk.js';
@@ -0,0 +1,283 @@
1
+ import { createHash, randomBytes } from 'node:crypto';
2
+ import { mkdir, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
3
+ import path from 'node:path';
4
+ import { replaceFile } from './lock.js';
5
+ import { RpcError } from './rpc-error.js';
6
+
7
+ /**
8
+ * The lifecycle journal (docs/protocol/alp-json-rpc-v1.md §12.7): one record per mutation of a session's
9
+ * native conversation (fork, rewind; later reload and live configure), keyed by resource, operation and
10
+ * the client's requestId. A mutation crosses the native runtime and alpd's own files, which no rename
11
+ * makes atomic, so it is journaled before the native step and replayed from the journal:
12
+ *
13
+ * prepared → written before the native step; nothing native happened yet, or it is in flight.
14
+ * applied → the native step answered; `native` holds what it made. alpd's own commit may follow.
15
+ * committed → alpd's commit is on disk; `result` answers every repeat of the request.
16
+ * failed → the native runtime refused it for certain; `error` answers every repeat.
17
+ * unknown → the native runtime may or may not have acted (a crash or a lost answer after prepared).
18
+ *
19
+ * A start of alpd turns `prepared` into `unknown` (never sends the native step again) and rolls `applied`
20
+ * forward with the operation's commit, which must therefore be idempotent. Refusals before `prepared`
21
+ * (validation, busy, stale) record nothing, so the same requestId may be tried again. As the rest of
22
+ * alpd's store, a resolved write survives a crash of alpd, not a power loss (no fsync).
23
+ */
24
+
25
+ export type LifecycleState = 'prepared' | 'applied' | 'committed' | 'failed' | 'unknown';
26
+
27
+ export type LifecycleEntry<Plan = any, Native = any, Result = any> = {
28
+ version: 1;
29
+ key: string;
30
+ /** The resource the operation changes or reads: a root session id. */
31
+ resource: string;
32
+ operation: string;
33
+ requestId: string;
34
+ /** A digest of the request; another payload under the same requestId is a conflict. */
35
+ fingerprint: string;
36
+ /** Unique attempt, so a retained completion witness cannot match a reused journal key. */
37
+ attemptId?: string;
38
+ state: LifecycleState;
39
+ /** Startup has observed this unknown outcome. It remains unknown for retries and audit. */
40
+ recoverySeenAt?: string;
41
+ /** What prepare decided; everything commit needs, so a restart can roll the operation forward. */
42
+ plan: Plan;
43
+ native?: Native;
44
+ result?: Result;
45
+ error?: { code: number; message: string; data?: unknown };
46
+ createdAt: string;
47
+ updatedAt: string;
48
+ };
49
+
50
+ /** Terminal entries are kept this long after their last write, as prompt receipts are (§10). */
51
+ export const LIFECYCLE_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
52
+
53
+ const keyOf = (resource: string, operation: string, requestId: string) =>
54
+ createHash('sha256').update(JSON.stringify(['lifecycle', resource, operation, requestId])).digest('hex');
55
+
56
+ export type LifecycleJournal = ReturnType<typeof createLifecycleJournal>;
57
+
58
+ export function createLifecycleJournal(directory: string) {
59
+ const writes = new Map<string, Promise<void>>();
60
+ let ready: Promise<void> | undefined;
61
+ const prepare = () => ready ??= mkdir(directory, { recursive: true, mode: 0o700 }).then(() => {}, error => { ready = undefined; throw error; });
62
+ const file = (key: string) => path.join(directory, `${key}.json`);
63
+
64
+ async function read(name: string): Promise<LifecycleEntry | undefined> {
65
+ let text: string;
66
+ try { text = await readFile(path.join(directory, name), 'utf8'); }
67
+ catch (error: any) { if (error?.code === 'ENOENT') return undefined; throw error; }
68
+ const entry = JSON.parse(text);
69
+ if (entry?.version !== 1 || typeof entry.key !== 'string' || typeof entry.state !== 'string') throw new Error(`unreadable lifecycle entry ${name}`);
70
+ return entry;
71
+ }
72
+
73
+ return {
74
+ keyOf,
75
+ async get(resource: string, operation: string, requestId: string): Promise<LifecycleEntry | undefined> {
76
+ const key = keyOf(resource, operation, requestId);
77
+ await writes.get(key);
78
+ await prepare();
79
+ return read(`${key}.json`);
80
+ },
81
+ /** Writes an entry atomically; writes of one key never land out of order. */
82
+ put(entry: LifecycleEntry) {
83
+ const body = JSON.stringify({ ...entry, updatedAt: new Date().toISOString() });
84
+ const next = (writes.get(entry.key) ?? Promise.resolve()).catch(() => {}).then(prepare).then(async () => {
85
+ const temporary = `${file(entry.key)}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
86
+ try {
87
+ await writeFile(temporary, body, { mode: 0o600 });
88
+ await replaceFile(temporary, file(entry.key));
89
+ } catch (error) {
90
+ await rm(temporary, { force: true }).catch(() => {});
91
+ throw error;
92
+ }
93
+ });
94
+ writes.set(entry.key, next);
95
+ void next.finally(() => { if (writes.get(entry.key) === next) writes.delete(entry.key); }).catch(() => {});
96
+ return next;
97
+ },
98
+ /** Every readable entry; an unreadable one is skipped (and named), never deleted. */
99
+ async list(onUnreadable?: (name: string, error: unknown) => void): Promise<LifecycleEntry[]> {
100
+ await prepare();
101
+ const entries: LifecycleEntry[] = [];
102
+ for (const name of await readdir(directory)) {
103
+ if (!name.endsWith('.json')) continue;
104
+ try { const entry = await read(name); if (entry) entries.push(entry); }
105
+ catch (error) { onUnreadable?.(name, error); }
106
+ }
107
+ return entries;
108
+ },
109
+ /** Removes terminal entries not written for `maxAgeMs`, and temporary files a crash left (only at start). */
110
+ async prune(maxAgeMs = LIFECYCLE_RETENTION_MS, { temporaries = false } = {}) {
111
+ await prepare();
112
+ const now = Date.now();
113
+ for (const name of await readdir(directory)) {
114
+ const target = path.join(directory, name);
115
+ if (name.endsWith('.tmp')) { if (temporaries) await rm(target, { force: true }); continue; }
116
+ if (!name.endsWith('.json')) continue;
117
+ const entry = await read(name).catch(() => undefined);
118
+ if (!entry || !['committed', 'failed', 'unknown'].includes(entry.state)) continue;
119
+ const info = await stat(target).catch(() => undefined);
120
+ if (info && now - info.mtimeMs > maxAgeMs) await rm(target, { force: true });
121
+ }
122
+ },
123
+ async flush() { await Promise.all([...writes.values()].map(write => write.catch(() => {}))); },
124
+ };
125
+ }
126
+
127
+ /** A failure the journal keeps as the answer of every repeat: its code, message and data. */
128
+ const answerOf = (error: unknown): { code: number; message: string; data?: unknown } =>
129
+ error instanceof RpcError ? { code: error.code, message: error.message, ...(error.data !== undefined ? { data: error.data } : {}) }
130
+ : { code: 1000, message: error instanceof Error ? error.message : String(error) };
131
+
132
+ export const outcomeUnknown = (operation: string, requestId: string) =>
133
+ new RpcError(1004, `alpd cannot tell whether ${operation} ${requestId} reached the runtime; check the session, then try again with a new requestId`, { reason: 'outcome_unknown' });
134
+
135
+ export type LifecycleSteps<Plan, Native, Result> = {
136
+ /** Validates and decides; may refuse (nothing is recorded). Runs inside the resource's queue. */
137
+ prepare(): Promise<Plan>;
138
+ /** The native step; a thrown error with `outcomeUnknown: true` records unknown, any other records failed. */
139
+ apply(plan: Plan): Promise<Native>;
140
+ /** alpd's own, idempotent commit from the entry alone (a restart replays it). */
141
+ commit(entry: LifecycleEntry<Plan, Native, Result>): Promise<Result>;
142
+ /** How a repeat answers from a committed entry (e.g. with a fresh session summary). */
143
+ repeat?(entry: LifecycleEntry<Plan, Native, Result>): Result | Promise<Result>;
144
+ };
145
+
146
+ /**
147
+ * Runs journaled operations: one at a time per resource, at most once per (resource, operation,
148
+ * requestId). The seam later lifecycle operations (live configure, reload) reuse with their own steps.
149
+ */
150
+ export function createLifecycle(journal: LifecycleJournal, {
151
+ crashPoint = (_name: string) => {}, completed = async (_entry: LifecycleEntry): Promise<{ result: any } | undefined> => undefined,
152
+ }: { crashPoint?: (name: string) => void; completed?: (entry: LifecycleEntry) => Promise<{ result: any } | undefined> } = {}) {
153
+ const queues = new Map<string, Promise<unknown>>();
154
+ const inflight = new Map<string, Promise<unknown>>();
155
+
156
+ /** Runs `work` after every earlier operation of `resource` settled. */
157
+ function serial<T>(resource: string, work: () => Promise<T>): Promise<T> {
158
+ const run = (queues.get(resource) ?? Promise.resolve()).catch(() => {}).then(work);
159
+ queues.set(resource, run);
160
+ void run.finally(() => { if (queues.get(resource) === run) queues.delete(resource); }).catch(() => {});
161
+ return run;
162
+ }
163
+
164
+ async function run<Plan, Native, Result>(
165
+ request: { resource: string; operation: string; requestId: string; fingerprint: string },
166
+ steps: LifecycleSteps<Plan, Native, Result>,
167
+ ): Promise<{ result: Result; duplicate: boolean; entry: LifecycleEntry<Plan, Native, Result> }> {
168
+ const key = journal.keyOf(request.resource, request.operation, request.requestId);
169
+ const earlier = inflight.get(key);
170
+ if (earlier) await earlier.catch(() => {});
171
+ const attempt = serial(request.resource, async () => {
172
+ let entry: LifecycleEntry<Plan, Native, Result> | undefined;
173
+ try { entry = await journal.get(request.resource, request.operation, request.requestId); }
174
+ catch (error) { throw new RpcError(1000, `alpd cannot read the journal of ${request.operation} ${request.requestId}`, { reason: 'persistence_failed' }); }
175
+ if (entry) {
176
+ if (entry.fingerprint !== request.fingerprint) throw new RpcError(1004, `${request.operation} ${request.requestId} was already requested with other parameters`, { reason: 'key_conflict' });
177
+ if (entry.state === 'committed') return { result: steps.repeat ? await steps.repeat(entry) : entry.result as Result, duplicate: true, entry };
178
+ if (entry.state === 'failed') throw new RpcError(entry.error?.code ?? 1000, entry.error?.message ?? `${request.operation} failed`, entry.error?.data);
179
+ // A commit that failed earlier finishes now; this is its first answer.
180
+ if (entry.state === 'applied') {
181
+ const saved = await completed(entry);
182
+ const done = await commit(entry, steps, saved);
183
+ return { result: done.result as Result, duplicate: saved !== undefined, entry: done };
184
+ }
185
+ throw outcomeUnknown(request.operation, request.requestId);
186
+ }
187
+ // A failed store commit is not success. Keep later native mutations behind it until a
188
+ // retry/start finishes it; a durable receipt permits progress despite a lost final marker.
189
+ for (const pending of await journal.list()) {
190
+ if (pending.resource === request.resource && ['configure', 'rewind'].includes(pending.operation) && pending.state === 'applied' && !await completed(pending)) {
191
+ throw new RpcError(1000, `alpd must finish ${pending.operation} ${pending.requestId} before another conversation mutation`, { reason: 'persistence_failed' });
192
+ }
193
+ }
194
+ const plan = await steps.prepare();
195
+ const now = new Date().toISOString();
196
+ entry = { version: 1, key, ...request, attemptId: randomBytes(16).toString('hex'), state: 'prepared', plan, createdAt: now, updatedAt: now };
197
+ try { await journal.put(entry); }
198
+ catch (error) { throw new RpcError(1000, `alpd could not record ${request.operation} ${request.requestId}; nothing was changed`, { reason: 'persistence_failed' }); }
199
+ crashPoint(`${request.operation}.after-prepared`);
200
+ let native: Native;
201
+ try {
202
+ native = await steps.apply(plan);
203
+ } catch (error: any) {
204
+ const unknown = error?.outcomeUnknown === true;
205
+ entry = { ...entry, state: unknown ? 'unknown' : 'failed', ...(unknown ? {} : { error: answerOf(error) }) };
206
+ await journal.put(entry).catch(() => {});
207
+ if (unknown) throw outcomeUnknown(request.operation, request.requestId);
208
+ throw error;
209
+ }
210
+ entry = { ...entry, state: 'applied', native };
211
+ try { await journal.put(entry); }
212
+ catch {
213
+ // The native step happened but its record did not: what a repeat finds is `prepared`, answered unknown.
214
+ throw outcomeUnknown(request.operation, request.requestId);
215
+ }
216
+ crashPoint(`${request.operation}.after-applied`);
217
+ const done = await commit(entry, steps);
218
+ return { result: done.result as Result, duplicate: false, entry: done };
219
+ });
220
+ inflight.set(key, attempt);
221
+ void attempt.finally(() => { if (inflight.get(key) === attempt) inflight.delete(key); }).catch(() => {});
222
+ return attempt;
223
+ }
224
+
225
+ async function commit<Plan, Native, Result>(entry: LifecycleEntry<Plan, Native, Result>, steps: Pick<LifecycleSteps<Plan, Native, Result>, 'commit'>, saved?: { result: Result }) {
226
+ let result: Result;
227
+ try {
228
+ if (!saved && !entry.attemptId && ['configure', 'rewind'].includes(entry.operation)) {
229
+ // Legacy applied entries have no atomic completion witness. A strictly later
230
+ // applied/committed attempt proves a newer native operation ran; replaying this
231
+ // ambiguous older commit could undo it. Keep it unfinished, never invent success.
232
+ const newer = (await journal.list()).some(other => other.resource === entry.resource && other.key !== entry.key
233
+ && other.createdAt > entry.createdAt && ['applied', 'committed'].includes(other.state));
234
+ if (newer) throw new RpcError(1000, `alpd cannot safely replay ${entry.operation} ${entry.requestId} over a later conversation mutation`, { reason: 'persistence_failed' });
235
+ }
236
+ result = saved ? saved.result : await steps.commit(entry);
237
+ }
238
+ catch (error) {
239
+ if (error instanceof RpcError) throw error;
240
+ throw new RpcError(1000, `alpd could not finish ${entry.operation} ${entry.requestId}; it finishes when tried again or when alpd starts`, { reason: 'persistence_failed' });
241
+ }
242
+ crashPoint(`${entry.operation}.before-committed`);
243
+ const done = { ...entry, state: 'committed' as const, result };
244
+ await journal.put(done).catch(() => {});
245
+ crashPoint(`${entry.operation}.after-committed`);
246
+ return done;
247
+ }
248
+
249
+ return {
250
+ run,
251
+ serial,
252
+ /**
253
+ * At start, before any request: `prepared` becomes `unknown` (the native step is never sent again),
254
+ * and unknown outcomes are durably observed once, without claiming success or replaying a commit.
255
+ * `applied` rolls forward through the operation's commit (left `applied` when that fails, to be
256
+ * finished by a repeat or the next start; such entries are answered).
257
+ */
258
+ async recover(commits: Record<string, (entry: LifecycleEntry) => Promise<unknown>>, log?: (message: string, fields: Record<string, unknown>) => void) {
259
+ const entries = await journal.list((name, error) => log?.(`unreadable lifecycle entry ${name}`, { error }));
260
+ const unfinished: LifecycleEntry[] = [];
261
+ for (const entry of entries) {
262
+ if (entry.state === 'prepared' || (entry.state === 'unknown' && !entry.recoverySeenAt)) {
263
+ try {
264
+ await journal.put({ ...entry, state: 'unknown', recoverySeenAt: new Date().toISOString() });
265
+ log?.(`${entry.operation} ${entry.requestId} of ${entry.resource} may or may not have reached the runtime`, { code: 'ALPD_LIFECYCLE_UNKNOWN', operation: entry.operation, resource: entry.resource, requestId: entry.requestId });
266
+ } catch (error) {
267
+ // No commit or native step was attempted; the next start may retry the observation.
268
+ log?.(`could not record unknown ${entry.operation} ${entry.requestId} of ${entry.resource}`, { code: 'ALPD_LIFECYCLE_OBSERVE_FAILED', error });
269
+ }
270
+ } else if (entry.state === 'applied') {
271
+ const committer = commits[entry.operation];
272
+ if (!committer) continue;
273
+ await serial(entry.resource, async () => commit(entry, { commit: committer }, await completed(entry))).catch(error => {
274
+ unfinished.push(entry);
275
+ log?.(`could not finish ${entry.operation} ${entry.requestId} of ${entry.resource}`, { code: 'ALPD_LIFECYCLE_ROLLFORWARD_FAILED', error });
276
+ });
277
+ }
278
+ }
279
+ /** Entries still applied: their resources wait for a repeat to finish them. */
280
+ return unfinished;
281
+ },
282
+ };
283
+ }
package/src/main.ts CHANGED
@@ -1,18 +1,21 @@
1
1
  import { spawn } from 'node:child_process';
2
- import { openSync, writeSync } from 'node:fs';
2
+ import { fstatSync, openSync, writeSync } from 'node:fs';
3
3
  import { mkdir, open, readFile, rename, stat, unlink, utimes, writeFile } from 'node:fs/promises';
4
4
  import path from 'node:path';
5
5
  import { fileURLToPath } from 'node:url';
6
6
  import templates from 'alp:templates';
7
7
  import { alpHome, daemonPaths, assertPrivateDirectory, PROTOCOL_VERSION, withDaemonLifecycle } from '@anhlp/alp-client/index';
8
- import { createAlpRuntime, reclaimCopies, reclaimWorktrees } from '@anhlp/alp-runtime/index';
8
+ import { attachmentStageDir, createAlpRuntime, liveProbes, ModelCatalog, reclaimCopies, reclaimWorktrees, setActiveCatalog } from '@anhlp/alp-runtime/index';
9
9
  import { createDaemonServer } from './server.js';
10
10
  import { acquireLock, heartbeat, releaseLock, updateLock } from './lock.js';
11
11
  import { createStore } from './store.js';
12
+ import { createDiskGuard, guardOutput, isDiskError } from './disk.js';
13
+ import { readAttachmentConfig } from './attachments.js';
12
14
  import { validateUserSettings } from '@anhlp/alp-core/validation';
13
15
  import { clearRestoredMarker, readRestoredMarker, recoverInterruptedRestore } from '@anhlp/alp-core/backup';
14
16
  import { migrateState } from '@anhlp/alp-core/migrations';
15
17
  import { createLogger } from '@anhlp/alp-core/log';
18
+ import { selfCommand, selfEntry } from '@anhlp/alp-core/packaged';
16
19
 
17
20
  declare const __ALP_VERSION__: string;
18
21
  const VERSION = typeof __ALP_VERSION__ === 'string' ? __ALP_VERSION__ : '0.0.0-dev';
@@ -37,7 +40,8 @@ async function detach(home: string) {
37
40
  await assertPrivateDirectory(path.dirname(log), { create: true });
38
41
  await rotate(log);
39
42
  const output = await open(log, 'a', 0o600);
40
- const child = spawn(process.execPath, [fileURLToPath(import.meta.url)], {
43
+ const self = selfCommand('daemon', { script: fileURLToPath(import.meta.url) });
44
+ const child = spawn(self.command, self.args, {
41
45
  detached: true,
42
46
  stdio: ['ignore', output.fd, output.fd, 'ipc'],
43
47
  env: process.env,
@@ -75,7 +79,7 @@ async function detach(home: string) {
75
79
  * log at start as the detached launcher does, then writes its output there itself. The
76
80
  * manager's own file keeps only what Node prints when it dies.
77
81
  */
78
- async function serviceLog(home: string) {
82
+ async function serviceLog(home: string, onError: (error: unknown) => void) {
79
83
  await assertPrivateDirectory(home, { create: true });
80
84
  const { log } = daemonPaths(home);
81
85
  await assertPrivateDirectory(path.dirname(log), { create: true });
@@ -83,7 +87,7 @@ async function serviceLog(home: string) {
83
87
  const fd = openSync(log, 'a', 0o600);
84
88
  for (const stream of [process.stdout, process.stderr]) {
85
89
  stream.write = ((chunk: string | Uint8Array, encoding?: unknown, callback?: unknown) => {
86
- try { if (typeof chunk === 'string') writeSync(fd, chunk); else writeSync(fd, chunk); } catch {}
90
+ try { if (typeof chunk === 'string') writeSync(fd, chunk); else writeSync(fd, chunk); } catch (error) { onError(error); }
87
91
  const done = typeof encoding === 'function' ? encoding : callback;
88
92
  if (typeof done === 'function') done();
89
93
  return true;
@@ -207,16 +211,23 @@ async function run(home: string) {
207
211
  const settings = await userSettings(home);
208
212
  const runtime = createAlpRuntime({
209
213
  templates, runLogDir, worktreeDir, copyDir, boardDir: path.join(home, 'boards'), libraryDir: home,
210
- recallFile: path.join(home, 'state', 'recall.json'), pauseFile: path.join(home, 'state', 'pause.json'), liveFile: path.join(home, 'state', 'live.json'),
214
+ // Read-only copies of attached files for the sessions' tools (§12.6); not on Windows, as the store.
215
+ ...(process.platform !== 'win32' ? { attachmentStageDir: attachmentStageDir(home) } : {}),
216
+ assignmentResultFile: path.join(home, 'state', 'assignment-results.json'), recallFile: path.join(home, 'state', 'recall.json'), pauseFile: path.join(home, 'state', 'pause.json'), liveFile: path.join(home, 'state', 'live.json'),
211
217
  autoResume: settings?.limits?.autoResume !== false, recoveryResume: settings?.recovery?.autoResume !== false && !opened.restored, previousExit: exit,
212
218
  });
213
- const store = createStore(path.join(home, 'state'));
219
+ // A full disk pauses ALP's work instead of stopping alpd (t-2831).
220
+ const disk = createDiskGuard({ home, runtime, log, ...(Number(process.env.ALP_DISK_CHECK_MS) > 0 ? { intervalMs: Number(process.env.ALP_DISK_CHECK_MS) } : {}) });
221
+ diskReport = error => { disk.report(error); };
222
+ const store = createStore(path.join(home, 'state'), { onWriteError: error => { disk.report(error); } });
214
223
  let stopping: Promise<void> | undefined;
215
224
  const shutdown = (code = 0) => {
216
225
  stopping ??= (async () => {
217
226
  const force = setTimeout(() => process.exit(code), 10_000);
218
227
  force.unref();
219
228
  clearInterval(beat);
229
+ disk.stop();
230
+ modelCatalog?.stop();
220
231
  await server.close().catch(() => {});
221
232
  await runtime.shutdown().catch(() => {});
222
233
  await store.flush();
@@ -228,7 +239,15 @@ async function run(home: string) {
228
239
  })();
229
240
  return stopping;
230
241
  };
231
- const server = createDaemonServer({ runtime, socketPath: socket, version: VERSION, store, runLogDir, previousExit: exit, home, templates, onShutdown: () => void shutdown() });
242
+ // The operator may lower the attachment limits (never raise them): <ALP_HOME>/attachments.json.
243
+ const attachmentConfig = await readAttachmentConfig(home);
244
+ for (const problem of attachmentConfig.problems) log.warn(problem, { code: 'ALP_ATTACHMENT_CONFIG' });
245
+ // The live model catalog (t-e5ee): static rows at once, provider lists in the background, every 6 h.
246
+ // ALP_MODEL_CATALOG=static keeps the static rows only (tests, offline hosts).
247
+ const modelCatalog = process.env.ALP_MODEL_CATALOG === 'static' ? undefined : new ModelCatalog({ home, probes: liveProbes() });
248
+ setActiveCatalog(modelCatalog);
249
+ void modelCatalog?.start().catch(() => {});
250
+ const server = createDaemonServer({ runtime, socketPath: socket, version: VERSION, store, runLogDir, previousExit: exit, home, templates, attachmentOptions: { limits: attachmentConfig.limits }, modelCatalog, onShutdown: () => void shutdown() });
232
251
  const beat = setInterval(() => {
233
252
  void heartbeat(home).then(owned => { if (!owned) void shutdown(1); });
234
253
  const now = new Date();
@@ -236,8 +255,9 @@ async function run(home: string) {
236
255
  }, 30_000);
237
256
  beat.unref();
238
257
  for (const signal of ['SIGINT', 'SIGTERM'] as const) process.on(signal, () => void shutdown());
239
- process.on('uncaughtException', error => { log.error('uncaught exception; alpd stops', { code: 'ALP_FATAL', error }); void shutdown(1); });
240
- process.on('unhandledRejection', error => { log.error('unhandled rejection; alpd stops', { code: 'ALP_FATAL', error }); void shutdown(1); });
258
+ // A write the disk refused is no reason to stop: the disk guard pauses work until it takes writes again.
259
+ process.on('uncaughtException', error => { if (disk.report(error)) return; log.error('uncaught exception; alpd stops', { code: 'ALP_FATAL', error }); void shutdown(1); });
260
+ process.on('unhandledRejection', error => { if (disk.report(error)) return; log.error('unhandled rejection; alpd stops', { code: 'ALP_FATAL', error }); void shutdown(1); });
241
261
  phase = 'listen';
242
262
  try {
243
263
  await server.listen();
@@ -250,22 +270,27 @@ async function run(home: string) {
250
270
  await updateLock(home, { ...lock, ready: true });
251
271
  // Clients that cannot locate alpd themselves (the Paseo plugin) start it from here next time.
252
272
  const { install } = daemonPaths(home);
253
- await writeFile(`${install}.tmp`, JSON.stringify({ entry: fileURLToPath(import.meta.url), version: VERSION }), { mode: 0o600 })
273
+ await writeFile(`${install}.tmp`, JSON.stringify({ entry: selfEntry(fileURLToPath(import.meta.url)), version: VERSION }), { mode: 0o600 })
254
274
  .then(() => rename(`${install}.tmp`, install))
255
275
  .catch(error => log.warn('could not record alpd\'s location', { code: 'ALP_INSTALL_RECORD_FAILED', error }));
256
276
  if (opened.restored) await clearRestoredMarker(home).catch(error => log.warn('could not clear the restore marker', { code: 'ALP_STATE_RESTORED', error }));
277
+ disk.start();
257
278
  if (process.connected) process.send?.('alpd.ready');
258
279
  log.info(`alpd ${VERSION} ready on ${socket} (pid ${process.pid})`, { event: 'ready', version: VERSION, pid: process.pid });
259
280
  }
260
281
 
261
282
  const home = alpHome();
283
+ /** Where a failed write to alpd's own output goes once the disk guard exists. */
284
+ let diskReport = (_error: unknown) => {};
285
+ // Before anything logs: a log write the full disk refused must not end alpd (t-2831).
286
+ guardOutput(error => { if (isDiskError(error)) diskReport(error); }, { fstatSync, writeSync });
262
287
  try {
263
288
  if (process.argv.includes('--detach')) await detach(home);
264
289
  else {
265
290
  // A direct foreground/login invocation is an explicit start. Do this before
266
291
  // admission registration, so a stop published during startup is preserved.
267
292
  if (!process.connected) await unlink(path.join(home, 'state', 'alpd.held')).catch(() => {});
268
- if (process.argv.includes('--service')) await serviceLog(home);
293
+ if (process.argv.includes('--service')) await serviceLog(home, error => { if (isDiskError(error)) diskReport(error); });
269
294
  if (process.connected) await run(home);
270
295
  else {
271
296
  // Retain admission through readiness even if the requesting service client