@voidlabs.gg/voidshift-agents 0.6.0 → 0.8.0

package/README.md

@@ -103,6 +103,15 @@ vsf agents project edit erp --workspace solvia --match DS06
 Atleurope ERP"). A card of that project runs in the matching project, in any
 workspace, before the workflow's own project is considered.
 
+Two settings keep runs inside your Claude subscription. `vsf config set
+agents.maxRuns 2` caps how many cards run at once over every workspace (0, the
+default, is no cap). Every 5 minutes the runner reads your 5 hour window with
+Claude Code's login, read only, and once it reaches `agents.pauseAt` percent
+(90 by default, 0 turns it off) no new run starts until the window resets;
+running cards finish. `vsf agents status` shows the window, and each run's
+`run.json` keeps the tokens and estimated cost of every step. Naming a card,
+`vsf agents run CARD`, starts it anyway.
+
 A workflow can also be a folder you write by hand,
 `~/.config/voidshift/agents/defs/NAME/agent.json`, with its prompt files next to
 it. Steps are the built-in ids above or your own:
@@ -127,6 +136,20 @@ verified card there (`null` never moves it), `labels: false` only takes the
 trigger label off, and `comment: false` skips the closing comment. Edit the file,
 then `vsf agents validate`.
 
+A step can run a shell command instead of an agent: `"run": "node sweep.mjs"`
+with `output: "none"`. Exit 0 is done, anything else fails the run, and the last
+line it prints is the step's summary. A run made only of command steps works in
+the project folder, with no worktree or branch. A step with `"handoff": "WORKFLOW"`
+hands cards on: every `HANDOFF: ENG-12` line in its output queues that card for
+the named workflow, which runs it as a run of its own, label or not. The card
+leaves the queue once its run has started.
+
+Scheduled runs are jobs: `vsf agents status` shows one line per job, the Runs
+list keeps to card runs (`vsf agents runs --jobs` lists the scheduled ones), and
+a scheduled run that opened no pull request removes its worktree and branch. A
+run whose process ends without an outcome is closed as failed on the runner's
+next pass.
+
 ### memory
 
 A folder of markdown notes, one topic per note, with an `INDEX.md` holding one
@@ -182,6 +205,14 @@ DCO. Only the new commits of that step are rewritten, never pushed ones.
 - **Your config** lives in `~/.config/voidshift`.
 - **Linux.** The runner is a systemd user timer. Run
   `sudo loginctl enable-linger $USER` so it keeps going after you log out.
