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/prime.mjs CHANGED
@@ -1,8 +1,8 @@
1
1
  import { homedir } from 'node:os';
2
- import { ago } from './card.mjs';
2
+ import { ago, askLines } from './card.mjs';
3
3
  import { getMeta } from './db.mjs';
4
4
  import { paths } from './paths.mjs';
5
- import { isScratch, listProjects, scratchDays } from './projects.mjs';
5
+ import { isScratch, listProjects, SCRATCH_DAYS } from './projects.mjs';
6
6
  import { CONFIG_DEFAULTS } from './setup.mjs';
7
7
  import { clip, estimateTokens } from './text.mjs';
8
8
 
@@ -11,6 +11,8 @@ const NAME_MAX = 60;
11
11
  const MAX_PROJECTS = 12;
12
12
  const MAX_LEFT_OFF = 3;
13
13
  const MAX_CONFIRM = 3;
14
+ /** The block's ceiling, in tokens: what does not fit is found by search. */
15
+ const PRIME_BUDGET = 800;
14
16
  const MAX_NOTICES = 2;
15
17
  const SCRIBE_FAILURES_TO_WARN = 3;
16
18
  /** A preference never used, and said more days ago than this, is the first to leave the block when room is short. */
@@ -25,20 +27,19 @@ const tilde = (path) => (path === homedir() || path.startsWith(`${homedir()}/`)
25
27
  * they are the problem". Everything that does not fit is reachable by search,
26
28
  * and the block says so rather than silently pretending to be complete.
27
29
  */
28
- export function prime(db, { budget, now = new Date().toISOString() } = {}) {
29
- const asked = budget ?? Number(getMeta(db, 'config.prime.budget') ?? CONFIG_DEFAULTS['prime.budget']);
30
+ export function prime(db, { budget, project = null, now = new Date().toISOString() } = {}) {
30
31
  // A budget that is not a number would hold nothing back: the default stands in for it.
31
- const limit = Number.isInteger(asked) && asked > 0 ? asked : Number(CONFIG_DEFAULTS['prime.budget']);
32
+ const limit = Number.isInteger(budget) && budget > 0 ? budget : PRIME_BUDGET;
32
33
  const machine = getMeta(db, 'machine');
33
34
  const open = `<sumo-memory${machine ? ` machine="${machine}"` : ''}>`;
34
35
  const close = '</sumo-memory>';
35
36
 
36
37
  // The small, time-sensitive sections are fixed first; preferences get whatever room is left.
37
38
  // Preserve the compact layout normally; when it cannot fit, keep time-sensitive lines first.
38
- const sections = [workflows(db), projectsLine(db), leftOff(db, now), jobs(db, now), toConfirm(db), warnings(db)];
39
+ const sections = [workflows(db), projectsLine(db), leftOff(db, now), jobs(db, now), toConfirm(db, { project, now }), warnings(db)];
39
40
  // Where the work with no project goes is said every time, and is not something remembered.
40
41
  const remembered = sections.flat().length;
41
- sections.splice(2, 0, scratchLine(db));
42
+ sections.splice(2, 0, scratchLine());
42
43
  const fixed = sections.flat();
43
44
  const spent = estimateTokens([open, ...fixed, close].join('\n'));
44
45
  const prefs = preferences(db, limit - spent, now);
@@ -121,8 +122,8 @@ function projectsLine(db) {
121
122
  return [`Projects: ${shown.join(' · ')}${more}`];
122
123
  }
123
124
 
124
- function scratchLine(db) {
125
- return [`Scratch: ${tilde(paths().scratch)} — work that belongs to no project goes here, a folder per chore; one idle ${scratchDays(db)} days is deleted`];
125
+ function scratchLine() {
126
+ return [`Scratch: ${tilde(paths().scratch)} — work that belongs to no project goes here, a folder per chore; one idle ${SCRATCH_DAYS} days is deleted`];
126
127
  }
127
128
 
128
129
  function leftOff(db, now) {
@@ -142,35 +143,22 @@ function jobs(db, now) {
142
143
  return rows.map((j) => `Job j${j.id} ${j.project} "${clip(j.title, 60)}" ${j.status.toUpperCase()} (${ago(j.updated_at, now)}) → sumo job show ${j.id}`);
143
144
  }
144
145
 
145
- function toConfirm(db) {
146
- const guesses = db.prepare(`SELECT * FROM memories WHERE state = 'unconfirmed' ORDER BY id LIMIT ?`).all(MAX_CONFIRM);
147
- const out = guesses.map(
148
- (m) => `Ask the user (then sumo confirm|reject m${m.id}): is this right? "${clip(m.type === 'procedure' ? `workflow "${m.title}"` : m.body, LINE_MAX)}"`,
149
- );
150
- // A notice stands only while both memories are still true; superseding or forgetting either settles it.
151
- const notices = db
152
- .prepare(
153
- `SELECT n.* FROM notices n
154
- JOIN memories a ON a.id = n.memory_a AND a.state = 'active'
155
- JOIN memories b ON b.id = n.memory_b AND b.state = 'active'
156
- ORDER BY n.id LIMIT ?`,
157
- )
158
- .all(MAX_NOTICES);
159
- for (const n of notices) {
160
- const verb = n.kind === 'lookalike' ? 'look alike' : 'disagree';
161
- out.push(`Ask the user: m${n.memory_a} and m${n.memory_b} ${verb} — ${clip(n.note, LINE_MAX)} (sumo show both; settle with sumo supersede or sumo forget)`);
162
- }
163
- return out;
146
+ /**
147
+ * What to put to the user at the start: guesses and notices about everything and about this session's project, each
148
+ * guess for two weeks. One about another project is asked with that project's card, when it comes up.
149
+ */
150
+ function toConfirm(db, { project = null, now }) {
151
+ return askLines(db, { scopes: ['global', ...(project ? [`project:${project}`] : [])], now, guesses: MAX_CONFIRM, notices: MAX_NOTICES });
164
152
  }
165
153
 
166
154
  function warnings(db) {
167
155
  const out = [];
168
156
  // AGENTS.md says a background writer files what the user says; with it off, nothing does unless the model is told.
169
- if ((getMeta(db, 'config.scribe.model') ?? CONFIG_DEFAULTS['scribe.model']) === 'off') {
170
- out.push('The memory writer is off (scribe.model): save what the user states that should last, as it is said, with sumo add.');
157
+ if ((getMeta(db, 'config.memory.model') ?? CONFIG_DEFAULTS['memory.model']) === 'off') {
158
+ out.push('The memory pass is off (memory.model): save what the user states that should last, as it is said, with sumo add.');
171
159
  }
172
160
  const failures = Number(getMeta(db, 'scribe.failures') ?? 0);
173
- if (failures >= SCRIBE_FAILURES_TO_WARN) out.push(`Warning: the background memory writer has failed ${failures} times in a row — nothing new is being remembered. Tell the user; sumo scribe status shows why.`);
161
+ if (failures >= SCRIBE_FAILURES_TO_WARN) out.push(`Warning: the background memory writer has failed ${failures} times in a row — nothing new is being remembered. Tell the user; sumo memory status shows why.`);
174
162
  const backup = getMeta(db, 'backup.failed');
175
163
  if (backup) out.push(`Warning: the weekly backup could not be written (${backup}). Tell the user; sumo backup tries again.`);
176
164
  return out;
package/src/projects.mjs CHANGED
@@ -3,10 +3,11 @@ import { homedir } from 'node:os';
3
3
  import { basename, join, resolve } from 'node:path';
4
4
  import { getMeta, setMeta, tx } from './db.mjs';
5
5
  import * as memory from './memory.mjs';
6
- import { UsageError } from './memory.mjs';
6
+ import { Refusal, UsageError } from './memory.mjs';
7
7
  import { paths } from './paths.mjs';
8
- import { gitRemote, scan } from './scan.mjs';
9
- import { CONFIG_DEFAULTS } from './setup.mjs';
8
+ import { changedSince, gitRemote, presentOf, scan } from './scan.mjs';
9
+
10
+ import { STOPWORDS } from './text.mjs';
10
11
 
11
12
  /**
12
13
  * Names too ordinary to mean "this project" when they turn up in a sentence.
@@ -22,7 +23,7 @@ const slugify = (name) => name.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').repl
22
23
 
23
24
  function expand(path) {
24
25
  const full = resolve(path.replace(/^~(?=$|\/)/, homedir()));
25
- if (!existsSync(full) || !statSync(full).isDirectory()) throw new UsageError(`${full} is not a directory`);
26
+ if (!existsSync(full) || !statSync(full).isDirectory()) throw new Refusal(`${full} is not a directory`);
26
27
  return realpathSync(full);
27
28
  }
28
29
 
@@ -35,13 +36,47 @@ export function aliasesOf(db, slug) {
35
36
  return db.prepare('SELECT alias FROM project_aliases WHERE slug = ? ORDER BY alias').all(slug).map((r) => r.alias);
36
37
  }
37
38
 
39
+ /**
40
+ * A name too short or too common to stand for a project: every sentence holding it would name the project, and its
41
+ * card — and its folder as the chat's place to work — would come with it.
42
+ */
43
+ const tooCommon = (name) => name.length < 3 || STOPWORDS.has(name);
44
+
45
+ /**
46
+ * Folders that are never a project: the disk's top, your home and anything above it, and sumo's own home. Made the
47
+ * chat's project, one would be the shell's place to write — all of it.
48
+ */
49
+ function refuseTooWide(path) {
50
+ const real = (p) => {
51
+ try {
52
+ return realpathSync(p);
53
+ } catch {
54
+ return p;
55
+ }
56
+ };
57
+ const holds = (outer, inner) => outer === '/' || outer === inner || `${inner}/`.startsWith(`${outer}/`);
58
+ const home = real(homedir());
59
+ const sumo = real(paths().home);
60
+ const refuse = (what) => {
61
+ throw new Refusal(`${path} cannot be a project: it holds ${what} — a project is one folder of work`);
62
+ };
63
+ if (path === '/') refuse('the whole disk');
64
+ if (holds(path, home)) refuse('your home');
65
+ if (holds(path, sumo)) refuse("sumo's own home");
66
+ // A system folder on the PATH (/opt/homebrew/bin, /usr/local/bin): made the shell's place to write, a program put there
67
+ // would run whenever its name is typed. One in the home is the user's own, and judged as the home is.
68
+ const onPath = String(process.env.PATH ?? '').split(':').filter((d) => d.startsWith('/')).map(real).find((d) => !holds(home, d) && holds(path, d));
69
+ if (onPath) refuse(`${onPath}, a folder on your PATH`);
70
+ }
71
+
38
72
  export function addAlias(db, slug, rawAlias) {
39
73
  const alias = slugify(rawAlias);
40
74
  if (!alias) throw new UsageError(`"${rawAlias}" is not a usable alias`);
75
+ if (tooCommon(alias)) throw new UsageError(`"${alias}" is too short or too common a word to name a project: every sentence with it would mean the project`);
41
76
  const takenBySlug = db.prepare('SELECT slug FROM projects WHERE slug = ?').get(alias);
42
77
  const takenByAlias = db.prepare('SELECT slug FROM project_aliases WHERE alias = ?').get(alias);
43
78
  const owner = takenBySlug?.slug ?? takenByAlias?.slug;
44
- if (owner && owner !== slug) throw new UsageError(`"${alias}" already means the project ${owner}`);
79
+ if (owner && owner !== slug) throw new Refusal(`"${alias}" already means the project ${owner}`);
45
80
  if (!owner) db.prepare('INSERT INTO project_aliases (alias, slug) VALUES (?, ?)').run(alias, slug);
46
81
  return alias;
47
82
  }
@@ -52,6 +87,7 @@ export function addAlias(db, slug, rawAlias) {
52
87
  */
53
88
  export function addProject(db, rawPath, { slug: wantedSlug, aliases = [], now = new Date().toISOString() } = {}) {
54
89
  const path = expand(rawPath);
90
+ refuseTooWide(path);
55
91
  // Read off disk before the write lock is taken, as rescan does.
56
92
  const read = { scanned: scan(path), remote: gitRemote(path) };
57
93
  return tx(db, () => {
@@ -60,8 +96,9 @@ export function addProject(db, rawPath, { slug: wantedSlug, aliases = [], now =
60
96
  if (created) {
61
97
  const slug = slugify(wantedSlug ?? basename(path));
62
98
  if (!slug) throw new UsageError('could not derive a name from that path — pass --slug');
99
+ if (wantedSlug !== undefined && tooCommon(slug)) throw new UsageError(`"${slug}" is too short or too common a word to name a project: every sentence with it would mean the project`);
63
100
  if (db.prepare('SELECT 1 FROM projects WHERE slug = ?').get(slug) || db.prepare('SELECT 1 FROM project_aliases WHERE alias = ?').get(slug)) {
64
- throw new UsageError(`the name "${slug}" is taken by another project — pass --slug <name>`);
101
+ throw new Refusal(`the name "${slug}" is taken by another project — pass --slug <name>`);
65
102
  }
66
103
  db.prepare('INSERT INTO projects (slug, name, path, remote, created_at, last_touched_at) VALUES (?, ?, ?, ?, ?, ?)').run(
67
104
  slug,
@@ -89,10 +126,11 @@ export function addProject(db, rawPath, { slug: wantedSlug, aliases = [], now =
89
126
  */
90
127
  export function rescan(db, nameOrAlias, now = new Date().toISOString(), read = null) {
91
128
  const project = getProject(db, nameOrAlias);
92
- if (!existsSync(project.path)) throw new UsageError(`${project.path} no longer exists — archive the project or re-add it at its new path`);
129
+ if (!existsSync(project.path)) throw new Refusal(`${project.path} no longer exists — archive the project or re-add it at its new path`);
93
130
  const scope = `project:${project.slug}`;
94
131
  // Read off disk before the write lock is taken: a slow disk or a strange file must not hold every other writer.
95
132
  const { scanned, remote } = read ?? { scanned: scan(project.path), remote: gitRemote(project.path) };
133
+ const present = presentOf(project.path);
96
134
 
97
135
  return tx(db, () => {
98
136
  const current = new Map(
@@ -127,10 +165,36 @@ export function rescan(db, nameOrAlias, now = new Date().toISOString(), read = n
127
165
  }
128
166
 
129
167
  db.prepare('UPDATE projects SET scanned_at = ?, remote = ? WHERE slug = ?').run(now, remote, project.slug);
168
+ // Which of the files it reads were there: one made or deleted since is a change no file's time can show.
169
+ setMeta(db, presentKey(project.slug), present);
130
170
  return changes;
131
171
  });
132
172
  }
133
173
 
174
+ /** Where a project's last scan keeps which of the files it reads were there. */
175
+ const presentKey = (slug) => `scan.present.${slug}`;
176
+
177
+ /** How old a scan may get before a card is built from a new one, whatever the disk says. */
178
+ const SCAN_FRESH_MS = 7 * 24 * 3_600_000;
179
+
180
+ /**
181
+ * A project's scanned facts made current before its card is shown: rescanned when the scan is a week old or anything it
182
+ * reads changed since — a stat of each file decides, so a card shown often costs nothing. True when it rescanned. A
183
+ * project whose folder is gone is left as it is: the card says where it was, and `project rescan` says what to do.
184
+ */
185
+ export function freshen(db, slug, now = new Date().toISOString()) {
186
+ const project = db.prepare('SELECT * FROM projects WHERE slug = ?').get(slug);
187
+ if (!project || !existsSync(project.path)) return false;
188
+ const stale =
189
+ !project.scanned_at ||
190
+ Date.parse(now) - Date.parse(project.scanned_at) > SCAN_FRESH_MS ||
191
+ changedSince(project.path, project.scanned_at) ||
192
+ getMeta(db, presentKey(slug)) !== presentOf(project.path);
193
+ if (!stale) return false;
194
+ rescan(db, slug, now);
195
+ return true;
196
+ }
197
+
134
198
  export function listProjects(db, { includeArchived = false } = {}) {
135
199
  return db
136
200
  .prepare(`SELECT * FROM projects ${includeArchived ? '' : `WHERE status = 'active'`} ORDER BY COALESCE(last_touched_at, created_at) DESC`)
@@ -167,8 +231,26 @@ export function detect(db, text) {
167
231
  return [...found];
168
232
  }
169
233
 
234
+ /**
235
+ * The registered project a directory is in — the project itself or a folder inside it, the deepest when one holds another —
236
+ * or null. A path reached through a link is read as where it leads, as a project's own path is.
237
+ */
238
+ export function projectAt(db, dir) {
239
+ let at;
240
+ try {
241
+ at = realpathSync(resolve(dir));
242
+ } catch {
243
+ at = resolve(dir);
244
+ }
245
+ const inside = db
246
+ .prepare(`SELECT slug, path FROM projects WHERE status = 'active'`)
247
+ .all()
248
+ .filter(({ path }) => at === path || at.startsWith(path.endsWith('/') ? path : `${path}/`));
249
+ return inside.sort((a, b) => b.path.length - a.path.length)[0]?.slug ?? null;
250
+ }
251
+
170
252
  /** The project for work that belongs to none. It lives in Sumo's own home, and a chore in it is kept only while it is worked on. */
171
- export const SCRATCH = 'scratch';
253
+ const SCRATCH = 'scratch';
172
254
  const DAY_MS = 24 * 3_600_000;
173
255
 
174
256
  /** Scratch's directory, made if it is not there: tools start in it, so it has to be. */
@@ -181,12 +263,12 @@ export function scratchDir() {
181
263
  export const isScratch = (project) => project.path === scratchDir();
182
264
 
183
265
  /** How many days a chore nothing is written in is kept. */
184
- export const scratchDays = (db) => Number(getMeta(db, 'config.scratch.days') ?? CONFIG_DEFAULTS['scratch.days']);
266
+ export const SCRATCH_DAYS = 14;
185
267
 
186
268
  /** How scratch is used, as its card and a job's brief say it. */
187
- export const scratchRules = (db) => [
269
+ export const scratchRules = () => [
188
270
  'for work that belongs to no project: one folder per chore, named <date>-<what it is>',
189
- `a folder nothing is written in for ${scratchDays(db)} days is deleted — to keep one, move it out of here, then: sumo project add <path>`,
271
+ `a folder nothing is written in for ${SCRATCH_DAYS} days is deleted — to keep one, move it out of here, then: sumo project add <path>`,
190
272
  'nothing here is checked or remembered: say in the report what you ran to prove the work',
191
273
  ];
192
274
 
@@ -227,6 +309,6 @@ export function keepScratch(db, now) {
227
309
  ensureScratch(db, now);
228
310
  const last = getMeta(db, 'scratch.pruned');
229
311
  if (last && Date.parse(now) - Date.parse(last) < DAY_MS) return;
230
- pruneScratch(now, scratchDays(db));
312
+ pruneScratch(now, SCRATCH_DAYS);
231
313
  setMeta(db, 'scratch.pruned', now);
232
314
  }
package/src/redact.mjs CHANGED
@@ -17,6 +17,12 @@ const PATTERNS = [
17
17
  /\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g,
18
18
  ];
19
19
 
20
+ /**
21
+ * A credential sent the HTTP way — `Authorization: Bearer <token>`, `Basic <base64>` — whatever its vendor: the scheme is
22
+ * kept, the credential goes. A token has a digit in it; a long plain word after "basic" in prose is left alone.
23
+ */
24
+ const AUTH_SCHEME = /\b(Bearer|Basic)\s+(?=[A-Za-z0-9._~+/=-]*\d)[A-Za-z0-9._~+/=-]{16,}/gi;
25
+
20
26
  // The name may be the tail of a longer one (DB_PASSWORD, GITHUB_TOKEN) and may be quoted, as a JSON key is; what follows it must be the assignment itself.
21
27
  const ASSIGNMENT = /(password|passwd|secret|token|api[_-]?key|access[_-]?key)(["']?\s*[:=]\s*)(["']?)([^\s"']{6,})\3/gi;
22
28
 
@@ -149,6 +155,10 @@ function redactReadable(text) {
149
155
  return `${head}${MARK}@`;
150
156
  });
151
157
  for (const pattern of PATTERNS) out = out.replace(pattern, hit);
158
+ out = out.replace(AUTH_SCHEME, (_m, scheme) => {
159
+ count++;
160
+ return `${scheme} ${MARK}`;
161
+ });
152
162
  out = keyFragments(out, hit);
153
163
  out = out.replace(ENV_KEY_QUOTED, (m, name, sep, _quote, value) => {
154
164
  if (value.startsWith('${')) return m;
package/src/render.mjs CHANGED
@@ -14,7 +14,8 @@ export function scopeLabel(scope) {
14
14
 
15
15
  function tags(m) {
16
16
  const parts = [TYPE_TAG[m.type], scopeLabel(m.scope), m.provenance];
17
- if (m.state !== 'active') parts.push(m.state);
17
+ // Stored as invalid; said as what the user did to it.
18
+ if (m.state !== 'active') parts.push(m.state === 'invalid' ? 'forgotten' : m.state);
18
19
  if (m.pinned) parts.push('pinned');
19
20
  return `[${parts.join('·')}]`;
20
21
  }
package/src/route.mjs CHANGED
@@ -1,4 +1,6 @@
1
1
  import { MODELS, usableModels } from './catalog.mjs';
2
+ import { getMeta } from './db.mjs';
3
+ import { CONFIG_DEFAULTS } from './setup.mjs';
2
4
  import { callLocalModel } from './model.mjs';
3
5
  import { UsageError } from './memory.mjs';
4
6
  import { elapsed } from './text.mjs';
@@ -14,8 +16,8 @@ const ROUTER_SYSTEM =
14
16
  'You assign a coding job to a model and an effort level. Answer with JSON only. First classify the job, then choose. kind: mechanical (typos, ' +
15
17
  'renames, comments, constants, tests for a pure function), routine (an ordinary feature or fix with a clear spec), hard (design, a bug whose ' +
16
18
  'cause is unknown, or reviewing risky code), novel (new algorithms, subtle concurrency, deep security review). surface: how much code the job ' +
17
- 'touches. risky: true when it touches security, credentials, money, migrations or concurrency. Model follows kind: haiku for mechanical (it ' +
18
- 'takes no effort setting), sonnet for routine, opus for hard, fable for novel. Effort follows surface: low for one spot, medium for a few ' +
19
+ 'touches. risky: true when it touches security, credentials, money, migrations or concurrency. Model follows kind: haiku for mechanical, ' +
20
+ 'sonnet for routine, opus for hard, fable for novel. Effort follows surface: low for one spot, medium for a few ' +
19
21
  'files, high for many interacting parts. risky raises the effort one step (low, medium, high, xhigh, max) and makes a routine job hard. ' +
20
22
  'History lists only the routes that failed or drew Important review findings on this project: for work like that, go above them.';
21
23
 
@@ -31,15 +33,15 @@ const SCOUT_ROUTER_SYSTEM =
31
33
  'exist, which dependencies are behind — however large or unfamiliar the project), hard (it must judge: an audit of security or ' +
32
34
  'correctness, a review, a hunt for the cause of a bug), novel (almost never: only reasoning nobody has written down, such as proving a ' +
33
35
  'concurrent algorithm correct). surface: how much code must be read. risky: true when what is judged is security, credentials, money, ' +
34
- 'migrations or concurrency. Model follows kind: haiku for mechanical (it takes no effort setting), sonnet for routine, opus for hard, ' +
36
+ 'migrations or concurrency. Model follows kind: haiku for mechanical, sonnet for routine, opus for hard, ' +
35
37
  'fable for novel. Effort follows surface: low for one spot, medium for a few files or a whole project read for a summary, high when ' +
36
38
  'many interacting parts must be judged together. risky raises the effort one step (low, medium, high, xhigh, max). ' +
37
39
  'History lists only the routes that failed or drew Important review findings on this project: for work like that, go above them.';
38
40
 
39
41
  /**
40
- * One answer shape per pairing, so the grammar itself cannot give haiku an effort or another model none.
41
- * The classification comes first: a small model that names the route first just repeats a route it was
42
- * shown, and one that has described the job first chooses from the description.
42
+ * The answer shape: the models that are on and the efforts every one of them takes. The classification comes
43
+ * first: a small model that names the route first just repeats a route it was shown, and one that has described
44
+ * the job first chooses from the description.
43
45
  */
44
46
  const answerShape = (models, efforts) => ({
45
47
  type: 'object',
@@ -54,13 +56,8 @@ const answerShape = (models, efforts) => ({
54
56
  required: ['kind', 'surface', 'risky', 'model', 'effort', 'reason'],
55
57
  additionalProperties: false,
56
58
  });
57
- /** The grammar over the models that are on: the haiku branch while haiku is, the effort branch over the others. */
58
- const routerSchema = (usable) => ({
59
- anyOf: [
60
- ...(usable.includes('haiku') ? [answerShape(['haiku'], ['none'])] : []),
61
- ...(usable.some((m) => m !== 'haiku') ? [answerShape(usable.filter((m) => m !== 'haiku'), EFFORTS)] : []),
62
- ],
63
- });
59
+ /** The grammar over the models that are on. */
60
+ const routerSchema = (usable) => answerShape(usable, EFFORTS);
64
61
 
65
62
  const TASK_CUT = 3500;
66
63
 
@@ -148,7 +145,7 @@ function routerPrompt(db, { agent, project, task, title, retryOf }) {
148
145
  return [
149
146
  `role: ${agent}`,
150
147
  `project: ${project.slug}${stack ? ` (${stack})` : ''}`,
151
- `models: ${usableModels(db).join(', ')}`,
148
+ `models: ${jobModels(db).join(', ')}`,
152
149
  ...(retryOf === undefined ? [] : [retryLine(db, retryOf)].filter(Boolean)),
153
150
  'history:',
154
151
  historyText(db, project.slug),
@@ -168,7 +165,7 @@ const CHAT_ROUTER_SYSTEM =
168
165
  'rename, running a command and reporting), routine (an ordinary feature or fix with a clear ask, a summary, an explanation), hard (design, ' +
169
166
  'a bug whose cause is unknown, a review of risky code, planning across a codebase), novel (new algorithms, subtle concurrency, deep security ' +
170
167
  'review). surface: how much code the turn touches. risky: true when it touches security, credentials, money, migrations or concurrency. ' +
171
- 'Model follows kind: haiku for mechanical (it takes no effort setting), sonnet for routine, opus for hard, fable for novel. Effort follows ' +
168
+ 'Model follows kind: haiku for mechanical, sonnet for routine, opus for hard, fable for novel. Effort follows ' +
172
169
  'surface: low for one spot, medium for a few files, high for many interacting parts. risky raises the effort one step (low, medium, high, ' +
173
170
  'xhigh, max) and makes a routine turn hard.';
174
171
 
@@ -177,33 +174,42 @@ function chatRouterPrompt(db, { project, text }) {
177
174
  return [`project: ${project ? `${project.slug}${stack ? ` (${stack})` : ''}` : 'none'}`, `models: ${usableModels(db).join(', ')}`, 'turn:', String(text ?? '').slice(0, TASK_CUT)].join('\n');
178
175
  }
179
176
 
180
- const askRouter = (db, { agent, project, task, title, retryOf }) => askFor(db, agent === 'scout' ? SCOUT_ROUTER_SYSTEM : ROUTER_SYSTEM, routerPrompt(db, { agent, project, task, title, retryOf }));
177
+ /** The smallest model a job may run on (`jobs.floor`); haiku, the cheapest, holds nothing back. */
178
+ const jobFloor = (db) => getMeta(db, 'config.jobs.floor') ?? CONFIG_DEFAULTS['jobs.floor'];
181
179
 
182
- async function askFor(db, system, prompt) {
180
+ /** The models a job may be routed to: the ones that are on, from the floor up — or all of them, when none at or above it is on. */
181
+ export function jobModels(db) {
183
182
  const usable = usableModels(db);
183
+ const above = usable.filter((m) => MODELS.indexOf(m) >= MODELS.indexOf(jobFloor(db)));
184
+ return above.length > 0 ? above : usable;
185
+ }
186
+
187
+ const askRouter = (db, { agent, project, task, title, retryOf }) => askFor(db, agent === 'scout' ? SCOUT_ROUTER_SYSTEM : ROUTER_SYSTEM, routerPrompt(db, { agent, project, task, title, retryOf }), jobModels(db));
188
+
189
+ async function askFor(db, system, prompt, models = usableModels(db)) {
190
+ const usable = models;
184
191
  if (usable.length === 0) throw new UsageError('no model is on — sumo models enable <name>');
185
192
  const result = await callLocalModel(db, { system, prompt, schema: routerSchema(usable) });
186
193
  if (!result.ok) return { ok: false, error: result.error };
187
194
  const { model, effort, reason, risky } = result.data ?? {};
188
195
  // The same pairing the schema enforces, checked again: a backend without grammar support can still answer anything.
189
- const fits = usable.includes(model) && (model === 'haiku' ? effort === 'none' : EFFORTS.includes(effort));
196
+ const fits = usable.includes(model) && EFFORTS.includes(effort);
190
197
  if (!fits || typeof reason !== 'string' || !reason.trim()) return { ok: false, error: `the router answered outside its schema: ${JSON.stringify(result.data)}` };
191
198
  // Whether the work touches security, credentials, money, migrations or concurrency: kept, so such work is reviewed. Only a plain yes is one.
192
199
  return { ok: true, model, effort, reason: reason.replace(/\s+/g, ' ').trim(), risky: risky === true };
193
200
  }
194
201
 
195
202
  // Routes compared on one scale: by model first, cheapest to dearest as the catalog lists them, then by effort.
196
- // Haiku's 'none' sits below every effort.
203
+ // The 'none' an old job ran at, from when haiku took no effort, sits below every effort.
197
204
  const modelRank = (model) => MODELS.indexOf(model);
198
205
  const effortRank = (effort) => EFFORTS.indexOf(effort);
199
206
  const compareRoutes = (a, b) => modelRank(a.model) - modelRank(b.model) || effortRank(a.effort) - effortRank(b.effort);
200
207
 
201
- /** One step above a route: the next model up that is on, keeping the effort (medium, off haiku); on the top one, one effort up, max at most. */
208
+ /** One step above a route: the next model up that is on, keeping the effort (medium, off an old 'none'); on the top one, one effort up, max at most. */
202
209
  function stepAbove({ model, effort }, usable) {
203
210
  const next = usable.find((m) => modelRank(m) > modelRank(model));
204
211
  if (next) return { model: next, effort: EFFORTS.includes(effort) ? effort : 'medium' };
205
212
  const top = usable.at(-1);
206
- if (top === 'haiku') return { model: top, effort: 'none' };
207
213
  return { model: top, effort: EFFORTS[Math.min(effortRank(effort) + 1, EFFORTS.length - 1)] };
208
214
  }
209
215
 
@@ -213,16 +219,24 @@ function stepAbove({ model, effort }, usable) {
213
219
  * 2 of 5 at more than twice the price of opus, which finished 5 of 6. So these hold whatever it answers:
214
220
  * - A first attempt starts lower: a worker's never runs on fable while opus is on, and no first attempt runs above high effort.
215
221
  * - A scout's first attempt does not run on haiku while sonnet is on: on the ledger, haiku scouts left 3 of 11 unfinished,
216
- * sonnet and opus ones none of 9 — and haiku caches nothing below 4,096 tokens. It runs on sonnet at low effort instead.
222
+ * sonnet and opus ones none of 9 (measured on Haiku 4.5; not yet on 5.5). It runs on sonnet at low effort instead.
217
223
  * - A retry of a job that failed, or that drew RETRY_IMPORTANT_THRESHOLD Important findings, runs at least one step above it.
218
224
  * - A reviewer pointed at a job runs on at least that job's model, at medium effort or more.
219
225
  * Pure: `retryOf` and `reviews` are the rows (id, model, effort, status, important) of the job retried and the job judged,
220
226
  * or nothing; `usable` is the models that are on, cheapest first. An attempt with no route Sumo knows has nothing to go
221
227
  * above. `policy` says what changed and why, or is null.
222
228
  */
223
- export function routePolicy({ agent, routed, retryOf: prev, reviews: target, usable }) {
229
+ export function routePolicy({ agent, routed, retryOf: prev, reviews: target, usable, floor = null }) {
224
230
  let route = { model: routed.model, effort: routed.effort };
225
231
  const why = [];
232
+ // The user's floor before anything else: a job never starts on a model below it while one at or above it is on.
233
+ if (floor && modelRank(route.model) < modelRank(floor)) {
234
+ const up = usable.find((m) => modelRank(m) >= modelRank(floor));
235
+ if (up) {
236
+ route = { model: up, effort: EFFORTS.includes(route.effort) ? route.effort : 'medium' };
237
+ why.push(`jobs.floor is ${floor}`);
238
+ }
239
+ }
226
240
  if (!prev) {
227
241
  if (agent === 'worker' && route.model === 'fable' && usable.includes('opus')) {
228
242
  route.model = 'opus';
@@ -250,7 +264,7 @@ export function routePolicy({ agent, routed, retryOf: prev, reviews: target, usa
250
264
  route.model = usable.find((m) => modelRank(m) >= modelRank(target.model)) ?? usable.at(-1);
251
265
  why.push(`a reviewer is at least as strong as j${target.id}'s ${target.model}`);
252
266
  }
253
- if (route.model !== 'haiku' && effortRank(route.effort) < effortRank('medium')) {
267
+ if (effortRank(route.effort) < effortRank('medium')) {
254
268
  route.effort = 'medium';
255
269
  why.push('a reviewer runs at medium effort at least');
256
270
  }
@@ -275,7 +289,7 @@ const jobRoute = (db, id) => (id === undefined || id === null ? null : (db.prepa
275
289
  export async function chooseRoute(db, { agent, project, task, title, retryOf, reviews }) {
276
290
  const routed = await askRouter(db, { agent, project, task, title, retryOf });
277
291
  if (!routed.ok) throw new UsageError(`the router failed: ${routed.error} — no job was created`);
278
- const { model, effort, policy } = routePolicy({ agent, routed, retryOf: jobRoute(db, retryOf), reviews: jobRoute(db, reviews), usable: usableModels(db) });
292
+ const { model, effort, policy } = routePolicy({ agent, routed, retryOf: jobRoute(db, retryOf), reviews: jobRoute(db, reviews), usable: usableModels(db), floor: jobFloor(db) });
279
293
  return { model, effort, reason: `router: ${routed.reason}${policy ? `; policy: ${policy}` : ''}`, risky: routed.risky };
280
294
  }
281
295
 
package/src/sandbox.mjs CHANGED
@@ -21,7 +21,7 @@ const SANDBOX_EXEC = '/usr/bin/sandbox-exec';
21
21
  const TOOL_CACHES = ['.npm', 'Library/Caches', '.cache', 'go/pkg', '.cargo/registry', '.cargo/git', 'Library/pnpm', '.bun/install/cache', '.gradle/caches', '.m2/repository'];
22
22
 
23
23
  /** What is printed for a write the sandbox refused — Codex looks for the same two — in any case: Node says `EPERM: operation not permitted`. */
24
- const BLOCKED = /operation not permitted|read-only file system/i;
24
+ const BLOCKED = /operation not permitted|read-only file system|unable to open database file|readonly database/i;
25
25
 
26
26
  /** Why the model's shell cannot be sandboxed here, or null when it can. */
27
27
  export function unsandboxable({ platform = process.platform, exec = SANDBOX_EXEC } = {}) {
@@ -32,7 +32,7 @@ export function unsandboxable({ platform = process.platform, exec = SANDBOX_EXEC
32
32
 
33
33
  const real = (path) => {
34
34
  try {
35
- return realpathSync(path);
35
+ return realpathSync.native(path);
36
36
  } catch {
37
37
  return null;
38
38
  }
@@ -100,10 +100,89 @@ function darwinUserCache() {
100
100
  * `sumo job finish`, which write there), the per-user cache macOS gives compilers, and the tool caches that exist. A
101
101
  * place that does not exist is left out.
102
102
  */
103
- export function writablePlaces(roots, { home = homedir(), tmp = tmpdir(), sumo = paths().home, userCache = darwinUserCache() } = {}) {
103
+ export function writablePlaces(roots, { home = homedir(), tmp = tmpdir(), sumo = paths().home, userCache = darwinUserCache(), opened = [] } = {}) {
104
104
  const places = [];
105
105
  for (const root of roots.map(real).filter(Boolean)) places.push(root, gitCommonDir(root));
106
106
  places.push(real(tmp), real('/private/tmp'), real(sumo), userCache && real(userCache), ...TOOL_CACHES.map((cache) => real(join(home, cache))));
107
+ // What the user opened for the session at the editor's question — a file, or a directory with everything under it — the shell may write too.
108
+ places.push(...[...opened].map(real));
109
+ return [...new Set(places.filter(Boolean))];
110
+ }
111
+
112
+ /**
113
+ * Files that something else reads later, outside the sandbox — the shell at its next start, a tool before it runs, an
114
+ * editor, a commit hook — by name: changed only when the user says so, in the project or anywhere else, and never
115
+ * opened for the session. Claude Code and Codex keep the same names. `sumo`'s own MCP file holds what may run unasked.
116
+ */
117
+ const GUARDED = {
118
+ 'your shell reads it when it starts': ['.zshrc', '.zshenv', '.zprofile', '.zlogin', '.bashrc', '.bash_profile', '.bash_login', '.profile', '.envrc'],
119
+ // Husky's hooks are the directory git's config names (`.husky/_`), kept with git's own; the rest of `.husky` is the project's.
120
+ 'a tool reads it before it runs': ['.npmrc', '.yarnrc', '.yarnrc.yml', 'bunfig.toml', '.pre-commit-config.yaml', 'lefthook.yml', '.mcp.json', '.claude', '.codex', '.agents'],
121
+ 'your editor reads it': ['.vscode', '.idea', '.devcontainer'],
122
+ // Keys and logins other programs trust: a line added to authorized_keys or a profile in .aws outlives every session.
123
+ 'it holds credentials other programs trust': ['.ssh', '.aws', '.gnupg', '.kube', '.docker', '.netrc', '.git-credentials', '.pgpass'],
124
+ };
125
+ /**
126
+ * Names that matter only in the home: a program's own setup, which runs or is read whenever that program starts. In a
127
+ * project a `bin` folder or a `.gitconfig` is the project's own.
128
+ */
129
+ const HOME_GUARDED = {
130
+ 'git reads it, and runs what it names': ['.gitconfig', '.config/git'],
131
+ 'macOS runs it when you log in': ['Library/LaunchAgents'],
132
+ 'a program there runs as a command': ['.local/bin', 'bin'],
133
+ 'a program you use reads it when it starts': ['.config/fish', '.vimrc', '.config/nvim', '.tmux.conf'],
134
+ };
135
+ const whyOf = (lists) => [...Object.entries(lists)].flatMap(([why, names]) => names.map((name) => [name.toLowerCase(), why]));
136
+ const GUARDED_WHY = whyOf(GUARDED);
137
+ const HOME_WHY = [...GUARDED_WHY, ...whyOf(HOME_GUARDED)];
138
+
139
+ /** What sumo keeps for itself, which only sumo writes: its memory and settings, its MCP servers, its own program and model. */
140
+ const SUMO_PRIVATE = ['memory.db', 'memory.db-wal', 'memory.db-shm', 'mcp.json', 'bin', 'models', 'eval.env'];
141
+
142
+ /** The directories on the PATH, absolute: a program put in one runs whenever its name is typed. */
143
+ const pathDirs = (env = process.env) => [...new Set(String(env.PATH ?? '').split(':').filter((d) => d.startsWith('/')).map((d) => resolve(d)))];
144
+
145
+ /**
146
+ * Why a path is changed only when the user says so, or null: it is, or is in, one of the guarded names directly under
147
+ * the project or the home — whichever holds it most closely, so a project kept inside `~/.claude` is its own. A
148
+ * `.vscode` deep in a package is the package's. Any repository's git directory, any folder on the PATH and sumo's own
149
+ * files are guarded wherever they are.
150
+ */
151
+ export function guardedWhy(path, { roots = [], home = homedir(), sumo = paths().home, env = process.env } = {}) {
152
+ // By name in any case: on macOS's disk `.ENVRC` is `.envrc` to whatever opens it.
153
+ const lower = path.toLowerCase();
154
+ for (const place of [sumo, real(sumo)].filter(Boolean)) {
155
+ const name = SUMO_PRIVATE.find((n) => lower === join(place, n).toLowerCase() || lower.startsWith(`${join(place, n).toLowerCase()}/`));
156
+ if (name) return name === 'mcp.json' ? 'it is the MCP allow list, which says what may run unasked' : 'it is sumo\'s own: its memory, settings or program';
157
+ }
158
+ const homes = new Set([home, real(home)].filter(Boolean));
159
+ const bases = [...new Set([...roots, home].flatMap((base) => [base, real(base)]).filter(Boolean))].sort((a, b) => b.length - a.length);
160
+ const base = bases.find((b) => path.startsWith(`${b}/`));
161
+ if (base) {
162
+ const rel = path.slice(base.length + 1).toLowerCase();
163
+ const named = (homes.has(base) ? HOME_WHY : GUARDED_WHY).find(([name]) => rel === name || rel.startsWith(`${name}/`));
164
+ if (named) return named[1];
165
+ }
166
+ // Any repository's git directory, not only the project's: its hooks run outside the sandbox on the next commit there.
167
+ if (lower.split('/').includes('.git')) return 'git runs what is in it, outside the sandbox';
168
+ const dirs = pathDirs(env);
169
+ return dirs.includes(dirname(path)) || dirs.some((d) => real(d) === dirname(path)) ? 'it is on your PATH: a program there runs as a command' : null;
170
+ }
171
+
172
+ /**
173
+ * What the shell may not write inside the places it may: the guarded files that are there, in each root and the home;
174
+ * sumo's own files by name, there or not (`mcp.json` made by the shell would be read as servers allowed to run); and
175
+ * the PATH's folders outside the project. Kept read-only as git's hooks are.
176
+ */
177
+ export function guardedPlaces(roots, { home = homedir(), sumo = paths().home, env = process.env } = {}) {
178
+ const places = [];
179
+ for (const dir of roots) places.push(...Object.values(GUARDED).flat().map((name) => real(join(dir, name))));
180
+ places.push(...[...Object.values(GUARDED), ...Object.values(HOME_GUARDED)].flat().map((name) => real(join(home, name))));
181
+ const own = real(sumo) ?? sumo;
182
+ places.push(...SUMO_PRIVATE.map((name) => join(own, name)));
183
+ // A PATH folder in a project is the project's; one above a project would make all of it read-only.
184
+ const inRoot = (d) => roots.map(real).filter(Boolean).some((r) => d === r || d.startsWith(`${r}/`) || r.startsWith(`${d}/`));
185
+ places.push(...pathDirs(env).map(real).filter((d) => d && !inRoot(d)));
107
186
  return [...new Set(places.filter(Boolean))];
108
187
  }
109
188