@buyong/pi-devin 0.0.0-stage → 0.1.0

package/src/pi/auth.ts

@@ -0,0 +1,134 @@
+import { createHash } from "node:crypto";
+import type { OAuthAuth, OAuthCredential } from "@earendil-works/pi-ai";
+import { loginAccount, type LoginOptions } from "../core/auth/index.ts";
+import { DevinClient } from "../core/client.ts";
+import { awaitWithSignal, endpoint, isAuthenticationError, RPCError } from "../core/protocol/transport.ts";
+import { object, requiredString, type Credential, type JsonObject } from "../core/types.ts";
+
+export const OAUTH_ONLY_MESSAGE = "Devin uses only the OAuth account session from /login. API key authentication is not supported.";
+
+export interface DevinAccountAuth extends OAuthAuth {
+  readonly generation: number;
+  assertUsable(credential: Credential): void;
+  /** Converts the OAuth credential stored by Pi into the shared credential and remembers it as this process's OAuth session. */
+  credentialFromHost(credential: OAuthCredential): Credential;
+  /** Rejects sessions that did not come from an OAuth login or stored credential (API keys etc.) before any network request. */
+  assertOAuthSession(credential: Credential): void;
+  /** Remembers only authentication failures confirmed in the same auth generation. The credential file is never deleted. */
+  invalidate(credential: Credential, error: unknown, generation: number): void;
+}
+
+export function credentialFromOAuth(credential: OAuthCredential): Credential {
+  if (credential.type !== "oauth" || credential.refresh !== "" || credential.expires !== 0) {
+    throw new Error("Unsupported Devin account credential. Sign in again with /login.");
+  }
+  const metadata = object(credential.devin, "Devin credential metadata");
+  if (metadata.version !== 1) throw new Error("The Devin account credential version differs. Sign in again with /login.");
+  return {
+    version: 1,
+    sessionToken: requiredString(credential.access, "Devin credential access"),
+    apiServerURL: endpoint(requiredString(metadata.apiServerURL, "Devin credential API server")),
+    createdAt: requiredString(metadata.createdAt, "Devin credential creation time"),
+  };
+}
+
+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. */
+function sessionKey(credential: Credential): string {
+  return createHash("sha256").update(credential.sessionToken).digest("hex");
+}
+
+export function createDevinAccountAuth(options: {
+  loginOptions?: Omit<LoginOptions, "onURL" | "promptCode" | "signal" | "flow" | "encoding">;
+  createClient?: (credential: Credential) => DevinClient;
+  onLogin?: () => void;
+  onValidated?: (credential: Credential, ownerHash: string, status: JsonObject) => void;
+  onInvalidated?: (credential: Credential, error: unknown) => void;
+  getSignal?: () => AbortSignal;
+} = {}): DevinAccountAuth {
+  const invalid = new Set<string>();
+  // Remembers only a hash, never the token. Pi calls toAuth on every request, so the session in use moves back to the front.
+  const oauthSessions = new Set<string>();
+  let generation = 0;
+  const requireUsable = (credential: Credential) => {
+    if (invalid.has(credentialKey(credential))) throw new RPCError("unauthenticated", "Authentication failed for this session. Sign in again with /login.");
+  };
+  const rememberOAuth = (credential: Credential) => {
+    const key = sessionKey(credential);
+    oauthSessions.delete(key);
+    if (oauthSessions.size >= 64) oauthSessions.delete(oauthSessions.values().next().value!);
+    oauthSessions.add(key);
+    return credential;
+  };
+  const auth: DevinAccountAuth = {
+    name: "Devin account",
+    get generation() { return generation; },
+    assertUsable: requireUsable,
+    credentialFromHost: (current) => rememberOAuth(credentialFromOAuth(current)),
+    assertOAuthSession(credential) {
+      // Kept as a plain error so it does not invalidate authentication or cancel a running request.
+      if (!oauthSessions.has(sessionKey(credential))) throw new Error(OAUTH_ONLY_MESSAGE);
+    },
+    async login(interaction) {
+      const lifetime = options.getSignal?.();
+      const signal = AbortSignal.any([interaction.signal, ...(lifetime ? [lifetime] : [])]);
+      signal.throwIfAborted();
+      const choice = await awaitWithSignal(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." },
+      ] }), signal);
+      if (choice !== "browser" && choice !== "manual") throw new Error("Unsupported Devin sign-in method.");
+      const credential = await loginAccount({
+        ...options.loginOptions, flow: choice, signal,
+        onURL: (url) => interaction.notify({ type: "auth_url", url, instructions: "Return to the terminal after signing in. Signing in does not guarantee CLI access or quota." }),
+        promptCode: (signal) => interaction.prompt({ type: "manual_code", message: "Paste the authorization code or callback URL. Do not enter an API key or session token.", signal }),
+      });
+      signal.throwIfAborted();
+      invalid.delete(credentialKey(credential));
+      rememberOAuth(credential);
+      generation++;
+      options.onLogin?.();
+      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: 0,
+        devin: { version: 1, apiServerURL: credential.apiServerURL, createdAt: credential.createdAt, flow: choice },
+      };
+    },
+    async refresh(current, callerSignal) {
+      const lifetime = options.getSignal?.();
+      const signal = AbortSignal.any([callerSignal, ...(lifetime ? [lifetime] : [])]);
+      signal.throwIfAborted();
+      const credential = credentialFromOAuth(current);
+      requireUsable(credential);
+      rememberOAuth(credential);
+      const expectedGeneration = generation;
+      const client = (options.createClient ?? ((value) => new DevinClient(value, { profile: "login" })))(credential);
+      try {
+        // 0 is not a server TTL. Pi's refresh entry point only checks the existing session; it never renews the token.
+        const status = await client.status(signal);
+        if (expectedGeneration === generation) options.onValidated?.(credential, requiredString(client.accountIdentityHash, "Devin account scope"), status);
+        return current;
+      } catch (error) { auth.invalidate(credential, error, expectedGeneration); throw error; }
+      finally { client.transport.close(); }
+    },
+    async toAuth(current) {
+      const credential = credentialFromOAuth(current);
+      requireUsable(credential);
+      rememberOAuth(credential);
+      // apiKey is only ModelAuth's transport field; the sign-in/storage auth type is always oauth.
+      return { apiKey: credential.sessionToken, baseUrl: credential.apiServerURL };
+    },
+    invalidate(credential, error, expectedGeneration) {
+      if (expectedGeneration !== generation || !isAuthenticationError(error)) return;
+      const key = credentialKey(credential);
+      if (invalid.has(key)) return;
+      if (invalid.size >= 64) invalid.delete(invalid.values().next().value!);
+      invalid.add(key);
+      options.onInvalidated?.(credential, error);
+    },
+  };
+  return auth;
+}

