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

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

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

package/dist/common/scheduler.d.ts

@@ -33,7 +33,7 @@ export type SchedulerEvent = {
     readonly inputs: Readonly<Record<string, JsonValue>>;
     readonly jobId: string;
     readonly nodeId: string;
-    readonly nodeKind: 'agent' | 'approval' | 'condition' | 'connector' | 'decision' | 'javascript' | 'openapi' | 'http-request' | 'llm' | 'value' | 'wait' | 'outputs' | 'workflow' | 'webhook-response';
+    readonly nodeKind: 'agent' | 'approval' | 'condition' | 'connector' | 'decision' | 'javascript' | 'openapi' | 'http-request' | '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,6 +9535,43 @@ var httpRequestExecutorSchema = strictObject({
 	]).default("auto"),
 	statusPolicy: _enum(["success", "all"]).default("success")
 }).extend({ kind: literal("http-request") });
+strictObject({
+	scope: _enum(["draft", "live"]),
+	values: boolean().optional()
+});
+strictObject({
+	scope: _enum(["draft", "live"]),
+	key: string$1().min(1).refine((key) => new TextEncoder().encode(key).length <= 256).optional()
+});
+strictObject({
+	scope: _enum(["draft", "live"]),
+	space: string$1().regex(/^(flow|node:.+)$/)
+});
+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"]),
+	limits: object({
+		maxValueBytes: number().positive(),
+		maxValues: number().int().positive(),
+		maxSpaces: number().int().positive(),
+		maxIdentities: number().positive(),
+		maxRunWrites: number().positive()
+	}),
+	values: array(object({
+		key: string$1(),
+		size: number().nonnegative(),
+		updatedAt: number(),
+		value: json$1().optional()
+	})),
+	spaces: array(object({
+		space: string$1(),
+		count: number().nonnegative(),
+		pendingCount: number().nonnegative(),
+		reservedCount: number().nonnegative(),
+		updatedAt: number()
+	}))
+});
 //#endregion
 //#region src/flow/common/retry.ts
 var retryNodeTypes = [
@@ -9889,7 +9926,8 @@ var managedFields = object({
 			flowId: text,
 			revisionId: text
 		}),
-		httpRequestExecutorSchema
+		httpRequestExecutorSchema,
+		skipDuplicatesExecutorSchema
 	])
 });
 var managed = managedFields.transform(limitDecisionTask);
@@ -10143,7 +10181,8 @@ object({
 		literal(9),
 		literal(10),
 		literal(11),
-		literal(12)
+		literal(12),
+		literal(13)
 	]),
 	document,
 	modules: record$1(text, module)
@@ -10551,7 +10590,7 @@ var nodeErrorSchema = {
 	}
 };
 function supportsNodeErrorHandling(node) {
-	return supportsNodeRetry(node);
+	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: {
@@ -11580,6 +11619,7 @@ function executeNode(context, input) {
 						if (additional.has(handle)) return false;
 						const task = "executor" in node.task ? node.task : void 0;
 						if (task == null || !["openapi", "http-request"].includes(task.executor.kind)) return true;
+						if (Object.hasOwn(input.launchInputs ?? {}, handle)) return true;
 						const mapping = node.inputs[handle];
 						return mapping?.kind != "unset" && (mapping != null || task.inputs.some((port) => "handle" in port && port.handle == handle && port.value !== void 0));
 					})),
@@ -11949,6 +11989,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]);
@@ -11994,6 +12036,7 @@ function runGraph(context, target, runId, launchInputs = {}, trigger, resume) {
 			node,
 			jobId,
 			nodeInputs,
+			launchInputs: launch[nodeId],
 			resolution,
 			flowId: target.flowId,
 			runId,
@@ -12165,10 +12208,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);
@@ -12203,7 +12253,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);
 		}
@@ -12241,6 +12291,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)
@@ -12291,7 +12343,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

@@ -0,0 +1,16 @@
+import type { JsonValue } from './flow-model.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 Skip Duplicates node across Runs, updating its business config and items. */
+    skipDuplicates(config: SkipDuplicatesConfig, items: JsonValue[]): Promise<{
+        items: JsonValue[];
+        duplicates: JsonValue[];
+    }>;
+}
+export declare const stateConformanceCases: readonly {
+    name: string;
+    verify(harness: StateConformanceHarness): Promise<void>;
+}[];

package/dist/common/tags.d.ts