+  Agents there run with permissions skipped (`--dangerously-skip-permissions`
+  for Claude, `--dangerously-bypass-approvals-and-sandbox` for Codex), so no
+  step ever waits on a prompt and the runner's user account is the boundary.
+  Run it as a dedicated user with no sudo that holds only the keys it needs,
+  never as root, and enable lingering for it from an admin account
+  (`sudo loginctl enable-linger <user>`). `vsf doctor` warns when the runner
+  user has sudo. A step that fails shows its error in the run log, on the card
+  and in Discord.
 
 ```sh
 vsf doctor                     # check everything is set up, and whether an update is out

package/dist/config.d.ts

@@ -14,6 +14,8 @@ export interface StepDef {
     label?: string;
     skill?: string;
     prompt?: string;
+    run?: string;
+    handoff?: string;
     output: Output;
     engine?: Engine;
     model?: string;
@@ -94,6 +96,8 @@ export interface AgentsConfig {
         signOff?: boolean;
         dropAiTrailers?: boolean;
     };
+    maxRuns?: number;
+    pauseAt?: number;
     folders?: Record<string, string>;
 }
 export declare const TEMPLATES: Record<string, {
@@ -133,6 +137,8 @@ export interface ResolvedStep {
     write: boolean;
     prompt: () => string;
     builtin?: StepId;
+    command?: string;
+    handoff?: string;
 }
 export declare function stepFile(step: StepDef, dir?: string): string | null;
 export declare function resolveStep(step: Step, config: Pick<AgentsConfig, 'engine' | 'models' | 'timeoutMinutes'>, dir?: string): ResolvedStep;

package/dist/config.js

@@ -62,6 +62,8 @@ export const DEFAULTS = {
     timeoutMinutes: 45,
     homes: [],
     enabled: [],
+    maxRuns: 0,
+    pauseAt: 90,
 };
 export const agentsDir = (configDir) => join(configDir, 'agents');
 const configPath = (configDir) => join(agentsDir(configDir), 'config.json');
@@ -221,6 +223,14 @@ export function resolveStep(step, config, dir) {
             timeoutMs: config.timeoutMinutes * 60_000, write: s.write, prompt: () => readFileSync(packSkill(step), 'utf8'), builtin: step,
         };
     }
+    // A command step runs a shell command, so it has no prompt.
+    if (step.run) {
+        return {
+            id: step.id, label: step.label ?? step.id, output: step.output, engine: step.engine ?? config.engine,
+            model: step.model ?? config.models.dev, timeoutMs: (step.timeoutMinutes ?? config.timeoutMinutes) * 60_000,
+            write: step.write ?? false, command: step.run, prompt: () => '', handoff: step.handoff,
+        };
+    }
     return {
         id: step.id,
         label: step.label ?? step.id,
@@ -235,5 +245,6 @@ export function resolveStep(step, config, dir) {
                 throw new Error(`Step ${step.id} has no prompt or skill.`);
             return readFileSync(file, 'utf8');
         },
+        handoff: step.handoff,
     };
 }

package/dist/control.d.ts

@@ -11,6 +11,7 @@ export declare function countRounds(steps: {
     result?: string;
 }[]): number;
 export declare const isInterrupted: (e: RunEntry, live: Current[]) => boolean;
+export declare const shownOutcome: (e: RunEntry, live: Current[]) => string;
 export declare function formatRunLine(e: RunEntry, now?: number, live?: Current[]): string;
 export declare function scanRunnerErrors(text: string, now: number): {
     count: number;
@@ -28,12 +29,31 @@ export declare function trackerWarnings(kinds: Kind[], trackers: Trackers): Prom
     kind: Kind;
     message: string;
 }[]>;
+export declare function changePaused(ctx: Pick<ToolContext, 'configDir' | 'log'>, paused: boolean, reason: string, fetcher?: typeof fetch, platform?: NodeJS.Platform): Promise<void>;
 export declare function workingLine(current: (Current & {
     elapsedMinutes: number;
 }) | null): string;
 export declare function workspaceLines(workspaces: string[], running: (Current & {
     elapsedMinutes: number;
 })[]): string[];
+interface JobSummary {
+    workflow: string;
+    schedule: string;
+    task: string;
+    last: {
+        at: string;
+        outcome: string;
+        reason?: string;
+        summary?: string;
+    } | null;
+    lastOkAt: string | null;
+    today: {
+        runs: number;
+        failed: number;
+        handed: number;
+    };
+}
+export declare function jobSummaries(config: Pick<AgentsConfig, 'workflows'>, all: RunEntry[], live: Current[], now?: number): JobSummary[];
 export declare function pickCancel(locks: Current[], dispatcher: Current | null, card?: string): Current | string;
 export declare const controlCommands: Record<string, ToolCommand>;
 export declare function controlChecks(ctx: ToolContext): Promise<Check[]>;

package/dist/control.js

@@ -2,13 +2,15 @@ import { spawnSync } from 'node:child_process';
 import { closeSync, existsSync, openSync, readFileSync, readSync, readdirSync, rmSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { parseArgs } from 'node:util';
-import { agentsDir, isCardTrigger, readAgentsConfig, workspaceOf, workspacesInUse } from "./config.js";
-import { isPaused, listRuns, ours, clearLock, liveCurrent, liveRuns, readCurrent, setPaused, workspaceLocks, writeRun } from "./state.js";
+import { DEFAULTS, agentsDir, isCardTrigger, readAgentsConfig, workspaceOf, workspacesInUse } from "./config.js";
+import { STOPPED_REASON, isPaused, lastSeen, listRuns, ours, clearLock, liveCurrent, liveRuns, readCurrent, readWindow, setPaused, usageText, workspaceLocks, writeRun } from "./state.js";
+import { windowHold, windowLine } from "./usage.js";
 import { runnerService } from "./service.js";
 import { TRACKERS, trackersFor } from "./tracker.js";
 import { parseFrom, resolveName, stepNames } from "./names.js";
 import { isStatusLabel } from "./workflow.js";
-import { cancelCard, dispatch, tick } from "./runner.js";
+import { cancelCard, dispatch, gateReason, tick } from "./runner.js";
+import { notifyRun, notifyRunner, sendSummary } from "./notify.js";
 const HOUR = 3_600_000;
 const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
 const CARD_ID = /^[A-Za-z][A-Za-z0-9]*-\d+$/;
@@ -80,13 +82,15 @@ export function countRounds(steps) {
 }
 // A run that says 'running' but is none of the live runs was cut off.
 export const isInterrupted = (e, live) => e.record?.outcome === 'running' && !live.some((l) => (l.runDir ? l.runDir === e.dir : l.card === e.card));
+// The record's outcome, except a run cut off without a live process, which failed.
+export const shownOutcome = (e, live) => (isInterrupted(e, live) ? 'failed' : e.record.outcome);
 export function formatRunLine(e, now = Date.now(), live = []) {
     const r = e.record;
     if (!r)
         return `${e.card}  ${when(stampDate(e.stamp))}  older run, logs only (${plural(e.logs.length, 'log')})`;
     const rounds = countRounds(r.steps);
-    const end = r.endedAt ? Date.parse(r.endedAt) : now;
-    const parts = [e.card, when(new Date(r.startedAt)), r.workflow, r.steps.map((s) => s.label).join(' → '), isInterrupted(e, live) ? 'interrupted' : r.outcome];
+    const end = r.endedAt ? Date.parse(r.endedAt) : isInterrupted(e, live) ? Date.parse(lastSeen(r)) : now;
+    const parts = [e.card, when(new Date(r.startedAt)), r.workflow, r.steps.map((s) => s.label).join(' → '), shownOutcome(e, live)];
     if (rounds)
         parts.push(plural(rounds, 'round'));
     parts.push(formatDuration(end - Date.parse(r.startedAt)));
@@ -121,16 +125,16 @@ const readLog = (configDir) => {
     }
 };
 const USAGE = {
-    status: 'status [--json]   Runner, the card each workspace is on, parked cards and workflows',
+    status: 'status [--json]   Runner, the card each workspace is on, failed and parked cards, scheduled jobs and workflows',
     start: 'start   Start the background runner',
     stop: 'stop   Stop the runner and cancel the cards it is working on',
     restart: 'restart   Stop and start the runner',
     pause: 'pause   Pick up no new cards; a card in progress carries on',
     resume: 'resume   Pick up new cards again',
-    run: 'run [CARD] [--workflow W] [--from STEP]   Run now instead of waiting for the next minute',
+    run: 'run [CARD] [--workflow W] [--from STEP]   Run now instead of waiting for the next minute; a named card skips the pause, the cap and the window hold',
     cancel: 'cancel [CARD]   Stop a card being worked on and clear its labels',
     retry: 'retry CARD [--workflow W]   Queue a parked or cancelled card again',
-    runs: 'runs [CARD] [--limit N] [--json]   Past runs, newest first',
+    runs: 'runs [CARD] [--limit N] [--jobs] [--json]   Past runs, newest first; --jobs lists scheduled runs only',
     show: 'show CARD [--json]   Steps, outcome and labels of the latest run',
     logs: 'logs [CARD] [--step N] [-f] [--lines N]   Runner log, or a card\'s step logs',
     clean: 'clean [--older 14d] [--yes]   Remove old worktrees and run folders',
@@ -246,6 +250,13 @@ export async function trackerWarnings(kinds, trackers) {
     }
     return out;
 }
+// Pauses or resumes the runner, and pings Discord only when that changed something.
+export async function changePaused(ctx, paused, reason, fetcher = fetch, platform = process.platform) {
+    const was = isPaused(ctx.configDir);
+    setPaused(ctx.configDir, paused);
+    if (was !== paused)
+        await notifyRunner(ctx.configDir, paused, reason, ctx.log, fetcher, platform);
+}
 async function startCmd(ctx) {
     if (!Object.keys(readAgentsConfig(ctx.configDir).workflows).length) {
         ctx.log('No workflows yet. Create one first: vsf agents workflow add.');
@@ -254,7 +265,7 @@ async function startCmd(ctx) {
     for (const w of await trackerWarnings(trackersInUse(readAgentsConfig(ctx.configDir)), trackersFor(ctx.configDir))) {
         ctx.log(`Warning: ${w.message.replace(/\.?$/, '.')} Workflows on ${TRACKERS[w.kind].name} are skipped until then.`);
     }
-    setPaused(ctx.configDir, false);
+    await changePaused(ctx, false, 'by vsf agents start');
     if (!runnerService().start(ctx.home, program(ctx), logPath(ctx.configDir))) {
         ctx.log('Could not start the runner. Check vsf agents logs.');
         return 1;
@@ -286,6 +297,43 @@ export function workspaceLines(workspaces, running) {
     const names = [...new Set([...workspaces, ...running.map((r) => workspaceOf(r))])];
     return names.map((ws) => `  ${ws}:${workingLine(running.find((r) => workspaceOf(r) === ws) ?? null) || ' idle.'}`);
 }
+// One entry per cron trigger: its newest run, last success and today's counts.
+export function jobSummaries(config, all, live, now = Date.now()) {
+    const day = new Date(now).toDateString();
+    const jobs = [];
+    for (const [workflow, w] of Object.entries(config.workflows)) {
+        for (const t of w.triggers) {
+            if (t.source !== 'cron')
+                continue;
+            const mine = all.filter((e) => e.record?.source === 'cron' && e.record.workflow === workflow && e.record.trigger === t.schedule);
+            const newest = mine[0];
+            const r = newest?.record;
+            const ok = mine.find((e) => e.record.outcome === 'done' || e.record.outcome === 'verified');
+            const todays = mine.filter((e) => new Date(e.record.startedAt).toDateString() === day);
+            jobs.push({
+                workflow,
+                schedule: t.schedule,
+                task: t.task,
+                last: r ? { at: r.endedAt ?? r.startedAt, outcome: shownOutcome(newest, live), reason: r.reason, summary: r.steps.at(-1)?.summary } : null,
+                lastOkAt: ok?.record.startedAt ?? null,
+                today: {
+                    runs: todays.length,
+                    failed: todays.filter((e) => ['failed', 'parked'].includes(shownOutcome(e, live))).length,
+                    handed: todays.reduce((n, e) => n + e.record.steps.reduce((m, s) => m + (s.handoffs?.length ?? 0), 0), 0),
+                },
+            });
+        }
+    }
+    return jobs;
+}
+// The status line for one job.
+function jobLine(j) {
+    const bad = j.last?.outcome === 'failed' || j.last?.outcome === 'parked';
+    const head = bad
+        ? `last failed ${clock(new Date(j.last.at))}${j.last.reason ? ` (${j.last.reason.replace(/\.$/, '')})` : ''}`
+        : `last ok ${j.lastOkAt ? clock(new Date(j.lastOkAt)) : 'never'}`;
+    return `Job ${j.workflow} (cron ${j.schedule}): ${head}, ${plural(j.today.runs, 'run')} today, ${j.today.failed} failed, ${j.today.handed} handed.`;
+}
 const status = guard(async (args, ctx) => {
     const p = parse('status', args, { json: { type: 'boolean' } }, ctx);
     if (typeof p === 'number')
@@ -301,20 +349,29 @@ const status = guard(async (args, ctx) => {
     const current = running.length ? { ...running[0], checking: false } : dispatcher ? { ...dispatcher, checking: true, elapsedMinutes: elapsed(dispatcher) } : null;
     const seen = new Set();
     const parked = [];
+    const failed = [];
     const interrupted = [];
-    for (const e of listRuns(ctx.configDir)) {
-        if (e.record?.outcome === 'running' && isInterrupted(e, live))
-            interrupted.push(e.card);
-        if (seen.has(e.card))
+    const all = listRuns(ctx.configDir);
+    for (const e of all) {
+        if (e.record?.source === 'cron' || seen.has(e.card))
             continue;
         seen.add(e.card);
         if (e.record?.outcome === 'parked')
             parked.push({ card: e.card, reason: e.record.reason });
+        else if (e.record?.outcome === 'failed')
+            failed.push({ card: e.card, reason: e.record.reason });
+        else if (isInterrupted(e, live))
+            failed.push({ card: e.card, reason: e.record?.reason ?? STOPPED_REASON });
     }
+    const jobs = jobSummaries(config, all, live);
     const workflows = Object.keys(config.workflows).length;
     const projects = Object.keys(config.projects).length;
+    const pauseAt = config.pauseAt ?? DEFAULTS.pauseAt;
+    const maxRuns = config.maxRuns ?? 0;
+    const w = readWindow(ctx.configDir);
     if (p.values.json) {
-        ctx.log(JSON.stringify({ engine: config.engine, runner, lastTick, current, running, parked, interrupted, workflows, projects }, null, 2));
+        const window = w && { ...w, heldUntil: windowHold(w, pauseAt) };
+        ctx.log(JSON.stringify({ engine: config.engine, runner, lastTick, current, running, parked, failed, interrupted, jobs, workflows, projects, window, maxRuns }, null, 2));
         return 0;
     }
     // One workspace keeps the single line; several get a line each.
@@ -330,12 +387,19 @@ const status = guard(async (args, ctx) => {
     if (perWorkspace)
         for (const line of workspaceLines(workspaces, running))
             ctx.log(line);
+    const windowText = windowLine(w, pauseAt);
+    if (windowText)
+        ctx.log(windowText);
+    if (maxRuns)
+        ctx.log(`Cap: at most ${plural(maxRuns, 'run')} at once.`);
     if (lastTick)
         ctx.log(`Last check: ${clock(new Date(lastTick.at))}, ${lastTick.line.replace(/\.$/, '') || 'no details'}.`);
-    for (const card of interrupted)
-        ctx.log(`Interrupted: ${card}. vsf agents retry ${card} to run it again.`);
+    for (const k of failed)
+        ctx.log(`Failed: ${k.card}${k.reason ? ` (${k.reason.replace(/\.$/, '')})` : ''}. vsf agents retry ${k.card} after fixing the cause.`);
     for (const k of parked)
         ctx.log(`Parked: ${k.card}${k.reason ? ` (${k.reason.replace(/\.$/, '')})` : ''}. vsf agents retry ${k.card} after fixing the cause.`);
+    for (const j of jobs)
+        ctx.log(jobLine(j));
     ctx.log(`${plural(workflows, 'workflow')}, ${plural(projects, 'project')}. vsf agents workflows lists them.`);
     return 0;
 });
@@ -366,7 +430,7 @@ const pause = guard(async (args, ctx) => {
     const p = parse('pause', args, {}, ctx);
     if (typeof p === 'number')
         return p;
-    setPaused(ctx.configDir, true);
+    await changePaused(ctx, true, 'by vsf agents pause');
     ctx.log('Paused. The runner picks up no new cards; a card in progress carries on. vsf agents resume to continue.');
     return 0;
 });
@@ -374,7 +438,7 @@ const resume = guard(async (args, ctx) => {
     const p = parse('resume', args, {}, ctx);
     if (typeof p === 'number')
         return p;
-    setPaused(ctx.configDir, false);
+    await changePaused(ctx, false, 'by vsf agents resume');
     ctx.log('Resumed.');
     return 0;
 });
@@ -411,6 +475,8 @@ const run = guard(async (args, ctx) => {
     if (!card && code === 0) {
         if (isPaused(ctx.configDir))
             ctx.log('The runner is paused, so nothing was picked up. vsf agents resume, or name a card.');
+        else if (gateReason({ configDir: ctx.configDir, config }))
+            ctx.log('Name a card to run it anyway.');
         else
             ctx.log('Nothing to do, or the card was verified.');
     }
@@ -456,6 +522,11 @@ const retry = guard(async (args, ctx) => {
         ctx.log(`${id} is running now. vsf agents cancel ${id} first.`);
         return 1;
     }
+    const latest = listRuns(ctx.configDir, id)[0]?.record;
+    if (latest?.source === 'cron') {
+        ctx.log(`${id} is a scheduled run. vsf agents run --workflow ${latest.workflow} fires it now.`);
+        return 1;
+    }
     const config = readAgentsConfig(ctx.configDir);
     const names = Object.keys(config.workflows);
     let found;
@@ -506,7 +577,7 @@ const retry = guard(async (args, ctx) => {
     return 0;
 });
 const runs = guard(async (args, ctx) => {
-    const p = parse('runs', args, { limit: { type: 'string' }, json: { type: 'boolean' } }, ctx);
+    const p = parse('runs', args, { limit: { type: 'string' }, jobs: { type: 'boolean' }, json: { type: 'boolean' } }, ctx);
     if (typeof p === 'number')
         return p;
     const card = p.positionals[0]?.toUpperCase();
@@ -515,7 +586,8 @@ const runs = guard(async (args, ctx) => {
     const limit = p.values.limit === undefined ? 20 : Number(p.values.limit);
     if (!Number.isInteger(limit) || limit < 1)
         return usageError('runs', ctx, '--limit needs a whole number above 0.');
-    const entries = listRuns(ctx.configDir, card).slice(0, limit);
+    // A named card lists all its runs; otherwise card runs, or with --jobs scheduled ones.
+    const entries = listRuns(ctx.configDir, card).filter((e) => !!card || (e.record?.source === 'cron') === !!p.values.jobs).slice(0, limit);
     if (p.values.json) {
         ctx.log(JSON.stringify(entries.map((e) => ({ card: e.card, stamp: e.stamp, dir: e.dir, logs: e.logs, record: e.record })), null, 2));
         return 0;
@@ -556,13 +628,17 @@ const show = guard(async (args, ctx) => {
         return 0;
     }
     ctx.log(`${latest.card}  ${latest.title}`);
-    ctx.log(`Workflow ${latest.workflow}, ${isInterrupted(all[0], liveRuns(ctx.configDir)) ? 'interrupted' : latest.outcome}${latest.prUrl ? `, PR ${latest.prUrl}` : ''}`);
+    ctx.log(`Workflow ${latest.workflow}, ${shownOutcome(all[0], liveRuns(ctx.configDir))}${latest.prUrl ? `, PR ${latest.prUrl}` : ''}`);
     if (labels)
         ctx.log(`Labels: ${labels.join(', ') || 'none'}`);
     for (const s of latest.steps) {
         const took = s.endedAt ? formatDuration(Date.parse(s.endedAt) - Date.parse(s.startedAt)) : 'running';
-        ctx.log(`  ${s.label.padEnd(12)} ${(s.result ?? 'running').toLowerCase().padEnd(8)} ${took.padEnd(6)} ${oneLine(s.summary ?? '')}`.trimEnd());
+        const used = usageText(s.usage);
+        ctx.log(`  ${s.label.padEnd(12)} ${(s.result ?? 'running').toLowerCase().padEnd(8)} ${took.padEnd(6)} ${used ? `${used}  ` : ''}${oneLine(s.summary ?? '')}`.trimEnd());
     }
+    const total = usageText(latest.usage);
+    if (total || latest.usage?.models?.length)
+        ctx.log(`Usage: ${[total, latest.usage?.models?.join(', ')].filter(Boolean).join(', ')}`);
     if (latest.outcome === 'parked' && latest.reason)
         ctx.log(`Parked: ${oneLine(latest.reason, 300)}`);
     if (all.length > 1)
@@ -720,7 +796,11 @@ const tickCmd = async (args, ctx) => {
     try {
         const { values } = parseArgs({ args, options: { card: { type: 'string' }, workflow: { type: 'string' }, schedule: { type: 'string' } }, strict: true });
         const config = readAgentsConfig(ctx.configDir);
-        const rc = { configDir: ctx.configDir, config, trackers: trackersFor(ctx.configDir), log: stamped, selfCommand: ctx.selfCommand };
+        const rc = {
+            configDir: ctx.configDir, config, trackers: trackersFor(ctx.configDir), log: stamped, selfCommand: ctx.selfCommand,
+            notify: (e) => notifyRun(ctx.configDir, e, stamped),
+            summary: (paused) => sendSummary(ctx.configDir, paused, stamped),
+        };
         if (values.card || values.workflow)
             return await tick(rc, values.card?.toUpperCase(), { workflow: values.workflow, schedule: values.schedule, child: true });
         return await dispatch(rc, { reload: () => readAgentsConfig(ctx.configDir) });

package/dist/engine.d.ts

@@ -1,4 +1,5 @@
 import { type ChildProcess } from 'node:child_process';
+import { type Usage } from './state.ts';
 export type Engine = 'claude' | 'codex';
 export interface RunOptions {
     engine: Engine;
@@ -10,6 +11,7 @@ export interface RunOptions {
     timeoutMs?: number;
     vault?: string;
     settingsFile?: string;
+    platform?: NodeJS.Platform;
 }
 export declare function engineArgs(o: RunOptions, outFile: string): {
     cmd: string;
@@ -17,7 +19,27 @@ export declare function engineArgs(o: RunOptions, outFile: string): {
 };
 export declare function track(child: ChildProcess): void;
 export declare function stopAgents(): Promise<void>;
+export declare function errorTail(stderr: string): string;
+export interface ClaudeResult {
+    text: string;
+    isError: boolean;
+    usage: Usage;
+}
+export declare function parseClaudeJson(stdout: string): ClaudeResult | null;
 export declare function runAgent(o: RunOptions): Promise<{
     ok: boolean;
     output: string;
+    error?: string;
+    usage?: Usage;
+}>;
+export declare function runCommand(o: {
+    command: string;
+    cwd: string;
+    logFile: string;
+    timeoutMs?: number;
+    env?: Record<string, string>;
+}): Promise<{
+    ok: boolean;
+    output: string;
+    error?: string;
 }>;