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

package/src/control/common/authoringCondition.ts

@@ -0,0 +1,110 @@
+import type { ConditionExpression, ConditionNode, ConditionOperand, ConditionOperator, JsonValue, Source } from '../../flow/common/change.ts'
+
+export type AuthoringConditionSource =
+  | { readonly kind: 'output'; readonly node: string; readonly port?: string; readonly field?: string }
+  | { readonly kind: 'variable'; readonly name: string }
+export type AuthoringConditionOperand = AuthoringConditionSource | { readonly kind: 'value'; readonly value?: JsonValue; readonly schema?: JsonValue }
+export interface AuthoringConditionExpression {
+  readonly left: AuthoringConditionOperand
+  readonly operator: ConditionOperator
+  readonly right?: AuthoringConditionOperand
+}
+type All = { readonly all: readonly AuthoringConditionExpression[] }
+export type AuthoringConditionWhen = AuthoringConditionExpression | All | { readonly any: readonly (AuthoringConditionExpression | All)[] }
+export interface AuthoringConditionConfiguration {
+  readonly match: ConditionNode['matchMode']
+  readonly branches: readonly { readonly name: string; readonly description?: string; readonly when: AuthoringConditionWhen }[]
+}
+
+/** Preserve empty groups in invalid drafts; do not turn them into unconditional branches. */
+export function conditionConfigurationView(
+  node: Pick<ConditionNode, 'cases' | 'matchMode'>,
+  source: (value: Source) => AuthoringConditionSource,
+): AuthoringConditionConfiguration {
+  const operand = (value: ConditionOperand): AuthoringConditionOperand =>
+    value.kind == 'source'
+      ? source(value.source)
+      : { kind: 'value', ...(value.value === undefined ? {} : { value: value.value }), ...(value.jsonSchema === undefined ? {} : { schema: value.jsonSchema }) }
+  const expression = (value: ConditionExpression): AuthoringConditionExpression => ({
+    left: operand(value.left),
+    operator: value.operator,
+    ...(value.right === undefined ? {} : { right: operand(value.right) }),
+  })
+  return {
+    match: node.matchMode,
+    branches: node.cases.map((branch) => {
+      const groups = branch.groups.map((group) =>
+        group.expressions.length == 1 ? expression(group.expressions[0]!) : { all: group.expressions.map(expression) },
+      )
+      return {
+        name: branch.output,
+        ...(branch.description === undefined ? {} : { description: branch.description }),
+        when: groups.length == 1 ? groups[0]! : { any: groups },
+      }
+    }),
+  }
+}
+
+export function prepareConditionConfiguration(
+  config: AuthoringConditionConfiguration,
+  source: (value: AuthoringConditionSource) => Source,
+): Pick<ConditionNode, 'cases' | 'matchMode'> {
+  const operand = (value: AuthoringConditionOperand): ConditionOperand =>
+    value.kind == 'value'
+      ? { kind: 'value', ...(value.value === undefined ? {} : { value: value.value }), ...(value.schema === undefined ? {} : { jsonSchema: value.schema }) }
+      : { kind: 'source', source: source(value) }
+  const expression = (value: AuthoringConditionExpression): ConditionExpression => ({
+    left: operand(value.left),
+    operator: value.operator,
+    ...(value.right === undefined ? {} : { right: operand(value.right) }),
+  })
+  return {
+    matchMode: config.match,
+    cases: config.branches.map((branch) => {
+      const groups = 'any' in branch.when ? branch.when.any : [branch.when]
+      return {
+        output: branch.name,
+        ...(branch.description === undefined ? {} : { description: branch.description }),
+        groups: groups.map((group) => ({ expressions: ('all' in group ? group.all : [group]).map(expression) })),
+      }
+    }),
+  }
+}
+
+/** Map a path relative to a persisted Condition configuration into its normalized public config. */
+export function conditionConfigurationFieldPath(node: Pick<ConditionNode, 'cases'>, path: readonly (string | number)[]): readonly (string | number)[] {
+  if (path[0] == 'matchMode') return ['match', ...path.slice(1)]
+  if (path[0] != 'cases') return path
+  if (path.length == 1) return ['branches']
+  const branchIndex = Number(path[1]),
+    branch = node.cases[branchIndex],
+    base: (string | number)[] = ['branches', path[1]!]
+  if (path[2] == 'output') return [...base, 'name', ...path.slice(3)]
+  if (path[2] != 'groups') return [...base, ...path.slice(2)]
+  base.push('when')
+  if (branch == null || path.length == 3) return base
+  const groupIndex = Number(path[3]),
+    group = branch.groups[groupIndex]
+  if (branch.groups.length != 1) base.push('any', path[3]!)
+  if (path[4] != 'expressions') return [...base, ...path.slice(4)]
+  if (group == null || path.length == 5) return group?.expressions.length == 1 ? base : [...base, 'all']
+  if (group.expressions.length != 1) base.push('all', path[5]!)
+  const remaining = path.slice(6).filter((part, index) => !(index == 1 && part == 'source'))
+  if (remaining[0] == 'left' || remaining[0] == 'right') {
+    switch (remaining[1]) {
+      case 'jsonSchema':
+        remaining[1] = 'schema'
+        break
+      case 'nodeId':
+        remaining[1] = 'node'
+        break
+      case 'output':
+        remaining[1] = 'port'
+        break
+      case 'bindingId':
+        remaining[1] = 'name'
+        break
+    }
+  }
+  return [...base, ...remaining]
+}

