@stigmer/runner 3.0.1

package/src/notification/__tests__/provider.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import {
+  registerProvider,
+  getProvider,
+  resetProviders,
+  type NotificationProvider,
+  type NotificationRequest,
+  type NotificationResult,
+} from "../provider.js";
+
+class StubProvider implements NotificationProvider {
+  channel(): string { return "stub"; }
+  async send(req: NotificationRequest): Promise<NotificationResult> {
+    return {
+      channel: "stub",
+      recipients: [...req.recipients],
+      delivered: true,
+      delivered_at: new Date().toISOString(),
+    };
+  }
+}
+
+describe("NotificationProviderRegistry", () => {
+  beforeEach(() => {
+    resetProviders();
+  });
+
+  it("registers and retrieves a provider by channel name", () => {
+    registerProvider(new StubProvider());
+    const provider = getProvider("stub");
+    expect(provider.channel()).toBe("stub");
+  });
+
+  it("throws when requesting an unregistered channel", () => {
+    expect(() => getProvider("slack")).toThrow(
+      "Notification channel 'slack' is not implemented",
+    );
+  });
+
+  it("lists available channels in the error message", () => {
+    registerProvider(new StubProvider());
+    expect(() => getProvider("email")).toThrow("available channels: stub");
+  });
+
+  it("shows (none) when no providers are registered", () => {
+    expect(() => getProvider("webhook")).toThrow("available channels: (none)");
+  });
+
+  it("overwrites a provider for the same channel on re-registration", async () => {
+    let callCount = 0;
+    const v1: NotificationProvider = {
+      channel: () => "stub",
+      send: async (req) => {
+        callCount = 1;
+        return { channel: "stub", recipients: [...req.recipients], delivered: true };
+      },
+    };
+    const v2: NotificationProvider = {
+      channel: () => "stub",
+      send: async (req) => {
+        callCount = 2;
+        return { channel: "stub", recipients: [...req.recipients], delivered: true };
+      },
+    };
+
+    registerProvider(v1);
+    registerProvider(v2);
+
+    await getProvider("stub").send({
+      channel: "stub",
+      recipients: ["http://example.com"],
+      subject: "",
+      body: "test",
+      metadata: {},
+    });
+
+    expect(callCount).toBe(2);
+  });
+
+  it("resetProviders clears all registrations", () => {
+    registerProvider(new StubProvider());
+    resetProviders();
+    expect(() => getProvider("stub")).toThrow("is not implemented");
+  });
+});

package/src/notification/__tests__/webhook.test.ts

