@intx/workflow-host 0.2.2

package/dist/supervisor/supervisor.d.ts

@@ -0,0 +1,202 @@
+import type { InferenceSource } from "@intx/types/runtime";
+import type { CancelOrigin } from "@intx/workflow";
+import { type EventPayload } from "../ipc/index.js";
+import { type CredentialsSnapshot } from "./credentials.js";
+import { type RecycleAttempt, type RecycleOrigin } from "./recycle.js";
+import type { WorkflowSupervisorBindings } from "./types.js";
+/**
+ * Default watchdog timeout for the supervisor's
+ * `synchronouslyDispatchTerminalWrite`. The handler holds the
+ * `substrate.write.response` back to the child until the dispatch
+ * loop's `markConsumed` settles for the matching terminal event; an
+ * unbounded wait would chain into a child / runtime / dispatch loop
+ * deadlock if `markConsumed` never armed (bug in the dispatch loop, a
+ * torn-down cohort, a stalled inbox primitive). 30s sits between the
+ * recycle path's `DEFAULT_KILL_TIMEOUT_MS` (5s, a hard process-level
+ * kill cap) and `DEFAULT_DRAIN_TIMEOUT_MS` (60s, the per-deployment
+ * drain budget) -- generous enough to absorb a slow legitimate
+ * markConsumed, tight enough to surface a real deadlock long before
+ * the drainTimeout would otherwise mask it.
+ */
+export declare const DEFAULT_TERMINAL_WRITE_WATCHDOG_MS = 30000;
+/**
+ * Public surface returned by `createWorkflowSupervisor`. Each method
+ * advances the supervisor through one lifecycle transition; the
+ * supervisor's internal state is encapsulated.
+ */
+export interface WorkflowSupervisor {
+    /**
+     * Spawn the workflow-process child, complete the IPC handshake,
+     * assemble the credentialsSnapshot, register the deployment's mail
+     * address, and begin forwarding inbound mail. Resolves once the
+     * child's `ready` frame has been received and credentials have
+     * been pushed.
+     */
+    spawn(opts: SpawnOpts): Promise<SpawnResult>;
+    /**
+     * Sign and commit a CancelRequested event under the named origin.
+     * Used by the host directly for `supervisor-operator` and `hub-
+     * admin` origins; the `self` origin is invoked indirectly by the
+     * supervisor when the child requests cancellation over the
+     * control IPC.
+     */
+    requestCancel(opts: CancelRequestOpts): Promise<CancelCommitInfo>;
+    /**
+     * Tear the deployment down: unregister the mail address, kill the
+     * child, dispose subscriptions, await child exit. Idempotent.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Send the supervisor's `drain` control mail to the child and arm
+     * a drainTimeout accumulator against every in-flight run. The
+     * child's `DrainController` flips its signal on receipt and the
+     * runtime body picks the change up at the four observation
+     * points; cancel-mode steps abort locally, wait-mode steps continue
+     * running. On accumulator expiry, the supervisor commits a signed
+     * `CancelRequested{origin: "supervisor-drain"}` per run via the
+     * accumulator's existing path. The promise resolves once the
+     * `drain` mail has been forwarded; the accumulators tick in the
+     * background and stop on shutdown or terminal-phase reach. The
+     * recycle path reuses this primitive verbatim for its drain step.
+     */
+    drain(opts: DrainOpts): Promise<void>;
+    /**
+     * Recycle the child: drain -> kill -> respawn with a fresh
+     * channelId. Funnels every recycle origin (operator command,
+     * supervisor policy, child self-initiated) through the same
+     * `triggerRecycle` code path.
+     */
+    recycle(opts: RecycleOpts): Promise<RecycleAttempt>;
+    /**
+     * Deliver a workflow-run signal to the child by sending a
+     * `signal.deliver` control IPC frame. The child commits the
+     * resulting `SignalReceived` event through its own substrate, which
+     * keeps the workflow-run repo's single-writer invariant intact -- the
+     * child is the only writer of `runs/<runId>/events/` on the sidecar
+     * side, and the pack-push pipeline propagates the commit to the hub
+     * without racing against a concurrent host-side write.
+     *
+     * Throws when the supervisor is not in a phase where it can address
+     * the child (idle / stopping / stopped); the caller is responsible
+     * for serializing delivery against `spawn` completion.
+     */
+    deliverSignal(opts: DeliverSignalOpts): Promise<void>;
+    /**
+     * Push a rotated inference-source list to the child's warm single-step
+     * agent. Mirrors `deliverSignal`: the supervisor is the single producer
+     * of `sources-updated` control frames, and delivery is phase-guarded to
+     * starting/running so a frame is never written into a recycling child's
+     * closing pipe. Throws otherwise.
+     */
+    deliverSources(opts: DeliverSourcesOpts): Promise<void>;
+    /**
+     * Current snapshot of the credentials pushed to the child. Surfaced
+     * so the host can audit the per-step contentHash without
+     * round-tripping the substrate. Returns `null` before spawn.
+     */
+    getCredentialsSnapshot(): CredentialsSnapshot | null;
+}
+export type SpawnOpts = {
+    /** Step ids in this deployment's `stepOrder` for credentials assembly. */
+    stepOrder: readonly string[];
+    /** Content hash of the deployment's workflow definition. */
+    definitionHash: string;
+    /**
+     * Whether the spawned child warm-keeps its agent across messages
+     * (design §3b). The host sets this true only for the single-step
+     * long-lived deployment the deploy projection marked a warm candidate;
+     * the supervisor threads it into the child's spawn env as `WARM_KEEP`
+     * so the child's run-loop builds a warm-agent cache. Carried
+     * explicitly so the warm-keep decision is deterministic and survives
+     * recycle (the recycle path re-spawns with the same env).
+     */
+    warmKeep: boolean;
+    /**
+     * Callback the supervisor invokes for each verified InferenceEvent
+     * the child publishes. Mirrors the existing `agent.event` event
+     * sink the host exposes; the supervisor is the in-host translator.
+     */
+    onInferenceEvent: (event: EventPayload) => void;
+};
+export type SpawnResult = {
+    /** Child process pid. */
+    pid: number;
+    /** IPC channelId minted for this spawn. */
+    channelId: string;
+    /** Initial credentials snapshot pushed to the child. */
+    credentialsSnapshot: CredentialsSnapshot;
+};
+export type CancelRequestOpts = {
+    runId: string;
+    origin: CancelOrigin;
+    reason: string;
+    /** ISO-8601 commit timestamp. */
+    at: string;
+};
+export type CancelCommitInfo = {
+    commitSha: string;
+    seq: number;
+};
+export type DrainOpts = {
+    /**
+     * Wire `deadlineMs` carried on the `drain` control frame so the
+     * child can echo the policy in its logs. The supervisor-side
+     * `drainTimeout` accumulator is driven by
+     * `WorkflowSupervisorBindings.drainTimeoutMs`, not by this value:
+     * the timeout policy is a per-deployment operator setting baked
+     * into the supervisor's bindings, not a per-call argument.
+     */
+    deadlineMs: number;
+};
+export type DeliverSignalOpts = {
+    /** Run the signal targets. The child rejects a delivery whose runId is unknown. */
+    runId: string;
+    /** Signal name the run's `awaitSignal` step matches against. */
+    signalName: string;
+    /**
+     * Producer-supplied dedup id. The workflow-run state machine
+     * rejects duplicate deliveries via `observedSignalIds`; callers
+     * mint a fresh value per call.
+     */
+    signalId: string;
+    /** Opaque signal payload the awaiter resolves with. */
+    payload: unknown;
+};
+export type DeliverSourcesOpts = {
+    /**
+     * The rotated ordered inference-source failover chain; element 0 is the
+     * active source. The wire boundary enforces a non-empty list with unique
+     * ids whose head is the default.
+     */
+    sources: InferenceSource[];
+    /** The default source id; the wire boundary requires it to equal `sources[0].id`. */
+    defaultSource: string;
+};
+export type RecycleOpts = {
+    reason: string;
+    /**
+     * Origin of the recycle request. Defaults to `"operator"` when the
+     * supervisor's caller-facing API is invoked directly; the policy
+     * timer wires `"policy"` and the child-side `recycle.request`
+     * upstream frame wires `"self"`.
+     */
+    origin?: RecycleOrigin;
+};
+/**
+ * Raised when a `pendingMerges` entry or a
+ * `markConsumedCompletionWaiters` waiter is rejected because the
+ * cohort it was registered against has been aborted (cohort transition
+ * during a recycle, or a supervisor shutdown). Callers awaiting the
+ * resolved value receive an instance of this error so the failure mode
+ * is recognisable from a generic substrate-merge or markConsumed
+ * failure.
+ */
+export declare class MergeAbortedError extends Error {
+    constructor(reason: string);
+}
+/**
+ * Construct a per-deployment supervisor. All host-specific
+ * dependencies are pulled in via `bindings`; nothing in the
+ * supervisor reaches into `process.env` or a singleton.
+ */
+export declare function createWorkflowSupervisor(bindings: WorkflowSupervisorBindings): WorkflowSupervisor;