@buyong/pi-devin 0.1.4 → 0.1.6

package/src/pi/features/catalog/restore.ts

@@ -0,0 +1,53 @@
+import type { ModelsStoreEntry } from "@earendil-works/pi-ai";
+import { Effect, Predicate } from "effect";
+import { restoreModelVariants, type VariantProjection } from "../../../core/models/variants.ts";
+import type { Credential, JsonObject } from "../../../core/types.ts";
+import { CATALOG_VERSION, DEVIN_API } from "./constants.ts";
+import { catalogScope } from "./projection.ts";
+import type { DevinModel } from "./types.ts";
+
+const ACCOUNT_HASH = /^[a-f0-9]{64}$/;
+export interface RestoredCatalog { projection: VariantProjection; account?: string; isSameSession: boolean }
+
+/** Every stored entry's configs when the whole store belongs to one scope and one account; anything mixed or edited is ignored. */
+function storedConfigs(stored: Readonly<ModelsStoreEntry>, credential: Credential): { configs: JsonObject[]; scope: unknown; account: unknown } | undefined {
+  const configs = new Map<string, JsonObject>();
+  let storedScope: unknown, storedAccount: unknown;
+  for (const [index, model] of stored.models.entries()) {
+    const metadata = (model as DevinModel).devin as unknown;
+    if (!Predicate.isObject(metadata)) return undefined;
+    if ((model.type !== undefined && model.type !== "chat") || model.provider !== "devin" || model.api !== DEVIN_API || model.baseUrl !== credential.apiServerURL
+      || metadata.version !== CATALOG_VERSION || !Predicate.isString(metadata.scope)) return undefined;
+    if (metadata.account !== undefined && (!Predicate.isString(metadata.account) || !ACCOUNT_HASH.test(metadata.account))) return undefined;
+    if (index === 0) { storedScope = metadata.scope; storedAccount = metadata.account; }
+    else if (metadata.scope !== storedScope || metadata.account !== storedAccount) return undefined;
+    if (!Array.isArray(metadata.configs)) return undefined;
+    for (const value of [...metadata.configs, ...(Array.isArray(metadata.unavailable) ? metadata.unavailable : [])]) {
+      if (!Predicate.isObject(value) || !Predicate.isString(value.modelUid)) return undefined;
+      const config = value as JsonObject;
+      const previous = configs.get(value.modelUid);
+      if (previous && JSON.stringify(previous) !== JSON.stringify(config)) return undefined;
+      configs.set(value.modelUid, config);
+    }
+  }
+  return { configs: [...configs.values()], scope: storedScope, account: storedAccount };
+}
+
+/**
+ * Restores the stored catalog of the same session, or of an earlier session of an account this process verified for `account`.
+ * Every entry must share one scope and one account, so a mixed or edited cache is never partly applied. A bad cache yields none.
+ */
+export function restoredCatalog(stored: Readonly<ModelsStoreEntry> | undefined, credential: Credential, account: string | undefined): Effect.Effect<RestoredCatalog | undefined> {
+  return Effect.suspend(() => {
+    if (!stored?.models.length) return Effect.succeed(undefined);
+    const entries = storedConfigs(stored, credential);
+    if (!entries) return Effect.succeed(undefined);
+    const isSameSession = entries.scope === catalogScope(credential);
+    // Another session's catalog is used only for the same verified account; account changes and logout never expose it.
+    if (!isSameSession && (account === undefined || entries.account !== account)) return Effect.succeed(undefined);
+    return restoreModelVariants(entries.configs).pipe(
+      Effect.map((projection): RestoredCatalog | undefined => ({ projection, account: account ?? entries.account as string | undefined, isSameSession })),
+      Effect.orElseSucceed(() => undefined),
+    );
+  });
+}

package/src/pi/features/catalog/service.ts

