@@ -0,0 +1,12 @@
+---
+'@objectstack/mcp': patch
+---
+
+fix(mcp): `agent_prompt` reads an agent through the protocol read `GET /api/v1/meta/agent/NAME` serves, so an agent a package ships is advertised and served
+
+Clause-②: yes (widening)
+Metadata-protocol: none
+
+The stdio MCP server's `agent_prompt` read agents from the kernel `metadata` service, which holds no copy of an agent a package ships (it lives in the registry the protocol reads). So a boot whose only agent came from a package did not list `agent_prompt`, and a get could not serve that agent, while `GET /api/v1/meta/agent/NAME` served it. Now, where the host's read has both the protocol's reads (the `protocol` service does), `agent_prompt` resolves the agent through its by-name read (`getMetaItem`) and the roster that decides whether the prompt is advertised reads its merged listing (`getMetaItems`), with the metadata service's completeness verdict kept on top as for skill prompts. One reader per host, decided once for both the roster and the get: a host without both reads reads the metadata service exactly as before, for both. A miss still answers `Error: Agent "X" not found`, and a by-name read refused `SERVICE_UNAVAILABLE` still answers the outage text with no instructions.
+
+`McpMergedMetadataRead`, the type of `MCPServerRuntime.bridgePrompts`' second parameter, gains an optional `getMetaItem(request)` member; a host that passes an object without it is read as before, the roster included.
@@ -232,3 +232,200 @@ describe('agent_prompt — advertised only where an agent can answer it', () =>
     }
   });
 });
