@codemation/core-nodes 0.4.2 → 0.6.0

package/dist/index.d.cts

@@ -1,8 +1,8 @@
 import { ReadableStream } from "node:stream/web";
-import { DependencyContainer as Container, InjectionToken as TypeToken } from "tsyringe";
 import { ZodType, input, output, z } from "zod";
-import { AIMessage, BaseMessage, HumanMessage, SystemMessage, ToolMessage } from "@langchain/core/messages";
-import { DynamicStructuredTool } from "@langchain/core/tools";
+import { DependencyContainer as Container, InjectionToken as TypeToken } from "tsyringe";
+import { AssistantModelMessage, ModelMessage, ToolModelMessage } from "ai";
+import { Cron, CronCallback } from "croner";
 
 //#region src/canvasIconName.d.ts
 /**
@@ -14,170 +14,223 @@ import { DynamicStructuredTool } from "@langchain/core/tools";
  */
 type CanvasIconName = string;
 //#endregion
-//#region ../core/src/contracts/emitPorts.d.ts
-declare const EMIT_PORTS_BRAND: unique symbol;
-type PortsEmission = Readonly<{
-  readonly [EMIT_PORTS_BRAND]: true;
-  readonly ports: Readonly<Partial<Record<OutputPortKey, Items | ReadonlyArray<JsonNonArray>>>>;
-}>;
+//#region ../core/src/contracts/baseTypes.d.ts
+/**
+ * Minimal base types that have no dependencies on other contracts.
+ * Used by credentialTypes, workflowTypes, and other contract layers
+ * to avoid circular dependencies.
+ */
+type WorkflowId = string;
+type NodeId = string;
+type OutputPortKey = string;
+type InputPortKey = string;
+type NodeConnectionName = string;
 //#endregion
