@buyong/pi-devin 0.1.5 → 0.1.6

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

@@ -0,0 +1,45 @@
+import type { VariantProjection } from "../../../core/models/variants.ts";
+import { DEVIN_API, FUSION_SIDEKICK_UID } from "./constants.ts";
+import { byModelID, groupDisplayNames, isUsable, publicModelIDs, publishedVariants, type VariantGroup } from "./ids.ts";
+import type { DevinModel, FusionChoices, FusionSelection } from "./types.ts";
+
+/**
+ * Fusion candidates. The lead must call the sidekick tool and the sidekick works with Pi tools, so
+ * only models that support tool calls qualify. All variants of a published group share capabilities.
+ */
+export function fusionChoices(projection: VariantProjection): FusionChoices {
+  const names = groupDisplayNames(projection), ids = publicModelIDs(projection);
+  const leads = projection.groups.filter((group) => group.canPublish && publishedVariants(group)[0]?.model.supportsToolCalls)
+    .map((group) => ({ id: ids.groups.get(group.id)!, name: names.get(group.id)!,
+      ...(group.variants.some((variant) => variant.model.isRecommended) ? { recommended: true as const } : {}) }));
+  const groupOf = new Map<string, VariantGroup>();
+  for (const group of projection.groups) for (const variant of group.variants) groupOf.set(variant.model.id, group);
+  const sidekicks = projection.variants.filter((variant) => isUsable(variant) && variant.model.supportsToolCalls).sort(byModelID)
+    .map((variant) => {
+      const group = groupOf.get(variant.model.id);
+      return { id: ids.variants.get(variant.model.id)!, name: variant.model.name, groupName: group ? names.get(group.id)! : variant.model.name, level: variant.level!,
+        ...(variant.model.isRecommended ? { recommended: true as const } : {}) };
+    });
+  return { leads, sidekicks };
+}
+
+/** Saved values missing from the current list fall back to the defaults per item. Without defaults, no Fusion entry is built. */
+export function effectiveFusion(projection: VariantProjection, requested: FusionSelection | undefined): FusionSelection | undefined {
+  const { leads, sidekicks } = fusionChoices(projection), ids = publicModelIDs(projection);
+  const defaultSidekick = ids.variants.get(FUSION_SIDEKICK_UID);
+  const defaultGroup = projection.groups.find((group) => group.variants.some((variant) => variant.model.id === FUSION_SIDEKICK_UID));
+  const defaultLead = defaultGroup && ids.groups.get(defaultGroup.id);
+  // A choice saved in the legacy format (`family:…`, `uid:…`) is read as the same model's new ID.
+  const current = (id: string | undefined) => id?.startsWith("family:") ? ids.groups.get(id)
+    : id?.startsWith("uid:") ? ids.variants.get(decodeURIComponent(id.slice("uid:".length))) : id;
+  const pick = (options: readonly { id: string }[], wanted: string | undefined, fallback: string | undefined) =>
+    options.find((option) => option.id === current(wanted))?.id ?? options.find((option) => option.id === fallback)?.id;
+  const leadID = pick(leads, requested?.leadID, defaultLead), sidekickID = pick(sidekicks, requested?.sidekickID, defaultSidekick);
+  return leadID && sidekickID ? { leadID, sidekickID } : undefined;
+}
+
+/** The Fusion pair of the lead's model. The host may copy model objects in its settings layer, so the pair is looked up by ID in the current list. */
+export function fusionOf(models: readonly DevinModel[], model: { provider?: string; api?: string; id: string } | undefined): FusionSelection | undefined {
+  if (model?.provider !== "devin" || model.api !== DEVIN_API) return undefined;
+  return models.find((candidate) => candidate.id === model.id)?.devin.fusion;
+}

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

