@stigmer/runner 3.0.9-dev.20260615153829 → 3.1.0

package/src/shared/filereview/secret-paths.ts

@@ -0,0 +1,121 @@
+/**
+ * The secret-safety gate for CAS capture (design doc 12).
+ *
+ * The git substrate never captures gitignored paths, which was an accidental
+ * safety property: `.gitignore` is where projects keep secrets (`.env`, private
+ * keys, credentials). The CAS substrate's whole purpose is to start capturing
+ * ignored / non-git paths — so, done naively, it would write secret bytes into
+ * durable artifact storage. This module is the fail-closed gate that prevents
+ * that: a path classified secret-like is BLOCKED from capture (authored as
+ * DIFF_UNREVIEWABLE instead) and its bytes never leave the workspace.
+ *
+ * Scope discipline (design doc 12 D2): this is deliberately a small, explicit,
+ * deterministic matcher — NOT the Phase-4 `sensitivity` taxonomy, NOT ML. It is
+ * a pure function over the path, so the cross-edition corpus can lock it (a path
+ * either blocks or captures, identically everywhere). The matcher errs toward
+ * blocking: a path only needs to LOOK secret-like to be withheld, because the
+ * cost of withholding a non-secret (it stays on the deny-gate, as today) is far
+ * lower than the cost of persisting a real secret.
+ *
+ * @since File-Change HITL Redesign (Phase 3 — CAS / DD-E)
+ */
+
+/**
+ * Basename patterns that mark a file secret-like. Matched case-insensitively
+ * against the final path segment. Kept as an explicit, reviewable list — adding
+ * a pattern is a deliberate, corpus-locked change, never a heuristic guess.
+ */
+export const SECRET_BASENAME_PATTERNS: readonly RegExp[] = [
+  /^\.env(\..+)?$/, // .env, .env.local, .env.production, ...
+  /^\.npmrc$/,
+  /^\.netrc$/,
+  /^\.pgpass$/,
+  /^\.htpasswd$/,
+  /^credentials(\.[A-Za-z0-9]+)?$/, // credentials, credentials.json, ...
+  /^secrets?(\.[A-Za-z0-9]+)?$/, // secret / secrets / secrets.yaml, ...
+  /^id_(rsa|dsa|ecdsa|ed25519)$/, // private SSH keys (no .pub)
+  /.*\.(pem|key|pfx|p12|keystore|jks|asc|ppk)$/,
+  /.*\.tfstate(\.backup)?$/, // terraform state embeds secrets
+  /.*\.tfvars$/,
+  /.*\.(kdbx)$/, // password databases
+];
+
+/**
+ * Path-fragment patterns that mark a file secret-like by WHERE it lives, matched
+ * against the normalized (forward-slash) full path. Covers credential stores
+ * whose basenames alone are ambiguous.
+ */
+export const SECRET_PATH_PATTERNS: readonly RegExp[] = [
+  /(^|\/)\.ssh\//, // ~/.ssh/* and repo-local .ssh/*
+  /(^|\/)\.aws\/credentials$/,
+  /(^|\/)\.gnupg\//,
+  /(^|\/)\.docker\/config\.json$/,
+  /(^|\/)\.kube\/config$/,
+];
+
+/** The final path segment (basename), for both `/` and `\` separators. */
+function basename(path: string): string {
+  const normalized = path.replace(/\\/g, "/");
+  const idx = normalized.lastIndexOf("/");
+  return idx >= 0 ? normalized.slice(idx + 1) : normalized;
+}
+
+/**
+ * Whether a path is secret-like and must NOT be captured into the durable CAS
+ * store. Fail-closed: an empty/unknown path is treated as secret-like (withheld)
+ * rather than captured.
+ */
+export function isSecretLikePath(path: string): boolean {
+  if (!path) return true;
+  const normalized = path.replace(/\\/g, "/");
+  const base = basename(normalized).toLowerCase();
+
+  for (const re of SECRET_BASENAME_PATTERNS) {
+    if (re.test(base)) return true;
+  }
+  const lowerPath = normalized.toLowerCase();
+  for (const re of SECRET_PATH_PATTERNS) {
+    if (re.test(lowerPath)) return true;
+  }
+  return false;
+}
+
+/** How the turn's observed gitignored paths split under the secret gate. */
+export interface CasSecretPartition {
+  /** Paths safe to capture into durable CAS (their bytes may be persisted). */
+  readonly capturablePaths: readonly string[];
+  /**
+   * Paths withheld from capture — authored as content-less DIFF_UNREVIEWABLE.
+   * The union of the gate's up-front blocks and any observed secret-like path.
+   */
+  readonly unreviewablePaths: readonly string[];
+}
+
+/**
+ * Split a turn's observed gitignored paths into capturable vs withheld — the
+ * single source of truth for "which ignored bytes may reach durable storage".
+ *
+ * `unreviewablePaths = gateBlockedPaths ∪ { p ∈ observed : isSecretLikePath(p) }`
+ * and `capturablePaths = { p ∈ observed : ¬isSecretLikePath(p) }`. The
+ * `isSecretLikePath` re-check over `observed` is the fail-closed backstop that
+ * holds **even under the global bypass** (`spec.auto_approve_all`): there the
+ * approval gate is not installed, so `gateBlockedPaths` is empty and this
+ * re-check is the only thing keeping a secret's bytes out of CAS. Order is
+ * preserved (gate blocks first, then observed order) and duplicates are folded,
+ * so the result is deterministic for the cross-edition corpus.
+ */
+export function partitionIgnoredPathsBySecret(
+  observedPaths: Iterable<string>,
+  gateBlockedPaths: ReadonlySet<string>,
+): CasSecretPartition {
+  const unreviewable = new Set<string>(gateBlockedPaths);
+  const capturablePaths: string[] = [];
+  for (const path of observedPaths) {
+    if (isSecretLikePath(path)) {
+      unreviewable.add(path);
+      continue;
+    }
+    capturablePaths.push(path);
+  }
+  return { capturablePaths, unreviewablePaths: [...unreviewable] };
+}

