@intx/workflow-host 0.2.2

package/dist/drain-controller.d.ts

@@ -0,0 +1,37 @@
+import { type DrainController } from "@intx/workflow";
+import type { DrainBehavior, WorkflowDefinition } from "@intx/workflow";
+export interface WorkflowHostDrainController extends DrainController {
+    /**
+     * Flip the drain signal. Idempotent; a second call after the
+     * signal has already aborted is a no-op so the supervisor's
+     * control-loop can re-deliver `drain` without breaking the
+     * accumulator's ordering.
+     */
+    requestDrain(): void;
+    /**
+     * Whether the drain has been requested. Distinct from
+     * `signal.aborted` only across the brief window where the signal
+     * has been aborted but a downstream observer has not yet read it.
+     */
+    readonly drainRequested: boolean;
+}
+export interface CreateWorkflowHostDrainControllerOpts {
+    /**
+     * The workflow definition the child loaded at startup. The
+     * controller consults this for `behaviorFor` resolution. The
+     * definition is immutable across the run lifetime; a redeploy
+     * tears the workflow-process down and respawns it.
+     */
+    definition: WorkflowDefinition;
+    /**
+     * Optional per-id override resolver. When supplied, the controller
+     * consults this before falling back to `resolveDrainBehavior`. The
+     * supervisor uses this for map-iteration steps whose runtime id
+     * shape (`<mapId>[<index>]`) the workflow definition does not
+     * carry directly; `resolveDrainBehavior` already handles the
+     * common case, so the override is reserved for host-specific
+     * extensions that diverge from the workflow-level conventions.
+     */
+    behaviorOverride?: (stepId: string) => DrainBehavior | undefined;
+}
+export declare function createWorkflowHostDrainController(opts: CreateWorkflowHostDrainControllerOpts): WorkflowHostDrainController;

package/dist/drain-controller.js

