evergreen-sdk 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+interface ApiCallMeta {
+    callee: string;
+    arg0?: string;
+}
+interface StepOptions {
+    input?: any;
+    children?: string[];
+    apiCalls?: ApiCallMeta[];
+    __not_async?: boolean;
+}
+export declare const evergreen: {
+    clear(): void;
+    run<T>(jobId: string, fn: () => T): T;
+    __autoStep<T>(name: string, location: {
+        file: string;
+        line: number;
+        column?: number;
+    }, fn: () => T | Promise<T>, options?: StepOptions): Promise<T>;
+    step<T>(name: string, fn: () => T | Promise<T>, options?: StepOptions): Promise<T>;
+};
+export {};

package/dist/index.js

@@ -0,0 +1,273 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evergreen = void 0;
+const node_async_hooks_1 = require("node:async_hooks");
+const ws_1 = __importDefault(require("ws"));
+const traceStorage = new node_async_hooks_1.AsyncLocalStorage();
+let ws = null;
+let isConnected = false;
+const pendingTelemetry = [];
+// Connect to the VS Code Extension Hub
+function connect() {
+    if (ws &&
+        (ws.readyState === ws_1.default.CONNECTING || ws.readyState === ws_1.default.OPEN))
+        return;
+    try {
+        ws = new ws_1.default("ws://localhost:3000");
+        ws.on("open", () => {
+            isConnected = true;
+            // Flush any telemetry that was emitted before the socket became ready.
+            while (pendingTelemetry.length > 0) {
+                const queued = pendingTelemetry.shift();
+                if (queued) {
+                    sendTelemetry(queued);
+                }
+            }
+        });
+        ws.on("close", () => {
+            isConnected = false;
+            // Optionally implement reconnect logic here
+        });
+        ws.on("error", () => {
+            isConnected = false;
+            // Silently fail if extension is not running
+        });
+    }
+    catch (error) {
+        isConnected = false;
+    }
+}
+// Ensure connection is attempted
+connect();
+function sanitizePayload(obj, maxDepth = 3) {
+    if (maxDepth <= 0)
+        return "[Max Depth Reached]";
+    if (obj === null || obj === undefined)
+        return obj;
+    if (typeof obj !== "object")
+        return obj;
+    if (obj instanceof Error) {
+        return { name: obj.name, message: obj.message, stack: obj.stack };
+    }
+    if (Array.isArray(obj)) {
+        return obj.map((item) => sanitizePayload(item, maxDepth - 1));
+    }
+    const sanitized = {};
+    for (const [key, value] of Object.entries(obj)) {
+        sanitized[key] = sanitizePayload(value, maxDepth - 1);
+    }
+    return sanitized;
+}
+function sendTelemetry(payload) {
+    console.log("TELEMETRY EMITTED:", payload.stepName, payload.status);
+    if (!ws || ws.readyState !== ws_1.default.OPEN) {
+        // Queue messages until the websocket is fully ready instead of dropping them.
+        pendingTelemetry.push(payload);
+        return;
+    }
+    try {
+        ws.send(JSON.stringify(payload));
+    }
+    catch (error) {
+        // Fire and forget, silently ignore send errors
+    }
+}
+function extractLocationFromStack(stack) {
+    if (!stack)
+        return undefined;
+    // The stack will look like:
+    // Error
+    //   at Object.step (/path/to/sdk/index.ts:...)
+    //   at myBusinessLogic (/path/to/business/logic.ts:42:15)
+    const lines = stack.split("\n");
+    if (lines.length >= 3) {
+        const callerLine = lines[2];
+        const match = callerLine.match(/\((.+):(\d+):\d+\)/) ||
+            callerLine.match(/at (.+):(\d+):\d+/);
+        if (match && match.length >= 3) {
+            return { file: match[1], line: parseInt(match[2], 10) };
+        }
+    }
+    return undefined;
+}
+exports.evergreen = {
+    clear() {
+        sendTelemetry({ type: "CLEAR" });
+    },
+    run(jobId, fn) {
+        return traceStorage.run({ jobId }, fn);
+    },
+    async __autoStep(name, location, fn, options) {
+        const store = traceStorage.getStore();
+        // If no context, just execute the function normally without tracing
+        if (!store) {
+            return await fn();
+        }
+        const { jobId, previousStep } = store;
+        const timestamp = Date.now();
+        const startTime = process.hrtime.bigint();
+        // Emit NODE_STARTED
+        sendTelemetry({
+            event: "NODE_STARTED",
+            status: "PENDING",
+            jobId,
+            stepName: name,
+            previousStep,
+            location,
+            children: options?.children || [],
+            apiCalls: options?.apiCalls || [],
+            __not_async: options?.__not_async ?? false,
+            timestamp,
+        });
+        // We must ensure subsequent nested steps know this step is their parent.
+        // To do this, we run the inner function in a nested context.
+        const newContext = { ...store, previousStep: name };
+        try {
+            // Execute the business logic within the new nested context
+            const result = await traceStorage.run(newContext, async () => {
+                return await fn();
+            });
+            const endTime = process.hrtime.bigint();
+            const durationMs = Number(endTime - startTime) / 1000000;
+            // Emit NODE_COMPLETED
+            sendTelemetry({
+                event: "NODE_COMPLETED",
+                status: "SUCCESS",
+                jobId,
+                stepName: name,
+                previousStep,
+                payload: {
+                    input: sanitizePayload(options?.input),
+                    output: sanitizePayload(result),
+                },
+                context: {
+                    input: sanitizePayload(options?.input),
+                    output: sanitizePayload(result),
+                    duration: durationMs,
+                },
+                location,
+                // include children and apiCalls again so the UI can still render ghost edges & API badges even if NODE_STARTED was missed
+                children: options?.children || [],
+                apiCalls: options?.apiCalls || [],
+                __not_async: options?.__not_async ?? false,
+                timestamp: Date.now(),
+            });
+            return result;
+        }
+        catch (error) {
+            const endTime = process.hrtime.bigint();
+            const durationMs = Number(endTime - startTime) / 1000000;
+            // Emit NODE_FAILED
+            sendTelemetry({
+                event: "NODE_FAILED",
+                status: "FAILED",
+                jobId,
+                stepName: name,
+                previousStep,
+                payload: {
+                    input: sanitizePayload(options?.input),
+                    error: sanitizePayload(error),
+                },
+                context: {
+                    input: sanitizePayload(options?.input),
+                    error: sanitizePayload(error),
+                    duration: durationMs,
+                },
+                location,
+                timestamp: Date.now(),
+            });
+            // Re-throw so backend logic behaves normally
+            throw error;
+        }
+    },
+    async step(name, fn, options) {
+        const store = traceStorage.getStore();
+        // If no context, just execute the function normally without tracing
+        if (!store) {
+            return await fn();
+        }
+        const { jobId, previousStep } = store;
+        // Capture location using a throwaway error
+        const locationError = new Error();
+        const location = extractLocationFromStack(locationError.stack) || {
+            file: "unknown",
+            line: 0,
+        };
+        const timestamp = Date.now();
+        const startTime = process.hrtime.bigint();
+        // Emit NODE_STARTED
+        sendTelemetry({
+            event: "NODE_STARTED",
+            status: "PENDING",
+            jobId,
+            stepName: name,
+            previousStep,
+            location,
+            timestamp,
+        });
+        // We must ensure subsequent nested steps know this step is their parent.
+        // To do this, we run the inner function in a nested context.
+        const newContext = { ...store, previousStep: name };
+        try {
+            // Execute the business logic within the new nested context
+            const result = await traceStorage.run(newContext, async () => {
+                return await fn();
+            });
+            const endTime = process.hrtime.bigint();
+            const durationMs = Number(endTime - startTime) / 1000000;
+            // Emit NODE_COMPLETED
+            sendTelemetry({
+                event: "NODE_COMPLETED",
+                status: "SUCCESS",
+                jobId,
+                stepName: name,
+                previousStep,
+                payload: {
+                    input: sanitizePayload(options?.input),
+                    output: sanitizePayload(result),
+                },
+                context: {
+                    input: sanitizePayload(options?.input),
+                    output: sanitizePayload(result),
+                    duration: durationMs,
+                },
+                location,
+                timestamp: Date.now(),
+            });
+            return result;
+        }
+        catch (error) {
+            const endTime = process.hrtime.bigint();
+            const durationMs = Number(endTime - startTime) / 1000000;
+            // Emit NODE_FAILED
+            sendTelemetry({
+                event: "NODE_FAILED",
+                status: "FAILED",
+                jobId,
+                stepName: name,
+                previousStep,
+                payload: {
+                    input: sanitizePayload(options?.input),
+                    error: sanitizePayload(error),
+                },
+                context: {
+                    input: sanitizePayload(options?.input),
+                    error: sanitizePayload(error),
+                    duration: durationMs,
+                },
+                location,
+                timestamp: Date.now(),
+            });
+            // Re-throw so backend logic behaves normally
+            throw error;
+        }
+    },
+};
+// Test hooks to allow unit tests to observe telemetry behavior without
+// depending on console output.
+exports.evergreen.__test__ = {
+    sendTelemetry,
+};

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export declare function testAlsPropagation(): Promise<void>;

