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

package/dist/common/scheduler.js

@@ -9535,6 +9535,51 @@ 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 dedupeExecutorSchema = strictObject({
+	field: string$1().default(""),
+	mode: _enum(["new", "increasing"]).default("new"),
+	space: _enum(["node", "flow"]).default("node")
+}).extend({ kind: literal("dedupe") });
+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(),
+		mode: _enum(["new", "increasing"]),
+		count: number().nonnegative(),
+		watermark: union([
+			string$1(),
+			number(),
+			_null()
+		]),
+		updatedAt: number()
+	}))
+});
 //#endregion
 //#region src/flow/common/retry.ts
 var retryNodeTypes = [
@@ -9889,7 +9934,8 @@ var managedFields = object({
 			flowId: text,
 			revisionId: text
 		}),
-		httpRequestExecutorSchema
+		httpRequestExecutorSchema,
+		dedupeExecutorSchema
 	])
 });
 var managed = managedFields.transform(limitDecisionTask);
@@ -10143,7 +10189,8 @@ object({
 		literal(9),
 		literal(10),
 		literal(11),
-		literal(12)
+		literal(12),
+		literal(13)
 	]),
 	document,
 	modules: record$1(text, module)
@@ -10551,7 +10598,7 @@ var nodeErrorSchema = {
 	}
 };
 function supportsNodeErrorHandling(node) {
-	return supportsNodeRetry(node);
+	return supportsNodeRetry(node) || node.kind === "task" && "executor" in node.task && node.task.executor.kind === "dedupe";
 }
 function nodeSystemOutputPorts(node) {
 	return supportsNodeErrorHandling(node) && node.onError == "error" ? { error: {
@@ -11580,6 +11627,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));
 					})),
@@ -11994,6 +12042,7 @@ function runGraph(context, target, runId, launchInputs = {}, trigger, resume) {
 			node,
 			jobId,
 			nodeInputs,
+			launchInputs: launch[nodeId],
 			resolution,
 			flowId: target.flowId,
 			runId,

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

@@ -0,0 +1,16 @@
+import type { JsonValue } from './flow-model.js';
+import type { DedupeConfig } 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<{
+        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.77",
   "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
@@ -677,6 +703,7 @@ export function decodeRunEvent(value: unknown) {
             nodeKind !== 'decision' &&
             nodeKind !== 'openapi' &&
             nodeKind !== 'http-request' &&
+            nodeKind !== 'dedupe' &&
             nodeKind !== 'llm' &&
             nodeKind !== 'agent' &&
             nodeKind !== 'value' &&
@@ -809,9 +836,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 +928,23 @@ 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[]): 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 }), version: 1 }),
         headers: { 'idempotency-key': idempotencyKey },
         method: 'POST',
       }),
@@ -939,13 +973,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 { dedupeConfigSchema, dedupeTask } 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 == 'dedupe') {
       const { kind: _kind, ...settings } = task.executor
       config = settings
     } else if (task.executor.kind == 'openapi') {
@@ -521,6 +522,7 @@ 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 == 'http-request') {
         task = httpRequestTask(httpRequestConfigSchema.parse(config), String(update.name), before)
         next = { ...next, inputs: httpRequestInputs(node.inputs, before, task) } as GraphNode
@@ -774,6 +776,9 @@ 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))
+              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 { dedupeTask } from '../../state/common/state.ts'
 
 const descriptions = {
   'start': 'A Start node with a required message parameter. Supply it through trigger.outputs.',
@@ -23,6 +24,7 @@ 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.',
   '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 +59,12 @@ export function authoringExample(name: string): { version: 1; operations: readon
         { name: 'needs_support', type: 'noul', instructions: 'Does the customer need support?' },
       ])
       break
