@intx/workflow-host 0.2.2 → 0.4.0

package/dist/adapters/spawn-child.d.ts

@@ -1,5 +1,6 @@
-import type { Principal, RepoStore } from "@intx/hub-sessions/substrate";
-import type { SpawnChildWorkflow, WorkflowDefinition } from "@intx/workflow";
+import type { InferenceEvent } from "@intx/types/runtime";
+import type { SpawnChildWorkflow, SpawnSuspendableChild, SuspendableChildHandle, WorkflowDefinition, WorkflowEvent } from "@intx/workflow";
+import type { CredentialMaterialRef } from "../child/run-child.js";
 /**
  * The terminal-status shape the runtime body expects back from a
  * spawn. Mirrored from `SpawnChildWorkflow`'s return type so the
@@ -16,7 +17,18 @@ export type ChildTerminalStatus = "completed" | "failed" | "cancelled";
  *
  * The callback receives the same `AbortSignal` the parent runtime
  * passed into the adapter so a parent-initiated cancellation
- * propagates to the child without an intermediate wrapper.
+ * propagates to the child without an intermediate wrapper. It also
+ * receives the parent run's live `onEvent` sink so the child's agent
+ * steps emit inference events up the same channel (mirroring
+ * {@link RunSuspendableChild}), and the spawn `depth` / ceiling so the
+ * child run's own spawns keep counting against the tree-wide bound.
+ *
+ * The callback also receives the parent run's live credential-material cell
+ * (the same reference the top-level step invoker reads live), so the child's
+ * inference resolves its source secret by `credentialId` against the run's
+ * current delivery -- a rotation the parent applies reaches the child through
+ * the shared reference. A non-sidecar executor that carries no credential
+ * material omits it.
  */
 export type RunChildWorkflow = (input: {
     definition: WorkflowDefinition;
@@ -26,49 +38,102 @@ export type RunChildWorkflow = (input: {
     parentRunId: string;
     parentStepId: string;
     signal: AbortSignal;
-}) => Promise<{
+    depth: number;
+    maxChildSpawnDepth: number;
+}, onEvent: (event: InferenceEvent) => void, credentialMaterial?: CredentialMaterialRef) => Promise<{
     terminalStatus: ChildTerminalStatus;
 }>;
-export interface WorkflowSpawnChildOpts {
-    /**
-     * Substrate the deploy orchestrator wrote the workflow asset into.
-     * The adapter reads the workflow envelope through
-     * `substrate.getRepoDir` -- the deploy-time `writeTree` already
-     * materialized the file under the returned directory and a flat
-     * `fs.readFile` does not need to walk the git object database.
-     */
-    substrate: RepoStore;
-    /**
-     * Principal the adapter presents to the substrate for any future
-     * authorize-gated read path. The current implementation does not
-     * gate `getRepoDir` (the substrate documents it as a pure path
-     * computation), but holding the principal in closure keeps the
-     * adapter symmetric with the sibling production adapters and ready
-     * for a future API that surfaces an authorize gate on the same
-     * read path.
-     */
-    principal: Principal;
-    /**
-     * Ref under the workflow asset's repo whose tree holds the
-     * deployed `workflow.json`. Callers typically supply
-     * `"refs/heads/main"` -- the workflow-kind handler enforces the
-     * envelope's structural shape at push time so a deploy ref read
-     * here either yields a valid envelope or surfaces a targeted
-     * parse/validation error.
-     */
-    deployRef: string;
-    /**
-     * Runtime-supplied child execution callback. The adapter delegates
-     * here once the `WorkflowDefinition` is resolved; the supervisor
-     * owns the child `WorkflowRuntimeEnv` and the `runtimeRun`
-     * invocation.
-     */
+/**
+ * Construct the terminal `WorkflowRuntimeEnv.SpawnChildWorkflow` adapter for an
+ * owned childWorkflow import. The child re-evaluated the whole pinned closure
+ * and lifted every inline child to an internal `{ ref }`, so the child
+ * definitions are in hand and already covered by the parent's re-verify.
+ * Resolve each `definitionRef`
+ * from the in-memory `bodies` map and delegate to the runtime-supplied
+ * `runChild`, with NO on-disk round-trip and NO separate per-child re-verify:
+ * materializing the child back out and re-fingerprinting it would round-trip
+ * trusted-in-hand data for no gain, and the closure re-eval on restart
+ * re-derives the same bodies durably. Mirrors
+ * {@link createInMemorySpawnSuspendableChild} but drives the child terminal-only
+ * (await its terminal status) rather than across approval parks.
+ */
+/**
+ * Host-side widening of the runtime {@link SpawnChildWorkflow} contract: the
+ * same input plus the per-run `onEvent` sink the host injects. The runtime env
+ * carries the narrow `SpawnChildWorkflow` (no event slot); the caller wraps this
+ * with its run's `onEvent`, mirroring {@link HostSpawnSuspendableChild}. The
+ * sink is a call argument (not closed over at construction) because the resolver
+ * is selected once per deployment while `onEvent` is built per run. The run's
+ * live credential-material cell rides the same seam, so the child's inference
+ * reads the parent's current credential delivery.
+ */
+export type HostSpawnChild = (input: Parameters<SpawnChildWorkflow>[0], onEvent: (event: InferenceEvent) => void, credentialMaterial?: CredentialMaterialRef) => ReturnType<SpawnChildWorkflow>;
+export declare function createInMemorySpawnChild(opts: {
+    bodies: ReadonlyMap<string, WorkflowDefinition>;
     runChild: RunChildWorkflow;
-}
+}): HostSpawnChild;
+/**
+ * Runtime-supplied suspendable child execution callback. The park-aware
+ * analog of {@link RunChildWorkflow}: the supervisor owns the child
+ * `WorkflowRuntimeEnv` construction and the `runtimeRun` invocation and
+ * returns a live `SuspendableChildHandle` the caller drives across the
+ * body's approval parks, rather than awaiting a terminal. The adapter is
+ * the single resolution point that hands the supervisor a concrete
+ * `WorkflowDefinition` alongside the parent attribution the runtime body
+ * produced.
+ */
+export type RunSuspendableChild = (input: {
+    definition: WorkflowDefinition;
+    definitionRef: string;
+    childRunId: string;
+    input: unknown;
+    parentRunId: string;
+    parentStepId: string;
+    signal: AbortSignal;
+    depth: number;
+    maxChildSpawnDepth: number;
+    resumeFromEvents?: readonly WorkflowEvent[];
+}, 
+/**
+ * Live inference-event sink for the child's agent steps. Threaded from the
+ * host's per-run funnel (the parent run's event-channel closure) so the
+ * body's inference events reach the hub's live stream instead of being
+ * silently dropped. Per-run durable attribution is unaffected -- the child
+ * runtime commits its events under `runs/<childRunId>/events/` regardless.
+ */
+onEvent: (event: InferenceEvent) => void, 
+/**
+ * The parent run's live credential-material cell. Threaded so the body's
+ * inference resolves its source secret by `credentialId` against the run's
+ * current delivery, reached live through the shared reference on a rotation.
+ * A non-sidecar executor that carries no credential material omits it.
+ */
+credentialMaterial?: CredentialMaterialRef) => Promise<SuspendableChildHandle>;
+/**
+ * Host-side widening of the runtime {@link SpawnSuspendableChild} contract: the
+ * same input plus the per-run `onEvent` sink the host injects. The runtime
+ * calls the narrow `SpawnSuspendableChild` (no event slot); the host binding
+ * wired into the runtime env closes over the run's funnel and forwards it here,
+ * mirroring how `ChildStepInvoker` widens the runtime `StepInvoker` with
+ * `onEvent`. The runtime contract in `@intx/workflow` stays untouched. The
+ * run's live credential-material cell rides the same seam, so the body's
+ * inference reads the parent's current credential delivery.
+ */
+export type HostSpawnSuspendableChild = (input: Parameters<SpawnSuspendableChild>[0], onEvent: (event: InferenceEvent) => void, credentialMaterial?: CredentialMaterialRef) => ReturnType<SpawnSuspendableChild>;
 /**
- * Construct the production `WorkflowRuntimeEnv.SpawnChildWorkflow`
- * adapter. The substrate handle, the principal, the deploy ref, and
- * the runtime-supplied child callback live in closure; the returned
- * callable satisfies the runtime-env interface.
+ * Construct the `WorkflowRuntimeEnv.SpawnSuspendableChild` adapter for the
+ * source-ref (code-sourced) path -- the only deploy lineage. The parent child
+ * re-evaluated the whole pinned closure in one sandbox and re-verified it
+ * against the approved hash -- which already covers every inline onTrigger body
+ * -- so the body definitions are in hand and already proven. Resolve each
+ * `definitionRef` from that in-memory `bodies` map and run it in-process, with
+ * NO disk round-trip and NO separate per-body re-verify: materializing the body
+ * back out and re-fingerprinting it would round-trip trusted-in-hand data for no
+ * gain, and the closure re-eval on restart re-derives the same bodies durably.
+ * The body still runs in the parent's sandbox (in-process today; a stricter
+ * per-body boundary is the deferred, opt-in SandboxBoundary case).
  */
-export declare function createWorkflowSpawnChild(opts: WorkflowSpawnChildOpts): SpawnChildWorkflow;
+export declare function createInMemorySpawnSuspendableChild(opts: {
+    bodies: ReadonlyMap<string, WorkflowDefinition>;
+    runSuspendableChild: RunSuspendableChild;
+}): HostSpawnSuspendableChild;

package/dist/adapters/spawn-child.js

@@ -1,34 +1,34 @@
 // Production `WorkflowRuntimeEnv.SpawnChildWorkflow` adapter.
 //
-// The runtime body sees the spawn callback shape: given a
-// `definitionRef` (a workflow asset's repo id), a parent-allocated
-// `childRunId`, the materialized child input, and parent attribution,
-// settle once the child run reaches a terminal phase. The adapter
-// itself does not execute the child workflow -- it resolves the
-// `definitionRef` into a concrete `WorkflowDefinition` from the
-// workflow repo's deploy ref, then delegates the spawn to a
-// runtime-supplied `runChild` callback. The supervisor wires the
+// The runtime body sees the spawn callback shape: given a `definitionRef`
+// (the internal ref the deploy step assigned when it lifted the authored
+// inline child), a parent-allocated `childRunId`, the materialized child
+// input, and parent attribution, settle once the child run reaches a terminal
+// phase. The adapter itself does not execute the child workflow -- it resolves
+// the `definitionRef` into a concrete `WorkflowDefinition` and delegates the
+// spawn to a runtime-supplied `runChild` callback. The supervisor wires the
 // callback against a child `WorkflowRuntimeEnv` and `runtimeRun`.
 //
-// Resolution path:
-//   1. Build `RepoId { kind: "workflow", id: definitionRef }` against
-//      the substrate the deploy orchestrator wrote the workflow asset
-//      into.
-//   2. Read `workflow.json` from the deploy ref's working tree at
-//      `getRepoDir(repoId)`. The deploy-time `writeTree` materializes
-//      the file on disk under the same path, so a flat `fs.readFile`
-//      against the substrate's repo dir gives the workflow envelope
-//      without dragging in a git object-database read for this commit.
-//      The sibling repo-store and blob-substrate adapters use the same
-//      working-tree-read pattern.
-//   3. Parse as JSON, validate the envelope shape via
-//      `workflowDefinitionEnvelopeSchema`, and surface the parsed
-//      object as a `WorkflowDefinition`. The state-machine-narrowed
-//      primitives are validated by the runtime body downstream; the
-//      adapter does the structural-shape check the workflow-kind
-//      handler already enforces at push time so a tampered-on-disk
-//      tree still surfaces a clear error here rather than crashing
-//      deep inside the runtime.
+// Two spawn types with DIFFERENT trust structures resolve here, so they
+// take different resolution paths -- not one shared resolver that pretends
+// they are the same:
+//
+//   - onTrigger BODY (the suspendable adapter): a body is a section
+//     extracted from the PARENT's own approved definition. Source-ref is the
+//     only deploy lineage, so the body is resolved in-memory from the parent's
+//     re-evaluated closure (`createInMemorySpawnSuspendableChild`), already
+//     covered by the parent's re-verify -- no separate on-disk read and no
+//     separate per-body re-verify.
+//
+//   - childWorkflow (the terminal adapter): an owned import embedded inline in
+//     the parent's definition. It is lifted to an internal `{ ref }` at child
+//     boot and resolved in-memory from the parent's closure map
+//     (`createInMemorySpawnChild`) -- exactly like a source-ref onTrigger
+//     body, with NO on-disk asset and NO separate per-child re-verify (the
+//     parent's re-verify already covers it, since the inline child rides the
+//     parent's hashed projection). The terminal-only drive (await the child's
+//     terminal, no park) is the only thing that distinguishes it from the
+//     suspendable body adapter.
 //
 // Drain coordination is handled by the supervisor's drain primitive
 // (`packages/workflow-host/src/supervisor`), not by this adapter. The
@@ -59,21 +59,17 @@
 // `runChild` does -- but the callback's input shape (`{ definition,
 // childRunId, ... }`) is the seam that makes the scoping unambiguous
 // at the boundary.
-import { type } from "arktype";
-import { workflowDefinitionEnvelopeSchema } from "@intx/hub-sessions/substrate";
-const WORKFLOW_JSON_PATH = "workflow.json";
-/**
- * Construct the production `WorkflowRuntimeEnv.SpawnChildWorkflow`
- * adapter. The substrate handle, the principal, the deploy ref, and
- * the runtime-supplied child callback live in closure; the returned
- * callable satisfies the runtime-env interface.
- */
-export function createWorkflowSpawnChild(opts) {
-    return async ({ definitionRef, childRunId, input, parentRunId, parentStepId, signal, }) => {
+export function createInMemorySpawnChild(opts) {
+    return async ({ definitionRef, childRunId, input, parentRunId, parentStepId, signal, depth, maxChildSpawnDepth, }, onEvent, credentialMaterial) => {
         if (signal.aborted) {
             throw abortError(signal);
         }
-        const definition = await resolveDefinition(opts, definitionRef);
+        const definition = opts.bodies.get(definitionRef);
+        if (definition === undefined) {
+            throw new Error(`workflow-runtime: spawn-child has no in-memory childWorkflow ` +
+                `definition for ${JSON.stringify(definitionRef)}; the parent's ` +
+                `closure should have lifted every inline child`);
+        }
         // Re-check the abort signal after the resolution await. The
         // caller can fire `signal.abort()` between the entry-time check
         // and here; without this re-check the child callback would be
@@ -91,46 +87,52 @@ export function createWorkflowSpawnChild(opts) {
             parentRunId,
             parentStepId,
             signal,
-        });
+            depth,
+            maxChildSpawnDepth,
+        }, onEvent, credentialMaterial);
         return { terminalStatus: result.terminalStatus };
     };
 }
