@stigmer/server 3.18.0-dev.20260918103812 → 3.18.0

package/src/domain/plugin/constants.ts

@@ -44,9 +44,15 @@ export type MaterializedKindName = (typeof MATERIALIZATION_ORDER)[number];
 export const TRANSFER_LANE_NOT_CONFIGURED =
   "plugin artifact transfer lane is not configured on this server";
 
-/** Warning kinds the SERVER adds to the library's; the wire carries them as strings. */
+/**
+ * Warning kinds the SERVER adds to the library's; the wire carries them as
+ * strings, and the list in PluginWarning.kind's comment (plugin/v1/status.proto)
+ * is kept equal to this one because the SDK docs are generated from it.
+ */
 export const SERVER_WARNING_KINDS = {
   componentIgnored: "component-ignored",
+  /** A system-content row the plugin took over in place (members.ts, judgeSlug). */
+  memberAdopted: "member-adopted",
   modelHintUnresolved: "model-hint-unresolved",
   subAgentNameBuiltin: "sub-agent-name-builtin",
   versionNotTaggable: "version-not-taggable",

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

@@ -19,6 +19,11 @@ import { PluginWarningSchema } from "@stigmer/protos/ai/stigmer/agentic/plugin/v
 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 {
+  RESERVED_LABEL_TRUE,
+  SYSTEM_LABEL,
+  isSystemContent,
+} from "../../../pipeline/apiresource-labels.js";
 import { SERVER_WARNING_KINDS, VERSION_TAG_PATTERN } from "../constants.js";
 import type { PlannedMember } from "../members.js";
 import type { ParsedOverlays } from "../overlay/documents.js";
@@ -105,24 +110,38 @@ export function planMaterialization(
   );
   const workflows = planWorkflows(overlays.workflows, identity);
 
+  // `system` is read from the labels each member will be written with (the
+  // overlay author's, the plugin's two merged over them). A skill's request
+  // carries only the plugin's two, so a skill never declares system content
+  // and can never adopt a row; the overlay kinds can.
   const members: PlannedMember[] = [
     ...skills.map((skill) => ({
       kind: ApiResourceKind.skill,
       slug: skill.slug,
       name: skill.name,
+      system: skill.request.labels[SYSTEM_LABEL] === RESERVED_LABEL_TRUE,
     })),
     ...mcpServers.map((server) => ({
       kind: ApiResourceKind.mcp_server,
       slug: server.slug,
       name: server.name,
+      system: isSystemContent(server.resource.metadata),
     })),
     ...(agent === undefined
       ? []
-      : [{ kind: ApiResourceKind.agent, slug: agent.slug, name: agent.name }]),
+      : [
+          {
+            kind: ApiResourceKind.agent,
+            slug: agent.slug,
+            name: agent.name,
+            system: isSystemContent(agent.resource.metadata),
+          },
+        ]),
     ...workflows.map((workflow) => ({
       kind: ApiResourceKind.workflow,
       slug: workflow.slug,
       name: workflow.name,
+      system: isSystemContent(workflow.resource.metadata),
     })),
   ];
 

package/src/domain/plugin/members.ts

@@ -8,14 +8,17 @@
  * pattern.
  *
  * The same module answers the two questions a push asks before any write:
- * which planned slugs are already held in the organization, and by whom
- * (this plugin: an upgrade; another plugin or an unmanaged resource: a
- * refusal naming the holder); and whether the plugin's members already
- * converge on the head's digest (every planned member present, each
- * carrying `stigmer.ai/plugin-version` equal to it), which is what lets a
- * re-push of the same archive return without a child write.
+ * what to do about each planned slug in the organization (`judgeSlug`:
+ * free; ours, an upgrade; system content the plugin replaces, adopted;
+ * another plugin's or a user's, refused naming the holder); and whether the
+ * plugin's members already converge on the head's digest (every planned
+ * member present, each carrying `stigmer.ai/plugin-version` equal to it),
+ * which is what lets a re-push of the same archive return without a child
+ * write.
  *
