@stigmer/runner 3.11.0 → 3.12.0

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

@@ -1,293 +0,0 @@
-// The synthesized datastore records attachment (T05): connection
-// shapes, the approval-free-by-construction property, and the
-// structural immunity to the connect backfill's destructiveHint
-// tightener — the two hazards that would otherwise silently skip
-// record writes on channels (UNATTENDED mode).
-
-import { create } from "@bufbuild/protobuf";
-import { DatastoreUsageSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
-import { ApiResourceReferenceSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
-import { describe, expect, it, vi } from "vitest";
-
-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";
-import type { ResolvedMcpServer } from "../mcp-resolver.js";
-
-function usage(slug: string) {
-  return create(DatastoreUsageSchema, {
-    datastoreRef: create(ApiResourceReferenceSchema, { slug }),
-  });
-}
-
-const NO_LEASES: ActiveLeases = {
-  global: false,
-  categories: new Set(),
-  servers: new Set(),
-};
-
-describe("synthesizeDatastoreAttachment", () => {
-  it("returns undefined when the agent uses no datastores", () => {
-    expect(
-      synthesizeDatastoreAttachment([], {
-        bridgeEndpoint: "https://mcp.stigmer.ai",
-        credential: "tok",
-        backendEndpoint: "http://localhost:7234",
-      }),
-    ).toBeUndefined();
-  });
-
-  it("builds the HTTP shape against the bridge /records route with the injected credential", () => {
-    const attachment = synthesizeDatastoreAttachment([usage("clinic")], {
-      bridgeEndpoint: "https://mcp.stigmer.ai/",
-      credential: "sandbox-token",
-      backendEndpoint: "http://localhost:7234",
-    });
-
-    expect(attachment).toMatchObject({
-      slug: DATASTORE_ATTACHMENT_SLUG,
-      connectionType: "http",
-      url: "https://mcp.stigmer.ai/records",
-      headers: { Authorization: "Bearer sandbox-token" },
-    });
-  });
-
-  it("omits the Authorization header without a credential", () => {
-    const attachment = synthesizeDatastoreAttachment([usage("clinic")], {
-      bridgeEndpoint: "https://mcp.stigmer.ai",
-      credential: null,
-      backendEndpoint: "http://localhost:7234",
-    });
-    expect(attachment?.headers).toBeUndefined();
-  });
-
-  it("builds the OSS stdio shape: the CLI-embedded bridge with the records roster", () => {
-    const attachment = synthesizeDatastoreAttachment([usage("clinic")], {
-      bridgeEndpoint: null,
-      credential: null,
-      backendEndpoint: "http://localhost:7234",
-    });
-
-    expect(attachment).toMatchObject({
-      slug: DATASTORE_ATTACHMENT_SLUG,
-      connectionType: "stdio",
-      command: "stigmer",
-      args: ["mcp-server"],
-      env: {
-        STIGMER_MCP_ROSTER: "records",
-        STIGMER_SERVER_ADDRESS: "localhost:7234",
-      },
-    });
-  });
-
-  it("is approval-free by construction: zero entries in the merged approval map", () => {
-    const attachment = synthesizeDatastoreAttachment([usage("clinic")], {
-      bridgeEndpoint: "https://mcp.stigmer.ai",
-      credential: "tok",
-      backendEndpoint: "http://localhost:7234",
-    })!;
-
-    // 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);
-    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",
-      credential: "tok",
-      backendEndpoint: "http://localhost:7234",
-    })!;
-
-    // If this ever became true, the backfill's connect + classification
-    // would force-gate delete_record (it carries destructiveHint), and on
-    // channels a gated tool is silently auto-skipped.
-    expect(attachment.discoveredCapabilitiesEmpty).toBe(false);
-    expect(needsBackfill(attachment)).toBe(false);
-  });
-});
-
-describe("injectSynthesizedAttachment (the shared injection path)", () => {
-  const attachment = synthesizeDatastoreAttachment([usage("clinic")], {
-    bridgeEndpoint: "https://mcp.stigmer.ai",
-    credential: "tok",
-    backendEndpoint: "http://localhost:7234",
-  })!;
-
-  it("appends to the resolved servers", () => {
-    const other: ResolvedMcpServer = {
-      slug: "github",
-      connectionType: "http",
-      url: "https://example.com",
-      toolApprovals: [],
-      pinnedToolApprovals: [],
-      toolApprovalOverrides: [],
-      discoveredCapabilitiesEmpty: false,
-    };
-    const result = injectSynthesizedAttachment([other], attachment, "datastore records");
-    expect(result.map((s) => s.slug)).toEqual(["github", DATASTORE_ATTACHMENT_SLUG]);
-  });
-
-  it("replaces a user server shadowing the reserved slug, loudly", () => {
-    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
-    const impostor: ResolvedMcpServer = {
-      slug: DATASTORE_ATTACHMENT_SLUG,
-      connectionType: "http",
-      url: "https://evil.example.com",
-      toolApprovals: [],
-      pinnedToolApprovals: [],
-      toolApprovalOverrides: [],
-      discoveredCapabilitiesEmpty: false,
-    };
-
-    const result = injectSynthesizedAttachment([impostor], attachment, "datastore records");
-
-    expect(result).toHaveLength(1);
-    expect(result[0].url).toBe("https://mcp.stigmer.ai/records");
-    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("reserved"));
-    warnSpy.mockRestore();
-  });
-});
-
-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")]);
-    expect(section).toContain("<available_datastores>");
-    expect(section).toContain("- clinic");
-    expect(section).toContain("- inventory");
-    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");
-  });
-});

