@stigmer/runner 3.0.1

package/src/activities/execute-cursor/hitl-diagnostics.ts

@@ -0,0 +1,82 @@
+/**
+ * Deny-time diagnostic utilities for HITL (human-in-the-loop) approvals.
+ *
+ * These helpers capture the agent's rationale and the workspace's git state
+ * at the moment a tool call is proposed/denied, so the approval record
+ * (PendingApproval.agent_rationale / branch_at_deny / head_sha_at_deny)
+ * carries enough context for a human reviewer and for later reinvocation.
+ */
+
+import type { AgentMessage } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { MessageType } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+const MAX_RATIONALE_CHARS = 500;
+
+/**
+ * Extract the agent's rationale for a tool call from the message history.
+ *
+ * Heuristic: Takes the content of the last AI message, which typically
+ * contains the agent's explanation of what it's about to do. Truncated
+ * to MAX_RATIONALE_CHARS to keep the approval record concise.
+ *
+ * Returns empty string if no AI messages exist.
+ */
+export function extractAgentRationale(
+  messages: AgentMessage[],
+  _toolCallId: string,
+): string {
+  const aiMessages = messages.filter((m) => m.type === MessageType.MESSAGE_AI);
+  if (aiMessages.length === 0) return "";
+
+  const lastAi = aiMessages[aiMessages.length - 1];
+  if (!lastAi.content) return "";
+
+  if (lastAi.content.length <= MAX_RATIONALE_CHARS) {
+    return lastAi.content;
+  }
+
+  return lastAi.content.slice(-MAX_RATIONALE_CHARS);
+}
+
+/**
+ * Get the current git branch name for a workspace directory.
+ *
+ * Best-effort: returns empty string on failure (non-git workspace,
+ * missing git binary, detached HEAD). Never throws.
+ */
+export async function getGitBranch(workspaceDir: string): Promise<string> {
+  try {
+    const { execFile } = await import("node:child_process");
+    const { promisify } = await import("node:util");
+    const execFileAsync = promisify(execFile);
+
+    const { stdout } = await execFileAsync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+      cwd: workspaceDir,
+      timeout: 5_000,
+    });
+    return stdout.trim();
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Get the current git HEAD SHA for a workspace directory.
+ *
+ * Best-effort: returns empty string on failure. Never throws.
+ */
+export async function getGitHeadSha(workspaceDir: string): Promise<string> {
+  try {
+    const { execFile } = await import("node:child_process");
+    const { promisify } = await import("node:util");
+    const execFileAsync = promisify(execFile);
+
+    const { stdout } = await execFileAsync("git", ["rev-parse", "HEAD"], {
+      cwd: workspaceDir,
+      timeout: 5_000,
+    });
+    return stdout.trim();
+  } catch {
+    return "";
+  }
+}

package/src/activities/execute-cursor/hook-script.ts

