@codemation/core-nodes 1.0.1 → 1.1.0

package/src/http/HttpRequestExecutor.ts

@@ -0,0 +1,150 @@
+import type { Item } from "@codemation/core";
+import type { HttpRequestResult, HttpRequestSpec } from "./httpRequest.types";
+import type { HttpBodyBuilder } from "./HttpBodyBuilder";
+import type { HttpUrlBuilder } from "./HttpUrlBuilder";
+
+/**
+ * Executes a single HTTP request described by {@link HttpRequestSpec}.
+ *
+ * - Credential sessions provide header/query deltas via `applyToRequest`.
+ * - Body encoding is delegated to {@link HttpBodyBuilder}.
+ * - URL query merging is delegated to {@link HttpUrlBuilder}.
+ * - Binary response bodies: when `download.mode` triggers binary attach, the
+ *   `bodyBinaryName` field is set in the result but the body is NOT read here.
+ *   Callers that need binary attachment should use `buildRequest` to get the
+ *   resolved URL + init and make the fetch + binary attach themselves.
+ *
+ * Collaborators (`fetch`, body builder, url builder) are injected so callers
+ * own construction at composition roots and tests can supply deterministic stubs.
+ */
+export class HttpRequestExecutor {
+  constructor(
+    private readonly fetchFn: typeof globalThis.fetch,
+    private readonly bodyBuilder: HttpBodyBuilder,
+    private readonly urlBuilder: HttpUrlBuilder,
+  ) {}
+
+  /**
+   * Builds the fetch init (headers, query, body) from the spec + credential delta,
+   * returning both the resolved URL and the RequestInit so callers can make the
+   * actual fetch call themselves (useful for streaming / binary attach).
+   */
+  async buildRequest(spec: HttpRequestSpec, item: Item): Promise<Readonly<{ url: string; init: RequestInit }>> {
+    const credentialDelta = spec.credential?.applyToRequest(spec) ?? {};
+
+    const mergedHeaders: Record<string, string> = {
+      ...(spec.headers ?? {}),
+      ...(credentialDelta.headers ?? {}),
+    };
+
+    const mergedQuery: Record<string, string | string[]> = {
+      ...(spec.query ?? {}),
+      ...(credentialDelta.query ?? {}),
+    };
+
+    const encodedBody = await this.bodyBuilder.build(spec.body, item, spec.ctx);
+
+    // Only set Content-Type from the encoded body when it is non-empty
+    // (empty string = FormData will set it automatically).
+    if (encodedBody && encodedBody.contentType) {
+      mergedHeaders["content-type"] = encodedBody.contentType;
+    }
+
+    const resolvedUrl = this.urlBuilder.build(spec.url, mergedQuery);
+
+    const init: RequestInit = {
+      method: spec.method,
+      headers: mergedHeaders,
+      ...(encodedBody ? { body: encodedBody.body } : {}),
+    };
+
+    return { url: resolvedUrl, init };
+  }
+
+  /**
+   * Executes an HTTP request and returns parsed result.
+   * For binary downloads (when `shouldAttachBody` is true), the body is NOT consumed
+   * and callers must call `ctx.binary.attach` directly using the resolved URL + init
+   * (available via `buildRequest`).
+   */
+  async execute(spec: HttpRequestSpec, item: Item): Promise<HttpRequestResult> {
+    const { url: resolvedUrl, init } = await this.buildRequest(spec, item);
+
+    const response = await this.fetchFn(resolvedUrl, init);
+
+    const responseHeaders = this.readHeaders(response.headers);
+    const mimeType = this.resolveMimeType(responseHeaders);
+
+    const downloadMode = spec.download?.mode ?? "auto";
+    const binaryName = spec.download?.binaryName ?? "body";
+    const shouldDownload = this.shouldAttachBody(downloadMode, mimeType);
+
+    const isJson = this.isJsonMimeType(mimeType);
+
+    let json: unknown | undefined;
+    let text: string | undefined;
+    let bodyBinaryName: string | undefined;
+
+    if (shouldDownload) {
+      // Signal to caller that binary attachment is needed.
+      bodyBinaryName = binaryName;
+      // Do NOT read the body here — the caller must handle binary attach separately.
+    } else if (isJson) {
+      try {
+        json = await response.json();
+      } catch {
+        text = await response.text();
+      }
+    } else {
+      text = await response.text();
+    }
+
+    return {
+      url: resolvedUrl,
+      method: spec.method.toUpperCase(),
+      status: response.status,
+      ok: response.ok,
+      statusText: response.statusText,
+      mimeType,
+      headers: responseHeaders,
+      ...(json !== undefined ? { json } : {}),
+      ...(text !== undefined ? { text } : {}),
+      ...(bodyBinaryName !== undefined ? { bodyBinaryName } : {}),
+    };
+  }
+
+  private readHeaders(headers: Headers): Readonly<Record<string, string>> {
+    const values: Record<string, string> = {};
+    headers.forEach((value, key) => {
+      values[key] = value;
+    });
+    return values;
+  }
+
+  private resolveMimeType(headers: Readonly<Record<string, string>>): string {
+    const contentType = headers["content-type"];
+    if (!contentType) {
+      return "application/octet-stream";
+    }
+    return contentType.split(";")[0]?.trim() || "application/octet-stream";
+  }
+
+  private isJsonMimeType(mimeType: string): boolean {
+    return mimeType === "application/json" || mimeType.endsWith("+json");
+  }
+
+  private shouldAttachBody(mode: "auto" | "always" | "never", mimeType: string): boolean {
+    if (mode === "always") {
+      return true;
+    }
+    if (mode === "never") {
+      return false;
+    }
+    return (
+      mimeType.startsWith("image/") ||
+      mimeType.startsWith("audio/") ||
+      mimeType.startsWith("video/") ||
+      mimeType === "application/pdf"
+    );
+  }
+}