package/dist/index.test.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.testAlsPropagation = testAlsPropagation;
+const index_1 = require("./index");
+// Simple Node-style test (compatible with node --test once compiled)
+// exported for use in dist/index.test.js
+async function testAlsPropagation() {
+    const events = [];
+    const originalSend = index_1.evergreen.__test__?.sendTelemetry;
+    if (originalSend) {
+        index_1.evergreen.__test__.sendTelemetry = (payload) => {
+            events.push(payload);
+            originalSend(payload);
+        };
+    }
+    try {
+        await index_1.evergreen.run("job-123", async () => {
+            await index_1.evergreen.__autoStep("outer", { file: "test.ts", line: 1, column: 0 }, async () => {
+                await index_1.evergreen.__autoStep("inner", { file: "test.ts", line: 5, column: 0 }, async () => 42);
+            }, {});
+        });
+        const started = events.filter((e) => e.event === "NODE_STARTED");
+        const outerStarted = started.find((e) => e.stepName === "outer");
+        const innerStarted = started.find((e) => e.stepName === "inner");
+        if (!outerStarted || !innerStarted) {
+            throw new Error("Expected NODE_STARTED events for outer and inner");
+        }
+        if (outerStarted.jobId !== "job-123") {
+            throw new Error("outer.jobId mismatch");
+        }
+        if (innerStarted.jobId !== "job-123") {
+            throw new Error("inner.jobId mismatch");
+        }
+        if (outerStarted.previousStep !== undefined) {
+            throw new Error("outer.previousStep should be undefined");
+        }
+        if (innerStarted.previousStep !== "outer") {
+            throw new Error("inner.previousStep should be 'outer'");
+        }
+    }
+    finally {
+        if (originalSend) {
+            index_1.evergreen.__test__.sendTelemetry = originalSend;
+        }
+    }
+}

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "evergreen-sdk",
+  "version": "1.0.0",
+  "description": "Evergreen Trace Backend SDK",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc -w",
+    "test": "NODE_ENV=test node --test dist/index.test.js"
+  },
+  "dependencies": {
+    "ws": "^8.14.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/ws": "^8.5.5",
+    "typescript": "^5.0.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,160 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evergreen = void 0;
+const node_async_hooks_1 = require("node:async_hooks");
+const ws_1 = require("ws");
+const traceStorage = new node_async_hooks_1.AsyncLocalStorage();
+let ws = null;
+let isConnected = false;
+// Connect to the VS Code Extension Hub
+function connect() {
+    if (ws && (ws.readyState === ws_1.default.CONNECTING || ws.readyState === ws_1.default.OPEN))
+        return;
+    try {
+        ws = new ws_1.default('ws://localhost:3000');
+        ws.on('open', () => {
+            isConnected = true;
+        });
+        ws.on('close', () => {
+            isConnected = false;
+            // Optionally implement reconnect logic here
+        });
+        ws.on('error', () => {
+            isConnected = false;
+            // Silently fail if extension is not running
+        });
+    }
+    catch (error) {
+        isConnected = false;
+    }
+}
+// Ensure connection is attempted
+connect();
+function sanitizePayload(obj, maxDepth = 3) {
+    if (maxDepth <= 0)
+        return '[Max Depth Reached]';
+    if (obj === null || obj === undefined)
+        return obj;
+    if (typeof obj !== 'object')
+        return obj;
+    if (obj instanceof Error) {
+        return { name: obj.name, message: obj.message, stack: obj.stack };
+    }
+    if (Array.isArray(obj)) {
+        return obj.map(item => sanitizePayload(item, maxDepth - 1));
+    }
+    const sanitized = {};
+    for (const [key, value] of Object.entries(obj)) {
+        sanitized[key] = sanitizePayload(value, maxDepth - 1);
+    }
+    return sanitized;
+}
+function sendTelemetry(payload) {
+    if (!isConnected || !ws || ws.readyState !== ws_1.default.OPEN)
+        return;
+    try {
+        ws.send(JSON.stringify(payload));
+    }
+    catch (error) {
+        // Fire and forget, silently ignore send errors
+    }
+}
+function extractLocationFromStack(stack) {
+    if (!stack)
+        return undefined;
+    // The stack will look like:
+    // Error
+    //   at Object.step (/path/to/sdk/index.ts:...)
+    //   at myBusinessLogic (/path/to/business/logic.ts:42:15)
+    const lines = stack.split('\n');
+    if (lines.length >= 3) {
+        const callerLine = lines[2];
+        const match = callerLine.match(/\((.+):(\d+):\d+\)/) || callerLine.match(/at (.+):(\d+):\d+/);
+        if (match && match.length >= 3) {
+            return { file: match[1], line: parseInt(match[2], 10) };
+        }
+    }
+    return undefined;
+}
+exports.evergreen = {
+    clear() {
+        sendTelemetry({ type: 'CLEAR' });
+    },
+    run(jobId, fn) {
+        return traceStorage.run({ jobId }, fn);
+    },
+    async step(name, fn, options) {
+        const store = traceStorage.getStore();
+        // If no context, just execute the function normally without tracing
+        if (!store) {
+            return await fn();
+        }
+        const { jobId, previousStep } = store;
+        // Capture location using a throwaway error
+        const locationError = new Error();
+        const location = extractLocationFromStack(locationError.stack) || { file: 'unknown', line: 0 };
+        const timestamp = Date.now();
+        const startTime = process.hrtime.bigint();
+        // Emit NODE_STARTED
+        sendTelemetry({
+            event: 'NODE_STARTED',
+            status: 'PENDING',
+            jobId,
+            stepName: name,
+            previousStep,
+            location,
+            timestamp
+        });
+        // We must ensure subsequent nested steps know this step is their parent.
+        // To do this, we run the inner function in a nested context.
+        const newContext = { ...store, previousStep: name };
+        try {
+            // Execute the business logic within the new nested context
+            const result = await traceStorage.run(newContext, async () => {
+                return await fn();
+            });
+            const endTime = process.hrtime.bigint();
+            const durationMs = Number(endTime - startTime) / 1000000;
+            // Emit NODE_COMPLETED
+            sendTelemetry({
+                event: 'NODE_COMPLETED',
+                status: 'SUCCESS',
+                jobId,
+                stepName: name,
+                previousStep,
+                payload: { input: sanitizePayload(options?.input), output: sanitizePayload(result) },
+                context: {
+                    input: sanitizePayload(options?.input),
+                    output: sanitizePayload(result),
+                    duration: durationMs
+                },
+                location,
+                timestamp: Date.now()
+            });
+            return result;
+        }
+        catch (error) {
+            const endTime = process.hrtime.bigint();
+            const durationMs = Number(endTime - startTime) / 1000000;
+            // Emit NODE_FAILED
+            sendTelemetry({
+                event: 'NODE_FAILED',
+                status: 'FAILED',
+                jobId,
+                stepName: name,
+                previousStep,
+                payload: { input: sanitizePayload(options?.input), error: sanitizePayload(error) },
+                context: {
+                    input: sanitizePayload(options?.input),
+                    error: sanitizePayload(error),
+                    duration: durationMs
+                },
+                location,
+                timestamp: Date.now()
+            });
+            // Re-throw so backend logic behaves normally
+            throw error;
+        }
+    }
+};
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"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"}