@@ -0,0 +1,158 @@
+import type { Credential as HostCredential, ModelsPublication, RefreshModelsContext } from "@earendil-works/pi-ai";
+import { Context, Effect, Layer } from "effect";
+import { abortWith } from "../../../core/cancellation.ts";
+import { toDevinFailure } from "../../../core/errors.ts";
+import { modelIDForUID, projectModelVariants, resolveBackendSelection, type VariantProjection } from "../../../core/models/variants.ts";
+import { endpoint } from "../../../core/protocol/endpoint.ts";
+import type { Credential } from "../../../core/types.ts";
+import { failWith } from "../../../core/validation.ts";
+import { ExtensionConfig } from "../../app/config.ts";
+import { Accounts } from "../accounts/service.ts";
+import { CredentialGuard } from "../auth/guard.ts";
+import { AuthState } from "../auth/state.ts";
+import { ProviderLifetime } from "../lifetime/service.ts";
+import { DisplaySettings, FusionSettings } from "../settings/service.ts";
+import { UsageChanges } from "../usage/changes.ts";
+import { DEVIN_API, isFusionModelID } from "./constants.ts";
+import { fusionChoices } from "./fusion.ts";
+import { isUsable, publicModelIDs } from "./ids.ts";
+import { catalogScope, modelsFromProjection } from "./projection.ts";
+import { RemoteCatalog } from "./remote.ts";
+import { restoredCatalog } from "./restore.ts";
+import type { DevinModel, ModelCatalogShape } from "./types.ts";
+
+const FRESHNESS_MS = 5 * 60_000;
+
+/**
+ * The only owner of the catalog query: when to look it up, what to restore from Pi's model store, and the list Pi shows.
+ * State changes only inside a publication Pi accepted, so a cancelled or rejected refresh never changes the list.
+ */
+export class ModelCatalog extends Context.Service<ModelCatalog, ModelCatalogShape>()("pi-devin/ModelCatalog") {}
+
+const publish = (context: RefreshModelsContext, publication: ModelsPublication) =>
+  Effect.tryPromise({ try: () => context.publish(publication), catch: toDevinFailure });
+
+export const ModelCatalogLive = Layer.effect(ModelCatalog, Effect.gen(function* () {
+  const config = yield* ExtensionConfig;
+  const auth = yield* AuthState;
+  const guard = yield* CredentialGuard;
+  const accounts = yield* Accounts;
+  const remote = yield* RemoteCatalog;
+  const fusionSettings = yield* FusionSettings;
+  const displaySettings = yield* DisplaySettings;
+  const changes = yield* UsageChanges;
+  const lifetime = yield* ProviderLifetime;
+  const now = config.now;
+
+  // The stored list is shared by every Pi process that uses the lead's agent directory. Only the default list is stored,
+  // without display filters or the sidekick-only exact list. It still holds every catalog config, so each process rebuilds its own list after restore.
+  const build = (next: VariantProjection, credential: Credential, account: string | undefined, isForStorage = false) => Effect.gen(function* () {
+    const fusion = config.isFusionChild ? false : yield* fusionSettings.read;
+    const recommendedOnly = !isForStorage && !config.isFusionChild && (yield* displaySettings.read).recommendedOnly;
+    return modelsFromProjection(next, credential, { fusion, recommendedOnly, listsAllExactModels: !isForStorage && config.isFusionChild, account });
+  });
+  let models: DevinModel[] = [], projection: VariantProjection | undefined, scope: string | undefined, catalogAccount: string | undefined;
+  let checkedAtMs = 0, endpointOverride: string | undefined, modelCredential: Credential | undefined, credentialScope: string | undefined;
+  const clear = () => {
+    models = []; projection = undefined; scope = undefined; catalogAccount = undefined; checkedAtMs = 0; modelCredential = undefined; credentialScope = undefined;
+  };
+  const currentProjection = (credential: Credential) => !projection || scope !== catalogScope(credential)
+    ? failWith("No Devin model list matches the current account and endpoint. Refresh the model list.") : Effect.succeed(projection);
+  const fromHost = (credential: HostCredential | undefined) => credential?.type === "oauth" ? auth.fromHost(credential) : Effect.succeed(undefined);
+  const effectiveCredential = (credential: HostCredential | undefined, baseUrl?: string) => Effect.flatMap(fromHost(credential), (resolved) => resolved
+    ? Effect.map(endpoint(baseUrl ?? resolved.apiServerURL), (apiServerURL): Credential | undefined => ({ ...resolved, apiServerURL })) : Effect.succeed(undefined));
+  const accountOf = (credential: Credential) => Effect.map(accounts.get(credential), (record) => record?.ownerHash);
+
+  /** Only a confirmed 401 of the same sign-in generation invalidates the credential. */
+  const fetchCatalog = (credential: Credential) => Effect.gen(function* () {
+    const generation = yield* auth.generation;
+    yield* auth.assertUsable(credential);
+    return yield* remote.fetch(credential).pipe(Effect.tapError((error) => guard.reportFailure(credential, error, generation)));
+  });
+
+  const refresh = (context: RefreshModelsContext) => Effect.gen(function* () {
+    const credential = yield* effectiveCredential(context.credential, context.baseUrl);
+    if (!credential) {
+      yield* publish(context, { update: clear });
+      return;
+    }
+    const expectedScope = catalogScope(credential);
+    // A bad cache is never used as run data, whatever is wrong with it. The current good state is kept.
+    const restored = yield* restoredCatalog(context.stored, credential, yield* accountOf(credential)).pipe(Effect.catchCause(() => Effect.succeed(undefined)));
+    if (restored && (scope !== expectedScope || !projection || (context.stored?.checkedAt ?? 0) > checkedAtMs)) {
+      const { projection: restoredProjection, account: restoredAccount, isSameSession } = restored;
+      const restoredModels = yield* build(restoredProjection, credential, restoredAccount);
+      const checkedAt = context.stored?.checkedAt;
+      const restoredAtMs = typeof checkedAt === "number" && Number.isFinite(checkedAt) && checkedAt >= 0 && checkedAt <= now() ? checkedAt : 0;
+      const accepted = yield* publish(context, {
+        // A catalog reused for a new session of the same account is stored under the new session, so a restart restores it too.
+        ...(isSameSession ? {} : { persist: { models: yield* build(restoredProjection, credential, restoredAccount, true), checkedAt: restoredAtMs } }),
+        update: () => {
+          projection = restoredProjection; models = restoredModels; scope = expectedScope; catalogAccount = restoredAccount; modelCredential = credential;
+          checkedAtMs = restoredAtMs; endpointOverride = context.baseUrl; credentialScope = expectedScope;
+        },
+      });
+      if (!accepted) return;
+    } else if (scope !== expectedScope || endpointOverride !== context.baseUrl || credentialScope !== expectedScope) {
+      const accepted = yield* publish(context, { update: () => {
+        if (scope !== expectedScope || endpointOverride !== context.baseUrl) clear();
+        endpointOverride = context.baseUrl; credentialScope = expectedScope;
+      } });
+      if (!accepted) return;
+    }
+    if (!context.allowNetwork) return;
+    const ageMs = now() - checkedAtMs;
+    if (!context.force && scope === expectedScope && projection && checkedAtMs > 0 && ageMs >= 0 && ageMs < FRESHNESS_MS) return;
+    const catalog = yield* fetchCatalog(credential);
+    const nextProjection = yield* projectModelVariants(catalog);
+    // Known after an account check in this process, or carried over from this same session's catalog.
+    const nextAccount = (yield* accountOf(credential)) ?? (scope === expectedScope ? catalogAccount : undefined);
+    const nextModels = yield* build(nextProjection, credential, nextAccount);
+    const checkedAt = now();
+    if (!Number.isSafeInteger(checkedAt) || checkedAt < 0) return yield* failWith("Invalid model cache check time.");
+    yield* publish(context, {
+      persist: { models: yield* build(nextProjection, credential, nextAccount, true), checkedAt },
+      update: () => {
+        projection = nextProjection; models = nextModels; scope = expectedScope; catalogAccount = nextAccount; modelCredential = credential;
+        checkedAtMs = checkedAt; endpointOverride = context.baseUrl; credentialScope = expectedScope;
+      },
+    });
+  });
+
+  return {
+    models: Effect.sync(() => models),
+    unsupported: Effect.sync(() => projection?.unsupported ?? []),
+    exactLevel: (uid) => Effect.sync(() => projection?.variants.find((variant) => variant.model.id === uid && isUsable(variant))?.level),
+    fusionChoices: Effect.sync(() => projection && !config.isFusionChild ? fusionChoices(projection) : undefined),
+    rebuild: Effect.suspend(() => projection && modelCredential
+      ? Effect.map(build(projection, modelCredential, catalogAccount), (next) => { models = next; }) : Effect.void),
+    currentScope: Effect.sync(() => credentialScope),
+    invalidate: Effect.sync(clear),
+    filter: (candidates, credential) => Effect.map(effectiveCredential(credential, endpointOverride), (resolved) => {
+      if (!resolved) return [];
+      const expected = catalogScope(resolved);
+      return candidates.filter((model) => model.provider === "devin" && model.api === DEVIN_API && model.baseUrl === resolved.apiServerURL && (model as DevinModel).devin?.scope === expected);
+    }).pipe(Effect.catchCause(() => Effect.succeed([]))),
+    // Sign-in, logout and restores change the current credential, which decides whose quota is shown.
+    refresh: (context) => Effect.flatMap(lifetime.current, (current) => current.guard(refresh(context)).pipe(abortWith(context.signal), Effect.ensuring(changes.publish))),
+    resolve: (modelID, level, credential) => Effect.gen(function* () {
+      const current = yield* currentProjection(credential);
+      let wanted = modelID;
+      if (isFusionModelID(modelID)) {
+        // Fusion lead requests use the same UID and thinking level as the selected lead group.
+        const fusion = models.find((model) => model.id === modelID)?.devin.fusion;
+        if (!fusion) return yield* failWith(`Fusion model unavailable: ${modelID}`);
+        wanted = fusion.leadID;
+      }
+      const target = publicModelIDs(current).targets.get(wanted);
+      if (!target) return yield* failWith(`Model or thinking level unavailable: ${modelID} (${level})`);
+      return yield* resolveBackendSelection(current, "group" in target ? target.group.id : modelIDForUID(target.variant.model.id), level);
+    }),
+    resolveUID: (uid, credential) => Effect.gen(function* () {
+      const current = yield* currentProjection(credential);
+      const level = current.variants.find((variant) => variant.model.id === uid && isUsable(variant))?.level;
+      if (!level) return yield* failWith(`Model UID unavailable: ${uid}`);
+      return yield* resolveBackendSelection(current, modelIDForUID(uid), level);
+    }),
+  } satisfies ModelCatalogShape;
+}));