+    case 'dedupe':
+      operations = [
+        ...createManagedTask({ nodeId: 'dedupe' }, dedupeTask()),
+        { kind: 'graph.node.input.set', nodeId: 'dedupe', 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 { dedupeConfigSchema } 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',
+  'dedupe',
   'condition',
   'value',
   'wait',
@@ -118,6 +120,7 @@ export const authoringConfigurations = {
   'connector': definitions.connector.omit({ outputMode: true }).strict(),
   'openapi': authoringOpenApiSchema,
   'http-request': httpRequestConfigSchema,
+  'dedupe': dedupeConfigSchema,
   '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 == 'dedupe' || 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 == '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 == '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>' } },
+              'dedupe': { config: { field: 'id', mode: 'new', space: 'node' }, 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/errors.ts

@@ -42,6 +42,9 @@ export const controlErrorCode = {
   triggerKeyInvalid: 'trigger-key.invalid',
   triggerKeyNotFound: 'trigger-key.not-found',
   triggerNotFound: 'trigger.not-found',
+  tagInvalid: 'tag.invalid',
+  tagConflict: 'tag.conflict',
+  tagNotFound: 'tag.not-found',
   variableInvalid: 'variable.invalid',
   variableLimitReached: 'variable.limit-reached',
   variableNotFound: 'variable.not-found',
@@ -93,6 +96,9 @@ export const controlErrorMetadata = {
   [controlErrorCode.triggerKeyInvalid]: { status: 409 },
   [controlErrorCode.triggerKeyNotFound]: { status: 404 },
   [controlErrorCode.triggerNotFound]: { status: 404 },
+  [controlErrorCode.tagInvalid]: { status: 400 },
+  [controlErrorCode.tagConflict]: { status: 409 },
+  [controlErrorCode.tagNotFound]: { status: 404 },
   [controlErrorCode.variableInvalid]: { status: 400 },
   [controlErrorCode.variableLimitReached]: { status: 409 },
   [controlErrorCode.variableNotFound]: { status: 404 },

package/src/control/common/flowDecoders.ts

@@ -60,6 +60,7 @@ export function flow(value: unknown): Flow {
             revisionId: string(target.revisionId),
           },
         }),
+    tagIds: source.tagIds === undefined ? [] : strings(source.tagIds),
     createdAt: string(source.createdAt),
     ...(source.connectorTeamId == null ? {} : { connectorTeamId: string(source.connectorTeamId) }),
     draftRevisionId: string(source.draftRevisionId),

package/src/control/common/mcp.ts

@@ -5,6 +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 { authoringReadSchema, authoringSearchSchema, authoringRequestSchema, authoringSchemaQuery } from './authoringSchema.ts'
 import { resultQuerySchema } from './resultQuery.ts'
 
@@ -50,6 +51,21 @@ 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.',
+    stateQuerySchema.extend({ flowId: flow }),
+    true,
+  ),
+  flow_state_clear: tool(
+    'Delete one business state key or clear all business values. Explicit draft/live scope is required; live changes production state immediately.',
+    stateClearSchema.extend({ flowId: flow }),
+    false,
+  ),
+  flow_dedupe_clear: tool(
+    'Clear one deduplication space (flow or node:<id>). Explicit draft/live scope is required; live changes production history immediately.',
+    dedupeClearSchema.extend({ flowId: flow }),
+    false,
+  ),
   flow_canvas: tool(
     'Broadcast a transient canvas command to connected Workbenches viewing this Flow. Success only confirms Server broadcast, not delivery or execution. No replay, session selection or Presentation save. Pan uses screen pixels (positive right/down); zoom is an absolute ratio (0.1–3); fit includes all nodes. Repeating pan moves again.',
     z.strictObject({ flowId: flow, command: canvasCommandSchema }),

package/src/control/common/requests.ts

@@ -18,6 +18,8 @@ const json: z.ZodType<JsonValue> = z.json()
 const id = z.string().min(1)
 const version = z.literal(1)
 const flowName = id.refine((value) => value == value.trim() && resourceNameIssue(value) == null, 'Flow name is invalid.')
+const tagIds = z.array(id).transform((ids) => [...new Set(ids)].toSorted())
+const tagName = id.transform((name) => name.trim()).refine((name) => resourceNameIssue(name) == null, 'Tag name is invalid.')
 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 = {
@@ -31,8 +33,11 @@ const schemas = {
   createEventSource: createEventSourceSchema,
   updateEventSource: updateEventSourceSchema,
   eventSourceRevision: eventSourceRevisionSchema,
-  importFlow: z.strictObject({ file: json, name: flowName.optional(), teamId: id.optional(), version }),
-  createFlow: z.strictObject({ name: flowName, teamId: id.optional(), version }),
+  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 }),
+  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 })]),
   renameFlow: z.strictObject({ name: flowName, version }),
   changeDraft: z.strictObject({ expectedRevisionId: id, operations: z.array(json).min(1), version }),
   repairDraft: z.strictObject({ expectedRevisionId: id, version }),
