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

package/src/control/common/requests.ts

@@ -0,0 +1,112 @@
+import { canvasCommandSchema } from '../../canvas/common/commands.ts'
+export { canvasCommandSchema } from '../../canvas/common/commands.ts'
+import { authoringRequestSchema, authoringReadSchema, authoringSearchSchema, authoringSchemaQuery, authoringCheckSchema } from './authoringSchema.ts'
+export * from './authoring.ts'
+import type { JsonValue } from '../../flow/common/change.ts'
+import type { DraftOperation } from './draftOperations.ts'
+
+import { waitCommentSchema } from '../../execution/common/wait.ts'
+import { decodeDraftOperations, draftOperationsSchema } from './draftOperations.ts'
+export { decodeDraftOperations, draftOperationsSchema, resolveDraftOperations, type DraftOperation } from './draftOperations.ts'
+import { z } from 'zod'
+import { resourceNameIssue } from '../../flow/common/change.ts'
+import { createEventSourceSchema, updateEventSourceSchema, eventSourceRevisionSchema } from './eventSourceSchemas.ts'
+
+export const waitActionBodySchema: { parse(value: unknown): { comment?: string | null } } = z.strictObject({ comment: waitCommentSchema })
+
+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 inputs = z.record(z.string(), z.record(z.string(), json))
+const trigger = z.strictObject({ nodeId: id, outputs: z.record(z.string(), json) })
+const schemas = {
+  canvas: z.strictObject({ command: canvasCommandSchema, version }),
+  authoringCheck: authoringCheckSchema,
+  authoringEdit: authoringRequestSchema,
+  authoringRead: authoringReadSchema,
+  authoringSearch: authoringSearchSchema,
+  authoringSchema: authoringSchemaQuery,
+  loadOpenApiDocument: z.strictObject({ url: z.string().min(1).max(8192), version }),
+  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 }),
+  renameFlow: z.strictObject({ name: flowName, version }),
+  changeDraft: z.strictObject({ expectedRevisionId: id, operations: z.array(json).min(1), version }),
+  repairDraft: z.strictObject({ expectedRevisionId: id, version }),
+  upgradeDraft: z.strictObject({ expectedRevisionId: id, version }),
+  setEnabled: z.strictObject({ enabled: z.boolean(), expectedPublicationId: id, version }),
+  updatePresentation: z.strictObject({ expectedRevision: z.int().positive(), value: z.record(z.string(), json), version }),
+  checkFlow: z.strictObject({ engineContract: id, version }),
+  publishFlow: z.strictObject({ engineContract: id, expectedLivePublicationId: id.nullable(), version }),
+  rollbackFlow: z.strictObject({ expectedLivePublicationId: id, version }),
+  createDraftRun: z.strictObject({ engineContract: id, inputs, trigger, version: z.literal(2) }),
+  createLiveRun: z.strictObject({ publicationId: id, inputs, trigger, version: z.literal(2) }),
+  resolveWait: z.strictObject({ action: z.enum(['approve', 'continue', 'reject']), comment: waitCommentSchema, version }),
+  putVariable: z.strictObject({
+    value: z.string().refine((value) => new TextEncoder().encode(value).byteLength <= 65_536, 'Variable value is too large.'),
+  }),
+  queryConnectorAccessCandidates: z.strictObject({
+    providerIds: z
+      .array(id.max(256))
+      .min(1)
+      .refine((ids) => new Set(ids).size == ids.length, 'Duplicate provider IDs.'),
+    version,
+  }),
+  removeConnectionUsage: z.strictObject({ connectionId: id, expectedRevisionId: id, expectedAccessRevision: z.int().nonnegative(), version }),
+  setConnectorService: z.strictObject({ expectedAccessRevision: z.int().nonnegative(), version }),
+  addProviderAccessBinding: z.strictObject({ accessBindingId: id, expectedAccessRevision: z.int().nonnegative(), version }),
+  removeProviderAccessBinding: z.strictObject({ accessBindingId: id, expectedAccessRevision: z.int().nonnegative(), version }),
+  versionOnly: z.strictObject({ version }),
+}
+
+function decoder<Value>(schema: z.ZodType<Value>): (value: unknown) => Value {
+  return (value) => schema.parse(value)
+}
+
+export const controlRequests = {
+  canvas: decoder(schemas.canvas),
+  authoringCheck: decoder(schemas.authoringCheck),
+  authoringEdit: decoder(schemas.authoringEdit),
+  authoringRead: decoder(schemas.authoringRead),
+  authoringSearch: decoder(schemas.authoringSearch),
+  authoringSchema: decoder(schemas.authoringSchema),
+  loadOpenApiDocument: decoder(schemas.loadOpenApiDocument),
+  createEventSource: decoder(schemas.createEventSource),
+  updateEventSource: decoder(schemas.updateEventSource),
+  eventSourceRevision: decoder(schemas.eventSourceRevision),
+  importFlow: decoder(schemas.importFlow),
+  createFlow: decoder(schemas.createFlow),
+  renameFlow: decoder(schemas.renameFlow),
+  changeDraft(value: unknown): { expectedRevisionId: string; operations: readonly DraftOperation[]; version: 1 } {
+    const body = schemas.changeDraft.parse(value)
+    return { ...body, operations: decodeDraftOperations(body.operations) }
+  },
+  repairDraft: decoder(schemas.repairDraft),
+  upgradeDraft: decoder(schemas.upgradeDraft),
+  setEnabled: decoder(schemas.setEnabled),
+  updatePresentation: decoder(schemas.updatePresentation),
+  checkFlow: decoder(schemas.checkFlow),
+  publishFlow: decoder(schemas.publishFlow),
+  rollbackFlow: decoder(schemas.rollbackFlow),
+  createDraftRun: decoder(schemas.createDraftRun),
+  createLiveRun: decoder(schemas.createLiveRun),
+  resolveWait: decoder(schemas.resolveWait),
+  putVariable: decoder(schemas.putVariable),
+  queryConnectorAccessCandidates: decoder(schemas.queryConnectorAccessCandidates),
+  removeConnectionUsage: decoder(schemas.removeConnectionUsage),
+  setConnectorService: decoder(schemas.setConnectorService),
+  addProviderAccessBinding: decoder(schemas.addProviderAccessBinding),
+  removeProviderAccessBinding: decoder(schemas.removeProviderAccessBinding),
+  versionOnly: decoder(schemas.versionOnly),
+}
+
+export function controlRequestSchema(name: keyof typeof controlRequests): JsonValue {
+  const schema = z.toJSONSchema(schemas[name], { io: 'input' })
+  if (name == 'changeDraft') return { ...schema, properties: { ...schema.properties, operations: draftOperationsSchema() } } as unknown as JsonValue
+  return schema as JsonValue
+}
+
+export { authoringExample, authoringExamples } from './authoringExamples.ts'

