@codemation/core-nodes 0.8.1 → 0.10.0

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { AssistantModelMessage, ModelMessage, ToolModelMessage, ToolSet } from "ai";
 import { Cron, CronCallback } from "croner";
-import { ReadableStream } from "node:stream/web";
 import { ZodType, input, output, z } from "zod";
 import { DependencyContainer as Container, InjectionToken as TypeToken } from "tsyringe";
+import { ReadableStream } from "node:stream/web";
 
 //#region src/canvasIconName.d.ts
 /**
@@ -14,6 +14,67 @@ import { DependencyContainer as Container, InjectionToken as TypeToken } from "t
  */
 type CanvasIconName = string;
 //#endregion
+//#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;
+  /**
+   * 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.
+ */
+interface TestTriggerNodeConfig<TOutputJson$1 = unknown> extends TriggerNodeConfig<TOutputJson$1, 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$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/baseTypes.d.ts
 /**
  * Minimal base types that have no dependencies on other contracts.
@@ -26,77 +87,333 @@ type OutputPortKey = string;
 type InputPortKey = string;
 type NodeConnectionName = string;
 //#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/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/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;
   /**
-   * 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.
+   * 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.
    */
-  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;
+  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/agentMcpTypes.d.ts
+/**
+ * An opaque MCP tool map: keyed by serverId → (toolName → tool definition).
+ * Typed as unknown so core does not depend on the AI SDK's ToolSet type.
+ * AIAgentNode (in core-nodes, which does depend on ai) casts this to
+ * ReadonlyMap<string, ToolSet> before passing to DeferredMetaToolStrategyFactory.
+ */
+type AgentMcpToolMap = ReadonlyMap<string, Readonly<Record<string, unknown>>>;
+/**
+ * Contract implemented by the host. Resolves MCP server bindings for an agent run
+ * via the standard credential-binding table (one slot per declared server, keyed
+ * by `(workflowId, mcpConnectionNodeId, "credential")`), and returns a ready-to-use
+ * tool map with wrapped execute callbacks for telemetry and 403 detection.
+ * Core-nodes imports this interface so AIAgentNode can inject it without
+ * depending on the host.
+ */
+interface AgentMcpIntegration {
   /**
-   * 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.
+   * Look up the credential binding per server, validate scopes, open pool
+   * connections, and return a tool map keyed by serverId. Each tool's
+   * execute callback includes:
+   * - Telemetry child span (mcp.server_id, mcp.tool_name attributes)
+   * - 403/permission error detection → emits a NeedsReconsentEvent span event
+   *
+   * Throws `AgentBindError` on validation failures (missing server, unbound
+   * credential slot, missing credential instance, insufficient scopes).
    */
-  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;
-} | {
+  prepareMcpTools(args: {
+    readonly workflowId: WorkflowId;
+    readonly agentNodeId: NodeId;
+    readonly serverIds: ReadonlyArray<string>;
+    readonly pinnedMcpTools: readonly string[];
+    readonly emitSpanEvent: (event: TelemetrySpanEventRecord) => void;
+    readonly startChildSpan: (args: {
+      readonly name: string;
+      readonly attributes?: Record<string, string>;
+    }) => {
+      readonly end: (args?: {
+        status?: "ok" | "error";
+        statusMessage?: string;
+      }) => void;
+    };
+    /** Per-MCP-tool-call invocation appender. Optional; when omitted the wrapper emits only telemetry spans. */
+    readonly appendMcpInvocation?: (args: ConnectionInvocationAppendArgs) => Promise<void>;
+    /** Agent activation id to attach to each invocation record (used by canvas + inspector grouping). */
+    readonly parentAgentActivationId?: NodeActivationId;
+    /** Per-item iteration id when the agent runs inside a per-item loop. */
+    readonly iterationId?: NodeIterationId;
+    /** Item index (0-based) of the iteration that owns these tool calls. */
+    readonly itemIndex?: number;
+    /** Parent invocation id when this agent is itself executing as a sub-agent. */
+    readonly parentInvocationId?: ConnectionInvocationId;
+  }): Promise<AgentMcpToolMap>;
+}
+//#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/itemExpr.d.ts
+declare const ITEM_EXPR_BRAND: unique symbol;
+type ItemExprResolvedContext = Readonly<{
+  runId: RunId;
+  workflowId: WorkflowId;
+  nodeId: NodeId;
+  activationId: NodeActivationId;
+  data: RunDataSnapshot;
+}>;
+/**
+ * Context aligned with former {@link ItemInputMapperContext} — use **`data`** to read any completed upstream node.
+ */
+type ItemExprContext = ItemExprResolvedContext;
+type ItemExprArgs<TItemJson = unknown> = Readonly<{
+  item: Item<TItemJson>;
+  itemIndex: number;
+  items: Items<TItemJson>;
+  ctx: ItemExprContext;
+}>;
+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>;
+}>;
+//#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
+/**
+ * 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 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;
+}
+//#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/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.
@@ -161,6 +478,19 @@ type CredentialInstanceRecord<TPublicConfig extends CredentialJsonRecord = Crede
   setupStatus: CredentialSetupStatus;
   createdAt: string;
   updatedAt: string;
+  /**
+   * Pointer to where the credential material bytes live. For OSS / standalone
+   * rows this is `{source: "local", ref: instanceId}` and the bytes co-locate
+   * with the row in the workspace DB. For managed-mode rows this is
+   * `{source: "control-plane", ref: <cp_id>}` and the bytes live at CP.
+   *
+   * The seam is read through `CredentialMaterialProvider`. See
+   * `docs/design/credentials-oauth-unification.md` ("Material provider seam").
+   */
+  material: Readonly<{
+    source: "local" | "control-plane";
+    ref: string;
+  }>;
 }>;
 /**
  * Arguments passed to `CredentialType.createSession` and `CredentialType.test`.
@@ -197,36 +527,282 @@ interface CredentialSessionService {
   }>): Promise<TSession>;
 }
 //#endregion
-//#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>;
+//#region ../core/src/contracts/mcpTypes.d.ts
+type McpServerTransport = "http";
+interface McpServerDeclaration {
+  /** Globally unique slug, e.g. "gmail". Workflow authors reference this. */
+  id: string;
+  displayName: string;
+  description: string;
+  transport: McpServerTransport;
+  url: string;
+  /**
+   * Credential types accepted by this MCP server, matching CredentialRequirement.acceptedTypes.
+   * Absent or empty means no credential is required.
+   */
+  acceptedCredentialTypes?: ReadonlyArray<string>;
+  /**
+   * Documentation only in MVP. The bind-time validator checks
+   * requiredScopes ⊆ CredentialInstance.scopesGranted.
+   */
+  requiredScopes?: string[];
+  /** Non-secret static headers merged onto every MCP request. */
+  staticHeaders?: Record<string, string>;
+  /**
+   * Overrides for tool descriptions advertised by the MCP server.
+   * Applied by the connection pool after tools/list.
+   * Key: exact tool name as returned by the server.
+   */
+  toolDescriptionOverrides?: Record<string, string>;
 }
 //#endregion
