@ours.network/fleet 0.18.1 → 0.19.0-nightly.10

package/dist/rooms-tasks/close.d.ts

@@ -0,0 +1,21 @@
+import { withFileLock } from '../atomic-file.js';
+import type { CoworkAdapter } from './cowork-adapter.js';
+import type { RoomMemberSeat, RoomOrchestrationRecord } from './types.js';
+export interface RoomCloseDeps {
+    inspectMember?(seat: RoomMemberSeat): Promise<{
+        launchId: string;
+    }>;
+    requestStop?(role: string): Promise<void>;
+    waitForLivenessAbsent?(role: string, launchId: string): Promise<void>;
+    secureArchive?(role: string, launchId: string): Promise<string>;
+    removeIdentity?(seat: RoomMemberSeat): Promise<void>;
+    lock?: typeof withFileLock;
+}
+/** One forward-only room close saga shared by every Fleet entry point. */
+export declare function acceptManagedRoomClose(roomId: string): Promise<RoomOrchestrationRecord>;
+export declare function recordManagedRoomCloseError(roomId: string, error: string, recoveryHint: string): Promise<RoomOrchestrationRecord>;
+export declare function closeManagedRoom(input: {
+    roomId: string;
+    cowork: Pick<CoworkAdapter, 'closeRoom'>;
+    deps?: RoomCloseDeps;
+}): Promise<RoomOrchestrationRecord>;

package/dist/rooms-tasks/close.js

