elasticdash-sdk 0.2.0

package/dist/workflow-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-runner.js","sourceRoot":"","sources":["../src/workflow-runner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AACxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AACtD,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AACrE,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAA;AACjH,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAgBxD,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,UAA4B,EAC5B,UAA8B,EAAE;IAEhC,MAAM,EACJ,UAAU,GAAG,KAAK,EAClB,UAAU,GAAG,CAAC,EACd,OAAO,GAAG,EAAE,EACZ,aAAa,GAAG,IAAI,EACpB,oBAAoB,GAAG,IAAI,GAC5B,GAAG,OAAO,CAAA;IAEX,MAAM,QAAQ,GAAG,IAAI,aAAa,EAAE,CAAA;IACpC,MAAM,MAAM,GAAG,IAAI,gBAAgB,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,CAAC,CAAA;IAEpE,iBAAiB,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAA;IAEvC,IAAI,aAAa;QAAE,cAAc,EAAE,CAAA;IACnC,IAAI,oBAAoB,EAAE,CAAC;QACzB,eAAe,EAAE,CAAA;QACjB,gBAAgB,EAAE,CAAA;IACpB,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,UAAU,EAAE,CAAA;QACjC,MAAM,QAAQ,CAAC,KAAK,EAAE,CAAA;QACtB,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,EAAE,CAAA;QAChC,MAAM,iBAAiB,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;QACpD,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAA;IAC1B,CAAC;YAAS,CAAC;QACT,IAAI,aAAa;YAAE,YAAY,EAAE,CAAA;QACjC,IAAI,oBAAoB,EAAE,CAAC;YACzB,aAAa,EAAE,CAAA;YACf,cAAc,EAAE,CAAA;QAClB,CAAC;QACD,iBAAiB,CAAC,SAAS,CAAC,CAAA;IAC9B,CAAC;AACH,CAAC"}

package/docs/agent-coding-instructions.md