-//#region ../core/src/contracts/runTypes.d.ts
+//#region ../core/src/contracts/collectionTypes.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.
+ * Represents a typed store for a single collection.
+ * All rows include auto-managed id, created_at, and updated_at fields.
  */
-interface RunTestContext {
-  readonly testSuiteRunId: string;
-  readonly testCaseIndex: number;
+interface CollectionStore<TRow extends Record<string, unknown> = Record<string, unknown>> {
   /**
-   * 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".
+   * Insert a new row. id, created_at, and updated_at are auto-populated.
    */
-  readonly testCaseLabel?: string;
-}
-type NodeInputsByPort = Readonly<Record<InputPortKey, Items>>;
-type NodeExecutionStatus = "pending" | "queued" | "running" | "completed" | "failed" | "skipped";
-interface NodeExecutionError {
+  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/authoring/defineNode.types.d.ts
+type ResolvableCredentialType = AnyCredentialType | CredentialTypeId;
+type DefinedNodeCredentialBinding = ResolvableCredentialType | Readonly<{
+  readonly type: ResolvableCredentialType | ReadonlyArray<ResolvableCredentialType>;
+  readonly label?: string;
+  readonly optional?: true;
+  readonly helpText?: string;
+  readonly helpUrl?: string;
+}>;
+type DefinedNodeCredentialBindings = Readonly<Record<string, DefinedNodeCredentialBinding>>;
+type DefinedNodeConfigInput<TConfigResolved extends CredentialJsonRecord, TItemJson> = ParamDeep<TConfigResolved, TItemJson>;
+interface DefinedNode<TKey$1 extends string, TConfig extends CredentialJsonRecord, TInputJson$1, TOutputJson$1, _TBindings extends DefinedNodeCredentialBindings | undefined = undefined> {
+  readonly kind: "defined-node";
+  readonly key: TKey$1;
+  readonly title: string;
+  readonly description?: string;
+  create<TConfigItemJson = TInputJson$1>(config: DefinedNodeConfigInput<TConfig, TConfigItemJson>, name?: string, id?: string): RunnableNodeConfig<TInputJson$1, TOutputJson$1>;
+  register(context: {
+    registerNode<TValue>(token: TypeToken<TValue>, implementation?: TypeToken<TValue>): void;
+  }): void;
+}
+//#endregion
+//#region ../core/src/authoring/defineHumanApprovalNode.types.d.ts
+/**
+ * Decision shape merged into `item.json` after a HITL approval task resolves.
+ *
+ * - `"approved"` / `"rejected"` — from a human decision (uses `approvedPredicate`).
+ * - `"timed-out"` — timeout fired with `onTimeout: "halt"`.
+ * - `"auto-accepted"` — timeout fired with `onTimeout: "auto-accept"`.
+ */
+interface HumanApprovalDecisionResult {
+  readonly status: "approved" | "rejected" | "timed-out" | "auto-accepted";
+  /** Identity of the person who decided; absent for automated outcomes. */
+  readonly actor?: HumanTaskActor;
+  /** ISO 8601 timestamp of the decision. */
+  readonly decidedAt?: Date;
+  /** Optional free-text note from the reviewer. */
+  readonly note?: string;
+  /**
+   * Full raw decision payload (only present for `"approved"` / `"rejected"`).
+   * Shape is determined by the channel's `decisionSchema`.
+   */
+  readonly payload?: Record<string, unknown>;
+}
+/**
+ * Output item shape emitted by a `defineHumanApprovalNode`-based node.
+ * Original `item.json` fields are preserved and `decision` is merged in.
+ * If the input `item.json` already contained a `decision` key it is **overwritten**.
+ */
+type HumanApprovalOutputJson<TInputJson$1 extends Record<string, unknown>> = TInputJson$1 & {
+  readonly decision: HumanApprovalDecisionResult;
+};
+/**
+ * Extends {@link DefinedNode} with the `humanApprovalToolBehavior` metadata marker.
+ * Story 10 reads this field when attaching the node as an agent tool.
+ */
+interface DefinedHumanApprovalNode<TKey$1 extends string, TConfig extends CredentialJsonRecord, TInputJson$1 extends Record<string, unknown>, TBindings extends DefinedNodeCredentialBindings | undefined = undefined> extends DefinedNode<TKey$1, TConfig, TInputJson$1, HumanApprovalOutputJson<TInputJson$1>, TBindings> {
+  /**
+   * Behavior hint consumed by the agent runtime (story 10) when this node is attached as a tool.
+   * `"return"` (default) — return the rejection to the agent as a tool result.
+   * `"halt"` — halt the agent run on rejection.
+   *
+   * Standalone DSL usage ignores this field.
+   */
+  readonly humanApprovalToolBehavior: {
+    onRejected: "return" | "halt";
+  };
+}
+//#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>;
+  /**
+   * Chainable shorthand for `.then(node.create(config, metadata?.name, metadata?.nodeId))`.
+   *
+   * Signals to readers that this step suspends the run and waits for a human decision.
+   * Throws at workflow-build time if `node` was not created via `defineHumanApprovalNode`.
+   *
+   * @example
+   * ```ts
+   * workflow
+   *   .trigger(...)
+   *   .humanApproval(inboxApproval, { title: "Approve?", body: "...", priority: "normal" })
+   *   .then(nextStep.create(...))
+   *   .build();
+   * ```
+   */
+  humanApproval<TKey$1 extends string, TConfig extends Record<string, unknown>, TBindings extends DefinedNodeCredentialBindings | undefined = undefined>(node: DefinedHumanApprovalNode<TKey$1, TConfig, TCurrentJson & Record<string, unknown>, TBindings>, config: TConfig, metadata?: {
+    name?: string;
+    nodeId?: string;
+  }): ChainCursor<HumanApprovalOutputJson<TCurrentJson & Record<string, unknown>>>;
+  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/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;
+}
+type NodeInputsByPort = Readonly<Record<InputPortKey, Items>>;
+type NodeExecutionStatus = "pending" | "queued" | "running" | "completed" | "failed" | "skipped" | "hitl-approved" | "hitl-rejected" | "hitl-timeout" | "hitl-auto-accepted" | "hitl-cancelled";
+interface NodeExecutionError {
   message: string;
   name?: string;
   stack?: string;
@@ -253,6 +829,8 @@ type ConnectionInvocationAppendArgs = Readonly<{
   itemIndex?: number;
   parentInvocationId?: ConnectionInvocationId;
 }>;
+/** Reason a run transitioned to {@link RunStatus} `"halted"`. */
+type RunHaltReason = "hitl-rejected" | "hitl-timeout" | "hitl-cancelled";
 interface PendingNodeExecution {
   runId: RunId;
   activationId: NodeActivationId;
@@ -285,36 +863,14 @@ type RunResult = {
   error: {
     message: string;
   };
+} | {
+  runId: RunId;
+  workflowId: WorkflowId;
+  startedAt: string;
+  status: "halted";
+  reason: RunHaltReason;
 };
 //#endregion
-//#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 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;
-}
-//#endregion
 //#region ../core/src/contracts/workflowTypes.d.ts
 type NodeIdRef<TJson = unknown> = NodeId & Readonly<{
   __codemationNodeJson?: TJson;
@@ -497,522 +1053,150 @@ type BinaryAttachment = Readonly<{
 }>;
 type ItemBinary = Readonly<Record<string, BinaryAttachment>>;
 type Item<TJson = unknown> = Readonly<{
-  json: TJson;
-  binary?: ItemBinary;
-  meta?: Readonly<Record<string, unknown>>;
-  paired?: ReadonlyArray<PairedItemRef>;
-}>;
-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;
-  nodeId: NodeId;
-  /** Subworkflow depth of the **spawning** run (0 = root). Passed when starting a child run. */
-  subworkflowDepth?: number;
-  /** Effective max node activations from the parent run (propagated to child policy merge). */
-  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";
-type WorkflowStoragePolicySpec = WorkflowStoragePolicyMode | TypeToken<WorkflowStoragePolicyResolver>;
-interface WorkflowStoragePolicyResolver {
-  shouldPersist(args: WorkflowStoragePolicyDecisionArgs): boolean | Promise<boolean>;
-}
-interface WorkflowStoragePolicyDecisionArgs {
-  readonly runId: RunId;
-  readonly workflowId: WorkflowId;
-  readonly workflow: WorkflowDefinition;
-  readonly finalStatus: "completed" | "failed";
-  readonly startedAt: string;
-  readonly finishedAt: string;
-}
-interface WorkflowPrunePolicySpec {
-  readonly runDataRetentionSeconds?: number;
-  readonly binaryRetentionSeconds?: number;
-  readonly telemetrySpanRetentionSeconds?: number;
-  readonly telemetryArtifactRetentionSeconds?: number;
-  readonly telemetryMetricRetentionSeconds?: number;
-}
-interface WorkflowErrorHandler {
-  onError(ctx: WorkflowErrorContext): void | Promise<void>;
-}
-interface WorkflowErrorContext {
-  readonly runId: RunId;
-  readonly workflowId: WorkflowId;
-  readonly workflow: WorkflowDefinition;
-  readonly failedNodeId: NodeId;
-  readonly error: Error;
-  readonly startedAt: string;
-  readonly finishedAt: string;
-}
-type WorkflowErrorHandlerSpec = TypeToken<WorkflowErrorHandler> | WorkflowErrorHandler;
-interface NodeErrorHandlerArgs<TConfig extends NodeConfigBase = NodeConfigBase> {
-  readonly kind: "single" | "multi";
-  readonly items: Items;
-  readonly inputsByPort: Readonly<Record<InputPortKey, Items>> | undefined;
-  readonly ctx: NodeExecutionContext<TConfig>;
-  readonly error: Error;
-}
-interface NodeErrorHandler {
-  handle<TConfig extends NodeConfigBase>(args: NodeErrorHandlerArgs<TConfig>): Promise<NodeOutputs>;
-}
-type NodeErrorHandlerSpec = TypeToken<NodeErrorHandler> | NodeErrorHandler;
-//#endregion
-//#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;
-  /**
-   * 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.
- */
-interface TestTriggerNodeConfig<TOutputJson$1 = unknown> extends TriggerNodeConfig<TOutputJson$1, 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$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/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/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/agentMcpTypes.d.ts
-/**
- * An opaque MCP tool map: keyed by serverId → (toolName → tool definition).
- * Typed as unknown so core does not depend on the AI SDK's ToolSet type.
- * AIAgentNode (in core-nodes, which does depend on ai) casts this to
- * ReadonlyMap<string, ToolSet> before passing to DeferredMetaToolStrategyFactory.
- */
-type AgentMcpToolMap = ReadonlyMap<string, Readonly<Record<string, unknown>>>;
-/**
- * Contract implemented by the host. Resolves MCP server bindings for an agent run
- * via the standard credential-binding table (one slot per declared server, keyed
- * by `(workflowId, mcpConnectionNodeId, "credential")`), and returns a ready-to-use
- * tool map with wrapped execute callbacks for telemetry and 403 detection.
- * Core-nodes imports this interface so AIAgentNode can inject it without
- * depending on the host.
- */
-interface AgentMcpIntegration {
-  /**
-   * Look up the credential binding per server, validate scopes, open pool
-   * connections, and return a tool map keyed by serverId. Each tool's
-   * execute callback includes:
-   * - Telemetry child span (mcp.server_id, mcp.tool_name attributes)
-   * - 403/permission error detection → emits a NeedsReconsentEvent span event
-   *
-   * Throws `AgentBindError` on validation failures (missing server, unbound
-   * credential slot, missing credential instance, insufficient scopes).
-   */
-  prepareMcpTools(args: {
-    readonly workflowId: WorkflowId;
-    readonly agentNodeId: NodeId;
-    readonly serverIds: ReadonlyArray<string>;
-    readonly pinnedMcpTools: readonly string[];
-    readonly emitSpanEvent: (event: TelemetrySpanEventRecord) => void;
-    readonly startChildSpan: (args: {
-      readonly name: string;
-      readonly attributes?: Record<string, string>;
-    }) => {
-      readonly end: (args?: {
-        status?: "ok" | "error";
-        statusMessage?: string;
-      }) => void;
-    };
-    /** Per-MCP-tool-call invocation appender. Optional; when omitted the wrapper emits only telemetry spans. */
-    readonly appendMcpInvocation?: (args: ConnectionInvocationAppendArgs) => Promise<void>;
-    /** Agent activation id to attach to each invocation record (used by canvas + inspector grouping). */
-    readonly parentAgentActivationId?: NodeActivationId;
-    /** Per-item iteration id when the agent runs inside a per-item loop. */
-    readonly iterationId?: NodeIterationId;
-    /** Item index (0-based) of the iteration that owns these tool calls. */
-    readonly itemIndex?: number;
-    /** Parent invocation id when this agent is itself executing as a sub-agent. */
-    readonly parentInvocationId?: ConnectionInvocationId;
-  }): Promise<AgentMcpToolMap>;
-}
-//#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/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/mcpTypes.d.ts
-type McpServerTransport = "http";
-interface McpServerDeclaration {
-  /** Globally unique slug, e.g. "gmail". Workflow authors reference this. */
-  id: string;
-  displayName: string;
-  description: string;
-  transport: McpServerTransport;
-  url: string;
-  /**
-   * Credential types accepted by this MCP server, matching CredentialRequirement.acceptedTypes.
-   * Absent or empty means no credential is required.
-   */
-  acceptedCredentialTypes?: ReadonlyArray<string>;
-  /**
-   * Documentation only in MVP. The bind-time validator checks
-   * requiredScopes ⊆ CredentialInstance.scopesGranted.
-   */
-  requiredScopes?: string[];
-  /** Non-secret static headers merged onto every MCP request. */
-  staticHeaders?: Record<string, string>;
-  /**
-   * Overrides for tool descriptions advertised by the MCP server.
-   * Applied by the connection pool after tools/list.
-   * Key: exact tool name as returned by the server.
-   */
-  toolDescriptionOverrides?: Record<string, string>;
-}
-//#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;
-  }>;
+  json: TJson;
+  binary?: ItemBinary;
+  meta?: Readonly<Record<string, unknown>>;
+  paired?: ReadonlyArray<PairedItemRef>;
+}>;
+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;
+  nodeId: NodeId;
+  /** Subworkflow depth of the **spawning** run (0 = root). Passed when starting a child run. */
+  subworkflowDepth?: number;
+  /** Effective max node activations from the parent run (propagated to child policy merge). */
+  engineMaxNodeActivations?: number;
+  /** Effective max subworkflow depth from the parent run (propagated to child policy merge). */
+  engineMaxSubworkflowDepth?: number;
   /**
-   * Delete a row by id. Hard delete only (no soft delete).
+   * 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.
    */
-  delete(id: string): Promise<{
-    deleted: boolean;
-  }>;
+  testContext?: RunTestContext;
 }
