sumo-agents 0.0.0-stage → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +38 -0
- package/LICENSE +21 -0
- package/README.md +111 -2
- package/bin/sumo.mjs +33 -0
- package/guides/delegation.md +33 -0
- package/guides/feature.md +14 -0
- package/guides/fix.md +14 -0
- package/guides/memory.md +23 -0
- package/guides/projects.md +27 -0
- package/guides/review.md +16 -0
- package/guides/workflows.md +26 -0
- package/logo.txt +19 -0
- package/package.json +42 -4
- package/prompts/agent.md +7 -0
- package/prompts/dream.md +13 -0
- package/prompts/scribe.md +21 -0
- package/spinner.txt +90 -0
- package/src/advisor.mjs +59 -0
- package/src/apply.mjs +368 -0
- package/src/auth.mjs +80 -0
- package/src/card.mjs +72 -0
- package/src/catalog.mjs +167 -0
- package/src/chat.mjs +1162 -0
- package/src/cli.mjs +815 -0
- package/src/cost.mjs +128 -0
- package/src/db.mjs +384 -0
- package/src/dream.mjs +97 -0
- package/src/editor.mjs +198 -0
- package/src/export.mjs +132 -0
- package/src/guard.mjs +121 -0
- package/src/guides.mjs +86 -0
- package/src/herdr.mjs +117 -0
- package/src/hooks.mjs +270 -0
- package/src/images.mjs +89 -0
- package/src/jobs.mjs +1184 -0
- package/src/jobtools.mjs +82 -0
- package/src/local-server.mjs +169 -0
- package/src/lock.mjs +45 -0
- package/src/loop.mjs +838 -0
- package/src/mcp.mjs +604 -0
- package/src/memory.mjs +400 -0
- package/src/model.mjs +270 -0
- package/src/page.html +304 -0
- package/src/page.mjs +135 -0
- package/src/paths.mjs +33 -0
- package/src/prime.mjs +177 -0
- package/src/projects.mjs +232 -0
- package/src/recall.mjs +45 -0
- package/src/redact.mjs +173 -0
- package/src/render.mjs +45 -0
- package/src/route.mjs +287 -0
- package/src/sandbox.mjs +173 -0
- package/src/scan.mjs +204 -0
- package/src/scribe.mjs +349 -0
- package/src/sessions.mjs +371 -0
- package/src/setup.mjs +528 -0
- package/src/sqlite.mjs +66 -0
- package/src/text.mjs +97 -0
- package/src/tools.mjs +987 -0
- package/src/transcript.mjs +106 -0
- package/src/tty.mjs +529 -0
- package/src/ui.mjs +1363 -0
- package/src/verify.mjs +369 -0
- package/src/web.mjs +49 -0
- package/src/workflows.mjs +270 -0
- package/src/worktree.mjs +128 -0
package/src/jobtools.mjs
ADDED
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
import { rmSync, writeFileSync } from 'node:fs';
|
|
2
|
+
import { join } from 'node:path';
|
|
3
|
+
import { paths, SELF } from './paths.mjs';
|
|
4
|
+
import { capRedacted, checksWrap, runCommand } from './tools.mjs';
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* What a sub-agent notes, asks, reads memory and closes its job with: tools of
|
|
8
|
+
* its own, not `sumo job` commands it has to remember to type. Each runs the
|
|
9
|
+
* same `sumo` command a person would, in a process of its own — a worker's
|
|
10
|
+
* checks take minutes, and in this process they would stall every other job
|
|
11
|
+
* and the chat beside them.
|
|
12
|
+
*/
|
|
13
|
+
|
|
14
|
+
const text = (description) => ({ type: 'string', description });
|
|
15
|
+
const tool = (name, description, properties = {}, required = Object.keys(properties)) => ({ name, description, input_schema: { type: 'object', properties, required } });
|
|
16
|
+
|
|
17
|
+
const NOTE = tool('note', 'Keep one line of progress — what now works; next: the step — so a resumed run starts from it.', { text: text('the note') });
|
|
18
|
+
const ASK = tool('ask', 'Blocked on something only the user can decide: one question, then stop. You are resumed with the answer.', { question: text('the question') });
|
|
19
|
+
const SEARCH = tool('search_memory', "Search the user's memory: their rules, and this project's facts and traps. You never write it.", { query: text('a few words') });
|
|
20
|
+
const BASELINE = tool('baseline', "Before your first edit: run the project's checks and record what already fails, so none of it is blamed on you. Takes minutes.");
|
|
21
|
+
const VERIFY = tool('verify', "Run the project's checks now and see the verdict DONE will be given. Takes minutes.");
|
|
22
|
+
const FINISH = tool(
|
|
23
|
+
'finish',
|
|
24
|
+
"Close the job — the last thing you do, or nobody knows it ended. A worker's first DONE is answered with the task beside its change, to look over once; the next runs the project's checks and is refused while something new fails.",
|
|
25
|
+
// No way to take the work unverified: that is for the user or the main agent to grant, never the author.
|
|
26
|
+
{ status: { type: 'string', enum: ['DONE', 'FAILED'] }, report: text('the report, in the shape the brief gives') },
|
|
27
|
+
);
|
|
28
|
+
|
|
29
|
+
/** A role's job tools, in a fixed order so its cached prefix never moves. */
|
|
30
|
+
export const jobTools = (agent) => [...(agent === 'worker' ? [BASELINE, VERIFY] : []), NOTE, ASK, SEARCH, FINISH];
|
|
31
|
+
const NAMES = new Set([BASELINE, VERIFY, NOTE, ASK, SEARCH, FINISH].map((t) => t.name));
|
|
32
|
+
export const isJobTool = (call) => NAMES.has(call.name);
|
|
33
|
+
|
|
34
|
+
/** One word for the shell: left as it is when plain, single-quoted otherwise. */
|
|
35
|
+
const word = (w) => (/^[\w/.:=@%+-]+$/.test(w) ? w : `'${String(w).replaceAll("'", `'\\''`)}'`);
|
|
36
|
+
const sumo = (args) => [...SELF, ...args].map(word).join(' ');
|
|
37
|
+
|
|
38
|
+
/** The command a call stands for, and what it reads on stdin. Null for a call missing what it needs. */
|
|
39
|
+
function commandFor(call, job) {
|
|
40
|
+
const input = call.input ?? {};
|
|
41
|
+
const id = String(job.id);
|
|
42
|
+
const given = (v) => typeof v === 'string' && v.trim() !== '';
|
|
43
|
+
switch (call.name) {
|
|
44
|
+
case 'note':
|
|
45
|
+
return given(input.text) ? { args: ['job', 'note', id], stdin: input.text } : null;
|
|
46
|
+
case 'ask':
|
|
47
|
+
return given(input.question) ? { args: ['job', 'ask', id], stdin: input.question } : null;
|
|
48
|
+
case 'search_memory':
|
|
49
|
+
// The query comes after `--`: one that looks like a flag is still words to search for.
|
|
50
|
+
return given(input.query) ? { args: ['search', '--project', job.project, '--', input.query] } : null;
|
|
51
|
+
case 'baseline':
|
|
52
|
+
return { args: ['job', 'baseline', id], checks: true };
|
|
53
|
+
case 'verify':
|
|
54
|
+
return { args: ['job', 'verify', id], checks: true };
|
|
55
|
+
case 'finish':
|
|
56
|
+
if (!['DONE', 'FAILED'].includes(input.status) || !given(input.report)) return null;
|
|
57
|
+
return { args: ['job', 'finish', id, '--status', input.status], stdin: input.report, checks: true };
|
|
58
|
+
default:
|
|
59
|
+
return null;
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/** Runs one job tool call; what the command printed is the answer, and a refusal is an error the model can read. */
|
|
64
|
+
export async function runJobTool(call, { job, ctx, signal = null }) {
|
|
65
|
+
const command = commandFor(call, job);
|
|
66
|
+
if (!command) return { content: `${call.name} is missing what it needs: ${JSON.stringify(jobTools(job.agent).find((t) => t.name === call.name)?.input_schema.required ?? [])}`, isError: true };
|
|
67
|
+
// Text goes in by file: the command's stdin is closed, and nothing the model wrote is ever read by a shell.
|
|
68
|
+
const file = command.stdin === undefined ? null : join(paths().jobs, String(job.id), `.${call.id}.txt`);
|
|
69
|
+
if (file) writeFileSync(file, command.stdin, { mode: 0o600 });
|
|
70
|
+
try {
|
|
71
|
+
const args = file ? [...command.args, '--from-file', file] : command.args;
|
|
72
|
+
// The checks give each command its own limit; anything else is quick. They run the project's code — tests the model may have
|
|
73
|
+
// written among it — so they run in the sandbox its shell is in, writing only where it may: Sumo's home is one of those places,
|
|
74
|
+
// so the records are still written. A check that fails only for the sandbox fails so at the baseline and at the end alike.
|
|
75
|
+
const run = await runCommand(sumo(args), { cwd: ctx.cwd, env: ctx.env, signal, timeoutMs: command.checks ? null : 60_000, wrap: command.checks ? checksWrap(ctx) : null });
|
|
76
|
+
if (run.error) return { content: run.error, isError: true };
|
|
77
|
+
const output = capRedacted(run.output.trim(), undefined, run.omitted);
|
|
78
|
+
return { content: output || '(done)', isError: run.stopped !== null || run.status !== 0 };
|
|
79
|
+
} finally {
|
|
80
|
+
if (file) rmSync(file, { force: true });
|
|
81
|
+
}
|
|
82
|
+
}
|
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
import { spawn, spawnSync } from 'node:child_process';
|
|
2
|
+
import { closeSync, mkdirSync, openSync } from 'node:fs';
|
|
3
|
+
import { createServer } from 'node:net';
|
|
4
|
+
import { basename, join } from 'node:path';
|
|
5
|
+
import { getMeta, setMeta, tx } from './db.mjs';
|
|
6
|
+
import { paths } from './paths.mjs';
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* The one llama-server behind every local model call. It runs in router mode over the models directory,
|
|
10
|
+
* detached from whichever `sumo` needed it first, so the router and the memory passes share a model that
|
|
11
|
+
* is loaded once; it sleeps after SLEEP_IDLE_SECONDS (a few hundred MB resident, under a second to wake)
|
|
12
|
+
* instead of holding the model between calls. Where it is lives in meta, so every process finds the same one.
|
|
13
|
+
*/
|
|
14
|
+
const META_KEY = 'llama.server';
|
|
15
|
+
const HEALTH_TIMEOUT_MS = 60_000;
|
|
16
|
+
const HEALTH_POLL_MS = 250;
|
|
17
|
+
const SLEEP_IDLE_SECONDS = 600;
|
|
18
|
+
/** The context the server is given: the largest scribe bundle seen was 24k tokens, dream's 90th percentile 12k. */
|
|
19
|
+
export const LOCAL_CONTEXT_TOKENS = 32_768;
|
|
20
|
+
/** How long a pass may think. Measured on the scribe probe, the 4B model answers right within this; uncapped, a small model can think until the token limit and answer nothing. */
|
|
21
|
+
export const LOCAL_REASONING_BUDGET = 1024;
|
|
22
|
+
|
|
23
|
+
/** Router mode names a model after its file. */
|
|
24
|
+
export const modelIdOf = (file) => basename(file, '.gguf');
|
|
25
|
+
|
|
26
|
+
function alive(pid) {
|
|
27
|
+
try {
|
|
28
|
+
process.kill(pid, 0);
|
|
29
|
+
return true;
|
|
30
|
+
} catch (cause) {
|
|
31
|
+
return cause.code === 'EPERM';
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/** Only a process still carrying the port it was started on is ours: a pid can be reused once the server is gone. */
|
|
36
|
+
function ours(server) {
|
|
37
|
+
if (!alive(server.pid)) return false;
|
|
38
|
+
const ps = spawnSync('ps', ['-o', 'command=', '-p', String(server.pid)], { encoding: 'utf8' });
|
|
39
|
+
return (ps.stdout ?? '').includes(`--port ${server.port}`);
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
function recorded(db) {
|
|
43
|
+
try {
|
|
44
|
+
return JSON.parse(getMeta(db, META_KEY) ?? 'null');
|
|
45
|
+
} catch {
|
|
46
|
+
return null;
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
async function healthy(port, timeoutMs = HEALTH_POLL_MS * 4) {
|
|
51
|
+
try {
|
|
52
|
+
const res = await fetch(`http://127.0.0.1:${port}/health`, { signal: AbortSignal.timeout(timeoutMs) });
|
|
53
|
+
return res.ok && (await res.json())?.status === 'ok';
|
|
54
|
+
} catch {
|
|
55
|
+
return false;
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** A TCP port nothing is listening on yet, for llama-server to bind to. */
|
|
60
|
+
function freePort() {
|
|
61
|
+
return new Promise((resolve, reject) => {
|
|
62
|
+
const srv = createServer();
|
|
63
|
+
srv.on('error', reject);
|
|
64
|
+
srv.listen(0, '127.0.0.1', () => {
|
|
65
|
+
const { port } = srv.address();
|
|
66
|
+
srv.close(() => resolve(port));
|
|
67
|
+
});
|
|
68
|
+
});
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
function sleep(ms) {
|
|
72
|
+
return new Promise((resolve) => setTimeout(resolve, ms));
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/** Polls /health until it answers {"status":"ok"}, the server dies, or the budget runs out. */
|
|
76
|
+
async function waitForHealth(port, dead) {
|
|
77
|
+
const start = Date.now();
|
|
78
|
+
while (Date.now() - start < HEALTH_TIMEOUT_MS) {
|
|
79
|
+
if (dead()) throw new Error(`llama-server exited before it was healthy: ${dead()}`);
|
|
80
|
+
if (await healthy(port)) return;
|
|
81
|
+
await sleep(HEALTH_POLL_MS);
|
|
82
|
+
}
|
|
83
|
+
throw new Error(`llama-server did not become healthy within ${Math.round(HEALTH_TIMEOUT_MS / 1000)}s`);
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
/** Starts the server for `file`, detached, logging to logs/llama-server.log, and records it. */
|
|
87
|
+
function start(db, { llama, file, port }) {
|
|
88
|
+
const logs = paths().logs;
|
|
89
|
+
mkdirSync(logs, { recursive: true, mode: 0o700 });
|
|
90
|
+
const out = openSync(join(logs, 'llama-server.log'), 'a');
|
|
91
|
+
let dead = null;
|
|
92
|
+
let child;
|
|
93
|
+
try {
|
|
94
|
+
child = spawn(llama, [
|
|
95
|
+
'--models-dir', paths().models, '--host', '127.0.0.1', '--port', String(port),
|
|
96
|
+
'--sleep-idle-seconds', String(SLEEP_IDLE_SECONDS), '-c', String(LOCAL_CONTEXT_TOKENS), '-ngl', '99',
|
|
97
|
+
'--jinja', '--reasoning-budget', String(LOCAL_REASONING_BUDGET), '-np', '1',
|
|
98
|
+
], { detached: true, stdio: ['ignore', out, out] });
|
|
99
|
+
} finally {
|
|
100
|
+
closeSync(out);
|
|
101
|
+
}
|
|
102
|
+
// A binary that vanished between the check and the spawn, or a server that dies on start, must surface as an
|
|
103
|
+
// answer from the health wait, never as an unhandled 'error' event that takes sumo down with it.
|
|
104
|
+
child.on('error', (cause) => { dead = cause.message; });
|
|
105
|
+
child.on('exit', (code, signal) => { dead ??= `exit ${code ?? signal}`; });
|
|
106
|
+
child.unref();
|
|
107
|
+
const server = { pid: child.pid, port, file, llama, startedAt: Date.now() };
|
|
108
|
+
setMeta(db, META_KEY, JSON.stringify(server));
|
|
109
|
+
return { server, dead: () => dead };
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
/**
|
|
113
|
+
* The server to send this call to: the recorded one when it was started for this model and binary and still
|
|
114
|
+
* answers, otherwise a fresh one in its place. Two processes starting at once start one server between them:
|
|
115
|
+
* the check and the spawn are one transaction.
|
|
116
|
+
*/
|
|
117
|
+
export async function ensureLocalServer(db, { llama, file }) {
|
|
118
|
+
const current = recorded(db);
|
|
119
|
+
if (current && current.file === file && current.llama === llama && ours(current)) {
|
|
120
|
+
if (await healthy(current.port)) return current;
|
|
121
|
+
// Started a moment ago by another sumo and still coming up: wait for it rather than replace it.
|
|
122
|
+
if (Date.now() - current.startedAt < HEALTH_TIMEOUT_MS) {
|
|
123
|
+
await waitForHealth(current.port, () => (ours(current) ? null : 'exited'));
|
|
124
|
+
return current;
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
// Only the server judged stale above: another sumo may have replaced it since, and that one is not ours to end.
|
|
128
|
+
if (current) stopLocalServer(db, current);
|
|
129
|
+
const port = await freePort();
|
|
130
|
+
const { server, dead } = tx(db, () => {
|
|
131
|
+
const again = recorded(db);
|
|
132
|
+
if (again && again.file === file && again.llama === llama && ours(again)) return { server: again, dead: () => null };
|
|
133
|
+
return start(db, { llama, file, port });
|
|
134
|
+
});
|
|
135
|
+
await waitForHealth(server.port, dead);
|
|
136
|
+
return server;
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
/**
|
|
140
|
+
* Ends the recorded server, if it is still ours, and forgets it. Setup calls this: the model or the binary may have changed.
|
|
141
|
+
* Given `expected`, only that server: a record that has changed since it was read belongs to someone else's call.
|
|
142
|
+
*/
|
|
143
|
+
export function stopLocalServer(db, expected) {
|
|
144
|
+
const current = recorded(db);
|
|
145
|
+
if (!current) return;
|
|
146
|
+
if (expected && (current.pid !== expected.pid || current.startedAt !== expected.startedAt)) return;
|
|
147
|
+
if (ours(current)) {
|
|
148
|
+
try {
|
|
149
|
+
process.kill(current.pid, 'SIGTERM');
|
|
150
|
+
} catch {
|
|
151
|
+
// Gone between the check and the signal.
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
db.prepare('DELETE FROM meta WHERE key = ?').run(META_KEY);
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
/** One line for `sumo scribe status`: where the server is and what it says about the model. */
|
|
158
|
+
export async function localServerStatus(db, { file }) {
|
|
159
|
+
const current = recorded(db);
|
|
160
|
+
if (!current) return 'local server: not running (starts on the first call)';
|
|
161
|
+
if (!ours(current)) return `local server: gone (was pid ${current.pid}); starts again on the next call`;
|
|
162
|
+
try {
|
|
163
|
+
const res = await fetch(`http://127.0.0.1:${current.port}/v1/models`, { signal: AbortSignal.timeout(1000) });
|
|
164
|
+
const model = (await res.json()).data?.find((m) => m.id === modelIdOf(file));
|
|
165
|
+
return `local server: pid ${current.pid}, port ${current.port}, ${file} ${model?.status?.value ?? 'not listed — run: sumo setup'}`;
|
|
166
|
+
} catch {
|
|
167
|
+
return `local server: pid ${current.pid} on port ${current.port} is not answering`;
|
|
168
|
+
}
|
|
169
|
+
}
|
package/src/lock.mjs
ADDED
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
import { readFileSync, rmSync, writeFileSync } from 'node:fs';
|
|
2
|
+
import { UsageError } from './memory.mjs';
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* One holder per thing — a job's run, a chat session. The lock names the process that holds it, so one left behind
|
|
6
|
+
* by a process that died is seen for what it is and taken over. `busy(holder)` is what to say when a live process has it.
|
|
7
|
+
*/
|
|
8
|
+
export function takeLock(file, busy) {
|
|
9
|
+
for (let attempt = 0; ; attempt++) {
|
|
10
|
+
try {
|
|
11
|
+
writeFileSync(file, String(process.pid), { flag: 'wx', mode: 0o600 });
|
|
12
|
+
return file;
|
|
13
|
+
} catch (cause) {
|
|
14
|
+
if (cause.code !== 'EEXIST' || attempt > 0) throw cause;
|
|
15
|
+
const holder = heldBy(file);
|
|
16
|
+
if (holder) throw new UsageError(busy(holder));
|
|
17
|
+
rmSync(file, { force: true });
|
|
18
|
+
}
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/** The live process holding a lock, or null: no lock, or one a process died with in its hand. */
|
|
23
|
+
export function heldBy(file) {
|
|
24
|
+
const pid = holderOf(file);
|
|
25
|
+
return pid && alive(pid) ? pid : null;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/** The process a lock names; none when the run that held it ended between taking a look and reading it. */
|
|
29
|
+
function holderOf(file) {
|
|
30
|
+
try {
|
|
31
|
+
return Number(readFileSync(file, 'utf8'));
|
|
32
|
+
} catch (cause) {
|
|
33
|
+
if (cause.code === 'ENOENT') return 0;
|
|
34
|
+
throw cause;
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
function alive(pid) {
|
|
39
|
+
try {
|
|
40
|
+
process.kill(pid, 0);
|
|
41
|
+
return true;
|
|
42
|
+
} catch (cause) {
|
|
43
|
+
return cause.code === 'EPERM';
|
|
44
|
+
}
|
|
45
|
+
}
|