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

package/dist/keychain.d.ts

@@ -0,0 +1,3 @@
+export declare function readLinearKey(): string | null;
+export declare const looksLikeLinearKey: (key: string) => boolean;
+export declare function storeLinearKey(key: string): boolean;

package/dist/keychain.js

@@ -0,0 +1,19 @@
+import { spawnSync } from 'node:child_process';
+import { userInfo } from 'node:os';
+const SERVICE = 'voidshift-linear';
+const KEY_SHAPE = /^lin_api_[A-Za-z0-9]+$/;
+export function readLinearKey() {
+    const r = spawnSync('/usr/bin/security', ['find-generic-password', '-s', SERVICE, '-w'], { encoding: 'utf8' });
+    const key = r.status === 0 ? r.stdout.trim() : '';
+    return key || null;
+}
+export const looksLikeLinearKey = (key) => KEY_SHAPE.test(key);
+// Stores the key through `security -i` on stdin, so it never appears in a
+// process list. The shape check above rules out anything that could break
+// out of the command line.
+export function storeLinearKey(key) {
+    if (!looksLikeLinearKey(key))
+        return false;
+    const command = `add-generic-password -U -s ${SERVICE} -a ${userInfo().username} -w ${key}\n`;
+    return spawnSync('/usr/bin/security', ['-i'], { input: command, encoding: 'utf8' }).status === 0;
+}

package/dist/launchd.d.ts

@@ -0,0 +1,7 @@
+export declare const LABEL = "org.devvoid.voidshift.agents";
+export declare function plistPath(home: string): string;
+export declare function runnerPlist(program: string[], env: Record<string, string>, logPath: string): string;
+export declare function runnerEnv(): Record<string, string>;
+export declare const runnerLoaded: () => boolean;
+export declare function startRunner(home: string, program: string[], logPath: string): boolean;
+export declare function stopRunner(home: string): void;

package/dist/launchd.js

