@stigmer/runner 3.9.0 → 3.11.0

package/dist/shared/llm-backend.js

@@ -0,0 +1,425 @@
+/**
+ * LLM provider-backend utilities — pure routing helpers for serving a
+ * provider's models through an alternative cloud backend (GCP Vertex AI,
+ * AWS Bedrock, Microsoft Foundry) instead of the provider's public API.
+ *
+ * Layering mirrors `llm-proxy.ts`: this module is pure string/config
+ * utilities with no LangChain or SDK dependency. Consumers: the runner
+ * factories run `preflightLlmBackends` at startup, and `model-client.ts`
+ * resolves the backend and translates model ids at construction time; see
+ * `__tests__/vertex-seam.test.ts` for the pinned seam behavior.
+ *
+ * Design decision record: stigmer-cloud
+ * `_projects/2026-08/20260809.01.multi-cloud-llm-provider-endpoints/`
+ * `design-decisions/001-provider-backends.md`.
+ */
+// ─── Backend selection ───────────────────────────────────────────────────────
+/** Env var selecting where Anthropic models are served. */
+export const ANTHROPIC_BACKEND_ENV = "STIGMER_ANTHROPIC_BACKEND";
+/** Env var selecting where OpenAI models are served. */
+export const OPENAI_BACKEND_ENV = "STIGMER_OPENAI_BACKEND";
+/** Operator guide for backend configuration; the single copy of this URL. */
+export const BACKEND_DOC_URL = "https://docs.stigmer.ai/guides/runners/model-backends";
+/** Planned-but-unshipped values get a "not in this build" message. */
+const PLANNED_ANTHROPIC = [];
+const PLANNED_OPENAI = ["azure"];
+function parseBackend(envVar, raw, supported, planned) {
+    const value = raw?.trim().toLowerCase() ?? "";
+    if (value === "") {
+        // Unset means the provider's public API — the zero-config default.
+        return { ok: true, backend: "public" };
+    }
+    if (supported.includes(value)) {
+        return { ok: true, backend: value };
+    }
+    if (planned.includes(value)) {
+        return {
+            ok: false,
+            message: `${envVar}="${value}" is not implemented in this build yet. ` +
+                `Supported today: ${supported.join(", ")}. See ${BACKEND_DOC_URL}.`,
+        };
+    }
+    return {
+        ok: false,
+        message: `${envVar}="${raw?.trim()}" is not a supported backend. ` +
+            `Supported: ${supported.join(", ")}. See ${BACKEND_DOC_URL}.`,
+    };
+}
+/** Parse `STIGMER_ANTHROPIC_BACKEND` (unset → `public`). */
+export function parseAnthropicBackend(env = process.env) {
+    return parseBackend(ANTHROPIC_BACKEND_ENV, env[ANTHROPIC_BACKEND_ENV], ["public", "vertex", "bedrock", "foundry"], PLANNED_ANTHROPIC);
+}
+/** Parse `STIGMER_OPENAI_BACKEND` (unset → `public`). */
+export function parseOpenAiBackend(env = process.env) {
+    return parseBackend(OPENAI_BACKEND_ENV, env[OPENAI_BACKEND_ENV], ["public"], 
+    // `vertex`/`bedrock` under the OpenAI var are wrong-provider values, not
+    // planned ones — they fall through to the unsupported-value message.
+    PLANNED_OPENAI);
+}
+/**
+ * Resolve the Anthropic backend for model construction, throwing the
+ * parser's message on an invalid value.
+ *
+ * The runner factories run {@link preflightLlmBackends} at startup, so in a
+ * normally-booted process this never throws — the throw is defense in depth
+ * for paths that construct models without the factories (tests, direct
+ * library use), keeping "invalid value" impossible to ride past silently.
+ */
+export function resolveAnthropicBackend(env = process.env) {
+    const parsed = parseAnthropicBackend(env);
+    if (!parsed.ok)
+        throw new Error(parsed.message);
+    return parsed.backend;
+}
+/**
+ * Static prerequisite check for the vertex backend, or null when satisfied.
+ *
+ * Region is the ONE hard requirement checkable without I/O: the Vertex SDK
+ * throws without it. Project id and credentials are deliberately NOT
+ * checked here — both are legitimately resolvable at request time from
+ * Application Default Credentials (workload identity, metadata server,
+ * gcloud login), so requiring env vars for them would reject perfectly
+ * valid GCP deployments. Runtime credential failures get actionable
+ * classification in `model-error.ts` instead.
+ */
+export function checkVertexPrerequisites(env = process.env) {
+    if (env.CLOUD_ML_REGION?.trim())
+        return null;
+    return (`The vertex backend requires CLOUD_ML_REGION (e.g. "asia-south1", or ` +
+        `"global" for the global endpoint). See ${BACKEND_DOC_URL}.`);
+}
+/** Operator override map: canonical id -> exact Bedrock id, consulted first. */
+export const BEDROCK_MODEL_MAP_ENV = "STIGMER_BEDROCK_MODEL_MAP";
+/** Inference-profile geography prefix (`us`, `eu`, `global`, …), no default. */
+export const BEDROCK_INFERENCE_PREFIX_ENV = "STIGMER_BEDROCK_INFERENCE_PREFIX";
+/**
+ * Static prerequisite check for the bedrock backend, or null when satisfied.
+ *
+ * AWS_REGION is REQUIRED even though the Bedrock SDK would default it to
+ * us-east-1 (pinned by bedrock-seam.test.ts): for a deployment-controlled
+ * data-residency feature, silently routing model traffic to a US region on
+ * a missing var is exactly the failure backends exist to prevent. Same
+ * shape as vertex's CLOUD_ML_REGION requirement. Credentials are
+ * deliberately NOT checked — the AWS chain (env keys, IRSA / instance
+ * metadata, config files, AWS_BEARER_TOKEN_BEDROCK) legitimately resolves
+ * at request time; requiring env keys would reject valid deployments.
+ * Runtime credential failures get actionable classification in
+ * `model-error.ts` instead.
+ *
+ * A malformed STIGMER_BEDROCK_MODEL_MAP is also fatal here: it is
+ * deployment-static, and finding out at the first model call would fail
+ * executions a boot check could have refused.
+ */
+export function checkBedrockPrerequisites(env = process.env) {
+    if (!env.AWS_REGION?.trim()) {
+        return (`The bedrock backend requires AWS_REGION (e.g. "ap-south-1"). It is ` +
+            `required even though the AWS SDK would default to us-east-1 — a ` +
+            `deployment that chose Bedrock for data residency must never fall ` +
+            `back to another region silently. See ${BACKEND_DOC_URL}.`);
+    }
+    const map = parseBedrockModelMap(env);
+    if (!map.ok)
+        return map.message;
+    return null;
+}
+/**
+ * Shared parser for the per-backend override maps: comma-separated
+ * `canonical=target` pairs. Unset or blank parses to an empty map (the
+ * backend's deterministic rule serves every model). Each env var keeps its
+ * own single copy of the malformed-entry text through `form`/`example` —
+ * preflight and translation surface the same string.
+ */
+function parseModelMap(envVar, raw, form, example) {
+    const trimmed = raw?.trim();
+    const map = new Map();
+    if (!trimmed)
+        return { ok: true, map };
+    for (const entry of trimmed.split(",")) {
+        const pair = entry.trim();
+        if (pair === "")
+            continue;
+        const eq = pair.indexOf("=");
+        const canonical = eq === -1 ? "" : pair.slice(0, eq).trim();
+        const target = eq === -1 ? "" : pair.slice(eq + 1).trim();
+        if (!canonical || !target) {
+            return {
+                ok: false,
+                message: `${envVar} entry "${pair}" is not of the form ${form} ` +
+                    `(e.g. "${example}"). Entries are comma-separated. ` +
+                    `See ${BACKEND_DOC_URL}.`,
+            };
+        }
+        map.set(canonical, target);
+    }
+    return { ok: true, map };
+}
+/**
+ * Parse `STIGMER_BEDROCK_MODEL_MAP`: comma-separated `canonical=bedrockId`
+ * pairs, e.g. "claude-sonnet-4-6=us.anthropic.claude-sonnet-4-6-v1:0".
+ */
+export function parseBedrockModelMap(env = process.env) {
+    return parseModelMap(BEDROCK_MODEL_MAP_ENV, env[BEDROCK_MODEL_MAP_ENV], "canonical=bedrockId", "claude-sonnet-4-6=us.anthropic.claude-sonnet-4-6-v1:0");
+}
+// ─── Microsoft Foundry (Azure) ───────────────────────────────────────────────
+/**
+ * Operator override map: canonical id -> Foundry deployment name, consulted
+ * first. Named DEPLOYMENT_MAP, not MODEL_MAP, because the target is Azure's
+ * term of art — the operator-chosen deployment name, not another model id.
+ */
+export const FOUNDRY_DEPLOYMENT_MAP_ENV = "STIGMER_FOUNDRY_DEPLOYMENT_MAP";
+/** The Foundry resource name (SDK-native; builds the endpoint host). */
+export const FOUNDRY_RESOURCE_ENV = "ANTHROPIC_FOUNDRY_RESOURCE";
+/** Full endpoint override (SDK-native; mutually exclusive with resource). */
+export const FOUNDRY_BASE_URL_ENV = "ANTHROPIC_FOUNDRY_BASE_URL";
+/**
+ * Parse `STIGMER_FOUNDRY_DEPLOYMENT_MAP`: comma-separated
+ * `canonical=deploymentName` pairs, e.g.
+ * "claude-sonnet-4-6=my-sonnet-deployment".
+ */
+export function parseFoundryDeploymentMap(env = process.env) {
+    return parseModelMap(FOUNDRY_DEPLOYMENT_MAP_ENV, env[FOUNDRY_DEPLOYMENT_MAP_ENV], "canonical=deploymentName", "claude-sonnet-4-6=my-sonnet-deployment");
+}
+/**
+ * Static prerequisite check for the foundry backend, or null when satisfied.
+ *
+ * The endpoint is the ONE hard requirement checkable without I/O: the
+ * Foundry SDK's constructor throws without exactly one of the resource
+ * name or a full base URL, so both halves of its contract (missing AND
+ * both-set) are refused here at boot with catalog messages instead of at
+ * the first model call. Credentials are deliberately NOT checked —
+ * ANTHROPIC_FOUNDRY_API_KEY is optional by design (without it the adapter
+ * authenticates through Microsoft Entra ID via the Azure credential chain,
+ * which resolves at request time exactly like Vertex ADC and the AWS
+ * chain), so requiring it would reject correctly-configured keyless
+ * deployments. Runtime credential failures get actionable classification
+ * in `model-error.ts` instead.
+ *
+ * A malformed STIGMER_FOUNDRY_DEPLOYMENT_MAP is also fatal here: it is
+ * deployment-static, and finding out at the first model call would fail
+ * executions a boot check could have refused.
+ */
+export function checkFoundryPrerequisites(env = process.env) {
+    const resource = env[FOUNDRY_RESOURCE_ENV]?.trim();
+    const baseUrl = env[FOUNDRY_BASE_URL_ENV]?.trim();
+    if (!resource && !baseUrl) {
+        return (`The foundry backend requires ${FOUNDRY_RESOURCE_ENV} (your Microsoft ` +
+            `Foundry resource name, e.g. "my-foundry-resource") or ` +
+            `${FOUNDRY_BASE_URL_ENV} (the full endpoint, e.g. ` +
+            `"https://my-foundry-resource.services.ai.azure.com/anthropic/"). ` +
+            `See ${BACKEND_DOC_URL}.`);
+    }
+    if (resource && baseUrl) {
+        return (`${FOUNDRY_RESOURCE_ENV} and ${FOUNDRY_BASE_URL_ENV} are mutually ` +
+            `exclusive — the base URL is derived from the resource name. Set ` +
+            `exactly one. See ${BACKEND_DOC_URL}.`);
+    }
+    const map = parseFoundryDeploymentMap(env);
+    if (!map.ok)
+        return map.message;
+    return null;
+}
+/**
+ * Check that direct-mode (unproxied) calls to `provider` have a usable
+ * credential path, or return the operator message describing what is
+ * missing. Null means "a request can authenticate":
+ *
+ * - `anthropic`: a non-blank `ANTHROPIC_API_KEY`, or any non-public backend
+ *   (vertex authenticates through Application Default Credentials, and
+ *   `ChatAnthropic` waives its API-key requirement when `createClient` is
+ *   supplied — pinned by vertex-seam.test.ts).
+ * - `openai`: a non-blank `OPENAI_API_KEY`. The message deliberately offers
+ *   no backend remedy until the azure adapter ships — advertising
+ *   STIGMER_OPENAI_BACKEND today would point the operator at a value that
+ *   fails with "not implemented in this build".
+ *
+ * An invalid backend value also returns null: `resolveAnthropicBackend` at
+ * model construction owns that condition's precise catalog message, and
+ * reporting it here too would create a second copy that can drift.
+ *
+ * This is the single copy of the "do we have a credential?" question. The
+ * reaction stays with each caller, because the right one differs per site:
+ * `call-llm.ts` raises a non-retryable LLM_MISSING_API_KEY, tool
+ * classification fails closed (every tool gated), and Cursor tier-2
+ * extraction skips to "no structured output". Callers consult it only when
+ * no proxy is configured — a proxied deployment authenticates with
+ * STIGMER_TOKEN and holds no provider credentials at all.
+ */
+export function checkDirectCredentials(provider, env = process.env) {
+    if (provider === "openai") {
+        if (env.OPENAI_API_KEY?.trim())
+            return null;
+        return (`OPENAI_API_KEY is not set and no proxy is configured. Set the API ` +
+            `key in your environment or connect to a Stigmer Cloud deployment. ` +
+            `See ${BACKEND_DOC_URL}.`);
+    }
+    if (env.ANTHROPIC_API_KEY?.trim())
+        return null;
+    const parsed = parseAnthropicBackend(env);
+    if (!parsed.ok || parsed.backend !== "public")
+        return null;
+    return (`ANTHROPIC_API_KEY is not set, no model backend is configured, and no ` +
+        `proxy is configured. Set the API key, configure a backend (e.g. ` +
+        `${ANTHROPIC_BACKEND_ENV}=vertex, bedrock, or foundry), or connect to ` +
+        `a Stigmer Cloud deployment. See ${BACKEND_DOC_URL}.`);
+}
+/**
+ * Validate the deployment's backend configuration once, at startup.
+ *
+ * Called by the runner factories (`createStigmerRunner` /
+ * `createStigmerRunnerManager`) — the construction boundary every entry
+ * path shares (static, pool, and manager modes in main.ts, plus in-process
+ * embedders of `@stigmer/runner`) — so a misconfigured deployment refuses
+ * to accept work instead of failing every execution mid-flight. Mirrors the
+ * `preflightNodeRuntime` pattern: pure check in, operator message out.
+ *
+ * Precedence rule: when `STIGMER_PROXY_ENDPOINT` is set the proxy owns
+ * provider routing and backend vars are inert, so they downgrade to
+ * warnings (never silence, but never fail a proxied fleet over an ignored
+ * var either). Without a proxy, invalid values and missing prerequisites
+ * are fatal.
+ */
+export function preflightLlmBackends(env = process.env) {
+    const proxySet = !!env.STIGMER_PROXY_ENDPOINT?.trim();
+    if (proxySet) {
+        const warnings = [];
+        for (const envVar of [ANTHROPIC_BACKEND_ENV, OPENAI_BACKEND_ENV]) {
+            const raw = env[envVar]?.trim();
+            if (raw && raw.toLowerCase() !== "public") {
+                warnings.push(`STIGMER_PROXY_ENDPOINT is set; ${envVar}=${raw} is ignored — ` +
+                    `the proxy owns provider routing.`);
+            }
+        }
+        return { error: null, warnings };
+    }
+    const errors = [];
+    const anthropic = parseAnthropicBackend(env);
+    if (!anthropic.ok) {
+        errors.push(anthropic.message);
+    }
+    else if (anthropic.backend === "vertex") {
+        const prereq = checkVertexPrerequisites(env);
+        if (prereq !== null)
+            errors.push(prereq);
+    }
+    else if (anthropic.backend === "bedrock") {
+        const prereq = checkBedrockPrerequisites(env);
+        if (prereq !== null)
+            errors.push(prereq);
+    }
+    else if (anthropic.backend === "foundry") {
+        const prereq = checkFoundryPrerequisites(env);
+        if (prereq !== null)
+            errors.push(prereq);
+    }
+    const openai = parseOpenAiBackend(env);
+    if (!openai.ok)
+        errors.push(openai.message);
+    return { error: errors.length > 0 ? errors.join("\n") : null, warnings: [] };
+}
+// ─── Model-id translation ────────────────────────────────────────────────────
+/**
+ * Matches a registry `apiModelId` that ends in a pre-4.6 snapshot date
+ * (`-YYYYMMDD`), e.g. "claude-sonnet-4-5-20250929".
+ */
+const TRAILING_SNAPSHOT_DATE = /-(\d{8})$/;
+/**
+ * Translate a canonical Anthropic API model id into Vertex AI's form.
+ *
+ * The model registry serves two id shapes, and Vertex treats them
+ * differently (platform.claude.com "Model IDs and versions"):
+ *
+ * - Pre-4.6 models carry a snapshot date, and Vertex separates it with `@`
+ *   instead of `-`: "claude-sonnet-4-5-20250929" -> "claude-sonnet-4-5@20250929".
+ * - 4.6-generation and later ids are dateless AND canonical on every
+ *   platform: "claude-sonnet-4-6" is used verbatim on Vertex. Appending a
+ *   date to them 404s — a real bug shipped by other integrations (Dify
+ *   langgenius/dify-official-plugins#2905, Roo-Code #11625) — so dateless
+ *   ids MUST pass through untouched.
+ *
+ * The translated id is Vertex wire detail only: it goes into the request
+ * URL path and must never escape the adapter into usage metrics or pricing,
+ * which key on the canonical id (the canonical-id invariant in the design
+ * decision record).
+ *
+ * Already-translated ids (`name@date`) and Bedrock-shaped ids
+ * (`anthropic.…-v1:0`) don't match the trailing-date pattern, so a second
+ * pass is a no-op by construction.
+ */
+export function toVertexModelId(apiModelId) {
+    return apiModelId.replace(TRAILING_SNAPSHOT_DATE, "@$1");
+}
+/**
+ * Translate a canonical Anthropic API model id into Bedrock's form, in
+ * three layers (approved design, T04) — each a deployment-level knob:
+ *
+ * 1. `STIGMER_BEDROCK_MODEL_MAP` override, consulted first: the escape
+ *    hatch for ids the deterministic rule cannot derive (Bedrock ids for
+ *    dateless canonicals may carry AWS-side snapshot dates we cannot know).
+ * 2. `STIGMER_BEDROCK_INFERENCE_PREFIX` (e.g. "us", "eu", "global"),
+ *    applied to the derived id. Newer Claude models on Bedrock are invoked
+ *    through geography-prefixed inference profiles (AWS lists the base id's
+ *    in-region endpoint as N/A) — but WHICH geography is a deployment
+ *    decision (data residency), underivable from the model id, and never
+ *    defaulted: a missing prefix yields the bare id, and if AWS rejects it
+ *    with its "use an inference profile" error, model-error.ts translates
+ *    that into "set ${BEDROCK_INFERENCE_PREFIX_ENV}".
+ * 3. Deterministic rule: `anthropic.{canonical}-v1:0` — verified against
+ *    AWS's model catalog for the registry's dated ids (e.g.
+ *    claude-sonnet-4-5-20250929 -> anthropic.claude-sonnet-4-5-20250929-v1:0).
+ *
+ * Like the Vertex translation, the result is wire detail only: it rides in
+ * the request URL and must never escape the adapter into usage metrics or
+ * pricing, which key on the canonical id (the canonical-id invariant).
+ *
+ * Throws the catalog message on a malformed map — defense in depth for
+ * paths that construct models without the factories; a normally-booted
+ * runner already refused to start in `checkBedrockPrerequisites`.
+ */
+export function toBedrockModelId(apiModelId, env = process.env) {
+    const parsed = parseBedrockModelMap(env);
+    if (!parsed.ok)
+        throw new Error(parsed.message);
+    const mapped = parsed.map.get(apiModelId);
+    if (mapped !== undefined)
+        return mapped;
+    // Lenient on a trailing dot ("us." and "us" both read as intent).
+    const prefix = env[BEDROCK_INFERENCE_PREFIX_ENV]?.trim().replace(/\.$/, "");
+    const derived = `anthropic.${apiModelId}-v1:0`;
+    return prefix ? `${prefix}.${derived}` : derived;
+}
+/**
+ * Translate a canonical Anthropic API model id into a Microsoft Foundry
+ * deployment name, in two layers (approved design, T05):
+ *
+ * 1. `STIGMER_FOUNDRY_DEPLOYMENT_MAP` override, consulted first: Foundry
+ *    routes by DEPLOYMENT NAME, and the portal lets operators name
+ *    deployments anything ("my-sonnet-deployment"). This is the escape
+ *    hatch for those custom names.
+ * 2. Deterministic rule: strip a trailing `-YYYYMMDD` snapshot date —
+ *    Foundry's DEFAULT deployment names are the dateless Claude ids
+ *    (claude-sonnet-4-5-20250929 -> claude-sonnet-4-5; dateless ids pass
+ *    through unchanged). Verified against Anthropic's published Foundry
+ *    model table: every native-catalog id maps onto a real default
+ *    deployment name. Note this is the INVERSE of toVertexModelId, which
+ *    keeps the date and reseparates it with `@`.
+ *
+ * Like the other translations, the result is wire detail only: it rides in
+ * the request body's `model` field (Foundry keeps it in the body — see
+ * foundry-seam.test.ts — unlike Vertex/Bedrock, which move it into the URL
+ * path) and must never escape the adapter into usage metrics or pricing,
+ * which key on the canonical id (the canonical-id invariant).
+ *
+ * Throws the catalog message on a malformed map — defense in depth for
+ * paths that construct models without the factories; a normally-booted
+ * runner already refused to start in `checkFoundryPrerequisites`.
+ */
+export function toFoundryDeploymentName(apiModelId, env = process.env) {
+    const parsed = parseFoundryDeploymentMap(env);
+    if (!parsed.ok)
+        throw new Error(parsed.message);
+    const mapped = parsed.map.get(apiModelId);
+    if (mapped !== undefined)
+        return mapped;
+    return apiModelId.replace(TRAILING_SNAPSHOT_DATE, "");
+}
+//# sourceMappingURL=llm-backend.js.map

