@stigmer/server 3.15.3-dev.20260914121148 → 3.16.0

package/src/domain/plugin/materialize/agent.ts

@@ -0,0 +1,186 @@
+/**
+ * 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 type { PluginPackage, PluginSubAgent } from "@stigmer/plugin-package";
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import type { Agent } 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 type { SubAgent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import { PluginWarningSchema } from "@stigmer/protos/ai/stigmer/agentic/plugin/v1/status_pb";
+import type { PluginWarning } 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 type { PluginIdentity } from "./identity.js";
+import { mcpServerSlugOf } from "./mcp-servers.js";
+import { skillSlugOf } from "./skills.js";
+
+export interface PlannedAgent {
+  readonly name: string;
+  readonly slug: string;
+  readonly resource: Agent;
+}
+
+/** Whether the plugin materialises an agent at all. */
+export function carriesAgent(plugin: PluginPackage): boolean {
+  return (
+    plugin.skills.length > 0 ||
+    plugin.subAgents.length > 0 ||
+    plugin.overlay.agent !== undefined
+  );
+}
+
+export function planAgent(
+  plugin: PluginPackage,
+  overlayAgent: Agent | undefined,
+  identity: PluginIdentity,
+  warnings: PluginWarning[],
+): PlannedAgent | undefined {
+  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: PluginSubAgent,
+  identity: PluginIdentity,
+  serverSlugs: readonly string[],
+  skillSlugByName: ReadonlyMap<string, string>,
+  warnings: PluginWarning[],
+): SubAgent {
+  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,
+            }),
+          ];
+    }),
+  });
+}

package/src/domain/plugin/materialize/default-agent-instructions.ts

@@ -0,0 +1,59 @@
+/**
+ * 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 const DEFAULT_AGENT_INSTRUCTIONS_VERSION = 1;
+
+/** Renders the composed agent's instructions for a plugin. */
+export function renderDefaultAgentInstructions(plugin: PluginPackage): string {
+  const lines: string[] = [];
+  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");
+}

package/src/domain/plugin/materialize/identity.ts

@@ -0,0 +1,67 @@
+/**
+ * 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 type { ApiResourceMetadata } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+
+import {
+  PLUGIN_LABEL,
+  PLUGIN_VERSION_LABEL,
+} from "../../../pipeline/apiresource-labels.js";
+
+/** 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 function memberLabels(identity: PluginIdentity): Record<string, string> {
+  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: PluginIdentity,
+  member: { readonly name: string; readonly slug: string },
+  authored?: ApiResourceMetadata,
+): ApiResourceMetadata {
+  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;
+}

package/src/domain/plugin/materialize/mcp-servers.ts

@@ -0,0 +1,175 @@
+/**
+ * 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 type { PluginMcpServer, PluginPackage } from "@stigmer/plugin-package";
+import { EnvVarDeclarationSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
+import type { EnvVarDeclaration } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
+import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import type { McpServer } 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 type { McpServerSpec } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_pb";
+
+import { generateSlug } from "../../../pipeline/steps/slug.js";
+import { memberMetadata } from "./identity.js";
+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 class McpServerOverlayError extends Error {
+  constructor(server: string, reason: string) {
+    super(`overlay for MCP server '${server}': ${reason}`);
+    this.name = "McpServerOverlayError";
+  }
+}
+
+export function mcpServerSlugOf(server: PluginMcpServer): string {
+  return generateSlug(server.name);
+}
+
+export function planMcpServers(
+  plugin: PluginPackage,
+  overlays: ReadonlyMap<string, McpServer>,
+  identity: PluginIdentity,
+): PlannedMcpServer[] {
+  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: never = 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: PluginPackage,
+): Map<string, EnvVarDeclaration> {
+  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(): EnvVarDeclaration {
+  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: string,
+  spec: McpServerSpec,
+  overlay: McpServer,
+): void {
+  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;
+}

package/src/domain/plugin/materialize/plan.ts

@@ -0,0 +1,124 @@
+/**
+ * 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 type { PluginFiles, PluginPackage } from "@stigmer/plugin-package";
+import { PluginWarningSchema } from "@stigmer/protos/ai/stigmer/agentic/plugin/v1/status_pb";
+import type { PluginWarning } 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 type { PlannedMember } from "../members.js";
+import type { ParsedOverlays } from "../overlay/documents.js";
+import { planAgent } from "./agent.js";
+import type { PlannedAgent } from "./agent.js";
+import type { PluginIdentity } from "./identity.js";
+import { planMcpServers } from "./mcp-servers.js";
+import type { PlannedMcpServer } from "./mcp-servers.js";
+import { planSkills } from "./skills.js";
+import type { PlannedSkill } from "./skills.js";
+import { planWorkflows } from "./workflows.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 function versionTag(
+  version: string | undefined,
+  warnings: PluginWarning[],
+): string {
+  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: PluginPackage,
+  files: PluginFiles,
+  overlays: ParsedOverlays,
+  identity: PluginIdentity,
+  message: string,
+): MaterializationPlan {
+  const warnings: PluginWarning[] = [];
+  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: PlannedMember[] = [
+    ...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 };
+}

package/src/domain/plugin/materialize/ports.ts

@@ -0,0 +1,53 @@
+/**
+ * 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;