elasticdash-test 0.1.25-alpha-2 → 0.1.25

package/docs/agent-integration-guide.md

@@ -5,6 +5,8 @@
 > **When to use**: Follow this guide step-by-step when a user asks you to "integrate ElasticDash", "set up ElasticDash testing", "implement elasticdash-test", or similar. Each step produces a specific file — work through them in order.
 >
 > **How to use**: Read the full guide first to understand the project's structure, then execute each step. Use the decision trees section to choose the right pattern for the user's project (framework type, module system, tool architecture).
+>
+> **Important**: Do NOT leave `YOUR_TOOL_NAME` / `YOUR_WORKFLOW_NAME` placeholders in generated files. Before creating `ed_tools.ts` and `ed_workflows.ts`, scan the user's codebase to identify their actual tool functions (functions that call external APIs, databases, or services) and workflow functions (async functions that orchestrate LLM calls and tool calls). Create the files with the real function names, imports, and types found in the codebase. If no tools or workflows exist yet, ask the user which functions to instrument rather than generating placeholder files.
 
 ---
 
@@ -12,9 +14,18 @@
 
 - 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`)
 
+### Identify tools and workflows in the codebase
+
+Before starting, scan the project to find:
+
+- **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`.
+
+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."
+
 ### Detect project type before starting
 
 Check these before choosing patterns:
@@ -47,6 +58,8 @@ Add to `.gitignore`:
 
 Create `ed_tools.ts` in the project root. This file wraps each tool function with tracing so ElasticDash can record and replay tool calls.
 
+**Before writing this file**: Search the codebase for functions that call external services (APIs, databases, SDKs). Each one becomes a wrapped export in `ed_tools.ts`. Replace all `YOUR_TOOL_*` and `YOUR_SOURCE_PATH_*` placeholders below with the actual function names and import paths found in the project.
+
 ### Choose your pattern
 
 - **Pattern B (recommended for most projects)**: inline async with mock support. Use when tools are imported individually, no central dispatcher exists, or you want dashboard mock support.
@@ -221,6 +234,8 @@ export default nextConfig
 
 Create `ed_workflows.ts` in the project root. This file exports workflow functions for the ElasticDash runner.
 
+**Before writing this file**: Search the codebase for the main AI workflow functions — async functions that orchestrate LLM calls and tool calls (e.g., a chat handler, an agent loop, a pipeline function). Replace all `YOUR_WORKFLOW` and `YOUR_SOURCE_PATH` placeholders below with the actual function names and import paths.
+
 ### Simple case — direct re-export
 
 ```ts
@@ -292,19 +307,53 @@ export { chatStreamHandler } from './app/api/chat-stream/chatStreamHandler'
 
 ---
 
-## Step 4: Update workflow imports
+## Step 4: Wire `ed_workflows.ts` to use `ed_tools.ts`
+
+> **Do not modify the user's existing production source files.** Only `ed_workflows.ts` needs to import from `ed_tools.ts`. The production codebase stays untouched.
+
+The ElasticDash layer sits alongside the production code, not inside it:
+
+```
+Production code (unchanged):
+  src/workflows/checkout.ts → imports from src/services/payments.ts directly
+
+ElasticDash layer (new files only):
+  ed_workflows.ts → imports tools from ed_tools.ts → calls the real service functions
+```
+
+### What to do
 
-Change your workflow code to import tools from `ed_tools.ts` instead of the original source files:
+In `ed_workflows.ts`, write wrapper functions that call tools through `ed_tools.ts` instead of importing from the original source. The ElasticDash test runner and dashboard call `ed_workflows.ts` — not the production code directly.
+
+### Example
 
 ```ts
-// BEFORE
-import { YOUR_TOOL_1 } from './services/YOUR_SOURCE'
+// ed_workflows.ts
+// Import tools from ed_tools.ts (instrumented), NOT from original source
+import { chargeCard, getOrderDetails } from './ed_tools'
+
+// Re-create the workflow logic using instrumented tools
+export async function checkoutFlow(input: { orderId: string }) {
+  const order = await getOrderDetails({ orderId: input.orderId })
+  const payment = await chargeCard({ amount: order.total })
+  return { orderId: order.orderId, paymentId: payment.id }
+}
+```
 
-// AFTER
-import { YOUR_TOOL_1 } from './ed_tools'
+```ts
+// ed_tools.ts
+// Import from the ORIGINAL source
+import { chargeCard as chargeCardImpl } from './src/services/payments'
+import { getOrderDetails as getOrderDetailsImpl } from './src/services/orders'
+
+// ... wrap with resolveMock + safeRecordToolCall pattern
 ```
 
-This single import change makes all tool calls observable by ElasticDash.
+### Why this approach
+
+- **No production risk**: Existing source files are never modified. Production imports stay as-is.
+- **Clean separation**: The `ed_` files are a parallel test/observability layer, not a refactor of the codebase.
+- **Easy removal**: Delete `ed_tools.ts` and `ed_workflows.ts` to fully remove ElasticDash — no rollback needed.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "elasticdash-test",
-  "version": "0.1.25-alpha-2",
+  "version": "0.1.25",
   "description": "AI-native test runner for ElasticDash workflow testing",
   "type": "module",
   "bin": {