@oomol-lab/open-flow 0.1.0-beta.73 → 0.1.0-beta.74

package/src/flow/common/semantics.ts

@@ -0,0 +1,474 @@
+import { decisionTaskIssues } from '../../decision/common/decision.ts'
+import { openApiIssues, authHandles } from '../../openapi/common/openapi.ts'
+import { nodeWorkflowReferences } from '../../workflow/common/workflow.ts'
+import { isTriggerNode } from './change.ts'
+export { renderPrompt } from './promptTemplate.ts'
+export { connectionUsage, removeConnectionUsage } from './connectionUsage.ts'
+import { matchesTriggerOutputs, normalizeTriggerOutputs } from '../../trigger/common/contract.ts'
+import { nodeInputMappings } from './condition.ts'
+import { connectionUsage } from './connectionUsage.ts'
+export { matchesTriggerOutputs, normalizeTriggerOutputs, triggerOutputDefinitions, triggerOutputPorts } from '../../trigger/common/contract.ts'
+import type { EngineContract } from '../../execution/common/engineContract.ts'
+import type { RuntimeProgram } from '../../execution/common/runtime.ts'
+import type { ConnectorActionCapability, ConnectorCapability, Graph, InputMapping, JsonValue, Port, RevisionContent, SchemaMismatch } from './change.ts'
+
+import { findEngineContract } from '../../execution/common/engineContract.ts'
+import { agentConfigIssues } from './agent.ts'
+import { decodeTaskCapabilities } from './change.ts'
+import { canonicalJsonBytes, canonicalModule, canonicalRevisionGraph, digestBytes } from './encoding.ts'
+import { nodeInputPorts, validateFlowGraph } from './graph.ts'
+import { inputValue } from './inputValue.ts'
+import { compareDiagnostics, validateModuleGraph } from './modules.ts'
+import { hasRetiredRef } from './schema.ts'
+export { availableOutputs, graphOrder, nodeInputPorts } from './graph.ts'
+export { validateModules } from './modules.ts'
+export { matchesSchema, schemaValidationErrors, variableInputCompatible } from './schema.ts'
+export { agentInput, agentToolInput, agentToolSchema } from './agent.ts'
+
+export interface SemanticClosure {
+  readonly dependencies: {
+    readonly bindings: ReadonlySet<string>
+    readonly nodes: ReadonlySet<string>
+    readonly modules: ReadonlySet<string>
+  }
+  readonly digest: string
+}
+
+function entries<T>(value: Readonly<Record<string, T>>): readonly (readonly [string, T])[] {
+  return Object.keys(value)
+    .toSorted()
+    .map((key) => [key, value[key]!] as const)
+}
+
+export function flowDependencies(content: RevisionContent, triggerId?: string): SemanticClosure['dependencies'] {
+  if (triggerId != null) return flowDependencies(runRevision(content, triggerId))
+  const bindings = new Set<string>()
+  const modules = new Set<string>()
+
+  function visitModule(id: string): void {
+    if (modules.has(id)) return
+    modules.add(id)
+    const module = content.modules[id]
+    if (module == null) return
+    for (const imported of module.imports.toSorted()) visitModule(imported)
+  }
+
+  function visitInputMappings(value: Readonly<Record<string, InputMapping>>): void {
+    for (const mapping of Object.values(value)) {
+      if (mapping.kind != 'sources') continue
+      for (const source of mapping.sources) {
+        if (source.kind != 'binding') continue
+        bindings.add(source.bindingId)
+      }
+    }
+  }
+
+  function visitGraph(value: Graph): void {
+    for (const [, node] of entries(value.nodes)) {
+      if (!isTriggerNode(node)) visitInputMappings(nodeInputMappings(node))
+      switch (node.kind) {
+        case 'condition':
+          break
+        case 'task':
+          if ('moduleId' in node.task) visitModule(node.task.moduleId)
+          break
+        case 'outputs':
+        case 'value':
+          break
+        case 'approval':
+        case 'wait':
+          break
+        case 'poll':
+        case 'integration':
+        case 'cron':
+        case 'error':
+        case 'manual':
+        case 'start':
+        case 'webhook':
+          break
+      }
+    }
+  }
+
+  visitGraph(content.document.graph)
+
+  return { bindings, modules, nodes: new Set(Object.keys(content.document.graph.nodes)) }
+}
+
+export async function flowClosure(content: RevisionContent): Promise<SemanticClosure> {
+  const dependencies = flowDependencies(content)
+  return { dependencies, digest: await digestBytes(closureBytes(content, dependencies)) }
+}
+
+/** Canonical semantic bytes, also used by transactional storage upgrades. */
+export function encodeFlowClosure(content: RevisionContent, triggerId?: string): Uint8Array {
+  const scoped = triggerId == null ? content : runRevision(content, triggerId)
+  return closureBytes(scoped, flowDependencies(scoped))
+}
+
+function closureBytes(content: RevisionContent, dependencies: SemanticClosure['dependencies']): Uint8Array {
+  const { bindings, modules } = dependencies
+  return canonicalJsonBytes({
+    bindings: Object.fromEntries([...bindings].toSorted().map((id) => [id, content.document.bindings[id] ?? null])),
+    graph: canonicalRevisionGraph(content, content.document.graph),
+    kind: 'open-flow-semantic-closure',
+    ...(content.modelVersion < 6 ? { subflows: {} } : {}),
+    modelVersion: content.modelVersion,
+    modules: Object.fromEntries([...modules].toSorted().map((id) => [id, content.modules[id] == null ? null : canonicalModule(content.modules[id])])),
+    ...(content.modelVersion < 6 ? { tasks: {} } : {}),
+    version: 2,
+  })
+}
+
+export function variableBindings(revision: RevisionContent, bindingIds: Iterable<string>): Readonly<Record<string, string>> {
+  return Object.fromEntries(
+    [...bindingIds].flatMap((bindingId) => {
+      const binding = revision.document.bindings[bindingId]
+      return binding?.kind == 'variable' ? [[bindingId, binding.target]] : []
+    }),
+  )
+}
+
+export interface FlowResourceReferences {
+  readonly calledFlowIds?: readonly string[]
+  readonly variableNames: readonly string[]
+  readonly connections: readonly { readonly providerId: string; readonly connectionId: string }[]
+  readonly errorSourceFlowIds: readonly string[]
+}
+
+export function flowResourceReferences(content: RevisionContent): FlowResourceReferences {
+  const connections = new Map<string, { readonly providerId: string; readonly connectionId: string }>()
+  for (const use of connectionUsage(content.document)) {
+    if (use.connectionId == null || use.connectionId === '') continue
+    connections.set(JSON.stringify([use.providerId, use.connectionId]), { providerId: use.providerId, connectionId: use.connectionId })
+  }
+  return {
+    calledFlowIds: [
+      ...new Set(
+        Object.values(content.document.graph.nodes).flatMap((node) =>
+          nodeWorkflowReferences(node)
+            .map(({ target }) => target.flowId)
+            .filter(Boolean),
+        ),
+      ),
+    ].toSorted(),
+    variableNames: [...new Set(Object.values(variableBindings(content, flowDependencies(content).bindings)))].toSorted(),
+    connections: [...connections].toSorted(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0)).map(([, value]) => value),
+    errorSourceFlowIds: [
+      ...new Set(Object.values(content.document.graph.nodes).flatMap((node) => (node.kind == 'error' ? (node.sourceFlowIds ?? []) : []))),
+    ].toSorted(),
+  }
+}
+
+export interface Diagnostic {
+  readonly code: string
+  readonly column: number
+  readonly fields?: readonly string[]
+  readonly line: number
+  readonly message: string
+  readonly mismatch?: SchemaMismatch
+  readonly path: string
+  readonly values?: Readonly<Record<string, string | number>>
+}
+
+export interface FlowValidation {
+  readonly closure: SemanticClosure
+  readonly diagnostics: readonly Diagnostic[]
+  readonly valid: boolean
+}
+
+export type FlowInputsValidation = 'invalid' | 'valid'
+
+export function validRunTrigger(revision: RevisionContent, value: unknown): boolean {
+  if (value == null || typeof value != 'object' || Array.isArray(value)) return false
+  const trigger = value as Readonly<Record<string, unknown>>
+  if (Object.keys(trigger).some((key) => key != 'nodeId' && key != 'outputs') || typeof trigger.nodeId != 'string' || !Object.hasOwn(trigger, 'outputs'))
+    return false
+  const node = revision.document.graph.nodes[trigger.nodeId]
+  return node != null && isTriggerNode(node) && matchesTriggerOutputs(node, trigger.outputs)
+}
+
+export function normalizeRunTrigger(
+  revision: RevisionContent,
+  value: unknown,
+): { readonly nodeId: string; readonly outputs: Readonly<Record<string, JsonValue>> } | undefined {
+  if (value == null || typeof value != 'object' || Array.isArray(value)) return
+  const trigger = value as Readonly<Record<string, unknown>>
+  if (Object.keys(trigger).some((key) => key != 'nodeId' && key != 'outputs') || typeof trigger.nodeId != 'string' || !Object.hasOwn(trigger, 'outputs')) return
+  const node = revision.document.graph.nodes[trigger.nodeId]
+  if (node == null || !isTriggerNode(node)) return
+  const outputs = normalizeTriggerOutputs(node, trigger.outputs)
+  return outputs == null ? undefined : { nodeId: trigger.nodeId, outputs }
+}
+
+export function validateFlowInputs(revision: RevisionContent, value: unknown): FlowInputsValidation {
+  if (value == null || typeof value != 'object' || Array.isArray(value)) return 'invalid'
+  const graph = revision.document.graph
+  for (const [nodeId, candidate] of Object.entries(value)) {
+    const node = graph.nodes[nodeId]
+    if (node == null || isTriggerNode(node) || node.kind == 'condition' || candidate == null || typeof candidate != 'object' || Array.isArray(candidate)) {
+      return 'invalid'
+    }
+    const inputs = nodeInputPorts(node)
+    for (const handle of Object.keys(candidate)) {
+      const port = inputs[handle]
+      if (port == null || hasRetiredRef(port.jsonSchema) || nodeInputMappings(node)[handle] != null || Object.hasOwn(port, 'value')) return 'invalid'
+    }
+  }
+  return 'valid'
+}
+
+export async function validateFlow(revision: RevisionContent, engine: EngineContract): Promise<FlowValidation> {
+  const closure = await flowClosure(revision)
+  const checked = validateModuleGraph(revision, [...closure.dependencies.modules], engine)
+  checked.diagnostics.push(...validateFlowGraph(revision))
+  const missingEntryModules = new Set<string>()
+  for (const [nodeId, node] of Object.entries(revision.document.graph.nodes)) {
+    if (node.kind != 'task' || !('moduleId' in node.task)) continue
+    if (revision.modules[node.task.moduleId] == null) {
+      checked.diagnostics.push({
+        code: 'task.module-missing',
+        column: 0,
+        line: 1,
+        message: `Inline Task "${nodeId}" references missing CodeModule "${node.task.moduleId}".`,
+        path: `/document/graph/nodes/${nodeId}/task/moduleId`,
+        values: { moduleId: node.task.moduleId, nodeId },
+      })
+    } else if (checked.analysis.get(node.task.moduleId)?.exports.has('default') == false && !missingEntryModules.has(node.task.moduleId)) {
+      missingEntryModules.add(node.task.moduleId)
+      checked.diagnostics.push({
+        code: 'task.missing-entry',
+        column: 0,
+        line: 1,
+        message: `CodeModule "${node.task.moduleId}" used by an Inline Task must export a default function.`,
+        path: `/modules/${node.task.moduleId}/source`,
+        values: { moduleId: node.task.moduleId },
+      })
+    }
+    try {
+      decodeTaskCapabilities(node.task.capabilities === undefined ? [] : node.task.capabilities)
+    } catch {
+      checked.diagnostics.push({
+        code: 'task.capability-incomplete',
+        column: 0,
+        line: 1,
+        message: `Inline Task "${nodeId}" has an incomplete Connector Capability.`,
+        path: `/document/graph/nodes/${nodeId}/task/capabilities`,
+        values: { nodeId },
+      })
+    }
+  }
+  for (const [nodeId, node] of Object.entries(revision.document.graph.nodes)) {
+    if (node.kind != 'task' || !('executor' in node.task)) continue
+    const task = node.task
+    for (const issue of decisionTaskIssues(task))
+      checked.diagnostics.push({
+        code: 'decision.config-invalid',
+        column: 0,
+        line: 1,
+        message: issue.message,
+        path: `/document/graph/nodes/${nodeId}/task/executor`,
+      })
+    for (const message of openApiIssues(task))
+      checked.diagnostics.push({ code: 'openapi.config-invalid', column: 0, line: 1, message, path: `/document/graph/nodes/${nodeId}/task/executor` })
+    if (task.executor.kind == 'openapi') {
+      const handles = authHandles(task.executor.auth)
+      for (const handle of handles) {
+        const mapping = node.inputs[handle]
+        if (mapping?.kind != 'sources' || mapping.sources.length == 0)
+          checked.diagnostics.push({
+            code: 'openapi.auth-source',
+            column: 0,
+            line: 1,
+            message: 'Authentication requires a deployment variable or upstream output.',
+            path: `/document/graph/nodes/${nodeId}/inputs/${handle}`,
+          })
+      }
+    }
+    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)) {
+        checked.diagnostics.push({
+          code: 'leina.robot-required',
+          column: 0,
+          line: 1,
+          message: 'Select a Leina robot or bind its identifier to an input source.',
+          path: `/document/graph/nodes/${nodeId}/inputs/leinaId`,
+        })
+      }
+    }
+    if (task.executor.kind == 'connector' && task.executor.action.length == 0) {
+      checked.diagnostics.push({
+        code: 'task.connector-incomplete',
+        column: 0,
+        line: 1,
+        message: `Connector Task "${nodeId}" requires an action.`,
+        path: `/document/graph/nodes/${nodeId}/task/executor`,
+        values: { nodeId },
+      })
+    }
+  }
+  const diagnostics = checked.diagnostics.toSorted(compareDiagnostics)
+  return { closure, diagnostics, valid: diagnostics.length == 0 }
+}
+
+export interface PreparedFlow {
+  readonly inputDefs: readonly Port[]
+  readonly outputDefs: readonly Port[]
+  readonly outputMappings: Readonly<Record<string, InputMapping>>
+  readonly closureDigest: string
+  readonly engineContract: string
+  readonly graph: Graph
+  readonly modules: RevisionContent['modules']
+}
+
+export type PrepareFlowResult =
+  | { readonly kind: 'engine-unsupported' }
+  | { readonly kind: 'flow-invalid'; readonly validation: FlowValidation }
+  | { readonly flow: PreparedFlow; readonly kind: 'prepared'; readonly validation: FlowValidation }
+
+function runRevision(revision: RevisionContent, triggerId: string): RevisionContent {
+  const graph = revision.document.graph
+  const reachable = new Set([triggerId])
+  for (const nodeId of reachable) {
+    for (const edge of graph.edges) if (edge.source == nodeId) reachable.add(edge.target)
+  }
+  function inputs(nodeId: string, mappings: Readonly<Record<string, InputMapping>>): Readonly<Record<string, InputMapping>> {
+    const ancestors = new Set<string>()
+    for (const edge of graph.edges) if (edge.target == nodeId) ancestors.add(edge.source)
+    for (const ancestor of ancestors) {
+      for (const edge of graph.edges) if (edge.target == ancestor) ancestors.add(edge.source)
+    }
+    return Object.fromEntries(
+      Object.entries(mappings).map(([handle, mapping]) => [
+        handle,
+        mapping.kind != 'sources'
+          ? mapping
+          : {
+              ...mapping,
+              sources: mapping.sources.filter(
+                (source) => source.kind != 'node' || graph.nodes[source.nodeId] == null || reachable.has(source.nodeId) || !ancestors.has(source.nodeId),
+              ),
+            },
+      ]),
+    )
+  }
+  const nodes: Record<string, Graph['nodes'][string]> = {}
+  for (const nodeId of reachable) {
+    const node = graph.nodes[nodeId]
+    if (node == null) continue
+    nodes[nodeId] =
+      node.kind == 'outputs'
+        ? { ...node, outputMappings: inputs(nodeId, node.outputMappings) }
+        : isTriggerNode(node)
+          ? node
+          : {
+              ...node,
+              inputs: inputs(nodeId, node.inputs),
+            }
+  }
+  const content = {
+    ...revision,
+    document: {
+      ...revision.document,
+      graph: { nodes, edges: graph.edges.filter((edge) => reachable.has(edge.source)) },
+    },
+  }
+  const { bindings } = flowDependencies(content)
+  return {
+    ...content,
+    document: { ...content.document, bindings: Object.fromEntries(Object.entries(content.document.bindings).filter(([id]) => bindings.has(id))) },
+  }
+}
+
+export async function prepareFlow(revision: RevisionContent, engineContract: string, triggerId?: string): Promise<PrepareFlowResult> {
+  const engine = findEngineContract(engineContract)
+  if (engine == null) return { kind: 'engine-unsupported' }
+  if (!engine.workflowTools && Object.values(revision.document.graph.nodes).some((node) => nodeWorkflowReferences(node).some((ref) => ref.tool != null)))
+    return { kind: 'engine-unsupported' }
+  if (triggerId != null) {
+    const trigger = revision.document.graph.nodes[triggerId]
+    if (trigger == null || !isTriggerNode(trigger))
+      return {
+        kind: 'flow-invalid',
+        validation: {
+          closure: await flowClosure(revision),
+          diagnostics: [
+            {
+              code: 'graph.trigger-invalid',
+              column: 0,
+              line: 1,
+              message: 'Select an existing Trigger node.',
+              path: '/document/graph',
+              values: { nodeId: triggerId },
+            },
+          ],
+          valid: false,
+        },
+      }
+    revision = runRevision(revision, triggerId)
+  }
+  if (
+    !engine.webhookResponses &&
+    Object.values(revision.document.graph.nodes).some(
+      (node) => node.kind === 'webhook-response' || (node.kind === 'webhook' && node.options?.responseBody?.kind === 'webhook-response'),
+    )
+  )
+    return { kind: 'engine-unsupported' }
+  if (!engine.waitAutoContinue && Object.values(revision.document.graph.nodes).some((node) => node.kind == 'wait' && node.autoContinue != null))
+    return { kind: 'engine-unsupported' }
+  const validation = await validateFlow(revision, engine)
+  if (!validation.valid) return { kind: 'flow-invalid', validation }
+  const { closure } = validation
+  const start = Object.values(revision.document.graph.nodes).find((node) => node.kind == 'start')
+  const outputs = Object.values(revision.document.graph.nodes).find((node) => node.kind == 'outputs')
+  return {
+    flow: {
+      closureDigest: closure.digest,
+      engineContract,
+      inputDefs: start?.inputDefs ?? [],
+      outputDefs: outputs?.outputDefs ?? [],
+      outputMappings: outputs?.outputMappings ?? {},
+      graph: revision.document.graph,
+      modules: Object.fromEntries([...closure.dependencies.modules].toSorted().map((id) => [id, revision.modules[id]!])),
+    },
+    kind: 'prepared',
+    validation,
+  }
+}
+
+export function createRuntimeProgram(prepared: PreparedFlow, entryModuleId: string, engineDigest: string): RuntimeProgram | undefined {
+  if (!Object.hasOwn(prepared.modules, entryModuleId)) return
+  return {
+    engineContract: prepared.engineContract,
+    engineDigest,
+    entryModuleId,
+    modules: prepared.modules,
+  }
+}
+
+export function agentActions(flow: Pick<PreparedFlow, 'graph'>): readonly ConnectorActionCapability[] {
+  return Object.values(flow.graph.nodes).flatMap((node) => {
+    if (node.kind != 'task' || !('executor' in node.task)) return []
+    const task = node.task
+    if (task.executor.kind != 'agent') return []
+    const notice = task.executor.notification
+    return [...task.executor.tools.filter((tool) => tool.kind != 'workflow'), ...(notice != null ? [notice] : [])]
+      .filter((tool) => tool.connectionId !== '')
+      .map((tool) => ({
+        kind: 'connector' as const,
+        action: tool.action,
+        connections: tool.connectionId == null ? [] : [{ connectionId: tool.connectionId }],
+      }))
+  })
+}
+
+export function codeActions(flow: Pick<PreparedFlow, 'graph'>): readonly ConnectorCapability[] {
+  return Object.values(flow.graph.nodes).flatMap((node) =>
+    node.kind == 'task' && 'moduleId' in node.task ? (node.task.capabilities ?? []).filter((item) => item.kind == 'connector') : [],
+  )
+}