package/src/http/HttpUrlBuilder.ts

@@ -0,0 +1,22 @@
+/**
+ * Merges query parameters into a base URL.
+ * Handles both scalar and array values, and preserves any existing params.
+ */
+export class HttpUrlBuilder {
+  build(baseUrl: string, query?: Readonly<Record<string, string | string[]>>): string {
+    if (!query || Object.keys(query).length === 0) {
+      return baseUrl;
+    }
+    const parsed = new URL(baseUrl);
+    for (const [key, value] of Object.entries(query)) {
+      if (Array.isArray(value)) {
+        for (const entry of value) {
+          parsed.searchParams.append(key, entry);
+        }
+      } else {
+        parsed.searchParams.append(key, value);
+      }
+    }
+    return parsed.toString();
+  }
+}

package/src/http/httpRequest.types.ts

@@ -0,0 +1,69 @@
+import type { NodeExecutionContext } from "@codemation/core";
+import type { RunnableNodeConfig } from "@codemation/core";
+
+/**
+ * Binary reference key into `item.binary`.
+ */
+export type BinaryRef = string;
+
+/**
+ * Discriminated union for the HTTP request body.
+ */
+export type HttpBodySpec =
+  | Readonly<{ kind: "none" }>
+  | Readonly<{ kind: "json"; data: unknown }>
+  | Readonly<{ kind: "form"; data: Readonly<Record<string, string>> }>
+  | Readonly<{
+      kind: "multipart";
+      fields: Readonly<Record<string, string>>;
+      binaries?: Readonly<Record<string, BinaryRef>>;
+    }>;
+
+/**
+ * Session interface that credential types implement.
+ * Returns header/query deltas so the executor can merge them without
+ * mutating the immutable HttpRequestSpec.
+ */
+export interface CredentialSession {
+  applyToRequest(spec: HttpRequestSpec): HttpCredentialDelta;
+}
+
+/**
+ * Mutations the credential session wants to apply to the outgoing request.
+ */
+export type HttpCredentialDelta = Readonly<{
+  headers?: Readonly<Record<string, string>>;
+  query?: Readonly<Record<string, string>>;
+}>;
+
+/**
+ * Full specification of one HTTP request. All URLs are fully resolved before
+ * being passed here (template substitution already applied by the caller).
+ */
+export type HttpRequestSpec = Readonly<{
+  url: string;
+  method: string;
+  headers?: Readonly<Record<string, string>>;
+  query?: Readonly<Record<string, string | string[]>>;
+  body?: HttpBodySpec;
+  credential?: CredentialSession;
+  download?: Readonly<{ mode: "auto" | "always" | "never"; binaryName: string }>;
+  /** Execution context — needed for binary attach. */
+  ctx: NodeExecutionContext<RunnableNodeConfig<unknown, unknown>>;
+}>;
+
+/**
+ * Result of executing an HTTP request.
+ */
+export type HttpRequestResult = Readonly<{
+  url: string;
+  method: string;
+  status: number;
+  ok: boolean;
+  statusText: string;
+  mimeType: string;
+  headers: Readonly<Record<string, string>>;
+  json?: unknown;
+  text?: string;
+  bodyBinaryName?: string;
+}>;

