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/logs.mjs ADDED
@@ -0,0 +1,165 @@
1
+ import { appendFileSync, chmodSync, copyFileSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, statSync, truncateSync, writeFileSync } from 'node:fs';
2
+ import { join } from 'node:path';
3
+ import { paths } from './paths.mjs';
4
+ import { redact } from './redact.mjs';
5
+
6
+ /**
7
+ * Sumo's own logs, in ~/.sumo-agents/logs: private like everything else in the home, and never growing without end.
8
+ * A log past LOG_ROTATE_BYTES is moved aside to `<name>.1` (one older generation kept) before the next line is
9
+ * written, so the newest lines are always in the file of that name and a log costs at most twice the limit.
10
+ */
11
+ export const LOG_ROTATE_BYTES = 1024 * 1024;
12
+ /** How many crash files are kept: the newest. */
13
+ const CRASHES_KEPT = 10;
14
+
15
+ /** A log past the limit, moved aside. Nothing there yet, or a file that cannot be moved, is left as it is: a log never stops the work. */
16
+ export function rotate(file, limit = LOG_ROTATE_BYTES) {
17
+ try {
18
+ if (statSync(file).size > limit) renameSync(file, `${file}.1`);
19
+ } catch {
20
+ // Not there yet, or not ours to move.
21
+ }
22
+ }
23
+
24
+ /** The logs this process has made sure are private: looked at once each, on the first line written. */
25
+ const madePrivate = new Set();
26
+
27
+ /**
28
+ * One or more lines added to a log of the home: made private when it is made, moved aside when it has grown too big.
29
+ * A mode is given only to a file being made, so a log from before logs were private is made private here, once.
30
+ */
31
+ export function appendLog(name, text) {
32
+ const dir = paths().logs;
33
+ mkdirSync(dir, { recursive: true, mode: 0o700 });
34
+ const file = join(dir, name);
35
+ rotate(file);
36
+ if (!madePrivate.has(file)) {
37
+ madePrivate.add(file);
38
+ try {
39
+ if (statSync(file).mode & 0o077) chmodSync(file, 0o600);
40
+ } catch {
41
+ // Not there yet: made private below, when it is made.
42
+ }
43
+ }
44
+ appendFileSync(file, text, { mode: 0o600 });
45
+ }
46
+
47
+ /**
48
+ * A log a long-lived process still holds open, kept in bounds where it lies: past the limit its lines are copied aside
49
+ * to `<name>.1` and the file emptied in place, so the writer — appending — carries on at its new start. A rename would
50
+ * leave the writer filling the moved file until it restarts.
51
+ */
52
+ export function trimLog(name, limit = LOG_ROTATE_BYTES) {
53
+ const file = join(paths().logs, name);
54
+ try {
55
+ if (statSync(file).size <= limit) return;
56
+ copyFileSync(file, `${file}.1`);
57
+ truncateSync(file, 0);
58
+ } catch {
59
+ // Not there, or not ours to trim: a log never stops the work.
60
+ }
61
+ }
62
+
63
+ /** A log opened for a child process to write to (llama-server's), moved aside first if it has grown too big. */
64
+ export function openLog(name) {
65
+ const dir = paths().logs;
66
+ mkdirSync(dir, { recursive: true, mode: 0o700 });
67
+ const file = join(dir, name);
68
+ rotate(file);
69
+ return openSync(file, 'a', 0o600);
70
+ }
71
+
72
+ const CRASH = /^crash-.+\.log$/;
73
+
74
+ /** The crash files there are, newest first, by their names, which are the times they were written. */
75
+ export function crashFiles() {
76
+ try {
77
+ return readdirSync(paths().logs).filter((name) => CRASH.test(name)).sort().reverse().map((name) => join(paths().logs, name));
78
+ } catch {
79
+ return [];
80
+ }
81
+ }
82
+
83
+ /** The newest crash file written since `since` (a Date), with when and the line that says what failed; null when there is none. */
84
+ export function latestCrash(since) {
85
+ const [file] = crashFiles();
86
+ if (!file) return null;
87
+ const at = statSync(file).mtime;
88
+ if (at < since) return null;
89
+ const said = readFileSync(file, 'utf8').split('\n').find((line) => line.startsWith('error: '))?.slice('error: '.length) ?? 'see the file';
90
+ return { file, at, said };
91
+ }
92
+
93
+ /**
94
+ * What a crash leaves behind: the version, the runtime, the command and the stack, every part redacted — an argument or
95
+ * a message may hold a token — in a file only its owner can read. Returns the file, or null when even that failed: a
96
+ * crash report must never be a second crash.
97
+ */
98
+ /** The line a crash file names its command with: the command, and only how many words came after it. */
99
+ function commandOf(args) {
100
+ const [command = '(none)', ...rest] = args;
101
+ const name = /^[a-z][a-z-]*$/.test(command) ? command : '(not a command)';
102
+ return `command: ${name}${rest.length > 0 ? ` (${rest.length} more argument${rest.length === 1 ? '' : 's'}, not kept)` : ''}`;
103
+ }
104
+
105
+ function writeCrash(error, origin, { version = '', argv = process.argv, now = new Date() } = {}) {
106
+ try {
107
+ const dir = paths().logs;
108
+ mkdirSync(dir, { recursive: true, mode: 0o700 });
109
+ const file = join(dir, `crash-${now.toISOString().replace(/[:.]/g, '-')}.log`);
110
+ const stack = error instanceof Error ? (error.stack ?? `${error.name}: ${error.message}`) : String(error);
111
+ const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
112
+ const body = [
113
+ `sumo ${version || 'unknown'} crashed (${origin})`,
114
+ `at: ${now.toISOString()}`,
115
+ `node: ${process.versions.bun ? `bun ${process.versions.bun}` : process.versions.node} · ${process.platform} ${process.arch}`,
116
+ // The command, never what was typed after it: a search, a memory or a message is the user's words, not a bug report's.
117
+ commandOf(argv.slice(2)),
118
+ `error: ${message.split('\n')[0]}`,
119
+ '',
120
+ stack,
121
+ '',
122
+ ].join('\n');
123
+ writeFileSync(file, redact(body).text, { mode: 0o600, flag: 'wx' });
124
+ for (const old of crashFiles().slice(CRASHES_KEPT)) rmSync(old, { force: true });
125
+ return file;
126
+ } catch {
127
+ return null;
128
+ }
129
+ }
130
+
131
+ /**
132
+ * Crashes written down as they happen, the process otherwise left to end as Node ends it: the monitor runs before
133
+ * Node's own handling and changes none of it — the stack still goes to stderr, the exit code is still 1, and the chat
134
+ * screen's own exit hooks still hand the terminal back. A rejection nobody handled reaches it as an uncaught exception.
135
+ */
136
+ export function watchForCrashes(version) {
137
+ process.on('uncaughtExceptionMonitor', (error, origin) => {
138
+ const file = writeCrash(error, origin, { version });
139
+ if (file) process.stderr.write(`sumo: crashed — written to ${file} (sumo doctor --report bundles it)\n`);
140
+ });
141
+ }
142
+
143
+ /** The last `count` lines of a file, redacted; empty when it cannot be read. */
144
+ export function tailOf(file, count = 50) {
145
+ try {
146
+ const lines = readFileSync(file, 'utf8').split('\n');
147
+ if (lines.at(-1) === '') lines.pop();
148
+ return redact(lines.slice(-count).join('\n')).text;
149
+ } catch {
150
+ return '';
151
+ }
152
+ }
153
+
154
+ /** The logs a report shows: the files directly in the logs folder that are not crash files, oldest generation last. */
155
+ export function logFiles() {
156
+ try {
157
+ const dir = paths().logs;
158
+ return readdirSync(dir)
159
+ .filter((name) => !CRASH.test(name) && existsSync(join(dir, name)) && statSync(join(dir, name)).isFile())
160
+ .sort()
161
+ .map((name) => join(dir, name));
162
+ } catch {
163
+ return [];
164
+ }
165
+ }
package/src/loop.mjs CHANGED
@@ -1,23 +1,28 @@
1
- import Anthropic from '@anthropic-ai/sdk';
2
1
  import { existsSync, readFileSync, rmSync } from 'node:fs';
