@stigmer/runner 3.0.1

package/dist/activities/execute-cursor/approval-policy.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Tool approval policy evaluation for the Cursor harness.
+ *
+ * Implements the four-level policy chain documented in the ToolCall proto:
+ *
+ * 1. McpServerStatus.tool_approvals — system-generated defaults from the
+ *    LLM classifier during the connect flow.
+ * 2. McpServerSpec.pinned_tool_approvals — manual overrides by the server
+ *    owner. Presence in the list means "requires approval."
+ * 3. McpServerUsage.tool_approval_overrides — per-agent customization with
+ *    an explicit requires_approval boolean.
+ * 4. AgentExecutionSpec.auto_approve_all — runtime bypass (highest priority).
+ *
+ * For MCP tools, the merged result determines whether the preToolUse hook
+ * allows or denies the call. For built-in Cursor tools (Shell, Read, etc.),
+ * a separate local policy applies.
+ */
+import type { ToolApprovalOverride } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import type { ResolvedMcpServer } from "./mcp-resolver.js";
+/**
+ * A single tool's merged approval decision after evaluating all policy layers.
+ */
+export interface MergedToolPolicy {
+    toolName: string;
+    mcpServerSlug: string;
+    requiresApproval: boolean;
+    approvalMessage: string;
+}
+/**
+ * Top-level tool-argument fields, in priority order, that identify the specific
+ * resource a built-in tool acts on. Used to render approval messages and to key
+ * HITL approval grants (see approval-state.ts). Authored here once and injected
+ * into the generated preToolUse hook script so the runner and the hook always
+ * agree on which field to match.
+ */
+export declare const SALIENT_ARG_FIELDS: readonly ["path", "command", "target_notebook"];
+/**
+ * Check whether a built-in (non-MCP) Cursor tool requires user approval.
+ *
+ * Only the explicitly gated, mutating/destructive tools require approval;
+ * everything else (read-only built-ins, and — at the hook layer — auto-approved
+ * MCP tools) is allowed. This "gate the dangerous set, allow the rest" model
+ * mirrors the native harness's resolveToolApproval, which also defaults
+ * unlisted tools to no-approval. It is deliberately fail-OPEN for unknown
+ * tools: the merged MCP policy map carries only the tools that REQUIRE
+ * approval, so a fail-closed default would wrongly deny every auto-approved
+ * MCP tool, which the hook cannot distinguish from an unknown built-in by name.
+ */
+export declare function builtInRequiresApproval(toolName: string): boolean;
+/**
+ * Returns the built-in tool names that require approval (the gated set the
+ * preToolUse hook denies unless auto-approved or granted on reinvocation).
+ */
+export declare function getBuiltInGatedList(): string[];
+/**
+ * Approval-message template for a gated built-in tool, or undefined when the
+ * tool is not a known gated built-in. Callers resolve the placeholders against
+ * the tool args via resolveApprovalMessage.
+ */
+export declare function getBuiltInApprovalMessage(toolName: string): string | undefined;
+/**
+ * Extract the canonical "salient" argument value that identifies the resource a
+ * built-in tool acts on (the file path, the shell command, …). Returns "" when
+ * no salient field is present. Kept in lockstep with SALIENT_ARG_FIELDS and the
+ * generated hook script so grant matching at deny-time and reinvoke-time never
+ * drift.
+ */
+export declare function extractArgKey(args: Record<string, unknown> | undefined): string;
+/**
+ * Merge approval policies from all four levels into a single lookup map.
+ *
+ * Keys are the raw tool name (e.g., "apply_cloud_resource"). Each MCP server
+ * contributes its own set of policies, so the map is keyed by
+ * "serverSlug/toolName" to avoid collisions between servers.
+ *
+ * Policy chain (each level overrides the previous):
+ * 1. status.toolApprovals — presence means "requires approval"
+ * 2. spec.pinnedToolApprovals — presence means "requires approval" (overrides)
+ * 3. agent tool_approval_overrides — explicit boolean per tool
+ * 4. auto_approve_all — bypasses everything
+ *
+ * When auto_approve_all is true, the returned map is empty (no tool
+ * requires approval).
+ */
+export declare function mergeApprovalPolicies(resolvedServers: ResolvedMcpServer[], agentOverrides: ToolApprovalOverride[], autoApproveAll: boolean): Map<string, MergedToolPolicy>;
+/**
+ * Look up whether an MCP tool requires approval.
+ *
+ * @param toolName - The actual MCP tool name (e.g., "apply_cloud_resource")
+ * @param mcpServerSlug - The MCP server slug (e.g., "planton")
+ * @param policies - The merged policy map from mergeApprovalPolicies()
+ * @returns The policy if approval is required, undefined if auto-approved
+ */
+export declare function lookupMcpToolPolicy(toolName: string, mcpServerSlug: string, policies: Map<string, MergedToolPolicy>): MergedToolPolicy | undefined;
+/**
+ * Resolve {{args.field}} placeholders in an approval message using the
+ * tool's actual arguments.
+ *
+ * Placeholder syntax matches the proto-documented format:
+ * - {{args.field_name}} — replaced with the argument value
+ * - {{tool_name}} — replaced with the tool name
+ * - Missing fields are replaced with "<unknown>"
+ */
+export declare function resolveApprovalMessage(template: string, toolName: string, args: Record<string, unknown>): string;

