@stigmer/runner 3.5.3 → 3.6.0

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

@@ -49,6 +49,10 @@ import { utcTimestamp, persistStatus, reportSetupProgress, slimStatus } from "..
 import { TimingRecorder, emitTimingLog } from "../../shared/cold-start-timing.js";
 import { readContextBridge } from "../../shared/context-bridge.js";
 import { readSenderIdentity } from "../../shared/sender-identity.js";
+import {
+  injectCallerIdentityEnv,
+  resolveCallerIdentity,
+} from "../../shared/caller-identity.js";
 import { readSessionContext } from "../../shared/session-context.js";
 import { withholdSecretContentFromMessages } from "../../shared/tool-row.js";
 import { StallTimeoutError, formatStallFailure } from "../../shared/stall-watchdog.js";
@@ -60,10 +64,12 @@ import { StreamingUpdateScheduler, loadStreamingConfig } from "../../shared/stre
 import { createCursorEventRecorder } from "./cursor-event-recorder.js";
 import { resolveMcpServers, toCursorMcpConfig, validateMcpServerEnv } from "./mcp-resolver.js";
 import { resolveMcpTransportPosture } from "../../shared/mcp-transport-guard.js";
+import { synthesizeDatastoreAttachment } from "../../shared/datastore-attachment.js";
 import {
-  injectDatastoreAttachment,
-  synthesizeDatastoreAttachment,
-} from "../../shared/datastore-attachment.js";
+  discoverChannelMessaging,
+  synthesizeChannelAttachment,
+} from "../../shared/channel-attachment.js";
+import { injectSynthesizedAttachment } from "../../shared/synthesized-attachment.js";
 import { mergeApprovalPolicies } from "./approval-policy.js";
 import { deriveActiveLeases, isUnattendedApprovalMode } from "../../shared/approval-policy.js";
 import { backfillMcpServersIfNeeded } from "./connect-backfill.js";
@@ -590,11 +596,23 @@ async function executeCursorInner(
       }
     }
 
-    // Phase 4: Resolve MCP servers with approval policies
+    // Phase 4: Resolve MCP servers with approval policies.
+    // The MCP-bound env map (and ONLY it — never the agent process env)
+    // carries the reserved caller-identity keys, so a server that declares
+    // them in spec.env can template the platform-verified caller into its
+    // headers. filterEnvToDeclaredKeys keeps every other server blind.
     await reportSetupProgress(client, executionId, "Resolving MCP servers");
     const transportPosture = resolveMcpTransportPosture(config.mode);
+    const mcpEnvVars = injectCallerIdentityEnv(
+      envVars,
+      resolveCallerIdentity(
+        blueprint.sessionSpec.metadata,
+        session.status?.audit?.specAudit?.createdBy,
+      ),
+      sessionId,
+    );
     let mcpResolution = await resolveMcpServers(
-      client, blueprint.mergedMcpServerUsages, envVars, transportPosture,
+      client, blueprint.mergedMcpServerUsages, mcpEnvVars, transportPosture,
     );
     setupTiming.mark("resolve_mcp_servers");
 
