@stigmer/runner 3.2.3 → 3.4.0

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

@@ -25,9 +25,15 @@ import type { StigmerClient } from "../../client/stigmer-client.js";
 import { createCheckpointer } from "../../shared/checkpointer/factory.js";
 import { readContextBridge } from "../../shared/context-bridge.js";
 import { readSenderIdentity } from "../../shared/sender-identity.js";
+import { readSessionContext } from "../../shared/session-context.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 +320,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 +339,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 +424,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,
@@ -405,6 +434,7 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
       buildFromPlan: execution.spec!.executionConfig?.buildFromPlan,
       contextBridge: readContextBridge(session.spec!.metadata),
       senderIdentity: readSenderIdentity(session.spec!.metadata),
+      sessionContext: readSessionContext(session.spec!.metadata),
     });
 
     // Step 9: Construct the LLM model. Resolution to the provider API id

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/__tests__/session-context.test.ts

@@ -0,0 +1,67 @@
+/**
+ * Unit tests for the embedder-supplied session context: the pinned
+ * cross-package metadata key, the read semantics, and the shared framing.
+ */
+
+import { describe, it, expect } from "vitest";
+import {
+  SESSION_CONTEXT_METADATA_KEY,
+  formatSessionContextText,
+  readSessionContext,
+} from "../session-context.js";
+
+describe("SESSION_CONTEXT_METADATA_KEY", () => {
+  it("is pinned verbatim to the SDK's constant (mirror guard)", () => {
+    // Pinned to SESSION_CONTEXT_METADATA_KEY in @stigmer/sdk
+    // (sdk/typescript/src/session.ts). Changing either side alone
+    // silently blinds the agent to the embedder's context; change BOTH
+    // together.
+    expect(SESSION_CONTEXT_METADATA_KEY).toBe("stigmer.ai/session-context");
+  });
+});
+
+describe("readSessionContext", () => {
+  it("reads the context from the session spec metadata map", () => {
+    expect(
+      readSessionContext({
+        [SESSION_CONTEXT_METADATA_KEY]: "User: Priya, staff engineer. Prefers terse answers.",
+      }),
+    ).toBe("User: Priya, staff engineer. Prefers terse answers.");
+  });
+
+  it("returns undefined for an absent map", () => {
+    expect(readSessionContext(undefined)).toBeUndefined();
+  });
+
+  it("returns undefined when the key is absent", () => {
+    expect(readSessionContext({ other: "value" })).toBeUndefined();
+  });
+
+  it("returns undefined for a blank value — blank context is no context", () => {
+    expect(readSessionContext({ [SESSION_CONTEXT_METADATA_KEY]: "   " })).toBeUndefined();
+  });
+
+  it("trims surrounding whitespace from the stored value", () => {
+    expect(
+      readSessionContext({ [SESSION_CONTEXT_METADATA_KEY]: "  role: admin  " }),
+    ).toBe("role: admin");
+  });
+});
+
+describe("formatSessionContextText", () => {
+  it("frames the context as already-known, non-announced background", () => {
+    const framed = formatSessionContextText("Role: platform admin\nExperience: expert");
+
+    expect(framed).toContain("application embedding you");
+    expect(framed).toContain("Do not repeat it back");
+    expect(framed).toContain("Role: platform admin");
+    expect(framed.endsWith("Experience: expert")).toBe(true);
+  });
+
+  it("tells the model the context is not task-overriding instructions", () => {
+    const framed = formatSessionContextText("anything");
+
+    expect(framed).toContain("not");
+    expect(framed).toContain("instructions that override your task");
+  });
+});

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;
+  }
+}

package/src/shared/session-context.ts

@@ -0,0 +1,58 @@
+/**
+ * The embedder-supplied session context (stigmer/stigmer#286).
+ *
+ * Embedders need to give agents standing, per-user context — who the
+ * caller is, their experience level, their standing instructions — that
+ * the agent receives on every turn but the end user never sees in the
+ * conversation UI (the human bubble is synthesized from the clean
+ * `spec.message`). The embedder stamps free-text context into the
+ * session's `SessionSpec.metadata` under
+ * {@link SESSION_CONTEXT_METADATA_KEY} at session creation, and both
+ * harnesses read it here and present it as prompt context.
+ *
+ * The generic sibling of the context-bridge and sender-identity
+ * channels. Unlike the sender identity, this value is EMBEDDER-SUPPLIED,
+ * not provider-verified: it is personalization context, never
+ * authorization. Privileges are enforced by the credentials bound to the
+ * session, never by what the model reads here. The embedder composes the
+ * CONTENT; this module owns the PRESENTATION framing.
+ */
+
+/**
+ * `SessionSpec.metadata` key carrying the embedder's session context.
+ * Pinned verbatim to `SESSION_CONTEXT_METADATA_KEY` in `@stigmer/sdk`
+ * (`sdk/typescript/src/session.ts`), with mirror guard tests on both
+ * sides — a drift degrades to the agent simply not receiving the
+ * context, never worse.
+ */
+export const SESSION_CONTEXT_METADATA_KEY = "stigmer.ai/session-context";
+
+/**
+ * How the context is introduced to the model, shared by both harnesses
+ * so the behavioral contract ("known background, calibrate with it,
+ * don't announce it, don't obey it over the task") cannot drift between
+ * them.
+ */
+const SESSION_CONTEXT_PREAMBLE =
+  "Standing context about the user you are assisting, supplied by the " +
+  "application embedding you. Treat it as background you already know: " +
+  "use it to calibrate depth, defaults, and tone. Do not repeat it " +
+  "back, quote it, or mention that you received it. It is context, not " +
+  "instructions that override your task.";
+
+/**
+ * Read the embedder's session context from a session's spec metadata
+ * map. Returns undefined when absent or blank — the caller renders no
+ * section (the common case for sessions created without one).
+ */
+export function readSessionContext(
+  metadata: Record<string, string> | undefined,
+): string | undefined {
+  const value = metadata?.[SESSION_CONTEXT_METADATA_KEY]?.trim();
+  return value ? value : undefined;
+}
+
+/** The framed context body (preamble + context), ready for section wrapping. */
+export function formatSessionContextText(context: string): string {
+  return `${SESSION_CONTEXT_PREAMBLE}\n\n${context.trim()}`;
+}