sailfork / t3code-github / packages/ effect-acp/ src/ protocol.ts

import type * as AcpCompat from "./compat.ts";
import * as Cause from "effect/Cause";
import * as Clock from "effect/Clock";
import * as Effect from "effect/Effect";
import * as Deferred from "effect/Deferred";
import * as Exit from "effect/Exit";
import * as Option from "effect/Option";
import * as Queue from "effect/Queue";
import * as Ref from "effect/Ref";
import type * as PlatformError from "effect/PlatformError";
import * as Schema from "effect/Schema";
import * as Scope from "effect/Scope";
import * as Stream from "effect/Stream";
import * as Stdio from "effect/Stdio";
import * as RpcClient from "effect/rpc/RpcClient";
import * as RpcClientError from "effect/rpc/RpcClientError";
import * as RpcMessage from "effect/rpc/RpcMessage";
import * as RpcSerialization from "effect/rpc/RpcSerialization";
import * as RpcServer from "effect/rpc/RpcServer";

import * as AcpSchema from "./schema.ts";
import * as AcpSchemaV1 from "./_generated/schema-v1.gen.ts";
import { CLIENT_METHODS } from "./_generated/meta.gen.ts";
import * as AcpError from "./errors.ts";
import { isolateNotificationHandler } from "./_internal/shared.ts";
const isAcpError = Schema.is(AcpError.AcpError);

export interface AcpProtocolLogEvent {
  readonly direction: "incoming" | "outgoing";
  readonly stage: "raw" | "decoded" | "decode_failed";
  readonly payload: unknown;
}

export interface AcpRequestContext {
  readonly requestId: string;
  readonly method: string;
}

export function acpRequestIdentity(requestId: AcpError.AcpRequestId): string {
  const prefix = "$t3:jsonrpc:";
  if (typeof requestId === "number") return `${prefix}number:${requestId}`;
  return requestId.startsWith(prefix) ? `${prefix}string:${requestId}` : requestId;
}

export type AcpRequestHandler<Request, Response> = (
  request: Request,
  context: AcpRequestContext,
) => Effect.Effect<Response, AcpError.AcpError>;

export type AcpIncomingNotification =
  | {
      readonly _tag: "SessionUpdate";
      readonly method: typeof CLIENT_METHODS.session_update;
      readonly params:
        | AcpSchema.UpdateSessionNotification
        | AcpSchemaV1.SessionNotification
        | AcpCompat.SessionNotification;
    }
  | {
      readonly _tag: "ElicitationComplete";
      readonly method: typeof CLIENT_METHODS.elicitation_complete | "session/elicitation/complete";
      readonly params: AcpSchema.CompleteElicitationNotification;
    }
  | {
      readonly _tag: "ExtNotification";
      readonly method: string;
      readonly params: unknown;
    };

export interface AcpStdio extends Omit<Stdio.Stdio, "stdin"> {
  readonly stdin: Stream.Stream<Uint8Array, PlatformError.PlatformError | AcpError.AcpError>;
}

export interface AcpPatchedProtocolOptions {
  readonly stdio: AcpStdio;
  readonly terminationError?: Effect.Effect<AcpError.AcpError>;
  readonly serverRequestMethods: ReadonlySet<string>;
  readonly logIncoming?: boolean;
  readonly logOutgoing?: boolean;
  readonly logger?: (event: AcpProtocolLogEvent) => Effect.Effect<void, never>;
  readonly onIncomingRequest?: (
    requestId: string,
    method: string,
    payload: unknown,
  ) => Effect.Effect<void, never>;

  readonly transformSessionUpdate?: (
    notification:
      | AcpSchema.UpdateSessionNotification
      | AcpSchemaV1.SessionNotification
      | AcpCompat.SessionNotification,
  ) =>
    | AcpSchema.UpdateSessionNotification
    | AcpSchemaV1.SessionNotification
    | AcpCompat.SessionNotification;
  readonly onNotification?: (
    notification: AcpIncomingNotification,
  ) => Effect.Effect<void, AcpError.AcpError, never>;
  readonly onExtRequest?: (
    method: string,
    params: unknown,
    context: AcpRequestContext,
  ) => Effect.Effect<unknown, AcpError.AcpError, never>;
  readonly onTermination?: (error: AcpError.AcpError) => Effect.Effect<void, never, never>;
  readonly onOutgoingResponseFailure?: (
    requestId: string,
    error: AcpError.AcpError,
  ) => Effect.Effect<void, never>;
  readonly onOutgoingResponse?: (requestId: string) => Effect.Effect<void, never>;
  readonly testHooks?: {
    readonly onOutgoingWriteAdmitted?: () => Effect.Effect<void>;
    readonly onOutgoingWriterExit?: (input: {
      readonly intentionalEnd: boolean;
    }) => Effect.Effect<void>;
  };
}

