@ours.network/fleet 0.1.0

package/dist/runner.js

@@ -0,0 +1,97 @@
+import { existsSync, readFileSync, writeFileSync, rmSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { parse } from 'yaml';
+import { agentDir } from './paths.js';
+import { loadConfig, findRole } from './config.js';
+import { getAdapter } from './harness/registry.js';
+import { Tmux } from './tmux.js';
+import { shq } from './exec.js';
+const defaultDeps = () => ({
+    tmux: new Tmux(),
+    isAlive: pid => { try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    } },
+    sleep: ms => new Promise(r => setTimeout(r, ms)),
+    now: () => Date.now(),
+    log: line => process.stderr.write(line + '\n'),
+});
+/** Compose the tmux pane shell command: env prefix + argv + exit-status capture. */
+export function buildPaneCommand(launch, roleEnv, exitStatusPath) {
+    const env = { PATH: process.env.PATH ?? '', ...launch.env, ...(roleEnv ?? {}) };
+    const envPfx = 'env ' + Object.entries(env).map(([k, v]) => `${k}=${shq(v)}`).join(' ');
+    const cmd = launch.argv.map(shq).join(' ');
+    return `${envPfx} ${cmd}; echo $? > ${shq(exitStatusPath)}`;
+}
+/** Read a temp role's config snapshot written by spawnTemp. */
+export function loadTempRole(name) {
+    const p = join(agentDir(name, true), 'role.yaml');
+    if (!existsSync(p))
+        throw new Error(`temp role '${name}' has no snapshot at ${p}`);
+    const role = parse(readFileSync(p, 'utf8'));
+    role.__temp = true;
+    return role;
+}
+/** One supervised session lifecycle. The supervisor re-invokes us after we return. */
+export async function runOnce(name, opts = {}, partialDeps = {}) {
+    const deps = { ...defaultDeps(), ...partialDeps };
+    const temp = opts.temp === true;
+    const role = temp ? loadTempRole(name) : findRole(loadConfig(opts.configPath), name);
+    const adapter = getAdapter(role.harness);
+    const dir = agentDir(name, temp);
+    mkdirSync(dir, { recursive: true });
+    const sidFile = join(dir, '.session-id');
+    if (!existsSync(sidFile))
+        writeFileSync(sidFile, randomUUID() + '\n');
+    const sessionId = readFileSync(sidFile, 'utf8').trim();
+    const bootedFile = join(dir, '.booted');
+    const exitFile = join(dir, '.exit-status');
+    const booted = existsSync(bootedFile);
+    const mode = booted && adapter.supportsResume ? 'resume' : 'fresh';
+    if (mode === 'fresh')
+        writeFileSync(bootedFile, '');
+    const runCwd = role.cwd && existsSync(role.cwd) ? role.cwd : dir;
+    const prep = await adapter.prepareSession(role, { stateDir: dir, runCwd });
+    const launch = adapter.buildLaunch(role, mode, { sessionId }, prep);
+    rmSync(exitFile, { force: true });
+    await deps.tmux.kill(name);
+    await deps.tmux.newSession(name, runCwd, buildPaneCommand(launch, role.env, exitFile));
+    let pid = null;
+    for (let i = 0; i < 40 && pid === null; i++) {
+        pid = await deps.tmux.panePid(name);
+        if (pid === null)
+            await deps.sleep(250);
+    }
+    if (pid === null)
+        throw new Error(`[${name}] could not resolve tmux pane pid`);
+    deps.log(`[${name}] up; pid=${pid} cwd=${runCwd} harness=${role.harness} mode=${mode}`);
+    const start = deps.now();
+    while (deps.isAlive(pid))
+        await deps.sleep(2000);
+    const elapsed = (deps.now() - start) / 1000;
+    const code = existsSync(exitFile) ? readFileSync(exitFile, 'utf8').trim() : 'crash';
+    const rotate = (why) => {
+        writeFileSync(sidFile, randomUUID() + '\n');
+        rmSync(bootedFile, { force: true });
+        deps.log(`[${name}] ${why} -> rotated session-id; next start is FRESH`);
+    };
+    if (code === '0' && adapter.exitPolicy.cleanExitIsFresh)
+        rotate(`clean exit (code 0)`);
+    else if (mode === 'resume' && elapsed < adapter.exitPolicy.fastFailSecs)
+        rotate(`resume failed fast (${elapsed.toFixed(0)}s, code ${code})`);
+    else
+        deps.log(`[${name}] exited (code ${code}, ${elapsed.toFixed(0)}s) -> next start RESUMES context`);
+}
+/** Temp-agent entrypoint: run one session, then remove the temp dir. */
+export async function runTemp(name, deps = {}) {
+    try {
+        await runOnce(name, { temp: true }, deps);
+    }
+    finally {
+        rmSync(agentDir(name, true), { recursive: true, force: true });
+    }
+}