@@ -0,0 +1,68 @@
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { userInfo } from 'node:os';
+import { dirname, join } from 'node:path';
+export const LABEL = 'org.devvoid.voidshift.agents';
+const xml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+const domain = () => `gui/${userInfo().uid}`;
+const launchctl = (args) => spawnSync('/bin/launchctl', args, { encoding: 'utf8' }).status === 0;
+export function plistPath(home) {
+    return join(home, 'Library', 'LaunchAgents', `${LABEL}.plist`);
+}
+// launchd starts jobs with a bare environment, so carry over what the agent
+// CLIs need to find themselves and their logins.
+export function runnerPlist(program, env, logPath) {
+    const args = program.map((a) => `    <string>${xml(a)}</string>`).join('\n');
+    const vars = Object.entries(env)
+        .map(([k, v]) => `    <key>${xml(k)}</key>\n    <string>${xml(v)}</string>`)
+        .join('\n');
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+${args}
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+${vars}
+  </dict>
+  <key>StartInterval</key>
+  <integer>60</integer>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${xml(logPath)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xml(logPath)}</string>
+</dict>
+</plist>
+`;
+}
+export function runnerEnv() {
+    const env = {};
+    for (const k of ['PATH', 'HOME', 'CLAUDE_CONFIG_DIR', 'CODEX_HOME', 'VOIDSHIFT_HOME']) {
+        const v = process.env[k];
+        if (v)
+            env[k] = v;
+    }
+    return env;
+}
+export const runnerLoaded = () => launchctl(['print', `${domain()}/${LABEL}`]);
+export function startRunner(home, program, logPath) {
+    const path = plistPath(home);
+    mkdirSync(dirname(path), { recursive: true });
+    mkdirSync(dirname(logPath), { recursive: true });
+    writeFileSync(path, runnerPlist(program, runnerEnv(), logPath));
+    if (runnerLoaded())
+        launchctl(['bootout', `${domain()}/${LABEL}`]);
+    return launchctl(['bootstrap', domain(), path]);
+}
+export function stopRunner(home) {
+    if (runnerLoaded())
+        launchctl(['bootout', `${domain()}/${LABEL}`]);
+    rmSync(plistPath(home), { force: true });
+}

package/dist/linear.d.ts

@@ -0,0 +1,33 @@
+export interface Card {
+    id: string;
+    identifier: string;
+    title: string;
+    description?: string;
+    url: string;
+    branchName: string;
+    teamId: string;
+    teamKey: string;
+    projectName?: string;
+    labels: string[];
+}
+export declare function createLinear(apiKey: string): {
+    viewer(): Promise<{
+        id: string;
+        name: string;
+    }>;
+    teams(): Promise<{
+        key: string;
+        name: string;
+        mine: boolean;
+    }[]>;
+    myCardsWithLabel(label: 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 type Linear = ReturnType<typeof createLinear>;

package/dist/linear.js

@@ -0,0 +1,122 @@
+// Linear over GraphQL with a personal API key (sent raw, no Bearer prefix).
+// Only the background runner uses this; interactive agents use the Linear
+// connection inside Claude Code or Codex.
+const ENDPOINT = 'https://api.linear.app/graphql';
+const CARD_FIELDS = `
+  id identifier title description url branchName
+  team { id key }
+  project { name }
+  labels { nodes { name } }
+`;
+function mapCard(n) {
+    return {
+        id: n.id,
+        identifier: n.identifier,
+        title: n.title,
+        description: n.description ?? undefined,
+        url: n.url,
+        branchName: n.branchName,
+        teamId: n.team.id,
+        teamKey: n.team.key,
+        projectName: n.project?.name ?? undefined,
+        labels: (n.labels?.nodes ?? []).map((l) => l.name),
+    };
+}
+export function createLinear(apiKey) {
+    async function gql(operation, query, variables = {}) {
+        let res;
+        try {
+            res = await fetch(ENDPOINT, {
+                method: 'POST',
+                signal: AbortSignal.timeout(30_000),
+                headers: { Authorization: apiKey, 'Content-Type': 'application/json' },
+                body: JSON.stringify({ query, variables }),
+            });
+        }
+        catch (err) {
+            const cause = err.cause;
+            throw new Error(`could not reach Linear (${cause?.code ?? cause?.message ?? err.message})`);
+        }
+        const text = await res.text();
+        let json = null;
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            // reported below
+        }
+        const error = json?.errors?.[0]?.message;
+        if (!res.ok || error || !json)
+            throw new Error(`linear ${operation} ${res.status}: ${error ?? text.slice(0, 200)}`);
+        return json.data;
+    }
+    async function labelId(name, teamId) {
+        const found = await gql('findLabel', `query FindLabel($name: String!, $teamId: ID) {
+        issueLabels(filter: { name: { eq: $name }, or: [{ team: { id: { eq: $teamId } } }, { team: { null: true } }] }) {
+          nodes { id name }
+        }
+      }`, { name, teamId });
+        const existing = (found?.issueLabels?.nodes ?? []).find((l) => l.name === name);
+        if (existing)
+            return existing.id;
+        const created = await gql('createLabel', `mutation CreateLabel($name: String!, $teamId: String) {
+        issueLabelCreate(input: { name: $name, teamId: $teamId }) { issueLabel { id } }
+      }`, { name, teamId });
+        const id = created?.issueLabelCreate?.issueLabel?.id;
+        if (!id)
+            throw new Error(`linear could not create label ${name}`);
+        return id;
+    }
+    return {
+        async viewer() {
+            const d = await gql('viewer', 'query { viewer { id name } }');
+            return d.viewer;
+        },
+        // Every team, with whether I am a member, members first.
+        async teams() {
+            const d = await gql('teams', 'query { teams(first: 100) { nodes { key name } } viewer { teams(first: 100) { nodes { key } } } }');
+            const mine = new Set((d?.viewer?.teams?.nodes ?? []).map((t) => t.key));
+            const all = d?.teams?.nodes ?? [];
+            return all.map((t) => ({ ...t, mine: mine.has(t.key) })).sort((a, b) => Number(b.mine) - Number(a.mine));
+        },
+        // My cards carrying the trigger label.
+        async myCardsWithLabel(label) {
+            const d = await gql('myCards', `query MyCards($label: String!) {
+          issues(first: 20, orderBy: createdAt, filter: { assignee: { isMe: { eq: true } }, labels: { name: { eq: $label } } }) {
+            nodes { ${CARD_FIELDS} }
+          }
+        }`, { label });
+            return (d?.issues?.nodes ?? []).map(mapCard);
+        },
+        async card(identifier) {
+            const d = await gql('card', `query Card($id: String!) { issue(id: $id) { ${CARD_FIELDS} } }`, { id: identifier });
+            if (!d?.issue)
+                throw new Error(`linear has no card ${identifier}`);
+            return mapCard(d.issue);
+        },
+        async comments(identifier) {
+            const d = await gql('comments', `query Comments($id: String!) { issue(id: $id) { comments(first: 100) { nodes { body createdAt } } } }`, { id: identifier });
+            return d?.issue?.comments?.nodes ?? [];
+        },
+        async comment(card, body) {
+            await gql('comment', `mutation Comment($issueId: String!, $body: String!) { commentCreate(input: { issueId: $issueId, body: $body }) { success } }`, { issueId: card.id, body });
+        },
+        // Replace the card's label set with `next`, creating labels as needed.
+        async setLabels(card, next) {
+            const ids = [];
+            for (const name of next)
+                ids.push(await labelId(name, card.teamId));
+            await gql('setLabels', `mutation SetLabels($id: String!, $labelIds: [String!]) { issueUpdate(id: $id, input: { labelIds: $labelIds }) { success } }`, { id: card.id, labelIds: ids });
+            card.labels = next;
+        },
+        // Move to a named workflow state; false if the team has no such state.
+        async moveTo(card, stateName) {
+            const d = await gql('states', `query States($teamId: ID!) { workflowStates(filter: { team: { id: { eq: $teamId } } }) { nodes { id name } } }`, { teamId: card.teamId });
+            const state = (d?.workflowStates?.nodes ?? []).find((s) => s.name.toLowerCase() === stateName.toLowerCase());
+            if (!state)
+                return false;
+            await gql('move', `mutation Move($id: String!, $stateId: String!) { issueUpdate(id: $id, input: { stateId: $stateId }) { success } }`, { id: card.id, stateId: state.id });
+            return true;
+        },
+    };
+}

package/dist/manage.d.ts

@@ -0,0 +1,18 @@
+import { type AgentsConfig, type Trigger, type Workflow } from './config.ts';
+export declare function validateWorkflow(config: Pick<AgentsConfig, 'enabled' | 'projects'>, workflow: Workflow): string[];
+export declare function parseTrigger(input: string): Trigger | null;
+export declare const sameTrigger: (a: Trigger, b: Trigger) => boolean;
+export declare function duplicateTriggerWarnings(workflows: Record<string, Workflow>, name: string, workflow: Workflow): string[];
+export declare function renameKey<T>(record: Record<string, T>, from: string, to: string): Record<string, T>;
+export type Place = {
+    first: true;
+} | {
+    last: true;
+} | {
+    before: string;
+} | {
+    after: string;
+};
+export declare function moveKey<T>(record: Record<string, T>, name: string, place: Place): Record<string, T>;
+export declare const workflowsUsing: (config: Pick<AgentsConfig, "workflows">, project: string) => string[];
+export declare function validateConfig(value: unknown, saved?: Pick<AgentsConfig, 'projects' | 'workflows'>): string[];

package/dist/manage.js

@@ -0,0 +1,120 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { AGENTS, STEPS } from "./config.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) {
+    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 (!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.`);
+    }
+    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.');
+    return problems;
+}
+// "ENG:vs-plan" into a trigger; the team is upper-cased.
+export function parseTrigger(input) {
+    const i = input.indexOf(':');
+    if (i < 0)
+        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;
+}
+export const sameTrigger = (a, b) => a.team === b.team && a.label === b.label;
+// 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) {
+    const lines = [];
+    for (const t of workflow.triggers) {
+        const owners = Object.entries(workflows).filter(([n, w]) => n === name || w.triggers.some((x) => sameTrigger(x, t))).map(([n]) => n);
+        const first = owners[0];
+        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.`);
+        }
+    }
+    return lines;
+}
+// Renames a key without moving it.
+export function renameKey(record, from, to) {
+    return Object.fromEntries(Object.entries(record).map(([k, v]) => [k === from ? to : k, v]));
+}
+// Moves one entry to a new place in the order.
+export function moveKey(record, name, place) {
+    const rest = Object.keys(record).filter((k) => k !== name);
+    let at = 0;
+    if ('last' in place)
+        at = rest.length;
+    else if ('before' in place)
+        at = rest.indexOf(place.before);
+    else if ('after' in place)
+        at = rest.indexOf(place.after) + 1;
+    if (at < 0 || (at === 0 && 'after' in place))
+        return record;
+    rest.splice(at, 0, name);
+    return Object.fromEntries(rest.map((k) => [k, record[k]]));
+}
+export const workflowsUsing = (config, project) => Object.entries(config.workflows).filter(([, w]) => w.project === project).map(([n]) => n);
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+// Everything wrong with a whole agents config, e.g. one edited by hand.
+// `saved` is the config on disk: only what the write changes is checked, so a
+// moved folder or a retired agent elsewhere does not block an unrelated edit.
+export function validateConfig(value, saved) {
+    if (!isObj(value))
+        return ['The config must be an object.'];
+    const problems = [];
+    if (value.engine !== 'claude' && value.engine !== 'codex')
+        problems.push('engine must be claude or codex.');
+    if (!isObj(value.models) || Object.values(value.models).some((m) => typeof m !== 'string'))
+        problems.push('models must map names to text.');
+    if (typeof value.reviewState !== 'string' || !value.reviewState.trim())
+        problems.push('reviewState must be a non-empty string.');
+    if (!isInt(value.timeoutMinutes, 1, 480))
+        problems.push('timeoutMinutes must be a whole number from 1 to 480.');
+    const projects = isObj(value.projects) ? value.projects : null;
+    if (!projects)
+        problems.push('projects must be an object.');
+    for (const [name, p] of Object.entries(projects ?? {})) {
+        if (!isObj(p) || typeof p.path !== 'string' || !p.path)
+            problems.push(`Project ${name} needs a path.`);
+        else if (saved?.projects?.[name]?.path !== p.path && !existsSync(join(p.path, '.git')))
+            problems.push(`Project ${name}: ${p.path} is not a git repository.`);
+    }
+    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 (!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))
+        problems.push('workflows must be an object.');
+    else {
+        const ctx = { enabled: Array.isArray(value.enabled) ? value.enabled : [], projects: (projects ?? {}) };
+        for (const [name, w] of Object.entries(value.workflows)) {
+            if (!isObj(w))
+                problems.push(`Workflow ${name} must be an object.`);
+            else {
+                // An unchanged workflow using a step that is not enabled is only a warning.
+                const unchanged = !!saved?.workflows?.[name] && JSON.stringify(saved.workflows[name]) === JSON.stringify(w);
+                for (const p of validateWorkflow(unchanged ? { ...ctx, enabled: [] } : ctx, w))
+                    problems.push(`Workflow ${name}: ${p}`);
+            }
+        }
+    }
+    return problems;
+}

package/dist/memory.d.ts

@@ -0,0 +1,2 @@
+export declare function vaultPath(configDir: string): string | undefined;
+export declare function recall(selfCommand: string[], configDir: string, text: string): string;

package/dist/memory.js

@@ -0,0 +1,37 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+// The memory tool's vault, when it is set up. Agents read it through
+// `voidshift memory recall` and write notes into it directly.
+export function vaultPath(configDir) {
+    const path = join(configDir, 'memory', 'config.json');
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const vault = JSON.parse(readFileSync(path, 'utf8')).vault;
+        return vault && existsSync(join(vault, 'INDEX.md')) ? vault : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// Notes matching the text, recalled the same way as before each of your
+// prompts. Empty when memory is not set up or nothing matches.
+export function recall(selfCommand, configDir, text) {
+    if (!vaultPath(configDir) || !selfCommand.length)
+        return '';
+    const [cmd, ...args] = selfCommand;
+    const r = spawnSync(cmd, [...args, 'memory', 'recall'], {
+        input: JSON.stringify({ prompt: text, session_id: `agents-${Date.now()}` }),
+        encoding: 'utf8',
+        timeout: 10_000,
+    });
+    if (r.status !== 0 || !r.stdout.trim())
+        return '';
+    try {
+        return JSON.parse(r.stdout).hookSpecificOutput?.additionalContext ?? '';
+    }
+    catch {
+        return '';
+    }
+}

package/dist/names.d.ts

@@ -0,0 +1,8 @@
+import { type StepId } from './config.ts';
+export declare function resolveName(names: string[], input: string, kind: string): {
+    name: string;
+} | {
+    error: string;
+};
+export declare function parseStep(input: string): StepId | null;
+export declare const stepNames: () => string;

package/dist/names.js

@@ -0,0 +1,26 @@
+import { STEPS } 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) {
+    if (!input.trim())
+        return { error: `Give a ${kind} name.` };
+    if (names.includes(input))
+        return { name: input };
+    const matches = names.filter((n) => n.startsWith(input));
+    if (matches.length === 1)
+        return { name: matches[0] };
+    if (!matches.length)
+        return { error: `No ${kind} named ${input}.${names.length ? ` There are: ${names.join(', ')}.` : ''}` };
+    return { error: `${input} matches ${matches.join(', ')}. Type more of the name.` };
+}
+// Short step names for commands: plan, plan-review, publish, dev, qa. The
+// full ids (vs-dev) and labels (Dev, "Plan review") work too.
+export function parseStep(input) {
+    const v = input.trim().toLowerCase().replace(/\s+/g, '-');
+    for (const id of Object.keys(STEPS)) {
+        if (v === id || `vs-${v}` === id || STEPS[id].label.toLowerCase().replace(/\s+/g, '-') === v)
+            return id;
+    }
+    return null;
+}
+export const stepNames = () => Object.keys(STEPS).map((id) => id.replace(/^vs-/, '')).join(', ');

package/dist/repos.d.ts

@@ -0,0 +1 @@
+export declare function findRepos(extraRoots?: string[], maxDepth?: number, limit?: number): string[];

package/dist/repos.js

@@ -0,0 +1,45 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const ROOTS = ['me', 'code', 'Code', 'projects', 'Projects', 'dev', 'Developer', 'src', 'work', 'repos', 'git', 'GitHub', 'Documents/GitHub'];
+const SKIP = new Set(['node_modules', 'Library', 'Applications', 'dist', 'build', 'vendor', 'target']);
+// Git repos under the usual code folders, a few levels deep. A folder with a
+// .git directory is a repo and is not searched further; worktrees (a .git
+// file) are left out so each repo shows once.
+export function findRepos(extraRoots = [], maxDepth = 4, limit = 400) {
+    const found = new Set();
+    const roots = [...extraRoots, ...ROOTS.map((r) => join(homedir(), r))].filter((r) => existsSync(r));
+    const walk = (dir, depth) => {
+        if (found.size >= limit)
+            return;
+        const git = join(dir, '.git');
+        if (existsSync(git) && statSync(git).isDirectory()) {
+            found.add(dir);
+            return;
+        }
+        if (depth >= maxDepth)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const name of entries) {
+            if (name.startsWith('.') || SKIP.has(name))
+                continue;
+            const full = join(dir, name);
+            try {
+                if (statSync(full).isDirectory())
+                    walk(full, depth + 1);
+            }
+            catch {
+                // unreadable, skip
+            }
+        }
+    };
+    for (const root of roots)
+        walk(root, 0);
+    return [...found].sort((a, b) => a.localeCompare(b));
+}

package/dist/runner.d.ts

@@ -0,0 +1,23 @@
+import { type AgentsConfig, type Workflow, type Project, type StepId, type Trigger } from './config.ts';
+import type { Card, Linear } from './linear.ts';
+export interface RunContext {
+    configDir: string;
+    config: AgentsConfig;
+    linear: Linear;
+    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;
+}): Promise<'verified' | 'changes' | 'parked'>;
+export declare function nextJob(rc: RunContext, only?: string, workflowName?: string): Promise<{
+    card: Card;
+    trigger: Trigger;
+    workflow: string;
+} | null>;
+export declare function cancelCard(linear: Linear, configDir: string, cardId: string, label: string): Promise<boolean>;
+export declare function tick(rc: RunContext, only?: string, opts?: {
+    workflow?: string;
+    from?: StepId;
+}): Promise<number>;