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

package/src/control/common/mcp.ts

@@ -0,0 +1,241 @@
+import type { JsonValue } from '../../flow/common/change.ts'
+
+import { z } from 'zod'
+import { canvasCommandSchema } from '../../canvas/common/commands.ts'
+import { runStatuses } from '../../execution/common/runLifecycle.ts'
+import { waitCommentSchema } from '../../execution/common/wait.ts'
+import { resourceNameIssue } from '../../flow/common/change.ts'
+import { authoringReadSchema, authoringSearchSchema, authoringRequestSchema, authoringSchemaQuery } from './authoringSchema.ts'
+import { resultQuerySchema } from './resultQuery.ts'
+
+export const mcpProtocolVersion = '2026-07-28'
+const json: z.ZodType<JsonValue> = z.json()
+const id = z.string().min(1)
+const mutationKey = id.max(256).describe('Stable identity for this mutation. Retry with the same key and identical arguments, even after a lost response.')
+const pageLimit = z.int().min(1).max(100).default(50)
+const flow = id.describe('Exact Flow ID returned by flow_list or flow_create.')
+const run = id.describe('Exact Run ID returned by flow_run or run_list.')
+export const mcpInstructions =
+  'Keep generated Flow and node names short enough to scan on the canvas. Aim for 2–4 English words or 4–8 Chinese characters, using the user\'s language unless the workflow has an established naming language. Name a Flow by its main purpose and a node by its action and object, such as "AI Trend Digest", "Fetch trends", "Verify sources", or "发布文章". Keep only qualifiers needed to distinguish similar nodes. Put detailed behavior in descriptions; avoid sentences, repeated workflow context, and obscure abbreviations. Preserve names explicitly supplied by the user, and do not rename unrelated existing nodes. ' +
+  'Use flow_list, flow_read and flow_search to inspect root workflows. Read node type schemas with flow_schema. Use flow_edit with the observed baseRevision and a stable requestId. Node edits affect only the selected node. Text edits require exactly one match. Execution edges and input sources are independent. Legacy Subflow content is unsupported. Edits can save incomplete drafts; inspect returned diagnostics and use flow_check before running. ' +
+  'Use flow_check before flow_run. Select an explicit Trigger node ID and fixed revision or publication. A new Flow has no Trigger until you add one. ' +
+  'Before adding a shared-source Trigger (Feishu, Slack Bot, Intercom, Sentry, Zoom, Fireflies, or Jira), use event_source_list and compare its Connection IDs with connector_connections in the Flow scope. If no source is available, create and verify one in Workbench. ' +
+  'Use flow_publish to publish a fixed Revision, then poll flow_publish_status until succeeded or failed. Use flow_live to inspect current online entries after publication. Use flow_set_enabled to enable or disable the observed Live publication. ' +
+  'flow_run returns an accepted Run, not its final result. Find Runs with run_list, poll run_get and use run_result after terminal. Resolve a waiting Run only with an explicit run_resolve_wait action allowed by run_get. ' +
+  'Use run_results and run_result_read to inspect stored Agent tool results; these are separate from the terminal Run result. ' +
+  'Retry flow_edit with identical arguments and the same requestId. Retry flow_create, flow_import, flow_publish and flow_run only with identical arguments and the same idempotencyKey; a new key can execute the Flow again. Canvas commands are transient broadcasts without execution confirmation; never automatically retry flow_canvas because pan is relative. Other mutations use the same resource identity and arguments when retrying. Cancel a Run explicitly with run_cancel. ' +
+  'Use nextCursor and nextAfter to read subsequent pages. Connector-backed deployments may require a Team; inspect connector_teams before creating a Flow.'
+
+function tool<Args>(description: string, schema: z.ZodType<Args>, readOnly: boolean, idempotent = true) {
+  return {
+    description,
+    annotations: { readOnlyHint: readOnly, destructiveHint: !readOnly, idempotentHint: idempotent, openWorldHint: true },
+    inputSchema: {
+      '~standard': {
+        version: 1 as const,
+        vendor: 'open-flow',
+        jsonSchema: {
+          input: (): Record<string, unknown> => z.toJSONSchema(schema, { io: 'input' }),
+          output: (): Record<string, unknown> => z.toJSONSchema(schema),
+        },
+        validate(value: unknown): { value: Args } | { issues: { message: string; path: string[] }[] } {
+          const result = schema.safeParse(value)
+          return result.success
+            ? { value: result.data }
+            : { issues: result.error.issues.map((issue) => ({ message: issue.message, path: issue.path.map(String) })) }
+        },
+      },
+    },
+  }
+}
+
+export const mcpTools = {
+  flow_canvas: tool(
+    'Broadcast a transient canvas command to connected Workbenches viewing this Flow. Success only confirms Server broadcast, not delivery or execution. No replay, session selection or Presentation save. Pan uses screen pixels (positive right/down); zoom is an absolute ratio (0.1–3); fit includes all nodes. Repeating pan moves again.',
+    z.strictObject({ flowId: flow, command: canvasCommandSchema }),
+    false,
+    false,
+  ),
+  flow_live: tool(
+    'Read the current published Flow, enablement and online entries, including Webhook URLs and request fields. Draft changes do not affect this view. An unpublished Flow returns not-published with no entries.',
+    z.strictObject({ flowId: flow }),
+    true,
+  ),
+  flow_list: tool(
+    'List Flows in this deployment. Continue with nextCursor; cursors are compatible with the Control API.',
+    z.strictObject({ cursor: id.optional(), limit: pageLimit }),
+    true,
+  ),
+  flow_read: tool(
+    'Read an outline, selected node details, or a bounded code/prompt excerpt. Carry the returned revision into subsequent reads and edits.',
+    authoringReadSchema.safeExtend({ flowId: flow }).meta({ ...authoringReadSchema.meta() }),
+    true,
+  ),
+  flow_search: tool(
+    'Find nodes by name, configuration or source text in a fixed Revision. Follow nextOffset for more matches.',
+    authoringSearchSchema.extend({ flowId: flow }),
+    true,
+  ),
+  flow_schema: tool(
+    'Read node configuration schemas and the edit grammar, or an Action contract. Action lookup requires a flowId.',
+    authoringSchemaQuery.safeExtend({ flowId: flow.optional() }),
+    true,
+  ),
+  flow_export: tool(
+    'Export the current draft as a shareable workflow JSON file. Structured external references are cleared. Literal secrets in code, prompts or business JSON remain; review before sharing.',
+    z.strictObject({ flowId: flow }),
+    true,
+  ),
+  flow_import: tool(
+    'Import workflow JSON as a new unpublished draft. External references are cleared and must be configured again. Keep identical arguments and idempotencyKey when retrying.',
+    z.strictObject({ file: json, name: id.optional(), teamId: id.optional(), idempotencyKey: mutationKey }),
+    false,
+  ),
+  flow_create: tool(
+    'Create an empty Flow. If this deployment uses OOMOL Connector, choose a teamId from connector_teams. Keep the key and arguments stable when retrying.',
+    z.strictObject({
+      name: id.refine((name) => name == name.trim() && resourceNameIssue(name) == null, 'Flow name is invalid.'),
+      idempotencyKey: mutationKey,
+      teamId: id.optional(),
+    }),
+    false,
+  ),
+  flow_edit: tool(
+    'Atomically edit root nodes, input sources, execution edges and text. Use $alias for preceding creations. Preserve baseRevision and requestId when retrying. A saved draft may have validation diagnostics.',
+    authoringRequestSchema.extend({ flowId: flow }),
+    false,
+  ),
+  flow_check: tool(
+    'Validate a fixed Revision and return diagnostics. Use the revision returned by flow_read or flow_edit as revisionId.',
+    z.strictObject({ flowId: flow, revisionId: id }),
+    true,
+  ),
+  flow_publish: tool(
+    'Publish a fixed Revision. Supply the observed Live publication ID, or null for the first publication, and a stable idempotencyKey. Returns an operation; poll flow_publish_status for success or failure.',
+    z.strictObject({ flowId: flow, revisionId: id, expectedLivePublicationId: id.nullable(), idempotencyKey: mutationKey }),
+    false,
+  ),
+  flow_publish_status: tool(
+    'Read a publish operation. Only succeeded confirms publication; failed includes the failure details. Keep polling while pending.',
+    z.strictObject({ flowId: flow, operationId: id }),
+    true,
+  ),
+  flow_set_enabled: tool(
+    'Enable or disable a published Flow. Supply expectedPublicationId from flow_list; a changed Live publication is a conflict. This does not cancel accepted Runs; use run_cancel for those.',
+    z.strictObject({ flowId: flow, expectedPublicationId: id, enabled: z.boolean() }),
+    false,
+  ),
+  flow_run: tool(
+    'Start a Run and return its runId. For draft supply flowId and revisionId; for live supply publicationId and select a Start node. Only draft Runs may simulate other Triggers. Always fix the source, Trigger and idempotencyKey. Start parameters come from the Start node’s flow_read config.inputDefs and are supplied in trigger.outputs; required parameters must be present, omitted nullable parameters become null, and unknown parameters are rejected. Poll run_get for completion.',
+    z
+      .discriminatedUnion('source', [
+        z.strictObject({
+          source: z.literal('draft'),
+          flowId: flow,
+          revisionId: id,
+          trigger: z.strictObject({ nodeId: id, outputs: z.record(z.string(), json) }),
+          inputs: z.record(z.string(), z.record(z.string(), json)).default({}),
+          idempotencyKey: mutationKey,
+        }),
+        z.strictObject({
+          source: z.literal('live'),
+          publicationId: id,
+          trigger: z.strictObject({ nodeId: id, outputs: z.record(z.string(), json) }),
+          inputs: z.record(z.string(), z.record(z.string(), json)).default({}),
+          idempotencyKey: mutationKey,
+        }),
+      ])
+      .meta({ type: 'object' }),
+    false,
+  ),
+  run_list: tool(
+    'List Runs for a Flow, optionally filtered by status. Continue with nextCursor; cursors are compatible with the Control API.',
+    z.strictObject({ flowId: flow, pendingWait: z.boolean().optional(), status: z.enum(runStatuses).optional(), cursor: id.optional(), limit: pageLimit }),
+    true,
+  ),
+  run_get: tool(
+    'Read Run status, including waiting details and allowed actions. Completed, failed, canceled and indeterminate are terminal.',
+    z.strictObject({ runId: run }),
+    true,
+  ),
+  run_events: tool(
+    'Read one page of Run events. Continue with nextAfter. Events can expire independently of the terminal result.',
+    z.strictObject({ runId: run, after: z.int().min(0).default(0), limit: pageLimit }),
+    true,
+  ),
+  run_result: tool(
+    'Read the terminal result. A queued, running or waiting Run returns run.not-terminal; inspect run_get first.',
+    z.strictObject({ runId: run }),
+    true,
+  ),
+  run_results: tool(
+    'List stored Agent tool result metadata for a Run, including Connector and code results. Continue with nextAfter as after. Use run_result_read to inspect content.',
+    z.strictObject({ runId: run, after: id.optional() }),
+    true,
+  ),
+  run_result_read: tool(
+    'Read a bounded page of a stored Agent tool result. Select a JSON Pointer with pointer and continue with nextOffset as offset at the same pointer. A complete value contains all data at that pointer.',
+    resultQuerySchema.extend({ runId: run, resultId: id }),
+    true,
+  ),
+  run_resolve_wait: tool(
+    'Explicitly resolve the waitId observed in run_get with one of its allowed actions. Optional comment records the reason (up to 2,000 Unicode code points). The first decision and comment win; inspect resolutionAccepted and action. Resume the same Run and poll run_get; do not create a replacement Run.',
+    z.strictObject({ runId: run, waitId: id, action: z.enum(['approve', 'continue', 'reject']), comment: waitCommentSchema }),
+    false,
+  ),
+  run_cancel: tool(
+    'Explicitly cancel a Run. Inspect cancelAccepted and the authoritative status; completion can win the race.',
+    z.strictObject({ runId: run }),
+    false,
+  ),
+  flow_code_connections: tool(
+    'Read the connections shared by all Code nodes in this Flow. With publicationId, read the fixed published snapshot; it cannot be edited.',
+    z.strictObject({ flowId: flow, publicationId: id.optional() }),
+    true,
+  ),
+  flow_connection_candidates: tool(
+    'List connections and permissions available to select. Node selections do not add shared Code usage.',
+    z.strictObject({ flowId: flow, providerIds: z.array(id).min(1) }),
+    true,
+  ),
+  flow_code_connection_set: tool(
+    'Add or remove shared Code usage in the Draft only. Does not change node selections or published versions. Use the observed accessRevision.',
+    z.strictObject({ flowId: flow, providerId: id, accessBindingId: id, selected: z.boolean(), expectedAccessRevision: z.int().nonnegative() }),
+    false,
+  ),
+  flow_connection_usage_remove: tool(
+    'Remove a connection from all node selections and shared Code usage in this Draft atomically. Keeps the account, published versions and accepted Runs. Use the observed revisionId and accessRevision.',
+    z.strictObject({ flowId: flow, connectionId: id, expectedRevisionId: id, expectedAccessRevision: z.int().nonnegative(), idempotencyKey: mutationKey }),
+    false,
+  ),
+  connector_teams: tool('List OOMOL Teams available for Flow creation. An unconfigured or custom Connector may not provide Teams.', z.strictObject({}), true),
+  connector_providers: tool('List Connector providers available in the Flow scope.', z.strictObject({ flowId: flow.optional() }), true),
+  connector_search: tool(
+    'Search Connector action summaries in the Flow scope. Read complete schemas with connector_get after selecting an action.',
+    z.strictObject({ query: z.string().trim().min(1).max(256), flowId: flow.optional() }),
+    true,
+  ),
+  connector_get: tool(
+    'Read a Connector action, input/output definitions and connection requirements before authoring a node.',
+    z.strictObject({ actionId: id, flowId: flow.optional() }),
+    true,
+  ),
+  connector_connections: tool(
+    'List Connector connections in the Flow scope. Use active connection IDs in bindings.',
+    z.strictObject({ serviceId: id.max(256), flowId: flow.optional() }),
+    true,
+  ),
+  event_source_list: tool(
+    'List shared event sources for Feishu, Slack Bot, Intercom, Sentry, Zoom, Fireflies, and Jira, including Team, Connection, event types, enabled and verification status. Inspect consumers for Flows actually using each source.',
+    z.strictObject({}),
+    true,
+  ),
+  trigger_search: tool(
+    'Search provider Trigger summaries; omit query to list all. Flow trigger instances are in flow_read. Start, Webhook and Cron are built-in node kinds described by flow_schema.',
+    z.strictObject({ query: z.string().trim().min(1).max(256).optional() }),
+    true,
+  ),
+  trigger_get: tool('Read a provider Trigger definition before creating its node.', z.strictObject({ key: id }), true),
+}
+
+export { mcpConformanceCases } from './mcpConformance.ts'