package/src/flow/common/sourceField.ts

@@ -0,0 +1,35 @@
+import type { NodeSource, PortDefinition } from './change.ts'
+
+import { schemaObject } from './schema.ts'
+
+/** Only explicitly declared, first-level object properties are selectable. */
+export function sourceFields(output: PortDefinition): readonly { readonly field: string; readonly port: PortDefinition }[] {
+  const schema = schemaObject(output.jsonSchema)
+  if (schema == null) return []
+  const properties = schemaObject(schema.properties ?? false)
+  const types = Array.isArray(schema.type) ? schema.type : [schema.type]
+  if (properties == null || (schema.type !== undefined && !types.includes('object'))) return []
+  const required = Array.isArray(schema.required) ? schema.required : []
+  const missingParent = output.nullable || types.some((type) => type !== 'object')
+  return Object.entries(properties).map(([field, jsonSchema]) => {
+    const description = schemaObject(jsonSchema)?.description
+    return {
+      field,
+      port: {
+        ...(typeof description == 'string' ? { description } : {}),
+        jsonSchema,
+        nullable: missingParent || !required.includes(field),
+      },
+    }
+  })
+}
+
+export function sourcePort(output: PortDefinition, field: string | undefined): PortDefinition | undefined {
+  return field === undefined ? output : sourceFields(output).find((candidate) => candidate.field === field)?.port
+}
+
+/** Present a selected first-level field as a compact path from its output. */
+export function sourceOutputLabel(source: Pick<NodeSource, 'output' | 'field' | 'system'>): string {
+  const output = source.system ? `$system / ${source.output}` : source.output
+  return source.field === undefined ? output : `${output} / ${source.field}`
+}

