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

package/src/control/common/authoringOpenApi.ts

@@ -0,0 +1,129 @@
+import type { JsonValue, ManagedTaskDefinition } from '../../flow/common/change.ts'
+import type { OpenApiAuth, OpenApiExecutor } from '../../openapi/common/openapi.ts'
+
+import { dequal } from 'dequal/lite'
+import { z } from 'zod'
+import { httpUrl, openApiTask, securityOptions, selectOperation, serverAddress, servers, snapshot } from '../../openapi/common/openapi.ts'
+
+const authenticationSchema = z.union([
+  z.strictObject({
+    schemes: z.array(z.string().min(1)).describe('One complete security alternative advertised by this operation; [] selects no authentication.'),
+  }),
+  z.strictObject({ type: z.enum(['bearer', 'basic']) }),
+  z.strictObject({ type: z.literal('apiKey'), name: z.string().min(1), in: z.enum(['header', 'query']) }),
+])
+
+export const authoringOpenApiSchema = z.strictObject({
+  sourceUrl: z.string().min(1),
+  path: z.string().min(1),
+  method: z.string().min(1),
+  serverUrl: z.string().optional(),
+  authentication: authenticationSchema.optional().describe('Omit to use the operation default. Bind credentials through the advertised node inputs.'),
+})
+
+export type AuthoringOpenApiConfig = z.infer<typeof authoringOpenApiSchema>
+
+export function openApiAuthenticationChoices(config: OpenApiExecutor) {
+  try {
+    return securityOptions(config.document, config.path, config.method).map(({ label, auth, error }) =>
+      Object.assign({ label }, auth == null ? { error } : { authentication: { schemes: auth.map((item) => item.id) } }),
+    )
+  } catch (error) {
+    // Reading an incomplete saved draft must not require a valid operation snapshot.
+    return [{ label: 'Saved operation', error: (error as Error).message }]
+  }
+}
+
+function authenticationView(config: OpenApiExecutor): NonNullable<AuthoringOpenApiConfig['authentication']> {
+  const schemes = config.auth.map((item) => item.id)
+  const declared = openApiAuthenticationChoices(config).some((option) => 'authentication' in option && dequal(option.authentication?.schemes, schemes))
+  if (!declared && config.auth.length == 1) {
+    const { id: _id, ...manual } = config.auth[0]!
+    return manual as NonNullable<AuthoringOpenApiConfig['authentication']>
+  }
+  return { schemes }
+}
+
+export function openApiConfigView(config: OpenApiExecutor): AuthoringOpenApiConfig {
+  return {
+    sourceUrl: config.sourceUrl,
+    path: config.path,
+    method: config.method,
+    serverUrl: config.serverUrl,
+    authentication: authenticationView(config),
+  }
+}
+
+export class AuthoringOpenApiAuthenticationError extends Error {
+  readonly code = 'openapi.authentication-invalid'
+  readonly details: { field: string; choices: ReturnType<typeof openApiAuthenticationChoices> }
+  constructor(config: OpenApiExecutor) {
+    super('Choose one complete authentication alternative advertised by this operation, or configure manual authentication.')
+    this.name = 'AuthoringOpenApiAuthenticationError'
+    this.details = { field: 'config.authentication', choices: openApiAuthenticationChoices(config) }
+  }
+}
+
+function prepareAuthentication(config: OpenApiExecutor, choice: NonNullable<AuthoringOpenApiConfig['authentication']>): readonly OpenApiAuth[] {
+  if (!('schemes' in choice)) return [{ id: 'manual', ...choice }]
+  const names = new Set(choice.schemes)
+  const matched = securityOptions(config.document, config.path, config.method).find(
+    (option) =>
+      option.auth != null && names.size == choice.schemes.length && option.auth.length == names.size && option.auth.every((auth) => names.has(auth.id)),
+  )
+  if (matched?.auth == null) throw new AuthoringOpenApiAuthenticationError(config)
+  return matched.auth
+}
+
+/** Operation snapshots and credential handles remain stable until their business selection changes. */
+export async function prepareOpenApiTask(
+  config: AuthoringOpenApiConfig,
+  previous: ManagedTaskDefinition | undefined,
+  fetch: (url: string) => Promise<JsonValue>,
+  name: string,
+  explicit: { authentication?: boolean; serverUrl?: boolean } = {},
+): Promise<ManagedTaskDefinition> {
+  const current = previous?.executor.kind == 'openapi' ? previous.executor : undefined
+  const changed = current == null || config.sourceUrl != current.sourceUrl || config.path != current.path || config.method != current.method
+  const authentication = changed && current != null && !explicit.authentication ? undefined : config.authentication
+  let selected: OpenApiExecutor
+  if (!changed) selected = current
+  else {
+    const document = await fetch(config.sourceUrl)
+    if (authentication != null && !('schemes' in authentication)) {
+      // Manual access tokens also support operations whose declared OAuth scheme is unsupported.
+      const saved = snapshot(document, config.path, config.method)
+      selected = {
+        kind: 'openapi',
+        sourceUrl: httpUrl(config.sourceUrl),
+        path: config.path,
+        method: config.method,
+        serverUrl: serverAddress(servers(saved, config.path, config.method)[0]!, config.sourceUrl),
+        document: saved,
+        auth: [],
+      }
+    } else selected = selectOperation(document, config.sourceUrl, config.path, config.method)
+  }
+  const defaultAuth = () => {
+    const defaultSelection = securityOptions(current!.document, current!.path, current!.method).find((option) => option.auth != null)?.auth
+    if (defaultSelection == null) throw new AuthoringOpenApiAuthenticationError(current!)
+    return defaultSelection
+  }
+  const auth =
+    authentication == null
+      ? !changed && explicit.authentication
+        ? defaultAuth()
+        : selected.auth
+      : !changed && dequal(authentication, authenticationView(current))
+        ? current.auth
+        : prepareAuthentication(selected, authentication)
+  const serverUrl =
+    !changed && explicit.serverUrl && config.serverUrl == null
+      ? serverAddress(servers(current.document, current.path, current.method)[0]!, current.sourceUrl)
+      : changed && current != null && !explicit.serverUrl
+        ? selected.serverUrl
+        : (config.serverUrl ?? selected.serverUrl)
+  const executor = { ...selected, auth, serverUrl }
+  if (previous != null && !changed && dequal(auth, current.auth)) return { ...previous, name, executor }
+  return openApiTask(executor, name)
+}