package/src/control/common/authoringDiagnosticFields.ts

@@ -0,0 +1,136 @@
+import type { GraphNode, Group, InputPort } from '../../flow/common/change.ts'
+
+import { conditionConfigurationFieldPath } from './authoringCondition.ts'
+
+type Ports = readonly (InputPort | Group)[]
+const metadata = new Set(['name', 'description', 'icon', 'timeoutMs', 'maxExecutions', 'retry', 'onError'])
+
+function portField(ports: Ports, path: readonly string[], parent: string): string {
+  const port = ports[Number(path[0])]
+  if (port == null || !('handle' in port)) return parent
+  const field = `${parent}.${port.handle}`
+  switch (path[1]) {
+    case 'jsonSchema':
+      return [field, 'schema', ...path.slice(2)].join('.')
+    case 'value':
+      return [field, 'default', ...path.slice(2)].join('.')
+    case 'nullable':
+    case 'description':
+      return [field, ...path.slice(1)].join('.')
+    default:
+      return field
+  }
+}
+
+/** Accept a decoded JSON Pointer, including or omitting its initial empty component. */
+export function authoringDiagnosticField(node: GraphNode | undefined, parts: readonly string[]): string {
+  const path = parts[0] == '' ? parts.slice(1) : parts
+  if (node == null) return 'config'
+  if (path[0] == 'modules') return 'code'
+  let location = path[0] == 'document' && path[1] == 'graph' && path[2] == 'nodes' ? path.slice(4) : path
+  const inlineDefinition = node.kind == 'task' && location[0] == 'task'
+  if (inlineDefinition) location = location.slice(1)
+  if (location.length == 0) return 'config'
+  const head = location[0]!
+  if (!inlineDefinition && metadata.has(head)) return location.join('.')
+  if (node.kind == 'start' && head == 'inputDefs') return portField(node.inputDefs, location.slice(1), 'config.inputDefs')
+  if (node.kind == 'outputs' && head == 'outputDefs') return portField(node.outputDefs, location.slice(1), 'config.outputDefs')
+  if (node.kind == 'outputs' && head == 'outputMappings') return ['inputs', ...location.slice(1)].join('.')
+  if (head == 'prompt') return 'prompt'
+  if (head == 'inputs' && !inlineDefinition) {
+    if (node.kind == 'condition' && location[1] != null) {
+      const [branch, group, expression, side] = location[1].split('/')
+      if (branch != null && group != null && expression != null && (side == 'left' || side == 'right'))
+        return ['config', ...conditionConfigurationFieldPath(node, ['cases', branch, 'groups', group, 'expressions', expression, side])].join('.')
+      return 'config.branches'
+    }
+    return location[1] == null ? 'inputs' : `inputs.${location[1]}`
+  }
+  if (node.kind == 'task') {
+    const task = node.task
+    if (task == null) return 'config'
+    const executor = 'executor' in task ? task.executor : undefined
+    if (head == 'additionalInputs') return portField(node.additionalInputs ?? [], location.slice(1), 'config.inputs')
+    if (head == 'inputs' || head == 'outputs') {
+      const ports = task[head]
+      const port = ports[Number(location[1])]
+      if (head == 'outputs' && (executor?.kind == 'agent' || executor?.kind == 'llm'))
+        return location[2] == 'jsonSchema' ? ['config', 'resultSchema', ...location.slice(3)].join('.') : 'config.resultSchema'
+      if (head == 'inputs' && executor?.kind == 'llm' && port != null && 'handle' in port && ['model', 'template', 'messages'].includes(port.handle))
+        return ['config', port.handle, ...(location[2] == 'value' ? location.slice(3) : [])].join('.')
+      const custom = executor == null || executor.kind == 'agent' || executor.kind == 'llm'
+      return portField(ports, location.slice(1), custom ? `config.${head}` : head == 'inputs' ? 'inputPorts' : 'outputPorts')
+    }
+    if (head == 'executor') {
+      const field = location[1]
+      if (field == null || field == 'kind') return 'config'
+      if (field == 'prompt') return 'prompt'
+      if (executor?.kind == 'workflow' && field == 'revisionId') return 'config.flowId'
+      if (executor?.kind == 'openapi') {
+        if (field == 'document') return 'config'
+        if (field == 'auth') return 'config.authentication'
+      }
+      if (executor?.kind == 'agent') {
+        if (field == 'tools') {
+          const tool = executor.tools[Number(location[2])]
+          if (tool == null) return 'config.tools'
+          const base = `config.tools.${location[2]}`
+          if (location[3] == 'id') return base
+          if (tool.kind == 'workflow' && (location[3] == 'revisionId' || location[3] == 'outputs')) return `${base}.flowId`
+          if (location[3] == 'inputs') {
+            const input = tool.inputs[Number(location[4])]
+            if (input == null) return `${base}.inputs`
+            return location[5] == 'source' ? [base, 'inputs', input.handle, ...location.slice(6)].join('.') : `${base}.inputs.${input.handle}`
+          }
+        }
+        if (field == 'notification' && location[2] == 'inputDefinitions') return 'config.notification.inputs'
+      }
+      return ['config', ...location.slice(1)].join('.')
+    }
+    if (
+      head == 'capabilities' &&
+      'moduleId' in task &&
+      task.capabilities?.[Number(location[1])]?.kind == 'workflow' &&
+      ['revisionId', 'inputs', 'outputs'].includes(location[2] ?? '')
+    )
+      return `config.capabilities.${location[1]}.flowId`
+    if (head == 'capabilities') return ['config', ...location].join('.')
+    if (head == 'name') return 'name'
+    return 'config'
+  }
+  switch (node.kind) {
+    case 'condition':
+      return head == 'cases' || head == 'matchMode' ? ['config', ...conditionConfigurationFieldPath(node, location)].join('.') : 'config'
+    case 'wait':
+    case 'approval':
+      return head == 'inputDefinitions'
+        ? portField(node.inputDefinitions, location.slice(1), 'config.inputs')
+        : head == 'autoContinue'
+          ? ['config', ...location].join('.')
+          : 'config'
+    case 'start':
+      return 'config'
+    case 'webhook':
+      if (head == 'bodyFields') return portField(node.bodyFields, location.slice(1), 'config.body')
+      return head == 'method' || head == 'options' ? ['config', ...location].join('.') : 'config'
+    case 'value': {
+      if (head != 'values') return 'config'
+      const port = node.values[Number(location[1])]
+      if (port == null) return 'config.values'
+      if (location[2] == 'value') return ['config', 'values', port.handle, ...location.slice(3)].join('.')
+      return portField(node.values, location.slice(1), 'config.outputs')
+    }
+    case 'cron':
+      return head == 'cronTimes' ? ['config', 'schedule', ...location.slice(1)].join('.') : 'config'
+    case 'poll':
+    case 'integration':
+      if (head == 'config') return location[1] == null ? 'inputs' : `inputs.${location[1]}`
+      if (head == 'definition') return location[1] == 'configInputs' ? portField(node.definition.configInputs, location.slice(2), 'inputPorts') : 'config.key'
+      if (head == 'pollTimes') return ['config', 'schedule', ...location.slice(1)].join('.')
+      return head == 'connectionId' ? 'config.connectionId' : 'config'
+    case 'error':
+      return head == 'sourceFlowIds' ? ['config', ...location].join('.') : 'config'
+    default:
+      return 'config'
+  }
+}