package/src/control/common/mcpConformance.ts

@@ -0,0 +1,142 @@
+import type { ControlApiConformanceCase, ControlApiConformanceHarness } from './conformance.ts'
+
+import { dequal } from 'dequal/lite'
+import { ControlClient } from './api.ts'
+import { mcpProtocolVersion, mcpTools } from './mcp.ts'
+
+function assert(value: unknown, message: string): asserts value {
+  if (!value) throw new Error(message)
+}
+
+async function rpc(harness: ControlApiConformanceHarness, method: string, params?: Record<string, unknown>) {
+  const response = await harness.request(
+    new Request(new URL('/v1/mcp', harness.origin), {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        'accept': 'application/json, text/event-stream',
+        'mcp-protocol-version': mcpProtocolVersion,
+        'mcp-method': method,
+        ...(method == 'tools/call' ? { 'mcp-name': String(params?.name) } : {}),
+      },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        id: crypto.randomUUID(),
+        method,
+        params: { ...params, _meta: { 'io.modelcontextprotocol/protocolVersion': mcpProtocolVersion, 'io.modelcontextprotocol/clientCapabilities': {} } },
+      }),
+    }),
+  )
+  assert(response.ok, `MCP ${method} returned HTTP ${response.status}: ${response.ok ? '' : await response.text()}.`)
+  assert(response.headers.get('mcp-session-id') == null, 'MCP must not create a session.')
+  const source = await response.text()
+  const body = response.headers.get('content-type')?.includes('text/event-stream')
+    ? JSON.parse(
+        source
+          .split('\n')
+          .findLast((line) => line.startsWith('data:'))
+          ?.slice(5) ?? 'null',
+      )
+    : JSON.parse(source)
+  assert(body != null && body.error == null, `MCP ${method} failed: ${JSON.stringify(body)}.`)
+  return body.result as Record<string, unknown>
+}
+
+export const mcpConformanceCases: readonly ControlApiConformanceCase[] = [
+  {
+    name: 'shares workflow import and export with REST and preserves idempotency',
+    async verify(harness) {
+      const client = new ControlClient((url, init) => harness.request(new Request(new URL(url, harness.origin), init)))
+      const original = await client.createFlow('Template source')
+      const exported = await rpc(harness, 'tools/call', { name: 'flow_export', arguments: { flowId: original.flowId } })
+      assert(exported.isError != true, 'MCP export failed.')
+      assert(dequal(exported.structuredContent, await client.exportFlow(original.flowId)), 'MCP and REST exports differ.')
+      const args = { file: exported.structuredContent, name: 'Imported template', idempotencyKey: crypto.randomUUID() }
+      const imported = await rpc(harness, 'tools/call', { name: 'flow_import', arguments: args })
+      assert(imported.isError != true, 'MCP import failed.')
+      const flow = imported.structuredContent as { flowId: string; draftRevisionId: string }
+      assert(flow.flowId != original.flowId && flow.draftRevisionId != original.draftRevisionId, 'Import reused resource identities.')
+      assert((await client.getEditor(flow.flowId)).live.publication == null, 'Import published the Flow.')
+      const retry = await rpc(harness, 'tools/call', { name: 'flow_import', arguments: args })
+      assert(dequal(retry.structuredContent, imported.structuredContent), 'Import retry created another Flow.')
+      const conflict = await rpc(harness, 'tools/call', { name: 'flow_import', arguments: { ...args, name: 'Changed import' } })
+      assert(conflict.isError == true, 'Changed import must conflict.')
+    },
+  },
+  {
+    name: 'publishes the public MCP catalog, input schemas and annotations',
+    async verify(harness) {
+      const result = await rpc(harness, 'tools/list')
+      assert(Array.isArray(result.tools), 'MCP tools must be an array.')
+      assert(result.tools.length == Object.keys(mcpTools).length, 'MCP tool count differs from the public contract.')
+      for (const [name, definition] of Object.entries(mcpTools)) {
+        const actual = result.tools.find((candidate) => candidate.name == name)
+        assert(actual != null, `Missing MCP tool ${name}.`)
+        assert(actual.description == definition.description, `${name} description differs.`)
+        assert(dequal(actual.annotations, definition.annotations), `${name} annotations differ.`)
+        const expected = definition.inputSchema['~standard'].jsonSchema.input()
+        const { $schema: _, ...schema } = expected
+        const { $schema: __, ...received } = actual.inputSchema
+        assert(dequal(received, schema), `${name} input schema differs.`)
+      }
+    },
+  },
+  {
+    name: 'shares Run pagination, status filters and cancellation between MCP and REST',
+    async verify(harness) {
+      const client = new ControlClient((url, init) => harness.request(new Request(new URL(url, harness.origin), init)))
+      const flow = await client.createFlow('MCP Run listing')
+      const changed = await client.changeDraft(flow.flowId, flow.draftRevisionId, [
+        { kind: 'graph.node.create', nodeId: 'start', node: { inputDefs: [], kind: 'start', name: 'Start' } },
+      ])
+      const args = {
+        source: 'draft',
+        flowId: flow.flowId,
+        revisionId: changed.revision.revisionId,
+        trigger: { nodeId: 'start', outputs: {} },
+      }
+      const runs: string[] = []
+      for (let index = 0; index < 2; index++) {
+        const accepted = await rpc(harness, 'tools/call', { name: 'flow_run', arguments: { ...args, idempotencyKey: crypto.randomUUID() } })
+        const run = accepted.structuredContent as Record<string, unknown>
+        assert(typeof run.runId == 'string', 'MCP must return an accepted Run ID.')
+        runs.push(run.runId)
+      }
+      const first = await rpc(harness, 'tools/call', { name: 'run_list', arguments: { flowId: flow.flowId, limit: 1 } })
+      const page = first.structuredContent as { runs: { runId: string }[]; nextCursor: string }
+      assert(page.runs.length == 1 && typeof page.nextCursor == 'string', 'Run listing must paginate.')
+      const rest = await client.listRuns(flow.flowId, { cursor: page.nextCursor, limit: 1 })
+      assert(rest.runs.length == 1 && rest.runs[0]?.runId != page.runs[0]?.runId, 'REST must continue the MCP Run cursor without duplicates.')
+      const restFirst = await client.listRuns(flow.flowId, { limit: 1 })
+      const next = await rpc(harness, 'tools/call', { name: 'run_list', arguments: { flowId: flow.flowId, cursor: restFirst.nextCursor, limit: 1 } })
+      assert(dequal(next.structuredContent, rest), 'MCP must continue the REST Run cursor.')
+      await rpc(harness, 'tools/call', { name: 'run_cancel', arguments: { runId: runs[0] } })
+      const filtered = await rpc(harness, 'tools/call', { name: 'run_list', arguments: { flowId: flow.flowId, status: 'canceled' } })
+      assert(dequal(filtered.structuredContent, await client.listRuns(flow.flowId, { status: 'canceled' })), 'MCP and REST status filters differ.')
+      const other = await client.createFlow('Other Run scope')
+      const invalid = await rpc(harness, 'tools/call', { name: 'run_list', arguments: { flowId: other.flowId, cursor: page.nextCursor } })
+      assert(invalid.isError == true, 'Run cursors must reject a different Flow scope.')
+      assert((invalid.structuredContent as { error: { code: string } }).error.code == 'page.invalid-cursor', 'Run cursor error must match REST.')
+    },
+  },
+  {
+    name: 'shares mutation receipts and authoritative Drafts between MCP and REST',
+    async verify(harness) {
+      const args = { name: 'MCP conformance', idempotencyKey: crypto.randomUUID() }
+      const call = () => rpc(harness, 'tools/call', { name: 'flow_create', arguments: args })
+      const created = await call()
+      assert(created.isError != true, 'MCP Flow creation failed.')
+      const flow = created.structuredContent as Record<string, unknown>
+      assert(typeof flow.flowId == 'string', 'MCP did not return a Flow ID.')
+      const retry = await call()
+      assert(dequal(retry.structuredContent, flow), 'MCP mutation replay changed identity.')
+      const response = await harness.request(new Request(new URL(`/v1/flows/${encodeURIComponent(flow.flowId)}/draft`, harness.origin)))
+      assert(response.ok, 'REST cannot read the Flow created through MCP.')
+      const draft = (await response.json()) as Record<string, unknown>
+      assert(draft.revisionId == flow.draftRevisionId, 'MCP and REST disagree on the Draft head.')
+      const conflict = await rpc(harness, 'tools/call', { name: 'flow_create', arguments: { ...args, name: 'Changed retry' } })
+      assert(conflict.isError == true, 'MCP must reject a changed idempotent replay.')
+      assert((conflict.structuredContent as { error: { code: string } }).error.code == 'flow.conflict', 'MCP must preserve the Control error code.')
+    },
+  },
+]

