@intx/workflow-host 0.2.2

package/dist/child/run-child.d.ts

@@ -0,0 +1,320 @@
+import type { Principal, RepoId, RepoStore as SubstrateRepoStore } from "@intx/hub-sessions/substrate";
+import type { DirectorRegistry } from "@intx/agent";
+import type { AuthzCallResult } from "@intx/inference";
+import type { RunResult, Scheduler, StepInvokeRequest, StepInvokeResult, SpawnChildWorkflow, WorkflowAuthorizeFn } from "@intx/workflow";
+import { type WorkflowHostDrainController } from "../drain-controller.js";
+import type { InferenceSource } from "@intx/types/runtime";
+import { type ControlChannelSender, type ControlPayload, type EventPayload, type FrameWriter, type NdjsonReader, type NdjsonWriter } from "../ipc/index.js";
+import type { CredentialsSnapshot } from "../supervisor/credentials.js";
+import { hashGrants } from "../supervisor/credentials.js";
+import type { SpawnTimeEnv } from "./env-bootstrap.js";
+import type { ChildOutboundMailBridge } from "./outbound-mail-bridge.js";
+import { type WarmAgentCache } from "./warm-agent-cache.js";
+/**
+ * `WorkflowAuthorize` closure factory shape. The child's authorize
+ * evaluates a `(resource, action)` request against the active
+ * credentialsSnapshot for the originating step. The closure used here
+ * is intentionally permissive on missing context: the workflow runtime
+ * supplies `stepId` from the `AuthorizeContext` it threads through
+ * every step's invoker, so a bare-call without a step id is a
+ * programming error rather than a security-sensitive path. The closure
+ * surfaces it loudly.
+ *
+ * Read-site: the closure consults a mutable reference so a
+ * `grants-updated` control frame swaps the snapshot in place without
+ * the caller having to reconstruct the closure.
+ */
+export type CredentialsSnapshotRef = {
+    current: CredentialsSnapshot | null;
+};
+/**
+ * Per-step inference-source table the build path reads through a mutable
+ * reference, keyed by stepId. Each value is the step's ordered failover
+ * chain (element 0 is the active source). The single-step build resolves
+ * its sources from `current` at build time, so a rotation that writes
+ * `current` before the first build is reflected in the built agent. A
+ * warm agent that is already built does not re-read this ref, so rotating
+ * its live sources is out of this ref's scope.
+ */
+export type SourcesSnapshotRef = {
+    current: Record<string, InferenceSource[]>;
+};
+/**
+ * Construct the workflow-level authorize closure backed by a
+ * mutable credentialsSnapshot reference.
+ *
+ * The closure looks up the step's grants by `stepId`, then delegates
+ * to the caller-supplied grant evaluator. The evaluator slot exists so
+ * the host wires its own grant-rule semantics without leaking the
+ * grant-rule grammar into the workflow-host package; tests inject a
+ * spy that records inputs.
+ */
+export type GrantEvaluator = (input: {
+    resource: string;
+    action: string;
+    stepId: string;
+    attempt: number | undefined;
+    runId: string | undefined;
+    grants: readonly unknown[];
+}) => Promise<AuthzCallResult>;
+export declare function createCredentialsBackedAuthorize(ref: CredentialsSnapshotRef, evaluate: GrantEvaluator): WorkflowAuthorizeFn;
+/**
+ * The workflow-host child's drain controller is the production
+ * implementation defined in `../drain-controller.ts`. The control-loop
+ * calls `requestDrain()` on receipt of the supervisor's `drain`
+ * control mail; the controller flips its signal and the runtime body
+ * observes the change at its four observation points. The `behaviorFor`
+ * resolver consults the loaded `WorkflowDefinition`.
+ */
+export type DrainController = WorkflowHostDrainController;
+/**
+ * Step-invoker shape the child binds. Widens the workflow-runtime
+ * `StepInvoker` with an `onEvent` callback the harness fires for
+ * every `InferenceEvent` it emits during the step's run, plus the
+ * child's credentials-backed `authorize` closure so the step agent's
+ * tool-invocation gate evaluates the per-step grants the supervisor
+ * pushed (rather than the host minting its own authorize that cannot
+ * see the live credentials snapshot). The child's `buildRuntimeEnv`
+ * constructs the per-step `onEvent` closure (wrapping the
+ * HMAC-authenticated event-channel sender) and threads both here so
+ * every event reaches the supervisor over the wire and every tool
+ * call resolves against the agent's grants. The runtime-runtime
+ * `StepInvoker` exposed via `WorkflowRuntimeEnv` remains the narrower
+ * shape -- the child wraps this binding into a `StepInvoker` inside
+ * `buildRuntimeEnv` so the workflow-runtime never sees the
+ * host-specific surface.
+ *
+ * The `warmCache` argument carries the run-loop's per-deployment
+ * warm-agent cache (design §3b) when the deployment is a warm candidate,
+ * and `undefined` otherwise. The binding forwards it to the step-invoker
+ * adapter, which builds-or-reuses the cached agent on a warm cache and
+ * keeps instantiate-send-teardown when it is absent. The cache is owned
+ * by the run-loop (`runWorkflowChild`), not the binding: the binding
+ * only reads it through to the adapter.
+ */
+export type ChildStepInvoker = (req: StepInvokeRequest, onEvent: (event: EventPayload) => void, authorize: WorkflowAuthorizeFn, warmCache: WarmAgentCache | undefined, sourcesRef: SourcesSnapshotRef) => Promise<StepInvokeResult>;
+/**
+ * Bindings the binary owns: per-deployment substrate identity,
+ * principal credentials, the runtime-supplied callbacks the
+ * adapter-layer cannot construct from `process.env` alone. Tests
+ * supply a fully in-memory bindings object so `runWorkflowChild` runs
+ * without touching disk.
+ */
+export interface RunWorkflowChildBindings {
+    /** Workflow-run substrate (per-deployment workflow-run repo). */
+    substrate: SubstrateRepoStore;
+    /** Per-deployment workflow-run repo identity. */
+    workflowRunRepoId: RepoId;
+    /** Workflow-run repo ref the child reads/writes. */
+    workflowRunRef: string;
+    /**
+     * Substrate-shaped principal the child presents on every workflow-run
+     * read/write. Per the IPC threat model the child holds no private
+     * key of its own; the principal here is a substrate-level identity
+     * the host's substrate accepts for `runs/<runId>/` writes.
+     */
+    principal: Principal;
+    /** Workflow-asset repo identity (used to load `workflow.json`). */
+    workflowDefinitionRepoId: RepoId;
+    /** Workflow-asset ref the deploy orchestrator wrote to. */
+    workflowDefinitionRef: string;
+    /**
+     * Step-invoker callback the runtime body invokes per step. The
+     * shape is the workflow-runtime `StepInvoker` widened with an
+     * `onEvent` slot so the harness can emit `InferenceEvent` frames
+     * up through the event channel for every step invocation. The
+     * production binary wires this against `createWorkflowStepInvoker`
+     * with the host's per-step env builder; tests inject a stub.
+     */
+    invokeStep: ChildStepInvoker;
+    /**
+     * Child-spawn callback the runtime body invokes for `childWorkflow`
+     * primitives. The production binary wires this against
+     * `createWorkflowSpawnChild`; tests inject a stub.
+     */
+    spawnChild: SpawnChildWorkflow;
+    /** Host-process scheduler singleton. The child consumes the same instance. */
+    scheduler: Scheduler;
+    /** Grant evaluator wired against the host's grant-rule grammar. */
+    evaluateGrants: GrantEvaluator;
+    /**
+     * Reclaim the local-disk scratch a run produced once the run has
+     * reached its terminal status. The host owns the on-disk layout
+     * (`<dataDir>/workflow-step-state/<repoId>/runs/<runId>/`), so the
+     * teardown lives next to the path construction in the substrate
+     * factory and the run-loop merely fires it at the run-completion
+     * moment it observes. Invoked ONLY on the cold (non-warm) path -- a
+     * warm deployment's single agent reuses one stable workspace across
+     * runs, so deleting per run would wipe a live conversation's files
+     * mid-stream. A cleanup failure is logged and swallowed: it is a
+     * disk-reclamation best-effort, never a correctness gate on the run's
+     * terminal status. Optional so tests and the recursive child-workflow
+     * adapter (which roots no per-run scratch of its own) can omit it.
+     */
+    cleanupRunStorage?: (runId: string) => Promise<void>;
+    /** Optional director registry; defaults to the canonical built-ins. */
+    directors?: DirectorRegistry;
+    /** Optional clock override; production wires `() => new Date()`. */
+    clock?: () => Date;
+    /** Optional id generator override; production wires a monotonic one. */
+    newId?: (prefix: string) => string;
+    /**
+     * Optional bootstrap credentialsSnapshot. The host's production
+     * wiring supplies this for multi-step deploys whose snapshot is
+     * baked at spawn time; tests can pre-seed it directly. Absent
+     * value defers to the first `grants-updated` control frame.
+     */
+    initialCredentialsSnapshot?: CredentialsSnapshot;
+    /**
+     * Bootstrap per-step inference-source table (keyed by stepId), parsed
+     * from the spawn env by the host's substrate factory. Seeds the
+     * mutable `sourcesRef` the build path reads. Absent value defers to an
+     * empty table, so a step with no pinned source fails loudly at build
+     * rather than resolving a default.
+     */
+    initialSources?: Record<string, InferenceSource[]>;
+    /**
+     * Optional override for the child's Ed25519 keypair factory. The
+     * child mints a fresh keypair at startup, holds the private half
+     * in its own address space, signs every upstream control frame
+     * with it, and publishes the public half in the `ready` frame so
+     * the supervisor can verify subsequent upstream frames. Production
+     * wires this against `@intx/crypto`'s `generateKeyPair`;
+     * tests inject a deterministic factory so they can assert on the
+     * published key. The supervisor's private key is NEVER threaded
+     * into the child -- the child holds only its own private half.
+     */
+    ipcChildKeyPairFactory?: () => Promise<{
+        privateKey: Uint8Array;
+        publicKey: Uint8Array;
+    }>;
+}
+export interface RunWorkflowChildOpts {
+    /** Parsed spawn-time env. */
+    env: SpawnTimeEnv;
+    /** Control-channel reader (supervisor -> child). */
+    controlReader: NdjsonReader;
+    /**
+     * Control-channel writer back to the supervisor. The child does not
+     * sign frames here today (the only upstream control frame, the
+     * `ready` signal, rides as an unsigned wire shape because the
+     * supervisor receives it on its trusted side). Future upstream
+     * frames will adopt the same envelope-and-signature contract the
+     * downstream side enforces; the writer slot exists today so the
+     * control-channel boundary is symmetric in shape.
+     */
+    controlWriter: NdjsonWriter;
+    /**
+     * Event-channel writer (child -> supervisor). The child publishes
+     * verified `InferenceEvent` frames the harness emits up through
+     * here. Tests inject an in-memory writer; production wires the
+     * inherited socketpair fd into a FrameWriter.
+     */
+    eventWriter: FrameWriter;
+    /** Bindings the binary or test harness owns. */
+    bindings: RunWorkflowChildBindings;
+    /**
+     * Optional pre-built upstream control sender the child uses to emit
+     * `ready` and (today) `pack.push.request` frames. Defaults to a
+     * sender minted internally against the child's own Ed25519 keypair.
+     * The process-shaped wrapper `runWorkflowChildFromProcessEnv`
+     * supplies a pre-built sender so the same Ed25519-signed surface is
+     * shared with the pack-push bridge it constructs against the
+     * substrate factory.
+     */
+    upstreamSender?: ControlChannelSender;
+    /**
+     * Optional substrate-write bridge whose `handleMergeRequest` and
+     * `handleWriteResponse` the child's control loop invokes when the
+     * matching downstream frames land. When omitted, inbound
+     * `substrate.merge.request` / `substrate.write.response` frames are
+     * logged at warn-level and dropped -- the wire shapes are
+     * well-formed but nobody on the child side asked for them. The
+     * pre-built bridge is the path the process-shaped wrapper takes so
+     * the substrate factory's proxy `RepoStore` can resolve writes
+     * against it.
+     */
+    substrateWriteBridge?: SubstrateWriteResponseSink;
+    /**
+     * Optional outbound-mail bridge (OUTBOUND half of mailbox ownership,
+     * §3a). The step agent's mail tools are backed by a transport whose
+     * `send` routes through this bridge: it emits an `outbound.message`
+     * upstream control frame and resolves the agent's mail-tool `send`
+     * once the supervisor's matching `outbound.result` lands. The
+     * control loop routes the downstream `outbound.result` frame to the
+     * bridge's `handleResult` and invokes `cancelAll` on any exit path so
+     * a pending send does not leak an awaiter after the supervisor tears
+     * the IPC down. When omitted, inbound `outbound.result` frames are
+     * logged at warn-level and dropped -- the wire shape is well-formed
+     * but no agent on the child side asked for an outbound send.
+     */
+    outboundMailBridge?: ChildOutboundMailBridge;
+}
+/**
+ * Narrow interface the child's control loop calls when downstream
+ * substrate-write frames arrive, plus the `cancelAll` shutdown
+ * surface the loop invokes on any exit path. Decouples the loop from
+ * the bridge's `submit` side so a test can drop in a recording sink
+ * without standing up the full bridge.
+ */
+export interface SubstrateWriteResponseSink {
+    handleMergeRequest(data: Extract<ControlPayload, {
+        type: "substrate.merge.request";
+    }>["data"]): void;
+    handleWriteResponse(data: Extract<ControlPayload, {
+        type: "substrate.write.response";
+    }>["data"]): void;
+    cancelAll(reason: string): void;
+}
+/**
+ * Public result the test harness inspects. Production binaries discard
+ * the return value (the process exits when this function resolves);
+ * tests assert on the discovered-run ids and the active credentials
+ * snapshot to verify the loop's behaviour without scraping logs.
+ */
+export interface RunWorkflowChildResult {
+    /** RunIds the child resumed at startup. */
+    resumedRunIds: readonly string[];
+    /** RunIds the child started from `trigger.fired` after `ready`. */
+    triggeredRunIds: readonly string[];
+    /** Snapshot active at function return. */
+    finalCredentialsSnapshot: CredentialsSnapshot | null;
+}
+/**
+ * Run the workflow-process child. Resolves once the control channel
+ * emits `shutdown` (or ends without a frame, in which case the loop
+ * exits cleanly).
+ */
+export declare function runWorkflowChild(opts: RunWorkflowChildOpts): Promise<RunWorkflowChildResult>;
+/**
+ * Mirror a run's terminal status back to the supervisor over the
+ * upstream control channel. Fired once per run from the resume and
+ * trigger.fire paths' `complete` continuation. The supervisor's
+ * per-cohort terminal broadcaster fans the event out to the dispatch
+ * loop and any armed drainTimeout accumulator subscribed for the
+ * runId.
+ *
+ * The frame mirrors the run's committed terminal event: every field --
+ * `kind`, `seq`, `at`, and (for `RunFailed`) `error.message` -- is
+ * sourced from that event, which is why the frame's `seq` matches the
+ * on-disk audit-log entry. `terminalStatus` is only the cross-check: the
+ * found event's `kind` must agree with it. A missing terminal event, or
+ * one whose kind disagrees, is a runtime producer bug (the runtime
+ * commits the terminal event last), and emitting a frame anyway would
+ * desync the supervisor from the durable log that `discoverInFlightRuns`
+ * reads on resume -- the supervisor would settle a run the on-disk log
+ * still shows in-flight. So this throws instead: no frame keeps the
+ * supervisor and the durable log agreeing that the run is unsettled, and
+ * the next recycle/restart resumes it. The throw propagates to the
+ * caller's `complete` continuation, which logs it.
+ *
+ * Errors flowing out of `upstreamSender.send` are a different case --
+ * a transport send failure, logged but not rethrown. The supervisor's
+ * dispatch loop is the authoritative settler through its cohort abort
+ * signal, so a lost frame surfaces structurally as a wedged dispatch
+ * rather than a silent lifecycle failure. The invariant throws above run
+ * before the send so that catch never swallows them.
+ */
+export declare function emitTerminalEvent(upstreamSender: ControlChannelSender, result: RunResult): Promise<void>;
+/** Re-export the hash helper so callers can verify the snapshot's pin. */
+export { hashGrants };