@voidlabs.gg/voidshift-agents 0.4.2 → 0.4.4

package/README.md

@@ -5,7 +5,7 @@ One CLI for the Void dev tools. Install it once, run `vsf` (short for
 defaults you can change. Everything setup does can be seen and changed later
 from the command line.
 
-> Early release. macOS only for now; Windows and Linux are next.
+> Early release. macOS and Linux (awake is macOS only); Windows is next.
 
 ```sh
 npm i -g @voidlabs.gg/voidshift
@@ -50,15 +50,24 @@ Five agents, installed into Claude Code (and Codex if you use it):
 | QA | CI, then code review, then a usability check in a headless browser |
 
 Use them yourself (`/vs-plan ENG-123` in Claude Code), or let a **workflow**
-run them. A workflow starts when one of your Linear cards gets a label, runs
-agents in order in a project (a repo on your Mac), and sends work back to the
-step that made it when a check fails:
+run them. A workflow starts when one of your Linear or VoidTrack cards gets a
+label, or on a schedule, runs agents in order in a project (a repo on your
+machine), and sends work back to the step that made it when a check fails:
 
 ```
 when ENG + vs-plan:  Dev → QA  in tether-relay
 ```
 
-The runner checks Linear every minute, works in its own copy of the repo so
+Triggers, as `--trigger` takes them:
+
+```
+ENG:vs-plan                           # a Linear card in ENG assigned to you gets vs-plan
+voidtrack:ORG:vs-start                # the same for VoidTrack (vsf agents key --voidtrack)
+"cron:0 5 * * 1:Update dependencies"  # every Monday 05:00, no card, on its own branch
+```
+
+A schedule fires once when due (a missed one is made up within a day) and
+`vsf agents run --workflow NAME` fires it now. The runner checks every minute, works in its own copy of the repo so
 your checkout is never touched, and keeps two labels on the card as it goes: the
 stage (`vs-planning`, `vs-plan-review`, `vs-dev`, `vs-qa`, then `vs-qa-verified`
 or `vs-parked`) and the round (`vs-v1`, `vs-v2`). On Linear it posts the plan and
@@ -104,10 +113,13 @@ to trust the recall hook once: run `/hooks` in Codex.
 - **Your own logins.** Agents run the official `claude` and `codex` CLIs you
   already use, signed in with your own account. VoidShift never reads or
   stores those credentials. The Linear API key for the runner lives in your
-  macOS Keychain.
+  macOS Keychain, or on Linux in `~/.config/voidshift/agents/secrets.json`
+  (mode 0600).
 - **Trust.** The Dev agent can run shell commands inside its copy of the repo
   so it can install and test. Review its pull requests like any other.
 - **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.
 
 ```sh
 vsf doctor                     # check everything is set up, and whether an update is out

package/dist/config.d.ts

@@ -13,11 +13,21 @@ export declare const AGENTS: Record<string, {
 }>;
 export declare const visibleAgents: () => string[];
 export declare const stepEnabled: (step: StepId, enabled: string[]) => boolean;
-export interface Trigger {
-    source: 'linear';
+export type Tracker = 'linear' | 'voidtrack';
+export interface CardTrigger {
+    source: Tracker;
     team: string;
     label: string;
 }
+export interface CronTrigger {
+    source: 'cron';
+    schedule: string;
+    task: string;
+}
+export type Trigger = CardTrigger | CronTrigger;
+export declare const isCardTrigger: (t: Trigger) => t is CardTrigger;
+export declare function triggerSpec(t: Trigger): string;
+export declare function describeTrigger(t: Trigger): string;
 export interface Project {
     path: string;
     base?: string;

package/dist/config.js

@@ -19,6 +19,19 @@ export const AGENTS = {
 };
 export const visibleAgents = () => Object.keys(AGENTS);
 export const stepEnabled = (step, enabled) => enabled.includes(step);
+export const isCardTrigger = (t) => t.source !== 'cron';
+// The form `--trigger` takes: "ENG:vs-plan" (Linear), "voidtrack:ORG:vs-start",
+// or "cron:0 5 * * 1:Update the dependencies".
+export function triggerSpec(t) {
+    if (t.source === 'cron')
+        return `cron:${t.schedule}:${t.task}`;
+    return t.source === 'voidtrack' ? `voidtrack:${t.team}:${t.label}` : `${t.team}:${t.label}`;
+}
+export function describeTrigger(t) {
+    if (t.source === 'cron')
+        return `cron ${t.schedule}`;
+    return `${t.source === 'voidtrack' ? 'VoidTrack ' : ''}${t.team} + ${t.label}`;
+}
 // Step lists to start a workflow from.
 export const TEMPLATES = {
     build: { steps: ['vs-dev', 'vs-qa'], maxRounds: 3 },
@@ -40,7 +53,7 @@ const configPath = (configDir) => join(agentsDir(configDir), 'config.json');
 export const hasWork = (workflow) => workflow.steps.some((s) => STEPS[s].output === 'commits');
 export const hasProducer = (workflow) => workflow.steps.some(isProducer);
 export const describeSteps = (steps) => steps.map((s) => STEPS[s].label).join(' → ');
-export const describeTriggers = (triggers) => triggers.map((t) => `${t.team} + ${t.label}`).join(', ');
+export const describeTriggers = (triggers) => triggers.map(describeTrigger).join(', ');
 export const describeWorkflow = (c) => `when ${describeTriggers(c.triggers)}: ${describeSteps(c.steps)} in ${c.project}`;
 // Step ids that were folded into QA.
 const RENAMED = { 'vs-qa-review': 'vs-qa', ci: null, 'vs-qa-ui': null };

package/dist/control.d.ts

@@ -1,5 +1,8 @@
+import { type AgentsConfig, type Tracker as Kind } from './config.ts';
 import { type Current, type RunEntry } from './state.ts';
 import type { Check, ToolCommand, ToolContext } from './types.ts';
+export { parsePlistArgs } from './launchd.ts';
+export declare const trackersInUse: (config: Pick<AgentsConfig, "workflows">) => Kind[];
 export declare function parseAge(input: string): number | null;
 export declare function formatDuration(ms: number): string;
 export declare function stampDate(stamp: string): Date;
@@ -12,13 +15,12 @@ export declare function scanRunnerErrors(text: string, now: number): {
     count: number;
     last: string;
 };
-export declare function parsePlistArgs(plist: string): string[];
 export declare const controlUsage: Record<string, string>;
 export interface CancelDeps {
     ours: (pid: number) => boolean;
     kill: (pid: number, signal: 'SIGTERM' | 'SIGKILL') => void;
     sleep: (ms: number) => Promise<void>;
-    cancelCard: (card: string, label: string) => Promise<boolean>;
+    cancelCard: (card: string, label: string, source: Kind) => Promise<boolean>;
 }
 export declare function cancelCurrent(ctx: ToolContext, c: Current, deps: CancelDeps): Promise<void>;
 export declare const controlCommands: Record<string, ToolCommand>;

package/dist/control.js

@@ -2,11 +2,10 @@ 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, readAgentsConfig } from "./config.js";
-import { readLinearKey } from "./keychain.js";
+import { agentsDir, isCardTrigger, readAgentsConfig } from "./config.js";
 import { isPaused, listRuns, ours, clearCurrent, liveCurrent, readCurrent, setPaused, writeRun } from "./state.js";
-import { plistPath, runnerLoaded, startRunner, stopRunner } from "./launchd.js";
-import { createLinear } from "./linear.js";
+import { runnerService } from "./service.js";
+import { TRACKERS, trackersFor } from "./tracker.js";
 import { parseStep, resolveName, stepNames } from "./names.js";
 import { isStatusLabel } from "./workflow.js";
 import { cancelCard, tick } from "./runner.js";
@@ -14,11 +13,28 @@ 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+$/;
 const ISO_LINE = /^(\d{4}-\d\d-\d\dT[\d:.]+Z)\s*(.*)$/;
-function linear() {
-    const key = readLinearKey();
-    if (!key)
-        throw new Error('No Linear API key. Run vsf agents key');
-    return createLinear(key);
+export { parsePlistArgs } from "./launchd.js";
+// Trackers the workflows' card triggers use.
+export const trackersInUse = (config) => [
+    ...new Set(Object.values(config.workflows).flatMap((w) => w.triggers.filter(isCardTrigger).map((t) => t.source))),
+];
+// A card by id, from the tracker of a workflow that starts on its team.
+async function findCard(config, trackers, id) {
+    const team = id.split('-')[0].toUpperCase();
+    const sources = [...new Set(Object.values(config.workflows).flatMap((w) => w.triggers.filter(isCardTrigger).filter((t) => t.team === team).map((t) => t.source)))];
+    if (!sources.length)
+        throw new Error(`No workflow starts on team ${team}.`);
+    let last = null;
+    for (const source of sources) {
+        try {
+            const tracker = trackers(source);
+            return { card: await tracker.card(id), tracker, source };
+        }
+        catch (err) {
+            last = err;
+        }
+    }
+    throw last;
 }
 const logPath = (configDir) => join(agentsDir(configDir), 'runner.log');
 const program = (ctx) => [...ctx.selfCommand, 'agents', 'tick'];
@@ -88,12 +104,6 @@ export function scanRunnerErrors(text, now) {
     }
     return { count: bad.length, last: bad.at(-1) ?? '' };
 }
-// The <string> values of a launchd plist's ProgramArguments.
-export function parsePlistArgs(plist) {
-    const block = /<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/.exec(plist)?.[1] ?? '';
-    const unxml = (s) => s.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&');
-    return [...block.matchAll(/<string>([\s\S]*?)<\/string>/g)].map((m) => unxml(m[1]));
-}
 function lastTickOf(text) {
     for (const line of text.split('\n').reverse()) {
         const m = ISO_LINE.exec(line);
@@ -160,7 +170,7 @@ const guard = (fn) => async (args, ctx) => {
 };
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 function runnerState(ctx) {
-    if (!runnerLoaded())
+    if (!runnerService().loaded())
         return 'stopped';
     return isPaused(ctx.configDir) ? 'paused' : 'running';
 }
@@ -184,7 +194,7 @@ export async function cancelCurrent(ctx, c, deps) {
                 // gone just now
             }
         }
-        ctx.log(c.card ? `Cancelled ${c.card}.` : 'Stopped a check of Linear.');
+        ctx.log(c.card ? `Cancelled ${c.card}.` : 'Stopped a check.');
         return;
     }
     // Dead or a reused pid: no signal, just tidy up what it left behind.
@@ -198,47 +208,58 @@ export async function cancelCurrent(ctx, c, deps) {
             // the record is only a nicety
         }
     }
-    if (c.card) {
-        const label = readAgentsConfig(ctx.configDir).workflows[c.workflow ?? '']?.triggers[0]?.label ?? "the workflow's label";
-        await deps.cancelCard(c.card, label);
+    if (c.card && c.source !== 'cron') {
+        const first = readAgentsConfig(ctx.configDir).workflows[c.workflow ?? '']?.triggers.find(isCardTrigger);
+        await deps.cancelCard(c.card, first?.label ?? "the workflow's label", c.source ?? 'linear');
         ctx.log(`Cleared a stale lock and cancelled ${c.card}.`);
     }
     else
         ctx.log('Cleared a stale lock.');
     clearCurrent(ctx.configDir);
 }
-const realDeps = (ctx, l) => ({
+const realDeps = (ctx) => ({
     ours,
     kill: (pid, signal) => process.kill(pid, signal),
     sleep,
-    cancelCard: (card, label) => cancelCard(l(), ctx.configDir, card, label),
+    cancelCard: async (card, label, source) => {
+        try {
+            return await cancelCard(trackersFor(ctx.configDir)(source), ctx.configDir, card, label, source);
+        }
+        catch {
+            return false;
+        }
+    },
 });
 async function startCmd(ctx) {
     if (!Object.keys(readAgentsConfig(ctx.configDir).workflows).length) {
         ctx.log('No workflows yet. Create one first: vsf agents workflow add.');
         return 1;
     }
-    try {
-        await linear().viewer();
-    }
-    catch (err) {
-        const msg = err.message;
-        ctx.log(/^No Linear API key/.test(msg) ? msg : `Linear did not accept the key: ${msg}. Run vsf agents key.`);
-        return 1;
+    const trackers = trackersFor(ctx.configDir);
+    for (const kind of trackersInUse(readAgentsConfig(ctx.configDir))) {
+        try {
+            await trackers(kind).viewer();
+        }
+        catch (err) {
+            const msg = err.message;
+            const flag = kind === 'linear' ? '' : ` --${kind}`;
+            ctx.log(/^No .* API key/.test(msg) ? msg : `${TRACKERS[kind].name} did not accept the key: ${msg}. Run vsf agents key${flag}.`);
+            return 1;
+        }
     }
     setPaused(ctx.configDir, false);
-    if (!startRunner(ctx.home, program(ctx), logPath(ctx.configDir))) {
+    if (!runnerService().start(ctx.home, program(ctx), logPath(ctx.configDir))) {
         ctx.log('Could not start the runner. Check vsf agents logs.');
         return 1;
     }
     return 0;
 }
 async function stopCmd(ctx) {
-    stopRunner(ctx.home);
-    // launchd may have stopped the pass; finish or tidy up whatever the lock still names.
+    runnerService().stop(ctx.home);
+    // Stopping the runner may have stopped the pass; finish or tidy up whatever the lock still names.
     const c = readCurrent(ctx.configDir);
     if (c)
-        await cancelCurrent(ctx, c, realDeps(ctx, linear));
+        await cancelCurrent(ctx, c, realDeps(ctx));
     ctx.log('Runner stopped.');
     return 0;
 }
@@ -271,7 +292,7 @@ const status = guard(async (args, ctx) => {
         return 0;
     }
     const working = current && !current.card
-        ? ' Checking Linear now.'
+        ? ' Checking now.'
         : current
             ? ` Working on ${current.card ?? 'a card'}${current.title ? ` "${current.title}"` : ''} (${[current.workflow, current.step, current.round !== undefined ? `round ${current.round + 1}` : '', `${current.elapsedMinutes}m`].filter(Boolean).join(', ')}).`
             : '';
@@ -296,7 +317,7 @@ const start = guard(async (args, ctx) => {
         return p;
     const code = await startCmd(ctx);
     if (!code)
-        ctx.log('Runner started. It checks Linear every minute for cards that start your workflows.');
+        ctx.log('Runner started. Every minute it checks for cards and schedules that start your workflows.');
     return code;
 });
 const stop = guard(async (args, ctx) => {
@@ -358,7 +379,7 @@ const run = guard(async (args, ctx) => {
             return 2;
         }
     }
-    const code = await tick({ configDir: ctx.configDir, config, linear: linear(), log: ctx.log, selfCommand: ctx.selfCommand }, card, { workflow, from });
+    const code = await tick({ configDir: ctx.configDir, config, trackers: trackersFor(ctx.configDir), log: ctx.log, selfCommand: ctx.selfCommand }, card, { workflow, from });
     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.');
@@ -383,7 +404,7 @@ const cancel = guard(async (args, ctx) => {
         ctx.log(`${c.card ?? 'Another card'} is running, not ${card}.`);
         return 1;
     }
-    await cancelCurrent(ctx, c, realDeps(ctx, linear));
+    await cancelCurrent(ctx, c, realDeps(ctx));
     return 0;
 });
 const retry = guard(async (args, ctx) => {
@@ -399,9 +420,17 @@ const retry = guard(async (args, ctx) => {
     }
     const config = readAgentsConfig(ctx.configDir);
     const names = Object.keys(config.workflows);
-    const l = linear();
-    const card = await l.card(id);
-    const startsOn = (n) => config.workflows[n].triggers.some((t) => t.team === card.teamKey);
+    let found;
+    try {
+        found = await findCard(config, trackersFor(ctx.configDir), id);
+    }
+    catch (err) {
+        ctx.log(err.message);
+        return 1;
+    }
+    const { card, source } = found;
+    const l = found.tracker;
+    const startsOn = (n) => config.workflows[n].triggers.some((t) => isCardTrigger(t) && t.source === source && t.team === card.teamKey);
     let chosen;
     if (p.values.workflow) {
         const r = resolveName(names, p.values.workflow, 'workflow');
@@ -428,7 +457,7 @@ const retry = guard(async (args, ctx) => {
         }
         chosen = candidates[0];
     }
-    const label = config.workflows[chosen].triggers.find((t) => t.team === card.teamKey).label;
+    const label = config.workflows[chosen].triggers.filter(isCardTrigger).find((t) => t.source === source && t.team === card.teamKey).label;
     const next = card.labels.filter((n) => !isStatusLabel(n));
     if (!next.includes(label))
         next.push(label);
@@ -479,7 +508,7 @@ const show = guard(async (args, ctx) => {
     }
     let labels = null;
     try {
-        labels = (await linear().card(id)).labels;
+        labels = (await findCard(readAgentsConfig(ctx.configDir), trackersFor(ctx.configDir), id)).card.labels;
     }
     catch {
         // live labels are optional
@@ -646,16 +675,12 @@ const clean = guard(async (args, ctx) => {
     ctx.log(`Removed ${plural(worktrees.length, 'worktree')} and ${plural(old.length, 'run')}.`);
     return 0;
 });
-// Internal: launchd runs this every minute.
+// Internal: the runner (launchd or systemd) runs this every minute.
 const tickCmd = async (_args, ctx) => {
     const stamped = (l) => ctx.log(`${new Date().toISOString()} ${l}`);
     try {
         const config = readAgentsConfig(ctx.configDir);
-        if (!readLinearKey()) {
-            stamped('No Linear API key. Run vsf agents key.');
-            return 1;
-        }
-        return await tick({ configDir: ctx.configDir, config, linear: linear(), log: stamped, selfCommand: ctx.selfCommand });
+        return await tick({ configDir: ctx.configDir, config, trackers: trackersFor(ctx.configDir), log: stamped, selfCommand: ctx.selfCommand });
     }
     catch (err) {
         stamped(`Could not run the check: ${err.message}`);
@@ -686,13 +711,14 @@ export async function controlChecks(ctx) {
     const checks = [];
     const state = runnerState(ctx);
     checks.push(state === 'running'
-        ? { name: 'agent runner', status: 'ok', detail: 'polling Linear every minute' }
+        ? { name: 'agent runner', status: 'ok', detail: 'checking every minute' }
         : state === 'paused'
             ? { name: 'agent runner', status: 'warn', detail: 'paused', fix: 'vsf agents resume' }
             : { name: 'agent runner', status: 'warn', detail: 'not running', fix: 'vsf agents start' });
-    const plist = plistPath(ctx.home);
-    if (existsSync(plist)) {
-        const missing = parsePlistArgs(readFileSync(plist, 'utf8')).filter((a) => a.startsWith('/') && !existsSync(a));
+    const service = runnerService();
+    const installed = service.programArgs(ctx.home);
+    if (installed) {
+        const missing = installed.filter((a) => a.startsWith('/') && !existsSync(a));
         checks.push(missing.length
             ? { name: 'runner program', status: 'fail', detail: `runner points at a missing ${missing[0]}`, fix: 'vsf agents restart' }
             : { name: 'runner program', status: 'ok', detail: 'found' });
@@ -706,6 +732,7 @@ export async function controlChecks(ctx) {
             ? { name: 'runner errors', status: 'warn', detail: `${plural(count, 'error')} in the last hour, last: ${last.slice(0, 120)}`, fix: 'vsf agents logs' }
             : { name: 'runner errors', status: 'ok', detail: 'no errors in the last hour' });
     }
+    checks.push(...service.checks());
     checks.push(engineLogin(readAgentsConfig(ctx.configDir).engine));
     return checks;
 }

package/dist/cron.d.ts

@@ -0,0 +1,9 @@
+export interface Schedule {
+    sets: Set<number>[];
+    anyDom: boolean;
+    anyDow: boolean;
+}
+export declare function parseCron(schedule: string): Schedule | null;
+export declare function matches(s: Schedule, d: Date): boolean;
+export declare const CATCH_UP_MS: number;
+export declare function lastDue(s: Schedule, since: Date, now: Date): Date | null;

package/dist/cron.js

@@ -0,0 +1,66 @@
+// Five field cron schedules: minute hour day-of-month month day-of-week, each
+// a list of *, numbers, ranges and steps (*/15, 1-5, 0,30). Sunday is 0 or 7.
+// When both day fields are restricted, either may match, as in classic cron.
+const FIELDS = [
+    [0, 59],
+    [0, 23],
+    [1, 31],
+    [1, 12],
+    [0, 7],
+];
+function field(text, [min, max]) {
+    const out = new Set();
+    for (const part of text.split(',')) {
+        const m = /^(\*|(\d+)(?:-(\d+))?)(?:\/(\d+))?$/.exec(part);
+        if (!m)
+            return null;
+        const step = m[4] ? Number(m[4]) : 1;
+        const lo = m[1] === '*' ? min : Number(m[2]);
+        const hi = m[1] === '*' ? max : m[3] ? Number(m[3]) : m[4] ? max : lo;
+        if (step < 1 || lo < min || hi > max || lo > hi)
+            return null;
+        for (let v = lo; v <= hi; v += step)
+            out.add(v);
+    }
+    return out;
+}
+export function parseCron(schedule) {
+    const parts = schedule.trim().split(/\s+/);
+    if (parts.length !== 5)
+        return null;
+    const sets = [];
+    for (let i = 0; i < 5; i++) {
+        const s = field(parts[i], FIELDS[i]);
+        if (!s)
+            return null;
+        sets.push(s);
+    }
+    if (sets[4].has(7))
+        sets[4].add(0);
+    return { sets, anyDom: parts[2] === '*', anyDow: parts[4] === '*' };
+}
+export function matches(s, d) {
+    const [min, hour, dom, month, dow] = s.sets;
+    if (!min.has(d.getMinutes()) || !hour.has(d.getHours()) || !month.has(d.getMonth() + 1))
+        return false;
+    const domOk = dom.has(d.getDate());
+    const dowOk = dow.has(d.getDay());
+    if (s.anyDom || s.anyDow)
+        return domOk && dowOk;
+    return domOk || dowOk;
+}
+const MINUTE = 60_000;
+// How far back a missed schedule is still made up for, e.g. after the runner
+// was busy or the machine was off. Older misses are skipped, not queued.
+export const CATCH_UP_MS = 24 * 60 * MINUTE;
+// The latest minute after `since` and up to `now` that the schedule matches,
+// or null. Only the latest counts: several missed runs fire once.
+export function lastDue(s, since, now) {
+    const floor = Math.max(since.getTime(), now.getTime() - CATCH_UP_MS);
+    const t = new Date(now);
+    t.setSeconds(0, 0);
+    for (; t.getTime() > floor; t.setTime(t.getTime() - MINUTE))
+        if (matches(s, t))
+            return new Date(t);
+    return null;
+}