@voidlabs.gg/voidshift-agents 0.6.0 → 0.8.0

package/dist/engine.js

@@ -2,15 +2,29 @@ import { spawn } from 'node:child_process';
 import { createWriteStream, mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { usageText } from "./state.js";
 // Tools a write step may use under `claude -p`. Anything else is denied,
 // since nobody is there to approve it.
 const CLAUDE_WRITE = ['Read', 'Glob', 'Grep', 'Edit', 'Write', 'Bash'];
 const CLAUDE_READ = ['Read', 'Glob', 'Grep', 'Bash(git diff:*)', 'Bash(git log:*)', 'Bash(git show:*)', 'Bash(npm test:*)', 'Bash(npm run:*)', 'Bash(pnpm:*)', 'Bash(yarn:*)', 'Bash(npx:*)', 'Bash(node:*)', 'Bash(ls:*)', 'Bash(rg:*)'];
 export function engineArgs(o, outFile) {
+    // Nobody is there to approve a prompt, and an allowlist that misses a tool
+    // breaks the run, so on Linux every step runs with permissions skipped.
+    const skip = (o.platform ?? process.platform) === 'linux';
+    if (o.engine === 'claude' && skip) {
+        const args = ['-p', '--output-format', 'json', '--dangerously-skip-permissions'];
+        if (o.vault)
+            args.push('--add-dir', o.vault);
+        if (o.model)
+            args.push('--model', o.model);
+        if (o.settingsFile)
+            args.push('--settings', o.settingsFile);
+        return { cmd: 'claude', args };
+    }
     if (o.engine === 'claude') {
         // Edit rules cover every file-writing tool; a Write(path) rule is ignored.
         const vaultTools = o.vault ? [`Edit(/${o.vault}/**)`] : [];
-        const args = ['-p', '--output-format', 'text', '--allowedTools', [...(o.write ? CLAUDE_WRITE : CLAUDE_READ), ...vaultTools].join(',')];
+        const args = ['-p', '--output-format', 'json', '--allowedTools', [...(o.write ? CLAUDE_WRITE : CLAUDE_READ), ...vaultTools].join(',')];
         if (o.vault)
             args.push('--add-dir', o.vault);
         if (o.write)
@@ -21,6 +35,13 @@ export function engineArgs(o, outFile) {
             args.push('--settings', o.settingsFile);
         return { cmd: 'claude', args };
     }
+    if (skip) {
+        const args = ['exec', '-C', o.cwd, '--dangerously-bypass-approvals-and-sandbox', '-o', outFile];
+        if (o.model)
+            args.push('-m', o.model);
+        args.push('-');
+        return { cmd: 'codex', args };
+    }
     const args = ['exec', '-C', o.cwd, '-s', o.write ? 'workspace-write' : 'read-only', '-o', outFile];
     // A read-only sandbox cannot write anywhere, so only write steps get the vault.
     if (o.vault && o.write)
@@ -49,8 +70,52 @@ export async function stopAgents() {
         if (c.exitCode === null && c.signalCode === null)
             c.kill('SIGKILL');
 }
+// Why a failed agent process failed: the last lines it wrote to stderr.
+export function errorTail(stderr) {
+    const lines = stderr.split('\n').map((l) => l.trim()).filter(Boolean);
+    let out = '';
+    for (const line of lines.reverse()) {
+        const next = out ? `${line} ${out}` : line;
+        if (next.length > 300)
+            break;
+        out = next;
+    }
+    return out || lines[0]?.slice(-300) || '';
+}
+// Claude's JSON answer: its final text, and the tokens and cost it spent.
+// Null when the output is not that JSON, so it is taken as plain text.
+export function parseClaudeJson(stdout) {
+    let j;
+    try {
+        j = JSON.parse(stdout);
+    }
+    catch {
+        return null;
+    }
+    if (!j || typeof j !== 'object' || typeof j.result !== 'string')
+        return null;
+    const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+    const usage = {};
+    const models = j.modelUsage && typeof j.modelUsage === 'object' ? Object.entries(j.modelUsage) : [];
+    if (models.length) {
+        // Every model the step used, side models included.
+        usage.input = models.reduce((t, [, m]) => t + num(m?.inputTokens), 0);
+        usage.output = models.reduce((t, [, m]) => t + num(m?.outputTokens), 0);
+        usage.cached = models.reduce((t, [, m]) => t + num(m?.cacheReadInputTokens) + num(m?.cacheCreationInputTokens), 0);
+        usage.model = models.reduce((best, cur) => (num(cur[1]?.costUSD) > num(best[1]?.costUSD) ? cur : best))[0];
+    }
+    else if (j.usage && typeof j.usage === 'object') {
+        usage.input = num(j.usage.input_tokens);
+        usage.output = num(j.usage.output_tokens);
+        usage.cached = num(j.usage.cache_read_input_tokens) + num(j.usage.cache_creation_input_tokens);
+    }
+    if (typeof j.total_cost_usd === 'number')
+        usage.costUsd = j.total_cost_usd;
+    return { text: j.result, isError: j.is_error === true, usage };
+}
 // Runs one agent step with the prompt on stdin. Resolves with the agent's
-// final text; everything it prints also goes to the log file.
+// final text; what it prints also goes to the log file, Claude's answer as
+// its text and a usage line. A process that fails also says why in `error`.
 export function runAgent(o) {
     const dir = mkdtempSync(join(tmpdir(), 'voidshift-run-'));
     const outFile = join(dir, 'last.txt');
@@ -63,24 +128,52 @@ export function runAgent(o) {
         const env = { ...process.env, VOIDSHIFT_RECALL: 'off' };
         const child = spawn(cmd, args, { cwd: o.cwd, env, stdio: ['pipe', 'pipe', 'pipe'] });
         track(child);
+        // Claude's JSON comes at exit, so it is held and logged as text then.
         let stdout = '';
         child.stdout.on('data', (d) => {
             stdout += d;
+            if (o.engine !== 'claude')
+                log.write(d);
+        });
+        // Only the tail is kept; the log has all of it.
+        let stderr = '';
+        child.stderr.on('data', (d) => {
+            stderr = (stderr + d).split('\n').slice(-20).join('\n');
             log.write(d);
         });
-        child.stderr.on('data', (d) => log.write(d));
-        const timer = setTimeout(() => child.kill('SIGTERM'), o.timeoutMs ?? 45 * 60_000);
+        const timeoutMs = o.timeoutMs ?? 45 * 60_000;
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGTERM');
+        }, timeoutMs);
         child.on('error', (err) => {
             clearTimeout(timer);
             children.delete(child);
             log.end(`\n${err.message}\n`);
-            resolve({ ok: false, output: err.message });
+            resolve({ ok: false, output: err.message, error: err.message });
         });
         child.on('close', (code) => {
             clearTimeout(timer);
             children.delete(child);
-            log.end(`\nexit ${code}\n`);
             let output = stdout;
+            let usage;
+            let failure = '';
+            if (o.engine === 'claude') {
+                const parsed = parseClaudeJson(stdout);
+                if (parsed) {
+                    output = parsed.text;
+                    if (Object.keys(parsed.usage).length)
+                        usage = parsed.usage;
+                    if (parsed.isError)
+                        failure = parsed.text;
+                    log.write(`${output}\n\nusage: ${[usageText(usage), usage?.model].filter(Boolean).join(', ') || 'none reported'}\n`);
+                }
+                else
+                    log.write(stdout);
+            }
+            else if (o.model)
+                usage = { model: o.model };
             if (o.engine === 'codex') {
                 try {
                     output = readFileSync(outFile, 'utf8');
@@ -90,8 +183,52 @@ export function runAgent(o) {
                 }
             }
             rmSync(dir, { recursive: true, force: true });
-            resolve({ ok: code === 0, output });
+            const minutes = Math.round(timeoutMs / 60_000);
+            const error = code === 0 ? undefined : timedOut ? `timed out after ${minutes} minute${minutes === 1 ? '' : 's'}` : errorTail(stderr) || errorTail(failure) || `exit ${code}`;
+            // Settled once the log is written, so the step's log is whole when read.
+            log.end(`\nexit ${code}\n`, () => resolve({ ok: code === 0, output, ...(error ? { error } : {}), ...(usage ? { usage } : {}) }));
         });
         child.stdin.end(o.prompt);
     });
 }
+// Runs one command step in a shell in place of an agent. Resolves with what it
+// printed on stdout, which is also logged along with stderr; a command that
+// fails also says why in `error`.
+export function runCommand(o) {
+    const log = createWriteStream(o.logFile, { flags: 'a' });
+    log.write(`$ ${o.command}\n\n`);
+    return new Promise((resolve) => {
+        const child = spawn('sh', ['-c', o.command], { cwd: o.cwd, env: { ...process.env, ...o.env }, stdio: ['ignore', 'pipe', 'pipe'] });
+        track(child);
+        let stdout = '';
+        child.stdout.on('data', (d) => {
+            stdout += d;
+            log.write(d);
+        });
+        // Only the tail is kept; the log has all of it.
+        let stderr = '';
+        child.stderr.on('data', (d) => {
+            stderr = (stderr + d).split('\n').slice(-20).join('\n');
+            log.write(d);
+        });
+        const timeoutMs = o.timeoutMs ?? 45 * 60_000;
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGTERM');
+        }, timeoutMs);
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            children.delete(child);
+            log.end(`\n${err.message}\n`);
+            resolve({ ok: false, output: err.message, error: err.message });
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            children.delete(child);
+            const minutes = Math.round(timeoutMs / 60_000);
+            const error = code === 0 ? undefined : timedOut ? `timed out after ${minutes} minute${minutes === 1 ? '' : 's'}` : errorTail(stderr) || `exit ${code}`;
+            log.end(`\nexit ${code}\n`, () => resolve({ ok: code === 0, output: stdout, ...(error ? { error } : {}) }));
+        });
+    });
+}