- * Proven by __tests__/members.test.ts and the conformance suite's
+ * Proven by __tests__/members.test.ts (the slug decision on plain values,
+ * convergence, the dropped set), __tests__/plugin.test.ts (adoption and
+ * refusal through a composed server) and the conformance suite's
  * listMembers, collision and reconcile arms.
  */
 import { fromBinary } from "@bufbuild/protobuf";
@@ -31,6 +34,7 @@ import type { ApiResourceMetadata } from "@stigmer/protos/ai/stigmer/commons/api
 import {
   PLUGIN_LABEL,
   PLUGIN_VERSION_LABEL,
+  isSystemContent,
   pluginIdOf,
 } from "../../pipeline/apiresource-labels.js";
 import { findResourceBySlug } from "../../pipeline/steps/helpers.js";
@@ -56,6 +60,8 @@ export interface Member {
   readonly name: string;
   /** The `stigmer.ai/plugin-version` value it was last materialised from. */
   readonly version: string;
+  /** Whether the stored row carries `stigmer.ai/system` (isSystemContent). */
+  readonly system: boolean;
 }
 
 /** A member the plan intends to exist after this push. */
@@ -63,6 +69,8 @@ export interface PlannedMember {
   readonly kind: ApiResourceKind;
   readonly slug: string;
   readonly name: string;
+  /** Whether the member the plugin brings declares `stigmer.ai/system`. */
+  readonly system: boolean;
 }
 
 function memberOf(
@@ -75,6 +83,7 @@ function memberOf(
     slug: metadata.slug,
     name: metadata.name,
     version: metadata.labels[PLUGIN_VERSION_LABEL] ?? "",
+    system: isSystemContent(metadata),
   };
 }
 
@@ -145,6 +154,66 @@ export async function slugHolder(
   };
 }
 
