sumo-agents 0.4.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 +76 -18
  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 +197 -86
  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 +3 -2
  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 +4 -2
  26. package/src/hooks.mjs +31 -18
  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 +76 -12
  40. package/src/redact.mjs +10 -0
  41. package/src/render.mjs +2 -1
  42. package/src/route.mjs +16 -22
  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 +46 -11
  47. package/src/setup.mjs +423 -78
  48. package/src/text.mjs +100 -1
  49. package/src/tools.mjs +258 -21
  50. package/src/tty.mjs +205 -78
  51. package/src/ui.mjs +869 -293
  52. package/src/verify.mjs +17 -1
package/AGENTS.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # sumo-agents
2
2
  You are the user's single point of contact for all their work on this machine. Their projects live
3
- elsewhere on disk. Memory is a local database behind one command,
3
+ elsewhere on disk. Memory is a local database behind
4
4
  `sumo`; a background process files what the user says, so you don't. The first message of every session
5
5
  is the memory block: preferences, projects, where things were left, open jobs, things to confirm.
6
6
 
@@ -23,8 +23,8 @@ nudge has fired → the `delegate` tool: `scout` looks, `worker` builds, `review
23
23
  run at once — read guides/delegation.md first.
24
24
 
25
25
  ## Coding
26
- - Before changing code, trace how it works now: the smallest complete slice — signature, callers,
27
- callees, types, tests. One grep, not a fan-out.
26
+ - Before changing code, trace the smallest complete slice: signature, callers, callees, types, tests.
27
+ One grep, not a fan-out.
28
28
  - One-sentence change → just make it. Multi-file or unfamiliar → plan first.
29
29
  - Reproduce first (failing test or command), fix, show the same check passing. No passing check → not done.
30
30
  - Smallest patch that fixes the root cause. No unrelated refactors — list what else you notice.
@@ -33,6 +33,8 @@ run at once — read guides/delegation.md first.
33
33
  - Never fake it: no invented APIs, flags or files, no placeholders, no claim a tool result didn't show.
34
34
  Unsure or unfinished → say so.
35
35
  - Two failed attempts at the same fix → stop and rethink from the evidence. No third variation.
36
- - No new dependency. A secret is used from the environment, or loaded with `set -a; source .env; set +a; <cmd>` in one call; never put in a file or printed.
37
- - Output: failures, not whole logs. No preamble, no restating the request. Only you see a command's output (the
38
- screen shows one line): say what the user needs. Edit the lines that change, never a whole file.
36
+ - Never undo changes you did not make; a file changed under you → stop, say so.
37
+ - No new dependency. A secret comes from the environment or `set -a; source .env; set +a; <cmd>` in one
38
+ call; never a file or output.
39
+ - Output: failures, not whole logs. No preamble, no restating the request. Only you see a command's output:
40
+ say what the user needs. Edit the lines that change, never a whole file.
package/CHANGELOG.md ADDED
@@ -0,0 +1,155 @@
1
+ # Changelog
2
+
3
+ What each release changed for you. The commit of each version has the full detail.
4
+
5
+ ## 0.5.0 — 2026-10-28
6
+
7
+ Newest first:
8
+
9
+ ### The chat screen in its own look (Oct 28)
10
+ - **A ledger, not a copy.** Every row of the conversation is named on its left edge in a word — `you`, `sumo`,
11
+ `read`, `edit`, `write`, `run`, `search`, `mcp`, `job`, `report`, `ask`, `error` — and its words start in one
12
+ column. A column beside the name holds the row's state: `✗` failed, `•` at work, `?` waiting on you, `›` picked.
13
+ The marks borrowed from other tools (`⏺`, `⎿`, `✻`, `Bash(…)`, `Update(…)`, a rounded box) are gone.
14
+ - **One colour of its own:** the terminal's cyan, so your theme decides the shade, light or dark. Yellow still asks,
15
+ red fails; everything secondary is faint. Jobs no longer cycle through five colours: their id says who they are.
16
+ - **Lighter.** The header is one row (no block letters); the box you type in is your own row under a faint rule,
17
+ where the message will stand once sent; a question to approve is a yellow `ask` row with a bar beside all it
18
+ covers, not a box. The working line turns a one-cell spinner instead of running a gradient through its words.
19
+ - **Cheaper to draw**, measured in a real terminal at 100x34 over the same 50 steps: 48% fewer bytes written in
20
+ all (473 KB to 250 KB) — a running command 17 KB instead of 49 KB, a streamed reply 12 KB instead of 22 KB, an
21
+ edit 4.5 KB instead of 7.7 KB, the empty window 4.0 KB instead of 5.4 KB. A keystroke is still about 200 bytes.
22
+ - **A question never wipes your scrollback.** A question to approve that is taller than the window — a long command,
23
+ a narrow window — used to make the screen and the terminal's scrollback be wiped and the whole conversation drawn
24
+ again. It now takes the rows the window has left: what would run is shown as far as they go and the rest is
25
+ counted (`… N more characters not shown — n, and ask the model for less`), with its keys always on the screen. The
26
+ call waiting under it is one row while it waits, since the question shows it whole. Checked at 40, 60 and 80
27
+ columns over 282 steps in a real terminal: nothing but Ctrl-L clears the screen.
28
+ - 24 more phrases for the working line in `spinner.txt`, a few from the ring and the savanna (111 in all).
29
+ - The pager (Ctrl-O), `sumo job watch` and a job's open record use the same ledger; the pager folds a long line
30
+ under its own words at the window's width instead of leaving it to come back at the edge. An error no longer says
31
+ "error" twice; the keys in a question are bold; the cap on a long question reads whole at 80 columns.
32
+
33
+ ### What the audits left, finished (Oct 28)
34
+ - **`sumo uninstall`**: shows what it will remove and asks you to type `uninstall` (`--yes` in a script). It copies
35
+ your memory out beside the home first (`--discard-memory` skips it), stops the local model's server, removes the
36
+ `sumo` links that run this home and what setup made there — anything of yours is left and named — and refuses a
37
+ home that is your home folder or above it.
38
+ - **Exit codes a script can act on**: 0 done, 1 not done (not there, not in a state for it, not the asker's to do) or
39
+ failed, 2 the command line was wrong, 4 an Anthropic credential is needed. `sumo help` says so.
40
+ - At a terminal `sumo prime` and `sumo project show` read as text, without the tags written for the model; piped,
41
+ they are unchanged. An open job is said as it is: `not started`, `running`, or `stopped`. A forgotten memory is
42
+ `forgotten`, not `invalid`; adding a registered project with another `--slug` says the name is kept.
43
+ - **The chat screen, finished.** A question says it waits once, in its panel, with its keys at full weight and one
44
+ wording for Esc. An error is marked `✗`, wraps under its own words with the API's reason faint beneath, and an
45
+ unknown 400 is said in words; a "prompt is too long" or `max_tokens` refusal is no longer called a credential
46
+ problem. What is merely not there yet is a note, not red. Files are named from the project, one spelling each.
47
+ `/help` is one line a command (31 rows at 80x24, from 90); commands say what they do for you, `/model` reads like
48
+ the status line and Tab marks the current model; the line still arriving shows no half-made markdown; the empty
49
+ window never clips the logo and suggests what to try; the box stays at the foot after a command answered with a note.
50
+ - `sumo export | head` no longer ends in a stack trace when macOS reports the closed pipe as ENOTCONN.
51
+ - **Memory asks you only what is real.** The local model names a pair of memories by number and sometimes names the
52
+ wrong one — a turn read as a memory, a memory it was never shown. A pair it names is now judged on its own before
53
+ anything is put to you; one judged unrelated is dropped and never asked again. The memory probe: 6 of 6 scenarios
54
+ every run, and no notice that ties an unrelated pair (from up to 3 a run).
55
+ - Search finds Japanese, Chinese and Korean words inside a longer run of text, in memories and in what you typed;
56
+ other languages search exactly as before.
57
+
58
+ ### Two independent audits, fixed (Oct 28)
59
+ - **The chat screen, checked in a real terminal.** A reply whose stream broke and was asked again is drawn once, not
60
+ glued to every failed try; a live area that grows past the foot of the window no longer leaves a stale copy behind;
61
+ the API's own retries are counted on the working line instead of waited on silently, and said once in the scroll.
62
+ - Saying no to a command or a change shows one line — what was declined, and your words — not the paths and the
63
+ instructions the model is given; a run outside the sandbox is asked with what the sandbox refused; one very long
64
+ line of output is cut to a few rows.
65
+ - Plain mode (`chat.screen plain`) is for a screen reader: no logo, no ticking clock, tables read as records and code
66
+ blocks named in words. With `NO_COLOR` the cursor in the box is still drawn, in reverse video.
67
+ - A wrong key on a question explains every key inside its panel; the model's question is asked once; an edit is headed
68
+ in words, not `str_replace`; a declined reply leaves no half sentence; at 80 columns the working line keeps "esc to
69
+ interrupt"; `/new` starts on a clean window; a folder that is not a project says the tools work in scratch, and how
70
+ to make it one; `/` and `@` menus come back once a recalled message is changed.
71
+ - **Nothing lost unasked.** `sumo forget <id> --purge` shows the memory and asks you to type its id; `sumo backup
72
+ restore` over a database that is fine says what each side holds and asks first. With no terminal, both need `--yes`.
73
+ - A purge now reaches every copy on the machine: the weekly backups, the copies made before an upgrade, and a database
74
+ a restore set aside. A restore over a working database keeps it as `memory.db.replaced-<time>`, not "damaged".
75
+ - `sumo setup` under a second home never takes over the `sumo` command of a home that is still there.
76
+ - Your own rule quoted whole ("slate uses pnpm, never npm") is filed as yours, not held as if you had said it the
77
+ other way round; a correction written as "uses bun, not pnpm" is too. A clash pairing the wrong memory, and a
78
+ one-off request guessed as a workflow, are dropped instead of put to you. The memory probe judges a sixth scenario —
79
+ your words are never held as a guess — and holds all six, every run of three.
80
+ - **The command line reads like one tool.** `sumo help` fits 100 columns and ends with the docs and how to report a
81
+ bug; `sumo help <command>` gives that command's every option, explained. `--days=7` and `-n5` work, a misspelt flag
82
+ is answered with the one it meant, and words a command would not use are refused instead of dropped
83
+ (`forget m1 m2` no longer forgets m1 alone). Search says how many more matched than it shows.
84
+ - `--json` on `search`, `show`, `project list` and `job list`: one object, its lists named.
85
+ - `job watch` on a job nobody started says how to start it instead of waiting for ever; the memory page with no
86
+ terminal says it needs one; `sumo mcp` refuses a token given in the clear and a non-web address, says it is
87
+ connecting, and exits 1 when every server failed. Job ids read `j1` everywhere, empty lists say what is true, and a
88
+ memory you type at a terminal is written by you.
89
+ - Ctrl-C during `sumo mcp` takes the server it started down with it. `FORCE_COLOR` turns colour on for sumo's own
90
+ lines too, piped included. A home that is a file, or one sumo may not write, is said as that with the next step —
91
+ doctor reports it as one line instead of crashing — and doctor names `sumo doctor --fix` where that is the fix.
92
+ Turning `shell.sandbox` off says plainly what it means.
93
+
94
+ ### Releases and CI locked down (Oct 28)
95
+ - A publish waits for the maintainer's approval in a `release` environment open only to `main`, and goes to npm by
96
+ trusted publishing with provenance: no npm token exists to steal.
97
+ - Every action is pinned to a commit, no job holds a permission it does not use, no dependency's install script
98
+ runs in CI, and the registry's signatures are checked. CodeQL scans the code and the workflows; Dependabot
99
+ proposes updates a week after they appear. [SECURITY.md](SECURITY.md#releases-and-the-supply-chain) has the table.
100
+
101
+ ### The screen, memory and neat code (Oct 28)
102
+ - The chat redraws only the line that changed: a keystroke writes about 200 bytes instead of the whole window, a
103
+ question waiting holds still, and full-width boxes keep their right edge in every terminal.
104
+ - A rule you say again in other words ("short answers" / "brief replies") is always raised for you to settle.
105
+ - The suite fails on an unused import or an export nothing uses, and on a fast command loading the heavy modules.
106
+ - `sumo config` has 15 settings, down from 22. `chat.screen` (`full`, `still`, `plain`) replaces `chat.motion` and
107
+ `chat.plain`; `model.url`, the model file's whole address, replaces `model.source`, `model.repo` and `model.file`;
108
+ `prime.budget`, `scratch.days`, `jobs.escalate` and `guides.auto` are fixed now. What you had set carries over,
109
+ and an old name says what it became.
110
+
111
+ ### Claude Code login and CI (Oct 28)
112
+ - On a Claude Code login, refusals fall back to another model and `/model` effort changes keep the cache, as on an
113
+ API key (checked live with `probes/oauth-features.mjs`).
114
+ - CI runs the suite on macOS, the platform sumo runs on, with Node 22 and 24, before a version is published.
115
+
116
+ ### Security, speed and polish (Oct 28)
117
+ - **Security:** sumo's own memory, settings and MCP servers are out of the shell's reach. Before, one injected
118
+ command could switch the sandbox off, plant a memory in your name or register an MCP server allowed to run
119
+ anything. A plain `sumo …` command from the model runs as sumo, where what only you control is refused.
120
+ - A project is one folder of work: never `/`, your home or above it. More guarded files: git's own config, login
121
+ items, editor and shell setup, every folder on your PATH; hard links are asked about each time.
122
+ - MCP refuses redirects; a trap learned from a web page or MCP server waits for you, and only you confirm it.
123
+ - Every command starts about 45% faster (`sumo hook prompt` 115 → 62 ms).
124
+ - The screen and the commands read as one product: reads by file name, hints that fit, plain wording in
125
+ `sumo cost`, `sumo memory status` and `sumo doctor`, `sumo config` sorted with did-you-mean.
126
+
127
+ ### One memory pass (Oct 28)
128
+ - **One memory pass** instead of a writer and a tidier: `sumo memory run | status | show`, one `memory.model`
129
+ setting. It files what you say and tidies itself when conversations finish or a week passes.
130
+ - Tidying raises memories that say one thing or disagree, fills in search terms, and keeps project facts fresh.
131
+ Guesses are asked only where they belong; unused traps an agent filed are let go after 45 days.
132
+ - One-off requests ("make the button blue") are not filed as rules; a rule with a condition still is.
133
+ - `probes/memory-quality.mjs` measures it: 3 of 5 scenarios held before these changes, all five after.
134
+
135
+ ### Edits outside the project, the SDK, jobs and doctor (Oct 27)
136
+ - The editor asks before changing a file outside the project — once, the file or its folder for the session, or
137
+ no with your reason — instead of refusing. Files read later (shell rc files, `.envrc`, credentials) are guarded.
138
+ - `@anthropic-ai/sdk` 1.3; Haiku is Haiku 5.5, about ten times cheaper; Sonnet 5.5 cache reads priced right.
139
+ - `/handoff`; jobs compact and go on when a prompt grows too long; a worker's first DONE is answered with a
140
+ numbered checklist; the model is told which files a command changed.
141
+ - `sumo --version`, crash files, `sumo doctor --fix | --report`, a database copy before each migration.
142
+ - Slack and other app-login MCP servers through Claude Code's login (`--from-claude`).
143
+
144
+ ## 0.4.0 — 2026-10-26
145
+ - The chat screen, tested by driving a real terminal: every row inside the window at any width, nothing drawn
146
+ raw, a job told in place under the call that started it, `/context`, `/export`, `/thinking`, `/copy`, `/clear`.
147
+ - `jobs.floor`: the smallest model a job may run on.
148
+
149
+ ## 0.3.0 — 2026-10-26
150
+ - The model's shell runs in a macOS sandbox; worktrees for a second worker; cheaper context (tool output cleared
151
+ later, in larger pieces); budgets for jobs and the chat; `sumo cost` with cache rewrites; checked work (the
152
+ first DONE answered, flaky checks run again); the coding eval with `--hard`.
153
+
154
+ ## 0.2.0 — 2026-10-13
155
+ - The chat asks before it builds, and memory keeps less that was never said.
package/README.md CHANGED
@@ -22,7 +22,7 @@ your environment.
22
22
 
23
23
  ```sh