package/src/index.ts

@@ -1,22 +1,30 @@
 export * from "./canvasIconName";
+export * from "./credentials/index";
+export * from "./http/httpRequest.types";
+export * from "./authoring/defineRestNode.types";
 export * from "./chatModels/OpenAIChatModelFactory";
 export * from "./chatModels/OpenAiStrictJsonSchemaFactory";
 export * from "./chatModels/OpenAiCredentialSession";
 export * from "./chatModels/openAiChatModelConfig";
 export * from "./chatModels/OpenAiChatModelPresetsFactory";
 export * from "./nodes/aiAgent";
+export * from "./nodes/assertion";
 export * from "./nodes/CallbackNodeFactory";
 export * from "./nodes/httpRequest";
 export * from "./nodes/aggregate";
 export * from "./nodes/filter";
 export * from "./nodes/if";
+export * from "./nodes/isTestRun";
 export * from "./nodes/switch";
 export * from "./nodes/split";
+export * from "./nodes/CronTriggerFactory";
+export * from "./nodes/CronTriggerNode";
 export * from "./nodes/ManualTriggerFactory";
 export * from "./nodes/mapData";
 export * from "./nodes/merge";
 export * from "./nodes/noOp";
 export * from "./nodes/subWorkflow";
+export * from "./nodes/testTrigger";
 export * from "./nodes/wait";
 export * from "./nodes/webhookRespondNowAndContinueError";
 export * from "./nodes/webhookRespondNowError";
@@ -30,3 +38,4 @@ export * from "./nodes/ConnectionCredentialNode";
 export * from "./nodes/ConnectionCredentialNodeConfig";
 export * from "./nodes/ConnectionCredentialNodeConfigFactory";
 export * from "./nodes/ConnectionCredentialExecutionContextFactory";
+export * from "./nodes/collections";

package/src/nodes/AIAgentNode.ts

@@ -356,7 +356,7 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
       return {
         config: entry.config,
         inputSchema: entry.runtime.inputSchema,
-        execute: async (input: unknown): Promise<unknown> => {
+        execute: async (input, hooks): Promise<unknown> => {
           const validated = entry.runtime.inputSchema.parse(input) as unknown;
           return await entry.runtime.execute({
             config: entry.config,
@@ -365,6 +365,7 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
             item,
             itemIndex,
             items,
+            hooks,
           });
         },
       } satisfies ItemScopedToolBinding;
@@ -421,11 +422,36 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
       activationId: ctx.activationId,
       inputsByPort: itemInputsByPort,
     });
+    await ctx.nodeState?.appendConnectionInvocation({
+      invocationId,
+      connectionNodeId: languageModelConnectionNodeId,
+      parentAgentNodeId: ctx.nodeId,
+      parentAgentActivationId: ctx.activationId,
+      status: "queued",
+      managedInput: summarizedInput,
+      queuedAt: startedAt.toISOString(),
+      iterationId: ctx.iterationId,
+      itemIndex: ctx.itemIndex,
+      parentInvocationId: ctx.parentInvocationId,
+    });
     await ctx.nodeState?.markRunning({
       nodeId: languageModelConnectionNodeId,
       activationId: ctx.activationId,
       inputsByPort: itemInputsByPort,
     });
