@buyong/pi-devin 0.1.5 → 0.1.6

package/src/core/inference/accumulator.ts

@@ -0,0 +1,174 @@
+import { randomUUID } from "node:crypto";
+import { Effect, Predicate } from "effect";
+import { DevinError } from "../errors.ts";
+import type { ChatMessage, ChatResult, JsonObject, ToolCall, Usage } from "../types.ts";
+import { failWith, object, requiredString, tokenCount } from "../validation.ts";
+
+// Backends mark a finished turn differently: Anthropic text ends with MIN_LOG_PROB, Gemini tool calls with STOP_PATTERN,
+// and OpenAI sends no stop reason (UNSPECIFIED is the proto3 default, so it is not on the wire).
+const COMPLETE_STOP_REASONS = new Set(["STOP_REASON_STOP_PATTERN", "STOP_REASON_FUNCTION_CALL", "STOP_REASON_MIN_LOG_PROB", "STOP_REASON_UNSPECIFIED", ""]);
+const COPIED_STRINGS = [
+  ["deltaSignatureType", "signatureType"], ["geminiThoughtSignature", "geminiThoughtSignature"],
+  ["outputId", "outputId"], ["thinkingId", "thinkingId"], ["phase", "phase"],
+] as const;
+const USAGE_FIELDS = [["inputTokens", "input"], ["outputTokens", "output"], ["cacheReadTokens", "cacheRead"], ["cacheWriteTokens", "cacheWrite"]] as const;
+
+const SERVER_JSON_ERROR = "The server reported a tool argument JSON error.";
+
+/**
+ * Fails when a finished result has a call that must not run: arguments that are not a JSON object, or calls cut off at the output limit.
+ * The CLI runs tools itself and uses this; Pi reports such calls back to the model instead.
+ */
+export function assertRunnableToolCalls(result: ChatResult): Effect.Effect<void, DevinError> {
+  return Effect.gen(function* () {
+    for (const call of result.message.toolCalls ?? []) {
+      const error = result.toolArgumentErrors[call.id];
+      if (error) return yield* failWith(error.startsWith(SERVER_JSON_ERROR) ? SERVER_JSON_ERROR : `Arguments of tool ${call.name} are not valid JSON.`);
+    }
+    if (result.message.toolCalls?.length && !COMPLETE_STOP_REASONS.has(result.stopReason)) return yield* failWith("Tool calls and the stop reason do not match.");
+  });
+}
+
+/** Pi's wording for arguments that are not a JSON object: the problem, then the text the model sent. */
+function argumentsError(call: ToolCall): string | undefined {
+  try {
+    const value = JSON.parse(call.argumentsJson) as unknown;
+    if (Predicate.isObject(value) && !Array.isArray(value)) return undefined;
+    return `Tool arguments must be a JSON object\n\nReceived arguments:\n${call.argumentsJson}`;
+  } catch (error) {
+    return `${error instanceof Error ? error.message : String(error)}\n\nReceived arguments:\n${call.argumentsJson}`;
+  }
+}
+
+/** Attaches argument deltas without an ID to the call that started with the first ID. Ambiguous parallel deltas are rejected. */
+export class ChatAccumulator {
+  readonly message: ChatMessage = { messageId: "", source: "CHAT_MESSAGE_SOURCE_SYSTEM", prompt: "" };
+  readonly usage: Usage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0 };
+  readonly calls = new Map<string, ToolCall>();
+  /** Calls the server marked as invalid JSON. Their arguments are reported, never parsed into a runnable call. */
+  private readonly serverArgumentErrors = new Set<string>();
+  private currentCall?: ToolCall;
+  private hasEnded = false;
+  private readonly startedAt = performance.now();
+  private firstDeltaMs?: number;
+  private stopReason = "";
+  private usageReported = false;
+  private frameCount = 0;
+  private stopFrameIndex?: number;
+  private lastUsageFrameIndex?: number;
+  private idlessToolDeltaCount = 0;
+  private actualModelUid?: string;
+  private usageModelUid?: string;
+
+  accept(data: JsonObject, isEnd = false): Effect.Effect<void, DevinError> {
+    const self = this;
+    return Effect.gen(function* () {
+      if (self.hasEnded) return yield* failWith("Cannot accumulate a response after EndStream.");
+      self.frameCount++;
+      if (isEnd) {
+        if (data.error) return yield* failWith("An error EndStream cannot be treated as success.");
+        self.hasEnded = true;
+        return;
+      }
+      if (data.redact === true) return yield* failWith("The server redacted the response.");
+      const message = self.message;
+      if (Predicate.isString(data.messageId) && data.messageId) message.messageId = data.messageId;
+      if (data.thinkingRedacted === true) {
+        message.thinkingRedacted = true;
+        message.thinking = "";
+      }
+      if (Predicate.isString(data.deltaText)) message.prompt += data.deltaText;
+      if (Predicate.isString(data.deltaThinking) && !message.thinkingRedacted) message.thinking = (message.thinking ?? "") + data.deltaThinking;
+      if (Predicate.isString(data.deltaSignature)) message.signature = (message.signature ?? "") + data.deltaSignature;
+      for (const [source, target] of COPIED_STRINGS) {
+        const value = data[source];
+        if (Predicate.isString(value)) message[target] = value;
+      }
+      if (Predicate.isString(data.actualModelUid)) self.actualModelUid = data.actualModelUid;
+      if (data.deltaToolCalls !== undefined) yield* self.acceptToolDeltas(data.deltaToolCalls);
+      if (data.deltaText || data.deltaThinking || data.deltaToolCalls) self.firstDeltaMs ??= performance.now() - self.startedAt;
+      if (Predicate.isString(data.stopReason) && data.stopReason) {
+        self.stopReason = data.stopReason;
+        self.stopFrameIndex = self.frameCount;
+      }
+      if (data.usage !== undefined) {
+        const usage = yield* object(data.usage, "usage");
+        if (Predicate.isString(usage.modelUid)) self.usageModelUid = usage.modelUid;
+        for (const [source, target] of USAGE_FIELDS) {
+          if (usage[source] === undefined) continue;
+          self.usage[target] = yield* tokenCount(usage[source], source);
+          self.usageReported = true;
+          self.lastUsageFrameIndex = self.frameCount;
+        }
+        self.usage.totalTokens = self.usage.input + self.usage.output + self.usage.cacheRead + self.usage.cacheWrite;
+      }
+    });
+  }
+
+  private acceptToolDeltas(deltas: unknown): Effect.Effect<void, DevinError> {
+    const self = this;
+    return Effect.gen(function* () {
+      if (!Array.isArray(deltas)) return yield* failWith("deltaToolCalls must be an array.");
+      for (const value of deltas) {
+        const delta = yield* object(value, "tool delta");
+        const id = Predicate.isString(delta.id) && delta.id ? delta.id : undefined;
+        if (id) {
+          let call = self.calls.get(id);
+          if (!call) {
+            call = { id, name: "", argumentsJson: "" };
+            self.calls.set(id, call);
+          }
+          self.currentCall = call;
+        } else {
+          self.idlessToolDeltaCount++;
+          if (deltas.length !== 1 || !self.currentCall || self.calls.size > 1) {
+            return yield* failWith("Cannot attach a delta without a tool ID to a specific call.");
+          }
+        }
+        const call = self.currentCall!;
+        if (delta.isCustomToolCall) return yield* failWith("Grammar-based custom tools are not supported.");
+        if (delta.invalidJsonErr || delta.invalidJsonStr) self.serverArgumentErrors.add(call.id);
+        if (Predicate.isString(delta.name)) call.name += delta.name;
+        if (Predicate.isString(delta.argumentsJson)) call.argumentsJson += delta.argumentsJson;
+      }
+    });
+  }
+
+  get finish(): Effect.Effect<ChatResult, DevinError> {
+    const self = this;
+    return Effect.gen(function* () {
+      if (!self.hasEnded) return yield* failWith("No successful EndStream.");
+      if (!COMPLETE_STOP_REASONS.has(self.stopReason) && self.stopReason !== "STOP_REASON_MAX_TOKENS") {
+        return yield* failWith(`stopReason cannot be treated as success: ${self.stopReason || "(none)"}`);
+      }
+      const toolArgumentErrors: Record<string, string> = {};
+      if (self.calls.size > 0) {
+        self.message.toolCalls = [...self.calls.values()];
+        for (const call of self.message.toolCalls) {
+          yield* requiredString(call.name, "tool name");
+          const error = self.serverArgumentErrors.has(call.id) ? `${SERVER_JSON_ERROR}\n\nReceived arguments:\n${call.argumentsJson}` : argumentsError(call);
+          if (error) toolArgumentErrors[call.id] = error;
+        }
+      }
+      if (self.stopReason === "STOP_REASON_FUNCTION_CALL" && !self.calls.size) {
+        return yield* failWith("The response ended with FUNCTION_CALL but has no tool call.");
+      }
+      self.message.messageId ||= randomUUID();
+      return {
+        message: self.message,
+        stopReason: self.stopReason,
+        usage: self.usage,
+        usageReported: self.usageReported,
+        frameCount: self.frameCount,
+        stopFrameIndex: self.stopFrameIndex,
+        lastUsageFrameIndex: self.lastUsageFrameIndex,
+        idlessToolDeltaCount: self.idlessToolDeltaCount,
+        toolArgumentErrors,
+        durationMs: Math.round(performance.now() - self.startedAt),
+        firstDeltaMs: self.firstDeltaMs === undefined ? undefined : Math.round(self.firstDeltaMs),
+        actualModelUid: self.actualModelUid,
+        ...(self.usageModelUid ? { usageModelUid: self.usageModelUid } : {}),
+      };
+    });
+  }
+}

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