package/src/control/common/providerAccess.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod'
+import { canonicalJsonBytes, digestBytes } from '../../flow/common/encoding.ts'
+
+const sourceSchema = z.discriminatedUnion('kind', [
+  z.strictObject({ kind: z.literal('admin-delegation') }),
+  z.strictObject({ kind: z.literal('policy'), ruleId: z.string().min(1).nullable() }),
+])
+
+export type ProviderAccessSource = { readonly kind: 'admin-delegation' } | { readonly kind: 'policy'; readonly ruleId: string | null }
+
+export interface ProviderAccessIdentity {
+  readonly accessBindingId: string
+  readonly connectionId: string
+  readonly providerId: string
+  readonly source: ProviderAccessSource
+}
+
+export type ProviderAccessReference =
+  | ProviderAccessIdentity
+  | { readonly accessBindingId: string; readonly providerId: string; readonly connectionId: null; readonly source: null }
+
+export function parseProviderAccessSource(value: unknown): ProviderAccessSource {
+  return sourceSchema.parse(value)
+}
+
+export async function providerAccessBindingId(teamId: string, identity: Omit<ProviderAccessIdentity, 'accessBindingId'>): Promise<string> {
+  return await digestBytes(canonicalJsonBytes(['provider-access', 2, teamId, identity.connectionId, identity.providerId, identity.source]))
+}

