@intx/workflow-host 0.3.0 → 0.4.0

package/dist/testing/memory-streams.js

@@ -0,0 +1,211 @@
+// In-memory stand-ins for the two IPC transports, for tests that drive a
+// supervisor or a workflow-process child without spawning one.
+//
+// Seventeen copies of these two factories accumulated across this package,
+// `apps/sidecar`, and the deploy tests, in nine variants apiece. The
+// divergences were almost entirely cosmetic, but the copies disagreed on one
+// thing that matters: whether `inject` appends the newline terminator that
+// delimits a wire frame.
+//
+// The two doubles answer that differently, because the two channels carry the
+// terminator differently. The event channel is byte-oriented and its
+// terminator is part of the payload, so `createMemoryFrameStream` separates
+// three roles and a caller says which one it means:
+//
+//   `writer`    what production writes through; bytes go in verbatim
+//   `inject`    one complete frame arriving on the wire, terminator supplied
+//   `injectRaw` bytes verbatim, for a deliberately malformed wire
+//
+// The control channel is line-oriented: one NDJSON line is one frame, and the
+// terminator is the line break the buffer does not store. So
+// `createMemoryNdjsonStream` has no third role -- `writer.write` and `inject`
+// are the same function -- and it strips one trailing newline, so a caller
+// that spells the terminator and one that omits it buffer the same line. A
+// malformed control frame is spelled as a malformed line, which `inject`
+// passes through unchanged apart from that newline, so there is no separate
+// raw role for a caller to reach for.
+//
+// A reader supports ONE `read()` iteration. Both channels are single-consumer
+// by construction -- the supervisor starts one pump per stream per child --
+// and the buffer is drained by whoever iterates, so a second iteration would
+// silently steal frames from the first. `read()` enforces that rather than
+// trusting it, because the way it gets violated is invisible: a spawner
+// double that hands the same streams to a respawned child re-reads them, and
+// the second iteration returns immediately off the closed stream instead of
+// receiving the new child's frames. The child then looks like it died on its
+// handshake, which is indistinguishable from the failure such a test is
+// usually written to examine.
+function announce(observers) {
+    const waiting = observers.list;
+    observers.list = [];
+    for (const observer of waiting)
+        observer();
+}
+/**
+ * Resolves on the next item to reach the buffer, from either direction.
+ *
+ * Edge-triggered: it does not see an item already buffered. A caller reads
+ * `flushed`, arms this, and re-checks in a loop, with the read and the arm in
+ * ONE synchronous block -- an `await` between them is what loses an item.
+ * Which of the two comes first inside that block decides nothing, because
+ * nothing can land between two synchronous statements. Both orders are in use
+ * here (`waitForUpstreamPayload` arms first, the park-notify waits in
+ * `apps/sidecar` read first) and both are safe for that reason.
+ */
+function nextWriteOf(observers) {
+    return new Promise((resolve) => {
+        observers.list.push(resolve);
+    });
+}
+export function createMemoryNdjsonStream() {
+    const buffer = [];
+    const observers = { list: [] };
+    const readObservers = { list: [] };
+    let reads = 0;
+    let waiter = null;
+    let done = false;
+    let reading = false;
+    function wake() {
+        const w = waiter;
+        waiter = null;
+        if (w)
+            w();
+    }
+    function push(line) {
+        buffer.push(line.replace(/\n$/, ""));
+        wake();
+        announce(observers);
+    }
+    const reader = {
+        read() {
+            if (reading) {
+                throw new Error("createMemoryNdjsonStream: a second read() on one stream; hand each spawn its own streams, as a real spawn does");
+            }
+            reading = true;
+            return (async function* () {
+                let handedOut = false;
+                for (;;) {
+                    if (handedOut) {
+                        // Counted here, on re-entry, rather than beside the `yield`. A
+                        // `for await` loop calls `next()` only after its body has run to
+                        // completion, so re-entry is the point at which the previous line
+                        // is finished with. Counting at the `yield` instead resolves a
+                        // waiter whose continuation is queued AHEAD of the consumer's, so
+                        // the one assertion the count exists for -- that a frame was
+                        // ignored -- would run before the consumer had looked at it.
+                        handedOut = false;
+                        reads += 1;
+                        announce(readObservers);
+                    }
+                    if (buffer.length > 0) {
+                        const next = buffer.shift();
+                        if (next === undefined) {
+                            throw new Error("buffer shift returned undefined");
+                        }
+                        handedOut = true;
+                        yield next;
+                        continue;
+                    }
+                    if (done)
+                        return;
+                    await new Promise((resolve) => {
+                        waiter = resolve;
+                    });
+                }
+            })();
+        },
+    };
+    return {
+        writer: { write: push },
+        reader,
+        inject: push,
+        flushed: () => buffer.slice(),
+        nextWrite: () => nextWriteOf(observers),
+        readCount: () => reads,
+        async awaitReadCount(count) {
+            for (;;) {
+                // Re-checked on every pass: level-triggered on the count, so a read
+                // that happened before this call resolves it. An edge wait on the next
+                // read deadlocks here, because the consumer usually reads an injected
+                // frame before a test can ask to be told about it.
+                const read = nextWriteOf(readObservers);
+                if (reads >= count)
+                    return;
+                await read;
+            }
+        },
+        close() {
+            done = true;
+            wake();
+            // A closed stream takes nothing further, so release anyone still
+            // watching rather than leaving them parked on a write that cannot come.
+            announce(observers);
+            announce(readObservers);
+        },
+    };
+}
+export function createMemoryFrameStream() {
+    const buffer = [];
+    const observers = { list: [] };
+    let waiter = null;
+    let done = false;
+    let reading = false;
+    function wake() {
+        const w = waiter;
+        waiter = null;
+        if (w)
+            w();
+    }
+    function pushRaw(bytes) {
+        buffer.push(bytes);
+        wake();
+        announce(observers);
+    }
+    const reader = {
+        read() {
+            if (reading) {
+                throw new Error("createMemoryFrameStream: a second read() on one stream; hand each spawn its own streams, as a real spawn does");
+            }
+            reading = true;
+            return (async function* () {
+                for (;;) {
+                    if (buffer.length > 0) {
+                        const next = buffer.shift();
+                        if (next === undefined) {
+                            throw new Error("frame buffer shift returned undefined");
+                        }
+                        yield next;
+                        continue;
+                    }
+                    if (done)
+                        return;
+                    await new Promise((resolve) => {
+                        waiter = resolve;
+                    });
+                }
+            })();
+        },
+    };
+    return {
+        writer: { write: pushRaw },
+        reader,
+        inject(bytes) {
+            // The event channel is newline-delimited: its sender terminates every
+            // frame, and the receiver splits on that terminator. A caller passing
+            // envelope bytes is describing one frame, so the terminator belongs
+            // here rather than at each call site.
+            const framed = new Uint8Array(bytes.length + 1);
+            framed.set(bytes, 0);
+            framed[bytes.length] = 0x0a;
+            pushRaw(framed);
+        },
+        injectRaw: pushRaw,
+        flushed: () => buffer.slice(),
+        nextWrite: () => nextWriteOf(observers),
+        close() {
+            done = true;
+            wake();
+            announce(observers);
+        },
+    };
+}

