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

package/dist/rooms-tasks/config.js

@@ -0,0 +1,171 @@
+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');
+    rejectUnknown(raw, RK, path, 'rooms');
+    const provider = raw.provider ?? 'cowork';
+    if (provider !== 'cowork')
+        throw new RoomsTasksConfigError(path, `rooms.provider: unsupported '${provider}'; allowed: cowork`);
+    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 { provider, 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,80 @@
+/**
+ * Cowork private management-socket adapter.
+ *
+ * Fleet orchestrates tasks/rooms but Cowork owns room state. This adapter
+ * communicates with Cowork via its Unix management socket using versioned
+ * JSON RPC. All methods fail closed: if Cowork is unreachable or returns
+ * an unexpected response, the operation fails rather than guessing.
+ *
+ * BLOCKED: The management socket protocol is defined in ours-cowork but
+ * the exact prerelease wire format needs verification. This adapter
+ * defines the interface Fleet needs and provides a fail-closed stub
+ * that reports the blocker. Replace the stub with socket calls once
+ * the Cowork management socket contract is verified.
+ */
+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>;
+    acceptAsIdentity(roomId: string, invite: string, identityCid: string, opts: {
+        role: string;
+    }): Promise<CoworkInviteAcceptResult>;
+    getRoom(roomId: string): Promise<CoworkRoomInfo | undefined>;
+    listRooms(): Promise<CoworkRoomInfo[]>;
+    closeRoom(roomId: string): Promise<void>;
+    getSeats(roomId: string): Promise<CoworkSeatInfo[]>;
+}
+export declare class CoworkUnavailableError extends Error {
+    constructor(message?: string);
+}
+export declare class CoworkProtocolError extends Error {
+    readonly operation: string;
+    constructor(operation: string, message: string);
+}
+/**
+ * Fail-closed stub adapter. Every method throws CoworkUnavailableError.
+ * This is the correct behavior until the Cowork management socket
+ * integration is verified against the prerelease wire format.
+ */
+export declare function createStubAdapter(): CoworkAdapter;

package/dist/rooms-tasks/cowork-adapter.js

@@ -0,0 +1,48 @@
+/**
+ * Cowork private management-socket adapter.
+ *
+ * Fleet orchestrates tasks/rooms but Cowork owns room state. This adapter
+ * communicates with Cowork via its Unix management socket using versioned
+ * JSON RPC. All methods fail closed: if Cowork is unreachable or returns
+ * an unexpected response, the operation fails rather than guessing.
+ *
+ * BLOCKED: The management socket protocol is defined in ours-cowork but
+ * the exact prerelease wire format needs verification. This adapter
+ * defines the interface Fleet needs and provides a fail-closed stub
+ * that reports the blocker. Replace the stub with socket calls once
+ * the Cowork management socket contract is verified.
+ */
+export class CoworkUnavailableError extends Error {
+    constructor(message = 'Cowork management socket is not reachable') {
+        super(message);
+    }
+}
+export class CoworkProtocolError extends Error {
+    operation;
+    constructor(operation, message) {
+        super(`cowork ${operation}: ${message}`);
+        this.operation = operation;
+    }
+}
+/**
+ * Fail-closed stub adapter. Every method throws CoworkUnavailableError.
+ * This is the correct behavior until the Cowork management socket
+ * integration is verified against the prerelease wire format.
+ */
+export function createStubAdapter() {
+    const unavailable = (op) => {
+        throw new CoworkUnavailableError(`Cowork adapter not yet connected: ${op}. ` +
+            'Blocker: Cowork management socket wire format must be verified against ours-cowork/prerelease.');
+    };
+    return {
+        async available() { return false; },
+        async createRoom() { return unavailable('createRoom'); },
+        async acceptInvite() { return unavailable('acceptInvite'); },
+        async issueInvite() { return unavailable('issueInvite'); },
+        async acceptAsIdentity() { return unavailable('acceptAsIdentity'); },
+        async getRoom() { return unavailable('getRoom'); },
+        async listRooms() { return unavailable('listRooms'); },
+        async closeRoom() { return unavailable('closeRoom'); },
+        async getSeats() { return unavailable('getSeats'); },
+    };
+}

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

@@ -0,0 +1,7 @@
+export * from './types.js';
+export * from './templates.js';
+export * from './config.js';
+export * from './task-state.js';
+export * from './room-state.js';
+export * from './cowork-adapter.js';
+export { registerTemplateCommands, registerTaskCommands, registerRoomCommands } from './cli.js';

package/dist/rooms-tasks/index.js

