@stigmer/runner 3.5.3 → 3.6.0

package/dist/shared/channel-attachment.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The runner-synthesized channel messaging attachment (proactive-messaging
+ * DD-006 D7/D8) — the datastore records attachment's structural twin.
+ *
+ * When the control plane says an agent serves at least one
+ * proactive-messaging channel (the `listMessagingChannels` discovery
+ * read, DD-006 D2 — the SAME candidate computation the send
+ * authorization runs, so attachment and authority cannot disagree), the
+ * runner synthesizes ONE MCP attachment serving `send_channel_message`,
+ * and injects the `<available_channel_templates>` prompt section so the
+ * model composes template sends in context without spending a tool
+ * round (DD-003 D5).
+ *
+ * Two connection shapes, one roster (the records pattern):
+ *   - Bridge endpoint configured (cloud): Streamable HTTP against the
+ *     bridge's /channels route with the execution's own session-scoped
+ *     credential as the Bearer token.
+ *   - No bridge endpoint (OSS/local): a spawned `stigmer mcp-server`
+ *     stdio child with STIGMER_MCP_ROSTER=channels. In practice OSS
+ *     answers the discovery read with an empty list (DD-006 D3), so
+ *     this shape only serves local deployments that grow a messaging
+ *     runtime later — it exists for symmetry with the deployment
+ *     topology, not for a live OSS path today.
+ *
+ * Approval-free by construction, and FORCED, not convenient (DD-002
+ * D6): both calling surfaces run APPROVAL_MODE_UNATTENDED, where a
+ * gated tool resolves as skip-and-adapt — a gated send tool would mean
+ * reminders never send. Empty approval maps + no McpServerUsage keep
+ * the connect backfill structurally unable to gate it (see
+ * synthesized-attachment.ts). Callers inject AFTER resolve + backfill.
+ *
+ * Failure posture (DD-006 D4): every discovery failure — OSS's empty
+ * answer, a registry outage, a control plane predating the RPC
+ * (UNIMPLEMENTED), a reach refusal — degrades to honest absence: no
+ * tool, no section, execution unharmed.
+ */
+import type { ChannelTemplate, MessagingChannel } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/message_io_pb";
+import type { StigmerClient } from "../client/stigmer-client.js";
+import type { ResolvedMcpServer } from "./mcp-resolver.js";
+import { type SynthesizedAttachmentOptions } from "./synthesized-attachment.js";
+/**
+ * The synthesized attachment's slug. Reserved: a user McpServer with
+ * this slug is shadowed by the synthesized attachment, with a warning.
+ * Pinned cross-repo by the mcp-server integration test (the
+ * TOOL_CALL_LIMIT precedent).
+ */
+export declare const CHANNEL_ATTACHMENT_SLUG = "stigmer-channels";
+/** The bridge route serving the channels-only roster (mcp-server DD-006 D8). */
+export declare const CHANNELS_ROUTE = "/channels";
+/**
+ * The most templates the prompt section carries (DD-006 D6): Meta
+ * allows hundreds per WABA, and an unbounded section would tax every
+ * run's context. Deterministic (name, language) order plus a withheld
+ * count keep the agent's behavior independent of registry ordering.
+ */
+export declare const TEMPLATE_SECTION_CAP = 30;
+/** One channel plus its sendable approved templates, ready to format. */
+export interface ChannelMessagingInfo {
+    channel: MessagingChannel;
+    templates: ChannelTemplate[];
+}
+/**
+ * The discovery read plus the per-channel template fetch, with the
+ * DD-006 D4 failure posture applied: this function NEVER throws — any
+ * failure returns an empty list (no tool, no section), because a
+ * messaging hiccup must not fail an execution that may not even want
+ * to send anything.
+ */
+export declare function discoverChannelMessaging(client: StigmerClient, scopedCredential: string | undefined): Promise<ChannelMessagingInfo[]>;
+/**
+ * Synthesize the channel messaging attachment. Returns undefined when
+ * the agent serves no proactive channel — the attachment exists exactly
+ * when the discovery read says so.
+ */
+export declare function synthesizeChannelAttachment(channels: ChannelMessagingInfo[], options: SynthesizedAttachmentOptions): ResolvedMcpServer | undefined;
+/**
+ * The `<available_channel_templates>` prompt section (DD-003 D5):
+ * approved AND sendable templates with their full body text, so the
+ * model fills positional placeholders beside the values it composes.
+ * Unsendable entries are filtered, not annotated (DD-006 D6 — the
+ * console panel is the diagnosis surface, the prompt is a composition
+ * aid). Returns "" when nothing survives the filter — the tool alone
+ * still serves text sends inside a 24-hour window.
+ */
+export declare function formatChannelTemplatesSection(channels: ChannelMessagingInfo[]): string;