package/dist/git.d.ts

@@ -34,3 +34,4 @@ export interface CommitPolicy {
 }
 export declare function applyPolicy(message: string, policy: CommitPolicy, signer: string | null, cwd: string): string;
 export declare function enforceCommitPolicy(worktree: string, from: string, policy: CommitPolicy): number;
+export declare function removeWorktree(repo: string, worktree: string, branch: string): void;

package/dist/git.js

@@ -194,3 +194,8 @@ export function enforceCommitPolicy(worktree, from, policy) {
         must(sh('git', ['reset', '-q', '--soft', head], worktree), 'git reset');
     return changed;
 }
+// Removes a worktree and its branch. Errors are ignored: either may be gone already.
+export function removeWorktree(repo, worktree, branch) {
+    sh('git', ['worktree', 'remove', '--force', worktree], repo);
+    sh('git', ['branch', '-D', branch], repo);
+}

package/dist/index.js

@@ -9,6 +9,7 @@ import { controlChecks, controlCommands, controlUsage } from "./control.js";
 import { keyStore, looksLikeLinearKey, readLinearKey, readSecret, storeLinearKey, storeSecret } from "./secrets.js";
 import { TRACKERS } from "./tracker.js";
 import { createVoidTrack } from "./voidtrack.js";
+import { addWebhook, dropWebhook, looksLikeWebhook, moveWebhook, removeWebhook, testWebhook, webhookFor } from "./notify.js";
 import { parseCron } from "./cron.js";
 import { trackersInUse } from "./control.js";
 import { runnerService } from "./service.js";