package/src/control/common/resultQuery.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod'
+
+export const resultQuerySchema = z.strictObject({
+  pointer: z.string().max(4096).default(''),
+  offset: z.number().int().nonnegative().default(0),
+  limit: z.number().int().min(1).max(100).default(20),
+  maxBytes: z.number().int().min(1).max(1048576).default(15000),
+})

package/src/control/common/results.ts

@@ -0,0 +1,176 @@
+import type { JsonValue } from '../../flow/common/change.ts'
+
+import { z } from 'zod'
+import { resultQuerySchema } from './resultQuery.ts'
+
+const json: z.ZodType<JsonValue> = z.json()
+const entry = z.object({
+  pointer: z.string(),
+  type: z.enum(['object', 'array', 'string', 'number', 'boolean', 'null']),
+  length: z.number().int().nonnegative().optional(),
+  complete: z.boolean(),
+  value: json.optional(),
+})
+const page = entry.extend({
+  offset: z.number().int().nonnegative(),
+  nextOffset: z.number().int().positive().optional(),
+  entries: z.array(entry).optional(),
+})
+const result = z.object({
+  resultId: z.string().min(1),
+  callId: z.string().min(1),
+  toolId: z.string().min(1),
+  source: z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('connector'), action: z.string().min(1) }),
+    z.object({ kind: z.literal('code') }),
+    z.object({ kind: z.literal('workflow'), flowId: z.string().min(1) }),
+  ]),
+  bytes: z.number().int().nonnegative(),
+  digest: z.string().regex(/^[a-f0-9]{64}$/),
+  createdAt: z.string().datetime(),
+})
+
+export type ResultCall =
+  | { readonly id: string; readonly kind: 'connector'; readonly action: string; readonly connectionId?: string }
+  | { readonly id: string; readonly kind: 'code' }
+  | { readonly id: string; readonly kind: 'workflow'; readonly flowId: string }
+
+export interface ResultInfo {
+  readonly resultId: string
+  readonly callId: string
+  readonly toolId: string
+  readonly source: { readonly kind: 'connector'; readonly action: string } | { readonly kind: 'code' } | { readonly kind: 'workflow'; readonly flowId: string }
+  readonly bytes: number
+  readonly digest: string
+  readonly createdAt: string
+}
+interface ResultEntry {
+  readonly pointer: string
+  readonly type: 'object' | 'array' | 'string' | 'number' | 'boolean' | 'null'
+  readonly length?: number
+  readonly complete: boolean
+  readonly value?: JsonValue
+}
+export interface ResultPage extends ResultEntry {
+  readonly offset: number
+  readonly nextOffset?: number
+  readonly entries?: readonly ResultEntry[]
+}
+export interface ResultQuery {
+  readonly pointer?: string
+  readonly offset?: number
+  readonly limit?: number
+  readonly maxBytes?: number
+}
+const listSchema = z.object({ version: z.literal(1), runId: z.string(), results: z.array(result), nextAfter: z.string().optional() })
+const readSchema = z.object({ version: z.literal(1), runId: z.string(), result, page })
+export function parseResultQuery(value: unknown): Required<ResultQuery> {
+  return resultQuerySchema.parse(value)
+}
+export function decodeResultList(value: unknown): {
+  readonly version: 1
+  readonly runId: string
+  readonly results: readonly ResultInfo[]
+  readonly nextAfter?: string
+} {
+  return listSchema.parse(value)
+}
+export function decodeResultRead(value: unknown): { readonly version: 1; readonly runId: string; readonly result: ResultInfo; readonly page: ResultPage } {
+  return readSchema.parse(value)
+}
+
+const encoder = new TextEncoder()
+function bytes(value: unknown): number {
+  return encoder.encode(JSON.stringify(value)).byteLength
+}
+
+function describe(item: JsonValue, path: string): ResultEntry {
+  const type = item === null ? 'null' : Array.isArray(item) ? 'array' : (typeof item as 'object' | 'string' | 'number' | 'boolean')
+  return {
+    pointer: path,
+    type,
+    ...(type == 'array' ? { length: (item as readonly JsonValue[]).length } : {}),
+    ...(type == 'object' ? { length: Object.keys(item as object).length } : {}),
+    complete: false,
+  }
+}
+
+export function readResult(value: JsonValue, query: ResultQuery = {}): ResultPage {
+  const { pointer, offset, limit, maxBytes } = parseResultQuery(query)
+  let selected = value
+  if (pointer != '') {
+    if (!pointer.startsWith('/')) throw new Error('Result pointer must be a JSON Pointer.')
+    for (const part of pointer.slice(1).split('/')) {
+      if (/~(?:[^01]|$)/.test(part)) throw new Error('Result pointer has an invalid escape.')
+      const key = part.replace(/~1/g, '/').replace(/~0/g, '~')
+      if (selected == null || typeof selected != 'object' || !Object.hasOwn(selected, key)) throw new Error('Result path does not exist.')
+      if (Array.isArray(selected)) {
+        if (!/^(0|[1-9]\d*)$/.test(key)) throw new Error('Invalid result array index.')
+        selected = selected[Number(key)]!
+      } else selected = (selected as Readonly<Record<string, JsonValue>>)[key]!
+    }
+  }
+  const description = describe(selected, pointer)
+  const whole = { ...description, complete: true, offset, value: selected }
+  if (
+    offset == 0 &&
+    (query.limit == null || description.length == null || description.length <= limit) &&
+    (typeof selected != 'string' || selected.length <= maxBytes) &&
+    bytes(whole) <= maxBytes
+  )
+    return whole
+  const root = description
+  if (typeof selected == 'string') {
+    let length = 0
+    let start = 0
+    for (let index = 0; index < selected.length; length++) {
+      if (length == offset) start = index
+      const point = selected.codePointAt(index)!
+      index += point > 0xffff ? 2 : 1
+    }
+    if (offset >= length) throw new Error('Result offset is out of range.')
+    const budget = maxBytes - bytes({ ...root, length, offset, value: '', nextOffset: length })
+    let used = 0
+    let cursor = start
+    let end = offset
+    while (cursor < selected.length) {
+      const point = selected.codePointAt(cursor)!
+      // JSON escapes controls and lone surrogates; valid pairs use four UTF-8 bytes.
+      let size
+      if (point == 0x22 || point == 0x5c || point == 8 || point == 9 || point == 10 || point == 12 || point == 13) size = 2
+      else if (point < 0x20 || (point >= 0xd800 && point <= 0xdfff)) size = 6
+      else if (point < 0x80) size = 1
+      else if (point < 0x800) size = 2
+      else if (point <= 0xffff) size = 3
+      else size = 4
+      if (used + size > budget) break
+      cursor += point > 0xffff ? 2 : 1
+      used += size
+      end++
+    }
+    const text = selected.slice(start, cursor)
+    if (end == offset) throw new Error('Result byte budget cannot fit a string character and page metadata.')
+    return { ...root, complete: offset == 0 && end == length, length, offset, value: text, ...(end < length ? { nextOffset: end } : {}) }
+  }
+  if (selected == null || typeof selected != 'object') throw new Error('Result cannot be paged.')
+  const keys = Object.keys(selected)
+  if (offset >= keys.length) throw new Error('Result offset is out of range.')
+  const entries: ResultEntry[] = []
+  const overhead = bytes({ ...root, offset, entries: [], nextOffset: keys.length })
+  let used = overhead
+  for (const key of keys.slice(offset, offset + limit)) {
+    const path = `${pointer}/${key.replace(/~/g, '~0').replace(/\//g, '~1')}`
+    const item = Array.isArray(selected) ? selected[Number(key)]! : (selected as Readonly<Record<string, JsonValue>>)[key]!
+    const metadata = describe(item, path)
+    const full = { ...metadata, complete: true, value: item }
+    const fullBytes = bytes(full)
+    const next = overhead + fullBytes <= maxBytes ? full : metadata
+    const size = (next === full ? fullBytes : bytes(metadata)) + (entries.length == 0 ? 0 : 1)
+    if (used + size > maxBytes) break
+    entries.push(next)
+    used += size
+  }
+  if (entries.length == 0) throw new Error('Result property name exceeds the preview limit. Download the full result.')
+  const end = offset + entries.length
+  return { ...root, offset, entries, ...(end < keys.length ? { nextOffset: end } : {}) }
+}

