@stigmer/runner 3.1.5 → 3.1.7

package/src/activities/execute-cursor/workspace-provision.ts

@@ -10,18 +10,38 @@
 import type { Config } from "../../config.js";
 import type { Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
 import { WorkspaceProvisioner } from "../../shared/workspace/provisioner.js";
+import type { ProvisionResult, WorkspaceBackend } from "../../shared/workspace/types.js";
 import { LocalWorkspaceBackend } from "../../shared/workspace/local-backend.js";
 import { ensurePlatformDir } from "../../shared/workspace/platform-dir.js";
 import { resolveSessionWorkspaceRoot } from "../../shared/workspace/session-root.js";
 
+/** What {@link provisionCursorWorkspace} hands back to the harness. */
+export interface CursorWorkspaceProvision {
+  /** The directories the agent should operate in (never empty). */
+  readonly workspaceDirs: string[];
+  /**
+   * Per-entry provision outcomes — carries the git metadata (repo URL, base
+   * branch, credential state) the write-back coordinator needs. Empty for a
+   * session with no workspace entries.
+   */
+  readonly provisionResults: ProvisionResult[];
+  /**
+   * The backend the entries were provisioned through — the write-back
+   * coordinator executes its git commands through it.
+   */
+  readonly workspaceBackend: WorkspaceBackend;
+}
+
 /**
  * Provision the session's workspace entries for a LOCAL Cursor agent.
  *
  * Clones git-repo entries (using the user's GITHUB_TOKEN from the resolved
  * execution environment) and mounts local-path entries, then returns the
- * directories the agent should operate in. A session with no workspace
- * entries gets its own empty per-session directory (see session-root.ts) —
- * never the shared root, which would leak other sessions' files into it.
+ * directories the agent should operate in — along with the provision results
+ * and backend the git write-back coordinator needs. A session with no
+ * workspace entries gets its own empty per-session directory (see
+ * session-root.ts) — never the shared root, which would leak other sessions'
+ * files into it.
  *
  * provisionGit is idempotent (it reuses an existing clone), so this is safe
  * to call on every execution, including multi-turn and HITL reinvocations.
@@ -31,13 +51,21 @@ export async function provisionCursorWorkspace(
   session: Session,
   envVars: Record<string, string>,
   sessionId: string,
-): Promise<string[]> {
+): Promise<CursorWorkspaceProvision> {
   const entries = session.spec?.workspaceEntries ?? [];
+  const platformDir = await ensurePlatformDir(sessionId);
+
   if (entries.length === 0) {
-    return [await resolveSessionWorkspaceRoot(config.workspaceRootDir, entries, sessionId)];
+    const sessionRoot = await resolveSessionWorkspaceRoot(
+      config.workspaceRootDir, entries, sessionId,
+    );
+    return {
+      workspaceDirs: [sessionRoot],
+      provisionResults: [],
+      workspaceBackend: new LocalWorkspaceBackend(sessionRoot, platformDir),
+    };
   }
 
-  const platformDir = await ensurePlatformDir(sessionId);
   const backend = new LocalWorkspaceBackend(config.workspaceRootDir, platformDir);
 
   const provisioner = new WorkspaceProvisioner();
@@ -53,5 +81,9 @@ export async function provisionCursorWorkspace(
     .map((result) => result.rootDir)
     .filter((dir): dir is string => Boolean(dir));
 
-  return dirs.length > 0 ? dirs : [config.workspaceRootDir];
+  return {
+    workspaceDirs: dirs.length > 0 ? dirs : [config.workspaceRootDir],
+    provisionResults: results,
+    workspaceBackend: backend,
+  };
 }

package/src/activities/execute-deep-agent/__tests__/post-stream.test.ts

@@ -3,7 +3,7 @@ import { create } from "@bufbuild/protobuf";
 import { AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import { processPostStream } from "../post-stream.js";
 import type { InlinePublisher } from "../inline-publisher.js";
-import type { WriteBackCoordinator } from "../writeback-coordinator.js";
+import type { WriteBackCoordinator } from "../../../shared/workspace/writeback-coordinator.js";
 
 function mockInlinePublisher(): InlinePublisher {
   return {

package/src/activities/execute-deep-agent/index.ts

@@ -45,7 +45,7 @@ import { streamExecution, type StreamResult } from "./streaming.js";
 import { loadStreamingConfig } from "../../shared/streaming-scheduler.js";
 import { StatusBuilder } from "./status-builder.js";
 import { InlinePublisher } from "./inline-publisher.js";
-import { WriteBackCoordinator } from "./writeback-coordinator.js";
+import { WriteBackCoordinator } from "../../shared/workspace/writeback-coordinator.js";
 import { processPostStream } from "./post-stream.js";
 import { resolveResumeInput, type GraphStateSnapshot } from "./hitl.js";
 import { captureApprovalArtifacts } from "./approval-file-change.js";
@@ -184,6 +184,13 @@ export function createDeepAgentActivities(config: Config) {
           ? new WriteBackCoordinator({
               statusWriter: statusBuilder,
               executionId,
+              // Branch/PR are session-scoped: every turn of this session
+              // appends commits to the same stigmer/<session-id> branch.
+              sessionId: setup.session.metadata?.id ?? "",
+              // The PR API token, plumbed from the resolved execution env —
+              // gitMetadata.repoUrl is token-stripped by construction, so the
+              // coordinator can never recover it from provisioning state.
+              githubToken: setup.mergedEnvVars.GITHUB_TOKEN ?? "",
               provisionResults: setup.provisionResults,
               workspaceEntries: workspaceEntries as any,
               workspaceBackend: setup.workspaceBackend,

package/src/activities/execute-deep-agent/inline-publisher.ts

@@ -20,7 +20,7 @@ import {
 } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import type { ArtifactStorage } from "../../shared/artifact-storage.js";
 import type { WorkspaceBackend } from "../../shared/workspace/types.js";
-import type { ExecutionStatusWriter } from "./execution-status-writer.js";
+import type { ExecutionStatusWriter } from "../../shared/execution-status-writer.js";
 import { utcTimestamp } from "../../shared/status.js";
 import { isSecretLikePath } from "../../shared/filereview/secret-paths.js";
 

package/src/activities/execute-deep-agent/post-stream.ts

@@ -13,7 +13,7 @@
 import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import type { InlinePublisher } from "./inline-publisher.js";
-import type { WriteBackCoordinator } from "./writeback-coordinator.js";
+import type { WriteBackCoordinator } from "../../shared/workspace/writeback-coordinator.js";
 import { autoPublishWrittenFiles } from "./auto-publish.js";
 
 export interface PostStreamOptions {

package/src/activities/execute-deep-agent/status-builder.ts

@@ -31,7 +31,7 @@ import { classifyTool } from "../../shared/tool-kind.js";
 import { applyTodoUpdate } from "../../shared/todos.js";
 import { ExecutionState } from "./execution-state.js";
 import { utcTimestamp } from "../../shared/status.js";
-import type { ExecutionStatusWriter } from "./execution-status-writer.js";
+import type { ExecutionStatusWriter } from "../../shared/execution-status-writer.js";
 import {
   UsageAccumulator,
   extractToolResult,

package/src/activities/execute-deep-agent/streaming-side-effects.ts

@@ -8,7 +8,7 @@
 
 import type { V3ProtocolEvent } from "./v3-event-recorder.js";
 import type { InlinePublisher } from "./inline-publisher.js";
-import type { WriteBackCoordinator } from "./writeback-coordinator.js";
+import type { WriteBackCoordinator } from "../../shared/workspace/writeback-coordinator.js";
 import { extractFilePath, isFileModifyingTool } from "../../shared/file-tools.js";
 
 interface CachedToolInput {

package/src/activities/execute-deep-agent/streaming-terminal.ts

@@ -8,7 +8,7 @@
 import { create } from "@bufbuild/protobuf";
 import { AgentMessageSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
 import { ExecutionPhase, MessageType } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
-import type { ExecutionStatusWriter } from "./execution-status-writer.js";
+import type { ExecutionStatusWriter } from "../../shared/execution-status-writer.js";
 import type { StreamResult } from "./streaming.js";
 import { slimStatus, utcTimestamp } from "../../shared/status.js";
 

package/src/activities/execute-deep-agent/streaming.ts

@@ -39,7 +39,7 @@ import type { ToolOutputOffloadContext } from "../../shared/status-offload.js";
 import type { StigmerClient } from "../../client/stigmer-client.js";
 import type { GracefulStopMiddleware } from "../../middleware/index.js";
 import type { InlinePublisher } from "./inline-publisher.js";
-import type { WriteBackCoordinator } from "./writeback-coordinator.js";
+import type { WriteBackCoordinator } from "../../shared/workspace/writeback-coordinator.js";
 import { createV2EventRecorder } from "./event-recorder.js";
 import { streamExecutionV3 } from "./streaming-v3.js";
 import { extractFilePath, isFileModifyingTool } from "../../shared/file-tools.js";

package/src/activities/execute-deep-agent/v3-status-builder.ts

@@ -30,7 +30,7 @@ import { classifyTool } from "../../shared/tool-kind.js";
 import { applyTodoUpdate } from "../../shared/todos.js";
 import { ExecutionState } from "./execution-state.js";
 import { utcTimestamp } from "../../shared/status.js";
-import type { ExecutionStatusWriter } from "./execution-status-writer.js";
+import type { ExecutionStatusWriter } from "../../shared/execution-status-writer.js";
 import type { ApprovalPolicyProvider } from "./status-builder.js";
 import type { StigmerRunEvent, V3UsagePayload } from "./v3-events.js";
 import { namespaceDepth } from "./v3-events.js";

package/src/shared/__tests__/mcp-oauth-detect.test.ts

@@ -0,0 +1,147 @@
+/**
+ * Unit tests for the HTTP MCP OAuth-challenge classifier.
+ *
+ * Verifies that `detectOAuthChallenge` recognizes a real MCP OAuth challenge
+ * (401 + `WWW-Authenticate: Bearer ...` per RFC 9728), and does NOT misfire on
+ * a plain invalid-token 401, a success, a non-OAuth error, or a network fault —
+ * so it can only ever turn an opaque failure into a clearer one, never mask a
+ * different cause.
+ */
+
+import { afterEach, describe, it, expect, vi } from "vitest";
+import {
+  OAuthRequiredError,
+  detectOAuthChallenge,
+  isOAuthChallenge,
+  parseResourceMetadataUrl,
+} from "../mcp-oauth-detect.js";
+
+function mockFetchOnce(response: {
+  status: number;
+  wwwAuthenticate?: string;
+}): void {
+  const headers = new Headers();
+  if (response.wwwAuthenticate !== undefined) {
+    headers.set("www-authenticate", response.wwwAuthenticate);
+  }
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async () =>
+      new Response(null, { status: response.status, headers }),
+    ),
+  );
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+describe("isOAuthChallenge", () => {
+  it("matches the MCP auth spec Bearer + OAuth realm challenge", () => {
+    expect(
+      isOAuthChallenge('Bearer realm="OAuth", resource_metadata="https://x/.well-known/oauth-protected-resource"'),
+    ).toBe(true);
+  });
+
+  it("matches a Bearer challenge that only advertises resource_metadata", () => {
+    expect(
+      isOAuthChallenge('Bearer resource_metadata="https://x/.well-known/oauth-protected-resource"'),
+    ).toBe(true);
+  });
+
+  it("does not match a plain Bearer 401 (invalid API key, not an OAuth requirement)", () => {
+    expect(isOAuthChallenge('Bearer error="invalid_token"')).toBe(false);
+  });
+
+  it("does not match a non-Bearer scheme", () => {
+    expect(isOAuthChallenge('Basic realm="oauth"')).toBe(false);
+  });
+
+  it("is empty-safe", () => {
+    expect(isOAuthChallenge("")).toBe(false);
+  });
+});
+
+describe("parseResourceMetadataUrl", () => {
+  it("extracts the resource_metadata URL", () => {
+    expect(
+      parseResourceMetadataUrl(
+        'Bearer realm="OAuth", resource_metadata="https://mcp.notion.com/.well-known/oauth-protected-resource/mcp"',
+      ),
+    ).toBe("https://mcp.notion.com/.well-known/oauth-protected-resource/mcp");
+  });
+
+  it("returns undefined when absent", () => {
+    expect(parseResourceMetadataUrl('Bearer realm="OAuth"')).toBeUndefined();
+  });
+});
+
+describe("detectOAuthChallenge", () => {
+  it("returns an OAuthRequiredError for a 401 OAuth challenge", async () => {
+    mockFetchOnce({
+      status: 401,
+      wwwAuthenticate:
+        'Bearer realm="OAuth", resource_metadata="https://mcp.notion.com/.well-known/oauth-protected-resource/mcp"',
+    });
+
+    const result = await detectOAuthChallenge("https://mcp.notion.com/mcp", {}, "notion");
+
+    expect(result).toBeInstanceOf(OAuthRequiredError);
+    expect(result?.serverSlug).toBe("notion");
+    expect(result?.resourceMetadataUrl).toBe(
+      "https://mcp.notion.com/.well-known/oauth-protected-resource/mcp",
+    );
+    // The message is self-contained and carries the "requires OAuth" marker the
+    // connect wrappers key on.
+    expect(result?.message).toContain("requires OAuth");
+    expect(result?.message).toContain("notion");
+  });
+
+  it("returns null for a 401 that is NOT an OAuth challenge (invalid static token)", async () => {
+    mockFetchOnce({ status: 401, wwwAuthenticate: 'Bearer error="invalid_token"' });
+    expect(
+      await detectOAuthChallenge("https://api.example.com/mcp", {}, "example"),
+    ).toBeNull();
+  });
+
+  it("returns null on a non-401 response", async () => {
+    mockFetchOnce({ status: 200 });
+    expect(
+      await detectOAuthChallenge("https://api.example.com/mcp", {}, "example"),
+    ).toBeNull();
+  });
+
+  it("returns null (never throws) when the probe itself fails", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => {
+        throw new Error("network down");
+      }),
+    );
+    expect(
+      await detectOAuthChallenge("https://api.example.com/mcp", {}, "example"),
+    ).toBeNull();
+  });
+
+  it("forwards the resolved headers to the probe request", async () => {
+    const fetchMock = vi.fn(
+      async (_url: string | URL, _init?: RequestInit) =>
+        new Response(null, { status: 200 }),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+
+    await detectOAuthChallenge(
+      "https://api.example.com/mcp",
+      { Authorization: "Bearer stale-token" },
+      "example",
+    );
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    const init = fetchMock.mock.calls[0]?.[1];
+    expect((init?.headers as Record<string, string>).Authorization).toBe(
+      "Bearer stale-token",
+    );
+    expect(init?.method).toBe("POST");
+  });
+});

