@codemation/core 0.8.0 → 0.10.0

package/src/bootstrap/runtime/EngineRuntimeRegistrar.ts

@@ -2,6 +2,7 @@ import { instanceCachingFactory, type DependencyContainer } from "../../di";
 import { CoreTokens } from "../../di";
 import { EngineExecutionLimitsPolicyFactory } from "../../policies/executionLimits/EngineExecutionLimitsPolicyFactory";
 import {
+  ChildExecutionScopeFactory,
   DefaultAsyncSleeper,
   InProcessRetryRunnerFactory,
   ItemExprResolver,
@@ -50,19 +51,25 @@ export class EngineRuntimeRegistrar {
     if (!container.isRegistered(RunnableOutputBehaviorResolver, true)) {
       container.registerSingleton(RunnableOutputBehaviorResolver, RunnableOutputBehaviorResolver);
     }
-    container.register(EngineExecutionLimitsPolicyFactory, { useClass: EngineExecutionLimitsPolicyFactory });
-    container.register(NodeInstanceFactoryFactory, { useClass: NodeInstanceFactoryFactory });
-    container.register(DefaultAsyncSleeper, { useClass: DefaultAsyncSleeper });
-    container.register(InProcessRetryRunnerFactory, { useClass: InProcessRetryRunnerFactory });
-    container.register(NodeExecutorFactory, { useClass: NodeExecutorFactory });
-    container.register(InlineDrivingSchedulerFactory, { useClass: InlineDrivingSchedulerFactory });
-    container.register(RunIntentServiceFactory, { useClass: RunIntentServiceFactory });
-    container.register(EngineWorkflowRunnerServiceFactory, {
-      useClass: EngineWorkflowRunnerServiceFactory,
-    });
-    container.register(WorkflowRepositoryWebhookTriggerMatcherFactory, {
-      useClass: WorkflowRepositoryWebhookTriggerMatcherFactory,
-    });
+    if (!container.isRegistered(ChildExecutionScopeFactory, true)) {
+      container.register(ChildExecutionScopeFactory, {
+        useFactory: instanceCachingFactory((dependencyContainer) => {
+          return new ChildExecutionScopeFactory(dependencyContainer.resolve(CoreTokens.ActivationIdFactory));
+        }),
+      });
+    }
+    container.registerSingleton(EngineExecutionLimitsPolicyFactory, EngineExecutionLimitsPolicyFactory);
+    container.registerSingleton(NodeInstanceFactoryFactory, NodeInstanceFactoryFactory);
+    container.registerSingleton(DefaultAsyncSleeper, DefaultAsyncSleeper);
+    container.registerSingleton(InProcessRetryRunnerFactory, InProcessRetryRunnerFactory);
+    container.registerSingleton(NodeExecutorFactory, NodeExecutorFactory);
+    container.registerSingleton(InlineDrivingSchedulerFactory, InlineDrivingSchedulerFactory);
+    container.registerSingleton(RunIntentServiceFactory, RunIntentServiceFactory);
+    container.registerSingleton(EngineWorkflowRunnerServiceFactory, EngineWorkflowRunnerServiceFactory);
+    container.registerSingleton(
+      WorkflowRepositoryWebhookTriggerMatcherFactory,
+      WorkflowRepositoryWebhookTriggerMatcherFactory,
+    );
   }
 
   private registerExecutionLimitsPolicy(
@@ -133,7 +140,7 @@ export class EngineRuntimeRegistrar {
   }
 
   private registerEngine(container: DependencyContainer, options: EngineRuntimeRegistrationOptions | undefined): void {
-    container.register(EngineFactory, { useClass: EngineFactory });
+    container.registerSingleton(EngineFactory, EngineFactory);
     const matcherProvider = this.resolveMatcherProvider(options);
     container.register(Engine, {
       useFactory: instanceCachingFactory((dependencyContainer) => {

package/src/browser.ts

@@ -9,6 +9,7 @@ export type {
 } from "./ai/AgentConnectionNodeCollector";
 export type { AgentNodeConfig } from "./ai/AiHost";
 export { ConnectionNodeIdFactory } from "./workflow/definition/ConnectionNodeIdFactory";
+export { NodeIterationIdFactory } from "./workflow/definition/NodeIterationIdFactory";
 export * from "./contracts/credentialTypes";
 export * from "./contracts/runtimeTypes";
 export * from "./contracts/runFinishedAtFactory";

package/src/contracts/CodemationTelemetryAttributeNames.ts

@@ -9,4 +9,10 @@ export class CodemationTelemetryAttributeNames {
   static readonly connectionInvocationId = "codemation.connection.invocation_id";
   static readonly toolName = "codemation.tool.name";
   static readonly traceParentRunId = "codemation.parent.run.id";
+  /** Per-item iteration that emitted this span/metric. Set on spans recorded inside a runnable per-item loop. */
+  static readonly iterationId = "codemation.iteration.id";
+  /** Item index (0-based) of the iteration. */
+  static readonly iterationIndex = "codemation.iteration.index";
+  /** Set when this span/metric was recorded under a sub-agent triggered by an outer LLM/tool call. */
+  static readonly parentInvocationId = "codemation.parent.invocation_id";
 }

package/src/contracts/NoOpNodeExecutionTelemetry.ts

@@ -1,15 +1,6 @@
-import type { NodeActivationId, NodeId } from "./workflowTypes";
-import type { NodeExecutionTelemetry, TelemetryChildSpanStart, TelemetrySpanScope } from "./telemetryTypes";
+import type { NodeExecutionTelemetry } from "./telemetryTypes";
 import { NoOpTelemetrySpanScope } from "./NoOpTelemetrySpanScope";
 
 export class NoOpNodeExecutionTelemetry {
-  static readonly value: NodeExecutionTelemetry = {
-    ...NoOpTelemetrySpanScope.value,
-    forNode(_: Readonly<{ nodeId: NodeId; activationId: NodeActivationId }>): NodeExecutionTelemetry {
-      return NoOpNodeExecutionTelemetry.value;
-    },
-    startChildSpan(_: TelemetryChildSpanStart): TelemetrySpanScope {
-      return NoOpTelemetrySpanScope.value;
-    },
-  };
+  static readonly value: NodeExecutionTelemetry = NoOpTelemetrySpanScope.nodeExecutionTelemetryValue;
 }

package/src/contracts/NoOpTelemetrySpanScope.ts

@@ -1,6 +1,9 @@
+import type { NodeActivationId, NodeId } from "./workflowTypes";
 import type {
+  NodeExecutionTelemetry,
   TelemetryArtifactAttachment,
   TelemetryArtifactReference,
+  TelemetryChildSpanStart,
   TelemetryMetricRecord,
   TelemetrySpanEnd,
   TelemetrySpanEventRecord,
@@ -8,15 +11,48 @@ import type {
 } from "./telemetryTypes";
 import { NoOpTelemetryArtifactReference } from "./NoOpTelemetryArtifactReference";
 
+/**
+ * Standalone no-op {@link NodeExecutionTelemetry} value used as the return for `asNodeTelemetry`.
+ *
+ * Defined here (instead of in `NoOpNodeExecutionTelemetry.ts`) so that {@link NoOpTelemetrySpanScope}
+ * can return it without importing the other module — both no-ops share this leaf.
+ */
+const noOpNodeExecutionTelemetry: NodeExecutionTelemetry = {
+  traceId: "00000000000000000000000000000000",
+  spanId: "0000000000000000",
+  addSpanEvent(_: TelemetrySpanEventRecord): void {},
+  recordMetric(_: TelemetryMetricRecord): void {},
+  attachArtifact(_: TelemetryArtifactAttachment): TelemetryArtifactReference {
+    return NoOpTelemetryArtifactReference.value;
+  },
+  end(_: TelemetrySpanEnd = {}): void {},
+  asNodeTelemetry(_: Readonly<{ nodeId: NodeId; activationId: NodeActivationId }>): NodeExecutionTelemetry {
+    return noOpNodeExecutionTelemetry;
+  },
+  forNode(_: Readonly<{ nodeId: NodeId; activationId: NodeActivationId }>): NodeExecutionTelemetry {
+    return noOpNodeExecutionTelemetry;
+  },
+  startChildSpan(_: TelemetryChildSpanStart): TelemetrySpanScope {
+    return noOpTelemetrySpanScope;
+  },
+};
+
+const noOpTelemetrySpanScope: TelemetrySpanScope = {
+  traceId: "00000000000000000000000000000000",
+  spanId: "0000000000000000",
+  addSpanEvent(_: TelemetrySpanEventRecord): void {},
+  recordMetric(_: TelemetryMetricRecord): void {},
+  attachArtifact(_: TelemetryArtifactAttachment): TelemetryArtifactReference {
+    return NoOpTelemetryArtifactReference.value;
+  },
+  end(_: TelemetrySpanEnd = {}): void {},
+  asNodeTelemetry(_: Readonly<{ nodeId: NodeId; activationId: NodeActivationId }>): NodeExecutionTelemetry {
+    return noOpNodeExecutionTelemetry;
+  },
+};
+
 export class NoOpTelemetrySpanScope {
-  static readonly value: TelemetrySpanScope = {
-    traceId: "00000000000000000000000000000000",
-    spanId: "0000000000000000",
-    addSpanEvent(_: TelemetrySpanEventRecord): void {},
-    recordMetric(_: TelemetryMetricRecord): void {},
-    attachArtifact(_: TelemetryArtifactAttachment): TelemetryArtifactReference {
-      return NoOpTelemetryArtifactReference.value;
-    },
-    end(_: TelemetrySpanEnd = {}): void {},
-  };
+  static readonly value: TelemetrySpanScope = noOpTelemetrySpanScope;
+  /** Internal: the shared no-op {@link NodeExecutionTelemetry} that {@link NoOpNodeExecutionTelemetry} re-exposes. */
+  static readonly nodeExecutionTelemetryValue: NodeExecutionTelemetry = noOpNodeExecutionTelemetry;
 }

package/src/contracts/assertionTypes.ts

@@ -0,0 +1,63 @@
+import type { JsonValue, NodeId } from "./workflowTypes";
+
+/**
+ * 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`.
+ */
+export 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>>;
+}
+
+/**
+ * Default {@link AssertionResult.passThreshold} when authors omit it. Boolean-style assertions
+ * (assertEqual / contains / etc.) emit `score: 1` or `score: 0` so this default works for them;
+ * AI-judge assertions are expected to set their own threshold.
+ */
+export const DEFAULT_ASSERTION_PASS_THRESHOLD = 0.5;
+
+/**
+ * Derive whether an assertion result is considered "passing" using the score-based contract:
+ * `errored` always fails, otherwise `score >= (passThreshold ?? 0.5)`. This is the canonical
+ * derivation — UI and rollup code should call it rather than inlining the comparison so future
+ * tweaks (e.g. NaN handling) land in one place.
+ */
+export function deriveAssertionPassed(result: {
+  readonly score: number;
+  readonly passThreshold?: number;
+  readonly errored?: true;
+}): boolean {
+  if (result.errored === true) return false;
+  const threshold = result.passThreshold ?? DEFAULT_ASSERTION_PASS_THRESHOLD;
+  return result.score >= threshold;
+}
+
+/**
+ * Provenance for a persisted {@link AssertionResult}: which node produced it and where in the
+ * per-item iteration tree it landed. Filled in by the host-side persister, not the node itself.
+ */
+export interface AssertionResultProvenance {
+  readonly nodeId: NodeId;
+  /** Per-item iteration id when the emitting node ran inside a per-item loop. */
+  readonly iterationId?: string;
+  /** Item index (0-based) within the activation that produced this assertion. */
+  readonly itemIndex?: number;
+}

package/src/contracts/baseTypes.ts

@@ -0,0 +1,12 @@
+/**
+ * Minimal base types that have no dependencies on other contracts.
+ * Used by credentialTypes, workflowTypes, and other contract layers
+ * to avoid circular dependencies.
+ */
+
+export type WorkflowId = string;
+export type NodeId = string;
+export type OutputPortKey = string;
+export type InputPortKey = string;
+export type PersistedTokenId = string;
+export type NodeConnectionName = string;

package/src/contracts/collectionTypes.ts

@@ -0,0 +1,44 @@
+/**
+ * Represents a typed store for a single collection.
+ * All rows include auto-managed id, created_at, and updated_at fields.
+ */
+export 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.
+ */
+export type CollectionsContext = Readonly<Record<string, CollectionStore>>;

package/src/contracts/credentialTypes.ts

@@ -1,4 +1,4 @@
-import type { NodeId, WorkflowId } from "./workflowTypes";
+import type { NodeId, WorkflowId } from "./baseTypes";
 
 export type CredentialTypeId = string;
 export type CredentialInstanceId = string;
@@ -91,6 +91,28 @@ export type CredentialOAuth2AuthDefinition = Readonly<
       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;
+    }
 >;
 
 export type CredentialAuthDefinition = CredentialOAuth2AuthDefinition;

package/src/contracts/executionPersistenceContracts.ts

@@ -148,6 +148,30 @@ export interface WorkflowRunDetailDto {
   readonly mutableState?: PersistedMutableRunState;
   readonly slotStates: ReadonlyArray<SlotExecutionStateDto>;
   readonly executionInstances: ReadonlyArray<ExecutionInstanceDto>;
+  readonly iterations?: ReadonlyArray<RunIterationDto>;
+}
+
+/**
+ * Per-item iteration projected from connection invocations and node activations.
+ *
+ * One iteration = one item processed by an agent within an activation. Multiple invocations
+ * (LLM rounds, tool calls) belonging to the same iteration share the iterationId.
+ */
+export interface RunIterationDto {
+  readonly iterationId: string;
+  readonly agentNodeId: NodeId;
+  readonly activationId: NodeActivationId;
+  readonly itemIndex: number;
+  readonly itemSummary?: string;
+  readonly status: NodeExecutionStatus;
+  readonly startedAt?: string;
+  readonly finishedAt?: string;
+  readonly invocationIds: ReadonlyArray<string>;
+  readonly parentInvocationId?: string;
+  /** Estimated cost rolled up from telemetry cost metric points, keyed by ISO currency code (e.g. "USD"). Values are minor units (cents-of-cents per the metric's `cost.currency_scale`). */
+  readonly estimatedCostMinorByCurrency?: Readonly<Record<string, number>>;
+  /** Currency scale (denominator) per currency, when present on the metric points. Joined with `estimatedCostMinorByCurrency` to format human-readable amounts. */
+  readonly estimatedCostCurrencyScaleByCurrency?: Readonly<Record<string, number>>;
 }
 
 export interface SlotExecutionStateDto {
@@ -178,6 +202,12 @@ export interface ExecutionInstanceDto {
   readonly inputJson?: JsonValue;
   readonly outputJson?: JsonValue;
   readonly error?: Readonly<NodeExecutionError>;
+  /** Per-item iteration that produced this instance. Set on connectionInvocation rows produced inside per-item runnable loops. */
+  readonly iterationId?: string;
+  /** Item index (0-based) of the iteration. */
+  readonly itemIndex?: number;
+  /** Parent invocation id when this instance was emitted by a sub-agent triggered by an outer LLM/tool call. */
+  readonly parentInvocationId?: string;
 }
 
 export interface WorkflowDetailSelectionState {

package/src/contracts/index.ts

@@ -1,3 +1,6 @@
+export * from "./baseTypes";
+export * from "./assertionTypes";
+export * from "./collectionTypes";
 export * from "./credentialTypes";
 export * from "./emitPorts";
 export * from "./executionPersistenceContracts";
@@ -6,6 +9,7 @@ export * from "./params";
 export * from "./itemExpr";
 export * from "./runtimeTypes";
 export * from "./telemetryTypes";
+export * from "./testTriggerTypes";
 export * from "./runFinishedAtFactory";
 export * from "./runTypes";
 export * from "./webhookTypes";

package/src/contracts/runTypes.ts

@@ -1,5 +1,5 @@
 import type { TypeToken } from "../di";
-import type { RunEventBus } from "../events/runEvents";
+import type { RunEventBus, TestCaseRunStatus } from "../events/runEvents";
 import type {
   Edge,
   InputPortKey,
@@ -7,6 +7,7 @@ import type {
   JsonValue,
   NodeActivationId,
   NodeId,
+  NodeIterationId,
   NodeKind,
   NodeOutputs,
   OutputPortKey,
@@ -19,6 +20,23 @@ import type {
   WorkflowNodeConnection,
 } from "./workflowTypes";
 
+/**
+ * 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.
+ */
+export 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;
+}
+
 export interface RunExecutionOptions {
   /** Run-intent override: force the inline scheduler and bypass node-level offload decisions. */
   localOnly?: boolean;
@@ -35,6 +53,8 @@ export interface RunExecutionOptions {
   maxNodeActivations?: number;
   /** Effective cap after engine policy merge (subworkflow nesting). */
   maxSubworkflowDepth?: number;
+  /** Present iff started by a TestSuiteOrchestrator; propagates to subworkflow runs via {@link ParentExecutionRef.testContext}. */
+  testContext?: RunTestContext;
 }
 
 /** Engine-owned counters persisted with the run (worker-safe). */
@@ -154,6 +174,12 @@ export interface ConnectionInvocationRecord {
   readonly startedAt?: string;
   readonly finishedAt?: string;
   readonly updatedAt: string;
+  /** Per-item iteration id minted by the engine when this invocation occurred inside a runnable node's per-item loop. */
+  readonly iterationId?: NodeIterationId;
+  /** Item index (0-based) of the iteration that produced this invocation. */
+  readonly itemIndex?: number;
+  /** When set, this invocation was produced inside a sub-agent triggered by the named parent invocation. */
+  readonly parentInvocationId?: ConnectionInvocationId;
 }
 
 /** Arguments for appending a {@link ConnectionInvocationRecord} (engine fills run/workflow ids and timestamps). */
@@ -169,6 +195,9 @@ export type ConnectionInvocationAppendArgs = Readonly<{
   queuedAt?: string;
   startedAt?: string;
   finishedAt?: string;
+  iterationId?: NodeIterationId;
+  itemIndex?: number;
+  parentInvocationId?: ConnectionInvocationId;
 }>;
 
 export interface RunCurrentState {
@@ -210,6 +239,13 @@ export interface RunSummary {
   workflowId: WorkflowId;
   startedAt: string;
   status: RunStatus;
+  /**
+   * Test-case status for runs dispatched as part of a TestSuiteRun. Carries the
+   * assertion-rollup-corrected outcome the test orchestrator persists onto the row, so the
+   * executions list can show "failed" for a run whose workflow completed cleanly but whose
+   * assertions caught regressions. Absent for non-test runs and legacy rows.
+   */
+  testCaseStatus?: TestCaseRunStatus;
   /** ISO timestamp when the run finished (derived from node snapshots or store `updatedAt`); omit while running/pending. */
   finishedAt?: string;
   parent?: ParentExecutionRef;

package/src/contracts/runtimeTypes.ts

@@ -2,14 +2,17 @@ import type { ReadableStream as BinaryReadableStream } from "node:stream/web";
 import type { TypeToken } from "../di";
 import type { RunEventBus } from "../events/runEvents";
 import type { CredentialSessionService } from "./credentialTypes";
+import type { CollectionsContext } from "./collectionTypes";
 import type { ExecutionTelemetry, ExecutionTelemetryFactory, NodeExecutionTelemetry } from "./telemetryTypes";
 import type {
   ConnectionInvocationAppendArgs,
+  ConnectionInvocationId,
   NodeInputsByPort,
   PersistedWorkflowSnapshot,
   PersistedWorkflowTokenRegistryLike,
   RunExecutionOptions,
   RunResult,
+  RunTestContext,
   WorkflowExecutionRepository,
 } from "./runTypes";
 import type { WorkflowActivationPolicy } from "./workflowActivationPolicy";
@@ -25,6 +28,7 @@ import type {
   NodeActivationId,
   NodeConfigBase,
   NodeId,
+  NodeIterationId,
   NodeOutputs,
   RunnableNodeConfig,
   OutputPortKey,
@@ -154,6 +158,21 @@ export interface ExecutionContext {
   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;
+  /**
+   * 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.
+   */
+  testContext?: RunTestContext;
+  /**
+   * Collections registered in the codemation config, keyed by collection name.
+   */
+  readonly collections?: CollectionsContext;
 }
 
 export interface ExecutionContextFactory {
@@ -169,6 +188,7 @@ export interface ExecutionContextFactory {
     nodeState?: NodeExecutionStatePublisher;
     telemetry?: ExecutionTelemetry;
     getCredential<TSession = unknown>(slotKey: string): Promise<TSession>;
+    testContext?: RunTestContext;
   }): ExecutionContext;
 }
 
@@ -180,6 +200,24 @@ export interface NodeExecutionContext<TConfig extends NodeConfigBase = NodeConfi
   binary: NodeBinaryAttachmentService;
 }
 
+export 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: import("../triggers/polling/PollingTriggerDedupWindow").PollingTriggerDedupWindow;
+}
+
 export interface TriggerSetupContext<
   TConfig extends TriggerNodeConfig<any, any> = TriggerNodeConfig<any, any>,
   TSetupState extends JsonValue | undefined = TriggerNodeSetupState<TConfig>,
@@ -189,6 +227,8 @@ export interface TriggerSetupContext<
   previousState: TSetupState;
   registerCleanup(cleanup: TriggerCleanupHandle): void;
   emit(items: Items): Promise<void>;
+  /** Generic polling-trigger surface. Pre-binds trigger id, emit, and registerCleanup. */
+  readonly polling: PollingTriggerHandle;
 }
 
 export interface TriggerTestItemsContext<
@@ -431,4 +471,6 @@ export interface EngineDeps {
   workflowPolicyRuntimeDefaults?: WorkflowPolicyRuntimeDefaults;
   /** When set, logs inactive-workflow skips at boot and trigger start/stop on activation changes. */
   triggerRuntimeDiagnostics?: TriggerRuntimeDiagnostics;
+  /** When set, the polling-trigger runtime uses this logger for cycle info/debug/error. */
+  pollingTriggerLogger?: import("../triggers/polling/PollingTriggerLogger").PollingTriggerLogger;
 }

package/src/contracts/telemetryTypes.ts

@@ -73,6 +73,14 @@ export 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;
 }
 
 export interface NodeExecutionTelemetry extends ExecutionTelemetry, TelemetrySpanScope {

package/src/contracts/testTriggerTypes.ts

@@ -0,0 +1,66 @@
+import type { Item, NodeId, WorkflowId } from "./workflowTypes";
+import type { TriggerNodeConfig } from "./workflowTypes";
+
+/**
+ * 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`.
+ */
+export 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.
+ */
+export interface TestTriggerSetupContext<
+  TConfig extends TestTriggerNodeConfig<unknown> = TestTriggerNodeConfig<unknown>,
+> {
+  readonly workflowId: WorkflowId;
+  readonly nodeId: NodeId;
+  readonly config: TConfig;
+  readonly testSuiteRunId: TestSuiteRunId;
+  /**
+   * 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}.
+   */
+  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.
+ */
+export interface TestTriggerNodeConfig<TOutputJson = unknown> extends TriggerNodeConfig<TOutputJson, undefined> {
+  readonly triggerKind: "test";
+  /**
+   * 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).
+   */
+  generateItems(ctx: TestTriggerSetupContext<TestTriggerNodeConfig<TOutputJson>>): AsyncIterable<Item<TOutputJson>>;
+  /** 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>): string | undefined;
+}