@stigmer/server 3.15.3-dev.20260914100347 → 3.15.3-dev.20260916211208

package/dist/domain/plugin/materialize/agent.js

@@ -0,0 +1,128 @@
+/**
+ * The agent from a plugin — materialised only when the plugin carries
+ * something agent-like: a skill, a sub-agent file, or an
+ * `ai.stigmer/agent.yaml`. An MCP-only plugin becomes its servers and no
+ * agent (the "a plugin is a toolbox, an agent is the worker" rule): most
+ * plugins in the wild are one server and one token, and five thin agents
+ * nobody runs would be the plugin-versus-agent confusion this kind exists
+ * to remove.
+ *
+ * Two sources, never mixed: the author's `agent.yaml` wholesale when
+ * present (its references still resolve in the agent chain's
+ * ValidateReferences), otherwise the composed default — instructions from
+ * the versioned template, every skill as a `skill_ref`, every server as an
+ * `mcp_server_usage`, every `agents/*.md` as a `sub_agent` with access to
+ * all the plugin's servers and the skills it asked for.
+ *
+ * Model hints are recorded, never applied: a dialect's `model` becomes a
+ * status warning and the sub-agent runs on the session's model. The
+ * catalog seam exposes neither family nor cost tier, the runner drops a
+ * sub-agent whose override it cannot resolve, and pinning a model the user
+ * did not choose has cost consequences; a later catalog seam can change
+ * this in one place. A sub-agent named like a runner built-in is recorded
+ * the same way: the runner warns and continues, so the install does too.
+ */
+import { create } from "@bufbuild/protobuf";
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { AgentSpecSchema, McpAccessSchema, McpServerUsageSchema, SubAgentSchema, } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import { PluginWarningSchema } from "@stigmer/protos/ai/stigmer/agentic/plugin/v1/status_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ApiResourceReferenceSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import { BUILT_IN_SUB_AGENT_NAMES, SERVER_WARNING_KINDS, } from "../constants.js";
+import { renderDefaultAgentInstructions } from "./default-agent-instructions.js";
+import { memberMetadata } from "./identity.js";
+import { mcpServerSlugOf } from "./mcp-servers.js";
+import { skillSlugOf } from "./skills.js";
+/** Whether the plugin materialises an agent at all. */
+export function carriesAgent(plugin) {
+    return (plugin.skills.length > 0 ||
+        plugin.subAgents.length > 0 ||
+        plugin.overlay.agent !== undefined);
+}
+export function planAgent(plugin, overlayAgent, identity, warnings) {
+    if (!carriesAgent(plugin)) {
+        return undefined;
+    }
+    const member = { name: identity.name, slug: identity.slug };
+    if (overlayAgent !== undefined) {
+        return {
+            ...member,
+            resource: create(AgentSchema, {
+                apiVersion: "agentic.stigmer.ai/v1",
+                kind: "Agent",
+                metadata: memberMetadata(identity, member, overlayAgent.metadata),
+                spec: overlayAgent.spec,
+            }),
+        };
+    }
+    const serverSlugs = plugin.mcpServers.map(mcpServerSlugOf);
+    const skillSlugByName = new Map(plugin.skills.map((skill) => [skill.name, skillSlugOf(skill)]));
+    const spec = create(AgentSpecSchema, {
+        description: plugin.description ?? "",
+        instructions: renderDefaultAgentInstructions(plugin),
+        skillRefs: [...skillSlugByName.values()].map((slug) => create(ApiResourceReferenceSchema, {
+            org: identity.org,
+            kind: ApiResourceKind.skill,
+            slug,
+        })),
+        mcpServerUsages: serverSlugs.map((slug) => create(McpServerUsageSchema, {
+            mcpServerRef: create(ApiResourceReferenceSchema, {
+                org: identity.org,
+                kind: ApiResourceKind.mcp_server,
+                slug,
+            }),
+        })),
+        subAgents: plugin.subAgents.map((subAgent) => planSubAgent(subAgent, identity, serverSlugs, skillSlugByName, warnings)),
+    });
+    return {
+        ...member,
+        resource: create(AgentSchema, {
+            apiVersion: "agentic.stigmer.ai/v1",
+            kind: "Agent",
+            metadata: memberMetadata(identity, member),
+            spec,
+        }),
+    };
+}
+function planSubAgent(subAgent, identity, serverSlugs, skillSlugByName, warnings) {
+    if (BUILT_IN_SUB_AGENT_NAMES.has(subAgent.name)) {
+        warnings.push(create(PluginWarningSchema, {
+            kind: SERVER_WARNING_KINDS.subAgentNameBuiltin,
+            path: subAgent.path,
+            message: `sub-agent '${subAgent.name}' shares its name with a built-in sub-agent; ` +
+                "the runner warns and runs the plugin's",
+        }));
+    }
+    const hint = subAgent.modelHint;
+    if (hint !== undefined &&
+        hint.alias !== "inherit" &&
+        hint.alias !== "unknown") {
+        // An unknown alias already carries the library's own sentence.
+        warnings.push(create(PluginWarningSchema, {
+            kind: SERVER_WARNING_KINDS.modelHintUnresolved,
+            path: subAgent.path,
+            message: `sub-agent '${subAgent.name}' names model '${hint.raw}'; Stigmer does not pin a model ` +
+                "from a plugin, so it runs on the session's model",
+        }));
+    }
+    return create(SubAgentSchema, {
+        name: subAgent.name,
+        description: subAgent.description ?? "",
+        instructions: subAgent.instructions,
+        mcpAccess: serverSlugs.map((slug) => create(McpAccessSchema, { mcpServer: slug })),
+        skillRefs: subAgent.skillNames.flatMap((name) => {
+            const slug = skillSlugByName.get(name);
+            // An unknown skill name already carries the library's own warning.
+            return slug === undefined
+                ? []
+                : [
+                    create(ApiResourceReferenceSchema, {
+                        org: identity.org,
+                        kind: ApiResourceKind.skill,
+                        slug,
+                    }),
+                ];
+        }),
+    });
+}
+//# sourceMappingURL=agent.js.map

