Fix REPL agent-stdio YAML pipe being echoed instead of executed

Replace the echo stub in AgentStdioHandler with a real dispatch pipeline:
multi-line YAML framing, YamlDotNet-based envelope parsing, command
dispatcher routing client.<name>.<method> through IGenericClientPassthrough,
and error wrapping that keeps the loop alive. Adds 11 acceptance tests
covering serializer round-trip, dispatcher routing, and stream framing.

FR-MCP-REPL-001, TR-MCP-REPL-001/003/004, TEST-MCP-REPL-001

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: sharpninja

src/McpServer.Repl.Core/AgentStdioProtocol.cs

@@ -0,0 +1,181 @@
+// FR-MCP-REPL-001: YAML Protocol STDIO REPL Host - Stream-level envelope loop
+// FR-MCP-REPL-002: REPL Lifecycle Management - Read/accumulate/dispatch loop
+// TR-MCP-REPL-003: Command Loop Lifecycle - Multi-line YAML framing
+// TEST-MCP-REPL-001: REPL host processes well-formed multi-line YAML envelopes end-to-end
+
+using System.Text;
+
+namespace McpServer.Repl.Core;
+
+/// <summary>
+/// Runs the REPL agent-stdio read/write loop: reads envelope lines from a <see cref="TextReader"/>,
+/// accumulates them into complete YAML documents (terminated by a blank line or the
+/// <c>---</c> document separator), dispatches each via <see cref="IReplCommandDispatcher"/>,
+/// and writes the response envelope back to the <see cref="TextWriter"/>.
+/// </summary>
+public interface IAgentStdioProtocol
+{
+    /// <summary>
+    /// Runs the agent-stdio loop until the reader reports end-of-stream or cancellation.
+    /// </summary>
+    /// <param name="reader">Inbound envelope stream.</param>
+    /// <param name="writer">Outbound response stream. The implementation flushes after each envelope.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    Task RunAsync(TextReader reader, TextWriter writer, CancellationToken cancellationToken);
+}
+
+/// <summary>
+/// Default <see cref="IAgentStdioProtocol"/> implementation. Accumulates inbound lines into
+/// YAML documents using the blank-line and <c>---</c> conventions, delegates parsing to
+/// <see cref="IYamlSerializer"/>, and routes each envelope through
+/// <see cref="IReplCommandDispatcher"/>. Malformed documents are reported as
+/// <c>invalid_envelope</c> errors and the loop continues.
+/// </summary>
+public sealed class AgentStdioProtocol : IAgentStdioProtocol
+{
+    private readonly IYamlSerializer _serializer;
+    private readonly IReplCommandDispatcher _dispatcher;
+
+    /// <summary>
+    /// Initializes a new <see cref="AgentStdioProtocol"/>.
+    /// </summary>
+    /// <param name="serializer">YAML serializer used to parse and emit envelopes.</param>
+    /// <param name="dispatcher">Command dispatcher invoked once per complete inbound envelope.</param>
+    public AgentStdioProtocol(IYamlSerializer serializer, IReplCommandDispatcher dispatcher)
+    {
+        _serializer = serializer ?? throw new ArgumentNullException(nameof(serializer));
+        _dispatcher = dispatcher ?? throw new ArgumentNullException(nameof(dispatcher));
+    }
+
+    /// <inheritdoc />
+    public async Task RunAsync(TextReader reader, TextWriter writer, CancellationToken cancellationToken)
+    {
+        ArgumentNullException.ThrowIfNull(reader);
+        ArgumentNullException.ThrowIfNull(writer);
+
+        var buffer = new StringBuilder();
+
+        while (!cancellationToken.IsCancellationRequested)
+        {
+            var line = await reader.ReadLineAsync(cancellationToken).ConfigureAwait(false);
+            if (line is null)
+            {
+                // End of stream — flush any accumulated envelope before exiting.
+                await FlushAsync(buffer, writer, cancellationToken).ConfigureAwait(false);
+                return;
+            }
+
+            if (IsDocumentBoundary(line))
+            {
+                await FlushAsync(buffer, writer, cancellationToken).ConfigureAwait(false);
+                continue;
+            }
+
+            buffer.AppendLine(line);
+        }
+
+        // Cancellation requested — attempt a final flush so callers don't lose the last envelope.
+        await FlushAsync(buffer, writer, cancellationToken).ConfigureAwait(false);
+    }
+
+    private static bool IsDocumentBoundary(string line)
+    {
+        if (string.IsNullOrWhiteSpace(line))
+        {
+            return true;
+        }
+
+        var trimmed = line.TrimEnd();
+        return trimmed == "---";
+    }
+
+    private async Task FlushAsync(StringBuilder buffer, TextWriter writer, CancellationToken cancellationToken)
+    {
+        if (buffer.Length == 0)
+        {
+            return;
+        }
+
+        var document = buffer.ToString();
+        buffer.Clear();
+
+        if (string.IsNullOrWhiteSpace(document))
+        {
+            return;
+        }
+
+        IYamlEnvelope envelope;
+        try
+        {
+            envelope = _serializer.Deserialize(document);
+        }
+        catch (Exception ex) when (ex is FormatException or InvalidOperationException)
+        {
+            var errorEnvelope = new YamlEnvelope
+            {
+                Type = "error",
+                Payload = new ErrorPayload
+                {
+                    RequestId = TryExtractRequestId(document),
+                    Code = "invalid_envelope",
+                    Message = ex.Message,
+                },
+            };
+            await WriteEnvelopeAsync(errorEnvelope, writer, cancellationToken).ConfigureAwait(false);
+            return;
+        }
+
+        IYamlEnvelope response;
+        try
+        {
+            response = await _dispatcher.DispatchAsync(envelope, cancellationToken).ConfigureAwait(false);
+        }
+        catch (OperationCanceledException)
+        {
+            throw;
+        }
+        catch (Exception ex)
+        {
+            response = new YamlEnvelope
+            {
+                Type = "error",
+                Payload = new ErrorPayload
+                {
+                    RequestId = (envelope.Payload as IRequestPayload)?.RequestId ?? "unknown",
+                    Code = "dispatch_error",
+                    Message = ex.Message,
+                },
+            };
+        }
+
+        await WriteEnvelopeAsync(response, writer, cancellationToken).ConfigureAwait(false);
+    }
+
+    private async Task WriteEnvelopeAsync(IYamlEnvelope envelope, TextWriter writer, CancellationToken cancellationToken)
+    {
+        var yaml = _serializer.Serialize(envelope);
+        // Envelopes are framed by a blank line, matching the inbound convention.
+        await writer.WriteAsync(yaml.AsMemory(), cancellationToken).ConfigureAwait(false);
+        if (!yaml.EndsWith('\n'))
+        {
+            await writer.WriteLineAsync().ConfigureAwait(false);
+        }
+        await writer.WriteLineAsync().ConfigureAwait(false);
+        await writer.FlushAsync(cancellationToken).ConfigureAwait(false);
+    }
+
+    private static string TryExtractRequestId(string document)
+    {
+        // Best-effort recovery of a requestId from a malformed document so callers can correlate.
+        foreach (var rawLine in document.Split('\n'))
+        {
+            var line = rawLine.Trim();
+            if (line.StartsWith("requestId:", StringComparison.OrdinalIgnoreCase))
+            {
+                return line["requestId:".Length..].Trim().Trim('"');
+            }
+        }
+
+        return "unknown";
+    }
+}