package/src/control/common/authoringExamples.ts

@@ -0,0 +1,192 @@
+import type { DraftOperation } from './draftOperations.ts'
+
+import {
+  createApproval,
+  createBuiltinTrigger,
+  createCodeTask,
+  createCondition,
+  createDecisionTask,
+  createLlmTask,
+  createManagedTask,
+  createValue,
+  createWait,
+} from '../../flow/common/nodeChanges.ts'
+import { openApiTask, selectOperation } from '../../openapi/common/openapi.ts'
+
+const descriptions = {
+  'start': 'A Start node with a required message parameter. Supply it through trigger.outputs.',
+  'error': 'A Flow Error node. Select upstream Flows, then publish and enable this Flow to listen for failures in their automatic runs.',
+  'webhook': 'A Webhook start node.',
+  'webhook-response': 'An HTTP response node with body, statusCode and headers inputs. Select it from a reachable Webhook.',
+  'cron': 'An hourly scheduled start node.',
+  'poll': 'Gmail polling by key; replace CONNECTION_ID with an active Gmail connection.',
+  'integration': 'Telegram webhook integration by key; replace CONNECTION_ID with an active Telegram connection.',
+  'decision': 'AI Decision evaluates named questions against target and returns a complete answer object per output. Configure target before running.',
+  '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.',
+  'code': 'A JavaScript module and its node. Use Code for custom computation; use Connector Tasks for existing actions.',
+  'condition': 'A condition with true and false execution branches.',
+  'value': 'A fixed value node.',
+  'approval': 'An Approval with approve and reject decision branches and a built-in notification output.',
+  'wait': 'A Wait with a continue action and a built-in notification output.',
+  'agent': 'An Agent with code computation enabled. Configure a model available in the deployment.',
+  'llm-chat': 'An LLM chat Task and its node; configure a model available in the deployment.',
+  'llm-json': 'An LLM JSON Task and its node; configure a model available in the deployment.',
+  'poll-notification':
+    'Gmail events → JavaScript text formatting → Connector notification. Replace connection/action IDs and match the notification input ports.',
+} as const
+
+export const authoringExampleNames = Object.keys(descriptions) as (keyof typeof descriptions)[]
+
+export const authoringExamples = authoringExampleNames.map((name) => ({ name, description: descriptions[name] }))
+
+export function authoringExample(name: string): { version: 1; operations: readonly DraftOperation[] } {
+  let operations: readonly DraftOperation[]
+  switch (name) {
+    case 'webhook-response':
+      operations = [{ kind: 'graph.node.create', nodeId: 'reply', node: { kind: 'webhook-response', name: 'Webhook Response', inputs: {} } }]
+      break
+    case 'error':
+      operations = createBuiltinTrigger('error', { kind: 'error', name: 'Flow Error' })
+      break
+    case 'decision':
+      operations = createDecisionTask({ nodeId: 'decision' }, 'AI Decision', [
+        { name: 'needs_support', type: 'noul', instructions: 'Does the customer need support?' },
+      ])
+      break
+    case 'openapi': {
+      const document = {
+        openapi: '3.1.0',
+        paths: { '/items': { get: { responses: { '200': { content: { 'application/json': { schema: { type: 'array', items: { type: 'string' } } } } } } } } },
+      }
+      operations = createManagedTask({ nodeId: 'api' }, openApiTask(selectOperation(document, 'https://api.example.com/openapi.json', '/items', 'get')))
+      break
+    }
+    case 'start':
+      operations = [
+        ...createBuiltinTrigger('start', { inputDefs: [{ handle: 'message', jsonSchema: { type: 'string' }, nullable: false }], kind: 'start', name: 'Start' }),
+      ]
+      break
+    case 'webhook':
+      operations = createBuiltinTrigger('start', { kind: 'webhook', method: 'POST', name: 'Webhook', bodyFields: [] })
+      break
+    case 'cron':
+      operations = createBuiltinTrigger('start', { kind: 'cron', name: 'Schedule', cronTimes: [{ type: 'every', unit: 'hour', value: 1 }] })
+      break
+    case 'poll':
+      operations = [
+        {
+          kind: 'graph.trigger.create',
+          nodeId: 'mail',
+
+          key: 'gmail.on_message_received',
+          connectionId: 'CONNECTION_ID',
+          config: {},
+          schedule: [{ type: 'every', unit: 'minute', value: 5 }],
+        },
+      ]
+      break
+    case 'integration':
+      operations = [
+        {
+          kind: 'graph.trigger.create',
+          nodeId: 'telegram',
+
+          key: 'telegram.on_update',
+          connectionId: 'CONNECTION_ID',
+          config: { updates: ['message'] },
+        },
+      ]
+      break
+    case 'agent':
+      operations = createManagedTask(
+        { nodeId: 'agent' },
+        {
+          name: 'Agent',
+          inputs: [{ handle: 'input', jsonSchema: { type: 'string' }, nullable: false, value: 'Summarize the current input.' }],
+          outputs: [{ handle: 'output', jsonSchema: { type: 'string' }, nullable: false }],
+          executor: { kind: 'agent', code: true, model: 'deepseek-v4-flash', prompt: '{{input}}', maxRounds: 10, tools: [] },
+        },
+      )
+      break
+    case 'connector':
+      operations = createManagedTask(
+        { nodeId: 'notify' },
+        {
+          name: 'Notify',
+          executor: { kind: 'connector', action: 'ACTION_ID', connectionId: 'CONNECTION_ID' },
+          inputs: [{ handle: 'text', jsonSchema: { type: 'string' }, nullable: false, value: 'Hello' }],
+          outputs: [],
+        },
+      )
+      break
+    case 'code':
+      operations = createCodeTask(
+        { nodeId: 'format', moduleId: 'format-module' },
+        'Format',
+        {
+          imports: [],
+          source: 'export default async function (inputs) { return { text: inputs.events.map(event => `${event.sender}: ${event.subject}`).join("\\n") } }',
+        },
+        {
+          inputs: [
+            {
+              handle: 'events',
+              jsonSchema: { type: 'array', items: { type: 'object' } },
+              nullable: false,
+              value: [],
+            },
+          ],
+          outputs: [{ handle: 'text', jsonSchema: { type: 'string' }, nullable: false }],
+        },
+      )
+      break
+    case 'condition':
+      operations = [
+        ...createCondition('condition', 'Condition'),
+        { kind: 'graph.node.input.set', nodeId: 'condition', handle: '0/0/0/left', value: { kind: 'value', value: 100 } },
+        { kind: 'graph.node.input.set', nodeId: 'condition', handle: '0/0/0/right', value: { kind: 'value', value: 100 } },
+      ]
+      break
+    case 'value':
+      operations = createValue('value', 'Value')
+      break
+    case 'approval':
+      operations = createApproval('approval', 'Approve?')
+      break
+    case 'wait':
+      operations = createWait('wait', 'Continue?')
+      break
+    case 'llm-chat':
+    case 'llm-json':
+      operations = createLlmTask({ nodeId: 'llm' }, 'LLM', name == 'llm-chat' ? 'chat' : 'json', 'Generated response.')
+      break
+    case 'poll-notification':
+      operations = [
+        ...authoringExample('poll').operations,
+        ...authoringExample('code').operations,
+        ...authoringExample('connector').operations,
+        { kind: 'graph.edge.connect', edge: { source: 'mail', target: 'format' } },
+        { kind: 'graph.edge.connect', edge: { source: 'format', target: 'notify' } },
+        {
+          kind: 'graph.node.input.set',
+          nodeId: 'format',
+          handle: 'events',
+          before: { kind: 'value', value: [] },
+          value: { kind: 'sources', sources: [{ kind: 'node', nodeId: 'mail', output: 'events' }] },
+        },
+        {
+          kind: 'graph.node.input.set',
+          nodeId: 'notify',
+          handle: 'text',
+          before: { kind: 'value', value: 'Hello' },
+          value: { kind: 'sources', sources: [{ kind: 'node', nodeId: 'format', output: 'text' }] },
+        },
+      ]
+      break
+    default:
+      throw new TypeError(`Unknown authoring example ${JSON.stringify(name)}.`)
+  }
+  return { version: 1 as const, operations }
+}