package/src/shared/execution-status-writer.ts

@@ -0,0 +1,56 @@
+/**
+ * Shared interface for proto mutation consumed by side-effect classes
+ * (InlinePublisher, WriteBackCoordinator) and streaming loops.
+ *
+ * The deep-agent harness implements it on its v2 StatusBuilder and
+ * V3StatusBuilder; the Cursor harness — which mutates a bare status proto
+ * with no builder — uses {@link statusProtoWriter}. Side-effect classes
+ * depend only on this interface, never on a specific implementation.
+ */
+
+import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { ExecutionArtifact } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/artifact_pb";
+import type { WorkspaceWriteBack } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/writeback_pb";
+
+export interface ExecutionStatusWriter {
+  readonly currentStatus: AgentExecutionStatus;
+  readonly forceNextUpdate: boolean;
+  clearForceFlag(): void;
+  addArtifact(artifact: ExecutionArtifact): void;
+  addWriteBack(wb: WorkspaceWriteBack): void;
+}
+
+/**
+ * An {@link ExecutionStatusWriter} over a bare status proto, for harnesses
+ * that mutate the status directly instead of through a builder (the Cursor
+ * harness). Mutations apply synchronously to the given proto; the caller's
+ * own persist points pick them up — the force flag is a streaming-loop
+ * concern the direct-mutation style has no use for, so it stays `false`.
+ *
+ * Write-backs upsert by `workspaceEntryName` — the same contract as the
+ * deep-agent `StatusBuilder.addWriteBack`: each git-backed workspace entry
+ * carries at most one record, progressing through phases.
+ */
+export function statusProtoWriter(status: AgentExecutionStatus): ExecutionStatusWriter {
+  return {
+    get currentStatus() {
+      return status;
+    },
+    forceNextUpdate: false,
+    clearForceFlag() {},
+    addArtifact(artifact: ExecutionArtifact) {
+      status.artifacts.push(artifact);
+    },
+    addWriteBack(wb: WorkspaceWriteBack) {
+      const backs = status.workspaceWriteBacks;
+      const idx = backs.findIndex(
+        (b) => b.workspaceEntryName === wb.workspaceEntryName,
+      );
+      if (idx >= 0) {
+        backs[idx] = wb;
+      } else {
+        backs.push(wb);
+      }
+    },
+  };
+}

