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
@@ -0,0 +1,371 @@
1
+ import { closeSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
2
+ import { join } from 'node:path';
3
+ import { ago } from './card.mjs';
4
+ import { heldBy } from './lock.mjs';
5
+ import { UsageError } from './memory.mjs';
6
+ import { paths } from './paths.mjs';
7
+ import { redact } from './redact.mjs';
8
+ import { clip, head } from './text.mjs';
9
+ import { readBackwards } from './transcript.mjs';
10
+
11
+ const TURN_MAX_CHARS = 4000;
12
+
13
+ /**
14
+ * Where a session starts costing quality. The numbers are absolute tokens, not
15
+ * a share of the window: what degrades an answer is how much context is in
16
+ * play, and a million-token window degrades at the same sizes a small one does.
17
+ * It is said early because every request pays for all of it again: a chat averages
18
+ * some 65k tokens a request, and it is most of what is spent.
19
+ */
20
+ const BANDS = [
21
+ { band: 'act', from: 150_000 },
22
+ { band: 'watch', from: 60_000 },
23
+ ];
24
+
25
+ /** Hooks can arrive in any order and a session can outlive a restart, so every write starts by making sure the row exists. */
26
+ export function ensureSession(db, { id, harness = 'claude', cwd = null, transcriptPath = null, now }) {
27
+ db.prepare(
28
+ `INSERT INTO sessions (id, harness, cwd, transcript_path, started_at) VALUES (?, ?, ?, ?, ?)
29
+ ON CONFLICT(id) DO UPDATE SET
30
+ cwd = COALESCE(excluded.cwd, cwd),
31
+ transcript_path = COALESCE(excluded.transcript_path, transcript_path),
32
+ ended_at = NULL`,
33
+ ).run(id, harness, cwd, transcriptPath, now);
34
+ }
35
+
36
+ /**
37
+ * Stores what the user typed, word for word — the ground truth every derived
38
+ * memory points back to. Returns the turn id, or null when there was nothing
39
+ * worth keeping (a slash command, a worker's brief, an empty line).
40
+ */
41
+ export function recordTurn(db, { sessionId, text, now }) {
42
+ const trimmed = text.trim();
43
+ // A command's name may carry a dash or a plugin prefix (`/code-review`, `/codex:rescue`); a path (`/usr/bin`) still has a slash after its first word.
44
+ if (!trimmed || /^\/[\w:-]+(\s|$)/.test(trimmed) || trimmed.startsWith('JOB:')) return null;
45
+
46
+ const cleaned = redact(trimmed);
47
+ const kept = cleaned.text.length > TURN_MAX_CHARS ? `${head(cleaned.text, TURN_MAX_CHARS)} …[cut]` : cleaned.text;
48
+ const { lastInsertRowid } = db
49
+ .prepare('INSERT INTO user_turns (session_id, ts, text, redacted) VALUES (?, ?, ?, ?)')
50
+ .run(sessionId, now, kept, cleaned.count > 0 ? 1 : 0);
51
+ db.prepare("UPDATE sessions SET last_turn_at = ?, dream_state = 'pending' WHERE id = ?").run(now, sessionId);
52
+ return Number(lastInsertRowid);
53
+ }
54
+
55
+ export function endSession(db, id, now) {
56
+ db.prepare('UPDATE sessions SET ended_at = ? WHERE id = ?').run(now, id);
57
+ }
58
+
59
+ export function pendingTurns(db, limit = 30) {
60
+ return db.prepare('SELECT * FROM user_turns WHERE scribed = 0 ORDER BY id LIMIT ?').all(limit);
61
+ }
62
+
63
+ export function markScribed(db, turnIds) {
64
+ if (turnIds.length === 0) return;
65
+ db.prepare(`UPDATE user_turns SET scribed = 1 WHERE id IN (${turnIds.map(() => '?').join(', ')})`).run(...turnIds);
66
+ }
67
+
68
+ export function injectedSlugs(db, sessionId) {
69
+ // The same table remembers which workflows and memories were shown; those keys ("workflow:m3", "recall:m7") contain a colon, which no project slug can.
70
+ return db.prepare(`SELECT slug FROM session_injections WHERE session_id = ? AND slug NOT LIKE '%:%' ORDER BY ts`).all(sessionId).map((r) => r.slug);
71
+ }
72
+
73
+ export function markInjected(db, sessionId, slug, now) {
74
+ db.prepare('INSERT OR REPLACE INTO session_injections (session_id, slug, ts) VALUES (?, ?, ?)').run(sessionId, slug, now);
75
+ }
76
+
77
+ /** After a compaction the cards are gone from context, so they have to be allowed back in. */
78
+ export function clearInjections(db, sessionId) {
79
+ db.prepare('DELETE FROM session_injections WHERE session_id = ?').run(sessionId);
80
+ }
81
+
82
+ /** The project this session is about right now: the one whose card went in most recently. */
83
+ export function currentProject(db, sessionId) {
84
+ return db.prepare(`SELECT slug FROM session_injections WHERE session_id = ? AND slug NOT LIKE '%:%' ORDER BY ts DESC LIMIT 1`).get(sessionId)?.slug ?? null;
85
+ }
86
+
87
+ export function addCheckpoint(db, { sessionId = null, project, done, next = null, now }) {
88
+ db.prepare('INSERT INTO checkpoints (session_id, project, done, next_step, ts) VALUES (?, ?, ?, ?, ?)').run(sessionId, project, done, next, now);
89
+ db.prepare('UPDATE projects SET last_touched_at = ? WHERE slug = ?').run(now, project);
90
+ }
91
+
92
+ /**
93
+ * Sessions the consolidation pass has not read yet. A session counts as over
94
+ * when it said so, or when it has been silent for two hours — a closed terminal
95
+ * or a crash never sends the goodbye. `includeOpen` is for a pass the user asked
96
+ * for by hand, which should not wait for anything.
97
+ */
98
+ export function sessionsAwaitingDream(db, now, limit = 5, { includeOpen = false } = {}) {
99
+ const cutoff = new Date(Date.parse(now) - 2 * 3_600_000).toISOString();
100
+ return db
101
+ .prepare(
102
+ `SELECT s.* FROM sessions s
103
+ WHERE s.dream_state = 'pending'
104
+ AND (? = 1 OR s.ended_at IS NOT NULL OR COALESCE(s.last_turn_at, s.started_at) < ?)
105
+ AND EXISTS (SELECT 1 FROM user_turns t WHERE t.session_id = s.id)
106
+ ORDER BY s.started_at LIMIT ?`,
107
+ )
108
+ .all(includeOpen ? 1 : 0, cutoff, limit);
109
+ }
110
+
111
+ /** What the user actually typed, searched word for word. */
112
+ export function searchTurns(db, match, limit = 8) {
113
+ return db
114
+ .prepare(
115
+ `SELECT t.* FROM user_turns_fts JOIN user_turns t ON t.id = user_turns_fts.rowid
116
+ WHERE user_turns_fts MATCH ? ORDER BY bm25(user_turns_fts), t.id DESC LIMIT ?`,
117
+ )
118
+ .all(match, limit);
119
+ }
120
+
121
+ /**
122
+ * How much context this session is carrying, from the last assistant turn the
123
+ * transcript recorded — everything the model was billed for reading, cache
124
+ * included. A transcript can be several megabytes, so a line is string-matched
125
+ * before it is parsed. Anything unreadable is null: a nudge that cannot be
126
+ * computed is simply not given, never an error in the middle of a turn.
127
+ */
128
+ export function contextUse(transcriptPath) {
129
+ if (!transcriptPath) return null;
130
+ // Read from the end, on every prompt: the size is in the last reply, and the file can be hundreds of megabytes.
131
+ return readBackwards(transcriptPath, (lines) => {
132
+ for (let i = lines.length - 1; i >= 0; i--) {
133
+ if (!lines[i].includes('"type":"assistant"')) continue;
134
+ let entry;
135
+ try {
136
+ entry = JSON.parse(lines[i]);
137
+ } catch {
138
+ return null; // A transcript that cannot be parsed answers nothing at all.
139
+ }
140
+ // An error Claude Code writes in the reply's place (a rate limit, a failed sign-in) bills nothing; the size is in the reply before it.
141
+ if (entry.isApiErrorMessage || entry.message?.model === '<synthetic>') continue;
142
+ const { message } = entry;
143
+ if (!message?.usage) return null;
144
+ const { input_tokens: input = 0, cache_read_input_tokens: read = 0, cache_creation_input_tokens: written = 0 } = message.usage;
145
+ return { tokens: input + read + written, model: message.model ?? null };
146
+ }
147
+ return undefined;
148
+ });
149
+ }
150
+
151
+ /** 'watch', 'act', or null while the session is still small. */
152
+ export function contextBand(tokens) {
153
+ return BANDS.find((b) => tokens >= b.from)?.band ?? null;
154
+ }
155
+
156
+ const inK = (tokens) => `${Math.round(tokens / 1000)}k`;
157
+
158
+ /**
159
+ * What the session is told when it crosses a band. One line, ending with the
160
+ * hint, so a `/compact` can be pasted exactly as it stands. No figure: a count
161
+ * of its own tokens is what makes a model cut its work short; the screen shows it.
162
+ */
163
+ export function contextNudge(band, focus) {
164
+ 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}`;
167
+ }
168
+
169
+ /**
170
+ * A task just ended: the cheapest moment there is to start a fresh session, if
171
+ * this one has grown enough to be worth it. Null when the newest session stored
172
+ * no transcript path — how big it is cannot be known, and nothing is guessed.
173
+ */
174
+ export function taskEndedNudge(db) {
175
+ const path = db.prepare(`SELECT transcript_path FROM sessions WHERE id NOT LIKE 'job:%' ORDER BY COALESCE(last_turn_at, started_at) DESC LIMIT 1`).get()?.transcript_path ?? null;
176
+ const use = contextUse(path);
177
+ if (!use || !contextBand(use.tokens)) return null;
178
+ return 'this session has grown large and the task just ended — a good moment for /new; the memory block brings the thread back.';
179
+ }
180
+
181
+ /**
182
+ * A chat session saved to be picked up again: the whole conversation as the model was sent it, written after every
183
+ * turn beside the session's log, so a closed terminal or a crash loses one turn at most. The API is stateless, so
184
+ * resuming is sending the same messages again; what it costs is one cold cache write.
185
+ */
186
+
187
+ const sessionsDir = () => join(paths().logs, 'sessions');
188
+ export const stateFile = (id) => join(sessionsDir(), `${id}.state.json`);
189
+ export const lockFile = (id) => join(sessionsDir(), `${id}.lock`);
190
+ /** A session id as it is shown and typed: the first eight characters, which no two sessions share in practice. */
191
+ export const shortId = (id) => id.slice(0, 8);
192
+ /** How long a saved session is kept to be resumed. */
193
+ const STATE_KEEP_MS = 30 * 24 * 3_600_000;
194
+ /** How much of a state file holds its summary: what comes before the messages. */
195
+ const SUMMARY_BYTES = 4096;
196
+ const NO_PICTURE = '[a picture was here; pictures are not kept when a session is saved]';
197
+ const TITLE_MAX = 60;
198
+
199
+ const redactValues = (value) => {
200
+ if (typeof value === 'string') return redact(value).text;
201
+ if (Array.isArray(value)) return value.map(redactValues);
202
+ if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, redactValues(v)]));
203
+ return value;
204
+ };
205
+
206
+ /**
207
+ * One block as it is kept: a picture becomes a line saying there was one; the words — the user's, the model's, a
208
+ * tool's input and what it printed — are redacted, since the user's were sent raw and no secret lands in a file. Ids,
209
+ * types, names and a thinking block's signature are left exactly as they are: the API matches on them.
210
+ */
211
+ function keepBlock(block) {
212
+ if (block.type === 'image') return { type: 'text', text: NO_PICTURE };
213
+ const { cache_control: _dropped, ...kept } = block;
214
+ if (typeof kept.text === 'string') kept.text = redact(kept.text).text;
215
+ if (kept.type === 'tool_result') kept.content = typeof kept.content === 'string' ? redact(kept.content).text : Array.isArray(kept.content) ? kept.content.map(keepBlock) : kept.content;
216
+ if (kept.type === 'tool_use') kept.input = redactValues(kept.input);
217
+ return kept;
218
+ }
219
+
220
+ /** 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) {
222
+ return messages.map((m) => ({ role: m.role, content: typeof m.content === 'string' ? redact(m.content).text : m.content.map(keepBlock) }));
223
+ }
224
+
225
+ /**
226
+ * The conversation without the model's thinking blocks: what a resumed session sends first. A block's signature is bound
227
+ * to the exact history it was made in — the system prompt, the tools, every message before it — and a saved session has
228
+ * had its secrets redacted and its pictures taken out, while AGENTS.md and the MCP servers may have changed since; on the
229
+ * current models such a block is refused, not ignored. The text and the calls stay; a reply that was only thinking goes.
230
+ */
231
+ export function withoutThinking(messages) {
232
+ return messages
233
+ .map((m) => (m.role === 'assistant' && Array.isArray(m.content) ? { ...m, content: m.content.filter((b) => b.type !== 'thinking' && b.type !== 'redacted_thinking') } : m))
234
+ .filter((m) => !(Array.isArray(m.content) && m.content.length === 0));
235
+ }
236
+
237
+ /** 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 }) {
239
+ mkdirSync(sessionsDir(), { recursive: true, mode: 0o700 });
240
+ const file = stateFile(id);
241
+ // 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 };
243
+ writeFileSync(`${file}.tmp`, JSON.stringify(state), { mode: 0o600 });
244
+ renameSync(`${file}.tmp`, file);
245
+ return file;
246
+ }
247
+
248
+ /** A saved session, whole; null when there is none by this id. One that cannot be read or is of another shape is said. */
249
+ export function loadState(id) {
250
+ let state;
251
+ try {
252
+ state = JSON.parse(readFileSync(stateFile(id), 'utf8'));
253
+ } catch (cause) {
254
+ if (cause.code === 'ENOENT') return null;
255
+ throw new UsageError(`the saved session ${shortId(id)} cannot be read: ${cause.message}`);
256
+ }
257
+ if (state?.version !== 1 || !Array.isArray(state.messages)) throw new UsageError(`the saved session ${shortId(id)} is not one this version can resume`);
258
+ return state;
259
+ }
260
+
261
+ /** What a state file says about itself, read from its head: everything before the messages. Null when it cannot be read. */
262
+ function summaryOf(file) {
263
+ try {
264
+ const fd = openSync(file, 'r');
265
+ let text;
266
+ try {
267
+ const buffer = Buffer.alloc(SUMMARY_BYTES);
268
+ text = buffer.toString('utf8', 0, readSync(fd, buffer, 0, SUMMARY_BYTES, 0));
269
+ } finally {
270
+ closeSync(fd);
271
+ }
272
+ const cut = text.indexOf(',"messages":');
273
+ return JSON.parse(cut === -1 ? readFileSync(file, 'utf8') : `${text.slice(0, cut)}}`);
274
+ } catch {
275
+ return null;
276
+ }
277
+ }
278
+
279
+ /**
280
+ * The sessions that can be picked up, newest first — every one still on disk, the heavy ones marked. `except` is the
281
+ * session asking, which cannot resume itself.
282
+ */
283
+ export function savedSessions(db, { now, except = null } = {}) {
284
+ let names;
285
+ try {
286
+ names = readdirSync(sessionsDir());
287
+ } catch (cause) {
288
+ if (cause.code === 'ENOENT') return [];
289
+ throw cause;
290
+ }
291
+ const firstTurn = db.prepare('SELECT text FROM user_turns WHERE session_id = ? ORDER BY id LIMIT 1');
292
+ const turns = db.prepare('SELECT COUNT(*) AS n FROM user_turns WHERE session_id = ?');
293
+ const row = db.prepare('SELECT last_turn_at FROM sessions WHERE id = ?');
294
+ return names
295
+ .filter((name) => name.endsWith('.state.json'))
296
+ .map((name) => name.slice(0, -'.state.json'.length))
297
+ .filter((id) => id !== except)
298
+ .map((id) => {
299
+ const summary = summaryOf(stateFile(id));
300
+ if (!summary?.savedAt) return null;
301
+ const tokens = summary.contextTokens ?? 0;
302
+ return {
303
+ id,
304
+ savedAt: summary.savedAt,
305
+ lastTurnAt: row.get(id)?.last_turn_at ?? summary.savedAt,
306
+ cwd: summary.cwd ?? null,
307
+ project: currentProject(db, id),
308
+ title: firstTurn.get(id)?.text ?? '',
309
+ turns: turns.get(id).n,
310
+ tokens,
311
+ heavy: contextBand(tokens) === 'act',
312
+ openElsewhere: heldBy(lockFile(id)),
313
+ };
314
+ })
315
+ .filter(Boolean)
316
+ .sort((a, b) => (a.savedAt < b.savedAt ? 1 : a.savedAt > b.savedAt ? -1 : 0));
317
+ }
318
+
319
+ /** The saved session `ref` names: `last` for the newest, otherwise the one id that starts with it. Anything else is said. */
320
+ export function findSaved(db, ref, options) {
321
+ const all = savedSessions(db, options);
322
+ if (ref === 'last') {
323
+ if (all.length === 0) throw new UsageError('no saved session to resume');
324
+ return all[0];
325
+ }
326
+ const hits = all.filter((s) => s.id.startsWith(ref));
327
+ 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(', ')}` : ''}`);
329
+ throw new UsageError(`"${ref}" could be ${hits.map((s) => shortId(s.id)).join(' or ')} — give more of the id`);
330
+ }
331
+
332
+ /** How a saved session is described, without its id: when, what about, how big, and what stands in the way of picking it up. */
333
+ export function describeSaved(s, now) {
334
+ const title = clip(s.title, TITLE_MAX);
335
+ const parts = [ago(s.lastTurnAt, now), s.project ?? 'no project', title ? `“${title}”` : '(nothing said)', `${s.turns} turn${s.turns === 1 ? '' : 's'}`, `${inK(s.tokens)} tokens`];
336
+ if (s.heavy) parts.push('heavy: the gauge said to start fresh');
337
+ if (s.openElsewhere) parts.push(`open in another terminal (process ${s.openElsewhere})`);
338
+ return parts.join(' · ');
339
+ }
340
+
341
+ export const sessionLine = (s, now) => `${shortId(s.id)} · ${describeSaved(s, now)}`;
342
+
343
+ /**
344
+ * Saved sessions older than the keep are let go — a save a crash cut short with them — and so is a lock a session
345
+ * died holding; the logs beside them stay, the dream pass reads those. Returns how many went.
346
+ */
347
+ export function pruneStates(now, keepMs = STATE_KEEP_MS) {
348
+ let names;
349
+ try {
350
+ names = readdirSync(sessionsDir());
351
+ } catch (cause) {
352
+ if (cause.code === 'ENOENT') return 0;
353
+ throw cause;
354
+ }
355
+ let gone = 0;
356
+ for (const name of names) {
357
+ const file = join(sessionsDir(), name);
358
+ try {
359
+ if (name.endsWith('.lock')) {
360
+ if (heldBy(file)) continue;
361
+ } else if (!/\.state\.json(?:\.tmp)?$/.test(name) || Date.parse(now) - statSync(file).mtimeMs <= keepMs) {
362
+ continue;
363
+ }
364
+ unlinkSync(file);
365
+ gone++;
366
+ } catch (cause) {
367
+ if (cause.code !== 'ENOENT') throw cause;
368
+ }
369
+ }
370
+ return gone;
371
+ }