package/src/pi/devin-command.ts

@@ -0,0 +1,76 @@
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { DevinPanel, PREFERENCE_ITEMS } from "./devin-panel.ts";
+import type { DevinPreferences, DevinSettings } from "./devin-settings.ts";
+import type { DevinProvider } from "./provider.ts";
+import { sessionUsage, usageReport, usageStatusText } from "./usage.ts";
+
+export const DEVIN_COMMAND_NAME = "devin";
+/** The only status key this package uses. */
+export const USAGE_STATUS_KEY = "devin-usage";
+const USAGE = "Usage: /devin, /devin recommended on|off, /devin status on|off";
+const ARGUMENT_KEYS: Readonly<Record<string, keyof DevinPreferences>> = { recommended: "recommendedOnly", status: "showUsageStatus" };
+
+/** The status is used in the TUI only. Turning the toggle off clears only this package's key. Values come only from the last account status and session records. */
+export function updateUsageStatus(ctx: ExtensionContext, provider: DevinProvider, settings: DevinSettings): void {
+  if (ctx.mode !== "tui") return;
+  const text = settings.read().showUsageStatus
+    ? usageStatusText(provider.getAccountUsage(), sessionUsage(ctx.sessionManager.getBranch()), (tone, segment) => ctx.ui.theme.fg(tone, segment)) : undefined;
+  ctx.ui.setStatus(USAGE_STATUS_KEY, text);
+}
+
+const onOff = (value: boolean) => value ? "on" : "off";
+
+/**
+ * `/devin` shows usage details and display settings. Settings are saved globally and applied immediately.
+ * The TUI gets a dedicated screen; other modes use arguments and notifications.
+ */
+export function registerDevinCommand(pi: ExtensionAPI, provider: DevinProvider, settings: DevinSettings, options: { now?: () => number } = {}): void {
+  const now = options.now ?? Date.now;
+  const apply = async (ctx: ExtensionCommandContext, next: DevinPreferences) => {
+    const previous = settings.read();
+    // Only write failures are thrown to the caller. A list refresh failure after saving is reported as a warning so the screen and the saved value stay in sync.
+    settings.write(next);
+    if (previous.recommendedOnly !== next.recommendedOnly) {
+      provider.rebuildModels();
+      // Pi keeps model and availability snapshots. Rebuild them without network so `/model` and RPC lists update immediately.
+      try {
+        await ctx.modelRegistry.refresh({ providers: ["devin"], allowNetwork: false });
+      } catch (error) {
+        ctx.ui.notify(`Settings were saved, but the model list could not be rebuilt: ${error instanceof Error ? error.message : String(error)}`, "warning");
+      }
+      const model = ctx.model;
+      if (model?.provider === "devin" && !provider.getModels().some((item) => item.id === model.id)) {
+        ctx.ui.notify(`The current model ${model.name} is now hidden from the list but stays in use for this session. To restore it when reopening the session, pick a model from the list.`, "warning");
+      }
+    }
+    updateUsageStatus(ctx, provider, settings);
+  };
+  pi.registerCommand(DEVIN_COMMAND_NAME, {
+    description: "Show Devin usage and change display settings (recommended models only, usage in the status line); saved globally",
+    handler: async (args, ctx) => {
+      const report = () => usageReport(provider.getAccountUsage(), sessionUsage(ctx.sessionManager.getBranch()), provider.lifecycle.budget(), now());
+      const tokens = args.trim().split(/\s+/).filter(Boolean);
+      if (tokens.length) {
+        const key = ARGUMENT_KEYS[tokens[0]];
+        if (tokens.length !== 2 || !key || (tokens[1] !== "on" && tokens[1] !== "off")) {
+          ctx.ui.notify(`Unknown argument. ${USAGE}`, "error");
+          return;
+        }
+        const value = tokens[1] === "on";
+        await apply(ctx, { ...settings.read(), [key]: value });
+        ctx.ui.notify(`${PREFERENCE_ITEMS.find((item) => item.key === key)!.label}: ${onOff(value)} (saved globally)`, "info");
+        return;
+      }
+      if (ctx.mode === "tui") {
+        await ctx.ui.custom<void>((tui, theme, _keybindings, done) => new DevinPanel({
+          theme, report, preferences: settings.read(), onChange: (next) => apply(ctx, next),
+          requestRender: () => tui.requestRender(), done: () => done(),
+        }));
+        return;
+      }
+      const preferences = settings.read();
+      const summary = PREFERENCE_ITEMS.map((item) => `${item.label} ${onOff(preferences[item.key])}`).join(" · ");
+      ctx.ui.notify([...report().map((line) => line.text), `Settings: ${summary}`, USAGE].join("\n"), "info");
+    },
+  });
+}

