@voidlabs.gg/voidshift-agents 0.4.3 → 0.4.5

package/dist/manage.js

@@ -1,42 +1,154 @@
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { AGENTS, STEPS } from "./config.js";
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { AGENTS, AGENT_FILE, OUTPUTS, STEP_ID, isBuiltin, readAgentFolder, stepFile, 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;
+// The line a step's prompt must ask for, so the runner can read the result.
+const RESULT_LINE = { plan: 'RESULT:', commits: 'RESULT:', verdict: 'VERDICT:' };
+// Everything wrong with one step. `dir` is the agent folder its files are in.
+export function validateStep(step, config, dir) {
+    if (typeof step === 'string') {
+        if (!isBuiltin(step))
+            return [`Unknown step ${step}.`];
+        return config.enabled.length && !config.enabled.includes(step) ? [`Step ${step} is not enabled.`] : [];
+    }
+    if (!isObj(step))
+        return ['A step must be a step id or an object.'];
+    const problems = [];
+    const id = typeof step.id === 'string' && STEP_ID.test(step.id) ? step.id : null;
+    if (!id)
+        problems.push(`Step id ${String(step.id)} must be lowercase letters, digits and dashes.`);
+    else if (isBuiltin(id))
+        problems.push(`Step id ${id} is a built-in step; use "${id}" on its own, or another id.`);
+    const name = id ?? 'A step';
+    if (!OUTPUTS.includes(step.output))
+        problems.push(`${name} output must be one of: ${OUTPUTS.join(', ')}.`);
+    if (step.label !== undefined && typeof step.label !== 'string')
+        problems.push(`${name} label must be text.`);
+    if (step.prompt !== undefined && typeof step.prompt !== 'string')
+        problems.push(`${name} prompt must be a file name.`);
+    if (step.skill !== undefined && typeof step.skill !== 'string')
+        problems.push(`${name} skill must be a name or a folder.`);
+    const sources = [step.skill, step.prompt].filter((v) => v !== undefined).length;
+    if (step.output === 'publish') {
+        if (sources)
+            problems.push(`${name} only pushes the branch, so it takes no skill or prompt.`);
+    }
+    else if (sources !== 1)
+        problems.push(`${name} needs exactly one of skill or prompt.`);
+    else if (typeof (step.prompt ?? step.skill) === 'string') {
+        const file = stepFile(step, dir);
+        if (!file || !existsSync(file))
+            problems.push(`${name} ${step.prompt ? 'prompt' : 'skill'} ${file ?? ''} does not exist.`);
+        else {
+            const want = RESULT_LINE[step.output];
+            if (want && !readFileSync(file, 'utf8').includes(want))
+                problems.push(`${name} prompt never asks for a ${want} line.`);
+        }
+    }
+    if (step.engine !== undefined && step.engine !== 'claude' && step.engine !== 'codex')
+        problems.push(`${name} engine must be claude or codex.`);
+    if (step.model !== undefined && typeof step.model !== 'string')
+        problems.push(`${name} model must be text.`);
+    if (step.timeoutMinutes !== undefined && !isInt(step.timeoutMinutes, 1, 480))
+        problems.push(`${name} timeoutMinutes must be a whole number from 1 to 480.`);
+    if (step.write !== undefined && typeof step.write !== 'boolean')
+        problems.push(`${name} write must be true or false.`);
+    else if (step.write === false && step.output === 'commits')
+        problems.push(`${name} makes commits, so write cannot be false.`);
+    return problems;
+}
 // Everything wrong with one workflow, in plain words. Empty means it is fine.
-export function validateWorkflow(config, workflow) {
+// `dir` is the agent folder a folder workflow comes from.
+export function validateWorkflow(config, workflow, dir) {
     const problems = [];
     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.');
-    for (const s of workflow.steps ?? []) {
-        if (!(s in STEPS))
-            problems.push(`Unknown step ${s}.`);
-        else if (config.enabled.length && !config.enabled.includes(s))
-            problems.push(`Step ${s} is not enabled.`);
+    const ids = new Set();
+    for (const s of Array.isArray(workflow.steps) ? workflow.steps : []) {
+        problems.push(...validateStep(s, config, dir));
+        const id = typeof s === 'string' ? s : isObj(s) ? s.id : undefined;
+        if (typeof id === 'string' && !isBuiltin(id)) {
+            if (ids.has(id))
+                problems.push(`Step id ${id} is used twice.`);
+            ids.add(id);
+        }
     }
     if (!config.projects[workflow.project])
         problems.push(`Project ${workflow.project} does not exist.`);
     if (!isInt(workflow.maxRounds, 1, 9))
         problems.push('Rounds must be a whole number from 1 to 9.');
+    const wb = workflow.writeBack;
+    if (wb !== undefined) {
+        if (!isObj(wb))
+            problems.push('writeBack must be an object.');
+        else {
+            if (wb.labels !== undefined && typeof wb.labels !== 'boolean')
+                problems.push('writeBack.labels must be true or false.');
+            if (wb.comment !== undefined && typeof wb.comment !== 'boolean')
+                problems.push('writeBack.comment must be true or false.');
+            if (wb.state !== undefined && wb.state !== null && (typeof wb.state !== 'string' || !wb.state.trim()))
+                problems.push('writeBack.state must be a state name, or null to never move the card.');
+        }
+    }
     return problems;
 }
-// "ENG:vs-plan" into a trigger; the team is upper-cased.
+// Everything wrong with an agent folder: its agent.json, its workflow and
+// prompt files, and a name config.json already uses.
+export function validateAgentFolder(dir, config) {
+    let workflow;
+    try {
+        workflow = readAgentFolder(dir);
+    }
+    catch (err) {
+        return [`${AGENT_FILE}: ${err.message}`];
+    }
+    const problems = validateWorkflow(config, workflow, dir);
+    const name = basename(dir);
+    const from = config.folders?.[name];
+    if (config.workflows[name] && (!from || resolve(from) !== resolve(dir)))
+        problems.push(`config.json already has a workflow named ${name}, and it wins. Rename the folder.`);
+    return problems;
+}
+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 +159,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;
@@ -99,6 +211,8 @@ export function validateConfig(value, saved) {
     }
     if (!Array.isArray(value.enabled) || value.enabled.some((a) => typeof a !== 'string' || !(a in AGENTS)))
         problems.push(`enabled must list agents from: ${Object.keys(AGENTS).join(', ')}.`);
+    if (value.commits !== undefined && (!isObj(value.commits) || Object.entries(value.commits).some(([k, v]) => !['signOff', 'dropAiTrailers'].includes(k) || typeof v !== 'boolean')))
+        problems.push('commits may only set signOff and dropAiTrailers, each true or false.');
     if (!Array.isArray(value.homes) || value.homes.some((h) => !isObj(h) || (h.kind !== 'claude' && h.kind !== 'codex') || typeof h.dir !== 'string'))
         problems.push('homes must be a list of { kind: claude or codex, dir }.');
     if (!isObj(value.workflows))
@@ -106,6 +220,9 @@ export function validateConfig(value, saved) {
     else {
         const ctx = { enabled: Array.isArray(value.enabled) ? value.enabled : [], projects: (projects ?? {}) };
         for (const [name, w] of Object.entries(value.workflows)) {
+            // Folder workflows are checked with their folder, by vsf agents validate.
+            if (isObj(value.folders) && value.folders[name])
+                continue;
             if (!isObj(w))
                 problems.push(`Workflow ${name} must be an object.`);
             else {

package/dist/names.d.ts

@@ -5,4 +5,5 @@ export declare function resolveName(names: string[], input: string, kind: string
     error: string;
 };
 export declare function parseStep(input: string): StepId | null;
+export declare const parseFrom: (input: string) => string | null;
 export declare const stepNames: () => string;

package/dist/names.js

@@ -1,4 +1,4 @@
-import { STEPS } from "./config.js";
+import { STEPS, STEP_ID } from "./config.js";
 // A workflow or project named in a command: the exact name, or the start of
 // exactly one name, e.g. "tether" for tether-relay-build.
 export function resolveName(names, input, kind) {
@@ -23,4 +23,7 @@ export function parseStep(input) {
     }
     return null;
 }
+// A step for --from: a built-in step by any of its names, or any id a custom
+// step could have. Whether the workflow has it is checked once it is known.
+export const parseFrom = (input) => parseStep(input) ?? (STEP_ID.test(input) ? input : null);
 export const stepNames = () => Object.keys(STEPS).map((id) => id.replace(/^vs-/, '')).join(', ');

package/dist/profile.d.ts

@@ -0,0 +1,10 @@
+import type { Check } from './types.ts';
+export declare const profileDir: (configDir: string) => string;
+export declare const RULES_FILE = "RULES.md";
+export declare const CLAUDE_SETTINGS = "claude-settings.json";
+export declare function readRules(configDir: string): string;
+export declare function renderClaudeSettings(configDir: string): string | null;
+export declare function claudeSettingsFile(configDir: string, runDir: string): string | undefined;
+export declare const rulesSection: (rules: string) => string;
+export declare function initProfile(configDir: string): string[];
+export declare function profileChecks(configDir: string): Check[];

package/dist/profile.js

@@ -0,0 +1,70 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { agentsDir } from "./config.js";
+// Your profile: what every agent run carries, on any machine, without touching
+// a Claude or Codex folder. RULES.md is added to every step's prompt, and
+// claude-settings.json is passed to Claude runs, with {{profile}} standing for
+// this folder so hooks can live in it.
+export const profileDir = (configDir) => join(agentsDir(configDir), 'profile');
+export const RULES_FILE = 'RULES.md';
+export const CLAUDE_SETTINGS = 'claude-settings.json';
+export function readRules(configDir) {
+    const path = join(profileDir(configDir), RULES_FILE);
+    return existsSync(path) ? readFileSync(path, 'utf8').trim() : '';
+}
+// The Claude settings with {{profile}} filled in, as text, or null when there
+// are none. Throws when the file is not a JSON object.
+export function renderClaudeSettings(configDir) {
+    const dir = profileDir(configDir);
+    const path = join(dir, CLAUDE_SETTINGS);
+    if (!existsSync(path))
+        return null;
+    const text = readFileSync(path, 'utf8').replaceAll('{{profile}}', dir);
+    const value = JSON.parse(text);
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error(`${CLAUDE_SETTINGS} must be a JSON object`);
+    return text;
+}
+// Writes the rendered settings into a run folder and returns the path, or
+// undefined when the profile has none.
+export function claudeSettingsFile(configDir, runDir) {
+    const text = renderClaudeSettings(configDir);
+    if (text === null)
+        return undefined;
+    const out = join(runDir, CLAUDE_SETTINGS);
+    writeFileSync(out, text);
+    return out;
+}
+// The prompt section for your rules, empty when there are none.
+export const rulesSection = (rules) => (rules ? `# Your rules\n\nFollow these in everything you write, including commits and comments.\n\n${rules}` : '');
+const STARTER_RULES = `<!-- Rules every agent follows on every run, on every machine.
+     Write them as you would tell a teammate. Delete this comment. -->
+`;
+// Creates the folder with a starter RULES.md. Existing files are kept.
+export function initProfile(configDir) {
+    const dir = profileDir(configDir);
+    mkdirSync(dir, { recursive: true });
+    const made = [];
+    const rules = join(dir, RULES_FILE);
+    if (!existsSync(rules)) {
+        writeFileSync(rules, STARTER_RULES);
+        made.push(RULES_FILE);
+    }
+    return made;
+}
+export function profileChecks(configDir) {
+    const dir = profileDir(configDir);
+    if (!existsSync(dir))
+        return [];
+    const parts = [];
+    if (readRules(configDir).replace(/<!--[\s\S]*?-->/g, '').trim())
+        parts.push('rules');
+    try {
+        if (renderClaudeSettings(configDir) !== null)
+            parts.push('Claude settings');
+    }
+    catch (err) {
+        return [{ name: 'agent profile', status: 'fail', detail: `${CLAUDE_SETTINGS}: ${err.message}`, fix: `fix ${join(dir, CLAUDE_SETTINGS)}` }];
+    }
+    return [parts.length ? { name: 'agent profile', status: 'ok', detail: parts.join(', ') } : { name: 'agent profile', status: 'warn', detail: 'empty', fix: `add rules to ${join(dir, RULES_FILE)}` }];
+}

package/dist/runner.d.ts

@@ -1,23 +1,30 @@
-import { type AgentsConfig, type Workflow, type Project, type StepId, type Trigger } from './config.ts';
-import type { Card, Linear } from './linear.ts';
+import { type AgentsConfig, type Workflow, type Project, type Trigger } from './config.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[];
 }
 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;
+    from?: string;
 }): 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;
+    from?: string;
 }): Promise<number>;
+export {};