@hyperdrive.bot/paseo-server 0.2.6

package/dist/server/server/workflow/workflow-manager.js

@@ -0,0 +1,444 @@
+import { randomUUID } from "node:crypto";
+import { PARENT_AGENT_ID_LABEL, WORKFLOW_ID_LABEL, WORKFLOW_TASK_ID_LABEL, } from "@hyperdrive.bot/paseo-protocol/agent-labels";
+import { projectWorkflowPhases, projectWorkflowProgress, resolveExecutionLayers, } from "./workflow-progress.js";
+// Re-exported for back-compat: this error used to be declared here before the
+// execution-layer logic moved to `workflow-progress.ts` (Epic 3, Story 3.1).
+export { WorkflowCycleError } from "./workflow-progress.js";
+// Default settle window (ms) for coalescing a burst of child `agent_state` events
+// into ONE projection emit. Mirrors AGENT_STREAM_COALESCE_DEFAULT_WINDOW_MS.
+export const WORKFLOW_PROJECTION_COALESCE_WINDOW_MS = 60;
+/** Thrown when a workflow id resolves to nothing in memory or storage. */
+export class WorkflowNotFoundError extends Error {
+    constructor(workflowId) {
+        super(`Workflow ${workflowId} not found`);
+        this.workflowId = workflowId;
+        this.name = "WorkflowNotFoundError";
+    }
+}
+/** Thrown when cancel targets a workflow that has already reached a terminal state. */
+export class WorkflowAlreadyTerminalError extends Error {
+    constructor(workflowId, status) {
+        super(`Workflow ${workflowId} is already ${status} and cannot be cancelled`);
+        this.workflowId = workflowId;
+        this.status = status;
+        this.name = "WorkflowAlreadyTerminalError";
+    }
+}
+export class WorkflowManager {
+    constructor(options) {
+        this.workflows = new Map();
+        this.subscribers = new Set();
+        this.projectionTimers = new Map();
+        this.agentManager = options.agentManager;
+        this.storage = options.storage;
+        this.coalesceWindowMs = options.coalesceWindowMs ?? WORKFLOW_PROJECTION_COALESCE_WINDOW_MS;
+        this.timers = options.timers ?? { setTimeout, clearTimeout };
+        // Subscribe to child lifecycle changes so progress is projected live. We only
+        // care about FUTURE state — `replayState: false` skips the synchronous replay of
+        // every existing agent at construction time.
+        this.unsubscribeAgents = this.agentManager.subscribe((event) => this.onAgentEvent(event), {
+            replayState: false,
+        });
+    }
+    /**
+     * Detach the AgentManager subscription and cancel any pending projection timers.
+     * Idempotent; safe to call on daemon shutdown.
+     */
+    dispose() {
+        this.unsubscribeAgents();
+        for (const timer of this.projectionTimers.values()) {
+            this.timers.clearTimeout(timer);
+        }
+        this.projectionTimers.clear();
+    }
+    /**
+     * Build a workflow snapshot from a task graph, persist it (Story 1.1 storage),
+     * register it in memory, emit to subscribers, and return the snapshot. No process
+     * is spawned here — that happens in {@link startWorkflow}/{@link spawnPhaseAgent}.
+     */
+    async createWorkflow(input) {
+        const id = input.id ?? randomUUID();
+        const now = new Date().toISOString();
+        const layers = resolveExecutionLayers(input.graph);
+        const phases = layers.map((layer, index) => ({
+            id: `layer-${index + 1}`,
+            title: `Layer ${index + 1}`,
+            status: "pending",
+            storyCount: layer.length,
+            completedStoryCount: 0,
+        }));
+        const snapshot = {
+            id,
+            cwd: input.cwd,
+            status: "pending",
+            title: input.title ?? input.graph.goal,
+            labels: input.labels ?? {},
+            phases,
+            childAgentIds: [],
+            totalStoryCount: input.graph.tasks.length,
+            completedStoryCount: 0,
+            createdAt: now,
+            updatedAt: now,
+        };
+        await this.storage.saveWorkflow(snapshot);
+        this.workflows.set(id, {
+            snapshot,
+            graph: input.graph,
+            baseConfig: input.baseConfig,
+            parentAgentId: input.parentAgentId,
+            terminalOutcomes: new Map(),
+        });
+        this.emit(snapshot);
+        return snapshot;
+    }
+    /**
+     * List every known workflow — storage records overlaid with in-memory snapshots.
+     * Live workflows are returned with progress PROJECTED from current child state
+     * (Story 3.1), so list surfaces show the same live counts as the detail/SSE views.
+     */
+    async listWorkflows() {
+        const byId = new Map();
+        for (const record of await this.storage.listWorkflows()) {
+            byId.set(record.id, record);
+        }
+        for (const live of this.workflows.values()) {
+            byId.set(live.snapshot.id, this.projectSnapshot(live));
+        }
+        return Array.from(byId.values());
+    }
+    /**
+     * Resolve a single workflow. A hard miss throws {@link WorkflowNotFoundError}.
+     * For a live workflow the returned snapshot carries progress PROJECTED from the
+     * current child-agent states — the persisted counter is never trusted as truth.
+     */
+    async getWorkflow(id) {
+        const live = this.workflows.get(id);
+        if (live) {
+            return this.projectSnapshot(live);
+        }
+        const stored = await this.storage.loadWorkflow(id);
+        if (!stored) {
+            throw new WorkflowNotFoundError(id);
+        }
+        return stored;
+    }
+    /**
+     * Cancel a workflow: flip it to the terminal `cancelled` status, persist, and
+     * emit. Resolves a live OR storage-only workflow. Throws
+     * {@link WorkflowNotFoundError} for an unknown id and
+     * {@link WorkflowAlreadyTerminalError} when it has already finished. Child-agent
+     * teardown is the separate concern of {@link cascadeArchiveChildren}.
+     */
+    async cancelWorkflow(workflowId) {
+        const live = this.workflows.get(workflowId);
+        const current = live?.snapshot ?? (await this.storage.loadWorkflow(workflowId));
+        if (!current) {
+            throw new WorkflowNotFoundError(workflowId);
+        }
+        if (isTerminalStatus(current.status)) {
+            throw new WorkflowAlreadyTerminalError(workflowId, current.status);
+        }
+        const now = new Date().toISOString();
+        const cancelled = {
+            ...current,
+            status: "cancelled",
+            completedAt: now,
+            updatedAt: now,
+        };
+        if (live) {
+            live.snapshot = cancelled;
+        }
+        await this.storage.saveWorkflow(cancelled);
+        this.emit(cancelled);
+        return cancelled;
+    }
+    /**
+     * Return the workflow's recorded lifecycle events, derived deterministically
+     * from its snapshot's timestamps (created/started/completed/archived). A
+     * one-shot read — continuous event push is Epic 2. Throws
+     * {@link WorkflowNotFoundError} for an unknown id.
+     */
+    async getWorkflowEvents(workflowId) {
+        const snapshot = await this.getWorkflow(workflowId);
+        return projectWorkflowEvents(snapshot);
+    }
+    /**
+     * Drive a workflow to completion of its spawn phase: transition pending -> running,
+     * then walk `executionLayers` sequentially, spawning each layer's task agents (in
+     * task order). Returns the updated snapshot.
+     */
+    async startWorkflow(workflowId) {
+        const live = this.requireLive(workflowId);
+        const startedAt = new Date().toISOString();
+        live.snapshot = {
+            ...live.snapshot,
+            status: "running",
+            startedAt,
+            updatedAt: startedAt,
+        };
+        await this.persist(live);
+        this.emit(live.snapshot);
+        const layers = resolveExecutionLayers(live.graph);
+        for (const layer of layers) {
+            for (const taskId of layer) {
+                const node = live.graph.tasks.find((task) => task.id === taskId);
+                if (!node) {
+                    throw new Error(`Task ${taskId} not found in workflow ${workflowId} graph`);
+                }
+                await this.spawnPhaseAgent({ workflowId, node, config: live.baseConfig });
+            }
+        }
+        return this.requireLive(workflowId).snapshot;
+    }
+    /**
+     * Spawn a single child agent for one task node via the public
+     * `agentManager.createAgent` surface, tagging it with WORKFLOW_ID_LABEL (and
+     * PARENT_AGENT_ID_LABEL when the workflow is owned by a parent agent). Records the
+     * child id on the snapshot and persists. Never spawns a process directly.
+     */
+    async spawnPhaseAgent(args) {
+        const { workflowId, node, config } = args;
+        const live = this.requireLive(workflowId);
+        const labels = {
+            ...live.snapshot.labels,
+            [WORKFLOW_ID_LABEL]: workflowId,
+            // Story 3.1 — map this child to its specific story node so the live progress
+            // projection can derive completion/phase/gate from real child lifecycle state.
+            [WORKFLOW_TASK_ID_LABEL]: node.id,
+        };
+        if (live.parentAgentId) {
+            labels[PARENT_AGENT_ID_LABEL] = live.parentAgentId;
+        }
+        const agent = await this.agentManager.createAgent(config, undefined, {
+            labels,
+            initialPrompt: node.prompt,
+            initialTitle: node.title,
+        });
+        live.snapshot = {
+            ...live.snapshot,
+            childAgentIds: [...live.snapshot.childAgentIds, agent.id],
+            updatedAt: new Date().toISOString(),
+        };
+        await this.persist(live);
+        this.emit(live.snapshot);
+        return agent;
+    }
+    /**
+     * Archive every child agent tagged to the workflow — no orphans — mirroring
+     * `AgentManager.cascadeArchiveChildren`, but keyed on WORKFLOW_ID_LABEL and using
+     * only the public archive surface (`listAgents` + `archiveAgent`). `archiveAgent`
+     * requires a live agent, so we iterate the live set exactly as the original guards
+     * on `agents.has(id)`. The workflow snapshot itself is marked archived.
+     */
+    async cascadeArchiveChildren(workflowId) {
+        for (const agent of this.agentManager.listAgents()) {
+            if (agent.labels?.[WORKFLOW_ID_LABEL] !== workflowId) {
+                continue;
+            }
+            await this.agentManager.archiveAgent(agent.id);
+        }
+        const live = this.workflows.get(workflowId);
+        if (live) {
+            const archivedAt = new Date().toISOString();
+            const status = terminalStatusForArchive(live.snapshot.status);
+            live.snapshot = { ...live.snapshot, status, archivedAt, updatedAt: archivedAt };
+            await this.persist(live);
+            this.emit(live.snapshot);
+        }
+    }
+    /**
+     * Number of live snapshot subscribers. Read-only observability — used by the
+     * SSE route's leak-guard test (Story 2.1) to assert that a disconnected client
+     * unsubscribes back to baseline. Additive; does not affect emit behaviour.
+     */
+    get subscriberCount() {
+        return this.subscribers.size;
+    }
+    /** Subscribe to workflow snapshot changes. Returns an unsubscribe function. */
+    subscribe(subscriber) {
+        this.subscribers.add(subscriber);
+        return () => {
+            this.subscribers.delete(subscriber);
+        };
+    }
+    emit(workflow) {
+        for (const subscriber of this.subscribers) {
+            try {
+                subscriber({ workflow });
+            }
+            catch {
+                // Subscriber error isolation — one bad listener never blocks the others.
+            }
+        }
+    }
+    /**
+     * AgentManager subscription handler (Story 3.1). Reacts only to child state
+     * changes for an agent tagged to a tracked, non-terminal workflow; schedules a
+     * coalesced projection emit for that workflow.
+     */
+    onAgentEvent(event) {
+        if (event.type !== "agent_state") {
+            return;
+        }
+        const workflowId = event.agent.labels?.[WORKFLOW_ID_LABEL];
+        if (workflowId === undefined) {
+            return;
+        }
+        const live = this.workflows.get(workflowId);
+        if (!live || isTerminalStatus(live.snapshot.status)) {
+            return;
+        }
+        // A child that reaches a terminal lifecycle is DELETED from AgentManager's live map
+        // (prepareAgentForClosure), so the live projection would never witness its completion.
+        // Record the terminal outcome now -- keyed by task, while the event still carries the
+        // closed agent -- so projectSnapshot counts it even after the agent is gone.
+        const taskId = event.agent.labels?.[WORKFLOW_TASK_ID_LABEL];
+        if (taskId !== undefined) {
+            if (event.agent.lifecycle === "closed") {
+                live.terminalOutcomes.set(taskId, event.agent.lastError ? "failed" : "success");
+            }
+            else if (event.agent.lifecycle === "error") {
+                live.terminalOutcomes.set(taskId, "failed");
+            }
+        }
+        this.scheduleProjectionEmit(workflowId);
+    }
+    /**
+     * Coalesce a burst of child updates into ONE projection emit per settled window
+     * (the `agent-stream-coalescer.ts` discipline). The first event in a burst arms a
+     * timer; subsequent events within the window are absorbed. On fire, the current
+     * child states are projected and the updated snapshot is emitted through the
+     * existing `workflow.*` / HTTP / SSE channels — no new transport, no polling.
+     */
+    scheduleProjectionEmit(workflowId) {
+        if (this.projectionTimers.has(workflowId)) {
+            return;
+        }
+        const timer = this.timers.setTimeout(() => {
+            this.projectionTimers.delete(workflowId);
+            const live = this.workflows.get(workflowId);
+            if (!live) {
+                return;
+            }
+            this.emit(this.projectSnapshot(live));
+        }, this.coalesceWindowMs);
+        timer.unref?.();
+        this.projectionTimers.set(workflowId, timer);
+    }
+    /**
+     * Overlay LIVE derived progress onto a workflow's base snapshot. Counts, per-phase
+     * gate status, and per-phase completion are recomputed from the current child-agent
+     * states — never read back from the persisted snapshot. Terminal workflows are
+     * returned unchanged (nothing left to project). The base snapshot's lifecycle
+     * fields (status, childAgentIds, timestamps, id/title) are preserved verbatim; only
+     * derived progress fields are overlaid, so this stays back-compat and additive.
+     */
+    projectSnapshot(live) {
+        const base = live.snapshot;
+        if (isTerminalStatus(base.status)) {
+            return base;
+        }
+        const children = this.agentManager
+            .listAgents()
+            .filter((agent) => agent.labels?.[WORKFLOW_ID_LABEL] === base.id);
+        const projectedPhases = projectWorkflowPhases({
+            children,
+            taskGraph: live.graph,
+            terminalOutcomes: live.terminalOutcomes,
+        });
+        const progress = projectWorkflowProgress({
+            children,
+            taskGraph: live.graph,
+            terminalOutcomes: live.terminalOutcomes,
+        });
+        // Overlay by index — preserve each phase's persisted id/title, refresh its gate.
+        const phases = base.phases.map((phase, index) => {
+            const projected = projectedPhases[index];
+            if (!projected) {
+                return phase;
+            }
+            return {
+                ...phase,
+                status: projected.status,
+                storyCount: projected.storyCount,
+                completedStoryCount: projected.completedStoryCount,
+            };
+        });
+        return {
+            ...base,
+            phases,
+            totalStoryCount: progress.totalStoryCount,
+            completedStoryCount: progress.completedStoryCount,
+        };
+    }
+    requireLive(workflowId) {
+        const live = this.workflows.get(workflowId);
+        if (!live) {
+            throw new WorkflowNotFoundError(workflowId);
+        }
+        return live;
+    }
+    async persist(live) {
+        await this.storage.saveWorkflow(live.snapshot);
+    }
+}
+/** A workflow in a terminal state can no longer be cancelled. */
+function isTerminalStatus(status) {
+    return status === "completed" || status === "failed" || status === "cancelled";
+}
+/** The lifecycle-event type that corresponds to a terminal status. */
+function terminalEventType(status) {
+    switch (status) {
+        case "failed":
+            return "failed";
+        case "cancelled":
+            return "cancelled";
+        // `completedAt` is only ever stamped alongside a terminal status, so the
+        // remaining cases (completed / pending / running) all map to "completed".
+        default:
+            return "completed";
+    }
+}
+/**
+ * Derive the ordered lifecycle-event list from a snapshot's timestamps. Pure and
+ * deterministic — the same snapshot always yields the same events.
+ */
+function projectWorkflowEvents(snapshot) {
+    const events = [
+        { workflowId: snapshot.id, type: "created", status: "pending", at: snapshot.createdAt },
+    ];
+    if (snapshot.startedAt) {
+        events.push({
+            workflowId: snapshot.id,
+            type: "started",
+            status: "running",
+            at: snapshot.startedAt,
+        });
+    }
+    if (snapshot.completedAt) {
+        events.push({
+            workflowId: snapshot.id,
+            type: terminalEventType(snapshot.status),
+            status: snapshot.status,
+            at: snapshot.completedAt,
+        });
+    }
+    if (snapshot.archivedAt) {
+        events.push({
+            workflowId: snapshot.id,
+            type: "archived",
+            status: snapshot.status,
+            at: snapshot.archivedAt,
+        });
+    }
+    return events;
+}
+/** Map a workflow status to its terminal tag when the workflow is archived. */
+function terminalStatusForArchive(status) {
+    if (status === "completed" || status === "failed") {
+        return status;
+    }
+    // pending / running / cancelled -> a workflow torn down before finishing is cancelled.
+    return "cancelled";
+}
+//# sourceMappingURL=workflow-manager.js.map

