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

package/dist/index.d.ts

@@ -20,18 +20,50 @@ export interface ArtifactRef {
     readonly kind: 'artifact';
     readonly id: string;
     readonly name: string;
-    readonly mediaType: string | undefined;
+    readonly mediaType?: string;
     readonly size: number;
     readonly digest: string;
 }
 export interface ArtifactPutOptions {
     readonly name: string;
-    readonly mediaType?: string | undefined;
+    readonly mediaType?: string;
 }
-export type ArtifactData = Uint8Array | Blob | ReadableStream<Uint8Array>;
+/** Strings are stored as UTF-8. */
+export type ArtifactData = string | Uint8Array;
+/** Artifacts belong to the current Run; an ArtifactRef is JSON and can be passed to downstream nodes. */
 export interface ArtifactCapability {
     put(data: ArtifactData, options: ArtifactPutOptions): Promise<ArtifactRef>;
-    open(ref: ArtifactRef): Promise<ReadableStream<Uint8Array>>;
+    open(ref: ArtifactRef): Promise<Uint8Array>;
+}
+export interface TaskFetchInit {
+    /** GET, HEAD, POST, PUT, PATCH, DELETE or OPTIONS. */
+    readonly method?: string;
+    readonly headers?: Readonly<Record<string, string>> | Iterable<readonly [string, string]>;
+    /** At most 1 MiB; strings are sent as UTF-8 text/plain unless a content-type header is supplied. */
+    readonly body?: string | Uint8Array | ArrayBuffer;
+    readonly signal?: AbortSignal;
+}
+export interface TaskFetchHeaders extends Iterable<[string, string]> {
+    get(name: string): string | null;
+    has(name: string): boolean;
+    entries(): IterableIterator<[string, string]>;
+    keys(): IterableIterator<string>;
+    values(): IterableIterator<string>;
+    forEach(callback: (value: string, name: string) => void): void;
+}
+/** A read-only subset of the Fetch Response; the body is buffered, at most 1 MiB, and readable once. */
+export interface TaskFetchResponse {
+    readonly status: number;
+    readonly statusText: string;
+    readonly ok: boolean;
+    readonly redirected: false;
+    readonly url: string;
+    readonly headers: TaskFetchHeaders;
+    readonly bodyUsed: boolean;
+    bytes(): Promise<Uint8Array>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    text(): Promise<string>;
+    json(): Promise<unknown>;
 }
 export interface MediaPreviewPayload {
     readonly type: 'video' | 'audio' | 'markdown' | 'iframe' | 'html';
@@ -60,12 +92,6 @@ export interface CsvPreviewPayload {
 }
 export type PreviewPayload = MediaPreviewPayload | TextPreviewPayload | ImagePreviewPayload | TablePreviewPayload | CsvPreviewPayload;
 export type PreviewType = PreviewPayload['type'];
-export interface TaskLogger {
-    debug(message: string, data?: unknown): void;
-    info(message: string, data?: unknown): void;
-    warn(message: string, data?: unknown): void;
-    error(message: string, data?: unknown): void;
-}
 export interface TaskContext<Actions extends object = Record<string, never>, Workflows extends object = {
     call: (name: never, input?: never) => Promise<never>;
 }> {
@@ -77,12 +103,13 @@ export interface TaskContext<Actions extends object = Record<string, never>, Wor
     readonly runId: string;
     readonly blockId: string;
     readonly artifact: ArtifactCapability;
-    readonly fetch: typeof fetch;
-    readonly logger: TaskLogger;
     /** Reads the selected direct predecessors, sorted by node ID; empty for a graph root. */
     getPrevious(): Promise<readonly PreviousNode[]>;
-    preview(payload: PreviewPayload, id?: string): Promise<void>;
-    reportProgress(progress: number): Promise<void>;
+    /**
+     * Calls an HTTP(S) URL whose host the node declares in its `http` Capability. Redirects are returned, not followed,
+     * and no platform credentials are added. Network failures reject with a TypeError.
+     */
+    fetch(input: string | URL, init?: TaskFetchInit): Promise<TaskFetchResponse>;
 }
 export type TaskResult<Outputs extends object> = keyof Outputs extends never ? Outputs | void : Outputs;
 export interface Task<Inputs extends object = Record<string, unknown>, Outputs extends object = Record<string, unknown>, Actions extends object = Record<string, never>, Workflows extends object = TaskContext['workflows']> {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oomol-lab/open-flow",
-  "version": "0.1.0-beta.74",
+  "version": "0.1.0-beta.76",
   "description": "TypeScript contracts and Browser runtime for Open Flow.",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
@@ -25,6 +25,10 @@
       "types": "./dist/common/decision.d.ts",
       "import": "./dist/common/decision.js"
     },
+    "./http-request": {
+      "types": "./dist/common/http-request.d.ts",
+      "import": "./dist/common/http-request.js"
+    },
     "./openapi": {
       "types": "./dist/common/openapi.d.ts",
       "import": "./dist/common/openapi.js"
@@ -109,6 +113,10 @@
       "types": "./dist/common/runtime-contract.d.ts",
       "import": "./dist/common/runtime-contract.js"
     },
+    "./runtime-nodejs-compat": {
+      "types": "./dist/common/runtime-nodejs-compat.d.ts",
+      "import": "./dist/common/runtime-nodejs-compat.js"
+    },
     "./scheduler": {
       "types": "./dist/common/scheduler.d.ts",
       "import": "./dist/common/scheduler.js"

package/skills/open-flow/references/flow-authoring.md

@@ -298,6 +298,7 @@ For Connector Tasks, independent Code Actions, Agent tools and notifications, an
 | Manual, HTTP or scheduled entry | `start`, `webhook`, `cron`: workflow `inputDefs`, HTTP body fields, or schedule.                                                                                                                                                    |
 | Workflow failure handler        | `error`: published upstream Flows' automatic Run failures; not a node-level catch or a handler for manual Run failures.                                                                                                             |
 | Call another workflow           | `workflow`: select an owned published Flow ID; inputs and outputs derive from its saved contract. Use `node.refresh` to update it.                                                                                                  |
+| Single HTTP request             | `http-request`: method, parameter modes, authentication, body and response configuration; URL and request values use public inputs.                                                                                                 |
 | Fixed HTTP operation            | `openapi`: an OpenAPI source, path and method; resolved authentication choices and ports appear in node details.                                                                                                                    |
 | Reusable constants              | `value`: named JSON values and optional output constraints.                                                                                                                                                                         |
 | Durable interaction             | `wait`, `approval`: prompt and named inputs; resume through the Run's Wait ID. Wait additionally supports optional `config.autoContinue` with `{kind:"after",durationMs:86400000}` or `{kind:"at",at:"2026-10-25T10:00:00+08:00"}`. |

package/skills/open-flow/references/flow-n8n-conversion.md

@@ -13,17 +13,17 @@ publishing and enabling remain separate actions within the user's authorization.
 
 ## Choose a representation
 
-| Source behavior                               | Open Flow building blocks                       | What determines a good fit                                                     |
-| --------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------ |
-| Scheduled, webhook or provider event          | Cron, Webhook, Poll or Integration Trigger      | Schedule/timezone, event payload, delivery and response behavior.              |
-| Provider read or write                        | Connector                                       | Exact operation, input/output shape, account and number of calls.              |
-| Field shaping, filtering, aggregation or join | Code with named input/output fields             | Explicit collection representation, ordering, keys and empty-input behavior.   |
-| IF or Switch                                  | Condition and named execution branches          | Predicate, first/all matches, fallback route and data sent onward.             |
-| Prompt plus model and output parser           | LLM with template, inputs and `resultSchema`    | Supported model, result shape and any parser repair behavior.                  |
-| Agent with tools or memory                    | Agent where its current contract fits           | Tool permissions, state lifetime and how context is supplied.                  |
-| HTTP request                                  | OpenAPI where an actual operation contract fits | Method, parameters, auth, response format and error behavior.                  |
-| Human response or durable pause               | Wait or Approval                                | Who resumes it, payload, timing, notification and external response lifecycle. |
-| Workflow failure handling                     | Error Trigger where its scope fits              | Which failures trigger it and what failure data it receives.                   |
+| Source behavior                               | Open Flow building blocks                               | What determines a good fit                                                     |
+| --------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| Scheduled, webhook or provider event          | Cron, Webhook, Poll or Integration Trigger              | Schedule/timezone, event payload, delivery and response behavior.              |
+| Provider read or write                        | Connector                                               | Exact operation, input/output shape, account and number of calls.              |
+| Field shaping, filtering, aggregation or join | Code with named input/output fields                     | Explicit collection representation, ordering, keys and empty-input behavior.   |
+| IF or Switch                                  | Condition and named execution branches                  | Predicate, first/all matches, fallback route and data sent onward.             |
+| Prompt plus model and output parser           | LLM with template, inputs and `resultSchema`            | Supported model, result shape and any parser repair behavior.                  |
+| Agent with tools or memory                    | Agent where its current contract fits                   | Tool permissions, state lifetime and how context is supplied.                  |
+| HTTP request                                  | `http-request`, or `openapi` for a documented operation | Method, parameters, auth, response format and error behavior.                  |
+| Human response or durable pause               | Wait or Approval                                        | Who resumes it, payload, timing, notification and external response lifecycle. |
+| Workflow failure handling                     | Error Trigger where its scope fits                      | Which failures trigger it and what failure data it receives.                   |
 
 Use `schema TYPE` and provider discovery for the actual deployment. A node's
 name alone does not establish equivalence. Provider operations can differ even
@@ -120,10 +120,14 @@ inside URLs, headers, expressions or Code; keep those out of Drafts and reports.
 Use supported credential bindings for the selected operation. A missing account
 can leave a Draft incomplete without implying that the action itself is absent.
 
-For HTTP Request conversion, `schema openapi` describes source URL, operation
-selection and supported authentication. Check the actual operation's response,
-non-success status, redirect, binary and retry requirements against that contract.
-An invented API specification does not establish support for an unknown operation.
+For HTTP Request conversion, `schema http-request` describes a single request's
+method, parameter modes, body, authentication and response handling. Bind `url`,
+request parameters and body through public inputs. Authentication inputs require
+variables or upstream outputs. Query arrays become repeated parameters; response
+arrays remain one value. The first version does not follow redirects or support
+pagination, files, OAuth or direct Agent tools. Check these requirements before
+calling the conversion equivalent. Use `schema openapi` when an actual operation
+contract is available; do not invent an API specification to make a request.
 
 A provider event may expose an ID where the source expected a full record. A
 Connector read can supply the missing data if it preserves the desired behavior.

package/src/base/common/json.ts

@@ -1,4 +1,4 @@
-export type JsonValue = null | boolean | number | string | readonly JsonValue[] | JsonObject
+import type { JsonValue } from '../../types/index.ts'
 
 export type JsonObject = { readonly [key: string]: JsonValue }
 

package/src/connector/common/proxy.ts

@@ -1,5 +1,5 @@
 import type { SourceOperation, SourceReferenceOperation } from '../../event-source/common/definition.ts'
-import type { JsonValue } from '../../flow/common/change.ts'
+import type { JsonValue } from '../../types/index.ts'
 export type TriggerOperationRequest =
   | { readonly operation: 'sourceReference'; readonly request: SourceReferenceOperation }
   | { readonly operation: 'source'; readonly request: SourceOperation }

package/src/control/common/api.ts

@@ -1,6 +1,6 @@
 import type { CanvasCommand } from '../../canvas/common/commands.ts'
 
-import { currentEngineContract } from '../../execution/common/engineContract.ts'
+import { currentEngineContract } from '../../runtime/common/engineContract.ts'
 import { workflowContractSchema, workflowReferencesSchema } from '../../workflow/common/workflow.ts'
 export type { CanvasCommand, CanvasCommandSubscriber } from '../../canvas/common/commands.ts'
 import type { LiveDetails } from './liveDetails.ts'
@@ -9,12 +9,12 @@ import { decodeLiveDetails } from './liveDetails.ts'
 export { liveEntries } from './liveDetails.ts'
 export { flowInputDefinitions } from './authoringFields.ts'
 export type { LiveDetails, LiveEntry } from './liveDetails.ts'
+import type { ProviderIconAppearance } from '../../connector/common/providerIconSprite.ts'
 import type { AuthoringRead, AuthoringSearch, AuthoringRequest, AuthoringType } from './authoringSchema.ts'
-import type { ProviderIconAppearance } from './providerIconSprite.ts'
 
 import { authoringReadResponse, authoringSearchResponse, authoringEditResponse, authoringCheckResponse } from './authoringSchema.ts'
-export { providerIconAppearance } from './providerIconSprite.ts'
-export type { ProviderIconAppearance, ProviderIconSprite, ProviderIconSpriteCatalog } from './providerIconSprite.ts'
+export { providerIconAppearance } from '../../connector/common/providerIconSprite.ts'
+export type { ProviderIconAppearance, ProviderIconSprite, ProviderIconSpriteCatalog } from '../../connector/common/providerIconSprite.ts'
 export { connectorAccess as decodeConnectorAccess, connectorAccessSnapshot as decodeConnectorAccessSnapshot } from './connectorDecoders.ts'
 import type { ProviderAccessIdentity, ProviderAccessReference } from './providerAccess.ts'
 export {
@@ -35,7 +35,8 @@ export { decodeEventSource, decodeEventSources, type CreateEventSource, type Upd
 import type { TriggerCatalogCache } from './triggerCatalog.ts'
 
 import { decodeTriggerCatalog } from './triggerCatalog.ts'
-export { decodeTriggerCatalog, searchTriggerKeys, type TriggerCatalog, type TriggerCatalogCache, type TriggerDisplay } from './triggerCatalog.ts'
+export { decodeTriggerCatalog, searchTriggerKeys, type TriggerCatalog, type TriggerCatalogCache } from './triggerCatalog.ts'
+export type { TriggerDisplay } from '../../trigger/providers/localization.ts'
 import type { TriggerConfigOption } from '../../trigger/common/configOptions.ts'
 export type { TriggerConfigOption } from '../../trigger/common/configOptions.ts'
 import type { ResultQuery } from './results.ts'
@@ -675,6 +676,7 @@ export function decodeRunEvent(value: unknown) {
             nodeKind !== 'javascript' &&
             nodeKind !== 'decision' &&
             nodeKind !== 'openapi' &&
+            nodeKind !== 'http-request' &&
             nodeKind !== 'llm' &&
             nodeKind !== 'agent' &&
             nodeKind !== 'value' &&

package/src/control/common/authoring.ts

@@ -42,6 +42,7 @@ import {
   renameFlowOutputSources,
 } from '../../flow/common/nodeChanges.ts'
 import { retryConfigurationSchema } from '../../flow/common/retry.ts'
+import { httpRequestTask, httpRequestConfigSchema, httpRequestInputs } from '../../http/common/httpRequest.ts'
 import { withWorkflowTask, workflowTask, workflowSelectionTask, workflowCapability, workflowAgentTool } from '../../workflow/common/workflow.ts'
 import { conditionConfigurationView, prepareConditionConfiguration } from './authoringCondition.ts'
 import { authoringDiagnosticField } from './authoringDiagnosticFields.ts'
@@ -145,7 +146,10 @@ export function authoringNode(content: RevisionContent, ref: string) {
         ),
       }
     else if (task.executor.kind == 'workflow') config = { flowId: task.executor.flowId }
-    else if (task.executor.kind == 'openapi') {
+    else if (task.executor.kind == 'http-request') {
+      const { kind: _kind, ...settings } = task.executor
+      config = settings
+    } else if (task.executor.kind == 'openapi') {
       config = { ...openApiConfigView(task.executor) }
     }
   } else if (node.kind == 'task' && 'moduleId' in node.task) {
@@ -442,7 +446,8 @@ export async function compileAuthoring(base: RevisionContent, request: Authoring
       const timing = record(record(patch.config).autoContinue)
       if (Object.hasOwn(timing, 'kind') && timing.kind != record(record(view.config).autoContinue).kind) record(update.config).autoContinue = timing
     }
-    if (type == 'openapi' && Object.hasOwn(record(patch.config), 'authentication')) record(update.config).authentication = record(patch.config).authentication
+    if ((type == 'openapi' || type == 'http-request') && Object.hasOwn(record(patch.config), 'authentication'))
+      record(update.config).authentication = record(patch.config).authentication
     for (const path of clear) clearPath(update, path)
     if (typeof update.name != 'string') fail('node.name-required', 'Node name cannot be cleared.')
     const config = authoringConfigurations[type].parse(update.config) as Record<string, unknown>
@@ -516,7 +521,10 @@ export async function compileAuthoring(base: RevisionContent, request: Authoring
           task = { ...before, name: String(update.name), executor: { ...executor, ...config } } as ManagedTaskDefinition
         } else task = await connectorTask(config, String(update.name))
       } else if (type == 'decision') task = decisionTask(config.questions as Parameters<typeof decisionTask>[0], String(update.name))
-      else if (type == 'openapi') {
+      else if (type == 'http-request') {
+        task = httpRequestTask(httpRequestConfigSchema.parse(config), String(update.name), before)
+        next = { ...next, inputs: httpRequestInputs(node.inputs, before, task) } as GraphNode
+      } else if (type == 'openapi') {
         task = await prepareOpenApiTask(config as AuthoringOpenApiConfig, before, (url) => host.openapi(url), String(update.name), {
           authentication: explicit('authentication'),
           serverUrl: explicit('serverUrl'),
@@ -766,6 +774,9 @@ export async function compileAuthoring(base: RevisionContent, request: Authoring
             case 'connector':
               changes = createManagedTask(identity, await connectorTask(config, name))
               break
+            case 'http-request':
+              changes = createManagedTask(identity, httpRequestTask(httpRequestConfigSchema.parse(config), name))
+              break
             case 'openapi':
               changes = createManagedTask(
                 identity,

package/src/control/common/authoringExamples.ts

@@ -11,6 +11,7 @@ import {
   createValue,
   createWait,
 } from '../../flow/common/nodeChanges.ts'
+import { httpRequestTask } from '../../http/common/httpRequest.ts'
 import { openApiTask, selectOperation } from '../../openapi/common/openapi.ts'
 
 const descriptions = {
@@ -22,6 +23,7 @@ const descriptions = {
   '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.',
+  'http-request': 'A single HTTP request. Bind url and request inputs; outputs are body, statusCode and headers.',
   '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.',
@@ -55,6 +57,12 @@ export function authoringExample(name: string): { version: 1; operations: readon
         { name: 'needs_support', type: 'noul', instructions: 'Does the customer need support?' },
       ])
       break
+    case 'http-request':
+      operations = [
+        ...createManagedTask({ nodeId: 'http' }, httpRequestTask()),
+        { kind: 'graph.node.input.set', nodeId: 'http', handle: 'url', value: { kind: 'value', value: 'https://example.com' } },
+      ]
+      break
     case 'openapi': {
       const document = {
         openapi: '3.1.0',

package/src/control/common/authoringSchema.ts

@@ -6,9 +6,12 @@ import {
   connectorAgentToolSchema,
   workflowAgentToolSchema,
   connectorCapabilitySchema,
+  httpCapabilitySchema,
   authoringDefinitionSchemas as definitions,
 } from '../../flow/common/changeSchema.ts'
 import { retryConfigurationSchema, retryNodeTypes } from '../../flow/common/retry.ts'
+import { httpRequestConfigSchema } from '../../http/common/httpRequest.ts'
+import { currentEngineContract, findEngineContract } from '../../runtime/common/engineContract.ts'
 import { authoringLlmConfiguration } from './authoringLlm.ts'
 import { authoringOpenApiSchema } from './authoringOpenApi.ts'
 
@@ -31,6 +34,7 @@ export const authoringTypes = [
   'llm',
   'decision',
   'openapi',
+  'http-request',
   'condition',
   'value',
   'wait',
@@ -69,7 +73,9 @@ 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 authoringCapabilities = z.array(
+  z.union([connectorCapabilitySchema, z.strictObject({ kind: z.literal('workflow'), name: id, flowId: id }), httpCapabilitySchema]),
+)
 const notification = z.strictObject({
   ...definitions.connector.shape,
   messageHandle: id,
@@ -111,6 +117,7 @@ export const authoringConfigurations = {
   'code': z.strictObject({ inputs: inputFields, outputs: outputFields, capabilities: authoringCapabilities.optional() }),
   'connector': definitions.connector.omit({ outputMode: true }).strict(),
   'openapi': authoringOpenApiSchema,
+  'http-request': httpRequestConfigSchema,
   'agent': definitions.agent
     .omit({ prompt: true, tools: true })
     .extend({
@@ -256,6 +263,9 @@ const requestContracts = {
   },
 }
 
+const codeBuiltins = [...findEngineContract(currentEngineContract)!.builtinModules!].filter((name) => !name.startsWith('node:'))
+const codeGuidance = `Code is an ES module whose default export receives (inputs, context) and returns the business outputs. It may import the Node builtins ${codeBuiltins.join(', ')}, with or without the node: prefix; fs is a fresh in-memory filesystem containing /tmp per execution. require, dynamic import, packages and the http/net builtins are unavailable. To call HTTP APIs, declare their hosts in config.capabilities as {kind: "http", hosts: ["api.example.com", "*.example.org"]} and use context.fetch(url, {method, headers, body}); it returns status, ok, headers.get(), text(), json() and bytes(), does not follow redirects, adds no credentials, and limits bodies to 1 MiB. Prefer an HTTP Request node for a single call without transformation and Connector Actions for services with accounts. context provides inputs, signal, getPrevious(), fetch, actions, workflows, artifact, flowId, runId and blockId. 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.`
+
 /** Transport-independent discovery of the same requests the service validates. */
 export function authoringRequestContract(name: string) {
   if (!Object.hasOwn(requestContracts, name)) return undefined
@@ -296,15 +306,17 @@ export function authoringSchema(kind?: AuthoringType) {
                       ? '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.',
+                        : kind == 'http-request'
+                          ? 'Configure method, query/headers modes and names, bodyFormat, authentication, responseFormat and statusPolicy. Bind url, query.<name>/header.<name> or whole query/headers objects, body and auth.token (Basic: auth.username/auth.password). Credentials accept variables or upstream outputs only. Outputs: body, statusCode, headers. Authentication is replaced as a complete choice.'
+                          : kind == 'openapi'
+                            ? 'Select an operation; the tool resolves its ports and authentication. Read authenticationChoices from node details. authentication is replaced as a complete choice. Bind advertised credentials through inputs.'
+                            : kind == 'workflow'
+                              ? 'Select another workflow with config.flowId. A workflow cannot call itself, including in a disconnected node. Owned unpublished or unavailable targets may be saved as incomplete drafts. Use node.refresh to load the current published interface.'
+                              : kind == 'agent'
+                                ? 'Tools accept Connector Actions or {kind: "workflow", flowId, name, description, approval, inputs}. Workflow parameter sources use model, input or value. The platform derives the interface. Refresh a workflow tool with node.refresh and tool: its name.'
+                                : kind == 'code'
+                                  ? codeGuidance
+                                  : 'Supply business configuration and input data. Fixed definitions are assembled by the tool. Existing constraints and defaults are preserved on partial updates.',
         example: {
           op: 'node.add',
           as: 'step',
@@ -312,15 +324,16 @@ export function authoringSchema(kind?: AuthoringType) {
           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: {
+              '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>' } },
+              'http-request': { config: {}, inputs: { url: { kind: 'value', value: 'https://example.com' } } },
+              '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: [
@@ -335,15 +348,15 @@ export function authoringSchema(kind?: AuthoringType) {
                   ],
                 },
               },
-              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: {
+              '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: {
+              'agent': {
                 config: {
                   model: 'deepseek-v4-flash',
                 },

package/src/control/common/authoringTools.ts

@@ -17,7 +17,7 @@ export type AuthoringCapability = Exclude<TaskCapability, WorkflowCapability> |
 export type WorkflowLookup = (flowId: string) => Promise<WorkflowContract | WorkflowCandidate>
 
 interface ToolIdentity {
-  readonly kind?: 'connector' | 'workflow'
+  readonly kind?: string
   readonly name?: string
   readonly flowId?: string
 }

package/src/control/common/conformance.ts

@@ -4,8 +4,8 @@ import type { ConnectorConnection, CreateEventSource, ResultInfo, PollTriggerTes
 import type { ProviderAccessIdentity } from './providerAccess.ts'
 
 import { dequal } from 'dequal/lite'
-import { currentEngineContract as engineContract } from '../../execution/common/engineContract.ts'
 import { upgradeRevisionContent } from '../../flow/common/change.ts'
+import { currentEngineContract as engineContract } from '../../runtime/common/engineContract.ts'
 import { ControlClient, decodeRunEvent } from './api.ts'
 import { allConnectorConnectionsQuery } from './connectorQueries.ts'
 

package/src/control/common/connectorDecoders.ts

@@ -14,10 +14,10 @@ import type {
   ProviderAccessBindingCandidate,
 } from './api.ts'
 
+import { providerIconAppearance } from '../../connector/common/providerIconSprite.ts'
 import { exact, requiredFields, integer, invalidResponse, jsonValue, record, string } from './decoding.ts'
 import { ApiError } from './errors.ts'
 import { parseProviderAccessSource } from './providerAccess.ts'
-import { providerIconAppearance } from './providerIconSprite.ts'
 
 export function leinaBots(value: unknown): readonly LeinaBot[] {
   const source = record(value)

package/src/control/common/eventSources.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import { eventSourceViewSchema } from '../../event-source/common/view.ts'
 
 const id = z.string().min(1).max(256)
 const eventType = z.string().regex(/^[a-z][a-z0-9_.:]{0,127}$/)
@@ -10,45 +11,17 @@ const eventSourceSchema = z.object({
   revision: z.int().positive(),
   name,
   provider: z.enum(['feishu', 'feishu_app_bot', 'slackbot', 'intercom', 'sentry', 'zoom', 'fireflies', 'jira']),
-  appId: id.nullable(),
-  workspaceId: id.optional(),
-  installationId: id.optional(),
-  organizationId: id.optional(),
-  projectId: id.optional(),
-  projectKey: id.optional(),
-  subscriptionStatus: z.enum(['idle', 'pending', 'ready', 'error']).optional(),
-  lastError: z.string().optional(),
-  signingSecretConfigured: z.boolean().optional(),
+  ...eventSourceViewSchema.shape,
   connectionId: id,
   teamId: id.nullable(),
   enabled: z.boolean(),
   eventTypes: z.array(eventType),
-  manageSubscriptions: z.boolean().nullable(),
-  verificationTokenConfigured: z.boolean().nullable(),
-  encryptKeyConfigured: z.boolean().nullable(),
   endpointUrl: z.string().nullable(),
-  verifiedAt: z.string().nullable(),
   lastReceivedAt: z.string().nullable(),
   updatedAt: z.string(),
   consumers: z.array(z.object({ flowId: id, flowName: z.string(), triggerNodeId: id })),
 })
 
-export const eventSourceViewSchema = eventSourceSchema.pick({
-  appId: true,
-  workspaceId: true,
-  installationId: true,
-  organizationId: true,
-  projectId: true,
-  projectKey: true,
-  subscriptionStatus: true,
-  lastError: true,
-  signingSecretConfigured: true,
-  manageSubscriptions: true,
-  verificationTokenConfigured: true,
-  encryptKeyConfigured: true,
-  verifiedAt: true,
-})
-
 export interface CreateFeishuEventSource {
   readonly kind?: 'feishu'
   readonly version: 1

package/src/control/common/triggerCatalog.ts

@@ -1,19 +1,12 @@
 import type { TriggerKeySnapshot } from '../../flow/common/change.ts'
 import type { UiLanguage } from '../../localization/common/languages.ts'
+import type { TriggerDisplay } from '../../trigger/providers/localization.ts'
 import type { TriggerKeySummary } from './api.ts'
 
 import { isUiLanguage } from '../../localization/common/languages.ts'
 import { exact, requiredFields, invalidResponse, record, string } from './decoding.ts'
 import { triggerKey } from './triggerDecoders.ts'
 
-export interface TriggerDisplay {
-  readonly configInputs: Readonly<Record<string, string>>
-  readonly configInputLabels: Readonly<Record<string, string>>
-  readonly displayName: string
-  readonly description: string
-  readonly outputs: Readonly<Record<string, string>>
-}
-
 export interface TriggerCatalog {
   readonly version: 3
   readonly locale: UiLanguage

package/src/decision/common/decision.ts

@@ -1,4 +1,4 @@
-import type { InputPort, JsonValue, ManagedTaskDefinition, Port } from '../../flow/common/change.ts'
+import type { InputPort, JsonValue, ManagedTaskDefinitionOf, Port, TaskExecutor } from '../../flow/common/model.ts'
 
 import { dequal } from 'dequal/lite'
 import { matchesSchema } from '../../flow/common/schema.ts'
@@ -18,6 +18,10 @@ export interface DecisionIssue {
   readonly message: string
 }
 
+function isDecisionExecutor(executor: TaskExecutor): executor is DecisionExecutor {
+  return executor.kind === 'decision'
+}
+
 export const decisionModel = 'typesafe/jev'
 export const decisionLimits = { choice: 255, score: 10 } as const
 
@@ -34,8 +38,8 @@ export function limitDecisionQuestions(questions: readonly DecisionQuestion[]):
 }
 
 /** Loading an oversized task also updates its previously generated output schemas. */
-export function limitDecisionTask(task: ManagedTaskDefinition): ManagedTaskDefinition {
-  if (task.executor.kind !== 'decision') return task
+export function limitDecisionTask<Task extends ManagedTaskDefinitionOf<TaskExecutor>>(task: Task): Task {
+  if (!isDecisionExecutor(task.executor)) return task
   const original = task.executor.questions
   const questions = limitDecisionQuestions(original)
   if (questions === original) return task
@@ -45,7 +49,8 @@ export function limitDecisionTask(task: ManagedTaskDefinition): ManagedTaskDefin
     if (index < 0 || original[index] === questions[index] || !dequal(port.jsonSchema, answerSchema(original[index]!))) return port
     return { ...port, jsonSchema: decisionAnswerSchema(questions[index]!) }
   })
-  return { ...task, executor: { ...task.executor, questions }, outputs }
+  // Only the decision executor and its derived outputs change, so the task keeps its own type.
+  return { ...task, executor: { ...task.executor, questions }, outputs } as Task
 }
 export const decisionStateSchema: JsonValue = { type: ['string', 'object', 'array'] }
 const probability: JsonValue = { type: 'number', minimum: 0, maximum: 1 }
@@ -102,7 +107,10 @@ function answerSchema(question: DecisionQuestion): JsonValue {
   return { type: 'object', properties, required: Object.keys(properties) }
 }
 
-export function decisionTask(questions: readonly DecisionQuestion[] = [defaultDecisionQuestion()], name = 'AI Decision'): ManagedTaskDefinition {
+export function decisionTask(
+  questions: readonly DecisionQuestion[] = [defaultDecisionQuestion()],
+  name = 'AI Decision',
+): ManagedTaskDefinitionOf<DecisionExecutor> {
   questions = limitDecisionQuestions(questions)
   const inputs: InputPort[] = [
     { handle: 'target', description: 'Text, object, or array to evaluate across all questions.', jsonSchema: decisionStateSchema, nullable: false },
@@ -111,9 +119,9 @@ export function decisionTask(questions: readonly DecisionQuestion[] = [defaultDe
   return { name, executor: { kind: 'decision', questions }, inputs, outputs }
 }
 
-export function decisionTaskIssues(task: ManagedTaskDefinition): readonly DecisionIssue[] {
+export function decisionTaskIssues(task: ManagedTaskDefinitionOf<TaskExecutor>): readonly DecisionIssue[] {
   task = limitDecisionTask(task)
-  if (task.executor.kind !== 'decision') return []
+  if (!isDecisionExecutor(task.executor)) return []
   const expected = decisionTask(task.executor.questions, task.name)
   return [
     ...decisionQuestionIssues(task.executor.questions),