@oomol-lab/open-flow 0.1.0-beta.3 → 0.1.0-beta.30

package/dist/common/runtime-contract.js

@@ -19,19 +19,101 @@ function t(n, r) {
 }
 //#endregion
 //#region src/execution/common/engineContract.ts
-var n = "open-flow-engine/v1", r = {
+var n = "open-flow-engine/v5", r = "open-flow-engine/v5/nodejs-compat-v1", i = {
 	platformExports: /* @__PURE__ */ new Set(["engineContract", "identity"]),
 	platformModule: "open-flow:platform",
 	platformSource: `export const engineContract = ${JSON.stringify(n)}
 export function identity(value) { return value }
 `
+}, a = {
+	...i,
+	builtinModules: new Set([
+		"assert",
+		"assert/strict",
+		"buffer",
+		"console",
+		"constants",
+		"crypto",
+		"events",
+		"fs",
+		"fs/promises",
+		"os",
+		"path",
+		"path/posix",
+		"process",
+		"punycode",
+		"querystring",
+		"stream",
+		"stream/promises",
+		"stream/web",
+		"string_decoder",
+		"timers",
+		"timers/promises",
+		"url",
+		"util",
+		"zlib"
+	].flatMap((e) => [e, `node:${e}`])),
+	platformSource: `export const engineContract = ${JSON.stringify(r)}
+export function identity(value) { return value }
+`
 };
-function i(e) {
-	return e == "open-flow-engine/v1" ? r : void 0;
+function o(e) {
+	if (e == "open-flow-engine/v5") return i;
+	if (e == "open-flow-engine/v5/nodejs-compat-v1") return a;
 }
 //#endregion
 //#region src/execution/common/runtime.ts
-function a(e, t, r = {}) {
+function s(e) {
+	let t = /* @__PURE__ */ new Set(), n = (e, r) => {
+		if (r > 64) throw Error("Task result exceeds the maximum JSON depth.");
+		if (e === null || typeof e == "string" || typeof e == "boolean" || typeof e == "number" && Number.isFinite(e)) return e;
+		if (typeof e != "object" || t.has(e) || !Array.isArray(e) && Object.getPrototypeOf(e) !== Object.prototype && Object.getPrototypeOf(e) !== null || Object.getOwnPropertySymbols(e).length > 0) throw Error("Task result must contain only JSON values.");
+		t.add(e);
+		let i = Array.isArray(e) ? Array.from(e, (e) => n(e, r + 1)) : Object.fromEntries(Object.entries(e).filter(([, e]) => r != 0 || e !== void 0).map(([e, t]) => [e, n(t, r + 1)]));
+		return t.delete(e), i;
+	};
+	return e === void 0 ? void 0 : n(e, 0);
+}
+var c = [{
+	name: "supports Node builtin imports and asynchronous virtual file operations",
+	async verify(e) {
+		u(await e.invoke({
+			capability: async () => ({
+				body: null,
+				status: 403
+			}),
+			input: null,
+			invocationId: "nodejs-files",
+			program: {
+				...l(e, "import assert from 'node:assert/strict';\nimport { Buffer } from 'node:buffer'; import path from 'node:path'; import fs from 'node:fs/promises';\nexport default async () => {\n  const file = path.join('/tmp', 'conformance.txt');\n  await fs.writeFile(file, Buffer.from('你好'));\n  const text = await fs.readFile(file, 'utf8');\n  assert.equal(text, '你好');\n  await fs.unlink(file);\n  return { text, bytes: Buffer.byteLength(text) };\n}"),
+				engineContract: r
+			}
+		}), {
+			text: "你好",
+			bytes: 6
+		}, "Node virtual files");
+	}
+}, {
+	name: "preserves abort reasons and cancels Promise timers",
+	async verify(e) {
+		u(await e.invoke({
+			capability: async () => ({
+				body: null,
+				status: 403
+			}),
+			input: null,
+			invocationId: "nodejs-abort",
+			program: {
+				...l(e, "import { setTimeout } from 'node:timers/promises';\nexport default async () => {\n  const controller = new AbortController(); const reason = { message: 'stop' };\n  const combined = AbortSignal.any([controller.signal]);\n  const pending = setTimeout(60000, 'late', { signal: combined });\n  controller.abort(reason); controller.abort('ignored');\n  let thrown; try { combined.throwIfAborted(); } catch (error) { thrown = error; }\n  try { await pending; return false; } catch (error) {\n    return { sameReason: combined.reason === reason && thrown === reason, name: error.name };\n  }\n}"),
+				engineContract: r
+			}
+		}), {
+			sameReason: !0,
+			name: "AbortError"
+		}, "Node cancellation");
+	}
+}];
+function l(e, t, r = {}) {
 	return {
 		engineContract: n,
 		engineDigest: e.engineDigest,
@@ -45,10 +127,10 @@ function a(e, t, r = {}) {
 		}
 	};
 }
-function o(e, n, r) {
+function u(e, n, r) {
 	if (!t(e, n)) throw Error(`${r}: expected ${JSON.stringify(n)}, received ${JSON.stringify(e)}.`);
 }
-async function s(e, t, n) {
+async function d(e, t, n) {
 	try {
 		await e;
 	} catch (e) {
@@ -57,17 +139,135 @@ async function s(e, t, n) {
 	}
 	throw Error(`${n}: operation unexpectedly succeeded.`);
 }
-var c = [
+var f = [
+	{
+		name: "rejects Task results that JSON transport would discard or coerce",
+		async verify(e) {
+			for (let t of [
+				"{ value: () => 42 }",
+				"{ value: Symbol(\"value\") }",
+				"{ value: NaN }",
+				"{ value: Infinity }",
+				"{ value: 1n }",
+				"{ value: { nested: undefined } }",
+				"{ value: [undefined] }",
+				"{ value: Array(1) }",
+				"{ value: new Date() }",
+				"{ value: { toJSON() { return \"hidden\" } } }",
+				"{ [Symbol(\"key\")]: 1 }",
+				"(() => { const value = {}; value.self = value; return { value } })()"
+			]) await d(e.invoke({
+				capability: async () => ({
+					body: null,
+					status: 200
+				}),
+				input: null,
+				invocationId: "invalid-task-result",
+				program: l(e, `export default () => (${t})`)
+			}), /Task result must contain only JSON values/, `Invalid Task result: ${t}`);
+		}
+	},
+	{
+		name: "snapshots JSON results while preserving missing ports and shared values",
+		async verify(e) {
+			let t = await e.invoke({
+				capability: async () => ({
+					body: null,
+					status: 200
+				}),
+				input: null,
+				invocationId: "json-task-result",
+				program: l(e, "export default () => {\n            const shared = { text: 'hello', values: [1, true, null] };\n            return { missing: undefined, nullable: null, first: shared, second: shared };\n          }")
+			}), n = {
+				text: "hello",
+				values: [
+					1,
+					!0,
+					null
+				]
+			};
+			u(t, {
+				nullable: null,
+				first: n,
+				second: n
+			}, "JSON Task result");
+		}
+	},
+	{
+		name: "preserves Action error codes and fixed per-call Connection selection",
+		async verify(e) {
+			let t = [{
+				kind: "connector",
+				action: "example.echo",
+				connections: [{
+					connectionId: "work",
+					alias: "office"
+				}, { connectionId: "home" }]
+			}];
+			u(await e.invoke({
+				capabilities: t,
+				capability: async ({ payload: e }) => {
+					let n = m(t, e);
+					if (n.input.fail) throw Object.assign(/* @__PURE__ */ Error("Provider unavailable."), { code: "connector.unavailable" });
+					return {
+						body: n.connectionId ?? null,
+						status: 200
+					};
+				},
+				input: null,
+				invocationId: "action-accounts",
+				program: l(e, "export default async (_, context) => {\n          const values = await Promise.all([\n            context.actions.example.echo({}, { connectionAlias: 'office' }),\n            context.actions['example.echo']({}, { connectionId: 'home' }),\n          ])\n          try { await context.actions.example.echo({ fail: true }, { connectionId: 'work' }) }\n          catch (error) { values.push(error.code) }\n          return values\n        }")
+			}), [
+				"work",
+				"home",
+				"connector.unavailable"
+			], "Action selection and recovery");
+		}
+	},
+	{
+		name: "shares Action entries and assigns independent concurrent call identities",
+		async verify(e) {
+			let t = [];
+			u(await e.invoke({
+				capabilities: [{
+					kind: "connector",
+					action: "example.echo",
+					connections: []
+				}],
+				capability: async (e) => (t.push(e), {
+					body: e.payload,
+					status: 200
+				}),
+				input: null,
+				invocationId: "action-calls",
+				program: l(e, "export default async (_input, context) => {\n          const call = context.actions.example.echo\n          return { same: call === context.actions['example.echo'], values: await Promise.all([call({ value: 1 }), call({ value: 2 }), call({ value: 3 })]) }\n        }")
+			}), {
+				same: !0,
+				values: [
+					1,
+					2,
+					3
+				].map((e) => ({
+					action: "example.echo",
+					input: { value: e }
+				}))
+			}, "Action results"), u(new Set(t.map((e) => e.callId)).size, 3, "Independent Action identities"), u(t.map((e) => e.invocationId), [
+				"action-calls",
+				"action-calls",
+				"action-calls"
+			], "Task identity");
+		}
+	},
 	{
 		name: "loads the fixed ESM closure and platform module",
 		async verify(e) {
-			o(await e.invoke({
+			u(await e.invoke({
 				capability: async () => {
 					throw Error("Capability must not be called.");
 				},
 				input: { value: 6 },
 				invocationId: "module-closure",
-				program: a(e, "import { double } from './helper.mjs'\nimport { engineContract, identity } from 'open-flow:platform'\nexport default (input) => ({ engineContract, value: identity(double(input.value)) })", { helper: {
+				program: l(e, "import { double } from './helper.mjs'\nimport { engineContract, identity } from 'open-flow:platform'\nexport default (input) => ({ engineContract, value: identity(double(input.value)) })", { helper: {
 					imports: [],
 					source: "export const double = (value) => value * 2"
 				} })
@@ -80,14 +280,14 @@ var c = [
 	{
 		name: "rejects modules outside the fixed closure",
 		async verify(e) {
-			await s(e.invoke({
+			await d(e.invoke({
 				capability: async () => ({
 					body: null,
 					status: 200
 				}),
 				input: null,
 				invocationId: "closed-linker",
-				program: a(e, "import fs from 'node:fs'\nexport default () => fs.readFileSync('/etc/passwd', 'utf8')")
+				program: l(e, "import fs from 'node:fs'\nexport default () => fs.readFileSync('/etc/passwd', 'utf8')")
 			}), /invalid|unsupported|cannot import|not part of/i, "Closed linker");
 		}
 	},
@@ -95,7 +295,7 @@ var c = [
 		name: "copies asynchronous Capability requests and responses",
 		async verify(e) {
 			let t = [];
-			o(await e.invoke({
+			u(await e.invoke({
 				capability: async (e) => (t.push(e), {
 					body: {
 						accepted: !0,
@@ -105,7 +305,7 @@ var c = [
 				}),
 				input: { issue: 42 },
 				invocationId: "async-capability",
-				program: a(e, "export default async (input, capability) => capability.connector({ action: 'read', input })")
+				program: l(e, "export default async (input, capability) => capability.artifact.put({ action: 'read', input })")
 			}), {
 				body: {
 					accepted: !0,
@@ -115,13 +315,13 @@ var c = [
 					}
 				},
 				status: 200
-			}, "Capability result"), o(t.map(({ invocationId: e, kind: t, payload: n }) => ({
+			}, "Capability result"), u(t.map(({ invocationId: e, kind: t, payload: n }) => ({
 				invocationId: e,
 				kind: t,
 				payload: n
 			})), [{
 				invocationId: "async-capability",
-				kind: "connector",
+				kind: "artifact.put",
 				payload: {
 					action: "read",
 					input: { issue: 42 }
@@ -129,23 +329,95 @@ var c = [
 			}], "Capability request");
 		}
 	},
+	{
+		name: "returns final outputs without exposing intermediate output capability",
+		async verify(e) {
+			u(await e.invoke({
+				capability: async () => {
+					throw Error("Capability must not be called.");
+				},
+				input: null,
+				invocationId: "final-outputs",
+				program: l(e, "export default (_input, context) => ({ available: typeof context.outputs, value: 1 })")
+			}), {
+				available: "undefined",
+				value: 1
+			}, "Final Task outputs");
+		}
+	},
 	{
 		name: "cancels a pending Capability and the user invocation",
 		async verify(e) {
 			let t = new AbortController(), n = !1, r, i = new Promise((e) => {
 				r = e;
-			}), c = e.invoke({
+			}), a = e.invoke({
+				capabilities: [{
+					kind: "connector",
+					action: "example.wait",
+					connections: []
+				}],
 				capability: async ({ signal: e }) => (r(), await new Promise((t, r) => e.addEventListener("abort", () => {
 					n = !0, r(e.reason);
 				}, { once: !0 }))),
 				input: null,
 				invocationId: "canceled-capability",
-				program: a(e, "export default async (_input, capability) => capability.connector({ action: 'wait' })"),
+				program: l(e, "export default async (_input, context) => context.actions.example.wait({})"),
 				signal: t.signal
 			});
-			await i, t.abort(/* @__PURE__ */ Error("Invocation canceled.")), await s(c, /cancel|abort|disposed/i, "Canceled invocation"), o(n, !0, "Capability cancellation");
+			await i, t.abort(/* @__PURE__ */ Error("Invocation canceled.")), await d(a, /cancel|abort|disposed/i, "Canceled invocation"), u(n, !0, "Capability cancellation");
 		}
 	}
 ];
+function p(e, t) {
+	let n = (e, t) => {
+		if (!(e === null || typeof e == "string" || typeof e == "boolean" || typeof e == "number" && Number.isFinite(e))) {
+			if (typeof e != "object" || t.has(e) || !Array.isArray(e) && Object.getPrototypeOf(e) !== Object.prototype && Object.getPrototypeOf(e) !== null || Object.getOwnPropertySymbols(e).length > 0) throw Object.assign(/* @__PURE__ */ Error("Action parameters must contain only JSON values."), { code: "capability.invalid" });
+			t.add(e);
+			for (let r of Array.isArray(e) ? e : Object.values(e)) n(r, t);
+			t.delete(e);
+		}
+	}, r = Object.create(null), i = /* @__PURE__ */ new Map();
+	for (let a of e) {
+		let e = a.action.indexOf("."), o = a.action.slice(0, e), s = a.action.slice(e + 1), c = i.get(o);
+		c ?? (c = Object.create(null), i.set(o, c), r[o] = c);
+		let l = async (e = {}, r) => (n(e, /* @__PURE__ */ new Set()), r !== void 0 && n(r, /* @__PURE__ */ new Set()), (await t({
+			action: a.action,
+			input: e,
+			...r === void 0 ? {} : { options: r }
+		})).body);
+		r[a.action] = l, c[s] = l;
+	}
+	for (let e of i.values()) Object.freeze(e);
+	return Object.freeze(r);
+}
+function m(e, t) {
+	let n = Object.assign(/* @__PURE__ */ Error("The Action request is invalid."), { code: "capability.invalid" }), r = Object.assign(/* @__PURE__ */ Error("The Action or Connection is not declared for this Task."), { code: "capability.denied" });
+	if (typeof t != "object" || !t || Array.isArray(t)) throw n;
+	let i = t;
+	if (Object.keys(i).some((e) => ![
+		"action",
+		"input",
+		"options"
+	].includes(e)) || typeof i.action != "string" || i.input == null || typeof i.input != "object" || Array.isArray(i.input)) throw n;
+	let a = e.find((e) => e.action == i.action);
+	if (a == null) throw r;
+	let o = a.connectionId;
+	if (Object.hasOwn(i, "options")) {
+		if (i.options == null || typeof i.options != "object" || Array.isArray(i.options)) throw n;
+		let e = i.options, t = Object.keys(e);
+		if (t.length != 1) throw n;
+		if (typeof e.connectionId == "string" && e.connectionId.length > 0 && t[0] == "connectionId") o = e.connectionId;
+		else if (typeof e.connectionAlias == "string" && e.connectionAlias.length > 0 && t[0] == "connectionAlias") {
+			if (o = a.connections.find((t) => t.alias == e.connectionAlias)?.connectionId, o == null) throw r;
+		} else throw n;
+	}
+	if (o != null && !a.connections.some((e) => e.connectionId == o)) throw r;
+	if (o == null && a.connections.length > 0) throw Object.assign(/* @__PURE__ */ Error("Choose a Connector Connection for this Action."), { code: "connector.connection-required" });
+	return {
+		action: i.action,
+		input: i.input,
+		...o == null ? {} : { connectionId: o }
+	};
+}
 //#endregion
-export { n as currentEngineContract, i as findEngineContract, c as runtimeConformanceCases };
+export { p as createActions, n as currentEngineContract, o as findEngineContract, r as nodejsEngineContract, c as nodejsRuntimeConformanceCases, m as resolveAction, f as runtimeConformanceCases, s as snapshotRuntimeResult };

package/dist/common/scheduler.d.ts

@@ -1,5 +1,6 @@
-import type { ConnectorCapability, JsonValue } from '../browser/flow-change.js';
+import type { ConnectorCapability, JsonValue, WaitAction } from '../browser/flow-change.js';
 import type { PreparedFlow } from './flow-semantics.js';
+import type { AgentCheckpoint } from './runtime-contract.js';
 import * as Effect from 'effect/Effect';
 export type SchedulerEvent = {
     readonly flowId: string;
@@ -17,29 +18,30 @@ export type SchedulerEvent = {
     readonly inputs: Readonly<Record<string, JsonValue>>;
     readonly jobId: string;
     readonly nodeId: string;
-    readonly nodeKind: 'condition' | 'connector' | 'javascript' | 'llm' | 'subflow' | 'value';
+    readonly nodeKind: 'agent' | 'approval' | 'condition' | 'connector' | 'javascript' | 'llm' | 'subflow' | 'value' | 'wait';
     readonly nodeTitle?: string;
     readonly runId: string;
     readonly type: 'node.started';
 } | {
-    readonly handle: string;
     readonly jobId: string;
     readonly nodeId: string;
+    readonly outputs: Readonly<Record<string, JsonValue>>;
     readonly runId: string;
-    readonly type: 'node.output';
-    readonly value: JsonValue;
+    readonly type: 'node.completed';
 } | {
+    readonly code: string;
     readonly jobId: string;
+    readonly message: string;
     readonly nodeId: string;
     readonly runId: string;
-    readonly type: 'node.completed';
+    readonly type: 'node.failed';
 } | {
-    readonly code: string;
     readonly jobId: string;
+    readonly level: 'debug' | 'error' | 'info' | 'warn';
     readonly message: string;
     readonly nodeId: string;
     readonly runId: string;
-    readonly type: 'node.failed';
+    readonly type: 'node.log';
 } | {
     readonly result: FlowRunResult | SubflowRunResult;
     readonly runId: string;
@@ -52,19 +54,82 @@ export type SchedulerEvent = {
 export interface FlowRunResult {
     readonly kind: 'node-results';
     readonly nodes: readonly {
-        readonly jobs: readonly {
-            readonly jobId: string;
-            readonly outputs: Readonly<Record<string, JsonValue>>;
-        }[];
         readonly nodeId: string;
+        readonly status: 'completed';
+        readonly jobId: string;
+        readonly outputs: Readonly<Record<string, JsonValue>>;
     }[];
 }
+export interface PendingWait {
+    readonly jobId: string;
+    readonly nodeId: string;
+    readonly value: JsonValue;
+    readonly waitId: string;
+    readonly pending?: JsonValue;
+}
+export interface WaitRequest {
+    readonly jobId: string;
+    readonly nodeId: string;
+    readonly value: JsonValue;
+    readonly waitId: string;
+    readonly actions: readonly ['continue'] | readonly ['approve', 'reject'];
+    readonly prompt: string;
+    readonly notify: boolean;
+    readonly notification?: {
+        readonly input: Readonly<Record<string, JsonValue>>;
+        readonly messageHandle: string;
+        readonly taskId: string;
+    };
+}
+export type WaitOperation = {
+    readonly kind: 'create';
+    readonly wait: WaitRequest;
+} | {
+    readonly kind: 'resolutions';
+    readonly waitIds: readonly string[];
+    readonly block: boolean;
+};
+export interface WaitHost {
+    readonly create: (wait: WaitRequest) => Effect.Effect<JsonValue | undefined, Error>;
+    readonly resolutions: (waitIds: readonly string[], block: boolean) => Effect.Effect<Readonly<Record<string, WaitAction>>, Error>;
+}
+export declare const waitRetentionMs = 120000;
+export interface FlowRunCheckpoint {
+    readonly bindingValues: Readonly<Record<string, string>>;
+    readonly inputs: Readonly<Record<string, Readonly<Record<string, JsonValue>>>>;
+    readonly results: Readonly<Record<string, {
+        readonly jobId: string;
+        readonly outputs: Readonly<Record<string, JsonValue>>;
+    }>>;
+    readonly counts: Readonly<Record<string, Readonly<Record<string, number>>>>;
+    readonly frames: Readonly<Record<string, Readonly<Record<string, Readonly<Record<string, JsonValue>>>>>>;
+    readonly version: 5;
+    readonly waits: readonly PendingWait[];
+    readonly agents: Readonly<Record<string, {
+        readonly invocationId: string;
+        readonly input: Readonly<Record<string, JsonValue>>;
+        readonly remainingMs?: number;
+        readonly checkpoint: AgentCheckpoint;
+    }>>;
+}
+export type FlowRunOutcome = FlowRunResult | {
+    readonly checkpoint: FlowRunCheckpoint;
+    readonly kind: 'waiting';
+    readonly remainingMs?: number;
+};
 export interface SubflowRunResult {
     readonly kind: 'function-outputs';
     readonly outputs: Readonly<Record<string, JsonValue>>;
     readonly target: 'subflow';
 }
 interface TaskInvocationBase {
+    readonly agent?: {
+        readonly action: 'approve' | 'reject';
+        readonly checkpoint: AgentCheckpoint;
+    };
+    readonly additionalInputs: Readonly<Record<string, JsonValue>>;
+    readonly blockId: string;
+    readonly flowId: string;
     readonly input: Readonly<Record<string, JsonValue>>;
     readonly invocationId: string;
     readonly jobId: string;
@@ -79,22 +144,35 @@ export type TaskInvocation = TaskInvocationBase & ({
 });
 export interface TriggerSeed {
     readonly nodeId: string;
-    readonly payload: JsonValue;
+    readonly outputs: Readonly<Record<string, JsonValue>>;
 }
 export interface SchedulerFailure {
     readonly code: string;
     readonly message: string;
 }
-export interface FlowRunOptions {
-    readonly bindingValues?: Readonly<Record<string, string>>;
+export type FlowRunOptions = {
     readonly createId: () => string;
     readonly emit?: (event: SchedulerEvent) => Effect.Effect<void, Error>;
     readonly flowId: string;
-    readonly inputs?: Readonly<Record<string, Readonly<Record<string, JsonValue>>>>;
     readonly invokeTask: (invocation: TaskInvocation) => Effect.Effect<unknown, Error>;
     readonly projectFailure?: (error: unknown) => SchedulerFailure;
     readonly runId: string;
-    readonly trigger?: TriggerSeed;
-}
-export declare function runFlow(prepared: PreparedFlow, options: FlowRunOptions): Effect.Effect<FlowRunResult, Error>;
+    readonly waits?: WaitHost;
+    readonly remainingMs?: number;
+} & RunLaunch;
+export type RunLaunch = {
+    readonly bindingValues?: Readonly<Record<string, string>>;
+    readonly inputs?: Readonly<Record<string, Readonly<Record<string, JsonValue>>>>;
+    readonly trigger: TriggerSeed;
+    readonly resume?: never;
+} | {
+    readonly resume: {
+        readonly checkpoint: unknown;
+    };
+    readonly bindingValues?: never;
+    readonly inputs?: never;
+    readonly trigger?: never;
+};
+export declare function decodeFlowRunCheckpoint(input: unknown): FlowRunCheckpoint;
+export declare function runFlow(prepared: PreparedFlow, options: FlowRunOptions): Effect.Effect<FlowRunOutcome, Error>;
 export {};