sumo-agents 0.6.1 → 0.7.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/card.mjs CHANGED
@@ -16,20 +16,25 @@ export function ago(iso, now) {
16
16
  return `${Math.round(hours / 24)}d ago`;
17
17
  }
18
18
 
19
- /** How long a guess is put to the user; after that it waits on the memory page and in search. */
20
- const GUESS_ASKED_DAYS = 14;
19
+ /** How long a held memory is put to the user; after that it waits on the memory page. */
20
+ const HELD_ASKED_DAYS = 14;
21
21
  const ASK_LINE_MAX = 120;
22
+ /** The question put, by why the memory is held: read from outside, or saved from the model's shell without the user's words. */
23
+ const HELD_ASKS = { outside: 'is this right?', shell: 'they never typed this — keep it?' };
22
24
 
23
25
  /**
24
- * What to put to the user about these scopes: guesses newer than two weeks, and notices whose two memories both
25
- * still stand — superseding or forgetting either settles one. The session-start block asks about everything and the
26
- * session's own project; a project's card asks about that project, wherever the session was started.
26
+ * What to put to the user about these scopes: memories newer than two weeks that are held for them — because the
27
+ * conversation they came from read the web or an MCP server, or because the model saved from its shell what the user
28
+ * never typed; nothing else is held: what the memory pass cannot tie to the user's own words is dropped, not queued
29
+ * as a guess — and notices whose two memories both still stand (superseding
30
+ * or forgetting either settles one). The session-start block asks about everything and the session's own project; a
31
+ * project's card asks about that project, wherever the session was started.
27
32
  */