package/src/index.test.ts

@@ -0,0 +1,58 @@
+import { evergreen } from "./index";
+
+// Simple Node-style test (compatible with node --test once compiled)
+// exported for use in dist/index.test.js
+export async function testAlsPropagation() {
+  const events: any[] = [];
+  const originalSend = (evergreen as any).__test__?.sendTelemetry;
+
+  if (originalSend) {
+    (evergreen as any).__test__.sendTelemetry = (payload: any) => {
+      events.push(payload);
+      originalSend(payload);
+    };
+  }
+
+  try {
+    await evergreen.run("job-123", async () => {
+      await evergreen.__autoStep(
+        "outer",
+        { file: "test.ts", line: 1, column: 0 },
+        async () => {
+          await evergreen.__autoStep(
+            "inner",
+            { file: "test.ts", line: 5, column: 0 },
+            async () => 42,
+          );
+        },
+        {},
+      );
+    });
+
+    const started = events.filter((e) => e.event === "NODE_STARTED");
+    const outerStarted = started.find((e) => e.stepName === "outer");
+    const innerStarted = started.find((e) => e.stepName === "inner");
+
+    if (!outerStarted || !innerStarted) {
+      throw new Error("Expected NODE_STARTED events for outer and inner");
+    }
+
+    if (outerStarted.jobId !== "job-123") {
+      throw new Error("outer.jobId mismatch");
+    }
+    if (innerStarted.jobId !== "job-123") {
+      throw new Error("inner.jobId mismatch");
+    }
+    if (outerStarted.previousStep !== undefined) {
+      throw new Error("outer.previousStep should be undefined");
+    }
+    if (innerStarted.previousStep !== "outer") {
+      throw new Error("inner.previousStep should be 'outer'");
+    }
+  } finally {
+    if (originalSend) {
+      (evergreen as any).__test__.sendTelemetry = originalSend;
+    }
+  }
+}
+

