@stigmer/runner 3.5.3 → 3.6.0

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

@@ -0,0 +1,276 @@
+/**
+ * The channel messaging attachment (proactive-messaging DD-006 D7/D8):
+ * discovery with the never-throw failure posture, both connection
+ * shapes, the structural approval-freedom the datastore attachment
+ * pinned before it, and the prompt section's filter/order/cap rules
+ * (DD-006 D6). The cross-repo pinned strings (slug, route, roster) are
+ * guarded here and in the mcp-server integration test — the
+ * TOOL_CALL_LIMIT precedent.
+ */
+
+import { describe, expect, it, vi } from "vitest";
+import { Code, ConnectError } from "@connectrpc/connect";
+import type {
+  ChannelTemplate,
+  MessagingChannel,
+} from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/message_io_pb";
+
+import { mockStigmerClient } from "../../__test-utils__/mock-client.js";
+import { mergeApprovalPolicies, type ActiveLeases } from "../approval-policy.js";
+import { needsBackfill } from "../connect-backfill.js";
+import {
+  CHANNEL_ATTACHMENT_SLUG,
+  CHANNELS_ROUTE,
+  TEMPLATE_SECTION_CAP,
+  discoverChannelMessaging,
+  formatChannelTemplatesSection,
+  synthesizeChannelAttachment,
+  type ChannelMessagingInfo,
+} from "../channel-attachment.js";
+import type { ResolvedMcpServer } from "../mcp-resolver.js";
+
+function channel(slug: string): MessagingChannel {
+  return { channel: slug, provider: "whatsapp" } as MessagingChannel;
+}
+
+function template(overrides: Partial<ChannelTemplate>): ChannelTemplate {
+  return {
+    name: "fee_reminder",
+    language: "en",
+    category: "UTILITY",
+    status: "APPROVED",
+    parameterFormat: "POSITIONAL",
+    parameterNames: ["1", "2"],
+    bodyText: "Hi {{1}}, your fee of {{2}} is due.",
+    headerFormat: "",
+    rejectionReason: "",
+    unsupportedReason: "",
+    ...overrides,
+  } as ChannelTemplate;
+}
+
+function info(slug: string, templates: ChannelTemplate[]): ChannelMessagingInfo {
+  return { channel: channel(slug), templates };
+}
+
+const noLeases: ActiveLeases = {
+  global: false,
+  categories: new Set(),
+  servers: new Set(),
+};
+
+describe("discoverChannelMessaging (the DD-006 D4 failure posture)", () => {
+  it("returns channels with their templates, threading the scoped credential", async () => {
+    const client = mockStigmerClient({
+      listMessagingChannels: vi.fn().mockResolvedValue([channel("isc-whatsapp")]),
+      listChannelTemplates: vi.fn().mockResolvedValue([template({})]),
+    });
+
+    const result = await discoverChannelMessaging(client, "scoped-tok");
+
+    expect(result).toHaveLength(1);
+    expect(result[0].channel.channel).toBe("isc-whatsapp");
+    expect(result[0].templates).toHaveLength(1);
+    expect(client.listMessagingChannels).toHaveBeenCalledWith("scoped-tok");
+    expect(client.listChannelTemplates).toHaveBeenCalledWith("isc-whatsapp", "scoped-tok");
+  });
+
+  it("answers empty for the everyday no-channel agent without fetching templates", async () => {
+    const client = mockStigmerClient();
+
+    expect(await discoverChannelMessaging(client, undefined)).toEqual([]);
+    expect(client.listChannelTemplates).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ["UNIMPLEMENTED (a control plane predating 3a)", Code.Unimplemented],
+    ["FAILED_PRECONDITION (the OSS posture on older servers)", Code.FailedPrecondition],
+    ["PERMISSION_DENIED (an unexpected reach refusal)", Code.PermissionDenied],
+  ])("degrades %s to honest absence, never a throw", async (_label, code) => {
+    const client = mockStigmerClient({
+      listMessagingChannels: vi.fn().mockRejectedValue(new ConnectError("nope", code)),
+    });
+    const quiet = vi.spyOn(console, "debug").mockImplementation(() => {});
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    expect(await discoverChannelMessaging(client, undefined)).toEqual([]);
+
+    quiet.mockRestore();
+    warn.mockRestore();
+  });
+
+  it("a template-read failure degrades PER CHANNEL — the tool survives, the section entry does not", async () => {
+    const client = mockStigmerClient({
+      listMessagingChannels: vi.fn().mockResolvedValue([channel("wa-a"), channel("wa-b")]),
+      listChannelTemplates: vi.fn()
+        .mockImplementation(async (slug: string) => {
+          if (slug === "wa-a") throw new ConnectError("registry down", Code.Unavailable);
+          return [template({})];
+        }),
+    });
+    const quiet = vi.spyOn(console, "debug").mockImplementation(() => {});
+
+    const result = await discoverChannelMessaging(client, undefined);
+
+    expect(result.map((r) => [r.channel.channel, r.templates.length])).toEqual([
+      ["wa-a", 0],
+      ["wa-b", 1],
+    ]);
+    quiet.mockRestore();
+  });
+});
+
+describe("synthesizeChannelAttachment", () => {
+  const options = {
+    bridgeEndpoint: "https://mcp.stigmer.ai/",
+    credential: "sandbox-token",
+    backendEndpoint: "http://localhost:7234",
+  };
+
+  it("returns undefined when the agent serves no proactive channel", () => {
+    expect(synthesizeChannelAttachment([], options)).toBeUndefined();
+  });
+
+  it("builds the HTTP shape against the bridge /channels route with the credential", () => {
+    const attachment = synthesizeChannelAttachment([info("isc-whatsapp", [])], options);
+    expect(attachment).toMatchObject({
+      slug: CHANNEL_ATTACHMENT_SLUG,
+      connectionType: "http",
+      url: "https://mcp.stigmer.ai/channels",
+      headers: { Authorization: "Bearer sandbox-token" },
+    });
+  });
+
+  it("builds the OSS stdio shape: the CLI-embedded bridge with the channels roster", () => {
+    const attachment = synthesizeChannelAttachment([info("isc-whatsapp", [])], {
+      bridgeEndpoint: null,
+      credential: null,
+      backendEndpoint: "http://localhost:7234",
+    });
+    expect(attachment).toMatchObject({
+      connectionType: "stdio",
+      command: "stigmer",
+      args: ["mcp-server"],
+      env: {
+        STIGMER_MCP_ROSTER: "channels",
+        STIGMER_SERVER_ADDRESS: "localhost:7234",
+      },
+    });
+  });
+
+  it("pins the cross-repo strings the mcp-server side guards too", () => {
+    expect(CHANNEL_ATTACHMENT_SLUG).toBe("stigmer-channels");
+    expect(CHANNELS_ROUTE).toBe("/channels");
+  });
+
+  it("is approval-free by construction: zero entries in the merged approval map", () => {
+    const attachment = synthesizeChannelAttachment([info("isc-whatsapp", [])], options)!;
+    // Forced, not convenient (DD-002 D6): both calling surfaces run
+    // UNATTENDED mode, where a gated tool resolves as skip-and-adapt —
+    // a gated send tool means reminders never send.
+    const merged = mergeApprovalPolicies(
+      [attachment as ResolvedMcpServer], [], noLeases,
+    );
+    expect(merged.size).toBe(0);
+  });
+
+  it("is structurally immune to the connect backfill (destructiveHint tightener)", () => {
+    const attachment = synthesizeChannelAttachment([info("isc-whatsapp", [])], options)!;
+    expect(attachment.discoveredCapabilitiesEmpty).toBe(false);
+    expect(needsBackfill(attachment)).toBe(false);
+  });
+});
+
+describe("formatChannelTemplatesSection (DD-006 D6)", () => {
+  it("renders sendable templates with body text, parameters, and the image-header requirement", () => {
+    const section = formatChannelTemplatesSection([
+      info("isc-whatsapp", [
+        template({}),
+        template({
+          name: "invoice_qr",
+          parameterFormat: "NAMED",
+          parameterNames: ["member_name", "amount"],
+          bodyText: "Hello {{member_name}}, pay {{amount}}.",
+          headerFormat: "IMAGE",
+        }),
+      ]),
+    ]);
+
+    expect(section).toContain("<available_channel_templates>");
+    expect(section).toContain("channel: isc-whatsapp (whatsapp)");
+    expect(section).toContain("- fee_reminder (en) [UTILITY], parameters: 1, 2");
+    expect(section).toContain('"Hi {{1}}, your fee of {{2}} is due."');
+    expect(section).toContain(
+      "- invoice_qr (en) [UTILITY], parameters: member_name, amount"
+        + " (requires header_image_link: a public HTTPS image URL)",
+    );
+    expect(section).toContain("send_channel_message");
+    expect(section).toContain("</available_channel_templates>");
+  });
+
+  it("filters unsendable templates out entirely — the console is the diagnosis surface", () => {
+    const section = formatChannelTemplatesSection([
+      info("isc-whatsapp", [
+        template({}),
+        template({
+          name: "dynamic_promo",
+          unsupportedReason: "this template has a dynamic-URL button, which this platform"
+            + " version cannot supply parameters for",
+        }),
+      ]),
+    ]);
+
+    expect(section).toContain("fee_reminder");
+    expect(section).not.toContain("dynamic_promo");
+  });
+
+  it("returns \"\" when nothing is sendable — the tool alone still serves text sends", () => {
+    expect(formatChannelTemplatesSection([info("isc-whatsapp", [])])).toBe("");
+    expect(formatChannelTemplatesSection([
+      info("isc-whatsapp", [template({ unsupportedReason: "unsupported" })]),
+    ])).toBe("");
+  });
+
+  it("orders deterministically by (name, language) — never registry order", () => {
+    const section = formatChannelTemplatesSection([
+      info("isc-whatsapp", [
+        template({ name: "b_second", language: "en" }),
+        template({ name: "a_first", language: "hi" }),
+        template({ name: "a_first", language: "en" }),
+      ]),
+    ]);
+
+    const first = section.indexOf("a_first (en)");
+    const second = section.indexOf("a_first (hi)");
+    const third = section.indexOf("b_second (en)");
+    expect(first).toBeGreaterThan(-1);
+    expect(second).toBeGreaterThan(first);
+    expect(third).toBeGreaterThan(second);
+  });
+
+  it("caps the section and names how many were withheld", () => {
+    const many = Array.from({ length: TEMPLATE_SECTION_CAP + 5 }, (_, i) =>
+      template({ name: `t_${String(i).padStart(3, "0")}` }));
+
+    const section = formatChannelTemplatesSection([info("isc-whatsapp", many)]);
+
+    expect(section).toContain(`t_${String(TEMPLATE_SECTION_CAP - 1).padStart(3, "0")}`);
+    expect(section).not.toContain(`t_${String(TEMPLATE_SECTION_CAP).padStart(3, "0")}`);
+    expect(section).toContain("(5 more approved templates not shown)");
+  });
+
+  it("the cap spans channels; a later channel with no budget left is omitted whole", () => {
+    const fill = Array.from({ length: TEMPLATE_SECTION_CAP }, (_, i) =>
+      template({ name: `t_${String(i).padStart(3, "0")}` }));
+
+    const section = formatChannelTemplatesSection([
+      info("wa-a", fill),
+      info("wa-b", [template({ name: "starved" })]),
+    ]);
+
+    expect(section).toContain("channel: wa-a (whatsapp)");
+    expect(section).not.toContain("channel: wa-b (whatsapp)");
+    expect(section).not.toContain("starved");
+    expect(section).toContain("(1 more approved template not shown)");
+  });
+});

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