package/dist/shared/llm-backend.js.map

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

package/dist/shared/llm-proxy.d.ts

@@ -25,6 +25,14 @@ export type LlmProvider = "anthropic" | "openai";
  * fall back to a default provider when an unknown model is requested.
  */
 export declare function inferProvider(modelName: string): LlmProvider;
+/**
+ * {@link inferProvider}, returning null instead of throwing on an unknown
+ * prefix. For credential pre-checks that must not preempt the construction
+ * path: when the provider cannot be determined here, the caller proceeds and
+ * lets `buildChatModel` raise inferProvider's precise message inside its own
+ * error handling, instead of a guess being made up front.
+ */
+export declare function tryInferProvider(modelName: string): LlmProvider | null;
 /**
  * Strip an explicit "provider:" prefix from the model name, returning
  * just the model ID portion. If no explicit prefix is present, returns

package/dist/shared/llm-proxy.js

@@ -61,6 +61,21 @@ export function inferProvider(modelName) {
         `Known prefixes: claude* (anthropic), gpt*/o1*/o3*/o4*/chatgpt* (openai). ` +
         `Use explicit prefix syntax "provider:model-name" for non-standard model names.`);
 }
+/**
+ * {@link inferProvider}, returning null instead of throwing on an unknown
+ * prefix. For credential pre-checks that must not preempt the construction
+ * path: when the provider cannot be determined here, the caller proceeds and
+ * lets `buildChatModel` raise inferProvider's precise message inside its own
+ * error handling, instead of a guess being made up front.
+ */
+export function tryInferProvider(modelName) {
+    try {
+        return inferProvider(modelName);
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Strip an explicit "provider:" prefix from the model name, returning
  * just the model ID portion. If no explicit prefix is present, returns

package/dist/shared/llm-proxy.js.map

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

package/dist/shared/mcp-enabled-tools.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Enforcement semantics for McpServerUsage.enabled_tools (issue #350).
+ *
+ * The proto contract (agent/v1/spec.proto McpServerUsage.enabled_tools,
+ * mcpserver/v1/spec.proto McpServerSpec.default_enabled_tools):
+ * - A non-empty enabled_tools on the usage is the allow-list for that server.
+ * - An empty usage list falls back to the server's default_enabled_tools.
+ * - Both empty means NO restriction — every discovered tool is available.
+ *
+ * Both harnesses import THIS module so they can never drift on these
+ * semantics (the mcp-transport-guard precedent for logic shared across the
+ * duplicated resolvers — see the header of shared/mcp-resolver.ts):
+ * - The deep-agent harness filters the discovered toolset before it reaches
+ *   the model (shared/mcp-manager.ts connectMcpServers).
+ * - The Cursor harness cannot hide tools (the Cursor SDK's McpServerConfig
+ *   has no allow-list field), so it denies non-enabled calls in the HITL
+ *   hook instead (execute-cursor/approval-state.ts mcpServerEnabledTools +
+ *   the "disabled" arm in hook-script.ts). Same guarantee, fail-closed.
+ *
+ * Names are bare tool names exactly as reported by tools/list — the same
+ * identity space as the sub-agent McpAccess filter and the approval-policy
+ * maps. An enabled name the server does not expose is warned and dropped
+ * (enforce the intersection): the restriction still holds and the run
+ * proceeds with the valid subset; apply-time validation against
+ * discovered_capabilities is the server-side follow-up that catches typos.
+ */
+/**
+ * Compute the effective allow-list for one resolved MCP server.
+ *
+ * Returns `undefined` when the server is unrestricted (both lists empty) —
+ * the absent-field shape ResolvedMcpServer carries so synthesized attachment
+ * servers and the discovery path stay unfiltered by construction.
+ */
+export declare function effectiveEnabledTools(usageEnabledTools: readonly string[] | undefined, defaultEnabledTools: readonly string[] | undefined): string[] | undefined;
+/**
+ * Filter a server's discovered tools by its effective allow-list.
+ *
+ * `undefined` enabledTools → unrestricted, tools pass through untouched.
+ * Otherwise only tools whose bare name is on the list survive; enabled names
+ * the server does not expose are warned and ignored (warn-and-intersect —
+ * a stale or mistyped name must narrow the toolset, never widen it or fail
+ * the run).
+ */
+export declare function filterToolsByEnabledTools<T extends {
+    name: string;
+}>(slug: string, tools: readonly T[], enabledTools: readonly string[] | undefined): T[];
+/**
+ * Collect the restricted servers' allow-lists keyed by slug — the shape the
+ * Cursor harness writes into the approval state file (mcpServerEnabledTools)
+ * for the hook's "disabled" arm. Unrestricted servers are ABSENT (the hook
+ * treats an absent slug as unrestricted), so the common no-restriction case
+ * stays an empty object.
+ */
+export declare function enabledToolsBySlug(servers: readonly {
+    slug: string;
+    enabledTools?: string[];
+}[]): Record<string, string[]>;

package/dist/shared/mcp-enabled-tools.js

@@ -0,0 +1,86 @@
+/**
+ * Enforcement semantics for McpServerUsage.enabled_tools (issue #350).
+ *
+ * The proto contract (agent/v1/spec.proto McpServerUsage.enabled_tools,
+ * mcpserver/v1/spec.proto McpServerSpec.default_enabled_tools):
+ * - A non-empty enabled_tools on the usage is the allow-list for that server.
+ * - An empty usage list falls back to the server's default_enabled_tools.
+ * - Both empty means NO restriction — every discovered tool is available.
+ *
+ * Both harnesses import THIS module so they can never drift on these
+ * semantics (the mcp-transport-guard precedent for logic shared across the
+ * duplicated resolvers — see the header of shared/mcp-resolver.ts):
+ * - The deep-agent harness filters the discovered toolset before it reaches
+ *   the model (shared/mcp-manager.ts connectMcpServers).
+ * - The Cursor harness cannot hide tools (the Cursor SDK's McpServerConfig
+ *   has no allow-list field), so it denies non-enabled calls in the HITL
+ *   hook instead (execute-cursor/approval-state.ts mcpServerEnabledTools +
+ *   the "disabled" arm in hook-script.ts). Same guarantee, fail-closed.
+ *
+ * Names are bare tool names exactly as reported by tools/list — the same
+ * identity space as the sub-agent McpAccess filter and the approval-policy
+ * maps. An enabled name the server does not expose is warned and dropped
+ * (enforce the intersection): the restriction still holds and the run
+ * proceeds with the valid subset; apply-time validation against
+ * discovered_capabilities is the server-side follow-up that catches typos.
+ */
+/**
+ * Compute the effective allow-list for one resolved MCP server.
+ *
+ * Returns `undefined` when the server is unrestricted (both lists empty) —
+ * the absent-field shape ResolvedMcpServer carries so synthesized attachment
+ * servers and the discovery path stay unfiltered by construction.
+ */
+export function effectiveEnabledTools(usageEnabledTools, defaultEnabledTools) {
+    if (usageEnabledTools && usageEnabledTools.length > 0) {
+        return [...usageEnabledTools];
+    }
+    if (defaultEnabledTools && defaultEnabledTools.length > 0) {
+        return [...defaultEnabledTools];
+    }
+    return undefined;
+}
+/**
+ * Filter a server's discovered tools by its effective allow-list.
+ *
+ * `undefined` enabledTools → unrestricted, tools pass through untouched.
+ * Otherwise only tools whose bare name is on the list survive; enabled names
+ * the server does not expose are warned and ignored (warn-and-intersect —
+ * a stale or mistyped name must narrow the toolset, never widen it or fail
+ * the run).
+ */
+export function filterToolsByEnabledTools(slug, tools, enabledTools) {
+    if (!enabledTools) {
+        return [...tools];
+    }
+    const allowed = new Set(enabledTools);
+    const filtered = tools.filter((tool) => allowed.has(tool.name));
+    const discovered = new Set(tools.map((t) => t.name));
+    const unknown = enabledTools.filter((name) => !discovered.has(name));
+    if (unknown.length > 0) {
+        console.warn(`[MCP] Server '${slug}': enabled_tools lists [${unknown.join(", ")}] ` +
+            `which the server does not expose — ignoring (the run proceeds with ` +
+            `the ${filtered.length} matching tool(s)). Fix the agent's ` +
+            `enabled_tools to match the server's discovered tools.`);
+    }
+    console.log(`[MCP] Server '${slug}': enabled_tools restricts ${tools.length} ` +
+        `discovered tool(s) to ${filtered.length}`);
+    return filtered;
+}
+/**
+ * Collect the restricted servers' allow-lists keyed by slug — the shape the
+ * Cursor harness writes into the approval state file (mcpServerEnabledTools)
+ * for the hook's "disabled" arm. Unrestricted servers are ABSENT (the hook
+ * treats an absent slug as unrestricted), so the common no-restriction case
+ * stays an empty object.
+ */
+export function enabledToolsBySlug(servers) {
+    const bySlug = {};
+    for (const server of servers) {
+        if (server.enabledTools) {
+            bySlug[server.slug] = [...server.enabledTools];
+        }
+    }
+    return bySlug;
+}
+//# sourceMappingURL=mcp-enabled-tools.js.map

