@yycholla/pi-dynamic-workflows 3.3.0

package/dist/workflow-manager.d.ts

@@ -0,0 +1,492 @@
+/**
+ * Workflow manager for background execution, pause/resume, and run management.
+ */
+import { EventEmitter } from "node:events";
+import type { ModelRegistry, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { WorkflowAgent } from "./agent.js";
+import { type WorkflowAgentSnapshot, type WorkflowSnapshot } from "./display.js";
+import { WorkflowError } from "./errors.js";
+import { type PersistedRunState, type RunLease, type RunPersistence, type RunStatus } from "./run-persistence.js";
+import { type JournalEntry, type WorkflowRunResult } from "./workflow.js";
+export interface ManagedRun {
+    runId: string;
+    status: RunStatus;
+    snapshot: WorkflowSnapshot;
+    result?: WorkflowRunResult;
+    error?: WorkflowError;
+    controller: AbortController;
+    startedAt: Date;
+    /** The real script, kept so the run can be resumed. */
+    script: string;
+    args?: unknown;
+    /** Accumulated agent results for resume (deterministic call index -> result). */
+    journal: JournalEntry[];
+    /** Cross-process execution lease for this run, when it is actively executing. */
+    lease?: RunLease;
+    /**
+     * True when the run was started in the background (or resumed) and the caller is
+     * not awaiting its result inline. Only background runs deliver their result back
+     * into the conversation; a foreground sync run already returns it as the tool
+     * result, so re-delivering would duplicate it.
+     */
+    background: boolean;
+    /**
+     * Auto-resume eligibility for this run (see ExecOptions.autoResume). Set once
+     * at creation and carried through resume() so it survives pause/resume cycles.
+     * Undefined means eligible (default-on); false opts out.
+     */
+    autoResume?: boolean;
+    /**
+     * The run's resolved hard token budget (per-run value, else the manager
+     * default), fixed at run start and carried through resume() — a resumed run
+     * must keep the budget it started with, not re-resolve against the current
+     * default (an explicit `null` opt-out would otherwise regain a budget).
+     */
+    tokenBudget?: number | null;
+    /**
+     * Named toolset tag for this run (see WorkflowManagerOptions.toolsets).
+     * ToolDefinitions are functions and can't be persisted, so the tag is what
+     * survives on disk — resume() re-resolves it so e.g. a resumed
+     * `/deep-research` run keeps its web tools instead of silently degrading to
+     * the default coding tools.
+     */
+    toolset?: string;
+    /**
+     * Real per-agent start/end timestamps, captured at onAgentStart/onAgentEnd
+     * (never fabricated), keyed by the agent's snapshot id. A running agent has
+     * an entry with no endedAt; persistRun() reads from here instead of stamping
+     * every agent with the run's startedAt / "now".
+     */
+    agentTimestamps: Map<number, {
+        startedAt: string;
+        endedAt?: string;
+    }>;
+    /**
+     * Live snapshot-agent lookup keyed by the agent CALL's unique id (see
+     * WorkflowRunOptions.onAgentStart/onAgentEnd/onAgentHistory's `id` field in
+     * workflow.ts — unique per call, never per label). onAgentEnd/onAgentHistory
+     * must resolve the snapshot entry to update through this map, never by
+     * scanning managed.snapshot.agents for a label match: two concurrent agents
+     * routinely share a label (e.g. parallel()'s default `"${phase} agent N"`
+     * labeling, or an author-supplied label reused across a fan-out), and a
+     * label+status scan would update whichever same-label entry it happens to
+     * find first — misattributing one agent's end/history event to a different,
+     * still-running sibling.
+     */
+    agentsById: Map<string, WorkflowAgentSnapshot>;
+    /**
+     * The run's cap on total agents (per-run value, else left undefined so
+     * runWorkflow applies its own MAX_AGENTS_PER_RUN default), fixed at run
+     * start/resume and carried through resume() — mirrors ManagedRun.tokenBudget
+     * exactly: a resumed run must keep the cap it started with, not silently
+     * regain the (much larger) default because ExecOptions.maxAgents isn't
+     * threaded through resume()'s executeRun() call.
+     */
+    maxAgents?: number;
+    /**
+     * The run's resolved per-agent timeout (per-run value, else the manager
+     * default at the time), fixed at run start/resume — same rationale as
+     * tokenBudget/maxAgents: resume() must not re-resolve against the manager's
+     * CURRENT defaultAgentTimeoutMs.
+     */
+    agentTimeoutMs?: number | null;
+    /**
+     * The run's resolved concurrency (per-run value, else the manager's
+     * concurrency at the time), fixed at run start/resume for the same reason
+     * as tokenBudget.
+     */
+    concurrency?: number;
+    /**
+     * The run's resolved agent-retry count (per-run value, else the manager
+     * default at the time), fixed at run start/resume for the same reason as
+     * tokenBudget.
+     */
+    agentRetries?: number;
+}
+/** Per-execution options shared by sync, background, and resume runs. */
+export interface ExecOptions {
+    /**
+     * Replay these journaled agent/checkpoint results for the unchanged prefix
+     * (resume), keyed by `${runId}:${index}` — see
+     * WorkflowRunOptions.resumeJournal in workflow.ts.
+     */
+    resumeJournal?: Map<string, JournalEntry>;
+    /** Cap on total agents for this run. */
+    maxAgents?: number;
+    /** Per-agent timeout in milliseconds. null/omitted means no hard timeout. */
+    agentTimeoutMs?: number | null;
+    /** Host signal (e.g. tool/Esc) that should abort this run when fired. */
+    externalSignal?: AbortSignal;
+    /** Called with the live snapshot on every progress event. */
+    onProgress?: (snapshot: WorkflowSnapshot) => void;
+    /** Hard token budget for this run; once spent reaches it, agent() throws. */
+    tokenBudget?: number | null;
+    /**
+     * Tool set for this run's subagents, replacing the default coding tools —
+     * e.g. built-in `/deep-research` appends web tools. Omit for the default.
+     * Not persistable (functions): pair with `toolset` so a resumed run can
+     * re-resolve the same tools.
+     */
+    tools?: ToolDefinition[];
+    /**
+     * Named toolset tag, resolved via WorkflowManagerOptions.toolsets. Persisted
+     * with the run and re-resolved on resume(). When both `tools` and `toolset`
+     * are given, `tools` wins for this execution and `toolset` is what resumes use.
+     */
+    toolset?: string;
+    /** Max concurrent agents for this execution. */
+    concurrency?: number;
+    /** Retry attempts after recoverable agent failures for this execution. */
+    agentRetries?: number;
+    /** Resolve a checkpoint() question with a human reply (only for UI-bearing runs). */
+    confirm?: (promptText: string, options: unknown) => Promise<unknown>;
+    /**
+     * Whether this run is eligible for auto-resume when it pauses on a provider
+     * usage limit. Default-on: omit or pass true to stay eligible, pass false to
+     * opt out. Persisted on the run so a cold-start UsageLimitScheduler respects
+     * it too. See usage-limit-scheduler.ts.
+     */
+    autoResume?: boolean;
+    /**
+     * Seed for the execution's cumulative token counters — passed through to
+     * runWorkflow's WorkflowRunOptions.initialTokenUsage. Only resume() sets
+     * this (from the persisted run's tokenUsage-at-pause), so the resumed
+     * execution's fresh SharedRuntime starts counting from the already-spent
+     * total instead of zero (see A2 in workflow-manager's resume()).
+     */
+    initialTokenUsage?: {
+        input: number;
+        output: number;
+        total: number;
+        cost: number;
+        cacheRead: number;
+        cacheWrite: number;
+    };
+}
+export interface WorkflowManagerOptions {
+    cwd?: string;
+    concurrency?: number;
+    /** Resolve a saved-workflow name to its script, enabling nested `workflow('name')`. */
+    loadSavedWorkflow?: (name: string) => string | undefined;
+    /** Inject a custom agent runner (tests); defaults to a real subagent session. */
+    agent?: Pick<WorkflowAgent, "run">;
+    /** The session's main model (provider/id), for auto-tiering explore agents. */
+    mainModel?: string;
+    /**
+     * The host Pi session's model registry. When provided, workflow subagents
+     * resolve models against the same registry as the main session, including
+     * extension-registered providers such as ollama-cloud.
+     */
+    modelRegistry?: ModelRegistry;
+    /** The pi session id to tag runs with (see setSessionId). */
+    sessionId?: string;
+    /** Default per-agent timeout when a run does not pass agentTimeoutMs. null means no hard timeout. */
+    defaultAgentTimeoutMs?: number | null;
+    /** Default retry attempts after recoverable agent failures. */
+    defaultAgentRetries?: number;
+    /** Default hard token budget when a run does not pass tokenBudget. null/omitted means no budget. */
+    defaultTokenBudget?: number | null;
+    /**
+     * Named toolsets resolvable by ExecOptions.toolset — e.g.
+     * `{ "web-research": () => [...createCodingTools(cwd), ...createWebTools()] }`.
+     * Called lazily per execution (including on resume). An unknown tag resolves
+     * to the default coding tools.
+     */
+    toolsets?: Record<string, () => ToolDefinition[]>;
+    /**
+     * Extra tool NAMES to deny in every subagent session, on top of the always-on
+     * `workflow`/`workflow_control` defaults (see DEFAULT_EXCLUDED_SUBAGENT_TOOLS).
+     * Host wiring passes settings.excludeSubagentTools here so users can also block
+     * other recursive-orchestration tools (#107).
+     */
+    excludeSubagentTools?: string[];
+    /**
+     * Persist each subagent transcript as a real pi session file under the
+     * standard sessions directory. Default false (in-memory, discarded).
+     */
+    persistAgentSessions?: boolean;
+    /**
+     * How many terminal (completed/failed/aborted) runs to retain full
+     * in-memory state for before the oldest is evicted from `runs` (see the
+     * class-level doc comment on that field). Defaults to
+     * DEFAULT_MAX_TERMINAL_RUNS_IN_MEMORY; exposed mainly for tests that want
+     * to observe eviction without creating dozens of runs.
+     */
+    maxTerminalRunsInMemory?: number;
+}
+/** Options that a fresh extension generation may safely refresh on a live
+ * manager handed across `/reload`. Execution identity (`cwd`, persistence,
+ * injected agent, and in-memory runs) is intentionally excluded. */
+export type WorkflowManagerReloadOptions = Pick<WorkflowManagerOptions, "concurrency" | "loadSavedWorkflow" | "defaultAgentTimeoutMs" | "defaultAgentRetries" | "defaultTokenBudget" | "toolsets" | "excludeSubagentTools" | "persistAgentSessions">;
+export declare class WorkflowManager extends EventEmitter {
+    /**
+     * Lifecycle contract for `runs`:
+     *
+     *  - An entry is added when a run starts (startInBackground/runSync) or is
+     *    resumed (resume()), always with a live AbortController and (usually)
+     *    an active RunLease.
+     *  - While status is "running" or "paused", the entry is NEVER evicted —
+     *    its execution could still settle (a pending executeRun() promise) or
+     *    it is mid-usage-limit-checkpoint/manually-paused and still considered
+     *    "the current state of this run" by callers. Eviction only ever
+     *    considers an entry AFTER executeRun() has fully settled it to
+     *    "completed" | "failed" | "aborted" (see IN_MEMORY_TERMINAL_STATUSES)
+     *    and persisted + released its lease — i.e. strictly after the same
+     *    isCurrent()-gated persistRun()/releaseRunLease() calls in
+     *    executeRun()'s success/catch tails.
+     *  - Once terminal, an entry becomes eviction-ELIGIBLE (recordTerminalRun())
+     *    but is not necessarily evicted immediately: up to
+     *    maxTerminalRunsInMemory terminal entries are kept, oldest evicted
+     *    first, so a `getRun()` call immediately after completion (e.g. the
+     *    "complete" event's own synchronous listeners — task-panel's result
+     *    delivery, `/workflows watch`) still sees the live object. Once
+     *    evicted, the entry is simply removed from `runs`; nothing else reads
+     *    or writes it again.
+     *  - Every caller of getRun()/getSnapshot() must treat "undefined"/null as
+     *    "no live in-memory copy right now" and fall back to listRuns() (backed
+     *    by run-persistence.ts, which is what's authoritative for a run once
+     *    the in-memory copy is gone) — this mirrors how those callers already
+     *    treat any run this process never had in memory (e.g. one started by a
+     *    different process and only ever seen via listRuns()). resume() never
+     *    depends on `runs` for a run's state either: it always reloads from
+     *    persistence, so an evicted runId resumes exactly like one from a
+     *    prior process.
+     *  - isCurrent(managed) composes with eviction the same way it composes
+     *    with resume()/deleteRun() replacing or removing an entry: eviction
+     *    removes the map entry outright, so a stale execution's later settle
+     *    (isCurrent() check) sees `this.runs.get(runId) !== managed` (in fact
+     *    undefined) and correctly no-ops, exactly as it would after
+     *    resume()/deleteRun().
+     */
+    private runs;
+    /**
+     * FIFO of runIds that reached IN_MEMORY_TERMINAL_STATUSES, oldest first —
+     * the eviction order for `runs` (see its doc comment). A runId can appear
+     * more than once (e.g. resumed after eviction, then terminates again);
+     * evicting is idempotent (recordTerminalRun() re-checks the CURRENT status
+     * of the current map entry for that id before deleting), so duplicates
+     * are harmless.
+     */
+    private terminalRunQueue;
+    private maxTerminalRunsInMemory;
+    private persistence;
+    private cwd;
+    private concurrency;
+    private loadSavedWorkflow?;
+    private agent?;
+    /** The session's main model (provider/id), for auto-tiering explore agents. */
+    private mainModel?;
+    /** The host Pi session's model registry, shared with subagents. */
+    private modelRegistry?;
+    /** The current pi session id; runs are stamped with it and listRuns() filters by it. */
+    private sessionId?;
+    private defaultAgentTimeoutMs;
+    private defaultAgentRetries;
+    private defaultTokenBudget;
+    private toolsets?;
+    private excludeSubagentTools?;
+    private persistAgentSessions;
+    constructor(options?: WorkflowManagerOptions);
+    /** Bind the manager to the current pi session, so new runs are tagged with it and
+     * the navigator/task-panel show only this session's runs (set on session_start). */
+    setSessionId(id: string | undefined): void;
+    /**
+     * On startup, any persisted run still marked "running" belongs to a process
+     * that died mid-run (this fresh manager has it nowhere in memory). Reconcile it
+     * to "paused" — never "failed" — so its journal is preserved and resume() can
+     * replay the completed prefix and finish the rest.
+     */
+    private recoverStaleRuns;
+    /**
+     * Refresh host configuration after Pi reloads the extension while retaining
+     * this manager's live runs, controllers, leases, and event listeners.
+     * Existing executions keep the options they captured at start; subsequent
+     * runs and resumes use these refreshed defaults.
+     */
+    reconfigureAfterReload(options: WorkflowManagerReloadOptions): void;
+    /** Set the session's main model (provider/id). Used to auto-tier explore agents. */
+    setMainModel(spec: string | undefined): void;
+    /** Set the host session's model registry so subagents resolve models consistently. */
+    setModelRegistry(registry: ModelRegistry): void;
+    /**
+     * Expose the host session's model registry to integrations sharing this
+     * manager. Workflow execution reads the same registry internally.
+     */
+    getModelRegistry(): ModelRegistry | undefined;
+    /**
+     * Start a workflow in the background.
+     * Returns immediately with a run ID; the workflow executes asynchronously.
+     */
+    startInBackground(script: string, args?: unknown, exec?: ExecOptions): {
+        runId: string;
+        promise: Promise<WorkflowRunResult>;
+    };
+    /**
+     * Execute a workflow synchronously (blocking) while still tracking it like a
+     * background run, so the `/workflows` navigator and the live task panel see it.
+     * `onProgress` fires on every progress event with the current snapshot, letting
+     * a caller (e.g. the workflow tool) drive its own inline display.
+     */
+    runSync(script: string, args?: unknown, exec?: ExecOptions): Promise<WorkflowRunResult>;
+    /** Build a fresh managed run with an empty snapshot. */
+    private createManaged;
+    private executeRun;
+    /**
+     * True when `managed` is still the live, current entry for its runId in
+     * `this.runs` — false once resume() has replaced it with a new ManagedRun
+     * object for the same runId, or deleteRun() has removed it entirely. A
+     * superseded ManagedRun's async completion (executeRun's promise settling
+     * well after something else already took over or tore down that runId)
+     * must not write to disk or touch lease state on the newer execution's
+     * behalf — see writeRunToDisk() and executeRun()'s post-await persist calls.
+     */
+    private isCurrent;
+    /**
+     * Emit an event on behalf of `managed`, but only while it's still the
+     * current entry for its runId (see isCurrent()) — mirrors the disk/lease
+     * guard for the observer-facing side of the same problem. A superseded
+     * execution's progress/terminal events (log, phase, agentStart/End,
+     * tokenUsage, complete, error, paused) are not just stale-but-harmless:
+     * "complete" in particular can drive background result delivery into the
+     * conversation, so letting a deleted/superseded run's stale settle still
+     * fire it would deliver a result for a run that, from the caller's POV, no
+     * longer exists (or has since been superseded by a newer execution whose
+     * own events already tell the true story). No event in this set has a
+     * legitimate reason to still reach listeners once superseded — unlike
+     * disk writes there's no "expected race, harmless no-op" nuance here, it's
+     * simply wrong to notify twice (or for a run that's gone). Events emitted
+     * directly by pause()/stop()/resume()/deleteRun() themselves are NOT routed
+     * through this helper — those methods own the transition and ARE current
+     * at the moment they fire, same precedent as their persist/lease calls.
+     */
+    private emitLive;
+    /**
+     * Mark `runId` as eviction-eligible now that its execution has genuinely
+     * settled to a terminal status (completed/failed/aborted — see
+     * IN_MEMORY_TERMINAL_STATUSES), and evict the oldest eligible entries
+     * beyond maxTerminalRunsInMemory. Callers must only invoke this after the
+     * same isCurrent()-gated persistRun()/releaseRunLease() sequence executeRun()
+     * already uses (see the `runs` field doc comment for the full contract) —
+     * this method itself re-validates the CURRENT entry's status before
+     * deleting anything, so it never evicts a run that isn't (or is no longer)
+     * genuinely terminal, including one resumed back to "running" after being
+     * queued here but before its turn to be evicted came up.
+     */
+    private recordTerminalRun;
+    /**
+     * Additively fold one agent-call's token cost into the run-wide persisted
+     * aggregate (managed.snapshot.tokenUsage), seeded (on resume) from the
+     * persisted total-at-pause — see A2. Shared by onAgentEnd (a completed or
+     * finally-failed agent call) and onRetrySpend (a failed attempt that WILL
+     * be retried, whose cost recordTokens() already folded into
+     * shared.spent/tokenUsage in workflow.ts, but which onAgentEnd never sees —
+     * see WorkflowRunOptions.onRetrySpend for why that needs its own channel).
+     */
+    private accumulateTokenUsage;
+    private releaseRunLease;
+    /** Trailing-edge throttle window for high-frequency progress persists (see schedulePersist). */
+    private static readonly PERSIST_THROTTLE_MS;
+    /** Pending trailing-edge persist timers for high-frequency progress events, keyed by runId. */
+    private persistTimers;
+    /**
+     * Coalesce rapid progress persists (currently: onAgentJournal, which fires
+     * once per completed agent and can burst under concurrency) to at most one
+     * disk write per PERSIST_THROTTLE_MS (trailing edge) instead of one write
+     * per tick — persistRun() does a full JSON.stringify of the run plus up to
+     * 3 sync writes, so firing it once per agent in a long run is O(N^2).
+     *
+     * Lifecycle-critical writes (status transitions, run end, pause/resume/stop)
+     * must NOT use this — call persistRun() directly, which flushes (and cancels)
+     * any pending timer first so a stale trailing write can never fire after, and
+     * resurrect, a terminal state.
+     */
+    private schedulePersist;
+    /**
+     * Persist immediately and synchronously. Cancels any pending throttled write
+     * for this run first, so the write that lands is always the caller's current
+     * (final) state — never superseded by a stale deferred write. Use this for
+     * every lifecycle-critical persist: run start, status transitions, run end,
+     * pause()/resume()/stop().
+     */
+    private persistRun;
+    private writeRunToDisk;
+    /**
+     * Pause a running workflow.
+     */
+    pause(runId: string): boolean;
+    /**
+     * Resume an interrupted run: replay journaled results for the unchanged prefix
+     * and run the rest live. Returns false if there is nothing resumable.
+     *
+     * `opts.script` lets the orchestrating model resume with an EDITED script
+     * (cached-prefix reuse / iteration): unchanged agent() calls whose content
+     * hash still matches the journal entry at their positional callIndex replay
+     * from cache, while the first changed or newly inserted call — and everything
+     * after it — re-runs live. When `opts.script` is omitted, resume behaves
+     * exactly as before and uses the persisted script (auto-resume, TUI resume);
+     * this keeps the existing single-arg `resume(runId)` callers (e.g. the
+     * UsageLimitScheduler) unchanged. `opts.args` overrides the persisted args
+     * only when provided; otherwise the persisted args are kept.
+     */
+    resume(runId: string, opts?: {
+        script?: string;
+        args?: unknown;
+    }): Promise<boolean>;
+    /**
+     * Stop a running workflow.
+     *
+     * Fast path: the run is live in this process (`this.runs`) — abort its
+     * controller and persist "aborted" as before. Fallback: the run is not in
+     * memory but is persisted as "running" or "paused" — e.g. it belongs to a
+     * prior pi session that this process's recoverStaleRuns() flipped to
+     * "paused" on disk without repopulating this.runs (see workflow-control-tool's
+     * findRun(), which resolves candidates from disk via listRuns()). There is no
+     * live controller to abort in that case — the run simply isn't executing in
+     * this process — so mark it aborted on disk directly, mirroring resume()'s
+     * persisted-fallback lease handling.
+     */
+    stop(runId: string): boolean;
+    /**
+     * Get status of a specific run.
+     */
+    getRun(runId: string): ManagedRun | undefined;
+    /**
+     * List all runs (active + persisted).
+     */
+    /**
+     * Runs for the navigator/task panel. Once bound to a session (setSessionId), only
+     * that session's runs are returned — runs from other sessions stay on disk and
+     * reappear when you switch back. Unbound (tests/legacy) returns everything.
+     */
+    listRuns(): PersistedRunState[];
+    /** All persisted runs regardless of session (used by cross-session recovery). */
+    listAllRuns(): PersistedRunState[];
+    /**
+     * Get snapshot of a run.
+     */
+    getSnapshot(runId: string): WorkflowSnapshot | null;
+    /**
+     * Delete a persisted run.
+     *
+     * If `runId` is still live in this process (running or paused-in-memory),
+     * abort its controller FIRST, before any teardown below — a live run left
+     * un-aborted would otherwise keep executing in the background indefinitely
+     * (burning API calls/tokens/holding a worktree) after its record is gone.
+     * Aborting first, while `managed` is still `this.runs.get(runId)`, costs
+     * nothing extra: the abort signal is fire-and-forget (cooperative — the
+     * execution winds down on its own schedule), so the exact instant we flip
+     * `this.runs`/release the lease/delete files relative to it doesn't matter
+     * for correctness. What DOES matter is that once this method returns, the
+     * aborted execution's eventual settle (executeRun's success/catch path,
+     * asynchronously, possibly much later) must be a harmless no-op rather than
+     * a resurrection — that's what isCurrent() guarantees: `this.runs.delete()`
+     * below means executeRun's later persistRun()/releaseRunLease() calls on
+     * this same `managed` object find `this.runs.get(runId) !== managed` (in
+     * fact `undefined`, since the entry is gone) and skip writing/releasing.
+     */
+    deleteRun(runId: string): boolean;
+    /**
+     * Get the persistence layer (for saving workflows).
+     */
+    getPersistence(): RunPersistence;
+}