package/dist/testing/spawn-observer.d.ts

@@ -0,0 +1,12 @@
+export type SpawnObserver = {
+    /** Call from inside the spawner double with the env it received. */
+    record(env: Record<string, string>): void;
+    /**
+     * Resolve with the first recorded env, whether the spawn has happened yet
+     * or not. A respawn records again; this always resolves with the first.
+     */
+    first(): Promise<Record<string, string>>;
+    /** Every env recorded so far, in spawn order. */
+    all(): readonly Record<string, string>[];
+};
+export declare function createSpawnObserver(): SpawnObserver;

package/dist/testing/spawn-observer.js

@@ -0,0 +1,36 @@
+// Records the environment each spawn was invoked with, and lets a caller wait
+// for the first one.
+//
+// A test that needs the spawn-time env -- almost always to read the IPC
+// channel id and mint a child-side sender -- has to wait for the spawner to
+// be called. Twenty-two sites did that by assigning a mutable binding inside
+// the spawner and re-reading it on a one-millisecond timer until it stopped
+// being undefined. The spawner being called IS the event, so it is reported
+// rather than inferred.
+export function createSpawnObserver() {
+    const envs = [];
+    let waiters = [];
+    return {
+        record(env) {
+            envs.push(env);
+            const waiting = waiters;
+            waiters = [];
+            for (const waiter of waiting)
+                waiter();
+        },
+        async first() {
+            for (;;) {
+                // Re-read on every pass, so a spawn that happened before this call
+                // resolves it rather than leaving it waiting for another one.
+                const spawned = new Promise((resolve) => {
+                    waiters.push(resolve);
+                });
+                const head = envs[0];
+                if (head !== undefined)
+                    return head;
+                await spawned;
+            }
+        },
+        all: () => envs.slice(),
+    };
+}

