sumo-agents 0.0.0-stage → 0.3.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.
Files changed (66) hide show
  1. package/AGENTS.md +38 -0
  2. package/LICENSE +21 -0
  3. package/README.md +111 -2
  4. package/bin/sumo.mjs +33 -0
  5. package/guides/delegation.md +33 -0
  6. package/guides/feature.md +14 -0
  7. package/guides/fix.md +14 -0
  8. package/guides/memory.md +23 -0
  9. package/guides/projects.md +27 -0
  10. package/guides/review.md +16 -0
  11. package/guides/workflows.md +26 -0
  12. package/logo.txt +19 -0
  13. package/package.json +42 -4
  14. package/prompts/agent.md +7 -0
  15. package/prompts/dream.md +13 -0
  16. package/prompts/scribe.md +21 -0
  17. package/spinner.txt +90 -0
  18. package/src/advisor.mjs +59 -0
  19. package/src/apply.mjs +368 -0
  20. package/src/auth.mjs +80 -0
  21. package/src/card.mjs +72 -0
  22. package/src/catalog.mjs +167 -0
  23. package/src/chat.mjs +1162 -0
  24. package/src/cli.mjs +815 -0
  25. package/src/cost.mjs +128 -0
  26. package/src/db.mjs +384 -0
  27. package/src/dream.mjs +97 -0
  28. package/src/editor.mjs +198 -0
  29. package/src/export.mjs +132 -0
  30. package/src/guard.mjs +121 -0
  31. package/src/guides.mjs +86 -0
  32. package/src/herdr.mjs +117 -0
  33. package/src/hooks.mjs +270 -0
  34. package/src/images.mjs +89 -0
  35. package/src/jobs.mjs +1184 -0
  36. package/src/jobtools.mjs +82 -0
  37. package/src/local-server.mjs +169 -0
  38. package/src/lock.mjs +45 -0
  39. package/src/loop.mjs +838 -0
  40. package/src/mcp.mjs +604 -0
  41. package/src/memory.mjs +400 -0
  42. package/src/model.mjs +270 -0
  43. package/src/page.html +304 -0
  44. package/src/page.mjs +135 -0
  45. package/src/paths.mjs +33 -0
  46. package/src/prime.mjs +177 -0
  47. package/src/projects.mjs +232 -0
  48. package/src/recall.mjs +45 -0
  49. package/src/redact.mjs +173 -0
  50. package/src/render.mjs +45 -0
  51. package/src/route.mjs +287 -0
  52. package/src/sandbox.mjs +173 -0
  53. package/src/scan.mjs +204 -0
  54. package/src/scribe.mjs +349 -0
  55. package/src/sessions.mjs +371 -0
  56. package/src/setup.mjs +528 -0
  57. package/src/sqlite.mjs +66 -0
  58. package/src/text.mjs +97 -0
  59. package/src/tools.mjs +987 -0
  60. package/src/transcript.mjs +106 -0
  61. package/src/tty.mjs +529 -0
  62. package/src/ui.mjs +1363 -0
  63. package/src/verify.mjs +369 -0
  64. package/src/web.mjs +49 -0
  65. package/src/workflows.mjs +270 -0
  66. package/src/worktree.mjs +128 -0