package/dist/domain/plugin/materialize/agent.js.map

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

package/dist/domain/plugin/materialize/default-agent-instructions.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The system prompt of a plugin's composed agent — the agent Stigmer
+ * materialises when a plugin carries skills or sub-agents but no
+ * `ai.stigmer/agent.yaml` of its own. A prompt is code: this module is its
+ * one home, it is versioned so a later change to the wording is a visible
+ * behaviour change with a number, and its rendering is pinned by a snapshot
+ * test. Nothing here reaches the runner; the text becomes
+ * `AgentSpec.instructions` and the runner composes it with the mounted
+ * skills like any other agent's.
+ *
+ * Design: the template names the plugin, lists what it carries, and gives
+ * three standing instructions (read the skill before acting, use the tools
+ * it names, report what was and was not done). Deliberately short: skills
+ * carry the real knowledge, and a long composed prompt would compete with
+ * them for the model's attention.
+ */
+import type { PluginPackage } from "@stigmer/plugin-package";
+/** Bumped whenever the rendered text changes; the snapshot test pins the pair. */
+export declare const DEFAULT_AGENT_INSTRUCTIONS_VERSION = 1;
+/** Renders the composed agent's instructions for a plugin. */
+export declare function renderDefaultAgentInstructions(plugin: PluginPackage): string;
+//# sourceMappingURL=default-agent-instructions.d.ts.map

package/dist/domain/plugin/materialize/default-agent-instructions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-agent-instructions.d.ts","sourceRoot":"","sources":["../../../../src/domain/plugin/materialize/default-agent-instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7D,kFAAkF;AAClF,eAAO,MAAM,kCAAkC,IAAI,CAAC;AAEpD,8DAA8D;AAC9D,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAoC5E"}

package/dist/domain/plugin/materialize/default-agent-instructions.js

