@voidlabs.gg/voidshift-agents 0.4.5 → 0.5.1

package/README.md

@@ -127,9 +127,18 @@ vsf memory status          # the vault and where recall is on
 vsf memory search WORDS    # notes recall would bring up
 vsf memory try "a prompt"  # exactly what recall would add to that prompt
 vsf memory check           # notes missing from INDEX.md, broken links
+vsf memory sync            # pull and push the vault through its git remote
 vsf memory on | off        # turn recall on or off
 ```
 
+To share the vault between machines, make it a git repository with a remote
+named `origin` (any host; a private repository). `vsf memory sync` commits new
+notes, rebases onto the remote and pushes. It also runs in the background from
+the recall hook when the last sync is over ten minutes old, and the agents
+runner syncs before and after every run. When a note changed on both sides,
+the remote's version stays and this machine's copy is saved beside it as
+`note.conflict-<machine>-<time>.md`, so nothing is lost.
+
 Setup creates a vault at `~/memory` or uses one you already have. Codex asks you
 to trust the recall hook once: run `/hooks` in Codex.
 
@@ -180,8 +189,12 @@ pnpm test
 node packages/cli/src/main.ts
 ```
 
-Node 22.18 or newer runs the TypeScript sources directly. Releases are cut by
-pushing a `v*` tag; CI publishes every package at that version.
+Node 22.18 or newer runs the TypeScript sources directly. Each package
+releases on its own: bump its `package.json` and push `agents-v0.5.0` (or
+`cli-v`, `memory-v`, `awake-v`), and CI publishes only that package. A plain
+`v*` tag publishes all four at one version. Tools declare the CLI contract
+they were built for; a CLI that is too old refuses to load them and says to
+run `vsf update`.
 
 ## License
 

package/dist/control.d.ts

@@ -1,5 +1,6 @@
 import { type AgentsConfig, type Tracker as Kind } from './config.ts';
 import { type Current, type RunEntry } from './state.ts';
+import { type Trackers } from './tracker.ts';
 import type { Check, ToolCommand, ToolContext } from './types.ts';
 export { parsePlistArgs } from './launchd.ts';
 export declare const trackersInUse: (config: Pick<AgentsConfig, "workflows">) => Kind[];
@@ -23,5 +24,12 @@ export interface CancelDeps {
     cancelCard: (card: string, label: string, source: Kind) => Promise<boolean>;
 }
 export declare function cancelCurrent(ctx: ToolContext, c: Current, deps: CancelDeps): Promise<void>;
+export declare function trackerWarnings(kinds: Kind[], trackers: Trackers): Promise<{
+    kind: Kind;
+    message: string;
+}[]>;
+export declare function workingLine(current: (Current & {
+    elapsedMinutes: number;
+}) | null): string;
 export declare const controlCommands: Record<string, ToolCommand>;
 export declare function controlChecks(ctx: ToolContext): Promise<Check[]>;

package/dist/control.js

@@ -230,23 +230,30 @@ const realDeps = (ctx) => ({
         }
     },
 });