package/src/pi/features/catalog/types.ts

@@ -0,0 +1,56 @@
+import type { Credential as HostCredential, Model, RefreshModelsContext } from "@earendil-works/pi-ai";
+import type { Effect } from "effect";
+import type { DevinError, DevinFailure } from "../../../core/errors.ts";
+import type { ModelCatalog as Catalog } from "../../../core/models/catalog.ts";
+import type { BackendModelSelection, EffectiveThinkingLevel } from "../../../core/models/variants.ts";
+import type { Credential, JsonObject } from "../../../core/types.ts";
+
+/** The Pi model API this provider registers. Duplicated as a literal type so type modules stay free of runtime imports. */
+export type DevinAPI = "devin-connect";
+
+/** The lead is a published group model ID; the sidekick is an exact variant model ID. Both come from `publicModelIDs`. */
+export interface FusionSelection { leadID: string; sidekickID: string }
+export interface FusionChoices {
+  leads: { id: string; name: string; recommended?: true }[];
+  /** `level` is the thinking level of this UID. It is passed to the sidekick child Pi as is. */
+  sidekicks: { id: string; name: string; groupName: string; level: EffectiveThinkingLevel; recommended?: true }[];
+}
+
+export interface DevinModel extends Model<DevinAPI> {
+  devin: {
+    version: number; scope: string; costsUnknown: true; configs: JsonObject[]; unavailable?: JsonObject[];
+    fusion?: FusionSelection;
+    /** Marked as recommended by the catalog. For a group, true when any variant is recommended. */
+    recommended?: true;
+    /** Account identity hash (endpoint and user ID) the catalog belongs to. Lets a new session of the same account reuse it. */
+    account?: string;
+  };
+}
+
+/** One remote catalog lookup for a credential, with the team's model policy applied. */
+export interface RemoteCatalogShape {
+  readonly fetch: (credential: Credential) => Effect.Effect<Catalog, DevinFailure>;
+}
+
+export interface ModelCatalogShape {
+  /** The current Pi model list. Makes no request. */
+  readonly models: Effect.Effect<readonly DevinModel[]>;
+  /** The given Pi models that belong to the credential's catalog scope. Never fails. */
+  readonly filter: (models: readonly Model<DevinAPI>[], credential: HostCredential | undefined) => Effect.Effect<readonly Model<DevinAPI>[]>;
+  /** Restores or refreshes the list for Pi's current credential. Stops with the provider lifetime and Pi's signal. */
+  readonly refresh: (context: RefreshModelsContext) => Effect.Effect<void, DevinFailure>;
+  readonly resolve: (modelID: string, level: EffectiveThinkingLevel, credential: Credential) => Effect.Effect<BackendModelSelection, DevinError>;
+  /** Resolves a catalog UID chosen by a payload hook at that variant's thinking level, including UIDs hidden from the list. */
+  readonly resolveUID: (uid: string, credential: Credential) => Effect.Effect<BackendModelSelection, DevinError>;
+  readonly unsupported: Effect.Effect<readonly { uid: string; reason: string }[]>;
+  /** Thinking level of a usable exact UID in the current catalog, including hidden ones. */
+  readonly exactLevel: (uid: string) => Effect.Effect<EffectiveThinkingLevel | undefined>;
+  /** Fusion candidates of the current catalog. Undefined without a catalog or in the sidekick child. */
+  readonly fusionChoices: Effect.Effect<FusionChoices | undefined>;
+  /** Rebuilds the list from the current catalog without network after a saved choice or setting changes. */
+  readonly rebuild: Effect.Effect<void>;
+  /** Scope of the credential seen by the last refresh, even before its catalog loads. Undefined after logout or sign-in. */
+  readonly currentScope: Effect.Effect<string | undefined>;
+  /** Forgets the list, for example after a new sign-in. */
+  readonly invalidate: Effect.Effect<void>;
+}