-/**
- * 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;
+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;
 }
-//#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;
+interface ActivationIdFactory {
+  makeActivationId(): NodeActivationId;
+}
+type UpstreamRefPlaceholder = `$${number}`;
+/** Whether to persist run execution data after the workflow finishes. */
+type WorkflowStoragePolicyMode = "ALL" | "SUCCESS" | "ERROR" | "NEVER";
+type WorkflowStoragePolicySpec = WorkflowStoragePolicyMode | TypeToken<WorkflowStoragePolicyResolver>;
+interface WorkflowStoragePolicyResolver {
+  shouldPersist(args: WorkflowStoragePolicyDecisionArgs): boolean | Promise<boolean>;
+}
+interface WorkflowStoragePolicyDecisionArgs {
+  readonly runId: RunId;
+  readonly workflowId: WorkflowId;
+  readonly workflow: WorkflowDefinition;
+  readonly finalStatus: "completed" | "failed";
+  readonly startedAt: string;
+  readonly finishedAt: string;
+}
+interface WorkflowPrunePolicySpec {
+  readonly runDataRetentionSeconds?: number;
+  readonly binaryRetentionSeconds?: number;
+  readonly telemetrySpanRetentionSeconds?: number;
+  readonly telemetryArtifactRetentionSeconds?: number;
+  readonly telemetryMetricRetentionSeconds?: number;
+}
+interface WorkflowErrorHandler {
+  onError(ctx: WorkflowErrorContext): void | Promise<void>;
+}
+interface WorkflowErrorContext {
+  readonly runId: RunId;
+  readonly workflowId: WorkflowId;
+  readonly workflow: WorkflowDefinition;
+  readonly failedNodeId: NodeId;
+  readonly error: Error;
+  readonly startedAt: string;
+  readonly finishedAt: string;
+}
+type WorkflowErrorHandlerSpec = TypeToken<WorkflowErrorHandler> | WorkflowErrorHandler;
+interface NodeErrorHandlerArgs<TConfig extends NodeConfigBase = NodeConfigBase> {
+  readonly kind: "single" | "multi";
+  readonly items: Items;
+  readonly inputsByPort: Readonly<Record<InputPortKey, Items>> | undefined;
+  readonly ctx: NodeExecutionContext<TConfig>;
+  readonly error: Error;
+}
+interface NodeErrorHandler {
+  handle<TConfig extends NodeConfigBase>(args: NodeErrorHandlerArgs<TConfig>): Promise<NodeOutputs>;
 }