@@ -602,11 +620,24 @@ async function executeCursorInner(
     heartbeatPhase = "resolving_mcp_servers";
     const sessionOrg = session.metadata?.org ?? "";
     mcpResolution = await backfillMcpServersIfNeeded(
-      client, mcpResolution, blueprint.mergedMcpServerUsages, envVars, sessionOrg,
+      client, mcpResolution, blueprint.mergedMcpServerUsages, mcpEnvVars, sessionOrg,
       transportPosture, heartbeat, secretKeys,
     );
     setupTiming.mark("backfill_mcp");
 
+    // The synthesized attachments' credential story (DD-006 D4): the
+    // exchanged token authenticates the discovery reads per-call (a
+    // desktop runner's ambient embedded_runner credential is refused by
+    // the messaging reach; undefined lets a cloud sandbox runner's
+    // ambient session-scoped token or OSS's no-auth apply). The
+    // attachment header falls back to the ambient credential where no
+    // exchange happens.
+    const exchangedRunnerToken =
+      await client.acquireScopedRunnerToken({ agentExecutionId: executionId });
+    const attachmentCredential = exchangedRunnerToken
+      ?? config.stigmerTokenRef?.current
+      ?? config.stigmerToken;
+
     // Phase 4a2: Synthesize the datastore records attachment (T05).
     // Deliberately AFTER resolve + backfill: the attachment has no
     // McpServerUsage and reports discovered capabilities, so the
@@ -614,18 +645,38 @@ async function executeCursorInner(
     // 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,
+        credential: attachmentCredential,
         backendEndpoint: config.stigmerBackendEndpoint,
       });
       if (attachment) {
-        const resolvedServers = injectDatastoreAttachment(
-          mcpResolution.resolvedServers, attachment,
+        const resolvedServers = injectSynthesizedAttachment(
+          mcpResolution.resolvedServers, attachment, "datastore records",
+        );
+        mcpResolution = {
+          resolvedServers,
+          cursorConfig: toCursorMcpConfig(resolvedServers),
+        };
+      }
+    }
+
+    // Phase 4a3: Synthesize the channel messaging attachment (DD-006
+    // D7/D8), the records attachment's twin. The discovery read is the
+    // attachment decision — the control plane runs the SAME candidate
+    // computation the send authorization uses — and every failure mode
+    // (no channel, OSS, registry down, pre-3a control plane) degrades
+    // to honest absence: no tool, no section, execution unharmed.
+    const channelMessaging = await discoverChannelMessaging(client, exchangedRunnerToken);
+    if (channelMessaging.length > 0) {
+      const attachment = synthesizeChannelAttachment(channelMessaging, {
+        bridgeEndpoint: config.mcpBridgeEndpoint,
+        credential: attachmentCredential,
+        backendEndpoint: config.stigmerBackendEndpoint,
+      });
+      if (attachment) {
+        const resolvedServers = injectSynthesizedAttachment(
+          mcpResolution.resolvedServers, attachment, "channel messaging",
         );
         mcpResolution = {
           resolvedServers,
@@ -992,6 +1043,7 @@ async function executeCursorInner(
       userMessage: spec.message,
       skills: skillMetadata,
       datastoreUsages: blueprint.datastoreUsages,
+      channelMessaging,
       subAgents: blueprint.subAgents,
       workspaceDirs: blueprint.workspaceDirs,
       workspaceFileRefs: spec.workspaceFileRefs ?? [],
@@ -1605,6 +1657,7 @@ async function executeCursorInner(
             userMessage: spec.message,
             skills: skillMetadata,
             datastoreUsages: blueprint.datastoreUsages,
+            channelMessaging,
             subAgents: blueprint.subAgents,
             workspaceDirs: blueprint.workspaceDirs,
             workspaceFileRefs: spec.workspaceFileRefs ?? [],
@@ -2169,6 +2222,11 @@ export interface BuildPromptInput {
   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[];
+  /**
+   * Serving proactive channels + their templates (the DD-006 D2
+   * discovery read) — the `<available_channel_templates>` section.
+   */
+  channelMessaging?: import("../../shared/channel-attachment.js").ChannelMessagingInfo[];
   subAgents: import("@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb").SubAgent[];
   workspaceDirs: string[];
   workspaceFileRefs: string[];
@@ -2276,6 +2334,7 @@ export function buildPrompt(input: BuildPromptInput): string {
     userMessage,
     skills,
     datastoreUsages: input.datastoreUsages ?? [],
+    channelMessaging: input.channelMessaging ?? [],
     subAgents,
     workspaceDirs,
     workspaceFileRefs,

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

@@ -22,6 +22,10 @@ import type { PendingApproval } from "@stigmer/protos/ai/stigmer/agentic/agentex
 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 {
+  formatChannelTemplatesSection,
+  type ChannelMessagingInfo,
+} from "../../shared/channel-attachment.js";
 import {
   formatSenderIdentityText,
   type SenderIdentity,
@@ -61,6 +65,12 @@ export interface EnhancedPromptOptions {
    * pointing the model at the synthesized record tools.
    */
   datastoreUsages?: DatastoreUsage[];
+  /**
+   * Serving proactive channels + their approved templates — rendered as
+   * the `<available_channel_templates>` section (proactive-messaging
+   * DD-003 D5) beside the synthesized send_channel_message tool.
+   */
+  channelMessaging?: ChannelMessagingInfo[];
   subAgents: SubAgent[];
   workspaceDirs: string[];
   workspaceFileRefs: string[];
@@ -133,6 +143,15 @@ export function buildEnhancedPrompt(options: EnhancedPromptOptions): string {
     sections.push(formatDatastoresSection(options.datastoreUsages));
   }
 
+  if (options.channelMessaging !== undefined && options.channelMessaging.length > 0) {
+    // "" when nothing is sendable — the tool alone still serves text
+    // sends inside a 24-hour window (DD-006 D6).
+    const channelSection = formatChannelTemplatesSection(options.channelMessaging);
+    if (channelSection !== "") {
+      sections.push(channelSection);
+    }
+  }
+
   if (options.subAgents.length > 0) {
     sections.push(formatSubAgentsSection(options.subAgents));
   }

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

@@ -98,6 +98,12 @@ export interface PromptBuilderInput {
    * formatDatastoresSection); empty when the agent uses no datastores.
    */
   datastoresPromptSection?: string;
+  /**
+   * The `<available_channel_templates>` section
+   * (shared/channel-attachment.ts formatChannelTemplatesSection); absent
+   * when the agent serves no proactive channel or nothing is sendable.
+   */
+  channelTemplatesPromptSection?: string;
   workspaceFileRefs: string[];
   workspaceRoot: string;
   injectedFiles: InjectedFile[];
@@ -174,6 +180,10 @@ export function buildEnhancedSystemPrompt(input: PromptBuilderInput): string {
     prompt += "\n\n" + input.datastoresPromptSection;
   }
 
+  if (input.channelTemplatesPromptSection) {
+    prompt += "\n\n" + input.channelTemplatesPromptSection;
+  }
+
   if (input.workspaceFileRefs.length > 0) {
     const refSection = buildReferencedFilesSection(
       input.workspaceFileRefs,

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

@@ -26,6 +26,10 @@ import { TimingRecorder, emitTimingLog } from "../../shared/cold-start-timing.js
 import { createCheckpointer } from "../../shared/checkpointer/factory.js";
 import { readContextBridge } from "../../shared/context-bridge.js";
 import { readSenderIdentity } from "../../shared/sender-identity.js";
+import {
+  injectCallerIdentityEnv,
+  resolveCallerIdentity,
+} from "../../shared/caller-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";
@@ -33,9 +37,14 @@ import { resolveMcpTransportPosture } from "../../shared/mcp-transport-guard.js"
 import { backfillMcpServersIfNeeded } from "../../shared/connect-backfill.js";
 import {
   formatDatastoresSection,
-  injectDatastoreAttachment,
   synthesizeDatastoreAttachment,
 } from "../../shared/datastore-attachment.js";
+import {
+  discoverChannelMessaging,
+  formatChannelTemplatesSection,
+  synthesizeChannelAttachment,
+} from "../../shared/channel-attachment.js";
+import { injectSynthesizedAttachment } from "../../shared/synthesized-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";
@@ -334,12 +343,41 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
     ];
     const datastoreUsages = agent.spec!.datastoreUsages || [];
 
+    // The synthesized attachments' credential story (DD-006 D4): the
+    // exchanged token authenticates the discovery reads per-call (the
+    // messaging reach refuses a desktop runner's ambient embedded_runner
+    // credential; undefined lets the ambient credential apply). The
+    // attachment header falls back to the ambient credential.
+    const exchangedRunnerToken =
+      await client.acquireScopedRunnerToken({ agentExecutionId: executionId });
+    const attachmentCredential = exchangedRunnerToken
+      ?? config.stigmerTokenRef?.current
+      ?? config.stigmerToken;
+
+    // The channel discovery read runs BEFORE the MCP gate below: an
+    // agent whose ONLY tool source is a proactive channel would
+    // otherwise never enter MCP resolution and never connect the
+    // attachment (DD-006 D7). Every failure mode degrades to an empty
+    // answer — no tool, no section, execution unharmed.
+    const channelMessaging = await discoverChannelMessaging(client, exchangedRunnerToken);
+
     let resolvedMcpServers: Awaited<ReturnType<typeof resolveMcpServers>> | null = null;
-    if (mcpServerUsages.length > 0 || datastoreUsages.length > 0) {
+    if (mcpServerUsages.length > 0 || datastoreUsages.length > 0 || channelMessaging.length > 0) {
       await reportSetupProgress(client, executionId, "Connecting tools…");
       const transportPosture = resolveMcpTransportPosture(config.mode);
+      // The MCP-bound env map (and ONLY it) carries the reserved
+      // caller-identity keys — mirror of the Cursor harness's Phase 4
+      // injection; filterEnvToDeclaredKeys keeps undeclared servers blind.
+      const mcpEnvVars = injectCallerIdentityEnv(
+        envResult.mergedEnvVars,
+        resolveCallerIdentity(
+          session.spec!.metadata,
+          session.status?.audit?.specAudit?.createdBy,
+        ),
+        sessionId,
+      );
       resolvedMcpServers = await resolveMcpServers(
-        client, mcpServerUsages, envResult.mergedEnvVars, transportPosture,
+        client, mcpServerUsages, mcpEnvVars, transportPosture,
       );
       timing.mark("resolve_mcp_servers");
 
@@ -348,7 +386,7 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
         client,
         resolvedMcpServers.resolvedServers,
         mcpServerUsages,
-        envResult.mergedEnvVars,
+        mcpEnvVars,
         sessionOrg,
         transportPosture,
         undefined,
@@ -360,17 +398,30 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
       // 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,
+          credential: attachmentCredential,
+          backendEndpoint: config.stigmerBackendEndpoint,
+        });
+        if (attachment) {
+          backfilledServers = injectSynthesizedAttachment(
+            backfilledServers, attachment, "datastore records",
+          );
+        }
+      }
+
+      // The channel messaging attachment (DD-006 D7/D8) — the records
+      // attachment's twin, injected under the same after-backfill rule.
+      if (channelMessaging.length > 0) {
+        const attachment = synthesizeChannelAttachment(channelMessaging, {
+          bridgeEndpoint: config.mcpBridgeEndpoint,
+          credential: attachmentCredential,
           backendEndpoint: config.stigmerBackendEndpoint,
         });
         if (attachment) {
-          backfilledServers = injectDatastoreAttachment(backfilledServers, attachment);
+          backfilledServers = injectSynthesizedAttachment(
+            backfilledServers, attachment, "channel messaging",
+          );
         }
       }
       resolvedMcpServers = { resolvedServers: backfilledServers };
@@ -445,6 +496,11 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
       datastoresPromptSection: datastoreUsages.length > 0
         ? formatDatastoresSection(datastoreUsages)
         : undefined,
+      // "" (nothing sendable) threads as undefined: the tool alone still
+      // serves text sends inside a 24-hour window (DD-006 D6).
+      channelTemplatesPromptSection: channelMessaging.length > 0
+        ? formatChannelTemplatesSection(channelMessaging) || undefined
+        : undefined,
       workspaceFileRefs: execution.spec!.workspaceFileRefs || [],
       workspaceRoot: workspaceBackend.rootDir,
       injectedFiles,

package/src/client/stigmer-client.ts

@@ -50,6 +50,8 @@ import type { Workflow } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/ap
 import { WorkflowInstanceQueryController } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/query_pb";
 import type { WorkflowInstance } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/api_pb";
 import { PlatformQueryController, GetRunnerScopedTokenInputSchema } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
+import { ChannelMessageQueryController } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/message_query_pb";
+import type { ChannelTemplate, MessagingChannel } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/message_io_pb";
 import { isEmbeddedRunnerToken } from "./token-claims.js";
 import { assertCreateRequirements, assertReferenceRequirements } from "./server-contracts.js";
 
@@ -156,6 +158,7 @@ export class StigmerClient {
   private readonly workflowQuery: Client<typeof WorkflowQueryController>;
   private readonly workflowInstanceQuery: Client<typeof WorkflowInstanceQueryController>;
   private readonly platformQuery: Client<typeof PlatformQueryController>;
+  private readonly channelMessageQuery: Client<typeof ChannelMessageQueryController>;
 
   private readonly tokenRef: TokenRef | null;
   private readonly runnerTokenRef: TokenRef | null;
@@ -239,6 +242,7 @@ export class StigmerClient {
     this.workflowQuery = createClient(WorkflowQueryController, this.transport);
     this.workflowInstanceQuery = createClient(WorkflowInstanceQueryController, this.transport);
     this.platformQuery = createClient(PlatformQueryController, this.transport);
+    this.channelMessageQuery = createClient(ChannelMessageQueryController, this.transport);
   }
 
   /**
@@ -380,6 +384,48 @@ export class StigmerClient {
     }
   }
 
+  /**
+   * The agent's serving proactive-messaging channels, as data
+   * (proactive-messaging DD-006 D2) — the runner's tool-attachment
+   * decision. An empty list is the everyday answer (most agents have no
+   * proactive channel).
+   *
+   * When a scoped runner token is supplied, the read authenticates with
+   * it per-call (the {@link getExecutionContextByExecutionId} precedent):
+   * the messaging reach refuses the desktop runner's ambient
+   * embedded_runner credential outright, and one desktop runner process
+   * serves many sessions concurrently, so the credential cannot live in
+   * a shared ref. A cloud sandbox runner's ambient credential is already
+   * the session-scoped token; OSS sends nothing and answers empty.
+   */
+  async listMessagingChannels(scopedToken?: string): Promise<MessagingChannel[]> {
+    const res = await this.channelMessageQuery.listMessagingChannels(
+      {},
+      scopedToken
+        ? { headers: { authorization: `Bearer ${scopedToken}` } }
+        : undefined,
+    );
+    return res.entries;
+  }
+
+  /**
+   * The channel's provider template registry, approved entries only —
+   * the `<available_channel_templates>` prompt section's source
+   * (proactive-messaging DD-003 D5). Entries carry the DD-006 D1
+   * sendability verdict (`unsupportedReason`, empty means sendable);
+   * the section formatter filters on it. Credential rules as
+   * {@link listMessagingChannels}.
+   */
+  async listChannelTemplates(channel: string, scopedToken?: string): Promise<ChannelTemplate[]> {
+    const res = await this.channelMessageQuery.listTemplates(
+      { channel, approvedOnly: true },
+      scopedToken
+        ? { headers: { authorization: `Bearer ${scopedToken}` } }
+        : undefined,
+    );
+    return res.entries;
+  }
+
   async getSession(sessionId: string): Promise<Session> {
     return this.sessionQuery.get({ value: sessionId });
   }

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

@@ -0,0 +1,159 @@
+/**
+ * Unit tests for the caller identity: the reserved env keys, the
+ * precedence chain, the authoritative injection, and the discovery
+ * sentinel that keeps identity-templating servers discoverable.
+ */
+
+import { describe, it, expect } from "vitest";
+import {
+  ANONYMOUS_KIND,
+  CALLER_IDENTITY_KIND_ENV_KEY,
+  CALLER_IDENTITY_VALUE_ENV_KEY,
+  SESSION_ID_ENV_KEY,
+  STIGMER_USER_KIND,
+  anonymousCallerIdentity,
+  injectAnonymousCallerIdentityForDiscovery,
+  injectCallerIdentityEnv,
+  resolveCallerIdentity,
+} from "../caller-identity.js";
+import {
+  SENDER_IDENTITY_METADATA_KEY,
+  SENDER_KIND_METADATA_KEY,
+} from "../sender-identity.js";
+import { resolveHeaders } from "../placeholder-resolver.js";
+
+describe("reserved env keys", () => {
+  it("are pinned verbatim — MCP server specs template these names (contract guard)", () => {
+    // These names appear in user-authored McpServer YAML (spec.env
+    // declarations and ${...} header templates). Renaming them breaks
+    // every deployed server that consumes caller identity.
+    expect(CALLER_IDENTITY_KIND_ENV_KEY).toBe("STIGMER_CALLER_IDENTITY_KIND");
+    expect(CALLER_IDENTITY_VALUE_ENV_KEY).toBe("STIGMER_CALLER_IDENTITY_VALUE");
+    expect(SESSION_ID_ENV_KEY).toBe("STIGMER_SESSION_ID");
+  });
+});
+
+describe("resolveCallerIdentity precedence", () => {
+  const channelMetadata = {
+    [SENDER_IDENTITY_METADATA_KEY]: "919800000001",
+    [SENDER_KIND_METADATA_KEY]: "whatsapp_phone",
+  };
+
+  it("channel sender wins, kind passed through VERBATIM from the broker", () => {
+    expect(
+      resolveCallerIdentity(channelMetadata, { id: "idacc_1", email: "owner@example.com" }),
+    ).toEqual({ kind: "whatsapp_phone", value: "919800000001" });
+  });
+
+  it("falls to the session creator (stigmer_user) when no channel sender exists", () => {
+    expect(
+      resolveCallerIdentity({}, { id: "idacc_1", email: "owner@example.com" }),
+    ).toEqual({ kind: STIGMER_USER_KIND, value: "owner@example.com" });
+  });
+
+  it("prefers the creator's email over the historically-mixed id field", () => {
+    // The audit actor's `id` is sometimes an identity-account id and
+    // sometimes an email (per the proto's own @internal note) — email is
+    // what humans bind against, so it wins when present.
+    expect(resolveCallerIdentity(undefined, { id: "idacc_1", email: "a@b.c" }).value).toBe("a@b.c");
+    expect(resolveCallerIdentity(undefined, { id: "idacc_1" }).value).toBe("idacc_1");
+  });
+
+  it("falls to anonymous when neither source exists (OSS sparse audit, no metadata)", () => {
+    expect(resolveCallerIdentity(undefined, undefined)).toEqual({
+      kind: ANONYMOUS_KIND,
+      value: "",
+    });
+    expect(resolveCallerIdentity({}, { id: "  ", email: "" })).toEqual({
+      kind: ANONYMOUS_KIND,
+      value: "",
+    });
+  });
+
+  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.
+    expect(
+      resolveCallerIdentity(
+        { [SENDER_IDENTITY_METADATA_KEY]: "919800000001" },
+        { email: "owner@example.com" },
+      ),
+    ).toEqual({ kind: STIGMER_USER_KIND, value: "owner@example.com" });
+  });
+});
+
+describe("injectCallerIdentityEnv", () => {
+  const identity = { kind: "whatsapp_phone", value: "919800000001" };
+
+  it("returns a NEW map with the reserved keys set — input never mutated", () => {
+    const input = { GRIST_API_KEY: "secret" };
+    const result = injectCallerIdentityEnv(input, identity, "sess_1");
+
+    expect(result).toEqual({
+      GRIST_API_KEY: "secret",
+      [CALLER_IDENTITY_KIND_ENV_KEY]: "whatsapp_phone",
+      [CALLER_IDENTITY_VALUE_ENV_KEY]: "919800000001",
+      [SESSION_ID_ENV_KEY]: "sess_1",
+    });
+    expect(input).toEqual({ GRIST_API_KEY: "secret" });
+  });
+
+  it("platform values are authoritative — a user env var cannot impersonate a caller", () => {
+    const result = injectCallerIdentityEnv(
+      { [CALLER_IDENTITY_VALUE_ENV_KEY]: "999999999999" },
+      identity,
+      "sess_1",
+    );
+    expect(result[CALLER_IDENTITY_VALUE_ENV_KEY]).toBe("919800000001");
+  });
+
+  it("the reserved keys can never hit the unresolved-placeholder silent-skip path", () => {
+    // At runtime PlaceholderResolutionError is caught and the server
+    // silently dropped from the execution — always-present injection makes
+    // that unreachable for these keys, whatever the identity resolved to.
+    const env = injectCallerIdentityEnv({}, anonymousCallerIdentity(), "");
+    const headers = resolveHeaders(
+      {
+        "X-Stigmer-Caller-Kind": `\${${CALLER_IDENTITY_KIND_ENV_KEY}}`,
+        "X-Stigmer-Caller-Value": `\${${CALLER_IDENTITY_VALUE_ENV_KEY}}`,
+      },
+      env,
+    );
+    expect(headers).toEqual({
+      "X-Stigmer-Caller-Kind": ANONYMOUS_KIND,
+      "X-Stigmer-Caller-Value": "",
+    });
+  });
+});
+
+describe("injectAnonymousCallerIdentityForDiscovery", () => {
+  it("resolves declared identity placeholders with the anonymous sentinel", () => {
+    // Discovery has no session: without the sentinel, a server templating
+    // ${STIGMER_CALLER_IDENTITY_VALUE} would throw
+    // PlaceholderResolutionError and never get its tools classified.
+    const declared = new Set([
+      "GRIST_API_KEY",
+      CALLER_IDENTITY_KIND_ENV_KEY,
+      CALLER_IDENTITY_VALUE_ENV_KEY,
+    ]);
+    const env = injectAnonymousCallerIdentityForDiscovery(declared, {
+      GRIST_API_KEY: "secret",
+    });
+
+    expect(
+      resolveHeaders(
+        { "X-Stigmer-Caller-Kind": `\${${CALLER_IDENTITY_KIND_ENV_KEY}}` },
+        env,
+      ),
+    ).toEqual({ "X-Stigmer-Caller-Kind": ANONYMOUS_KIND });
+    expect(env[CALLER_IDENTITY_VALUE_ENV_KEY]).toBe("");
+    expect(env.GRIST_API_KEY).toBe("secret");
+  });
+
+  it("is declaration-gated: servers that never declared the keys get an untouched map", () => {
+    const input = { OTHER: "x" };
+    const result = injectAnonymousCallerIdentityForDiscovery(new Set(["OTHER"]), input);
+    expect(result).toBe(input);
+    expect(result).not.toHaveProperty(CALLER_IDENTITY_KIND_ENV_KEY);
+  });
+});