@@ -0,0 +1,159 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { attachOursClient } from '@ours.network/sdk/client';
+import { withFileLock } from '../atomic-file.js';
+import { agentDir, stateRoot } from '../paths.js';
+import { readTempSupervisor, secureStoppedTempArchive, stopTempSupervisor, tempSupervisorLiveness, } from '../temp-lifecycle.js';
+import { advanceMemberRetirement, advanceRoomClose, beginRoomClose, closeRoom, getRoomRecord, setRoomCloseError, } from './room-state.js';
+const CLOSE_LOCK_STALE_MS = 5 * 60_000;
+const STOP_POLLS = 50;
+const STOP_POLL_MS = 100;
+function roomCloseLockPath(roomId) {
+    return join(stateRoot(), 'locks', 'room-close', encodeURIComponent(roomId));
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function exactMemberIdentity(seat) {
+    const dir = agentDir(seat.role_name, true);
+    const identityPath = join(dir, '.identity');
+    if (!existsSync(dir) || !existsSync(identityPath)) {
+        throw new Error(`room member '${seat.role_name}' has no live Fleet temp-state identity proof; refusing retirement`);
+    }
+    const identity = readFileSync(identityPath, 'utf8').trim();
+    if (identity !== seat.role_name) {
+        throw new Error(`room member '${seat.role_name}' temp state binds identity '${identity}'; refusing mismatched retirement`);
+    }
+}
+async function inspectMember(seat) {
+    exactMemberIdentity(seat);
+    const supervisor = readTempSupervisor(agentDir(seat.role_name, true));
+    if (!supervisor || supervisor.role !== seat.role_name) {
+        throw new Error(`room member '${seat.role_name}' has no exact Fleet supervisor ownership proof`);
+    }
+    return { launchId: supervisor.launchId };
+}
+async function waitForLivenessAbsent(role, launchId, lifecycleDeps = {}) {
+    const dir = agentDir(role, true);
+    const sleep = lifecycleDeps.sleep ?? ((ms) => new Promise(resolve => setTimeout(resolve, ms)));
+    for (let attempt = 0; attempt < STOP_POLLS; attempt++) {
+        if (!existsSync(dir))
+            return; // secureStoppedTempArchive proves the exact archive next.
+        const supervisor = readTempSupervisor(dir);
+        if (!supervisor || supervisor.role !== role || supervisor.launchId !== launchId) {
+            throw new Error(`temporary role '${role}' changed while waiting for launch ${launchId} to stop`);
+        }
+        const state = await tempSupervisorLiveness(dir, lifecycleDeps);
+        if (state === 'stopped')
+            return;
+        if (attempt < STOP_POLLS - 1)
+            await sleep(STOP_POLL_MS);
+    }
+    throw new Error(`temporary role '${role}' did not reach proven stopped liveness`);
+}
+async function withIdentityClient(work) {
+    const client = await attachOursClient({
+        env: process.env,
+        leaseToken: `ours-fleet-room-close-${process.pid}-${randomUUID()}`,
+        clientPid: process.pid,
+    });
+    try {
+        return await work(client);
+    }
+    finally {
+        await client.releaseLease().catch(() => { });
+    }
+}
+function listedIdentity(rows, name) {
+    return rows.find(row => row.name === name);
+}
+async function removeExactMemberIdentity(seat) {
+    await withIdentityClient(async (client) => {
+        const before = listedIdentity(await client.listIdentities(), seat.role_name);
+        if (!before)
+            return;
+        if (before.cid?.toLowerCase() !== seat.identity_cid.toLowerCase()) {
+            throw new Error(`room member '${seat.role_name}' identity CID mismatch: recorded ${seat.identity_cid}, found ${before.cid ?? 'none'}`);
+        }
+        try {
+            await client.removeIdentity({ name: seat.role_name });
+        }
+        catch (error) {
+            const code = error instanceof Error && error.name === 'OursError'
+                ? error.code
+                : undefined;
+            if (code !== 'NO_SUCH_IDENTITY')
+                throw error;
+            const after = listedIdentity(await client.listIdentities(), seat.role_name);
+            if (after)
+                throw error;
+        }
+        const after = listedIdentity(await client.listIdentities(), seat.role_name);
+        if (after) {
+            throw new Error(`room member '${seat.role_name}' identity still exists after remove_identity`);
+        }
+    });
+}
+async function retireMember(roomId, seat, deps) {
+    let room = getRoomRecord(roomId);
+    let current = room.member_seats.find(candidate => candidate.role_name === seat.role_name);
+    let retirement = current.retirement;
+    if (!retirement) {
+        const ownership = await (deps.inspectMember ?? inspectMember)(current);
+        room = advanceMemberRetirement(roomId, current.role_name, 'stop_requested', ownership.launchId);
+        current = room.member_seats.find(candidate => candidate.role_name === seat.role_name);
+        retirement = current.retirement;
+    }
+    if (retirement.phase === 'stop_requested') {
+        await (deps.requestStop ?? (async (role) => { await stopTempSupervisor(role); }))(current.role_name);
+        await (deps.waitForLivenessAbsent ?? waitForLivenessAbsent)(current.role_name, retirement.launch_id);
+        room = advanceMemberRetirement(roomId, current.role_name, 'liveness_absent', retirement.launch_id);
+        current = room.member_seats.find(candidate => candidate.role_name === seat.role_name);
+        retirement = current.retirement;
+    }
+    if (retirement.phase === 'liveness_absent') {
+        const archivePath = await (deps.secureArchive ?? secureStoppedTempArchive)(current.role_name, retirement.launch_id);
+        room = advanceMemberRetirement(roomId, current.role_name, 'archive_secured', retirement.launch_id, archivePath);
+        current = room.member_seats.find(candidate => candidate.role_name === seat.role_name);
+        retirement = current.retirement;
+    }
+    if (retirement.phase === 'archive_secured') {
+        await (deps.removeIdentity ?? removeExactMemberIdentity)(current);
+        advanceMemberRetirement(roomId, current.role_name, 'identity_absent', retirement.launch_id, retirement.archive_path);
+    }
+}
+/** One forward-only room close saga shared by every Fleet entry point. */
+export function acceptManagedRoomClose(roomId) {
+    return withFileLock(roomCloseLockPath(roomId), () => beginRoomClose(roomId), {}, CLOSE_LOCK_STALE_MS);
+}
+export function recordManagedRoomCloseError(roomId, error, recoveryHint) {
+    return withFileLock(roomCloseLockPath(roomId), () => setRoomCloseError(roomId, error, recoveryHint), {}, CLOSE_LOCK_STALE_MS);
+}
+export async function closeManagedRoom(input) {
+    const deps = input.deps ?? {};
+    const lock = deps.lock ?? withFileLock;
+    return lock(roomCloseLockPath(input.roomId), async () => {
+        let room = beginRoomClose(input.roomId);
+        if (room.state === 'closed')
+            return room;
+        try {
+            if (room.close?.phase === 'retire_members') {
+                for (const seat of room.member_seats) {
+                    if (seat.retirement?.phase === 'identity_absent')
+                        continue;
+                    await retireMember(input.roomId, seat, deps);
+                }
+                room = advanceRoomClose(input.roomId, 'close_cowork');
+            }
+            if (room.close?.phase === 'close_cowork') {
+                await input.cowork.closeRoom(input.roomId);
+            }
+            return closeRoom(input.roomId);
+        }
+        catch (error) {
+            setRoomCloseError(input.roomId, errorText(error), `Retry 'ours-fleet room close ${input.roomId} ${input.roomId}' or run room recover.`);
+            throw error;
+        }
+    }, {}, CLOSE_LOCK_STALE_MS);
+}

package/dist/rooms-tasks/config.d.ts

@@ -0,0 +1,15 @@
+import type { RoomsConfig, TasksConfig, RoomTemplatesConfig } from './types.js';
+export declare class RoomsTasksConfigError extends Error {
+    readonly path: string;
+    constructor(path: string, message: string);
+}
+export declare function fingerprint(invite: string): string;
+export declare function validateRoomsConfig(raw: unknown, vars: Record<string, string>, path: string): RoomsConfig & {
+    _invite?: {
+        value: string;
+        fingerprint: string;
+    };
+};
+export declare function validateTasksConfig(raw: unknown, path: string): TasksConfig;
+export declare function validateRoomTemplatesConfig(raw: unknown, path: string): RoomTemplatesConfig;
+export declare const FLEET_D_ALLOWED_KEYS: readonly ["roles", "rooms", "room_templates", "tasks"];

package/dist/rooms-tasks/config.js

@@ -0,0 +1,174 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { ROOMS_KEYS as RK, ROOMS_OWNER_KEYS as ROK, ROOMS_COWORK_KEYS as RCK, ROOMS_DEFAULTS_KEYS as RDK, TASKS_KEYS as TK, TEMPLATE_KEYS as TPK, TEMPLATE_MEMBER_KEYS as TMK, TEMPLATE_OVERRIDE_KEYS as TOK, } from './types.js';
+import { BUILTIN_TEMPLATES } from './templates.js';
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const CID_RE = /^[0-9a-fA-F]{64}$/;
+export class RoomsTasksConfigError extends Error {
+    path;
+    constructor(path, message) {
+        super(`${path}: ${message}`);
+        this.path = path;
+    }
+}
+function rejectUnknown(obj, allowed, path, section) {
+    const bad = Object.keys(obj).filter(k => !allowed.includes(k));
+    if (bad.length)
+        throw new RoomsTasksConfigError(path, `${section} has unknown key(s) ${bad.join(', ')}; allowed: ${allowed.join(', ')}`);
+}
+export function fingerprint(invite) {
+    return createHash('sha256').update(invite.trim()).digest('hex');
+}
+function resolveInvite(owner, vars, path) {
+    const inline = owner.public_invite;
+    const file = owner.public_invite_file;
+    if (inline && file)
+        throw new RoomsTasksConfigError(path, 'rooms.owner: exactly one of public_invite or public_invite_file');
+    if (!inline && !file)
+        return undefined;
+    let raw;
+    if (file) {
+        const resolved = file.replace(/\$\{(\w+)\}/g, (m, k) => (k in vars ? String(vars[k]) : m));
+        if (!existsSync(resolved))
+            throw new RoomsTasksConfigError(path, `rooms.owner.public_invite_file: not found: ${resolved}`);
+        raw = readFileSync(resolved, 'utf8').trim();
+    }
+    else {
+        raw = inline;
+    }
+    if (!raw)
+        throw new RoomsTasksConfigError(path, 'rooms.owner: invite is empty');
+    return { value: raw, fingerprint: fingerprint(raw) };
+}
+export function validateRoomsConfig(raw, vars, path) {
+    if (!isPlainObject(raw))
+        throw new RoomsTasksConfigError(path, 'rooms: must be a mapping');
+    // Migration-only input: provider selection was exposed before rooms shipped,
+    // even though cowork was the sole implementation. Accept the one historical
+    // value without carrying it into the current schema or resolved config.
+    if (Object.hasOwn(raw, 'provider') && raw.provider !== 'cowork')
+        throw new RoomsTasksConfigError(path, 'rooms.provider: only the legacy value \'cowork\' can be migrated; remove this field because ours-cowork is always used');
+    const { provider: _legacyProvider, ...current } = raw;
+    rejectUnknown(current, RK, path, 'rooms');
+    let cowork;
+    if (raw.cowork !== undefined) {
+        if (!isPlainObject(raw.cowork))
+            throw new RoomsTasksConfigError(path, 'rooms.cowork: must be a mapping');
+        rejectUnknown(raw.cowork, RCK, path, 'rooms.cowork');
+        cowork = { config: raw.cowork.config };
+    }
+    if (!isPlainObject(raw.owner))
+        throw new RoomsTasksConfigError(path, 'rooms.owner: required and must be a mapping');
+    rejectUnknown(raw.owner, ROK, path, 'rooms.owner');
+    const ownerProvider = raw.owner.provider ?? 'messenger-server';
+    const expectedCid = raw.owner.expected_cid;
+    if (!expectedCid)
+        throw new RoomsTasksConfigError(path, 'rooms.owner.expected_cid: required');
+    if (!CID_RE.test(expectedCid))
+        throw new RoomsTasksConfigError(path, 'rooms.owner.expected_cid: must be exactly 64 hexadecimal characters');
+    const ownerRole = raw.owner.role ?? 'Owner';
+    const invite = resolveInvite(raw.owner, vars, path);
+    const owner = {
+        provider: ownerProvider,
+        expected_cid: expectedCid.toLowerCase(),
+        role: ownerRole,
+        ...(raw.owner.public_invite ? { public_invite: '[REDACTED]' } : {}),
+        ...(raw.owner.public_invite_file ? { public_invite_file: raw.owner.public_invite_file } : {}),
+    };
+    let defaults;
+    if (raw.defaults !== undefined) {
+        if (!isPlainObject(raw.defaults))
+            throw new RoomsTasksConfigError(path, 'rooms.defaults: must be a mapping');
+        rejectUnknown(raw.defaults, RDK, path, 'rooms.defaults');
+        defaults = {
+            template: raw.defaults.template,
+            attach_owner: raw.defaults.attach_owner,
+            close_when_task_done: raw.defaults.close_when_task_done,
+        };
+    }
+    return { cowork, owner, defaults, _invite: invite };
+}
+export function validateTasksConfig(raw, path) {
+    if (!isPlainObject(raw))
+        throw new RoomsTasksConfigError(path, 'tasks: must be a mapping');
+    rejectUnknown(raw, TK, path, 'tasks');
+    const createMode = raw.create_mode;
+    if (createMode !== undefined && createMode !== 'start' && createMode !== 'backlog')
+        throw new RoomsTasksConfigError(path, `tasks.create_mode: must be 'start' or 'backlog'`);
+    if (raw.close_room_on_done !== undefined && typeof raw.close_room_on_done !== 'boolean')
+        throw new RoomsTasksConfigError(path, 'tasks.close_room_on_done: must be a boolean');
+    if (raw.retain_completed_for !== undefined && typeof raw.retain_completed_for !== 'string')
+        throw new RoomsTasksConfigError(path, 'tasks.retain_completed_for: must be a duration string');
+    return {
+        default_room_template: raw.default_room_template,
+        create_mode: createMode,
+        close_room_on_done: raw.close_room_on_done,
+        retain_completed_for: raw.retain_completed_for,
+    };
+}
+export function validateRoomTemplatesConfig(raw, path) {
+    if (!isPlainObject(raw))
+        throw new RoomsTasksConfigError(path, 'room_templates: must be a mapping');
+    const result = {};
+    for (const [name, tplRaw] of Object.entries(raw)) {
+        if (!/^[a-z0-9_-]+$/.test(name))
+            throw new RoomsTasksConfigError(path, `room_templates: invalid template name '${name}' (allowed: [a-z0-9_-])`);
+        if (!isPlainObject(tplRaw))
+            throw new RoomsTasksConfigError(path, `room_templates.${name}: must be a mapping`);
+        rejectUnknown(tplRaw, [...TPK, 'name'], path, `room_templates.${name}`);
+        const isBuiltinOverride = BUILTIN_TEMPLATES.some(b => b.name === name);
+        if (isBuiltinOverride && !tplRaw.override_builtin)
+            throw new RoomsTasksConfigError(path, `room_templates.${name}: overrides built-in template; set override_builtin: true and bump version`);
+        const version = tplRaw.version;
+        if (version === undefined || !Number.isInteger(version) || version < 1)
+            throw new RoomsTasksConfigError(path, `room_templates.${name}.version: required positive integer`);
+        if (!tplRaw.description || typeof tplRaw.description !== 'string')
+            throw new RoomsTasksConfigError(path, `room_templates.${name}.description: required string`);
+        if (!Array.isArray(tplRaw.members) || !tplRaw.members.length)
+            throw new RoomsTasksConfigError(path, `room_templates.${name}.members: required non-empty array`);
+        const members = tplRaw.members.map((m, i) => {
+            if (!isPlainObject(m))
+                throw new RoomsTasksConfigError(path, `room_templates.${name}.members[${i}]: must be a mapping`);
+            rejectUnknown(m, TMK, path, `room_templates.${name}.members[${i}]`);
+            if (!m.slot || typeof m.slot !== 'string')
+                throw new RoomsTasksConfigError(path, `room_templates.${name}.members[${i}].slot: required string`);
+            if (!m.role || typeof m.role !== 'string')
+                throw new RoomsTasksConfigError(path, `room_templates.${name}.members[${i}].role: required string`);
+            if (!Number.isInteger(m.count) || m.count < 1)
+                throw new RoomsTasksConfigError(path, `room_templates.${name}.members[${i}].count: required positive integer`);
+            if (!m.role_ref || typeof m.role_ref !== 'string')
+                throw new RoomsTasksConfigError(path, `room_templates.${name}.members[${i}].role_ref: required string`);
+            if (m.overrides !== undefined) {
+                if (!isPlainObject(m.overrides))
+                    throw new RoomsTasksConfigError(path, `room_templates.${name}.members[${i}].overrides: must be a mapping`);
+                rejectUnknown(m.overrides, TOK, path, `room_templates.${name}.members[${i}].overrides`);
+            }
+            return {
+                slot: m.slot,
+                role: m.role,
+                count: m.count,
+                role_ref: m.role_ref,
+                overrides: m.overrides,
+            };
+        });
+        let room;
+        if (tplRaw.room !== undefined) {
+            if (!isPlainObject(tplRaw.room))
+                throw new RoomsTasksConfigError(path, `room_templates.${name}.room: must be a mapping`);
+            room = {
+                quiet_membership: tplRaw.room.quiet_membership,
+                anonymous: tplRaw.room.anonymous,
+            };
+        }
+        result[name] = {
+            name,
+            version: version,
+            description: tplRaw.description,
+            room,
+            contract: tplRaw.contract,
+            members,
+        };
+    }
+    return result;
+}
+export const FLEET_D_ALLOWED_KEYS = ['roles', 'rooms', 'room_templates', 'tasks'];

package/dist/rooms-tasks/cowork-adapter.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Typed client for the ours-cowork v1 private management-socket protocol.
+ *
+ * Cowork owns room state. Fleet only invokes the versioned JSON RPC exposed
+ * by Cowork's Unix socket and projects the response into orchestration data.
+ */
+import type { Socket } from 'node:net';
+export interface CoworkRoomCreateResult {
+    room_id: string;
+    identity_name: string;
+    identity_cid: string;
+}
+export interface CoworkInviteAcceptResult {
+    seat_cid: string;
+    seat_state: 'pending' | 'active';
+}
+export interface CoworkInviteResult {
+    invite: string;
+    min_accepts: number;
+}
+export interface CoworkSeatInfo {
+    identity_cid: string;
+    role: string;
+    seat_state: 'pending' | 'active' | 'removed';
+}
+export interface CoworkRoomInfo {
+    room_id: string;
+    identity_name: string;
+    identity_cid: string;
+    room_name: string;
+    state: 'provisioning' | 'active' | 'closing' | 'closed';
+    seats: CoworkSeatInfo[];
+    goal?: string;
+    briefing?: string;
+}
+export interface CoworkAdapter {
+    available(): Promise<boolean>;
+    createRoom(opts: {
+        room_name: string;
+        goal: string;
+        briefing: string;
+        quiet_membership?: boolean;
+        anonymous?: boolean;
+    }): Promise<CoworkRoomCreateResult>;
+    acceptInvite(roomId: string, invite: string, opts: {
+        role: string;
+        expected_cid: string;
+    }): Promise<CoworkInviteAcceptResult>;
+    issueInvite(roomId: string, opts: {
+        role: string;
+        min_accepts: number;
+    }): Promise<CoworkInviteResult>;
+    getRoom(roomId: string): Promise<CoworkRoomInfo | undefined>;
+    listRooms(): Promise<CoworkRoomInfo[]>;
+    closeRoom(roomId: string): Promise<void>;
+    getSeats(roomId: string): Promise<CoworkSeatInfo[]>;
+    recoverRoom(roomId: string): Promise<CoworkRoomInfo>;
+}
+export declare class CoworkUnavailableError extends Error {
+    constructor(message?: string, options?: ErrorOptions);
+}
+export declare class CoworkProtocolError extends Error {
+    readonly operation: string;
+    readonly code: string;
+    constructor(operation: string, message: string, code?: string, options?: ErrorOptions);
+}
+export interface CoworkAdapterOptions {
+    configPath?: string;
+    socketPath?: string;
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+    connect?: (path: string) => Socket;
+}
+/** Resolve the same config/state inputs as ours-cowork and return its Unix socket. */
+export declare function resolveCoworkSocketPath(options?: CoworkAdapterOptions): string;
+export declare function createCoworkAdapter(options?: CoworkAdapterOptions): CoworkAdapter;