package/src/pi/devin-panel.ts

@@ -0,0 +1,77 @@
+import { matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
+import type { DevinPreferences } from "./devin-settings.ts";
+import type { PickerTheme } from "./fusion-picker.ts";
+import type { UsageLine } from "./usage.ts";
+
+export const PREFERENCE_ITEMS: readonly { key: keyof DevinPreferences; label: string; detail: string }[] = [
+  { key: "recommendedOnly", label: "Recommended models only", detail: "/model shows only recommended variants and Devin Fusion" },
+  { key: "showUsageStatus", label: "Usage in status line", detail: "shows quota and session tokens in the footer" },
+];
+const HELP = "↑↓ move · space/↵ toggle · esc close";
+
+export interface DevinPanelOptions {
+  theme: PickerTheme;
+  report: () => UsageLine[];
+  preferences: DevinPreferences;
+  /** Saves and applies on every toggle. On failure, shows a notice and reverts to the previous value. */
+  onChange: (next: DevinPreferences) => Promise<void>;
+  requestRender: () => void;
+  done: () => void;
+}
+
+/** TUI screen for `/devin`. Shows usage details together with the display setting toggles. */
+export class DevinPanel {
+  private cursor = 0;
+  private preferences: DevinPreferences;
+  private notice: string | undefined;
+  private isSaving = false;
+  private cached: { width: number; lines: string[] } | undefined;
+  private readonly options: DevinPanelOptions;
+
+  constructor(options: DevinPanelOptions) {
+    this.options = options;
+    this.preferences = { ...options.preferences };
+  }
+
+  invalidate(): void { this.cached = undefined; }
+
+  private changed(): void { this.invalidate(); this.options.requestRender(); }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) return this.options.done();
+    if (matchesKey(data, "up")) { this.cursor = (this.cursor + PREFERENCE_ITEMS.length - 1) % PREFERENCE_ITEMS.length; return this.changed(); }
+    if (matchesKey(data, "down")) { this.cursor = (this.cursor + 1) % PREFERENCE_ITEMS.length; return this.changed(); }
+    if ((matchesKey(data, "space") || matchesKey(data, "enter")) && !this.isSaving) void this.toggle();
+  }
+
+  private async toggle(): Promise<void> {
+    const key = PREFERENCE_ITEMS[this.cursor].key, previous = this.preferences;
+    this.preferences = { ...previous, [key]: !previous[key] };
+    this.isSaving = true; this.notice = undefined; this.changed();
+    try {
+      await this.options.onChange(this.preferences);
+    } catch (error) {
+      this.preferences = previous;
+      this.notice = `Could not save: ${error instanceof Error ? error.message : String(error)}`;
+    } finally {
+      this.isSaving = false; this.changed();
+    }
+  }
+
+  render(width: number): string[] {
+    if (this.cached?.width === width) return this.cached.lines;
+    const { theme } = this.options;
+    const lines = [theme.fg("accent", theme.bold("Devin")) + theme.fg("muted", " · usage and display settings"), ""];
+    for (const line of this.options.report()) lines.push(theme.fg(line.isHeading ? "accent" : line.tone ?? "muted", line.text));
+    lines.push("", theme.fg("accent", theme.bold("Settings")));
+    PREFERENCE_ITEMS.forEach((item, index) => {
+      const isSelected = index === this.cursor;
+      const row = `${isSelected ? "›" : " "} [${this.preferences[item.key] ? "x" : " "}] ${item.label}`;
+      lines.push((isSelected ? theme.fg("accent", theme.bold(row)) : row) + theme.fg("dim", ` — ${item.detail}`));
+    });
+    lines.push("", this.notice ? theme.fg("warning", this.notice) : theme.fg("dim", this.isSaving ? "Saving…" : HELP));
+    const result = lines.map((line) => truncateToWidth(line, width));
+    this.cached = { width, lines: result };
+    return result;
+  }
+}

