@stigmer/runner 3.9.0 → 3.11.0

package/src/shared/__tests__/bedrock-seam.test.ts

@@ -0,0 +1,390 @@
+/**
+ * Characterization test for the ChatAnthropic `createClient` ->
+ * AnthropicBedrock seam — the integration the T04 bedrock backend adapter
+ * is built on. Sibling of vertex-seam.test.ts; same rules: this pins REAL
+ * cross-package behavior (`@langchain/anthropic` bundling @anthropic-ai/sdk
+ * 0.95.x driving `@anthropic-ai/bedrock-sdk` bundling its own nested
+ * >=0.115 copy), so a future bump of either side fails here in CI instead
+ * of in production. See scripts/check-langchain-deps.sh for why the two
+ * @anthropic-ai/sdk versions coexist and when they collapse to one.
+ *
+ * Determinism: zero live credentials, zero network. SigV4 signing runs for
+ * real — it is pure HMAC over static test keys passed through the SDK's
+ * own `awsAccessKey`/`awsSecretKey` options (the AWS credential provider
+ * chain is bypassed entirely, so no IMDS/config-file probing) — and
+ * transport is a recording `fetch` injected through the SDK's `fetch`
+ * option. Streaming fixtures are binary AWS EventStream frames built with
+ * the SDK's OWN exported marshaller (getMinimalSerdeContext), so the
+ * EventStream -> SSE normalization path that every real Bedrock stream
+ * takes is exercised, not bypassed.
+ */
+
+import { describe, it, expect } from "vitest";
+import { ChatAnthropic } from "@langchain/anthropic";
+import { AnthropicBedrock } from "@anthropic-ai/bedrock-sdk";
+import { getMinimalSerdeContext } from "@anthropic-ai/bedrock-sdk/core/streaming";
+import { HumanMessage, AIMessage, AIMessageChunk } from "@langchain/core/messages";
+
+// ─── Fixtures ────────────────────────────────────────────────────────────────
+
+/**
+ * Bedrock's id form for a dated pre-4.6 Claude: `anthropic.` vendor prefix
+ * and `-v1:0` version suffix (see llm-backend.ts translation, T04).
+ */
+const BEDROCK_MODEL_ID = "anthropic.claude-sonnet-4-5-20250929-v1:0";
+const REGION = "asia-south1";
+const ACCESS_KEY = "AKIA-SEAM-TEST";
+const SECRET_KEY = "seam-test-secret";
+
+const WEATHER_TOOL = {
+  name: "get_weather",
+  description: "Get the current weather for a city.",
+  input_schema: {
+    type: "object" as const,
+    properties: { city: { type: "string" } },
+    required: ["city"],
+  },
+};
+
+/** Non-streaming (`/invoke`) response: text + tool_use + usage. */
+const MESSAGE_RESPONSE = {
+  id: "msg_bedrock_test_01",
+  type: "message",
+  role: "assistant",
+  model: BEDROCK_MODEL_ID,
+  content: [
+    { type: "text", text: "I'll check the weather." },
+    { type: "tool_use", id: "toolu_test_01", name: "get_weather", input: { city: "Chennai" } },
+  ],
+  stop_reason: "tool_use",
+  stop_sequence: null,
+  usage: { input_tokens: 25, output_tokens: 17 },
+};
+
+/**
+ * Streaming (`/invoke-with-response-stream`) events in Anthropic's grammar.
+ * On the Bedrock wire each rides base64-encoded inside a binary EventStream
+ * `chunk` frame; the SDK's eventStreamToSSEResponse turns them back into
+ * the SSE the nested @anthropic-ai/sdk parses.
+ */
+const STREAM_EVENTS: ReadonlyArray<Record<string, unknown>> = [
+  {
+    type: "message_start",
+    message: {
+      id: "msg_bedrock_test_02", type: "message", role: "assistant",
+      model: BEDROCK_MODEL_ID, content: [], stop_reason: null, stop_sequence: null,
+      usage: { input_tokens: 25, output_tokens: 1 },
+    },
+  },
+  { type: "content_block_start", index: 0, content_block: { type: "text", text: "" } },
+  { type: "content_block_delta", index: 0, delta: { type: "text_delta", text: "I'll check the weather." } },
+  { type: "content_block_stop", index: 0 },
+  { type: "content_block_start", index: 1, content_block: { type: "tool_use", id: "toolu_test_02", name: "get_weather", input: {} } },
+  { type: "content_block_delta", index: 1, delta: { type: "input_json_delta", partial_json: '{"city":"Chennai"}' } },
+  { type: "content_block_stop", index: 1 },
+  { type: "message_delta", delta: { stop_reason: "tool_use", stop_sequence: null }, usage: { output_tokens: 17 } },
+  { type: "message_stop" },
+];
+
+/**
+ * Serialize Anthropic events into Bedrock's binary EventStream framing
+ * using the SDK's own marshaller — the same codec its deserializer runs —
+ * so the fixture is wire-faithful by construction, not by hand-rolling.
+ */
+async function binaryEventStreamBody(
+  events: ReadonlyArray<Record<string, unknown>>,
+): Promise<Buffer> {
+  const { eventStreamMarshaller } = getMinimalSerdeContext();
+  async function* input(): AsyncGenerator<Record<string, unknown>> {
+    yield* events;
+  }
+  const serialized = eventStreamMarshaller.serialize(input(), (event) => ({
+    headers: {
+      ":event-type": { type: "string", value: "chunk" },
+      ":message-type": { type: "string", value: "event" },
+      ":content-type": { type: "string", value: "application/json" },
+    },
+    body: new TextEncoder().encode(
+      JSON.stringify({ bytes: Buffer.from(JSON.stringify(event)).toString("base64") }),
+    ),
+  }));
+  const chunks: Buffer[] = [];
+  for await (const chunk of serialized) {
+    chunks.push(Buffer.from(chunk as Uint8Array));
+  }
+  return Buffer.concat(chunks);
+}
+
+// ─── Harness ─────────────────────────────────────────────────────────────────
+
+interface RecordedRequest {
+  url: string;
+  method: string;
+  headers: Record<string, string>;
+  body: Record<string, unknown>;
+}
+
+interface SeamHarness {
+  model: ChatAnthropic;
+  requests: RecordedRequest[];
+  /** Options ChatAnthropic passed to the createClient factory. */
+  factoryOptions: Array<{ maxRetries?: number }>;
+  /** The AnthropicBedrock instances the factory constructed. */
+  clients: AnthropicBedrock[];
+}
+
+/**
+ * Build a real ChatAnthropic wired to a real AnthropicBedrock through the
+ * `createClient` seam, with transport replaced by a recording fetch.
+ *
+ * The factory honors `maxRetries` from the incoming options: LangChain owns
+ * retrying (its AsyncCaller wraps every request) and passes `maxRetries: 0`
+ * so the underlying SDK must not retry underneath it — same contract the
+ * vertex seam pins, preserved by the T04 adapter.
+ */
+function buildSeamHarness(streamBody?: Buffer): SeamHarness {
+  const requests: RecordedRequest[] = [];
+  const factoryOptions: SeamHarness["factoryOptions"] = [];
+  const clients: AnthropicBedrock[] = [];
+
+  const recordingFetch: typeof fetch = async (input, init) => {
+    const headers: Record<string, string> = {};
+    new Headers(init?.headers).forEach((value, key) => {
+      headers[key] = value;
+    });
+    requests.push({
+      url: String(input),
+      method: init?.method ?? "GET",
+      headers,
+      body: JSON.parse(String(init?.body)) as Record<string, unknown>,
+    });
+    const streaming = String(input).includes("invoke-with-response-stream");
+    return streaming
+      ? new Response(streamBody, {
+          status: 200,
+          // The real Bedrock wire content type — adaptResponse matches it
+          // positively and transcodes the binary frames back to SSE.
+          headers: { "Content-Type": "application/vnd.amazon.eventstream" },
+        })
+      : new Response(JSON.stringify(MESSAGE_RESPONSE), {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        });
+  };
+
+  const model = new ChatAnthropic({
+    model: BEDROCK_MODEL_ID,
+    temperature: 0,
+    maxTokens: 1024,
+    createClient: (options) => {
+      factoryOptions.push({ maxRetries: options.maxRetries });
+      const client = new AnthropicBedrock({
+        awsRegion: REGION,
+        awsAccessKey: ACCESS_KEY,
+        awsSecretKey: SECRET_KEY,
+        fetch: recordingFetch,
+        maxRetries: options.maxRetries,
+      });
+      clients.push(client);
+      return client;
+    },
+  });
+
+  return { model, requests, factoryOptions, clients };
+}
+
+/**
+ * Bedrock moves the model id into the URL path. Pinned: the installed
+ * 0.32.x interpolates it UNENCODED — the `-v1:0` colon stays literal in
+ * the path (newer SDK source URI-encodes via its `path` template helper;
+ * if an upgrade flips this to `%3A`, AWS accepts both, but this pin makes
+ * the change visible instead of silent).
+ */
+const expectedUrl = (specifier: "invoke" | "invoke-with-response-stream") =>
+  `https://bedrock-runtime.${REGION}.amazonaws.com/model/` +
+  `${BEDROCK_MODEL_ID}/${specifier}`;
+
+// ─── Tests ───────────────────────────────────────────────────────────────────
+
+describe("ChatAnthropic createClient -> AnthropicBedrock seam", () => {
+  it("constructs without an Anthropic API key when createClient is provided", () => {
+    // chat_models.js waives the "Anthropic API key not found" check for
+    // factory-constructed clients — the waiver the bedrock backend depends on.
+    expect(() => buildSeamHarness()).not.toThrow();
+  });
+
+  it("defaults awsRegion to us-east-1 when AWS_REGION is unset (why preflight requires it)", () => {
+    // Pinned deliberately: the SDK will happily route traffic to us-east-1
+    // on a missing region. For a deployment-controlled data-residency
+    // feature that silent cross-region default is unacceptable, so
+    // checkBedrockPrerequisites (llm-backend.ts) refuses to start without
+    // an explicit AWS_REGION. If the SDK ever drops the default, this test
+    // tells us the preflight rationale needs rewording.
+    const saved = process.env.AWS_REGION;
+    delete process.env.AWS_REGION;
+    try {
+      const client = new AnthropicBedrock({
+        awsAccessKey: ACCESS_KEY,
+        awsSecretKey: SECRET_KEY,
+      });
+      expect(client.awsRegion).toBe("us-east-1");
+    } finally {
+      if (saved !== undefined) process.env.AWS_REGION = saved;
+    }
+  });
+
+  it("shapes a non-streaming request into Bedrock wire form (/invoke) and SigV4-signs it", async () => {
+    const h = buildSeamHarness();
+
+    const result = await h.model.invoke([new HumanMessage("Weather in Chennai?")]);
+
+    expect(h.requests).toHaveLength(1);
+    const req = h.requests[0];
+
+    // Model id rides in the URL path (URI-encoded), never in the body;
+    // stream flag is likewise URL routing, not body content.
+    expect(req.url).toBe(expectedUrl("invoke"));
+    expect(req.method).toBe("POST");
+    expect(req.body).not.toHaveProperty("model");
+    expect(req.body).not.toHaveProperty("stream");
+    expect(req.body.anthropic_version).toBe("bedrock-2023-05-31");
+    expect(req.body.max_tokens).toBe(1024);
+
+    // SigV4 signature over the adapted request reached the wire, scoped to
+    // the region and the bedrock service — the signature must cover the
+    // FINAL (middleware-adapted) request or AWS rejects it.
+    expect(req.headers.authorization).toMatch(/^AWS4-HMAC-SHA256 /);
+    expect(req.headers.authorization).toContain(`/${REGION}/bedrock/aws4_request`);
+    expect(req.headers["x-amz-date"]).toMatch(/^\d{8}T\d{6}Z$/);
+
+    expect(result).toBeInstanceOf(AIMessage);
+  });
+
+  it("round-trips tool definitions and tool_use blocks into tool_calls", async () => {
+    const h = buildSeamHarness();
+    const withTools = h.model.bindTools([WEATHER_TOOL]);
+
+    const result = (await withTools.invoke([
+      new HumanMessage("Weather in Chennai?"),
+    ])) as AIMessage;
+
+    // Tool definition survived request shaping through the Bedrock adapter.
+    const tools = h.requests[0].body.tools as Array<{ name: string }>;
+    expect(tools).toHaveLength(1);
+    expect(tools[0].name).toBe("get_weather");
+
+    // The tool_use response block became a LangChain tool_call with its id —
+    // the identity the HITL approval flow keys on.
+    expect(result.tool_calls).toHaveLength(1);
+    expect(result.tool_calls?.[0]).toMatchObject({
+      id: "toolu_test_01",
+      name: "get_weather",
+      args: { city: "Chennai" },
+    });
+  });
+
+  it("reports usage_metadata on non-streaming responses (what billing reads)", async () => {
+    const h = buildSeamHarness();
+
+    const result = (await h.model.invoke([
+      new HumanMessage("Weather in Chennai?"),
+    ])) as AIMessage;
+
+    expect(result.usage_metadata).toMatchObject({
+      input_tokens: 25,
+      output_tokens: 17,
+      total_tokens: 42,
+    });
+  });
+
+  it("streams via /invoke-with-response-stream, transcoding EventStream frames to tool_calls and usage", async () => {
+    const h = buildSeamHarness(await binaryEventStreamBody(STREAM_EVENTS));
+
+    let final: AIMessageChunk | undefined;
+    for await (const chunk of await h.model.stream([
+      new HumanMessage("Weather in Chennai?"),
+    ])) {
+      final = final === undefined ? chunk : final.concat(chunk);
+    }
+
+    expect(h.requests).toHaveLength(1);
+    expect(h.requests[0].url).toBe(expectedUrl("invoke-with-response-stream"));
+    expect(h.requests[0].body).not.toHaveProperty("stream");
+    expect(h.requests[0].body).not.toHaveProperty("model");
+
+    expect(final).toBeDefined();
+    expect(final?.text).toBe("I'll check the weather.");
+    expect(final?.tool_calls).toHaveLength(1);
+    expect(final?.tool_calls?.[0]).toMatchObject({
+      id: "toolu_test_02",
+      name: "get_weather",
+      args: { city: "Chennai" },
+    });
+
+    // input from message_start; output accumulated across message events.
+    // Pinned to the observed accumulation (same math the vertex seam pins)
+    // so a LangChain bump that changes usage accounting fails here first.
+    expect(final?.usage_metadata).toMatchObject({
+      input_tokens: 25,
+      output_tokens: 18,
+    });
+  });
+
+  it("passes maxRetries: 0 to the factory and the honored value reaches the client", async () => {
+    const h = buildSeamHarness(await binaryEventStreamBody(STREAM_EVENTS));
+
+    await h.model.invoke([new HumanMessage("hi")]);
+    for await (const chunk of await h.model.stream([new HumanMessage("hi")])) {
+      void chunk;
+    }
+
+    // LangChain owns retrying: it must hand the factory maxRetries: 0, once
+    // per cached client (batch + streaming are constructed independently).
+    expect(h.factoryOptions).toHaveLength(2);
+    expect(h.factoryOptions.every((o) => o.maxRetries === 0)).toBe(true);
+    expect(h.clients).toHaveLength(2);
+    expect(h.clients.every((c) => c.maxRetries === 0)).toBe(true);
+  });
+
+  it("cannot serve countTokens: the request is never adapted to a Bedrock route", async () => {
+    // Bedrock supports neither token counting nor prompt caching — a
+    // documented limitation of the bedrock backend (operator doc,
+    // docs/guides/runners/model-backends.mdx). The installed 0.32.x still
+    // EXPOSES messages.countTokens (newer SDK source deletes the resource
+    // at construction), but its request bypasses the /model/… rewrite —
+    // MODEL_ENDPOINTS covers only /v1/complete and /v1/messages — so it
+    // targets a path that does not exist on the Bedrock runtime and can
+    // never succeed against AWS. Pinned so an SDK upgrade that either
+    // deletes the method or starts adapting it surfaces here, prompting a
+    // docs review instead of silent drift.
+    const requests: string[] = [];
+    const notFoundFetch: typeof fetch = async (input) => {
+      requests.push(String(input));
+      return new Response("{}", { status: 404 });
+    };
+    const client = new AnthropicBedrock({
+      awsRegion: REGION,
+      awsAccessKey: ACCESS_KEY,
+      awsSecretKey: SECRET_KEY,
+      fetch: notFoundFetch,
+      maxRetries: 0,
+    });
+
+    // 0.32.x quirk: the TYPES already omit countTokens while the RUNTIME
+    // still exposes it — the cast reaches the runtime truth this test pins.
+    const messages = client.messages as unknown as {
+      countTokens: (req: Record<string, unknown>) => Promise<unknown>;
+    };
+    await expect(
+      messages.countTokens({
+        model: BEDROCK_MODEL_ID,
+        messages: [{ role: "user", content: "hi" }],
+      }),
+    ).rejects.toThrow();
+    expect(requests).toHaveLength(1);
+    // Anthropic-shaped path on the Bedrock host — not a /model/… route.
+    expect(requests[0]).toBe(
+      `https://bedrock-runtime.${REGION}.amazonaws.com/v1/messages/count_tokens`,
+    );
+  });
+});