package/dist/testing/stub-repo-store.d.ts

@@ -0,0 +1,10 @@
+import type { RepoStore } from "@intx/hub-sessions";
+export type StubRepoStoreOpts = {
+    /**
+     * Permit `writeTreePreservingPrefix`, returning a fixed commit and no
+     * newly-terminal runs. Off by default, so a test that does not ask for it
+     * fails on the call rather than accepting it.
+     */
+    writeTree?: boolean;
+};
+export declare function createStubRepoStore(baseDir: string, opts?: StubRepoStoreOpts): RepoStore;

package/dist/testing/stub-repo-store.js

@@ -0,0 +1,39 @@
+// A RepoStore that implements only what a test declares it needs, and throws
+// for everything else.
+//
+// The throw is the point. These stubs assert, by failing, that the code under
+// them touches nothing beyond the named surface -- so the narrow ones are not
+// an incomplete version of the broad ones, and substituting a working store
+// would silently permit paths that currently fail loudly.
+//
+// Only the two capability sets that were byte-identical across several files
+// live here. The rest of this repo's stub stores are genuinely different
+// fidelities, up to a 218-line in-memory implementation, and merging those
+// would trade a real assertion for a smaller diff.
+import path from "node:path";
+export function createStubRepoStore(baseDir, opts = {}) {
+    const stub = {
+        getRepoDir(repoId) {
+            return path.join(baseDir, repoId.kind, repoId.id);
+        },
+        ...(opts.writeTree === true
+            ? {
+                writeTreePreservingPrefix: async () => ({
+                    commitSha: "deadbeefcafef00d",
+                    newlyTerminalRuns: [],
+                }),
+            }
+            : {}),
+    };
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- test stub; every method the opts did not enable surfaces a precise failure via the proxy
+    return new Proxy(stub, {
+        get(target, prop, receiver) {
+            const value = Reflect.get(target, prop, receiver);
+            if (value !== undefined)
+                return value;
+            return () => {
+                throw new Error(`stub RepoStore: ${String(prop)} not implemented for this test`);
+            };
+        },
+    });
+}

package/dist/testing/supervisor-reaper.d.ts

@@ -0,0 +1,24 @@
+/** The part of a supervisor a reaper needs. */
+export type ReapableSupervisor = {
+    shutdown(): Promise<void>;
+};
+export type SupervisorReaper = {
+    /** Register a supervisor and return it, for use at the construction site. */
+    track<T extends ReapableSupervisor>(supervisor: T): T;
+    /**
+     * Shut down every supervisor registered since the last call. Pass straight
+     * to `afterEach`.
+     *
+     * The teardowns overlap: every `shutdown()` is called before any is awaited,
+     * so they settle in whatever order they finish rather than registration
+     * order. Nothing here sequences one supervisor's teardown after another's.
+     *
+     * `shutdown` early-returns once the phase is terminal. That guard does not
+     * cover `stopping`, so a teardown already in flight is re-entered here --
+     * harmlessly, because every branch of the teardown is guarded on the prior
+     * phase and a second pass through `stopping` does no work. Either way the
+     * tests that tear themselves down are unaffected.
+     */
+    reap(): Promise<void>;
+};
+export declare function createSupervisorReaper(): SupervisorReaper;

package/dist/testing/supervisor-reaper.js

