fix(engine,wrapper): proper path-based MCP config delivery (protocol 0.2.0)

[manojp99]

TL;DR

Three latent runtime-crashing bugs in _runtime.py made the entire --mcp-servers flow non-functional at engine 0.2.0. All three were silenced by adjacent # pyright: ignore suppressions in the same ~50-line MCP plumbing block. Pyright was right; the author was rationalizing.

Coordinated fix: the wrapper writes the MCP config file in the format amplifier-module-tool-mcp expects, passes the path via the renamed --mcp-config-path flag, and the engine sets AMPLIFIER_MCP_CONFIG for the module to discover via its existing 4-source priority chain. Each layer owns one responsibility. Wire protocol bumped 0.1.0 → 0.2.0; coordinated release of engine 0.3.0 + wrapper 0.4.0.

The three latent bugs (all in _runtime.py)

#	Symptom	Root cause
1	AttributeError: 'PreparedBundle' object has no attribute 'config'	prepared.config.get("tools", {}).get("tool-mcp", {}) — PreparedBundle is a dataclass with mount_plan, resolver, bundle, bundle_package_paths, mode_warnings, module_exports. No config attribute exists. The author wrote a prose comment claiming "stubs are incomplete" — the runtime confirmed the type checker, not the comment. Silenced as reportAttributeAccessIssue.
2	AttributeError: 'list' object has no attribute 'get'	After fixing #1 to use mount_plan["tools"]: that field is a list of {module, source, config} dicts, not a dict keyed by module name. The author treated it as a dict. No comment, just a wrong assumption.
3	TypeError: PreparedBundle.create_session() got an unexpected keyword argument 'tool_overrides'	The foundation API signature is create_session(session_id=None, parent_id=None, approval_system=None, display_system=None, session_cwd=None, is_resumed=False). No tool_overrides kwarg. Silenced as reportCallIssue.

The entire merge-and-deliver chain in _runtime.py was wired to a tool_overrides mechanism that doesn't exist on the foundation API. The wire --mcp-servers flag has been non-functional since the spec was added.

The proper fix

The module (amplifier-module-tool-mcp) already has four documented config sources: inline bundle config, project .amplifier/mcp.json, user ~/.amplifier/mcp.json, and AMPLIFIER_MCP_CONFIG env var → JSON path. The wire --mcp-servers was trying to be a fifth, parallel mechanism. Instead, we route it as a fourth-priority entry through the existing env-var path.

┌─────────────────────────────────────────────────────────────┐
│ Host                                                        │
│   SpawnAgentParams.mcpServers: Record<string, ServerConfig> │  ← unchanged
└──────────────────────────┬──────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│ Wrapper (amplifier-agent-ts 0.4.0)                          │
│   mcp-spill.ts:                                             │
│     - Always spill to 0600 tmpfile (drop inline branch)     │
│     - Write {"mcpServers": <map>} (matches module schema)   │
│     - Return plain path (no @-prefix)                       │
│   argv-builder.ts:                                          │
│     - --mcp-config-path <path>                              │
└──────────────────────────┬──────────────────────────────────┘
                           ↓ wire (protocol 0.2.0)
┌─────────────────────────────────────────────────────────────┐
│ Engine CLI (single_turn.py)                                 │
│   - --mcp-config-path <path>: validate exists, forward      │
│   - No JSON parsing, no file reading                        │
└──────────────────────────┬──────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│ Engine runtime (_runtime.py)                                │
│   if mcp_config_path:                                       │
│       os.environ["AMPLIFIER_MCP_CONFIG"] = mcp_config_path  │
│   session = await prepared.create_session(...)              │
└──────────────────────────┬──────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│ amplifier-module-tool-mcp (unchanged)                       │
│   _load_from_env() → file read → merge with 3 other sources │
└─────────────────────────────────────────────────────────────┘

No format knowledge in the engine. No mount_plan mutation (which would race across turns). No imaginary kwargs.

What's deleted

• _runtime.py: ~30 lines of merge logic, 4 # pyright: ignore suppressions, the non-existent tool_overrides kwarg, the bogus prepared.config reference, the list-as-dict access pattern.
• single_turn.py: the _parse_json_or_atpath(mcp_servers_raw, ...) call. Replaced with a Path(...).is_file() check.
• mcp-spill.ts: the inline-JSON-on-argv branch and anyServerHasEnv helper. Replaced with always-spill.
• protocol/methods.py: mcpServers: NotRequired[dict[str, McpServerConfig]]. Replaced with mcpConfigPath: NotRequired[str].

Wire compatibility

Protocol bumped 0.1.0 → 0.2.0. This is a clean break:

• Old wrapper + new engine → protocol_version_mismatch with remediation hint ("reinstall both: uv tool install --reinstall amplifier-agent and npm install amplifier-agent-ts@latest")
• New wrapper + old engine → same clean error
• Matched versions → works

No silent format mismatches. Anyone who was successfully using --mcp-servers was actually not — the code crashed for them too — so there's no working consumer base to migrate.

Host API preserved

SpawnAgentParams.mcpServers: Record<string, ServerConfig> stays exactly the same. Hosts (e.g. nanoclaw) don't see the wire-level rename. The wrapper internally translates dict → wrapped-format tmpfile → path.

Verification

Check	Result
Engine pytest (tests/test_runtime_mcp_threading.py)	5/5 pass
Wrapper bun tests (mcp-spill.test.ts + argv-builder.test.ts)	12/12 pass
Wrapper bun run typecheck	exit 0
Engine end-to-end (manual amplifier-agent run in container)	Bundle mounts, reaches OpenAI, returns parseable envelope. New --mcp-config-path flag validated against {"mcpServers": {}} file.

End-to-end test envelope (excerpted):

{
  "protocolVersion": "0.2.0",
  "sessionId": "pathD-rootverify-9457",
  "turnId": "turn-1",
  "reply": "",
  "error": {
    "code": "internal",
    "classification": "engine",
    "message": "RuntimeError: Execution failed: InvalidRequestError: ... 'reasoning.effort' is not supported with this model."
  }
}

The error returned by OpenAI ('reasoning.effort' not supported with this model) is a separate bug in amplifier-module-provider-openai — the provider is sending a reasoning.effort parameter to a model that doesn't accept it. Out of scope for this PR; it lives in a different repo and surfaces after the engine fix is in place. To be filed separately.

Coordinated release

• amplifier-agent (engine) 0.2.0 → 0.3.0 — consumers pin via git+https://github.com/microsoft/amplifier-agent@engine-v0.3.0 (PyPI publishing not wired yet — separate follow-up).
• amplifier-agent-ts (wrapper) 0.3.1 → 0.4.0 — published to npm with provenance via publish-wrapper.yml (OIDC trusted publishing, same flow as 0.3.1).

After merge: tag engine-v0.3.0 and wrapper-v0.4.0 on the merge commit. The wrapper publish workflow fires on wrapper-v* tag push.

Migration for downstream consumers

• Wrapper callers: no code changes. Bump dependency to amplifier-agent-ts@0.4.0.
• Container/Dockerfile consumers (e.g. nanoclaw): bump AMPLIFIER_AGENT_REF to engine-v0.3.0. Bump wrapper to 0.4.0. The pair must move together.