-//#region ../core/src/contracts/itemExpr.d.ts
-declare const ITEM_EXPR_BRAND: unique symbol;
-type ItemExprResolvedContext = Readonly<{
-  runId: RunId;
-  workflowId: WorkflowId;
-  nodeId: NodeId;
-  activationId: NodeActivationId;
-  data: RunDataSnapshot;
+//#region ../core/src/contracts/credentialTypes.d.ts
+type CredentialTypeId = string;
+type CredentialInstanceId = string;
+type CredentialMaterialSourceKind = "db" | "env" | "code";
+type CredentialSetupStatus = "draft" | "ready";
+type CredentialHealthStatus = "unknown" | "healthy" | "failing";
+type CredentialFieldSchema = Readonly<{
+  key: string;
+  label: string;
+  type: "string" | "password" | "textarea" | "json" | "boolean";
+  required?: true;
+  order?: number;
+  /**
+   * Where this field appears in the credential dialog. Use `"advanced"` for optional or
+   * power-user fields; they render inside a collapsible section (see `CredentialTypeDefinition.advancedSection`).
+   * Defaults to `"default"` when omitted.
+   */
+  visibility?: "default" | "advanced";
+  placeholder?: string;
+  helpText?: string;
+  /** When set, host resolves this field from process.env at runtime; env wins over stored values. */
+  envVarName?: string;
+  /**
+   * When set, the dialog shows a copy action for this exact string (e.g. a static OAuth redirect URI
+   * pattern or documentation URL). Do not use for secret values.
+   */
+  copyValue?: string;
+  /** Accessible label for the copy control (default: Copy). */
+  copyButtonLabel?: string;
+}>;
+type CredentialRequirement = Readonly<{
+  slotKey: string;
+  label: string;
+  acceptedTypes: ReadonlyArray<CredentialTypeId>;
+  optional?: true;
+  helpText?: string;
+  helpUrl?: string;
+}>;
+type CredentialHealth = Readonly<{
+  status: CredentialHealthStatus;
+  message?: string;
+  testedAt?: string;
+  expiresAt?: string;
+  details?: Readonly<Record<string, unknown>>;
+}>;
+type OAuth2ProviderFromPublicConfig = Readonly<{
+  authorizeUrlFieldKey: string;
+  tokenUrlFieldKey: string;
+  userInfoUrlFieldKey?: string;
+}>;
+type CredentialOAuth2ScopesFromPublicConfig = Readonly<{
+  presetFieldKey: string;
+  presetScopes: Readonly<Record<string, ReadonlyArray<string>>>;
+  customPresetKey?: string;
+  customScopesFieldKey?: string;
+}>;
+type CredentialOAuth2AuthDefinition = Readonly<{
+  kind: "oauth2";
+  providerId: string;
+  scopes: ReadonlyArray<string>;
+  scopesFromPublicConfig?: CredentialOAuth2ScopesFromPublicConfig;
+  clientIdFieldKey?: string;
+  clientSecretFieldKey?: string;
+} | {
+  kind: "oauth2";
+  providerFromPublicConfig: OAuth2ProviderFromPublicConfig;
+  scopes: ReadonlyArray<string>;
+  scopesFromPublicConfig?: CredentialOAuth2ScopesFromPublicConfig;
+  clientIdFieldKey?: string;
+  clientSecretFieldKey?: string;
+} | {
+  kind: "oauth2";
+  /**
+   * Free-form provider identifier for telemetry, DB rows, and Better Auth provider naming.
+   * Not used for any registry lookup — URLs come from {@link authorizeUrl} / {@link tokenUrl}.
+   */
+  providerId: string;
+  /**
+   * Authorization endpoint. May contain `{publicFieldKey}` placeholders that the runtime
+   * substitutes from the credential's resolved public config (URL-encoded).
+   * Example: `https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize`
+   */
+  authorizeUrl: string;
+  /** Token endpoint. Same templating rules as {@link authorizeUrl}. */
+  tokenUrl: string;
+  /** Optional userinfo endpoint. Same templating rules as {@link authorizeUrl}. */
+  userInfoUrl?: string;
+  scopes: ReadonlyArray<string>;
+  scopesFromPublicConfig?: CredentialOAuth2ScopesFromPublicConfig;
+  clientIdFieldKey?: string;
+  clientSecretFieldKey?: string;
+}>;
+type CredentialAuthDefinition = CredentialOAuth2AuthDefinition;
+type CredentialAdvancedSectionPresentation = Readonly<{
+  /** Collapsible section title (default: "Advanced"). */
+  title?: string;
+  /** Optional short helper text shown inside the section (above the fields). */
+  description?: string;
+  /** When true, the advanced section starts expanded. Default: false (collapsed). */
+  defaultOpen?: boolean;
+}>;
+type CredentialTypeDefinition = Readonly<{
+  typeId: CredentialTypeId;
+  displayName: string;
+  description?: string;
+  publicFields?: ReadonlyArray<CredentialFieldSchema>;
+  secretFields?: ReadonlyArray<CredentialFieldSchema>;
+  /**
+   * Optional labels for the collapsible block that contains every field with `visibility: "advanced"`.
+   * If omitted, the UI still shows that block with defaults (title "Advanced", collapsed).
+   */
+  advancedSection?: CredentialAdvancedSectionPresentation;
+  supportedSourceKinds?: ReadonlyArray<CredentialMaterialSourceKind>;
+  auth?: CredentialAuthDefinition;
 }>;
 /**
- * Context aligned with former {@link ItemInputMapperContext} — use **`data`** to read any completed upstream node.
+ * JSON-shaped credential field bag (public config, resolved secret material, etc.).
  */
-type ItemExprContext = ItemExprResolvedContext;
-type ItemExprArgs<TItemJson = unknown> = Readonly<{
-  item: Item<TItemJson>;
-  itemIndex: number;
-  items: Items<TItemJson>;
-  ctx: ItemExprContext;
+type CredentialJsonRecord = Readonly<Record<string, unknown>>;
+/**
+ * Persisted credential instance with typed `publicConfig`.
+ * Hosts may specialize `secretRef` with a stricter union while remaining
+ * assignable here for session/test callbacks.
+ */
+type CredentialInstanceRecord<TPublicConfig extends CredentialJsonRecord = CredentialJsonRecord> = Readonly<{
+  instanceId: CredentialInstanceId;
+  typeId: CredentialTypeId;
+  displayName: string;
+  sourceKind: CredentialMaterialSourceKind;
+  publicConfig: TPublicConfig;
+  secretRef: CredentialJsonRecord;
+  tags: ReadonlyArray<string>;
+  setupStatus: CredentialSetupStatus;
+  createdAt: string;
+  updatedAt: string;
 }>;
-type ItemExprCallback<T, TItemJson = unknown> = (args: ItemExprArgs<TItemJson>) => T | Promise<T>;
-type ItemExpr<T, TItemJson = unknown> = Readonly<{
-  readonly [ITEM_EXPR_BRAND]: true;
-  readonly fn: ItemExprCallback<T, TItemJson>;
+/**
+ * Arguments passed to `CredentialType.createSession` and `CredentialType.test`.
+ * Declare `TPublicConfig` / `TMaterial` on `CredentialType` so implementations are checked
+ * against your credential shapes (similar to `NodeExecutionContext.config` for nodes).
+ */
+type CredentialSessionFactoryArgs<TPublicConfig extends CredentialJsonRecord = CredentialJsonRecord, TMaterial extends CredentialJsonRecord = CredentialJsonRecord> = Readonly<{
+  instance: CredentialInstanceRecord<TPublicConfig>;
+  material: TMaterial;
+  publicConfig: TPublicConfig;
 }>;
-//#endregion
-//#region ../core/src/contracts/params.d.ts
-type Expr<T, TItemJson = unknown> = ItemExpr<T, TItemJson>;
-type ParamDeep<T, TItemJson = unknown> = Expr<T, TItemJson> | (T extends readonly (infer U)[] ? ReadonlyArray<ParamDeep<U, TItemJson>> : never) | (T extends object ? { [K in keyof T]: ParamDeep<T[K], TItemJson> } : T);
-//#endregion
-//#region ../core/src/contracts/retryPolicySpec.types.d.ts
+type CredentialSessionFactory<TPublicConfig extends CredentialJsonRecord = CredentialJsonRecord, TMaterial extends CredentialJsonRecord = CredentialJsonRecord, TSession = unknown> = (args: CredentialSessionFactoryArgs<TPublicConfig, TMaterial>) => Promise<TSession>;
+type CredentialHealthTester<TPublicConfig extends CredentialJsonRecord = CredentialJsonRecord, TMaterial extends CredentialJsonRecord = CredentialJsonRecord> = (args: CredentialSessionFactoryArgs<TPublicConfig, TMaterial>) => Promise<CredentialHealth>;
 /**
- * In-process retry policy for runnable nodes. Serialized configs use the same
- * `kind` discriminator (`JSON.stringify` / persisted workflows).
- *
- * `maxAttempts` is the total number of tries including the first (e.g. 3 means up to 2 delays after failures).
+ * Full credential type implementation: `definition` (UI/schema), `createSession`, and `test`.
+ * Use this at registration and config boundaries; `CredentialTypeDefinition` is only the schema slice.
  */
-type RetryPolicySpec = NoneRetryPolicySpec | FixedRetryPolicySpec | ExponentialRetryPolicySpec;
-interface NoneRetryPolicySpec {
-  readonly kind: "none";
-}
-interface FixedRetryPolicySpec {
-  readonly kind: "fixed";
-  /** Total attempts including the first execution. Must be >= 1. */
-  readonly maxAttempts: number;
-  readonly delayMs: number;
-}
-interface ExponentialRetryPolicySpec {
-  readonly kind: "exponential";
-  /** Total attempts including the first execution. Must be >= 1. */
-  readonly maxAttempts: number;
-  readonly initialDelayMs: number;
-  readonly multiplier: number;
-  readonly maxDelayMs?: number;
-  /** When true, each delay is multiplied by a random factor in [1, 1.2). */
-  readonly jitter?: boolean;
+type CredentialType<TPublicConfig extends CredentialJsonRecord = CredentialJsonRecord, TMaterial extends CredentialJsonRecord = CredentialJsonRecord, TSession = unknown> = Readonly<{
+  definition: CredentialTypeDefinition;
+  createSession: CredentialSessionFactory<TPublicConfig, TMaterial, TSession>;
+  test: CredentialHealthTester<TPublicConfig, TMaterial>;
+}>;
+/**
+ * Credential type with unspecified generics — used for `CodemationConfig.credentialTypes`, the host registry,
+ * and anywhere a concrete `CredentialType<YourPublic, YourMaterial, YourSession>` is placed in a heterogeneous list.
+ * Using `any` here avoids unsafe `as` casts while keeping typed `satisfies CredentialType<…>` definitions.
+ */
+type AnyCredentialType = CredentialType<any, any, unknown>;
+interface CredentialSessionService {
+  getSession<TSession = unknown>(args: Readonly<{
+    workflowId: WorkflowId;
+    nodeId: NodeId;
+    slotKey: string;
+  }>): Promise<TSession>;
 }
 //#endregion
-//#region ../core/src/contracts/telemetryTypes.d.ts
-type TelemetryAttributePrimitive = string | number | boolean | null;
-interface TelemetryAttributes {
-  readonly [key: string]: TelemetryAttributePrimitive | undefined;
-}
-interface TelemetryMetricRecord {
-  readonly name: string;
-  readonly value: number;
-  readonly unit?: string;
-  readonly attributes?: TelemetryAttributes;
+//#region ../core/src/triggers/polling/PollingTriggerDedupWindow.d.ts
+/**
+ * Merges processed-ID windows for polling triggers, capping the total to avoid unbounded growth.
+ * Plugin code receives an instance of this class via {@link PollingTriggerHandle.dedup}.
+ */
+declare class PollingTriggerDedupWindow {
+  static readonly defaultCapN = 2000;
+  merge(previous: ReadonlyArray<string>, incoming: ReadonlyArray<string>, capN?: number): ReadonlyArray<string>;
 }
-interface TelemetrySpanEventRecord {
-  readonly name: string;
-  readonly occurredAt?: Date;
-  readonly attributes?: TelemetryAttributes;
+//#endregion
+//#region ../core/src/contracts/runTypes.d.ts
+/**
+ * Test-suite linkage for a run. When set, this run was started by a TestSuiteOrchestrator
+ * as one test case inside a TestSuiteRun. The `IsTestRun` node and host-side persisters key
+ * off the presence of this field. Subworkflow runs inherit it from their parent run.
+ */
+interface RunTestContext {
+  readonly testSuiteRunId: string;
+  readonly testCaseIndex: number;
+  /**
+   * Optional human-friendly label for this test case (e.g. an email subject when fixtures
+   * are loaded from a mailbox). Resolved per item by `TestTrigger.caseLabel(item)` if set,
+   * persisted on `Run.test_case_label` so the Tests-tab tree-table can show "RFQ for batch 14"
+   * instead of "run_1777755971399_bbb86beac1396".
+   */
+  readonly testCaseLabel?: string;
 }
-interface TelemetryArtifactAttachment {
-  readonly kind: string;
-  readonly contentType: string;
-  readonly previewText?: string;
-  readonly previewJson?: JsonValue;
-  readonly payloadText?: string;
-  readonly payloadJson?: JsonValue;
-  readonly bytes?: number;
-  readonly truncated?: boolean;
-  readonly expiresAt?: Date;
-}
-interface TelemetryArtifactReference {
-  readonly artifactId: string;
-  readonly traceId?: string;
-  readonly spanId?: string;
-}
-interface TelemetrySpanEnd {
-  readonly status?: "ok" | "error";
-  readonly statusMessage?: string;
-  readonly endedAt?: Date;
-  readonly attributes?: TelemetryAttributes;
-}
-interface TelemetryChildSpanStart {
-  readonly name: string;
-  readonly kind?: "internal" | "client";
-  readonly startedAt?: Date;
-  readonly attributes?: TelemetryAttributes;
-}
-interface TelemetryScope {
-  readonly traceId?: string;
-  readonly spanId?: string;
-  readonly costTracking?: CostTrackingTelemetry;
-  addSpanEvent(args: TelemetrySpanEventRecord): Promise<void> | void;
-  recordMetric(args: TelemetryMetricRecord): Promise<void> | void;
-  attachArtifact(args: TelemetryArtifactAttachment): Promise<TelemetryArtifactReference> | TelemetryArtifactReference;
-}
-interface TelemetrySpanScope extends TelemetryScope {
-  readonly traceId: string;
-  readonly spanId: string;
-  end(args?: TelemetrySpanEnd): Promise<void> | void;
-}
-interface NodeExecutionTelemetry extends ExecutionTelemetry, TelemetrySpanScope {
-  startChildSpan(args: TelemetryChildSpanStart): TelemetrySpanScope;
-}
-interface ExecutionTelemetry extends TelemetryScope {
-  readonly traceId: string;
-  readonly spanId: string;
-  forNode(args: Readonly<{
-    nodeId: NodeId;
-    activationId: NodeActivationId;
-  }>): NodeExecutionTelemetry;
-}
-//#endregion
-//#region ../core/src/contracts/CostTrackingTelemetryContract.d.ts
-type CostTrackingComponent = "chat" | "ocr" | "rag";
-interface CostTrackingUsageRecord {
-  readonly component: CostTrackingComponent;
-  readonly provider: string;
-  readonly operation: string;
-  readonly pricingKey: string;
-  readonly usageUnit: string;
-  readonly quantity: number;
-  readonly modelName?: string;
-  readonly attributes?: TelemetryAttributes;
-}
-interface CostTrackingPriceQuote {
-  readonly currency: string;
-  readonly currencyScale: number;
-  readonly estimatedAmountMinor: number;
-  readonly estimateKind: "catalog";
-}
-interface CostTrackingTelemetry {
-  captureUsage(args: CostTrackingUsageRecord): Promise<CostTrackingPriceQuote | undefined>;
-  forScope(scope: TelemetryScope): CostTrackingTelemetry;
-}
-//#endregion
-//#region ../core/src/contracts/runTypes.d.ts
-type NodeInputsByPort = Readonly<Record<InputPortKey, Items>>;
-type NodeExecutionStatus = "pending" | "queued" | "running" | "completed" | "failed" | "skipped";
-interface NodeExecutionError {
-  message: string;
-  name?: string;
-  stack?: string;
-  details?: JsonValue;
+type NodeInputsByPort = Readonly<Record<InputPortKey, Items>>;
+type NodeExecutionStatus = "pending" | "queued" | "running" | "completed" | "failed" | "skipped";
+interface NodeExecutionError {
+  message: string;
+  name?: string;
+  stack?: string;
+  details?: JsonValue;
 }
 /** Stable id for a single connection invocation row in {@link ConnectionInvocationRecord}. */
 type ConnectionInvocationId = string;
@@ -194,6 +247,9 @@ type ConnectionInvocationAppendArgs = Readonly<{
   queuedAt?: string;
   startedAt?: string;
   finishedAt?: string;
+  iterationId?: NodeIterationId;
+  itemIndex?: number;
+  parentInvocationId?: ConnectionInvocationId;
 }>;
 interface PendingNodeExecution {
   runId: RunId;
@@ -229,291 +285,85 @@ type RunResult = {
   };
 };
 //#endregion
-//#region ../core/src/contracts/webhookTypes.d.ts
-type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
-interface WebhookControlSignal {
-  readonly __webhookControl: true;
-  readonly kind: "respondNow" | "respondNowAndContinue";
-  readonly responseItems: Items;
-  readonly continueItems?: Items;
+//#region ../core/src/contracts/retryPolicySpec.types.d.ts
+/**
+ * In-process retry policy for runnable nodes. Serialized configs use the same
+ * `kind` discriminator (`JSON.stringify` / persisted workflows).
+ *
+ * `maxAttempts` is the total number of tries including the first (e.g. 3 means up to 2 delays after failures).
+ */
+type RetryPolicySpec = NoneRetryPolicySpec | FixedRetryPolicySpec | ExponentialRetryPolicySpec;
+interface NoneRetryPolicySpec {
+  readonly kind: "none";
 }
-interface TriggerInstanceId {
-  workflowId: WorkflowId;
-  nodeId: NodeId;
+interface FixedRetryPolicySpec {
+  readonly kind: "fixed";
+  /** Total attempts including the first execution. Must be >= 1. */
+  readonly maxAttempts: number;
+  readonly delayMs: number;
 }
-//#endregion
-//#region ../core/src/workflow/dsl/workflowBuilderTypes.d.ts
-type AnyRunnableNodeConfig = RunnableNodeConfig<any, any>;
-type AnyTriggerNodeConfig = TriggerNodeConfig<any>;
-type ValidStepSequence<TCurrentJson, TSteps extends ReadonlyArray<AnyRunnableNodeConfig>> = TSteps extends readonly [] ? readonly [] : TSteps extends readonly [infer TFirst, ...infer TRest] ? TFirst extends RunnableNodeConfig<TCurrentJson, infer TNextJson> ? TRest extends ReadonlyArray<AnyRunnableNodeConfig> ? readonly [TFirst, ...ValidStepSequence<TNextJson, TRest>] : never : never : TSteps;
-type StepSequenceOutput<TCurrentJson, TSteps extends ReadonlyArray<AnyRunnableNodeConfig> | undefined> = TSteps extends ReadonlyArray<AnyRunnableNodeConfig> ? TSteps extends readonly [] ? TCurrentJson : TSteps extends readonly [infer TFirst, ...infer TRest] ? TFirst extends RunnableNodeConfig<TCurrentJson, infer TNextJson> ? TRest extends ReadonlyArray<AnyRunnableNodeConfig> ? StepSequenceOutput<TNextJson, TRest> : never : never : TCurrentJson : TCurrentJson;
-type TypesMatch<TLeft, TRight> = [TLeft] extends [TRight] ? ([TRight] extends [TLeft] ? true : false) : false;
-type BranchOutputGuard<TCurrentJson, TTrueSteps extends ReadonlyArray<AnyRunnableNodeConfig> | undefined, TFalseSteps extends ReadonlyArray<AnyRunnableNodeConfig> | undefined> = TypesMatch<StepSequenceOutput<TCurrentJson, TTrueSteps>, StepSequenceOutput<TCurrentJson, TFalseSteps>> extends true ? unknown : never;
-type BranchStepsArg<TCurrentJson, TSteps extends ReadonlyArray<AnyRunnableNodeConfig>> = TSteps & ValidStepSequence<TCurrentJson, TSteps>;
-type BranchMoreArgs<TCurrentJson, TFirstStep extends RunnableNodeConfig<TCurrentJson, any>, TRestSteps extends ReadonlyArray<AnyRunnableNodeConfig>> = TRestSteps & ValidStepSequence<RunnableNodeOutputJson<TFirstStep>, TRestSteps>;
-type BooleanWhenOverloads<TCurrentJson, TReturn> = {
-  <TSteps extends ReadonlyArray<AnyRunnableNodeConfig>>(branch: boolean, steps: BranchStepsArg<TCurrentJson, TSteps>): TReturn;
-  <TFirstStep extends RunnableNodeConfig<TCurrentJson, any>, TRestSteps extends ReadonlyArray<AnyRunnableNodeConfig>>(branch: boolean, step: TFirstStep, ...more: BranchMoreArgs<TCurrentJson, TFirstStep, TRestSteps>): TReturn;
-};
-//#endregion
-//#region ../core/src/workflow/dsl/WhenBuilder.d.ts
-declare class WhenBuilder<TCurrentJson> {
-  private readonly wf;
-  private readonly from;
-  private readonly branchPort;
-  constructor(wf: WorkflowBuilder, from: NodeRef, branchPort: OutputPortKey);
-  addBranch<TSteps extends ReadonlyArray<AnyRunnableNodeConfig>>(steps: TSteps & ValidStepSequence<TCurrentJson, TSteps>): this;
-  readonly when: BooleanWhenOverloads<TCurrentJson, WhenBuilder<TCurrentJson>>;
-  build(): WorkflowDefinition;
+interface ExponentialRetryPolicySpec {
+  readonly kind: "exponential";
+  /** Total attempts including the first execution. Must be >= 1. */
+  readonly maxAttempts: number;
+  readonly initialDelayMs: number;
+  readonly multiplier: number;
+  readonly maxDelayMs?: number;
+  /** When true, each delay is multiplied by a random factor in [1, 1.2). */
+  readonly jitter?: boolean;
 }
 //#endregion
-//#region ../core/src/workflow/dsl/ChainCursorResolver.d.ts
-type ChainCursorEndpoint = Readonly<{
-  node: NodeRef;
-  output: OutputPortKey;
-  inputPortHint?: InputPortKey;
+//#region ../core/src/contracts/workflowTypes.d.ts
+type NodeIdRef<TJson = unknown> = NodeId & Readonly<{
+  __codemationNodeJson?: TJson;
 }>;
-type ChainCursorWhenOverloads<TCurrentJson> = BooleanWhenOverloads<TCurrentJson, WhenBuilder<TCurrentJson>> & {
-  <TTrueSteps extends ReadonlyArray<AnyRunnableNodeConfig> | undefined, TFalseSteps extends ReadonlyArray<AnyRunnableNodeConfig> | undefined>(branches: Readonly<{
-    true?: TTrueSteps extends ReadonlyArray<AnyRunnableNodeConfig> ? BranchStepsArg<TCurrentJson, TTrueSteps> : never;
-    false?: TFalseSteps extends ReadonlyArray<AnyRunnableNodeConfig> ? BranchStepsArg<TCurrentJson, TFalseSteps> : never;
-  }> & BranchOutputGuard<TCurrentJson, TTrueSteps, TFalseSteps>): ChainCursor<StepSequenceOutput<TCurrentJson, TTrueSteps>>;
-};
-declare class ChainCursor<TCurrentJson> {
-  private readonly wf;
-  private readonly endpoints;
-  constructor(wf: WorkflowBuilder, endpoints: ReadonlyArray<ChainCursorEndpoint>);
-  then<TOutputJson$1, TConfig extends RunnableNodeConfig<TCurrentJson, TOutputJson$1>>(config: TConfig): ChainCursor<RunnableNodeOutputJson<TConfig>>;
-  thenIntoInputHints<TOutputJson$1, TConfig extends RunnableNodeConfig<any, TOutputJson$1>>(config: TConfig): ChainCursor<RunnableNodeOutputJson<TConfig>>;
-  readonly when: ChainCursorWhenOverloads<TCurrentJson>;
-  route<TNextJson$1>(branches: Readonly<Record<OutputPortKey, (branch: ChainCursor<TCurrentJson>) => ChainCursor<TNextJson$1> | undefined>>): ChainCursor<TNextJson$1>;
-  build(): WorkflowDefinition;
-  private resolveSharedInputPortHint;
-}
-//#endregion
-//#region ../core/src/workflow/dsl/WorkflowBuilder.d.ts
-declare class WorkflowBuilder {
-  private readonly meta;
-  private readonly options?;
-  private readonly nodes;
-  private readonly edges;
-  private seq;
-  constructor(meta: {
-    id: WorkflowId;
-    name: string;
-  }, options?: Readonly<Record<string, never>> | undefined);
-  private add;
-  private connect;
-  trigger<TConfig extends AnyTriggerNodeConfig>(config: TConfig): ChainCursor<TriggerNodeOutputJson<TConfig>>;
-  start<TConfig extends AnyRunnableNodeConfig>(config: TConfig): ChainCursor<RunnableNodeOutputJson<TConfig>>;
-  build(): WorkflowDefinition;
-}
-//#endregion
-//#region ../core/src/contracts/runtimeTypes.d.ts
-interface WorkflowRunnerService {
-  runById(args: {
-    workflowId: WorkflowId;
-    startAt?: NodeId;
-    items: Items;
-    parent?: ParentExecutionRef;
-  }): Promise<RunResult>;
-}
-interface NodeResolver {
-  resolve<T>(token: TypeToken<T>): T;
+type NodeKind = "trigger" | "node";
+type JsonPrimitive = string | number | boolean | null;
+interface JsonObject {
+  readonly [key: string]: JsonValue;
 }
-interface NodeExecutionStatePublisher {
-  markQueued(args: {
-    nodeId: NodeId;
-    activationId?: NodeActivationId;
-    inputsByPort?: NodeInputsByPort;
-  }): Promise<void>;
-  markRunning(args: {
-    nodeId: NodeId;
-    activationId?: NodeActivationId;
-    inputsByPort?: NodeInputsByPort;
-  }): Promise<void>;
-  markCompleted(args: {
+type JsonValue = JsonPrimitive | JsonObject | JsonArray;
+type JsonArray = ReadonlyArray<JsonValue>;
+/** JSON value that is not a top-level array (nested arrays inside objects are allowed). */
+type JsonNonArray = JsonPrimitive | JsonObject;
+interface Edge {
+  from: {
     nodeId: NodeId;
-    activationId?: NodeActivationId;
-    inputsByPort?: NodeInputsByPort;
-    outputs?: NodeOutputs;
-  }): Promise<void>;
-  markFailed(args: {
+    output: OutputPortKey;
+  };
+  to: {
     nodeId: NodeId;
-    activationId?: NodeActivationId;
-    inputsByPort?: NodeInputsByPort;
-    error: Error;
-  }): Promise<void>;
-  appendConnectionInvocation(args: ConnectionInvocationAppendArgs): Promise<void>;
+    input: InputPortKey;
+  };
 }
-type BinaryBody = ReadableStream<Uint8Array> | AsyncIterable<Uint8Array> | Uint8Array | ArrayBuffer;
-interface BinaryStorageReadResult {
-  body: ReadableStream<Uint8Array>;
-  size?: number;
+/**
+ * Named connection from a parent node to child nodes that exist in {@link WorkflowDefinition.nodes}
+ * but are not traversed by the main execution graph. Parents are commonly executable nodes, but may
+ * also be connection-owned nodes for recursive agent attachments.
+ */
+interface WorkflowNodeConnection {
+  readonly parentNodeId: NodeId;
+  readonly connectionName: NodeConnectionName;
+  readonly childNodeIds: ReadonlyArray<NodeId>;
 }
-interface BinaryAttachmentCreateRequest {
+interface WorkflowDefinition {
+  id: WorkflowId;
   name: string;
-  body: BinaryBody;
-  mimeType: string;
-  filename?: string;
-  previewKind?: BinaryAttachment["previewKind"];
-}
-interface NodeBinaryAttachmentService extends ExecutionBinaryService {
-  attach(args: BinaryAttachmentCreateRequest): Promise<BinaryAttachment>;
-  withAttachment<TJson>(item: Item<TJson>, name: string, attachment: BinaryAttachment): Item<TJson>;
-}
-interface ExecutionBinaryService {
-  forNode(args: {
-    nodeId: NodeId;
-    activationId: NodeActivationId;
-  }): NodeBinaryAttachmentService;
-  openReadStream(attachment: BinaryAttachment): Promise<BinaryStorageReadResult | undefined>;
-}
-interface ExecutionContext {
-  runId: RunId;
-  workflowId: WorkflowId;
-  parent?: ParentExecutionRef;
-  /** This run's subworkflow depth (0 = root). */
-  subworkflowDepth: number;
-  /** Effective activation budget cap for this run (after policy merge). */
-  engineMaxNodeActivations: number;
-  /** Effective subworkflow nesting cap for this run (after policy merge). */
-  engineMaxSubworkflowDepth: number;
-  now: () => Date;
-  data: RunDataSnapshot;
-  nodeState?: NodeExecutionStatePublisher;
-  telemetry: ExecutionTelemetry;
-  binary: ExecutionBinaryService;
-  getCredential<TSession = unknown>(slotKey: string): Promise<TSession>;
-}
-interface NodeExecutionContext<TConfig extends NodeConfigBase = NodeConfigBase> extends ExecutionContext {
-  nodeId: NodeId;
-  activationId: NodeActivationId;
-  config: TConfig;
-  telemetry: NodeExecutionTelemetry;
-  binary: NodeBinaryAttachmentService;
-}
-interface TriggerSetupContext<TConfig extends TriggerNodeConfig<any, any> = TriggerNodeConfig<any, any>, TSetupState$1 extends JsonValue | undefined = TriggerNodeSetupState<TConfig>> extends ExecutionContext {
-  trigger: TriggerInstanceId;
-  config: TConfig;
-  previousState: TSetupState$1;
-  registerCleanup(cleanup: TriggerCleanupHandle): void;
-  emit(items: Items): Promise<void>;
-}
-interface TriggerTestItemsContext<TConfig extends TriggerNodeConfig<any, any> = TriggerNodeConfig<any, any>, TSetupState$1 extends JsonValue | undefined = TriggerNodeSetupState<TConfig>> extends ExecutionContext {
-  trigger: TriggerInstanceId;
-  nodeId: NodeId;
-  config: TConfig;
-  previousState: TSetupState$1;
-}
-interface TriggerCleanupHandle {
-  stop(): Promise<void> | void;
-}
-/**
- * Per-item runnable node: return JSON, an array to fan-out on `main`, an explicit `Item`, or {@link emitPorts}
- * for multi-port emission. Engine applies `inputSchema.parse(item.json)` and passes the result as `args.input`
- * (wire `item.json` is unchanged). Transform helpers may opt into binary preservation, while routers and
- * pass-through nodes should return explicit items when they need to preserve full item state.
- */
-interface RunnableNodeExecuteArgs<TConfig extends RunnableNodeConfig<any, any> = RunnableNodeConfig<any, any>, TInputJson$1 = unknown> {
-  readonly input: TInputJson$1;
-  readonly item: Item;
-  readonly itemIndex: number;
-  readonly items: Items;
-  readonly ctx: NodeExecutionContext<TConfig>;
-}
-interface RunnableNode<TConfig extends RunnableNodeConfig<any, any> = RunnableNodeConfig<any, any>, TInputJson$1 = unknown, _TOutputJson = unknown> {
-  readonly kind: "node";
-  /**
-   * Declared output ports (e.g. `["main"]`).
-   *
-   * Prefer describing dynamic router ports (Switch) and fixed multi-ports (If true/false)
-   * via {@link NodeConfigBase.declaredOutputPorts}. Engine defaults to `["main"]` when omitted.
-   */
-  readonly outputPorts?: ReadonlyArray<OutputPortKey>;
-  /** When omitted, engine uses {@link RunnableNodeConfig.inputSchema} or `z.unknown()`. */
-  readonly inputSchema?: ZodType<TInputJson$1>;
-  execute(args: RunnableNodeExecuteArgs<TConfig, TInputJson$1>): Promise<unknown> | unknown;
-}
-interface MultiInputNode<TConfig extends NodeConfigBase = NodeConfigBase> {
-  kind: "node";
-  /**
-   * Declared output ports (typically `["main"]`).
-   *
-   * Prefer describing ports for authoring/canvas via {@link NodeConfigBase.declaredOutputPorts}.
-   * Engine defaults to `["main"]` when omitted.
-   */
-  outputPorts?: ReadonlyArray<OutputPortKey>;
-  executeMulti(inputsByPort: NodeInputsByPort, ctx: NodeExecutionContext<TConfig>): Promise<NodeOutputs>;
-}
-type TriggerSetupStateFor<TConfig extends TriggerNodeConfig<any, any>> = TriggerNodeSetupState<TConfig>;
-interface TriggerNode<TConfig extends TriggerNodeConfig<any, any> = TriggerNodeConfig<any, any>> {
-  kind: "trigger";
-  outputPorts: readonly ["main"];
-  setup(ctx: TriggerSetupContext<TConfig>): Promise<TriggerSetupStateFor<TConfig>>;
-  execute(items: Items, ctx: NodeExecutionContext<TConfig>): Promise<NodeOutputs>;
-}
-interface TestableTriggerNode<TConfig extends TriggerNodeConfig<any, any> = TriggerNodeConfig<any, any>> extends TriggerNode<TConfig> {
-  getTestItems(ctx: TriggerTestItemsContext<TConfig>): Promise<Items>;
-}
-type ExecutableTriggerNode<TConfig extends TriggerNodeConfig<any, any> = TriggerNodeConfig<any, any>> = TriggerNode<TConfig>;
-//#endregion
-//#region ../core/src/contracts/workflowTypes.d.ts
-type WorkflowId = string;
-type NodeId = string;
-type NodeIdRef<TJson = unknown> = NodeId & Readonly<{
-  __codemationNodeJson?: TJson;
-}>;
-type OutputPortKey = string;
-type InputPortKey = string;
-type NodeKind = "trigger" | "node";
-type JsonPrimitive = string | number | boolean | null;
-interface JsonObject {
-  readonly [key: string]: JsonValue;
-}
-type JsonValue = JsonPrimitive | JsonObject | JsonArray;
-type JsonArray = ReadonlyArray<JsonValue>;
-/** JSON value that is not a top-level array (nested arrays inside objects are allowed). */
-type JsonNonArray = JsonPrimitive | JsonObject;
-interface Edge {
-  from: {
-    nodeId: NodeId;
-    output: OutputPortKey;
-  };
-  to: {
-    nodeId: NodeId;
-    input: InputPortKey;
-  };
-}
-type NodeConnectionName = string;
-/**
- * Named connection from a parent node to child nodes that exist in {@link WorkflowDefinition.nodes}
- * but are not traversed by the main execution graph. Parents are commonly executable nodes, but may
- * also be connection-owned nodes for recursive agent attachments.
- */
-interface WorkflowNodeConnection {
-  readonly parentNodeId: NodeId;
-  readonly connectionName: NodeConnectionName;
-  readonly childNodeIds: ReadonlyArray<NodeId>;
-}
-interface WorkflowDefinition {
-  id: WorkflowId;
-  name: string;
-  nodes: NodeDefinition[];
-  edges: Edge[];
-  /**
-   * Optional metadata: which nodes are connection-owned children (e.g. AI agent `llm` / `tools` slots).
-   * When omitted, all nodes in {@link nodes} are treated as executable for topology.
-   */
-  readonly connections?: ReadonlyArray<WorkflowNodeConnection>;
-  /** Directory + file-stem path under a workflow discovery root (for UI grouping only). */
-  discoveryPathSegments?: readonly string[];
-  /** Retention for run JSON and binaries (seconds). Host/env may supply defaults when omitted. */
-  readonly prunePolicy?: WorkflowPrunePolicySpec;
-  /** Whether to keep run data after completion. Host/env may supply defaults when omitted. */
-  readonly storagePolicy?: WorkflowStoragePolicySpec;
-  /** Invoked after a node fails permanently (retries exhausted) and node error handler did not recover. */
-  readonly workflowErrorHandler?: WorkflowErrorHandlerSpec;
+  nodes: NodeDefinition[];
+  edges: Edge[];
+  /**
+   * Optional metadata: which nodes are connection-owned children (e.g. AI agent `llm` / `tools` slots).
+   * When omitted, all nodes in {@link nodes} are treated as executable for topology.
+   */
+  readonly connections?: ReadonlyArray<WorkflowNodeConnection>;
+  /** Directory + file-stem path under a workflow discovery root (for UI grouping only). */
+  discoveryPathSegments?: readonly string[];
+  /** Retention for run JSON and binaries (seconds). Host/env may supply defaults when omitted. */
+  readonly prunePolicy?: WorkflowPrunePolicySpec;
+  /** Whether to keep run data after completion. Host/env may supply defaults when omitted. */
+  readonly storagePolicy?: WorkflowStoragePolicySpec;
+  /** Invoked after a node fails permanently (retries exhausted) and node error handler did not recover. */
+  readonly workflowErrorHandler?: WorkflowErrorHandlerSpec;
 }
 interface NodeConfigBase {
   readonly kind: NodeKind;
@@ -542,6 +392,14 @@ interface NodeConfigBase {
   readonly declaredOutputPorts?: ReadonlyArray<OutputPortKey>;
   readonly declaredInputPorts?: ReadonlyArray<InputPortKey>;
   getCredentialRequirements?(): ReadonlyArray<CredentialRequirement>;
+  /**
+   * Marker: this node emits {@link import("./assertionTypes").AssertionResult}-shaped items on its
+   * `main` port. The TestSuiteOrchestrator (and host-side TestAssertionPersister) listen for
+   * `nodeCompleted` events from nodes with this flag set, and persist their output items as
+   * TestAssertion records (only when the run carries a `testContext`). Set on assertion node
+   * configs (e.g. `AssertionNodeConfig`, `StringEqualsAssertionNodeConfig`).
+   */
+  readonly emitsAssertions?: true;
 }
 declare const runnableNodeInputType: unique symbol;
 declare const runnableNodeOutputType: unique symbol;
@@ -571,6 +429,12 @@ interface TriggerNodeConfig<TOutputJson$1 = unknown, TSetupState$1 extends JsonV
   readonly kind: "trigger";
   readonly [triggerNodeOutputType]?: TOutputJson$1;
   readonly [triggerNodeSetupStateType]?: TSetupState$1;
+  /**
+   * Distinguishes triggers driven by the live activation policy (webhooks, cron, polling) from
+   * triggers driven only by the {@link TestSuiteOrchestrator}. `WorkflowActivation` skips
+   * `"test"` triggers; the orchestrator skips `"live"` triggers. Defaults to `"live"` when omitted.
+   */
+  readonly triggerKind?: "live" | "test";
 }
 type RunnableNodeInputJson<TConfig extends RunnableNodeConfig<any, any>> = TConfig extends RunnableNodeConfig<infer TInputJson, any> ? TInputJson : never;
 type RunnableNodeOutputJson<TConfig extends RunnableNodeConfig<any, any>> = TConfig extends RunnableNodeConfig<any, infer TOutputJson> ? TOutputJson : never;
@@ -620,6 +484,12 @@ type Items<TJson = unknown> = ReadonlyArray<Item<TJson>>;
 type NodeOutputs = Partial<Record<OutputPortKey, Items>>;
 type RunId = string;
 type NodeActivationId = string;
+/**
+ * One per-item iteration of a runnable node's execute loop. Refines `NodeActivationId` for
+ * per-item connection invocations and telemetry. Undefined when the executing node is a batch
+ * node or trigger that does not iterate items.
+ */
+type NodeIterationId = string;
 interface ParentExecutionRef {
   runId: RunId;
   workflowId: WorkflowId;
@@ -630,12 +500,21 @@ interface ParentExecutionRef {
   engineMaxNodeActivations?: number;
   /** Effective max subworkflow depth from the parent run (propagated to child policy merge). */
   engineMaxSubworkflowDepth?: number;
+  /**
+   * Test-suite linkage inherited by the child subworkflow run. Set by whichever node
+   * spawns the subworkflow when its own `ctx.testContext` is present, so assertions
+   * emitted inside a subworkflow land under the correct parent test case.
+   */
+  testContext?: RunTestContext;
 }
 interface RunDataSnapshot {
   getOutputs(nodeId: NodeId): NodeOutputs | undefined;
   getOutputItems<TJson = unknown>(nodeId: NodeId | NodeIdRef<TJson>, output?: OutputPortKey): Items<TJson>;
   getOutputItem<TJson = unknown>(nodeId: NodeId | NodeIdRef<TJson>, itemIndex: number, output?: OutputPortKey): Item<TJson> | undefined;
 }
+interface ActivationIdFactory {
+  makeActivationId(): NodeActivationId;
+}
 type UpstreamRefPlaceholder = `$${number}`;
 /** Whether to persist run execution data after the workflow finishes. */
 type WorkflowStoragePolicyMode = "ALL" | "SUCCESS" | "ERROR" | "NEVER";
@@ -683,155 +562,564 @@ interface NodeErrorHandler {
 }
 type NodeErrorHandlerSpec = TypeToken<NodeErrorHandler> | NodeErrorHandler;
 //#endregion
-//#region ../core/src/contracts/credentialTypes.d.ts
-type CredentialTypeId = string;
-type CredentialInstanceId = string;
-type CredentialMaterialSourceKind = "db" | "env" | "code";
-type CredentialSetupStatus = "draft" | "ready";
-type CredentialHealthStatus = "unknown" | "healthy" | "failing";
-type CredentialFieldSchema = Readonly<{
-  key: string;
-  label: string;
-  type: "string" | "password" | "textarea" | "json" | "boolean";
-  required?: true;
-  order?: number;
+//#region ../core/src/contracts/testTriggerTypes.d.ts
+/**
+ * Identifier minted by the host (or in-memory test runner) for one execution of a test suite.
+ * One TestSuiteRun produces N child workflow runs, one per item yielded by `generateItems`.
+ */
+type TestSuiteRunId = string;
+/**
+ * Setup context passed to a {@link TestTriggerNodeConfig.generateItems} callback. Distinct from
+ * {@link import("./runtimeTypes").TriggerSetupContext} on purpose: test triggers are not
+ * activated by the live trigger lifecycle (webhooks, cron, polling) and never call `emit` —
+ * the orchestrator pulls from the iterable they return and dispatches one run per item.
+ */
+interface TestTriggerSetupContext<TConfig extends TestTriggerNodeConfig<unknown> = TestTriggerNodeConfig<unknown>> {
+  readonly workflowId: WorkflowId;
+  readonly nodeId: NodeId;
+  readonly config: TConfig;
+  readonly testSuiteRunId: TestSuiteRunId;
   /**
-   * Where this field appears in the credential dialog. Use `"advanced"` for optional or
-   * power-user fields; they render inside a collapsible section (see `CredentialTypeDefinition.advancedSection`).
-   * Defaults to `"default"` when omitted.
+   * Resolves a credential session for a slot declared on this trigger's
+   * {@link import("./workflowTypes").NodeConfigBase.getCredentialRequirements}. Same contract as
+   * {@link import("./runtimeTypes").ExecutionContext.getCredential}.
    */
-  visibility?: "default" | "advanced";
-  placeholder?: string;
-  helpText?: string;
-  /** When set, host resolves this field from process.env at runtime; env wins over stored values. */
-  envVarName?: string;
+  getCredential<TSession = unknown>(slotKey: string): Promise<TSession>;
+  /** AbortSignal raised when the suite is cancelled — long-running pulls should bail out. */
+  readonly signal: AbortSignal;
+}
+/**
+ * A trigger config that emits **test cases**. Each item yielded by {@link generateItems}
+ * becomes one workflow run (with `executionOptions.testContext` set), so 10 yielded items
+ * → 10 runs marked under the same TestSuiteRun.
+ *
+ * The trigger is otherwise a normal {@link TriggerNodeConfig} (so the canvas treats it like
+ * any other trigger), but its `triggerKind` is `"test"` so the live activation policy skips it.
+ */
+interface TestTriggerNodeConfig<TOutputJson$1 = unknown> extends TriggerNodeConfig<TOutputJson$1, undefined> {
+  readonly triggerKind: "test";
   /**
-   * When set, the dialog shows a copy action for this exact string (e.g. a static OAuth redirect URI
-   * pattern or documentation URL). Do not use for secret values.
+   * Author-supplied async iterable of items, evaluated lazily. Implementations may fetch from
+   * credentialed APIs, read fixture files, or yield hard-coded items. The orchestrator iterates
+   * and dispatches one run per item, with concurrency capped by {@link concurrency} (default 4).
    */
-  copyValue?: string;
-  /** Accessible label for the copy control (default: Copy). */
-  copyButtonLabel?: string;
-}>;
-type CredentialRequirement = Readonly<{
-  slotKey: string;
-  label: string;
-  acceptedTypes: ReadonlyArray<CredentialTypeId>;
-  optional?: true;
-  helpText?: string;
-  helpUrl?: string;
-}>;
-type CredentialHealth = Readonly<{
-  status: CredentialHealthStatus;
-  message?: string;
-  testedAt?: string;
-  expiresAt?: string;
-  details?: Readonly<Record<string, unknown>>;
-}>;
-type OAuth2ProviderFromPublicConfig = Readonly<{
-  authorizeUrlFieldKey: string;
-  tokenUrlFieldKey: string;
-  userInfoUrlFieldKey?: string;
-}>;
-type CredentialOAuth2ScopesFromPublicConfig = Readonly<{
-  presetFieldKey: string;
-  presetScopes: Readonly<Record<string, ReadonlyArray<string>>>;
-  customPresetKey?: string;
-  customScopesFieldKey?: string;
-}>;
-type CredentialOAuth2AuthDefinition = Readonly<{
-  kind: "oauth2";
-  providerId: string;
-  scopes: ReadonlyArray<string>;
-  scopesFromPublicConfig?: CredentialOAuth2ScopesFromPublicConfig;
-  clientIdFieldKey?: string;
-  clientSecretFieldKey?: string;
-} | {
-  kind: "oauth2";
-  providerFromPublicConfig: OAuth2ProviderFromPublicConfig;
-  scopes: ReadonlyArray<string>;
-  scopesFromPublicConfig?: CredentialOAuth2ScopesFromPublicConfig;
-  clientIdFieldKey?: string;
-  clientSecretFieldKey?: string;
-}>;
-type CredentialAuthDefinition = CredentialOAuth2AuthDefinition;
-type CredentialAdvancedSectionPresentation = Readonly<{
-  /** Collapsible section title (default: "Advanced"). */
-  title?: string;
-  /** Optional short helper text shown inside the section (above the fields). */
-  description?: string;
-  /** When true, the advanced section starts expanded. Default: false (collapsed). */
-  defaultOpen?: boolean;
-}>;
-type CredentialTypeDefinition = Readonly<{
-  typeId: CredentialTypeId;
-  displayName: string;
-  description?: string;
-  publicFields?: ReadonlyArray<CredentialFieldSchema>;
-  secretFields?: ReadonlyArray<CredentialFieldSchema>;
+  generateItems(ctx: TestTriggerSetupContext<TestTriggerNodeConfig<TOutputJson$1>>): AsyncIterable<Item<TOutputJson$1>>;
+  /** Per-suite-run cap on simultaneously-executing test cases. Default: 4. */
+  readonly concurrency?: number;
+  /**
+   * Free-form description of where the test cases come from — surfaced in the node properties
+   * panel and the suite-detail header so authors revisiting the workflow six months later
+   * remember which mailbox / folder / fixture file the cases originate from.
+   *
+   * Example: `"All emails in the Gmail label \"test/triage-fixtures\" — 14 messages as of 2026-05-03."`
+   */
+  readonly description?: string;
+  /**
+   * Resolves a human-readable label for one yielded test case (e.g. email subject). The
+   * orchestrator calls this once per yielded item, persists the result on the run, and the
+   * Tests-tab UI uses it to render the case row instead of the opaque runId. Return
+   * `undefined` to fall back to "Case #N".
+   */
+  caseLabel?(item: Item<TOutputJson$1>): string | undefined;
+}
+//#endregion
+//#region ../core/src/contracts/assertionTypes.d.ts
+/**
+ * One assertion emitted by an assertion-emitting node (a node whose config sets
+ * `emitsAssertions: true`). Each emitted item on `main` carries one of these as `item.json`.
+ *
+ * Pass/fail is derived from `score >= (passThreshold ?? 0.5)` — see {@link deriveAssertionPassed}.
+ * The `errored` marker is for cases where the assertion code itself threw (distinct from
+ * "the assertion was evaluated and the score was low") and is treated as a hard fail in rollups
+ * regardless of `score`.
+ */
+interface AssertionResult {
+  readonly name: string;
+  /** 0..1 score. Source of truth for pass/fail (compared against `passThreshold`). */
+  readonly score: number;
+  /** 0..1 threshold for "passed". When omitted, consumers default to 0.5. */
+  readonly passThreshold?: number;
+  /** True when evaluating the assertion threw — treated as fail regardless of `score`. */
+  readonly errored?: true;
+  /** What the assertion expected. Free-form JSON; UIs render with a JSON viewer. */
+  readonly expected?: JsonValue;
+  /** What the workflow actually produced. */
+  readonly actual?: JsonValue;
+  /** Short human-readable explanation, especially for fails / errors. */
+  readonly message?: string;
+  /** Bag of supplemental fields (e.g. judge prompt, judge raw response, comparison method). */
+  readonly details?: Readonly<Record<string, JsonValue>>;
+}
+//#endregion
+//#region ../core/src/contracts/telemetryTypes.d.ts
+type TelemetryAttributePrimitive = string | number | boolean | null;
+interface TelemetryAttributes {
+  readonly [key: string]: TelemetryAttributePrimitive | undefined;
+}
+interface TelemetryMetricRecord {
+  readonly name: string;
+  readonly value: number;
+  readonly unit?: string;
+  readonly attributes?: TelemetryAttributes;
+}
+interface TelemetrySpanEventRecord {
+  readonly name: string;
+  readonly occurredAt?: Date;
+  readonly attributes?: TelemetryAttributes;
+}
+interface TelemetryArtifactAttachment {
+  readonly kind: string;
+  readonly contentType: string;
+  readonly previewText?: string;
+  readonly previewJson?: JsonValue;
+  readonly payloadText?: string;
+  readonly payloadJson?: JsonValue;
+  readonly bytes?: number;
+  readonly truncated?: boolean;
+  readonly expiresAt?: Date;
+}
+interface TelemetryArtifactReference {
+  readonly artifactId: string;
+  readonly traceId?: string;
+  readonly spanId?: string;
+}
+interface TelemetrySpanEnd {
+  readonly status?: "ok" | "error";
+  readonly statusMessage?: string;
+  readonly endedAt?: Date;
+  readonly attributes?: TelemetryAttributes;
+}
+interface TelemetryChildSpanStart {
+  readonly name: string;
+  readonly kind?: "internal" | "client";
+  readonly startedAt?: Date;
+  readonly attributes?: TelemetryAttributes;
+}
+interface TelemetryScope {
+  readonly traceId?: string;
+  readonly spanId?: string;
+  readonly costTracking?: CostTrackingTelemetry;
+  addSpanEvent(args: TelemetrySpanEventRecord): Promise<void> | void;
+  recordMetric(args: TelemetryMetricRecord): Promise<void> | void;
+  attachArtifact(args: TelemetryArtifactAttachment): Promise<TelemetryArtifactReference> | TelemetryArtifactReference;
+}
+interface TelemetrySpanScope extends TelemetryScope {
+  readonly traceId: string;
+  readonly spanId: string;
+  end(args?: TelemetrySpanEnd): Promise<void> | void;
+  /**
+   * Lift this span into a {@link NodeExecutionTelemetry} scoped to a different (nodeId, activationId).
+   * Children created via the returned telemetry's `startChildSpan` get this span as their parent.
+   *
+   * Used at the sub-agent boundary so that nested runtime telemetry parents under the agent.tool.call
+   * span instead of the orchestrator's node-level span.
+   */
+  asNodeTelemetry(args: Readonly<{
+    nodeId: NodeId;
+    activationId: NodeActivationId;
+  }>): NodeExecutionTelemetry;
+}
+interface NodeExecutionTelemetry extends ExecutionTelemetry, TelemetrySpanScope {
+  startChildSpan(args: TelemetryChildSpanStart): TelemetrySpanScope;
+}
+interface ExecutionTelemetry extends TelemetryScope {
+  readonly traceId: string;
+  readonly spanId: string;
+  forNode(args: Readonly<{
+    nodeId: NodeId;
+    activationId: NodeActivationId;
+  }>): NodeExecutionTelemetry;
+}
+//#endregion
+//#region ../core/src/contracts/CostTrackingTelemetryContract.d.ts
+type CostTrackingComponent = "chat" | "ocr" | "rag";
+interface CostTrackingUsageRecord {
+  readonly component: CostTrackingComponent;
+  readonly provider: string;
+  readonly operation: string;
+  readonly pricingKey: string;
+  readonly usageUnit: string;
+  readonly quantity: number;
+  readonly modelName?: string;
+  readonly attributes?: TelemetryAttributes;
+}
+interface CostTrackingPriceQuote {
+  readonly currency: string;
+  readonly currencyScale: number;
+  readonly estimatedAmountMinor: number;
+  readonly estimateKind: "catalog";
+}
+interface CostTrackingTelemetry {
+  captureUsage(args: CostTrackingUsageRecord): Promise<CostTrackingPriceQuote | undefined>;
+  forScope(scope: TelemetryScope): CostTrackingTelemetry;
+}
+//#endregion
+//#region ../core/src/contracts/webhookTypes.d.ts
+type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+interface WebhookControlSignal {
+  readonly __webhookControl: true;
+  readonly kind: "respondNow" | "respondNowAndContinue";
+  readonly responseItems: Items;
+  readonly continueItems?: Items;
+}
+interface TriggerInstanceId {
+  workflowId: WorkflowId;
+  nodeId: NodeId;
+}
+//#endregion
+//#region ../core/src/contracts/collectionTypes.d.ts
+/**
+ * Represents a typed store for a single collection.
+ * All rows include auto-managed id, created_at, and updated_at fields.
+ */
+interface CollectionStore<TRow extends Record<string, unknown> = Record<string, unknown>> {
+  /**
+   * Insert a new row. id, created_at, and updated_at are auto-populated.
+   */
+  insert(row: TRow): Promise<TRow & {
+    id: string;
+    created_at: Date;
+    updated_at: Date;
+  }>;
+  /**
+   * Get a single row by id.
+   */
+  get(id: string): Promise<(TRow & {
+    id: string;
+    created_at: Date;
+    updated_at: Date;
+  }) | null>;
+  /**
+   * Find a single row matching the provided filter.
+   */
+  findOne(filter: Partial<TRow>): Promise<(TRow & {
+    id: string;
+    created_at: Date;
+    updated_at: Date;
+  }) | null>;
+  /**
+   * List rows with optional pagination and filtering.
+   */
+  list(opts?: {
+    limit?: number;
+    offset?: number;
+    where?: Partial<TRow>;
+  }): Promise<{
+    rows: ReadonlyArray<TRow & {
+      id: string;
+      created_at: Date;
+      updated_at: Date;
+    }>;
+    total: number;
+  }>;
+  /**
+   * Update a row by id with partial data.
+   */
+  update(id: string, patch: Partial<TRow>): Promise<TRow & {
+    id: string;
+    created_at: Date;
+    updated_at: Date;
+  }>;
+  /**
+   * Delete a row by id. Hard delete only (no soft delete).
+   */
+  delete(id: string): Promise<{
+    deleted: boolean;
+  }>;
+}
+/**
+ * Runtime collections context: keyed by collection name.
+ */
+type CollectionsContext = Readonly<Record<string, CollectionStore>>;
+//#endregion
+//#region ../core/src/contracts/emitPorts.d.ts
+declare const EMIT_PORTS_BRAND: unique symbol;
+type PortsEmission = Readonly<{
+  readonly [EMIT_PORTS_BRAND]: true;
+  readonly ports: Readonly<Partial<Record<OutputPortKey, Items | ReadonlyArray<JsonNonArray>>>>;
+}>;
+//#endregion
+//#region ../core/src/workflow/dsl/workflowBuilderTypes.d.ts
+type AnyRunnableNodeConfig = RunnableNodeConfig<any, any>;
+type AnyTriggerNodeConfig = TriggerNodeConfig<any>;
+type ValidStepSequence<TCurrentJson, TSteps extends ReadonlyArray<AnyRunnableNodeConfig>> = TSteps extends readonly [] ? readonly [] : TSteps extends readonly [infer TFirst, ...infer TRest] ? TFirst extends RunnableNodeConfig<TCurrentJson, infer TNextJson> ? TRest extends ReadonlyArray<AnyRunnableNodeConfig> ? readonly [TFirst, ...ValidStepSequence<TNextJson, TRest>] : never : never : TSteps;
+type StepSequenceOutput<TCurrentJson, TSteps extends ReadonlyArray<AnyRunnableNodeConfig> | undefined> = TSteps extends ReadonlyArray<AnyRunnableNodeConfig> ? TSteps extends readonly [] ? TCurrentJson : TSteps extends readonly [infer TFirst, ...infer TRest] ? TFirst extends RunnableNodeConfig<TCurrentJson, infer TNextJson> ? TRest extends ReadonlyArray<AnyRunnableNodeConfig> ? StepSequenceOutput<TNextJson, TRest> : never : never : TCurrentJson : TCurrentJson;
+type TypesMatch<TLeft, TRight> = [TLeft] extends [TRight] ? ([TRight] extends [TLeft] ? true : false) : false;
+type BranchOutputGuard<TCurrentJson, TTrueSteps extends ReadonlyArray<AnyRunnableNodeConfig> | undefined, TFalseSteps extends ReadonlyArray<AnyRunnableNodeConfig> | undefined> = TypesMatch<StepSequenceOutput<TCurrentJson, TTrueSteps>, StepSequenceOutput<TCurrentJson, TFalseSteps>> extends true ? unknown : never;
+type BranchStepsArg<TCurrentJson, TSteps extends ReadonlyArray<AnyRunnableNodeConfig>> = TSteps & ValidStepSequence<TCurrentJson, TSteps>;
+type BranchMoreArgs<TCurrentJson, TFirstStep extends RunnableNodeConfig<TCurrentJson, any>, TRestSteps extends ReadonlyArray<AnyRunnableNodeConfig>> = TRestSteps & ValidStepSequence<RunnableNodeOutputJson<TFirstStep>, TRestSteps>;
+type BooleanWhenOverloads<TCurrentJson, TReturn> = {
+  <TSteps extends ReadonlyArray<AnyRunnableNodeConfig>>(branch: boolean, steps: BranchStepsArg<TCurrentJson, TSteps>): TReturn;
+  <TFirstStep extends RunnableNodeConfig<TCurrentJson, any>, TRestSteps extends ReadonlyArray<AnyRunnableNodeConfig>>(branch: boolean, step: TFirstStep, ...more: BranchMoreArgs<TCurrentJson, TFirstStep, TRestSteps>): TReturn;
+};
+//#endregion
+//#region ../core/src/workflow/dsl/WhenBuilder.d.ts
+declare class WhenBuilder<TCurrentJson> {
+  private readonly wf;
+  private readonly from;
+  private readonly branchPort;
+  constructor(wf: WorkflowBuilder, from: NodeRef, branchPort: OutputPortKey);
+  addBranch<TSteps extends ReadonlyArray<AnyRunnableNodeConfig>>(steps: TSteps & ValidStepSequence<TCurrentJson, TSteps>): this;
+  readonly when: BooleanWhenOverloads<TCurrentJson, WhenBuilder<TCurrentJson>>;
+  build(): WorkflowDefinition;
+}
+//#endregion
+//#region ../core/src/workflow/dsl/ChainCursorResolver.d.ts
+type ChainCursorEndpoint = Readonly<{
+  node: NodeRef;
+  output: OutputPortKey;
+  inputPortHint?: InputPortKey;
+}>;
+type ChainCursorWhenOverloads<TCurrentJson> = BooleanWhenOverloads<TCurrentJson, WhenBuilder<TCurrentJson>> & {
+  <TTrueSteps extends ReadonlyArray<AnyRunnableNodeConfig> | undefined, TFalseSteps extends ReadonlyArray<AnyRunnableNodeConfig> | undefined>(branches: Readonly<{
+    true?: TTrueSteps extends ReadonlyArray<AnyRunnableNodeConfig> ? BranchStepsArg<TCurrentJson, TTrueSteps> : never;
+    false?: TFalseSteps extends ReadonlyArray<AnyRunnableNodeConfig> ? BranchStepsArg<TCurrentJson, TFalseSteps> : never;
+  }> & BranchOutputGuard<TCurrentJson, TTrueSteps, TFalseSteps>): ChainCursor<StepSequenceOutput<TCurrentJson, TTrueSteps>>;
+};
+declare class ChainCursor<TCurrentJson> {
+  private readonly wf;
+  private readonly endpoints;
+  constructor(wf: WorkflowBuilder, endpoints: ReadonlyArray<ChainCursorEndpoint>);
+  then<TOutputJson$1, TConfig extends RunnableNodeConfig<TCurrentJson, TOutputJson$1>>(config: TConfig): ChainCursor<RunnableNodeOutputJson<TConfig>>;
+  thenIntoInputHints<TOutputJson$1, TConfig extends RunnableNodeConfig<any, TOutputJson$1>>(config: TConfig): ChainCursor<RunnableNodeOutputJson<TConfig>>;
+  readonly when: ChainCursorWhenOverloads<TCurrentJson>;
+  route<TNextJson$1>(branches: Readonly<Record<OutputPortKey, (branch: ChainCursor<TCurrentJson>) => ChainCursor<TNextJson$1> | undefined>>): ChainCursor<TNextJson$1>;
+  build(): WorkflowDefinition;
+  private resolveSharedInputPortHint;
+}
+//#endregion
+//#region ../core/src/workflow/dsl/WorkflowBuilder.d.ts
+declare class WorkflowBuilder {
+  private readonly meta;
+  private readonly options?;
+  private readonly nodes;
+  private readonly edges;
+  constructor(meta: {
+    id: WorkflowId;
+    name: string;
+  }, options?: Readonly<Record<string, never>> | undefined);
+  private add;
+  private connect;
+  trigger<TConfig extends AnyTriggerNodeConfig>(config: TConfig): ChainCursor<TriggerNodeOutputJson<TConfig>>;
+  start<TConfig extends AnyRunnableNodeConfig>(config: TConfig): ChainCursor<RunnableNodeOutputJson<TConfig>>;
+  build(): WorkflowDefinition;
+  private validateNodeIds;
+}
+//#endregion
+//#region ../core/src/contracts/runtimeTypes.d.ts
+interface WorkflowRunnerService {
+  runById(args: {
+    workflowId: WorkflowId;
+    startAt?: NodeId;
+    items: Items;
+    parent?: ParentExecutionRef;
+  }): Promise<RunResult>;
+}
+interface NodeResolver {
+  resolve<T>(token: TypeToken<T>): T;
+}
+interface NodeExecutionStatePublisher {
+  markQueued(args: {
+    nodeId: NodeId;
+    activationId?: NodeActivationId;
+    inputsByPort?: NodeInputsByPort;
+  }): Promise<void>;
+  markRunning(args: {
+    nodeId: NodeId;
+    activationId?: NodeActivationId;
+    inputsByPort?: NodeInputsByPort;
+  }): Promise<void>;
+  markCompleted(args: {
+    nodeId: NodeId;
+    activationId?: NodeActivationId;
+    inputsByPort?: NodeInputsByPort;
+    outputs?: NodeOutputs;
+  }): Promise<void>;
+  markFailed(args: {
+    nodeId: NodeId;
+    activationId?: NodeActivationId;
+    inputsByPort?: NodeInputsByPort;
+    error: Error;
+  }): Promise<void>;
+  appendConnectionInvocation(args: ConnectionInvocationAppendArgs): Promise<void>;
+}
+type BinaryBody = ReadableStream<Uint8Array> | AsyncIterable<Uint8Array> | Uint8Array | ArrayBuffer;
+interface BinaryStorageReadResult {
+  body: ReadableStream<Uint8Array>;
+  size?: number;
+}
+interface BinaryAttachmentCreateRequest {
+  name: string;
+  body: BinaryBody;
+  mimeType: string;
+  filename?: string;
+  previewKind?: BinaryAttachment["previewKind"];
+}
+interface NodeBinaryAttachmentService extends ExecutionBinaryService {
+  attach(args: BinaryAttachmentCreateRequest): Promise<BinaryAttachment>;
+  withAttachment<TJson>(item: Item<TJson>, name: string, attachment: BinaryAttachment): Item<TJson>;
+}
+interface ExecutionBinaryService {
+  forNode(args: {
+    nodeId: NodeId;
+    activationId: NodeActivationId;
+  }): NodeBinaryAttachmentService;
+  openReadStream(attachment: BinaryAttachment): Promise<BinaryStorageReadResult | undefined>;
+}
+interface ExecutionContext {
+  runId: RunId;
+  workflowId: WorkflowId;
+  parent?: ParentExecutionRef;
+  /** This run's subworkflow depth (0 = root). */
+  subworkflowDepth: number;
+  /** Effective activation budget cap for this run (after policy merge). */
+  engineMaxNodeActivations: number;
+  /** Effective subworkflow nesting cap for this run (after policy merge). */
+  engineMaxSubworkflowDepth: number;
+  now: () => Date;
+  data: RunDataSnapshot;
+  nodeState?: NodeExecutionStatePublisher;
+  telemetry: ExecutionTelemetry;
+  binary: ExecutionBinaryService;
+  getCredential<TSession = unknown>(slotKey: string): Promise<TSession>;
+  /** Per-item iteration id, set by {@link NodeExecutor} on the ctx passed into runnable `execute`. */
+  iterationId?: NodeIterationId;
+  /** Item index (0-based) within the current activation's batch; set alongside {@link iterationId}. */
+  itemIndex?: number;
+  /** When set, this ctx is executing inside a sub-agent triggered by the named parent invocation. */
+  parentInvocationId?: ConnectionInvocationId;
   /**
-   * Optional labels for the collapsible block that contains every field with `visibility: "advanced"`.
-   * If omitted, the UI still shows that block with defaults (title "Advanced", collapsed).
+   * Present iff the run was started by a TestSuiteOrchestrator. The {@link IsTestRunNode}
+   * branches on this; assertion-emitting nodes use it to decide whether to record results.
    */
-  advancedSection?: CredentialAdvancedSectionPresentation;
-  supportedSourceKinds?: ReadonlyArray<CredentialMaterialSourceKind>;
-  auth?: CredentialAuthDefinition;
-}>;
-/**
- * JSON-shaped credential field bag (public config, resolved secret material, etc.).
- */
-type CredentialJsonRecord = Readonly<Record<string, unknown>>;
+  testContext?: RunTestContext;
+  /**
+   * Collections registered in the codemation config, keyed by collection name.
+   */
+  readonly collections?: CollectionsContext;
+}
+interface NodeExecutionContext<TConfig extends NodeConfigBase = NodeConfigBase> extends ExecutionContext {
+  nodeId: NodeId;
+  activationId: NodeActivationId;
+  config: TConfig;
+  telemetry: NodeExecutionTelemetry;
+  binary: NodeBinaryAttachmentService;
+}
+interface PollingTriggerHandle {
+  /**
+   * Start the polling loop. The runtime registers its own cleanup handle so callers do not need to
+   * call {@link TriggerSetupContext.registerCleanup} for the loop.
+   * @returns The state returned by the first cycle (or `undefined` when the overlap guard fired).
+   */
+  start<TState, TItem>(args: {
+    intervalMs: number;
+    seedState?: TState;
+    runCycle: (cycleCtx: {
+      previousState: TState | undefined;
+      signal: AbortSignal;
+    }) => Promise<{
+      items: Items<TItem>;
+      nextState: TState;
+    }>;
+  }): Promise<TState | undefined>;
+  /** Convenience dedup-window helper. */
+  readonly dedup: PollingTriggerDedupWindow;
+}
+interface TriggerSetupContext<TConfig extends TriggerNodeConfig<any, any> = TriggerNodeConfig<any, any>, TSetupState$1 extends JsonValue | undefined = TriggerNodeSetupState<TConfig>> extends ExecutionContext {
+  trigger: TriggerInstanceId;
+  config: TConfig;
+  previousState: TSetupState$1;
+  registerCleanup(cleanup: TriggerCleanupHandle): void;
+  emit(items: Items): Promise<void>;
+  /** Generic polling-trigger surface. Pre-binds trigger id, emit, and registerCleanup. */
+  readonly polling: PollingTriggerHandle;
+}
+interface TriggerTestItemsContext<TConfig extends TriggerNodeConfig<any, any> = TriggerNodeConfig<any, any>, TSetupState$1 extends JsonValue | undefined = TriggerNodeSetupState<TConfig>> extends ExecutionContext {
+  trigger: TriggerInstanceId;
+  nodeId: NodeId;
+  config: TConfig;
+  previousState: TSetupState$1;
+}
+interface TriggerCleanupHandle {
+  stop(): Promise<void> | void;
+}
 /**
- * Persisted credential instance with typed `publicConfig`.
- * Hosts may specialize `secretRef` with a stricter union while remaining
- * assignable here for session/test callbacks.
+ * Per-item runnable node: return JSON, an array to fan-out on `main`, an explicit `Item`, or {@link emitPorts}
+ * for multi-port emission. Engine applies `inputSchema.parse(item.json)` and passes the result as `args.input`
+ * (wire `item.json` is unchanged). Transform helpers may opt into binary preservation, while routers and
+ * pass-through nodes should return explicit items when they need to preserve full item state.
  */
-type CredentialInstanceRecord<TPublicConfig extends CredentialJsonRecord = CredentialJsonRecord> = Readonly<{
-  instanceId: CredentialInstanceId;
-  typeId: CredentialTypeId;
-  displayName: string;
-  sourceKind: CredentialMaterialSourceKind;
-  publicConfig: TPublicConfig;
-  secretRef: CredentialJsonRecord;
-  tags: ReadonlyArray<string>;
-  setupStatus: CredentialSetupStatus;
-  createdAt: string;
-  updatedAt: string;
+interface RunnableNodeExecuteArgs<TConfig extends RunnableNodeConfig<any, any> = RunnableNodeConfig<any, any>, TInputJson$1 = unknown> {
+  readonly input: TInputJson$1;
+  readonly item: Item;
+  readonly itemIndex: number;
+  readonly items: Items;
+  readonly ctx: NodeExecutionContext<TConfig>;
+}
+interface RunnableNode<TConfig extends RunnableNodeConfig<any, any> = RunnableNodeConfig<any, any>, TInputJson$1 = unknown, _TOutputJson = unknown> {
+  readonly kind: "node";
+  /**
+   * Declared output ports (e.g. `["main"]`).
+   *
+   * Prefer describing dynamic router ports (Switch) and fixed multi-ports (If true/false)
+   * via {@link NodeConfigBase.declaredOutputPorts}. Engine defaults to `["main"]` when omitted.
+   */
+  readonly outputPorts?: ReadonlyArray<OutputPortKey>;
+  /** When omitted, engine uses {@link RunnableNodeConfig.inputSchema} or `z.unknown()`. */
+  readonly inputSchema?: ZodType<TInputJson$1>;
+  execute(args: RunnableNodeExecuteArgs<TConfig, TInputJson$1>): Promise<unknown> | unknown;
+}
+interface MultiInputNode<TConfig extends NodeConfigBase = NodeConfigBase> {
+  kind: "node";
+  /**
+   * Declared output ports (typically `["main"]`).
+   *
+   * Prefer describing ports for authoring/canvas via {@link NodeConfigBase.declaredOutputPorts}.
+   * Engine defaults to `["main"]` when omitted.
+   */
+  outputPorts?: ReadonlyArray<OutputPortKey>;
+  executeMulti(inputsByPort: NodeInputsByPort, ctx: NodeExecutionContext<TConfig>): Promise<NodeOutputs>;
+}
+type TriggerSetupStateFor<TConfig extends TriggerNodeConfig<any, any>> = TriggerNodeSetupState<TConfig>;
+interface TriggerNode<TConfig extends TriggerNodeConfig<any, any> = TriggerNodeConfig<any, any>> {
+  kind: "trigger";
+  outputPorts: readonly ["main"];
+  setup(ctx: TriggerSetupContext<TConfig>): Promise<TriggerSetupStateFor<TConfig>>;
+  execute(items: Items, ctx: NodeExecutionContext<TConfig>): Promise<NodeOutputs>;
+}
+interface TestableTriggerNode<TConfig extends TriggerNodeConfig<any, any> = TriggerNodeConfig<any, any>> extends TriggerNode<TConfig> {
+  getTestItems(ctx: TriggerTestItemsContext<TConfig>): Promise<Items>;
+}
+type ExecutableTriggerNode<TConfig extends TriggerNodeConfig<any, any> = TriggerNodeConfig<any, any>> = TriggerNode<TConfig>;
+//#endregion
+//#region ../core/src/contracts/itemExpr.d.ts
+declare const ITEM_EXPR_BRAND: unique symbol;
+type ItemExprResolvedContext = Readonly<{
+  runId: RunId;
+  workflowId: WorkflowId;
+  nodeId: NodeId;
+  activationId: NodeActivationId;
+  data: RunDataSnapshot;
 }>;
 /**
- * Arguments passed to `CredentialType.createSession` and `CredentialType.test`.
- * Declare `TPublicConfig` / `TMaterial` on `CredentialType` so implementations are checked
- * against your credential shapes (similar to `NodeExecutionContext.config` for nodes).
+ * Context aligned with former {@link ItemInputMapperContext} — use **`data`** to read any completed upstream node.
  */
-type CredentialSessionFactoryArgs<TPublicConfig extends CredentialJsonRecord = CredentialJsonRecord, TMaterial extends CredentialJsonRecord = CredentialJsonRecord> = Readonly<{
-  instance: CredentialInstanceRecord<TPublicConfig>;
-  material: TMaterial;
-  publicConfig: TPublicConfig;
+type ItemExprContext = ItemExprResolvedContext;
+type ItemExprArgs<TItemJson = unknown> = Readonly<{
+  item: Item<TItemJson>;
+  itemIndex: number;
+  items: Items<TItemJson>;
+  ctx: ItemExprContext;
 }>;
-type CredentialSessionFactory<TPublicConfig extends CredentialJsonRecord = CredentialJsonRecord, TMaterial extends CredentialJsonRecord = CredentialJsonRecord, TSession = unknown> = (args: CredentialSessionFactoryArgs<TPublicConfig, TMaterial>) => Promise<TSession>;
-type CredentialHealthTester<TPublicConfig extends CredentialJsonRecord = CredentialJsonRecord, TMaterial extends CredentialJsonRecord = CredentialJsonRecord> = (args: CredentialSessionFactoryArgs<TPublicConfig, TMaterial>) => Promise<CredentialHealth>;
-/**
- * Full credential type implementation: `definition` (UI/schema), `createSession`, and `test`.
- * Use this at registration and config boundaries; `CredentialTypeDefinition` is only the schema slice.
- */
-type CredentialType<TPublicConfig extends CredentialJsonRecord = CredentialJsonRecord, TMaterial extends CredentialJsonRecord = CredentialJsonRecord, TSession = unknown> = Readonly<{
-  definition: CredentialTypeDefinition;
-  createSession: CredentialSessionFactory<TPublicConfig, TMaterial, TSession>;
-  test: CredentialHealthTester<TPublicConfig, TMaterial>;
+type ItemExprCallback<T, TItemJson = unknown> = (args: ItemExprArgs<TItemJson>) => T | Promise<T>;
+type ItemExpr<T, TItemJson = unknown> = Readonly<{
+  readonly [ITEM_EXPR_BRAND]: true;
+  readonly fn: ItemExprCallback<T, TItemJson>;
 }>;
-/**
- * Credential type with unspecified generics — used for `CodemationConfig.credentialTypes`, the host registry,
- * and anywhere a concrete `CredentialType<YourPublic, YourMaterial, YourSession>` is placed in a heterogeneous list.
- * Using `any` here avoids unsafe `as` casts while keeping typed `satisfies CredentialType<…>` definitions.
- */
-type AnyCredentialType = CredentialType<any, any, unknown>;
-interface CredentialSessionService {
-  getSession<TSession = unknown>(args: Readonly<{
-    workflowId: WorkflowId;
-    nodeId: NodeId;
-    slotKey: string;
-  }>): Promise<TSession>;
-}
+//#endregion
+//#region ../core/src/contracts/params.d.ts
+type Expr<T, TItemJson = unknown> = ItemExpr<T, TItemJson>;
+type ParamDeep<T, TItemJson = unknown> = Expr<T, TItemJson> | (T extends readonly (infer U)[] ? ReadonlyArray<ParamDeep<U, TItemJson>> : never) | (T extends object ? { [K in keyof T]: ParamDeep<T[K], TItemJson> } : T);
 //#endregion
 //#region ../core/src/authoring/defineNode.types.d.ts
 type ResolvableCredentialType = AnyCredentialType | CredentialTypeId;
@@ -897,6 +1185,15 @@ type ToolExecuteArgs<TConfig extends ToolConfig = ToolConfig, TInput = unknown>
   item: Item;
   itemIndex: number;
   items: Items;
+  /**
+   * Optional sub-agent boundary hooks: when present, the live `agent.tool.call` span and the
+   * planned tool-call invocationId are forwarded so node-backed runtimes can re-root their child
+   * execution scope. Plain function tools may safely ignore these hooks.
+   */
+  hooks?: Readonly<{
+    parentSpan?: TelemetrySpanScope;
+    parentInvocationId?: ConnectionInvocationId;
+  }>;
 }>;
 type AgentMessageRole = "system" | "user" | "assistant";
 type AgentMessageBuildArgs<TInputJson$1 = unknown> = Readonly<{
@@ -947,25 +1244,47 @@ interface ChatModelConfig {
   readonly presentation?: AgentCanvasPresentation;
   getCredentialRequirements?(): ReadonlyArray<CredentialRequirement>;
 }
-interface LangChainChatModelLike {
-  invoke(input: unknown, options?: unknown): Promise<unknown>;
-  bindTools?(tools: ReadonlyArray<unknown>): LangChainChatModelLike;
-  withStructuredOutput?(outputSchema: ZodSchemaAny, config?: ChatModelStructuredOutputOptions): LangChainStructuredOutputModelLike;
+/**
+ * Provider-neutral chat language model wrapper returned by a {@link ChatModelFactory}.
+ *
+ * Thin adapter around an AI SDK `LanguageModelV2` (from `@ai-sdk/provider`) plus the call-site
+ * defaults Codemation needs at every generate/stream: the provider label, the model name used for
+ * pricing / telemetry, and the default invocation options (max output tokens, temperature,
+ * provider-specific overrides).
+ *
+ * The consumer (AIAgentNode / AgentStructuredOutputRunner) passes `languageModel` directly into
+ * `generateText({ model, ... })` from the `ai` package.
+ */
+interface ChatLanguageModel {
+  /** AI SDK `LanguageModelV2` instance (kept `unknown` to avoid leaking the SDK type into `@codemation/core`). */
+  readonly languageModel: unknown;
+  /** Stable pricing/telemetry key — e.g. `"gpt-4.1-nano"`. */
+  readonly modelName: string;
+  /** Provider label — e.g. `"openai"`. Used for cost tracking. */
+  readonly provider?: string;
+  /** Defaults merged into every call. Consumers may override per-invocation. */
+  readonly defaultCallOptions?: ChatLanguageModelCallOptions;
 }
-interface LangChainStructuredOutputModelLike {
-  invoke(input: unknown, options?: unknown): Promise<unknown>;
+interface ChatLanguageModelCallOptions {
+  readonly maxOutputTokens?: number;
+  readonly temperature?: number;
+  readonly providerOptions?: Readonly<Record<string, Readonly<Record<string, JsonValue>>>>;
 }
-interface ChatModelStructuredOutputOptions {
-  readonly method?: "jsonSchema" | "functionCalling" | "jsonMode";
+/**
+ * Options for a structured-output generate call. Mirrors
+ * `generateText({ output: Output.object(...) })` from the `ai` package.
+ */
+interface StructuredOutputOptions {
+  /** Optional schema name — used by some providers as the JSON schema name attribute. */
+  readonly schemaName?: string;
+  /** When `true`, the consumer should pass a strict-mode-compatible JSON Schema record. */
   readonly strict?: boolean;
-  readonly includeRaw?: boolean;
-  readonly tools?: ReadonlyArray<unknown>;
 }
 interface ChatModelFactory<TConfig extends ChatModelConfig = ChatModelConfig> {
   create(args: Readonly<{
     config: TConfig;
     ctx: NodeExecutionContext<any>;
-  }>): Promise<LangChainChatModelLike> | LangChainChatModelLike;
+  }>): Promise<ChatLanguageModel> | ChatLanguageModel;
 }
 type NodeBackedToolInputMapperArgs<TNodeConfig extends RunnableNodeConfig<any, any>, TToolInput = unknown> = Readonly<{
   input: TToolInput;
@@ -1002,6 +1321,32 @@ interface AgentNodeConfig<TInputJson$1 = unknown, TOutputJson$1 = unknown> exten
   readonly outputSchema?: ZodType<TOutputJson$1>;
 }
 //#endregion
+//#region ../core/src/execution/ChildExecutionScopeFactory.d.ts
+/**
+ * Builds a re-rooted child execution context for sub-agent (and other deeply-nested) invocations.
+ *
+ * At the orchestrator's `agent.tool.call` boundary the inner runtime needs a ctx whose:
+ * - `nodeId` is the tool's connection node id (so inner LLM/tool connection ids derive correctly),
+ * - `activationId` is fresh (so its connection-invocation rows are uniquely identifiable),
+ * - `telemetry` parents children under the tool-call span (not the orchestrator's node span),
+ * - `binary` is scoped to the new (nodeId, activationId),
+ * - `parentInvocationId` points back to the tool-call invocation for downstream lineage.
+ *
+ * Registered via factory in {@link EngineRuntimeRegistrar} so constructors stay free of parameter
+ * decorators (Next/SWC and coverage tooling cannot parse them on in-repo sources).
+ */
+declare class ChildExecutionScopeFactory {
+  private readonly activationIdFactory;
+  constructor(activationIdFactory: ActivationIdFactory);
+  forSubAgent<TConfig extends RunnableNodeConfig<any, any>>(args: Readonly<{
+    parentCtx: NodeExecutionContext<TConfig>;
+    childNodeId: NodeId;
+    childConfig: TConfig;
+    parentInvocationId: ConnectionInvocationId;
+    parentSpan: TelemetrySpanScope;
+  }>): NodeExecutionContext<TConfig>;
+}
+//#endregion
 //#region ../core/src/execution/ItemExprResolver.d.ts
 /**
  * Resolves {@link import("../contracts/itemExpr").ItemExpr} leaves on runnable config before {@link RunnableNode.execute}.
@@ -1033,6 +1378,325 @@ declare class NodeOutputNormalizer {
   private applyOutput;
 }
 //#endregion
+//#region src/http/httpRequest.types.d.ts
+/**
+ * Binary reference key into `item.binary`.
+ */
+type BinaryRef = string;
+/**
+ * Discriminated union for the HTTP request body.
+ */
+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.
+ */
+interface CredentialSession {
+  applyToRequest(spec: HttpRequestSpec): HttpCredentialDelta;
+}
+/**
+ * Mutations the credential session wants to apply to the outgoing request.
+ */
+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).
+ */
+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.
+ */
+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;
+}>;
+//#endregion
+//#region src/credentials/ApiKeyCredentialType.d.ts
+/**
+ * API key credential that injects a key either as an HTTP header or a query parameter.
+ */
+declare const apiKeyCredentialType: Readonly<{
+  definition: Readonly<{
+    typeId: CredentialTypeId;
+    displayName: string;
+    description?: string;
+    publicFields?: ReadonlyArray<CredentialFieldSchema>;
+    secretFields?: ReadonlyArray<CredentialFieldSchema>;
+    advancedSection?: CredentialAdvancedSectionPresentation;
+    supportedSourceKinds?: ReadonlyArray<CredentialMaterialSourceKind>;
+    auth?: CredentialAuthDefinition;
+  }>;
+  createSession: CredentialSessionFactory<{
+    placement: unknown;
+    name: unknown;
+  }, {
+    apiKey: unknown;
+  }, CredentialSession>;
+  test: CredentialHealthTester<{
+    placement: unknown;
+    name: unknown;
+  }, {
+    apiKey: unknown;
+  }>;
+}> & {
+  readonly key: string;
+};
+//#endregion
+//#region src/credentials/BasicAuthCredentialType.d.ts
+/**
+ * HTTP Basic authentication credential.
+ * Session sets `Authorization: Basic <base64(username:password)>`.
+ */
+declare const basicAuthCredentialType: Readonly<{
+  definition: Readonly<{
+    typeId: CredentialTypeId;
+    displayName: string;
+    description?: string;
+    publicFields?: ReadonlyArray<CredentialFieldSchema>;
+    secretFields?: ReadonlyArray<CredentialFieldSchema>;
+    advancedSection?: CredentialAdvancedSectionPresentation;
+    supportedSourceKinds?: ReadonlyArray<CredentialMaterialSourceKind>;
+    auth?: CredentialAuthDefinition;
+  }>;
+  createSession: CredentialSessionFactory<{
+    username: unknown;
+  }, {
+    password: unknown;
+  }, CredentialSession>;
+  test: CredentialHealthTester<{
+    username: unknown;
+  }, {
+    password: unknown;
+  }>;
+}> & {
+  readonly key: string;
+};
+//#endregion
+//#region src/credentials/BearerTokenCredentialType.d.ts
+/**
+ * Simple Bearer token credential.
+ * Session sets `Authorization: Bearer <token>` on every request.
+ */
+declare const bearerTokenCredentialType: Readonly<{
+  definition: Readonly<{
+    typeId: CredentialTypeId;
+    displayName: string;
+    description?: string;
+    publicFields?: ReadonlyArray<CredentialFieldSchema>;
+    secretFields?: ReadonlyArray<CredentialFieldSchema>;
+    advancedSection?: CredentialAdvancedSectionPresentation;
+    supportedSourceKinds?: ReadonlyArray<CredentialMaterialSourceKind>;
+    auth?: CredentialAuthDefinition;
+  }>;
+  createSession: CredentialSessionFactory<Readonly<Record<string, unknown>>, {
+    token: unknown;
+  }, CredentialSession>;
+  test: CredentialHealthTester<Readonly<Record<string, unknown>>, {
+    token: unknown;
+  }>;
+}> & {
+  readonly key: string;
+};
+//#endregion
+//#region src/credentials/OAuth2ClientCredentialsTypeFactory.d.ts
+/**
+ * OAuth2 client-credentials flow credential.
+ *
+ * This is a machine-to-machine flow: no user redirect occurs. The session
+ * POSTs to the configured `tokenUrl` with `client_credentials` grant, caches
+ * the resulting access token for the duration of the session, and injects it
+ * as `Authorization: Bearer <token>` on each request.
+ *
+ * Token caching is per-session only (one createSession call = one token fetch
+ * at most). Cross-session caching would require host-level state and is out of
+ * scope here. Because the engine creates a fresh session per execution, a new
+ * token is fetched once per node activation.
+ *
+ * NOTE: `auth` is intentionally omitted from the definition. The OAuth2
+ * `auth: { kind: "oauth2" }` shape signals an authorization-code / user-redirect
+ * flow; using it here would cause the host UI to render an OAuth consent button
+ * that goes nowhere. Client-credentials is a purely server-side flow.
+ */
+declare const oauth2ClientCredentialsType: Readonly<{
+  definition: Readonly<{
+    typeId: CredentialTypeId;
+    displayName: string;
+    description?: string;
+    publicFields?: ReadonlyArray<CredentialFieldSchema>;
+    secretFields?: ReadonlyArray<CredentialFieldSchema>;
+    advancedSection?: CredentialAdvancedSectionPresentation;
+    supportedSourceKinds?: ReadonlyArray<CredentialMaterialSourceKind>;
+    auth?: CredentialAuthDefinition;
+  }>;
+  createSession: CredentialSessionFactory<{
+    tokenUrl: unknown;
+    scopes: unknown;
+    audience: unknown;
+  }, {
+    clientId: unknown;
+    clientSecret: unknown;
+  }, CredentialSession>;
+  test: CredentialHealthTester<{
+    tokenUrl: unknown;
+    scopes: unknown;
+    audience: unknown;
+  }, {
+    clientId: unknown;
+    clientSecret: unknown;
+  }>;
+}> & {
+  readonly key: string;
+};
+//#endregion
+//#region src/authoring/defineRestNode.types.d.ts
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * API endpoint descriptor.
+ */
+type RestNodeApi = Readonly<{
+  /**
+   * Base URL, e.g. `"https://api.slack.com"`.
+   */
+  baseUrl: string;
+  /**
+   * Path relative to `baseUrl`. May contain `{paramName}` placeholders that
+   * are substituted from `input` keys before the request is made.
+   * Example: `"/users/{userId}/profile"`
+   */
+  path: string;
+  /** HTTP method (default: GET). */
+  method?: string;
+}>;
+/**
+ * The HTTP result shape passed into the `response` mapper.
+ */
+type RestNodeResponseContext = Readonly<{
+  status: number;
+  ok: boolean;
+  statusText: string;
+  mimeType: string;
+  headers: Readonly<Record<string, string>>;
+  json?: unknown;
+  text?: string;
+}>;
+/**
+ * What the `request` callback may return to customise the request.
+ */
+type RestNodeRequestShape = Readonly<{
+  /** Additional path parameters to substitute (merged with `input`). */
+  pathParams?: Readonly<Record<string, string>>;
+  /** Extra query params. */
+  query?: Readonly<Record<string, string>>;
+  /** Extra headers. */
+  headers?: Readonly<Record<string, string>>;
+  /** Request body. */
+  body?: HttpBodySpec;
+}>;
+/**
+ * Error handling policy for non-2xx responses.
+ *  - `"throw"` (default) — throws an `Error` for non-2xx responses.
+ *  - `"passthrough"` — returns the result regardless of status.
+ */
+type RestNodeErrorPolicy = "throw" | "passthrough";
+interface DefineRestNodeOptions<TKey$1 extends string, TCredentials extends DefinedNodeCredentialBindings | undefined, TInputJson$1, TOutputJson$1> {
+  readonly key: TKey$1;
+  readonly title: string;
+  readonly description?: string;
+  readonly icon?: string;
+  readonly api: RestNodeApi;
+  /**
+   * Credential bindings keyed by slot. Use the built-in credential types from
+   * `@codemation/core-nodes` (e.g. `bearerTokenCredentialType`) or any custom one.
+   * The slot key must match what the `request` callback's context uses.
+   */
+  readonly credentials?: TCredentials;
+  /**
+   * Zod schema for per-item input. Validated before `execute`.
+   */
+  readonly inputSchema?: ZodType<TInputJson$1>;
+  /**
+   * Builds the per-request customisations from the item input.
+   * Return `body`, `query`, `headers`, and/or `pathParams`.
+   */
+  request?(context: Readonly<{
+    input: TInputJson$1;
+  }>): MaybePromise<RestNodeRequestShape>;
+  /**
+   * Maps the HTTP response to the node's output JSON.
+   * When omitted, the output is `{ status, ok, statusText, mimeType, headers, json, text }`.
+   */
+  response?(context: RestNodeResponseContext & Readonly<{
+    input: TInputJson$1;
+  }>): MaybePromise<TOutputJson$1>;
+  /**
+   * How to handle non-2xx responses.
+   * @default "throw"
+   */
+  readonly errorPolicy?: RestNodeErrorPolicy;
+}
+/**
+ * Declarative helper for creating thin API-wrapper nodes.
+ *
+ * Usage:
+ * ```ts
+ * export const postMessage = defineRestNode({
+ *   key: "slack.post-message",
+ *   title: "Send Slack message",
+ *   icon: "si:slack",
+ *   api: { baseUrl: "https://slack.com/api", path: "/chat.postMessage", method: "POST" },
+ *   credentials: { auth: bearerTokenCredentialType },
+ *   inputSchema: z.object({ channel: z.string(), text: z.string() }),
+ *   request: ({ input }) => ({
+ *     body: { kind: "json", data: { channel: input.channel, text: input.text } },
+ *   }),
+ *   response: ({ json }) => ({ messageTs: (json as any).ts }),
+ * });
+ * ```
+ *
+ * - `defineRestNode` is a thin wrapper over `defineNode`; it does not introduce a new runtime kind.
+ * - Credential sessions are resolved via the `credentials` binding map (same as `defineNode`).
+ * - Path `{placeholder}` substitution is applied from `input` keys before the request is made.
+ * - Non-2xx responses throw an `Error` by default (`errorPolicy: "throw"`).
+ */
+declare function defineRestNode<TKey$1 extends string, TCredentials extends DefinedNodeCredentialBindings | undefined, TInputJson$1, TOutputJson$1 = RestNodeResponseContext>(options: DefineRestNodeOptions<TKey$1, TCredentials, TInputJson$1, TOutputJson$1>): DefinedNode<TKey$1, Record<string, never>, TInputJson$1, TOutputJson$1, TCredentials>;
+//#endregion
 //#region src/chatModels/openAiChatModelConfig.d.ts
 declare class OpenAIChatModelConfig implements ChatModelConfig {
   readonly name: string;
@@ -1058,16 +1722,96 @@ declare class OpenAIChatModelFactory implements ChatModelFactory<OpenAIChatModel
   create(args: Readonly<{
     config: OpenAIChatModelConfig;
     ctx: NodeExecutionContext<any>;
-  }>): Promise<LangChainChatModelLike>;
+  }>): Promise<ChatLanguageModel>;
+}
+//#endregion
+//#region src/nodes/ConnectionCredentialExecutionContextFactory.d.ts
+/**
+ * Builds a {@link NodeExecutionContext} whose identity for credential binding and `getCredential`
+ * is a **connection-owned** workflow node id (`ConnectionNodeIdFactory` in `@codemation/core`),
+ * not the executing parent node. Use for LLM slots, tool slots, or any connection-scoped owner.
+ */
+declare class ConnectionCredentialExecutionContextFactory {
+  private readonly credentialResolverFactory;
+  constructor(credentialSessions: CredentialSessionService);
+  forConnectionNode<TConfig extends NodeConfigBase>(ctx: NodeExecutionContext<TConfig>, args: Readonly<{
+    connectionNodeId: NodeId;
+    getCredentialRequirements: () => ReadonlyArray<CredentialRequirement>;
+  }>): NodeExecutionContext<TConfig>;
+}
+//#endregion
+//#region src/nodes/AIAgentExecutionHelpersFactory.d.ts
+/**
+ * Helper utilities shared by {@link AIAgentNode} and supporting runners.
+ *
+ * Responsibilities:
+ * - {@link #createConnectionCredentialExecutionContextFactory} centralizes credential-context wiring.
+ * - {@link #createJsonSchemaRecord} is a pure Zod → draft-07 converter used by both
+ *   `OpenAiStrictJsonSchemaFactory` (to feed OpenAI-strict structured output) and the
+ *   `AgentStructuredOutputRepairPromptFactory` (to show a required-schema reminder).
+ */
+declare class AIAgentExecutionHelpersFactory {
+  createConnectionCredentialExecutionContextFactory(credentialSessions: CredentialSessionService): ConnectionCredentialExecutionContextFactory;
+  /**
+   * Produces a plain JSON Schema object (`draft-07`) from a Zod schema, as needed by
+   * OpenAI tool-parameter schemas and the structured-output repair prompt.
+   * - Prefers the schema's **instance** `toJSONSchema(...)` method so we stay inside the Zod
+   *   instance that created the schema (works across consumer/framework tsx namespaces — see
+   *   {@link ZodInstanceToJsonSchema}). Falls back to the framework-imported module function.
+   * - Strips root `$schema` (OpenAI ignores it).
+   * - Sanitizes `required` for cfworker json-schema compatibility (must be a string array or absent).
+   */
+  createJsonSchemaRecord(inputSchema: ZodSchemaAny, options: Readonly<{
+    schemaName: string;
+    requireObjectRoot: boolean;
+  }>): Record<string, unknown>;
+  /**
+   * Runs Zod's `toJSONSchema` via the schema's own instance method when available, so consumer
+   * schemas loaded under a different tsx namespace still convert correctly. If the caller handed us
+   * a payload that lacks that method (e.g. a plain JSON Schema record or a Zod instance whose
+   * prototype was stripped), we fall back to the framework-bundled module function.
+   */
+  private convertZodSchemaToJsonSchema;
+  /**
+   * `@cfworker/json-schema` iterates `schema.required` with `for...of`; it must be a string array or absent.
+   */
+  private sanitizeJsonSchemaRequiredKeywordsForCfworker;
 }
 //#endregion
-//#region src/chatModels/OpenAIStructuredOutputMethodFactory.d.ts
-declare class OpenAIStructuredOutputMethodFactory {
-  private static readonly isoDatePattern;
-  create(chatModelConfig: ChatModelConfig): ChatModelStructuredOutputOptions | undefined;
-  private readModelName;
-  private supportsJsonSchema;
-  private supportsSnapshotAtOrAfter;
+//#region src/chatModels/OpenAiStrictJsonSchemaFactory.d.ts
+/**
+ * Produces an OpenAI **strict mode**–compliant JSON Schema for an AIAgent `outputSchema`.
+ *
+ * Why this exists: AI SDK's default Zod → JSON Schema conversion (Zod v4's `toJSONSchema`) can
+ * emit `unevaluatedProperties: false` or skip `additionalProperties: false` on object branches.
+ * OpenAI's strict-mode validator rejects anything missing `additionalProperties: false` at
+ * `context=()` (the root) and requires **all properties** in `required`. We convert here so all
+ * legal Zod root shapes work (object, union, discriminated union, nullable-object wrapper, array,
+ * intersection, …) and hand AI SDK a pre-tagged `jsonSchema(...)` record that passes straight
+ * through to the provider.
+ *
+ * Rules enforced on the produced JSON Schema record:
+ * - Every `type: "object"` node (root and nested under `allOf`/`anyOf`/`oneOf`/`items`/`prefixItems`/`$defs`):
+ *   - `additionalProperties: false`
+ *   - `required` lists **every** key in `properties` (OpenAI strict requires all properties required;
+ *     express optionality via `.nullable()` / `z.union([..., z.null()])`).
+ *   - `properties` is always an object (empty object allowed).
+ * - `$schema`, `unevaluatedProperties`, and `default` are stripped (OpenAI rejects / ignores them).
+ * - `sanitizeJsonSchemaRequiredKeywordsForCfworker` invariants from
+ *   {@link AIAgentExecutionHelpersFactory.createJsonSchemaRecord} are preserved as a starting point.
+ */
+declare class OpenAiStrictJsonSchemaFactory {
+  private readonly executionHelpers;
+  constructor(executionHelpers: AIAgentExecutionHelpersFactory);
+  createStructuredOutputRecord(schema: ZodSchemaAny, options: Readonly<{
+    schemaName: string;
+    title?: string;
+  }>): Record<string, unknown>;
+  private strictifyRecursive;
+  private stripOpenAiRejectedKeywords;
+  private isObjectNode;
+  private readPropertiesObject;
+  private recurseIntoComposites;
 }
 //#endregion
 //#region src/chatModels/OpenAiCredentialSession.d.ts
@@ -1089,41 +1833,6 @@ declare class OpenAiChatModelPresets {
 }
 declare const openAiChatModelPresets: OpenAiChatModelPresets;
 //#endregion
-//#region src/nodes/AgentMessageFactory.d.ts
-declare class AgentMessageFactory {
-  static createPromptMessages(messages: ReadonlyArray<AgentMessageDto>): ReadonlyArray<BaseMessage>;
-  static createSystemPrompt(systemMessage: string): SystemMessage;
-  static createUserPrompt(prompt: string): HumanMessage;
-  static createAssistantPrompt(prompt: string): AIMessage;
-  static createToolMessage(toolCallId: string, content: string): ToolMessage;
-  static extractContent(message: unknown): string;
-  static extractToolCalls(message: unknown): ReadonlyArray<AgentToolCall>;
-  private static isRecord;
-  private static createPromptMessage;
-}
-//#endregion
-//#region src/nodes/AgentOutputFactory.d.ts
-declare class AgentOutputFactory {
-  static fromUnknown(value: unknown): NodeOutputs;
-  static replaceJson(item: Item, value: unknown): Item;
-  static fromAgentContent(content: string): unknown;
-}
-//#endregion
-//#region src/nodes/ConnectionCredentialExecutionContextFactory.d.ts
-/**
- * Builds a {@link NodeExecutionContext} whose identity for credential binding and `getCredential`
- * is a **connection-owned** workflow node id (`ConnectionNodeIdFactory` in `@codemation/core`),
- * not the executing parent node. Use for LLM slots, tool slots, or any connection-scoped owner.
- */
-declare class ConnectionCredentialExecutionContextFactory {
-  private readonly credentialResolverFactory;
-  constructor(credentialSessions: CredentialSessionService);
-  forConnectionNode<TConfig extends NodeConfigBase>(ctx: NodeExecutionContext<TConfig>, args: Readonly<{
-    connectionNodeId: NodeId;
-    getCredentialRequirements: () => ReadonlyArray<CredentialRequirement>;
-  }>): NodeExecutionContext<TConfig>;
-}
-//#endregion
 //#region src/nodes/aiAgentSupport.types.d.ts
 declare class AgentItemPortMap {
   static fromItem(item: Item): NodeInputsByPort;
@@ -1136,15 +1845,33 @@ type ResolvedTool = Readonly<{
     execute(args: ToolExecuteArgs<ToolConfig, unknown>): Promise<unknown>;
   }>;
 }>;
+/**
+ * Per-item binding of a tool: the user config plus the resolved runtime and a snapshot of the
+ * original Zod `inputSchema`.
+ *
+ * `execute` accepts optional `hooks` so the agent coordinator can pass the live `agent.tool.call`
+ * span and the planned tool-call's `invocationId`. Node-backed sub-agent tools use these hooks
+ * via {@link ChildExecutionScopeFactory} to re-root their runtime ctx under the tool-call boundary
+ * (fresh activationId, telemetry parented at the tool-call span, `parentInvocationId` set).
+ */
 type ItemScopedToolBinding = Readonly<{
   config: ToolConfig;
-  langChainTool: DynamicStructuredTool;
+  inputSchema: ZodSchemaAny;
+  execute(input: unknown, hooks?: ItemScopedToolCallHooks): Promise<unknown>;
+}>;
+type ItemScopedToolCallHooks = Readonly<{
+  /** Live agent.tool.call span (used to parent sub-agent telemetry). */
+  parentSpan?: TelemetrySpanScope;
+  /** invocationId of the parent tool call (used to thread `parentInvocationId` through ctx). */
+  parentInvocationId?: ConnectionInvocationId;
 }>;
 type PlannedToolCall = Readonly<{
   binding: ItemScopedToolBinding;
   toolCall: AgentToolCall;
   invocationIndex: number;
   nodeId: string;
+  /** Stable id reused across queued / running / completed connection invocation rows for this tool call. */
+  invocationId: string;
 }>;
 type ExecutedToolCall = Readonly<{
   toolName: string;
@@ -1153,30 +1880,33 @@ type ExecutedToolCall = Readonly<{
   serialized: string;
 }>;
 //#endregion
-//#region src/nodes/AIAgentExecutionHelpersFactory.d.ts
+//#region src/nodes/AgentMessageFactory.d.ts
 /**
- * LangChain adapters and credential context wiring for {@link AIAgentNode}.
- * Lives in a `*Factory.ts` composition-root module so construction stays explicit and testable.
+ * AI-SDK-shaped message construction for the AIAgent stack. Emits plain `ModelMessage[]`
+ * ( `{ role: 'system' | 'user' | 'assistant' | 'tool', content: ... }` ) as consumed by
+ * `generateText({ messages })` from the `ai` package.
  */
-declare class AIAgentExecutionHelpersFactory {
-  createConnectionCredentialExecutionContextFactory(credentialSessions: CredentialSessionService): ConnectionCredentialExecutionContextFactory;
-  createDynamicStructuredTool(entry: ResolvedTool, toolCredentialContext: NodeExecutionContext<any>, item: Item, itemIndex: number, items: Items): DynamicStructuredTool;
+declare class AgentMessageFactory {
+  static createPromptMessages(messages: ReadonlyArray<AgentMessageDto>): ReadonlyArray<ModelMessage>;
   /**
-   * Produces a plain JSON Schema object for OpenAI tool parameters and LangChain tool invocation:
-   * - **Zod** → `toJSONSchema(..., { target: "draft-07" })` so shapes match what `@cfworker/json-schema`
-   *   expects (`required` must be an array; draft 2020-12 output can break validation).
-   * - Otherwise LangChain `toJsonSchema` (Standard Schema + JSON passthrough); if the result is still Zod
-   *   (duplicate `zod` copies), fall back to Zod `toJSONSchema` with draft-07.
-   * - Strip root `$schema` for OpenAI; normalize invalid `required` keywords for cfworker; ensure `properties`.
+   * Builds the assistant message that contains optional text plus one or more tool-call parts,
+   * matching the shape AI SDK emits between steps.
    */
-  createJsonSchemaRecord(inputSchema: ZodSchemaAny, options: Readonly<{
-    schemaName: string;
-    requireObjectRoot: boolean;
-  }>): Record<string, unknown>;
+  static createAssistantWithToolCalls(text: string | undefined, toolCalls: ReadonlyArray<AgentToolCall>): AssistantModelMessage;
   /**
-   * `@cfworker/json-schema` iterates `schema.required` with `for...of`; it must be a string array or absent.
+   * Builds the `{ role: "tool", content: [{ type: "tool-result", ... }, ...] }` message returned
+   * to the model after each tool round.
    */
-  private sanitizeJsonSchemaRequiredKeywordsForCfworker;
+  static createToolResultsMessage(executedToolCalls: ReadonlyArray<ExecutedToolCall>): ToolModelMessage;
+  private static toToolResultJson;
+  private static createPromptMessage;
+}
+//#endregion
+//#region src/nodes/AgentOutputFactory.d.ts
+declare class AgentOutputFactory {
+  static fromUnknown(value: unknown): NodeOutputs;
+  static replaceJson(item: Item, value: unknown): Item;
+  static fromAgentContent(content: string): unknown;
 }
 //#endregion
 //#region src/nodes/AgentStructuredOutputRepairPromptFactory.d.ts
@@ -1195,26 +1925,46 @@ declare class AgentStructuredOutputRepairPromptFactory {
 }
 //#endregion
 //#region src/nodes/AgentStructuredOutputRunner.d.ts
+type StructuredOutputSchemaForModel = ZodSchemaAny | Readonly<Record<string, unknown>>;
+/**
+ * Orchestrates a 2-attempt repair loop on top of `generateText({ output: Output.object(...) })`.
+ *
+ * Strategy:
+ * 1. If the caller already has a raw final text (from a prior tool-calling turn), try parsing it
+ *    directly against the schema — fast path for models that already emit strict JSON.
+ * 2. Otherwise, run a native structured-output call via {@link invokeStructuredModel}. For the
+ *    OpenAI-strict path, a {@link OpenAiStrictJsonSchemaFactory}-built JSON Schema record is
+ *    handed to AI SDK's `jsonSchema(...)` wrapper (preserves `additionalProperties: false` at
+ *    every object depth).
+ * 3. If the structured call fails (AI_NoObjectGeneratedError / ZodError / schema reject), run a
+ *    text-mode repair prompt with the validation error appended, up to 2 attempts.
+ */
 declare class AgentStructuredOutputRunner {
   private readonly repairPromptFactory;
-  private readonly openAiStructuredOutputMethodFactory;
+  private readonly openAiStrictJsonSchemaFactory;
   private static readonly repairAttemptCount;
-  constructor(repairPromptFactory: AgentStructuredOutputRepairPromptFactory, openAiStructuredOutputMethodFactory: OpenAIStructuredOutputMethodFactory);
+  private static readonly structuredOutputSchemaName;
+  constructor(repairPromptFactory: AgentStructuredOutputRepairPromptFactory, openAiStrictJsonSchemaFactory: OpenAiStrictJsonSchemaFactory);
   resolve<TOutput>(args: Readonly<{
-    model: LangChainChatModelLike;
+    model: ChatLanguageModel;
     chatModelConfig: ChatModelConfig;
     schema: ZodSchemaAny;
-    conversation: ReadonlyArray<BaseMessage>;
-    rawFinalResponse?: AIMessage;
+    conversation: ReadonlyArray<ModelMessage>;
+    rawFinalText?: string;
     agentName: string;
     nodeId: string;
-    invokeTextModel: (messages: ReadonlyArray<BaseMessage>) => Promise<AIMessage>;
-    invokeStructuredModel: (model: LangChainStructuredOutputModelLike, messages: ReadonlyArray<BaseMessage>) => Promise<unknown>;
+    invokeTextModel: (messages: ReadonlyArray<ModelMessage>) => Promise<{
+      text: string;
+    }>;
+    invokeStructuredModel: (schema: StructuredOutputSchemaForModel, messages: ReadonlyArray<ModelMessage>, options: StructuredOutputOptions | undefined) => Promise<unknown>;
   }>): Promise<TOutput>;
   private retryWithRepairPrompt;
-  private createStructuredOutputModel;
-  private getStructuredOutputOptions;
-  private supportsNativeStructuredOutput;
+  /**
+   * Chooses strict mode for OpenAI chat-model configs, off otherwise.  Extendable in future for
+   * other providers that adopt the same "supply a JSON Schema record directly" contract.
+   */
+  private resolveStructuredOutputOptions;
+  private resolveOutputSchemaForModel;
   private tryParseAndValidate;
   private tryValidateStructuredValue;
   private summarizeError;
@@ -1321,7 +2071,6 @@ declare class AgentToolExecutionCoordinator {
   private createRepairPayload;
   private createRepairDetails;
   private createValidationMessage;
-  private parseToolOutput;
   private toJsonValue;
   private extractErrorDetails;
   private serializeIssue;
@@ -1347,8 +2096,24 @@ declare class NodeBackedToolRuntime {
   private readonly itemExprResolver;
   private readonly outputNormalizer;
   private readonly outputBehaviorResolver;
-  constructor(nodeResolver: NodeResolver, itemExprResolver: ItemExprResolver, outputNormalizer: NodeOutputNormalizer, outputBehaviorResolver: RunnableOutputBehaviorResolver);
+  private readonly childExecutionScopeFactory;
+  constructor(nodeResolver: NodeResolver, itemExprResolver: ItemExprResolver, outputNormalizer: NodeOutputNormalizer, outputBehaviorResolver: RunnableOutputBehaviorResolver, childExecutionScopeFactory: ChildExecutionScopeFactory);
   execute(config: NodeBackedToolConfig<any, ZodSchemaAny, ZodSchemaAny>, args: ToolExecuteArgs): Promise<unknown>;
+  /**
+   * Returns a re-rooted child ctx for nested-agent tools (so their LLM/tool connection ids derive
+   * from the tool connection node, telemetry parents under the tool-call span, and connection
+   * invocations carry `parentInvocationId`). Plain runnable tools (non-agent) keep the orchestrator
+   * ctx with only `config` swapped — no nesting concern.
+   *
+   * The caller (`AIAgentNode.createItemScopedTools`) already wraps the orchestrator ctx via
+   * `ConnectionCredentialExecutionContextFactory.forConnectionNode`, so `args.ctx.nodeId` is the
+   * tool's own connection node id (e.g. `AIAgentNode:2__conn__tool__searchInMail`). We pass that
+   * through as the sub-agent's `nodeId`; deriving another `toolConnectionNodeId(args.ctx.nodeId,
+   * config.name)` here would prepend a duplicate `__conn__tool__<name>` segment and exponentially
+   * deepen ids on each invocation, which also breaks credential resolution because user-provided
+   * bindings sit on the single-level connection node id.
+   */
+  private resolveNodeCtx;
   private executeResolvedNode;
   private isRunnableNode;
   private isMultiInputNode;
@@ -1363,28 +2128,21 @@ declare class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
   private readonly toolExecutionCoordinator;
   kind: "node";
   outputPorts: readonly ["main"];
-  /**
-   * Engine validates {@link RunnableNodeConfig.inputSchema} (Zod) on {@code item.json} before enqueue, then resolves
-   * per-item **`itemExpr`** leaves on config before {@link #execute}. Prefer modeling prompts as
-   * {@code { messages: [{ role, content }, ...] }} (on input or config) so persisted inputs are visible in the UI.
-   */
   readonly inputSchema: z.ZodUnknown;
   private readonly connectionCredentialExecutionContextFactory;
-  /** One resolved model/tools bundle per activation context (same ctx across items in a batch). */
   private readonly preparedByExecutionContext;
   constructor(nodeResolver: NodeResolver, credentialSessions: CredentialSessionService, nodeBackedToolRuntime: NodeBackedToolRuntime, executionHelpers: AIAgentExecutionHelpersFactory, structuredOutputRunner: AgentStructuredOutputRunner, toolExecutionCoordinator: AgentToolExecutionCoordinator);
   execute(args: RunnableNodeExecuteArgs<AIAgent<any, any>>): Promise<unknown>;
   private getOrPrepareExecution;
-  /**
-   * Resolves the chat model and tools once per activation, then reuses for every item in the batch.
-   */
   private prepareExecution;
-  /**
-   * One item: build prompts, optionally bind tools, run the multi-turn loop, map the final model message to workflow JSON.
-   */
   private runAgentForItem;
   /**
-   * Repeatedly invokes the model until it returns without tool calls, or guardrails end the loop.
+   * Multi-turn loop:
+   * - Each turn is a single `generateText` call with tools exposed but **not auto-executed**
+   *   (we control tool dispatch so that {@link AgentToolExecutionCoordinator} drives repair /
+   *   connection-invocation recording / transient-error handling exactly like before).
+   * - When the model returns no tool calls the loop ends with the model's text as the final answer.
+   * - Respects `guardrails.maxTurns` and `guardrails.onTurnLimitReached`.
    */
   private runTurnLoopUntilFinalAnswer;
   private cannotExecuteAnotherToolRound;
@@ -1392,20 +2150,52 @@ declare class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
   private appendAssistantAndToolMessages;
   private resolveFinalOutputJson;
   private buildOutputItem;
-  private bindToolsToModel;
   private resolveTools;
   private createItemScopedTools;
-  private invokeModel;
-  private invokeStructuredModel;
+  /**
+   * Builds an AI SDK {@link ToolSet} where every tool ships a pre-converted JSON Schema (via
+   * {@link jsonSchema}) — not the raw Zod schema — and carries **no** `execute`. Two reasons:
+   *
+   * 1. Codemation owns tool dispatch + the per-tool repair loop (see {@link AgentToolExecutionCoordinator}),
+   *    so the AI SDK must surface tool calls back to us instead of auto-running them.
+   * 2. The AI SDK's `asSchema` helper discriminates between Zod v3 / Zod v4 / Standard Schema via
+   *    runtime feature-detection (`~standard`, `_zod`, etc.). Handing it a pre-built
+   *    {@link jsonSchema} record — which is tagged with `Symbol.for('vercel.ai.schema')` — skips all
+   *    of that detection and guarantees the provider receives a draft-07 JSON Schema with
+   *    `additionalProperties: false` at every object depth (see {@link OpenAiStrictJsonSchemaFactory}
+   *    for the same logic applied to structured-output schemas). Codemation still runs its own Zod
+   *    validation on tool inputs before execute — the schema handed to the model is advisory.
+   */
+  private buildToolSet;
+  /**
+   * One `generateText` turn (no auto tool execution) with Codemation-owned child-span telemetry
+   * and connection-invocation state recording.
+   */
+  private invokeTextTurn;
+  /**
+   * Structured-output turn: runs `generateText({ output: Output.object({ schema }) })` via the
+   * structured-output runner.  We keep this as a separate helper because the runner needs the raw
+   * validated value (not just text) back, and must be able to retry on Zod failures.
+   */
+  private invokeStructuredTurn;
+  private isZodSchema;
+  private resolveCallOptions;
+  /**
+   * 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;
+  private extractTurnResult;
+  private extractAssistantMessage;
+  private extractUsageFromResult;
+  private toFiniteNumber;
   private createModelInvocationSpan;
   private recordModelUsageMetrics;
   private captureCostTrackingUsage;
   private resolveChatModelName;
-  private extractModelUsageMetrics;
-  private extractUsageObject;
-  private readUsageNumber;
-  private readNestedUsageValue;
-  private isRecord;
   private markQueuedTools;
   private planToolCalls;
   private failTrackedNodeInvocation;
@@ -1413,21 +2203,59 @@ declare class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
   private resultToJsonValue;
   private createPromptMessages;
   private resolveToolRuntime;
-  /**
-   * Consumer apps can resolve two copies of `@codemation/core`, breaking `instanceof NodeBackedToolConfig` and
-   * sending node-backed tools down the plugin-tool branch with `inputSchema: undefined` (LangChain then crashes in
-   * json-schema validation). {@link NodeBackedToolConfig#toolKind} is stable across copies.
-   */
   private isNodeBackedToolConfig;
-  /**
-   * Callable tools use {@link CallableToolConfig#toolKind} for cross-package / JSON round-trip safety.
-   */
   private isCallableToolConfig;
   private resolveGuardrails;
   private getAgentDisplayName;
   private extractErrorDetails;
 }
 //#endregion
+//#region src/nodes/AssertionNode.d.ts
+/**
+ * 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.
+ */
+declare class AssertionNode implements RunnableNode<Assertion<any>> {
+  kind: "node";
+  outputPorts: readonly ["main"];
+  execute(args: RunnableNodeExecuteArgs<Assertion<any>>): Promise<unknown>;
+}
+//#endregion
+//#region src/nodes/assertion.d.ts
+interface AssertionOptions<TInputJson$1> {
+  readonly name?: string;
+  readonly id?: string;
+  readonly icon?: string;
+  /**
+   * Author callback. Returns one or more {@link AssertionResult}s per input item. Each becomes
+   * one emitted output item — useful for per-row reporting in the Tests tab. Return `[]` to
+   * emit nothing for this case (rare; usually you want at least a "no-op" pass).
+   */
+  assertions(item: Item<TInputJson$1>, ctx: NodeExecutionContext<Assertion<TInputJson$1>>): Promise<ReadonlyArray<AssertionResult>> | ReadonlyArray<AssertionResult>;
+}
+/**
+ * Generic assertion node — the "callback" form. For declarative shorthands (StringEquals,
+ * JudgeByAgent) compose this with helpers added in later phases. Sets `emitsAssertions: true`
+ * so host-side persisters know to record its outputs as `TestAssertion` rows.
+ */
+declare class Assertion<TInputJson$1 = unknown> implements RunnableNodeConfig<TInputJson$1, AssertionResult> {
+  readonly kind: "node";
+  readonly type: TypeToken<unknown>;
+  readonly icon: string;
+  readonly name: string;
+  readonly id?: string;
+  readonly emitsAssertions: true;
+  readonly assertions: AssertionOptions<TInputJson$1>["assertions"];
+  constructor(options: AssertionOptions<TInputJson$1>);
+}
+//#endregion
 //#region src/nodes/CallbackNode.d.ts
 declare class CallbackNode implements RunnableNode<Callback<any, any>> {
   kind: "node";
@@ -1472,10 +2300,12 @@ declare class HttpRequestNode implements RunnableNode<HttpRequest<any, any>> {
   readonly outputPorts: readonly ["main"];
   execute(args: RunnableNodeExecuteArgs<HttpRequest<any, any>>): Promise<unknown>;
   private executeItem;
+  private resolveCredential;
   private resolveUrl;
   private asRecord;
   private readHeaders;
   private resolveMimeType;
+  private isJsonMimeType;
   private shouldAttachBody;
   private resolveFilename;
   private readFilenameFromContentDisposition;
@@ -1492,15 +2322,41 @@ type HttpRequestOutputJson = Readonly<{
   statusText: string;
   mimeType: string;
   headers: Readonly<Record<string, string>>;
+  json?: unknown;
+  text?: string;
   bodyBinaryName?: string;
 }>;
+/**
+ * The built-in HTTP request credential type IDs accepted by the `HttpRequest` node.
+ * These match the four generic credential types shipped with `@codemation/core-nodes`.
+ */
+declare const HTTP_REQUEST_ACCEPTED_CREDENTIAL_TYPES: ReadonlyArray<string>;
 declare class HttpRequest<TInputJson$1 = Readonly<{
   url?: string;
 }>, TOutputJson$1 = HttpRequestOutputJson> implements RunnableNodeConfig<TInputJson$1, TOutputJson$1> {
   readonly name: string;
   readonly args: Readonly<{
+    /** HTTP method (default: GET). */
     method?: string;
+    /**
+     * Legacy: field name on item.json to read the URL from.
+     * Use `url` for a literal/templated URL instead.
+     */
     urlField?: string;
+    /** Literal or templated URL. When present, takes precedence over `urlField`. */
+    url?: string;
+    /** Extra headers to add to every request. */
+    headers?: Readonly<Record<string, string>>;
+    /** Query parameters to append to the URL. */
+    query?: Readonly<Record<string, string>>;
+    /** Request body specification. For canvas use, pass a JSON string in `body.data`. */
+    body?: HttpBodySpec;
+    /**
+     * Credential slot key. When set, the node resolves a credential via
+     * `ctx.getCredential(credentialSlot)` and applies it to the request.
+     * The slot must be declared in `getCredentialRequirements()`.
+     */
+    credentialSlot?: string;
     binaryName?: string;
     downloadMode?: HttpRequestDownloadMode;
     id?: string;
@@ -1511,9 +2367,29 @@ declare class HttpRequest<TInputJson$1 = Readonly<{
   readonly execution: {
     readonly hint: "local";
   };
+  readonly icon: "lucide:globe";
   constructor(name: string, args?: Readonly<{
+    /** HTTP method (default: GET). */
     method?: string;
+    /**
+     * Legacy: field name on item.json to read the URL from.
+     * Use `url` for a literal/templated URL instead.
+     */
     urlField?: string;
+    /** Literal or templated URL. When present, takes precedence over `urlField`. */
+    url?: string;
+    /** Extra headers to add to every request. */
+    headers?: Readonly<Record<string, string>>;
+    /** Query parameters to append to the URL. */
+    query?: Readonly<Record<string, string>>;
+    /** Request body specification. For canvas use, pass a JSON string in `body.data`. */
+    body?: HttpBodySpec;
+    /**
+     * Credential slot key. When set, the node resolves a credential via
+     * `ctx.getCredential(credentialSlot)` and applies it to the request.
+     * The slot must be declared in `getCredentialRequirements()`.
+     */
+    credentialSlot?: string;
     binaryName?: string;
     downloadMode?: HttpRequestDownloadMode;
     id?: string;
@@ -1523,6 +2399,7 @@ declare class HttpRequest<TInputJson$1 = Readonly<{
   get urlField(): string;
   get binaryName(): string;
   get downloadMode(): HttpRequestDownloadMode;
+  getCredentialRequirements(): ReadonlyArray<CredentialRequirement>;
 }
 //#endregion
 //#region src/nodes/AggregateNode.d.ts
@@ -1543,7 +2420,7 @@ declare class Aggregate<TIn = unknown, TOut = unknown> implements RunnableNodeCo
     readonly hint: "local";
   };
   readonly keepBinaries: true;
-  readonly icon: "lucide:layers";
+  readonly icon: "builtin:aggregate-rows";
   constructor(name: string, aggregate: (items: Items<TIn>, ctx: NodeExecutionContext<Aggregate<TIn, TOut>>) => TOut | Promise<TOut>, id?: string | undefined);
 }
 //#endregion
@@ -1584,11 +2461,43 @@ declare class If<TInputJson$1 = unknown> implements RunnableNodeConfig<TInputJso
   readonly execution: {
     readonly hint: "local";
   };
-  readonly icon: "lucide:split";
+  readonly icon: "lucide:split@rot=90";
   readonly declaredOutputPorts: readonly ["true", "false"];
   constructor(name: string, predicate: (item: Item<TInputJson$1>, index: number, items: Items<TInputJson$1>, ctx: NodeExecutionContext<If<TInputJson$1>>) => boolean, id?: string | undefined);
 }
 //#endregion
+//#region src/nodes/IsTestRunNode.d.ts
+/**
+ * Routes each item to the `true` port if `ctx.testContext` is set (the run was started by the
+ * TestSuiteOrchestrator), else to `false`. Lets workflow authors guard real side-effects:
+ *
+ *   GmailTrigger / TestTrigger → ClassifyAgent → IsTestRun
+ *                                                 ├── true → AssertionNode
+ *                                                 └── false → SendReply
+ */
+declare class IsTestRunNode implements RunnableNode<IsTestRun<unknown>> {
+  kind: "node";
+  execute(args: RunnableNodeExecuteArgs<IsTestRun<unknown>>): unknown;
+}
+//#endregion
+//#region src/nodes/isTestRun.d.ts
+/**
+ * Branches per-item on whether the current run is a test run. Output ports: `true`, `false`.
+ * The wire payload is unchanged — this is a router, not a transform.
+ */
+declare class IsTestRun<TInputJson$1 = unknown> implements RunnableNodeConfig<TInputJson$1, TInputJson$1> {
+  readonly kind: "node";
+  readonly type: TypeToken<unknown>;
+  readonly execution: {
+    readonly hint: "local";
+  };
+  readonly icon: "lucide:flask-conical";
+  readonly declaredOutputPorts: readonly ["true", "false"];
+  readonly name: string;
+  readonly id?: string;
+  constructor(name?: string, id?: string);
+}
+//#endregion
 //#region src/nodes/SwitchNode.d.ts
 /**
  * Routes each item to exactly one output port. Port names must match workflow edges (see {@link Switch} config).
@@ -1645,10 +2554,49 @@ declare class Split<TIn = unknown, TElem = unknown> implements RunnableNodeConfi
    * Mirrors {@link MapData}'s empty-output behavior.
    */
   readonly continueWhenEmptyOutput: true;
-  readonly icon: "lucide:ungroup";
+  readonly icon: "builtin:split-rows";
   constructor(name: string, getElements: (item: Item<TIn>, ctx: NodeExecutionContext<Split<TIn, TElem>>) => readonly TElem[], id?: string | undefined);
 }
 //#endregion
+//#region src/nodes/CronTriggerFactory.d.ts
+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.
+ */
+declare class CronTrigger implements TriggerNodeConfig<CronTickJson> {
+  readonly name: string;
+  private readonly args;
+  readonly kind: "trigger";
+  readonly type: TypeToken<unknown>;
+  readonly icon: "lucide:clock";
+  readonly id?: string;
+  constructor(name: string, args: Readonly<{
+    schedule: string;
+    timezone?: string;
+  }>, id?: string);
+  get schedule(): string;
+  get timezone(): string | undefined;
+  createJob(callback: CronCallback): Cron;
+}
+//#endregion
+//#region src/nodes/CronTriggerNode.d.ts
+declare class CronTriggerNode implements TestableTriggerNode<CronTrigger> {
+  readonly kind: "trigger";
+  readonly outputPorts: readonly ["main"];
+  setup(ctx: TriggerSetupContext<CronTrigger>): Promise<undefined>;
+  execute(items: Items, _ctx: NodeExecutionContext<CronTrigger>): Promise<NodeOutputs>;
+  getTestItems(ctx: TriggerTestItemsContext<CronTrigger>): Promise<Items>;
+}
+//#endregion
 //#region src/nodes/ManualTriggerNode.d.ts
 /**
  * Setup is intentionally a no-op: the engine host can run workflows manually
@@ -1705,6 +2653,7 @@ declare class MapData<TInputJson$1 = unknown, TOutputJson$1 = unknown> implement
   };
   /** Zero mapped items should still allow downstream nodes to run. */
   readonly continueWhenEmptyOutput: true;
+  readonly icon: "lucide:square-pen";
   readonly keepBinaries: boolean;
   constructor(name: string, map: (item: Item<TInputJson$1>, ctx: NodeExecutionContext<MapData<TInputJson$1, TOutputJson$1>>) => TOutputJson$1, options?: MapDataOptions);
   get id(): string | undefined;
@@ -1732,7 +2681,7 @@ declare class Merge<TInputJson$1 = unknown, TOutputJson$1 = TInputJson$1> implem
   readonly id?: string | undefined;
   readonly kind: "node";
   readonly type: TypeToken<unknown>;
-  readonly icon: "lucide:git-merge";
+  readonly icon: "lucide:merge@rot=90";
   constructor(name: string, cfg?: Readonly<{
     mode: MergeMode;
     /**
@@ -1759,6 +2708,7 @@ declare class NoOp<TItemJson = unknown> implements RunnableNodeConfig<TItemJson,
   readonly execution: {
     readonly hint: "local";
   };
+  readonly icon: "lucide:circle-dashed";
   constructor(name?: string, id?: string | undefined);
 }
 //#endregion
@@ -1787,6 +2737,71 @@ declare class SubWorkflow<TInputJson$1 = unknown, TOutputJson$1 = unknown> imple
   } | UpstreamRefPlaceholder> | undefined, startAt?: NodeId | undefined, id?: string | undefined);
 }
 //#endregion
+//#region src/nodes/TestTriggerNode.d.ts
+/**
+ * Author-defined test-fixture trigger. Live activation skips this trigger (filtered by
+ * `triggerKind === "test"` in `TriggerRuntimeService`); the `TestSuiteOrchestrator` drives its
+ * `generateItems` callback during a TestSuiteRun and dispatches one workflow run per yielded item.
+ *
+ * `setup` is intentionally a no-op for symmetry with other trigger nodes — the real work happens
+ * in the orchestrator. `execute` is a passthrough so items provided to `engine.runWorkflow(...)`
+ * (one per case) flow downstream unchanged on `main`.
+ */
+declare class TestTriggerNode implements TriggerNode<TestTriggerNodeConfig<any>> {
+  kind: "trigger";
+  outputPorts: readonly ["main"];
+  setup(_ctx: TriggerSetupContext<TestTriggerNodeConfig<any>>): Promise<undefined>;
+  execute(items: Items, _ctx: NodeExecutionContext<TestTriggerNodeConfig<any>>): Promise<NodeOutputs>;
+}
+//#endregion
+//#region src/nodes/testTrigger.d.ts
+interface TestTriggerOptions<TOutputJson$1> {
+  readonly name?: string;
+  readonly id?: string;
+  readonly icon?: string;
+  /** Cap on simultaneous in-flight test cases for one suite run. Default: 4 (orchestrator). */
+  readonly concurrency?: number;
+  readonly credentialRequirements?: ReadonlyArray<CredentialRequirement>;
+  /**
+   * Free-form description of where the test cases come from. Shown in the node properties
+   * panel and the Tests-tab suite-detail header so authors revisiting the workflow six months
+   * later remember which mailbox / folder / fixture file the cases originate from.
+   */
+  readonly description?: string;
+  /**
+   * Author callback that yields one item per test case. Items are dispatched as separate
+   * workflow runs by the TestSuiteOrchestrator, with `executionOptions.testContext` set.
+   * The provided context exposes credential resolution and an AbortSignal for cancellation.
+   */
+  generateItems(ctx: TestTriggerSetupContext<TestTrigger<TOutputJson$1>>): AsyncIterable<Item<TOutputJson$1>>;
+  /**
+   * Optional resolver: extract a human-readable label from a yielded item. The orchestrator
+   * persists this on the run, so the Tests-tab tree-table shows e.g. "RFQ for batch 14"
+   * instead of an opaque runId. Typical use: `(item) => item.json.subject` for mailbox tests.
+   */
+  caseLabel?(item: Item<TOutputJson$1>): string | undefined;
+}
+/**
+ * Trigger config for a test fixture source. Drop one (or more) of these on the canvas alongside
+ * a workflow's live triggers; clicking "Run tests" on the Tests tab invokes
+ * {@link TestTriggerOptions.generateItems} via the TestSuiteOrchestrator.
+ */
+declare class TestTrigger<TOutputJson$1 = unknown> implements TestTriggerNodeConfig<TOutputJson$1> {
+  readonly kind: "trigger";
+  readonly triggerKind: "test";
+  readonly type: TypeToken<unknown>;
+  readonly icon: string;
+  readonly name: string;
+  readonly id?: string;
+  readonly concurrency?: number;
+  readonly description?: string;
+  readonly generateItems: TestTriggerOptions<TOutputJson$1>["generateItems"];
+  readonly caseLabel?: TestTriggerOptions<TOutputJson$1>["caseLabel"];
+  private readonly credentialRequirements;
+  constructor(options: TestTriggerOptions<TOutputJson$1>);
+  getCredentialRequirements(): ReadonlyArray<CredentialRequirement>;
+}
+//#endregion
 //#region src/nodes/WaitDurationFactory.d.ts
 declare class WaitDuration {
   static normalize(milliseconds: number): number;
@@ -1811,6 +2826,7 @@ declare class Wait<TItemJson = unknown> implements RunnableNodeConfig<TItemJson,
   };
   /** Pass-through empty batches should still advance to downstream nodes. */
   readonly continueWhenEmptyOutput: true;
+  readonly icon: "lucide:hourglass";
   constructor(name: string, milliseconds: number, id?: string | undefined);
 }
 //#endregion
@@ -1841,7 +2857,7 @@ declare class WebhookTrigger<TSchema extends WebhookInputSchema | undefined = un
   readonly id?: string | undefined;
   readonly kind: "trigger";
   readonly type: TypeToken<unknown>;
-  readonly icon = "lucide:globe";
+  readonly icon = "lucide:webhook";
   constructor(name: string, args: Readonly<{
     endpointKey: string;
     methods: ReadonlyArray<HttpMethod>;
@@ -2030,5 +3046,67 @@ declare class AIAgentConnectionWorkflowExpander {
   private assertNoIdCollision;
 }
 //#endregion
-export { AIAgent, AIAgentConnectionWorkflowExpander, AIAgentExecutionHelpersFactory, AIAgentNode, AgentItemPortMap, AgentMessageFactory, AgentOutputFactory, AgentStructuredOutputRepairPromptFactory, AgentStructuredOutputRunner, AgentToolCallPortMap, AgentToolErrorClassifier, AgentToolExecutionCoordinator, AgentToolRepairExhaustedError, AgentToolRepairPolicy, Aggregate, AggregateNode, Callback, CallbackHandler, CallbackNode, CallbackOptions, CallbackResultNormalizer, CanvasIconName, ConnectionCredentialExecutionContextFactory, ConnectionCredentialNode, ConnectionCredentialNodeConfig, ConnectionCredentialNodeConfigFactory, ExecutedToolCall, Filter, FilterNode, HttpRequest, HttpRequestDownloadMode, HttpRequestNode, HttpRequestOutputJson, If, IfNode, ItemScopedToolBinding, ManualTrigger, ManualTriggerNode, MapData, MapDataNode, MapDataOptions, Merge, MergeMode, MergeNode, NoOp, NoOpNode, OpenAIChatModelConfig, OpenAIChatModelFactory, OpenAIStructuredOutputMethodFactory, OpenAiChatModelPresets, OpenAiCredentialSession, PlannedToolCall, ResolvedTool, Split, SplitNode, SubWorkflow, SubWorkflowNode, Switch, SwitchCaseKeyResolver, SwitchNode, Wait, WaitDuration, WaitNode, WebhookRespondNowAndContinueError, WebhookRespondNowError, WebhookTrigger, WebhookTriggerNode, type WorkflowAgentMessages, type WorkflowAgentOptions, WorkflowAuthoringBuilder, WorkflowBranchBuilder, WorkflowChain, createWorkflowBuilder, openAiChatModelPresets, registerCoreNodes, workflow };
+//#region src/nodes/collections/collectionInsertNode.types.d.ts
+declare const collectionInsertNode: DefinedNode<"collection-insert", {
+  collectionName: string;
+  data: Record<string, unknown>;
+}, unknown, Record<string, unknown> & {
+  id: string;
+  created_at: Date;
+  updated_at: Date;
+}, undefined>;
+//#endregion
+//#region src/nodes/collections/collectionGetNode.types.d.ts
+declare const collectionGetNode: DefinedNode<"collection-get", {
+  collectionName: string;
+  id: string;
+}, unknown, never[] | (Record<string, unknown> & {
+  id: string;
+  created_at: Date;
+  updated_at: Date;
+}), undefined>;
+//#endregion
+//#region src/nodes/collections/collectionFindOneNode.types.d.ts
+declare const collectionFindOneNode: DefinedNode<"collection-find-one", {
+  collectionName: string;
+  where: Record<string, unknown>;
+}, unknown, never[] | (Record<string, unknown> & {
+  id: string;
+  created_at: Date;
+  updated_at: Date;
+}), undefined>;
+//#endregion
+//#region src/nodes/collections/collectionListNode.types.d.ts
+declare const collectionListNode: DefinedNode<"collection-list", {
+  collectionName: string;
+  limit?: number | undefined;
+  offset?: number | undefined;
+  where?: Record<string, unknown> | undefined;
+}, unknown, (Record<string, unknown> & {
+  id: string;
+  created_at: Date;
+  updated_at: Date;
+})[], undefined>;
+//#endregion
+//#region src/nodes/collections/collectionUpdateNode.types.d.ts
+declare const collectionUpdateNode: DefinedNode<"collection-update", {
+  collectionName: string;
+  id: string;
+  patch: Record<string, unknown>;
+}, unknown, Record<string, unknown> & {
+  id: string;
+  created_at: Date;
+  updated_at: Date;
+}, undefined>;
+//#endregion
+//#region src/nodes/collections/collectionDeleteNode.types.d.ts
+declare const collectionDeleteNode: DefinedNode<"collection-delete", {
+  collectionName: string;
+  id: string;
+}, unknown, {
+  deleted: boolean;
+  id: string;
+}, undefined>;
+//#endregion
+export { AIAgent, AIAgentConnectionWorkflowExpander, AIAgentExecutionHelpersFactory, AIAgentNode, AgentItemPortMap, AgentMessageFactory, AgentOutputFactory, AgentStructuredOutputRepairPromptFactory, AgentStructuredOutputRunner, AgentToolCallPortMap, AgentToolErrorClassifier, AgentToolExecutionCoordinator, AgentToolRepairExhaustedError, AgentToolRepairPolicy, Aggregate, AggregateNode, Assertion, AssertionNode, AssertionOptions, BinaryRef, Callback, CallbackHandler, CallbackNode, CallbackOptions, CallbackResultNormalizer, CanvasIconName, ConnectionCredentialExecutionContextFactory, ConnectionCredentialNode, ConnectionCredentialNodeConfig, ConnectionCredentialNodeConfigFactory, CredentialSession, CronTickJson, CronTrigger, CronTriggerNode, DefineRestNodeOptions, ExecutedToolCall, Filter, FilterNode, HTTP_REQUEST_ACCEPTED_CREDENTIAL_TYPES, HttpBodySpec, HttpCredentialDelta, HttpRequest, HttpRequestDownloadMode, HttpRequestNode, HttpRequestOutputJson, HttpRequestResult, HttpRequestSpec, If, IfNode, IsTestRun, IsTestRunNode, ItemScopedToolBinding, ManualTrigger, ManualTriggerNode, MapData, MapDataNode, MapDataOptions, Merge, MergeMode, MergeNode, NoOp, NoOpNode, OpenAIChatModelConfig, OpenAIChatModelFactory, OpenAiChatModelPresets, OpenAiCredentialSession, OpenAiStrictJsonSchemaFactory, PlannedToolCall, ResolvedTool, RestNodeApi, RestNodeErrorPolicy, RestNodeRequestShape, RestNodeResponseContext, Split, SplitNode, SubWorkflow, SubWorkflowNode, Switch, SwitchCaseKeyResolver, SwitchNode, TestTrigger, TestTriggerNode, TestTriggerOptions, Wait, WaitDuration, WaitNode, WebhookRespondNowAndContinueError, WebhookRespondNowError, WebhookTrigger, WebhookTriggerNode, type WorkflowAgentMessages, type WorkflowAgentOptions, WorkflowAuthoringBuilder, WorkflowBranchBuilder, WorkflowChain, apiKeyCredentialType, basicAuthCredentialType, bearerTokenCredentialType, collectionDeleteNode, collectionFindOneNode, collectionGetNode, collectionInsertNode, collectionListNode, collectionUpdateNode, createWorkflowBuilder, defineRestNode, oauth2ClientCredentialsType, openAiChatModelPresets, registerCoreNodes, workflow };
 //# sourceMappingURL=index.d.cts.map