sumo-agents 0.7.2 → 0.8.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.
package/src/cursor.mjs ADDED
@@ -0,0 +1,405 @@
1
+ import { randomUUID } from 'node:crypto';
2
+ import { mkdirSync, realpathSync, writeFileSync } from 'node:fs';
3
+ import { join } from 'node:path';
4
+ import { CURSOR_MODELS, cursorKeyIn } from './catalog.mjs';
5
+ import { isMcpTool, runMcpTool } from './mcp.mjs';
6
+ import { costOf, logRun, usageOf } from './model.mjs';
7
+ import { paths } from './paths.mjs';
8
+ import { BASH_TOOL, EDITOR_TOOL, runTool } from './tools.mjs';
9
+ import { WEB_FETCH_TOOL, WEB_SEARCH_TOOL } from './web.mjs';
10
+
11
+ /**
12
+ * A conversation on a Cursor model — a job's, or a chat turn's — through the Cursor SDK. Cursor runs the loop on its own servers and calls back here
13
+ * for every tool: the agent has none of Cursor's own but its web search and fetch where Sumo's are offered, and Sumo's tools — the shell, the editor,
14
+ * the job's tools, the MCP servers — go to it as custom tools that run in this process, through the same gate and the same
15
+ * sandbox as on Claude. Measured on @cursor/sdk 1.4.1 (Nov 18 2026):
16
+ * - `tools` is not kept with the agent: an agent resumed without it had Cursor's own file tools again. Every send here
17
+ * creates or resumes with it.
18
+ * - A custom system prompt needs Cursor to enable it for the account; Sumo's prompt goes in the first message instead, with
19
+ * today's date, which the model otherwise guesses — once as a year gone.
20
+ * - Cursor's web search runs on its servers and nothing of it comes back: a run given it is marked as having read the web up front.
21
+ * - A cancel stops the run, but the calls already sent still arrive: each waits its turn and is refused once the job stops.
22
+ * - The SDK sets up Cursor's own shell and file tools in this process whether or not they are offered; only a `local.fs` tree
23
+ * locks the host out (its filesystem/host-lockout.d.ts). The tree here is empty.
24
+ * - An agent is stored under the folder it was made in (`local.cwd`); a resume from another folder finds nothing. That folder
25
+ * is one of Sumo's, the same every time (`cursorFolder`), never the project: see there for what the SDK runs in it.
26
+ * - The SDK keeps a fetch of its own in this process, outside any sandbox, that `local.fs` does not lock out and that cannot
27
+ * be replaced beside it (`resourceProviderOptions` is refused with `fs`): if Cursor's servers ask it for a URL, it is
28
+ * fetched from here, `shell.network off` or not. Only the tools named to the server (`cursorTools`) say otherwise.
29
+ * Measured live (Nov 18 2026): Cursor's webFetch runs on Cursor's own isolated server, not through it — asked for
30
+ * `http://127.0.0.1:<port>` and for `localtest.me` (which resolves to it), a local server here saw no request, and
31
+ * Cursor answered that its fetch runs from an isolated server and cannot reach localhost.
32
+ * - Each request to the model reports its usage as it ends (`model-call-completed`, through `onDelta`); the stream's `usage`
33
+ * is the run's sum. The ledger takes a row per request, and the budget and the clock are held after each.
34
+ */
35
+
36
+ /**
37
+ * Cursor's own tools the agent is given: the custom-tool path Sumo's tools come by, and its web search and fetch only where the
38
+ * request carries Sumo's — the chat's and a scout's, never a worker's or a reviewer's, as on Claude. Nothing else.
39
+ */
40
+ const cursorTools = (params) => [
41
+ ...((params.tools ?? []).some((t) => t.name === WEB_SEARCH_TOOL.name) ? ['webSearch'] : []),
42
+ ...((params.tools ?? []).some((t) => t.name === WEB_FETCH_TOOL.name) ? ['webFetch'] : []),
43
+ 'mcp',
44
+ ];
45
+
46
+ /** What Sumo's two Anthropic-defined tools take, written out for a model that was never told: the bash and editor schemas. */
47
+ const BASH_SCHEMA = {
48
+ description: 'Run a shell command in the project folder and get what it printed. The shell keeps its state between calls; restart: true starts a fresh one.',
49
+ inputSchema: { type: 'object', properties: { command: { type: 'string' }, restart: { type: 'boolean' } } },
50
+ };
51
+ const EDITOR_SCHEMA = {
52
+ description:
53
+ 'View or change a file. view: a file with its line numbers (view_range [first, last] for part of it) or a folder\'s files. create: a new file ' +
54
+ 'of file_text. str_replace: replace old_str, which must occur exactly once, with new_str. insert: new_str after line insert_line (0 for the top).',
55
+ inputSchema: {
56
+ type: 'object',
57
+ properties: {
58
+ command: { type: 'string', enum: ['view', 'create', 'str_replace', 'insert'] },
59
+ path: { type: 'string' },
60
+ file_text: { type: 'string' },
61
+ old_str: { type: 'string' },
62
+ new_str: { type: 'string' },
63
+ insert_line: { type: 'integer' },
64
+ view_range: { type: 'array', items: { type: 'integer' }, minItems: 2, maxItems: 2 },
65
+ },
66
+ required: ['command', 'path'],
67
+ },
68
+ };
69
+
70
+ /** The request's tools as Cursor takes them, by name: Sumo's own with their schemas; the API's server tools (search, the tool finder, the advisor) are left out. */
71
+ function toolsOf(params) {
72
+ const wanted = {};
73
+ for (const tool of params.tools ?? []) {
74
+ if (tool.name === BASH_TOOL.name) wanted[tool.name] = BASH_SCHEMA;
75
+ else if (tool.name === EDITOR_TOOL.name) wanted[tool.name] = EDITOR_SCHEMA;
76
+ else if (tool.input_schema) wanted[tool.name] = { description: tool.description ?? '', inputSchema: tool.input_schema };
77
+ }
78
+ return wanted;
79
+ }
80
+
81
+ /** The model as Cursor takes it: its id, the standard variant, and the effort where the model takes one (Grok's top is xhigh). */
82
+ export function cursorModel(model, effort) {
83
+ const name = Object.keys(CURSOR_MODELS).find((n) => CURSOR_MODELS[n].id === model || n === model);
84
+ const known = CURSOR_MODELS[name];
85
+ if (!known) throw new Error(`${model} is not a Cursor model Sumo knows`);
86
+ const params = [...known.params];
87
+ if (known.effort && effort && effort !== 'none') params.push({ id: known.effort, value: effort === 'max' ? 'xhigh' : effort });
88
+ return { id: known.id, params };
89
+ }
90
+
91
+ /** A message's words: its text blocks, without the tool calls, results and pictures beside them. */
92
+ const wordsOf = (m) => (typeof m.content === 'string' ? m.content : m.content.filter((b) => b.type === 'text').map((b) => b.text).join('\n\n')).trim();
93
+
94
+ /**
95
+ * What Cursor is sent of the messages from `from` on. What the user side said since the last send, as it is; where the
96
+ * conversation went on without this agent — the start of a chat that moves to it, turns answered on Claude — it is told what was
97
+ * said on both sides, in words: the tool calls and what came back are not carried over.
98
+ */
99
+ function textFrom(messages, from, fresh) {
100
+ const since = messages.slice(from).filter((m) => m.role === 'user' || m.role === 'assistant').filter((m) => wordsOf(m));
101
+ const replied = since.findLastIndex((m) => m.role === 'assistant');
102
+ if (replied === -1) return since.map(wordsOf).join('\n\n');
103
+ const before = since.slice(0, replied + 1).map((m) => `${m.role === 'user' ? 'The user' : 'You'}: ${wordsOf(m)}`);
104
+ const now = since.slice(replied + 1).map(wordsOf);
105
+ const told = fresh ? 'The conversation so far' : 'What was said since you last answered';
106
+ return [`${told}, in words (the tool calls in it are not carried over):\n\n${before.join('\n\n')}`, ...now].join('\n\n');
107
+ }
108
+
109
+ /**
110
+ * Each conversation's Cursor agent: its id, and the last message of the conversation it has been told. Kept beside the request,
111
+ * never in it — the request is what Claude is sent too, and the API refuses a field it does not take. A new conversation is a
112
+ * new request, and so a new agent; one whose history was rewritten under it (the message it knew is gone) is a new agent too,
113
+ * told the conversation whole.
114
+ */
115
+ const agents = new WeakMap();
116
+
117
+ /** A tool's result as Cursor takes it: its words, and a picture as a picture rather than as text. */
118
+ const forCursor = (content) =>
119
+ typeof content === 'string'
120
+ ? [{ type: 'text', text: content }]
121
+ : content.map((b) => (b.type === 'image' && b.source?.type === 'base64' ? { type: 'image', data: b.source.data, mimeType: b.source.media_type } : { type: 'text', text: b.text ?? JSON.stringify(b) }));
122
+
123
+ /** Cursor's usage of one turn in the shape the ledger prices: its input counts what was read from the cache and written to it. */
124
+ const anthropicUsage = (u) => ({
125
+ input_tokens: Math.max(0, (u.inputTokens ?? 0) - (u.cacheReadTokens ?? 0) - (u.cacheWriteTokens ?? 0)),
126
+ cache_read_input_tokens: u.cacheReadTokens ?? 0,
127
+ cache_creation_input_tokens: u.cacheWriteTokens ?? 0,
128
+ output_tokens: u.outputTokens ?? 0,
129
+ });
130
+
131
+ /**
132
+ * What went wrong with Cursor, in a line a person can act on. A refused key comes thrown as an AuthenticationError, or as the
133
+ * error a run ended on, which carries only its message and code (`unauthenticated`, the SDK's for a Connect Unauthenticated).
134
+ */
135
+ function describeCursorError(cause) {
136
+ const message = String(cause?.message ?? cause).replace(/\s+/g, ' ');
137
+ if (cause?.name === 'AuthenticationError' || cause?.code === 'unauthenticated') return `Cursor refused CURSOR_API_KEY: ${message.slice(0, 200)}`;
138
+ return message.slice(0, 300);
139
+ }
140
+
141
+ /** A folder as it really is on disk (macOS's /tmp is /private/tmp), or as given when it cannot be read. */
142
+ function realFolder(path) {
143
+ try {
144
+ return realpathSync.native(path);
145
+ } catch {
146
+ return path;
147
+ }
148
+ }
149
+
150
+ /**
151
+ * Where Cursor's agents are kept and where the SDK runs what it runs for itself: a folder of Sumo's, the same every time,
152
+ * so an agent is found again whatever folder the conversation is in. After each run the SDK looks for a pull request of
153
+ * that folder's branch — `git rev-parse`, then `gh pr list` and a command named `origin` — found on the PATH and handed
154
+ * this process's environment, keys and all; in a project, a program the shell put on a PATH folder there would be run
155
+ * outside the sandbox. Here there is no repository, and a `.git` that leads nowhere stops git looking above it, so the
156
+ * first step finds no branch and the others never run. The model is told the project's folder (`reportedWorkspacePath`).
157
+ */
158
+ function cursorFolder() {
159
+ const dir = join(paths().home, 'cursor');
160
+ mkdirSync(dir, { recursive: true, mode: 0o700 });
161
+ const stop = join(dir, '.git');
162
+ try {
163
+ writeFileSync(stop, 'gitdir: /dev/null/none\n', { mode: 0o600, flag: 'wx' });
164
+ } catch (cause) {
165
+ if (cause.code !== 'EEXIST') throw cause;
166
+ }
167
+ return realFolder(dir);
168
+ }
169
+
170
+ /** The pictures the user put in the messages Cursor is about to be told — those after its last answer — as the SDK takes them on a send. */
171
+ const picturesIn = (messages) =>
172
+ messages
173
+ .slice(messages.findLastIndex((m) => m.role === 'assistant') + 1)
174
+ .filter((m) => m.role === 'user' && Array.isArray(m.content))
175
+ .flatMap((m) => m.content.filter((b) => b.type === 'image' && b.source?.type === 'base64').map((b) => ({ data: b.source.data, mimeType: b.source.media_type })));
176
+
177
+ /**
178
+ * Runs the job's conversation on Cursor until the model stops, the budget or the clock runs out, or `signal` aborts — and
179
+ * answers as `converse` does (src/loop.mjs): `{ turns, stop, error, text, totals, toldLast }`. Called again on the same
180
+ * `params` (a job told to close), it sends what was added since, to the same agent. Each result is watched as on Claude
181
+ * (`roundWatch`): what `inbox` hands over and the warnings near the budget, the clock and the turn limit ride on it, and the
182
+ * same brakes stop a run that goes round or is declined. The calls `concurrent` picks run beside the others. Nothing the run
183
+ * started outlives it: a call still at work when it ends is cut off and answered before this returns. `sdk` stands in for
184
+ * @cursor/sdk in tests.
185
+ */
186
+ export async function converseCursor(db, params, { ctx, ledger, beforeTool = null, concurrent = null, onText = null, onTool = null, onResult = null, onOutput = null, onUsage = null, inbox = null, signal = null, budget = null, clock = null, circling = null, remind = null, now = () => new Date().toISOString(), sdk = null } = {}) {
187
+ const { Agent, emptyFs } = sdk ?? (await import('@cursor/sdk'));
188
+ const apiKey = cursorKeyIn() ? process.env.CURSOR_API_KEY.trim() : null;
189
+ const totals = { inputTokens: 0, outputTokens: 0, costUsd: 0, toolCalls: 0, contextTokens: 0 };
190
+ const log = (result, note) => logRun(db, { kind: ledger.kind, model: params.model, result, note, now: now(), jobId: ledger.jobId ?? null, sessionId: ledger.sessionId ?? null });
191
+ const failed = (error) => {
192
+ log({ ok: false, usage: usageOf(params.model, null) }, error);
193
+ return { turns: 0, stop: 'error', error, text: '', totals, toldLast: false };
194
+ };
195
+ if (!apiKey) return failed('no CURSOR_API_KEY in this shell — export it in the shell sumo starts from');
196
+
197
+ // The run's own stop: it ends when the run does, and with it whatever the run started; the caller's stop ends it too.
198
+ const own = new AbortController();
199
+ const runSignal = signal ? AbortSignal.any([signal, own.signal]) : own.signal;
200
+ // The loop's own watch, loaded when a run begins: loop.mjs imports this module, and an import back from here at load time
201
+ // was a cycle the standalone binary's bundle spun on for ever, before any job could start.
202
+ const { heardFrom, roundWatch } = await import('./loop.mjs');
203
+ const heard = () => heardFrom(inbox);
204
+ const watch = roundWatch({ ctx, budget, clock, circling, remind, now });
205
+ const spent = () => (budget?.spent ?? 0) + totals.costUsd;
206
+ // The job's clock runs from when the job began (`clock.from`), not from this send: a job told to close is still on it.
207
+ const overTime = () => clock !== null && Date.parse(now()) - clock.from >= clock.ms;
208
+ let turns = 0;
209
+ let stop = null;
210
+ let stopped = null;
211
+ let run = null;
212
+ /** The request a result was last watched at: the local model's look and the plan come once a request, not once a call. */
213
+ let watchedAt = -1;
214
+ const cancel = (why) => {
215
+ stop ??= why;
216
+ stopped ??= why === 'budget' ? 'reached its budget' : why === 'time' ? 'reached its time limit' : 'was stopped';
217
+ own.abort();
218
+ run?.cancel().catch(() => {});
219
+ };
220
+
221
+ // One call: refused once the run is stopping; else through the gate and the tool as on Claude, under the run's own signal,
222
+ // its result watched as a round on Claude is, and the call and its answer joined to the conversation together.
223
+ const answer = async (call) => {
224
+ if (stopped || runSignal.aborted) return { content: [{ type: 'text', text: `not run: the ${ledger.kind === 'chat' ? 'turn' : 'job'} ${stopped ?? 'was stopped'}` }], isError: true };
225
+ totals.toolCalls++;
226
+ onTool?.(call);
227
+ let out;
228
+ try {
229
+ out = (await beforeTool?.(call, { signal: runSignal })) ?? (isMcpTool(call.name) ? await runMcpTool(call, { signal: runSignal }) : await runTool(call, ctx, { signal: runSignal, onOutput: onOutput && ((chunk) => onOutput(call, chunk)) }));
230
+ } catch (cause) {
231
+ out = { content: `the tool failed: ${cause.message}`, isError: true };
232
+ }
233
+ onResult?.(call, out);
234
+ const results = [{ type: 'tool_result', tool_use_id: call.id, content: out.content, is_error: Boolean(out.isError) }];
235
+ const marked = watch.mark([call], results);
236
+ let after = [];
237
+ if (marked.looping || marked.declined) cancel(marked.looping ? 'loop' : 'declined');
238
+ else {
239
+ const fresh = turns !== watchedAt;
240
+ watchedAt = turns;
241
+ if (fresh) await watch.circles(turns, results, runSignal);
242
+ after = [...heard(), ...watch.notes(turns, spent, { past: true })];
243
+ const reminder = fresh ? watch.reminder(turns) : null;
244
+ if (reminder) after.push({ type: 'text', text: reminder });
245
+ }
246
+ // The call and what came back join the conversation as a call on Claude does, so a turn on Claude after this one
247
+ // knows what was done and read — told only the reply, Claude once denied having made the file Composer made.
248
+ params.messages.push(
249
+ { role: 'assistant', content: [{ type: 'tool_use', id: call.id, name: call.name, input: call.input }] },
250
+ { role: 'user', content: [...results, ...after] },
251
+ );
252
+ return { content: [...forCursor(results[0].content), ...after], isError: results[0].is_error };
253
+ };
254
+
255
+ // Sumo's tools, one at a time as on Claude: Cursor may send several at once, and two edits racing over one file is no answer.
256
+ // The calls `concurrent` picks — delegated jobs — run beside them. Every call is kept until it is answered.
257
+ let queue = Promise.resolve();
258
+ const working = new Set();
259
+ const customTools = Object.fromEntries(
260
+ Object.entries(toolsOf(params)).map(([name, { description, inputSchema }]) => [
261
+ name,
262
+ {
263
+ description,
264
+ inputSchema,
265
+ execute: (args) => {
266
+ // An id the API takes (letters, digits, _ and -) and that no other call in the conversation has: the call joins it.
267
+ const call = { id: `cursor_${randomUUID().replaceAll('-', '')}`, name, input: args ?? {} };
268
+ const beside = Boolean(concurrent?.(call));
269
+ const turn = beside ? answer(call) : queue.then(() => answer(call));
270
+ if (!beside) queue = turn.catch(() => {});
271
+ working.add(turn);
272
+ turn.then(
273
+ () => working.delete(turn),
274
+ () => working.delete(turn),
275
+ );
276
+ return turn;
277
+ },
278
+ },
279
+ ]),
280
+ );
281
+ // The run is over: what it started is cut off, by its own signal, and answered before anything else is said or returned.
282
+ const drain = async () => {
283
+ stopped ??= 'ended';
284
+ own.abort();
285
+ while (working.size > 0) await Promise.allSettled([...working]);
286
+ };
287
+
288
+ const model = cursorModel(params.model, params.output_config?.effort);
289
+ const known = agents.get(params);
290
+ const from = known ? params.messages.lastIndexOf(known.last) + 1 : 0;
291
+ const first = from === 0;
292
+ // Cursor keeps its agents in one folder of Sumo's (`cursorFolder`), never the project's: a chat that moves to a project goes on
293
+ // with the same agent, and the model is told where its tools work now. Cursor's own file and shell tools, offered or not, are
294
+ // set up in this process: they get an empty tree, never the disk. The project is told by what it really is: the SDK refuses a
295
+ // folder under /tmp, its scratch space, and a project there is /private/tmp.
296
+ const local = { cwd: cursorFolder(), fs: emptyFs(), reportedWorkspacePath: realFolder(ctx.cwd), settingSources: [], customTools };
297
+ const day = now().slice(0, 10);
298
+ const system = (params.system ?? []).map((b) => (typeof b === 'string' ? b : b.text)).join('\n\n');
299
+ /** What an agent is sent: told the conversation whole when it is new, else what was said since `start`; with the pictures the user pasted. */
300
+ const toSend = (start, fresh) => {
301
+ const moved = !fresh && known.workspace !== ctx.cwd ? `Your tools work in ${ctx.cwd} now.\n\n` : '';
302
+ const words = fresh ? `${system}\n\nToday is ${day}.\n\n${textFrom(params.messages, 0, true)}` : `${moved}${textFrom(params.messages, start, false)}`;
303
+ const pictures = picturesIn(params.messages.slice(start));
304
+ return pictures.length > 0 ? { text: words, images: pictures } : words;
305
+ };
306
+
307
+ // One request to the model ended: its row in the ledger, and the budget, the clock and the turn limit held against the job.
308
+ const onDelta = ({ update }) => {
309
+ if (update?.type !== 'model-call-completed' || !update.usage) return;
310
+ turns++;
311
+ const shaped = anthropicUsage(update.usage);
312
+ const usage = usageOf(params.model, shaped);
313
+ totals.inputTokens += usage.inputTokens;
314
+ totals.outputTokens += usage.outputTokens;
315
+ totals.costUsd += costOf(params.model, shaped);
316
+ totals.contextTokens = update.usage.inputTokens ?? 0;
317
+ log({ ok: true, usage }, `turn ${turns} on Cursor`);
318
+ onUsage?.(totals);
319
+ if (budget && spent() >= budget.usd) cancel('budget');
320
+ if (overTime()) cancel('time');
321
+ if (watch.outOfTurns(turns)) cancel('max_turns');
322
+ };
323
+
324
+ let agent;
325
+ const send = async (said) => {
326
+ const told = params.messages.at(-1);
327
+ run = await agent.send(said, { onDelta });
328
+ agents.set(params, { agentId: agent.agentId, last: told, workspace: ctx.cwd });
329
+ };
330
+ const tools = cursorTools(params);
331
+ const made = () => Agent.create({ apiKey, model, tools, local });
332
+ try {
333
+ let message = toSend(from, first);
334
+ if (first) agent = await made();
335
+ else {
336
+ try {
337
+ agent = await Agent.resume(known.agentId, { apiKey, model, tools, local });
338
+ } catch {
339
+ // An agent that cannot be picked up again — gone from Cursor's store, or refused — is let go, and a new one is told the
340
+ // whole conversation: kept, it would be asked for again, and refused again, on every turn after this one.
341
+ agents.delete(params);
342
+ agent = await made();
343
+ message = toSend(0, true);
344
+ }
345
+ }
346
+ await send(message);
347
+ } catch (cause) {
348
+ agent?.close?.();
349
+ return failed(describeCursorError(cause));
350
+ }
351
+ // The job's deadline aborts the signal too (runJob arms it, so a request in flight is cut off): said as the time limit.
352
+ const onAbort = () => cancel(overTime() ? 'time' : 'interrupted');
353
+ if (signal?.aborted) onAbort();
354
+ else signal?.addEventListener('abort', onAbort, { once: true });
355
+
356
+ let text = '';
357
+ let reply = '';
358
+ try {
359
+ for (;;) {
360
+ if (stop) run.cancel().catch(() => {});
361
+ let ran = '';
362
+ for await (const m of run.stream()) {
363
+ if (m.type === 'assistant') {
364
+ const said = (m.message?.content ?? []).filter((b) => b.type === 'text').map((b) => b.text).join('');
365
+ if (said) {
366
+ ran += said;
367
+ text += said;
368
+ onText?.(said);
369
+ }
370
+ }
371
+ }
372
+ const result = await run.wait();
373
+ if (result.status === 'error' && !stop) {
374
+ await drain();
375
+ const why = describeCursorError(result.error ?? 'the run failed');
376
+ log({ ok: false, usage: usageOf(params.model, null) }, `turn ${turns + 1}: ${why}`);
377
+ return { turns, stop: 'error', error: why, text, totals, toldLast: watch.toldLast };
378
+ }
379
+ reply = (typeof result.result === 'string' && result.result) || ran;
380
+ // What the user said after the last call was answered is answered too, by the same agent, as a reply on Claude is followed.
381
+ const said = stop ? [] : heard();
382
+ if (said.length === 0) break;
383
+ if (reply.trim()) params.messages.push({ role: 'assistant', content: [{ type: 'text', text: reply }] });
384
+ params.messages.push({ role: 'user', content: said });
385
+ await send(said.map((b) => b.text).join('\n\n'));
386
+ }
387
+ await drain();
388
+ // The reply joins the conversation Sumo keeps, in words: what a later turn on Claude reads, and what a saved session holds.
389
+ if (reply.trim()) {
390
+ params.messages.push({ role: 'assistant', content: [{ type: 'text', text: reply }] });
391
+ agents.set(params, { agentId: agent.agentId, last: params.messages.at(-1), workspace: ctx.cwd });
392
+ }
393
+ return { turns, stop: stop ?? 'end_turn', error: null, text: reply, totals, toldLast: watch.toldLast };
394
+ } catch (cause) {
395
+ await drain();
396
+ if (stop) return { turns, stop, error: null, text, totals, toldLast: watch.toldLast };
397
+ const why = describeCursorError(cause);
398
+ log({ ok: false, usage: usageOf(params.model, null) }, `turn ${turns + 1}: ${why}`);
399
+ return { turns, stop: 'error', error: why, text, totals, toldLast: watch.toldLast };
400
+ } finally {
401
+ signal?.removeEventListener('abort', onAbort);
402
+ await drain();
403
+ agent.close?.();
404
+ }
405
+ }
package/src/db.mjs CHANGED
@@ -402,17 +402,19 @@ const MIGRATIONS = [
402
402
  CASE state WHEN 'superseded' THEN 'superseded' WHEN 'invalid' THEN 'forgotten' ELSE 'rejected' END, 'unknown', 'backfilled'
403
403
  FROM memories WHERE state IN ('superseded', 'invalid', 'rejected') ORDER BY id;
404
404
 
405
- -- The guesses still waiting, rejected once. The event first: it names the rows while they are still waiting.
406
- INSERT INTO memory_events (ts, memory_id, op, actor, reason)
407
- SELECT strftime('%Y-%m-%dT%H:%M:%fZ', 'now'), id, 'rejected', 'migration', 'a guess still waiting when guesses stopped being kept'
408
- FROM memories WHERE state = 'unconfirmed' AND held_for IS NULL ORDER BY id;
409
- UPDATE memories SET state = 'rejected', invalid_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
410
- WHERE state = 'unconfirmed' AND held_for IS NULL;
411
-
412
405
  -- A conversation the old writer had read to its end is not read again as if new.
413
406
  INSERT INTO extractions (session_id, extractor_version, status, attempts, first_turn, last_turn, started_at, ended_at)
414
407
  SELECT session_id, 'v0', 'ok', 1, MIN(id), MAX(id), MIN(ts), MAX(ts) FROM user_turns GROUP BY session_id HAVING MIN(scribed) = 1;
415
408
  `);
409
+ // The guesses still waiting, rejected once, at one moment: the history's line and the row say the same time. The
410
+ // event first: it names the rows while they are still waiting.
411
+ const now = new Date().toISOString();
412
+ db.prepare(
413
+ `INSERT INTO memory_events (ts, memory_id, op, actor, reason)
414
+ SELECT ?, id, 'rejected', 'migration', 'a guess still waiting when guesses stopped being kept'
415
+ FROM memories WHERE state = 'unconfirmed' AND held_for IS NULL ORDER BY id`,
416
+ ).run(now);
417
+ db.prepare("UPDATE memories SET state = 'rejected', invalid_at = ? WHERE state = 'unconfirmed' AND held_for IS NULL").run(now);
416
418
  },
417
419
  // 17: two things migration 16 got wrong, mended for a database that has had it — 16 itself stays as it ran.
418
420
  (db) => {
@@ -516,7 +518,12 @@ function opened(file) {
516
518
  db.close();
517
519
  throw new Error(`the database is from a newer sumo (schema ${found}; this one knows ${MIGRATIONS.length}) — upgrade: npm update -g sumo-agents`);
518
520
  }
519
- if (found > 0 && found < MIGRATIONS.length) copyAside(db, file, found);
521
+ try {
522
+ if (found > 0 && found < MIGRATIONS.length) copyAside(db, file, found);
523
+ } catch (cause) {
524
+ db.close();
525
+ throw cause;
526
+ }
520
527
  migrate(db);
521
528
  return db;
522
529
  }
@@ -530,7 +537,8 @@ const HALF_MADE_MS = 60_000;
530
537
  * The database as it is, copied beside it before it is migrated — `<db>.pre-v<N>.bak`, N the version it was at — so an
531
538
  * upgrade that goes wrong can be undone by hand. VACUUM INTO writes a consistent copy while others read; it writes into
532
539
  * a file made empty and private first, so the copy is never readable by others for a moment. A copy already there was
533
- * made by a process that got here first. One that cannot be made is let go: the migrations only add.
540
+ * made by a process that got here first. One that cannot be made stops the upgrade, said with why: a migration also
541
+ * changes rows (16 rejected the guesses still waiting), and none runs without the copy that would undo it.
534
542
  */
535
543
  function copyAside(db, file, version) {
536
544
  const copy = `${file}.pre-v${version}.bak`;
@@ -542,16 +550,19 @@ function copyAside(db, file, version) {
542
550
  } catch {
543
551
  // Not there: the usual case.
544
552
  }
553
+ const refused = (cause) =>
554
+ new Error(`the database could not be copied aside before upgrading it (${cause.code ?? cause.message}) — nothing was changed: it is still at schema ${version}, and sumo runs again once a copy can be written beside it (free some disk space): ${file}`, { cause });
545
555
  try {
546
556
  closeSync(openSync(copy, 'wx', 0o600));
547
- } catch {
548
- return;
557
+ } catch (cause) {
558
+ if (cause.code === 'EEXIST') return;
559
+ throw refused(cause);
549
560
  }
550
561
  try {
551
562
  db.exec(`VACUUM INTO '${copy.replaceAll("'", "''")}'`);
552
- } catch {
563
+ } catch (cause) {
553
564
  rmSync(copy, { force: true });
554
- return;
565
+ throw refused(cause);
555
566
  }