package/src/control/common/revisionDecoders.ts

@@ -0,0 +1,52 @@
+import type { Draft, DraftChange, DraftSync, Presentation, RevisionMetadata } from './api.ts'
+
+import { decodeRevisionContent } from '../../flow/common/encoding.ts'
+import { integer, invalidResponse, jsonValue, record, string } from './decoding.ts'
+
+function revisionMetadata(value: unknown): RevisionMetadata {
+  const source = record(value)
+  const parentRevisionId = source.parentRevisionId
+  if (source.version != 1 || (parentRevisionId !== null && typeof parentRevisionId != 'string')) return invalidResponse()
+  return {
+    actorId: string(source.actorId),
+    createdAt: string(source.createdAt),
+    digest: string(source.digest),
+    flowId: string(source.flowId),
+    modelVersion: integer(source.modelVersion),
+    parentRevisionId,
+    revisionId: string(source.revisionId),
+    version: 1,
+  }
+}
+
+export function draft(value: unknown): Draft {
+  const source = record(value)
+  try {
+    return { ...revisionMetadata(source), content: decodeRevisionContent(source.content) }
+  } catch {
+    return invalidResponse()
+  }
+}
+
+export function presentation(value: unknown): Presentation {
+  const source = record(value)
+  if (source.version != 1 || integer(source.revision) < 1) return invalidResponse()
+  return {
+    revision: integer(source.revision),
+    updatedAt: string(source.updatedAt),
+    value: Object.fromEntries(Object.entries(record(source.value)).map(([key, item]) => [key, jsonValue(item)])),
+    version: 1,
+  }
+}
+
+export function draftChange(value: unknown): DraftChange {
+  const source = record(value)
+  if (source.version != 1) return invalidResponse()
+  return { revision: revisionMetadata(source.revision), version: 1 }
+}
+
+export function draftSync(value: unknown): DraftSync {
+  const source = record(value)
+  if (source.version != 1 || source.kind != 'snapshot') return invalidResponse()
+  return { draft: draft(source.draft), kind: 'snapshot', version: 1 }
+}

