@hyperdrive.bot/fleet-server 0.3.99

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

@@ -0,0 +1,363 @@
+import type { WorkflowAgentPreset, WorkflowLifecycleEvent, WorkflowSnapshot } from "@hyperdrive.bot/fleet-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 { WorkflowInvalidGraphError } from "./workflow-progress.js";
+export { WorkflowUnknownAgentError } from "./workflow-agent-resolution.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;
+}
+/**
+ * Minimal logging surface: a pino `Logger` satisfies it structurally.
+ *
+ * `error` is declared as a METHOD shorthand (bivariant) rather than a function
+ * property, so both a pino `Logger` and a plain test stub are assignable.
+ */
+export interface WorkflowManagerLogger {
+    error(context: Record<string, unknown>, message: string): void;
+    trace(context: Record<string, unknown>, message: string): 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 inline config override for this task; highest precedence. */
+    agentConfig?: WorkflowAgentPreset;
+    /** 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 named agent presets; a task's `agentType` selects one. Persisted on the snapshot (Story 2.2). */
+    agentPresets?: Record<string, WorkflowAgentPreset>;
+    /** 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;
+    private readonly logger?;
+    constructor(options: {
+        agentManager: AgentManager;
+        storage: WorkflowStorage;
+        coalesceWindowMs?: number;
+        timers?: WorkflowProjectionTimers;
+        logger?: WorkflowManagerLogger;
+    });
+    /**
+     * 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[]>;
+    /**
+     * Readiness predicate for the spawn scheduler - a pure function of `live`.
+     *
+     * Returns, in `graph.tasks` array order (so spawn order is deterministic), the NODE of
+     * every task that is not yet spawned, not yet terminal, and whose every declared
+     * dependency has already recorded a `"success"` outcome. Nodes, not ids: both callers
+     * need the node to spawn it, and returning ids made each of them re-scan `graph.tasks`
+     * (an O(n^2) lookup) behind an unreachable `if (!node) continue` guard.
+     *
+     * Readiness is computed from `TaskNode.dependencies` DIRECTLY, never from
+     * `resolveExecutionLayers`, whose declared-layer branch returns
+     * `metadata.executionLayers` verbatim and unvalidated, and never from layer output.
+     *
+     * A dependency id absent from `terminalOutcomes` is NOT satisfied. That single rule
+     * also makes an out-of-graph dependency unsatisfiable: a ghost id can never gain a
+     * terminal outcome, because outcomes are only ever written for real spawned children.
+     * This is a DELIBERATE divergence from `computeLayersFromDependencies`
+     * (workflow-progress.ts:268), whose `|| !byId.has(dep)` clause treats an out-of-graph
+     * dep as already met so it can keep layering already-stored graphs. Under a scheduler,
+     * "satisfied because it does not exist" would launch a task whose stated precondition
+     * was never met.
+     *
+     * Performs no I/O, no clock read and no `agentManager` call.
+     */
+    private readyTaskNodes;
+    /**
+     * Drive a workflow's FIRST spawn wave: transition pending -> running, then spawn
+     * exactly the tasks that are ready: those whose declared `dependencies` are already
+     * satisfied. On a fresh graph that is the dependency-free set; a task that declares a
+     * dependency is deliberately NOT launched here, which is what makes
+     * `TaskNode.dependencies` a real runtime constraint rather than a decorative field.
+     *
+     * Parallelism is residual, not declared: two tasks run together because nothing holds
+     * them, not because a layer listed them side by side.
+     *
+     * This method never launches a later wave. Tasks unblocked by a child reaching a
+     * terminal state are launched by the continuation path (Story 1.2), driven from
+     * `onAgentEvent`, not from here. 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.
+     *
+     * `config` arrives ALREADY RESOLVED by the caller (`resolveTaskConfig`, Story 2.1);
+     * this method performs no resolution of its own, so one helper serves both spawn
+     * call sites with no duplicated precedence rule.
+     *
+     * Returns the child on the normal path and `undefined` when the workflow was cancelled
+     * mid-spawn and the child was discarded (gate 1.002 NIT-4). The two cases are otherwise
+     * indistinguishable to a caller - same type, same shape - and the discarded agent is a
+     * corpse: archived, and deliberately absent from `childAgentIds`. `undefined` is the
+     * only honest way to say "there is no child here" through a public surface.
+     */
+    spawnPhaseAgent(args: {
+        workflowId: string;
+        node: TaskNode;
+        config: AgentSessionConfig;
+    }): Promise<ManagedAgent | undefined>;
+    /**
+     * Tear down a child that was created for a workflow which went terminal mid-spawn.
+     * Uses `archiveAgent`, the same public surface {@link cascadeArchiveChildren} uses, so
+     * the child is closed and marked archived rather than left running for a workflow
+     * nobody is watching. The child id is deliberately NOT appended to the snapshot: a
+     * cancelled workflow gains no children.
+     *
+     * Best effort and never throws. It runs on the failure path of a spawn that has already
+     * happened; a teardown error must not turn into a rejected `startWorkflow`, nor into an
+     * unhandled rejection from the detached continuation IIFE.
+     */
+    private discardOrphanedChild;
+    /**
+     * 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. Reacts only to child state changes for an
+     * agent tagged to a tracked, RUNNING workflow (pending, cancelled and finished
+     * workflows are all rejected by the early return). It does three things:
+     *
+     * 1. Records the child's terminal outcome while the event still carries the closed
+     *    agent (Story 3.1),
+     * 2. Drives ORCHESTRATION (Story 1.2): every surviving event sweeps the graph for
+     *    tasks whose dependencies just became satisfied and spawns them. This is the
+     *    only continuation path; there is no poll loop and no second `startWorkflow`, and
+     * 3. SETTLES the workflow (Story 1.3): once every declared task has a terminal
+     *    outcome it flips to `completed`, and the first `failed` outcome flips it to
+     *    `failed`, freezing the projected counts into the snapshot at that instant.
+     *
+     * Then it schedules a coalesced projection emit for the workflow. Continuation runs
+     * ALONGSIDE that emit, never behind it: the 60 ms window throttles display, and
+     * routing scheduling through it would add a window's dead time per graph edge.
+     *
+     * MUST stay synchronous and MUST NOT throw. `AgentManager.dispatch` invokes
+     * `subscriber.callback(event)` with no try/catch (agent-manager.ts:3992), so a throw
+     * here starves every later subscriber and propagates out of the caller's
+     * `await closeAgent(id)`. Making it `async` is the other half of the same bug:
+     * `dispatch` ignores the returned promise, so a rejection becomes an unhandled one.
+     */
+    private onAgentEvent;
+    /**
+     * Spawn every task whose dependencies have just become satisfied. Takes the ALREADY
+     * RESOLVED `LiveWorkflow` rather than a workflow id, so it can never call
+     * `requireLive` and can never throw `WorkflowNotFoundError` synchronously into
+     * `AgentManager.dispatch`. Returns `void`, never a promise, and never throws.
+     *
+     * The ENTRY guard deliberately lives in the caller (`onAgentEvent`'s early return), not
+     * here: a workflow that is not `running` never reaches this method, so cancellation
+     * wins for free with no second entry guard to keep in sync. The re-read inside the
+     * detached loop is a different question - not "may I start?" but "is this still true
+     * after the last await?" - and it has no equivalent in the caller, which returned long
+     * before that loop runs.
+     *
+     * Readiness comes from `readyTaskNodes`, the single Story 1.1 rule. This method adds no
+     * second readiness rule, does not flip the workflow status, does not stamp
+     * `completedAt` and does not record an outcome for a task whose spawn failed:
+     * inventing a failure outcome here would change the projection's counts.
+     */
+    private continueWorkflow;
+    /**
+     * Settle the workflow to a terminal status once its graph has finished. Takes the
+     * ALREADY RESOLVED `LiveWorkflow`, never a workflow id, so it can never call
+     * `requireLive` and can never throw `WorkflowNotFoundError` into
+     * `AgentManager.dispatch`.
+     *
+     * The rule is read THROUGH `graph.tasks`, not off `terminalOutcomes.values()`. With the
+     * ledger keyed on `live.childTaskIds` (gate 1.003 MINOR-4) an out-of-graph key can no
+     * longer enter the map at all, so this is a second layer rather than the only one; it is
+     * kept because it costs nothing and it is the layer that survives if the key ever becomes
+     * derivable from an event again. Mapping the declared tasks over the map also means a
+     * partially populated ledger reads as "not finished" rather than as "finished".
+     *
+     * Everything up to the first `await` is synchronous ON PURPOSE. `AgentManager.dispatch`
+     * is a plain synchronous loop invoked from inside `await closeAgent(...)`, so the status
+     * flip and the frozen counts are committed to memory before that expression resolves -
+     * which is what lets a caller read the terminal snapshot on the very next line with no
+     * polling. Only `persist` and `emit` are asynchronous.
+     *
+     * Children are never cancelled, closed, archived or interrupted here: an independent
+     * in-flight sibling keeps running after a failure.
+     */
+    private settleWorkflow;
+    /**
+     * 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