package/dist/activities/execute-cursor/approval-policy.js

@@ -0,0 +1,193 @@
+/**
+ * Tool approval policy evaluation for the Cursor harness.
+ *
+ * Implements the four-level policy chain documented in the ToolCall proto:
+ *
+ * 1. McpServerStatus.tool_approvals — system-generated defaults from the
+ *    LLM classifier during the connect flow.
+ * 2. McpServerSpec.pinned_tool_approvals — manual overrides by the server
+ *    owner. Presence in the list means "requires approval."
+ * 3. McpServerUsage.tool_approval_overrides — per-agent customization with
+ *    an explicit requires_approval boolean.
+ * 4. AgentExecutionSpec.auto_approve_all — runtime bypass (highest priority).
+ *
+ * For MCP tools, the merged result determines whether the preToolUse hook
+ * allows or denies the call. For built-in Cursor tools (Shell, Read, etc.),
+ * a separate local policy applies.
+ */
+/**
+ * Built-in (non-MCP) Cursor tools that mutate the workspace or execute
+ * commands. These require approval when auto_approve_all is false, mirroring
+ * the native harness's DANGEROUS_PLATFORM_TOOLS (write/edit/create/delete/
+ * execute/shell). Each value is an approval-message template resolved against
+ * the tool args (see resolveApprovalMessage); its placeholder names the same
+ * field the grant matcher keys on (path/command/target_notebook).
+ */
+const BUILT_IN_GATED = new Map([
+    ["Write", "Write file: {{args.path}}"],
+    ["StrReplace", "Edit file: {{args.path}}"],
+    ["EditNotebook", "Edit notebook: {{args.target_notebook}}"],
+    ["Shell", "Run command: {{args.command}}"],
+    ["Delete", "Delete: {{args.path}}"],
+]);
+/**
+ * Top-level tool-argument fields, in priority order, that identify the specific
+ * resource a built-in tool acts on. Used to render approval messages and to key
+ * HITL approval grants (see approval-state.ts). Authored here once and injected
+ * into the generated preToolUse hook script so the runner and the hook always
+ * agree on which field to match.
+ */
+export const SALIENT_ARG_FIELDS = ["path", "command", "target_notebook"];
+/**
+ * Check whether a built-in (non-MCP) Cursor tool requires user approval.
+ *
+ * Only the explicitly gated, mutating/destructive tools require approval;
+ * everything else (read-only built-ins, and — at the hook layer — auto-approved
+ * MCP tools) is allowed. This "gate the dangerous set, allow the rest" model
+ * mirrors the native harness's resolveToolApproval, which also defaults
+ * unlisted tools to no-approval. It is deliberately fail-OPEN for unknown
+ * tools: the merged MCP policy map carries only the tools that REQUIRE
+ * approval, so a fail-closed default would wrongly deny every auto-approved
+ * MCP tool, which the hook cannot distinguish from an unknown built-in by name.
+ */
+export function builtInRequiresApproval(toolName) {
+    return BUILT_IN_GATED.has(toolName);
+}
+/**
+ * Returns the built-in tool names that require approval (the gated set the
+ * preToolUse hook denies unless auto-approved or granted on reinvocation).
+ */
+export function getBuiltInGatedList() {
+    return [...BUILT_IN_GATED.keys()];
+}
+/**
+ * Approval-message template for a gated built-in tool, or undefined when the
+ * tool is not a known gated built-in. Callers resolve the placeholders against
+ * the tool args via resolveApprovalMessage.
+ */
+export function getBuiltInApprovalMessage(toolName) {
+    return BUILT_IN_GATED.get(toolName);
+}
+/**
+ * Extract the canonical "salient" argument value that identifies the resource a
+ * built-in tool acts on (the file path, the shell command, …). Returns "" when
+ * no salient field is present. Kept in lockstep with SALIENT_ARG_FIELDS and the
+ * generated hook script so grant matching at deny-time and reinvoke-time never
+ * drift.
+ */
+export function extractArgKey(args) {
+    if (!args)
+        return "";
+    for (const field of SALIENT_ARG_FIELDS) {
+        const v = args[field];
+        if (typeof v === "string" && v.length > 0)
+            return v;
+    }
+    return "";
+}
+/**
+ * Merge approval policies from all four levels into a single lookup map.
+ *
+ * Keys are the raw tool name (e.g., "apply_cloud_resource"). Each MCP server
+ * contributes its own set of policies, so the map is keyed by
+ * "serverSlug/toolName" to avoid collisions between servers.
+ *
+ * Policy chain (each level overrides the previous):
+ * 1. status.toolApprovals — presence means "requires approval"
+ * 2. spec.pinnedToolApprovals — presence means "requires approval" (overrides)
+ * 3. agent tool_approval_overrides — explicit boolean per tool
+ * 4. auto_approve_all — bypasses everything
+ *
+ * When auto_approve_all is true, the returned map is empty (no tool
+ * requires approval).
+ */
+export function mergeApprovalPolicies(resolvedServers, agentOverrides, autoApproveAll) {
+    const merged = new Map();
+    if (autoApproveAll)
+        return merged;
+    for (const server of resolvedServers) {
+        const serverPolicies = new Map();
+        // Layer 1: system-generated defaults (presence = requires approval)
+        for (const policy of server.toolApprovals) {
+            if (!policy.toolName)
+                continue;
+            serverPolicies.set(policy.toolName, {
+                requiresApproval: true,
+                message: policy.message || `Execute tool: ${policy.toolName}`,
+            });
+        }
+        // Layer 2: manual overrides (presence = requires approval, overrides layer 1)
+        for (const pinned of server.pinnedToolApprovals) {
+            if (!pinned.toolName)
+                continue;
+            serverPolicies.set(pinned.toolName, {
+                requiresApproval: true,
+                message: pinned.message || serverPolicies.get(pinned.toolName)?.message || `Execute tool: ${pinned.toolName}`,
+            });
+        }
+        // Layer 3: per-agent overrides (explicit boolean, can enable or disable)
+        for (const override of agentOverrides) {
+            if (!override.toolName)
+                continue;
+            const existing = serverPolicies.get(override.toolName);
+            if (existing) {
+                existing.requiresApproval = override.requiresApproval;
+                if (override.message) {
+                    existing.message = override.message;
+                }
+            }
+            else if (override.requiresApproval) {
+                serverPolicies.set(override.toolName, {
+                    requiresApproval: true,
+                    message: override.message || `Execute tool: ${override.toolName}`,
+                });
+            }
+        }
+        // Write merged policies into the result map
+        for (const [toolName, policy] of serverPolicies) {
+            if (!policy.requiresApproval)
+                continue;
+            const key = `${server.slug}/${toolName}`;
+            merged.set(key, {
+                toolName,
+                mcpServerSlug: server.slug,
+                requiresApproval: true,
+                approvalMessage: policy.message,
+            });
+        }
+    }
+    return merged;
+}
+/**
+ * Look up whether an MCP tool requires approval.
+ *
+ * @param toolName - The actual MCP tool name (e.g., "apply_cloud_resource")
+ * @param mcpServerSlug - The MCP server slug (e.g., "planton")
+ * @param policies - The merged policy map from mergeApprovalPolicies()
+ * @returns The policy if approval is required, undefined if auto-approved
+ */
+export function lookupMcpToolPolicy(toolName, mcpServerSlug, policies) {
+    return policies.get(`${mcpServerSlug}/${toolName}`);
+}
+/**
+ * Resolve {{args.field}} placeholders in an approval message using the
+ * tool's actual arguments.
+ *
+ * Placeholder syntax matches the proto-documented format:
+ * - {{args.field_name}} — replaced with the argument value
+ * - {{tool_name}} — replaced with the tool name
+ * - Missing fields are replaced with "<unknown>"
+ */
+export function resolveApprovalMessage(template, toolName, args) {
+    return template
+        .replace(/\{\{tool_name\}\}/g, toolName)
+        .replace(/\{\{args\.(\w+)\}\}/g, (_match, field) => {
+        const value = args[field];
+        if (value === undefined || value === null)
+            return "<unknown>";
+        if (typeof value === "string")
+            return value;
+        return JSON.stringify(value);
+    });
+}
+//# sourceMappingURL=approval-policy.js.map