3
2
  import { join, resolve } from 'node:path';
4
3
  import { ADVISOR_BETA, ADVISOR_SPENT, ADVISOR_SPENT_AT, ADVISOR_STOP_AT, advisorIn, advisorLine, advisorOf, advisorResult, advisorRuns, advisorTool, isAdvisorCall, isAdvisorResult } from './advisor.mjs';
5
- import { anthropicClient, authenticatedRequest, resolveAnthropicCredential } from './auth.mjs';
4
+ import { anthropicClient, authenticatedRequest, FALLBACK_BETA, loadSdk, resolveAnthropicCredential } from './auth.mjs';
6
5
  import { MODEL_IDS, modelId, MODELS, usableModels } from './catalog.mjs';
7
6
  import { getMeta, tx } from './db.mjs';
8
7
  import { handleEvent } from './hooks.mjs';
9
- import { brief, getJob, planOf, readState, runLockFile, settle, takeInbox, toldToClose, treeOf } from './jobs.mjs';
8
+ import { brief, getJob, noteOutsideRead, planOf, readState, runLockFile, settle, takeInbox, toldToClose, treeOf } from './jobs.mjs';
10
9
  import { isJobTool, jobTools, runJobTool } from './jobtools.mjs';
11
10
  import { takeLock } from './lock.mjs';