@@ -0,0 +1,31 @@
+/** Bumped whenever the rendered text changes; the snapshot test pins the pair. */
+export const DEFAULT_AGENT_INSTRUCTIONS_VERSION = 1;
+/** Renders the composed agent's instructions for a plugin. */
+export function renderDefaultAgentInstructions(plugin) {
+    const lines = [];
+    const description = plugin.description?.trim() ?? "";
+    lines.push(description === ""
+        ? `You are ${plugin.name}, an agent installed from the ${plugin.name} plugin.`
+        : `You are ${plugin.name}: ${description}`);
+    if (plugin.skills.length > 0) {
+        lines.push("");
+        lines.push("Your skills:");
+        for (const skill of plugin.skills) {
+            const summary = skill.description?.trim() ?? "";
+            lines.push(summary === "" ? `- ${skill.name}` : `- ${skill.name}: ${summary}`);
+        }
+    }
+    if (plugin.mcpServers.length > 0) {
+        lines.push("");
+        lines.push("Your tools come from these MCP servers:");
+        for (const server of plugin.mcpServers) {
+            lines.push(`- ${server.name}`);
+        }
+    }
+    lines.push("");
+    lines.push("Before acting on a task a skill covers, read that skill and follow it. " +
+        "Use the tools your servers provide rather than guessing at their results. " +
+        "When you finish, state what you did and what you could not do.");
+    return lines.join("\n");
+}
+//# sourceMappingURL=default-agent-instructions.js.map

package/dist/domain/plugin/materialize/default-agent-instructions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-agent-instructions.js","sourceRoot":"","sources":["../../../../src/domain/plugin/materialize/default-agent-instructions.ts"],"names":[],"mappings":"AAkBA,kFAAkF;AAClF,MAAM,CAAC,MAAM,kCAAkC,GAAG,CAAC,CAAC;AAEpD,8DAA8D;AAC9D,MAAM,UAAU,8BAA8B,CAAC,MAAqB;IAClE,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IACrD,KAAK,CAAC,IAAI,CACR,WAAW,KAAK,EAAE;QAChB,CAAC,CAAC,WAAW,MAAM,CAAC,IAAI,iCAAiC,MAAM,CAAC,IAAI,UAAU;QAC9E,CAAC,CAAC,WAAW,MAAM,CAAC,IAAI,KAAK,WAAW,EAAE,CAC7C,CAAC;IAEF,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAC3B,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;YAClC,MAAM,OAAO,GAAG,KAAK,CAAC,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;YAChD,KAAK,CAAC,IAAI,CACR,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,IAAI,KAAK,OAAO,EAAE,CACnE,CAAC;QACJ,CAAC;IACH,CAAC;IAED,IAAI,MAAM,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACjC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,yCAAyC,CAAC,CAAC;QACtD,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;YACvC,KAAK,CAAC,IAAI,CAAC,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CACR,yEAAyE;QACvE,4EAA4E;QAC5E,gEAAgE,CACnE,CAAC;IAEF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/domain/plugin/materialize/identity.d.ts

@@ -0,0 +1,28 @@
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import type { ApiResourceMetadata } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+/** The plugin, as its members see it. */
+export interface PluginIdentity {
+    readonly org: string;
+    /** The plugin's resource id — the membership label's value. */
+    readonly id: string;
+    readonly slug: string;
+    readonly name: string;
+    /** The archive digest — the convergence label's value. */
+    readonly digest: string;
+    /** The level every member takes; unspecified means the child kind's default. */
+    readonly visibility: ApiResourceVisibility;
+}
+/** The two labels a member carries, and nothing else the plugin owns. */
+export declare function memberLabels(identity: PluginIdentity): Record<string, string>;
+/**
+ * A member's metadata: the plugin's org and visibility, the member's own
+ * name and slug, the plugin's labels merged OVER any the overlay author
+ * wrote (an author may label their agent; they may not claim membership of
+ * another plugin, and the sanitiser has already refused every reserved key
+ * an author tried).
+ */
+export declare function memberMetadata(identity: PluginIdentity, member: {
+    readonly name: string;
+    readonly slug: string;
+}, authored?: ApiResourceMetadata): ApiResourceMetadata;
+//# sourceMappingURL=identity.d.ts.map

package/dist/domain/plugin/materialize/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../../../src/domain/plugin/materialize/identity.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,qBAAqB,EAAE,MAAM,wDAAwD,CAAC;AAE/F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4DAA4D,CAAC;AAOtG,yCAAyC;AACzC,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,gFAAgF;IAChF,QAAQ,CAAC,UAAU,EAAE,qBAAqB,CAAC;CAC5C;AAED,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAK7E;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EACxD,QAAQ,CAAC,EAAE,mBAAmB,GAC7B,mBAAmB,CAerB"}

package/dist/domain/plugin/materialize/identity.js