package/src/pi/devin-settings.ts

@@ -0,0 +1,50 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+const SCHEMA_VERSION = 1;
+
+/** Display settings toggled by `/devin`. Both default to off and never change how models are used or requested. */
+export interface DevinPreferences {
+  /** Lists only the variants that the catalog marks as recommended. */
+  recommendedOnly: boolean;
+  /** Shows quota and session usage in the TUI status line. */
+  showUsageStatus: boolean;
+}
+
+export const DEFAULT_PREFERENCES: DevinPreferences = { recommendedOnly: false, showUsageStatus: false };
+
+export interface DevinSettings {
+  read(): DevinPreferences;
+  write(preferences: DevinPreferences): void;
+}
+
+export function devinSettingsPath(agentDir: string): string {
+  return join(agentDir, "pi-devin", "settings.json");
+}
+
+/** Default store so SDK callers and tests never write to the real agent directory. */
+export function memoryDevinSettings(initial: Partial<DevinPreferences> = {}): DevinSettings {
+  let current: DevinPreferences = { ...DEFAULT_PREFERENCES, ...initial };
+  return { read: () => ({ ...current }), write: (preferences) => { current = { ...preferences }; } };
+}
+
+/** An unreadable or malformed file reads as the defaults and is not overwritten. Writes are replaced atomically within the same directory. */
+export function fileDevinSettings(path: string): DevinSettings {
+  return {
+    read() {
+      try {
+        const value = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
+        if (value.schemaVersion === SCHEMA_VERSION && typeof value.recommendedOnly === "boolean" && typeof value.showUsageStatus === "boolean") {
+          return { recommendedOnly: value.recommendedOnly, showUsageStatus: value.showUsageStatus };
+        }
+      } catch { /* A missing or corrupt file falls back to the defaults. */ }
+      return { ...DEFAULT_PREFERENCES };
+    },
+    write(preferences) {
+      mkdirSync(dirname(path), { recursive: true });
+      const temporary = `${path}.${process.pid}.tmp`;
+      writeFileSync(temporary, JSON.stringify({ schemaVersion: SCHEMA_VERSION, ...preferences }, null, 2) + "\n");
+      renameSync(temporary, path);
+    },
+  };
+}