package/src/pi/features/clients/service.ts

@@ -0,0 +1,47 @@
+import { Context, Effect, Layer } from "effect";
+import { makeDevinClient, type DevinClient } from "../../../core/client.ts";
+import { makeFingerprintProvider, type FingerprintProvider } from "../../../core/protocol/fingerprint.ts";
+import { DeviceIdentitySource } from "../../../core/services/device-identity.ts";
+import { fetchTransport, HttpTransport } from "../../../core/services/http-transport.ts";
+import type { Credential } from "../../../core/types.ts";
+import { evictOldest } from "../bounded.ts";
+import { catalogScope } from "../catalog/projection.ts";
+import type { DevinClientsShape } from "./types.ts";
+
+/**
+ * Clients of one provider. A credential's device fingerprint is collected once and shared by its clients;
+ * every open client is tracked so shutdown can stop in-flight requests. Each client still has its own connection pool.
+ */
+export class DevinClients extends Context.Service<DevinClients, DevinClientsShape>()("pi-devin/DevinClients") {}
+
+export const DevinClientsLive = Layer.effect(DevinClients, Effect.gen(function* () {
+  const transport = yield* HttpTransport;
+  const device = yield* DeviceIdentitySource;
+  const fingerprints = new Map<string, FingerprintProvider>();
+  const clients = new Set<DevinClient>();
+
+  const fingerprintFor = (credential: Credential) => Effect.suspend(() => {
+    const key = catalogScope(credential);
+    const cached = fingerprints.get(key);
+    if (cached) return Effect.succeed(cached);
+    evictOldest(fingerprints, 16);
+    return Effect.tap(makeFingerprintProvider(credential.sessionToken, { collectIdentity: device.collect }), (created) => Effect.sync(() => {
+      fingerprints.set(key, created);
+    }));
+  });
+
+  return {
+    open: (credential, options = {}) => Effect.gen(function* () {
+      const { fetch, ...clientOptions } = options;
+      const client = yield* makeDevinClient(credential, { ...clientOptions, fingerprint: yield* fingerprintFor(credential) }).pipe(
+        Effect.provideService(HttpTransport, fetch ? fetchTransport(fetch) : transport),
+        Effect.provideService(DeviceIdentitySource, device),
+      );
+      clients.add(client);
+      yield* Effect.addFinalizer(() => Effect.sync(() => { clients.delete(client); }));
+      return client;
+    }),
+    closeAll: Effect.suspend(() => Effect.forEach([...clients], (client) => client.close, { discard: true })),
+    clearFingerprints: Effect.sync(() => fingerprints.clear()),
+  } satisfies DevinClientsShape;
+}));

