feat(repository-plugin): load trusted package code

packages/mcp/mcp-client/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/mcp/mcp-client/README.md
-README.md: d7966595c68ff1ec4a288caf5d9fe4b0bf580cc5
-README.zh.md: eb9e0dbdb48423cc4bc698fda355e973e42bc7a3
+README.md: 6bcc195e36d24d7e5ae3462573b30f1b41c963a7
+README.zh.md: 8886c16c3fe66d283ae2191661118729a89f1aeb

packages/mcp/mcp-client/README.md

@@ -56,7 +56,7 @@ Every MCP tool has two names: the raw MCP name (sent on the wire in `tools/call`
 
 ## Behavior
 
-- On connect: `listTools()` → registers each tool via `ctx.tools.register()` under its public name.
+- On connect: plugin activation awaits `listTools()` and registers each tool via `ctx.tools.register()` under its public name before the composition starts its first turn. Initial connection failure is logged and activates with no tools.
 - Listens for `notifications/tools/list_changed` → re-syncs; a failed re-sync keeps the previous generation registered.
 - Tool execute: `client.callTool({ name: rawName, arguments }, { signal })` with timeout + abort support—the public name is never sent to the server.
 - Canonical success is `{ content: JsonValue[], structuredContent? }`; complete JSON MCP blocks survive for programmatic callers. A supported advertised `outputSchema` validates `structuredContent`; unsupported schema vocabulary falls back to unconstrained `JsonValue`.
@@ -101,7 +101,6 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 ## Known Limitations and Deferred Work
 
-- **Initial discovery is asynchronous** — plugin load does not wait for connection and `listTools()`, so a turn started immediately after boot or HMR can assemble before the MCP tools are registered.
 - **Tools are the only bridged MCP capability** — Resources and Prompts have no harness consumption surface and are deferred.
 - **Crash recovery is manual** — transport closure does not auto-reconnect; registered tools can remain visible but fail against the closed transport until an HMR reload or Host restart.
 - **Native non-text rendering is lossy** — image, audio, and resource payloads become placeholders in model context even though the execution-local canonical value preserves their JSON blocks. Richer Native multimedia projection is deferred.

packages/mcp/mcp-client/README.zh.md

@@ -56,7 +56,7 @@ MCP 客户端桥接插件：连接外部 [Model Context Protocol](https://modelc
 
 ## 行为
 
-- 连接时：`listTools()` → 通过 `ctx.tools.register()` 使用各自公开名称注册每个工具。
+- 连接时：插件激活会等待 `listTools()`，并在组合开始首个轮次前通过 `ctx.tools.register()` 以公开名称注册每个工具。初始连接失败会记录日志，插件仍会激活但不注册工具。
 - 监听 `notifications/tools/list_changed` → 重新同步；同步失败时保留上一世代的注册。
 - 工具执行：`client.callTool({ name: rawName, arguments }, { signal })`，支持超时 + 中止；公开名称绝不会发给服务器。
 - 规范成功值是 `{ content: JsonValue[], structuredContent? }`；完整的 JSON MCP 块会保留给编程调用方。受支持且已声明的 `outputSchema` 会验证 `structuredContent`；不受支持的 schema 词汇会回退为不受约束的 `JsonValue`。
@@ -101,7 +101,6 @@ MCP 客户端桥接插件：连接外部 [Model Context Protocol](https://modelc
 
 ## 已知限制与暂缓事项
 
-- **初始发现是异步的**：插件加载不会等待连接和 `listTools()`，因此在启动或 HMR 后立即开始的轮次可能在 MCP 工具注册前完成组装。
 - **只桥接 MCP 的工具能力**：资源和提示词没有 harness 消费接口，暂缓实现。
 - **崩溃恢复需要手动触发**：传输关闭后不会自动重新连接；已注册工具可能仍然可见，但会因传输已关闭而调用失败，直到 HMR 重载或重启 Host。
 - **Native 非文本渲染有损**：图片、音频与资源载荷在模型上下文中会变成占位符，即使执行局部的规范值保留了其 JSON 块。更丰富的 Native 多媒体投影暂缓实现。

packages/mcp/mcp-client/src/index.ts

@@ -116,7 +116,13 @@ export const Config = z.union([
 
 // ---- Plugin apply ----
 
-export function apply(ctx: Context, config: Config): void {
+/**
+ * Connect one MCP server and publish its initial tool generation before activation.
+ * @param ctx - plugin context carrying the tool registry.
+ * @param config - resolved transport and server namespace configuration.
+ * @returns startup readiness after connection and initial tool discovery settle.
+ */
+export function apply(ctx: Context, config: Config): Promise<void> {
   // Reserve the namespace first: a duplicate `serverName` fails THIS instance
   // at load with an actionable error and leaves the earlier instance intact.
   ctx.effect(() => {
@@ -179,4 +185,6 @@ export function apply(ctx: Context, config: Config): void {
     for (const dispose of live().values()) dispose()
     try { await client.close() } catch { /* transport already gone */ }
   }, 'mcp-client.connection')
+
+  return ready.then(() => undefined)
 }

packages/mcp/mcp-client/tests/apply.spec.ts

@@ -141,8 +141,7 @@ describe('apply (plugin lifecycle)', () => {
   })
 
   it('connects, syncs tools under the namespace, and registers a notification handler', async () => {
-    apply(ctx, stdioConfig)
-    await sleep(50)
+    await apply(ctx, stdioConfig)
 
     expect(mockConnect).toHaveBeenCalled()
     expect(mockListTools).toHaveBeenCalled()
@@ -152,11 +151,10 @@ describe('apply (plugin lifecycle)', () => {
   })
 
   it('rejects a duplicate serverName at load and leaves the first instance intact', async () => {
-    apply(ctx, stdioConfig)
-    await sleep(50)
+    await apply(ctx, stdioConfig)
     expect(ctx.tools.get('mcp__srv__remote')).toBeDefined()
 
-    expect(() => { apply(ctx, stdioConfig) }).toThrow(/serverName "srv" is already in use/)
+    expect(() => { void apply(ctx, stdioConfig) }).toThrow(/serverName "srv" is already in use/)
     // First instance unaffected.
     expect(ctx.tools.get('mcp__srv__remote')).toBeDefined()
   })
@@ -165,8 +163,7 @@ describe('apply (plugin lifecycle)', () => {
     const first = new Context()
     await first.plugin(SystemPrompt)
     await first.plugin(ToolRegistry)
-    apply(first, stdioConfig)
-    await sleep(50)
+    await apply(first, stdioConfig)
 
     await first.fiber.dispose()
     await sleep(50)
@@ -176,16 +173,17 @@ describe('apply (plugin lifecycle)', () => {
     const second = new Context()
     await second.plugin(SystemPrompt)
     await second.plugin(ToolRegistry)
-    expect(() => { apply(second, stdioConfig) }).not.toThrow()
+    await expect(apply(second, stdioConfig)).resolves.toBeUndefined()
+    await second.fiber.dispose()
   })
 
   it('scopes serverName reservations per app root', async () => {
     const other = await mountRegistry()
 
-    apply(ctx, stdioConfig)
+    const first = apply(ctx, stdioConfig)
     // Same serverName on a DIFFERENT root is fine.
-    expect(() => { apply(other, stdioConfig) }).not.toThrow()
-    await sleep(50)
+    const second = apply(other, stdioConfig)
+    await Promise.all([first, second])
 
     expect(ctx.tools.get('mcp__srv__remote')).toBeDefined()
     expect(other.tools.get('mcp__srv__remote')).toBeDefined()
@@ -194,8 +192,7 @@ describe('apply (plugin lifecycle)', () => {
   it('logs error and registers no tools when connect fails; dispose is a no-op', async () => {
     mockConnect.mockRejectedValue(new Error('connection refused'))
 
-    apply(ctx, stdioConfig)
-    await sleep(50)
+    await apply(ctx, stdioConfig)
 
     expect(mockListTools).not.toHaveBeenCalled()
     expect(ctx.tools.get('mcp__srv__remote')).toBeUndefined()
@@ -208,8 +205,7 @@ describe('apply (plugin lifecycle)', () => {
   })
 
   it('re-syncs tools on ToolListChanged notification', async () => {
-    apply(ctx, stdioConfig)
-    await sleep(50)
+    await apply(ctx, stdioConfig)
 
     expect(ctx.tools.get('mcp__srv__remote')).toBeDefined()
 
@@ -226,8 +222,7 @@ describe('apply (plugin lifecycle)', () => {
   })
 
   it('keeps the previous generation when a re-sync fails', async () => {
-    apply(ctx, stdioConfig)
-    await sleep(50)
+    await apply(ctx, stdioConfig)
     expect(ctx.tools.get('mcp__srv__remote')).toBeDefined()
 
     mockListTools.mockRejectedValue(new Error('flaky server'))
@@ -242,7 +237,7 @@ describe('apply (plugin lifecycle)', () => {
     // Load through ctx.plugin so ONLY the plugin's fiber is disposed — the
     // registry must survive to observe the unregistration.
     const fiber = ctx.plugin({ name: 'mcp-client', inject: ['tools'], apply }, stdioConfig)
-    await sleep(50)
+    await fiber
 
     // Advance to a second generation first.
     mockListTools.mockResolvedValue({
@@ -264,8 +259,7 @@ describe('apply (plugin lifecycle)', () => {
   it('effect disposer handles client.close failure gracefully', async () => {
     mockClose.mockRejectedValue(new Error('already closed'))
 
-    apply(ctx, stdioConfig)
-    await sleep(50)
+    await apply(ctx, stdioConfig)
 
     // Should not throw when dispose is triggered.
     await ctx.fiber.dispose()
@@ -283,8 +277,7 @@ describe('apply (plugin lifecycle)', () => {
       toolCallTimeoutMs: 30_000,
     }
 
-    apply(ctx, httpConfig)
-    await sleep(50)
+    await apply(ctx, httpConfig)
 
     expect(mockConnect).toHaveBeenCalled()
     expect(ctx.tools.get('mcp__web__remote')).toBeDefined()

packages/mcp/mcp-client/tests/mcp-client.e2e.ts

@@ -43,21 +43,6 @@ async function mountRegistry(): Promise<Context> {
   return ctx
 }
 
-/** Apply the MCP client plugin and wait for tools to be registered. */
-async function applyAndWait(ctx: Context, config: Config, timeoutMs = 20_000): Promise<void> {
-  // Annotated bindings (not withResolvers<void>()): the tests lint layer runs
-  // no-invalid-void-type with default options, which rejects the explicit
-  // type argument in call position but accepts the inferred form.
-  const gate: PromiseWithResolvers<void> = Promise.withResolvers()
-  const timer = setTimeout(
-    () => { gate.reject(new Error(`applyAndWait timed out after ${timeoutMs}ms — no tools/change event`)) },
-    timeoutMs,
-  )
-  ctx.on('tools/change', () => { clearTimeout(timer); gate.resolve() })
-  apply(ctx, config)
-  await gate.promise
-}
-
 function sleep(ms: number): Promise<void> {
   const gate: PromiseWithResolvers<void> = Promise.withResolvers()
   setTimeout(gate.resolve, ms)
@@ -94,7 +79,7 @@ describe('fixture server — controlled scenarios', () => {
 
   beforeAll(async () => {
     ctx = await mountRegistry()
-    await applyAndWait(ctx, fixtureConfig)
+    await apply(ctx, fixtureConfig)
   }, 30_000)
 
   afterAll(async () => {
@@ -180,9 +165,9 @@ describe('fixture server — duplicate serverName', () => {
       cwd: packageDir,
       toolCallTimeoutMs: 15_000,
     }
-    await applyAndWait(ctx, config)
+    await apply(ctx, config)
 
-    expect(() => { apply(ctx, config) }).toThrow(/serverName "dup" is already in use/)
+    expect(() => { void apply(ctx, config) }).toThrow(/serverName "dup" is already in use/)
 
     await ctx.fiber.dispose()
     await sleep(200)
@@ -192,7 +177,7 @@ describe('fixture server — duplicate serverName', () => {
 describe('fixture server — disposal', () => {
   it('disposes cleanly without error', async () => {
     const ctx = await mountRegistry()
-    await applyAndWait(ctx, {
+    await apply(ctx, {
       transport: 'stdio',
       serverName: 'fixture',
       command: process.execPath,
@@ -229,7 +214,7 @@ describe('server-everything — official test server', () => {
 
   beforeAll(async () => {
     ctx = await mountRegistry()
-    await applyAndWait(ctx, config)
+    await apply(ctx, config)
   }, 60_000)
 
   afterAll(async () => {
@@ -293,7 +278,7 @@ describe('server-filesystem — real filesystem operations', () => {
       cwd: '',
       toolCallTimeoutMs: 30_000,
     }
-    await applyAndWait(ctx, config)
+    await apply(ctx, config)
   }, 60_000)
 
   afterAll(async () => {
@@ -409,7 +394,7 @@ describe('streamable-http — in-process MCP server', () => {
       headers: { Authorization: 'Bearer e2e-test-token' },
       toolCallTimeoutMs: 15_000,
     }
-    await applyAndWait(ctx, config)
+    await apply(ctx, config)
   }, 30_000)
 
   afterAll(async () => {