@codemation/core 0.13.2 → 0.15.0

package/src/authoring/definePollingTrigger.types.ts

@@ -1,18 +1,11 @@
-/**
- * definePollingTrigger — declarative helper for authoring polling triggers.
- *
- * Mirrors the ergonomics of `defineNode` / `defineRestNode` / `defineCredential`.
- * Plugin authors supply a `poll` function plus metadata; the helper synthesises the
- * two internal classes (`DefinedPollingTriggerRuntime` + `DefinedPollingTriggerConfig`)
- * that the engine's trigger machinery requires. Internal classes, DI annotations, and
- * `PollingTriggerRuntime` wiring are hidden from the plugin-author surface entirely.
- */
 import type {
   Items,
+  JsonObject,
   JsonValue,
   NodeExecutionContext,
   NodeInspectorSummaryRow,
   NodeOutputs,
+  PollingTriggerConfig,
   TestableTriggerNode,
   TriggerNodeConfig,
   TriggerSetupContext,
@@ -21,6 +14,7 @@ import type {
 } from "..";
 import type { CredentialJsonRecord, CredentialRequirement } from "../contracts/credentialTypes";
 import type { DefinedNodeCredentialAccessors, DefinedNodeCredentialBindings } from "./defineNode.types";
+import type { NodeBaseOptions } from "./nodeBaseOptions.types";
 import { node as persistedNode } from "../runtime-types/runtimeTypeDecorators.types";
 import {
   definedNodeCredentialRequirementFactory,
@@ -28,15 +22,8 @@ import {
 } from "./definePollingTriggerInternals";
 import type { ZodType } from "zod";
 
-// ---------------------------------------------------------------------------
-// Public types
-// ---------------------------------------------------------------------------
-
 type MaybePromise<TValue> = TValue | Promise<TValue>;
 
-/**
- * Context passed into the `poll` callback on each tick.
- */
 export interface DefinePollingTriggerPollContext<
   TConfig extends CredentialJsonRecord,
   TState extends JsonValue | undefined,
@@ -47,36 +34,17 @@ export interface DefinePollingTriggerPollContext<
   readonly credentials: DefinedNodeCredentialAccessors<TBindings>;
 }
 
-/**
- * What `poll` must return each tick.
- */
 export interface DefinePollingTriggerPollResult<TItemJson, TState extends JsonValue | undefined> {
-  /**
-   * New items to emit. Each item may carry an optional `dedupKey`; duplicate keys are
-   * filtered out against a rolling dedup window (managed internally by the runtime).
-   * Items without a `dedupKey` are always emitted.
-   */
   readonly items: ReadonlyArray<{ json: TItemJson; dedupKey?: string }>;
-  /** Persisted as the trigger's setup state for the next tick. */
   readonly nextState: TState;
 }
 
-/**
- * Context passed into the `execute` callback for post-emit enrichment (e.g. fetching
- * attachment bytes). Mirrors `NodeExecutionContext` so plugin authors use familiar patterns.
- */
 export type DefinePollingTriggerExecuteContext<TConfig extends TriggerNodeConfig<any, any>> =
   NodeExecutionContext<TConfig>;
 
-/**
- * Context passed into the `testItems` callback.
- */
 export type DefinePollingTriggerTestItemsContext<TConfig extends TriggerNodeConfig<any, any>> =
   TriggerTestItemsContext<TConfig>;
 
-/**
- * Options accepted by `definePollingTrigger`.
- */
 export interface DefinePollingTriggerOptions<
   TKey extends string,
   TConfig extends CredentialJsonRecord,
@@ -84,77 +52,30 @@ export interface DefinePollingTriggerOptions<
   TState extends JsonValue | undefined,
   TBindings extends DefinedNodeCredentialBindings | undefined = undefined,
 > {
-  /**
-   * Unique node-token-id-style key, e.g. `"msgraph-mail.on-new-mail"`.
-   * Used as the persisted runtime type name — must be stable across deployments.
-   */
   readonly key: TKey;
+  readonly packageName?: string;
   readonly title: string;
   readonly description?: string;
-  /** Canvas icon (same contract as `NodeConfigBase.icon`). */
   readonly icon?: string;
-  /**
-   * Zod schema for the trigger's user-facing configuration.
-   * When provided, the returned `create()` method is typed against the inferred config type.
-   */
   readonly configSchema?: ZodType<TConfig>;
-  /** Credential bindings keyed by slot (same format as `defineNode`). */
   readonly credentials?: TBindings;
-  /**
-   * Static configuration summary surfaced in the workflow inspector — see
-   * {@link import("../contracts/workflowTypes").NodeConfigBase.inspectorSummary}.
-   *
-   * Receives the static config; returns 2–6 short label/value pairs (or `undefined` to skip).
-   */
   readonly inspectorSummary?: (
     args: Readonly<{ config: TConfig }>,
   ) => ReadonlyArray<NodeInspectorSummaryRow> | undefined;
-  /**
-   * Called once when the trigger arms (or re-arms after a server restart) to provide the
-   * initial value for `state` when no persisted state exists.
-   */
   initialState?(): TState;
-  /**
-   * Polling interval in milliseconds. The runtime enforces a minimum of 25 ms.
-   * @default 60_000
-   */
   readonly pollIntervalMs?: number;
-  /**
-   * The per-tick poll logic. Called by the runtime each interval.
-   * Must return new items plus the next persisted state.
-   */
   poll(
     pollCtx: DefinePollingTriggerPollContext<TConfig, TState, TBindings>,
   ): MaybePromise<DefinePollingTriggerPollResult<TItemJson, TState>>;
-  /**
-   * Optional post-emit enrichment step (runs in the normal node-execute phase after the
-   * trigger fires and the workflow run starts). Use for expensive per-item work such as
-   * fetching attachment bytes via `ctx.binary.attach`. When omitted, the trigger passes
-   * items through unchanged.
-   */
   execute?(
     items: Items<TItemJson>,
     ctx: NodeExecutionContext<DefinedPollingTriggerConfig<TConfig, TItemJson>>,
   ): MaybePromise<NodeOutputs>;
-  /**
-   * Optional implementation for the workflow UI's "Test" button. Should return a small
-   * sample of current items without consulting or mutating polling state.
-   */
   testItems?(
     ctx: TriggerTestItemsContext<DefinedPollingTriggerConfig<TConfig, TItemJson>>,
   ): MaybePromise<Items<TItemJson>>;
 }
 
-// ---------------------------------------------------------------------------
-// DefinedPollingTrigger (returned object)
-// ---------------------------------------------------------------------------
-
-/**
- * The object returned by `definePollingTrigger`. Register it via
- * `definePlugin({ nodes: [myTrigger] })` or call `.register(ctx)` directly.
- *
- * `poll` is also directly callable for unit-testing — no runtime needed.
- */
 export interface DefinedPollingTrigger<
   TKey extends string,
   TConfig extends CredentialJsonRecord,
@@ -166,43 +87,27 @@ export interface DefinedPollingTrigger<
   readonly key: TKey;
   readonly title: string;
   readonly description?: string;
-  /**
-   * Create the trigger config for use in workflow definitions.
-   * @param cfg - User-facing trigger configuration.
-   * @param name - Display name (defaults to `title`).
-   * @param id - Optional stable node id.
-   */
-  create(cfg: TConfig, name?: string, id?: string): DefinedPollingTriggerConfig<TConfig, TItemJson>;
-  /**
-   * Test seam: call `poll` directly without starting the runtime.
-   * Returns `{ items, nextState }` just like the real runtime receives.
-   */
+  create(
+    cfg: TConfig,
+    name?: string,
+    idOrOptions?: string | NodeBaseOptions,
+  ): DefinedPollingTriggerConfig<TConfig, TItemJson>;
   poll(
     pollCtx: Omit<DefinePollingTriggerPollContext<TConfig, TState, TBindings>, "credentials"> & {
       credentials?: DefinedNodeCredentialAccessors<TBindings>;
     },
   ): MaybePromise<DefinePollingTriggerPollResult<TItemJson, TState>>;
-  /** Registers the synthesised runtime class with the plugin container. */
   register(context: { registerNode<TValue>(token: TypeToken<TValue>, implementation?: TypeToken<TValue>): void }): void;
 }
 
