elasticdash-sdk 0.2.6 → 0.2.7-beta-2

package/docs/agent-integration-guide.md

@@ -49,16 +49,19 @@ Add to `.gitignore`:
 .ed_traces/
 ```
 
+> **Do not stop here — Step 1 is not a complete integration.** Without Steps 2–4, no tool calls are wrapped and no traces are produced. Continue to Step 2 before reporting "done" to the user.
+
 ---
 
 ## Step 2: Create `ed_tools.ts`
 
-Create `ed_tools.ts` in the project root. This file wraps each tool function with `wrapTool()` for automatic tracing, mocking, and telemetry.
+Create `ed_tools.ts` in the project root. This file wraps each tool function with `edTool()` for automatic tracing, mocking, telemetry, and CLI/MCP rerun discovery. (`edTool` is `wrapTool` + global registry registration — prefer it as the default. Drop down to `wrapTool` only for inline closures that should NOT be discoverable by name.)
 
 ### Template
 
 ```ts
 // ed_tools.ts
+import { createRequire } from 'node:module'
 import { setElasticDashModule } from './ed_workflows'
 
 // Import original tool implementations from the actual source files
@@ -70,29 +73,39 @@ import { originalTool2 } from './utils/YOUR_SOURCE_2'
 // ---------------------------------------------------------------------------
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-type WrapToolFn = <T extends (...args: any[]) => any>(name: string, fn: T) => T
+type EdToolFn = <T extends (...args: any[]) => any>(name: string, fn: T) => T
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-let wrapTool: WrapToolFn = (_name: string, fn: any) => fn
+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')
-  wrapTool = _edModule.wrapTool ?? wrapTool
+  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)
 }
 
 // ---------------------------------------------------------------------------
 // Wrapped tools — one export per tool
 // ---------------------------------------------------------------------------
 