@@ -0,0 +1,49 @@
+// Per-file registry of the supervisors a test built, so a lifecycle hook can
+// tear them down whatever way the test ended.
+//
+// A supervisor is normally torn down by a `shutdown()` at the end of the test
+// that built it, which an earlier failed assertion skips -- and some tests
+// never had one. What that abandons is not inert: a dispatch suspended in
+// `waitForRunTerminalOrPark` holds that function's armed five-minute
+// backstop, whose clearing `finally` cannot run while the race it guards is
+// pending. Aborting the cohort is what settles that race, so reaping is what
+// disarms the timer. The unit pass shares a module registry per worker, so an
+// un-reaped supervisor outlives its file and any failure it causes is charged
+// to an unrelated test.
+//
+// The registry is per-call rather than module-level: two test files importing
+// one shared array would reap each other's supervisors if their lifecycles
+// ever overlapped.
+export function createSupervisorReaper() {
+    const live = [];
+    return {
+        track(supervisor) {
+            live.push(supervisor);
+            return supervisor;
+        },
+        async reap() {
+            // Every `shutdown()` is CALLED before any of them is awaited, so no
+            // supervisor's teardown waits on its neighbours': one that REJECTS and
+            // one that never SETTLES both leave the rest to run to completion.
+            // Awaiting them one at a time would not -- a teardown that never
+            // settled would mean the supervisors behind it never started theirs,
+            // each keeping its child and its armed backstop.
+            //
+            // A non-settling `shutdown()` still blocks this function's own
+            // resolution, because `allSettled` waits for that one too -- so the
+            // `afterEach` calling it does not complete, and the lane timeout is what
+            // fails the file. Abandoning the pending one would take a deadline,
+            // which "Synchronizing on State, Not Time" in CONVENTIONS.md rules out,
+            // and `shutdown()` offers no other signal to race. What this covers is
+            // the leak, not the hang.
+            //
+            // `shutdown` is documented as total, so a throw is a defect and fails
+            // the test rather than landing in a log nobody reads.
+            const settled = await Promise.allSettled(live.splice(0).map((supervisor) => supervisor.shutdown()));
+            const failures = settled.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+            if (failures.length > 0) {
+                throw new AggregateError(failures, "supervisor teardown threw");
+            }
+        },
+    };
+}

package/dist/testing/upstream-frames.d.ts

@@ -0,0 +1,47 @@
+import { ControlPayload } from "../ipc/control-channel.js";
+/**
+ * Decode every payload of `type_` from `lines`, in arrival order.
+ *
+ * Frames that fail envelope or payload validation are skipped, so a test
+ * asserting on one payload kind is not fooled by an unrelated frame sharing
+ * the stream.
+ */
+export declare function readPayloadsOfType<T extends string>(lines: readonly string[], type_: T): Extract<typeof ControlPayload.infer, {
+    type: T;
+}>[];
+/** The runIds carried on every `trigger.fire` frame in `lines`, in order. */
+export declare function parseTriggerFireRunIds(lines: readonly string[]): string[];
+/** The part of a stream double this module reads. */
+export type UpstreamFrameSource = {
+    flushed(): readonly string[];
+    nextWrite(): Promise<void>;
+};
+/**
+ * Resolve with the first payload of `type_` that `match` accepts, whether it
+ * is already buffered or arrives later.
+ *
+ * The buffer is re-read only when a line actually arrives, and the wait
+ * carries no deadline: a frame that never comes is caught by the lane
+ * timeout, per "Synchronizing on State, Not Time" in CONVENTIONS.md.
+ */
+export declare function waitForUpstreamPayload<T extends string>(stream: UpstreamFrameSource, type_: T, match?: (payload: Extract<typeof ControlPayload.infer, {
+    type: T;
+}>) => boolean): Promise<Extract<typeof ControlPayload.infer, {
+    type: T;
+}>>;
+/**
+ * Resolve once at least `count` payloads of `type_` have been written, with
+ * every matching payload in arrival order.
+ *
+ * The count form exists because most waits here are for the Nth frame rather
+ * than for a particular one; a caller wanting a specific frame should use
+ * `waitForUpstreamPayload` with a predicate.
+ */
+export declare function waitForUpstreamPayloads<T extends string>(stream: UpstreamFrameSource, type_: T, count?: number): Promise<Extract<typeof ControlPayload.infer, {
+    type: T;
+}>[]>;
+/**
+ * Resolve once at least `count` `trigger.fire` frames have been written, with
+ * every runId seen in order.
+ */
+export declare function waitForTriggerFireRunIds(stream: UpstreamFrameSource, count: number): Promise<string[]>;