556
567
  const mine = `${basename(file)}.pre-v`;
557
568
  const copies = readdirSync(dirname(file))
package/src/dream.mjs CHANGED
@@ -2,11 +2,11 @@ import { readFileSync } from 'node:fs';
2
2
  import { join } from 'node:path';
3
3
  import { raiseNotice } from './apply.mjs';
4
4
  import { getMeta, setMeta, tx } from './db.mjs';
5
+ import { memoryModel } from './ledger.mjs';
5
6
  import { storedKeys } from './memory.mjs';
6
7
  import { callModel, logRun } from './model.mjs';
7
8
  import { REPO_ROOT } from './paths.mjs';
8
9
  import { redact } from './redact.mjs';
9
- import { CONFIG_DEFAULTS } from './setup.mjs';
10
10
  import { clip, stem, words } from './text.mjs';
11
11
 
12
12
  /**
@@ -144,7 +144,7 @@ const KEYS_SCHEMA = {
144
144
  };
145
145
 
146
146
  /** Whether the tidy steps may run: they call the local model only, never one that is paid for. */
147
- const tidiesLocally = (db) => (getMeta(db, 'config.memory.model') ?? CONFIG_DEFAULTS['memory.model']) === 'local';
147
+ const tidiesLocally = (db) => memoryModel(db) === 'local';
148
148
 