-export const myTool1 = wrapTool('myTool1', async (input: any) => {
+export const myTool1 = edTool('myTool1', async (input: any) => {
   return await originalTool1(input)
 })
 
-export const myTool2 = wrapTool('myTool2', async (input: any) => {
+export const myTool2 = edTool('myTool2', async (input: any) => {
   const { someField } = input as { someField: string }
   return await originalTool2(someField)
 })
@@ -100,14 +113,14 @@ export const myTool2 = wrapTool('myTool2', async (input: any) => {
 
 ### Key patterns
 
-- **`wrapTool(name, fn)`** wraps the function with automatic tracing, mocking, and telemetry. 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.
-- **`setElasticDashModule`** shares the loaded module with `ed_workflows.ts` so `edStartTrace`/`edEndTrace` use the same tracing context as `wrapTool`.
+- **`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.
+- **`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.
 
 ### Important rules
 
-- The string name passed to `wrapTool()` **must match** the exported function name exactly.
+- The string name passed to `edTool()` (or `wrapTool()`) **must match** the exported function name exactly.
 - Each tool function must accept a single input object and return a plain value (JSON-serializable).
 - Tool functions must not close over HTTP context, framework state, or database clients — extract pure logic first.
 
@@ -139,17 +152,56 @@ 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
+// `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 {
   _ed = mod
 }
 
+/**
+ * Initialise observability through the SHARED SDK module instance.
+ * Call this once at process startup (e.g. from main.ts or your server
+ * entry point) BEFORE any workflow runs. If env vars are set this is
+ * also called lazily from edStartTrace, so this explicit form is for
+ * projects that want predictable, fail-fast init.
+ */
+export function edInitObservability(opts?: { serverUrl?: string; apiKey?: string }): void {
+  if (!_ed || _obsInitialised) return
+  const serverUrl = opts?.serverUrl
+    ?? process.env.ELASTICDASH_API_URL
+    ?? process.env.ELASTICDASH_SERVER_URL
+    ?? process.env.ELASTICDASH_SERVER
+  const apiKey = opts?.apiKey ?? process.env.ELASTICDASH_API_KEY
+  if (!serverUrl || !apiKey) return
+  try {
+    _ed.initObservability({ serverUrl, apiKey })
+    _obsInitialised = true
+  } catch (err) {
+    console.error('[ed_workflows] edInitObservability error:', err)
+  }
+}
+
 export const edStartTrace = async (workflowName: string): Promise<void> => {
   if (!_ed) return
   try {
+    // Lazy init from env vars on first trace — keeps the simple case
+    // ("set ELASTICDASH_API_URL + ELASTICDASH_API_KEY, just run") working
+    // without an explicit init call.
+    if (!_obsInitialised) edInitObservability()
     await _ed.tryAutoInitHttpContext()
     _ed.startTrace(workflowName)
   } catch (err) {
@@ -165,8 +217,32 @@ export const edEndTrace = (): void => {
     console.error('[ed_workflows] edEndTrace error:', err)
   }
 }
+
+/**
+ * Flush remaining trace events and close the backend connection.
+ * Call from a `finally` block at the end of your process lifecycle
+ * (CLI: in main() finally; HTTP server: rarely needed — the SDK
+ * auto-registers SIGTERM/SIGINT handlers that call this).
+ *
+ * The SDK's auto-exit hooks (registered by initObservability) are
+ * async; for short-lived CLI scripts the process can terminate BEFORE
+ * those hooks complete and drop the final event batch. Explicit
+ * shutdown via this helper is the only guarantee that the last batch
+ * lands.
+ */
+export const edShutdownObservability = async (): Promise<void> => {
+  if (!_ed || !_obsInitialised) return
+  try {
+    await _ed.shutdownObservability()
+    _obsInitialised = false
+  } catch (err) {
+    console.error('[ed_workflows] edShutdownObservability error:', err)
+  }
+}
 ```
 
+> **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
 
 For non-framework projects where the workflow can be imported directly:
@@ -221,7 +297,7 @@ export const YOUR_WORKFLOW = async (input: {
 ```
 ed_tools.ts
   ├── imports original functions from services/utils
-  ├── wraps each with wrapTool() for tracing
+  ├── wraps each with edTool() for tracing + rerun registration
   └── exports wrapped versions with the SAME or similar names
 
 ed_workflows.ts
@@ -239,6 +315,32 @@ Existing source files (MODIFIED):
 
 ### What to do
 
+**0. Add `edInitObservability` to your entry point.**
+
+Call `edInitObservability` once at process startup so observability is wired up through the SAME SDK module instance that `ed_tools.ts` and `ed_workflows.ts` share. Do this BEFORE any workflow runs. Skipping this is the #1 cause of `[elasticdash] startTrace: observability not initialised` errors at runtime.
+
+For a CLI / standalone Node script — init at the top, shutdown in a `finally` block:
+
+```ts
+// src/main.ts
+import 'dotenv/config'
+import { edInitObservability, edShutdownObservability } from '../ed_workflows.js'
+import { researchManager } from './manager.js'
+
+async function main() {
+  edInitObservability()           // env vars: ELASTICDASH_API_URL + ELASTICDASH_API_KEY
+  try {
+    // ... rest of your main() ...
+  } finally {
+    await edShutdownObservability()   // guarantees the final batch lands
+  }
+}
+```
+
+The `finally + edShutdownObservability` block is **required for CLIs**. The SDK auto-registers `beforeExit`/`SIGTERM`/`SIGINT` handlers, but those are async; for short-lived scripts the process can tear down before they complete, dropping the final batch.
+
+For Next.js / Remix / SvelteKit / Express, call `edInitObservability()` in your framework's instrumentation hook OR at the very top of your server entry file before any route handler is registered. Explicit shutdown is rarely needed — the server stays up; the auto-registered SIGTERM handler covers graceful restarts. Do NOT replace `edInitObservability` with `import { initObservability } from 'elasticdash-sdk'` — that hits a different module instance and the error returns. See Step 3's "Why route init through `_ed`?" callout.
+
 **1. Find every file that calls a tool function and update its imports:**
 
 For each tool exported from `ed_tools.ts`, search the codebase for files that import the original function. Update the import to come from `ed_tools` instead.
@@ -433,6 +535,46 @@ This confirms:
 
 **If it fails:** Check that `.env` has valid `ELASTICDASH_API_URL` and `ELASTICDASH_API_KEY` values. If the API key is rejected, the user needs to get a new one from https://app.elasticdash.com.
 
+### Verifying programmatic init from the integrated app
+
+`npx elasticdash observe` is the *CLI* path — it runs `initObservability` in its own process. The actual integrated app (via `edInitObservability` in `ed_workflows.ts`) also calls `initObservability` programmatically, opens the same socket, installs the same AI interceptor, and pushes events on the same batcher. **You do not need `npx elasticdash observe` running for the integrated app to produce traces.**
+
+To verify the programmatic path is working, set `ELASTICDASH_DEBUG=1` in the user's `.env` and run the user's app once. You should see these lines on stderr on the first trace:
+
+```
+[elasticdash] Observability initialised — sessionId=<uuid> workflow=<name> server=<url>
+[elasticdash] Socket connected: <socket-id>
+[elasticdash] startTrace: <workflow-name>, capture=false
+[elasticdash] Flushed N events (status 200)
+```
+
+If you see NONE of them, init is not running. The most common causes are the dual-module-instance trap (someone imported `initObservability` directly instead of using `edInitObservability`), missing env vars, or `ed_tools.ts` was never imported by the running code path (so `setElasticDashModule` was never called and `_ed` is null — `edStartTrace` / `edInitObservability` silently return).
+
+If you see the first three lines but not the "Flushed" line, the final batch is being dropped on exit — confirm that the entry point calls `edShutdownObservability()` in a `finally` block.
+
+### Where to view the traces
+
+Once `[elasticdash] Flushed N events` appears on stderr, the events are live on the backend. Two ways to view them:
+
+1. **Cloud dashboard** — open `https://app.elasticdash.com`, sign in with the project the API key belongs to, and the run shows up in the traces list. This is the simplest path for users who already have a cloud project.
+2. **Local dashboard** — run `npx elasticdash dashboard` (opens `http://localhost:4573` and proxies the same backend). Useful for debugging since it lets the agent rerun individual workflow steps with mocked tools, browse the captured tool/AI events, and edit prompts in place. See [Workflows Dashboard](dashboard.md) for the full feature set.
+
+For framework projects (Next.js / Remix / etc.), the dashboard can also **trigger workflow runs directly against the running dev server** via HTTP-mode reruns — see [HTTP Workflow Mode](../README.md#http-workflow-mode) in the README. Confirm by running `npm run dev` in the user's project, then `npx elasticdash dashboard` in a second terminal, and triggering a rerun from the dashboard UI.
+
+**End-to-end flow recap** for the agent reporting "done" to the user:
+
+```
+1. npm install elasticdash-sdk             ← Step 1
+2. ed_tools.ts wraps tool functions        ← Step 2
+3. ed_workflows.ts has init/start/end/shutdown helpers + workflow exports   ← Step 3
+4. Entry point calls edInitObservability() then runs the workflow, finally edShutdownObservability()   ← Step 4
+5. .env has ELASTICDASH_API_URL + ELASTICDASH_API_KEY   ← Step 6
+6. User runs their app   →   sees [elasticdash] ... logs on stderr   ← this section
+7. User opens https://app.elasticdash.com or `npx elasticdash dashboard`   →   sees the trace
+```
+
+Only after step 7 has been confirmed is the integration end-to-end. If step 7 fails (logs say "Flushed" but trace doesn't appear), the most likely cause is the API key belongs to a different project than the one the user is viewing — check the project picker in the dashboard.
+
 After validation, stop the observe process (Ctrl+C) and inform the user that ElasticDash is integrated. Provide these commands for ongoing use:
 
 ```bash

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.6",
+  "version": "0.2.7-beta-2",
   "description": "AI-native SDK for ElasticDash workflow testing, tracing, and observability",
   "type": "module",
   "bin": {

package/src/dashboard-server.ts

@@ -453,6 +453,11 @@ function runWorkflowInSubprocess(
   },
 ): Promise<WorkflowSubprocessResult> {
   return new Promise((resolve) => {
+    const startMs = Date.now()
+    const elapsed = () => Date.now() - startMs
+    const debug = (...a: unknown[]) => {
+      if (process.env.ELASTICDASH_DEBUG === '1') console.error(...a)
+    }
     const workerScript = new URL('./workflow-runner-worker.js', import.meta.url).pathname
     const projectDir = path.dirname(workflowsModulePath)
     const denoProject = isDenoProject(projectDir)
@@ -472,15 +477,52 @@ function runWorkflowInSubprocess(
       cwd: projectDir,
       stdio: ['pipe', 'pipe', 'pipe', 'pipe'],
     })
+    const pid = child.pid ?? -1
+    debug(`[elasticdash dashboard] workflow subprocess stage=spawned pid=${pid} elapsedMs=${elapsed()} workflow=${workflowName}`)
+
+    // Heartbeat — workflows can be long; without this the dashboard is blind.
+    // 0 disables. Default 5s.
+    const heartbeatMs = Number(process.env.ELASTICDASH_HEARTBEAT_MS ?? 5000)
+    const heartbeat = heartbeatMs > 0
+      ? setInterval(() => {
+          debug(`[elasticdash dashboard] workflow subprocess heartbeat pid=${pid} elapsedMs=${elapsed()} workflow=${workflowName}`)
+        }, heartbeatMs)
+      : null
+
+    // Optional kill switch. Default unset = no timeout (preserves prior behavior).
+    let timedOut = false
+    const timeoutMs = Number(process.env.ELASTICDASH_WORKFLOW_TIMEOUT_MS ?? 0)
+    const timeout = timeoutMs > 0
+      ? setTimeout(() => {
+          timedOut = true
+          debug(`[elasticdash dashboard] workflow subprocess TIMEOUT pid=${pid} after ${timeoutMs}ms — sending SIGTERM`)
+          try { child.kill('SIGTERM') } catch { /* already dead */ }
+          setTimeout(() => {
+            try { child.kill('SIGKILL') } catch { /* already dead */ }
+          }, 2000)
+        }, timeoutMs)
+      : null
+
+    const cleanup = () => {
+      if (heartbeat) clearInterval(heartbeat)
+      if (timeout) clearTimeout(timeout)
+    }
 
     let fd3Data = ''
     let stderr = ''
+    let sawFd3 = false
+    let sawStdout = false
+    let sawStderr = false
 
     // Line-buffer stdout so that large result JSON lines split across multiple
     // data events are reassembled before processing.
     const WORKFLOW_RESULT_PREFIX = '__ELASTICDASH_RESULT__:'
     let stdoutBuf = ''
     child.stdout.on('data', (chunk) => {
+      if (!sawStdout) {
+        sawStdout = true
+        debug(`[elasticdash dashboard] workflow subprocess stage=first-stdout pid=${pid} elapsedMs=${elapsed()}`)
+      }
       stdoutBuf += chunk.toString()
       const lines = stdoutBuf.split('\n')
       stdoutBuf = lines.pop() ?? '' // keep last (possibly incomplete) line
@@ -494,15 +536,27 @@ function runWorkflowInSubprocess(
       }
     })
     child.stderr.on('data', (chunk) => {
+      if (!sawStderr) {
+        sawStderr = true
+        debug(`[elasticdash dashboard] workflow subprocess stage=first-stderr pid=${pid} elapsedMs=${elapsed()}`)
+      }
       stderr += chunk.toString()
       process.stderr.write(chunk)
     })
     const fd3 = child.stdio[3] as import('stream').Readable | null
     fd3?.on('data', (chunk: Buffer | string) => {
+      if (!sawFd3) {
+        sawFd3 = true
+        debug(`[elasticdash dashboard] workflow subprocess stage=first-fd3 pid=${pid} elapsedMs=${elapsed()}`)
+      }
       fd3Data += chunk.toString()
     })
 
-    child.on('close', () => {
+    child.on('close', (code, signal) => {
+      cleanup()
+      const elapsedMs = elapsed()
+      debug(`[elasticdash dashboard] workflow subprocess stage=closed pid=${pid} code=${code} signal=${signal ?? 'none'} elapsedMs=${elapsedMs} stderrBytes=${stderr.length} fd3Bytes=${fd3Data.length}`)
+
       // Flush any remaining buffered stdout line (e.g. result with no trailing newline)
       if (stdoutBuf.startsWith(WORKFLOW_RESULT_PREFIX)) {
         fd3Data += stdoutBuf.slice(WORKFLOW_RESULT_PREFIX.length)
@@ -514,12 +568,25 @@ function runWorkflowInSubprocess(
         try {
           resolve(JSON.parse(fd3Data))
           return
-        } catch { /* fall through */ }
+        } catch (parseErr) {
+          const detail = `[exit=${code} signal=${signal ?? 'none'} elapsedMs=${elapsedMs} pid=${pid}] fd3 payload failed to parse: ${(parseErr as Error).message}`
+          resolve({ ok: false, error: detail })
+          return
+        }
       }
-      resolve({ ok: false, error: stderr.trim() || 'Workflow subprocess produced no output.' })
+      const stderrExcerpt = stderr.length > 1024 ? `…${stderr.slice(-1024)}` : stderr
+      const detail = `[exit=${code} signal=${signal ?? 'none'} elapsedMs=${elapsedMs} pid=${pid} stderrBytes=${stderr.length}]`
+      const baseError = timedOut
+        ? `Workflow subprocess timed out after ${timeoutMs}ms`
+        : (stderr.trim() || 'Workflow subprocess produced no output.')
+      const errorMsg = stderr.trim()
+        ? `${baseError} ${detail}`
+        : `${baseError} ${detail}${stderrExcerpt ? `\nLast stderr: ${stderrExcerpt}` : ''}`
+      resolve({ ok: false, error: errorMsg })
     })
 
     child.on('error', (err) => {
+      cleanup()
       const hint = denoProject && (err as NodeJS.ErrnoException).code === 'ENOENT'
         ? ' (Deno project detected — ensure "deno" is installed and available in PATH)'
         : ''
@@ -544,6 +611,7 @@ function runWorkflowInSubprocess(
     })
     child.stdin.write(payload)
     child.stdin.end() // Always close stdin to avoid subprocess hang
+    debug(`[elasticdash dashboard] workflow subprocess stage=payload-written pid=${pid} elapsedMs=${elapsed()} payloadBytes=${payload.length}`)
   })
 }
 

package/src/execution/tool-runner.ts

@@ -118,6 +118,7 @@ export function runToolInSubprocess(
   return new Promise((resolve) => {
     debugLog('[elasticdash portal] Spawning tool subprocess', { toolsModulePath, toolName, args, frozenEventsCount: frozenEvents?.length ?? 0 })
     const startMs = Date.now()
+    const elapsed = () => Date.now() - startMs
     const workerScript = resolveWorkerScript('../tool-runner-worker.js')
     const projectDir = path.dirname(toolsModulePath)
     const denoProject = isDenoProject(projectDir)
@@ -136,15 +137,50 @@ export function runToolInSubprocess(
       cwd: projectDir,
       stdio: ['pipe', 'pipe', 'pipe'],
     })
+    const pid = child.pid ?? -1
+    debugLog(`[elasticdash portal] tool subprocess stage=spawned pid=${pid} elapsedMs=${elapsed()} tool=${toolName}`)
+
+    // Heartbeat: prove the parent is still waiting on a live child. 0 disables.
+    const heartbeatMs = Number(process.env.ELASTICDASH_HEARTBEAT_MS ?? 5000)
+    const heartbeat = heartbeatMs > 0
+      ? setInterval(() => {
+          debugLog(`[elasticdash portal] tool subprocess heartbeat pid=${pid} elapsedMs=${elapsed()} tool=${toolName}`)
+        }, heartbeatMs)
+      : null
+
+    // Optional kill switch. Default unset = no timeout (preserves prior behavior).
+    let timedOut = false
+    const timeoutMs = Number(process.env.ELASTICDASH_TOOL_TIMEOUT_MS ?? 0)
+    const timeout = timeoutMs > 0
+      ? setTimeout(() => {
+          timedOut = true
+          debugLog(`[elasticdash portal] tool subprocess TIMEOUT pid=${pid} after ${timeoutMs}ms — sending SIGTERM`)
+          try { child.kill('SIGTERM') } catch { /* already dead */ }
+          setTimeout(() => {
+            try { child.kill('SIGKILL') } catch { /* already dead */ }
+          }, 2000)
+        }, timeoutMs)
+      : null
+
+    const cleanup = () => {
+      if (heartbeat) clearInterval(heartbeat)
+      if (timeout) clearTimeout(timeout)
+    }
 
     const RESULT_PREFIX = '__ELASTICDASH_RESULT__:'
     let resultLine = ''
     let stderr = ''
+    let sawStdout = false
+    let sawStderr = false
 
     // Line-buffer stdout so that large result JSON lines split across multiple
     // data events are reassembled before processing.
     let stdoutBuf = ''
     child.stdout.on('data', (chunk: Buffer) => {
+      if (!sawStdout) {
+        sawStdout = true
+        debugLog(`[elasticdash portal] tool subprocess stage=first-stdout pid=${pid} elapsedMs=${elapsed()}`)
+      }
       stdoutBuf += chunk.toString()
       const lines = stdoutBuf.split('\n')
       stdoutBuf = lines.pop() ?? '' // keep last (possibly incomplete) line
@@ -157,12 +193,18 @@ export function runToolInSubprocess(
       }
     })
     child.stderr.on('data', (chunk: Buffer) => {
+      if (!sawStderr) {
+        sawStderr = true
+        debugLog(`[elasticdash portal] tool subprocess stage=first-stderr pid=${pid} elapsedMs=${elapsed()}`)
+      }
       stderr += chunk.toString()
       process.stderr.write(chunk)
     })
 
-    child.on('close', () => {
-      const currentDurationMs = Date.now() - startMs
+    child.on('close', (code, signal) => {
+      cleanup()
+      const currentDurationMs = elapsed()
+      debugLog(`[elasticdash portal] tool subprocess stage=closed pid=${pid} code=${code} signal=${signal ?? 'none'} elapsedMs=${currentDurationMs} stderrBytes=${stderr.length}`)
 
       // Flush any remaining buffered stdout line (e.g. result with no trailing newline)
       if (stdoutBuf.startsWith(RESULT_PREFIX)) {
@@ -175,17 +217,31 @@ export function runToolInSubprocess(
         try {
           resolve({ ...JSON.parse(resultLine), currentDurationMs })
           return
-        } catch { /* fall through */ }
+        } catch (parseErr) {
+          const detail = `[exit=${code} signal=${signal ?? 'none'} elapsedMs=${currentDurationMs} pid=${pid}] resultLine failed to parse: ${(parseErr as Error).message}`
+          resolve({ ok: false, error: detail, currentDurationMs })
+          return
+        }
       }
-      resolve({ ok: false, error: stderr.trim() || 'Tool subprocess produced no output.', currentDurationMs })
+
+      const stderrExcerpt = stderr.length > 1024 ? `…${stderr.slice(-1024)}` : stderr
+      const detail = `[exit=${code} signal=${signal ?? 'none'} elapsedMs=${currentDurationMs} pid=${pid} stderrBytes=${stderr.length}]`
+      const baseError = timedOut
+        ? `Tool subprocess timed out after ${timeoutMs}ms`
+        : (stderr.trim() || 'Tool subprocess produced no output.')
+      const errorMsg = stderr.trim()
+        ? `${baseError} ${detail}`
+        : `${baseError} ${detail}${stderrExcerpt ? `\nLast stderr: ${stderrExcerpt}` : ''}`
+      resolve({ ok: false, error: errorMsg, currentDurationMs })
     })
 
     child.on('error', (err) => {
+      cleanup()
       const hint = denoProject && (err as NodeJS.ErrnoException).code === 'ENOENT'
         ? ' (Deno project detected — ensure "deno" is installed and available in PATH)'
         : ''
       debugLog(`[elasticdash portal] Failed to spawn tool subprocess: ${err.message}${hint}`)
-      resolve({ ok: false, error: `Failed to spawn tool subprocess: ${err.message}${hint}`, currentDurationMs: Date.now() - startMs })
+      resolve({ ok: false, error: `Failed to spawn tool subprocess: ${err.message}${hint}`, currentDurationMs: elapsed() })
     })
 
     const payload = JSON.stringify({
@@ -196,6 +252,7 @@ export function runToolInSubprocess(
     })
     child.stdin.write(payload)
     child.stdin.end()
+    debugLog(`[elasticdash portal] tool subprocess stage=payload-written pid=${pid} elapsedMs=${elapsed()} payloadBytes=${payload.length}`)
   })
 }