@buyong/pi-devin 0.1.4 → 0.1.6

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

@@ -0,0 +1,69 @@
+import { Context, Effect, Layer } from "effect";
+import type { Credential, JsonObject } from "../../../core/types.ts";
+import { requiredString } from "../../../core/validation.ts";
+import { ExtensionConfig } from "../../app/config.ts";
+import { AuthState } from "../auth/state.ts";
+import { evictOldest } from "../bounded.ts";
+import { catalogScope } from "../catalog/projection.ts";
+import { DevinClients } from "../clients/service.ts";
+import { ProviderLifetime } from "../lifetime/service.ts";
+import { UsageStore } from "../settings/service.ts";
+import { UsageChanges } from "../usage/changes.ts";
+import { accountUsage } from "../usage/report.ts";
+import type { AccountUsage } from "../usage/types.ts";
+import type { AccountRecord, AccountsShape } from "./types.ts";
+
+/**
+ * The only owner of the account status query (`GetUserStatus`): accounts this process verified, by credential scope,
+ * and the newest quota they reported. Request checks, the check after sign-in and the periodic session check all go through it.
+ */
+export class Accounts extends Context.Service<Accounts, AccountsShape>()("pi-devin/Accounts") {}
+
+export const AccountsLive = Layer.effect(Accounts, Effect.gen(function* () {
+  const clients = yield* DevinClients;
+  const store = yield* UsageStore;
+  const changes = yield* UsageChanges;
+  const lifetime = yield* ProviderLifetime;
+  const auth = yield* AuthState;
+  const config = yield* ExtensionConfig;
+  const records = new Map<string, AccountRecord>();
+  let latestUsage: { scope: string; usage: AccountUsage } | undefined;
+
+  // A stopped provider records nothing more.
+  const record = (credential: Credential, ownerHash: string, status: JsonObject) => Effect.gen(function* () {
+    if (!(yield* lifetime.isActive)) return;
+    const scope = catalogScope(credential);
+    evictOldest(records, 16);
+    records.set(scope, { ownerHash, status });
+    const usage = accountUsage(status, config.now());
+    latestUsage = { scope, usage };
+    // Subagents and the Fusion sidekick run in other processes; a failed write only loses sharing.
+    yield* Effect.ignore(store.write(scope, usage));
+    yield* changes.publish;
+  });
+
+  return {
+    get: (credential) => Effect.sync(() => records.get(catalogScope(credential))),
+    check: (credential, check) => Effect.scoped(Effect.gen(function* () {
+      const client = yield* clients.open(credential, { profile: "login", ...check.connection });
+      const status = yield* client.status();
+      if ((yield* auth.generation) !== check.expectedGeneration) return "stale" as const;
+      if (check.beforeRecord) yield* check.beforeRecord;
+      yield* record(credential, yield* requiredString(yield* client.accountIdentityHash, "Devin account scope"), status);
+      return "recorded" as const;
+    })),
+    forget: (credential) => Effect.sync(() => {
+      records.delete(catalogScope(credential));
+      latestUsage = undefined;
+    }),
+    clear: Effect.sync(() => {
+      records.clear();
+      latestUsage = undefined;
+    }),
+    usage: (scope) => Effect.map(store.read(scope), (shared) => {
+      const local = latestUsage?.scope === scope ? latestUsage.usage : undefined;
+      const newest = shared && (!local || shared.fetchedAtMs > local.fetchedAtMs) ? shared : local;
+      return newest ? { ...newest } : undefined;
+    }),
+  } satisfies AccountsShape;
+}));

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

@@ -0,0 +1,25 @@
+import type { Effect } from "effect";
+import type { DevinFailure } from "../../../core/errors.ts";
+import type { Credential, JsonObject } from "../../../core/types.ts";
+import type { AccountUsage } from "../usage/types.ts";
+
+export interface AccountRecord { ownerHash: string; status: JsonObject }
+
+export interface AccountCheck {
+  /** Sign-in generation the caller started in. When a newer sign-in started meanwhile, nothing is recorded. */
+  expectedGeneration: number;
+  /** Connection settings of the lookup, such as Pi's per-request fetch and time limit. */
+  connection?: { fetch?: typeof fetch; timeoutMs?: number };
+  /** Runs after the generation check and before recording. Its failure leaves the result unrecorded. */
+  beforeRecord?: Effect.Effect<void, DevinFailure>;
+}
+
+export interface AccountsShape {
+  readonly get: (credential: Credential) => Effect.Effect<AccountRecord | undefined>;
+  /** Looks up the account status and records it. `"stale"` when a newer sign-in started meanwhile. Failure policy belongs to the caller. */
+  readonly check: (credential: Credential, check: AccountCheck) => Effect.Effect<"recorded" | "stale", DevinFailure>;
+  readonly forget: (credential: Credential) => Effect.Effect<void>;
+  readonly clear: Effect.Effect<void>;
+  /** Newest quota for the scope, received here or by another process sharing the usage store. Makes no request. */
+  readonly usage: (scope: string) => Effect.Effect<AccountUsage | undefined>;
+}

