@ours.network/fleet 1.2.0-nightly.19 → 1.2.0-nightly.20

package/README.md

@@ -139,7 +139,11 @@ the caller's owner channel with the caller and spawned-role details. This is an
 honest-actor convenience and attribution path, not a security boundary; host
 shells and deliberately bypassed absolute binaries retain direct behavior.
 
-## Local web console
+## Local web API
+
+Frontend source and builds are maintained in the standalone `ours-web` repository. Fleet builds only its backend API. Configure a separately built frontend static root when serving the unified application through the gateway. The former console source is preserved there under `legacy-fleet/`.
+
+### Console API usage
 
 The interactive console is packaged with `@ours.network/fleet` and binds to
 IPv4 loopback by default. Remote or proxy exposure is always explicit:
@@ -1811,3 +1815,8 @@ recreate identities, redeem invites, or rewrite lifecycle state. Temporary room
 remain transient across host reboot; retained launch records do not restore them.
 
 See [predefined Brain models and runtime requirements](presets/README.md) for the verified model/effort matrix and regeneration instructions.
+
+### YAML room layouts
+
+Room layouts describe room composition with shared or fresh participant sessions and independent room closure.
+See [Room layouts](docs/room-layouts.md) for YAML examples and CLI commands.

package/dist/agent-ours/correspondence.d.ts

@@ -0,0 +1,10 @@
+/** Read-only operations exposed by the identity-owning supervisor. */
+export interface AgentHistoryQuery {
+    peer_cid: string;
+    limit?: number;
+    before_seq?: number;
+}
+export interface SupervisorCorrespondence {
+    contacts(): Promise<unknown>;
+    history(request: AgentHistoryQuery): Promise<unknown>;
+}

package/dist/agent-ours/correspondence.js

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

package/dist/agent-ours/runtime.d.ts

