@buyong/pi-devin 0.1.5 → 0.1.6

package/src/core/cancellation.ts

@@ -0,0 +1,99 @@
+import { Deferred, Duration, Effect, Exit, type Scope } from "effect";
+import { RequestTimeout, toDevinFailure, type DevinFailure } from "./errors.ts";
+
+/**
+ * A one-shot stop switch that carries its reason. Interruption has no reason, so lifetimes such as a closed client,
+ * an invalidated login or an ended run fail the guarded work with the reason instead.
+ */
+export interface Cancellation {
+  /** Fails with the reason once cancelled; never succeeds. */
+  readonly await: Effect.Effect<never, DevinFailure>;
+  readonly isCancelled: () => boolean;
+  readonly reason: () => DevinFailure | undefined;
+  /** Cancels once; later reasons are ignored. Also usable from synchronous host callbacks. */
+  readonly cancelUnsafe: (reason: DevinFailure) => void;
+  readonly cancel: (reason: DevinFailure) => Effect.Effect<void>;
+  /** Stops the effect when cancelled and fails it with the reason. Already cancelled work does not start. */
+  readonly guard: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E | DevinFailure, R>;
+}
+
+export function makeCancellation(): Cancellation {
+  const deferred = Deferred.makeUnsafe<never, DevinFailure>();
+  let current: DevinFailure | undefined;
+  const cancelUnsafe = (reason: DevinFailure) => {
+    if (current) return;
+    current = reason;
+    Deferred.doneUnsafe(deferred, Exit.fail(reason));
+  };
+  return {
+    await: Deferred.await(deferred),
+    isCancelled: () => current !== undefined,
+    reason: () => current,
+    cancelUnsafe,
+    cancel: (reason) => Effect.sync(() => cancelUnsafe(reason)),
+    guard: (effect) => Effect.suspend(() => current ? Effect.fail(current) : Effect.raceFirst(effect, Deferred.await(deferred))),
+  };
+}
+
+/** Guards an effect with several cancellations; the first one wins. */
+export function guardAll(cancellations: readonly Cancellation[]) {
+  return <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E | DevinFailure, R> =>
+    cancellations.reduce<Effect.Effect<A, E | DevinFailure, R>>((guarded, cancellation) => cancellation.guard(guarded), effect);
+}
+
+/**
+ * Starts a deadline at once. The timer is registered before the guarded work runs any of its own code,
+ * so hooks that advance or block time cannot slip past it. The timer stops with the scope.
+ */
+export function startDeadline(timeoutMs: number, reason: () => DevinFailure = () => new RequestTimeout({ message: `The request exceeded the ${timeoutMs}ms timeout.` })): Effect.Effect<Cancellation, never, Scope.Scope> {
+  return Effect.gen(function* () {
+    const deadline = makeCancellation();
+    yield* Effect.forkScoped(Effect.sleep(Duration.millis(timeoutMs)).pipe(Effect.andThen(deadline.cancel(reason()))), { startImmediately: true });
+    return deadline;
+  });
+}
+
+/** A deadline that restarts whenever data arrives. */
+export interface IdleDeadline extends Cancellation {
+  /** Restarts the wait. Has no effect once the deadline has passed. */
+  readonly touch: Effect.Effect<void>;
+}
+
+/**
+ * Starts an idle deadline at once: it passes only when nothing arrives for `timeoutMs`, so a long response that keeps
+ * streaming is not cut off. Like `startDeadline`, the timer exists before the guarded work runs. It stops with the scope.
+ */
+export function startIdleDeadline(timeoutMs: number, reason: () => DevinFailure = () => new RequestTimeout({ message: `The request received no data for ${timeoutMs}ms.` })): Effect.Effect<IdleDeadline, never, Scope.Scope> {
+  return Effect.gen(function* () {
+    const deadline = makeCancellation();
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const arm = () => {
+      clearTimeout(timer);
+      if (!deadline.isCancelled()) timer = setTimeout(() => deadline.cancelUnsafe(reason()), timeoutMs);
+    };
+    arm();
+    yield* Effect.addFinalizer(() => Effect.sync(() => clearTimeout(timer)));
+    return { ...deadline, touch: Effect.sync(arm) };
+  });
+}
+
+/** Fails with the signal's reason once it aborts; never succeeds. */
+export function whenAborted(signal: AbortSignal): Effect.Effect<never, DevinFailure> {
+  return Effect.callback<never, DevinFailure>((resume) => {
+    const onAbort = () => resume(Effect.fail(toDevinFailure(signal.reason)));
+    if (signal.aborted) { onAbort(); return; }
+    signal.addEventListener("abort", onAbort, { once: true });
+    return Effect.sync(() => signal.removeEventListener("abort", onAbort));
+  });
+}
+
+/**
+ * Bridges a host `AbortSignal`: the effect stops when it aborts and fails with the signal's reason,
+ * because hosts tell cancellation from a timeout by that reason.
+ */
+export function abortWith(signal: AbortSignal | undefined) {
+  return <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E | DevinFailure, R> => {
+    if (!signal) return effect;
+    return Effect.suspend(() => signal.aborted ? Effect.fail(toDevinFailure(signal.reason)) : Effect.raceFirst(effect, whenAborted(signal)));
+  };
+}

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";