package/src/pi/features/auth/credential.ts

@@ -0,0 +1,40 @@
+import { createHash } from "node:crypto";
+import type { OAuthCredential } from "@earendil-works/pi-ai";
+import { Effect } from "effect";
+import type { DevinError } from "../../../core/errors.ts";
+import { endpoint } from "../../../core/protocol/endpoint.ts";
+import type { Credential } from "../../../core/types.ts";
+import { failWith, object, requiredString } from "../../../core/validation.ts";
+
+export const OAUTH_ONLY_MESSAGE = "Devin uses only the OAuth account session from /login. API key authentication is not supported.";
+/**
+ * Pi checks the stored session again after this interval. It is not a server TTL: the server expiry is unknown, no new token
+ * is issued, and each model request still checks the account outside Pi's credential lock.
+ */
+export const SESSION_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+export function credentialFromOAuth(credential: OAuthCredential): Effect.Effect<Credential, DevinError> {
+  return Effect.gen(function* () {
+    // 0.1.4 and earlier stored `expires: 0`; Pi checks such a session again on its next use.
+    if (credential.type !== "oauth" || credential.refresh !== "" || !Number.isSafeInteger(credential.expires) || credential.expires < 0) {
+      return yield* failWith("Unsupported Devin account credential. Sign in again with /login.");
+    }
+    const metadata = yield* object(credential.devin, "Devin credential metadata");
+    if (metadata.version !== 1) return yield* failWith("The Devin account credential version differs. Sign in again with /login.");
+    return {
+      version: 1,
+      sessionToken: yield* requiredString(credential.access, "Devin credential access"),
+      apiServerURL: yield* endpoint(yield* requiredString(metadata.apiServerURL, "Devin credential API server")),
+      createdAt: yield* requiredString(metadata.createdAt, "Devin credential creation time"),
+    } satisfies Credential;
+  });
+}
+
+export function credentialKey(credential: Credential): string {
+  return createHash("sha256").update(credential.apiServerURL + "\0" + credential.sessionToken).digest("hex");
+}
+
+/** Endpoint mismatches are rejected separately by the model list scope. This only checks that the session came from OAuth. */
+export function sessionKey(credential: Credential): string {
+  return createHash("sha256").update(credential.sessionToken).digest("hex");
+}

package/src/pi/features/auth/guard.ts

@@ -0,0 +1,25 @@
+import { Context, Effect, Layer } from "effect";
+import { isAuthenticationError } from "../../../core/errors.ts";
+import { Accounts } from "../accounts/service.ts";
+import { Runs } from "../runs/service.ts";
+import { UsageChanges } from "../usage/changes.ts";
+import { AuthState } from "./state.ts";
+import type { CredentialGuardShape } from "./types.ts";
+
+/** Turns a confirmed authentication failure into its consequences, in order and within the reporting effect. */
+export class CredentialGuard extends Context.Service<CredentialGuard, CredentialGuardShape>()("pi-devin/CredentialGuard") {}
+
+export const CredentialGuardLive = Layer.effect(CredentialGuard, Effect.gen(function* () {
+  const auth = yield* AuthState;
+  const accounts = yield* Accounts;
+  const runs = yield* Runs;
+  const changes = yield* UsageChanges;
+  return {
+    reportFailure: (credential, error, generation) => Effect.gen(function* () {
+      if (!isAuthenticationError(error) || !(yield* auth.markInvalid(credential, error, generation))) return;
+      yield* accounts.forget(credential);
+      yield* runs.abort(error);
+      yield* changes.publish;
+    }),
+  } satisfies CredentialGuardShape;
+}));

package/src/pi/features/auth/login.ts