@@ -0,0 +1,40 @@
+/**
+ * What every member of a plugin inherits from the plugin: the
+ * organization, the two reserved labels (the plugin's id for membership,
+ * the archive digest for convergence) and the visibility. One function
+ * stamps a child's metadata so the four materialisers cannot disagree on
+ * how a member is marked, and one type carries the plugin's identity into
+ * them so none reaches back into the head.
+ */
+import { create } from "@bufbuild/protobuf";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+import { PLUGIN_LABEL, PLUGIN_VERSION_LABEL, } from "../../../pipeline/apiresource-labels.js";
+/** The two labels a member carries, and nothing else the plugin owns. */
+export function memberLabels(identity) {
+    return {
+        [PLUGIN_LABEL]: identity.id,
+        [PLUGIN_VERSION_LABEL]: identity.digest,
+    };
+}
+/**
+ * A member's metadata: the plugin's org and visibility, the member's own
+ * name and slug, the plugin's labels merged OVER any the overlay author
+ * wrote (an author may label their agent; they may not claim membership of
+ * another plugin, and the sanitiser has already refused every reserved key
+ * an author tried).
+ */
+export function memberMetadata(identity, member, authored) {
+    const metadata = authored === undefined ? create(ApiResourceMetadataSchema, {}) : authored;
+    metadata.org = identity.org;
+    metadata.name = member.name;
+    metadata.slug = member.slug;
+    metadata.id = "";
+    if (identity.visibility !==
+        ApiResourceVisibility.api_resource_visibility_unspecified) {
+        metadata.visibility = identity.visibility;
+    }
+    metadata.labels = { ...metadata.labels, ...memberLabels(identity) };
+    return metadata;
+}
+//# sourceMappingURL=identity.js.map

package/dist/domain/plugin/materialize/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../../../../src/domain/plugin/materialize/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAE5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,wDAAwD,CAAC;AAC/F,OAAO,EAAE,yBAAyB,EAAE,MAAM,4DAA4D,CAAC;AAGvG,OAAO,EACL,YAAY,EACZ,oBAAoB,GACrB,MAAM,yCAAyC,CAAC;AAejD,yEAAyE;AACzE,MAAM,UAAU,YAAY,CAAC,QAAwB;IACnD,OAAO;QACL,CAAC,YAAY,CAAC,EAAE,QAAQ,CAAC,EAAE;QAC3B,CAAC,oBAAoB,CAAC,EAAE,QAAQ,CAAC,MAAM;KACxC,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,QAAwB,EACxB,MAAwD,EACxD,QAA8B;IAE9B,MAAM,QAAQ,GACZ,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,yBAAyB,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;IAC5E,QAAQ,CAAC,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC;IAC5B,QAAQ,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;IAC5B,QAAQ,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;IAC5B,QAAQ,CAAC,EAAE,GAAG,EAAE,CAAC;IACjB,IACE,QAAQ,CAAC,UAAU;QACnB,qBAAqB,CAAC,mCAAmC,EACzD,CAAC;QACD,QAAQ,CAAC,UAAU,GAAG,QAAQ,CAAC,UAAU,CAAC;IAC5C,CAAC;IACD,QAAQ,CAAC,MAAM,GAAG,EAAE,GAAG,QAAQ,CAAC,MAAM,EAAE,GAAG,YAAY,CAAC,QAAQ,CAAC,EAAE,CAAC;IACpE,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/domain/plugin/materialize/mcp-servers.d.ts

@@ -0,0 +1,15 @@
+import type { PluginMcpServer, PluginPackage } from "@stigmer/plugin-package";
+import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import type { PluginIdentity } from "./identity.js";
+export interface PlannedMcpServer {
+    readonly name: string;
+    readonly slug: string;
+    readonly resource: McpServer;
+}
+/** A refused overlay, phrased for the author. */
+export declare class McpServerOverlayError extends Error {
+    constructor(server: string, reason: string);
+}
+export declare function mcpServerSlugOf(server: PluginMcpServer): string;
+export declare function planMcpServers(plugin: PluginPackage, overlays: ReadonlyMap<string, McpServer>, identity: PluginIdentity): PlannedMcpServer[];
+//# sourceMappingURL=mcp-servers.d.ts.map

