sumo-agents 0.0.0-stage → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (66) hide show
  1. package/AGENTS.md +38 -0
  2. package/LICENSE +21 -0
  3. package/README.md +111 -2
  4. package/bin/sumo.mjs +33 -0
  5. package/guides/delegation.md +33 -0
  6. package/guides/feature.md +14 -0
  7. package/guides/fix.md +14 -0
  8. package/guides/memory.md +23 -0
  9. package/guides/projects.md +27 -0
  10. package/guides/review.md +16 -0
  11. package/guides/workflows.md +26 -0
  12. package/logo.txt +19 -0
  13. package/package.json +42 -4
  14. package/prompts/agent.md +7 -0
  15. package/prompts/dream.md +13 -0
  16. package/prompts/scribe.md +21 -0
  17. package/spinner.txt +90 -0
  18. package/src/advisor.mjs +59 -0
  19. package/src/apply.mjs +368 -0
  20. package/src/auth.mjs +80 -0
  21. package/src/card.mjs +72 -0
  22. package/src/catalog.mjs +167 -0
  23. package/src/chat.mjs +1162 -0
  24. package/src/cli.mjs +815 -0
  25. package/src/cost.mjs +128 -0
  26. package/src/db.mjs +384 -0
  27. package/src/dream.mjs +97 -0
  28. package/src/editor.mjs +198 -0
  29. package/src/export.mjs +132 -0
  30. package/src/guard.mjs +121 -0
  31. package/src/guides.mjs +86 -0
  32. package/src/herdr.mjs +117 -0
  33. package/src/hooks.mjs +270 -0
  34. package/src/images.mjs +89 -0
  35. package/src/jobs.mjs +1184 -0
  36. package/src/jobtools.mjs +82 -0
  37. package/src/local-server.mjs +169 -0
  38. package/src/lock.mjs +45 -0
  39. package/src/loop.mjs +838 -0
  40. package/src/mcp.mjs +604 -0
  41. package/src/memory.mjs +400 -0
  42. package/src/model.mjs +270 -0
  43. package/src/page.html +304 -0
  44. package/src/page.mjs +135 -0
  45. package/src/paths.mjs +33 -0
  46. package/src/prime.mjs +177 -0
  47. package/src/projects.mjs +232 -0
  48. package/src/recall.mjs +45 -0
  49. package/src/redact.mjs +173 -0
  50. package/src/render.mjs +45 -0
  51. package/src/route.mjs +287 -0
  52. package/src/sandbox.mjs +173 -0
  53. package/src/scan.mjs +204 -0
  54. package/src/scribe.mjs +349 -0
  55. package/src/sessions.mjs +371 -0
  56. package/src/setup.mjs +528 -0
  57. package/src/sqlite.mjs +66 -0
  58. package/src/text.mjs +97 -0
  59. package/src/tools.mjs +987 -0
  60. package/src/transcript.mjs +106 -0
  61. package/src/tty.mjs +529 -0
  62. package/src/ui.mjs +1363 -0
  63. package/src/verify.mjs +369 -0
  64. package/src/web.mjs +49 -0
  65. package/src/workflows.mjs +270 -0
  66. package/src/worktree.mjs +128 -0