-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;
-    }
-    const trackers = trackersFor(ctx.configDir);
-    for (const kind of trackersInUse(readAgentsConfig(ctx.configDir))) {
+// One message per tracker whose key is missing or refused. The tick skips a
+// tracker it cannot open, so these warn rather than stop the runner.
+export async function trackerWarnings(kinds, trackers) {
+    const out = [];
+    for (const kind of kinds) {
         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;
+            out.push({ kind, message: /^No .* API key/.test(msg) ? msg : `${TRACKERS[kind].name} did not accept the key: ${msg}. Run vsf agents key${flag}.` });
         }
     }
+    return out;
+}
+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;
+    }
+    for (const w of await trackerWarnings(trackersInUse(readAgentsConfig(ctx.configDir)), trackersFor(ctx.configDir))) {
+        ctx.log(`Warning: ${w.message.replace(/\.?$/, '.')} Workflows on ${TRACKERS[w.kind].name} are skipped until then.`);
+    }
     setPaused(ctx.configDir, false);
     if (!runnerService().start(ctx.home, program(ctx), logPath(ctx.configDir))) {
         ctx.log('Could not start the runner. Check vsf agents logs.');
@@ -263,6 +270,14 @@ async function stopCmd(ctx) {
     ctx.log('Runner stopped.');
     return 0;
 }
+// The lock holds the round as the card's vs-vN label shows it; 0 before any round.
+export function workingLine(current) {
+    if (!current)
+        return '';
+    if (!current.card)
+        return ' Checking now.';
+    return ` Working on ${current.card}${current.title ? ` "${current.title}"` : ''} (${[current.workflow, current.step, current.round ? `round ${current.round}` : '', `${current.elapsedMinutes}m`].filter(Boolean).join(', ')}).`;
+}
 const status = guard(async (args, ctx) => {
     const p = parse('status', args, { json: { type: 'boolean' } }, ctx);
     if (typeof p === 'number')
@@ -291,11 +306,7 @@ const status = guard(async (args, ctx) => {
         ctx.log(JSON.stringify({ engine: config.engine, runner, lastTick, current, parked, interrupted, workflows, projects }, null, 2));
         return 0;
     }
-    const working = current && !current.card
-        ? ' 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(', ')}).`
-            : '';
+    const working = workingLine(current);
     if (runner === 'running')
         ctx.log(`Runner: running.${working}`);
     else if (runner === 'paused')

package/dist/index.js

@@ -1042,6 +1042,7 @@ const homeCommands = {
 const sameModels = (a, b) => a.dev === b.dev && a.review === b.review;
 const agents = {
     name: 'agents',
+    contract: 1,
     summary: 'Agents for Claude Code and Codex that plan, build and QA Linear cards',
     config: {
         read: (dir) => readAgentsConfig(dir),

package/dist/memory.d.ts

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

package/dist/memory.js

@@ -35,3 +35,15 @@ export function recall(selfCommand, configDir, text) {
         return '';
     }
 }
+// Brings the vault up to date through its git remote, or shares the notes
+// agents wrote. Never fails a run: returns a line worth logging, or ''.
+export function syncMemory(selfCommand, configDir) {
+    if (!vaultPath(configDir) || !selfCommand.length)
+        return '';
+    const [cmd, ...args] = selfCommand;
+    const r = spawnSync(cmd, [...args, 'memory', 'sync', '--quiet'], { encoding: 'utf8', timeout: 90_000 });
+    const out = `${r.stdout ?? ''}${r.stderr ?? ''}`.trim();
+    if (r.error)
+        return `memory sync did not run (${r.error.message})`;
+    return r.status === 0 ? out : out || 'memory sync failed';
+}

package/dist/runner.js

@@ -1,12 +1,12 @@
 import { existsSync, mkdirSync } from 'node:fs';
 import { basename, join } from 'node:path';
-import { LABELS, PLAN_HEADING, buildPrompt, findingsFor, fixTarget, isStatusLabel, latestPlan, parseDevResult, parseVerdict, planBody, qaPassed, stageLabels, verdictBlock, } from "./workflow.js";
+import { LABELS, PLAN_HEADING, buildPrompt, findingsFor, fixTarget, isStatusLabel, latestPlan, needsPlan, parseDevResult, parseVerdict, planBody, qaPassed, stageLabels, verdictBlock, } from "./workflow.js";
 import { agentsDir, hasWork, isCardTrigger, resolveStep, stepId, stepIdLabel } from "./config.js";
 import { lastDue, parseCron } from "./cron.js";
 import { runAgent, stopAgents } from "./engine.js";
 import { commitsAhead, enforceCommitPolicy, defaultBranch, ensureDraftPr, ensureWorktree, headSha, markReady, push, resetWorktree, waitForChecks, waitForPrHead } from "./git.js";
 import { noTracker } from "./tracker.js";
-import { recall, vaultPath } from "./memory.js";
+import { recall, syncMemory, vaultPath } from "./memory.js";
 import { claudeSettingsFile, readRules, rulesSection } from "./profile.js";
 import { bootTime, clearCurrent, isPaused, ours, readCurrent, readPending, writeCurrent, writePending, writeRun, readCronState, writeCronState } from "./state.js";
 const stamp = () => new Date().toISOString().replace(/[:.]/g, '-');
@@ -138,10 +138,7 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
             throw new Park(`Workflow ${workflowName} has no ${stepIdLabel(opts.from)} step.`);
         // 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.findIndex((d, n) => n >= from && d.output === 'plan');
-        // A check before any commits is a check on the plan, like Plan review.
-        const needsPlan = steps.findIndex((d, n) => n >= from && (d.output === 'commits' || (d.output === 'verdict' && d.builtin !== 'vs-qa')));
-        if (!plan && needsPlan >= 0 && (firstPlan < 0 || firstPlan > needsPlan)) {
+        if (!plan && needsPlan(steps, from)) {
             throw new Park('No plan comment (starting with "## Plan") was found. Publish a plan first, or start the workflow with Plan.');
         }
         await stage(stageOf(steps[from]));
@@ -156,6 +153,10 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
             throw new Park(`Your agent profile's Claude settings are broken: ${err.message}`);
         }
         const rules = rulesSection(readRules(rc.configDir));
+        // Latest notes from every machine before recall reads them.
+        const pulled = syncMemory(rc.selfCommand, rc.configDir);
+        if (pulled)
+            say(pulled);
         const known = [recall(rc.selfCommand, rc.configDir, `${workflow.project} ${card.title}\n${card.description ?? ''}`), vault ? memoryNote(vault) : '', rules].filter(Boolean).join('\n\n');
         const worktree = join(agentsDir(rc.configDir), 'worktrees', card.identifier);
         ensureWorktree(project.path, worktree, card.branchName, base);
@@ -336,6 +337,10 @@ export async function runCard(card, trigger, workflowName, workflow, project, rc
     }
     finally {
         active = null;
+        // Share whatever notes the agents wrote, whatever the outcome.
+        const shared = syncMemory(rc.selfCommand, rc.configDir);
+        if (shared)
+            say(shared);
     }
 }
 // A scheduled run's stand-in for a card: the task, on a branch of its own.

package/dist/types.d.ts

@@ -40,6 +40,7 @@ export type ToolCommand = (args: string[], ctx: ToolContext) => Promise<number>;
 export interface Tool {
     name: string;
     summary: string;
+    contract?: number;
     install(ctx: ToolContext): Promise<void>;
     uninstall(ctx: ToolContext): Promise<void>;
     checks(ctx: ToolContext): Promise<Check[]>;

package/dist/workflow.d.ts

@@ -49,4 +49,8 @@ export interface PromptInput {
 export declare function buildPrompt(p: PromptInput): string;
 export declare function verdictBlock<T>(steps: T[], i: number, isVerdict: (s: T) => boolean): [number, number];
 export declare function fixTarget<T>(steps: T[], blockStart: number, isProducer: (s: T) => boolean): number;
+export declare function needsPlan(steps: {
+    output: string;
+    builtin?: string;
+}[], from: number): boolean;
 export declare function planBody(output: string): string;

package/dist/workflow.js

@@ -105,6 +105,21 @@ export function fixTarget(steps, blockStart, isProducer) {
             return j;
     return -1;
 }
+// Whether a run starting at `from` needs a plan comment: some step before any
+// Plan step writes commits or checks the plan. A check counts as a plan check
+// only when a Plan step comes before it, so a review-only workflow runs bare.
+export function needsPlan(steps, from) {
+    for (let n = from; n < steps.length; n++) {
+        const s = steps[n];
+        if (s.output === 'plan')
+            return false;
+        if (s.output === 'commits')
+            return true;
+        if (s.output === 'verdict' && s.builtin !== 'vs-qa' && (s.builtin === 'vs-plan-review' || steps.slice(0, n).some((d) => d.output === 'plan')))
+            return true;
+    }
+    return false;
+}
 // Plan output minus the trailing RESULT line, ready to post.
 export function planBody(output) {
     return output.replace(/^\s*RESULT:.*$/gim, '').trim();

package/pack/vs-plan/SKILL.md

@@ -94,7 +94,9 @@ The plan file holds the detail. In the chat, keep it short and plain:
 Start straight at Understanding. Do not repeat the card id or title; the card
 already shows them.
 
-Length follows the change: under 350 words for a small one, never padded.
+Outcome first. Under 350 words for a small change, never over 700 for any
+change. File and line detail only in Surfaces; no code blocks over 5 lines;
+Six angles lists only angles that apply.
 
 **Understanding.** Two to four sentences: what the card asks, what it got
 wrong, which reading you chose.
@@ -123,6 +125,7 @@ anything a human must click.
 - No ticket ids in code comments.
 - No em dashes or en dashes.
 - No narration of process. State findings.
+- Do not quote code the dev agent can read.
 
 ## When you run inside a workflow
 

package/pack/vs-plan-review/SKILL.md

@@ -41,7 +41,8 @@ main points.
 2. The findings that change what gets built, most important first, at most 5,
    one short plain line each: what is wrong and what to do about it.
 3. Everything smaller in one line: `Minor: ...`.
-4. A short `Details` section: for each finding, the file and line that proves it.
+4. A short `Details` section: one line per finding, the file and line that
+   proves it.
 5. Last line, exactly one of:
 
 ```
@@ -56,6 +57,7 @@ fixes to the plan file.
 
 - No em dashes or en dashes.
 - No narration of process. State findings.
+- Whole review under 300 words.
 
 ## When you run inside a workflow
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voidlabs.gg/voidshift-agents",
-  "version": "0.4.5",
+  "version": "0.5.1",
   "description": "Agents for Claude Code and Codex that plan, build and QA Linear cards, chained and run in the background.",
   "license": "Apache-2.0",
   "repository": {
@@ -40,7 +40,7 @@
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "node --test test/*.test.ts",
+    "test": "node --test --test-force-exit --test-timeout=60000 test/*.test.ts",
     "prepublishOnly": "rm -rf dist && tsc -p tsconfig.json"
   },
   "devDependencies": {