@@ -0,0 +1,138 @@
+# ElasticDash SDK — AI Coding Agent Instructions
+
+> **Audience**: Coding agents (Claude Code, Cursor, Copilot, Codex, Windsurf, etc.) integrating `elasticdash-sdk` into a user's project.
+>
+> **When to use**: Follow these instructions when a user asks you to "integrate ElasticDash", "set up ElasticDash testing", "implement elasticdash-sdk", or similar.
+>
+> **Technical reference**: All templates, code patterns, and step-by-step implementation details are in the companion doc: [Integration Guide](./agent-integration-guide.md) (`node_modules/elasticdash-sdk/docs/agent-integration-guide.md`). Read it alongside these instructions.
+
+---
+
+## How to start
+
+Tell your coding agent this prompt to begin:
+
+```
+Integrate elasticdash-sdk into this project.
+Read node_modules/elasticdash-sdk/docs/agent-coding-instructions.md for how to proceed,
+and node_modules/elasticdash-sdk/docs/agent-integration-guide.md for technical reference.
+```
+
+Or if you used `npx elasticdash init-guide`:
+
+```
+Read AGENTS.md and follow it to integrate elasticdash-sdk into this project.
+Also read node_modules/elasticdash-sdk/docs/agent-integration-guide.md for technical reference.
+```
+
+---
+
+## Behavioral rules
+
+- **Automation level**: Automatically implement all steps unless you are not confident about a specific change (e.g., unclear which function is a tool vs. a utility, or ambiguous workflow boundaries). In those cases, ask the user before proceeding. For straightforward tool/workflow functions, proceed without asking.
+- **No placeholders**: Do NOT leave `YOUR_TOOL_NAME` / `YOUR_WORKFLOW_NAME` placeholders in generated files. Scan the codebase first and use real function names, imports, and types.
+- **Modify source files**: The integration requires updating existing source files (route handlers, executors) to import tools from `ed_tools` and add trace hooks. This is expected — do not skip it.
+
+---
+
+## Execution order
+
+### Phase 1: Pre-flight checks
+
+**1. Check `.env` for `ELASTICDASH_API_URL`**
+
+- If present: use the existing value.
+- If missing: add `ELASTICDASH_API_URL=https://server.elasticdash.com` to `.env`.
+
+**2. Check `.env` for `ELASTICDASH_API_KEY`**
+
+- If present: proceed.
+- If missing: **STOP and ask the user**:
+
+> "Your project needs an ElasticDash API key. Please complete the onboarding at https://app.elasticdash.com to get your project API key, then add `ELASTICDASH_API_KEY=ed_your_key_here` to your `.env` file. Let me know when it's ready."
+
+**Do not continue until `ELASTICDASH_API_KEY` is set.** The SDK cannot connect to the backend without it.
+
+
+### Phase 2: Scan the codebase
+
+Before creating any files, identify:
+
+- **Tool functions**: Exported async functions that call external services (APIs, databases, search, etc.). Look for functions that use `fetch`, database clients, SDK calls, or any external I/O. These go in `ed_tools.ts`.
+- **Workflow functions**: Exported async functions that orchestrate an AI pipeline — typically calling an LLM and one or more tools. Look for functions that call OpenAI, Anthropic, Gemini, or similar SDKs. These go in `ed_workflows.ts`.
+- **Route handlers / entry points**: Files that call the tool and workflow functions above. These need import updates in Phase 3.
+
+If the project has no clear tool or workflow functions yet, ask the user:
+
+> "Which functions in your codebase make external API/service calls (tools), and which functions orchestrate your AI workflow? I need to know so I can set up ElasticDash instrumentation."
+
+Also detect the project type (see [Integration Guide — Prerequisites](./agent-integration-guide.md#detect-project-type-before-starting)) to choose the right patterns.
+
+### Phase 3: Implement
+
+Follow the [Integration Guide](./agent-integration-guide.md) steps 1–7 in order, using real function names from Phase 2:
+
+1. **Install** — `npm install elasticdash-sdk`, update `.gitignore`
+2. **Create `ed_tools.ts`** — wrap each identified tool function with `wrapTool()`
+3. **Create `ed_workflows.ts`** — add trace hooks (`edStartTrace`/`edEndTrace`) and workflow exports
+4. **Update existing source files** — change imports from original sources to `ed_tools`, add trace hooks to route handlers
+5. **Add config and scripts** — `elasticdash.config.ts`, `package.json` scripts
+6. **Environment variables** — verify all required vars are in `.env`
+7. **Write a test** (optional) — create a sample `.ai.test.ts` file if the user wants tests
+
+**When modifying existing files (Step 4):**
+
+- Search the codebase for every file that imports the original tool functions
+- Update imports to come from `ed_tools` instead
+- Add `edStartTrace`/`edEndTrace` to route handlers
+- Do NOT modify `ed_tools.ts` imports (they must still reference original sources)
+- Do NOT modify the original tool implementation files
+- If unsure whether a function is a tool, ask the user
+
+### Phase 4: Validate
+
+Run the `observe` command to establish a socket.io connection to the ElasticDash backend:
+
+```bash
+npx elasticdash observe
+```
+
+**Expected output on success:**
+
+```
+[elasticdash] Observability active
+  Session ID : <uuid>
+  Server     : https://server.elasticdash.com
+```
+
+This confirms:
+
+- `ELASTICDASH_API_URL` and `ELASTICDASH_API_KEY` are valid (backend authenticates the API key and returns `auth:ok`)
+- The socket.io connection to the backend is established
+- The SDK discovered and registered tools from `ed_tools.ts` and workflows from `ed_workflows.ts` (pushed to `POST /api/observability/catalog`)
+
+**If it fails:** Check that `.env` has valid values. If the API key is rejected, the user needs to get a new one from https://app.elasticdash.com.
+
+After validation, stop the observe process (Ctrl+C) and inform the user that ElasticDash is integrated. Provide these commands for ongoing use:
+
+```bash
+npx elasticdash test          # Run aiTest tests
+npx ed ed-test --no-upload    # Run defineTest benchmarks
+npx elasticdash dashboard     # Open the dashboard
+npx elasticdash observe       # Start live tracing
+```
+
+---
+
+## Decision guidance
+
+When the integration guide offers multiple patterns, use these rules:
+
+| Decision | Choose this | When |
+|----------|-------------|------|
+| Subprocess vs HTTP mode | HTTP mode | Project uses Next.js, Remix, SvelteKit, or similar framework |
+| Subprocess vs HTTP mode | Subprocess (default) | Plain Node.js project, no framework |
+| `wrapTool` vs manual pattern | `wrapTool` | Always prefer unless the project specifically needs mock support via `resolveMock` |
+| Path alias handling | Advanced dashboard script | `tsconfig.json` has a `"paths"` field |
+| `ed_agents.ts` | Create it | Project has a planner/executor agent pattern |
+| `ed_agents.ts` | Skip it | No multi-step agent |

package/docs/agent-integration-guide.md

@@ -0,0 +1,564 @@
+# ElasticDash SDK — Integration Guide
+
+Technical reference for integrating `elasticdash-sdk` into a project. Contains all templates, code patterns, and step-by-step details.
+
+> **For AI coding agents**: See [Agent Coding Instructions](./agent-coding-instructions.md) for behavioral rules, automation guidance, and execution order.
+
+## How to start with a coding agent
+
+Tell your coding agent this prompt:
+
+```
+Integrate elasticdash-sdk into this project.
+Read node_modules/elasticdash-sdk/docs/agent-coding-instructions.md for how to proceed,
+and node_modules/elasticdash-sdk/docs/agent-integration-guide.md for technical reference.
+```
+
+---
+
+## Prerequisites
+
+- Node.js >= 20
+- npm, yarn, or pnpm
+- At least one AI workflow function (a callable async function that makes LLM/tool calls)
+- LLM provider API keys for providers used in workflows (e.g., `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`)
+
+### Detect project type before starting
+
+Check these before choosing patterns:
+
+| Check | How | Result |
+|-------|-----|--------|
+| Module system | `package.json` → `"type"` field | `"module"` = ESM, `"commonjs"` or missing = CJS |
+| Framework | Look for `next.config.*`, `remix.config.*`, `svelte.config.*` | Present = framework project, use HTTP mode |
+| Path aliases | `tsconfig.json` → `"paths"` field | Present = need advanced dashboard script |
+| Tool architecture | Does the project use a central `dispatchTool(name, args)` function? | Yes = Pattern A, No = Pattern B |
+
+---
+
+## Step 1: Install
+
+```bash
+npm install elasticdash-sdk
+```
+
+Add to `.gitignore`:
+
+```gitignore
+.temp/
+.ed_traces/
+```
+
+---
+
+## 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.
+
+### Template
+
+```ts
+// ed_tools.ts
+import { setElasticDashModule } from './ed_workflows'
+
+// Import original tool implementations from the actual source files
+import { originalTool1 } from './services/YOUR_SOURCE_1'
+import { originalTool2 } from './utils/YOUR_SOURCE_2'
+
+// ---------------------------------------------------------------------------
+// Load elasticdash-sdk and share the module with ed_workflows.ts
+// ---------------------------------------------------------------------------
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type WrapToolFn = <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
+
+try {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const _edModule = (eval('require') as (id: string) => any)('elasticdash-sdk')
+  wrapTool = _edModule.wrapTool ?? wrapTool
+  // 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
+}
+
+// ---------------------------------------------------------------------------
+// Wrapped tools — one export per tool
+// ---------------------------------------------------------------------------
+
+export const myTool1 = wrapTool('myTool1', async (input: any) => {
+  return await originalTool1(input)
+})
+
+export const myTool2 = wrapTool('myTool2', async (input: any) => {
+  const { someField } = input as { someField: string }
+  return await originalTool2(someField)
+})
+```
+
+### 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`.
+- 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.
+- 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.
+
+### Next.js only
+
+Add `elasticdash-sdk` to `serverExternalPackages` in `next.config.ts`:
+
+```ts
+// next.config.ts
+const nextConfig = {
+  serverExternalPackages: ['elasticdash-sdk'],
+}
+export default nextConfig
+```
+
+---
+
+## Step 3: Create `ed_workflows.ts`
+
+Create `ed_workflows.ts` in the project root. This file serves two purposes:
+
+1. **Trace lifecycle hooks** (`edStartTrace`, `edEndTrace`) — called from route handlers to mark workflow boundaries
+2. **Workflow exports** — callable functions for the ElasticDash dashboard and test runner
+
+### Trace lifecycle hooks
+
+Every `ed_workflows.ts` should export `edStartTrace` and `edEndTrace`. These are called from route handlers (Step 4) to mark when a workflow starts and ends:
+
+```ts
+// ed_workflows.ts — trace hooks (copy as-is)
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let _ed: any = null
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function setElasticDashModule(mod: any): void {
+  _ed = mod
+}
+
+export const edStartTrace = async (workflowName: string): Promise<void> => {
+  if (!_ed) return
+  try {
+    await _ed.tryAutoInitHttpContext()
+    _ed.startTrace(workflowName)
+  } catch (err) {
+    console.error('[ed_workflows] edStartTrace error:', err)
+  }
+}
+
+export const edEndTrace = (): void => {
+  if (!_ed) return
+  try {
+    _ed.endTrace()
+  } catch (err) {
+    console.error('[ed_workflows] edEndTrace error:', err)
+  }
+}
+```
+
+### Workflow exports — simple case
+
+For non-framework projects where the workflow can be imported directly:
+
+```ts
+// ed_workflows.ts
+export { YOUR_WORKFLOW } from './YOUR_SOURCE_PATH'
+```
+
+### Workflow exports — HTTP mode (Next.js / Remix / framework projects)
+
+For framework projects, the workflow calls the running dev server instead of importing the route handler:
+
+```ts
+// ed_workflows.ts
+
+const APP_URL = process.env.APP_URL ?? 'http://localhost:3000'
+
+export const YOUR_WORKFLOW = async (input: {
+  messages: Array<{ role: string; content: string }>
+  sessionId?: string
+}): Promise<unknown> => {
+  const response = await fetch(`${APP_URL}/api/YOUR_ENDPOINT`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(input),
+  })
+
+  if (!response.ok) {
+    const text = await response.text()
+    throw new Error(`HTTP ${response.status}: ${text}`)
+  }
+
+  return response.json()
+}
+```
+
+### Requirements for all workflow exports
+
+- Accept only JSON-serializable inputs (strings, numbers, arrays, plain objects)
+- Return only JSON-serializable outputs
+- Must not depend on framework runtime APIs, HTTP request context, or live service clients
+
+---
+
+## Step 4: Update existing source files to use `ed_tools`
+
+> **This step modifies the user's existing source files.** The files that call tool functions must import from `ed_tools` instead of the original source, so that all tool calls go through the ElasticDash tracing layer. Similarly, workflow entry points (route handlers, etc.) must call `edStartTrace` / `edEndTrace` from `ed_workflows`.
+
+### Architecture after integration
+
+```
+ed_tools.ts
+  ├── imports original functions from services/utils
+  ├── wraps each with wrapTool() for tracing
+  └── exports wrapped versions with the SAME or similar names
+
+ed_workflows.ts
+  ├── exports edStartTrace / edEndTrace for workflow-level tracing
+  └── exports workflow functions (for dashboard/test runner)
+
+Existing source files (MODIFIED):
+  app/api/chat/route.ts
+    ├── BEFORE: import { myTool } from '@/services/myService'
+    ├── AFTER:  import { myTool } from '@/ed_tools'
+    ├── ADDED:  import { edStartTrace, edEndTrace } from '@/ed_workflows'
+    └── ADDED:  await edStartTrace('workflowName') at handler entry
+                edEndTrace() at handler exit
+```
+
+### What to do
+
+**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.
+
+```ts
+// BEFORE — app/api/chat/route.ts
+import { clarifyAndRefineUserInput } from '@/utils/queryRefinement'
+import { dynamicApiRequest } from '@/services/apiService'
+
+// AFTER — app/api/chat/route.ts
+import { queryRefinement } from '@/ed_tools'
+import { apiService } from '@/ed_tools'
+```
+
+```ts
+// BEFORE — app/api/chat/executor.ts
+import { dynamicApiRequest } from '@/services/apiService'
+
+// AFTER — app/api/chat/executor.ts
+import { apiService } from '@/ed_tools'
+```
+
+**2. Add trace hooks to route handlers / workflow entry points:**
+
+At the top of each route handler or workflow entry function, add `edStartTrace` and `edEndTrace`:
+
+```ts
+// app/api/chat/route.ts
+import { edStartTrace, edEndTrace } from '@/ed_workflows'
+
+export async function POST(req: Request) {
+  await edStartTrace('chatHandler')
+  try {
+    // ... existing handler logic, now using tools from ed_tools
+  } finally {
+    edEndTrace()
+  }
+}
+```
+
+**3. Update call sites if the wrapped function has a different name:**
+
+If `ed_tools.ts` exports a tool under a different name than the original (e.g., `queryRefinement` wrapping `clarifyAndRefineUserInput`), update the call sites to use the new name.
+
+### What NOT to modify
+
+- **Do not modify `ed_tools.ts` imports** — it must still import from the original source files.
+- **Do not modify the original tool implementation files** (e.g., `services/apiService.ts`, `utils/queryRefinement.ts`) — they stay as-is.
+- **Do not modify files that don't call tool functions** — only update files that directly import and call the wrapped tools.
+
+---
+
+## Step 5: Add config and scripts
+
+### `elasticdash.config.ts`
+
+Create in project root:
+
+```ts
+// elasticdash.config.ts
+export default {
+  testMatch: ['**/*.ai.test.ts'],
+  traceMode: 'local' as const,
+}
+```
+
+### `package.json` scripts
+
+Add these scripts:
+
+```json
+{
+  "scripts": {
+    "dashboard:ai": "elasticdash dashboard",
+    "test:ai": "elasticdash test"
+  }
+}
+```
+
+**If the project uses TypeScript path aliases** (e.g., `@/lib/...` in `tsconfig.json` `paths`):
+
+```json
+{
+  "scripts": {
+    "dashboard:ai": "NODE_OPTIONS='--import tsx/esm --require tsx/cjs --require tsconfig-paths/register' elasticdash dashboard"
+  }
+}
+```
+
+---
+
+## Step 6: Environment variables
+
+Set in `.env` or CI secrets:
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `ELASTICDASH_API_URL` | Backend server URL (`https://server.elasticdash.com` for cloud) | For upload/CI |
+| `ELASTICDASH_API_KEY` | Project API key from dashboard | For upload/CI |
+| `ELASTICDASH_DEBUG` | Set to `1` to enable SDK debug logging (default: off) | Optional |
+| `ELASTICDASH_CAPTURE_TRACE` | Set to `1` to record trace fixtures to disk (default: off) | Optional |
+| `ELASTICDASH_ACCEPT_RERUNS` | Set to `false`/`0` to reject rerun requests (default: on) | Optional |
+| `OPENAI_API_KEY` | OpenAI API key | If using OpenAI |
+| `ANTHROPIC_API_KEY` | Anthropic API key | If using Claude |
+| `GEMINI_API_KEY` | Google Gemini API key | If using Gemini |
+| `GROK_API_KEY` | xAI Grok API key | If using Grok |
+
+---
+
+## Step 7: Write a test
+
+### Option A: `aiTest` — live workflow testing
+
+Create a file ending in `.ai.test.ts`:
+
+```ts
+// tests/YOUR_WORKFLOW.ai.test.ts
+import 'elasticdash-sdk/dist/test-setup.js'
+import { expect } from 'expect'
+
+// Import your workflow from ed_workflows.ts
+import { YOUR_WORKFLOW } from '../ed_workflows'
+
+aiTest('YOUR_TEST_NAME', async (ctx) => {
+  await YOUR_WORKFLOW({ /* your input */ })
+
+  // Assert an LLM step occurred
+  expect(ctx.trace).toHaveLLMStep({ model: 'gpt-4' })
+
+  // Assert a tool was called
+  expect(ctx.trace).toCallTool('YOUR_TOOL_NAME')
+
+  // Semantic output matching (LLM-judged)
+  expect(ctx.trace).toMatchSemanticOutput('expected output description')
+})
+```
+
+### Option B: `defineTest` — CI/CD fixture-based testing
+
+First, record a trace:
+
+```bash
+ELASTICDASH_CAPTURE_TRACE=1 tsx YOUR_WORKFLOW_SCRIPT.ts
+```
+
+Then create `ed_tests.ts`:
+
+```ts
+// ed_tests.ts
+import { defineTest } from 'elasticdash-sdk'
+import { YOUR_WORKFLOW } from './ed_workflows'
+
+defineTest({
+  name: 'YOUR_TEST_NAME',
+  trace: './.ed_traces/YOUR_TRACE_FILE.json',
+  target: { type: 'tool_call', step_id: 'tool_call_0' },
+  benchmarks: { max_duration_ms: 2000 },
+  run: async () => {
+    await YOUR_WORKFLOW({ /* your input */ })
+  },
+})
+```
+
+Run:
+
+```bash
+npx ed ed-test --no-upload
+```
+
+---
+
+## Step 8: Validate the integration
+
+After all files are created, validate the setup by establishing a socket.io connection to the ElasticDash backend. Run the `observe` command — it connects to the server, authenticates with the API key, and registers the project's tools and workflows:
+
+```bash
+npx elasticdash observe
+```
+
+**Expected output on success:**
+
+```
+[elasticdash] Observability active
+  Session ID : <uuid>
+  Server     : https://server.elasticdash.com
+```
+
+This confirms:
+- `ELASTICDASH_API_URL` and `ELASTICDASH_API_KEY` are valid
+- The socket.io connection to the backend is established
+- The SDK can discover `ed_tools.ts` and `ed_workflows.ts`
+
+**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.
+
+After validation, stop the observe process (Ctrl+C) and inform the user that ElasticDash is integrated. Provide these commands for ongoing use:
+
+```bash
+# Run aiTest tests
+npx elasticdash test
+
+# Run defineTest benchmarks
+npx ed ed-test --no-upload
+
+# Open the dashboard
+npx elasticdash dashboard
+
+# Start observability (connect to backend for live tracing)
+npx elasticdash observe
+
+# Record a trace fixture
+ELASTICDASH_CAPTURE_TRACE=1 tsx your-workflow.ts
+```
+
+---
+
+## Decision Trees
+
+### Subprocess mode vs HTTP mode
+
+```
+Does your workflow live inside a framework route handler (Next.js, Remix, SvelteKit)?
+  YES → Use HTTP mode:
+    1. Configure workflow in elasticdash.config.ts with mode: 'http'
+    2. Add initHttpRunContext() to your request handler
+    3. Use wrapTool/wrapAI for observability
+  NO → Use subprocess mode (default):
+    1. Export workflow from ed_workflows.ts
+    2. Tools auto-intercepted via ed_tools.ts
+```
+
+### HTTP mode config template
+
+```ts
+// elasticdash.config.ts
+export default {
+  testMatch: ['**/*.ai.test.ts'],
+  workflows: {
+    YOUR_WORKFLOW: {
+      mode: 'http',
+      url: 'http://localhost:3001/api/YOUR_ENDPOINT',
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      bodyTemplate: {
+        messages: [{ role: 'user', content: '{{input.message}}' }],
+      },
+      responseFormat: 'vercel-ai-stream',
+    },
+  },
+}
+```
+
+### HTTP mode handler setup
+
+```ts
+// app/api/YOUR_ENDPOINT/route.ts
+import { initHttpRunContext, wrapTool, wrapAI } from 'elasticdash-sdk'
+
+export async function POST(req: Request) {
+  const runId = req.headers.get('x-elasticdash-run-id')
+  const serverUrl = req.headers.get('x-elasticdash-server')
+  if (runId && serverUrl) {
+    await initHttpRunContext(runId, serverUrl)
+  }
+  // ... rest of handler
+}
+```
+
+### AI call recording
+
+```
+Does your workflow call LLMs via OpenAI/Gemini/Grok SDKs?
+  YES → Automatic interception, no code changes needed
+  NO (custom provider or Anthropic SDK) → Use wrapAI:
+    import { wrapAI } from 'elasticdash-sdk'
+    export const callLLM = wrapAI('model-name', async (messages) => {
+      return await yourLLMClient.call(messages)
+    })
+```
+
+### Agent setup (`ed_agents.ts`)
+
+```
+Does your project use a multi-step agent with a planner/executor pattern?
+  YES → Create ed_agents.ts:
+    export { plannerAgent, executorAgent } from './your-agent-logic'
+    // OR use SDK reference implementations:
+    export { plannerAgent, executorAgent, resumeAgentFromTrace } from 'elasticdash-sdk'
+  NO → Skip ed_agents.ts
+```
+
+---
+
+## Troubleshooting
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `replay miss: tool_call::YOUR_TOOL` | Trace fixture is stale or workflow changed | Re-record: `ELASTICDASH_CAPTURE_TRACE=1 tsx your-workflow.ts` |
+| `MODULE_NOT_FOUND: elasticdash-sdk` | SDK not installed or Next.js bundling issue | Run `npm install elasticdash-sdk`. For Next.js, add to `serverExternalPackages` |
+| `Cannot find module '@/...'` | Path aliases not resolved at runtime | Use advanced dashboard script with `tsconfig-paths/register` |
+| `test has no run function` | `run` field missing in `defineTest` | Add `run: async () => { ... }` to the test definition |
+| `Tool "x" not found in registry` | Tool not exported from `ed_tools.ts` | Export the tool function from `ed_tools.ts` |
+| `ERR_UNKNOWN_FILE_EXTENSION` | ESM/CJS mismatch | Check `package.json` `type` field and `tsconfig.json` `module` setting |
+| Git metadata shows `unknown` | No `.git` directory | Ensure repo is checked out (common in CI with shallow clones) |
+
+---
+
+## Final checklist
+
+After integration, verify these files exist:
+
+```
+your-project/
+  .env                  # ELASTICDASH_API_URL and ELASTICDASH_API_KEY set
+  ed_tools.ts           # Instrumented tool wrappers (real function names, not placeholders)
+  ed_workflows.ts       # Workflow exports using tools from ed_tools.ts
+  elasticdash.config.ts # Test runner config
+  package.json          # dashboard:ai and test:ai scripts added
+  .gitignore            # .temp/ and .ed_traces/ added
+```
+
+Verify by running `npx elasticdash observe` — a successful socket.io connection confirms the integration is complete.