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

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' | 'dedupe' | 'llm' | 'value' | 'wait' | 'outputs' | 'workflow' | 'webhook-response';
+    readonly nodeKind: 'agent' | 'approval' | 'condition' | 'connector' | 'decision' | 'javascript' | 'openapi' | 'http-request' | 'skip-duplicates' | 'llm' | 'value' | 'wait' | 'outputs' | 'workflow' | 'webhook-response';
     readonly nodeTitle?: string;
     readonly runId: string;
     readonly type: 'node.started';
@@ -167,6 +167,7 @@ export type RunLaunch = {
 } | {
     readonly resume: {
         readonly checkpoint: unknown;
+        readonly readyWorkflowRunIds?: readonly string[];
     };
     readonly bindingValues?: never;
     readonly inputs?: never;

package/dist/common/scheduler.js

@@ -14,37 +14,6 @@ var nanoid$1 = (size = 21) => {
 	return id;
 };
 //#endregion
-//#region src/flow/common/inputValue.ts
-/** An explicit clear suppresses the default; absent mappings still inherit it. */
-function inputValue(mapping, fallback) {
-	if (mapping?.kind === "unset") return void 0;
-	return mapping?.kind === "value" ? mapping.value : fallback;
-}
-//#endregion
-//#region ../../node_modules/.bun/dequal@2.0.3/node_modules/dequal/lite/index.mjs
-var has = Object.prototype.hasOwnProperty;
-function dequal(foo, bar) {
-	var ctor, len;
-	if (foo === bar) return true;
-	if (foo && bar && (ctor = foo.constructor) === bar.constructor) {
-		if (ctor === Date) return foo.getTime() === bar.getTime();
-		if (ctor === RegExp) return foo.toString() === bar.toString();
-		if (ctor === Array) {
-			if ((len = foo.length) === bar.length) while (len-- && dequal(foo[len], bar[len]));
-			return len === -1;
-		}
-		if (!ctor || typeof foo === "object") {
-			len = 0;
-			for (ctor in foo) {
-				if (has.call(foo, ctor) && ++len && !has.call(bar, ctor)) return false;
-				if (!(ctor in bar) || !dequal(foo[ctor], bar[ctor])) return false;
-			}
-			return Object.keys(bar).length === len;
-		}
-	}
-	return foo !== foo && bar !== bar;
-}
-//#endregion
 //#region ../../node_modules/.bun/zod@4.6.5/node_modules/zod/v4/core/util.js
 function getEnumValues(entries) {
 	const numericValues = Object.values(entries).filter((v) => typeof v === "number");
@@ -5719,6 +5688,37 @@ function datetime(params) {
 	return /* @__PURE__ */ _isoDateTime(ZodISODateTime, params);
 }
 //#endregion
+//#region src/flow/common/inputValue.ts
+/** An explicit clear suppresses the default; absent mappings still inherit it. */
+function inputValue(mapping, fallback) {
+	if (mapping?.kind === "unset") return void 0;
+	return mapping?.kind === "value" ? mapping.value : fallback;
+}
+//#endregion
+//#region ../../node_modules/.bun/dequal@2.0.3/node_modules/dequal/lite/index.mjs
+var has = Object.prototype.hasOwnProperty;
+function dequal(foo, bar) {
+	var ctor, len;
+	if (foo === bar) return true;
+	if (foo && bar && (ctor = foo.constructor) === bar.constructor) {
+		if (ctor === Date) return foo.getTime() === bar.getTime();
+		if (ctor === RegExp) return foo.toString() === bar.toString();
+		if (ctor === Array) {
+			if ((len = foo.length) === bar.length) while (len-- && dequal(foo[len], bar[len]));
+			return len === -1;
+		}
+		if (!ctor || typeof foo === "object") {
+			len = 0;
+			for (ctor in foo) {
+				if (has.call(foo, ctor) && ++len && !has.call(bar, ctor)) return false;
+				if (!(ctor in bar) || !dequal(foo[ctor], bar[ctor])) return false;
+			}
+			return Object.keys(bar).length === len;
+		}
+	}
+	return foo !== foo && bar !== bar;
+}
+//#endregion
 //#region ../../node_modules/.bun/@cfworker+json-schema@4.1.1/node_modules/@cfworker/json-schema/dist/esm/deep-compare-strict.js
 function deepCompareStrict(a, b) {
 	const typeofa = typeof a;
@@ -9535,23 +9535,30 @@ var httpRequestExecutorSchema = strictObject({
 	]).default("auto"),
 	statusPolicy: _enum(["success", "all"]).default("success")
 }).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);