-async function resolveDefinition(opts, definitionRef) {
-    const repoId = { kind: "workflow", id: definitionRef };
-    const fs = await import("node:fs/promises");
-    const path = await import("node:path");
-    const dir = opts.substrate.getRepoDir(repoId);
-    const workflowPath = path.join(dir, WORKFLOW_JSON_PATH);
-    let raw;
-    try {
-        raw = await fs.readFile(workflowPath, "utf8");
-    }
-    catch (cause) {
-        if (isErrnoNotFound(cause)) {
-            throw new Error(`workflow-runtime: spawn-child cannot resolve definitionRef ${JSON.stringify(definitionRef)}: ${WORKFLOW_JSON_PATH} not present under ${repoId.kind}/${repoId.id} on ${opts.deployRef}`, { cause });
+/**
+ * Construct the `WorkflowRuntimeEnv.SpawnSuspendableChild` adapter for the
+ * source-ref (code-sourced) path -- the only deploy lineage. The parent child
+ * re-evaluated the whole pinned closure in one sandbox and re-verified it
+ * against the approved hash -- which already covers every inline onTrigger body
+ * -- so the body definitions are in hand and already proven. Resolve each
+ * `definitionRef` from that in-memory `bodies` map and run it in-process, with
+ * NO disk round-trip and NO separate per-body re-verify: materializing the body
+ * back out and re-fingerprinting it would round-trip trusted-in-hand data for no
+ * gain, and the closure re-eval on restart re-derives the same bodies durably.
+ * The body still runs in the parent's sandbox (in-process today; a stricter
+ * per-body boundary is the deferred, opt-in SandboxBoundary case).
+ */
+export function createInMemorySpawnSuspendableChild(opts) {
+    return async ({ definitionRef, childRunId, input, parentRunId, parentStepId, signal, depth, maxChildSpawnDepth, resumeFromEvents, }, onEvent, credentialMaterial) => {
+        if (signal.aborted) {
+            throw abortError(signal);
+        }
+        const definition = opts.bodies.get(definitionRef);
+        if (definition === undefined) {
+            throw new Error(`workflow-runtime: source-ref spawn-child has no in-memory onTrigger ` +
+                `body for ${JSON.stringify(definitionRef)}; the parent's closure ` +
+                `re-eval should have extracted every inline body`);
+        }
+        if (signal.aborted) {
+            throw abortError(signal);
         }
-        throw cause;
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch (cause) {
-        throw new Error(`workflow-runtime: spawn-child read ${WORKFLOW_JSON_PATH} for ${repoId.kind}/${repoId.id} on ${opts.deployRef} is not valid JSON`, { cause });
-    }
-    const validated = workflowDefinitionEnvelopeSchema(parsed);
-    if (validated instanceof type.errors) {
-        throw new Error(`workflow-runtime: spawn-child ${WORKFLOW_JSON_PATH} for ${repoId.kind}/${repoId.id} on ${opts.deployRef} failed envelope validation: ${validated.summary}`);
-    }
-    // The envelope schema enforces the structural shape the workflow
-    // body and state machine consume; the discriminated narrow over
-    // every `Primitive` variant lives downstream (the runtime body
-    // walks the steps and dispatches per-kind). Re-deriving the
-    // primitive narrow here would duplicate `defineWorkflow`'s
-    // validation, and the workflow-kind handler already enforced the
-    // same envelope at push time.
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- WorkflowDefinition's primitive union is narrowed downstream by the runtime body; the envelope schema enforces the structural shape this adapter cares about
-    return validated;
+        return opts.runSuspendableChild({
+            definition,
+            definitionRef,
+            childRunId,
+            input,
+            parentRunId,
+            parentStepId,
+            signal,
+            depth,
+            maxChildSpawnDepth,
+            ...(resumeFromEvents !== undefined ? { resumeFromEvents } : {}),
+        }, onEvent, credentialMaterial);
+    };
 }
 /**
  * Construct the rejection used when `signal.aborted` short-circuits.
@@ -144,9 +146,3 @@ function abortError(signal) {
         return reason;
     return new DOMException("aborted", "AbortError");
 }
-function isErrnoNotFound(cause) {
-    if (cause === null || typeof cause !== "object")
-        return false;
-    const code = cause.code;
-    return code === "ENOENT";
-}

package/dist/adapters/step-invoker.d.ts

@@ -1,7 +1,7 @@
 import { type Agent, type AgentDefinition, type BaseEnv } from "@intx/agent";
-import type { InferenceEvent, InferenceSource } from "@intx/types/runtime";
+import type { InboundMessage, InferenceEvent, InferenceSource, MailPartReader } from "@intx/types/runtime";
 import type { StepInvokeRequest, StepInvoker, WorkflowAuthorizeFn } from "@intx/workflow";
-import type { WarmAgentCache } from "../child/warm-agent-cache.js";
+import type { WarmAgentCache, WarmReplyDrive } from "../child/warm-agent-cache.js";
 /**
  * Per-step env contributions the caller of the adapter owns.
  *
@@ -104,6 +104,56 @@ export interface WorkflowStepInvokerOpts {
      * has no cross-run conversation to mirror.
      */
     onRunBoundary?: (key: string) => Promise<void>;
+    /**
+     * Seed hook for the warm path (design §3c threading). When supplied, the
+     * adapter calls it before `agent.send` on every message whose delivered
+     * input is a mail-derived `InboundMessage`, passing the step identity
+     * (`authzContext.stepId`, the same key `onRunBoundary` and the warm cache
+     * use) and that message. The sidecar wires this to the warm agent's
+     * durable conversation store, which routes the message onto the connector
+     * thread (seeding threadRoot / lastMessageId / replyTo) so the reply path
+     * can compose a threaded reply. Awaited before the send so the thread
+     * state is committed and durably flushed before the reply is produced; a
+     * seed failure surfaces by rejecting the step.
+     *
+     * Only mail-derived inbound messages seed: an approval-resume inbound
+     * carries a synthetic sender and a correlation id, and a synthesized
+     * string input is not a message, so neither advances the connector
+     * thread. Omitted on the cold path, which has no durable connector state
+     * to seed.
+     */
+    seedInbound?: (key: string, message: InboundMessage) => Promise<void>;
+    /**
+     * Connector reply-drain hook for the warm path (design §3c). When supplied,
+     * the adapter invokes it ONCE -- at the warm agent's first-message build --
+     * with the step identity (`authzContext.stepId`, the same key the warm
+     * cache, seed, and run-boundary hooks use) and the agent's lifetime event
+     * stream. The sidecar wires this to the shared connector reply drain: on
+     * every `connector.reply` the agent emits, the drain composes a threaded
+     * reply from the durable store's connector thread and sends it through the
+     * supervisor-backed outbound bridge, then advances the thread from the send
+     * receipt.
+     *
+     * The returned drive handle exposes the drain's lifetime `done` promise --
+     * which settles when the agent's stream ends at eviction, folded into the
+     * warm entry's event-forward promise so the cache drains the reply loop
+     * alongside the observability forwarder -- plus the per-turn settle barrier
+     * (`replySeq` / `waitForReplyAfter`) the warm step gates each reply turn on,
+     * so the run parks only after the reply is durably sent.
+     *
+     * Omitted on the cold path (a torn-down per-step agent has no cross-message
+     * connector thread) and whenever the deployment is not warm-kept.
+     */
+    driveReplies?: (key: string, stream: ReturnType<Agent["stream"]>) => WarmReplyDrive;
+    /**
+     * Reader for the run's inbound-mail parts. When the step input is a decoded
+     * `Mail`, the adapter resolves each part's `ref` to its committed bytes
+     * through this reader and delivers a real `InboundMessage` (text and/or
+     * attachments) to `agent.send`. Supplied by the run child for the top-level
+     * run's steps; absent for body steps, where a part whose bytes must be read
+     * is refused loudly rather than silently flattened to text.
+     */
+    mailPartReader?: MailPartReader;
 }
 /**
  * Construct the production `WorkflowRuntimeEnv.StepInvoker` adapter.