@@ -379,6 +380,7 @@ const USAGE = [
     ['link DIR [--claude | --codex]', 'Link the agents into a config folder'],
     ['unlink DIR', 'Remove the agents from a config folder'],
     ['key [--voidtrack]', 'Store or replace the Linear or VoidTrack API key (reads stdin without a terminal)'],
+    ['discord [--workflow W] [--test] [--rm]', 'Store, test or remove the Discord webhook for run pings, global or for one workflow; it is stored only after a test message goes through (reads stdin without a terminal)'],
     ['profile [init]', `Your profile: rules (${RULES_FILE}) and Claude settings (${CLAUDE_SETTINGS}) every agent run carries; init creates it`],
     ['validate [DIR]', `Check an agent folder (DIR/${AGENT_FILE} and its prompts), or the config and every folder under agents/defs`],
     ['help [COMMAND]', 'Show this list, or one command'],
@@ -662,8 +664,14 @@ const workflowSubs = {
             if (!teams)
                 return 1;
             const r = await promptWorkflow(ctx.ui, config, teams, { name, workflow: current }, true);
-            if (r.name !== name)
+            if (r.name !== name) {
+                const refused = moveWebhook(ctx.configDir, name, r.name);
+                if (refused) {
+                    ctx.log(refused);
+                    return 1;
+                }
                 config.workflows = renameKey(config.workflows, name, r.name);
+            }
             config.workflows[r.name] = r.workflow;
             return saveWorkflow(config, r.name, r.workflow, ctx);
         }
@@ -716,6 +724,11 @@ const workflowSubs = {
             ctx.log(`A workflow named ${next} already exists.`);
             return 1;
         }
+        const refused = moveWebhook(ctx.configDir, old, next);
+        if (refused) {
+            ctx.log(refused);
+            return 1;
+        }
         config.workflows = renameKey(config.workflows, old, next);
         save(ctx, config);
         ctx.log(`Workflow ${old} is now ${next}.`);
@@ -742,6 +755,7 @@ const workflowSubs = {
         }
         delete config.workflows[name];
         save(ctx, config);
+        dropWebhook(ctx.configDir, name);
         ctx.log(`Deleted workflow ${name}.`);
         return 0;
     },