24
24
  npm install -g sumo-agents
25
- sumo setup # creates ~/.sumo-agents and downloads the 2.5 GB router model
25
+ sumo setup # creates ~/.sumo-agents and downloads the 2.5 GB local model (routes jobs, runs the memory pass)
26
26
  sumo doctor # every line should say ok
27
27
  sumo chat
28
28
  ```
@@ -35,13 +35,24 @@ are covered in [Install](https://github.com/sumododda/sumo-agents/wiki/Install).
35
35
  - Just talk. Name the project you mean; the first time, Sumo confirms its path and registers it. Started inside a
36
36
  registered project, the chat works there from the start.
37
37
  - Say how you like things done. "Always run the linter before you commit" is remembered in your words and
38
- loaded next time.
38
+ loaded next time. What Sumo only guessed you meant is asked in sessions about that project, for two weeks;
39
+ after that it waits on the memory page (`/memory`).
40
+ - Memory looks after itself, in one background pass on the local model. After a turn it files what you said;
41
+ once three conversations have finished, or a week has passed, it also reads them side by side and raises two
42
+ memories that say one thing, or cannot both be true, for you to settle. A project's facts are read again when
43
+ its files change. A trap an agent filed that nobody was shown in 45 days is let go, history kept. What a job
44
+ learned while reading the web or an MCP server waits for you to confirm. `sumo memory status` says how it is
45
+ doing; `sumo memory run --tidy` tidies now.
39
46
  - `/fix`, `/feature` and `/review` load a short written procedure for that kind of work. They also load on
40
47
  their own when your message asks for one.
41
48
  - Big work is delegated without being asked. A row for the job appears under the box, you keep talking,
42
49
  and its report comes back into the conversation.
43
- - `/new` starts a fresh session, and a new task deserves one. `/resume` picks an old one up. `/help` lists
50
+ - `/new` starts a fresh session, and a new task deserves one. `/handoff` has the model write a hand-off of
51
+ the piece in hand first, and the fresh session starts from it. `/resume` picks an old one up. `/help` lists
44
52
  the rest, and `?` on an empty box shows the keys you reach for most.
53
+ - The screen reads like a ledger: each row is named on its left edge in a word — `you`, `read`, `edit`, `run`,
54
+ `sumo`, `ask` — so a turn is scanned down one column. Colour only repeats what the words say: your theme's cyan
55
+ is Sumo's own, yellow asks, red fails.
45
56
  - Ctrl-R searches what you sent before. `/context` shows how full the context is and what the session has cost.
46
57
  `/export` writes the conversation to a Markdown file.
47
58
 
@@ -50,42 +61,84 @@ are covered in [Install](https://github.com/sumododda/sumo-agents/wiki/Install).
50
61
  - Destructive commands (`rm -rf ~`, `git reset --hard`, dropping a table) and commands that print secrets
51
62
  are refused in code before they run. `! <command>` runs one yourself.
52
63
  - On macOS the agent's shell runs in a sandbox: it writes only in the project, the temporary folders, Sumo's
53
- home and the tool caches, never in git's hooks or config. A write it blocks is put to you once to run
54
- outside it. `sumo config shell.network off` also keeps it off the network.
64
+ home and the tool caches — never in git's hooks or config, nor Sumo's own memory, settings or MCP servers. A
65
+ plain `sumo …` command it runs is run as Sumo itself, where what only you may change is refused. A write the
66
+ sandbox blocks is put to you once to run outside it. `sumo config shell.network off` keeps it off the network.
67
+ - An MCP server that takes only a registered app's login, as Slack's official one does, is reached through
68
+ Claude Code's: `claude mcp add --transport http --scope user slack https://mcp.slack.com/mcp`, `claude mcp login slack`,
69
+ then `sumo mcp add slack --url https://mcp.slack.com/mcp --from-claude`. Sumo borrows the token and never refreshes it.
70
+ On macOS the token is read from the keychain: when macOS asks, choose Always Allow.
71
+ - The editor reads any file but changes only the project's. A change to one outside it — a config file in
72
+ your home, say — is put to you with the change: once, or that file or its directory for the rest of the
73
+ session, where the shell may then write too. The home itself is never opened that way. A file something
74
+ else reads later — your shell's rc files, `.envrc`, `.npmrc`, `.vscode`, `.mcp.json`, Sumo's own MCP file —
75
+ is changed only when you say so, each time, under any spelling of its name.
76
+ - Any of these questions can be refused with your reason: `r`, type why, Enter. The model reads it as what to
77
+ do instead. Questions from several jobs queue, and the one shown says how many wait behind it.
55
78
  - The agent's shell gets your whole environment except the Anthropic credential. It never waits on a prompt,