package/dist/spawn.d.ts

@@ -0,0 +1,19 @@
+import { type OpsDeps } from './ops.js';
+import type { Tmux } from './tmux.js';
+export interface SpawnOpts {
+    name: string;
+    temp?: boolean;
+    harness?: string;
+    mission?: string;
+    identity?: string;
+    cwd?: string;
+    coordinator?: string;
+    bioFile?: string;
+    personaFile?: string;
+    overseeInterval?: string;
+    configPath?: string;
+}
+/** Permanent spawn: persist to ~/fleet.d/<Name>.yaml, then bring it up. */
+export declare function spawnPermanent(o: SpawnOpts, deps: OpsDeps): Promise<string>;
+/** Temp spawn: state under ~/.ours-fleet/tmp, plain tmux, auto-clean on exit. */
+export declare function spawnTemp(o: SpawnOpts, tmux: Tmux, binPath: string): Promise<string>;

package/dist/spawn.js

@@ -0,0 +1,57 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { stringify } from 'yaml';
+import { agentDir, fleetDDir } from './paths.js';
+import { loadConfig } from './config.js';
+import { applyRole, up } from './ops.js';
+import { shq } from './exec.js';
+function roleFromOpts(o) {
+    const r = {};
+    if (o.harness)
+        r.harness = o.harness;
+    if (o.identity)
+        r.identity = o.identity;
+    if (o.cwd)
+        r.cwd = o.cwd;
+    if (o.coordinator)
+        r.coordinator = o.coordinator;
+    if (o.mission)
+        r.mission = o.mission;
+    if (o.bioFile)
+        r.bio = readFileSync(o.bioFile, 'utf8').trim();
+    if (o.personaFile)
+        r.persona = readFileSync(o.personaFile, 'utf8').trim();
+    return r;
+}
+function assertNameFree(o) {
+    const cfg = loadConfig(o.configPath);
+    if (cfg.roles.some(r => r.name === o.name))
+        throw new Error(`role '${o.name}' already exists (${cfg.roles.find(r => r.name === o.name).sourceFile})`);
+    if (existsSync(agentDir(o.name)) || existsSync(agentDir(o.name, true)))
+        throw new Error(`agent dir for '${o.name}' already exists — pick another name or 'ours-fleet rm ${o.name}'`);
+}
+/** Permanent spawn: persist to ~/fleet.d/<Name>.yaml, then bring it up. */
+export async function spawnPermanent(o, deps) {
+    assertNameFree(o);
+    mkdirSync(fleetDDir(), { recursive: true });
+    const file = join(fleetDDir(), `${o.name}.yaml`);
+    writeFileSync(file, stringify({ roles: { [o.name]: roleFromOpts(o) } }));
+    await up(loadConfig(o.configPath), [o.name], deps);
+    return file;
+}
+/** Temp spawn: state under ~/.ours-fleet/tmp, plain tmux, auto-clean on exit. */
+export async function spawnTemp(o, tmux, binPath) {
+    assertNameFree(o);
+    const cfg = loadConfig(o.configPath);
+    const role = {
+        ...roleFromOpts(o),
+        name: o.name,
+        harness: o.harness ?? cfg.defaults.harness ?? 'claude-code',
+        identity: o.identity ?? o.name,
+        sourceFile: '(temp)',
+    };
+    const dir = applyRole(role, { temp: true });
+    writeFileSync(join(dir, 'role.yaml'), stringify(role));
+    await tmux.newSession(o.name, dir, `${shq(binPath)} _run-temp ${shq(o.name)}`);
+    return dir;
+}