@@ -1220,6 +1234,11 @@ const agents = {
             if (!(await setupKey(ui, ctx.configDir, 'voidtrack')))
                 ctx.log('VoidTrack is not connected yet. Run vsf agents key --voidtrack.');
         }
+        if (!webhookFor(ctx.configDir) && (await ui.confirm('Send run pings to Discord?', false))) {
+            const url = await ui.secret('Paste the Discord webhook URL', (v) => (looksLikeWebhook(v.trim()) ? undefined : 'Not a Discord webhook URL'));
+            if (!(await addWebhook(ctx.configDir, url.trim(), undefined, ui.info)))
+                ctx.log('Discord is not connected. Run vsf agents discord to retry.');
+        }
         if (Object.keys(config.workflows).length && (await ui.confirm('Start the background runner now? Every minute it checks for cards and schedules that start your workflows.'))) {
             const ok = runnerService().start(ctx.home, [...ctx.selfCommand, 'agents', 'tick'], join(agentsDir(ctx.configDir), 'runner.log'));
             ctx.log(ok ? 'Runner started.' : 'Could not start the runner. Try vsf agents start.');
@@ -1258,6 +1277,8 @@ const agents = {
                 checks.push({ name, status: 'fail', detail: err.message, fix: `vsf agents key${kind === 'linear' ? '' : ` --${kind}`}` });
             }
         }
+        if (webhookFor(ctx.configDir))
+            checks.push({ name: 'discord', status: 'ok', detail: 'webhook set' });
         const workflows = Object.entries(saved.workflows);
         const broken = workflows.filter(([, c]) => !saved.projects[c.project] || !isRepo(saved.projects[c.project].path)).map(([n]) => n);
         checks.push(!workflows.length
@@ -1389,6 +1410,38 @@ const agents = {
             }
             return (await verifyAndStore(ctx.configDir, key, ctx.log, ctx.log, kind)) ? 0 : 1;
         },
