@ours.network/fleet 0.15.7 → 0.17.0

package/dist/web/server.js

@@ -159,6 +159,46 @@ export async function buildWebServer(services, boundary, options = {}) {
             throw new FleetError('capability_unavailable', 'fleet topology is unavailable');
         return services.topology();
     });
+    const drafts = () => {
+        if (!services.topologyDrafts)
+            throw new FleetError('capability_unavailable', 'topology sketching is unavailable');
+        return services.topologyDrafts;
+    };
+    app.get('/api/v1/topology/draft', async (request) => {
+        auth.authenticate(request);
+        return drafts().read();
+    });
+    app.put('/api/v1/topology/draft', async (request) => {
+        const session = auth.authenticate(request, true);
+        const body = request.body;
+        const result = await drafts().write(String(body?.revision ?? ''), body?.draft);
+        events.publish('topology.draft.changed', { revision: result.revision });
+        await audit.record({
+            requestId: request.id, browser: session.id, action: 'topology.draft.save', result: 'succeeded',
+        });
+        return result;
+    });
+    const promotion = () => {
+        if (!services.topologyPromote)
+            throw new FleetError('capability_unavailable', 'adding sketches to the fleet is unavailable');
+        return services.topologyPromote;
+    };
+    app.post('/api/v1/topology/promote/preview', async (request) => {
+        auth.authenticate(request, true);
+        return promotion().preview(promoteRequest(request.body));
+    });
+    // Writes configuration only. Nothing here starts a process: `Launch` is a
+    // separate, explicit action, so adding to the fleet can never launch by surprise.
+    app.post('/api/v1/topology/promote', async (request) => {
+        const session = auth.authenticate(request, true);
+        const result = await promotion().promote(promoteRequest(request.body));
+        events.publish('configuration.changed', { revision: result.newRevision });
+        events.publish('topology.draft.changed', { revision: result.draftRevision });
+        await audit.record({
+            requestId: request.id, browser: session.id, action: 'topology.promote', result: 'succeeded',
+        });
+        return result;
+    });
     app.get('/api/v1/roles/:id', async (request) => {
         auth.authenticate(request);
         return services.query.detail(request.params.id);
@@ -454,6 +494,16 @@ function clearAuthCookies(reply) {
         'ofs_device=; HttpOnly; SameSite=Strict; Path=/api; Max-Age=0',
     ]);
 }