@@ -0,0 +1,46 @@
+// Production `DrainController` implementation for the workflow-host
+// child.
+//
+// The `@intx/workflow` runtime body observes drain at four sites
+// (main loop entry, retry-between-attempts in runStep, waitForTimer,
+// runAwaitSignal). Each observation consults `behaviorFor(stepId)`
+// to decide whether to abort the step's local controller. This file
+// supplies the production controller the workflow-process child wires
+// against the runtime env.
+//
+// The controller owns three pieces of state:
+//   1. An `AbortController` whose signal exposes drain status to the
+//      runtime body.
+//   2. A reference to the live `WorkflowDefinition` the child loaded;
+//      `behaviorFor` consults the primitive at the requested stepId
+//      and returns its declared drainBehavior.
+//   3. An `accumulatedCancelMs` counter the supervisor's drainTimeout
+//      accumulator reads. The runtime body increments it; the
+//      supervisor consults it without owning the writer.
+//
+// The supervisor calls `requestDrain()` when its control-loop receives
+// the `drain` mail; the controller flips its signal and the runtime
+// body's observation points pick up the change on their next tick.
+import { resolveDrainBehavior } from "@intx/workflow";
+export function createWorkflowHostDrainController(opts) {
+    const controller = new AbortController();
+    let requested = false;
+    return {
+        signal: controller.signal,
+        behaviorFor(stepId) {
+            const override = opts.behaviorOverride?.(stepId);
+            if (override !== undefined)
+                return override;
+            return resolveDrainBehavior(opts.definition, stepId);
+        },
+        requestDrain() {
+            if (requested)
+                return;
+            requested = true;
+            controller.abort();
+        },
+        get drainRequested() {
+            return requested;
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { createWorkflowRunRepoStore, type WorkflowRunRepoStoreOpts, } from "./adapters/repo-store.js";
+export { createWorkflowRunBlobSubstrate, type WorkflowRunBlobSubstrateOpts, } from "./adapters/blob-substrate.js";
+export { createWorkflowStepInvoker, type StepEnvBase, type WorkflowStepInvokerOpts, } from "./adapters/step-invoker.js";
+export { createWorkflowSpawnChild, type ChildTerminalStatus, type RunChildWorkflow, type WorkflowSpawnChildOpts, } from "./adapters/spawn-child.js";
+export { createWorkflowSupervisor, assembleCredentialsSnapshot, commitCancelRequested, createDrainTimeoutAccumulator, createRecyclePolicy, defaultStepRepoId, hashGrants, triggerRecycle, DEFAULT_DRAIN_TIMEOUT_MS, DEFAULT_KILL_TIMEOUT_MS, DEFAULT_POLICY_INTERVAL_MS, DEFAULT_TERMINAL_WRITE_WATCHDOG_MS, MAX_BUFFERED_MAIL, STEP_GRANTS_PATH, STEP_GRANTS_REF, SUPERVISOR_PRINCIPAL_KIND, type AssembleCredentialsSnapshotOpts, type CancelCommitInfo, type CancelRequestOpts, type CommitCancelRequestedOpts, type CommitCancelRequestedResult, type CredentialsSnapshot, type CredentialsSnapshotStep, type DeliverSignalOpts, type DeliverSourcesOpts, type DeriveMailAuditRef, type DeriveStepAddress, type DeriveStepRepoId, type DrainOpts, type DrainTimeoutAccumulator, type DrainTimeoutAccumulatorFactory, type DrainTimeoutOpts, type InboxPrimitives, type MailAuditRef, type MailBusBindings, type PrincipalSigner, type RecycleAttempt, type RecycleContext, type RecycleOpts, type RecycleOrigin, type RecyclePolicy, type RecyclePolicyBounds, type RecyclePolicyOpts, type SignedPayload, type SpawnOpts, type SpawnResult, type SubprocessHandle, type SubprocessSpawner, type TerminalEventSource, type TerminalRunEvent, type TriggerRecycleOpts, type DispatchTimingMark, type DispatchStructuralCounters, type DispatchSubstrateLeg, type WorkflowSupervisor, type WorkflowSupervisorBindings, type WorkflowSupervisorPrincipalKind, } from "./supervisor/index.js";
+export { createWorkflowHostDrainController, type WorkflowHostDrainController, type CreateWorkflowHostDrainControllerOpts, } from "./drain-controller.js";
+export { wrapHubTransportAsMailBus, type HubTransportMailBusAdapter, } from "./mail-bus/index.js";
+export { ControlPayload, DEFAULT_EVENT_BUFFER_LIMIT, EventPayload, FrameEnvelope, IPC_CRYPTO, SourcesUpdatedData, MacedEnvelope, OutboundAttachmentPayload, OutboundMessagePayload, SignedEnvelope, createControlChannelSender, createEventChannelSender, decodeEnvelope, encodeEnvelope, generateChannelId, generateHmacKey, receiveControlChannel, receiveEventChannel, signEd25519, signHmac, verifyEd25519, verifyHmac, type ControlChannelReceiverOpts, type ControlChannelSender, type ControlChannelSenderOpts, type EventChannelReceiverOpts, type EventChannelSender, type EventChannelSenderOpts, type FrameReader, type FrameWriter, type NdjsonReader, type NdjsonWriter, } from "./ipc/index.js";
+export { EVENT_CHANNEL_FD, createChildOutboundMailBridge, createChildSubstrateWriteBridge, createCredentialsBackedAuthorize, createProxyWorkflowRunRepoStore, createSupervisorBackedTransport, createWarmAgentCache, discoverInFlightRuns, parseSpawnTimeEnv, runWorkflowChild, runWorkflowChildFromProcessEnv, type ChildOutboundMailBridge, type ChildStepInvoker, type ChildSubstrateWriteBridge, type CreateChildOutboundMailBridgeOpts, type CreateChildSubstrateWriteBridgeOpts, type CreateProxyWorkflowRunRepoStoreOpts, type CredentialsSnapshotRef, type DiscoverRunsOpts, type DiscoveredRun, type DrainController, type GrantEvaluator, type RunWorkflowChildBindings, type RunWorkflowChildFromProcessEnvOpts, type RunWorkflowChildOpts, type RunWorkflowChildResult, type SourcesSnapshotRef, type SpawnTimeEnv, type SubstrateFactory, type SubstrateFactoryEnv, type SubstrateWriteRequest, type SubstrateWriteResponseSink, type WarmAgentCache, type WarmEventSinkRef, } from "./child/index.js";
+export { adaptHostScheduler, createWorkflowHostScheduler, createWorkflowHostSignalChannel, SignalReceivedEnvelope, type SchedulerHandle, type SchedulerOpts, type SignalChannelHandle, type SignalChannelOpts, } from "./seams/index.js";

package/dist/index.js

@@ -0,0 +1,10 @@
+export { createWorkflowRunRepoStore, } from "./adapters/repo-store.js";
+export { createWorkflowRunBlobSubstrate, } from "./adapters/blob-substrate.js";
+export { createWorkflowStepInvoker, } from "./adapters/step-invoker.js";
+export { createWorkflowSpawnChild, } from "./adapters/spawn-child.js";
+export { createWorkflowSupervisor, assembleCredentialsSnapshot, commitCancelRequested, createDrainTimeoutAccumulator, createRecyclePolicy, defaultStepRepoId, hashGrants, triggerRecycle, DEFAULT_DRAIN_TIMEOUT_MS, DEFAULT_KILL_TIMEOUT_MS, DEFAULT_POLICY_INTERVAL_MS, DEFAULT_TERMINAL_WRITE_WATCHDOG_MS, MAX_BUFFERED_MAIL, STEP_GRANTS_PATH, STEP_GRANTS_REF, SUPERVISOR_PRINCIPAL_KIND, } from "./supervisor/index.js";
+export { createWorkflowHostDrainController, } from "./drain-controller.js";
+export { wrapHubTransportAsMailBus, } from "./mail-bus/index.js";
+export { ControlPayload, DEFAULT_EVENT_BUFFER_LIMIT, EventPayload, FrameEnvelope, IPC_CRYPTO, SourcesUpdatedData, MacedEnvelope, OutboundAttachmentPayload, OutboundMessagePayload, SignedEnvelope, createControlChannelSender, createEventChannelSender, decodeEnvelope, encodeEnvelope, generateChannelId, generateHmacKey, receiveControlChannel, receiveEventChannel, signEd25519, signHmac, verifyEd25519, verifyHmac, } from "./ipc/index.js";
+export { EVENT_CHANNEL_FD, createChildOutboundMailBridge, createChildSubstrateWriteBridge, createCredentialsBackedAuthorize, createProxyWorkflowRunRepoStore, createSupervisorBackedTransport, createWarmAgentCache, discoverInFlightRuns, parseSpawnTimeEnv, runWorkflowChild, runWorkflowChildFromProcessEnv, } from "./child/index.js";
+export { adaptHostScheduler, createWorkflowHostScheduler, createWorkflowHostSignalChannel, SignalReceivedEnvelope, } from "./seams/index.js";

package/dist/ipc/control-channel.d.ts

@@ -0,0 +1,336 @@
+import { decodeEnvelope } from "./envelope.js";
+/**
+ * Wire-shape of one per-step credentials entry the supervisor pushes
+ * inside a `grants-updated` frame. Mirrors `CredentialsSnapshotStep`
+ * in `supervisor/credentials.ts` -- duplicated here as an arktype
+ * validator so the control-channel module stays free of a
+ * compile-time import on the supervisor module (the IPC module sits
+ * underneath the supervisor and child modules in the dependency
+ * graph). The contentHash pins the per-step grants so the child can
+ * detect a stale push and ignore an out-of-order one.
+ */
+export declare const CredentialsSnapshotStepPayload: import("arktype/internal/variants/object.ts").ObjectType<{
+    stepId: string;
+    address: string;
+    grants: unknown[];
+    contentHash: string;
+}, {}>;
+export declare const CredentialsSnapshotPayload: import("arktype/internal/variants/object.ts").ObjectType<{
+    steps: {
+        stepId: string;
+        address: string;
+        grants: unknown[];
+        contentHash: string;
+    }[];
+}, {}>;
+/**
+ * Wire shape of a `sources-updated` frame's `data`: the full ordered
+ * inference-source failover chain plus the default source id. Carried
+ * inline like the grants snapshot -- a single-producer, single-consumer
+ * supervisor->child push, so a substrate round-trip would only add
+ * latency. No per-source hash rides along; a source list is flat, with no
+ * per-item pin for a receiver to cross-check.
+ *
+ * The `narrow` pins two frame-structural invariants at this boundary so
+ * every consumer can trust them without re-checking: source ids are
+ * unique, and the first element is the default source. The head-is-default
+ * rule is what keeps the two rotation paths in agreement -- a warm agent's
+ * `setSources` activates the matched default index, while a cold rebuild
+ * pins element 0 -- so they pick the same active source only when the
+ * default is the head.
+ */
+export declare const SourcesUpdatedData: import("arktype/internal/variants/object.ts").ObjectType<{
+    sources: {
+        id: string;
+        provider: string;
+        baseURL: string;
+        apiKey: string;
+        model: string;
+        defaults?: {
+            maxTokens?: number;
+            providerOptions?: Record<string, unknown>;
+        };
+        capabilities?: string[];
+    }[];
+    defaultSource: string;
+}, {}>;
+/**
+ * Wire projection of an attachment on an outbound mail message. The
+ * runtime `MessageAttachment.data` is raw bytes; the NDJSON control
+ * channel is text, so the bytes ride base64-encoded under `dataBase64`.
+ * The child encodes on send; the supervisor decodes before handing the
+ * `OutboundMessage` to the host transport.
+ */
+export declare const OutboundAttachmentPayload: import("arktype/internal/variants/object.ts").ObjectType<{
+    name: string;
+    contentType: string;
+    dataBase64: string;
+}, {}>;
+/**
+ * Wire projection of `@intx/types/runtime`'s `OutboundMessage`. Mirrors
+ * that type field-for-field with two adjustments for the NDJSON wire:
+ * attachment bytes are base64 strings (see `OutboundAttachmentPayload`),
+ * and every optional field is spelled with the `"?"` suffix so an
+ * absent field round-trips as absent rather than `null`. The supervisor
+ * reconstructs the runtime `OutboundMessage` from this shape before
+ * invoking `MailBusBindings.sendOutbound`.
+ *
+ * Duplicated here as an arktype validator (rather than importing the
+ * TypeScript `OutboundMessage` type) so the IPC module validates the
+ * child-supplied payload at the wire boundary -- the child is a separate
+ * process and its frames are untrusted input the receiver must parse.
+ */
+export declare const OutboundMessagePayload: import("arktype/internal/variants/object.ts").ObjectType<{
+    to: string | string[];
+    type: "conversation.message" | "conversation.join" | "conversation.leave" | "offering.request" | "offering.response" | "offering.error" | "offering.discover" | "offering.catalog" | "payment.required" | "payment.receipt" | "payment.verified" | "approval.request" | "approval.granted" | "approval.denied" | "system.health" | "system.register" | "system.deregister" | "system.credential.refresh";
+    cc?: string | string[];
+    subject?: string;
+    content?: string;
+    payload?: Record<string, unknown>;
+    summary?: string;
+    attachments?: {
+        name: string;
+        contentType: string;
+        dataBase64: string;
+    }[];
+    inReplyTo?: string;
+    correlationId?: string;
+    sessionId?: string;
+    tenantId?: string;
+}, {}>;
+export type OutboundMessagePayload = typeof OutboundMessagePayload.infer;
+/**
+ * Discriminated union of every control-channel payload kind. The
+ * `type` discriminator namespaces the control-plane vocabulary so a
+ * future addition (e.g. `connector-bind`) lands by extending this
+ * union and not by widening the envelope shape. Inference events
+ * NEVER appear here; they ride the event channel.
+ */
+export declare const ControlPayload: import("arktype/internal/variants/object.ts").ObjectType<{
+    type: "trigger.fire";
+    data: {
+        runId: string;
+        messageId: string;
+        receivedAt: number;
+    };
+} | {
+    type: "signal.deliver";
+    data: {
+        runId: string;
+        signalName: string;
+        signalId: string;
+        payload: unknown;
+    };
+} | {
+    type: "drain";
+    data: {
+        deadlineMs: number;
+    };
+} | {
+    type: "shutdown";
+    data: {
+        reason: string;
+    };
+} | {
+    type: "grants-updated";
+    data: {
+        snapshot: {
+            steps: {
+                stepId: string;
+                address: string;
+                grants: unknown[];
+                contentHash: string;
+            }[];
+        };
+        stepHashes?: Record<string, string>;
+    };
+} | {
+    type: "sources-updated";
+    data: {
+        sources: {
+            id: string;
+            provider: string;
+            baseURL: string;
+            apiKey: string;
+            model: string;
+            defaults?: {
+                maxTokens?: number;
+                providerOptions?: Record<string, unknown>;
+            };
+            capabilities?: string[];
+        }[];
+        defaultSource: string;
+    };
+} | {
+    type: "ready";
+    data: {
+        childPid: number;
+        childPublicKey: string;
+    };
+} | {
+    type: "recycle.request";
+    data: {
+        reason: string;
+    };
+} | {
+    type: "substrate.write.request";
+    data: {
+        requestId: string;
+        repoId: {
+            kind: string;
+            id: string;
+        };
+        ref: string;
+        preservePrefix: string;
+        message: string;
+    };
+} | {
+    type: "substrate.merge.request";
+    data: {
+        requestId: string;
+        existing: {
+            path: string;
+            contentBase64: string;
+        }[];
+    };
+} | {
+    type: "substrate.merge.response";
+    data: {
+        requestId: string;
+        result: {
+            ok: true;
+            files: {
+                path: string;
+                contentBase64: string;
+            }[];
+        } | {
+            ok: false;
+            reason: string;
+        };
+    };
+} | {
+    type: "substrate.write.response";
+    data: {
+        requestId: string;
+        result: {
+            ok: true;
+            commitSha: string;
+        } | {
+            ok: false;
+            reason: string;
+        };
+    };
+} | {
+    type: "outbound.message";
+    data: {
+        requestId: string;
+        senderAddress: string;
+        message: {
+            to: string | string[];
+            type: "conversation.message" | "conversation.join" | "conversation.leave" | "offering.request" | "offering.response" | "offering.error" | "offering.discover" | "offering.catalog" | "payment.required" | "payment.receipt" | "payment.verified" | "approval.request" | "approval.granted" | "approval.denied" | "system.health" | "system.register" | "system.deregister" | "system.credential.refresh";
+            cc?: string | string[];
+            subject?: string;
+            content?: string;
+            payload?: Record<string, unknown>;
+            summary?: string;
+            attachments?: {
+                name: string;
+                contentType: string;
+                dataBase64: string;
+            }[];
+            inReplyTo?: string;
+            correlationId?: string;
+            sessionId?: string;
+            tenantId?: string;
+        };
+        mailbox?: string;
+    };
+} | {
+    type: "outbound.result";
+    data: {
+        requestId: string;
+        result: {
+            ok: true;
+            messageId: string;
+            status: "delivered" | "queued";
+        } | {
+            ok: false;
+            reason: string;
+        };
+    };
+} | {
+    type: "terminal.event";
+    data: {
+        runId: string;
+        seq: number;
+        kind: "RunCompleted" | "RunFailed" | "RunCancelled";
+        at: string;
+        error?: {
+            message: string;
+        };
+    };
+}, {}>;
+export type ControlPayload = typeof ControlPayload.infer;
+export interface NdjsonWriter {
+    write(line: string): Promise<void> | void;
+}
+export interface NdjsonReader {
+    read(): AsyncIterableIterator<string>;
+}
+export interface ControlChannelSenderOpts {
+    privateKeySeed: Uint8Array;
+    channelId: string;
+    writer: NdjsonWriter;
+}
+export interface ControlChannelSender {
+    send(payload: ControlPayload): Promise<void>;
+    readonly seq: number;
+}
+/**
+ * Construct the supervisor-side control-channel sender. The
+ * supervisor's Ed25519 seed lives in closure. The matching public
+ * key flows to the child through spawn-time env -- never the seed.
+ */
+export declare function createControlChannelSender(opts: ControlChannelSenderOpts): ControlChannelSender;
+export interface ControlChannelReceiverOpts {
+    /**
+     * Public key used to verify every inbound frame. When `Uint8Array`
+     * the value is fixed at construction time (the child's downstream
+     * receiver uses the supervisor's pubkey from `HOST_PUBKEY`). When
+     * `{ bootstrapFromReady: true }` the receiver opens in
+     * bootstrap mode: the first frame must be `ready` and must carry
+     * a `childPublicKey` hex-encoded Ed25519 public key in its payload.
+     * The receiver extracts the key, verifies the first frame's
+     * signature against it, then continues verifying subsequent frames
+     * against the same key. The supervisor's upstream receiver opens
+     * in bootstrap mode so the child can publish its own public key
+     * over the wire without the supervisor ever holding the matching
+     * private half.
+     */
+    publicKey: Uint8Array | {
+        bootstrapFromReady: true;
+    };
+    channelId: string;
+    reader: NdjsonReader;
+    /**
+     * Invoked when any invariant is violated: signature failure,
+     * channelId mismatch, non-monotonic seq, malformed payload. The
+     * receiver's contract is to crash on any such violation. The
+     * caller wires this to a process-exit path; tests inject a
+     * recorder to assert on the failure mode.
+     */
+    onCrash: (reason: string) => void;
+}
+/**
+ * Construct the child-side control-channel receiver. Yields one
+ * verified, in-order `ControlPayload` per call. Any frame that
+ * fails verification, carries a non-current channelId, or arrives
+ * out of order calls `onCrash` and ends the iterator.
+ */
+export declare function receiveControlChannel(opts: ControlChannelReceiverOpts): AsyncGenerator<ControlPayload, void, void>;
+/**
+ * Re-export the envelope decoder for callers that need to inspect
+ * a control frame's envelope without going through the receiver
+ * iterator (testing harnesses that fuzz the wire format).
+ */
+export { decodeEnvelope };