56
79
  stops a command silent for 2 minutes (`timeout 600 <cmd>` asks for longer), and runs a command ending in
57
80
  `&` in the background with its own log.
58
- - A worker's first DONE is answered with its task beside its change to check; the second runs your checks.
81
+ - A worker's first DONE is answered with its task as a numbered checklist beside its change, one answer per
82
+ item; the second runs your checks.
59
83
  A failed first attempt is retried once on the next model up, and risky work is reviewed, without asking.
60
84
  A second worker on a git project works in a worktree of its own.
61
- - A job's run stops at $10 or 60 minutes (`jobs.budget`, `jobs.minutes`). `sumo cost` shows where the money went.
85
+ - A job's run stops at $10 or 60 minutes (`jobs.budget`, `jobs.minutes`). `sumo cost` shows where the money went,
86
+ and why the cache was written again when it was.
62
87
  - `/undo` puts back the files the last chat turn changed with the editor.
63
88
  - Only your words become memory. Web pages, files and tool output are never filed as yours.
64
89
  - The local model, Qwen3-4B through llama.cpp, routes jobs and writes memory for $0 and sleeps when idle.
90
+ - A crash is written, redacted, to `~/.sumo-agents/logs/crash-*.log`. `sumo doctor --report` prints everything a
91
+ bug report needs, redacted, and sends nothing; the logs that hold what you said are counted there, not quoted.
92
+ `sumo doctor --fix` makes the home's files private again.
93
+ - The database is copied beside itself before an upgrade migrates it (`memory.db.pre-v<N>.bak`, the last three),
94
+ and weekly into `~/.sumo-agents/backups`. A database that will not open is said with the newest copy:
95
+ `sumo backup restore` puts it back (or `sumo backup restore <file>`), keeping the damaged one aside. Over a
96
+ database that is fine, it says what would be lost and asks first (`--yes` in a script).
97
+ - `sumo forget <id> --purge` erases a memory for good, from every backup and set-aside copy too; it shows the memory
98
+ and asks you to type its id (`--yes` in a script).
99
+ - `NO_COLOR=1` turns colour off everywhere, the chat screen included; the cursor in the box and the changed part of an
100
+ edit stay in reverse video, which is not colour. `sumo --version` says which sumo this is.
65
101
 