package/src/control/common/providerIconSprite.ts

@@ -0,0 +1,42 @@
+/** Coordinates and dimensions are physical pixels in the sprite image. */
+export interface ProviderIconSprite {
+  readonly version: string
+  readonly pixelRatio: number
+  readonly iconSize: number
+  readonly bleed: number
+  readonly width: number
+  readonly height: number
+  readonly lightUrl: string
+  readonly darkUrl: string
+}
+export interface ProviderIconAppearance {
+  readonly iconSprite?: ProviderIconSprite
+  readonly iconSpritePosition?: { readonly x: number; readonly y: number }
+}
+
+/** One sprite sheet serves all provider positions in a catalog response. */
+export interface ProviderIconSpriteCatalog {
+  readonly iconSprite: ProviderIconSprite
+  readonly positions: Readonly<Record<string, NonNullable<ProviderIconAppearance['iconSpritePosition']>>>
+}
+
+/** Optional artwork must never make an otherwise usable catalog unavailable. */
+export function providerIconAppearance(metadata: unknown, position: unknown): ProviderIconAppearance {
+  if (!metadata || typeof metadata != 'object' || !position || typeof position != 'object') return {}
+  const m = metadata as ProviderIconSprite
+  const p = position as { x: number; y: number }
+  if (
+    typeof m.version != 'string' ||
+    ![m.pixelRatio, m.iconSize, m.width, m.height].every((v) => Number.isInteger(v) && v > 0) ||
+    ![m.bleed, p.x, p.y].every((v) => Number.isInteger(v) && v >= 0) ||
+    p.x + m.iconSize > m.width ||
+    p.y + m.iconSize > m.height
+  )
+    return {}
+  try {
+    for (const url of [m.lightUrl, m.darkUrl]) if (typeof url != 'string' || !['https:', 'http:', 'data:'].includes(new URL(url).protocol)) return {}
+  } catch {
+    return {}
+  }
+  return { iconSprite: m, iconSpritePosition: { x: p.x, y: p.y } }
+}