+type NodeErrorHandlerSpec = TypeToken<NodeErrorHandler> | NodeErrorHandler;
 //#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;
+//#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>;
 }
 //#endregion
 //#region ../core/src/contracts/runtimeTypes.d.ts
+/** Opaque unique identifier for a single HumanTask instance. */
+type HumanTaskId = string;
+/**
+ * Minimal handle handed to the `deliver` callback so it can route to the correct
+ * inbox channel.
+ */
+interface HumanTaskHandle {
+  readonly taskId: HumanTaskId;
+  readonly runId: string;
+  readonly nodeId: string;
+  readonly expiresAt: Date;
+  /** TODO: real signed URL; placeholder empty string for now. */
+  readonly resumeUrl: string;
+  /**
+   * Arbitrary JSON metadata copied from `SuspensionRequest.request.metadata` at suspension time.
+   * Used by the agent runtime to round-trip the `agentCheckpoint` back to the
+   * resumed node via `ctx.resumeContext.task.metadata`.
+   */
+  readonly metadata?: Readonly<Record<string, JsonValue>>;
+}
+/** Identity of the person who made a decision on the task. */
+interface HumanTaskActor {
+  readonly actorId: string;
+  readonly displayName?: string;
+}
+/**
+ * Resume context injected into `NodeExecutionContext` when the engine re-activates
+ * a previously suspended node. `defineHumanApprovalNode` wraps this with parsed
+ * `TDecision`; at the engine layer `decision.value` is `unknown`.
+ */
+interface ResumeContext {
+  readonly decision: Readonly<{
+    kind: "decided";
+    value: unknown;
+    actor: HumanTaskActor;
+    decidedAt: Date;
+  }> | Readonly<{
+    kind: "timed_out";
+    at: Date;
+  }> | Readonly<{
+    kind: "auto_accepted";
+    at: Date;
+  }>;
+  readonly delivery: JsonValue;
+  readonly task: HumanTaskHandle;
+}
 interface WorkflowRunnerService {
   runById(args: {
     workflowId: WorkflowId;
@@ -1080,6 +1264,22 @@ interface ExecutionBinaryService {
     activationId: NodeActivationId;
   }): NodeBinaryAttachmentService;
   openReadStream(attachment: BinaryAttachment): Promise<BinaryStorageReadResult | undefined>;
+  /**
+   * Reads all bytes from the attachment into a contiguous `Uint8Array`.
+   * Checks `attachment.size` against `maxBytes` *before* any allocation; throws a bounded-read
+   * error when exceeded (no OOM). Throws if the stream is unavailable or the byte count mismatches.
+   */
+  getBytes(attachment: BinaryAttachment, maxBytes?: number): Promise<Uint8Array>;
+  /**
+   * Reads the attachment and decodes the bytes as UTF-8 text.
+   * Subject to the same bounded-read safety as `getBytes`.
+   */
+  getText(attachment: BinaryAttachment, maxBytes?: number): Promise<string>;
+  /**
+   * Reads the attachment, decodes as UTF-8 text, and parses as JSON.
+   * Throws a clear error on invalid JSON. Subject to the same bounded-read safety.
+   */
+  getJson<T = unknown>(attachment: BinaryAttachment, maxBytes?: number): Promise<T>;
 }
 interface ExecutionContext {
   runId: RunId;
@@ -1112,6 +1312,14 @@ interface ExecutionContext {
    * Collections registered in the codemation config, keyed by collection name.
    */
   readonly collections?: CollectionsContext;
+  /**
+   * Resolve a DI token from the host container.
+   * Allows nodes to reach host-side services (e.g. `InboxChannelResolverToken`)
+   * without importing host code. Wired by `DefaultExecutionContextFactory`; throws
+   * a clear error when no resolver is configured (e.g. in unit tests that don't
+   * set up the full container).
+   */
+  resolve<T>(token: TypeToken<T>): T;
 }
 interface NodeExecutionContext<TConfig extends NodeConfigBase = NodeConfigBase> extends ExecutionContext {
   nodeId: NodeId;
@@ -1119,6 +1327,11 @@ interface NodeExecutionContext<TConfig extends NodeConfigBase = NodeConfigBase>
   config: TConfig;
   telemetry: NodeExecutionTelemetry;
   binary: NodeBinaryAttachmentService;
+  /**
+   * Present when this node activation is a HITL resume.
+   * The node checks `ctx.resumeContext !== undefined` and takes the resume branch.
+   */
+  resumeContext?: ResumeContext;
 }
 interface PollingTriggerHandle {
   /**
@@ -1207,57 +1420,6 @@ interface TestableTriggerNode<TConfig extends TriggerNodeConfig<any, any> = Trig
 }
 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;
-}>;
-/**
- * Context aligned with former {@link ItemInputMapperContext} — use **`data`** to read any completed upstream node.
- */
-type ItemExprContext = ItemExprResolvedContext;
-type ItemExprArgs<TItemJson = unknown> = Readonly<{
-  item: Item<TItemJson>;
-  itemIndex: number;
-  items: Items<TItemJson>;
-  ctx: ItemExprContext;
-}>;
-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>;
-}>;
-//#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;
-type DefinedNodeCredentialBinding = ResolvableCredentialType | Readonly<{
-  readonly type: ResolvableCredentialType | ReadonlyArray<ResolvableCredentialType>;
-  readonly label?: string;
-  readonly optional?: true;
-  readonly helpText?: string;
-  readonly helpUrl?: string;
-}>;
-type DefinedNodeCredentialBindings = Readonly<Record<string, DefinedNodeCredentialBinding>>;
-type DefinedNodeConfigInput<TConfigResolved extends CredentialJsonRecord, TItemJson> = ParamDeep<TConfigResolved, TItemJson>;
-interface DefinedNode<TKey$1 extends string, TConfig extends CredentialJsonRecord, TInputJson$1, TOutputJson$1, _TBindings extends DefinedNodeCredentialBindings | undefined = undefined> {
-  readonly kind: "defined-node";
-  readonly key: TKey$1;
-  readonly title: string;
-  readonly description?: string;
-  create<TConfigItemJson = TInputJson$1>(config: DefinedNodeConfigInput<TConfig, TConfigItemJson>, name?: string, id?: string): RunnableNodeConfig<TInputJson$1, TOutputJson$1>;
-  register(context: {
-    registerNode<TValue>(token: TypeToken<TValue>, implementation?: TypeToken<TValue>): void;
-  }): void;
-}
-//#endregion
 //#region ../core/src/ai/NodeBackedToolConfig.d.ts
 declare class NodeBackedToolConfig<TNodeConfig extends RunnableNodeConfig<any, any>, TInputSchema extends ZodSchemaAny, TOutputSchema extends ZodSchemaAny> implements ToolConfig {
   readonly name: string;
@@ -2086,21 +2248,6 @@ declare class CodemationChatModelFactory implements ChatModelFactory<CodemationC
     config: CodemationChatModelConfig;
     ctx: NodeExecutionContext<any>;
   }>): Promise<ChatLanguageModel>;
-  /**
-   * Creates an HMAC-signed fetch wrapper for use with AI SDK's createOpenAI.
-   * Each call signs the request body with the workspace pairing secret so the
-   * LLM broker can authenticate the workspace without a user-managed API key.
-   *
-   * Mirrors HmacRequestSigner from @codemation/host/pairing without importing
-   * that package (which would create a circular dependency since @codemation/host
-   * depends on @codemation/core-nodes).
-   */
-  private buildHmacSignedFetch;
-  /**
-   * Produces a Codemation-Hmac v1 Authorization header value.
-   * The algorithm must match HmacVerifier.computeSignature() in the control-plane.
-   */
-  private buildHmacAuthHeader;
 }
 //#endregion
 //#region src/chatModels/ManagedModelFetcher.d.ts