66
102
  ## Configuration
67
103
 
68
- `sumo config <key> <value>` sets one; `sumo config` lists them. The ones most people touch:
104
+ `sumo config <key> <value>` sets one; `sumo config` lists all fifteen, in this order:
69
105
 
70
106
  | Key | Default | What it does |
71
107
  |---|---|---|
72
- | `chat.model` | `opus` | What the chat runs on. `auto` lets the local router pick per turn. |
73
- | `chat.effort` | `medium` | Effort when the chat model is fixed. |
74
108
  | `chat.budget` | `5` | Dollars a chat session costs before the screen says so; `0` never. |
75
- | `chat.motion` | `on` | `off` keeps the working line still: no colours flowing through it. |
76
- | `projects.home` | `~` | Where new projects are created. |
109
+ | `chat.effort` | `medium` | Effort when the chat model is fixed. |
110
+ | `chat.model` | `opus` | What the chat runs on. `auto` lets the local router pick per turn. |
111
+ | `chat.notify` | `on` | `off` stops the bell and the notification when a long turn ends behind another window. |
112
+ | `chat.screen` | `full` | `still` keeps the working line's spinner still. `plain` draws the chat for a screen reader: words, not pictures (no logo), ASCII marks (`x` a failure, `*` at work, `>` your prompt), no rule over the box or bar beside a question, and nothing that moves or ticks. |
113
+ | `jobs.advisor` | `off` | `on` lets a job ask the next model up for advice. |
77
114
  | `jobs.budget` | `10` | Dollars one job may spend before it is stopped; `0` for no cap. |
