@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/dist/shared/mcp-tool-listing.js

@@ -0,0 +1,166 @@
+/**
+ * Lists the tools an MCP server offers now, with the one mark the approval
+ * default reads: whether the tool's own MCP annotation says
+ * `destructiveHint: true`. Nothing is stored; every listing asks the server.
+ *
+ * Two readers: a tools listing a person asks for from a plugin's page
+ * (activities/list-plugin-tools.ts, the connect workflow's one step), and
+ * the start of a turn on an engine that does not bind the tools itself (the
+ * Cursor engine's tools are loaded by its SDK, not by this runner), whose
+ * approval default needs the marks before the turn runs
+ * ({@link listTurnTools}). The native engine reads the same marks from the
+ * tools it loads, so it never lists twice.
+ *
+ * Annotations are untrusted (the MCP spec says so), so they are read only in
+ * the direction that adds a question: `readOnlyHint` is never read, and a
+ * tool marked both read-only and destructive asks. MCP's own default for an
+ * unannotated tool is "destructive"; Stigmer acts only on an explicit true,
+ * so a server that annotates nothing gates nothing. A server whose listing
+ * fails asks before every one of its tools (`McpToolListing.unlisted`): an
+ * unread mark never means "ask nothing".
+ *
+ * Bounds (issue #239): a remote endpoint that accepts a connection but never
+ * completes the handshake would otherwise hang forever, so HTTP servers get
+ * a short init bound and stdio servers a generous one, because a first run
+ * may compile or install packages (issue #243). A local program is started
+ * as the agent user on a separating runner (`stdioAsAgent`): its command is
+ * the plugin's, and must never run with the runner's rights.
+ */
+import { MultiServerMCPClient } from "@langchain/mcp-adapters";
+import { agentIdentity, setprivArgs } from "./agent-identity.js";
+import { toMcpClientConfig } from "./mcp-manager.js";
+import { detectOAuthChallenge } from "./mcp-oauth-detect.js";
+import { withTimeout } from "./with-timeout.js";
+const HTTP_INIT_TIMEOUT_MS = 30_000;
+const STDIO_INIT_TIMEOUT_MS = 270_000;
+/** The most pages of tools one listing reads before it gives up: a server that never stops paging asks for every tool. */
+const MAX_LIST_PAGES = 100;
+/** The session-init bound for a server's transport. */
+export function initTimeoutMsFor(connectionType) {
+    return connectionType === "stdio" ? STDIO_INIT_TIMEOUT_MS : HTTP_INIT_TIMEOUT_MS;
+}
+/**
+ * The user-facing message for a session-init timeout. Names the endpoint (or
+ * command) so the failure is diagnosable from the message alone, and explains
+ * the known silent-hang shape for HTTP endpoints — issue #239's mechanism.
+ */
+export function initTimeoutMessageFor(slug, resolved) {
+    const seconds = Math.round(initTimeoutMsFor(resolved.connectionType) / 1000);
+    if (resolved.connectionType === "stdio") {
+        return (`MCP server '${slug}' (command: ${resolved.command}) did not complete ` +
+            `MCP initialization within ${seconds}s. If this server requires ` +
+            `compilation or package installation on first run (e.g. go run, npx), ` +
+            `the cold start may have exceeded the listing's timeout.`);
+    }
+    return (`MCP server '${slug}' at ${resolved.url} did not complete MCP ` +
+        `initialization within ${seconds}s. The endpoint accepted the connection ` +
+        `but never finished the handshake — commonly an endpoint that rejects ` +
+        `streamable HTTP while leaving its SSE fallback stream silently open. ` +
+        `Verify the URL points at a live streamable-HTTP MCP endpoint.`);
+}
+/**
+ * A stdio server's connection rewritten to start as the agent user through
+ * `setpriv`, with the agent's home as `HOME`, on a separating runner
+ * (`shared/agent-identity.ts`). An HTTP server, and every server on a runner
+ * that does not separate, is unchanged.
+ */
+export function stdioAsAgent(config, identity = agentIdentity()) {
+    if (identity === null)
+        return config;
+    const out = {};
+    for (const [slug, connection] of Object.entries(config)) {
+        out[slug] =
+            connection.transport === "stdio"
+                ? {
+                    ...connection,
+                    command: "setpriv",
+                    args: [...setprivArgs(identity), "--", connection.command, ...(connection.args ?? [])],
+                    env: { ...connection.env, HOME: identity.home },
+                }
+                : connection;
+    }
+    return out;
+}
+/**
+ * Connects to one resolved server and lists its tools. Throws the server's
+ * failure; an HTTP server asking for a sign-in is re-probed once so the
+ * failure says so instead of the MCP client's opaque aggregate.
+ */
+export async function listServerTools(server) {
+    const slug = server.slug;
+    const connectionConfig = stdioAsAgent(toMcpClientConfig([server]));
+    const client = new MultiServerMCPClient(connectionConfig);
+    const tools = [];
+    try {
+        await withTimeout(initTimeoutMsFor(server.connectionType), () => initTimeoutMessageFor(slug, server), async () => {
+            await client.initializeConnections();
+            const mcpClient = await client.getClient(slug);
+            if (!mcpClient) {
+                throw new Error(`Failed to get MCP client for server '${slug}' after initialization`);
+            }
+            // Every page the server answers: a destructive tool on a later page
+            // must ask as one on the first does. The native engine's loader
+            // follows the cursor the same way.
+            let cursor;
+            let pages = 0;
+            do {
+                const listed = await mcpClient.listTools(cursor === undefined ? undefined : { cursor });
+                for (const tool of listed.tools) {
+                    tools.push({
+                        name: tool.name,
+                        description: tool.description ?? "",
+                        destructive: tool.annotations?.destructiveHint === true,
+                    });
+                }
+                cursor = listed.nextCursor;
+                pages += 1;
+                if (cursor !== undefined && pages >= MAX_LIST_PAGES) {
+                    throw new Error(`MCP server '${slug}' answered more than ${MAX_LIST_PAGES} pages of tools`);
+                }
+            } while (cursor !== undefined);
+        });
+    }
+    catch (err) {
+        const connection = connectionConfig[slug];
+        if (connection !== undefined && connection.transport === "http" && connection.url) {
+            const oauthError = await detectOAuthChallenge(connection.url, connection.headers, slug);
+            if (oauthError)
+                throw oauthError;
+        }
+        throw err;
+    }
+    finally {
+        await client.close().catch((err) => {
+            console.warn(`[mcp-tool-listing] Error closing MCP client for '${slug}': ${err instanceof Error ? err.message : err}`);
+        });
+    }
+    return tools;
+}
+/**
+ * Lists every server of a turn in parallel, the agent's own and its
+ * plugins', for an engine that does not bind the tools itself, so a tool
+ * either marks destructive asks first whichever kind of server holds it.
+ * The platform's own servers are never listed:
+ * none of their tools asks. A server whose listing fails is named in
+ * `unlisted`, with the reason logged.
+ */
+export async function listTurnTools(servers, list = listServerTools) {
+    const listed = await Promise.all(servers
+        .filter((server) => server.home.kind !== "platform")
+        .map(async (server) => {
+        try {
+            return { server: server.slug, tools: await list(server) };
+        }
+        catch (err) {
+            console.warn(`[mcp-tool-listing] The tools of MCP server '${server.slug}' could not be listed, so every one of them asks first this turn: ` +
+                `${err instanceof Error ? err.message : String(err)}`);
+            return { server: server.slug, tools: undefined };
+        }
+    }));
+    return {
+        listed: listed.flatMap(({ server, tools }) => tools === undefined ? [] : [{ server, tools: tools.map((tool) => tool.name) }]),
+        destructive: listed.flatMap(({ server, tools }) => (tools ?? []).filter((tool) => tool.destructive).map((tool) => ({ server, tool: tool.name }))),
+        unlisted: listed.filter(({ tools }) => tools === undefined).map(({ server }) => server),
+    };
+}
+//# sourceMappingURL=mcp-tool-listing.js.map

