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

package/src/flow/common/model.ts

@@ -0,0 +1,130 @@
+import type { JsonValue, Port, PortDefinition } from '../../types/index.ts'
+
+export type { JsonValue, Port, PortDefinition } from '../../types/index.ts'
+
+/** Primitives shared by every node family. Node unions and graph operations belong to change.ts. */
+
+export interface RetryConfiguration {
+  readonly maxRetries: number
+  readonly intervalMs: number
+}
+
+export interface InputPortDefinition extends PortDefinition {
+  readonly value?: JsonValue
+}
+
+export interface InputPort extends InputPortDefinition {
+  readonly handle: string
+}
+
+export interface Group {
+  readonly collapsed?: boolean
+  readonly group: string
+}
+
+export function portsByHandle<Value extends Port>(ports: readonly (Value | Group)[]): Readonly<Record<string, Value>> {
+  return Object.fromEntries(ports.flatMap((port) => ('handle' in port ? [[port.handle, port]] : [])))
+}
+
+export interface NodeSource {
+  readonly system?: true
+  readonly field?: string
+  readonly kind: 'node'
+  readonly nodeId: string
+  readonly output: string
+}
+
+export interface BindingSource {
+  readonly bindingId: string
+  readonly kind: 'binding'
+}
+
+export type FixedInputValue = { readonly kind: 'unset' } | { readonly kind: 'value'; readonly value: JsonValue }
+export type InputValues = Readonly<Record<string, FixedInputValue>>
+
+export type InputMapping = FixedInputValue | { readonly kind: 'sources'; readonly sources: readonly (BindingSource | NodeSource)[] }
+
+export interface GraphNodeBase {
+  readonly description?: string
+  readonly icon?: string
+  readonly inputs: Readonly<Record<string, InputMapping>>
+  readonly name?: string
+  readonly maxExecutions?: number
+  readonly timeoutMs?: number
+  readonly retry?: RetryConfiguration
+  readonly onError?: 'stop' | 'error'
+}
+
+export type Source = BindingSource | NodeSource
+
+export interface WorkflowCapability {
+  readonly kind: 'workflow'
+  readonly name: string
+  readonly flowId: string
+  readonly revisionId: string
+  readonly inputs: readonly Port[]
+  readonly outputs: readonly Port[] | null
+}
+
+/** Hosts that Code may call through `context.fetch`; requires Flow model 12 and Engine v9. */
+export interface HttpCapability {
+  readonly kind: 'http'
+  readonly hosts: readonly string[]
+}
+
+export type TaskCapability = ConnectorCapability | WorkflowCapability | HttpCapability
+
+export interface ConnectorAccessCapability {
+  readonly actionHints?: readonly string[]
+  readonly connectionHints?: readonly {
+    readonly action: string
+    readonly connectionId: string
+    readonly alias?: string
+  }[]
+  readonly kind: 'connector'
+}
+
+export interface ConnectorActionCapability {
+  readonly action: string
+  readonly connections: readonly { readonly connectionId: string; readonly alias?: string }[]
+  readonly connectionId?: string
+  readonly kind: 'connector'
+}
+
+export type ConnectorPermissionCapability =
+  | { readonly kind: 'connector'; readonly mode: 'shared' }
+  | { readonly kind: 'connector'; readonly mode: 'independent'; readonly actions: readonly { readonly action: string; readonly connectionId?: string }[] }
+
+export type ConnectorCapability = ConnectorAccessCapability | ConnectorActionCapability | ConnectorPermissionCapability
+
+export interface TaskDefinitionBase {
+  readonly inputs: readonly (InputPort | Group)[]
+  readonly name: string
+  readonly outputs: readonly (Port | Group)[]
+}
+
+export interface InlineTaskDefinition extends TaskDefinitionBase {
+  readonly capabilities?: readonly TaskCapability[]
+  readonly moduleId: string
+}
+
+/** The executor shape every managed Task shares; each node family narrows it with its own executor. */
+export interface TaskExecutor {
+  readonly kind: string
+}
+
+export interface ManagedTaskDefinitionOf<Executor extends TaskExecutor> extends TaskDefinitionBase {
+  readonly executor: Executor
+}
+
+export interface WorkflowExecutor {
+  readonly kind: 'workflow'
+  readonly flowId: string
+  readonly revisionId: string
+}
+
+export interface CodeModule {
+  readonly imports: readonly string[]
+  readonly name: string
+  readonly source: string
+}