@@ -0,0 +1,79 @@
+import type { ModelVariant, VariantProjection } from "../../../core/models/variants.ts";
+import { FUSION_MODEL_ID } from "./constants.ts";
+
+export type VariantGroup = VariantProjection["groups"][number];
+export const byModelID = (a: ModelVariant, b: ModelVariant) => a.model.id < b.model.id ? -1 : a.model.id > b.model.id ? 1 : 0;
+export const isUsable = (variant: ModelVariant) => variant.level !== undefined && !variant.unsupported;
+export const publishedVariants = (group: VariantGroup) => group.variants.filter(isUsable).sort(byModelID);
+
+/**
+ * Dimension labels that tell groups apart: only dimensions whose values differ among published groups of the same family name.
+ * When the catalog value name is empty, 0 counts as the default and is omitted; an enabled value uses the dimension name.
+ */
+function groupDistinctParts(projection: VariantProjection): Map<string, string[]> {
+  const families = new Map<string, VariantGroup[]>();
+  for (const group of projection.groups) families.set(group.name, [...(families.get(group.name) ?? []), group]);
+  const result = new Map<string, string[]>();
+  for (const groups of families.values()) {
+    const peers = groups.filter((group) => group.canPublish).length > 1 ? groups.filter((group) => group.canPublish) : groups;
+    const values = (key: string) => new Set(peers.map((group) => {
+      const dimension = group.dimensions.find((entry) => entry.key === key);
+      return dimension ? `${dimension.order}\0${dimension.name}` : "";
+    }));
+    for (const group of groups) {
+      const parts = group.dimensions.filter((dimension) => values(dimension.key).size > 1).flatMap((dimension) => {
+        if (dimension.name) return [`${dimension.key} ${dimension.name}`];
+        if (dimension.order === 0) return [];
+        const orders = new Set(peers.map((peer) => peer.dimensions.find((entry) => entry.key === dimension.key)).filter((entry) => entry && !entry.name && entry.order !== 0).map((entry) => entry!.order));
+        return [orders.size > 1 ? `${dimension.key} ${dimension.order}` : dimension.key];
+      });
+      result.set(group.id, parts);
+    }
+  }
+  return result;
+}
+
+/** Human-readable group name. Example: `Claude Opus 4.8 · Fast Mode`. */
+export function groupDisplayNames(projection: VariantProjection): Map<string, string> {
+  const parts = groupDistinctParts(projection);
+  return new Map(projection.groups.map((group) => [group.id, [group.name, ...parts.get(group.id)!].join(" · ")]));
+}
+
+const slug = (text: string) => text.toLowerCase().replace(/[^a-z0-9.]+/g, "-").replace(/^-+|-+$/g, "");
+
+/** Model IDs shown in Pi lists. Groups are keyed by their internal `family:` key, variants by catalog UID. */
+export interface PublicModelIDs {
+  groups: ReadonlyMap<string, string>;
+  variants: ReadonlyMap<string, string>;
+  targets: ReadonlyMap<string, { group: VariantGroup } | { variant: ModelVariant }>;
+}
+
+const publicIDCache = new WeakMap<VariantProjection, PublicModelIDs>();
+/**
+ * Pi `/model` shows IDs, not model names, so the IDs are made human-readable.
+ * Published groups use `familyID[-differing dimensions]` (e.g. `claude-opus-4.8-fast-mode`); variants use the catalog UID (e.g. `swe-2-high`).
+ * The same catalog always yields the same IDs regardless of display mode. On a clash, groups win and the variant gets `-exact`.
+ */
+export function publicModelIDs(projection: VariantProjection): PublicModelIDs {
+  const cached = publicIDCache.get(projection);
+  if (cached) return cached;
+  const parts = groupDistinctParts(projection), taken = new Set([FUSION_MODEL_ID]);
+  const groups = new Map<string, string>(), variants = new Map<string, string>(), targets = new Map<string, { group: VariantGroup } | { variant: ModelVariant }>();
+  const claim = (base: string) => {
+    let id = base;
+    for (let suffix = 2; taken.has(id); suffix++) id = `${base}-${suffix}`;
+    taken.add(id);
+    return id;
+  };
+  for (const group of projection.groups.filter((entry) => entry.canPublish).sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0)) {
+    const id = claim([slug(group.family), ...parts.get(group.id)!.map(slug)].filter(Boolean).join("-") || "model");
+    groups.set(group.id, id); targets.set(id, { group });
+  }
+  for (const variant of projection.variants.filter(isUsable).sort(byModelID)) {
+    const id = claim(taken.has(variant.model.id) ? `${variant.model.id}-exact` : variant.model.id);
+    variants.set(variant.model.id, id); targets.set(id, { variant });
+  }
+  const result = { groups, variants, targets };
+  publicIDCache.set(projection, result);
+  return result;
+}

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

