@stigmer/runner 3.10.0 → 3.11.0

package/dist/shared/datastore-attachment.d.ts

@@ -22,8 +22,12 @@
  *     OSS callers resolve as the local principal (T05 R2).
  *
  * Approval-free by construction (DD-001 SD-3): empty toolApprovals +
- * pinnedToolApprovals mean mergeApprovalPolicies emits no entries for
- * this server — zero classifier involvement. `discoveredCapabilitiesEmpty`
+ * pinnedToolApprovals + toolApprovalOverrides mean mergeApprovalPolicies
+ * emits no entries for this server — zero classifier involvement, and no
+ * proto surface can target it (the attachment has no McpServerUsage, and
+ * since issue #349 an agent's overrides are scoped to their own usage's
+ * server, so a same-named override elsewhere cannot reach this one).
+ * `discoveredCapabilitiesEmpty`
  * is false and the attachment has no McpServerUsage, so the connect
  * backfill (whose destructiveHint tightener would force-gate
  * delete_record — silently skipped on channels under UNATTENDED mode)
@@ -48,9 +52,48 @@ export declare const RECORDS_ROUTE = "/records";
  */
 export declare function synthesizeDatastoreAttachment(datastoreUsages: DatastoreUsage[], options: SynthesizedAttachmentOptions): ResolvedMcpServer | undefined;
 /**
- * The `<available_datastores>` prompt section (DD-005 SD-5, the
- * skills-section precedent): names the attached datastores and points
- * the model at describe_datastore first. Shared by both harnesses so
- * the section text cannot drift (the sender-identity precedent).
+ * The five record tools the records roster always serves (DD-005; the
+ * mcp-server's records roster registers all five unconditionally for the
+ * agent audience — only the `org` argument shape varies by audience, see
+ * mcp-server/src/domains/records/tools.ts). Because the roster never
+ * legitimately narrows, any of these missing from the connected toolset
+ * means the store is degraded (issue #325) — the prompt section and the
+ * reconciliation both derive from this one list so they cannot drift.
  */
-export declare function formatDatastoresSection(datastoreUsages: DatastoreUsage[]): string;
+export declare const EXPECTED_RECORD_TOOLS: readonly ["describe_datastore", "find_records", "insert_record", "update_record", "delete_record"];
+/**
+ * Reconcile the record tools actually connected against the roster
+ * contract (issue #325). Returns the expected tools absent from
+ * `actualToolNames` — empty means healthy. Names are bare tool names
+ * exactly as reported by tools/list (the mcp-enabled-tools identity
+ * space); extraneous names are ignored.
+ */
+export declare function missingRecordTools(actualToolNames: Iterable<string>): string[];
+/**
+ * The operator-facing degradation notice (issue #325): pushed as a
+ * MESSAGE_SYSTEM row on the execution status so "declared N datastores,
+ * X/5 record tools connected" is visible without reading a transcript.
+ * Lives HERE with the rest of the datastore-attachment wording — the
+ * harness only threads it.
+ */
+export declare function formatDatastoreDegradationNotice(declaredCount: number, missing: readonly string[]): string;
+/**
+ * The datastores prompt section (DD-005 SD-5, the skills-section
+ * precedent). Shared by both harnesses so the section text cannot drift
+ * (the sender-identity precedent). Two honest renderings (issue #325):
+ *
+ * - Healthy (`missingToolNames` empty or omitted — the Cursor harness
+ *   always calls it this way: the Cursor SDK connects MCP itself, so
+ *   that harness can never observe the live roster):
+ *   `<available_datastores>` names the attached datastores, points the
+ *   model at describe_datastore first, and carries a standing
+ *   failure-disclosure instruction — the only mechanism that covers
+ *   tools which connected but fail at call time (the WhatsApp-pilot
+ *   outage shape).
+ * - Degraded (deep-agent only, from missingRecordTools against the
+ *   connected roster): `<unavailable_datastores>` instead — the section
+ *   must not promise tools the agent does not have. Names the declared
+ *   datastores, states which record tools are missing, and instructs
+ *   plain disclosure over improvisation.
+ */
+export declare function formatDatastoresSection(datastoreUsages: DatastoreUsage[], missingToolNames?: readonly string[]): string;

