@anhlp/alp-daemon 0.0.0-beta.1 → 0.0.0-beta.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/server.ts CHANGED
@@ -1,10 +1,11 @@
1
1
  import { createHash, randomBytes } from 'node:crypto';
2
2
  import { appendFile, chmod, mkdir, readFile, unlink, lstat, rename } from 'node:fs/promises';
3
3
  import net from 'node:net';
4
+ import os from 'node:os';
4
5
  import { assertPrivateDirectory, assertPrivateSocket } from '@anhlp/alp-client/index';
5
6
  import path from 'node:path';
6
7
  import { createLogger } from '@anhlp/alp-core/log';
7
- import { AlpRpcError, CAPABILITY, MAX_FRAME, PROTOCOL_VERSION, ERROR, RPC_ERROR, RPC_METHODS, encodeFrame } from '@anhlp/alp-protocol';
8
+ import { AlpRpcError, CAPABILITY, MAX_FRAME, PROMPT_IMAGES, PROTOCOL_VERSION, ERROR, RPC_ERROR, RPC_METHODS, base64Bytes, encodeFrame } from '@anhlp/alp-protocol';
8
9
  import { validateParams } from '@anhlp/alp-protocol/contract';
9
10
  export { ERROR } from '@anhlp/alp-protocol';
10
11
  import { DEFAULT_MODEL, models, modes, thinkingOptions, type AlpEvent, type AlpRuntime, type Envelope, type SessionSnapshot } from '@anhlp/alp-runtime/index';
@@ -12,6 +13,7 @@ import type { Receipt, SessionRecord, SessionStatus, Store, UnreadableReceipt }
12
13
  import type { SessionSummary } from '@anhlp/alp-protocol/session';
13
14
  import { RpcError } from './rpc-error.js';
14
15
  import { createOperations, type OperationsOptions } from './operations.js';
16
+ import { FileAccessError, FilesError, listWorkspaceDirectory, readWorkspaceFile, searchWorkspaceFiles } from './files.js';
15
17
 
16
18
  /**
17
19
  * alpd's JSON-RPC surface over one shared runtime (plans/reference/ALPD.md §3, §6, §14).
@@ -79,6 +81,39 @@ const RECEIPT_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
79
81
  /** How often a running alpd applies retention, besides at start (ALPD §68). */
80
82
  const RETENTION_SWEEP_MS = 6 * 60 * 60 * 1000;
81
83
  const LIVE: SessionStatus[] = ['initializing', 'idle', 'running'];