package/dist/shared/channel-attachment.js

@@ -0,0 +1,203 @@
+/**
+ * The runner-synthesized channel messaging attachment (proactive-messaging
+ * DD-006 D7/D8) — the datastore records attachment's structural twin.
+ *
+ * When the control plane says an agent serves at least one
+ * proactive-messaging channel (the `listMessagingChannels` discovery
+ * read, DD-006 D2 — the SAME candidate computation the send
+ * authorization runs, so attachment and authority cannot disagree), the
+ * runner synthesizes ONE MCP attachment serving `send_channel_message`,
+ * and injects the `<available_channel_templates>` prompt section so the
+ * model composes template sends in context without spending a tool
+ * round (DD-003 D5).
+ *
+ * Two connection shapes, one roster (the records pattern):
+ *   - Bridge endpoint configured (cloud): Streamable HTTP against the
+ *     bridge's /channels route with the execution's own session-scoped
+ *     credential as the Bearer token.
+ *   - No bridge endpoint (OSS/local): a spawned `stigmer mcp-server`
+ *     stdio child with STIGMER_MCP_ROSTER=channels. In practice OSS
+ *     answers the discovery read with an empty list (DD-006 D3), so
+ *     this shape only serves local deployments that grow a messaging
+ *     runtime later — it exists for symmetry with the deployment
+ *     topology, not for a live OSS path today.
+ *
+ * Approval-free by construction, and FORCED, not convenient (DD-002
+ * D6): both calling surfaces run APPROVAL_MODE_UNATTENDED, where a
+ * gated tool resolves as skip-and-adapt — a gated send tool would mean
+ * reminders never send. Empty approval maps + no McpServerUsage keep
+ * the connect backfill structurally unable to gate it (see
+ * synthesized-attachment.ts). Callers inject AFTER resolve + backfill.
+ *
+ * Failure posture (DD-006 D4): every discovery failure — OSS's empty
+ * answer, a registry outage, a control plane predating the RPC
+ * (UNIMPLEMENTED), a reach refusal — degrades to honest absence: no
+ * tool, no section, execution unharmed.
+ */
+import { Code, ConnectError } from "@connectrpc/connect";
+import { grpcTarget } from "./synthesized-attachment.js";
+/**
+ * The synthesized attachment's slug. Reserved: a user McpServer with
+ * this slug is shadowed by the synthesized attachment, with a warning.
+ * Pinned cross-repo by the mcp-server integration test (the
+ * TOOL_CALL_LIMIT precedent).
+ */
+export const CHANNEL_ATTACHMENT_SLUG = "stigmer-channels";
+/** The bridge route serving the channels-only roster (mcp-server DD-006 D8). */
+export const CHANNELS_ROUTE = "/channels";
+/**
+ * The most templates the prompt section carries (DD-006 D6): Meta
+ * allows hundreds per WABA, and an unbounded section would tax every
+ * run's context. Deterministic (name, language) order plus a withheld
+ * count keep the agent's behavior independent of registry ordering.
+ */
+export const TEMPLATE_SECTION_CAP = 30;
+/**
+ * The discovery read plus the per-channel template fetch, with the
+ * DD-006 D4 failure posture applied: this function NEVER throws — any
+ * failure returns an empty list (no tool, no section), because a
+ * messaging hiccup must not fail an execution that may not even want
+ * to send anything.
+ */
+export async function discoverChannelMessaging(client, scopedCredential) {
+    let channels;
+    try {
+        channels = await client.listMessagingChannels(scopedCredential);
+    }
+    catch (err) {
+        logDiscoveryFailure("listMessagingChannels", err);
+        return [];
+    }
+    if (channels.length === 0) {
+        return [];
+    }
+    // Template reads degrade PER CHANNEL: a registry outage on one
+    // channel must not strip the section for another, and never the tool
+    // (a channel with unreadable templates can still send text inside a
+    // 24-hour window).
+    return Promise.all(channels.map(async (channel) => {
+        try {
+            return {
+                channel,
+                templates: await client.listChannelTemplates(channel.channel, scopedCredential),
+            };
+        }
+        catch (err) {
+            logDiscoveryFailure(`listTemplates(${channel.channel})`, err);
+            return { channel, templates: [] };
+        }
+    }));
+}
+/**
+ * Synthesize the channel messaging attachment. Returns undefined when
+ * the agent serves no proactive channel — the attachment exists exactly
+ * when the discovery read says so.
+ */
+export function synthesizeChannelAttachment(channels, options) {
+    if (channels.length === 0) {
+        return undefined;
+    }
+    // Approval-free by construction + backfill-proof: see file header.
+    const base = {
+        slug: CHANNEL_ATTACHMENT_SLUG,
+        toolApprovals: [],
+        pinnedToolApprovals: [],
+        discoveredCapabilitiesEmpty: false,
+    };
+    if (options.bridgeEndpoint !== null && options.bridgeEndpoint !== "") {
+        return {
+            ...base,
+            connectionType: "http",
+            url: options.bridgeEndpoint.replace(/\/+$/, "") + CHANNELS_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: "channels",
+            STIGMER_SERVER_ADDRESS: grpcTarget(options.backendEndpoint),
+        },
+    };
+}
+/**
+ * The `<available_channel_templates>` prompt section (DD-003 D5):
+ * approved AND sendable templates with their full body text, so the
+ * model fills positional placeholders beside the values it composes.
+ * Unsendable entries are filtered, not annotated (DD-006 D6 — the
+ * console panel is the diagnosis surface, the prompt is a composition
+ * aid). Returns "" when nothing survives the filter — the tool alone
+ * still serves text sends inside a 24-hour window.
+ */
+export function formatChannelTemplatesSection(channels) {
+    let withheld = 0;
+    let budget = TEMPLATE_SECTION_CAP;
+    const channelBlocks = [];
+    for (const { channel, templates } of channels) {
+        // Sendable-only (unsupportedReason empty), deterministic order —
+        // agent behavior must never depend on registry ordering (DD-006 D6).
+        const sendable = templates
+            .filter((t) => t.unsupportedReason === "")
+            .sort((a, b) => a.name.localeCompare(b.name) || a.language.localeCompare(b.language));
+        const kept = sendable.slice(0, Math.max(budget, 0));
+        withheld += sendable.length - kept.length;
+        budget -= kept.length;
+        if (kept.length === 0) {
+            continue;
+        }
+        const lines = kept.map((t) => {
+            const parameters = t.parameterNames.length > 0
+                ? `, parameters: ${t.parameterNames.join(", ")}`
+                : "";
+            const header = t.headerFormat === "IMAGE"
+                ? " (requires header_image_link: a public HTTPS image URL)"
+                : "";
+            return [
+                `  - ${t.name} (${t.language}) [${t.category}]${parameters}${header}`,
+                `    "${t.bodyText}"`,
+            ].join("\n");
+        });
+        channelBlocks.push([`channel: ${channel.channel} (${channel.provider})`, ...lines].join("\n"));
+    }
+    if (channelBlocks.length === 0) {
+        return "";
+    }
+    const footer = withheld > 0
+        ? [`(${withheld} more approved template${withheld === 1 ? "" : "s"} not shown)`]
+        : [];
+    return [
+        "<available_channel_templates>",
+        "You can send business-initiated messages on the channels below with the",
+        "send_channel_message tool. Outside a 24-hour customer-service window the",
+        "provider only accepts a pre-approved template, so prefer a template. Fill",
+        "every placeholder from the conversation; never invent a value.",
+        "",
+        ...channelBlocks,
+        ...footer,
+        "</available_channel_templates>",
+    ].join("\n");
+}
+/**
+ * Expected absences log quietly; anything else warns so an operator can
+ * diagnose a mis-provisioned credential without failing the execution.
+ * UNIMPLEMENTED is a control plane predating the discovery RPC — the
+ * DD-006 D4 deploy-order self-healing case.
+ */
+function logDiscoveryFailure(what, err) {
+    const ce = ConnectError.from(err);
+    const expected = ce.code === Code.Unimplemented ||
+        ce.code === Code.FailedPrecondition ||
+        ce.code === Code.Unavailable;
+    if (expected) {
+        console.debug(`[channel-attachment] ${what} degraded to honest absence: ${ce.message}`);
+    }
+    else {
+        console.warn(`[channel-attachment] ${what} failed unexpectedly (no tool, no section): ${ce.message}`);
+    }
+}
+//# sourceMappingURL=channel-attachment.js.map

