@stigmer/runner 3.2.3 → 3.3.0

package/src/activities/execute-cursor/index.ts

@@ -55,7 +55,11 @@ import { DeltaEnricher } from "./delta-enricher.js";
 import { TodoTracker } from "./todo-tracker.js";
 import { StreamingUpdateScheduler, loadStreamingConfig } from "../../shared/streaming-scheduler.js";
 import { createCursorEventRecorder } from "./cursor-event-recorder.js";
-import { resolveMcpServers, validateMcpServerEnv } from "./mcp-resolver.js";
+import { resolveMcpServers, toCursorMcpConfig, validateMcpServerEnv } from "./mcp-resolver.js";
+import {
+  injectDatastoreAttachment,
+  synthesizeDatastoreAttachment,
+} from "../../shared/datastore-attachment.js";
 import { mergeApprovalPolicies } from "./approval-policy.js";
 import { deriveActiveLeases, isUnattendedApprovalMode } from "../../shared/approval-policy.js";
 import { backfillMcpServersIfNeeded } from "./connect-backfill.js";
@@ -583,6 +587,33 @@ async function executeCursorInner(
       client, mcpResolution, blueprint.mergedMcpServerUsages, envVars, sessionOrg,
       heartbeat, secretKeys,
     );
+
+    // Phase 4a2: Synthesize the datastore records attachment (T05).
+    // Deliberately AFTER resolve + backfill: the attachment has no
+    // McpServerUsage and reports discovered capabilities, so the
+    // backfill's destructiveHint tightener can never force-gate
+    // delete_record (which on channels would be silently skipped).
+    // Empty approval maps keep it approval-free by construction.
+    if (blueprint.datastoreUsages.length > 0) {
+      const scopedCredential =
+        (await client.acquireScopedRunnerToken({ agentExecutionId: executionId }))
+        ?? config.stigmerTokenRef?.current
+        ?? config.stigmerToken;
+      const attachment = synthesizeDatastoreAttachment(blueprint.datastoreUsages, {
+        bridgeEndpoint: config.mcpBridgeEndpoint,
+        credential: scopedCredential,
+        backendEndpoint: config.stigmerBackendEndpoint,
+      });
+      if (attachment) {
+        const resolvedServers = injectDatastoreAttachment(
+          mcpResolution.resolvedServers, attachment,
+        );
+        mcpResolution = {
+          resolvedServers,
+          cursorConfig: toCursorMcpConfig(resolvedServers),
+        };
+      }
+    }
     const mcpConfig = mcpResolution.cursorConfig;
 
     // Phase 4b: Merge approval policies from all layers.