package/dist/shared/mcp-tool-listing.js.map

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

package/dist/shared/mcp-transport-guard.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Transport guard for MCP servers — stdio is local-runner-only.
+ *
+ * Why this is load-bearing: a stdio MCP server means "download a package
+ * from a public registry at session start and run it as a subprocess with
+ * the execution's secrets in its environment". On a local runner that
+ * machine belongs to the user — their trust decision. On a managed cloud
+ * runner it is a supply-chain exposure the platform owns, so hosted
+ * execution is HTTP-only. The control plane refuses such executions at
+ * create time (stigmer-cloud's McpTransportPolicy); this guard is the
+ * defense-in-depth backstop at the moment a subprocess would actually be
+ * spawned — it must hold even if a stdio usage reaches a cloud runner
+ * through a path the control plane did not see.
+ *
+ * The posture derives from Config.mode ("cloud" → forbid stdio), NOT from
+ * cloudModeEnabled — that is the Cursor cloud-agent feature flag and says
+ * nothing about where this process runs. STIGMER_MCP_ALLOW_STDIO exists as
+ * an explicit override so operators can roll the policy back without a
+ * redeploy (the runner-side counterpart of the control plane's
+ * stigmer.mcp.stdio-cloud-block kill-switch). Managed cloud deployments
+ * never set it.
+ *
+ * A rejection is thrown as {@link McpTransportError} and must FAIL the
+ * execution loudly: the resolvers' per-server catch blocks swallow
+ * resolution failures into console.warn and continue, which would turn a
+ * policy rejection into an agent silently losing tools. Both resolvers
+ * rethrow this error type for exactly that reason.
+ *
+ * Mirrors the posture/override/error shape of tools/url-guard.ts (the
+ * web_fetch SSRF boundary), the runner's established idiom for
+ * mode-keyed guards.
+ */
+export type McpTransportPosture = "stdio-allowed" | "stdio-forbidden";
+/** Thrown for every guard rejection; message is safe to surface to the user. */
+export declare class McpTransportError extends Error {
+    constructor(message: string);
+}
+/**
+ * Derive the transport posture from runner mode plus the explicit override.
+ *
+ * @param mode Config.mode — "cloud" means a managed runner on shared infrastructure.
+ * @param env  Environment to read STIGMER_MCP_ALLOW_STDIO from.
+ */
+export declare function resolveMcpTransportPosture(mode: "local" | "cloud", env?: NodeJS.ProcessEnv): McpTransportPosture;
+/**
+ * Assert that a resolved MCP server's transport is allowed under the given
+ * posture. Applies only to the servers plugins bring, flowing through the
+ * resolvers — the internal synthesized attachments are built
+ * separately and are already HTTP in cloud mode.
+ *
+ * @throws McpTransportError when the posture forbids stdio and the server uses it
+ */
+export declare function assertTransportAllowed(slug: string, connectionType: "stdio" | "http" | "sse", posture: McpTransportPosture): void;

package/dist/shared/mcp-transport-guard.js

@@ -0,0 +1,70 @@
+/**
+ * Transport guard for MCP servers — stdio is local-runner-only.
+ *
+ * Why this is load-bearing: a stdio MCP server means "download a package
+ * from a public registry at session start and run it as a subprocess with
+ * the execution's secrets in its environment". On a local runner that
+ * machine belongs to the user — their trust decision. On a managed cloud
+ * runner it is a supply-chain exposure the platform owns, so hosted
+ * execution is HTTP-only. The control plane refuses such executions at
+ * create time (stigmer-cloud's McpTransportPolicy); this guard is the
+ * defense-in-depth backstop at the moment a subprocess would actually be
+ * spawned — it must hold even if a stdio usage reaches a cloud runner
+ * through a path the control plane did not see.
+ *
+ * The posture derives from Config.mode ("cloud" → forbid stdio), NOT from
+ * cloudModeEnabled — that is the Cursor cloud-agent feature flag and says
+ * nothing about where this process runs. STIGMER_MCP_ALLOW_STDIO exists as
+ * an explicit override so operators can roll the policy back without a
+ * redeploy (the runner-side counterpart of the control plane's
+ * stigmer.mcp.stdio-cloud-block kill-switch). Managed cloud deployments
+ * never set it.
+ *
+ * A rejection is thrown as {@link McpTransportError} and must FAIL the
+ * execution loudly: the resolvers' per-server catch blocks swallow
+ * resolution failures into console.warn and continue, which would turn a
+ * policy rejection into an agent silently losing tools. Both resolvers
+ * rethrow this error type for exactly that reason.
+ *
+ * Mirrors the posture/override/error shape of tools/url-guard.ts (the
+ * web_fetch SSRF boundary), the runner's established idiom for
+ * mode-keyed guards.
+ */
+/** Thrown for every guard rejection; message is safe to surface to the user. */
+export class McpTransportError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "McpTransportError";
+    }
+}
+/**
+ * Derive the transport posture from runner mode plus the explicit override.
+ *
+ * @param mode Config.mode — "cloud" means a managed runner on shared infrastructure.
+ * @param env  Environment to read STIGMER_MCP_ALLOW_STDIO from.
+ */
+export function resolveMcpTransportPosture(mode, env = process.env) {
+    const override = env.STIGMER_MCP_ALLOW_STDIO;
+    if (override === "true")
+        return "stdio-allowed";
+    if (override === "false")
+        return "stdio-forbidden";
+    return mode === "cloud" ? "stdio-forbidden" : "stdio-allowed";
+}
+/**
+ * Assert that a resolved MCP server's transport is allowed under the given
+ * posture. Applies only to the servers plugins bring, flowing through the
+ * resolvers — the internal synthesized attachments are built
+ * separately and are already HTTP in cloud mode.
+ *
+ * @throws McpTransportError when the posture forbids stdio and the server uses it
+ */
+export function assertTransportAllowed(slug, connectionType, posture) {
+    if (posture === "stdio-forbidden" && connectionType === "stdio") {
+        throw new McpTransportError(`MCP server '${slug}' uses the stdio transport, which runs only on local ` +
+            `runners — this cloud runner refuses to spawn it. Run the session on a ` +
+            `local runner (session execution_target: local), or replace '${slug}' ` +
+            `with a remote (HTTP) MCP server.`);
+    }
+}
+//# sourceMappingURL=mcp-transport-guard.js.map

