@voidlabs.gg/voidshift-agents 0.0.0-stage → 0.4.1

package/dist/engine.d.ts

@@ -0,0 +1,22 @@
+import { type ChildProcess } from 'node:child_process';
+export type Engine = 'claude' | 'codex';
+export interface RunOptions {
+    engine: Engine;
+    model?: string;
+    cwd: string;
+    prompt: string;
+    write: boolean;
+    logFile: string;
+    timeoutMs?: number;
+    vault?: string;
+}
+export declare function engineArgs(o: RunOptions, outFile: string): {
+    cmd: string;
+    args: string[];
+};
+export declare function track(child: ChildProcess): void;
+export declare function stopAgents(): Promise<void>;
+export declare function runAgent(o: RunOptions): Promise<{
+    ok: boolean;
+    output: string;
+}>;

package/dist/engine.js

@@ -0,0 +1,95 @@
+import { spawn } from 'node:child_process';
+import { createWriteStream, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+// 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) {
+    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(',')];
+        if (o.vault)
+            args.push('--add-dir', o.vault);
+        if (o.write)
+            args.push('--permission-mode', 'acceptEdits');
+        if (o.model)
+            args.push('--model', o.model);
+        return { cmd: 'claude', 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)
+        args.push('--add-dir', o.vault);
+    if (o.model)
+        args.push('-m', o.model);
+    args.push('-');
+    return { cmd: 'codex', args };
+}
+// Agent processes running now, so a cancel can stop them.
+const children = new Set();
+// Registers a child process so stopAgents() can stop it.
+export function track(child) {
+    children.add(child);
+    child.on('close', () => children.delete(child));
+}
+// Asks every running agent to stop and waits up to 2 seconds for them to go,
+// then kills the rest. The caller exits right after, so nothing may linger.
+export async function stopAgents() {
+    for (const c of children)
+        c.kill('SIGTERM');
+    const deadline = Date.now() + 2000;
+    while (children.size && Date.now() < deadline)
+        await new Promise((r) => setTimeout(r, 50));
+    for (const c of children)
+        if (c.exitCode === null && c.signalCode === null)
+            c.kill('SIGKILL');
+}
+// 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.
+export function runAgent(o) {
+    const dir = mkdtempSync(join(tmpdir(), 'voidshift-run-'));
+    const outFile = join(dir, 'last.txt');
+    const { cmd, args } = engineArgs(o, outFile);
+    const log = createWriteStream(o.logFile, { flags: 'a' });
+    log.write(`$ ${cmd} ${args.join(' ')}\n\n`);
+    return new Promise((resolve) => {
+        // The runner recalls memory for the card itself; the recall hook would
+        // match on the whole prompt, skill text included.
+        const env = { ...process.env, VOIDSHIFT_RECALL: 'off' };
+        const child = spawn(cmd, args, { cwd: o.cwd, env, stdio: ['pipe', 'pipe', 'pipe'] });
+        track(child);
+        let stdout = '';
+        child.stdout.on('data', (d) => {
+            stdout += d;
+            log.write(d);
+        });
+        child.stderr.on('data', (d) => log.write(d));
+        const timer = setTimeout(() => child.kill('SIGTERM'), o.timeoutMs ?? 45 * 60_000);
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            children.delete(child);
+            log.end(`\n${err.message}\n`);
+            resolve({ ok: false, output: err.message });
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            children.delete(child);
+            log.end(`\nexit ${code}\n`);
+            let output = stdout;
+            if (o.engine === 'codex') {
+                try {
+                    output = readFileSync(outFile, 'utf8');
+                }
+                catch {
+                    // fall back to stdout
+                }
+            }
+            rmSync(dir, { recursive: true, force: true });
+            resolve({ ok: code === 0, output });
+        });
+        child.stdin.end(o.prompt);
+    });
+}

package/dist/git.d.ts