package/dist/supervisor/index.d.ts

@@ -0,0 +1,7 @@
+import { type Exec } from '../exec.js';
+import type { SupervisorBackend } from './types.js';
+export type { SupervisorBackend } from './types.js';
+export { makeSystemdBackend, unitFor } from './systemd.js';
+export { makeLaunchdBackend, labelFor } from './launchd.js';
+export { makeNoneBackend } from './none.js';
+export declare function pickBackend(exec?: Exec, platform?: NodeJS.Platform): SupervisorBackend;

package/dist/supervisor/index.js

@@ -0,0 +1,16 @@
+import { realExec } from '../exec.js';
+import { makeSystemdBackend } from './systemd.js';
+import { makeLaunchdBackend } from './launchd.js';
+import { makeNoneBackend } from './none.js';
+export { makeSystemdBackend, unitFor } from './systemd.js';
+export { makeLaunchdBackend, labelFor } from './launchd.js';
+export { makeNoneBackend } from './none.js';
+export function pickBackend(exec = realExec, platform = process.platform) {
+    if (process.env.OURS_FLEET_SUPERVISOR === 'none')
+        return makeNoneBackend(exec);
+    if (platform === 'darwin')
+        return makeLaunchdBackend(exec);
+    if (platform === 'linux')
+        return makeSystemdBackend(exec);
+    throw new Error(`unsupported platform '${platform}' (linux and darwin only)`);
+}

package/dist/supervisor/launchd.d.ts

@@ -0,0 +1,4 @@
+import { type Exec } from '../exec.js';
+import type { SupervisorBackend } from './types.js';
+export declare const labelFor: (name: string) => string;
+export declare function makeLaunchdBackend(exec?: Exec, uid?: number): SupervisorBackend;

package/dist/supervisor/launchd.js