@@ -0,0 +1,127 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { WebhookProvider } from "../webhook.js";
+import type { NotificationRequest } from "../provider.js";
+
+function makeRequest(overrides?: Partial<NotificationRequest>): NotificationRequest {
+  return {
+    channel: "webhook",
+    recipients: ["https://hooks.example.com/notify"],
+    subject: "Test Subject",
+    body: "Test body message",
+    metadata: { priority: "high" },
+    ...overrides,
+  };
+}
+
+describe("WebhookProvider", () => {
+  const provider = new WebhookProvider();
+  const originalFetch = globalThis.fetch;
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  it("returns channel name 'webhook'", () => {
+    expect(provider.channel()).toBe("webhook");
+  });
+
+  it("sends JSON POST to each recipient URL on success", async () => {
+    const fetchSpy = vi.fn(() =>
+      Promise.resolve(new Response(null, { status: 200 })),
+    );
+    globalThis.fetch = fetchSpy as any;
+
+    const result = await provider.send(makeRequest({
+      recipients: ["https://a.com/hook", "https://b.com/hook"],
+    }));
+
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+    expect(result.delivered).toBe(true);
+    expect(result.delivered_at).toBeDefined();
+    expect(result.channel).toBe("webhook");
+    expect(result.recipients).toEqual(["https://a.com/hook", "https://b.com/hook"]);
+
+    const call = fetchSpy.mock.calls[0] as unknown as [string, RequestInit];
+    expect(call[0]).toBe("https://a.com/hook");
+    expect(call[1].method).toBe("POST");
+    expect((call[1].headers as Record<string, string>)["Content-Type"]).toBe("application/json");
+    const body = JSON.parse(call[1].body as string);
+    expect(body.subject).toBe("Test Subject");
+    expect(body.body).toBe("Test body message");
+    expect(body.metadata).toEqual({ priority: "high" });
+  });
+
+  it("returns delivered=false with error on HTTP 4xx", async () => {
+    globalThis.fetch = vi.fn(() =>
+      Promise.resolve(new Response(null, { status: 400 })),
+    ) as any;
+
+    const result = await provider.send(makeRequest());
+
+    expect(result.delivered).toBe(false);
+    expect(result.error).toContain("returned status 400");
+  });
+
+  it("returns delivered=false with error on HTTP 5xx", async () => {
+    globalThis.fetch = vi.fn(() =>
+      Promise.resolve(new Response(null, { status: 502 })),
+    ) as any;
+
+    const result = await provider.send(makeRequest());
+
+    expect(result.delivered).toBe(false);
+    expect(result.error).toContain("returned status 502");
+  });
+
+  it("returns delivered=false with error on network failure", async () => {
+    globalThis.fetch = vi.fn(() =>
+      Promise.reject(new Error("ECONNREFUSED")),
+    ) as any;
+
+    const result = await provider.send(makeRequest());
+
+    expect(result.delivered).toBe(false);
+    expect(result.error).toContain("Webhook delivery to");
+    expect(result.error).toContain("ECONNREFUSED");
+  });
+
+  it("stops on first failing recipient and reports the error", async () => {
+    const fetchSpy = vi.fn()
+      .mockResolvedValueOnce(new Response(null, { status: 200 }))
+      .mockResolvedValueOnce(new Response(null, { status: 500 }));
+    globalThis.fetch = fetchSpy as any;
+
+    const result = await provider.send(makeRequest({
+      recipients: ["https://ok.com", "https://fail.com"],
+    }));
+
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+    expect(result.delivered).toBe(false);
+    expect(result.error).toContain("fail.com");
+  });
+
+  it("sends correct JSON payload shape", async () => {
+    let capturedBody: string | undefined;
+    globalThis.fetch = vi.fn((_, opts) => {
+      capturedBody = (opts as any).body;
+      return Promise.resolve(new Response(null, { status: 200 }));
+    }) as any;
+
+    await provider.send(makeRequest({
+      subject: "Alert",
+      body: "Server down",
+      metadata: { env: "prod" },
+    }));
+
+    const parsed = JSON.parse(capturedBody!);
+    expect(parsed).toEqual({
+      subject: "Alert",
+      body: "Server down",
+      metadata: { env: "prod" },
+    });
+  });
+});

package/src/notification/index.ts

@@ -0,0 +1,15 @@
+export {
+  type NotificationProvider,
+  type NotificationRequest,
+  type NotificationResult,
+  registerProvider,
+  getProvider,
+  resetProviders,
+} from "./provider.js";
+
+export { WebhookProvider } from "./webhook.js";
+
+import { registerProvider } from "./provider.js";
+import { WebhookProvider } from "./webhook.js";
+
+registerProvider(new WebhookProvider());

package/src/notification/provider.ts

@@ -0,0 +1,52 @@
+/**
+ * Notification provider registry.
+ *
+ * Channels are string identifiers (not an enum) for extensibility —
+ * new channels can be added without code changes beyond implementing
+ * the Provider interface and calling registerProvider().
+ */
+
+export interface NotificationRequest {
+  readonly channel: string;
+  readonly recipients: readonly string[];
+  readonly subject: string;
+  readonly body: string;
+  readonly template?: string;
+  readonly metadata: Readonly<Record<string, string>>;
+}
+
+export interface NotificationResult {
+  readonly channel: string;
+  readonly recipients: readonly string[];
+  readonly delivered: boolean;
+  readonly delivered_at?: string;
+  readonly error?: string;
+}
+
+export interface NotificationProvider {
+  channel(): string;
+  send(request: NotificationRequest): Promise<NotificationResult>;
+}
+
+const providers = new Map<string, NotificationProvider>();
+
+export function registerProvider(provider: NotificationProvider): void {
+  providers.set(provider.channel(), provider);
+}
+
+export function getProvider(channel: string): NotificationProvider {
+  const provider = providers.get(channel);
+  if (!provider) {
+    const available = providers.size > 0
+      ? Array.from(providers.keys()).join(", ")
+      : "(none)";
+    throw new Error(
+      `Notification channel '${channel}' is not implemented; available channels: ${available}`,
+    );
+  }
+  return provider;
+}
+
+export function resetProviders(): void {
+  providers.clear();
+}

package/src/notification/webhook.ts

@@ -0,0 +1,61 @@
+/**
+ * Webhook notification provider — delivers notifications via HTTP POST.
+ *
+ * Each recipient is treated as a URL. The notification body is sent as
+ * a JSON payload: { subject, body, metadata }. Delivery is best-effort:
+ * HTTP errors or network failures produce a result with delivered=false
+ * rather than throwing, matching Go's non-fatal delivery semantics.
+ */
+
+import type { NotificationProvider, NotificationRequest, NotificationResult } from "./provider.js";
+
+const WEBHOOK_TIMEOUT_MS = 30_000;
+
+export class WebhookProvider implements NotificationProvider {
+  channel(): string {
+    return "webhook";
+  }
+
+  async send(request: NotificationRequest): Promise<NotificationResult> {
+    const payload = JSON.stringify({
+      subject: request.subject,
+      body: request.body,
+      metadata: request.metadata,
+    });
+
+    for (const url of request.recipients) {
+      try {
+        const response = await fetch(url, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: payload,
+          signal: AbortSignal.timeout(WEBHOOK_TIMEOUT_MS),
+        });
+
+        if (response.status >= 400) {
+          return {
+            channel: "webhook",
+            recipients: [...request.recipients],
+            delivered: false,
+            error: `Webhook ${url} returned status ${response.status}`,
+          };
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          channel: "webhook",
+          recipients: [...request.recipients],
+          delivered: false,
+          error: `Webhook delivery to ${url} failed: ${message}`,
+        };
+      }
+    }
+
+    return {
+      channel: "webhook",
+      recipients: [...request.recipients],
+      delivered: true,
+      delivered_at: new Date().toISOString(),
+    };
+  }
+}

package/src/otel-metrics.ts

@@ -0,0 +1,73 @@
+/**
+ * OTel metric instrument registry for the unified runner.
+ *
+ * Matches Go workflow-runner's `pkg/otel/metrics.go` instrument names.
+ * All instruments are created lazily on first access. When no
+ * MeterProvider is configured, they are no-ops (OTel global fallback).
+ */
+
+import type { Counter, Histogram, UpDownCounter } from "@opentelemetry/api";
+
+const METER_NAME = "stigmer-runner";
+
+export interface RunnerInstruments {
+  readonly executionCount: Counter;
+  readonly executionActive: UpDownCounter;
+  readonly activityDuration: Histogram;
+  readonly workflowTaskDuration: Histogram;
+  readonly workflowTaskCount: Counter;
+  readonly llmCallDuration: Histogram;
+  readonly llmCallCount: Counter;
+  readonly llmTokensInput: Counter;
+  readonly llmTokensOutput: Counter;
+}
+
+let instruments: RunnerInstruments | null = null;
+
+export async function getInstruments(): Promise<RunnerInstruments> {
+  if (instruments) return instruments;
+
+  const api = await import("@opentelemetry/api");
+  const meter = api.metrics.getMeter(METER_NAME);
+
+  instruments = {
+    executionCount: meter.createCounter("stigmer.execution.count", {
+      description: "Total number of workflow executions started",
+    }),
+    executionActive: meter.createUpDownCounter("stigmer.execution.active", {
+      description: "Currently active workflow executions",
+    }),
+    activityDuration: meter.createHistogram("stigmer.activity.duration", {
+      unit: "ms",
+      description: "Duration of Temporal activities in milliseconds",
+    }),
+    workflowTaskDuration: meter.createHistogram("stigmer.workflow.task.duration", {
+      unit: "ms",
+      description: "Duration of individual workflow tasks in milliseconds",
+    }),
+    workflowTaskCount: meter.createCounter("stigmer.workflow.task.count", {
+      description: "Total number of workflow tasks executed",
+    }),
+    llmCallDuration: meter.createHistogram("stigmer.llm.call.duration", {
+      unit: "ms",
+      description: "Duration of LLM API calls in milliseconds",
+    }),
+    llmCallCount: meter.createCounter("stigmer.llm.call.count", {
+      description: "Total number of LLM API calls",
+    }),
+    llmTokensInput: meter.createCounter("stigmer.llm.tokens.input", {
+      unit: "{token}",
+      description: "Total input tokens consumed across LLM calls",
+    }),
+    llmTokensOutput: meter.createCounter("stigmer.llm.tokens.output", {
+      unit: "{token}",
+      description: "Total output tokens produced across LLM calls",
+    }),
+  };
+
+  return instruments;
+}
+
+export function resetInstruments(): void {
+  instruments = null;
+}

package/src/otel.ts

@@ -0,0 +1,194 @@
+/**
+ * OpenTelemetry tracing and metrics initialization.
+ *
+ * Env-var-driven: reads OTEL_EXPORTER_OTLP_ENDPOINT and configures an
+ * OTLP/gRPC exporter with W3C TraceContext + Baggage propagation. When
+ * the env var is unset, returns null — zero overhead.
+ */
+
+export async function initTracing(serviceName: string): Promise<(() => Promise<void>) | null> {
+  const endpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+  if (!endpoint) {
+    return null;
+  }
+
+  const { NodeTracerProvider } = await import("@opentelemetry/sdk-trace-node");
+  const { BatchSpanProcessor } = await import("@opentelemetry/sdk-trace-base");
+  const { OTLPTraceExporter } = await import("@opentelemetry/exporter-trace-otlp-grpc");
+  const { resourceFromAttributes } = await import("@opentelemetry/resources");
+  const { W3CTraceContextPropagator, CompositePropagator, W3CBaggagePropagator } = await import("@opentelemetry/core");
+  const otelApi = await import("@opentelemetry/api");
+
+  const resource = resourceFromAttributes({ "service.name": serviceName });
+  const exporter = new OTLPTraceExporter({ url: endpoint });
+  const provider = new NodeTracerProvider({
+    resource,
+    spanProcessors: [new BatchSpanProcessor(exporter)],
+  });
+  provider.register();
+
+  otelApi.propagation.setGlobalPropagator(
+    new CompositePropagator({
+      propagators: [new W3CTraceContextPropagator(), new W3CBaggagePropagator()],
+    }),
+  );
+
+  console.log(`OTel tracing enabled (endpoint=${endpoint}, service=${serviceName})`);
+
+  return async () => {
+    await provider.shutdown();
+  };
+}
+
+export async function initMetrics(serviceName: string): Promise<(() => Promise<void>) | null> {
+  const endpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+  if (!endpoint) {
+    return null;
+  }
+
+  const { MeterProvider, PeriodicExportingMetricReader } = await import("@opentelemetry/sdk-metrics");
+  const { OTLPMetricExporter } = await import("@opentelemetry/exporter-metrics-otlp-grpc");
+  const { resourceFromAttributes } = await import("@opentelemetry/resources");
+  const otelApi = await import("@opentelemetry/api");
+
+  const resource = resourceFromAttributes({ "service.name": serviceName });
+  const exporter = new OTLPMetricExporter({ url: endpoint });
+  const reader = new PeriodicExportingMetricReader({
+    exporter,
+    exportIntervalMillis: 30_000,
+  });
+  const provider = new MeterProvider({ resource, readers: [reader] });
+
+  otelApi.metrics.setGlobalMeterProvider(provider);
+
+  console.log(`OTel metrics enabled (endpoint=${endpoint}, service=${serviceName})`);
+
+  return async () => {
+    await provider.shutdown();
+  };
+}
+
+// Span names — shared across all Stigmer runners (Go, Python, TypeScript)
+export const SPAN_CURSOR_TURN = "stigmer.cursor.turn";
+export const SPAN_DEEP_AGENT_RUN = "stigmer.deepagent.run";
+export const SPAN_LLM_CALL = "stigmer.llm.call";
+export const SPAN_LLM_EVAL = "stigmer.llm.eval";
+export const SPAN_MCP_TOOL = "stigmer.mcp.tool_call";
+export const SPAN_WORKFLOW_EXECUTE = "stigmer.workflow.execute";
+export const SPAN_WORKFLOW_TASK = "stigmer.workflow.task";
+
+// Attribute keys — LLM
+export const ATTR_LLM_PROVIDER = "stigmer.llm.provider";
+export const ATTR_LLM_MODEL = "stigmer.llm.model";
+export const ATTR_LLM_PROXY_ACTIVE = "stigmer.llm.proxy_active";
+export const ATTR_LLM_INPUT_TOKENS = "stigmer.llm.input_tokens";
+export const ATTR_LLM_OUTPUT_TOKENS = "stigmer.llm.output_tokens";
+
+// Attribute keys — Cursor/harness
+export const ATTR_CURSOR_MODE = "stigmer.cursor.mode";
+export const ATTR_CURSOR_MODEL = "stigmer.cursor.model";
+export const ATTR_SESSION_ID = "stigmer.session.id";
+export const ATTR_HARNESS = "stigmer.harness";
+
+// Attribute keys — MCP
+export const ATTR_MCP_TOOL_NAME = "stigmer.mcp.tool_name";
+export const ATTR_MCP_SERVER_NAME = "stigmer.mcp.server_name";
+export const ATTR_MCP_SERVER_ID = "stigmer.mcp.server_id";
+
+// Attribute keys — Workflow
+export const ATTR_WORKFLOW_EXECUTION_ID = "stigmer.workflow.execution_id";
+export const ATTR_WORKFLOW_NAME = "stigmer.workflow.name";
+export const ATTR_TASK_NAME = "stigmer.workflow.task.name";
+export const ATTR_TASK_KIND = "stigmer.workflow.task.kind";
+
+// Baggage keys — propagated through W3C baggage headers
+export const BAGGAGE_EXECUTION_ID = "stigmer.execution_id";
+export const BAGGAGE_SESSION_ID = "stigmer.session_id";
+export const BAGGAGE_ORG_ID = "stigmer.org_id";
+
+/**
+ * Start a cursor turn span. No-op when tracing is not initialized.
+ */
+export async function startCursorTurnSpan(attrs: {
+  model: string;
+  mode: string;
+  sessionId: string;
+}): Promise<{ setTokens(input: number, output: number): void; end(): void }> {
+  const noop = { setTokens() {}, end() {} };
+  try {
+    const otelApi = await import("@opentelemetry/api");
+    const tracer = otelApi.trace.getTracer("stigmer-runner");
+    const span = tracer.startSpan(SPAN_CURSOR_TURN, {
+      attributes: {
+        [ATTR_CURSOR_MODEL]: attrs.model,
+        [ATTR_CURSOR_MODE]: attrs.mode,
+        [ATTR_SESSION_ID]: attrs.sessionId,
+      },
+    });
+    return {
+      setTokens(input: number, output: number) {
+        if (input) span.setAttribute(ATTR_LLM_INPUT_TOKENS, input);
+        if (output) span.setAttribute(ATTR_LLM_OUTPUT_TOKENS, output);
+      },
+      end() {
+        span.end();
+      },
+    };
+  } catch {
+    return noop;
+  }
+}
+
+/**
+ * Record cursor turn metrics. No-op when metrics are not initialized.
+ */
+export async function recordTurnMetrics(opts: {
+  durationMs: number;
+  inputTokens: number;
+  outputTokens: number;
+  model: string;
+  mode: string;
+}): Promise<void> {
+  try {
+    const otelApi = await import("@opentelemetry/api");
+    const meter = otelApi.metrics.getMeter("stigmer-runner");
+
+    const attrs = {
+      [ATTR_CURSOR_MODEL]: opts.model,
+      [ATTR_CURSOR_MODE]: opts.mode,
+    };
+
+    meter.createHistogram("stigmer.llm.call.duration", { unit: "ms" })
+      .record(opts.durationMs, attrs);
+    meter.createCounter("stigmer.llm.call.count")
+      .add(1, attrs);
+
+    if (opts.inputTokens) {
+      meter.createCounter("stigmer.llm.tokens.input", { unit: "{token}" })
+        .add(opts.inputTokens, attrs);
+    }
+    if (opts.outputTokens) {
+      meter.createCounter("stigmer.llm.tokens.output", { unit: "{token}" })
+        .add(opts.outputTokens, attrs);
+    }
+  } catch {
+    // Metrics not initialized — silently skip.
+  }
+}
+
+export async function setBaggage(items: Record<string, string>): Promise<void> {
+  try {
+    const otelApi = await import("@opentelemetry/api");
+    const ctx = otelApi.context.active();
+    let bag = otelApi.propagation.getBaggage(ctx) ?? otelApi.propagation.createBaggage();
+    for (const [k, v] of Object.entries(items)) {
+      if (v) {
+        bag = bag.setEntry(k, { value: v });
+      }
+    }
+    const newCtx = otelApi.propagation.setBaggage(ctx, bag);
+    otelApi.context.with(newCtx, () => {});
+  } catch {
+    // Tracing not initialized — silently skip.
+  }
+}