@ours.network/fleet 0.15.6 → 0.16.0

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;

package/dist/web/topology-model.js

@@ -0,0 +1,220 @@
+import { deriveTopology, } from './topology.js';
+export const IMPLICIT_WATCH_LABEL = 'watches all agents (default)';
+const AGENT_MISSION = {
+    field: 'mission',
+    why: 'An agent without a mission has nothing to do and reads as noise on the canvas.',
+    fix: 'Write one sentence about this agent\'s job.',
+};
+const WATCHDOG_COORDINATOR = {
+    field: 'coordinator',
+    why: 'A watchdog reports to exactly one coordinator; the fleet refuses to load without it.',
+    fix: 'Name the agent this watchdog reports to.',
+};
+const LOOP_PROMPT = {
+    field: 'prompt',
+    why: 'An interval delivers a prompt on a schedule; there is nothing to deliver yet.',
+    fix: 'Write the prompt this interval should send.',
+};
+const LOOP_TARGET = {
+    field: 'roles',
+    why: 'An interval needs at least one agent to deliver its prompt to.',
+    fix: 'Connect this interval to an agent.',
+};
+/**
+ * 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 function mergeTopology(config, roles, draft) {
+    const snapshot = deriveTopology(config, roles);
+    const problems = draft.problem ? [draft.problem] : [];
+    const configIds = new Set(snapshot.nodes.map(node => node.id));
+    const shadowed = draft.draft.drafts.nodes.filter(node => configIds.has(node.id));
+    if (shadowed.length)
+        problems.push({
+            code: 'draft_conflicts_with_config',
+            severity: 'warning',
+            source: 'topology.json',
+            detail: `${shadowed.map(node => node.id).join(', ')} now exist${shadowed.length === 1 ? 's' : ''} in the fleet configuration; rename the draft to keep sketching it`,
+        });
+    const draftNodes = draft.draft.drafts.nodes.filter(node => !configIds.has(node.id));
+    const draftEdges = draft.draft.drafts.edges;
+    const nodes = [
+        ...snapshot.nodes.map(node => configNode(node, config)),
+        ...draftNodes.map(node => draftNode(node, draftEdges, draftNodes, config)),
+    ];
+    const known = new Map(nodes.map(node => [node.id, node]));
+    const implicitConfigWatchdogs = new Set(config.watchdogs.filter(watchdog => !watchdog.watchExplicit).map(watchdog => `watchdog:${watchdog.name}`));
+    const edges = [
+        ...snapshot.edges.map(edge => annotate(edge, 'config', edge.kind === 'watches' && implicitConfigWatchdogs.has(edge.from), known)),
+        ...draftEdges.map(edge => annotate({
+            id: `${edge.kind}:${edge.from}:${edge.to}`, kind: edge.kind,
+            from: edge.from, to: edge.to, label: edgeLabel(edge.kind),
+        }, 'draft', false, known)),
+        ...implicitDraftWatchEdges(draftNodes, draftEdges, nodes, known),
+    ];
+    for (const node of nodes) {
+        const position = draft.draft.positions[node.id];
+        if (position)
+            node.position = position;
+    }
+    return {
+        nodes,
+        edges,
+        unknownLineage: snapshot.unknownLineage,
+        problems,
+        draftRevision: draft.revision,
+        draftWritable: draft.writable,
+    };
+}
+/* ------------------------------------------------------------------ *
+ * Configured nodes
+ * ------------------------------------------------------------------ */
+function configNode(node, config) {
+    const name = node.id.slice(node.kind.length + 1);
+    const missing = [];
+    let enabled;
+    if (node.kind === 'agent') {
+        const role = config.roles.find(candidate => candidate.name === name);
+        // A role reachable only through its on-disk state directory is running
+        // configuration we cannot inspect; do not invent a gap for it.
+        if (role && !nonBlank(role.mission))
+            missing.push(AGENT_MISSION);
+    }
+    else if (node.kind === 'watchdog') {
+        enabled = config.watchdogs.find(candidate => candidate.name === name)?.enabled;
+    }
+    else {
+        enabled = config.loops.find(candidate => candidate.name === name)?.enabled;
+    }
+    const complete = missing.length === 0;
+    return { ...node, origin: 'config', valid: true, complete, launchable: complete, missing, enabled };
+}
+/* ------------------------------------------------------------------ *
+ * Draft nodes
+ * ------------------------------------------------------------------ */
+function draftNode(node, edges, draftNodes, config) {
+    const name = node.id.slice(node.kind.length + 1);
+    const missing = [];
+    const collision = nameConflict(node.kind, name, config);
+    if (collision)
+        missing.push({
+            field: 'name',
+            why: `The fleet already uses the name "${name}" for ${collision}.`,
+            fix: 'Rename this draft before adding it to the fleet.',
+        });
+    const draftIds = new Set(draftNodes.map(other => other.id));
+    const outgoing = edges.filter(edge => edge.from === node.id);
+    const stillDraft = (kind) => outgoing
+        .filter(edge => edge.kind === kind && draftIds.has(edge.to))
+        .map(edge => edge.to.slice('agent:'.length));
+    if (node.kind === 'agent') {
+        if (!nonBlank(node.fields.mission))
+            missing.push(AGENT_MISSION);
+    }
+    else if (node.kind === 'watchdog') {
+        if (!nonBlank(node.fields.coordinator))
+            missing.push(WATCHDOG_COORDINATOR);
+        pushPendingTargets(missing, 'watch', stillDraft('watches'), 'A watchdog may only watch agents that are already in the fleet.');
+    }
+    else {
+        if (!outgoing.some(edge => edge.kind === 'targets'))
+            missing.push(LOOP_TARGET);
+        if (!nonBlank(node.fields.prompt))
+            missing.push(LOOP_PROMPT);
+        pushPendingTargets(missing, 'roles', stillDraft('targets'), 'An interval may only deliver to agents that are already in the fleet.');
+    }
+    return {
+        id: node.id,
+        kind: node.kind,
+        label: name,
+        status: 'draft',
+        detail: draftDetail(node),
+        origin: 'draft',
+        valid: !collision,
+        complete: missing.length === 0,
+        launchable: false, // a draft is in no file the supervisor reads
+        missing,
+        fields: node.fields,
+        enabled: node.fields.enabled === undefined ? undefined : node.fields.enabled !== false,
+    };
+}
+function pushPendingTargets(missing, field, pending, why) {
+    if (!pending.length)
+        return;
+    missing.push({
+        field, why,
+        fix: `Add ${pending.join(', ')} to the fleet first, or remove the connection.`,
+    });
+}
+function draftDetail(node) {
+    const value = node.kind === 'agent' ? node.fields.mission
+        : node.kind === 'watchdog' ? node.fields.coordinator && `Reports to ${node.fields.coordinator}`
+            : node.fields.prompt;
+    return nonBlank(value) ? String(value) : undefined;
+}
+/* ------------------------------------------------------------------ *
+ * Edges
+ * ------------------------------------------------------------------ */
+function annotate(edge, origin, implicit, known) {
+    return {
+        ...edge,
+        label: implicit ? IMPLICIT_WATCH_LABEL : edge.label,
+        origin,
+        implicit,
+        dangling: !known.has(edge.from) || !known.has(edge.to),
+    };
+}
+/**
+ * A draft watchdog nobody scoped to a single agent is a *standalone* watchdog:
+ * promoting it omits `watch:`, which the config layer reads as "every role".
+ * Draw that so the owner sees the coverage before adding it, and so an agent
+ * added later is visibly covered with no edit at all.
+ */
+function implicitDraftWatchEdges(draftNodes, draftEdges, nodes, known) {
+    const persistentAgents = nodes.filter(node => node.kind === 'agent' && node.lifetime !== 'temporary');
+    return draftNodes
+        .filter(node => node.kind === 'watchdog'
+        && !draftEdges.some(edge => edge.kind === 'watches' && edge.from === node.id))
+        .flatMap(watchdog => persistentAgents.map(agent => annotate({
+        id: `watches:${watchdog.id}:${agent.id}`, kind: 'watches',
+        from: watchdog.id, to: agent.id, label: IMPLICIT_WATCH_LABEL,
+    }, 'draft', true, known)));
+}
+const edgeLabel = (kind) => (kind === 'watches' ? 'watches' : kind === 'targets' ? 'delivers to' : 'oversees');
+/* ------------------------------------------------------------------ *
+ * Shared
+ * ------------------------------------------------------------------ */
+/**
+ * What already owns `name`, or undefined when a draft of this kind may use it.
+ *
+ * Deliberately mirrors the collisions the config layer actually rejects and no
+ * others: a watchdog name may not equal a role name, and a watchdog identity
+ * (`Watchdog-<name>` by default) may not equal a role name, a role identity or
+ * another watchdog identity. Loop names share no namespace with anything, so a
+ * loop is only ever blocked by another loop of the same name.
+ */
+function nameConflict(kind, name, config) {
+    if (kind === 'loop')
+        return undefined;
+    if (kind === 'agent') {
+        // Adding a role named N breaks any watchdog already using N as its identity.
+        if (config.watchdogs.some(watchdog => watchdog.name === name))
+            return 'a watchdog';
+        const identity = config.watchdogs.find(watchdog => watchdog.identity === name);
+        return identity ? `watchdog ${identity.name}'s identity` : undefined;
+    }
+    if (config.roles.some(role => role.name === name))
+        return 'a role';
+    const identity = `Watchdog-${name}`;
+    if (config.roles.some(role => role.name === identity))
+        return `a role, which this watchdog's identity "${identity}" would collide with`;
+    if (config.roles.some(role => role.identity === identity))
+        return `a role identity, which this watchdog's identity "${identity}" would collide with`;
+    const other = config.watchdogs.find(watchdog => watchdog.identity === identity);
+    return other ? `watchdog ${other.name}'s identity "${identity}"` : undefined;
+}
+const nonBlank = (value) => typeof value === 'string' ? value.trim() !== '' : value !== undefined && value !== null;

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