@@ -0,0 +1,116 @@
+import type { AuthInteraction, OAuthCredential } from "@earendil-works/pi-ai";
+import { Context, Duration, Effect, Layer } from "effect";
+import { loginAccount } from "../../../core/auth/login.ts";
+import { abortWith } from "../../../core/cancellation.ts";
+import { Cancelled, isTransientConnectionFailure, toDevinFailure } from "../../../core/errors.ts";
+import { HttpTransport, type HttpTransportShape } from "../../../core/services/http-transport.ts";
+import { failWith } from "../../../core/validation.ts";
+import { ExtensionConfig } from "../../app/config.ts";
+import { Accounts } from "../accounts/service.ts";
+import { ModelCatalog } from "../catalog/service.ts";
+import { DevinClients } from "../clients/service.ts";
+import { ProviderLifetime } from "../lifetime/service.ts";
+import { Runs } from "../runs/service.ts";
+import { UsageChanges } from "../usage/changes.ts";
+import { credentialFromOAuth, SESSION_CHECK_INTERVAL_MS } from "./credential.ts";
+import { CredentialGuard } from "./guard.ts";
+import { AuthState } from "./state.ts";
+import type { AccountLoginShape } from "./types.ts";
+
+/** Upper bound of the account check right after sign-in. Sign-in succeeds even when this check fails. */
+const LOGIN_CHECK_TIMEOUT_MS = 15_000;
+
+/** The transport of `/login` code exchanges, chosen by the environment like the provider's own transport. */
+export class LoginTransport extends Context.Service<LoginTransport, HttpTransportShape>()("pi-devin/LoginTransport") {}
+
+/** Pi's OAuth flows: sign-in, the periodic session check under Pi's credential lock, and request auth. */
+export class AccountLogin extends Context.Service<AccountLogin, AccountLoginShape>()("pi-devin/AccountLogin") {}
+
+/** A host prompt that is withdrawn, through its signal, when the waiting effect is interrupted. */
+const prompt = <A>(request: (signal: AbortSignal) => Promise<A>) => Effect.tryPromise({ try: request, catch: toDevinFailure });
+
+export const AccountLoginLive = Layer.effect(AccountLogin, Effect.gen(function* () {
+  const config = yield* ExtensionConfig;
+  const auth = yield* AuthState;
+  const accounts = yield* Accounts;
+  const guard = yield* CredentialGuard;
+  const catalog = yield* ModelCatalog;
+  const clients = yield* DevinClients;
+  const runs = yield* Runs;
+  const changes = yield* UsageChanges;
+  const lifetime = yield* ProviderLifetime;
+  const transport = yield* LoginTransport;
+  const now = config.now;
+
+  /** Stops the work when the caller's signal or the provider lifetime current at the start of the host call ends, failing with that reason. */
+  const stoppable = (signal: AbortSignal | undefined) => Effect.map(lifetime.current, (current) => <A, E>(effect: Effect.Effect<A, E>) =>
+    current.guard(effect).pipe(abortWith(signal)));
+
+  const signIn = (interaction: AuthInteraction) => Effect.gen(function* () {
+    const choice = yield* prompt((signal) => interaction.prompt({ type: "select", signal, message: "Devin account sign-in method", options: [
+      { id: "browser", label: "Browser sign-in", description: "Choose an account, then return through a loopback callback." },
+      { id: "manual", label: "Manual authorization code", description: "Enter a one-time code using the Devin CLI manual flow. This is not an API key prompt." },
+    ] }));
+    if (choice !== "browser" && choice !== "manual") return yield* failWith("Unsupported Devin sign-in method.");
+    const credential = yield* loginAccount({
+      ...config.login, flow: choice,
+      onURL: (url) => Effect.sync(() => interaction.notify({ type: "auth_url", url, instructions: "Return to the terminal after signing in. Signing in does not guarantee CLI access or quota." })),
+      promptCode: prompt((signal) => interaction.prompt({ type: "manual_code", message: "Paste the authorization code or callback URL. Do not enter an API key or session token.", signal })),
+    }).pipe(Effect.provideService(HttpTransport, transport));
+    return { choice, credential };
+  });
+
+  /** A new session replaces everything learned from the previous one, in this order, before its own account is checked. */
+  const replaceSession = Effect.all([
+    accounts.clear, clients.clearFingerprints, catalog.invalidate,
+    runs.abort(new Cancelled({ message: "The Devin account was re-authenticated." })), changes.publish,
+  ], { discard: true });
+
+  const login = (interaction: AuthInteraction) => Effect.gen(function* () {
+    const stop = yield* stoppable(interaction.signal);
+    const { choice, credential } = yield* stop(signIn(interaction));
+    const generation = yield* auth.acceptLogin(credential);
+    yield* replaceSession;
+    // Records the new session's account and quota so the same account's model list and usage are available at once.
+    // Sign-in is not a permission check: a failure here, including cancellation, is left to the first model request.
+    yield* stop(accounts.check(credential, { expectedGeneration: generation })).pipe(
+      Effect.timeoutOrElse({ duration: Duration.millis(LOGIN_CHECK_TIMEOUT_MS), orElse: () => Effect.void }),
+      Effect.ignore,
+    );
+    interaction.notify({ type: "info", message: "Signed in to the Devin account. The server expiry time and refresh grant are unknown. If authentication fails, sign in again with /login." });
+    return {
+      type: "oauth", access: credential.sessionToken, refresh: "", expires: now() + SESSION_CHECK_INTERVAL_MS,
+      devin: { version: 1, apiServerURL: credential.apiServerURL, createdAt: credential.createdAt, flow: choice },
+    } satisfies OAuthCredential;
+  });
+
+  const usableCredential = (current: OAuthCredential) => Effect.gen(function* () {
+    const credential = yield* credentialFromOAuth(current);
+    yield* auth.assertUsable(credential);
+    return yield* auth.rememberOAuth(credential);
+  });
+
+  const refresh = (current: OAuthCredential) => Effect.gen(function* () {
+    const credential = yield* usableCredential(current);
+    // Pi calls this while holding the shared auth.json lock once the check interval has passed, and saves the result.
+    // The new expiry only schedules the next check; the token is never renewed.
+    const checked = (): OAuthCredential => ({ ...current, expires: now() + SESSION_CHECK_INTERVAL_MS });
+    // Model requests already check the account outside the lock, so a process that checked it does not wait on the network.
+    if (yield* accounts.get(credential)) return checked();
+    const expectedGeneration = yield* auth.generation;
+    return yield* accounts.check(credential, { expectedGeneration }).pipe(
+      Effect.map(checked),
+      Effect.catch((error) => Effect.andThen(guard.reportFailure(credential, error, expectedGeneration),
+        // An unreachable check must not block the request: keep the stored session unchanged so the model request
+        // succeeds or reports its own retryable transport error, and the next use checks again.
+        isTransientConnectionFailure(error) ? Effect.succeed(current) : Effect.fail(error))),
+    );
+  });
+
+  return {
+    login,
+    refresh: (current, signal) => Effect.flatMap(stoppable(signal), (stop) => stop(refresh(current))),
+    // apiKey is only ModelAuth's transport field; the sign-in/storage auth type is always oauth.
+    toAuth: (current) => Effect.map(usableCredential(current), (credential) => ({ apiKey: credential.sessionToken, baseUrl: credential.apiServerURL })),
+  } satisfies AccountLoginShape;
+}));