@@ -79,6 +84,9 @@ export const controlRequests = {
   eventSourceRevision: decoder(schemas.eventSourceRevision),
   importFlow: decoder(schemas.importFlow),
   createFlow: decoder(schemas.createFlow),
+  saveTag: decoder(schemas.saveTag),
+  setFlowTags: decoder(schemas.setFlowTags),
+  updateFlow: decoder(schemas.updateFlow),
   renameFlow: decoder(schemas.renameFlow),
   changeDraft(value: unknown): { expectedRevisionId: string; operations: readonly DraftOperation[]; version: 1 } {
     const body = schemas.changeDraft.parse(value)

package/src/control/common/tags.ts

@@ -0,0 +1,20 @@
+import type { FlowQuery, Tag, TagListItem } from './api.ts'
+
+import { integer, invalidResponse, record, string } from './decoding.ts'
+
+export function normalizeFlowQuery(query: FlowQuery = {}): Required<FlowQuery> {
+  return { query: query.query?.trim().toLowerCase() ?? '', tagIds: [...new Set(query.tagIds ?? [])].toSorted(), untagged: query.untagged ?? false }
+}
+
+export function decodeTag(value: unknown): Tag {
+  const source = record(value)
+  if (source.version != 1) return invalidResponse()
+  return { tagId: string(source.tagId), name: string(source.name), version: 1 }
+}
+
+export function decodeTagListItem(value: unknown): TagListItem {
+  const source = record(value)
+  const referenceCount = integer(source.referenceCount)
+  if (referenceCount < 0) return invalidResponse()
+  return { ...decodeTag(source), referenceCount }
+}

package/src/execution/common/events.ts

@@ -23,6 +23,7 @@ const nodeKinds = new Set([
   'javascript',
   'openapi',
   'http-request',
+  'dedupe',
   'llm',
   'value',
   'wait',
@@ -56,6 +57,7 @@ function nodeKind(
   | 'javascript'
   | 'openapi'
   | 'http-request'
+  | 'dedupe'
   | 'llm'
   | 'value'
   | 'wait'
@@ -76,6 +78,7 @@ function nodeKind(
     | 'javascript'
     | 'openapi'
     | 'http-request'
+    | 'dedupe'
     | 'llm'
     | 'value'
     | 'wait'

package/src/execution/common/node-execution.ts

@@ -109,6 +109,7 @@ function nodeKind(
   | 'javascript'
   | 'openapi'
   | 'http-request'
+  | 'dedupe'
   | 'llm'
   | 'value'
   | 'wait'
@@ -301,6 +302,7 @@ export function executeNode(
     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
@@ -368,6 +370,7 @@ export function executeNode(
               if (additional.has(handle)) return false
               const task = 'executor' in node.task ? node.task : undefined
               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' &&

package/src/execution/common/scheduler.ts

@@ -70,6 +70,7 @@ export type SchedulerEvent =
         | 'javascript'
         | 'openapi'
         | 'http-request'
+        | 'dedupe'
         | 'llm'
         | 'value'
         | 'wait'
@@ -344,6 +345,7 @@ function runGraph(
           node,
           jobId,
           nodeInputs,
+          launchInputs: launch[nodeId],
           resolution,
           flowId: target.flowId,
           runId,