package/src/control/common/publicationDecoders.ts

@@ -0,0 +1,98 @@
+import type { Live, Publication, PublicationPage, PublishOperation } from './api.ts'
+
+import { requiredFields, integer, invalidResponse, record, string } from './decoding.ts'
+
+export function publication(value: unknown): Publication {
+  const source = record(value)
+  const liveEnd = source.liveEnd == null ? undefined : record(source.liveEnd)
+  if (liveEnd != null && typeof liveEnd.enabled != 'boolean') return invalidResponse()
+  const operation = source.operation
+  const sourcePublicationId = source.sourcePublicationId
+  if (source.version != 1) return invalidResponse()
+  if (operation != 'publish' && operation != 'rollback') return invalidResponse()
+  if (sourcePublicationId != null && typeof sourcePublicationId != 'string') return invalidResponse()
+  return {
+    ...(liveEnd == null ? {} : { liveEnd: { enabled: liveEnd.enabled as boolean, endedAt: string(liveEnd.endedAt) } }),
+    actorId: string(source.actorId),
+    closureDigest: string(source.closureDigest),
+    createdAt: string(source.createdAt),
+    engineContract: string(source.engineContract),
+    flowId: string(source.flowId),
+    modelVersion: integer(source.modelVersion),
+    operation: operation as Publication['operation'],
+    publicationId: string(source.publicationId),
+    sharedAccessDigest: string(source.sharedAccessDigest),
+    revisionDigest: string(source.revisionDigest),
+    revisionId: string(source.revisionId),
+    ...(sourcePublicationId == null ? {} : { sourcePublicationId }),
+    version: 1,
+  }
+}
+
+export function publishOperation(value: unknown): PublishOperation {
+  const source = record(value)
+  const status = source.status
+  const common = {
+    createdAt: string(source.createdAt),
+    flowId: string(source.flowId),
+    operationId: string(source.operationId),
+    revisionId: string(source.revisionId),
+    updatedAt: string(source.updatedAt),
+    version: 1 as const,
+  }
+  if (source.version != 1) return invalidResponse()
+  switch (status) {
+    case 'pending':
+      requiredFields(source, ['createdAt', 'flowId', 'operationId', 'revisionId', 'status', 'updatedAt', 'version'])
+      return { ...common, status }
+    case 'succeeded':
+      requiredFields(source, ['createdAt', 'flowId', 'operationId', 'publicationId', 'revisionId', 'status', 'updatedAt', 'version'])
+      return { ...common, publicationId: string(source.publicationId), status }
+    case 'failed': {
+      requiredFields(source, ['createdAt', 'flowId', 'issue', 'operationId', 'revisionId', 'status', 'updatedAt', 'version'])
+      const issue = record(source.issue)
+      const nodeId = issue.nodeId
+      requiredFields(issue, ['code', 'message', ...(nodeId == null ? [] : ['nodeId'])])
+      return {
+        ...common,
+        issue: { code: string(issue.code), message: string(issue.message), ...(nodeId == null ? {} : { nodeId: string(nodeId) }) },
+        status,
+      }
+    }
+    default:
+      return invalidResponse()
+  }
+}
+
+export function live(value: unknown): Live {
+  const source = record(value)
+  const status = source.status
+  const candidate = source.publication
+  if (source.version != 1 || typeof source.hasUnpublishedChanges != 'boolean') return invalidResponse()
+  if (status != 'not-published' && status != 'runnable' && status != 'suspended') return invalidResponse()
+  if (status == 'not-published' && candidate !== null) return invalidResponse()
+  if (status != 'not-published' && candidate === null) return invalidResponse()
+  return {
+    flowId: string(source.flowId),
+    hasUnpublishedChanges: source.hasUnpublishedChanges,
+    publication: candidate === null ? null : publication(candidate),
+    revision: integer(source.revision),
+    status: status as Live['status'],
+    version: 1,
+  }
+}
+
+export function publicationPage(value: unknown): PublicationPage {
+  const source = record(value)
+  const nextCursor = source.nextCursor
+  const total = source.total
+  if (source.version != 1 || !Array.isArray(source.publications)) return invalidResponse()
+  if (nextCursor != null && typeof nextCursor != 'string') return invalidResponse()
+  if (total != null && !Number.isSafeInteger(total)) return invalidResponse()
+  return {
+    ...(nextCursor == null ? {} : { nextCursor }),
+    publications: source.publications.map(publication),
+    ...(total == null ? {} : { total: total as number }),
+    version: 1,
+  }
+}

package/src/control/common/random.ts

@@ -0,0 +1,16 @@
+export function randomId(): string {
+  const crypto = globalThis.crypto
+  if (crypto != null) {
+    try {
+      if (typeof crypto.randomUUID == 'function') return crypto.randomUUID()
+    } catch {}
+    if (typeof crypto.getRandomValues == 'function') {
+      const bytes = crypto.getRandomValues(new Uint8Array(16))
+      bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x40
+      bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80
+      const value = Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('')
+      return `${value.slice(0, 8)}-${value.slice(8, 12)}-${value.slice(12, 16)}-${value.slice(16, 20)}-${value.slice(20)}`
+    }
+  }
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`
+}