84
+ const PROMPT_TITLE_CHARS = 60;
85
+
86
+ /**
87
+ * A root's name from its first prompt, as Paseo names an agent (server/agent/create-agent-title.ts
88
+ * at b63a325): the first non-blank line, whitespace folded, at most 60 characters, no ellipsis.
89
+ * Counted in code points, where Paseo counts UTF-16 units, so a cut never splits a character.
90
+ */
91
+ function titleFromPrompt(text: string): string | undefined {
92
+ const line = text.split(/\r?\n/).map(entry => entry.replace(/\s+/g, ' ').trim()).find(Boolean);
93
+ return line ? [...line].slice(0, PROMPT_TITLE_CHARS).join('').trim() || undefined : undefined;
94
+ }
95
+
96
+ /**
97
+ * session.list's order and its keyset cursor: roots before children, the latest `updatedAt`
98
+ * first, then by id, so a page continues after the last session it holds, as Paseo's history pages
99
+ * (server/pagination/sortable-pager.ts at b63a325). The cursor is opaque to clients.
100
+ */
101
+ type ListKey = [child: 0 | 1, updatedAt: string, id: string];
102
+ const listCursor = {
103
+ key: (session: SessionSummary): ListKey => [session.parentId ? 1 : 0, session.updatedAt ?? '', session.id],
104
+ compare([childA, updatedA, idA]: ListKey, [childB, updatedB, idB]: ListKey) {
105
+ return childA - childB || (updatedA === updatedB ? 0 : updatedA < updatedB ? 1 : -1) || (idA === idB ? 0 : idA < idB ? -1 : 1);
106
+ },
107
+ encode: (key: ListKey) => Buffer.from(JSON.stringify(key), 'utf8').toString('base64url'),
108
+ decode(cursor: string): ListKey {
109
+ let key: unknown;
110
+ try { key = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8')); } catch {}
111
+ if (!Array.isArray(key) || key.length !== 3 || (key[0] !== 0 && key[0] !== 1) || typeof key[1] !== 'string' || typeof key[2] !== 'string') {
112
+ throw new RpcError(RPC_ERROR.invalidParams, 'cursor is not one session.list answered', { reason: 'invalid_params' });
113
+ }
114
+ return key as ListKey;
115
+ },
116
+ };
82
117
 
83
118
  /** What clients need from a daemon connection; AlpClient implements it over the socket. */
84
119
  import type { DaemonConnection } from '@anhlp/alp-protocol/connection';
@@ -140,6 +175,30 @@ export function createDaemonServer({ runtime, socketPath, version, onShutdown, s
140
175
  const restored = store ? restore() : Promise.resolve();
141
176
 
142
177
  const deliver = (connection: Connection, envelope: Envelope) => connection.send({ jsonrpc: '2.0', method: 'event', params: envelope });
178
+ /** Connections that called question.watch, with the projectRoot they asked for and whether they want roots' turn ends. */
179
+ const watchers = new Map<Connection, { projectRoot?: string; turns: boolean }>();
180
+
181
+ /** The project of a tree, live or recorded. */
182
+ function projectOf(root: string) {
183
+ return runtime.snapshot(root)?.projectRoot ?? records.get(root)?.session?.projectRoot;
184
+ }
185
+
186
+ /**
187
+ * Tells watchers not attached to the tree of a question asked or resolved there, or, for those
188
+ * that asked for `turns`, of the end of a root's turn. Their copy has no `cursor`: it is not part
189
+ * of a timeline they replay (docs/protocol/alp-json-rpc-v1.md §8.1, §12.2).
190
+ */
191
+ function tellWatchers(root: string, envelope: Envelope, turn = false) {
192
+ if (!watchers.size) return;
193
+ const { cursor: _cursor, ...announced } = envelope;
194
+ const project = projectOf(root);
195
+ for (const [connection, { projectRoot, turns }] of watchers) {
196
+ if (turn && !turns) continue;
197
+ if (attached.get(root)?.has(connection)) continue;
198
+ if (projectRoot !== undefined && project !== projectRoot) continue;
199
+ deliver(connection, announced);
200
+ }
201
+ }
143
202
 
144
203
  /** Records a change; the write is queued, and a failure is logged and counted in daemon.status. */
145
204
  function save(record: SessionRecord & { activeTurnId?: string }, changes: Partial<SessionRecord & { activeTurnId?: string }> = {}) {
@@ -163,25 +222,47 @@ export function createDaemonServer({ runtime, socketPath, version, onShutdown, s
163
222
  if (last > (cursors.get(root) ?? 0)) cursors.set(root, last);
164
223
  }
165
224
 
166
- /** Lifecycle bookkeeping for one event; returns true when the record changed. */
167
- function track(sessionId: string, root: string, event: AlpEvent) {
225
+ /** Lifecycle bookkeeping for one event; returns true when it named the root. */
226
+ function track(sessionId: string, root: string, event: AlpEvent): boolean {
168
227
  const now = new Date().toISOString();
169
228
  let record = records.get(sessionId);
170
229
  if (event.type === 'session.opened') {
171
230
  record ??= { version: 1, id: sessionId, rootId: root, status: 'initializing', createdAt: now, updatedAt: now };
172
- save(record, { rootId: root, session: event.session, status: 'idle', lastError: undefined, activeTurnId: undefined });
173
- return;
231
+ // A reopened session keeps its last usage until its runtime reports again.
232
+ const usage = event.session.usage ?? record.session?.usage;
233
+ save(record, { rootId: root, session: { ...event.session, ...(usage ? { usage } : {}) }, status: 'idle', lastError: undefined, activeTurnId: undefined });
234
+ return false;
174
235
  }
175
- if (!record) return;
236
+ if (!record) return false;
176
237
  if (event.type === 'session.updated') save(record, { session: { ...record.session, ...event.session, ...(event.session.parked ? {} : { parked: undefined }) } });
177
238
  // Work on an archived session brings it back.
178
239
  else if (event.type === 'turn.started') save(record, { status: 'running', activeTurnId: event.turnId, archived: undefined });
179
240
  else if (event.type === 'turn.ended') save(record, { status: 'idle', activeTurnId: undefined, ...(event.state === 'failed' ? { lastError: { message: event.error?.message ?? 'Turn failed' } } : {}) });
241
+ // The latest usage, for a closed session's summary; written with the record's next change.
242
+ else if (event.type === 'usage' && record.session) record.session = { ...record.session, usage: event.usage };
180
243
  else if (event.type === 'session.failed') save(record, { status: 'error', lastError: event.error });
181
244
  else if (event.type === 'session.closed') save(record, { status: record.status === 'error' ? 'error' : 'closed', activeTurnId: undefined });
182
245
  else if (event.type === 'item' && sessionId === root && !record.title && event.item.kind === 'user_message' && !event.item.clientMessageId?.startsWith('alp-')) {
183
- save(record, { title: event.item.text.replace(/\s+/g, ' ').trim().slice(0, 80) });
246
+ // The user's first message names an unnamed root, as Paseo names an agent (ALPD §15).
247
+ const title = titleFromPrompt(event.item.text);
248
+ if (title) { save(record, { title }); return true; }
184
249
  }
250
+ return false;
251
+ }
252
+
253
+ /**
254
+ * Tells the viewers of a live root its name, as a `session.updated` kept in its timeline, so a
255
+ * viewer attached later replays it. Nothing is sent for a root that is not open.
256
+ */
257
+ function announceTitle(root: string, title: string) {
258
+ const session = runtime.snapshot(root);
259
+ if (!session || rootOf.get(root) !== root) return;
260
+ const envelope = keep(root, { sessionId: root, epoch: `title-${startedAt}`, seq: 0, ts: new Date().toISOString(), event: { type: 'session.updated', session: { ...session, title } } });
261
+ const log = logs.get(root) ?? [];
262
+ log.push(envelope);
263
+ if (log.length > TREE_LOG_LIMIT) log.splice(0, log.length - TREE_LOG_LIMIT);
264
+ logs.set(root, log);
265
+ for (const connection of attached.get(root) ?? []) deliver(connection, envelope);
185
266
  }
186
267
 
187
268
  runtime.onEvent(original => {
@@ -194,15 +275,20 @@ export function createDaemonServer({ runtime, socketPath, version, onShutdown, s
194
275
  rootOf.set(sessionId, parent ? rootOf.get(parent) ?? parent : sessionId);
195
276
  }
196
277
  const root = rootOf.get(sessionId) ?? sessionId;
278
+ let named = false;
197
279
  if (rootOf.has(sessionId)) {
198
280
  envelope = keep(root, envelope);
199
281
  const log = logs.get(root) ?? [];
200
282
  log.push(envelope);
201
283
  if (log.length > TREE_LOG_LIMIT) log.splice(0, log.length - TREE_LOG_LIMIT);
202
284
  logs.set(root, log);
203
- track(sessionId, root, event);
285
+ named = track(sessionId, root, event);
204
286
  }
205
287
  for (const connection of attached.get(root) ?? []) deliver(connection, envelope);
288
+ if (event.type === 'question' || event.type === 'question.resolved') tellWatchers(root, envelope);
289
+ else if (event.type === 'turn.ended' && sessionId === root) tellWatchers(root, envelope, true);
290
+ // After the message that named it, so its cursor follows the message's.
291
+ if (named) announceTitle(root, records.get(root)!.title!);
206
292
  if (event.type === 'session.closed' && sessionId === root) {
207
293
  setImmediate(() => forget(root));
208
294
  } else {
@@ -635,8 +721,47 @@ export function createDaemonServer({ runtime, socketPath, version, onShutdown, s
635
721
  },
636
722
 
637
723
  'question.list'(_connection, { projectRoot } = {}) {
638
- const questions = runtime.questions().filter(question => projectRoot === undefined || runtime.snapshot(question.rootId)?.projectRoot === projectRoot);
639
- return { questions };
724
+ return { questions: runtime.questions().filter(question => projectRoot === undefined || projectOf(question.rootId) === projectRoot) };
725
+ },
726
+
727
+ /**
728
+ * The questions waiting now; from then on this connection is told of `question` and
729
+ * `question.resolved` in every tree, or those of `projectRoot`, attached or not. Calling it
730
+ * again replaces the filter; it lasts as long as the connection (ALPD §15). With `turns`, also
731
+ * of `turn.ended` of every root (docs/protocol/alp-json-rpc-v1.md §12.2).
732
+ */
733
+ 'question.watch'(connection, { projectRoot, turns } = {}) {
734
+ // No await between registering and listing: an event either is in the list or follows it.
735
+ watchers.set(connection, { projectRoot, turns: turns === true });
736
+ return { questions: runtime.questions().filter(question => projectRoot === undefined || projectOf(question.rootId) === projectRoot) };
737
+ },
738
+
739
+ /**
740
+ * The files of a directory whose path matches a query, read-only and confined to it: no link
741
+ * is followed, only names are read (docs/protocol/alp-json-rpc-v1.md §12.3, ALPD §15).
742
+ */
743
+ async 'workspace.files.search'(_connection, { projectRoot, query, limit } = {}) {
744
+ if (typeof projectRoot !== 'string' || !path.isAbsolute(projectRoot) || path.resolve(projectRoot) !== projectRoot) {
745
+ throw new RpcError(RPC_ERROR.invalidParams, 'projectRoot must be an absolute, normalized path', { reason: 'invalid_path' });
746
+ }
747
+ try {
748
+ return await searchWorkspaceFiles(projectRoot, { query, limit });
749
+ } catch (error) {
750
+ if (error instanceof FilesError) throw new RpcError(ERROR.notFound, error.message, { reason: 'not_directory' });
751
+ throw error;
752
+ }
753
+ },
754
+
755
+ /**
756
+ * The entries of a directory under projectRoot, and the content of a text file there:
757
+ * read-only, confined to it, no link followed, blocked paths always refused, .gitignore'd ones
758
+ * unless includeIgnored (docs/protocol/alp-json-rpc-v1.md §12.4, ALPD §15).
759
+ */
760
+ async 'workspace.files.list'(_connection, { projectRoot, path: relative, includeIgnored } = {}) {
761
+ return filesCall(projectRoot, () => listWorkspaceDirectory(projectRoot, { path: relative, includeIgnored: includeIgnored === true }));
762
+ },
763
+ async 'workspace.files.read'(_connection, { projectRoot, path: relative, includeIgnored } = {}) {
764
+ return filesCall(projectRoot, () => readWorkspaceFile(projectRoot, { path: relative, includeIgnored: includeIgnored === true }));
640
765
  },
641
766
 
642
767
  /** The project board: live claims, decisions and findings (ALPD §18). */
@@ -780,6 +905,16 @@ export function createDaemonServer({ runtime, socketPath, version, onShutdown, s
780
905
  async 'session.prompt'(_connection, { sessionId, clientMessageId, delivery = 'auto', content }) {
781
906
  if (typeof clientMessageId !== 'string' || !Array.isArray(content)) throw new RpcError(-32602, 'clientMessageId and content are required');
782
907
  if (delivery !== 'auto' && delivery !== 'steer') throw new RpcError(-32602, 'delivery must be auto or steer');
908
+ // Images are inline only (the schema refuses a path or URL); here their number and decoded size.
909
+ const images = content.filter((part: { type?: string }) => part?.type === 'image');
910
+ if (images.length > PROMPT_IMAGES.maxCount) throw new RpcError(-32602, `A prompt takes at most ${PROMPT_IMAGES.maxCount} images`);
911
+ let total = 0;
912
+ for (const image of images) {
913
+ const bytes = base64Bytes(image.data);
914
+ total += bytes;
915
+ if (bytes > PROMPT_IMAGES.maxBytes) throw new RpcError(-32602, `An image in a prompt is at most ${PROMPT_IMAGES.maxBytes} bytes`);
916
+ if (total > PROMPT_IMAGES.maxTotalBytes) throw new RpcError(-32602, `The images of a prompt are at most ${PROMPT_IMAGES.maxTotalBytes} bytes together`);
917
+ }
783
918
  const send = async () => {
784
919
  // Failures of an open session arrive as prompt.failed events; an unknown session has no watcher.
785
920
  live(sessionId);
@@ -815,6 +950,7 @@ export function createDaemonServer({ runtime, socketPath, version, onShutdown, s
815
950
  Object.assign(record, { title: title.replace(/\s+/g, ' ').trim() });
816
951
  try { await store?.put(record); }
817
952
  catch (error) { record.title = before; throw persistenceFailed(`the name of ${record.id}`, error); }
953
+ announceTitle(record.id, record.title!);
818
954
  return { session: summary(record.id) };
819
955
  },
820
956
 
@@ -833,15 +969,29 @@ export function createDaemonServer({ runtime, socketPath, version, onShutdown, s
833
969
  return { session: known(sessionId) };
834
970
  },
835
971
 
836
- 'session.list'(_connection, { projectRoot, rootsOnly = false, includeClosed = false, includeArchived = false } = {}): { sessions: SessionSummary[] } {
972
+ /**
973
+ * Roots first, then newest first, by id last. With `limit` a page, and `nextCursor` while more
974
+ * follow; `cursor` continues after the session it names; `query` keeps the sessions whose title
975
+ * or id holds every word of it; `projectRoots` those of any of these projects, as a gateway lists
976
+ * a grant's workspaces (docs/protocol/alp-json-rpc-v1.md §12.1).
977
+ */
978
+ 'session.list'(_connection, { projectRoot, projectRoots, rootsOnly = false, includeClosed = false, includeArchived = false, limit, cursor, query } = {}): { sessions: SessionSummary[]; nextCursor?: string } {
979
+ const projects = Array.isArray(projectRoots) ? new Set<string>(projectRoots) : undefined;
980
+ const after = cursor === undefined ? undefined : listCursor.decode(cursor);
981
+ const words = typeof query === 'string' ? query.toLowerCase().split(/\s+/).filter(Boolean) : [];
837
982
  const ids = new Set([...runtime.list().map(session => session.id), ...records.keys()]);
838
983
  const sessions = [...ids].map(summary).filter((session): session is SessionSummary => !!session)
839
984
  .filter(session => includeClosed || session.status === 'idle' || session.status === 'running')
840
985
  .filter(session => includeArchived || !session.archived)
841
986
  .filter(session => !rootsOnly || !session.parentId)
842
987
  .filter(session => projectRoot === undefined || session.projectRoot === projectRoot)
843
- .sort((a, b) => Number(!!a.parentId) - Number(!!b.parentId) || (b.updatedAt ?? '').localeCompare(a.updatedAt ?? ''));
844
- return { sessions };
988
+ .filter(session => !projects || projects.has(session.projectRoot))
989
+ .filter(session => !words.length || words.every(word => `${session.title ?? ''}\n${session.id}`.toLowerCase().includes(word)))
990
+ .sort((a, b) => listCursor.compare(listCursor.key(a), listCursor.key(b)))
991
+ .filter(session => !after || listCursor.compare(listCursor.key(session), after) > 0);
992
+ if (limit === undefined || sessions.length <= limit) return { sessions };
993
+ const page = sessions.slice(0, limit);
994
+ return { sessions: page, nextCursor: listCursor.encode(listCursor.key(page.at(-1)!)) };
845
995
  },
846
996
  };
847
997
  for (const [method, handler] of Object.entries(operations.handlers)) handlers[method] = (_connection, params) => handler(params);
@@ -883,8 +1033,26 @@ export function createDaemonServer({ runtime, socketPath, version, onShutdown, s
883
1033
  return { live: true, ready: checks.every(check => check.ok), checks };
884
1034
  }
885
1035
 
1036
+ /**
1037
+ * One workspace.files.list or read call: projectRoot checked, refusals answered with their code
1038
+ * and reason, any other failure with a fixed message (it may name a host path; alpd logs it).
1039
+ */
1040
+ async function filesCall<T>(projectRoot: unknown, read: () => Promise<T>): Promise<T> {
1041
+ if (typeof projectRoot !== 'string' || !path.isAbsolute(projectRoot) || path.resolve(projectRoot) !== projectRoot) {
1042
+ throw new RpcError(RPC_ERROR.invalidParams, 'projectRoot must be an absolute, normalized path', { reason: 'invalid_path' });
1043
+ }
1044
+ try {
1045
+ return await read();
1046
+ } catch (error) {
1047
+ if (error instanceof FileAccessError) throw new RpcError(error.code, error.message, { reason: error.reason });
1048
+ if (error instanceof FilesError) throw new RpcError(ERROR.notFound, error.message, { reason: 'not_directory' });
1049
+ log.error('workspace file read failed', { code: 'ALPD_FILES_FAILED', error });
1050
+ throw new RpcError(ERROR.failed, 'alpd could not read the workspace file');
1051
+ }
1052
+ }
1053
+
886
1054
  /** What this daemon lists in daemon.hello: only features it serves now (docs/protocol/alp-json-rpc-v1.md §6). */
887
- const capabilities = [CAPABILITY.attachAfter, CAPABILITY.extensionMethods, ...(store ? [CAPABILITY.promptReceipts] : []), ...operations.capabilities];
1055
+ const capabilities = [CAPABILITY.attachAfter, CAPABILITY.extensionMethods, CAPABILITY.sessionListPage, CAPABILITY.questionWatch, CAPABILITY.questionWatchTurns, CAPABILITY.workspaceFiles, CAPABILITY.workspaceFilesRead, CAPABILITY.promptImages, ...(store ? [CAPABILITY.promptReceipts] : []), ...operations.capabilities];
888
1056
 
889
1057
  /** A response too large for the wire becomes an error the client can read. */
890
1058
  function fits(response: { jsonrpc: '2.0'; id: string | number | null; result?: unknown; error?: unknown }) {
@@ -935,7 +1103,7 @@ export function createDaemonServer({ runtime, socketPath, version, onShutdown, s
935
1103
  const issues = validateParams(method, params)!;
936
1104
  if (issues.length) throw invalidParams(issues);
937
1105
  connection.helloed = true;
938
- respond({ result: { protocolVersion: PROTOCOL_VERSION, daemonVersion: version, pid: process.pid, capabilities } });
1106
+ respond({ result: { protocolVersion: PROTOCOL_VERSION, daemonVersion: version, pid: process.pid, hostname: os.hostname(), capabilities } });
939
1107
  return;
940
1108
  }
941
1109
  if (!connection.helloed) throw new RpcError(ERROR.protocol, 'daemon.hello is required first', { reason: 'hello_required' });
@@ -971,6 +1139,7 @@ export function createDaemonServer({ runtime, socketPath, version, onShutdown, s
971
1139
  waiting.reject(new Error('ALP daemon caller connection closed'));
972
1140
  }
973
1141
  connections.delete(connection);
1142
+ watchers.delete(connection);
974
1143
  for (const root of [...connection.roots]) {
975
1144
  detach(connection, root);
976
1145
  void reap(root);