@stigmer/runner 3.0.1

package/dist/shared/model-registry.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Model registry — provider lookup and economy-tier model derivation.
+ *
+ * Fetches the model registry from the Stigmer API (same endpoint as
+ * model-pricing-data.ts) and uses `costTier` + `harness` fields to
+ * dynamically resolve economy-tier models for extraction/summarization.
+ */
+/**
+ * Check whether a model identifier is known to the registry.
+ *
+ * Used to validate SubAgent model_override values. Returns false if the
+ * registry is empty (fetch failed) — callers should treat this as "unknown"
+ * and reject the override to avoid running on an unintended model.
+ */
+export declare function isModelRegistered(modelId: string): Promise<boolean>;
+/**
+ * Derive the recommended economy-tier model for summarization/classification
+ * tasks, given a primary model name.
+ *
+ * Resolution:
+ * 1. Look up the primary model's provider in the registry
+ * 2. Map provider → economy model (anthropic→claude-haiku-4.5, openai→gpt-4o-mini)
+ * 3. Fall back to the primary model itself if provider is unknown or unmapped
+ */
+export declare function getSummarizationModel(primaryModel: string): Promise<string>;
+/**
+ * Resolve the economy-tier model for a given primary model by querying
+ * the registry for costTier=economy + same provider + harness=native.
+ *
+ * Resolution order:
+ * 1. Find the primary model's provider in the registry
+ * 2. Find an economy-tier native model from that provider
+ * 3. Cross-provider fallback: any economy-tier native model
+ * 4. Last resort: return the primary model itself
+ */
+export declare function getEconomyModel(primaryModel: string): Promise<string>;
+export declare function getDefaultModel(): Promise<string>;
+/**
+ * Resolve a Stigmer registry model ID to the provider's API model identifier.
+ *
+ * The registry maintains two identifiers per model:
+ *   - `id`: Stigmer canonical ID (e.g., "claude-haiku-4.5")
+ *   - `apiModelId`: Provider API identifier (e.g., "claude-haiku-4-5-20251001")
+ *
+ * This function performs the translation that the proto documentation promises:
+ * "Model reference resolved via the Stigmer model registry."
+ *
+ * Graceful degradation:
+ *   - Registry unavailable → returns the original string unchanged
+ *   - Model not found in registry → returns the original string unchanged
+ *   - Model found but has no apiModelId → returns the registry `id` unchanged
+ */
+export declare function resolveToApiModelId(registryId: string): Promise<string>;
+/** Exposed for testing — resets the in-memory cache. */
+export declare function _resetRegistryCache(): void;

package/dist/shared/model-registry.js