@@ -0,0 +1,76 @@
+import { mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { home, logsRoot } from '../paths.js';
+import { realExec } from '../exec.js';
+export const labelFor = (name) => `network.ours.fleet.${name}`;
+const agentsDir = () => join(home(), 'Library', 'LaunchAgents');
+const plistPath = (name) => join(agentsDir(), `${labelFor(name)}.plist`);
+function plist(name, binPath) {
+    const log = join(logsRoot(), `${name}.log`);
+    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>${labelFor(name)}</string>
+  <key>ProgramArguments</key>
+  <array><string>${binPath}</string><string>_run</string><string>${name}</string></array>
+  <key>KeepAlive</key><true/>
+  <key>RunAtLoad</key><true/>
+  <key>StandardOutPath</key><string>${log}</string>
+  <key>StandardErrorPath</key><string>${log}</string>
+</dict>
+</plist>
+`;
+}
+export function makeLaunchdBackend(exec = realExec, uid = process.getuid?.() ?? 501) {
+    const domain = `gui/${uid}`;
+    return {
+        id: 'launchd',
+        async init() {
+            mkdirSync(agentsDir(), { recursive: true });
+            mkdirSync(logsRoot(), { recursive: true });
+            return [
+                `LaunchAgents dir ready: ${agentsDir()}`,
+                'note: launchd agents start at login (macOS has no linger equivalent)',
+            ];
+        },
+        async install(name, binPath) {
+            mkdirSync(agentsDir(), { recursive: true });
+            mkdirSync(logsRoot(), { recursive: true });
+            writeFileSync(plistPath(name), plist(name, binPath));
+            await exec('launchctl', ['bootout', `${domain}/${labelFor(name)}`]); // best-effort refresh
+            const r = await exec('launchctl', ['bootstrap', domain, plistPath(name)]);
+            if (r.code !== 0)
+                throw new Error(`launchctl bootstrap ${labelFor(name)} failed: ${r.stderr.trim()}`);
+        },
+        async start(name) {
+            const r = await exec('launchctl', ['bootstrap', domain, plistPath(name)]);
+            if (r.code !== 0)
+                await exec('launchctl', ['kickstart', `${domain}/${labelFor(name)}`]);
+        },
+        async stop(name) {
+            const r = await exec('launchctl', ['bootout', `${domain}/${labelFor(name)}`]);
+            if (r.code !== 0)
+                throw new Error(`launchctl bootout ${labelFor(name)} failed: ${r.stderr.trim()}`);
+        },
+        async restart(name) {
+            const r = await exec('launchctl', ['kickstart', '-k', `${domain}/${labelFor(name)}`]);
+            if (r.code !== 0)
+                throw new Error(`launchctl kickstart ${labelFor(name)} failed: ${r.stderr.trim()}`);
+        },
+        async status(name) {
+            const r = await exec('launchctl', ['print', `${domain}/${labelFor(name)}`]);
+            if (r.code !== 0)
+                return `not loaded (${labelFor(name)})`;
+            return r.stdout.split('\n').slice(0, 12).join('\n');
+        },
+        async uninstall(name) {
+            await exec('launchctl', ['bootout', `${domain}/${labelFor(name)}`]);
+            rmSync(plistPath(name), { force: true });
+        },
+        logsArgs(name, follow) {
+            const log = join(logsRoot(), `${name}.log`);
+            return { cmd: 'tail', args: follow ? ['-f', log] : ['-n', '200', log] };
+        },
+    };
+}

package/dist/supervisor/none.d.ts

@@ -0,0 +1,8 @@
+import { type Exec } from '../exec.js';
+import type { SupervisorBackend } from './types.js';
+/**
+ * No supervision: sessions are plain tmux, nothing survives a reboot and
+ * nothing restarts on crash. Used for temp agents and CI tests
+ * (OURS_FLEET_SUPERVISOR=none).
+ */
+export declare function makeNoneBackend(exec?: Exec): SupervisorBackend;

package/dist/supervisor/none.js

@@ -0,0 +1,24 @@
+import { Tmux } from '../tmux.js';
+import { realExec, shq } from '../exec.js';
+/**
+ * No supervision: sessions are plain tmux, nothing survives a reboot and
+ * nothing restarts on crash. Used for temp agents and CI tests
+ * (OURS_FLEET_SUPERVISOR=none).
+ */
+export function makeNoneBackend(exec = realExec) {
+    const tmux = new Tmux(exec);
+    return {
+        id: 'none',
+        async init() { return ['no supervisor: sessions are plain tmux (no reboot survival)']; },
+        async install(name, binPath) {
+            await tmux.kill(name);
+            await tmux.newSession(name, process.cwd(), `${shq(binPath)} _run ${shq(name)}`);
+        },
+        async start(name) { throw new Error(`'${name}' has no unit under the none backend — use install/spawn`); },
+        async stop(name) { await tmux.kill(name); },
+        async restart(name) { throw new Error(`restart unsupported under the none backend — stop + install '${name}'`); },
+        async status(name) { return (await tmux.has(name)) ? `tmux session '${name}' running` : `'${name}' not running`; },
+        async uninstall(name) { await tmux.kill(name); },
+        logsArgs(name) { return { cmd: 'tmux', args: ['capture-pane', '-t', name, '-p'] }; },
+    };
+}

package/dist/supervisor/systemd.d.ts

@@ -0,0 +1,5 @@
+import { type Exec } from '../exec.js';
+import type { SupervisorBackend } from './types.js';
+export declare const UNIT_TEMPLATE = "ours-fleet-agent@.service";
+export declare const unitFor: (name: string) => string;
+export declare function makeSystemdBackend(exec?: Exec): SupervisorBackend;

package/dist/supervisor/systemd.js

@@ -0,0 +1,63 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { userInfo } from 'node:os';
+import { home } from '../paths.js';
+import { realExec } from '../exec.js';
+export const UNIT_TEMPLATE = 'ours-fleet-agent@.service';
+export const unitFor = (name) => `ours-fleet-agent@${name}.service`;
+export function makeSystemdBackend(exec = realExec) {
+    const ctl = (...args) => exec('systemctl', ['--user', ...args]);
+    return {
+        id: 'systemd',
+        async init(binPath) {
+            const msgs = [];
+            const unitDir = join(home(), '.config', 'systemd', 'user');
+            mkdirSync(unitDir, { recursive: true });
+            writeFileSync(join(unitDir, UNIT_TEMPLATE), `[Unit]
+Description=ours-fleet agent %i
+After=default.target
+
+[Service]
+Type=simple
+ExecStart=${binPath} _run %i
+Restart=always
+RestartSec=2
+TimeoutStopSec=15
+
+[Install]
+WantedBy=default.target
+`);
+            msgs.push(`installed ${join(unitDir, UNIT_TEMPLATE)}`);
+            await ctl('daemon-reload');
+            const linger = await exec('loginctl', ['enable-linger', userInfo().username]);
+            msgs.push(linger.code === 0
+                ? 'linger enabled (roles survive logout + reboot)'
+                : `warning: could not enable linger (${linger.stderr.trim() || 'permission'}) — run: sudo loginctl enable-linger ${userInfo().username}`);
+            return msgs;
+        },
+        async install(name) {
+            const r = await ctl('enable', '--now', unitFor(name));
+            if (r.code !== 0)
+                throw new Error(`systemctl enable --now ${unitFor(name)} failed: ${r.stderr.trim()}`);
+        },
+        async start(name) { await ctl('start', unitFor(name)); },
+        async stop(name) {
+            const r = await ctl('stop', unitFor(name));
+            if (r.code !== 0)
+                throw new Error(`systemctl stop ${unitFor(name)} failed: ${r.stderr.trim()}`);
+        },
+        async restart(name) {
+            const r = await ctl('restart', unitFor(name));
+            if (r.code !== 0)
+                throw new Error(`systemctl restart ${unitFor(name)} failed: ${r.stderr.trim()}`);
+        },
+        async status(name) {
+            const r = await ctl('status', unitFor(name), '--no-pager');
+            return r.stdout || r.stderr;
+        },
+        async uninstall(name) { await ctl('disable', '--now', unitFor(name)); },
+        logsArgs(name, follow) {
+            return { cmd: 'journalctl', args: ['--user', '-u', unitFor(name), ...(follow ? ['-f'] : ['-n', '200'])] };
+        },
+    };
+}

package/dist/supervisor/types.d.ts

@@ -0,0 +1,17 @@
+export interface SupervisorBackend {
+    id: 'systemd' | 'launchd' | 'none';
+    /** One-time host setup (unit template / dirs / linger). Returns human-readable messages. */
+    init(binPath: string): Promise<string[]>;
+    /** Ensure the role's unit exists and is enabled + started. */
+    install(name: string, binPath: string): Promise<void>;
+    start(name: string): Promise<void>;
+    stop(name: string): Promise<void>;
+    restart(name: string): Promise<void>;
+    status(name: string): Promise<string>;
+    uninstall(name: string): Promise<void>;
+    /** Command the CLI execs (stdio inherited) to show logs. */
+    logsArgs(name: string, follow: boolean): {
+        cmd: string;
+        args: string[];
+    };
+}

package/dist/supervisor/types.js

@@ -0,0 +1 @@
+export {};

package/dist/tmux.d.ts

@@ -0,0 +1,14 @@
+import { type Exec } from './exec.js';
+/** Thin tmux wrapper; all session handling in the core goes through this. */
+export declare class Tmux {
+    private exec;
+    constructor(exec?: Exec);
+    has(name: string): Promise<boolean>;
+    newSession(name: string, cwd: string, shellCommand: string): Promise<void>;
+    kill(name: string): Promise<void>;
+    capture(name: string, lines?: number): Promise<string>;
+    panePid(name: string): Promise<number | null>;
+    list(): Promise<string>;
+    sendText(name: string, text: string): Promise<void>;
+    sendKey(name: string, key: string): Promise<void>;
+}

package/dist/tmux.js

@@ -0,0 +1,50 @@
+import { realExec } from './exec.js';
+/** Thin tmux wrapper; all session handling in the core goes through this. */
+export class Tmux {
+    exec;
+    constructor(exec = realExec) {
+        this.exec = exec;
+    }
+    async has(name) {
+        return (await this.exec('tmux', ['has-session', '-t', name])).code === 0;
+    }
+    async newSession(name, cwd, shellCommand) {
+        const r = await this.exec('tmux', ['new-session', '-d', '-s', name, '-c', cwd, shellCommand]);
+        if (r.code !== 0)
+            throw new Error(`tmux new-session '${name}' failed (${r.code}): ${r.stderr.trim()}`);
+    }
+    async kill(name) {
+        await this.exec('tmux', ['kill-session', '-t', name]); // best-effort
+    }
+    async capture(name, lines = 40) {
+        const r = await this.exec('tmux', ['capture-pane', '-t', name, '-p']);
+        if (r.code !== 0)
+            throw new Error(`tmux capture-pane '${name}' failed: ${r.stderr.trim()}`);
+        const all = r.stdout.replace(/\n+$/, '').split('\n');
+        return all.slice(-lines).join('\n');
+    }
+    async panePid(name) {
+        const r = await this.exec('tmux', ['list-panes', '-t', name, '-F', '#{pane_pid}']);
+        if (r.code !== 0)
+            return null;
+        const pid = parseInt(r.stdout.trim().split('\n')[0], 10);
+        return Number.isFinite(pid) ? pid : null;
+    }
+    async list() {
+        const r = await this.exec('tmux', ['ls']);
+        return r.code === 0 ? r.stdout.trimEnd() : '';
+    }
+    async sendText(name, text) {
+        let r = await this.exec('tmux', ['send-keys', '-t', name, '-l', text]);
+        if (r.code !== 0)
+            throw new Error(`tmux send-keys '${name}' failed: ${r.stderr.trim()}`);
+        r = await this.exec('tmux', ['send-keys', '-t', name, 'Enter']);
+        if (r.code !== 0)
+            throw new Error(`tmux send-keys Enter '${name}' failed: ${r.stderr.trim()}`);
+    }
+    async sendKey(name, key) {
+        const r = await this.exec('tmux', ['send-keys', '-t', name, key]);
+        if (r.code !== 0)
+            throw new Error(`tmux send-keys '${name}' failed: ${r.stderr.trim()}`);
+    }
+}

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION: string;

package/dist/version.js

@@ -0,0 +1,3 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+export const VERSION = require('../package.json').version;

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@ours.network/fleet",
+  "version": "0.1.0",
+  "description": "Harness-agnostic fleet of persistent, identity-bound AI agents. Declarative fleet.yaml, tmux consoles, systemd/launchd supervision, ours.network messaging.",
+  "type": "module",
+  "license": "FSL-1.1-Apache-2.0",
+  "repository": { "type": "git", "url": "https://github.com/adapt-toolkit/ours-fleet.git" },
+  "bin": { "ours-fleet": "dist/cli.js" },
+  "main": "dist/index.js",
+  "files": ["dist", "README.md", "LICENSE"],
+  "engines": { "node": ">=20" },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": { "commander": "^12.1.0", "yaml": "^2.5.0" },
+  "devDependencies": { "@types/node": "^20.14.0", "typescript": "^5.5.0", "vitest": "^2.0.0" }
+}