package/dist/shared/mcp-enabled-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-enabled-tools.js","sourceRoot":"","sources":["../../src/shared/mcp-enabled-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CACnC,iBAAgD,EAChD,mBAAkD;IAElD,IAAI,iBAAiB,IAAI,iBAAiB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtD,OAAO,CAAC,GAAG,iBAAiB,CAAC,CAAC;IAChC,CAAC;IACD,IAAI,mBAAmB,IAAI,mBAAmB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1D,OAAO,CAAC,GAAG,mBAAmB,CAAC,CAAC;IAClC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,yBAAyB,CACvC,IAAY,EACZ,KAAmB,EACnB,YAA2C;IAE3C,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC;IACpB,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,CAAC;IACtC,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAEhE,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACrD,MAAM,OAAO,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;IACrE,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO,CAAC,IAAI,CACV,iBAAiB,IAAI,2BAA2B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;YACtE,qEAAqE;YACrE,OAAO,QAAQ,CAAC,MAAM,sCAAsC;YAC5D,uDAAuD,CACxD,CAAC;IACJ,CAAC;IAED,OAAO,CAAC,GAAG,CACT,iBAAiB,IAAI,8BAA8B,KAAK,CAAC,MAAM,GAAG;QAClE,yBAAyB,QAAQ,CAAC,MAAM,EAAE,CAC3C,CAAC;IAEF,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAA6D;IAE7D,MAAM,MAAM,GAA6B,EAAE,CAAC;IAC5C,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;YACxB,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}