@oomol-lab/open-flow 0.1.0-beta.76 → 0.1.0-beta.77

package/dist/common/mcp.d.ts

@@ -3,6 +3,99 @@ import { z } from 'zod';
 export declare const mcpProtocolVersion = "2026-07-28";
 export declare const mcpInstructions: string;
 export declare const mcpTools: {
+    flow_state: {
+        description: string;
+        annotations: {
+            readOnlyHint: boolean;
+            destructiveHint: boolean;
+            idempotentHint: boolean;
+            openWorldHint: boolean;
+        };
+        inputSchema: {
+            '~standard': {
+                version: 1;
+                vendor: string;
+                jsonSchema: {
+                    input: () => Record<string, unknown>;
+                    output: () => Record<string, unknown>;
+                };
+                validate(value: unknown): {
+                    value: {
+                        scope: "draft" | "live";
+                        values?: boolean | undefined;
+                        flowId: string;
+                    };
+                } | {
+                    issues: {
+                        message: string;
+                        path: string[];
+                    }[];
+                };
+            };
+        };
+    };
+    flow_state_clear: {
+        description: string;
+        annotations: {
+            readOnlyHint: boolean;
+            destructiveHint: boolean;
+            idempotentHint: boolean;
+            openWorldHint: boolean;
+        };
+        inputSchema: {
+            '~standard': {
+                version: 1;
+                vendor: string;
+                jsonSchema: {
+                    input: () => Record<string, unknown>;
+                    output: () => Record<string, unknown>;
+                };
+                validate(value: unknown): {
+                    value: {
+                        scope: "draft" | "live";
+                        key?: string | undefined;
+                        flowId: string;
+                    };
+                } | {
+                    issues: {
+                        message: string;
+                        path: string[];
+                    }[];
+                };
+            };
+        };
+    };
+    flow_dedupe_clear: {
+        description: string;
+        annotations: {
+            readOnlyHint: boolean;
+            destructiveHint: boolean;
+            idempotentHint: boolean;
+            openWorldHint: boolean;
+        };
+        inputSchema: {
+            '~standard': {
+                version: 1;
+                vendor: string;
+                jsonSchema: {
+                    input: () => Record<string, unknown>;
+                    output: () => Record<string, unknown>;
+                };
+                validate(value: unknown): {
+                    value: {
+                        scope: "draft" | "live";
+                        space: string;
+                        flowId: string;
+                    };
+                } | {
+                    issues: {
+                        message: string;
+                        path: string[];
+                    }[];
+                };
+            };
+        };
+    };
     flow_canvas: {
         description: string;
         annotations: {
@@ -161,7 +254,7 @@ export declare const mcpTools: {
                     value: {
                         revision?: string | undefined;
                         query: string;
-                        type?: "agent" | "approval" | "code" | "condition" | "connector" | "cron" | "decision" | "error" | "http-request" | "integration" | "llm" | "openapi" | "outputs" | "poll" | "start" | "value" | "wait" | "webhook" | "webhook-response" | "workflow" | undefined;
+                        type?: "agent" | "approval" | "code" | "condition" | "connector" | "cron" | "decision" | "dedupe" | "error" | "http-request" | "integration" | "llm" | "openapi" | "outputs" | "poll" | "start" | "value" | "wait" | "webhook" | "webhook-response" | "workflow" | undefined;
                         offset: number;
                         limit: number;
                         flowId: string;
@@ -193,7 +286,7 @@ export declare const mcpTools: {
                 };
                 validate(value: unknown): {
                     value: {
-                        type?: "agent" | "approval" | "code" | "condition" | "connector" | "cron" | "decision" | "error" | "http-request" | "integration" | "llm" | "openapi" | "outputs" | "poll" | "start" | "value" | "wait" | "webhook" | "webhook-response" | "workflow" | undefined;
+                        type?: "agent" | "approval" | "code" | "condition" | "connector" | "cron" | "decision" | "dedupe" | "error" | "http-request" | "integration" | "llm" | "openapi" | "outputs" | "poll" | "start" | "value" | "wait" | "webhook" | "webhook-response" | "workflow" | undefined;
                         action?: string | undefined;
                         flowId?: string | undefined;
                     };
@@ -321,7 +414,7 @@ export declare const mcpTools: {
                         edits: ({
                             op: "node.add";
                             as: string;
-                            type: "agent" | "approval" | "code" | "condition" | "connector" | "cron" | "decision" | "error" | "http-request" | "integration" | "llm" | "openapi" | "outputs" | "poll" | "start" | "value" | "wait" | "webhook" | "webhook-response" | "workflow";
+                            type: "agent" | "approval" | "code" | "condition" | "connector" | "cron" | "decision" | "dedupe" | "error" | "http-request" | "integration" | "llm" | "openapi" | "outputs" | "poll" | "start" | "value" | "wait" | "webhook" | "webhook-response" | "workflow";
                             name: string;
                             onError?: "error" | "stop" | undefined;
                             retry?: {

package/dist/common/mcp.js

@@ -8846,6 +8846,54 @@ var httpRequestConfigSchema = strictObject({
 	statusPolicy: _enum(["success", "all"]).default("success")
 });
 var httpRequestExecutorSchema = httpRequestConfigSchema.extend({ kind: literal("http-request") });
+//#endregion
+//#region src/state/common/state.ts
+var stateQuerySchema = strictObject({
+	scope: _enum(["draft", "live"]),
+	values: boolean().optional()
+});
+var stateClearSchema = strictObject({
+	scope: _enum(["draft", "live"]),
+	key: string$1().min(1).refine((key) => new TextEncoder().encode(key).length <= 256).optional()
+});
+var dedupeClearSchema = strictObject({
+	scope: _enum(["draft", "live"]),
+	space: string$1().regex(/^(flow|node:.+)$/)
+});
+var dedupeConfigSchema = strictObject({
+	field: string$1().default(""),
+	mode: _enum(["new", "increasing"]).default("new"),
+	space: _enum(["node", "flow"]).default("node")
+});
+var dedupeExecutorSchema = dedupeConfigSchema.extend({ kind: literal("dedupe") });
+var flowStateViewSchema = object({
+	version: literal(1),
+	scope: _enum(["draft", "live"]),
+	limits: object({
+		maxValueBytes: number().positive(),
+		maxValues: number().int().positive(),
+		maxSpaces: number().int().positive(),
+		maxIdentities: number().positive(),
+		maxRunWrites: number().positive()
+	}),
+	values: array(object({
+		key: string$1(),
+		size: number().nonnegative(),
+		updatedAt: number(),
+		value: json$4().optional()
+	})),
+	spaces: array(object({
+		space: string$1(),
+		mode: _enum(["new", "increasing"]),
+		count: number().nonnegative(),
+		watermark: union([
+			string$1(),
+			number(),
+			_null()
+		]),
+		updatedAt: number()
+	}))
+});
 function checkJsonDepth(value, depth = 0) {
 	if (depth > 64) throw new TypeError("Value exceeds the maximum JSON depth.");
 	if (value != null && typeof value == "object") for (const child of Object.values(value)) checkJsonDepth(child, depth + 1);
@@ -9134,7 +9182,8 @@ var managedFields = object({
 			flowId: text,
 			revisionId: text
 		}),
-		httpRequestExecutorSchema
+		httpRequestExecutorSchema,
+		dedupeExecutorSchema
 	])
 });
 var managed = managedFields.transform(limitDecisionTask);
@@ -9404,7 +9453,8 @@ var revision = object({
 		literal(9),
 		literal(10),
 		literal(11),
-		literal(12)
+		literal(12),
+		literal(13)
 	]),
 	document,
 	modules: record$2(text, module)
@@ -9605,6 +9655,7 @@ array(union([...new Map(Object.entries(shapes).map(([kind, shape]) => [kind, sha
 	...shape
 })])).values()])).min(1);
 function checkModelVersion(content) {
+	if (content.modelVersion < 13 && Object.values(content.document.graph.nodes).some((candidateNode) => candidateNode.kind === "task" && "executor" in candidateNode.task && candidateNode.task.executor.kind === "dedupe")) throw new Error("Deduplication requires Flow model v13.");
 	if (content.modelVersion < 12 && Object.values(content.document.graph.nodes).some((candidateNode) => candidateNode.kind == "task" && "moduleId" in candidateNode.task && candidateNode.task.capabilities?.some((item) => item.kind == "http"))) throw new TypeError("Code HTTP access requires Flow model version 12.");
 	if (content.modelVersion < 11 && Object.values(content.document.graph.nodes).some((candidateNode) => candidateNode.kind == "task" && "executor" in candidateNode.task && candidateNode.task.executor.kind == "http-request")) throw new TypeError("HTTP Request requires Flow model version 11.");
 	if (content.modelVersion < 11 && Object.values(content.document.graph.nodes).some((candidateNode) => candidateNode.kind == "task" && ("moduleId" in candidateNode.task ? candidateNode.task.capabilities?.some((item) => item.kind == "workflow") : candidateNode.task.executor.kind == "agent" && candidateNode.task.executor.tools.some((item) => item.kind == "workflow")))) throw new TypeError("Workflow tools require Flow model version 11.");
@@ -9636,8 +9687,8 @@ function resourceNameIssue(value) {
 }
 //#endregion
 //#region src/runtime/common/engineContract.ts
-/** v9 is a single contract: the Node compatibility builtins, `context.fetch`, and no `context.egress`. */
-var currentEngineContract = "open-flow-engine/v9";
+/** v10 adds persistent Flow State to the published v9 Node compatibility and fetch contract. */
+var currentEngineContract = "open-flow-engine/v10";
 /** The published v8 Node compatibility contract, retained for existing Publications and Runs. */
 var nodejsEngineContract = "open-flow-engine/v8/nodejs-compat-v1";
 var platformSource = (contract) => `export const engineContract = ${JSON.stringify(contract)}
@@ -9682,13 +9733,19 @@ var nodejsContract = {
 	].flatMap((name) => [name, `node:${name}`])),
 	platformSource: platformSource(nodejsEngineContract)
 };
-var currentContract = {
+var v9Contract = {
 	...nodejsContract,
 	codeFetch: true,
+	platformSource: platformSource("open-flow-engine/v9")
+};
+var currentContract = {
+	...v9Contract,
+	flowState: true,
 	platformSource: platformSource(currentEngineContract)
 };
 function findEngineContract(contract) {
-	if (contract == "open-flow-engine/v9") return currentContract;
+	if (contract == "open-flow-engine/v10") return currentContract;
+	if (contract == "open-flow-engine/v9") return v9Contract;
 	if (contract == "open-flow-engine/v8") return v8Contract;
 	if (contract == "open-flow-engine/v8/nodejs-compat-v1") return nodejsContract;
 	if (contract == "open-flow-engine/v7" || contract == "open-flow-engine/v7/nodejs-compat-v1") return {
@@ -9755,6 +9812,7 @@ var type = _enum([
 	"decision",
 	"openapi",
 	"http-request",
+	"dedupe",
 	"condition",
 	"value",
 	"wait",
@@ -9885,6 +9943,7 @@ var authoringConfigurations = {
 	"connector": authoringDefinitionSchemas.connector.omit({ outputMode: true }).strict(),
 	"openapi": authoringOpenApiSchema,
 	"http-request": httpRequestConfigSchema,
+	"dedupe": dedupeConfigSchema,
 	"agent": authoringDefinitionSchemas.agent.omit({
 		prompt: true,
 		tools: true
@@ -10160,11 +10219,14 @@ var controlErrorCode = {
 	triggerKeyInvalid: "trigger-key.invalid",
 	triggerKeyNotFound: "trigger-key.not-found",
 	triggerNotFound: "trigger.not-found",
+	tagInvalid: "tag.invalid",
+	tagConflict: "tag.conflict",
+	tagNotFound: "tag.not-found",
 	variableInvalid: "variable.invalid",
 	variableLimitReached: "variable.limit-reached",
 	variableNotFound: "variable.not-found"
 };
-controlErrorCode.eventSourceInvalid, controlErrorCode.eventSourceIdentityUnavailable, controlErrorCode.eventSourceNotFound, controlErrorCode.eventSourceConflict, controlErrorCode.authenticationRequired, controlErrorCode.authorizationDenied, controlErrorCode.bindingUnresolved, controlErrorCode.connectorActionNotFound, controlErrorCode.connectorAccessConflict, controlErrorCode.connectorAccessInvalid, controlErrorCode.connectorAccessRequired, controlErrorCode.connectorAccessUnsupported, controlErrorCode.connectorUnconfigured, controlErrorCode.connectorUnavailable, controlErrorCode.connectorConsoleUnconfigured, controlErrorCode.engineUnavailable, controlErrorCode.engineUnsupported, controlErrorCode.flowInvalid, controlErrorCode.flowRepairRequired, controlErrorCode.flowUpgradeRequired, controlErrorCode.flowNotFound, controlErrorCode.flowBusy, controlErrorCode.flowConflict, controlErrorCode.flowPresentationConflict, controlErrorCode.flowRevisionConflict, controlErrorCode.liveConflict, controlErrorCode.liveNotFound, controlErrorCode.pageInvalidCursor, controlErrorCode.publicationConflict, controlErrorCode.publicationNotFound, controlErrorCode.publicationUnsupported, controlErrorCode.publishOperationNotFound, controlErrorCode.routeNotFound, controlErrorCode.runConflict, controlErrorCode.runEventsExpired, controlErrorCode.runInvalid, controlErrorCode.runNotFound, controlErrorCode.runNotTerminal, controlErrorCode.runOverloaded, controlErrorCode.runWaitNotFound, controlErrorCode.triggerKeyInvalid, controlErrorCode.triggerKeyNotFound, controlErrorCode.triggerNotFound, controlErrorCode.variableInvalid, controlErrorCode.variableLimitReached, controlErrorCode.variableNotFound;
+controlErrorCode.eventSourceInvalid, controlErrorCode.eventSourceIdentityUnavailable, controlErrorCode.eventSourceNotFound, controlErrorCode.eventSourceConflict, controlErrorCode.authenticationRequired, controlErrorCode.authorizationDenied, controlErrorCode.bindingUnresolved, controlErrorCode.connectorActionNotFound, controlErrorCode.connectorAccessConflict, controlErrorCode.connectorAccessInvalid, controlErrorCode.connectorAccessRequired, controlErrorCode.connectorAccessUnsupported, controlErrorCode.connectorUnconfigured, controlErrorCode.connectorUnavailable, controlErrorCode.connectorConsoleUnconfigured, controlErrorCode.engineUnavailable, controlErrorCode.engineUnsupported, controlErrorCode.flowInvalid, controlErrorCode.flowRepairRequired, controlErrorCode.flowUpgradeRequired, controlErrorCode.flowNotFound, controlErrorCode.flowBusy, controlErrorCode.flowConflict, controlErrorCode.flowPresentationConflict, controlErrorCode.flowRevisionConflict, controlErrorCode.liveConflict, controlErrorCode.liveNotFound, controlErrorCode.pageInvalidCursor, controlErrorCode.publicationConflict, controlErrorCode.publicationNotFound, controlErrorCode.publicationUnsupported, controlErrorCode.publishOperationNotFound, controlErrorCode.routeNotFound, controlErrorCode.runConflict, controlErrorCode.runEventsExpired, controlErrorCode.runInvalid, controlErrorCode.runNotFound, controlErrorCode.runNotTerminal, controlErrorCode.runOverloaded, controlErrorCode.runWaitNotFound, controlErrorCode.triggerKeyInvalid, controlErrorCode.triggerKeyNotFound, controlErrorCode.triggerNotFound, controlErrorCode.tagInvalid, controlErrorCode.tagConflict, controlErrorCode.tagNotFound, controlErrorCode.variableInvalid, controlErrorCode.variableLimitReached, controlErrorCode.variableNotFound;
 var ApiError = class extends Error {
 	constructor(status, code, message, details) {
 		super(message);
@@ -11430,6 +11492,7 @@ function flow$1(value) {
 			publicationId: string(target.publicationId),
 			revisionId: string(target.revisionId)
 		} },
+		tagIds: source.tagIds === void 0 ? [] : strings(source.tagIds),
 		createdAt: string(source.createdAt),
 		...source.connectorTeamId == null ? {} : { connectorTeamId: string(source.connectorTeamId) },
 		draftRevisionId: string(source.draftRevisionId),
@@ -11864,6 +11927,33 @@ function randomId() {
 	return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
 }
 //#endregion
+//#region src/control/common/tags.ts
+function normalizeFlowQuery(query = {}) {
+	return {
+		query: query.query?.trim().toLowerCase() ?? "",
+		tagIds: [...new Set(query.tagIds ?? [])].toSorted(),
+		untagged: query.untagged ?? false
+	};
+}
+function decodeTag(value) {
+	const source = record(value);
+	if (source.version != 1) return invalidResponse();
+	return {
+		tagId: string(source.tagId),
+		name: string(source.name),
+		version: 1
+	};
+}
+function decodeTagListItem(value) {
+	const source = record(value);
+	const referenceCount = integer(source.referenceCount);
+	if (referenceCount < 0) return invalidResponse();
+	return {
+		...decodeTag(source),
+		referenceCount
+	};
+}
+//#endregion
 //#region src/control/common/api.ts
 function decodeRunEvent(value) {
 	const source = record(value);
@@ -11967,7 +12057,7 @@ function decodeRunEvent(value) {
 			switch (kind) {
 				case "node.started": {
 					const nodeKind = payload.nodeKind;
-					if (nodeKind !== void 0 && nodeKind !== "approval" && nodeKind !== "condition" && nodeKind !== "connector" && nodeKind !== "javascript" && nodeKind !== "decision" && nodeKind !== "openapi" && nodeKind !== "http-request" && nodeKind !== "llm" && nodeKind !== "agent" && nodeKind !== "value" && nodeKind !== "outputs" && nodeKind !== "webhook-response" && nodeKind !== "workflow" && nodeKind !== "wait") return invalidResponse();
+					if (nodeKind !== void 0 && nodeKind !== "approval" && nodeKind !== "condition" && nodeKind !== "connector" && nodeKind !== "javascript" && nodeKind !== "decision" && nodeKind !== "openapi" && nodeKind !== "http-request" && nodeKind !== "dedupe" && nodeKind !== "llm" && nodeKind !== "agent" && nodeKind !== "value" && nodeKind !== "outputs" && nodeKind !== "webhook-response" && nodeKind !== "workflow" && nodeKind !== "wait") return invalidResponse();
 					return {
 						...base,
 						kind,
@@ -12094,6 +12184,10 @@ var ControlClient = class {
 	}
 	async listFlows(options = {}) {
 		const parameters = new URLSearchParams();
+		const filter = normalizeFlowQuery(options);
+		if (filter.query) parameters.set("query", filter.query);
+		if (filter.tagIds.length) parameters.set("tagIds", filter.tagIds.join(","));
+		if (filter.untagged) parameters.set("untagged", "true");
 		if (options.cursor != null) parameters.set("cursor", options.cursor);
 		if (options.limit != null) parameters.set("limit", String(options.limit));
 		if (options.includeTotal != null) parameters.set("includeTotal", String(options.includeTotal));
@@ -12183,15 +12277,17 @@ var ControlClient = class {
 				file,
 				name: options.name,
 				teamId: options.teamId,
+				tagIds: options.tagIds,
 				version: 1
 			})
 		}));
 	}
-	async createFlow(name, idempotencyKey = `flow-${randomId()}`, teamId) {
+	async createFlow(name, idempotencyKey = `flow-${randomId()}`, teamId, tagIds) {
 		return flow$1(await this.request("/v1/flows", {
 			body: JSON.stringify({
 				name,
 				...teamId == null ? {} : { teamId },
+				...tagIds == null ? {} : { tagIds },
 				version: 1
 			}),
 			headers: { "idempotency-key": idempotencyKey },
@@ -12226,15 +12322,68 @@ var ControlClient = class {
 		if (source.version != 1 || !Array.isArray(source.listeners)) return invalidResponse();
 		return source.listeners.map(errorListener);
 	}
-	async renameFlow(flowId, name) {
-		return flow$1(await this.request(`/v1/flows/${segment(flowId)}`, {
+	async listTags(signal) {
+		const source = record(await this.request("/v1/tags", { signal }));
+		if (source.version != 1 || !Array.isArray(source.tags)) return invalidResponse();
+		return {
+			tags: source.tags.map(decodeTagListItem),
+			version: 1
+		};
+	}
+	async createTag(name) {
+		return decodeTag(await this.request("/v1/tags", {
+			method: "POST",
 			body: JSON.stringify({
 				name,
 				version: 1
-			}),
-			method: "PATCH"
+			})
+		}));
+	}
+	async renameTag(tagId, name) {
+		return decodeTag(await this.request(`/v1/tags/${segment(tagId)}`, {
+			method: "PATCH",
+			body: JSON.stringify({
+				name,
+				version: 1
+			})
 		}));
 	}
+	async deleteTag(tagId) {
+		if (record(await this.request(`/v1/tags/${segment(tagId)}`, { method: "DELETE" })).version != 1) invalidResponse();
+	}
+	async setFlowTags(flowId, tagIds) {
+		return flow$1(await this.request(`/v1/flows/${segment(flowId)}/tags`, {
+			method: "PUT",
+			body: JSON.stringify({
+				tagIds,
+				version: 1
+			})
+		}));
+	}
+	async updateFlow(flowId, changes) {
+		return flow$1(await this.request(`/v1/flows/${segment(flowId)}`, {
+			method: "PATCH",
+			body: JSON.stringify({
+				...changes,
+				version: 1
+			})
+		}));
+	}
+	async getFlowState(flowId, scope, values = false) {
+		const result = flowStateViewSchema.safeParse(await this.request(`/v1/flows/${segment(flowId)}/state?scope=${scope}&values=${values}`));
+		return result.success && result.data.scope === scope ? result.data : invalidResponse();
+	}
+	async clearFlowState(flowId, scope, key) {
+		const source = record(await this.request(`/v1/flows/${segment(flowId)}/state?scope=${scope}${key == null ? "" : `&key=${encodeURIComponent(key)}`}`, { method: "DELETE" }));
+		if (source.version !== 1 || source.cleared !== true) invalidResponse();
+	}
+	async clearFlowDedupe(flowId, scope, space) {
+		const source = record(await this.request(`/v1/flows/${segment(flowId)}/dedupe?scope=${scope}&space=${encodeURIComponent(space)}`, { method: "DELETE" }));
+		if (source.version !== 1 || source.cleared !== true) invalidResponse();
+	}
+	async renameFlow(flowId, name) {
+		return this.updateFlow(flowId, { name });
+	}
 	async deleteFlow(flowId) {
 		return flow$1(await this.request(`/v1/flows/${segment(flowId)}`, { method: "DELETE" }));
 	}
@@ -12986,6 +13135,9 @@ function tool(description, schema, readOnly, idempotent = true) {
 	};
 }
 var mcpTools = {
+	flow_state: tool("Inspect Flow state usage, business keys and deduplication spaces. Values are omitted unless requested. Scope is required.", stateQuerySchema.extend({ flowId: flow }), true),
+	flow_state_clear: tool("Delete one business state key or clear all business values. Explicit draft/live scope is required; live changes production state immediately.", stateClearSchema.extend({ flowId: flow }), false),
+	flow_dedupe_clear: tool("Clear one deduplication space (flow or node:<id>). Explicit draft/live scope is required; live changes production history immediately.", dedupeClearSchema.extend({ flowId: flow }), false),
 	flow_canvas: tool("Broadcast a transient canvas command to connected Workbenches viewing this Flow. Success only confirms Server broadcast, not delivery or execution. No replay, session selection or Presentation save. Pan uses screen pixels (positive right/down); zoom is an absolute ratio (0.1–3); fit includes all nodes. Repeating pan moves again.", strictObject({
 		flowId: flow,
 		command: canvasCommandSchema

package/dist/common/run-events.js

@@ -54,6 +54,7 @@ var nodeKinds = /* @__PURE__ */ new Set([
 	"javascript",
 	"openapi",
 	"http-request",
+	"dedupe",
 	"llm",
 	"value",
 	"wait",

package/dist/common/runtime-contract.d.ts

@@ -1,5 +1,19 @@
 import type { CodeModule, ConnectorCapability, TaskCapability, JsonValue } from './flow-model.js';
 export { currentEngineContract, nodejsEngineContract, findEngineContract, type EngineContract } from './engine-contract.js';
+/** Serialized into the guest; keep validation and helpers self-contained. */
+export declare function createState(invoke: (kind: string, payload: JsonValue) => Promise<RuntimeCapabilityResponse>): {
+    state: Readonly<{
+        get(key: unknown): Promise<JsonValue>;
+        set(key: unknown, value: unknown): Promise<void>;
+        insert(key: unknown, value: unknown): Promise<boolean>;
+        delete(key: unknown): Promise<void>;
+        list(): Promise<string[]>;
+    }>;
+    dedupe: Readonly<{
+        insert(ids: unknown): Promise<boolean[]>;
+        has(ids: unknown): Promise<boolean[]>;
+    }>;
+};
 export type RuntimeModule = Pick<CodeModule, 'imports' | 'source'>;
 /** Snapshot a Task result before JSON transport can discard or coerce invalid values. */
 export declare function snapshotRuntimeResult(value: unknown): JsonValue | undefined;

package/dist/common/runtime-contract.js

@@ -23,8 +23,8 @@ function dequal(foo, bar) {
 }
 //#endregion
 //#region src/runtime/common/engineContract.ts
-/** v9 is a single contract: the Node compatibility builtins, `context.fetch`, and no `context.egress`. */
-var currentEngineContract = "open-flow-engine/v9";
+/** v10 adds persistent Flow State to the published v9 Node compatibility and fetch contract. */
+var currentEngineContract = "open-flow-engine/v10";
 /** The published v8 Node compatibility contract, retained for existing Publications and Runs. */
 var nodejsEngineContract = "open-flow-engine/v8/nodejs-compat-v1";
 var platformSource = (contract) => `export const engineContract = ${JSON.stringify(contract)}
@@ -69,13 +69,19 @@ var nodejsContract = {
 	].flatMap((name) => [name, `node:${name}`])),
 	platformSource: platformSource(nodejsEngineContract)
 };
-var currentContract = {
+var v9Contract = {
 	...nodejsContract,
 	codeFetch: true,
+	platformSource: platformSource("open-flow-engine/v9")
+};
+var currentContract = {
+	...v9Contract,
+	flowState: true,
 	platformSource: platformSource(currentEngineContract)
 };
 function findEngineContract(contract) {
-	if (contract == "open-flow-engine/v9") return currentContract;
+	if (contract == "open-flow-engine/v10") return currentContract;
+	if (contract == "open-flow-engine/v9") return v9Contract;
 	if (contract == "open-flow-engine/v8") return v8Contract;
 	if (contract == "open-flow-engine/v8/nodejs-compat-v1") return nodejsContract;
 	if (contract == "open-flow-engine/v7" || contract == "open-flow-engine/v7/nodejs-compat-v1") return {
@@ -95,6 +101,60 @@ function findEngineContract(contract) {
 }
 //#endregion
 //#region src/runtime/common/runtime.ts
+/** Serialized into the guest; keep validation and helpers self-contained. */
+function createState(invoke) {
+	const invalid = (message) => Object.assign(new TypeError(message), { code: "capability.invalid" });
+	const keyOf = (key) => {
+		if (typeof key !== "string" || key.length === 0 || new TextEncoder().encode(key).length > 256) throw invalid("State keys require 1 to 256 UTF-8 bytes.");
+		return key;
+	};
+	const valueOf = (value) => {
+		if (value === void 0) throw invalid("State values must be JSON.");
+		try {
+			return snapshotRuntimeResult({ value }).value;
+		} catch {
+			throw invalid("State values must be JSON.");
+		}
+	};
+	const idsOf = (ids) => {
+		if (!Array.isArray(ids) || !Array.from(ids).every((id) => typeof id === "string" || typeof id === "number" && Number.isFinite(id))) throw invalid("Identities must be strings or finite numbers.");
+		return ids;
+	};
+	return {
+		state: Object.freeze({
+			async get(key) {
+				return (await invoke("state.get", { key: keyOf(key) })).body.value;
+			},
+			async set(key, value) {
+				await invoke("state.set", {
+					key: keyOf(key),
+					value: valueOf(value)
+				});
+			},
+			async insert(key, value) {
+				if (value === null) throw invalid("State insert does not accept null.");
+				return (await invoke("state.insert", {
+					key: keyOf(key),
+					value: valueOf(value)
+				})).body.inserted;
+			},
+			async delete(key) {
+				await invoke("state.delete", { key: keyOf(key) });
+			},
+			async list() {
+				return (await invoke("state.list", {})).body.keys;
+			}
+		}),
+		dedupe: Object.freeze({
+			async insert(ids) {
+				return (await invoke("dedupe.insert", { ids: idsOf(ids) })).body.inserted;
+			},
+			async has(ids) {
+				return (await invoke("dedupe.has", { ids: idsOf(ids) })).body.present;
+			}
+		})
+	};
+}
 /** Snapshot a Task result before JSON transport can discard or coerce invalid values. */
 function snapshotRuntimeResult(value) {
 	const parents = /* @__PURE__ */ new Set();
@@ -394,6 +454,59 @@ async function rejects(operation, pattern, message) {
 	throw new Error(`${message}: operation unexpectedly succeeded.`);
 }
 var runtimeConformanceCases = [
+	{
+		name: "cancels detached State work when its Task finishes",
+		async verify(harness) {
+			let aborted = false;
+			equal(await harness.invoke({
+				input: null,
+				invocationId: "state-detached",
+				capability: async ({ signal }) => await new Promise((resolve) => {
+					signal.addEventListener("abort", () => {
+						aborted = true;
+						resolve({
+							status: 200,
+							body: null
+						});
+					}, { once: true });
+				}),
+				program: program(harness, `export default async (_, context) => {
+          void context.state.set('detached', 1);
+          await new Promise(resolve => setTimeout(resolve, 20));
+          return null;
+        }`)
+			}), null, "Detached State Task result");
+			equal(aborted, true, "Detached State cancellation");
+		}
+	},
+	{
+		name: "rejects non-JSON State values and invalid identities before Host dispatch",
+		async verify(harness) {
+			let calls = 0;
+			equal(await harness.invoke({
+				input: null,
+				invocationId: "state-invalid",
+				capability: async () => {
+					calls += 1;
+					return {
+						status: 200,
+						body: null
+					};
+				},
+				program: program(harness, `export default async (_, context) => {
+          const cyclic = {}; cyclic.self = cyclic;
+          const invalid = [undefined, NaN, Infinity, new Date(), { x: undefined }, cyclic, [undefined], { x: () => 1 }];
+          const errors = [];
+          for (const value of invalid) { try { await context.state.set('key', value); errors.push('accepted'); } catch (e) { errors.push(e.code); } }
+          for (const call of [() => context.state.get(''), () => context.state.get('x'.repeat(257)), () => context.state.insert('x', null), () => context.dedupe.insert([NaN]), () => context.dedupe.has([null]), () => context.dedupe.insert(new Array(1))]) {
+            try { await call(); errors.push('accepted'); } catch (e) { errors.push(e.code); }
+          }
+          return errors;
+        }`)
+			}), Array.from({ length: 14 }, () => "capability.invalid"), "State boundary validation");
+			equal(calls, 0, "State invalid dispatch");
+		}
+	},
 	{
 		name: "rejects Task results that JSON transport would discard or coerce",
 		async verify(harness) {
@@ -1098,4 +1211,4 @@ function createWorkflows(invoke) {
 	} });
 }
 //#endregion
-export { createActions, createArtifacts, createBase64, createFetch, createWorkflows, currentEngineContract, findEngineContract, nodejsEngineContract, nodejsRuntimeConformanceCases, resolveAction, runtimeConformanceCases, snapshotRuntimeResult };
+export { createActions, createArtifacts, createBase64, createFetch, createState, createWorkflows, currentEngineContract, findEngineContract, nodejsEngineContract, nodejsRuntimeConformanceCases, resolveAction, runtimeConformanceCases, snapshotRuntimeResult };

package/dist/common/scheduler-node-execution.d.ts

@@ -63,6 +63,7 @@ export declare function executeNode(context: NodeExecutionContext, input: {
     readonly node: ExecutableNode;
     readonly jobId: string;
     readonly nodeInputs: Readonly<Record<string, JsonValue>>;
+    readonly launchInputs?: Readonly<Record<string, JsonValue>>;
     readonly flowId: string;
     readonly runId: string;
     readonly graph: Graph;

package/dist/common/scheduler.d.ts

@@ -33,7 +33,7 @@ export type SchedulerEvent = {
     readonly inputs: Readonly<Record<string, JsonValue>>;
     readonly jobId: string;
     readonly nodeId: string;
-    readonly nodeKind: 'agent' | 'approval' | 'condition' | 'connector' | 'decision' | 'javascript' | 'openapi' | 'http-request' | 'llm' | 'value' | 'wait' | 'outputs' | 'workflow' | 'webhook-response';
+    readonly nodeKind: 'agent' | 'approval' | 'condition' | 'connector' | 'decision' | 'javascript' | 'openapi' | 'http-request' | 'dedupe' | 'llm' | 'value' | 'wait' | 'outputs' | 'workflow' | 'webhook-response';
     readonly nodeTitle?: string;
     readonly runId: string;
     readonly type: 'node.started';