ai-ctrl-workflow-logic 0.1.10 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-ctrl-workflow-logic",
-  "version": "0.1.10",
+  "version": "0.2.1",
   "private": false,
   "description": "WorkCtrlFlow-backed AI Ctrl Workflow adapter logic",
   "type": "module",
@@ -8,19 +8,21 @@
   "exports": {
     ".": "./src/index.ts",
     "./browser": "./src/browser.ts",
-    "./filesystem": "./src/filesystem.ts"
+    "./filesystem": "./src/filesystem.ts",
+    "./sources": "./src/source-loader.ts"
   },
   "dependencies": {
-    "ai-ctrl-workflow-contract": "0.1.6",
-    "ai-workflow-contract": "0.1.9",
-    "ai-workflow-logic": "0.1.11",
-    "flow-step-space-logic": "0.1.1",
-    "instant-ctrl-flow-contract": "0.1.2",
-    "instant-ctrl-flow-logic": "0.1.5",
-    "task-manager-contract": "0.1.3",
-    "task-manager-logic": "0.1.6",
-    "work-ctrl-flow-contract": "0.1.3",
-    "work-ctrl-flow-logic": "0.1.4"
+    "depa-behavior-tree": "0.1.2",
+    "ai-ctrl-workflow-contract": "0.2.1",
+    "ai-workflow-contract": "0.2.2",
+    "ai-workflow-logic": "0.2.2",
+    "flow-step-space-logic": "0.1.2",
+    "instant-ctrl-flow-contract": "0.1.3",
+    "instant-ctrl-flow-logic": "0.1.7",
+    "task-manager-contract": "0.1.4",
+    "task-manager-logic": "0.1.7",
+    "work-ctrl-flow-contract": "0.1.4",
+    "work-ctrl-flow-logic": "0.1.6"
   },
   "files": [
     "src"

package/src/delegation.ts

@@ -0,0 +1,55 @@
+import { BehaviorResult, type ActionHandler, type CtrlFlowNodeType, type INodeConfig } from 'depa-behavior-tree';
+import { createFlowHandlers, flowStateOf } from 'instant-ctrl-flow-logic';
+import { WaitNodeHandler, type TickController, type WorkCtrlFlowEngineOptions } from 'work-ctrl-flow-logic';
+import type { FlowBundleSpec, FlowCodeResolver } from 'instant-ctrl-flow-contract';
+import { WorkflowDelegationSuspendedError } from 'ai-workflow-logic';
+
+/** Uses the existing scheduler, native WaitHandles and resume token history. */
+export function createAICtrlWorkflowDelegationHandlers(
+  spec: FlowBundleSpec,
+  resolveCode: FlowCodeResolver,
+  bindNodeRuntime: WorkCtrlFlowEngineOptions['bindNodeRuntime'],
+  controller: () => TickController,
+): Record<string, ActionHandler<CtrlFlowNodeType, INodeConfig>> {
+  const handlers = createFlowHandlers(spec, resolveCode, {
+    begin: () => { throw Error('Delegation Run handler does not own branch decisions'); },
+    record: () => { throw Error('Delegation Run handler does not own branch decisions'); },
+    runtimeForNode: (nodeId, runtime, state) => bindNodeRuntime?.(runtime, controller().runtimeIdentity(nodeId, state)) ?? runtime,
+  });
+  return { 'flow.Run': { async execute(ctx) {
+    const c = controller();
+    if (c.suspended.length) { c.inertKeys.add(ctx.node.Key); return BehaviorResult.Failure; }
+    const key = c.invocationKeyFor(ctx.node.Key);
+    const recorded = c.snapshot.nodeResults[key];
+    if (recorded) {
+      if (bindNodeRuntime) c.invocationKeyFor(ctx.node.Key);
+      return recorded === 'Success' ? BehaviorResult.Success : BehaviorResult.Failure;
+    }
+    const result = await handlers['flow.Run']!.execute(ctx);
+    const flow = flowStateOf(ctx);
+    if (!(flow.fault instanceof WorkflowDelegationSuspendedError)) {
+      if (result !== BehaviorResult.Running) c.snapshot.nodeResults[key] = result === BehaviorResult.Success ? 'Success' : 'Failure';
+      for (const handle of [...c.snapshot.openWaitHandles]) {
+        if (!handle.nodeKey.startsWith(`${ctx.node.Key}:delegation:`) || handle.signalKey !== key) continue;
+        handle.status = 'Consumed'; handle.closedAtMs = c.now();
+        c.snapshot.appliedResumeSignals.push(`${handle.waitHandleId}:${handle.resumeToken}`);
+        c.snapshot.waitResults[handle.invocationKey] = { result: result === BehaviorResult.Success ? 'Success' : 'Failure' };
+        c.snapshot.openWaitHandles = c.snapshot.openWaitHandles.filter(item => item !== handle);
+        c.snapshot.closedWaitHandles.push(handle);
+      }
+      return result;
+    }
+    const delegationInvocationKey = flow.fault.invocationKey;
+    const status = flow.fault.status;
+    delete flow.fault;
+    // Signal payload is only a wakeup; task output always comes from owner observation.
+    const prefix = `${ctx.node.Key}:delegation:`;
+    const scope=key.slice(0,key.lastIndexOf('/')+1);
+    const count = c.snapshot.closedWaitHandles.filter(handle => handle.nodeKey.startsWith(prefix) && handle.invocationKey.startsWith(`${scope}${prefix}`)).length;
+    const proxy = Object.create(ctx);
+    Object.defineProperty(proxy, 'node', { value: { ...ctx.node, Key: `${prefix}${count}`, Config: { signalKind: 'workflow.delegation.observe', signalKey: key } } });
+    return new WaitNodeHandler('external-job', controller, async (_ctx, handle) => {
+      handle.metadata = { workflowDelegation: { kind: 'workflow.task-delegation/v1', invocationKey: delegationInvocationKey, actionInvocationKey: key, status } };
+    }).execute(proxy);
+  } } };
+}

package/src/filesystem.ts

@@ -21,6 +21,8 @@ import {
 } from 'ai-workflow-logic';
 import { createFilesystemFlowCodeResolver, type FlowModuleImporter } from 'instant-ctrl-flow-logic/filesystem';
 import type { FlowNodeSpec } from 'instant-ctrl-flow-contract';
+import { projectWorkCtrlFlowInvocationOwners } from 'work-ctrl-flow-logic';
+import { assertFrozenAIAgentTaskBinding } from 'ai-workflow-logic/run-freeze';
 import {
   assembleDefinitionStepProfileDirectory,
   createFilesystemDefinitionStepProfileRuntime,
@@ -135,24 +137,29 @@ export function createMaterializedAICtrlWorkflowControllerFromDirectory(
     agentTaskProofs: _agentTaskProofs,
     ...controllerOptions
   } = options;
+  const bindAgentNode=options.agentEffects?createAICtrlWorkflowAgentNodeRuntimeBinder({
+    flowInstanceId:options.instanceId,
+    checkpointRuntime:{checkpointStore},
+    effects:options.agentEffects,
+    workflowRef:`resource://${binding.definition.fqn}`,
+    taskProofs:options.agentTaskProofs??{},
+  }):undefined;
   const controller = createAICtrlWorkflowController({
     ...controllerOptions,
     binding,
     store,
     resolveCode: createFilesystemFlowCodeResolver(options.importModule),
-    ...(options.agentEffects ? {
-      bindNodeRuntime: createAICtrlWorkflowAgentNodeRuntimeBinder({
-        flowInstanceId: options.instanceId,
-        checkpointRuntime: { checkpointStore },
-        effects: options.agentEffects,
-        workflowRef: `resource://${binding.definition.fqn}`,
-        taskProofs: options.agentTaskProofs ?? {},
-      }),
+    suspendDelegations: options.agentEffects?.delegation !== undefined,
+    ...(bindAgentNode ? {
+      // Pure branch/loop predicates have no Agent task. Keep the Agent binder
+      // exact for the nodes whose frozen proof actually grants that facade.
+      bindNodeRuntime:(runtime,identity)=>options.agentTaskProofs?.[identity.nodeId]?bindAgentNode(runtime,identity):runtime,
     } : {}),
   });
   const materializedController: AICtrlWorkflowController = {
     ...controller,
     async start(treeId, startOptions) {
+      for (const proof of Object.values(options.agentTaskProofs ?? {})) assertFrozenAIAgentTaskBinding(proof);
       const existing = await controller.store.load(treeId);
       if (existing) {
         if (startOptions?.input !== undefined
@@ -165,6 +172,10 @@ export function createMaterializedAICtrlWorkflowControllerFromDirectory(
       }
       return controller.start(treeId, startOptions);
     },
+    async resume(treeId, signal) {
+      for (const proof of Object.values(options.agentTaskProofs ?? {})) assertFrozenAIAgentTaskBinding(proof);
+      return controller.resume(treeId, signal);
+    },
   };
   return Object.assign(materializedController, {
     checkpointStore,
@@ -211,6 +222,7 @@ function profileAuthorityFromBinding(
   return Object.freeze({
     profileKind: 'AICtrlWorkflow' as const,
     definitionStepIds: Object.freeze([...definitionStepIds]),
+    definitionInvocationOwners: projectWorkCtrlFlowInvocationOwners(binding.definition),
     extensionsByStepId: Object.freeze(Object.fromEntries((forest?.stepOrder ?? []).flatMap((stepId) => {
       const extensions = Object.fromEntries(Object.entries(forest!.steps[stepId].extensions).map(([kind, extension]) => [kind, Object.freeze({
         ...(extension.schemaRef === undefined ? {} : { schemaRef: extension.schemaRef }),

package/src/index.ts

@@ -1,3 +1,5 @@
+import { createAICtrlWorkflowDelegationHandlers } from './delegation.js';
+export { createAICtrlWorkflowDelegationHandlers } from './delegation.js';
 import type {
   AICtrlWorkflowController,
   AICtrlWorkflowNodeRecord,
@@ -8,6 +10,7 @@ import type {
   AICtrlWorkflowRunProfileState,
   AICtrlWorkflowRuntime,
   AIAgentHostEffectPort,
+  AIAgentProcessorRuntime,
   FrozenAIAgentTaskBinding,
   AIWorkflowAuthoredEffects,
   AIWorkflowEffectProvider,
@@ -25,10 +28,11 @@ import type {
 import {
   commitFlowRunCheckpoint,
   createAIWorkflowRuntimeContext,
-  defineAICtrlWorkflow,
   loadFlowRunCheckpoint,
   projectWorkCtrlSnapshotToCheckpointData,
   bindAIAgentProcessors,
+  bindWorkflowNodeTasks,
+  bindWorkflowTaskDelegation,
 } from 'ai-workflow-logic';
 import { assertFrozenAIAgentTaskBinding } from 'ai-workflow-logic/run-freeze';
 import type {
@@ -37,7 +41,6 @@ import type {
   FlowSourceCollection,
   LoadFlowSourcesOptions,
 } from 'instant-ctrl-flow-contract';
-import { loadCtrlFlowProfileFromSources } from 'instant-ctrl-flow-logic';
 import type {
   ResumeSignal,
   TickOutcome,
@@ -184,23 +187,39 @@ export function createAICtrlWorkflowAgentNodeRuntimeBinder(
     const proof = options.taskProofs[identity.nodeId];
     if (!proof) throw new Error(`AI_AGENT_TASK_PROOF_REQUIRED: no frozen proof for node ${identity.nodeId}.`);
     const taskBinding = assertFrozenAIAgentTaskBinding(proof).task;
-    const effects: AIWorkflowAuthoredEffects = bindAIAgentProcessors({
+    const visit = identity.invocationKey.slice(identity.invocationKey.lastIndexOf('#') + 1);
+    const scope = identity.invocationKey.includes('/') ? identity.invocationKey.slice(0, identity.invocationKey.lastIndexOf('/')) : '';
+    const agentRuntime = {
       checkpointRuntime: options.checkpointRuntime,
       checkpointKey: { instanceId: options.flowInstanceId, runId: identity.treeId },
       nodeId: identity.nodeId,
       invocationKey: identity.invocationKey,
+      nodeContext:{generation:identity.generation??Number(visit),scope},
       workflowKind: 'AICtrlWorkflow',
       workflowRef: options.workflowRef,
       taskBinding,
       effects: options.effects,
       ...(options.metadata === undefined ? {} : { metadata: options.metadata }),
-    });
-    return Object.freeze({ ...runtime, ai: Object.freeze({ ...workflowRuntime.ai, effects }) });
+    } satisfies AIAgentProcessorRuntime;
+    const effects: AIWorkflowAuthoredEffects = bindAIAgentProcessors(agentRuntime);
+    const delegation=options.effects.delegation ? bindWorkflowTaskDelegation({
+        checkpointRuntime: options.checkpointRuntime,
+        checkpointKey: { instanceId: options.flowInstanceId, runId: identity.treeId },
+        nodeId: identity.nodeId, invocationKey: identity.invocationKey,
+        workflowKind: 'AICtrlWorkflow', workflowRef: options.workflowRef, taskBinding,
+        visit: identity.visit ?? `${scope}#${visit}`, generation: identity.generation ?? Number(visit), effects: options.effects.delegation,
+      }) : undefined;
+    return Object.freeze({ ...runtime, ai: Object.freeze({ ...workflowRuntime.ai, effects,
+      tasks:bindWorkflowNodeTasks(agentRuntime,delegation),
+      ...(delegation?{delegation}:{}),
+    }) });
   };
 }
 
 export interface CreateAICtrlWorkflowControllerOptions
   extends Omit<WorkCtrlFlowEngineOptions, 'definition' | 'runtime' | 'expectedForm'> {
+  /** Set by composition when a native delegation owner is bound. */
+  readonly suspendDelegations?: boolean;
   readonly binding: AICtrlWorkflowDefinitionBinding;
   readonly resolveCode: FlowCodeResolver<AICtrlWorkflowRuntime>;
   readonly resolveFlow?: WorkCtrlFlowDefinition['resolveFlow'];
@@ -218,6 +237,10 @@ export function createAICtrlWorkflowController(
   };
   const engine = new WorkCtrlFlowEngine({
     ...options,
+    ...(options.suspendDelegations ? { extraHandlers: controller => ({
+      ...createAICtrlWorkflowDelegationHandlers(options.binding.definition, options.resolveCode as FlowCodeResolver, options.bindNodeRuntime, controller),
+      ...options.extraHandlers?.(controller),
+    }) } : {}),
     expectedForm: 'WorkCtrlFlow',
     definition,
     runtime: createAICtrlWorkflowRuntime({ runtime: options.runtime, ai: options.ai }),
@@ -231,34 +254,7 @@ export function createAICtrlWorkflowController(
   };
 }
 
-export function defineWorkCtrlFlowBackedAICtrlWorkflow(
-  definition: AICtrlWorkflowDefinitionBinding['definition'],
-): AICtrlWorkflowDefinitionBinding {
-  return defineAICtrlWorkflow(definition);
-}
-
-export interface AICtrlWorkflowSourceLoadResult {
-  readonly binding?: AICtrlWorkflowDefinitionBinding;
-  readonly diagnostics: readonly FlowDiagnostic[];
-}
-
-export function loadAICtrlWorkflowSources(
-  sources: FlowSourceCollection,
-  options: LoadFlowSourcesOptions = {},
-): AICtrlWorkflowSourceLoadResult {
-  const loaded = loadCtrlFlowProfileFromSources(sources, {
-    ...options,
-    profileRoot: 'AICtrlWorkflow',
-    substrateForm: 'WorkCtrlFlow',
-  });
-  if (!loaded.spec || loaded.diagnostics.length > 0) {
-    return { diagnostics: loaded.diagnostics };
-  }
-  return {
-    binding: defineWorkCtrlFlowBackedAICtrlWorkflow(loaded.spec),
-    diagnostics: loaded.diagnostics,
-  };
-}
+export * from './source-loader.js';
 
 function nodeIdFromInvocationKey(invocationKey: string): string {
   const withoutVisit = invocationKey.slice(0, invocationKey.lastIndexOf('#'));

package/src/source-loader.ts

@@ -0,0 +1,37 @@
+import type { AICtrlWorkflowDefinitionBinding } from "ai-workflow-contract";
+import { defineAICtrlWorkflow } from "ai-workflow-logic/definitions";
+import type {
+  FlowDiagnostic,
+  FlowSourceCollection,
+  LoadFlowSourcesOptions,
+} from "instant-ctrl-flow-contract";
+import { loadCtrlFlowProfileFromSources } from "instant-ctrl-flow-logic/browser";
+
+export function defineWorkCtrlFlowBackedAICtrlWorkflow(
+  definition: AICtrlWorkflowDefinitionBinding["definition"],
+): AICtrlWorkflowDefinitionBinding {
+  return defineAICtrlWorkflow(definition);
+}
+
+export interface AICtrlWorkflowSourceLoadResult {
+  readonly binding?: AICtrlWorkflowDefinitionBinding;
+  readonly diagnostics: readonly FlowDiagnostic[];
+}
+
+export function loadAICtrlWorkflowSources(
+  sources: FlowSourceCollection,
+  options: LoadFlowSourcesOptions = {},
+): AICtrlWorkflowSourceLoadResult {
+  const loaded = loadCtrlFlowProfileFromSources(sources, {
+    ...options,
+    profileRoot: "AICtrlWorkflow",
+    substrateForm: "WorkCtrlFlow",
+  });
+  if (!loaded.spec || loaded.diagnostics.length > 0) {
+    return { diagnostics: loaded.diagnostics };
+  }
+  return {
+    binding: defineWorkCtrlFlowBackedAICtrlWorkflow(loaded.spec),
+    diagnostics: loaded.diagnostics,
+  };
+}