Skip to content

Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.

17.4 KB
Raw Blame
import * as Predicate from "effect/Predicate";
import * as Cause from "effect/Cause";
import * as Deferred from "effect/Deferred";
import * as Effect from "effect/Effect";
import * as Queue from "effect/Queue";
import * as Ref from "effect/Ref";
import * as Scope from "effect/Scope";
import * as Schema from "effect/Schema";
import * as Stdio from "effect/Stdio";
import * as Stream from "effect/Stream";

import * as CodexError from "./errors.ts";
import { JsonRpcResponseEnvelope, JsonRpcRequestEnvelope } from "./_internal/shared.ts";

const isJsonRpcResponseEnvelope = Schema.is(JsonRpcResponseEnvelope);

const isCodexAppServerError = Schema.is(CodexError.CodexAppServerError);

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

export interface CodexAppServerIncomingNotification {
  readonly method: string;
  readonly params?: unknown;
}

export interface CodexAppServerIncomingRequest {
  readonly id: string | number;
  readonly method: string;
  readonly params?: unknown;
}

export interface CodexAppServerPatchedProtocolOptions {
  readonly stdio: Stdio.Stdio;
  readonly terminationError?: Effect.Effect<CodexError.CodexAppServerError>;
  /**
   * Enables raw notification observation. Zero (the default) returns an empty stream.
   * A positive integer retains the newest N unread events, dropping the oldest on overflow.
   * "unbounded" preserves the legacy lossless FIFO, including all events before a late reader.
   * Buffers never block callback dispatch; finite buffers can also drop events for slow readers.
   */
  readonly rawNotificationBufferSize?: number | "unbounded";
  /**
   * Enables raw request observation with the same buffering rules as rawNotificationBufferSize.
   * Observation does not replace onRequest or send replies; finite buffers can drop requests.
   */
  readonly rawRequestBufferSize?: number | "unbounded";
  readonly logIncoming?: boolean;
  readonly logOutgoing?: boolean;
  readonly logger?: (event: CodexAppServerProtocolLogEvent) => Effect.Effect<void, never>;
  readonly onNotification?: (
    notification: CodexAppServerIncomingNotification,
  ) => Effect.Effect<void, never>;
  readonly onRequest?: (
    request: CodexAppServerIncomingRequest,
  ) => Effect.Effect<JsonRpcResponseEnvelope["result"], CodexError.CodexAppServerError>;
  readonly onTermination?: (error: CodexError.CodexAppServerError) => Effect.Effect<void, never>;
}

export interface CodexAppServerPatchedProtocol {
  /**
   * Opt-in FIFO shared by readers, not a broadcast. Disabled streams end immediately.
   * Enabled streams drain on input termination; scope closure discards the buffer and interrupts readers.
   */
  readonly incomingNotifications: Stream.Stream<CodexAppServerIncomingNotification>;
  /**
   * Opt-in request observation with the same stream lifecycle as incomingNotifications.
   * Reading does not send a reply or disable onRequest.
   */
  readonly incomingRequests: Stream.Stream<CodexAppServerIncomingRequest>;
  readonly request: (
    method: string,
    payload?: JsonRpcRequestEnvelope["params"],
  ) => Effect.Effect<JsonRpcResponseEnvelope["result"], CodexError.CodexAppServerError>;
  readonly notify: (
    method: string,
    payload?: JsonRpcRequestEnvelope["params"],
  ) => Effect.Effect<void, CodexError.CodexAppServerError>;
  readonly respond: (
    requestId: string | number,
    result: JsonRpcResponseEnvelope["result"],
  ) => Effect.Effect<void, CodexError.CodexAppServerError>;
  readonly respondError: (
    requestId: string | number,
    error: CodexError.CodexAppServerRequestError,
  ) => Effect.Effect<void, CodexError.CodexAppServerError>;
}

interface OutgoingMessage {
  readonly id?: string | number;
  readonly method?: string;
  readonly params?: JsonRpcRequestEnvelope["params"];
  readonly result?: JsonRpcResponseEnvelope["result"];
  readonly error?: CodexError.CodexAppServerProtocolErrorShape;
}

interface CodexAppServerPendingRequest {
  readonly deferred: Deferred.Deferred<
    JsonRpcResponseEnvelope["result"],
    CodexError.CodexAppServerError
  >;
  readonly method: string;
}

