@buyong/pi-devin 0.1.4 → 0.1.6

package/src/core/protocol/connect-client.ts

@@ -0,0 +1,288 @@
+import { randomBytes } from "node:crypto";
+import { gzipSync } from "node:zlib";
+import { Effect, Exit, Fiber, Predicate, Scope, Stream } from "effect";
+import { HttpBody, HttpClientRequest, type HttpClient, type HttpClientResponse } from "effect/http";
+import { guardAll, makeCancellation, startDeadline, startIdleDeadline, type Cancellation } from "../cancellation.ts";
+import { Cancelled, isAuthenticationError, RPCError, toDevinError, type DevinError, type DevinFailure } from "../errors.ts";
+import { redactFailure, requestSecrets, safeError } from "../redaction.ts";
+import type { JsonObject } from "../types.ts";
+import { failWith, object } from "../validation.ts";
+import { endpoint } from "./endpoint.ts";
+import { decodeFrames, encodeFrame, MAX_FRAME_BYTES, type Frame } from "./frames.ts";
+import { HttpTransport } from "../services/http-transport.ts";
+import { discardResponse, fromHttpClientError, readBoundedBytes, readBoundedJSON, responseChunks } from "./http.ts";
+import { CHAT_METHOD, chatRequestCodec, unaryCodecs } from "./protobuf.ts";
+
+// The CLI compresses frames only when they are at least 8192 bytes.
+export const DEFAULT_COMPRESSION_THRESHOLD_BYTES = 8 * 1024;
+export const ASSIGN_MODEL_METHOD = "exa.api_server_pb.ApiServerService/AssignModel";
+const DEFAULT_TIMEOUT_MS = 90_000;
+const UNARY_RESPONSE_BYTES = 4 * 1024 * 1024;
+const ERROR_BODY_BYTES = 64 * 1024;
+/** Only an initial compressed request rejected with these statuses is resent once uncompressed. */
+const COMPRESSION_FALLBACK_STATUSES = new Set([408, 415, 500, 502, 503, 504]);
+type Encoding = "proto" | "json" | "stream";
+
+export interface RequestAttempt {
+  method: "POST" | "GET";
+  path: string;
+  attempt: number;
+  isMetered: boolean;
+  isCompressed: boolean;
+  stage?: string;
+  modelUid?: string;
+}
+
+export interface StreamRequestContext {
+  stage?: string;
+  /** Runs once, right after the first attempt was handed to the transport. */
+  onDispatched?: Effect.Effect<void, DevinFailure>;
+  headers?: Record<string, string | null>;
+  onPayload?: (payload: JsonObject) => Effect.Effect<JsonObject | undefined, DevinFailure>;
+  onResponse?: (response: { status: number; headers: Record<string, string> }) => Effect.Effect<void, DevinFailure>;
+  /** Observes each parsed frame before normalization and error classification. */
+  onFrame?: (frame: Frame) => Effect.Effect<void, DevinFailure>;
+}
+
+export interface ConnectClientOptions {
+  baseURL: string;
+  token?: string;
+  /** A unary call must finish within it; a stream fails after this long without data. Defaults to 90000ms. */
+  timeoutMs?: number;
+  compressionThresholdBytes?: number;
+  trace?: () => string;
+  /** Sees every attempt before it is sent and can refuse it, for example when a request budget is used up. */
+  onRequest?: (attempt: RequestAttempt) => Effect.Effect<void, DevinFailure>;
+}
+
+export interface ConnectClient {
+  readonly baseURL: string;
+  readonly token: string | undefined;
+  readonly timeoutMs: number;
+  readonly compressionThresholdBytes: number;
+  readonly isAuthenticationInvalid: Effect.Effect<boolean>;
+  readonly assertAuthenticated: Effect.Effect<void, DevinFailure>;
+  /** Ends with the client: closing it or a confirmed 401 also stops waits between requests. */
+  readonly lifetime: Cancellation;
+  readonly close: Effect.Effect<void>;
+  unary(method: string, body: JsonObject, options?: { encoding?: "proto" | "json" }): Effect.Effect<JsonObject, DevinFailure>;
+  stream(method: string, body: JsonObject, context?: StreamRequestContext): Stream.Stream<Frame, DevinFailure>;
+  getJSON(origin: string, path: string): Effect.Effect<JsonObject, DevinFailure>;
+}
+
+function retryAfterMs(headers: Headers | Record<string, string | undefined>): number | undefined {
+  const value = (headers instanceof Headers ? headers.get("retry-after") : headers["retry-after"])?.trim();
+  if (!value) return undefined;
+  const milliseconds = /^\d+$/.test(value) ? Number(value) * 1000
+    : /^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), /.test(value) ? Date.parse(value) - Date.now() : NaN;
+  if (!Number.isFinite(milliseconds) || !Number.isSafeInteger(milliseconds)) return undefined;
+  return Math.max(0, milliseconds);
+}
+
+function requestHeaders(defaults: Record<string, string>, overrides: StreamRequestContext["headers"]): Effect.Effect<Record<string, string>, DevinError> {
+  return Effect.gen(function* () {
+    const headers = yield* Effect.try({ try: () => new Headers(defaults), catch: toDevinError });
+    for (const [name, value] of Object.entries(overrides ?? {})) {
+      if (["host", "content-length"].includes(name.toLowerCase()) && value !== headers.get(name)) {
+        return yield* failWith("Host and Content-Length are managed by the transport from the actual destination and body.");
+      }
+      yield* Effect.try({ try: () => { if (value === null) headers.delete(name); else headers.set(name, value); }, catch: toDevinError });
+    }
+    return Object.fromEntries(headers.entries());
+  });
+}
+
+const defaultTrace = () => `${randomBytes(16).toString("hex")}-${randomBytes(8).toString("hex")}-0`;
+
+/**
+ * A Connect client bound to one endpoint and token, sending through its own connection from `HttpTransport`.
+ * It closes with the scope, or earlier through `close`.
+ */
+export function makeConnectClient(options: ConnectClientOptions): Effect.Effect<ConnectClient, DevinError, HttpTransport | Scope.Scope> {
+  return Effect.gen(function* () {
+    const baseURL = yield* endpoint(options.baseURL);
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 2_147_483_647) {
+      return yield* failWith("The request timeout must be an integer from 1 to 2147483647ms.");
+    }
+    const compressionThresholdBytes = options.compressionThresholdBytes ?? DEFAULT_COMPRESSION_THRESHOLD_BYTES;
+    if (!Number.isSafeInteger(compressionThresholdBytes) || compressionThresholdBytes < 1) {
+      return yield* failWith("The compression threshold must be a positive integer number of bytes.");
+    }
+    const token = options.token;
+    const trace = options.trace ?? defaultTrace;
+    const transport = yield* HttpTransport;
+    const poolScope = yield* Scope.make();
+    const http: HttpClient.HttpClient = yield* transport.open.pipe(Scope.provide(poolScope));
+    const lifetime = makeCancellation();
+    let authenticationError: RPCError | undefined;
+    let isClosed = false;
+
+    const close = Effect.suspend(() => {
+      if (isClosed) return Effect.void;
+      isClosed = true;
+      lifetime.cancelUnsafe(new Cancelled({ message: "The client is closed." }));
+      return Scope.close(poolScope, Exit.void);
+    });
+    yield* Effect.addFinalizer(() => close);
+
+    const assertAuthenticated: Effect.Effect<void, DevinFailure> = Effect.suspend((): Effect.Effect<void, DevinFailure> => authenticationError ? Effect.fail(authenticationError)
+      : isClosed ? failWith("The client is closed.") : Effect.void);
+
+    /** Only a confirmed 401 of this client invalidates it. Other in-flight requests stop too; the stored token is kept and nothing logs in again. */
+    const failure = (secrets: () => readonly string[]) => (error: DevinFailure): Effect.Effect<never, DevinFailure> => Effect.suspend(() => {
+      if (isAuthenticationError(error) && token && !authenticationError) {
+        authenticationError = error;
+        lifetime.cancelUnsafe(error);
+      }
+      return Effect.fail(redactFailure(error, secrets()));
+    });
+
+    /** Runs one RPC under its deadline and the client's lifetime. The deadline starts before any hook or byte is sent. */
+    const withRequestScope = <A>(secrets: () => readonly string[], effect: Effect.Effect<A, DevinFailure, Scope.Scope>) => Effect.scoped(Effect.gen(function* () {
+      yield* assertAuthenticated;
+      const deadline = yield* startDeadline(timeoutMs);
+      return yield* guardAll([deadline, lifetime])(effect);
+    })).pipe(Effect.catch(failure(secrets)));
+
+    const post = (method: string, body: JsonObject, encoding: Encoding, context: StreamRequestContext = {}): Effect.Effect<HttpClientResponse.HttpClientResponse, DevinFailure, Scope.Scope> => Effect.gen(function* () {
+      yield* assertAuthenticated;
+      const isStreaming = encoding === "stream";
+      if (isStreaming && method !== CHAT_METHOD) return yield* failWith("Unsupported streaming RPC.");
+      const bytes = isStreaming ? yield* chatRequestCodec.encode(body)
+        : encoding === "proto" ? yield* Effect.flatMap(unaryCodecs(method), (codecs) => codecs.request.encode(body)) : Buffer.from(JSON.stringify(body));
+      if (bytes.length > MAX_FRAME_BYTES) return yield* failWith("The request body exceeds 8 MiB.");
+      const isMetered = method === CHAT_METHOD || method === ASSIGN_MODEL_METHOD;
+      const sentryTrace = method === CHAT_METHOD ? trace() : undefined;
+      let isCompressed = isStreaming && bytes.length >= compressionThresholdBytes;
+      const contentType = isStreaming ? "application/connect+proto" : encoding === "proto" ? "application/proto" : "application/json";
+      const modelUid = Predicate.isString(body.chatModelUid) ? body.chatModelUid : Predicate.isString(body.modelRouterUid) ? body.modelRouterUid : undefined;
+      for (let attempt = 1; ; attempt++) {
+        yield* assertAuthenticated;
+        const compressed = isCompressed;
+        const payload = isStreaming
+          ? yield* encodeFrame(compressed ? yield* Effect.try({ try: () => gzipSync(bytes), catch: toDevinError }) : bytes, compressed ? 1 : 0)
+          : Buffer.from(bytes);
+        const headers = yield* requestHeaders({
+          ...(token ? { authorization: `Basic ${token}-${token}` } : {}),
+          ...(sentryTrace ? { "sentry-trace": sentryTrace } : {}),
+          ...(compressed ? { "connect-content-encoding": "gzip" } : {}),
+          "content-type": contentType,
+          "connect-protocol-version": "1",
+          accept: "*/*",
+          "accept-encoding": "gzip",
+          "content-length": String(payload.byteLength),
+        }, context.headers);
+        if (options.onRequest) yield* options.onRequest({ method: "POST", path: method, attempt, isMetered, isCompressed: compressed, stage: context.stage, modelUid });
+        const request = HttpClientRequest.post(`${baseURL}/${method}`).pipe(
+          HttpClientRequest.setBody(HttpBody.raw(encoding === "json" ? payload.toString("utf8") : new Uint8Array(payload))),
+          HttpClientRequest.setHeaders(headers),
+        );
+        // The request leaves before onDispatched runs. If it is never joined, closing the scope stops it and discards a late response.
+        const dispatched = yield* Effect.forkScoped(http.execute(request), { startImmediately: true });
+        if (attempt === 1 && context.onDispatched) yield* context.onDispatched;
+        const response = yield* Fiber.join(dispatched).pipe(Effect.mapError(fromHttpClientError));
+        // An unread body is released on every path except a successful hand-off to the caller.
+        yield* Effect.addFinalizer((exit) => Exit.isSuccess(exit) ? Effect.void : discardResponse(response));
+        if (context.onResponse) yield* context.onResponse({ status: response.status, headers: { ...response.headers } });
+        // Compression fallback the CLI uses. Keeps the same deadline, body, fingerprint, trace and per-attempt budget.
+        // 401/403/429 and one-time login exchanges are never resent through this path.
+        if (attempt === 1 && compressed && COMPRESSION_FALLBACK_STATUSES.has(response.status)) {
+          yield* discardResponse(response);
+          isCompressed = false;
+          continue;
+        }
+        if (response.status === 401) {
+          yield* discardResponse(response);
+          return yield* Effect.fail(RPCError.make("unauthenticated", "HTTP 401: the server rejected the authentication credential.", 401));
+        }
+        if (response.status < 200 || response.status >= 300) {
+          const secrets = requestSecrets(body, token);
+          const details = yield* readBoundedJSON(response, ERROR_BODY_BYTES).pipe(Effect.flatMap((value) => object(value, "RPC error")), Effect.orElseSucceed((): JsonObject => ({})));
+          return yield* Effect.fail(RPCError.make(Predicate.isString(details.code) ? safeError(details.code, secrets) : `http_${response.status}`,
+            safeError(Predicate.isString(details.message) ? details.message : `HTTP ${response.status}`, secrets),
+            response.status, response.status === 429 ? retryAfterMs(response.headers) : undefined));
+        }
+        if (response.headers["content-type"]?.split(";")[0].trim().toLowerCase() !== contentType) {
+          yield* discardResponse(response);
+          return yield* failWith(`Unexpected Content-Type (expected: ${contentType})`);
+        }
+        return response;
+      }
+    });
+
+    const unary: ConnectClient["unary"] = (method, body, unaryOptions = {}) => {
+      const encoding = unaryOptions.encoding ?? "proto";
+      return withRequestScope(() => requestSecrets(body, token), Effect.gen(function* () {
+        const response = yield* post(method, body, encoding);
+        return encoding === "json" ? yield* object(yield* readBoundedJSON(response, UNARY_RESPONSE_BYTES), "RPC response")
+          : yield* Effect.flatMap(unaryCodecs(method), (codecs) => Effect.flatMap(readBoundedBytes(response, UNARY_RESPONSE_BYTES), codecs.response.decode));
+      }));
+    };
+
+    const stream: ConnectClient["stream"] = (method, body, context = {}) => {
+      const secrets = requestSecrets(body, token);
+      // A custom header name alone cannot tell whether its value is secret.
+      for (const value of Object.values(context.headers ?? {})) if (value) secrets.push(value);
+      const frames = Stream.unwrap(Effect.gen(function* () {
+        yield* assertAuthenticated;
+        // A stream may answer for a long time; it ends only after `timeoutMs` without data, like Pi's idle HTTP timeout.
+        const deadline = yield* startIdleDeadline(timeoutMs);
+        const guard = guardAll([deadline, lifetime]);
+        const opened = guard(Effect.gen(function* () {
+          let payload = body;
+          if (context.onPayload) {
+            const replacement = yield* context.onPayload(body);
+            if (replacement !== undefined) payload = yield* object(replacement, "request payload");
+          }
+          secrets.push(...requestSecrets(payload, token));
+          const response = yield* post(method, payload, "stream", context);
+          const compression = response.headers["connect-content-encoding"] ?? "identity";
+          if (compression !== "identity" && compression !== "gzip") {
+            yield* discardResponse(response);
+            return yield* failWith("Unsupported Connect response compression.");
+          }
+          return decodeFrames(responseChunks(response).pipe(Stream.tap(() => deadline.touch)), { compression }).pipe(Stream.mapEffect((frame) => Effect.gen(function* () {
+            if (context.onFrame) yield* context.onFrame(frame);
+            if (frame.isEnd && frame.data.error) {
+              const error = yield* object(frame.data.error, "EndStream error");
+              return yield* Effect.fail(RPCError.make(Predicate.isString(error.code) ? safeError(error.code, secrets) : "unknown",
+                safeError(Predicate.isString(error.message) ? error.message : "Connect stream failed", secrets)));
+            }
+            return frame;
+          })));
+        }));
+        return Stream.unwrap(opened).pipe(Stream.interruptWhen(deadline.await), Stream.interruptWhen(lifetime.await));
+      }));
+      return frames.pipe(Stream.catch((error) => Stream.fromEffect(failure(() => secrets)(error))));
+    };
+
+    const getJSON: ConnectClient["getJSON"] = (origin, path) => Effect.gen(function* () {
+      const base = yield* endpoint(origin);
+      if (!path.startsWith("/v3/") || path.includes("..") || path.includes("?") || path.includes("#")) {
+        return yield* failWith("Unsupported Devin REST path.");
+      }
+      return yield* withRequestScope(() => token ? [token] : [], Effect.gen(function* () {
+        if (options.onRequest) yield* options.onRequest({ method: "GET", path, attempt: 1, isMetered: false, isCompressed: false });
+        const request = HttpClientRequest.get(`${base}${path}`).pipe(HttpClientRequest.setHeaders({
+          ...(token ? { authorization: `Bearer ${token}` } : {}), accept: "*/*",
+          ...(path === "/v3/self" ? {} : { "accept-encoding": "gzip" }),
+        }));
+        const response = yield* http.execute(request).pipe(Effect.mapError(fromHttpClientError));
+        yield* Effect.addFinalizer((exit) => Exit.isSuccess(exit) ? Effect.void : discardResponse(response));
+        if (response.status < 200 || response.status >= 300) {
+          yield* discardResponse(response);
+          return yield* Effect.fail(RPCError.make(response.status === 401 ? "unauthenticated" : `http_${response.status}`,
+            `Devin REST HTTP ${response.status}`, response.status, response.status === 429 ? retryAfterMs(response.headers) : undefined));
+        }
+        return yield* object(yield* readBoundedJSON(response, UNARY_RESPONSE_BYTES), "Devin REST response");
+      }));
+    });
+
+    return {
+      baseURL, token, timeoutMs, compressionThresholdBytes, lifetime, close, assertAuthenticated,
+      isAuthenticationInvalid: Effect.sync(() => authenticationError !== undefined),
+      unary, stream, getJSON,
+    };
+  });
+}

