@stigmer/server 3.15.3-dev.20260914121148 → 3.16.0

package/src/domain/mcpserver/connect-execution-id.ts

@@ -0,0 +1,34 @@
+/**
+ * The synthetic execution id of an MCP connect — the ONE home for its
+ * shape, built here by the connect lane and recognized here by the
+ * runner-credential lane, so the two can never drift apart.
+ *
+ * A connect is not an execution: it has no AgentExecution or
+ * WorkflowExecution row. What it has is an ephemeral ExecutionContext
+ * (connect.ts `createConnectExecutionContext`) whose `spec.execution_id`
+ * must name SOMETHING for the decrypt lane's binding check
+ * (executioncontext/resolve-values-for-caller.ts: the token's
+ * `execution_id` claim must equal the EC's), and this id is that
+ * something — an id that names no resource kind, so the contract's
+ * `kind_meta` prefix table (pipeline/apiresource-meta.ts) cannot mistake
+ * it for a row. The runner-credential lane reads it the other way round
+ * (runnerauth/bound-execution.ts `boundExecutionKindOf`): an id this
+ * predicate recognizes is a connect binding, resolved through the EC row
+ * whose `spec.execution_id` it is. Keep the builder and the predicate
+ * together; a second copy of the prefix anywhere would be the drift this
+ * module exists to prevent.
+ */
+import { randomUUID } from "node:crypto";
+
+/** The prefix every connect execution id carries — no resource kind's id starts with it. */
+const CONNECT_EXECUTION_ID_PREFIX = "connect-";
+
+/** One connect's execution id: the server it discovers plus eight hex of entropy per attempt. */
+export function newConnectExecutionId(mcpServerId: string): string {
+  return `${CONNECT_EXECUTION_ID_PREFIX}${mcpServerId}-${randomUUID().slice(0, 8)}`;
+}
+
+/** Whether `executionId` is a connect's — the runner-credential lane's recognition of the third binding. */
+export function isConnectExecutionId(executionId: string): boolean {
+  return executionId.startsWith(CONNECT_EXECUTION_ID_PREFIX);
+}

package/src/domain/mcpserver/connect.ts

@@ -17,7 +17,6 @@
 import { create } from "@bufbuild/protobuf";
 import type { MessageInitShape } from "@bufbuild/protobuf";
 import { Code, ConnectError } from "@connectrpc/connect";