package/src/control/common/authoringSchema.ts

@@ -0,0 +1,404 @@
+import type { JsonValue } from '../../types/index.ts'
+
+import { z } from 'zod'
+import {
+  agentToolFields,
+  connectorAgentToolSchema,
+  workflowAgentToolSchema,
+  connectorCapabilitySchema,
+  authoringDefinitionSchemas as definitions,
+} from '../../flow/common/changeSchema.ts'
+import { retryConfigurationSchema, retryNodeTypes } from '../../flow/common/retry.ts'
+import { authoringLlmConfiguration } from './authoringLlm.ts'
+import { authoringOpenApiSchema } from './authoringOpenApi.ts'
+
+const id = z.string().min(1)
+const json = z.json()
+const patch = z.record(id, json)
+export const authoringTypes = [
+  'start',
+  'outputs',
+  'webhook-response',
+  'workflow',
+  'webhook',
+  'cron',
+  'error',
+  'poll',
+  'integration',
+  'code',
+  'connector',
+  'agent',
+  'llm',
+  'decision',
+  'openapi',
+  'condition',
+  'value',
+  'wait',
+  'approval',
+] as const
+const type = z.enum(authoringTypes)
+export type AuthoringType = z.infer<typeof type>
+const referenceSchema = id.describe(
+  'An existing node reference returned by read/search, or $alias for a preceding node.add in this edit batch. For node.add.as "step", reference "$step", never bare "step". Aliases are local to one batch.',
+)
+const output = z.strictObject({
+  kind: z.literal('output'),
+  node: referenceSchema,
+  port: id.optional().describe('Omit for a node with one output. For multiple outputs, choose a name from node details.'),
+  field: z.string().optional(),
+})
+const system = z.strictObject({ kind: z.literal('system'), node: referenceSchema, port: z.literal('error'), field: z.string().optional() })
+const variable = z.strictObject({ kind: z.literal('variable'), name: id })
+export const authoringSourceSchema = z.union([
+  output,
+  system,
+  variable,
+  z.strictObject({ kind: z.literal('value'), value: json }),
+  z.strictObject({ kind: z.literal('unset') }),
+  z.strictObject({ kind: z.literal('default') }),
+  z.strictObject({ kind: z.literal('sources'), sources: z.array(z.union([output, system, variable])).min(1) }),
+])
+const operand = z.union([z.strictObject({ kind: z.literal('value'), value: json.optional(), schema: json.optional() }), output, system, variable])
+const toolSources = z
+  .record(id, agentToolFields.inputs.element.shape.source)
+  .optional()
+  .describe(
+    'Tool input sources by name. The platform resolves types from the selected Action or workflow. New inputs default to model-provided; omitted existing sources are preserved.',
+  )
+const agentTool = z.union([
+  workflowAgentToolSchema.omit({ id: true, inputs: true, outputs: true, revisionId: true }).extend({ inputs: toolSources }).strict(),
+  connectorAgentToolSchema.omit({ id: true, inputs: true }).extend({ inputs: toolSources }).strict(),
+])
+const authoringCapabilities = z.array(z.union([connectorCapabilitySchema, z.strictObject({ kind: z.literal('workflow'), name: id, flowId: id })]))
+const notification = z.strictObject({
+  ...definitions.connector.shape,
+  messageHandle: id,
+  inputs: z.record(id, z.union([z.strictObject({ kind: z.literal('value'), value: json }), z.strictObject({ kind: z.literal('input'), input: id })])),
+})
+const field = z.strictObject({ schema: json.optional(), nullable: z.boolean().optional(), description: z.string().optional() })
+const inputFields = z
+  .record(id, field.extend({ default: json.optional() }))
+  .describe(
+    'Optional business input constraints by name. A binding to a new Code, Agent, LLM, Wait or Approval input automatically declares an input accepting any JSON. Existing constraints are preserved. Omitted schema accepts any JSON; omitted nullable is true. Use default for inherited values; input.set supplies data.',
+  )
+export const flowInputFields = z
+  .record(id, field)
+  .describe(
+    'Workflow input definitions by name. Omitted schema accepts any JSON; omitted nullable is true. No defaults. Supply call values as trigger.outputs.',
+  )
+export const flowOutputFields = flowInputFields.describe(
+  'Workflow output definitions by name. Omitted schema accepts any JSON; omitted nullable is true. No defaults. Set values on the Outputs node with input.set or node.add.inputs.',
+)
+export const flowInputFieldsView = z.record(id, field.extend({ schema: json as z.ZodType<JsonValue>, nullable: z.boolean() }))
+const outputFields = z.record(id, field).describe('Code return fields by name. Omitted schema accepts any JSON; omitted nullable is true.')
+const expression = z.strictObject({
+  left: operand,
+  operator: definitions.condition.shape.cases.element.shape.groups.element.shape.expressions.element.shape.operator,
+  right: operand.optional(),
+})
+const all = z.strictObject({ all: z.array(expression) })
+const when = z.union([expression, all, z.strictObject({ any: z.array(z.union([expression, all])) })])
+export const authoringConfigurations = {
+  'webhook-response': z.strictObject({}),
+  'workflow': z.strictObject({ flowId: id }),
+  'start': z.strictObject({ inputDefs: flowInputFields.default({}) }),
+  'outputs': z.strictObject({ outputDefs: flowOutputFields.default({}) }),
+  'error': z.strictObject({ sourceFlowIds: z.array(id).optional() }),
+  'webhook': definitions.webhook.omit({ bodyFields: true }).extend({ body: inputFields }).strict(),
+  'cron': z.strictObject({ schedule: definitions.schedule }),
+  'poll': z.strictObject({ key: id, connectionId: id.optional(), schedule: definitions.schedule }),
+  '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(),
+  'openapi': authoringOpenApiSchema,
+  'agent': definitions.agent
+    .omit({ prompt: true, tools: true })
+    .extend({
+      inputs: inputFields,
+      resultSchema: json.describe('JSON schema of the final result. Defaults to text. The tool manages the output definition; references can omit port.'),
+      tools: z.array(agentTool),
+      notification: notification.optional(),
+    })
+    .strict(),
+  'llm': authoringLlmConfiguration.extend({ inputs: inputFields }),
+  'decision': definitions.decision,
+  'condition': z.strictObject({ match: z.enum(['first', 'all']), branches: z.array(z.strictObject({ name: id, description: z.string().optional(), when })) }),
+  'value': z.strictObject({ values: patch, outputs: outputFields }),
+  'wait': z.strictObject({
+    inputs: inputFields,
+    autoContinue: definitions.waitAutoContinue
+      .optional()
+      .describe(
+        'Wait only. Omit to disable; clear config.autoContinue to remove. after counts from each wait registration; at requires an explicit offset and continues immediately if already past. Optional timezone preserves the editor zone; at remains the absolute instant. Server requires the deadline to precede the 7-day expiry.',
+      ),
+  }),
+  'approval': z.strictObject({ inputs: inputFields }),
+}
+const metadata = {
+  onError: z.enum(['stop', 'error']).optional(),
+  name: id.optional(),
+  description: z.string().optional(),
+  icon: z.string().optional(),
+  maxExecutions: z.int().positive().optional(),
+  timeoutMs: z.number().nonnegative().optional(),
+  retry: retryConfigurationSchema
+    .partial()
+    .optional()
+    .describe(
+      'Node retry policy for Code, Connector, OpenAPI, LLM and AI Decision. Omitted update fields preserve the policy; use clear: [["retry"]] to disable it. maxRetries counts additional attempts; intervalMs is 1000–60000 in whole seconds.',
+    ),
+}
+const updates = z.strictObject({
+  ...metadata,
+  config: patch
+    .optional()
+    .describe(
+      'Recursively merge configuration; omitted fields remain unchanged and arrays replace as a whole. This includes schema objects: {} does not clear an existing schema. Use clear paths to remove fields, e.g. ["config","inputs","amount","schema","type"].',
+    ),
+})
+export const authoringEditSchema = z.discriminatedUnion('op', [
+  z.strictObject({
+    op: z.literal('node.add'),
+    as: id
+      .regex(/^[A-Za-z][\w-]*$/)
+      .describe('Unique batch-local alias without the $ prefix. Later edits must reference this new node as $alias; the bare alias is not its node ID.'),
+    type,
+    name: id,
+    onError: z.enum(['stop', 'error']).optional(),
+    retry: retryConfigurationSchema.optional(),
+    config: patch.optional(),
+    inputs: z
+      .record(id, authoringSourceSchema)
+      .optional()
+      .describe('Input data sources, applied after creation, as input.set operations. Execution edges are separate.'),
+    code: z.string().optional(),
+    prompt: z.string().optional(),
+  }),
+  z.strictObject({ op: z.literal('node.update'), node: referenceSchema, set: updates.optional(), clear: z.array(z.array(id).min(1)).optional() }),
+  z.strictObject({
+    op: z.literal('node.refresh'),
+    node: referenceSchema,
+    tool: id.optional().describe('Name of a workflow tool on an Agent or Code node. Omit for a Call Workflow node.'),
+  }),
+  z.strictObject({ op: z.literal('node.remove'), node: referenceSchema }),
+  z.strictObject({ op: z.literal('input.set'), node: referenceSchema, input: id, source: authoringSourceSchema }),
+  z.strictObject({ op: z.enum(['edge.connect', 'edge.disconnect']), source: referenceSchema, target: referenceSchema, branch: id.optional() }),
+  z.strictObject({ op: z.literal('text.edit'), node: referenceSchema, field: z.enum(['code', 'prompt']), oldText: id, newText: z.string() }),
+  z.strictObject({ op: z.literal('text.set'), node: referenceSchema, field: z.enum(['code', 'prompt']), text: z.string() }),
+])
+export const authoringRequestSchema = z.strictObject({ baseRevision: id, requestId: id.max(256), edits: z.array(authoringEditSchema).min(1).max(1000) })
+export const authoringReadSchema = z
+  .strictObject({
+    revision: id.optional().describe('Fixed revision from a previous read; omit to read the current draft.'),
+    nodes: z.array(id).min(1).max(100).optional().describe('Node references to read in one batch. Mutually exclusive with text. Long texts return metadata.'),
+    text: z
+      .strictObject({ node: id, field: z.enum(['code', 'prompt']), start: z.int().positive().default(1), lines: z.int().min(1).max(200).default(80) })
+      .optional()
+      .describe('Read code or prompt by line (1-based). Mutually exclusive with nodes. Follow nextStart at the same revision until truncated is false.'),
+  })
+  .refine((v) => v.nodes == null || v.text == null, 'Choose nodes or text.')
+  .meta({ not: { required: ['nodes', 'text'] }, description: 'Omit nodes and text for an outline; provide nodes for details, or text for an excerpt.' })
+export const authoringCheckSchema = z.strictObject({ revisionId: id })
+export const authoringSearchSchema = z.strictObject({
+  revision: id.optional(),
+  query: id.max(1000),
+  type: type.optional(),
+  offset: z.int().nonnegative().default(0),
+  limit: z.int().min(1).max(100).default(20),
+})
+export type AuthoringRequest = z.infer<typeof authoringRequestSchema>
+export type AuthoringEdit = z.infer<typeof authoringEditSchema>
+export type AuthoringRead = z.input<typeof authoringReadSchema>
+export type AuthoringSearch = z.input<typeof authoringSearchSchema>
+export type AuthoringSource = z.infer<typeof authoringSourceSchema>
+export const authoringSchemaQuery = z
+  .strictObject({ type: type.optional(), action: id.optional() })
+  .refine((v) => v.type == null || v.action == null, 'Choose type or action.')
+
+const requestContracts = {
+  read: {
+    schema: authoringReadSchema,
+    guidance:
+      'Read Start and Outputs node details for their interface definitions and data sources. Choose one mode: outline (omit nodes and text), node details (nodes), or text excerpt (text). nodes and text are mutually exclusive. Text defaults to 80 lines, at most 200 lines and 24000 characters. For the complete text, repeat at nextStart with the same revision until truncated is false.',
+    examples: [{}, { revision: 'REVISION', nodes: ['NODE'] }, { revision: 'REVISION', text: { node: 'NODE', field: 'prompt', start: 1, lines: 80 } }],
+  },
+  search: {
+    schema: authoringSearchSchema,
+    guidance: 'Search names, configurations and text. Keep the returned revision when following nextOffset or reading a match.',
+    examples: [{ query: 'Customer summary', type: 'agent' }],
+  },
+  edit: {
+    schema: authoringRequestSchema,
+    guidance:
+      'Edit Start config.inputDefs and Outputs config.outputDefs through node.add or node.update; clear paths are relative to the node, e.g. ["config","inputDefs","amount"]. Set Outputs values with input.set. Use the observed revision as baseRevision and a stable requestId. Edits are ordered and atomic. node.add.as declares a batch-local alias without $. Every later reference to that new node must use $alias, including node, edge source/target and output source node fields; a bare alias is not the node ID. Use returned node references in later batches. Updates recursively merge objects (including schemas); {} preserves existing fields. Arrays replace as a whole. Remove fields with clear paths. Text replacement requires exactly one match. Read the target text first. A saved draft can have validation diagnostics.',
+    examples: [
+      {
+        baseRevision: 'REVISION',
+        requestId: 'CREATE_REQUEST',
+        edits: [
+          { op: 'node.add', as: 'start', type: 'start', name: 'Start' },
+          { op: 'node.add', as: 'step', type: 'code', name: 'Process', code: 'export default ({value}) => ({result:value})' },
+          { op: 'edge.connect', source: '$start', target: '$step' },
+          { op: 'node.update', node: '$step', set: { description: 'Created and connected in one atomic edit.' } },
+        ],
+      },
+      {
+        baseRevision: 'REVISION',
+        requestId: 'REQUEST',
+        edits: [{ op: 'text.edit', node: 'NODE', field: 'prompt', oldText: 'Original rule.', newText: 'Updated rule.' }],
+      },
+    ],
+  },
+  check: {
+    schema: authoringCheckSchema,
+    guidance: 'Check a fixed revision. In the CLI, pass this identity with --revision REVISION.',
+    examples: [{ revisionId: 'REVISION' }],
+  },
+}
+
+/** Transport-independent discovery of the same requests the service validates. */
+export function authoringRequestContract(name: string) {
+  if (!Object.hasOwn(requestContracts, name)) return undefined
+  const contract = requestContracts[name as keyof typeof requestContracts]
+  return { request: z.toJSONSchema(contract.schema, { io: 'input' }), guidance: contract.guidance, examples: contract.examples }
+}
+
+export function authoringSchema(kind?: AuthoringType) {
+  return kind == null
+    ? {
+        types: authoringTypes,
+        request: z.toJSONSchema(authoringRequestSchema),
+        guidance:
+          'Read a node type schema before creating or configuring it. Use $alias to reference a preceding node.add in the same batch. Read returns stable node references. Long code and prompt fields use text reads and edits. Changes use the observed baseRevision and a stable requestId.',
+      }
+    : {
+        type: kind,
+        onError: 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']
+          : ['start', 'outputs', 'error', 'cron', 'webhook', 'value', 'condition'].includes(kind)
+            ? []
+            : ['value', 'unset', 'default', 'output', 'system', 'variable', 'sources'],
+        extensibleInputs: ['code', 'agent', 'llm', 'wait', 'approval'].includes(kind),
+        guidance:
+          kind == 'webhook-response'
+            ? 'Prepare an HTTP response using fixed inputs body (any JSON, default empty text), statusCode (number, default 200) and headers (scalar-valued object, default {}). Select this node in Webhook options.responseBody as {kind: "webhook-response", nodeId: "node reference", timeoutMs: 30000}. Its first completion responds immediately while the Run continues. It has no business outputs. Multiple response nodes are allowed; each Webhook selects one reachable node.'
+            : kind == 'outputs'
+              ? 'Declare output fields through config.outputDefs. Set their values through node.add.inputs or input.set. Outputs is a singleton execution sink; it waits for its predecessors and produces workflow business outputs independently of node logs. No downstream edges or data references to Outputs are allowed.'
+              : kind == 'webhook'
+                ? 'Use options.responseBody: {kind: "webhook-response", nodeId: "node ID or $alias", timeoutMs: 30000} to respond on the selected node’s first completion while the Run continues. Body, statusCode and headers come exclusively from that node; clear workflow-output-only status/header references when switching. Alternatively configure options.responseBody as {kind: "workflow-outputs", output?: "top-level output name", timeoutMs?: 30000} to respond after the Run succeeds. Omit output for the complete object. Connect Webhook to Outputs. Timeout is 1000–60000 ms; HTTP timeout does not cancel the Run. Strings return text; other values return JSON. Only in this mode, options.responseStatusCodeOutput can select a numeric top-level workflow output as the HTTP status, overriding the preserved fixed responseStatusCode (default 200). Its runtime value must be an integer from 200 to 599, excluding 204, 205, 304; missing or invalid values return 500. Use responseHeaders for fixed text headers. In workflow-output mode, responseHeaderOutputs maps header names to top-level output names; values can be string, number or boolean and are converted to text. Alternatively responseHeadersSource: {kind: "workflow-outputs", output?: "object field"} replaces the entire header object (omit output for all outputs), preserving but ignoring per-header settings. Missing, null, complex or invalid header values return 500 without fallback. Header restrictions and Content-Type policy still apply. Omit responseBody for immediate responseData. Clear options.responseBody, options.responseStatusCodeOutput, options.responseHeadersSource and options.responseHeaderOutputs explicitly to switch back.'
+                : kind == 'start'
+                  ? 'Declare workflow inputs through config.inputDefs; read them in Start node details. REST calls and manual runs supply them as trigger.outputs. Downstream nodes bind these parameters as Start outputs. Start has no input sources or defaults; non-nullable parameters are required, and omitted nullable parameters become null.'
+                  : kind == 'condition'
+                    ? 'Edit branch operands through config.branches. A branch can test one expression, all expressions, or any alternatives. Unmatched execution uses branch otherwise.'
+                    : ['poll', 'integration'].includes(kind)
+                      ? 'Configure static parameters with node.add.inputs or input.set. Definitions come from the selected Trigger key; execution output and variable sources are unavailable.'
+                      : kind == 'llm'
+                        ? '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 == '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'
+                                ? 'Select workflows through config.capabilities: [{kind: "workflow", flowId, name}]. Call context.workflows.call(name, input) and await its business output. The platform derives input/output types. Refresh a selected workflow tool with node.refresh and tool: its name. Calls obey node and Run time limits.'
+                                : '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',
+          type: kind,
+          name: 'Step',
+          ...((
+            {
+              start: { config: { inputDefs: {} } },
+              outputs: { config: { outputDefs: {} } },
+              workflow: { config: { flowId: '<Flow ID>' } },
+              connector: { config: { action: '<Action ID>', connectionId: '<Connection ID>' } },
+              poll: { config: { key: '<Trigger key>', schedule: [{ type: 'every', unit: 'minute', value: 5 }] } },
+              integration: { config: { key: '<Trigger key>' } },
+              openapi: { config: { sourceUrl: 'https://example.com/openapi.json', path: '/items', method: 'get' } },
+              code: { code: 'export default ({value}) => ({result:value})', inputs: { value: { kind: 'value', value: 'Hello' } } },
+              condition: {
+                config: {
+                  match: 'first',
+                  branches: [
+                    {
+                      name: 'yes',
+                      when: {
+                        left: { kind: 'value', value: 120 },
+                        operator: '>',
+                        right: { kind: 'value', value: 100 },
+                      },
+                    },
+                  ],
+                },
+              },
+              value: { config: { values: { threshold: 100, region: 'EU' } } },
+              webhook: { config: { method: 'POST', body: { orderId: { schema: { type: 'string' }, nullable: false } } } },
+              wait: { prompt: 'Continue processing this order?', inputs: { order: { kind: 'value', value: { orderId: 'A-1' } } } },
+              approval: { prompt: 'Approve this order?', inputs: { order: { kind: 'value', value: { orderId: 'A-1' } } } },
+              llm: {
+                config: { model: { model: 'deepseek-v4-flash' }, template: [{ role: 'user', content: 'Summarize {{order}}.' }] },
+                inputs: { order: { kind: 'value', value: { orderId: 'A-1', total: 42 } } },
+              },
+              agent: {
+                config: {
+                  model: 'deepseek-v4-flash',
+                },
+                inputs: { orders: { kind: 'value', value: [{ orderId: 'A-1', total: 42 }] } },
+                prompt: 'Summarize {{orders}}.',
+              },
+            } as Partial<Record<AuthoringType, unknown>>
+          )[kind] as object),
+        },
+        configuration: z.toJSONSchema(authoringConfigurations[kind].partial()),
+        texts: kind == 'code' ? ['code'] : ['agent', 'wait', 'approval'].includes(kind) ? ['prompt'] : [],
+      }
+}
+
+export const authoringDiagnosticSchema = z.object({
+  code: id,
+  message: z.string(),
+  nodes: z.array(id),
+  field: z.string().optional(),
+  line: z.number().optional(),
+  column: z.number().optional(),
+})
+export const authoringCheckResponse = z.object({
+  flowId: id,
+  revisionId: id,
+  valid: z.boolean(),
+  diagnostics: z.array(authoringDiagnosticSchema),
+  version: z.literal(1),
+})
+export const authoringEditResponse = z.object({
+  flowId: id,
+  saved: z.literal(true),
+  revision: id,
+  nodes: z.record(id, id),
+  changes: z.array(z.object({ index: z.int(), op: id, node: id.optional() })),
+  validation: z.object({ status: z.enum(['valid', 'invalid', 'unavailable']), diagnostics: z.array(authoringDiagnosticSchema).optional() }),
+  version: z.literal(1),
+})
+export const authoringReadResponse = z.object({
+  flowId: id,
+  revision: id,
+  data: z.object({
+    nodes: z.array(z.record(z.string(), json)).optional(),
+    edges: z.array(json).optional(),
+    text: z.record(z.string(), json).optional(),
+  }),
+  version: z.literal(1),
+})
+export const authoringSearchResponse = z.object({
+  flowId: id,
+  revision: id,
+  data: z.object({
+    matches: z.array(z.object({ node: id.optional(), field: id, line: z.int().optional(), excerpt: z.string() })),
+    total: z.int(),
+    nextOffset: z.int().optional(),
+  }),
+  version: z.literal(1),
+})