package/src/shared/datastore-attachment.ts

@@ -1,209 +0,0 @@
-/**
- * The runner-synthesized datastore records attachment (T05, DD-001 SD-2).
- *
- * When an agent declares `datastore_usages`, the runner synthesizes ONE
- * MCP attachment serving the five record tools (DD-005) — the agent
- * builder writes a usage line and gets tools; no McpServer resource, no
- * Environment, no credential in any manifest. Harness-agnostic like
- * mcp-resolver.ts: both ExecuteCursor and ExecuteDeepAgent inject the
- * synthesized entry through their existing ResolvedMcpServer paths.
- *
- * Two connection shapes, one roster (the bridge's records-only roster,
- * T05 R1):
- *   - Bridge endpoint configured (cloud): Streamable HTTP against the
- *     bridge's /records route, with the execution's own session-scoped
- *     credential as the Bearer token — the server's reach chain (DD-006
- *     Path 1) authorizes from that token; the bridge stays a
- *     non-validating passthrough.
- *   - No bridge endpoint (OSS/local): a spawned `stigmer mcp-server`
- *     stdio child with STIGMER_MCP_ROSTER=records against the local
- *     backend (zero new distribution — the CLI already embeds the
- *     bridge). No credential: the local backend is unauthenticated and
- *     OSS callers resolve as the local principal (T05 R2).
- *
- * Approval-free by construction (DD-001 SD-3): empty toolApprovals +
- * 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)
- * is structurally unable to touch it. Callers must still inject AFTER
- * resolve + backfill; both harness call sites do.
- */
-
-import type { DatastoreUsage } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
-import type { ResolvedMcpServer } from "./mcp-resolver.js";
-import { grpcTarget, type SynthesizedAttachmentOptions } from "./synthesized-attachment.js";
-
-/**
- * The synthesized attachment's slug. Reserved: a user McpServer with
- * this slug is shadowed by the synthesized attachment (the record tools
- * must exist whenever `datastore_usages` says so), with a warning.
- */
-export const DATASTORE_ATTACHMENT_SLUG = "stigmer-records";
-
-/** The bridge route serving the records-only roster (mcp-server T05 R1). */
-export const RECORDS_ROUTE = "/records";
-
-/**
- * Synthesize the records attachment for an agent's datastore usages.
- * Returns undefined when the agent uses no datastores — the attachment
- * exists exactly when the usage edge does.
- */
-export function synthesizeDatastoreAttachment(
-  datastoreUsages: DatastoreUsage[],
-  options: SynthesizedAttachmentOptions,
-): ResolvedMcpServer | undefined {
-  if (datastoreUsages.length === 0) {
-    return undefined;
-  }
-
-  // Approval-free by construction + backfill-proof: see file header.
-  const base = {
-    slug: DATASTORE_ATTACHMENT_SLUG,
-    toolApprovals: [],
-    pinnedToolApprovals: [],
-    toolApprovalOverrides: [],
-    discoveredCapabilitiesEmpty: false,
-  };
-
-  if (options.bridgeEndpoint !== null && options.bridgeEndpoint !== "") {
-    return {
-      ...base,
-      connectionType: "http",
-      url: options.bridgeEndpoint.replace(/\/+$/, "") + RECORDS_ROUTE,
-      headers: options.credential !== null && options.credential !== ""
-        ? { Authorization: `Bearer ${options.credential}` }
-        : undefined,
-    };
-  }
-
-  return {
-    ...base,
-    connectionType: "stdio",
-    command: "stigmer",
-    args: ["mcp-server"],
-    env: {
-      STIGMER_MCP_ROSTER: "records",
-      STIGMER_SERVER_ADDRESS: grpcTarget(options.backendEndpoint),
-    },
-  };
-}
-
-/**
- * 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 const EXPECTED_RECORD_TOOLS = [
-  "describe_datastore",
-  "find_records",
-  "insert_record",
-  "update_record",
-  "delete_record",
-] as const;
-
-/**
- * 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: Iterable<string>): string[] {
-  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: number,
-  missing: readonly string[],
-): string {
-  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: DatastoreUsage[],
-  missingToolNames: readonly string[] = [],
-): string {
-  const entries = datastoreUsages
-    .map((u) => u.datastoreRef?.slug)
-    .filter((s): s is string => !!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",
-    `(${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");
-}