package/dist/shared/mcp-transport-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-transport-guard.js","sourceRoot":"","sources":["../../src/shared/mcp-transport-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAIH,gFAAgF;AAChF,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,UAAU,0BAA0B,CACxC,IAAuB,EACvB,MAAyB,OAAO,CAAC,GAAG;IAEpC,MAAM,QAAQ,GAAG,GAAG,CAAC,uBAAuB,CAAC;IAC7C,IAAI,QAAQ,KAAK,MAAM;QAAE,OAAO,eAAe,CAAC;IAChD,IAAI,QAAQ,KAAK,OAAO;QAAE,OAAO,iBAAiB,CAAC;IACnD,OAAO,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,eAAe,CAAC;AAChE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CACpC,IAAY,EACZ,cAAwC,EACxC,OAA4B;IAE5B,IAAI,OAAO,KAAK,iBAAiB,IAAI,cAAc,KAAK,OAAO,EAAE,CAAC;QAChE,MAAM,IAAI,iBAAiB,CACzB,eAAe,IAAI,uDAAuD;YAC1E,wEAAwE;YACxE,+DAA+D,IAAI,IAAI;YACvE,kCAAkC,CACnC,CAAC;IACJ,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,103 @@
+/**
+ * The runner-synthesized memory capture attachment.
+ *
+ * When the execution's recall snapshot says memory is on
+ * (`status.recalled_memories.enabled` — the ONE server-owned field that
+ * serves both the recall and capture sides, stamped by the create
+ * pipeline's compose step), the runner synthesizes ONE MCP attachment
+ * serving the `remember` tool. No discovery RPC exists on this path:
+ * unlike the channel attachment's registry read, the enablement answer
+ * is already on the spec — a free, synchronous read (the
+ * conversation-attachment session-label precedent). The enabled bit with
+ * ZERO facts is a meaningful state: memory is on, nothing stored yet —
+ * the tool is offered so the first fact can be proposed.
+ *
+ * Two connection shapes, one roster (the channels pattern), one
+ * credential — the run's own — presented on both:
+ *   - Bridge endpoint configured (cloud): Streamable HTTP against the
+ *     bridge's /memory route with the run's credential as the Bearer
+ *     token, plus the capture context as per-request headers.
+ *   - No bridge endpoint (OSS/local): a spawned `stigmer mcp-server`
+ *     stdio child with STIGMER_MCP_ROSTER=memory, the run's credential
+ *     as its startup credential (synthesized-attachment.ts
+ *     `stdioCredentialEnv`), plus the capture context as
+ *     STIGMER_MEMORY_* env. Without the credential a server that signs
+ *     people in refuses every `remember` as nobody's (stigmer#1147);
+ *     with it the memory is the run's person's, which the server derives
+ *     from the credential and nothing the child says.
+ *
+ * The capture context (org + agent/session/execution ids) is
+ * attribution, never authorization (since 2026-08-22): the cloud create
+ * handler accepts it only
+ * from a session-sandbox credential and overrides session/org with the
+ * token's own claims; the OSS server under sign-in admits it from the
+ * run's credential and proves the session off the run's row, and stores
+ * it as given under the local single-user trust model. The subject is
+ * never threaded — the server derives it from the credential.
+ *
+ * Approval-free by construction (the synthesized-attachment contract):
+ * the tool only ever creates a PROPOSAL the user must confirm through
+ * the control plane, so gating the propose call would stack a second
+ * consent gate in front of the real one (consent is the
+ * confirm RPC, not tool approval). Callers inject AFTER resolve.
+ *
+ * Failure posture: the attachment is synthesized from values already in
+ * hand, so the only failure mode is the create RPC refusing at call
+ * time — which the mcp-server's memory error mapper relays honestly.
+ * When the snapshot is absent or disabled: no tool, honest absence.
+ */
+import type { RecalledMemories } from "@stigmer/apis/ai/stigmer/agentic/run/v1/spec_pb";
+import type { ResolvedMcpServer } from "./mcp-resolver.js";
+import { type SynthesizedAttachmentOptions } from "./synthesized-attachment.js";
+/**
+ * The synthesized attachment's slug. Reserved: no plugin server is named
+ * like it (theirs start `plugin_`), and one that were would be shadowed by
+ * the synthesized attachment, with a warning.
+ * Runner-internal (the resolved-server name and shadow key — the
+ * mcp-server never sees it); pinned by this module's test. The ROUTE
+ * and the context keys below are cross-repo strings, pinned on both
+ * sides (the TOOL_CALL_LIMIT precedent).
+ */
+export declare const MEMORY_ATTACHMENT_SLUG = "stigmer-memory";
+/** The bridge route serving the memory-only roster (mcp-server twin: MEMORY_ROUTE). */
+export declare const MEMORY_ROUTE = "/memory";
+/**
+ * The capture-context carriers, mirrored byte-for-byte by the
+ * mcp-server's memory domain (domains/memory/context.ts): headers on
+ * the bridge's per-request path, env on the stdio child — the same
+ * per-request-then-startup split the credential itself uses.
+ */
+export declare const MEMORY_ORG_HEADER = "x-stigmer-memory-org";
+export declare const MEMORY_AGENT_ID_HEADER = "x-stigmer-memory-agent-id";
+export declare const MEMORY_SESSION_ID_HEADER = "x-stigmer-memory-session-id";
+export declare const MEMORY_EXECUTION_ID_HEADER = "x-stigmer-memory-execution-id";
+export declare const MEMORY_ORG_ENV = "STIGMER_MEMORY_ORG";
+export declare const MEMORY_AGENT_ID_ENV = "STIGMER_MEMORY_AGENT_ID";
+export declare const MEMORY_SESSION_ID_ENV = "STIGMER_MEMORY_SESSION_ID";
+export declare const MEMORY_EXECUTION_ID_ENV = "STIGMER_MEMORY_EXECUTION_ID";
+/**
+ * Where a proposed memory comes from — threaded to the mcp-server so
+ * the create request carries org addressing and provenance. Empty
+ * fields are omitted from the carrier (best-effort attribution; the
+ * server treats absent as empty).
+ */
+export interface MemoryCaptureContext {
+    readonly org: string;
+    readonly agentId: string;
+    readonly sessionId: string;
+    readonly agentExecutionId: string;
+}
+/**
+ * Reports whether the execution's recall snapshot offers the remember
+ * tool (the snapshot's enabled bit IS the runner's injection
+ * signal — one server-owned field, no parallel flag, no discovery
+ * round-trip). Exposed for the harnesses' MCP gates, which must open
+ * MCP resolution for a memory-only agent.
+ */
+export declare function memoryCaptureEnabled(recalled: RecalledMemories | undefined): boolean;
+/**
+ * Synthesize the memory capture attachment. Returns undefined when the
+ * recall snapshot is absent or disabled — the attachment exists exactly
+ * when the server-composed snapshot says memory is on.
+ */
+export declare function synthesizeMemoryAttachment(recalled: RecalledMemories | undefined, context: MemoryCaptureContext, options: SynthesizedAttachmentOptions): ResolvedMcpServer | undefined;

