@voidlabs.gg/voidshift-agents 0.4.3 → 0.4.4

package/dist/manage.js

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { AGENTS, STEPS } from "./config.js";
+import { AGENTS, STEPS, describeTrigger, triggerSpec } from "./config.js";
+import { parseCron } from "./cron.js";
 const isInt = (v, min, max) => typeof v === 'number' && Number.isInteger(v) && v >= min && v <= max;
 // Everything wrong with one workflow, in plain words. Empty means it is fine.
 export function validateWorkflow(config, workflow) {
@@ -8,10 +9,20 @@ export function validateWorkflow(config, workflow) {
     if (!workflow.triggers?.length)
         problems.push('Needs at least one trigger.');
     for (const t of workflow.triggers ?? []) {
-        if (!t.team?.trim())
-            problems.push('A trigger has no team.');
-        if (!t.label?.trim())
-            problems.push('A trigger has no label.');
+        if (t.source === 'cron') {
+            if (!parseCron(t.schedule ?? ''))
+                problems.push(`Schedule ${t.schedule} is not a five field cron schedule, like 0 5 * * 1.`);
+            if (!t.task?.trim())
+                problems.push('A schedule has no task.');
+        }
+        else if (t.source !== 'linear' && t.source !== 'voidtrack')
+            problems.push(`Unknown trigger source ${t.source}.`);
+        else {
+            if (!t.team?.trim())
+                problems.push('A trigger has no team.');
+            if (!t.label?.trim())
+                problems.push('A trigger has no label.');
+        }
     }
     if (!workflow.steps?.length)
         problems.push('Needs at least one step.');
@@ -27,16 +38,27 @@ export function validateWorkflow(config, workflow) {
         problems.push('Rounds must be a whole number from 1 to 9.');
     return problems;
 }
-// "ENG:vs-plan" into a trigger; the team is upper-cased.
+export const TRIGGER_FORMS = 'TEAM:LABEL (Linear), voidtrack:TEAM:LABEL, or cron:SCHEDULE:TASK';
+// "ENG:vs-plan" (Linear, also "linear:ENG:vs-plan"), "voidtrack:ORG:vs-start"
+// or "cron:0 5 * * 1:Update the dependencies" into a trigger. Teams are
+// upper-cased; a schedule must parse.
 export function parseTrigger(input) {
-    const i = input.indexOf(':');
-    if (i < 0)
+    const text = input.trim();
+    // A source prefix decides the form; a bare TEAM:LABEL is Linear.
+    if (text.startsWith('cron:')) {
+        const cron = /^cron:([^:]+):([\s\S]+)$/.exec(text);
+        const schedule = cron?.[1].trim().replace(/\s+/g, ' ') ?? '';
+        const task = cron?.[2].trim() ?? '';
+        return parseCron(schedule) && task ? { source: 'cron', schedule, task } : null;
+    }
+    const m = /^(linear|voidtrack):/.test(text) ? /^(linear|voidtrack):([^:]+):(.+)$/.exec(text) : /^()([^:]+):(.+)$/.exec(text);
+    if (!m)
         return null;
-    const team = input.slice(0, i).trim().toUpperCase();
-    const label = input.slice(i + 1).trim();
-    return team && label ? { source: 'linear', team, label } : null;
+    const team = m[2].trim().toUpperCase();
+    const label = m[3].trim();
+    return team && label ? { source: (m[1] || 'linear'), team, label } : null;
 }
-export const sameTrigger = (a, b) => a.team === b.team && a.label === b.label;
+export const sameTrigger = (a, b) => triggerSpec(a) === triggerSpec(b);
 // Warning lines for triggers this workflow shares with another one. Only the
 // first workflow in order starts a card, so the rest never get it.
 export function duplicateTriggerWarnings(workflows, name, workflow) {
@@ -47,7 +69,7 @@ export function duplicateTriggerWarnings(workflows, name, workflow) {
         for (const other of owners) {
             if (other === name)
                 continue;
-            lines.push(`Warning: ${other} also starts on ${t.team} + ${t.label}, and ${first} wins. vsf agents workflow move changes the order.`);
+            lines.push(`Warning: ${other} also starts on ${describeTrigger(t)}, and ${first} wins. vsf agents workflow move changes the order.`);
         }
     }
     return lines;

package/dist/runner.d.ts

@@ -1,9 +1,10 @@
 import { type AgentsConfig, type Workflow, type Project, type StepId, type Trigger } from './config.ts';
-import type { Card, Linear } from './linear.ts';
+import type { Card } from './linear.ts';
+import { type Tracker, type Trackers } from './tracker.ts';
 export interface RunContext {
     configDir: string;
     config: AgentsConfig;
-    linear: Linear;
+    trackers: Trackers;
     log: (line: string) => void;
     selfCommand: string[];
 }
@@ -11,13 +12,19 @@ export declare function summarize(output: string): string;
 export declare function runCard(card: Card, trigger: Trigger, workflowName: string, workflow: Workflow, project: Project, rc: RunContext, opts?: {
     from?: StepId;
 }): Promise<'verified' | 'changes' | 'parked'>;
-export declare function nextJob(rc: RunContext, only?: string, workflowName?: string): Promise<{
+type Job = {
     card: Card;
     trigger: Trigger;
     workflow: string;
-} | null>;
-export declare function cancelCard(linear: Linear, configDir: string, cardId: string, label: string): Promise<boolean>;
+};
+export declare function cronCard(workflow: string, task: string, at: Date): Card;
+export declare function nextJob(rc: RunContext, only?: string, workflowName?: string, opts?: {
+    force?: boolean;
+    now?: Date;
+}): Promise<Job | null>;
+export declare function cancelCard(tracker: Tracker, configDir: string, cardId: string, label: string, source?: 'linear' | 'voidtrack'): Promise<boolean>;
 export declare function tick(rc: RunContext, only?: string, opts?: {
     workflow?: string;
     from?: StepId;
 }): Promise<number>;
+export {};

package/dist/runner.js

@@ -2,11 +2,13 @@ import { existsSync, mkdirSync, readFileSync } from 'node:fs';
 import { basename, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { LABELS, PLAN_HEADING, buildPrompt, findingsFor, fixTarget, isStatusLabel, latestPlan, parseDevResult, parseVerdict, planBody, qaPassed, stageLabels, verdictBlock, } from "./workflow.js";
-import { STEPS, agentsDir, hasWork, isProducer } from "./config.js";
+import { STEPS, agentsDir, hasWork, isCardTrigger, isProducer } from "./config.js";
+import { lastDue, parseCron } from "./cron.js";
 import { runAgent, stopAgents } from "./engine.js";
 import { commitsAhead, defaultBranch, ensureDraftPr, ensureWorktree, headSha, markReady, push, resetWorktree, waitForChecks, waitForPrHead } from "./git.js";
+import { noTracker } from "./tracker.js";
 import { recall, vaultPath } from "./memory.js";
-import { bootTime, clearCurrent, isPaused, ours, readCurrent, readPending, writeCurrent, writePending, writeRun } from "./state.js";
+import { bootTime, clearCurrent, isPaused, ours, readCurrent, readPending, writeCurrent, writePending, writeRun, readCronState, writeCronState } from "./state.js";
 const packDir = fileURLToPath(new URL('../pack/', import.meta.url));
 const skill = (name) => readFileSync(join(packDir, name, 'SKILL.md'), 'utf8');
 const stamp = () => new Date().toISOString().replace(/[:.]/g, '-');
@@ -18,7 +20,7 @@ function withLabels(card, drop, add) {
 const UNATTENDED = `# Running unattended
 
 You are one step in a workflow. Nobody can answer questions and the
-Linear connection is not available: the card and any plan are included above.
+tracker connection is not available: the card and any plan are included above.
 Do not write plan files; return your output as your final message. Make the
 call the code supports and state it.`;
 // Agents keep the memory vault the way you do: durable learnings become notes.
@@ -41,20 +43,23 @@ const isVerdict = (s) => STEPS[s].output === 'verdict';
 // step that produces something, Plan or Dev, and the workflow continues from
 // there, until everything passes or the loop cap parks the card.
 export async function runCard(card, trigger, workflowName, workflow, project, rc, opts = {}) {
-    const { linear, config, log } = rc;
+    const { config, log } = rc;
+    // A scheduled run has no card, so it has nothing to write back to.
+    const linear = isCardTrigger(trigger) ? rc.trackers(trigger.source) : noTracker;
+    const label = isCardTrigger(trigger) ? trigger.label : '';
     const runDir = join(agentsDir(rc.configDir), 'runs', card.identifier, stamp());
     mkdirSync(runDir, { recursive: true });
     const say = (line) => log(`${card.identifier} ${line}`);
     const steps = workflow.steps;
     const startedAt = new Date().toISOString();
-    const record = { card: card.identifier, title: card.title, url: card.url, workflow: workflowName, trigger: trigger.label, steps: [], outcome: 'running', startedAt };
+    const record = { card: card.identifier, title: card.title, url: card.url || undefined, workflow: workflowName, trigger: label || (trigger.source === 'cron' ? trigger.schedule : ''), source: trigger.source, steps: [], outcome: 'running', startedAt };
     active = { record, runDir };
     const save = () => writeRun(runDir, record);
     save();
     let loops = 0;
     // The lock tells status and cancel what is running.
-    const mark = (step) => writeCurrent(rc.configDir, { pid: process.pid, card: card.identifier, title: card.title, workflow: workflowName, step, round: loops, startedAt, runDir });
-    // Written before the first Linear call, so a cancel always knows the card.
+    const mark = (step) => writeCurrent(rc.configDir, { pid: process.pid, card: card.identifier, title: card.title, workflow: workflowName, step, round: loops, startedAt, runDir, source: trigger.source });
+    // Written before the first tracker call, so a cancel always knows the card.
     mark('Starting');
     const begin = (step) => {
         const rec = { step, label: STEPS[step].label, startedAt: new Date().toISOString() };
@@ -84,8 +89,8 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
     const setRound = (n) => {
         loops = n;
     };
-    const stage = (name, round) => linear.setLabels(card, stageLabels(card.labels, trigger.label, name, round));
-    // Linear hears from the runner twice: the plan once it has passed review,
+    const stage = (name, round) => linear.setLabels(card, stageLabels(card.labels, label, name, round));
+    // The tracker hears from the runner twice: the plan once it has passed review,
     // and one final comment. Findings stay here until the final one.
     let lastFindings = '';
     let planToPost = null;
@@ -97,19 +102,21 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
     };
     async function park(reason) {
         say(`parked: ${reason}`);
-        const comment = `**Parked:** ${reason}${lastFindings ? `\n\n${lastFindings}` : ''}\n\nFix the cause, then add \`${trigger.label}\` again to retry.`;
+        const comment = `**Parked:** ${reason}${lastFindings ? `\n\n${lastFindings}` : ''}\n\nFix the cause, then add \`${label}\` again to retry.`;
         const add = [LABELS.parked, ...(loops ? [LABELS.version(loops)] : [])];
         let commented = false;
         try {
             await postPlan();
             await linear.comment(card, comment);
             commented = true;
-            await linear.setLabels(card, stageLabels(card.labels, trigger.label, LABELS.parked, loops || undefined));
+            await linear.setLabels(card, stageLabels(card.labels, label, LABELS.parked, loops || undefined));
         }
         catch (err) {
-            say(`could not reach Linear to park it (${err.message}). Will retry next minute.`);
+            if (!isCardTrigger(trigger))
+                return done('parked', reason);
+            say(`could not reach ${trigger.source === 'voidtrack' ? 'VoidTrack' : 'Linear'} to park it (${err.message}). Will retry next minute.`);
             // An empty comment is skipped on retry, so it is not posted twice.
-            writePending(rc.configDir, [...readPending(rc.configDir), { card: card.identifier, comment: commented ? '' : comment, drop: [trigger.label], add, dropStatus: true }]);
+            writePending(rc.configDir, [...readPending(rc.configDir), { card: card.identifier, comment: commented ? '' : comment, drop: [label], add, dropStatus: true, source: trigger.source }]);
         }
         return done('parked', reason);
     }
@@ -119,7 +126,8 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
         const from = opts.from ? steps.indexOf(opts.from) : 0;
         if (from < 0)
             throw new Park(`Workflow ${workflowName} has no ${STEPS[opts.from].label} step.`);
-        let plan = latestPlan(await linear.comments(card.identifier));
+        // A scheduled run has no card to plan on, so its task is the plan unless a Plan step writes one.
+        let plan = isCardTrigger(trigger) ? latestPlan(await linear.comments(card.identifier)) : card.description ?? null;
         const firstPlan = steps.indexOf('vs-plan', from);
         const needsPlan = steps.findIndex((s, n) => n >= from && (s === 'vs-dev' || s === 'vs-plan-review'));
         if (!plan && needsPlan >= 0 && (firstPlan < 0 || firstPlan > needsPlan)) {
@@ -207,7 +215,7 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
                 if (target < 0) {
                     await postPlan();
                     await linear.comment(card, `**Changes needed.**\n\n${notes}`);
-                    await linear.setLabels(card, stageLabels(card.labels, trigger.label, LABELS.changes, round));
+                    await linear.setLabels(card, stageLabels(card.labels, label, LABELS.changes, round));
                     say('changes requested');
                     return done('changes');
                 }
@@ -278,7 +286,7 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
             markReady(worktree, card.branchName);
             moved = await linear.moveTo(card, config.reviewState);
         }
-        await linear.setLabels(card, stageLabels(card.labels, trigger.label, LABELS.verified, loops || undefined));
+        await linear.setLabels(card, stageLabels(card.labels, label, LABELS.verified, loops || undefined));
         await linear.comment(card, `**All checks passed.**${prUrl ? ` PR ready: ${prUrl}` : ''}${hasWork(workflow) && !moved ? `\n\n(No "${config.reviewState}" state on this team, so the card was not moved.)` : ''}`);
         say('verified');
         return done('verified');
@@ -292,34 +300,107 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
         active = null;
     }
 }
-// The first card waiting on any workflow's triggers, in workflow order.
-// With a workflow name, only that workflow is considered.
-export async function nextJob(rc, only, workflowName) {
-    const pinned = only ? await rc.linear.card(only) : null;
-    for (const [name, workflow] of Object.entries(rc.config.workflows)) {
-        if (workflowName && name !== workflowName)
-            continue;
-        for (const trigger of workflow.triggers) {
-            const cards = pinned ? [pinned] : await rc.linear.myCardsWithLabel(trigger.label);
-            // A pinned card may have lost its label (a parked card re-run by hand), so match by team.
-            const card = cards.find((c) => c.teamKey === trigger.team && (pinned || c.labels.includes(trigger.label)));
-            if (card)
-                return { card, trigger, workflow: name };
+// A scheduled run's stand-in for a card: the task, on a branch of its own.
+export function cronCard(workflow, task, at) {
+    const stamp = at.toISOString().slice(0, 16).replace(/[-:T]/g, '');
+    const slug = workflow.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'cron';
+    return {
+        id: '',
+        identifier: `${slug.replace(/-/g, '').toUpperCase()}-${stamp}`,
+        title: task.split('\n')[0].slice(0, 80),
+        description: task,
+        url: '',
+        branchName: `vs/${slug}-${stamp}`,
+        teamId: '',
+        teamKey: '',
+        labels: [],
+    };
+}
+const cronKey = (workflow, schedule) => `${workflow} ${schedule}`;
+// The first job waiting on any workflow's triggers, in workflow order: a card
+// carrying a trigger label, or a schedule that came due since it last fired.
+// A schedule seen for the first time starts counting from now. With a card,
+// only that card is considered; with a workflow name, only that workflow, and
+// `force` fires its schedule now.
+export async function nextJob(rc, only, workflowName, opts = {}) {
+    const now = opts.now ?? new Date();
+    const workflows = Object.entries(rc.config.workflows).filter(([name]) => !workflowName || name === workflowName);
+    let pinned = null;
+    if (only) {
+        const team = only.split('-')[0].toUpperCase();
+        const sources = [...new Set(workflows.flatMap(([, w]) => w.triggers.filter(isCardTrigger).filter((t) => t.team === team).map((t) => t.source)))];
+        for (const source of sources) {
+            try {
+                pinned = { card: await rc.trackers(source).card(only), source };
+                break;
+            }
+            catch (err) {
+                if (source === sources.at(-1))
+                    throw err;
+            }
         }
+        if (!pinned)
+            return null;
+    }
+    const cron = readCronState(rc.configDir);
+    let cronChanged = false;
+    try {
+        for (const [name, workflow] of workflows) {
+            for (const trigger of workflow.triggers) {
+                if (!isCardTrigger(trigger)) {
+                    const schedule = only ? null : parseCron(trigger.schedule);
+                    if (!schedule)
+                        continue;
+                    const key = cronKey(name, trigger.schedule);
+                    const last = cron[key];
+                    const due = opts.force ? now : last ? lastDue(schedule, new Date(last), now) : null;
+                    if (!last || due) {
+                        cron[key] = now.toISOString();
+                        cronChanged = true;
+                    }
+                    if (due)
+                        return { card: cronCard(name, trigger.task, due), trigger, workflow: name };
+                    continue;
+                }
+                // A pinned card may have lost its label (a parked card re-run by hand), so match by team.
+                if (pinned) {
+                    if (pinned.source === trigger.source && pinned.card.teamKey === trigger.team)
+                        return { card: pinned.card, trigger, workflow: name };
+                    continue;
+                }
+                let cards;
+                try {
+                    cards = await rc.trackers(trigger.source).myCardsWithLabel(trigger.label, trigger.team);
+                }
+                catch (err) {
+                    // One tracker being down or unset must not stop the others.
+                    rc.log(`Could not check ${trigger.source === 'voidtrack' ? 'VoidTrack' : 'Linear'} for ${trigger.team} + ${trigger.label} (${err.message}). Trying again next minute.`);
+                    continue;
+                }
+                const card = cards.find((c) => c.teamKey === trigger.team && c.labels.includes(trigger.label));
+                if (card)
+                    return { card, trigger, workflow: name };
+            }
+        }
+        return null;
+    }
+    finally {
+        if (cronChanged)
+            writeCronState(rc.configDir, cron);
     }
-    return null;
 }
-// Retries Linear writes that failed while parking. Never throws.
+// Retries tracker writes that failed while parking. Never throws.
 async function flushPending(rc) {
     const left = [];
     for (const p of readPending(rc.configDir)) {
         try {
-            const card = await rc.linear.card(p.card);
+            const tracker = rc.trackers(p.source ?? 'linear');
+            const card = await tracker.card(p.card);
             if (p.comment) {
-                await rc.linear.comment(card, p.comment);
+                await tracker.comment(card, p.comment);
                 p.comment = '';
             }
-            await rc.linear.setLabels(card, withLabels(card, (l) => p.drop.includes(l) || (!!p.dropStatus && isStatusLabel(l)), p.add));
+            await tracker.setLabels(card, withLabels(card, (l) => p.drop.includes(l) || (!!p.dropStatus && isStatusLabel(l)), p.add));
         }
         catch {
             left.push(p);
@@ -332,27 +413,27 @@ async function flushPending(rc) {
         // nothing more to do
     }
 }
-// Takes the working label off a cancelled card and says so. When Linear
+// Takes the working label off a cancelled card and says so. When the tracker
 // cannot be reached the same change is queued for the next tick.
-export async function cancelCard(linear, configDir, cardId, label) {
+export async function cancelCard(tracker, configDir, cardId, label, source = 'linear') {
     const comment = `**Cancelled.** Add \`${label}\` again to restart.`;
     try {
-        const card = await linear.card(cardId);
-        await linear.setLabels(card, withLabels(card, isStatusLabel, []));
-        await linear.comment(card, comment);
+        const card = await tracker.card(cardId);
+        await tracker.setLabels(card, withLabels(card, isStatusLabel, []));
+        await tracker.comment(card, comment);
         return true;
     }
     catch {
-        queueCancel(configDir, cardId, comment);
+        queueCancel(configDir, cardId, comment, source);
         return false;
     }
 }
-function queueCancel(configDir, cardId, comment) {
+function queueCancel(configDir, cardId, comment, source = 'linear') {
     const pending = readPending(configDir);
     if (pending.some((p) => p.card === cardId && p.comment === comment))
         return;
     try {
-        writePending(configDir, [...pending, { card: cardId, comment, drop: [], add: [], dropStatus: true }]);
+        writePending(configDir, [...pending, { card: cardId, comment, drop: [], add: [], dropStatus: true, source }]);
     }
     catch {
         // nothing more to do
@@ -385,13 +466,15 @@ export async function tick(rc, only, opts = {}) {
                 // the run folder is gone
             }
         }
-        if (running) {
+        if (running && running.record.source !== 'cron') {
             const { card, trigger } = running.record;
+            const source = running.record.source ?? 'linear';
             const timeout = new Promise((resolve) => setTimeout(() => resolve(false), 5000).unref());
-            const finished = await Promise.race([cancelCard(rc.linear, rc.configDir, card, trigger), timeout]);
+            const work = (async () => cancelCard(rc.trackers(source), rc.configDir, card, trigger, source))().catch(() => false);
+            const finished = await Promise.race([work, timeout]);
             // Did not finish in time: leave the work for the next tick.
             if (!finished)
-                queueCancel(rc.configDir, card, `**Cancelled.** Add \`${trigger}\` again to restart.`);
+                queueCancel(rc.configDir, card, `**Cancelled.** Add \`${trigger}\` again to restart.`, source);
         }
         clearCurrent(rc.configDir);
         process.exit(143);
@@ -404,10 +487,10 @@ export async function tick(rc, only, opts = {}) {
             return 0;
         let job;
         try {
-            job = await nextJob(rc, only, opts.workflow);
+            job = await nextJob(rc, only, opts.workflow, { force: !!opts.workflow && !only });
         }
         catch (err) {
-            rc.log(`Could not check Linear (${err.message}). Trying again next minute.`);
+            rc.log(`Could not read ${only} (${err.message}).`);
             return 1;
         }
         if (!job) {

package/dist/state.d.ts

@@ -1,4 +1,4 @@
-import { type StepId } from './config.ts';
+import { type StepId, type Trigger } from './config.ts';
 export interface Current {
     pid: number;
     card?: string;
@@ -8,6 +8,7 @@ export interface Current {
     round?: number;
     startedAt?: string;
     runDir?: string;
+    source?: Trigger['source'];
 }
 export declare const lockPath: (configDir: string) => string;
 export declare function readCurrent(configDir: string): Current | null;
@@ -25,6 +26,7 @@ export interface Pending {
     drop: string[];
     add: string[];
     dropStatus?: boolean;
+    source?: 'linear' | 'voidtrack';
 }
 export declare function readPending(configDir: string): Pending[];
 export declare function writePending(configDir: string, pending: Pending[]): void;
@@ -44,6 +46,7 @@ export interface RunRecord {
     url?: string;
     workflow: string;
     trigger: string;
+    source?: Trigger['source'];
     steps: StepRecord[];
     outcome: Outcome;
     reason?: string;
@@ -61,3 +64,5 @@ export interface RunEntry {
     logs: string[];
 }
 export declare function listRuns(configDir: string, card?: string): RunEntry[];
+export declare function readCronState(configDir: string): Record<string, string>;
+export declare function writeCronState(configDir: string, state: Record<string, string>): void;

package/dist/state.js

@@ -105,3 +105,18 @@ export function listRuns(configDir, card) {
     }
     return out.sort((a, b) => (a.stamp < b.stamp ? 1 : -1));
 }
+// When each schedule last fired, by workflow and schedule, so a restart or a
+// busy runner never fires one twice.
+const cronPath = (configDir) => join(agentsDir(configDir), 'cron.json');
+export function readCronState(configDir) {
+    try {
+        return JSON.parse(readFileSync(cronPath(configDir), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+export function writeCronState(configDir, state) {
+    mkdirSync(agentsDir(configDir), { recursive: true });
+    writeFileSync(cronPath(configDir), JSON.stringify(state, null, 2) + '\n');
+}

package/dist/tracker.d.ts

@@ -0,0 +1,24 @@
+import type { Tracker as Kind } from './config.ts';
+import type { Card } from './linear.ts';
+export interface Tracker {
+    viewer(): Promise<{
+        id: string;
+        name: string;
+    }>;
+    myCardsWithLabel(label: string, team: string): Promise<Card[]>;
+    card(identifier: string): Promise<Card>;
+    comments(identifier: string): Promise<{
+        body: string;
+        createdAt: string;
+    }[]>;
+    comment(card: Card, body: string): Promise<void>;
+    setLabels(card: Card, next: string[]): Promise<void>;
+    moveTo(card: Card, stateName: string): Promise<boolean>;
+}
+export declare const TRACKERS: Record<Kind, {
+    name: string;
+    keyHint: string;
+}>;
+export type Trackers = (kind: Kind) => Tracker;
+export declare function trackersFor(configDir: string): Trackers;
+export declare const noTracker: Tracker;

package/dist/tracker.js

@@ -0,0 +1,36 @@
+import { createLinear } from "./linear.js";
+import { readSecret } from "./secrets.js";
+import { createVoidTrack } from "./voidtrack.js";
+export const TRACKERS = {
+    linear: { name: 'Linear', keyHint: 'Linear > Settings > Security & access > API keys' },
+    voidtrack: { name: 'VoidTrack', keyHint: 'VoidTrack > Settings > API keys' },
+};
+export function trackersFor(configDir) {
+    const open = new Map();
+    return (kind) => {
+        let t = open.get(kind);
+        if (!t) {
+            const key = readSecret(configDir, kind);
+            if (!key)
+                throw new Error(`No ${TRACKERS[kind].name} API key. Run vsf agents key${kind === 'linear' ? '' : ` --${kind}`}`);
+            t = kind === 'voidtrack' ? createVoidTrack(key) : createLinear(key);
+            open.set(kind, t);
+        }
+        return t;
+    };
+}
+// Stands in for a tracker on a scheduled run, which has no card: reads find
+// nothing and writes go nowhere.
+export const noTracker = {
+    viewer: async () => ({ id: '', name: '' }),
+    myCardsWithLabel: async () => [],
+    card: async (id) => {
+        throw new Error(`a scheduled run has no card ${id}`);
+    },
+    comments: async () => [],
+    comment: async () => { },
+    setLabels: async (card, next) => {
+        card.labels = next;
+    },
+    moveTo: async () => false,
+};

package/dist/voidtrack.d.ts

@@ -0,0 +1,18 @@
+import type { Card } from './linear.ts';
+export declare const branchFor: (identifier: string) => string;
+export declare function mapIssue(i: any, web: string): Card;
+export declare function createVoidTrack(apiKey: string, fetcher?: typeof fetch): {
+    viewer(): Promise<{
+        id: string;
+        name: string;
+    }>;
+    myCardsWithLabel(label: string, team: string): Promise<Card[]>;
+    card(identifier: string): Promise<Card>;
+    comments(identifier: string): Promise<{
+        body: string;
+        createdAt: string;
+    }[]>;
+    comment(card: Card, body: string): Promise<void>;
+    setLabels(card: Card, next: string[]): Promise<void>;
+    moveTo(card: Card, stateName: string): Promise<boolean>;
+};

package/dist/voidtrack.js

@@ -0,0 +1,89 @@
+// VoidTrack over its REST API with a bearer key. Self hosted installs set
+// VOIDTRACK_API_URL; the web app lives at the same address without /api.
+const apiBase = () => (process.env.VOIDTRACK_API_URL ?? 'https://web.voidtrack.app/api').replace(/\/$/, '');
+// One branch per card that survives a retitle: GitHub closes a pull request
+// whose branch is renamed.
+export const branchFor = (identifier) => identifier.toLowerCase();
+export function mapIssue(i, web) {
+    return {
+        id: i.id,
+        identifier: i.identifier,
+        title: i.title,
+        description: i.description ?? undefined,
+        url: `${web}/issue/${i.identifier}`,
+        branchName: branchFor(i.identifier),
+        teamId: i.team?.id ?? '',
+        teamKey: i.team?.key ?? i.identifier.split('-')[0],
+        projectName: i.project?.name ?? undefined,
+        labels: (i.labels ?? []).map((l) => (typeof l === 'string' ? l : l.name)),
+    };
+}
+export function createVoidTrack(apiKey, fetcher = fetch) {
+    const base = apiBase();
+    const web = base.replace(/\/api$/, '');
+    async function call(method, path, body) {
+        let res;
+        try {
+            res = await fetcher(`${base}${path}`, {
+                method,
+                signal: AbortSignal.timeout(30_000),
+                headers: { Authorization: `Bearer ${apiKey}`, ...(body === undefined ? {} : { 'Content-Type': 'application/json' }) },
+                body: body === undefined ? undefined : JSON.stringify(body),
+            });
+        }
+        catch (err) {
+            const cause = err.cause;
+            throw new Error(`could not reach VoidTrack (${cause?.code ?? cause?.message ?? err.message})`);
+        }
+        const text = await res.text();
+        if (!res.ok)
+            throw Object.assign(new Error(`voidtrack ${method} ${path.split('?')[0]} ${res.status}: ${text.slice(0, 200)}`), { status: res.status });
+        return text ? JSON.parse(text) : {};
+    }
+    const enc = encodeURIComponent;
+    return {
+        async viewer() {
+            const d = await call('GET', '/v1/users');
+            const me = (d.users ?? []).find((u) => u.isMe);
+            if (!me)
+                throw new Error('voidtrack did not say which user this key belongs to');
+            return { id: me.id, name: me.name };
+        },
+        // My open cards in the team carrying the label. The API cannot filter on
+        // labels, so that part happens here.
+        async myCardsWithLabel(label, team) {
+            const d = await call('GET', `/v1/issues?team=${enc(team)}&assignee=me&stateType=backlog,unstarted,started&sort=created&limit=200`);
+            return (d.issues ?? []).map((i) => mapIssue(i, web)).filter((c) => c.labels.includes(label));
+        },
+        async card(identifier) {
+            const d = await call('GET', `/v1/issues/${enc(identifier)}`);
+            if (!d.issue)
+                throw new Error(`voidtrack has no card ${identifier}`);
+            return mapIssue(d.issue, web);
+        },
+        async comments(identifier) {
+            const d = await call('GET', `/v1/issues/${enc(identifier)}/comments`);
+            return (d.comments ?? []).map((c) => ({ body: c.body, createdAt: c.createdAt }));
+        },
+        async comment(card, body) {
+            await call('POST', `/v1/issues/${enc(card.identifier)}/comments`, { body });
+        },
+        // Labels are free text on VoidTrack and the list replaces the whole set.
+        async setLabels(card, next) {
+            await call('PATCH', `/v1/issues/${enc(card.identifier)}`, { labels: next });
+            card.labels = next;
+        },
+        // Move to a named state; false if the team has no such state.
+        async moveTo(card, stateName) {
+            try {
+                await call('PATCH', `/v1/issues/${enc(card.identifier)}`, { state: stateName });
+                return true;
+            }
+            catch (err) {
+                if (err.status === 400 || err.status === 404)
+                    return false;
+                throw err;
+            }
+        },
+    };
+}