@@ -0,0 +1,159 @@
+/**
+ * Template for the preToolUse hook script that Cursor spawns.
+ *
+ * This module doesn't execute as a hook itself — it generates the shell
+ * script that is written to .cursor/hooks/stigmer-approval.sh. That script
+ * is invoked by Cursor for every tool call via the preToolUse hook.
+ *
+ * The hook script:
+ * 1. Reads the tool call JSON from stdin
+ * 2. Reads the approval state JSON file written by the cursor-runner
+ * 3. Evaluates the policy: auto-approve, approved grants (reinvocation),
+ *    gated built-in tools, MCP require-approval policies
+ * 4. On a deny, appends the call's identity token to the denial ledger
+ *    (stigmer-denials.jsonl) so the runner can mark the gated tool call as
+ *    WAITING_APPROVAL — the hook is the only place the deny decision is made,
+ *    so its ledger is the authoritative record of what was gated this turn
+ * 5. Returns { "permission": "allow" } or { "permission": "deny" } on stdout
+ *
+ * The script is self-contained (no Node.js required) for portability. It uses
+ * bash + grep/cut for lightweight JSON field extraction. All policy decisions
+ * are pre-computed by the runner into the state file; the hook only performs
+ * mechanical field extraction and string lookups — the policy itself is
+ * authored once in TypeScript (approval-policy.ts / approval-state.ts).
+ *
+ * Policy evaluation order (first match wins). The model is "gate the dangerous
+ * set, allow the rest" — matching the native harness and avoiding denial of
+ * auto-approved MCP tools (which are absent from mcpToolPolicies):
+ * 1. autoApproveAll → allow
+ * 2. Matches an approved grant token → allow (reinvocation after approval)
+ * 3. Tool name in builtInGatedList → deny
+ * 4. Tool name in mcpToolPolicies (require-approval) → deny
+ * 5. Everything else (read-only built-ins, auto-approved MCP, unknown) → allow
+ */
+
+import { SALIENT_ARG_FIELDS } from "./approval-policy.js";
+
+const APPROVAL_REQUIRED_AGENT_MESSAGE =
+  "STIGMER_APPROVAL_REQUIRED: This tool call requires user approval before " +
+  "execution. Do not attempt alternative approaches or workarounds. The " +
+  "execution will resume after the user reviews and approves this tool call.";
+
+/**
+ * Generates the bash hook script content.
+ *
+ * The script reads a JSON state file written by the cursor-runner before
+ * each agent.send() call. The state file is the single source of truth
+ * for all approval decisions.
+ *
+ * Approved grants are matched by a base64 token of `toolName \n salientArg`,
+ * recomputed here from the incoming tool call. The salient-arg field list is
+ * injected from SALIENT_ARG_FIELDS so the runner and the hook never disagree on
+ * which argument identifies the resource. The encoding must stay byte-identical
+ * to grantToken() in approval-state.ts.
+ */
+export function generateHookScript(stateFilePath: string, ledgerFilePath: string): string {
+  const salientFields = SALIENT_ARG_FIELDS.join(" ");
+  return `#!/bin/bash
+# Stigmer HITL approval hook for Cursor preToolUse
+# Generated by cursor-runner — do not edit manually.
+#
+# Reads tool call from stdin (JSON), checks approval state file,
+# returns permission decision on stdout (JSON). On a deny, appends the call's
+# identity token to the denial ledger so the runner can mark the gated tool call
+# as WAITING_APPROVAL.
+
+set -euo pipefail
+
+INPUT=$(cat)
+
+# Extract tool_name from the hook input JSON.
+# Cursor sends the actual tool name (e.g. "search_services" for MCP tools).
+# Every extraction ends with '|| true': under 'set -e' a non-matching grep would
+# otherwise abort the script and emit no decision.
+TOOL_NAME=$(echo "$INPUT" | grep -o '"tool_name":"[^"]*"' | head -1 | cut -d'"' -f4 || true)
+
+STATE_FILE="${stateFilePath}"
+LEDGER_FILE="${ledgerFilePath}"
+
+# --- Failsafe: missing state file → deny (fail-closed) ---
+if [ ! -f "$STATE_FILE" ]; then
+  echo '{"permission":"deny","agent_message":"${APPROVAL_REQUIRED_AGENT_MESSAGE}","user_message":"Tool requires approval: '"$TOOL_NAME"'"}'
+  exit 0
+fi
+
+STATE=$(cat "$STATE_FILE")
+
+# --- 1. Auto-approve all ---
+if echo "$STATE" | grep -q '"autoApproveAll":true'; then
+  echo '{"permission":"allow"}'
+  exit 0
+fi
+
+# --- 2. Approved grants (reinvocation after SubmitApproval) ---
+# Build the same base64 token the runner stored for an approved tool call and
+# match it against approvedGrantTokens. Match by (name + salient arg); fall back
+# to name-only for grants with no salient arg (MCP tools). Salient-arg field
+# order is injected from SALIENT_ARG_FIELDS (single source of truth).
+TOKEN_NAME=$(printf '%s\\n' "$TOOL_NAME" | base64 | tr -d '\\n')
+if echo "$STATE" | grep -q "\\"$TOKEN_NAME\\""; then
+  echo '{"permission":"allow"}'
+  exit 0
+fi
+SALIENT=""
+for field in ${salientFields}; do
+  v=$(echo "$INPUT" | grep -o "\\"$field\\":\\"[^\\"]*\\"" | head -1 | cut -d'"' -f4 || true)
+  if [ -n "$v" ]; then SALIENT="$v"; break; fi
+done
+if [ -n "$SALIENT" ]; then
+  TOKEN_SALIENT=$(printf '%s\\n%s' "$TOOL_NAME" "$SALIENT" | base64 | tr -d '\\n')
+  if echo "$STATE" | grep -q "\\"$TOKEN_SALIENT\\""; then
+    echo '{"permission":"allow"}'
+    exit 0
+  fi
+fi
+
+# Identity token recorded on a deny so the runner can correlate the gated call
+# back to its streamed tool call. Prefer the salient-arg token (identifies the
+# specific resource); fall back to name-only. Byte-identical to grantToken().
+if [ -n "$SALIENT" ]; then DENY_TOKEN="$TOKEN_SALIENT"; else DENY_TOKEN="$TOKEN_NAME"; fi
+
+# Append a denial record to the ledger. Best-effort: a ledger write failure must
+# never abort the decision (the deny still goes out on stdout). toolName is raw
+# for human-readable debugging; token drives correlation in the runner.
+record_denial() {
+  echo '{"toolName":"'"$TOOL_NAME"'","token":"'"$DENY_TOKEN"'"}' >> "$LEDGER_FILE" 2>/dev/null || true
+}
+
+# --- 3. Gated built-in tools (Write, StrReplace, Shell, ...) → deny ---
+GATED_LIST=$(echo "$STATE" | grep -o '"builtInGatedList":\\[[^]]*\\]' | head -1 || true)
+if [ -n "$GATED_LIST" ] && [ -n "$TOOL_NAME" ] && echo "$GATED_LIST" | grep -q "\\"$TOOL_NAME\\""; then
+  record_denial
+  echo '{"permission":"deny","agent_message":"${APPROVAL_REQUIRED_AGENT_MESSAGE}","user_message":"Tool requires approval: '"$TOOL_NAME"'"}'
+  exit 0
+fi
+
+# --- 4. MCP tools that require approval → deny ---
+# mcpToolPolicies holds only require-approval tools (auto-approved MCP tools are
+# absent), so presence means "deny" unless an entry is explicitly false.
+if echo "$STATE" | grep -q "\\"mcpToolPolicies\\"" && [ -n "$TOOL_NAME" ]; then
+  TOOL_POLICY=$(echo "$STATE" | grep -o "\\"$TOOL_NAME\\":{[^}]*}" | head -1 || true)
+  if [ -n "$TOOL_POLICY" ] && ! echo "$TOOL_POLICY" | grep -q '"requiresApproval":false'; then
+    MSG=$(echo "$TOOL_POLICY" | grep -o '"message":"[^"]*"' | head -1 | cut -d'"' -f4 || true)
+    if [ -z "$MSG" ]; then
+      MSG="Tool requires approval: $TOOL_NAME"
+    fi
+    record_denial
+    echo '{"permission":"deny","agent_message":"${APPROVAL_REQUIRED_AGENT_MESSAGE}","user_message":"'"$MSG"'"}'
+    exit 0
+  fi
+fi
+
+# --- 5. Everything else → allow ---
+# Read-only built-ins, auto-approved MCP tools, and anything not explicitly
+# gated. Fail-open mirrors the native harness (gate the dangerous set, allow the
+# rest) and prevents denying auto-approved MCP tools the state cannot enumerate.
+echo '{"permission":"allow"}'
+exit 0
+`;
+}