package/dist/activities/execute-cursor/approval-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-policy.js","sourceRoot":"","sources":["../../../src/activities/execute-cursor/approval-policy.ts"],"names":[],"mappings":"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"}

package/dist/activities/execute-cursor/approval-state.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Approval state management for the hook-deny + reinvoke HITL model.
+ *
+ * Before starting a Cursor Agent run, the cursor-runner writes a state file
+ * to the workspace. The preToolUse hook script reads this file to decide
+ * whether to allow or deny each tool call.
+ *
+ * State file format (JSON):
+ * {
+ *   "autoApproveAll": false,
+ *   "builtInGatedList": ["Write", "StrReplace", "Shell", ...],
+ *   "mcpToolPolicies": {
+ *     "apply_cloud_resource": { "requiresApproval": true, "message": "..." }
+ *   },
+ *   "approvedGrants": [{ "toolName": "Write", "mcpServerSlug": "", "argKey": "a.txt" }],
+ *   "approvedGrantTokens": ["V3JpdGUKYS50eHQ="]
+ * }
+ *
+ * The hook gates only the explicitly dangerous set (builtInGatedList) and the
+ * MCP tools that require approval (mcpToolPolicies, which by construction holds
+ * only require-approval entries); every other tool is allowed. This mirrors the
+ * native harness and avoids denying auto-approved MCP tools, which are absent
+ * from the policy map and indistinguishable from unknown tools by name.
+ *
+ * Why grants instead of tool-call ids: a resumed Cursor agent re-issues the
+ * approved tool with a BRAND NEW call id, so matching on the original call id
+ * can never let the re-attempt through. Instead we grant by tool identity —
+ * tool name plus a "salient" argument (the file path for Write, the command for
+ * Shell, …; see extractArgKey). On reinvocation the hook allows a tool call
+ * only if its (name, salient-arg) matches an approved grant; rejected/skipped
+ * tools and any newly proposed dangerous tool are re-gated.
+ *
+ * Tokens: the hook is a self-contained bash script, so it cannot parse an array
+ * of grant objects. `approvedGrantTokens` is the flat, base64-encoded form of
+ * each grant that the hook matches by simple string membership. The structured
+ * `approvedGrants` is retained for readability, debugging, and tests; the two
+ * are always generated together from the same source.
+ *
+ * Denial ledger (hook → runner):
+ * The state file is the runner's INPUT to the hook. Its symmetric OUTPUT is the
+ * denial ledger (stigmer-denials.jsonl): when the hook denies a tool, it appends
+ * the call's identity token to this file. The runner reads the ledger after the
+ * run to learn which tool calls were gated — the hook is the only component that
+ * actually makes the per-call allow/deny decision, so its ledger is the
+ * authoritative "what was denied this turn" signal (the cursor analog of the
+ * native harness's LangGraph interrupts). The token uses the SAME identity space
+ * as approvedGrantTokens, so a denial token approved this turn becomes a grant
+ * token next turn.
+ */
+import { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { PendingApproval } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
+import type { AgentMessage } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import type { MergedToolPolicy } from "./approval-policy.js";
+export interface McpToolPolicyEntry {
+    requiresApproval: boolean;
+    message?: string;
+}
+/**
+ * The identity of an approved tool call, stable across agent resume.
+ *
+ * - argKey is the salient argument (path/command/…) for built-in tools; matched
+ *   exactly so only the approved resource is allowed through on the resumed turn.
+ * - argKey is empty for MCP tools (and built-in tools with no salient field);
+ *   the grant then matches by name alone, since the user approved that tool.
+ */
+export interface ApprovalGrant {
+    toolName: string;
+    mcpServerSlug: string;
+    argKey: string;
+}
+export interface ApprovalStateFile {
+    autoApproveAll: boolean;
+    builtInGatedList: string[];
+    mcpToolPolicies: Record<string, McpToolPolicyEntry>;
+    approvedGrants: ApprovalGrant[];
+    approvedGrantTokens: string[];
+}
+/**
+ * Compute the flat token the bash hook matches on. The hook recomputes the same
+ * token from the incoming tool call (`base64(toolName \n salientArg)`), so the
+ * encoding here must stay byte-identical to the hook script in hook-script.ts.
+ */
+export declare function grantToken(toolName: string, argKey: string): string;
+/**
+ * Build approval grants from the pending approvals the user adjudicated and
+ * their decisions. Only APPROVE decisions produce grants. Built-in tools are
+ * keyed by their salient argument; MCP tools are keyed by name only.
+ */
+export declare function buildApprovalGrants(pendingApprovals: PendingApproval[], decisions: Map<string, ApprovalAction>): ApprovalGrant[];
+/**
+ * Build the approval state file content from merged policies and any approval
+ * grants from a previous HITL cycle.
+ *
+ * The state file drives the hook script's allow/deny decisions:
+ * - builtInGatedList: dangerous built-in tools the hook denies (unless granted)
+ * - mcpToolPolicies: per-tool policy for MCP tools requiring approval
+ * - approvedGrants / approvedGrantTokens: tools approved in the current HITL
+ *   cycle, allowed through on reinvocation
+ */
+export declare function buildApprovalState(mergedPolicies: Map<string, MergedToolPolicy>, autoApproveAll: boolean, grants?: ApprovalGrant[]): ApprovalStateFile;
+/**
+ * Write the approval state file to the workspace for the hook script to read.
+ *
+ * Written as COMPACT JSON (no indentation): the bash hook parses it with
+ * line-oriented grep patterns that assume `"key":value` with no spaces or
+ * newlines (e.g. `"autoApproveAll":true`, `"name":{...}`). Pretty-printing
+ * would break every lookup.
+ */
+export declare function writeApprovalStateFile(workspaceRoot: string, state: ApprovalStateFile): Promise<string>;
+/**
+ * One denial recorded by the preToolUse hook. `token` is the call's identity in
+ * the same space as grantToken() (base64 of `toolName \n salientArg`), used to
+ * correlate the denial back to the streamed tool call. `toolName` is carried raw
+ * for human-readable debugging of the ledger file.
+ */
+export interface DeniedLedgerEntry {
+    toolName: string;
+    token: string;
+}
+/** Absolute path of the per-turn denial ledger the hook appends to. */
+export declare function denialLedgerPath(workspaceRoot: string): string;
+/**
+ * Truncate the denial ledger to empty for a fresh turn, returning its path.
+ *
+ * Called every turn alongside writeApprovalStateFile (the workspace is durable
+ * and reused across HITL reinvocations), so the runner only ever reads denials
+ * produced by the current run. A Temporal activity retry re-runs this reset
+ * before re-running the agent, so the read stays deterministic under retries.
+ */
+export declare function resetDenialLedger(workspaceRoot: string): Promise<string>;
+/**
+ * Read the denial ledger written by the hook during the turn. Missing file →
+ * no denials. Blank or partially-written lines are tolerated (the hook appends
+ * line-by-line and a run can be interrupted), so a malformed tail never hides
+ * the valid denials before it.
+ */
+export declare function readDenialLedger(workspaceRoot: string): Promise<DeniedLedgerEntry[]>;
+/**
+ * Reconstruct the adjudicated approvals for a HITL reinvocation directly from
+ * the tool calls in messages.
+ *
+ * The tool call — not pending_approvals — is the source of truth for an approval
+ * decision. The backend projects pending_approvals from tool-call status
+ * (PendingApprovalComputer) and CLEARS entries once they carry an approval_action,
+ * so by the time the workflow reinvokes this activity, pending_approvals is empty
+ * and the decision survives only on the tool call (status WAITING_APPROVAL +
+ * approval_action set). This mirrors the native harness
+ * (execute-deep-agent/hitl.ts extractApprovalDecisions).
+ *
+ * Returns a PendingApproval list reconstructed from those tool calls (so the
+ * existing grant/prompt builders work unchanged) alongside the decision map.
+ */
+export interface AdjudicatedApprovals {
+    pendingApprovals: PendingApproval[];
+    decisions: Map<string, ApprovalAction>;
+}
+export declare function reconstructAdjudicatedApprovals(messages: AgentMessage[]): AdjudicatedApprovals;