@intx/workflow-host 0.3.0 → 0.4.0

package/dist/workflow-definition-loader.js

@@ -112,6 +112,112 @@ export async function loadWorkflowDirectorRegistryFromClosure(args) {
     logger.debug `loaded ${String(loaded.length)} custom director(s) from ${args.packageDir}`;
     return createWorkflowDirectorRegistry(loaded);
 }
+/**
+ * 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 async function loadWorkflowLoopFnsFromClosure(args) {
+    const importModule = args.importModule ?? ((url) => import(url));
+    const pkgJson = await readPackageJSON(args.packageDir);
+    const entryRel = pkgJson.interchange?.loops;
+    if (entryRel === undefined) {
+        // No loops module. A workflow with no loop primitive never calls this; one
+        // that declares a loop fails closed here when its ref is resolved.
+        return (ref) => {
+            throw new Error(`loop fn ${JSON.stringify(ref)} was requested, but the workflow package at ${args.packageDir} declares no interchange.loops module`);
+        };
+    }
+    const entryAbs = await resolveContainedEntry(args.packageDir, entryRel, "interchange.loops");
+    const importUrl = args.importCacheKey === undefined
+        ? pathToFileURL(entryAbs).href
+        : `${pathToFileURL(entryAbs).href}?importCacheKey=${encodeURIComponent(args.importCacheKey)}`;
+    let mod;
+    try {
+        mod = await importModule(importUrl);
+    }
+    catch (cause) {
+        throw new Error(`failed to import interchange.loops entry ${JSON.stringify(entryRel)} for workflow package at ${args.packageDir}`, { cause });
+    }
+    if (mod === null || typeof mod !== "object") {
+        throw new Error(`interchange.loops entry ${JSON.stringify(entryRel)} for workflow package at ${args.packageDir} did not evaluate to a module object`);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- module namespace object: loop fns resolve by export name
+    const loopModule = mod;
+    logger.debug `loaded interchange.loops module from ${args.packageDir}`;
+    return (ref) => {
+        const fn = loopModule[ref];
+        if (typeof fn !== "function") {
+            throw new Error(`interchange.loops entry ${JSON.stringify(entryRel)} for workflow package at ${args.packageDir} exports no loop fn named ${JSON.stringify(ref)}`);
+        }
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- resolved by export name; the loop runtime applies it as a pure (childOutput, carryState) fn
+        return fn;
+    };
+}
+/**
+ * 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 async function loadWorkflowActionHandlersFromClosure(args) {
+    const importModule = args.importModule ?? ((url) => import(url));
+    const pkgJson = await readPackageJSON(args.packageDir);
+    const entryRel = pkgJson.interchange?.actions;
+    if (entryRel === undefined) {
+        return (ref) => {
+            throw new Error(`action handler ${JSON.stringify(ref)} was requested, but the workflow package at ${args.packageDir} declares no interchange.actions module`);
+        };
+    }
+    const entryAbs = await resolveContainedEntry(args.packageDir, entryRel, "interchange.actions");
+    const importUrl = args.importCacheKey === undefined
+        ? pathToFileURL(entryAbs).href
+        : `${pathToFileURL(entryAbs).href}?importCacheKey=${encodeURIComponent(args.importCacheKey)}`;
+    let mod;
+    try {
+        mod = await importModule(importUrl);
+    }
+    catch (cause) {
+        throw new Error(`failed to import interchange.actions entry ${JSON.stringify(entryRel)} for workflow package at ${args.packageDir}`, { cause });
+    }
+    if (mod === null || typeof mod !== "object") {
+        throw new Error(`interchange.actions entry ${JSON.stringify(entryRel)} for workflow package at ${args.packageDir} did not evaluate to a module object`);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- module namespace object: action handlers resolve by export name
+    const actionModule = mod;
+    logger.debug `loaded interchange.actions module from ${args.packageDir}`;
+    return (ref) => {
+        const fn = actionModule[ref];
+        if (typeof fn !== "function") {
+            throw new Error(`interchange.actions entry ${JSON.stringify(entryRel)} for workflow package at ${args.packageDir} exports no action handler named ${JSON.stringify(ref)}`);
+        }
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- resolved by export name; invoked as an ActionHandler (input, ctx, signal) by createDefaultActionInvoker
+        return fn;
+    };
+}
 /**
  * Import each declared plugin package's `interchange.tools` module from the
  * materialized workflow closure and collect the `AnnotatedPluginFactory`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@intx/workflow-host",
   "description": "Production-host implementations of the abstract WorkflowRuntimeEnv from @intx/workflow",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "license": "LGPL-2.1-only",
   "type": "module",
   "exports": {
@@ -9,19 +9,25 @@
       "intx-src": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./testing": {
+      "intx-src": "./src/testing/index.ts",
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
     }
   },
   "dependencies": {
-    "@intx/agent": "0.3.0",
-    "@intx/crypto": "0.3.0",
-    "@intx/hub-sessions": "0.3.0",
-    "@intx/inference": "0.3.0",
-    "@intx/log": "0.3.0",
-    "@intx/mail-memory": "0.3.0",
-    "@intx/mime": "0.3.0",
-    "@intx/storage-isogit": "0.3.0",
-    "@intx/types": "0.3.0",
-    "@intx/workflow": "0.3.0",
+    "@intx/agent": "0.4.0",
+    "@intx/crypto": "0.4.0",
+    "@intx/hub-sessions": "0.4.0",
+    "@intx/inference": "0.4.0",
+    "@intx/log": "0.4.0",
+    "@intx/mail-memory": "0.4.0",
+    "@intx/mailbox": "0.4.0",
+    "@intx/mime": "0.4.0",
+    "@intx/storage-isogit": "0.4.0",
+    "@intx/types": "0.4.0",
+    "@intx/workflow": "0.4.0",
     "arktype": "^2.1.29"
   },
   "files": [

package/dist/conversation-text.d.ts

@@ -1,23 +0,0 @@
-/**
- * Extract the conversation body text from a raw inbound MIME message.
- *
- * Three on-wire shapes are handled, matching every producer the mail
- * bus accepts:
- *   1. The Interchange assembler's `multipart/signed` envelope whose
- *      first part is a `multipart/mixed` body carrying the text at part
- *      path `1.1`.
- *   2. A `multipart/signed` envelope wrapping a bare `text/plain` part
- *      (a sender that signs without the `multipart/mixed` wrapper); the
- *      text is at part path `1`.
- *   3. A flat top-level `text/plain` message (no multipart structure at
- *      all); the body is the bytes after the header section.
- *
- * The top-level `Content-Type` selects the shape: only a `multipart/*`
- * root walks into parts; anything else reads the single body directly.
- * This mirrors the conversation branch of mail-memory's `fetchFull`
- * while also tolerating the flat single-part case the in-process agent
- * accepts, so a non-standard inbound mail still delivers its text to
- * the agent rather than crashing the run. `messageId` is used only for
- * error attribution.
- */
-export declare function extractConversationText(raw: Uint8Array, messageId: string): string;

