@voidlabs.gg/voidshift 0.4.4 → 0.4.6

package/README.md

@@ -86,8 +86,33 @@ vsf agents workflow add|edit|show|rename|move|rm
 vsf agents projects | project add|edit|show|rename|rm
 vsf agents homes | link DIR        # where the agents are installed
 vsf agents clean                   # old worktrees and run logs
+vsf agents validate [DIR]          # check the config and agent folders
 ```
 
+A workflow can also be a folder you write by hand,
+`~/.config/voidshift/agents/defs/NAME/agent.json`, with its prompt files next to
+it. Steps are the built-in ids above or your own:
+
+```json
+{
+  "triggers": [{ "source": "cron", "schedule": "0 7 * * 1-5", "task": "Morning brief" }],
+  "steps": [{ "id": "brief", "prompt": "brief.md", "output": "none", "model": "haiku", "timeoutMinutes": 10 }],
+  "maxRounds": 1,
+  "project": "tether-relay",
+  "writeBack": { "labels": true, "state": null, "comment": true }
+}
+```
+
+A step's `output` is `plan`, `verdict`, `commits`, `publish` or `none`; a failed
+`verdict` sends the work back to the nearest `plan` or `commits` step. `engine`,
+`model` and `timeoutMinutes` fall back to the config, and `write` to true only
+for `commits`. A `publish` step takes no prompt; the others take one `prompt`
+file or `skill`, which must ask for a `RESULT:` line (`plan`, `commits`) or a
+`VERDICT:` line (`verdict`). `writeBack` applies to card runs: `state` moves a
+verified card there (`null` never moves it), `labels: false` only takes the
+trigger label off, and `comment: false` skips the closing comment. Edit the file,
+then `vsf agents validate`.
+
 ### memory
 
 A folder of markdown notes, one topic per note, with an `INDEX.md` holding one
@@ -102,12 +127,35 @@ 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.
 
+### Your profile
+
+Every agent run carries your profile, on any machine, without touching your
+Claude or Codex folder. `vsf agents profile init` creates
+`~/.config/voidshift/agents/profile/`:
+
+- `RULES.md` is added to every step's prompt (style, commit rules, tone).
+- `claude-settings.json` is passed to Claude runs with `--settings`, so hooks
+  come along. `{{profile}}` stands for the folder, so hook scripts can live in it.
+
+Setup also asks what the runner does to agent commits before it pushes them:
+remove AI co-author lines, and add `Signed-off-by` for repos that ask for a
+DCO. Only the new commits of that step are rewritten, never pushed ones.
+
 ## What to know
 
 - **Your own logins.** Agents run the official `claude` and `codex` CLIs you
@@ -141,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/loader.d.ts

@@ -1,5 +1,5 @@
 import type { ToolEntry } from './registry.ts';
-import type { Tool } from './tool.ts';
+import { type Tool } from './tool.ts';
 export declare function locate(entry: ToolEntry, configDir: string): string | null;
 export declare function npm(args: string[]): boolean;
 export declare function fetchTool(entry: ToolEntry, configDir: string): boolean;

package/dist/loader.js

@@ -10,6 +10,7 @@ import { spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { CONTRACT } from "./tool.js";
 // Inside the monorepo, tools load straight from source. Installed copies
 // live under <configDir>/tools, one npm prefix shared by every tool.
 function sourcePath(entry) {
@@ -47,5 +48,8 @@ export async function loadTool(entry, configDir) {
     if (!path)
         throw new Error(`could not download ${entry.pkg}. Check your connection and run vsf setup again.`);
     const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(path).href)));
+    const contract = mod.default.contract ?? 1;
+    if (contract > CONTRACT)
+        throw new Error(`${entry.name} needs a newer vsf (it uses tool contract ${contract}, this vsf knows ${CONTRACT}). Run vsf update.`);
     return mod.default;
 }

package/dist/tool.d.ts

@@ -37,9 +37,11 @@ export interface ToolContext {
     ui: Ui;
 }
 export type ToolCommand = (args: string[], ctx: ToolContext) => Promise<number>;
+export declare const CONTRACT = 1;
 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/tool.js

@@ -1,4 +1,6 @@
 // The contract every voidshift tool implements. The CLI owns discovery,
 // install and reporting; a tool only knows how to set itself up, take
 // itself down, say whether it is healthy, and run its own subcommands.
-export {};
+// The version of this contract. A tool built for a newer one may call things
+// this CLI does not have, so it is not loaded; tools without the field are 1.
+export const CONTRACT = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voidlabs.gg/voidshift",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "One CLI for the Void dev tools: keep your Mac awake, run agents in the background, shared skills and memory for Claude Code and Codex.",
   "license": "Apache-2.0",
   "repository": {