@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
package/dist/store.d.ts CHANGED
@@ -1,5 +1,16 @@
1
1
  import type { Envelope, SessionSnapshot, SessionSpec } from '@anhlp/alp-runtime/index';
2
2
  import type { SessionError, SessionStatus } from '@anhlp/alp-protocol/session';
3
+ import type { TurnAttention } from '@anhlp/alp-protocol/events';
4
+ import type { ConversationBranch, ForkProvenance, NativeBase } from '@anhlp/alp-protocol/session';
5
+ /** A branch a rewind set aside (§12.7): its public description, the native conversation and where its timeline lies. */
6
+ export type StoredBranch = ConversationBranch & {
7
+ /** The native conversation the root continued before the rewind: never deleted, so the branch stays recoverable. */
8
+ threadId: string;
9
+ base?: NativeBase;
10
+ /** The first discarded cursor, and the rewind's marker cursor (the branch holds what lay between). */
11
+ cut: number;
12
+ marker: number;
13
+ };
3
14
  /**
4
15
  * alpd's durable state (plans/reference/ALPD.md §5, §66): one JSON record per session,
5
16
  * written atomically, one append-only JSONL timeline per tree, and one receipt per
@@ -20,6 +31,30 @@ export type SessionRecord = {
20
31
  title?: string;
21
32
  /** Set aside by the user: closed, and listed only when asked (ALPD §61). */
22
33
  archived?: boolean;
34
+ /** A root's last turn that ended unseen, until a client acknowledges it or another turn starts (Paseo's requiresAttention). */
35
+ attention?: TurnAttention;
36
+ /** Claude: the conversation `session.threadId` is made from on its first prompt, after a fork or rewind (§12.7). */
37
+ base?: NativeBase;
38
+ /** Where this root was forked from (§12.7). */
39
+ forkedFrom?: ForkProvenance;
40
+ /** Stable creation ownership; current native binding/title may change after a fork. */
41
+ forkAttempt?: {
42
+ key: string;
43
+ attemptId?: string;
44
+ createdAt: string;
45
+ fingerprint: string;
46
+ };
47
+ /** Branches rewinds set aside, oldest first (§12.7). */
48
+ branches?: StoredBranch[];
49
+ /** Atomic proof of completed conversation commits whose journal marker may be missing. */
50
+ lifecycleCommits?: Record<string, {
51
+ operation: string;
52
+ requestId: string;
53
+ createdAt: string;
54
+ fingerprint: string;
55
+ attemptId?: string;
56
+ result: any;
57
+ }>;
23
58
  createdAt: string;
24
59
  updatedAt: string;
25
60
  };
@@ -60,6 +95,8 @@ export type StoreHealth = {
60
95
  };
61
96
  export type Store = ReturnType<typeof createStore>;