@@ -0,0 +1,178 @@
+/**
+ * Model registry — provider lookup and economy-tier model derivation.
+ *
+ * Fetches the model registry from the Stigmer API (same endpoint as
+ * model-pricing-data.ts) and uses `costTier` + `harness` fields to
+ * dynamically resolve economy-tier models for extraction/summarization.
+ */
+const DEFAULT_API_URL = "https://api.stigmer.ai";
+const CACHE_TTL_MS = 3_600_000;
+let cache = null;
+let inflightFetch = null;
+function parseRegistry(json) {
+    if (!json || typeof json !== "object")
+        return [];
+    const models = json.models;
+    if (!Array.isArray(models))
+        return [];
+    return models
+        .filter((m) => typeof m.id === "string" && typeof m.provider === "string")
+        .map((m) => ({
+        id: m.id,
+        apiModelId: typeof m.apiModelId === "string" ? m.apiModelId : undefined,
+        provider: m.provider,
+        costTier: m.costTier ?? "standard",
+        harness: m.harness ?? "native",
+        featured: !!m.featured,
+    }));
+}
+async function fetchRegistry() {
+    const url = `${process.env.STIGMER_CLOUD_API_URL ?? DEFAULT_API_URL}/v1/proxy/model-registry`;
+    const headers = {};
+    const token = process.env.STIGMER_TOKEN ?? process.env.STIGMER_AUTH_TOKEN;
+    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 = await res.json();
+    return parseRegistry(data);
+}
+async function getRegistry() {
+    if (cache && Date.now() < cache.expiresAt) {
+        return cache.models;
+    }
+    if (inflightFetch)
+        return inflightFetch;
+    inflightFetch = fetchRegistry()
+        .then((models) => {
+        cache = { models, expiresAt: Date.now() + CACHE_TTL_MS };
+        return models;
+    })
+        .catch((err) => {
+        console.warn(`Failed to fetch model registry for provider lookup: ${err}`);
+        cache = { models: [], expiresAt: Date.now() + CACHE_TTL_MS };
+        return [];
+    })
+        .finally(() => {
+        inflightFetch = null;
+    });
+    return inflightFetch;
+}
+/**
+ * Check whether a model identifier is known to the registry.
+ *
+ * Used to validate SubAgent model_override values. Returns false if the
+ * registry is empty (fetch failed) — callers should treat this as "unknown"
+ * and reject the override to avoid running on an unintended model.
+ */
+export async function isModelRegistered(modelId) {
+    const registry = await getRegistry();
+    if (registry.length === 0)
+        return false;
+    return registry.some((m) => m.id === modelId);
+}
+/**
+ * Derive the recommended economy-tier model for summarization/classification
+ * tasks, given a primary model name.
+ *
+ * Resolution:
+ * 1. Look up the primary model's provider in the registry
+ * 2. Map provider → economy model (anthropic→claude-haiku-4.5, openai→gpt-4o-mini)
+ * 3. Fall back to the primary model itself if provider is unknown or unmapped
+ */
+export async function getSummarizationModel(primaryModel) {
+    return getEconomyModel(primaryModel);
+}
+/**
+ * Resolve the economy-tier model for a given primary model by querying
+ * the registry for costTier=economy + same provider + harness=native.
+ *
+ * Resolution order:
+ * 1. Find the primary model's provider in the registry
+ * 2. Find an economy-tier native model from that provider
+ * 3. Cross-provider fallback: any economy-tier native model
+ * 4. Last resort: return the primary model itself
+ */
+export async function getEconomyModel(primaryModel) {
+    const registry = await getRegistry();
+    if (registry.length === 0) {
+        // Registry unavailable: keep the caller's chosen model rather than
+        // switching to a hardcoded economy model on a possibly-unconfigured
+        // provider. Summarization degrades gracefully to the primary model.
+        console.warn(`Model registry empty — falling back to primary model "${primaryModel}" for economy tier`);
+        return primaryModel;
+    }
+    const primary = registry.find((m) => m.id === primaryModel);
+    const targetProvider = primary?.provider ?? "anthropic";
+    const sameProviderEconomy = registry.find((m) => m.provider === targetProvider && m.costTier === "economy" && m.harness === "native");
+    if (sameProviderEconomy)
+        return sameProviderEconomy.id;
+    const anyEconomy = registry.find((m) => m.costTier === "economy" && m.harness === "native");
+    if (anyEconomy)
+        return anyEconomy.id;
+    if (!primary) {
+        console.warn(`Model "${primaryModel}" not found in registry and no economy fallback available`);
+    }
+    return primaryModel;
+}
+/**
+ * Resolve the default agent execution model from the registry.
+ *
+ * Used when the user hasn't selected a model (no executionConfig.modelName).
+ * Returns the provider's API model identifier (e.g., "claude-sonnet-4-6"),
+ * not the Stigmer registry ID (e.g., "claude-sonnet-4.6").
+ *
+ * Resolution order:
+ * 1. Featured + standard + native (platform's curated default)
+ * 2. Any standard + native model
+ * 3. Hardcoded fallback (registry unavailable)
+ */
+const FALLBACK_DEFAULT_MODEL = "claude-sonnet-4-6";
+export async function getDefaultModel() {
+    const registry = await getRegistry();
+    if (registry.length === 0) {
+        console.warn(`Model registry empty — using fallback default model "${FALLBACK_DEFAULT_MODEL}"`);
+        return FALLBACK_DEFAULT_MODEL;
+    }
+    const featuredStandard = registry.find((m) => m.featured && m.costTier === "standard" && m.harness === "native");
+    if (featuredStandard)
+        return featuredStandard.apiModelId ?? featuredStandard.id;
+    const anyStandard = registry.find((m) => m.costTier === "standard" && m.harness === "native");
+    if (anyStandard)
+        return anyStandard.apiModelId ?? anyStandard.id;
+    return FALLBACK_DEFAULT_MODEL;
+}
+/**
+ * Resolve a Stigmer registry model ID to the provider's API model identifier.
+ *
+ * The registry maintains two identifiers per model:
+ *   - `id`: Stigmer canonical ID (e.g., "claude-haiku-4.5")
+ *   - `apiModelId`: Provider API identifier (e.g., "claude-haiku-4-5-20251001")
+ *
+ * This function performs the translation that the proto documentation promises:
+ * "Model reference resolved via the Stigmer model registry."
+ *
+ * Graceful degradation:
+ *   - Registry unavailable → returns the original string unchanged
+ *   - Model not found in registry → returns the original string unchanged
+ *   - Model found but has no apiModelId → returns the registry `id` unchanged
+ */
+export async function resolveToApiModelId(registryId) {
+    if (!registryId)
+        return registryId;
+    const registry = await getRegistry();
+    if (registry.length === 0)
+        return registryId;
+    const entry = registry.find((m) => m.id === registryId);
+    if (!entry)
+        return registryId;
+    return entry.apiModelId ?? registryId;
+}
+/** Exposed for testing — resets the in-memory cache. */
+export function _resetRegistryCache() {
+    cache = null;
+    inflightFetch = null;
+}
+//# sourceMappingURL=model-registry.js.map

