sumo-agents 0.3.0 → 0.5.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 (52) hide show
  1. package/AGENTS.md +8 -6
  2. package/CHANGELOG.md +155 -0
  3. package/README.md +82 -19
  4. package/bin/sumo.mjs +13 -2
  5. package/guides/feature.md +2 -1
  6. package/guides/memory.md +6 -4
  7. package/guides/projects.md +1 -1
  8. package/guides/review.md +1 -1
  9. package/package.json +5 -4
  10. package/prompts/dream.md +6 -0
  11. package/spinner.txt +25 -1
  12. package/src/apply.mjs +146 -18
  13. package/src/auth.mjs +32 -5
  14. package/src/card.mjs +39 -2
  15. package/src/catalog.mjs +6 -3
  16. package/src/chat.mjs +289 -89
  17. package/src/cli.mjs +359 -135
  18. package/src/cost.mjs +67 -8
  19. package/src/db.mjs +106 -3
  20. package/src/dream.mjs +445 -19
  21. package/src/editor.mjs +113 -11
  22. package/src/export.mjs +105 -7
  23. package/src/guard.mjs +57 -11
  24. package/src/guides.mjs +5 -4
  25. package/src/herdr.mjs +9 -4
  26. package/src/hooks.mjs +35 -19
  27. package/src/jobs.mjs +118 -39
  28. package/src/jobtools.mjs +6 -4
  29. package/src/keeper.mjs +77 -0
  30. package/src/local-server.mjs +9 -16
  31. package/src/lock.mjs +2 -1
  32. package/src/logs.mjs +165 -0
  33. package/src/loop.mjs +121 -44
  34. package/src/mcp.mjs +72 -16
  35. package/src/memory.mjs +142 -15
  36. package/src/model.mjs +41 -21
  37. package/src/paths.mjs +38 -0
  38. package/src/prime.mjs +19 -31
  39. package/src/projects.mjs +94 -12
  40. package/src/redact.mjs +10 -0
  41. package/src/render.mjs +2 -1
  42. package/src/route.mjs +39 -25
  43. package/src/sandbox.mjs +82 -3
  44. package/src/scan.mjs +35 -1
  45. package/src/scribe.mjs +10 -22
  46. package/src/sessions.mjs +49 -13
  47. package/src/setup.mjs +425 -76
  48. package/src/text.mjs +100 -1
  49. package/src/tools.mjs +258 -21
  50. package/src/tty.mjs +481 -105
  51. package/src/ui.mjs +1205 -276
  52. package/src/verify.mjs +17 -1