src/McpServer.Repl.Core/ReplCommandDispatcher.cs

@@ -0,0 +1,180 @@
+// FR-MCP-REPL-001: YAML Protocol STDIO REPL Host - Server-side command dispatcher
+// FR-MCP-REPL-003: Command Namespace Parity - Request routing to client passthrough
+// TR-MCP-REPL-004: Command Registry and Dispatcher - Envelope-to-handler routing
+// TEST-MCP-REPL-001: REPL host processes well-formed YAML command envelopes
+
+namespace McpServer.Repl.Core;
+
+/// <summary>
+/// Dispatches parsed YAML envelopes to the appropriate handler and returns the response
+/// envelope. Responsible for routing <c>hello</c> handshakes and <c>request</c> envelopes
+/// by method namespace (currently <c>client.*.*</c> via <see cref="IGenericClientPassthrough"/>).
+/// Unknown namespaces produce a <c>method_not_found</c> error envelope so the agent loop
+/// can respond and continue instead of crashing.
+/// </summary>
+public interface IReplCommandDispatcher
+{
+    /// <summary>
+    /// Dispatches a parsed YAML envelope and returns the response envelope (result or error).
+    /// Never throws for recoverable dispatch failures — unexpected exceptions are caught and
+    /// wrapped in an error envelope so the caller's read/write loop can remain alive.
+    /// </summary>
+    /// <param name="envelope">The inbound envelope to dispatch. Must have a non-null payload.</param>
+    /// <param name="cancellationToken">Cancellation token propagated to handlers.</param>
+    /// <returns>The response envelope to emit back to the caller.</returns>
+    Task<IYamlEnvelope> DispatchAsync(IYamlEnvelope envelope, CancellationToken cancellationToken);
+}
+
+/// <summary>
+/// Default <see cref="IReplCommandDispatcher"/> implementation. Routes <c>hello</c> envelopes
+/// to a handshake response and <c>request</c> envelopes with the <c>client.&lt;clientName&gt;.&lt;methodName&gt;</c>
+/// method shape to <see cref="IGenericClientPassthrough.InvokeAsync"/>. All other method
+/// namespaces produce a <c>method_not_found</c> error envelope.
+/// </summary>
+public sealed class ReplCommandDispatcher : IReplCommandDispatcher
+{
+    private const string ServerProtocolVersion = "1.0";
+    private readonly IGenericClientPassthrough _passthrough;
+
+    /// <summary>
+    /// Initializes a new <see cref="ReplCommandDispatcher"/>.
+    /// </summary>
+    /// <param name="passthrough">The generic client passthrough used to invoke <c>client.*.*</c> methods.</param>
+    public ReplCommandDispatcher(IGenericClientPassthrough passthrough)
+    {
+        _passthrough = passthrough ?? throw new ArgumentNullException(nameof(passthrough));
+    }
+
+    /// <inheritdoc />
+    public async Task<IYamlEnvelope> DispatchAsync(IYamlEnvelope envelope, CancellationToken cancellationToken)
+    {
+        ArgumentNullException.ThrowIfNull(envelope);
+
+        switch (envelope.Type)
+        {
+            case "hello":
+                return BuildHelloResponse(envelope.Payload as IHelloPayload);
+
+            case "request":
+                if (envelope.Payload is not IRequestPayload request)
+                {
+                    return BuildError(
+                        requestId: "unknown",
+                        code: "invalid_envelope",
+                        message: "Request envelope is missing a request payload.");
+                }
+                return await DispatchRequestAsync(request, cancellationToken).ConfigureAwait(false);
+
+            default:
+                return BuildError(
+                    requestId: "unknown",
+                    code: "invalid_envelope",
+                    message: $"Unsupported envelope type: {envelope.Type}");
+        }
+    }
+
+    private async Task<IYamlEnvelope> DispatchRequestAsync(IRequestPayload request, CancellationToken cancellationToken)
+    {
+        var method = request.Method ?? "";
+
+        if (method.StartsWith("client.", StringComparison.Ordinal))
+        {
+            return await DispatchClientRequestAsync(request, cancellationToken).ConfigureAwait(false);
+        }
+
+        return BuildError(
+            requestId: request.RequestId,
+            code: "method_not_found",
+            message: $"Method '{method}' is not routed by this dispatcher. " +
+                     "Supported namespaces: client.<clientName>.<methodName>.");
+    }
+
+    private async Task<IYamlEnvelope> DispatchClientRequestAsync(IRequestPayload request, CancellationToken cancellationToken)
+    {
+        // method shape: client.<clientName>.<methodName>
+        var parts = request.Method.Split('.', 3);
+        if (parts.Length != 3 || parts[0] != "client" ||
+            string.IsNullOrEmpty(parts[1]) || string.IsNullOrEmpty(parts[2]))
+        {
+            return BuildError(
+                requestId: request.RequestId,
+                code: "method_not_found",
+                message: $"Method '{request.Method}' does not match the expected 'client.<clientName>.<methodName>' shape.");
+        }
+
+        var clientName = parts[1];
+        var methodName = parts[2];
+        var args = request.Params is null
+            ? new Dictionary<string, object?>()
+            : new Dictionary<string, object?>(request.Params, StringComparer.OrdinalIgnoreCase);
+
+        try
+        {
+            var result = await _passthrough.InvokeAsync(clientName, methodName, args, cancellationToken).ConfigureAwait(false);
+            return new YamlEnvelope
+            {
+                Type = "result",
+                Payload = new ResultPayload
+                {
+                    RequestId = request.RequestId,
+                    Result = result,
+                },
+            };
+        }
+        catch (OperationCanceledException)
+        {
+            throw;
+        }
+        catch (Exception ex)
+        {
+            return BuildError(
+                requestId: request.RequestId,
+                code: "method_invocation_error",
+                message: ex.Message,
+                details: new Dictionary<string, object?>
+                {
+                    ["clientName"] = clientName,
+                    ["methodName"] = methodName,
+                    ["exceptionType"] = ex.GetType().FullName,
+                });
+        }
+    }
+
+    private static IYamlEnvelope BuildHelloResponse(IHelloPayload? request)
+    {
+        var capabilities = new List<string> { "client-passthrough" };
+        if (request?.Capabilities is not null)
+        {
+            capabilities.AddRange(request.Capabilities);
+        }
+
+        return new YamlEnvelope
+        {
+            Type = "hello",
+            Payload = new HelloPayload
+            {
+                ProtocolVersion = ServerProtocolVersion,
+                Capabilities = capabilities,
+            },
+        };
+    }
+
+    private static IYamlEnvelope BuildError(
+        string requestId,
+        string code,
+        string message,
+        IReadOnlyDictionary<string, object?>? details = null)
+    {
+        return new YamlEnvelope
+        {
+            Type = "error",
+            Payload = new ErrorPayload
+            {
+                RequestId = requestId,
+                Code = code,
+                Message = message,
+                Details = details,
+            },
+        };
+    }
+}