@@ -920,6 +951,7 @@ async function executeCursorInner(
       instructions: blueprint.instructions,
       userMessage: spec.message,
       skills: skillMetadata,
+      datastoreUsages: blueprint.datastoreUsages,
       subAgents: blueprint.subAgents,
       workspaceDirs: blueprint.workspaceDirs,
       workspaceFileRefs: spec.workspaceFileRefs ?? [],
@@ -1500,6 +1532,7 @@ async function executeCursorInner(
             instructions: blueprint.instructions,
             userMessage: spec.message,
             skills: skillMetadata,
+            datastoreUsages: blueprint.datastoreUsages,
             subAgents: blueprint.subAgents,
             workspaceDirs: blueprint.workspaceDirs,
             workspaceFileRefs: spec.workspaceFileRefs ?? [],
@@ -2056,6 +2089,8 @@ export interface BuildPromptInput {
   instructions: string;
   userMessage: string;
   skills: import("./prompt-builder.js").SkillMetadata[];
+  /** Datastores attached via `datastore_usages` — the `<available_datastores>` section. */
+  datastoreUsages?: import("@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb").DatastoreUsage[];
   subAgents: import("@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb").SubAgent[];
   workspaceDirs: string[];
   workspaceFileRefs: string[];
@@ -2155,6 +2190,7 @@ export function buildPrompt(input: BuildPromptInput): string {
     instructions,
     userMessage,
     skills,
+    datastoreUsages: input.datastoreUsages ?? [],
     subAgents,
     workspaceDirs,
     workspaceFileRefs,

package/src/activities/execute-cursor/prompt-builder.ts

@@ -17,10 +17,11 @@
  */
 
 import { resolve } from "node:path";
-import type { SubAgent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import type { DatastoreUsage, SubAgent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
 import type { PendingApproval } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
 import { ApprovalAction, InteractionMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { formatContextBridgeText } from "../../shared/context-bridge.js";
+import { formatDatastoresSection } from "../../shared/datastore-attachment.js";
 import {
   formatSenderIdentityText,
   type SenderIdentity,
@@ -53,6 +54,12 @@ export interface EnhancedPromptOptions {
   instructions: string;
   userMessage: string;
   skills: SkillMetadata[];
+  /**
+   * Datastores attached via `datastore_usages` — rendered as the
+   * `<available_datastores>` section (DD-005 SD-5, skills precedent)
+   * pointing the model at the synthesized record tools.
+   */
+  datastoreUsages?: DatastoreUsage[];
   subAgents: SubAgent[];
   workspaceDirs: string[];
   workspaceFileRefs: string[];
@@ -113,6 +120,10 @@ export function buildEnhancedPrompt(options: EnhancedPromptOptions): string {
     sections.push(formatSkillsSection(options.skills));
   }
 
+  if (options.datastoreUsages !== undefined && options.datastoreUsages.length > 0) {
+    sections.push(formatDatastoresSection(options.datastoreUsages));
+  }
+
   if (options.subAgents.length > 0) {
     sections.push(formatSubAgentsSection(options.subAgents));
   }

package/src/activities/execute-deep-agent/__tests__/hitl-reject.test.ts

@@ -239,6 +239,7 @@ const httpConfig: Config = {
   temporalAddress: "localhost:7233",
   temporalNamespace: "default",
   stigmerBackendEndpoint: "http://localhost:7234",
+  mcpBridgeEndpoint: null,
   stigmerToken: null,
   cursorApiKey: "",
   workspaceRootDir: "/tmp/test",

package/src/activities/execute-deep-agent/__tests__/hitl-resume-approve-all.test.ts

@@ -284,6 +284,7 @@ const baseConfig: Config = {
   temporalAddress: "localhost:7233",
   temporalNamespace: "default",
   stigmerBackendEndpoint: "http://localhost:7234",
+  mcpBridgeEndpoint: null,
   stigmerToken: null,
   cursorApiKey: "",
   workspaceRootDir: "/tmp/test",

package/src/activities/execute-deep-agent/__tests__/hitl-resume-history.test.ts

@@ -238,6 +238,7 @@ const baseConfig: Config = {
   temporalAddress: "localhost:7233",
   temporalNamespace: "default",
   stigmerBackendEndpoint: "http://localhost:7234",
+  mcpBridgeEndpoint: null,
   stigmerToken: null,
   cursorApiKey: "",
   workspaceRootDir: "/tmp/test",

package/src/activities/execute-deep-agent/__tests__/index.test.ts

@@ -35,6 +35,7 @@ describe("ExecuteDeepAgent activity", () => {
     temporalAddress: "localhost:7233",
     temporalNamespace: "default",
     stigmerBackendEndpoint: "http://localhost:7234",
+  mcpBridgeEndpoint: null,
     stigmerToken: null,
     cursorApiKey: "",
     workspaceRootDir: "/tmp/test",

package/src/activities/execute-deep-agent/__tests__/sequential-gate-resume.test.ts

@@ -244,6 +244,7 @@ const memoryConfig: Config = {
   temporalAddress: "localhost:7233",
   temporalNamespace: "default",
   stigmerBackendEndpoint: "http://localhost:7234",
+  mcpBridgeEndpoint: null,
   stigmerToken: null,
   cursorApiKey: "",
   workspaceRootDir: "/tmp/test",

package/src/activities/execute-deep-agent/prompt-builder.ts

@@ -92,6 +92,11 @@ export interface PromptBuilderInput {
   provisionResults: ProvisionResult[];
   containerRoot: string;
   skillsPromptSection: string;
+  /**
+   * The `<available_datastores>` section (shared/datastore-attachment.ts
+   * formatDatastoresSection); empty when the agent uses no datastores.
+   */
+  datastoresPromptSection?: string;
   workspaceFileRefs: string[];
   workspaceRoot: string;
   injectedFiles: InjectedFile[];
@@ -156,6 +161,10 @@ export function buildEnhancedSystemPrompt(input: PromptBuilderInput): string {
     prompt += input.skillsPromptSection;
   }
 
+  if (input.datastoresPromptSection) {
+    prompt += "\n\n" + input.datastoresPromptSection;
+  }
+
   if (input.workspaceFileRefs.length > 0) {
     const refSection = buildReferencedFilesSection(
       input.workspaceFileRefs,

package/src/activities/execute-deep-agent/setup.ts

@@ -28,6 +28,11 @@ import { readSenderIdentity } from "../../shared/sender-identity.js";
 import { connectMcpServers, type McpConnectionResult } from "../../shared/mcp-manager.js";
 import { resolveMcpServers } from "../../shared/mcp-resolver.js";
 import { backfillMcpServersIfNeeded } from "../../shared/connect-backfill.js";
+import {
+  formatDatastoresSection,
+  injectDatastoreAttachment,
+  synthesizeDatastoreAttachment,
+} from "../../shared/datastore-attachment.js";
 import { WorkspaceProvisioner } from "../../shared/workspace/provisioner.js";
 import { LocalWorkspaceBackend } from "../../shared/workspace/local-backend.js";
 import type { WorkspaceBackend, ProvisionResult } from "../../shared/workspace/types.js";
@@ -314,16 +319,17 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
       ...(agent.spec!.mcpServerUsages || []),
       ...(session.spec!.mcpServerUsages || []),
     ];
+    const datastoreUsages = agent.spec!.datastoreUsages || [];
 
     let resolvedMcpServers: Awaited<ReturnType<typeof resolveMcpServers>> | null = null;
-    if (mcpServerUsages.length > 0) {
+    if (mcpServerUsages.length > 0 || datastoreUsages.length > 0) {
       await reportSetupProgress(client, executionId, "Connecting tools…");
       resolvedMcpServers = await resolveMcpServers(
         client, mcpServerUsages, envResult.mergedEnvVars,
       );
 
       const sessionOrg = session.metadata?.org ?? "";
-      const backfilledServers = await backfillMcpServersIfNeeded(
+      let backfilledServers = await backfillMcpServersIfNeeded(
         client,
         resolvedMcpServers.resolvedServers,
         mcpServerUsages,
@@ -332,6 +338,25 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
         undefined,
         envResult.secretKeys,
       );
+
+      // The datastore records attachment (T05) — injected AFTER resolve +
+      // backfill so the destructiveHint tightener can never gate it; empty
+      // approval maps keep it approval-free by construction (see
+      // shared/datastore-attachment.ts).
+      if (datastoreUsages.length > 0) {
+        const scopedCredential =
+          (await client.acquireScopedRunnerToken({ agentExecutionId: executionId }))
+          ?? config.stigmerTokenRef?.current
+          ?? config.stigmerToken;
+        const attachment = synthesizeDatastoreAttachment(datastoreUsages, {
+          bridgeEndpoint: config.mcpBridgeEndpoint,
+          credential: scopedCredential,
+          backendEndpoint: config.stigmerBackendEndpoint,
+        });
+        if (attachment) {
+          backfilledServers = injectDatastoreAttachment(backfilledServers, attachment);
+        }
+      }
       resolvedMcpServers = { resolvedServers: backfilledServers };
 
       mcpConnection = await connectMcpServers(
@@ -398,6 +423,9 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
       provisionResults,
       containerRoot: workspaceBackend.rootDir,
       skillsPromptSection,
+      datastoresPromptSection: datastoreUsages.length > 0
+        ? formatDatastoresSection(datastoreUsages)
+        : undefined,
       workspaceFileRefs: execution.spec!.workspaceFileRefs || [],
       workspaceRoot: workspaceBackend.rootDir,
       injectedFiles,

package/src/config.ts

@@ -60,6 +60,14 @@ export interface Config {
   readonly temporalNamespace: string;
   readonly stigmerBackendEndpoint: string;
   readonly stigmerToken: string | null;
+  /**
+   * The MCP bridge endpoint for the runner-synthesized datastore
+   * records attachment (STIGMER_MCP_BRIDGE_ENDPOINT, e.g.
+   * https://mcp.stigmer.ai). Null selects the OSS/local shape: a
+   * spawned `stigmer mcp-server` stdio child against the local backend.
+   * See shared/datastore-attachment.ts.
+   */
+  readonly mcpBridgeEndpoint: string | null;
   /**
    * Bearer credential for the Cursor SDK's Connect RPC transport.
    *
@@ -153,6 +161,8 @@ export function loadConfig(): Config {
     ? requireEnv("STIGMER_TOKEN")
     : (process.env.STIGMER_TOKEN ?? null);
 
+  const mcpBridgeEndpoint = process.env.STIGMER_MCP_BRIDGE_ENDPOINT ?? null;
+
   // In proxy mode, pass STIGMER_TOKEN as the SDK's API key. The SDK exchanges
   // it (via REST proxy → Tomcat → Cursor) for an access token. The HTTP/2
   // interceptor injects x-stigmer-auth for BiDi proxy authentication while
@@ -202,6 +212,7 @@ export function loadConfig(): Config {
     temporalNamespace,
     stigmerBackendEndpoint,
     stigmerToken,
+    mcpBridgeEndpoint,
     cursorApiKey,
     workspaceRootDir,
     mode,

package/src/runner-manager.ts

@@ -583,6 +583,9 @@ export function mapManagerOptionsToConfig(
     temporalNamespace: options.temporalNamespace ?? "default",
     stigmerBackendEndpoint: normalizeEndpoint(options.stigmerEndpoint),
     stigmerToken: options.stigmerToken ?? null,
+    // Env-only like the env-loaded path (loadConfig): the bridge endpoint
+    // is deployment topology, not per-session state.
+    mcpBridgeEndpoint: process.env.STIGMER_MCP_BRIDGE_ENDPOINT ?? null,
     stigmerTokenRef: tokenRef,
     stigmerRunnerTokenRef: runnerTokenRef,
     cursorApiKey: proxyActive

package/src/runner.ts

@@ -268,6 +268,9 @@ export function mapOptionsToConfig(options: StigmerRunnerOptions): Config {
     temporalNamespace: options.temporalNamespace ?? "default",
     stigmerBackendEndpoint: normalizeEndpoint(options.stigmerEndpoint),
     stigmerToken: options.stigmerToken ?? null,
+    // Env-only like the env-loaded path (loadConfig): the bridge endpoint
+    // is deployment topology, not per-session state.
+    mcpBridgeEndpoint: process.env.STIGMER_MCP_BRIDGE_ENDPOINT ?? null,
     cursorApiKey: proxyActive
       ? (options.cursorApiKey ?? "proxy-managed")
       : (options.cursorApiKey ?? ""),

package/src/shared/__tests__/artifact-storage.test.ts

@@ -420,6 +420,7 @@ describe("loadArtifactStorageConfig", () => {
     temporalAddress: "localhost:7233",
     temporalNamespace: "default",
     stigmerBackendEndpoint: "http://localhost:7234",
+    mcpBridgeEndpoint: null,
     cursorApiKey: "",
     workspaceRootDir: "/tmp",
     maxConcurrentActivities: 5,

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

@@ -0,0 +1,165 @@
+// 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,
+  formatDatastoresSection,
+  injectDatastoreAttachment,
+  synthesizeDatastoreAttachment,
+} from "../datastore-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("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("injectDatastoreAttachment", () => {
+  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: [],
+      discoveredCapabilitiesEmpty: false,
+    };
+    const result = injectDatastoreAttachment([other], attachment);
+    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: [],
+      discoveredCapabilitiesEmpty: false,
+    };
+
+    const result = injectDatastoreAttachment([impostor], attachment);
+
+    expect(result).toHaveLength(1);
+    expect(result[0].url).toBe("https://mcp.stigmer.ai/records");
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("reserved"));
+    warnSpy.mockRestore();
+  });
+});
+
+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>");
+  });
+});

package/src/shared/datastore-attachment.ts

@@ -0,0 +1,166 @@
+/**
+ * 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 mean mergeApprovalPolicies emits no entries for
+ * this server — zero classifier involvement. `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";
+
+/**
+ * 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";
+
+export interface DatastoreAttachmentOptions {
+  /**
+   * The bridge's HTTP endpoint (STIGMER_MCP_BRIDGE_ENDPOINT, e.g.
+   * https://mcp.stigmer.ai). Null selects the OSS stdio shape.
+   */
+  bridgeEndpoint: string | null;
+  /**
+   * The execution's session-scoped credential (the sandbox token a
+   * cloud runner holds, or the desktop runner's exchanged scoped
+   * token). Null attaches no Authorization header (OSS/local).
+   */
+  credential: string | null;
+  /**
+   * The stigmer backend endpoint the stdio child dials
+   * (config.stigmerBackendEndpoint). Only used for the OSS shape.
+   */
+  backendEndpoint: string;
+}
+
+/**
+ * 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: DatastoreAttachmentOptions,
+): 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: [],
+    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),
+    },
+  };
+}
+
+/**
+ * Inject the synthesized attachment into a resolved server list —
+ * AFTER resolve + backfill (see file header). A user server shadowing
+ * the reserved slug is replaced, loudly.
+ */
+export function injectDatastoreAttachment(
+  resolvedServers: ResolvedMcpServer[],
+  attachment: ResolvedMcpServer,
+): ResolvedMcpServer[] {
+  const shadowed = resolvedServers.some((s) => s.slug === attachment.slug);
+  if (shadowed) {
+    console.warn(
+      `MCP server slug "${attachment.slug}" is reserved for the datastore ` +
+      "records attachment; the user-defined server is replaced.",
+    );
+  }
+  return [
+    ...resolvedServers.filter((s) => s.slug !== attachment.slug),
+    attachment,
+  ];
+}
+
+/**
+ * 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).
+ */
+export function formatDatastoresSection(datastoreUsages: DatastoreUsage[]): string {
+  const slugs = datastoreUsages
+    .map((u) => u.datastoreRef?.slug)
+    .filter((s): s is string => !!s);
+  const entries = slugs.map((slug) => `- ${slug}`);
+  return [
+    "<available_datastores>",
+    "You have access to the following datastores through the record tools",
+    "(describe_datastore, find_records, insert_record, update_record, delete_record).",
+    "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,
+    "</available_datastores>",
+  ].join("\n");
+}
+
+/**
+ * The gRPC dial target (host:port) for a backend endpoint URL — the
+ * shape STIGMER_SERVER_ADDRESS wants (the bridge warns on schemes).
+ */
+function grpcTarget(endpoint: string): string {
+  try {
+    return new URL(endpoint).host;
+  } catch {
+    return endpoint;
+  }
+}