@buyong/pi-devin 0.1.4 → 0.1.6

package/src/core/client.ts

@@ -1,9 +1,15 @@
-import { parseModelCatalog, type ModelCatalog } from "./models/catalog.ts";
 import { createHash } from "node:crypto";
-import { ConnectClient, ASSIGN_MODEL_METHOD, endpoint, type ConnectClientOptions } from "./protocol/transport.ts";
-import { createFingerprintProvider, type FingerprintProvider } from "./protocol/fingerprint.ts";
+import { Effect, Predicate, type Scope } from "effect";
+import type { DevinError, DevinFailure } from "./errors.ts";
 import { wireMessages } from "./inference/messages.ts";
-import { object, requiredString, type ChatMessage, type Credential, type JsonObject, type ModelInfo } from "./types.ts";
+import { parseModelCatalog, type ModelCatalog } from "./models/catalog.ts";
+import { ASSIGN_MODEL_METHOD, makeConnectClient, type ConnectClient, type ConnectClientOptions } from "./protocol/connect-client.ts";
+import { endpoint, isLoopbackHost } from "./protocol/endpoint.ts";
+import { makeFingerprintProvider, type FingerprintProvider } from "./protocol/fingerprint.ts";
+import { DeviceIdentitySource } from "./services/device-identity.ts";
+import type { HttpTransport } from "./services/http-transport.ts";
+import type { ChatMessage, Credential, JsonObject, ModelInfo } from "./types.ts";
+import { failWith, object, requiredString } from "./validation.ts";
 
 export const CLIENT_VERSION = "3000.11.92";
 export type MetadataProfile = "agent" | "standalone" | "login";
@@ -11,143 +17,142 @@ const MODEL_DISPLAYS = [
   "DISPLAY_OPTION_MODEL_ROUTER", "DISPLAY_OPTION_QUICK_REVIEW", "DISPLAY_OPTION_HIDDEN_TOOL",
   "DISPLAY_OPTION_WIRE_7", "DISPLAY_OPTION_MODERN_AGENT_CHAT",
 ];
+const STATUS_METHOD = "exa.seat_management_pb.SeatManagementService/GetUserStatus";
+const MODELS_METHOD = "exa.api_server_pb.ApiServerService/GetCliModelConfigs";
 
 export interface DevinClientOptions extends Omit<ConnectClientOptions, "baseURL" | "token"> {
   profile?: MetadataProfile;
   restBaseURL?: string;
+  /** A provider shared with other clients of the same credential. Otherwise this client collects device values once for itself. */
   fingerprint?: FingerprintProvider;
 }
 