package/src/control/common/authoringTools.ts

@@ -0,0 +1,123 @@
+import type { AgentInput, AgentTool, TaskCapability, WorkflowCapability } from '../../flow/common/change.ts'
+import type { WorkflowContract, WorkflowCandidate } from '../../workflow/common/workflow.ts'
+import type { ConnectorAction } from './api.ts'
+
+import { workflowAgentTool, workflowCapability } from '../../workflow/common/workflow.ts'
+
+interface AuthoringAgentToolBase {
+  readonly name: string
+  readonly description: string
+  readonly approval: boolean
+  readonly inputs?: Readonly<Record<string, AgentInput>>
+}
+
+export type AuthoringAgentTool = AuthoringAgentToolBase &
+  ({ readonly kind?: 'connector'; readonly action: string; readonly connectionId?: string } | { readonly kind: 'workflow'; readonly flowId: string })
+export type AuthoringCapability = Exclude<TaskCapability, WorkflowCapability> | Pick<WorkflowCapability, 'kind' | 'name' | 'flowId'>
+export type WorkflowLookup = (flowId: string) => Promise<WorkflowContract | WorkflowCandidate>
+
+interface ToolIdentity {
+  readonly kind?: 'connector' | 'workflow'
+  readonly name?: string
+  readonly flowId?: string
+}
+
+/** A rename retains a snapshot only when one removed name matches one added name for the same target. */
+function previousWorkflowTool<T extends ToolIdentity>(
+  tool: Pick<WorkflowCapability, 'name' | 'flowId'>,
+  next: readonly ToolIdentity[],
+  previous: readonly T[],
+): T | undefined {
+  const named = previous.find((item) => item.name == tool.name)
+  if (named != null) return named
+  const added = next.filter((item) => item.kind == 'workflow' && item.flowId == tool.flowId && !previous.some((old) => old.name == item.name))
+  if (added.length != 1) return
+  const removed = previous.filter((item) => item.kind == 'workflow' && item.flowId == tool.flowId && !next.some((itemNext) => itemNext.name == item.name))
+  return removed.length == 1 ? removed[0] : undefined
+}
+
+export function outwardCapabilities(capabilities: readonly TaskCapability[]): readonly AuthoringCapability[] {
+  return capabilities.map((item) => (item.kind == 'workflow' ? { kind: item.kind, name: item.name, flowId: item.flowId } : item))
+}
+
+export async function prepareCapabilities(
+  capabilities: readonly AuthoringCapability[],
+  previous: readonly TaskCapability[],
+  workflow: WorkflowLookup,
+): Promise<readonly TaskCapability[]> {
+  return Promise.all(
+    capabilities.map(async (item) => {
+      if (item.kind != 'workflow') return item
+      const old = previousWorkflowTool(item, capabilities, previous)
+      return old?.kind == 'workflow' && old.flowId == item.flowId ? { ...old, name: item.name } : workflowCapability(item.name, await workflow(item.flowId))
+    }),
+  )
+}
+
+export class AuthoringToolInputError extends Error {
+  readonly code = 'tool.input-not-found'
+  readonly details: { tool: string; action: string; input: string; choices: readonly string[] }
+  constructor(details: AuthoringToolInputError['details']) {
+    super(`Unknown input ${JSON.stringify(details.input)} for tool ${JSON.stringify(details.tool)}. Choose from: ${details.choices.join(', ') || '(none)'}.`)
+    this.name = 'AuthoringToolInputError'
+    this.details = details
+  }
+}
+
+export function outwardAgentTools(tools: readonly AgentTool[]): readonly AuthoringAgentTool[] {
+  return tools.map((tool) => {
+    const { id: _id, inputs, ...settings } = tool
+    return {
+      ...(tool.kind == 'workflow'
+        ? { kind: tool.kind, name: tool.name, description: tool.description, approval: tool.approval, flowId: tool.flowId }
+        : settings),
+      inputs: Object.fromEntries(inputs.map((input) => [input.handle, input.source])),
+    } as AuthoringAgentTool
+  })
+}
+
+/** Keep persisted tool contracts until the caller selects a different target or explicitly refreshes. */
+export async function prepareAgentTools(
+  tools: readonly AuthoringAgentTool[],
+  previous: readonly AgentTool[],
+  action: (id: string) => Promise<ConnectorAction>,
+  id: () => string,
+  workflow?: WorkflowLookup,
+): Promise<readonly AgentTool[]> {
+  const prepared: AgentTool[] = []
+  for (const tool of tools) {
+    const old = tool.kind == 'workflow' ? previousWorkflowTool(tool, tools, previous) : previous.find((item) => item.name == tool.name)
+    if (tool.kind == 'workflow') {
+      if (workflow == null) throw new Error('Workflow tools are unavailable.')
+      const retained = old?.kind == 'workflow' && old.flowId == tool.flowId ? old : undefined
+      const preparedTool = retained ?? workflowAgentTool(old?.id ?? id(), tool.name, await workflow(tool.flowId))
+      const choices = preparedTool.inputs.map((port) => port.handle)
+      for (const input of Object.keys(tool.inputs ?? {}))
+        if (!choices.includes(input)) throw new AuthoringToolInputError({ tool: tool.name, action: tool.flowId, input, choices })
+      prepared.push({
+        ...preparedTool,
+        name: tool.name,
+        description: tool.description,
+        approval: tool.approval,
+        inputs: preparedTool.inputs.map((port) => Object.assign({}, port, { source: tool.inputs?.[port.handle] ?? port.source })),
+      })
+      continue
+    }
+    const retained = old?.kind != 'workflow' && old?.action == tool.action ? old : undefined
+    const definition = retained == null ? await action(tool.action) : undefined
+    const ports =
+      retained?.inputs ?? Object.entries(definition!.inputs).map(([handle, port]) => Object.assign({}, port, { handle, source: { kind: 'model' } as const }))
+    const choices = ports.map((port) => port.handle)
+    for (const input of Object.keys(tool.inputs ?? {})) {
+      if (!choices.includes(input)) throw new AuthoringToolInputError({ tool: tool.name, action: tool.action, input, choices })
+    }
+    const { inputs: sources, ...settings } = tool
+    prepared.push({
+      ...settings,
+      id: old?.id ?? id(),
+      action: definition?.actionId ?? tool.action,
+      inputs: ports.map((port) => (sources != null && Object.hasOwn(sources, port.handle) ? Object.assign({}, port, { source: sources[port.handle]! }) : port)),
+    })
+  }
+  return prepared
+}