package/src/activities/execute-cursor/http2-interceptor.ts

@@ -0,0 +1,253 @@
+/**
+ * HTTP/2 session interceptor for Cursor SDK Connect RPC proxy support.
+ *
+ * The Cursor SDK's Connect RPC transport (@connectrpc/connect-node) uses
+ * Node's native `http2` module, completely bypassing globalThis.fetch.
+ * This means the fetch interceptor (fetch-interceptor.ts) cannot inject
+ * the `x-stigmer-execution-id` header on BiDi streams.
+ *
+ * CHALLENGE: connect-node uses `import * as http2 from "node:http2"`. Node
+ * builds that ESM namespace by snapshotting the builtin's CJS exports at the
+ * FIRST `import` of the module, then freezes the namespace bindings. Patching
+ * `http2.connect` via `require()` mutates the shared CJS singleton, and that
+ * mutation is only visible to ESM namespace imports performed AFTER the patch.
+ * If connect-node imports `node:http2` first, its namespace is already frozen
+ * to the original `connect` and our later patch is invisible to it.
+ *
+ * LOAD ORDER IS THEREFORE LOAD-BEARING: this interceptor MUST be installed
+ * before the first connect-node import in the process. The runner enforces this
+ * by (a) keeping connect-node out of the pre-install static module graph
+ * (bootstrap.ts loads StigmerClient via dynamic import) and (b) installing this
+ * interceptor before resolving Temporal coordinates / importing the SDK in the
+ * runner factories. assertHttp2ConnectPatched() verifies the ESM-facade view at
+ * boot so any future regression fails loudly instead of silently 401-ing.
+ *
+ * This module patches `http2.connect()` to wrap returned sessions. The
+ * wrapped session's `request()` method reads the execution ID from the
+ * shared AsyncLocalStorage and injects it as an HTTP/2 header on each
+ * stream targeting the proxy endpoint.
+ *
+ * This is the same instrumentation approach used by OpenTelemetry's
+ * @opentelemetry/instrumentation-http2 for Node.js HTTP/2 tracing.
+ *
+ * EXIT CONDITION: This patch becomes unnecessary if @cursor/sdk ever
+ * exposes a mechanism to inject custom headers on its Connect RPC
+ * transport (e.g., interceptors option, defaultHeaders config, or a
+ * transport factory). At that point, replace this with a single Connect
+ * interceptor and remove the http2 patch.
+ *
+ * IMPORTANT: This module must be imported and installed BEFORE @cursor/sdk
+ * to ensure the patch is in place when the SDK opens its HTTP/2 session.
+ */
+
+import { createRequire } from "node:module";
+import type http2Type from "node:http2";
+import { getExecutionContext } from "./fetch-interceptor.js";
+
+// Use require() to get the ACTUAL CJS module singleton. Mutations here
+// are visible to all importers including ESM namespace imports, because
+// Node.js builtins expose a single shared exports object.
+const require = createRequire(import.meta.url);
+const http2: typeof http2Type = require("node:http2");
+
+const EXECUTION_ID_HEADER = "x-stigmer-execution-id";
+const STIGMER_AUTH_HEADER = "x-stigmer-auth";
+
+interface Http2InterceptorConfig {
+  proxyHostname: string;
+  proxyPort: string;
+  stigmerToken: string;
+}
+
+let config: Http2InterceptorConfig | null = null;
+let originalConnect: typeof http2.connect = http2.connect;
+
+// Tracks all wrapped proxy sessions for inter-activity lifecycle management.
+// Sessions are added on wrap and auto-removed on close.
+const proxySessions = new Set<http2Type.ClientHttp2Session>();
+
+/**
+ * Parses an authority (URL or host:port string) into hostname + port
+ * for comparison against the configured proxy endpoint.
+ */
+function parseAuthority(authority: string | URL): { hostname: string; port: string } | null {
+  try {
+    const url = authority instanceof URL ? authority : new URL(authority);
+    const port = url.port || (url.protocol === "https:" ? "443" : "80");
+    return { hostname: url.hostname, port };
+  } catch {
+    return null;
+  }
+}
+
+function isProxyAuthority(authority: string | URL): boolean {
+  if (!config) return false;
+  const parsed = parseAuthority(authority);
+  if (!parsed) return false;
+  return parsed.hostname === config.proxyHostname && parsed.port === config.proxyPort;
+}
+
+/**
+ * Wraps a ClientHttp2Session's `request()` method to inject the
+ * execution ID header from the current AsyncLocalStorage context.
+ *
+ * HTTP/2 multiplexes multiple streams on a single connection, so
+ * different executions may share the same session. Reading from ALS
+ * at request() time (per-stream) is the correct approach.
+ */
+function wrapSession(session: http2Type.ClientHttp2Session): http2Type.ClientHttp2Session {
+  proxySessions.add(session);
+  session.once("close", () => proxySessions.delete(session));
+
+  const originalRequest = session.request.bind(session);
+
+  session.request = function patchedRequest(
+    headers?: http2Type.OutgoingHttpHeaders,
+    options?: http2Type.ClientSessionRequestOptions,
+  ): http2Type.ClientHttp2Stream {
+    if (!config) {
+      return originalRequest(headers, options);
+    }
+
+    const ctx = getExecutionContext().getStore();
+    const augmented: http2Type.OutgoingHttpHeaders = {
+      ...headers,
+      [STIGMER_AUTH_HEADER]: `Bearer ${config.stigmerToken}`,
+    };
+    if (ctx?.executionId) {
+      augmented[EXECUTION_ID_HEADER] = ctx.executionId;
+    }
+    return originalRequest(augmented, options);
+  } as typeof session.request;
+
+  return session;
+}
+
+/**
+ * Install the HTTP/2 interceptor. Call once at startup, BEFORE importing
+ * @cursor/sdk.
+ *
+ * When proxyEndpoint is not provided, the interceptor is not installed
+ * and all http2.connect() calls pass through to the original.
+ */
+export function installHttp2Interceptor(opts: {
+  proxyEndpoint: string | undefined;
+  stigmerToken: string | undefined;
+}): void {
+  if (!opts.proxyEndpoint) {
+    return;
+  }
+
+  if (!opts.stigmerToken) {
+    return;
+  }
+
+  const parsed = parseAuthority(opts.proxyEndpoint);
+  if (!parsed) {
+    console.warn(
+      `[http2-interceptor] Could not parse proxyEndpoint "${opts.proxyEndpoint}", skipping install`,
+    );
+    return;
+  }
+
+  config = { proxyHostname: parsed.hostname, proxyPort: parsed.port, stigmerToken: opts.stigmerToken };
+  originalConnect = http2.connect;
+
+  http2.connect = function patchedConnect(
+    authority: string | URL,
+    optionsOrListener?: any,
+    listener?: any,
+  ): http2Type.ClientHttp2Session {
+    const isProxy = isProxyAuthority(authority);
+    const session = originalConnect.call(http2, authority as any, optionsOrListener, listener);
+
+    if (isProxy) {
+      return wrapSession(session);
+    }
+
+    return session;
+  } as typeof http2.connect;
+
+  console.log(
+    `[http2-interceptor] Installed: Connect RPC streams to ${parsed.hostname}:${parsed.port} ` +
+      `will carry x-stigmer-auth + x-stigmer-execution-id`,
+  );
+}
+
+/**
+ * Verify the patch is visible to ESM namespace importers of `node:http2`
+ * (i.e. @connectrpc/connect-node). Call once at boot, immediately after
+ * {@link installHttp2Interceptor}.
+ *
+ * Unlike the CJS `require("node:http2")` singleton, the ESM namespace produced
+ * by `import * as http2 from "node:http2"` is snapshotted at the module's first
+ * import and frozen. If connect-node imported `node:http2` before the patch was
+ * applied, this namespace still exposes the ORIGINAL `connect`, so BiDi streams
+ * would silently omit `x-stigmer-auth` and hit HTTP 401. Importing the module
+ * here and comparing `ns.connect` against our patched `http2.connect` is the
+ * only honest check — comparing two `require()` views is tautological because
+ * they are the same object.
+ *
+ * No-op when the interceptor is not configured (no proxy/token), since there is
+ * nothing to patch in that case.
+ *
+ * @throws if the interceptor is configured but the ESM facade is unpatched —
+ * a load-order regression that must fail loudly at boot, not at request time.
+ */
+export async function assertHttp2ConnectPatched(): Promise<void> {
+  if (!config) {
+    return;
+  }
+
+  const ns = await import("node:http2");
+  if (ns.connect !== http2.connect) {
+    throw new Error(
+      "[http2-interceptor] node:http2 ESM facade is unpatched: connect-node imported " +
+        "node:http2 before installHttp2Interceptor() ran, so its frozen namespace still " +
+        "holds the original http2.connect. BiDi streams would omit x-stigmer-auth and 401. " +
+        "Fix the load order: keep @connectrpc/connect-node out of the pre-install static " +
+        "module graph (load StigmerClient via dynamic import) and install this interceptor " +
+        "before resolving Temporal coordinates / importing @cursor/sdk. See bootstrap.ts " +
+        "and the runner factories.",
+    );
+  }
+}
+
+/**
+ * Update the auth token on the live interceptor config. Must be called
+ * whenever the Stigmer JWT is refreshed (e.g. via IPC updateToken) so
+ * that HTTP/2-intercepted streams use the current token instead of the
+ * one frozen at install time.
+ */
+export function updateHttp2InterceptorToken(token: string): void {
+  if (config) {
+    config = { ...config, stigmerToken: token };
+  }
+}
+
+/**
+ * Remove the interceptor and restore the original http2.connect.
+ * Primarily for testing.
+ */
+export function uninstallHttp2Interceptor(): void {
+  config = null;
+  http2.connect = originalConnect;
+  proxySessions.clear();
+}
+
+/**
+ * Close all tracked HTTP/2 sessions to the proxy endpoint, forcing
+ * the SDK to establish a fresh connection on next use.
+ *
+ * Call between sequential workflow task activities to prevent a
+ * degraded session from one task poisoning the next. No-op when
+ * no sessions are tracked (e.g., first activity in a workflow).
+ */
+export function closeProxySessions(): void {
+  for (const session of proxySessions) {
+    if (!session.closed && !session.destroyed) {
+      session.close();
+    }
+  }
+  proxySessions.clear();
+}