@oomol-lab/open-flow 0.1.0-beta.85 → 0.1.0-beta.86

package/src/control/common/api.ts

@@ -64,10 +64,27 @@ export type { WorkflowFile, WorkflowCleanupSummary } from '../../flow/common/wor
 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'
+import type { ControlCacheOptions } from './catalogCache.ts'
 
+import { ControlCatalogCache } from './catalogCache.ts'
 import { flowCheck } from './checkDecoders.ts'
-import { connection, connectorAccess, connectorAccessSnapshot, connectorAccessCandidatesBatch, connectorAction, leinaBots } from './connectorDecoders.ts'
-import { allConnectorConnectionsQuery, connectorActionQuery, connectorConnectionsQuery, connectorProvidersQuery } from './connectorQueries.ts'
+import {
+  connection,
+  connectorAccess,
+  connectorAccessSnapshot,
+  connectorAccessCandidatesBatch,
+  connectorAction,
+  connectorActionMetadata,
+  leinaBots,
+} from './connectorDecoders.ts'
+import {
+  allConnectorConnectionsQuery,
+  connectorActionQuery,
+  connectorActionMetadataQuery,
+  connectorConnectionsQuery,
+  connectorProvidersQuery,
+} from './connectorQueries.ts'
+export type { ControlCacheDelegate, ControlCacheOptions, ControlCacheRead } from './catalogCache.ts'
 import { requiredFields, integer, invalidResponse, jsonValue, record, string } from './decoding.ts'
 import { errorListener, flow, flowPage, variable, variableListItem, variableReferences } from './flowDecoders.ts'
 import { live, publication, publicationPage, publishOperation } from './publicationDecoders.ts'
