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

package/src/execution/common/events.ts

@@ -0,0 +1,328 @@
+import type { WebhookResponseSnapshot } from '../../flow/common/webhookResponse.ts'
+
+import { validWebhookStatus, webhookHeaderValues } from '../../flow/common/webhookResponse.ts'
+export type ProjectedRunEvent =
+  | {
+      readonly response?: WebhookResponseSnapshot
+      readonly kind: 'node.completed'
+      readonly payload: Readonly<Record<string, unknown>>
+      readonly value: unknown
+    }
+  | {
+      readonly kind: 'node.artifact' | 'node.failed' | 'node.log' | 'node.progress' | 'node.started' | 'run.progress' | 'run.started'
+      readonly payload: Readonly<Record<string, unknown>>
+    }
+
+const encoder = new TextEncoder()
+const nodeKinds = new Set([
+  'agent',
+  'approval',
+  'condition',
+  'connector',
+  'decision',
+  'javascript',
+  'openapi',
+  'llm',
+  'value',
+  'wait',
+  'outputs',
+  'workflow',
+  'webhook-response',
+])
+
+function object(value: unknown, description: string): Record<string, unknown> {
+  if (value == null || typeof value != 'object' || Array.isArray(value)) throw new TypeError(`${description} must be an object.`)
+  return value as Record<string, unknown>
+}
+
+function string(value: unknown, description: string): string {
+  if (typeof value != 'string' || value.length == 0) throw new TypeError(`${description} must be a non-empty string.`)
+  return value
+}
+
+function optionalString(value: unknown, description: string): string | undefined {
+  return value === undefined ? undefined : string(value, description)
+}
+
+function nodeKind(
+  value: unknown,
+):
+  | 'agent'
+  | 'approval'
+  | 'condition'
+  | 'connector'
+  | 'decision'
+  | 'javascript'
+  | 'openapi'
+  | 'llm'
+  | 'value'
+  | 'wait'
+  | 'outputs'
+  | 'workflow'
+  | 'webhook-response'
+  | undefined {
+  if (value === undefined) return
+  if (!nodeKinds.has(value as string)) {
+    throw new TypeError('Runtime node.started nodeKind is invalid.')
+  }
+  return value as
+    | 'agent'
+    | 'approval'
+    | 'condition'
+    | 'connector'
+    | 'decision'
+    | 'javascript'
+    | 'openapi'
+    | 'llm'
+    | 'value'
+    | 'wait'
+    | 'outputs'
+    | 'workflow'
+    | 'webhook-response'
+}
+
+function runId(event: Record<string, unknown>): string {
+  return string(event.runId, 'Runtime event runId')
+}
+
+function nodeContext(
+  event: Record<string, unknown>,
+  flows: ReadonlyMap<string, string>,
+  platformRunId: string,
+): {
+  readonly executionId: Promise<string>
+  readonly flowId: string
+  readonly nodeId: string
+  readonly rawRunId: string
+} {
+  const rawRunId = runId(event)
+  const flowId = flows.get(rawRunId)
+  if (flowId == null) throw new TypeError('Runtime node event preceded its run.started event.')
+  return {
+    executionId: projectExecutionId(platformRunId, rawRunId, string(event.jobId, 'Runtime node event jobId')),
+    flowId,
+    nodeId: string(event.nodeId, 'Runtime node event nodeId'),
+    rawRunId,
+  }
+}
+
+/** Stable public identity shared by events and durable workflow-call provenance. */
+export function projectExecutionId(platformRunId: string, rawRunId: string, jobId: string): Promise<string> {
+  return opaqueId('execution', platformRunId, rawRunId, jobId)
+}
+
+async function opaqueId(prefix: 'execution' | 'scope', ...parts: readonly string[]): Promise<string> {
+  const bytes = encoder.encode(JSON.stringify([1, prefix, ...parts]))
+  const input = new Uint8Array(bytes.byteLength)
+  input.set(bytes)
+  const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', input))
+  return `${prefix}_${[...digest]
+    .slice(0, 16)
+    .map((byte) => byte.toString(16).padStart(2, '0'))
+    .join('')}`
+}
+
+function message(value: unknown): string {
+  return string(value, 'Runtime event message')
+    .replace(/Bearer\s+\S+/gi, 'Bearer [REDACTED]')
+    .replace(/\b(api[-_ ]?key|authorization|password|secret|token)\s*[:=]\s*\S+/gi, '$1=[REDACTED]')
+}
+
+export { message as sanitizeRuntimeErrorMessage }
+
+function nodeFailureCode(value: unknown, allowed: ReadonlySet<string>): string {
+  const code = string(value, 'Runtime node.failed code')
+  if (!allowed.has(code)) throw new TypeError('Runtime node.failed code is invalid.')
+  return code
+}
+
+function artifact(value: unknown): {
+  readonly digest: string
+  readonly id: string
+  readonly kind: 'artifact'
+  readonly mediaType?: string
+  readonly name: string
+  readonly size: number
+} {
+  const ref = object(value, 'Runtime ArtifactRef')
+  const keys = Object.keys(ref)
+  if (
+    keys.some((key) => !['kind', 'id', 'name', 'mediaType', 'size', 'digest'].includes(key)) ||
+    ref.kind != 'artifact' ||
+    typeof ref.id != 'string' ||
+    ref.id.length == 0 ||
+    typeof ref.name != 'string' ||
+    ref.name.length == 0 ||
+    (ref.mediaType !== undefined && (typeof ref.mediaType != 'string' || ref.mediaType.length == 0)) ||
+    typeof ref.size != 'number' ||
+    !Number.isSafeInteger(ref.size) ||
+    ref.size < 0 ||
+    typeof ref.digest != 'string' ||
+    !/^sha256:[0-9a-f]{64}$/.test(ref.digest)
+  ) {
+    throw new TypeError('Runtime ArtifactRef is invalid.')
+  }
+  return {
+    digest: ref.digest,
+    id: ref.id,
+    kind: 'artifact',
+    ...(ref.mediaType === undefined ? {} : { mediaType: ref.mediaType as string }),
+    name: ref.name,
+    size: ref.size,
+  }
+}
+
+export function createEventProjector(platformRunId: string, nodeFailureCodes: ReadonlySet<string>): (event: unknown) => Promise<ProjectedRunEvent | undefined> {
+  const flows = new Map<string, string>()
+  const paths = new Map<string, readonly string[]>()
+  const jobs = new Map<string, string>()
+  const nodeProgressBuckets = new Map<string, number>()
+  const runProgressBuckets = new Map<string, number>()
+  return async (value) => {
+    const event = object(value, 'Runtime event')
+    const type = string(event.type, 'Runtime event type')
+
+    if (type == 'run.started') {
+      const rawRunId = runId(event)
+      const flowId = string(event.flowId, 'Runtime run.started flowId')
+      const knownFlow = flows.get(rawRunId)
+      if (knownFlow != null && knownFlow != flowId) throw new TypeError('Runtime run identity changed its flowId.')
+      flows.set(rawRunId, flowId)
+      const parentRunId = event.parentRunId
+      if (parentRunId !== undefined && (typeof parentRunId != 'string' || parentRunId.length == 0)) {
+        throw new TypeError('Runtime run.started parentRunId must be a non-empty string when present.')
+      }
+      const parentJobId = optionalString(event.parentJobId, 'Runtime run.started parentJobId')
+      const parentNode = parentRunId == null || parentJobId == null ? undefined : jobs.get(JSON.stringify([parentRunId, parentJobId]))
+      paths.set(rawRunId, parentRunId == null ? [] : [...(paths.get(parentRunId as string) ?? []), parentNode ?? flowId])
+      return {
+        kind: 'run.started',
+        payload: {
+          flowId,
+          ...(parentRunId === undefined ? {} : { parentScopeId: await opaqueId('scope', platformRunId, parentRunId) }),
+          scopeId: await opaqueId('scope', platformRunId, rawRunId),
+        },
+      }
+    }
+
+    if (type == 'run.progress') {
+      const rawRunId = runId(event)
+      const flowId = flows.get(rawRunId)
+      if (flowId == null) throw new TypeError('Runtime run.progress event preceded its run.started event.')
+      if (typeof event.progress != 'number' || !Number.isFinite(event.progress) || event.progress < 0 || event.progress > 100) {
+        throw new TypeError('Runtime run.progress value must be between 0 and 100.')
+      }
+      const bucket = Math.floor(event.progress)
+      if ((runProgressBuckets.get(rawRunId) ?? -1) >= bucket) return
+      runProgressBuckets.set(rawRunId, bucket)
+      return {
+        kind: 'run.progress',
+        payload: {
+          flowId,
+          progress: event.progress,
+          scopeId: await opaqueId('scope', platformRunId, rawRunId),
+        },
+      }
+    }
+
+    if (type == 'run.completed' || type == 'run.failed') {
+      const rawRunId = runId(event)
+      if (type == 'run.failed' && rawRunId == platformRunId && event.failure != null) {
+        const failure = object(event.failure, 'Runtime terminal failure')
+        const context = nodeContext(failure, flows, platformRunId)
+        return {
+          kind: 'node.failed',
+          payload: {
+            terminal: true,
+            nodeId: context.nodeId,
+            executionId: await context.executionId,
+            path: paths.get(context.rawRunId) ?? [],
+            error: { code: nodeFailureCode(failure.code, nodeFailureCodes), message: message(failure.message) },
+          },
+        }
+      }
+      return
+    }
+
+    if (
+      type == 'node.started' ||
+      type == 'node.progress' ||
+      type == 'node.artifact' ||
+      type == 'node.log' ||
+      type == 'node.completed' ||
+      type == 'node.failed'
+    ) {
+      const context = nodeContext(event, flows, platformRunId)
+      const executionId = await context.executionId
+      const payload = {
+        executionId,
+        flowId: context.flowId,
+        nodeId: context.nodeId,
+        scopeId: await opaqueId('scope', platformRunId, context.rawRunId),
+        ...(event.systemOutputs === undefined ? {} : { systemOutputs: object(event.systemOutputs, 'Runtime system outputs') }),
+        ...(event.handled === true ? { handled: true } : {}),
+      }
+      switch (type) {
+        case 'node.completed':
+          return {
+            kind: type,
+            payload,
+            value: object(event.outputs, 'Runtime node.completed outputs'),
+            ...(event.response == null || context.rawRunId !== platformRunId ? {} : { response: responseSnapshot(event.response) }),
+          }
+        case 'node.started': {
+          jobs.set(JSON.stringify([context.rawRunId, event.jobId]), context.nodeId)
+          const kind = nodeKind(event.nodeKind)
+          const nodeTitle = optionalString(event.nodeTitle, 'Runtime node.started nodeTitle')
+          const operation = optionalString(event.operation, 'Runtime node.started operation')
+          return {
+            kind: type,
+            payload: {
+              ...payload,
+              ...(kind === undefined ? {} : { nodeKind: kind }),
+              ...(nodeTitle === undefined ? {} : { nodeTitle }),
+              ...(operation === undefined ? {} : { operation }),
+            },
+          }
+        }
+        case 'node.progress':
+          if (typeof event.progress != 'number' || !Number.isFinite(event.progress) || event.progress < 0 || event.progress > 100) {
+            throw new TypeError('Runtime node.progress value must be between 0 and 100.')
+          }
+          const bucket = Math.floor(event.progress)
+          if ((nodeProgressBuckets.get(executionId) ?? -1) >= bucket) return
+          nodeProgressBuckets.set(executionId, bucket)
+          return { kind: type, payload: { ...payload, progress: event.progress } }
+        case 'node.artifact':
+          return { kind: type, payload: { ...payload, artifact: artifact(event.artifact) } }
+        case 'node.log':
+          if (!['debug', 'info', 'warn', 'error'].includes(event.level as string)) throw new TypeError('Runtime node.log level is invalid.')
+          return { kind: type, payload: { ...payload, level: event.level, message: message(event.message) } }
+        case 'node.failed':
+          return {
+            kind: type,
+            payload: {
+              ...payload,
+              ...((paths.get(context.rawRunId)?.length ?? 0) == 0 ? {} : { path: paths.get(context.rawRunId)! }),
+              error: { code: nodeFailureCode(event.code, nodeFailureCodes), message: message(event.message) },
+            },
+          }
+      }
+    }
+
+    throw new TypeError(`Runtime event type ${JSON.stringify(type)} is not supported.`)
+  }
+}
+
+function responseSnapshot(value: unknown): WebhookResponseSnapshot {
+  const source = object(value, 'Runtime response')
+  const headers = webhookHeaderValues(source.headers)
+  if (
+    !validWebhookStatus(source.status) ||
+    typeof source.body !== 'string' ||
+    !['text/plain;charset=UTF-8', 'application/json'].includes(String(source.contentType)) ||
+    headers == null
+  )
+    throw new TypeError('Invalid runtime response.')
+  return { status: source.status, body: source.body, contentType: String(source.contentType), headers }
+}