export interface AcpPatchedProtocol {
  readonly clientProtocol: RpcClient.Protocol["Service"];
  readonly serverProtocol: RpcServer.Protocol["Service"];
  readonly incoming: Stream.Stream<AcpIncomingNotification>;
  readonly request: (method: string, payload: unknown) => Effect.Effect<unknown, AcpError.AcpError>;
  readonly notify: (method: string, payload: unknown) => Effect.Effect<void, AcpError.AcpError>;
}

interface AcpPendingRequest {
  readonly deferred: Deferred.Deferred<unknown, AcpError.AcpError>;
  readonly method: string;
}

interface AcpOutgoingWrite {
  readonly acknowledgement?: Deferred.Deferred<void, AcpError.AcpError>;
  readonly payload: string | Uint8Array;
}

interface AcpOutgoingWriterState {
  readonly outstandingAcknowledgements: ReadonlySet<Deferred.Deferred<void, AcpError.AcpError>>;
  readonly intentionalEnd: boolean;
  readonly terminalError?: AcpError.AcpError;
}

const decodeSessionUpdate = Schema.decodeUnknownEffect(
  Schema.Union([
    // Claude ACP v2 reports prompt failures on idle; alpha.3 omits that field.
    Schema.Struct({
      ...AcpSchema.UpdateSessionNotification.fields,
      update: Schema.Struct({
        sessionUpdate: Schema.Literal("state_update"),
        state: Schema.Literal("idle"),
        stopReason: Schema.optionalKey(Schema.NullOr(AcpSchema.StopReason)),
        usage: Schema.optionalKey(Schema.NullOr(AcpSchema.Usage)),
        error: Schema.optionalKey(Schema.NullOr(AcpSchema.Error)),
        _meta: AcpSchema.UpdateSessionNotification.fields._meta,
      }),
    }),
    AcpSchema.UpdateSessionNotification,
    AcpSchemaV1.SessionNotification,
  ]),
);
const decodeElicitationComplete = Schema.decodeUnknownEffect(
  AcpSchema.CompleteElicitationNotification,
);
const parserFactory = RpcSerialization.ndJsonRpc();
// ndJsonRpc skips lines that are not JSON. A malformed agent line has to end the
// session, so frames are split here and each one goes through the strict codec.
const makeStrictNdJsonRpcParser = () => {
  const codec = RpcSerialization.jsonRpc().makeUnsafe();
  const decoder = new TextDecoder();
  let buffer = "";
  return {
    decode: (bytes: Uint8Array | string): ReadonlyArray<unknown> => {
      const chunk = typeof bytes === "string" ? bytes : decoder.decode(bytes, { stream: true });
      const lastNewline = chunk.lastIndexOf("\n");
      // Splitting the whole buffer per chunk is quadratic for multi-megabyte lines.
      if (lastNewline === -1) {
        buffer += chunk;
        return [];
      }
      const lines = (buffer + chunk.slice(0, lastNewline)).split("\n");
      buffer = chunk.slice(lastNewline + 1);
      return lines.flatMap((line) => codec.decode(line));
    },
    // A truncated final line is left to the exit status, which explains a crash better.
    end: (): ReadonlyArray<unknown> => {
      const line = buffer + decoder.decode();
      buffer = "";
      try {
        return line.trim() === "" ? [] : codec.decode(line);
      } catch {
        return [];
      }
    },
    encode: (response: Parameters<typeof codec.encode>[0]) => {
      const encoded = codec.encode(response);
      return encoded === undefined ? undefined : `${encoded}\n`;
    },
  };
};
const MAX_BUFFERED_RAW_NOTIFICATIONS = 32;

const decodeFailureDiagnostics = (error: AcpError.AcpProtocolParseError) => ({
  operation: error.operation,
  ...(error.method === undefined ? {} : { method: error.method }),
  ...(error.requestId === undefined ? {} : { requestId: error.requestId }),
  ...(error.issueCount === undefined ? {} : { issueCount: error.issueCount }),
  ...(error.issueKinds === undefined ? {} : { issueKinds: error.issueKinds }),
  ...(error.maximumPathDepth === undefined ? {} : { maximumPathDepth: error.maximumPathDepth }),
  ...(error.issueSummary === undefined ? {} : { issueSummary: error.issueSummary }),
});
const encodeJsonRpcNotification = Schema.encodeUnknownExit(
  Schema.fromJsonString(
    Schema.Struct({
      jsonrpc: Schema.Literal("2.0"),
      method: Schema.String,
      params: Schema.Unknown,
    }),
  ),
);