const isIncomingRequest = Schema.is(JsonRpcRequestEnvelope);

const isNotificationShape = Schema.is(
  Schema.Struct({ method: Schema.String, params: Schema.optional(Schema.Unknown) }),
);

function isIncomingNotification(
  value: JsonRpcRequestEnvelope["params"],
): value is CodexAppServerIncomingNotification {
  return isNotificationShape(value) && !("id" in value);
}

const isIncomingResponse = isJsonRpcResponseEnvelope;

const encodeJsonString = Schema.encodeUnknownEffect(Schema.fromJsonString(Schema.Unknown));

const decodeJsonString = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Unknown));

const encodeWireMessage = (
  message: OutgoingMessage,
): Effect.Effect<string, CodexError.CodexAppServerProtocolParseError> =>
  encodeJsonString(message).pipe(
    Effect.map((encoded) => `${encoded}\n`),
    Effect.mapError((cause) => {
      const method = Predicate.isString(message.method) ? message.method : undefined;

      const requestId =
        Predicate.isString(message.id) || Predicate.isNumber(message.id)
          ? String(message.id)
          : undefined;

      return CodexError.CodexAppServerProtocolParseError.fromSchemaError(
        "encode-wire-message",
        cause,
        {
          ...(method === undefined ? {} : { method }),
          ...(requestId === undefined ? {} : { requestId }),
        },
      );
    }),
  );

const decodeWireMessage = (
  line: string,
): Effect.Effect<JsonRpcRequestEnvelope["params"], CodexError.CodexAppServerProtocolParseError> =>
  decodeJsonString(line).pipe(
    Effect.mapError((cause) =>
      CodexError.CodexAppServerProtocolParseError.fromSchemaError("decode-wire-message", cause),
    ),
  );

const normalizeIncomingError = (
  cause: unknown,
  operation: CodexError.CodexAppServerTransportOperation,
): CodexError.CodexAppServerError =>
  isCodexAppServerError(cause)
    ? cause
    : new CodexError.CodexAppServerTransportError({
        operation,
        cause: cause,
      });

const toProtocolMessage = (
  requestId: string | number,
  fields: {
    readonly result?: unknown;
    readonly error?: CodexError.CodexAppServerProtocolErrorShape;
  },
) => ({
  id: requestId,
  ...(fields.result !== undefined ? { result: fields.result } : {}),
  ...(fields.error !== undefined ? { error: fields.error } : {}),
});

const makeRawQueue = Effect.fn("makeRawQueue")(function* <A>(bufferSize: number | "unbounded" = 0) {
  if (bufferSize === 0) {
    return undefined;
  }

  if (bufferSize !== "unbounded" && (!Number.isSafeInteger(bufferSize) || bufferSize < 0)) {
    return yield* Effect.die(
      new RangeError("Raw buffer size must be a non-negative safe integer or 'unbounded'."),
    );
  }

  return yield* Effect.acquireRelease(
    Queue.sliding<A, Cause.Done<void>>(
      bufferSize === "unbounded" ? Number.POSITIVE_INFINITY : bufferSize,
    ),
    Queue.shutdown,
  );
});

