@ours.network/fleet 0.10.3 → 0.10.4

package/dist/application/role-repository.js

@@ -0,0 +1,168 @@
+import { lstatSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { parse } from 'yaml';
+import { loadConfig, resolveMonitorConfig, resolvePermissions, ROLE_NAME_RE, } from '../config.js';
+import { agentsRoot, tmpRoot } from '../paths.js';
+const MAX_SNAPSHOT_BYTES = 256 * 1024;
+function safeDirs(root) {
+    try {
+        return readdirSync(root, { withFileTypes: true })
+            .filter(entry => entry.isDirectory() && !entry.isSymbolicLink() && ROLE_NAME_RE.test(entry.name))
+            .map(entry => entry.name);
+    }
+    catch {
+        return [];
+    }
+}
+function view(role) {
+    return {
+        name: role.name, harness: role.harness, session: role.session, identity: role.identity,
+        mission: role.mission, coordinator: role.coordinator, model: role.model,
+        cwd: role.cwd ? redactHome(role.cwd) : undefined,
+        permissions: role.permissions,
+    };
+}
+function redactHome(path) {
+    const home = process.env.OURS_FLEET_HOME;
+    return home && (path === home || path.startsWith(home + '/')) ? `~${path.slice(home.length)}` : path;
+}
+function snapshot(path, name) {
+    try {
+        const stat = lstatSync(path);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_SNAPSHOT_BYTES)
+            throw new Error('snapshot is not a bounded regular file');
+        const raw = parse(readFileSync(path, 'utf8'));
+        if (!raw || typeof raw !== 'object')
+            throw new Error('snapshot must be a mapping');
+        const session = raw.session === 'acp' || raw.session === 'tmux' ? raw.session : 'tmux';
+        return {
+            role: {
+                ...raw, name, harness: typeof raw.harness === 'string' ? raw.harness : 'claude-code',
+                session, identity: typeof raw.identity === 'string' ? raw.identity : name,
+                permissions: resolvePermissions(undefined, raw.permissions),
+                permissionsDeclared: raw.permissions !== undefined,
+                monitor: resolveMonitorConfig(undefined, raw.monitor),
+                sourceFile: '(temp)',
+            },
+        };
+    }
+    catch (error) {
+        return {
+            problem: {
+                code: 'corrupt_temp_snapshot', severity: 'error', source: 'role.yaml',
+                detail: `temporary snapshot is unreadable: ${error.message}`,
+            },
+        };
+    }
+}
+async function boundedMap(values, limit, fn) {
+    const results = new Array(values.length);
+    let next = 0;
+    await Promise.all(Array.from({ length: Math.min(limit, values.length) }, async () => {
+        for (;;) {
+            const index = next++;
+            if (index >= values.length)
+                return;
+            results[index] = await fn(values[index]);
+        }
+    }));
+    return results;
+}
+export class RoleRepository {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async list() {
+        const permanentRoot = this.options.permanentRoot ?? agentsRoot();
+        const temporaryRoot = this.options.temporaryRoot ?? tmpRoot();
+        let configured = [];
+        let configProblem;
+        try {
+            configured = loadConfig(this.options.configPath).roles;
+        }
+        catch (error) {
+            configProblem = { code: 'config_invalid', severity: 'error', source: 'config', detail: error.message };
+        }
+        const permanent = new Set(safeDirs(permanentRoot));
+        const temporary = new Set(safeDirs(temporaryRoot));
+        const configuredByName = new Map(configured.map(role => [role.name, role]));
+        const names = [...new Set([...configuredByName.keys(), ...permanent, ...temporary])].sort();
+        return boundedMap(names, this.options.concurrency ?? 8, async (name) => {
+            const config = configuredByName.get(name);
+            const inPermanent = permanent.has(name);
+            const inTemporary = temporary.has(name);
+            const problems = configProblem ? [configProblem] : [];
+            let tempRole;
+            let stateHealth = inPermanent || inTemporary ? 'present' : 'missing';
+            if (inTemporary) {
+                const read = snapshot(join(temporaryRoot, name, 'role.yaml'), name);
+                tempRole = read.role;
+                if (read.problem) {
+                    problems.push(read.problem);
+                    stateHealth = 'corrupt';
+                }
+            }
+            if (inPermanent && inTemporary)
+                problems.push({ code: 'duplicate_state', severity: 'error', detail: 'both permanent and temporary state exist' });
+            const intended = config?.session ?? tempRole?.session;
+            const detected = await this.detect(name, intended);
+            if (intended && detected !== 'none' && detected !== intended && detected !== 'ambiguous')
+                problems.push({
+                    code: 'backend_mismatch', severity: 'warning',
+                    detail: `configured ${intended}, detected ${detected}`,
+                });
+            return {
+                id: name,
+                lifetime: config ? 'permanent' : inTemporary ? 'temporary' : 'orphan',
+                configured: Boolean(config),
+                config: config ? view(config) : tempRole ? view(tempRole) : undefined,
+                stateRef: inTemporary ? { lifetime: 'temporary' } : inPermanent ? { lifetime: 'permanent' } : undefined,
+                stateHealth,
+                configuredBackend: intended,
+                detectedBackend: detected,
+                compatibility: { compatible: true },
+                problems,
+            };
+        });
+    }
+    async get(id) {
+        if (!ROLE_NAME_RE.test(id))
+            return undefined;
+        return (await this.list()).find(role => role.id === id);
+    }
+    stateDir(record) {
+        if (!record.stateRef)
+            return undefined;
+        const root = record.stateRef.lifetime === 'temporary'
+            ? (this.options.temporaryRoot ?? tmpRoot()) : (this.options.permanentRoot ?? agentsRoot());
+        const candidate = join(root, record.id);
+        try {
+            const canonicalRoot = realpathSync(root);
+            const canonical = realpathSync(candidate);
+            const rel = relative(canonicalRoot, canonical);
+            if (rel.startsWith('..') || rel === '')
+                return rel === '' ? undefined : undefined;
+            return canonical;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async detect(name, intended) {
+        if (!this.options.probeBackend)
+            return intended ?? 'none';
+        const timeoutMs = this.options.timeoutMs ?? 2_000;
+        const result = await Promise.race([
+            this.options.probeBackend(name, intended),
+            new Promise(resolve => setTimeout(() => resolve({ acp: false, tmux: false }), timeoutMs)),
+        ]).catch(() => ({ acp: false, tmux: false }));
+        if (result.acp && result.tmux)
+            return 'ambiguous';
+        if (result.acp)
+            return 'acp';
+        if (result.tmux)
+            return 'tmux';
+        return 'none';
+    }
+}

package/dist/application/session-control.d.ts

@@ -0,0 +1,55 @@
+import { controlRequest } from '../session/control.js';
+import type { SessionSnapshot } from '../session/types.js';
+import { Tmux } from '../tmux.js';
+import type { OutputPage, SendReceipt, SessionDescriptor } from './types.js';
+export interface RoleSessionControl {
+    describe(): Promise<SessionDescriptor>;
+    snapshot(): Promise<SessionSnapshot>;
+    recentOutput(request?: {
+        since?: number;
+        limit?: number;
+    }): Promise<OutputPage>;
+    sendText(text: string): Promise<SendReceipt>;
+    interrupt?(): Promise<{
+        accepted: true;
+    }>;
+    respondPermission?(request: {
+        permissionId: string;
+        optionId: string;
+    }): Promise<{
+        accepted: true;
+    }>;
+}
+export declare class AcpRoleSessionAdapter implements RoleSessionControl {
+    private readonly stateDir;
+    private readonly request;
+    constructor(stateDir: string, request?: typeof controlRequest);
+    describe(): Promise<SessionDescriptor>;
+    snapshot(): Promise<SessionSnapshot>;
+    recentOutput(request?: {
+        since?: number;
+        limit?: number;
+    }): Promise<OutputPage>;
+    sendText(text: string): Promise<SendReceipt>;
+    interrupt(): Promise<{
+        accepted: true;
+    }>;
+    respondPermission(request: {
+        permissionId: string;
+        optionId: string;
+    }): Promise<{
+        accepted: true;
+    }>;
+    private call;
+}
+export declare class TmuxRoleSessionAdapter implements RoleSessionControl {
+    private readonly roleId;
+    private readonly tmux;
+    constructor(roleId: string, tmux?: Tmux);
+    describe(): Promise<SessionDescriptor>;
+    snapshot(): Promise<SessionSnapshot>;
+    recentOutput(request?: {
+        limit?: number;
+    }): Promise<OutputPage>;
+    sendText(text: string): Promise<SendReceipt>;
+}

package/dist/application/session-control.js

@@ -0,0 +1,115 @@
+import { randomUUID } from 'node:crypto';
+import { controlRequest } from '../session/control.js';
+import { Tmux } from '../tmux.js';
+import { FleetError, normalizeError } from './errors.js';
+const visibleEvents = (events) => events.filter(event => event.kind !== 'thought');
+export class AcpRoleSessionAdapter {
+    stateDir;
+    request;
+    constructor(stateDir, request = controlRequest) {
+        this.stateDir = stateDir;
+        this.request = request;
+    }
+    async describe() {
+        const response = await this.call('snapshot');
+        const result = response;
+        return {
+            backend: 'acp', protocolVersion: result.protocolVersion ?? 1,
+            features: result.features ?? [], snapshot: result,
+        };
+    }
+    async snapshot() {
+        return await this.call('snapshot');
+    }
+    async recentOutput(request = {}) {
+        const limit = Math.min(Math.max(request.limit ?? 100, 1), 500);
+        const descriptor = await this.describe();
+        const result = descriptor.protocolVersion >= 2
+            ? await this.call('events_since', { since: request.since ?? 0 })
+            : await this.call('follow', { since: request.since ?? 0, controller: false });
+        const page = result;
+        const events = visibleEvents(page.events ?? []).slice(-limit);
+        return {
+            events, firstSeq: page.firstSeq ?? events[0]?.seq,
+            lastSeq: page.lastSeq ?? events.at(-1)?.seq,
+            truncated: Boolean(page.truncated) || (page.events?.length ?? 0) > limit,
+            nextCursor: events.at(-1) ? String(events.at(-1).seq) : undefined,
+        };
+    }
+    async sendText(text) {
+        if (!text.trim())
+            throw new FleetError('invalid_request', 'text is required');
+        if (Buffer.byteLength(text) > 32 * 1024)
+            throw new FleetError('invalid_request', 'text exceeds 32 KiB');
+        const result = await this.call('submit_prompt', { text });
+        return {
+            accepted: true, promptId: result.promptId, queuedBehind: result.queuedBehind,
+            terminalOutcomeKnown: false,
+            detail: result.queuedBehind
+                ? `accepted; ${result.queuedBehind} turn(s) queued ahead`
+                : 'accepted; turn may still be running',
+        };
+    }
+    async interrupt() {
+        await this.call('interrupt');
+        return { accepted: true };
+    }
+    async respondPermission(request) {
+        await this.call('respond_permission', request);
+        return { accepted: true };
+    }
+    async call(command, fields = {}) {
+        try {
+            const response = await this.request(this.stateDir, { command, ...fields }, 5_000);
+            if (!response.ok)
+                throw new FleetError(response.kind === 'offline' ? 'offline'
+                    : response.kind === 'control-unavailable' ? 'control_unavailable'
+                        : response.kind === 'timeout' ? 'timeout'
+                            : response.kind === 'rejected' ? 'rejected' : 'backend_failure', response.error ?? `${command} failed`, { provesOffline: response.kind === 'offline' });
+            return response.result;
+        }
+        catch (error) {
+            throw normalizeError(error);
+        }
+    }
+}
+export class TmuxRoleSessionAdapter {
+    roleId;
+    tmux;
+    constructor(roleId, tmux = new Tmux()) {
+        this.roleId = roleId;
+        this.tmux = tmux;
+    }
+    async describe() {
+        return { backend: 'tmux', protocolVersion: 1, features: ['text', 'capture'] };
+    }
+    async snapshot() {
+        const alive = await this.tmux.has(this.roleId);
+        return { backend: 'tmux', alive, readiness: alive ? 'idle' : 'failed' };
+    }
+    async recentOutput(request = {}) {
+        try {
+            const text = await this.tmux.capture(this.roleId, Math.min(request.limit ?? 100, 500));
+            return { events: [], text, truncated: false };
+        }
+        catch (error) {
+            throw normalizeError(error);
+        }
+    }
+    async sendText(text) {
+        if (!text.trim())
+            throw new FleetError('invalid_request', 'text is required');
+        if (Buffer.byteLength(text) > 32 * 1024)
+            throw new FleetError('invalid_request', 'text exceeds 32 KiB');
+        try {
+            await this.tmux.sendText(this.roleId, text);
+        }
+        catch (error) {
+            throw normalizeError(error);
+        }
+        return {
+            accepted: true, promptId: randomUUID(), queuedBehind: 0, terminalOutcomeKnown: false,
+            detail: 'literal text and Enter sent; terminal outcome is unknown',
+        };
+    }
+}

package/dist/application/types.d.ts

@@ -0,0 +1,156 @@
+import type { CommonPermissions, SessionBackendId } from '../config.js';
+import type { ExitRecord, SessionEvent, SessionSnapshot } from '../session/types.js';
+export type RoleLifetime = 'permanent' | 'temporary' | 'orphan';
+export type DetectedBackend = SessionBackendId | 'none' | 'ambiguous';
+export interface ResolvedRoleView {
+    name: string;
+    harness: string;
+    session: SessionBackendId;
+    identity: string;
+    mission?: string;
+    coordinator?: string;
+    model?: string;
+    cwd?: string;
+    permissions: CommonPermissions;
+}
+export interface RoleRecord {
+    id: string;
+    lifetime: RoleLifetime;
+    configured: boolean;
+    config?: ResolvedRoleView;
+    stateRef?: {
+        lifetime: 'permanent' | 'temporary';
+    };
+    stateHealth: 'present' | 'missing' | 'corrupt';
+    configuredBackend?: SessionBackendId;
+    detectedBackend: DetectedBackend;
+    compatibility: {
+        compatible: boolean;
+        detail?: string;
+    };
+    problems: Problem[];
+}
+export interface Problem {
+    code: string;
+    severity: 'info' | 'warning' | 'error';
+    detail: string;
+    source?: string;
+}
+export interface RoleStatus {
+    roleId: string;
+    observedAt: string;
+    overall: 'ready' | 'busy' | 'attention' | 'offline' | 'unknown';
+    supervisor: {
+        backend: 'systemd' | 'launchd' | 'none';
+        liveness: 'running' | 'stopped' | 'unknown';
+        nativeState?: string;
+        detail: string;
+    };
+    session: {
+        backend: SessionBackendId | 'unknown';
+        reachability: 'online' | 'offline' | 'unavailable' | 'unknown';
+        readiness: 'starting' | 'idle' | 'running' | 'awaiting_permission' | 'failed' | 'unknown';
+        evidence: 'authoritative' | 'inferred';
+        sessionId?: string;
+        lastError?: string;
+        pendingPermissionId?: string;
+    };
+    restart: {
+        circuit: 'closed' | 'open';
+        consecutiveImmediateFailures: number;
+        nextDelayMs: number;
+        lastReason?: string;
+        openedAt?: string;
+    };
+    monitor: {
+        mode: 'fleet' | 'native' | 'unknown';
+        health: 'armed' | 'degraded' | 'failed' | 'unknown';
+        updatedAt?: string;
+        detail?: string;
+        stale: boolean;
+    };
+    lastExit?: ExitRecord;
+    isolation: {
+        degraded: boolean;
+        detail?: string;
+    };
+    problems: Problem[];
+}
+export interface RoleCapabilities {
+    protocolVersion: number;
+    inventory: true;
+    status: true;
+    output: {
+        recent: boolean;
+        stream: boolean;
+        structured: boolean;
+        replayCursor: boolean;
+    };
+    input: {
+        text: boolean;
+        rawKeys: boolean;
+        interrupt: boolean;
+        steering: boolean;
+    };
+    permissions: {
+        observe: boolean;
+        respond: boolean;
+    };
+    terminal: {
+        available: boolean;
+        reason?: 'wrong_backend' | 'pty_unavailable' | 'offline' | 'incompatible_runner';
+        multiViewer: boolean;
+        writerLease: boolean;
+    };
+    lifecycle: {
+        start: boolean;
+        stop: boolean;
+        restartResume: boolean;
+        restartFresh: boolean;
+        remove: boolean;
+    };
+    logs: {
+        tail: boolean;
+        follow: boolean;
+        cursor: boolean;
+    };
+}
+export interface OutputPage {
+    events: SessionEvent[];
+    text?: string;
+    firstSeq?: number;
+    lastSeq?: number;
+    truncated: boolean;
+    nextCursor?: string;
+}
+export interface SendReceipt {
+    accepted: boolean;
+    promptId: string;
+    queuedBehind: number;
+    terminalOutcomeKnown: boolean;
+    detail: string;
+}
+export interface SessionDescriptor {
+    backend: SessionBackendId;
+    protocolVersion: number;
+    features: string[];
+    snapshot?: SessionSnapshot;
+}
+export interface LogRecord {
+    at?: string;
+    text: string;
+    cursor?: string;
+    redactionApplied: boolean;
+    compacted?: {
+        kind: 'monitor_stream_hiccup';
+        reason: string;
+        count: number;
+        firstAt?: string;
+        lastAt?: string;
+    };
+}
+export interface LogPage {
+    records: LogRecord[];
+    nextCursor?: string;
+    truncated: boolean;
+}

package/dist/application/types.js

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

package/dist/cli.js

@@ -22,6 +22,9 @@ import { allWarnings, analyzeFleetPermissions, formatNative } from './permission
 import { AI_DOCS } from './docs.js';
 import { controlRequest, controlSocketPath, followControl, livenessNote, } from './session/control.js';
 import { SessionControlError } from './session/types.js';
+import { startWebConsole } from './web/runtime.js';
+import { requestWebControl } from './web/control.js';
+import { WebServiceManager } from './web/service.js';
 import './harness/claude-code.js'; // registers the claude-code adapter
 import './harness/codex.js'; // registers the codex adapter
 // sudo/su shells lack XDG_RUNTIME_DIR, breaking every systemctl/journalctl
@@ -47,6 +50,7 @@ const passthrough = (cmd, args) => new Promise(resolve => {
 const program = new Command()
     .name('ours-fleet')
     .description('Fleet of persistent, identity-bound AI agents — selectable harness and tmux/ACP sessions.')
+    .enablePositionalOptions()
     .version(VERSION);
 const cOpt = (cmd) => cmd.option('-c, --configuration <file>', 'config file (default: ~/fleet.yaml + ~/fleet.d/)');
 const collect = (value, previous) => [...previous, value];
@@ -508,6 +512,143 @@ program.command('init').description('one-time host setup (units, dirs, linger)')
         console.log(m);
     console.log('\nNext: copy examples/fleet.yaml to ~/fleet.yaml, edit, then: ours-fleet up');
 });
+const webCommand = cOpt(program.command('web').description('start or open the secure localhost fleet web console'))
+    .enablePositionalOptions()
+    .option('--port <port>', 'loopback service port (default: 49271)', value => {
+    const port = Number(value);
+    if (!Number.isInteger(port) || port < 1 || port > 65_535)
+        throw new Error('invalid port');
+    return port;
+})
+    .option('--no-open', 'do not open a browser automatically')
+    .action(async (opts) => {
+    try {
+        const manager = new WebServiceManager();
+        for (const line of await manager.install(binPath, opts.port ?? 49_271, opts.configuration))
+            process.stdout.write(line + '\n');
+        await manager.start();
+        if (opts.open !== false) {
+            await requestWebControlWhenReady('open');
+            process.stdout.write('Trusted-browser pairing opened locally.\n');
+        }
+        else
+            process.stdout.write('Web service started; run `ours-fleet web open` to pair a browser.\n');
+    }
+    catch (e) {
+        die(e);
+    }
+});
+const webPort = (command) => cOpt(command)
+    .option('--port <port>', 'loopback service port (default: 49271)', value => {
+    const port = Number(value);
+    if (!Number.isInteger(port) || port < 1 || port > 65_535)
+        throw new Error('invalid port');
+    return port;
+});
+const webServe = cOpt(webCommand.command('serve').description('run the web console in the foreground'))
+    .option('--port <port>', 'loopback port (default: 49271; 0 chooses a free port)', value => {
+    const port = Number(value);
+    if (!Number.isInteger(port) || port < 0 || port > 65_535)
+        throw new Error('invalid port');
+    return port;
+});
+webServe
+    .option('--no-open', 'do not open a browser automatically')
+    .action(async (opts) => {
+    try {
+        const consoleServer = await startWebConsole({
+            configPath: opts.configuration, port: opts.port,
+            open: opts.open !== false, binPath,
+            log: line => process.stderr.write(line + '\n'),
+        });
+        process.stdout.write(`ours-fleet web listening on ${consoleServer.address}\n`);
+        process.stdout.write(opts.open !== false
+            ? 'Trusted-browser pairing opened locally.\n'
+            : 'Run `ours-fleet web open` on this computer to pair a browser.\n');
+        const shutdown = async () => { await consoleServer.close(); process.exit(0); };
+        process.once('SIGINT', () => { void shutdown(); });
+        process.once('SIGTERM', () => { void shutdown(); });
+    }
+    catch (e) {
+        die(e);
+    }
+});
+webPort(webCommand.command('install').description('install or update the owner web service'))
+    .action(async (opts) => {
+    try {
+        for (const line of await new WebServiceManager().install(binPath, opts.port ?? 49_271, opts.configuration))
+            process.stdout.write(line + '\n');
+    }
+    catch (e) {
+        die(e);
+    }
+});
+for (const [name, description] of [
+    ['start', 'start the installed owner web service'],
+    ['stop', 'stop the owner web service'],
+    ['restart', 'restart the owner web service'],
+])
+    webCommand.command(name).description(description).action(async () => {
+        try {
+            await new WebServiceManager()[name]();
+            process.stdout.write(`Web service ${{ start: 'started', stop: 'stopped', restart: 'restarted' }[name]}.\n`);
+        }
+        catch (e) {
+            die(e);
+        }
+    });
+webCommand.command('status').description('show native web service status')
+    .action(async () => {
+    try {
+        process.stdout.write(await new WebServiceManager().status() + '\n');
+    }
+    catch (e) {
+        die(e);
+    }
+});
+webCommand.command('uninstall').description('stop and uninstall the owner web service')
+    .action(async () => {
+    try {
+        process.stdout.write(await new WebServiceManager().uninstall() + '\n');
+    }
+    catch (e) {
+        die(e);
+    }
+});
+webCommand.command('open').description('securely open or re-pair a browser with the running console')
+    .action(async () => {
+    try {
+        await requestWebControl('open');
+        process.stdout.write('Trusted-browser pairing opened locally.\n');
+    }
+    catch (e) {
+        die(e);
+    }
+});
+webCommand.command('revoke-all').description('revoke all trusted browsers and active web sessions')
+    .action(async () => {
+    try {
+        await requestWebControl('revoke-all');
+        process.stdout.write('Revoked all trusted browsers and active web sessions.\n');
+    }
+    catch (e) {
+        die(e);
+    }
+});
+async function requestWebControlWhenReady(command) {
+    let last;
+    for (let attempt = 0; attempt < 40; attempt++) {
+        try {
+            await requestWebControl(command, undefined, 500);
+            return;
+        }
+        catch (error) {
+            last = error;
+            await new Promise(resolve => setTimeout(resolve, 125));
+        }
+    }
+    throw last;
+}
 program.command('_run <name>', { hidden: true }).description('internal: supervisor entrypoint')
     .option('-c, --configuration <file>')
     .action(async (name, opts) => {