package/src/pi/features/clients/types.ts

@@ -0,0 +1,22 @@
+import type { Effect, Scope } from "effect";
+import type { DevinClient, MetadataProfile } from "../../../core/client.ts";
+import type { DevinError } from "../../../core/errors.ts";
+import type { ConnectClientOptions } from "../../../core/protocol/connect-client.ts";
+import type { Credential } from "../../../core/types.ts";
+
+export interface ClientOptions {
+  profile?: MetadataProfile;
+  /** Pi's per-request fetch. Replaces the provider's transport for this client only. */
+  fetch?: typeof fetch;
+  timeoutMs?: number;
+  onRequest?: ConnectClientOptions["onRequest"];
+}
+
+export interface DevinClientsShape {
+  /** A client for the calling scope. Shares the credential's device fingerprint and closes with the scope. */
+  readonly open: (credential: Credential, options?: ClientOptions) => Effect.Effect<DevinClient, DevinError, Scope.Scope>;
+  /** Closes every open client; their in-flight requests fail as closed. */
+  readonly closeAll: Effect.Effect<void>;
+  /** Forgets the per-credential fingerprints, so later clients collect device values again. */
+  readonly clearFingerprints: Effect.Effect<void>;
+}

package/src/pi/features/default-scheduler.ts

@@ -0,0 +1,12 @@
+import { Context, Effect, Scheduler } from "effect";
+
+/** Effect's process-wide default scheduler, the one `Effect.runFork` and `runPromise` use. */
+const defaultScheduler = Context.get(Context.empty(), Scheduler.Scheduler);
+
+/**
+ * Runs work that outlives the Pi call that started it on Effect's default scheduler. A fiber forked inside `runSync`, or by a
+ * runner captured while `runSync` built the layers, inherits that call's synchronous scheduler, which yields through microtasks:
+ * a long burst would then keep timers, I/O and user input waiting until it ends, instead of yielding to them every 2048 operations.
+ */
+export const onDefaultScheduler = <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
+  Effect.provideService(effect, Scheduler.Scheduler, defaultScheduler);

package/src/pi/features/inference/request.ts