+strictObject({
+	scope: _enum(["draft", "live"]),
+	values: literal(false).optional()
+});
 strictObject({
 	scope: _enum(["draft", "live"]),
-	values: boolean().optional()
+	keys: array(keySchema).min(1).max(stateReadLimits.maxKeys).refine((keys) => new Set(keys).size === keys.length, "State keys must be distinct.")
 });
 strictObject({
 	scope: _enum(["draft", "live"]),
-	key: string$1().min(1).refine((key) => new TextEncoder().encode(key).length <= 256).optional()
+	key: keySchema.optional()
 });
 strictObject({
 	scope: _enum(["draft", "live"]),
 	space: string$1().regex(/^(flow|node:.+)$/)
 });
-var dedupeExecutorSchema = strictObject({
-	field: string$1().default(""),
-	mode: _enum(["new", "increasing"]).default("new"),
-	space: _enum(["node", "flow"]).default("node")
-}).extend({ kind: literal("dedupe") });
+var skipDuplicatesExecutorSchema = 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([]) }).extend({ kind: literal("skip-duplicates") });
 object({
 	version: literal(1),
 	scope: _enum(["draft", "live"]),
@@ -9562,24 +9569,30 @@ object({
 		maxIdentities: number().positive(),
 		maxRunWrites: number().positive()
 	}),
-	values: array(object({
+	values: array(strictObject({
 		key: string$1(),
 		size: number().nonnegative(),
-		updatedAt: number(),
-		value: json$1().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()
 	}))
 });
+object({
+	version: literal(1),
+	scope: _enum(["draft", "live"]),
+	values: array(strictObject({
+		key: keySchema,
+		value: json$1()
+	})).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
 //#region src/flow/common/retry.ts
 var retryNodeTypes = [
@@ -9935,7 +9948,7 @@ var managedFields = object({
 			revisionId: text
 		}),
 		httpRequestExecutorSchema,
-		dedupeExecutorSchema
+		skipDuplicatesExecutorSchema
 	])
 });
 var managed = managedFields.transform(limitDecisionTask);
@@ -10598,7 +10611,7 @@ var nodeErrorSchema = {
 	}
 };
 function supportsNodeErrorHandling(node) {
-	return supportsNodeRetry(node) || node.kind === "task" && "executor" in node.task && node.task.executor.kind === "dedupe";
+	return supportsNodeRetry(node) || node.kind === "task" && "executor" in node.task && node.task.executor.kind === "skip-duplicates";
 }
 function nodeSystemOutputPorts(node) {
 	return supportsNodeErrorHandling(node) && node.onError == "error" ? { error: {
@@ -11997,6 +12010,8 @@ function runGraph(context, target, runId, launchInputs = {}, trigger, resume) {
 		const changes = yield* Queue.unbounded();
 		let remainingMs = context.remainingMs;
 		let measuredAt = yield* Clock.currentTimeMillis;
+		let nextCallCheckAt = measuredAt + (resume == null ? 1e3 : 0);
+		let readyWorkflowRunIds = resume?.readyWorkflowRunIds;
 		let idleSince;
 		const agents = { ...resume?.checkpoint.agents };
 		const resolveInputs = (nodeId, node) => resolveNodeInputs(nodeId, node, dependencies, context.bindingValues, launch[nodeId]);
@@ -12214,10 +12229,17 @@ function runGraph(context, target, runId, launchInputs = {}, trigger, resume) {
 				return yield* Effect.failCause(firstCause);
 			}
 			if (pendingWaits.size > 0 && context.waits != null) applyResolutions(yield* context.waits.resolutions([...pendingWaits.values()].map((wait) => wait.waitId), false), now);
-			for (const call of pendingCalls.values()) yield* observe(call.nodeId, call.jobId, Effect.gen(function* () {
-				const result = yield* execute(call.nodeId, target.graph.nodes[call.nodeId], call.jobId, call.input);
-				yield* settleNode(call.nodeId, call.jobId, result);
-			})).pipe(Effect.catch(() => Effect.void));
+			if (pendingCalls.size > 0 && now >= nextCallCheckAt) {
+				for (const call of pendingCalls.values()) {
+					if (readyWorkflowRunIds != null && !readyWorkflowRunIds.has(call.childRunId)) continue;
+					yield* observe(call.nodeId, call.jobId, Effect.gen(function* () {
+						const result = yield* execute(call.nodeId, target.graph.nodes[call.nodeId], call.jobId, call.input);
+						yield* settleNode(call.nodeId, call.jobId, result);
+					})).pipe(Effect.catch(() => Effect.void));
+				}
+				readyWorkflowRunIds = void 0;
+				nextCallCheckAt = (yield* Clock.currentTimeMillis) + 1e3;
+			}
 			const ready = dependencies.ready();
 			for (const nodeId of ready) executeReady(nodeId);
 			const running = yield* FiberSet.size(active);
@@ -12252,7 +12274,7 @@ function runGraph(context, target, runId, launchInputs = {}, trigger, resume) {
 			const activity = Queue.take(changes).pipe(Effect.as({}));
 			const decision = pendingWaits.size == 0 || context.waits == null ? Effect.never : context.waits.resolutions([...pendingWaits.values()].map((wait) => wait.waitId), true);
 			let next = Effect.raceFirst(activity, decision);
-			if (pendingCalls.size > 0) next = Effect.raceFirst(next, Effect.sleep(1e3).pipe(Effect.as({})));
+			if (pendingCalls.size > 0) next = Effect.raceFirst(next, Effect.sleep(Math.max(0, nextCallCheckAt - (yield* Clock.currentTimeMillis))).pipe(Effect.as({})));
 			if (left != null) next = Effect.raceFirst(next, Effect.sleep(Math.max(0, left)).pipe(Effect.as({})));
 			applyResolutions(yield* next, yield* Clock.currentTimeMillis);
 		}
@@ -12290,6 +12312,8 @@ function runFlow(prepared, options) {
 	return Effect.gen(function* () {
 		if (options.resume != null && (options.inputs != null || options.trigger != null || options.bindingValues != null)) return yield* Effect.fail(/* @__PURE__ */ new Error("A resumed Flow Run cannot accept launch inputs, binding values, or a Trigger seed."));
 		const decoded = options.resume == null ? void 0 : decodeFlowRunCheckpoint(options.resume.checkpoint);
+		const readyWorkflowRunIds = options.resume?.readyWorkflowRunIds === void 0 ? void 0 : new Set(array(string$1().min(1)).parse(options.resume.readyWorkflowRunIds));
+		if (readyWorkflowRunIds != null && [...readyWorkflowRunIds].some((id) => !decoded?.calls?.some((call) => call.childRunId == id))) return yield* Effect.fail(/* @__PURE__ */ new Error("Ready workflow Run is not present in the checkpoint."));
 		const outputs = (nodeId, value) => isResolutionNode(prepared.graph.nodes[nodeId]) && value.pending != null ? {
 			...value,
 			pending: withWaitNotificationMessage(value.pending)
@@ -12340,7 +12364,10 @@ function runFlow(prepared, options) {
 			inputDefs: prepared.inputDefs,
 			outputDefs: prepared.outputDefs,
 			outputMappings: prepared.outputMappings
-		}, options.runId, options.inputs, trigger, checkpoint == null ? void 0 : { checkpoint });
+		}, options.runId, options.inputs, trigger, checkpoint == null ? void 0 : {
+			checkpoint,
+			readyWorkflowRunIds
+		});
 	});
 }
 //#endregion

package/dist/common/state-conformance.d.ts

@@ -1,11 +1,11 @@
 import type { JsonValue } from './flow-model.js';
-import type { DedupeConfig } from './flow-state.js';
+import type { SkipDuplicatesConfig } from './flow-state.js';
 export interface StateConformanceHarness {
     readonly maxIdentities: number;
     /** Executes Code on the same initially empty Flow and scope on every call; returns its `result` output. */
     run(source: string): Promise<JsonValue>;
-    /** Executes the same dedupe node across Runs, updating its business config and items. */
-    dedupe(config: DedupeConfig, items: JsonValue[]): Promise<{
+    /** Executes the same Skip Duplicates node across Runs, updating its business config and items. */
+    skipDuplicates(config: SkipDuplicatesConfig, items: JsonValue[]): Promise<{
         items: JsonValue[];
         duplicates: JsonValue[];
     }>;

package/dist/index.d.ts

@@ -104,6 +104,7 @@ export interface TaskContext<Actions extends object = Record<string, never>, Wor
     readonly blockId: string;
     readonly state: {
         get(key: string): Promise<JsonValue | null>;
+        get(keys: readonly string[]): Promise<(JsonValue | null)[]>;
         set(key: string, value: JsonValue): Promise<void>;
         insert(key: string, value: Exclude<JsonValue, null>): Promise<boolean>;
         delete(key: string): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oomol-lab/open-flow",
-  "version": "0.1.0-beta.77",
+  "version": "0.1.0-beta.79",
   "description": "TypeScript contracts and Browser runtime for Open Flow.",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {

package/src/control/common/api.ts

@@ -1,8 +1,8 @@
 import type { CanvasCommand } from '../../canvas/common/commands.ts'
-import type { FlowStateView, StateScope } from '../../state/common/state.ts'
+import type { FlowStateValues, FlowStateView, StateScope } from '../../state/common/state.ts'
 
 import { currentEngineContract } from '../../runtime/common/engineContract.ts'
-import { flowStateViewSchema } from '../../state/common/state.ts'
+import { flowStateValuesSchema, flowStateViewSchema } from '../../state/common/state.ts'
 import { workflowContractSchema, workflowReferencesSchema } from '../../workflow/common/workflow.ts'
 export type { CanvasCommand, CanvasCommandSubscriber } from '../../canvas/common/commands.ts'
 import type { LiveDetails } from './liveDetails.ts'
@@ -149,6 +149,11 @@ export interface PublicationPresentation {
   readonly presentation: Presentation | null
 }
 
+export interface FlowCreationOptions {
+  readonly tagIds?: readonly string[]
+  readonly presentation?: Readonly<Record<string, JsonValue>>
+}
+
 export interface Presentation {
   readonly revision: number
   readonly updatedAt: string
@@ -703,7 +708,7 @@ export function decodeRunEvent(value: unknown) {
             nodeKind !== 'decision' &&
             nodeKind !== 'openapi' &&
             nodeKind !== 'http-request' &&
-            nodeKind !== 'dedupe' &&
+            nodeKind !== 'skip-duplicates' &&
             nodeKind !== 'llm' &&
             nodeKind !== 'agent' &&
             nodeKind !== 'value' &&
@@ -941,10 +946,22 @@ export class ControlClient {
     )
   }
 
-  async createFlow(name: string, idempotencyKey = `flow-${randomId()}`, teamId?: string, tagIds?: readonly string[]): Promise<Flow> {
+  async createFlow(
+    name: string,
+    idempotencyKey = `flow-${randomId()}`,
+    teamId?: string,
+    tagIds?: readonly string[],
+    initialPresentation?: Readonly<Record<string, JsonValue>>,
+  ): Promise<Flow> {
     return flow(
       await this.request('/v1/flows', {
-        body: JSON.stringify({ name, ...(teamId == null ? {} : { teamId }), ...(tagIds == null ? {} : { tagIds }), version: 1 }),
+        body: JSON.stringify({
+          name,
+          ...(teamId == null ? {} : { teamId }),
+          ...(tagIds == null ? {} : { tagIds }),
+          ...(initialPresentation == null ? {} : { presentation: initialPresentation }),
+          version: 1,
+        }),
         headers: { 'idempotency-key': idempotencyKey },
         method: 'POST',
       }),
@@ -1000,11 +1017,23 @@ export class ControlClient {
     return flow(await this.request(`/v1/flows/${segment(flowId)}`, { method: 'PATCH', body: JSON.stringify({ ...changes, version: 1 }) }))
   }
 
-  async getFlowState(flowId: string, scope: StateScope, values = false): Promise<FlowStateView> {
-    const result = flowStateViewSchema.safeParse(await this.request(`/v1/flows/${segment(flowId)}/state?scope=${scope}&values=${values}`))
+  async getFlowState(flowId: string, scope: StateScope): Promise<FlowStateView> {
+    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: string, scope: StateScope, keys: readonly string[], signal?: AbortSignal): Promise<FlowStateValues> {
+    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: string, scope: StateScope, key?: string): Promise<void> {
     const source = record(
       await this.request(`/v1/flows/${segment(flowId)}/state?scope=${scope}${key == null ? '' : `&key=${encodeURIComponent(key)}`}`, { method: 'DELETE' }),

package/src/control/common/authoring.ts

@@ -43,7 +43,7 @@ import {
 } from '../../flow/common/nodeChanges.ts'
 import { retryConfigurationSchema } from '../../flow/common/retry.ts'
 import { httpRequestTask, httpRequestConfigSchema, httpRequestInputs } from '../../http/common/httpRequest.ts'
-import { dedupeConfigSchema, dedupeTask } from '../../state/common/state.ts'
+import { skipDuplicatesConfigSchema, skipDuplicatesTask } from '../../state/common/state.ts'
 import { withWorkflowTask, workflowTask, workflowSelectionTask, workflowCapability, workflowAgentTool } from '../../workflow/common/workflow.ts'
 import { conditionConfigurationView, prepareConditionConfiguration } from './authoringCondition.ts'
 import { authoringDiagnosticField } from './authoringDiagnosticFields.ts'
@@ -147,7 +147,7 @@ export function authoringNode(content: RevisionContent, ref: string) {
         ),
       }
     else if (task.executor.kind == 'workflow') config = { flowId: task.executor.flowId }
-    else if (task.executor.kind == 'http-request' || task.executor.kind == 'dedupe') {
+    else if (task.executor.kind == 'http-request' || task.executor.kind == 'skip-duplicates') {
       const { kind: _kind, ...settings } = task.executor
       config = settings
     } else if (task.executor.kind == 'openapi') {
@@ -522,7 +522,8 @@ export async function compileAuthoring(base: RevisionContent, request: Authoring
           task = { ...before, name: String(update.name), executor: { ...executor, ...config } } as ManagedTaskDefinition
         } else task = await connectorTask(config, String(update.name))
       } else if (type == 'decision') task = decisionTask(config.questions as Parameters<typeof decisionTask>[0], String(update.name))
-      else if (type == 'dedupe') task = { ...before, name: String(update.name), executor: { kind: 'dedupe', ...dedupeConfigSchema.parse(config) } }
+      else if (type == 'skip-duplicates')
+        task = { ...before, name: String(update.name), executor: { kind: 'skip-duplicates', ...skipDuplicatesConfigSchema.parse(config) } }
       else if (type == 'http-request') {
         task = httpRequestTask(httpRequestConfigSchema.parse(config), String(update.name), before)
         next = { ...next, inputs: httpRequestInputs(node.inputs, before, task) } as GraphNode
@@ -776,8 +777,8 @@ export async function compileAuthoring(base: RevisionContent, request: Authoring
             case 'connector':
               changes = createManagedTask(identity, await connectorTask(config, name))
               break
-            case 'dedupe':
-              changes = createManagedTask(identity, dedupeTask(dedupeConfigSchema.parse(config), name))
+            case 'skip-duplicates':
+              changes = createManagedTask(identity, skipDuplicatesTask(skipDuplicatesConfigSchema.parse(config), name))
               break
             case 'http-request':
               changes = createManagedTask(identity, httpRequestTask(httpRequestConfigSchema.parse(config), name))

package/src/control/common/authoringExamples.ts

@@ -13,7 +13,7 @@ import {
 } from '../../flow/common/nodeChanges.ts'
 import { httpRequestTask } from '../../http/common/httpRequest.ts'
 import { openApiTask, selectOperation } from '../../openapi/common/openapi.ts'
-import { dedupeTask } from '../../state/common/state.ts'
+import { skipDuplicatesTask } from '../../state/common/state.ts'
 
 const descriptions = {
   'start': 'A Start node with a required message parameter. Supply it through trigger.outputs.',
@@ -24,7 +24,8 @@ const descriptions = {
   'poll': 'Gmail polling by key; replace CONNECTION_ID with an active Gmail connection.',
   'integration': 'Telegram webhook integration by key; replace CONNECTION_ID with an active Telegram connection.',
   'decision': 'AI Decision evaluates named questions against target and returns a complete answer object per output. Configure target before running.',
-  'dedupe': 'Filter items using persistent history. Records immediately, including when downstream work fails. Empty field uses each scalar item as identity.',
+  'skip-duplicates':
+    'Skip items already recorded by successful Runs. Configure identity fields; an empty list uses each string or numeric item. History is private to the node and only commits after Run success.',
   'http-request': 'A single HTTP request. Bind url and request inputs; outputs are body, statusCode and headers.',
   'openapi': 'A fixed JSON API operation. Replace the example document and URL before running.',
   'connector':
@@ -59,10 +60,10 @@ export function authoringExample(name: string): { version: 1; operations: readon
         { name: 'needs_support', type: 'noul', instructions: 'Does the customer need support?' },
       ])
       break
-    case 'dedupe':
+    case 'skip-duplicates':
       operations = [
-        ...createManagedTask({ nodeId: 'dedupe' }, dedupeTask()),
-        { kind: 'graph.node.input.set', nodeId: 'dedupe', handle: 'items', value: { kind: 'value', value: ['a', 'b', 'a'] } },
+        ...createManagedTask({ nodeId: 'skip-duplicates' }, skipDuplicatesTask()),
+        { kind: 'graph.node.input.set', nodeId: 'skip-duplicates', handle: 'items', value: { kind: 'value', value: ['a', 'b', 'a'] } },
       ]
       break
     case 'http-request':

package/src/control/common/authoringSchema.ts

@@ -12,7 +12,7 @@ import {
 import { retryConfigurationSchema, retryNodeTypes } from '../../flow/common/retry.ts'
 import { httpRequestConfigSchema } from '../../http/common/httpRequest.ts'
 import { currentEngineContract, findEngineContract } from '../../runtime/common/engineContract.ts'
-import { dedupeConfigSchema } from '../../state/common/state.ts'
+import { skipDuplicatesConfigSchema } from '../../state/common/state.ts'
 import { authoringLlmConfiguration } from './authoringLlm.ts'
 import { authoringOpenApiSchema } from './authoringOpenApi.ts'
 
@@ -36,7 +36,7 @@ export const authoringTypes = [
   'decision',
   'openapi',
   'http-request',
-  'dedupe',
+  'skip-duplicates',
   'condition',
   'value',
   'wait',
@@ -120,7 +120,7 @@ export const authoringConfigurations = {
   'connector': definitions.connector.omit({ outputMode: true }).strict(),
   'openapi': authoringOpenApiSchema,
   'http-request': httpRequestConfigSchema,
-  'dedupe': dedupeConfigSchema,
+  'skip-duplicates': skipDuplicatesConfigSchema,
   'agent': definitions.agent
     .omit({ prompt: true, tools: true })
     .extend({
@@ -286,7 +286,7 @@ export function authoringSchema(kind?: AuthoringType) {
       }
     : {
         type: kind,
-        onError: kind == 'dedupe' || retryNodeTypes.some((nodeType) => nodeType == kind) ? { enum: ['stop', 'error'] } : false,
+        onError: kind == 'skip-duplicates' || retryNodeTypes.some((nodeType) => nodeType == kind) ? { enum: ['stop', 'error'] } : false,
         retry: retryNodeTypes.some((nodeType) => nodeType == kind) ? z.toJSONSchema(retryConfigurationSchema) : false,
         inputSources: ['poll', 'integration'].includes(kind)
           ? ['value', 'unset', 'default']
@@ -309,8 +309,8 @@ export function authoringSchema(kind?: AuthoringType) {
                       ? 'Configure static parameters with node.add.inputs or input.set. Definitions come from the selected Trigger key; execution output and variable sources are unavailable.'
                       : kind == 'llm'
                         ? 'Configure model settings, message templates and history as defaults. Input bindings with the same names override these defaults; named business inputs can be bound directly. Template strings interpolate {{name}}.'
-                        : kind == 'dedupe'
-                          ? 'Bind an items array. Configure field (dot-separated identity path, empty for scalar items), mode (new or increasing), and space (node or flow). Outputs are items and duplicates. History persists immediately; downstream failures do not roll it back. Increasing mode accepts finite numbers or RFC 3339 timestamps, never mixed types.'
+                        : kind == 'skip-duplicates'
+                          ? 'Bind an items array. Configure fields as dot-separated identity paths; an empty list uses each scalar item. Outputs are items and duplicates. History belongs to this node and commits only when the Run completes successfully. Fields accept strings or finite numbers; missing or complex values reject the batch.'
                           : kind == 'http-request'
                             ? 'Configure method, query/headers modes and names, bodyFormat, authentication, responseFormat and statusPolicy. Bind url, query.<name>/header.<name> or whole query/headers objects, body and auth.token (Basic: auth.username/auth.password). Credentials accept variables or upstream outputs only. Outputs: body, statusCode, headers. Authentication is replaced as a complete choice.'
                             : kind == 'openapi'
@@ -335,7 +335,7 @@ export function authoringSchema(kind?: AuthoringType) {
               'connector': { config: { action: '<Action ID>', connectionId: '<Connection ID>' } },
               'poll': { config: { key: '<Trigger key>', schedule: [{ type: 'every', unit: 'minute', value: 5 }] } },
               'integration': { config: { key: '<Trigger key>' } },
-              'dedupe': { config: { field: 'id', mode: 'new', space: 'node' }, inputs: { items: { kind: 'value', value: [{ id: 'a' }, { id: 'b' }] } } },
+              'skip-duplicates': { config: { fields: ['id'] }, inputs: { items: { kind: 'value', value: [{ id: 'a' }, { id: 'b' }] } } },
               'http-request': { config: {}, inputs: { url: { kind: 'value', value: 'https://example.com' } } },
               'openapi': { config: { sourceUrl: 'https://example.com/openapi.json', path: '/items', method: 'get' } },
               'code': { code: 'export default ({value}) => ({result:value})', inputs: { value: { kind: 'value', value: 'Hello' } } },

package/src/control/common/conformance.ts

@@ -205,6 +205,37 @@ function liveRunRequest(harness: ControlApiConformanceHarness, publicationId: st
 }
 
 export const controlApiConformanceCases: readonly ControlApiConformanceCase[] = [
+  {
+    name: 'reads State metadata and bounded explicit keys without scope-wide value retrieval',
+    async verify(harness) {
+      const api = new ControlClient((url, init) => harness.request(new Request(new URL(url, harness.origin), init)))
+      const flow = await api.createFlow('State reads')
+      equal((await api.getFlowState(flow.flowId, 'draft')).values, [], 'New Flow State metadata')
+      equal(
+        await api.getFlowStateValues(flow.flowId, 'live', ['second', 'first']),
+        {
+          version: 1,
+          scope: 'live',
+          values: [
+            { key: 'second', value: null },
+            { key: 'first', value: null },
+          ],
+        },
+        'Missing named State keys',
+      )
+      const metadata = await request(harness, `/v1/flows/${flow.flowId}/state?scope=draft&values=false`)
+      await json(metadata, 200, 'Legacy metadata-only query')
+      equal(metadata.headers.get('cache-control'), 'no-store', 'State metadata cache policy')
+      await error(await request(harness, `/v1/flows/${flow.flowId}/state?scope=draft&values=true`), 400, 'flow.invalid', 'Scope-wide State values')
+      for (const input of [{ scope: 'draft', keys: [] }, { keys: ['key'] }, { scope: 'draft', keys: Array.from({ length: 17 }, (_, index) => String(index)) }])
+        await error(
+          await request(harness, `/v1/flows/${flow.flowId}/state/read`, { method: 'POST', body: JSON.stringify({ version: 1, ...input }) }),
+          400,
+          'flow.invalid',
+          'Invalid named State read',
+        )
+    },
+  },
   {
     name: 'imports workflow files atomically and exports a new unpublished draft with its Presentation',
     async verify(harness) {

package/src/control/common/mcp.ts

@@ -5,7 +5,7 @@ import { canvasCommandSchema } from '../../canvas/common/commands.ts'
 import { runStatuses } from '../../execution/common/runLifecycle.ts'
 import { waitCommentSchema } from '../../execution/common/wait.ts'
 import { resourceNameIssue } from '../../flow/common/change.ts'
-import { stateQuerySchema, stateClearSchema, dedupeClearSchema } from '../../state/common/state.ts'
+import { stateQuerySchema, stateReadSchema, stateClearSchema, dedupeClearSchema } from '../../state/common/state.ts'
 import { authoringReadSchema, authoringSearchSchema, authoringRequestSchema, authoringSchemaQuery } from './authoringSchema.ts'
 import { resultQuerySchema } from './resultQuery.ts'
 
@@ -52,10 +52,15 @@ function tool<Args>(description: string, schema: z.ZodType<Args>, readOnly: bool
 
 export const mcpTools = {
   flow_state: tool(
-    'Inspect Flow state usage, business keys and deduplication spaces. Values are omitted unless requested. Scope is required.',
+    '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 }),

package/src/control/common/requests.ts

@@ -10,6 +10,7 @@ import { decodeDraftOperations, draftOperationsSchema } from './draftOperations.
 export { decodeDraftOperations, draftOperationsSchema, resolveDraftOperations, type DraftOperation } from './draftOperations.ts'
 import { z } from 'zod'
 import { resourceNameIssue } from '../../flow/common/change.ts'
+import { stateReadSchema } from '../../state/common/state.ts'
 import { createEventSourceSchema, updateEventSourceSchema, eventSourceRevisionSchema } from './eventSourceSchemas.ts'
 
 export const waitActionBodySchema: { parse(value: unknown): { comment?: string | null } } = z.strictObject({ comment: waitCommentSchema })
@@ -23,6 +24,7 @@ const tagName = id.transform((name) => name.trim()).refine((name) => resourceNam
 const inputs = z.record(z.string(), z.record(z.string(), json))
 const trigger = z.strictObject({ nodeId: id, outputs: z.record(z.string(), json) })
 const schemas = {
+  readFlowState: stateReadSchema.extend({ version }),
   canvas: z.strictObject({ command: canvasCommandSchema, version }),
   authoringCheck: authoringCheckSchema,
   authoringEdit: authoringRequestSchema,
@@ -34,7 +36,13 @@ const schemas = {
   updateEventSource: updateEventSourceSchema,
   eventSourceRevision: eventSourceRevisionSchema,
   importFlow: z.strictObject({ file: json, name: flowName.optional(), teamId: id.optional(), tagIds: tagIds.optional(), version }),
-  createFlow: z.strictObject({ name: flowName, teamId: id.optional(), tagIds: tagIds.optional(), version }),
+  createFlow: z.strictObject({
+    name: flowName,
+    teamId: id.optional(),
+    tagIds: tagIds.optional(),
+    presentation: z.record(z.string(), json).optional(),
+    version,
+  }),
   saveTag: z.strictObject({ name: tagName, version }),
   setFlowTags: z.strictObject({ tagIds, version }),
   updateFlow: z.union([z.strictObject({ name: flowName, tagIds: tagIds.optional(), version }), z.strictObject({ name: flowName.optional(), tagIds, version })]),
@@ -72,6 +80,7 @@ function decoder<Value>(schema: z.ZodType<Value>): (value: unknown) => Value {
 }
 
 export const controlRequests = {
+  readFlowState: decoder(schemas.readFlowState),
   canvas: decoder(schemas.canvas),
   authoringCheck: decoder(schemas.authoringCheck),
   authoringEdit: decoder(schemas.authoringEdit),