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

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

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 import { chmodSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, } from 'node:fs';
-import { basename, dirname, extname, join } from 'node:path';
+import { basename, dirname, extname, join, resolve } from 'node:path';
 import { parse, stringify } from 'yaml';
 import { replaceFileAtomically, withFileLock } from '../atomic-file.js';
 import { loadConfig, ROLE_NAME_RE, splitRootFor } from '../config.js';
@@ -18,20 +18,34 @@ export class FleetConfigService {
     path;
     preflight;
     beforeMutation;
+    validationInputs = [];
+    /** Cached during canonical reads; observer filtering must never parse YAML. */
+    resourceValidationInputs() { return this.validationInputs; }
     constructor(options = {}) {
         this.path = options.configPath ?? defaultConfigPath();
         this.preflight = options.preflight ?? (async () => emptyReport());
         this.beforeMutation = options.beforeMutation;
     }
-    read() {
+    read(includeDefinitions = false) {
         const sources = readSources(this.path);
+        let raw;
         try {
+            const manifest = parse(sources.documents.get(basename(sources.manifest)), { prettyErrors: false });
+            const record = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+            const vars = record(manifest.vars);
+            const expand = (value) => value.replace(/\$\{(\w+)\}/g, (match, key) => key in vars ? String(vars[key]) : match);
+            const invite = record(record(manifest.rooms).owner).public_invite_file;
+            const prompts = Object.values(record(manifest.watchdogs)).map(value => record(value).prompt_file);
+            // Record even invalid/missing references before validation, so repairing an
+            // already observed dependency can never retain a certified stale capture.
+            this.validationInputs = [...(typeof invite === 'string' ? [expand(expand(invite))] : []),
+                ...prompts.filter((value) => typeof value === 'string').map(expand)].map(value => resolve(value));
             loadConfig(this.path, { yamlMode: 'strict' });
+            raw = modelFrom(sources, includeDefinitions);
         }
         catch (error) {
             throw safeError(error, sourceSensitiveValues(sources));
         }
-        const raw = modelFrom(sources);
         const redacted = redactModel(raw);
         return {
             path: basename(this.path), exists: true, firstRun: false,
@@ -41,7 +55,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 +77,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 +119,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 +200,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 +215,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 +247,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 +273,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 +440,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 +450,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>;
+};

package/dist/web/prefix-gateway.js

@@ -0,0 +1,248 @@
+import { randomUUID } from 'node:crypto';
+import { WorkspaceDeviceAuthError } from './workspace-devices.js';
+import { createServer, request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+/** The App offers exactly these two subprotocols; only the marker is ever answered or forwarded. */
+const DEVICE_SOCKET_PROTOCOL = 'ours.workspace.v1';
+const DEVICE_SOCKET_BEARER = 'ours.workspace.bearer.';
+/** The device credential a WebSocket offered as a subprotocol; undefined when it offered none of ours. */
+function deviceSocketCredential(req) {
+    const offered = String(req.headers['sec-websocket-protocol'] ?? '').split(',').map(value => value.trim()).filter(Boolean);
+    if (!offered.some(value => value === DEVICE_SOCKET_PROTOCOL || value.startsWith(DEVICE_SOCKET_BEARER)))
+        return undefined;
+    const credentials = offered.filter(value => value.startsWith(DEVICE_SOCKET_BEARER));
+    const token = credentials[0]?.slice(DEVICE_SOCKET_BEARER.length) ?? '';
+    if (offered.length !== 2 || credentials.length !== 1 || !offered.includes(DEVICE_SOCKET_PROTOCOL) || !/^[A-Za-z0-9_.-]{16,256}$/.test(token))
+        throw new Error('invalid workspace socket subprotocol');
+    return token;
+}
+const hopHeaders = new Set(['connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization', 'te', 'trailer', 'transfer-encoding', 'upgrade']);
+function headersFor(message) {
+    const denied = new Set([...hopHeaders, ...(message.headers.connection ?? '').split(',').map(x => x.trim().toLowerCase())]);
+    return Object.fromEntries(Object.entries(message.headers).filter(([key]) => !denied.has(key)));
+}
+/** Raw transport deliberately runs outside Fastify's JSON parser and body limits. */
+export function createPrefixGateway(options) {
+    const auth = options.auth === 'backend' ? undefined : options.auth;
+    let auditWindow = Date.now(), auditCount = 0;
+    const rejected = (requestId, prefix, result) => {
+        if (Date.now() - auditWindow >= 60_000) {
+            auditWindow = Date.now();
+            auditCount = 0;
+        }
+        if (auditCount++ >= 60)
+            return;
+        void options.audit?.record({ requestId, action: 'gateway' + prefix.replaceAll('/', '.'), result, errorCode: 'unauthorized' }).catch(() => { });
+    };
+    const services = options.services.map(target => {
+        if (!/^\/[a-z][a-z0-9-]*$/.test(target.prefix) || target.prefix === '/fleet')
+            throw new Error('invalid service prefix');
+        const origin = new URL(target.origin);
+        if (target.upstreamPrefix && !/^\/(?:[A-Za-z0-9_-]+\/)*[A-Za-z0-9_-]*$/.test(target.upstreamPrefix))
+            throw new Error('invalid upstream service prefix');
+        if (!['http:', 'https:'].includes(origin.protocol) || origin.pathname !== '/' || origin.search || origin.hash || origin.username || origin.password)
+            throw new Error('service target must be an HTTP origin');
+        return { ...target, origin: origin.origin };
+    });
+    if (new Set(services.map(x => x.prefix)).size !== services.length)
+        throw new Error('duplicate service prefix');
+    const select = (req) => {
+        const raw = req.url ?? '/';
+        if (!raw.startsWith('/') || raw.startsWith('//'))
+            throw new Error('invalid request target');
+        const path = raw.split('?')[0];
+        const service = services.find(x => path === x.prefix || path.startsWith(x.prefix + '/'));
+        const fleet = path === '/fleet/api' || path.startsWith('/fleet/api/');
+        return { service, origin: service?.origin ?? options.fleetOrigin,
+            path: service ? (service.upstreamPrefix || '') + (raw.slice(service.prefix.length) || '/').replace(/^\?/, '/?') : fleet ? raw.slice('/fleet'.length) : raw };
+    };
+    const prepare = (req, upgrade = false) => {
+        const route = select(req);
+        // The device credential of an App WebSocket: accepted only on an upgrade, from the exact
+        // account origin, on a path the service declares, and never beside another credential.
+        const socketCredential = upgrade && auth ? deviceSocketCredential(req) : undefined;
+        if (socketCredential !== undefined) {
+            const path = route.service ? (req.url ?? '/').split('?')[0].slice(route.service.prefix.length) : undefined;
+            if (!route.service?.deviceSocketPaths?.includes(path ?? '') || req.headers.authorization !== undefined || req.headers.cookie !== undefined
+                || !req.headers.origin || auth.accountOrigin(req) !== req.headers.origin)
+                throw new Error('workspace socket credential is not accepted here');
+        }
+        // Authentication sees the credential as the bearer it is; the request's own headers are untouched.
+        const authHeaders = socketCredential !== undefined ? { ...req.headers, authorization: `Bearer ${socketCredential}` } : req.headers;
+        const request = { headers: authHeaders, method: req.method, url: route.path };
+        if (!auth && (req.headers.origin || req.headers['sec-fetch-site'] || !route.service))
+            throw new Error('machine-client listener rejects browser requests');
+        auth?.validateBoundary(request, upgrade);
+        const session = route.service && auth ? auth.authenticate(request, !upgrade && !['GET', 'HEAD', 'OPTIONS'].includes(req.method ?? 'GET')) : undefined;
+        const headers = headersFor(req);
+        // Forward only the explicit browser context, never an attacker-selected forwarding chain.
+        for (const key of Object.keys(headers))
+            if (key.startsWith('x-forwarded-') || key === 'forwarded')
+                delete headers[key];
+        delete headers['x-ours-workspace-auth'];
+        delete headers['x-ours-request-id'];
+        if (route.service) {
+            if (auth)
+                for (const name of ['cookie', 'authorization', 'x-csrf-token', 'x-ours-api-token'])
+                    delete headers[name];
+            // The server gateway lets this header choose a producer credential; only machine producers send it directly there.
+            delete headers['x-ours-notifications-producer'];
+            if (route.service.stripBrowserContext) {
+                for (const name of ['origin', 'sec-fetch-site', 'sec-fetch-mode', 'sec-fetch-dest', 'sec-fetch-user'])
+                    delete headers[name];
+            }
+            Object.assign(headers, route.service.headers);
+            headers.host = new URL(route.origin).host;
+        }
+        if (upgrade) {
+            headers.connection = 'Upgrade';
+            headers.upgrade = 'websocket';
+        }
+        // The credential subprotocol ends here: the service is not offered it, on any request.
+        if (socketCredential !== undefined || String(headers['sec-websocket-protocol'] ?? '').includes(DEVICE_SOCKET_BEARER))
+            delete headers['sec-websocket-protocol'];
+        return { ...route, headers, session, authHeaders, deviceSocket: socketCredential !== undefined };
+    };
+    const track = (authHeaders, session, close, neutral = false) => {
+        if (!session)
+            return () => { };
+        // The session authenticated for this request, with its own deadline, not whatever is current later.
+        const unbind = auth.bindTransport(session, close);
+        const timer = setInterval(() => {
+            if (neutral) {
+                if (!auth.sessionValid(session))
+                    close();
+            }
+            else
+                try {
+                    auth.authenticate({ headers: authHeaders });
+                }
+                catch {
+                    close();
+                }
+        }, neutral ? 1000 : 30_000);
+        timer.unref();
+        return () => { clearInterval(timer); unbind(); };
+    };
+    // The account App calls workspace services directly from its own origin with a device
+    // credential. Only that exact configured origin is answered; the reply grants nothing by
+    // itself, every request is still authenticated below.
+    const accountCors = (req) => {
+        const origin = auth?.accountOrigin(req);
+        return origin ? { 'access-control-allow-origin': origin, vary: 'Origin',
+            'access-control-expose-headers': 'Accept-Ranges, Content-Disposition, Content-Length, Content-Range, Content-Type, ETag, X-Ours-Workspace-Auth, X-Ours-Request-Id, X-Resource-Producer, X-Resource-Revision, X-Resource-Source-Generation, X-Resource-Source-Position, X-Resource-Connection, X-Resource-View, X-Resource-Epoch, X-Resource-Baseline' } : {};
+    };
+    const server = createServer((req, res) => {
+        const cors = accountCors(req);
+        const requestId = randomUUID();
+        let route;
+        try {
+            if (req.method === 'OPTIONS' && cors.vary && req.headers['access-control-request-method'] && select(req).service) {
+                auth.validateBoundary({ headers: req.headers, method: req.method, url: req.url }, false);
+                res.writeHead(204, { ...cors, 'cache-control': 'no-store', 'access-control-max-age': '600',
+                    'access-control-allow-methods': 'GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS',
+                    'access-control-allow-headers': 'Authorization, Content-Type, Idempotency-Key, If-None-Match, Range, X-CSRF-Token, X-Ours-Messenger-CSRF, X-Voice-Duration, X-Resource-Connection, X-Resource-View, X-Resource-Epoch, X-Resource-Baseline' });
+                res.end();
+                return;
+            }
+            route = prepare(req);
+        }
+        catch (error) {
+            const code = error.code;
+            const deviceRejected = error instanceof WorkspaceDeviceAuthError;
+            if (code === 'unauthorized')
+                rejected(requestId, '/auth', deviceRejected ? 'device_rejected' : 'gateway_rejected');
+            res.writeHead(code === 'unauthorized' ? 401 : 403, { ...cors, 'content-type': 'application/json', 'cache-control': 'no-store',
+                ...(code === 'unauthorized' ? { 'x-ours-request-id': requestId } : {}),
+                ...(deviceRejected ? { 'x-ours-workspace-auth': 'rejected' } : {}) });
+            res.end(JSON.stringify({ error: { code: code ?? 'forbidden', message: error.message } }));
+            return;
+        }
+        const upstream = (route.origin.startsWith('https:') ? httpsRequest : httpRequest)(route.origin, {
+            method: req.method, path: route.path, headers: route.headers,
+        }, response => {
+            const headers = headersFor(response);
+            if (route.service) {
+                delete headers['set-cookie'];
+                // Only Fleet may assert device rejection; never trust a service's marker or correlation id.
+                delete headers['x-ours-workspace-auth'];
+                delete headers['x-ours-request-id'];
+                if (response.statusCode === 401) {
+                    headers['x-ours-request-id'] = requestId;
+                    headers['x-ours-workspace-auth'] = 'service';
+                    rejected(requestId, route.service.prefix, 'upstream_401');
+                }
+                for (const key of Object.keys(headers))
+                    if (key.startsWith('access-control-'))
+                        delete headers[key];
+                Object.assign(headers, cors);
+            }
+            res.writeHead(response.statusCode ?? 502, headers);
+            // Streaming headers, including exact-origin CORS and upstream errors,
+            // must reach the client before the first event or body byte arrives.
+            res.flushHeaders();
+            response.on('error', () => res.destroy());
+            response.on('aborted', () => res.destroy());
+            response.on('close', () => { if (!response.complete)
+                res.destroy(); });
+            response.pipe(res);
+            res.on('close', () => response.destroy());
+        });
+        upstream.on('error', () => {
+            if (!res.headersSent)
+                res.writeHead(502, { ...(route.service ? cors : {}), 'content-type': 'application/json' });
+            res.end(JSON.stringify({ error: { code: 'upstream_unavailable', message: 'Service is unavailable' } }));
+        });
+        const neutral = req.method === 'GET' && route.service?.prefix === '/notifications'
+            && new URL(req.url ?? '/', 'http://gateway.invalid').searchParams.get('resources') === '1'
+            && new URL(req.url ?? '/', 'http://gateway.invalid').pathname === '/notifications/api/v1/events';
+        const untrack = track(route.authHeaders, route.session, () => { upstream.destroy(); res.destroy(); }, neutral);
+        res.on('close', untrack);
+        req.on('aborted', () => upstream.destroy());
+        res.on('close', () => upstream.destroy());
+        req.pipe(upstream);
+    });
+    const sockets = new Set();
+    server.on('connection', socket => { sockets.add(socket); socket.on('close', () => sockets.delete(socket)); });
+    server.on('upgrade', (req, socket, head) => {
+        let route;
+        try {
+            route = prepare(req, true);
+        }
+        catch {
+            socket.end('HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n');
+            return;
+        }
+        const upstream = (route.origin.startsWith('https:') ? httpsRequest : httpRequest)(route.origin, {
+            method: req.method, path: route.path, headers: route.headers,
+        });
+        upstream.on('upgrade', (response, peer, upstreamHead) => {
+            const headers = headersFor(response);
+            headers.connection = 'Upgrade';
+            headers.upgrade = 'websocket';
+            delete headers['set-cookie'];
+            // A browser that offered subprotocols needs one answered; only the marker, never the credential.
+            if (route.deviceSocket)
+                headers['sec-websocket-protocol'] = DEVICE_SOCKET_PROTOCOL;
+            socket.write(`HTTP/1.1 101 Switching Protocols\r\n${Object.entries(headers).flatMap(([k, v]) => (Array.isArray(v) ? v : [v]).map(value => `${k}: ${value}\r\n`)).join('')}\r\n`);
+            if (head.length)
+                peer.write(head);
+            if (upstreamHead.length)
+                socket.write(upstreamHead);
+            const untrack = track(route.authHeaders, route.session, () => { peer.destroy(); socket.destroy(); });
+            socket.on('close', untrack);
+            peer.pipe(socket);
+            socket.pipe(peer);
+            peer.on('error', () => socket.destroy());
+            socket.on('error', () => peer.destroy());
+            socket.on('close', () => peer.destroy());
+            peer.on('close', () => socket.destroy());
+        });
+        upstream.on('response', response => { socket.end(`HTTP/1.1 ${response.statusCode ?? 502} Rejected\r\nConnection: close\r\n\r\n`); response.destroy(); });
+        upstream.on('error', () => socket.destroy());
+        socket.on('close', () => upstream.destroy());
+        upstream.end();
+    });
+    return { server, async close() { for (const socket of sockets)
+            socket.destroy(); await new Promise((resolve, reject) => server.close(error => error ? reject(error) : resolve())); } };
+}

package/dist/web/resource-views.d.ts

@@ -0,0 +1,138 @@
+import type { ServerResponse } from 'node:http';
+import { type FleetResourceScope, type FleetResourceState } from '../application/resource-observer.js';
+export declare function abortableProjection<T>(read: Promise<T>, signal: AbortSignal): Promise<T>;
+export interface ResourceFrameBinding {
+    readonly protocolVersion: 1;
+    readonly producerGeneration: string;
+    readonly subscriptionEpoch: number;
+    readonly viewId: string;
+    readonly sequence: number;
+    readonly revision: number;
+    readonly baselineId?: string;
+    readonly source?: FleetResourceState;
+}
+export type ResourceHealthReason = 'auth_required' | 'unsupported' | 'upstream_unavailable';
+export type ResourceEnvelope = ResourceFrameBinding & ({
+    readonly kind: 'snapshot';
+    readonly payload: unknown;
+} | {
+    readonly kind: 'upsert';
+    readonly payload: unknown;
+} | {
+    readonly kind: 'delete';
+    readonly payload: {
+        readonly id: string;
+        readonly revision: number;
+    };
+} | {
+    readonly kind: 'ready';
+    readonly payload: {
+        readonly baselineId: string;
+        readonly source: FleetResourceState;
+    };
+} | {
+    readonly kind: 'coverage';
+    readonly payload: {
+        readonly source: FleetResourceState;
+    };
+} | {
+    readonly kind: 'resync';
+    readonly payload: {
+        readonly reason: 'capacity' | 'projection_unavailable';
+    };
+} | {
+    readonly kind: 'health';
+    readonly payload: {
+        readonly healthy: false;
+        readonly reason: ResourceHealthReason;
+    };
+});
+interface ResourceCoverage {
+    protocolVersion: 1;
+    producerGeneration: string;
+    views: Array<ResourceFrameBinding & {
+        source: FleetResourceState;
+    }>;
+}
+type ResourceOutputRecord = ResourceEnvelope | ResourceCoverage;
+export interface ResourceWireFrame {
+    event: 'resource' | 'resource-chunk' | 'resource-coverage';
+    data: Record<string, unknown>;
+}
+export declare const RESOURCE_FRAME_BYTES: number;
+export declare const RESOURCE_PENDING_BYTES: number;
+export declare const RESOURCE_ASSEMBLY_BYTES: number;
+/** Minimum spacing of activity-only follow-up captures of one view. */
+export declare const ACTIVITY_CAPTURE_INTERVAL_MS = 1000;
+/** Lazily yield byte chunks so backpressure never queues an entire large record.
+ * Base64 prevents splitting a Unicode scalar from corrupting JSON/SSE parsing. */
+export declare function resourceFrames(envelope: ResourceEnvelope): Generator<ResourceWireFrame>;
+/** One Fleet HTTP writer. The active record owns the assembly budget;
+ * waiting live records share the smaller pending-output budget. */
+export declare class ResourceOutput {
+    #private;
+    readonly response: ServerResponse;
+    readonly signal: AbortSignal;
+    readonly failed: (error: Error) => void;
+    constructor(response: ServerResponse, signal: AbortSignal, failed: (error: Error) => void);
+    send(envelope: ResourceOutputRecord, admitted?: () => void): Promise<void>;
+    close(error?: Error): void;
+}
+export interface ResourceDescriptor {
+    viewId: string;
+    resource: 'directory' | 'roles' | 'tasks' | 'task-lists' | 'configuration' | 'previews' | 'task-layout' | 'creation-action' | 'action' | 'member-addition' | 'login' | 'onboarding-health' | 'subscriptions';
+    entityId?: string;
+    receiptId?: string;
+    provider?: 'claude' | 'codex';
+    includeTemporary?: boolean;
+    includeDefinitions?: boolean;
+    ids?: string[];
+    state?: string;
+    list?: string;
+    groupByList?: boolean;
+    includeDeleting?: boolean;
+}
+export declare function canonicalResourceDescriptor(input: unknown): ResourceDescriptor;
+interface BoundProjection {
+    payload: unknown;
+    source: FleetResourceState;
+    producerGeneration: string;
+    revision: number;
+    baselineId: string;
+    descriptor: ResourceDescriptor;
+}
+export declare class ResourceBindingError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/** Same committed snapshot/ready/bound-read contract as Messenger. No controllers,
+ * notification reads or presence are acquired by this delivery owner. */
+export declare class FleetResourceViews {
+    private scope;
+    private project;
+    private configurationInputs;
+    private activityCaptureIntervalMs;
+    readonly producerGeneration: `${string}-${string}-${string}-${string}-${string}`;
+    private connections;
+    constructor(scope: FleetResourceScope, project: (descriptor: ResourceDescriptor, signal: AbortSignal, owner: string) => Promise<unknown>, configurationInputs?: () => readonly string[], activityCaptureIntervalMs?: number);
+    open(response: ServerResponse, owner: string, authorized: () => boolean): {
+        connectionId: `${string}-${string}-${string}-${string}-${string}`;
+        close: () => void;
+    };
+    register(owner: string, connectionId: string, viewId: string, epoch: number, input: unknown): {
+        subscriptionEpoch: number;
+        baselineId: string;
+    };
+    remove(owner: string, connectionId: string, viewId: string, epoch: number): void;
+    bound(owner: string, connectionId: string, viewId: string, epoch: number, baselineId: string): Promise<BoundProjection>;
+    close(): void;
+    private get;
+    private current;
+    private retire;
+    private emit;
+    private coverage;
+    private affects;
+    private schedule;
+    private refresh;
+}
+export {};