package/src/control/common/authoringFields.ts

@@ -0,0 +1,53 @@
+import type { InputPort, Group, JsonValue, RevisionContent } from '../../flow/common/change.ts'
+
+import { dequal } from 'dequal/lite'
+const record = (value: unknown): Record<string, unknown> =>
+  value != null && typeof value == 'object' && !Array.isArray(value) ? (value as Record<string, unknown>) : {}
+/** Business field contracts, independent of storage handles and presentation groups. */
+export function fieldsView(ports: readonly (InputPort | Group)[]) {
+  return Object.fromEntries(
+    ports.flatMap((port) =>
+      'handle' in port
+        ? [
+            [
+              port.handle,
+              {
+                schema: port.jsonSchema,
+                nullable: port.nullable,
+                ...(port.description == null ? {} : { description: port.description }),
+                ...(Object.hasOwn(port, 'value') ? { default: port.value } : {}),
+              },
+            ],
+          ]
+        : [],
+    ),
+  )
+}
+export function fieldsToPorts(fields: unknown, previous: readonly (InputPort | Group)[]): readonly (InputPort | Group)[] {
+  const remaining = new Map(Object.entries(record(fields)))
+  function port(handle: string, value: unknown): InputPort {
+    const field = record(value)
+    return {
+      handle,
+      jsonSchema: (Object.hasOwn(field, 'schema') ? field.schema : {}) as JsonValue,
+      nullable: (field.nullable ?? true) as boolean,
+      ...(field.description == null ? {} : { description: String(field.description) }),
+      ...(Object.hasOwn(field, 'default') ? { value: field.default as JsonValue } : {}),
+    }
+  }
+  return [
+    ...previous.flatMap<InputPort | Group>((old) => {
+      if (!('handle' in old)) return [old]
+      if (!remaining.has(old.handle)) return []
+      const value = remaining.get(old.handle)
+      remaining.delete(old.handle)
+      return [dequal(fieldsView([old])[old.handle], value) ? old : port(old.handle, value)]
+    }),
+    ...Array.from(remaining, ([handle, value]) => port(handle, value)),
+  ]
+}
+
+/** The workflow input contract shared by draft authoring and published views. */
+export function flowInputDefinitions(content: RevisionContent) {
+  return fieldsView(Object.values(content.document.graph.nodes).find((node) => node.kind == 'start')?.inputDefs ?? [])
+}