78
115
  | `jobs.floor` | `haiku` | The smallest model a job may run on: `sonnet` keeps every job off Haiku, `opus` puts them all on Opus or Fable. |
79
116
  | `jobs.minutes` | `60` | Minutes one job may run before it is stopped; `0` for no limit. |
80
- | `jobs.escalate` | `on` | A worker's failed first attempt is retried once on the next model up. |
81
117
  | `jobs.review` | `risky` | Which verified work gets a reviewer without asking: `risky`, `all` or `off`. |
82
- | `jobs.advisor` | `off` | `on` lets a job ask the next model up for advice. |
83
- | `shell.sandbox` | `on` | The agent's shell in the macOS sandbox. Read when a chat or job starts. |
118
+ | `memory.model` | `local` | What the memory pass runs on: `local`, a model name, or `off` (the chat then saves what lasts itself). |
119
+ | `model.url` | `https://huggingface.co/Qwen/Qwen3-4B-GGUF/resolve/main/Qwen3-4B-Q4_K_M.gguf` | The local model's download address, a `.gguf` file. Run `sumo setup` after changing it; `sumo setup --model-source <base>` puts a mirror in front of the same file. |
120
+ | `projects.home` | `~` | Where new projects are created. |
84
121
  | `shell.network` | `on` | `off` keeps the sandboxed shell to this machine. |
