@hyperdrive.bot/paseo-server 0.2.6

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

@@ -0,0 +1,2 @@
+export declare const WORKFLOWS_FEATURE_ENABLED = true;
+//# sourceMappingURL=workflow-feature.d.ts.map

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

@@ -0,0 +1,8 @@
+// COMPAT(workflows): added in v0.1.X, remove gate after 2026-12-17.
+//
+// Single source of truth for the `workflows` capability. Both the `server_info`
+// handshake flag (`buildServerInfoStatusPayload()` in websocket-server.ts) and the
+// HTTP route gate (`registerWorkflowHttpRoutes` `featureEnabled`) read THIS constant,
+// so the advertised capability and the actually-served routes can never drift.
+export const WORKFLOWS_FEATURE_ENABLED = true;
+//# sourceMappingURL=workflow-feature.js.map

package/dist/server/server/workflow/workflow-http-routes.d.ts

@@ -0,0 +1,27 @@
+import type express from "express";
+import type pino from "pino";
+import type { WorkflowManager } from "./workflow-manager.js";
+/**
+ * Dependencies for the read-only `/api/workflows/*` HTTP surface.
+ *
+ * `featureEnabled` is the SAME boolean advertised as `server_info.features.workflows`
+ * (see `workflow-feature.ts`) — when it is `false`, every route 404s and no SSE
+ * stream is ever opened, so the advertised capability and the served routes cannot
+ * drift.
+ */
+export interface WorkflowHttpRoutesDeps {
+    manager: WorkflowManager;
+    featureEnabled: boolean;
+}
+/**
+ * Register the daemon's read-only workflow HTTP routes on the existing Express app,
+ * mirroring the `registerPushRoutes` / `registerWorkspaceSessionsRoute` convention.
+ * No second listener or port — these attach to the shared `app`.
+ *
+ * Routes:
+ * - `GET /api/workflows/status`      → JSON array of workflow summaries.
+ * - `GET /api/workflows/:id`         → single workflow JSON, 404 on unknown id.
+ * - `GET /api/workflows/:id/events`  → SSE stream of phase transitions for that id.
+ */
+export declare function registerWorkflowHttpRoutes(app: express.Express, deps: WorkflowHttpRoutesDeps, logger: pino.Logger): void;
+//# sourceMappingURL=workflow-http-routes.d.ts.map

package/dist/server/server/workflow/workflow-http-routes.js

@@ -0,0 +1,97 @@
+import { WorkflowNotFoundError } from "./workflow-manager.js";
+/**
+ * Register the daemon's read-only workflow HTTP routes on the existing Express app,
+ * mirroring the `registerPushRoutes` / `registerWorkspaceSessionsRoute` convention.
+ * No second listener or port — these attach to the shared `app`.
+ *
+ * Routes:
+ * - `GET /api/workflows/status`      → JSON array of workflow summaries.
+ * - `GET /api/workflows/:id`         → single workflow JSON, 404 on unknown id.
+ * - `GET /api/workflows/:id/events`  → SSE stream of phase transitions for that id.
+ */
+export function registerWorkflowHttpRoutes(app, deps, logger) {
+    const { manager, featureEnabled } = deps;
+    const routeLogger = logger.child({ component: "workflow-http-routes" });
+    // GET /api/workflows/status — array of summaries (empty list ⇒ []). Registered
+    // before `/:id` so the literal path wins over the param route.
+    app.get("/api/workflows/status", (_req, res) => {
+        if (!featureEnabled) {
+            res.status(404).json({ error: "workflows feature not enabled" });
+            return;
+        }
+        void (async () => {
+            try {
+                const workflows = await manager.listWorkflows();
+                res.json(workflows);
+            }
+            catch (err) {
+                routeLogger.error({ err }, "failed to list workflows");
+                res.status(500).json({ error: "failed to list workflows" });
+            }
+        })();
+    });
+    // GET /api/workflows/:id — single workflow; unknown id ⇒ 404 JSON (never 5xx).
+    app.get("/api/workflows/:id", (req, res) => {
+        if (!featureEnabled) {
+            res.status(404).json({ error: "workflows feature not enabled" });
+            return;
+        }
+        void (async () => {
+            const { id } = req.params;
+            try {
+                const workflow = await manager.getWorkflow(id);
+                res.json(workflow);
+            }
+            catch (err) {
+                if (err instanceof WorkflowNotFoundError) {
+                    res.status(404).json({ error: "workflow not found" });
+                    return;
+                }
+                routeLogger.error({ err, id }, "failed to get workflow");
+                res.status(500).json({ error: "failed to get workflow" });
+            }
+        })();
+    });
+    // GET /api/workflows/:id/events — SSE phase-transition stream. The single
+    // load-bearing rule: every subscribe() has a matching unsubscribe() in the
+    // "close" handler (the leak guard).
+    app.get("/api/workflows/:id/events", (req, res) => {
+        if (!featureEnabled) {
+            res.status(404).json({ error: "workflows feature not enabled" });
+            return;
+        }
+        void (async () => {
+            const { id } = req.params;
+            // Resolve first — an unknown id 404s BEFORE any stream is opened.
+            try {
+                await manager.getWorkflow(id);
+            }
+            catch (err) {
+                if (err instanceof WorkflowNotFoundError) {
+                    res.status(404).json({ error: "workflow not found" });
+                    return;
+                }
+                routeLogger.error({ err, id }, "failed to resolve workflow for SSE");
+                res.status(500).json({ error: "failed to get workflow" });
+                return;
+            }
+            res.setHeader("Content-Type", "text/event-stream");
+            res.setHeader("Cache-Control", "no-cache");
+            res.setHeader("Connection", "keep-alive");
+            res.flushHeaders();
+            const unsubscribe = manager.subscribe((event) => {
+                // The route is id-scoped — only stream transitions for THIS workflow.
+                if (event.workflow.id !== id) {
+                    return;
+                }
+                res.write(`data: ${JSON.stringify(event)}\n\n`);
+            });
+            req.on("close", () => {
+                unsubscribe();
+                res.end();
+            });
+        })();
+    });
+    routeLogger.info("Registered GET /api/workflows/status, /api/workflows/:id, /api/workflows/:id/events");
+}
+//# sourceMappingURL=workflow-http-routes.js.map

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