+/**
+ * What a push does about one planned slug, decided before any write.
+ *
+ *   free              nothing holds it; the member is created
+ *   ours              this plugin's own member; the push is an upgrade
+ *   adopt             system content no plugin manages, and the plugin
+ *                     brings system content for the same slug: the child's
+ *                     apply (upsert-by-slug) rewrites the row in place, so
+ *                     its id, its default instance, every personal instance
+ *                     and every session bound to them survive
+ *   held-unmanaged    a resource no plugin manages and the rule above does
+ *                     not admit; refused naming it
+ *   held-by-plugin    another plugin's member; refused naming that plugin
+ *
+ * Adoption is deliberately narrow, "system replaces system": the held row's
+ * label narrows which rows are eligible (a user's row never carries it on
+ * an edition that enforces reserved labels), and the plugin's own claim to
+ * the label was charged to `can_write_reserved_labels` by the sanitiser
+ * moments before, so the grant is the caller's live permission and never
+ * the label alone (pipeline/apiresource-labels.ts). It never transfers a
+ * member between plugins: another plugin's slug is refused whatever labels
+ * either side carries. The one case it exists for is the platform re-homing
+ * the content it seeded before plugins existed (the default agent; the
+ * platform's own server) without orphaning a single conversation.
+ */
+export type SlugDecision =
+  | { readonly kind: "free" }
+  | { readonly kind: "ours"; readonly holder: Member }
+  | { readonly kind: "adopt"; readonly holder: Member }
+  | { readonly kind: "held-unmanaged"; readonly holder: Member }
+  | {
+      readonly kind: "held-by-plugin";
+      readonly holder: Member;
+      readonly pluginId: string;
+    };
+
+export function judgeSlug(
+  holder: SlugHolder,
+  planned: PlannedMember,
+  pluginId: string,
+): SlugDecision {
+  if (!holder.held) {
+    return { kind: "free" };
+  }
+  if (holder.byPlugin === pluginId) {
+    return { kind: "ours", holder: holder.holder };
+  }
+  if (holder.byPlugin !== undefined) {
+    return {
+      kind: "held-by-plugin",
+      holder: holder.holder,
+      pluginId: holder.byPlugin,
+    };
+  }
+  if (holder.holder.system && planned.system) {
+    return { kind: "adopt", holder: holder.holder };
+  }
+  return { kind: "held-unmanaged", holder: holder.holder };
+}
+
 /**
  * Whether the stored members already ARE the plan at this digest: every
  * planned member present, none extra, each stamped with the digest.

package/src/domain/plugin/push.ts

@@ -19,8 +19,10 @@
  * digest, READY, every member present and stamped with it) the controller
  * returns the head and the install chain never runs, so a re-push writes
  * nothing. Everything that can refuse — the archive, the package, the
- * overlay, a reserved label, a held slug, a missing permission, the level
- * — refuses in the plan chain BEFORE any write; the install chain's own
+ * overlay, a reserved label, a held slug (unless it is system content the
+ * plugin replaces, which is adopted in place: members.ts, judgeSlug), a
+ * missing permission, the level — refuses in the plan chain BEFORE any
+ * write; the install chain's own
  * failures are a child's, wrapped with the plugin's name, and leave a head
  * that says FAILED so the next push of the same archive converges.
  *
@@ -52,6 +54,7 @@ import {
   PluginStatusSchema,
   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 { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
 import {
@@ -95,7 +98,7 @@ import { requireOperatorMaySetPublic } from "../../pipeline/steps/visibility-gat
 import { ResourceNotFoundError } from "../../store/interface.js";
 import type { Store } from "../../store/interface.js";
 import { openPluginArchive } from "./archive.js";
-import { VERSION_TAG_PATTERN } from "./constants.js";
+import { SERVER_WARNING_KINDS, VERSION_TAG_PATTERN } from "./constants.js";
 import type { OpenedPluginArchive } from "./archive.js";
 import type { PluginIdentity } from "./materialize/identity.js";
 import { McpServerOverlayError } from "./materialize/mcp-servers.js";
@@ -105,10 +108,11 @@ import type { PluginMaterializerProvider } from "./materialize/ports.js";
 import {
   droppedMembers,
   findMembers,
+  judgeSlug,
   membersConverge,
   slugHolder,
 } from "./members.js";
-import type { Member } from "./members.js";
+import type { Member, PlannedMember } from "./members.js";
 import { parseOverlays } from "./overlay/documents.js";
 import type { ParsedOverlays } from "./overlay/documents.js";
 import { OverlayParseError } from "./overlay/parse.js";
@@ -339,9 +343,11 @@ export function requestedVisibility(
 
 /**
  * PlanMaterialization — everything the push will write, checked whole:
- * every child slug against the organization (free, ours, or refused
- * naming the holder), the caller's permission for every member kind, and
- * the plugin's current members for the convergence and drop decisions.
+ * every child slug against the organization (free, ours, adopted system
+ * content, or refused naming the holder), the caller's permission for
+ * every member kind, and the plugin's current members for the convergence
+ * and drop decisions. An adopted slug is recorded as a warning on the plan,
+ * so the install receipt says which rows the plugin took over.
  */
 export function newPlanMaterializationStep(
   store: Store,
@@ -376,6 +382,7 @@ export function newPlanMaterializationStep(
         throw error;
       }
 
+      const adopted: PluginWarning[] = [];
       for (const member of plan.members) {
         let holder;
         try {
@@ -383,20 +390,41 @@ export function newPlanMaterializationStep(
         } catch (error) {
           throw internalError(error, "failed to check a member slug");
         }
-        if (!holder.held || holder.byPlugin === identity.id) {
-          continue;
-        }
+        const decision = judgeSlug(holder, member, identity.id);
         const noun = memberNoun(member.kind);
-        if (holder.byPlugin === undefined) {
-          throw alreadyExistsError(
-            noun,
-            `'${member.slug}' exists in org '${identity.org}' and is not managed by a plugin; rename or delete it first`,
-          );
+        switch (decision.kind) {
+          case "free":
+          case "ours":
+            break;
+          case "adopt":
+            adopted.push(
+              create(PluginWarningSchema, {
+                kind: SERVER_WARNING_KINDS.memberAdopted,
+                path: declaringDocumentOf(overlays, member),
+                message:
+                  `${noun} '${member.slug}' (${decision.holder.id}) was seeded by the platform before this plugin and is now managed by it; ` +
+                  "its definition is the plugin's, and its instances and conversations continue",
+              }),
+            );
+            break;
+          case "held-unmanaged":
+            throw alreadyExistsError(
+              noun,
+              `'${member.slug}' exists in org '${identity.org}' and is not managed by a plugin; rename or delete it first`,
+            );
+          case "held-by-plugin":
+            throw alreadyExistsError(
+              noun,
+              `'${member.slug}' is held by plugin '${await pluginSlugOf(store, decision.pluginId)}'`,
+            );
+          default: {
+            const exhaustive: never = decision;
+            throw internalError(
+              new Error(`unknown slug decision ${JSON.stringify(exhaustive)}`),
+              "failed to check a member slug",
+            );
+          }
         }
-        throw alreadyExistsError(
-          noun,
-          `'${member.slug}' is held by plugin '${await pluginSlugOf(store, holder.byPlugin)}'`,
-        );
       }
 
       const missing: string[] = [];
@@ -452,7 +480,12 @@ export function newPlanMaterializationStep(
       } catch (error) {
         throw internalError(error, "failed to list plugin members");
       }
-      ctx.set(PLUGIN_PLAN_KEY, plan);
+      // An adoption is something this push noticed and did not refuse, so it
+      // rides the plan's warnings onto the install receipt like the rest.
+      ctx.set(PLUGIN_PLAN_KEY, {
+        ...plan,
+        warnings: [...plan.warnings, ...adopted],
+      } satisfies MaterializationPlan);
       ctx.set(EXISTING_MEMBERS_KEY, members);
     },
   };
@@ -986,6 +1019,33 @@ function memberNoun(kind: ApiResourceKind): string {
   return MEMBER_NOUNS.get(kind) ?? ApiResourceKind[kind] ?? String(kind);
 }
 
+/**
+ * The overlay document that declared an adopted member, for the warning's
+ * path: only an overlay can carry the system label, so a skill (whose
+ * request carries the plugin's labels alone) never reaches this.
+ */
+function declaringDocumentOf(
+  overlays: ParsedOverlays,
+  member: PlannedMember,
+): string {
+  switch (member.kind) {
+    case ApiResourceKind.agent:
+      return overlays.agent?.path ?? "";
+    case ApiResourceKind.mcp_server:
+      return (
+        overlays.mcpServers.find((document) => document.server === member.name)
+          ?.path ?? ""
+      );
+    case ApiResourceKind.workflow:
+      return (
+        overlays.workflows.find((document) => document.name === member.name)
+          ?.path ?? ""
+      );
+    default:
+      return "";
+  }
+}
+
 /** The holding plugin's slug for a refusal; a dangling id names itself. */
 async function pluginSlugOf(store: Store, pluginId: string): Promise<string> {
   try {

package/src/domain/workflowexecution/lifecycle.ts

@@ -934,7 +934,7 @@ export async function recoverExecution(
               temporalConfig: deps.temporalConfig,
             },
             loadedExecution(ctx),
-            ctx.callerIdentity,
+            ctx.callerIdentity.identityId,
           );
         },
       },

