@codemation/core-nodes 0.0.22 → 0.0.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemation/core-nodes",
-  "version": "0.0.22",
+  "version": "0.0.24",
   "publishConfig": {
     "access": "public"
   },
@@ -31,7 +31,7 @@
     "@langchain/core": "^1.1.31",
     "@langchain/openai": "^1.2.12",
     "lucide-react": "^0.577.0",
-    "@codemation/core": "0.2.1"
+    "@codemation/core": "0.2.3"
   },
   "devDependencies": {
     "@types/node": "^25.3.5",

package/src/index.ts

@@ -6,7 +6,10 @@ export * from "./chatModels/OpenAiChatModelPresetsFactory";
 export * from "./nodes/aiAgent";
 export * from "./nodes/CallbackNodeFactory";
 export * from "./nodes/httpRequest";
+export * from "./nodes/aggregate";
+export * from "./nodes/filter";
 export * from "./nodes/if";
+export * from "./nodes/split";
 export * from "./nodes/ManualTriggerFactory";
 export * from "./nodes/mapData";
 export * from "./nodes/merge";

package/src/nodes/AIAgentConfig.ts

@@ -4,15 +4,17 @@ import {
   type AgentMessageConfig,
   type AgentNodeConfig,
   type ChatModelConfig,
+  type ItemInputMapper,
   type RetryPolicySpec,
   type RunnableNodeConfig,
   type ToolConfig,
   type TypeToken,
 } from "@codemation/core";
+import type { ZodType } from "zod";
 
 import { AIAgentNode } from "./AIAgentNode";
 
-export interface AIAgentOptions<TInputJson = unknown, _TOutputJson = unknown> {
+export interface AIAgentOptions<TInputJson = unknown, _TOutputJson = unknown, TWireJson = TInputJson> {
   readonly name: string;
   readonly messages: AgentMessageConfig<TInputJson>;
   readonly chatModel: ChatModelConfig;
@@ -20,14 +22,18 @@ export interface AIAgentOptions<TInputJson = unknown, _TOutputJson = unknown> {
   readonly id?: string;
   readonly retryPolicy?: RetryPolicySpec;
   readonly guardrails?: AgentGuardrailConfig;
+  /** Engine applies with {@link RunnableNodeConfig.inputSchema} before {@link AIAgentNode.executeOne}. */
+  readonly inputSchema?: ZodType<TInputJson>;
+  /** Per-item mapper before validation; use with {@link inputSchema} so persisted run inputs show the prompt payload. */
+  readonly mapInput?: ItemInputMapper<TWireJson, TInputJson>;
 }
 
 /**
  * AI agent: credential bindings are keyed to connection-owned LLM/tool node ids (ConnectionNodeIdFactory),
  * not to the agent workflow node id.
  */
-export class AIAgent<TInputJson = unknown, TOutputJson = unknown>
-  implements RunnableNodeConfig<TInputJson, TOutputJson>, AgentNodeConfig<TInputJson, TOutputJson>
+export class AIAgent<TInputJson = unknown, TOutputJson = unknown, TWireJson = TInputJson>
+  implements RunnableNodeConfig<TInputJson, TOutputJson, TWireJson>, AgentNodeConfig<TInputJson, TOutputJson, TWireJson>
 {
   readonly kind = "node" as const;
   readonly type: TypeToken<unknown> = AIAgentNode;
@@ -40,8 +46,10 @@ export class AIAgent<TInputJson = unknown, TOutputJson = unknown>
   readonly id?: string;
   readonly retryPolicy: RetryPolicySpec;
   readonly guardrails?: AgentGuardrailConfig;
+  readonly inputSchema?: ZodType<TInputJson>;
+  readonly mapInput?: ItemInputMapper<TWireJson, TInputJson>;
 
-  constructor(options: AIAgentOptions<TInputJson, TOutputJson>) {
+  constructor(options: AIAgentOptions<TInputJson, TOutputJson, TWireJson>) {
     this.name = options.name;
     this.messages = options.messages;
     this.chatModel = options.chatModel;
@@ -49,5 +57,7 @@ export class AIAgent<TInputJson = unknown, TOutputJson = unknown>
     this.id = options.id;
     this.retryPolicy = options.retryPolicy ?? RetryPolicy.defaultForAiAgent;
     this.guardrails = options.guardrails;
+    this.inputSchema = options.inputSchema;
+    this.mapInput = options.mapInput;
   }
 }

package/src/nodes/AIAgentNode.ts

@@ -4,13 +4,12 @@ import type {
   ChatModelConfig,
   ChatModelFactory,
   Item,
+  ItemNode,
   Items,
   JsonValue,
   LangChainChatModelLike,
-  Node,
   NodeExecutionContext,
   NodeInputsByPort,
-  NodeOutputs,
   Tool,
   ToolConfig,
   ZodSchemaAny,
@@ -30,6 +29,7 @@ import {
 } from "@codemation/core";
 
 import { AIMessage, type BaseMessage } from "@langchain/core/messages";
+import { z } from "zod";
 
 import type { AIAgent } from "./AIAgentConfig";
 import { AIAgentExecutionHelpersFactory } from "./AIAgentExecutionHelpersFactory";
@@ -49,7 +49,7 @@ import {
 type ResolvedGuardrails = Required<Pick<AgentGuardrailConfig, "maxTurns" | "onTurnLimitReached">> &
   Pick<AgentGuardrailConfig, "modelInvocationOptions">;
 
-/** Everything needed to run the agent loop for a workflow execution (one `execute` call). */
+/** Everything needed to run the agent loop for one item (shared across items in the same activation). */
 interface PreparedAgentExecution {
   readonly ctx: NodeExecutionContext<AIAgent<any, any>>;
   readonly model: LangChainChatModelLike;
@@ -59,11 +59,21 @@ interface PreparedAgentExecution {
 }
 
 @node({ packageName: "@codemation/core-nodes" })
-export class AIAgentNode implements Node<AIAgent<any, any>> {
+export class AIAgentNode implements ItemNode<AIAgent<any, any>, unknown, unknown> {
   kind = "node" as const;
   outputPorts = ["main"] as const;
+  /**
+   * Engine applies {@link RunnableNodeConfig.mapInput} + parse before {@link #executeOne}. Prefer modeling
+   * prompts as {@code { messages: [{ role, content }, ...] }} so persisted inputs are visible in the UI.
+   */
+  readonly inputSchema = z.unknown();
 
   private readonly connectionCredentialExecutionContextFactory: ConnectionCredentialExecutionContextFactory;
+  /** One resolved model/tools bundle per activation context (same ctx across items in a batch). */
+  private readonly preparedByExecutionContext = new WeakMap<
+    NodeExecutionContext<AIAgent<any, any>>,
+    Promise<PreparedAgentExecution>
+  >();
 
   constructor(
     @inject(CoreTokens.NodeResolver)
@@ -79,17 +89,35 @@ export class AIAgentNode implements Node<AIAgent<any, any>> {
       this.executionHelpers.createConnectionCredentialExecutionContextFactory(credentialSessions);
   }
 
-  async execute(items: Items, ctx: NodeExecutionContext<AIAgent<any, any>>): Promise<NodeOutputs> {
-    const prepared = await this.prepareExecution(ctx);
-    const out: Item[] = [];
-    for (let i = 0; i < items.length; i++) {
-      out.push(await this.runAgentForItem(prepared, items[i]!, i, items));
+  async executeOne(args: {
+    input: unknown;
+    item: Item;
+    itemIndex: number;
+    items: Items;
+    ctx: NodeExecutionContext<AIAgent<any, any>>;
+  }): Promise<unknown> {
+    const prepared = await this.getOrPrepareExecution(args.ctx);
+    const itemWithMappedJson = { ...args.item, json: args.input };
+    const resultItem = await this.runAgentForItem(prepared, itemWithMappedJson, args.itemIndex, args.items);
+    return resultItem.json;
+  }
+
+  private async getOrPrepareExecution(ctx: NodeExecutionContext<AIAgent<any, any>>): Promise<PreparedAgentExecution> {
+    let pending = this.preparedByExecutionContext.get(ctx);
+    if (!pending) {
+      pending = this.prepareExecution(ctx);
+      this.preparedByExecutionContext.set(ctx, pending);
+    }
+    try {
+      return await pending;
+    } catch (error) {
+      this.preparedByExecutionContext.delete(ctx);
+      throw error;
     }
-    return { main: out };
   }
 
   /**
-   * Resolves the chat model and tools once, then returns shared state for every item in the batch.
+   * Resolves the chat model and tools once per activation, then reuses for every item in the batch.
    */
   private async prepareExecution(ctx: NodeExecutionContext<AIAgent<any, any>>): Promise<PreparedAgentExecution> {
     const chatModelFactory = this.nodeResolver.resolve(ctx.config.chatModel.type) as ChatModelFactory<ChatModelConfig>;
@@ -467,7 +495,7 @@ export class AIAgentNode implements Node<AIAgent<any, any>> {
     ctx: NodeExecutionContext<AIAgent<any, any>>,
   ): ReadonlyArray<BaseMessage> {
     return AgentMessageFactory.createPromptMessages(
-      AgentMessageConfigNormalizer.normalize(ctx.config, {
+      AgentMessageConfigNormalizer.resolveFromInputOrConfig(item.json, ctx.config, {
         item,
         itemIndex,
         items,

package/src/nodes/AggregateNode.ts

@@ -0,0 +1,19 @@
+import type { Items, Node, NodeExecutionContext, NodeOutputs } from "@codemation/core";
+
+import { node } from "@codemation/core";
+
+import type { Aggregate } from "./aggregate";
+
+@node({ packageName: "@codemation/core-nodes" })
+export class AggregateNode implements Node<Aggregate<any, any>> {
+  kind = "node" as const;
+  outputPorts = ["main"] as const;
+
+  async execute(items: Items, ctx: NodeExecutionContext<Aggregate<any, any>>): Promise<NodeOutputs> {
+    if (items.length === 0) {
+      return { main: [] };
+    }
+    const json = await Promise.resolve(ctx.config.aggregate(items as Items, ctx));
+    return { main: [{ json }] };
+  }
+}

package/src/nodes/FilterNode.ts

@@ -0,0 +1,22 @@
+import type { Item, Items, Node, NodeExecutionContext, NodeOutputs } from "@codemation/core";
+
+import { node } from "@codemation/core";
+
+import type { Filter } from "./filter";
+
+@node({ packageName: "@codemation/core-nodes" })
+export class FilterNode implements Node<Filter<any>> {
+  kind = "node" as const;
+  outputPorts = ["main"] as const;
+
+  async execute(items: Items, ctx: NodeExecutionContext<Filter<any>>): Promise<NodeOutputs> {
+    const out: Item[] = [];
+    for (let i = 0; i < items.length; i++) {
+      const item = items[i] as Item;
+      if (ctx.config.predicate(item as Item, i, items as Items, ctx)) {
+        out.push(item);
+      }
+    }
+    return { main: out };
+  }
+}

package/src/nodes/MapDataNode.ts

@@ -1,20 +1,23 @@
-import type { Item, Items, Node, NodeExecutionContext, NodeOutputs } from "@codemation/core";
+import type { Item, ItemNode, Items, NodeExecutionContext } from "@codemation/core";
 
 import { node } from "@codemation/core";
+import { z } from "zod";
 
 import { MapData } from "./mapData";
 
 @node({ packageName: "@codemation/core-nodes" })
-export class MapDataNode implements Node<MapData<any, any>> {
+export class MapDataNode implements ItemNode<MapData<any, any>, unknown, unknown> {
   kind = "node" as const;
   outputPorts = ["main"] as const;
+  readonly inputSchema = z.unknown();
 
-  async execute(items: Items, ctx: NodeExecutionContext<MapData<any, any>>): Promise<NodeOutputs> {
-    const out: Item[] = [];
-    for (let i = 0; i < items.length; i++) {
-      const item = items[i] as Item<unknown>;
-      out.push({ ...item, json: ctx.config.map(item, ctx) });
-    }
-    return { main: out };
+  async executeOne(args: {
+    input: unknown;
+    item: Item;
+    itemIndex: number;
+    items: Items;
+    ctx: NodeExecutionContext<MapData<any, any>>;
+  }): Promise<unknown> {
+    return args.ctx.config.map(args.item, args.ctx);
   }
 }

package/src/nodes/SplitNode.ts

@@ -0,0 +1,26 @@
+import type { Item, Items, Node, NodeExecutionContext, NodeOutputs } from "@codemation/core";
+
+import { node } from "@codemation/core";
+
+import type { Split } from "./split";
+
+@node({ packageName: "@codemation/core-nodes" })
+export class SplitNode implements Node<Split<any, any>> {
+  kind = "node" as const;
+  outputPorts = ["main"] as const;
+
+  async execute(items: Items, ctx: NodeExecutionContext<Split<any, any>>): Promise<NodeOutputs> {
+    const out: Item[] = [];
+    for (let i = 0; i < items.length; i++) {
+      const item = items[i] as Item;
+      const elements = ctx.config.getElements(item, ctx);
+      for (let j = 0; j < elements.length; j++) {
+        out.push({
+          ...item,
+          json: elements[j],
+        });
+      }
+    }
+    return { main: out };
+  }
+}

package/src/nodes/aggregate.ts

@@ -0,0 +1,21 @@
+import type { Items, NodeExecutionContext, RunnableNodeConfig, TypeToken } from "@codemation/core";
+
+import { AggregateNode } from "./AggregateNode";
+
+export class Aggregate<TIn = unknown, TOut = unknown> implements RunnableNodeConfig<TIn, TOut> {
+  readonly kind = "node" as const;
+  readonly type: TypeToken<unknown> = AggregateNode;
+  readonly execution = { hint: "local" } as const;
+  readonly icon = "lucide:layers" as const;
+
+  constructor(
+    public readonly name: string,
+    public readonly aggregate: (
+      items: Items<TIn>,
+      ctx: NodeExecutionContext<Aggregate<TIn, TOut>>,
+    ) => TOut | Promise<TOut>,
+    public readonly id?: string,
+  ) {}
+}
+
+export { AggregateNode } from "./AggregateNode";

package/src/nodes/filter.ts

@@ -0,0 +1,23 @@
+import type { Item, Items, NodeExecutionContext, RunnableNodeConfig, TypeToken } from "@codemation/core";
+
+import { FilterNode } from "./FilterNode";
+
+export class Filter<TIn = unknown> implements RunnableNodeConfig<TIn, TIn> {
+  readonly kind = "node" as const;
+  readonly type: TypeToken<unknown> = FilterNode;
+  readonly execution = { hint: "local" } as const;
+  readonly icon = "lucide:filter" as const;
+
+  constructor(
+    public readonly name: string,
+    public readonly predicate: (
+      item: Item<TIn>,
+      index: number,
+      items: Items<TIn>,
+      ctx: NodeExecutionContext<Filter<TIn>>,
+    ) => boolean,
+    public readonly id?: string,
+  ) {}
+}
+
+export { FilterNode } from "./FilterNode";

package/src/nodes/split.ts

@@ -0,0 +1,23 @@
+import type { Item, NodeExecutionContext, RunnableNodeConfig, TypeToken } from "@codemation/core";
+
+import { SplitNode } from "./SplitNode";
+
+export class Split<TIn = unknown, TElem = unknown> implements RunnableNodeConfig<TIn, TElem> {
+  readonly kind = "node" as const;
+  readonly type: TypeToken<unknown> = SplitNode;
+  readonly execution = { hint: "local" } as const;
+  /**
+   * When splitting yields zero items for a batch, downstream single-input nodes still run once with an empty batch.
+   * Mirrors {@link MapData}'s empty-output behavior.
+   */
+  readonly continueWhenEmptyOutput = true as const;
+  readonly icon = "lucide:ungroup" as const;
+
+  constructor(
+    public readonly name: string,
+    public readonly getElements: (item: Item<TIn>, ctx: NodeExecutionContext<Split<TIn, TElem>>) => readonly TElem[],
+    public readonly id?: string,
+  ) {}
+}
+
+export { SplitNode } from "./SplitNode";

package/src/register.types.ts

@@ -9,6 +9,9 @@ import { NoOpNode } from "./nodes/noOp";
 import { SubWorkflowNode } from "./nodes/subWorkflow";
 import { WaitNode } from "./nodes/wait";
 import { ConnectionCredentialNode } from "./nodes/ConnectionCredentialNode";
+import { AggregateNode } from "./nodes/aggregate";
+import { FilterNode } from "./nodes/filter";
+import { SplitNode } from "./nodes/split";
 
 /**
  * Registrar for built-in nodes. In a real project, this would use tsyringe's
@@ -34,4 +37,7 @@ export function registerCoreNodes(container: Container): void {
   void AIAgentExecutionHelpersFactory;
   void WaitNode;
   void ConnectionCredentialNode;
+  void SplitNode;
+  void FilterNode;
+  void AggregateNode;
 }

package/src/workflowAuthoring/WorkflowBranchBuilder.types.ts

@@ -10,7 +10,7 @@ import { WorkflowDurationParser } from "./WorkflowDurationParser.types";
 export class WorkflowBranchBuilder<TCurrentJson> {
   constructor(private readonly steps: ReadonlyArray<AnyRunnableNodeConfig> = []) {}
 
-  then<TConfig extends RunnableNodeConfig<TCurrentJson, any>>(
+  then<TInputJson, TOutputJson, TConfig extends RunnableNodeConfig<TInputJson, TOutputJson, TCurrentJson>>(
     config: TConfig,
   ): WorkflowBranchBuilder<RunnableNodeOutputJson<TConfig>> {
     return new WorkflowBranchBuilder<RunnableNodeOutputJson<TConfig>>([...this.steps, config]);

package/src/workflowAuthoring/WorkflowChain.types.ts

@@ -18,7 +18,7 @@ type BranchOutputMatch<TLeft, TRight> = [TLeft] extends [TRight] ? ([TRight] ext
 export class WorkflowChain<TCurrentJson> {
   constructor(private readonly chain: ChainCursor<TCurrentJson>) {}
 
-  then<TConfig extends RunnableNodeConfig<TCurrentJson, any>>(
+  then<TInputJson, TOutputJson, TConfig extends RunnableNodeConfig<TInputJson, TOutputJson, TCurrentJson>>(
     config: TConfig,
   ): WorkflowChain<RunnableNodeOutputJson<TConfig>> {
     return new WorkflowChain(this.chain.then(config));