/**
 * First id for typed Effect RPC requests. Starts within signed int32 for SDKs that reject
 * larger numeric ids (e.g. the Kotlin ACP SDK decodes ids as `Int`), while staying far
 * above extension ids, which count up from 1.
 */
export const RPC_REQUEST_ID_START = 2 ** 30;

const isEffectRpcRequestId = (requestId: AcpError.AcpRequestId): boolean =>
  typeof requestId === "number" && Number.isSafeInteger(requestId);

/**
 * Effect RPC's JSON-RPC codec treats a standard JSON-RPC error object as a
 * defect unless it carries Effect's private `_tag: "Cause"` envelope.
 */
function normalizeAcpJsonRpcError(
  message: RpcMessage.FromClientEncoded | RpcMessage.FromServerEncoded,
): RpcMessage.FromClientEncoded | RpcMessage.FromServerEncoded {
  if (message._tag !== "Exit" || message.exit._tag !== "Failure") return message;
  const [failure] = message.exit.cause;
  if (
    message.exit.cause.length !== 1 ||
    failure?._tag !== "Die" ||
    !isProtocolError(failure.defect)
  ) {
    return message;
  }
  return {
    ...message,
    exit: {
      _tag: "Failure",
      cause: [{ _tag: "Fail", error: failure.defect }],
    },
  };
}

