@codemation/core 0.0.16 → 0.0.19

package/src/authoring/defineCredential.types.ts

@@ -0,0 +1,172 @@
+import type {
+  AnyCredentialType,
+  CredentialFieldSchema,
+  CredentialHealth,
+  CredentialJsonRecord,
+  CredentialSessionFactoryArgs,
+  CredentialType,
+  CredentialTypeDefinition,
+} from "../contracts/credentialTypes";
+import { z } from "zod";
+
+type MaybePromise<TValue> = TValue | Promise<TValue>;
+
+type CredentialFieldInput = CredentialFieldSchema["type"] | Readonly<Omit<CredentialFieldSchema, "key">>;
+
+type CredentialFieldMap<TConfig extends CredentialJsonRecord> = Readonly<
+  Record<keyof TConfig & string, CredentialFieldInput>
+>;
+
+type ZodObjectSchema<TConfig extends CredentialJsonRecord = CredentialJsonRecord> = z.ZodType<TConfig>;
+
+type InferCredentialConfig<TSource> =
+  TSource extends z.ZodType<infer TConfig, any, any>
+    ? Readonly<TConfig> & CredentialJsonRecord
+    : TSource extends CredentialFieldMap<infer TConfig>
+      ? TConfig
+      : CredentialJsonRecord;
+
+export interface DefineCredentialOptions<
+  TPublicSource extends CredentialFieldMap<any> | ZodObjectSchema<any>,
+  TSecretSource extends CredentialFieldMap<any> | ZodObjectSchema<any>,
+  TSession,
+> {
+  readonly key: string;
+  readonly label: string;
+  readonly description?: string;
+  readonly public: TPublicSource;
+  readonly secret: TSecretSource;
+  readonly supportedSourceKinds?: CredentialTypeDefinition["supportedSourceKinds"];
+  readonly auth?: CredentialTypeDefinition["auth"];
+  createSession(
+    args: CredentialSessionFactoryArgs<InferCredentialConfig<TPublicSource>, InferCredentialConfig<TSecretSource>>,
+  ): MaybePromise<TSession>;
+  test(
+    args: CredentialSessionFactoryArgs<InferCredentialConfig<TPublicSource>, InferCredentialConfig<TSecretSource>>,
+  ): MaybePromise<CredentialHealth>;
+}
+
+export class CredentialFieldSchemaFactory {
+  static create<TConfig extends CredentialJsonRecord>(
+    source: CredentialFieldMap<TConfig> | ZodObjectSchema<TConfig>,
+  ): ReadonlyArray<CredentialFieldSchema> {
+    if (source instanceof z.ZodObject) {
+      return this.createFromZodObject(source);
+    }
+    return this.createFromMap(source as CredentialFieldMap<TConfig>);
+  }
+
+  private static createFromMap<TConfig extends CredentialJsonRecord>(
+    source: CredentialFieldMap<TConfig>,
+  ): ReadonlyArray<CredentialFieldSchema> {
+    return Object.entries(source).map(([key, input], index) => {
+      if (typeof input === "string") {
+        return {
+          key,
+          label: this.humanize(key),
+          order: index,
+          type: input as CredentialFieldSchema["type"],
+        };
+      }
+      return {
+        key,
+        order: index,
+        ...(input as Readonly<Omit<CredentialFieldSchema, "key">>),
+      };
+    });
+  }
+
+  private static createFromZodObject<_TConfig extends CredentialJsonRecord>(
+    source: z.ZodObject,
+  ): ReadonlyArray<CredentialFieldSchema> {
+    const shape = source.shape;
+    return Object.entries(shape).map(([key, schema], index) => {
+      const resolved = this.unwrap(schema);
+      return {
+        key,
+        label: this.humanize(key),
+        order: index,
+        required: this.isRequired(schema) ? true : undefined,
+        type: this.resolveType(resolved),
+      };
+    });
+  }
+
+  private static isRequired(schema: z.ZodTypeAny): boolean {
+    return !(schema instanceof z.ZodOptional || schema instanceof z.ZodDefault);
+  }
+
+  private static unwrap(schema: z.ZodTypeAny): z.ZodTypeAny {
+    let current: z.ZodTypeAny = schema;
+    while (current instanceof z.ZodOptional || current instanceof z.ZodDefault) {
+      current = current.unwrap() as z.ZodTypeAny;
+    }
+    return current;
+  }
+
+  private static resolveType(schema: z.ZodTypeAny): CredentialFieldSchema["type"] {
+    if (schema instanceof z.ZodBoolean) {
+      return "boolean";
+    }
+    if (schema instanceof z.ZodString) {
+      return "string";
+    }
+    return "json";
+  }
+
+  private static humanize(key: string): string {
+    return key
+      .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+      .replace(/[-_.]+/g, " ")
+      .replace(/\s+/g, " ")
+      .trim()
+      .replace(/^./, (character) => character.toUpperCase());
+  }
+}
+
+export function defineCredential<
+  TPublicSource extends CredentialFieldMap<any> | ZodObjectSchema<any>,
+  TSecretSource extends CredentialFieldMap<any> | ZodObjectSchema<any>,
+  TSession,
+>(
+  options: DefineCredentialOptions<TPublicSource, TSecretSource, TSession>,
+): CredentialType<InferCredentialConfig<TPublicSource>, InferCredentialConfig<TSecretSource>, TSession> & {
+  readonly key: string;
+} {
+  const definition: CredentialTypeDefinition = {
+    typeId: options.key,
+    displayName: options.label,
+    description: options.description,
+    publicFields: CredentialFieldSchemaFactory.create(options.public),
+    secretFields: CredentialFieldSchemaFactory.create(options.secret),
+    supportedSourceKinds: options.supportedSourceKinds ?? ["db", "env", "code"],
+    auth: options.auth,
+  };
+
+  const credentialType: AnyCredentialType = {
+    definition,
+    async createSession(args) {
+      return await options.createSession(
+        args as CredentialSessionFactoryArgs<
+          InferCredentialConfig<TPublicSource>,
+          InferCredentialConfig<TSecretSource>
+        >,
+      );
+    },
+    async test(args) {
+      return await options.test(
+        args as CredentialSessionFactoryArgs<
+          InferCredentialConfig<TPublicSource>,
+          InferCredentialConfig<TSecretSource>
+        >,
+      );
+    },
+  };
+
+  return {
+    ...credentialType,
+    key: options.key,
+  } as CredentialType<InferCredentialConfig<TPublicSource>, InferCredentialConfig<TSecretSource>, TSession> & {
+    readonly key: string;
+  };
+}