28
- export function askLines(db, { scopes, now, guesses: maxGuesses, notices: maxNotices }) {
33
+ export function askLines(db, { scopes, now, held: maxHeld, notices: maxNotices }) {
29
34
  const marks = scopes.map(() => '?').join(', ');
30
- const since = new Date(Date.parse(now) - GUESS_ASKED_DAYS * 86_400_000).toISOString();
31
- const guesses = db.prepare(`SELECT * FROM memories WHERE state = 'unconfirmed' AND scope IN (${marks}) AND created_at >= ? ORDER BY id LIMIT ?`).all(...scopes, since, maxGuesses);
32
- const out = guesses.map((m) => `Ask the user (then sumo confirm|reject m${m.id}): is this right? "${clip(m.type === 'procedure' ? `workflow "${m.title}"` : m.body, ASK_LINE_MAX)}"`);
35
+ const since = new Date(Date.parse(now) - HELD_ASKED_DAYS * 86_400_000).toISOString();
36
+ const held = db.prepare(`SELECT * FROM memories WHERE state = 'unconfirmed' AND held_for IS NOT NULL AND scope IN (${marks}) AND created_at >= ? ORDER BY id LIMIT ?`).all(...scopes, since, maxHeld);
37
+ const out = held.map((m) => `Ask the user (then sumo confirm|reject m${m.id}): ${HELD_ASKS[m.held_for] ?? HELD_ASKS.outside} "${clip(m.type === 'procedure' ? `workflow "${m.title}"` : m.body, ASK_LINE_MAX)}"`);
33
38
  const notices = db
34
39
  .prepare(
35
40
  `SELECT n.* FROM notices n
@@ -46,7 +51,7 @@ export function askLines(db, { scopes, now, guesses: maxGuesses, notices: maxNot
46
51
  }
47
52
 
48
53
  /** The most a card asks: room is kept for what the project is. */
49
- const CARD_GUESSES = 2;
54
+ const CARD_HELD = 2;
50
55
  const CARD_NOTICES = 1;
51
56
 
52
57
  /**
@@ -71,7 +76,7 @@ export function card(db, nameOrAlias, { budget = CARD_BUDGET_TOKENS, now = new D
71
76
 
72
77
  // Asked of the user, so only where the user is: first, and whole — clipped, a question would lose what it asks.
73
78
  // A job's brief and `sumo project show` leave them out.
74
- if (asks) for (const text of askLines(db, { scopes: [scope], now, guesses: CARD_GUESSES, notices: CARD_NOTICES })) candidates.push({ priority: 0, order: order++, text, id: null });
79
+ if (asks) for (const text of askLines(db, { scopes: [scope], now, held: CARD_HELD, notices: CARD_NOTICES })) candidates.push({ priority: 0, order: order++, text, id: null });
75
80
 
76
81
  for (const m of rows.filter((r) => r.scan_key)) offer(SCAN_PRIORITY[m.scan_key] ?? 11, m.body, m.id);
77
82
  for (const m of rows.filter((r) => !r.scan_key && (r.type === 'preference' || r.type === 'decision'))) offer(PRIORITY.rule, `rule m${m.id}: ${m.body}`, m.id);
package/src/catalog.mjs CHANGED
@@ -6,8 +6,8 @@ import { UsageError } from './memory.mjs';
6
6
  /**
7
7
  * The models Sumo can run on: the short names the router, `/model` and `sumo config` use, cheapest
8
8
  * first, and the API model each one means. Each has a switch. `sumo setup` asks the API once which
9
- * of them this credential can use and sets the switches from the answer; `sumo models discover` asks
10
- * again; `sumo models enable|disable <name>` sets one by hand. The chat, the router, the passes and a
9
+ * of them this credential can use and sets the switches from the answer; the settings page asks again
10
+ * (API models › Discover) and sets one by hand. The chat, the router, the passes and a
11
11
  * job's run all read the switches as they are now.
12
12
  */
13
13
  export const MODEL_IDS = {
@@ -58,7 +58,7 @@ export function knownModel(name, also = []) {
58
58
  /** Why `name` cannot be used right now, with the way out (`orElse` is another one), or null while it is on. */
59
59
  export function offLine(db, name, orElse) {
60
60
  if (modelStates(db)[name].on) return null;
61
- return `${name} is off — sumo models enable ${name}${orElse ? `, or ${orElse}` : ''}`;
61
+ return `${name} is off — turn it on under API models, on the settings page (sumo config)${orElse ? `, or ${orElse}` : ''}`;
62
62
  }
63
63
 
64
64
  /** `name` is on, or a usage error saying how to turn it on. */
package/src/chat.mjs CHANGED
@@ -1,6 +1,6 @@
1
1
  import { randomUUID } from 'node:crypto';
2
2
  import { EventEmitter } from 'node:events';
3
- import { appendFileSync, mkdirSync, readFileSync, rmSync, statSync } from 'node:fs';
3
+ import { appendFileSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
4
4
  import { basename, dirname, join, relative, resolve, sep } from 'node:path';
5
5
  import { createInterface } from 'node:readline/promises';
6
6
  import { isAdvisorTool } from './advisor.mjs';
@@ -99,6 +99,7 @@ function commandList(db, { effortNow = () => null, inUse = () => ({}), saved = (
99
99
  { name: 'context', hint: 'how full the context is, and what it has cost' },
100
100
  { name: 'export', args: '[path]', hint: 'save the conversation as a Markdown file' },
101
101
  { name: 'thinking', args: 'on|off', hint: "show or hide the model's thinking as it works", choices: (given) => (given.length === 0 ? ['on', 'off'] : []) },
102
+ { name: 'config', hint: 'every setting, on one page' },
102
103
  { name: 'help', hint: 'the commands and the keys' },
103
104
  { name: 'handoff', hint: 'start fresh from a hand-off the model writes' },
104
105
  { name: 'new', hint: 'start a fresh session (/clear does too)' },
@@ -172,7 +173,12 @@ function branchOf(dir) {
172
173
  for (let at = resolve(dir); ; at = dirname(at)) {
173
174
  const git = join(at, '.git');
174
175
  try {
175
- const home = statSync(git).isDirectory() ? git : resolve(at, /^gitdir: (.+)$/m.exec(readFileSync(git, 'utf8'))[1]);
176
+ let home = git;
177
+ try {
178
+ home = resolve(at, /^gitdir: (.+)$/m.exec(readFileSync(git, 'utf8'))[1]);
179
+ } catch (cause) {
180
+ if (cause.code !== 'EISDIR') throw cause;
181
+ }
176
182
  const head = readFileSync(join(home, 'HEAD'), 'utf8').trim();
177
183
  return /^ref: refs\/heads\/(.+)$/.exec(head)?.[1] ?? head.slice(0, 8);
178
184
  } catch {
@@ -268,7 +274,7 @@ export function contextReport({ contextTokens = 0, rows = [], turns = 0, calls =
268
274
  }
269
275
 
270
276
  /** A session past its budget, in one line: what it has cost, how to start afresh, and how to move the line. */
271
- const budgetLine = (cost) => `this session has cost $${cost.toFixed(2)} — /new starts a fresh one; sumo config chat.budget changes when this is said`;
277
+ const budgetLine = (cost) => `this session has cost $${cost.toFixed(2)} — /new starts a fresh one; Spend notice, on the settings page (/config), changes when this is said`;
272
278
 
273
279
  /** Where the context is large enough that quality drops, and where it is time for /handoff: the bands the session is told about. */
274
280
  const CONTEXT_LARGE = 60_000;
@@ -320,7 +326,7 @@ export function createChat(db, { model, effort, cwd = process.cwd(), send = send
320
326
  // A model the user turned off is not chatted on, however the chat came to be on it; auto reads the switches each turn.
321
327
  // A full API id is that model too (claude-opus-5-5 is opus), switched off or on with it.
322
328
  const named = MODELS.find((name) => MODEL_IDS[name] === model) ?? model;
323
- if (named !== 'auto' && MODELS.includes(named)) assertOn(db, named, 'sumo config chat.model <name>');
329
+ if (named !== 'auto' && MODELS.includes(named)) assertOn(db, named, 'pick another Model there');
324
330
  effort ??= model === 'auto' ? null : configured(db, 'chat.effort');
325
331
  /** On auto, the route the last turn ran on; null otherwise. */
326
332
  let routed = null;
@@ -804,10 +810,22 @@ export function createChat(db, { model, effort, cwd = process.cwd(), send = send
804
810
  return id;
805
811
  }
806
812
 
807
- /** A turn that ended before the model answered left its operator message at the tail; the API takes one only where the model answers next, so before anything follows it, it becomes text. An effort said there may stand anywhere, and stays. */
813
+ /**
814
+ * A turn that ended before the model answered left its operator message unanswered. The API takes one only where the model
815
+ * answers next, past any other system messages beside it — an effort said after it does not shelter it — so before anything
816
+ * follows it, it becomes text. A request with one stranded was refused, or sent it as this same text to a model that takes
817
+ * none, so no reply rests on what changes; a session saved stranded is mended here too. An effort said alone may stand anywhere, and stays.
818
+ */
808
819
  function settleTail() {
809
- const tail = params.messages.at(-1);
810
- if (tail?.role === 'system' && !effortOnly(tail)) params.messages[params.messages.length - 1] = asText(tail.content);
820
+ let next = null;
821
+ for (let i = params.messages.length - 1; i >= 0; i--) {
822
+ const m = params.messages[i];
823
+ if (m.role !== 'system') next = m.role;
824
+ else if (!effortOnly(m) && next !== 'assistant') {
825
+ params.messages[i] = asText(m.content);
826
+ next = 'user';
827
+ }
828
+ }
811
829
  }
812
830
 
813
831
  /**
@@ -982,7 +1000,8 @@ export function createChat(db, { model, effort, cwd = process.cwd(), send = send
982
1000
  const asked = outcome.stop === 'end_turn';
983
1001
  const edited = [...unchecked].map((path) => relative(workspace().cwd, path));
984
1002
  const checks = declared();
985
- const held = continued ? '' : event('stop', asked ? { last_assistant_message: outcome.text, stop_hook_active: false, edited, checks } : { stop_hook_active: true });
1003
+ // The reply goes with the event either way, for the journal: also the one a continued turn ends on, which asks nothing more.
1004
+ const held = event('stop', asked && !continued ? { last_assistant_message: outcome.text, stop_hook_active: false, edited, checks } : { last_assistant_message: outcome.text, stop_hook_active: true });
986
1005
  if (!held) return outcome;
987
1006
  const { context } = JSON.parse(held);
988
1007
  if (context.includes('<check>')) watch({ type: 'check', edited, checks });
@@ -1063,7 +1082,7 @@ export function createChat(db, { model, effort, cwd = process.cwd(), send = send
1063
1082
  const [, name, args = ''] = m;
1064
1083
  if (name === 'exit' || name === 'quit') return { control: 'quit' };
1065
1084
  if (name === 'new' || name === 'clear') return { control: 'new' };
1066
- if (name === 'memory' || name === 'undo' || name === 'context' || name === 'handoff') return { control: name };
1085
+ if (name === 'memory' || name === 'undo' || name === 'context' || name === 'handoff' || name === 'config') return { control: name };
1067
1086
  if (name === 'model' || name === 'resume' || name === 'mcp' || name === 'copy' || name === 'help' || name === 'stop' || name === 'export' || name === 'thinking') return { control: name, args: args.trim() };
1068
1087
  const make = Object.hasOwn(COMMANDS, name) ? COMMANDS[name] : undefined;
1069
1088
  if (make) return { ...make(args.trim()), said: args.trim() };
@@ -1162,6 +1181,8 @@ export function createChat(db, { model, effort, cwd = process.cwd(), send = send
1162
1181
  saved: () => others().map((s) => sessionLine(s, now())),
1163
1182
  end,
1164
1183
  commands,
1184
+ /** How this chat's MCP servers connected, for the settings page: each one's name, whether it is up, its tools. */
1185
+ mcpServers: () => (registry && !registry.error ? registry.servers() : []),
1165
1186
  get sessionId() {
1166
1187
  return sessionId;
1167
1188
  },
package/src/check.mjs ADDED
@@ -0,0 +1,371 @@
1
+ import { getMeta, setMeta } from './db.mjs';
2
+ import { replaySetAside } from './hooks.mjs';
3
+ import { tidyDue } from './dream.mjs';
4
+ import { emptyRun, extractorVersion, filingState } from './ledger.mjs';
5
+ import { localServerStatus } from './local-server.mjs';
6
+ import { paths } from './paths.mjs';
7
+ import { heartbeat } from './prime.mjs';
8
+ import { modelStats } from './scribe.mjs';
9
+ import { searchAll } from './search.mjs';
10
+ import { lastHeard, sessionsAwaitingExtraction } from './sessions.mjs';
11
+ import { CONFIG_DEFAULTS, modelFileOf } from './setup.mjs';
12
+ import { spoolStatus } from './spool.mjs';
13
+ import { STOPWORDS } from './text.mjs';
14
+
15
+ /**
16
+ * Memory checking itself, so a failure is loud: whether the user is still heard, whether what was heard can be found,
17
+ * whether anything waits where nobody looks. Capture once stopped for 35 days, with sumo commands run from Claude Code
18
+ * all the while, and the only sign was "last heard 35d ago" inside a line marked ok. Loaded only by the commands that report — `sumo memory status|check`, `sumo doctor`,
19
+ * the line a memory command prints inside a harness that is not heard — never by a hook.
20
+ */
21
+
22
+ const DAY_MS = 86_400_000;
23
+ const many = (n, one, more = `${one}s`) => `${n} ${n === 1 ? one : more}`;
24
+
25
+ /** How long ago, in the largest whole unit: `3d ago`, `5h ago`, `just now`. */
26
+ function sinceSaid(at, now) {
27
+ const hours = (Date.parse(now) - Date.parse(at)) / 3_600_000;
28
+ if (hours >= 24) return `${Math.floor(hours / 24)}d ago`;
29
+ return hours >= 1 ? `${Math.floor(hours)}h ago` : 'just now';
30
+ }
31
+
32
+ /** How old a project's scan may be before memory health names it. */
33
+ const SCAN_STALE_DAYS = 7;
34
+ /** A scan this old is a warning, not a note. */
35
+ const SCAN_WARN_DAYS = 30;
36
+
37
+ /** A finished conversation still unread after this long is not waiting its turn: nothing is reading. */
38
+ const UNREAD_FAIL_MS = 48 * 3_600_000;
39
+ /** This many conversations read in a row with nothing filed is said: one is normal, ten are a model that answers nothing. */
40
+ const EMPTY_RUN_WARN = 10;
41
+
42
+ /**
43
+ * The finished conversations still unread 48 hours after they went quiet, while the writer is on: `{ count, since }`,
44
+ * `since` when the oldest of them finished — its goodbye, or the last thing said or answered in it. A pass is started
45
+ * whenever a session starts or ends, so a conversation waits minutes; thirty once waited for weeks, and one left open
46
+ * for two days waited beside a status that counted it, behind checks that were all ok. Judged by the clock alone: a
47
+ * journal with nothing unread is never at fault for being quiet, and one conversation left unread over a holiday is
48
+ * said — the command that reads it is in the line.
49
+ */
50
+ function unreadLong(db, now) {
51
+ if ((getMeta(db, 'config.memory.model') ?? CONFIG_DEFAULTS['memory.model']) === 'off') return { count: 0, since: null };
52
+ const cutoff = new Date(Date.parse(now) - UNREAD_FAIL_MS).toISOString();
53
+ const answered = db.prepare('SELECT MAX(ts) AS at FROM replies WHERE session_id = ?');
54
+ const quietSince = (s) => {
55
+ if (s.ended_at) return s.ended_at;
56
+ const said = s.last_turn_at ?? s.started_at;
57
+ const reply = answered.get(s.id).at;
58
+ return reply && reply > said ? reply : said;
59
+ };
60
+ const finished = sessionsAwaitingExtraction(db, { now, limit: 1000 }).map(quietSince).filter((at) => at < cutoff).sort();
61
+ return { count: finished.length, since: finished[0] ?? null };
62
+ }
63
+
64
+ /**
65
+ * How memory is doing, as plain values for whoever says it — doctor, the memory status:
66
+ * - `beat`: whether a harness in use is still heard, and when each last was (`heartbeat` in prime.mjs);
67
+ * - `filing`: how the memory pass's filing stands (`filingState` in ledger.mjs);
68
+ * - `scans`: active projects whose scan is more than a week old, oldest first, with its age in days;
69
+ * - `unread`: finished conversations left unread for over 48 hours (`unreadLong`);
70
+ * - `emptyRun`: how many conversations read last, in a row, filed nothing (ledger.mjs).
71
+ * `filing` is handed in by a caller that already read it.
72
+ */
73
+ export function memoryHealth(db, now = new Date().toISOString(), { filing = filingState(db, now) } = {}) {
74
+ const scans = db
75
+ .prepare(`SELECT slug, scanned_at FROM projects WHERE status = 'active' AND scanned_at IS NOT NULL ORDER BY scanned_at`)
76
+ .all()
77
+ .map((p) => ({ slug: p.slug, days: Math.floor((Date.parse(now) - Date.parse(p.scanned_at)) / DAY_MS) }))
78
+ .filter((p) => p.days > SCAN_STALE_DAYS);
79
+ return { beat: heartbeat(db, now), filing, scans, unread: unreadLong(db, now), emptyRun: emptyRun(db) };
80
+ }
81
+
82
+ /**
83
+ * Memory health said in one line, for doctor and the memory status: `{ ok, fail, label, fix }`. Not ok when Claude
84
+ * Code is in use and not heard, conversations have waited two days unread, filing is paused, the last ten
85
+ * conversations read filed nothing, or a project's scan is a month old; `fix` says what to do about each. `fail` is
86
+ * what fails a run of doctor, the status and the check: sumo commands run from Claude Code while no turn arrives from
87
+ * it, or finished conversations nobody reads. How long ago anything was heard is in the label and is never a fault by itself.
88
+ */
89
+ export function memoryHealthLine(health, now = new Date().toISOString()) {
90
+ const { beat, filing, scans, unread = { count: 0, since: null } } = health;
91
+ const empty = (health.emptyRun ?? 0) >= EMPTY_RUN_WARN ? health.emptyRun : 0;
92
+ const both = beat.heard.claude && beat.heard.sumo;
93
+ const parts = [
94
+ beat.lastAt ? `last heard ${sinceSaid(beat.lastAt, now)}${both ? ` (Claude Code ${sinceSaid(beat.heard.claude, now)} · sumo chat ${sinceSaid(beat.heard.sumo, now)})` : ''}` : 'nothing heard yet',
95
+ `${filing.lastOkAt ? `last filed ${sinceSaid(filing.lastOkAt, now)}` : 'nothing filed yet'}${filing.paused ? ', filing paused' : filing.failures > 0 ? `, ${many(filing.failures, 'pass', 'passes')} failed since` : ''}`,
96
+ ];
97
+ if (filing.junkRate !== null) parts.push(`${Math.round(filing.junkRate * 100)}% of what was filed was thrown out`);
98
+ if (unread.count > 0) parts.push(`${many(unread.count, 'finished conversation')} unread for over 48 hours`);
99
+ if (empty > 0) parts.push(`the last ${empty} conversations read filed nothing`);
100
+ if (scans.length > 0) {
101
+ const named = scans.slice(0, 3).map((p) => `${p.slug}, ${p.days}d`).join('; ');
102
+ parts.push(`${many(scans.length, 'project scan')} over ${SCAN_STALE_DAYS} days old (${named}${scans.length > 3 ? '; …' : ''})`);
103
+ }
104
+ const old = scans.filter((p) => p.days > SCAN_WARN_DAYS);
105
+ const fix = [
106
+ beat.deaf ? beat.fix : null,
107
+ unread.count > 0 ? `${many(unread.count, 'finished conversation')} ${unread.count === 1 ? 'has' : 'have'} waited over 48 hours to be read (the oldest since ${unread.since.slice(0, 10)}): sumo memory run reads them, and sumo memory status says whether filing is paused` : null,
108
+ filing.paused ? `filing is paused: ${filing.reason}` : null,
109
+ empty > 0 ? `nothing is the normal answer for one conversation, not for ${empty} in a row: sumo memory show prints what the model is sent, sumo memory eval measures what it files` : null,
110
+ old.length > 0 ? `rescan: sumo project rescan ${old[0].slug}${old.length > 1 ? ` (and ${old.length - 1} more)` : ''}` : null,
111
+ ].filter(Boolean).join('; ');
112
+ return { ok: fix === '', fail: beat.deaf !== null || unread.count > 0, label: `memory: ${parts.join(' · ')}`, fix };
113
+ }
114
+
115
+ /** The full-text indexes, each over the table it is named for. */
116
+ const INDEXES = ['memories_fts', 'user_turns_fts', 'replies_fts'];
117
+ /** The newest turns the canary looks through for one with words of its own. */
118
+ const CANARY_LOOKS = 20;
119
+ /** The words of a turn the canary searches by, and the fewest that make a search of its own. */
120
+ const CANARY_WORDS = 6;
121
+ const CANARY_MIN = 3;
122
+ /** How far down the search's answer the turn may stand: others may hold the same words. */
123
+ const CANARY_SHOWN = 50;
124
+ /** A backup older than this is said: one is made weekly, at a session's start. */
125
+ const BACKUP_STALE_DAYS = 14;
126
+ /** A pass still `running` after this long was left by a process that died: a batch takes minutes. */
127
+ const RUN_DEAD_AFTER_MS = 30 * 60_000;
128
+ /** The finished conversations of a harness looked at for replies, and how many without one are no accident. */
129
+ const REPLY_LOOKS = 10;
130
+ const REPLY_MISSING = 3;
131
+ /** A conversation nobody has spoken in for this long is over (as in sessions.mjs). */
132
+ const FINISHED_AFTER_MS = 30 * 60_000;
133
+
134
+ /** What SQLite says is wrong with a full-text index — its own structure, and against the table it indexes — or null. */
135
+ function indexProblem(db, name) {
136
+ try {
137
+ db.exec(`INSERT INTO ${name}(${name}, rank) VALUES ('integrity-check', 1)`);
138
+ return null;
139
+ } catch (cause) {
140
+ return String(cause.message);
141
+ }
142
+ }
143
+
144
+ /** Builds each named index again from its table. */
145
+ function rebuildIndexes(db, names) {
146
+ for (const name of names) db.exec(`INSERT INTO ${name}(${name}) VALUES ('rebuild')`);
147
+ }
148
+
149
+ /** The longest words of a text that are its own: no stopword, nothing under four letters, each once. */
150
+ function distinctive(text) {
151
+ const found = text.toLowerCase().match(/[\p{L}\p{N}_]+/gu) ?? [];
152
+ return [...new Set(found.filter((w) => w.length >= 4 && !STOPWORDS.has(w)))].sort((a, b) => b.length - a.length).slice(0, CANARY_WORDS);
153
+ }
154
+
155
+ /**
156
+ * The canary: the newest turn of the journal with words of its own must be found by searching those words. It is the
157
+ * whole read path in one look — a turn written, indexed, and found — and it fails when any link is gone.
158
+ */
159
+ function canary(db) {
160
+ for (const turn of db.prepare('SELECT id, text FROM user_turns ORDER BY id DESC LIMIT ?').all(CANARY_LOOKS)) {
161
+ const picked = distinctive(turn.text);
162
+ if (picked.length < CANARY_MIN) continue;
163
+ // The one search everyone uses, over the conversations alone: it keeps no miss and counts no memory as used.
164
+ const found = searchAll(db, picked.join(' '), { turns: true, everywhere: true, limit: CANARY_SHOWN }).conversations.some((hit) => hit.kind === 'turn' && hit.id === turn.id);
165
+ return found
166
+ ? { ok: true, label: `the newest turn (t${turn.id}) is found by its own words`, fix: '' }
167
+ : { ok: false, label: `the newest turn (t${turn.id}) is not found by its own words (${picked.join(' ')})`, fix: 'the search index does not hold what was said — rebuild it: sumo memory check --fix' };
168
+ }
169
+ return { ok: true, label: 'no turn with words of its own to look for yet', fix: '' };
170
+ }
171
+
172
+ /** Whether the weekly backup is being made: one that failed, or is two weeks old with something to lose, is said. */
173
+ function backupCheck(db, now) {
174
+ const failed = getMeta(db, 'backup.failed');
175
+ if (failed) return { ok: false, label: `the weekly backup could not be written (${failed})`, fix: 'sumo backup tries again' };
176
+ const last = getMeta(db, 'last_backup');
177
+ const days = (at) => Math.floor((Date.parse(now) - Date.parse(at)) / DAY_MS);
178
+ if (last) {
179
+ const age = days(last);
180
+ return { ok: age <= BACKUP_STALE_DAYS, label: `last backup ${age === 0 ? 'today' : `${age}d ago`}`, fix: 'one is made weekly when a session starts; now: sumo backup' };
181
+ }
182
+ // Never backed up: a failure only once there is something two weeks old to lose.
183
+ const oldest = db.prepare('SELECT MIN(at) AS at FROM (SELECT MIN(created_at) AS at FROM memories UNION ALL SELECT MIN(ts) FROM user_turns)').get().at;
184
+ const owed = oldest !== null && days(oldest) > BACKUP_STALE_DAYS;
185
+ return { ok: !owed, label: owed ? `no backup yet, and memory goes back ${days(oldest)} days` : 'no backup yet (the first is made when a session starts)', fix: 'sumo backup' };
186
+ }
187
+
188
+ /**
189
+ * Conversations with what the user said and nothing the assistant answered, among each harness's last finished ones —
190
+ * only those from since replies are kept (a turn with a digest is one). One is an interrupted turn; most of them is a
191
+ * harness whose `stop` event does not reach sumo.
192
+ */
193
+ function repliesCheck(db, now) {
194
+ const cutoff = new Date(Date.parse(now) - FINISHED_AFTER_MS).toISOString();
195
+ const rows = db
196
+ .prepare(
197
+ `SELECT s.harness, EXISTS (SELECT 1 FROM replies r WHERE r.session_id = s.id) AS answered,
198
+ ROW_NUMBER() OVER (PARTITION BY s.harness ORDER BY s.started_at DESC, s.id DESC) AS nth
199
+ FROM sessions s
200
+ WHERE EXISTS (SELECT 1 FROM user_turns t WHERE t.session_id = s.id AND t.sha IS NOT NULL)
201
+ AND (s.ended_at IS NOT NULL OR COALESCE(s.last_turn_at, s.started_at) < ?)`,
202
+ )
203
+ .all(cutoff)
204
+ .filter((r) => r.nth <= REPLY_LOOKS);
205
+ const bad = [];
206
+ for (const harness of new Set(rows.map((r) => r.harness))) {
207
+ const mine = rows.filter((r) => r.harness === harness);
208
+ const missing = mine.filter((r) => !r.answered).length;
209
+ if (missing >= REPLY_MISSING && missing * 2 > mine.length) bad.push(`${missing} of the last ${mine.length} from ${harness === 'claude' ? 'Claude Code' : harness === 'sumo' ? 'sumo chat' : harness}`);
210
+ }
211
+ return bad.length > 0
212
+ ? { ok: false, label: `conversations kept without the assistant's replies: ${bad.join(', ')}`, fix: 'the stop event is not reaching sumo — sumo help hooks shows the line for it; logs/hook.log says what failed' }
213
+ : { ok: true, label: rows.length > 0 ? "conversations are kept with the assistant's replies" : 'no finished conversation to look at for replies yet', fix: '' };
214
+ }
215
+
216
+ /**
217
+ * Every check of the memory layer, each `{ name, ok, label, fix }`: the three full-text indexes (SQLite's own
218
+ * integrity-check, against the tables they index), the canary, the spool, the backup, passes left running, replies
219
+ * missing from conversations, and how filing stands. `sumo memory check` prints them and exits 1 when one fails;
220
+ * `sumo doctor` carries them. `fix: true` rebuilds an index that fails, and replays the spool's set-aside lines, before judging. `filing` is handed in by a
221
+ * caller that already read it.
222
+ */
223
+ export function memoryCheck(db, now = new Date().toISOString(), { fix = false, filing = filingState(db, now) } = {}) {
224
+ const checks = [];
225
+ const check = (name, { ok, label, fix: how = '' }) => checks.push({ name, ok, label, fix: ok ? '' : how });
226
+
227
+ for (const name of INDEXES) {
228
+ let problem = indexProblem(db, name);
229
+ let rebuilt = false;
230
+ if (problem && fix) {
231
+ rebuildIndexes(db, [name]);
232
+ rebuilt = true;
233
+ problem = indexProblem(db, name);
234
+ }
235
+ check(`index:${name}`, { ok: problem === null, label: `search index ${name}${rebuilt && !problem ? ' (rebuilt)' : ''}${problem ? `: ${problem}` : ''}`, fix: rebuilt ? 'rebuilding it did not mend it — sumo backup restore puts the newest backup back' : 'rebuild it: sumo memory check --fix' });
236
+ }
237
+
238
+ check('canary', canary(db));
239
+
240
+ // Mending tries what was set aside once more: a turn set aside while the database was busy goes in now.
241
+ const retried = fix ? replaySetAside(db).replayed : 0;
242
+ const again = retried > 0 ? ` (${retried} replayed)` : '';
243
+ const spool = spoolStatus();
244
+ const spooled = [spool.waiting > 0 ? `${many(spool.waiting, 'event')} not yet in the journal` : null, spool.bad > 0 ? `${many(spool.bad, 'line')} set aside as unreadable${again}` : null].filter(Boolean);
245
+ check('spool', {
246
+ ok: spooled.length === 0,
247
+ label: spooled.length === 0 ? `nothing waits in the spool${retried > 0 ? ` (${many(retried, 'line')} set aside ${retried === 1 ? 'was' : 'were'} replayed)` : ''}` : `the spool (${paths().spool}): ${spooled.join(', ')}`,
248
+ fix: [
249
+ spool.waiting > 0 ? 'what waits is replayed by the next thing said in a session; if it still waits after that the database cannot be written, and logs/hook.log says why' : null,
250
+ // What a retry could not replay was never an event: only reading it says what it was.
251
+ spool.bad > 0 ? `events.bad.jsonl holds what could not be replayed, with the reason on each line: ${fix ? 'read it, then delete it' : 'sumo memory check --fix tries them again'}` : null,
252
+ ].filter(Boolean).join('; '),
253
+ });
254
+
255
+ check('backup', backupCheck(db, now));
256
+
257
+ const dead = db.prepare(`SELECT COUNT(*) AS n, MIN(started_at) AS since FROM extractions WHERE status = 'running' AND started_at < ?`).get(new Date(Date.parse(now) - RUN_DEAD_AFTER_MS).toISOString());
258
+ check('passes', {
259
+ ok: dead.n === 0,
260
+ label: dead.n === 0 ? 'no memory pass was left unfinished' : `${many(dead.n, 'memory pass', 'memory passes')} left running by a process that died (since ${dead.since?.slice(0, 16)})`,
261
+ fix: 'sumo memory run reads those conversations again',
262
+ });
263
+
264
+ check('replies', repliesCheck(db, now));
265
+
266
+ const empty = emptyRun(db);
267
+ const said = [
268
+ filing.failures > 0 ? `${many(filing.failures, 'pass', 'passes')} failed in a row` : null,
269
+ filing.quarantined > 0 ? `${many(filing.quarantined, 'turn')} set aside after failing three times` : null,
270
+ filing.junkRate !== null ? `${Math.round(filing.junkRate * 100)}% of what was filed was thrown out` : null,
271
+ filing.fallbackUsed ? 'the last pass ran on the fallback model' : null,
272
+ empty >= EMPTY_RUN_WARN ? `the last ${empty} conversations read filed nothing` : null,
273
+ ].filter(Boolean);
274
+ check('filing', { ok: !filing.paused, label: `filing ${filing.paused ? 'is paused' : 'is on'}${said.length > 0 ? ` — ${said.join(', ')}` : ''}`, fix: filing.reason ?? '' });
275
+
276
+ return checks;
277
+ }
278
+
279
+ /** When the line below was last said: it is said once a day, not on every command. */
280
+ const NOT_HEARD_SAID = 'heard.claude_told_at';
281
+ const NOT_HEARD_AFTER_MS = DAY_MS;
282
+
283
+ /**
284
+ * The line a memory command prints when it is run inside Claude Code and Claude Code is not being heard: `CLAUDECODE=1`
285
+ * is in the environment (Claude Code sets it in its shell) and no turn has come from harness 'claude' in a day — with
286
+ * the hooks in place, the prompt that led to this command would have been one. Says what is wrong and where the lines
287
+ * to add are; '' when all is well, when this is sumo's own shell, or when it was said in the last day (remembered in
288
+ * `meta`, so it does not nag on every command).
289
+ */
290
+ export function notHeardLine(db, { env = process.env, now = new Date().toISOString() } = {}) {
291
+ if (env.CLAUDECODE !== '1' || env.SUMO_TOOL || env.SUMO_JOB) return '';
292
+ const heard = lastHeard(db, 'claude');
293
+ if (heard && Date.parse(now) - Date.parse(heard) < NOT_HEARD_AFTER_MS) return '';
294
+ const told = getMeta(db, NOT_HEARD_SAID);
295
+ if (told && Date.parse(now) - Date.parse(told) < NOT_HEARD_AFTER_MS) return '';
296
+ setMeta(db, NOT_HEARD_SAID, now);
297
+ const since = heard ? `nothing has come from it for ${sinceSaid(heard, now).replace(' ago', '')}` : 'nothing has ever come from it';
298
+ return `sumo: this Claude Code session is not being heard by sumo's memory (${since}) — what the user says here is not kept. Tell the user: the hook lines are missing from Claude Code's settings; sumo help hooks prints them and says where they go.`;
299
+ }
300
+
301
+ /**
302
+ * `sumo help hooks`: the lines that make Claude Code heard, to be added by the user — sumo never edits another tool's
303
+ * settings, and never reads them. The launcher is named by its full path: a hook runs without the user's PATH.
304
+ */
305
+ export function hooksHelp() {
306
+ const sumo = paths().launcher;
307
+ const line = (event, name) => ` ${`"${event}":`.padEnd(20)}[{ "hooks": [{ "type": "command", "command": "${sumo} hook ${name}" }] }]`;
308
+ return [
309
+ "sumo's memory hears Claude Code through Claude Code's hooks. Add these to the \"hooks\" object of",
310
+ "~/.claude/settings.json (every project), or of one project's .claude/settings.json — sumo never",
311
+ "edits another tool's settings, so they are yours to add, and to take out again:",
312
+ '',
313
+ ' "hooks": {',
314
+ `${line('SessionStart', 'session-start')},`,
315
+ `${line('UserPromptSubmit', 'prompt')},`,
316
+ `${line('Stop', 'stop')},`,
317
+ `${line('SessionEnd', 'session-end')}`,
318
+ ' }',
319
+ '',
320
+ 'session-start puts the memory block in front of the session, prompt keeps what you say (and brings',
321
+ "a project's card in), stop keeps the assistant's reply, session-end closes the conversation so it is",
322
+ "read for memory. Each takes the event's JSON on stdin and never fails the session: what goes wrong",
323
+ 'is in logs/hook.log, and what could not be written waits in the spool.',
324
+ '',
325
+ 'To see it work: say something in Claude Code, then sumo memory status — "last heard" is just now.',
326
+ ];
327
+ }
328
+
329
+ /** The pass's own requests in the ledger of model runs, named as the status says them. */
330
+ const HALVES = { scribe: 'filing', dream: 'tidying' };
331
+ /** A status line: its label in a column of its own, so the values stand in one. */
332
+ const LABEL_WIDTH = 11;
333
+ const row = (label, value) => `${label.padEnd(LABEL_WIDTH)}${value}`;
334
+
335
+ /**
336
+ * `sumo memory status`: one screen that says how memory stands now — whether the user is heard, and from where; the
337
+ * model and which rung of the ladder is in use (the local model, the fallback, or none); what waits; whether filing
338
+ * is on, and why not; the last tidy; what the pass has spent. The lines carry `exitCode: 1` when Claude Code is in use
339
+ * and not heard.
340
+ */
341
+ export async function memoryStatus(db, now = new Date().toISOString()) {
342
+ const filing = filingState(db, now);
343
+ const health = memoryHealthLine(memoryHealth(db, now, { filing }), now);
344
+ const model = getMeta(db, 'config.memory.model') ?? CONFIG_DEFAULTS['memory.model'];
345
+ const server = model === 'local' ? await localServerStatus(db, { file: modelFileOf(db) }) : null;
346
+ const rung = model === 'off' ? 'none: the pass is off, what is said is still kept and found by search' : filing.fallbackUsed ? 'the fallback: the local model could not answer the last pass' : model === 'local' ? 'the local model' : `${model}, as set`;
347
+ const version = extractorVersion(db);
348
+ const finished = sessionsAwaitingExtraction(db, { now, limit: 1000 }).length;
349
+ const spool = spoolStatus();
350
+ const heard = (at) => (at ? sinceSaid(at, now) : 'never');
351
+ const tidied = db.prepare(`SELECT MAX(ts) AS at FROM model_runs WHERE kind = 'dream' AND ok = 1`).get()?.at ?? null;
352
+ const sweep = getMeta(db, 'dream.last_tidy');
353
+ const failedAt = getMeta(db, 'memory.tidy_failed_at');
354
+ const day = (at) => (at ? at.slice(0, 10) : 'never');
355
+ // The ledger holds every request; the pass's own are its filing and its tidying, named so.
356
+ const spent = modelStats(db)
357
+ .filter((l) => /^(scribe|dream): /.test(l))
358
+ .map((l) => l.replace(/^(scribe|dream)/, (kind) => HALVES[kind]));
359
+ const lines = [
360
+ `${health.ok ? 'ok ' : health.fail ? 'FAIL' : 'warn'} ${health.label}${health.fix ? ` — ${health.fix}` : ''}`,
361
+ row('heard', `Claude Code ${heard(lastHeard(db, 'claude'))} · sumo chat ${heard(lastHeard(db, 'sumo'))}`),
362
+ row('model', `${model}${server ? ` · ${server}` : ''} · in use: ${rung} · extractor ${version}`),
363
+ row('waiting', `${many(finished, 'finished conversation')} to read · ${many(spool.waiting, 'spooled event')}${spool.bad > 0 ? ` (${spool.bad} unreadable)` : ''} · ${many(filing.quarantined, 'quarantined turn')}`),
364
+ row('filing', filing.paused ? `paused — ${filing.reason}` : filing.failures > 0 ? `on — failed ${many(filing.failures, 'time')} in a row, pauses at three` : 'on'),
365
+ row('last tidy', `${day(tidied)} · weekly sweep: ${day(sweep)}${tidyDue(db, now) ? ' — due: the next pass tidies' : ''}`),
366
+ ...(failedAt ? [row('failing', `the last tidy, at ${failedAt.slice(0, 16)}; tried again by itself six hours on, or now: sumo memory run --tidy`)] : []),
367
+ ...(spent.length > 0 ? [row('spent', spent[0]), ...spent.slice(1).map((l) => row('', l))] : []),
368
+ ];
369
+ // A harness in use and not heard fails the status, as it fails doctor and the check: a script can act on it.
370
+ return health.fail ? Object.assign(lines, { exitCode: 1 }) : lines;
371
+ }