+        async discord(args, ctx) {
+            const p = begin('discord', args, { workflow: { type: 'string' }, test: { type: 'boolean' }, rm: { type: 'boolean' } }, ctx);
+            if (typeof p === 'number')
+                return p;
+            if (p.positionals.length) {
+                ctx.log('Webhooks are not accepted on the command line. Pipe the URL in instead.');
+                return 2;
+            }
+            if (p.values.test && p.values.rm) {
+                ctx.log('Give --test or --rm, not both.');
+                return 2;
+            }
+            let workflow;
+            if (p.values.workflow) {
+                const name = pickWorkflow(readAgentsConfig(ctx.configDir), p.values.workflow, ctx);
+                if (!name)
+                    return 1;
+                workflow = name;
+            }
+            if (p.values.test)
+                return (await testWebhook(ctx.configDir, workflow, ctx.log)) ? 0 : 1;
+            if (p.values.rm)
+                return removeWebhook(ctx.configDir, workflow, ctx.log) ? 0 : 1;
+            const url = interactive()
+                ? await ctx.ui.secret('Paste the Discord webhook URL', (v) => (looksLikeWebhook(v.trim()) ? undefined : 'Not a Discord webhook URL'))
+                : readFileSync(0, 'utf8');
+            if (!url.trim()) {
+                ctx.log('No webhook on stdin.');
+                return 2;
+            }
+            return (await addWebhook(ctx.configDir, url.trim(), workflow, ctx.log)) ? 0 : 1;
+        },
         async help(args, ctx) {
             const want = args.join(' ').trim();
             if (!want) {

package/dist/manage.d.ts

@@ -1,6 +1,6 @@
 import { type AgentsConfig, type Step, type Trigger, type Workflow } from './config.ts';
-export declare function validateStep(step: Step, config: Pick<AgentsConfig, 'enabled'>, dir?: string): string[];
-export declare function validateWorkflow(config: Pick<AgentsConfig, 'enabled' | 'projects'>, workflow: Workflow, dir?: string): string[];
+export declare function validateStep(step: Step, config: Pick<AgentsConfig, 'enabled'> & Partial<Pick<AgentsConfig, 'workflows'>>, dir?: string): string[];
+export declare function validateWorkflow(config: Pick<AgentsConfig, 'enabled' | 'projects'> & Partial<Pick<AgentsConfig, 'workflows'>>, workflow: Workflow, dir?: string): string[];
 export declare function validateAgentFolder(dir: string, config: Pick<AgentsConfig, 'enabled' | 'projects' | 'workflows' | 'folders'>): string[];
 export declare const TRIGGER_FORMS = "TEAM:LABEL (Linear), voidtrack:TEAM:LABEL, or cron:SCHEDULE:TASK";
 export declare function parseTrigger(input: string): Trigger | null;

package/dist/manage.js

@@ -29,13 +29,25 @@ export function validateStep(step, config, dir) {
         problems.push(`${name} prompt must be a file name.`);
     if (step.skill !== undefined && typeof step.skill !== 'string')
         problems.push(`${name} skill must be a name or a folder.`);
-    const sources = [step.skill, step.prompt].filter((v) => v !== undefined).length;
+    if (step.run !== undefined && (typeof step.run !== 'string' || !step.run.trim()))
+        problems.push(`${name} run must be a command.`);
+    if (step.handoff !== undefined) {
+        if (typeof step.handoff !== 'string' || !step.handoff.trim())
+            problems.push(`${name} handoff must be a workflow name.`);
+        else if (config.workflows && !Object.hasOwn(config.workflows, step.handoff))
+            problems.push(`${name} hands cards to ${step.handoff}, which is not a workflow.`);
+    }
+    const sources = [step.skill, step.prompt, step.run].filter((v) => v !== undefined).length;
     if (step.output === 'publish') {
         if (sources)
-            problems.push(`${name} only pushes the branch, so it takes no skill or prompt.`);
+            problems.push(`${name} only pushes the branch, so it takes no skill, prompt or run.`);
     }
     else if (sources !== 1)
-        problems.push(`${name} needs exactly one of skill or prompt.`);
+        problems.push(`${name} needs exactly one of skill, prompt or run.`);
+    else if (step.run !== undefined) {
+        if (step.output !== 'none')
+            problems.push(`${name} runs a command, so its output must be none.`);
+    }
     else if (typeof (step.prompt ?? step.skill) === 'string') {
         const file = stepFile(step, dir);
         if (!file || !existsSync(file))
@@ -121,8 +133,8 @@ export function validateAgentFolder(dir, config) {
     catch (err) {
         return [`${AGENT_FILE}: ${err.message}`];
     }
-    const problems = validateWorkflow(config, workflow, dir);
     const name = basename(dir);
+    const problems = validateWorkflow({ ...config, workflows: { ...config.workflows, [name]: workflow } }, workflow, dir);
     const from = config.folders?.[name];
     if (config.workflows[name] && (!from || resolve(from) !== resolve(dir)))
         problems.push(`config.json already has a workflow named ${name}, and it wins. Rename the folder.`);
@@ -228,6 +240,10 @@ export function validateConfig(value, saved) {
         problems.push('reviewState must be a non-empty string.');
     if (!isInt(value.timeoutMinutes, 1, 480))
         problems.push('timeoutMinutes must be a whole number from 1 to 480.');
+    if (value.maxRuns !== undefined && !isInt(value.maxRuns, 0, 32))
+        problems.push('maxRuns must be a whole number from 0 to 32, 0 for no cap.');
+    if (value.pauseAt !== undefined && !isInt(value.pauseAt, 0, 100))
+        problems.push('pauseAt must be a whole number from 0 to 100, 0 to never hold.');
     const projects = isObj(value.projects) ? value.projects : null;
     if (!projects)
         problems.push('projects must be an object.');
@@ -263,7 +279,7 @@ export function validateConfig(value, saved) {
     if (!isObj(value.workflows))
         problems.push('workflows must be an object.');
     else {
-        const ctx = { enabled: Array.isArray(value.enabled) ? value.enabled : [], projects: (projects ?? {}) };
+        const ctx = { enabled: Array.isArray(value.enabled) ? value.enabled : [], projects: (projects ?? {}), workflows: value.workflows };
         for (const [name, w] of Object.entries(value.workflows)) {
             // Folder workflows are checked with their folder, by vsf agents validate.
             if (isObj(value.folders) && value.folders[name])

package/dist/notify.d.ts

@@ -0,0 +1,30 @@
+export declare const looksLikeWebhook: (url: string) => boolean;
+export declare const slug: (name: string) => string;
+export declare const webhookFor: (configDir: string, workflow?: string, platform?: NodeJS.Platform) => string | null;
+export declare function postDiscord(url: string, content: string, fetcher?: typeof fetch, timeoutMs?: number): Promise<string | null>;
+export type RunKind = 'ready' | 'passed' | 'parked' | 'failed';
+export interface RunEvent {
+    kind: RunKind;
+    card: string;
+    title: string;
+    workflow: string;
+    url?: string;
+    prUrl?: string;
+    reason?: string;
+}
+export declare function runMessage(e: RunEvent): string;
+export declare function notifyRun(configDir: string, e: RunEvent, log: (line: string) => void, fetcher?: typeof fetch, platform?: NodeJS.Platform): Promise<void>;
+export declare function notifyRunner(configDir: string, paused: boolean, reason: string, log: (line: string) => void, fetcher?: typeof fetch, platform?: NodeJS.Platform): Promise<void>;
+export interface NotifyState {
+    summaryDay?: string;
+    summaryAt?: string;
+}
+export declare function readNotifyState(configDir: string): NotifyState;
+export declare function writeNotifyState(configDir: string, state: NotifyState): void;
+export declare function summaryMessage(configDir: string, since: Date, paused: boolean): string | null;
+export declare function sendSummary(configDir: string, paused: boolean, log: (line: string) => void, now?: Date, fetcher?: typeof fetch, platform?: NodeJS.Platform): Promise<void>;
+export declare function addWebhook(configDir: string, url: string, workflow: string | undefined, log: (line: string) => void, fetcher?: typeof fetch, platform?: NodeJS.Platform): Promise<boolean>;
+export declare function testWebhook(configDir: string, workflow: string | undefined, log: (line: string) => void, fetcher?: typeof fetch, platform?: NodeJS.Platform): Promise<boolean>;
+export declare function removeWebhook(configDir: string, workflow: string | undefined, log: (line: string) => void, platform?: NodeJS.Platform): boolean;
+export declare function moveWebhook(configDir: string, from: string, to: string, platform?: NodeJS.Platform): string | null;
+export declare function dropWebhook(configDir: string, workflow: string, platform?: NodeJS.Platform): void;