@buyong/pi-devin 0.1.5 → 0.1.6

package/src/core/protocol/fingerprint.ts

@@ -1,6 +1,9 @@
 import { createCipheriv, createHash, randomBytes } from "node:crypto";
 import { performance } from "node:perf_hooks";
-import { collectDeviceIdentity, type DeviceIdentity } from "./device.ts";
+import { Effect } from "effect";
+import { toDevinError, type DevinError } from "../errors.ts";
+import { failWith } from "../validation.ts";
+import type { DeviceIdentity } from "./device.ts";
 
 // Matches the CLI's fingerprint construction; verified with fake-token requests only.
 // This is not encryption for credential storage. f contains the API token, so it is never logged.
@@ -8,8 +11,10 @@ const KEY_MATERIAL = "df97465349f38646af1d66c263e25e08";
 const KEY = createHash("sha256").update(KEY_MATERIAL, "utf8").digest();
 
 export interface FingerprintProvider {
-  create(): string;
-  device(): string;
+  /** A new ciphertext per request: the same device, a fresh timestamp and nonce. */
+  readonly create: Effect.Effect<string, DevinError>;
+  /** The device hash, collected once on first use. */
+  readonly device: Effect.Effect<string, DevinError>;
 }
 
 export function hashDeviceIdentity(identity: DeviceIdentity): string {
@@ -17,20 +22,20 @@ export function hashDeviceIdentity(identity: DeviceIdentity): string {
   return createHash("sha512").update(macs + identity.serial + identity.username, "utf8").digest("hex");
 }
 
-export function createFingerprintProvider(sessionToken: string, options: {
-  collectIdentity?: () => DeviceIdentity;
+export interface FingerprintOptions {
+  /** Device values for this provider. Collected on first use and kept; concurrent first requests share one collection. */
+  collectIdentity: Effect.Effect<DeviceIdentity, DevinError>;
   nowNanoseconds?: () => bigint;
   nonce?: () => Uint8Array;
-} = {}): FingerprintProvider {
-  let device: string | undefined;
-  const getDevice = () => device ??= hashDeviceIdentity((options.collectIdentity ?? collectDeviceIdentity)());
-  return {
-    device: getDevice,
-    create: () => encodeFingerprint({
-      deviceFingerprint: getDevice(), sessionToken,
-      timestampNanoseconds: options.nowNanoseconds?.(), nonce: options.nonce?.(),
-    }),
-  };
+}
+
+export function makeFingerprintProvider(sessionToken: string, options: FingerprintOptions): Effect.Effect<FingerprintProvider> {
+  return Effect.map(Effect.cached(Effect.map(options.collectIdentity, hashDeviceIdentity)), (device) => ({
+    device,
+    create: Effect.flatMap(device, (deviceFingerprint) => encodeFingerprint({
+      deviceFingerprint, sessionToken, timestampNanoseconds: options.nowNanoseconds?.(), nonce: options.nonce?.(),
+    })),
+  }));
 }
 
 export function unixNanoseconds(): bigint {
@@ -45,15 +50,22 @@ export function encodeFingerprint(options: {
   sessionToken: string;
   timestampNanoseconds?: bigint;
   nonce?: Uint8Array;
-}): string {
-  if (!/^[0-9a-f]{128}$/.test(options.deviceFingerprint)) throw new Error("The device identifier must be 128 lowercase hex characters.");
-  if (!options.sessionToken || /[|\s\u0000-\u001f\u007f]/.test(options.sessionToken)) throw new Error("Invalid session token format.");
-  const timestamp = options.timestampNanoseconds ?? unixNanoseconds();
-  if (timestamp < 0n || timestamp >= (1n << 128n)) throw new Error("Invalid fingerprint timestamp.");
-  const nonce = options.nonce ?? randomBytes(12);
-  if (nonce.length !== 12) throw new Error("The fingerprint nonce must be 12 bytes.");
-  const plaintext = `${options.deviceFingerprint}|${options.sessionToken}|${timestamp}`;
-  const cipher = createCipheriv("aes-256-gcm", KEY, nonce);
-  const ciphertext = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
-  return Buffer.concat([nonce, ciphertext, cipher.getAuthTag()]).toString("hex");
+}): Effect.Effect<string, DevinError> {
+  return Effect.suspend(() => {
+    if (!/^[0-9a-f]{128}$/.test(options.deviceFingerprint)) return failWith("The device identifier must be 128 lowercase hex characters.");
+    if (!options.sessionToken || /[|\s\u0000-\u001f\u007f]/.test(options.sessionToken)) return failWith("Invalid session token format.");
+    const timestamp = options.timestampNanoseconds ?? unixNanoseconds();
+    if (timestamp < 0n || timestamp >= (1n << 128n)) return failWith("Invalid fingerprint timestamp.");
+    const nonce = options.nonce ?? randomBytes(12);
+    if (nonce.length !== 12) return failWith("The fingerprint nonce must be 12 bytes.");
+    const plaintext = `${options.deviceFingerprint}|${options.sessionToken}|${timestamp}`;
+    return Effect.try({
+      try: () => {
+        const cipher = createCipheriv("aes-256-gcm", KEY, nonce);
+        const ciphertext = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+        return Buffer.concat([nonce, ciphertext, cipher.getAuthTag()]).toString("hex");
+      },
+      catch: toDevinError,
+    });
+  });
 }

package/src/core/protocol/frames.ts

@@ -0,0 +1,101 @@
+import { gunzipSync } from "node:zlib";
+import { Effect, Stream } from "effect";
+import { DevinError } from "../errors.ts";
+import type { JsonObject } from "../types.ts";
+import { failWith, object } from "../validation.ts";
+import { chatResponseCodec } from "./protobuf.ts";
+
+export const MAX_FRAME_BYTES = 8 * 1024 * 1024;
+export const MAX_RESPONSE_BYTES = 64 * 1024 * 1024;
+
+export interface Frame {
+  isEnd: boolean;
+  data: JsonObject;
+}
+
+export function encodeFrame(bytes: Uint8Array, flags = 0): Effect.Effect<Buffer, DevinError> {
+  return Effect.suspend(() => {
+    const payload = Buffer.from(bytes);
+    if (payload.length > MAX_FRAME_BYTES) return failWith("The request frame exceeds 8 MiB.");
+    const header = Buffer.alloc(5);
+    header[0] = flags;
+    header.writeUInt32BE(payload.length, 1);
+    return Effect.succeed(Buffer.concat([header, payload]));
+  });
+}
+
+/** The connection ended before the stream was complete, so a new request may succeed. */
+const prematureClose = (message: string) => new DevinError({ message, code: "ERR_STREAM_PREMATURE_CLOSE" });
+
+/** Parses one response's Connect envelopes. HTTP chunk boundaries and Connect frame boundaries are independent. */
+class FrameDecoder {
+  private buffered: Buffer = Buffer.alloc(0);
+  private hasEnded = false;
+  private wireBytes = 0;
+  private decodedBytes = 0;
+  private readonly decoder = new TextDecoder("utf-8", { fatal: true });
+  private readonly compression: "identity" | "gzip" | undefined;
+
+  constructor(compression: "identity" | "gzip" | undefined) {
+    this.compression = compression;
+  }
+
+  push(chunk: Uint8Array): Effect.Effect<Frame[], DevinError> {
+    const self = this;
+    return Effect.gen(function* () {
+      self.wireBytes += chunk.byteLength;
+      if (self.wireBytes > MAX_RESPONSE_BYTES) return yield* failWith("The response exceeds 64 MiB.");
+      if (self.hasEnded && chunk.byteLength > 0) return yield* failWith("Data follows EndStream.");
+      self.buffered = Buffer.concat([self.buffered, chunk]);
+      const frames: Frame[] = [];
+      while (self.buffered.length >= 5) {
+        if (self.hasEnded) return yield* failWith("A frame follows EndStream.");
+        const flags = self.buffered[0];
+        if ((flags & ~3) !== 0) return yield* failWith(`Unknown Connect flags: ${flags}`);
+        const payloadBytes = self.buffered.readUInt32BE(1);
+        if (payloadBytes > MAX_FRAME_BYTES) return yield* failWith("The response frame exceeds 8 MiB.");
+        if (self.buffered.length < 5 + payloadBytes) break;
+        let payload: Buffer = self.buffered.subarray(5, 5 + payloadBytes);
+        self.buffered = self.buffered.subarray(5 + payloadBytes);
+        if (flags & 1) {
+          if (self.compression !== "gzip") return yield* failWith("A compressed frame has no valid gzip encoding header.");
+          const compressed = payload;
+          payload = yield* Effect.try({
+            try: () => gunzipSync(compressed, { maxOutputLength: MAX_FRAME_BYTES }),
+            catch: () => new DevinError({ message: "The gzip frame is corrupt or exceeds the decompression limit." }),
+          });
+        }
+        self.decodedBytes += payload.byteLength;
+        if (self.decodedBytes > MAX_RESPONSE_BYTES) return yield* failWith("The decompressed response exceeds 64 MiB.");
+        self.hasEnded = Boolean(flags & 2);
+        const bytes = payload;
+        const data = self.hasEnded
+          ? yield* Effect.try({ try: () => JSON.parse(self.decoder.decode(bytes)) as unknown, catch: () => undefined }).pipe(
+            Effect.flatMap((value) => object(value, "EndStream")),
+            Effect.mapError(() => new DevinError({ message: "EndStream is not a valid UTF-8 JSON object." })),
+          )
+          : yield* chatResponseCodec.decode(bytes);
+        frames.push({ isEnd: self.hasEnded, data });
+      }
+      return frames;
+    });
+  }
+
+  get end(): Effect.Effect<void, DevinError> {
+    if (this.buffered.length !== 0) return Effect.fail(prematureClose("The connection ended with an incomplete Connect frame."));
+    if (!this.hasEnded) return Effect.fail(prematureClose("The connection ended without EndStream."));
+    return Effect.void;
+  }
+}
+
+/** Decodes Connect frames from a response body. A truncated stream fails as a premature close. */
+export function decodeFrames<E, R>(chunks: Stream.Stream<Uint8Array, E, R>, options: { compression?: "identity" | "gzip" } = {}): Stream.Stream<Frame, E | DevinError, R> {
+  return Stream.suspend(() => {
+    const decoder = new FrameDecoder(options.compression);
+    return chunks.pipe(
+      Stream.mapEffect((chunk) => decoder.push(chunk)),
+      Stream.flattenIterable,
+      Stream.concat(Stream.fromEffectDrain(Effect.suspend(() => decoder.end))),
+    );
+  });
+}

package/src/core/protocol/http/fetch-client.ts

@@ -0,0 +1,42 @@
+import { Effect } from "effect";
+import { HttpClient, type HttpClientError, type HttpClientRequest, type HttpClientResponse } from "effect/http";
+import { requestBody, transportError } from "./node-client.ts";
+import { DevinHttpResponse } from "./response.ts";
+
+const ignore = () => {};
+
+/**
+ * `HttpClient` over an injected `fetch`, such as the one Pi passes in stream options. Sends the transport's exact headers
+ * and body, never follows redirects, and discards a response that arrives after its request ended.
+ */
+export function makeFetchHttpClient(fetchImpl: typeof fetch): HttpClient.HttpClient {
+  const send = (request: HttpClientRequest.HttpClientRequest) => Effect.callback<HttpClientResponse.HttpClientResponse, HttpClientError.HttpClientError>((resume) => {
+    const controller = new AbortController();
+    let isSettled = false;
+    let pending: Promise<Response>;
+    try {
+      pending = Promise.resolve(fetchImpl(request.url, {
+        method: request.method, redirect: "error", headers: Object.fromEntries(Object.entries(request.headers)),
+        body: requestBody(request) as BodyInit | undefined, signal: controller.signal,
+      }));
+    } catch (error) {
+      resume(Effect.fail(transportError(request, error)));
+      return;
+    }
+    pending.then((response) => {
+      if (isSettled) { void response.body?.cancel().catch(ignore); return; }
+      isSettled = true;
+      resume(Effect.succeed(new DevinHttpResponse(request, response, () => controller.abort())));
+    }, (error: unknown) => {
+      if (isSettled) return;
+      isSettled = true;
+      resume(Effect.fail(transportError(request, error)));
+    });
+    return Effect.sync(() => {
+      if (isSettled) return;
+      isSettled = true;
+      controller.abort();
+    });
+  });
+  return HttpClient.makeWith<HttpClientError.HttpClientError, never, HttpClientError.HttpClientError, never>((request) => Effect.flatMap(request, send), Effect.succeed);
+}

package/src/core/protocol/http/node-client.ts

@@ -0,0 +1,130 @@
+import { Agent as HTTPAgent, request as httpRequest, type IncomingMessage } from "node:http";
+import { Agent as HTTPSAgent, request as httpsRequest } from "node:https";
+import { pipeline, Readable } from "node:stream";
+import type { ConnectionOptions } from "node:tls";
+import { createGunzip } from "node:zlib";
+import { Effect, type Scope } from "effect";
+import { HttpClient, HttpClientError, type HttpClientRequest, type HttpClientResponse } from "effect/http";
+import { DevinHttpResponse } from "./response.ts";
+
+export interface HTTPTransportOptions {
+  /** Trusts a user-supplied CA without disabling certificate or host verification. */
+  ca?: ConnectionOptions["ca"];
+}
+
+export function transportError(request: HttpClientRequest.HttpClientRequest, cause: unknown): HttpClientError.HttpClientError {
+  return new HttpClientError.HttpClientError({ reason: new HttpClientError.TransportError({ request, cause }) });
+}
+
+/** The request body as the transports send it: bytes or text, never a stream. */
+export function requestBody(request: HttpClientRequest.HttpClientRequest): Uint8Array | string | undefined {
+  const body = request.body;
+  if (body._tag === "Uint8Array") return body.body;
+  if (body._tag === "Raw" && (typeof body.body === "string" || body.body instanceof Uint8Array)) return body.body;
+  return undefined;
+}
+
+function nodeResponse(incoming: IncomingMessage): Response | Error {
+  const responseHeaders = new Headers();
+  for (const [name, value] of Object.entries(incoming.headers)) {
+    for (const entry of Array.isArray(value) ? value : value === undefined ? [] : [value]) responseHeaders.append(name, entry);
+  }
+  const status = incoming.statusCode ?? 502;
+  const hasNoBody = [204, 205, 304].includes(status);
+  const encoding = responseHeaders.get("content-encoding")?.trim().toLowerCase();
+  let stream: Readable = incoming;
+  if (hasNoBody) incoming.resume();
+  else if (encoding && encoding !== "identity") {
+    if (encoding !== "gzip") {
+      // An encoding problem in an error body must not hide an already received 401/403/429 status.
+      if (status >= 200 && status < 300) return new Error("Unsupported HTTP response compression.");
+    } else {
+      const decoded = createGunzip();
+      // Propagates consumer cancellation and compression errors to the original socket and keeps backpressure.
+      pipeline(incoming, decoded, () => {});
+      stream = decoded;
+      responseHeaders.delete("content-encoding");
+      responseHeaders.delete("content-length");
+    }
+  }
+  try {
+    return new Response(hasNoBody ? null : Readable.toWeb(stream) as ReadableStream<Uint8Array>, { status, headers: responseHeaders });
+  } catch (error) {
+    return error instanceof Error ? error : new Error(String(error));
+  }
+}
+
+/**
+ * HTTP/1.1-only `HttpClient` over `node:http`. Owns a pool for the scope's lifetime and verifies TLS certificates and hosts.
+ * The 5000ms socket timeout spells out the previous Node global agent setting as a PoC policy;
+ * it is not the overall RPC deadline. It does not claim to match the CLI's TLS or pool policy.
+ */
+export function makeNodeHttpClient(options: HTTPTransportOptions = {}): Effect.Effect<HttpClient.HttpClient, never, Scope.Scope> {
+  return Effect.gen(function* () {
+    const pool = yield* Effect.acquireRelease(Effect.sync(() => ({
+      isClosed: false,
+      http: new HTTPAgent({ keepAlive: true, timeout: 5000 }),
+      https: new HTTPSAgent({
+        keepAlive: true, timeout: 5000, rejectUnauthorized: true, minVersion: "TLSv1.2",
+        ALPNProtocols: ["http/1.1"], ...(options.ca === undefined ? {} : { ca: options.ca }),
+      }),
+    })), (pool) => Effect.sync(() => {
+      pool.isClosed = true;
+      pool.http.destroy();
+      pool.https.destroy();
+    }));
+
+    const send = (request: HttpClientRequest.HttpClientRequest): Effect.Effect<HttpClientResponse.HttpClientResponse, HttpClientError.HttpClientError> => Effect.suspend(() => {
+      if (pool.isClosed) return Effect.fail(transportError(request, new Error("The HTTP transport is closed.")));
+      if (request.method !== "POST" && request.method !== "GET") return Effect.fail(transportError(request, new Error("This transport supports only URL GET/POST without redirects.")));
+      let url: URL;
+      try { url = new URL(request.url); } catch (error) { return Effect.fail(transportError(request, error)); }
+      if (!["https:", "http:"].includes(url.protocol)) return Effect.fail(transportError(request, new Error("Unsupported HTTP protocol.")));
+      const raw = requestBody(request);
+      const body = raw === undefined ? undefined : Buffer.from(raw);
+      if (request.method === "POST" && !body) return Effect.fail(transportError(request, new Error("A POST body must be a string or a byte array.")));
+      if (request.method === "GET" && body) return Effect.fail(transportError(request, new Error("A GET body is not supported.")));
+      let headers: Record<string, string>;
+      try {
+        // Validates names and values the same way fetch does before anything is sent.
+        const validated = new Headers(Object.entries(request.headers));
+        headers = {};
+        for (const [name, value] of validated) if (name !== "host" && name !== "content-length") headers[name] = value;
+      } catch (error) { return Effect.fail(transportError(request, error)); }
+      headers.host = url.host;
+      if (body) headers["content-length"] = String(body.byteLength);
+      const isHTTPS = url.protocol === "https:";
+      return Effect.callback<HttpClientResponse.HttpClientResponse, HttpClientError.HttpClientError>((resume) => {
+        let isSettled = false;
+        const fail = (cause: unknown) => {
+          if (isSettled) return;
+          isSettled = true;
+          resume(Effect.fail(transportError(request, cause)));
+        };
+        const outgoing = (isHTTPS ? httpsRequest : httpRequest)(url, {
+          method: request.method, headers, agent: isHTTPS ? pool.https : pool.http,
+        }, (incoming) => {
+          if (isSettled) { incoming.destroy(); return; }
+          const response = nodeResponse(incoming);
+          if (response instanceof Error) { incoming.destroy(); fail(response); return; }
+          isSettled = true;
+          resume(Effect.succeed(new DevinHttpResponse(request, response, () => { incoming.destroy(); outgoing.destroy(); })));
+        });
+        outgoing.on("error", fail);
+        outgoing.once("upgrade", (_response, socket) => {
+          socket.destroy();
+          fail(new Error("HTTP upgrade is not supported."));
+        });
+        outgoing.removeHeader("connection");
+        outgoing.end(body);
+        return Effect.sync(() => {
+          if (isSettled) return;
+          isSettled = true;
+          outgoing.destroy();
+        });
+      });
+    });
+
+    return HttpClient.makeWith<HttpClientError.HttpClientError, never, HttpClientError.HttpClientError, never>((request) => Effect.flatMap(request, send), Effect.succeed);
+  });
+}

package/src/core/protocol/http/response.ts

@@ -0,0 +1,99 @@
+import { Effect, Inspectable, Option, Stream } from "effect";
+import { pipeArguments } from "effect/Pipeable";
+import { HttpClientError, HttpClientResponse, HttpIncomingMessage, type HttpClientRequest } from "effect/http";
+
+const ignore = () => {};
+
+/**
+ * A web `Response` seen through Effect's `HttpClientResponse`. Unlike `HttpClientResponse.fromWeb`, ending its body early
+ * never waits for an uncooperative `cancel()`, and the transport is stopped only while the body is still in flight,
+ * so a fully read keep-alive connection stays reusable.
+ */
+export class DevinHttpResponse extends Inspectable.Class implements HttpClientResponse.HttpClientResponse {
+  readonly [HttpClientResponse.TypeId] = HttpClientResponse.TypeId;
+  readonly [HttpIncomingMessage.TypeId] = HttpIncomingMessage.TypeId;
+  readonly request: HttpClientRequest.HttpClientRequest;
+  readonly source: Response;
+  private readonly web: HttpClientResponse.HttpClientResponse;
+  private readonly abortTransport: () => void;
+  private isBodySettled = false;
+
+  constructor(request: HttpClientRequest.HttpClientRequest, source: Response, abortTransport: () => void) {
+    super();
+    this.request = request;
+    this.source = source;
+    this.abortTransport = abortTransport;
+    this.web = HttpClientResponse.fromWeb(request, source);
+  }
+
+  get url() { return this.web.url; }
+  get status() { return this.source.status; }
+  get headers() { return this.web.headers; }
+  get cookies() { return this.web.cookies; }
+  get remoteAddress() { return Option.none<string>(); }
+  get formData() { return this.web.formData; }
+  get json() { return this.web.json; }
+  get text() { return this.web.text; }
+  get urlParamsBody() { return this.web.urlParamsBody; }
+  get arrayBuffer() { return this.web.arrayBuffer; }
+
+  /** Stops an unread or partly read body. Responses that arrive after their request ended are discarded the same way. */
+  get discard(): Effect.Effect<void> {
+    return Effect.sync(() => this.abandon(undefined));
+  }
+
+  private abandon(reader: ReadableStreamDefaultReader<Uint8Array> | undefined): void {
+    if (this.isBodySettled) return;
+    this.isBodySettled = true;
+    try {
+      if (reader) { void reader.cancel().catch(ignore); reader.releaseLock(); }
+      else if (this.source.body && !this.source.body.locked) void this.source.body.cancel().catch(ignore);
+    } finally { this.abortTransport(); }
+  }
+
+  get stream(): Stream.Stream<Uint8Array, HttpClientError.HttpClientError> {
+    return Stream.suspend(() => {
+      const body = this.source.body;
+      if (!body || this.isBodySettled) {
+        return Stream.fail(new HttpClientError.HttpClientError({
+          reason: new HttpClientError.EmptyBodyError({ request: this.request, response: this, description: "The response has no body." }),
+        }));
+      }
+      const reader = body.getReader();
+      const iterator: AsyncIterator<Uint8Array> = {
+        next: async () => {
+          try {
+            const item = await reader.read();
+            if (item.done && !this.isBodySettled) { this.isBodySettled = true; reader.releaseLock(); }
+            return item.done ? { done: true, value: undefined } : item;
+          } catch (error) {
+            this.abandon(reader);
+            throw error;
+          }
+        },
+        // Called when the consumer stops early. Cancellation is started but never awaited.
+        return: async () => {
+          this.abandon(reader);
+          return { done: true, value: undefined };
+        },
+      };
+      return Stream.fromAsyncIterable({ [Symbol.asyncIterator]: () => iterator }, (cause) => new HttpClientError.HttpClientError({
+        reason: new HttpClientError.DecodeError({ request: this.request, response: this, cause }),
+      }));
+    });
+  }
+
+  toJSON(): unknown {
+    return HttpIncomingMessage.inspect(this, { _id: "HttpClientResponse", request: this.request.toJSON(), status: this.status });
+  }
+
+  pipe() {
+    // biome-ignore lint/complexity/noArguments: Pipeable forwards the call's arguments.
+    return pipeArguments(this, arguments);
+  }
+}
+
+/** Discards the body of a response this package's transports produced. */
+export function discardResponse(response: HttpClientResponse.HttpClientResponse): Effect.Effect<void> {
+  return response instanceof DevinHttpResponse ? response.discard : Effect.void;
+}

package/src/core/protocol/http.ts

@@ -1,109 +1,49 @@
-import { Agent as HTTPAgent, request as httpRequest } from "node:http";
-import { Agent as HTTPSAgent, request as httpsRequest } from "node:https";
-import { Readable, pipeline } from "node:stream";
-import type { ConnectionOptions } from "node:tls";
-import { createGunzip } from "node:zlib";
+import { Effect, Stream } from "effect";
+import type { HttpClientError, HttpClientResponse } from "effect/http";
+import { DevinError, toDevinFailure, type DevinFailure } from "../errors.ts";
+import { failWith } from "../validation.ts";
 
-export interface HTTPTransportOptions {
-  /** Trusts a user-supplied CA without disabling certificate or host verification. */
-  ca?: ConnectionOptions["ca"];
+export { discardResponse } from "./http/response.ts";
+export { makeFetchHttpClient } from "./http/fetch-client.ts";
+export { makeNodeHttpClient, type HTTPTransportOptions } from "./http/node-client.ts";
+
+/** Keeps the transport cause (message and Node error code) so callers can tell network failures apart. */
+export function fromHttpClientError(error: HttpClientError.HttpClientError): DevinFailure {
+  const reason = error.reason;
+  switch (reason._tag) {
+    case "TransportError":
+    case "DecodeError":
+    case "EncodeError":
+    case "InvalidUrlError": return toDevinFailure(reason.cause ?? reason.description ?? error.message);
+    case "EmptyBodyError": return new DevinError({ message: reason.description ?? "The response has no body." });
+    case "StatusCodeError": return new DevinError({ message: reason.description ?? error.message });
+  }
 }
 
-export interface HTTPTransport {
-  fetch: typeof fetch;
-  close(): void;
+/** The response body as chunks, failing as Devin failures. */
+export function responseChunks(response: HttpClientResponse.HttpClientResponse): Stream.Stream<Uint8Array, DevinFailure> {
+  return Stream.mapError(response.stream, fromHttpClientError);
 }
 
-/**
- * HTTP/1.1-only transport. Owns a per-client pool and verifies TLS certificates and hosts.
- * The 5000ms socket timeout spells out the previous Node global agent setting as a PoC policy;
- * it is not the overall RPC deadline. It does not claim to match the CLI's TLS or pool policy.
- */
-export function createHTTPTransport(options: HTTPTransportOptions = {}): HTTPTransport {
-  const httpAgent = new HTTPAgent({ keepAlive: true, timeout: 5000 });
-  const httpsAgent = new HTTPSAgent({
-    keepAlive: true, timeout: 5000, rejectUnauthorized: true, minVersion: "TLSv1.2",
-    ALPNProtocols: ["http/1.1"], ...(options.ca === undefined ? {} : { ca: options.ca }),
+export function readBoundedBytes(response: HttpClientResponse.HttpClientResponse, maxBytes: number): Effect.Effect<Buffer, DevinFailure> {
+  return Effect.suspend(() => {
+    let bytes = 0;
+    const chunks: Uint8Array[] = [];
+    return responseChunks(response).pipe(
+      Stream.runForEach((chunk) => {
+        bytes += chunk.byteLength;
+        if (bytes > maxBytes) return failWith("The response size limit was exceeded.");
+        chunks.push(chunk);
+        return Effect.void;
+      }),
+      Effect.map(() => Buffer.concat(chunks)),
+    );
   });
-  let isClosed = false;
-  const fetchHTTP: typeof fetch = async (input, init) => {
-    if (isClosed) throw new Error("The HTTP transport is closed.");
-    if (!(typeof input === "string" || input instanceof URL) || !["POST", "GET"].includes(init?.method ?? "") || init?.redirect !== "error") {
-      throw new Error("This transport supports only URL GET/POST without redirects.");
-    }
-    const url = new URL(input);
-    if (!["https:", "http:"].includes(url.protocol)) throw new Error("Unsupported HTTP protocol.");
-    const body = typeof init.body === "string" ? Buffer.from(init.body)
-      : init.body instanceof Uint8Array ? Buffer.from(init.body) : undefined;
-    if (init.method === "POST" && !body) throw new Error("A POST body must be a string or a byte array.");
-    if (init.method === "GET" && init.body != null) throw new Error("A GET body is not supported.");
-    const validated = new Headers(init.headers);
-    const entries = init.headers instanceof Headers ? [...init.headers.entries()]
-      : Array.isArray(init.headers) ? init.headers : Object.entries(init.headers ?? {});
-    const headers: Record<string, string> = {};
-    for (const [name] of entries) {
-      const key = name.toLowerCase();
-      if (key !== "host" && key !== "content-length") headers[key] = validated.get(name)!;
-    }
-    headers.host = url.host;
-    if (body) headers["content-length"] = String(body.byteLength);
-    return new Promise<Response>((resolve, reject) => {
-      const isHTTPS = url.protocol === "https:";
-      const send = isHTTPS ? httpsRequest : httpRequest;
-      const request = send(url, {
-        method: init.method, headers, signal: init.signal ?? undefined,
-        agent: isHTTPS ? httpsAgent : httpAgent,
-      }, (incoming) => {
-        try {
-          const responseHeaders = new Headers();
-          for (const [name, value] of Object.entries(incoming.headers)) {
-            for (const entry of Array.isArray(value) ? value : value === undefined ? [] : [value]) responseHeaders.append(name, entry);
-          }
-          const status = incoming.statusCode ?? 502;
-          const hasNoBody = [204, 205, 304].includes(status);
-          const encoding = responseHeaders.get("content-encoding")?.trim().toLowerCase();
-          let stream: Readable = incoming;
-          if (hasNoBody) incoming.resume();
-          else if (encoding && encoding !== "identity") {
-            if (encoding !== "gzip") {
-              // An encoding problem in an error body must not hide an already received 401/403/429 status.
-              if (status >= 200 && status < 300) throw new Error("Unsupported HTTP response compression.");
-            } else {
-              const decoded = createGunzip();
-              // Propagates consumer cancellation and compression errors to the original socket and keeps backpressure.
-              pipeline(incoming, decoded, () => {});
-              stream = decoded;
-              responseHeaders.delete("content-encoding");
-              responseHeaders.delete("content-length");
-            }
-          }
-          resolve(new Response(hasNoBody ? null : Readable.toWeb(stream) as ReadableStream<Uint8Array>, {
-            status, headers: responseHeaders,
-          }));
-        } catch (error) {
-          incoming.destroy();
-          reject(error);
-        }
-      });
-      request.once("error", reject);
-      request.once("upgrade", (_response, socket) => {
-        socket.destroy();
-        reject(new Error("HTTP upgrade is not supported."));
-      });
-      request.removeHeader("connection");
-      request.end(body);
-    });
-  };
-  return {
-    fetch: fetchHTTP,
-    close() {
-      if (isClosed) return;
-      isClosed = true;
-      httpAgent.destroy();
-      httpsAgent.destroy();
-    },
-  };
 }
 
-/** Default transport for existing direct callers. ConnectClient owns its own pool. */
-export const requestHTTP: typeof fetch = createHTTPTransport().fetch;
+export function readBoundedJSON(response: HttpClientResponse.HttpClientResponse, maxBytes: number): Effect.Effect<unknown, DevinFailure> {
+  return Effect.flatMap(readBoundedBytes(response, maxBytes), (bytes) => Effect.try({
+    try: () => JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)) as unknown,
+    catch: () => new DevinError({ message: "The server did not return valid JSON." }),
+  }));
+}