@hyperdrive.bot/paseo-server 0.3.42 → 0.3.44

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

@@ -1,16 +1,28 @@
-import type { WorkflowLifecycleEvent, WorkflowSnapshot } from "@hyperdrive.bot/paseo-protocol/messages";
+import type { WorkflowAgentPreset, 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 { 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. */
+/** 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.
+ * 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
@@ -41,12 +53,14 @@ export interface TaskNode {
     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. */
+    /** Execution layers - each layer runs in parallel, layers run sequentially. */
     executionLayers: string[][];
     /** Maximum number of tasks that can run in parallel. */
     maxParallelism: number;
@@ -87,13 +101,15 @@ export interface CreateWorkflowInput {
     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. */
+    /** Optional owning agent id - children also carry PARENT_AGENT_ID_LABEL. */
     parentAgentId?: string;
 }
 /** Event emitted to workflow subscribers whenever a snapshot changes. */
@@ -121,11 +137,13 @@ export declare class WorkflowManager {
     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.
@@ -135,11 +153,11 @@ export declare class WorkflowManager {
     /**
      * 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}.
+     * 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.
+     * 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.
      */
@@ -147,7 +165,7 @@ export declare class WorkflowManager {
     /**
      * 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.
+     * current child-agent states - the persisted counter is never trusted as truth.
      */
     getWorkflow(id: string): Promise<WorkflowSnapshot>;
     /**
@@ -161,14 +179,48 @@ export declare class WorkflowManager {
     /**
      * 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
+     * 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.
+     * 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>;
     /**
@@ -176,14 +228,36 @@ export declare class WorkflowManager {
      * `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>;
+    }): Promise<ManagedAgent | undefined>;
     /**
-     * Archive every child agent tagged to the workflow — no orphans — mirroring
+     * 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
@@ -191,7 +265,7 @@ export declare class WorkflowManager {
      */
     cascadeArchiveChildren(workflowId: string): Promise<void>;
     /**
-     * Number of live snapshot subscribers. Read-only observability — used by the
+     * 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.
      */
@@ -200,23 +274,84 @@ export declare class WorkflowManager {
     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.
+     * 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.
+     * 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
+     * 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.