package/src/pi/extension.ts

@@ -0,0 +1,80 @@
+import type { Model } from "@earendil-works/pi-ai";
+import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createDevinProvider, type DevinProvider } from "./provider.ts";
+import { DEVIN_STATE_ENTRY } from "./lifecycle.ts";
+import { registerDevinCommand, updateUsageStatus } from "./devin-command.ts";
+import { memoryDevinSettings, type DevinSettings } from "./devin-settings.ts";
+import { registerFusionCommand } from "./fusion-command.ts";
+import { memoryFusionSettings, type FusionSettings } from "./fusion-settings.ts";
+import { createSidekickTool, fusionOf, SIDEKICK_TOOL_NAME, type SidekickToolOptions } from "./sidekick.ts";
+
+type ProviderOptions = NonNullable<Parameters<typeof createDevinProvider>[0]>;
+export interface DevinExtensionOptions extends Omit<ProviderOptions, "fusion" | "listsAllExactModels" | "recommendedOnly"> {
+  /** Store for the `/devin-fusion` choice. Kept in memory only when omitted. */
+  fusionSettings?: FusionSettings;
+  /** Store for the `/devin` display settings. Kept in memory only when omitted. */
+  devinSettings?: DevinSettings;
+  /** The child Pi started as the sidekick registers no Fusion model, tool or command, and no `/devin` or status line. */
+  isFusionChild?: boolean;
+  /** Overrides the sidekick session location and how the child starts. The default location is the Pi agent directory. */
+  sidekick?: Partial<SidekickToolOptions>;
+}
+
+export function registerDevinExtension(pi: ExtensionAPI, options: DevinExtensionOptions = {}): DevinProvider {
+  const { fusionSettings, devinSettings, isFusionChild, sidekick: sidekickOptions, ...providerOptions } = options;
+  const settings = fusionSettings ?? memoryFusionSettings();
+  const preferences = isFusionChild ? undefined : devinSettings ?? memoryDevinSettings();
+  // The child Pi runs on the exact UID the lead chose, so it lists every exact UID and ignores the recommended filter.
+  const provider = createDevinProvider({
+    ...providerOptions, fusion: isFusionChild ? false : () => settings.read(), listsAllExactModels: isFusionChild === true,
+    recommendedOnly: preferences ? () => preferences.read().recommendedOnly : undefined,
+  });
+  pi.registerProvider(provider);
+  if (preferences) registerDevinCommand(pi, provider, preferences);
+  const refreshStatus = (context: Parameters<typeof updateUsageStatus>[0]) => { if (preferences) updateUsageStatus(context, provider, preferences); };
+  const sidekick = isFusionChild ? undefined
+    : createSidekickTool(pi, provider, { agentDir: sidekickOptions?.agentDir ?? getAgentDir, runtime: sidekickOptions?.runtime });
+  if (sidekick) {
+    pi.registerTool(sidekick.definition);
+    registerFusionCommand(pi, provider, settings);
+  }
+  // Enables the sidekick only for the Fusion model and leaves other extensions' and the user's active tools alone.
+  const syncSidekick = (model: Model<any> | undefined) => {
+    if (!sidekick) return;
+    const active = pi.getActiveTools(), isActive = active.includes(SIDEKICK_TOOL_NAME);
+    const shouldBeActive = fusionOf(provider, model) !== undefined;
+    if (shouldBeActive && !isActive) pi.setActiveTools([...active, SIDEKICK_TOOL_NAME]);
+    else if (!shouldBeActive && isActive) pi.setActiveTools(active.filter((name) => name !== SIDEKICK_TOOL_NAME));
+  };
+  pi.on("model_select", (event) => { syncSidekick(event.model); });
+  pi.on("input", (event) => { sidekick?.onInput(event.source); });
+  pi.on("session_start", (_event, context) => {
+    if (context.modelRegistry.getRegisteredNativeProvider("devin") !== provider) {
+      provider.shutdown();
+      throw new Error("The Devin provider ID collides with another registration. Remove the duplicate extension and reload.");
+    }
+    provider.attachSession({
+      getSessionId: () => context.sessionManager.getSessionId(),
+      getBranch: () => context.sessionManager.getBranch(),
+      append: (data) => pi.appendEntry(DEVIN_STATE_ENTRY, data),
+    });
+    sidekick?.onSessionStart(context.sessionManager.getSessionId());
+    syncSidekick(context.model);
+    refreshStatus(context);
+  });
+  pi.on("message_end", (event, context) => {
+    if (event.message.role === "assistant" && event.message.provider === "devin") refreshStatus(context);
+  });
+  pi.on("before_agent_start", () => { provider.lifecycle.begin("agent"); });
+  pi.on("agent_start", () => { provider.lifecycle.agentStarted(); });
+  // Host retry or overflow recovery can continue after agent_end.
+  pi.on("agent_settled", (_event, context) => { provider.lifecycle.finish(); refreshStatus(context); });
+  pi.on("session_before_compact", (event) => { provider.lifecycle.beforeCompaction(event.reason); });
+  pi.on("session_compact", (event) => { provider.lifecycle.afterCompaction(event.reason); });
+  pi.on("session_compact_failed", (event) => { provider.lifecycle.afterCompaction(event.reason); });
+  pi.on("session_before_tree", (event) => { if (event.preparation.userWantsSummary) provider.lifecycle.beforeTree(); });
+  pi.on("session_tree", (_event, context) => { provider.lifecycle.treeChanged(); refreshStatus(context); });
+  pi.on("cache_warming_decision", (_event, context) => context.model?.provider === "devin" ? { action: "stop" } : undefined);
+  pi.on("session_shutdown", () => { sidekick?.reset(); provider.shutdown(); });
+  return provider;
+}