@@ -1,3 +1,4 @@
+import type { AgentHistoryQuery } from './correspondence.js';
 import type { OursClient } from '@ours.network/sdk/client';
 import { RuntimeJournal, type RuntimeState } from './state.js';
 export interface AssignedIdentity {
@@ -47,6 +48,11 @@ export declare class AgentOursRuntime {
     prepare(room?: RoomAdmission, timeoutMs?: number): Promise<void>;
     /** Admission covers SDK calls, response rendering and agent filesystem callbacks. */
     admit(): Promise<() => void>;
+    /** Trusted supervisor-only admission for a later room; keeps the live harness
+     * and original startup assignment. Not exposed as an agent lifecycle tool. */
+    joinAdditionalRoom(invite: string, expectedRoomCid: string): Promise<void>;
+    readContacts(): Promise<unknown>;
+    readHistory(request: AgentHistoryQuery): Promise<unknown>;
     startHarness<T>(start: () => Promise<T>): Promise<T>;
     suspend(): Promise<void>;
     terminal(): Promise<void>;

package/dist/agent-ours/runtime.js

@@ -201,6 +201,42 @@ export class AgentOursRuntime {
             throw error;
         }
     }
+    /** Trusted supervisor-only admission for a later room; keeps the live harness
+     * and original startup assignment. Not exposed as an agent lifecycle tool. */
+    async joinAdditionalRoom(invite, expectedRoomCid) {
+        const release = await this.admit();
+        try {
+            const contact = await this.deps.client.addContact({ invite });
+            if (contact.cid !== expectedRoomCid)
+                throw Error('ADDITIONAL_ROOM_CID_MISMATCH');
+            await this.verify();
+        }
+        finally {
+            release();
+        }
+    }
+    async readContacts() {
+        const release = await this.admit();
+        try {
+            const data = await this.deps.client.listContacts();
+            await this.verify();
+            return { identity: { name: this.state.name, cid: this.state.cid, generation: this.state.generation }, ...data };
+        }
+        finally {
+            release();
+        }
+    }
+    async readHistory(request) {
+        const release = await this.admit();
+        try {
+            const data = await this.deps.client.listHistory(request);
+            await this.verify();
+            return { identity: { name: this.state.name, cid: this.state.cid, generation: this.state.generation }, ...data };
+        }
+        finally {
+            release();
+        }
+    }
     async startHarness(start) {
         if (!this.accepting || this.state.phase !== 'READY')
             throw Error('RUNTIME_NOT_READY');

package/dist/agent-ours/service.js

@@ -1,3 +1,4 @@
+import { socketPath as privateSocketPath } from '../socket-path.js';
 import { randomBytes, randomUUID } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
@@ -207,7 +208,7 @@ export async function prepareManagedAgent(role, stateDir, temporary) {
         await identities.add(role.identity);
         const bridgeDir = join(stateDir, '.ours-bridge');
         mkdirSync(bridgeDir, { recursive: true, mode: 0o700 });
-        const capability = randomBytes(32).toString('hex'), socket = join(bridgeDir, `g${generation}.sock`);
+        const capability = randomBytes(32).toString('hex'), socket = privateSocketPath(join(bridgeDir, `g${generation}.sock`));
         const endpoint = await startMcpEndpoint({
             socket,
             capability,

package/dist/application/conversation-history.d.ts

@@ -0,0 +1,6 @@
+import type { ConversationPageView } from './session-control.js';
+/** Read the existing ACP session ledger without opening its writer/recovery store. */
+export declare function resumedConversationPage(stateDir: string, request: {
+    after?: string;
+    limit?: number;
+}, live: ConversationPageView, expectedSessionId: string): Promise<ConversationPageView>;

package/dist/application/conversation-history.js

@@ -0,0 +1,65 @@
+import { createReadStream } from 'node:fs';
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+/** Read the existing ACP session ledger without opening its writer/recovery store. */
+export async function resumedConversationPage(stateDir, request, live, expectedSessionId) {
+    let sessionId;
+    let files;
+    try {
+        sessionId = (await readFile(join(stateDir, '.acp-session-id'), 'utf8')).trim();
+        files = (await readdir(join(stateDir, '.conversation'))).filter(n => /^events-\d{6}\.jsonl$/.test(n)).sort();
+    }
+    catch {
+        return live;
+    }
+    if (!sessionId || sessionId !== expectedSessionId || !files.length)
+        return live;
+    const after = Number(request.after ?? 0);
+    if (!Number.isSafeInteger(after) || after < 0)
+        return live;
+    const limit = Math.min(1000, Math.max(1, Number.isFinite(request.limit) ? Math.floor(request.limit) : 200));
+    const events = [];
+    let next = String(after);
+    let first;
+    let hasMore = false;
+    scan: for (const file of files) {
+        const input = createReadStream(join(stateDir, '.conversation', file), { encoding: 'utf8' });
+        const lines = createInterface({ input, crlfDelay: Infinity });
+        try {
+            for await (const line of lines) {
+                let event;
+                try {
+                    event = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                const cursor = Number(event.seq);
+                if (!Number.isSafeInteger(cursor) || cursor <= after)
+                    continue;
+                const historical = ['fleet.task_created', 'prompt.admitted', 'message.chunk', 'message.replace', 'tool.upsert', 'tool.content_chunk', 'turn.completed'].includes(event.kind);
+                const visible = event.source !== 'agent_replay' && (event.sessionGeneration === live.snapshot.sessionGeneration || (historical && event.acpSessionId === sessionId));
+                if (!visible) {
+                    next = String(cursor);
+                    continue;
+                }
+                if (events.length === limit) {
+                    hasMore = true;
+                    break scan;
+                }
+                first ??= String(cursor);
+                events.push(event);
+                next = String(cursor);
+            }
+        }
+        finally {
+            lines.close();
+            input.destroy();
+        }
+    }
+    // If a fresh/resumed session changed during the read, use the live page only.
+    if ((await readFile(join(stateDir, '.acp-session-id'), 'utf8')).trim() !== sessionId)
+        return live;
+    return { ...live, events, firstAvailableCursor: first, nextCursor: next, hasMore };
+}

package/dist/application/fleet-query-service.d.ts

@@ -24,7 +24,7 @@ export declare class FleetQueryService {
     private readonly options;
     private readonly control;
     constructor(options: FleetQueryOptions);
-    list(): Promise<Array<{
+    list(includeTemporary?: boolean): Promise<Array<{
         role: RoleRecord;
         status: RoleStatus;
         capabilities: RoleCapabilities;

package/dist/application/fleet-query-service.js

@@ -75,9 +75,9 @@ export class FleetQueryService {
         this.options = options;
         this.control = options.control ?? controlRequest;
     }
-    async list() {
+    async list(includeTemporary = false) {
         const roles = (await this.options.repository.list())
-            .filter(role => role.configured && role.lifetime === 'permanent');
+            .filter(role => (role.configured && role.lifetime === 'permanent') || (includeTemporary && role.lifetime === 'temporary'));
         return Promise.all(roles.map(async (role) => {
             const status = await this.status(role);
             return { role, status, capabilities: roleCapabilities(role, status, this.options.capabilityContext) };

package/dist/application/preset-provenance.d.ts

@@ -0,0 +1,19 @@
+export declare const PROVENANCE_KINDS: {
+    readonly role: "roles";
+    readonly brain: "brains";
+    readonly template: "agent_templates";
+    readonly layout: "room_layouts";
+};
+export type ProvenanceKind = keyof typeof PROVENANCE_KINDS;
+export type ProvenanceStatus = 'predefined' | 'changed' | 'custom';
+export interface ProvenanceEntry {
+    status: ProvenanceStatus;
+    preset?: string;
+}
+export type Provenance = Record<ProvenanceKind, Record<string, ProvenanceEntry>>;
+export declare class PresetProvenance {
+    private configPath?;
+    private presetRoot;
+    constructor(configPath?: string | undefined, presetRoot?: string);
+    read(): Provenance;
+}

package/dist/application/preset-provenance.js

@@ -0,0 +1,59 @@
+/** Where each configured definition came from, compared with the packaged presets.
+ * A definition is `predefined` when it has the same value as the shipped preset of
+ * the same name, `changed` when a preset of that name exists but the value differs,
+ * and `custom` otherwise. Values are compared after parsing, so the formatting the
+ * configuration editor writes does not count as a change. Preset text is returned
+ * so users can see exactly what ships; it contains no host data.
+ */
+import { isDeepStrictEqual } from 'node:util';
+import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
+import { basename, extname, join } from 'node:path';
+import { parse } from 'yaml';
+import { defaultConfigPath } from '../paths.js';
+import { splitRootFor } from '../config.js';
+import { packagedPresetRoot } from '../preset-bootstrap.js';
+export const PROVENANCE_KINDS = { role: 'roles', brain: 'brains', template: 'agent_templates', layout: 'room_layouts' };
+const MAX_BYTES = 256 * 1024;
+/** Regular, bounded YAML files of one directory, by definition name. Anything else is skipped. */
+function yamlFiles(dir) {
+    const files = new Map();
+    if (!existsSync(dir) || !lstatSync(dir).isDirectory())
+        return files;
+    for (const file of readdirSync(dir).sort()) {
+        if (!/\.ya?ml$/.test(file))
+            continue;
+        const path = join(dir, file), stat = lstatSync(path);
+        if (!stat.isFile() || stat.size > MAX_BYTES)
+            continue;
+        files.set(basename(file, extname(file)), readFileSync(path, 'utf8'));
+    }
+    return files;
+}
+const parsed = (text) => { try {
+    return parse(text);
+}
+catch {
+    return Symbol('unparseable');
+} };
+export class PresetProvenance {
+    configPath;
+    presetRoot;
+    constructor(configPath, presetRoot = join(packagedPresetRoot(), 'fleet')) {
+        this.configPath = configPath;
+        this.presetRoot = presetRoot;
+    }
+    read() {
+        const split = splitRootFor(this.configPath ?? defaultConfigPath());
+        const result = {};
+        for (const [kind, dir] of Object.entries(PROVENANCE_KINDS)) {
+            const presets = yamlFiles(join(this.presetRoot, dir)), installed = yamlFiles(join(split, dir));
+            result[kind] = Object.fromEntries([...installed].map(([name, text]) => {
+                const preset = presets.get(name);
+                if (preset === undefined)
+                    return [name, { status: 'custom' }];
+                return [name, { status: isDeepStrictEqual(parsed(text), parsed(preset)) ? 'predefined' : 'changed', preset }];
+            }));
+        }
+        return result;
+    }
+}

package/dist/application/room-layout-definitions.d.ts

@@ -0,0 +1,45 @@
+import { loadConfig } from '../config.js';
+import { type RoomLayoutDefinition } from '../rooms-tasks/layout-config.js';
+export declare const ABSENT_REVISION = "absent";
+export type LayoutDefinitionBody = Omit<RoomLayoutDefinition, 'sourceFile'>;
+export type LayoutListEntry = {
+    name: string;
+    revision: string;
+    file: string;
+    definition: LayoutDefinitionBody;
+    issues: string[];
+    definition_hash: string;
+} | {
+    name: string;
+    revision: string;
+    file: string;
+    error: string;
+};
+export declare class RoomLayoutDefinitions {
+    private configPath?;
+    private deps;
+    constructor(configPath?: string | undefined, deps?: {
+        loadConfiguration?: typeof loadConfig;
+    });
+    private root;
+    private pathFor;
+    private currentRevision;
+    /** Agent-template references that do not resolve in the current Fleet configuration. */
+    private templateIssues;
+    /** The configured default (`rooms.defaults.template`, else `tasks.default_room_template`) when it names a usable layout. */
+    defaultLayout(entries?: LayoutListEntry[]): string | undefined;
+    list(): LayoutListEntry[];
+    validate(raw: unknown): {
+        definition?: LayoutDefinitionBody;
+        issues: string[];
+    };
+    save(name: string, expectedRevision: string, raw: unknown): Promise<{
+        name: string;
+        revision: string;
+        definition: LayoutDefinitionBody;
+    }>;
+    remove(name: string, expectedRevision: string): Promise<{
+        name: string;
+        deleted: boolean;
+    }>;
+}

package/dist/application/room-layout-definitions.js

@@ -0,0 +1,130 @@
+/** Web authoring of `fleet/room_layouts/<name>.yaml`.
+ * Writes are revision-guarded (sha256 of the file bytes) and validated with the
+ * same parser the CLI uses. Retained layout runs keep their own snapshots, so
+ * editing or deleting a definition never changes an existing run.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync } from 'node:fs';
+import { basename, extname, join } from 'node:path';
+import { stringify } from 'yaml';
+import { replaceFileAtomically, withFileLock } from '../atomic-file.js';
+import { parseFleetDocument } from '../config-yaml.js';
+import { defaultConfigPath } from '../paths.js';
+import { loadConfig, splitRootFor } from '../config.js';
+import { assertLayoutFile, validLayoutKey, validateRoomLayout } from '../rooms-tasks/layout-config.js';
+import { FleetError } from './errors.js';
+import { layoutDefinitionHash } from './task-layouts.js';
+export const ABSENT_REVISION = 'absent';
+const revisionOf = (bytes) => createHash('sha256').update(bytes).digest('hex');
+export class RoomLayoutDefinitions {
+    configPath;
+    deps;
+    constructor(configPath, deps = {}) {
+        this.configPath = configPath;
+        this.deps = deps;
+    }
+    root() { return join(splitRootFor(this.configPath ?? defaultConfigPath()), 'room_layouts'); }
+    pathFor(name) {
+        if (!validLayoutKey(name))
+            throw new FleetError('invalid_request', 'layout name must start with a letter and use letters, digits, - or _');
+        return join(this.root(), `${name}.yaml`);
+    }
+    currentRevision(path) {
+        if (!existsSync(path))
+            return ABSENT_REVISION;
+        assertLayoutFile(path);
+        return revisionOf(readFileSync(path));
+    }
+    /** Agent-template references that do not resolve in the current Fleet configuration. */
+    templateIssues(definition) {
+        let templates = {};
+        try {
+            templates = (this.deps.loadConfiguration ?? loadConfig)(this.configPath).agentTemplates ?? {};
+        }
+        catch (error) {
+            return [`fleet configuration unavailable: ${error.message}`];
+        }
+        return Object.entries(definition.participants).flatMap(([key, participant]) => participant.agent_template && !Object.hasOwn(templates, participant.agent_template)
+            ? [`participant ${key}: agent template not found: ${participant.agent_template}`] : []);
+    }
+    /** The configured default (`rooms.defaults.template`, else `tasks.default_room_template`) when it names a usable layout. */
+    defaultLayout(entries = this.list()) {
+        let name;
+        try {
+            const config = (this.deps.loadConfiguration ?? loadConfig)(this.configPath);
+            name = config.rooms?.defaults?.template ?? config.tasks?.default_room_template;
+        }
+        catch {
+            return undefined;
+        }
+        const entry = entries.find(e => e.name === name);
+        return entry && !('error' in entry) && !entry.issues.length ? entry.name : undefined;
+    }
+    list() {
+        const root = this.root();
+        if (!existsSync(root))
+            return [];
+        assertLayoutFile(root, true);
+        return readdirSync(root).filter(file => /\.ya?ml$/.test(file)).sort().map(file => {
+            const name = basename(file, extname(file)), path = join(root, file);
+            try {
+                if (!validLayoutKey(name))
+                    throw Error(`invalid room layout id: ${name}`);
+                assertLayoutFile(path);
+                const bytes = readFileSync(path);
+                const definition = validateRoomLayout(parseFleetDocument(path, bytes.toString('utf8'), 'strict').value, file);
+                return { name, file, revision: revisionOf(bytes), definition, issues: this.templateIssues(definition), definition_hash: layoutDefinitionHash(definition) };
+            }
+            catch (error) {
+                // Only a trusted regular file may be read to offer an overwrite revision.
+                let revision = ABSENT_REVISION;
+                try {
+                    assertLayoutFile(path);
+                    revision = revisionOf(readFileSync(path));
+                }
+                catch { /* not trusted: never read */ }
+                return { name, file, revision, error: error.message };
+            }
+        });
+    }
+    validate(raw) {
+        let definition;
+        try {
+            definition = validateRoomLayout(raw, 'room layout');
+        }
+        catch (error) {
+            return { issues: [error.message] };
+        }
+        return { definition, issues: this.templateIssues(definition) };
+    }
+    async save(name, expectedRevision, raw) {
+        const path = this.pathFor(name);
+        const { definition, issues } = this.validate(raw);
+        if (!definition || issues.length)
+            throw new FleetError('invalid_request', issues.join('; '));
+        const root = this.root();
+        mkdirSync(root, { recursive: true, mode: 0o700 });
+        assertLayoutFile(root, true);
+        return withFileLock(`${path}.lock`, async () => {
+            const current = this.currentRevision(path);
+            if (current !== expectedRevision)
+                throw new FleetError('stale_state', 'room layout changed since it was loaded; reload before saving');
+            const { description, participants, rooms } = definition;
+            const text = stringify({ version: 1, ...(description ? { description } : {}), participants, rooms });
+            replaceFileAtomically(path, text, 0o600);
+            return { name, revision: revisionOf(text), definition };
+        });
+    }
+    async remove(name, expectedRevision) {
+        const path = this.pathFor(name);
+        return withFileLock(`${path}.lock`, async () => {
+            const current = this.currentRevision(path);
+            if (current === ABSENT_REVISION)
+                return { name, deleted: false };
+            if (current !== expectedRevision)
+                throw new FleetError('stale_state', 'room layout changed since it was loaded; reload before deleting');
+            unlinkSync(path);
+            return { name, deleted: true };
+        });
+    }
+}

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

@@ -1,3 +1,4 @@
+import type { AgentHistoryQuery } from '../agent-ours/correspondence.js';
 import { controlRequest } from '../session/control.js';
 import type { ConversationEventV1, ConversationSnapshot, PromptReceipt } from '../session/conversation-types.js';
 import type { SessionSnapshot } from '../session/types.js';
@@ -23,6 +24,8 @@ export interface InterruptReceipt {
     reasonCode?: string;
 }
 export interface RoleSessionControl {
+    agentContacts?(): Promise<unknown>;
+    agentHistory?(request: AgentHistoryQuery): Promise<unknown>;
     describe(): Promise<SessionDescriptor>;
     snapshot(): Promise<SessionSnapshot>;
     recentOutput(request?: {
@@ -45,6 +48,7 @@ export interface RoleSessionControl {
         commandId: string;
         text: string;
         actorBrowserSession: string;
+        expectedSessionGeneration?: string;
         source: 'owner_admin_console';
     }): Promise<PromptReceipt>;
     interruptV2?(commandId: string): Promise<InterruptReceipt & {
@@ -75,6 +79,9 @@ export declare class RoleSessionControlAdapter implements RoleSessionControl {
     private readonly stateDir;
     private readonly request;
     constructor(stateDir: string, request?: typeof controlRequest);
+    agentContacts(): Promise<unknown>;
+    agentHistory(request: AgentHistoryQuery): Promise<unknown>;
+    private requireCorrespondence;
     describe(): Promise<SessionDescriptor>;
     snapshot(): Promise<SessionSnapshot>;
     recentOutput(request?: {
@@ -91,6 +98,7 @@ export declare class RoleSessionControlAdapter implements RoleSessionControl {
         commandId: string;
         text: string;
         actorBrowserSession: string;
+        expectedSessionGeneration?: string;
         source: 'owner_admin_console';
     }): Promise<PromptReceipt>;
     interruptV2(commandId: string): Promise<InterruptReceipt & {

package/dist/application/session-control.js

@@ -1,3 +1,4 @@
+import { resumedConversationPage } from './conversation-history.js';
 import { controlRequest, followConversation } from '../session/control.js';
 import { FleetError, normalizeError } from './errors.js';
 const visibleEvents = (events) => events.filter(event => event.kind !== 'thought');
@@ -8,6 +9,10 @@ export class RoleSessionControlAdapter {
         this.stateDir = stateDir;
         this.request = request;
     }
+    async agentContacts() { await this.requireCorrespondence(); return this.call('agent_contacts'); }
+    async agentHistory(request) { await this.requireCorrespondence(); return this.call('agent_history', { agentHistory: request }); }
+    async requireCorrespondence() { if (!(await this.describe()).features.includes('agent_correspondence'))
+        throw new FleetError('capability_unavailable', 'This session needs an updated supervisor to show contacts and history.'); }
     async describe() {
         const response = await this.call('snapshot');
         const result = response;
@@ -58,9 +63,20 @@ export class RoleSessionControlAdapter {
         };
     }
     async conversationPage(request = {}) {
-        return await this.call('conversation_page', {
+        const live = await this.call('conversation_page', {
             after: request.after, limit: request.limit,
         });
+        const snapshot = await this.snapshot();
+        if (snapshot.backend !== 'acp' || !snapshot.sessionId)
+            return live;
+        try {
+            const history = await resumedConversationPage(this.stateDir, request, live, snapshot.sessionId);
+            const check = await this.call('conversation_page', { limit: 1 });
+            return check.snapshot.sessionGeneration === live.snapshot.sessionGeneration ? history : await this.call('conversation_page', request);
+        }
+        catch {
+            return live;
+        }
     }
     async submitPromptV2(request) {
         if (!request.text.trim())
@@ -68,13 +84,15 @@ export class RoleSessionControlAdapter {
         if (Buffer.byteLength(request.text) > 32 * 1024)
             throw new FleetError('invalid_request', 'text exceeds 32 KiB');
         try {
-            return await this.call('submit_prompt_v2', {
+            return await this.call(request.expectedSessionGeneration ? 'submit_voice_prompt' : 'submit_prompt_v2', {
                 commandId: request.commandId, text: request.text, actor: request.actorBrowserSession,
-                source: request.source,
+                source: request.source, expectedSessionGeneration: request.expectedSessionGeneration,
             });
         }
         catch (error) {
             const fleetError = normalizeError(error);
+            if (fleetError.message.includes('session_changed:'))
+                throw new FleetError('stale_state', 'Agent session changed. Record a new voice message.');
             if (fleetError.message.includes('idempotency_conflict'))
                 throw new FleetError('idempotency_conflict', 'this command id was already used with a different prompt body');
             throw fleetError;

package/dist/application/task-layouts.d.ts

@@ -0,0 +1,89 @@
+import { type RoomLayoutDefinition } from '../rooms-tasks/layout-config.js';
+import { RoomLayoutService } from '../rooms-tasks/layout-service.js';
+import type { TaskLayoutLink, TaskRecord } from '../rooms-tasks/types.js';
+export type TaskLayoutOperation = 'open' | 'close-room' | 'close';
+export interface TaskLayoutOperationRecord {
+    /** Only the worker holding the current ID may update the record. */
+    id: string;
+    operation: TaskLayoutOperation;
+    room?: string;
+    status: 'launching' | 'running' | 'succeeded' | 'failed';
+    error?: string;
+    updated_at: string;
+}
+export interface TaskLayoutRoomView {
+    key: string;
+    goal: string;
+    members: string[];
+    roles?: Record<string, string>;
+    state: 'declared' | 'provisioning' | 'active' | 'closed';
+    room_id?: string;
+    identity_cid?: string;
+    ready: string[];
+}
+export interface TaskLayoutView {
+    name: string;
+    run_id: string;
+    created: boolean;
+    closed: boolean;
+    closing: boolean;
+    uncertain?: string;
+    rooms: TaskLayoutRoomView[];
+    participants: Array<{
+        key: string;
+        agent_template?: string;
+        owned: boolean;
+        retired: boolean;
+        agent?: string;
+        cid?: string;
+    }>;
+    operation?: TaskLayoutOperationRecord;
+}
+/** Hash of the authorable definition only (never the source file path). */
+export declare function layoutDefinitionHash(definition: RoomLayoutDefinition): string;
+/** Always-current brief for layout participants; rooms may open long after the run snapshot.
+ * It lives in Fleet's private layout state, never in the agent-writable task workspace. */
+export declare function taskBriefPath(task: Pick<TaskRecord, 'task_id'>): string;
+export declare function writeTaskBrief(task: Pick<TaskRecord, 'task_id' | 'title' | 'brief'>): void;
+/** Task context reaches every participant through the room contract (briefing text).
+ * The contract references the brief file instead of copying the brief, so later edits reach later rooms. */
+export declare function taskScopedDefinition(definition: RoomLayoutDefinition, task: Pick<TaskRecord, 'task_id' | 'title' | 'brief' | 'workspace'>): RoomLayoutDefinition;
+/** Opening rooms requires a started, live task; checked again by the worker before any side effect. */
+export declare function assertLayoutOpenable(task: TaskRecord): void;
+export declare class TaskLayouts {
+    private configPath?;
+    private deps;
+    constructor(configPath?: string | undefined, deps?: {
+        service?: RoomLayoutService;
+        launch?: (args: string[], operation: string) => Promise<void>;
+        binPath?: () => string | undefined;
+    });
+    private service;
+    private operationPath;
+    private provenancePath;
+    /** Serializes run creation, worker preconditions and deletion's removal of the run. */
+    private withTaskLock;
+    /** Resolve a layout for task creation: it must exist, parse and reference known Agent Templates. */
+    resolve(name: string): {
+        name: string;
+        definition_hash: string;
+    };
+    runExists(link: TaskLayoutLink): boolean;
+    /** Idempotent: reuse a run whose provenance matches this task, or snapshot one from the pinned source. */
+    ensureRun(task: TaskRecord, precondition?: (current: TaskRecord) => void): Promise<void>;
+    private verifyProvenance;
+    readOperation(runId: string): TaskLayoutOperationRecord | undefined;
+    /** Update only the still-current operation; a superseded or forgotten one is never resurrected. */
+    private updateOperation;
+    private writeOperation;
+    /** Sanitized read model: no Agent Template snapshots, owner fingerprints or session internals. */
+    view(task: TaskRecord): TaskLayoutView | undefined;
+    /** Accept an operation and run it in a detached worker; the outcome is recorded for polling. */
+    launch(task: TaskRecord, operation: TaskLayoutOperation, room?: string): Promise<TaskLayoutOperationRecord>;
+    /** Worker body. Errors are recorded and rethrown; unknown engine outcomes stay in run state for inspection. */
+    /** Without an ID (direct CLI use) the worker claims a new current operation. */
+    run(task: TaskRecord, operation: TaskLayoutOperation, room?: string, operationId?: string): Promise<void>;
+    private perform;
+    /** Deletion: close every layout resource, then remove the run and its operation record. */
+    closeAndForget(task: Pick<TaskRecord, 'task_id' | 'layout'>): Promise<void>;
+}