type contracts + impl plan created

Author: Shanyu-Dabbiru

apps/sim/lib/mcp/resilience/README.md

@@ -0,0 +1,57 @@
+# Goal Description
+Implement a "Day 2" reliability layer for the simstudioai/sim workflow engine by building a composable Resilience Interceptor/Middleware Pipeline for the MCP `executeTool` logic. This pipeline ensures enterprise-grade stability by introducing a Circuit Breaker State Machine, Zod-based Schema Enforcement for LLM outputs, and detailed Telemetry for latency and failure analysis, while addressing high-concurrency Node/TS environments.
+
+## User Review Required
+- Please confirm if `apps/sim/lib/mcp/service.ts` is the correct core injection point for wrapping `executeTool`.
+- Note on file path: `apps/sim/lib/workflow/executor.ts` was not found. Instead, `apps/sim/executor/execution/executor.ts` and `apps/sim/tools/workflow/executor.ts` were analyzed. Ensure intercepting `McpService`'s `executeTool` serves your architectural needs.
+- Please confirm the schema enforcement approach: we will compile and cache JSON Schemas to Zod validators upon MCP server discovery or lazily, instead of parsing dynamically per request.
+
+## Proposed Changes
+
+We will split the implementation into discrete PRs / Commits to maintain structure.
+
+### Part 1: Telemetry Hooks
+Implement the foundation for tracking.
+*(Change Rationale: Transitioning to a middleware pattern instead of a monolithic proxy, allowing telemetry to be composed easily).*
+#### [NEW] `apps/sim/lib/mcp/resilience/telemetry.ts`
+- Implement telemetry middleware hook to capture `latency_ms` and `failure_reason` (e.g., `TIMEOUT`, `VALIDATION_ERROR`, `API_500`).
+
+### Part 2: Circuit Breaker State Machine
+Implement the state management logic.
+*(Change Rationale: Added a HALF-OPEN concurrency lock (semaphore) to prevent the "thundering herd" issue on the downstream server. Documented that this operates on local, per-instance state using an LRU cache to prevent memory leaks).*
+#### [NEW] `apps/sim/lib/mcp/resilience/circuit-breaker.ts`
+- Implement the `CircuitBreaker` middleware with states: `CLOSED`, `OPEN`, and `HALF-OPEN`.
+- Handle failure thresholds, reset timeouts, and logic for failing fast.
+- **Concurrency Lock:** During `HALF-OPEN`, strictly gate the transition so only **one** probe request is allowed through. All other concurrent requests will fail-fast until the probe resolves.
+- **Memory & State:** Use an LRU cache or scoped ties for the CircuitBreaker registry, binding the lifecycle of the breaker explicitly to the lifecycle of the MCP connection to prevent memory leaks. Also, this operates on local, per-instance state.
+
+### Part 3: Schema Validation
+Implement the Zod validation logic for LLM arguments.
+*(Change Rationale: Added schema compilation caching to avoid severe CPU bottlenecking per request, and returning `isError: true` on validation failures to natively trigger LLM self-correction).*
+#### [NEW] `apps/sim/lib/mcp/resilience/schema-validator.ts`
+- Logic to enforce schemas using `Zod` as a middleware.
+- **Schema Caching:** Compile JSON Schemas to Zod schemas and cache them in a registry mapped to `toolId` during the initial discovery phase or lazily on first compile. Flush cached validators dynamically when listening for MCP lifecycle events (e.g., mid-session tool list updates).
+- **LLM Self-Correction:** Instead of throwing exceptions that crash the workflow engine when Zod validation fails, intercept validation errors and return a gracefully formatted MCP execution result: `{ isError: true, content: [{ type: "text", text: "Schema validation failed: [Zod Error Details]" }] }`.
+
+### Part 4: Resilience Pipeline Integration
+Wrap up the tools via a Pipeline instead of a monolithic proxy.
+*(Change Rationale: Switched from a God Object Proxy to a Middleware Pipeline to support granular, per-tool enablement).*
+#### [NEW] `apps/sim/lib/mcp/resilience/pipeline.ts`
+- Implement a chain of responsibility (interceptor/middleware pipeline) for `executeTool`.
+- Provide an API like `executeTool.use(telemetry).use(validate(cachedSchema)).use(circuitBreaker(config))` rather than a sequential sequence inside a rigid class.
+- This composable architecture allows enabling or disabling specific middlewares dynamically per tool (e.g., un-trusted vs internal tools).
+
+#### [MODIFY] `apps/sim/lib/mcp/service.ts`
+- Update `mcpService.executeTool` to run requests through the configurable `ResiliencePipeline`, rather than hardcoded proxy logic.
+
+## Verification Plan
+### Automated Tests
+- Create a mock MCP server execution test suite.
+- Write tests in `apps/sim/lib/mcp/resilience/pipeline.test.ts` to assert:
+  - Circuit Breaker trips to `OPEN` on simulated `API_500` and trips to `HALF-OPEN` after a cooldown.
+  - **New Test:** Verify HALF-OPEN strictly allows exactly **one** simulated concurrent probe request through.
+  - **New Test:** Schema validation returns `isError: true` standard format for improper LLM args without triggering execution.
+- Telemetry correctly logs latency.
+
+### Manual Verification
+- Execute tests generating visual output demonstrating the circuit breaker "tripping" and "recovering".

apps/sim/lib/mcp/resilience/types.ts

@@ -0,0 +1,37 @@
+import type { McpToolCall, McpToolResult } from '@/lib/mcp/types'
+
+/**
+ * Context passed through the Resilience Pipeline
+ */
+export interface McpExecutionContext {
+  toolCall: McpToolCall
+  serverId: string
+  userId: string
+  workspaceId: string
+  /**
+   * Additional parameters passed directly by the executeTool caller
+   */
+  extraHeaders?: Record<string, string>
+}
+
+/**
+ * Standardized function signature for invoking the NEXT component in the pipeline
+ */
+export type McpMiddlewareNext = (
+  context: McpExecutionContext
+) => Promise<McpToolResult>
+
+/**
+ * Interface that all Resilience Middlewares must implement
+ */
+export interface McpMiddleware {
+  /**
+   * Execute the middleware logic
+   * @param context The current execution context
+   * @param next The next middleware/tool in the chain
+   */
+  execute(
+    context: McpExecutionContext,
+    next: McpMiddlewareNext
+  ): Promise<McpToolResult>
+}