package/src/authoring/defineNode.types.ts

@@ -0,0 +1,227 @@
+import type {
+  AnyCredentialType,
+  CredentialJsonRecord,
+  CredentialRequirement,
+  CredentialTypeId,
+} from "../contracts/credentialTypes";
+import type { Node, NodeExecutionContext } from "../contracts/runtimeTypes";
+import type { Items, NodeOutputs, RunnableNodeConfig } from "../contracts/workflowTypes";
+import type { TypeToken } from "../di";
+import { node as persistedNode } from "../runtime-types/runtimeTypeDecorators.types";
+import { z } from "zod";
+import { DefinedNodeRegistry } from "./DefinedNodeRegistry";
+
+type MaybePromise<TValue> = TValue | Promise<TValue>;
+
+type ResolvableCredentialType = AnyCredentialType | CredentialTypeId;
+
+type SessionForCredentialType<TCredential extends ResolvableCredentialType> = TCredential extends AnyCredentialType
+  ? Awaited<ReturnType<TCredential["createSession"]>>
+  : unknown;
+
+export type DefinedNodeCredentialBinding =
+  | ResolvableCredentialType
+  | Readonly<{
+      readonly type: ResolvableCredentialType | ReadonlyArray<ResolvableCredentialType>;
+      readonly label?: string;
+      readonly optional?: true;
+      readonly helpText?: string;
+      readonly helpUrl?: string;
+    }>;
+
+export type DefinedNodeCredentialBindings = Readonly<Record<string, DefinedNodeCredentialBinding>>;
+
+type SessionForBinding<TBinding extends DefinedNodeCredentialBinding> =
+  TBinding extends Readonly<{ type: infer TType }>
+    ? TType extends ReadonlyArray<infer TEntry>
+      ? SessionForCredentialType<TEntry & ResolvableCredentialType>
+      : SessionForCredentialType<TType & ResolvableCredentialType>
+    : SessionForCredentialType<TBinding & ResolvableCredentialType>;
+
+export type DefinedNodeCredentialAccessors<TBindings extends DefinedNodeCredentialBindings | undefined> =
+  TBindings extends DefinedNodeCredentialBindings
+    ? Readonly<{
+        [TKey in keyof TBindings]: () => Promise<SessionForBinding<TBindings[TKey]>>;
+      }>
+    : Readonly<Record<string, never>>;
+
+export interface DefinedNodeRunContext<
+  TConfig extends CredentialJsonRecord,
+  TBindings extends DefinedNodeCredentialBindings | undefined,
+> {
+  readonly config: TConfig;
+  readonly credentials: DefinedNodeCredentialAccessors<TBindings>;
+  readonly execution: NodeExecutionContext<RunnableNodeConfig<TConfig, unknown>>;
+}
+
+export interface DefinedNode<
+  TKey extends string,
+  TConfig extends CredentialJsonRecord,
+  TInputJson,
+  TOutputJson,
+  _TBindings extends DefinedNodeCredentialBindings | undefined = undefined,
+> {
+  readonly kind: "defined-node";
+  readonly key: TKey;
+  readonly title: string;
+  readonly description?: string;
+  create(config: TConfig, name?: string, id?: string): RunnableNodeConfig<TInputJson, TOutputJson>;
+  register(context: { registerNode<TValue>(token: TypeToken<TValue>, implementation?: TypeToken<TValue>): void }): void;
+}
+
+export interface DefineNodeOptions<
+  TKey extends string,
+  TConfig extends CredentialJsonRecord,
+  TInputJson,
+  TOutputJson,
+  TBindings extends DefinedNodeCredentialBindings | undefined = undefined,
+> {
+  readonly key: TKey;
+  readonly title: string;
+  readonly description?: string;
+  readonly input?: Readonly<Record<keyof TConfig & string, unknown>>;
+  readonly configSchema?: z.ZodType<TConfig>;
+  readonly credentials?: TBindings;
+  run(
+    items: ReadonlyArray<TInputJson>,
+    context: DefinedNodeRunContext<TConfig, TBindings>,
+  ): MaybePromise<ReadonlyArray<TOutputJson>>;
+}
+
+const definedNodeCredentialRequirementFactory = {
+  create(bindings: DefinedNodeCredentialBindings | undefined): ReadonlyArray<CredentialRequirement> {
+    if (!bindings) {
+      return [];
+    }
+    return Object.entries(bindings).map(([slotKey, binding]) => {
+      if (typeof binding === "string" || this.isCredentialType(binding)) {
+        return {
+          slotKey,
+          label: this.humanize(slotKey),
+          acceptedTypes: [this.resolveTypeId(binding)],
+        };
+      }
+
+      const types = Array.isArray(binding.type) ? binding.type : [binding.type];
+      return {
+        slotKey,
+        label: binding.label ?? this.humanize(slotKey),
+        acceptedTypes: types.map((entry) => this.resolveTypeId(entry)),
+        optional: binding.optional,
+        helpText: binding.helpText,
+        helpUrl: binding.helpUrl,
+      };
+    });
+  },
+
+  isCredentialType(value: unknown): value is AnyCredentialType {
+    return (
+      Boolean(value) &&
+      typeof value === "object" &&
+      "definition" in (value as Record<string, unknown>) &&
+      typeof (value as AnyCredentialType).definition?.typeId === "string"
+    );
+  },
+
+  resolveTypeId(type: ResolvableCredentialType): string {
+    return typeof type === "string" ? type : type.definition.typeId;
+  },
+
+  humanize(key: string): string {
+    return key
+      .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+      .replace(/[-_.]+/g, " ")
+      .replace(/\s+/g, " ")
+      .trim()
+      .replace(/^./, (character) => character.toUpperCase());
+  },
+} as const;
+
+const definedNodeCredentialAccessorFactory = {
+  create<TBindings extends DefinedNodeCredentialBindings | undefined>(
+    bindings: TBindings,
+    ctx: NodeExecutionContext<RunnableNodeConfig<any, any>>,
+  ): DefinedNodeCredentialAccessors<TBindings> {
+    if (!bindings) {
+      return {} as DefinedNodeCredentialAccessors<TBindings>;
+    }
+    const entries = Object.keys(bindings).map((slotKey) => [slotKey, () => ctx.getCredential(slotKey)] as const);
+    return Object.fromEntries(entries) as DefinedNodeCredentialAccessors<TBindings>;
+  },
+} as const;
+
+export function defineNode<
+  TKey extends string,
+  TConfig extends CredentialJsonRecord,
+  TInputJson,
+  TOutputJson,
+  TBindings extends DefinedNodeCredentialBindings | undefined = undefined,
+>(
+  options: DefineNodeOptions<TKey, TConfig, TInputJson, TOutputJson, TBindings>,
+): DefinedNode<TKey, TConfig, TInputJson, TOutputJson, TBindings> {
+  const credentialRequirements = definedNodeCredentialRequirementFactory.create(options.credentials);
+  type DefinedRunnableNodeConfigShape = RunnableNodeConfig<TInputJson, TOutputJson> & Readonly<{ config: TConfig }>;
+
+  const DefinedNodeRuntime = class implements Node<DefinedRunnableNodeConfigShape> {
+    readonly kind = "node" as const;
+    readonly outputPorts = ["main"] as const;
+
+    async execute(items: Items, ctx: NodeExecutionContext<DefinedRunnableNodeConfigShape>): Promise<NodeOutputs> {
+      const outputs = await options.run(
+        items.map((item) => item.json as TInputJson),
+        {
+          config: ctx.config.config,
+          credentials: definedNodeCredentialAccessorFactory.create(
+            options.credentials,
+            ctx,
+          ) as DefinedNodeCredentialAccessors<TBindings>,
+          execution: ctx as unknown as NodeExecutionContext<RunnableNodeConfig<TConfig, unknown>>,
+        },
+      );
+
+      return {
+        main: outputs.map((json, index) => {
+          const existing = items[index];
+          if (!existing) {
+            return { json };
+          }
+          return { ...existing, json };
+        }),
+      };
+    }
+  };
+
+  persistedNode({ name: options.key })(DefinedNodeRuntime);
+
+  const DefinedRunnableNodeConfig = class implements RunnableNodeConfig<TInputJson, TOutputJson> {
+    readonly kind = "node" as const;
+    readonly type: TypeToken<unknown> = DefinedNodeRuntime;
+
+    constructor(
+      public readonly name: string,
+      public readonly config: TConfig,
+      public readonly id?: string,
+    ) {}
+
+    getCredentialRequirements(): ReadonlyArray<CredentialRequirement> {
+      return credentialRequirements;
+    }
+  };
+
+  const definition: DefinedNode<TKey, TConfig, TInputJson, TOutputJson, TBindings> = {
+    kind: "defined-node",
+    key: options.key,
+    title: options.title,
+    description: options.description,
+    create(config, name = options.title, id) {
+      return new DefinedRunnableNodeConfig(name, config, id);
+    },
+    register(context) {
+      context.registerNode(DefinedNodeRuntime);
+    },
+  };
+
+  DefinedNodeRegistry.register(definition as DefinedNode<string, Record<string, unknown>, unknown, unknown>);
+
+  return definition;
+}