+function promoteRequest(body) {
+    const value = (body ?? {});
+    if (!Array.isArray(value.ids) || value.ids.some(id => typeof id !== 'string'))
+        throw new FleetError('invalid_request', 'ids must be a list of sketch ids');
+    return {
+        ids: value.ids,
+        configRevision: String(value.configRevision ?? ''),
+        draftRevision: typeof value.draftRevision === 'string' ? value.draftRevision : undefined,
+    };
+}
 function cryptoRandomId() { return randomBytes(12).toString('hex'); }
 function escapeHtml(value) {
     return value.replace(/[&<>"']/g, char => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[char]));

package/dist/web/topology-draft-store.d.ts

@@ -0,0 +1,80 @@
+import type { Problem } from '../application/types.js';
+import type { TopologyNodeKind } from './topology.js';
+/**
+ * Durable storage for *sketches*: nodes the owner has drawn but not yet added to
+ * the fleet, and where every node sits on the canvas.
+ *
+ * This file is deliberately invisible to `loadConfig`. An incomplete agent in
+ * `roles:` would be started by `ours-fleet up`, and an incomplete watchdog or
+ * loop is a hard `ConfigError` that makes the entire fleet unloadable — so a
+ * draft cannot live in fleet.yaml at all. Being outside the config also makes
+ * "visible but not launchable" true at the daemon level rather than in the UI.
+ *
+ * Nothing here is authoritative and nothing here is a secret: the schema admits
+ * only presentational coordinates and a small allowlist of plain draft fields,
+ * so `env:`/`vars:` values can never reach it.
+ */
+export declare const TOPOLOGY_DRAFT_VERSION = 1;
+export type DraftFieldValue = string | number | boolean;
+export interface DraftPosition {
+    x: number;
+    y: number;
+}
+export interface DraftNode {
+    id: string;
+    kind: TopologyNodeKind;
+    fields: Record<string, DraftFieldValue>;
+}
+export interface DraftEdge {
+    kind: 'oversees' | 'watches' | 'targets';
+    from: string;
+    to: string;
+}
+export interface DraftTutorial {
+    step: number;
+    dismissed: boolean;
+}
+export interface TopologyDraft {
+    version: number;
+    positions: Record<string, DraftPosition>;
+    drafts: {
+        nodes: DraftNode[];
+        edges: DraftEdge[];
+    };
+    tutorial: DraftTutorial;
+}
+export interface TopologyDraftRead {
+    draft: TopologyDraft;
+    revision: string;
+    /** Set when the stored file was unusable and an empty draft is being served. */
+    problem?: Problem;
+    /** False when the file was written by a newer console and must not be clobbered. */
+    writable: boolean;
+}
+export interface TopologyDraftWriteResult {
+    draft: TopologyDraft;
+    revision: string;
+}
+export declare const emptyDraft: () => TopologyDraft;
+export interface TopologyDraftStoreOptions {
+    dir?: string;
+}
+export declare class TopologyDraftStore {
+    readonly path: string;
+    private readonly dir;
+    constructor(options?: TopologyDraftStoreOptions);
+    /**
+     * Never throws. A missing, unreadable, oversized, malformed or future-version
+     * sidecar degrades to an empty draft plus a `problem` the console can show as
+     * a banner — losing sketches is bad, but blocking the console on them is worse.
+     */
+    read(): TopologyDraftRead;
+    /**
+     * Revision-guarded, atomic, 0600. Strict on the way in: an out-of-bounds
+     * coordinate, an unknown field or an unparseable id is refused with a reason
+     * rather than silently dropped, because the caller is the console's own
+     * editor and a silent drop would look like data loss.
+     */
+    write(baseRevision: string, next: unknown): Promise<TopologyDraftWriteResult>;
+    private readRaw;
+}

package/dist/web/topology-draft-store.js

@@ -0,0 +1,337 @@
+import { createHash } from 'node:crypto';
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { replaceFileAtomically, withFileLock } from '../atomic-file.js';
+import { stateRoot } from '../paths.js';
+import { FleetError } from '../application/errors.js';
+/**
+ * Durable storage for *sketches*: nodes the owner has drawn but not yet added to
+ * the fleet, and where every node sits on the canvas.
+ *
+ * This file is deliberately invisible to `loadConfig`. An incomplete agent in
+ * `roles:` would be started by `ours-fleet up`, and an incomplete watchdog or
+ * loop is a hard `ConfigError` that makes the entire fleet unloadable — so a
+ * draft cannot live in fleet.yaml at all. Being outside the config also makes
+ * "visible but not launchable" true at the daemon level rather than in the UI.
+ *
+ * Nothing here is authoritative and nothing here is a secret: the schema admits
+ * only presentational coordinates and a small allowlist of plain draft fields,
+ * so `env:`/`vars:` values can never reach it.
+ */
+export const TOPOLOGY_DRAFT_VERSION = 1;
+const MAX_FILE_BYTES = 256 * 1024;
+const MAX_NODES = 500;
+const MAX_EDGES = 2000;
+const MAX_POSITIONS = 2000;
+const MAX_COORDINATE = 100_000;
+const MAX_FIELDS_PER_NODE = 32;
+const MAX_FIELD_LENGTH = 16 * 1024;
+const MAX_TUTORIAL_STEP = 32;
+const NODE_ID_RE = /^(agent|watchdog|loop):[A-Za-z0-9_-]{1,64}$/;
+const NODE_KINDS = ['agent', 'watchdog', 'loop'];
+/** `spawned` is runtime provenance, never a drawn edge. */
+const EDGE_KINDS = ['oversees', 'watches', 'targets'];
+/**
+ * Draft fields the console may persist. An allowlist rather than a denylist so
+ * secret-bearing keys (`env`, `vars`, `harness_options`) are excluded by
+ * construction; extend it deliberately when the inspector grows a field.
+ *
+ * Every entry is a plain scalar that promotion can write straight into a role,
+ * watchdog or loop mapping. Nested settings (`permissions:`, `harness_options:`,
+ * `isolation:`) are deliberately absent: they are edited through the reviewed
+ * configuration editor once the node is real, not sketched.
+ */
+const FIELD_KEYS = [
+    'mission', 'bio', 'persona', 'coordinator', 'prompt',
+    'interval', 'initial_delay', 'jitter', 'enabled',
+    'harness', 'session', 'model', 'identity', 'cwd',
+];
+export const emptyDraft = () => ({
+    version: TOPOLOGY_DRAFT_VERSION,
+    positions: {},
+    drafts: { nodes: [], edges: [] },
+    tutorial: { step: 0, dismissed: false },
+});
+export class TopologyDraftStore {
+    path;
+    dir;
+    constructor(options = {}) {
+        this.dir = options.dir ?? join(stateRoot(), 'web');
+        this.path = join(this.dir, 'topology.json');
+    }
+    /**
+     * Never throws. A missing, unreadable, oversized, malformed or future-version
+     * sidecar degrades to an empty draft plus a `problem` the console can show as
+     * a banner — losing sketches is bad, but blocking the console on them is worse.
+     */
+    read() {
+        const raw = this.readRaw();
+        const revision = digest(raw.text);
+        if (raw.problem)
+            return { draft: emptyDraft(), revision, problem: raw.problem, writable: true };
+        if (raw.text === '')
+            return { draft: emptyDraft(), revision, writable: true };
+        let parsed;
+        try {
+            parsed = JSON.parse(raw.text);
+        }
+        catch (error) {
+            return {
+                draft: emptyDraft(), revision, writable: true,
+                problem: problem('draft_corrupt', `topology drafts are unreadable and were ignored: ${error.message}`),
+            };
+        }
+        const version = parsed?.version;
+        if (typeof version === 'number' && version > TOPOLOGY_DRAFT_VERSION)
+            return {
+                draft: emptyDraft(), revision, writable: false,
+                problem: problem('draft_version_unsupported', `topology drafts were written by a newer console (version ${version}); update ours-fleet to edit them`),
+            };
+        return { draft: coerceDraft(parsed), revision, writable: true };
+    }
+    /**
+     * Revision-guarded, atomic, 0600. Strict on the way in: an out-of-bounds
+     * coordinate, an unknown field or an unparseable id is refused with a reason
+     * rather than silently dropped, because the caller is the console's own
+     * editor and a silent drop would look like data loss.
+     */
+    async write(baseRevision, next) {
+        const draft = validateDraft(next);
+        const text = `${JSON.stringify(draft, null, 2)}\n`;
+        if (Buffer.byteLength(text) > MAX_FILE_BYTES)
+            throw new FleetError('invalid_request', `topology drafts exceed ${MAX_FILE_BYTES} bytes`);
+        return withFileLock(`${this.path}.lock`, () => {
+            const current = this.read();
+            if (!current.writable)
+                throw new FleetError('incompatible_version', current.problem?.detail ?? 'topology drafts are not writable');
+            if (!baseRevision || baseRevision !== current.revision)
+                throw new FleetError('stale_state', 'topology drafts changed since they were opened; reload before saving');
+            mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+            chmodSync(this.dir, 0o700);
+            replaceFileAtomically(this.path, text, 0o600);
+            return { draft, revision: digest(text) };
+        });
+    }
+    readRaw() {
+        if (!existsSync(this.path))
+            return { text: '' };
+        try {
+            const stat = lstatSync(this.path);
+            if (!stat.isFile() || stat.isSymbolicLink())
+                return { text: '', problem: problem('draft_unreadable', 'topology drafts must be a regular non-symlink file') };
+            if (stat.size > MAX_FILE_BYTES)
+                return { text: '', problem: problem('draft_unreadable', `topology drafts exceed ${MAX_FILE_BYTES} bytes and were ignored`) };
+            const uid = process.getuid?.();
+            if (uid !== undefined && stat.uid !== uid)
+                return { text: '', problem: problem('draft_unreadable', 'topology drafts are not owned by the current user') };
+            return { text: readFileSync(this.path, 'utf8') };
+        }
+        catch (error) {
+            return { text: '', problem: problem('draft_unreadable', `topology drafts could not be read: ${error.message}`) };
+        }
+    }
+}
+const problem = (code, detail) => ({ code, severity: 'warning', detail, source: 'topology.json' });
+const digest = (text) => createHash('sha256').update(text).digest('hex');
+/* ------------------------------------------------------------------ *
+ * Lenient read coercion — drop what does not fit, keep the rest.
+ * ------------------------------------------------------------------ */
+function coerceDraft(value) {
+    const draft = emptyDraft();
+    if (!isRecord(value))
+        return draft;
+    const positions = value.positions;
+    if (isRecord(positions))
+        for (const [id, raw] of Object.entries(positions).slice(0, MAX_POSITIONS)) {
+            if (!NODE_ID_RE.test(id) || !isRecord(raw))
+                continue;
+            if (!isCoordinate(raw.x) || !isCoordinate(raw.y))
+                continue;
+            draft.positions[id] = { x: raw.x, y: raw.y };
+        }
+    const drafts = isRecord(value.drafts) ? value.drafts : {};
+    const seenNodes = new Set();
+    if (Array.isArray(drafts.nodes))
+        for (const raw of drafts.nodes) {
+            if (draft.drafts.nodes.length >= MAX_NODES)
+                break;
+            const node = coerceNode(raw);
+            if (!node || seenNodes.has(node.id))
+                continue;
+            seenNodes.add(node.id);
+            draft.drafts.nodes.push(node);
+        }
+    const seenEdges = new Set();
+    if (Array.isArray(drafts.edges))
+        for (const raw of drafts.edges) {
+            if (draft.drafts.edges.length >= MAX_EDGES)
+                break;
+            const edge = coerceEdge(raw);
+            if (!edge)
+                continue;
+            const key = `${edge.kind}:${edge.from}:${edge.to}`;
+            if (seenEdges.has(key))
+                continue;
+            seenEdges.add(key);
+            draft.drafts.edges.push(edge);
+        }
+    if (isRecord(value.tutorial)) {
+        const { step, dismissed } = value.tutorial;
+        if (typeof step === 'number' && Number.isInteger(step) && step >= 0 && step <= MAX_TUTORIAL_STEP)
+            draft.tutorial.step = step;
+        draft.tutorial.dismissed = dismissed === true;
+    }
+    return draft;
+}
+function coerceNode(value) {
+    if (!isRecord(value))
+        return undefined;
+    const { id, kind } = value;
+    if (typeof id !== 'string' || !NODE_ID_RE.test(id))
+        return undefined;
+    if (typeof kind !== 'string' || !NODE_KINDS.includes(kind))
+        return undefined;
+    if (!id.startsWith(`${kind}:`))
+        return undefined;
+    const fields = {};
+    if (isRecord(value.fields))
+        for (const [key, raw] of Object.entries(value.fields)) {
+            if (Object.keys(fields).length >= MAX_FIELDS_PER_NODE)
+                break;
+            if (!FIELD_KEYS.includes(key) || !isFieldValue(raw))
+                continue;
+            fields[key] = raw;
+        }
+    return { id, kind: kind, fields };
+}
+function coerceEdge(value) {
+    if (!isRecord(value))
+        return undefined;
+    const { kind, from, to } = value;
+    if (typeof kind !== 'string' || !EDGE_KINDS.includes(kind))
+        return undefined;
+    if (typeof from !== 'string' || !NODE_ID_RE.test(from))
+        return undefined;
+    if (typeof to !== 'string' || !NODE_ID_RE.test(to) || from === to)
+        return undefined;
+    return { kind: kind, from, to };
+}
+/* ------------------------------------------------------------------ *
+ * Strict write validation — refuse with a reason.
+ * ------------------------------------------------------------------ */
+function validateDraft(value) {
+    if (!isRecord(value))
+        throw invalid('topology draft must be a JSON object');
+    const version = value.version ?? TOPOLOGY_DRAFT_VERSION;
+    if (version !== TOPOLOGY_DRAFT_VERSION)
+        throw invalid(`unsupported topology draft version ${String(version)}`);
+    const draft = emptyDraft();
+    const positions = value.positions ?? {};
+    if (!isRecord(positions))
+        throw invalid('positions must be an object');
+    const positionIds = Object.keys(positions);
+    if (positionIds.length > MAX_POSITIONS)
+        throw invalid(`at most ${MAX_POSITIONS} node positions are supported`);
+    for (const id of positionIds) {
+        if (!NODE_ID_RE.test(id))
+            throw invalid(`invalid node id in positions: ${id}`);
+        const raw = positions[id];
+        if (!isRecord(raw) || !isCoordinate(raw.x) || !isCoordinate(raw.y))
+            throw invalid(`position for ${id} must be finite x/y within ±${MAX_COORDINATE}`);
+        draft.positions[id] = { x: raw.x, y: raw.y };
+    }
+    const drafts = value.drafts ?? {};
+    if (!isRecord(drafts))
+        throw invalid('drafts must be an object');
+    const nodes = drafts.nodes ?? [];
+    const edges = drafts.edges ?? [];
+    if (!Array.isArray(nodes))
+        throw invalid('drafts.nodes must be an array');
+    if (!Array.isArray(edges))
+        throw invalid('drafts.edges must be an array');
+    if (nodes.length > MAX_NODES)
+        throw invalid(`at most ${MAX_NODES} draft nodes are supported`);
+    if (edges.length > MAX_EDGES)
+        throw invalid(`at most ${MAX_EDGES} draft edges are supported`);
+    const seenNodes = new Set();
+    for (const raw of nodes) {
+        const node = validateNode(raw);
+        if (seenNodes.has(node.id))
+            throw invalid(`duplicate draft node ${node.id}`);
+        seenNodes.add(node.id);
+        draft.drafts.nodes.push(node);
+    }
+    const seenEdges = new Set();
+    for (const raw of edges) {
+        const edge = validateEdge(raw);
+        const key = `${edge.kind}:${edge.from}:${edge.to}`;
+        if (seenEdges.has(key))
+            continue;
+        seenEdges.add(key);
+        draft.drafts.edges.push(edge);
+    }
+    const tutorial = value.tutorial ?? {};
+    if (!isRecord(tutorial))
+        throw invalid('tutorial must be an object');
+    const step = tutorial.step ?? 0;
+    if (typeof step !== 'number' || !Number.isInteger(step) || step < 0 || step > MAX_TUTORIAL_STEP)
+        throw invalid(`tutorial.step must be an integer between 0 and ${MAX_TUTORIAL_STEP}`);
+    draft.tutorial = { step, dismissed: tutorial.dismissed === true };
+    return draft;
+}
+function validateNode(value) {
+    if (!isRecord(value))
+        throw invalid('each draft node must be an object');
+    const { id, kind } = value;
+    if (typeof id !== 'string' || !NODE_ID_RE.test(id))
+        throw invalid(`draft node id must look like agent:<Name>: ${JSON.stringify(id)}`);
+    if (typeof kind !== 'string' || !NODE_KINDS.includes(kind))
+        throw invalid(`draft node ${id} has an unknown kind ${JSON.stringify(kind)}`);
+    if (!id.startsWith(`${kind}:`))
+        throw invalid(`draft node ${id} does not match kind ${kind}`);
+    const rawFields = value.fields ?? {};
+    if (!isRecord(rawFields))
+        throw invalid(`draft node ${id} fields must be an object`);
+    const keys = Object.keys(rawFields);
+    if (keys.length > MAX_FIELDS_PER_NODE)
+        throw invalid(`draft node ${id} has more than ${MAX_FIELDS_PER_NODE} fields`);
+    const fields = {};
+    for (const key of keys) {
+        if (!FIELD_KEYS.includes(key))
+            throw invalid(`draft node ${id} may not store field ${JSON.stringify(key)}`);
+        const raw = rawFields[key];
+        if (!isFieldValue(raw))
+            throw invalid(`draft node ${id} field ${key} must be a string under ${MAX_FIELD_LENGTH} characters, a finite number, or a boolean`);
+        fields[key] = raw;
+    }
+    return { id, kind: kind, fields };
+}
+function validateEdge(value) {
+    if (!isRecord(value))
+        throw invalid('each draft edge must be an object');
+    const { kind, from, to } = value;
+    if (typeof kind !== 'string' || !EDGE_KINDS.includes(kind))
+        throw invalid(`draft edge has an unknown kind ${JSON.stringify(kind)}`);
+    if (typeof from !== 'string' || !NODE_ID_RE.test(from))
+        throw invalid(`invalid draft edge source ${JSON.stringify(from)}`);
+    if (typeof to !== 'string' || !NODE_ID_RE.test(to))
+        throw invalid(`invalid draft edge target ${JSON.stringify(to)}`);
+    if (from === to)
+        throw invalid(`draft edge ${from} cannot point at itself`);
+    return { kind: kind, from, to };
+}
+const invalid = (message) => new FleetError('invalid_request', message);
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isCoordinate(value) {
+    return typeof value === 'number' && Number.isFinite(value)
+        && value >= -MAX_COORDINATE && value <= MAX_COORDINATE;
+}
+function isFieldValue(value) {
+    if (typeof value === 'boolean')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    return typeof value === 'string' && value.length <= MAX_FIELD_LENGTH;
+}

package/dist/web/topology-model.d.ts

@@ -0,0 +1,62 @@
+import type { FleetConfig } from '../config.js';
+import type { Problem } from '../application/types.js';
+import { type RuntimeRoleItem, type TopologyEdge, type TopologyNode } from './topology.js';
+import type { DraftFieldValue, DraftPosition, TopologyDraftRead } from './topology-draft-store.js';
+/**
+ * The console's read model: authoritative configuration overlaid with the
+ * sketches and canvas positions from the draft sidecar.
+ *
+ * `deriveTopology` stays a pure function of resolved config plus the runtime
+ * role list — this layer calls it and annotates the result, so the derivation
+ * and its tests keep their meaning. Everything drafts add is additive.
+ */
+export type NodeOrigin = 'draft' | 'config';
+/** One actionable reason a node is not yet ready, phrased for the owner. */
+export interface MissingRequirement {
+    field: string;
+    why: string;
+    fix: string;
+}
+export interface MergedTopologyNode extends TopologyNode {
+    origin: NodeOrigin;
+    /** Would `loadConfig` accept this node's name today. */
+    valid: boolean;
+    /** Meets the bar for being added to the fleet. */
+    complete: boolean;
+    /**
+     * Whether a process may be started for this node. A draft is never launchable,
+     * and not because the UI hides a button: a draft is in no file the supervisor
+     * or `ours-fleet up` reads.
+     */
+    launchable: boolean;
+    missing: MissingRequirement[];
+    position?: DraftPosition;
+    enabled?: boolean;
+    /** Sketched values, on draft nodes only — what promotion writes. */
+    fields?: Record<string, DraftFieldValue>;
+}
+export interface MergedTopologyEdge extends TopologyEdge {
+    origin: NodeOrigin;
+    /** A watchdog with no `watch:` list watches every agent, including later ones. */
+    implicit: boolean;
+    /** An endpoint that no longer exists — kept visible rather than swallowed. */
+    dangling: boolean;
+}
+export interface MergedTopology {
+    nodes: MergedTopologyNode[];
+    edges: MergedTopologyEdge[];
+    unknownLineage: string[];
+    problems: Problem[];
+    draftRevision: string;
+    draftWritable: boolean;
+}
+export declare const IMPLICIT_WATCH_LABEL = "watches all agents (default)";
+/**
+ * Merge configuration and drafts into the graph the console renders.
+ *
+ * Drift is surfaced, never silently repaired: a draft whose name is now taken
+ * by real configuration is reported as a problem rather than shadowing it, a
+ * draft edge to a vanished node is kept and marked dangling, and a position for
+ * a node that no longer exists is simply dropped.
+ */
+export declare function mergeTopology(config: FleetConfig, roles: RuntimeRoleItem[], draft: TopologyDraftRead): MergedTopology;