@@ -0,0 +1,190 @@
+import { clampThinkingLevel, type AssistantMessageEventStream, type Model, type SimpleStreamOptions, type TranscriptContext } from "@earendil-works/pi-ai";
+import { Cause, Effect, Stream } from "effect";
+import { assertCanInfer } from "../../../core/auth/access.ts";
+import { abortWith } from "../../../core/cancellation.ts";
+import { Cancelled, isTransientConnectionFailure, RPCError, toDevinFailure, type DevinFailure } from "../../../core/errors.ts";
+import { ChatAccumulator } from "../../../core/inference/accumulator.ts";
+import { chatRequest } from "../../../core/inference/request.ts";
+import type { BackendModelSelection, EffectiveThinkingLevel } from "../../../core/models/variants.ts";
+import { endpoint } from "../../../core/protocol/endpoint.ts";
+import { CHAT_METHOD } from "../../../core/protocol/protobuf.ts";
+import { safeError } from "../../../core/redaction.ts";
+import type { Credential, JsonObject } from "../../../core/types.ts";
+import { failWith, object, requiredString, tokenCount } from "../../../core/validation.ts";
+import { DevinResponseStream } from "../../adapters/pi/response-stream.ts";
+import { toDevinTranscript } from "../../adapters/pi/transcript.ts";
+import type { AccountsShape } from "../accounts/types.ts";
+import type { AuthStateShape, CredentialGuardShape } from "../auth/types.ts";
+import { isFusionModelID } from "../catalog/constants.ts";
+import { hasExtendedPromptCacheRetention } from "../catalog/projection.ts";
+import type { DevinAPI, ModelCatalogShape } from "../catalog/types.ts";
+import type { DevinClientsShape } from "../clients/types.ts";
+import type { ProviderLifetimeShape } from "../lifetime/types.ts";
+import type { DevinLifecycle } from "../runs/lifecycle.ts";
+import { FUSION_LEAD_GUIDANCE } from "../sidekick/prompts.ts";
+
+/** Services one request uses, resolved once when the inference service is built. */
+export interface InferenceDependencies {
+  auth: AuthStateShape;
+  guard: CredentialGuardShape;
+  catalog: ModelCatalogShape;
+  accounts: AccountsShape;
+  clients: DevinClientsShape;
+  runs: DevinLifecycle;
+  lifetime: ProviderLifetimeShape;
+}
+
+/** One provider call: Pi's event stream, returned at once, and the request that feeds it. */
+export interface InferenceRequest {
+  stream: AssistantMessageEventStream;
+  /** Never fails: every ending closes the stream with exactly one terminal event. */
+  run: Effect.Effect<void>;
+}
+
+/** Connect codes of passing server trouble, in the words Pi's host retry matches. */
+const CONNECT_RETRY_LABELS: Readonly<Record<string, string>> = {
+  resource_exhausted: "Rate limit", internal: "Internal error", deadline_exceeded: "Request timed out",
+};
+
+/**
+ * Pi decides host retries from the message text alone. Node and Connect report failures as codes ("read ECONNRESET",
+ * "resource_exhausted: …") and an error body replaces the HTTP status, so the status or code is kept in words Pi matches.
+ * The original detail stays, so Pi's rules against retrying quota and billing errors still apply.
+ */
+function hostRetryableMessage(error: unknown, message: string): string {
+  if (isTransientConnectionFailure(error)) return `Connection error (${message})`;
+  if (!(error instanceof RPCError)) return message;
+  if (error.httpStatus !== undefined && error.httpStatus >= 400) return message.includes(String(error.httpStatus)) ? message : `HTTP ${error.httpStatus} (${message})`;
+  const label = CONNECT_RETRY_LABELS[error.code];
+  return label ? `${label} (${message})` : message;
+}
+
+/** Like Pi's built-in providers: the caller option wins; otherwise only PI_CACHE_RETENTION=long (provider env first) means long retention. */
+function resolveCacheRetention(options: SimpleStreamOptions): NonNullable<SimpleStreamOptions["cacheRetention"]> {
+  if (options.cacheRetention) return options.cacheRetention;
+  return (options.env?.PI_CACHE_RETENTION || process.env.PI_CACHE_RETENTION) === "long" ? "long" : "short";
+}
+
+/** A host hook may return a value or a promise and may throw; it is withdrawn when the request stops. */
+const hook = <A>(evaluate: () => A | PromiseLike<A>) => Effect.tryPromise({ try: async () => await evaluate(), catch: toDevinFailure });
+
+/**
+ * Prepares one request synchronously: the response stream (with its start event), the sign-in generation
+ * and the provider lifetime current at the call. The returned `run` sends the request and reports into the stream.
+ */
+export const prepareRequest = (deps: InferenceDependencies, model: Model<DevinAPI>, context: TranscriptContext, requestOptions: SimpleStreamOptions = {}): Effect.Effect<InferenceRequest> => Effect.gen(function* () {
+  const effectiveLevel = (requestOptions.reasoning ?? clampThinkingLevel(model, "off")) as EffectiveThinkingLevel;
+  const response = new DevinResponseStream(model, "");
+  const accumulator = new ChatAccumulator();
+  const generation = yield* deps.auth.generation;
+  const lifetime = yield* deps.lifetime.current;
+  let credential: Credential | undefined, actualUID = "", isRedacted = false;
+
+  const run = Effect.gen(function* () {
+    const current: Credential = {
+      version: 1, sessionToken: yield* requiredString(requestOptions.apiKey, "Devin account authentication (/login required)"),
+      apiServerURL: yield* endpoint(model.baseUrl), createdAt: new Date().toISOString(),
+    };
+    credential = current;
+    // Pi can override the OAuth value with an apiKey in models.json or a caller option. Only OAuth sessions are accepted.
+    yield* deps.auth.assertOAuthSession(current);
+    yield* deps.auth.assertUsable(current);
+    let selected = yield* deps.catalog.resolve(model.id, effectiveLevel, current);
+    actualUID = selected.uid;
+    response.message.providerThinkingLevel = actualUID;
+    // Retries belong to Pi and the only transport is a Connect stream, so `maxRetries` and `transport` preferences are ignored.
+    const cacheRetention = resolveCacheRetention(requestOptions);
+    const assertCacheRetention = (selection: BackendModelSelection) => cacheRetention === "long" && !hasExtendedPromptCacheRetention(selection.variant)
+      ? failWith("Long cache lifetime is not confirmed for this Devin model. Long retention is supported only for models whose catalog Prompt Cache Retention is 24h.")
+      : Effect.void;
+    yield* assertCacheRetention(selected);
+
+    // The per-request account check (permission and quota) runs here, outside Pi's shared credential lock.
+    const known = yield* deps.accounts.get(current);
+    yield* deps.accounts.check(current, {
+      expectedGeneration: generation,
+      connection: { fetch: requestOptions.fetch, timeoutMs: requestOptions.timeoutMs },
+      beforeRecord: deps.auth.assertUsable(current),
+    }).pipe(
+      Effect.flatMap((outcome) => outcome === "stale" ? Effect.fail(new Cancelled({ message: "The Devin authentication generation changed." })) : Effect.void),
+      // A check that cannot reach the server keeps the last known account; the model request reports its own failure.
+      Effect.catch((error) => known && isTransientConnectionFailure(error) ? Effect.void : Effect.fail(error)),
+    );
+    const account = yield* deps.accounts.get(current);
+    if (!account) return yield* failWith("The Devin account check was interrupted.");
+    yield* assertCanInfer(account.status);
+
+    const lease = yield* Effect.acquireRelease(deps.runs.acquire(account.ownerHash), (acquired) => acquired.release);
+    const transcript = yield* toDevinTranscript(context, selected.model);
+    if (isFusionModelID(model.id)) transcript.systemPrompt = [transcript.systemPrompt, FUSION_LEAD_GUIDANCE].filter(Boolean).join("\n\n");
+    const maximum = requestOptions.maxTokens === undefined ? selected.model.maxOutputTokens : yield* tokenCount(requestOptions.maxTokens, "maxTokens");
+    if (maximum < 1 || maximum > selected.model.maxOutputTokens) return yield* failWith("The output limit is outside the selected Devin model range.");
+    const client = yield* deps.clients.open(current, { fetch: requestOptions.fetch, timeoutMs: requestOptions.timeoutMs,
+      onRequest: (attempt) => attempt.isMetered ? lease.assertAttempt : Effect.void,
+    });
+    yield* lease.addCleanup(client.close);
+    const request = chatRequest({ metadata: yield* client.metadata(), model: selected.uid, ...transcript, maxTokens: maximum,
+      cascadeId: lease.cascadeId, trajectoryId: lease.trajectoryId, stepIndex: lease.stepIndex,
+      executionId: lease.executionId, clientSessionId: requestOptions.sessionId ?? lease.sessionId,
+      isAuxiliary: lease.isAuxiliary, isRecovery: lease.isRecovery, includeContext: false,
+    });
+    if (requestOptions.temperature !== undefined) {
+      if (!Number.isFinite(requestOptions.temperature) || requestOptions.temperature < 0) return yield* failWith("temperature must be a finite value of 0 or more.");
+      (yield* object(request.configuration, "configuration")).temperature = requestOptions.temperature;
+    }
+    if (cacheRetention === "none") for (const prompt of request.chatMessagePrompts as JsonObject[]) delete prompt.promptCacheOptions;
+    const identity = JSON.stringify([request.cascadeId, request.trajectoryReference, request.executionId, request.clientSessionId]);
+
+    const frames = client.transport.stream(CHAT_METHOD, request, {
+      headers: requestOptions.headers,
+      onPayload: (payload) => Effect.gen(function* () {
+        const replacement = requestOptions.onPayload ? yield* hook(() => requestOptions.onPayload!(payload, model)) : undefined;
+        const finalPayload = replacement === undefined ? payload : yield* object(replacement, "provider payload");
+        if (JSON.stringify([finalPayload.cascadeId, finalPayload.trajectoryReference, finalPayload.executionId, finalPayload.clientSessionId]) !== identity) {
+          return yield* failWith("A payload hook cannot change the owned run, session or step identifiers.");
+        }
+        actualUID = yield* requiredString(finalPayload.chatModelUid, "chatModelUid");
+        if (actualUID !== selected.uid) {
+          // An exact UID hidden from the list is re-resolved at that UID's level when the current catalog has it.
+          if (!(yield* deps.catalog.exactLevel(actualUID))) return yield* failWith("A payload hook selected an unavailable model UID.");
+          selected = yield* deps.catalog.resolveUID(actualUID, current);
+          yield* toDevinTranscript(context, selected.model); // A model change re-checks existing image and tool limits.
+          yield* assertCacheRetention(selected);
+        }
+        const outputLimit = yield* tokenCount((yield* object(finalPayload.configuration, "configuration")).maxTokens, "maxTokens");
+        if (outputLimit < 1 || outputLimit > selected.model.maxOutputTokens) return yield* failWith("The payload hook output limit is outside the model range.");
+        response.message.providerThinkingLevel = actualUID;
+        return finalPayload;
+      }),
+      onResponse: (info) => Effect.gen(function* () {
+        if (info.status === 401) yield* deps.guard.reportFailure(current, RPCError.make("unauthenticated", "HTTP 401", 401), generation);
+        if (requestOptions.onResponse) yield* hook(() => requestOptions.onResponse!(info, model));
+      }),
+      onFrame: (frame) => Effect.gen(function* () {
+        if (requestOptions.onProviderStreamEvent) yield* hook(() => requestOptions.onProviderStreamEvent!(structuredClone(frame.data), model));
+        if (frame.isEnd && frame.data.error) return; // Connect error classification belongs to the transport.
+        if (frame.data.redact === true) { isRedacted = true; yield* response.redact; }
+        yield* accumulator.accept(frame.data, frame.isEnd);
+        if (!frame.isEnd) yield* response.accept(frame.data, accumulator);
+      }),
+    });
+    yield* lease.cancellation.guard(Stream.runDrain(frames));
+    const result = yield* accumulator.finish;
+    result.message.modelUid = actualUID;
+    yield* response.finish(result);
+  });
+
+  // The scope encloses the failure report as well, so Pi sees the terminal event before the client closes and the lease lets the next request in.
+  const settled = Effect.scoped(lifetime.guard(run).pipe(
+    abortWith(requestOptions.signal),
+    // Every ending, including a defect, closes Pi's stream with exactly one terminal event.
+    Effect.catchCause((cause) => Effect.gen(function* () {
+      const error: DevinFailure = Cause.hasInterruptsOnly(cause) ? new Cancelled({ message: "The Devin request was interrupted." }) : toDevinFailure(Cause.squash(cause));
+      if (credential) yield* deps.guard.reportFailure(credential, error, generation);
+      accumulator.message.modelUid = actualUID || undefined;
+      yield* response.fail(hostRetryableMessage(error, safeError(error, credential ? [credential.sessionToken] : [])),
+        error.name === "AbortError", isRedacted ? undefined : accumulator.message);
+    })),
+  ));
+  return { stream: response.stream, run: settled };
+});