+    await ctx.nodeState?.appendConnectionInvocation({
+      invocationId,
+      connectionNodeId: languageModelConnectionNodeId,
+      parentAgentNodeId: ctx.nodeId,
+      parentAgentActivationId: ctx.activationId,
+      status: "running",
+      managedInput: summarizedInput,
+      queuedAt: startedAt.toISOString(),
+      startedAt: startedAt.toISOString(),
+      iterationId: ctx.iterationId,
+      itemIndex: ctx.itemIndex,
+      parentInvocationId: ctx.parentInvocationId,
+    });
     try {
       const tools = this.buildToolSet(itemScopedTools);
       const callOptions = this.resolveCallOptions(model, guardrails.modelInvocationOptions);
@@ -441,11 +467,12 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
       });
       const turnResult = this.extractTurnResult(result as AnyGenerateTextResult);
       const finishedAt = new Date();
+      const managedOutput = this.summarizeTurnOutput(turnResult);
       await ctx.nodeState?.markCompleted({
         nodeId: languageModelConnectionNodeId,
         activationId: ctx.activationId,
         inputsByPort: itemInputsByPort,
-        outputs: AgentOutputFactory.fromUnknown({ content: turnResult.text }),
+        outputs: AgentOutputFactory.fromUnknown(managedOutput),
       });
       await span.attachArtifact({ kind: "ai.messages", contentType: "application/json", previewJson: summarizedInput });
       await span.attachArtifact({ kind: "ai.response", contentType: "application/json", previewJson: turnResult.text });
@@ -458,10 +485,13 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
         parentAgentActivationId: ctx.activationId,
         status: "completed",
         managedInput: summarizedInput,
-        managedOutput: turnResult.text,
+        managedOutput,
         queuedAt: startedAt.toISOString(),
         startedAt: startedAt.toISOString(),
         finishedAt: finishedAt.toISOString(),
+        iterationId: ctx.iterationId,
+        itemIndex: ctx.itemIndex,
+        parentInvocationId: ctx.parentInvocationId,
       });
       return turnResult;
     } catch (error) {
@@ -504,11 +534,36 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
       activationId: ctx.activationId,
       inputsByPort: itemInputsByPort,
     });
+    await ctx.nodeState?.appendConnectionInvocation({
+      invocationId,
+      connectionNodeId: languageModelConnectionNodeId,
+      parentAgentNodeId: ctx.nodeId,
+      parentAgentActivationId: ctx.activationId,
+      status: "queued",
+      managedInput: summarizedInput,
+      queuedAt: startedAt.toISOString(),
+      iterationId: ctx.iterationId,
+      itemIndex: ctx.itemIndex,
+      parentInvocationId: ctx.parentInvocationId,
+    });
     await ctx.nodeState?.markRunning({
       nodeId: languageModelConnectionNodeId,
       activationId: ctx.activationId,
       inputsByPort: itemInputsByPort,
     });
+    await ctx.nodeState?.appendConnectionInvocation({
+      invocationId,
+      connectionNodeId: languageModelConnectionNodeId,
+      parentAgentNodeId: ctx.nodeId,
+      parentAgentActivationId: ctx.activationId,
+      status: "running",
+      managedInput: summarizedInput,
+      queuedAt: startedAt.toISOString(),
+      startedAt: startedAt.toISOString(),
+      iterationId: ctx.iterationId,
+      itemIndex: ctx.itemIndex,
+      parentInvocationId: ctx.parentInvocationId,
+    });
     try {
       const callOptions = this.resolveCallOptions(model, guardrails.modelInvocationOptions);
       const outputSchema =
@@ -551,6 +606,9 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
         queuedAt: startedAt.toISOString(),
         startedAt: startedAt.toISOString(),
         finishedAt: finishedAt.toISOString(),
+        iterationId: ctx.iterationId,
+        itemIndex: ctx.itemIndex,
+        parentInvocationId: ctx.parentInvocationId,
       });
       return result.experimental_output;
     } catch (error) {
@@ -589,6 +647,22 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     };
   }
 