package/src/control/common/runDecoders.ts

@@ -0,0 +1,240 @@
+import type { RunStatus } from '../../execution/common/runLifecycle.ts'
+import type { JsonValue, WaitAction } from '../../flow/common/change.ts'
+import type { Run, RunCancellation, RunChannel, RunDetails, RunInitiator, RunPage, RunResult } from './api.ts'
+
+import { runStatuses } from '../../execution/common/runLifecycle.ts'
+import { requiredFields, integer, invalidResponse, record, string } from './decoding.ts'
+
+const runStatusSet: ReadonlySet<RunStatus> = new Set(runStatuses)
+
+function runStatus(value: unknown): RunStatus {
+  return typeof value == 'string' && runStatusSet.has(value as RunStatus) ? (value as RunStatus) : invalidResponse()
+}
+
+function run(value: unknown): Run {
+  const source = record(value)
+  const kind = source.source
+  const startedAt = source.startedAt
+  const finishedAt = source.finishedAt
+  if (source.version != 1 || (kind != 'draft' && kind != 'live')) return invalidResponse()
+  if (startedAt != null && typeof startedAt != 'string') return invalidResponse()
+  if (finishedAt != null && typeof finishedAt != 'string') return invalidResponse()
+  return {
+    createdAt: string(source.createdAt),
+    ...(finishedAt == null ? {} : { finishedAt }),
+    flowId: string(source.flowId),
+    revisionId: string(source.revisionId),
+    runId: string(source.runId),
+    source: kind as Run['source'],
+    ...(startedAt == null ? {} : { startedAt }),
+    status: runStatus(source.status),
+    version: 1,
+  }
+}
+
+function runWaiting(value: unknown) {
+  const source = record(value)
+  requiredFields(source, ['actions', 'expiresAt', 'nodeId', 'prompt', 'waitId', 'waitingSince'])
+  const actions = source.actions
+  if (
+    !Array.isArray(actions) ||
+    !((actions.length == 1 && actions[0] == 'continue') || (actions.length == 2 && actions[0] == 'approve' && actions[1] == 'reject'))
+  ) {
+    return invalidResponse()
+  }
+  return {
+    actions: actions as unknown as readonly ['continue'] | readonly ['approve', 'reject'],
+    ...(source.autoContinueAt === undefined ? {} : { autoContinueAt: string(source.autoContinueAt) }),
+    expiresAt: string(source.expiresAt),
+    nodeId: string(source.nodeId),
+    prompt: string(source.prompt),
+    waitId: string(source.waitId),
+    waitingSince: string(source.waitingSince),
+  }
+}
+
+function workflowIdentity(value: unknown) {
+  const ref = record(value)
+  return {
+    flowId: string(ref.flowId),
+    runId: string(ref.runId),
+    nodeId: string(ref.nodeId),
+    executionId: string(ref.executionId),
+    ...(ref.callId == null ? {} : { callId: string(ref.callId) }),
+  }
+}
+
+function runInitiator(value: unknown): RunInitiator {
+  const source = record(value)
+  const channels: readonly RunChannel[] = ['workbench', 'cli', 'mcp', 'api', 'trigger', 'workflow']
+  if (!channels.includes(source.channel as RunChannel)) return invalidResponse()
+  return {
+    channel: source.channel as RunChannel,
+    ...(source.actorId === undefined ? {} : { actorId: string(source.actorId) }),
+  }
+}
+
+export function runDetails(value: unknown): RunDetails {
+  const source = record(value)
+  const summary = run(source)
+  const eventsExpiresAt = source.eventsExpiresAt
+  if (eventsExpiresAt != null && typeof eventsExpiresAt != 'string') return invalidResponse()
+  if (source.waiting !== undefined || !Array.isArray(source.waits)) return invalidResponse()
+  const waits = source.waits.map(runWaiting)
+  if (
+    new Set(waits.map((wait) => wait.waitId)).size != waits.length ||
+    (summary.status == 'waiting' && waits.length == 0 && (!Array.isArray(source.calls) || source.calls.length == 0)) ||
+    (['completed', 'failed', 'canceled', 'indeterminate'].includes(summary.status) && waits.length > 0)
+  )
+    return invalidResponse()
+  if (source.occurrenceId !== undefined && source.triggerNodeId === undefined) return invalidResponse()
+  const state = { status: summary.status, waits }
+  if (source.calls !== undefined && !Array.isArray(source.calls)) return invalidResponse()
+  const details = {
+    ...summary,
+    ...(source.initiator === undefined ? {} : { initiator: runInitiator(source.initiator) }),
+    ...errorHandling(source),
+    ...(source.triggerNodeId === undefined ? {} : { triggerNodeId: string(source.triggerNodeId) }),
+    ...(source.caller === undefined ? {} : { caller: workflowIdentity(source.caller) }),
+    ...(source.calls === undefined
+      ? {}
+      : {
+          calls: (source.calls as unknown[]).map((item) =>
+            Object.assign(workflowIdentity(item), { status: record(item).status === null ? null : runStatus(record(item).status) }),
+          ),
+        }),
+    closureDigest: string(source.closureDigest),
+    engineContract: string(source.engineContract),
+    engineDigest: string(source.engineDigest),
+    ...(eventsExpiresAt == null ? {} : { eventsExpiresAt }),
+    modelVersion: integer(source.modelVersion),
+    sharedAccessDigest: string(source.sharedAccessDigest),
+    revisionDigest: string(source.revisionDigest),
+    ...state,
+  }
+  switch (summary.source) {
+    case 'draft':
+      return { ...details, source: 'draft' }
+    case 'live':
+      return {
+        ...details,
+        publicationId: string(source.publicationId),
+        source: 'live',
+        ...(source.occurrenceId === undefined ? {} : { occurrenceId: string(source.occurrenceId), triggerNodeId: string(source.triggerNodeId) }),
+      }
+  }
+}
+
+export function runPage(value: unknown): RunPage {
+  const source = record(value)
+  const nextCursor = source.nextCursor
+  if (source.version != 1 || !Array.isArray(source.runs)) return invalidResponse()
+  if (nextCursor != null && typeof nextCursor != 'string') return invalidResponse()
+  return {
+    flowId: string(source.flowId),
+    ...(nextCursor == null ? {} : { nextCursor }),
+    runs: source.runs.map(run),
+    version: 1,
+  }
+}
+
+export function runCancellation(value: unknown): RunCancellation {
+  const source = record(value)
+  const status = runStatus(source.status)
+  if (
+    source.version != 1 ||
+    typeof source.cancelAccepted != 'boolean' ||
+    status == 'queued' ||
+    status == 'starting' ||
+    status == 'running' ||
+    status == 'waiting'
+  ) {
+    return invalidResponse()
+  }
+  return { cancelAccepted: source.cancelAccepted, runId: string(source.runId), status, version: 1 }
+}
+
+export function waitResolution(value: unknown) {
+  const source = record(value)
+  requiredFields(source, ['action', 'comment', 'resolutionAccepted', 'resolvedAt', 'runId', 'status', 'version', 'waitId'])
+  const action = source.action
+  const resolvedAt = source.resolvedAt
+  if (
+    source.version != 1 ||
+    typeof source.resolutionAccepted != 'boolean' ||
+    (source.comment !== null && typeof source.comment != 'string') ||
+    (action !== null && action != 'approve' && action != 'continue' && action != 'reject') ||
+    (resolvedAt !== null && typeof resolvedAt != 'string') ||
+    (action === null) != (resolvedAt === null) ||
+    (source.resolutionAccepted && action === null)
+  ) {
+    return invalidResponse()
+  }
+  return {
+    action: action as WaitAction | null,
+    comment: source.comment as string | null,
+    resolutionAccepted: source.resolutionAccepted,
+    resolvedAt: resolvedAt as string | null,
+    runId: string(source.runId),
+    status: runStatus(source.status),
+    version: 1 as const,
+    waitId: string(source.waitId),
+  }
+}
+
+export function runResult(value: unknown): RunResult {
+  const source = record(value)
+  const status = source.status
+  if (source.version != 1) return invalidResponse()
+  const base = { finishedAt: string(source.finishedAt), runId: string(source.runId), version: 1 as const }
+  if (status == 'completed') {
+    if (!Object.hasOwn(source, 'result')) return invalidResponse()
+    return { ...base, result: source.result as JsonValue, status: 'completed' }
+  }
+  if (status == 'canceled') return { ...base, status: 'canceled' }
+  if (status == 'failed') {
+    const error = record(source.error)
+    return { ...base, error: runFailure(error), status: 'failed' }
+  }
+  if (status == 'indeterminate') {
+    const error = record(source.error)
+    return { ...base, error: runFailure(error), status: 'indeterminate' }
+  }
+  return invalidResponse()
+}
+
+function errorHandling(source: Record<string, unknown>): Pick<RunDetails, 'errorDispatches' | 'errorSource'> {
+  const errorSource = source.errorSource == null ? undefined : record(source.errorSource)
+  if (source.errorDispatches != null && !Array.isArray(source.errorDispatches)) return invalidResponse()
+  return {
+    ...(errorSource == null ? {} : { errorSource: { flowId: string(errorSource.flowId), runId: string(errorSource.runId) } }),
+    ...(source.errorDispatches == null
+      ? {}
+      : {
+          errorDispatches: (source.errorDispatches as unknown[]).map((value) => {
+            const dispatch = record(value)
+            const flowId = string(dispatch.flowId)
+            switch (dispatch.status) {
+              case 'pending':
+                return { status: 'pending' as const, flowId }
+              case 'dispatched':
+                return { status: 'dispatched' as const, flowId, runId: string(dispatch.runId) }
+              case 'failed':
+                return { status: 'failed' as const, flowId, message: string(dispatch.message) }
+              default:
+                return invalidResponse()
+            }
+          }),
+        }),
+  }
+}
+
+export function runFailure(error: Record<string, unknown>) {
+  return {
+    code: string(error.code),
+    message: string(error.message),
+    ...(error.nodeId === undefined ? {} : { nodeId: string(error.nodeId) }),
+    ...(error.jobId === undefined ? {} : { jobId: string(error.jobId) }),
+    ...(error.path === undefined ? {} : { path: (Array.isArray(error.path) ? error.path : invalidResponse()).map(string) }),
+  }
+}