package/src/pi/features/inference/service.ts

@@ -0,0 +1,33 @@
+import { Context, Effect, FiberSet, Layer } from "effect";
+import { Accounts } from "../accounts/service.ts";
+import { CredentialGuard } from "../auth/guard.ts";
+import { AuthState } from "../auth/state.ts";
+import { ModelCatalog } from "../catalog/service.ts";
+import { DevinClients } from "../clients/service.ts";
+import { onDefaultScheduler } from "../default-scheduler.ts";
+import { ProviderLifetime } from "../lifetime/service.ts";
+import { Runs } from "../runs/service.ts";
+import { prepareRequest, type InferenceDependencies } from "./request.ts";
+import type { InferenceShape } from "./types.ts";
+
+/**
+ * Devin requests behind Pi's provider calls. Each request owns its scope (lease, request client) and runs in a fiber of this
+ * service, so it outlives the synchronous provider call that returned its stream. It stops through its own guards, never by Pi returning.
+ */
+export class Inference extends Context.Service<Inference, InferenceShape>()("pi-devin/Inference") {}
+
+export const InferenceLive = Layer.effect(Inference, Effect.gen(function* () {
+  const deps: InferenceDependencies = {
+    auth: yield* AuthState, guard: yield* CredentialGuard, catalog: yield* ModelCatalog, accounts: yield* Accounts,
+    clients: yield* DevinClients, runs: yield* Runs, lifetime: yield* ProviderLifetime,
+  };
+  const requests = yield* FiberSet.make<void, never>();
+  return {
+    start: (model, context, options) => Effect.gen(function* () {
+      const request = yield* prepareRequest(deps, model, context, options);
+      // Starts at once, as the previous synchronous prefix did: validation failures reach the stream before the call returns.
+      yield* FiberSet.run(requests, onDefaultScheduler(request.run), { startImmediately: true });
+      return request.stream;
+    }),
+  } satisfies InferenceShape;
+}));