package/dist/shared/datastore-attachment.js

@@ -22,8 +22,12 @@
  *     OSS callers resolve as the local principal (T05 R2).
  *
  * Approval-free by construction (DD-001 SD-3): empty toolApprovals +
- * pinnedToolApprovals mean mergeApprovalPolicies emits no entries for
- * this server — zero classifier involvement. `discoveredCapabilitiesEmpty`
+ * pinnedToolApprovals + toolApprovalOverrides mean mergeApprovalPolicies
+ * emits no entries for this server — zero classifier involvement, and no
+ * proto surface can target it (the attachment has no McpServerUsage, and
+ * since issue #349 an agent's overrides are scoped to their own usage's
+ * server, so a same-named override elsewhere cannot reach this one).
+ * `discoveredCapabilitiesEmpty`
  * is false and the attachment has no McpServerUsage, so the connect
  * backfill (whose destructiveHint tightener would force-gate
  * delete_record — silently skipped on channels under UNATTENDED mode)
@@ -53,6 +57,7 @@ export function synthesizeDatastoreAttachment(datastoreUsages, options) {
         slug: DATASTORE_ATTACHMENT_SLUG,
         toolApprovals: [],
         pinnedToolApprovals: [],
+        toolApprovalOverrides: [],
         discoveredCapabilitiesEmpty: false,
     };
     if (options.bridgeEndpoint !== null && options.bridgeEndpoint !== "") {
@@ -77,25 +82,102 @@ export function synthesizeDatastoreAttachment(datastoreUsages, options) {
     };
 }
 /**
- * The `<available_datastores>` prompt section (DD-005 SD-5, the
- * skills-section precedent): names the attached datastores and points
- * the model at describe_datastore first. Shared by both harnesses so
- * the section text cannot drift (the sender-identity precedent).
+ * The five record tools the records roster always serves (DD-005; the
+ * mcp-server's records roster registers all five unconditionally for the
+ * agent audience — only the `org` argument shape varies by audience, see
+ * mcp-server/src/domains/records/tools.ts). Because the roster never
+ * legitimately narrows, any of these missing from the connected toolset
+ * means the store is degraded (issue #325) — the prompt section and the
+ * reconciliation both derive from this one list so they cannot drift.
  */