-import { randomUUID } from "node:crypto";
 
 import type {
   EnvironmentList,
@@ -62,6 +61,7 @@ import type {
 } from "../../store/interface.js";
 import { ResourceNotFoundError } from "../../store/interface.js";
 import { resolveOAuthAppRef } from "../oauthapp/refresolution.js";
+import { newConnectExecutionId } from "./connect-execution-id.js";
 import {
   persistConnectFailure,
   persistConnectResult,
@@ -169,10 +169,21 @@ export interface ConnectEnvironmentReader {
 /**
  * The ExecutionContext lifecycle surface for the ephemeral connect EC —
  * Go's downstream executioncontext client (create + delete).
+ *
+ * `create` takes the connecting caller and the composition creates the
+ * row AS THAT PERSON (boot/inprocess.ts, the `asCaller` lane of ruling
+ * R5), never under the internal class: the row's creator stamp is what
+ * the runner-subject verifier resolves the connect's person from when
+ * the runner presents the connect token under the built-in posture
+ * (runnerauth/bound-execution.ts, the `mcp-connect` binding). A row
+ * stamped `internal` would name nobody, and the credentialed connect
+ * would be refused at identity on every enforcing self-host. `delete`
+ * stays the server's own act: the row is the lane's, whoever asked.
  */
 export interface ConnectExecutionContextClient {
   create(
     executionContext: MessageInitShape<typeof ExecutionContextSchema>,
+    caller: CallerIdentity,
   ): Promise<ExecutionContext>;
   delete(
     input: MessageInitShape<typeof ApiResourceDeleteInputSchema>,
@@ -272,7 +283,7 @@ export async function connect(
     input,
   );
 
-  const prepared = await prepareConnect(deps, mcpServer, input);
+  const prepared = await prepareConnect(deps, mcpServer, input, identity);
 
   try {
     let run: ConnectRun;
@@ -385,11 +396,28 @@ export async function connect(
  * read the caller's grant and secrets, which a background task has no
  * request context to do (the same constraint that scopes
  * startBestEffortConnect to env-less servers).
+ *
+ * A connect's discovery runs on the runner with TWO credentials, and the
+ * split is deliberate. The runner's own process credential reads the
+ * McpServer's metadata — under the built-in posture that credential is
+ * the operator's API key, and the operator is an organization admin
+ * (deploy/helm/stigmer: the signed-in operator mints the runner's key),
+ * whom the model makes an owner of every McpServer in the organization
+ * (authorization/model/mcp_server.ts), so a member's private server is
+ * readable. The connect token minted below reads the SECRETS: it is
+ * bound to this connect's ExecutionContext, and under the built-in
+ * posture the runner-subject verifier resolves its bearer to the person
+ * that row was created by — which is why the row is created as `identity`
+ * and not as the server. The end state where every RPC of a discovery
+ * acts as the person (the cloud's connect-sandbox shape) needs a row an
+ * env-less connect would also create; it creates none today, so that is
+ * a design act of its own, not a widening to make here.
  */
 export async function prepareConnect(
   deps: McpServerConnectDeps,
   mcpServer: McpServer,
   input: ConnectInput,
+  identity: CallerIdentity,
 ): Promise<PreparedConnect> {
   const mcpServerId = mcpServer.metadata?.id ?? "";
   const callerOrg = input.org;
@@ -402,7 +430,7 @@ export async function prepareConnect(
     await refreshOAuthTokenIfNeeded(deps, mcpServer, callerOrg);
   }
 
-  const executionId = `connect-${mcpServerId}-${randomUUID().slice(0, 8)}`;
+  const executionId = newConnectExecutionId(mcpServerId);
 
   const ecResourceId = await createConnectExecutionContext(
     deps,
@@ -410,6 +438,7 @@ export async function prepareConnect(
     executionId,
     callerOrg,
     input.runtimeEnv,
+    identity,
   );
 
   const workflowInput: ConnectWorkflowInput = {
@@ -464,6 +493,10 @@ export async function prepareConnect(
  * sources: OAuth-managed variables from the grant's managed environment,
  * the remainder from the user's personal environment. Returns "" when the
  * MCP server has no env declarations and no runtime_env.
+ *
+ * The row is created as `caller`, the person connecting (see the
+ * ConnectExecutionContextClient doc): its creator stamp is the connect
+ * token's person under the built-in posture.
  */
 async function createConnectExecutionContext(
   deps: McpServerConnectDeps,
@@ -471,6 +504,7 @@ async function createConnectExecutionContext(
   executionId: string,
   callerOrg: string,
   runtimeEnv: { [key: string]: ExecutionValue },
+  caller: CallerIdentity,
 ): Promise<string> {
   let ecData: { [key: string]: ExecutionValue };
 
@@ -540,6 +574,7 @@ async function createConnectExecutionContext(
           data: ecData,
         },
       }),
+      caller,
     );
   } catch (error) {
     throw internalError(error, "failed to create connect ExecutionContext");

package/src/domain/mcpserver/controller.ts

@@ -77,6 +77,7 @@ import {
   EXISTING_RESOURCE_KEY,
   newLoadExistingStep,
 } from "../../pipeline/steps/load-existing.js";
+import { newGuardPluginManagedStep } from "../../pipeline/steps/guard-plugin-managed.js";
 import {
   SHOULD_CREATE_KEY,
   newLoadForApplyStep,
@@ -269,6 +270,10 @@ async function update(
     .addStep(newValidateProtoStep())
     .addStep(newResolveSlugStep())
     .addStep(newLoadExistingStep(deps.store))
+    // A resource a plugin materialised is the plugin's to redefine; a client
+    // write is refused naming the plugin (GuardPluginManaged, keyed on the
+    // STORED labels and the plugin row's existence).
+    .addStep(newGuardPluginManagedStep(deps.store))
     .addStep(newBuildUpdateStateStep())
     .addStep(newGuardReservedLabelsStep(deps.authorizer))
     .addStep(newValidateDefaultEnabledToolsStep())
@@ -374,6 +379,7 @@ async function deleteMcpServer(
     )
     .addStep(newValidateProtoStep())
     .addStep(newLoadExistingForDeleteStep(deps.store, McpServerSchema))
+    .addStep(newGuardPluginManagedStep(deps.store))
     .addStep(newDeleteResourceStep(deps.store))
     .addStep(
       newCleanupIamPoliciesStep(deps.authorizationLifecycle, deps.logger),
@@ -426,6 +432,11 @@ async function updateVisibility(
     )
     .addStep(newValidateProtoStep())
     .addStep(newLoadMcpServerForVisibilityUpdateStep(deps.store))
+    .addStep(
+      newGuardPluginManagedStep(deps.store, {
+        existingKey: UPDATE_VISIBILITY_MCP_SERVER_KEY,
+      }),
+    )
     .addStep(
       newRecordVisibilityBeforeUpdateStep(UPDATE_VISIBILITY_MCP_SERVER_KEY),
     )

package/src/domain/mcpserver/engine.ts

@@ -26,9 +26,15 @@
  * read RPC redacts secrets unless the caller presents an execution-scoped
  * runner token, and the discovery activity has no execution of its own to
  * exchange for one — the capability travels with the work item. It is a
- * decrypt-lane discriminator, not a secret value: short-TTL, bound to
- * this connect flow's ephemeral EC (deleted when the handler returns),
- * and useless once either expires.
+ * short-TTL token bound to this connect flow's ephemeral EC (deleted when
+ * the connect settles, on the blocking lane and the async one alike) and
+ * useless once either expires. What it unlocks depends on the posture:
+ * under trusted-local it is a decrypt-lane discriminator and nothing more;
+ * under the built-in authorization posture the same token also admits its
+ * bearer AS THE PERSON who asked for the connect, on every RPC, for as
+ * long as the EC row exists (runnerauth/runnerauth.ts, the two lanes by
+ * posture; runnerauth/bound-execution.ts, the `mcp-connect` binding). It
+ * sits in Temporal history in the clear like every server-written input.
  */
 export interface ConnectWorkflowInput {
   readonly mcp_server_id: string;

package/src/domain/mcpserver/start-connect.ts

@@ -118,7 +118,7 @@ export async function startConnect(
     }
   }
 
-  const prepared = await prepareConnect(deps, mcpServer, input);
+  const prepared = await prepareConnect(deps, mcpServer, input, identity);
 
   // Taken before the start so the advisory describes the queue the run is
   // about to join. Warn-only by design: a worker may be booting (the

package/src/domain/platform/controller.ts

@@ -10,21 +10,34 @@
  * composed-server pattern).
  *
  * getRunnerScopedToken is the mint side of the runner-token lane
- * (oss#535) — the seam src/runnerauth/ reserved for this sub-project. OSS
- * has no caller identity, so unlike the cloud exchange there is no
- * credential to verify: any caller naming an execution receives a token
- * for it. On a single-user server the token is the LANE DISCRIMINATOR that
- * lets the EC read RPCs redact by default without breaking the runner, not
- * a trust boundary (DD-004).
+ * (oss#535) — the seam src/runnerauth/. What the token IS depends on the
+ * server's posture, and so does who may obtain one:
+ *
+ *   - Under trusted-local (the laptop: one caller, nothing to separate)
+ *     the arms below mint a clocked token for any caller naming an
+ *     execution. The token is the LANE DISCRIMINATOR that lets the
+ *     ExecutionContext read RPCs redact by default without breaking the
+ *     runner, not a trust boundary — there is no identity for it to
+ *     change.
+ *   - Under the built-in authorization posture the same token is an
+ *     IDENTITY: the runner-subject verifier admits its bearer as the
+ *     human whose run it is (runnerauth/runner-subject-verifier.ts). A
+ *     mint for anyone would be impersonation, so the built-in provider
+ *     defines exchangeScopedToken and this controller delegates to it:
+ *     the run credential is minted for the run's own person and nobody
+ *     else (runnerauth/built-in-runner-credential-provider.ts). Runs get
+ *     their credential from the dispatch itself (the engine clients put
+ *     it on the workflow input); this exchange is the runner's fallback.
  *
  * The C4 capability delegation (20260827.09, gate ruling Q1): when the
  * composed provider defines exchangeScopedToken / bootstrapCredentials,
  * this controller delegates the exchange arms and the bootstrap
- * credential fields to it wholesale — the cloud's per-arm caller-class
- * gating, row authorization, and multi-lane minting are POLICY, not
- * contract, and live behind the seam. With neither defined (the OSS
- * default), every arm below behaves exactly as before; the conformance
- * suites pin that byte-identity.
+ * credential fields to it wholesale — per-arm caller gating, row
+ * authorization, and multi-lane minting are POLICY, not contract, and
+ * live behind the seam (the cloud's four-arm exchange; open source's
+ * built-in gate). With neither defined (the trusted-local default), every
+ * arm below behaves exactly as before; the conformance suites pin that
+ * byte-identity.
  */
 import type { ConnectRouter, HandlerContext } from "@connectrpc/connect";
 import { create } from "@bufbuild/protobuf";

package/src/domain/plugin/__tests__/materialize.test.ts

@@ -0,0 +1,303 @@
+/**
+ * Pins the pure half of a push — what the plan says a package becomes,
+ * before any write: the composed agent's instructions (the versioned
+ * template, snapshot-pinned), a sub-agent's mcp_access naming server
+ * SLUGS while `model_override` stays empty and the hint becomes a warning,
+ * a built-in name becoming a warning, an MCP-only package planning no
+ * agent, the `mcpServers` key-to-slug rule, a skill archive rooted at its
+ * SKILL.md with the plugin's labels on the request, a version the tag
+ * pattern rejects becoming a warning, an overlay that redefines the
+ * transport refused, and the convergence and drop rules over members.
+ */
+import { describe, expect, it } from "vitest";
+
+import {
+  inMemoryPluginFiles,
+  readPluginPackage,
+} from "@stigmer/plugin-package";
+import type { PluginPackage } from "@stigmer/plugin-package";
+import { cursorPlugin, openPlugin } from "@stigmer/plugin-package/testing";
+import type { PluginFixture } from "@stigmer/plugin-package/testing";
+import { create } from "@bufbuild/protobuf";
+import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import {
+  McpServerSpecSchema,
+  StdioServerConfigSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_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 { inflateEntry } from "../../../archive/inflate.js";
+import { openArchive } from "../../../archive/open.js";
+import {
+  PLUGIN_LABEL,
+  PLUGIN_VERSION_LABEL,
+} from "../../../pipeline/apiresource-labels.js";
+import {
+  DEFAULT_AGENT_INSTRUCTIONS_VERSION,
+  renderDefaultAgentInstructions,
+} from "../materialize/default-agent-instructions.js";
+import type { PluginIdentity } from "../materialize/identity.js";
+import { McpServerOverlayError } from "../materialize/mcp-servers.js";
+import { planMaterialization } from "../materialize/plan.js";
+import { droppedMembers, membersConverge } from "../members.js";
+import type { Member } from "../members.js";
+
+const IDENTITY: PluginIdentity = {
+  org: "acme",
+  id: "plg_1",
+  slug: "thermos",
+  name: "thermos",
+  digest: "d".repeat(64),
+  visibility: ApiResourceVisibility.visibility_org,
+};
+
+function read(fixture: PluginFixture): PluginPackage {
+  const outcome = readPluginPackage(inMemoryPluginFiles(fixture));
+  if (!outcome.ok) {
+    throw new Error(outcome.errors.map((e) => e.message).join("\n"));
+  }
+  return outcome.plugin;
+}
+
+const thermos = cursorPlugin({
+  name: "thermos",
+  version: "1.2.0",
+  description: "Code review with a thermonuclear standard",
+  skills: [
+    {
+      name: "thermo-review",
+      description: "Review code thoroughly",
+      body: "# Review",
+      files: { "references/checklist.md": "- read it all" },
+    },
+  ],
+  agents: [
+    {
+      file: "reviewer",
+      frontmatter: {
+        name: "reviewer",
+        description: "Reviews",
+        model: "sonnet",
+      },
+      body: "You review pull requests with care.",
+    },
+    {
+      file: "explore",
+      frontmatter: { name: "explore", description: "Shadows a built-in" },
+      body: "You explore the repository far and wide.",
+    },
+  ],
+  mcpServers: {
+    my_github: {
+      type: "http",
+      url: "https://api.githubcopilot.com/mcp/",
+      headers: { Authorization: "Bearer ${GITHUB_TOKEN}" },
+    },
+  },
+  variables: { GITHUB_TOKEN: { type: "string", title: "Token" } },
+  required: ["GITHUB_TOKEN"],
+});
+
+describe("renderDefaultAgentInstructions", () => {
+  it("renders the versioned template for the package", () => {
+    expect(DEFAULT_AGENT_INSTRUCTIONS_VERSION).toBe(1);
+    expect(renderDefaultAgentInstructions(read(thermos))).toBe(
+      [
+        "You are thermos: Code review with a thermonuclear standard",
+        "",
+        "Your skills:",
+        "- thermo-review: Review code thoroughly",
+        "",
+        "Your tools come from these MCP servers:",
+        "- my_github",
+        "",
+        "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.",
+      ].join("\n"),
+    );
+  });
+});
+
+describe("planMaterialization", () => {
+  const pkg = read(thermos);
+  const plan = planMaterialization(
+    pkg,
+    inMemoryPluginFiles(thermos),
+    { workflows: [], mcpServers: [] },
+    IDENTITY,
+    "first",
+  );
+
+  it("plans one skill, one server and one agent, in materialisation order", () => {
+    expect(
+      plan.members.map((m) => `${ApiResourceKind[m.kind]}:${m.slug}`),
+    ).toEqual(["skill:thermo-review", "mcp_server:mygithub", "agent:thermos"]);
+    expect(plan.tag).toBe("1.2.0");
+  });
+
+  it("writes the skill's archive rooted at SKILL.md and stamps the plugin's labels on the request", () => {
+    const skill = plan.skills[0]!;
+    expect(skill.request.labels).toEqual({
+      [PLUGIN_LABEL]: "plg_1",
+      [PLUGIN_VERSION_LABEL]: "d".repeat(64),
+    });
+    expect(skill.request.tag).toBe("1.2.0");
+    expect(skill.request.message).toBe("first");
+    const { entries } = openArchive(skill.request.artifact);
+    expect(entries.map((e) => e.name)).toEqual([
+      "SKILL.md",
+      "references/checklist.md",
+    ]);
+    expect(
+      new TextDecoder().decode(inflateEntry(entries[0]!.entry, 1 << 20)),
+    ).toContain("name: thermo-review");
+  });
+
+  it("names servers by slug everywhere a sub-agent or usage refers to them", () => {
+    expect(plan.mcpServers[0]).toMatchObject({
+      name: "my_github",
+      slug: "mygithub",
+    });
+    expect(
+      plan.mcpServers[0]!.resource.spec?.env["GITHUB_TOKEN"],
+    ).toMatchObject({ isSecret: true, optional: false });
+    const agent = plan.agent!.resource;
+    expect(
+      agent.spec?.mcpServerUsages.map((u) => u.mcpServerRef?.slug),
+    ).toEqual(["mygithub"]);
+    expect(
+      agent.spec?.subAgents.map((s) => s.mcpAccess.map((a) => a.mcpServer)),
+    ).toEqual([["mygithub"], ["mygithub"]]);
+  });
+
+  it("records a model hint and a built-in name as warnings and never sets model_override", () => {
+    expect(
+      plan.agent!.resource.spec?.subAgents.map((s) => s.modelOverride),
+    ).toEqual(["", ""]);
+    expect(plan.warnings.map((w) => `${w.kind}:${w.path}`)).toEqual(
+      expect.arrayContaining([
+        "model-hint-unresolved:agents/reviewer.md",
+        "sub-agent-name-builtin:agents/explore.md",
+      ]),
+    );
+  });
+
+  it("plans no agent for an MCP-only package", () => {
+    const mcpOnly = openPlugin({
+      name: "github",
+      mcpServers: {
+        github: { type: "streamable-http", url: "https://example.com/mcp" },
+      },
+    });
+    const onlyPlan = planMaterialization(
+      read(mcpOnly),
+      inMemoryPluginFiles(mcpOnly),
+      { workflows: [], mcpServers: [] },
+      IDENTITY,
+      "",
+    );
+    expect(onlyPlan.agent).toBeUndefined();
+    expect(onlyPlan.members.map((m) => ApiResourceKind[m.kind])).toEqual([
+      "mcp_server",
+    ]);
+  });
+
+  it("warns and leaves the tag empty when the manifest version does not fit the tag pattern", () => {
+    const built = cursorPlugin({
+      name: "b",
+      version: "1.0.0+build.7",
+      skills: [{ name: "s" }],
+    });
+    const builtPlan = planMaterialization(
+      read(built),
+      inMemoryPluginFiles(built),
+      { workflows: [], mcpServers: [] },
+      IDENTITY,
+      "",
+    );
+    expect(builtPlan.tag).toBe("");
+    expect(builtPlan.warnings.map((w) => w.kind)).toContain(
+      "version-not-taggable",
+    );
+    expect(builtPlan.skills[0]!.request.tag).toBe("");
+  });
+
+  it("refuses a server overlay that redefines the transport", () => {
+    const overlay = create(McpServerSchema, {
+      spec: create(McpServerSpecSchema, {
+        serverType: {
+          case: "stdio",
+          value: create(StdioServerConfigSchema, { command: "npx" }),
+        },
+      }),
+    });
+    expect(() =>
+      planMaterialization(
+        pkg,
+        inMemoryPluginFiles(thermos),
+        {
+          workflows: [],
+          mcpServers: [
+            {
+              path: "ai.stigmer/mcp-servers/my_github.yaml",
+              server: "my_github",
+              resource: overlay,
+            },
+          ],
+        },
+        IDENTITY,
+        "",
+      ),
+    ).toThrow(McpServerOverlayError);
+  });
+});
+
+describe("members: convergence and drops", () => {
+  const digest = "d".repeat(64);
+  const stored: Member[] = [
+    {
+      kind: ApiResourceKind.skill,
+      id: "skl_1",
+      slug: "thermo-review",
+      name: "thermo-review",
+      version: digest,
+    },
+    {
+      kind: ApiResourceKind.agent,
+      id: "agt_1",
+      slug: "thermos",
+      name: "thermos",
+      version: digest,
+    },
+  ];
+  const planned = [
+    {
+      kind: ApiResourceKind.skill,
+      slug: "thermo-review",
+      name: "thermo-review",
+    },
+    { kind: ApiResourceKind.agent, slug: "thermos", name: "thermos" },
+  ];
+
+  it("converges only when every planned member is present and stamped with the digest", () => {
+    expect(membersConverge(stored, planned, digest)).toBe(true);
+    expect(membersConverge(stored, planned, "e".repeat(64))).toBe(false);
+    expect(membersConverge(stored.slice(1), planned, digest)).toBe(false);
+    expect(
+      membersConverge(
+        [...stored, { ...stored[0]!, slug: "extra", id: "skl_2" }],
+        planned,
+        digest,
+      ),
+    ).toBe(false);
+  });
+
+  it("drops the members the plan no longer names", () => {
+    expect(droppedMembers(stored, planned.slice(1)).map((m) => m.slug)).toEqual(
+      ["thermo-review"],
+    );
+    expect(droppedMembers(stored, planned)).toEqual([]);
+  });
+});

package/src/domain/plugin/__tests__/overlay-parse.test.ts

@@ -0,0 +1,85 @@
+/**
+ * Pins the overlay parser as the server twin of the SDK's strict manifest
+ * parse: a document the CLI accepts parses (camelCase and proto field
+ * names both), an unknown field refuses naming the path, a wrong `kind`
+ * refuses, a missing `kind` refuses, an empty or non-mapping document
+ * refuses, a foreign `metadata.org` refuses while an empty or matching
+ * one passes, and malformed YAML refuses with the parser's message.
+ */
+import { describe, expect, it } from "vitest";
+
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+
+import { OverlayParseError, parseOverlayDocument } from "../overlay/parse.js";
+
+const encoder = new TextEncoder();
+const AGENT = { schema: AgentSchema, yamlKind: "Agent", org: "acme" };
+
+function parse(text: string) {
+  return parseOverlayDocument(
+    "ai.stigmer/agent.yaml",
+    encoder.encode(text),
+    AGENT,
+  );
+}
+
+function refusal(text: string): string {
+  try {
+    parse(text);
+  } catch (error) {
+    expect(error).toBeInstanceOf(OverlayParseError);
+    return (error as OverlayParseError).message;
+  }
+  throw new Error("expected a refusal");
+}
+
+describe("parseOverlayDocument", () => {
+  it("parses a document the CLI accepts, in either field casing", () => {
+    const agent = parse(
+      "apiVersion: agentic.stigmer.ai/v1\nkind: Agent\nmetadata:\n  name: thermos\nspec:\n  instructions: Long enough instructions here.\n  skill_refs:\n    - slug: a\n  skillRefs:\n    - slug: b\n",
+    );
+    expect(agent.metadata?.name).toBe("thermos");
+    expect(agent.spec?.skillRefs.map((r) => r.slug)).toContain("b");
+  });
+
+  it("refuses an unknown field, naming the document", () => {
+    expect(
+      refusal("kind: Agent\nmetadata:\n  name: t\nspec:\n  colour: blue\n"),
+    ).toContain("overlay document 'ai.stigmer/agent.yaml': invalid Agent:");
+  });
+
+  it("refuses a kind other than the one its location holds", () => {
+    expect(refusal("kind: Workflow\nmetadata:\n  name: t\n")).toBe(
+      "overlay document 'ai.stigmer/agent.yaml': kind 'Workflow' is not the Agent this location holds",
+    );
+  });
+
+  it("refuses a missing kind", () => {
+    expect(refusal("metadata:\n  name: t\n")).toContain(
+      "missing the required 'kind' field (expected kind: Agent)",
+    );
+  });
+
+  it("refuses an empty or non-mapping document", () => {
+    expect(refusal("   \n")).toContain("the document is empty");
+    expect(refusal("- a\n- b\n")).toContain("expected a mapping document");
+  });
+
+  it("refuses a foreign org and accepts an empty or matching one", () => {
+    expect(
+      refusal("kind: Agent\nmetadata:\n  name: t\n  org: other\n"),
+    ).toContain(
+      "metadata.org 'other' is not the organization the plugin is installed into ('acme')",
+    );
+    expect(
+      parse("kind: Agent\nmetadata:\n  name: t\n  org: acme\n").metadata?.org,
+    ).toBe("acme");
+    expect(parse("kind: Agent\nmetadata:\n  name: t\n").metadata?.org).toBe("");
+  });
+
+  it("refuses malformed YAML with the parser's message", () => {
+    expect(refusal("kind: Agent\nmetadata: [unclosed\n")).toContain(
+      "invalid YAML:",
+    );
+  });
+});