@stigmer/mcp-server 3.12.0 → 3.12.2

package/src/domains/apply-visibility.ts

@@ -0,0 +1,47 @@
+// Declared-visibility follow-up for the apply tools (oss#573).
+//
+// Plain updates preserve the stored visibility on both editions — the
+// updateVisibility RPC is the only door for visibility changes, where the
+// server-side guards live (per-kind level support, default-instance
+// rejection). So when an apply tool's input declares a visibility and the
+// applied resource comes back with a different level (i.e. the resource
+// already existed), we follow up with one UpdateVisibility RPC on the same
+// controller. The CLI's skill-push and manifest-apply flows do the same.
+//
+// No-ops are skipped (input omitted visibility, create honored it, or the
+// stored level already matches), so an unchanged apply costs nothing extra.
+// Guard rejections propagate to the caller's rpcError wrapper — the model
+// sees the real FAILED_PRECONDITION / INVALID_ARGUMENT, not a silent lie.
+
+import { create } from "@bufbuild/protobuf";
+import type { CallOptions } from "@connectrpc/connect";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import { UpdateVisibilityInputSchema, type UpdateVisibilityInput } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import type { ApiResourceMetadata } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+
+interface HasResourceMetadata {
+  metadata?: ApiResourceMetadata;
+}
+
+interface UpdateVisibilityClient<T> {
+  updateVisibility(input: UpdateVisibilityInput, options?: CallOptions): Promise<T>;
+}
+
+/**
+ * Land the input-declared visibility through the guarded door when the
+ * applied resource's stored level differs. Returns the resource carrying the
+ * final visibility (the follow-up's response, or `applied` unchanged when no
+ * follow-up was needed).
+ */
+export async function applyDeclaredVisibility<T extends HasResourceMetadata>(
+  client: UpdateVisibilityClient<T>,
+  callOptions: CallOptions,
+  applied: T,
+  declared: ApiResourceVisibility,
+): Promise<T> {
+  if (declared === ApiResourceVisibility.api_resource_visibility_unspecified) return applied;
+  const resourceId = applied.metadata?.id ?? "";
+  if (resourceId === "") return applied;
+  if (applied.metadata?.visibility === declared) return applied;
+  return client.updateVisibility(create(UpdateVisibilityInputSchema, { resourceId, visibility: declared }), callOptions);
+}

package/src/domains/apply.integration.test.ts

@@ -7,6 +7,7 @@
 // data map with secret flags, and the recursive workflow task_config expansion
 // (http_call leaf, fork/for_each nesting).
 