package/src/editor.mjs ADDED
@@ -0,0 +1,198 @@
1
+ /**
2
+ * The input box of the chat, as plain state: the text, where the cursor is,
3
+ * what was sent before, and which command the menu has picked. Every key is a
4
+ * function from one state to the next, so the screen only has to draw it.
5
+ */
6
+
7
+ /** An empty box. `history` is what Up recalls, oldest first; `at` is the entry shown, one past the end for the text being written. */
8
+ export const editor = (history = []) => ({ text: '', cursor: 0, history, at: history.length, draft: '', pick: 0 });
9
+
10
+ /**
11
+ * The menu for what is being typed: the commands a half-typed slash could mean, or, once a command's
12
+ * arguments have started, what its `choices(given)` offers for the one being typed — nothing for a
13
+ * command that offers none. Each entry says what to show (`label`), its hint, and the whole text
14
+ * picking it leaves in the box (`complete`).
15
+ */
16
+ export function menuFor(text, commands) {
17
+ if (/^\/\w*$/.test(text)) return commands.filter((c) => c.name.startsWith(text.slice(1))).map((c) => ({ name: c.name, label: `/${c.name}`, hint: c.hint, complete: `/${c.name} ` }));
18
+ const m = /^\/(\w+)\s+([^\n]*)$/.exec(text);
19
+ const command = m && commands.find((c) => c.name === m[1] && c.choices);
20
+ if (!command) return [];
21
+ const given = m[2].split(/\s+/).filter(Boolean);
22
+ const typing = /\s$/.test(m[2]) || m[2] === '' ? '' : given.pop();
23
+ const head = `/${command.name} ${given.map((w) => `${w} `).join('')}`;
24
+ // A choice is a word, or a word with a hint beside it (`{ name, hint }`).
25
+ return command
26
+ .choices(given)
27
+ .map((choice) => (typeof choice === 'string' ? { name: choice, hint: '' } : choice))
28
+ .filter((choice) => choice.name.startsWith(typing))
29
+ .map((choice) => ({ name: choice.name, label: choice.name, hint: choice.hint, complete: `${head}${choice.name} ` }));
30
+ }
31
+
32
+ /**
33
+ * The `@word` the cursor stands at the end of — a file being named: where it starts, and what has been typed of it.
34
+ * Null when there is none: the `@` must begin the text or follow a space, so an address or a decorator is not one.
35
+ */
36
+ export function mentionAt({ text, cursor }) {
37
+ const m = /(^|\s)@([\w./~-]*)$/.exec(text.slice(0, cursor));
38
+ return m ? { from: m.index + m[1].length, query: m[2] } : null;
39
+ }
40
+
41
+ /** The files a few typed characters could mean, best first: a name that starts with them, a path that does, then either holding them; the shorter path first. */
42
+ export function matchFiles(list, query, max = 8) {
43
+ const q = query.toLowerCase();
44
+ const found = [];
45
+ for (const path of list) {
46
+ const p = path.toLowerCase();
47
+ const name = p.slice(p.lastIndexOf('/') + 1);
48
+ const rank = name.startsWith(q) ? 0 : p.startsWith(q) ? 1 : name.includes(q) ? 2 : p.includes(q) ? 3 : -1;
49
+ if (rank !== -1) found.push([rank, path]);
50
+ }
51
+ return found.sort((a, b) => a[0] - b[0] || a[1].length - b[1].length || (a[1] < b[1] ? -1 : 1)).slice(0, max).map(([, path]) => path);
52
+ }
53
+
54
+ /**
55
+ * The menu for the text being written: the slash menu, or — given `files(query, from)`, which answers with the paths a
56
+ * mention could mean — the files for the `@word` at the cursor; picking one leaves its path where the mention was. A
57
+ * recalled entry has none, so the arrows keep walking history; nor has a text whose menu Esc shut (`shut`), until it changes.
58
+ */
59
+ export function menuOf(state, commands, files = null) {
60
+ if (state.at !== state.history.length || state.shut === state.text) return [];
61
+ const menu = menuFor(state.text, commands);
62
+ const at = menu.length === 0 && files ? mentionAt(state) : null;
63
+ if (!at) return menu;
64
+ return files(at.query, at.from).map((path) => ({ name: path, label: path, hint: '', file: true, complete: `${state.text.slice(0, at.from)}${path} ${state.text.slice(state.cursor)}`, cursor: at.from + path.length + 1 }));
65
+ }
66
+
67
+ const GRAPHEMES = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
68
+ /** The character before the cursor, whole: an emoji is several code units and one keystroke. */
69
+ function before({ text, cursor }) {
70
+ let last = '';
71
+ for (const { segment } of GRAPHEMES.segment(text.slice(lineStart({ text, cursor }), cursor))) last = segment;
72
+ return last || text.slice(cursor - 1, cursor);
73
+ }
74
+ /** The character the cursor is on; empty at the end of the text. */
75
+ export const under = ({ text, cursor }) => GRAPHEMES.segment(text.slice(cursor))[Symbol.iterator]().next().value?.segment ?? '';
76
+ /** Where the word before the cursor starts, the spaces between them passed over. Walked back from the cursor: a pattern for it is tried from every place in the text, and a long paste is one long word. */
77
+ function wordLeft({ text, cursor }) {
78
+ let at = cursor;
79
+ while (at > 0 && /\s/.test(text[at - 1])) at--;
80
+ while (at > 0 && /\S/.test(text[at - 1])) at--;
81
+ return at;
82
+ }
83
+ const wordRight = ({ text, cursor }) => cursor + /^\s*\S*/.exec(text.slice(cursor))[0].length;
84
+
85
+ const edit = (state, text, cursor) => ({ ...state, text, cursor, pick: 0 });
86
+ const lineStart = ({ text, cursor }) => (cursor === 0 ? 0 : text.lastIndexOf('\n', cursor - 1) + 1);
87
+ const lineEnd = ({ text, cursor }) => (text.indexOf('\n', cursor) === -1 ? text.length : text.indexOf('\n', cursor));
88
+ const insert = (state, chunk) => edit(state, state.text.slice(0, state.cursor) + chunk + state.text.slice(state.cursor), state.cursor + chunk.length);
89
+ const cut = (state, from, to) => edit(state, state.text.slice(0, from) + state.text.slice(to), from);
90
+
91
+ /** Pasted text goes in whole, its line ends made plain; a newline in it is never Enter. */
92
+ export const paste = (state, text) => insert(state, text.replace(/\r\n?/g, '\n'));
93
+
94
+ const BURST_KEYS = { '\r': ['\r', { return: true }], '\t': ['', { tab: true }], '\x7f': ['', { backspace: true }] };
95
+ /** A control character is Ctrl and a letter: 3 is Ctrl-C. */
96
+ const burstKey = (ch) => BURST_KEYS[ch] ?? (ch < ' ' ? [String.fromCharCode(ch.charCodeAt(0) + 96), { ctrl: true }] : [ch, {}]);
97
+
98
+ /**
99
+ * Keys typed faster than the screen reads them arrive as one string. This
100
+ * gives them back one at a time, so an Enter in the middle is still Enter.
101
+ * Pasted text does not come this way: the terminal marks it, and it goes to `paste`.
102
+ */
103
+ export function keysOf(input, key) {
104
+ if (input.length < 2 || key.ctrl || key.meta) return [[input, key]];
105
+ return [...input].map(burstKey);
106
+ }
107
+
108
+ function recall(state, at) {
109
+ const draft = state.at === state.history.length ? state.text : state.draft;
110
+ const text = at === state.history.length ? draft : state.history[at];
111
+ return { ...state, at, draft, text, cursor: text.length, pick: 0 };
112
+ }
113
+
114
+ /** Up or down: through the menu when it is open, between the lines of the text, and past its first or last line into history. */
115
+ function vertical(state, step, menu) {
116
+ if (menu.length > 0) return { ...state, pick: (state.pick + step + menu.length) % menu.length };
117
+ const start = lineStart(state);
118
+ let column = 0;
119
+ for (const _ of GRAPHEMES.segment(state.text.slice(start, state.cursor))) column++;
120
+ if (step < 0) {
121
+ if (start === 0) return state.at > 0 ? recall(state, state.at - 1) : state;
122
+ const above = lineStart({ text: state.text, cursor: start - 1 });
123
+ return { ...state, cursor: cursorOnLine(state.text, above, start - 1, column) };
124
+ }
125
+ const end = lineEnd(state);
126
+ if (end === state.text.length) return state.at < state.history.length ? recall(state, state.at + 1) : state;
127
+ const below = lineEnd({ text: state.text, cursor: end + 1 });
128
+ return { ...state, cursor: cursorOnLine(state.text, end + 1, below, column) };
129
+ }
130
+
131
+ function cursorOnLine(text, start, end, column) {
132
+ let cursor = start;
133
+ for (const { segment } of GRAPHEMES.segment(text.slice(start, end))) {
134
+ if (column-- === 0) break;
135
+ cursor += segment.length;
136
+ }
137
+ return cursor;
138
+ }
139
+
140
+ function send(state) {
141
+ const text = state.text.trim();
142
+ if (!text) return { state: edit(state, '', 0) };
143
+ const history = state.history.at(-1) === text ? state.history : [...state.history, text];
144
+ return { state: editor(history), submit: text };
145
+ }
146
+
147
+ /**
148
+ * One key. `input` and `key` are what Ink's useInput hands over; `commands`
149
+ * is the slash menu's list. Returns the next state, and `submit` when the key
150
+ * sent the text.
151
+ */
152
+ export function press(state, input, key, commands = [], files = null) {
153
+ const menu = menuOf(state, commands, files);
154
+ const { text, cursor } = state;
155
+ const word = key.meta || key.ctrl;
156
+
157
+ if (key.return) {
158
+ if (text[cursor - 1] === '\\') return { state: insert(cut(state, cursor - 1, cursor), '\n') };
159
+ if (key.shift || key.meta) return { state: insert(state, '\n') };
160
+ const chosen = menu[state.pick];
161
+ if (chosen && text !== chosen.complete.trimEnd()) return { state: edit(state, chosen.complete, chosen.cursor ?? chosen.complete.length) };
162
+ return send(state);
163
+ }
164
+ if (key.tab) {
165
+ const chosen = menu[state.pick];
166
+ return { state: chosen ? edit(state, chosen.complete, chosen.cursor ?? chosen.complete.length) : state };
167
+ }
168
+ if (key.upArrow) return { state: vertical(state, -1, menu) };
169
+ if (key.downArrow) return { state: vertical(state, 1, menu) };
170
+ if (key.leftArrow) return { state: { ...state, cursor: word ? wordLeft(state) : cursor - before(state).length } };
171
+ if (key.rightArrow) return { state: { ...state, cursor: word ? wordRight(state) : cursor + under(state).length } };
172
+ if (key.home) return { state: { ...state, cursor: lineStart(state) } };
173
+ if (key.end) return { state: { ...state, cursor: lineEnd(state) } };
174
+ if (key.backspace) return { state: cut(state, key.meta ? wordLeft(state) : cursor - before(state).length, cursor) };
175
+ if (key.delete) return { state: cut(state, cursor, cursor + under(state).length) };
176
+
177
+ if (key.ctrl) {
178
+ if (input === 'j') return { state: insert(state, '\n') };
179
+ if (input === 'a') return { state: { ...state, cursor: lineStart(state) } };
180
+ if (input === 'e') return { state: { ...state, cursor: lineEnd(state) } };
181
+ if (input === 'u') {
182
+ // At the start of a line nothing of it is before the cursor: the line above goes instead, so pressing it again clears a box of many lines.
183
+ const start = lineStart(state);
184
+ return { state: cut(state, start === cursor && cursor > 0 ? lineStart({ text: state.text, cursor: cursor - 1 }) : start, cursor) };
185
+ }
186
+ if (input === 'k') return { state: cut(state, cursor, lineEnd(state)) };
187
+ if (input === 'w') return { state: cut(state, wordLeft(state), cursor) };
188
+ if (input === 'd') return { state: cut(state, cursor, cursor + under(state).length) };
189
+ return { state };
190
+ }
191
+ if (key.meta) {
192
+ if (input === 'b') return { state: { ...state, cursor: wordLeft(state) } };
193
+ if (input === 'f') return { state: { ...state, cursor: wordRight(state) } };
194
+ return { state };
195
+ }
196
+ if (!input) return { state };
197
+ return { state: insert(state, input) };
198
+ }
package/src/export.mjs ADDED
@@ -0,0 +1,132 @@
1
+ import { chmodSync, existsSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
2
+ import { join } from 'node:path';
3
+ import { getMeta, setMeta } from './db.mjs';
4
+ import { paths } from './paths.mjs';
5
+ import { DatabaseSync } from './sqlite.mjs';
6
+
7
+ const KEEP_BACKUPS = 5;
8
+ export const SECTIONS = [
9
+ ['preference', 'Preferences'],
10
+ ['decision', 'Decisions'],
11
+ ['fact', 'Facts'],
12
+ ['gotcha', 'Gotchas'],
13
+ ['procedure', 'Workflows'],
14
+ ];
15
+
16
+ /**
17
+ * The view for a person: grouped, titled, dated. Never loaded by an agent —
18
+ * agents get the one-line form in render.mjs.
19
+ */
20
+ export function exportMarkdown(db, now = new Date().toISOString()) {
21
+ const projects = new Map(db.prepare('SELECT slug, name, path FROM projects').all().map((p) => [`project:${p.slug}`, p]));
22
+ const rows = db.prepare(`SELECT * FROM memories WHERE state IN ('active', 'unconfirmed') ORDER BY id`).all();
23
+ const machine = getMeta(db, 'machine');
24
+ const out = [`# Memory${machine ? ` — ${machine}` : ''} — ${now.slice(0, 10)}`, ''];
25
+
26
+ const scopes = ['global', ...[...new Set(rows.map((r) => r.scope))].filter((s) => s !== 'global').sort()];
27
+ for (const scope of scopes) {
28
+ const active = rows.filter((r) => r.scope === scope && r.state === 'active');
29
+ if (active.length === 0) continue;
30
+ const project = projects.get(scope);
31
+ out.push(scope === 'global' ? '## Global' : `## Project: ${project?.name ?? scope} (${project?.path ?? 'path unknown'})`, '');
32
+ for (const [type, heading] of SECTIONS) {
33
+ const group = active.filter((r) => r.type === type);
34
+ if (group.length === 0) continue;
35
+ out.push(`### ${heading}`, '');
36
+ for (const m of group) out.push(...entry(m));
37
+ out.push('');
38
+ }
39
+ }
40
+
41
+ const unconfirmed = rows.filter((r) => r.state === 'unconfirmed');
42
+ if (unconfirmed.length > 0) {
43
+ out.push('## Waiting for your yes/no', '');
44
+ for (const m of unconfirmed) out.push(...entry(m));
45
+ out.push('');
46
+ }
47
+ if (rows.length === 0) out.push('Nothing remembered yet.', '');
48
+ return out.join('\n');
49
+ }
50
+
51
+ function entry(m) {
52
+ const meta = `m${m.id} · ${m.provenance} · ${m.valid_from.slice(0, 10)}${m.pinned ? ' · pinned' : ''}`;
53
+ if (m.type !== 'procedure') return [`- ${m.body} _(${meta})_`];
54
+ const body = m.body.split('\n').map((l) => ` ${l}`);
55
+ return [`- **${m.title}**${m.cue ? ` — when: "${m.cue}"` : ''}${m.gate ? ` — gates: \`${m.gate}\`` : ''} _(${meta})_`, ...body];
56
+ }
57
+
58
+ /** Every row of every table the user's knowledge lives in, for moving or inspecting the store. */
59
+ export function exportJson(db) {
60
+ const all = (table) => db.prepare(`SELECT * FROM ${table}`).all();
61
+ return {
62
+ exported_at: new Date().toISOString(),
63
+ machine: getMeta(db, 'machine'),
64
+ projects: all('projects'),
65
+ project_aliases: all('project_aliases'),
66
+ memories: all('memories'),
67
+ };
68
+ }
69
+
70
+ /**
71
+ * A consistent snapshot while other sessions keep writing. The data has no git
72
+ * history by design, so this is the only undo there is.
73
+ */
74
+ export function backup(db, now = new Date()) {
75
+ const dir = paths().backups;
76
+ mkdirSync(dir, { recursive: true, mode: 0o700 });
77
+ const stamp = now.toISOString().replace(/[:.]/g, '-');
78
+ const file = join(dir, `memory-${stamp}.db`);
79
+ db.prepare('VACUUM INTO ?').run(file);
80
+ chmodSync(file, 0o600);
81
+ setMeta(db, 'last_backup', now.toISOString());
82
+ setMeta(db, 'backup.failed', '');
83
+
84
+ const old = readdirSync(dir)
85
+ .filter((f) => /^memory-.*\.db$/.test(f))
86
+ .sort()
87
+ .slice(0, -KEEP_BACKUPS);
88
+ for (const f of old) rmSync(join(dir, f), { force: true });
89
+ return { file, pruned: old.length };
90
+ }
91
+
92
+ /**
93
+ * A purge reaches the backups too: "erased, not recoverable" must hold for every copy this machine keeps. Each backup
94
+ * loses the memory and the sentence it came from, and is rewritten so the pages that held them are gone.
95
+ * Returns how many were cleaned, and the ones that could not be — said, never hidden.
96
+ */
97
+ export function purgeFromBackups({ id, body, created_at: createdAt, source_turn: sourceTurn }) {
98
+ const dir = paths().backups;
99
+ const files = existsSync(dir) ? readdirSync(dir).filter((f) => /^memory-.*\.db$/.test(f)) : [];
100
+ const failed = [];
101
+ let cleaned = 0;
102
+ for (const f of files) {
103
+ let db = null;
104
+ try {
105
+ db = new DatabaseSync(join(dir, f));
106
+ db.exec('PRAGMA secure_delete = ON;');
107
+ // The same memory, not just the same number: a backup from after a restore may hold another one under this id.
108
+ const row = db.prepare('SELECT source_turn FROM memories WHERE id = ? AND body = ? AND created_at = ?').get(id, body, createdAt);
109
+ if (row) {
110
+ // All of it or none: a backup this cannot clean whole is left as it was, and named.
111
+ db.exec('BEGIN');
112
+ try {
113
+ db.prepare('DELETE FROM memories WHERE id = ?').run(id);
114
+ if (sourceTurn !== null) db.prepare('DELETE FROM user_turns WHERE id = ?').run(sourceTurn);
115
+ // A deleted row's words stay in the full-text index's pages until it is rebuilt; VACUUM keeps those pages.
116
+ db.exec(`INSERT INTO memories_fts(memories_fts) VALUES ('rebuild'); INSERT INTO user_turns_fts(user_turns_fts) VALUES ('rebuild');`);
117
+ db.exec('COMMIT');
118
+ } catch (cause) {
119
+ db.exec('ROLLBACK');
120
+ throw cause;
121
+ }
122
+ db.exec('VACUUM');
123
+ cleaned++;
124
+ }
125
+ } catch {
126
+ failed.push(join(dir, f));
127
+ } finally {
128
+ db?.close();
129
+ }
130
+ }
131
+ return { cleaned, failed };
132
+ }
package/src/guard.mjs ADDED
@@ -0,0 +1,121 @@
1
+ import { homedir } from 'node:os';
2
+
3
+ /**
4
+ * The guard: a shell command that would wipe a tree, throw away history or
5
+ * empty a database, and any way of reading a secret file, are refused before
6
+ * they run. No memory is consulted and no database is opened — the check is
7
+ * a handful of patterns over the command or the path, and nothing else.
8
+ *
9
+ * It is a refusal, never an argument: the reason says what was matched and
10
+ * that the user can run the command themselves. What it does not cover is as
11
+ * deliberate as what it does — a force-push is an accepted way of cleaning up
12
+ * history here, and `rm -rf node_modules` is Tuesday.
13
+ */
14
+
15
+ /**
16
+ * A file whose contents are a secret: reading it is refused, and a change that adds one is never DONE. A glob (`.env*`) names them too.
17
+ * Any case: the disk a Mac ships with reads `.ENV` as `.env`. A redirect (`<.env`) is a reading too.
18
+ */
19
+ const SECRET_FILE =
20
+ /(^|[\s/'"=<])(\.env[*?]*(\.(?!example\b|sample\b|template\b)[\w*?-]+)?|\.netrc|\.git-credentials|\.aws\/credentials|\.ssh\/(?!known_hosts\b|config\b|authorized_keys\b)[\w.-]+(?<!\.pub)|id_(rsa|dsa|ecdsa|ed25519)(?!\.pub)|[\w.-]+\.(pem|key|p12|pfx))(?=$|[\s'"|;&)])/i;
21
+
22
+ /** Anything that would put a file's contents in front of the model, `$(< file)` among them. `source .env` is not on it: that sets variables without showing them. */
23
+ const PRINTS = /(^|[\s;&|($`])(cat|head|tail|less|more|bat|grep|rg|egrep|fgrep|sed|awk|cut|strings|xxd|hexdump|od|base64|nl|tac|view|vim?|nano|code|open|pbcopy|jq|yq)\s|\$\(\s*</;
24
+
25
+ /** Where one simple command ends and the next begins: a separator, a pipe, a new line, a subshell or a substitution. */
26
+ const SEPARATORS = /[;&|\n()`]|\$\(/;
27
+
28
+ /** A secret file bound to a name instead of read: `f=.env`, `for f in .env .env.local`. What later prints `$f` is a reading of it. */
29
+ const BINDS = /(^|[\s;&|(`])(?:\w+=|for\s+\w+\s+in\s)/;
30
+
31
+ /**
32
+ * Whether a command puts a secret file's contents in front of the model: a printing command with the file among its
33
+ * words — in the same simple command, not merely somewhere in the same line, so `source .env && npm test | tail` is
34
+ * what it looks like — or a printing command given a variable the file was bound to earlier in the line.
35
+ */
36
+ function printsSecret(command) {
37
+ const parts = command.replace(/\\\n/g, ' ').split(SEPARATORS);
38
+ let bound = false;
39
+ for (const part of parts) {
40
+ if (!SECRET_FILE.test(part)) continue;
41
+ // `$(< .env)` was split at its `$(`: what is left starts with the redirect.
42
+ if (PRINTS.test(part) || /^\s*</.test(part)) return true;
43
+ if (BINDS.test(part)) bound = true;
44
+ }
45
+ return bound && parts.some((part) => PRINTS.test(part) && part.includes('$'));
46
+ }
47
+ /**
48
+ * A command whose only job is to print the whole environment, secrets and all: `env`, `printenv`, `export`, `set`, `declare`
49
+ * or `typeset` with nothing but flags and redirections after it. `env FOO=1 cmd`, `set -e`, `export FOO=1` and `printenv HOME` are not that.
50
+ * A redirection is its first mark and whatever follows: `>>` read as one mark or as two is the same word, counted twice.
51
+ */
52
+ const DUMPS_ENV = /^\s*(?:sudo\s+)?(?:(?:env|printenv|declare|typeset)(?:\s+(?:-\S+|\d*[<>&]\S*))*|export(?:\s+-p)?|set)\s*$/;
53
+
54
+ /**
55
+ * `rm` — by any path (`/bin/rm`), escaped (`\rm`), behind sudo, env, nice, timeout or xargs — and everything up to the
56
+ * end of its command, which a new line is too. Its flags may come before or after its targets; only a recursive spelling
57
+ * of them is looked at further. Each word between is read one way — a word, whatever it starts with: a dash that
58
+ * could be read apart from its word doubled the readings with every flag, and a build's worth of flags stood the check still.
59
+ */
60
+ const RM = /(^|[\s;&|(`"'])(?:(?:sudo|env|nice|timeout|xargs|command)(?:\s+\S+)*?\s+)?\\?(?:\/\S*\/)?rm\s+([^;&|)`\n]+)/g;
61
+ const RECURSIVE = /(^|\s)(?:-[a-zA-Z]*[rR][a-zA-Z]*|--recursive)(?=\s|$)/;
62
+ const FLAG = /^-{1,2}[\w-]+$/;
63
+
64
+ /** A target that is the whole machine, the home, the working directory, or one level below any of them. */
65
+ const ROOT_OR_HOME_OR_HERE = /^(?:\/|~\/?|\$HOME\/?|\$\{HOME\}\/?|\.{1,2}\/?|\*|\.{1,2}\/\*|(?:\/|~\/|\$HOME\/|\$\{HOME\}\/)(?:[^/\s*]+\/?|\*))$/;
66
+
67
+ const unquote = (word) => word.replace(/^["']|["']$/g, '');
68
+
69
+ /** The home and the working directory spelled out in full are the same targets as `~` and `.`. */
70
+ function spelledShort(target, { cwd, home }) {
71
+ const trimmed = target.length > 1 ? target.replace(/\/+$/, '') : target;
72
+ if (cwd && (trimmed === cwd || trimmed === `${cwd}/*`)) return '.';
73
+ if (home && (trimmed === home || trimmed.startsWith(`${home}/`))) return `~${trimmed.slice(home.length)}`;
74
+ return target;
75
+ }
76
+
77
+ const RULES = [
78
+ {
79
+ test: (c, where) => {
80
+ // A line ending in a backslash goes on: its targets are still rm's.
81
+ for (const m of c.replace(/\\\n/g, ' ').matchAll(RM)) {
82
+ const words = m[2].trim().split(/\s+/);
83
+ // `--` ends the flags: what follows is a target, however it is spelled.
84
+ const end = words.indexOf('--');
85
+ const flags = (end === -1 ? words : words.slice(0, end)).filter((w) => FLAG.test(w));
86
+ if (!RECURSIVE.test(flags.join(' '))) continue;
87
+ const targets = (end === -1 ? words.filter((w) => !FLAG.test(w)) : words.slice(end + 1)).map(unquote).map((t) => spelledShort(t, where));
88
+ if (targets.some((t) => ROOT_OR_HOME_OR_HERE.test(t))) return true;
89
+ }
90
+ return false;
91
+ },
92
+ why: (c) => `\`${c}\` would delete a whole tree — the machine, the home directory, the working directory, or something one level below one of them`,
93
+ },
94
+ { test: (c) => /\bgit\s+reset\s+(?:\S+\s+)*--hard\b/.test(c), why: () => '`git reset --hard` throws away every uncommitted change' },
95
+ { test: (c) => /\bgit\s+clean\s+(?:\S+\s+)*(?:-[a-zA-Z]*f|--force)/.test(c), why: () => '`git clean -f` deletes every untracked file' },
96
+ // `git checkout .` too, and from a commit (`git checkout HEAD -- .`): every spelling that puts the whole tree back.
97
+ { test: (c) => /\bgit\s+(?:checkout(?:\s+(?!-)\S+)?(?:\s+--)?|restore(?:\s+--worktree)?(?:\s+--)?)\s+\.(?:\s|$)/.test(c), why: () => 'restoring `.` discards every uncommitted change at once' },
98
+ { test: (c) => /\bgit\s+branch\s+(?:\S+\s+)*-D\b/.test(c), why: () => '`git branch -D` deletes a branch whether or not it was merged' },
99
+ { test: (c) => /\bgit\s+stash\s+(?:drop|clear)\b/.test(c), why: () => 'dropping a stash loses work that is nowhere else' },
100
+ {
101
+ test: (c) => /\b(?:psql|mysql|mariadb|sqlite3|sqlcmd|mongosh?)\b[\s\S]*\b(?:DROP\s+(?:TABLE|DATABASE|SCHEMA)|TRUNCATE)\b/i.test(c),
102
+ why: () => 'that statement empties or drops a table or database',
103
+ },
104
+ { test: (c) => printsSecret(c), why: () => 'it would print a secret file (.env, a private key, credentials). Use `source`/`set -a` to load it without showing it' },
105
+ { test: (c) => c.replace(/\\\n/g, ' ').split(SEPARATORS).some((part) => DUMPS_ENV.test(part)), why: () => 'it would print the whole environment, secrets included. A variable is for the command that needs it, never for printing' },
106
+ ];
107
+
108
+ /** Why a shell command is refused, or null when it may run. `cwd` is where it would run, so its full spelling is known too. */
109
+ export function guardCommand(command, { cwd = null, home = homedir() } = {}) {
110
+ for (const rule of RULES) {
111
+ if (rule.test(command, { cwd, home })) return `Refused: ${rule.why(command)}. If it is what the user wants, they run it themselves: \`! ${command}\``;
112
+ }
113
+ return null;
114
+ }
115
+
116
+ export const isSecretPath = (path) => SECRET_FILE.test(path);
117
+
118
+ /** Why reading a file is refused, or null when it may be read. */
119
+ export function guardPath(path) {
120
+ return isSecretPath(path) ? `Refused: ${path} is a secret file. Its values are for the environment, not the context — load it with \`source\` where it is needed, and ask the user what it holds.` : null;
121
+ }
package/src/guides.mjs ADDED
@@ -0,0 +1,86 @@
1
+ import { readdirSync, readFileSync } from 'node:fs';
2
+ import { join } from 'node:path';
3
+ import { getMeta } from './db.mjs';
4
+ import { REPO_ROOT } from './paths.mjs';
5
+ import { CONFIG_DEFAULTS } from './setup.mjs';
6
+ import { stem, words } from './text.mjs';
7
+
8
+ /**
9
+ * A guide is the written way of doing one kind of work: a short numbered list in guides/<name>.md.
10
+ * Telling the model to go and read one does not work — the session logs show the work happening
11
+ * daily and the guides read about never — so the three that are ways of working fire by
12
+ * themselves. A `when:` line in a header names the phrases that mean the user is asking for that
13
+ * work; the guide rides in with the message that says one, judged by word stems the way a taught
14
+ * workflow is, with no model asked and no token spent until it fires. A guide with no header is a
15
+ * reference page: read on demand, never matched.
16
+ */
17
+
18
+ const HEADER = /^---\n([\s\S]*?)\n---\n/;
19
+ const TITLE = /^#[^\n]*\n+/;
20
+
21
+ /**
22
+ * Which guide wins when a message says more than one: "review my fix" is a review, "fix the broken add
23
+ * button" is a fix. Also the only guides that fire — a header on any other file is ignored.
24
+ */
25
+ const PRECEDENCE = ['review', 'fix', 'feature'];
26
+ /** What a worker's brief may carry unasked: a job is never a review of itself. */
27
+ export const WORKER_GUIDES = ['fix', 'feature'];
28
+
29
+ const stemsOf = (text) => new Set(words(text).map(stem));
30
+
31
+ /** `a, b, "a phrase, quoted"` → the phrases, each as the stems every one of which has to be in the message. */
32
+ function phrasesOf(value) {
33
+ return value
34
+ .split(',')
35
+ .map((p) => p.trim().replace(/^"(.*)"$/, '$1'))
36
+ .filter(Boolean)
37
+ .map((p) => [...stemsOf(p)])
38
+ .filter((stems) => stems.length > 0);
39
+ }
40
+
41
+ function parse(text) {
42
+ const header = HEADER.exec(text);
43
+ const fields = Object.fromEntries((header?.[1] ?? '').split('\n').map((l) => l.split(/:\s*/, 2)).filter(([k, v]) => k && v));
44
+ return { when: fields.when ? phrasesOf(fields.when) : [], body: text.replace(HEADER, '').replace(TITLE, '').trim() };
45
+ }
46
+
47
+ const fileOf = (name) => join(REPO_ROOT, 'guides', `${name}.md`);
48
+
49
+ /** The guide's steps, without the header and the title — the brief has its own heading for them. */
50
+ export function guideBody(name) {
51
+ return parse(readFileSync(fileOf(name), 'utf8')).body;
52
+ }
53
+
54
+ /** Every guide that fires, in the order they are tried. */
55
+ export function firingGuides() {
56
+ const present = new Set(readdirSync(join(REPO_ROOT, 'guides')).map((f) => f.replace(/\.md$/, '')));
57
+ return PRECEDENCE.filter((name) => present.has(name))
58
+ .map((name) => ({ name, ...parse(readFileSync(fileOf(name), 'utf8')) }))
59
+ .filter((g) => g.when.length > 0);
60
+ }
61
+
62
+ /** The guide the text asks for: the first, by precedence, with a phrase all of whose stems are in it. */
63
+ export function matchGuide(text, among = PRECEDENCE) {
64
+ const have = stemsOf(String(text ?? ''));
65
+ const hit = firingGuides().find((g) => among.includes(g.name) && g.when.some((stems) => stems.every((s) => have.has(s))));
66
+ return hit?.name ?? null;
67
+ }
68
+
69
+ const RECEIVING = '**Receiving a review.**';
70
+
71
+ /**
72
+ * The block the chat is handed. A fix or a feature is done in the conversation, so its steps go in whole.
73
+ * A review is not: code written in a session is never judged in that session, so the chat is told to
74
+ * delegate it and given only the half about receiving the findings.
75
+ */
76
+ export function renderGuide(name) {
77
+ const body = guideBody(name);
78
+ if (name === 'review') {
79
+ return `<guide review>\nCode written in this session is never reviewed in this session: delegate it to a reviewer (agent "reviewer", the task what was asked); then this is how to treat the findings:\n${body.slice(body.indexOf(RECEIVING) + RECEIVING.length).trim()}\n</guide>`;
80
+ }
81
+ const asking = name === 'fix' ? 'a fix' : 'something built';
82
+ return `<guide ${name}>\nThe user is asking for ${asking}. This is how that is done here — follow it in order:\n${body}\n</guide>`;
83
+ }
84
+
85
+ /** `guides.auto`: whether guides ride in unasked and the end of a turn is held for an unchecked edit. */
86
+ export const autoGuides = (db) => (getMeta(db, 'config.guides.auto') ?? CONFIG_DEFAULTS['guides.auto']) !== 'off';
package/src/herdr.mjs ADDED
@@ -0,0 +1,117 @@
1
+ import { spawnSync } from 'node:child_process';
2
+ import { paths } from './paths.mjs';
3
+
4
+ /**
5
+ * Herdr is where a delegated job can be watched. The job itself runs in the chat's process; inside Herdr it also
6
+ * gets a tab of its own, listed on the left and named after it, where `sumo job watch` shows its work as it
7
+ * happens and reports it to Herdr as an agent with its state — so the chat keeps one line per job. Everything
8
+ * goes through the `herdr` CLI, which answers in JSON.
9
+ */
10
+
11
+ export const runHerdr = (args) => spawnSync('herdr', args, { encoding: 'utf8', timeout: 10_000 });
12
+
13
+ /** The name a job goes by in Herdr's lists: `j33 scout`. */
14
+ export const agentLabel = (job) => `j${job.id} ${job.agent}`;
15
+
16
+ /**
17
+ * What the job's own process tells Herdr about itself, when it runs in a pane: working while it works, blocked
18
+ * when it stopped on a question, idle when it is over. Best effort — a Herdr that will not listen changes nothing.
19
+ */
20
+ export function reportAgent(herdr, env, { job, state, message = '' }) {
21
+ if (!env.HERDR_PANE_ID) return;
22
+ herdr(['pane', 'report-agent', env.HERDR_PANE_ID, '--source', 'sumo', '--agent', agentLabel(job), '--state', state, ...(message ? ['--message', message.slice(0, 200)] : [])]);
23
+ }
24
+
25
+ /** One word for the shell a pane runs: left as it is when it is plain, single-quoted when it holds a space or anything else the shell would read. */
26
+ const shellWord = (text) => (/^[\w/.:=@%+-]+$/.test(text) ? text : `'${text.replaceAll("'", `'\\''`)}'`);
27
+
28
+ /**
29
+ * A tab in the chat's workspace that shows a job's work: `sumo job watch`, not the job — that stays in the chat.
30
+ * Throws with Herdr's reason when the tab cannot be opened; the job runs the same either way. The watcher is typed
31
+ * into the tab's shell after this returns, once the shell is ready for it; `onFail` hears why when it never started.
32
+ */
33
+ export function openWatchTab(herdr, { job, project, env = process.env, onFail = () => {}, sleep }) {
34
+ const workspace = env.HERDR_WORKSPACE_ID ? ['--workspace', env.HERDR_WORKSPACE_ID] : [];
35
+ const made = herdr(['tab', 'create', ...workspace, '--cwd', project.path, '--label', `${agentLabel(job)} · ${job.title}`, '--no-focus']);
36
+ const tab = parse(made, (result) => result.root_pane?.pane_id);
37
+ if (tab.error) throw new Error(tab.error);
38
+ // Marked as the tab's own, so the watcher may close it behind a job that is done; the home goes with the command,
39
+ // or a chat on another home would be watched from the default one.
40
+ const command = `env SUMO_JOB_TAB=1 SUMO_AGENTS_HOME=${shellWord(paths().home)} ${shellWord(paths().launcher)} job watch ${job.id}`;
41
+ startWatcher(herdr, { pane: tab.id, job: job.id, command, sleep })
42
+ .then((started) => started || onFail('its Herdr tab never started the watcher'))
43
+ .catch((cause) => onFail(cause.message));
44
+ return tab.id;
45
+ }
46
+
47
+ const POLL_MS = 250;
48
+ /** How long a new shell is given to reach its prompt, and a typed watcher to start, before it is typed again. */
49
+ const READY_MS = 15_000;
50
+ const STARTED_MS = 3_000;
51
+ const TRIES = 3;
52
+ const pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms).unref());
53
+
54
+ /** What the pane runs in the foreground, from Herdr; null when Herdr cannot say — an older Herdr, or a pane that is gone. */
55
+ function foreground(herdr, pane) {
56
+ const run = herdr(['pane', 'process-info', '--pane', pane]);
57
+ if (run.error || run.status !== 0) return null;
58
+ try {
59
+ return JSON.parse(run.stdout).result?.process_info ?? null;
60
+ } catch {
61
+ return null;
62
+ }
63
+ }
64
+
65
+ const screen = (herdr, pane) => {
66
+ const run = herdr(['pane', 'read', pane, '--source', 'visible']);
67
+ return run.error || run.status !== 0 ? null : String(run.stdout);
68
+ };
69
+
70
+ /**
71
+ * Types the watcher into a new tab's shell and makes sure it runs. A shell still starting up can throw away what is
72
+ * typed before its prompt — the command shows, then nothing — so the watcher is typed only once the shell stands
73
+ * alone in the foreground with its screen settled, and typed again, a few times at most, when it did not start.
74
+ * True once it runs, or once Herdr can no longer say (the pane closed behind a job that ended, or a Herdr too old to ask).
75
+ */
76
+ export async function startWatcher(herdr, { pane, job, command, sleep = pause, tries = TRIES }) {
77
+ const watching = new RegExp(`job watch ${job}(?!\\d)`);
78
+ const started = (info) => info.foreground_processes?.some((p) => watching.test(String(p.cmdline))) || screen(herdr, pane)?.includes(`⏺ j${job} `);
79
+ for (let attempt = 0; attempt < tries; attempt++) {
80
+ let last = null;
81
+ for (let waited = 0; waited < READY_MS; waited += POLL_MS) {
82
+ const info = foreground(herdr, pane);
83
+ if (info === null) break;
84
+ const now = screen(herdr, pane);
85
+ const alone = info.foreground_processes?.every((p) => p.pid === info.shell_pid);
86
+ if (alone && now?.trim() && now === last) break;
87
+ last = now;
88
+ await sleep(POLL_MS);
89
+ }
90
+ const run = herdr(['pane', 'run', pane, command]);
91
+ if (run.error || run.status !== 0) throw new Error(`Herdr opened the tab but would not run the watcher in it: ${String(run.stderr || run.stdout || run.error?.message).trim().slice(0, 200)}`);
92
+ for (let waited = 0; waited < STARTED_MS; waited += POLL_MS) {
93
+ await sleep(POLL_MS);
94
+ const info = foreground(herdr, pane);
95
+ if (info === null || started(info)) return true;
96
+ }
97
+ }
98
+ return false;
99
+ }
100
+
101
+ function parse(run, pick) {
102
+ if (run.error) return { error: run.error.code === 'ENOENT' ? '`herdr` is not on PATH' : run.error.message };
103
+ try {
104
+ const answer = JSON.parse(run.stdout);
105
+ if (answer.error) return { error: answer.error.message ?? answer.error.code ?? 'Herdr refused' };
106
+ const id = pick(answer.result ?? {});
107
+ return id ? { id } : { error: 'Herdr answered without a pane id' };
108
+ } catch {
109
+ return { error: `Herdr did not answer in JSON: ${String(run.stderr || run.stdout).trim().slice(0, 200)}` };
110
+ }
111
+ }
112
+
113
+ /** A job that is done closes the tab opened to watch it; one that failed or stopped on a question keeps it, and a tab the user opened is theirs. */
114
+ export function closeJobTab(herdr, env, job) {
115
+ if (!env.SUMO_JOB_TAB || !env.HERDR_TAB_ID || job.status !== 'done') return;
116
+ herdr(['tab', 'close', env.HERDR_TAB_ID]);
117
+ }