package/src/control/common/authoringLlm.ts

@@ -0,0 +1,70 @@
+import type { Group, InputPort, JsonValue, ManagedTaskDefinition } from '../../flow/common/change.ts'
+
+import { dequal } from 'dequal/lite'
+import { z } from 'zod'
+
+// Values remain JSON so an existing draft with invalid runtime values can still
+// be inspected and repaired without rewriting unrelated configuration.
+export const authoringLlmConfiguration = z.strictObject({
+  mode: z.enum(['chat', 'json']),
+  resultSchema: z.json(),
+  model: z.json().optional().describe('Default model settings: {model, temperature?, top_p?, max_tokens?}. A bound model input takes precedence.'),
+  template: z.json().optional().describe('Default message templates: [{role: "system" | "user" | "assistant", content: "Text with {{namedInput}}"}].'),
+  messages: z.json().optional().describe('Default conversation history, prepended without template interpolation; an array of {role, content} or null.'),
+})
+
+const defaults = { model: 'model', template: 'template', messages: 'messages' } as const
+type DefaultName = keyof typeof defaults
+
+/** Read defaults only. Node bindings remain independently visible and editable. */
+export function llmConfigurationView(task: ManagedTaskDefinition): Record<string, JsonValue> {
+  if (task.executor.kind != 'llm') throw new TypeError('Expected an LLM task.')
+  const config: Record<string, JsonValue> = {
+    mode: task.executor.mode,
+    resultSchema: task.outputs.find((port) => 'handle' in port)?.jsonSchema ?? {},
+  }
+  for (const [name, handle] of Object.entries(defaults)) {
+    const port = task.inputs.find((candidate): candidate is InputPort => 'handle' in candidate && candidate.handle == handle)
+    if (port != null && Object.hasOwn(port, 'value')) config[name] = port.value!
+  }
+  return config
+}
+
+/** Update default values without altering port contracts, groups, or node bindings. */
+export function prepareLlmConfiguration(config: Record<string, unknown>, previous: ManagedTaskDefinition, name: string): ManagedTaskDefinition {
+  if (previous.executor.kind != 'llm') throw new TypeError('Expected an LLM task.')
+  const old = llmConfigurationView(previous)
+  const changed = (Object.keys(defaults) as DefaultName[]).filter(
+    (key) => Object.hasOwn(old, key) != Object.hasOwn(config, key) || !dequal(old[key], config[key]),
+  )
+  const inputs = previous.inputs.map((port): InputPort | Group => {
+    if (!('handle' in port)) return port
+    const key = changed.find((candidate) => defaults[candidate] == port.handle)
+    if (key == null) return port
+    const { value: _value, ...withoutDefault } = port
+    return Object.hasOwn(config, key) ? { ...withoutDefault, value: config[key] as JsonValue } : withoutDefault
+  })
+  return {
+    ...previous,
+    name,
+    executor: { ...previous.executor, mode: config.mode as 'chat' | 'json' },
+    inputs,
+    outputs: dequal(old.resultSchema, config.resultSchema)
+      ? previous.outputs
+      : previous.outputs.map((port) => ('handle' in port ? { ...port, jsonSchema: config.resultSchema as JsonValue } : port)),
+  }
+}
+
+/** Keep the production LLM factory's contracts while removing sample business data. */
+export function initialAuthoringLlmTask(task: ManagedTaskDefinition): ManagedTaskDefinition {
+  if (task.executor.kind != 'llm') throw new TypeError('Expected an LLM task.')
+  return {
+    ...task,
+    inputs: task.inputs.flatMap<InputPort | Group>((port) => {
+      if (!('handle' in port)) return [port]
+      if (port.handle == 'input') return []
+      if (port.handle == 'template') return [{ ...port, value: [{ role: 'user', content: '' }] }]
+      return [port]
+    }),
+  }
+}