package/dist/shared/memory-attachment.js

@@ -0,0 +1,142 @@
+/**
+ * The runner-synthesized memory capture attachment.
+ *
+ * When the execution's recall snapshot says memory is on
+ * (`status.recalled_memories.enabled` — the ONE server-owned field that
+ * serves both the recall and capture sides, stamped by the create
+ * pipeline's compose step), the runner synthesizes ONE MCP attachment
+ * serving the `remember` tool. No discovery RPC exists on this path:
+ * unlike the channel attachment's registry read, the enablement answer
+ * is already on the spec — a free, synchronous read (the
+ * conversation-attachment session-label precedent). The enabled bit with
+ * ZERO facts is a meaningful state: memory is on, nothing stored yet —
+ * the tool is offered so the first fact can be proposed.
+ *
+ * Two connection shapes, one roster (the channels pattern), one
+ * credential — the run's own — presented on both:
+ *   - Bridge endpoint configured (cloud): Streamable HTTP against the
+ *     bridge's /memory route with the run's credential as the Bearer
+ *     token, plus the capture context as per-request headers.
+ *   - No bridge endpoint (OSS/local): a spawned `stigmer mcp-server`
+ *     stdio child with STIGMER_MCP_ROSTER=memory, the run's credential
+ *     as its startup credential (synthesized-attachment.ts
+ *     `stdioCredentialEnv`), plus the capture context as
+ *     STIGMER_MEMORY_* env. Without the credential a server that signs
+ *     people in refuses every `remember` as nobody's (stigmer#1147);
+ *     with it the memory is the run's person's, which the server derives
+ *     from the credential and nothing the child says.
+ *
+ * The capture context (org + agent/session/execution ids) is
+ * attribution, never authorization (since 2026-08-22): the cloud create
+ * handler accepts it only
+ * from a session-sandbox credential and overrides session/org with the
+ * token's own claims; the OSS server under sign-in admits it from the
+ * run's credential and proves the session off the run's row, and stores
+ * it as given under the local single-user trust model. The subject is
+ * never threaded — the server derives it from the credential.
+ *
+ * Approval-free by construction (the synthesized-attachment contract):
+ * the tool only ever creates a PROPOSAL the user must confirm through
+ * the control plane, so gating the propose call would stack a second
+ * consent gate in front of the real one (consent is the
+ * confirm RPC, not tool approval). Callers inject AFTER resolve.
+ *
+ * Failure posture: the attachment is synthesized from values already in
+ * hand, so the only failure mode is the create RPC refusing at call
+ * time — which the mcp-server's memory error mapper relays honestly.
+ * When the snapshot is absent or disabled: no tool, honest absence.
+ */
+import { MEMORY_MCP_SERVER } from "@stigmer/tool-vocabulary";
+import { grpcTarget, SERVER_ADDRESS_ENV_KEY } from "./platform-server-address.js";
+import { stdioCredentialEnv, } from "./synthesized-attachment.js";
+/**
+ * The synthesized attachment's slug. Reserved: no plugin server is named
+ * like it (theirs start `plugin_`), and one that were would be shadowed by
+ * the synthesized attachment, with a warning.
+ * Runner-internal (the resolved-server name and shadow key — the
+ * mcp-server never sees it); pinned by this module's test. The ROUTE
+ * and the context keys below are cross-repo strings, pinned on both
+ * sides (the TOOL_CALL_LIMIT precedent).
+ */
+export const MEMORY_ATTACHMENT_SLUG = MEMORY_MCP_SERVER;
+/** The bridge route serving the memory-only roster (mcp-server twin: MEMORY_ROUTE). */
+export const MEMORY_ROUTE = "/memory";
+/**
+ * The capture-context carriers, mirrored byte-for-byte by the
+ * mcp-server's memory domain (domains/memory/context.ts): headers on
+ * the bridge's per-request path, env on the stdio child — the same
+ * per-request-then-startup split the credential itself uses.
+ */
+export const MEMORY_ORG_HEADER = "x-stigmer-memory-org";
+export const MEMORY_AGENT_ID_HEADER = "x-stigmer-memory-agent-id";
+export const MEMORY_SESSION_ID_HEADER = "x-stigmer-memory-session-id";
+export const MEMORY_EXECUTION_ID_HEADER = "x-stigmer-memory-execution-id";
+export const MEMORY_ORG_ENV = "STIGMER_MEMORY_ORG";
+export const MEMORY_AGENT_ID_ENV = "STIGMER_MEMORY_AGENT_ID";
+export const MEMORY_SESSION_ID_ENV = "STIGMER_MEMORY_SESSION_ID";
+export const MEMORY_EXECUTION_ID_ENV = "STIGMER_MEMORY_EXECUTION_ID";
+/**
+ * Reports whether the execution's recall snapshot offers the remember
+ * tool (the snapshot's enabled bit IS the runner's injection
+ * signal — one server-owned field, no parallel flag, no discovery
+ * round-trip). Exposed for the harnesses' MCP gates, which must open
+ * MCP resolution for a memory-only agent.
+ */
+export function memoryCaptureEnabled(recalled) {
+    return recalled?.enabled === true;
+}
+/**
+ * Synthesize the memory capture attachment. Returns undefined when the
+ * recall snapshot is absent or disabled — the attachment exists exactly
+ * when the server-composed snapshot says memory is on.
+ */
+export function synthesizeMemoryAttachment(recalled, context, options) {
+    if (!memoryCaptureEnabled(recalled)) {
+        return undefined;
+    }
+    // Approval-free by construction: see file header.
+    const base = {
+        slug: MEMORY_ATTACHMENT_SLUG,
+        home: { kind: "platform" },
+    };
+    if (options.bridgeEndpoint !== null && options.bridgeEndpoint !== "") {
+        return {
+            ...base,
+            connectionType: "http",
+            url: options.bridgeEndpoint.replace(/\/+$/, "") + MEMORY_ROUTE,
+            headers: {
+                ...(options.credential !== null && options.credential !== ""
+                    ? { Authorization: `Bearer ${options.credential}` }
+                    : undefined),
+                ...nonEmptyEntries([
+                    [MEMORY_ORG_HEADER, context.org],
+                    [MEMORY_AGENT_ID_HEADER, context.agentId],
+                    [MEMORY_SESSION_ID_HEADER, context.sessionId],
+                    [MEMORY_EXECUTION_ID_HEADER, context.agentExecutionId],
+                ]),
+            },
+        };
+    }
+    return {
+        ...base,
+        connectionType: "stdio",
+        command: "stigmer",
+        args: ["mcp-server"],
+        env: {
+            STIGMER_MCP_ROSTER: "memory",
+            [SERVER_ADDRESS_ENV_KEY]: grpcTarget(options.backendEndpoint),
+            ...stdioCredentialEnv(options.credential),
+            ...nonEmptyEntries([
+                [MEMORY_ORG_ENV, context.org],
+                [MEMORY_AGENT_ID_ENV, context.agentId],
+                [MEMORY_SESSION_ID_ENV, context.sessionId],
+                [MEMORY_EXECUTION_ID_ENV, context.agentExecutionId],
+            ]),
+        },
+    };
+}
+/** The non-empty context fields as carrier entries (absent means empty). */
+function nonEmptyEntries(pairs) {
+    return Object.fromEntries(pairs.filter(([, value]) => value !== ""));
+}
+//# sourceMappingURL=memory-attachment.js.map

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

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