export const makeCodexAppServerPatchedProtocol = Effect.fn("makeCodexAppServerPatchedProtocol")(
  function* (
    options: CodexAppServerPatchedProtocolOptions,
  ): Effect.fn.Return<CodexAppServerPatchedProtocol, never, Scope.Scope> {
    const outgoing = yield* Queue.unbounded<string, Cause.Done<void>>();

    const incomingNotifications = yield* makeRawQueue<CodexAppServerIncomingNotification>(
      options.rawNotificationBufferSize,
    );

    const incomingRequests = yield* makeRawQueue<CodexAppServerIncomingRequest>(
      options.rawRequestBufferSize,
    );

    const pending = yield* Ref.make(new Map<string, CodexAppServerPendingRequest>());
    const nextRequestId = yield* Ref.make(1);
    const remainder: Array<string> = [];
    const terminationHandled = yield* Ref.make(false);

    const logProtocol = (event: CodexAppServerProtocolLogEvent) => {
      if (event.direction === "incoming" && !options.logIncoming) {
        return Effect.void;
      }

      if (event.direction === "outgoing" && !options.logOutgoing) {
        return Effect.void;
      }

      return (
        options.logger?.(event) ??
        Effect.logDebug("Codex App Server protocol event").pipe(Effect.annotateLogs({ event }))
      );
    };

    const failAllPending = (error: CodexError.CodexAppServerError) =>
      Ref.get(pending).pipe(
        Effect.flatMap((current) =>
          Effect.forEach([...current.values()], ({ deferred }) => Deferred.fail(deferred, error), {
            discard: true,
          }),
        ),
        Effect.andThen(Ref.set(pending, new Map())),
      );

    const handleTermination = (classify: () => Effect.Effect<CodexError.CodexAppServerError>) =>
      Ref.modify(terminationHandled, (handled) => {
        if (handled) {
          return [Effect.void, true] as const;
        }

        return [
          Effect.gen(function* () {
            if (incomingNotifications) {
              yield* Queue.end(incomingNotifications);
            }

            if (incomingRequests) {
              yield* Queue.end(incomingRequests);
            }

            const error = yield* classify();
            yield* failAllPending(error);
            yield* Queue.end(outgoing);

            if (options.onTermination) {
              yield* options.onTermination(error);
            }
          }),
          true,
        ] as const;
      }).pipe(Effect.flatten);

    const offerOutgoing = (message: OutgoingMessage) =>
      Effect.gen(function* () {
        yield* logProtocol({
          direction: "outgoing",
          stage: "decoded",
          payload: message,
        });
        const encoded = yield* encodeWireMessage(message);
        yield* logProtocol({
          direction: "outgoing",
          stage: "raw",
          payload: encoded,
        });
        yield* Queue.offer(outgoing, encoded).pipe(Effect.asVoid);
      });

    const removePending = (requestId: string) =>
      Ref.update(pending, (current) => {
        if (!current.has(requestId)) {
          return current;
        }

        const next = new Map(current);
        next.delete(requestId);

        return next;
      });

    const resolvePending = (
      requestId: string,
      handler: (pendingRequest: CodexAppServerPendingRequest) => Effect.Effect<void>,
    ) =>
      Ref.modify(pending, (current) => {
        const pendingRequest = current.get(requestId);

        if (!pendingRequest) {
          return [Effect.void, current] as const;
        }

        const next = new Map(current);
        next.delete(requestId);

        return [handler(pendingRequest), next] as const;
      }).pipe(Effect.flatten);

    const respond = (requestId: string | number, result: JsonRpcResponseEnvelope["result"]) =>
      offerOutgoing(toProtocolMessage(requestId, { result }));

    const respondError = (
      requestId: string | number,
      error: CodexError.CodexAppServerRequestError,
    ) => offerOutgoing(toProtocolMessage(requestId, { error: error.toProtocolError() }));

    const handleResponse = (response: JsonRpcResponseEnvelope) => {
      const requestId = String(response.id);
      const protocolError = response.error;

      if (protocolError !== undefined) {
        return resolvePending(requestId, ({ deferred, method }) =>
          Deferred.fail(
            deferred,
            CodexError.CodexAppServerRequestError.fromProtocolError(
              protocolError,
              method,
              requestId,
            ),
          ),
        );
      }

      return resolvePending(requestId, ({ deferred }) =>
        Deferred.succeed(deferred, response.result),
      );
    };

    const handleRequest = (request: CodexAppServerIncomingRequest) =>
      (incomingRequests ? Queue.offer(incomingRequests, request) : Effect.void).pipe(
        Effect.andThen(
          options.onRequest
            ? options.onRequest(request).pipe(
                Effect.matchEffect({
                  onFailure: (error) =>
                    respondError(
                      request.id,
                      CodexError.CodexAppServerRequestError.fromAppServerError(
                        error,
                        request.method,
                      ),
                    ),
                  onSuccess: (result) => respond(request.id, result),
                }),
              )
            : Effect.void,
        ),
        Effect.asVoid,
      );

    const handleNotification = (notification: CodexAppServerIncomingNotification) =>
      (incomingNotifications ? Queue.offer(incomingNotifications, notification) : Effect.void).pipe(
        Effect.andThen(options.onNotification ? options.onNotification(notification) : Effect.void),
        Effect.asVoid,
      );

    const routeMessage = (message: JsonRpcRequestEnvelope["params"]) => {
      if (isIncomingRequest(message)) {
        return handleRequest(message);
      }

      if (isIncomingNotification(message)) {
        return handleNotification(message);
      }

      if (isIncomingResponse(message)) {
        return handleResponse(message);
      }

      return Effect.fail(
        CodexError.CodexAppServerProtocolParseError.fromUnroutableMessage(message),
      );
    };

    const handleLine = (line: string): Effect.Effect<void, CodexError.CodexAppServerError> => {
      if (line.trim().length === 0) {
        return Effect.void;
      }

      return logProtocol({
        direction: "incoming",
        stage: "raw",
        payload: line,
      }).pipe(
        Effect.flatMap(() => decodeWireMessage(line)),
        Effect.tap((decoded) =>
          logProtocol({
            direction: "incoming",
            stage: "decoded",
            payload: decoded,
          }),
        ),
        Effect.tapErrorTag("CodexAppServerProtocolParseError", (error) =>
          logProtocol({
            direction: "incoming",
            stage: "decode_failed",
            payload: {
              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 }),
            },
          }),
        ),
        Effect.flatMap(routeMessage),
      );
    };

    yield* options.stdio.stdin.pipe(
      Stream.decodeText(),
      Stream.runForEach((chunk) =>
        Effect.sync(() => {
          const lines: Array<string> = [];
          let start = 0;

          for (
            let newline = chunk.indexOf("\n");
            newline !== -1;
            newline = chunk.indexOf("\n", start)
          ) {
            remainder.push(chunk.slice(start, newline));
            lines.push(remainder.join("").replace(/\r$/, ""));
            remainder.length = 0;
            start = newline + 1;
          }

          // Keep unfinished lines in fragments so each chunk is scanned only once.
          if (start < chunk.length) {
            remainder.push(chunk.slice(start));
          }

          return lines;
        }).pipe(Effect.flatMap((lines) => Effect.forEach(lines, handleLine, { discard: true }))),
      ),
      Effect.matchEffect({
        onFailure: (error) =>
          handleTermination(() =>
            Effect.succeed(normalizeIncomingError(error, "read-input-stream")),
          ),
        onSuccess: () =>
          Effect.sync(() => {
            const line = remainder.join("");
            remainder.length = 0;

            return line;
          }).pipe(
            Effect.flatMap(handleLine),
            Effect.matchEffect({
              onFailure: (error) => handleTermination(() => Effect.succeed(error)),
              onSuccess: () =>
                handleTermination(
                  () =>
                    options.terminationError ??
                    Effect.succeed(new CodexError.CodexAppServerInputStreamEndedError({})),
                ),
            }),
          ),
      }),
      Effect.forkScoped,
    );

    yield* Stream.fromQueue(outgoing).pipe(Stream.run(options.stdio.stdout()), Effect.forkScoped);

    const request = (method: string, payload?: JsonRpcRequestEnvelope["params"]) =>
      Effect.gen(function* () {
        const requestId = yield* Ref.modify(
          nextRequestId,
          (current) => [current, current + 1] as const,
        );

        const deferred = yield* Deferred.make<unknown, CodexError.CodexAppServerError>();
        yield* Ref.update(pending, (current) =>
          new Map(current).set(String(requestId), { deferred, method }),
        );
        yield* offerOutgoing({
          id: requestId,
          method,
          ...(payload !== undefined ? { params: payload } : {}),
        }).pipe(Effect.tapError(() => removePending(String(requestId))));

        return yield* Deferred.await(deferred).pipe(
          Effect.onInterrupt(() => removePending(String(requestId))),
        );
      });

    const notify = (method: string, payload?: JsonRpcRequestEnvelope["params"]) =>
      offerOutgoing({
        method,
        ...(payload !== undefined ? { params: payload } : {}),
      });

    return {
      incomingNotifications: incomingNotifications
        ? Stream.fromQueue(incomingNotifications)
        : Stream.empty,
      incomingRequests: incomingRequests ? Stream.fromQueue(incomingRequests) : Stream.empty,
      request,
      notify,
      respond,
      respondError,
    } satisfies CodexAppServerPatchedProtocol;
  },
);