export const makeAcpPatchedProtocol = Effect.fn("makeAcpPatchedProtocol")(function* (
  options: AcpPatchedProtocolOptions,
): Effect.fn.Return<AcpPatchedProtocol, never, Scope.Scope> {
  const parser = makeStrictNdJsonRpcParser();
  const serverQueue = yield* Queue.unbounded<RpcMessage.FromClientEncoded>();
  const clientQueue = yield* Queue.unbounded<RpcMessage.FromServerEncoded>();
  const notificationQueue = yield* Queue.sliding<AcpIncomingNotification>(
    MAX_BUFFERED_RAW_NOTIFICATIONS,
  );
  const disconnects = yield* Queue.unbounded<number>();
  const outgoing = yield* Queue.unbounded<AcpOutgoingWrite, AcpError.AcpError | Cause.Done<void>>();
  const outgoingWriterState = yield* Ref.make<AcpOutgoingWriterState>({
    intentionalEnd: false,
    outstandingAcknowledgements: new Set(),
  });
  const nextRequestId = yield* Ref.make(1);
  const warnedDecodeFailures = new Set<string>();
  const terminationHandled = yield* Ref.make(false);
  const terminationFailure = yield* Deferred.make<never, AcpError.AcpError>();
  const extPending = yield* Ref.make(new Map<string, AcpPendingRequest>());

  const ensureActive = Ref.get(terminationHandled).pipe(
    Effect.flatMap((terminated) => (terminated ? Deferred.await(terminationFailure) : Effect.void)),
  );

  const logProtocol = (event: AcpProtocolLogEvent) => {
    if (event.direction === "incoming" && !options.logIncoming) {
      return Effect.void;
    }
    if (event.direction === "outgoing" && !options.logOutgoing) {
      return Effect.void;
    }
    return (
      options.logger?.(event) ??
      Effect.logDebug("ACP protocol event").pipe(Effect.annotateLogs({ event }))
    );
  };

  const offerOutgoing = Effect.fn("offerOutgoing")(function* (
    message: RpcMessage.FromClientEncoded | RpcMessage.FromServerEncoded,
  ) {
    // RpcClient emits `@effect/rpc/Interrupt` when a pending request's fiber is interrupted.
    // ACP has no such method; agents log it as an error and cannot act on it, so drop it.
    if (message._tag === "Interrupt") {
      return;
    }
    yield* ensureActive;
    yield* logProtocol({
      direction: "outgoing",
      stage: "decoded",
      payload: message,
    });

    const method = message._tag === "Request" ? message.tag : undefined;
    const encodedRequestId =
      message._tag === "Request"
        ? message.id
        : "requestId" in message
          ? message.requestId
          : undefined;
    const requestId = encodedRequestId === "" ? undefined : encodedRequestId;
    const encoded = yield* Effect.try({
      try: () => parser.encode(message),
      catch: (cause) => AcpError.AcpProtocolParseError.fromEncodingError(method, requestId, cause),
    });

    if (encoded) {
      yield* logProtocol({
        direction: "outgoing",
        stage: "raw",
        payload: typeof encoded === "string" ? encoded : new TextDecoder().decode(encoded),
      });

      yield* ensureActive;
      const acknowledgement =
        message._tag === "Exit" ? yield* Deferred.make<void, AcpError.AcpError>() : undefined;
      const admissionError = yield* Ref.modify(outgoingWriterState, (state) => {
        if (state.terminalError !== undefined) {
          return [state.terminalError, state] as const;
        }
        if (acknowledgement === undefined) {
          return [undefined, state] as const;
        }
        return [
          undefined,
          {
            ...state,
            outstandingAcknowledgements: new Set(state.outstandingAcknowledgements).add(
              acknowledgement,
            ),
          },
        ] as const;
      });
      if (admissionError !== undefined) {
        return yield* admissionError;
      }
      if (options.testHooks?.onOutgoingWriteAdmitted !== undefined) {
        yield* options.testHooks.onOutgoingWriteAdmitted();
      }
      yield* Queue.offer(outgoing, {
        payload: encoded,
        ...(acknowledgement === undefined ? {} : { acknowledgement }),
      }).pipe(
        Effect.mapError(
          (cause) =>
            new AcpError.AcpTransportError({
              detail: "Failed to queue an outgoing ACP message",
              cause,
            }),
        ),
        Effect.filterOrFail(
          (accepted) => accepted,
          () =>
            new AcpError.AcpTransportError({
              detail: "The ACP output queue was closed before accepting a message",
              cause: "Output queue closed",
            }),
        ),
        Effect.tapError((error) =>
          acknowledgement === undefined
            ? Effect.void
            : Ref.update(outgoingWriterState, (state) => {
                const updated = new Set(state.outstandingAcknowledgements);
                updated.delete(acknowledgement);
                return { ...state, outstandingAcknowledgements: updated };
              }).pipe(Effect.andThen(Deferred.fail(acknowledgement, error)), Effect.asVoid),
        ),
      );
      if (acknowledgement !== undefined) {
        yield* Deferred.await(acknowledgement);
      }
      if (message._tag === "Exit" && options.onOutgoingResponse !== undefined) {
        yield* options.onOutgoingResponse(acpRequestIdentity(message.requestId));
      }
    }
  });

  const resolveExtPending = (
    requestId: AcpError.AcpRequestId,
    onFound: (pendingRequest: AcpPendingRequest) => Effect.Effect<void>,
  ) =>
    Ref.modify(extPending, (pending) => {
      const pendingKey = acpRequestIdentity(requestId);
      const pendingRequest = pending.get(pendingKey);
      if (!pendingRequest) {
        return [Effect.void, pending] as const;
      }
      const next = new Map(pending);
      next.delete(pendingKey);
      return [onFound(pendingRequest), next] as const;
    }).pipe(Effect.flatten);

  const removeExtPending = (requestId: AcpError.AcpRequestId) =>
    Ref.update(extPending, (pending) => {
      const pendingKey = acpRequestIdentity(requestId);
      if (!pending.has(pendingKey)) {
        return pending;
      }
      const next = new Map(pending);
      next.delete(pendingKey);
      return next;
    });

  const completeExtPendingFailure = (requestId: AcpError.AcpRequestId, error: AcpError.AcpError) =>
    resolveExtPending(requestId, ({ deferred }) => Deferred.fail(deferred, error));

  const completeExtPendingSuccess = (requestId: AcpError.AcpRequestId, value: unknown) =>
    resolveExtPending(requestId, ({ deferred }) => Deferred.succeed(deferred, value));

  const failAllExtPending = (error: AcpError.AcpError) =>
    Ref.getAndSet(extPending, new Map()).pipe(
      Effect.flatMap((pending) =>
        Effect.forEach([...pending.values()], ({ deferred }) => Deferred.fail(deferred, error), {
          discard: true,
        }),
      ),
    );

  const dispatchNotification = (notification: AcpIncomingNotification) =>
    Queue.offer(notificationQueue, notification).pipe(
      Effect.andThen(
        // A failing or dying handler must not stop the reader, or every later
        // message on the connection goes unanswered.
        options.onNotification
          ? isolateNotificationHandler(options.onNotification(notification))
          : Effect.void,
      ),
      Effect.asVoid,
    );

  const emitClientProtocolError = (error: AcpError.AcpError) =>
    Queue.offer(clientQueue, {
      _tag: "ClientProtocolError",
      error: new RpcClientError.RpcClientError({
        reason: new RpcClientError.RpcClientDefect({
          message: "ACP protocol terminated.",
          cause: error,
        }),
      }),
    }).pipe(Effect.asVoid);

  const handleTermination = (classify: () => Effect.Effect<AcpError.AcpError>) =>
    Ref.modify(terminationHandled, (handled) => {
      if (handled) {
        return [Effect.void, true] as const;
      }
      return [
        Effect.gen(function* () {
          yield* Queue.offer(disconnects, 0);
          const error = yield* classify();
          yield* Deferred.fail(terminationFailure, error);
          yield* failAllExtPending(error);
          yield* emitClientProtocolError(error);
          if (options.onTermination) {
            yield* options.onTermination(error);
          }
        }),
        true,
      ] as const;
    }).pipe(Effect.flatten);

  const respondWithSuccess = (requestId: AcpError.AcpRequestId, value: unknown) =>
    offerOutgoing({
      _tag: "Exit",
      requestId,
      exit: {
        _tag: "Success",
        value,
      },
    });

  const respondWithError = (requestId: AcpError.AcpRequestId, error: AcpError.AcpRequestError) =>
    offerOutgoing({
      _tag: "Exit",
      requestId,
      exit: {
        _tag: "Failure",
        cause: [
          {
            _tag: "Fail",
            error: error.toProtocolError(),
          },
        ],
      },
    });

  const handleExtRequest = (message: RpcMessage.RequestEncoded) => {
    if (!options.onExtRequest) {
      return respondWithError(message.id, AcpError.AcpRequestError.methodNotFound(message.tag));
    }
    return options
      .onExtRequest(message.tag, message.payload, {
        requestId: acpRequestIdentity(message.id),
        method: message.tag,
      })
      .pipe(
        Effect.matchCauseEffect({
          onFailure: (cause) => {
            const failure = Cause.hasDies(cause) ? Option.none() : Cause.findErrorOption(cause);
            if (Option.isSome(failure)) {
              return respondWithError(
                message.id,
                AcpError.AcpRequestError.fromExtensionHandlerError(failure.value, message.tag),
              );
            }
            return Effect.logError(
              `ACP extension request handler failed for '${message.tag}'`,
              cause,
            ).pipe(
              Effect.andThen(
                respondWithError(
                  message.id,
                  AcpError.AcpRequestError.internalError(
                    `ACP extension request handler failed for method '${message.tag}'`,
                    undefined,
                    {
                      method: message.tag,
                      operation: "handle-extension-request",
                      cause: Cause.squash(cause),
                    },
                  ),
                ),
              ),
            );
          },
          onSuccess: (value) => respondWithSuccess(message.id, value),
        }),
      );
  };

  // Drop undecodable notifications without ending working sessions; newer specs may add unknown shapes.
  // Warn once per distinct failure per connection because agents repeat bad payloads.
  const dropUndecodableNotification = (method: string) => (cause: Schema.SchemaError) => {
    const error = AcpError.AcpProtocolParseError.fromSchemaError(
      "decode-notification-payload",
      method,
      cause,
    );
    const diagnostics = decodeFailureDiagnostics(error);
    const key = `${method}\n${error.issueSummary}`;
    const firstOfItsKind = !warnedDecodeFailures.has(key);
    warnedDecodeFailures.add(key);
    return logProtocol({
      direction: "incoming",
      stage: "decode_failed",
      payload: diagnostics,
    }).pipe(
      Effect.andThen(
        firstOfItsKind
          ? Effect.logWarning("Dropped an ACP notification that failed to decode").pipe(
              Effect.annotateLogs(diagnostics),
            )
          : Effect.void,
      ),
    );
  };

  const handleRequestEncoded = (message: RpcMessage.RequestEncoded) => {
    if (message.id === "") {
      if (message.tag === CLIENT_METHODS.session_update) {
        return decodeSessionUpdate(message.payload).pipe(
          Effect.matchEffect({
            onFailure: dropUndecodableNotification(CLIENT_METHODS.session_update),
            onSuccess: (params) =>
              dispatchNotification({
                _tag: "SessionUpdate",
                method: CLIENT_METHODS.session_update,
                params: options.transformSessionUpdate?.(params) ?? params,
              }),
          }),
        );
      }
      if (
        message.tag === CLIENT_METHODS.elicitation_complete ||
        message.tag === "session/elicitation/complete"
      ) {
        const method = message.tag;
        return decodeElicitationComplete(message.payload).pipe(
          Effect.matchEffect({
            onFailure: dropUndecodableNotification(method),
            onSuccess: (params) =>
              dispatchNotification({ _tag: "ElicitationComplete", method, params }),
          }),
        );
      }
      return dispatchNotification({
        _tag: "ExtNotification",
        method: message.tag,
        params: message.payload,
      });
    }

    const observeIncoming =
      options.onIncomingRequest?.(acpRequestIdentity(message.id), message.tag, message.payload) ??
      Effect.void;

    if (!options.serverRequestMethods.has(message.tag)) {
      return observeIncoming.pipe(
        Effect.andThen(handleExtRequest(message)),
        Effect.catchTags({
          AcpProtocolParseError: (error) =>
            Effect.logWarning(error).pipe(
              Effect.annotateLogs({
                method: message.tag,
                requestId: message.id,
                operation: error.operation,
              }),
              Effect.andThen(
                respondWithError(
                  message.id,
                  AcpError.AcpRequestError.fromExtensionResponseEncodingError(
                    message.tag,
                    message.id,
                    error,
                  ),
                ),
              ),
            ),
        }),
        Effect.asVoid,
      );
    }

    return observeIncoming.pipe(Effect.andThen(Queue.offer(serverQueue, message)), Effect.asVoid);
  };

  const forwardToRpcClient = (
    message: RpcMessage.ResponseChunkEncoded | RpcMessage.ResponseExitEncoded,
  ) =>
    isEffectRpcRequestId(message.requestId)
      ? Queue.offer(clientQueue, message).pipe(Effect.asVoid)
      : Effect.void;

  const handleExitEncoded = (message: RpcMessage.ResponseExitEncoded) =>
    Ref.get(extPending).pipe(
      Effect.flatMap((pending) => {
        const pendingRequest = pending.get(acpRequestIdentity(message.requestId));
        if (!pendingRequest) {
          return forwardToRpcClient(message);
        }
        if (message.exit._tag === "Success") {
          return completeExtPendingSuccess(message.requestId, message.exit.value);
        }
        const failure = message.exit.cause.find((entry) => entry._tag === "Fail");
        if (failure && isProtocolError(failure.error)) {
          return completeExtPendingFailure(
            message.requestId,
            AcpError.AcpRequestError.fromProtocolError(failure.error, {
              method: pendingRequest.method,
              requestId: message.requestId,
              cause: message.exit.cause,
            }),
          );
        }
        return completeExtPendingFailure(
          message.requestId,
          AcpError.AcpRequestError.fromExtensionResponseFailure(
            pendingRequest.method,
            message.requestId,
            message.exit.cause,
          ),
        );
      }),
    );

  const routeDecodedMessage = (
    message: RpcMessage.FromClientEncoded | RpcMessage.FromServerEncoded,
  ): Effect.Effect<void, AcpError.AcpError> => {
    switch (message._tag) {
      case "Request":
        return handleRequestEncoded(message);
      case "Exit":
        return handleExitEncoded(message);
      case "Chunk":
        return Ref.get(extPending).pipe(
          Effect.flatMap((pending) => {
            const pendingRequest = pending.get(acpRequestIdentity(message.requestId));
            return pendingRequest
              ? completeExtPendingFailure(
                  message.requestId,
                  AcpError.AcpRequestError.unsupportedStreamingResponse(
                    pendingRequest.method,
                    message.requestId,
                  ),
                )
              : forwardToRpcClient(message);
          }),
        );
      case "Defect":
      case "ClientProtocolError":
      case "Pong":
        return Queue.offer(clientQueue, message).pipe(Effect.asVoid);
      case "Ack":
      case "Interrupt":
      case "Ping":
      case "Eof":
        return Queue.offer(serverQueue, message).pipe(Effect.asVoid);
    }
  };

  yield* options.stdio.stdin.pipe(
    Stream.runForEach((data) =>
      (options.logIncoming
        ? logProtocol({
            direction: "incoming",
            stage: "raw",
            payload: typeof data === "string" ? data : new TextDecoder().decode(data),
          })
        : Effect.void
      ).pipe(
        Effect.flatMap(() =>
          Effect.try({
            try: () =>
              (
                parser.decode(data) as ReadonlyArray<
                  RpcMessage.FromClientEncoded | RpcMessage.FromServerEncoded
                >
              ).map(normalizeAcpJsonRpcError),
            catch: (cause) =>
              new AcpError.AcpProtocolParseError({
                operation: "decode-wire-message",
                cause,
              }),
          }),
        ),
        Effect.tap((messages) =>
          logProtocol({
            direction: "incoming",
            stage: "decoded",
            payload: messages,
          }),
        ),
        Effect.tapErrorTag("AcpProtocolParseError", (error) =>
          logProtocol({
            direction: "incoming",
            stage: "decode_failed",
            payload: decodeFailureDiagnostics(error),
          }),
        ),
        Effect.flatMap((messages) =>
          Effect.forEach(messages, routeDecodedMessage, {
            discard: true,
          }),
        ),
      ),
    ),
    Effect.andThen(
      Effect.suspend(() =>
        Effect.forEach(
          (
            parser.end() as ReadonlyArray<
              RpcMessage.FromClientEncoded | RpcMessage.FromServerEncoded
            >
          ).map(normalizeAcpJsonRpcError),
          routeDecodedMessage,
          { discard: true },
        ),
      ),
    ),
    // Anything that ends the reader, including a defect in a callback it runs,
    // terminates the connection so pending requests fail instead of hanging.
    Effect.matchCauseEffect({
      onFailure: (cause) => {
        const failure = Cause.findErrorOption(cause);
        const error = Option.isSome(failure) ? failure.value : Cause.squash(cause);
        const normalized: AcpError.AcpError = isAcpError(error)
          ? error
          : new AcpError.AcpTransportError({
              operation: "read-input-stream",
              cause: error,
            });
        return handleTermination(() => Effect.succeed(normalized));
      },
      onSuccess: () =>
        handleTermination(() => {
          const ended = new AcpError.AcpInputStreamEndedError({});
          if (!options.terminationError) return Effect.succeed(ended);
          // Stdout can close without process exit; use a live-clock diagnostic grace period.
          return options.terminationError.pipe(
            Effect.timeoutOption("250 millis"),
            Effect.provideService(Clock.Clock, Clock.Clock.defaultValue()),
            Effect.map(Option.getOrElse(() => ended)),
          );
        }),
    }),
    Effect.forkScoped,
  );

  const failOutgoingWrites = (error: AcpError.AcpError) =>
    Ref.modify(outgoingWriterState, (state) => {
      const terminalError = state.terminalError ?? error;
      return [
        [terminalError, state.outstandingAcknowledgements] as const,
        {
          ...state,
          terminalError,
          outstandingAcknowledgements: new Set<Deferred.Deferred<void, AcpError.AcpError>>(),
        },
      ] as const;
    }).pipe(
      Effect.flatMap((acknowledgements) =>
        Effect.forEach(
          acknowledgements[1],
          (acknowledgement) => Deferred.fail(acknowledgement, acknowledgements[0]),
          { concurrency: "unbounded", discard: true },
        ),
      ),
      Effect.andThen(Queue.fail(outgoing, error)),
      Effect.asVoid,
    );
  const completeOutgoingWrites = () =>
    Ref.modify(outgoingWriterState, (state) => {
      return [
        state.outstandingAcknowledgements,
        {
          ...state,
          outstandingAcknowledgements: new Set<Deferred.Deferred<void, AcpError.AcpError>>(),
        },
      ] as const;
    }).pipe(
      Effect.flatMap((acknowledgements) =>
        Effect.forEach(
          acknowledgements,
          (acknowledgement) => Deferred.succeed(acknowledgement, undefined),
          { concurrency: "unbounded", discard: true },
        ),
      ),
      Effect.asVoid,
    );
  const acknowledgeOutgoingWrite = (acknowledgement: Deferred.Deferred<void, AcpError.AcpError>) =>
    Ref.update(outgoingWriterState, (state) => {
      const updated = new Set(state.outstandingAcknowledgements);
      updated.delete(acknowledgement);
      return { ...state, outstandingAcknowledgements: updated };
    }).pipe(Effect.andThen(Deferred.succeed(acknowledgement, undefined)), Effect.asVoid);
  yield* Stream.fromQueue(outgoing).pipe(
    Stream.flatMap((write) => {
      const acknowledgement = write.acknowledgement;
      const completion =
        acknowledgement === undefined
          ? Stream.empty
          : Stream.fromEffect(acknowledgeOutgoingWrite(acknowledgement)).pipe(Stream.drain);
      return Stream.make(write.payload).pipe(Stream.concat(completion));
    }),
    Stream.run(options.stdio.stdout()),
    Effect.onExit((exit) =>
      Exit.match(exit, {
        onFailure: (cause) => {
          const error = new AcpError.AcpTransportError({
            detail: Cause.hasInterruptsOnly(cause)
              ? "The ACP output writer was interrupted while closing"
              : "Failed to write an outgoing ACP message",
            cause,
          });
          return failOutgoingWrites(error).pipe(
            Effect.andThen(
              Cause.hasInterruptsOnly(cause)
                ? Effect.void
                : handleTermination(() => Effect.succeed(error)),
            ),
          );
        },
        onSuccess: () =>
          Ref.get(outgoingWriterState).pipe(
            Effect.flatMap((state) => {
              const handled = state.intentionalEnd
                ? completeOutgoingWrites()
                : (() => {
                    const error = new AcpError.AcpTransportError({
                      detail: "ACP output writer ended before the protocol closed",
                      cause: "Output writer ended",
                    });
                    return failOutgoingWrites(error).pipe(
                      Effect.andThen(handleTermination(() => Effect.succeed(error))),
                    );
                  })();
              return handled.pipe(
                Effect.andThen(
                  options.testHooks?.onOutgoingWriterExit === undefined
                    ? Effect.void
                    : options.testHooks.onOutgoingWriterExit({
                        intentionalEnd: state.intentionalEnd,
                      }),
                ),
              );
            }),
          ),
      }),
    ),
    Effect.forkScoped,
  );

  // Protocol loops and per-message sends share the caller's operation span.
  const clientProtocol = RpcClient.Protocol.of({
    run: Effect.fnUntraced(function* (_clientId, f) {
      return yield* Stream.fromQueue(clientQueue).pipe(
        Stream.runForEach((message) => f(message)),
        Effect.forever,
      );
    }),
    send: Effect.fnUntraced(function* (_clientId, request) {
      return yield* offerOutgoing(request).pipe(
        Effect.mapError(
          (error) =>
            new RpcClientError.RpcClientError({
              reason: new RpcClientError.RpcClientDefect({
                message: "Failed to send ACP protocol message.",
                cause: error,
              }),
            }),
        ),
      );
    }),
    supportsAck: true,
    supportsTransferables: false,
    codecFor: parserFactory.codecFor,
  });

  const serverProtocol = RpcServer.Protocol.of({
    run: Effect.fnUntraced(function* (f) {
      return yield* Stream.fromQueue(serverQueue).pipe(
        Stream.runForEach((message) => f(0, message)),
        Effect.forever,
      );
    }),
    disconnects,
    send: Effect.fnUntraced(function* (_clientId, response) {
      return yield* offerOutgoing(response).pipe(
        Effect.tapError((error) =>
          response._tag === "Exit" && options.onOutgoingResponseFailure !== undefined
            ? options.onOutgoingResponseFailure(acpRequestIdentity(response.requestId), error)
            : Effect.void,
        ),
        Effect.orDie,
      );
    }),
    end: Effect.fn("RpcServer.Protocol.end")(function (_clientId) {
      return Ref.update(outgoingWriterState, (state) => ({ ...state, intentionalEnd: true })).pipe(
        Effect.andThen(Queue.end(outgoing)),
      );
    }),
    clientIds: Effect.succeed(new Set([0])),
    initialMessage: Effect.succeedNone,
    supportsAck: true,
    supportsTransferables: false,
    codecFor: parserFactory.codecFor,
    supportsSpanPropagation: true,
    supportsNotifications: true,
  });

  // JSON-RPC notifications carry no `id`. Encoding a Request without `isNotification`
  // emits an `id`, which real agents (Grok CLI) parse as a malformed request and silently drop.
  const sendNotification = Effect.fn("sendNotification")(function* (
    method: string,
    payload: unknown,
  ) {
    yield* ensureActive;
    yield* logProtocol({
      direction: "outgoing",
      stage: "decoded",
      payload: { _tag: "Notification", tag: method, payload },
    });
    const exit = encodeJsonRpcNotification({ jsonrpc: "2.0", method, params: payload });
    if (Exit.isFailure(exit)) {
      return yield* AcpError.AcpProtocolParseError.fromEncodingError(
        method,
        undefined,
        Cause.squash(exit.cause),
      );
    }
    const encoded = `${exit.value}\n`;
    yield* logProtocol({ direction: "outgoing", stage: "raw", payload: encoded });
    yield* ensureActive;
    // FIFO queue admission preserves wire ordering against later requests
    // (a session/prompt sent after session/cancel cannot overtake it).
    yield* Queue.offer(outgoing, { payload: encoded }).pipe(
      Effect.mapError(
        (cause) =>
          new AcpError.AcpTransportError({
            detail: "Failed to queue an outgoing ACP notification",
            cause,
          }),
      ),
      Effect.filterOrFail(
        (accepted) => accepted,
        () =>
          new AcpError.AcpTransportError({
            detail: "The ACP output queue was closed before accepting a notification",
            cause: "Output queue closed",
          }),
      ),
    );
  });

  const sendRequest = Effect.fn("sendRequest")(function* (method: string, payload: unknown) {
    yield* ensureActive;
    const requestId = yield* Ref.modify(
      nextRequestId,
      (current) => [current, current + 1] as const,
    );
    const deferred = yield* Deferred.make<unknown, AcpError.AcpError>();
    yield* Ref.update(extPending, (pending) =>
      new Map(pending).set(acpRequestIdentity(requestId), { deferred, method }),
    );
    yield* offerOutgoing({
      _tag: "Request",
      id: requestId,
      tag: method,
      payload,
      headers: [],
    }).pipe(Effect.tapError(() => removeExtPending(requestId)));
    return yield* Deferred.await(deferred).pipe(
      Effect.onInterrupt(() => removeExtPending(requestId)),
    );
  });

  return {
    clientProtocol,
    serverProtocol,
    get incoming() {
      return Stream.fromQueue(notificationQueue);
    },
    request: sendRequest,
    notify: sendNotification,
  } satisfies AcpPatchedProtocol;
});

const isProtocolError = Schema.is(AcpSchema.Error);