@voidlabs.gg/voidshift-agents 0.7.0 → 0.8.0

package/dist/state.js

@@ -113,6 +113,19 @@ export function setPaused(configDir, paused) {
     else
         rmSync(pausePath(configDir), { force: true });
 }
+const windowPath = (configDir) => join(agentsDir(configDir), 'window.json');
+export function readWindow(configDir) {
+    try {
+        return JSON.parse(readFileSync(windowPath(configDir), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function writeWindow(configDir, w) {
+    mkdirSync(agentsDir(configDir), { recursive: true });
+    writeFileSync(windowPath(configDir), JSON.stringify(w, null, 2) + '\n');
+}
 const pendingPath = (configDir) => join(agentsDir(configDir), 'pending.json');
 export function readPending(configDir) {
     try {
@@ -129,6 +142,42 @@ export function writePending(configDir, pending) {
     else
         rmSync(pendingPath(configDir), { force: true });
 }
+export function addUsage(total, step) {
+    const sum = (a, b) => (a === undefined && b === undefined ? undefined : (a ?? 0) + (b ?? 0));
+    const out = {};
+    const input = sum(total?.input, step.input);
+    const output = sum(total?.output, step.output);
+    const cached = sum(total?.cached, step.cached);
+    const costUsd = sum(total?.costUsd, step.costUsd);
+    if (input !== undefined)
+        out.input = input;
+    if (output !== undefined)
+        out.output = output;
+    if (cached !== undefined)
+        out.cached = cached;
+    if (costUsd !== undefined)
+        out.costUsd = costUsd;
+    const models = [...new Set([...(total?.models ?? []), ...(step.model ? [step.model] : [])])];
+    if (models.length)
+        out.models = models;
+    return out;
+}
+// "12.3k in, 4.1k out, 1.2M cached, $0.42 est.", or empty with nothing to show.
+export function usageText(u) {
+    if (!u)
+        return '';
+    const n = (v) => (v >= 1e6 ? `${(v / 1e6).toFixed(1)}M` : v >= 1e3 ? `${(v / 1e3).toFixed(1)}k` : String(v));
+    const parts = [];
+    if (u.input !== undefined)
+        parts.push(`${n(u.input)} in`);
+    if (u.output !== undefined)
+        parts.push(`${n(u.output)} out`);
+    if (u.cached)
+        parts.push(`${n(u.cached)} cached`);
+    if (u.costUsd !== undefined)
+        parts.push(`$${u.costUsd.toFixed(2)} est.`);
+    return parts.join(', ');
+}
 export const runsDir = (configDir) => join(agentsDir(configDir), 'runs');
 export function writeRun(runDir, run) {
     writeFileSync(join(runDir, 'run.json'), JSON.stringify(run, null, 2) + '\n');
@@ -174,3 +223,70 @@ export function writeCronState(configDir, state) {
     mkdirSync(agentsDir(configDir), { recursive: true });
     writeFileSync(cronPath(configDir), JSON.stringify(state, null, 2) + '\n');
 }
+const handoffsPath = (configDir) => join(agentsDir(configDir), 'handoffs.json');
+export function readHandoffs(configDir) {
+    try {
+        return JSON.parse(readFileSync(handoffsPath(configDir), 'utf8'));
+    }
+    catch {
+        return [];
+    }
+}
+export function writeHandoffs(configDir, handoffs) {
+    mkdirSync(agentsDir(configDir), { recursive: true });
+    if (handoffs.length)
+        writeFileSync(handoffsPath(configDir), JSON.stringify(handoffs, null, 2) + '\n');
+    else
+        rmSync(handoffsPath(configDir), { force: true });
+}
+// Queues cards for a workflow, once each: a card already waiting for it is skipped.
+export function queueHandoffs(configDir, workflow, cards, from, now = new Date()) {
+    const queue = readHandoffs(configDir);
+    const added = [];
+    for (const card of cards) {
+        if (queue.some((h) => h.card === card && h.workflow === workflow))
+            continue;
+        const h = { card, workflow, from, at: now.toISOString() };
+        queue.push(h);
+        added.push(h);
+    }
+    if (added.length)
+        writeHandoffs(configDir, queue);
+    return added;
+}
+// Takes a card off the queue once its run for the workflow has started.
+export function takeHandoff(configDir, card, workflow) {
+    const queue = readHandoffs(configDir);
+    const left = queue.filter((h) => !(h.card === card && h.workflow === workflow));
+    if (left.length !== queue.length)
+        writeHandoffs(configDir, left);
+}
+// When a run that ended without finishing last showed signs of life: its last
+// step's end or start, else its start.
+export function lastSeen(run) {
+    const last = run.steps.at(-1);
+    return last?.endedAt ?? last?.startedAt ?? run.startedAt;
+}
+export const STOPPED_REASON = 'The run stopped without finishing: its process ended before it could record an outcome.';
+// Closes runs that say "running" while no live run holds them: their process
+// is gone, so they failed. `live` is the run folders live runs hold, and
+// `cards` the cards of live runs whose lock names no folder. Returns the cards closed.
+export function closeStale(configDir, live) {
+    const closed = [];
+    for (const e of listRuns(configDir)) {
+        const r = e.record;
+        if (!r || r.outcome !== 'running')
+            continue;
+        if (live.some((l) => (l.runDir ? l.runDir === e.dir : l.card === e.card)))
+            continue;
+        const steps = r.steps.map((s) => (s.endedAt ? s : { ...s, endedAt: lastSeen(r), result: s.result ?? 'stopped' }));
+        try {
+            writeRun(e.dir, { ...r, steps, outcome: 'failed', reason: r.reason ?? STOPPED_REASON, endedAt: lastSeen({ ...r, steps }) });
+            closed.push(e.card);
+        }
+        catch {
+            // the folder is gone
+        }
+    }
+    return closed;
+}

package/dist/systemd.d.ts

@@ -1,3 +1,4 @@
+import { spawnSync } from 'node:child_process';
 import type { Check } from './types.ts';
 export declare const UNIT = "voidshift-agents";
 export declare const servicePath: (home: string) => string;
@@ -12,3 +13,4 @@ export declare function startRunner(home: string, program: string[], env: Record
 export declare function stopRunner(home: string): void;
 export declare function programArgs(home: string): string[] | null;
 export declare function lingerCheck(): Check;
+export declare function sudoCheck(run?: typeof spawnSync, uid?: number): Check;

package/dist/systemd.js

@@ -83,3 +83,17 @@ export function lingerCheck() {
         ? { name: 'runner after logout', status: 'ok', detail: 'lingering is on, the runner keeps going after logout and reboot' }
         : { name: 'runner after logout', status: 'warn', detail: 'lingering is off, the runner stops when you log out', fix: `sudo loginctl enable-linger ${user}` };
 }
+// Agents run with permissions skipped on Linux, so the runner's user account
+// is the boundary: anything that user can do, an agent can too.
+export function sudoCheck(run = spawnSync, uid = userInfo().uid) {
+    const name = 'runner user';
+    const fix = 'Run the runner as a dedicated user with no sudo, holding only the keys it needs.';
+    if (uid === 0)
+        return { name, status: 'fail', detail: 'runs as root; Claude refuses to skip permissions as root', fix };
+    const groups = (run('id', ['-Gn'], { encoding: 'utf8' }).stdout ?? '').toString().split(/\s+/);
+    const admin = groups.some((g) => ['sudo', 'wheel', 'admin'].includes(g));
+    if (admin || run('sudo', ['-n', 'true'], { encoding: 'utf8' }).status === 0) {
+        return { name, status: 'warn', detail: 'the runner user has sudo; anything an agent runs could too', fix };
+    }
+    return { name, status: 'ok', detail: 'no sudo, the account limits what agents can do' };
+}

package/dist/usage.d.ts

@@ -0,0 +1,18 @@
+import { type Window } from './state.ts';
+export declare const WINDOW_MS: number;
+export interface TokenSource {
+    platform?: NodeJS.Platform;
+    claudeDir?: string;
+    now?: number;
+}
+export declare function readClaudeToken(o?: TokenSource): {
+    token: string;
+} | {
+    error: string;
+};
+export declare function fetchWindow(token: string, fetcher?: typeof fetch): Promise<Pick<Window, 'utilization' | 'resetsAt'>>;
+export declare function windowStale(w: Window | null, now?: Date): boolean;
+export declare function refreshWindow(configDir: string, fetcher?: typeof fetch, token?: () => ReturnType<typeof readClaudeToken>, now?: Date): Promise<Window>;
+export declare function windowHold(w: Window | null, pauseAt: number, now?: Date): string | null;
+export declare const clock: (iso: string) => string;
+export declare function windowLine(w: Window | null, pauseAt: number, now?: Date): string;

package/dist/usage.js

@@ -0,0 +1,102 @@
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { readWindow, writeWindow } from "./state.js";
+// The Claude subscription's 5 hour window. The runner reads it every few
+// minutes with Claude Code's own login, read only: the token is never
+// refreshed here, so an expired one just means no reading until Claude runs.
+export const WINDOW_MS = 5 * 60_000;
+const USAGE_URL = 'https://api.anthropic.com/api/oauth/usage';
+// Claude Code's access token: the macOS Keychain first, then its credentials file.
+export function readClaudeToken(o = {}) {
+    let text = '';
+    if ((o.platform ?? process.platform) === 'darwin') {
+        const r = spawnSync('/usr/bin/security', ['find-generic-password', '-s', 'Claude Code-credentials', '-w'], { encoding: 'utf8', timeout: 5000 });
+        if (r.status === 0)
+            text = r.stdout.trim();
+    }
+    if (!text) {
+        try {
+            text = readFileSync(join(o.claudeDir ?? (process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude')), '.credentials.json'), 'utf8');
+        }
+        catch {
+            return { error: 'no Claude login found' };
+        }
+    }
+    let oauth;
+    try {
+        oauth = JSON.parse(text)?.claudeAiOauth;
+    }
+    catch {
+        return { error: 'the Claude credentials could not be read' };
+    }
+    if (typeof oauth?.accessToken !== 'string' || !oauth.accessToken)
+        return { error: 'no Claude login found' };
+    if (typeof oauth.expiresAt === 'number' && oauth.expiresAt <= (o.now ?? Date.now()))
+        return { error: 'the Claude login has expired; it renews when Claude next runs' };
+    return { token: oauth.accessToken };
+}
+export async function fetchWindow(token, fetcher = fetch) {
+    const res = await fetcher(USAGE_URL, { headers: { Authorization: `Bearer ${token}`, 'anthropic-beta': 'oauth-2025-04-20' }, signal: AbortSignal.timeout(10_000) });
+    if (!res.ok)
+        throw new Error(`the usage endpoint answered ${res.status}`);
+    const five = (await res.json())?.five_hour;
+    // Percent used, 0 to 100, as Claude's /usage shows it. A value under 1 is
+    // under 1%, not a fraction: reading it as one would hold runs at a reset.
+    const u = typeof five?.utilization === 'number' ? five.utilization : NaN;
+    if (!Number.isFinite(u))
+        throw new Error('the answer had no 5 hour window');
+    const resets = typeof five?.resets_at === 'string' ? new Date(five.resets_at) : null;
+    return { utilization: u, ...(resets && !isNaN(resets.getTime()) ? { resetsAt: resets.toISOString() } : {}) };
+}
+// A reading is stale after 5 minutes, or once its window has reset.
+export function windowStale(w, now = new Date()) {
+    if (!w)
+        return true;
+    if (now.getTime() - Date.parse(w.checkedAt) >= WINDOW_MS)
+        return true;
+    return !!w.resetsAt && Date.parse(w.resetsAt) <= now.getTime();
+}
+// Reads the window and saves it to window.json. Never throws: a failure is
+// saved as the error, keeping the old reading while its window is still on.
+export async function refreshWindow(configDir, fetcher = fetch, token = readClaudeToken, now = new Date()) {
+    const old = readWindow(configDir);
+    const keep = old?.utilization !== undefined && old.resetsAt && Date.parse(old.resetsAt) > now.getTime() ? { utilization: old.utilization, resetsAt: old.resetsAt } : {};
+    const checkedAt = now.toISOString();
+    let w;
+    try {
+        const t = token();
+        w = 'error' in t ? { checkedAt, ...keep, error: t.error } : { checkedAt, ...(await fetchWindow(t.token, fetcher)) };
+    }
+    catch (err) {
+        w = { checkedAt, ...keep, error: err.message };
+    }
+    writeWindow(configDir, w);
+    return w;
+}
+// When new runs may start again, or null when they may start now. Holds once
+// the window is at `pauseAt` percent, until it resets; 0 never holds.
+export function windowHold(w, pauseAt, now = new Date()) {
+    if (!w || pauseAt <= 0 || w.utilization === undefined || !w.resetsAt)
+        return null;
+    return w.utilization >= pauseAt && Date.parse(w.resetsAt) > now.getTime() ? w.resetsAt : null;
+}
+const pad2 = (n) => String(n).padStart(2, '0');
+export const clock = (iso) => {
+    const d = new Date(iso);
+    return `${pad2(d.getHours())}:${pad2(d.getMinutes())}`;
+};
+// What status prints for the window, or empty with nothing read yet.
+export function windowLine(w, pauseAt, now = new Date()) {
+    if (!w)
+        return '';
+    if (w.utilization === undefined)
+        return w.error ? `Window: could not read the 5 hour window (${w.error}).` : '';
+    const pct = Math.round(w.utilization);
+    const until = windowHold(w, pauseAt, now);
+    if (until)
+        return `Window: held at ${pct}% until ${clock(until)}, running cards finish.`;
+    const resets = w.resetsAt && Date.parse(w.resetsAt) > now.getTime() ? `, resets ${clock(w.resetsAt)}` : '';
+    return `Window: 5 hour at ${pct}%${resets}.`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voidlabs.gg/voidshift-agents",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Agents for Claude Code and Codex that plan, build and QA Linear cards, chained and run in the background.",
   "license": "Apache-2.0",
   "repository": {