package/src/control/common/triggerCatalog.ts

@@ -0,0 +1,89 @@
+import type { TriggerKeySnapshot } from '../../flow/common/change.ts'
+import type { UiLanguage } from '../../localization/common/languages.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
+  readonly definitions: readonly TriggerKeySnapshot[]
+  readonly display: Readonly<Record<string, TriggerDisplay>>
+}
+
+export interface TriggerCatalogCache {
+  readonly data: TriggerCatalog
+  readonly etag: string | null
+}
+
+export function decodeTriggerCatalog(value: unknown): TriggerCatalog {
+  const source = record(value)
+  requiredFields(source, ['version', 'locale', 'definitions', 'display'])
+  if (source.version != 3 || !isUiLanguage(source.locale) || !Array.isArray(source.definitions)) return invalidResponse()
+  const definitions = source.definitions.map(triggerKey)
+  const entries = record(source.display)
+  const keys = new Set(definitions.map((definition) => definition.key))
+  if (keys.size != definitions.length || Object.keys(entries).length != keys.size) return invalidResponse()
+  const display = Object.fromEntries(
+    definitions.map((definition) => {
+      const { key } = definition
+      const copy = record(entries[key])
+      requiredFields(copy, ['configInputs', 'configInputLabels', 'displayName', 'description', 'outputs'])
+      return [
+        key,
+        {
+          configInputs: descriptions(
+            copy.configInputs,
+            definition.configInputs.flatMap((field) => ('handle' in field ? [field.handle] : [])),
+          ),
+          configInputLabels: labels(
+            copy.configInputLabels,
+            definition.configInputs.flatMap((field) => ('handle' in field ? [field.handle] : [])),
+          ),
+          displayName: string(copy.displayName),
+          description: string(copy.description),
+          outputs: descriptions(
+            copy.outputs,
+            definition.outputs.map((field) => field.handle),
+          ),
+        },
+      ]
+    }),
+  )
+  return { version: 3, locale: source.locale, definitions, display }
+}
+
+function descriptions(value: unknown, handles: readonly string[]): Readonly<Record<string, string>> {
+  const source = record(value)
+  exact(source, handles)
+  return Object.fromEntries(Object.entries(source).map(([handle, description]) => [handle, string(description)]))
+}
+
+function labels(value: unknown, handles: readonly string[]): Readonly<Record<string, string>> {
+  const source = record(value)
+  if (Object.keys(source).some((handle) => !handles.includes(handle))) return invalidResponse()
+  return Object.fromEntries(
+    Object.entries(source).map(([handle, label]) => {
+      const text = string(label)
+      return text.trim().length == 0 ? invalidResponse() : [handle, text]
+    }),
+  )
+}
+
+export function searchTriggerKeys(keys: readonly TriggerKeySummary[], query?: string): readonly TriggerKeySummary[] {
+  if (query == null) return keys
+  const term = query.toLowerCase()
+  return keys.filter((item) =>
+    [item.description, item.displayName, item.key, item.name, item.provider, item.type].some((value) => value.toLowerCase().includes(term)),
+  )
+}