package/dist/shared/model-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-registry.js","sourceRoot":"","sources":["../../src/shared/model-registry.ts"],"names":[],"mappings":"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"}

package/dist/shared/placeholder-resolver.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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.
+ */
+export declare class PlaceholderResolutionError extends Error {
+    readonly variableName: string;
+    readonly context?: string | undefined;
+    constructor(variableName: string, context?: string | undefined);
+}
+/**
+ * Resolve all ${VAR_NAME} placeholders in a template string.
+ *
+ * @throws PlaceholderResolutionError if any placeholder cannot be resolved.
+ */
+export declare function resolvePlaceholders(template: string, envVars: Record<string, string>, context?: string): string;
+/**
+ * Resolve placeholders in all values of a headers map.
+ */
+export declare function resolveHeaders(headers: Record<string, string>, envVars: Record<string, string>): Record<string, string>;
+/**
+ * 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 declare function filterEnvToDeclaredKeys(declaredEnv: Record<string, unknown> | undefined, envVars: Record<string, string>, serverSlug: string): Record<string, string>;

package/dist/shared/placeholder-resolver.js

@@ -0,0 +1,75 @@
+/**
+ * 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 {
+    variableName;
+    context;
+    constructor(variableName, context) {
+        const where = context ? ` in ${context}` : "";
+        super(`Unresolved placeholder \${${variableName}}${where}: ` +
+            `variable is not present in the execution environment`);
+        this.variableName = variableName;
+        this.context = context;
+        this.name = "PlaceholderResolutionError";
+    }
+}
+/**
+ * Resolve all ${VAR_NAME} placeholders in a template string.
+ *
+ * @throws PlaceholderResolutionError if any placeholder cannot be resolved.
+ */
+export function resolvePlaceholders(template, envVars, context) {
+    return template.replace(PLACEHOLDER_RE, (match, varName) => {
+        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, envVars) {
+    const resolved = {};
+    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, envVars, serverSlug) {
+    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 = {};
+    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;
+}
+//# sourceMappingURL=placeholder-resolver.js.map

package/dist/shared/placeholder-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"placeholder-resolver.js","sourceRoot":"","sources":["../../src/shared/placeholder-resolver.ts"],"names":[],"mappings":"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"}

package/dist/shared/plan-artifact.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 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 type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { ArtifactStorage } from "./artifact-storage.js";
+/** Canonical filename for a plan artifact. UI detection keys on this name. */
+export declare 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 declare 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 declare function extractFinalPlanText(status: AgentExecutionStatus): string | 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 declare function publishPlanArtifact(opts: {
+    readonly status: AgentExecutionStatus;
+    readonly executionId: string;
+    readonly planText: string;
+    readonly artifactStorage: ArtifactStorage;
+}): Promise<void>;

package/dist/shared/plan-artifact.js

@@ -0,0 +1,98 @@
+/**
+ * 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 { 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 { 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) {
+    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) {
+    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}`);
+    }
+}
+//# sourceMappingURL=plan-artifact.js.map

package/dist/shared/plan-artifact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-artifact.js","sourceRoot":"","sources":["../../src/shared/plan-artifact.ts"],"names":[],"mappings":"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"}

package/dist/shared/skill-relevance.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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 declare const SKILL_COUNT_THRESHOLD = 8;
+/**
+ * Split text into lowercase tokens, dropping stop words and
+ * single-character fragments.
+ */
+export declare function tokenize(text: string): string[];
+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[];
+}
+/**
+ * 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 declare function scoreSkills(userMessage: string, skillNames: readonly string[], skillDescriptions: readonly string[], options?: {
+    k1?: number;
+    b?: number;
+}): ScoredSkill[];
+/**
+ * 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 declare function filterSkills(userMessage: string, skillNames: readonly string[], skillDescriptions: readonly string[], options?: {
+    threshold?: number;
+}): SkillFilterResult;