package/dist/server/server/workflow/workflow-progress.d.ts

@@ -0,0 +1,95 @@
+import type { WorkflowSnapshot } from "@hyperdrive.bot/paseo-protocol/messages";
+import type { ManagedAgent } from "../agent/agent-manager.js";
+import type { TaskGraph } from "./workflow-manager.js";
+/**
+ * workflow-progress — Epic 3, Story 3.1.
+ *
+ * Live workflow progress is DERIVED, never stored. This module owns the single pure
+ * computation that turns the *current set* of child-agent states + the workflow's
+ * task graph into `{ completedStoryCount, totalStoryCount, phase, gateStatus }`.
+ *
+ * Why a pure function of the current set (not a fold over per-event deltas):
+ * - **Order-independent.** Counting the present states means arrival order cannot
+ *   change the result — feeding the same children shuffled yields a deeply-equal
+ *   projection. This is what makes "derived, not stored" testable as an equality.
+ * - **Monotonic-correct.** `completedStoryCount` only moves up as more children reach
+ *   terminal-success; it never flickers backwards under out-of-order arrival.
+ * - **Recompute-on-load safe.** After a daemon restart the projection is rebuilt from
+ *   whatever child states exist now; no persisted counter is trusted as truth.
+ *
+ * Determinism rules (mirroring `docs/architecture.md` timeline discipline):
+ * - NEVER call `Date.now()` / `new Date()` here. Recency ordering uses the canonical
+ *   daemon-owned `ManagedAgent.updatedAt`, with the agent id as a stable tiebreak so
+ *   equal timestamps still resolve order-independently.
+ * - No I/O, no module-level mutable state, no snapshot reads.
+ *
+ * `WorkflowCycleError` + the execution-layer resolution live here (rather than in
+ * `workflow-manager.ts`) so the manager and the projection share ONE layer derivation
+ * — guaranteeing the phase order the manager persists matches the phases this module
+ * projects. The manager imports both back from here; the only edge in the other
+ * direction is the type-only `TaskGraph`/`TaskNode` import above (erased at runtime,
+ * so there is no runtime cycle).
+ */
+type WorkflowStatus = WorkflowSnapshot["status"];
+/** The four derived progress values for a workflow, computed from child states. */
+export interface WorkflowProgress {
+    /** Story nodes whose mapped child reached terminal-success. Never exceeds total. */
+    completedStoryCount: number;
+    /** Total number of story (task) nodes in the run. */
+    totalStoryCount: number;
+    /** Id of the current phase (earliest phase with a non-done story); null when all done. */
+    phase: string | null;
+    /** Gate status of the current phase, mapped onto WorkflowStatus; null for an empty graph. */
+    gateStatus: WorkflowStatus | null;
+}
+/** Per-phase projected state — used by the manager to overlay the wire `phases[]`. */
+export interface ProjectedPhase {
+    /** Stable phase id, matching the manager's `layer-${index + 1}` convention. */
+    id: string;
+    /** Zero-based phase index (execution-layer order). */
+    index: number;
+    /** Task ids belonging to this phase, in graph order. */
+    taskIds: string[];
+    /** Number of story nodes in this phase. */
+    storyCount: number;
+    /** Story nodes in this phase whose child reached terminal-success. */
+    completedStoryCount: number;
+    /** Derived gate status for this phase. */
+    status: WorkflowStatus;
+}
+/** Per-task lifecycle classification, derived purely from a child's lifecycle. */
+export type TaskOutcome = "pending" | "running" | "success" | "failed";
+/**
+ * Project per-phase gate state from the current child states. Children MUST already
+ * be scoped to a single workflow (filtered by `WORKFLOW_ID_LABEL`) — task ids are
+ * only unique within one workflow's graph.
+ */
+export declare function projectWorkflowPhases(params: {
+    children: ManagedAgent[];
+    taskGraph: TaskGraph;
+    terminalOutcomes?: ReadonlyMap<string, TaskOutcome>;
+}): ProjectedPhase[];
+/**
+ * Project the workflow's live progress summary from the current child states.
+ *
+ * Pure function of `(children, taskGraph)` only — no I/O, no clock, no stored-count
+ * reads. Calling it twice with the same inputs (in any order) returns deeply-equal
+ * results. Children MUST already be scoped to the workflow via `WORKFLOW_ID_LABEL`.
+ */
+export declare function projectWorkflowProgress(params: {
+    children: ManagedAgent[];
+    taskGraph: TaskGraph;
+    terminalOutcomes?: ReadonlyMap<string, TaskOutcome>;
+}): WorkflowProgress;
+/** Thrown when a task graph's dependencies cannot be layered (cycle / dangling dep). */
+export declare class WorkflowCycleError extends Error {
+    readonly unresolved: string[];
+    constructor(unresolved: string[]);
+}
+/**
+ * Resolve the layered execution order for a graph. Prefer the graph's declared
+ * `metadata.executionLayers`; otherwise compute layers from task dependencies.
+ */
+export declare function resolveExecutionLayers(graph: TaskGraph): string[][];
+export {};
+//# sourceMappingURL=workflow-progress.d.ts.map