@@ -0,0 +1,4 @@
+import type { FlowQuery, Tag, TagListItem } from './control-api.js';
+export declare function normalizeFlowQuery(query?: FlowQuery): Required<FlowQuery>;
+export declare function decodeTag(value: unknown): Tag;
+export declare function decodeTagListItem(value: unknown): TagListItem;

package/dist/index.d.ts

@@ -102,6 +102,17 @@ export interface TaskContext<Actions extends object = Record<string, never>, Wor
     readonly inputs: Readonly<Record<string, unknown>>;
     readonly runId: string;
     readonly blockId: string;
+    readonly state: {
+        get(key: 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>;
+        list(): Promise<string[]>;
+    };
+    readonly dedupe: {
+        insert(ids: readonly (string | number)[]): Promise<boolean[]>;
+        has(ids: readonly (string | number)[]): Promise<boolean[]>;
+    };
     readonly artifact: ArtifactCapability;
     /** Reads the selected direct predecessors, sorted by node ID; empty for a graph root. */
     getPrevious(): Promise<readonly PreviousNode[]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oomol-lab/open-flow",
-  "version": "0.1.0-beta.76",
+  "version": "0.1.0-beta.78",
   "description": "TypeScript contracts and Browser runtime for Open Flow.",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
@@ -25,6 +25,10 @@
       "types": "./dist/common/decision.d.ts",
       "import": "./dist/common/decision.js"
     },
+    "./flow-state": {
+      "types": "./dist/common/flow-state.d.ts",
+      "import": "./dist/common/flow-state.js"
+    },
     "./http-request": {
       "types": "./dist/common/http-request.d.ts",
       "import": "./dist/common/http-request.js"

package/src/control/common/api.ts

@@ -1,6 +1,8 @@
 import type { CanvasCommand } from '../../canvas/common/commands.ts'
+import type { FlowStateView, StateScope } from '../../state/common/state.ts'
 
 import { currentEngineContract } from '../../runtime/common/engineContract.ts'
+import { 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'
@@ -77,6 +79,8 @@ export type { FlowCatalogEvent, FlowChangeEvent } from './flowNotifications.ts'
 
 import { ApiError } from './errors.ts'
 import { randomId } from './random.ts'
+import { decodeTag, decodeTagListItem, normalizeFlowQuery } from './tags.ts'
+export { normalizeFlowQuery } from './tags.ts'
 
 export interface CanvasBroadcast {
   readonly version: 1
@@ -103,7 +107,29 @@ export interface FlowResources {
   }
 }
 
+export interface FlowUpdate {
+  readonly name?: string
+  readonly tagIds?: readonly string[]
+}
+
+export interface FlowQuery {
+  readonly query?: string
+  readonly tagIds?: readonly string[]
+  readonly untagged?: boolean
+}
+
+export interface Tag {
+  readonly tagId: string
+  readonly name: string
+  readonly version: 1
+}
+
+export interface TagListItem extends Tag {
+  readonly referenceCount: number
+}
+
 export interface Flow {
+  readonly tagIds?: readonly string[]
   readonly live?: { readonly enabled: boolean; readonly hasStart: boolean; readonly publicationId: string; readonly revisionId: string }
 
   readonly createdAt: string
@@ -123,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
@@ -677,6 +708,7 @@ export function decodeRunEvent(value: unknown) {
             nodeKind !== 'decision' &&
             nodeKind !== 'openapi' &&
             nodeKind !== 'http-request' &&
+            nodeKind !== 'skip-duplicates' &&
             nodeKind !== 'llm' &&
             nodeKind !== 'agent' &&
             nodeKind !== 'value' &&
@@ -809,9 +841,13 @@ export class ControlClient {
   }
 
   async listFlows(
-    options: { readonly cursor?: string; readonly includeTotal?: boolean; readonly limit?: number; readonly signal?: AbortSignal } = {},
+    options: FlowQuery & { readonly cursor?: string; readonly includeTotal?: boolean; readonly limit?: number; readonly signal?: AbortSignal } = {},
   ): Promise<FlowPage> {
     const parameters = new URLSearchParams()
+    const filter = normalizeFlowQuery(options)
+    if (filter.query) parameters.set('query', filter.query)
+    if (filter.tagIds.length) parameters.set('tagIds', filter.tagIds.join(','))
+    if (filter.untagged) parameters.set('untagged', 'true')
     if (options.cursor != null) parameters.set('cursor', options.cursor)
     if (options.limit != null) parameters.set('limit', String(options.limit))
     if (options.includeTotal != null) parameters.set('includeTotal', String(options.includeTotal))
@@ -897,20 +933,35 @@ export class ControlClient {
     }
   }
 
-  async importFlow(file: WorkflowFile, options: { readonly name?: string; readonly teamId?: string; readonly idempotencyKey?: string } = {}): Promise<Flow> {
+  async importFlow(
+    file: WorkflowFile,
+    options: { readonly name?: string; readonly teamId?: string; readonly idempotencyKey?: string; readonly tagIds?: readonly string[] } = {},
+  ): Promise<Flow> {
     return flow(
       await this.request('/v1/flows/import', {
         method: 'POST',
         headers: { 'Idempotency-Key': options.idempotencyKey ?? `flow-${randomId()}` },
-        body: JSON.stringify({ file, name: options.name, teamId: options.teamId, version: 1 }),
+        body: JSON.stringify({ file, name: options.name, teamId: options.teamId, tagIds: options.tagIds, version: 1 }),
       }),
     )
   }
 
-  async createFlow(name: string, idempotencyKey = `flow-${randomId()}`, teamId?: 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 }), version: 1 }),
+        body: JSON.stringify({
+          name,
+          ...(teamId == null ? {} : { teamId }),
+          ...(tagIds == null ? {} : { tagIds }),
+          ...(initialPresentation == null ? {} : { presentation: initialPresentation }),
+          version: 1,
+        }),
         headers: { 'idempotency-key': idempotencyKey },
         method: 'POST',
       }),