package/src/shared/__tests__/caller-identity.test.ts

@@ -11,6 +11,7 @@ import {
   CALLER_IDENTITY_VALUE_ENV_KEY,
   SESSION_ID_ENV_KEY,
   STIGMER_USER_KIND,
+  SYSTEM_CREATOR_SENTINEL,
   anonymousCallerIdentity,
   injectAnonymousCallerIdentityForDiscovery,
   injectCallerIdentityEnv,
@@ -70,6 +71,30 @@ describe("resolveCallerIdentity precedence", () => {
     });
   });
 
+  it('the "system" audit placeholder is never a caller — falls to anonymous (contract guard)', () => {
+    // The OSS server stamps created_by.id = "system" on every create (no
+    // local auth) and the cloud's AuditActorBuilder falls back to the
+    // same literal — one string shared by ALL such traffic. Presenting it
+    // would let a single MCP binding for "system" grant every one of
+    // those sessions, so it must resolve to the anonymous sentinel.
+    expect(resolveCallerIdentity(undefined, { id: SYSTEM_CREATOR_SENTINEL })).toEqual({
+      kind: ANONYMOUS_KIND,
+      value: "",
+    });
+    expect(resolveCallerIdentity({}, { id: " system ", email: "" })).toEqual({
+      kind: ANONYMOUS_KIND,
+      value: "",
+    });
+  });
+
+  it('a real email always wins — an account is never demoted for its id alone', () => {
+    // Email-first ordering: the sentinel check only ever sees creators
+    // that have no email, so a resolvable principal cannot be demoted.
+    expect(
+      resolveCallerIdentity(undefined, { id: SYSTEM_CREATOR_SENTINEL, email: "ops@example.com" }),
+    ).toEqual({ kind: STIGMER_USER_KIND, value: "ops@example.com" });
+  });
+
   it("a half-present channel identity (value without kind) is NOT a channel sender", () => {
     // readSenderIdentity requires value AND kind; a half-stamped session
     // falls through to the creator rather than fabricating a kind.

package/src/shared/__tests__/channel-attachment.test.ts

@@ -169,7 +169,7 @@ describe("synthesizeChannelAttachment", () => {
     // UNATTENDED mode, where a gated tool resolves as skip-and-adapt —
     // a gated send tool means reminders never send.
     const merged = mergeApprovalPolicies(
-      [attachment as ResolvedMcpServer], [], noLeases,
+      [attachment as ResolvedMcpServer], noLeases,
     );
     expect(merged.size).toBe(0);
   });

package/src/shared/__tests__/connect-backfill.test.ts

@@ -14,6 +14,7 @@ function makeServer(overrides: Partial<ResolvedMcpServer> = {}): ResolvedMcpServ
     args: ["-y", "@mcp/test-server"],
     toolApprovals: [],
     pinnedToolApprovals: [],
+    toolApprovalOverrides: [],
     discoveredCapabilitiesEmpty: false,
     ...overrides,
   };

package/src/shared/__tests__/conversation-attachment.test.ts

@@ -126,7 +126,7 @@ describe("synthesizeConversationAttachment", () => {
     // Channel surfaces run APPROVAL_MODE_UNATTENDED, where a gated tool
     // resolves as skip-and-adapt — a gated escalation would never fire
     // (DD-008's approval-free ruling, the DD-001 SD-3 structural bypass).
-    const merged = mergeApprovalPolicies([attachment], [], noLeases);
+    const merged = mergeApprovalPolicies([attachment], noLeases);
     expect(merged.size).toBe(0);
   });
 

package/src/shared/__tests__/datastore-attachment.test.ts

@@ -13,7 +13,10 @@ import { mergeApprovalPolicies, type ActiveLeases } from "../approval-policy.js"
 import { needsBackfill } from "../connect-backfill.js";
 import {
   DATASTORE_ATTACHMENT_SLUG,
+  EXPECTED_RECORD_TOOLS,
+  formatDatastoreDegradationNotice,
   formatDatastoresSection,
+  missingRecordTools,
   synthesizeDatastoreAttachment,
 } from "../datastore-attachment.js";
 import { injectSynthesizedAttachment } from "../synthesized-attachment.js";
@@ -94,10 +97,38 @@ describe("synthesizeDatastoreAttachment", () => {
 
     // Absence from the map means auto-approved for EVERY consumer (the
     // Cursor hook, the deep-agent gate) — DD-001 SD-3's structural bypass.
-    const merged = mergeApprovalPolicies([attachment], [], NO_LEASES);
+    const merged = mergeApprovalPolicies([attachment], NO_LEASES);
     expect(merged.size).toBe(0);
   });
 
+  it("stays approval-free when another server's usage overrides a same-named tool (issue #349)", () => {
+    const attachment = synthesizeDatastoreAttachment([usage("clinic")], {
+      bridgeEndpoint: "https://mcp.stigmer.ai",
+      credential: "tok",
+      backendEndpoint: "http://localhost:7234",
+    })!;
+
+    // Before #349 a flat override list applied inside every server's merge
+    // loop, so this crm override would have force-gated the attachment's
+    // delete_record too — and on channels (UNATTENDED mode) a gated tool
+    // is silently skipped. Overrides now ride their own server, so the
+    // attachment (which has no usage) is immune by construction.
+    const crm: ResolvedMcpServer = {
+      slug: "crm",
+      connectionType: "http",
+      url: "https://crm.example.com/mcp",
+      toolApprovals: [],
+      pinnedToolApprovals: [],
+      toolApprovalOverrides: [
+        { toolName: "delete_record", requiresApproval: true, message: "" } as any,
+      ],
+      discoveredCapabilitiesEmpty: false,
+    };
+    const merged = mergeApprovalPolicies([crm, attachment], NO_LEASES);
+    expect(merged.has("crm/delete_record")).toBe(true);
+    expect(merged.has(`${DATASTORE_ATTACHMENT_SLUG}/delete_record`)).toBe(false);
+  });
+
   it("is structurally immune to the connect backfill (destructiveHint tightener)", () => {
     const attachment = synthesizeDatastoreAttachment([usage("clinic")], {
       bridgeEndpoint: "https://mcp.stigmer.ai",
@@ -127,6 +158,7 @@ describe("injectSynthesizedAttachment (the shared injection path)", () => {
       url: "https://example.com",
       toolApprovals: [],
       pinnedToolApprovals: [],
+      toolApprovalOverrides: [],
       discoveredCapabilitiesEmpty: false,
     };
     const result = injectSynthesizedAttachment([other], attachment, "datastore records");
@@ -141,6 +173,7 @@ describe("injectSynthesizedAttachment (the shared injection path)", () => {
       url: "https://evil.example.com",
       toolApprovals: [],
       pinnedToolApprovals: [],
+      toolApprovalOverrides: [],
       discoveredCapabilitiesEmpty: false,
     };
 
@@ -153,6 +186,45 @@ describe("injectSynthesizedAttachment (the shared injection path)", () => {
   });
 });
 
+describe("EXPECTED_RECORD_TOOLS", () => {
+  it("pins the records-roster contract: exactly the five tools the mcp-server registers", () => {
+    // Drift pin (issue #325): the reconciliation treats ANY of these as
+    // mandatory because mcp-server/src/domains/records/tools.ts registers
+    // all five unconditionally for the agent audience. If a record tool is
+    // ever added, removed, or renamed there, this pin forces the reviewer
+    // to update the roster contract deliberately in both places.
+    expect([...EXPECTED_RECORD_TOOLS]).toEqual([
+      "describe_datastore",
+      "find_records",
+      "insert_record",
+      "update_record",
+      "delete_record",
+    ]);
+  });
+});
+
+describe("missingRecordTools", () => {
+  it("returns empty when all five record tools are connected", () => {
+    expect(missingRecordTools([...EXPECTED_RECORD_TOOLS])).toEqual([]);
+  });
+
+  it("returns every expected tool when the roster is empty", () => {
+    expect(missingRecordTools([])).toEqual([...EXPECTED_RECORD_TOOLS]);
+  });
+
+  it("returns only the absent tools on a partial roster", () => {
+    expect(
+      missingRecordTools(["describe_datastore", "find_records", "insert_record"]),
+    ).toEqual(["update_record", "delete_record"]);
+  });
+
+  it("ignores extraneous tool names", () => {
+    expect(
+      missingRecordTools([...EXPECTED_RECORD_TOOLS, "some_other_tool"]),
+    ).toEqual([]);
+  });
+});
+
 describe("formatDatastoresSection", () => {
   it("names the attached datastores and points at describe_datastore first", () => {
     const section = formatDatastoresSection([usage("clinic"), usage("inventory")]);
@@ -162,4 +234,60 @@ describe("formatDatastoresSection", () => {
     expect(section).toContain("describe_datastore");
     expect(section).toContain("</available_datastores>");
   });
+
+  it("carries the standing failure-disclosure instruction in the healthy section", () => {
+    // The only mechanism covering tools that connected but fail at call
+    // time (the WhatsApp-pilot outage shape), and the Cursor harness's
+    // entire coverage — that harness can never observe the live roster.
+    const section = formatDatastoresSection([usage("clinic")]);
+    expect(section).toContain("the datastore is unreachable");
+    expect(section).toContain("do not answer from memory");
+  });
+
+  it("advertises exactly the expected record tools (no hand-written drift)", () => {
+    const section = formatDatastoresSection([usage("clinic")]);
+    for (const tool of EXPECTED_RECORD_TOOLS) {
+      expect(section).toContain(tool);
+    }
+  });
+
+  it("renders the degraded section instead when record tools are missing", () => {
+    const section = formatDatastoresSection(
+      [usage("clinic")],
+      ["find_records", "insert_record"],
+    );
+    // Must NOT promise tools the agent does not have — the issue's core
+    // complaint (oss#325).
+    expect(section).not.toContain("<available_datastores>");
+    expect(section).toContain("<unavailable_datastores>");
+    expect(section).toContain("find_records, insert_record.");
+    expect(section).toContain("- clinic");
+    expect(section).toContain("cannot be reached right now");
+    expect(section).toContain("Never answer");
+    expect(section).toContain("</unavailable_datastores>");
+  });
+
+  it("renders healthy when the missing list is empty (negative control)", () => {
+    const section = formatDatastoresSection([usage("clinic")], []);
+    expect(section).toContain("<available_datastores>");
+    expect(section).not.toContain("<unavailable_datastores>");
+  });
+});
+
+describe("formatDatastoreDegradationNotice", () => {
+  it("states declared count, connected fraction, and the missing tools", () => {
+    const notice = formatDatastoreDegradationNotice(2, [
+      "update_record",
+      "delete_record",
+    ]);
+    expect(notice).toContain("declared 2 datastore(s)");
+    expect(notice).toContain("3/5 record tools connected");
+    expect(notice).toContain("missing: update_record, delete_record");
+    expect(notice).toContain("instructed to disclose");
+  });
+
+  it("reads 0/5 on a fully absent roster", () => {
+    const notice = formatDatastoreDegradationNotice(1, [...EXPECTED_RECORD_TOOLS]);
+    expect(notice).toContain("0/5 record tools connected");
+  });
 });