feat(agent-harness): bound MCP gateway transport in the Worker

[iscekic]

No new behavior — this change adds connection safeguards that the product does not use yet.

---

Summary

createMcpTransportFactory retains Model Context Protocol (MCP) software development kit (SDK) parsing and sessions, but pins McpConnection destinations and credentials.
httpResponseBytes limits aggregate bytes before parsing; the caller supplies an operation signal and throwing onFailure, which receives sanitized McpTransportFailure reasons.
Any terminal failure closes every connection and blocks later requests and messages without retries, so interrupted mutations can retain uncertain results.

Files

• services/agent-harness/src/tools/mcp-transport.ts — Source; added, 150 lines (+150/-0). Defines McpConnection with serverId, configurationVersion, url, and authorization; requires one factory per operation and caller-controlled deadlines. Rejects malformed addresses, non-https: schemes, embedded credentials, queries, fragments, redirects, changed destinations, and status 400. Reports unsafe_destination, reauthorization_required for 401/403, unavailable_server for other failures, and limit_exceeded for byte overflow. Allows status 405 for the optional GET stream. Combines caller and SDK cancellation, counts streamed bytes across connections, cancels bodies, preserves the first failure, and disables reconnection. Retains SDK session and protocol handling without exposing provider diagnostics.

mcpTestFixture supplies an offline provider with randomized tool schemas, recorded requests and effects, configurable responses, and failures after effects occur.
Worker tests use the real SDK to verify initialization, discovery, execution, cancellation, immutable credentials, and failure containment across multiple connections.
The regressions cover lost mutation replies without repeating effects, but do not establish live provider connectivity.

Files

• services/agent-harness/src/tools/mcp-transport.test.ts — Test; added, 224 lines (+224/-0). Checks initialization, discovery, calls, and server-sent events through the SDK. Covers unsafe addresses, redirects, immutable authorization, sanitized direct errors, and connection-closed client results. Exercises multi-connection shutdown, blocked reuse, multibyte overflow despite misleading response lengths, and deadlines before and during requests, bodies, and initialization.
• services/agent-harness/src/tools/mcp-test-fixture.ts — Test fixture; added, 79 lines (+79/-0). Provides randomized integer schemas, read-only tool metadata, configurable structured results, and request/effect logs. Simulates initialization, discovery, calls, notification acknowledgments, unsupported listening, status failures, lost replies, stalled calls, overflow, and custom responses.

Tests: 2 files added: mcp-transport.test.ts (+224/-0 lines) and mcp-test-fixture.ts (+79/-0 lines), totaling 303 added lines.
Generated: 0 files changed.

---

Visual Changes

Visual Changes: N/A

Verification

Manual verification: Not performed; this level does not activate the harness.
The fixture and software development kit (SDK) regressions do not prove live provider connectivity.

Reviewer Notes

Human steps: None before merge or after merge.

• Recorded automated checks: Five scoped commands passed, including 30 Worker tests. They covered formatting, scoped lint, transport tests, format validation, and whitespace checks.
• Continuous integration (CI) owns repository-wide type and build checks.
• Validated discovery and execution remain in a19-runtime; this level adds only the transport, fixture, and tests.
• Repository: Kilo-Org/cloud. Worktree: /Users/igor/Projects/.worktrees/shared-agent-harness-3bb0.
• Review range: shared-agent-harness-3bb0-s24...shared-agent-harness-3bb0-s25.

Runtime verification remains pending at the stack tip. This level adds bounded MCP transport without activating the harness.

Stacked PRs — merge bottom to top. Each level shows only its own diff.

Runtime verification (E2E, user advocacy, simplify) runs on the tip PR over every level.
Every level keeps its own checks, its own bot review, and its own threads; each one is answered on its own PR.
Each level is its own deliverable: it builds and passes its own checks alone.
A finding on a level is repaired on that level, then carried upward with stack.sh forward.