package/src/scan.mjs CHANGED
@@ -99,7 +99,7 @@ function recipe(makefile, target) {
99
99
  * project itself says what a command runs — a script, a recipe — that is its
100
100
  * `definition`, so a job that rewrites it can be told apart from one that does not.
101
101
  */
102
- export function projectCommands(root, pkg = readJson(root, 'package.json')) {
102
+ function projectCommands(root, pkg = readJson(root, 'package.json')) {
103
103
  const found = [];
104
104
  if (pkg?.scripts) {
105
105
  const pm = nodePackageManager(root);
@@ -188,6 +188,40 @@ function ci(root) {
188
188
  }
189
189
  }
190
190
 
191
+ /**
192
+ * Everything a scan reads, by its place in the repository: a file here changed, appeared or went away, and a fact may
193
+ * have too. The directories are in it for what is made or deleted in them — a README added, a CLAUDE.md removed.
194
+ */
195
+ /**
196
+ * The files and folders a scan reads. Not the project folder itself: its time moves with every swap file, .DS_Store and
197
+ * save-by-rename. A scanned file made or deleted is told by `presentOf` instead.
198
+ */
199
+ const READS = [
200
+ '.claude', join('.github', 'workflows'),
201
+ 'package.json', 'tsconfig.json', 'bun.lock', 'bun.lockb', 'pnpm-lock.yaml', 'yarn.lock', 'pnpm-workspace.yaml',
202
+ 'pyproject.toml', 'requirements.txt', 'uv.lock', 'poetry.lock', 'go.mod', 'Cargo.toml', 'Gemfile', 'pom.xml',
203
+ 'build.gradle', 'build.gradle.kts', 'Package.swift', 'Makefile', 'README.md', 'readme.md', 'README', 'README.rst',
204
+ 'AGENTS.md', 'CLAUDE.md', join('.claude', 'CLAUDE.md'),
205
+ ];
206
+
207
+ /** Which of the files and folders a scan reads are there, as one string to keep beside the scan and compare with later. */
208
+ export function presentOf(root) {
209
+ return READS.filter((name) => existsSync(join(root, name))).join('\n');
210
+ }
211
+
212
+ /** Whether anything a scan reads changed after `since` (an ISO time): a stat of each, never a read. */
213
+ export function changedSince(root, since) {
214
+ const at = Date.parse(since);
215
+ if (!Number.isFinite(at)) return true;
216
+ return READS.some((name) => {
217
+ try {
218
+ return statSync(join(root, name)).mtimeMs > at;
219
+ } catch {
220
+ return false;
221
+ }
222
+ });
223
+ }
224
+
191
225
  /** Facts in the order the project card should show them. A key with nothing to say is simply absent. */
192
226
  export function scan(root) {
193
227
  const pkg = readJson(root, 'package.json');
package/src/scribe.mjs CHANGED
@@ -3,11 +3,10 @@ import { appendFileSync, closeSync, openSync, readFileSync, rmSync, statSync, wr
3
3
  import { join } from 'node:path';
4
4
  import { applyOps } from './apply.mjs';
5
5
  import { resolveAnthropicCredential } from './auth.mjs';
6
- import { ago } from './card.mjs';
7
6
  import { MODELS, offLine, usableModels } from './catalog.mjs';
8
7
  import { getMeta, openDb, setMeta, tx } from './db.mjs';
9
- import { localServerStatus } from './local-server.mjs';
10
8
  import { callModel, failure, logRun } from './model.mjs';
9
+ import { appendLog } from './logs.mjs';
11
10
  import { paths, REPO_ROOT, SELF } from './paths.mjs';
12
11
  import { aliasesOf, listProjects } from './projects.mjs';
13
12
  import { line } from './render.mjs';
@@ -135,7 +134,7 @@ export async function withLock(name, fn) {
135
134
  }
136
135
  }
137
136
 
138
- export function projectEnum(db) {
137
+ function projectEnum(db) {
139
138
  return listProjects(db, { includeArchived: true }).map((p) => p.slug);
140
139
  }
141
140
 
@@ -173,6 +172,7 @@ export function opsSchema(db, ops) {
173
172
  ? branch('checkpoint', { project: { type: 'string', enum: slugs }, done: { type: 'string' }, next: { type: ['string', 'null'] } })
174
173
  : null,
175
174
  contradiction: branch('contradiction', { ids: { type: 'array', items: { type: 'integer' } }, note: { type: 'string' } }),
175
+ same: branch('same', { ids: { type: 'array', items: { type: 'integer' } }, note: { type: 'string' } }),
176
176
  procedure: branch('procedure', { scope: field.scope, title: { type: 'string' }, cue: { type: 'string' }, body: field.body }),
177
177
  };
178
178
  return {
@@ -243,11 +243,12 @@ const fallbackModel = (db) => usableModels(db)[0] ?? null;
243
243
 
244
244
  /** Shared by the writer and the consolidation pass: ask, validate, record what it cost. */
245
245
  export async function askAndApply(db, { kind, promptFile, bundle, ops, sessionId, now }) {
246
- let model = getMeta(db, `config.${kind}.model`) ?? CONFIG_DEFAULTS[`${kind}.model`];
246
+ // One setting for the whole memory pass, filing and tidying alike.
247
+ let model = getMeta(db, 'config.memory.model') ?? CONFIG_DEFAULTS['memory.model'];
247
248
  const system = readFileSync(join(REPO_ROOT, 'prompts', promptFile), 'utf8').trim();
248
249
  const schema = opsSchema(db, ops);
249
250
  // A writer set to a model the user has since turned off is not called: the refusal is the pass's failure, in the ledger like any other.
250
- const off = MODELS.includes(model) ? offLine(db, model, `sumo config ${kind}.model local`) : null;
251
+ const off = MODELS.includes(model) ? offLine(db, model, 'sumo config memory.model local') : null;
251
252
  let result = off ? failure(off) : await callModel(db, { system, prompt: bundle.prompt, schema, model, kind });
252
253
  // A local answer that failed (server down, bundle past its context, answer cut off) is one failed row, then one more try —
253
254
  // when a credential is there to pay for it and a model is on to take it.
@@ -268,21 +269,21 @@ export async function askAndApply(db, { kind, promptFile, bundle, ops, sessionId
268
269
  logRun(db, { kind, model, result: { ...result, ok: false }, note: error, now });
269
270
  return { ok: false, error, applied: [], dropped: [], usage: result.usage };
270
271
  }
271
- const outcome = applyOps(db, result.data.ops, { source: kind, turns: bundle.turns, sessionId, now });
272
+ const outcome = applyOps(db, result.data.ops, { source: kind, turns: bundle.turns, shown: bundle.shown, sessionId, now });
272
273
  logRun(db, { kind, model, result, note: `applied=${outcome.applied.length} dropped=${outcome.dropped.length}`, now });
273
- for (const reason of outcome.dropped) appendFileSync(join(paths().logs, 'scribe.log'), `${now} dropped — ${reason}\n`);
274
+ for (const reason of outcome.dropped) appendLog('scribe.log', `${now} dropped — ${reason}\n`);
274
275
  return { ok: true, error: null, ...outcome, usage: result.usage };
275
276
  }
276
277
 
277
278
  /** Whether the user turned the writer off: nothing gets filed, so nothing should wait for it to be. */
278
- export const writerOff = (db) => (getMeta(db, 'config.scribe.model') ?? CONFIG_DEFAULTS['scribe.model']) === 'off';
279
+ export const writerOff = (db) => (getMeta(db, 'config.memory.model') ?? CONFIG_DEFAULTS['memory.model']) === 'off';
279
280
 
280
281
  /**
281
282
  * Files what was said since the last run. Turns are marked done only after the
282
283
  * answer was applied, so a failed call costs nothing but a retry.
283
284
  */
284
285
  export async function runScribe(db, { now = new Date().toISOString() } = {}) {
285
- if (writerOff(db)) return { skipped: 'scribe.model is off' };
286
+ if (writerOff(db)) return { skipped: 'memory.model is off' };
286
287
 
287
288
  return withLock('scribe', async () => {
288
289
  const bundle = buildBundle(db);
@@ -306,19 +307,6 @@ export async function runScribe(db, { now = new Date().toISOString() } = {}) {
306
307
  });
307
308
  }
308
309
 
309
- export async function scribeStatus(db) {
310
- const failures = Number(getMeta(db, 'scribe.failures') ?? 0);
311
- const last = getMeta(db, 'scribe.last_run');
312
- const model = getMeta(db, 'config.scribe.model') ?? CONFIG_DEFAULTS['scribe.model'];
313
- return [
314
- `model: ${model}`,
315
- ...(model === 'local' ? [await localServerStatus(db, { file: getMeta(db, 'config.model.file') ?? CONFIG_DEFAULTS['model.file'] })] : []),
316
- `turns waiting: ${pendingTurns(db, 1000).length}`,
317
- `last run: ${last ? `${last} (${ago(last, new Date().toISOString())})` : 'never'}`,
318
- failures > 0 ? `failing: ${failures} in a row — ${getMeta(db, 'scribe.last_error')}` : 'healthy',
319
- ];
320
- }
321
-
322
310
  export function modelStats(db) {
323
311
  const rows = db
324
312
  .prepare(
package/src/sessions.mjs CHANGED
@@ -2,10 +2,10 @@ import { closeSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, re
2
2
  import { join } from 'node:path';
3
3
  import { ago } from './card.mjs';
4
4
  import { heldBy } from './lock.mjs';
5
- import { UsageError } from './memory.mjs';
5
+ import { Refusal, UsageError } from './memory.mjs';
6
6
  import { paths } from './paths.mjs';
7
7
  import { redact } from './redact.mjs';
8
- import { clip, head } from './text.mjs';
8
+ import { cjkTerms, clip, containing, head } from './text.mjs';
9
9
  import { readBackwards } from './transcript.mjs';
10
10
 
11
11
  const TURN_MAX_CHARS = 4000;
@@ -52,6 +52,28 @@ export function recordTurn(db, { sessionId, text, now }) {
52
52
  return Number(lastInsertRowid);
53
53
  }
54
54
 
55
+ /**
56
+ * A call that reached past the machine — a web search or fetch, an MCP server — written on its session, each tool once:
57
+ * what the conversation says after it may be what a page told it, so the memory pass holds what it would file from the
58
+ * conversation's replies for the user (arXiv 2503.03704: memory written from injected content is read later as trusted).
59
+ * A session not recorded yet gets nothing: a call comes after the turn that recorded it.
60
+ */
61
+ export function noteSessionOutside(db, sessionId, tool) {
62
+ if (!sessionId) return;
63
+ const name = String(tool).replace(/\s+/g, ' ');
64
+ const row = db.prepare('SELECT outside_read FROM sessions WHERE id = ?').get(sessionId);
65
+ if (!row || (row.outside_read ?? '').split('\n').includes(name)) return;
66
+ db.prepare('UPDATE sessions SET outside_read = ? WHERE id = ?').run(row.outside_read ? `${row.outside_read}\n${name}` : name, sessionId);
67
+ }
68
+
69
+ /** The tools any of these sessions read past the machine with, each once, in the order first seen. */
70
+ export function outsideReadsOf(db, sessionIds) {
71
+ const ids = [...new Set(sessionIds)].filter(Boolean);
72
+ if (ids.length === 0) return [];
73
+ const rows = db.prepare(`SELECT outside_read FROM sessions WHERE id IN (${ids.map(() => '?').join(', ')}) AND outside_read IS NOT NULL`).all(...ids);
74
+ return [...new Set(rows.flatMap((r) => r.outside_read.split('\n')))];
75
+ }
76
+
55
77
  export function endSession(db, id, now) {
56
78
  db.prepare('UPDATE sessions SET ended_at = ? WHERE id = ?').run(now, id);
57
79
  }
@@ -108,14 +130,27 @@ export function sessionsAwaitingDream(db, now, limit = 5, { includeOpen = false
108
130
  .all(includeOpen ? 1 : 0, cutoff, limit);
109
131
  }
110
132
 
111
- /** What the user actually typed, searched word for word. */
133
+ /**
134
+ * What the user actually typed, searched word for word: `match` is `ftsQuery`'s expression. A Chinese, Japanese or
135
+ * Korean word sits inside a run the index keeps as one word, so it is looked for in the text itself: what holds the most
136
+ * of those words, newest first, after what the index found.
137
+ */
112
138
  export function searchTurns(db, match, limit = 8) {
113
- return db
139
+ const found = db
114
140
  .prepare(
115
141
  `SELECT t.* FROM user_turns_fts JOIN user_turns t ON t.id = user_turns_fts.rowid
116
142
  WHERE user_turns_fts MATCH ? ORDER BY bm25(user_turns_fts), t.id DESC LIMIT ?`,
117
143
  )
118
144
  .all(match, limit);
145
+ const terms = cjkTerms(match);
146
+ if (terms.length === 0 || found.length >= limit) return found;
147
+ const holds = terms.map(() => `(text LIKE ? ESCAPE '\\')`);
148
+ const patterns = terms.map(containing);
149
+ const seen = new Set(found.map((t) => t.id));
150
+ const more = db
151
+ .prepare(`SELECT * FROM user_turns WHERE ${holds.join(' OR ')} ORDER BY ${holds.join(' + ')} DESC, id DESC LIMIT ?`)
152
+ .all(...patterns, ...patterns, limit + found.length);
153
+ return [...found, ...more.filter((t) => !seen.has(t.id))].slice(0, limit);
119
154
  }
120
155
 
121
156
  /**
@@ -162,8 +197,8 @@ const inK = (tokens) => `${Math.round(tokens / 1000)}k`;
162
197
  */
163
198
  export function contextNudge(band, focus) {
164
199
  const hint = `hint: focus on ${focus}; keep decisions and open job ids in a note; drop tool output and file contents.`;
165
- if (band === 'act') return `context: very large — start fresh now: note where you are (sumo job note; the end of the turn records "Left off"), then tell the user to type /new. ${hint}`;
166
- return `context: large — quality drops from here. Finish the piece in hand, then tell the user to type /new: the memory block brings the thread back. ${hint}`;
200
+ if (band === 'act') return `context: very large — start fresh now: note where you are (sumo job note; the end of the turn records "Left off"), then tell the user to type /handoff, which carries your hand-off into a fresh session, or /new. ${hint}`;
201
+ return `context: large — quality drops from here. Finish the piece in hand, then tell the user to type /handoff: a fresh session starts from your hand-off, and the memory block brings the thread back. ${hint}`;
167
202
  }
168
203
 
169
204
  /**
@@ -218,7 +253,7 @@ function keepBlock(block) {
218
253
  }
219
254
 
220
255
  /** The conversation as it is kept on disk: no pictures, no secrets, no cache markers (they are placed again when it is sent). */
221
- export function keepable(messages) {
256
+ function keepable(messages) {
222
257
  return messages.map((m) => ({ role: m.role, content: typeof m.content === 'string' ? redact(m.content).text : m.content.map(keepBlock) }));
223
258
  }
224
259
 
@@ -235,11 +270,12 @@ export function withoutThinking(messages) {
235
270
  }
236
271
 
237
272
  /** Writes the session's state whole, then moves it into place: a crash while writing leaves the last good one. */
238
- export function saveState({ id, messages, model, effort, routed, cwd, contextTokens, now }) {
273
+ export function saveState({ id, messages, model, effort, routed, cwd, contextTokens, now, pending = [] }) {
239
274
  mkdirSync(sessionsDir(), { recursive: true, mode: 0o700 });
240
275
  const file = stateFile(id);
241
276
  // The summary first, so a listing can read it without the messages behind it; the route's reason last, since it is prose of any length.
242
- const state = { version: 1, id, savedAt: now, contextTokens, model, effort, cwd, messages: keepable(messages), routed };
277
+ // `pending` is what jobs reported that the model has not read yet: it goes with the session, to be read when it is picked up again.
278
+ const state = { version: 1, id, savedAt: now, contextTokens, model, effort, cwd, messages: keepable(messages), routed, pending };
243
279
  writeFileSync(`${file}.tmp`, JSON.stringify(state), { mode: 0o600 });
244
280
  renameSync(`${file}.tmp`, file);
245
281
  return file;
@@ -252,9 +288,9 @@ export function loadState(id) {
252
288
  state = JSON.parse(readFileSync(stateFile(id), 'utf8'));
253
289
  } catch (cause) {
254
290
  if (cause.code === 'ENOENT') return null;
255
- throw new UsageError(`the saved session ${shortId(id)} cannot be read: ${cause.message}`);
291
+ throw new Refusal(`the saved session ${shortId(id)} cannot be read: ${cause.message}`);
256
292
  }
257
- if (state?.version !== 1 || !Array.isArray(state.messages)) throw new UsageError(`the saved session ${shortId(id)} is not one this version can resume`);
293
+ if (state?.version !== 1 || !Array.isArray(state.messages)) throw new Refusal(`the saved session ${shortId(id)} is not one this version can resume`);
258
294
  return state;
259
295
  }
260
296
 
@@ -320,12 +356,12 @@ export function savedSessions(db, { now, except = null } = {}) {
320
356
  export function findSaved(db, ref, options) {
321
357
  const all = savedSessions(db, options);
322
358
  if (ref === 'last') {
323
- if (all.length === 0) throw new UsageError('no saved session to resume');
359
+ if (all.length === 0) throw new Refusal('no saved session to resume');
324
360
  return all[0];
325
361
  }
326
362
  const hits = all.filter((s) => s.id.startsWith(ref));
327
363
  if (hits.length === 1) return hits[0];
328
- if (hits.length === 0) throw new UsageError(`no saved session starts with "${ref}"${all.length > 0 ? ` — one of: ${all.map((s) => shortId(s.id)).join(', ')}` : ''}`);
364
+ if (hits.length === 0) throw new Refusal(`no saved session starts with "${ref}"${all.length > 0 ? ` — one of: ${all.map((s) => shortId(s.id)).join(', ')}` : ''}`);
329
365
  throw new UsageError(`"${ref}" could be ${hits.map((s) => shortId(s.id)).join(' or ')} — give more of the id`);
330
366
  }
331
367