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

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 '../../execution/common/engineContract.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'
@@ -9,12 +11,12 @@ import { decodeLiveDetails } from './liveDetails.ts'
 export { liveEntries } from './liveDetails.ts'
 export { flowInputDefinitions } from './authoringFields.ts'
 export type { LiveDetails, LiveEntry } from './liveDetails.ts'
+import type { ProviderIconAppearance } from '../../connector/common/providerIconSprite.ts'
 import type { AuthoringRead, AuthoringSearch, AuthoringRequest, AuthoringType } from './authoringSchema.ts'
-import type { ProviderIconAppearance } from './providerIconSprite.ts'
 
 import { authoringReadResponse, authoringSearchResponse, authoringEditResponse, authoringCheckResponse } from './authoringSchema.ts'
-export { providerIconAppearance } from './providerIconSprite.ts'
-export type { ProviderIconAppearance, ProviderIconSprite, ProviderIconSpriteCatalog } from './providerIconSprite.ts'
+export { providerIconAppearance } from '../../connector/common/providerIconSprite.ts'
+export type { ProviderIconAppearance, ProviderIconSprite, ProviderIconSpriteCatalog } from '../../connector/common/providerIconSprite.ts'
 export { connectorAccess as decodeConnectorAccess, connectorAccessSnapshot as decodeConnectorAccessSnapshot } from './connectorDecoders.ts'
 import type { ProviderAccessIdentity, ProviderAccessReference } from './providerAccess.ts'
 export {
@@ -35,7 +37,8 @@ export { decodeEventSource, decodeEventSources, type CreateEventSource, type Upd
 import type { TriggerCatalogCache } from './triggerCatalog.ts'
 
 import { decodeTriggerCatalog } from './triggerCatalog.ts'
-export { decodeTriggerCatalog, searchTriggerKeys, type TriggerCatalog, type TriggerCatalogCache, type TriggerDisplay } from './triggerCatalog.ts'
+export { decodeTriggerCatalog, searchTriggerKeys, type TriggerCatalog, type TriggerCatalogCache } from './triggerCatalog.ts'
+export type { TriggerDisplay } from '../../trigger/providers/localization.ts'
 import type { TriggerConfigOption } from '../../trigger/common/configOptions.ts'
 export type { TriggerConfigOption } from '../../trigger/common/configOptions.ts'
 import type { ResultQuery } from './results.ts'
@@ -76,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
@@ -102,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
@@ -676,6 +703,7 @@ export function decodeRunEvent(value: unknown) {
             nodeKind !== 'decision' &&
             nodeKind !== 'openapi' &&
             nodeKind !== 'http-request' &&
+            nodeKind !== 'dedupe' &&
             nodeKind !== 'llm' &&
             nodeKind !== 'agent' &&
             nodeKind !== 'value' &&
@@ -808,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))
@@ -896,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',
       }),
@@ -938,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

@@ -6,10 +6,13 @@ import {
   connectorAgentToolSchema,
   workflowAgentToolSchema,
   connectorCapabilitySchema,
+  httpCapabilitySchema,
   authoringDefinitionSchemas as definitions,
 } from '../../flow/common/changeSchema.ts'
 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'
 
