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

package/src/execution/common/runtime.ts

@@ -0,0 +1,563 @@
+import type { CodeModule, ConnectorCapability, TaskCapability, JsonValue } from '../../flow/common/change.ts'
+
+import { dequal } from 'dequal/lite'
+import { currentEngineContract, nodejsEngineContract } from './engineContract.ts'
+
+export { currentEngineContract, nodejsEngineContract, findEngineContract, type EngineContract } from './engineContract.ts'
+
+export type RuntimeModule = Pick<CodeModule, 'imports' | 'source'>
+
+/** Snapshot a Task result before JSON transport can discard or coerce invalid values. */
+export function snapshotRuntimeResult(value: unknown): JsonValue | undefined {
+  // This function is also serialized into the isolated runtime; keep it self-contained.
+  const parents = new Set<object>()
+  const copy = (item: unknown, depth: number): JsonValue => {
+    if (depth > 64) throw new Error('Task result exceeds the maximum JSON depth.')
+    if (item === null || typeof item == 'string' || typeof item == 'boolean') return item
+    if (typeof item == 'number' && Number.isFinite(item)) return item
+    if (
+      typeof item != 'object' ||
+      parents.has(item) ||
+      (!Array.isArray(item) && Object.getPrototypeOf(item) !== Object.prototype && Object.getPrototypeOf(item) !== null) ||
+      Object.getOwnPropertySymbols(item).length > 0
+    )
+      throw new Error('Task result must contain only JSON values.')
+    parents.add(item)
+    const result = Array.isArray(item)
+      ? Array.from(item, (child) => copy(child, depth + 1))
+      : Object.fromEntries(
+          Object.entries(item)
+            .filter(([, child]) => depth != 0 || child !== undefined)
+            .map(([key, child]) => [key, copy(child, depth + 1)]),
+        )
+    parents.delete(item)
+    return result
+  }
+  return value === undefined ? undefined : copy(value, 0)
+}
+
+export const nodejsRuntimeConformanceCases: readonly RuntimeConformanceCase[] = [
+  {
+    name: 'supports Node builtin imports and asynchronous virtual file operations',
+    async verify(harness) {
+      const value = await harness.invoke({
+        capability: async () => ({ body: null, status: 403 }),
+        input: null,
+        invocationId: 'nodejs-files',
+        program: {
+          ...program(
+            harness,
+            `import assert from 'node:assert/strict';
+import { Buffer } from 'node:buffer'; import path from 'node:path'; import fs from 'node:fs/promises';
+export default async () => {
+  const file = path.join('/tmp', 'conformance.txt');
+  await fs.writeFile(file, Buffer.from('你好'));
+  const text = await fs.readFile(file, 'utf8');
+  assert.equal(text, '你好');
+  await fs.unlink(file);
+  return { text, bytes: Buffer.byteLength(text) };
+}`,
+          ),
+          engineContract: nodejsEngineContract,
+        },
+      })
+      equal(value, { text: '你好', bytes: 6 }, 'Node virtual files')
+    },
+  },
+  {
+    name: 'preserves abort reasons and cancels Promise timers',
+    async verify(harness) {
+      const value = await harness.invoke({
+        capability: async () => ({ body: null, status: 403 }),
+        input: null,
+        invocationId: 'nodejs-abort',
+        program: {
+          ...program(
+            harness,
+            `import { setTimeout } from 'node:timers/promises';
+export default async () => {
+  const controller = new AbortController(); const reason = { message: 'stop' };
+  const combined = AbortSignal.any([controller.signal]);
+  const pending = setTimeout(60000, 'late', { signal: combined });
+  controller.abort(reason); controller.abort('ignored');
+  let thrown; try { combined.throwIfAborted(); } catch (error) { thrown = error; }
+  try { await pending; return false; } catch (error) {
+    return { sameReason: combined.reason === reason && thrown === reason, name: error.name };
+  }
+}`,
+          ),
+          engineContract: nodejsEngineContract,
+        },
+      })
+      equal(value, { sameReason: true, name: 'AbortError' }, 'Node cancellation')
+    },
+  },
+]
+
+export interface RuntimeProgram {
+  readonly engineContract: string
+  readonly engineDigest: string
+  readonly entryModuleId: string
+  readonly modules: Readonly<Record<string, RuntimeModule>>
+}
+
+export interface RuntimeCapabilityCall {
+  readonly nodeId?: string
+  readonly jobId?: string
+  readonly callId: string
+  readonly invocationId: string
+  readonly kind: string
+  readonly payload: JsonValue
+  readonly signal: AbortSignal
+}
+
+export interface RuntimeCapabilityResponse {
+  readonly body: JsonValue
+  readonly status: number
+}
+
+export interface LlmTaskInvocation {
+  readonly input: Readonly<Record<string, JsonValue>>
+  readonly invocationId: string
+  readonly mode: 'chat' | 'json'
+  readonly signal: AbortSignal
+  readonly version: 1
+}
+
+export type LlmTaskResult =
+  | { readonly kind: 'completed'; readonly value: JsonValue; readonly version: 1 }
+  | {
+      readonly retryable?: boolean
+      readonly code: 'llm.output-invalid' | 'llm.unavailable'
+      readonly kind: 'failed'
+      readonly message: string
+      readonly version: 1
+    }
+
+export type InvokeLlmTask = (invocation: LlmTaskInvocation) => Promise<LlmTaskResult>
+
+export interface AgentCheckpoint {
+  readonly state: JsonValue
+  readonly callId: string
+  readonly toolId: string
+  readonly input: Readonly<Record<string, JsonValue>>
+  readonly rounds: number
+  readonly version: 1
+}
+
+export type AgentResult = { readonly kind: 'completed'; readonly output: JsonValue } | { readonly kind: 'suspended'; readonly checkpoint: AgentCheckpoint }
+
+export interface AgentInvocation {
+  readonly input: Readonly<Record<string, JsonValue>>
+  readonly invocationId: string
+  readonly signal: AbortSignal
+  readonly resume?: { readonly action: 'approve' | 'reject'; readonly checkpoint: AgentCheckpoint }
+}
+
+export interface RuntimeInvocation {
+  readonly capabilities?: readonly TaskCapability[]
+  readonly capability: (call: RuntimeCapabilityCall) => Promise<RuntimeCapabilityResponse>
+  readonly input: JsonValue
+  readonly invocationId: string
+  readonly program: RuntimeProgram
+  readonly signal?: AbortSignal
+}
+
+export interface RuntimeHarness {
+  readonly engineDigest: string
+  invoke(invocation: RuntimeInvocation): Promise<JsonValue | undefined>
+}
+
+export interface RuntimeConformanceCase {
+  readonly name: string
+  verify(harness: RuntimeHarness): Promise<void>
+}
+
+function program(harness: RuntimeHarness, source: string, modules: Readonly<Record<string, RuntimeModule>> = {}): RuntimeProgram {
+  return {
+    engineContract: currentEngineContract,
+    engineDigest: harness.engineDigest,
+    entryModuleId: 'main',
+    modules: {
+      ...modules,
+      main: { imports: Object.keys(modules), source },
+    },
+  }
+}
+
+function equal(actual: unknown, expected: unknown, message: string): void {
+  if (!dequal(actual, expected)) {
+    throw new Error(`${message}: expected ${JSON.stringify(expected)}, received ${JSON.stringify(actual)}.`)
+  }
+}
+
+async function rejects(operation: Promise<unknown>, pattern: RegExp, message: string): Promise<void> {
+  try {
+    await operation
+  } catch (error) {
+    if (pattern.test(error instanceof Error ? error.message : String(error))) return
+    throw new Error(`${message}: received ${error instanceof Error ? error.message : String(error)}.`, { cause: error })
+  }
+  throw new Error(`${message}: operation unexpectedly succeeded.`)
+}
+
+export const runtimeConformanceCases: readonly RuntimeConformanceCase[] = [
+  {
+    name: 'rejects Task results that JSON transport would discard or coerce',
+    async verify(harness) {
+      for (const expression of [
+        '{ value: () => 42 }',
+        '{ value: Symbol("value") }',
+        '{ value: NaN }',
+        '{ value: Infinity }',
+        '{ value: 1n }',
+        '{ value: { nested: undefined } }',
+        '{ value: [undefined] }',
+        '{ value: Array(1) }',
+        '{ value: new Date() }',
+        '{ value: { toJSON() { return "hidden" } } }',
+        '{ [Symbol("key")]: 1 }',
+        '(() => { const value = {}; value.self = value; return { value } })()',
+      ]) {
+        await rejects(
+          harness.invoke({
+            capability: async () => ({ body: null, status: 200 }),
+            input: null,
+            invocationId: 'invalid-task-result',
+            program: program(harness, `export default () => (${expression})`),
+          }),
+          /Task result must contain only JSON values/,
+          `Invalid Task result: ${expression}`,
+        )
+      }
+    },
+  },
+  {
+    name: 'snapshots JSON results while preserving missing ports and shared values',
+    async verify(harness) {
+      const value = await harness.invoke({
+        capability: async () => ({ body: null, status: 200 }),
+        input: null,
+        invocationId: 'json-task-result',
+        program: program(
+          harness,
+          `export default () => {
+            const shared = { text: 'hello', values: [1, true, null] };
+            return { missing: undefined, nullable: null, first: shared, second: shared };
+          }`,
+        ),
+      })
+      const shared = { text: 'hello', values: [1, true, null] }
+      equal(value, { nullable: null, first: shared, second: shared }, 'JSON Task result')
+    },
+  },
+  {
+    name: 'preserves Action error codes and fixed per-call Connection selection',
+    async verify(harness) {
+      const declarations: readonly ConnectorCapability[] = [
+        {
+          kind: 'connector',
+          action: 'example.echo',
+          connections: [{ connectionId: 'work', alias: 'office' }, { connectionId: 'home' }],
+        },
+      ]
+      const result = await harness.invoke({
+        capabilities: declarations,
+        capability: async ({ payload }) => {
+          const selected = resolveAction(declarations, payload)
+          if (selected.input.fail) throw Object.assign(new Error('Provider unavailable.'), { code: 'connector.unavailable' })
+          return { body: selected.connectionId ?? null, status: 200 }
+        },
+        input: null,
+        invocationId: 'action-accounts',
+        program: program(
+          harness,
+          `export default async (_, context) => {
+          const values = await Promise.all([
+            context.actions.example.echo({}, { connectionAlias: 'office' }),
+            context.actions['example.echo']({}, { connectionId: 'home' }),
+          ])
+          try { await context.actions.example.echo({ fail: true }, { connectionId: 'work' }) }
+          catch (error) { values.push(error.code) }
+          return values
+        }`,
+        ),
+      })
+      equal(result, ['work', 'home', 'connector.unavailable'], 'Action selection and recovery')
+    },
+  },
+  {
+    name: 'shares Action entries and assigns independent concurrent call identities',
+    async verify(harness) {
+      const calls: RuntimeCapabilityCall[] = []
+      const value = await harness.invoke({
+        capabilities: [{ kind: 'connector', action: 'example.echo', connections: [] }],
+        capability: async (call) => {
+          calls.push(call)
+          return { body: call.payload, status: 200 }
+        },
+        input: null,
+        invocationId: 'action-calls',
+        program: program(
+          harness,
+          `export default async (_input, context) => {
+          const call = context.actions.example.echo
+          return { same: call === context.actions['example.echo'], values: await Promise.all([call({ value: 1 }), call({ value: 2 }), call({ value: 3 })]) }
+        }`,
+        ),
+      })
+      equal(value, { same: true, values: [1, 2, 3].map((item) => ({ action: 'example.echo', input: { value: item } })) }, 'Action results')
+      equal(new Set(calls.map((call) => call.callId)).size, 3, 'Independent Action identities')
+      equal(
+        calls.map((call) => call.invocationId),
+        ['action-calls', 'action-calls', 'action-calls'],
+        'Task identity',
+      )
+    },
+  },
+
+  {
+    name: 'loads the fixed ESM closure and platform module',
+    async verify(harness) {
+      const value = await harness.invoke({
+        capability: async () => {
+          throw new Error('Capability must not be called.')
+        },
+        input: { value: 6 },
+        invocationId: 'module-closure',
+        program: program(
+          harness,
+          `import { double } from './helper.mjs'
+import { engineContract, identity } from 'open-flow:platform'
+export default (input) => ({ engineContract, value: identity(double(input.value)) })`,
+          { helper: { imports: [], source: 'export const double = (value) => value * 2' } },
+        ),
+      })
+      equal(value, { engineContract: currentEngineContract, value: 12 }, 'ESM closure result')
+    },
+  },
+  {
+    name: 'rejects modules outside the fixed closure',
+    async verify(harness) {
+      await rejects(
+        harness.invoke({
+          capability: async () => ({ body: null, status: 200 }),
+          input: null,
+          invocationId: 'closed-linker',
+          program: program(
+            harness,
+            `import fs from 'node:fs'
+export default () => fs.readFileSync('/etc/passwd', 'utf8')`,
+          ),
+        }),
+        /invalid|unsupported|cannot import|not part of/i,
+        'Closed linker',
+      )
+    },
+  },
+  {
+    name: 'copies asynchronous Capability requests and responses',
+    async verify(harness) {
+      const calls: RuntimeCapabilityCall[] = []
+      const value = await harness.invoke({
+        capability: async (call) => {
+          calls.push(call)
+          return { body: { accepted: true, echoed: call.payload }, status: 200 }
+        },
+        input: { issue: 42 },
+        invocationId: 'async-capability',
+        program: program(harness, `export default async (input, capability) => capability.artifact.put({ action: 'read', input })`),
+      })
+      equal(value, { body: { accepted: true, echoed: { action: 'read', input: { issue: 42 } } }, status: 200 }, 'Capability result')
+      equal(
+        calls.map(({ invocationId, kind, payload }) => ({ invocationId, kind, payload })),
+        [{ invocationId: 'async-capability', kind: 'artifact.put', payload: { action: 'read', input: { issue: 42 } } }],
+        'Capability request',
+      )
+    },
+  },
+  {
+    name: 'returns final outputs without exposing intermediate output capability',
+    async verify(harness) {
+      const value = await harness.invoke({
+        capability: async () => {
+          throw new Error('Capability must not be called.')
+        },
+        input: null,
+        invocationId: 'final-outputs',
+        program: program(
+          harness,
+          `export default async (_input, context) => ({ available: typeof context.outputs, previous: await context.getPrevious(), value: 1 })`,
+        ),
+      })
+      equal(value, { available: 'undefined', previous: [], value: 1 }, 'Final Task outputs')
+    },
+  },
+  {
+    name: 'cancels a pending Capability and the user invocation',
+    async verify(harness) {
+      const cancellation = new AbortController()
+      let capabilityAborted = false
+      let capabilityStarted!: () => void
+      const started = new Promise<void>((resolve) => {
+        capabilityStarted = resolve
+      })
+      const invoked = harness.invoke({
+        capabilities: [{ kind: 'connector', action: 'example.wait', connections: [] }],
+        capability: async ({ signal }) => {
+          capabilityStarted()
+          return await new Promise<RuntimeCapabilityResponse>((_resolve, reject) =>
+            signal.addEventListener(
+              'abort',
+              () => {
+                capabilityAborted = true
+                reject(signal.reason)
+              },
+              { once: true },
+            ),
+          )
+        },
+        input: null,
+        invocationId: 'canceled-capability',
+        program: program(harness, `export default async (_input, context) => context.actions.example.wait({})`),
+        signal: cancellation.signal,
+      })
+      await started
+      cancellation.abort(new Error('Invocation canceled.'))
+      await rejects(invoked, /cancel|abort|disposed/i, 'Canceled invocation')
+      equal(capabilityAborted, true, 'Capability cancellation')
+    },
+  },
+]
+
+export function createActions(invoke: (payload: JsonValue) => Promise<RuntimeCapabilityResponse>): Readonly<Record<string, unknown>> {
+  // Keep validation inside the function serialized into the isolated runtime.
+  // eslint-disable-next-line unicorn/consistent-function-scoping
+  const json = (value: unknown, parents: Set<object>): void => {
+    if (value === null || typeof value == 'string' || typeof value == 'boolean' || (typeof value == 'number' && Number.isFinite(value))) return
+    if (
+      typeof value != 'object' ||
+      parents.has(value) ||
+      (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) ||
+      Object.getOwnPropertySymbols(value).length > 0
+    )
+      throw Object.assign(new Error('Action parameters must contain only JSON values.'), { code: 'capability.invalid' })
+    parents.add(value)
+    for (const child of Array.isArray(value) ? value : Object.values(value)) json(child, parents)
+    parents.delete(value)
+  }
+  const target: Record<string, unknown> = Object.create(null)
+  const calls = new Map<string, (input?: JsonValue, options?: JsonValue) => Promise<JsonValue>>()
+  const providers = new Map<string, Readonly<Record<string, unknown>>>()
+  const actionCall = (action: string): ((input?: JsonValue, options?: JsonValue) => Promise<JsonValue>) => {
+    let call = calls.get(action)
+    if (call != null) return call
+    call = async (input: JsonValue = {}, options?: JsonValue): Promise<JsonValue> => {
+      json(input, new Set())
+      if (options !== undefined) json(options, new Set())
+      const response = await invoke({ action, input, ...(options === undefined ? {} : { options }) })
+      return response.body
+    }
+    calls.set(action, call)
+    return call
+  }
+  target.call = async (action: JsonValue, input: JsonValue = {}, options?: JsonValue): Promise<JsonValue> => {
+    if (typeof action != 'string') throw Object.assign(new Error('Action ID must be a string.'), { code: 'capability.invalid' })
+    return actionCall(action)(input, options)
+  }
+  Object.freeze(target)
+  return new Proxy(target, {
+    get(object, property) {
+      if (typeof property != 'string') return Reflect.get(object, property)
+      if (Object.hasOwn(object, property)) return object[property]
+      if (property.includes('.')) return actionCall(property)
+      let methods = providers.get(property)
+      if (methods == null) {
+        const provider = property
+        const providerTarget = Object.freeze(Object.create(null) as Record<string, unknown>)
+        methods = new Proxy(providerTarget, {
+          get(_object, name) {
+            return typeof name == 'string' ? actionCall(`${provider}.${name}`) : undefined
+          },
+        })
+        providers.set(property, methods)
+      }
+      return methods
+    },
+  })
+}
+
+export function resolveAction(
+  declarations: readonly ConnectorCapability[],
+  payload: unknown,
+): { readonly action: string; readonly connectionId?: string; readonly input: Readonly<Record<string, JsonValue>> } {
+  const invalid = Object.assign(new Error('The Action request is invalid.'), { code: 'capability.invalid' })
+  const denied = Object.assign(new Error('The Action or Connection is unavailable for this Code node.'), { code: 'capability.denied' })
+  if (payload == null || typeof payload != 'object' || Array.isArray(payload)) throw invalid
+  const source = payload as Record<string, JsonValue>
+  if (
+    Object.keys(source).some((key) => !['action', 'input', 'options'].includes(key)) ||
+    typeof source.action != 'string' ||
+    !/^[A-Za-z0-9_-]+\.[A-Za-z0-9_.-]+$/.test(source.action) ||
+    source.input == null ||
+    typeof source.input != 'object' ||
+    Array.isArray(source.input)
+  )
+    throw invalid
+  const permissions = declarations.find((declaration) => 'mode' in declaration)
+  const allowed = permissions?.mode == 'independent' ? permissions.actions.find((entry) => entry.action == source.action) : undefined
+  if (permissions?.mode == 'independent' && allowed == null) throw denied
+  const hints = declarations.flatMap((declaration) => {
+    if ('mode' in declaration) return []
+    if ('action' in declaration) {
+      if (declaration.action != source.action) return []
+      return [
+        ...declaration.connections.flatMap((connection) =>
+          connection.alias == null ? [] : [{ action: declaration.action, connectionId: connection.connectionId, alias: connection.alias }],
+        ),
+        ...(declaration.connectionId == null ? [] : [{ action: declaration.action, connectionId: declaration.connectionId }]),
+      ]
+    }
+    return declaration.connectionHints?.filter((hint) => hint.action == source.action) ?? []
+  })
+  let connectionId = hints.find((hint) => hint.alias == null)?.connectionId
+  if (Object.hasOwn(source, 'options')) {
+    if (source.options == null || typeof source.options != 'object' || Array.isArray(source.options)) throw invalid
+    const options = source.options as Record<string, JsonValue>
+    const keys = Object.keys(options)
+    if (keys.length != 1) throw invalid
+    if (typeof options.connectionId == 'string' && options.connectionId.length > 0 && keys[0] == 'connectionId') {
+      connectionId = options.connectionId
+    } else if (typeof options.connectionAlias == 'string' && options.connectionAlias.length > 0 && keys[0] == 'connectionAlias') {
+      connectionId = hints.find((item) => item.alias == options.connectionAlias)?.connectionId
+      if (connectionId == null) throw denied
+    } else throw invalid
+  }
+  if (permissions?.mode == 'independent') {
+    if (connectionId != null && connectionId != allowed?.connectionId) throw denied
+    connectionId = allowed?.connectionId
+  }
+  if (permissions?.mode == 'shared' && Object.hasOwn(source, 'options') && connectionId == null) throw denied
+  return { action: source.action, input: source.input as Readonly<Record<string, JsonValue>>, ...(connectionId == null ? {} : { connectionId }) }
+}
+
+export interface DecisionTaskInvocation {
+  readonly questions: readonly import('../../decision/common/decision.ts').DecisionQuestion[]
+  readonly state: JsonValue
+  readonly invocationId: string
+  readonly signal: AbortSignal
+  readonly version: 1
+}
+export type InvokeDecisionTask = (invocation: DecisionTaskInvocation) => Promise<LlmTaskResult>
+
+/** Serialized into the sandbox alongside the strict JSON snapshot helper. */
+export function createWorkflows(invoke: (payload: JsonValue) => Promise<RuntimeCapabilityResponse>) {
+  return Object.freeze({
+    async call(name: string, input: Readonly<Record<string, JsonValue>> = {}): Promise<JsonValue> {
+      if (typeof name != 'string' || input == null || typeof input != 'object' || Array.isArray(input))
+        throw Object.assign(new Error('Workflow name and input object are required.'), { code: 'capability.invalid' })
+      const value = snapshotRuntimeResult(input)!
+      return (await invoke({ name, input: value })).body
+    },
+  })
+}