package/src/flow/common/modules.ts

@@ -1,4 +1,4 @@
-import type { EngineContract } from '../../execution/common/engineContract.ts'
+import type { EngineContract } from '../../runtime/common/engineContract.ts'
 import type { RevisionContent } from './change.ts'
 import type { Diagnostic } from './semantics.ts'
 

package/src/flow/common/portChanges.ts

@@ -1,4 +1,4 @@
-import type { InputMapping } from './change.ts'
+import type { InputMapping } from './model.ts'
 
 export function renamedPort(
   previous: readonly ({ readonly handle: string } | { readonly group: string })[],

package/src/flow/common/retry.ts

@@ -1,13 +1,11 @@
 import type { GraphNode } from './change.ts'
+import type { RetryConfiguration } from './model.ts'
 
 import { z } from 'zod'
 
-export interface RetryConfiguration {
-  readonly maxRetries: number
-  readonly intervalMs: number
-}
+export type { RetryConfiguration } from './model.ts'
 
-export const retryNodeTypes = ['code', 'connector', 'openapi', 'llm', 'decision'] as const
+export const retryNodeTypes = ['code', 'connector', 'openapi', 'http-request', 'llm', 'decision'] as const
 export const nodeRetryLimits = { maxRetries: 5, minIntervalMs: 1000, maxIntervalMs: 60000, intervalStepMs: 1000 } as const
 export const defaultNodeRetry: RetryConfiguration = { maxRetries: 2, intervalMs: 2000 }
 export const retryConfigurationSchema = z.strictObject({

package/src/flow/common/semantics.ts

@@ -1,18 +1,20 @@
+import { dequal } from 'dequal/lite'
 import { decisionTaskIssues } from '../../decision/common/decision.ts'
+import { httpRequestIssues, httpAuthHandles, httpRequestTask, httpRequestUrl } from '../../http/common/httpRequest.ts'
 import { openApiIssues, authHandles } from '../../openapi/common/openapi.ts'
-import { nodeWorkflowReferences } from '../../workflow/common/workflow.ts'
 import { isTriggerNode } from './change.ts'
+import { nodeWorkflowReferences } from './workflowReferences.ts'
 export { renderPrompt } from './promptTemplate.ts'
 export { connectionUsage, removeConnectionUsage } from './connectionUsage.ts'
 import { matchesTriggerOutputs, normalizeTriggerOutputs } from '../../trigger/common/contract.ts'
 import { nodeInputMappings } from './condition.ts'
 import { connectionUsage } from './connectionUsage.ts'
 export { matchesTriggerOutputs, normalizeTriggerOutputs, triggerOutputDefinitions, triggerOutputPorts } from '../../trigger/common/contract.ts'
-import type { EngineContract } from '../../execution/common/engineContract.ts'
-import type { RuntimeProgram } from '../../execution/common/runtime.ts'
+import type { EngineContract } from '../../runtime/common/engineContract.ts'
+import type { RuntimeProgram } from '../../runtime/common/runtime.ts'
 import type { ConnectorActionCapability, ConnectorCapability, Graph, InputMapping, JsonValue, Port, RevisionContent, SchemaMismatch } from './change.ts'
 
-import { findEngineContract } from '../../execution/common/engineContract.ts'
+import { findEngineContract } from '../../runtime/common/engineContract.ts'
 import { agentConfigIssues } from './agent.ts'
 import { decodeTaskCapabilities } from './change.ts'
 import { canonicalJsonBytes, canonicalModule, canonicalRevisionGraph, digestBytes } from './encoding.ts'
@@ -271,13 +273,57 @@ export async function validateFlow(revision: RevisionContent, engine: EngineCont
       })
     for (const message of openApiIssues(task))
       checked.diagnostics.push({ code: 'openapi.config-invalid', column: 0, line: 1, message, path: `/document/graph/nodes/${nodeId}/task/executor` })
-    if (task.executor.kind == 'openapi') {
-      const handles = authHandles(task.executor.auth)
+    if (task.executor.kind == 'http-request') {
+      for (const issue of httpRequestIssues(task.executor))
+        checked.diagnostics.push({
+          code: 'http-request.config-invalid',
+          column: 0,
+          line: 1,
+          message: issue.message,
+          path: `/document/graph/nodes/${nodeId}/task/executor/${issue.field}`,
+        })
+      if (node.inputs.url?.kind == 'value') {
+        try {
+          httpRequestUrl(node.inputs.url.value)
+        } catch {
+          checked.diagnostics.push({
+            code: 'http-request.url-invalid',
+            column: 0,
+            line: 1,
+            message: 'Enter an HTTP(S) URL without embedded credentials.',
+            path: `/document/graph/nodes/${nodeId}/inputs/url`,
+          })
+        }
+      }
+      if (task.executor.bodyFormat != 'none' && (node.inputs.body == null || node.inputs.body.kind == 'unset'))
+        checked.diagnostics.push({
+          code: 'http-request.body-required',
+          column: 0,
+          line: 1,
+          message: 'Set or bind the request body; JSON null is an explicit value.',
+          path: `/document/graph/nodes/${nodeId}/inputs/body`,
+        })
+      const expected = httpRequestTask(task.executor)
+
+      if (
+        !dequal(httpPortContracts(task.inputs), httpPortContracts(expected.inputs)) ||
+        !dequal(httpPortContracts(task.outputs), httpPortContracts(expected.outputs))
+      )
+        checked.diagnostics.push({
+          code: 'http-request.ports-invalid',
+          column: 0,
+          line: 1,
+          message: 'HTTP Request ports must match its configuration.',
+          path: `/document/graph/nodes/${nodeId}/task`,
+        })
+    }
+    if (task.executor.kind == 'openapi' || task.executor.kind == 'http-request') {
+      const handles = task.executor.kind == 'openapi' ? authHandles(task.executor.auth) : httpAuthHandles(task.executor)
       for (const handle of handles) {
         const mapping = node.inputs[handle]
         if (mapping?.kind != 'sources' || mapping.sources.length == 0)
           checked.diagnostics.push({
-            code: 'openapi.auth-source',
+            code: `${task.executor.kind}.auth-source`,
             column: 0,
             line: 1,
             message: 'Authentication requires a deployment variable or upstream output.',
@@ -385,9 +431,27 @@ function runRevision(revision: RevisionContent, triggerId: string): RevisionCont
   }
 }
 
+const httpPortContracts = (ports: import('./change.ts').ManagedTaskDefinition['inputs']) =>
+  ports
+    .filter((port) => 'handle' in port)
+    .map(({ handle, jsonSchema, nullable }) => ({ handle, jsonSchema, nullable }))
+    .toSorted((a, b) => a.handle.localeCompare(b.handle))
+
 export async function prepareFlow(revision: RevisionContent, engineContract: string, triggerId?: string): Promise<PrepareFlowResult> {
   const engine = findEngineContract(engineContract)
   if (engine == null) return { kind: 'engine-unsupported' }
+  if (
+    !engine.httpRequests &&
+    Object.values(revision.document.graph.nodes).some((node) => node.kind == 'task' && 'executor' in node.task && node.task.executor.kind == 'http-request')
+  )
+    return { kind: 'engine-unsupported' }
+  if (
+    !engine.codeFetch &&
+    Object.values(revision.document.graph.nodes).some(
+      (node) => node.kind == 'task' && 'moduleId' in node.task && node.task.capabilities?.some((item) => item.kind == 'http'),
+    )
+  )
+    return { kind: 'engine-unsupported' }
   if (!engine.workflowTools && Object.values(revision.document.graph.nodes).some((node) => nodeWorkflowReferences(node).some((ref) => ref.tool != null)))
     return { kind: 'engine-unsupported' }
   if (triggerId != null) {

package/src/flow/common/webhookResponse.ts

@@ -1,4 +1,6 @@
-import type { InputPort, JsonValue, Port, PortDefinition } from './change.ts'
+import type { InputPort, JsonValue, Port, PortDefinition } from './model.ts'
+
+import { httpHeaderNameIssue } from '../../http/common/headers.ts'
 
 export const webhookResponseTimeout = {
   defaultMs: 30_000,
@@ -30,12 +32,6 @@ export function workflowOutputsPort(outputs: readonly Port[]): PortDefinition {
   } as const
 }
 
-/** Header names are case-insensitive; never silently combine duplicate business fields. */
-export function webhookHeaderNameIssue(name: string, names: readonly string[]): 'invalid' | 'duplicate' | undefined {
-  if (!/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(name)) return 'invalid'
-  if (names.some((candidate) => candidate.toLowerCase() === name.toLowerCase())) return 'duplicate'
-}
-
 /** Fixed inputs belong to the node, not author-supplied definitions. */
 export const webhookResponseInputs: readonly InputPort[] = [
   { handle: 'body', jsonSchema: {}, nullable: true, value: '' },
@@ -60,7 +56,7 @@ export function webhookHeaderValues(source: unknown): Readonly<Record<string, st
   const headers: Record<string, string> = {}
   const names: string[] = []
   for (const [name, value] of Object.entries(source)) {
-    if (webhookHeaderNameIssue(name, names) != null) return
+    if (httpHeaderNameIssue(name, names) != null) return
     if (typeof value !== 'string' && typeof value !== 'boolean' && !(typeof value === 'number' && Number.isFinite(value))) return
     const text = String(value)
     if ([...text].some((character) => character.charCodeAt(0) > 255 || /[\0\r\n]/.test(character))) return

package/src/flow/common/workflowReferences.ts

@@ -0,0 +1,31 @@
+import type { GraphNode } from './change.ts'
+import type { WorkflowCapability } from './model.ts'
+
+/** Workflow declarations share discovery across authoring, admission and resource indexing. */
+export function nodeWorkflowReferences(node: GraphNode): readonly {
+  readonly target: Omit<WorkflowCapability, 'kind' | 'name'>
+  readonly path: string
+  readonly tool?: string
+}[] {
+  if (node.kind != 'task') return []
+  if ('moduleId' in node.task)
+    return (node.task.capabilities ?? []).flatMap((item, index) =>
+      item.kind == 'workflow' ? [{ target: item, path: `task/capabilities/${index}`, tool: item.name }] : [],
+    )
+  if (node.task.executor.kind == 'workflow')
+    return [
+      {
+        target: {
+          ...node.task.executor,
+          inputs: node.task.inputs.filter((port) => 'handle' in port),
+          outputs: node.task.outputs.filter((port) => 'handle' in port),
+        },
+        path: 'task/executor',
+      },
+    ]
+  if (node.task.executor.kind == 'agent')
+    return node.task.executor.tools.flatMap((item, index) =>
+      item.kind == 'workflow' ? [{ target: item, path: `task/executor/tools/${index}`, tool: item.name }] : [],
+    )
+  return []
+}

package/src/http/common/authBindings.ts

@@ -0,0 +1,9 @@
+import type { InputMapping } from '../../flow/common/model.ts'
+
+/** Never allow credentials to enter a Revision as literal inputs of an OpenAPI or HTTP request node. */
+export function assertHttpAuthBindings(inputs: Readonly<Record<string, InputMapping>>): void {
+  for (const [handle, mapping] of Object.entries(inputs)) {
+    if (handle.startsWith('auth.') && mapping.kind == 'value')
+      throw new TypeError('HTTP authentication accepts deployment variables and upstream outputs only.')
+  }
+}

package/src/http/common/headers.ts

@@ -0,0 +1,5 @@
+/** Header names are case-insensitive; never silently combine duplicate business fields. */
+export function httpHeaderNameIssue(name: string, names: readonly string[]): 'invalid' | 'duplicate' | undefined {
+  if (!/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(name)) return 'invalid'
+  if (names.some((candidate) => candidate.toLowerCase() === name.toLowerCase())) return 'duplicate'
+}

package/src/http/common/hosts.ts

@@ -0,0 +1,13 @@
+/** Hosts of a Code `http` Capability: lowercase DNS names or IPv4 addresses; `*.example.com` matches subdomains only. */
+export const httpHostPattern = /^(?:\*\.)?(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)*[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/
+export const maxHttpHosts = 20
+
+/** Wildcards must name a registrable suffix, so `*.com` is rejected. */
+export function isHttpHost(value: string): boolean {
+  return httpHostPattern.test(value) && (!value.startsWith('*.') || value.slice(2).includes('.'))
+}
+
+export function httpHostAllowed(hosts: readonly string[], hostname: string): boolean {
+  const host = hostname.toLowerCase()
+  return hosts.some((pattern) => (pattern.startsWith('*.') ? host.endsWith(pattern.slice(1)) : host == pattern))
+}

package/src/http/common/httpRequest.ts

@@ -0,0 +1,266 @@
+import type { InputMapping, InputPort, JsonValue, ManagedTaskDefinitionOf, TaskDefinitionBase, TaskExecutor } from '../../flow/common/model.ts'
+
+import { dequal } from 'dequal/lite'
+import { z } from 'zod'
+import { remapInputMappings, renamedPort } from '../../flow/common/portChanges.ts'
+import { httpHeaderNameIssue } from './headers.ts'
+
+export { httpHostAllowed, isHttpHost, maxHttpHosts } from './hosts.ts'
+
+const parameterSchema = z.strictObject({ mode: z.enum(['fields', 'object']).default('fields'), names: z.array(z.string()).default([]) })
+export const httpRequestConfigSchema = z.strictObject({
+  method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']).default('GET'),
+  query: parameterSchema.default({ mode: 'fields', names: [] }),
+  headers: parameterSchema.default({ mode: 'fields', names: [] }),
+  bodyFormat: z.enum(['none', 'json', 'text', 'form']).default('none'),
+  authentication: z
+    .union([
+      z.strictObject({ type: z.literal('none') }),
+      z.strictObject({ type: z.enum(['bearer', 'basic']) }),
+      z.strictObject({ type: z.literal('apiKey'), name: z.string(), in: z.enum(['header', 'query']) }),
+    ])
+    .default({ type: 'none' }),
+  responseFormat: z.enum(['auto', 'json', 'text']).default('auto'),
+  statusPolicy: z.enum(['success', 'all']).default('success'),
+})
+export type HttpRequestConfig = z.infer<typeof httpRequestConfigSchema>
+export interface HttpRequestExecutor extends HttpRequestConfig {
+  readonly kind: 'http-request'
+}
+export const httpRequestExecutorSchema = httpRequestConfigSchema.extend({ kind: z.literal('http-request') })
+const scalarSchema = { type: ['string', 'number', 'boolean'] }
+const queryValueSchema = { anyOf: [scalarSchema, { type: 'array', items: scalarSchema }] }
+export const httpHeaderSchema = { type: 'object', additionalProperties: { type: 'string' } }
+export const httpQuerySchema = { type: 'object', additionalProperties: queryValueSchema }
+
+export function httpAuthHandles(config: HttpRequestConfig): string[] {
+  return config.authentication.type == 'none' ? [] : config.authentication.type == 'basic' ? ['auth.username', 'auth.password'] : ['auth.token']
+}
+// Preserve metadata on ports whose contracts did not change.
+function retain(ports: readonly InputPort[], old: TaskDefinitionBase['inputs']): TaskDefinitionBase['inputs'] {
+  const remaining = new Map(ports.map((port) => [port.handle, port]))
+  return [
+    ...old.flatMap((item): TaskDefinitionBase['inputs'] => {
+      if ('group' in item) return [item]
+      const next = remaining.get(item.handle)
+      if (next == null) return []
+      remaining.delete(item.handle)
+      return [dequal(item.jsonSchema, next.jsonSchema) && item.nullable == next.nullable ? item : next]
+    }),
+    ...remaining.values(),
+  ]
+}
+export function httpRequestTask(
+  config: HttpRequestConfig = httpRequestConfigSchema.parse({}),
+  name = 'HTTP Request',
+  previous?: TaskDefinitionBase,
+): ManagedTaskDefinitionOf<HttpRequestExecutor> {
+  const inputs: InputPort[] = [{ handle: 'url', jsonSchema: { type: 'string' }, nullable: false }]
+  for (const group of ['query', 'headers'] as const) {
+    if (config[group].mode == 'object') inputs.push({ handle: group, jsonSchema: group == 'query' ? httpQuerySchema : httpHeaderSchema, nullable: true })
+    else
+      for (const parameterName of config[group].names.filter((value) => value.trim()))
+        inputs.push({
+          handle: `${group == 'query' ? 'query' : 'header'}.${parameterName}`,
+          jsonSchema: group == 'query' ? queryValueSchema : { type: 'string' },
+          nullable: true,
+        })
+  }
+  if (config.bodyFormat != 'none')
+    inputs.push({
+      handle: 'body',
+      jsonSchema: config.bodyFormat == 'json' ? {} : config.bodyFormat == 'text' ? { type: 'string' } : httpQuerySchema,
+      nullable: config.bodyFormat == 'json',
+    })
+  inputs.push(...httpAuthHandles(config).map((handle) => ({ handle, jsonSchema: { type: 'string' }, nullable: false })))
+  const outputs: InputPort[] = [
+    { handle: 'body', jsonSchema: config.responseFormat == 'text' ? { type: 'string' } : {}, nullable: true },
+    { handle: 'statusCode', jsonSchema: { type: 'integer' }, nullable: false },
+    { handle: 'headers', jsonSchema: httpHeaderSchema, nullable: false },
+  ]
+
+  return {
+    name,
+    executor: { ...config, kind: 'http-request' },
+    inputs: retain(inputs, previous?.inputs ?? []),
+    outputs: retain(outputs, previous?.outputs ?? []),
+  }
+}
+export interface HttpRequestIssue {
+  field: string
+  index?: number
+  code: 'bodyUnsupported' | 'parameterNamesInvalid' | 'headerNameInvalid' | 'keyNameRequired' | 'authConflict'
+  message: string
+}
+export function httpRequestIssues(config: HttpRequestConfig): HttpRequestIssue[] {
+  const issues: HttpRequestIssue[] = []
+  if (['GET', 'HEAD'].includes(config.method) && config.bodyFormat != 'none')
+    issues.push({ field: 'bodyFormat', code: 'bodyUnsupported', message: 'GET and HEAD do not support a request body.' })
+  for (const group of ['query', 'headers'] as const) {
+    if (config[group].mode != 'fields') continue
+    const seen = new Set<string>()
+    for (const [index, name] of config[group].names.entries()) {
+      const key = group == 'headers' ? name.toLowerCase() : name
+      if (!name.trim() || seen.has(key))
+        issues.push({ field: group, index, code: 'parameterNamesInvalid', message: 'Parameter names must be nonempty and unique.' })
+      seen.add(key)
+      if (group == 'headers' && httpHeaderNameIssue(name, []) === 'invalid')
+        issues.push({ field: group, index, code: 'headerNameInvalid', message: 'Invalid HTTP header name.' })
+    }
+  }
+  const auth = config.authentication
+  if (auth.type != 'none') {
+    const group = auth.type == 'apiKey' && auth.in == 'query' ? 'query' : 'headers'
+    const name = auth.type == 'apiKey' ? auth.name : 'authorization'
+    if (!name.trim()) issues.push({ field: 'authentication', code: 'keyNameRequired', message: 'API Key requires a name.' })
+    if (group == 'headers' && name.trim() && httpHeaderNameIssue(name, []) === 'invalid')
+      issues.push({ field: 'authentication', code: 'headerNameInvalid', message: 'Invalid authentication header name.' })
+    if (config[group].mode == 'fields' && config[group].names.some((item) => (group == 'headers' ? item.toLowerCase() == name.toLowerCase() : item == name)))
+      issues.push({ field: 'authentication', code: 'authConflict', message: 'Authentication conflicts with a request parameter.' })
+  }
+  return issues
+}
+function entries(value: JsonValue | undefined): [string, JsonValue][] {
+  if (value == null) return []
+  if (typeof value != 'object' || Array.isArray(value)) throw new Error('Expected a parameter object.')
+  return Object.entries(value)
+}
+function scalar(value: JsonValue): string {
+  if (typeof value != 'string' && typeof value != 'number' && typeof value != 'boolean') throw new Error('Expected a scalar parameter.')
+  return String(value)
+}
+function append(query: URLSearchParams, name: string, value: JsonValue): void {
+  for (const item of Array.isArray(value) ? value : [value]) query.append(name, scalar(item))
+}
+export function httpRequestUrl(value: unknown): URL {
+  if (typeof value != 'string' || !value.trim()) throw new Error('A URL is required.')
+  const url = new URL(value)
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password) throw new Error('An HTTP(S) URL without credentials is required.')
+  return url
+}
+export function buildHttpRequest(config: HttpRequestConfig, input: Readonly<Record<string, JsonValue>>): { url: string; init: RequestInit } {
+  if (httpRequestIssues(config).length) throw new Error('Invalid HTTP request configuration.')
+  const url = httpRequestUrl(input.url)
+  const parameters = (group: 'query' | 'headers') =>
+    config[group].mode == 'object'
+      ? entries(input[group])
+      : config[group].names.flatMap((name): [string, JsonValue][] => {
+          const value = input[`${group == 'query' ? 'query' : 'header'}.${name}`]
+          return value == null ? [] : [[name, value]]
+        })
+  for (const [name, value] of parameters('query')) {
+    url.searchParams.delete(name)
+    append(url.searchParams, name, value)
+  }
+  const headers = new Headers()
+  for (const [name, value] of parameters('headers')) {
+    if (headers.has(name)) throw new Error('Duplicate HTTP header.')
+    if (typeof value != 'string') throw new Error('HTTP headers require text values.')
+    headers.set(name, value)
+  }
+  const auth = config.authentication
+  const credential = (part: string) => {
+    const value = input[`auth.${part}`]
+    if (typeof value != 'string' || !value) throw new Error('Authentication source is required.')
+    return value
+  }
+  if (auth.type != 'none') {
+    const name = auth.type == 'apiKey' ? auth.name : 'authorization'
+    if (auth.type == 'apiKey' && auth.in == 'query') {
+      if (url.searchParams.has(name)) throw new Error('Authentication conflicts with a query parameter.')
+      url.searchParams.set(name, credential('token'))
+    } else {
+      if (headers.has(name)) throw new Error('Authentication conflicts with a header.')
+      if (auth.type == 'basic') {
+        const username = credential('username')
+        if (username.includes(':')) throw new Error('Basic username cannot contain a colon.')
+        const bytes = new TextEncoder().encode(`${username}:${credential('password')}`)
+        headers.set(name, `Basic ${btoa(Array.from(bytes, (byte) => String.fromCharCode(byte)).join(''))}`)
+      } else headers.set(name, auth.type == 'bearer' ? `Bearer ${credential('token')}` : credential('token'))
+    }
+  }
+  let body: string | undefined
+  if (config.bodyFormat != 'none') {
+    if (!Object.hasOwn(input, 'body')) throw new Error('Request body is unset.')
+    let contentType: string
+    if (config.bodyFormat == 'json') {
+      body = JSON.stringify(input.body)
+      contentType = 'application/json'
+    } else if (config.bodyFormat == 'text') {
+      if (typeof input.body != 'string') throw new Error('Text body requires a string.')
+      body = input.body
+      contentType = 'text/plain'
+    } else {
+      if (input.body == null) throw new Error('Form body requires an object.')
+      const form = new URLSearchParams()
+      for (const [name, value] of entries(input.body)) append(form, name, value)
+      body = form.toString()
+      contentType = 'application/x-www-form-urlencoded'
+    }
+    const supplied = headers.get('content-type')
+    if (config.bodyFormat != 'text' && supplied != null && supplied.split(';')[0]!.trim().toLowerCase() != contentType)
+      throw new Error('Content-Type conflicts with body format.')
+    if (supplied == null) headers.set('content-type', contentType)
+  }
+  return { url: url.href, init: { method: config.method, headers, body, redirect: 'manual' } }
+}
+export function parseHttpResponse(config: HttpRequestConfig, status: number, headers: Headers, text: string): Record<string, JsonValue> {
+  if (config.statusPolicy == 'success' && (status < 200 || status >= 300)) throw new Error(`HTTP ${status}`)
+  let body: JsonValue = null
+  if (text && config.method != 'HEAD' && ![204, 205, 304].includes(status)) {
+    const media = (headers.get('content-type') ?? '').split(';')[0]!.trim().toLowerCase()
+    body =
+      config.responseFormat == 'json' || (config.responseFormat == 'auto' && /^application\/(json|.+\+json)$/.test(media))
+        ? (JSON.parse(text) as JsonValue)
+        : text
+  }
+  return { body, statusCode: status, headers: Object.fromEntries([...headers].filter(([name]) => name != 'set-cookie')) }
+}
+
+/** Only a named parameter rename carries a value; changing source modes is not a rename. */
+export function httpRequestInputs(
+  mappings: Readonly<Record<string, InputMapping>>,
+  previous: TaskDefinitionBase,
+  next: TaskDefinitionBase,
+): Record<string, InputMapping> {
+  const candidate = renamedPort(previous.inputs, next.inputs)
+  const rename = candidate != null && ['query.', 'header.'].some((prefix) => candidate.every((name) => name.startsWith(prefix))) ? candidate : undefined
+  return remapInputMappings(mappings, next.inputs, rename)
+}
+
+/** A Task node as HTTP helpers read it; inline Tasks have no executor. */
+interface HttpTaskNode {
+  readonly inputs: Readonly<Record<string, InputMapping>>
+  readonly task: TaskDefinitionBase & { readonly executor?: TaskExecutor }
+}
+
+function httpRequestExecutor(node: HttpTaskNode): HttpRequestExecutor | undefined {
+  const executor = node.task.executor
+  return executor?.kind === 'http-request' ? (executor as HttpRequestExecutor) : undefined
+}
+
+/** The object editor assembles named inputs without changing unrelated request settings. */
+export function withHttpParameterFields<Node extends HttpTaskNode>(node: Node, group: 'query' | 'headers', values: Record<string, JsonValue>): Node {
+  const config = httpRequestExecutor(node)
+  if (config == null) return node
+  const task = httpRequestTask({ ...config, [group]: { mode: 'fields', names: Object.keys(values) } }, node.task.name, node.task)
+  const inputs = httpRequestInputs(node.inputs, node.task, task)
+  const rename = renamedPort(node.task.inputs, task.inputs)
+  for (const [name, value] of Object.entries(values)) {
+    const handle = `${group === 'query' ? 'query' : 'header'}.${name}`
+    const existing = config[group].mode === 'fields' && (config[group].names.includes(name) || rename?.[1] === handle)
+    if (inputs[handle] == null && !existing) inputs[handle] = { kind: 'value', value }
+  }
+  // Only the HTTP Task and its input mappings change, so the node keeps its own type.
+  return { ...node, task, inputs } as Node
+}
+
+export function withHttpParameterSource<Node extends HttpTaskNode>(node: Node, group: 'query' | 'headers', mapping?: InputMapping): Node {
+  const config = httpRequestExecutor(node)
+  if (config == null) return node
+  const task = httpRequestTask({ ...config, [group]: { mode: 'object', names: [] } }, node.task.name, node.task)
+  const inputs = httpRequestInputs(node.inputs, node.task, task)
+  if (mapping == null) delete inputs[group]
+  else inputs[group] = mapping
+  return { ...node, task, inputs } as Node
+}