@buyong/pi-devin 0.1.4 → 0.1.6

package/src/core/inference/images.ts

@@ -1,24 +1,31 @@
+import { Effect } from "effect";
+import type { DevinError } from "../errors.ts";
 import type { ImageData } from "../types.ts";
+import { failWith } from "../validation.ts";
 
 export const MAX_IMAGE_BYTES = 4 * 1024 * 1024;
 export const MAX_IMAGES_BYTES = 5 * 1024 * 1024;
 
-export function imageMimeType(bytes: Uint8Array): ImageData["mimeType"] {
+export function imageMimeType(bytes: Uint8Array): Effect.Effect<ImageData["mimeType"], DevinError> {
   const data = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
-  if (data.subarray(0, 8).equals(Buffer.from("89504e470d0a1a0a", "hex"))) return "image/png";
-  if (data.length >= 3 && data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff) return "image/jpeg";
-  if (["GIF87a", "GIF89a"].includes(data.subarray(0, 6).toString("ascii"))) return "image/gif";
-  if (data.length >= 12 && data.subarray(0, 4).toString("ascii") === "RIFF" && data.subarray(8, 12).toString("ascii") === "WEBP") return "image/webp";
-  throw new Error("Unsupported image. Use a PNG, JPEG, GIF or WebP file.");
+  if (data.subarray(0, 8).equals(Buffer.from("89504e470d0a1a0a", "hex"))) return Effect.succeed("image/png");
+  if (data.length >= 3 && data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff) return Effect.succeed("image/jpeg");
+  if (["GIF87a", "GIF89a"].includes(data.subarray(0, 6).toString("ascii"))) return Effect.succeed("image/gif");
+  if (data.length >= 12 && data.subarray(0, 4).toString("ascii") === "RIFF" && data.subarray(8, 12).toString("ascii") === "WEBP") return Effect.succeed("image/webp");
+  return failWith("Unsupported image. Use a PNG, JPEG, GIF or WebP file.");
 }
 
-export function imageFromBase64(data: string, mimeType: string): { image: ImageData; sizeBytes: number } {
-  if (data.length > Math.ceil(MAX_IMAGE_BYTES / 3) * 4 || data.length % 4 === 1 || !/^[A-Za-z0-9+/]*={0,2}$/.test(data)) {
-    throw new Error("Invalid image Base64 format or size.");
-  }
-  const bytes = Buffer.from(data, "base64");
-  if (bytes.length > MAX_IMAGE_BYTES || bytes.toString("base64").replace(/=+$/, "") !== data.replace(/=+$/, "")) throw new Error("Invalid image Base64 format or size.");
-  const actualMimeType = imageMimeType(bytes);
-  if (mimeType !== actualMimeType) throw new Error("The image MIME type does not match its actual format.");
-  return { image: { base64Data: data, mimeType: actualMimeType }, sizeBytes: bytes.length };
+export function imageFromBase64(data: string, mimeType: string): Effect.Effect<{ image: ImageData; sizeBytes: number }, DevinError> {
+  return Effect.gen(function* () {
+    if (data.length > Math.ceil(MAX_IMAGE_BYTES / 3) * 4 || data.length % 4 === 1 || !/^[A-Za-z0-9+/]*={0,2}$/.test(data)) {
+      return yield* failWith("Invalid image Base64 format or size.");
+    }
+    const bytes = Buffer.from(data, "base64");
+    if (bytes.length > MAX_IMAGE_BYTES || bytes.toString("base64").replace(/=+$/, "") !== data.replace(/=+$/, "")) {
+      return yield* failWith("Invalid image Base64 format or size.");
+    }
+    const actualMimeType = yield* imageMimeType(bytes);
+    if (mimeType !== actualMimeType) return yield* failWith("The image MIME type does not match its actual format.");
+    return { image: { base64Data: data, mimeType: actualMimeType }, sizeBytes: bytes.length };
+  });
 }

package/src/core/inference/request.ts

@@ -0,0 +1,59 @@
+import { randomUUID } from "node:crypto";
+import type { ChatMessage, ChatTool, ImageData, JsonObject } from "../types.ts";
+import { wireMessages } from "./messages.ts";
+
+export const DEFAULT_SYSTEM_PROMPT = "You are a helpful assistant. Follow the user\'s request concisely.";
+
+export function userMessage(prompt: string, images: readonly ImageData[] = []): ChatMessage {
+  return {
+    messageId: randomUUID(), source: "CHAT_MESSAGE_SOURCE_USER", prompt,
+    ...(images.length ? { images: images.map((image) => ({ ...image })) } : {}),
+  };
+}
+
+export function chatRequest(options: {
+  metadata: JsonObject;
+  model: string;
+  messages: ChatMessage[];
+  systemPrompt: string;
+  maxTokens: number;
+  cascadeId: string;
+  trajectoryId: string;
+  executionId?: string;
+  clientSessionId?: string;
+  modelAssignmentJwt?: string;
+  stepIndex?: number;
+  isAuxiliary?: boolean;
+  isRecovery?: boolean;
+  includeContext?: boolean;
+  cwd?: string;
+  tools?: ChatTool[];
+}): JsonObject {
+  return {
+    metadata: options.metadata,
+    prompt: options.systemPrompt,
+    chatMessagePrompts: wireMessages(options.messages, { includeContext: options.includeContext, cwd: options.cwd }),
+    chatModelUid: options.model,
+    requestType: "CHAT_MESSAGE_REQUEST_TYPE_CASCADE",
+    configuration: {
+      maxTokens: options.maxTokens,
+      numCompletions: 1,
+      maxNewlines: 400,
+      temperature: 1,
+      topK: 40,
+      topP: Math.fround(0.95),
+    },
+    trajectoryReference: {
+      trajectoryId: options.trajectoryId,
+      trajectoryType: "CORTEX_TRAJECTORY_TYPE_CASCADE",
+      ...(!options.isAuxiliary && !options.isRecovery && options.messages.at(-1)?.source === "CHAT_MESSAGE_SOURCE_USER" ? { stepType: "CORTEX_STEP_TYPE_USER_INPUT" } : {}),
+      ...(options.stepIndex ? { stepIndex: options.stepIndex } : {}),
+    },
+    cascadeId: options.cascadeId,
+    plannerMode: "CONVERSATIONAL_PLANNER_MODE_DEFAULT",
+    ...(!options.isAuxiliary && options.executionId ? { executionId: options.executionId } : {}),
+    ...(options.clientSessionId ? { clientSessionId: options.clientSessionId } : {}),
+    ...(options.modelAssignmentJwt ? { modelAssignmentJwt: options.modelAssignmentJwt } : {}),
+    ...(options.tools?.length ? { tools: options.tools } : {}),
+  };
+}

package/src/core/inference/retry.ts

@@ -1,5 +1,6 @@
-import { setTimeout as delay } from "node:timers/promises";
-import { awaitWithSignal, RPCError } from "../protocol/transport.ts";
+import { Duration, Effect } from "effect";
+import { RPCError, type DevinError, type DevinFailure } from "../errors.ts";
+import { failWith } from "../validation.ts";
 
 const CREATION_ATTEMPTS = 5;
 const RECOVERY_ATTEMPTS = 3;
@@ -10,7 +11,8 @@ const RETRYABLE_CONNECT_CODES = new Set(["resource_exhausted", "deadline_exceede
 
 export interface InferenceRetryRuntime {
   random?: () => number;
-  wait?: (delayMs: number, signal: AbortSignal) => Promise<void>;
+  /** Waits between attempts. Defaults to `Effect.sleep`, which the caller's interruption and guards stop. */
+  wait?: (delayMs: number) => Effect.Effect<void, DevinFailure>;
 }
 
 export interface InferenceRetryEvent {
@@ -21,48 +23,46 @@ export interface InferenceRetryEvent {
 }
 
 /** Backoff: starts at 2 s, doubles, jitter factor 0.5. The elapsed-time cap is disabled. */
-export function inferenceRetryDelayMs(retryIndex: number, random: number): number {
-  if (!Number.isInteger(retryIndex) || retryIndex < 0 || retryIndex >= CREATION_ATTEMPTS - 1) throw new Error("Invalid retry index.");
-  if (!Number.isFinite(random) || random < 0 || random >= 1) throw new Error("The retry random value must be at least 0 and below 1.");
+export function inferenceRetryDelayMs(retryIndex: number, random: number): Effect.Effect<number, DevinError> {
+  if (!Number.isInteger(retryIndex) || retryIndex < 0 || retryIndex >= CREATION_ATTEMPTS - 1) return failWith("Invalid retry index.");
+  if (!Number.isFinite(random) || random < 0 || random >= 1) return failWith("The retry random value must be at least 0 and below 1.");
   const intervalMs = Math.min(INITIAL_INTERVAL_MS * 2 ** retryIndex, MAX_INTERVAL_MS);
   const intervalNanos = intervalMs * 1_000_000;
-  return Math.floor((intervalNanos * 0.5 + random * (intervalNanos + 1)) / 1_000_000);
+  return Effect.succeed(Math.floor((intervalNanos * 0.5 + random * (intervalNanos + 1)) / 1_000_000));
 }
 
-function canRetryCreation(error: unknown): boolean {
+function canRetryCreation(error: DevinFailure): boolean {
   return error instanceof RPCError && error.httpStatus !== undefined && RETRYABLE_HTTP_STATUSES.has(error.httpStatus);
 }
 
-function canRecover(error: unknown): boolean {
+function canRecover(error: DevinFailure): boolean {
   return canRetryCreation(error) || (error instanceof RPCError && error.httpStatus === undefined && RETRYABLE_CONNECT_CODES.has(error.code));
 }
 
 /** Makes each attempt build a new request, separate from the same-body resend of the 415/compression fallback. */
-export async function withInferenceRetries<T>(
-  request: (isRecovery: boolean) => Promise<T>,
-  options: { signal: AbortSignal; runtime?: InferenceRetryRuntime; onRetry?: (event: InferenceRetryEvent) => void },
-): Promise<T> {
-  const { signal, runtime = {} } = options;
+export function withInferenceRetries<A>(
+  request: (isRecovery: boolean) => Effect.Effect<A, DevinFailure>,
+  options: { runtime?: InferenceRetryRuntime; onRetry?: (event: InferenceRetryEvent) => Effect.Effect<void> } = {},
+): Effect.Effect<A, DevinFailure> {
+  const runtime = options.runtime ?? {};
   const random = runtime.random ?? Math.random;
-  const wait = runtime.wait ?? ((delayMs: number, signal: AbortSignal) => delay(delayMs, undefined, { signal }));
-  let lastError: unknown;
-  for (let recovery = 0; recovery < RECOVERY_ATTEMPTS; recovery++) {
-    for (let attempt = 0; attempt < CREATION_ATTEMPTS; attempt++) {
-      signal.throwIfAborted();
-      try { return await request(recovery > 0); }
-      catch (error) {
-        signal.throwIfAborted();
-        if (!canRecover(error)) throw error;
+  const wait = runtime.wait ?? ((delayMs: number) => Effect.sleep(Duration.millis(delayMs)));
+  return Effect.gen(function* () {
+    let lastError: DevinFailure | undefined;
+    for (let recovery = 0; recovery < RECOVERY_ATTEMPTS; recovery++) {
+      for (let attempt = 0; attempt < CREATION_ATTEMPTS; attempt++) {
+        const outcome = yield* Effect.result(request(recovery > 0));
+        if (outcome._tag === "Success") return outcome.success;
+        const error = outcome.failure;
+        if (!canRecover(error)) return yield* Effect.fail(error);
         lastError = error;
         if (!canRetryCreation(error) || attempt + 1 === CREATION_ATTEMPTS) break;
-        const delayMs = inferenceRetryDelayMs(attempt, random());
-        options.onRetry?.({ phase: "creation", nextAttempt: attempt + 2, limit: CREATION_ATTEMPTS, delayMs });
-        try { await awaitWithSignal(wait(delayMs, signal), signal); }
-        catch (error) { signal.throwIfAborted(); throw error; }
+        const delayMs = yield* inferenceRetryDelayMs(attempt, random());
+        if (options.onRetry) yield* options.onRetry({ phase: "creation", nextAttempt: attempt + 2, limit: CREATION_ATTEMPTS, delayMs });
+        yield* wait(delayMs);
       }
+      if (recovery + 1 < RECOVERY_ATTEMPTS && options.onRetry) yield* options.onRetry({ phase: "recovery", nextAttempt: recovery + 2, limit: RECOVERY_ATTEMPTS, delayMs: 0 });
     }
-    signal.throwIfAborted();
-    if (recovery + 1 < RECOVERY_ATTEMPTS) options.onRetry?.({ phase: "recovery", nextAttempt: recovery + 2, limit: RECOVERY_ATTEMPTS, delayMs: 0 });
-  }
-  throw lastError;
+    return yield* Effect.fail(lastError!);
+  });
 }

package/src/core/inference/state.ts

@@ -1,8 +1,12 @@
+import { Effect } from "effect";
+import type { DevinError } from "../errors.ts";
+import { failWith } from "../validation.ts";
+
 export const MAX_STEP_INDEX = 2_147_483_647;
 
 export interface StepState { nextStepIndex: number }
 
-export function takeStep(state: StepState): number {
-  if (state.nextStepIndex >= MAX_STEP_INDEX) throw new Error("The session step limit was exceeded.");
-  return state.nextStepIndex++;
+export function takeStep(state: StepState): Effect.Effect<number, DevinError> {
+  return Effect.suspend(() => state.nextStepIndex >= MAX_STEP_INDEX ? failWith("The session step limit was exceeded.")
+    : Effect.succeed(state.nextStepIndex++));
 }

package/src/core/inference/stream-chat.ts

@@ -0,0 +1,48 @@
+import { Effect, Predicate, Stream } from "effect";
+import type { DevinFailure } from "../errors.ts";
+import type { ConnectClient } from "../protocol/connect-client.ts";
+import { CHAT_METHOD } from "../protocol/protobuf.ts";
+import type { ChatResult, JsonObject } from "../types.ts";
+import { assertRunnableToolCalls, ChatAccumulator } from "./accumulator.ts";
+
+export interface StreamChatOptions {
+  onText?: (delta: string) => Effect.Effect<void>;
+  stage?: string;
+  onDispatched?: Effect.Effect<void, DevinFailure>;
+}
+
+/** Sends one chat request and folds its frames into a single result. */
+export function streamChat(client: ConnectClient, request: JsonObject, options: StreamChatOptions = {}): Effect.Effect<ChatResult, DevinFailure> {
+  return Effect.gen(function* () {
+    const accumulator = new ChatAccumulator();
+    yield* client.stream(CHAT_METHOD, request, { stage: options.stage, onDispatched: options.onDispatched }).pipe(Stream.runForEach((frame) => Effect.gen(function* () {
+      yield* accumulator.accept(frame.data, frame.isEnd);
+      if (!frame.isEnd && Predicate.isString(frame.data.deltaText) && options.onText) yield* options.onText(frame.data.deltaText);
+    })));
+    const result = yield* accumulator.finish;
+    yield* assertRunnableToolCalls(result);
+    // Field 22 records the model of the generation request, not actualModelUid/usage.modelUid.
+    if (Predicate.isString(request.chatModelUid)) result.message.modelUid = request.chatModelUid;
+    return result;
+  });
+}
+
+/** Raw thinking and signatures never go to logs or reports. They are only resent inside requests. */
+export function summarizeChat(result: ChatResult): JsonObject {
+  return {
+    text: result.message.prompt,
+    stopReason: result.stopReason,
+    usage: result.usage,
+    usageReported: result.usageReported,
+    toolCalls: result.message.toolCalls ?? [],
+    thinkingChars: result.message.thinking?.length ?? 0,
+    hasSignature: Boolean(result.message.signature || result.message.geminiThoughtSignature),
+    frameCount: result.frameCount,
+    stopFrameIndex: result.stopFrameIndex,
+    lastUsageFrameIndex: result.lastUsageFrameIndex,
+    idlessToolDeltaCount: result.idlessToolDeltaCount,
+    durationMs: result.durationMs,
+    firstDeltaMs: result.firstDeltaMs,
+    actualModelUid: result.actualModelUid,
+  };
+}

package/src/core/models/access.ts

@@ -1,7 +1,8 @@
+import { Predicate } from "effect";
 import type { JsonObject, ModelInfo } from "../types.ts";
 
 /** When the server provides a separate allowlist, it is applied together with the catalog's disabled flags. */
-export function applyTeamModelPolicy(models: ModelInfo[], team: JsonObject): void {
-  const allowed = Array.isArray(team.allowedModelUids) ? team.allowedModelUids.filter((id): id is string => typeof id === "string") : [];
-  if (allowed.length) for (const model of models) model.isDisabled ||= !allowed.includes(model.id);
+export function applyTeamModelPolicy(models: readonly ModelInfo[], team: JsonObject): ModelInfo[] {
+  const allowed = Array.isArray(team.allowedModelUids) ? team.allowedModelUids.filter(Predicate.isString) : [];
+  return allowed.length ? models.map((model) => ({ ...model, isDisabled: model.isDisabled || !allowed.includes(model.id) })) : [...models];
 }

package/src/core/models/catalog.ts

@@ -1,35 +1,44 @@
-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";
 
 export interface ModelCatalog { raw: JsonObject; models: ModelInfo[]; defaultModelUid?: string }
 
-export function parseModelCatalog(response: JsonObject): ModelCatalog {
-  if (!Array.isArray(response.clientModelConfigs)) throw new Error("clientModelConfigs is missing.");
-  const override = object(response.defaultOverrideModelConfig ?? {}, "defaultOverrideModelConfig");
-  const defaultModelUid = typeof override.modelUid === "string" ? override.modelUid : undefined;
-  const models = response.clientModelConfigs.map((value) => {
-    const config = object(value, "ClientModelConfig");
-    const info = object(config.modelInfo, "modelInfo");
-    const features = object(info.modelFeatures ?? {}, "modelFeatures");
-    const family = object(config.modelFamilyMetadata ?? {}, "modelFamilyMetadata");
+function parseModel(value: unknown): Effect.Effect<ModelInfo, DevinError> {
+  return Effect.gen(function* () {
+    const config = yield* object(value, "ClientModelConfig");
+    const info = yield* object(config.modelInfo, "modelInfo");
+    const features = yield* object(info.modelFeatures ?? {}, "modelFeatures");
+    const family = yield* object(config.modelFamilyMetadata ?? {}, "modelFamilyMetadata");
     return {
-      id: requiredString(config.modelUid, "modelUid"),
-      name: requiredString(config.label, "label"),
-      contextWindow: tokenCount(info.maxTokens ?? 0, "context window"),
-      maxOutputTokens: tokenCount(info.maxOutputTokens ?? 0, "max output tokens"),
+      id: yield* requiredString(config.modelUid, "modelUid"),
+      name: yield* requiredString(config.label, "label"),
+      contextWindow: yield* tokenCount(info.maxTokens ?? 0, "context window"),
+      maxOutputTokens: yield* tokenCount(info.maxOutputTokens ?? 0, "max output tokens"),
       supportsThinking: features.supportsThinking === true,
       supportsImages: config.supportsImages === true || features.supportsImages === true,
       supportsToolCalls: features.supportsToolCalls === true,
       supportsParallelToolCalls: features.supportsParallelToolCalls === true,
       isRouter: info.isModelRouter === true,
       isDisabled: config.disabled === true,
-      familyId: typeof info.modelFamilyUid === "string" ? info.modelFamilyUid : undefined,
-      aliases: Array.isArray(info.aliases) ? info.aliases.filter((value): value is string => typeof value === "string") : [],
+      familyId: Predicate.isString(info.modelFamilyUid) ? info.modelFamilyUid : undefined,
+      aliases: Array.isArray(info.aliases) ? info.aliases.filter(Predicate.isString) : [],
       isDefaultInFamily: config.isDefaultModelInFamily === true || family.isDefaultModelInFamily === true,
       isRecommended: config.isRecommended === true,
-      costTier: typeof config.modelCostTier === "string" ? config.modelCostTier : undefined,
-      creditMultiplier: typeof config.creditMultiplier === "number" ? config.creditMultiplier : undefined,
-      pricingType: typeof config.pricingType === "string" ? config.pricingType : undefined,
+      costTier: Predicate.isString(config.modelCostTier) ? config.modelCostTier : undefined,
+      creditMultiplier: Predicate.isNumber(config.creditMultiplier) ? config.creditMultiplier : undefined,
+      pricingType: Predicate.isString(config.pricingType) ? config.pricingType : undefined,
     };
   });
-  return { raw: response, models, defaultModelUid };
+}
+
+export function parseModelCatalog(response: JsonObject): Effect.Effect<ModelCatalog, DevinError> {
+  return Effect.gen(function* () {
+    if (!Array.isArray(response.clientModelConfigs)) return yield* failWith("clientModelConfigs is missing.");
+    const override = yield* object(response.defaultOverrideModelConfig ?? {}, "defaultOverrideModelConfig");
+    const defaultModelUid = Predicate.isString(override.modelUid) ? override.modelUid : undefined;
+    const models = yield* Effect.forEach(response.clientModelConfigs, parseModel);
+    return { raw: response, models, defaultModelUid };
+  });
 }

package/src/core/models/select.ts

@@ -1,19 +1,23 @@
+import { Effect } from "effect";
+import type { DevinError } from "../errors.ts";
 import type { ModelInfo } from "../types.ts";
+import { failWith } from "../validation.ts";
 
 /** Saved sessions and AssignModel results are already-resolved UIDs, not selectors. */
-export function getModelByUID(models: readonly ModelInfo[], uid: string): ModelInfo {
+export function getModelByUID(models: readonly ModelInfo[], uid: string): Effect.Effect<ModelInfo, DevinError> {
   const model = models.find((entry) => entry.id === uid);
-  if (!model) throw new Error(`${uid} is not in the model list. It is not replaced with another model automatically.`);
-  if (model.isDisabled) throw new Error(`Model is disabled: ${uid}`);
-  return model;
+  if (!model) return failWith(`${uid} is not in the model list. It is not replaced with another model automatically.`);
+  if (model.isDisabled) return failWith(`Model is disabled: ${uid}`);
+  return Effect.succeed(model);
 }
 
+const normalize = (name: string) => name.trim().toLowerCase().replaceAll(" ", "-");
+const tokenize = (name: string): string[] => name.toLowerCase().match(/[a-z]+|[0-9]+/g) ?? [];
+
 /** Resolves user selectors to match the CLI's selector semantics. The caller picks the default first. */
-export function selectModel(models: readonly ModelInfo[], selector: string): ModelInfo {
-  const normalize = (name: string) => name.trim().toLowerCase().replaceAll(" ", "-");
-  const tokenize = (name: string): string[] => name.toLowerCase().match(/[a-z]+|[0-9]+/g) ?? [];
+export function selectModel(models: readonly ModelInfo[], selector: string): Effect.Effect<ModelInfo, DevinError> {
   const query = normalize(selector);
-  if (!query) throw new Error("The model name is empty.");
+  if (!query) return failWith("The model name is empty.");
 
   // Families take precedence over aliases. An alias points to a family, not a declared variant.
   const family = models.find((model) => model.familyId && normalize(model.familyId) === query)
@@ -21,8 +25,7 @@ export function selectModel(models: readonly ModelInfo[], selector: string): Mod
   if (family) {
     const selected = models.find((model) => !model.isDisabled
       && (family.familyId ? model.familyId === family.familyId : model.id === family.id));
-    if (!selected) throw new Error(`Model is disabled: ${selector}`);
-    return selected;
+    return selected ? Effect.succeed(selected) : failWith(`Model is disabled: ${selector}`);
   }
 
   const exact = models.find((model) => normalize(model.id) === query)
@@ -38,6 +41,5 @@ export function selectModel(models: readonly ModelInfo[], selector: string): Mod
     : [];
   candidates.sort((left, right) => left.tokens.length - right.tokens.length
     || (left.model.id < right.model.id ? 1 : left.model.id > right.model.id ? -1 : 0));
-  if (candidates[0]) return candidates[0].model;
-  throw new Error(`Model unavailable: ${selector}`);
+  return candidates[0] ? Effect.succeed(candidates[0].model) : failWith(`Model unavailable: ${selector}`);
 }

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