@@ -726,6 +743,7 @@ export function decodeRunEvent(value: unknown) {
             nodeKind !== 'approval' &&
             nodeKind !== 'condition' &&
             nodeKind !== 'connector' &&
+            nodeKind !== 'connector-proxy' &&
             nodeKind !== 'javascript' &&
             nodeKind !== 'decision' &&
             nodeKind !== 'openapi' &&
@@ -850,10 +868,14 @@ export type ConditionalResult<T> =
 export class ControlClient {
   private readonly requestControl: ControlRequest
   private readonly channel: 'workbench' | 'cli' | 'api'
+  private readonly catalogCache?: ControlCatalogCache
+  private readonly options: { readonly cache?: ControlCacheOptions }
 
-  constructor(requestControl: ControlRequest, channel: 'workbench' | 'cli' | 'api' = 'api') {
+  constructor(requestControl: ControlRequest, channel: 'workbench' | 'cli' | 'api' = 'api', options: { readonly cache?: ControlCacheOptions } = {}) {
+    this.options = options
     this.channel = channel
     this.requestControl = requestControl
+    if (options.cache != null) this.catalogCache = new ControlCatalogCache(options.cache)
   }
 
   async loadOpenApiDocument(url: string, signal?: AbortSignal): Promise<JsonValue> {
@@ -1140,6 +1162,14 @@ export class ControlClient {
   }
 
   async getTriggerCatalog(locale: string, cached?: TriggerCatalogCache, signal?: AbortSignal): Promise<TriggerCatalogCache> {
+    if (this.catalogCache != null) {
+      const result = await this.catalogResponse(
+        { path: `/v1/trigger-keys/catalog?locale=${encodeURIComponent(locale)}`, decode: decodeTriggerCatalog },
+        300_000,
+        signal,
+      )
+      return { data: result.data, etag: result.etag }
+    }
     const headers = new Headers()
     if (cached?.etag) headers.set('if-none-match', cached.etag)
     const response = await this.response(`/v1/trigger-keys/catalog?locale=${encodeURIComponent(locale)}`, { headers, signal }, true)
@@ -1151,6 +1181,23 @@ export class ControlClient {
   }
 
   async getTriggerKey(key: string, signal?: AbortSignal): Promise<TriggerKeySnapshot> {
+    if (this.catalogCache != null)
+      return (
+        await this.catalogResponse(
+          {
+            path: `/v1/trigger-keys/${segment(key)}`,
+            decode: (value) => {
+              const source = record(value)
+              if (source.version != 1) return invalidResponse()
+              const definition = triggerKey(source.definition)
+              if (definition.key != key) return invalidResponse('Trigger key does not match the requested definition.')
+              return definition
+            },
+          },
+          300_000,
+          signal,
+        )
+      ).data
     const source = record(await this.request(`/v1/trigger-keys/${segment(key)}`, { signal }))
     if (source.version != 1) return invalidResponse()
     return triggerKey(source.definition)
@@ -1265,6 +1312,7 @@ export class ControlClient {
 
   async listConnectorProviders(signal?: AbortSignal, flowId?: string, locale?: string): Promise<readonly ConnectorProvider[]> {
     const query = connectorProvidersQuery(flowId, locale)
+    if (this.catalogCache != null) return (await this.catalogResponse(query, 300_000, signal)).data
     return this.connectorRequest(query.path, 'providers', signal, query.decode)
   }
 
@@ -1350,6 +1398,21 @@ export class ControlClient {
     return this.connectorRequest(query.path, 'actions', signal, query.decode, fresh)
   }
 
+  async listConnectorActionMetadata(serviceId?: string, signal?: AbortSignal, flowId?: string, locale?: string): Promise<readonly ConnectorActionMetadata[]> {
+    return this.connectorMetadata(
+      { ...(serviceId == null ? {} : { service: serviceId }), ...(flowId == null ? {} : { flowId }), ...(locale == null ? {} : { locale }) },
+      signal,
+    )
+  }
+
+  async searchConnectorActionMetadata(query: string, signal?: AbortSignal, flowId?: string, locale?: string): Promise<readonly ConnectorActionMetadata[]> {
+    return this.connectorMetadata({ q: query.trim(), ...(flowId == null ? {} : { flowId }), ...(locale == null ? {} : { locale }) }, signal)
+  }
+
+  async getConnectorActionMetadata(actionId: string, signal?: AbortSignal, flowId?: string, locale?: string, fresh = false): Promise<ConnectorActionMetadata> {
+    return (await this.catalogResponse(connectorActionMetadataQuery(actionId, flowId, locale), 30_000, signal, fresh)).data
+  }
+
   async listAllConnectorConnections(signal?: AbortSignal, flowId?: string, fresh = false): Promise<readonly ConnectorConnection[]> {
     const query = allConnectorConnectionsQuery(flowId)
     return this.connectorRequest(query.path, 'connections', signal, query.decode, fresh)
@@ -1618,6 +1681,38 @@ export class ControlClient {
     )
   }
 
+  private async catalogResponse<Value>(
+    query: { readonly path: string; readonly decode: (value: unknown) => Value },
+    maxAgeMs: number,
+    signal?: AbortSignal,
+    fresh = false,
+  ) {
+    if (this.catalogCache != null)
+      return this.catalogCache.read(query, (etag) => this.readCatalog({ path: query.path, decode: jsonValue }, etag), maxAgeMs, signal, fresh)
+    const response = await this.readCatalog(query, null, signal)
+    if (!response.modified) return invalidResponse()
+    return { data: response.data, etag: response.etag }
+  }
+
+  private async connectorMetadata(parameters: Readonly<Record<string, string>>, signal?: AbortSignal): Promise<readonly ConnectorActionMetadata[]> {
+    const query = new URLSearchParams(parameters).toString()
+    return (
+      await this.catalogResponse(
+        {
+          path: `/v1/connector/action-metadata${query ? `?${query}` : ''}`,
+          decode: (value) => {
+            const source = record(value)
+            requiredFields(source, ['actions', 'version'])
+            if (source.version != 1 || !Array.isArray(source.actions)) return invalidResponse()
+            return source.actions.map(connectorActionMetadata)
+          },
+        },
+        30_000,
+        signal,
+      )
+    ).data
+  }
+
   private async connectorActions(parameters: Readonly<Record<string, string>>, signal?: AbortSignal): Promise<readonly ConnectorAction[]> {
     const query = Object.entries(parameters)
       .map(([key, value]) => `${segment(key)}=${segment(value)}`)
@@ -1642,6 +1737,7 @@ export class ControlClient {
   }
 
   protected async response(path: string, init: RequestInit, allowNotModified = false): Promise<Response> {
+    if (this.options.cache?.mode == 'offline') throw new ApiError(503, 'control.offline', 'Network requests are disabled for this Control client.')
     const headers = new Headers(init.headers)
     if (init.body != null) headers.set('content-type', 'application/json')
     const response = await this.requestControl(path, { ...init, headers })

package/src/control/common/authoring.ts

@@ -16,7 +16,7 @@ import type { AuthoringRead, AuthoringRequest, AuthoringSearch, AuthoringSource,
 import type { AuthoringAgentTool, AuthoringCapability } from './authoringTools.ts'
 
 import { dequal } from 'dequal/lite'
-import { connectorOutputMode } from '../../connector/common/actionSchema.ts'
+import { connectorProxyConfigSchema, connectorProxyInputs, connectorProxyTask } from '../../connector/common/proxy.ts'
 import { decisionTask } from '../../decision/common/decision.ts'
 import { supportsNodeRetry, isTriggerNode, applyFlowChanges, decodeChangeOperations, upgradeRevisionContent } from '../../flow/common/change.ts'
 import { nodeInputMappings } from '../../flow/common/condition.ts'
@@ -40,6 +40,7 @@ import {
   updateStartInputDefs,
   updateOutputsDefs,
   renameFlowOutputSources,
+  setInputMappings,
 } from '../../flow/common/nodeChanges.ts'
 import { retryConfigurationSchema } from '../../flow/common/retry.ts'
 import { httpRequestTask, httpRequestConfigSchema, httpRequestInputs } from '../../http/common/httpRequest.ts'
@@ -147,7 +148,7 @@ export function authoringNode(content: RevisionContent, ref: string) {
         ),
       }
     else if (task.executor.kind == 'workflow') config = { flowId: task.executor.flowId }
-    else if (task.executor.kind == 'http-request' || task.executor.kind == 'skip-duplicates') {
+    else if (task.executor.kind == 'http-request' || task.executor.kind == 'skip-duplicates' || task.executor.kind == 'connector-proxy') {
       const { kind: _kind, ...settings } = task.executor
       config = settings
     } else if (task.executor.kind == 'openapi') {
@@ -319,7 +320,7 @@ export interface AuthoringHost {
   workflow?(flowId: string): Promise<WorkflowContract | WorkflowCandidate>
   id(label: string): string
   action(id: string): Promise<ConnectorAction>
-  trigger(key: string): TriggerKeySnapshot
+  trigger(key: string): TriggerKeySnapshot | Promise<TriggerKeySnapshot>
   openapi(url: string): Promise<JsonValue>
 }
 function merge(base: unknown, patch: unknown): unknown {
@@ -407,13 +408,20 @@ export async function compileAuthoring(base: RevisionContent, request: Authoring
 
   async function connectorTask(config: Record<string, unknown>, name: string): Promise<ManagedTaskDefinition> {
     const action = await host.action(String(config.action))
+    // The source owns projection. A whole-response port carries the root schema;
+    // named ports carry their field schemas, including a field named "output".
+    const wholeResponse =
+      action.outputSchema !== undefined &&
+      Object.keys(action.outputs).length == 1 &&
+      Object.hasOwn(action.outputs, 'output') &&
+      dequal(action.outputs.output!.jsonSchema, action.outputSchema)
     return {
       name,
       executor: {
         kind: 'connector',
         action: action.actionId,
         ...(config.connectionId == null ? {} : { connectionId: String(config.connectionId) }),
-        ...(action.outputSchema !== undefined && connectorOutputMode(action.outputSchema) == 'value' ? { outputMode: 'value' as const } : {}),
+        ...(wholeResponse ? { outputMode: 'value' as const } : {}),
       },
       inputs: Object.entries(action.inputs).map(([handle, port]) => Object.assign({ handle }, port)),
       outputs: Object.entries(action.outputs).map(([handle, port]) => Object.assign({ handle }, port)),
@@ -524,7 +532,10 @@ export async function compileAuthoring(base: RevisionContent, request: Authoring
       } else if (type == 'decision') task = decisionTask(config.questions as Parameters<typeof decisionTask>[0], String(update.name))
       else if (type == 'skip-duplicates')
         task = { ...before, name: String(update.name), executor: { kind: 'skip-duplicates', ...skipDuplicatesConfigSchema.parse(config) } }
-      else if (type == 'http-request') {
+      else if (type == 'connector-proxy') {
+        task = connectorProxyTask(connectorProxyConfigSchema.parse(config), String(update.name), before)
+        next = { ...next, inputs: connectorProxyInputs(node.inputs, before, task) } as GraphNode
+      } else if (type == 'http-request') {
         task = httpRequestTask(httpRequestConfigSchema.parse(config), String(update.name), before)
         next = { ...next, inputs: httpRequestInputs(node.inputs, before, task) } as GraphNode
       } else if (type == 'openapi') {
@@ -677,7 +688,7 @@ export async function compileAuthoring(base: RevisionContent, request: Authoring
       replace(ref, { ...node, config })
       return
     }
-    if (!Object.hasOwn(inputDefinitions(node), input)) {
+    if (!Object.hasOwn(inputDefinitions(node), input) && !(typeOf(node) === 'connector-proxy' && input === 'body')) {
       const type = typeOf(node)
       if (!['agent', 'code', 'llm', 'wait', 'approval'].includes(type))
         fail('input.not-found', `Unknown input ${input}.`, { node: ref, input, choices: Object.keys(inputDefinitions(node)) })
@@ -691,8 +702,8 @@ export async function compileAuthoring(base: RevisionContent, request: Authoring
         : value.kind == 'value' || value.kind == 'unset'
           ? value
           : { kind: 'sources', sources: (value.kind == 'sources' ? value.sources : [value]).map(source) }
-    const before = nodeInputMappings(nodeAt(content, ref))[input]
-    if (!dequal(before, mapping)) apply([{ kind: 'graph.node.input.set', nodeId: ref, handle: input, before, ...(mapping == null ? {} : { value: mapping }) }])
+    const changes = setInputMappings(content, ref, { [input]: mapping }) ?? []
+    if (changes.length > 0) apply(changes)
   }
   for (const edit of parsed.edits) {
     try {
@@ -777,6 +788,9 @@ export async function compileAuthoring(base: RevisionContent, request: Authoring
             case 'connector':
               changes = createManagedTask(identity, await connectorTask(config, name))
               break
+            case 'connector-proxy':
+              changes = createManagedTask(identity, connectorProxyTask(connectorProxyConfigSchema.parse(config), name))
+              break
             case 'skip-duplicates':
               changes = createManagedTask(identity, skipDuplicatesTask(skipDuplicatesConfigSchema.parse(config), name))
               break
@@ -803,7 +817,7 @@ export async function compileAuthoring(base: RevisionContent, request: Authoring
               break
             case 'poll':
             case 'integration': {
-              const definition = host.trigger(String(config.key))
+              const definition = await host.trigger(String(config.key))
               if (definition.type != edit.type) fail('trigger.type-mismatch', 'Trigger key has a different type.')
               changes = createProviderTrigger(nodeId, definition, { name, config: {} })
               break

package/src/control/common/authoringExamples.ts

@@ -1,5 +1,6 @@
 import type { DraftOperation } from './draftOperations.ts'
 
+import { connectorProxyConfigSchema, connectorProxyTask } from '../../connector/common/proxy.ts'
 import {
   createApproval,
   createBuiltinTrigger,
@@ -27,6 +28,8 @@ const descriptions = {
   'skip-duplicates':
     'Skip items already recorded by successful Runs. Configure identity fields; an empty list uses each string or numeric item. History is private to the node and only commits after Run success.',
   'http-request': 'A single HTTP request. Bind url and request inputs; outputs are body, statusCode and headers.',
+  'connector-proxy':
+    'A Provider API request through Connector Proxy. Select a Provider and account, then bind endpoint. Outputs preserve body, statusCode, headers and bodyEncoding.',
   'openapi': 'A fixed JSON API operation. Replace the example document and URL before running.',
   'connector':
     'A Connector Task and its node. Replace ACTION_ID, CONNECTION_ID and port definitions using connector_get / connector show. Set connectionId to an empty string to defer account configuration; execution will require an account.',
@@ -72,6 +75,12 @@ export function authoringExample(name: string): { version: 1; operations: readon
         { kind: 'graph.node.input.set', nodeId: 'http', handle: 'url', value: { kind: 'value', value: 'https://example.com' } },
       ]
       break
+    case 'connector-proxy':
+      operations = [
+        ...createManagedTask({ nodeId: 'request' }, connectorProxyTask(connectorProxyConfigSchema.parse({ providerId: 'github', connectionId: '' }))),
+        { kind: 'graph.node.input.set', nodeId: 'request', handle: 'endpoint', value: { kind: 'value', value: '/user' } },
+      ]
+      break
     case 'openapi': {
       const document = {
         openapi: '3.1.0',

package/src/control/common/authoringSchema.ts

@@ -1,6 +1,7 @@
 import type { JsonValue } from '../../types/index.ts'
 
 import { z } from 'zod'
+import { connectorProxyConfigSchema } from '../../connector/common/proxy.ts'
 import {
   agentToolFields,
   connectorAgentToolSchema,
@@ -31,6 +32,7 @@ export const authoringTypes = [
   'integration',
   'code',
   'connector',
+  'connector-proxy',
   'agent',
   'llm',
   'decision',
@@ -118,6 +120,7 @@ export const authoringConfigurations = {
   'integration': z.strictObject({ key: id, connectionId: id.optional() }),
   'code': z.strictObject({ inputs: inputFields, outputs: outputFields, capabilities: authoringCapabilities.optional() }),
   'connector': definitions.connector.omit({ outputMode: true }).strict(),
+  'connector-proxy': connectorProxyConfigSchema,
   'openapi': authoringOpenApiSchema,
   'http-request': httpRequestConfigSchema,
   'skip-duplicates': skipDuplicatesConfigSchema,
@@ -286,7 +289,8 @@ export function authoringSchema(kind?: AuthoringType) {
       }
     : {
         type: kind,
-        onError: kind == 'skip-duplicates' || retryNodeTypes.some((nodeType) => nodeType == kind) ? { enum: ['stop', 'error'] } : false,
+        onError:
+          kind == 'skip-duplicates' || kind == 'connector-proxy' || retryNodeTypes.some((nodeType) => nodeType == kind) ? { enum: ['stop', 'error'] } : false,
         retry: retryNodeTypes.some((nodeType) => nodeType == kind) ? z.toJSONSchema(retryConfigurationSchema) : false,
         inputSources: ['poll', 'integration'].includes(kind)
           ? ['value', 'unset', 'default']
@@ -311,17 +315,21 @@ export function authoringSchema(kind?: AuthoringType) {
                         ? 'Configure model settings, message templates and history as defaults. Input bindings with the same names override these defaults; named business inputs can be bound directly. Template strings interpolate {{name}}.'
                         : kind == 'skip-duplicates'
                           ? 'Bind an items array. Configure fields as dot-separated identity paths; an empty list uses each scalar item. Outputs are items and duplicates. History belongs to this node and commits only when the Run completes successfully. Fields accept strings or finite numbers; missing or complex values reject the batch.'
-                          : kind == 'http-request'
-                            ? 'Configure method, query/headers modes and names, bodyFormat, authentication, responseFormat and statusPolicy. Bind url, query.<name>/header.<name> or whole query/headers objects, body and auth.token (Basic: auth.username/auth.password). Credentials accept variables or upstream outputs only. Outputs: body, statusCode, headers. Authentication is replaced as a complete choice.'
-                            : kind == 'openapi'
-                              ? 'Select an operation; the tool resolves its ports and authentication. Read authenticationChoices from node details. authentication is replaced as a complete choice. Bind advertised credentials through inputs.'
-                              : kind == 'workflow'
-                                ? 'Select another workflow with config.flowId. A workflow cannot call itself, including in a disconnected node. Owned unpublished or unavailable targets may be saved as incomplete drafts. Use node.refresh to load the current published interface.'
-                                : kind == 'agent'
-                                  ? 'Tools accept Connector Actions or {kind: "workflow", flowId, name, description, approval, inputs}. Workflow parameter sources use model, input or value. The platform derives the interface. Refresh a workflow tool with node.refresh and tool: its name.'
-                                  : kind == 'code'
-                                    ? codeGuidance
-                                    : 'Supply business configuration and input data. Fixed definitions are assembled by the tool. Existing constraints and defaults are preserved on partial updates.',
+                          : kind == 'connector-proxy'
+                            ? 'Call a Provider API using its Connector account. Configure providerId, connectionId, method and query/headers modes and names. Bind endpoint, query.<name>/header.<name> or complete query/headers objects, and optional body. Setting or binding body automatically selects JSON; clearing it omits the body. Explicit null is a JSON body. Outputs: body, statusCode, headers, bodyEncoding. Proxy permissions are independent of Action permissions. Upstream HTTP errors remain response data when Connector returns a successful proxy result. Unsupported Providers fail at execution. Use connectionId: "" to defer account configuration. Retries are not supported.'
+                            : kind == 'http-request'
+                              ? 'Configure method, query/headers modes and names, bodyFormat, authentication, responseFormat and statusPolicy. Bind url, query.<name>/header.<name> or whole query/headers objects, body and auth.token (Basic: auth.username/auth.password). Credentials accept variables or upstream outputs only. Outputs: body, statusCode, headers. Authentication is replaced as a complete choice.'
+                              : kind == 'openapi'
+                                ? 'Select an operation; the tool resolves its ports and authentication. Read authenticationChoices from node details. authentication is replaced as a complete choice. Bind advertised credentials through inputs.'
+                                : kind == 'workflow'
+                                  ? 'Select another workflow with config.flowId. A workflow cannot call itself, including in a disconnected node. Owned unpublished or unavailable targets may be saved as incomplete drafts. Use node.refresh to load the current published interface.'
+                                  : kind == 'connector'
+                                    ? 'Select an Action and account. The platform derives ports from its schema. Open or dynamic response objects expose the complete response as one output; closed objects expose named fields. Read the created node for output names. Bind the whole response for dynamic fields; declared direct properties also support output field selection. Local edits preserve saved ports and response mapping.'
+                                    : kind == 'agent'
+                                      ? 'Tools accept Connector Actions or {kind: "workflow", flowId, name, description, approval, inputs}. Workflow parameter sources use model, input or value. The platform derives the interface. Refresh a workflow tool with node.refresh and tool: its name.'
+                                      : kind == 'code'
+                                        ? codeGuidance
+                                        : 'Supply business configuration and input data. Fixed definitions are assembled by the tool. Existing constraints and defaults are preserved on partial updates.',
         example: {
           op: 'node.add',
           as: 'step',
@@ -333,6 +341,7 @@ export function authoringSchema(kind?: AuthoringType) {
               'outputs': { config: { outputDefs: {} } },
               'workflow': { config: { flowId: '<Flow ID>' } },
               'connector': { config: { action: '<Action ID>', connectionId: '<Connection ID>' } },
+              'connector-proxy': { config: { providerId: 'github', connectionId: '' }, inputs: { endpoint: { kind: 'value', value: '/user' } } },
               'poll': { config: { key: '<Trigger key>', schedule: [{ type: 'every', unit: 'minute', value: 5 }] } },
               'integration': { config: { key: '<Trigger key>' } },
               'skip-duplicates': { config: { fields: ['id'] }, inputs: { items: { kind: 'value', value: [{ id: 'a' }, { id: 'b' }] } } },

package/src/control/common/catalogCache.ts

@@ -0,0 +1,145 @@
+import type { JsonValue } from '../../flow/common/change.ts'
+
+import { jsonValue } from './decoding.ts'
+import { ApiError } from './errors.ts'
+
+/** Storage is host-owned. Keys and records are opaque to the delegate. */
+export interface ControlCacheDelegate {
+  get(key: string): Promise<unknown>
+  set(key: string, value: JsonValue): Promise<void>
+  delete(key: string): Promise<void>
+}
+
+export interface ControlCacheRead {
+  readonly path: string
+  readonly source: 'cache' | 'network' | 'revalidated'
+  readonly body: JsonValue
+  readonly etag: string | null
+  readonly validatedAt: number
+  readonly stale: boolean
+}
+
+export interface ControlCacheOptions {
+  /** Non-secret identity of the deployment and effective caller/resource scope. */
+  readonly scope: string
+  readonly delegate: ControlCacheDelegate
+  readonly mode?: 'default' | 'refresh' | 'offline'
+  readonly maxAgeMs?: number
+  readonly onRead?: (read: ControlCacheRead) => void
+}
+
+interface CachedResponse {
+  readonly version: 1
+  readonly body: JsonValue
+  readonly etag: string | null
+  readonly validatedAt: number
+}
+
+interface CatalogQuery<Value> {
+  readonly path: string
+  readonly decode: (value: unknown) => Value
+}
+
+type CatalogLoad = (
+  etag: string | null,
+) => Promise<{ readonly modified: true; readonly data: JsonValue; readonly etag: string | null } | { readonly modified: false; readonly etag: string | null }>
+
+function cachedResponse(value: unknown): CachedResponse | undefined {
+  if (value == null || typeof value != 'object' || Array.isArray(value)) return
+  const entry = value as Record<string, unknown>
+  if (
+    entry.version !== 1 ||
+    !Object.hasOwn(entry, 'body') ||
+    !(entry.etag === null || typeof entry.etag == 'string') ||
+    typeof entry.validatedAt != 'number' ||
+    !Number.isFinite(entry.validatedAt) ||
+    entry.validatedAt < 0
+  )
+    return
+  return { version: 1, body: jsonValue(entry.body), etag: entry.etag, validatedAt: entry.validatedAt }
+}
+
+/** Cancellation belongs to each waiter, not the shared metadata request. */
+function wait<Value>(promise: Promise<Value>, signal?: AbortSignal): Promise<Value> {
+  if (signal == null) return promise
+  if (signal.aborted) {
+    void promise.catch(() => {})
+    return Promise.reject(signal.reason)
+  }
+  return new Promise((resolve, reject) => {
+    const abort = () => reject(signal.reason)
+    signal.addEventListener('abort', abort, { once: true })
+    promise.then(resolve, reject).finally(() => signal.removeEventListener('abort', abort))
+  })
+}
+
+/** Complete Flow API responses, never a merged store of catalog entities. */
+export class ControlCatalogCache {
+  readonly #pending = new Map<string, { readonly fresh: boolean; readonly promise: Promise<ControlCacheRead> }>()
+  private readonly options: ControlCacheOptions
+
+  constructor(options: ControlCacheOptions) {
+    this.options = options
+    if (!options.scope.trim()) throw new TypeError('Control cache scope must be nonempty.')
+    if (options.maxAgeMs != null && (!Number.isFinite(options.maxAgeMs) || options.maxAgeMs < 0))
+      throw new TypeError('Control cache maxAgeMs must be finite and nonnegative.')
+  }
+
+  async read<Value>(query: CatalogQuery<Value>, load: CatalogLoad, maxAgeMs: number, signal?: AbortSignal, fresh = false) {
+    signal?.throwIfAborted()
+    const key = JSON.stringify(['open-flow:catalog', 1, this.options.scope, query.path])
+    const result = await wait(this.#request(key, query, load, this.options.maxAgeMs ?? maxAgeMs, fresh || this.options.mode == 'refresh'), signal)
+    const data = query.decode(structuredClone(result.body))
+    try {
+      this.options.onRead?.({ ...result, body: structuredClone(result.body) })
+    } catch {}
+    return { data, etag: result.etag }
+  }
+
+  #request<Value>(key: string, query: CatalogQuery<Value>, load: CatalogLoad, maxAgeMs: number, fresh: boolean): Promise<ControlCacheRead> {
+    const previous = this.#pending.get(key)
+    if (previous != null) {
+      if (!fresh || previous.fresh) return previous.promise
+      // An explicit refresh must validate after a preceding ordinary lookup.
+      return previous.promise.catch(() => undefined).then(() => this.#request(key, query, load, maxAgeMs, true))
+    }
+    const promise = this.#load(key, query, load, maxAgeMs, fresh).finally(() => {
+      if (this.#pending.get(key)?.promise === promise) this.#pending.delete(key)
+    })
+    this.#pending.set(key, { fresh, promise })
+    return promise
+  }
+
+  async #load<Value>(key: string, query: CatalogQuery<Value>, load: CatalogLoad, maxAgeMs: number, fresh: boolean): Promise<ControlCacheRead> {
+    let cached: CachedResponse | undefined
+    try {
+      const stored = await this.options.delegate.get(key)
+      cached = cachedResponse(stored)
+      if (cached != null) query.decode(structuredClone(cached.body))
+      if (stored !== undefined && cached == null) await this.options.delegate.delete(key)
+    } catch {
+      cached = undefined
+      try {
+        await this.options.delegate.delete(key)
+      } catch {}
+    }
+    const now = Date.now()
+    const stale = cached == null || cached.validatedAt > now || now - cached.validatedAt >= maxAgeMs
+    if (cached != null && (this.options.mode == 'offline' || (!fresh && !stale))) return { ...cached, path: query.path, source: 'cache', stale }
+    if (this.options.mode == 'offline') throw new ApiError(503, 'catalog.cache-miss', `No compatible cached response for ${query.path}.`)
+
+    const result = await load(cached?.etag ?? null)
+    if (!result.modified && cached == null) throw new ApiError(502, 'response.invalid', 'A catalog returned 304 without a cached response.')
+    const entry: CachedResponse = {
+      version: 1,
+      body: result.modified ? result.data : cached!.body,
+      etag: result.etag ?? (result.modified ? null : cached!.etag),
+      validatedAt: Date.now(),
+    }
+    query.decode(structuredClone(entry.body))
+    try {
+      await this.options.delegate.set(key, structuredClone({ ...entry }))
+    } catch {}
+    return { ...entry, path: query.path, source: result.modified ? 'network' : 'revalidated', stale: false }
+  }
+}

package/src/control/common/conformance.ts

@@ -31,6 +31,10 @@ function equal(actual: unknown, expected: unknown, message: string): void {
   if (!dequal(actual, expected)) fail(`${message}: expected ${JSON.stringify(expected)}, received ${JSON.stringify(actual)}.`)
 }
 
+function oneOf(actual: unknown, expected: readonly unknown[], message: string): void {
+  if (!expected.some((value) => dequal(actual, value))) fail(`${message}: expected one of ${JSON.stringify(expected)}, received ${JSON.stringify(actual)}.`)
+}
+
 function record(value: unknown, message: string): RecordValue {
   if (value == null || typeof value != 'object' || Array.isArray(value)) fail(`${message}: expected an object.`)
   return value as RecordValue
@@ -940,9 +944,11 @@ export const controlApiConformanceCases: readonly ControlApiConformanceCase[] =
         }
         return current
       }
+      // Deployments may keep an idle Wait session in memory or freeze it immediately.
+      const pausedStatuses = ['running', 'waiting']
       const hasWait = (value: RecordValue) => list(value.waits, 'Waits').length > 0
       let detail = await awaitRun(run, hasWait, 'Wait Run to pause')
-      equal(detail.status, 'running', 'Wait Run status')
+      oneOf(detail.status, pausedStatuses, 'Wait Run status')
       const waiting = record(list(detail.waits, 'Waits')[0], 'Active Wait')
       equal(waiting.actions, ['approve', 'reject'], 'Wait actions')
       equal(waiting.nodeId, 'approval', 'Wait node')
@@ -972,7 +978,7 @@ export const controlApiConformanceCases: readonly ControlApiConformanceCase[] =
       const approved = await json(await resolveWait('approve'), 200, 'Approve Wait')
       equal(approved.action, 'approve', 'Approved action')
       equal(approved.resolutionAccepted, true, 'Approved resolution')
-      equal(approved.status, 'running', 'Resolved Run status')
+      oneOf(approved.status, ['running', 'queued'], 'Resolved Run status')
       requiredString(approved.resolvedAt, 'Wait resolution time')
       const rejected = await json(await resolveWait('reject'), 200, 'Reject resolved Wait')
       equal(rejected.action, 'approve', 'Winning action')
@@ -995,7 +1001,7 @@ export const controlApiConformanceCases: readonly ControlApiConformanceCase[] =
       const canceled = await create('wait-run-cancel', 'Create cancelable Wait Run')
       const canceledRunId = requiredString(canceled.runId, 'Cancelable Wait Run id')
       const canceledDetail = await awaitRun(canceled, hasWait, 'Wait cancelable Run to pause')
-      equal(canceledDetail.status, 'running', 'Cancelable Wait status')
+      oneOf(canceledDetail.status, pausedStatuses, 'Cancelable Wait status')
       equal(
         (
           await json(

package/src/control/common/connectorQueries.ts

@@ -1,6 +1,6 @@
-import type { ConnectorAction, ConnectorConnection, ConnectorProvider } from './api.ts'
+import type { ConnectorAction, ConnectorActionMetadata, ConnectorConnection, ConnectorProvider } from './api.ts'
 
-import { connection, connectorAction, connectorProvider } from './connectorDecoders.ts'
+import { connection, connectorAction, connectorActionMetadata, connectorProvider } from './connectorDecoders.ts'
 import { requiredFields, invalidResponse, record, string } from './decoding.ts'
 
 export interface RequestQuery<Value> {
@@ -36,6 +36,21 @@ export function connectorActionQuery(actionId: string, flowId?: string, locale?:
   }
 }
 
+export function connectorActionMetadataQuery(actionId: string, flowId?: string, locale?: string): RequestQuery<ConnectorActionMetadata> {
+  const parameters = new URLSearchParams({ ...(flowId == null ? {} : { flowId }), ...(locale == null ? {} : { locale }) }).toString()
+  return {
+    path: `/v1/connector/action-metadata/${encodeURIComponent(actionId)}${parameters ? `?${parameters}` : ''}`,
+    decode: (value) => {
+      const source = record(value)
+      requiredFields(source, ['action', 'version'])
+      if (source.version != 1) return invalidResponse()
+      const action = connectorActionMetadata(source.action)
+      if (action.actionId != actionId) return invalidResponse('action.actionId: does not match the requested Action.')
+      return action
+    },
+  }
+}
+
 export function allConnectorConnectionsQuery(flowId?: string): RequestQuery<readonly ConnectorConnection[]> {
   return {
     path: `/v1/connector/connections${scope(flowId)}`,

package/src/control/common/requests.ts

@@ -2,6 +2,7 @@ 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'
+export { createWorkflowAuthoring, type WorkflowAuthoringOptions } from './workflowAuthoring.ts'
 import type { JsonValue } from '../../flow/common/change.ts'
 import type { DraftOperation } from './draftOperations.ts'