122
+ | `shell.sandbox` | `on` | The agent's shell in the macOS sandbox. Read when a chat or job starts. |
85
123
 
86
- The full list, the API model switches and the environment variables are in
124
+ The API model switches and the environment variables are in
87
125
  [Install](https://github.com/sumododda/sumo-agents/wiki/Install#configuration).
88
126
 
127
+ ## Uninstall
128
+
129
+ ```sh
130
+ sumo uninstall # shows what it will remove and asks; --yes in a script
131
+ npm uninstall -g sumo-agents
132
+ ```
133
+
134
+ `sumo uninstall` copies your memory out first, beside `~/.sumo-agents` (after a reinstall,
135
+ `sumo backup restore <that file> --yes` puts it back; `--discard-memory` skips the copy). Then it stops the local
136
+ model's server, removes the `sumo` links on your PATH that run this sumo, and removes what `sumo setup` made in
137
+ `~/.sumo-agents` — anything else you put there is left, and named. It refuses a home that is your home folder or above.
138
+
139
+ Sumo writes nothing else: no shell profile, no other tool's settings. If you added `sumo hook` to a harness's hook
140
+ configuration yourself, remove those lines there. llama.cpp stays installed: `brew uninstall llama.cpp` if you want.
141
+
89
142
  ## Learn more
90
143
 
91
144
  The [wiki](https://github.com/sumododda/sumo-agents/wiki) has the detail:
@@ -97,6 +150,9 @@ The [wiki](https://github.com/sumododda/sumo-agents/wiki) has the detail:
97
150
  - [Safety](https://github.com/sumododda/sumo-agents/wiki/Safety): what is enforced by code and what is only asked
98
151
  - [How it works](https://github.com/sumododda/sumo-agents/wiki/How-it-works): a turn, the local model, costs
99
152
 
153
+ What each release changed is in [CHANGELOG.md](CHANGELOG.md); what is enforced, its limits and how to report a
154
+ vulnerability are in [SECURITY.md](SECURITY.md).
155
+
100
156
  ## Development
101
157
 
102
158
  ```sh
@@ -110,8 +166,10 @@ npm run build:bin # optional: a standalone binary in dist/sumo-agents/
110
166
  `node probes/coding-eval.mjs --route sonnet/medium` runs real jobs on small tasks and scores them with hidden
111
167
  tests; `--hard` runs the harder set, `--no-guides` and `--advisor` change one thing at a time. It costs money.
112
168
 
113
- A release is a commit on `main` that raises the version in `package.json`. The workflow runs the suite
114
- and publishes it to npm. Probes, the coding eval and the repository layout are in
169
+ A release is a commit on `main` that raises the version in `package.json`. The workflow runs the suite on
170
+ macOS, the platform sumo runs on, with Node 22 and 24; when both pass, the publish waits in the `release` environment for the
171
+ maintainer's approval, then goes to npm with provenance and no stored token. How CI is locked down is in
172
+ [SECURITY.md](SECURITY.md#releases-and-the-supply-chain). Probes, the coding eval and the repository layout are in
115
173
  [Development](https://github.com/sumododda/sumo-agents/wiki/Development).
116
174
 
117
175
  MIT licensed.
package/bin/sumo.mjs CHANGED
@@ -1,6 +1,11 @@
1
1
  #!/usr/bin/env node
2
2
  import tls from 'node:tls';
3
3
 
4
+ // NO_COLOR (no-color.org) is honoured by the whole screen, not only by sumo's own lines: chalk, which ink draws with,
5
+ // reads FORCE_COLOR once, when it loads, and ignores NO_COLOR. Said to it here, before anything loads it. Empty is
6
+ // not set, and a FORCE_COLOR the user gave wins.
7
+ if (process.env.NO_COLOR && !process.env.FORCE_COLOR) process.env.FORCE_COLOR = '0';
8
+
4
9
  // Node reads the environment setting at startup. Add system CAs to this process
5
10
  // before loading the CLI, and enable the startup setting for its descendants.
6
11
  // Bun has no setDefaultCACertificates: the binary it builds is started with
@@ -23,11 +28,17 @@ process.emitWarning = (warning, ...rest) => {
23
28
  };
24
29
 
25
30
  // A reader that stops early (`sumo export | head`) closes the pipe: that is the
26
- // end of the output, not a crash with a stack trace.
31
+ // end of the output, not a crash with a stack trace. macOS says it as EPIPE, or
32
+ // as ENOTCONN when the reader is gone before the write lands.
27
33
  process.stdout.on('error', (error) => {
28
- if (error.code !== 'EPIPE') throw error;
34
+ if (error.code !== 'EPIPE' && error.code !== 'ENOTCONN') throw error;
29
35
  process.exit(0);
30
36
  });
31
37
 
38
+ // A crash is written down — redacted, in logs/ — and otherwise ends as Node ends it.
39
+ const { watchForCrashes } = await import('../src/logs.mjs');
40
+ const { VERSION } = await import('../src/paths.mjs');
41
+ watchForCrashes(VERSION);
42
+
32
43
  const { main } = await import('../src/cli.mjs');
33
44
  process.exitCode = await main(process.argv.slice(2));
package/guides/feature.md CHANGED
@@ -11,4 +11,5 @@ when: add, build, implement, feature, extend, design, rewrite, approach, archite
11
11
  6. Build until they pass, without touching them. No code for cases that cannot happen; nothing the outcome did not name unless you can say what breaks without it.
12
12
  7. Name one wrong implementation that would still pass. If there is one, add the test that kills it.
13
13
  8. The project's own checks. Lint failure → the tool's safe autofix first, then the code — never an ignore.
14
- 9. Delete what the change orphaned. Update only the docs whose truth changed; search for the old value.
14
+ 9. Output a person reads — a screen, a message, a CLI's text → run it as they would and quote what it printed.
15
+ 10. Delete what the change orphaned. Update only the docs whose truth changed; search for the old value.
package/guides/memory.md CHANGED
@@ -1,7 +1,8 @@
1
1
  # Memory
2
2
 
3
- Everything the user has told any session on this machine, behind `sumo`. You read it; a background
4
- writer (a cheap model, checked by code) files what the user says after each turn.
3
+ Everything the user has told any session on this machine, behind `sumo`. You read it; one background
4
+ memory pass (a cheap model, checked by code) files what the user says after each turn and tidies memory
5
+ when conversations finish.
5
6
 
6
7
  **Reading**
7
8
  - `sumo search "<words>" [--project <slug>]` — ranked one-line results. Scope is global plus the named
@@ -19,5 +20,6 @@ writer (a cheap model, checked by code) files what the user says after each turn
19
20
  session-start block. Ask the user in one line, then `sumo confirm <id>` or `sumo reject <id>`.
20
21
  The user can do the same, and edit or forget, on a page: `/memory` in the chat, or `sumo memory`.
21
22
 
22
- **If the block warns that the writer is failing:** tell the user, run `sumo scribe status`. While
23
- `sumo config scribe.model` is `off`, save durable statements yourself with `sumo add` as they are made.
23
+ **If the block warns that the memory pass is failing:** tell the user, run `sumo memory status`. While
24
+ `sumo config memory.model` is `off`, save durable statements yourself with `sumo add` as they are made.
25
+ Asked to tidy memory: `sumo memory run --tidy`, then say what it raised.
@@ -22,6 +22,6 @@ A project is a directory somewhere on this machine, registered once.
22
22
 
23
23
  **No project** → scratch (`sumo project show scratch`): one folder per chore, named `<date>-<what it is>`. With no
24
24
  project named the tools start there; from inside a project, hand the chore to a job with project `scratch`. A folder
25
- nothing is written in for `sumo config scratch.days` days is deleted — worth keeping → move it out, `sumo project add`.
25
+ nothing is written in for 14 days is deleted — worth keeping → move it out, `sumo project add`.
26
26
 
27
27
  `sumo project alias <slug> <name>` adds a name · `sumo project archive <slug>` retires one (memories kept).
package/guides/review.md CHANGED
@@ -4,7 +4,7 @@ when: review, audit, "look over", critique
4
4
  # Review
5
5
 
6
6
  1. Judge the change, not its author's account of it. A report is claims; a stated reason never makes a finding smaller.
7
- 2. First — does it do what was asked? Missing: asked for, not there. Extra: there, not asked for. Misunderstood: the wrong thing, built well. Check every requirement and every named edge case against the change.
7
+ 2. First — does it do what was asked? Missing: asked for, not there. Extra: there, not asked for. Misunderstood: the wrong thing, built well. The brief lists what was asked by number; give a verdict on each number, with what in the change shows it, and check every named edge case against the change.
8
8
  3. Then — can it be trusted? Wrong behaviour, a regression, damaged data or a race, a broken interface, a check that was weakened, changed behaviour with no test, tests that assert nothing.
9
9
  4. Read the change, not the codebase. Look outside it only for a risk you can name — callers of a changed signature, users of changed shared state — one look per risk, and say what you looked at.
10
10
  5. The change touches sign-in or permissions, input parsing, SQL, file paths, shell commands, secrets or deserialising → follow what an outsider controls to where it lands. Never call code secure; say what you could not see.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "sumo-agents",
3
- "version": "0.4.0",
3
+ "version": "0.5.0",
4
4
  "description": "One repo you talk to: a local memory engine and working process for coding agents.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -26,6 +26,7 @@
26
26
  "guides/",
27
27
  "prompts/",
28
28
  "AGENTS.md",
29
+ "CHANGELOG.md",
29
30
  "logo.txt",
30
31
  "spinner.txt"
31
32
  ],
@@ -37,8 +38,8 @@
37
38
  "build:bin": "node scripts/build-bin.mjs"
38
39
  },
39
40
  "dependencies": {
40
- "@anthropic-ai/sdk": "^0.131.0",
41
- "ink": "^7.1.1",
42
- "react": "^19.3.0"
41
+ "@anthropic-ai/sdk": "^1.3.0",
42
+ "ink": "^8.0.0",
43
+ "react": "^19.3.1"
43
44
  }
44
45
  }
package/prompts/dream.md CHANGED
@@ -4,6 +4,7 @@ Each conversation was already filed as it happened. Your job is only what become
4
4
 
5
5
  - add / supersede — a preference, rule, decision or fact the user stated that is missing from what is remembered, or that replaces one of those memories (`old` = its number). Supply `type`, `scope`, `topic`, `body`, `turn` and `quote`. Give the N from [tN] and an exact run of words from that turn; for an inferred pattern the user never said out loud, use null for both `turn` and `quote`. Such a guess will be put to the user as a question.
6
6
  - contradiction — two remembered items that cannot both be true: `ids` and a short `note` saying why. Never pick the winner.
7
+ - same — two remembered items that say one thing in different words ("short answers" / "brief replies"): `ids` and a short `note`. Never merge them yourself; never add a third.
7
8
  - procedure — a routine of several steps the user walked the assistant through more than once: `scope`, `title`, `cue` (what the user says to start it) and `body` (numbered steps).
8
9
  - gotcha, checkpoint — only when one is clearly missing.
9
10
 
@@ -11,3 +12,8 @@ Write every `body` as one plain standing sentence. Scope: `project:<name>` when
11
12
  `keys`: up to 6 search terms a memory is about that its `body` does not use (a rule about eslint: lint, linter), or [].
12
13
 
13
14
  Be conservative: a wrong memory costs more than a missing one. Most passes change nothing. Then return {"ops": []}.
15
+
16
+ Two smaller tasks come without conversations, under their own heading; answer only the one asked:
17
+ - "Pairs to judge": for each [pN], `label` how memories A and B relate — `same` (they say one thing in other words), `replaces` (the same matter, and one changes it: another value, tool, place or rule), `conflict` (they cannot both be true), or `unrelated` (they only share words, or both hold). When unsure: `unrelated`.
18
+ - "Search terms": for each [mN], a `topic` (one lowercase word: git, testing, style, writing, tooling, deploy…) and `keys` as above.
19
+ - "Rules said twice": for each rule checked that says what another rule in the list says, in other words ("I prefer short answers" / "keep your replies brief"), one `{ rule, same_as }` with their numbers. Two rules about different things, or that differ in a value, are not the same. When unsure, leave it out; usually the list is empty.
package/spinner.txt CHANGED
@@ -87,4 +87,28 @@ Assembling a solution from reputable spare parts
87
87
  Testing the theory before it escapes
88
88
  Persuading the app to behave in public
89
89
  Finding the exact moment it got weird
90
- Attempting to leave no trace except a commit
90
+ Attempting to leave no trace except a commit
91
+ Stomping the ring before the bout
92
+ Throwing salt for a clean match
93
+ Holding the stance
94
+ Pushing the bug out of the ring
95
+ Bowing to the stack trace
96
+ Tightening the mawashi
97
+ Stalking the bug through the tall grass
98
+ Waking the lion, gently
99
+ Roaring quietly at the build
100
+ Grooming the codebase’s mane
101
+ Pretending to nap, actually thinking
102
+ Counting the off-by-ones
103
+ Asking the linter for a second opinion
104
+ Rehearsing the commit message
105
+ Untangling the import graph
106
+ Checking the tests test something
107
+ Holding a short meeting with the call stack
108
+ Sorting the facts from the vibes
109
+ Proofreading the regex
110
+ Herding the async functions
111
+ Looking under the abstraction
112
+ Measuring twice, editing once
113
+ Making the warnings feel heard
114
+ Sweeping dead code under a better rug