@@ -0,0 +1,7 @@
+export * from './types.js';
+export * from './templates.js';
+export * from './config.js';
+export * from './task-state.js';
+export * from './room-state.js';
+export * from './cowork-adapter.js';
+export { registerTemplateCommands, registerTaskCommands, registerRoomCommands } from './cli.js';

package/dist/rooms-tasks/room-state.d.ts

@@ -0,0 +1,22 @@
+import type { RoomOrchestrationRecord, RoomOrchestrationState, SagaPhase, RoomMemberSeat, ProvisioningDetail } from './types.js';
+export declare const roomsDir: () => string;
+export declare class RoomStateError extends Error {
+}
+export interface CreateRoomInput {
+    room_id: string;
+    room_name: string;
+    task_id?: string;
+    template_snapshot?: import('./types.js').TemplateSnapshot;
+}
+export declare function createRoomRecord(input: CreateRoomInput): RoomOrchestrationRecord;
+export declare function getRoomRecord(id: string): RoomOrchestrationRecord | undefined;
+export declare function listRoomRecords(filter?: {
+    state?: RoomOrchestrationState | RoomOrchestrationState[];
+}): RoomOrchestrationRecord[];
+export declare function advanceSaga(id: string, phase: SagaPhase, stepIndex?: number, detail?: ProvisioningDetail): RoomOrchestrationRecord;
+export declare function setSagaError(id: string, error: string, hint?: string, detail?: ProvisioningDetail): RoomOrchestrationRecord;
+export declare function setRoomIdentity(id: string, roomIdentityCid: string): RoomOrchestrationRecord;
+export declare function setOwnerSeat(id: string, ownerSeatCid: string, inviteFingerprint: string): RoomOrchestrationRecord;
+export declare function updateMemberSeats(id: string, seats: RoomMemberSeat[]): RoomOrchestrationRecord;
+export declare function activateRoom(id: string): RoomOrchestrationRecord;
+export declare function closeRoom(id: string): RoomOrchestrationRecord;

package/dist/rooms-tasks/room-state.js

