elasticdash-sdk 0.2.6 → 0.2.7-beta

package/docs/agent-integration-guide.md

@@ -49,11 +49,13 @@ 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
 
@@ -70,14 +72,14 @@ 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
 
 try {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const _edModule = (eval('require') as (id: string) => any)('elasticdash-sdk')
-  wrapTool = _edModule.wrapTool ?? wrapTool
+  edTool = _edModule.edTool ?? _edModule.wrapTool ?? edTool
   // Share the module instance with ed_workflows.ts so trace hooks use the same context
   setElasticDashModule(_edModule)
 } catch {
@@ -88,11 +90,11 @@ try {
 // 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 +102,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.
+- **`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.
-- **`setElasticDashModule`** shares the loaded module with `ed_workflows.ts` so `edStartTrace`/`edEndTrace` use the same tracing context as `wrapTool`.
+- **`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.
 
@@ -141,15 +143,43 @@ Every `ed_workflows.ts` should export `edStartTrace` and `edEndTrace`. These are
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 let _ed: any = null
+let _obsInitialised = false
 
 // 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 +195,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 `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`.
+
 ### Workflow exports — simple case
 
 For non-framework projects where the workflow can be imported directly:
@@ -221,7 +275,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 +293,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 +513,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "elasticdash-sdk",
-  "version": "0.2.6",
+  "version": "0.2.7-beta",
   "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}`)
   })
 }
 

package/src/tool-runner-worker.ts

@@ -23,6 +23,13 @@ import { pathToFileURL } from 'node:url'
 
 const RESULT_PREFIX = '__ELASTICDASH_RESULT__:'
 
+const WORKER_START_MS = Date.now()
+function stage(name: string, extra?: Record<string, unknown>): void {
+  if (process.env.ELASTICDASH_DEBUG !== '1') return
+  const tail = extra ? ' ' + Object.entries(extra).map(([k, v]) => `${k}=${typeof v === 'string' ? v : JSON.stringify(v)}`).join(' ') : ''
+  process.stderr.write(`[elasticdash-worker tool] stage=${name} pid=${process.pid} elapsedMs=${Date.now() - WORKER_START_MS}${tail}\n`)
+}
+
 function writeResult(result: unknown): Promise<void> {
   return new Promise((resolve, reject) => {
     process.stdout.write(RESULT_PREFIX + JSON.stringify(result) + '\n', (err) =>
@@ -158,6 +165,7 @@ function installFrozenFetchFallback(frozenEvents: FrozenEvent[]): void {
 }
 
 async function main() {
+  stage('boot')
   const originalExit = process.exit.bind(process)
 
   // Prevent the SDK's tryAutoInitHttpContext from triggering full observability
@@ -175,6 +183,7 @@ async function main() {
   for await (const chunk of process.stdin) {
     raw += chunk
   }
+  stage('stdin-eof', { bytes: raw.length })
 
   let payload: { toolsModulePath: string; toolName: string; args: unknown[]; frozenEvents?: FrozenEvent[] }
   try {
@@ -184,6 +193,7 @@ async function main() {
     originalExit(1)
     return
   }
+  stage('payload-parsed')
 
   const { toolsModulePath, toolName, args, frozenEvents } = payload
 
@@ -193,12 +203,16 @@ async function main() {
   const hasFrozen = frozenEvents && frozenEvents.length > 0
   if (hasFrozen) {
     await setupFrozenContext(frozenEvents)
+    stage('frozen-context-ready', { count: frozenEvents.length })
+  } else {
+    stage('frozen-context-skipped')
   }
 
   try {
     let mod: any
     try {
       mod = await import(pathToFileURL(toolsModulePath).href)
+      stage('tool-module-imported')
     } catch (importErr) {
       const ie = importErr as Error
       await writeResult({ ok: false, error: `Failed to import tool module: ${ie.stack || ie.message}` })
@@ -210,31 +224,37 @@ async function main() {
     // as long as their containing module is reachable from toolsModulePath's
     // import graph. Falls back to ed_tools-style module export lookup.
     let fn: ((...a: unknown[]) => unknown) | undefined
+    let resolvedVia = 'none'
     try {
       const reg = await import('./tool-registry.js')
       const registered = reg.getRegisteredTool(toolName)
-      if (registered) fn = registered.wrapped
+      if (registered) { fn = registered.wrapped; resolvedVia = 'registry' }
     } catch {
       // Registry module not available (older SDK build); fall through to export lookup.
     }
     if (!fn) {
       const exported = mod[toolName]
-      if (typeof exported === 'function') fn = exported
+      if (typeof exported === 'function') { fn = exported; resolvedVia = 'module-export' }
     }
     if (typeof fn !== 'function') {
       await writeResult({ ok: false, error: `"${toolName}" not found via edTool() registry or as an exported function in the module.` })
       originalExit(1)
       return
     }
+    stage('tool-resolved', { tool: toolName, via: resolvedVia })
 
+    stage('tool-call-start', { tool: toolName })
     const currentOutput = await fn(...args)
+    stage('tool-call-end', { tool: toolName })
     await writeResult({ ok: true, currentOutput })
+    stage('result-written')
     originalExit(0)
   } catch (e) {
     const err = e as Error
     const errorMsg = err.stack || err.message || String(e)
     process.stderr.write(`[elasticdash-worker] Tool execution failed:\n${errorMsg}\n`)
     await writeResult({ ok: false, error: errorMsg })
+    stage('result-written', { ok: false })
     originalExit(1)
   } finally {
     if (hasFrozen) restoreFrozenFetch()

package/src/trigger-executor.ts

@@ -101,6 +101,8 @@ export async function executeTrigger(
       const runs: StepRunResult[] = []
 
       for (let i = 0; i < trigger.runCount; i++) {
+        const runStart = Date.now()
+        debugLog(`[elasticdash] Trigger ${trigger.triggerId} step=${stepIndex + 1}/${totalSteps} name=${step.eventName} run=${i + 1}/${trigger.runCount} phase=start`)
         const result = await executePortalTask(
           {
             taskId: `trigger-${trigger.triggerId}-${step.eventName}-${i}`,
@@ -130,7 +132,7 @@ export async function executeTrigger(
           usageTotalTokens: result.usage?.totalTokens,
         })
 
-        debugLog(`[elasticdash] Trigger ${trigger.triggerId} step=${step.eventName} run=${i} ok=${result.ok}`)
+        debugLog(`[elasticdash] Trigger ${trigger.triggerId} step=${stepIndex + 1}/${totalSteps} name=${step.eventName} run=${i + 1}/${trigger.runCount} phase=done ok=${result.ok} elapsedMs=${Date.now() - runStart}`)
       }
 
       stepResult = {