@stigmer/runner 3.0.1

package/src/activities/execute-cursor/model-pricing-data.ts

@@ -0,0 +1,167 @@
+/**
+ * Cursor model pricing data — fetched from the authenticated model registry API.
+ *
+ * On first access (or after the TTL expires), fetches the full model
+ * registry from the Stigmer Cloud API, filters to cursor-harness models,
+ * and caches the result in memory. Falls back to conservative default
+ * pricing if the API is unreachable.
+ *
+ * Environment variables:
+ * - STIGMER_CLOUD_API_URL: API base URL (defaults to https://api.stigmer.ai)
+ * - STIGMER_AUTH_TOKEN: Bearer token for authentication (required)
+ */
+
+/** Per-million rates for a speed/mode variant (e.g. "fast") of a base model. */
+export interface CursorVariantPricing {
+  readonly inputPricePerMillion: number;
+  readonly outputPricePerMillion: number;
+  readonly cacheWritePricePerMillion: number;
+  readonly cacheReadPricePerMillion: number;
+}
+
+export interface CursorModelPricing {
+  readonly model: string;
+  readonly displayName: string;
+  readonly costTier: string;
+  readonly inputPricePerMillion: number;
+  readonly outputPricePerMillion: number;
+  readonly cacheWritePricePerMillion: number;
+  readonly cacheReadPricePerMillion: number;
+  /** Speed-mode price overrides keyed by variant (e.g. "fast"); optional. */
+  readonly speedVariants?: Readonly<Record<string, CursorVariantPricing>>;
+}
+
+interface RegistryVariantEntry {
+  inputPricePerMillion: number;
+  outputPricePerMillion: number;
+  cacheWritePricePerMillion: number;
+  cacheReadPricePerMillion: number;
+}
+
+interface RegistryEntry {
+  id: string;
+  displayName: string;
+  provider: string;
+  harness: string;
+  costTier?: string;
+  pricing?: {
+    inputPricePerMillion: number;
+    outputPricePerMillion: number;
+    cacheWritePricePerMillion: number;
+    cacheReadPricePerMillion: number;
+  };
+  pricingVariants?: Record<string, RegistryVariantEntry>;
+}
+
+const DEFAULT_API_URL = "https://api.stigmer.ai";
+const CACHE_TTL_MS = 3_600_000; // 1 hour
+
+const DEFAULT_PRICING: CursorModelPricing = {
+  model: "unknown",
+  displayName: "Unknown",
+  costTier: "standard",
+  inputPricePerMillion: 1.25,
+  outputPricePerMillion: 6.00,
+  cacheWritePricePerMillion: 1.25,
+  cacheReadPricePerMillion: 0.25,
+};
+
+let cache: { data: readonly CursorModelPricing[]; expiresAt: number } | null = null;
+let inflightFetch: Promise<readonly CursorModelPricing[]> | null = null;
+
+function getApiUrl(): string {
+  return process.env.STIGMER_CLOUD_API_URL ?? DEFAULT_API_URL;
+}
+
+function getAuthToken(): string | undefined {
+  return process.env.STIGMER_TOKEN ?? process.env.STIGMER_AUTH_TOKEN;
+}
+
+function parsePricingTable(json: unknown): CursorModelPricing[] {
+  if (!json || typeof json !== "object") return [];
+  const models = (json as Record<string, unknown>).models;
+  if (!Array.isArray(models)) return [];
+
+  return (models as RegistryEntry[])
+    .filter((m) => m.harness === "cursor" && m.pricing != null)
+    .map((m) => ({
+      model: m.id,
+      displayName: m.displayName,
+      costTier: m.costTier ?? "standard",
+      inputPricePerMillion: m.pricing!.inputPricePerMillion,
+      outputPricePerMillion: m.pricing!.outputPricePerMillion,
+      cacheWritePricePerMillion: m.pricing!.cacheWritePricePerMillion,
+      cacheReadPricePerMillion: m.pricing!.cacheReadPricePerMillion,
+      speedVariants: parseVariants(m.pricingVariants),
+    }));
+}
+
+function parseVariants(
+  variants: Record<string, RegistryVariantEntry> | undefined,
+): Record<string, CursorVariantPricing> | undefined {
+  if (!variants || typeof variants !== "object") return undefined;
+  const out: Record<string, CursorVariantPricing> = {};
+  for (const [key, v] of Object.entries(variants)) {
+    if (!v || typeof v !== "object") continue;
+    out[key] = {
+      inputPricePerMillion: v.inputPricePerMillion,
+      outputPricePerMillion: v.outputPricePerMillion,
+      cacheWritePricePerMillion: v.cacheWritePricePerMillion,
+      cacheReadPricePerMillion: v.cacheReadPricePerMillion,
+    };
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+async function fetchFromApi(): Promise<readonly CursorModelPricing[]> {
+  const url = `${getApiUrl()}/v1/proxy/model-registry`;
+  const headers: Record<string, string> = {};
+  const token = getAuthToken();
+  if (token) {
+    headers["Authorization"] = `Bearer ${token}`;
+  }
+  const res = await fetch(url, { headers });
+  if (!res.ok) throw new Error(`Model registry fetch failed: ${res.status}`);
+  const data: unknown = await res.json();
+  const table = parsePricingTable(data);
+  if (table.length === 0) {
+    throw new Error("Model registry returned no cursor-harness models");
+  }
+  return table;
+}
+
+/**
+ * Get the cursor model pricing table from the cached API response.
+ *
+ * Deduplicates concurrent calls — only one fetch is in-flight at a time.
+ * Falls back to an array containing only {@link DEFAULT_PRICING} if the
+ * API is unreachable.
+ */
+export async function getPricingTable(): Promise<readonly CursorModelPricing[]> {
+  if (cache && Date.now() < cache.expiresAt) {
+    return cache.data;
+  }
+
+  if (inflightFetch) return inflightFetch;
+
+  inflightFetch = fetchFromApi()
+    .then((data) => {
+      cache = { data, expiresAt: Date.now() + CACHE_TTL_MS };
+      return data;
+    })
+    .catch((err) => {
+      console.warn(
+        `Failed to fetch model registry from API, using default pricing: ${err}`,
+      );
+      const fallback = [DEFAULT_PRICING];
+      cache = { data: fallback, expiresAt: Date.now() + CACHE_TTL_MS };
+      return fallback;
+    })
+    .finally(() => {
+      inflightFetch = null;
+    });
+
+  return inflightFetch;
+}
+
+export { DEFAULT_PRICING };

package/src/activities/execute-cursor/model-pricing.ts

@@ -0,0 +1,167 @@
+/**
+ * Cursor model pricing lookup, validation, and cost computation.
+ *
+ * Pricing data is fetched from the public model registry API and cached
+ * locally with a 1-hour TTL. The pricing map is initialized on first
+ * access via {@link ensureLoaded}.
+ */
+
+import { getPricingTable, DEFAULT_PRICING } from "./model-pricing-data.js";
+import type { CursorModelPricing } from "./model-pricing-data.js";
+
+export type { CursorModelPricing };
+
+/**
+ * Strip provider date suffixes from model IDs so that e.g.
+ * "claude-haiku-4-5-20251001" matches the registry entry "claude-haiku-4-5".
+ * Matches date-like suffixes: -YYYYMMDD or -YYYYMMDDvN at end of string.
+ */
+function normalizeModelId(model: string): string {
+  return model.replace(/-\d{8}(?:v\d+)?$/, "");
+}
+
+/**
+ * Speed-mode suffixes Cursor appends to a base model id (longest first).
+ * Only speed variants change the per-token price; effort suffixes do not.
+ */
+const SPEED_SUFFIXES = ["-high-fast", "-medium-fast", "-low-fast", "-fast"];
+
+/**
+ * If `model` carries a speed suffix, return the base id; otherwise null.
+ * e.g. "composer-2.5-fast" -> "composer-2.5".
+ */
+function stripSpeedSuffix(model: string): string | null {
+  for (const suffix of SPEED_SUFFIXES) {
+    if (model.endsWith(suffix)) return model.slice(0, -suffix.length);
+  }
+  return null;
+}
+
+/**
+ * Return a copy of a base pricing entry with its "fast" variant rates applied,
+ * preserving the original (wire) model id. Returns null when the base declares
+ * no fast variant.
+ */
+function applyFastVariant(
+  base: CursorModelPricing,
+  wireModel: string,
+): CursorModelPricing | null {
+  const fast = base.speedVariants?.fast;
+  if (!fast) return null;
+  return {
+    ...base,
+    model: wireModel,
+    inputPricePerMillion: fast.inputPricePerMillion,
+    outputPricePerMillion: fast.outputPricePerMillion,
+    cacheWritePricePerMillion: fast.cacheWritePricePerMillion,
+    cacheReadPricePerMillion: fast.cacheReadPricePerMillion,
+  };
+}
+
+let pricingByModel: Map<string, CursorModelPricing> | null = null;
+let initPromise: Promise<void> | null = null;
+
+/**
+ * Ensure the pricing map has been populated from the API cache.
+ *
+ * Call this once at service startup or before the first pricing lookup.
+ * Subsequent calls are no-ops while the cache is fresh.
+ */
+export async function ensureLoaded(): Promise<void> {
+  if (initPromise) return initPromise;
+
+  initPromise = getPricingTable().then((table) => {
+    pricingByModel = new Map(table.map((entry) => [entry.model, entry]));
+  });
+
+  return initPromise;
+}
+
+function getMap(): Map<string, CursorModelPricing> {
+  if (!pricingByModel) {
+    console.warn("Model pricing accessed before ensureLoaded() — returning empty map");
+    return new Map();
+  }
+  return pricingByModel;
+}
+
+/**
+ * Validate a requested model ID against the pricing registry.
+ * Returns the model ID if it has a pricing entry, otherwise falls back
+ * to "default". Tries the exact ID first, then a normalized version
+ * with date suffixes stripped.
+ */
+export function resolveModelId(requestedModel: string): string {
+  if (!requestedModel || requestedModel === "default") return "default";
+  const map = getMap();
+  if (map.has(requestedModel)) return requestedModel;
+
+  const normalized = normalizeModelId(requestedModel);
+  if (normalized !== requestedModel && map.has(normalized)) return normalized;
+
+  console.warn(
+    `Model "${requestedModel}" (normalized: "${normalized}") not in pricing registry (${map.size} models), falling back to "default"`,
+  );
+  return "default";
+}
+
+/**
+ * Look up pricing for a Cursor model. Falls back to Auto-pool rates for
+ * unknown models (conservative default that avoids undercharging).
+ * Tries the exact ID first, then a normalized version with date suffixes
+ * stripped.
+ */
+export function getCursorModelPricing(model: string): CursorModelPricing {
+  const map = getMap();
+  const exact = map.get(model);
+  if (exact) return exact;
+
+  // Speed variant (e.g. "composer-2.5-fast"): resolve the base entry and apply
+  // its fast-tier rates so the display estimate matches the authoritative bill.
+  const speedBase = stripSpeedSuffix(model);
+  if (speedBase) {
+    const baseEntry = map.get(speedBase) ?? map.get(normalizeModelId(speedBase));
+    if (baseEntry) {
+      const fast = applyFastVariant(baseEntry, model);
+      if (fast) return fast;
+    }
+  }
+
+  const normalized = normalizeModelId(model);
+  if (normalized !== model) {
+    const byNormalized = map.get(normalized);
+    if (byNormalized) return byNormalized;
+  }
+
+  console.warn(
+    `Pricing lookup miss for "${model}" (normalized: "${normalized}"), using DEFAULT_PRICING`,
+  );
+  return { ...DEFAULT_PRICING, model };
+}
+
+/**
+ * Compute USD cost for a single turn.
+ *
+ * The Cursor SDK follows Anthropic's convention: `inputTokens` is the
+ * TOTAL input tokens including cached portions. `cacheReadTokens` and
+ * `cacheWriteTokens` are subsets of `inputTokens`, not additive buckets.
+ *
+ * To avoid double-counting, we subtract cached tokens from inputTokens
+ * before applying the regular input rate:
+ *   regularInput = inputTokens - cacheReadTokens - cacheWriteTokens
+ */
+export function computeTurnCost(
+  pricing: CursorModelPricing,
+  inputTokens: number,
+  outputTokens: number,
+  cacheWriteTokens: number,
+  cacheReadTokens: number,
+): number {
+  const regularInput = Math.max(0, inputTokens - cacheReadTokens - cacheWriteTokens);
+  return (
+    regularInput * pricing.inputPricePerMillion
+    + outputTokens * pricing.outputPricePerMillion
+    + cacheWriteTokens * pricing.cacheWritePricePerMillion
+    + cacheReadTokens * pricing.cacheReadPricePerMillion
+  ) / 1_000_000;
+}

package/src/activities/execute-cursor/placeholder-resolver.ts

@@ -0,0 +1,109 @@
+/**
+ * Strict placeholder resolver for ${VAR_NAME} syntax in MCP server configs.
+ *
+ * Port of the Python agent-runner's PlaceholderResolver (strict mode only).
+ * Always raises on unresolved placeholders — sending literal ${VAR} as an
+ * HTTP header value (e.g. Authorization: Bearer ${API_KEY}) produces
+ * cryptic auth failures from the remote server.
+ */
+
+const PLACEHOLDER_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+
+export class PlaceholderResolutionError extends Error {
+  constructor(
+    public readonly variableName: string,
+    public readonly context?: string,
+  ) {
+    const where = context ? ` in ${context}` : "";
+    super(
+      `Unresolved placeholder \${${variableName}}${where}: ` +
+        `variable is not present in the execution environment`,
+    );
+    this.name = "PlaceholderResolutionError";
+  }
+}
+
+/**
+ * Resolve all ${VAR_NAME} placeholders in a template string.
+ *
+ * @throws PlaceholderResolutionError if any placeholder cannot be resolved.
+ */
+export function resolvePlaceholders(
+  template: string,
+  envVars: Record<string, string>,
+  context?: string,
+): string {
+  return template.replace(PLACEHOLDER_RE, (match, varName: string) => {
+    if (varName in envVars) {
+      return envVars[varName];
+    }
+    throw new PlaceholderResolutionError(varName, context);
+  });
+}
+
+/**
+ * Resolve placeholders in all values of a headers map.
+ *
+ * @throws PlaceholderResolutionError if any header value contains an
+ *   unresolvable placeholder.
+ */
+export function resolveHeaders(
+  headers: Record<string, string>,
+  envVars: Record<string, string>,
+): Record<string, string> {
+  const resolved: Record<string, string> = {};
+  for (const [key, value] of Object.entries(headers)) {
+    resolved[key] = resolvePlaceholders(value, envVars, `header "${key}"`);
+  }
+  return resolved;
+}
+
+/**
+ * Filter env vars to only keys declared in the MCP server's spec.env.
+ *
+ * Mirrors the agent-runner's _filter_env_to_declared_keys: prevents
+ * secret over-sharing by restricting the subprocess/HTTP environment to
+ * explicitly declared variables.
+ */
+export function filterEnvToDeclaredKeys(
+  declaredEnv: Record<string, unknown> | undefined,
+  envVars: Record<string, string>,
+  serverSlug: string,
+): Record<string, string> {
+  if (!declaredEnv || Object.keys(declaredEnv).length === 0) {
+    if (Object.keys(envVars).length > 0) {
+      console.log(
+        `MCP server '${serverSlug}' has no env declarations — ` +
+          `dropping ${Object.keys(envVars).length} env var(s)`,
+      );
+    }
+    return {};
+  }
+
+  const declaredKeys = new Set(Object.keys(declaredEnv));
+  const filtered: Record<string, string> = {};
+
+  for (const [key, value] of Object.entries(envVars)) {
+    if (declaredKeys.has(key)) {
+      filtered[key] = value;
+    }
+  }
+
+  const dropped = Object.keys(envVars).length - Object.keys(filtered).length;
+  if (dropped > 0) {
+    console.log(
+      `MCP server '${serverSlug}': passing ${Object.keys(filtered).length} ` +
+        `declared env var(s), filtered out ${dropped} undeclared key(s)`,
+    );
+  }
+
+  const missing = [...declaredKeys].filter((k) => !(k in filtered));
+  if (missing.length > 0) {
+    console.warn(
+      `MCP server '${serverSlug}': env declares [${missing.sort().join(", ")}] ` +
+        `but they are not present in the resolved environment`,
+    );
+  }
+
+  return filtered;
+}