@@ -2134,11 +2281,18 @@ type ResolvedTool = Readonly<{
  * 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).
+ *
+ * `humanApproval` is present only when the tool was created via `defineHumanApprovalNode`
+ * (via its marker) — detected during `resolveTools` in `AIAgentNode`.
  */
 type ItemScopedToolBinding = Readonly<{
   config: ToolConfig;
   inputSchema: ZodSchemaAny;
   execute(input: unknown, hooks?: ItemScopedToolCallHooks): Promise<unknown>;
+  /** Present when this binding is backed by a HITL-approval node (story 10). */
+  humanApproval?: Readonly<{
+    onRejected: "halt" | "return";
+  }>;
 }>;
 type ItemScopedToolCallHooks = Readonly<{
   /** Live agent.tool.call span (used to parent sub-agent telemetry). */
@@ -2374,6 +2528,14 @@ declare class AgentToolExecutionCoordinator {
     ctx: NodeExecutionContext<AIAgent<any, any>>;
     agentName: string;
     repairAttemptsByToolName: Map<string, number>;
+    /** Conversation including the assistant message that emitted these tool_use blocks. Stored in checkpoint on HITL suspension. */
+    conversationSnapshot?: ReadonlyArray<ModelMessage>;
+    /** Turn count at the moment of this coordinator invocation. */
+    turnCount?: number;
+    /** Cumulative tool-call count up to and including this batch. */
+    toolCallCount?: number;
+    /** Model id for checkpoint migration safety. */
+    modelId?: string;
   }>): Promise<ReadonlyArray<ExecutedToolCall>>;
   private executePlannedToolCall;
   private recordFailedInvocation;
