elasticdash-sdk 0.2.7-beta → 0.2.7-beta-2

package/README.md

@@ -71,7 +71,9 @@ That's it. The agent reads the baked-in guide (which transcludes the same conten
 
 > **Do not shortcut this step.** Without `ed_tools.ts` and `ed_workflows.ts` plus the init call, the SDK does not intercept tool or AI calls — your project will run without errors and produce zero traces. A vague prompt like "install elasticdash-sdk" lets the agent stop at `npm install`; the prompt above is explicit about completing integration.
 
-> **Init must go through `edInitObservability` (the helper inside `ed_workflows.ts`), not `import { initObservability } from 'elasticdash-sdk'` in your entry file.** Both files in the integration share one CJS module instance via `eval('require')`; importing `initObservability` directly hits a *different* ESM instance, leaving `_ed.startTrace` reading from an empty store. The symptom is `[elasticdash] startTrace: observability not initialised` at runtime. The integration guide's Step 3 explains why; the `edInitObservability` helper is the only correct path. For CLI scripts, also call `edShutdownObservability()` from a `finally` block at process exit — the SDK's auto-registered exit hooks are async and short-lived processes can terminate before the final batch flushes.
+> **Init must go through `edInitObservability` (the helper inside `ed_workflows.ts`), not `import { initObservability } from 'elasticdash-sdk'` in your entry file.** Both files in the integration share one CJS module instance via `createRequire(import.meta.url)`; importing `initObservability` directly hits a *different* ESM instance, leaving `_ed.startTrace` reading from an empty store. The symptom is `[elasticdash] startTrace: observability not initialised` at runtime. The integration guide's Step 3 explains why; the `edInitObservability` helper is the only correct path. For CLI scripts, also call `edShutdownObservability()` from a `finally` block at process exit — the SDK's auto-registered exit hooks are async and short-lived processes can terminate before the final batch flushes.
+
+> **Important: do not use `eval('require')` to load the SDK in `ed_tools.ts`.** The `eval('require')(...)` trick that older versions of this guide recommended works only in CJS — in any project with `"type": "module"` in `package.json`, it throws "require is not defined", the catch silently swallows the error, and the entire integration no-ops with zero logs and zero traces. Use `createRequire(import.meta.url)` from `node:module` instead; it works in both ESM and CJS.
 
 **Fallback** — if you don't want to add a file to your repo, you can skip `init-guide` and use this prompt instead, which directs the agent at the docs inside `node_modules/`:
 
@@ -477,21 +479,25 @@ This file loads the SDK, shares the module instance with `ed_workflows.ts`, and
 
 ```ts
 // ed_tools.ts
+import { createRequire } from 'node:module';
 import { setElasticDashModule } from './ed_workflows';
 
-let wrapTool: <T extends (...args: any[]) => any>(name: string, fn: T) => T = (_name, fn) => fn;
+let edTool: <T extends (...args: any[]) => any>(name: string, fn: T) => T = (_name, fn) => fn;
+
+// `createRequire(import.meta.url)` works in BOTH ESM (`"type": "module"`)
+// and CJS projects. Do NOT use `eval('require')` — it silently throws in
+// ESM and the whole integration produces zero traces with zero logs.
+const nodeRequire = createRequire(import.meta.url);
 
 try {
-  // For Next.js / Turbopack: eval('require') bypasses static analysis.
-  // For plain Node.js projects you can use a normal require() or import.
-  const _edModule = (eval('require') as (id: string) => any)('elasticdash-sdk');
-  wrapTool = _edModule.wrapTool ?? wrapTool;
+  const _edModule = nodeRequire('elasticdash-sdk');
+  edTool = _edModule.edTool ?? _edModule.wrapTool ?? edTool;
   setElasticDashModule(_edModule);
-} catch {
-  // elasticdash-sdk not available — tools run without tracing
+} catch (err) {
+  console.error('[ed_tools] failed to load elasticdash-sdk:', err);
 }
 
-export const myTool = wrapTool('myTool', async (input: { query: string }) => {
+export const myTool = edTool('myTool', async (input: { query: string }) => {
   // ... your tool logic
 });
 ```

package/docs/agent-integration-guide.md

