sumo-agents 0.1.0 → 0.4.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/src/cli.mjs CHANGED
@@ -9,6 +9,7 @@ import { dreamStatus, runDream } from './dream.mjs';
9
9
  import { backup, exportJson, exportMarkdown, purgeFromBackups } from './export.mjs';
10
10
  import { resolveAnthropicCredential } from './auth.mjs';
11
11
  import { chat, jobPrinter } from './chat.mjs';
12
+ import { costLines } from './cost.mjs';
12
13
  import { closeJobTab, reportAgent, runHerdr } from './herdr.mjs';
13
14
  import { runHook } from './hooks.mjs';
14
15
  import { runJob as runJobLoop, runLines } from './loop.mjs';
@@ -22,6 +23,7 @@ import * as projects from './projects.mjs';
22
23
  import { detail, historyLine, line, scopeLabel } from './render.mjs';
23
24
  import { buildBundle, modelStats, outcomeLines, runScribe, scribeStatus } from './scribe.mjs';
24
25
  import { findSaved, searchTurns, taskEndedNudge } from './sessions.mjs';
26
+ import { overlap } from './text.mjs';
25
27
  import { CHAT_EFFORTS, config, doctor, positiveInteger, setup } from './setup.mjs';
26
28
  import { colourEnabled, safeForTerminal, styles } from './tty.mjs';
27
29
  import { ftsQuery } from './text.mjs';
@@ -30,7 +32,7 @@ import { verdictLines } from './verify.mjs';
30
32
  const HELP = `sumo — local memory for the sumo-agents process
31
33
 
32
34
  sumo chat [--model M] [--effort E] [--resume [id]] talk: the chat, with this memory behind it
33
- sumo search <query> [--project S] [--type T] [--everywhere] [--all] [--turns] [-n N]
35
+ sumo search <query> [--project S] [--type T] [--everywhere] [--all] [--turns] [--since <YYYY-MM-DD|Nd>] [--before <YYYY-MM-DD>] [-n N]
34
36
  sumo add <type> "<text>" [--project S] [--topic T] [--pin] [--supersedes ID] [--observed]
35
37
  types: preference · fact · decision · gotcha
36
38
  sumo learn "<title>" --cue "<action>" [--gate '<regex>'] [--project S] workflow steps on stdin
@@ -45,7 +47,7 @@ const HELP = `sumo — local memory for the sumo-agents process
45
47
  finish ID --status DONE|FAILED · show ID · list [--all] · abandon ID · retry ID · stats
46
48
  sumo prime the block a session starts with
47
49
  sumo scribe run|show|status|stats sumo dream run|status the cheap-model passes
48
- sumo export [--json] sumo backup
50
+ sumo export [--json] sumo backup sumo cost [--days N] [--project S] where the money went
49
51
  sumo models [discover | enable <name> | disable <name>] the API models: which are here, which are on
50
52
  sumo mcp [add <name> -- <command> [args…] | add <name> --url U | remove N | tools N | allow N <tool>|all | revoke N <tool>|all]
51
53
  MCP servers: their tools reach the chat and every job; a tool not allowed asks first
@@ -69,7 +71,7 @@ EOF
69
71
  */