@@ -0,0 +1,30 @@
+export interface Out {
+    ok: boolean;
+    code: number | null;
+    stdout: string;
+    stderr: string;
+}
+export declare function sh(cmd: string, args: string[], cwd: string, timeoutMs?: number): Out;
+export declare function defaultBranch(repo: string): string;
+export declare function ensureWorktree(repo: string, path: string, branch: string, base: string): void;
+export declare function commitsAhead(worktree: string, base: string): number;
+export declare function headSha(worktree: string): string;
+export declare function push(worktree: string, branch: string): void;
+export declare function ensureDraftPr(worktree: string, branch: string, base: string, title: string, body: string): string;
+export declare function markReady(worktree: string, branch: string): boolean;
+export interface CheckSummary {
+    failed: {
+        name: string;
+        link: string;
+    }[];
+    pending: string[];
+    passed: number;
+}
+export declare function summarizeChecks(text: string): CheckSummary;
+export declare function ciReport(s: CheckSummary): string;
+export declare function waitForPrHead(worktree: string, branch: string, sha: string, timeoutMs?: number): Promise<boolean>;
+export declare function waitForChecks(worktree: string, branch: string, timeoutMs?: number, settleMs?: number): Promise<{
+    verdict: 'SHIP' | 'FIX' | 'SKIP';
+    report: string;
+}>;
+export declare function resetWorktree(worktree: string): void;

package/dist/git.js