package/dist/testing/upstream-frames.js

@@ -0,0 +1,94 @@
+// Reading and awaiting the control frames a supervisor writes upstream.
+//
+// A test that drives a supervisor asserts on the frames it emitted, and has
+// to wait for the one it cares about first. That wait was written as a
+// deadline plus a one-millisecond tick that re-decoded the whole buffer --
+// two wall-clock numbers deciding a run whose subject is what a frame
+// CONTAINS, never how quickly it appears. Waiting on the write removes the
+// window instead of widening it.
+import { type } from "arktype";
+import { ControlPayload } from "../ipc/control-channel.js";
+import { SignedEnvelope } from "../ipc/envelope.js";
+/**
+ * Decode every payload of `type_` from `lines`, in arrival order.
+ *
+ * Frames that fail envelope or payload validation are skipped, so a test
+ * asserting on one payload kind is not fooled by an unrelated frame sharing
+ * the stream.
+ */
+export function readPayloadsOfType(lines, type_) {
+    const out = [];
+    for (const line of lines) {
+        let raw;
+        try {
+            raw = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const signed = SignedEnvelope(raw);
+        if (signed instanceof type.errors)
+            continue;
+        const payload = ControlPayload(signed.envelope.payload);
+        if (payload instanceof type.errors)
+            continue;
+        if (payload.type !== type_)
+            continue;
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- the arktype narrow above pins the discriminator; the cast walks the union to the matching branch
+        out.push(payload);
+    }
+    return out;
+}
+/** The runIds carried on every `trigger.fire` frame in `lines`, in order. */
+export function parseTriggerFireRunIds(lines) {
+    return readPayloadsOfType(lines, "trigger.fire").map((p) => p.data.runId);
+}
+/**
+ * Resolve with the first payload of `type_` that `match` accepts, whether it
+ * is already buffered or arrives later.
+ *
+ * The buffer is re-read only when a line actually arrives, and the wait
+ * carries no deadline: a frame that never comes is caught by the lane
+ * timeout, per "Synchronizing on State, Not Time" in CONVENTIONS.md.
+ */
+export async function waitForUpstreamPayload(stream, type_, match = () => true) {
+    for (;;) {
+        // Re-read on every pass, so a frame already in the buffer resolves this
+        // rather than leaving it waiting for the next write.
+        const arrived = stream.nextWrite();
+        const found = readPayloadsOfType(stream.flushed(), type_).find(match);
+        if (found !== undefined)
+            return found;
+        await arrived;
+    }
+}
+/**
+ * Resolve once at least `count` payloads of `type_` have been written, with
+ * every matching payload in arrival order.
+ *
+ * The count form exists because most waits here are for the Nth frame rather
+ * than for a particular one; a caller wanting a specific frame should use
+ * `waitForUpstreamPayload` with a predicate.
+ */
+export async function waitForUpstreamPayloads(stream, type_, count = 1) {
+    for (;;) {
+        const arrived = stream.nextWrite();
+        const found = readPayloadsOfType(stream.flushed(), type_);
+        if (found.length >= count)
+            return found;
+        await arrived;
+    }
+}
+/**
+ * Resolve once at least `count` `trigger.fire` frames have been written, with
+ * every runId seen in order.
+ */
+export async function waitForTriggerFireRunIds(stream, count) {
+    for (;;) {
+        const arrived = stream.nextWrite();
+        const ids = parseTriggerFireRunIds(stream.flushed());
+        if (ids.length >= count)
+            return ids;
+        await arrived;
+    }
+}

package/dist/workflow-definition-loader.d.ts

@@ -1,5 +1,6 @@
 import { type AnnotatedPluginFactory, type DirectorRegistry, type ToolDeclaration } from "@intx/agent";
 import type { WorkflowDefinition } from "@intx/workflow/definition";
+import type { ActionHandler, LoopFnRegistry } from "@intx/workflow";
 export interface LoadWorkflowDefinitionFromClosureArgs {
     /**
      * Directory of the materialized workflow package within the closure:
@@ -75,6 +76,61 @@ export interface LoadWorkflowDirectorRegistryFromClosureArgs {
  *   cannot be imported, or it exports no `AnnotatedDirectorFactory` value
  */
 export declare function loadWorkflowDirectorRegistryFromClosure(args: LoadWorkflowDirectorRegistryFromClosureArgs): Promise<DirectorRegistry>;
+export interface LoadWorkflowLoopFnsFromClosureArgs {
+    /**
+     * Directory of the materialized workflow package within the closure --
+     * the same directory `loadWorkflowDefinitionFromClosure` reads.
+     */
+    readonly packageDir: string;
+    /** See `LoadWorkflowDefinitionFromClosureArgs.importCacheKey`. */
+    readonly importCacheKey?: string;
+    /** Test seam for dynamic import; see the definition loader's variant. */
+    readonly importModule?: (importUrl: string) => Promise<unknown>;
+}
+/**
+ * Compose the `LoopFnRegistry` for a workflow closure from the closure
+ * package's OWN `interchange.loops` module. A `loop` primitive's `while` and
+ * `carry` refs resolve by EXPORT NAME against that module's exports.
+ *
+ * Unlike directors there is NO built-in default: a package with no
+ * `interchange.loops` field composes to an EMPTY registry that throws on any
+ * ref lookup. A workflow that declares a `loop` but ships no loops module thus
+ * fails closed when its refs are resolved (eagerly, at establish); a workflow
+ * with no `loop` primitive never resolves a ref, so an absent field is valid
+ * there. Loading OUTSIDE the definition-hash re-verify is safe: the approved
+ * hash pins each ref string, and the closure's SRI pins the module bytes.
+ *
+ * @throws (from the returned registry) if a requested ref names no export, or
+ *   names an export that is not a function.
+ * @throws if the loops entry path escapes the package or cannot be imported.
+ */
+export declare function loadWorkflowLoopFnsFromClosure(args: LoadWorkflowLoopFnsFromClosureArgs): Promise<LoopFnRegistry>;
+export interface LoadWorkflowActionHandlersFromClosureArgs {
+    /** Directory of the materialized workflow package within the closure. */
+    readonly packageDir: string;
+    /** See `LoadWorkflowDefinitionFromClosureArgs.importCacheKey`. */
+    readonly importCacheKey?: string;
+    /** Test seam for dynamic import; see the definition loader's variant. */
+    readonly importModule?: (importUrl: string) => Promise<unknown>;
+}
+/**
+ * Compose the action-handler resolver for a workflow closure from the closure
+ * package's OWN `interchange.actions` module. An `action` primitive's `handler`
+ * ref resolves by EXPORT NAME against that module's exports.
+ *
+ * Mirrors {@link loadWorkflowLoopFnsFromClosure}: there is NO built-in default,
+ * so a package with no `interchange.actions` field composes to a resolver that
+ * throws on any lookup. A workflow that declares an `action` but ships no
+ * actions module fails closed when its handler is resolved (eagerly, at
+ * establish); a workflow with no `action` primitive never resolves a handler.
+ * Loading OUTSIDE the definition-hash re-verify is safe: the approved hash pins
+ * each handler ref string, and the closure's SRI pins the module bytes.
+ *
+ * @throws (from the returned resolver) if a requested ref names no export, or an
+ *   export that is not a function.
+ * @throws if the actions entry path escapes the package or cannot be imported.
+ */
+export declare function loadWorkflowActionHandlersFromClosure(args: LoadWorkflowActionHandlersFromClosureArgs): Promise<(ref: string) => ActionHandler>;
 export interface LoadWorkflowPluginsFromClosureArgs {
     /**
      * Directory of the materialized workflow package within the closure --