@@ -2382,6 +2544,11 @@ declare class AgentToolExecutionCoordinator {
   private createValidationMessage;
   private toJsonValue;
   private extractErrorDetails;
+  /**
+   * Extracts the text content from the last assistant message in the conversation snapshot.
+   * Used to populate `agentReasoning` in the HITL suspension metadata.
+   */
+  private extractLastAssistantText;
   private serializeIssue;
 }
 //#endregion
@@ -2479,6 +2646,17 @@ declare class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
   private readonly preparedByExecutionContext;
   constructor(nodeResolver: NodeResolver, credentialSessions: CredentialSessionService, nodeBackedToolRuntime: NodeBackedToolRuntime, executionHelpers: AIAgentExecutionHelpersFactory, structuredOutputRunner: AgentStructuredOutputRunner, toolExecutionCoordinator: AgentToolExecutionCoordinator, toolLoadingStrategyFactory: DeferredMetaToolStrategyFactory, agentMcpIntegration: AgentMcpIntegration);
   execute(args: RunnableNodeExecuteArgs<AIAgent<any, any>>): Promise<unknown>;
+  /**
+   * Resume path: re-enters the agent loop after a HITL suspension.
+   * Reconstructs the conversation from the checkpoint, injects the human decision
+   * as a tool_result, and continues the loop from where it suspended.
+   */
+  private executeResumed;
+  /**
+   * Normalizes a {@link ResumeContext} decision into a flat JSON-serializable shape
+   * suitable for injection as a tool_result content.
+   */
+  private normalizeDecision;
   private getOrPrepareExecution;
   private prepareExecution;
   private prepareMcpToolsByServer;
