@buyong/pi-devin 0.1.5 → 0.1.6

package/src/core/models/variants.ts

@@ -1,4 +1,7 @@
-import { object, requiredString, tokenCount, type JsonObject, type ModelInfo } from "../types.ts";
+import { Effect, Predicate } from "effect";
+import type { DevinError } from "../errors.ts";
+import type { JsonObject, ModelInfo } from "../types.ts";
+import { failWith, object, requiredString, tokenCount } from "../validation.ts";
 import { parseModelCatalog, type ModelCatalog } from "./catalog.ts";
 import { getModelByUID } from "./select.ts";
 
@@ -43,20 +46,23 @@ export function groupModelID(family: string, dimensions: readonly ModelDimension
   return "family:" + encodeURIComponent(family) + (dimensions.length ? ":" + Buffer.from(key).toString("base64url") : "");
 }
 
-function dimensionsOf(config: JsonObject): ModelDimension[] {
-  const family = object(config.modelFamilyMetadata ?? {}, "modelFamilyMetadata");
-  if (family.entries === undefined) return [];
-  if (!Array.isArray(family.entries)) throw new Error("Model dimension entries are not an array.");
-  const seen = new Set<string>();
-  return family.entries.map((item) => {
-    const entry = object(item, "model dimension"), value = object(entry.value ?? {}, "dimension value");
-    const key = requiredString(entry.key, "dimension key");
-    if (seen.has(key)) throw new Error(`Duplicate model dimension: ${key}`);
-    seen.add(key);
-    const order = tokenCount(value.order ?? 0, "dimension order");
-    if (!Number.isSafeInteger(order)) throw new Error("The model dimension order must be an integer.");
-    return { key, order, name: typeof value.name === "string" ? value.name : "" };
-  }).sort((a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : 0);
+function dimensionsOf(config: JsonObject): Effect.Effect<ModelDimension[], DevinError> {
+  return Effect.gen(function* () {
+    const family = yield* object(config.modelFamilyMetadata ?? {}, "modelFamilyMetadata");
+    if (family.entries === undefined) return [];
+    if (!Array.isArray(family.entries)) return yield* failWith("Model dimension entries are not an array.");
+    const seen = new Set<string>();
+    const dimensions: ModelDimension[] = [];
+    for (const item of family.entries) {
+      const entry = yield* object(item, "model dimension"), value = yield* object(entry.value ?? {}, "dimension value");
+      const key = yield* requiredString(entry.key, "dimension key");
+      if (seen.has(key)) return yield* failWith(`Duplicate model dimension: ${key}`);
+      seen.add(key);
+      const order = yield* tokenCount(value.order ?? 0, "dimension order");
+      dimensions.push({ key, order, name: Predicate.isString(value.name) ? value.name : "" });
+    }
+    return dimensions.sort((a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : 0);
+  });
 }
 
 function classify(model: ModelInfo, dimensions: readonly ModelDimension[]): Pick<ModelVariant, "level" | "unsupported"> {
@@ -73,8 +79,7 @@ function classify(model: ModelInfo, dimensions: readonly ModelDimension[]): Pick
   return { unsupported: "thinking strength metadata is unknown" };
 }
 
-function sanitizedConfig(config: JsonObject, model: ModelInfo, familyName: string, dimensions: readonly ModelDimension[]): JsonObject {
-  const info = object(config.modelInfo, "modelInfo");
+function sanitizedConfig(info: JsonObject, model: ModelInfo, familyName: string, dimensions: readonly ModelDimension[]): JsonObject {
   return {
     modelUid: model.id, label: model.name, disabled: model.isDisabled, maxTokens: model.contextWindow,
     supportsImages: model.supportsImages,
@@ -83,7 +88,7 @@ function sanitizedConfig(config: JsonObject, model: ModelInfo, familyName: strin
     modelInfo: {
       modelUid: model.id, modelFamilyUid: model.familyId || model.id,
       maxTokens: model.contextWindow, maxOutputTokens: model.maxOutputTokens,
-      ...(typeof info.modelType === "string" ? { modelType: info.modelType } : {}),
+      ...(Predicate.isString(info.modelType) ? { modelType: info.modelType } : {}),
       isModelRouter: model.isRouter, aliases: [...(model.aliases ?? [])],
       modelFeatures: {
         supportsImages: model.supportsImages, supportsToolCalls: model.supportsToolCalls,
@@ -98,66 +103,74 @@ function capabilityKey(model: ModelInfo): string {
   return JSON.stringify([model.contextWindow, model.maxOutputTokens, model.supportsImages, model.supportsToolCalls, model.supportsParallelToolCalls]);
 }
 
-export function projectModelVariants(catalog: ModelCatalog): VariantProjection {
-  const configs = catalog.raw.clientModelConfigs;
-  if (!Array.isArray(configs) || configs.length !== catalog.models.length) throw new Error("The raw and projected model lists do not match.");
-  const ids = new Set<string>();
-  const variants = catalog.models.map((original, index): ModelVariant => {
-    if (ids.has(original.id)) throw new Error(`Duplicate model UID: ${original.id}`);
-    ids.add(original.id);
-    const config = object(configs[index], "model config"), info = object(config.modelInfo, "modelInfo");
-    if (config.modelUid !== original.id) throw new Error("Model UIDs do not match the raw order.");
-    const allDimensions = dimensionsOf(config);
-    const family = object(config.modelFamilyMetadata ?? {}, "modelFamilyMetadata");
-    const model = { ...original, aliases: [...(original.aliases ?? [])], contextWindow: tokenCount(config.maxTokens ?? original.contextWindow, "context window") };
-    const familyName = typeof family.modelFamilyLabel === "string" && family.modelFamilyLabel ? family.modelFamilyLabel : model.familyId || model.name;
-    const classification = typeof info.modelType === "string" && info.modelType !== "MODEL_TYPE_CHAT"
-      ? { unsupported: "not a chat model" } : classify(model, allDimensions);
+export function projectModelVariants(catalog: ModelCatalog): Effect.Effect<VariantProjection, DevinError> {
+  return Effect.gen(function* () {
+    const configs = catalog.raw.clientModelConfigs;
+    if (!Array.isArray(configs) || configs.length !== catalog.models.length) return yield* failWith("The raw and projected model lists do not match.");
+    const ids = new Set<string>();
+    const variants: ModelVariant[] = [];
+    for (const [index, original] of catalog.models.entries()) {
+      if (ids.has(original.id)) return yield* failWith(`Duplicate model UID: ${original.id}`);
+      ids.add(original.id);
+      const config = yield* object(configs[index], "model config"), info = yield* object(config.modelInfo, "modelInfo");
+      if (config.modelUid !== original.id) return yield* failWith("Model UIDs do not match the raw order.");
+      const allDimensions = yield* dimensionsOf(config);
+      const family = yield* object(config.modelFamilyMetadata ?? {}, "modelFamilyMetadata");
+      const model = { ...original, aliases: [...(original.aliases ?? [])], contextWindow: yield* tokenCount(config.maxTokens ?? original.contextWindow, "context window") };
+      const familyName = Predicate.isString(family.modelFamilyLabel) && family.modelFamilyLabel ? family.modelFamilyLabel : model.familyId || model.name;
+      const classification = Predicate.isString(info.modelType) && info.modelType !== "MODEL_TYPE_CHAT"
+        ? { unsupported: "not a chat model" } : classify(model, allDimensions);
+      variants.push({
+        model, family: model.familyId || model.id, familyName,
+        dimensions: allDimensions.filter((entry) => !thinkingDimensions.has(entry.key)), ...classification,
+        config: sanitizedConfig(info, model, familyName, allDimensions),
+      });
+    }
+    const groupMap = new Map<string, VariantGroup>();
+    for (const variant of variants) {
+      const id = groupModelID(variant.family, variant.dimensions);
+      let group = groupMap.get(id);
+      if (!group) {
+        group = { id, family: variant.family, name: variant.familyName, dimensions: variant.dimensions, variants: [], mappings: {}, canPublish: true };
+        groupMap.set(id, group);
+      }
+      group.variants.push(variant);
+      if (variant.level === undefined || variant.unsupported) continue;
+      if (group.mappings[variant.level]) { group.canPublish = false; group.reason = "ambiguous UID for thinking level"; }
+      else group.mappings[variant.level] = variant.model.id;
+    }
+    for (const group of groupMap.values()) {
+      const supported = group.variants.filter((variant) => variant.level !== undefined && !variant.unsupported);
+      if (!supported.length) { group.canPublish = false; group.reason = "no verified thinking mapping"; }
+      else if (new Set(supported.map((variant) => capabilityKey(variant.model))).size !== 1) {
+        group.canPublish = false; group.reason = "variant capabilities differ; use exact UID";
+      }
+    }
     return {
-      model, family: model.familyId || model.id, familyName,
-      dimensions: allDimensions.filter((entry) => !thinkingDimensions.has(entry.key)), ...classification,
-      config: sanitizedConfig(config, model, familyName, allDimensions),
+      variants, groups: [...groupMap.values()],
+      unsupported: variants.flatMap((variant) => variant.unsupported ? [{ uid: variant.model.id, reason: variant.unsupported }] : []),
     };
   });
-  const groupMap = new Map<string, VariantGroup>();
-  for (const variant of variants) {
-    const id = groupModelID(variant.family, variant.dimensions);
-    let group = groupMap.get(id);
-    if (!group) {
-      group = { id, family: variant.family, name: variant.familyName, dimensions: variant.dimensions, variants: [], mappings: {}, canPublish: true };
-      groupMap.set(id, group);
-    }
-    group.variants.push(variant);
-    if (variant.level === undefined || variant.unsupported) continue;
-    if (group.mappings[variant.level]) { group.canPublish = false; group.reason = "ambiguous UID for thinking level"; }
-    else group.mappings[variant.level] = variant.model.id;
-  }
-  for (const group of groupMap.values()) {
-    const supported = group.variants.filter((variant) => variant.level !== undefined && !variant.unsupported);
-    if (!supported.length) { group.canPublish = false; group.reason = "no verified thinking mapping"; }
-    else if (new Set(supported.map((variant) => capabilityKey(variant.model))).size !== 1) {
-      group.canPublish = false; group.reason = "variant capabilities differ; use exact UID";
-    }
-  }
-  return { variants, groups: [...groupMap.values()], unsupported: variants.filter((variant) => variant.unsupported).map((variant) => ({ uid: variant.model.id, reason: variant.unsupported! })) };
 }
 
-export function restoreModelVariants(configs: readonly JsonObject[]): VariantProjection {
-  return projectModelVariants(parseModelCatalog({ clientModelConfigs: [...configs] }));
+export function restoreModelVariants(configs: readonly JsonObject[]): Effect.Effect<VariantProjection, DevinError> {
+  return Effect.flatMap(parseModelCatalog({ clientModelConfigs: [...configs] }), projectModelVariants);
 }
 
 /** Accepts only the effective level that Pi already clamped or selected. Never falls back to an alias, price or default model. */
-export function resolveBackendSelection(projection: VariantProjection, modelID: string, level: EffectiveThinkingLevel): BackendModelSelection {
-  if (!EFFECTIVE_THINKING_LEVELS.includes(level)) throw new Error(`Unsupported thinking level: ${level}`);
-  let variant = projection.variants.find((entry) => modelIDForUID(entry.model.id) === modelID);
-  if (variant) {
-    if (variant.unsupported || variant.level !== level) throw new Error(`This exact UID does not support the requested thinking level: ${modelID} (${level})`);
-  } else {
-    const group = projection.groups.find((entry) => entry.id === modelID);
-    const uid = group?.canPublish ? group.mappings[level] : undefined;
-    if (!uid) throw new Error(`Model or thinking level unavailable: ${modelID} (${level})`);
-    variant = projection.variants.find((entry) => entry.model.id === uid)!;
-  }
-  const model = getModelByUID(projection.variants.map((entry) => entry.model), variant.model.id);
-  return { uid: model.id, model, level, variant };
+export function resolveBackendSelection(projection: VariantProjection, modelID: string, level: EffectiveThinkingLevel): Effect.Effect<BackendModelSelection, DevinError> {
+  return Effect.gen(function* () {
+    if (!EFFECTIVE_THINKING_LEVELS.includes(level)) return yield* failWith(`Unsupported thinking level: ${level}`);
+    let variant = projection.variants.find((entry) => modelIDForUID(entry.model.id) === modelID);
+    if (variant) {
+      if (variant.unsupported || variant.level !== level) return yield* failWith(`This exact UID does not support the requested thinking level: ${modelID} (${level})`);
+    } else {
+      const group = projection.groups.find((entry) => entry.id === modelID);
+      const uid = group?.canPublish ? group.mappings[level] : undefined;
+      variant = uid === undefined ? undefined : projection.variants.find((entry) => entry.model.id === uid);
+      if (!variant) return yield* failWith(`Model or thinking level unavailable: ${modelID} (${level})`);
+    }
+    const model = yield* getModelByUID(projection.variants.map((entry) => entry.model), variant.model.id);
+    return { uid: model.id, model, level, variant };
+  });
 }

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