package/src/flow/common/triggerScheduleSchema.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod'
+
+export const triggerScheduleSchema = z.array(
+  z.union([
+    z.object({ type: z.literal('cron'), expression: z.string(), timezone: z.string() }),
+    z.object({ type: z.literal('every'), unit: z.enum(['day', 'hour', 'minute', 'month', 'week']), value: z.number() }),
+  ]),
+)

package/src/flow/common/wait.ts

@@ -0,0 +1,30 @@
+import type { WaitAutoContinue } from './change.ts'
+
+import { z } from 'zod'
+import { isTimeZone } from '../../localization/common/timeZone.ts'
+
+/** Drafts retain incomplete values; semantic validation gates publication and execution. */
+export const waitAutoContinueDraftSchema = z.discriminatedUnion('kind', [
+  z.strictObject({ kind: z.literal('after'), durationMs: z.number().nullable() }),
+  z.strictObject({
+    kind: z.literal('at'),
+    at: z.string(),
+    timezone: z.string().optional(),
+  }),
+])
+
+/** Static business configuration; the deployment owns the allowed wait lifetime. */
+export const waitAutoContinueSchema = z.discriminatedUnion('kind', [
+  waitAutoContinueDraftSchema.options[0].extend({ durationMs: z.number().int().positive().max(Number.MAX_SAFE_INTEGER) }),
+  waitAutoContinueDraftSchema.options[1].extend({
+    at: z.iso.datetime({ offset: true }),
+    timezone: z.string().refine(isTimeZone, 'Select a valid IANA timezone.').optional(),
+  }),
+])
+
+/** Resolve one registration's intent; the deployment separately enforces its lifetime. */
+export function waitAutoContinueAt(config: WaitAutoContinue, waitingSince: number): number {
+  const timing = waitAutoContinueSchema.parse(config)
+  const at = timing.kind == 'after' ? waitingSince + timing.durationMs : Date.parse(timing.at)
+  return Math.max(waitingSince, at)
+}