package/dist/conversation-text.js

@@ -1,56 +0,0 @@
-// Shared inbound-mail conversation-text extraction. Two call sites resolve a
-// run's mail input to the text the agent actually sees, each at the layer that
-// knows its bytes are inbound mail: the child's `resolveTriggerPayload` (turn
-// 1, the trigger) reads the mail from the substrate, and the supervisor's
-// dispatch loop (turn 2+, a mail delivered to a parked run as a signal) inlines
-// it. Both must produce the SAME shape -- extracted body text, not the raw MIME
-// envelope -- so the extractor lives here rather than in either caller.
-import { extractPartByPath, parseHeaderSection, parseMimePart, } from "@intx/mime";
-/**
- * Extract the conversation body text from a raw inbound MIME message.
- *
- * Three on-wire shapes are handled, matching every producer the mail
- * bus accepts:
- *   1. The Interchange assembler's `multipart/signed` envelope whose
- *      first part is a `multipart/mixed` body carrying the text at part
- *      path `1.1`.
- *   2. A `multipart/signed` envelope wrapping a bare `text/plain` part
- *      (a sender that signs without the `multipart/mixed` wrapper); the
- *      text is at part path `1`.
- *   3. A flat top-level `text/plain` message (no multipart structure at
- *      all); the body is the bytes after the header section.
- *
- * The top-level `Content-Type` selects the shape: only a `multipart/*`
- * root walks into parts; anything else reads the single body directly.
- * This mirrors the conversation branch of mail-memory's `fetchFull`
- * while also tolerating the flat single-part case the in-process agent
- * accepts, so a non-standard inbound mail still delivers its text to
- * the agent rather than crashing the run. `messageId` is used only for
- * error attribution.
- */
-export function extractConversationText(raw, messageId) {
-    const { headers, bodyOffset } = parseHeaderSection(raw);
-    const rootMime = (headers.get("content-type") ?? "")
-        .split(";")[0]
-        ?.trim()
-        .toLowerCase();
-    if (rootMime === undefined || !rootMime.startsWith("multipart/")) {
-        // Flat single-part message: the body is everything after the
-        // header section.
-        return new TextDecoder("utf-8", { fatal: false }).decode(raw.subarray(bodyOffset));
-    }
-    let part1;
-    try {
-        part1 = parseMimePart(extractPartByPath(raw, "1"));
-    }
-    catch (cause) {
-        throw new Error(`conversation-text: cannot parse inbound mail part 1 for messageId ${messageId}`, { cause });
-    }
-    const part1Mime = (part1.contentType.split(";")[0] ?? "")
-        .trim()
-        .toLowerCase();
-    const bodyBytes = part1Mime.startsWith("multipart/")
-        ? parseMimePart(extractPartByPath(raw, "1.1")).body
-        : part1.body;
-    return new TextDecoder("utf-8", { fatal: false }).decode(bodyBytes);
-}