-// ---------------------------------------------------------------------------
-// DefinedPollingTriggerConfig (TriggerNodeConfig shape for the engine)
-// ---------------------------------------------------------------------------
-
-/**
- * TriggerNodeConfig produced by `DefinedPollingTrigger.create(...)`.
- * Holds user configuration and credential requirements for the engine.
- * The setup state type is opaque `JsonValue | undefined` — the runtime
- * uses an internal wrapped shape that plugin authors never see.
- */
-export class DefinedPollingTriggerConfig<TConfig extends CredentialJsonRecord, TItemJson> implements TriggerNodeConfig<
-  TItemJson,
-  JsonValue | undefined
-> {
+export class DefinedPollingTriggerConfig<TConfig extends CredentialJsonRecord, TItemJson>
+  implements TriggerNodeConfig<TItemJson, JsonValue | undefined>, PollingTriggerConfig
+{
   readonly kind = "trigger" as const;
   readonly type: TypeToken<unknown>;
   readonly icon: string | undefined;
+  readonly id?: string;
+  readonly description?: string;
 
   constructor(
     public readonly name: string,
@@ -210,29 +115,37 @@ export class DefinedPollingTriggerConfig<TConfig extends CredentialJsonRecord, T
     typeToken: TypeToken<unknown>,
     icon: string | undefined,
     private readonly credentialRequirements: ReadonlyArray<CredentialRequirement>,
-    public readonly id?: string,
+    idOrOptions?: string | NodeBaseOptions,
     private readonly inspectorSummaryFn?: (
       args: Readonly<{ config: TConfig }>,
     ) => ReadonlyArray<NodeInspectorSummaryRow> | undefined,
+    private readonly defaultPollIntervalMs?: number,
   ) {
     this.type = typeToken;
     this.icon = icon;
+    const resolved = typeof idOrOptions === "string" ? { id: idOrOptions } : idOrOptions;
+    this.id = resolved?.id;
+    this.description = resolved?.description;
   }
 
   getCredentialRequirements(): ReadonlyArray<CredentialRequirement> {
     return this.credentialRequirements;
   }
 
+  getTriggerPollConfig(): Readonly<{ config: JsonObject; pollIntervalMs?: number }> {
+    const cfgPollInterval = (this.cfg as Partial<{ pollIntervalMs: number }>).pollIntervalMs;
+    const resolvedInterval = cfgPollInterval ?? this.defaultPollIntervalMs;
+    return {
+      config: this.cfg as unknown as JsonObject,
+      pollIntervalMs: resolvedInterval,
+    };
+  }
+
   inspectorSummary(): ReadonlyArray<NodeInspectorSummaryRow> | undefined {
     return this.inspectorSummaryFn?.({ config: this.cfg });
   }
 }
 
-// ---------------------------------------------------------------------------
-// Internal wrapped state helpers
-// ---------------------------------------------------------------------------
-
-/** Opaque shape stored in the trigger setup state repository. @internal */
 interface InternalWrappedState {
   readonly userState: JsonValue | undefined;
   readonly seenKeys: ReadonlyArray<string>;
@@ -247,32 +160,6 @@ function isWrappedState(value: unknown): value is InternalWrappedState {
   );
 }
 
-// ---------------------------------------------------------------------------
-// Implementation factory
-// ---------------------------------------------------------------------------
-
-/**
- * Declarative helper for authoring polling triggers.
- *
- * ```ts
- * export const onNewMail = definePollingTrigger({
- *   key: "my-plugin.on-new-mail",
- *   title: "On new mail",
- *   configSchema: z.object({ folder: z.string() }),
- *   credentials: { auth: myOAuthCredentialType },
- *   initialState: () => ({ lastSeenId: undefined }),
- *   pollIntervalMs: 60_000,
- *   async poll({ config, state, credentials }) {
- *     const session = await credentials.auth();
- *     const messages = await fetchMessages(session, config.folder, state.lastSeenId);
- *     return {
- *       items: messages.map(m => ({ json: m, dedupKey: m.id })),
- *       nextState: { lastSeenId: messages[0]?.id ?? state.lastSeenId },
- *     };
- *   },
- * });
- * ```
- */
 export function definePollingTrigger<
   TKey extends string,
   TConfig extends CredentialJsonRecord,
@@ -287,10 +174,6 @@ export function definePollingTrigger<
 
   type TConfig_ = DefinedPollingTriggerConfig<TConfig, TItemJson>;
 
-  // ---------------------------------------------------------------------------
-  // Synthesised runtime class (implements TestableTriggerNode)
-  // ---------------------------------------------------------------------------
-
   const DefinedPollingTriggerRuntime = class implements TestableTriggerNode<TConfig_> {
     readonly kind = "trigger" as const;
     readonly outputPorts = ["main"] as const;
@@ -300,7 +183,6 @@ export function definePollingTrigger<
       const intervalMs =
         (cfg as Partial<{ pollIntervalMs: number }>).pollIntervalMs ?? options.pollIntervalMs ?? DEFAULT_INTERVAL_MS;
 
-      // Unwrap previously persisted state, or create the initial wrapped state.
       const persisted = ctx.previousState;
       const existingWrapped: InternalWrappedState | undefined = isWrappedState(persisted) ? persisted : undefined;
       const seedWrapped: InternalWrappedState = existingWrapped ?? {
@@ -326,7 +208,6 @@ export function definePollingTrigger<
             credentials: credentialAccessors,
           });
 
-          // Dedup: filter items whose dedupKey is already seen
           const newItems: Array<{ json: TItemJson }> = [];
           const newKeys: string[] = [];
           for (const item of pollResult.items) {
@@ -339,7 +220,6 @@ export function definePollingTrigger<
             newItems.push({ json: item.json });
           }
 
-          // Merge keys, cap the window at 2000 to bound state size
           const allKeys = [...wrapped.seenKeys, ...newKeys];
           const cappedKeys = allKeys.length > 2000 ? allKeys.slice(allKeys.length - 2000) : allKeys;
 
@@ -373,11 +253,7 @@ export function definePollingTrigger<
     }
   };
 
