Open source AI Employees. 8 scheduled business roles, 60 routines, on Claude Code and 10 other harnesses. They drive your browser the way you do and improve every run. You own the files.
JavaScript ai-agentsai-employeeai-employeesantigravityautomationclaude-codeclaude-skillcodexhermes-agentopenclawopencodescheduled-taskssmall-business
#!/usr/bin/env node
// Shared source. Copied into each kit so installed employees have no runtime dependency.
import fs from 'node:fs';
import path from 'node:path';
import crypto from 'node:crypto';
import assert from 'node:assert/strict';
import os from 'node:os';
import { fileURLToPath, pathToFileURL } from 'node:url';
const text = (x) => typeof x === 'string' && x.trim().length > 0;
const stamp = (x) => text(x) && !Number.isNaN(Date.parse(x));
function requireValue(test, message) { if (!test) throw new Error(message); }
export function inside(root, rel) {
requireValue(text(rel) && !path.isAbsolute(rel) && !rel.includes('\\') && !rel.split('/').includes('..'), 'Use a relative path inside the employee');
const resolved = path.resolve(root, rel), base = fs.realpathSync(root);
requireValue(resolved.startsWith(path.resolve(root) + path.sep), 'Path escapes employee');
let parent = resolved;
while (!fs.existsSync(parent)) parent = path.dirname(parent);
const real = fs.realpathSync(parent);
requireValue(real === base || real.startsWith(base + path.sep), 'Linked path escapes employee');
return resolved;
}
export function loadRows(file) {
if (!fs.existsSync(file)) return [];
return fs.readFileSync(file, 'utf8').replace(/^\uFEFF/, '').split(/\r?\n/).filter(x => x.trim()).map((x, i) => {
try { return JSON.parse(x); } catch { throw new Error(`Malformed ledger line ${i + 1}; preserve it and report the gap`); }
});
}
export function chooseWork(candidates) {
// Candidates come from the owning routine's existing queue; this never grants authority.
return candidates.filter(c => c.owned === true && c.fresh === true && c.authorized === true && c.inputs_ready === true)
.sort((a, b) => Number(b.prevents_loss === true) - Number(a.prevents_loss === true)
|| Number(b.fulfills_commitment === true) - Number(a.fulfills_commitment === true)
|| Number(b.unblocks_work === true) - Number(a.unblocks_work === true)
|| (b.value ?? 0) - (a.value ?? 0) || (a.effort ?? 0) - (b.effort ?? 0))[0] ?? null;
}
export function validateExperiment(x) {
requireValue(x.schema === 1, 'Experiment schema must be 1');
for (const k of ['id', 'owner', 'hypothesis', 'source', 'baseline', 'change', 'primary_metric', 'guardrail', 'review_when', 'decision_rule', 'authority']) requireValue(text(x[k]), `Experiment needs ${k}`);
requireValue(['prepared', 'running', 'unmeasured', 'inconclusive', 'improved', 'no-improvement', 'worse', 'retired'].includes(x.status), 'Invalid experiment status');
requireValue(['controlled', 'directional'].includes(x.design), 'Declare controlled or directional design');
if (x.design === 'controlled') requireValue(text(x.assignment) && text(x.contamination_check), 'Controlled tests need assignment and contamination checks');
if (['improved', 'no-improvement', 'worse'].includes(x.status)) requireValue(x.measurement_ready === true && x.sufficient_evidence === true && text(x.result_evidence), 'Measured conclusions need sufficient evidence');
if (x.status === 'running') requireValue(text(x.launch_receipt), 'Running needs an observed launch receipt');
return x;
}
export function validateHandoff(x) {
requireValue(x.schema === 1, 'Handoff schema must be 1');
for (const k of ['id', 'from', 'to', 'source', 'requested_deliverable', 'acceptance', 'expires_on', 'status']) requireValue(text(x[k]), `Handoff needs ${k}`);
requireValue(stamp(x.expires_on), 'Handoff needs an expiry date');
requireValue(['proposed', 'accepted', 'declined', 'completed', 'expired'].includes(x.status), 'Invalid handoff status');
if (x.status === 'completed') requireValue(text(x.receipt), 'Completed handoff needs a receipt');
return x;
}
export function checkExperimentCapacity(root, experiment) {
validateExperiment(experiment);
const schedule = fs.readFileSync(path.join(root, 'SCHEDULE.md'), 'utf8');
const cap = Number(/active_experiments:\s*(\d+)/.exec(schedule)?.[1]);
requireValue(Number.isInteger(cap) && cap > 0, 'SCHEDULE.md needs active_experiments');
const active = new Set(), base = inside(root, 'experiments');
if (fs.existsSync(base)) for (const owner of fs.readdirSync(base)) {
const dir = inside(root, `experiments/${owner}`);
if (!fs.statSync(dir).isDirectory()) continue;
for (const file of fs.readdirSync(dir).filter(f => f.endsWith('.json'))) {
const row = validateExperiment(JSON.parse(fs.readFileSync(inside(root, `experiments/${owner}/${file}`), 'utf8')));
if (['prepared', 'running'].includes(row.status)) active.add(`${row.owner}/${row.id}`);
}
}
const key = `${experiment.owner}/${experiment.id}`;
if (['prepared', 'running'].includes(experiment.status)) active.add(key); else active.delete(key);
requireValue(active.size <= cap, 'Active experiment limit reached; finish or retire existing work first');
return { active: active.size, cap };
}
export function handoffInbox(root, routine, now = Date.now()) {
const profile = JSON.parse(fs.readFileSync(path.join(root, 'work-profile.json'), 'utf8'));
requireValue(Object.hasOwn(profile.routines, routine), 'Unknown receiving routine');
const configPath = inside(root, 'handoffs/routes.json');
if (!fs.existsSync(configPath)) return { configured: false, items: [] };
const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
requireValue(config.schema === 1 && Array.isArray(config.routes), 'Invalid member route configuration');
const items = [], seen = new Set();
for (const route of config.routes.filter(r => r.to_routine === routine)) {
requireValue(path.isAbsolute(route.root) && text(route.from) && /^[a-z][a-z0-9-]+$/.test(route.source_routine) && Array.isArray(route.fields), 'Route needs explicit root, source, owner and allowed fields');
const dir = inside(route.root, `handoffs/outbox/${route.source_routine}`);
if (!fs.existsSync(dir)) continue;
for (const file of fs.readdirSync(dir).filter(f => f.endsWith('.json'))) {
const raw = JSON.parse(fs.readFileSync(inside(route.root, `handoffs/outbox/${route.source_routine}/${file}`), 'utf8'));
const row = Object.fromEntries(Object.entries(raw).filter(([k]) => k === 'schema' || route.fields.includes(k)));
validateHandoff(row);
requireValue(row.from === route.from && row.to === routine, 'Handoff identity does not match configured route');
// The outbox proposes work. Only local receiving receipts can accept or complete it.
requireValue(row.status === 'proposed', 'Producer outbox cannot assert recipient acceptance');
const key = `${route.from}/${row.id}`;
requireValue(!seen.has(key), 'Duplicate handoff id from the same source'); seen.add(key);
items.push({ ...row, status: Date.parse(row.expires_on) < now ? 'expired' : 'proposed' });
}
}
return { configured: true, items };
}
export function validateProgress(root, x) {
requireValue(x.schema === 1 && /^[a-z][a-z0-9-]+$/.test(x.routine), 'Invalid progress schema or routine');
for (const k of ['period', 'work_id', 'summary', 'next_action', 'next_check']) requireValue(text(x[k]), `Progress needs ${k}`);
requireValue(stamp(x.observed_at), 'Progress needs observed_at');
requireValue(typeof x.expected === 'boolean', 'Declare whether a deliverable was expected this period');
requireValue(['advanced', 'completed', 'blocked', 'quiet'].includes(x.delivery), 'Invalid delivery state');
requireValue(['unknown', 'unmeasured', 'inconclusive', 'improved', 'no-improvement', 'worse'].includes(x.business), 'Invalid business result');
requireValue(Array.isArray(x.artifacts) && Array.isArray(x.blockers), 'Artifacts and blockers must be arrays');
if (['improved', 'no-improvement', 'worse'].includes(x.business)) requireValue(text(x.result_evidence) && x.artifacts.includes(x.result_evidence), 'A measured business conclusion needs its result evidence among the verified artifacts');
if (['advanced', 'completed'].includes(x.delivery)) requireValue(x.artifacts.length > 0, 'Progress needs a verified deliverable');
const artifacts = x.artifacts.map(rel => {
requireValue(!/^(state|progress|archive)\/|(^|\/)runlog\.jsonl$/.test(rel), 'Bookkeeping alone is not a deliverable');
const p = inside(root, rel), bytes = fs.readFileSync(p);
requireValue(bytes.length > 0, 'Deliverable is empty');
return { path: rel, sha256: crypto.createHash('sha256').update(bytes).digest('hex') };
});
for (const b of x.blockers) {
for (const k of ['key', 'step', 'owner', 'kind', 'evidence', 'next_action', 'next_check']) requireValue(text(b[k]), `Blocker needs ${k}`);
requireValue(stamp(b.verified_at), 'Blocker must be verified this run');
requireValue(Date.parse(b.verified_at) <= Date.parse(x.observed_at), 'Blocker verification cannot be in the future');
requireValue(['permission', 'access', 'input', 'evidence', 'dependency'].includes(b.kind), 'Invalid blocker kind');
}
if (x.delivery === 'blocked') requireValue(x.blockers.length > 0, 'Blocked needs a scoped blocker');
return { ...x, verified_artifacts: artifacts };
}
export function deliveryHealth(rows, threshold = 2) {
requireValue(Number.isInteger(threshold) && threshold > 0, 'Invalid stalled threshold');
// Retries in one period do not count as extra eligible periods.
const periods = new Map();
for (const row of rows) periods.set(row.period, row);
const folded = [...periods.values()];
let streak = 0;
for (let i = folded.length - 1; i >= 0; i--) {
const r = folded[i];
if (!r.expected) break;
const prior = folded.slice(0, i).reverse().find(p => p.work_id === r.work_id && p.verified_artifacts?.length);
const changed = r.verified_artifacts?.length && (!prior || JSON.stringify(r.verified_artifacts.map(a => a.sha256).sort()) !== JSON.stringify(prior.verified_artifacts.map(a => a.sha256).sort()));
if (['completed', 'advanced'].includes(r.delivery) && changed) break;
streak++;
}
return { delivery: !folded.length ? 'unknown' : streak >= threshold ? 'stalled' : streak ? 'at-risk' : 'on-track', eligible_periods_without_progress: streak, latest: folded.at(-1) ?? null };
}
export function recordProgress(root, input) {
const profile = JSON.parse(fs.readFileSync(path.join(root, 'work-profile.json'), 'utf8'));
requireValue(Object.hasOwn(profile.routines, input.routine), 'Unknown routine');
const x = validateProgress(root, input), dir = inside(root, `progress/${x.routine}`);
fs.mkdirSync(dir, { recursive: true });
const receiptId = crypto.createHash('sha256').update(`${x.period}\n${x.work_id}\n${x.observed_at}`).digest('hex');
const file = path.join(dir, receiptId + '.json');
if (fs.existsSync(file)) { requireValue(fs.readFileSync(file, 'utf8') === JSON.stringify(x, null, 2) + '\n', 'Receipt id conflict'); return file; }
fs.writeFileSync(file, JSON.stringify(x, null, 2) + '\n', { flag: 'wx' });
return file;
}
export function readProgress(root, routine) {
const dir = inside(root, `progress/${routine}`);
if (!fs.existsSync(dir)) return [];
return fs.readdirSync(dir).filter(f => f.endsWith('.json')).map(f => JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8'))).sort((a, b) => a.observed_at.localeCompare(b.observed_at));
}
function selftest() {
const root = fs.mkdtempSync(path.join(os.tmpdir(), 'work-cycle-'));
try {
fs.mkdirSync(path.join(root, 'drafts')); fs.writeFileSync(path.join(root, 'drafts/result.md'), 'A sourced draft');
const p = { schema: 1, routine: 'test-produce', period: '2026-10-01', observed_at: '2026-10-01T10:00:00Z', work_id: 'draft-one', expected: true, delivery: 'completed', business: 'unmeasured', summary: 'Draft ready', artifacts: ['drafts/result.md'], blockers: [], next_action: 'Review current revision', next_check: 'next eligible period' };
const valid = validateProgress(root, p);
assert.equal(deliveryHealth([valid]).delivery, 'on-track');
assert.equal(deliveryHealth([valid, { ...valid, period: '2026-10-02' }, { ...valid, period: '2026-10-03' }]).delivery, 'stalled');
const held = { ...valid, delivery: 'quiet', verified_artifacts: [] };
assert.equal(deliveryHealth([held, held]).eligible_periods_without_progress, 1);
assert.equal(deliveryHealth([{ ...held, expected: false }]).delivery, 'on-track');
assert.equal(deliveryHealth([]).delivery, 'unknown');
assert.throws(() => validateProgress(root, { ...p, artifacts: ['../secret'] }));
assert.throws(() => validateProgress(root, { ...p, artifacts: ['state/job.json'] }));
assert.throws(() => validateProgress(root, { ...p, artifacts: [] }));
assert.throws(() => validateProgress(root, { ...p, business: 'improved' }));
assert.equal(chooseWork([{ id: 'publish', owned: true, authorized: false, fresh: true, inputs_ready: true }, { id: 'prepare', owned: true, authorized: true, fresh: true, inputs_ready: true }]).id, 'prepare');
assert.equal(chooseWork([{ owned: false, authorized: true, fresh: true, inputs_ready: true }]), null);
const experiment = Object.fromEntries(['id','owner','hypothesis','source','baseline','change','primary_metric','guardrail','review_when','decision_rule','authority'].map(k => [k, k]));
assert.equal(validateExperiment({ ...experiment, schema: 1, design: 'directional', status: 'inconclusive' }).status, 'inconclusive');
assert.throws(() => validateExperiment({ ...experiment, schema: 1, design: 'directional', status: 'improved', measurement_ready: false }));
assert.throws(() => validateExperiment({ ...experiment, schema: 1, design: 'controlled', status: 'prepared' }));
console.log('work-cycle: selftest PASS');
} finally { fs.rmSync(root, { recursive: true, force: true }); }
}
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
try {
const args = process.argv.slice(2), value = key => args[args.indexOf(key) + 1];
if (args.includes('--selftest')) selftest();
else {
const root = path.resolve(args.includes('--root') ? value('--root') : path.join(path.dirname(fileURLToPath(import.meta.url)), '..'));
if (args[0] === 'record') console.log(recordProgress(root, JSON.parse(fs.readFileSync(value('--file'), 'utf8'))));
else if (args[0] === 'health') {
const schedule = fs.readFileSync(path.join(root, 'SCHEDULE.md'), 'utf8');
const threshold = Number(/stalled_after_eligible_periods:\s*(\d+)/.exec(schedule)?.[1]);
console.log(JSON.stringify(deliveryHealth(readProgress(root, value('--routine')), threshold), null, 2));
} else if (args[0] === 'handoff-inbox') console.log(JSON.stringify(handoffInbox(root, value('--routine')), null, 2));
else if (args[0] === 'validate-experiment' || args[0] === 'validate-handoff') {
const x = JSON.parse(fs.readFileSync(value('--file'), 'utf8'));
(args[0] === 'validate-experiment' ? checkExperimentCapacity(root, x) : validateHandoff(x)); console.log('valid');
} else throw new Error('Usage: work-cycle.mjs record --file receipt.json | health --routine id | validate-experiment --file file | validate-handoff --file file | --selftest');
}
} catch (e) { console.error(e.message); process.exitCode = 1; }
}