-export function formatDatastoresSection(datastoreUsages) {
-    const slugs = datastoreUsages
+export const EXPECTED_RECORD_TOOLS = [
+    "describe_datastore",
+    "find_records",
+    "insert_record",
+    "update_record",
+    "delete_record",
+];
+/**
+ * Reconcile the record tools actually connected against the roster
+ * contract (issue #325). Returns the expected tools absent from
+ * `actualToolNames` — empty means healthy. Names are bare tool names
+ * exactly as reported by tools/list (the mcp-enabled-tools identity
+ * space); extraneous names are ignored.
+ */
+export function missingRecordTools(actualToolNames) {
+    const present = new Set(actualToolNames);
+    return EXPECTED_RECORD_TOOLS.filter((name) => !present.has(name));
+}
+/**
+ * The operator-facing degradation notice (issue #325): pushed as a
+ * MESSAGE_SYSTEM row on the execution status so "declared N datastores,
+ * X/5 record tools connected" is visible without reading a transcript.
+ * Lives HERE with the rest of the datastore-attachment wording — the
+ * harness only threads it.
+ */
+export function formatDatastoreDegradationNotice(declaredCount, missing) {
+    const connected = EXPECTED_RECORD_TOOLS.length - missing.length;
+    return (`Datastore record tools unavailable this turn: declared ` +
+        `${declaredCount} datastore(s), ${connected}/${EXPECTED_RECORD_TOOLS.length} ` +
+        `record tools connected (missing: ${missing.join(", ")}). The agent has ` +
+        `been instructed to disclose this instead of answering from memory.`);
+}
+/**
+ * The datastores prompt section (DD-005 SD-5, the skills-section
+ * precedent). Shared by both harnesses so the section text cannot drift
+ * (the sender-identity precedent). Two honest renderings (issue #325):
+ *
+ * - Healthy (`missingToolNames` empty or omitted — the Cursor harness
+ *   always calls it this way: the Cursor SDK connects MCP itself, so
+ *   that harness can never observe the live roster):
+ *   `<available_datastores>` names the attached datastores, points the
+ *   model at describe_datastore first, and carries a standing
+ *   failure-disclosure instruction — the only mechanism that covers
+ *   tools which connected but fail at call time (the WhatsApp-pilot
+ *   outage shape).
+ * - Degraded (deep-agent only, from missingRecordTools against the
+ *   connected roster): `<unavailable_datastores>` instead — the section
+ *   must not promise tools the agent does not have. Names the declared
+ *   datastores, states which record tools are missing, and instructs
+ *   plain disclosure over improvisation.
+ */
+export function formatDatastoresSection(datastoreUsages, missingToolNames = []) {
+    const entries = datastoreUsages
         .map((u) => u.datastoreRef?.slug)
-        .filter((s) => !!s);
-    const entries = slugs.map((slug) => `- ${slug}`);
+        .filter((s) => !!s)
+        .map((slug) => `- ${slug}`);
+    if (missingToolNames.length > 0) {
+        return [
+            "<unavailable_datastores>",
+            "This agent is configured to use the datastores listed below, but the",
+            "following record tools failed to connect this turn:",
+            missingToolNames.join(", ") + ".",
+            "Treat these datastores as unreachable for any operation that needs a",
+            "missing tool.",
+            "",
+            ...entries,
+            "",
+            "When the user's request depends on one of these datastores, tell them",
+            "plainly that the datastore cannot be reached right now. Never answer",
+            "from memory, guess, or improvise a substitute for what the datastore",
+            "would have returned.",
+            "</unavailable_datastores>",
+        ].join("\n");
+    }
     return [
         "<available_datastores>",
         "You have access to the following datastores through the record tools",
-        "(describe_datastore, find_records, insert_record, update_record, delete_record).",
+        `(${EXPECTED_RECORD_TOOLS.join(", ")}).`,
         "Before your first operation against a datastore, call describe_datastore to",
         "learn its collections, field encodings, and which operations you are allowed",
         "to perform.",
         "",
         ...entries,
+        "",
+        "If any record tool is missing from your toolset or a record tool call",
+        "fails, the datastore is unreachable: tell the user plainly that you cannot",
+        "reach it right now, and do not answer from memory, guess, or improvise a",
+        "substitute for what it would have returned.",
         "</available_datastores>",
     ].join("\n");
 }

package/dist/shared/datastore-attachment.js.map

@@ -1 +1 @@
-{"version":3,"file":"datastore-attachment.js","sourceRoot":"","sources":["../../src/shared/datastore-attachment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAIH,OAAO,EAAE,UAAU,EAAqC,MAAM,6BAA6B,CAAC;AAE5F;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,iBAAiB,CAAC;AAE3D,4EAA4E;AAC5E,MAAM,CAAC,MAAM,aAAa,GAAG,UAAU,CAAC;AAExC;;;;GAIG;AACH,MAAM,UAAU,6BAA6B,CAC3C,eAAiC,EACjC,OAAqC;IAErC,IAAI,eAAe,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjC,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,mEAAmE;IACnE,MAAM,IAAI,GAAG;QACX,IAAI,EAAE,yBAAyB;QAC/B,aAAa,EAAE,EAAE;QACjB,mBAAmB,EAAE,EAAE;QACvB,2BAA2B,EAAE,KAAK;KACnC,CAAC;IAEF,IAAI,OAAO,CAAC,cAAc,KAAK,IAAI,IAAI,OAAO,CAAC,cAAc,KAAK,EAAE,EAAE,CAAC;QACrE,OAAO;YACL,GAAG,IAAI;YACP,cAAc,EAAE,MAAM;YACtB,GAAG,EAAE,OAAO,CAAC,cAAc,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,aAAa;YAC/D,OAAO,EAAE,OAAO,CAAC,UAAU,KAAK,IAAI,IAAI,OAAO,CAAC,UAAU,KAAK,EAAE;gBAC/D,CAAC,CAAC,EAAE,aAAa,EAAE,UAAU,OAAO,CAAC,UAAU,EAAE,EAAE;gBACnD,CAAC,CAAC,SAAS;SACd,CAAC;IACJ,CAAC;IAED,OAAO;QACL,GAAG,IAAI;QACP,cAAc,EAAE,OAAO;QACvB,OAAO,EAAE,SAAS;QAClB,IAAI,EAAE,CAAC,YAAY,CAAC;QACpB,GAAG,EAAE;YACH,kBAAkB,EAAE,SAAS;YAC7B,sBAAsB,EAAE,UAAU,CAAC,OAAO,CAAC,eAAe,CAAC;SAC5D;KACF,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,eAAiC;IACvE,MAAM,KAAK,GAAG,eAAe;SAC1B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,EAAE,IAAI,CAAC;SAChC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;IACjD,OAAO;QACL,wBAAwB;QACxB,sEAAsE;QACtE,kFAAkF;QAClF,6EAA6E;QAC7E,8EAA8E;QAC9E,aAAa;QACb,EAAE;QACF,GAAG,OAAO;QACV,yBAAyB;KAC1B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}
+{"version":3,"file":"datastore-attachment.js","sourceRoot":"","sources":["../../src/shared/datastore-attachment.ts"],"names":[],"mappings":"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"}

package/dist/shared/http-retry.d.ts

@@ -0,0 +1,43 @@
+/**
+ * HTTP error classification for side-channel proxy retries.
+ *
+ * The runner reaches stigmer-service's Side-Channel Proxy (`/v1/proxy/...`)
+ * over plain `fetch` from several clients — the checkpoint saver today;
+ * artifact storage, the LLM proxy, and the registry endpoint are candidates
+ * (stigmer/stigmer#468). This module is the one place that answers "is this
+ * HTTP failure worth retrying?", the `fetch` twin of grpc-retry.ts: it holds
+ * the classification policy only, kept small and separately tested. The
+ * bounded-backoff loop that consumes it lives with each client (the
+ * grpc-retry/status.ts split).
+ *
+ * The policy is grounded in what the proxy actually emits, not HTTP folklore.
+ * CheckpointerProxyController returns exactly four deterministic errors —
+ * 400 (malformed document), 403 (FGA deny), 404 (no such checkpoint), and
+ * 413 (the 4 MB cap) — and never a transient status. Transient failures
+ * reach the runner only as 5xx (Spring's error handler, ingress 502-504),
+ * 408/429 (infrastructure between runner and service), or as network-level
+ * fetch rejections. 401/403 stay terminal deliberately: retrying cannot fix
+ * an expired or rejected credential.
+ */
+/**
+ * True for HTTP statuses that signal a transient condition worth retrying:
+ * 408 (request timeout), 429 (throttled), and all 5xx. Every other status is
+ * deterministic — the proxy's 4xx errors mean the same request will fail the
+ * same way forever.
+ */
+export declare function isRetryableHttpStatus(status: number): boolean;
+/**
+ * True for `fetch` rejections that signal a transient transport condition:
+ *
+ * - `TypeError` — undici's network-failure shape (`fetch failed`, with the
+ *   ECONNREFUSED/ECONNRESET/DNS cause attached). A deterministic TypeError
+ *   (e.g. a malformed URL) also matches, which is accepted: such a bug fails
+ *   every attempt including the first test run, and the bounded budget caps
+ *   the wasted retries at seconds.
+ * - `TimeoutError` — the rejection shape of `AbortSignal.timeout()`, i.e. a
+ *   hung connection whose attempt we bounded ourselves.
+ *
+ * A manual abort (`AbortError`) is deliberately NOT retryable: the caller
+ * cancelled on purpose.
+ */
+export declare function isRetryableFetchError(err: unknown): boolean;

package/dist/shared/http-retry.js

@@ -0,0 +1,50 @@
+/**
+ * HTTP error classification for side-channel proxy retries.
+ *
+ * The runner reaches stigmer-service's Side-Channel Proxy (`/v1/proxy/...`)
+ * over plain `fetch` from several clients — the checkpoint saver today;
+ * artifact storage, the LLM proxy, and the registry endpoint are candidates
+ * (stigmer/stigmer#468). This module is the one place that answers "is this
+ * HTTP failure worth retrying?", the `fetch` twin of grpc-retry.ts: it holds
+ * the classification policy only, kept small and separately tested. The
+ * bounded-backoff loop that consumes it lives with each client (the
+ * grpc-retry/status.ts split).
+ *
+ * The policy is grounded in what the proxy actually emits, not HTTP folklore.
+ * CheckpointerProxyController returns exactly four deterministic errors —
+ * 400 (malformed document), 403 (FGA deny), 404 (no such checkpoint), and
+ * 413 (the 4 MB cap) — and never a transient status. Transient failures
+ * reach the runner only as 5xx (Spring's error handler, ingress 502-504),
+ * 408/429 (infrastructure between runner and service), or as network-level
+ * fetch rejections. 401/403 stay terminal deliberately: retrying cannot fix
+ * an expired or rejected credential.
+ */
+/**
+ * True for HTTP statuses that signal a transient condition worth retrying:
+ * 408 (request timeout), 429 (throttled), and all 5xx. Every other status is
+ * deterministic — the proxy's 4xx errors mean the same request will fail the
+ * same way forever.
+ */
+export function isRetryableHttpStatus(status) {
+    return status === 408 || status === 429 || status >= 500;
+}
+/**
+ * True for `fetch` rejections that signal a transient transport condition:
+ *
+ * - `TypeError` — undici's network-failure shape (`fetch failed`, with the
+ *   ECONNREFUSED/ECONNRESET/DNS cause attached). A deterministic TypeError
+ *   (e.g. a malformed URL) also matches, which is accepted: such a bug fails
+ *   every attempt including the first test run, and the bounded budget caps
+ *   the wasted retries at seconds.
+ * - `TimeoutError` — the rejection shape of `AbortSignal.timeout()`, i.e. a
+ *   hung connection whose attempt we bounded ourselves.
+ *
+ * A manual abort (`AbortError`) is deliberately NOT retryable: the caller
+ * cancelled on purpose.
+ */
+export function isRetryableFetchError(err) {
+    if (err instanceof TypeError)
+        return true;
+    return err instanceof Error && err.name === "TimeoutError";
+}
+//# sourceMappingURL=http-retry.js.map

package/dist/shared/http-retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-retry.js","sourceRoot":"","sources":["../../src/shared/http-retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAc;IAClD,OAAO,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,IAAI,GAAG,CAAC;AAC3D,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAY;IAChD,IAAI,GAAG,YAAY,SAAS;QAAE,OAAO,IAAI,CAAC;IAC1C,OAAO,GAAG,YAAY,KAAK,IAAI,GAAG,CAAC,IAAI,KAAK,cAAc,CAAC;AAC7D,CAAC"}

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

@@ -0,0 +1,275 @@
+/**
+ * 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`.
+ */
+import type { LlmProvider } from "./llm-proxy.js";
+/** Env var selecting where Anthropic models are served. */
+export declare const ANTHROPIC_BACKEND_ENV = "STIGMER_ANTHROPIC_BACKEND";
+/** Env var selecting where OpenAI models are served. */
+export declare const OPENAI_BACKEND_ENV = "STIGMER_OPENAI_BACKEND";
+/** Operator guide for backend configuration; the single copy of this URL. */
+export declare const BACKEND_DOC_URL = "https://docs.stigmer.ai/guides/runners/model-backends";
+/**
+ * Backends implemented in this build. Anthropic's values name the serving
+ * SERVICE, not the cloud (`foundry` is Microsoft Foundry, the Azure
+ * service that hosts Claude — "azure" would collide with the unrelated
+ * Azure OpenAI service). The design vocabulary also reserves `azure`
+ * (OpenAI); until that adapter lands — contingent on OpenAI models
+ * entering the native catalog — selecting it is a distinct "recognized
+ * but not implemented" failure, never a silent fallback to the public
+ * API, which would quietly route traffic outside the compliance boundary
+ * the operator asked for.
+ */
+export type AnthropicBackend = "public" | "vertex" | "bedrock" | "foundry";
+export type OpenAiBackend = "public";
+/**
+ * Result of parsing a backend env var. `message` is the operator-facing
+ * text; it names the exact var, the bad value, and what is supported, and
+ * is the single copy of that text (preflight, model construction, and any
+ * future consumer all surface this same string).
+ */
+export type BackendParseResult<B> = {
+    readonly ok: true;
+    readonly backend: B;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/** Parse `STIGMER_ANTHROPIC_BACKEND` (unset → `public`). */
+export declare function parseAnthropicBackend(env?: NodeJS.ProcessEnv): BackendParseResult<AnthropicBackend>;
+/** Parse `STIGMER_OPENAI_BACKEND` (unset → `public`). */
+export declare function parseOpenAiBackend(env?: NodeJS.ProcessEnv): BackendParseResult<OpenAiBackend>;
+/**
+ * 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 declare function resolveAnthropicBackend(env?: NodeJS.ProcessEnv): AnthropicBackend;
+/**
+ * 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 declare function checkVertexPrerequisites(env?: NodeJS.ProcessEnv): string | null;
+/** Operator override map: canonical id -> exact Bedrock id, consulted first. */
+export declare const BEDROCK_MODEL_MAP_ENV = "STIGMER_BEDROCK_MODEL_MAP";
+/** Inference-profile geography prefix (`us`, `eu`, `global`, …), no default. */
+export declare 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 declare function checkBedrockPrerequisites(env?: NodeJS.ProcessEnv): string | null;
+type ModelMapParseResult = {
+    readonly ok: true;
+    readonly map: ReadonlyMap<string, string>;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * 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 declare function parseBedrockModelMap(env?: NodeJS.ProcessEnv): ModelMapParseResult;
+/**
+ * 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 declare const FOUNDRY_DEPLOYMENT_MAP_ENV = "STIGMER_FOUNDRY_DEPLOYMENT_MAP";
+/** The Foundry resource name (SDK-native; builds the endpoint host). */
+export declare const FOUNDRY_RESOURCE_ENV = "ANTHROPIC_FOUNDRY_RESOURCE";
+/** Full endpoint override (SDK-native; mutually exclusive with resource). */
+export declare 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 declare function parseFoundryDeploymentMap(env?: NodeJS.ProcessEnv): ModelMapParseResult;
+/**
+ * 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 declare function checkFoundryPrerequisites(env?: NodeJS.ProcessEnv): string | 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 declare function checkDirectCredentials(provider: LlmProvider, env?: NodeJS.ProcessEnv): string | null;
+export interface LlmBackendPreflight {
+    /** Fatal, actionable operator message; null when the config is usable. */
+    readonly error: string | null;
+    /** Non-fatal operator notices (e.g. proxy overrides backend selection). */
+    readonly warnings: readonly string[];
+}
+/**
+ * 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 declare function preflightLlmBackends(env?: NodeJS.ProcessEnv): LlmBackendPreflight;
+/**
+ * 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 declare function toVertexModelId(apiModelId: string): string;
+/**
+ * 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 declare function toBedrockModelId(apiModelId: string, env?: NodeJS.ProcessEnv): string;
+/**
+ * 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 declare function toFoundryDeploymentName(apiModelId: string, env?: NodeJS.ProcessEnv): string;
+export {};