package/src/pipeline/apiresource-labels.ts

@@ -13,7 +13,11 @@
  * authorizer's permissive default ALLOWS reserved-label writes by design
  * (the self-hosted operator owns the store), which is why a restrict-shaped
  * predicate here still pairs the label with server-owned state: the
- * plugin-managed guard refuses only beside an existing plugin row.
+ * plugin-managed guard refuses only beside an existing plugin row, and a
+ * plugin adopts a system-content row only when its own claim to the same
+ * label was just charged to `can_write_reserved_labels` by the sanitiser
+ * (domain/plugin/members.ts) — the label narrows which rows are eligible,
+ * the live authorization is what grants.
  */
 import type { ApiResourceMetadata } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
 
@@ -39,6 +43,20 @@ export const DEFAULT_INSTANCE_LABEL = `${RESERVED_LABEL_PREFIX}default-instance`
  */
 export const SYSTEM_MANAGED_LABEL = `${RESERVED_LABEL_PREFIX}system-managed`;
 
+/**
+ * Marks system content: a resource the platform itself seeded rather than a
+ * user authored — the system organization, the default agent, the
+ * platform's own MCP servers. The label predates this module (the retired
+ * seedpack wrote it on every row it applied; the official plugins' overlays
+ * carry it on the resources they replace) and has one server-side meaning:
+ * a plugin push may adopt a system-content row that holds a slug the plugin
+ * needs, keeping the row's id and everything bound to it, instead of
+ * refusing the slug as taken. It never marks a user's resource, so a user's
+ * row is never adopted (domain/plugin/members.ts, judgeSlug). The CLI names
+ * the same bytes as SYSTEM_ORG_LABEL for the organization it ensures.
+ */
+export const SYSTEM_LABEL = `${RESERVED_LABEL_PREFIX}system`;
+
 /**
  * The only value that activates a reserved marker label; any other value is
  * inert (matching cloud's "true".equals(...)). Stamped by the flows that
@@ -86,3 +104,10 @@ export function isDefaultInstance(
 ): boolean {
   return metadata?.labels[DEFAULT_INSTANCE_LABEL] === RESERVED_LABEL_TRUE;
 }
+
+/** Whether the metadata carries the SYSTEM_LABEL marker (undefined-safe). */
+export function isSystemContent(
+  metadata: ApiResourceMetadata | undefined,
+): boolean {
+  return metadata?.labels[SYSTEM_LABEL] === RESERVED_LABEL_TRUE;
+}