-export class DevinClient {
+export interface StatusOptions {
+  /** Rejects a different signed-in user before anything else is sent. */
+  expectedUserId?: string;
+  profile?: MetadataProfile;
+}
+
+export interface DevinClient {
   readonly credential: Credential;
   readonly transport: ConnectClient;
   readonly profile: MetadataProfile;
   readonly fingerprint: FingerprintProvider;
-  defaultModelUid?: string;
-  accountIdentityHash?: string;
-  private organizationId?: string;
-  private restBaseURL: string;
-  private readonly hasExplicitRestURL: boolean;
-  constructor(credential: Credential, options: DevinClientOptions = {}) {
-    this.credential = credential;
-    const { profile, fingerprint, restBaseURL, ...transportOptions } = options;
-    const rpcOrigin = endpoint(credential.apiServerURL);
-    const isLoopback = ["localhost", "127.0.0.1", "[::1]"].includes(new URL(rpcOrigin).hostname);
-    this.hasExplicitRestURL = restBaseURL !== undefined;
-    this.restBaseURL = endpoint(restBaseURL ?? (isLoopback ? rpcOrigin : "https://api.devin.ai"));
-    this.profile = profile ?? "agent";
-    this.fingerprint = fingerprint ?? createFingerprintProvider(credential.sessionToken);
-    this.transport = new ConnectClient({ baseURL: credential.apiServerURL, token: credential.sessionToken, ...transportOptions });
-  }
-
-  metadata(options: { profile?: MetadataProfile; includeModelDisplays?: boolean } = {}): JsonObject {
-    const profile = options.profile ?? this.profile;
-    const version = profile === "standalone" ? "0.0.0-dev" : CLIENT_VERSION;
-    return {
-      apiKey: this.credential.sessionToken,
-      ideName: profile === "agent" ? "devin-cli" : "chisel",
-      ideVersion: version,
-      extensionName: "chisel",
-      extensionVersion: version,
-      locale: "en",
-      os: process.platform,
-      ...(profile === "agent" ? { ideType: "chisel" } : {}),
-      ...(options.includeModelDisplays ? { supportedModelDisplays: [...MODEL_DISPLAYS] } : {}),
-      f: this.fingerprint.create(),
-    };
-  }
+  /** Default model of the last fetched catalog. */
+  readonly defaultModelUid: Effect.Effect<string | undefined>;
+  /** Hash of the endpoint and user ID from the last status check. */
+  readonly accountIdentityHash: Effect.Effect<string | undefined>;
+  readonly close: Effect.Effect<void>;
+  metadata(options?: { profile?: MetadataProfile; includeModelDisplays?: boolean }): Effect.Effect<JsonObject, DevinError>;
+  status(options?: StatusOptions): Effect.Effect<JsonObject, DevinFailure>;
+  readonly catalog: Effect.Effect<ModelCatalog, DevinFailure>;
+  readonly models: Effect.Effect<ModelInfo[], DevinFailure>;
+  readonly teamSettings: Effect.Effect<JsonObject, DevinFailure>;
+  readonly managedPlugins: Effect.Effect<JsonObject, DevinFailure>;
+  assignModel(routerUid: string, cascadeId: string, message: ChatMessage | undefined): Effect.Effect<{ modelUid: string; assignmentJwt: string }, DevinFailure>;
+  readonly self: Effect.Effect<JsonObject, DevinFailure>;
+  readonly integrations: Effect.Effect<JsonObject | undefined, DevinFailure>;
+  analytics(events: readonly JsonObject[]): Effect.Effect<void, DevinFailure>;
+}
 
-  async status(signal?: AbortSignal, expectedUserId?: string, profile = this.profile): Promise<JsonObject> {
-    signal?.throwIfAborted();
-    const response = await this.transport.unary(
-      "exa.seat_management_pb.SeatManagementService/GetUserStatus", { metadata: this.metadata({ profile }) }, signal,
-    );
-    const user = object(response.userStatus, "userStatus");
-    if (expectedUserId && user.userId !== expectedUserId) {
-      throw new Error("The signed-in user ID differs from the requested account. Sign in again; no inference was run.");
-    }
-    const plan = object(user.planStatus ?? {}, "planStatus");
-    const info = object(plan.planInfo ?? {}, "planInfo");
-    const devin = object(info.devinInfo ?? {}, "devinInfo");
-    const userId = requiredString(user.userId, "userStatus.userId");
-    this.accountIdentityHash = createHash("sha256").update(`${this.transport.baseURL}\0${userId}`).digest("hex");
-    this.organizationId = typeof devin.orgId === "string" ? devin.orgId : undefined;
-    if (!this.hasExplicitRestURL && typeof devin.apiUrl === "string" && devin.apiUrl) {
-      const candidate = endpoint(devin.apiUrl);
-      if (candidate !== this.restBaseURL && candidate !== this.transport.baseURL) throw new Error("Unverified REST server. Specify it explicitly with --rest-server.");
-      this.restBaseURL = candidate;
-    }
-    const hasQuota = info.billingStrategy === "BILLING_STRATEGY_QUOTA";
-    // Name, email, organization ID and the raw response are not exposed.
-    return {
-      ...(expectedUserId ? { identityVerified: true } : {}),
-      teamsTier: user.teamsTier,
-      canUseCli: info.devinInfo ? devin.canUseCli === true : undefined,
-      billingStrategy: info.billingStrategy,
-      dailyQuotaRemainingPercent: plan.dailyQuotaRemainingPercent ?? (hasQuota ? 0 : undefined),
-      weeklyQuotaRemainingPercent: plan.weeklyQuotaRemainingPercent ?? (hasQuota ? 0 : undefined),
-      dailyQuotaResetAtUnix: plan.dailyQuotaResetAtUnix,
-      weeklyQuotaResetAtUnix: plan.weeklyQuotaResetAtUnix,
-    };
-  }
+/** A client for one credential. It closes with the scope, or earlier through `close`. */
+export function makeDevinClient(credential: Credential, options: DevinClientOptions = {}): Effect.Effect<DevinClient, DevinError, HttpTransport | DeviceIdentitySource | Scope.Scope> {
+  return Effect.gen(function* () {
+    const { profile = "agent", fingerprint: providedFingerprint, restBaseURL: explicitRestURL, ...transportOptions } = options;
+    const rpcOrigin = yield* endpoint(credential.apiServerURL);
+    const hasExplicitRestURL = explicitRestURL !== undefined;
+    let restBaseURL = yield* endpoint(explicitRestURL ?? (isLoopbackHost(new URL(rpcOrigin).hostname) ? rpcOrigin : "https://api.devin.ai"));
+    const device = yield* DeviceIdentitySource;
+    const fingerprint = providedFingerprint ?? (yield* makeFingerprintProvider(credential.sessionToken, { collectIdentity: device.collect }));
+    const transport = yield* makeConnectClient({ baseURL: credential.apiServerURL, token: credential.sessionToken, ...transportOptions });
+    let defaultModelUid: string | undefined, accountIdentityHash: string | undefined, organizationId: string | undefined;
 
-  async catalog(signal?: AbortSignal): Promise<ModelCatalog> {
-    signal?.throwIfAborted();
-    const response = await this.transport.unary(
-      "exa.api_server_pb.ApiServerService/GetCliModelConfigs", { metadata: this.metadata({ includeModelDisplays: true }) }, signal,
-    );
-    const catalog = parseModelCatalog(response);
-    this.defaultModelUid = catalog.defaultModelUid;
-    return catalog;
-  }
+    const metadata: DevinClient["metadata"] = (metadataOptions = {}) => Effect.map(fingerprint.create, (f) => {
+      const selected = metadataOptions.profile ?? profile;
+      const version = selected === "standalone" ? "0.0.0-dev" : CLIENT_VERSION;
+      return {
+        apiKey: credential.sessionToken,
+        ideName: selected === "agent" ? "devin-cli" : "chisel",
+        ideVersion: version,
+        extensionName: "chisel",
+        extensionVersion: version,
+        locale: "en",
+        os: process.platform,
+        ...(selected === "agent" ? { ideType: "chisel" } : {}),
+        ...(metadataOptions.includeModelDisplays ? { supportedModelDisplays: [...MODEL_DISPLAYS] } : {}),
+        f,
+      };
+    });
 
-  async models(signal?: AbortSignal): Promise<ModelInfo[]> {
-    return (await this.catalog(signal)).models;
-  }
+    const status: DevinClient["status"] = (statusOptions = {}) => Effect.gen(function* () {
+      const response = yield* transport.unary(STATUS_METHOD, { metadata: yield* metadata({ profile: statusOptions.profile }) });
+      const user = yield* object(response.userStatus, "userStatus");
+      if (statusOptions.expectedUserId && user.userId !== statusOptions.expectedUserId) {
+        return yield* failWith("The signed-in user ID differs from the requested account. Sign in again; no inference was run.");
+      }
+      const plan = yield* object(user.planStatus ?? {}, "planStatus");
+      const info = yield* object(plan.planInfo ?? {}, "planInfo");
+      const devin = yield* object(info.devinInfo ?? {}, "devinInfo");
+      const userId = yield* requiredString(user.userId, "userStatus.userId");
+      accountIdentityHash = createHash("sha256").update(`${transport.baseURL}\0${userId}`).digest("hex");
+      organizationId = Predicate.isString(devin.orgId) ? devin.orgId : undefined;
+      if (!hasExplicitRestURL && Predicate.isString(devin.apiUrl) && devin.apiUrl) {
+        const candidate = yield* endpoint(devin.apiUrl);
+        if (candidate !== restBaseURL && candidate !== transport.baseURL) return yield* failWith("Unverified REST server. Specify it explicitly with --rest-server.");
+        restBaseURL = candidate;
+      }
+      const hasQuota = info.billingStrategy === "BILLING_STRATEGY_QUOTA";
+      // Name, email, organization ID and the raw response are not exposed.
+      return {
+        ...(statusOptions.expectedUserId ? { identityVerified: true } : {}),
+        teamsTier: user.teamsTier,
+        canUseCli: info.devinInfo ? devin.canUseCli === true : undefined,
+        billingStrategy: info.billingStrategy,
+        dailyQuotaRemainingPercent: plan.dailyQuotaRemainingPercent ?? (hasQuota ? 0 : undefined),
+        weeklyQuotaRemainingPercent: plan.weeklyQuotaRemainingPercent ?? (hasQuota ? 0 : undefined),
+        dailyQuotaResetAtUnix: plan.dailyQuotaResetAtUnix,
+        weeklyQuotaResetAtUnix: plan.weeklyQuotaResetAtUnix,
+      };
+    });
 
-  async teamSettings(signal?: AbortSignal): Promise<JsonObject> {
-    signal?.throwIfAborted();
-    return this.transport.unary("exa.seat_management_pb.SeatManagementService/GetCliTeamSettings",
-      { metadata: this.metadata({ includeModelDisplays: true }) }, signal);
-  }
+    const catalog = Effect.gen(function* () {
+      const response = yield* transport.unary(MODELS_METHOD, { metadata: yield* metadata({ includeModelDisplays: true }) });
+      const parsed = yield* parseModelCatalog(response);
+      defaultModelUid = parsed.defaultModelUid;
+      return parsed;
+    });
 
-  async managedPlugins(signal?: AbortSignal): Promise<JsonObject> {
-    signal?.throwIfAborted();
-    // Only fetches the manifest. This does not mean installing a remote plugin or running its commands is approved.
-    return this.transport.unary("exa.api_server_pb.ApiServerService/GetAccountManagedPlugins", { metadata: this.metadata() }, signal);
-  }
+    const assignModel: DevinClient["assignModel"] = (routerUid, cascadeId, message) => Effect.gen(function* () {
+      const prompt = message ? wireMessages([message])[0] : undefined;
+      if (prompt) delete prompt.promptCacheOptions;
+      const response = yield* transport.unary(ASSIGN_MODEL_METHOD, {
+        metadata: yield* metadata(), modelRouterUid: routerUid, cascadeId, ...(prompt ? { chatMessagePrompt: prompt } : {}),
+      });
+      const assignment = yield* object(response.assignment, "assignment");
+      return {
+        modelUid: yield* requiredString(assignment.modelUid, "assignment.modelUid"),
+        assignmentJwt: message ? yield* requiredString(assignment.assignmentJwt, "assignment.assignmentJwt") : String(assignment.assignmentJwt ?? ""),
+      };
+    });
 
-  async assignModel(routerUid: string, cascadeId: string, message: ChatMessage | undefined, signal?: AbortSignal): Promise<{ modelUid: string; assignmentJwt: string }> {
-    signal?.throwIfAborted();
-    const prompt = message ? wireMessages([message])[0] : undefined;
-    if (prompt) delete prompt.promptCacheOptions;
-    const response = await this.transport.unary(ASSIGN_MODEL_METHOD, {
-      metadata: this.metadata(), modelRouterUid: routerUid, cascadeId, ...(prompt ? { chatMessagePrompt: prompt } : {}),
-    }, signal);
-    const assignment = object(response.assignment, "assignment");
     return {
-      modelUid: requiredString(assignment.modelUid, "assignment.modelUid"),
-      assignmentJwt: message ? requiredString(assignment.assignmentJwt, "assignment.assignmentJwt") : String(assignment.assignmentJwt ?? ""),
+      credential, transport, profile, fingerprint, metadata, status, catalog, assignModel,
+      close: transport.close,
+      defaultModelUid: Effect.sync(() => defaultModelUid),
+      accountIdentityHash: Effect.sync(() => accountIdentityHash),
+      models: Effect.map(catalog, (parsed) => parsed.models),
+      teamSettings: Effect.flatMap(metadata({ includeModelDisplays: true }), (value) =>
+        transport.unary("exa.seat_management_pb.SeatManagementService/GetCliTeamSettings", { metadata: value })),
+      // Only fetches the manifest. This does not mean installing a remote plugin or running its commands is approved.
+      managedPlugins: Effect.flatMap(metadata(), (value) => transport.unary("exa.api_server_pb.ApiServerService/GetAccountManagedPlugins", { metadata: value })),
+      self: Effect.suspend(() => transport.getJSON(restBaseURL, "/v3/self")),
+      integrations: Effect.suspend(() => organizationId
+        ? transport.getJSON(restBaseURL, `/v3/organizations/${encodeURIComponent(organizationId)}/integrations`) : Effect.succeed(undefined)),
+      analytics: (events) => events.length === 0 ? Effect.void : Effect.asVoid(transport.unary("exa.product_analytics_pb.ProductAnalyticsService/BatchRecordAnalyticsEvents", {
+        events: [...events], apiKey: credential.sessionToken,
+      })),
     };
-  }
-
-  async self(signal?: AbortSignal): Promise<JsonObject> {
-    return this.transport.getJSON(this.restBaseURL, "/v3/self", signal);
-  }
-
-  async integrations(signal?: AbortSignal): Promise<JsonObject | undefined> {
-    if (!this.organizationId) return undefined;
-    return this.transport.getJSON(this.restBaseURL, `/v3/organizations/${encodeURIComponent(this.organizationId)}/integrations`, signal);
-  }
-
-  async analytics(events: JsonObject[], signal?: AbortSignal): Promise<void> {
-    signal?.throwIfAborted();
-    if (events.length === 0) return;
-    await this.transport.unary("exa.product_analytics_pb.ProductAnalyticsService/BatchRecordAnalyticsEvents", {
-      events, apiKey: this.credential.sessionToken,
-    }, signal);
-  }
+  });
 }
 
-
 export { getModelByUID, selectModel } from "./models/select.ts";

package/src/core/errors.ts

@@ -0,0 +1,115 @@
+import { Data, Predicate } from "effect";
+
+/** A failure whose message is safe to show. `code` keeps a Node or library error code, such as `ECONNRESET`, for classification. */
+export class DevinError extends Data.TaggedError("DevinError")<{
+  readonly message: string;
+  readonly code?: string | undefined;
+}> {}
+
+/** Cancellation by the caller, the lifecycle or a closed client. Keeps the `AbortError` name hosts recognize. */
+export class Cancelled extends Data.TaggedError("Cancelled")<{ readonly message: string }> {
+  override get name(): string { return "AbortError"; }
+}
+
+/** A local deadline or a host timeout. Keeps the `TimeoutError` name hosts recognize. */
+export class RequestTimeout extends Data.TaggedError("RequestTimeout")<{ readonly message: string }> {
+  override get name(): string { return "TimeoutError"; }
+}
+
+export type RPCFailureKind = "authentication" | "permission" | "rate_limit" | "timeout" | "rpc";
+
+function rpcFailureKind(code: string, httpStatus: number | undefined): RPCFailureKind {
+  // An error body that contradicts the HTTP status does not invalidate authentication.
+  if (httpStatus !== undefined && httpStatus >= 400) {
+    if (httpStatus === 401) return "authentication";
+    if (httpStatus === 403) return "permission";
+    if (httpStatus === 429) return "rate_limit";
+    if (httpStatus === 408 || httpStatus === 504) return "timeout";
+    return "rpc";
+  }
+  if (code === "unauthenticated") return "authentication";
+  if (code === "permission_denied") return "permission";
+  if (code === "resource_exhausted") return "rate_limit";
+  if (code === "deadline_exceeded") return "timeout";
+  return "rpc";
+}
+
+const AUTHENTICATION_NOTICE = " The authentication credential is not valid. It may have expired or been revoked; sign in again with login.";
+
+/** An error the server reported over HTTP or Connect. `message` is already `code: detail`. */
+export class RPCError extends Data.TaggedError("RPCError")<{
+  readonly code: string;
+  readonly message: string;
+  readonly httpStatus?: number | undefined;
+  readonly retryAfterMs?: number | undefined;
+}> {
+  static make(code: string, detail: string, httpStatus?: number, retryAfterMs?: number): RPCError {
+    const message = `${code}: ${detail}`;
+    return new RPCError({
+      code, httpStatus, retryAfterMs,
+      message: rpcFailureKind(code, httpStatus) === "authentication" ? message.slice(0, 600) + AUTHENTICATION_NOTICE : message,
+    });
+  }
+
+  get kind(): RPCFailureKind { return rpcFailureKind(this.code, this.httpStatus); }
+}
+
+export type DevinFailure = DevinError | Cancelled | RequestTimeout | RPCError;
+
+const FAILURE_TAGS = new Set(["DevinError", "Cancelled", "RequestTimeout", "RPCError"]);
+
+export function isDevinFailure(value: unknown): value is DevinFailure {
+  return value instanceof Error && Predicate.hasProperty(value, "_tag") && FAILURE_TAGS.has(value._tag as string);
+}
+
+/** The Node error code of a failure or of its cause, used to tell network failures apart. */
+function errorCode(value: unknown): string | undefined {
+  if (Predicate.hasProperty(value, "code") && Predicate.isString(value.code)) return value.code;
+  const cause = value instanceof Error ? value.cause : undefined;
+  return Predicate.hasProperty(cause, "code") && Predicate.isString(cause.code) ? cause.code : undefined;
+}
+
+/** Turns anything thrown or rejected by foreign code, including abort reasons, into a typed failure. */
+export function toDevinFailure(cause: unknown): DevinFailure {
+  if (isDevinFailure(cause)) return cause;
+  const message = cause instanceof Error ? cause.message : String(cause);
+  const name = cause instanceof Error ? cause.name : undefined;
+  if (name === "AbortError") return new Cancelled({ message });
+  if (name === "TimeoutError") return new RequestTimeout({ message });
+  return new DevinError({ message, code: errorCode(cause) });
+}
+
+/** Like `toDevinFailure` for synchronous library calls that cannot be cancelled: always a `DevinError`. */
+export function toDevinError(cause: unknown): DevinError {
+  return cause instanceof DevinError ? cause : new DevinError({ message: cause instanceof Error ? cause.message : String(cause), code: errorCode(cause) });
+}
+
+export function isAuthenticationError(error: unknown): error is RPCError {
+  return error instanceof RPCError && error.kind === "authentication";
+}
+
+const NETWORK_CODES = /^(ECONN|ENET|EHOST|EPIPE$|ENOTFOUND$|EAI_|ETIMEDOUT$|ERR_TLS_|CERT_|DEPTH_ZERO_SELF_SIGNED_CERT$|SELF_SIGNED_CERT_IN_CHAIN$|UNABLE_TO_)/;
+const TRANSIENT_CONNECTION_CODES = /^(ECONNREFUSED|ECONNRESET|ECONNABORTED|EPIPE|ETIMEDOUT|EHOSTUNREACH|ENETUNREACH|ENETDOWN|ENOTFOUND|EAI_AGAIN|ERR_STREAM_PREMATURE_CLOSE)$/;
+
+/** Failure classification for reports. Never includes a message, token or identifier. */
+export function failureDetails(error: unknown): Record<string, unknown> {
+  const failure = toDevinFailure(error);
+  switch (failure._tag) {
+    case "RPCError": return {
+      category: failure.kind, code: failure.code,
+      ...(failure.httpStatus === undefined ? {} : { httpStatus: failure.httpStatus }),
+      ...(failure.retryAfterMs === undefined ? {} : { retryAfterMs: failure.retryAfterMs }),
+      ...(failure.kind === "authentication" ? { requiresLogin: true } : {}),
+    };
+    case "RequestTimeout": return { category: "timeout", code: "deadline_exceeded" };
+    case "Cancelled": return { category: "cancelled" };
+    case "DevinError": return failure.code !== undefined && NETWORK_CODES.test(failure.code) ? { category: "network", code: failure.code } : { category: "error" };
+  }
+}
+
+/** The request got no usable answer from a working server, so sending it again may succeed. TLS and certificate failures are not included. */
+export function isTransientConnectionFailure(error: unknown): boolean {
+  const failure = toDevinFailure(error);
+  if (failure instanceof RPCError) return failure.code === "unavailable" || [502, 503, 504].includes(failure.httpStatus ?? 0);
+  return failure instanceof DevinError && failure.code !== undefined && TRANSIENT_CONNECTION_CODES.test(failure.code);
+}

package/src/core/index.ts

@@ -1,12 +1,26 @@
-/** Host-independent API shared by the CLI and Pi. */
-export const CORE_CONTRACT_VERSION = 1;
+/**
+ * Host-independent API shared by the CLI and Pi. Version 2 returns Effect values instead of promises;
+ * version 3 takes the HTTP transport and device identity collection from services instead of options.
+ */
+export const CORE_CONTRACT_VERSION = 3;
 export * from "./types.ts";
+export * from "./errors.ts";
+export * from "./cancellation.ts";
+export * from "./validation.ts";
+export * from "./redaction.ts";
 export * from "./client.ts";
 export * from "./auth/index.ts";
 export * from "./models/catalog.ts";
-export * from "./inference/chat.ts";
+export * from "./inference/request.ts";
+export * from "./inference/accumulator.ts";
+export * from "./inference/stream-chat.ts";
 export * from "./inference/messages.ts";
 export * from "./inference/retry.ts";
 export * from "./inference/state.ts";
-export * from "./protocol/transport.ts";
+export * from "./protocol/connect-client.ts";
+export * from "./protocol/frames.ts";
+export * from "./protocol/endpoint.ts";
 export * from "./protocol/fingerprint.ts";
+export * from "./services/http-transport.ts";
+export * from "./services/device-identity.ts";
+export * from "./services/platform.ts";

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