@@ -33,6 +36,7 @@ export const authoringTypes = [
   'decision',
   'openapi',
   'http-request',
+  'dedupe',
   'condition',
   'value',
   'wait',
@@ -71,7 +75,9 @@ const agentTool = z.union([
   workflowAgentToolSchema.omit({ id: true, inputs: true, outputs: true, revisionId: true }).extend({ inputs: toolSources }).strict(),
   connectorAgentToolSchema.omit({ id: true, inputs: true }).extend({ inputs: toolSources }).strict(),
 ])
-const authoringCapabilities = z.array(z.union([connectorCapabilitySchema, z.strictObject({ kind: z.literal('workflow'), name: id, flowId: id })]))
+const authoringCapabilities = z.array(
+  z.union([connectorCapabilitySchema, z.strictObject({ kind: z.literal('workflow'), name: id, flowId: id }), httpCapabilitySchema]),
+)
 const notification = z.strictObject({
   ...definitions.connector.shape,
   messageHandle: id,
@@ -114,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({
@@ -259,6 +266,9 @@ const requestContracts = {
   },
 }
 
+const codeBuiltins = [...findEngineContract(currentEngineContract)!.builtinModules!].filter((name) => !name.startsWith('node:'))
+const codeGuidance = `Code is an ES module whose default export receives (inputs, context) and returns the business outputs. It may import the Node builtins ${codeBuiltins.join(', ')}, with or without the node: prefix; fs is a fresh in-memory filesystem containing /tmp per execution. require, dynamic import, packages and the http/net builtins are unavailable. To call HTTP APIs, declare their hosts in config.capabilities as {kind: "http", hosts: ["api.example.com", "*.example.org"]} and use context.fetch(url, {method, headers, body}); it returns status, ok, headers.get(), text(), json() and bytes(), does not follow redirects, adds no credentials, and limits bodies to 1 MiB. Prefer an HTTP Request node for a single call without transformation and Connector Actions for services with accounts. context provides inputs, signal, getPrevious(), fetch, actions, workflows, artifact, flowId, runId and blockId. Select workflows through config.capabilities: [{kind: "workflow", flowId, name}]. Call context.workflows.call(name, input) and await its business output. The platform derives input/output types. Refresh a selected workflow tool with node.refresh and tool: its name. Calls obey node and Run time limits.`
+
 /** Transport-independent discovery of the same requests the service validates. */
 export function authoringRequestContract(name: string) {
   if (!Object.hasOwn(requestContracts, name)) return undefined
@@ -276,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']
@@ -299,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'
-                                  ? 'Select workflows through config.capabilities: [{kind: "workflow", flowId, name}]. Call context.workflows.call(name, input) and await its business output. The platform derives input/output types. Refresh a selected workflow tool with node.refresh and tool: its name. Calls obey node and Run time limits.'
-                                  : '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',
@@ -323,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/authoringTools.ts

@@ -17,7 +17,7 @@ export type AuthoringCapability = Exclude<TaskCapability, WorkflowCapability> |
 export type WorkflowLookup = (flowId: string) => Promise<WorkflowContract | WorkflowCandidate>
 
 interface ToolIdentity {
-  readonly kind?: 'connector' | 'workflow'
+  readonly kind?: string
   readonly name?: string
   readonly flowId?: string
 }

package/src/control/common/conformance.ts

@@ -4,8 +4,8 @@ import type { ConnectorConnection, CreateEventSource, ResultInfo, PollTriggerTes
 import type { ProviderAccessIdentity } from './providerAccess.ts'
 
 import { dequal } from 'dequal/lite'
-import { currentEngineContract as engineContract } from '../../execution/common/engineContract.ts'
 import { upgradeRevisionContent } from '../../flow/common/change.ts'
+import { currentEngineContract as engineContract } from '../../runtime/common/engineContract.ts'
 import { ControlClient, decodeRunEvent } from './api.ts'
 import { allConnectorConnectionsQuery } from './connectorQueries.ts'
 

package/src/control/common/connectorDecoders.ts

@@ -14,10 +14,10 @@ import type {
   ProviderAccessBindingCandidate,
 } from './api.ts'
 
+import { providerIconAppearance } from '../../connector/common/providerIconSprite.ts'
 import { exact, requiredFields, integer, invalidResponse, jsonValue, record, string } from './decoding.ts'
 import { ApiError } from './errors.ts'
 import { parseProviderAccessSource } from './providerAccess.ts'
-import { providerIconAppearance } from './providerIconSprite.ts'
 
 export function leinaBots(value: unknown): readonly LeinaBot[] {
   const source = record(value)

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/eventSources.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import { eventSourceViewSchema } from '../../event-source/common/view.ts'
 
 const id = z.string().min(1).max(256)
 const eventType = z.string().regex(/^[a-z][a-z0-9_.:]{0,127}$/)
@@ -10,45 +11,17 @@ const eventSourceSchema = z.object({
   revision: z.int().positive(),
   name,
   provider: z.enum(['feishu', 'feishu_app_bot', 'slackbot', 'intercom', 'sentry', 'zoom', 'fireflies', 'jira']),
-  appId: id.nullable(),
-  workspaceId: id.optional(),
-  installationId: id.optional(),
-  organizationId: id.optional(),
-  projectId: id.optional(),
-  projectKey: id.optional(),
-  subscriptionStatus: z.enum(['idle', 'pending', 'ready', 'error']).optional(),
-  lastError: z.string().optional(),
-  signingSecretConfigured: z.boolean().optional(),
+  ...eventSourceViewSchema.shape,
   connectionId: id,
   teamId: id.nullable(),
   enabled: z.boolean(),
   eventTypes: z.array(eventType),
-  manageSubscriptions: z.boolean().nullable(),
-  verificationTokenConfigured: z.boolean().nullable(),
-  encryptKeyConfigured: z.boolean().nullable(),
   endpointUrl: z.string().nullable(),
-  verifiedAt: z.string().nullable(),
   lastReceivedAt: z.string().nullable(),
   updatedAt: z.string(),
   consumers: z.array(z.object({ flowId: id, flowName: z.string(), triggerNodeId: id })),
 })
 
-export const eventSourceViewSchema = eventSourceSchema.pick({
-  appId: true,
-  workspaceId: true,
-  installationId: true,
-  organizationId: true,
-  projectId: true,
-  projectKey: true,
-  subscriptionStatus: true,
-  lastError: true,
-  signingSecretConfigured: true,
-  manageSubscriptions: true,
-  verificationTokenConfigured: true,
-  encryptKeyConfigured: true,
-  verifiedAt: true,
-})
-
 export interface CreateFeishuEventSource {
   readonly kind?: 'feishu'
   readonly version: 1

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/control/common/triggerCatalog.ts

@@ -1,19 +1,12 @@
 import type { TriggerKeySnapshot } from '../../flow/common/change.ts'
 import type { UiLanguage } from '../../localization/common/languages.ts'
+import type { TriggerDisplay } from '../../trigger/providers/localization.ts'
 import type { TriggerKeySummary } from './api.ts'
 
 import { isUiLanguage } from '../../localization/common/languages.ts'
 import { exact, requiredFields, invalidResponse, record, string } from './decoding.ts'
 import { triggerKey } from './triggerDecoders.ts'
 
-export interface TriggerDisplay {
-  readonly configInputs: Readonly<Record<string, string>>
-  readonly configInputLabels: Readonly<Record<string, string>>
-  readonly displayName: string
-  readonly description: string
-  readonly outputs: Readonly<Record<string, string>>
-}
-
 export interface TriggerCatalog {
   readonly version: 3
   readonly locale: UiLanguage

package/src/decision/common/decision.ts

@@ -1,4 +1,4 @@
-import type { InputPort, JsonValue, ManagedTaskDefinition, Port } from '../../flow/common/change.ts'
+import type { InputPort, JsonValue, ManagedTaskDefinitionOf, Port, TaskExecutor } from '../../flow/common/model.ts'
 
 import { dequal } from 'dequal/lite'
 import { matchesSchema } from '../../flow/common/schema.ts'
@@ -18,6 +18,10 @@ export interface DecisionIssue {
   readonly message: string
 }
 
+function isDecisionExecutor(executor: TaskExecutor): executor is DecisionExecutor {
+  return executor.kind === 'decision'
+}
+
 export const decisionModel = 'typesafe/jev'
 export const decisionLimits = { choice: 255, score: 10 } as const
 
@@ -34,8 +38,8 @@ export function limitDecisionQuestions(questions: readonly DecisionQuestion[]):
 }
 
 /** Loading an oversized task also updates its previously generated output schemas. */
-export function limitDecisionTask(task: ManagedTaskDefinition): ManagedTaskDefinition {
-  if (task.executor.kind !== 'decision') return task
+export function limitDecisionTask<Task extends ManagedTaskDefinitionOf<TaskExecutor>>(task: Task): Task {
+  if (!isDecisionExecutor(task.executor)) return task
   const original = task.executor.questions
   const questions = limitDecisionQuestions(original)
   if (questions === original) return task
@@ -45,7 +49,8 @@ export function limitDecisionTask(task: ManagedTaskDefinition): ManagedTaskDefin
     if (index < 0 || original[index] === questions[index] || !dequal(port.jsonSchema, answerSchema(original[index]!))) return port
     return { ...port, jsonSchema: decisionAnswerSchema(questions[index]!) }
   })
-  return { ...task, executor: { ...task.executor, questions }, outputs }
+  // Only the decision executor and its derived outputs change, so the task keeps its own type.
+  return { ...task, executor: { ...task.executor, questions }, outputs } as Task
 }
 export const decisionStateSchema: JsonValue = { type: ['string', 'object', 'array'] }
 const probability: JsonValue = { type: 'number', minimum: 0, maximum: 1 }
@@ -102,7 +107,10 @@ function answerSchema(question: DecisionQuestion): JsonValue {
   return { type: 'object', properties, required: Object.keys(properties) }
 }
 
-export function decisionTask(questions: readonly DecisionQuestion[] = [defaultDecisionQuestion()], name = 'AI Decision'): ManagedTaskDefinition {
+export function decisionTask(
+  questions: readonly DecisionQuestion[] = [defaultDecisionQuestion()],
+  name = 'AI Decision',
+): ManagedTaskDefinitionOf<DecisionExecutor> {
   questions = limitDecisionQuestions(questions)
   const inputs: InputPort[] = [
     { handle: 'target', description: 'Text, object, or array to evaluate across all questions.', jsonSchema: decisionStateSchema, nullable: false },
@@ -111,9 +119,9 @@ export function decisionTask(questions: readonly DecisionQuestion[] = [defaultDe
   return { name, executor: { kind: 'decision', questions }, inputs, outputs }
 }
 
-export function decisionTaskIssues(task: ManagedTaskDefinition): readonly DecisionIssue[] {
+export function decisionTaskIssues(task: ManagedTaskDefinitionOf<TaskExecutor>): readonly DecisionIssue[] {
   task = limitDecisionTask(task)
-  if (task.executor.kind !== 'decision') return []
+  if (!isDecisionExecutor(task.executor)) return []
   const expected = decisionTask(task.executor.questions, task.name)
   return [
     ...decisionQuestionIssues(task.executor.questions),