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

package/dist/common/authoring.d.ts

@@ -10,7 +10,7 @@ export declare class AuthoringError extends Error {
 }
 export declare function authoringNode(content: RevisionContent, ref: string): {
     ref: 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;
     readOnly: boolean;
     description?: string | undefined;
@@ -98,7 +98,7 @@ export declare function readAuthoring(content: RevisionContent, query?: Authorin
     text?: undefined;
     nodes: {
         ref: 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;
         readOnly: boolean;
         description?: string | undefined;
@@ -174,7 +174,7 @@ export declare function readAuthoring(content: RevisionContent, query?: Authorin
     text?: undefined;
     nodes: {
         ref: 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;
         readOnly: boolean;
         inputHandles: string[];

package/dist/common/authoringExamples.d.ts

@@ -8,7 +8,7 @@ declare const descriptions: {
     readonly poll: 'Gmail polling by key; replace CONNECTION_ID with an active Gmail connection.';
     readonly integration: 'Telegram webhook integration by key; replace CONNECTION_ID with an active Telegram connection.';
     readonly decision: 'AI Decision evaluates named questions against target and returns a complete answer object per output. Configure target before running.';
-    readonly dedupe: 'Filter items using persistent history. Records immediately, including when downstream work fails. Empty field uses each scalar item as identity.';
+    readonly '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.';
     readonly 'http-request': 'A single HTTP request. Bind url and request inputs; outputs are body, statusCode and headers.';
     readonly openapi: 'A fixed JSON API operation. Replace the example document and URL before running.';
     readonly connector: 'A Connector Task and its node. Replace ACTION_ID, CONNECTION_ID and port definitions using connector_get / connector show. Set connectionId to an empty string to defer account configuration; execution will require an account.';
@@ -24,8 +24,8 @@ declare const descriptions: {
 };
 export declare const authoringExampleNames: (keyof typeof descriptions)[];
 export declare const authoringExamples: {
-    name: "agent" | "approval" | "code" | "condition" | "connector" | "cron" | "decision" | "dedupe" | "error" | "http-request" | "integration" | "llm-chat" | "llm-json" | "openapi" | "poll" | "poll-notification" | "start" | "value" | "wait" | "webhook" | "webhook-response";
-    description: "A Connector Task and its node. Replace ACTION_ID, CONNECTION_ID and port definitions using connector_get / connector show. Set connectionId to an empty string to defer account configuration; execution will require an account." | "A Flow Error node. Select upstream Flows, then publish and enable this Flow to listen for failures in their automatic runs." | "A JavaScript module and its node. Use Code for custom computation; use Connector Tasks for existing actions." | "A Start node with a required message parameter. Supply it through trigger.outputs." | "A Wait with a continue action and a built-in notification output." | "A Webhook start node." | "A condition with true and false execution branches." | "A fixed JSON API operation. Replace the example document and URL before running." | "A fixed value node." | "A single HTTP request. Bind url and request inputs; outputs are body, statusCode and headers." | "AI Decision evaluates named questions against target and returns a complete answer object per output. Configure target before running." | "An Agent with code computation enabled. Configure a model available in the deployment." | "An Approval with approve and reject decision branches and a built-in notification output." | "An HTTP response node with body, statusCode and headers inputs. Select it from a reachable Webhook." | "An LLM JSON Task and its node; configure a model available in the deployment." | "An LLM chat Task and its node; configure a model available in the deployment." | "An hourly scheduled start node." | "Filter items using persistent history. Records immediately, including when downstream work fails. Empty field uses each scalar item as identity." | "Gmail events → JavaScript text formatting → Connector notification. Replace connection/action IDs and match the notification input ports." | "Gmail polling by key; replace CONNECTION_ID with an active Gmail connection." | "Telegram webhook integration by key; replace CONNECTION_ID with an active Telegram connection.";
+    name: "agent" | "approval" | "code" | "condition" | "connector" | "cron" | "decision" | "error" | "http-request" | "integration" | "llm-chat" | "llm-json" | "openapi" | "poll" | "poll-notification" | "skip-duplicates" | "start" | "value" | "wait" | "webhook" | "webhook-response";
+    description: "A Connector Task and its node. Replace ACTION_ID, CONNECTION_ID and port definitions using connector_get / connector show. Set connectionId to an empty string to defer account configuration; execution will require an account." | "A Flow Error node. Select upstream Flows, then publish and enable this Flow to listen for failures in their automatic runs." | "A JavaScript module and its node. Use Code for custom computation; use Connector Tasks for existing actions." | "A Start node with a required message parameter. Supply it through trigger.outputs." | "A Wait with a continue action and a built-in notification output." | "A Webhook start node." | "A condition with true and false execution branches." | "A fixed JSON API operation. Replace the example document and URL before running." | "A fixed value node." | "A single HTTP request. Bind url and request inputs; outputs are body, statusCode and headers." | "AI Decision evaluates named questions against target and returns a complete answer object per output. Configure target before running." | "An Agent with code computation enabled. Configure a model available in the deployment." | "An Approval with approve and reject decision branches and a built-in notification output." | "An HTTP response node with body, statusCode and headers inputs. Select it from a reachable Webhook." | "An LLM JSON Task and its node; configure a model available in the deployment." | "An LLM chat Task and its node; configure a model available in the deployment." | "An hourly scheduled start node." | "Gmail events → JavaScript text formatting → Connector notification. Replace connection/action IDs and match the notification input ports." | "Gmail polling by key; replace CONNECTION_ID with an active Gmail connection." | "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." | "Telegram webhook integration by key; replace CONNECTION_ID with an active Telegram connection.";
 }[];
 export declare function authoringExample(name: string): {
     version: 1;

package/dist/common/authoringSchema.d.ts

@@ -1,6 +1,6 @@
 import type { JsonValue } from '../index.js';
 import { z } from 'zod';
-export declare const authoringTypes: readonly ['start', 'outputs', 'webhook-response', 'workflow', 'webhook', 'cron', 'error', 'poll', 'integration', 'code', 'connector', 'agent', 'llm', 'decision', 'openapi', 'http-request', 'dedupe', 'condition', 'value', 'wait', 'approval'];
+export declare const authoringTypes: readonly ['start', 'outputs', 'webhook-response', 'workflow', 'webhook', 'cron', 'error', 'poll', 'integration', 'code', 'connector', 'agent', 'llm', 'decision', 'openapi', 'http-request', 'skip-duplicates', 'condition', 'value', 'wait', 'approval'];
 declare const type: z.ZodEnum<{
     agent: "agent";
     approval: "approval";
@@ -9,7 +9,6 @@ declare const type: z.ZodEnum<{
     connector: "connector";
     cron: "cron";
     decision: "decision";
-    dedupe: "dedupe";
     error: "error";
     "http-request": "http-request";
     integration: "integration";
@@ -17,6 +16,7 @@ declare const type: z.ZodEnum<{
     openapi: "openapi";
     outputs: "outputs";
     poll: "poll";
+    "skip-duplicates": "skip-duplicates";
     start: "start";
     value: "value";
     wait: "wait";
@@ -304,16 +304,8 @@ export declare const authoringConfigurations: {
             success: "success";
         }>>;
     }, z.core.$strict>;
-    dedupe: z.ZodObject<{
-        field: z.ZodDefault<z.ZodString>;
-        mode: z.ZodDefault<z.ZodEnum<{
-            increasing: "increasing";
-            new: "new";
-        }>>;
-        space: z.ZodDefault<z.ZodEnum<{
-            flow: "flow";
-            node: "node";
-        }>>;
+    'skip-duplicates': z.ZodObject<{
+        fields: z.ZodDefault<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>;
     agent: z.ZodObject<{
         code: z.ZodOptional<z.ZodBoolean>;
@@ -709,7 +701,6 @@ export declare const authoringEditSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         connector: "connector";
         cron: "cron";
         decision: "decision";
-        dedupe: "dedupe";
         error: "error";
         "http-request": "http-request";
         integration: "integration";
@@ -717,6 +708,7 @@ export declare const authoringEditSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         openapi: "openapi";
         outputs: "outputs";
         poll: "poll";
+        "skip-duplicates": "skip-duplicates";
         start: "start";
         value: "value";
         wait: "wait";
@@ -881,7 +873,6 @@ export declare const authoringRequestSchema: z.ZodObject<{
             connector: "connector";
             cron: "cron";
             decision: "decision";
-            dedupe: "dedupe";
             error: "error";
             "http-request": "http-request";
             integration: "integration";
@@ -889,6 +880,7 @@ export declare const authoringRequestSchema: z.ZodObject<{
             openapi: "openapi";
             outputs: "outputs";
             poll: "poll";
+            "skip-duplicates": "skip-duplicates";
             start: "start";
             value: "value";
             wait: "wait";
@@ -1067,7 +1059,6 @@ export declare const authoringSearchSchema: z.ZodObject<{
         connector: "connector";
         cron: "cron";
         decision: "decision";
-        dedupe: "dedupe";
         error: "error";
         "http-request": "http-request";
         integration: "integration";
@@ -1075,6 +1066,7 @@ export declare const authoringSearchSchema: z.ZodObject<{
         openapi: "openapi";
         outputs: "outputs";
         poll: "poll";
+        "skip-duplicates": "skip-duplicates";
         start: "start";
         value: "value";
         wait: "wait";
@@ -1099,7 +1091,6 @@ export declare const authoringSchemaQuery: z.ZodObject<{
         connector: "connector";
         cron: "cron";
         decision: "decision";
-        dedupe: "dedupe";
         error: "error";
         "http-request": "http-request";
         integration: "integration";
@@ -1107,6 +1098,7 @@ export declare const authoringSchemaQuery: z.ZodObject<{
         openapi: "openapi";
         outputs: "outputs";
         poll: "poll";
+        "skip-duplicates": "skip-duplicates";
         start: "start";
         value: "value";
         wait: "wait";
@@ -1132,7 +1124,6 @@ export declare function authoringRequestContract(name: string): {
                 connector: "connector";
                 cron: "cron";
                 decision: "decision";
-                dedupe: "dedupe";
                 error: "error";
                 "http-request": "http-request";
                 integration: "integration";
@@ -1140,6 +1131,7 @@ export declare function authoringRequestContract(name: string): {
                 openapi: "openapi";
                 outputs: "outputs";
                 poll: "poll";
+                "skip-duplicates": "skip-duplicates";
                 start: "start";
                 value: "value";
                 wait: "wait";
@@ -1315,7 +1307,6 @@ export declare function authoringRequestContract(name: string): {
             connector: "connector";
             cron: "cron";
             decision: "decision";
-            dedupe: "dedupe";
             error: "error";
             "http-request": "http-request";
             integration: "integration";
@@ -1323,6 +1314,7 @@ export declare function authoringRequestContract(name: string): {
             openapi: "openapi";
             outputs: "outputs";
             poll: "poll";
+            "skip-duplicates": "skip-duplicates";
             start: "start";
             value: "value";
             wait: "wait";
@@ -1416,7 +1408,7 @@ export declare function authoringRequestContract(name: string): {
 } | undefined;
 export declare function authoringSchema(kind?: AuthoringType): {
     type?: undefined;
-    types: readonly ["start", "outputs", "webhook-response", "workflow", "webhook", "cron", "error", "poll", "integration", "code", "connector", "agent", "llm", "decision", "openapi", "http-request", "dedupe", "condition", "value", "wait", "approval"];
+    types: readonly ["start", "outputs", "webhook-response", "workflow", "webhook", "cron", "error", "poll", "integration", "code", "connector", "agent", "llm", "decision", "openapi", "http-request", "skip-duplicates", "condition", "value", "wait", "approval"];
     request: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
         baseRevision: z.ZodString;
         requestId: z.ZodString;
@@ -1431,7 +1423,6 @@ export declare function authoringSchema(kind?: AuthoringType): {
                 connector: "connector";
                 cron: "cron";
                 decision: "decision";
-                dedupe: "dedupe";
                 error: "error";
                 "http-request": "http-request";
                 integration: "integration";
@@ -1439,6 +1430,7 @@ export declare function authoringSchema(kind?: AuthoringType): {
                 openapi: "openapi";
                 outputs: "outputs";
                 poll: "poll";
+                "skip-duplicates": "skip-duplicates";
                 start: "start";
                 value: "value";
                 wait: "wait";
@@ -1601,7 +1593,7 @@ export declare function authoringSchema(kind?: AuthoringType): {
 } | {
     types?: undefined;
     request?: 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";
+    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";
     onError: boolean | {
         enum: string[];
     };
@@ -1615,7 +1607,7 @@ export declare function authoringSchema(kind?: AuthoringType): {
     example: {
         op: string;
         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;
     };
     configuration: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{}, z.core.$strict>>;

package/dist/common/control-api-conformance.js

@@ -8628,24 +8628,31 @@ 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 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: boolean().optional()
+	values: literal(false).optional()
 });
 strictObject({
 	scope: _enum(["draft", "live"]),
-	key: string$1().min(1).refine((key) => new TextEncoder().encode(key).length <= 256).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"]),
-	space: string$1().regex(/^(flow|node:.+)$/)
+	key: keySchema.optional()
 });
-var dedupeConfigSchema = strictObject({
-	field: string$1().default(""),
-	mode: _enum(["new", "increasing"]).default("new"),
-	space: _enum(["node", "flow"]).default("node")
+strictObject({
+	scope: _enum(["draft", "live"]),
+	space: string$1().regex(/^(flow|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"]),
@@ -8656,24 +8663,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);
@@ -8963,7 +8976,7 @@ var managedFields = object({
 			revisionId: text
 		}),
 		httpRequestExecutorSchema,
-		dedupeExecutorSchema
+		skipDuplicatesExecutorSchema
 	])
 });
 var managed = managedFields.transform(limitDecisionTask);
@@ -9435,7 +9448,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.");
@@ -9649,7 +9662,7 @@ var type = _enum([
 	"decision",
 	"openapi",
 	"http-request",
-	"dedupe",
+	"skip-duplicates",
 	"condition",
 	"value",
 	"wait",
@@ -9780,7 +9793,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
@@ -11866,7 +11879,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,
@@ -12091,12 +12104,13 @@ var ControlClient = class {
 			})
 		}));
 	}
-	async createFlow(name, idempotencyKey = `flow-${randomId()}`, teamId, tagIds) {
+	async createFlow(name, idempotencyKey = `flow-${randomId()}`, teamId, tagIds, initialPresentation) {
 		return flow(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 },
@@ -12178,10 +12192,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$1(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();
@@ -12873,6 +12899,46 @@ function liveRunRequest(harness, publicationId, key) {
 	});
 }
 var controlApiConformanceCases = [
+	{
+		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/dist/common/control-api.d.ts

@@ -1,5 +1,5 @@
 import type { CanvasCommand } from './canvas-commands.js';
-import type { FlowStateView, StateScope } from './flow-state.js';
+import type { FlowStateValues, FlowStateView, StateScope } from './flow-state.js';
 export type { CanvasCommand, CanvasCommandSubscriber } from './canvas-commands.js';
 import type { LiveDetails } from './liveDetails.js';
 export { liveEntries } from './liveDetails.js';
@@ -101,6 +101,10 @@ export interface PublicationPresentation {
     readonly version: 1;
     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;
@@ -830,7 +834,7 @@ export declare class ControlClient {
         readonly idempotencyKey?: string;
         readonly tagIds?: readonly string[];
     }): Promise<Flow>;
-    createFlow(name: string, idempotencyKey?: string, teamId?: string, tagIds?: readonly string[]): Promise<Flow>;
+    createFlow(name: string, idempotencyKey?: string, teamId?: string, tagIds?: readonly string[], initialPresentation?: Readonly<Record<string, JsonValue>>): Promise<Flow>;
     broadcastCanvas(flowId: string, command: CanvasCommand): Promise<CanvasBroadcast>;
     getFlow(flowId: string): Promise<Flow>;
     getErrorListeners(flowId: string, signal?: AbortSignal): Promise<readonly ErrorListener[]>;
@@ -843,7 +847,8 @@ export declare class ControlClient {
     deleteTag(tagId: string): Promise<void>;
     setFlowTags(flowId: string, tagIds: readonly string[]): Promise<Flow>;
     updateFlow(flowId: string, changes: FlowUpdate): Promise<Flow>;
-    getFlowState(flowId: string, scope: StateScope, values?: boolean): Promise<FlowStateView>;
+    getFlowState(flowId: string, scope: StateScope): Promise<FlowStateView>;
+    getFlowStateValues(flowId: string, scope: StateScope, keys: readonly string[], signal?: AbortSignal): Promise<FlowStateValues>;
     clearFlowState(flowId: string, scope: StateScope, key?: string): Promise<void>;
     clearFlowDedupe(flowId: string, scope: StateScope, space: string): Promise<void>;
     renameFlow(flowId: string, name: string): Promise<Flow>;