@codemation/core 0.14.0 → 0.15.0

package/src/contracts/runtimeTypes.ts

@@ -19,56 +19,30 @@ import type { WorkflowActivationPolicy } from "./workflowActivationPolicy";
 import type { TriggerInstanceId, WebhookTriggerMatcher } from "./webhookTypes";
 import type { ZodType } from "zod";
 
-// ---------------------------------------------------------------------------
-// HITL primitives
-// ---------------------------------------------------------------------------
-
-/** Opaque unique identifier for a single HumanTask instance. */
 export type HumanTaskId = string;
 
-/**
- * Duration string — ISO 8601 duration ("PT24H") or shorthand ("24h").
- * Parsed by the timeout job; stored as-is in the suspension record.
- */
 export type Duration = string;
 
-/**
- * Minimal handle handed to the `deliver` callback so it can route to the correct
- * inbox channel.
- */
 export 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, import("./workflowTypes").JsonValue>>;
 }
 
-/** Human-readable description surface shown to the reviewer. */
 export interface HumanTaskSubject {
   readonly title: string;
   readonly summary: string;
   readonly attributes?: import("./workflowTypes").JsonValue;
 }
 
-/** Identity of the person who made a decision on the task. */
 export 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`.
- */
 export interface ResumeContext {
   readonly decision:
     | Readonly<{ kind: "decided"; value: unknown; actor: HumanTaskActor; decidedAt: Date }>
@@ -78,25 +52,6 @@ export interface ResumeContext {
   readonly task: HumanTaskHandle;
 }
 
-/**
- * Thrown by a node's `execute()` to request durable suspension of the current item.
- * The engine catches this, persists the suspension entry, calls `deliver`, and
- * continues to the next item (per-item semantics).
- *
- * @example
- * ```ts
- * throw new SuspensionRequest({
- *   decisionSchema: z.object({ approved: z.boolean() }),
- *   timeout: "PT24H",
- *   onTimeout: "halt",
- *   subject: { title: "Approve invoice", summary: "Invoice #1234 needs approval" },
- *   deliver: async (handle) => {
- *     await notifySlack(handle);
- *     return { channel: "slack", ts: "..." };
- *   },
- * });
- * ```
- */
 export class SuspensionRequest<
   TDecision = unknown,
   TDelivery extends import("./workflowTypes").JsonValue = import("./workflowTypes").JsonValue,
@@ -111,8 +66,6 @@ export class SuspensionRequest<
       deliver: (handle: HumanTaskHandle) => Promise<TDelivery>;
     }>,
   ) {
-    // Extending Error so wrappers like InProcessRetryRunner preserve identity
-    // (`instanceof SuspensionRequest`) instead of coercing via String(thrown).
     super(`SuspensionRequest(${request.subject?.title ?? "untitled"})`);
     this.name = "SuspensionRequest";
   }
@@ -190,11 +143,6 @@ export interface NodeExecutionStatePublisher {
     error: Error;
   }): Promise<void>;
   appendConnectionInvocation(args: ConnectionInvocationAppendArgs): Promise<void>;
-  /**
-   * Annotates the current snapshot for `nodeId` with the id of the child run spawned by a
-   * SubWorkflow invocation. Called from `SubWorkflowNode.execute` after `runById` resolves.
-   * The engine's subsequent `markCompleted` call preserves the value via `previous.childRunId`.
-   */
   setChildRunId?(args: { nodeId: NodeId; childRunId: RunId }): Promise<void>;
 }
 
@@ -227,9 +175,7 @@ export interface BinaryStorage {
   openReadStream(storageKey: string): Promise<BinaryStorageReadResult | undefined>;
   stat(storageKey: string): Promise<BinaryStorageStatResult>;
   delete(storageKey: string): Promise<void>;
-  /** Deletes multiple objects in bulk. Keys are batched internally. */
   deleteMany(storageKeys: ReadonlyArray<string>): Promise<void>;
-  /** Lists all keys sharing a common prefix. Returns keys in arbitrary order. */
   listByPrefix(prefix: string): Promise<ReadonlyArray<string>>;
 }
 
@@ -246,27 +192,13 @@ export interface NodeBinaryAttachmentService extends ExecutionBinaryService {
   withAttachment<TJson>(item: Item<TJson>, name: string, attachment: BinaryAttachment): Item<TJson>;
 }
 
-/** Default maximum bytes read into memory by the bounded helpers (50 MiB). */
 export const BINARY_DEFAULT_MAX_BYTES = 50 * 1024 * 1024;
 
 export interface ExecutionBinaryService {
   forNode(args: { nodeId: NodeId; 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>;
 }
 
@@ -274,11 +206,8 @@ export interface ExecutionContext {
   runId: RunId;
   workflowId: WorkflowId;
   parent?: ParentExecutionRef;
-  /** This run's subworkflow depth (0 = root). */
   subworkflowDepth: number;
-  /** Effective activation budget cap for this run (after policy merge). */
   engineMaxNodeActivations: number;
-  /** Effective subworkflow nesting cap for this run (after policy merge). */
   engineMaxSubworkflowDepth: number;
   now: () => Date;
   data: RunDataSnapshot;
@@ -286,28 +215,11 @@ 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;
-  /**
-   * 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;
 }
 
@@ -334,19 +246,10 @@ export interface NodeExecutionContext<TConfig extends NodeConfigBase = NodeConfi
   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;
 }
 
-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).
-   */
+export interface TriggerPollingPort {
   start<TState, TItem>(args: {
     intervalMs: number;
     seedState?: TState;
@@ -355,7 +258,9 @@ export interface PollingTriggerHandle {
       signal: AbortSignal;
     }) => Promise<{ items: Items<TItem>; nextState: TState }>;
   }): Promise<TState | undefined>;
-  /** Convenience dedup-window helper. */
+}
+
+export interface PollingTriggerHandle extends TriggerPollingPort {
   readonly dedup: import("../triggers/polling/PollingTriggerDedupWindow").PollingTriggerDedupWindow;
 }
 
@@ -368,7 +273,6 @@ 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;
 }
 
@@ -382,12 +286,6 @@ export interface TriggerTestItemsContext<
   previousState: TSetupState;
 }
 
-/**
- * Trigger setup state is intentionally engine-owned so future ownership and
- * leader-election metadata can be coordinated centrally rather than pushed into
- * package-level setup code.
- */
-
 export interface PersistedTriggerSetupState<TState extends JsonValue | undefined = JsonValue | undefined> {
   trigger: TriggerInstanceId;
   updatedAt: string;
@@ -409,12 +307,6 @@ export interface EngineHost {
   workflows?: WorkflowRunnerService;
 }
 
-/**
- * Per-item runnable node: return JSON, an array to fan-out on `main`, an explicit `Item`, or {@link emitPorts}
- * for multi-port emission. Engine applies `inputSchema.parse(item.json)` and passes the result as `args.input`
- * (wire `item.json` is unchanged). Transform helpers may opt into binary preservation, while routers and
- * pass-through nodes should return explicit items when they need to preserve full item state.
- */
 export interface RunnableNodeExecuteArgs<
   TConfig extends RunnableNodeConfig<any, any> = RunnableNodeConfig<any, any>,
   TInputJson = unknown,
@@ -432,19 +324,11 @@ export interface RunnableNode<
   _TOutputJson = unknown,
 > {
   readonly kind: "node";
-  /**
-   * Declared output ports (e.g. `["main"]`).
-   *
-   * Prefer describing dynamic router ports (Switch) and fixed multi-ports (If true/false)
-   * via {@link NodeConfigBase.declaredOutputPorts}. Engine defaults to `["main"]` when omitted.
-   */
   readonly outputPorts?: ReadonlyArray<OutputPortKey>;
-  /** When omitted, engine uses {@link RunnableNodeConfig.inputSchema} or `z.unknown()`. */
   readonly inputSchema?: ZodType<TInputJson>;
   execute(args: RunnableNodeExecuteArgs<TConfig, TInputJson>): Promise<unknown> | unknown;
 }
 
-/** @deprecated Use {@link RunnableNode} */
 export type ItemNode<
   TConfig extends RunnableNodeConfig<any, any> = RunnableNodeConfig<any, any>,
   TInputJson = unknown,
@@ -453,12 +337,6 @@ export type ItemNode<
 
 export interface MultiInputNode<TConfig extends NodeConfigBase = NodeConfigBase> {
   kind: "node";
-  /**
-   * Declared output ports (typically `["main"]`).
-   *
-   * Prefer describing ports for authoring/canvas via {@link NodeConfigBase.declaredOutputPorts}.
-   * Engine defaults to `["main"]` when omitted.
-   */
   outputPorts?: ReadonlyArray<OutputPortKey>;
   executeMulti(inputsByPort: NodeInputsByPort, ctx: NodeExecutionContext<TConfig>): Promise<NodeOutputs>;
 }
@@ -582,7 +460,6 @@ export interface WorkflowSnapshotResolver {
   }): WorkflowDefinition | undefined;
 }
 
-/** Optional host wiring for trigger lifecycle logs (boot skip + activation sync). */
 export interface TriggerRuntimeDiagnostics {
   info(message: string): void;
   warn(message: string): void;
@@ -592,7 +469,6 @@ export interface EngineDeps {
   credentialSessions: CredentialSessionService;
   liveWorkflowRepository: LiveWorkflowRepository;
   workflowRepository: WorkflowRepository;
-  /** When {@link AllWorkflowsActiveWorkflowActivationPolicy}, all workflows behave as active (tests). */
   workflowActivationPolicy: WorkflowActivationPolicy;
   nodeResolver: NodeResolver;
   triggerSetupStateRepository: TriggerSetupStateRepository;
@@ -608,10 +484,7 @@ export interface EngineDeps {
   eventBus?: RunEventBus;
   tokenRegistry: PersistedWorkflowTokenRegistryLike;
   workflowNodeInstanceFactory: WorkflowNodeInstanceFactory;
-  /** Defaults for prune/storage snapshot when workflow omits explicit policy fields. */
   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,13 +73,6 @@ 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;
 }
 

package/src/contracts/testTriggerTypes.ts

@@ -1,18 +1,8 @@
 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>,
 > {
@@ -20,47 +10,14 @@ export interface TestTriggerSetupContext<
   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;
 }

package/src/contracts/triggerInvokerTypes.ts

@@ -0,0 +1,6 @@
+import type { Items, TriggerNodeConfig } from "./workflowTypes";
+import type { TriggerInstanceId } from "./webhookTypes";
+
+export interface TriggerInvoker {
+  invoke(trigger: TriggerInstanceId, config: TriggerNodeConfig, lastRanAt: string | undefined): Promise<Items>;
+}

package/src/contracts/webhookTypes.ts

@@ -11,7 +11,6 @@ export interface WebhookControlSignal {
 
 export interface WebhookTriggerRoutingDiagnostics {
   warn(message: string): void;
-  /** Inactive workflows omitted from the webhook route index (optional; host should wire for clarity at boot/reload). */
   info?(message: string): void;
 }
 
@@ -20,9 +19,7 @@ export interface TriggerInstanceId {
   nodeId: NodeId;
 }
 
-/** Match for an incoming HTTP request: user-defined URL segment + workflow trigger node. */
 export interface WebhookInvocationMatch {
-  /** Same value as the webhook trigger's configured endpoint key (URL segment under the webhook base path). */
   endpointPath: string;
   workflowId: WorkflowId;
   nodeId: NodeId;
@@ -30,20 +27,15 @@ export interface WebhookInvocationMatch {
   parseJsonBody?: (body: unknown) => unknown;
 }
 
-/** Result of resolving an HTTP method + endpoint path against the catalog webhook index (404 vs 405 vs match). */
 export type WebhookTriggerResolution =
   | { status: "notFound" }
   | { status: "methodNotAllowed"; match: WebhookInvocationMatch }
   | { status: "ok"; match: WebhookInvocationMatch };
 
-/**
- * Resolves webhook routes from workflow definitions (catalog-backed index, no registration at trigger setup).
- */
 export interface WebhookTriggerMatcher {
   match(args: { endpointPath: string; method: HttpMethod }): WebhookInvocationMatch | undefined;
   lookup(endpointPath: string): WebhookInvocationMatch | undefined;
   onEngineWorkflowsLoaded?(): void;
   onEngineStopped?(): void;
-  /** Rebuild route index after activation changes without stopping the engine. */
   reloadWebhookRoutes?(): void;
 }

package/src/contracts/workflowActivationPolicy.ts

@@ -1,14 +1,9 @@
 import type { WorkflowId } from "./workflowTypes";
 
-/**
- * Host-controlled policy: when false, trigger {@link TriggerNode} setup is skipped and webhook routes
- * for that workflow are not registered (see engine trigger runtime + webhook matcher).
- */
 export interface WorkflowActivationPolicy {
   isActive(workflowId: WorkflowId): boolean;
 }
 
-/** Default for tests and harnesses: every workflow is treated as active (legacy behavior). */
 export class AllWorkflowsActiveWorkflowActivationPolicy implements WorkflowActivationPolicy {
   isActive(_workflowId: WorkflowId): boolean {
     return true;

package/src/contracts/workflowTypes.ts

@@ -23,7 +23,6 @@ export interface JsonObject {
 }
 export type JsonValue = JsonPrimitive | JsonObject | JsonArray;
 export type JsonArray = ReadonlyArray<JsonValue>;
-/** JSON value that is not a top-level array (nested arrays inside objects are allowed). */
 export type JsonNonArray = JsonPrimitive | JsonObject;
 
 export interface Edge {
@@ -31,11 +30,6 @@ export interface Edge {
   to: { nodeId: NodeId; input: InputPortKey };
 }
 
-/**
- * Named connection from a parent node to child nodes that exist in {@link WorkflowDefinition.nodes}
- * but are not traversed by the main execution graph. Parents are commonly executable nodes, but may
- * also be connection-owned nodes for recursive agent attachments.
- */
 export interface WorkflowNodeConnection {
   readonly parentNodeId: NodeId;
   readonly connectionName: NodeConnectionName;
@@ -47,18 +41,10 @@ export interface WorkflowDefinition {
   name: string;
   nodes: NodeDefinition[];
   edges: Edge[];
-  /**
-   * Optional metadata: which nodes are connection-owned children (e.g. AI agent `llm` / `tools` slots).
-   * When omitted, all nodes in {@link nodes} are treated as executable for topology.
-   */
   readonly connections?: ReadonlyArray<WorkflowNodeConnection>;
-  /** Directory + file-stem path under a workflow discovery root (for UI grouping only). */
   discoveryPathSegments?: readonly string[];
-  /** Retention for run JSON and binaries (seconds). Host/env may supply defaults when omitted. */
   readonly prunePolicy?: WorkflowPrunePolicySpec;
-  /** Whether to keep run data after completion. Host/env may supply defaults when omitted. */
   readonly storagePolicy?: WorkflowStoragePolicySpec;
-  /** Invoked after a node fails permanently (retries exhausted) and node error handler did not recover. */
   readonly workflowErrorHandler?: WorkflowErrorHandlerSpec;
 }
 
@@ -76,57 +62,22 @@ export interface NodeConfigBase {
   readonly name?: string;
   readonly id?: NodeId;
   readonly icon?: string;
-  /**
-   * Plain-language, non-technical explanation of what this node does, surfaced in the workflow
-   * inspector / node properties sidebar. A first-class config option every authorable node accepts
-   * directly (alongside `id`), so it flows into the persisted config the mappers read. Distinct from
-   * {@link inspectorSummary} (config-derived label/value rows).
-   */
   readonly description?: string;
   readonly execution?: Readonly<{ hint?: "local" | "worker"; queue?: string }>;
-  /** In-process execute retries (runnable nodes). Triggers typically omit this. */
   readonly retryPolicy?: RetryPolicySpec;
-  /** Recover from execute failures; return outputs to continue, or rethrow to fail the node. */
   readonly nodeErrorHandler?: NodeErrorHandlerSpec;
-  /**
-   * When true, edges carrying zero items on an output port still schedule single-input downstream nodes.
-   * Decided from the **source** node that produced the (empty) output. Default (false/undefined): empty
-   * main batches skip downstream execution and propagate the empty path.
-   */
   readonly continueWhenEmptyOutput?: boolean;
-  /**
-   * Declared I/O port names for canvas authoring (unioned with ports inferred from edges).
-   * Use for dynamic routers (Switch) and future error ports.
-   */
   readonly declaredOutputPorts?: ReadonlyArray<OutputPortKey>;
   readonly declaredInputPorts?: ReadonlyArray<InputPortKey>;
   getCredentialRequirements?(): ReadonlyArray<CredentialRequirement>;
-  /**
-   * Marker: this node emits {@link import("./assertionTypes").AssertionResult}-shaped items on its
-   * `main` port. The TestSuiteOrchestrator (and host-side TestAssertionPersister) listen for
-   * `nodeCompleted` events from nodes with this flag set, and persist their output items as
-   * TestAssertion records (only when the run carries a `testContext`). Set on assertion node
-   * configs (e.g. `AssertionNodeConfig`, `StringEqualsAssertionNodeConfig`).
-   */
   readonly emitsAssertions?: true;
-  /**
-   * Static configuration summary surfaced in the workflow inspector — the design-time
-   * "what does this node do" panel that renders before any run telemetry exists.
-   *
-   * Return 2–6 short label/value pairs derived from this config (method + url for an HTTP
-   * call, model + tool list for an agent, schedule + timezone for a cron trigger, etc.).
-   * Values are truncated by the UI; aim for one line each. Return `undefined` to opt out
-   * — the inspector hides the section when no rows are produced.
-   *
-   * Implement on the config class instance so the function can read sibling config fields.
-   * `defineNode({ inspectorSummary })` plumbs through to this.
-   */
   inspectorSummary?(): ReadonlyArray<NodeInspectorSummaryRow> | undefined;
 }
 
-/**
- * One row of a node's static configuration summary. See {@link NodeConfigBase.inspectorSummary}.
- */
+export interface PollingTriggerConfig {
+  getTriggerPollConfig(): Readonly<{ config: JsonObject; pollIntervalMs?: number }>;
+}
+
 export interface NodeInspectorSummaryRow {
   readonly label: string;
   readonly value: string;
@@ -136,24 +87,11 @@ export declare const runnableNodeInputType: unique symbol;
 export declare const runnableNodeOutputType: unique symbol;
 export declare const triggerNodeOutputType: unique symbol;
 
-/**
- * Runnable node: **`TInputJson`** is what **`inputSchema`** validates on **`item.json`** (the wire payload).
- * **`TOutputJson`** is emitted `item.json` on outputs.
- */
 export interface RunnableNodeConfig<TInputJson = unknown, TOutputJson = unknown> extends NodeConfigBase {
   readonly kind: "node";
   readonly [runnableNodeInputType]?: TInputJson;
   readonly [runnableNodeOutputType]?: TOutputJson;
-  /**
-   * Optional Zod input contract for {@link RunnableNode} when not set on the node class.
-   * Resolution order: node instance `inputSchema`, then config `inputSchema`, then `z.unknown()`.
-   */
   readonly inputSchema?: ZodType<TInputJson>;
-  /**
-   * When an activation receives **zero** input items, the engine normally runs `execute` zero times.
-   * Set to **`runOnce`** to run `execute` once with an empty `items` batch (and a synthetic wire item for schema parsing).
-   * Used by batch-style callback nodes (built-in `Callback`) so `callback([], ctx)` still runs.
-   */
   readonly emptyBatchExecution?: "skip" | "runOnce";
 }
 
@@ -166,11 +104,6 @@ export interface TriggerNodeConfig<
   readonly kind: "trigger";
   readonly [triggerNodeOutputType]?: TOutputJson;
   readonly [triggerNodeSetupStateType]?: TSetupState;
-  /**
-   * Distinguishes triggers driven by the live activation policy (webhooks, cron, polling) from
-   * triggers driven only by the {@link TestSuiteOrchestrator}. `WorkflowActivation` skips
-   * `"test"` triggers; the orchestrator skips `"live"` triggers. Defaults to `"live"` when omitted.
-   */
   readonly triggerKind?: "live" | "test";
 }
 
@@ -239,28 +172,15 @@ export type NodeOutputs = Partial<Record<OutputPortKey, Items>>;
 
 export type RunId = string;
 export 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.
- */
 export type NodeIterationId = string;
 
 export 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?: import("./runTypes").RunTestContext;
 }
 
@@ -305,7 +225,6 @@ export interface NodeOffloadPolicy {
   decide(args: { workflowId: WorkflowId; nodeId: NodeId; config: NodeConfigBase }): NodeSchedulerDecision;
 }
 
-/** Whether to persist run execution data after the workflow finishes. */
 export type WorkflowStoragePolicyMode = "ALL" | "SUCCESS" | "ERROR" | "NEVER";
 
 export type WorkflowStoragePolicySpec = WorkflowStoragePolicyMode | TypeToken<WorkflowStoragePolicyResolver>;
@@ -370,7 +289,6 @@ export interface NodeErrorHandler {
 
 export type NodeErrorHandlerSpec = TypeToken<NodeErrorHandler> | NodeErrorHandler;
 
-/** Runtime defaults when workflow omits prune/storage fields (typically from host env). */
 export interface WorkflowPolicyRuntimeDefaults {
   readonly retentionSeconds?: number;
   readonly binaryRetentionSeconds?: number;