package/src/authoring/index.ts

@@ -0,0 +1,12 @@
+export { DefinedNodeRegistry } from "./DefinedNodeRegistry";
+export type {
+  DefinedNode,
+  DefinedNodeCredentialAccessors,
+  DefinedNodeCredentialBinding,
+  DefinedNodeCredentialBindings,
+  DefinedNodeRunContext,
+  DefineNodeOptions,
+} from "./defineNode.types";
+export { defineNode } from "./defineNode.types";
+export type { DefineCredentialOptions } from "./defineCredential.types";
+export { defineCredential } from "./defineCredential.types";

package/src/index.ts

@@ -1,4 +1,5 @@
 export { SystemClock, type Clock } from "./contracts/Clock";
+export * from "./authoring";
 export * from "./ai/AiHost";
 export * from "./workflow";
 export * from "./di";

package/src/planning/CurrentStateFrontierPlanner.ts

@@ -303,7 +303,17 @@ export class CurrentStateFrontierPlanner {
     if (!incomingEdge) {
       return false;
     }
-    return this.hasOutputPort(currentState, incomingEdge.from.nodeId, incomingEdge.from.output);
+    if (!this.hasOutputPort(currentState, incomingEdge.from.nodeId, incomingEdge.from.output)) {
+      return false;
+    }
+    if (this.usesCollect(nodeId)) {
+      return true;
+    }
+    const items = this.resolveOutputItems(currentState, incomingEdge.from.nodeId, incomingEdge.from.output);
+    if (items.length > 0) {
+      return true;
+    }
+    return this.shouldContinueAfterEmptyOutputFromSource(incomingEdge.from.nodeId);
   }
 
   private resolveInput(currentState: RunCurrentState, nodeId: NodeId, input: InputPortKey): Items {
@@ -335,6 +345,19 @@ export class CurrentStateFrontierPlanner {
     return currentState.outputsByNode[nodeId]?.[output] ?? [];
   }
 
+  private usesCollect(nodeId: NodeId): boolean {
+    const expectedInputs = this.topology.expectedInputsByNode.get(nodeId) ?? [];
+    return expectedInputs.length !== 1 || expectedInputs[0] !== "in";
+  }
+
+  private shouldContinueAfterEmptyOutputFromSource(nodeId: NodeId): boolean {
+    const definition = this.topology.defsById.get(nodeId);
+    if (!definition) {
+      return false;
+    }
+    return definition.config.continueWhenEmptyOutput === true;
+  }
+
   private getPinnedOutputs(currentState: RunCurrentState, nodeId: NodeId): NodeOutputs | undefined {
     return currentState.mutableState?.nodesById?.[nodeId]?.pinnedOutputsByPort;
   }

package/src/runtime/RunIntentService.ts

@@ -20,6 +20,7 @@ export type StartWorkflowIntent = {
   workflow: WorkflowDefinition;
   startAt?: string;
   items: Items;
+  synthesizeTriggerItems?: boolean;
   parent?: CurrentStateExecutionRequest["parent"];
   executionOptions?: RunExecutionOptions;
   workflowSnapshot?: CurrentStateExecutionRequest["workflowSnapshot"];
@@ -34,6 +35,7 @@ export type RerunFromNodeIntent = {
   nodeId: NodeId;
   currentState: RunCurrentState;
   items?: Items;
+  synthesizeTriggerItems?: boolean;
   parent?: CurrentStateExecutionRequest["parent"];
   executionOptions?: RunExecutionOptions;
   workflowSnapshot?: CurrentStateExecutionRequest["workflowSnapshot"];
@@ -58,22 +60,16 @@ export class RunIntentService {
   ) {}
 
   async startWorkflow(args: StartWorkflowIntent): Promise<RunResult> {
+    const items = await this.resolveStartWorkflowItems(args);
     if (args.startAt && !args.currentState && !args.stopCondition && !args.reset) {
-      return await this.engine.runWorkflow(
-        args.workflow,
-        args.startAt,
-        args.items,
-        args.parent,
-        args.executionOptions,
-        {
-          workflowSnapshot: args.workflowSnapshot,
-          mutableState: args.mutableState,
-        },
-      );
+      return await this.engine.runWorkflow(args.workflow, args.startAt, items, args.parent, args.executionOptions, {
+        workflowSnapshot: args.workflowSnapshot,
+        mutableState: args.mutableState,
+      });
     }
     return await this.engine.runWorkflowFromState({
       workflow: args.workflow,
-      items: args.items,
+      items,
       parent: args.parent,
       executionOptions: args.executionOptions,
       workflowSnapshot: args.workflowSnapshot,
@@ -85,8 +81,9 @@ export class RunIntentService {
   }
 
   async rerunFromNode(args: RerunFromNodeIntent): Promise<RunResult> {
-    if (args.items) {
-      return await this.engine.runWorkflow(args.workflow, args.nodeId, args.items, args.parent, args.executionOptions, {
+    const items = await this.resolveRerunItems(args);
+    if (items) {
+      return await this.engine.runWorkflow(args.workflow, args.nodeId, items, args.parent, args.executionOptions, {
         workflowSnapshot: args.workflowSnapshot,
         mutableState: args.mutableState,
       });
@@ -103,6 +100,63 @@ export class RunIntentService {
     });
   }
 
+  private async resolveStartWorkflowItems(args: StartWorkflowIntent): Promise<Items> {
+    if (this.hasNonEmptyItems(args.items)) {
+      return args.items;
+    }
+    const triggerNodeId = this.resolveStartWorkflowTriggerNodeId(args);
+    if (!triggerNodeId) {
+      return args.items;
+    }
+    return (await this.engine.createTriggerTestItems({ workflow: args.workflow, nodeId: triggerNodeId })) ?? args.items;
+  }
+
+  private async resolveRerunItems(args: RerunFromNodeIntent): Promise<Items | undefined> {
+    if (this.hasNonEmptyItems(args.items)) {
+      return args.items;
+    }
+    const triggerNodeId = this.resolveRerunTriggerNodeId(args);
+    if (!triggerNodeId) {
+      return args.items;
+    }
+    return (await this.engine.createTriggerTestItems({ workflow: args.workflow, nodeId: triggerNodeId })) ?? args.items;
+  }
+
+  private resolveStartWorkflowTriggerNodeId(args: StartWorkflowIntent): NodeId | undefined {
+    if (args.stopCondition?.kind === "nodeCompleted" && this.isTriggerNode(args.workflow, args.stopCondition.nodeId)) {
+      return args.stopCondition.nodeId;
+    }
+    if (!args.synthesizeTriggerItems) {
+      return undefined;
+    }
+    if (args.startAt && this.isTriggerNode(args.workflow, args.startAt)) {
+      return args.startAt;
+    }
+    return this.firstTriggerNodeId(args.workflow);
+  }
+
+  private resolveRerunTriggerNodeId(args: RerunFromNodeIntent): NodeId | undefined {
+    if (this.isTriggerNode(args.workflow, args.nodeId)) {
+      return args.nodeId;
+    }
+    if (!args.synthesizeTriggerItems) {
+      return undefined;
+    }
+    return this.firstTriggerNodeId(args.workflow);
+  }
+
+  private firstTriggerNodeId(workflow: WorkflowDefinition): NodeId | undefined {
+    return workflow.nodes.find((node) => node.kind === "trigger")?.id;
+  }
+
+  private isTriggerNode(workflow: WorkflowDefinition, nodeId: string): boolean {
+    return workflow.nodes.find((node) => node.id === nodeId)?.kind === "trigger";
+  }
+
+  private hasNonEmptyItems(items: Items | undefined): boolean {
+    return (items?.length ?? 0) > 0;
+  }
+
   resolveWebhookTrigger(args: { endpointPath: string; method: HttpMethod }): WebhookTriggerResolution {
     return this.engine.resolveWebhookTrigger(args);
   }