package/src/memory.mjs ADDED
@@ -0,0 +1,400 @@
1
+ import { createHash } from 'node:crypto';
2
+ import { getMeta, setMeta, tx } from './db.mjs';
3
+ import { redact } from './redact.mjs';
4
+ import { clip, ftsQuery, overlap, sharedStems, stem, words } from './text.mjs';
5
+ import { matchWithin } from './workflows.mjs';
6
+
7
+ /** How much of a search that found nothing is kept as the record of it. */
8
+ const MISS_KEPT = 200;
9
+
10
+ export const TYPES = ['preference', 'fact', 'decision', 'gotcha', 'procedure'];
11
+
12
+ const IMPORTANCE = { preference: 0.8, procedure: 0.8, decision: 0.7, gotcha: 0.6, fact: 0.5 };
13
+ const PROVENANCE_WEIGHT = { stated: 1, observed: 0.9, scanned: 0.7, inferred: 0.5 };
14
+ /** Days for a memory's rank to fall to 1/e. Absent means it does not age: a preference stays true until superseded. */
15
+ const DECAY_DAYS = { fact: 365, gotcha: 365 };
16
+ const PROJECT_MATCH_BOOST = 1.5;
17
+ const OTHER_PROJECT_PENALTY = 0.5;
18
+ const SIMILAR_OVERLAP = 0.5;
19
+ /** How many search terms a memory carries beside its words, and how long one may be. */
20
+ const KEYS_KEPT = 6;
21
+ const KEY_CHARS = 32;
22
+
23
+ /** Commands no gate may ever catch: a pattern that matches these would hold back everything. */
24
+ const NEVER_GATED = ['', 'ls', 'cd src', 'git status', 'cat README.md'];
25
+ /** Text of the kind that sets a backtracking pattern off: long runs of one character, of words, of spaces, each with a miss at the end. */
26
+ const RUNAWAY = ['a'.repeat(40), 'word '.repeat(30), ' '.repeat(60), '1'.repeat(40), 'gh pr create '.repeat(8)].map((text) => `${text}!`);
27
+
28
+ /** A mistake in how `sumo` was called (exit 2), as opposed to something going wrong (exit 1). */
29
+ export class UsageError extends Error {}
30
+
31
+ /**
32
+ * A gate is a regular expression over a shell command: the commands a workflow has to come before.
33
+ * It is written once, by whoever teaches the workflow, and shown to the user — stated, not guessed.
34
+ */
35
+ export function checkGate(raw) {
36
+ const pattern = String(raw ?? '').trim();
37
+ const example = 'a gate is a regular expression over the shell command, e.g. gh(-axi)? pr create';
38
+ if (!pattern) throw new UsageError(example);
39
+ let regex;
40
+ try {
41
+ regex = new RegExp(pattern, 'i');
42
+ } catch (cause) {
43
+ throw new UsageError(`that gate is not a valid regular expression: ${cause.message}`);
44
+ }
45
+ const caught = NEVER_GATED.find((command) => regex.test(command));
46
+ if (caught !== undefined) throw new UsageError(`that gate is too broad — it would hold back "${caught || 'every command'}"`);
47
+ if (pattern.length < 4) throw new UsageError(`that gate is too short to mean one command — ${example}`);
48
+ if (RUNAWAY.some((text) => matchWithin(regex, text) === null)) {
49
+ throw new UsageError(`that gate takes too long to match — a repeat inside a repeat, such as (a+)+ or (\\w+\\s*)+, makes it run for minutes on some commands. ${example}`);
50
+ }
51
+ return pattern;
52
+ }
53
+
54
+ export function setGate(db, id, raw) {
55
+ const row = get(db, id);
56
+ if (row.type !== 'procedure') throw new UsageError(`m${id} is not a workflow — only a workflow can gate a command`);
57
+ const gate = raw === null ? null : checkGate(raw);
58
+ db.prepare('UPDATE memories SET gate = ? WHERE id = ?').run(gate, id);
59
+ return get(db, id);
60
+ }
61
+
62
+ export function parseId(raw) {
63
+ if (raw === undefined) throw new UsageError('a memory id is needed — ids look like m12');
64
+ const match = /^m?(\d+)$/.exec(String(raw ?? '').trim());
65
+ if (!match) throw new UsageError(`"${raw}" is not a memory id — ids look like m12`);
66
+ return Number(match[1]);
67
+ }
68
+
69
+ export function resolveProject(db, nameOrAlias) {
70
+ const find = (key) => db.prepare('SELECT slug FROM projects WHERE slug = ?').get(key) ?? db.prepare('SELECT slug FROM project_aliases WHERE alias = ?').get(key);
71
+ // A project is also known by the name it was registered from, as typed: "My Proj" is my-proj (the slug projects.mjs makes).
72
+ const row = find(nameOrAlias.toLowerCase()) ?? find(nameOrAlias.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, ''));
73
+ if (!row) {
74
+ const known = db.prepare(`SELECT slug FROM projects WHERE status = 'active' ORDER BY slug LIMIT 9`).all().map((r) => r.slug);
75
+ const listed = known.length === 0 ? '' : ` (known: ${known.slice(0, 8).join(', ')}${known.length > 8 ? ', …' : ''})`;
76
+ throw new UsageError(`unknown project "${nameOrAlias}"${listed} — register it first: sumo project add <path>`);
77
+ }
78
+ return row.slug;
79
+ }
80
+
81
+ function scopeFor(db, project) {
82
+ return project ? `project:${resolveProject(db, project)}` : 'global';
83
+ }
84
+
85
+ export function get(db, id) {
86
+ const row = db.prepare('SELECT * FROM memories WHERE id = ?').get(id);
87
+ if (!row) throw new UsageError(`no memory m${id}`);
88
+ return row;
89
+ }
90
+
91
+ function requireActive(db, id, verb) {
92
+ const row = get(db, id);
93
+ if (row.state !== 'active') throw new UsageError(`m${id} is ${row.state} — only an active memory can be ${verb}`);
94
+ return row;
95
+ }
96
+
97
+ /** A memory's text as it is stored: secrets scrubbed, and — since a memory is one statement — on one line, unless it is a procedure, which may be a document. */
98
+ export function storedBody(type, text) {
99
+ const cleaned = redact(text ?? '');
100
+ return { text: type === 'procedure' ? cleaned.text.trim() : cleaned.text.replace(/\s+/g, ' ').trim(), redacted: cleaned.count };
101
+ }
102
+
103
+ /**
104
+ * A memory's search terms as they are stored, or null: what it is about, in words its body does not use — "lint" for
105
+ * "always run eslint --fix before you commit". A model writes them, so each is checked here and a bad one is dropped,
106
+ * never the memory: not text, longer than a term, secret-looking, a repeat, or only words the body has already.
107
+ */
108
+ export function storedKeys(raw, body) {
109
+ const given = (Array.isArray(raw) ? raw : [raw]).filter((k) => typeof k === 'string').flatMap((k) => k.split(','));
110
+ const known = new Set(words(body).map(stem));
111
+ const kept = [];
112
+ for (const term of given) {
113
+ const key = term.replace(/\s+/g, ' ').trim();
114
+ // Before it is lowercased: a token's mixed case is part of what gives it away.
115
+ if (!key || key.length > KEY_CHARS || redact(key).count > 0 || kept.includes(key.toLowerCase())) continue;
116
+ if (words(key).every((w) => known.has(stem(w)))) continue;
117
+ kept.push(key.toLowerCase());
118
+ if (kept.length === KEYS_KEPT) break;
119
+ }
120
+ return kept.length > 0 ? kept.join(', ') : null;
121
+ }
122
+
123
+ /**
124
+ * Stores one memory. Returns it with any active memories that look like the
125
+ * same statement, so the caller can supersede instead of piling up duplicates.
126
+ */
127
+ export function add(db, input) {
128
+ if (!TYPES.includes(input.type)) {
129
+ throw new UsageError(`unknown type "${input.type}" — one of: ${TYPES.join(', ')}`);
130
+ }
131
+ const provenance = input.provenance ?? 'stated';
132
+ if (!(provenance in PROVENANCE_WEIGHT)) throw new UsageError(`unknown provenance "${provenance}"`);
133
+
134
+ const { text: body, redacted } = storedBody(input.type, input.body);
135
+ if (!body) throw new UsageError('nothing to remember — the text is empty');
136
+ if (input.type === 'procedure' && !input.title?.trim()) throw new UsageError('a procedure needs a title');
137
+ const gate = input.gate === undefined ? null : checkGate(input.gate);
138
+ if (gate !== null && input.type !== 'procedure') throw new UsageError('only a workflow can gate a command');
139
+
140
+ const scope = scopeFor(db, input.project);
141
+ const now = input.now ?? new Date().toISOString();
142
+
143
+ return tx(db, () => {
144
+ const replaced = input.supersedes === undefined ? null : requireActive(db, input.supersedes, 'superseded');
145
+ const similar = replaced ? [] : findSimilar(db, { type: input.type, title: input.title, body, scope });
146
+
147
+ const { lastInsertRowid } = db
148
+ .prepare(
149
+ `INSERT INTO memories (type, scope, title, cue, gate, body, topic, keys, provenance, state, pinned, importance,
150
+ scan_key, written_by, source_session, source_turn, source_quote, valid_from, created_at)
151
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
152
+ )
153
+ .run(
154
+ input.type,
155
+ scope,
156
+ input.title?.trim() || null,
157
+ input.cue?.trim() || null,
158
+ gate,
159
+ body,
160
+ input.topic?.trim().toLowerCase() || null,
161
+ storedKeys(input.keys, body),
162
+ provenance,
163
+ provenance === 'inferred' ? 'unconfirmed' : 'active',
164
+ input.pin ? 1 : 0,
165
+ IMPORTANCE[input.type],
166
+ input.scanKey ?? null,
167
+ input.writtenBy ?? 'chat-model',
168
+ input.sourceSession ?? null,
169
+ input.sourceTurn ?? null,
170
+ input.sourceQuote ?? null,
171
+ now,
172
+ now,
173
+ );
174
+ const id = Number(lastInsertRowid);
175
+ if (replaced) markSuperseded(db, replaced.id, id, now);
176
+
177
+ return { memory: get(db, id), similar, redacted };
178
+ });
179
+ }
180
+
181
+ /**
182
+ * A fact read off disk that was retired by anything but the scanner — forgotten, or replaced — stays retired: the next
183
+ * rescan reads the same text off disk, and must not bring back what was let go. A different text is news, and comes in.
184
+ */
185
+ const retiredKey = (scope, scanKey) => `scan.retired.${scope}.${scanKey}`;
186
+ // Kept as a digest, never the text: a purge erases the words, and the fact still stays let go.
187
+ const digestOf = (body) => createHash('sha256').update(body).digest('hex');
188
+ function noteRetired(db, id) {
189
+ const row = db.prepare('SELECT scope, scan_key, body FROM memories WHERE id = ?').get(id);
190
+ if (row?.scan_key) setMeta(db, retiredKey(row.scope, row.scan_key), digestOf(row.body));
191
+ }
192
+ /** Whether a scanned fact with this text was let go by someone other than the scanner. */
193
+ export const scanRetired = (db, scope, scanKey, body) => getMeta(db, retiredKey(scope, scanKey)) === digestOf(body);
194
+
195
+ function markSuperseded(db, oldId, newId, now) {
196
+ noteRetired(db, oldId);
197
+ db.prepare(`UPDATE memories SET state = 'superseded', superseded_by = ?, invalid_at = ? WHERE id = ?`).run(
198
+ newId,
199
+ now,
200
+ oldId,
201
+ );
202
+ }
203
+
204
+ /** Links two memories that already exist: `oldId` stops being true because of `newId`. */
205
+ export function supersede(db, oldId, newId, now = new Date().toISOString()) {
206
+ if (oldId === newId) throw new UsageError('a memory cannot supersede itself');
207
+ return tx(db, () => {
208
+ requireActive(db, oldId, 'superseded');
209
+ requireActive(db, newId, 'the replacement');
210
+ markSuperseded(db, oldId, newId, now);
211
+ return get(db, oldId);
212
+ });
213
+ }
214
+
215
+ function findSimilar(db, { type, title, body, scope }) {
216
+ const match = ftsQuery(type === 'procedure' ? `${title} ${body}` : body);
217
+ if (!match) return [];
218
+ // Same scope, plus global: a project rule that overrides a global one is
219
+ // legitimate, but whoever adds it should see what it overrides.
220
+ const candidates = db
221
+ .prepare(
222
+ `SELECT m.* FROM memories_fts JOIN memories m ON m.id = memories_fts.rowid
223
+ WHERE memories_fts MATCH ? AND m.state = 'active' AND m.scope IN (?, 'global')
224
+ AND (m.type = 'procedure') = ?
225
+ ORDER BY bm25(memories_fts) LIMIT 8`,
226
+ )
227
+ .all(match, scope, type === 'procedure' ? 1 : 0);
228
+
229
+ const text = (m) => (m.type === 'procedure' ? m.title : m.body);
230
+ const mine = type === 'procedure' ? title : body;
231
+ return candidates.filter((m) => overlap(mine, text(m)) >= SIMILAR_OVERLAP).slice(0, 3);
232
+ }
233
+
234
+ /**
235
+ * Higher is better. Pure, so ranking can be tested without a database or a clock.
236
+ *
237
+ * Relevance is each row's BM25 relative to the best match, square-rooted. Raw
238
+ * BM25 rewards short text so heavily that, among one-sentence memories, a terse
239
+ * scanned fact would outrank the fuller sentence the user actually said. Damped
240
+ * like this it still orders by relevance, but trust and scope can outweigh it.
241
+ */
242
+ export function score(row, { projectScope, now, bestRank }) {
243
+ const relevance = Math.sqrt(row.rank / bestRank); // bm25() is negative, most negative = best, so this is 0..1
244
+ const scopeWeight =
245
+ row.scope === projectScope ? PROJECT_MATCH_BOOST : row.scope === 'global' ? 1 : OTHER_PROJECT_PENALTY;
246
+ const decayDays = DECAY_DAYS[row.type];
247
+ const ageDays = (Date.parse(now) - Date.parse(row.valid_from)) / 86_400_000;
248
+ const decay = decayDays ? Math.exp(-Math.max(0, ageDays) / decayDays) : 1;
249
+ return relevance * scopeWeight * PROVENANCE_WEIGHT[row.provenance] * (0.5 + row.importance) * decay;
250
+ }
251
+
252
+ /** Memories put in front of someone count as used: where room is short, what is used often is shown first. */
253
+ export function markHits(db, ids, now) {
254
+ if (ids.length === 0) return;
255
+ db.prepare(`UPDATE memories SET hits = hits + 1, last_hit_at = ? WHERE id IN (${ids.map(() => '?').join(', ')})`).run(now, ...ids);
256
+ }
257
+
258
+ /**
259
+ * Ranked search. Scope is `global` plus the named project; other projects stay
260
+ * invisible unless `everywhere` is set — only their hit counts come back, so
261
+ * the caller learns where to look without one project's memory leaking into
262
+ * another's work. `record: false` is for a search nobody asked for: it counts
263
+ * no hits and keeps no misses, and the caller decides what was used.
264
+ * `since` and `before` (ISO times) hold it to a time: since, what was said or
265
+ * last changed — replaced, let go — at or after it; before, what was said before it.
266
+ */
267
+ export function search(db, query, opts = {}) {
268
+ const match = ftsQuery(query);
269
+ if (!match) throw new UsageError('nothing to search for');
270
+ if (opts.type && !TYPES.includes(opts.type)) {
271
+ throw new UsageError(`unknown type "${opts.type}" — one of: ${TYPES.join(', ')}`);
272
+ }
273
+
274
+ const projectScope = opts.project ? scopeFor(db, opts.project) : null;
275
+ const now = opts.now ?? new Date().toISOString();
276
+ const limit = opts.limit ?? 8;
277
+
278
+ const where = ['memories_fts MATCH ?'];
279
+ const params = [match];
280
+ if (!opts.all) where.push(`m.state = 'active'`);
281
+ if (opts.type) {
282
+ where.push('m.type = ?');
283
+ params.push(opts.type);
284
+ }
285
+ if (opts.since) {
286
+ where.push('(m.created_at >= ? OR m.invalid_at >= ?)');
287
+ params.push(opts.since, opts.since);
288
+ }
289
+ // A memory is changed only after it is said: one said before then is all that happened before then.
290
+ if (opts.before) {
291
+ where.push('m.created_at < ?');
292
+ params.push(opts.before);
293
+ }
294
+
295
+ const rows = db
296
+ .prepare(
297
+ `SELECT m.*, bm25(memories_fts) AS rank FROM memories_fts JOIN memories m ON m.id = memories_fts.rowid
298
+ WHERE ${where.join(' AND ')}`,
299
+ )
300
+ .all(...params);
301
+
302
+ const inScope = (row) => opts.everywhere || row.scope === 'global' || row.scope === projectScope;
303
+ // OR-ed words match on any one of them. Fine for words a caller picked; a caller searching with
304
+ // words nobody picked — a sentence lifted from a reply — sets a floor on how many must be shared.
305
+ const close = (row) => !opts.minShared || sharedStems(query, `${row.title ?? ''} ${row.cue ?? ''} ${row.body} ${row.keys ?? ''}`) >= opts.minShared;
306
+ const candidates = rows.filter((row) => inScope(row) && close(row));
307
+ // Not Math.min(...ranks): spread into arguments, a broad query's rows overflow the call stack.
308
+ const bestRank = candidates.reduce((best, row) => Math.min(best, row.rank), Infinity);
309
+ const results = candidates
310
+ .map((row) => ({ ...row, score: score(row, { projectScope, now, bestRank }) }))
311
+ .sort((a, b) => b.score - a.score || b.id - a.id)
312
+ .slice(0, limit);
313
+
314
+ const elsewhere = {};
315
+ for (const row of rows) if (!inScope(row)) elsewhere[row.scope] = (elsewhere[row.scope] ?? 0) + 1;
316
+
317
+ if (opts.record === false) return { results, elsewhere };
318
+ if (results.length > 0) {
319
+ markHits(db, results.map((r) => r.id), now);
320
+ } else {
321
+ // The record of what memory could not answer: the evidence for whether
322
+ // keyword search is enough or embeddings are ever worth adding.
323
+ // Kept like everything else here: without secrets, and short — a pasted log is not a question worth keeping whole.
324
+ db.prepare('INSERT INTO search_misses (ts, query, scope) VALUES (?, ?, ?)').run(
325
+ now,
326
+ clip(redact(query).text, MISS_KEPT),
327
+ opts.everywhere ? 'everywhere' : (projectScope ?? 'global'),
328
+ );
329
+ }
330
+
331
+ return { results, elsewhere };
332
+ }
333
+
334
+ /** Every memory connected to `id` by supersession, oldest first. */
335
+ export function history(db, id) {
336
+ get(db, id);
337
+ const seen = new Map();
338
+ const queue = [id];
339
+ while (queue.length > 0) {
340
+ const current = queue.pop();
341
+ if (seen.has(current)) continue;
342
+ const row = db.prepare('SELECT * FROM memories WHERE id = ?').get(current);
343
+ if (!row) continue;
344
+ seen.set(current, row);
345
+ if (row.superseded_by !== null) queue.push(row.superseded_by);
346
+ for (const prev of db.prepare('SELECT id FROM memories WHERE superseded_by = ?').all(current)) queue.push(prev.id);
347
+ }
348
+ return [...seen.values()].sort((a, b) => a.valid_from.localeCompare(b.valid_from) || a.id - b.id);
349
+ }
350
+
351
+ /**
352
+ * The search indexes keep a deleted entry's words until they next merge, unless told to drop them at once. The
353
+ * setting stays on once made. FTS5 has it from SQLite 3.42, which every Node this runs on bundles; a build linked
354
+ * against an older system SQLite still purges, leaving those words to the next merge.
355
+ */
356
+ function eraseFromIndexes(db) {
357
+ const [major, minor] = db.prepare('SELECT sqlite_version() AS v').get().v.split('.').map(Number);
358
+ if (major === 3 && minor < 42) return;
359
+ db.exec(`
360
+ INSERT INTO memories_fts(memories_fts, rank) VALUES ('secure-delete', 1);
361
+ INSERT INTO user_turns_fts(user_turns_fts, rank) VALUES ('secure-delete', 1);
362
+ `);
363
+ }
364
+
365
+ /** Stops a memory being true. With `purge` it is erased outright, for things that should never have been stored. */
366
+ export function forget(db, id, { purge = false, now = new Date().toISOString() } = {}) {
367
+ const row = get(db, id);
368
+ if (purge) {
369
+ tx(db, () => {
370
+ eraseFromIndexes(db);
371
+ // A scanned fact let go for good stays let go: only its digest is kept, never its words.
372
+ noteRetired(db, id);
373
+ db.prepare('DELETE FROM memories WHERE id = ?').run(id);
374
+ // Erasing the memory but keeping the sentence it came from would not be erasing it.
375
+ if (row.source_turn !== null) db.prepare('DELETE FROM user_turns WHERE id = ?').run(row.source_turn);
376
+ });
377
+ // The write-ahead log still holds the pages as they were before the delete; copy it into the file and empty it.
378
+ db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
379
+ return { ...row, state: 'purged' };
380
+ }
381
+ if (row.state === 'invalid') return row;
382
+ noteRetired(db, id);
383
+ db.prepare(`UPDATE memories SET state = 'invalid', invalid_at = ? WHERE id = ?`).run(now, id);
384
+ return get(db, id);
385
+ }
386
+
387
+ /** The user said yes to a guess: from here on it carries the weight of something they stated. */
388
+ export function confirm(db, id) {
389
+ const row = get(db, id);
390
+ if (row.state !== 'unconfirmed') throw new UsageError(`m${id} is ${row.state} — only an unconfirmed memory can be confirmed`);
391
+ db.prepare(`UPDATE memories SET state = 'active', provenance = 'stated' WHERE id = ?`).run(id);
392
+ return get(db, id);
393
+ }
394
+
395
+ export function reject(db, id, now = new Date().toISOString()) {
396
+ const row = get(db, id);
397
+ if (row.state !== 'unconfirmed') throw new UsageError(`m${id} is ${row.state} — only an unconfirmed memory can be rejected`);
398
+ db.prepare(`UPDATE memories SET state = 'rejected', invalid_at = ? WHERE id = ?`).run(now, id);
399
+ return get(db, id);
400
+ }
package/src/model.mjs ADDED
@@ -0,0 +1,270 @@
1
+ import { jsonSchemaOutputFormat } from '@anthropic-ai/sdk/helpers/json-schema';
2
+ import { spawnSync } from 'node:child_process';
3
+ import { accessSync, appendFileSync, constants, existsSync, mkdirSync } from 'node:fs';
4
+ import { join } from 'node:path';
5
+ import { anthropicClient, authenticatedRequest, resolveAnthropicCredential } from './auth.mjs';
6
+ import { describeApiError, modelId } from './catalog.mjs';
7
+ import { getMeta } from './db.mjs';
8
+ import { ensureLocalServer, LOCAL_REASONING_BUDGET, modelIdOf } from './local-server.mjs';
9
+ import { paths } from './paths.mjs';
10
+ import { CONFIG_DEFAULTS } from './setup.mjs';
11
+ import { SEARCH_USD } from './web.mjs';
12
+
13
+ const TIMEOUT_MS = 180_000;
14
+ // The SDK tries twice more by default, a timeout included: three minutes would be nine, and a call the API did
15
+ // answer could be sent and billed again. One more try rides out a moment of overload; the scribe's fallback does the rest.
16
+ const MAX_RETRIES = 1;
17
+ // Room for a schema'd answer with a sentence of reasoning; a small model cut off mid-string is unparseable JSON.
18
+ const MAX_ANSWER_TOKENS = 400;
19
+ // A memory pass on the local model thinks first, up to the server's reasoning budget, then lists its operations.
20
+ const MAX_LOCAL_PASS_TOKENS = LOCAL_REASONING_BUDGET + 3072;
21
+ // A scribe pass answers with a list of operations. Every model but haiku thinks first, and the thinking counts toward this
22
+ // limit too: 8k holds both, ends well inside the call's three minutes, and is far below the 21,333 the SDK sends without
23
+ // streaming. An answer longer than this is the model rambling, not remembering.
24
+ const MAX_API_ANSWER_TOKENS = 8192;
25
+ /** What the SDK's beta parse() sent with a schema'd request, kept for the OAuth path that goes through the beta API. */
26
+ const STRUCTURED_OUTPUTS_BETA = 'structured-outputs-2025-12-15';
27
+
28
+ /** US dollars per million tokens: input, output, and what a cache read costs relative to input. */
29
+ export const PRICES = {
30
+ 'claude-haiku-4-5-20251001': { input: 1, output: 5, cacheRead: 0.1 },
31
+ 'claude-sonnet-5-5': { input: 2, output: 10, cacheRead: 0.1 },
32
+ 'claude-opus-5-5': { input: 4, output: 20, cacheRead: 0.05 },
33
+ 'claude-fable-5-1': { input: 10, output: 50, cacheRead: 0.025 },
34
+ };
35
+ /** What writing to the cache costs relative to input: the five-minute cache every request here writes. */
36
+ export const CACHE_WRITE = 1.25;
37
+
38
+ /** What one response cost, from its usage and the price list; 0 for a model the list does not know. */
39
+ export function costOf(model, usage) {
40
+ const price = PRICES[modelId(model)];
41
+ if (!price) return 0;
42
+ const plain = usage.input_tokens ?? 0;
43
+ const read = usage.cache_read_input_tokens ?? 0;
44
+ const written = usage.cache_creation_input_tokens ?? 0;
45
+ const out = usage.output_tokens ?? 0;
46
+ // A web search is paid for by the search, on top of the tokens of what it found.
47
+ const searches = (usage.server_tool_use?.web_search_requests ?? 0) * SEARCH_USD;
48
+ return (plain * price.input + read * price.input * price.cacheRead + written * price.input * CACHE_WRITE + out * price.output) / 1_000_000 + searches;
49
+ }
50
+
51
+ /** The request one cheap-model call sends: a frozen system prompt, the bundle as the one user turn, the answer shape enforced by the API. */
52
+ export function requestFor({ system, prompt, schema, model }) {
53
+ return {
54
+ model: modelId(model),
55
+ max_tokens: MAX_API_ANSWER_TOKENS,
56
+ system,
57
+ messages: [{ role: 'user', content: prompt }],
58
+ // Sent as written. The helper's own rewrite moves every enum into a description, and the API then holds the answer to none of them.
59
+ output_config: { format: jsonSchemaOutputFormat(schema, { transform: false }) },
60
+ };
61
+ }
62
+
63
+ /** The usage of an API response in the shape every caller gets back: inputTokens is the total, the cache split rides beside it. */
64
+ export function usageOf(model, usage) {
65
+ const cacheReadTokens = usage?.cache_read_input_tokens ?? null;
66
+ const cacheCreationTokens = usage?.cache_creation_input_tokens ?? null;
67
+ return {
68
+ inputTokens: (usage?.input_tokens ?? 0) + (cacheReadTokens ?? 0) + (cacheCreationTokens ?? 0),
69
+ outputTokens: usage?.output_tokens ?? 0,
70
+ costUsd: costOf(model, usage ?? {}),
71
+ cacheReadTokens,
72
+ cacheCreationTokens,
73
+ };
74
+ }
75
+
76
+ /** The stand-in's JSON envelope (the shape Claude Code printed, kept so recorded answers still replay), turned into a result. */
77
+ function envelopeToResult(run, command) {
78
+ if (run.error) return failure(`could not run ${command}: ${run.error.message}`);
79
+ let envelope;
80
+ try {
81
+ envelope = JSON.parse(run.stdout);
82
+ } catch {
83
+ return failure(`unreadable answer (exit ${run.status}): ${(run.stderr || run.stdout).slice(0, 300)}`);
84
+ }
85
+
86
+ const usage = { ...usageOf(null, envelope.usage), costUsd: envelope.total_cost_usd ?? 0 };
87
+ if (envelope.is_error) return { ...failure(`model call failed: ${String(envelope.result ?? envelope.subtype).slice(0, 300)}`), usage };
88
+
89
+ let data = envelope.structured_output;
90
+ if (data === undefined || data === null) {
91
+ try {
92
+ data = JSON.parse(String(envelope.result).replace(/^```(?:json)?\s*|\s*```$/g, ''));
93
+ } catch {
94
+ return { ...failure('the answer was not the JSON that was asked for'), usage };
95
+ }
96
+ }
97
+ return { ok: true, data, usage, error: null };
98
+ }
99
+
100
+ /**
101
+ * One call to the cheap model, outside any conversation.
102
+ *
103
+ * It goes straight to the Messages API with an API key or Claude Code OAuth token: a
104
+ * system prompt, one user turn, and a JSON schema the API itself enforces on
105
+ * the answer. No tools, no thinking, nothing loaded from disk — so it costs the
106
+ * prompt and the answer, and nothing else.
107
+ *
108
+ * SUMO_AGENTS_MODEL_CMD swaps the call for a stand-in that reads the same
109
+ * request and prints a recorded envelope; the tests use it to replay answers
110
+ * without spending anything.
111
+ */
112
+ export async function callModel(db, { system, prompt, schema, model, kind }) {
113
+ // The passes' default: the same local model that routes jobs, with thinking on; its caller keeps the ledger.
114
+ if (model === 'local') return callLocalModel(db, { system, prompt, schema, kind, think: true, maxTokens: MAX_LOCAL_PASS_TOKENS, log: false });
115
+
116
+ const standIn = process.env.SUMO_AGENTS_MODEL_CMD;
117
+ if (standIn) {
118
+ const run = spawnSync(standIn, [], {
119
+ input: JSON.stringify({ system, prompt, schema, model }),
120
+ encoding: 'utf8',
121
+ timeout: TIMEOUT_MS,
122
+ maxBuffer: 16 * 1024 * 1024,
123
+ });
124
+ return envelopeToResult(run, standIn);
125
+ }
126
+
127
+ try {
128
+ const credential = resolveAnthropicCredential();
129
+ if (!credential) return failure('no Anthropic credential — export ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN in the shell that runs sumo');
130
+ const client = anthropicClient({ timeout: TIMEOUT_MS, maxRetries: MAX_RETRIES }, credential);
131
+ const request = authenticatedRequest(requestFor({ system, prompt, schema, model }), credential);
132
+ // Not the SDK's parse(): it throws on an answer that is not JSON before the stop reason or the usage can be read,
133
+ // so a cut-off or refused answer would be misnamed and what it spent never logged. The answer is parsed below instead.
134
+ const response = credential?.type === 'oauth'
135
+ ? await client.beta.messages.create({ ...request, betas: [...request.betas, STRUCTURED_OUTPUTS_BETA] })
136
+ : await client.messages.create(request);
137
+ const usage = usageOf(model, response.usage);
138
+ if (response.stop_reason === 'refusal') return { ...failure(`the model declined to answer (${response.stop_details?.category ?? 'no category'})`), usage };
139
+ if (response.stop_reason === 'max_tokens') return { ...failure(`the answer was cut off at ${MAX_API_ANSWER_TOKENS} tokens`), usage };
140
+ let data = null;
141
+ try {
142
+ data = JSON.parse(response.content.find((b) => b.type === 'text')?.text ?? '');
143
+ } catch {
144
+ // Said below.
145
+ }
146
+ if (data === null) return { ...failure('the answer was not the JSON that was asked for'), usage };
147
+ return { ok: true, data, usage, error: null };
148
+ } catch (cause) {
149
+ return failure(describeApiError(cause));
150
+ }
151
+ }
152
+ /** llama-server's error body, as one line a person can act on. */
153
+ function describeLocal(status, body) {
154
+ const error = body?.error ?? {};
155
+ if (error.type === 'exceed_context_size_error') {
156
+ return `the bundle (${error.n_prompt_tokens} tokens) is larger than the local model's context (${error.n_ctx} tokens)`;
157
+ }
158
+ return `llama-server returned HTTP ${status}: ${String(error.message ?? JSON.stringify(body)).slice(0, 200)}`;
159
+ }
160
+
161
+ /**
162
+ * One call to the local model, through the llama-server that stays up for it (see local-server.mjs).
163
+ * Same envelope as callModel ({ ok, data, usage, error }), so a caller cannot tell which backend
164
+ * answered. The router asks with the defaults: no thinking, a short answer, a ledger row of kind
165
+ * `local`. A memory pass asks with `think`, a longer answer cap and `log: false`, keeping its own
166
+ * ledger; `kind` tells a stand-in which of them is asking. The stand-in path uses spawnSync, exactly
167
+ * like callModel, so tests never wait on a promise that depends on a real server.
168
+ */
169
+ export async function callLocalModel(db, { system, prompt, schema, kind = 'local', think = false, maxTokens = MAX_ANSWER_TOKENS, log = true, timeoutMs = TIMEOUT_MS }) {
170
+ const now = new Date().toISOString();
171
+ const modelFile = getMeta(db, 'config.model.file') ?? CONFIG_DEFAULTS['model.file'];
172
+ const modelLabel = `local:${modelFile}`;
173
+ const record = (result) => {
174
+ if (log) logRun(db, { kind: 'local', model: modelLabel, result, note: result.ok ? 'ok' : result.error, now });
175
+ return result;
176
+ };
177
+
178
+ const standIn = process.env.SUMO_AGENTS_MODEL_CMD;
179
+ if (standIn) {
180
+ const run = spawnSync(standIn, [], {
181
+ input: JSON.stringify({ system, prompt, schema, model: 'local', kind, think, maxTokens }),
182
+ encoding: 'utf8',
183
+ timeout: timeoutMs,
184
+ maxBuffer: 16 * 1024 * 1024,
185
+ });
186
+ return record(envelopeToResult(run, standIn));
187
+ }
188
+
189
+ const modelPath = join(paths().models, modelFile);
190
+ if (!existsSync(modelPath)) return record(failure(`model file not found at ${modelPath} — run: sumo setup`));
191
+ const llama = getMeta(db, 'llama.path');
192
+ if (!llama) return record(failure('llama-server is not pinned — run: sumo setup'));
193
+ try {
194
+ accessSync(llama, constants.X_OK);
195
+ } catch {
196
+ return record(failure(`llama-server is no longer at ${llama} — run: sumo setup`));
197
+ }
198
+
199
+ try {
200
+ const server = await ensureLocalServer(db, { llama, file: modelFile });
201
+ const res = await fetch(`http://127.0.0.1:${server.port}/v1/chat/completions`, {
202
+ method: 'POST',
203
+ headers: { 'content-type': 'application/json' },
204
+ signal: AbortSignal.timeout(timeoutMs),
205
+ body: JSON.stringify({
206
+ model: modelIdOf(modelFile),
207
+ messages: [
208
+ { role: 'system', content: system },
209
+ { role: 'user', content: prompt },
210
+ ],
211
+ response_format: { type: 'json_schema', json_schema: { name: 'answer', schema, strict: true } },
212
+ chat_template_kwargs: { enable_thinking: think },
213
+ temperature: 0,
214
+ max_tokens: maxTokens,
215
+ }),
216
+ });
217
+ const text = await res.text();
218
+ let body = null;
219
+ try {
220
+ body = JSON.parse(text);
221
+ } catch {
222
+ // Said below, with the status.
223
+ }
224
+ if (!res.ok) throw new Error(describeLocal(res.status, body ?? { error: { message: text } }));
225
+ const choice = body.choices[0];
226
+ const usage = {
227
+ inputTokens: body.usage?.prompt_tokens ?? 0,
228
+ outputTokens: body.usage?.completion_tokens ?? 0,
229
+ costUsd: 0,
230
+ cacheReadTokens: null,
231
+ cacheCreationTokens: null,
232
+ };
233
+ if (choice.finish_reason === 'length') return record({ ...failure(`the answer was cut off at ${maxTokens} tokens`), usage });
234
+ let data = null;
235
+ try {
236
+ data = JSON.parse(choice.message.content);
237
+ } catch {
238
+ // Said below.
239
+ }
240
+ if (data === null) return record({ ...failure('the answer was not the JSON that was asked for'), usage });
241
+ return record({ ok: true, data, usage, error: null });
242
+ } catch (cause) {
243
+ return record(failure(cause.message));
244
+ }
245
+ }
246
+
247
+ /** A call that did not happen or did not answer, in the envelope every caller reads: nothing spent, the reason in `error`. */
248
+ export function failure(error) {
249
+ return { ok: false, data: null, usage: { inputTokens: 0, outputTokens: 0, costUsd: 0, cacheReadTokens: null, cacheCreationTokens: null }, error };
250
+ }
251
+
252
+ /**
253
+ * The one `model_runs` row every cheap-model call leaves behind, whichever backend answered it.
254
+ * The cache split comes from result.usage and the job and session from the options; any of them
255
+ * missing is written as NULL.
256
+ */
257
+ export function logRun(db, { kind, model, result, note, now, jobId = null, sessionId = null }) {
258
+ db.prepare(
259
+ `INSERT INTO model_runs (ts, kind, model, input_tokens, output_tokens, cost_usd, ok, note, cache_read_tokens, cache_creation_tokens, job_id, session_id)
260
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
261
+ ).run(
262
+ now, kind, model, result.usage.inputTokens, result.usage.outputTokens, result.usage.costUsd, result.ok ? 1 : 0, note,
263
+ result.usage.cacheReadTokens ?? null, result.usage.cacheCreationTokens ?? null, jobId, sessionId,
264
+ );
265
+ mkdirSync(paths().logs, { recursive: true, mode: 0o700 });
266
+ appendFileSync(
267
+ join(paths().logs, 'scribe.log'),
268
+ `${now} ${kind} ${model} ${result.ok ? 'ok' : 'FAILED'} in=${result.usage.inputTokens} out=${result.usage.outputTokens} $${result.usage.costUsd.toFixed(4)} ${note}\n`,
269
+ );
270
+ }