package/src/shared/mcp-oauth-detect.ts

@@ -0,0 +1,112 @@
+/**
+ * OAuth-challenge classification for HTTP MCP endpoints.
+ *
+ * When an HTTP MCP endpoint requires OAuth (per the MCP Authorization spec /
+ * RFC 9728), an unauthenticated or statically-tokened request is answered with
+ * `401` and a `WWW-Authenticate: Bearer ...` header pointing at OAuth protected
+ * resource metadata. The MCP client SDK surfaces this only as an opaque
+ * aggregate error ("unhandled errors in a TaskGroup"), which tells the user
+ * nothing.
+ *
+ * This module turns that opaque failure into a precise, actionable signal: it
+ * re-probes the endpoint once (only on the failure path, so the happy path pays
+ * nothing) and, if it sees an OAuth challenge, returns an {@link
+ * OAuthRequiredError} whose message tells the user to connect via OAuth instead
+ * of a manual token.
+ *
+ * Kept transport-library-agnostic (uses global `fetch`) so it is reusable by
+ * connect-time discovery, execution-time error enrichment, and any other caller
+ * that holds an MCP endpoint URL + headers.
+ */
+
+const OAUTH_PROBE_TIMEOUT_MS = 10_000;
+
+/**
+ * Raised when an HTTP MCP endpoint answers with an OAuth authentication
+ * challenge. The message is self-contained and user-facing: it survives the
+ * Temporal boundary and is shown by the connect error wrappers verbatim.
+ *
+ * The literal phrase "requires OAuth" is a stable marker the Go/Java connect
+ * wrappers match to avoid appending a generic "check your credentials" suffix.
+ */
+export class OAuthRequiredError extends Error {
+  constructor(
+    public readonly serverSlug: string,
+    public readonly resourceMetadataUrl?: string,
+  ) {
+    super(
+      `MCP server '${serverSlug}' requires OAuth: its endpoint returned an ` +
+        `authentication challenge (HTTP 401). A manually-entered API token will ` +
+        `not work here — connect it with the OAuth "Sign in" flow instead.`,
+    );
+    this.name = "OAuthRequiredError";
+  }
+}
+
+/**
+ * Whether a `WWW-Authenticate` header value is an OAuth challenge.
+ *
+ * The MCP auth spec emits `Bearer realm="OAuth", resource_metadata="..."`. We
+ * require the `Bearer` scheme plus either an OAuth realm or a resource-metadata
+ * pointer, so a plain `Bearer` 401 from a static-token API (an invalid key, not
+ * an OAuth requirement) is not misclassified.
+ */
+export function isOAuthChallenge(wwwAuthenticate: string): boolean {
+  const value = wwwAuthenticate.toLowerCase();
+  if (!value.includes("bearer")) return false;
+  return value.includes("oauth") || value.includes("resource_metadata");
+}
+
+/** Extract the `resource_metadata` URL from a `WWW-Authenticate` value, if present. */
+export function parseResourceMetadataUrl(
+  wwwAuthenticate: string,
+): string | undefined {
+  const match = /resource_metadata="([^"]+)"/i.exec(wwwAuthenticate);
+  return match?.[1];
+}
+
+/**
+ * Probe an HTTP MCP endpoint once to decide whether its failure is an OAuth
+ * challenge. Returns an {@link OAuthRequiredError} to throw, or `null` when the
+ * endpoint is not asking for OAuth (so the caller rethrows the original error).
+ *
+ * Never throws: any probe/network failure returns `null` so this classification
+ * step can never mask or replace the original discovery error.
+ */
+export async function detectOAuthChallenge(
+  url: string,
+  headers: Record<string, string> | undefined,
+  slug: string,
+): Promise<OAuthRequiredError | null> {
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json, text/event-stream",
+        ...(headers ?? {}),
+      },
+      // A minimal MCP initialize request — enough to trigger the endpoint's
+      // auth check without establishing a session.
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: {},
+      }),
+      signal: AbortSignal.timeout(OAUTH_PROBE_TIMEOUT_MS),
+    });
+
+    if (response.status !== 401) return null;
+
+    const wwwAuthenticate = response.headers.get("www-authenticate") ?? "";
+    if (!isOAuthChallenge(wwwAuthenticate)) return null;
+
+    return new OAuthRequiredError(
+      slug,
+      parseResourceMetadataUrl(wwwAuthenticate),
+    );
+  } catch {
+    return null;
+  }
+}