package/dist/shared/channel-attachment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-attachment.js","sourceRoot":"","sources":["../../src/shared/channel-attachment.ts"],"names":[],"mappings":"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"}

package/dist/shared/datastore-attachment.d.ts

@@ -32,6 +32,7 @@
  */
 import type { DatastoreUsage } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
 import type { ResolvedMcpServer } from "./mcp-resolver.js";
+import { type SynthesizedAttachmentOptions } from "./synthesized-attachment.js";
 /**
  * The synthesized attachment's slug. Reserved: a user McpServer with
  * this slug is shadowed by the synthesized attachment (the record tools
@@ -40,36 +41,12 @@ import type { ResolvedMcpServer } from "./mcp-resolver.js";
 export declare const DATASTORE_ATTACHMENT_SLUG = "stigmer-records";
 /** The bridge route serving the records-only roster (mcp-server T05 R1). */
 export declare 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 declare function synthesizeDatastoreAttachment(datastoreUsages: DatastoreUsage[], options: DatastoreAttachmentOptions): ResolvedMcpServer | undefined;
-/**
- * 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 declare function injectDatastoreAttachment(resolvedServers: ResolvedMcpServer[], attachment: ResolvedMcpServer): ResolvedMcpServer[];
+export declare function synthesizeDatastoreAttachment(datastoreUsages: DatastoreUsage[], options: SynthesizedAttachmentOptions): ResolvedMcpServer | undefined;
 /**
  * The `<available_datastores>` prompt section (DD-005 SD-5, the
  * skills-section precedent): names the attached datastores and points

package/dist/shared/datastore-attachment.js

@@ -30,6 +30,7 @@
  * is structurally unable to touch it. Callers must still inject AFTER
  * resolve + backfill; both harness call sites do.
  */
