Skip to content

Add hosted-safe protocol passthrough with injectable I/O context#4

Merged
carldebilly merged 7 commits intomainfrom
dev/cdb/mcp-support
Feb 28, 2026
Merged

Add hosted-safe protocol passthrough with injectable I/O context#4
carldebilly merged 7 commits intomainfrom
dev/cdb/mcp-support

Conversation

@carldebilly
Copy link
Member

Why

AsProtocolPassthrough() keeps stdout clean for stdio protocols (MCP/LSP/DAP/CGI-style), but hosted sessions have a different stream ownership model.

This PR adds an explicit low-level I/O contract for handlers and makes passthrough behavior safe and predictable in hosted transports.

What changed

  • Added new injectable service: IReplIoContext
  • Added default implementation: LiveReplIoContext
  • Registered IReplIoContext in core/default DI paths (CLI and hosted overlay)
  • Extended protocol passthrough runtime behavior:
    • Local CLI: unchanged (stdout reserved for protocol stream, repl diagnostics to stderr)
    • Hosted session: fail fast unless handler explicitly requests IReplIoContext
  • Added explicit runtime error code for unsupported hosted passthrough:
    • protocol_passthrough_hosted_not_supported
  • Marked IReplIoContext as framework-injected for documentation export (not exposed as user option)
  • Updated docs:
    • new docs/commands.md
    • README passthrough guidance
    • shell completion notes preserved

Developer-facing behavior

A hosted passthrough handler must be stream-capable, e.g.:

app.Map("transfer send", (IReplIoContext io) =>
{
    io.Output.WriteLine("zmodem-start");
    return Results.Exit(0);
})
.AsProtocolPassthrough();

Console-bound libraries that open Console.* directly remain CLI-only.

Tests

Added/updated coverage for:

  • CommandBuilder passthrough API and shell completion bridge marking
  • passthrough banner suppression and stdout/stderr cleanliness
  • hosted fail-fast when passthrough handler is not stream-capable
  • hosted success when handler requests IReplIoContext
  • IReplIoContext injection in CLI mode

Validated with:

  • Repl.Tests
  • Repl.IntegrationTests
  • Repl.ProtocolTests

Compatibility

  • No breaking change to AsProtocolPassthrough() API surface
  • Behavioral change is scoped to hosted sessions:
    • previously ambiguous
    • now explicit fail-fast unless stream-capable handler is declared

Notes

This lays groundwork for niche remote stream workflows (for example ZMODEM-like transfers) without weakening safety for console-bound protocol SDKs.

@carldebilly carldebilly merged commit 4213088 into main Feb 28, 2026
10 checks passed
@carldebilly carldebilly deleted the dev/cdb/mcp-support branch February 28, 2026 22:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant