@stigmer/runner 3.0.1

package/src/activities/execute-cursor/__tests__/delta-enricher.test.ts

@@ -0,0 +1,242 @@
+/**
+ * Unit tests for DeltaEnricher status promotion and finalize reconciliation.
+ *
+ * Validates:
+ * - tool-call-completed delta promotes RUNNING -> COMPLETED (FM-2 fix)
+ * - finalize() reconciliation catches orphaned RUNNING tool calls (FM-3 safety net)
+ * - terminal statuses (FAILED, SKIPPED) are never overwritten
+ */
+
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import { AgentMessageSchema, ToolCallSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import type { AgentMessage } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import {
+  MessageType,
+  ToolCallStatus,
+  ToolCallStreamingSource,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { InteractionUpdate } from "@cursor/sdk";
+import { DeltaEnricher } from "../delta-enricher.js";
+
+function makeMessage(toolCalls: Array<{
+  id: string;
+  name: string;
+  status: ToolCallStatus;
+  completedAt?: string;
+  result?: string;
+  isStreaming?: boolean;
+}>): AgentMessage {
+  return create(AgentMessageSchema, {
+    type: MessageType.MESSAGE_AI,
+    content: "test",
+    toolCalls: toolCalls.map((tc) =>
+      create(ToolCallSchema, {
+        id: tc.id,
+        name: tc.name,
+        status: tc.status,
+        completedAt: tc.completedAt ?? "",
+        result: tc.result ?? "",
+        isStreaming: tc.isStreaming ?? false,
+        streamingSource: tc.isStreaming ? ToolCallStreamingSource.OUTPUT : ToolCallStreamingSource.UNSPECIFIED,
+      }),
+    ),
+  });
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("DeltaEnricher tool-call-completed status promotion", () => {
+  it("promotes RUNNING to COMPLETED when tool-call-completed delta arrives", () => {
+    const enricher = new DeltaEnricher();
+    const messages: AgentMessage[] = [
+      makeMessage([{ id: "tc-1", name: "Shell", status: ToolCallStatus.TOOL_CALL_RUNNING }]),
+    ];
+
+    enricher.processDelta({
+      type: "tool-call-completed",
+      callId: "tc-1",
+      toolCall: { type: "shell" },
+    } as unknown as InteractionUpdate);
+
+    enricher.applyEnrichments(messages);
+
+    const tc = messages[0].toolCalls[0];
+    expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
+    expect(tc.completedAt).toBeTruthy();
+  });
+
+  it("does not overwrite COMPLETED status (idempotent)", () => {
+    const enricher = new DeltaEnricher();
+    const messages: AgentMessage[] = [
+      makeMessage([{
+        id: "tc-1",
+        name: "Shell",
+        status: ToolCallStatus.TOOL_CALL_COMPLETED,
+        completedAt: "2026-01-01T00:00:00Z",
+      }]),
+    ];
+
+    enricher.processDelta({
+      type: "tool-call-completed",
+      callId: "tc-1",
+      toolCall: { type: "shell" },
+    } as unknown as InteractionUpdate);
+
+    enricher.applyEnrichments(messages);
+
+    const tc = messages[0].toolCalls[0];
+    expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
+    expect(tc.completedAt).toBe("2026-01-01T00:00:00Z");
+  });
+
+  it("does not overwrite FAILED status (terminal takes precedence)", () => {
+    const enricher = new DeltaEnricher();
+    const messages: AgentMessage[] = [
+      makeMessage([{ id: "tc-1", name: "Shell", status: ToolCallStatus.TOOL_CALL_FAILED }]),
+    ];
+
+    enricher.processDelta({
+      type: "tool-call-completed",
+      callId: "tc-1",
+      toolCall: { type: "shell" },
+    } as unknown as InteractionUpdate);
+
+    enricher.applyEnrichments(messages);
+
+    const tc = messages[0].toolCalls[0];
+    expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_FAILED);
+  });
+
+  it("sets timing on tool-call-started", () => {
+    const enricher = new DeltaEnricher();
+    const messages: AgentMessage[] = [
+      makeMessage([{ id: "tc-1", name: "Shell", status: ToolCallStatus.TOOL_CALL_RUNNING }]),
+    ];
+
+    enricher.processDelta({
+      type: "tool-call-started",
+      callId: "tc-1",
+      toolCall: { type: "shell" },
+    } as unknown as InteractionUpdate);
+
+    enricher.applyEnrichments(messages);
+
+    const tc = messages[0].toolCalls[0];
+    expect(tc.startedAt).toBeTruthy();
+  });
+});
+
+describe("DeltaEnricher finalize reconciliation", () => {
+  it("promotes RUNNING tool call with completedAt to COMPLETED", () => {
+    vi.spyOn(console, "log").mockImplementation(() => {});
+
+    const enricher = new DeltaEnricher();
+    const messages: AgentMessage[] = [
+      makeMessage([{
+        id: "tc-1",
+        name: "Execute Sql",
+        status: ToolCallStatus.TOOL_CALL_RUNNING,
+        completedAt: "2026-01-01T00:00:00Z",
+      }]),
+    ];
+
+    enricher.finalize(messages);
+
+    const tc = messages[0].toolCalls[0];
+    expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
+  });
+
+  it("promotes RUNNING tool call with non-empty result to COMPLETED", () => {
+    vi.spyOn(console, "log").mockImplementation(() => {});
+
+    const enricher = new DeltaEnricher();
+    const messages: AgentMessage[] = [
+      makeMessage([{
+        id: "tc-1",
+        name: "Shell",
+        status: ToolCallStatus.TOOL_CALL_RUNNING,
+        result: "command output here",
+      }]),
+    ];
+
+    enricher.finalize(messages);
+
+    const tc = messages[0].toolCalls[0];
+    expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
+    expect(tc.completedAt).toBeTruthy();
+  });
+
+  it("does not promote PENDING tool call without completion evidence", () => {
+    const enricher = new DeltaEnricher();
+    const messages: AgentMessage[] = [
+      makeMessage([{
+        id: "tc-1",
+        name: "Shell",
+        status: ToolCallStatus.TOOL_CALL_PENDING,
+      }]),
+    ];
+
+    enricher.finalize(messages);
+
+    const tc = messages[0].toolCalls[0];
+    expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_PENDING);
+  });
+
+  it("does not promote RUNNING tool call without any completion evidence", () => {
+    const enricher = new DeltaEnricher();
+    const messages: AgentMessage[] = [
+      makeMessage([{
+        id: "tc-1",
+        name: "Shell",
+        status: ToolCallStatus.TOOL_CALL_RUNNING,
+      }]),
+    ];
+
+    enricher.finalize(messages);
+
+    const tc = messages[0].toolCalls[0];
+    expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_RUNNING);
+  });
+
+  it("clears isStreaming on all tool calls", () => {
+    const enricher = new DeltaEnricher();
+    const messages: AgentMessage[] = [
+      makeMessage([{
+        id: "tc-1",
+        name: "Shell",
+        status: ToolCallStatus.TOOL_CALL_RUNNING,
+        isStreaming: true,
+      }]),
+    ];
+
+    enricher.finalize(messages);
+
+    const tc = messages[0].toolCalls[0];
+    expect(tc.isStreaming).toBe(false);
+    expect(tc.streamingSource).toBe(ToolCallStreamingSource.UNSPECIFIED);
+  });
+
+  it("reconciles tool calls across multiple messages", () => {
+    vi.spyOn(console, "log").mockImplementation(() => {});
+
+    const enricher = new DeltaEnricher();
+    const messages: AgentMessage[] = [
+      makeMessage([
+        { id: "tc-1", name: "Read", status: ToolCallStatus.TOOL_CALL_COMPLETED },
+        { id: "tc-2", name: "Execute Sql", status: ToolCallStatus.TOOL_CALL_RUNNING, result: "rows returned" },
+      ]),
+      makeMessage([
+        { id: "tc-3", name: "Shell", status: ToolCallStatus.TOOL_CALL_RUNNING, completedAt: "2026-01-01T00:00:00Z" },
+      ]),
+    ];
+
+    enricher.finalize(messages);
+
+    expect(messages[0].toolCalls[0].status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
+    expect(messages[0].toolCalls[1].status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
+    expect(messages[1].toolCalls[0].status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
+  });
+});

package/src/activities/execute-cursor/__tests__/error-classifier-introspection.test.ts

@@ -0,0 +1,156 @@
+/**
+ * Tests for the error-classifier introspection sources added alongside the
+ * BiDi-route observability work:
+ *
+ * - `sdkError`: structured fields from a thrown CursorSdkError (top priority)
+ * - `conversationErrorText`: text recovered from the failing run.conversation()
+ *
+ * These ensure a transport/routing failure (e.g. the grpc-status 12 routing bug)
+ * surfaces an actionable message instead of the bare "no detail from SDK".
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { synthesizeError } from "../error-classifier.js";
+
+const FALLBACK = { model: "default", mode: "cloud", agentId: "agent-1" };
+
+function base() {
+  return {
+    sdkResultFields: undefined,
+    streamErrorMessage: undefined,
+    capturedRejection: undefined,
+    isResumedHandle: false,
+    fallbackContext: FALLBACK,
+  } as const;
+}
+
+describe("error-classifier introspection sources", () => {
+  beforeEach(() => {
+    vi.spyOn(console, "log").mockImplementation(() => {});
+  });
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe("sdkError source", () => {
+    it("classifies an 'unavailable' CursorSdkError as retryable network", () => {
+      const result = synthesizeError({
+        ...base(),
+        sdkError: { code: "unavailable", status: 503, message: "service unavailable" },
+      });
+      expect(result.source).toBe("sdk");
+      expect(result.category).toBe("network");
+      expect(result.retryable).toBe(true);
+      expect(result.message).toBe("service unavailable");
+    });
+
+    it("classifies an 'unauthenticated' CursorSdkError as non-retryable auth", () => {
+      const result = synthesizeError({
+        ...base(),
+        sdkError: { code: "unauthenticated", status: 401 },
+      });
+      expect(result.source).toBe("sdk");
+      expect(result.category).toBe("auth");
+      expect(result.retryable).toBe(false);
+    });
+
+    it("classifies from code/status alone when no message is present", () => {
+      const result = synthesizeError({
+        ...base(),
+        sdkError: { code: "resource_exhausted" },
+      });
+      expect(result.source).toBe("sdk");
+      expect(result.category).toBe("rate-limit");
+      expect(result.message).toBe("resource_exhausted");
+    });
+
+    it("ignores an empty sdkError and falls through to the next source", () => {
+      const result = synthesizeError({
+        ...base(),
+        sdkError: {},
+        streamErrorMessage: "fetch failed",
+      });
+      expect(result.source).toBe("stream");
+      expect(result.category).toBe("network");
+    });
+  });
+
+  describe("conversationErrorText source", () => {
+    it("surfaces the conversation error text instead of the generic fallback", () => {
+      const result = synthesizeError({
+        ...base(),
+        conversationErrorText: "Method not found: agent.v1.AgentService/Run (unimplemented)",
+      });
+      expect(result.source).toBe("conversation");
+      expect(result.message).toContain("unimplemented");
+      // Not the bare fallback message.
+      expect(result.message).not.toContain("no detail from SDK");
+    });
+
+    it("classifies a recognizable category from the conversation text", () => {
+      const result = synthesizeError({
+        ...base(),
+        conversationErrorText: "deadline_exceeded while contacting upstream",
+      });
+      expect(result.source).toBe("conversation");
+      expect(result.category).toBe("network");
+      expect(result.retryable).toBe(true);
+    });
+  });
+
+  describe("source precedence", () => {
+    const allSources = {
+      ...base(),
+      sdkError: { code: "unavailable", message: "from-sdk-error" },
+      sdkResultFields: "from-sdk-result network error",
+      streamErrorMessage: "from-stream timeout",
+      capturedRejection: { code: "unavailable", message: "from-rejection", timestamp: Date.now() },
+      conversationErrorText: "from-conversation enotfound",
+    };
+
+    it("prefers the thrown CursorSdkError above all other sources", () => {
+      const result = synthesizeError({ ...allSources });
+      expect(result.source).toBe("sdk");
+      expect(result.message).toBe("from-sdk-error");
+    });
+
+    it("falls to sdkResultFields when sdkError is absent", () => {
+      const result = synthesizeError({ ...allSources, sdkError: undefined });
+      expect(result.source).toBe("sdk");
+      expect(result.message).toBe("from-sdk-result network error");
+    });
+
+    it("falls to the stream message next", () => {
+      const result = synthesizeError({
+        ...allSources,
+        sdkError: undefined,
+        sdkResultFields: undefined,
+      });
+      expect(result.source).toBe("stream");
+      expect(result.message).toBe("from-stream timeout");
+    });
+
+    it("falls to the captured rejection next", () => {
+      const result = synthesizeError({
+        ...allSources,
+        sdkError: undefined,
+        sdkResultFields: undefined,
+        streamErrorMessage: undefined,
+      });
+      expect(result.source).toBe("rejection");
+      expect(result.message).toContain("from-rejection");
+    });
+
+    it("falls to the conversation text last, above the generic fallback", () => {
+      const result = synthesizeError({
+        ...allSources,
+        sdkError: undefined,
+        sdkResultFields: undefined,
+        streamErrorMessage: undefined,
+        capturedRejection: undefined,
+      });
+      expect(result.source).toBe("conversation");
+      expect(result.message).toBe("from-conversation enotfound");
+    });
+  });
+});

package/src/activities/execute-cursor/__tests__/fetch-interceptor.test.ts

@@ -0,0 +1,211 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+
+const PROXY_ENDPOINT = "https://proxy.example.com:9093";
+const STIGMER_TOKEN = "test-stigmer-jwt-token";
+
+interface CapturedCall {
+  url: string;
+  init?: RequestInit;
+}
+
+/**
+ * The fetch interceptor captures globalThis.fetch at module load time as
+ * `originalFetch`. To test it properly, we must install a mock fetch
+ * BEFORE the module loads, then dynamically import it. This ensures the
+ * interceptor delegates to our mock instead of the real network fetch.
+ */
+describe("fetch-interceptor", () => {
+  const realFetch = globalThis.fetch;
+  let calls: CapturedCall[];
+  let installFetchInterceptor: typeof import("../fetch-interceptor.js").installFetchInterceptor;
+  let uninstallFetchInterceptor: typeof import("../fetch-interceptor.js").uninstallFetchInterceptor;
+  let getExecutionContext: typeof import("../fetch-interceptor.js").getExecutionContext;
+
+  beforeEach(async () => {
+    calls = [];
+    const mockResponse = new Response(JSON.stringify({ ok: true }), { status: 200 });
+
+    globalThis.fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+      const url = typeof input === "string"
+        ? input
+        : input instanceof URL
+          ? input.toString()
+          : (input as Request).url;
+      calls.push({ url, init });
+      return mockResponse.clone();
+    }) as typeof fetch;
+
+    // Bust the module cache so originalFetch captures our mock
+    vi.resetModules();
+    const mod = await import("../fetch-interceptor.js");
+    installFetchInterceptor = mod.installFetchInterceptor;
+    uninstallFetchInterceptor = mod.uninstallFetchInterceptor;
+    getExecutionContext = mod.getExecutionContext;
+  });
+
+  afterEach(() => {
+    uninstallFetchInterceptor();
+    globalThis.fetch = realFetch;
+  });
+
+  describe("Connect-RPC paths via fetch (BiDi proxy auth injection)", () => {
+    beforeEach(() => {
+      installFetchInterceptor({ proxyEndpoint: PROXY_ENDPOINT, stigmerToken: STIGMER_TOKEN });
+    });
+
+    it("injects x-stigmer-auth on /aiserver.v1 path targeting proxy endpoint", async () => {
+      await globalThis.fetch(
+        `${PROXY_ENDPOINT}/aiserver.v1.AnalyticsService/BootstrapStatsig`,
+        {
+          method: "POST",
+          headers: {
+            "authorization": "Bearer cursor-access-token",
+            "content-type": "application/json",
+          },
+        },
+      );
+
+      expect(calls).toHaveLength(1);
+      const headers = new Headers(calls[0].init?.headers);
+      expect(headers.get("x-stigmer-auth")).toBe(`Bearer ${STIGMER_TOKEN}`);
+    });
+
+    it("preserves the original authorization header (Cursor access token)", async () => {
+      await globalThis.fetch(
+        `${PROXY_ENDPOINT}/aiserver.v1.AnalyticsService/BootstrapStatsig`,
+        {
+          method: "POST",
+          headers: { "authorization": "Bearer cursor-access-token" },
+        },
+      );
+
+      expect(calls).toHaveLength(1);
+      const headers = new Headers(calls[0].init?.headers);
+      expect(headers.get("authorization")).toBe("Bearer cursor-access-token");
+      expect(headers.get("x-stigmer-auth")).toBe(`Bearer ${STIGMER_TOKEN}`);
+    });
+
+    it("does NOT rewrite the URL for Connect-RPC paths", async () => {
+      const originalUrl = `${PROXY_ENDPOINT}/aiserver.v1.AnalyticsService/BootstrapStatsig`;
+
+      await globalThis.fetch(originalUrl, { method: "POST" });
+
+      expect(calls).toHaveLength(1);
+      expect(calls[0].url).toBe(originalUrl);
+    });
+
+    it("injects x-stigmer-auth on /agent.v1 path targeting proxy endpoint", async () => {
+      await globalThis.fetch(
+        `${PROXY_ENDPOINT}/agent.v1.AgentService/Run`,
+        {
+          method: "POST",
+          headers: { "authorization": "Bearer cursor-token" },
+        },
+      );
+
+      expect(calls).toHaveLength(1);
+      const headers = new Headers(calls[0].init?.headers);
+      expect(headers.get("x-stigmer-auth")).toBe(`Bearer ${STIGMER_TOKEN}`);
+      expect(headers.get("authorization")).toBe("Bearer cursor-token");
+    });
+
+    it("injects x-stigmer-execution-id when execution context is active", async () => {
+      const executionContext = getExecutionContext();
+      await executionContext.run({ executionId: "exec-test-123" }, async () => {
+        await globalThis.fetch(
+          `${PROXY_ENDPOINT}/aiserver.v1.AnalyticsService/LogStatsigEvent`,
+          { method: "POST" },
+        );
+      });
+
+      expect(calls).toHaveLength(1);
+      const headers = new Headers(calls[0].init?.headers);
+      expect(headers.get("x-stigmer-execution-id")).toBe("exec-test-123");
+      expect(headers.get("x-stigmer-auth")).toBe(`Bearer ${STIGMER_TOKEN}`);
+    });
+
+    it("does NOT inject x-stigmer-execution-id when no execution context", async () => {
+      await globalThis.fetch(
+        `${PROXY_ENDPOINT}/aiserver.v1.AnalyticsService/BootstrapStatsig`,
+        { method: "POST" },
+      );
+
+      expect(calls).toHaveLength(1);
+      const headers = new Headers(calls[0].init?.headers);
+      expect(headers.get("x-stigmer-execution-id")).toBeNull();
+      expect(headers.get("x-stigmer-auth")).toBe(`Bearer ${STIGMER_TOKEN}`);
+    });
+  });
+
+  describe("REST path URL rewriting (existing behavior)", () => {
+    beforeEach(() => {
+      installFetchInterceptor({ proxyEndpoint: PROXY_ENDPOINT, stigmerToken: STIGMER_TOKEN });
+    });
+
+    it("rewrites Cursor-domain REST URLs and replaces auth", async () => {
+      await globalThis.fetch(
+        "https://api2.cursor.sh/auth/exchange_user_api_key",
+        {
+          method: "POST",
+          headers: { "authorization": "Bearer original-key" },
+        },
+      );
+
+      expect(calls).toHaveLength(1);
+      expect(calls[0].url).toBe(
+        `${PROXY_ENDPOINT}/v1/proxy/cursor/api2.cursor.sh/auth/exchange_user_api_key`,
+      );
+      const headers = new Headers(calls[0].init?.headers);
+      expect(headers.get("authorization")).toBe(`Bearer ${STIGMER_TOKEN}`);
+      expect(headers.get("x-stigmer-auth")).toBeNull();
+    });
+
+    it("rewrites proxy-endpoint REST paths (non-Connect-RPC)", async () => {
+      await globalThis.fetch(
+        `${PROXY_ENDPOINT}/auth/exchange_user_api_key`,
+        { method: "POST" },
+      );
+
+      expect(calls).toHaveLength(1);
+      expect(calls[0].url).toContain("/v1/proxy/cursor/api2.cursor.sh/auth/");
+    });
+  });
+
+  describe("passthrough (no interception)", () => {
+    beforeEach(() => {
+      installFetchInterceptor({ proxyEndpoint: PROXY_ENDPOINT, stigmerToken: STIGMER_TOKEN });
+    });
+
+    it("does NOT intercept Connect-RPC paths on non-proxy hosts", async () => {
+      const url = "https://other-host.example.com/aiserver.v1.AnalyticsService/BootstrapStatsig";
+
+      await globalThis.fetch(url, {
+        method: "POST",
+        headers: { "authorization": "Bearer some-token" },
+      });
+
+      expect(calls).toHaveLength(1);
+      expect(calls[0].url).toBe(url);
+      const headers = new Headers(calls[0].init?.headers);
+      expect(headers.get("x-stigmer-auth")).toBeNull();
+    });
+
+    it("does NOT intercept already-rewritten /v1/proxy/ paths", async () => {
+      const url = `${PROXY_ENDPOINT}/v1/proxy/cursor/api.cursor.com/v1/models`;
+
+      await globalThis.fetch(url, { method: "GET" });
+
+      expect(calls).toHaveLength(1);
+      expect(calls[0].url).toBe(url);
+    });
+
+    it("does NOT intercept non-Cursor, non-proxy requests", async () => {
+      const url = "https://api.openai.com/v1/chat/completions";
+
+      await globalThis.fetch(url, { method: "POST" });
+
+      expect(calls).toHaveLength(1);
+      expect(calls[0].url).toBe(url);
+    });
+  });
+});