@@ -61,6 +61,7 @@ Create `ed_tools.ts` in the project root. This file wraps each tool function wit
 
 ```ts
 // ed_tools.ts
+import { createRequire } from 'node:module'
 import { setElasticDashModule } from './ed_workflows'
 
 // Import original tool implementations from the actual source files
@@ -76,14 +77,24 @@ type EdToolFn = <T extends (...args: any[]) => any>(name: string, fn: T) => T
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 let edTool: EdToolFn = (_name: string, fn: any) => fn
 
+// `createRequire` works in BOTH ESM (`"type": "module"`) and CJS projects —
+// it's the only require shape that survives both. The older `eval('require')`
+// trick silently throws in ESM ("require is not defined"), the catch swallows
+// it, _ed stays null, and every helper in ed_workflows.ts returns silently —
+// you get zero traces and zero error logs. Always use createRequire.
+const nodeRequire = createRequire(import.meta.url)
+
 try {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const _edModule = (eval('require') as (id: string) => any)('elasticdash-sdk')
+  const _edModule = nodeRequire('elasticdash-sdk')
   edTool = _edModule.edTool ?? _edModule.wrapTool ?? edTool
   // Share the module instance with ed_workflows.ts so trace hooks use the same context
   setElasticDashModule(_edModule)
-} catch {
-  // elasticdash-sdk not available — all wrappers pass through to original functions
+} catch (err) {
+  // Surface load failures explicitly — silent failure here is the #1 cause of
+  // "I installed the SDK but no traces appear". Logging the error means a user
+  // running with ELASTICDASH_DEBUG=1 (or any time) sees what went wrong.
+  console.error('[ed_tools] failed to load elasticdash-sdk:', err)
 }
 
 // ---------------------------------------------------------------------------
@@ -103,7 +114,7 @@ export const myTool2 = edTool('myTool2', async (input: any) => {
 ### Key patterns
 
 - **`edTool(name, fn)`** wraps the function with automatic tracing, mocking, telemetry, and global registry registration so the CLI `run-tool <name>` and MCP `run_tool` can rerun it by name. Falls back to a passthrough if `elasticdash-sdk` is not installed.
-- **`eval('require')`** is used instead of `import()` to share the same module instance across `ed_tools.ts` and `ed_workflows.ts`. This avoids ESM/CJS dual-instance issues.
+- **`createRequire(import.meta.url)`** is used instead of static `import()` to share the same module instance across `ed_tools.ts` and `ed_workflows.ts`. This avoids ESM/CJS dual-instance issues. Do not substitute `eval('require')` — that throws "require is not defined" in ESM projects (any project with `"type": "module"` in `package.json`), the catch swallows it, and the entire integration silently no-ops.
 - **`setElasticDashModule`** shares the loaded module with `ed_workflows.ts` so `edStartTrace`/`edEndTrace` use the same tracing context as `edTool`.
 - The exported name (e.g., `myTool1`) can differ from the original function name (e.g., `originalTool1`). The call sites in existing source files will be updated to use the new name in Step 4.
 
@@ -141,9 +152,20 @@ Every `ed_workflows.ts` should export `edStartTrace` and `edEndTrace`. These are
 ```ts
 // ed_workflows.ts — trace hooks (copy as-is)
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-let _ed: any = null
-let _obsInitialised = false
+// `var` (not `let`) is intentional. `ed_tools.ts` imports `setElasticDashModule`
+// from this file and calls it during its own module load. If this module's
+// re-export of YOUR_WORKFLOW (below) sits in a transitive import chain that
+// reaches `ed_tools.ts`, ESM evaluates `ed_tools.ts` BEFORE this module's body
+// runs — and `let _ed = null` would be in TDZ (temporal dead zone) at that
+// moment, throwing `Cannot access '_ed' before initialization` inside
+// setElasticDashModule. `var _ed` hoists with `undefined` so the assignment
+// works during circular import. After this module's body runs, the value set
+// during the circular call is preserved (no re-initialiser overwrites it).
+
+// eslint-disable-next-line no-var, @typescript-eslint/no-explicit-any
+var _ed: any
+// eslint-disable-next-line no-var
+var _obsInitialised: boolean
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function setElasticDashModule(mod: any): void {
@@ -219,7 +241,7 @@ export const edShutdownObservability = async (): Promise<void> => {
 }
 ```
 
-> **Why route init through `_ed` instead of importing `initObservability` directly?** The SDK uses AsyncLocalStorage to correlate events. Both `ed_tools.ts` and `ed_workflows.ts` must share the same SDK module instance — that's why `ed_tools.ts` loads the SDK via `eval('require')` and passes it through `setElasticDashModule`. If `main.ts` does `import { initObservability } from 'elasticdash-sdk'` directly, the ESM-loaded copy is a **different module instance** from the CJS-loaded copy that `_ed` references — init writes to one store, `startTrace` reads from another, and you get `[elasticdash] startTrace: observability not initialised` at runtime. Always init through `edInitObservability` from `ed_workflows.ts`.
+> **Why route init through `_ed` instead of importing `initObservability` directly?** The SDK uses AsyncLocalStorage to correlate events. Both `ed_tools.ts` and `ed_workflows.ts` must share the same SDK module instance — that's why `ed_tools.ts` loads the SDK via `createRequire(import.meta.url)` and passes it through `setElasticDashModule`. If `main.ts` does `import { initObservability } from 'elasticdash-sdk'` directly, the ESM-loaded copy is a **different module instance** from the CJS-loaded copy that `_ed` references — init writes to one store, `startTrace` reads from another, and you get `[elasticdash] startTrace: observability not initialised` at runtime. Always init through `edInitObservability` from `ed_workflows.ts`.
 
 ### Workflow exports — simple case
 

package/docs/partial-mocking.md

@@ -107,16 +107,22 @@ Concurrent requests with different mock configs (or no mocks at all) run in para
 
 #### Next.js + Turbopack note
 
-If Turbopack flags `elasticdash-sdk` as "Module not found" at build time (some configs do this for `serverExternalPackages`), use `eval('require')`:
+If Turbopack flags `elasticdash-sdk` as "Module not found" at build time (some configs do this for `serverExternalPackages`), use `createRequire(import.meta.url)`:
 
 ```ts
+import { createRequire } from 'node:module';
+const nodeRequire = createRequire(import.meta.url);
+
 try {
-  const { applyInboundMockConfig } = (eval('require') as any)('elasticdash-sdk');
+  const { applyInboundMockConfig } = nodeRequire('elasticdash-sdk');
   applyInboundMockConfig(request);
-} catch { /* SDK not installed — proceed live */ }
+} catch (err) {
+  console.error('[mocking] failed to load elasticdash-sdk:', err);
+  /* SDK not installed — proceed live */
+}
 ```
 
-This is the same pattern users already use for `initHttpRunContext` for dashboard mode. The `try/catch` makes the SDK a soft dependency: if it's not present in prod, the route still works.
+This is the same pattern users already use for `initHttpRunContext` for dashboard mode. The `try/catch` makes the SDK a soft dependency: if it's not present in prod, the route still works. **Do not substitute `eval('require')`** — it silently throws in ESM projects (`"type": "module"` in `package.json`) and the catch hides the failure, leaving the route running live in what looks like mock mode.
 
 #### Polymorphic input
 

package/docs/workflow-modes.md

@@ -232,18 +232,17 @@ If `runWithInitializedHttpContext` is called outside `start()` (e.g., in the han
 
 ## Importing the SDK in Next.js / Turbopack
 
-Turbopack statically analyzes `import()` and `require()` calls, which causes `Module not found` errors for `serverExternalPackages`. Use `eval('require')` or `createRequire` to bypass this:
+Turbopack statically analyzes `import()` and `require()` calls, which causes `Module not found` errors for `serverExternalPackages`. Use `createRequire(import.meta.url)` to bypass this:
 
 ```ts
-// Option 1: eval('require') — simple, works everywhere
-const { wrapTool } = (eval('require') as (id: string) => any)('elasticdash-sdk')
-
-// Option 2: createRequire — cleaner, no eval
+// Recommended: createRequire — works in both ESM ("type": "module") and CJS
 import { createRequire } from 'node:module'
-const nodeRequire = createRequire(process.cwd() + '/')
-const { wrapTool } = nodeRequire('elasticdash-sdk')
+const nodeRequire = createRequire(import.meta.url)
+const { edTool } = nodeRequire('elasticdash-sdk')
 ```
 
+> **Do not use `eval('require')`.** It looks simpler but silently throws "require is not defined" in any ESM project — the typical `try/catch` wrapping it swallows the error, the SDK never loads, and the integration produces zero traces with zero logs. Use `createRequire` unconditionally.
+
 Also add the SDK to `serverExternalPackages` in `next.config.js`:
 
 ```js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "elasticdash-sdk",
-  "version": "0.2.7-beta",
+  "version": "0.2.7-beta-2",
   "description": "AI-native SDK for ElasticDash workflow testing, tracing, and observability",
   "type": "module",
   "bin": {