@stigmer/runner 3.0.1

package/dist/activities/execute-cursor/hitl-diagnostics.js

@@ -0,0 +1,73 @@
+/**
+ * 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 { 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, _toolCallId) {
+    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) {
+    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) {
+    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 "";
+    }
+}
+//# sourceMappingURL=hitl-diagnostics.js.map

package/dist/activities/execute-cursor/hitl-diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hitl-diagnostics.js","sourceRoot":"","sources":["../../../src/activities/execute-cursor/hitl-diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,8DAA8D,CAAC;AAE3F,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAEhC;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CACnC,QAAwB,EACxB,WAAmB;IAEnB,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,WAAW,CAAC,UAAU,CAAC,CAAC;IAC7E,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEvC,MAAM,MAAM,GAAG,UAAU,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACjD,IAAI,CAAC,MAAM,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IAE/B,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,IAAI,mBAAmB,EAAE,CAAC;QACjD,OAAO,MAAM,CAAC,OAAO,CAAC;IACxB,CAAC;IAED,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,mBAAmB,CAAC,CAAC;AACpD,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,YAAoB;IACrD,IAAI,CAAC;QACH,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC;QACxD,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC;QAChD,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;QAE1C,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,KAAK,EAAE,CAAC,WAAW,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE;YACnF,GAAG,EAAE,YAAY;YACjB,OAAO,EAAE,KAAK;SACf,CAAC,CAAC;QACH,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,YAAoB;IACtD,IAAI,CAAC;QACH,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC;QACxD,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC;QAChD,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;QAE1C,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,KAAK,EAAE,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE;YACnE,GAAG,EAAE,YAAY;YACjB,OAAO,EAAE,KAAK;SACf,CAAC,CAAC;QACH,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/activities/execute-cursor/hook-script.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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
+ */
+/**
+ * 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 declare function generateHookScript(stateFilePath: string, ledgerFilePath: string): string;

package/dist/activities/execute-cursor/hook-script.js

@@ -0,0 +1,156 @@
+/**
+ * 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, ledgerFilePath) {
+    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
+`;
+}
+//# sourceMappingURL=hook-script.js.map

package/dist/activities/execute-cursor/hook-script.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-script.js","sourceRoot":"","sources":["../../../src/activities/execute-cursor/hook-script.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D,MAAM,+BAA+B,GACnC,0EAA0E;IAC1E,uEAAuE;IACvE,2EAA2E,CAAC;AAE9E;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB,CAAC,aAAqB,EAAE,cAAsB;IAC9E,MAAM,aAAa,GAAG,kBAAkB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACnD,OAAO;;;;;;;;;;;;;;;;;;;cAmBK,aAAa;eACZ,cAAc;;;;gDAImB,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;eAuBhE,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;gDA4BoB,+BAA+B;;;;;;;;;;;;;;;kDAe7B,+BAA+B;;;;;;;;;;;CAWhF,CAAC;AACF,CAAC"}

package/dist/activities/execute-cursor/http2-interceptor.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare function installHttp2Interceptor(opts: {
+    proxyEndpoint: string | undefined;
+    stigmerToken: string | undefined;
+}): void;
+/**
+ * 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 declare function assertHttp2ConnectPatched(): Promise<void>;
+/**
+ * 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 declare function updateHttp2InterceptorToken(token: string): void;
+/**
+ * Remove the interceptor and restore the original http2.connect.
+ * Primarily for testing.
+ */
+export declare function uninstallHttp2Interceptor(): void;
+/**
+ * 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 declare function closeProxySessions(): void;

package/dist/activities/execute-cursor/http2-interceptor.js

@@ -0,0 +1,209 @@
+/**
+ * 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 { 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 = require("node:http2");
+const EXECUTION_ID_HEADER = "x-stigmer-execution-id";
+const STIGMER_AUTH_HEADER = "x-stigmer-auth";
+let config = null;
+let originalConnect = 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();
+/**
+ * Parses an authority (URL or host:port string) into hostname + port
+ * for comparison against the configured proxy endpoint.
+ */
+function parseAuthority(authority) {
+    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) {
+    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) {
+    proxySessions.add(session);
+    session.once("close", () => proxySessions.delete(session));
+    const originalRequest = session.request.bind(session);
+    session.request = function patchedRequest(headers, options) {
+        if (!config) {
+            return originalRequest(headers, options);
+        }
+        const ctx = getExecutionContext().getStore();
+        const augmented = {
+            ...headers,
+            [STIGMER_AUTH_HEADER]: `Bearer ${config.stigmerToken}`,
+        };
+        if (ctx?.executionId) {
+            augmented[EXECUTION_ID_HEADER] = ctx.executionId;
+        }
+        return originalRequest(augmented, options);
+    };
+    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) {
+    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, optionsOrListener, listener) {
+        const isProxy = isProxyAuthority(authority);
+        const session = originalConnect.call(http2, authority, optionsOrListener, listener);
+        if (isProxy) {
+            return wrapSession(session);
+        }
+        return session;
+    };
+    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() {
+    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) {
+    if (config) {
+        config = { ...config, stigmerToken: token };
+    }
+}
+/**
+ * Remove the interceptor and restore the original http2.connect.
+ * Primarily for testing.
+ */
+export function uninstallHttp2Interceptor() {
+    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() {
+    for (const session of proxySessions) {
+        if (!session.closed && !session.destroyed) {
+            session.close();
+        }
+    }
+    proxySessions.clear();
+}
+//# sourceMappingURL=http2-interceptor.js.map

package/dist/activities/execute-cursor/http2-interceptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http2-interceptor.js","sourceRoot":"","sources":["../../../src/activities/execute-cursor/http2-interceptor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAE7D,uEAAuE;AACvE,wEAAwE;AACxE,0DAA0D;AAC1D,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,KAAK,GAAqB,OAAO,CAAC,YAAY,CAAC,CAAC;AAEtD,MAAM,mBAAmB,GAAG,wBAAwB,CAAC;AACrD,MAAM,mBAAmB,GAAG,gBAAgB,CAAC;AAQ7C,IAAI,MAAM,GAAkC,IAAI,CAAC;AACjD,IAAI,eAAe,GAAyB,KAAK,CAAC,OAAO,CAAC;AAE1D,6EAA6E;AAC7E,wDAAwD;AACxD,MAAM,aAAa,GAAG,IAAI,GAAG,EAAgC,CAAC;AAE9D;;;GAGG;AACH,SAAS,cAAc,CAAC,SAAuB;IAC7C,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,SAAS,YAAY,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC;QACtE,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACpE,OAAO,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC1C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,gBAAgB,CAAC,SAAuB;IAC/C,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC1B,MAAM,MAAM,GAAG,cAAc,CAAC,SAAS,CAAC,CAAC;IACzC,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC1B,OAAO,MAAM,CAAC,QAAQ,KAAK,MAAM,CAAC,aAAa,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,SAAS,CAAC;AACtF,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,WAAW,CAAC,OAAqC;IACxD,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC3B,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,aAAa,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;IAE3D,MAAM,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAEtD,OAAO,CAAC,OAAO,GAAG,SAAS,cAAc,CACvC,OAAuC,EACvC,OAA+C;QAE/C,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,eAAe,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAC3C,CAAC;QAED,MAAM,GAAG,GAAG,mBAAmB,EAAE,CAAC,QAAQ,EAAE,CAAC;QAC7C,MAAM,SAAS,GAAkC;YAC/C,GAAG,OAAO;YACV,CAAC,mBAAmB,CAAC,EAAE,UAAU,MAAM,CAAC,YAAY,EAAE;SACvD,CAAC;QACF,IAAI,GAAG,EAAE,WAAW,EAAE,CAAC;YACrB,SAAS,CAAC,mBAAmB,CAAC,GAAG,GAAG,CAAC,WAAW,CAAC;QACnD,CAAC;QACD,OAAO,eAAe,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAC7C,CAA2B,CAAC;IAE5B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAGvC;IACC,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;QACxB,OAAO;IACT,CAAC;IAED,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;QACvB,OAAO;IACT,CAAC;IAED,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAClD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,CAAC,IAAI,CACV,sDAAsD,IAAI,CAAC,aAAa,qBAAqB,CAC9F,CAAC;QACF,OAAO;IACT,CAAC;IAED,MAAM,GAAG,EAAE,aAAa,EAAE,MAAM,CAAC,QAAQ,EAAE,SAAS,EAAE,MAAM,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC;IACrG,eAAe,GAAG,KAAK,CAAC,OAAO,CAAC;IAEhC,KAAK,CAAC,OAAO,GAAG,SAAS,cAAc,CACrC,SAAuB,EACvB,iBAAuB,EACvB,QAAc;QAEd,MAAM,OAAO,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;QAC5C,MAAM,OAAO,GAAG,eAAe,CAAC,IAAI,CAAC,KAAK,EAAE,SAAgB,EAAE,iBAAiB,EAAE,QAAQ,CAAC,CAAC;QAE3F,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,WAAW,CAAC,OAAO,CAAC,CAAC;QAC9B,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAyB,CAAC;IAE1B,OAAO,CAAC,GAAG,CACT,yDAAyD,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,IAAI,GAAG;QACxF,oDAAoD,CACvD,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB;IAC7C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO;IACT,CAAC;IAED,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,CAAC;IACtC,IAAI,EAAE,CAAC,OAAO,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CACb,gFAAgF;YAC9E,iFAAiF;YACjF,oFAAoF;YACpF,kFAAkF;YAClF,oFAAoF;YACpF,kFAAkF;YAClF,2BAA2B,CAC9B,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,2BAA2B,CAAC,KAAa;IACvD,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,GAAG,EAAE,GAAG,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC;IAC9C,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,yBAAyB;IACvC,MAAM,GAAG,IAAI,CAAC;IACd,KAAK,CAAC,OAAO,GAAG,eAAe,CAAC;IAChC,aAAa,CAAC,KAAK,EAAE,CAAC;AACxB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB;IAChC,KAAK,MAAM,OAAO,IAAI,aAAa,EAAE,CAAC;QACpC,IAAI,CAAC,OAAO,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;YAC1C,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,CAAC;IACH,CAAC;IACD,aAAa,CAAC,KAAK,EAAE,CAAC;AACxB,CAAC"}

package/dist/activities/execute-cursor/index.d.ts

@@ -0,0 +1,67 @@
+/**
+ * ExecuteCursor Temporal activity — the core of the cursor-runner service.
+ *
+ * Implements the same Slim-Payload Pattern as ExecuteGraphton:
+ * - Receives only executionId + harnessStateId (Cursor agentId)
+ * - Hydrates execution from DB via gRPC
+ * - Resolves full agent blueprint (instructions, MCP servers, skills, sub-agents)
+ * - Runs the Cursor agent, streams events, reports status
+ * - Returns slim AgentExecutionStatus to workflow
+ *
+ * Durable HITL Model:
+ * When a tool requires approval, the preToolUse hook denies it. The activity
+ * captures the denied tool details, reports WAITING_FOR_APPROVAL, and RETURNS
+ * to the workflow. The workflow waits for the approvalGateResolved signal,
+ * then reinvokes this activity. On reinvocation, the activity resumes the
+ * Cursor Agent and prompts it to execute the approved tool.
+ *
+ * This is identical to the LangGraph flow from the workflow's perspective.
+ *
+ * Durable Continuation Model:
+ * Conversation continuity is carried by the Cursor SDK's native local agent
+ * state, whose SQLite store is persisted on the durable workspace volume
+ * (see resolvePlatformOptions) so Agent.resume() survives pod restart,
+ * reschedule, and snapshot restore. When resume fails (store lost/corrupted
+ * or agent unknown), resolveAgent() creates a fresh agent and the next turn
+ * starts from the user message plus re-injected instructions.
+ */
+import { InteractionMode, ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { Config } from "../../config.js";
+import type { AgentResolution } from "./session-lifecycle.js";
+/**
+ * Creates the activity functions bound to the runner config.
+ * Returned object is passed to Temporal Worker.create({ activities }).
+ */
+export declare function createCursorActivities(config: Config): {
+    ExecuteCursor: (executionId: string, threadId: string) => Promise<unknown>;
+};
+export interface BuildPromptInput {
+    resolution: AgentResolution;
+    approvalDecisions: Map<string, ApprovalAction> | undefined;
+    instructions: string;
+    userMessage: string;
+    skills: import("./prompt-builder.js").SkillMetadata[];
+    subAgents: import("@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb").SubAgent[];
+    workspaceDirs: string[];
+    workspaceFileRefs: string[];
+    attachmentPaths: string[];
+    pendingApprovals: import("@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb").PendingApproval[];
+    interactionMode?: InteractionMode;
+}
+/**
+ * Select and build the appropriate prompt based on resolution reason and
+ * HITL state.
+ *
+ * Conversation continuation is carried entirely by the Cursor SDK's native
+ * agent state (the local SQLite store persisted on the durable workspace
+ * volume, or cloud server-side state) — there is no separate continuation
+ * store. The prompt therefore depends only on how the agent was resolved:
+ *
+ * 1. HITL reinvocation        -> buildReinvocationPrompt (approval decisions;
+ *                                 the resumed agent's native context carries
+ *                                 the prior conversation)
+ * 2. resumed_successfully      -> raw userMessage (native context carries it)
+ * 3. first execution / fresh   -> buildEnhancedPrompt (full instructions +
+ *    agent after resume failure   skills; no prior conversation to inherit)
+ */
+export declare function buildPrompt(input: BuildPromptInput): string;