@stigmer/runner 3.0.1

package/src/shared/placeholder-resolver.ts

@@ -0,0 +1,102 @@
+/**
+ * Strict placeholder resolver for ${VAR_NAME} syntax in MCP server configs.
+ *
+ * Always raises on unresolved placeholders — sending literal ${VAR} as an
+ * HTTP header value 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.
+ */
+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.
+ * Prevents secret over-sharing by restricting the 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;
+}

package/src/shared/plan-artifact.ts

@@ -0,0 +1,120 @@
+/**
+ * Plan-mode artifact publishing.
+ *
+ * When an execution runs in Plan mode (InteractionMode.PLAN), the agent's final
+ * message IS the plan. We publish that text as a first-class `plan.md`
+ * ExecutionArtifact so the UI can render a reviewable Plan card with
+ * copy/download, and a follow-up "Implement" execution can reference it
+ * deterministically.
+ *
+ * This is deliberately a single, harness-agnostic helper:
+ * - The native (deepagents) harness already auto-publishes files an agent
+ *   writes (InlinePublisher), but Plan mode is read-only, so there is no file to
+ *   publish — the plan lives only in the final message.
+ * - The Cursor harness has no artifact pipeline at all.
+ *
+ * Publishing the final message here, at finalization, gives both harnesses an
+ * identical, durable plan artifact derived from the single source of truth (the
+ * final AI message). It mirrors the InlinePublisher "publish a derived artifact"
+ * pattern: one immutable artifact, published once, never a parallel copy that
+ * can drift.
+ *
+ * The plan content is NOT duplicated as a separate stored blob beyond this
+ * artifact — the chat message remains the live/streamed view; the artifact is
+ * the durable/exportable view, detected by convention (a FILE artifact named
+ * `plan.md`).
+ */
+
+import { createHash } from "node:crypto";
+import { create } from "@bufbuild/protobuf";
+import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ExecutionArtifactSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/artifact_pb";
+import {
+  ExecutionArtifactKind,
+  MessageType,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { ArtifactStorage } from "./artifact-storage.js";
+import { utcTimestamp } from "./status.js";
+
+/** Canonical filename for a plan artifact. UI detection keys on this name. */
+export const PLAN_ARTIFACT_NAME = "plan.md";
+
+/**
+ * Sandbox path recorded on the artifact. Routes under `.stigmer/` (the
+ * session platform dir), so it never pollutes the user's workspace, and a
+ * follow-up execution can reference it via workspace file refs if desired.
+ */
+export const PLAN_ARTIFACT_SANDBOX_PATH = ".stigmer/plans/plan.md";
+
+/**
+ * Returns the text of the last AI message in a completed status, trimmed.
+ * Returns `undefined` when there is no AI message with content — the plan was
+ * empty and nothing should be published.
+ */
+export function extractFinalPlanText(status: AgentExecutionStatus): string | undefined {
+  for (let i = status.messages.length - 1; i >= 0; i--) {
+    const msg = status.messages[i];
+    if (msg.type === MessageType.MESSAGE_AI && msg.content.trim().length > 0) {
+      return msg.content;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Publishes `planText` as a `plan.md` ExecutionArtifact and registers it on
+ * `status.artifacts`. Idempotent: re-publishing replaces any existing `plan.md`
+ * rather than appending a duplicate, preserving a single source of truth.
+ *
+ * Fire-and-forget by contract: a plan that fails to upload must never fail the
+ * execution. Errors are logged and swallowed.
+ */
+export async function publishPlanArtifact(opts: {
+  readonly status: AgentExecutionStatus;
+  readonly executionId: string;
+  readonly planText: string;
+  readonly artifactStorage: ArtifactStorage;
+}): Promise<void> {
+  const { status, executionId, planText, artifactStorage } = opts;
+
+  if (planText.trim().length === 0) {
+    return;
+  }
+
+  try {
+    const content = Buffer.from(planText, "utf-8");
+    const contentHash = createHash("sha256").update(content).digest("hex");
+    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,
+      sandboxPath: PLAN_ARTIFACT_SANDBOX_PATH,
+      kind: ExecutionArtifactKind.FILE,
+      sizeBytes: BigInt(content.length),
+      storageKey,
+      downloadUrl,
+      createdAt: utcTimestamp(),
+      contentHash,
+    });
+
+    const existingIdx = status.artifacts.findIndex((a) => a.name === PLAN_ARTIFACT_NAME);
+    if (existingIdx >= 0) {
+      status.artifacts[existingIdx] = artifact;
+    } else {
+      status.artifacts.push(artifact);
+    }
+
+    console.log(
+      `[plan-artifact] execution=${executionId} — published ${PLAN_ARTIFACT_NAME} ` +
+      `(${content.length} bytes, hash=${contentHash.slice(0, 12)})`,
+    );
+  } catch (err) {
+    console.warn(
+      `[plan-artifact] execution=${executionId} — ` +
+      `failed to publish plan (non-fatal): ${err}`,
+    );
+  }
+}

package/src/shared/skill-relevance.ts

@@ -0,0 +1,222 @@
+/**
+ * Skill relevance scoring for smart context filtering.
+ *
+ * Uses a BM25-inspired algorithm to score each skill's relevance
+ * against the user message. When an agent has many skills configured,
+ * low-relevance skills are excluded from the system prompt to improve
+ * signal quality.
+ *
+ * The progressive disclosure model means only skill metadata
+ * (~50-70 tokens per skill) lives in the prompt, so filtering
+ * primarily reduces noise rather than saving tokens.
+ *
+ * BM25 (Best Matching 25) is a lightweight, well-understood ranking
+ * function from information retrieval. It uses term frequency saturation
+ * and document length normalisation — both important when matching a
+ * short user message (query) against short skill metadata (documents of
+ * 5-20 tokens each).
+ *
+ * No external dependencies required.
+ */
+
+/** Relevance filtering activates only when the agent has at least this many skills. */
+export const SKILL_COUNT_THRESHOLD = 8;
+
+/** Term-frequency saturation. Higher values weight repeated terms more. */
+const BM25_K1 = 1.5;
+
+/** Length normalisation. 0 = none, 1 = full relative to average doc length. */
+const BM25_B = 0.75;
+
+const STOP_WORDS: ReadonlySet<string> = new Set([
+  "a", "an", "the", "is", "are", "was", "were", "be", "been",
+  "being", "have", "has", "had", "do", "does", "did", "will",
+  "would", "could", "should", "may", "might", "shall", "can",
+  "to", "of", "in", "for", "on", "with", "at", "by", "from",
+  "as", "into", "through", "during", "before", "after", "above",
+  "below", "between", "and", "but", "or", "nor", "not", "so",
+  "yet", "both", "either", "neither", "each", "every", "all",
+  "any", "few", "more", "most", "some", "such", "no", "only",
+  "own", "same", "than", "too", "very", "just", "because",
+  "about", "up", "out", "if", "then", "that", "this", "these",
+  "those", "it", "its", "i", "me", "my", "we", "our", "you",
+  "your", "he", "she", "they", "them", "their", "what", "which",
+  "who", "whom", "how", "when", "where", "why",
+]);
+
+const TOKEN_PATTERN = /[a-z0-9]+/g;
+
+// ─── Tokenisation ────────────────────────────────────────────────────────
+
+/**
+ * Split text into lowercase tokens, dropping stop words and
+ * single-character fragments.
+ */
+export function tokenize(text: string): string[] {
+  const matches = text.toLowerCase().match(TOKEN_PATTERN);
+  if (!matches) return [];
+  return matches.filter(tok => !STOP_WORDS.has(tok) && tok.length > 1);
+}
+
+// ─── Data structures ─────────────────────────────────────────────────────
+
+export interface ScoredSkill {
+  readonly index: number;
+  readonly name: string;
+  readonly score: number;
+}
+
+export interface SkillFilterResult {
+  /** Indices of skills to include in the prompt (original order). */
+  readonly includedIndices: number[];
+  /** Indices of skills excluded from the prompt (original order). */
+  readonly excludedIndices: number[];
+  /** Names of excluded skills (sorted alphabetically). */
+  readonly excludedNames: string[];
+}
+
+// ─── BM25 scoring ────────────────────────────────────────────────────────
+
+/**
+ * Score each skill's relevance to the user message using BM25.
+ *
+ * Each skill's name and description are concatenated into a document
+ * and scored against the query terms extracted from the user message.
+ *
+ * Returns ScoredSkill list ordered by descending score (ties broken alphabetically).
+ */
+export function scoreSkills(
+  userMessage: string,
+  skillNames: readonly string[],
+  skillDescriptions: readonly string[],
+  options?: { k1?: number; b?: number },
+): ScoredSkill[] {
+  const k1 = options?.k1 ?? BM25_K1;
+  const b = options?.b ?? BM25_B;
+
+  const queryTerms = tokenize(userMessage);
+  const n = skillNames.length;
+
+  if (n === 0) return [];
+
+  if (queryTerms.length === 0) {
+    return skillNames.map((name, index) => ({ index, name, score: 0.0 }));
+  }
+
+  // Build per-skill term-frequency maps.
+  const docs: Map<string, number>[] = [];
+  const docLengths: number[] = [];
+
+  for (let i = 0; i < n; i++) {
+    const tokens = tokenize(`${skillNames[i]} ${skillDescriptions[i]}`);
+    const tf = new Map<string, number>();
+    for (const tok of tokens) {
+      tf.set(tok, (tf.get(tok) ?? 0) + 1);
+    }
+    docs.push(tf);
+    docLengths.push(tokens.length);
+  }
+
+  const avgdl = docLengths.reduce((sum, l) => sum + l, 0) / n;
+
+  // IDF per unique query term.
+  const uniqueQueryTerms = new Set(queryTerms);
+  const idf = new Map<string, number>();
+  for (const term of uniqueQueryTerms) {
+    let df = 0;
+    for (const doc of docs) {
+      if (doc.has(term)) df++;
+    }
+    idf.set(term, Math.max(0.0, Math.log((n - df + 0.5) / (df + 0.5) + 1.0)));
+  }
+
+  // Score each document.
+  const results: ScoredSkill[] = [];
+  for (let i = 0; i < n; i++) {
+    const docTf = docs[i];
+    const dl = docLengths[i];
+    let score = 0.0;
+    for (const term of queryTerms) {
+      const tfVal = docTf.get(term);
+      if (tfVal === undefined) continue;
+      const numerator = tfVal * (k1 + 1);
+      const denominator = tfVal + k1 * (1 - b + b * dl / avgdl);
+      score += (idf.get(term) ?? 0.0) * numerator / denominator;
+    }
+    results.push({ index: i, name: skillNames[i], score });
+  }
+
+  results.sort((a, b_) => {
+    if (b_.score !== a.score) return b_.score - a.score;
+    return a.name.localeCompare(b_.name);
+  });
+
+  return results;
+}
+
+// ─── Filtering ───────────────────────────────────────────────────────────
+
+/**
+ * Partition skills into included / excluded based on relevance.
+ *
+ * Below the threshold, every skill is included unconditionally.
+ * Above the threshold, skills whose BM25 score is zero (no query
+ * term overlap at all) are moved to the excluded set.
+ *
+ * A safety floor guarantees that at least half the skills are
+ * always included, regardless of scores.
+ */
+export function filterSkills(
+  userMessage: string,
+  skillNames: readonly string[],
+  skillDescriptions: readonly string[],
+  options?: { threshold?: number },
+): SkillFilterResult {
+  const threshold = options?.threshold ?? SKILL_COUNT_THRESHOLD;
+  const n = skillNames.length;
+  const allIndices = Array.from({ length: n }, (_, i) => i);
+
+  if (n < threshold) {
+    return {
+      includedIndices: allIndices,
+      excludedIndices: [],
+      excludedNames: [],
+    };
+  }
+
+  const scored = scoreSkills(userMessage, skillNames, skillDescriptions);
+
+  const included: number[] = [];
+  const excluded: number[] = [];
+  const excludedNames: string[] = [];
+
+  for (const s of scored) {
+    if (s.score > 0.0) {
+      included.push(s.index);
+    } else {
+      excluded.push(s.index);
+      excludedNames.push(s.name);
+    }
+  }
+
+  // Safety: always keep at least half the skills.
+  const minIncluded = Math.max(1, Math.floor(n / 2));
+  if (included.length < minIncluded) {
+    const deficit = minIncluded - included.length;
+    const reInclude = excluded.splice(0, deficit);
+    included.push(...reInclude);
+    for (const idx of reInclude) {
+      const nameIdx = excludedNames.indexOf(skillNames[idx]);
+      if (nameIdx !== -1) excludedNames.splice(nameIdx, 1);
+    }
+  }
+
+  included.sort((a, b) => a - b);
+  excluded.sort((a, b) => a - b);
+
+  return {
+    includedIndices: included,
+    excludedIndices: excluded,
+    excludedNames: excludedNames.sort(),
+  };
+}