@ours.network/fleet 1.2.0-nightly.9 → 2.0.0

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,26 @@
+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;
+    private lastQualifyingOutputAt;
+    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,239 @@
+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;
+    lastQualifyingOutputAt = Date.now();
+    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;
+        if (type === 'keepalive' && Date.now() - this.lastQualifyingOutputAt < 15_000)
+            return true;
+        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;
+            }
+            if (!this.ended)
+                this.lastQualifyingOutputAt = Date.now();
+            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';
+import { presentAttachmentEvent } from './agent-attachments.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 stateDir = owner?.snapshot().stateDir;
+                const present = (event) => presentAttachmentEvent(stateDir, request.params.id, event);
+                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', present(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', present(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/events.d.ts

@@ -8,6 +8,8 @@ export interface FleetEvent {
 }
 export declare class FleetEventBus {
     private readonly events;
+    private readonly resourceListeners;
+    subscribeResources(listener: () => void): () => void;
     private readonly clients;
     publish(kind: string, payload: unknown, roleId?: string): FleetEvent;
     attach(socket: WebSocket, lastEventId?: string): () => void;

package/dist/web/events.js

@@ -1,6 +1,8 @@
 import { randomUUID } from 'node:crypto';
 export class FleetEventBus {
     events = [];
+    resourceListeners = new Set();
+    subscribeResources(listener) { this.resourceListeners.add(listener); return () => { this.resourceListeners.delete(listener); }; }
     clients = new Set();
     publish(kind, payload, roleId) {
         const event = { eventId: randomUUID(), at: new Date().toISOString(), roleId, kind, payload };
@@ -12,6 +14,12 @@ export class FleetEventBus {
             if (socket.readyState === socket.OPEN && socket.bufferedAmount < 1024 * 1024)
                 socket.send(frame);
         }
+        for (const listener of this.resourceListeners) {
+            try {
+                listener();
+            }
+            catch { }
+        }
         return event;
     }
     attach(socket, lastEventId) {
@@ -30,5 +38,6 @@ export class FleetEventBus {
         for (const socket of this.clients)
             socket.close(1001, 'server shutdown');
         this.clients.clear();
+        this.resourceListeners.clear();
     }
 }

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;
@@ -44,8 +47,11 @@ export declare class FleetConfigService {
     readonly path: string;
     private readonly preflight;
     private readonly beforeMutation?;
+    private validationInputs;
+    /** Cached during canonical reads; observer filtering must never parse YAML. */
+    resourceValidationInputs(): readonly string[];
     constructor(options?: FleetConfigServiceOptions);
-    read(): ConfigReadResult;
+    read(includeDefinitions?: boolean): ConfigReadResult;
     preview(baseRevision: string, input: unknown): Promise<ConfigPreviewResult>;
     write(baseRevision: string, input: unknown): Promise<ConfigWriteResult>;
 }