+  /**
+   * Build a no-code-friendly output payload for an LLM round.
+   *
+   * Always includes `content` (matching the canvas snapshot shape used elsewhere) and adds a
+   * `toolCalls` array when the round produced tool calls so the execution inspector surfaces the
+   * planned calls instead of just an empty `""` for tool-only rounds.
+   */
+  private summarizeTurnOutput(turnResult: TurnResult): JsonValue {
+    if (turnResult.toolCalls.length === 0) return { content: turnResult.text };
+    const toolCalls = turnResult.toolCalls.map((toolCall) => ({
+      name: toolCall.name,
+      args: this.resultToJsonValue(toolCall.input) ?? null,
+    }));
+    return { content: turnResult.text, toolCalls };
+  }
+
   private extractTurnResult(result: AnyGenerateTextResult): TurnResult {
     const usage = this.extractUsageFromResult(result);
     const text = result.text;
@@ -642,6 +716,13 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
         [CodemationTelemetryAttributeNames.connectionInvocationId]: invocationId,
         [GenAiTelemetryAttributeNames.operationName]: "chat",
         [GenAiTelemetryAttributeNames.requestModel]: this.resolveChatModelName(ctx.config.chatModel),
+        ...(ctx.iterationId ? { [CodemationTelemetryAttributeNames.iterationId]: ctx.iterationId } : {}),
+        ...(typeof ctx.itemIndex === "number"
+          ? { [CodemationTelemetryAttributeNames.iterationIndex]: ctx.itemIndex }
+          : {}),
+        ...(ctx.parentInvocationId
+          ? { [CodemationTelemetryAttributeNames.parentInvocationId]: ctx.parentInvocationId }
+          : {}),
       },
     });
   }
@@ -707,12 +788,25 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     plannedToolCalls: ReadonlyArray<PlannedToolCall>,
     ctx: NodeExecutionContext<AIAgent<any, any>>,
   ): Promise<void> {
+    const queuedAt = new Date().toISOString();
     for (const plannedToolCall of plannedToolCalls) {
       await ctx.nodeState?.markQueued({
         nodeId: plannedToolCall.nodeId,
         activationId: ctx.activationId,
         inputsByPort: AgentToolCallPortMap.fromInput(plannedToolCall.toolCall.input ?? {}),
       });
+      await ctx.nodeState?.appendConnectionInvocation({
+        invocationId: plannedToolCall.invocationId,
+        connectionNodeId: plannedToolCall.nodeId,
+        parentAgentNodeId: ctx.nodeId,
+        parentAgentActivationId: ctx.activationId,
+        status: "queued",
+        managedInput: this.resultToJsonValue(plannedToolCall.toolCall.input),
+        queuedAt,
+        iterationId: ctx.iterationId,
+        itemIndex: ctx.itemIndex,
+        parentInvocationId: ctx.parentInvocationId,
+      });
     }
   }
 
@@ -732,6 +826,7 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
         toolCall,
         invocationIndex,
         nodeId: ConnectionNodeIdFactory.toolConnectionNodeId(parentNodeId, binding.config.name),
+        invocationId: ConnectionInvocationIdFactory.create(),
       } satisfies PlannedToolCall;
     });
   }
@@ -771,6 +866,9 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
       queuedAt: args.startedAt.toISOString(),
       startedAt: args.startedAt.toISOString(),
       finishedAt: finishedAt.toISOString(),
+      iterationId: args.ctx.iterationId,
+      itemIndex: args.ctx.itemIndex,
+      parentInvocationId: args.ctx.parentInvocationId,
     });
     return effectiveError;
   }

package/src/nodes/AgentToolExecutionCoordinator.ts

@@ -1,5 +1,5 @@
 import type { JsonValue, NodeExecutionContext } from "@codemation/core";
-import { CodemationTelemetryAttributeNames, ConnectionInvocationIdFactory, inject, injectable } from "@codemation/core";
+import { CodemationTelemetryAttributeNames, inject, injectable } from "@codemation/core";
 
 import type { AIAgent } from "./AIAgentConfig";
 import { AgentOutputFactory } from "./AgentOutputFactory";