@@ -0,0 +1,228 @@
+import type { WorkflowLifecycleEvent, WorkflowSnapshot } from "@hyperdrive.bot/paseo-protocol/messages";
+import type { AgentManager, ManagedAgent } from "../agent/agent-manager.js";
+import type { AgentSessionConfig } from "../agent/agent-sdk-types.js";
+import type { WorkflowStorage } from "./workflow-storage.js";
+export { WorkflowCycleError } from "./workflow-progress.js";
+export declare const WORKFLOW_PROJECTION_COALESCE_WINDOW_MS = 60;
+/** Injectable timer surface — defaults to the globals; overridable for deterministic tests. */
+export interface WorkflowProjectionTimers {
+    setTimeout: (callback: () => void, ms?: number) => ReturnType<typeof setTimeout>;
+    clearTimeout: (handle: ReturnType<typeof setTimeout>) => void;
+}
+/**
+ * WorkflowManager — Epic 1, Story 1.2.
+ *
+ * The daemon-owned orchestration core. It decomposes a task-graph into child agents
+ * spawned through the EXISTING `agentManager.createAgent` lifecycle, so every child
+ * inherits PTY transport, supervision, timeline streaming, persistence, and MCP tools
+ * for free. WorkflowManager never spawns a process itself.
+ *
+ * The dependency is strictly one-directional: WorkflowManager imports AgentManager,
+ * AgentManager never imports WorkflowManager (enforced by `npm run typecheck`). Both
+ * imports here are type-only, so there is zero runtime edge back into the manager.
+ */
+/** Individual task node in the dependency graph. */
+export interface TaskNode {
+    /** Unique task identifier (e.g. "task-001"). */
+    id: string;
+    /** Task IDs that must complete before this task can start. */
+    dependencies: string[];
+    /** Detailed description of what this task accomplishes. */
+    description: string;
+    /** Full prompt the spawned agent executes. */
+    prompt: string;
+    /** Human-readable task title. */
+    title: string;
+    /** File path where task output will be written. */
+    outputFile: string;
+    /** Whether this task can run in parallel with others in the same layer. */
+    parallelizable: boolean;
+    /** Estimated time in minutes for the agent to complete. */
+    estimatedMinutes: number;
+    /** Optional agent type to use (dev, architect, qa, etc.). */
+    agentType?: string;
+    /** Optional specific files this task operates on (per-file tasks). */
+    targetFiles?: string[];
+}
+/** Metadata about the task graph. */
+export interface TaskGraphMetadata {
+    /** Execution layers — each layer runs in parallel, layers run sequentially. */
+    executionLayers: string[][];
+    /** Maximum number of tasks that can run in parallel. */
+    maxParallelism: number;
+    /** Total number of tasks. */
+    totalTasks: number;
+    /** Estimated total duration in minutes. */
+    estimatedDuration: number;
+    /** Whether per-file task generation was used. */
+    perFileMode: boolean;
+    /** Whether tasks are formatted as BMAD stories. */
+    storyFormat?: boolean;
+    /** Optional total files targeted for per-file mode. */
+    totalFiles?: number;
+}
+/** Complete task graph representing a decomposed goal. */
+export interface TaskGraph {
+    /** The original big goal being decomposed. */
+    goal: string;
+    /** Master prompt template reusable across similar goals. */
+    masterPrompt: string;
+    /** Metadata about the task graph. */
+    metadata: TaskGraphMetadata;
+    /** Session-specific information. */
+    session: {
+        id: string;
+        createdAt: string;
+        outputDirectory: string;
+    };
+    /** All tasks in the graph. */
+    tasks: TaskNode[];
+}
+type WorkflowStatus = WorkflowSnapshot["status"];
+/** Input to {@link WorkflowManager.createWorkflow}. */
+export interface CreateWorkflowInput {
+    /** Working directory all child agents inherit. */
+    cwd: string;
+    /** Decomposed task graph that drives child-agent spawning. */
+    graph: TaskGraph;
+    /** Base session config (provider/model template) each child is spawned with. */
+    baseConfig: AgentSessionConfig;
+    /** Optional explicit workflow id (defaults to a random UUID). */
+    id?: string;
+    /** Optional display title (defaults to the graph goal). */
+    title?: string | null;
+    /** Optional labels copied onto every spawned child alongside the workflow id. */
+    labels?: Record<string, string>;
+    /** Optional owning agent id — children also carry PARENT_AGENT_ID_LABEL. */
+    parentAgentId?: string;
+}
+/** Event emitted to workflow subscribers whenever a snapshot changes. */
+export interface WorkflowEvent {
+    workflow: WorkflowSnapshot;
+}
+export type WorkflowSubscriber = (event: WorkflowEvent) => void;
+/** Thrown when a workflow id resolves to nothing in memory or storage. */
+export declare class WorkflowNotFoundError extends Error {
+    readonly workflowId: string;
+    constructor(workflowId: string);
+}
+/** Thrown when cancel targets a workflow that has already reached a terminal state. */
+export declare class WorkflowAlreadyTerminalError extends Error {
+    readonly workflowId: string;
+    readonly status: WorkflowStatus;
+    constructor(workflowId: string, status: WorkflowStatus);
+}
+export declare class WorkflowManager {
+    private readonly agentManager;
+    private readonly storage;
+    private readonly workflows;
+    private readonly subscribers;
+    private readonly timers;
+    private readonly coalesceWindowMs;
+    private readonly projectionTimers;
+    private readonly unsubscribeAgents;
+    constructor(options: {
+        agentManager: AgentManager;
+        storage: WorkflowStorage;
+        coalesceWindowMs?: number;
+        timers?: WorkflowProjectionTimers;
+    });
+    /**
+     * Detach the AgentManager subscription and cancel any pending projection timers.
+     * Idempotent; safe to call on daemon shutdown.
+     */
+    dispose(): void;
+    /**
+     * 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}.
+     */
+    createWorkflow(input: CreateWorkflowInput): Promise<WorkflowSnapshot>;
+    /**
+     * 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.
+     */
+    listWorkflows(): Promise<WorkflowSnapshot[]>;
+    /**
+     * 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.
+     */
+    getWorkflow(id: string): Promise<WorkflowSnapshot>;
+    /**
+     * 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}.
+     */
+    cancelWorkflow(workflowId: string): Promise<WorkflowSnapshot>;
+    /**
+     * 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.
+     */
+    getWorkflowEvents(workflowId: string): Promise<WorkflowLifecycleEvent[]>;
+    /**
+     * 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.
+     */
+    startWorkflow(workflowId: string): Promise<WorkflowSnapshot>;
+    /**
+     * 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.
+     */
+    spawnPhaseAgent(args: {
+        workflowId: string;
+        node: TaskNode;
+        config: AgentSessionConfig;
+    }): Promise<ManagedAgent>;
+    /**
+     * 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.
+     */
+    cascadeArchiveChildren(workflowId: string): Promise<void>;
+    /**
+     * 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(): number;
+    /** Subscribe to workflow snapshot changes. Returns an unsubscribe function. */
+    subscribe(subscriber: WorkflowSubscriber): () => void;
+    private emit;
+    /**
+     * 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.
+     */
+    private onAgentEvent;
+    /**
+     * 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.
+     */
+    private scheduleProjectionEmit;
+    /**
+     * 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.
+     */
+    private projectSnapshot;
+    private requireLive;
+    private persist;
+}
+//# sourceMappingURL=workflow-manager.d.ts.map