@@ -2501,6 +2679,11 @@ declare class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
   private buildOutputItem;
   private resolveTools;
   private createItemScopedTools;
+  /**
+   * Detects whether a tool config is backed by a `defineHumanApprovalNode` marker
+   * and returns the HITL behavior config, or `undefined` when not a HITL tool.
+   */
+  private resolveHumanApprovalBehavior;
   /**
    * Invoke a text turn using the merged tool set from item-scoped tools (coordinator-managed)
    * and strategy tools (find_tools + discovered MCP tools).
@@ -2515,6 +2698,8 @@ declare class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
   /**
    * Builds a ToolSet from resolved tools for strategy initialization.
    * The strategy uses this for its "always-included" node-backed tool descriptions.
+   * HITL tools (detected via the `humanApprovalToolBehavior` field set by `defineHumanApprovalNode`) get the solo-constraint sentence
+   * appended to their description.
    */
   private buildToolSetFromResolved;
   /**
@@ -3664,5 +3849,71 @@ declare const collectionDeleteNode: DefinedNode<"collection-delete", {
   id: string;
 }, undefined>;
 //#endregion
-export { AIAgent, AIAgentConnectionWorkflowExpander, AIAgentExecutionHelpersFactory, AIAgentNode, AgentItemPortMap, AgentMessageFactory, AgentOutputFactory, AgentStructuredOutputRepairPromptFactory, AgentStructuredOutputRunner, AgentToolCallPortMap, AgentToolErrorClassifier, AgentToolExecutionCoordinator, AgentToolRepairExhaustedError, AgentToolRepairPolicy, Aggregate, AggregateNode, Assertion, AssertionNode, AssertionOptions, BM25Index, BinaryRef, Callback, CallbackHandler, CallbackNode, CallbackOptions, CallbackResultNormalizer, CanvasIconName, CodemationChatModelConfig, CodemationChatModelFactory, CodemationManagedModel, ConnectionCredentialExecutionContextFactory, ConnectionCredentialNode, ConnectionCredentialNodeConfig, ConnectionCredentialNodeConfigFactory, CredentialSession, CronTickJson, CronTrigger, CronTriggerNode, DeferredMetaToolStrategy, DeferredMetaToolStrategyFactory, DefineRestNodeOptions, type ExecutedToolCall, Filter, FilterNode, type FindToolsResult, HTTP_REQUEST_ACCEPTED_CREDENTIAL_TYPES, HttpBodySpec, HttpCredentialDelta, HttpRequest, HttpRequestDownloadMode, HttpRequestNode, HttpRequestOutputJson, HttpRequestResult, HttpRequestSpec, If, IfNode, IsTestRun, IsTestRunNode, type ItemScopedToolBinding, ManagedModelDto, ManagedModelFetcher, ManualTrigger, ManualTriggerNode, MapData, MapDataNode, MapDataOptions, Merge, MergeMode, MergeNode, NoOp, NoOpNode, OpenAIChatModelConfig, OpenAIChatModelFactory, OpenAiChatModelPresets, OpenAiCredentialSession, OpenAiStrictJsonSchemaFactory, type PlannedToolCall, type ResolvedTool, RestNodeApi, RestNodeErrorPolicy, RestNodeRequestShape, RestNodeResponseContext, SSRFBlockedError, Split, SplitNode, SsrfGuard, SubWorkflow, SubWorkflowNode, Switch, SwitchCaseKeyResolver, SwitchNode, TestTrigger, TestTriggerNode, TestTriggerOptions, type ToolLoadingStrategy, type ToolLoadingStrategyInitInput, type ToolLoadingStrategyTurnContext, 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 };
+//#region src/nodes/InboxApprovalNode.types.d.ts
+/**
+ * A subject field (title / body) for an inbox approval. Either a static string
+ * or a contextual callback that builds the string from the item using ordinary
+ * JavaScript template literals — e.g. `({ item }) => `Approve ${item.json.vendor}``.
+ * Code-first: no template DSL, just functions.
+ */
+type InboxSubjectField = string | ((args: {
+  item: Item;
+}) => string);
+/**
+ * Auto-detecting inbox approval node.
+ *
+ * Uses `ctx.resolve(InboxChannelResolverToken)` to pick the right inbox channel
+ * at runtime:
+ * - In managed mode (PairingConfig present): routes to the control-plane inbox.
+ * - Otherwise: routes to the local inbox.
+ *
+ * Authors use this node directly; no extra wiring needed per deployment mode.
+ */
+declare const inboxApproval: DefinedHumanApprovalNode<"inbox.approval", {
+  title: InboxSubjectField;
+  body: InboxSubjectField;
+  priority: "low" | "normal" | "high";
+  timeout: string;
+  onTimeout: "halt" | "auto-accept";
+}, Record<string, unknown>, undefined>;
+//#endregion
+//#region src/nodes/codemationDocumentScannerNode.d.ts
+declare const ANALYZER_TYPES: readonly ["document", "invoice", "image", "auto"];
+type DocScannerAnalyzerType = (typeof ANALYZER_TYPES)[number];
+/** Per-field value/confidence shape as returned by apps/doc-scanner. */
+type DocScannerField = Readonly<{
+  value: unknown;
+  confidence: number | null;
+}>;
+/** Output shape of CodemationDocumentScanner — identical to the service wire response. */
+type DocScannerOutput = Readonly<{
+  markdown: string;
+  fields: Readonly<Record<string, DocScannerField>>;
+}>;
+type CodemationDocumentScannerConfig = Readonly<{
+  /** Key on `item.binary` that holds the document. Default: "data". */
+  binaryField?: string;
+  /** Analyzer type. Default: "auto" (routes on mime type on the service side). */
+  analyzerType?: DocScannerAnalyzerType;
+  /** MIME type override. Falls back to attachment.mimeType. */
+  contentType?: string;
+  /** Include per-field confidence scores (0–1). Default: false.
+   *  Enabling this roughly doubles contextualization tokens for document analyzers.
+   *  Image and auto-to-image requests silently ignore this flag (confidence stays null). */
+  includeConfidence?: boolean;
+  /** Max bytes checked before any read. Default: 50 MiB (same cap as OCR nodes, LD10). */
+  maxBytes?: number;
+}>;
+declare const codemationDocumentScannerNode: DefinedNode<"codemation.document-scanner", {
+  binaryField?: string | undefined;
+  analyzerType?: "auto" | "document" | "invoice" | "image" | undefined;
+  contentType?: string | undefined;
+  includeConfidence?: boolean | undefined;
+  maxBytes?: number | undefined;
+}, unknown, Readonly<{
+  markdown: string;
+  fields: Readonly<Record<string, DocScannerField>>;
+}>, undefined>;
+//#endregion
+export { AIAgent, AIAgentConnectionWorkflowExpander, AIAgentExecutionHelpersFactory, AIAgentNode, AgentItemPortMap, AgentMessageFactory, AgentOutputFactory, AgentStructuredOutputRepairPromptFactory, AgentStructuredOutputRunner, AgentToolCallPortMap, AgentToolErrorClassifier, AgentToolExecutionCoordinator, AgentToolRepairExhaustedError, AgentToolRepairPolicy, Aggregate, AggregateNode, Assertion, AssertionNode, AssertionOptions, BM25Index, BinaryRef, Callback, CallbackHandler, CallbackNode, CallbackOptions, CallbackResultNormalizer, CanvasIconName, CodemationChatModelConfig, CodemationChatModelFactory, CodemationDocumentScannerConfig, CodemationManagedModel, ConnectionCredentialExecutionContextFactory, ConnectionCredentialNode, ConnectionCredentialNodeConfig, ConnectionCredentialNodeConfigFactory, CredentialSession, CronTickJson, CronTrigger, CronTriggerNode, DeferredMetaToolStrategy, DeferredMetaToolStrategyFactory, DefineRestNodeOptions, DocScannerAnalyzerType, DocScannerField, DocScannerOutput, type ExecutedToolCall, Filter, FilterNode, type FindToolsResult, HTTP_REQUEST_ACCEPTED_CREDENTIAL_TYPES, HttpBodySpec, HttpCredentialDelta, HttpRequest, HttpRequestDownloadMode, HttpRequestNode, HttpRequestOutputJson, HttpRequestResult, HttpRequestSpec, If, IfNode, IsTestRun, IsTestRunNode, type ItemScopedToolBinding, ManagedModelDto, ManagedModelFetcher, ManualTrigger, ManualTriggerNode, MapData, MapDataNode, MapDataOptions, Merge, MergeMode, MergeNode, NoOp, NoOpNode, OpenAIChatModelConfig, OpenAIChatModelFactory, OpenAiChatModelPresets, OpenAiCredentialSession, OpenAiStrictJsonSchemaFactory, type PlannedToolCall, type ResolvedTool, RestNodeApi, RestNodeErrorPolicy, RestNodeRequestShape, RestNodeResponseContext, SSRFBlockedError, Split, SplitNode, SsrfGuard, SubWorkflow, SubWorkflowNode, Switch, SwitchCaseKeyResolver, SwitchNode, TestTrigger, TestTriggerNode, TestTriggerOptions, type ToolLoadingStrategy, type ToolLoadingStrategyInitInput, type ToolLoadingStrategyTurnContext, Wait, WaitDuration, WaitNode, WebhookRespondNowAndContinueError, WebhookRespondNowError, WebhookTrigger, WebhookTriggerNode, type WorkflowAgentMessages, type WorkflowAgentOptions, WorkflowAuthoringBuilder, WorkflowBranchBuilder, WorkflowChain, apiKeyCredentialType, basicAuthCredentialType, bearerTokenCredentialType, codemationDocumentScannerNode, collectionDeleteNode, collectionFindOneNode, collectionGetNode, collectionInsertNode, collectionListNode, collectionUpdateNode, createWorkflowBuilder, defineRestNode, inboxApproval, oauth2ClientCredentialsType, openAiChatModelPresets, registerCoreNodes, workflow };
 //# sourceMappingURL=index.d.ts.map