package/src/pi/features/auth/state.ts

@@ -0,0 +1,48 @@
+import { Context, Effect, Layer } from "effect";
+import { isAuthenticationError, RPCError } from "../../../core/errors.ts";
+import type { Credential } from "../../../core/types.ts";
+import { failWith } from "../../../core/validation.ts";
+import { evictOldest } from "../bounded.ts";
+import { credentialFromOAuth, credentialKey, OAUTH_ONLY_MESSAGE, sessionKey } from "./credential.ts";
+import type { AuthStateShape } from "./types.ts";
+
+/**
+ * Whether a credential may be used: the sign-in generation, credentials invalidated by a confirmed 401,
+ * and the OAuth sessions this process has seen. Remembers only hashes, never a token.
+ */
+export class AuthState extends Context.Service<AuthState, AuthStateShape>()("pi-devin/AuthState") {}
+
+export const AuthStateLive = Layer.sync(AuthState, () => {
+  const invalid = new Set<string>();
+  const oauthSessions = new Set<string>();
+  let generation = 0;
+  const rememberOAuth = (credential: Credential) => Effect.sync(() => {
+    const key = sessionKey(credential);
+    oauthSessions.delete(key);
+    evictOldest(oauthSessions, 64);
+    oauthSessions.add(key);
+    return credential;
+  });
+  return {
+    generation: Effect.sync(() => generation),
+    assertUsable: (credential) => Effect.suspend(() => invalid.has(credentialKey(credential))
+      ? Effect.fail(RPCError.make("unauthenticated", "Authentication failed for this session. Sign in again with /login.")) : Effect.void),
+    // Kept as a plain error so it does not invalidate authentication or cancel a running request.
+    assertOAuthSession: (credential) => Effect.suspend(() => oauthSessions.has(sessionKey(credential)) ? Effect.void : failWith(OAUTH_ONLY_MESSAGE)),
+    rememberOAuth,
+    fromHost: (credential) => Effect.flatMap(credentialFromOAuth(credential), rememberOAuth),
+    markInvalid: (credential, error, expectedGeneration) => Effect.sync(() => {
+      if (expectedGeneration !== generation || !isAuthenticationError(error)) return false;
+      const key = credentialKey(credential);
+      if (invalid.has(key)) return false;
+      evictOldest(invalid, 64);
+      invalid.add(key);
+      return true;
+    }),
+    acceptLogin: (credential) => Effect.gen(function* () {
+      invalid.delete(credentialKey(credential));
+      yield* rememberOAuth(credential);
+      return ++generation;
+    }),
+  } satisfies AuthStateShape;
+});

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