@@ -0,0 +1,93 @@
+import { createHash } from "node:crypto";
+import { EFFECTIVE_THINKING_LEVELS, type EffectiveThinkingLevel, type ModelVariant, type VariantProjection } from "../../../core/models/variants.ts";
+import type { Credential } from "../../../core/types.ts";
+import { CATALOG_VERSION, DEVIN_API, FUSION_MODEL_ID } from "./constants.ts";
+import { effectiveFusion } from "./fusion.ts";
+import { groupDisplayNames, isUsable, publicModelIDs, publishedVariants } from "./ids.ts";
+import type { DevinModel, FusionSelection } from "./types.ts";
+
+/** Options for projecting the model list. Defaults: group list, Fusion included, recommended filter off. */
+export interface ProjectionOptions {
+  /** Saved Fusion choice. false (sidekick child Pi) creates no Fusion entry. */
+  fusion?: FusionSelection | false;
+  /** Lists only models with a variant marked as recommended. Groups stay groups. The Fusion entry is unaffected. */
+  recommendedOnly?: boolean;
+  /** Also lists exact UIDs that a group already covers. Used only by the sidekick child Pi. */
+  listsAllExactModels?: boolean;
+  /** Account identity hash recorded with every model. */
+  account?: string;
+}
+
+/**
+ * A model whose catalog entry marks 24-hour prompt cache retention as a variant attribute.
+ * The request wire has no retention field, so this flag is the only basis for allowing long retention.
+ */
+export function hasExtendedPromptCacheRetention(variant: ModelVariant): boolean {
+  return variant.dimensions.some((dimension) => dimension.key === "Prompt Cache Retention" && dimension.name === "24h");
+}
+
+/** Scope of one credential on one endpoint. Credentials reaching here already carry a validated endpoint origin. */
+export function catalogScope(credential: Credential): string {
+  return createHash("sha256").update(credential.apiServerURL + "\0" + credential.sessionToken).digest("hex");
+}
+
+function thinkingMap(mappings: Partial<Record<EffectiveThinkingLevel, string>>) {
+  return Object.fromEntries(EFFECTIVE_THINKING_LEVELS.map((level) => [level, mappings[level] ?? null]));
+}
+
+function modelDefinition(id: string, name: string, variants: ModelVariant[], mappings: Partial<Record<EffectiveThinkingLevel, string>>, credential: Credential, account?: string): DevinModel {
+  const first = variants[0].model;
+  return {
+    id, name, api: DEVIN_API, provider: "devin", baseUrl: credential.apiServerURL,
+    reasoning: Object.keys(mappings).some((level) => level !== "off"), thinkingLevelMap: thinkingMap(mappings),
+    input: first.supportsImages ? ["text", "image"] : ["text"],
+    contextWindow: first.contextWindow, maxTokens: first.maxOutputTokens,
+    // Placeholder for Pi's required numeric fields. It does not mean free or a real USD price.
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    devin: { version: CATALOG_VERSION, scope: catalogScope(credential), costsUnknown: true, configs: variants.map((variant) => variant.config), ...(account ? { account } : {}) },
+  };
+}
+
+/**
+ * Exact UIDs covered by a published group are hidden and chosen with `/thinking`. Their catalog configs are stored on the group model.
+ * `recommendedOnly` keeps only groups and uncovered exact UIDs that hold a recommended variant, so `/thinking` still picks the UID.
+ * Without any recommended variant, it falls back to the default list.
+ * `listsAllExactModels` is only for processes that pick exact UIDs directly, such as the sidekick child.
+ */
+export function modelsFromProjection(projection: VariantProjection, credential: Credential, options: ProjectionOptions = {}): DevinModel[] {
+  const models: DevinModel[] = [], names = groupDisplayNames(projection), ids = publicModelIDs(projection);
+  const published = projection.groups.filter((group) => group.canPublish);
+  const recommendedUIDs = new Set(projection.variants.filter((variant) => isUsable(variant) && variant.model.isRecommended).map((variant) => variant.model.id));
+  // Fall back to the default projection so accounts without recommended flags never get an empty list.
+  const isRecommendedOnly = options.recommendedOnly === true && recommendedUIDs.size > 0;
+  const isListed = (uids: readonly string[]) => !isRecommendedOnly || uids.some((uid) => recommendedUIDs.has(uid));
+  for (const group of published) {
+    if (!isListed(Object.values(group.mappings))) continue;
+    const model = modelDefinition(ids.groups.get(group.id)!, names.get(group.id)!, publishedVariants(group), group.mappings, credential, options.account);
+    if (group.variants.some((variant) => variant.model.isRecommended)) model.devin.recommended = true;
+    models.push(model);
+  }
+  const covered = new Set(published.flatMap((group) => Object.values(group.mappings)));
+  const exact = projection.variants.filter((variant) => isUsable(variant) && isListed([variant.model.id])
+    && (options.listsAllExactModels === true || !covered.has(variant.model.id)));
+  const listedNames = new Set(models.map((model) => model.name));
+  for (const variant of exact) {
+    const name = listedNames.has(variant.model.name) ? `${variant.model.name} (${variant.model.id})` : variant.model.name;
+    const model = modelDefinition(ids.variants.get(variant.model.id)!, name, [variant], { [variant.level!]: variant.model.id }, credential, options.account);
+    if (variant.model.isRecommended) model.devin.recommended = true;
+    models.push(model);
+  }
+  const fusion = options.fusion;
+  const pair = fusion === false ? undefined : effectiveFusion(projection, fusion);
+  if (pair) {
+    const lead = projection.groups.find((group) => ids.groups.get(group.id) === pair.leadID)!;
+    const sidekick = projection.variants.find((variant) => ids.variants.get(variant.model.id) === pair.sidekickID)!;
+    const model = modelDefinition(FUSION_MODEL_ID, `Devin Fusion · ${names.get(lead.id)} + ${sidekick.model.name}`, publishedVariants(lead), lead.mappings, credential, options.account);
+    model.devin.fusion = pair;
+    models.push(model);
+  }
+  models.sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+  if (models.length) models[0].devin.unavailable = projection.variants.filter((variant) => variant.unsupported)
+    .sort((a, b) => a.model.id < b.model.id ? -1 : a.model.id > b.model.id ? 1 : 0).map((variant) => variant.config);
+  return models;
+}

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

@@ -0,0 +1,15 @@
+import { Context, Effect, Layer } from "effect";
+import { applyTeamModelPolicy } from "../../../core/models/access.ts";
+import { DevinClients } from "../clients/service.ts";
+import type { RemoteCatalogShape } from "./types.ts";
+
+/** The remote side of the catalog query: one lookup of the catalog and the team settings for a credential. */
+export class RemoteCatalog extends Context.Service<RemoteCatalog, RemoteCatalogShape>()("pi-devin/RemoteCatalog") {}
+
+export const RemoteCatalogLive = Layer.effect(RemoteCatalog, Effect.map(DevinClients, (clients) => ({
+  fetch: (credential) => Effect.scoped(Effect.gen(function* () {
+    const client = yield* clients.open(credential);
+    const catalog = yield* client.catalog;
+    return { ...catalog, models: applyTeamModelPolicy(catalog.models, yield* client.teamSettings) };
+  })),
+} satisfies RemoteCatalogShape)));

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