package/src/index.ts

@@ -0,0 +1,334 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import WebSocket from "ws";
+
+interface EvergreenContext {
+  jobId: string;
+  previousStep?: string;
+}
+
+interface ApiCallMeta {
+  callee: string;
+  arg0?: string;
+}
+
+interface StepOptions {
+  input?: any;
+  children?: string[];
+  apiCalls?: ApiCallMeta[];
+  __not_async?: boolean;
+}
+
+const traceStorage = new AsyncLocalStorage<EvergreenContext>();
+let ws: WebSocket | null = null;
+let isConnected = false;
+const pendingTelemetry: any[] = [];
+
+// Connect to the VS Code Extension Hub
+function connect() {
+  if (
+    ws &&
+    (ws.readyState === WebSocket.CONNECTING || ws.readyState === WebSocket.OPEN)
+  )
+    return;
+
+  try {
+    ws = new WebSocket("ws://localhost:4321");
+
+    ws.on("open", () => {
+      isConnected = true;
+      // Flush any telemetry that was emitted before the socket became ready.
+      while (pendingTelemetry.length > 0) {
+        const queued = pendingTelemetry.shift();
+        if (queued) {
+          sendTelemetry(queued);
+        }
+      }
+    });
+
+    ws.on("close", () => {
+      isConnected = false;
+      // Optionally implement reconnect logic here
+    });
+
+    ws.on("error", () => {
+      isConnected = false;
+      // Silently fail if extension is not running
+    });
+  } catch (error) {
+    isConnected = false;
+  }
+}
+
+// Ensure connection is attempted
+connect();
+
+function sanitizePayload(obj: any, maxDepth = 3): any {
+  if (maxDepth <= 0) return "[Max Depth Reached]";
+
+  if (obj === null || obj === undefined) return obj;
+  if (typeof obj !== "object") return obj;
+
+  if (obj instanceof Error) {
+    return { name: obj.name, message: obj.message, stack: obj.stack };
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map((item) => sanitizePayload(item, maxDepth - 1));
+  }
+
+  const sanitized: Record<string, any> = {};
+  for (const [key, value] of Object.entries(obj)) {
+    sanitized[key] = sanitizePayload(value, maxDepth - 1);
+  }
+  return sanitized;
+}
+
+function sendTelemetry(payload: any) {
+  console.log("TELEMETRY EMITTED:", payload.stepName, payload.status);
+  if (!ws || ws.readyState !== WebSocket.OPEN) {
+    // Queue messages until the websocket is fully ready instead of dropping them.
+    pendingTelemetry.push(payload);
+    return;
+  }
+
+  try {
+    ws.send(JSON.stringify(payload));
+  } catch (error) {
+    // Fire and forget, silently ignore send errors
+  }
+}
+
+function extractLocationFromStack(
+  stack?: string,
+): { file: string; line: number } | undefined {
+  if (!stack) return undefined;
+
+  // The stack will look like:
+  // Error
+  //   at Object.step (/path/to/sdk/index.ts:...)
+  //   at myBusinessLogic (/path/to/business/logic.ts:42:15)
+
+  const lines = stack.split("\n");
+  if (lines.length >= 3) {
+    const callerLine = lines[2];
+    const match =
+      callerLine.match(/\((.+):(\d+):\d+\)/) ||
+      callerLine.match(/at (.+):(\d+):\d+/);
+    if (match && match.length >= 3) {
+      return { file: match[1], line: parseInt(match[2], 10) };
+    }
+  }
+  return undefined;
+}
+
+export const evergreen = {
+  clear() {
+    sendTelemetry({ type: "CLEAR" });
+  },
+
+  run<T>(jobId: string, fn: () => T): T {
+    return traceStorage.run({ jobId }, fn);
+  },
+
+  async __autoStep<T>(
+    name: string,
+    location: { file: string; line: number; column?: number },
+    fn: () => T | Promise<T>,
+    options?: StepOptions,
+  ): Promise<T> {
+    const store = traceStorage.getStore();
+
+    // If no context, just execute the function normally without tracing
+    if (!store) {
+      return await fn();
+    }
+
+    const { jobId, previousStep } = store;
+
+    const timestamp = Date.now();
+    const startTime = process.hrtime.bigint();
+
+    // Emit NODE_STARTED
+    sendTelemetry({
+      event: "NODE_STARTED",
+      status: "PENDING",
+      jobId,
+      stepName: name,
+      previousStep,
+      location,
+      children: options?.children || [],
+      apiCalls: options?.apiCalls || [],
+      __not_async: options?.__not_async ?? false,
+      timestamp,
+    });
+
+    // We must ensure subsequent nested steps know this step is their parent.
+    // To do this, we run the inner function in a nested context.
+    const newContext = { ...store, previousStep: name };
+
+    try {
+      // Execute the business logic within the new nested context
+      const result = await traceStorage.run(newContext, async () => {
+        return await fn();
+      });
+
+      const endTime = process.hrtime.bigint();
+      const durationMs = Number(endTime - startTime) / 1000000;
+
+      // Emit NODE_COMPLETED
+      sendTelemetry({
+        event: "NODE_COMPLETED",
+        status: "SUCCESS",
+        jobId,
+        stepName: name,
+        previousStep,
+        payload: {
+          input: sanitizePayload(options?.input),
+          output: sanitizePayload(result),
+        },
+        context: {
+          input: sanitizePayload(options?.input),
+          output: sanitizePayload(result),
+          duration: durationMs,
+        },
+        location,
+        // include children and apiCalls again so the UI can still render ghost edges & API badges even if NODE_STARTED was missed
+        children: options?.children || [],
+        apiCalls: options?.apiCalls || [],
+        __not_async: options?.__not_async ?? false,
+        timestamp: Date.now(),
+      });
+
+      return result;
+    } catch (error) {
+      const endTime = process.hrtime.bigint();
+      const durationMs = Number(endTime - startTime) / 1000000;
+
+      // Emit NODE_FAILED
+      sendTelemetry({
+        event: "NODE_FAILED",
+        status: "FAILED",
+        jobId,
+        stepName: name,
+        previousStep,
+        payload: {
+          input: sanitizePayload(options?.input),
+          error: sanitizePayload(error),
+        },
+        context: {
+          input: sanitizePayload(options?.input),
+          error: sanitizePayload(error),
+          duration: durationMs,
+        },
+        location,
+        timestamp: Date.now(),
+      });
+
+      // Re-throw so backend logic behaves normally
+      throw error;
+    }
+  },
+
+  async step<T>(
+    name: string,
+    fn: () => T | Promise<T>,
+    options?: StepOptions,
+  ): Promise<T> {
+    const store = traceStorage.getStore();
+
+    // If no context, just execute the function normally without tracing
+    if (!store) {
+      return await fn();
+    }
+
+    const { jobId, previousStep } = store;
+
+    // Capture location using a throwaway error
+    const locationError = new Error();
+    const location = extractLocationFromStack(locationError.stack) || {
+      file: "unknown",
+      line: 0,
+    };
+    const timestamp = Date.now();
+    const startTime = process.hrtime.bigint();
+
+    // Emit NODE_STARTED
+    sendTelemetry({
+      event: "NODE_STARTED",
+      status: "PENDING",
+      jobId,
+      stepName: name,
+      previousStep,
+      location,
+      timestamp,
+    });
+
+    // We must ensure subsequent nested steps know this step is their parent.
+    // To do this, we run the inner function in a nested context.
+    const newContext = { ...store, previousStep: name };
+
+    try {
+      // Execute the business logic within the new nested context
+      const result = await traceStorage.run(newContext, async () => {
+        return await fn();
+      });
+
+      const endTime = process.hrtime.bigint();
+      const durationMs = Number(endTime - startTime) / 1000000;
+
+      // Emit NODE_COMPLETED
+      sendTelemetry({
+        event: "NODE_COMPLETED",
+        status: "SUCCESS",
+        jobId,
+        stepName: name,
+        previousStep,
+        payload: {
+          input: sanitizePayload(options?.input),
+          output: sanitizePayload(result),
+        },
+        context: {
+          input: sanitizePayload(options?.input),
+          output: sanitizePayload(result),
+          duration: durationMs,
+        },
+        location,
+        timestamp: Date.now(),
+      });
+
+      return result;
+    } catch (error) {
+      const endTime = process.hrtime.bigint();
+      const durationMs = Number(endTime - startTime) / 1000000;
+
+      // Emit NODE_FAILED
+      sendTelemetry({
+        event: "NODE_FAILED",
+        status: "FAILED",
+        jobId,
+        stepName: name,
+        previousStep,
+        payload: {
+          input: sanitizePayload(options?.input),
+          error: sanitizePayload(error),
+        },
+        context: {
+          input: sanitizePayload(options?.input),
+          error: sanitizePayload(error),
+          duration: durationMs,
+        },
+        location,
+        timestamp: Date.now(),
+      });
+
+      // Re-throw so backend logic behaves normally
+      throw error;
+    }
+  },
+};
+
+// Test hooks to allow unit tests to observe telemetry behavior without
+// depending on console output.
+(evergreen as any).__test__ = {
+  sendTelemetry,
+};

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "es2020",
+    "module": "commonjs",
+    "declaration": true,
+    "outDir": "./dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"]
+}