@@ -0,0 +1,36 @@
+import type { AuthInteraction, ModelAuth, OAuthCredential } from "@earendil-works/pi-ai";
+import type { Effect } from "effect";
+import type { DevinError, DevinFailure, RPCError } from "../../../core/errors.ts";
+import type { Credential } from "../../../core/types.ts";
+
+export interface AuthStateShape {
+  /** Increases with every successful sign-in. Work captures it when it starts and acts on failures only within the same generation. */
+  readonly generation: Effect.Effect<number>;
+  /** Fails with an authentication error when this credential was invalidated. */
+  readonly assertUsable: (credential: Credential) => Effect.Effect<void, RPCError>;
+  /** Rejects sessions that did not come from an OAuth login or stored credential (API keys etc.) before any network request. */
+  readonly assertOAuthSession: (credential: Credential) => Effect.Effect<void, DevinError>;
+  /** Remembers the credential as this process's OAuth session. Pi resolves the session in use on every request, so it moves back to the front. */
+  readonly rememberOAuth: (credential: Credential) => Effect.Effect<Credential>;
+  /** Converts the OAuth credential stored by Pi into the shared credential and remembers it as an OAuth session. */
+  readonly fromHost: (credential: OAuthCredential) => Effect.Effect<Credential, DevinError>;
+  /** Marks a confirmed authentication failure of the given generation. True only when this call invalidated the credential. */
+  readonly markInvalid: (credential: Credential, error: unknown, generation: number) => Effect.Effect<boolean>;
+  /** A new sign-in: clears its invalid mark, remembers it and starts the next generation, which it returns. */
+  readonly acceptLogin: (credential: Credential) => Effect.Effect<number>;
+}
+
+export interface CredentialGuardShape {
+  /**
+   * Acts on a failure seen while using the credential. Only a confirmed authentication failure of the current generation
+   * invalidates it; then its account record is forgotten and the running run stops with the same error. The credential file is never deleted.
+   */
+  readonly reportFailure: (credential: Credential, error: unknown, generation: number) => Effect.Effect<void>;
+}
+
+/** Pi's OAuth flows. Each call stops with the provider lifetime current when it started and with the caller's signal. */
+export interface AccountLoginShape {
+  readonly login: (interaction: AuthInteraction) => Effect.Effect<OAuthCredential, DevinFailure>;
+  readonly refresh: (current: OAuthCredential, signal: AbortSignal) => Effect.Effect<OAuthCredential, DevinFailure>;
+  readonly toAuth: (current: OAuthCredential) => Effect.Effect<ModelAuth, DevinError | RPCError>;
+}

package/src/pi/features/bounded.ts

@@ -0,0 +1,4 @@
+/** Makes room in an insertion-ordered set or map by forgetting its oldest entry once it holds `limit` entries. */
+export function evictOldest<T>(collection: Set<T> | Map<T, unknown>, limit: number): void {
+  if (collection.size >= limit) collection.delete(collection.keys().next().value!);
+}

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

@@ -0,0 +1,10 @@
+import type { DevinAPI } from "./types.ts";
+
+export const DEVIN_API: DevinAPI = "devin-connect";
+export const CATALOG_VERSION = 1;
+/** Default sidekick when nothing is saved or the saved one is gone. The default lead is the group this UID belongs to. */
+export const FUSION_SIDEKICK_UID = "swe-2-medium";
+/** The single Fusion entry shown in `/model`. Lead and sidekick follow the global `/devin-fusion` choice. */
+export const FUSION_MODEL_ID = "fusion";
+
+export function isFusionModelID(id: string): boolean { return id === FUSION_MODEL_ID; }

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