package/dist/domain/plugin/materialize/mcp-servers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-servers.d.ts","sourceRoot":"","sources":["../../../../src/domain/plugin/materialize/mcp-servers.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAI9E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wDAAwD,CAAC;AAUxF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;CAC9B;AAED,iDAAiD;AACjD,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAI3C;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAE/D;AAED,wBAAgB,cAAc,CAC5B,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,EACxC,QAAQ,EAAE,cAAc,GACvB,gBAAgB,EAAE,CAuDpB"}

package/dist/domain/plugin/materialize/mcp-servers.js

@@ -0,0 +1,131 @@
+/**
+ * MCP servers from a plugin: one `McpServer` per `mcpServers` entry of the
+ * portable `mcp.json`, layered with the plugin's Stigmer overlay for that
+ * server when the author wrote one (`ai.stigmer/mcp-servers/<name>.yaml`).
+ *
+ * The portable file owns what every client reads: the transport (`http`
+ * url and headers, or `stdio` command and args) and the variables the
+ * server references, which become `EnvVarDeclaration`s the runner resolves
+ * from the user's Environment. The overlay owns what only Stigmer reads:
+ * OAuth (`auth`), scope hints, default and pinned tools, the icon, tags,
+ * the repository link, and a richer description. An overlay that sets the
+ * transport or declares env is refused: the portable file is the one home
+ * of both, so a Cursor or Claude user installing the same plugin sees the
+ * same server.
+ *
+ * The server's name is the `mcpServers` key and its slug `generateSlug`
+ * of it (the platform's one slug rule: lowercase, dots and spaces to
+ * hyphens, every other symbol dropped, so `my_server` becomes `myserver`);
+ * sub-agents and the agent's usages reference the slug.
+ */
+import { create } from "@bufbuild/protobuf";
+import { EnvVarDeclarationSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
+import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { HttpServerConfigSchema, McpServerSpecSchema, StdioServerConfigSchema, } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_pb";
+import { generateSlug } from "../../../pipeline/steps/slug.js";
+import { memberMetadata } from "./identity.js";
+/** A refused overlay, phrased for the author. */
+export class McpServerOverlayError extends Error {
+    constructor(server, reason) {
+        super(`overlay for MCP server '${server}': ${reason}`);
+        this.name = "McpServerOverlayError";
+    }
+}
+export function mcpServerSlugOf(server) {
+    return generateSlug(server.name);
+}
+export function planMcpServers(plugin, overlays, identity) {
+    const env = declaredVariables(plugin);
+    return plugin.mcpServers.map((server) => {
+        const overlay = overlays.get(server.name);
+        const spec = create(McpServerSpecSchema, {
+            description: plugin.description ?? "",
+            env: Object.fromEntries(server.env.map((name) => [name, env.get(name) ?? inferredSecret()])),
+        });
+        switch (server.transport) {
+            case "http":
+                spec.serverType = {
+                    case: "http",
+                    value: create(HttpServerConfigSchema, {
+                        url: server.url,
+                        headers: { ...server.headers },
+                    }),
+                };
+                break;
+            case "stdio":
+                spec.serverType = {
+                    case: "stdio",
+                    value: create(StdioServerConfigSchema, {
+                        command: server.command,
+                        args: [...server.args],
+                    }),
+                };
+                break;
+            default: {
+                const exhaustive = server;
+                throw new Error(`unknown transport ${JSON.stringify(exhaustive)}`);
+            }
+        }
+        if (overlay !== undefined) {
+            layerOverlay(server.name, spec, overlay);
+        }
+        const slug = mcpServerSlugOf(server);
+        return {
+            name: server.name,
+            slug,
+            resource: create(McpServerSchema, {
+                apiVersion: "agentic.stigmer.ai/v1",
+                kind: "McpServer",
+                metadata: memberMetadata(identity, { name: server.name, slug }, overlay?.metadata),
+                spec,
+            }),
+        };
+    });
+}
+/** Every declared variable, by name, as the runner's declaration shape. */
+function declaredVariables(plugin) {
+    return new Map(plugin.variables.map((variable) => [
+        variable.name,
+        create(EnvVarDeclarationSchema, {
+            isSecret: variable.isSecret,
+            description: variable.description ?? "",
+            optional: variable.optional,
+        }),
+    ]));
+}
+/**
+ * A reference the library did not declare cannot happen — it infers every
+ * undeclared `${VAR}` as a required secret — so this arm is the honest
+ * default for a name the declaration list somehow lacks.
+ */
+function inferredSecret() {
+    return create(EnvVarDeclarationSchema, { isSecret: true, optional: false });
+}
+/** The overlay's Stigmer-only fields over the portable spec; the portable owner's fields stay. */
+function layerOverlay(serverName, spec, overlay) {
+    const authored = overlay.spec;
+    if (authored === undefined) {
+        return;
+    }
+    if (authored.serverType.case !== undefined) {
+        throw new McpServerOverlayError(serverName, "the transport (http or stdio) lives in mcp.json, where every client reads it; the overlay may not redefine it");
+    }
+    if (Object.keys(authored.env).length > 0) {
+        throw new McpServerOverlayError(serverName, "variables are declared where mcp.json references them (the plugin's variables or userConfig); the overlay may not declare env");
+    }
+    if (authored.description !== "")
+        spec.description = authored.description;
+    if (authored.iconUrl !== "")
+        spec.iconUrl = authored.iconUrl;
+    if (authored.tags.length > 0)
+        spec.tags = [...authored.tags];
+    if (authored.defaultEnabledTools.length > 0)
+        spec.defaultEnabledTools = [...authored.defaultEnabledTools];
+    if (authored.pinnedToolApprovals.length > 0)
+        spec.pinnedToolApprovals = [...authored.pinnedToolApprovals];
+    if (authored.repositoryUrl !== "")
+        spec.repositoryUrl = authored.repositoryUrl;
+    if (authored.auth !== undefined)
+        spec.auth = authored.auth;
+}
+//# sourceMappingURL=mcp-servers.js.map

package/dist/domain/plugin/materialize/mcp-servers.js.map

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

package/dist/domain/plugin/materialize/plan.d.ts

@@ -0,0 +1,24 @@
+import type { PluginFiles, PluginPackage } from "@stigmer/plugin-package";
+import type { PluginWarning } from "@stigmer/protos/ai/stigmer/agentic/plugin/v1/status_pb";
+import type { PlannedMember } from "../members.js";
+import type { ParsedOverlays } from "../overlay/documents.js";
+import type { PlannedAgent } from "./agent.js";
+import type { PluginIdentity } from "./identity.js";
+import type { PlannedMcpServer } from "./mcp-servers.js";
+import type { PlannedSkill } from "./skills.js";
+import type { PlannedWorkflow } from "./workflows.js";
+export interface MaterializationPlan {
+    readonly skills: readonly PlannedSkill[];
+    readonly mcpServers: readonly PlannedMcpServer[];
+    readonly agent: PlannedAgent | undefined;
+    readonly workflows: readonly PlannedWorkflow[];
+    /** Every member the push intends, in materialisation order. */
+    readonly members: readonly PlannedMember[];
+    /** The audit tag this push assigns; empty when the version does not fit. */
+    readonly tag: string;
+    readonly warnings: readonly PluginWarning[];
+}
+/** The manifest version as a tag, or empty with a warning when it cannot be one. */
+export declare function versionTag(version: string | undefined, warnings: PluginWarning[]): string;
+export declare function planMaterialization(plugin: PluginPackage, files: PluginFiles, overlays: ParsedOverlays, identity: PluginIdentity, message: string): MaterializationPlan;
+//# sourceMappingURL=plan.d.ts.map

package/dist/domain/plugin/materialize/plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../../../src/domain/plugin/materialize/plan.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE1E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wDAAwD,CAAC;AAI5F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAE9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEtD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;IACzC,QAAQ,CAAC,UAAU,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACjD,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,SAAS,EAAE,SAAS,eAAe,EAAE,CAAC;IAC/C,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;IAC3C,4EAA4E;IAC5E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;CAC7C;AAED,oFAAoF;AACpF,wBAAgB,UAAU,CACxB,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,QAAQ,EAAE,aAAa,EAAE,GACxB,MAAM,CAgBR;AAED,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,cAAc,EACxB,QAAQ,EAAE,cAAc,EACxB,OAAO,EAAE,MAAM,GACd,mBAAmB,CAiDrB"}

package/dist/domain/plugin/materialize/plan.js

@@ -0,0 +1,77 @@
+/**
+ * The materialisation plan: everything a push will write, computed before
+ * anything is written. One pure function turns the library's description
+ * of the package, the parsed overlay and the plugin's identity into the
+ * four planned member sets plus the warnings the plan itself raised, so
+ * the push step can check every slug against the organization, pre-
+ * authorise the caller for every child kind, and decide whether the
+ * members already converge — all before the first in-process call.
+ *
+ * Warnings collected here join the library's in `PluginStatus.warnings`:
+ * every ignored component (recorded once per component, as the library
+ * records it), each unapplied model hint, each built-in name shadowed, and
+ * a manifest version the tag pattern rejects.
+ */
+import { create } from "@bufbuild/protobuf";
+import { PluginWarningSchema } from "@stigmer/protos/ai/stigmer/agentic/plugin/v1/status_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { SERVER_WARNING_KINDS, VERSION_TAG_PATTERN } from "../constants.js";
+import { planAgent } from "./agent.js";
+import { planMcpServers } from "./mcp-servers.js";
+import { planSkills } from "./skills.js";
+import { planWorkflows } from "./workflows.js";
+/** The manifest version as a tag, or empty with a warning when it cannot be one. */
+export function versionTag(version, warnings) {
+    if (version === undefined || version === "") {
+        return "";
+    }
+    if (VERSION_TAG_PATTERN.test(version)) {
+        return version;
+    }
+    warnings.push(create(PluginWarningSchema, {
+        kind: SERVER_WARNING_KINDS.versionNotTaggable,
+        message: `version '${version}' cannot be a tag (letters, digits, '.', '_' and '-' only); ` +
+            "this version is reachable by its digest but not by name",
+    }));
+    return "";
+}
+export function planMaterialization(plugin, files, overlays, identity, message) {
+    const warnings = [];
+    for (const ignored of plugin.ignored) {
+        warnings.push(create(PluginWarningSchema, {
+            kind: SERVER_WARNING_KINDS.componentIgnored,
+            path: ignored.path,
+            message: `${ignored.kind} at '${ignored.path}' is not installed; Stigmer reads skills, MCP servers, sub-agents and the ai.stigmer/ overlay`,
+        }));
+    }
+    const tag = versionTag(plugin.version, warnings);
+    const skills = planSkills(plugin, files, identity, tag, message);
+    const mcpServers = planMcpServers(plugin, new Map(overlays.mcpServers.map((document) => [
+        document.server,
+        document.resource,
+    ])), identity);
+    const agent = planAgent(plugin, overlays.agent?.resource, identity, warnings);
+    const workflows = planWorkflows(overlays.workflows, identity);
+    const members = [
+        ...skills.map((skill) => ({
+            kind: ApiResourceKind.skill,
+            slug: skill.slug,
+            name: skill.name,
+        })),
+        ...mcpServers.map((server) => ({
+            kind: ApiResourceKind.mcp_server,
+            slug: server.slug,
+            name: server.name,
+        })),
+        ...(agent === undefined
+            ? []
+            : [{ kind: ApiResourceKind.agent, slug: agent.slug, name: agent.name }]),
+        ...workflows.map((workflow) => ({
+            kind: ApiResourceKind.workflow,
+            slug: workflow.slug,
+            name: workflow.name,
+        })),
+    ];
+    return { skills, mcpServers, agent, workflows, members, tag, warnings };
+}
+//# sourceMappingURL=plan.js.map

package/dist/domain/plugin/materialize/plan.js.map

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

package/dist/domain/plugin/materialize/ports.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The one edge the plugin domain has onto the four child domains — a
+ * consumer-defined, method-segregated surface the composition root
+ * satisfies with in-process clients (boot/inprocess.ts), the
+ * `AgentInstanceApplier` shape. Every call rides the in-process router
+ * transport AS THE INSTALLING CALLER (the `asCaller` call options): each
+ * child's full chain runs — validation, the caller's own permission for
+ * that kind, references, the reserved-label and managed guards (both pass
+ * by origin), persist, tuples, index — so a materialised skill is a skill
+ * the CLI could have pushed, attributed to the user who installed it.
+ *
+ * Why an interface and not the clients: the domain reads at its boundary
+ * what it needs and nothing more (no update, no create, no reads), the
+ * agent↔agentinstance-style cycle between routes and clients is broken at
+ * the consumer with a lazy provider, and a test supplies a recording fake.
+ */
+import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import type { Skill } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
+import type { PushSkillRequest } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/io_pb";
+import type { Workflow } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import type { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import type { CallerIdentity } from "../../../extensions/identity.js";
+export interface PluginMaterializer {
+    /** Skill push is upsert-by-slug from the frontmatter; the request carries the plugin's labels. */
+    pushSkill(request: PushSkillRequest, caller: CallerIdentity): Promise<Skill>;
+    /** Apply is upsert-by-slug for the three YAML kinds. */
+    applyMcpServer(server: McpServer, caller: CallerIdentity): Promise<McpServer>;
+    applyAgent(agent: Agent, caller: CallerIdentity): Promise<Agent>;
+    applyWorkflow(workflow: Workflow, caller: CallerIdentity): Promise<Workflow>;
+    /**
+     * The one door for a level change (metadata.proto): an existing member
+     * whose level differs from the plugin's is moved here after apply.
+     */
+    updateVisibility(kind: ApiResourceKind, resourceId: string, visibility: ApiResourceVisibility, caller: CallerIdentity): Promise<void>;
+    /** A member the new archive dropped, or the whole set on uninstall. */
+    deleteByKind(kind: ApiResourceKind, resourceId: string, caller: CallerIdentity): Promise<void>;
+}
+/** Lazy provider: the clients exist only after the routes they ride are registered. */
+export type PluginMaterializerProvider = () => PluginMaterializer;
+//# sourceMappingURL=ports.d.ts.map

package/dist/domain/plugin/materialize/ports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.d.ts","sourceRoot":"","sources":["../../../../src/domain/plugin/materialize/ports.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oDAAoD,CAAC;AAChF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wDAAwD,CAAC;AACxF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oDAAoD,CAAC;AAChF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mDAAmD,CAAC;AAC1F,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uDAAuD,CAAC;AACtF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qFAAqF,CAAC;AAC3H,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wDAAwD,CAAC;AAEpG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAEtE,MAAM,WAAW,kBAAkB;IACjC,kGAAkG;IAClG,SAAS,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAC7E,wDAAwD;IACxD,cAAc,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAC9E,UAAU,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IACjE,aAAa,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC7E;;;OAGG;IACH,gBAAgB,CACd,IAAI,EAAE,eAAe,EACrB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,qBAAqB,EACjC,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,uEAAuE;IACvE,YAAY,CACV,IAAI,EAAE,eAAe,EACrB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED,uFAAuF;AACvF,MAAM,MAAM,0BAA0B,GAAG,MAAM,kBAAkB,CAAC"}

package/dist/domain/plugin/materialize/ports.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ports.js.map

package/dist/domain/plugin/materialize/ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.js","sourceRoot":"","sources":["../../../../src/domain/plugin/materialize/ports.ts"],"names":[],"mappings":""}

package/dist/domain/plugin/materialize/skills.d.ts

@@ -0,0 +1,12 @@
+import type { PluginFiles, PluginPackage, PluginSkill } from "@stigmer/plugin-package";
+import type { PushSkillRequest } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/io_pb";
+import type { PluginIdentity } from "./identity.js";
+export interface PlannedSkill {
+    readonly name: string;
+    readonly slug: string;
+    readonly request: PushSkillRequest;
+}
+/** The slug a plugin skill will have once pushed; the plan checks it before any write. */
+export declare function skillSlugOf(skill: PluginSkill): string;
+export declare function planSkills(plugin: PluginPackage, files: PluginFiles, identity: PluginIdentity, tag: string, message: string): PlannedSkill[];
+//# sourceMappingURL=skills.d.ts.map

package/dist/domain/plugin/materialize/skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../../../src/domain/plugin/materialize/skills.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EACV,WAAW,EACX,aAAa,EACb,WAAW,EACZ,MAAM,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mDAAmD,CAAC;AAK1F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;CACpC;AAED,0FAA0F;AAC1F,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAEtD;AAED,wBAAgB,UAAU,CACxB,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,cAAc,EACxB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,GACd,YAAY,EAAE,CAqBhB"}