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

package/dist/common/flow-state.js

@@ -5604,44 +5604,58 @@ function dequal(foo, bar) {
 //#region src/state/common/conformance.ts
 var stateConformanceCases = [
 	{
-		name: "persists watermarks by instant and resets changed modes atomically",
+		name: "reads selected State keys in input order with missing, falsy and independent values",
 		async verify(harness) {
-			const config = {
-				field: "",
-				mode: "increasing",
-				space: "node"
-			};
-			if (!dequal(await harness.dedupe(config, [
-				"2026-10-30T09:00:00+08:00",
-				"2026-10-30T01:00:00Z",
-				"2026-10-30T02:00:00Z"
-			]), {
-				items: ["2026-10-30T09:00:00+08:00", "2026-10-30T02:00:00Z"],
-				duplicates: ["2026-10-30T01:00:00Z"]
-			})) throw new Error("Watermarks must compare instants and preserve item order.");
-			let rejected = false;
-			try {
-				await harness.dedupe(config, [1]);
-			} catch {
-				rejected = true;
-			}
-			if (!rejected) throw new Error("Mixed watermark types must fail.");
-			if (!dequal(await harness.dedupe(config, ["2026-10-30T02:00:00Z", "2026-10-30T03:00:00Z"]), {
-				items: ["2026-10-30T03:00:00Z"],
-				duplicates: ["2026-10-30T02:00:00Z"]
-			})) throw new Error("A failed batch must preserve the previous watermark.");
-			await harness.dedupe({
-				...config,
-				mode: "new"
-			}, []);
-			if (!dequal(await harness.dedupe(config, [
-				5,
-				3,
-				5
-			]), {
-				items: [5, 3],
-				duplicates: [5]
-			})) throw new Error("A mode reset must discard previous watermarks, including on empty batches.");
+			if (!dequal(await harness.run(`export default async (_, context) => {
+        await context.state.set('object', { nested: [1] });
+        await context.state.set('zero', 0);
+        await context.state.set('false', false);
+        await context.state.set('empty', '');
+        const values = await context.state.get(['false', 'missing', 'object', 'zero', 'empty']);
+        values[2].nested.push(2);
+        return {result: {values, retained: await context.state.get('object'), zero: await context.state.get('zero')}};
+      }`), {
+				values: [
+					false,
+					null,
+					{ nested: [1, 2] },
+					0,
+					""
+				],
+				retained: { nested: [1] },
+				zero: 0
+			})) throw new Error("State batch reads must preserve order, missing keys and independent JSON values.");
+		}
+	},
+	{
+		name: "skips composite identities across successful Runs without depending on field order",
+		async verify(harness) {
+			const items = [
+				{
+					company: "a",
+					id: 1
+				},
+				{
+					company: "b",
+					id: 1
+				},
+				{
+					company: "a",
+					id: 1
+				}
+			];
+			if (!dequal(await harness.skipDuplicates({ fields: ["company", "id"] }, items), {
+				items: items.slice(0, 2),
+				duplicates: [items[2]]
+			})) throw new Error("Composite identities must retain the first item in input order.");
+			if (!dequal(await harness.skipDuplicates({ fields: ["id", "company"] }, items), {
+				items: [],
+				duplicates: items
+			})) throw new Error("Successful Run history must persist independently of field order.");
+			if (!dequal(await harness.skipDuplicates({ fields: ["id"] }, items), {
+				items: [items[0]],
+				duplicates: items.slice(1)
+			})) throw new Error("The field definition must participate in identity.");
 		}
 	},
 	{
@@ -5710,30 +5724,35 @@ var stateConformanceCases = [
 ];
 //#endregion
 //#region src/state/common/state.ts
+var stateReadLimits = {
+	maxKeys: 16,
+	maxBytes: 1048576
+};
+var keySchema = string().min(1).refine((value) => new TextEncoder().encode(value).length <= 256);
 var stateQuerySchema = strictObject({
 	scope: _enum(["draft", "live"]),
-	values: boolean().optional()
+	values: literal(false).optional()
+});
+var stateReadSchema = strictObject({
+	scope: _enum(["draft", "live"]),
+	keys: array(keySchema).min(1).max(stateReadLimits.maxKeys).refine((keys) => new Set(keys).size === keys.length, "State keys must be distinct.")
 });
 var stateClearSchema = strictObject({
 	scope: _enum(["draft", "live"]),
-	key: string().min(1).refine((key) => new TextEncoder().encode(key).length <= 256).optional()
+	key: keySchema.optional()
 });
 var dedupeClearSchema = strictObject({
 	scope: _enum(["draft", "live"]),
 	space: string().regex(/^(flow|node:.+)$/)
 });
-var dedupeConfigSchema = strictObject({
-	field: string().default(""),
-	mode: _enum(["new", "increasing"]).default("new"),
-	space: _enum(["node", "flow"]).default("node")
-});
-var dedupeExecutorSchema = dedupeConfigSchema.extend({ kind: literal("dedupe") });
-function dedupeTask(config = dedupeConfigSchema.parse({}), name = "Remove Duplicates") {
+var skipDuplicatesConfigSchema = strictObject({ fields: array(string().refine((field) => field.length > 0 && field.split(".").every((part) => part.length > 0), "Use a nonempty dot-separated field path.")).refine((fields) => new Set(fields).size === fields.length, "Identity fields must be distinct.").default([]) });
+var skipDuplicatesExecutorSchema = skipDuplicatesConfigSchema.extend({ kind: literal("skip-duplicates") });
+function skipDuplicatesTask(config = skipDuplicatesConfigSchema.parse({}), name = "Skip Duplicates") {
 	return {
 		name,
 		executor: {
 			...config,
-			kind: "dedupe"
+			kind: "skip-duplicates"
 		},
 		inputs: [{
 			handle: "items",
@@ -5753,7 +5772,7 @@ var StateError = class extends Error {
 		this.retryable = false;
 		this.name = "StateError";
 		this.code = code;
-		this.catchable = code === "dedupe.full";
+		this.catchable = code === "dedupe.full" || code === "node.input-invalid";
 	}
 };
 function stateKey(key) {
@@ -5767,58 +5786,18 @@ function dedupeIdentities(value) {
 async function hashIdentities(ids) {
 	return Promise.all(ids.map(async (id) => new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(`${typeof id}:${String(id)}`))).slice(0, 16)));
 }
-function watermarkValue(id) {
-	if (typeof id === "number") {
-		if (!Number.isFinite(id)) throw new StateError("capability.invalid", "Watermarks must be finite.");
-		return id;
-	}
-	const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,3}))?(Z|[+-]\d{2}:\d{2})$/.exec(id);
-	if (match == null) throw new StateError("capability.invalid", "Watermarks require RFC 3339 timestamps with an explicit timezone.");
-	const [, year, month, day, hour, minute, second, , zone] = match;
-	const y = Number(year);
-	const days = [
-		31,
-		y % 4 === 0 && (y % 100 !== 0 || y % 400 === 0) ? 29 : 28,
-		31,
-		30,
-		31,
-		30,
-		31,
-		31,
-		30,
-		31,
-		30,
-		31
-	][Number(month) - 1] ?? 0;
-	const result = Date.parse(id);
-	if (Number(month) < 1 || Number(month) > 12 || Number(day) < 1 || Number(day) > days || Number(hour) > 23 || Number(minute) > 59 || Number(second) > 59 || zone !== "Z" && (Number(zone.slice(1, 3)) > 23 || Number(zone.slice(4)) > 59) || !Number.isFinite(result)) throw new StateError("capability.invalid", "Watermarks require valid calendar timestamps.");
-	return result;
-}
-function increasingIdentities(ids, watermark) {
-	const type = typeof (watermark ?? ids[0]);
-	if (ids.some((id) => typeof id !== type)) throw new StateError("capability.invalid", "Watermark types must not be mixed.");
-	const initial = watermark == null ? -Infinity : watermarkValue(watermark);
-	const seen = /* @__PURE__ */ new Set();
-	let maximum = initial;
-	let next = watermark;
-	return {
-		inserted: ids.map((id) => {
-			const value = watermarkValue(id);
-			const fresh = value > initial && !seen.has(value);
-			seen.add(value);
-			if (value > maximum) {
-				maximum = value;
-				next = id;
-			}
-			return fresh;
-		}),
-		watermark: next
-	};
-}
-function itemIdentities(items, field) {
-	if (!Array.isArray(items)) throw new StateError("capability.invalid", "Deduplication requires an array of items.");
-	const path = field === "" ? [] : field.split(".");
-	return dedupeIdentities(items.map((item) => path.reduce((value, key) => value != null && typeof value === "object" && Object.hasOwn(value, key) ? value[key] : void 0, item)));
+/** Canonical identities include the field definition and preserve scalar types. */
+function skipDuplicatesIdentities(items, fields) {
+	if (!Array.isArray(items)) throw new StateError("node.input-invalid", "Skip Duplicates requires an array of items.");
+	const paths = fields.toSorted();
+	return items.map((item, index) => {
+		const values = (paths.length === 0 ? [""] : paths).map((field) => {
+			const value = field === "" ? item : field.split(".").reduce((current, key) => current != null && typeof current === "object" && Object.hasOwn(current, key) ? current[key] : void 0, item);
+			if (typeof value !== "string" && !(typeof value === "number" && Number.isFinite(value))) throw new StateError("node.input-invalid", `Item ${index + 1}, ${field === "" ? "the item itself" : `field ${JSON.stringify(field)}`} must be a string or finite number.`);
+			return value;
+		});
+		return JSON.stringify([paths, values]);
+	});
 }
 var flowStateViewSchema = object({
 	version: literal(1),
@@ -5830,23 +5809,29 @@ var flowStateViewSchema = object({
 		maxIdentities: number().positive(),
 		maxRunWrites: number().positive()
 	}),
-	values: array(object({
+	values: array(strictObject({
 		key: string(),
 		size: number().nonnegative(),
-		updatedAt: number(),
-		value: json().optional()
+		updatedAt: number()
 	})),
 	spaces: array(object({
 		space: string(),
-		mode: _enum(["new", "increasing"]),
 		count: number().nonnegative(),
-		watermark: union([
-			string(),
-			number(),
-			_null()
-		]),
+		pendingCount: number().nonnegative(),
+		reservedCount: number().nonnegative(),
 		updatedAt: number()
 	}))
 });
+var flowStateValuesSchema = object({
+	version: literal(1),
+	scope: _enum(["draft", "live"]),
+	values: array(strictObject({
+		key: keySchema,
+		value: json()
+	})).min(1).max(stateReadLimits.maxKeys)
+}).refine((response) => {
+	const encoder = new TextEncoder();
+	return response.values.reduce((bytes, item) => bytes + (item.value === null ? 0 : encoder.encode(JSON.stringify(item.value)).byteLength), 0) <= stateReadLimits.maxBytes;
+}, "State values exceed the 1 MiB read limit.");
 //#endregion
-export { StateError, dedupeClearSchema, dedupeConfigSchema, dedupeExecutorSchema, dedupeIdentities, dedupeTask, flowStateViewSchema, hashIdentities, increasingIdentities, itemIdentities, stateClearSchema, stateConformanceCases, stateKey, stateQuerySchema, watermarkValue };
+export { StateError, dedupeClearSchema, dedupeIdentities, flowStateValuesSchema, flowStateViewSchema, hashIdentities, skipDuplicatesConfigSchema, skipDuplicatesExecutorSchema, skipDuplicatesIdentities, skipDuplicatesTask, stateClearSchema, stateConformanceCases, stateKey, stateQuerySchema, stateReadLimits, stateReadSchema };

package/dist/common/mcp.d.ts

@@ -22,7 +22,38 @@ export declare const mcpTools: {
                 validate(value: unknown): {
                     value: {
                         scope: "draft" | "live";
-                        values?: boolean | undefined;
+                        values?: false | undefined;
+                        flowId: string;
+                    };
+                } | {
+                    issues: {
+                        message: string;
+                        path: string[];
+                    }[];
+                };
+            };
+        };
+    };
+    flow_state_read: {
+        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";
+                        keys: string[];
                         flowId: string;
                     };
                 } | {
@@ -254,7 +285,7 @@ export declare const mcpTools: {
                     value: {
                         revision?: string | undefined;
                         query: string;
-                        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;
+                        type?: "agent" | "approval" | "code" | "condition" | "connector" | "cron" | "decision" | "error" | "http-request" | "integration" | "llm" | "openapi" | "outputs" | "poll" | "skip-duplicates" | "start" | "value" | "wait" | "webhook" | "webhook-response" | "workflow" | undefined;
                         offset: number;
                         limit: number;
                         flowId: string;
@@ -286,7 +317,7 @@ export declare const mcpTools: {
                 };
                 validate(value: unknown): {
                     value: {
-                        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;
+                        type?: "agent" | "approval" | "code" | "condition" | "connector" | "cron" | "decision" | "error" | "http-request" | "integration" | "llm" | "openapi" | "outputs" | "poll" | "skip-duplicates" | "start" | "value" | "wait" | "webhook" | "webhook-response" | "workflow" | undefined;
                         action?: string | undefined;
                         flowId?: string | undefined;
                     };
@@ -414,7 +445,7 @@ export declare const mcpTools: {
                         edits: ({
                             op: "node.add";
                             as: string;
-                            type: "agent" | "approval" | "code" | "condition" | "connector" | "cron" | "decision" | "dedupe" | "error" | "http-request" | "integration" | "llm" | "openapi" | "outputs" | "poll" | "start" | "value" | "wait" | "webhook" | "webhook-response" | "workflow";
+                            type: "agent" | "approval" | "code" | "condition" | "connector" | "cron" | "decision" | "error" | "http-request" | "integration" | "llm" | "openapi" | "outputs" | "poll" | "skip-duplicates" | "start" | "value" | "wait" | "webhook" | "webhook-response" | "workflow";
                             name: string;
                             onError?: "error" | "stop" | undefined;
                             retry?: {

package/dist/common/mcp.js

@@ -8848,24 +8848,29 @@ var httpRequestConfigSchema = strictObject({
 var httpRequestExecutorSchema = httpRequestConfigSchema.extend({ kind: literal("http-request") });
 //#endregion
 //#region src/state/common/state.ts
+var stateReadLimits = {
+	maxKeys: 16,
+	maxBytes: 1048576
+};
+var keySchema = string$1().min(1).refine((value) => new TextEncoder().encode(value).length <= 256);
 var stateQuerySchema = strictObject({
 	scope: _enum(["draft", "live"]),
-	values: boolean().optional()
+	values: literal(false).optional()
+});
+var stateReadSchema = strictObject({
+	scope: _enum(["draft", "live"]),
+	keys: array(keySchema).min(1).max(stateReadLimits.maxKeys).refine((keys) => new Set(keys).size === keys.length, "State keys must be distinct.")
 });
 var stateClearSchema = strictObject({
 	scope: _enum(["draft", "live"]),
-	key: string$1().min(1).refine((key) => new TextEncoder().encode(key).length <= 256).optional()
+	key: keySchema.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 skipDuplicatesConfigSchema = strictObject({ fields: array(string$1().refine((field) => field.length > 0 && field.split(".").every((part) => part.length > 0), "Use a nonempty dot-separated field path.")).refine((fields) => new Set(fields).size === fields.length, "Identity fields must be distinct.").default([]) });
+var skipDuplicatesExecutorSchema = skipDuplicatesConfigSchema.extend({ kind: literal("skip-duplicates") });
 var flowStateViewSchema = object({
 	version: literal(1),
 	scope: _enum(["draft", "live"]),
@@ -8876,24 +8881,30 @@ var flowStateViewSchema = object({
 		maxIdentities: number().positive(),
 		maxRunWrites: number().positive()
 	}),
-	values: array(object({
+	values: array(strictObject({
 		key: string$1(),
 		size: number().nonnegative(),
-		updatedAt: number(),
-		value: json$4().optional()
+		updatedAt: number()
 	})),
 	spaces: array(object({
 		space: string$1(),
-		mode: _enum(["new", "increasing"]),
 		count: number().nonnegative(),
-		watermark: union([
-			string$1(),
-			number(),
-			_null()
-		]),
+		pendingCount: number().nonnegative(),
+		reservedCount: number().nonnegative(),
 		updatedAt: number()
 	}))
 });
+var flowStateValuesSchema = object({
+	version: literal(1),
+	scope: _enum(["draft", "live"]),
+	values: array(strictObject({
+		key: keySchema,
+		value: json$4()
+	})).min(1).max(stateReadLimits.maxKeys)
+}).refine((response) => {
+	const encoder = new TextEncoder();
+	return response.values.reduce((bytes, item) => bytes + (item.value === null ? 0 : encoder.encode(JSON.stringify(item.value)).byteLength), 0) <= stateReadLimits.maxBytes;
+}, "State values exceed the 1 MiB read limit.");
 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);
@@ -9183,7 +9194,7 @@ var managedFields = object({
 			revisionId: text
 		}),
 		httpRequestExecutorSchema,
-		dedupeExecutorSchema
+		skipDuplicatesExecutorSchema
 	])
 });
 var managed = managedFields.transform(limitDecisionTask);
@@ -9655,7 +9666,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 < 13 && Object.values(content.document.graph.nodes).some((candidateNode) => candidateNode.kind === "task" && "executor" in candidateNode.task && candidateNode.task.executor.kind === "skip-duplicates")) throw new Error("Skip Duplicates 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.");
@@ -9812,7 +9823,7 @@ var type = _enum([
 	"decision",
 	"openapi",
 	"http-request",
-	"dedupe",
+	"skip-duplicates",
 	"condition",
 	"value",
 	"wait",
@@ -9943,7 +9954,7 @@ var authoringConfigurations = {
 	"connector": authoringDefinitionSchemas.connector.omit({ outputMode: true }).strict(),
 	"openapi": authoringOpenApiSchema,
 	"http-request": httpRequestConfigSchema,
-	"dedupe": dedupeConfigSchema,
+	"skip-duplicates": skipDuplicatesConfigSchema,
 	"agent": authoringDefinitionSchemas.agent.omit({
 		prompt: true,
 		tools: true
@@ -12057,7 +12068,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 !== "dedupe" && 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 !== "skip-duplicates" && nodeKind !== "llm" && nodeKind !== "agent" && nodeKind !== "value" && nodeKind !== "outputs" && nodeKind !== "webhook-response" && nodeKind !== "workflow" && nodeKind !== "wait") return invalidResponse();
 					return {
 						...base,
 						kind,
@@ -12282,12 +12293,13 @@ var ControlClient = class {
 			})
 		}));
 	}
-	async createFlow(name, idempotencyKey = `flow-${randomId()}`, teamId, tagIds) {
+	async createFlow(name, idempotencyKey = `flow-${randomId()}`, teamId, tagIds, initialPresentation) {
 		return flow$1(await this.request("/v1/flows", {
 			body: JSON.stringify({
 				name,
 				...teamId == null ? {} : { teamId },
 				...tagIds == null ? {} : { tagIds },
+				...initialPresentation == null ? {} : { presentation: initialPresentation },
 				version: 1
 			}),
 			headers: { "idempotency-key": idempotencyKey },
@@ -12369,10 +12381,22 @@ var ControlClient = class {
 			})
 		}));
 	}
-	async getFlowState(flowId, scope, values = false) {
-		const result = flowStateViewSchema.safeParse(await this.request(`/v1/flows/${segment(flowId)}/state?scope=${scope}&values=${values}`));
+	async getFlowState(flowId, scope) {
+		const result = flowStateViewSchema.safeParse(await this.request(`/v1/flows/${segment(flowId)}/state?scope=${scope}`));
 		return result.success && result.data.scope === scope ? result.data : invalidResponse();
 	}
+	async getFlowStateValues(flowId, scope, keys, signal) {
+		const result = flowStateValuesSchema.safeParse(await this.request(`/v1/flows/${segment(flowId)}/state/read`, {
+			method: "POST",
+			body: JSON.stringify({
+				version: 1,
+				scope,
+				keys
+			}),
+			signal
+		}));
+		return result.success && result.data.scope === scope && result.data.values.length === keys.length && result.data.values.every((item, index) => item.key === keys[index]) ? 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();
@@ -13135,7 +13159,8 @@ 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: tool("Inspect Flow state usage, business key metadata and deduplication spaces. Never returns values. Scope is required.", stateQuerySchema.extend({ flowId: flow }), true),
+	flow_state_read: tool("Read values for 1–16 distinct named State keys in one explicit scope. Values are returned in request order; missing keys return null. The combined stored JSON limit is 1 MiB; oversized reads fail without partial results.", stateReadSchema.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({

package/dist/common/run-events.js

@@ -54,7 +54,7 @@ var nodeKinds = /* @__PURE__ */ new Set([
 	"javascript",
 	"openapi",
 	"http-request",
-	"dedupe",
+	"skip-duplicates",
 	"llm",
 	"value",
 	"wait",
@@ -81,12 +81,12 @@ function nodeKind(value) {
 function runId(event) {
 	return string(event.runId, "Runtime event runId");
 }
-function nodeContext(event, flows, platformRunId) {
+function nodeContext(event, flows, platformRunId, identify) {
 	const rawRunId = runId(event);
 	const flowId = flows.get(rawRunId);
 	if (flowId == null) throw new TypeError("Runtime node event preceded its run.started event.");
 	return {
-		executionId: projectExecutionId(platformRunId, rawRunId, string(event.jobId, "Runtime node event jobId")),
+		executionId: identify("execution", platformRunId, rawRunId, string(event.jobId, "Runtime node event jobId")),
 		flowId,
 		nodeId: string(event.nodeId, "Runtime node event nodeId"),
 		rawRunId
@@ -139,6 +139,16 @@ function createEventProjector(platformRunId, nodeFailureCodes) {
 	const jobs = /* @__PURE__ */ new Map();
 	const nodeProgressBuckets = /* @__PURE__ */ new Map();
 	const runProgressBuckets = /* @__PURE__ */ new Map();
+	const identities = /* @__PURE__ */ new Map();
+	const identify = (prefix, ...parts) => {
+		const key = JSON.stringify([prefix, ...parts]);
+		let identity = identities.get(key);
+		if (identity == null) {
+			identity = opaqueId(prefix, ...parts);
+			identities.set(key, identity);
+		}
+		return identity;
+	};
 	return async (value) => {
 		const event = object(value, "Runtime event");
 		const type = string(event.type, "Runtime event type");
@@ -157,8 +167,8 @@ function createEventProjector(platformRunId, nodeFailureCodes) {
 				kind: "run.started",
 				payload: {
 					flowId,
-					...parentRunId === void 0 ? {} : { parentScopeId: await opaqueId("scope", platformRunId, parentRunId) },
-					scopeId: await opaqueId("scope", platformRunId, rawRunId)
+					...parentRunId === void 0 ? {} : { parentScopeId: await identify("scope", platformRunId, parentRunId) },
+					scopeId: await identify("scope", platformRunId, rawRunId)
 				}
 			};
 		}
@@ -175,7 +185,7 @@ function createEventProjector(platformRunId, nodeFailureCodes) {
 				payload: {
 					flowId,
 					progress: event.progress,
-					scopeId: await opaqueId("scope", platformRunId, rawRunId)
+					scopeId: await identify("scope", platformRunId, rawRunId)
 				}
 			};
 		}
@@ -183,7 +193,7 @@ function createEventProjector(platformRunId, nodeFailureCodes) {
 			const rawRunId = runId(event);
 			if (type == "run.failed" && rawRunId == platformRunId && event.failure != null) {
 				const failure = object(event.failure, "Runtime terminal failure");
-				const context = nodeContext(failure, flows, platformRunId);
+				const context = nodeContext(failure, flows, platformRunId, identify);
 				return {
 					kind: "node.failed",
 					payload: {
@@ -201,13 +211,13 @@ function createEventProjector(platformRunId, nodeFailureCodes) {
 			return;
 		}
 		if (type == "node.started" || type == "node.progress" || type == "node.artifact" || type == "node.log" || type == "node.completed" || type == "node.failed") {
-			const context = nodeContext(event, flows, platformRunId);
+			const context = nodeContext(event, flows, platformRunId, identify);
 			const executionId = await context.executionId;
 			const payload = {
 				executionId,
 				flowId: context.flowId,
 				nodeId: context.nodeId,
-				scopeId: await opaqueId("scope", platformRunId, context.rawRunId),
+				scopeId: await identify("scope", platformRunId, context.rawRunId),
 				...event.systemOutputs === void 0 ? {} : { systemOutputs: object(event.systemOutputs, "Runtime system outputs") },
 				...event.handled === true ? { handled: true } : {}
 			};

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

@@ -3,7 +3,10 @@ export { currentEngineContract, nodejsEngineContract, findEngineContract, type E
 /** 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>;
+        get: {
+            (key: string): Promise<JsonValue>;
+            (keys: readonly string[]): Promise<JsonValue[]>;
+        };
         set(key: unknown, value: unknown): Promise<void>;
         insert(key: unknown, value: unknown): Promise<boolean>;
         delete(key: unknown): Promise<void>;