@intx/workflow-host 0.2.2 → 0.4.0

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

@@ -0,0 +1,187 @@
+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:
+     * the directory holding the package's `package.json`, with its
+     * `node_modules/` already laid out by the closure-materialization
+     * machinery so the entry module's bare-specifier imports resolve.
+     */
+    readonly packageDir: string;
+    /**
+     * Optional token mixed into the import URL's query string to bust
+     * Node's ESM module cache. Node keys the ESM cache by resolved
+     * URL/path, not by content: a process that imports the same package
+     * directory twice with different bytes underneath (a rare re-apply in
+     * a reused child) would otherwise resolve to the first-imported module
+     * instance. Passing a per-materialization token (the closure's
+     * integrity SRI is the natural choice) makes each materialization a
+     * distinct ESM cache entry. Omit it when the process imports a given
+     * package directory at most once.
+     */
+    readonly importCacheKey?: string;
+    /**
+     * Test seam for dynamic import. Production omits this and the loader
+     * uses the native dynamic-import expression. The argument is the
+     * `file://` URL the loader resolves for the `interchange.workflow`
+     * entry.
+     */
+    readonly importModule?: (importUrl: string) => Promise<unknown>;
+}
+/**
+ * Import the `interchange.workflow` entry from a materialized workflow
+ * package closure, evaluate it, and return the validated
+ * `WorkflowDefinition` its `defineWorkflow(...)` call produced.
+ *
+ * @param args - the materialized package directory plus optional import
+ *   seams
+ * @returns the validated `WorkflowDefinition`
+ * @throws if the package.json is missing/malformed, declares no
+ *   `interchange.workflow` entry, the entry path escapes the package
+ *   directory, the module cannot be imported, or its evaluation does not
+ *   produce exactly one value that validates as a `WorkflowDefinition`
+ */
+export declare function loadWorkflowDefinitionFromClosure(args: LoadWorkflowDefinitionFromClosureArgs): Promise<WorkflowDefinition>;
+export interface LoadWorkflowDirectorRegistryFromClosureArgs {
+    /**
+     * Directory of the materialized workflow package within the closure --
+     * the same directory `loadWorkflowDefinitionFromClosure` reads. Both the
+     * approval-time probe and the run-child call this over the SAME frozen
+     * closure, so the director set they compose cannot drift.
+     */
+    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 `DirectorRegistry` for a workflow closure from the closure
+ * package's OWN `interchange.directors` module (if any), alongside the
+ * built-in default director. A package with no `interchange.directors`
+ * field composes to the built-ins-only registry -- absence is valid, a
+ * workflow need not ship a director. A present-but-empty directors module
+ * is malformed and throws, matching the tool-package loader.
+ *
+ * Only the workflow's OWN package directors are loaded here. Directors
+ * shipped by PINNED dependency packages are deliberately not resolved on
+ * the source-ref path yet: the airlocked probe does not materialize pinned
+ * packages, so loading them here would let the runtime resolve a director
+ * the probe never advertised for approval. A workflow referencing a
+ * pinned-package director fails closed (the capability walk reports it as
+ * unresolved).
+ *
+ * @throws if the directors entry path escapes the package, the module
+ *   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 --
+     * the same directory `loadWorkflowDefinitionFromClosure` reads. Each
+     * declared plugin package is resolved from this package's laid-out
+     * `node_modules/`, exactly as the workflow entry's own bare-specifier
+     * imports resolve.
+     */
+    readonly packageDir: string;
+    /**
+     * Plugin-package names the workflow's agents declare via
+     * `AgentDefinition.plugins` (`["@intx/tools-lsp"]`). Each MUST be a
+     * direct dependency of the workflow package so it is laid out under the
+     * workflow package's `node_modules/`. Empty is valid (no plugins).
+     */
+    readonly plugins: readonly string[];
+    /** See `LoadWorkflowDefinitionFromClosureArgs.importCacheKey`. */
+    readonly importCacheKey?: string;
+    /** Test seam for dynamic import; see the definition loader's variant. */
+    readonly importModule?: (importUrl: string) => Promise<unknown>;
+}
+/**
+ * Import each declared plugin package's `interchange.tools` module from the
+ * materialized workflow closure and collect the `AnnotatedPluginFactory`
+ * values it exports. This is the run-child counterpart to the tool-package
+ * loader's plugin channel: a source-ref workflow contributes no plugin factory
+ * through its agent definition (a plugin has no agent slot), so the child
+ * materializes the declared plugins straight from the already-laid-out closure
+ * -- no re-download, no manifest -- and feeds them into the existing per-step
+ * plugin chain. The closure bytes were SRI-verified when the deploy applied the
+ * frozen closure, and resolution walks the same `node_modules/` graph the
+ * workflow entry's imports use.
+ *
+ * @throws if a declared plugin package cannot be resolved, declares no
+ *   `interchange.tools` entry, the entry escapes the package, cannot be
+ *   imported, or exports no `AnnotatedPluginFactory` value
+ */
+export declare function loadWorkflowPluginFactoriesFromClosure(args: LoadWorkflowPluginsFromClosureArgs): Promise<AnnotatedPluginFactory[]>;
+/**
+ * Read the static tool `definitions` each declared plugin package
+ * contributes, keyed by plugin-package name, WITHOUT retaining the plugin
+ * factory (so the caller never instantiates a plugin, which for LSP would
+ * start a subprocess). This is the probe/capability-walk counterpart to
+ * `loadWorkflowPluginFactoriesFromClosure`: it loads the SAME plugin module
+ * from the SAME frozen closure so the tool grant surface the walk approves
+ * matches the plugin the run-child materializes.
+ *
+ * A plugin package that exports plugin factories but declares no tool
+ * definitions (a middleware-only plugin) maps to an empty array -- valid,
+ * it contributes no tool grant.
+ *
+ * @throws under the same conditions as `loadWorkflowPluginFactoriesFromClosure`
+ */
+export declare function loadWorkflowPluginToolDefinitionsFromClosure(args: LoadWorkflowPluginsFromClosureArgs): Promise<Map<string, readonly ToolDeclaration[]>>;