-  persistedNode({ name: options.key })(DefinedPollingTriggerRuntime);
-
-  // ---------------------------------------------------------------------------
-  // Returned definition object
-  // ---------------------------------------------------------------------------
+  persistedNode({ name: options.key, packageName: options.packageName })(DefinedPollingTriggerRuntime);
 
   const definition: DefinedPollingTrigger<TKey, TConfig, TItemJson, TState, TBindings> = {
     kind: "defined-polling-trigger",
@@ -385,17 +261,22 @@ export function definePollingTrigger<
     title: options.title,
     description: options.description,
 
-    create(cfg: TConfig, name = options.title, id?: string): DefinedPollingTriggerConfig<TConfig, TItemJson> {
+    create(
+      cfg: TConfig,
+      name = options.title,
+      idOrOptions?: string | NodeBaseOptions,
+    ): DefinedPollingTriggerConfig<TConfig, TItemJson> {
       return new DefinedPollingTriggerConfig<TConfig, TItemJson>(
         name,
         cfg,
         DefinedPollingTriggerRuntime,
         options.icon,
         credentialRequirements,
-        id,
+        idOrOptions,
         options.inspectorSummary as
           | ((args: Readonly<{ config: TConfig }>) => ReadonlyArray<NodeInspectorSummaryRow> | undefined)
           | undefined,
+        options.pollIntervalMs,
       );
     },
 

package/src/authoring/definePollingTriggerInternals.ts

@@ -1,7 +1,3 @@
-/**
- * Shared internal helpers for defineNode and definePollingTrigger.
- * Not part of the public API — import only from authoring helpers.
- */
 import type { AnyCredentialType, CredentialRequirement, CredentialTypeId } from "../contracts/credentialTypes";
 import type { NodeExecutionContext } from "../contracts/runtimeTypes";
 import type { RunnableNodeConfig } from "../contracts/workflowTypes";

package/src/authoring/index.ts

@@ -1,4 +1,5 @@
 export { DefinedNodeRegistry } from "./DefinedNodeRegistry";
+export type { NodeBaseOptions } from "./nodeBaseOptions.types";
 export type {
   DefinedNode,
   DefinedNodeConfigInput,

package/src/authoring/nodeBaseOptions.types.ts

@@ -0,0 +1,4 @@
+export interface NodeBaseOptions {
+  readonly id?: string;
+  readonly description?: string;
+}

package/src/binaries/boundedReadBinary.types.ts

@@ -2,19 +2,6 @@ import type { BinaryAttachment, BinaryStorage } from "../types";
 import type { BinaryStorageReadResult } from "../types";
 import { BINARY_DEFAULT_MAX_BYTES } from "../contracts/runtimeTypes";
 
-/**
- * Reads all bytes from an already-opened binary stream into a contiguous `Uint8Array`.
- *
- * Safety contract:
- *  - `attachment.size` is checked against `maxBytes` *before* any allocation (no OOM).
- *  - A single buffer of exactly `attachment.size` is pre-allocated; the stream fills it
- *    directly — no chunks array, no doubling.
- *  - A byte-count mismatch between the declared size and actual stream content is an error.
- *
- * This is the single canonical implementation; `ExecutionBinaryService.getBytes`,
- * `getText`, and `getJson` all delegate here. The per-package `readBinaryBody` helpers
- * in `core-nodes` and `core-nodes-ocr` have been removed in favour of this function.
- */
 export async function boundedReadBinary(
   result: BinaryStorageReadResult,
   attachment: BinaryAttachment,
@@ -49,7 +36,6 @@ export async function boundedReadBinary(
   return out;
 }
 
-/** Shared implementation of `getBytes` used by both binary-service classes. */
 export async function readBinaryAsBytes(
   storage: BinaryStorage,
   attachment: BinaryAttachment,
@@ -62,7 +48,6 @@ export async function readBinaryAsBytes(
   return boundedReadBinary(result, attachment, maxBytes);
 }
 
-/** Shared implementation of `getText` used by both binary-service classes. */
 export async function readBinaryAsText(
   storage: BinaryStorage,
   attachment: BinaryAttachment,
@@ -72,7 +57,6 @@ export async function readBinaryAsText(
   return new TextDecoder().decode(bytes);
 }
 
-/** Shared implementation of `getJson` used by both binary-service classes. */
 export async function readBinaryAsJson<T = unknown>(
   storage: BinaryStorage,
   attachment: BinaryAttachment,

package/src/bootstrap/index.ts

@@ -1,4 +1,3 @@
-/** Composition-root engine graph and advanced runtime wiring. Not part of the main `@codemation/core` barrel. */
 export { Engine } from "../orchestration/Engine";
 export {
   AbortControllerFactory,
@@ -57,4 +56,11 @@ export {
   WorkflowStoragePolicyEvaluator,
   type EngineExecutionLimitsPolicyConfig,
 } from "../policies";
-export { MissingRuntimeTriggerToken, PersistedWorkflowTokenRegistry } from "../workflowSnapshots";
+export {
+  MissingRuntimeParityGuard,
+  MissingRuntimeTriggerToken,
+  PersistedWorkflowTokenRegistry,
+  WorkflowParityMismatchError,
+  type MissingRuntimeNodeDetail,
+} from "../workflowSnapshots";
+export { WorkflowSnapshotCodec } from "../workflowSnapshots/WorkflowSnapshotCodec";

package/src/bootstrap/runtime/EngineRuntimeRegistrar.ts

@@ -33,11 +33,6 @@ import { Engine } from "../../orchestration/Engine";
 import type { EngineRuntimeRegistrationOptions } from "./EngineRuntimeRegistration.types";
 import type { WebhookTriggerMatcherProvider } from "./EngineRuntimeRegistration.types";
 
-/**
- * Container-first entry: call on a host/test container **after** workflow, run, node, and credential
- * ports are registered. The registrar owns the default inline scheduler, engine binding,
- * and intent-surface wiring so hosts only override the seams they actually replace.
- */
 export class EngineRuntimeRegistrar {
   register(container: DependencyContainer, options?: EngineRuntimeRegistrationOptions): void {
     this.registerSupportFactories(container);

package/src/bootstrap/runtime/EngineRuntimeRegistration.types.ts

@@ -5,42 +5,19 @@ import type { TriggerRuntimeDiagnostics } from "../../contracts/runtimeTypes";
 import type { WorkflowPolicyRuntimeDefaults } from "../../contracts/workflowTypes";
 import type { EngineExecutionLimitsPolicyConfig } from "../../policies/executionLimits/EngineExecutionLimitsPolicy";
 
-/**
- * Creates the webhook route matcher used by {@link import("../api/Engine").Engine}.
- * Hosts may supply logging/diagnostics; tests often use the default factory without diagnostics.
- */
 export interface WebhookTriggerMatcherProvider {
   createMatcher(container: DependencyContainer): WebhookTriggerMatcher;
 }
 
-/**
- * Supplies optional trigger-runtime logging (inactive workflow skips, activation sync).
- */
 export interface TriggerRuntimeDiagnosticsProvider {
   create(container: DependencyContainer): TriggerRuntimeDiagnostics | undefined;
 }
 
 export interface EngineRuntimeRegistrationOptions {
-  /**
-   * Static limits merged into the factory when the policy token is first resolved.
-   * Prefer {@link resolveEngineExecutionLimits} when limits can change after registration (e.g. host `useRuntimeConfig`).
-   */
   engineExecutionLimits?: Partial<EngineExecutionLimitsPolicyConfig>;
-  /**
-   * Called when the limits policy is first resolved; overrides {@link engineExecutionLimits} when both are set.
-   * Use this for host wiring so `runtime.engineExecutionLimits` applied after `registerCoreInfrastructure` is honored.
-   */
   resolveEngineExecutionLimits?: () => Partial<EngineExecutionLimitsPolicyConfig> | undefined;
-  /**
-   * When {@link webhookTriggerMatcherProvider} is omitted, the registrar builds
-   * {@link import("../../runtime/WorkflowRepositoryWebhookTriggerMatcher").WorkflowRepositoryWebhookTriggerMatcher}
-   * using this optional routing diagnostics surface.
-   */
   webhookTriggerRoutingDiagnostics?: WebhookTriggerRoutingDiagnostics;
-  /** Overrides default webhook matcher construction (e.g. host-injected loggers). */
   webhookTriggerMatcherProvider?: WebhookTriggerMatcherProvider;
-  /** Overrides default trigger diagnostics (undefined when omitted). */
   triggerRuntimeDiagnosticsProvider?: TriggerRuntimeDiagnosticsProvider;
-  /** Runtime retention/storage defaults used when workflows omit prune/storage policy fields. */
   workflowPolicyRuntimeDefaults?: WorkflowPolicyRuntimeDefaults;
 }

package/src/browser.ts

@@ -1,6 +1,3 @@
-/**
- * Browser / Next client–safe surface: no Node builtins or modules that pull `runStorage` (e.g. `node:stream/web`).
- */
 export { AgentConnectionNodeCollector } from "./ai/AgentConnectionNodeCollector";
 export type {
   AgentConnectionCredentialSource,

package/src/contracts/AgentBindError.ts

@@ -1,8 +1,3 @@
-/**
- * Thrown at agent bind time when mcpServers declarations cannot be resolved.
- * Causes include: unknown server id, missing credential instance, insufficient scopes,
- * and ambiguous shorthand binding (multiple credential instances match).
- */
 export class AgentBindError extends Error {
   constructor(message: string) {
     super(message);

package/src/contracts/Clock.ts

@@ -1,4 +1,3 @@
-/** Port for time; inject `SystemClock` in production and a fake/test clock in tests. */
 export interface Clock {
   now(): Date;
 }

package/src/contracts/CodemationTelemetryAttributeNames.ts

@@ -9,24 +9,14 @@ export class CodemationTelemetryAttributeNames {
   static readonly connectionInvocationId = "codemation.connection.invocation_id";
   static readonly toolName = "codemation.tool.name";
   static readonly traceParentRunId = "codemation.parent.run.id";
-  /** Per-item iteration that emitted this span/metric. Set on spans recorded inside a runnable per-item loop. */
   static readonly iterationId = "codemation.iteration.id";
-  /** Item index (0-based) of the iteration. */
   static readonly iterationIndex = "codemation.iteration.index";
-  /** Set when this span/metric was recorded under a sub-agent triggered by an outer LLM/tool call. */
   static readonly parentInvocationId = "codemation.parent.invocation_id";
-  /** MCP server id on spans created for callTool invocations. */
   static readonly mcpServerId = "mcp.server_id";
-  /** MCP tool name on spans created for callTool invocations. */
   static readonly mcpToolName = "mcp.tool_name";
-  /** Terminal node-execution status (e.g. `"hitl-approved"`, `"hitl-rejected"`) on HITL outcome spans. */
   static readonly nodeExecutionStatus = "codemation.node.execution_status";
-  /** Populated on run-halted spans; discriminates the halt reason (e.g. `"hitl-rejected"`). */
   static readonly runHaltReason = "codemation.run.halt_reason";
-  /** Human task ID on `hitl.task.*` span events. */
   static readonly hitlTaskId = "codemation.hitl.task_id";
-  /** HITL channel name (e.g. `"inbox"`, `"control-plane-inbox"`) on `hitl.task.*` span events. */
   static readonly hitlChannel = "codemation.hitl.channel";
-  /** Decision outcome (e.g. `"approved"`, `"rejected"`) on `hitl.task.decided` span events. */
   static readonly hitlDecisionStatus = "codemation.hitl.decision_status";
 }

package/src/contracts/NoOpAgentMcpIntegration.ts

@@ -1,11 +1,5 @@
 import type { AgentMcpIntegration, AgentMcpToolMap } from "./agentMcpTypes";
 
-/**
- * No-op implementation of AgentMcpIntegration.
- * Registered by the core engine runtime as a fallback when the host does not
- * supply a real implementation (e.g. in unit tests or headless engine setups).
- * Always returns an empty tool map so the agent runs with node-backed tools only.
- */
 export class NoOpAgentMcpIntegration implements AgentMcpIntegration {
   async prepareMcpTools(): Promise<AgentMcpToolMap> {
     return new Map();

package/src/contracts/NoOpTelemetrySpanScope.ts

@@ -11,12 +11,6 @@ import type {
 } from "./telemetryTypes";
 import { NoOpTelemetryArtifactReference } from "./NoOpTelemetryArtifactReference";
 
-/**
- * Standalone no-op {@link NodeExecutionTelemetry} value used as the return for `asNodeTelemetry`.
- *
- * Defined here (instead of in `NoOpNodeExecutionTelemetry.ts`) so that {@link NoOpTelemetrySpanScope}
- * can return it without importing the other module — both no-ops share this leaf.
- */
 const noOpNodeExecutionTelemetry: NodeExecutionTelemetry = {
   traceId: "00000000000000000000000000000000",
   spanId: "0000000000000000",
@@ -53,6 +47,5 @@ const noOpTelemetrySpanScope: TelemetrySpanScope = {
 
 export class NoOpTelemetrySpanScope {
   static readonly value: TelemetrySpanScope = noOpTelemetrySpanScope;
-  /** Internal: the shared no-op {@link NodeExecutionTelemetry} that {@link NoOpNodeExecutionTelemetry} re-exposes. */
   static readonly nodeExecutionTelemetryValue: NodeExecutionTelemetry = noOpNodeExecutionTelemetry;
 }

package/src/contracts/RetryPolicy.ts

@@ -15,9 +15,7 @@ export class RetryPolicy implements FixedRetryPolicySpec {
     }
   }
 
-  /** Default for HTTP-style transient failures: 3 tries, 1s between attempts. */
   static readonly defaultForHttp: FixedRetryPolicySpec = { kind: "fixed", maxAttempts: 3, delayMs: 1000 };
 
-  /** Default for LLM / agent calls: 3 tries, 2s fixed backoff. */
   static readonly defaultForAiAgent: FixedRetryPolicySpec = { kind: "fixed", maxAttempts: 3, delayMs: 2000 };
 }

package/src/contracts/agentMcpTypes.ts

@@ -3,44 +3,15 @@ import type { ConnectionInvocationAppendArgs, ConnectionInvocationId } from "./r
 import type { TelemetrySpanEventRecord } from "./telemetryTypes";
 import type { NodeActivationId, NodeIterationId } from "./workflowTypes";
 
-/**
- * Emitted as a span event when a credential is missing required scopes
- * (bind-time) or when callTool returns a permission error (runtime).
- * The credential type id can be looked up from the credential instance when needed.
- */
 export interface NeedsReconsentEvent {
   readonly serverId: string;
   readonly credentialInstanceId: string;
   readonly missingScopesHint?: readonly string[];
 }
 
-/**
- * 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.
- */
 export 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.
- */
 export 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;
@@ -50,15 +21,10 @@ export interface AgentMcpIntegration {
     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>;
 }