@@ -0,0 +1,117 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { replaceFileAtomically } from '../atomic-file.js';
+import { stateRoot } from '../paths.js';
+export const roomsDir = () => join(stateRoot(), 'rooms');
+function roomPath(id) { return join(roomsDir(), `${id}.json`); }
+export class RoomStateError extends Error {
+}
+function readRoom(id) {
+    const p = roomPath(id);
+    if (!existsSync(p))
+        throw new RoomStateError(`room not found: ${id}`);
+    return JSON.parse(readFileSync(p, 'utf8'));
+}
+function writeRoom(record) {
+    mkdirSync(roomsDir(), { recursive: true });
+    replaceFileAtomically(roomPath(record.room_id), JSON.stringify(record, null, 2) + '\n');
+}
+export function createRoomRecord(input) {
+    const existing = getRoomRecord(input.room_id);
+    if (existing)
+        return existing;
+    const record = {
+        room_id: input.room_id,
+        room_name: input.room_name,
+        task_id: input.task_id,
+        template_snapshot: input.template_snapshot,
+        saga: { phase: 'persist_intent', step_index: 0 },
+        member_seats: [],
+        state: 'provisioning',
+        created_at: new Date().toISOString(),
+    };
+    writeRoom(record);
+    return record;
+}
+export function getRoomRecord(id) {
+    try {
+        return readRoom(id);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function listRoomRecords(filter) {
+    const dir = roomsDir();
+    if (!existsSync(dir))
+        return [];
+    const states = filter?.state
+        ? (Array.isArray(filter.state) ? filter.state : [filter.state])
+        : undefined;
+    const rooms = [];
+    for (const f of readdirSync(dir).filter(f => f.endsWith('.json'))) {
+        try {
+            const r = JSON.parse(readFileSync(join(dir, f), 'utf8'));
+            if (!states || states.includes(r.state))
+                rooms.push(r);
+        }
+        catch { /* skip corrupt */ }
+    }
+    return rooms.sort((a, b) => a.created_at.localeCompare(b.created_at));
+}
+export function advanceSaga(id, phase, stepIndex, detail) {
+    const r = readRoom(id);
+    r.saga = { phase, step_index: stepIndex ?? 0 };
+    if (detail)
+        r.provisioning_detail = detail;
+    else
+        delete r.provisioning_detail;
+    writeRoom(r);
+    return r;
+}
+export function setSagaError(id, error, hint, detail) {
+    const r = readRoom(id);
+    r.saga.error = error;
+    r.saga.recovery_hint = hint;
+    if (detail)
+        r.provisioning_detail = detail;
+    writeRoom(r);
+    return r;
+}
+export function setRoomIdentity(id, roomIdentityCid) {
+    const r = readRoom(id);
+    r.room_identity_cid = roomIdentityCid;
+    writeRoom(r);
+    return r;
+}
+export function setOwnerSeat(id, ownerSeatCid, inviteFingerprint) {
+    const r = readRoom(id);
+    r.owner_seat_cid = ownerSeatCid;
+    r.owner_invite_fingerprint = inviteFingerprint;
+    writeRoom(r);
+    return r;
+}
+export function updateMemberSeats(id, seats) {
+    const r = readRoom(id);
+    r.member_seats = seats;
+    writeRoom(r);
+    return r;
+}
+export function activateRoom(id) {
+    const r = readRoom(id);
+    r.state = 'active';
+    r.saga = { phase: 'completed', step_index: 0 };
+    delete r.provisioning_detail;
+    r.activated_at = new Date().toISOString();
+    writeRoom(r);
+    return r;
+}
+export function closeRoom(id) {
+    const r = readRoom(id);
+    if (r.state === 'closed')
+        return r;
+    r.state = 'closed';
+    r.closed_at = new Date().toISOString();
+    writeRoom(r);
+    return r;
+}

package/dist/rooms-tasks/task-state.d.ts

@@ -0,0 +1,31 @@
+import type { TaskRecord, TaskState, TaskOrigin, TaskTemplateRef, TaskOutcome, TaskMemberRole } from './types.js';
+export declare const tasksDir: () => string;
+export declare class TaskStateError extends Error {
+}
+export interface CreateTaskInput {
+    title: string;
+    brief?: string;
+    brief_file?: string;
+    template?: TaskTemplateRef;
+    origin: TaskOrigin;
+    idempotency_key?: string;
+    start?: boolean;
+    room_id?: string;
+}
+export declare function createTask(input: CreateTaskInput): TaskRecord;
+export declare function getTask(id: string): TaskRecord;
+export declare function listTasks(filter?: {
+    state?: TaskState | TaskState[];
+}): TaskRecord[];
+export declare function findByIdempotencyKey(key: string): TaskRecord | undefined;
+export declare function startTask(id: string): TaskRecord;
+export declare function activateTask(id: string): TaskRecord;
+export declare function blockTask(id: string, reason: string): TaskRecord;
+export declare function unblockTask(id: string): TaskRecord;
+export declare function reviewTask(id: string): TaskRecord;
+export declare function completeTask(id: string, outcome?: TaskOutcome): TaskRecord;
+export declare function cancelTask(id: string): TaskRecord;
+export declare function failTask(id: string, error: string): TaskRecord;
+export declare function updateTaskRoom(id: string, roomId: string, roomIdentityCid: string): TaskRecord;
+export declare function updateTaskMembers(id: string, members: TaskMemberRole[]): TaskRecord;
+export declare function deleteTask(id: string): void;

package/dist/rooms-tasks/task-state.js

@@ -0,0 +1,173 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { replaceFileAtomically } from '../atomic-file.js';
+import { stateRoot } from '../paths.js';
+import { TASK_TERMINAL_STATES, TASK_CANCELLABLE_STATES } from './types.js';
+export const tasksDir = () => join(stateRoot(), 'tasks');
+function taskPath(id) { return join(tasksDir(), `${id}.json`); }
+function generateTaskId() {
+    const ts = Date.now().toString(36).padStart(9, '0');
+    const rand = randomUUID().replace(/-/g, '').slice(0, 8);
+    return `${ts}${rand}`;
+}
+export class TaskStateError extends Error {
+}
+function readTask(id) {
+    const p = taskPath(id);
+    if (!existsSync(p))
+        throw new TaskStateError(`task not found: ${id}`);
+    return JSON.parse(readFileSync(p, 'utf8'));
+}
+function writeTask(record) {
+    mkdirSync(tasksDir(), { recursive: true });
+    replaceFileAtomically(taskPath(record.task_id), JSON.stringify(record, null, 2) + '\n');
+}
+// ── Lifecycle transitions ───────────────────────────────────────────────
+const VALID_TRANSITIONS = {
+    backlog: ['provisioning', 'cancelled'],
+    provisioning: ['active', 'failed', 'cancelled'],
+    active: ['review', 'failed', 'cancelled'],
+    review: ['done', 'failed', 'cancelled'],
+    done: [],
+    cancelled: [],
+    failed: [],
+};
+function assertTransition(from, to) {
+    if (!VALID_TRANSITIONS[from].includes(to))
+        throw new TaskStateError(`cannot transition from '${from}' to '${to}'`);
+}
+export function createTask(input) {
+    const key = input.idempotency_key ?? randomUUID();
+    const existing = findByIdempotencyKey(key);
+    if (existing)
+        return existing;
+    const state = input.start === false ? 'backlog' : 'provisioning';
+    const record = {
+        task_id: generateTaskId(),
+        title: input.title,
+        brief: input.brief,
+        brief_file: input.brief_file,
+        state,
+        template: input.template,
+        room_id: input.room_id,
+        member_roles: [],
+        origin: input.origin,
+        idempotency_key: key,
+        created_at: new Date().toISOString(),
+        started_at: state === 'provisioning' ? new Date().toISOString() : undefined,
+    };
+    writeTask(record);
+    return record;
+}
+export function getTask(id) { return readTask(id); }
+export function listTasks(filter) {
+    const dir = tasksDir();
+    if (!existsSync(dir))
+        return [];
+    const states = filter?.state
+        ? (Array.isArray(filter.state) ? filter.state : [filter.state])
+        : undefined;
+    const tasks = [];
+    for (const f of readdirSync(dir).filter(f => f.endsWith('.json'))) {
+        try {
+            const t = JSON.parse(readFileSync(join(dir, f), 'utf8'));
+            if (!states || states.includes(t.state))
+                tasks.push(t);
+        }
+        catch { /* corrupt file, skip */ }
+    }
+    return tasks.sort((a, b) => a.created_at.localeCompare(b.created_at));
+}
+export function findByIdempotencyKey(key) {
+    return listTasks().find(t => t.idempotency_key === key);
+}
+export function startTask(id) {
+    const t = readTask(id);
+    assertTransition(t.state, 'provisioning');
+    t.state = 'provisioning';
+    t.started_at = new Date().toISOString();
+    writeTask(t);
+    return t;
+}
+export function activateTask(id) {
+    const t = readTask(id);
+    assertTransition(t.state, 'active');
+    t.state = 'active';
+    delete t.blocked;
+    writeTask(t);
+    return t;
+}
+export function blockTask(id, reason) {
+    const t = readTask(id);
+    if (TASK_TERMINAL_STATES.includes(t.state))
+        throw new TaskStateError(`cannot block a '${t.state}' task`);
+    t.blocked = { reason, at: new Date().toISOString() };
+    writeTask(t);
+    return t;
+}
+export function unblockTask(id) {
+    const t = readTask(id);
+    if (!t.blocked)
+        throw new TaskStateError('task is not blocked');
+    delete t.blocked;
+    writeTask(t);
+    return t;
+}
+export function reviewTask(id) {
+    const t = readTask(id);
+    assertTransition(t.state, 'review');
+    t.state = 'review';
+    delete t.blocked;
+    writeTask(t);
+    return t;
+}
+export function completeTask(id, outcome) {
+    const t = readTask(id);
+    assertTransition(t.state, 'done');
+    t.state = 'done';
+    t.ended_at = new Date().toISOString();
+    delete t.blocked;
+    if (outcome)
+        t.outcome = outcome;
+    writeTask(t);
+    return t;
+}
+export function cancelTask(id) {
+    const t = readTask(id);
+    if (!TASK_CANCELLABLE_STATES.includes(t.state))
+        throw new TaskStateError(`cannot cancel a '${t.state}' task`);
+    t.state = 'cancelled';
+    t.ended_at = new Date().toISOString();
+    delete t.blocked;
+    writeTask(t);
+    return t;
+}
+export function failTask(id, error) {
+    const t = readTask(id);
+    assertTransition(t.state, 'failed');
+    t.state = 'failed';
+    t.ended_at = new Date().toISOString();
+    t.outcome = { summary: error };
+    delete t.blocked;
+    writeTask(t);
+    return t;
+}
+export function updateTaskRoom(id, roomId, roomIdentityCid) {
+    const t = readTask(id);
+    t.room_id = roomId;
+    t.room_identity_cid = roomIdentityCid;
+    writeTask(t);
+    return t;
+}
+export function updateTaskMembers(id, members) {
+    const t = readTask(id);
+    t.member_roles = members;
+    writeTask(t);
+    return t;
+}
+export function deleteTask(id) {
+    const p = taskPath(id);
+    if (existsSync(p))
+        rmSync(p);
+}

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

@@ -0,0 +1,6 @@
+import type { TemplateDefinition, TemplateSnapshot } from './types.js';
+export declare const BUILTIN_TEMPLATES: readonly TemplateDefinition[];
+export declare function hashTemplate(t: TemplateDefinition): string;
+export declare function snapshotTemplate(t: TemplateDefinition): TemplateSnapshot;
+export declare function resolveTemplate(name: string, customTemplates: Record<string, TemplateDefinition>): TemplateDefinition | undefined;
+export declare function listTemplates(customTemplates: Record<string, TemplateDefinition>): TemplateDefinition[];