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

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/engine.js ADDED
@@ -0,0 +1,733 @@
1
+ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
2
+ import { join } from 'node:path';
3
+ import { sha256, readContained, ensureDir } from "./fs-safe.js";
4
+ import { now } from "./store.js";
5
+ import { splitPersona } from "./context.js";
6
+ import { toolError } from "./errors.js";
7
+ const SESSION_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,200}$/;
8
+ const SKILL_ID = /^[a-z0-9][a-z0-9-]{0,64}$/;
9
+ const EMPTY_STATE = { currentGoal: '', todos: [], pointers: [], notes: '' };
10
+ /**
11
+ * @param {import('./store.js').Store} store
12
+ */
13
+ export function createEngine(store) {
14
+ return new Engine(store);
15
+ }
16
+ export class Engine {
17
+ store;
18
+ openViews;
19
+ surface;
20
+ /**
21
+ * @param {import('./store.js').Store} store
22
+ */
23
+ constructor(store) {
24
+ this.store = store;
25
+ /** @type {Map<string, { revision: number, turn: number | null }>} */
26
+ this.openViews = new Map();
27
+ /** @type {Map<string, { seq: number | null, textIncludes: boolean }>} */
28
+ this.surface = new Map();
29
+ }
30
+ /**
31
+ * @param {string} sessionId
32
+ * @param {{ parentSessionId?: string | null, seeded?: boolean }} [fork]
33
+ */
34
+ ensureSession(sessionId, fork = {}) {
35
+ assertSessionId(sessionId);
36
+ const existing = this.binding(sessionId);
37
+ if (existing)
38
+ return existing;
39
+ const created = now();
40
+ this.store.db.prepare(`
41
+ INSERT INTO session_bindings (
42
+ session_id, kind, status, schema_version, persona_version_id, fork_parent_session_id,
43
+ fork_seeded, last_view_revision, compaction_epoch, error_code, created_at, updated_at
44
+ ) VALUES (?, 'session', 'active', 1, NULL, ?, ?, 0, 0, NULL, ?, ?)
45
+ `).run(sessionId, fork.parentSessionId ?? null, fork.seeded ? 1 : 0, created, created);
46
+ return this.binding(sessionId);
47
+ }
48
+ /**
49
+ * @param {string} sessionId
50
+ */
51
+ binding(sessionId) {
52
+ return this.store.db.prepare('SELECT * FROM session_bindings WHERE session_id = ?').get(sessionId) ?? null;
53
+ }
54
+ /**
55
+ * Ordinary sessions stay kind `session`. A bound persona is an assistant identity,
56
+ * so binding one marks the session as a BOT. Startup also promotes older rows
57
+ * that already had a persona and were left as `session` by the kind default.
58
+ * @param {string} sessionId
59
+ */
60
+ isBot(sessionId) {
61
+ return this.binding(sessionId)?.kind === 'bot';
62
+ }
63
+ /**
64
+ * @param {string} sessionId
65
+ */
66
+ markBot(sessionId) {
67
+ assertSessionId(sessionId);
68
+ const existing = this.binding(sessionId);
69
+ const stamped = now();
70
+ if (existing) {
71
+ if (existing.kind !== 'bot') {
72
+ this.store.db.prepare(`UPDATE session_bindings SET kind = 'bot', updated_at = ? WHERE session_id = ?`).run(stamped, sessionId);
73
+ }
74
+ return this.binding(sessionId);
75
+ }
76
+ this.store.db.prepare(`
77
+ INSERT INTO session_bindings (
78
+ session_id, kind, status, schema_version, persona_version_id, fork_parent_session_id,
79
+ fork_seeded, last_view_revision, compaction_epoch, error_code, created_at, updated_at
80
+ ) VALUES (?, 'bot', 'active', 1, NULL, NULL, 0, 0, 0, NULL, ?, ?)
81
+ `).run(sessionId, stamped, stamped);
82
+ return this.binding(sessionId);
83
+ }
84
+ listBots() {
85
+ return this.store.db.prepare(`
86
+ SELECT session_id, persona_version_id FROM session_bindings WHERE kind = 'bot' ORDER BY created_at
87
+ `).all().map(row => {
88
+ const persona = row.persona_version_id == null ? null : this.persona(row.persona_version_id);
89
+ const bytes = persona ? this.store.readBlob('persona', persona.content_hash) : null;
90
+ const name = bytes ? splitPersona(bytes.toString('utf8')).name : '';
91
+ return { sessionId: row.session_id, name };
92
+ });
93
+ }
94
+ latestPersona() {
95
+ return this.store.db.prepare('SELECT * FROM persona_versions ORDER BY id DESC LIMIT 1').get() ?? null;
96
+ }
97
+ /**
98
+ * @param {number} id
99
+ */
100
+ persona(id) {
101
+ return this.store.db.prepare('SELECT * FROM persona_versions WHERE id = ?').get(id) ?? null;
102
+ }
103
+ /**
104
+ * @param {{ id: number, content_hash: string }} persona
105
+ */
106
+ personaBlobOk(persona) {
107
+ const bytes = this.store.readBlob('persona', persona.content_hash);
108
+ return bytes != null && sha256(bytes) === persona.content_hash;
109
+ }
110
+ /**
111
+ * User-confirmed SOUL. The model cannot call this.
112
+ * @param {string} text
113
+ * @param {string} [note]
114
+ */
115
+ confirmPersona(text, note) {
116
+ const bytes = Buffer.from(text, 'utf8');
117
+ const hash = sha256(bytes);
118
+ this.store.writeBlob('persona', hash, bytes);
119
+ const existing = this.store.db.prepare('SELECT * FROM persona_versions WHERE content_hash = ?').get(hash);
120
+ if (existing)
121
+ return existing;
122
+ const created = now();
123
+ this.store.db.prepare(`
124
+ INSERT INTO persona_versions (content_hash, byte_length, note, created_by, created_at)
125
+ VALUES (?, ?, ?, 'user', ?)
126
+ `).run(hash, bytes.length, note ?? null, created);
127
+ return this.store.db.prepare('SELECT * FROM persona_versions WHERE content_hash = ?').get(hash);
128
+ }
129
+ /**
130
+ * @param {string} sessionId
131
+ * @param {number | null} personaId
132
+ */
133
+ bindPersona(sessionId, personaId) {
134
+ if (personaId != null)
135
+ this.markBot(sessionId);
136
+ else
137
+ this.ensureSession(sessionId);
138
+ if (personaId == null) {
139
+ this.store.db.prepare(`
140
+ UPDATE session_bindings
141
+ SET persona_version_id = NULL, status = 'active', error_code = NULL, updated_at = ?
142
+ WHERE session_id = ?
143
+ `).run(now(), sessionId);
144
+ return this.binding(sessionId);
145
+ }
146
+ const persona = this.persona(personaId);
147
+ if (!persona)
148
+ throw Object.assign(new Error('persona not found'), { code: 'NOT_FOUND' });
149
+ if (!this.personaBlobOk(persona)) {
150
+ this.markError(sessionId, 'HASH_MISMATCH');
151
+ throw Object.assign(new Error('persona blob does not match its hash'), { code: 'HASH_MISMATCH' });
152
+ }
153
+ this.store.db.prepare(`
154
+ UPDATE session_bindings
155
+ SET persona_version_id = ?, status = 'active', error_code = NULL, updated_at = ?
156
+ WHERE session_id = ?
157
+ `).run(personaId, now(), sessionId);
158
+ return this.binding(sessionId);
159
+ }
160
+ /**
161
+ * @param {string} sessionId
162
+ * @param {string} code
163
+ */
164
+ markError(sessionId, code) {
165
+ this.store.db.prepare(`
166
+ UPDATE session_bindings SET status = 'error', error_code = ?, updated_at = ? WHERE session_id = ?
167
+ `).run(code, now(), sessionId);
168
+ }
169
+ /**
170
+ * @param {string} sessionId
171
+ * @param {string | null} watermark
172
+ */
173
+ noteWatermark(sessionId, watermark) {
174
+ if (!this.binding(sessionId) || watermark == null)
175
+ return;
176
+ const current = this.binding(sessionId).last_event_watermark;
177
+ if (current != null && BigInt(current) >= BigInt(watermark))
178
+ return;
179
+ this.store.db.prepare(`
180
+ UPDATE session_bindings SET last_event_watermark = ?, updated_at = ? WHERE session_id = ?
181
+ `).run(watermark, now(), sessionId);
182
+ }
183
+ /**
184
+ * @param {string} sessionId
185
+ * @param {string | undefined} sourceEventId
186
+ */
187
+ checkSource(sessionId, sourceEventId) {
188
+ if (sourceEventId == null || sourceEventId === '')
189
+ return null;
190
+ if (!/^\d+$/.test(sourceEventId))
191
+ return toolError('VALIDATION', 'sourceEventId must be an event sequence number in this session.');
192
+ const watermark = this.binding(sessionId)?.last_event_watermark;
193
+ if (watermark == null || BigInt(sourceEventId) > BigInt(watermark)) {
194
+ return toolError('VALIDATION', 'sourceEventId is outside the events this session has observed.');
195
+ }
196
+ return null;
197
+ }
198
+ /**
199
+ * @param {string} sessionId
200
+ * @param {number} turn
201
+ */
202
+ freeze(sessionId, turn) {
203
+ const binding = this.ensureSession(sessionId);
204
+ const state = this.stateRow(sessionId);
205
+ const facts = this.store.db.prepare(`
206
+ SELECT id FROM facts WHERE session_id = ? AND status = 'active'
207
+ ORDER BY priority DESC, updated_at DESC, id DESC
208
+ `).all(sessionId).map(row => row.id);
209
+ const skills = this.store.db.prepare(`
210
+ SELECT skill_id, version, summary, enabled, revoked, scope
211
+ FROM skill_bindings WHERE session_id = ? ORDER BY skill_id
212
+ `).all(sessionId);
213
+ const selected = {
214
+ factIds: facts,
215
+ memoryIds: [],
216
+ personaVersionId: binding.persona_version_id,
217
+ workingStateRev: state?.revision ?? 0,
218
+ skills,
219
+ };
220
+ const revision = binding.last_view_revision + 1;
221
+ const frozenAt = now();
222
+ this.store.db.prepare(`
223
+ INSERT INTO view_revisions (
224
+ session_id, revision, frozen_at, event_watermark, persona_version_id, working_state_rev,
225
+ snapshot_hash, compaction_epoch, presence, selected_json
226
+ ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'unknown', ?)
227
+ `).run(sessionId, revision, frozenAt, binding.last_event_watermark, binding.persona_version_id, state?.revision ?? 0, 'pending', binding.compaction_epoch, JSON.stringify(selected));
228
+ this.store.db.prepare(`
229
+ UPDATE session_bindings SET last_view_revision = ?, updated_at = ? WHERE session_id = ?
230
+ `).run(revision, frozenAt, sessionId);
231
+ this.openViews.set(sessionId, { revision, turn });
232
+ return this.view(sessionId, revision);
233
+ }
234
+ /**
235
+ * @param {string} sessionId
236
+ * @param {number} [turn]
237
+ */
238
+ viewForTurn(sessionId, turn) {
239
+ const open = this.openViews.get(sessionId);
240
+ if (open && (turn == null || open.turn === turn))
241
+ return this.view(sessionId, open.revision);
242
+ return this.freeze(sessionId, turn ?? -1);
243
+ }
244
+ /**
245
+ * @param {string} sessionId
246
+ * @param {number} revision
247
+ */
248
+ view(sessionId, revision) {
249
+ const row = this.store.db.prepare(`
250
+ SELECT * FROM view_revisions WHERE session_id = ? AND revision = ?
251
+ `).get(sessionId, revision);
252
+ if (!row)
253
+ return null;
254
+ return { ...row, selected: JSON.parse(row.selected_json) };
255
+ }
256
+ /**
257
+ * @param {string} sessionId
258
+ */
259
+ currentView(sessionId) {
260
+ const open = this.openViews.get(sessionId);
261
+ if (open)
262
+ return this.view(sessionId, open.revision);
263
+ const binding = this.binding(sessionId);
264
+ if (!binding || binding.last_view_revision === 0)
265
+ return null;
266
+ return this.view(sessionId, binding.last_view_revision);
267
+ }
268
+ /**
269
+ * @param {string} sessionId
270
+ * @param {number} revision
271
+ * @param {string} hash
272
+ * @param {'present' | 'unknown' | 'needs_reinject'} presence
273
+ */
274
+ recordSnapshot(sessionId, revision, hash, presence) {
275
+ this.store.db.prepare(`
276
+ UPDATE view_revisions SET snapshot_hash = ?, presence = ? WHERE session_id = ? AND revision = ?
277
+ `).run(hash, presence, sessionId, revision);
278
+ }
279
+ /**
280
+ * Adapter-internal counter. Not a DSH field.
281
+ * @param {string} sessionId
282
+ * @param {'needs_reinject' | 'unknown'} presence
283
+ */
284
+ bumpEpoch(sessionId, presence) {
285
+ const binding = this.binding(sessionId);
286
+ if (!binding)
287
+ return;
288
+ const epoch = binding.compaction_epoch + 1;
289
+ this.store.db.prepare(`
290
+ UPDATE session_bindings SET compaction_epoch = ?, updated_at = ? WHERE session_id = ?
291
+ `).run(epoch, now(), sessionId);
292
+ this.store.db.prepare(`
293
+ UPDATE view_revisions
294
+ SET compaction_epoch = ?, presence = ?
295
+ WHERE session_id = ? AND revision = ?
296
+ `).run(epoch, presence, sessionId, binding.last_view_revision);
297
+ }
298
+ /**
299
+ * @param {string} sessionId
300
+ * @param {number | null} seq
301
+ */
302
+ noteSurface(sessionId, seq) {
303
+ this.surface.set(sessionId, { seq, textIncludes: true });
304
+ const binding = this.binding(sessionId);
305
+ if (!binding)
306
+ return;
307
+ this.store.db.prepare(`
308
+ UPDATE view_revisions SET presence = 'present'
309
+ WHERE session_id = ? AND revision = ? AND snapshot_hash != 'pending'
310
+ `).run(sessionId, binding.last_view_revision);
311
+ }
312
+ /**
313
+ * @param {string} sessionId
314
+ * @param {number[]} sourceSeqs
315
+ */
316
+ noteRemoval(sessionId, sourceSeqs) {
317
+ const retained = this.surface.get(sessionId);
318
+ if (retained?.seq != null && sourceSeqs.includes(retained.seq)) {
319
+ this.surface.set(sessionId, { seq: null, textIncludes: false });
320
+ this.bumpEpoch(sessionId, 'needs_reinject');
321
+ return true;
322
+ }
323
+ return false;
324
+ }
325
+ /**
326
+ * @param {string} sessionId
327
+ */
328
+ stateRow(sessionId) {
329
+ return this.store.db.prepare('SELECT * FROM working_state WHERE session_id = ?').get(sessionId) ?? null;
330
+ }
331
+ /**
332
+ * @param {string} sessionId
333
+ */
334
+ statePayload(sessionId) {
335
+ const row = this.stateRow(sessionId);
336
+ if (!row)
337
+ return { revision: 0, payload: { ...EMPTY_STATE, todos: [], pointers: [] } };
338
+ return { revision: row.revision, payload: JSON.parse(row.payload_json) };
339
+ }
340
+ /**
341
+ * @param {string} sessionId
342
+ */
343
+ revokedSkills(sessionId) {
344
+ return this.store.db.prepare(`
345
+ SELECT skill_id, version FROM skill_bindings
346
+ WHERE session_id = ? AND revoked = 1 ORDER BY skill_id
347
+ `).all(sessionId);
348
+ }
349
+ /**
350
+ * @param {number[]} ids
351
+ */
352
+ factsByIds(ids) {
353
+ if (ids.length === 0)
354
+ return [];
355
+ const rows = this.store.db.prepare(`SELECT * FROM facts WHERE id IN (${ids.map(() => '?').join(',')})`).all(...ids);
356
+ const byId = new Map(rows.map(row => [row.id, row]));
357
+ return ids.map(id => byId.get(id)).filter(Boolean);
358
+ }
359
+ /**
360
+ * @param {string} sessionId
361
+ * @param {string} idempotencyKey
362
+ * @param {string} payloadHash
363
+ * @param {string} toolName
364
+ * @param {unknown} request
365
+ * @param {() => Record<string, unknown>} apply
366
+ * @param {number} viewRevision
367
+ */
368
+ mutate(sessionId, idempotencyKey, payloadHash, toolName, request, apply, viewRevision) {
369
+ const prior = this.store.db.prepare(`
370
+ SELECT * FROM mutations WHERE scope = ? AND idempotency_key = ?
371
+ `).get(sessionId, idempotencyKey);
372
+ if (prior) {
373
+ if (prior.payload_hash !== payloadHash)
374
+ return toolError('IDEMPOTENCY_KEY_REUSE', 'The same idempotency key was reused for different content.');
375
+ const stored = JSON.parse(prior.result_json);
376
+ return { ...stored, outcome: 'replayed', viewRevisionFrozen: viewRevision };
377
+ }
378
+ const data = apply();
379
+ if (data.ok === false)
380
+ return data;
381
+ const result = {
382
+ ok: true,
383
+ outcome: 'applied',
384
+ viewRevisionFrozen: viewRevision,
385
+ storeRevision: data.storeRevision,
386
+ data: data.data,
387
+ export: 'pending',
388
+ };
389
+ const info = this.store.db.prepare(`
390
+ INSERT INTO mutations (
391
+ scope, idempotency_key, payload_hash, tool_name, request_json, result_json, outcome, created_at
392
+ ) VALUES (?, ?, ?, ?, ?, ?, 'applied', ?)
393
+ `).run(sessionId, idempotencyKey, payloadHash, toolName, JSON.stringify(request), JSON.stringify(result), now());
394
+ this.store.db.prepare(`
395
+ INSERT INTO export_outbox (session_id, mutation_id, status, attempts, updated_at)
396
+ VALUES (?, ?, 'pending', 0, ?)
397
+ `).run(sessionId, Number(info.lastInsertRowid), now());
398
+ return { ...result, mutationId: Number(info.lastInsertRowid) };
399
+ }
400
+ /**
401
+ * @param {string} sessionId
402
+ */
403
+ async flushExport(sessionId) {
404
+ const rows = this.store.db.prepare(`
405
+ SELECT * FROM export_outbox WHERE session_id = ? AND status IN ('pending','failed') ORDER BY id
406
+ `).all(sessionId);
407
+ for (const row of rows)
408
+ await this.exportOne(row);
409
+ }
410
+ /**
411
+ * @param {{ id: number, session_id: string, attempts: number }} row
412
+ */
413
+ async exportOne(row) {
414
+ try {
415
+ const text = this.exportMarkdown(row.session_id);
416
+ const dir = join(this.store.root, 'export', row.session_id);
417
+ mkdirSync(dir, { recursive: true, mode: 0o700 });
418
+ writeFileSync(join(dir, 'memory.md'), text, { mode: 0o600 });
419
+ this.store.db.prepare(`
420
+ UPDATE export_outbox SET status = 'done', attempts = ?, last_error = NULL, updated_at = ? WHERE id = ?
421
+ `).run(row.attempts + 1, now(), row.id);
422
+ return { ok: true };
423
+ }
424
+ catch (error) {
425
+ const message = error instanceof Error ? error.message : String(error);
426
+ this.store.db.prepare(`
427
+ UPDATE export_outbox SET status = 'failed', attempts = ?, last_error = ?, updated_at = ? WHERE id = ?
428
+ `).run(row.attempts + 1, message, now(), row.id);
429
+ return { ok: false, error: message };
430
+ }
431
+ }
432
+ /**
433
+ * @param {string} sessionId
434
+ */
435
+ exportMarkdown(sessionId) {
436
+ const facts = this.store.db.prepare(`
437
+ SELECT id, revision, content, status FROM facts WHERE session_id = ? ORDER BY id
438
+ `).all(sessionId);
439
+ const memories = this.store.db.prepare(`
440
+ SELECT id, revision, title, content, status FROM memories WHERE session_id = ? ORDER BY id
441
+ `).all(sessionId);
442
+ const state = this.statePayload(sessionId);
443
+ const lines = [`# session ${sessionId}`, '', '## facts'];
444
+ for (const fact of facts) {
445
+ lines.push(fact.status === 'forgotten' ? `- forgotten:${fact.id}` : `- ${fact.id} rev ${fact.revision} (${fact.status}): ${fact.content}`);
446
+ }
447
+ lines.push('', '## memories');
448
+ for (const memory of memories) {
449
+ lines.push(memory.status === 'forgotten'
450
+ ? `- forgotten:${memory.id}`
451
+ : `- ${memory.id} rev ${memory.revision} (${memory.status}) ${memory.title ?? ''}: ${memory.content}`);
452
+ }
453
+ lines.push('', '## working state', '```json', JSON.stringify(state.payload), '```', '');
454
+ return lines.join('\n');
455
+ }
456
+ /**
457
+ * @param {string} sessionId
458
+ * @param {string} query
459
+ * @param {number} limit
460
+ */
461
+ recall(sessionId, query, limit) {
462
+ const ftsFacts = searchFts(this.store.db, 'facts_fts', 'content', sessionId, 'facts', query, limit);
463
+ const ftsMemories = searchFts(this.store.db, 'memories_fts', 'title, content', sessionId, 'memories', query, limit);
464
+ let strategy = 'fts';
465
+ let facts = ftsFacts;
466
+ let memories = ftsMemories;
467
+ if (facts.length === 0 && memories.length === 0 && query.length <= 32) {
468
+ strategy = 'substring';
469
+ const like = `%${query.replace(/[\\%_]/g, char => `\\${char}`)}%`;
470
+ facts = this.store.db.prepare(`
471
+ SELECT id, content, revision, priority FROM facts
472
+ WHERE session_id = ? AND status = 'active' AND content LIKE ? ESCAPE '\\'
473
+ ORDER BY priority DESC, updated_at DESC LIMIT ?
474
+ `).all(sessionId, like, limit);
475
+ memories = this.store.db.prepare(`
476
+ SELECT id, title, content, revision FROM memories
477
+ WHERE session_id = ? AND status = 'active' AND (content LIKE ? ESCAPE '\\' OR ifnull(title,'') LIKE ? ESCAPE '\\')
478
+ ORDER BY updated_at DESC LIMIT ?
479
+ `).all(sessionId, like, like, limit);
480
+ }
481
+ return { strategy, facts, memories };
482
+ }
483
+ /**
484
+ * @param {string} sessionId
485
+ * @param {'private' | 'public'} scope
486
+ * @param {string} skillId
487
+ * @param {string} version
488
+ * @param {string} summary
489
+ * @param {Buffer} bytes
490
+ */
491
+ registerSkill(sessionId, scope, skillId, version, summary, bytes) {
492
+ assertSessionId(sessionId);
493
+ if (!SKILL_ID.test(skillId))
494
+ throw Object.assign(new Error('invalid skill id'), { code: 'VALIDATION' });
495
+ this.ensureSession(sessionId);
496
+ const existing = this.skillRow(sessionId, skillId);
497
+ if (existing && existing.scope === 'private' && scope === 'public') {
498
+ throw Object.assign(new Error('private skill keeps this id'), { code: 'FORBIDDEN' });
499
+ }
500
+ const hash = sha256(bytes);
501
+ this.store.writeBlob('skill', hash, bytes);
502
+ const reread = this.store.readBlob('skill', hash);
503
+ if (reread == null || sha256(reread) !== hash) {
504
+ throw Object.assign(new Error('skill blob mismatch'), { code: 'HASH_MISMATCH' });
505
+ }
506
+ const boundAt = now();
507
+ this.store.db.prepare(`
508
+ INSERT INTO skill_bindings (
509
+ session_id, skill_id, scope, version, content_hash, summary, enabled, revoked, bound_at
510
+ ) VALUES (?, ?, ?, ?, ?, ?, 1, 0, ?)
511
+ ON CONFLICT(session_id, skill_id) DO UPDATE SET
512
+ scope = excluded.scope,
513
+ version = excluded.version,
514
+ content_hash = excluded.content_hash,
515
+ summary = excluded.summary,
516
+ enabled = 1,
517
+ revoked = 0,
518
+ bound_at = excluded.bound_at
519
+ `).run(sessionId, skillId, scope, version, hash, summary, boundAt);
520
+ return this.skillRow(sessionId, skillId);
521
+ }
522
+ /**
523
+ * @param {string} sessionId
524
+ * @param {string} skillId
525
+ */
526
+ skillRow(sessionId, skillId) {
527
+ return this.store.db.prepare(`
528
+ SELECT * FROM skill_bindings WHERE session_id = ? AND skill_id = ?
529
+ `).get(sessionId, skillId) ?? null;
530
+ }
531
+ /**
532
+ * @param {string} sessionId
533
+ * @param {string} skillId
534
+ * @param {{ enabled?: boolean, revoked?: boolean }} patch
535
+ */
536
+ setSkillFlags(sessionId, skillId, patch) {
537
+ const row = this.skillRow(sessionId, skillId);
538
+ if (!row)
539
+ throw Object.assign(new Error('skill not bound'), { code: 'NOT_FOUND' });
540
+ const enabled = patch.enabled == null ? row.enabled : (patch.enabled ? 1 : 0);
541
+ const revoked = patch.revoked == null ? row.revoked : (patch.revoked ? 1 : 0);
542
+ this.store.db.prepare(`
543
+ UPDATE skill_bindings SET enabled = ?, revoked = ?, bound_at = ? WHERE session_id = ? AND skill_id = ?
544
+ `).run(enabled, revoked, now(), sessionId, skillId);
545
+ return this.skillRow(sessionId, skillId);
546
+ }
547
+ /**
548
+ * @param {string} sessionId
549
+ * @param {string} skillId
550
+ */
551
+ loadSkill(sessionId, skillId) {
552
+ const binding = this.binding(sessionId);
553
+ if (!binding)
554
+ return toolError('NOT_FOUND', 'This session has no binding yet.');
555
+ if (binding.status === 'error')
556
+ return toolError('UNAVAILABLE', `Binding is ${binding.error_code ?? 'error'}.`);
557
+ const row = this.skillRow(sessionId, skillId);
558
+ if (!row)
559
+ return toolError('NOT_FOUND', 'This session has no binding for that skill.');
560
+ if (row.revoked === 1)
561
+ return toolError('REVOKED', 'That skill is revoked.');
562
+ if (row.enabled !== 1)
563
+ return toolError('FORBIDDEN', 'That skill is not enabled.');
564
+ const bytes = this.store.readBlob('skill', row.content_hash);
565
+ if (bytes == null || sha256(bytes) !== row.content_hash) {
566
+ return toolError('HASH_MISMATCH', 'The skill text hash does not match the binding.');
567
+ }
568
+ return {
569
+ ok: true,
570
+ outcome: 'applied',
571
+ data: {
572
+ skillId: row.skill_id,
573
+ version: row.version,
574
+ scope: row.scope,
575
+ contentHash: row.content_hash,
576
+ body: bytes.toString('utf8'),
577
+ grantsTools: false,
578
+ },
579
+ };
580
+ }
581
+ /**
582
+ * Read a user-managed source file and register its bytes.
583
+ * @param {string} sessionId
584
+ * @param {'private' | 'public'} scope
585
+ * @param {string} skillId
586
+ */
587
+ registerSkillFromDisk(sessionId, scope, skillId) {
588
+ assertSessionId(sessionId);
589
+ if (!SKILL_ID.test(skillId))
590
+ throw Object.assign(new Error('invalid skill id'), { code: 'VALIDATION' });
591
+ const root = scope === 'public'
592
+ ? join(this.store.root, 'src', 'skills', 'public')
593
+ : join(this.store.root, 'src', 'skills', 'private', sessionId);
594
+ ensureDir(root);
595
+ const file = join(root, skillId, 'SKILL.md');
596
+ if (!existsSync(file))
597
+ throw Object.assign(new Error('SKILL.md not found'), { code: 'NOT_FOUND' });
598
+ const bytes = readContained(root, file);
599
+ const text = bytes.toString('utf8');
600
+ const version = /^\s*version:\s*(\S+)/m.exec(text)?.[1] ?? '0.0.0';
601
+ const summary = /^\s*description:\s*(.+)$/m.exec(text)?.[1]?.trim() ?? '';
602
+ return this.registerSkill(sessionId, scope, skillId, version, summary.slice(0, 240), bytes);
603
+ }
604
+ recover() {
605
+ const report = { bindings: 0, errors: [], promoted: [], ftsRebuilt: false, exports: [] };
606
+ const personas = this.store.db.prepare('SELECT * FROM persona_versions').all();
607
+ for (const persona of personas) {
608
+ if (!this.personaBlobOk(persona))
609
+ report.errors.push({ persona: persona.id, code: 'HASH_MISMATCH' });
610
+ }
611
+ const bindings = this.store.db.prepare('SELECT * FROM session_bindings').all();
612
+ for (const binding of bindings) {
613
+ report.bindings += 1;
614
+ if (binding.persona_version_id != null) {
615
+ const persona = this.persona(binding.persona_version_id);
616
+ if (!persona || !this.personaBlobOk(persona))
617
+ this.markError(binding.session_id, 'HASH_MISMATCH');
618
+ else if (binding.kind !== 'bot') {
619
+ this.markBot(binding.session_id);
620
+ report.promoted.push(binding.session_id);
621
+ }
622
+ }
623
+ const skills = this.store.db.prepare(`
624
+ SELECT * FROM skill_bindings WHERE session_id = ? AND enabled = 1 AND revoked = 0
625
+ `).all(binding.session_id);
626
+ for (const skill of skills) {
627
+ const bytes = this.store.readBlob('skill', skill.content_hash);
628
+ if (bytes == null || sha256(bytes) !== skill.content_hash) {
629
+ this.markError(binding.session_id, 'HASH_MISMATCH');
630
+ report.errors.push({ sessionId: binding.session_id, skillId: skill.skill_id, code: 'HASH_MISMATCH' });
631
+ }
632
+ }
633
+ if (binding.last_view_revision > 0) {
634
+ this.store.db.prepare(`
635
+ UPDATE view_revisions SET presence = 'unknown'
636
+ WHERE session_id = ? AND revision = ? AND presence = 'present'
637
+ `).run(binding.session_id, binding.last_view_revision);
638
+ }
639
+ }
640
+ report.ftsRebuilt = rebuildFtsIfNeeded(this.store.db);
641
+ return report;
642
+ }
643
+ }
644
+ /**
645
+ * @param {string} sessionId
646
+ */
647
+ export function assertSessionId(sessionId) {
648
+ if (!SESSION_ID.test(sessionId)) {
649
+ throw Object.assign(new Error('session id rejected'), { code: 'VALIDATION' });
650
+ }
651
+ }
652
+ /**
653
+ * @param {import('node:sqlite').DatabaseSync} db
654
+ * @param {string} fts
655
+ * @param {string} columns
656
+ * @param {string} sessionId
657
+ * @param {'facts' | 'memories'} table
658
+ * @param {string} query
659
+ * @param {number} limit
660
+ */
661
+ function searchFts(db, fts, columns, sessionId, table, query, limit) {
662
+ const match = `"${query.replaceAll('"', ' ')}"`;
663
+ try {
664
+ if (table === 'facts') {
665
+ return db.prepare(`
666
+ SELECT f.id, f.content, f.revision, f.priority
667
+ FROM facts_fts
668
+ JOIN facts f ON f.id = facts_fts.rowid
669
+ WHERE facts_fts MATCH ? AND f.session_id = ? AND f.status = 'active'
670
+ LIMIT ?
671
+ `).all(match, sessionId, limit);
672
+ }
673
+ return db.prepare(`
674
+ SELECT m.id, m.title, m.content, m.revision
675
+ FROM memories_fts
676
+ JOIN memories m ON m.id = memories_fts.rowid
677
+ WHERE memories_fts MATCH ? AND m.session_id = ? AND m.status = 'active'
678
+ LIMIT ?
679
+ `).all(match, sessionId, limit);
680
+ }
681
+ catch {
682
+ return [];
683
+ }
684
+ }
685
+ /**
686
+ * @param {import('node:sqlite').DatabaseSync} db
687
+ */
688
+ function rebuildFtsIfNeeded(db) {
689
+ const factCount = db.prepare(`SELECT count(*) AS n FROM facts WHERE status = 'active'`).get().n;
690
+ const memoryCount = db.prepare(`SELECT count(*) AS n FROM memories WHERE status = 'active'`).get().n;
691
+ let ftsFacts = 0;
692
+ let ftsMemories = 0;
693
+ try {
694
+ ftsFacts = db.prepare('SELECT count(*) AS n FROM facts_fts').get().n;
695
+ ftsMemories = db.prepare('SELECT count(*) AS n FROM memories_fts').get().n;
696
+ }
697
+ catch {
698
+ ftsFacts = -1;
699
+ }
700
+ if (ftsFacts === factCount && ftsMemories === memoryCount)
701
+ return false;
702
+ db.exec(`INSERT INTO facts_fts(facts_fts) VALUES('delete-all')`);
703
+ db.exec(`INSERT INTO memories_fts(memories_fts) VALUES('delete-all')`);
704
+ const facts = db.prepare(`SELECT id, content FROM facts WHERE status = 'active'`).all();
705
+ const insertFact = db.prepare('INSERT INTO facts_fts(rowid, content) VALUES (?, ?)');
706
+ for (const fact of facts)
707
+ insertFact.run(fact.id, fact.content);
708
+ const memories = db.prepare(`SELECT id, title, content FROM memories WHERE status = 'active'`).all();
709
+ const insertMemory = db.prepare('INSERT INTO memories_fts(rowid, title, content) VALUES (?, ?, ?)');
710
+ for (const memory of memories)
711
+ insertMemory.run(memory.id, memory.title ?? '', memory.content);
712
+ return true;
713
+ }
714
+ export function syncFactFts(db, id, content, active) {
715
+ if (active)
716
+ db.prepare('INSERT INTO facts_fts(rowid, content) VALUES (?, ?)').run(id, content);
717
+ else
718
+ db.prepare(`INSERT INTO facts_fts(facts_fts, rowid, content) VALUES ('delete', ?, ?)`).run(id, content);
719
+ }
720
+ export function syncMemoryFts(db, id, title, content, active) {
721
+ if (active)
722
+ db.prepare('INSERT INTO memories_fts(rowid, title, content) VALUES (?, ?, ?)').run(id, title ?? '', content);
723
+ else
724
+ db.prepare(`INSERT INTO memories_fts(memories_fts, rowid, title, content) VALUES ('delete', ?, ?, ?)`).run(id, title ?? '', content);
725
+ }
726
+ export { EMPTY_STATE, SKILL_ID };
727
+ /**
728
+ * @param {string} file
729
+ * @returns {string}
730
+ */
731
+ export function readText(file) {
732
+ return readFileSync(file, 'utf8');
733
+ }