@@ -53,7 +53,7 @@ export class AgentToolExecutionCoordinator {
   ): Promise<ExecutedToolCall> {
     const { plannedToolCall, ctx } = args;
     const toolCallInputsByPort = AgentToolCallPortMap.fromInput(plannedToolCall.toolCall.input ?? {});
-    const invocationId = ConnectionInvocationIdFactory.create();
+    const invocationId = plannedToolCall.invocationId;
     const startedAt = new Date();
     const span = ctx.telemetry.startChildSpan({
       name: "agent.tool.call",
@@ -62,6 +62,13 @@ export class AgentToolExecutionCoordinator {
       attributes: {
         [CodemationTelemetryAttributeNames.connectionInvocationId]: invocationId,
         [CodemationTelemetryAttributeNames.toolName]: plannedToolCall.binding.config.name,
+        ...(ctx.iterationId ? { [CodemationTelemetryAttributeNames.iterationId]: ctx.iterationId } : {}),
+        ...(typeof ctx.itemIndex === "number"
+          ? { [CodemationTelemetryAttributeNames.iterationIndex]: ctx.itemIndex }
+          : {}),
+        ...(ctx.parentInvocationId
+          ? { [CodemationTelemetryAttributeNames.parentInvocationId]: ctx.parentInvocationId }
+          : {}),
       },
     });
     await ctx.nodeState?.markRunning({
@@ -69,9 +76,24 @@ export class AgentToolExecutionCoordinator {
       activationId: ctx.activationId,
       inputsByPort: toolCallInputsByPort,
     });
+    await ctx.nodeState?.appendConnectionInvocation({
+      invocationId,
+      connectionNodeId: plannedToolCall.nodeId,
+      parentAgentNodeId: ctx.nodeId,
+      parentAgentActivationId: ctx.activationId,
+      status: "running",
+      managedInput: this.toJsonValue(plannedToolCall.toolCall.input),
+      queuedAt: startedAt.toISOString(),
+      startedAt: startedAt.toISOString(),
+      iterationId: ctx.iterationId,
+      parentInvocationId: ctx.parentInvocationId,
+    });
 
     try {
-      const result = await plannedToolCall.binding.execute(plannedToolCall.toolCall.input ?? {});
+      const result = await plannedToolCall.binding.execute(plannedToolCall.toolCall.input ?? {}, {
+        parentSpan: span,
+        parentInvocationId: invocationId,
+      });
       const serialized = typeof result === "string" ? result : JSON.stringify(result);
       const finishedAt = new Date();
       await ctx.nodeState?.markCompleted({
@@ -102,6 +124,8 @@ export class AgentToolExecutionCoordinator {
         queuedAt: startedAt.toISOString(),
         startedAt: startedAt.toISOString(),
         finishedAt: finishedAt.toISOString(),
+        iterationId: ctx.iterationId,
+        parentInvocationId: ctx.parentInvocationId,
       });
       return {
         toolName: plannedToolCall.binding.config.name,
@@ -262,6 +286,8 @@ export class AgentToolExecutionCoordinator {
       queuedAt: args.startedAt.toISOString(),
       startedAt: args.startedAt.toISOString(),
       finishedAt: finishedAt.toISOString(),
+      iterationId: args.ctx.iterationId,
+      parentInvocationId: args.ctx.parentInvocationId,
     });
   }
 

package/src/nodes/AssertionNode.ts

@@ -0,0 +1,42 @@
+import type { AssertionResult, RunnableNode, RunnableNodeExecuteArgs } from "@codemation/core";
+import { node } from "@codemation/core";
+
+import { Assertion } from "./assertion";
+
+/**
+ * Runs the author's `assertions` callback for each input item and emits one workflow `Item` per
+ * returned {@link AssertionResult} on `main`. Persistence is handled by a host-side subscriber
+ * to `nodeCompleted` events that filters on `config.emitsAssertions === true`; this node does
+ * not write to any store on its own.
+ *
+ * If the author callback throws, we emit a single synthetic AssertionResult with `errored: true`
+ * and `score: 0`. Without this catch the whole node would fail and no assertion row would be
+ * persisted — making the rollup blind to "the assertion code itself is broken." The synthetic
+ * row keeps `failedAssertionsByRunId` consistent and gives the UI something to surface.
+ */
+@node({ packageName: "@codemation/core-nodes" })
+export class AssertionNode implements RunnableNode<Assertion<any>> {
+  kind = "node" as const;
+  outputPorts = ["main"] as const;
+
+  async execute(args: RunnableNodeExecuteArgs<Assertion<any>>): Promise<unknown> {
+    const ctx = args.ctx;
+    const config = ctx.config;
+    try {
+      const results: ReadonlyArray<AssertionResult> = await config.assertions(args.item, ctx);
+      // Engine "array → fan-out on main, each element is item.json" — returning the plain results
+      // makes downstream `item.json` exactly an AssertionResult. Wrapping in `{ json: result }`
+      // would double-wrap (engine would see `Item`-shaped values but treat them as JSON values).
+      return [...results];
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      const erroredResult: AssertionResult = {
+        name: config.name ?? "assertion",
+        score: 0,
+        errored: true,
+        message,
+      };
+      return [erroredResult];
+    }
+  }
+}

package/src/nodes/CronTriggerFactory.ts

@@ -0,0 +1,45 @@
+import type { TriggerNodeConfig, TypeToken } from "@codemation/core";
+
+import { Cron } from "croner";
+import type { CronCallback } from "croner";
+
+import { CronTriggerNode } from "./CronTriggerNode";
+
+export type CronTickJson = { firedAt: string; scheduledFor: string };
+
+/**
+ * Schedules a workflow on a standard cron expression.
+ *
+ * Each tick emits one item: `{ firedAt: string, scheduledFor: string }` — both ISO-8601 timestamps.
+ * `firedAt` is the wall-clock moment the callback ran; `scheduledFor` is the cron-computed
+ * firing instant (these differ when the job was delayed).
+ *
+ * Timezone defaults to UTC when omitted — cron without an explicit TZ is a DST footgun.
+ */
+export class CronTrigger implements TriggerNodeConfig<CronTickJson> {
+  readonly kind = "trigger" as const;
+  readonly type: TypeToken<unknown> = CronTriggerNode;
+  readonly icon = "lucide:clock" as const;
+  readonly id?: string;
+
+  constructor(
+    public readonly name: string,
+    private readonly args: Readonly<{ schedule: string; timezone?: string }>,
+    id?: string,
+  ) {
+    new Cron(args.schedule, { paused: true, timezone: args.timezone });
+    this.id = id;
+  }
+
+  get schedule(): string {
+    return this.args.schedule;
+  }
+
+  get timezone(): string | undefined {
+    return this.args.timezone;
+  }
+
+  createJob(callback: CronCallback): Cron {
+    return new Cron(this.args.schedule, { timezone: this.args.timezone, protect: true }, callback);
+  }
+}

package/src/nodes/CronTriggerNode.ts

@@ -0,0 +1,40 @@
+import type {
+  Items,
+  NodeExecutionContext,
+  NodeOutputs,
+  TestableTriggerNode,
+  TriggerSetupContext,
+  TriggerTestItemsContext,
+} from "@codemation/core";
+
+import { node } from "@codemation/core";
+
+import { CronTrigger } from "./CronTriggerFactory";
+
+@node({ packageName: "@codemation/core-nodes" })
+export class CronTriggerNode implements TestableTriggerNode<CronTrigger> {
+  readonly kind = "trigger" as const;
+  readonly outputPorts = ["main"] as const;
+
+  async setup(ctx: TriggerSetupContext<CronTrigger>): Promise<undefined> {
+    const job = ctx.config.createJob(async (self) => {
+      const scheduledFor = self.currentRun()?.toISOString() ?? ctx.now().toISOString();
+      await ctx.emit([{ json: { firedAt: ctx.now().toISOString(), scheduledFor } }]);
+    });
+    ctx.registerCleanup({
+      stop: () => {
+        job.stop();
+      },
+    });
+    return undefined;
+  }
+
+  async execute(items: Items, _ctx: NodeExecutionContext<CronTrigger>): Promise<NodeOutputs> {
+    return { main: items };
+  }
+
+  async getTestItems(ctx: TriggerTestItemsContext<CronTrigger>): Promise<Items> {
+    const nowIso = ctx.now().toISOString();
+    return [{ json: { firedAt: nowIso, scheduledFor: nowIso } }];
+  }
+}