@ours.network/fleet 1.2.0-nightly.7 → 1.2.0-nightly.70

package/dist/web/control.js

@@ -1,9 +1,10 @@
+import { socketPath as privateSocketPath } from '../socket-path.js';
 import { chmodSync, mkdirSync, rmSync } from 'node:fs';
 import { createConnection, createServer } from 'node:net';
 import { join } from 'node:path';
 import { FleetError, safeLine } from '../application/errors.js';
 import { stateRoot } from '../paths.js';
-export const webControlPath = (dir = join(stateRoot(), 'web')) => join(dir, 'control.sock');
+export const webControlPath = (dir = join(stateRoot(), 'web')) => privateSocketPath(join(dir, 'control.sock'));
 export async function startWebControlServer(options) {
     const dir = options.dir ?? join(stateRoot(), 'web');
     const path = webControlPath(dir);
@@ -34,13 +35,14 @@ export async function startWebControlServer(options) {
                     if (used > rateLimit)
                         throw new FleetError('rate_limited', 'local web control rate limit exceeded');
                     const parsed = JSON.parse(body.slice(0, body.indexOf('\n')));
-                    if (parsed.command === 'open')
-                        await options.onOpen();
+                    let result;
+                    if (parsed.command === 'link-device' && options.onLinkDevice)
+                        result = await options.onLinkDevice();
                     else if (parsed.command === 'revoke-all')
                         await options.onRevokeAll();
                     else
                         throw new FleetError('invalid_request', 'unknown local web control command');
-                    socket.end(JSON.stringify({ ok: true }) + '\n');
+                    socket.end(JSON.stringify({ ok: true, result }) + '\n');
                 }
                 catch (error) {
                     const code = error instanceof FleetError ? error.code : 'internal';
@@ -65,7 +67,7 @@ export async function startWebControlServer(options) {
     };
 }
 export async function requestWebControl(command, path = webControlPath(), timeoutMs = 5_000) {
-    await new Promise((resolve, reject) => {
+    return await new Promise((resolve, reject) => {
         const socket = createConnection(path);
         let response = '';
         let settled = false;
@@ -73,7 +75,7 @@ export async function requestWebControl(command, path = webControlPath(), timeou
             socket.destroy();
             reject(new FleetError('timeout', 'local web control request timed out'));
         }, timeoutMs);
-        const finish = (error) => {
+        const finish = (error, result) => {
             if (settled)
                 return;
             settled = true;
@@ -81,7 +83,7 @@ export async function requestWebControl(command, path = webControlPath(), timeou
             if (error)
                 reject(error);
             else
-                resolve();
+                resolve(result);
         };
         socket.once('connect', () => socket.write(JSON.stringify({ command }) + '\n'));
         socket.on('data', chunk => { response += chunk.toString('utf8'); });
@@ -91,7 +93,7 @@ export async function requestWebControl(command, path = webControlPath(), timeou
                 const parsed = JSON.parse(response);
                 if (!parsed.ok)
                     throw new FleetError(parsed.error?.code === 'rate_limited' ? 'rate_limited' : 'rejected', parsed.error?.message ?? 'local web control request was rejected');
-                finish();
+                finish(undefined, parsed.result);
             }
             catch (error) {
                 finish(error);

package/dist/web/conversation-stream-codec.d.ts

@@ -0,0 +1,23 @@
+/** Public v1 wire contract. Kept free of Node APIs so browser consumers can share it. */
+export declare const MAX_FRAME_BYTES: number;
+export declare const MAX_ASSEMBLY_BYTES: number;
+export declare const MAX_PENDING_BYTES: number;
+export type ConversationRecordType = 'ready' | 'ledger' | 'state' | 'role' | 'resync' | 'keepalive';
+export interface ConversationStreamRecord {
+    version: 1;
+    type: ConversationRecordType;
+    payload: unknown;
+}
+/** A payload is the logical record; SSE/JSON envelopes do not consume its assembly budget. */
+export declare function encodeConversationRecord(type: ConversationRecordType, payload: unknown, id: string): Generator<string>;
+/** Strict incremental decoder: one assembly, no partial publication, UTF-8 split safe. */
+export declare class ConversationStreamDecoder {
+    private readonly publish;
+    private decoder;
+    private pending;
+    private assembly?;
+    constructor(publish: (record: ConversationStreamRecord) => void);
+    push(bytes: Uint8Array): void;
+    finish(): void;
+    private accept;
+}

package/dist/web/conversation-stream-codec.js

@@ -0,0 +1,110 @@
+/** Public v1 wire contract. Kept free of Node APIs so browser consumers can share it. */
+export const MAX_FRAME_BYTES = 512 * 1024;
+export const MAX_ASSEMBLY_BYTES = 16 * 1024 * 1024;
+export const MAX_PENDING_BYTES = 8 * 1024 * 1024;
+const utf8 = new TextEncoder();
+const types = new Set(['ready', 'ledger', 'state', 'role', 'resync', 'keepalive']);
+const frame = (value) => `event: conversation\ndata: ${JSON.stringify(value)}\n\n`;
+const identity = (payload) => ({ generation: payload?.sessionGeneration ?? payload?.snapshot?.sessionGeneration,
+    revision: payload?.stateRevision ?? payload?.snapshot?.stateRevision ?? payload?.roleRevision });
+/** A payload is the logical record; SSE/JSON envelopes do not consume its assembly budget. */
+export function* encodeConversationRecord(type, payload, id) {
+    const json = JSON.stringify(payload), totalBytes = utf8.encode(json).byteLength;
+    if (totalBytes > MAX_ASSEMBLY_BYTES)
+        throw new Error('conversation record exceeds assembly limit');
+    const direct = frame({ version: 1, type, payload });
+    if (utf8.encode(direct).byteLength <= MAX_FRAME_BYTES) {
+        yield direct;
+        return;
+    }
+    const position = identity(payload);
+    yield frame({ version: 1, type: 'start', id, recordType: type, totalBytes, ...position });
+    // At most 48K UTF-16 units: even worst-case JSON escapes fit a 512 KiB frame.
+    let index = 0;
+    for (let offset = 0; offset < json.length;) {
+        let end = Math.min(json.length, offset + 48 * 1024);
+        if (end < json.length && /[\uD800-\uDBFF]/.test(json[end - 1]))
+            end--;
+        yield frame({ version: 1, type: 'chunk', id, index: index++, data: json.slice(offset, end) });
+        offset = end;
+    }
+    yield frame({ version: 1, type: 'commit', id, totalBytes, ...position });
+}
+/** Strict incremental decoder: one assembly, no partial publication, UTF-8 split safe. */
+export class ConversationStreamDecoder {
+    publish;
+    decoder = new TextDecoder('utf-8', { fatal: true });
+    pending = '';
+    assembly;
+    constructor(publish) {
+        this.publish = publish;
+    }
+    push(bytes) {
+        try {
+            this.pending += this.decoder.decode(bytes, { stream: true });
+            for (;;) {
+                const end = this.pending.indexOf('\n\n');
+                if (end < 0)
+                    break;
+                const text = this.pending.slice(0, end + 2);
+                this.pending = this.pending.slice(end + 2);
+                if (utf8.encode(text).byteLength > MAX_FRAME_BYTES)
+                    throw new Error('frame limit exceeded');
+                if (!text.startsWith('event: conversation\ndata: '))
+                    throw new Error('invalid conversation frame');
+                this.accept(JSON.parse(text.slice(26, -2)));
+            }
+            if (utf8.encode(this.pending).byteLength > MAX_FRAME_BYTES)
+                throw new Error('frame limit exceeded');
+        }
+        catch (error) {
+            this.pending = '';
+            this.assembly = undefined;
+            throw error;
+        }
+    }
+    finish() {
+        const rest = this.decoder.decode();
+        if (rest || this.pending || this.assembly)
+            throw new Error('incomplete conversation stream');
+    }
+    accept(value) {
+        if (value?.version !== 1)
+            throw new Error('unsupported conversation version');
+        if (types.has(value.type)) {
+            if (this.assembly)
+                throw new Error('overlapping assembly');
+            this.publish(value);
+            return;
+        }
+        if (value.type === 'start') {
+            if (this.assembly)
+                throw new Error('overlapping assembly');
+            if (typeof value.id !== 'string' || !types.has(value.recordType) || !Number.isSafeInteger(value.totalBytes) || value.totalBytes < 1 || value.totalBytes > MAX_ASSEMBLY_BYTES)
+                throw new Error('invalid assembly length/type');
+            this.assembly = { id: value.id, type: value.recordType, total: value.totalBytes, bytes: 0, index: 0, parts: [], generation: value.generation, revision: value.revision };
+            return;
+        }
+        const assembly = this.assembly;
+        if (!assembly || value.id !== assembly.id)
+            throw new Error('assembly identity mismatch');
+        if (value.type === 'chunk') {
+            if (value.index !== assembly.index++ || typeof value.data !== 'string')
+                throw new Error('assembly chunk order');
+            if (!value.data.length)
+                throw new Error('assembly empty chunk');
+            assembly.bytes += utf8.encode(value.data).byteLength;
+            if (assembly.bytes > assembly.total)
+                throw new Error('assembly length exceeded');
+            assembly.parts.push(value.data);
+            return;
+        }
+        if (value.type !== 'commit' || value.totalBytes !== assembly.total || assembly.bytes !== assembly.total)
+            throw new Error('assembly length mismatch');
+        const payload = JSON.parse(assembly.parts.join('')), position = identity(payload);
+        if (value.generation !== assembly.generation || value.revision !== assembly.revision || position.generation !== assembly.generation || position.revision !== assembly.revision)
+            throw new Error('assembly revision mismatch');
+        this.assembly = undefined;
+        this.publish({ version: 1, type: assembly.type, payload });
+    }
+}

package/dist/web/conversation-stream.d.ts

@@ -0,0 +1,25 @@
+import type { Writable } from 'node:stream';
+import { type ConversationRecordType } from './conversation-stream-codec.js';
+/** One active logical record; only waiting encoded output consumes the pending budget. */
+export declare class ConversationStreamWriter {
+    private readonly output;
+    private readonly failed;
+    private queue;
+    private active?;
+    private waiting;
+    private ended;
+    private sequence;
+    pendingBytes: number;
+    get busy(): boolean;
+    constructor(output: Writable, failed: (reason: string) => void);
+    private error;
+    private drain;
+    send(type: ConversationRecordType, payload: unknown): boolean;
+    private flush;
+    private fail;
+    close(): void;
+}
+import type { FastifyInstance } from 'fastify';
+import type { WebServices } from './server.js';
+import type { WebAuth } from './auth.js';
+export declare function registerConversationStream(app: FastifyInstance, services: WebServices, auth: WebAuth): void;

package/dist/web/conversation-stream.js

@@ -0,0 +1,231 @@
+import { encodeConversationRecord, MAX_PENDING_BYTES } from './conversation-stream-codec.js';
+/** One active logical record; only waiting encoded output consumes the pending budget. */
+export class ConversationStreamWriter {
+    output;
+    failed;
+    queue = [];
+    active;
+    waiting = false;
+    ended = false;
+    sequence = 0;
+    pendingBytes = 0;
+    get busy() { return Boolean(this.active); }
+    constructor(output, failed) {
+        this.output = output;
+        this.failed = failed;
+        output.on('drain', this.drain);
+        output.once('error', this.error);
+    }
+    error = () => this.fail('transport-error');
+    drain = () => { this.waiting = false; this.flush(); };
+    send(type, payload) {
+        if (this.ended)
+            return false;
+        const id = String(++this.sequence);
+        try {
+            if (!this.active) {
+                this.active = encodeConversationRecord(type, payload, id);
+                this.flush();
+            }
+            else {
+                let bytes = 0;
+                for (const frame of encodeConversationRecord(type, payload, id))
+                    bytes += Buffer.byteLength(frame);
+                if (this.pendingBytes + bytes > MAX_PENDING_BYTES) {
+                    this.fail('output-overflow');
+                    return false;
+                }
+                this.queue.push({ type, payload, id, bytes });
+                this.pendingBytes += bytes;
+            }
+            return !this.ended;
+        }
+        catch {
+            this.fail('record-too-large');
+            return false;
+        }
+    }
+    flush() {
+        if (this.ended || this.waiting)
+            return;
+        try {
+            while (this.active) {
+                const next = this.active.next();
+                if (!next.done) {
+                    if (!this.output.write(next.value)) {
+                        this.waiting = true;
+                        return;
+                    }
+                }
+                else {
+                    const queued = this.queue.shift();
+                    this.active = queued ? encodeConversationRecord(queued.type, queued.payload, queued.id) : undefined;
+                    if (queued)
+                        this.pendingBytes -= queued.bytes;
+                }
+            }
+        }
+        catch {
+            this.fail('record-too-large');
+        }
+    }
+    fail(reason) {
+        if (this.ended)
+            return;
+        // A resync is only useful at a frame boundary with writable capacity.
+        if (!this.waiting && !this.output.destroyed) {
+            const frame = encodeConversationRecord('resync', { reason, capability: 'degraded', retry: reason !== 'record-too-large' }, 'terminal').next().value;
+            if (frame)
+                this.output.write(frame);
+        }
+        const blocked = this.waiting;
+        this.close();
+        this.failed(reason);
+        if (blocked)
+            this.output.destroy();
+    }
+    close() {
+        if (this.ended)
+            return;
+        this.ended = true;
+        this.active = undefined;
+        this.queue = [];
+        this.pendingBytes = 0;
+        this.output.off('drain', this.drain);
+        this.output.off('error', this.error);
+    }
+}
+import { FleetError } from '../application/errors.js';
+export function registerConversationStream(app, services, auth) {
+    const connections = new Set();
+    app.addHook('preClose', async () => { for (const close of connections)
+        close(); });
+    app.get('/api/v1/roles/:id/conversation/events', async (request, reply) => {
+        const browser = auth.authenticate(request);
+        const generation = request.query.expectedGeneration, rawAfter = request.query.after ?? '0', after = Number(rawAfter);
+        if (typeof generation !== 'string' || !generation.trim() || generation.length > 512 || !/^\d+$/.test(rawAfter) || !Number.isSafeInteger(after))
+            throw new FleetError('invalid_request', 'expectedGeneration and a nonnegative integer after cursor are required');
+        if (!services.observeRole)
+            throw new FleetError('capability_unavailable', 'Complete conversation observation is unavailable');
+        let ended = false, owner, follow;
+        let binding, timer;
+        let epoch = 0, revision = -1, lifetime, available = false;
+        let abort = new AbortController();
+        const close = () => {
+            if (ended)
+                return;
+            ended = true;
+            epoch++;
+            abort.abort();
+            if (timer)
+                clearInterval(timer);
+            binding?.();
+            writer.close();
+            follow?.close();
+            follow = undefined;
+            owner?.dispose();
+            connections.delete(close);
+            reply.raw.end();
+        };
+        const writer = new ConversationStreamWriter(reply.raw, close);
+        const resync = (reason, retry = true) => writer.send('resync', { reason, retry, capability: 'degraded' });
+        const valid = () => { if (auth.sessionValid(browser))
+            return true; writer.send('resync', { reason: 'auth-expired', retry: browser.rotating ? 'authenticate' : 'reauthenticate', capability: 'auth-expired' }); close(); return false; };
+        const stopFollow = () => { epoch++; abort.abort(); abort = new AbortController(); follow?.close(); follow = undefined; };
+        const open = async () => {
+            const current = ++epoch, signal = abort.signal;
+            const active = () => !ended && current === epoch && !signal.aborted;
+            try {
+                const control = await services.session(request.params.id);
+                if (!active() || !valid())
+                    return;
+                const descriptor = await control.describe(owner);
+                if (!active() || !valid())
+                    return;
+                if (!control.followConversation || !descriptor.features.includes('conversation_live_complete')) {
+                    resync('capability-unavailable', false);
+                    return;
+                }
+                const handle = await control.followConversation({ controller: false, expectedGeneration: generation, after, signal, roleObservation: owner,
+                    onReplay: page => { if (active() && valid()) {
+                        for (const event of page.events)
+                            writer.send('ledger', event);
+                        writer.send('ledger', { coveredThrough: page.coveredThrough });
+                    } },
+                    onReady: ready => {
+                        if (active() && valid()) {
+                            writer.send('state', ready.snapshot);
+                            writer.send('ready', { sessionGeneration: ready.snapshot.sessionGeneration, stateRevision: ready.snapshot.stateRevision,
+                                ledgerBarrier: ready.snapshot.ledgerBarrier, coveredThrough: ready.coveredThrough, capability: 'complete', authorizedUntil: browser.absoluteExpiresAt });
+                        }
+                    },
+                    onEvent: event => { if (active() && valid()) {
+                        writer.send('ledger', event);
+                        writer.send('ledger', { coveredThrough: event.seq });
+                    } },
+                    onState: state => { if (active() && valid())
+                        writer.send('state', state); },
+                    onClose: reason => { if (active()) {
+                        epoch++;
+                        abort.abort();
+                        follow = undefined;
+                        resync(reason ?? 'control-closed', !reason?.includes('assembly limit'));
+                    } },
+                });
+                if (!active())
+                    handle.close();
+                else
+                    follow = handle;
+            }
+            catch {
+                if (active())
+                    resync('observation-unavailable');
+            }
+        };
+        const changed = (state) => {
+            if (ended || state.roleRevision <= revision)
+                return;
+            revision = state.roleRevision;
+            const { stateDir: _private, ...publicState } = state;
+            writer.send('role', publicState);
+            const replaced = lifetime !== undefined && lifetime !== state.roleLifetime;
+            const nextAvailable = state.availability === 'available' && state.health === 'healthy';
+            if (replaced || !nextAvailable)
+                stopFollow();
+            if (state.health !== 'healthy')
+                resync(state.failure ?? 'role-observation-unavailable', state.health !== 'unsupported');
+            else if (replaced)
+                resync('role-replaced');
+            const shouldOpen = nextAvailable && (!available || replaced);
+            lifetime = state.roleLifetime;
+            available = nextAvailable;
+            if (shouldOpen)
+                void open();
+        };
+        reply.hijack();
+        for (const [name, value] of Object.entries(reply.getHeaders()))
+            if (value !== undefined)
+                reply.raw.setHeader(name, Array.isArray(value) ? value : String(value));
+        reply.raw.writeHead(200, { 'Content-Type': 'text/event-stream; charset=utf-8', 'Cache-Control': 'no-store', 'X-Accel-Buffering': 'no' });
+        reply.raw.flushHeaders();
+        reply.raw.once('close', close);
+        connections.add(close);
+        binding = auth.bindTransport(browser, () => { writer.send('resync', { reason: 'auth-expired', capability: 'auth-expired', retry: browser.rotating ? 'authenticate' : 'reauthenticate' }); close(); });
+        try {
+            // Factory callbacks can be synchronous; defer handling until the owner can be borrowed.
+            owner = services.observeRole(request.params.id, state => queueMicrotask(() => changed(state)));
+            if (ended) {
+                owner.dispose();
+                return;
+            }
+            changed(owner.snapshot());
+            timer = setInterval(() => { if (valid())
+                writer.send('keepalive', { at: Date.now() }); }, 1_000);
+            timer.unref();
+        }
+        catch {
+            resync('role-observation-unavailable');
+            close();
+        }
+    });
+}

package/dist/web/fleet-config-service.d.ts

@@ -4,6 +4,9 @@ export interface EditableFleetModel {
     manifest: Record<string, unknown>;
     agents: Record<string, Record<string, unknown>>;
     agent_templates: Record<string, Record<string, unknown>>;
+    roles?: Record<string, Record<string, unknown>>;
+    brains?: Record<string, Record<string, unknown>>;
+    room_templates?: Record<string, Record<string, unknown>>;
 }
 export interface ConfigReadResult {
     path: string;
@@ -45,7 +48,7 @@ export declare class FleetConfigService {
     private readonly preflight;
     private readonly beforeMutation?;
     constructor(options?: FleetConfigServiceOptions);
-    read(): ConfigReadResult;
+    read(includeDefinitions?: boolean): ConfigReadResult;
     preview(baseRevision: string, input: unknown): Promise<ConfigPreviewResult>;
     write(baseRevision: string, input: unknown): Promise<ConfigWriteResult>;
 }

package/dist/web/fleet-config-service.js

@@ -23,7 +23,7 @@ export class FleetConfigService {
         this.preflight = options.preflight ?? (async () => emptyReport());
         this.beforeMutation = options.beforeMutation;
     }
-    read() {
+    read(includeDefinitions = false) {
         const sources = readSources(this.path);
         try {
             loadConfig(this.path, { yamlMode: 'strict' });
@@ -31,7 +31,7 @@ export class FleetConfigService {
         catch (error) {
             throw safeError(error, sourceSensitiveValues(sources));
         }
-        const raw = modelFrom(sources);
+        const raw = modelFrom(sources, includeDefinitions);
         const redacted = redactModel(raw);
         return {
             path: basename(this.path), exists: true, firstRun: false,
@@ -41,7 +41,7 @@ export class FleetConfigService {
     async preview(baseRevision, input) {
         const current = readSources(this.path);
         assertRevision(baseRevision, current);
-        const currentModel = modelFrom(current);
+        const currentModel = modelFrom(current, !!input && typeof input === 'object' && 'roles' in input);
         const next = restoreRedactions(assertModel(input), currentModel, new Set(redactModel(currentModel).paths));
         const proposal = renderProposal(current, next);
         const staged = stageProposal(this.path, current, proposal);
@@ -63,7 +63,7 @@ export class FleetConfigService {
         return withFileLock(`${splitRootFor(this.path)}.web-edit.lock`, async () => {
             const current = readSources(this.path);
             assertRevision(baseRevision, current);
-            const currentModel = modelFrom(current);
+            const currentModel = modelFrom(current, !!input && typeof input === 'object' && 'roles' in input);
             const next = restoreRedactions(assertModel(input), currentModel, new Set(redactModel(currentModel).paths));
             const proposal = renderProposal(current, next);
             const changed = changedDocuments(current, proposal);
@@ -105,6 +105,8 @@ export class FleetConfigService {
                         rmSync(target, { force: true });
                     else {
                         assertWritableTarget(target, current.documents.has(rel));
+                        mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
+                        trustedDirectory(dirname(target));
                         replaceFileAtomically(target, contents, 0o600);
                         chmodSync(target, 0o600);
                     }
@@ -184,7 +186,7 @@ function readSources(manifest) {
     }
     return { manifest, root, documents };
 }
-function modelFrom(sources) {
+function modelFrom(sources, includeDefinitions = false) {
     const manifestKey = basename(sources.manifest);
     const manifest = parseFleetDocument(sources.manifest, sources.documents.get(manifestKey), 'strict').value;
     const agents = {};
@@ -199,15 +201,24 @@ function modelFrom(sources) {
             const id = basename(rel, extname(rel));
             agent_templates[id] = parseFleetDocument(absoluteFor(sources.manifest, rel), source, 'strict').value;
         }
-    return { manifest, agents, agent_templates };
+    const model = { manifest, agents, agent_templates };
+    if (includeDefinitions)
+        for (const kind of ['roles', 'brains', 'room_templates']) {
+            model[kind] = {};
+            for (const [rel, source] of sources.documents)
+                if (rel.startsWith(kind + '/') && ['.yaml', '.yml'].includes(extname(rel))) {
+                    model[kind][basename(rel, extname(rel))] = parseFleetDocument(absoluteFor(sources.manifest, rel), source, 'strict').value;
+                }
+        }
+    return model;
 }
 function assertModel(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         throw new FleetError('invalid_request', 'model must be an object');
     const input = value;
-    if (Object.keys(input).sort().join(',') !== 'agent_templates,agents,manifest')
-        throw new FleetError('invalid_request', 'model allows exactly manifest, agents, and agent_templates');
-    for (const key of ['manifest', 'agents', 'agent_templates'])
+    if (!['agent_templates,agents,manifest', 'agent_templates,agents,brains,manifest,roles,room_templates'].includes(Object.keys(input).sort().join(',')))
+        throw new FleetError('invalid_request', 'model requires manifest, agents, agent_templates and optionally all definition collections');
+    for (const key of Object.keys(input))
         if (!input[key] || typeof input[key] !== 'object' || Array.isArray(input[key]))
             throw new FleetError('invalid_request', `${key} must be an object`);
     for (const [id, doc] of Object.entries(input.agents)) {
@@ -222,6 +233,14 @@ function assertModel(value) {
         if (!doc || typeof doc !== 'object' || Array.isArray(doc))
             throw new FleetError('invalid_request', `Agent Template '${id}' must be an object`);
     }
+    for (const kind of ['roles', 'brains', 'room_templates']) {
+        for (const [id, doc] of Object.entries((input[kind] ?? {}))) {
+            if (!ROLE_NAME_RE.test(id))
+                throw new FleetError('invalid_request', `invalid definition ID '${id}'`);
+            if (!doc || typeof doc !== 'object' || Array.isArray(doc))
+                throw new FleetError('invalid_request', `definition '${id}' must be an object`);
+        }
+    }
     return structuredClone(input);
 }
 function renderProposal(current, model) {
@@ -240,9 +259,21 @@ function renderProposal(current, model) {
         next.set(oldRel ?? join('agent_templates', `${id}.yaml`), oldRel
             ? render(current.documents.get(oldRel), doc) : stringify(doc));
     }
-    for (const [rel, source] of current.documents)
-        if (rel.startsWith('roles/') || rel.startsWith('brains/') || rel.startsWith('room_templates/'))
-            next.set(rel, source);
+    for (const kind of ['roles', 'brains', 'room_templates']) {
+        if (model[kind] === undefined) {
+            for (const [rel, source] of current.documents)
+                if (rel.startsWith(kind + '/'))
+                    next.set(rel, source);
+            continue;
+        }
+        for (const [rel, source] of current.documents)
+            if (rel.startsWith(kind + '/') && !['.yaml', '.yml'].includes(extname(rel)))
+                next.set(rel, source);
+        for (const [id, doc] of Object.entries(model[kind])) {
+            const oldRel = [...current.documents.keys()].find(rel => rel.startsWith(kind + '/') && ['.yaml', '.yml'].includes(extname(rel)) && basename(rel, extname(rel)) === id);
+            next.set(oldRel ?? join(kind, `${id}.yaml`), oldRel ? render(current.documents.get(oldRel), doc) : stringify(doc));
+        }
+    }
     return next;
 }
 function render(source, model) {
@@ -395,9 +426,9 @@ function sourceDiff(before, after, label, secrets) {
         ...left.slice(left.length - tail, left.length - tail + trailing).map(x => ` ${x}`), ''].join('\n');
 }
 function proposalDiff(current, proposal) {
-    const secrets = sensitiveValues(modelFrom(current));
+    const secrets = sensitiveValues(modelFrom(current, true));
     try {
-        secrets.push(...sensitiveValues(modelFrom({ ...current, documents: proposal })));
+        secrets.push(...sensitiveValues(modelFrom({ ...current, documents: proposal }, true)));
     }
     catch { /* validation reports later */ }
     return [...new Set([...current.documents.keys(), ...proposal.keys()])].sort().map(rel => sourceDiff(current.documents.get(rel) ?? '', proposal.get(rel) ?? '', rel, secrets)).filter(Boolean).join('\n');
@@ -405,7 +436,7 @@ function proposalDiff(current, proposal) {
 function splitLines(source) { return source.replace(/\n$/, '').split('\n'); }
 function restartImpact(before, after) {
     const roles = [...new Set([...Object.keys(before.agents), ...Object.keys(after.agents)])]
-        .filter(id => JSON.stringify(before.agents[id]) !== JSON.stringify(after.agents[id])).sort();
+        .filter(id => JSON.stringify(before.agents[id]) !== JSON.stringify(after.agents[id]) || JSON.stringify(before.roles) !== JSON.stringify(after.roles) || JSON.stringify(before.brains) !== JSON.stringify(after.brains)).sort();
     const watchdogScheduler = JSON.stringify(before.manifest.watchdogs) !== JSON.stringify(after.manifest.watchdogs);
     const scheduledLoops = JSON.stringify(before.manifest.loops) !== JSON.stringify(after.manifest.loops);
     const required = roles.length > 0 || watchdogScheduler || scheduledLoops;

package/dist/web/prefix-gateway.d.ts

@@ -0,0 +1,32 @@
+import type { AuditSink } from './audit.js';
+import { type IncomingMessage } from 'node:http';
+import type { WebAuth } from './auth.js';
+/** Each entry exposes one dedicated backend listener. Endpoint dispatch stays upstream. */
+export interface ServiceTarget {
+    prefix: string;
+    origin: string;
+    upstreamPrefix?: string;
+    /** Server-side service credentials; never taken from browser headers. */
+    headers?: Record<string, string>;
+    /** Dedicated credential-authenticated services reject direct browser context. */
+    stripBrowserContext?: boolean;
+    /**
+     * Service paths (below the prefix) where the account App may open a WebSocket with its device
+     * credential. A browser cannot set Authorization on a WebSocket, so only there it is accepted
+     * as a subprotocol.
+     */
+    deviceSocketPaths?: string[];
+}
+export interface GatewayOptions {
+    /** Backend mode is for a separate loopback machine-client listener; browsers are rejected. */
+    auth: WebAuth | 'backend';
+    fleetOrigin: string;
+    services: ServiceTarget[];
+    /** Bounded unauthorized-response diagnostics: fixed service/action enums only. */
+    audit?: Pick<AuditSink, 'record'>;
+}
+/** Raw transport deliberately runs outside Fastify's JSON parser and body limits. */
+export declare function createPrefixGateway(options: GatewayOptions): {
+    server: import("http").Server<typeof IncomingMessage, typeof import("http").ServerResponse>;
+    close(): Promise<void>;
+};