package/src/pi/features/inference/types.ts

@@ -0,0 +1,11 @@
+import type { AssistantMessageEventStream, Model, SimpleStreamOptions, TranscriptContext } from "@earendil-works/pi-ai";
+import type { Effect } from "effect";
+import type { DevinAPI } from "../catalog/types.ts";
+
+export interface InferenceShape {
+  /**
+   * Returns Pi's event stream for one Devin request. Runs synchronously up to the first wait: the stream carries its
+   * start event, and the request already holds its sign-in generation and provider lifetime. The request runs on in a fiber the service owns.
+   */
+  readonly start: (model: Model<DevinAPI>, context: TranscriptContext, options?: SimpleStreamOptions) => Effect.Effect<AssistantMessageEventStream>;
+}

package/src/pi/features/lifetime/service.ts

@@ -0,0 +1,19 @@
+import { Context, Effect, Layer } from "effect";
+import { makeCancellation } from "../../../core/cancellation.ts";
+import type { ProviderLifetimeShape } from "./types.ts";
+
+/**
+ * How long the provider's work may run: from a session attach until shutdown. Shutdown ends it with a reason
+ * instead of interrupting fibers, so stopped requests report that reason. The next session attach starts a new one.
+ */
+export class ProviderLifetime extends Context.Service<ProviderLifetime, ProviderLifetimeShape>()("pi-devin/ProviderLifetime") {}
+
+export const ProviderLifetimeLive = Layer.sync(ProviderLifetime, () => {
+  let current = makeCancellation();
+  return {
+    current: Effect.sync(() => current),
+    isActive: Effect.sync(() => !current.isCancelled()),
+    end: (reason) => Effect.sync(() => current.cancelUnsafe(reason)),
+    renew: Effect.sync(() => { if (current.isCancelled()) current = makeCancellation(); }),
+  } satisfies ProviderLifetimeShape;
+});

package/src/pi/features/lifetime/types.ts

@@ -0,0 +1,13 @@
+import type { Effect } from "effect";
+import type { Cancellation } from "../../../core/cancellation.ts";
+import type { DevinFailure } from "../../../core/errors.ts";
+
+export interface ProviderLifetimeShape {
+  /** The lifetime current at the call. Work captures it when it starts, so a later session's lifetime never stops it. */
+  readonly current: Effect.Effect<Cancellation>;
+  readonly isActive: Effect.Effect<boolean>;
+  /** Ends the current lifetime; work guarded by it fails with this reason. */
+  readonly end: (reason: DevinFailure) => Effect.Effect<void>;
+  /** Starts a new lifetime when the current one has ended. */
+  readonly renew: Effect.Effect<void>;
+}