62
97
  export declare function createStore(root: string): {
98
+ /** The state directory this store keeps its files in. */
99
+ root: string;
63
100
  put(record: SessionRecord): Promise<void>;
64
101
  receipt(key: string): Promise<Receipt | UnreadableReceipt | undefined>;
65
102
  putReceipt(key: string, receipt: Receipt): Promise<void>;
@@ -79,8 +116,39 @@ export declare function createStore(root: string): {
79
116
  pruneReceipts(maxAgeMs: number, { temporaries }?: {
80
117
  temporaries?: boolean | undefined;
81
118
  }): Promise<void>;
119
+ /** Authoritative record after queued writes, including failed writes (which do not prove completion). */
120
+ get(id: string): Promise<SessionRecord | undefined>;
82
121
  list(): Promise<SessionRecord[]>;
83
122
  append(rootId: string, envelope: Envelope): Promise<void>;
123
+ history(rootId: string, sessionId: string, options?: {
124
+ before?: string;
125
+ limit?: number;
126
+ maxBytes?: number;
127
+ }): Promise<{
128
+ tipCursor: number;
129
+ olderCursor?: string | undefined;
130
+ generation: string;
131
+ items: import("./history.js").HistoryItem[];
132
+ hasOlder: boolean;
133
+ }>;
134
+ /**
135
+ * Rewinds a tree's timeline (§12.7), idempotently: the whole timeline moves to the branch file
136
+ * `<root>.branch-<id>.jsonl`, and the root's timeline becomes its lines before `cut`, the root's own
137
+ * session lifecycle lines after it (opened, updated, closed: not conversation), `marker`, and any line
138
+ * whose cursor follows the marker's, in cursor order. Runs in
139
+ * the tree's append queue, so no append lands in between. A crash leaves the old timeline, or the
140
+ * branch and the new one beside it (finished by the next call); the history index is rebuilt with a
141
+ * new generation, so every older history cursor is stale.
142
+ */
143
+ rewind(rootId: string, { cut, branchId, marker }: {
144
+ cut: number;
145
+ branchId: string;
146
+ marker: Envelope;
147
+ }): Promise<void>;
148
+ /** Writes a new tree's whole timeline at once (a fork's, §12.7); written again whole by a repeat. */
149
+ createTimeline(rootId: string, envelopes: Envelope[]): Promise<void>;
150
+ /** The timeline of a branch a rewind set aside; empty when it is not there. */
151
+ branchTimeline(rootId: string, branchId: string): Promise<Envelope[]>;
84
152
  timeline(rootId: string): Promise<Envelope[]>;
85
153
  /**
86
154
  * Waits for the queued writes of these records and timelines, and names those that
@@ -102,7 +170,7 @@ export declare function createStore(root: string): {
102
170
  /** How many records, receipts and timelines are failed now: a later successful write clears a record, a lost timeline line never clears. */
103
171
  failing(): number;
104
172
  health(): StoreHealth;
105
- /** Removes a whole tree: its records and its timeline. */
173
+ /** Removes a whole tree: its records, its timeline and the branches rewinds set aside. */
106
174
  remove(rootId: string, ids: string[]): Promise<void>;
107
175
  flush(): Promise<void>;
108
176
  };
package/dist/store.js CHANGED
@@ -1,5 +1,6 @@
1
1
  // packages/daemon/src/store.ts
2
- import { appendFile, mkdir, open, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
2
+ import { createHistoryIndex } from "./history.js";
3
+ import { appendFile, mkdir, open, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
3
4
  import { replaceFile } from "./lock.js";
4
5
  import { randomBytes } from "node:crypto";
5
6
  import path from "node:path";
@@ -11,6 +12,7 @@ var TAIL_CHUNK = 64 * 1024;
11
12
  function createStore(root) {
12
13
  const sessionsDir = path.join(root, "sessions");
13
14
  const timelineDir = path.join(root, "timeline");
15
+ const historyIndexes = /* @__PURE__ */ new Map();
14
16
  const receiptsDir = path.join(root, "receipts");
15
17
  const writes = /* @__PURE__ */ new Map();
16
18
  const appends = /* @__PURE__ */ new Map();
@@ -114,7 +116,10 @@ function createStore(root) {
114
116
  return envelopes;
115
117
  }
116
118
  const receiptFile = (key) => path.join(receiptsDir, `${fileName(key)}.json`);
119
+ const branchFile = (rootId, branchId) => path.join(timelineDir, `${fileName(rootId)}.branch-${fileName(branchId)}.jsonl`);
117
120
  return {
121
+ /** The state directory this store keeps its files in. */
122
+ root,
118
123
  put(record) {
119
124
  const file = path.join(sessionsDir, `${fileName(record.id)}.json`);
120
125
  const body = JSON.stringify(record);
@@ -185,6 +190,17 @@ function createStore(root) {
185
190
  }
186
191
  }
187
192
  },
193
+ /** Authoritative record after queued writes, including failed writes (which do not prove completion). */
194
+ async get(id) {
195
+ await writes.get(id)?.catch(() => {
196
+ });
197
+ try {
198
+ return JSON.parse(await readFile(path.join(sessionsDir, `${fileName(id)}.json`), "utf8"));
199
+ } catch (error) {
200
+ if (error?.code === "ENOENT") return void 0;
201
+ throw error;
202
+ }
203
+ },
188
204
  async list() {
189
205
  await prepare();
190
206
  const records = [];
@@ -212,6 +228,93 @@ function createStore(root) {
212
228
  await appendFile(file, line, { mode: 384 });
213
229
  }, true, { rootId });
214
230
  },
231
+ async history(rootId, sessionId, options = {}) {
232
+ await prepare();
233
+ await appends.get(rootId);
234
+ let index = historyIndexes.get(rootId);
235
+ if (!index) {
236
+ index = createHistoryIndex(path.join(timelineDir, `${fileName(rootId)}.jsonl`));
237
+ historyIndexes.set(rootId, index);
238
+ }
239
+ return index.page(sessionId, options);
240
+ },
241
+ /**
242
+ * Rewinds a tree's timeline (§12.7), idempotently: the whole timeline moves to the branch file
243
+ * `<root>.branch-<id>.jsonl`, and the root's timeline becomes its lines before `cut`, the root's own
244
+ * session lifecycle lines after it (opened, updated, closed: not conversation), `marker`, and any line
245
+ * whose cursor follows the marker's, in cursor order. Runs in
246
+ * the tree's append queue, so no append lands in between. A crash leaves the old timeline, or the
247
+ * branch and the new one beside it (finished by the next call); the history index is rebuilt with a
248
+ * new generation, so every older history cursor is stale.
249
+ */
250
+ rewind(rootId, { cut, branchId, marker }) {
251
+ const file = path.join(timelineDir, `${fileName(rootId)}.jsonl`);
252
+ const branch = branchFile(rootId, branchId);
253
+ const temporary = `${file}.rewind-${fileName(branchId)}.tmp`;
254
+ return queue(appends, rootId, `timeline rewind ${rootId}`, async () => {
255
+ const exists = (target) => stat(target).then(() => true, (error) => {
256
+ if (error?.code === "ENOENT") return false;
257
+ throw error;
258
+ });
259
+ if (!await exists(branch)) {
260
+ if (!repaired.has(rootId)) {
261
+ await repairTail(file);
262
+ repaired.add(rootId);
263
+ }
264
+ const text = await readFile(file, "utf8").catch((error) => {
265
+ if (error?.code === "ENOENT") return "";
266
+ throw error;
267
+ });
268
+ const kept = [];
269
+ const markerCursor = marker.cursor ?? Number.MAX_SAFE_INTEGER;
270
+ let cursor = 0;
271
+ for (const line of text.split("\n")) {
272
+ if (!line) continue;
273
+ let envelope;
274
+ try {
275
+ envelope = JSON.parse(line);
276
+ } catch {
277
+ continue;
278
+ }
279
+ cursor = typeof envelope.cursor === "number" && envelope.cursor > cursor ? envelope.cursor : cursor + 1;
280
+ const lifecycle = envelope.sessionId === rootId && ["session.opened", "session.ready", "session.updated", "session.closed", "session.failed"].includes(envelope.event?.type);
281
+ if (cursor < cut) kept.push({ cursor, line });
282
+ else if (lifecycle || cursor > markerCursor) kept.push({ cursor, line: JSON.stringify({ ...envelope, cursor }) });
283
+ }
284
+ kept.push({ cursor: markerCursor, line: JSON.stringify(marker) });
285
+ kept.sort((a, b) => a.cursor - b.cursor);
286
+ await writeFile(temporary, `${kept.map((entry) => entry.line).join("\n")}
287
+ `, { mode: 384 });
288
+ if (await exists(file)) await rename(file, branch);
289
+ else await writeFile(branch, "", { mode: 384 });
290
+ }
291
+ if (await exists(temporary)) await rename(temporary, file);
292
+ await Promise.all([".jsonl.idx", ".jsonl.history.json"].map((suffix) => rm(path.join(timelineDir, `${fileName(rootId)}${suffix}`), { force: true })));
293
+ historyIndexes.delete(rootId);
294
+ repaired.add(rootId);
295
+ }, false, { rootId });
296
+ },
297
+ /** Writes a new tree's whole timeline at once (a fork's, §12.7); written again whole by a repeat. */
298
+ createTimeline(rootId, envelopes) {
299
+ const file = path.join(timelineDir, `${fileName(rootId)}.jsonl`);
300
+ return queue(appends, rootId, `timeline ${rootId}`, async () => {
301
+ await writeAtomic(file, envelopes.map((envelope) => `${JSON.stringify(envelope)}
302
+ `).join(""));
303
+ await Promise.all([".jsonl.idx", ".jsonl.history.json"].map((suffix) => rm(path.join(timelineDir, `${fileName(rootId)}${suffix}`), { force: true })));
304
+ historyIndexes.delete(rootId);
305
+ repaired.add(rootId);
306
+ }, false, { rootId });
307
+ },
308
+ /** The timeline of a branch a rewind set aside; empty when it is not there. */
309
+ async branchTimeline(rootId, branchId) {
310
+ await appends.get(rootId);
311
+ try {
312
+ return parseTimeline(await readFile(branchFile(rootId, branchId), "utf8"), path.basename(branchFile(rootId, branchId)));
313
+ } catch (error) {
314
+ if (error?.code === "ENOENT") return [];
315
+ throw error;
316
+ }
317
+ },
215
318
  async timeline(rootId) {
216
319
  await appends.get(rootId);
217
320
  const name = `${fileName(rootId)}.jsonl`;
@@ -258,15 +361,18 @@ function createStore(root) {
258
361
  health() {
259
362
  return { ...health, ...health.lastError ? { lastError: { ...health.lastError } } : {} };
260
363
  },
261
- /** Removes a whole tree: its records and its timeline. */
364
+ /** Removes a whole tree: its records, its timeline and the branches rewinds set aside. */
262
365
  async remove(rootId, ids) {
263
366
  await Promise.all([...ids.map((id) => writes.get(id)), appends.get(rootId)]);
367
+ const branches = (await readdir(timelineDir).catch(() => [])).filter((name) => name.startsWith(`${fileName(rootId)}.branch-`));
264
368
  await Promise.all([
265
369
  ...ids.map((id) => rm(path.join(sessionsDir, `${fileName(id)}.json`), { force: true })),
266
- rm(path.join(timelineDir, `${fileName(rootId)}.jsonl`), { force: true })
370
+ ...[".jsonl", ".jsonl.idx", ".jsonl.history.json"].map((suffix) => rm(path.join(timelineDir, `${fileName(rootId)}${suffix}`), { force: true })),
371
+ ...branches.map((name) => rm(path.join(timelineDir, name), { force: true }))
267
372
  ]);
268
373
  for (const id of ids) failed.delete(id);
269
374
  failed.delete(`timeline:${rootId}`);
375
+ historyIndexes.delete(rootId);
270
376
  repaired.delete(rootId);
271
377
  },
272
378
  async flush() {
@@ -0,0 +1,157 @@
1
+ import type { TerminalInfo, TerminalLimits } from '@anhlp/alp-protocol/rpc';
2
+ /**
3
+ * Terminals (capability `terminal`, docs/protocol/alp-json-rpc-v1.md §12.10, issue #121 H): a real
4
+ * PTY running a shell on this host **as the daemon's account**. A workspace chooses only where the
5
+ * shell starts and who sees the terminal; it is not a sandbox. alpd serves terminals only while the
6
+ * host owner opted in (`<ALP_HOME>/terminal.json` `allowRemoteTerminal`, an owner-private file no RPC
7
+ * writes), on macOS and Linux, when the optional `node-pty` module loads. Lifecycle is audited;
8
+ * input, output and the environment never are.
9
+ */
10
+ /** Who a call acts for, as for attachments: a gateway's credential and grant epoch, or the owner. */
11
+ export type TerminalPrincipal = {
12
+ id: string;
13
+ epoch: string;
14
+ roots?: readonly string[];
15
+ };
16
+ /** The connection a terminal streams to: alpd's own IPC connection object. */
17
+ export type TerminalSink = {
18
+ send(message: unknown): void;
19
+ socket?: {
20
+ writableLength: number;
21
+ destroyed?: boolean;
22
+ };
23
+ };
24
+ type Disposable = {
25
+ dispose(): void;
26
+ };
27
+ /** What alpd uses of a node-pty process. */
28
+ export type PtyProcess = {
29
+ pid: number;
30
+ /** The PTY's device (node-pty's UnixTerminal), such as /dev/ttys004 or /dev/pts/3. */
31
+ readonly ptsName?: string;
32
+ write(data: string): void;
33
+ resize(cols: number, rows: number): void;
34
+ kill(signal?: string): void;
35
+ onData(listener: (data: string) => void): Disposable;
36
+ onExit(listener: (event: {
37
+ exitCode: number;
38
+ signal?: number;
39
+ }) => void): Disposable;
40
+ };
41
+ export type PtySpawn = (file: string, args: string[], options: {
42
+ name: string;
43
+ cols: number;
44
+ rows: number;
45
+ cwd: string;
46
+ env: Record<string, string>;
47
+ }) => PtyProcess;
48
+ /** One process: ids, (Linux) session, controlling tty, age, and the terminal markers in its environment. */
49
+ export type ProcessRow = {
50
+ pid: number;
51
+ ppid: number;
52
+ pgid: number;
53
+ sid?: number;
54
+ tty?: string;
55
+ elapsedMs: number;
56
+ markers?: string[];
57
+ };
58
+ type Log = {
59
+ info(message: string, fields?: Record<string, unknown>): void;
60
+ warn(message: string, fields?: Record<string, unknown>): void;
61
+ };
62
+ export type TerminalServiceOptions = {
63
+ home: string;
64
+ /** The canonical directory of a registry workspace, or a RegistryError-like refusal. */
65
+ resolveWorkspace(workspaceId: string): Promise<string>;
66
+ log: Log;
67
+ /** Lower limits (tests, an embedding host); never higher than TERMINAL. */
68
+ limits?: Partial<TerminalLimits>;
69
+ now?: () => number;
70
+ platform?: NodeJS.Platform;
71
+ /** Test hook: the PTY spawner; default node-pty, loaded on first use. */
72
+ spawn?: PtySpawn;
73
+ /** Test hook: the process table; default `ps`. */
74
+ processes?: () => Promise<ProcessRow[]>;
75
+ sweepMs?: number;
76
+ killGraceMs?: number;
77
+ /** Bytes of terminal events waiting on a connection's socket before it counts as a slow consumer. */
78
+ maxBufferedBytes?: number;
79
+ };
80
+ /**
81
+ * The host switch and the operator's lower limits. Anything but a regular, owner-private file of
82
+ * this user saying `"allowRemoteTerminal": true` is off.
83
+ */
84
+ export declare function readTerminalConfig(home: string, log?: Log): Promise<{
85
+ enabled: boolean;
86
+ reason?: string;
87
+ limits: TerminalLimits;
88
+ paseo: boolean;
89
+ }>;
90
+ /**
91
+ * The process table: pid, parent, group, (Linux) session, controlling tty, age, and the terminal
92
+ * markers in each process's environment (macOS: `ps -E`, this user's processes only; Linux:
93
+ * /proc/<pid>/environ, readable for this user's processes).
94
+ */
95
+ export declare function psProcesses(platform?: NodeJS.Platform): () => Promise<ProcessRow[]>;
96
+ /** Splits output into frames of at most `max` UTF-8 bytes, never inside a character. */
97
+ export declare function frames(data: string, max: number): string[];
98
+ export declare function createTerminalService(options: TerminalServiceOptions): {
99
+ /** `terminalLimits` for daemon.hello while terminals are served, else undefined. */
100
+ advertised(): Promise<TerminalLimits | undefined>;
101
+ create(principal: TerminalPrincipal, params: {
102
+ workspaceId: string;
103
+ cols: number;
104
+ rows: number;
105
+ requestId: string;
106
+ }): Promise<{
107
+ terminal: TerminalInfo;
108
+ }>;
109
+ list(principal: TerminalPrincipal, params: {
110
+ workspaceId?: string;
111
+ }): Promise<{
112
+ terminals: TerminalInfo[];
113
+ }>;
114
+ attach(principal: TerminalPrincipal, sink: TerminalSink, params: {
115
+ terminalId: string;
116
+ after?: number;
117
+ }): Promise<{
118
+ gap?: {
119
+ fromSeq: number;
120
+ toSeq: number;
121
+ } | undefined;
122
+ terminal: TerminalInfo;
123
+ nextSeq: number;
124
+ }>;
125
+ input(principal: TerminalPrincipal, sink: TerminalSink, params: {
126
+ terminalId: string;
127
+ data: string;
128
+ }): Promise<{
129
+ bytes: number;
130
+ }>;
131
+ resize(principal: TerminalPrincipal, sink: TerminalSink, params: {
132
+ terminalId: string;
133
+ cols: number;
134
+ rows: number;
135
+ }): Promise<{
136
+ cols: number;
137
+ rows: number;
138
+ }>;
139
+ close(principal: TerminalPrincipal, params: {
140
+ terminalId: string;
141
+ }): Promise<{
142
+ closed: true;
143
+ }>;
144
+ /** Every terminal of a principal, any epoch: a gateway's revocation. */
145
+ revoke(principalId: string): Promise<{
146
+ closed: number;
147
+ }>;
148
+ /** A connection closed: its terminals keep running for reconnectMs. */
149
+ disconnect(sink: TerminalSink): void;
150
+ sweep: () => Promise<void>;
151
+ /** alpd stops: every terminal ends (reason `shutdown`) and its tree is killed. */
152
+ shutdown(): Promise<void>;
153
+ /** Test hook: pids of every running terminal's shell. */
154
+ pids(): number[];
155
+ };
156
+ export type TerminalService = ReturnType<typeof createTerminalService>;
157
+ export {};