@@ -14,9 +14,9 @@ import { needsBackfill } from "../connect-backfill.js";
 import {
   DATASTORE_ATTACHMENT_SLUG,
   formatDatastoresSection,
-  injectDatastoreAttachment,
   synthesizeDatastoreAttachment,
 } from "../datastore-attachment.js";
+import { injectSynthesizedAttachment } from "../synthesized-attachment.js";
 import type { ResolvedMcpServer } from "../mcp-resolver.js";
 
 function usage(slug: string) {
@@ -113,7 +113,7 @@ describe("synthesizeDatastoreAttachment", () => {
   });
 });
 
-describe("injectDatastoreAttachment", () => {
+describe("injectSynthesizedAttachment (the shared injection path)", () => {
   const attachment = synthesizeDatastoreAttachment([usage("clinic")], {
     bridgeEndpoint: "https://mcp.stigmer.ai",
     credential: "tok",
@@ -129,7 +129,7 @@ describe("injectDatastoreAttachment", () => {
       pinnedToolApprovals: [],
       discoveredCapabilitiesEmpty: false,
     };
-    const result = injectDatastoreAttachment([other], attachment);
+    const result = injectSynthesizedAttachment([other], attachment, "datastore records");
     expect(result.map((s) => s.slug)).toEqual(["github", DATASTORE_ATTACHMENT_SLUG]);
   });
 
@@ -144,7 +144,7 @@ describe("injectDatastoreAttachment", () => {
       discoveredCapabilitiesEmpty: false,
     };
 
-    const result = injectDatastoreAttachment([impostor], attachment);
+    const result = injectSynthesizedAttachment([impostor], attachment, "datastore records");
 
     expect(result).toHaveLength(1);
     expect(result[0].url).toBe("https://mcp.stigmer.ai/records");

package/src/shared/caller-identity.ts

@@ -0,0 +1,161 @@
+/**
+ * The caller identity for MCP server configs — reserved platform env keys
+ * that carry the platform-verified "who is calling" into user-defined MCP
+ * server headers/args, without ever passing through the model.
+ *
+ * The identity is a (kind, value) pair with fixed precedence:
+ *   1. The channel sender (Meta/Slack-verified, stamped into
+ *      `SessionSpec.metadata` by the cloud broker — sender-identity.ts is
+ *      the reader).
+ *   2. The session creator (`stigmer_user`) from the Session resource's
+ *      audit actor — console/CLI sessions have no channel sender, but the
+ *      platform knows exactly who created the session.
+ *   3. The anonymous sentinel — discovery (no session exists) and sessions
+ *      with no readable creator. Consumers must treat anonymous as a
+ *      first-class caller: answer tools/list, refuse tool calls.
+ *
+ * Injection is opt-in by construction: the values enter the env map used
+ * for MCP placeholder resolution, and `filterEnvToDeclaredKeys` already
+ * restricts every server to the keys it declared in `spec.env`. A server
+ * that never declares the reserved keys never receives identity.
+ * Declarations MUST be `optional: true` — execution creation validates
+ * declared-env completeness in both editions, and these keys have no value
+ * until the runner injects them.
+ *
+ * Trust model: the resulting header is RUNNER-asserted, not signed. It
+ * closes the prompt-injection hole (the model cannot influence the value),
+ * but the receiving server must pair it with a shared secret and be
+ * operated by someone who trusts the runner's network path.
+ */
+
+import { readSenderIdentity } from "./sender-identity.js";
+
+/** Reserved env key: the identity's kind token. */
+export const CALLER_IDENTITY_KIND_ENV_KEY = "STIGMER_CALLER_IDENTITY_KIND";
+
+/** Reserved env key: the identity's value. */
+export const CALLER_IDENTITY_VALUE_ENV_KEY = "STIGMER_CALLER_IDENTITY_VALUE";
+
+/** Reserved env key: the session the identity was resolved for. */
+export const SESSION_ID_ENV_KEY = "STIGMER_SESSION_ID";
+
+/**
+ * Kind token for a platform user (console/CLI session creator). Channel
+ * kinds (`whatsapp_phone`, `slack_user_id`, ...) pass through VERBATIM
+ * from the cloud broker's metadata — this module never rewrites them.
+ */
+export const STIGMER_USER_KIND = "stigmer_user";
+
+/**
+ * Kind token for the anonymous caller. Deliberately a real token rather
+ * than an absent key: every declared placeholder must resolve in every
+ * resolution context, or discovery fails with PlaceholderResolutionError
+ * before the server's tools are ever classified.
+ */
+export const ANONYMOUS_KIND = "anonymous";
+
+/** The resolved caller identity. */
+export interface CallerIdentity {
+  kind: string;
+  value: string;
+}
+
+/** The audit actor shape read from `status.audit.spec_audit.created_by`. */
+export interface SessionCreatorActor {
+  id?: string;
+  email?: string;
+}
+
+/** The identity injected when no session context exists (discovery). */
+export function anonymousCallerIdentity(): CallerIdentity {
+  return { kind: ANONYMOUS_KIND, value: "" };
+}
+
+/**
+ * Resolve the caller identity for a session: channel sender first, then
+ * the session creator, then anonymous.
+ *
+ * The creator value prefers email over id: bindings are maintained by
+ * humans, and the audit actor's `id` field is historically mixed
+ * (identity-account id vs email — see the proto's own @internal note).
+ * Binding matchers should compare emails case-insensitively.
+ */
+export function resolveCallerIdentity(
+  sessionMetadata: Record<string, string> | undefined,
+  creator?: SessionCreatorActor,
+): CallerIdentity {
+  const sender = readSenderIdentity(sessionMetadata);
+  if (sender) {
+    return { kind: sender.kind, value: sender.value };
+  }
+
+  const email = creator?.email?.trim();
+  const id = creator?.id?.trim();
+  const value = email || id;
+  if (value) {
+    return { kind: STIGMER_USER_KIND, value };
+  }
+
+  return anonymousCallerIdentity();
+}
+
+/**
+ * Return a NEW env map with the reserved caller-identity keys set —
+ * platform values are authoritative over same-named user entries (the
+ * injectPlatformEnv precedent: a user env var must never be able to
+ * impersonate a caller).
+ *
+ * Call this on the env map handed to MCP resolution ONLY — never on the
+ * map that reaches agent subprocess environments. Per-server opt-in is
+ * enforced downstream by filterEnvToDeclaredKeys.
+ */
+export function injectCallerIdentityEnv(
+  envVars: Record<string, string>,
+  identity: CallerIdentity,
+  sessionId: string,
+): Record<string, string> {
+  const reserved: Record<string, string> = {
+    [CALLER_IDENTITY_KIND_ENV_KEY]: identity.kind,
+    [CALLER_IDENTITY_VALUE_ENV_KEY]: identity.value,
+    [SESSION_ID_ENV_KEY]: sessionId,
+  };
+
+  for (const [key, value] of Object.entries(reserved)) {
+    if (key in envVars && envVars[key] !== value) {
+      console.info(
+        `Platform env var '${key}' overrides value from ExecutionContext ` +
+        `(caller-identity vars are authoritative)`,
+      );
+    }
+  }
+
+  return { ...envVars, ...reserved };
+}
+
+/**
+ * Discovery-context injection: the connect workflow resolves the same
+ * header templates with no session, so every declared reserved key gets
+ * the anonymous sentinel — otherwise a caller-identity-templating server
+ * can never be discovered. Gated on the server's declared keys, matching
+ * injectPlatformEnv's contract in the discovery activity.
+ */
+export function injectAnonymousCallerIdentityForDiscovery(
+  declaredEnvKeys: ReadonlySet<string>,
+  envVars: Record<string, string>,
+): Record<string, string> {
+  const anonymous = anonymousCallerIdentity();
+  const sentinels: Record<string, string> = {
+    [CALLER_IDENTITY_KIND_ENV_KEY]: anonymous.kind,
+    [CALLER_IDENTITY_VALUE_ENV_KEY]: anonymous.value,
+    [SESSION_ID_ENV_KEY]: "",
+  };
+
+  let result: Record<string, string> | undefined;
+  for (const [key, value] of Object.entries(sentinels)) {
+    if (!declaredEnvKeys.has(key)) continue;
+    if (!result) result = { ...envVars };
+    result[key] = value;
+  }
+
+  return result ?? envVars;
+}