@oomol-lab/open-flow 0.1.0-beta.81 → 0.1.0-beta.83

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.81",
+  "version": "0.1.0-beta.83",
   "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/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/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/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'>