@stigmer/runner 3.5.3 → 3.7.0

package/src/sandbox-token-renewal.ts

@@ -0,0 +1,212 @@
+/**
+ * Self-renewal of a cloud sandbox's control-plane credential (STIGMER_TOKEN).
+ *
+ * A sandbox token is minted with a fixed TTL, but the sandbox it serves has
+ * no fixed lifetime: an active conversation extends a session sandbox
+ * indefinitely, and a long workflow run can outlast any TTL chosen at
+ * provisioning. Before this module, the only refresh path was the control
+ * plane's Secret-rewrite + pod restart — which the 2026-08-05 incident
+ * showed both sacrifices the turn that trips it (the old pod picks up the
+ * work holding the dead env token) and wipes an ephemeral sandbox's
+ * workspace. Renewal decouples credential lifetime from sandbox lifetime:
+ * the runner re-mints in-process before expiry via the getRunnerScopedToken
+ * `renewal` arm, and the server bounds renewability by the live sandbox
+ * record (a reaped sandbox's credential dies with it).
+ *
+ * Relationship to {@link createRunnerTokenCoordinator}
+ * (runner-token-coordinator.ts): the coordinator owns the PROXY credential
+ * (x-stigmer-auth) and re-mints it using the control-plane token; this
+ * module keeps that control-plane token itself fresh, so the two form one
+ * chain with no expiring root. They stay separate modules because their
+ * hosts differ — every proxy-mode runner has a coordinator, but only
+ * in-cluster sandbox runners (static cloud sandboxes and pool members) hold
+ * a renewable credential; the desktop's control-plane token is the user's
+ * own Auth0 token, refreshed by the host app.
+ *
+ * The loop re-reads the CURRENT token every cycle rather than binding to
+ * the boot credential, because the credential's class can change under it:
+ * a pool member boots with a non-renewable pool_sandbox token and swaps to
+ * a renewable session token at claim time (attach-session.ts). A
+ * non-renewable token parks the loop on a slow recheck instead of stopping
+ * it, so the swap is picked up without any coupling to the claim path.
+ */
+
+/**
+ * Renew once the token has lived this fraction of its issued lifetime
+ * (anchored on iat/exp, the coordinator's 0.8 convention). Anchoring on the
+ * ISSUED lifetime matters: a fraction of the *remaining* lifetime re-arms at
+ * 80% of an ever-shrinking remainder and never reaches the renewal point.
+ */
+const RENEW_AT_LIFETIME_FRACTION = 0.8;
+
+/**
+ * Fallback safety margin before expiry for a token without an iat claim:
+ * renew this early, leaving room for two retry cycles.
+ */
+const FALLBACK_RENEW_MARGIN_MS = 10 * 60_000;
+
+/** Retry delay after a failed renewal — short enough to recover well before expiry. */
+const RETRY_DELAY_MS = 60_000;
+
+/** Recheck cadence while the current token is not a renewable class (pre-claim pool member). */
+const RECHECK_DELAY_MS = 60_000;
+
+/** Floor for any scheduled delay so a malformed expiry cannot spin a hot loop. */
+const MIN_DELAY_MS = 5_000;
+
+/** The token_type claims the renewal arm accepts (mirrors the server's gate). */
+const RENEWABLE_TOKEN_TYPES = new Set(["sandbox", "workflow_sandbox"]);
+
+export interface SandboxTokenRenewalOptions {
+  /** Reads the credential currently in effect (re-read every cycle; see module doc). */
+  readonly getToken: () => string | null | undefined;
+  /**
+   * Calls the getRunnerScopedToken `renewal` arm authenticated with
+   * {@code currentToken}. Returns undefined when the server minted nothing;
+   * the loop retries rather than crashing the runner.
+   */
+  readonly renew: (currentToken: string) => Promise<
+    { token: string; expiresInSeconds?: number } | undefined
+  >;
+  /** Applies a freshly minted credential to every sink the host wires (ref, env, interceptors). */
+  readonly applyToken: (token: string) => void;
+  /** Optional structured logger; defaults to console. */
+  readonly log?: Pick<typeof console, "log" | "warn">;
+}
+
+export interface SandboxTokenRenewal {
+  /** Stop the renewal timer. Idempotent. */
+  stop(): void;
+}
+
+/**
+ * Whether a token's decoded claims mark it as renewable through the
+ * `renewal` arm. Exported so a static-mode host can decide not to start
+ * the loop at all for a credential whose class can never change.
+ */
+export function isRenewableSandboxToken(token: string | null | undefined): boolean {
+  const claims = decodeClaims(token);
+  return claims !== null
+    && RENEWABLE_TOKEN_TYPES.has(claims.tokenType ?? "")
+    && claims.expMs !== null;
+}
+
+/**
+ * Start the renewal loop. The first cycle runs immediately (it only reads
+ * the token and schedules; no network call unless the credential is already
+ * past its renewal point).
+ */
+export function startSandboxTokenRenewal(
+  options: SandboxTokenRenewalOptions,
+): SandboxTokenRenewal {
+  const log = options.log ?? console;
+  let stopped = false;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+
+  const schedule = (delayMs: number): void => {
+    if (stopped) {
+      return;
+    }
+    timer = setTimeout(() => {
+      void cycle();
+    }, Math.max(MIN_DELAY_MS, delayMs));
+    // Never keep the process alive solely for a token renewal.
+    timer.unref?.();
+  };
+
+  const cycle = async (): Promise<void> => {
+    if (stopped) {
+      return;
+    }
+    const token = options.getToken() ?? null;
+    const claims = decodeClaims(token);
+
+    if (token === null || claims === null
+        || !RENEWABLE_TOKEN_TYPES.has(claims.tokenType ?? "")) {
+      // Not (yet) a renewable credential — a pre-claim pool member, or a
+      // credential class this loop does not own. Park and look again.
+      schedule(RECHECK_DELAY_MS);
+      return;
+    }
+
+    if (claims.expMs === null) {
+      // A renewable-class token without an expiry is a mint-side anomaly;
+      // renewing "before expiry" is undefined, so park rather than spin.
+      log.warn("[sandbox-token-renewal] Credential carries no exp claim; parking");
+      schedule(RECHECK_DELAY_MS);
+      return;
+    }
+
+    const renewAtMs = claims.iatMs !== null
+      ? claims.iatMs + (claims.expMs - claims.iatMs) * RENEW_AT_LIFETIME_FRACTION
+      : claims.expMs - FALLBACK_RENEW_MARGIN_MS;
+    const delayMs = renewAtMs - Date.now();
+    if (delayMs > MIN_DELAY_MS) {
+      schedule(delayMs);
+      return;
+    }
+
+    // At or past the renewal point (possibly past expiry after a long pod
+    // pause — the attempt is still correct: the server decides).
+    try {
+      const renewed = await options.renew(token);
+      if (renewed) {
+        options.applyToken(renewed.token);
+        log.log("[sandbox-token-renewal] Sandbox credential renewed");
+        // Recompute from the fresh token (its own exp is authoritative).
+        schedule(MIN_DELAY_MS);
+      } else {
+        log.warn("[sandbox-token-renewal] Server minted no renewal; will retry");
+        schedule(RETRY_DELAY_MS);
+      }
+    } catch (err) {
+      log.warn(
+        "[sandbox-token-renewal] Renewal failed; will retry: " +
+        `${err instanceof Error ? err.message : err}`,
+      );
+      schedule(RETRY_DELAY_MS);
+    }
+  };
+
+  void cycle();
+
+  return {
+    stop(): void {
+      stopped = true;
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+    },
+  };
+}
+
+/**
+ * Decode the claims this module reads (token_type, iat, exp) from an
+ * unverified JWT. Decode-only on purpose: this is the runner's OWN
+ * credential, minted by the server it will present it back to —
+ * verification happens there.
+ */
+function decodeClaims(
+  token: string | null | undefined,
+): { tokenType: string | undefined; iatMs: number | null; expMs: number | null } | null {
+  if (!token) {
+    return null;
+  }
+  const parts = token.split(".");
+  if (parts.length !== 3) {
+    return null;
+  }
+  try {
+    const payload = JSON.parse(
+      Buffer.from(parts[1], "base64url").toString("utf-8"),
+    ) as { token_type?: string; iat?: number; exp?: number };
+    return {
+      tokenType: payload.token_type,
+      iatMs: typeof payload.iat === "number" ? payload.iat * 1000 : null,
+      expMs: typeof payload.exp === "number" ? payload.exp * 1000 : null,
+    };
+  } catch {
+    return null;
+  }
+}

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

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");