@@ -0,0 +1,136 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { track } from "./engine.js";
+export function sh(cmd, args, cwd, timeoutMs = 120_000) {
+    const r = spawnSync(cmd, args, { cwd, encoding: 'utf8', timeout: timeoutMs });
+    return { ok: r.status === 0, code: r.status, stdout: (r.stdout ?? '').trim(), stderr: (r.stderr ?? '').trim() };
+}
+function must(out, what) {
+    if (!out.ok)
+        throw new Error(`${what} failed: ${out.stderr || out.stdout}`);
+    return out.stdout;
+}
+export function defaultBranch(repo) {
+    const ref = sh('git', ['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], repo);
+    if (ref.ok)
+        return ref.stdout.replace(/^origin\//, '');
+    for (const b of ['main', 'master'])
+        if (sh('git', ['rev-parse', '--verify', `origin/${b}`], repo).ok)
+            return b;
+    throw new Error(`cannot tell the default branch of ${repo}`);
+}
+// A worktree per card on the card's branch, so the developer's checkout is
+// never touched.
+export function ensureWorktree(repo, path, branch, base) {
+    must(sh('git', ['fetch', 'origin'], repo), 'git fetch');
+    if (existsSync(path)) {
+        sh('git', ['pull', '--ff-only', 'origin', branch], path);
+        return;
+    }
+    const remote = sh('git', ['rev-parse', '--verify', `origin/${branch}`], repo).ok;
+    const local = sh('git', ['rev-parse', '--verify', branch], repo).ok;
+    const args = remote
+        ? ['worktree', 'add', '-B', branch, path, `origin/${branch}`]
+        : local
+            ? ['worktree', 'add', path, branch]
+            : ['worktree', 'add', '-b', branch, path, `origin/${base}`];
+    must(sh('git', args, repo), 'git worktree add');
+}
+export function commitsAhead(worktree, base) {
+    const out = sh('git', ['rev-list', '--count', `origin/${base}..HEAD`], worktree);
+    return out.ok ? Number(out.stdout) : 0;
+}
+export function headSha(worktree) {
+    return sh('git', ['rev-parse', 'HEAD'], worktree).stdout;
+}
+export function push(worktree, branch) {
+    must(sh('git', ['push', '-u', 'origin', branch], worktree), 'git push');
+}
+// The branch's open pull request. A closed one is reopened, since a closed PR
+// never runs CI on new commits; a merged one gets a fresh PR.
+export function ensureDraftPr(worktree, branch, base, title, body) {
+    const view = sh('gh', ['pr', 'view', branch, '--json', 'url,state', '-q', '.state + " " + .url'], worktree);
+    const [state, url] = view.ok ? view.stdout.split(' ') : [];
+    if (state === 'OPEN' && url)
+        return url;
+    if (state === 'CLOSED' && url && sh('gh', ['pr', 'reopen', branch], worktree).ok)
+        return url;
+    return must(sh('gh', ['pr', 'create', '--draft', '--base', base, '--head', branch, '--title', title, '--body', body], worktree), 'gh pr create');
+}
+export function markReady(worktree, branch) {
+    return sh('gh', ['pr', 'ready', branch], worktree).ok;
+}
+// Parses plain `gh pr checks` output: name, state, duration, link per line,
+// tab separated. Works on old gh versions that lack --json.
+export function summarizeChecks(text) {
+    const out = { failed: [], pending: [], passed: 0 };
+    for (const line of text.split('\n')) {
+        const [name, state, , link] = line.split('\t');
+        if (!name || !state)
+            continue;
+        if (state === 'pass' || state === 'skipping')
+            out.passed++;
+        else if (state === 'pending')
+            out.pending.push(name.trim());
+        else
+            out.failed.push({ name: name.trim(), link: (link ?? '').trim() });
+    }
+    return out;
+}
+// One short line per failed check, for the card and for Dev.
+export function ciReport(s) {
+    const lines = s.failed.map((f) => `- ${f.name}${f.link ? `: ${f.link}` : ''}`);
+    const pending = s.pending.length ? `\nStill running: ${s.pending.join(', ')}.` : '';
+    return `CI failed:\n${lines.join('\n')}${pending}`;
+}
+// Waits for CI on the PR, then reads the final state once. Repos without CI
+// pass through as SKIP.
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+// True once GitHub shows `sha` as the head of the branch's pull request, so the
+// checks read next belong to that commit and not to an older push.
+export async function waitForPrHead(worktree, branch, sha, timeoutMs = 3 * 60_000) {
+    const until = Date.now() + timeoutMs;
+    for (;;) {
+        const head = sh('gh', ['pr', 'view', branch, '--json', 'headRefOid', '-q', '.headRefOid'], worktree);
+        if (head.ok && head.stdout === sha)
+            return true;
+        if (Date.now() > until)
+            return false;
+        await sleep(10_000);
+    }
+}
+// CI for the pull request's current head. Checks take a moment to register
+// after a push, so "no checks" only counts once they have had time to show up.
+export async function waitForChecks(worktree, branch, timeoutMs = 30 * 60_000, settleMs = 2 * 60_000) {
+    const settled = Date.now() + settleMs;
+    const noChecks = () => {
+        const out = sh('gh', ['pr', 'checks', branch], worktree);
+        return /no checks reported/i.test(`${out.stdout}\n${out.stderr}`);
+    };
+    while (Date.now() < settled && noChecks())
+        await sleep(15_000);
+    return new Promise((resolve) => {
+        const child = spawn('gh', ['pr', 'checks', branch, '--watch', '--interval', '30'], { cwd: worktree, stdio: ['ignore', 'pipe', 'pipe'] });
+        track(child);
+        let text = '';
+        child.stdout.on('data', (d) => (text += d));
+        child.stderr.on('data', (d) => (text += d));
+        const timer = setTimeout(() => child.kill('SIGTERM'), timeoutMs);
+        child.on('close', () => {
+            clearTimeout(timer);
+            if (/no checks reported/i.test(text))
+                return resolve({ verdict: 'SKIP', report: 'No CI checks on this repo.' });
+            const summary = summarizeChecks(sh('gh', ['pr', 'checks', branch], worktree).stdout);
+            if (!summary.failed.length && !summary.pending.length)
+                return resolve({ verdict: 'SHIP', report: `CI passed (${summary.passed} checks).` });
+            if (!summary.failed.length)
+                return resolve({ verdict: 'FIX', report: `CI did not finish in time. Still running: ${summary.pending.join(', ')}.` });
+            resolve({ verdict: 'FIX', report: ciReport(summary) });
+        });
+    });
+}
+// QA runs with write access so it can start the app; nothing it changes stays.
+export function resetWorktree(worktree) {
+    sh('git', ['reset', '--hard', 'HEAD'], worktree);
+    sh('git', ['clean', '-fd'], worktree);
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import type { Tool } from './types.ts';
+declare const agents: Tool;
+export default agents;