@thready-web/dsh-bot-plugin 0.0.0-stage → 0.1.0-beta.1

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/dist/desk.js ADDED
@@ -0,0 +1,518 @@
1
+ /** Workbench routes inside the DSH process. The browser calls /dsh-bot/api. */
2
+ import { readFileSync } from 'node:fs';
3
+ import { dirname, join } from 'node:path';
4
+ import { openLedger, validIdempotencyKey } from "./desk-ledger.js";
5
+ import { openSessionPreviews } from "./session-previews.js";
6
+ import { purgeSessionFiles, sessionDirectory, writeBotMarker } from "./session-files.js";
7
+ const API = '/session-foundations/api';
8
+ const PREVIEW_SESSION = /^(?:session|worker)-[A-Za-z0-9-]+$/;
9
+ const SECRET_KEY = /token|secret|password|authorization|api[-_]?key|cookie/i;
10
+ /**
11
+ * @param {object} options
12
+ * @param {string} options.ledgerFile
13
+ * @param {string} options.profileDir
14
+ * @param {string} options.sessionCwd
15
+ * @param {(sessionId: string) => boolean} options.isBot
16
+ * @param {(sessionId: string) => { kind?: string } | null | undefined} options.mark
17
+ * @param {(sessionId: string) => void | Promise<void>} options.hold
18
+ * @param {(sessionId: string) => void | Promise<void>} options.release
19
+ * @param {(endpoint: string, args: Record<string, unknown>, req: import('node:http').IncomingMessage) => Promise<{ status: number, body: RpcEnvelope }>} options.rpc
20
+ * @param {(req: import('node:http').IncomingMessage) => Promise<Record<string, unknown>>} options.usage
21
+ */
22
+ export function createDesk(options) {
23
+ const ledger = openLedger(options.ledgerFile);
24
+ const sessionPreviews = openSessionPreviews(join(dirname(options.ledgerFile), 'session-previews.json'));
25
+ /** @type {Map<string, Promise<void>>} */
26
+ const promptLocks = new Map();
27
+ const sessionsRoot = join(options.profileDir, 'sessions');
28
+ return {
29
+ /**
30
+ * @param {string} method
31
+ * @param {string} path
32
+ */
33
+ owns(method, path) {
34
+ const sub = subpath(path);
35
+ if (sub === null)
36
+ return false;
37
+ if (method === 'GET' && (sub === '/health' || sub === '/sessions' || sub === '/tasks' || sub === '/usage' || sub === '/file'))
38
+ return true;
39
+ if (method === 'POST' && (sub === '/sessions' || sub === '/sessions/previews' || sub === '/tasks'))
40
+ return true;
41
+ if (method === 'POST' && /^\/sessions\/session-[A-Za-z0-9-]+\/(?:archive|purge)$/.test(sub))
42
+ return true;
43
+ if (method === 'POST' && /^\/tasks\/[0-9a-f-]{36}\/cancel$/.test(sub))
44
+ return true;
45
+ return false;
46
+ },
47
+ /**
48
+ * @param {string} method
49
+ * @param {string} path
50
+ * @param {URL} url
51
+ * @param {import('node:http').IncomingMessage} req
52
+ */
53
+ async handle(method, path, url, req) {
54
+ const sub = subpath(path) ?? '';
55
+ const body = method === 'POST' ? await readJson(req) : {};
56
+ if (method === 'GET' && sub === '/health')
57
+ return { status: 200, body: await health(req) };
58
+ if (method === 'GET' && sub === '/sessions') {
59
+ const result = await options.rpc('session/list', { _request: {} }, req);
60
+ return { status: result.status, body: attachPreviews(result.body) };
61
+ }
62
+ if (method === 'POST' && sub === '/sessions/previews')
63
+ return savePreviews(body);
64
+ if (method === 'POST' && sub === '/sessions')
65
+ return createSession(req, body);
66
+ const archive = sub.match(/^\/sessions\/(session-[A-Za-z0-9-]+)\/archive$/);
67
+ if (method === 'POST' && archive)
68
+ return archiveBlank(req, archive[1]);
69
+ const purge = sub.match(/^\/sessions\/(session-[A-Za-z0-9-]+)\/purge$/);
70
+ if (method === 'POST' && purge)
71
+ return purgeBlank(req, purge[1]);
72
+ if (method === 'GET' && sub === '/tasks')
73
+ return { status: 200, body: { items: ledger.tasks() } };
74
+ if (method === 'POST' && sub === '/tasks')
75
+ return createTask(req, body);
76
+ const cancel = sub.match(/^\/tasks\/([0-9a-f-]{36})\/cancel$/);
77
+ if (method === 'POST' && cancel)
78
+ return cancelTask(req, cancel[1]);
79
+ if (method === 'GET' && sub === '/usage')
80
+ return { status: 200, body: redactSecrets(await options.usage(req)) };
81
+ if (method === 'GET' && sub === '/file')
82
+ return filePreview(req, url);
83
+ return { status: 404, body: { error: 'not_found' } };
84
+ },
85
+ };
86
+ /**
87
+ * @param {import('node:http').IncomingMessage} req
88
+ */
89
+ async function health(req) {
90
+ const execution = await executionState(req);
91
+ return {
92
+ primary: { reachable: execution.reachable },
93
+ execution: { ready: execution.ready, reason: execution.reason },
94
+ };
95
+ }
96
+ /**
97
+ * @param {import('node:http').IncomingMessage} req
98
+ */
99
+ async function executionState(req) {
100
+ const catalog = await options.rpc('session/modelCatalog', {}, req);
101
+ const value = catalog.body?.result?.value;
102
+ const routable = Array.isArray(value?.routableProviders) ? value.routableProviders : [];
103
+ if (catalog.body?.result?.ok === true && routable.length > 0)
104
+ return { ready: true, reason: '', reachable: true };
105
+ const failure = catalog.body?.result?.error?.message;
106
+ return {
107
+ ready: false,
108
+ reason: catalog.body?.result?.ok === true ? 'no_provider' : (failure ? String(failure) : 'catalog_unreadable'),
109
+ reachable: catalog.status > 0 && catalog.status < 500,
110
+ };
111
+ }
112
+ /**
113
+ * @param {import('node:http').IncomingMessage} req
114
+ * @param {Record<string, unknown>} body
115
+ */
116
+ async function createSession(req, body) {
117
+ const key = idempotencyOf(req, body);
118
+ if (!validIdempotencyKey(key))
119
+ return { status: 400, body: { error: 'idempotency_key_required' } };
120
+ const existing = ledger.session(key);
121
+ if (existing)
122
+ return { status: 200, body: { sessionId: existing.sessionId, reused: true } };
123
+ const listed = await options.rpc('session/list', { _request: {} }, req);
124
+ const known = listed.body?.result?.ok === true && Array.isArray(listed.body.result.value?.items)
125
+ ? listed.body.result.value.items
126
+ : [];
127
+ const reusable = options.sessionCwd === ''
128
+ ? undefined
129
+ : known.find(item => item?.blank === true && item?.running !== true && item?.cwd === options.sessionCwd && typeof item.sessionId === 'string');
130
+ const request = options.sessionCwd === ''
131
+ ? {}
132
+ : reusable
133
+ ? { cwd: options.sessionCwd, sessionId: reusable.sessionId }
134
+ : { cwd: options.sessionCwd };
135
+ const created = await options.rpc('session/create', { request }, req);
136
+ const sessionId = created.body?.result?.value?.sessionId;
137
+ if (created.body?.result?.ok !== true || typeof sessionId !== 'string') {
138
+ return { status: 502, body: { error: 'session_create_failed', upstream: created.body?.result?.error ?? null } };
139
+ }
140
+ const marked = options.mark(sessionId);
141
+ if (!marked || marked.kind !== 'bot') {
142
+ return { status: 502, body: { error: 'bot_mark_failed', sessionId, upstream: marked ?? null } };
143
+ }
144
+ let marker = '';
145
+ if (options.sessionCwd !== '') {
146
+ try {
147
+ marker = writeBotMarker({
148
+ sessionsRoot,
149
+ cwd: options.sessionCwd,
150
+ sessionId,
151
+ name: typeof body.name === 'string' ? body.name : '',
152
+ });
153
+ }
154
+ catch {
155
+ return { status: 502, body: { error: 'bot_marker_failed', sessionId } };
156
+ }
157
+ }
158
+ ledger.rememberSession(key, sessionId);
159
+ return { status: 201, body: { sessionId, kind: 'bot', marker, reused: Boolean(reusable) && sessionId === reusable.sessionId } };
160
+ }
161
+ /**
162
+ * @param {import('node:http').IncomingMessage} req
163
+ * @param {string} sessionId
164
+ */
165
+ async function archiveBlank(req, sessionId) {
166
+ const listed = await options.rpc('session/list', { _request: {} }, req);
167
+ const items = listed.body?.result?.value?.items;
168
+ if (listed.body?.result?.ok !== true || !Array.isArray(items)) {
169
+ return { status: 502, body: { error: 'session_list_failed', upstream: listed.body?.result?.error ?? null } };
170
+ }
171
+ const item = items.find(entry => entry?.sessionId === sessionId);
172
+ if (!item)
173
+ return { status: 404, body: { error: 'session_not_found' } };
174
+ if (item.blank !== true || item.running === true)
175
+ return { status: 409, body: { error: 'not_blank' } };
176
+ const archived = await options.rpc('workspace/archiveSession', { request: { sessionId } }, req);
177
+ const archivedSessionIds = archived.body?.result?.value?.archivedSessionIds;
178
+ if (archived.body?.result?.ok !== true || !Array.isArray(archivedSessionIds)) {
179
+ return { status: 502, body: { error: 'archive_failed', upstream: archived.body?.result?.error ?? null } };
180
+ }
181
+ return { status: 200, body: { sessionId, archivedSessionIds } };
182
+ }
183
+ /**
184
+ * @param {import('node:http').IncomingMessage} req
185
+ * @param {string} sessionId
186
+ */
187
+ async function purgeBlank(req, sessionId) {
188
+ const listed = await options.rpc('session/list', { _request: {} }, req);
189
+ const items = listed.body?.result?.value?.items;
190
+ if (listed.body?.result?.ok !== true || !Array.isArray(items)) {
191
+ return { status: 502, body: { error: 'session_list_failed', upstream: listed.body?.result?.error ?? null } };
192
+ }
193
+ const item = items.find(entry => entry?.sessionId === sessionId);
194
+ if (!item)
195
+ return { status: 404, body: { error: 'session_not_found' } };
196
+ if (item.blank !== true || item.running === true || typeof item.cwd !== 'string' || item.cwd === '') {
197
+ return { status: 409, body: { error: 'not_blank' } };
198
+ }
199
+ try {
200
+ purgeSessionFiles({
201
+ sessionsRoot,
202
+ cacheFile: join(options.profileDir, 'storages', 'session_projcache', 'sessions', `${sessionId}.json`),
203
+ workspaceFile: join(options.profileDir, 'storages', 'workspace.json'),
204
+ sessionId,
205
+ cwd: item.cwd,
206
+ });
207
+ }
208
+ catch (error) {
209
+ return { status: 500, body: { error: 'purge_failed', message: error instanceof Error ? error.message : 'purge failed' } };
210
+ }
211
+ sessionPreviews.forget(sessionId);
212
+ return { status: 200, body: { sessionId, purged: true } };
213
+ }
214
+ /**
215
+ * @param {unknown} body
216
+ */
217
+ function attachPreviews(body) {
218
+ if (!body || typeof body !== 'object' || Array.isArray(body))
219
+ return body;
220
+ return { ...body, previews: sessionPreviews.all() };
221
+ }
222
+ /**
223
+ * @param {Record<string, unknown>} body
224
+ */
225
+ function savePreviews(body) {
226
+ if (body.previews && typeof body.previews === 'object' && !Array.isArray(body.previews)) {
227
+ sessionPreviews.rememberAll(body.previews);
228
+ return { status: 200, body: { ok: true, previews: sessionPreviews.all() } };
229
+ }
230
+ const saved = sessionPreviews.remember(body.sessionId, body.preview);
231
+ if (!saved.ok)
232
+ return { status: 400, body: { error: saved.error } };
233
+ return { status: 200, body: { ok: true, preview: saved.preview } };
234
+ }
235
+ /**
236
+ * @param {import('node:http').IncomingMessage} req
237
+ * @param {Record<string, unknown>} body
238
+ */
239
+ async function createTask(req, body) {
240
+ const key = idempotencyOf(req, body);
241
+ if (!validIdempotencyKey(key))
242
+ return { status: 400, body: { error: 'idempotency_key_required' } };
243
+ const text = typeof body.text === 'string' ? body.text : '';
244
+ const sessionId = typeof body.sessionId === 'string' ? body.sessionId : '';
245
+ if (text.trim() === '' || text.length > 8000 || !/^session-[A-Za-z0-9-]+$/.test(sessionId)) {
246
+ return { status: 400, body: { error: 'invalid_task' } };
247
+ }
248
+ const execution = await executionState(req);
249
+ const remembered = ledger.rememberTask(key, {
250
+ sessionId,
251
+ status: execution.ready ? 'accepted' : 'blocked_unconfigured',
252
+ reason: execution.ready ? '' : execution.reason,
253
+ });
254
+ if (!remembered.created)
255
+ return { status: 200, body: { task: remembered.record, reused: true } };
256
+ if (!execution.ready) {
257
+ return { status: 409, body: { error: 'model_unconfigured', task: remembered.record, execution: { ready: false, reason: execution.reason } } };
258
+ }
259
+ const delivered = await withPromptLock(sessionId, () => deliverPrompt(req, sessionId, text, remembered.record.id));
260
+ if (!delivered.ok) {
261
+ const updated = ledger.updateTask(remembered.record.id, {
262
+ status: 'failed',
263
+ reason: delivered.reason,
264
+ upstreamCode: delivered.upstreamCode,
265
+ });
266
+ return { status: delivered.status, body: { error: delivered.error, task: updated } };
267
+ }
268
+ return { status: 202, body: { task: remembered.record, reused: false, interrupted: delivered.interrupted } };
269
+ }
270
+ /**
271
+ * @param {import('node:http').IncomingMessage} req
272
+ * @param {string} id
273
+ */
274
+ async function cancelTask(req, id) {
275
+ const task = ledger.task(id);
276
+ if (!task)
277
+ return { status: 404, body: { error: 'not_found' } };
278
+ if (task.status !== 'accepted')
279
+ return { status: 409, body: { error: 'not_running', task } };
280
+ const result = await options.rpc('session/cancel', { request: { sessionId: task.sessionId } }, req);
281
+ const updated = ledger.updateTask(task.id, {
282
+ status: result.body?.result?.ok === true ? 'cancelled' : 'failed',
283
+ reason: result.body?.result?.ok === true ? '' : (result.body?.result?.error?.message ?? 'cancel failed'),
284
+ upstreamCode: result.body?.result?.error?.code,
285
+ });
286
+ return { status: result.body?.result?.ok === true ? 200 : 502, body: { task: updated } };
287
+ }
288
+ /**
289
+ * @param {import('node:http').IncomingMessage} req
290
+ * @param {URL} url
291
+ */
292
+ async function filePreview(req, url) {
293
+ const sessionId = url.searchParams.get('sessionId') ?? '';
294
+ const filePath = workspaceRelativePath(url.searchParams.get('path') ?? '');
295
+ if (!PREVIEW_SESSION.test(sessionId) || filePath === null)
296
+ return { status: 400, body: { error: 'invalid_file' } };
297
+ const result = await options.rpc('workspaceFiles/read', {
298
+ workspaceFileScopeId: sessionId,
299
+ path: filePath,
300
+ range: { offset: 1, limit: 2000 },
301
+ }, req);
302
+ const value = result.body?.result?.value;
303
+ if (result.body?.result?.ok !== true || !value || typeof value.text !== 'string') {
304
+ const code = result.body?.result?.error?.code;
305
+ return {
306
+ status: result.status === 401 ? 401 : 404,
307
+ body: { error: 'file_unreadable', code: typeof code === 'string' ? code : 'workspace-file/not-found' },
308
+ };
309
+ }
310
+ return {
311
+ status: 200,
312
+ body: {
313
+ path: filePath,
314
+ name: filePath.split('/').at(-1) ?? filePath,
315
+ text: value.text,
316
+ eof: value.eof === true,
317
+ bytes: typeof value.bytes === 'number' ? value.bytes : null,
318
+ },
319
+ };
320
+ }
321
+ /**
322
+ * @param {string} sessionId
323
+ * @param {() => Promise<T>} fn
324
+ * @template T
325
+ */
326
+ async function withPromptLock(sessionId, fn) {
327
+ const previous = promptLocks.get(sessionId) ?? Promise.resolve();
328
+ let release = () => { };
329
+ const gate = new Promise(resolve => {
330
+ release = () => resolve(undefined);
331
+ });
332
+ const tail = previous.then(() => gate);
333
+ promptLocks.set(sessionId, tail);
334
+ await previous;
335
+ try {
336
+ return await fn();
337
+ }
338
+ finally {
339
+ release();
340
+ if (promptLocks.get(sessionId) === tail)
341
+ promptLocks.delete(sessionId);
342
+ }
343
+ }
344
+ /**
345
+ * @param {string} sessionId
346
+ */
347
+ function botMarked(sessionId) {
348
+ if (options.sessionCwd === '')
349
+ return false;
350
+ try {
351
+ const file = join(sessionDirectory(sessionsRoot, options.sessionCwd, sessionId), 'bot.json');
352
+ const parsed = JSON.parse(readFileSync(file, 'utf8'));
353
+ return parsed?.kind === 'bot' && parsed?.sessionId === sessionId;
354
+ }
355
+ catch {
356
+ return false;
357
+ }
358
+ }
359
+ /**
360
+ * @param {import('node:http').IncomingMessage} req
361
+ * @param {string} sessionId
362
+ * @returns {Promise<boolean | null>}
363
+ */
364
+ async function sessionRunning(req, sessionId) {
365
+ const listed = await options.rpc('session/list', { _request: {} }, req);
366
+ if (listed.body?.result?.ok !== true || !Array.isArray(listed.body.result.value?.items))
367
+ return null;
368
+ const item = listed.body.result.value.items.find(entry => entry?.sessionId === sessionId);
369
+ return item?.running === true;
370
+ }
371
+ /**
372
+ * Idle sessions queue. A live bot turn is cancelled, then the new text is a new turn.
373
+ * The cancel is only the main session. Worker sessions are not addressed here.
374
+ * @param {import('node:http').IncomingMessage} req
375
+ * @param {string} sessionId
376
+ * @param {string} text
377
+ * @param {string} requestId
378
+ */
379
+ async function deliverPrompt(req, sessionId, text, requestId) {
380
+ const running = await sessionRunning(req, sessionId);
381
+ if (running === null) {
382
+ return { ok: false, status: 502, error: 'session_unreadable', reason: 'Could not tell whether the session is still running.', upstreamCode: '' };
383
+ }
384
+ let interrupted = false;
385
+ if (running && (options.isBot(sessionId) || botMarked(sessionId))) {
386
+ interrupted = true;
387
+ await options.hold(sessionId);
388
+ const cancelled = await options.rpc('session/cancel', { request: { sessionId } }, req);
389
+ if (cancelled.body?.result?.ok !== true) {
390
+ await options.release(sessionId);
391
+ return {
392
+ ok: false,
393
+ status: 502,
394
+ error: 'cancel_failed',
395
+ reason: cancelled.body?.result?.error?.message ?? 'cancel failed',
396
+ upstreamCode: cancelled.body?.result?.error?.code ?? '',
397
+ };
398
+ }
399
+ for (const task of ledger.tasks()) {
400
+ if (task.sessionId === sessionId && task.status === 'accepted' && task.id !== requestId) {
401
+ ledger.updateTask(task.id, { status: 'cancelled', reason: 'interrupted' });
402
+ }
403
+ }
404
+ }
405
+ const prompted = await options.rpc('session/prompt', {
406
+ request: { requestId, sessionId, mode: 'queue', content: [{ type: 'text', text }] },
407
+ }, req);
408
+ if (prompted.body?.result?.ok !== true) {
409
+ if (interrupted)
410
+ await options.release(sessionId);
411
+ return {
412
+ ok: false,
413
+ status: 502,
414
+ error: 'prompt_failed',
415
+ reason: prompted.body?.result?.error?.message ?? 'prompt failed',
416
+ upstreamCode: prompted.body?.result?.error?.code ?? '',
417
+ };
418
+ }
419
+ return { ok: true, interrupted };
420
+ }
421
+ }
422
+ /**
423
+ * @param {string} path
424
+ */
425
+ function subpath(path) {
426
+ if (path === API)
427
+ return '/';
428
+ if (!path.startsWith(`${API}/`))
429
+ return null;
430
+ return path.slice(API.length);
431
+ }
432
+ /**
433
+ * @param {import('node:http').IncomingMessage} req
434
+ * @param {Record<string, unknown>} body
435
+ */
436
+ function idempotencyOf(req, body) {
437
+ const value = req.headers['idempotency-key'];
438
+ const header = typeof value === 'string' ? value : '';
439
+ if (header !== '')
440
+ return header;
441
+ return typeof body.idempotencyKey === 'string' ? body.idempotencyKey : '';
442
+ }
443
+ /**
444
+ * Keep a preview path inside a session workspace: relative, no parent segments.
445
+ * @param {string} value
446
+ * @returns {string | null}
447
+ */
448
+ function workspaceRelativePath(value) {
449
+ if (value.length === 0 || value.length > 512 || /[\u0000-\u001f\\?#]/.test(value))
450
+ return null;
451
+ if (value.startsWith('/') || /^[a-zA-Z]:/.test(value))
452
+ return null;
453
+ const parts = [];
454
+ for (const part of value.split('/')) {
455
+ if (part === '' || part === '.')
456
+ continue;
457
+ if (part === '..')
458
+ return null;
459
+ parts.push(part);
460
+ }
461
+ return parts.length === 0 ? null : parts.join('/');
462
+ }
463
+ /**
464
+ * @param {unknown} value
465
+ * @returns {any}
466
+ */
467
+ function redactSecrets(value) {
468
+ if (Array.isArray(value))
469
+ return value.map(redactSecrets);
470
+ if (value !== null && typeof value === 'object') {
471
+ /** @type {Record<string, unknown>} */
472
+ const out = {};
473
+ for (const [key, inner] of Object.entries(value)) {
474
+ if (SECRET_KEY.test(key))
475
+ continue;
476
+ out[key] = redactSecrets(inner);
477
+ }
478
+ return out;
479
+ }
480
+ return value;
481
+ }
482
+ /**
483
+ * @param {import('node:http').IncomingMessage} req
484
+ * @returns {Promise<Record<string, unknown>>}
485
+ */
486
+ function readJson(req) {
487
+ return new Promise((resolve, reject) => {
488
+ const chunks = [];
489
+ let size = 0;
490
+ req.on('data', (chunk) => {
491
+ size += chunk.length;
492
+ if (size > 32_768) {
493
+ reject(Object.assign(new Error('body too large'), { code: 'VALIDATION' }));
494
+ req.destroy();
495
+ return;
496
+ }
497
+ chunks.push(chunk);
498
+ });
499
+ req.on('end', () => {
500
+ if (chunks.length === 0) {
501
+ resolve({});
502
+ return;
503
+ }
504
+ try {
505
+ const parsed = JSON.parse(Buffer.concat(chunks).toString('utf8'));
506
+ resolve(parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {});
507
+ }
508
+ catch (error) {
509
+ reject(Object.assign(error instanceof Error ? error : new Error('invalid json'), { code: 'VALIDATION' }));
510
+ }
511
+ });
512
+ req.on('error', reject);
513
+ });
514
+ }
515
+ /**
516
+ * @typedef {object} RpcEnvelope
517
+ * @property {{ ok?: boolean, value?: any, error?: { message?: string, code?: string } }} [result]
518
+ */