package/src/shared/fingerprint-secret.ts

@@ -0,0 +1,53 @@
+/**
+ * Runner-held master secret for HITL approval fingerprints (Phase 2).
+ *
+ * The per-execution fingerprint key is derived from this secret + `execution_id`
+ * (see {@link file://./approval-fingerprint.ts} `deriveExecutionFingerprintKey`).
+ * Source precedence:
+ *
+ *  1. `STIGMER_RUNNER_HITL_SECRET` env var (UTF-8), when set — the only way to get
+ *     a key that is STABLE across runner processes/replicas. Required once a lease
+ *     becomes a cross-process bearer token (Phase 7); optional today.
+ *  2. A per-process random secret generated once at first use — sufficient for
+ *     Phase 2 because the fingerprint is recompute-and-compare WITHIN one runner
+ *     process for a given execution: the deep-agent gateway runs in-process, and
+ *     the Cursor key is written to and read from the per-session state file by the
+ *     same process. A process restart re-keys, which can only *re-ask* a pending
+ *     approval (fail-safe), never silently mis-authorize.
+ *
+ * The secret is never logged. The value is memoized so the per-process fallback
+ * stays stable for the lifetime of the process.
+ */
+
+import { randomBytes, type BinaryLike } from "node:crypto";
+
+const ENV_VAR = "STIGMER_RUNNER_HITL_SECRET";
+
+let cached: Buffer | undefined;
+let warned = false;
+
+/**
+ * Return the runner's HITL master secret (env-configured, else a stable
+ * per-process random fallback). Memoized.
+ */
+export function getRunnerHitlMasterSecret(): BinaryLike {
+  if (cached) return cached;
+
+  const fromEnv = process.env[ENV_VAR];
+  if (fromEnv && fromEnv.length > 0) {
+    cached = Buffer.from(fromEnv, "utf-8");
+    return cached;
+  }
+
+  cached = randomBytes(32);
+  if (!warned) {
+    warned = true;
+    console.warn(
+      `[hitl-gateway] ${ENV_VAR} is not set; using a per-process random ` +
+      "fingerprint secret. Fingerprints are stable within this process only — " +
+      `set ${ENV_VAR} for a key stable across runner restarts/replicas ` +
+      "(required in Phase 7).",
+    );
+  }
+  return cached;
+}

package/src/shared/model-client.ts