@@ -939,13 +990,52 @@ export class ControlClient {
     return source.listeners.map(errorListener)
   }
 
-  async renameFlow(flowId: string, name: string): Promise<Flow> {
-    return flow(
-      await this.request(`/v1/flows/${segment(flowId)}`, {
-        body: JSON.stringify({ name, version: 1 }),
-        method: 'PATCH',
-      }),
+  async listTags(signal?: AbortSignal): Promise<{ readonly tags: readonly TagListItem[]; readonly version: 1 }> {
+    const source = record(await this.request('/v1/tags', { signal }))
+    if (source.version != 1 || !Array.isArray(source.tags)) return invalidResponse()
+    return { tags: source.tags.map(decodeTagListItem), version: 1 }
+  }
+
+  async createTag(name: string): Promise<Tag> {
+    return decodeTag(await this.request('/v1/tags', { method: 'POST', body: JSON.stringify({ name, version: 1 }) }))
+  }
+
+  async renameTag(tagId: string, name: string): Promise<Tag> {
+    return decodeTag(await this.request(`/v1/tags/${segment(tagId)}`, { method: 'PATCH', body: JSON.stringify({ name, version: 1 }) }))
+  }
+
+  async deleteTag(tagId: string): Promise<void> {
+    const source = record(await this.request(`/v1/tags/${segment(tagId)}`, { method: 'DELETE' }))
+    if (source.version != 1) invalidResponse()
+  }
+
+  async setFlowTags(flowId: string, tagIds: readonly string[]): Promise<Flow> {
+    return flow(await this.request(`/v1/flows/${segment(flowId)}/tags`, { method: 'PUT', body: JSON.stringify({ tagIds, version: 1 }) }))
+  }
+
+  async updateFlow(flowId: string, changes: FlowUpdate): Promise<Flow> {
+    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}`))
+    return result.success && result.data.scope === scope ? 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' }),
     )
+    if (source.version !== 1 || source.cleared !== true) invalidResponse()
+  }
+
+  async clearFlowDedupe(flowId: string, scope: StateScope, space: string): Promise<void> {
+    const source = record(await this.request(`/v1/flows/${segment(flowId)}/dedupe?scope=${scope}&space=${encodeURIComponent(space)}`, { method: 'DELETE' }))
+    if (source.version !== 1 || source.cleared !== true) invalidResponse()
+  }
+
+  async renameFlow(flowId: string, name: string): Promise<Flow> {
+    return this.updateFlow(flowId, { name })
   }
 
   async deleteFlow(flowId: string): Promise<Flow> {

package/src/control/common/authoring.ts

@@ -43,6 +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 { 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'
@@ -146,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') {
+    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') {
@@ -521,6 +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 == '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
@@ -774,6 +777,9 @@ export async function compileAuthoring(base: RevisionContent, request: Authoring
             case 'connector':
               changes = createManagedTask(identity, await connectorTask(config, name))
               break
+            case 'skip-duplicates':
+              changes = createManagedTask(identity, skipDuplicatesTask(skipDuplicatesConfigSchema.parse(config), name))
+              break
             case 'http-request':
               changes = createManagedTask(identity, httpRequestTask(httpRequestConfigSchema.parse(config), name))
               break

package/src/control/common/authoringExamples.ts

@@ -13,6 +13,7 @@ import {
 } from '../../flow/common/nodeChanges.ts'
 import { httpRequestTask } from '../../http/common/httpRequest.ts'
 import { openApiTask, selectOperation } from '../../openapi/common/openapi.ts'
+import { skipDuplicatesTask } from '../../state/common/state.ts'
 
 const descriptions = {
   'start': 'A Start node with a required message parameter. Supply it through trigger.outputs.',
@@ -23,6 +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.',
+  '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':
@@ -57,6 +60,12 @@ export function authoringExample(name: string): { version: 1; operations: readon
         { name: 'needs_support', type: 'noul', instructions: 'Does the customer need support?' },
       ])
       break
+    case 'skip-duplicates':
+      operations = [
+        ...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':
       operations = [
         ...createManagedTask({ nodeId: 'http' }, httpRequestTask()),

package/src/control/common/authoringSchema.ts

@@ -12,6 +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 { skipDuplicatesConfigSchema } from '../../state/common/state.ts'
 import { authoringLlmConfiguration } from './authoringLlm.ts'
 import { authoringOpenApiSchema } from './authoringOpenApi.ts'
 
@@ -35,6 +36,7 @@ export const authoringTypes = [
   'decision',
   'openapi',
   'http-request',
+  'skip-duplicates',
   'condition',
   'value',
   'wait',
@@ -118,6 +120,7 @@ export const authoringConfigurations = {
   'connector': definitions.connector.omit({ outputMode: true }).strict(),
   'openapi': authoringOpenApiSchema,
   'http-request': httpRequestConfigSchema,
+  'skip-duplicates': skipDuplicatesConfigSchema,
   'agent': definitions.agent
     .omit({ prompt: true, tools: true })
     .extend({
@@ -283,7 +286,7 @@ export function authoringSchema(kind?: AuthoringType) {
       }
     : {
         type: kind,
-        onError: 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']
@@ -306,17 +309,19 @@ 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 == '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'
-                            ? 'Select an operation; the tool resolves its ports and authentication. Read authenticationChoices from node details. authentication is replaced as a complete choice. Bind advertised credentials through inputs.'
-                            : kind == 'workflow'
-                              ? 'Select another workflow with config.flowId. A workflow cannot call itself, including in a disconnected node. Owned unpublished or unavailable targets may be saved as incomplete drafts. Use node.refresh to load the current published interface.'
-                              : kind == 'agent'
-                                ? 'Tools accept Connector Actions or {kind: "workflow", flowId, name, description, approval, inputs}. Workflow parameter sources use model, input or value. The platform derives the interface. Refresh a workflow tool with node.refresh and tool: its name.'
-                                : kind == 'code'
-                                  ? codeGuidance
-                                  : 'Supply business configuration and input data. Fixed definitions are assembled by the tool. Existing constraints and defaults are preserved on partial updates.',
+                        : 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'
+                              ? 'Select an operation; the tool resolves its ports and authentication. Read authenticationChoices from node details. authentication is replaced as a complete choice. Bind advertised credentials through inputs.'
+                              : kind == 'workflow'
+                                ? 'Select another workflow with config.flowId. A workflow cannot call itself, including in a disconnected node. Owned unpublished or unavailable targets may be saved as incomplete drafts. Use node.refresh to load the current published interface.'
+                                : kind == 'agent'
+                                  ? 'Tools accept Connector Actions or {kind: "workflow", flowId, name, description, approval, inputs}. Workflow parameter sources use model, input or value. The platform derives the interface. Refresh a workflow tool with node.refresh and tool: its name.'
+                                  : kind == 'code'
+                                    ? codeGuidance
+                                    : 'Supply business configuration and input data. Fixed definitions are assembled by the tool. Existing constraints and defaults are preserved on partial updates.',
         example: {
           op: 'node.add',
           as: 'step',
@@ -330,6 +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>' } },
+              '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' } } },