@oomol-lab/open-flow 0.1.0-beta.80 → 0.1.0-beta.82

package/dist/render/node/licenses.md

@@ -0,0 +1,75 @@
+# Licenses
+
+The app bundles dependencies which contain the following licenses:
+
+## @wopjs/cast - 0.1.16 (MIT)
+
+MIT License
+
+Copyright (c) 2026 wopjs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## dequal - 2.0.3 (MIT)
+
+The MIT License (MIT)
+
+Copyright (c) Luke Edwards <luke.edwards05@gmail.com> (lukeed.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+## zod - 4.6.5 (MIT)
+
+MIT License
+
+Copyright (c) 2025 Colin McDonnell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oomol-lab/open-flow",
-  "version": "0.1.0-beta.80",
+  "version": "0.1.0-beta.82",
   "description": "TypeScript contracts and Browser runtime for Open Flow.",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
@@ -141,6 +141,10 @@
       "types": "./dist/browser/preview.css.d.ts",
       "default": "./dist/browser/preview.css"
     },
+    "./render": {
+      "types": "./dist/render/node/index.d.ts",
+      "import": "./dist/render/node/index.js"
+    },
     "./workbench": {
       "types": "./dist/browser/workbench.d.ts",
       "import": "./dist/browser/workbench.js"
@@ -174,7 +178,13 @@
     "effect": "4.0.0-rc.112",
     "zod": "^4.6.5",
     "react": "^18.3.1 || ^19.0.0",
-    "react-dom": "^18.3.1 || ^19.0.0"
+    "react-dom": "^18.3.1 || ^19.0.0",
+    "playwright-core": "^1.64.1"
+  },
+  "peerDependenciesMeta": {
+    "playwright-core": {
+      "optional": true
+    }
   },
   "sideEffects": [
     "**/*.css"

package/src/connector/common/actionContract.ts

@@ -0,0 +1,26 @@
+import type { JsonValue } from '../../types/index.ts'
+
+interface ConnectorActionContract {
+  readonly inputConstraints?: readonly {
+    readonly handle: string
+    readonly jsonSchema: JsonValue
+    readonly code: string
+    readonly message: string
+  }[]
+  readonly pendingMessageInput?: string
+}
+
+/** These rules also apply to existing Revision snapshots without a catalog lookup. */
+export const connectorActionContracts: Readonly<Record<string, ConnectorActionContract | undefined>> = {
+  'leina.send_notification': {
+    inputConstraints: [
+      {
+        handle: 'leinaId',
+        jsonSchema: { type: 'string', pattern: '\\S' },
+        code: 'leina.robot-required',
+        message: 'Select a Leina robot or bind its identifier to an input source.',
+      },
+    ],
+    pendingMessageInput: 'message',
+  },
+}

package/src/control/common/api.ts

@@ -55,10 +55,13 @@ export {
   type ResultQuery,
 } from './results.ts'
 import type { RunStatus } from '../../execution/common/runLifecycle.ts'
+import type { WorkflowBundle, WorkflowExportPreview } from '../../flow/common/workflowBundle.ts'
 import type { WorkflowFile } from '../../flow/common/workflowFile.ts'
 
+import { decodeWorkflowExportPreview, workflowBundleFromPreview } from '../../flow/common/workflowBundle.ts'
 import { decodeWorkflowFile } from '../../flow/common/workflowFile.ts'
 export type { WorkflowFile, WorkflowCleanupSummary } from '../../flow/common/workflowFile.ts'
+export type { WorkflowBundle, WorkflowExportPreview } from '../../flow/common/workflowBundle.ts'
 import type { InputPortDefinition, JsonValue, PortDefinition, RevisionContent, TriggerKeySnapshot, WaitAction } from '../../flow/common/change.ts'
 import type { FlowResourceReferences } from '../../flow/common/semantics.ts'
 
@@ -109,9 +112,26 @@ export interface FlowResources {
 
 export interface FlowUpdate {
   readonly name?: string
+  readonly icon?: string | null
+  readonly description?: string | null
   readonly tagIds?: readonly string[]
 }
 
+export interface WorkflowBundleImportResult {
+  readonly version: 1
+  readonly flow: Flow
+  readonly flows: readonly Flow[]
+}
+
+export function decodeWorkflowBundleImportResult(value: unknown): WorkflowBundleImportResult {
+  const source = record(value)
+  if (source.version != 1 || !Array.isArray(source.flows) || source.flows.length == 0) return invalidResponse()
+  const entry = flow(source.flow)
+  const flows = source.flows.map(flow)
+  if (new Set(flows.map((item) => item.flowId)).size != flows.length || !flows.some((item) => item.flowId == entry.flowId)) return invalidResponse()
+  return { version: 1, flow: entry, flows }
+}
+
 export interface FlowQuery {
   readonly query?: string
   readonly tagIds?: readonly string[]
@@ -139,6 +159,8 @@ export interface Flow {
   /** Connector Team scope used by the OOMOL resource cache. */
   readonly connectorTeamId?: string
   readonly name: string
+  readonly icon?: string
+  readonly description?: string
   readonly status: 'active' | 'retiring'
   readonly updatedAt: string
   readonly version: 1
@@ -933,6 +955,34 @@ export class ControlClient {
     }
   }
 
+  async getFlowExportPreview(flowId: string): Promise<WorkflowExportPreview> {
+    const value = await this.request(`/v1/flows/${segment(flowId)}/export-preview`)
+    try {
+      return decodeWorkflowExportPreview(value)
+    } catch {
+      return invalidResponse()
+    }
+  }
+
+  async exportFlowBundle(flowId: string): Promise<WorkflowBundle> {
+    const preview = await this.getFlowExportPreview(flowId)
+    if (preview.unavailableFlowIds.length) throw new ApiError(400, 'flow.invalid', 'Some referenced workflows are unavailable.')
+    return workflowBundleFromPreview(preview)
+  }
+
+  async importFlowBundle(
+    file: WorkflowBundle,
+    options: { readonly name?: string; readonly teamId?: string; readonly idempotencyKey?: string; readonly tagIds?: readonly string[] } = {},
+  ): Promise<WorkflowBundleImportResult> {
+    return decodeWorkflowBundleImportResult(
+      await this.request('/v1/flows/import-bundle', {
+        method: 'POST',
+        headers: { 'Idempotency-Key': options.idempotencyKey ?? `flow-${randomId()}` },
+        body: JSON.stringify({ file, name: options.name, teamId: options.teamId, tagIds: options.tagIds, version: 1 }),
+      }),
+    )
+  }
+
   async importFlow(
     file: WorkflowFile,
     options: { readonly name?: string; readonly teamId?: string; readonly idempotencyKey?: string; readonly tagIds?: readonly string[] } = {},

package/src/control/common/flowDecoders.ts

@@ -67,6 +67,8 @@ export function flow(value: unknown): Flow {
     resourceReferences: resourceReferences(source.resourceReferences),
     flowId: string(source.flowId),
     name: string(source.name),
+    ...(source.icon === undefined ? {} : { icon: string(source.icon) }),
+    ...(source.description === undefined ? {} : { description: string(source.description) }),
     status: status as Flow['status'],
     updatedAt: string(source.updatedAt),
     version: 1,

package/src/control/common/mcp.ts

@@ -103,13 +103,13 @@ export const mcpTools = {
     true,
   ),
   flow_export: tool(
-    'Export the current draft as a shareable workflow JSON file. Structured external references are cleared. Literal secrets in code, prompts or business JSON remain; review before sharing.',
-    z.strictObject({ flowId: flow }),
+    'Export the current draft as shareable workflow JSON. Set includeDependencies to bundle all referenced drafts. Structured external references are cleared. Literal secrets in code, prompts or business JSON remain; review before sharing.',
+    z.strictObject({ flowId: flow, includeDependencies: z.boolean().optional() }),
     true,
   ),
   flow_import: tool(
-    'Import workflow JSON as a new unpublished draft. External references are cleared and must be configured again. Keep identical arguments and idempotencyKey when retrying.',
-    z.strictObject({ file: json, name: id.optional(), teamId: id.optional(), idempotencyKey: mutationKey }),
+    'Import workflow JSON or a bundle as new unpublished drafts. tagIds apply to every imported workflow. External references are cleared and must be configured again. Keep identical arguments and idempotencyKey when retrying.',
+    z.strictObject({ file: json, name: id.optional(), teamId: id.optional(), tagIds: z.array(id).optional(), idempotencyKey: mutationKey }),
     false,
   ),
   flow_create: tool(

package/src/control/common/requests.ts

@@ -45,7 +45,18 @@ const schemas = {
   }),
   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 })]),
+  updateFlow: z
+    .strictObject({
+      name: flowName.optional(),
+      icon: z.string().nullable().optional(),
+      description: z.string().nullable().optional(),
+      tagIds: tagIds.optional(),
+      version,
+    })
+    .refine(
+      (value) => value.name !== undefined || value.icon !== undefined || value.description !== undefined || value.tagIds !== undefined,
+      'Flow settings are empty.',
+    ),
   renameFlow: z.strictObject({ name: flowName, version }),
   changeDraft: z.strictObject({ expectedRevisionId: id, operations: z.array(json).min(1), version }),
   repairDraft: z.strictObject({ expectedRevisionId: id, version }),

package/src/flow/common/edgeChanges.ts

@@ -1,6 +1,7 @@
 import type { ChangeOperation, GraphEdge, RevisionContent } from './change.ts'
 
 import { dequal } from 'dequal/lite'
+import { connectorActionContracts } from '../../connector/common/actionContract.ts'
 
 export function connect(content: RevisionContent, edge: GraphEdge): readonly ChangeOperation[] {
   const selected = content.document.graph
@@ -8,20 +9,22 @@ export function connect(content: RevisionContent, edge: GraphEdge): readonly Cha
   const changes: ChangeOperation[] = [{ edge, kind: 'graph.edge.connect' }]
   const source = selected.nodes[edge.source]
   const target = selected.nodes[edge.target]
+  const messageInput =
+    target?.kind == 'task' && 'executor' in target.task && target.task.executor.kind == 'connector'
+      ? connectorActionContracts[target.task.executor.action]?.pendingMessageInput
+      : undefined
   if (
     edge.sourceHandle == 'pending' &&
     (source?.kind == 'approval' || source?.kind == 'wait') &&
     target?.kind == 'task' &&
-    'executor' in target.task &&
-    target.task.executor.kind == 'connector' &&
-    target.task.executor.action == 'leina.send_notification' &&
-    (target.inputs.message == null || target.inputs.message.kind == 'unset')
+    messageInput != null &&
+    (target.inputs[messageInput] == null || target.inputs[messageInput]?.kind == 'unset')
   ) {
     changes.push({
       kind: 'graph.node.input.set',
       nodeId: edge.target,
-      handle: 'message',
-      before: target.inputs.message,
+      handle: messageInput,
+      before: target.inputs[messageInput],
       value: { kind: 'sources', sources: [{ kind: 'node', nodeId: edge.source, output: 'pending', field: 'message' }] },
     })
   }

package/src/flow/common/encoding.ts

@@ -21,6 +21,7 @@ import type {
 import { isTriggerNode, currentFlowModelVersion } from '@oomol-lab/open-flow/flow-change'
 import { decodeRevisionEnvelope, repairRevisionEnvelope } from './changeSchema.ts'
 export * from './workflowFile.ts'
+export * from './workflowBundle.ts'
 export { maxJsonDepth } from './json.ts'
 
 export { decodeFlowDocument, decodeRevisionContent, upgradeWorkflowInterfaceDocument } from './changeSchema.ts'

package/src/flow/common/semantics.ts

@@ -1,4 +1,5 @@
 import { dequal } from 'dequal/lite'
+import { connectorActionContracts } from '../../connector/common/actionContract.ts'
 import { decisionTaskIssues } from '../../decision/common/decision.ts'
 import { httpRequestIssues, httpAuthHandles, httpRequestTask, httpRequestUrl } from '../../http/common/httpRequest.ts'
 import { openApiIssues, authHandles } from '../../openapi/common/openapi.ts'
@@ -22,7 +23,7 @@ import { canonicalJsonBytes, canonicalModule, canonicalRevisionGraph, digestByte
 import { nodeInputPorts, validateFlowGraph } from './graph.ts'
 import { inputValue } from './inputValue.ts'
 import { compareDiagnostics, validateModuleGraph } from './modules.ts'
-import { hasRetiredRef } from './schema.ts'
+import { hasRetiredRef, matchesSchema } from './schema.ts'
 export { availableOutputs, graphOrder, nodeInputPorts } from './graph.ts'
 export { validateModules } from './modules.ts'
 export { matchesSchema, schemaValidationErrors, variableInputCompatible } from './schema.ts'
@@ -349,16 +350,18 @@ export async function validateFlow(revision: RevisionContent, engine: EngineCont
     for (const message of agentConfigIssues(task)) {
       checked.diagnostics.push({ code: 'agent.config-invalid', column: 0, line: 1, message, path: `/document/graph/nodes/${nodeId}/task/executor` })
     }
-    if (task.executor.kind == 'connector' && task.executor.action == 'leina.send_notification') {
-      const mapping = node.inputs.leinaId
-      const value = inputValue(mapping, nodeInputPorts(node).leinaId?.value)
-      if ((mapping?.kind != 'sources' || mapping.sources.length == 0) && (typeof value != 'string' || value.trim().length == 0)) {
+    if (task.executor.kind == 'connector') {
+      for (const constraint of connectorActionContracts[task.executor.action]?.inputConstraints ?? []) {
+        const mapping = node.inputs[constraint.handle]
+        if (mapping?.kind == 'sources' && mapping.sources.length > 0) continue
+        const value = inputValue(mapping, nodeInputPorts(node)[constraint.handle]?.value)
+        if (value !== undefined && matchesSchema(value, constraint.jsonSchema)) continue
         checked.diagnostics.push({
-          code: 'leina.robot-required',
+          code: constraint.code,
           column: 0,
           line: 1,
-          message: 'Select a Leina robot or bind its identifier to an input source.',
-          path: `/document/graph/nodes/${nodeId}/inputs/leinaId`,
+          message: constraint.message,
+          path: `/document/graph/nodes/${nodeId}/inputs/${constraint.handle}`,
         })
       }
     }

package/src/flow/common/workflowBundle.ts

@@ -0,0 +1,117 @@
+import type { WorkflowFile } from './workflowFile.ts'
+
+import { z } from 'zod'
+import { checkJsonDepth } from './json.ts'
+import { cleanWorkflowFile, decodeWorkflowFile } from './workflowFile.ts'
+import { mapNodeWorkflowTargets, nodeWorkflowReferences } from './workflowReferences.ts'
+
+export interface WorkflowBundleEntry {
+  readonly flowId: string
+  readonly file: WorkflowFile
+}
+
+export interface WorkflowBundle {
+  readonly kind: 'open-flow-workflow-bundle'
+  readonly version: 1
+  readonly entryFlowId: string
+  readonly workflows: readonly WorkflowBundleEntry[]
+}
+
+/** A saved export snapshot; unavailable targets carry no account metadata. */
+export interface WorkflowExportPreview {
+  readonly version: 1
+  readonly entryFlowId: string
+  readonly workflows: readonly WorkflowBundleEntry[]
+  readonly unavailableFlowIds: readonly string[]
+}
+
+const entries = z.array(z.strictObject({ flowId: z.string().min(1), file: z.unknown() })).min(1)
+const bundleSchema = z.strictObject({ kind: z.literal('open-flow-workflow-bundle'), version: z.literal(1), entryFlowId: z.string().min(1), workflows: entries })
+const previewSchema = z.strictObject({
+  version: z.literal(1),
+  entryFlowId: z.string().min(1),
+  workflows: entries,
+  unavailableFlowIds: z.array(z.string().min(1)),
+})
+
+function decodeEntries(value: z.infer<typeof entries>, entryFlowId: string, unavailableFlowIds: readonly string[] = []): readonly WorkflowBundleEntry[] {
+  const workflows = value.map(({ flowId, file }) => ({ flowId, file: decodeWorkflowFile(file) }))
+  const ids = new Set(workflows.map(({ flowId }) => flowId))
+  if (ids.size != workflows.length || !ids.has(entryFlowId)) throw new TypeError('Workflow identities must be unique and include the entry workflow.')
+  const unavailable = new Set(unavailableFlowIds)
+  if (unavailable.size != unavailableFlowIds.length || unavailableFlowIds.some((id) => ids.has(id)))
+    throw new TypeError('Invalid unavailable workflow identities.')
+  for (const { file } of workflows)
+    for (const node of Object.values(file.content.document.graph.nodes))
+      for (const { target } of nodeWorkflowReferences(node))
+        if (target.flowId && !ids.has(target.flowId) && !unavailable.has(target.flowId))
+          throw new TypeError('A referenced workflow is missing from the bundle.')
+  return workflows
+}
+
+export function decodeWorkflowBundle(value: unknown): WorkflowBundle {
+  checkJsonDepth(value, -4)
+  const bundle = bundleSchema.parse(value)
+  return { ...bundle, workflows: decodeEntries(bundle.workflows, bundle.entryFlowId) }
+}
+
+export function decodeWorkflowExportPreview(value: unknown): WorkflowExportPreview {
+  checkJsonDepth(value, -4)
+  const preview = previewSchema.parse(value)
+  return { ...preview, workflows: decodeEntries(preview.workflows, preview.entryFlowId, preview.unavailableFlowIds) }
+}
+
+export function cleanWorkflowBundle(value: unknown): WorkflowBundle {
+  const bundle = decodeWorkflowBundle(value)
+  return { ...bundle, workflows: bundle.workflows.map(({ flowId, file }) => ({ flowId, file: cleanWorkflowFile(file).file })) }
+}
+
+export function workflowBundleFromPreview(preview: WorkflowExportPreview): WorkflowBundle {
+  if (preview.unavailableFlowIds.length) throw new TypeError('Some referenced workflows are unavailable.')
+  return cleanWorkflowBundle({ kind: 'open-flow-workflow-bundle', version: 1, entryFlowId: preview.entryFlowId, workflows: preview.workflows })
+}
+
+export function encodeWorkflowBundle(bundle: WorkflowBundle): string {
+  return `${JSON.stringify(cleanWorkflowBundle(bundle), null, 2)}\n`
+}
+
+export type WorkflowImportFile = WorkflowFile | WorkflowBundle
+
+export function parseWorkflowImportFile(text: string): WorkflowImportFile {
+  const value: unknown = JSON.parse(text)
+  return value != null && typeof value == 'object' && 'kind' in value && value.kind == 'open-flow-workflow-bundle'
+    ? decodeWorkflowBundle(value)
+    : decodeWorkflowFile(value)
+}
+
+/** A bundle creates new drafts, so old published interface provenance must be refreshed. */
+export function remapWorkflowBundle(bundle: WorkflowBundle, flowIds: ReadonlyMap<string, string>): WorkflowBundle {
+  const cleaned = cleanWorkflowBundle(bundle)
+  function identity(flowId: string): string {
+    const mapped = flowIds.get(flowId)
+    if (mapped == null || mapped.length == 0) throw new TypeError('Missing imported workflow identity.')
+    return mapped
+  }
+  const workflows = cleaned.workflows.map(({ flowId, file }) => ({
+    flowId: identity(flowId),
+    file: {
+      ...file,
+      content: {
+        ...file.content,
+        document: {
+          ...file.content.document,
+          graph: {
+            ...file.content.document.graph,
+            nodes: Object.fromEntries(
+              Object.entries(file.content.document.graph.nodes).map(([id, node]) => [
+                id,
+                mapNodeWorkflowTargets(node, (target) => ({ flowId: target.flowId ? identity(target.flowId) : '', revisionId: '' })),
+              ]),
+            ),
+          },
+        },
+      },
+    },
+  }))
+  return decodeWorkflowBundle({ ...cleaned, entryFlowId: identity(cleaned.entryFlowId), workflows })
+}

package/src/flow/common/workflowFile.ts

@@ -12,6 +12,8 @@ export interface WorkflowFile {
   readonly kind: 'open-flow-workflow'
   readonly version: 1
   readonly name?: string
+  readonly icon?: string
+  readonly description?: string
   readonly content: RevisionContent
   readonly presentation?: Readonly<Record<string, JsonValue>>
 }
@@ -25,6 +27,8 @@ const envelope = z.strictObject({
   kind: z.literal('open-flow-workflow'),
   version: z.literal(1),
   name: z.string().optional(),
+  icon: z.string().optional(),
+  description: z.string().optional(),
   content: z.unknown(),
   presentation: z.record(z.string(), z.json()).optional(),
 })

package/src/flow/common/workflowReferences.ts

@@ -1,6 +1,26 @@
 import type { GraphNode } from './change.ts'
 import type { WorkflowCapability } from './model.ts'
 
+type WorkflowTarget = Pick<WorkflowCapability, 'flowId' | 'revisionId'>
+
+/** Rewrite only declared workflow identities, preserving business values and saved ports. */
+export function mapNodeWorkflowTargets(node: GraphNode, map: (target: WorkflowTarget) => WorkflowTarget): GraphNode {
+  if (node.kind != 'task') return node
+  const task = node.task
+  if ('moduleId' in task)
+    return task.capabilities?.some((item) => item.kind == 'workflow')
+      ? { ...node, task: { ...task, capabilities: task.capabilities.map((item) => (item.kind == 'workflow' ? Object.assign({}, item, map(item)) : item)) } }
+      : node
+  const executor = task.executor
+  if (executor.kind == 'workflow') return { ...node, task: { ...task, executor: { ...executor, ...map(executor) } } }
+  if (executor.kind == 'agent')
+    return {
+      ...node,
+      task: { ...task, executor: { ...executor, tools: executor.tools.map((tool) => (tool.kind == 'workflow' ? Object.assign({}, tool, map(tool)) : tool)) } },
+    }
+  return node
+}
+
 /** Workflow declarations share discovery across authoring, admission and resource indexing. */
 export function nodeWorkflowReferences(node: GraphNode): readonly {
   readonly target: Omit<WorkflowCapability, 'kind' | 'name'>