+import { clone } from "@bufbuild/protobuf";
 import type { ConnectRouter } from "@connectrpc/connect";
 import { connectNodeAdapter } from "@connectrpc/connect-node";
 import {
@@ -18,7 +19,7 @@ import type { AddressInfo } from "node:net";
 
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
-import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { type Agent, AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
 import { AgentCommandController } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/command_pb";
 import type { Environment } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/api_pb";
 import { EnvironmentCommandController } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/command_pb";
@@ -29,6 +30,7 @@ import { WorkflowCommandController } from "@stigmer/protos/ai/stigmer/agentic/wo
 import { WorkflowTaskKind } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/enum_pb";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import type { UpdateVisibilityInput } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 
 import { configureLogger } from "../logger";
@@ -42,6 +44,13 @@ let appliedAgent: Agent | undefined;
 let appliedMcpServer: McpServerProto | undefined;
 let appliedWorkflow: Workflow | undefined;
 let appliedEnvironment: Environment | undefined;
+const visibilityUpdates: UpdateVisibilityInput[] = [];
+
+// The single-door contract (oss#573): a plain update preserves the STORED
+// visibility, so the apply response can disagree with the request. This slug
+// makes the mock backend simulate that — apply echoes back a pre-existing
+// resource whose stored level is org, regardless of the requested one.
+const STORED_ORG_SLUG = "stored-org-agent";
 const openSessions = new Set<ServerHttp2Session>();
 
 interface ToolResult {
@@ -58,8 +67,21 @@ beforeAll(async () => {
     router.service(AgentCommandController, {
       apply: (req) => {
         appliedAgent = req;
+        if (req.metadata?.slug === STORED_ORG_SLUG) {
+          const stored = clone(AgentSchema, req);
+          stored.metadata!.id = "agent-stored-1";
+          stored.metadata!.visibility = ApiResourceVisibility.visibility_org;
+          return stored;
+        }
         return req;
       },
+      updateVisibility: (input) => {
+        visibilityUpdates.push(input);
+        const updated = clone(AgentSchema, appliedAgent!);
+        updated.metadata!.id = input.resourceId;
+        updated.metadata!.visibility = input.visibility;
+        return updated;
+      },
     });
     router.service(McpServerCommandController, {
       apply: (req) => {
@@ -234,6 +256,38 @@ describe("apply tools integration", () => {
     expect(forCfg.do).toHaveLength(1);
   });
 
+  it("apply_agent lands a declared visibility the update preserved away via UpdateVisibility (oss#573)", async () => {
+    const result = await callTool("apply_agent", {
+      name: "Stored Org Agent",
+      org: "acme",
+      visibility: "PUBLIC",
+      instructions: "i",
+    });
+    expect(result.isError).toBeFalsy();
+
+    // Server "preserved" stored org; the tool must follow up once through
+    // the guarded door and return the landed level, not the stale one.
+    expect(visibilityUpdates).toHaveLength(1);
+    expect(visibilityUpdates[0].resourceId).toBe("agent-stored-1");
+    expect(visibilityUpdates[0].visibility).toBe(ApiResourceVisibility.visibility_public);
+    const text = result.content.find((c) => c.type === "text")?.text ?? "";
+    expect(JSON.parse(text).metadata.visibility).toBe("visibility_public");
+  });
+
+  it("apply_agent skips the follow-up when the server already matches", async () => {
+    visibilityUpdates.length = 0;
+    const result = await callTool("apply_agent", {
+      name: "Plain Agent",
+      org: "acme",
+      visibility: "PUBLIC",
+      instructions: "i",
+    });
+    expect(result.isError).toBeFalsy();
+    // The echo backend returns the requested level (and no id) — no diff,
+    // no follow-up.
+    expect(visibilityUpdates).toHaveLength(0);
+  });
+
   it("apply_environment rebuilds the data map with secret flags", async () => {
     const result = await callTool("apply_environment", {
       name: "GitHub Creds",

package/src/domains/environments/apply.ts

@@ -11,7 +11,10 @@
 import { EnvironmentSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/api_pb";
 import { EnvironmentCommandController } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/command_pb";
 
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+
 import { environmentInputToProto, type EnvironmentInput } from "../../gen/environment.js";
+import { applyDeclaredVisibility } from "../apply-visibility.js";
 import { withClient } from "../client.js";
 import { toProtoJson } from "../marshal.js";
 import { rpcError } from "../rpcerr.js";
@@ -30,7 +33,13 @@ export async function applyEnvironment(
     token,
     async (client, callOptions) => {
       try {
-        const result = await client.apply(environment, callOptions);
+        const applied = await client.apply(environment, callOptions);
+        const result = await applyDeclaredVisibility(
+          client,
+          callOptions,
+          applied,
+          environment.metadata?.visibility ?? ApiResourceVisibility.api_resource_visibility_unspecified,
+        );
         return toProtoJson(EnvironmentSchema, result);
       } catch (err) {
         throw rpcError(err, desc);

package/src/domains/mcpservers/apply.ts

@@ -7,7 +7,10 @@
 import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
 import { McpServerCommandController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/command_pb";
 
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+
 import { mcpServerInputToProto, type McpServerInput } from "../../gen/mcpserver.js";
+import { applyDeclaredVisibility } from "../apply-visibility.js";
 import { withClient } from "../client.js";
 import { toProtoJson } from "../marshal.js";
 import { rpcError } from "../rpcerr.js";
@@ -26,7 +29,13 @@ export async function applyMcpServer(
     token,
     async (client, callOptions) => {
       try {
-        const result = await client.apply(server, callOptions);
+        const applied = await client.apply(server, callOptions);
+        const result = await applyDeclaredVisibility(
+          client,
+          callOptions,
+          applied,
+          server.metadata?.visibility ?? ApiResourceVisibility.api_resource_visibility_unspecified,
+        );
         return toProtoJson(McpServerSchema, result);
       } catch (err) {
         throw rpcError(err, desc);

package/src/domains/workflows/apply.ts

@@ -11,7 +11,10 @@
 import { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
 import { WorkflowCommandController } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/command_pb";
 
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+
 import { workflowInputToProto, type WorkflowInput } from "../../gen/workflow.js";
+import { applyDeclaredVisibility } from "../apply-visibility.js";
 import { withClient } from "../client.js";
 import { toProtoJson } from "../marshal.js";
 import { rpcError } from "../rpcerr.js";
@@ -30,7 +33,13 @@ export async function applyWorkflow(
     token,
     async (client, callOptions) => {
       try {
-        const result = await client.apply(workflow, callOptions);
+        const applied = await client.apply(workflow, callOptions);
+        const result = await applyDeclaredVisibility(
+          client,
+          callOptions,
+          applied,
+          workflow.metadata?.visibility ?? ApiResourceVisibility.api_resource_visibility_unspecified,
+        );
         return toProtoJson(WorkflowSchema, result);
       } catch (err) {
         throw rpcError(err, desc);

package/src/gen/agent.ts

@@ -18,7 +18,7 @@ export const AgentInputShape = {
   name: z.string().describe("Human-readable name of the resource."),
   slug: z.string().optional().describe("URL-friendly identifier (lowercase alphanumeric with hyphens). Auto-generated from name if omitted."),
   org: z.string().describe("Organization that owns this resource (e.g. acme)."),
-  visibility: z.string().optional().describe("Resource visibility: PRIVATE or PUBLIC. Omit to leave unchanged on updates."),
+  visibility: z.string().optional().describe("Resource visibility: PRIVATE or PUBLIC. Applied at create; on updates a changed value is landed through the guarded UpdateVisibility RPC. Omit to leave unchanged."),
   labels: z.record(z.string()).optional().describe("Key-value labels for organization and filtering."),
   tags: z.array(z.string()).optional().describe("Tags for categorization and discovery."),
   description: z.string().optional().describe("Human-readable description for UI and marketplace display."),

package/src/gen/environment.ts

@@ -15,7 +15,7 @@ export const EnvironmentInputShape = {
   name: z.string().describe("Human-readable name of the resource."),
   slug: z.string().optional().describe("URL-friendly identifier (lowercase alphanumeric with hyphens). Auto-generated from name if omitted."),
   org: z.string().describe("Organization that owns this resource (e.g. acme)."),
-  visibility: z.string().optional().describe("Resource visibility: PRIVATE or PUBLIC. Omit to leave unchanged on updates."),
+  visibility: z.string().optional().describe("Resource visibility: PRIVATE or PUBLIC. Applied at create; on updates a changed value is landed through the guarded UpdateVisibility RPC. Omit to leave unchanged."),
   labels: z.record(z.string()).optional().describe("Key-value labels for organization and filtering."),
   tags: z.array(z.string()).optional().describe("Tags for categorization and discovery."),
   description: z.string().optional().describe("Human-readable description for UI and listing display."),

package/src/gen/mcpserver.ts

@@ -18,7 +18,7 @@ export const McpServerInputShape = {
   name: z.string().describe("Human-readable name of the resource."),
   slug: z.string().optional().describe("URL-friendly identifier (lowercase alphanumeric with hyphens). Auto-generated from name if omitted."),
   org: z.string().describe("Organization that owns this resource (e.g. acme)."),
-  visibility: z.string().optional().describe("Resource visibility: PRIVATE or PUBLIC. Omit to leave unchanged on updates."),
+  visibility: z.string().optional().describe("Resource visibility: PRIVATE or PUBLIC. Applied at create; on updates a changed value is landed through the guarded UpdateVisibility RPC. Omit to leave unchanged."),
   labels: z.record(z.string()).optional().describe("Key-value labels for organization and filtering."),
   tags: z.array(z.string()).optional().describe("Tags for categorization and discovery."),
   description: z.string().optional().describe("Human-readable description for marketplace display and documentation. Should explain what this MCP server does and its primary use cases. Example: 'GitHub MCP server for repository operations, code search, and PR management'"),
@@ -27,7 +27,7 @@ export const McpServerInputShape = {
   http: z.lazy(() => HttpServerConfigInputSchema).optional().describe("HTTP-based server (HTTP + Server-Sent Events communication). Used for remote/managed MCP services accessible over the network."),
   default_enabled_tools: z.array(z.string()).optional().describe("Default tools to enable from this MCP server. Empty list means all tools are enabled by default. Applies whenever an agent's McpServerUsage.enabled_tools is empty."),
   env: z.record(z.lazy(() => EnvVarDeclarationInputSchema)).optional().describe("Environment variable declarations for this MCP server. Keys are variable names; values describe their metadata and optionality."),
-  pinned_tool_approvals: z.array(z.lazy(() => ToolApprovalPolicyInputSchema)).optional().describe("Manual tool approval overrides set by the MCP server owner."),
+  pinned_tool_approvals: z.array(z.lazy(() => ToolApprovalPolicyInputSchema)).optional().describe("Tools pinned by the MCP server owner to always require approval."),
   repository_url: z.string().optional().describe("URL of the upstream source repository for this MCP server. Shown in the marketplace so users can inspect the implementation for trust and transparency. Example: 'https://github.com/modelcontextprotocol/servers'"),
   github_stars: z.number().optional().describe("GitHub star count at the time of curation. Used as a popularity signal in marketplace display. 0 if unknown or non-GitHub repository."),
   auth: z.lazy(() => McpServerAuthInputSchema).optional().describe("OAuth authentication configuration for automated credential acquisition. When set, the MCP server's Connect page offers an OAuth flow instead of (or in addition to) manual credential entry. The acquired access token is stored in a system-managed environment (identified by grant.environment_id) as the env var named by auth.target_env_var. That env var must also be declared in env so the execution pipeline knows about it."),

package/src/gen/workflow.ts

@@ -45,7 +45,7 @@ export const WorkflowInputShape = {
   name: z.string().describe("Human-readable name of the resource."),
   slug: z.string().optional().describe("URL-friendly identifier (lowercase alphanumeric with hyphens). Auto-generated from name if omitted."),
   org: z.string().describe("Organization that owns this resource (e.g. acme)."),
-  visibility: z.string().optional().describe("Resource visibility: PRIVATE or PUBLIC. Omit to leave unchanged on updates."),
+  visibility: z.string().optional().describe("Resource visibility: PRIVATE or PUBLIC. Applied at create; on updates a changed value is landed through the guarded UpdateVisibility RPC. Omit to leave unchanged."),
   labels: z.record(z.string()).optional().describe("Key-value labels for organization and filtering."),
   tags: z.array(z.string()).optional().describe("Tags for categorization and discovery."),
   description: z.string().optional().describe("Human-readable description for UI and marketplace display."),
@@ -121,7 +121,7 @@ const AgentCallTaskConfigInputSchema = z.object({
   env: z.record(z.string()).optional().describe("Runtime environment variables to pass to the agent. Values can be literal strings or JQ expressions that reference workflow context or secrets. Example: {'GITHUB_TOKEN': '${ .secrets.GH_TOKEN }'} Optional."),
   run_config: z.lazy(() => RunConfigInputSchema).optional().describe("Per-call model choice and run bounds. Unset fields inherit the platform defaults."),
   output: z.lazy(() => AgentCallOutputContractInputSchema).optional().describe("Structured output contract for this agent call. When set, the workflow runner extracts structured JSON from the agent's final response and validates it against the declared schema. The validated JSON is placed in the task output under the 'structured' key, enabling reliable downstream routing via switch_case expressions. When not set, the task output contains the agent's raw text response. @since T02 (Structured Agent Output Model)"),
-  harness: z.string().optional().describe("Execution harness for the agent invocation. Determines which execution engine processes the agent call: - HARNESS_UNSPECIFIED / HARNESS_NATIVE: Stigmer native engine (Python/LangGraph) - HARNESS_CURSOR: Cursor SDK engine (TypeScript/Cursor) The workflow-runner creates a Session with this harness before creating the AgentExecution. The harness is a session-level concern — it determines tool availability, state management, model access, and billing tier. When unspecified, defaults to HARNESS_NATIVE (the workflow surface's platform default). YAML Example: - code_review: call: agent with: agent: 'code-reviewer' harness: cursor message: 'Review this PR' Allowed values: HARNESS_NATIVE, HARNESS_CURSOR."),
+  harness: z.string().optional().describe("Execution harness for the agent invocation. Determines which execution engine processes the agent call: - HARNESS_UNSPECIFIED / HARNESS_NATIVE: Stigmer native engine (Python/LangGraph) - HARNESS_CURSOR: Cursor SDK engine (TypeScript/Cursor) The runner creates a Session with this harness before creating the AgentExecution. The harness is a session-level concern — it determines tool availability, state management, model access, and billing tier. When unspecified, defaults to HARNESS_NATIVE (the workflow surface's platform default). YAML Example: - code_review: call: agent with: agent: 'code-reviewer' harness: cursor message: 'Review this PR' Allowed values: HARNESS_NATIVE, HARNESS_CURSOR."),
   workspace_entries: z.array(z.lazy(() => WorkspaceEntryInputSchema)).optional().describe("Workspace the child run's session operates on. Empty means no workspace."),
   environment_refs: z.array(z.lazy(() => EnvironmentRefInputSchema)).optional().describe("References to Environment resources whose values are provided to the child runs this task creates. This is how a tool-using agent becomes runnable from a workflow: bind an org-shared environment holding the needed credentials, and the child runs receive its values at runtime. The agent and its default instance stay untouched."),
 });

package/src/http.integration.test.ts

@@ -68,6 +68,21 @@ afterAll(async () => {
 
 const base = () => `http://127.0.0.1:${port}`;
 
+/**
+ * Every refusal must be a JSON-RPC error object with Content-Type
+ * application/json (oss#316 — strict MCP clients parse the body; text/plain
+ * surfaced as opaque content-type errors). Returns the error for
+ * code-specific assertions.
+ */
+async function expectJsonRpcError(res: Response): Promise<{ code: number; message: string }> {
+  expect(res.headers.get("content-type")).toBe("application/json");
+  const body = (await res.json()) as { jsonrpc: string; error: { code: number; message: string }; id: null };
+  expect(body.jsonrpc).toBe("2.0");
+  expect(body.id).toBeNull();
+  expect(typeof body.error.code).toBe("number");
+  return body.error;
+}
+
 describe("HTTP transport hardening + OAuth discovery", () => {
   it("answers the /health probe without auth", async () => {
     const res = await fetch(`${base()}/health`);
@@ -75,6 +90,16 @@ describe("HTTP transport hardening + OAuth discovery", () => {
     expect(await res.json()).toEqual({ status: "ok" });
   });
 
+  it("reports unready on /ready when the backend hop is down (no auth required)", async () => {
+    // The suite's backend address points at nothing — exactly the failure
+    // class /ready exists to expose while /health stays green (oss#316).
+    const res = await fetch(`${base()}/ready`);
+    expect(res.status).toBe(503);
+    const body = (await res.json()) as { status: string; reason?: string };
+    expect(body.status).toBe("unready");
+    expect(body.reason).toContain("backend health check failed");
+  });
+
   it("serves RFC 9728 protected resource metadata", async () => {
     const res = await fetch(`${base()}/.well-known/oauth-protected-resource`);
     expect(res.status).toBe(200);
@@ -95,7 +120,7 @@ describe("HTTP transport hardening + OAuth discovery", () => {
     expect(res.headers.get("access-control-allow-methods")).toContain("GET");
   });
 
-  it("challenges token-less requests with WWW-Authenticate", async () => {
+  it("challenges token-less requests with WWW-Authenticate and a JSON-RPC body", async () => {
     const res = await fetch(`${base()}/`, { method: "POST", body: "{}" });
     expect(res.status).toBe(401);
     const challenge = res.headers.get("www-authenticate") ?? "";
@@ -104,6 +129,9 @@ describe("HTTP transport hardening + OAuth discovery", () => {
       'resource_metadata="https://mcp.stigmer.ai/.well-known/oauth-protected-resource"',
     );
     expect(challenge).toContain('scope="read write"');
+    const error = await expectJsonRpcError(res);
+    expect(error.code).toBe(-32000);
+    expect(error.message).toContain("missing or malformed Authorization");
   });
 
   it("rejects a malformed Authorization header as token-less", async () => {
@@ -115,16 +143,22 @@ describe("HTTP transport hardening + OAuth discovery", () => {
     });
     expect(res.status).toBe(401);
     expect(res.headers.get("www-authenticate") ?? "").toContain('realm="stigmer"');
+    await expectJsonRpcError(res);
   });
 
-  it("returns 404 for an unknown MCP session even with a valid token", async () => {
+  it("returns the SDK's session-not-found shape (404, code -32001) for an unknown session", async () => {
+    // -32001 on a 404 is the streamable-HTTP recovery signal: on it a
+    // conformant client MUST open a new session with a fresh initialize —
+    // how clients survive the bridge's in-memory sessions dying on restart.
     const res = await fetch(`${base()}/`, {
       method: "POST",
       headers: { authorization: "Bearer test-token", "mcp-session-id": "does-not-exist" },
       body: "{}",
     });
     expect(res.status).toBe(404);
-    expect(await res.text()).toContain("unknown or expired MCP session");
+    const error = await expectJsonRpcError(res);
+    expect(error.code).toBe(-32001);
+    expect(error.message).toContain("unknown or expired MCP session");
   });
 
   it("rejects a sessionless non-initialize POST", async () => {
@@ -134,7 +168,9 @@ describe("HTTP transport hardening + OAuth discovery", () => {
       body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/list" }),
     });
     expect(res.status).toBe(400);
-    expect(await res.text()).toContain("an initialize request is required");
+    const error = await expectJsonRpcError(res);
+    expect(error.code).toBe(-32000);
+    expect(error.message).toContain("an initialize request is required");
   });
 
   it("rejects a sessionless GET (no Mcp-Session-Id)", async () => {
@@ -143,7 +179,9 @@ describe("HTTP transport hardening + OAuth discovery", () => {
       headers: { authorization: "Bearer test-token" },
     });
     expect(res.status).toBe(400);
-    expect(await res.text()).toContain("missing Mcp-Session-Id header");
+    const error = await expectJsonRpcError(res);
+    expect(error.code).toBe(-32000);
+    expect(error.message).toContain("Mcp-Session-Id header is required");
   });
 });
 
@@ -189,6 +227,8 @@ describe("HTTP route dispatch (the closed route table)", () => {
     // except the send tool its attachment existed for.
     const res = await initialize("/no-such-roster");
     expect(res.status).toBe(404);
-    expect(await res.text()).toContain("unknown MCP route: /no-such-roster");
+    const error = await expectJsonRpcError(res);
+    expect(error.code).toBe(-32000);
+    expect(error.message).toContain("unknown MCP route: /no-such-roster");
   });
 });

package/src/readiness.test.ts

@@ -0,0 +1,90 @@
+// Unit tests for the cached readiness check (oss#316). The backend RPC is
+// injected, so caching, in-flight dedupe, and verdict propagation are pinned
+// without a live gRPC server; the /ready route's wiring (including the real
+// checkBackendHealth against a dead backend) is covered by
+// http.integration.test.ts.
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  createReadinessCheck,
+  READINESS_CACHE_TTL_MS,
+  type ReadinessResult,
+} from "./readiness";
+
+const READY: ReadinessResult = { ready: true };
+const UNREADY: ReadinessResult = { ready: false, reason: "backend health status: NOT_SERVING" };
+
+beforeEach(() => {
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe("createReadinessCheck", () => {
+  it("propagates the ready verdict", async () => {
+    const check = createReadinessCheck("addr", async () => READY);
+    await expect(check()).resolves.toEqual({ ready: true });
+  });
+
+  it("propagates the unready verdict with its reason", async () => {
+    const check = createReadinessCheck("addr", async () => UNREADY);
+    await expect(check()).resolves.toEqual(UNREADY);
+  });
+
+  it("serves cached verdicts within the TTL without re-dialing", async () => {
+    const probe = vi.fn(async () => READY);
+    const check = createReadinessCheck("addr", probe);
+    await check();
+    vi.advanceTimersByTime(READINESS_CACHE_TTL_MS - 1);
+    await check();
+    expect(probe).toHaveBeenCalledTimes(1);
+  });
+
+  it("re-checks after the TTL expires", async () => {
+    const probe = vi.fn(async () => READY);
+    const check = createReadinessCheck("addr", probe);
+    await check();
+    vi.advanceTimersByTime(READINESS_CACHE_TTL_MS + 1);
+    await check();
+    expect(probe).toHaveBeenCalledTimes(2);
+  });
+
+  it("recovers: an unready verdict is replaced by a ready one after the TTL", async () => {
+    const probe = vi
+      .fn<() => Promise<ReadinessResult>>()
+      .mockResolvedValueOnce(UNREADY)
+      .mockResolvedValueOnce(READY);
+    const check = createReadinessCheck("addr", probe);
+    await expect(check()).resolves.toEqual(UNREADY);
+    vi.advanceTimersByTime(READINESS_CACHE_TTL_MS + 1);
+    await expect(check()).resolves.toEqual({ ready: true });
+  });
+
+  it("shares one in-flight RPC across concurrent callers", async () => {
+    let resolveProbe!: (r: ReadinessResult) => void;
+    const probe = vi.fn(
+      () => new Promise<ReadinessResult>((resolve) => (resolveProbe = resolve)),
+    );
+    const check = createReadinessCheck("addr", probe);
+
+    const first = check();
+    const second = check();
+    resolveProbe(READY);
+
+    await expect(first).resolves.toEqual({ ready: true });
+    await expect(second).resolves.toEqual({ ready: true });
+    expect(probe).toHaveBeenCalledTimes(1);
+  });
+
+  it("passes the configured backend address to the probe", async () => {
+    const probe = vi.fn(async (addr: string) => {
+      expect(addr).toBe("backend:50051");
+      return READY;
+    });
+    await createReadinessCheck("backend:50051", probe)();
+    expect(probe).toHaveBeenCalledWith("backend:50051");
+  });
+});

package/src/readiness.ts

@@ -0,0 +1,94 @@
+// Backend-hop readiness probe (stigmer/stigmer#316).
+//
+// /health reports process liveness only, which left a total backend-hop
+// failure invisible: the bridge once spoke gRPC-web to a backend that only
+// accepts native gRPC, every tool call failed for weeks, and all three
+// Kubernetes probes stayed green. Readiness must therefore exercise the
+// actual hop — transport, content-type, listener — with one cheap RPC.
+//
+// The probe RPC is grpc.health.v1.Health/Check: the one backend call both
+// editions serve credential-free by design (the Go server sets it SERVING
+// before its network listener opens; the cloud Java interceptors exempt
+// "grpc.health.v1.Health" by name — "probes and tooling carry no bearer").
+// The hosted bridge holds no startup credential (per-request Bearer
+// passthrough only), so an authenticated probe is not an option.
+//
+// Only the READINESS probe should point here. Liveness and startup must stay
+// on /health: readiness failure drains traffic (correct for a backend
+// outage), while liveness/startup failures restart the pod — a restart loop
+// that cannot fix a broken backend and destroys every live MCP session.
+
+import { createClient } from "@connectrpc/connect";
+import { Health, HealthCheckResponse_ServingStatus } from "@stigmer/protos/grpc/health/v1/health_pb";
+import { transportForToken } from "./domains/client.js";
+
+/**
+ * Per-check RPC bound. Deliberately below the probe's HTTP timeout in the
+ * deployment overlay (5 s) so a hung backend yields a clean 503 with a
+ * reason, never a probe-level timeout that hides it.
+ */
+export const READINESS_RPC_TIMEOUT_MS = 4_000;
+
+/**
+ * How long a verdict is served without re-dialing the backend. Bounds probe
+ * (and operator curl) traffic to at most one backend RPC per window without
+ * meaningfully delaying either transition: at the overlay's 10 s readiness
+ * period, every scheduled probe still lands on a fresh check.
+ */
+export const READINESS_CACHE_TTL_MS = 5_000;
+
+export interface ReadinessResult {
+  ready: boolean;
+  /** Human-readable cause when not ready; surfaced in the 503 body. */
+  reason?: string;
+}
+
+/** Checks the backend hop once; see {@link createReadinessCheck} for caching. */
+export async function checkBackendHealth(serverAddress: string): Promise<ReadinessResult> {
+  const client = createClient(Health, transportForToken(serverAddress, ""));
+  try {
+    const res = await client.check({}, { timeoutMs: READINESS_RPC_TIMEOUT_MS });
+    if (res.status === HealthCheckResponse_ServingStatus.SERVING) {
+      return { ready: true };
+    }
+    return {
+      ready: false,
+      reason: `backend health status: ${HealthCheckResponse_ServingStatus[res.status] ?? res.status}`,
+    };
+  } catch (err) {
+    return {
+      ready: false,
+      reason: `backend health check failed: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
+/**
+ * Build the cached readiness check used by the /ready route: verdicts are
+ * reused for {@link READINESS_CACHE_TTL_MS} and concurrent callers share one
+ * in-flight RPC, so probe pressure can never amplify into backend pressure.
+ */
+export function createReadinessCheck(
+  serverAddress: string,
+  check: (addr: string) => Promise<ReadinessResult> = checkBackendHealth,
+): () => Promise<ReadinessResult> {
+  let cached: { result: ReadinessResult; at: number } | undefined;
+  let inFlight: Promise<ReadinessResult> | undefined;
+
+  return async () => {
+    if (cached !== undefined && Date.now() - cached.at < READINESS_CACHE_TTL_MS) {
+      return cached.result;
+    }
+    if (inFlight === undefined) {
+      inFlight = check(serverAddress)
+        .then((result) => {
+          cached = { result, at: Date.now() };
+          return result;
+        })
+        .finally(() => {
+          inFlight = undefined;
+        });
+    }
+    return inFlight;
+  };
+}