1. shared-agent-harness-3bb0 — chore(agent-harness): register workspaces and enforce CI boundaries #5632
2. shared-agent-harness-3bb0-s2 — feat(agent-harness): define portable domain and snapshots #5637
3. shared-agent-harness-3bb0-s3 — feat(agent-harness): define commands tools and permission policy #5639
4. shared-agent-harness-3bb0-s4 — feat(agent-harness): share client state and cursor recovery #5643
5. shared-agent-harness-3bb0-s5 — feat(agent-harness): persist command intents and execution receipts #5647
6. shared-agent-harness-3bb0-s6 — feat(db): add harness ingress grants and retirement fences #5655
7. shared-agent-harness-3bb0-s7 — feat(agent-harness): deliver legacy history and project durable text #5659
8. shared-agent-harness-3bb0-s8 — feat(agent-harness): authorize durable grants and registered clients #5662
9. shared-agent-harness-3bb0-s9 — feat(agent-harness): fence retirement and retry payload cleanup #5667
10. shared-agent-harness-3bb0-s10 — feat(agent-harness): persist authoritative state in SQLite #5675
11. shared-agent-harness-3bb0-s11 — feat(agent-harness): admit durable runs and revisioned commands #5678
12. shared-agent-harness-3bb0-s12 — feat(agent-harness): recover queued runs and stream checkpointed steps #5688
13. shared-agent-harness-3bb0-s13 — feat(agent-harness): resolve interactions and dispatch tools sequentially #5693
14. shared-agent-harness-3bb0-s14 — feat(agent-harness): fence designated client tool execution #5697
15. shared-agent-harness-3bb0-s15 — feat(agent-harness): synchronize durable snapshots and legacy history #5701
16. shared-agent-harness-3bb0-s16 — feat(agent-harness): reuse authorized invitations with durable replay #5704
17. shared-agent-harness-3bb0-s17 — feat(integrations): bound repository transport for harness reads #5710
18. shared-agent-harness-3bb0-s18 — feat(integrations): expose bounded authorized repository reads #5714
19. shared-agent-harness-3bb0-s19 — feat(agent-harness): expose named authorized resource reads #5718
20. shared-agent-harness-3bb0-s20 — feat(sessions): bound history transport for harness reads #5724
21. shared-agent-harness-3bb0-s21 — feat(agent-harness): read scoped Cloud Agent context and progress #5726
22. shared-agent-harness-3bb0-s22 — fix(agent-harness): preserve ordered Cloud Agent dispatch identity #5731
23. shared-agent-harness-3bb0-s23 — feat(agent-harness): hand coding work to authorized Cloud Agent sessions #5733
24. shared-agent-harness-3bb0-s24 — feat(agent-harness): authorize scoped MCP gateway connections #5737
25. shared-agent-harness-3bb0-s25 — feat(agent-harness): bound MCP gateway transport in the Worker #5740 ← this PR
26. shared-agent-harness-3bb0-s26 — feat(agent-harness): execute validated remote MCP tools #5743
27. shared-agent-harness-3bb0-s27 — refactor(exa): share provider dispatch and usage recording #5746
28. shared-agent-harness-3bb0-s28 — feat(agent-harness): authorize bounded web provider requests #5747
29. shared-agent-harness-3bb0-s29 — feat(agent-harness): normalize web sources and preserve citations #5749
30. shared-agent-harness-3bb0-s30 — feat(agent-harness): define closed internal operation contracts #5753
31. shared-agent-harness-3bb0-s31 — feat(agent-harness): authorize internal maintenance operations #5754
32. shared-agent-harness-3bb0-s32 — feat(agent-harness): authorize named Kilo operation dispatch #5755
33. shared-agent-harness-3bb0-s33 — feat(agent-harness): authorize internal provider operations #5757
34. shared-agent-harness-3bb0-s34 — feat(agent-harness): secure the internal operations endpoint #5758
35. shared-agent-harness-3bb0-s35 — feat(agent-harness): bound and sanitize model streams #5767
36. shared-agent-harness-3bb0-s36 — feat(agent-harness): secure billed model inference #5776
37. shared-agent-harness-3bb0-s37 — test(agent-harness): cover model gateway security boundaries #5777 (tip)

[kilo-code-bot]

Code Review Summary

Status: 2 Issues Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	2
SUGGESTION	0

Issue Details (click to expand)

WARNING

File	Line	Issue
services/agent-harness/src/tools/mcp-transport.ts	39	Already-aborted signals never seal the factory
services/agent-harness/src/tools/mcp-transport.ts	93	controller.error can throw and skip reader.cancel()

Files Reviewed (3 files)

• services/agent-harness/src/tools/mcp-transport.ts - 2 issues
• services/agent-harness/src/tools/mcp-transport.test.ts - 0 issues
• services/agent-harness/src/tools/mcp-test-fixture.ts - 0 issues

Fix these issues in Kilo Cloud

---

_{Reviewed by grok-4.6 · Input: 186K · Output: 35.7K · Cached: 1.1M}

_{Review guidance: REVIEW.md from base branch shared-agent-harness-3bb0-s24}

[iscekic]

Closing: the owner stopped this workflow section. The branch is retained.