@@ -0,0 +1,31 @@
+import type { ConfigPreviewResult, ConfigWriteResult, FleetConfigService } from './fleet-config-service.js';
+import type { TopologyDraftStore } from './topology-draft-store.js';
+import type { MergedTopology } from './topology-model.js';
+export interface PromoteRequest {
+    ids: string[];
+    configRevision: string;
+    draftRevision?: string;
+}
+export interface PromotePreview extends ConfigPreviewResult {
+    promoted: string[];
+}
+export interface PromoteResult extends ConfigWriteResult {
+    promoted: string[];
+    /** False when the config landed but the sketches could not be cleared. */
+    draftsCleared: boolean;
+    draftRevision: string;
+}
+export interface TopologyPromoteOptions {
+    drafts: TopologyDraftStore;
+    configuration: FleetConfigService;
+    topology(): Promise<MergedTopology>;
+}
+export declare class TopologyPromoteService {
+    private readonly options;
+    constructor(options: TopologyPromoteOptions);
+    preview(request: PromoteRequest): Promise<PromotePreview>;
+    promote(request: PromoteRequest): Promise<PromoteResult>;
+    private clearDrafts;
+    /** Build the configuration model that adding `ids` produces. */
+    private build;
+}

package/dist/web/topology-promote.js

@@ -0,0 +1,168 @@
+import { FleetError } from '../application/errors.js';
+/**
+ * Turn sketches into configuration.
+ *
+ * Promotion is the middle step of sketch -> promote -> launch, and it writes
+ * configuration ONLY. It never provisions an identity, never registers a
+ * supervisor service and never starts a process: `Launch` is a separate, explicit
+ * action. That separation is what makes "visible but not launchable" true at the
+ * daemon level rather than as a UI rule.
+ *
+ * No YAML is written here. The mutation is expressed against the configuration
+ * *model* and handed to `FleetConfigService`, so the revision guard, the real
+ * loader validating a candidate file, the reviewed diff, the timestamped backup
+ * and the atomic 0600 replace are all impossible to bypass.
+ */
+/** Loop interval when the sketch did not choose one (`resolveLoops` requires it). */
+const DEFAULT_LOOP_INTERVAL = '10m';
+/** Scalar draft fields that are valid keys of a role mapping. */
+const ROLE_FIELDS = ['mission', 'bio', 'persona', 'coordinator', 'harness', 'session', 'model', 'identity', 'cwd'];
+/** Scalar draft fields that are valid keys of a watchdog mapping. */
+const WATCHDOG_FIELDS = ['coordinator', 'interval', 'enabled'];
+/** Scalar draft fields that are valid keys of a loop mapping. */
+const LOOP_FIELDS = ['prompt', 'interval', 'initial_delay', 'jitter'];
+export class TopologyPromoteService {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async preview(request) {
+        const { model, promoted } = await this.build(request);
+        const preview = await this.options.configuration.preview(request.configRevision, model);
+        return { ...preview, promoted };
+    }
+    async promote(request) {
+        const { model, promoted } = await this.build(request);
+        const written = await this.options.configuration.write(request.configRevision, model);
+        // The configuration is real now. Clearing the sketches is best effort: if the
+        // sidecar moved under us the drafts simply resurface as shadowed-by-config,
+        // which the merged model already reports, rather than losing the write.
+        const cleared = await this.clearDrafts(promoted, request.draftRevision);
+        return { ...written, promoted, draftsCleared: cleared.ok, draftRevision: cleared.revision };
+    }
+    async clearDrafts(promoted, draftRevision) {
+        const current = this.options.drafts.read();
+        if (draftRevision !== undefined && draftRevision !== current.revision)
+            return { ok: false, revision: current.revision };
+        const promotedIds = new Set(promoted);
+        const next = {
+            ...current.draft,
+            drafts: {
+                nodes: current.draft.drafts.nodes.filter(node => !promotedIds.has(node.id)),
+                /*
+                 * A drawn edge is owned by its SOURCE — it becomes the source's `watch:`
+                 * or `roles:` list — so it is materialised, and therefore redundant, only
+                 * once the source itself is written. Clearing it because the TARGET was
+                 * promoted silently rewrites the survivor's meaning: a watchdog scoped to
+                 * one agent loses its only scope edge, reads as standalone, and is then
+                 * written with no `watch:` key at all — that is, watching everything.
+                 */
+                edges: current.draft.drafts.edges.filter(edge => !promotedIds.has(edge.from)),
+            },
+        };
+        try {
+            const written = await this.options.drafts.write(current.revision, next);
+            return { ok: true, revision: written.revision };
+        }
+        catch {
+            return { ok: false, revision: current.revision };
+        }
+    }
+    /** Build the configuration model that adding `ids` produces. */
+    async build(request) {
+        if (!Array.isArray(request.ids) || request.ids.length === 0)
+            throw new FleetError('invalid_request', 'name at least one sketch to add to the fleet');
+        const merged = await this.options.topology();
+        const read = this.options.configuration.read();
+        if (read.revision !== request.configRevision)
+            throw new FleetError('stale_state', 'fleet.yaml changed since it was opened; reload before adding to the fleet');
+        const selected = request.ids.map(id => resolve(merged, id));
+        const model = structuredClone(read.model);
+        // Agents first: a watchdog's `watch:` list and a loop's `roles:` list may only
+        // name roles that exist, including ones being added in this same write.
+        for (const node of [...selected].sort(byKind))
+            addNode(model, node, merged);
+        return { model, promoted: selected.map(node => node.id) };
+    }
+}
+const KIND_ORDER = { agent: 0, watchdog: 1, loop: 2 };
+const byKind = (a, b) => KIND_ORDER[a.kind] - KIND_ORDER[b.kind];
+function resolve(merged, id) {
+    const node = merged.nodes.find(candidate => candidate.id === id);
+    if (!node)
+        throw new FleetError('invalid_request', `there is no sketch called ${id}`);
+    if (node.origin !== 'draft')
+        throw new FleetError('conflict', `${node.label} is already part of the fleet configuration`);
+    if (!node.valid || !node.complete) {
+        const why = node.missing.map(item => `${item.field}: ${item.fix}`).join(' ');
+        throw new FleetError('invalid_request', `${node.label} is not ready to add — ${why}`);
+    }
+    return node;
+}
+function addNode(model, node, merged) {
+    const block = section(model, node.kind === 'agent' ? 'roles' : node.kind === 'watchdog' ? 'watchdogs' : 'loops');
+    if (block[node.label] !== undefined)
+        throw new FleetError('conflict', `${node.label} already exists in the configuration`);
+    block[node.label] = node.kind === 'agent' ? agentEntry(node)
+        : node.kind === 'watchdog' ? watchdogEntry(node, merged)
+            : loopEntry(node, merged, model);
+}
+function agentEntry(node) {
+    return pick(node, ROLE_FIELDS);
+}
+/**
+ * D4, and the owner requirement it encodes: a watchdog drawn on its own carries
+ * NO `watch:` key, which the config layer reads as "every configured role" —
+ * so an agent added tomorrow is covered with no edit at all. A watchdog created
+ * from a specific agent carries that agent explicitly and stays scoped to it.
+ */
+function watchdogEntry(node, merged) {
+    const scoped = linked(merged, node.id, 'watches');
+    return { ...pick(node, WATCHDOG_FIELDS), ...(scoped.length ? { watch: scoped } : {}) };
+}
+function loopEntry(node, merged, model) {
+    const roles = linked(merged, node.id, 'targets');
+    const entry = {
+        roles, ...pick(node, LOOP_FIELDS),
+    };
+    entry.interval ??= DEFAULT_LOOP_INTERVAL;
+    // An enabled loop hard-requires `session: acp` on every target. Adding one to a
+    // tmux agent would make the whole fleet unloadable, so it arrives switched off
+    // and badged instead — the owner turns it on after switching the agent to ACP.
+    if (node.enabled === false || !roles.every(role => sessionOf(model, role) === 'acp'))
+        entry.enabled = false;
+    return entry;
+}
+/** Names of the agents this node points at, from drawn edges and derived ones alike. */
+function linked(merged, id, kind) {
+    return [...new Set(merged.edges
+            .filter(edge => edge.kind === kind && edge.from === id && !edge.implicit && !edge.dangling)
+            .map(edge => edge.to.slice('agent:'.length)))].sort();
+}
+function sessionOf(model, role) {
+    const roles = model.roles;
+    const defaults = model.defaults;
+    return String(roles?.[role]?.session ?? defaults?.session ?? 'tmux');
+}
+function section(model, key) {
+    const existing = model[key];
+    if (existing && typeof existing === 'object' && !Array.isArray(existing))
+        return existing;
+    const created = {};
+    model[key] = created;
+    return created;
+}
+/** Copy only the sketched fields that are real keys of the target mapping. */
+function pick(node, keys) {
+    const fields = node.fields ?? {};
+    const out = {};
+    for (const key of keys) {
+        const value = fields[key];
+        if (value === undefined)
+            continue;
+        if (typeof value === 'string' && value.trim() === '')
+            continue;
+        out[key] = value;
+    }
+    return out;
+}