70
72
  const USAGE = {
71
73
  chat: 'sumo chat [--model auto|<model>] [--effort <effort>] [--resume [id]] (piped: plain lines, the memory block first; --resume picks a saved session up, the newest without an id)',
72
- search: 'sumo search <query> [--project S] [--type T] [--everywhere] [--all] [--turns] [-n N]',
74
+ search: 'sumo search <query> [--project S] [--type T] [--everywhere] [--all] [--turns] [--since <YYYY-MM-DD|Nd>] [--before <YYYY-MM-DD>] [-n N] (--since: said or changed since that day, or in the last N days; --before: said before that day)',
73
75
  add: `sumo add preference|fact|decision|gotcha "<one sentence>" [--project S] [--topic T] [--pin] [--supersedes ID] [--observed]
74
76
  a workflow (steps to repeat) is saved with sumo learn instead:
75
77
  ${LEARN_USAGE}`,
@@ -88,8 +90,10 @@ sumo project show <name> | list [--all] | rescan <name> | alias <name> <alias> |
88
90
  [--guide fix|feature|review|none] carry guides/<name>.md into the brief (unsaid: what the title and goal ask for)
89
91
  [--reviews <id>] reviewer: judge that job's change (default: what is uncommitted)
90
92
  [--tests-may-change] worker: this task is allowed to edit tests that already exist
93
+ [--attempts 2|3] worker: that many attempts, each in a worktree of its own; the best verified one is kept
91
94
  sumo job brief|show|abandon <id>
92
95
  sumo job run <id> runs the job here, in Sumo's own loop, on its route; it closes itself as its brief says
96
+ then, unasked: a first attempt that failed is retried one step up (jobs.escalate), risky work done is reviewed (jobs.review)
93
97
  sumo job watch <id> what a job running in the chat is doing, as it does it (a Herdr tab shows this)
94
98
  sumo job note|ask|answer|tell <id> (text on stdin; tell: a message a running job reads next)
95
99
  sumo job baseline <id> the project's checks, before the work
@@ -101,6 +105,7 @@ sumo job stats [--project S] jobs, done, failed, reviewed, avg important, and w
101
105
  sumo job list [--all]`,
102
106
  prime: 'sumo prime [--budget N]',
103
107
  scribe: 'sumo scribe run|show|status|stats',
108
+ cost: 'sumo cost [--days N] [--project S] what the requests cost, by kind and model: fresh input, cache reads, cache writes and output; then the cache rewrites — context written again while the cache should still have held it',
104
109
  dream: 'sumo dream run|status',
105
110
  apply: 'sumo apply <ops.json> [--source scribe|dream]',
106
111
  export: 'sumo export [--json]',
@@ -121,12 +126,33 @@ sumo mcp allow <name> <tool>|all let it run without asking sumo mcp re
121
126
  };
122
127
 
123
128
  const ADDABLE = ['preference', 'fact', 'decision', 'gotcha'];
129
+
130
+ /**
131
+ * Who runs this command: the model's shell carries SUMO_TOOL, a job's SUMO_JOB too. Under either, what only the user does is
132
+ * refused — the allow list, the switches and the configuration — and a job writes no memory at all. The chat may still remember
133
+ * for the user, held to what the user typed: a statement none of their recent words say is kept unconfirmed, for them to say yes to.
134
+ */
135
+ const fromTool = () => Boolean(process.env.SUMO_TOOL || process.env.SUMO_JOB);
136
+ const fromJob = () => process.env.SUMO_JOB || null;
137
+ const OWNER_ONLY = "Refused: the model's shell does not change what the user controls — the MCP allow list, the models and the configuration. If the user wants it, they run it themselves: `! sumo …`";
138
+ const jobWrites = () => `Refused: j${fromJob()} runs this command, and a job never writes memory. Put what you learned in your report; the user, or the chat, decides what is kept.`;
139
+ /** The scribe's bar for "the user said this": the memory shares this much of its words with a turn the user typed. */
140
+ const SAID_BY_USER = 0.34;
141
+ const RECENT_TURNS = 40;
142
+ /** Whether something the user typed lately says what the memory says, so a memory the model files as the user's is really theirs. */
143
+ function saidByUser(db, text) {
144
+ return db
145
+ .prepare('SELECT text FROM user_turns ORDER BY id DESC LIMIT ?')
146
+ .all(RECENT_TURNS)
147
+ .some((turn) => overlap(text, turn.text) >= SAID_BY_USER);
148
+ }
149
+ const HELD = (id) => `held as unconfirmed: nothing the user typed lately says this, so it is theirs to confirm — sumo confirm m${id}, or sumo reject m${id}`;
124
150
  /** The docs say "workflow", the store says "procedure"; whoever types either means the same thing. */
125
151
  const WORKFLOW_NAMES = ['workflow', 'procedure'];
126
152
 
127
153
  /** value: flags that take an argument; bool: flags that don't. Anything else is a typo and says so. */
128
154
  const COMMANDS = {
129
- search: { value: ['project', 'type', 'n'], bool: ['everywhere', 'all', 'turns'], run: runSearch },
155
+ search: { value: ['project', 'type', 'n', 'since', 'before'], bool: ['everywhere', 'all', 'turns'], run: runSearch },
130
156
  add: { value: ['project', 'topic', 'supersedes'], bool: ['pin', 'observed'], run: runAdd },
131
157
  learn: { value: ['project', 'cue', 'gate', 'from-file'], bool: [], run: runLearn },
132
158
  gate: { value: [], bool: [], run: runGate },
@@ -138,9 +164,10 @@ const COMMANDS = {
138
164
  reject: { value: [], bool: [], run: (db, { args }) => [`rejected ${line(memory.reject(db, memory.parseId(args[0])))}`] },
139
165
  memory: { value: [], bool: [], run: runMemoryPage },
140
166
  project: { value: ['slug'], multi: ['alias'], bool: ['all'], run: runProject },
141
- job: { value: ['project', 'title', 'agent', 'status', 'from-file', 'guide', 'reviews', 'accept'], bool: ['all', 'tests-may-change'], run: runJob },
167
+ job: { value: ['project', 'title', 'agent', 'status', 'from-file', 'guide', 'reviews', 'accept', 'attempts'], bool: ['all', 'tests-may-change'], run: runJob },
142
168
  prime: { value: ['budget'], bool: [], run: (db, { flags }) => [prime(db, { budget: flags.budget === undefined ? undefined : positiveInteger(flags.budget, '--budget needs a positive number') })] },
143
169
  scribe: { value: [], bool: [], run: runScribeCommand },
170
+ cost: { value: ['days', 'project'], bool: [], run: (db, { flags }) => costLines(db, { days: flags.days === undefined ? undefined : positiveInteger(flags.days, '--days needs a positive number'), project: flags.project }) },
144
171
  dream: { value: [], bool: [], run: runDreamCommand },
145
172
  apply: { value: ['source'], bool: [], run: runApply },
146
173
  export: { value: [], bool: ['json', 'md'], run: runExport },
@@ -149,6 +176,14 @@ const COMMANDS = {
149
176
  mcp: { value: ['url'], multi: ['env', 'header'], bool: [], run: runMcp },
150
177
  };
151
178
 
179
+ /** Memory a job's shell never writes: it reports, and the user or the chat decides. */
180
+ const JOB_NEVER = ['add', 'learn', 'gate', 'supersede', 'forget', 'confirm', 'reject', 'apply'];
181
+ /** What the model's shell never changes, by command and the subcommands that change something. */
182
+ const OWNER_COMMANDS = new Map([
183
+ ['mcp', (args) => ['add', 'remove', 'allow', 'revoke'].includes(args[0])],
184
+ ['models', (args) => ['enable', 'disable', 'discover'].includes(args[0])],
185
+ ]);
186
+
152
187
  function parse(argv, spec) {
153
188
  const args = [];
154
189
  const flags = {};
@@ -184,11 +219,31 @@ function need(args, count, command) {
184
219
  if (args.length < count) throw new UsageError(`usage: ${USAGE[command]}`);
185
220
  }
186
221
 
222
+ const DAY_MS = 86_400_000;
223
+
224
+ /**
225
+ * A day as typed after --since or --before: 2026-10-01 is the start of that day in UTC, the day every date memory shows
226
+ * is in. Where `back` allows it, 7d is that many days back from now.
227
+ */
228
+ function dayFlag(raw, flag, { back = false } = {}) {
229
+ if (raw === undefined) return undefined;
230
+ const days = back ? /^(\d+)d$/.exec(raw) : null;
231
+ const time = days && Number(days[1]) > 0 ? new Date(Date.now() - Number(days[1]) * DAY_MS) : null;
232
+ if (time && !Number.isNaN(time.getTime())) return time.toISOString();
233
+ // A day that does not exist, 2026-02-30, would roll over into the next month: it is a typo, and said as one.
234
+ const day = /^\d{4}-\d{2}-\d{2}$/.test(raw) ? new Date(`${raw}T00:00:00.000Z`) : null;
235
+ if (day && !Number.isNaN(day.getTime()) && day.toISOString().startsWith(raw)) return day.toISOString();
236
+ throw new UsageError(`${flag} takes a day (YYYY-MM-DD)${back ? ' or a number of days back (7d)' : ''}, not "${raw}"`);
237
+ }
238
+
187
239
  function runSearch(db, { args, flags }) {
188
240
  need(args, 1, 'search');
189
241
  const limit = flags.n === undefined ? undefined : positiveInteger(flags.n, '-n needs a positive number');
242
+ const since = dayFlag(flags.since, '--since', { back: true });
243
+ const before = dayFlag(flags.before, '--before');
190
244
 
191
245
  if (flags.turns) {
246
+ if (since || before) throw new UsageError('--since and --before hold memories to a time, not what the user typed — leave out --turns, or the dates');
192
247
  const match = ftsQuery(args.join(' '));
193
248
  if (!match) throw new UsageError('nothing to search for');
194
249
  const turns = searchTurns(db, match, limit);
@@ -200,6 +255,8 @@ function runSearch(db, { args, flags }) {
200
255
  type: WORKFLOW_NAMES.includes(flags.type) ? 'procedure' : flags.type,
201
256
  everywhere: flags.everywhere,
202
257
  all: flags.all,
258
+ since,
259
+ before,
203
260
  limit,
204
261
  });
205
262
 
@@ -226,29 +283,34 @@ function savedLines({ memory: saved, similar, redacted }) {
226
283
 
227
284
  function runAdd(db, { args, flags }) {
228
285
  need(args, 2, 'add');
286
+ if (fromJob()) throw new UsageError(jobWrites());
229
287
  const [type, ...text] = args;
230
288
  if (WORKFLOW_NAMES.includes(type)) throw new UsageError(`a workflow has a title and steps, so it is saved with sumo learn, not sumo add:\n${LEARN_USAGE}`);
231
289
  if (!ADDABLE.includes(type)) throw new UsageError(`unknown type "${type}" — one of: ${ADDABLE.join(', ')} (for a workflow: sumo learn)`);
232
- return savedLines(
233
- memory.add(db, {
234
- type,
235
- body: text.join(' '),
236
- project: flags.project,
237
- topic: flags.topic,
238
- pin: flags.pin,
239
- supersedes: flags.supersedes === undefined ? undefined : memory.parseId(flags.supersedes),
240
- provenance: flags.observed ? 'observed' : 'stated',
241
- }),
242
- );
290
+ const body = text.join(' ');
291
+ // From the model's shell, the user's word is checked against the user's words: an inferred memory waits unconfirmed.
292
+ const held = fromTool() && !saidByUser(db, body);
293
+ const saved = memory.add(db, {
294
+ type,
295
+ body,
296
+ project: flags.project,
297
+ topic: flags.topic,
298
+ pin: flags.pin,
299
+ supersedes: flags.supersedes === undefined ? undefined : memory.parseId(flags.supersedes),
300
+ provenance: held ? 'inferred' : flags.observed ? 'observed' : 'stated',
301
+ });
302
+ return savedLines(saved).concat(held ? [HELD(saved.memory.id)] : []);
243
303
  }
244
304
 
245
305
  function runLearn(db, { args, flags }) {
246
306
  need(args, 1, 'learn');
307
+ if (fromJob()) throw new UsageError(jobWrites());
247
308
  const body = flags['from-file'] ? readFileSync(flags['from-file'], 'utf8') : process.stdin.isTTY ? '' : readFileSync(0, 'utf8');
248
309
  if (!body.trim()) throw new UsageError('no steps given — pipe them in, or use --from-file <path>');
249
- return savedLines(
250
- memory.add(db, { type: 'procedure', title: args.join(' '), cue: flags.cue, gate: flags.gate, body, project: flags.project }),
251
- ).concat(flags.gate ? [`gates shell commands matching: ${flags.gate}`] : []);
310
+ const title = args.join(' ');
311
+ const held = fromTool() && !saidByUser(db, [title, flags.cue ?? '', body].join(' '));
312
+ const saved = memory.add(db, { type: 'procedure', title, cue: flags.cue, gate: flags.gate, body, project: flags.project, provenance: held ? 'inferred' : 'stated' });
313
+ return savedLines(saved).concat(flags.gate ? [`gates shell commands matching: ${flags.gate}`] : [], held ? [HELD(saved.memory.id)] : []);
252
314
  }
253
315
 
254
316
  function runGate(db, { args }) {
@@ -319,8 +381,16 @@ function stdinText(flags) {
319
381
  return process.stdin.isTTY ? '' : readFileSync(0, 'utf8');
320
382
  }
321
383
 
322
- /** The lines `new` and `retry` both print: the job, its route, and exactly what to start it with. */
323
- function createdLines(job, warnings) {
384
+ /** The lines `new` and `retry` both print: the job, its route, and exactly what to start it with. Several attempts are one line each. */
385
+ function createdLines(job, warnings, attempts = null) {
386
+ if (attempts) {
387
+ return [
388
+ ...attempts.map((a) => `created ${jobs.jobLine(a)}`),
389
+ ...warnings,
390
+ `route: ${job.model}/${job.effort} — ${job.route_reason}`,
391
+ `run each: ${attempts.map((a) => `sumo job run ${a.id}`).join(' · ')} — once all have closed, the best verified one is brought back`,
392
+ ];
393
+ }
324
394
  return [
325
395
  `created ${jobs.jobLine(job)}`,
326
396
  ...warnings,
@@ -401,11 +471,14 @@ function copyFrom(file, at, decoder) {
401
471
  }
402
472
  }
403
473
 
474
+ /** A job closed from a shell has its worktree settled here — unless it is the job's own shell, whose run settles it once the run ends. */
475
+ const settleHere = (db, id) => (process.env.SUMO_JOB === String(id) ? [] : jobs.settle(db, id));
476
+
404
477
  async function runJob(db, { args, flags }) {
405
478
  const [sub, rawId] = args;
406
479
  if (sub === 'new') {
407
480
  if (!flags.project) throw new UsageError(`usage: ${USAGE.job}`);
408
- const { job, warnings } = await jobs.newJob(db, {
481
+ const { job, jobs: attempts, warnings } = await jobs.newJob(db, {
409
482
  project: flags.project,
410
483
  title: flags.title,
411
484
  agent: flags.agent,
@@ -413,8 +486,9 @@ async function runJob(db, { args, flags }) {
413
486
  guide: flags.guide,
414
487
  reviews: flags.reviews === undefined ? undefined : jobs.parseJobId(flags.reviews),
415
488
  testsMayChange: Boolean(flags['tests-may-change']),
489
+ attempts: flags.attempts === undefined ? 1 : Number(flags.attempts),
416
490
  });
417
- return createdLines(job, warnings);
491
+ return createdLines(job, warnings, attempts);
418
492
  }
419
493
  if (sub === 'list') {
420
494
  const all = jobs.listJobs(db, { all: flags.all });
@@ -452,14 +526,25 @@ async function runJob(db, { args, flags }) {
452
526
  const stop = new AbortController();
453
527
  const interrupt = () => stop.abort();
454
528
  process.once('SIGINT', interrupt);
455
- let outcome;
529
+ // What follows the job unasked — a retry one step up of a first attempt that failed, a review of risky work done — runs
530
+ // here after it, the same way, and each is said in turn. The job's tab is the first one's: what is typed there goes to it.
531
+ let ran;
532
+ let last;
456
533
  try {
457
- outcome = await runJobLoop(db, id, { ...watch, signal: stop.signal, ...(process.stdout.isTTY ? { onStart: (job) => tabBegins(db, job, watch.onStart) } : {}) });
534
+ ran = await jobs.runFollowed(
535
+ db,
536
+ id,
537
+ async (each, warnings = []) => {
538
+ last = await runJobLoop(db, each, { ...watch, signal: stop.signal, ...(process.stdout.isTTY && each === id ? { onStart: (job) => tabBegins(db, job, watch.onStart) } : {}) });
539
+ return [...warnings, ...runLines(last), ...last.settled];
540
+ },
541
+ { signal: stop.signal },
542
+ );
458
543
  } finally {
459
544
  process.off('SIGINT', interrupt);
460
545
  }
461
- const lines = runLines(outcome).map(safeForTerminal);
462
- tabEnds(outcome.job, lines[0]);
546
+ const lines = ran.flatMap((step) => [...(step.line ? ['', step.line] : []), ...(step.result ?? []), ...(step.error ? [`j${step.id} stopped on an error: ${step.error}`] : [])]).map(safeForTerminal);
547
+ tabEnds(last.job, runLines(last)[0]);
463
548
  return lines;
464
549
  }
465
550
  case 'show':
@@ -481,7 +566,7 @@ async function runJob(db, { args, flags }) {
481
566
  case 'abandon':
482
567
  jobs.abandon(db, id);
483
568
  // A task just ended: if the session is already big, this is the cheapest moment to start a fresh one.
484
- return [`abandoned j${id}`, ...[taskEndedNudge(db)].filter(Boolean)];
569
+ return [`abandoned j${id}`, ...(await settleHere(db, id)), ...[taskEndedNudge(db)].filter(Boolean)];
485
570
  case 'baseline':
486
571
  return jobs.baseline(db, id);
487
572
  case 'verify': {
@@ -503,6 +588,7 @@ async function runJob(db, { args, flags }) {
503
588
  `STATUS: ${job.status === 'done' ? 'DONE' : 'FAILED'}${unverified ? ' (UNVERIFIED — taken without running the checks)' : ''} — j${id}`,
504
589
  ...(verdict?.flags ?? []).map((f) => ` look at: ${f}`),
505
590
  ...learned.applied.map((l) => ` ${l}`),
591
+ ...(await settleHere(db, id)),
506
592
  ...[taskEndedNudge(db)].filter(Boolean),
507
593
  ];
508
594
  }
@@ -649,8 +735,8 @@ function runBackup(db) {
649
735
  return [`backed up to ${file}${pruned > 0 ? ` (removed ${pruned} old)` : ''}`];
650
736
  }
651
737
 
652
- function runDoctor() {
653
- const checks = doctor();
738
+ async function runDoctor() {
739
+ const checks = await doctor();
654
740
  // On a terminal the mark is coloured, so a failure stands out of a column of oks; piped, it is the same words.
655
741
  const s = styles(colourEnabled());
656
742
  for (const c of checks) {
@@ -700,9 +786,10 @@ export async function main(argv) {
700
786
  db.close();
701
787
  }
702
788
  }
703
- if (command === 'doctor') return runDoctor();
789
+ if (command === 'doctor') return await runDoctor();
704
790
  if (command === 'config') {
705
791
  const { args } = parse(rest, { value: [], bool: [] });
792
+ if (args[1] !== undefined && fromTool()) throw new UsageError(OWNER_ONLY);
706
793
  process.stdout.write(`${config(args[0], args[1]).join('\n')}\n`);
707
794
  return 0;
708
795
  }
@@ -711,6 +798,8 @@ export async function main(argv) {
711
798
  const spec = Object.hasOwn(COMMANDS, command) ? COMMANDS[command] : null;
712
799
  if (!spec) throw new UsageError(`unknown command "${command}" — see: sumo help`);
713
800
  const parsed = parse(rest, spec);
801
+ if (JOB_NEVER.includes(command) && fromJob()) throw new UsageError(jobWrites());
802
+ if (OWNER_COMMANDS.has(command) && fromTool() && OWNER_COMMANDS.get(command)(parsed.args)) throw new UsageError(OWNER_ONLY);
714
803
  const db = openDb();
715
804
  try {
716
805
  const lines = await spec.run(db, parsed);
package/src/cost.mjs ADDED
@@ -0,0 +1,128 @@
1
+ import { MODEL_IDS, MODELS, modelId } from './catalog.mjs';
2
+ import { CACHE_WRITE, PRICES } from './model.mjs';
3
+ import { getProject } from './projects.mjs';
4
+
5
+ /**
6
+ * Where the money goes, read from the ledger: every request `model_runs` holds, by the kind of conversation that made it
7
+ * and the model that answered, in dollars and in the four ways a request is paid for — input read fresh, input read from
8
+ * the cache, input written to it, and output. Then the cache rewrites: requests that paid to write their context again
9
+ * while the cache should still have held it. A conversation here is a job, or outside one a chat session, on one model:
10
+ * the advisor answers in the same session on a model of its own, and a cache is never shared between models.
11
+ */
12
+
13
+ /** A request that read less than this from the cache found next to nothing of its context there. */
14
+ const REWRITE_READ_UNDER = 10_000;
15
+ /** …and wrote more than this share of its input to the cache again. */
16
+ const REWRITE_SHARE = 0.5;
17
+ /** How long what is written to the cache lives unread: a request this soon after the one before should have found it. */
18
+ const CACHE_LIVES_MS = 5 * 60_000;
19
+
20
+ const PARTS = ['uncached', 'read', 'write', 'output'];
21
+
22
+ /** What one request paid for each part, from its tokens and the price list; a model the list does not know splits into nothing. */
23
+ function partsOf(row) {
24
+ const price = PRICES[modelId(row.model)];
25
+ if (!price) return { uncached: 0, read: 0, write: 0, output: 0 };
26
+ // The ledger keeps the whole input; what was read fresh is what the cache neither gave nor took.
27
+ const read = row.cache_read_tokens ?? 0;
28
+ const written = row.cache_creation_tokens ?? 0;
29
+ const plain = Math.max(0, (row.input_tokens ?? 0) - read - written);
30
+ return {
31
+ uncached: (plain * price.input) / 1_000_000,
32
+ read: (read * price.input * price.cacheRead) / 1_000_000,
33
+ write: (written * price.input * CACHE_WRITE) / 1_000_000,
34
+ output: ((row.output_tokens ?? 0) * price.output) / 1_000_000,
35
+ };
36
+ }
37
+
38
+ const empty = () => ({ requests: 0, usd: 0, uncached: 0, read: 0, write: 0, output: 0, search: 0 });
39
+
40
+ function add(into, row, parts) {
41
+ into.requests++;
42
+ into.usd += row.cost_usd ?? 0;
43
+ for (const part of PARTS) into[part] += parts[part];
44
+ // What the tokens do not explain is what a search cost on top of them.
45
+ into.search += Math.max(0, (row.cost_usd ?? 0) - PARTS.reduce((sum, part) => sum + parts[part], 0));
46
+ }
47
+
48
+ /**
49
+ * The ledger's rows, summed: the whole, each kind and model (dearest first), and the cache rewrites — requests that read
50
+ * under 10k from the cache and wrote over half their input to it, under five minutes after the request before in the same
51
+ * conversation. Only a request that answered counts as the one before: a failed one warmed nothing. Pure, so it is tested
52
+ * on rows alone.
53
+ */
54
+ export function breakdown(rows) {
55
+ const total = empty();
56
+ const groups = new Map();
57
+ const rewrites = { requests: 0, usd: 0 };
58
+ const last = new Map();
59
+ const ordered = [...rows].sort((a, b) => (a.ts < b.ts ? -1 : a.ts > b.ts ? 1 : 0));
60
+ for (const row of ordered) {
61
+ const parts = partsOf(row);
62
+ add(total, row, parts);
63
+ const key = `${row.kind}\n${row.model}`;
64
+ if (!groups.has(key)) groups.set(key, { kind: row.kind, model: row.model, ...empty() });
65
+ add(groups.get(key), row, parts);
66
+
67
+ const conversation = row.job_id !== null && row.job_id !== undefined ? `j${row.job_id}` : row.session_id ? `s${row.session_id}` : null;
68
+ if (conversation === null || !(row.input_tokens > 0)) continue;
69
+ const thread = `${conversation}\n${row.model}`;
70
+ const at = Date.parse(row.ts);
71
+ const before = last.get(thread);
72
+ last.set(thread, at);
73
+ const read = row.cache_read_tokens ?? 0;
74
+ const written = row.cache_creation_tokens ?? 0;
75
+ if (before !== undefined && at - before < CACHE_LIVES_MS && read < REWRITE_READ_UNDER && written > row.input_tokens * REWRITE_SHARE) {
76
+ rewrites.requests++;
77
+ rewrites.usd += parts.write;
78
+ }
79
+ }
80
+ return { total, groups: [...groups.values()].sort((a, b) => b.usd - a.usd), rewrites };
81
+ }
82
+
83
+ const dollars = (usd) => `$${usd.toFixed(2)}`;
84
+ const count = (n, word) => `${n.toLocaleString('en-US')} ${word}${n === 1 ? '' : 's'}`;
85
+ const percent = (part, whole) => (whole > 0 ? ` (${Math.round((part / whole) * 100)}%)` : '');
86
+ /** A model by the name Sumo calls it; a local model or one the list does not know, as the ledger has it. */
87
+ const nameOf = (model) => MODELS.find((name) => MODEL_IDS[name] === model) ?? model;
88
+
89
+ /** The four parts of a sum, and a search when one was paid for; with `of`, each part's share of it. */
90
+ function split(sum, of = null) {
91
+ const share = (part) => (of === null ? '' : percent(part, of));
92
+ const parts = [`uncached ${dollars(sum.uncached)}${share(sum.uncached)}`, `cache read ${dollars(sum.read)}${share(sum.read)}`, `cache write ${dollars(sum.write)}${share(sum.write)}`, `output ${dollars(sum.output)}${share(sum.output)}`];
93
+ if (sum.search >= 0.005) parts.push(`search ${dollars(sum.search)}`);
94
+ return parts.join(' · ');
95
+ }
96
+
97
+ /**
98
+ * `sumo cost [--days N] [--project S]`: what the ledger says was spent, the whole first, then each kind and model, then
99
+ * the cache rewrites. A project's spend is its jobs and the chat sessions its card came up in — a session that worked
100
+ * on two projects is counted under each.
101
+ */
102
+ export function costLines(db, { days, project } = {}) {
103
+ const slug = project === undefined ? null : getProject(db, project).slug;
104
+ const since = days === undefined ? null : new Date(Date.now() - days * 86_400_000).toISOString();
105
+ const rows = db
106
+ .prepare(
107
+ `SELECT ts, kind, model, input_tokens, output_tokens, cost_usd, cache_read_tokens, cache_creation_tokens, job_id, session_id
108
+ FROM model_runs
109
+ WHERE (? IS NULL OR ts >= ?)
110
+ AND (? IS NULL
111
+ OR job_id IN (SELECT id FROM jobs WHERE project = ?)
112
+ OR (job_id IS NULL AND session_id IN (SELECT session_id FROM session_injections WHERE slug = ?)))
113
+ ORDER BY ts, id`,
114
+ )
115
+ .all(since, since, slug, slug, slug);
116
+ const window = days === undefined ? null : `the last ${count(days, 'day')}`;
117
+ if (rows.length === 0) return [`nothing was spent ${window ? `in ${window}` : 'yet'}${slug ? ` on ${slug}` : ''}`];
118
+
119
+ const { total, groups, rewrites } = breakdown(rows);
120
+ const share = total.usd > 0 ? `, ${Math.round((rewrites.usd / total.usd) * 100)}% of the total` : '';
121
+ const scope = `${window ?? `since ${rows[0].ts.slice(0, 10)}`}${slug ? ` · ${slug}` : ''}`;
122
+ return [
123
+ `${scope}: ${count(total.requests, 'request')}, ${dollars(total.usd)} — ${split(total, total.usd)}`,
124
+ // A group that cost nothing — the local model's — has nothing to split.
125
+ ...groups.map((g) => ` ${g.kind} · ${nameOf(g.model)}: ${count(g.requests, 'request')}, ${dollars(g.usd)}${g.usd >= 0.005 ? ` — ${split(g)}` : ''}`),
126
+ `cache rewrites: ${count(rewrites.requests, 'request')} read under ${REWRITE_READ_UNDER / 1000}k from the cache and wrote most of their context again, under ${CACHE_LIVES_MS / 60_000} minutes after the request before — ${dollars(rewrites.usd)} of cache writes${share}`,
127
+ ];
128
+ }
package/src/db.mjs CHANGED
@@ -1,7 +1,7 @@
1
1
  import { chmodSync, closeSync, existsSync, mkdirSync, openSync, statSync } from 'node:fs';
2
2
  import { dirname } from 'node:path';
3
- import { DatabaseSync } from 'node:sqlite';
4
3
  import { paths } from './paths.mjs';
4
+ import { DatabaseSync } from './sqlite.mjs';
5
5
 
6
6
  /**
7
7
  * One entry per schema version, applied in order and never edited once shipped.
@@ -230,6 +230,45 @@ const MIGRATIONS = [
230
230
  'job_id INTEGER',
231
231
  'session_id TEXT',
232
232
  ]),
233
+
234
+ // 8 — a memory may carry search terms beside the user's words: what it is about, in words it does not use itself.
235
+ // They are searched, never shown as the user's words. A full-text table takes no new column, so the index is made
236
+ // again with them, and filled from every memory already stored.
237
+ (db) => {
238
+ addColumnsIfMissing(db, 'memories', ['keys TEXT']);
239
+ db.exec(`
240
+ DROP TRIGGER IF EXISTS memories_fts_insert;
241
+ DROP TRIGGER IF EXISTS memories_fts_delete;
242
+ DROP TRIGGER IF EXISTS memories_fts_update;
243
+ DROP TABLE IF EXISTS memories_fts;
244
+
245
+ CREATE VIRTUAL TABLE memories_fts USING fts5(
246
+ title, cue, body, topic, keys,
247
+ content='memories', content_rowid='id', tokenize='porter unicode61'
248
+ );
249
+ INSERT INTO memories_fts(memories_fts) VALUES ('rebuild');
250
+
251
+ CREATE TRIGGER memories_fts_insert AFTER INSERT ON memories BEGIN
252
+ INSERT INTO memories_fts(rowid, title, cue, body, topic, keys)
253
+ VALUES (new.id, new.title, new.cue, new.body, new.topic, new.keys);
254
+ END;
255
+
256
+ CREATE TRIGGER memories_fts_delete AFTER DELETE ON memories BEGIN
257
+ INSERT INTO memories_fts(memories_fts, rowid, title, cue, body, topic, keys)
258
+ VALUES ('delete', old.id, old.title, old.cue, old.body, old.topic, old.keys);
259
+ END;
260
+
261
+ CREATE TRIGGER memories_fts_update AFTER UPDATE OF title, cue, body, topic, keys ON memories BEGIN
262
+ INSERT INTO memories_fts(memories_fts, rowid, title, cue, body, topic, keys)
263
+ VALUES ('delete', old.id, old.title, old.cue, old.body, old.topic, old.keys);
264
+ INSERT INTO memories_fts(rowid, title, cue, body, topic, keys)
265
+ VALUES (new.id, new.title, new.cue, new.body, new.topic, new.keys);
266
+ END;
267
+ `);
268
+ },
269
+ // 9 — whether the router called a job's work risky (security, credentials, money, migrations, concurrency): 1 or 0, so such
270
+ // work is reviewed once it is done. Nullable: a job routed before this migration was never asked.
271
+ (db) => addColumnsIfMissing(db, 'jobs', ['risky INTEGER']),
233
272
  ];
234
273
 
235
274
  /**