12
11
  import { DECLINED, gateMcp, isMcpTool, mcpReady, runMcpTool, TOOL_SEARCH } from './mcp.mjs';
13
12
  import { UsageError } from './memory.mjs';
13
+ import { noteRewrite, prefixOf } from './cost.mjs';
14
14
  import { callLocalModel, costOf, logRun, usageOf } from './model.mjs';
15
15
  import { paths, REPO_ROOT } from './paths.mjs';
16
16
  import { getProject } from './projects.mjs';
17
+ import { noteSessionOutside } from './sessions.mjs';
17
18
  import { CONFIG_DEFAULTS } from './setup.mjs';
18
19
  import { ASK_TOOL, BASH_TOOL, childEnv, EDITOR_TOOL, INTERRUPTED, killGroup, runTool } from './tools.mjs';
19
20
  import { changesSince, diffStat, verdictLines } from './verify.mjs';
20
- import { isWebCall, isWebResult, WEB_TOOLS, webResult } from './web.mjs';
21
+ import { isWebCall, isWebResult, isWebTool, WEB_TOOLS, webResult } from './web.mjs';
22
+
23
+ // The loop is what makes requests: whatever imports it is about to, so the SDK is loaded with it (auth.mjs loads it
24
+ // for no one else). Its error classes are what a failed request is told apart by.
25
+ const Anthropic = await loadSdk();
21
26
 
22
27
  /**
23
28
  * The loop every conversation runs in: one request, the policy pipeline over
@@ -28,7 +33,7 @@ import { isWebCall, isWebResult, WEB_TOOLS, webResult } from './web.mjs';
28
33
  */
29
34
 
30
35
  const MAX_TURNS = 150;
31
- /** Every model but haiku always thinks, and the thinking counts toward this: it holds a long turn's thinking and its reply. */
36
+ /** Every model always thinks, and the thinking counts toward this: it holds a long turn's thinking and its reply. */
32
37
  const MAX_OUTPUT_TOKENS = 64_000;
33
38
  const REQUEST_TIMEOUT_MS = 600_000;
34
39
  const BETAS = ['context-management-2025-06-27'];
@@ -36,10 +41,12 @@ const BETAS = ['context-management-2025-06-27'];
36
41
  const CUT_OFF = 'not run: the reply was cut off before this call was complete';