149
149
  /** One call of the tidy steps to the local model, with the tidy's own instructions, and its ledger row. */
150
150
  async function askLocal(db, { prompt, schema, kind, now }) {
package/src/jobs.mjs CHANGED
@@ -1,5 +1,4 @@
1
1
  import { execFileSync } from 'node:child_process';
2
- import { createHash } from 'node:crypto';
3
2
  import { appendFileSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
4
3
  import { join } from 'node:path';
5
4
  import { applyOps } from './apply.mjs';
@@ -13,6 +12,7 @@ import { callModel, failure, logRun } from './model.mjs';
13
12
  import { paths } from './paths.mjs';
14
13
  import { preferences } from './prime.mjs';
15
14
  import { getProject, isScratch } from './projects.mjs';
15
+ import { ownGit } from './sandbox.mjs';
16
16
  import { chooseRoute, RETRY_IMPORTANT_THRESHOLD, statsLines } from './route.mjs';
17
17
  import { verifyCommands } from './scan.mjs';
18
18
  import { filingState } from './ledger.mjs';
@@ -20,6 +20,7 @@ import { runScribe } from './scribe.mjs';
20
20
  import { addCheckpoint, pendingTurns } from './sessions.mjs';
21
21
  import { CONFIG_DEFAULTS } from './setup.mjs';
22
22
  import { clip, estimateTokens, head, STOPWORDS } from './text.mjs';
23
+ import { digest } from './tools.mjs';
23
24
  import { changesSince, diffStat, hasCommit, snapshot, stillThere, takeBaseline, verdictLines, verify, writeChanges } from './verify.mjs';
24
25
  import { bringBack, dropTree, makeTree, sharedSourceDependencies, treeDiff } from './worktree.mjs';
25
26
 
@@ -162,7 +163,7 @@ function whereThingsStand(root) {
162
163
  return null;
163
164
  }
164
165
  };
165
- const git = (...args) => run('git', ['--no-optional-locks', '-c', 'core.quotePath=false', ...args]);
166
+ const git = (...args) => run('git', ['--no-optional-locks', '-c', 'core.quotePath=false', ...ownGit(args)]);
166
167
  const repo = git('rev-parse', '--is-inside-work-tree')?.trim() === 'true';
167
168
  const heading = '## Where things stand as this job begins — no need to look it up again';
168
169
  const lines = [];
@@ -229,7 +230,6 @@ ${REPORT[job.agent]}
229
230
  `;
230
231
  }
231
232
 
232
- const digest = (text) => createHash('sha256').update(text).digest('hex');
233
233
  const stateKey = (id) => `job.${id}.verify`;
234
234
 
235
235
  /**
@@ -380,7 +380,7 @@ export async function newJob(db, { project: nameOrAlias, title, agent = 'worker'
380
380
 
381
381
  // A rule the user stated a minute ago may not be filed yet, and the brief is built from memory: the conversation
382
382
  // still going on is read now. Not while filing is paused — a job starting is not the user asking for it by hand.
383
- if (pendingTurns(db, 1).length > 0 && !filingState(db, now).paused) await runScribe(db, { now });
383
+ if (pendingTurns(db, 1).length > 0 && !filingState(db).paused) await runScribe(db, { now });
384
384
 
385
385
  const route = routed ?? (await chooseRoute(db, { agent, project, task, title: title.trim(), retryOf, reviews }));
386
386
 
@@ -605,6 +605,11 @@ async function followUp(db, id, { now = new Date().toISOString() } = {}) {
605
605
  const why = `j${id} failed on ${routeOf(job)} after it was told to close near its ${near}: it is not retried one step up, which would start again on a dearer route with a fresh ${near}. To retry it anyway: sumo job retry ${id}`;
606
606
  return { line: said(id, 'Not retried', [why])[0] };
607
607
  }
608
+ // Its DONE could not be verified here — no check, or none that could be compared: a dearer route would meet the same wall.
609
+ if (existsSync(unverifiableFile(id))) {
610
+ const why = `j${id} failed on ${routeOf(job)} after its DONE could not be verified here: it is not retried one step up, which would meet the same wall. To retry it anyway: sumo job retry ${id}`;
611
+ return { line: said(id, 'Not retried', [why])[0] };
612
+ }
608
613
  try {
609
614
  const made = await retry(db, id, { now });
610
615
  return { ...made, kind: 'retry', line: `j${id} failed on ${routeOf(job)} and was retried on ${routeOf(made.job)}, as j${made.job.id} — j${id}'s own report: sumo job show ${id}` };
@@ -838,21 +843,26 @@ export const appendLive = (id, text) => appendFileSync(liveFile(id), text, { mod
838
843
  export const endLive = (id, lines) => writeFileSync(endFile(id), `${lines.join('\n')}\n`, { mode: 0o600 });
839
844
 
840
845
  /**
841
- * The tools a job used that read the world outside the machine — a web search, a fetch, an MCP server — one name a
842
- * line, each once. What such a run says it learned may be what a page told it, so it is not filed as a fact (see finish).
846
+ * The tools a job used that read the world outside the machine — a web search, a fetch, an MCP server — each once. What
847
+ * such a run says it learned may be what a page told it, so it is not filed as a fact (see finish). Kept in the database,
848
+ * which the job's shell cannot write: a mark in the job's own folder could be wiped by the job it marks. A job from before
849
+ * wrote a file there, read beside it — a mark only adds.
843
850
  */
851
+ const outsideKey = (id) => `job.${id}.outside`;
844
852
  const outsideFile = (id) => fileOf(id, 'outside');
845
- export function noteOutsideRead(id, tool) {
853
+ export function noteOutsideRead(db, id, tool) {
846
854
  const name = String(tool).replace(/\s+/g, ' ');
847
- if (outsideReads(id).includes(name)) return;
848
- appendFileSync(outsideFile(id), `${name}\n`, { mode: 0o600 });
855
+ const kept = outsideReads(db, id);
856
+ if (!kept.includes(name)) setMeta(db, outsideKey(id), [...kept, name].join('\n'));
849
857
  }
850
- export function outsideReads(id) {
858
+ export function outsideReads(db, id) {
859
+ let before = [];
851
860
  try {
852
- return readFileSync(outsideFile(id), 'utf8').split('\n').filter(Boolean);
861
+ before = readFileSync(outsideFile(id), 'utf8').split('\n').filter(Boolean);
853
862
  } catch {
854
- return [];
863
+ // None: a job of this version keeps its mark in the database alone.
855
864
  }
865
+ return [...new Set([...(getMeta(db, outsideKey(id)) ?? '').split('\n').filter(Boolean), ...before])];
856
866
  }
857
867
 
858
868
  /** What was told to the job since it last looked, taken off the disk so it is read once. A file that is not a message is passed over. */
@@ -924,6 +934,8 @@ function findingsSection(report) {
924
934
  }
925
935
 
926
936
  const checkedFile = (id) => fileOf(id, 'checked');
937
+ /** Written when a DONE was refused as unverifiable: a FAILED the job closes on after it is not the work failing, and is not retried. */
938
+ const unverifiableFile = (id) => fileOf(id, 'unverifiable');
927
939
  /** How many changed files, and how many new ones, the check names before it counts the rest. */
928
940
  const CHECK_LISTED = 30;
929
941
 
@@ -1011,6 +1023,9 @@ function checkAgainstTask(db, job, state) {
1011
1023
  * as gotchas, only in this project, marked as observed, through the same
1012
1024
  * validator as every other model-written memory.
1013
1025
  */
1026
+ /** What a job is told when work cannot be checked here: the user takes it or not, and it has not failed. */
1027
+ export const ASK_TO_ACCEPT = 'Ask the user to accept it — the ask tool — saying what blocks verification: work that cannot be checked here has not failed, so do not finish FAILED for it.';
1028
+
1014
1029
  export function finish(db, id, { status, report, accept }, now = new Date().toISOString()) {
1015
1030
  const job = getJob(db, id);
1016
1031
  requireOpen(job, 'finished');
@@ -1022,7 +1037,10 @@ export function finish(db, id, { status, report, accept }, now = new Date().toIS
1022
1037
  // A DONE that cannot be checked is refused, not waved through; --accept is the way to take it anyway, and it is written down.
1023
1038
  const graded = job.agent === 'worker' && status === 'DONE';
1024
1039
  const state = graded ? readState(db, id) : null;
1025
- const unchecked = (why) => new Refusal(`j${id} cannot be verified — ${why}. To take the work as it stands: sumo job finish ${id} --status DONE --accept "<why>"`);
1040
+ const unchecked = (why) => {
1041
+ writeFileSync(unverifiableFile(id), `${now}\n`, { mode: 0o600 });
1042
+ return new Refusal(`j${id} cannot be verified — ${why}. To take the work as it stands: sumo job finish ${id} --status DONE --accept "<why>" — the user's to run: a job asks the user to accept it — the ask tool — and does not finish FAILED for this`);
1043
+ };
1026
1044
  if (graded && accept === undefined && !state) throw unchecked(`the record of where it began (${fileOf(id, 'verify.json')}) cannot be read, or was changed since sumo wrote it`);
1027
1045
  // Before the checks are run, the author looks once at the task beside its change: the first DONE is answered with that, not taken.
1028
1046
  // Kept in the job's folder, so a run started again goes on to the checks instead of being asked again.
@@ -1072,7 +1090,7 @@ export function finish(db, id, { status, report, accept }, now = new Date().toIS
1072
1090
  // A run that read a page or an MCP server may be passing on what it was told: what it learned waits for the user to
1073
1091
  // confirm (arXiv 2503.03704 — memory written from injected content is read later as trusted). Exactly what this
1074
1092
  // finish wrote is held: another job finishing in the same project at the same moment keeps its own.
1075
- const outside = outsideReads(id);
1093
+ const outside = outsideReads(db, id);
1076
1094
  if (outside.length > 0 && learned.written.length > 0) {
1077
1095
  const held = db
1078
1096
  .prepare(`UPDATE memories SET state = 'unconfirmed', provenance = 'inferred', held_for = 'outside' WHERE id IN (${learned.written.map(() => '?').join(', ')}) AND type = 'gotcha' AND state = 'active' RETURNING id`)