@codemation/core 0.10.2 → 0.11.1

package/src/authoring/defineNode.types.ts

@@ -6,7 +6,7 @@ import type {
 } from "../contracts/credentialTypes";
 import type { ParamDeep } from "../contracts/params";
 import type { RunnableNode, RunnableNodeExecuteArgs, NodeExecutionContext } from "../contracts/runtimeTypes";
-import type { Item, Items, RunnableNodeConfig } from "../contracts/workflowTypes";
+import type { Item, Items, NodeInspectorSummaryRow, RunnableNodeConfig } from "../contracts/workflowTypes";
 import type { TypeToken } from "../di";
 import { node as persistedNode } from "../runtime-types/runtimeTypeDecorators.types";
 import type { ZodType } from "zod";
@@ -120,6 +120,15 @@ export interface DefineNodeOptions<
   readonly inputSchema?: ZodType<TInputJson>;
   /** Preserve inbound `item.binary` when `execute` returns plain JSON or item-shaped results without `binary`. */
   readonly keepBinaries?: boolean;
+  /**
+   * 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;
   execute(
     args: DefineNodeExecuteArgs<TConfig, TInputJson>,
     context: DefinedNodeRunContext<TConfig, TBindings>,
@@ -143,6 +152,9 @@ export interface DefineBatchNodeOptions<
   readonly input?: Readonly<Record<keyof TConfig & string, unknown>>;
   readonly configSchema?: z.ZodType<TConfig>;
   readonly credentials?: TBindings;
+  readonly inspectorSummary?: (
+    args: Readonly<{ config: TConfig }>,
+  ) => ReadonlyArray<NodeInspectorSummaryRow> | undefined;
   run(
     items: ReadonlyArray<TInputJson>,
     context: DefinedNodeRunContext<TConfig, TBindings>,
@@ -273,6 +285,10 @@ export function defineNode<
     getCredentialRequirements(): ReadonlyArray<CredentialRequirement> {
       return credentialRequirements;
     }
+
+    inspectorSummary(): ReadonlyArray<NodeInspectorSummaryRow> | undefined {
+      return options.inspectorSummary?.({ config: this.config });
+    }
   };
 
   const definition: DefinedNode<TKey, TConfig, TInputJson, TOutputJson, TBindings> = {
@@ -356,6 +372,10 @@ export function defineBatchNode<
     getCredentialRequirements(): ReadonlyArray<CredentialRequirement> {
       return credentialRequirements;
     }
+
+    inspectorSummary(): ReadonlyArray<NodeInspectorSummaryRow> | undefined {
+      return options.inspectorSummary?.({ config: this.config });
+    }
   };
 
   const definition: DefinedNode<TKey, TConfig, TInputJson, TOutputJson, TBindings> = {

package/src/authoring/definePollingTrigger.types.ts

@@ -11,6 +11,7 @@ import type {
   Items,
   JsonValue,
   NodeExecutionContext,
+  NodeInspectorSummaryRow,
   NodeOutputs,
   TestableTriggerNode,
   TriggerNodeConfig,
@@ -99,6 +100,15 @@ export interface DefinePollingTriggerOptions<
   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.
@@ -201,6 +211,9 @@ export class DefinedPollingTriggerConfig<TConfig extends CredentialJsonRecord, T
     icon: string | undefined,
     private readonly credentialRequirements: ReadonlyArray<CredentialRequirement>,
     public readonly id?: string,
+    private readonly inspectorSummaryFn?: (
+      args: Readonly<{ config: TConfig }>,
+    ) => ReadonlyArray<NodeInspectorSummaryRow> | undefined,
   ) {
     this.type = typeToken;
     this.icon = icon;
@@ -209,6 +222,10 @@ export class DefinedPollingTriggerConfig<TConfig extends CredentialJsonRecord, T
   getCredentialRequirements(): ReadonlyArray<CredentialRequirement> {
     return this.credentialRequirements;
   }
+
+  inspectorSummary(): ReadonlyArray<NodeInspectorSummaryRow> | undefined {
+    return this.inspectorSummaryFn?.({ config: this.cfg });
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -376,6 +393,9 @@ export function definePollingTrigger<
         options.icon,
         credentialRequirements,
         id,
+        options.inspectorSummary as
+          | ((args: Readonly<{ config: TConfig }>) => ReadonlyArray<NodeInspectorSummaryRow> | undefined)
+          | undefined,
       );
     },
 

package/src/binaries/UnavailableBinaryStorage.ts

@@ -16,4 +16,10 @@ export class UnavailableBinaryStorage implements BinaryStorage {
   }
 
   async delete(): Promise<void> {}
+
+  async deleteMany(): Promise<void> {}
+
+  async listByPrefix(): Promise<ReadonlyArray<string>> {
+    return [];
+  }
 }

package/src/bootstrap/runtime/EngineRuntimeRegistrar.ts

@@ -1,5 +1,6 @@
 import { instanceCachingFactory, type DependencyContainer } from "../../di";
 import { CoreTokens } from "../../di";
+import { NoOpAgentMcpIntegration } from "../../contracts/NoOpAgentMcpIntegration";
 import { EngineExecutionLimitsPolicyFactory } from "../../policies/executionLimits/EngineExecutionLimitsPolicyFactory";
 import {
   ChildExecutionScopeFactory,
@@ -39,6 +40,14 @@ export class EngineRuntimeRegistrar {
     this.registerDefaultActivationScheduler(container);
     this.registerEngine(container, options);
     this.registerIntentServices(container);
+    this.registerAgentMcpIntegration(container);
+  }
+
+  private registerAgentMcpIntegration(container: DependencyContainer): void {
+    if (container.isRegistered(CoreTokens.AgentMcpIntegration, true)) {
+      return;
+    }
+    container.registerInstance(CoreTokens.AgentMcpIntegration, new NoOpAgentMcpIntegration());
   }
 
   private registerSupportFactories(container: DependencyContainer): void {

package/src/browser.ts

@@ -6,6 +6,7 @@ export type {
   AgentConnectionCredentialSource,
   AgentConnectionNodeDescriptor,
   AgentConnectionNodeRole,
+  McpServerResolver,
 } from "./ai/AgentConnectionNodeCollector";
 export type { AgentNodeConfig } from "./ai/AiHost";
 export { ConnectionNodeIdFactory } from "./workflow/definition/ConnectionNodeIdFactory";

package/src/contracts/AgentBindError.ts

@@ -0,0 +1,11 @@
+/**
+ * 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);
+    this.name = "AgentBindError";
+  }
+}

package/src/contracts/CodemationTelemetryAttributeNames.ts

@@ -15,4 +15,8 @@ export class CodemationTelemetryAttributeNames {
   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";
 }

package/src/contracts/NoOpAgentMcpIntegration.ts

@@ -0,0 +1,13 @@
+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/agentMcpTypes.ts

@@ -0,0 +1,64 @@
+import type { NodeId, WorkflowId } from "./baseTypes";
+import type { ConnectionInvocationAppendArgs, ConnectionInvocationId } from "./runTypes";
+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;
+    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>;
+}

package/src/contracts/index.ts

@@ -1,5 +1,9 @@
+export * from "./AgentBindError";
+export * from "./agentMcpTypes";
+export * from "./NoOpAgentMcpIntegration";
 export * from "./baseTypes";
 export * from "./assertionTypes";
+export * from "./mcpTypes";
 export * from "./collectionTypes";
 export * from "./credentialTypes";
 export * from "./emitPorts";

package/src/contracts/mcpTypes.ts

@@ -0,0 +1,29 @@
+export type McpServerTransport = "http";
+// "stdio" is a self-host-only escape hatch (CODEMATION_ALLOW_STDIO_MCP=true); not typed here for managed.
+
+export 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>;
+}

package/src/contracts/runTypes.ts

@@ -88,6 +88,8 @@ export interface PersistedWorkflowSnapshotNode {
   tokenName?: string;
   configTokenName?: string;
   config: unknown;
+  /** Pre-computed static configuration summary; populated by WorkflowSnapshotCodec. */
+  inspectorSummary?: ReadonlyArray<Readonly<{ label: string; value: string }>>;
 }
 
 export interface PersistedWorkflowSnapshot {
@@ -174,6 +176,10 @@ export interface ConnectionInvocationRecord {
   readonly status: NodeExecutionStatus;
   readonly managedInput?: JsonValue;
   readonly managedOutput?: JsonValue;
+  /** Short human-readable description of what this invocation is doing right now (e.g. `"calling search_messages"`). Rendered as a sub-line on the canvas node card. */
+  readonly statusLabel?: string;
+  /** Stable identifier for the thing this invocation acts on (e.g. an MCP tool name like `"search_messages"`). Persists across status transitions so the inspector can show it on completed/failed entries too. Connection nodes that ARE the tool (e.g. node-backed agent tools) leave this unset — the parent node id already identifies the subject. */
+  readonly subjectName?: string;
   readonly error?: NodeExecutionError;
   readonly queuedAt?: string;
   readonly startedAt?: string;
@@ -196,6 +202,8 @@ export type ConnectionInvocationAppendArgs = Readonly<{
   status: NodeExecutionStatus;
   managedInput?: JsonValue;
   managedOutput?: JsonValue;
+  statusLabel?: string;
+  subjectName?: string;
   error?: NodeExecutionError;
   queuedAt?: string;
   startedAt?: string;

package/src/contracts/runtimeTypes.ts

@@ -128,6 +128,10 @@ 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>>;
 }
 
 export interface BinaryAttachmentCreateRequest {

package/src/contracts/workflowTypes.ts

@@ -102,6 +102,27 @@ export interface NodeConfigBase {
    * 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 NodeInspectorSummaryRow {
+  readonly label: string;
+  readonly value: string;
 }
 
 export declare const runnableNodeInputType: unique symbol;

package/src/contracts.ts

@@ -1,6 +1,9 @@
 // Pure-type-only re-exports. Use this for type-only consumers that should not drag in runtime DSL or factory code.
 // This subpath prevents unnecessary compile-graph bloat for packages that only need types like NodeId, Items, etc.
 
+export type * from "./contracts/agentMcpTypes";
+export * from "./contracts/AgentBindError";
+export * from "./contracts/NoOpAgentMcpIntegration";
 export type * from "./contracts/baseTypes";
 export type * from "./contracts/assertionTypes";
 // assertionTypes also exports a runtime helper for deriving pass/fail from a score+threshold.

package/src/credentials/OAuthFlowExecutor.types.ts

@@ -0,0 +1,45 @@
+/**
+ * Four-concept model for credentials (see docs/design/credentials-oauth-unification.md):
+ *   1. CredentialType — schema for stored material (e.g. "oauth.google.gmail").
+ *   2. Credential slot requirement — which types a node or MCP server accepts.
+ *   3. CredentialInstance — a stored, usable token row in the host's credential store.
+ *   4. OAuthFlowExecutor (this file) — the only concept that differs between deployment
+ *      modes. DI selects one implementation at boot; the rest of the system programs
+ *      against this interface alone.
+ */
+
+export interface OAuthFlowStartArgs {
+  readonly typeId: string;
+  readonly scopes: ReadonlyArray<string>;
+  readonly redirectUri: string;
+  readonly instanceId?: string;
+}
+
+export interface OAuthFlowStartResult {
+  readonly consentUrl: string;
+  readonly stateToken: string;
+}
+
+export interface OAuthFlowCallbackArgs {
+  readonly stateToken: string;
+  readonly code: string;
+}
+
+export interface OAuthMaterial {
+  readonly accessToken: string;
+  readonly refreshToken?: string;
+  readonly expiresAt?: string;
+  readonly grantedScopes: ReadonlyArray<string>;
+}
+
+export interface OAuthFlowExecutor {
+  start(args: OAuthFlowStartArgs): Promise<OAuthFlowStartResult>;
+  /**
+   * Returns the instanceId associated with a pending stateToken without consuming it.
+   * Used by callback routes to identify the target instance before calling completeCallback.
+   * Returns undefined when the stateToken is unknown or already consumed.
+   */
+  lookupInstanceId(stateToken: string): string | undefined;
+  completeCallback(args: OAuthFlowCallbackArgs): Promise<OAuthMaterial>;
+  refresh(args: { typeId: string; instanceId: string; material: OAuthMaterial }): Promise<OAuthMaterial>;
+}

package/src/di/CoreTokens.ts

@@ -1,6 +1,7 @@
 import type { TypeToken } from "./index";
 import type { RunEventBus } from "../events/runEvents";
 import type { EngineExecutionLimitsPolicy } from "../policies/executionLimits/EngineExecutionLimitsPolicy";
+import type { AgentMcpIntegration } from "../contracts/agentMcpTypes";
 import type {
   ActivationIdFactory,
   BinaryStorage,
@@ -57,4 +58,10 @@ export const CoreTokens = {
   WorkflowActivationPolicy: Symbol.for(
     "codemation.core.WorkflowActivationPolicy",
   ) as TypeToken<WorkflowActivationPolicy>,
+  /**
+   * Optional. When registered, AIAgentNode uses it to resolve mcpServers bindings,
+   * validate scopes, open pool connections, and prepare the MCP ToolSet map.
+   * Not registered in the default core bootstrap — the host provides the implementation.
+   */
+  AgentMcpIntegration: Symbol.for("codemation.core.AgentMcpIntegration") as TypeToken<AgentMcpIntegration>,
 } as const;

package/src/execution/InProcessRetryRunner.ts

@@ -7,6 +7,9 @@ import type { AsyncSleeper } from "./asyncSleeper.types";
 
 export type { AsyncSleeper } from "./asyncSleeper.types";
 
+/** Maximum permitted retry attempts — workflow-declared values above this are clamped. */
+const HARD_MAX_RETRY_ATTEMPTS = 10;
+
 type NormalizedPolicy =
   | { readonly kind: "none"; readonly maxAttempts: 1 }
   | { readonly kind: "fixed"; readonly maxAttempts: number; readonly delayMs: number }
@@ -22,8 +25,13 @@ type NormalizedPolicy =
 export class InProcessRetryRunner {
   constructor(private readonly sleeper: AsyncSleeper) {}
 
-  async run<T>(policy: RetryPolicySpec | undefined, work: () => Promise<T>): Promise<T> {
-    const spec = InProcessRetryRunner.normalizePolicy(policy);
+  async run<T>(
+    policy: RetryPolicySpec | undefined,
+    work: () => Promise<T>,
+    shouldRetry?: (error: unknown) => boolean,
+    warn?: (message: string) => void,
+  ): Promise<T> {
+    const spec = InProcessRetryRunner.normalizePolicy(policy, warn);
     let lastError: unknown;
     for (let attempt = 1; attempt <= spec.maxAttempts; attempt++) {
       try {
@@ -33,6 +41,9 @@ export class InProcessRetryRunner {
         if (attempt >= spec.maxAttempts) {
           break;
         }
+        if (shouldRetry !== undefined && !shouldRetry(error)) {
+          break;
+        }
         const delayMs = InProcessRetryRunner.delayAfterFailureMs(spec, attempt);
         await this.sleeper.sleep(delayMs);
       }
@@ -58,7 +69,10 @@ export class InProcessRetryRunner {
     return Math.max(0, Math.floor(ms));
   }
 
-  private static normalizePolicy(policy: RetryPolicySpec | undefined): NormalizedPolicy {
+  private static normalizePolicy(
+    policy: RetryPolicySpec | undefined,
+    warn?: (message: string) => void,
+  ): NormalizedPolicy {
     if (policy === undefined) {
       return { kind: "none", maxAttempts: 1 };
     }
@@ -71,15 +85,17 @@ export class InProcessRetryRunner {
     }
     if (kind === "fixed") {
       const p = policy as FixedRetryPolicySpec;
-      const maxAttempts = InProcessRetryRunner.assertPositiveInt(p.maxAttempts, "fixed.maxAttempts");
+      const raw = InProcessRetryRunner.assertPositiveInt(p.maxAttempts, "fixed.maxAttempts");
+      const maxAttempts = InProcessRetryRunner.clampMaxAttempts(raw, warn);
       const delayMs = InProcessRetryRunner.assertNonNegativeFinite(p.delayMs, "fixed.delayMs");
       return { kind: "fixed", maxAttempts, delayMs };
     }
     if (kind === "exponential") {
       const p = policy as ExponentialRetryPolicySpec;
+      const raw = InProcessRetryRunner.assertPositiveInt(p.maxAttempts, "exponential.maxAttempts");
       return {
         kind: "exponential",
-        maxAttempts: InProcessRetryRunner.assertPositiveInt(p.maxAttempts, "exponential.maxAttempts"),
+        maxAttempts: InProcessRetryRunner.clampMaxAttempts(raw, warn),
         initialDelayMs: InProcessRetryRunner.assertNonNegativeFinite(p.initialDelayMs, "exponential.initialDelayMs"),
         multiplier: InProcessRetryRunner.assertMultiplier(p.multiplier),
         maxDelayMs:
@@ -92,6 +108,16 @@ export class InProcessRetryRunner {
     return { kind: "none", maxAttempts: 1 };
   }
 
+  private static clampMaxAttempts(requested: number, warn?: (message: string) => void): number {
+    if (requested > HARD_MAX_RETRY_ATTEMPTS) {
+      warn?.(
+        `Retry policy maxAttempts (${requested}) exceeds hard ceiling (${HARD_MAX_RETRY_ATTEMPTS}); clamping to ${HARD_MAX_RETRY_ATTEMPTS}.`,
+      );
+      return HARD_MAX_RETRY_ATTEMPTS;
+    }
+    return requested;
+  }
+
   private static assertPositiveInt(value: unknown, label: string): number {
     if (typeof value !== "number" || !Number.isFinite(value) || value < 1 || !Number.isInteger(value)) {
       throw new Error(`Retry policy ${label} must be a positive integer`);

package/src/execution/NodeExecutor.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { isPortsEmission, isUnbrandedPortsEmissionShape } from "../contracts/emitPorts";
+import { CredentialUnboundError } from "../contracts/credentialTypes";
 
 import type {
   Item,
@@ -38,14 +39,33 @@ export class NodeExecutor {
   }
 
   async execute(request: NodeActivationRequest): Promise<NodeOutputs> {
+    await this.assertRequiredCredentialsBound(request);
     const policy = request.ctx.config.retryPolicy;
-    return await this.retryRunner.run(policy, async () => {
-      const nodeInstance = this.nodeInstanceFactory.createByType(request.ctx.config.type);
-      if (request.kind === "multi") {
-        return await this.executeMultiInputActivation(request, nodeInstance);
-      }
-      return await this.executeSingleInputNode(request, nodeInstance);
-    });
+    return await this.retryRunner.run(
+      policy,
+      async () => {
+        const nodeInstance = this.nodeInstanceFactory.createByType(request.ctx.config.type);
+        if (request.kind === "multi") {
+          return await this.executeMultiInputActivation(request, nodeInstance);
+        }
+        return await this.executeSingleInputNode(request, nodeInstance);
+      },
+      (error) => !this.isCredentialError(error),
+    );
+  }
+
+  private async assertRequiredCredentialsBound(request: NodeActivationRequest): Promise<void> {
+    if (!request.ctx.getCredential) return;
+    for (const req of request.ctx.config.getCredentialRequirements?.() ?? []) {
+      if (req.optional) continue;
+      await request.ctx.getCredential(req.slotKey);
+    }
+  }
+
+  private isCredentialError(e: unknown): boolean {
+    if (e instanceof CredentialUnboundError) return true;
+    const cause = e instanceof Error ? (e as { cause?: unknown }).cause : undefined;
+    return cause instanceof CredentialUnboundError;
   }
 
   private async executeMultiInputActivation(

package/src/execution/NodeRunStateWriter.ts

@@ -156,6 +156,8 @@ export class NodeRunStateWriter implements NodeExecutionStatePublisher {
         status: args.status,
         managedInput: args.managedInput,
         managedOutput: args.managedOutput,
+        statusLabel: args.statusLabel,
+        subjectName: args.subjectName,
         error: args.error,
         queuedAt: args.queuedAt,
         startedAt: args.startedAt,

package/src/index.ts

@@ -6,6 +6,7 @@ export type {
   AgentConnectionCredentialSource,
   AgentConnectionNodeDescriptor,
   AgentConnectionNodeRole,
+  McpServerResolver,
 } from "./ai/AgentConnectionNodeCollector";
 export * from "./workflow";
 export * from "./di";
@@ -34,3 +35,12 @@ export type {
   PollingRunCycleResult,
   PollingTriggerStartArgs,
 } from "./triggers/polling";
+export { WorkflowEdgePortValidator } from "./validation/WorkflowEdgePortValidator";
+export type { WorkflowEdgePortError, WorkflowEdgePortValidationResult } from "./validation/WorkflowEdgePortError.types";
+export type {
+  OAuthFlowStartArgs,
+  OAuthFlowStartResult,
+  OAuthFlowCallbackArgs,
+  OAuthMaterial,
+  OAuthFlowExecutor,
+} from "./credentials/OAuthFlowExecutor.types";

package/src/orchestration/RunContinuationService.ts

@@ -161,7 +161,9 @@ export class RunContinuationService {
 
     const completedActivations = (state.engineCounters?.completedNodeActivations ?? 0) + 1;
     const engineCounters = { completedNodeActivations: completedActivations };
-    const maxNodeActivations = state.executionOptions?.maxNodeActivations ?? Number.MAX_SAFE_INTEGER;
+    const maxNodeActivations =
+      state.executionOptions?.maxNodeActivations ??
+      this.executionLimitsPolicy.createRootExecutionOptions().maxNodeActivations!;
 
     if (this.semantics.isStopConditionSatisfied(state.control?.stopCondition, args.nodeId)) {
       const completedState = this.persistedRunStateTerminalBuilder.mergeTerminal({
@@ -566,7 +568,9 @@ export class RunContinuationService {
 
     const completedActivations = (args.state.engineCounters?.completedNodeActivations ?? 0) + 1;
     const engineCounters = { completedNodeActivations: completedActivations };
-    const maxNodeActivations = args.state.executionOptions?.maxNodeActivations ?? Number.MAX_SAFE_INTEGER;
+    const maxNodeActivations =
+      args.state.executionOptions?.maxNodeActivations ??
+      this.executionLimitsPolicy.createRootExecutionOptions().maxNodeActivations!;
 
     if (this.semantics.isStopConditionSatisfied(args.state.control?.stopCondition, args.args.nodeId)) {
       const completedState = this.persistedRunStateTerminalBuilder.mergeTerminal({

package/src/runStorage/InMemoryBinaryStorageRegistry.ts

@@ -47,6 +47,16 @@ export class InMemoryBinaryStorage implements BinaryStorage {
   async delete(storageKey: string): Promise<void> {
     this.values.delete(storageKey);
   }
+
+  async deleteMany(storageKeys: ReadonlyArray<string>): Promise<void> {
+    for (const key of storageKeys) {
+      this.values.delete(key);
+    }
+  }
+
+  async listByPrefix(prefix: string): Promise<ReadonlyArray<string>> {
+    return Array.from(this.values.keys()).filter((key) => key.startsWith(prefix));
+  }
 }
 
 export { BinaryBodyBufferReader } from "./BinaryBodyBufferReader";