feat(cli): substitute ${COMMONLY_AGENT_TOKEN} / ${COMMONLY_API_URL} in MCP config

[samxu01]

Summary

Lets users keep their checked-in env files free of secrets. The wrapper substitutes the agent's runtime token + instance URL into the generated MCP config at spawn time, from values already on hand (the saved token record).

Why this is needed. Surfaced during the 2026-04-17 cross-agent demo validation: every env spec referencing commonly-mcp had to be hand-rewritten with the agent's cm_agent_* token after attach, because the token is minted at attach time and only known to the wrapper. Without substitution, a shared/checked-in env file is unusable across agents.

Recognised placeholders (substituted everywhere a string appears in the MCP config — env values, command args, and url fields):

Placeholder	Substituted with
${COMMONLY_AGENT_TOKEN}	per-(agent, pod) cm_agent_* runtime token
${COMMONLY_API_URL}	instance URL the agent is attached to
${COMMONLY_INSTANCE_URL}	alias for ${COMMONLY_API_URL}

Properties:

• One-pass, literal substitution. No nested expansion, no shell quoting.
• Unknown ${COMMONLY_*} placeholders are left intact so typos surface as runtime MCP errors, not silent empty strings.
• Falsy ctx values are also no-ops (placeholder preserved) so users can diagnose missing context.

Plumbing: performRun now passes runtimeToken + instanceUrl into the adapter.spawn ctx; claude adapter passes them through to writeMcpConfig.

Example

// env.json — checked into source control, no secrets
{
  "mcp": [{
    "name": "commonly",
    "transport": "stdio",
    "command": ["commonly-mcp"],
    "env": {
      "COMMONLY_API_URL":     "${COMMONLY_API_URL}",
      "COMMONLY_AGENT_TOKEN": "${COMMONLY_AGENT_TOKEN}",
      "COMMONLY_DEFAULT_POD": "<your-pod-id>"
    }
  }]
}

After commonly agent attach claude --env env.json --pod <id>, the same file works for every attached agent without manual editing.

Test plan

• cd cli && npm test — 131/133 passing (6 new: 5 substitution + 1 ctx plumbing; 2 skipped Linux-only)
• Self-review against docs/REVIEW.md
• Live-validated end-to-end on commonly-dev with placeholder env (no hardcoded tokens)

Out of scope (deferred)

• Auto-handling agent.ask events in the run loop. Was bundled with this work originally (see closed feat(cli): close cross-agent loop — auto-handle agent.ask + ${COMMONLY_AGENT_TOKEN} substitution #237), but pulled out: collapsing cross-agent talk into a hidden RPC backchannel undercuts Commonly's "shared social substrate" pitch. Default for agent↔agent should be DM-pod messaging (existing chat infra) — separate design discussion + ADR addendum.

🤖 Generated with Claude Code