feat(agent-core-v2): caller MCP servers on session create and skill-dir file access

[sailist]

Related Issue

None — the problem is explained in the next section.

Problem

Two v1-parity gaps in the v2 engine (experimental):

1. MCP servers supplied by the caller when creating a session were silently dropped: the initial MCP load only read file config and plugin servers, so sessions created through the SDK/server with explicit mcpServers never connected to them.
2. File tools (Read/Write/Edit/Grep/Glob and media tools) could not reach skill directories outside the working directory. v1 merged skill roots into the workspace once at construction; v2 never merged them, so skills living outside the cwd were invisible to file tools, and --skillsDir / the server's skillDirs option had no effect.

What changed

1. Caller-supplied MCP servers on session create

• Add mcpServers to CreateSessionOptions, forwarded to the session's first ensureMcpReady call so caller-supplied servers ride on the initial load.
• ensureMcpReady accepts callerServers, honored only by the call that starts the initial load; later calls just await the in-flight single-flight load.
• Merge precedence mirrors v1: file config < caller-supplied < plugin servers.

2. File tools reach skill roots; skillDirs seed

• Add extendWorkspaceWithSkillRoots to path-access; Read/Write/Edit/Grep/Glob and media tools merge skill-catalog roots into the workspace per call (v1 merged once at construction), so skill dirs outside the cwd stay reachable and late-loading roots are picked up.
• Add skillCatalogRuntimeOptionsSeed; wire --skillsDir into the v2 print CLI and skillDirs into kap-server startServer (v1 SDK skillDirs parity).

3. Comment cleanup in agent-core-v2

• Enforce the package's documented convention that comments live only in the top-of-file block: strip mid-file doc/prose/trailing comments across the package while preserving header blocks and lint-suppression comments. No code tokens changed (verified by parser token-stream comparison, plus typecheck, tests, and lint against the pre-change baseline).

Changesets for the two fixes are included; the comment-only commit needs none.

Checklist

• I have read the CONTRIBUTING document.
• I have linked a related issue, or explained the problem above.
• I have added tests that prove my feature works.
• Ran gen-changesets skill, or this PR needs no changeset.
• Ran gen-docs skill, or this PR needs no doc update.

[changeset-bot]

🦋 Changeset detected

Latest commit: 6f03722

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@moonshot-ai/agent-core-v2	Patch
@moonshot-ai/kap-server	Patch
@moonshot-ai/kimi-code	Patch
@moonshot-ai/klient	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[sailist]

Superseded: the same work landed via #1637 (caller-supplied MCP servers), #1636 (skill dirs parity), and #1656 (comment cleanup). Verified no unique changes remain.