package/src/pi/fusion-command.ts

@@ -0,0 +1,83 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { FUSION_MODEL_ID, type DevinModel, type FusionChoices, type FusionSelection } from "./models.ts";
+import { FusionPicker } from "./fusion-picker.ts";
+import type { FusionSettings } from "./fusion-settings.ts";
+import type { DevinProvider } from "./provider.ts";
+
+export const FUSION_COMMAND_NAME = "devin-fusion";
+const USAGE = `Usage: /${FUSION_COMMAND_NAME} or /${FUSION_COMMAND_NAME} <lead model ID> <sidekick model ID>`;
+
+function currentFusion(provider: DevinProvider): DevinModel | undefined {
+  return (provider.getModels() as readonly DevinModel[]).find((model) => model.id === FUSION_MODEL_ID);
+}
+
+/** Disambiguates duplicate display names in a select list with an index, and maps the chosen label back to its value. */
+async function choose<T>(ctx: ExtensionCommandContext, title: string, items: readonly T[], label: (item: T) => string, isCurrent: (item: T) => boolean) {
+  const names = items.map(label);
+  const labels = items.map((item, index) => {
+    const name = names.filter((other) => other === names[index]).length > 1 ? `${names[index]} (${index + 1})` : names[index];
+    return (isCurrent(item) ? "● " : "  ") + name;
+  });
+  const picked = await ctx.ui.select(title, labels);
+  return picked === undefined ? undefined : items[labels.indexOf(picked)];
+}
+
+async function pickInteractively(ctx: ExtensionCommandContext, choices: FusionChoices, current: FusionSelection | undefined): Promise<FusionSelection | undefined> {
+  const lead = await choose(ctx, "Devin Fusion · lead model", choices.leads, (item) => item.name, (item) => item.id === current?.leadID);
+  if (!lead) return undefined;
+  const groups = [...new Set(choices.sidekicks.map((item) => item.groupName))];
+  const currentGroup = choices.sidekicks.find((item) => item.id === current?.sidekickID)?.groupName;
+  const group = groups.length === 1 ? groups[0] : await choose(ctx, "Devin Fusion · sidekick model", groups, (item) => item, (item) => item === currentGroup);
+  if (group === undefined) return undefined;
+  const variants = choices.sidekicks.filter((item) => item.groupName === group);
+  const sidekick = variants.length === 1 ? variants[0]
+    : await choose(ctx, `Devin Fusion · sidekick variant (${group})`, variants, (item) => item.name, (item) => item.id === current?.sidekickID);
+  return sidekick ? { leadID: lead.id, sidekickID: sidekick.id } : undefined;
+}
+
+/**
+ * `/devin-fusion` only chooses the lead/sidekick pair. Whether Fusion is used is decided by picking Devin Fusion in `/model`.
+ * If the current model is Fusion, it is re-selected with the updated model object so the thinking level range matches.
+ */
+export function registerFusionCommand(pi: ExtensionAPI, provider: DevinProvider, settings: FusionSettings): void {
+  pi.registerCommand(FUSION_COMMAND_NAME, {
+    description: "Choose the lead and sidekick models for Devin Fusion (saved globally)",
+    handler: async (args, ctx) => {
+      const choices = provider.getFusionChoices();
+      if (!choices?.leads.length || !choices.sidekicks.length) {
+        ctx.ui.notify("No Devin models are available for Fusion. Check that the model list refreshed after /login.", "warning");
+        return;
+      }
+      const before = currentFusion(provider);
+      const tokens = args.trim().split(/\s+/).filter(Boolean);
+      let selection: FusionSelection | undefined;
+      if (tokens.length) {
+        const [leadID, sidekickID] = tokens;
+        if (tokens.length !== 2 || !choices.leads.some((item) => item.id === leadID) || !choices.sidekicks.some((item) => item.id === sidekickID)) {
+          ctx.ui.notify(`This model cannot be used for Fusion. ${USAGE}`, "error");
+          return;
+        }
+        selection = { leadID, sidekickID };
+      } else if (ctx.mode === "tui") {
+        selection = await ctx.ui.custom<FusionSelection | undefined>((tui, theme, _keybindings, done) => new FusionPicker({
+          choices, current: before?.devin.fusion, theme, requestRender: () => tui.requestRender(), done,
+        }));
+        if (!selection) return;
+      } else if (ctx.hasUI) {
+        // RPC clients cannot draw the custom screen, so they get the select dialogs.
+        selection = await pickInteractively(ctx, choices, before?.devin.fusion);
+        if (!selection) return;
+      } else {
+        ctx.ui.notify(before ? `Current: ${before.name}` : `No Devin Fusion pair is set. ${USAGE}`, "info");
+        return;
+      }
+      settings.write(selection);
+      provider.rebuildModels();
+      // Pi keeps model and availability snapshots. Rebuild them without network so `/model` and RPC lists update immediately.
+      await ctx.modelRegistry.refresh({ providers: ["devin"], allowNetwork: false });
+      const after = currentFusion(provider);
+      if (after && ctx.model?.provider === "devin" && ctx.model.id === FUSION_MODEL_ID) await pi.setModel(after);
+      ctx.ui.notify(after ? `Saved ${after.name}. Pick Devin Fusion in /model to use it.` : "The Fusion pair was saved, but it cannot be built from the current model list.", "info");
+    },
+  });
+}