37
42
  /**
38
43
  * A request sent again after the API or the connection gave way, not the request: how many times, and the wait between
39
- * tries, doubling from the base to the cap. The SDK itself tries twice more only before the first byte; a stream that
40
- * breaks half-way, or an overload it has given up on, lands here, and a nine-minute job must not die of one 529.
44
+ * tries, doubling from the base to the cap. Every try is the loop's — the client's own would be waited on with nothing
45
+ * said, two under each of these — so each is counted down where the work shows, and a nine-minute job does not die of one 529.
41
46
  */
42
47
  export const RETRY = { limit: 6, baseMs: 1000, capMs: 30_000 };
48
+ /** The tries a lone request — a summary, a hand-off — gets from the client, in the background: nothing sends it again otherwise. */
49
+ export const QUIET_RETRIES = 2;
43
50
  /** The same call with the same input and the same answer, over and over: said to the model at the third, and the run stopped at the fifth. */
44
51
  const REPEAT_NUDGE_AT = 3;
45
52
  const REPEAT_STOP_AT = 5;
@@ -87,7 +94,7 @@ const CIRCLES_SCHEMA = { type: 'object', properties: { stuck: { type: 'boolean'
87
94
  /** The beta under which one request summarizes the conversation server-side, in place of answering it. */
88
95
  const COMPACT_BETA = 'compact-2026-09-04';
89
96
  /** Where a job sheds its past rather than stop: the "act" band of the context gauge, where quality is already falling. */
90
- export const COMPACT_AT = 150_000;
97
+ const COMPACT_AT = 150_000;
91
98
  /** Not again until this many responses after the last summary: a conversation at once too big again is not fixed by another. */
92
99
  const COMPACT_GAP = 3;
93
100
  /** What the summary is to keep, told to the summarizer in place of the server's own prompt. */
@@ -151,11 +158,34 @@ export function codingRules() {
151
158
  export const systemPrompt = () => [promptFile('agent.md'), `## How the user wants code changed\n${codingRules()}`].join('\n\n');
152
159
 
153
160
  /**
154
- * How a model thinks: every model but haiku always does, and is asked to say in summary what it thought, so a turn that
155
- * runs for minutes is not silent on the screen — the thinking itself, and its price, are the same either way. Haiku takes
156
- * no thinking setting at all.
161
+ * How a model thinks: every model always does, and is asked to say in summary what it thought, so a turn that runs for
162
+ * minutes is not silent on the screen — the thinking itself, and its price, are the same either way. `model` is kept
163
+ * for a model that may one day take none.
164
+ */
165
+ export const thinkingFor = (_model) => ({ type: 'adaptive', display: 'summarized' });
166
+
167
+ /**
168
+ * Whether a model's declined replies are run again on another, server-side: every model but haiku, whose refusals have no
169
+ * fallback. A request that goes on from one answered that way carries the `fallback` block as it came, and is priced on
170
+ * the model that answered.
157
171
  */
158
- export const thinkingFor = (model) => (modelId(model) === MODEL_IDS.haiku ? undefined : { type: 'adaptive', display: 'summarized' });
172
+ const fallsBack = (model) => modelId(model) !== MODEL_IDS.haiku;
173
+
174
+ /** A request's fallback set as its model takes it: on, with its beta, or off. The request itself is changed. */
175
+ export function withFallback(params, model) {
176
+ const betas = (params.betas ?? []).filter((b) => b !== FALLBACK_BETA);
177
+ if (fallsBack(model)) {
178
+ params.fallbacks = 'default';
179
+ params.betas = [...betas, FALLBACK_BETA];
180
+ } else {
181
+ delete params.fallbacks;
182
+ params.betas = betas;
183
+ }
184
+ return params;
185
+ }
186
+
187
+ /** The model a reply fell back to, when it did: the API answered on another model after the first declined. Null otherwise. */
188
+ const fellBackTo = (response) => response.content?.find((b) => b.type === 'fallback')?.to?.model ?? null;
159
189
 
160
190
  /** The request for a conversation's first turn. */
161
191
  export function paramsFor({ model, effort, tools, text, system }) {
@@ -171,7 +201,7 @@ export function paramsFor({ model, effort, tools, text, system }) {
171
201
  if (effort && effort !== 'none') params.output_config = { effort };
172
202
  const thinking = thinkingFor(model);
173
203
  if (thinking) params.thinking = thinking;
174
- return params;
204
+ return withFallback(params, model);
175
205
  }
176
206
 
177
207
  /**
@@ -250,10 +280,14 @@ export function markTail(messages) {
250
280
 
251
281
  export const textOf = (content) => content.filter((b) => b.type === 'text').map((b) => b.text).join('\n').trim();
252
282
 
253
- /** The default transport: streamed, so a long turn never trips the HTTP timeout; the text and the thinking said as they come, and each block of the reply as it ends. */
254
- export async function sendToApi(params, { onText, onThinking, onBlock, signal } = {}) {
283
+ /**
284
+ * The default transport: streamed, so a long turn never trips the HTTP timeout; the text and the thinking said as they come,
285
+ * and each block of the reply as it ends. The client sends nothing again by itself: the loop does, where the wait is
286
+ * counted on the screen. A request nothing sends again — a summary, a hand-off — asks for the client's quiet `retries`.
287
+ */
288
+ export async function sendToApi(params, { onText, onThinking, onBlock, signal, retries = 0 } = {}) {
255
289
  const credential = resolveAnthropicCredential();
256
- const client = anthropicClient({ timeout: REQUEST_TIMEOUT_MS }, credential);
290
+ const client = anthropicClient({ timeout: REQUEST_TIMEOUT_MS, maxRetries: retries }, credential);
257
291
  const stream = client.beta.messages.stream(authenticatedRequest(params, credential), signal ? { signal } : undefined);
258
292
  if (onText) stream.on('text', onText);
259
293
  if (onThinking) stream.on('thinking', (delta, snapshot) => onThinking(delta, snapshot));
@@ -281,6 +315,9 @@ export function retryDelay(cause, attempt, { baseMs, capMs } = RETRY, random = M
281
315
  }
282
316
 
283
317
  /** What went wrong with a request, in one short line: the status and the API's own words, not the JSON they came in. */
318
+ /** The API's refusal of a conversation too big for the model to take whole: a 400 that says so. */
319
+ const overflowed = (cause) => cause?.status === 400 && /prompt is too long/i.test(describeFailure(cause));
320
+
284
321
  export function describeFailure(cause) {
285
322
  if (cause instanceof Anthropic.APIError && (cause.error?.error?.message || cause.type)) {
286
323
  const type = cause.type ?? cause.error?.error?.type ?? null;
@@ -384,8 +421,12 @@ export async function converse(db, params, { send = sendToApi, ctx, ledger, befo
384
421
  const totals = { inputTokens: 0, outputTokens: 0, costUsd: 0, toolCalls: 0, contextTokens: 0 };
385
422
  let turns = 0;
386
423
  let stop = 'max_turns';
424
+ /** What the API said with a refusal: the category, when it gave one. */
425
+ let stopDetail = null;
387
426
  let text = '';
388
427
  let compactedAt = -Infinity;
428
+ /** Whether the conversation was summarized because the model would no longer take it whole: once a run. */
429
+ let shedForLength = false;
389
430
  let toldLast = false;
390
431
  // The ledger names the model that answered: with a fallback that is not always the one asked for.
391
432
  const log = (result, note, model = params.model) => logRun(db, { kind: ledger.kind, model, result, note, now: now(), jobId: ledger.jobId ?? null, sessionId: ledger.sessionId ?? null });
@@ -435,6 +476,34 @@ export async function converse(db, params, { send = sendToApi, ctx, ledger, befo
435
476
  for (const call of hosted.open.values()) onResult?.(call, { content: 'not finished: the request ended first', isError: true });
436
477
  hosted.open.clear();
437
478
  };
479
+ /**
480
+ * The conversation so far summarized server-side, and the run gone on from the summary. A summary that cannot be had
481
+ * costs nothing but its request: the run goes on as it was. True when the summary stands in place of the history;
482
+ * 'interrupted' when the user stopped it.
483
+ */
484
+ async function shed() {
485
+ compactedAt = turns;
486
+ try {
487
+ const summary = await send(compactionParams(params, compact.instructions), { signal, retries: QUIET_RETRIES });
488
+ const block = summary.content.find((b) => b.type === 'compaction' && b.content);
489
+ const by = summary.model ?? params.model;
490
+ const spent = usageOf(by, summary.usage);
491
+ totals.inputTokens += spent.inputTokens;
492
+ totals.outputTokens += spent.outputTokens;
493
+ totals.costUsd += costOf(by, summary.usage ?? {});
494
+ log({ ok: Boolean(block), usage: spent }, `turn ${turns} compaction${block ? '' : ': no summary came back'}`, by);
495
+ if (!block) return false;
496
+ ledger.cleared = true;
497
+ // A job's own record of its work rides after the line, from code and not from the summary; whatever cannot be read is left out.
498
+ params.messages = [{ role: 'assistant', content: summary.content }, { role: 'user', content: [{ type: 'text', text: [RESUMED(compact.brief), recordedBy(compact)].filter(Boolean).join('\n\n') }] }];
499
+ onCompact?.({ turns, before: totals.contextTokens, summary: block.content });
500
+ return true;
501
+ } catch (cause) {
502
+ if (signal?.aborted) return 'interrupted';
503
+ log({ ok: false, usage: usageOf(params.model, null) }, `turn ${turns} compaction: ${describeFailure(cause).slice(0, 200)}`);
504
+ return false;
505
+ }
506
+ }
438
507
 
439
508
  while (turns < MAX_TURNS) {
440
509
  // A job that has spent its budget sends nothing more: the last round it made is answered, and the run ends there.
@@ -467,6 +536,17 @@ export async function converse(db, params, { send = sendToApi, ctx, ledger, befo
467
536
  if (await pause(delayMs, signal)) return interrupted();
468
537
  continue;
469
538
  }
539
+ // A conversation the model no longer takes whole is summarized, once, and sent again from the summary; refused again, the run ends as any error ends it.
540
+ if (compact && overflowed(cause) && !shedForLength) {
541
+ shedForLength = true;
542
+ log({ ok: false, usage: usageOf(params.model, null) }, `turn ${turns}: ${why} — summarizing to go on`);
543
+ const shedding = await shed();
544
+ if (shedding === 'interrupted') return interrupted();
545
+ if (shedding) {
546
+ markTail(params.messages);
547
+ continue;
548
+ }
549
+ }
470
550
  log({ ok: false, usage: usageOf(params.model, null) }, `turn ${turns}: ${why}`);
471
551
  return { turns, stop: 'error', error: describeFailure(cause).slice(0, 300), status: cause.status ?? null, text, totals, toldLast };
472
552
  }
@@ -477,7 +557,9 @@ export async function converse(db, params, { send = sendToApi, ctx, ledger, befo
477
557
  totals.outputTokens += usage.outputTokens;
478
558
  totals.costUsd += costOf(served, response.usage ?? {});
479
559
  totals.contextTokens = contextOf(served, response.usage);
480
- log({ ok: true, usage }, `turn ${turns} ${response.stop_reason}${clearedBy(response)}`, served);
560
+ log({ ok: true, usage }, `turn ${turns} ${response.stop_reason}${clearedBy(response)}${fellBackTo(response) ? ` fell back from ${params.model}` : ''}`, served);
561
+ // Why this request wrote its context again, if it did, on its row: the API clearing tool uses before it answered is one reason.
562
+ noteRewrite(db, ledger, { at: Date.parse(now()), model: served, prefix: prefixOf(params), usage, cleared: clearedBy(response) !== '' });
481
563
  // What the advisor read and wrote is not in the reply's own count: it is paid at the advisor's price, and has a row under its name.
482
564
  for (const run of advisorRuns(response.usage)) {
483
565
  const spent = usageOf(run.model, run);
@@ -487,8 +569,10 @@ export async function converse(db, params, { send = sendToApi, ctx, ledger, befo
487
569
  log({ ok: true, usage: spent }, `turn ${turns} advisor`, run.model);
488
570
  }
489
571
 
490
- // A refused reply is not kept: what streamed before the refusal is not an answer, and its calls were never made.
572
+ // A refused reply is not kept: what streamed before the refusal is not an answer, and its calls were never made. Why, when the
573
+ // API says — the category the classifiers put it in — is said with the stop.
491
574
  const refused = response.stop_reason === 'refusal';
575
+ if (refused) stopDetail = response.stop_details?.category ?? null;
492
576
  // A reply with nothing in it is not kept either: the API refuses an empty message once anything follows it.
493
577
  if (response.content.length > 0 && !refused) params.messages.push({ role: 'assistant', content: response.content });
494
578
  if (!refused) text = textOf(response.content) || text;
@@ -597,30 +681,12 @@ export async function converse(db, params, { send = sendToApi, ctx, ledger, befo
597
681
  // Past the band where the work must either stop or shed its past: the conversation so far is summarized server-side, here, at the
598
682
  // end of a tool round, and goes on from the summary. A summary that cannot be had costs nothing but its request: the run goes on as it was.
599
683
  if (compact && !overBudget() && !overTime() && totals.contextTokens >= compact.at && turns - compactedAt >= COMPACT_GAP) {
600
- compactedAt = turns;
601
- try {
602
- const summary = await send(compactionParams(params, compact.instructions), { signal });
603
- const block = summary.content.find((b) => b.type === 'compaction' && b.content);
604
- const by = summary.model ?? params.model;
605
- const spent = usageOf(by, summary.usage);
606
- totals.inputTokens += spent.inputTokens;
607
- totals.outputTokens += spent.outputTokens;
608
- totals.costUsd += costOf(by, summary.usage ?? {});
609
- log({ ok: Boolean(block), usage: spent }, `turn ${turns} compaction${block ? '' : ': no summary came back'}`, by);
610
- if (block) {
611
- // A job's own record of its work rides after the line, from code and not from the summary; whatever cannot be read is left out.
612
- params.messages = [{ role: 'assistant', content: summary.content }, { role: 'user', content: [{ type: 'text', text: [RESUMED(compact.brief), recordedBy(compact)].filter(Boolean).join('\n\n') }] }];
613
- onCompact?.({ turns, before: totals.contextTokens, summary: block.content });
614
- }
615
- } catch (cause) {
616
- if (signal?.aborted) return interrupted();
617
- log({ ok: false, usage: usageOf(params.model, null) }, `turn ${turns} compaction: ${describeFailure(cause).slice(0, 200)}`);
618
- }
684
+ if ((await shed()) === 'interrupted') return interrupted();
619
685
  }
620
686
  }
621
687
 
622
688
  endHosted();
623
- return { turns, stop, error: null, text, totals, toldLast };
689
+ return { turns, stop, stopDetail, error: null, text, totals, toldLast };
624
690
  }
625
691
 
626
692
  /**
@@ -695,7 +761,7 @@ export async function runJob(db, id, { send = sendToApi, now, signal = null, onS
695
761
  const lock = tx(db, () => takeRunLock(id));
696
762
  const heard = () => [...(inbox?.() ?? []), ...takeInbox(id)];
697
763
  // A command the sandbox blocked is put to the user with the job named, as its MCP calls are; its background commands are its own to end.
698
- const ctx = { ...contextFor(project, { jobId: id, sandbox: sandboxOn(db), network: networkOn(db), tree: tree?.path }), approve: approve && ((ask) => approve({ ...ask, job: id })), background: new Set() };
764
+ const ctx = { ...contextFor(project, { jobId: id, sandbox: sandboxOn(db), network: networkOn(db), tree: tree?.path }), approve: approve && ((ask) => approve({ ...ask, job: id })), opened: new Set(), background: new Set() };
699
765
  // The workflow gate holds a job's commands as it holds the chat's: once per session for this job, which has a context of its own,
700
766
  // and with the job's own project in scope whether or not its card came up in the session.
701
767
  const gate = (call) => {
@@ -718,7 +784,18 @@ export async function runJob(db, id, { send = sendToApi, now, signal = null, onS
718
784
  const plan = turns % PLAN_EVERY === 0 ? planOf(id) : null;
719
785
  return plan && PLAN_AGAIN(plan);
720
786
  };
721
- const run = () => converse(db, params, { send, now, signal, onTool, onResult, onTurn, onThinking, onRetry, onCompact, compact, budget, clock, circling, remind, inbox: heard, beforeTool: gate, ctx, ledger: { kind: job.agent, jobId: id, sessionId: job.session_id } });
787
+ // A call that reaches past the machine — a search, a fetch, an MCP server — is written down: what the job then says it
788
+ // learned is held for the user, not filed as fact.
789
+ // So is the conversation the job reports to: its report reaches the chat, and what the chat says after it may be what
790
+ // a page told the job.
791
+ const told = (call) => {
792
+ if (isWebTool(call) || isMcpTool(call.name)) {
793
+ noteOutsideRead(id, call.name);
794
+ noteSessionOutside(db, job.session_id, call.name);
795
+ }
796
+ onTool?.(call);
797
+ };
798
+ const run = () => converse(db, params, { send, now, signal, onTool: told, onResult, onTurn, onThinking, onRetry, onCompact, compact, budget, clock, circling, remind, inbox: heard, beforeTool: gate, ctx, ledger: { kind: job.agent, jobId: id, sessionId: job.session_id } });
722
799
  let outcome = await run();
723
800
  if (outcome.stop === 'end_turn' && getJob(db, id).status === 'running') {
724
801
  params.messages.push({ role: 'user', content: [{ type: 'text', text: UNCLOSED }] });
@@ -806,9 +883,9 @@ async function circlingWhy(db, calls) {
806
883
  /** One run per job: two would drive two agents over the same tree. */
807
884
  const takeRunLock = (id) => takeLock(runLockFile(id), (holder) => `j${id} is already being run (process ${holder}) — wait for it, or stop it there`);
808
885
 
809
- /** Why a conversation ended, when it was neither the model finishing nor the user stopping it nor an error; null otherwise. Said to a chat as to a job. */
810
- export function stopReason(stop) {
811
- if (stop === 'refusal') return 'stopped: the model declined to continue';
886
+ /** Why a conversation ended, when it was neither the model finishing nor the user stopping it nor an error; null otherwise. Said to a chat as to a job. `detail` is the refusal's category, when the API gave one. */
887
+ export function stopReason(stop, detail = null) {
888
+ if (stop === 'refusal') return `stopped: the model declined to continue${detail ? ` (${detail})` : ''}`;
812
889
  if (stop === 'max_tokens') return 'stopped: a reply hit the output limit';
813
890
  if (stop === 'model_context_window_exceeded') return 'stopped: the conversation no longer fits in the model\'s context';
814
891
  if (stop === 'max_turns') return `stopped: ${MAX_TURNS} turns without an end`;
@@ -831,7 +908,7 @@ export function runLines(outcome) {
831
908
  if (stop === 'error') lines.push(`stopped: ${outcome.error}`);
832
909
  if (stop === 'interrupted') lines.push(INTERRUPTED);
833
910
  if (stop === 'max_turns') lines.push(`stopped: ${MAX_TURNS} turns without closing the job`);
834
- else if (stopReason(stop)) lines.push(stopReason(stop));
911
+ else if (stopReason(stop, outcome.stopDetail)) lines.push(stopReason(stop, outcome.stopDetail));
835
912
  if (closed === 'never closed') lines.push(`close it yourself from its report: sumo job show ${job.id}`);
836
913
  if (outcome.text) lines.push(...outcome.text.split('\n').slice(-6));
837
914
  return lines;