+
+/**
+ * [#31514] `agent_prompt` reads an agent through the protocol, the read
+ * `GET /api/v1/meta/agent/NAME` serves, and its advertisement reads the
+ * protocol's listing, `GET /api/v1/meta/agent`'s. An agent a package ships
+ * lives in the registry the protocol reads; the kernel `metadata` service holds
+ * no copy of it, so the metadata double below holds none (`get` answers
+ * `undefined`, `list` answers `[]`), and the protocol double serves it. The
+ * real-kernel twin of these pins is
+ * `packages/qa/dogfood/test/mcp-stdio-package-object-discovery.test.ts`.
+ */
+describe('agent_prompt — one reader with GET /meta/agent/NAME (the protocol)', () => {
+  const PACKAGE_AGENT = {
+    name: 'pkg_helper',
+    label: 'Package Helper',
+    instructions: 'You help with what the package ships.',
+    active: true,
+  };
+
+  /** A protocol double: the merged listing and the by-name read, over `agents` and `skills`. */
+  function protocol({ agents = [PACKAGE_AGENT], skills = [SKILL], byName }: {
+    agents?: unknown[];
+    skills?: unknown[];
+    byName?: (request: { type: string; name: string }) => Promise<unknown>;
+  } = {}) {
+    const itemsOf = (type: string) => (type === 'agent' ? agents : type === 'skill' ? skills : []);
+    return {
+      getMetaItems: vi.fn(async ({ type }: { type: string }) => ({ type, items: itemsOf(type) })),
+      getMetaItem: vi.fn(byName ?? (async ({ type, name }: { type: string; name: string }) => ({
+        type,
+        name,
+        item: (itemsOf(type) as Array<{ name: string }>).find((i) => i.name === name),
+      }))),
+    };
+  }
+
+  async function connectWith(service: ReturnType<typeof metadataService>, read: unknown) {
+    const log = logger();
+    const runtime = new MCPServerRuntime({ name: 'objectstack-test', version: '9.9.9', logger: log as never });
+    await runtime.bridgePrompts(service as never, read as never);
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    const client = new Client({ name: 'test-client', version: '0.0.0' });
+    await Promise.all([runtime.server.connect(serverTransport), client.connect(clientTransport)]);
+    return {
+      client,
+      log,
+      close: async () => {
+        await client.close();
+        await runtime.stop().catch(() => {});
+      },
+    };
+  }
+
+  /** Every call the metadata double took for the `agent` type. */
+  const agentCallsOn = (service: ReturnType<typeof metadataService>) =>
+    [service.get, service.list, service.listDiagnosed]
+      .flatMap((fn) => (fn as ReturnType<typeof vi.fn>).mock.calls)
+      .filter((args) => args[0] === 'agent');
+
+  it('a boot whose only agent a package ships lists agent_prompt, and the argument names that agent', async () => {
+    const service = metadataService({ agents: [] });
+    const session = await connectWith(service, protocol());
+    try {
+      const listed = await session.client.listPrompts();
+      expect(listed.prompts.map((p) => p.name)).toContain('agent_prompt');
+      expect(agentNameDescription(listed.prompts)).toContain('"pkg_helper"');
+    } finally {
+      await session.close();
+    }
+  });
+
+  it('serves the package agent with the instructions the protocol\'s by-name read answers, and never asks the metadata service for it', async () => {
+    const service = metadataService({ agents: [] });
+    const read = protocol();
+    const session = await connectWith(service, read);
+    try {
+      const served = await session.client.getPrompt({ name: 'agent_prompt', arguments: { agentName: 'pkg_helper' } });
+      const answered = (await read.getMetaItem({ type: 'agent', name: 'pkg_helper' })) as { item: { instructions: string } };
+      expect(served.messages).toEqual([
+        { role: 'assistant', content: { type: 'text', text: answered.item.instructions } },
+      ]);
+      expect(read.getMetaItem).toHaveBeenCalledWith({ type: 'agent', name: 'pkg_helper' });
+      expect(agentCallsOn(service).filter((args) => args[1] === 'pkg_helper')).toEqual([]);
+    } finally {
+      await session.close();
+    }
+  });
+
+  it('CONTROL: an environment agent is served as before', async () => {
+    const service = metadataService({ agents: [AGENT] });
+    const session = await connectWith(service, protocol({ agents: [AGENT, PACKAGE_AGENT] }));
+    try {
+      const listed = await session.client.listPrompts();
+      expect(agentNameDescription(listed.prompts)).toContain('"support_triage"');
+      const served = await session.client.getPrompt({
+        name: 'agent_prompt',
+        arguments: { agentName: 'support_triage', objectName: 'case' },
+      });
+      expect(served.messages).toEqual([
+        { role: 'assistant', content: { type: 'text', text: 'You triage support cases.\n\n--- Current Context ---\nCurrent object: case' } },
+      ]);
+    } finally {
+      await session.close();
+    }
+  });
+
+  it('a name the protocol does not serve keeps today\'s miss answer', async () => {
+    const session = await connectWith(metadataService({ agents: [] }), protocol());
+    try {
+      const miss = await session.client.getPrompt({ name: 'agent_prompt', arguments: { agentName: 'nope' } });
+      expect(miss.messages).toEqual([
+        { role: 'user', content: { type: 'text', text: 'Error: Agent "nope" not found' } },
+      ]);
+    } finally {
+      await session.close();
+    }
+  });
+
+  it('a by-name read refused SERVICE_UNAVAILABLE (503) answers the #6055 outage text and serves no instructions', async () => {
+    const outage = Object.assign(new Error('The metadata store could not be read.'), { code: 'SERVICE_UNAVAILABLE', status: 503 });
+    const session = await connectWith(
+      metadataService({ agents: [] }),
+      protocol({ byName: async () => { throw outage; } }),
+    );
+    try {
+      const answer = await session.client.getPrompt({ name: 'agent_prompt', arguments: { agentName: 'pkg_helper' } });
+      expect(answer.messages).toHaveLength(1);
+      expect(answer.messages[0].role).toBe('user');
+      const text = (answer.messages[0].content as { text: string }).text;
+      expect(text.startsWith('Error: SERVICE_UNAVAILABLE — ')).toBe(true);
+      expect(text).not.toContain(PACKAGE_AGENT.instructions);
+      expect(session.log.warn).toHaveBeenCalledWith(
+        expect.stringContaining('agent prompt refused'),
+        expect.objectContaining({ agentName: 'pkg_helper' }),
+      );
+    } finally {
+      await session.close();
+    }
+  });
+  it('a host whose read has the listing but no by-name read reads the metadata service for both the roster and the get', async () => {
+    // One decision per host. The listing alone would let the roster advertise a
+    // package agent that the get, still on the metadata service, answers "not
+    // found": the #28940 defect again, on a host `bridgePrompts`' parameter type
+    // accepts.
+    const service = metadataService({ agents: [AGENT] });
+    const listingOnly = { getMetaItems: vi.fn(protocol().getMetaItems) };
+    const session = await connectWith(service, listingOnly);
+    try {
+      const listed = await session.client.listPrompts();
+      const description = agentNameDescription(listed.prompts) ?? '';
+      expect(description).toContain('"support_triage"');
+      expect(description).not.toContain('pkg_helper');
+      expect(listingOnly.getMetaItems).not.toHaveBeenCalledWith({ type: 'agent' });
+      const served = await session.client.getPrompt({ name: 'agent_prompt', arguments: { agentName: 'support_triage' } });
+      expect(served.messages).toEqual([
+        { role: 'assistant', content: { type: 'text', text: 'You triage support cases.' } },
+      ]);
+    } finally {
+      await session.close();
+    }
+  });
+
+  it('a by-name read that throws anything but SERVICE_UNAVAILABLE travels as a protocol error and serves no instructions', async () => {
+    const session = await connectWith(
+      metadataService({ agents: [] }),
+      protocol({ byName: async () => { throw Object.assign(new Error('registry exploded'), { code: 'INTERNAL' }); } }),
+    );
+    try {
+      const got = session.client.getPrompt({ name: 'agent_prompt', arguments: { agentName: 'pkg_helper' } });
+      await expect(got).rejects.toThrow(/registry exploded/);
+      await expect(got).rejects.not.toThrow(PACKAGE_AGENT.instructions);
+      expect(session.log.warn).not.toHaveBeenCalledWith(expect.stringContaining('agent prompt refused'), expect.anything());
+    } finally {
+      await session.close();
+    }
+  });
+
+  it('a degraded roster verdict with the protocol present and no agent named keeps the prompt listed, naming no agent', async () => {
+    const session = await connectWith(
+      metadataService({
+        agentList: async () => ({ items: [], degraded: true, errors: ['loader sys_metadata: connection refused'] }),
+      }),
+      protocol({ agents: [] }),
+    );
+    try {
+      const listed = await session.client.listPrompts();
+      expect(listed.prompts.map((p) => p.name)).toContain('agent_prompt');
+      expect(agentNameDescription(listed.prompts) ?? '').not.toContain('e.g.');
+      expect(session.log.warn).toHaveBeenCalledWith(
+        expect.stringContaining('agent_prompt'),
+        expect.objectContaining({ errors: ['loader sys_metadata: connection refused'] }),
+      );
+    } finally {
+      await session.close();
+    }
+  });
+});
@@ -526,6 +526,14 @@ async function diagnoseListRead(
 export interface McpMergedMetadataRead {
   /** The protocol's merged listing for one metadata type. */
   getMetaItems(request: { type: string }): Promise<unknown>;
+  /**
+   * [#31514] The protocol's by-name read, the one `GET /api/v1/meta/TYPE/NAME`
+   * serves. `agent_prompt` resolves an agent through it where the host has it
+   * ({@link buildAgentPromptResult}), so an agent a package ships, which lives
+   * in the registry this read consults and has no copy in the metadata
+   * service, is served by name the way the REST read serves it.
+   */
+  getMetaItem?(request: { type: string; name: string }): Promise<unknown>;
 }
 
 /**
@@ -698,6 +706,60 @@ export interface AgentPromptResult {
   messages: Array<{ role: 'user' | 'assistant'; content: { type: 'text'; text: string } }>;
 }
 
+/**
+ * [#31514] Read one agent by name through the protocol's by-name read, the read
+ * `GET /api/v1/meta/agent/NAME` serves, where this host has one; the metadata
+ * service otherwise, as before. Which of the two is {@link agentReadOf}'s
+ * decision, the one the roster takes too. ONE reader per host, never both:
+ * the defect this closes is that the two disagree (an agent a package ships
+ * lives in the registry the protocol reads, and the metadata service holds no
+ * copy of it), so a lookup that tried one and then the other would keep both
+ * answers alive.
+ *
+ * The protocol answers `{ type, name, item }`, with `item` absent on a miss,
+ * and throws `SERVICE_UNAVAILABLE` (503) when the metadata service behind it
+ * could not be read and the whole chain resolved nothing: that is the #6055
+ * outage, reported as {@link DiagnosedRead.degraded}. Any other throw travels
+ * to the caller, as a throw of the metadata service's read always did.
+ */
+async function readAgentByName(
+  metadataService: IMetadataService,
+  protocol: McpMergedMetadataRead | undefined,
+  name: string,
+): Promise<DiagnosedRead> {
+  const read = agentReadOf(protocol);
+  if (!read?.getMetaItem) {
+    return diagnosedGet(metadataService, 'agent', name);
+  }
+  let envelope: unknown;
+  try {
+    envelope = await read.getMetaItem({ type: 'agent', name });
+  } catch (err) {
+    if ((err as { code?: unknown } | null)?.code === METADATA_UNAVAILABLE_CODE) {
+      return { data: undefined, degraded: true, errors: [err instanceof Error ? err.message : String(err)] };
+    }
+    throw err;
+  }
+  return { data: (envelope as { item?: unknown } | null | undefined)?.item, degraded: false, errors: [] };
+}
+
+/**
+ * [#31514] The ONE decision, per host, of which layer `agent_prompt` reads:
+ * the protocol when the host's read carries both the merged listing and the
+ * by-name read, the metadata service (`undefined` here) otherwise. The roster
+ * ({@link readAgentRoster}) and the get ({@link readAgentByName}) both take
+ * this answer, so they cannot split: a read with the listing but no by-name
+ * read would otherwise advertise a package agent that the get, left on the
+ * metadata service, answers "not found", the #28940 defect again.
+ */
+function agentReadOf(mergedRead: McpMergedMetadataRead | undefined): McpMergedMetadataRead | undefined {
+  return mergedRead
+    && typeof mergedRead.getMetaItems === 'function'
+    && typeof mergedRead.getMetaItem === 'function'
+    ? mergedRead
+    : undefined;
+}
+
 /** An `Error: …` answer on the prompt surface — this file's existing shape. */
 function promptError(text: string): AgentPromptResult {
   return { messages: [{ role: 'user' as const, content: { type: 'text' as const, text } }] };
@@ -727,18 +789,24 @@ function promptError(text: string): AgentPromptResult {
  * `degraded` only decides the answer once the read has resolved NOTHING, i.e.
  * only when the answer would otherwise have been the unfounded "not found".
  * A read that answered a body is served as it always was.
+ *
+ * [#31514] The agent is read through `protocol`, the read
+ * `GET /api/v1/meta/agent/NAME` serves, where the host has both its reads
+ * ({@link agentReadOf}, {@link readAgentByName}); the three states above are
+ * unchanged.
  */
 export async function buildAgentPromptResult(
   metadataService: IMetadataService,
   args: { agentName?: unknown; objectName?: unknown; recordId?: unknown; viewName?: unknown },
   logger?: Logger,
+  protocol?: McpMergedMetadataRead,
 ): Promise<AgentPromptResult> {
   const agentName = String(args.agentName ?? '');
   if (!agentName) {
     return promptError('Error: agentName argument is required');
   }
 
-  const read = await diagnosedGet(metadataService, 'agent', agentName);
+  const read = await readAgentByName(metadataService, protocol, agentName);
 
   if (read.data === undefined || read.data === null) {
     if (read.degraded) {
@@ -799,17 +867,26 @@ type AgentRoster =
  * [#28940] Read which agents this boot holds, for the `agent_prompt`
  * advertisement.
  *
- * The roster is read from the metadata service — the same layer
- * {@link buildAgentPromptResult} resolves a name from — so the names the
- * argument teaches are names a `prompts/get` can answer. `agent` is a
- * code-only type (ADR-0063 §2 closes `*.agent.ts` to third parties, and the
- * save door refuses a runtime create), so no runtime write grows the set after
- * boot, and the merged overlay read the skill snapshot uses has nothing to add.
+ * The roster is read from the same layer {@link buildAgentPromptResult}
+ * resolves a name from, so the names the argument teaches are names a
+ * `prompts/get` can answer. [#31514] That layer is the protocol where the host
+ * has both its reads ({@link agentReadOf}, the decision the get takes too):
+ * its merged listing, `GET /api/v1/meta/agent`'s read
+ * ({@link mergedDiagnosedList}), which holds the agents a package ships. The
+ * metadata service holds no copy of those, so a roster read from it alone told
+ * a boot whose only agent a package ships that it held none, and the prompt
+ * was not advertised. The completeness verdict is still the metadata
+ * service's, as for the skill listing. `agent` is a code-only type (ADR-0063 §2
+ * closes `*.agent.ts` to third parties, and the save door refuses a runtime
+ * create), so no runtime write grows the set after boot.
  */
-async function readAgentRoster(metadataService: IMetadataService): Promise<AgentRoster> {
+async function readAgentRoster(
+  metadataService: IMetadataService,
+  mergedRead: McpMergedMetadataRead | undefined,
+): Promise<AgentRoster> {
   let read: DiagnosedListRead;
   try {
-    read = await diagnosedList(metadataService, 'agent');
+    read = await mergedDiagnosedList(metadataService, agentReadOf(mergedRead), 'agent');
   } catch (err) {
     return { state: 'unknown', errors: [err instanceof Error ? err.message : String(err)] };
   }
@@ -1708,11 +1785,15 @@ export class MCPServerRuntime {
     // once the transport attaches. A roster read that cannot say (degraded, or
     // it threw) keeps the prompt, which then answers the honest #6055 outage
     // text at get time.
-    const roster = await readAgentRoster(metadataService);
+    // [#31514] Through the protocol where the host has both its reads, the
+    // metadata service otherwise: one decision ({@link agentReadOf}) that the
+    // get below takes too.
+    const agentRead = agentReadOf(mergedRead);
+    const roster = await readAgentRoster(metadataService, agentRead);
     if (roster.state === 'none') {
       logger?.info(
         '[MCP] agent_prompt not advertised — this boot registers no agent, so nothing could answer it. '
-          + 'It is listed on a boot whose metadata service holds at least one agent.',
+          + 'It is listed on a boot that holds at least one agent, one a package ships included.',
       );
     } else {
       if (roster.state === 'unknown') {
@@ -1743,8 +1824,9 @@ export class MCPServerRuntime {
         },
         async (args) =>
           // [#6055] Outage vs. miss lives in the builder — see
-          // {@link buildAgentPromptResult}.
-          buildAgentPromptResult(metadataService, args, logger),
+          // {@link buildAgentPromptResult}. [#31514] The agent is read through
+          // the protocol's by-name read where `agentRead` is the protocol.
+          buildAgentPromptResult(metadataService, args, logger, agentRead),
       );
 
       logger?.info('[MCP] Agent prompts bridged');