package/src/flow/common/webhookMethod.ts

@@ -0,0 +1,7 @@
+export const webhookMethods = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'] as const
+
+export type WebhookMethod = (typeof webhookMethods)[number]
+
+export function webhookSupportsBody(method: WebhookMethod): boolean {
+  return method !== 'GET'
+}

package/src/flow/common/webhookResponse.ts

@@ -0,0 +1,75 @@
+import type { InputPort, JsonValue, Port, PortDefinition } from './change.ts'
+
+export const webhookResponseTimeout = {
+  defaultMs: 30_000,
+  minMs: 1000,
+  maxMs: 60_000,
+} as const
+
+export const webhookStatusCodePort = { jsonSchema: { type: 'number' }, nullable: true } as const
+
+export function webhookResponseAllowsBody(status: number): boolean {
+  return status !== 204 && status !== 205 && status !== 304
+}
+
+export const webhookHeaderValuePort = { jsonSchema: { type: ['string', 'number', 'boolean'] }, nullable: true } as const
+export const webhookHeadersPort = {
+  jsonSchema: { type: 'object', additionalProperties: { type: ['string', 'number', 'boolean'] } },
+  nullable: true,
+} as const
+
+export function workflowOutputsPort(outputs: readonly Port[]): PortDefinition {
+  return {
+    jsonSchema: {
+      type: 'object',
+      properties: Object.fromEntries(outputs.map((port) => [port.handle, port.jsonSchema])),
+      additionalProperties: false,
+      required: outputs.map((port) => port.handle),
+    },
+    nullable: false,
+  } as const
+}
+
+/** Header names are case-insensitive; never silently combine duplicate business fields. */
+export function webhookHeaderNameIssue(name: string, names: readonly string[]): 'invalid' | 'duplicate' | undefined {
+  if (!/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(name)) return 'invalid'
+  if (names.some((candidate) => candidate.toLowerCase() === name.toLowerCase())) return 'duplicate'
+}
+
+/** Fixed inputs belong to the node, not author-supplied definitions. */
+export const webhookResponseInputs: readonly InputPort[] = [
+  { handle: 'body', jsonSchema: {}, nullable: true, value: '' },
+  { handle: 'statusCode', jsonSchema: { type: 'number' }, nullable: false, value: 200 },
+  { handle: 'headers', jsonSchema: webhookHeadersPort.jsonSchema, nullable: false, value: {} },
+]
+
+export interface WebhookResponseSnapshot {
+  readonly body: string
+  readonly contentType: string
+  readonly status: number
+  readonly headers: Readonly<Record<string, string>>
+}
+
+export function validWebhookStatus(value: unknown): value is number {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 200 && value <= 599 && webhookResponseAllowsBody(value)
+}
+
+/** Portable validation also runs in the isolated engine, which has no HTTP globals. */
+export function webhookHeaderValues(source: unknown): Readonly<Record<string, string>> | undefined {
+  if (source == null || typeof source !== 'object' || Array.isArray(source)) return
+  const headers: Record<string, string> = {}
+  const names: string[] = []
+  for (const [name, value] of Object.entries(source)) {
+    if (webhookHeaderNameIssue(name, names) != null) return
+    if (typeof value !== 'string' && typeof value !== 'boolean' && !(typeof value === 'number' && Number.isFinite(value))) return
+    const text = String(value)
+    if ([...text].some((character) => character.charCodeAt(0) > 255 || /[\0\r\n]/.test(character))) return
+    names.push(name)
+    Object.defineProperty(headers, name, { value: text, enumerable: true, configurable: true })
+  }
+  return headers
+}
+
+export function encodeWebhookBody(value: JsonValue): Pick<WebhookResponseSnapshot, 'body' | 'contentType'> {
+  return typeof value === 'string' ? { body: value, contentType: 'text/plain;charset=UTF-8' } : { body: JSON.stringify(value), contentType: 'application/json' }
+}