package/src/core/protocol/device.ts

@@ -1,5 +1,8 @@
-import { execFileSync } from "node:child_process";
 import { networkInterfaces, userInfo, type NetworkInterfaceInfo } from "node:os";
+import { Effect } from "effect";
+import { ChildProcessSpawner } from "effect/process";
+import { toDevinError, type DevinError } from "../errors.ts";
+import { commandOutput } from "../services/platform.ts";
 
 export interface DeviceIdentity {
   serial: string;
@@ -10,25 +13,22 @@ export interface DeviceIdentity {
 /** OS inputs read by device collection. Tests control only this boundary; collection rules and the fingerprint computation run unchanged. */
 export interface DeviceSystem {
   platform: NodeJS.Platform;
-  run(file: string, args: string[]): string;
-  networkInterfaces(): NodeJS.Dict<NetworkInterfaceInfo[]>;
-  username(): string;
+  run(file: string, args: readonly string[]): Effect.Effect<string, DevinError>;
+  networkInterfaces(): Effect.Effect<NodeJS.Dict<NetworkInterfaceInfo[]>, DevinError>;
+  username(): Effect.Effect<string, DevinError>;
 }
 
 // The MAC collection shell input is a fixed string and never includes user input.
 const MAC_COMMAND = `ifconfig 2>/dev/null | awk '/^[a-z]/{iface=$1} /inet6? /{has_ip[iface]=1} /ether /{mac[iface]=$2} END{for(i in has_ip) if(mac[i] && mac[i]!="00:00:00:00:00:00") print mac[i]}' | tr '[:upper:]' '[:lower:]' | sort -u`;
-const COMMAND_OPTIONS = {
-  encoding: "utf8" as const, timeout: 3000, maxBuffer: 1024 * 1024,
-  env: { PATH: "/usr/bin:/bin:/usr/sbin:/sbin", LC_ALL: "C" },
-  stdio: ["ignore", "pipe", "ignore"] as ["ignore", "pipe", "ignore"],
-};
+const COMMAND_OPTIONS = { env: { PATH: "/usr/bin:/bin:/usr/sbin:/sbin", LC_ALL: "C" }, timeoutMs: 3000, maxOutputBytes: 1024 * 1024 };
 
-function nodeDeviceSystem(): DeviceSystem {
+/** This machine's OS inputs. Commands run through the given process spawner. */
+export function nodeDeviceSystem(spawner: ChildProcessSpawner.ChildProcessSpawner["Service"]): DeviceSystem {
   return {
     platform: process.platform,
-    run: (file, args) => execFileSync(file, args, COMMAND_OPTIONS),
-    networkInterfaces,
-    username: () => userInfo().username,
+    run: (file, args) => commandOutput(file, args, COMMAND_OPTIONS).pipe(Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner)),
+    networkInterfaces: () => Effect.try({ try: () => networkInterfaces(), catch: toDevinError }),
+    username: () => Effect.try({ try: () => userInfo().username, catch: toDevinError }),
   };
 }
 
@@ -48,26 +48,25 @@ function interfaceMACs(interfaces: NodeJS.Dict<NetworkInterfaceInfo[]>): string[
  * Device values are used only for the fingerprint. Credentials and settings of an installed CLI are never read.
  * macOS reads ioreg/ifconfig. Serial collection on other OSes is unverified, so the
  * serial is left empty instead of being invented; MACs come from the common Node API under the same conditions.
+ * Every failed read becomes the documented empty value; the output may be sensitive, so it never reaches an error.
  */
-export function collectDeviceIdentity(system: DeviceSystem = nodeDeviceSystem()): DeviceIdentity {
-  const isDarwin = system.platform === "darwin";
-  let serial = "";
-  if (isDarwin) {
-    try {
-      const result = system.run("/usr/sbin/ioreg", ["-rd1", "-c", "IOPlatformExpertDevice"]);
-      const match = result.match(/"IOPlatformSerialNumber"\s*=\s*("(?:\\.|[^"\\])*")/);
-      if (match) serial = JSON.parse(match[1]) as string;
-    } catch { /* A failed serial read becomes an empty value. The output may be sensitive, so it is not included in errors. */ }
-  }
-  let macs: string[] = [];
-  if (Buffer.byteLength(serial) < 4) {
-    try {
-      macs = isDarwin
-        ? system.run("/bin/sh", ["-c", MAC_COMMAND]).split(/\r?\n/).filter(Boolean)
-        : interfaceMACs(system.networkInterfaces());
-    } catch { /* A failed MAC collection yields an empty list. */ }
-  }
-  let username = "unknown";
-  try { username = system.username(); } catch { /* value used when the system call fails */ }
-  return { serial, macs, username };
+export function collectDeviceIdentity(system: DeviceSystem): Effect.Effect<DeviceIdentity> {
+  return Effect.gen(function* () {
+    const isDarwin = system.platform === "darwin";
+    let serial = "";
+    if (isDarwin) {
+      const output = yield* system.run("/usr/sbin/ioreg", ["-rd1", "-c", "IOPlatformExpertDevice"]).pipe(Effect.orElseSucceed(() => ""));
+      const match = output.match(/"IOPlatformSerialNumber"\s*=\s*("(?:\\.|[^"\\])*")/);
+      if (match) serial = yield* Effect.try({ try: () => JSON.parse(match[1]) as string, catch: () => "" }).pipe(Effect.orElseSucceed(() => ""));
+    }
+    let macs: string[] = [];
+    if (Buffer.byteLength(serial) < 4) {
+      macs = yield* (isDarwin
+        ? Effect.map(system.run("/bin/sh", ["-c", MAC_COMMAND]), (output) => output.split(/\r?\n/).filter(Boolean))
+        : Effect.map(system.networkInterfaces(), interfaceMACs)
+      ).pipe(Effect.orElseSucceed((): string[] => []));
+    }
+    const username = yield* system.username().pipe(Effect.orElseSucceed(() => "unknown"));
+    return { serial, macs, username };
+  });
 }

package/src/core/protocol/endpoint.ts

@@ -0,0 +1,22 @@
+import { Effect } from "effect";
+import { toDevinError, type DevinError } from "../errors.ts";
+import { failWith } from "../validation.ts";
+
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "[::1]", "localhost"]);
+
+export function isLoopbackHost(hostname: string): boolean {
+  return LOOPBACK_HOSTS.has(hostname);
+}
+
+/** The origin of an HTTPS endpoint, or of loopback HTTP for local verification, without credentials or a path. */
+export function endpoint(value: string): Effect.Effect<string, DevinError> {
+  return Effect.try({ try: () => new URL(value), catch: toDevinError }).pipe(Effect.flatMap((url) => {
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopbackHost(url.hostname))) {
+      return failWith("The endpoint must be HTTPS, or loopback HTTP for local verification.");
+    }
+    if (url.username || url.password || url.search || url.hash || url.pathname !== "/") {
+      return failWith("The endpoint must not contain credentials, a path, a query, or a fragment.");
+    }
+    return Effect.succeed(url.origin);
+  }));
+}

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);
+}