@@ -0,0 +1,122 @@
+/**
+ * Single construction point for LangChain chat models in the runner.
+ *
+ * This is the only place that translates a Stigmer registry model ID
+ * (dot-notation, e.g. "claude-haiku-4.5") into the provider's API model ID
+ * (e.g. "claude-haiku-4-5-20251001") before a client is built — so no
+ * activity can bypass the translation and 404 the provider.
+ *
+ * Layering: `llm-proxy.ts` stays pure routing utilities (no LangChain
+ * dependency); this module is the LangChain-aware layer above it that owns
+ * the resolve -> infer-provider -> strip-prefix -> proxy-wire -> construct
+ * sequence that used to be copy-pasted across every LLM activity.
+ */
+
+import { ChatAnthropic } from "@langchain/anthropic";
+import { ChatOpenAI } from "@langchain/openai";
+import type { BaseChatModel } from "@langchain/core/language_models/chat_models";
+
+import {
+  inferProvider,
+  stripProviderPrefix,
+  resolveProxyBaseUrl,
+  buildProxyHeaders,
+  type LlmProvider,
+} from "./llm-proxy.js";
+import { resolveToApiModelId } from "./model-registry.js";
+
+export interface BuildChatModelOptions {
+  /** Registry id ("claude-haiku-4.5"), "provider:model", or a provider API id. */
+  readonly modelName: string;
+  /** When set, requests route through the Stigmer proxy at the provider path. */
+  readonly proxyEndpoint?: string;
+  readonly stigmerToken?: string;
+  /** Scope headers for proxy FGA/billing attribution. */
+  readonly headerScope?: {
+    executionId?: string;
+    mcpServerId?: string;
+    workflowExecutionId?: string;
+  };
+  /** Defaults to 0. */
+  readonly temperature?: number;
+  /**
+   * Pass-through only; intentionally no default. Anthropic requires a value,
+   * but callers differ (setup omits it, call-llm uses 4096), so the default
+   * stays the caller's decision to avoid silently changing behavior.
+   */
+  readonly maxTokens?: number;
+  readonly timeoutMs?: number;
+  readonly maxRetries?: number;
+}
+
+export interface BuiltChatModel {
+  readonly model: BaseChatModel;
+  readonly provider: LlmProvider;
+  /** The resolved id actually handed to the provider. */
+  readonly apiModelId: string;
+}
+
+/**
+ * Build a configured chat model, resolving the registry id to a provider API
+ * id first. The resolution MUST precede provider inference and prefix
+ * stripping — that ordering is the invariant each per-site copy kept dropping,
+ * surfacing as `404 model: claude-haiku-4.5` at the provider.
+ */
+export async function buildChatModel(opts: BuildChatModelOptions): Promise<BuiltChatModel> {
+  const resolved = await resolveToApiModelId(opts.modelName);
+  const provider = inferProvider(resolved);
+  const apiModelId = stripProviderPrefix(resolved);
+
+  const baseUrl = opts.proxyEndpoint
+    ? resolveProxyBaseUrl(opts.proxyEndpoint, provider)
+    : undefined;
+  const headers = opts.proxyEndpoint && opts.stigmerToken
+    ? buildProxyHeaders(opts.stigmerToken, opts.headerScope ?? {})
+    : undefined;
+
+  // Proxy mode authenticates with the Stigmer token; direct mode falls back to
+  // the provider's own env-var key.
+  const apiKey = opts.proxyEndpoint
+    ? (opts.stigmerToken ?? "proxy-managed")
+    : provider === "openai"
+      ? (process.env.OPENAI_API_KEY ?? "")
+      : (process.env.ANTHROPIC_API_KEY ?? "");
+
+  const common = {
+    temperature: opts.temperature ?? 0,
+    apiKey,
+    ...(opts.maxTokens ? { maxTokens: opts.maxTokens } : {}),
+    ...(opts.timeoutMs ? { maxRetries: opts.maxRetries ?? 0, timeout: opts.timeoutMs } : {}),
+  };
+
+  // The two SDKs name the transport-override block differently (OpenAI:
+  // `configuration`, Anthropic: `clientOptions`) — encapsulating that here is
+  // the whole point, since the shape mismatch is where bugs used to hide.
+  const model: BaseChatModel = provider === "openai"
+    ? new ChatOpenAI({
+        model: apiModelId,
+        ...common,
+        ...(baseUrl || headers
+          ? {
+              configuration: {
+                ...(baseUrl ? { baseURL: baseUrl } : {}),
+                ...(headers ? { defaultHeaders: headers } : {}),
+              },
+            }
+          : {}),
+      })
+    : new ChatAnthropic({
+        model: apiModelId,
+        ...common,
+        ...(baseUrl || headers
+          ? {
+              clientOptions: {
+                ...(baseUrl ? { baseURL: baseUrl } : {}),
+                ...(headers ? { defaultHeaders: headers } : {}),
+              },
+            }
+          : {}),
+      });
+
+  return { model, provider, apiModelId };
+}

package/src/shared/plan-artifact.ts

@@ -87,7 +87,6 @@ export async function publishPlanArtifact(opts: {
     const storageKey = `artifacts/${executionId}/${PLAN_ARTIFACT_NAME}`;
 
     await artifactStorage.upload(storageKey, content, "text/markdown");
-    const downloadUrl = await artifactStorage.getDownloadUrl(storageKey);
 
     const artifact = create(ExecutionArtifactSchema, {
       name: PLAN_ARTIFACT_NAME,
@@ -95,7 +94,6 @@ export async function publishPlanArtifact(opts: {
       kind: ExecutionArtifactKind.FILE,
       sizeBytes: BigInt(content.length),
       storageKey,
-      downloadUrl,
       createdAt: utcTimestamp(),
       contentHash,
     });