package/dist/web/yaml-document-edit.d.ts

@@ -0,0 +1,31 @@
+export type YamlModel = Record<string, unknown>;
+/** Formatting of the source document, so a rewrite does not reflow it. */
+export interface DocumentFormatting {
+    indent: number;
+    indentSeq: boolean;
+}
+/**
+ * Apply `model` to `source`, returning the new document text.
+ *
+ * Guarantees:
+ * - an unchanged model returns `source` byte for byte;
+ * - regions outside a change keep their bytes whenever the change is spliceable;
+ * - the result parses back to exactly `model`, verified before returning, so a
+ *   planning bug can never silently write something else to disk.
+ */
+export declare function renderModelOntoSource(source: string, model: YamlModel): string;
+/**
+ * Replace every `defaults.env` / `roles.*.env` value — and every `vars:` entry
+ * those values interpolate — with `marker`.
+ *
+ * Splices the scalars out of the original bytes rather than re-rendering, so the
+ * only difference from `source` is the secrets themselves. Redaction must not be
+ * able to introduce (or conceal) a formatting change in a review diff.
+ */
+export declare function redactSourceSecrets(source: string, marker: string): string;
+/**
+ * Best-effort detection of the document's block indentation, used only when a
+ * change is not spliceable and the document has to be re-rendered. Detection
+ * failure falls back to the library defaults; correctness never depends on it.
+ */
+export declare function detectFormatting(source: string): DocumentFormatting;