package/src/sandbox/__tests__/docker.integration.test.ts

@@ -68,7 +68,6 @@ describe.skipIf(!optedIn || !dockerAnswers())(
       await driver.ensureSessionSandbox(sessionId, {
         taskQueue: `session:${sessionId}`,
         stigmerToken: "tok-docker-smoke",
-        callerClass: "user",
       });
       expect(await driver.probe("session", sessionId)).toBe("running");
 
@@ -92,7 +91,6 @@ describe.skipIf(!optedIn || !dockerAnswers())(
       await driver.ensureSessionSandbox(sessionId, {
         taskQueue: `session:${sessionId}`,
         stigmerToken: "tok-docker-smoke",
-        callerClass: "user",
       });
       expect(await driver.probe("session", sessionId)).toBe("running");
 

package/src/sandbox/__tests__/kubernetes.test.ts

@@ -89,11 +89,7 @@ function fakeGateway(
   };
 }
 
-const env = {
-  taskQueue: "session:ses_1",
-  stigmerToken: "tok-1",
-  callerClass: "user",
-};
+const env = { taskQueue: "session:ses_1", stigmerToken: "tok-1" };
 
 describe("the ensure state machine", () => {
   it("absent → Secret, PVC, Deployment — in that order, no readiness wait", async () => {
@@ -215,11 +211,7 @@ describe("the manifest shapes (the Java SandboxManifestFactory pins)", () => {
   });
 
   it("a token-less sandbox omits the token env but keeps the (empty) Secret", () => {
-    const tokenless = {
-      taskQueue: "session:ses_1",
-      stigmerToken: "",
-      callerClass: "user",
-    };
+    const tokenless = { taskQueue: "session:ses_1", stigmerToken: "" };
     const deployment = buildSandboxDeployment(
       "session",
       "ses_1",

package/src/sandbox/__tests__/local-process.integration.test.ts

@@ -81,7 +81,6 @@ describe.skipIf(process.platform === "win32")(
       await driver.ensureSessionSandbox("ses_smoke", {
         taskQueue: "session:ses_smoke",
         stigmerToken: "tok-smoke",
-        callerClass: "user",
       });
       await vi.waitFor(() => expect(spawnCount()).toBe(1), {
         timeout: CHILD_SETTLE_TIMEOUT_MS,
@@ -92,7 +91,6 @@ describe.skipIf(process.platform === "win32")(
       await driver.ensureSessionSandbox("ses_smoke", {
         taskQueue: "session:ses_smoke",
         stigmerToken: "tok-smoke",
-        callerClass: "user",
       });
       expect(spawnCount()).toBe(1);
 
@@ -126,7 +124,6 @@ describe.skipIf(process.platform === "win32")(
       await driver.ensureSessionSandbox("ses_smoke", {
         taskQueue: "session:ses_smoke",
         stigmerToken: "",
-        callerClass: "user",
       });
       await vi.waitFor(() => expect(spawnCount()).toBe(2), {
         timeout: CHILD_SETTLE_TIMEOUT_MS,