+import { grpcTarget } from "./synthesized-attachment.js";
 /**
  * The synthesized attachment's slug. Reserved: a user McpServer with
  * this slug is shadowed by the synthesized attachment (the record tools
@@ -75,22 +76,6 @@ export function synthesizeDatastoreAttachment(datastoreUsages, options) {
         },
     };
 }
-/**
- * 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, attachment) {
-    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
@@ -114,16 +99,4 @@ export function formatDatastoresSection(datastoreUsages) {
         "</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) {
-    try {
-        return new URL(endpoint).host;
-    }
-    catch {
-        return endpoint;
-    }
-}
 //# sourceMappingURL=datastore-attachment.js.map

package/dist/shared/datastore-attachment.js.map

@@ -1 +1 @@
-{"version":3,"file":"datastore-attachment.js","sourceRoot":"","sources":["../../src/shared/datastore-attachment.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"datastore-attachment.js","sourceRoot":"","sources":["../../src/shared/datastore-attachment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAIH,OAAO,EAAE,UAAU,EAAqC,MAAM,6BAA6B,CAAC;AAE5F;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,iBAAiB,CAAC;AAE3D,4EAA4E;AAC5E,MAAM,CAAC,MAAM,aAAa,GAAG,UAAU,CAAC;AAExC;;;;GAIG;AACH,MAAM,UAAU,6BAA6B,CAC3C,eAAiC,EACjC,OAAqC;IAErC,IAAI,eAAe,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjC,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,mEAAmE;IACnE,MAAM,IAAI,GAAG;QACX,IAAI,EAAE,yBAAyB;QAC/B,aAAa,EAAE,EAAE;QACjB,mBAAmB,EAAE,EAAE;QACvB,2BAA2B,EAAE,KAAK;KACnC,CAAC;IAEF,IAAI,OAAO,CAAC,cAAc,KAAK,IAAI,IAAI,OAAO,CAAC,cAAc,KAAK,EAAE,EAAE,CAAC;QACrE,OAAO;YACL,GAAG,IAAI;YACP,cAAc,EAAE,MAAM;YACtB,GAAG,EAAE,OAAO,CAAC,cAAc,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,aAAa;YAC/D,OAAO,EAAE,OAAO,CAAC,UAAU,KAAK,IAAI,IAAI,OAAO,CAAC,UAAU,KAAK,EAAE;gBAC/D,CAAC,CAAC,EAAE,aAAa,EAAE,UAAU,OAAO,CAAC,UAAU,EAAE,EAAE;gBACnD,CAAC,CAAC,SAAS;SACd,CAAC;IACJ,CAAC;IAED,OAAO;QACL,GAAG,IAAI;QACP,cAAc,EAAE,OAAO;QACvB,OAAO,EAAE,SAAS;QAClB,IAAI,EAAE,CAAC,YAAY,CAAC;QACpB,GAAG,EAAE;YACH,kBAAkB,EAAE,SAAS;YAC7B,sBAAsB,EAAE,UAAU,CAAC,OAAO,CAAC,eAAe,CAAC;SAC5D;KACF,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,eAAiC;IACvE,MAAM,KAAK,GAAG,eAAe;SAC1B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,EAAE,IAAI,CAAC;SAChC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;IACjD,OAAO;QACL,wBAAwB;QACxB,sEAAsE;QACtE,kFAAkF;QAClF,6EAA6E;QAC7E,8EAA8E;QAC9E,aAAa;QACb,EAAE;QACF,GAAG,OAAO;QACV,yBAAyB;KAC1B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/shared/synthesized-attachment.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Shared mechanics of runner-synthesized MCP attachments — the pieces
+ * the datastore records attachment (T05) and the channel messaging
+ * attachment (proactive-messaging DD-006 D8) have in common, extracted
+ * when the second attachment arrived.
+ *
+ * A synthesized attachment is a first-party MCP server entry the runner
+ * builds itself (no McpServer resource, no Environment, no credential in
+ * any manifest) on a RESERVED slug. Approval-freedom is structural, not
+ * configured: empty toolApprovals + pinnedToolApprovals mean
+ * mergeApprovalPolicies emits no entries, and discoveredCapabilitiesEmpty
+ * false + no McpServerUsage keep the connect backfill's destructiveHint
+ * tightener structurally unable to touch it. Callers must still inject
+ * AFTER resolve + backfill; every harness call site does.
+ */
+import type { ResolvedMcpServer } from "./mcp-resolver.js";
+/**
+ * Connection options for a synthesized attachment — one shape for every
+ * attachment because the deployment topology, not the domain, decides
+ * the connection.
+ */
+export interface SynthesizedAttachmentOptions {
+    /**
+     * The bridge's HTTP endpoint (STIGMER_MCP_BRIDGE_ENDPOINT, e.g.
+     * https://mcp.stigmer.ai). Null selects the OSS/local 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;
+}
+/**
+ * Inject a synthesized attachment into a resolved server list — AFTER
+ * resolve + backfill (see the module header). A user server shadowing
+ * the reserved slug is replaced, loudly; `label` names the attachment
+ * in that warning (e.g. "datastore records").
+ */
+export declare function injectSynthesizedAttachment(resolvedServers: ResolvedMcpServer[], attachment: ResolvedMcpServer, label: string): ResolvedMcpServer[];
+/**
+ * The gRPC dial target (host:port) for a backend endpoint URL — the
+ * shape STIGMER_SERVER_ADDRESS wants (the bridge warns on schemes).
+ */
+export declare function grpcTarget(endpoint: string): string;

package/dist/shared/synthesized-attachment.js

@@ -0,0 +1,45 @@
+/**
+ * Shared mechanics of runner-synthesized MCP attachments — the pieces
+ * the datastore records attachment (T05) and the channel messaging
+ * attachment (proactive-messaging DD-006 D8) have in common, extracted
+ * when the second attachment arrived.
+ *
+ * A synthesized attachment is a first-party MCP server entry the runner
+ * builds itself (no McpServer resource, no Environment, no credential in
+ * any manifest) on a RESERVED slug. Approval-freedom is structural, not
+ * configured: empty toolApprovals + pinnedToolApprovals mean
+ * mergeApprovalPolicies emits no entries, and discoveredCapabilitiesEmpty
+ * false + no McpServerUsage keep the connect backfill's destructiveHint
+ * tightener structurally unable to touch it. Callers must still inject
+ * AFTER resolve + backfill; every harness call site does.
+ */
+/**
+ * Inject a synthesized attachment into a resolved server list — AFTER
+ * resolve + backfill (see the module header). A user server shadowing
+ * the reserved slug is replaced, loudly; `label` names the attachment
+ * in that warning (e.g. "datastore records").
+ */
+export function injectSynthesizedAttachment(resolvedServers, attachment, label) {
+    const shadowed = resolvedServers.some((s) => s.slug === attachment.slug);
+    if (shadowed) {
+        console.warn(`MCP server slug "${attachment.slug}" is reserved for the ${label} ` +
+            "attachment; the user-defined server is replaced.");
+    }
+    return [
+        ...resolvedServers.filter((s) => s.slug !== attachment.slug),
+        attachment,
+    ];
+}
+/**
+ * The gRPC dial target (host:port) for a backend endpoint URL — the
+ * shape STIGMER_SERVER_ADDRESS wants (the bridge warns on schemes).
+ */
+export function grpcTarget(endpoint) {
+    try {
+        return new URL(endpoint).host;
+    }
+    catch {
+        return endpoint;
+    }
+}
+//# sourceMappingURL=synthesized-attachment.js.map

package/dist/shared/synthesized-attachment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"synthesized-attachment.js","sourceRoot":"","sources":["../../src/shared/synthesized-attachment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AA4BH;;;;;GAKG;AACH,MAAM,UAAU,2BAA2B,CACzC,eAAoC,EACpC,UAA6B,EAC7B,KAAa;IAEb,MAAM,QAAQ,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC,IAAI,CAAC,CAAC;IACzE,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,CAAC,IAAI,CACV,oBAAoB,UAAU,CAAC,IAAI,yBAAyB,KAAK,GAAG;YACpE,kDAAkD,CACnD,CAAC;IACJ,CAAC;IACD,OAAO;QACL,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC,IAAI,CAAC;QAC5D,UAAU;KACX,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,QAAgB;IACzC,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAC;IAClB,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigmer/runner",
-  "version": "3.5.3",
+  "version": "3.6.0",
   "description": "Embeddable Temporal worker for the Stigmer AI agent platform — handles agent execution, workflow orchestration, and MCP server management",
   "license": "Apache-2.0",
   "type": "module",
@@ -85,7 +85,7 @@
     "@opentelemetry/sdk-metrics": "^2.0.0",
     "@opentelemetry/sdk-trace-base": "^2.0.0",
     "@opentelemetry/sdk-trace-node": "^2.0.0",
-    "@stigmer/protos": "3.5.3",
+    "@stigmer/protos": "3.6.0",
     "@temporalio/activity": "^1.11.0",
     "@temporalio/client": "^1.11.0",
     "@temporalio/common": "^1.11.0",

package/src/__test-utils__/mock-client.ts

@@ -26,6 +26,10 @@ export function mockStigmerClient(overrides: MockMethods = {}): StigmerClient {
     getRunnerScopedToken: vi.fn().mockResolvedValue(undefined),
     getSession: vi.fn().mockResolvedValue({}),
     updateSession: vi.fn().mockResolvedValue({}),
+    // No proactive channels by default — the everyday answer for most
+    // agents (DD-006 D2); tests opt in to a channel-bound agent.
+    listMessagingChannels: vi.fn().mockResolvedValue([]),
+    listChannelTemplates: vi.fn().mockResolvedValue([]),
     getAgent: vi.fn().mockResolvedValue({}),
     getAgentInstance: vi.fn().mockResolvedValue({}),
     getMcpServer: vi.fn().mockResolvedValue({}),

package/src/activities/__tests__/discover-mcp-server.test.ts

@@ -411,6 +411,55 @@ describe("DiscoverMcpServer activity", () => {
       expect(mockClient.getExecutionContextByExecutionId).toHaveBeenCalledWith("ctx-abc");
     });
 
+    it("discovers a caller-identity-templating server via the anonymous sentinel", async () => {
+      // Discovery has no session, so declared STIGMER_CALLER_IDENTITY_*
+      // placeholders resolve to the anonymous sentinel instead of failing
+      // with PlaceholderResolutionError — the failure mode that would
+      // leave an identity-consuming server's tools permanently
+      // unclassified. The server sees an anonymous caller and must answer
+      // tools/list (its authz layer refuses tool CALLS, not discovery).
+      const { discoverMcpServer } = await import("../discover-mcp-server.js");
+      const { MultiServerMCPClient } = await import("@langchain/mcp-adapters");
+
+      const spec = makeHttpSpec("https://isc-mcp.example.com/mcp");
+      spec.serverType.value.headers = {
+        "X-Stigmer-Caller-Kind": "${STIGMER_CALLER_IDENTITY_KIND}",
+        "X-Stigmer-Caller-Value": "${STIGMER_CALLER_IDENTITY_VALUE}",
+        Authorization: "Bearer ${ISC_SHARED_SECRET}",
+      };
+      spec.env = {
+        STIGMER_CALLER_IDENTITY_KIND: { optional: true },
+        STIGMER_CALLER_IDENTITY_VALUE: { optional: true },
+        ISC_SHARED_SECRET: { isSecret: true },
+      };
+
+      const mockClient = makeMockStigmerClient({
+        mcpServer: makeMcpServer({ metadata: { slug: "isc-gym" }, spec }),
+        executionContext: {
+          spec: { data: { ISC_SHARED_SECRET: { value: "s3cret", isSecret: true } } },
+        },
+      });
+
+      const mockMcpClient = makeMockMcpClient({
+        tools: [{ name: "get_gym_info", description: "Public info", inputSchema: { type: "object" } }],
+      });
+      mockInitializeConnections.mockResolvedValue({});
+      mockGetClient.mockResolvedValue(mockMcpClient);
+
+      const result = await discoverMcpServer(
+        { mcpServerId: "mcp-isc", executionContextId: "ctx-isc" },
+        { stigmerClient: mockClient as any, transportPosture: "stdio-forbidden" },
+      );
+
+      expect(result.tools).toHaveLength(1);
+      const connectionConfig = vi.mocked(MultiServerMCPClient).mock.calls[0][0] as any;
+      expect(connectionConfig["isc-gym"].headers).toEqual({
+        "X-Stigmer-Caller-Kind": "anonymous",
+        "X-Stigmer-Caller-Value": "",
+        Authorization: "Bearer s3cret",
+      });
+    });
+
     it("returns empty env when no executionContextId provided", async () => {
       const { discoverMcpServer } = await import("../discover-mcp-server.js");
 

package/src/activities/discover-mcp-server.ts

@@ -30,6 +30,7 @@ import {
   type McpTransportPosture,
 } from "../shared/mcp-transport-guard.js";
 import { detectOAuthChallenge } from "../shared/mcp-oauth-detect.js";
+import { injectAnonymousCallerIdentityForDiscovery } from "../shared/caller-identity.js";
 import { withTimeout } from "../shared/with-timeout.js";
 import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
 import type { Config } from "../config.js";
@@ -249,7 +250,18 @@ export async function discoverMcpServer(
   const declaredEnvKeys = mcpServer.spec.env
     ? new Set(Object.keys(mcpServer.spec.env))
     : new Set<string>();
-  const finalEnv = injectPlatformEnv(declaredEnvKeys, envVars);
+  const platformEnv = injectPlatformEnv(declaredEnvKeys, envVars);
+
+  // Discovery runs with no session, so every declared caller-identity key
+  // resolves to the anonymous sentinel — without it, a server templating
+  // ${STIGMER_CALLER_IDENTITY_VALUE} in its headers would fail discovery
+  // with PlaceholderResolutionError and its tools would never be
+  // classified. Servers consuming these keys answer tools/list to
+  // anonymous callers by contract.
+  const finalEnv = injectAnonymousCallerIdentityForDiscovery(
+    declaredEnvKeys,
+    platformEnv,
+  );
 
   const resolved = mcpServerToResolved(mcpServer, slug, finalEnv);
   if (!resolved) {