@saibolla/ada 0.1.2

package/dist/cli.js

@@ -0,0 +1,404 @@
+import { config as loadDotenv } from "dotenv";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { homedir } from "node:os";
+import { parseArgs } from "node:util";
+// Load .env from Ada home first, then project dir overrides
+const adaEnvPath = resolve(process.env.ADA_HOME ?? homedir(), ".ada", ".env");
+if (existsSync(adaEnvPath)) {
+    loadDotenv({ path: adaEnvPath, quiet: true });
+}
+loadDotenv({ quiet: true }); // loads .env from cwd, overrides ada home values
+import { fileURLToPath } from "node:url";
+import { getUserName as getAlphaUserName, isLoggedIn as isAlphaLoggedIn, login as loginAlpha, logout as logoutAlpha, } from "@ada/alpha-hub/lib";
+import { AuthStorage, DefaultPackageManager, ModelRegistry, SettingsManager } from "@mariozechner/pi-coding-agent";
+import { syncBundledAssets } from "./bootstrap/sync.js";
+import { ensureAdaHome, getDefaultSessionDir, getAdaAgentDir, getAdaHome } from "./config/paths.js";
+import { launchPiChat } from "./pi/launch.js";
+import { CORE_PACKAGE_SOURCES, getOptionalPackagePresetSources, listOptionalPackagePresets } from "./pi/package-presets.js";
+import { normalizeAdaSettings, normalizeThinkingLevel, parseModelSpec } from "./pi/settings.js";
+import { getCurrentModelSpec, loginModelProvider, logoutModelProvider, printModelList, setDefaultModelSpec, } from "./model/commands.js";
+import { printSearchStatus } from "./search/commands.js";
+import { runDoctor, runStatus } from "./setup/doctor.js";
+import { setupPreviewDependencies } from "./setup/preview.js";
+import { runSetup } from "./setup/setup.js";
+import { runUpdate } from "./setup/update.js";
+import { ASH, printAsciiHeader, printInfo, printPanel, printSection, RESET, SAGE } from "./ui/terminal.js";
+import { cliCommandSections, formatCliWorkflowUsage, legacyFlags, readPromptSpecs, topLevelCommandNames, } from "../metadata/commands.mjs";
+const TOP_LEVEL_COMMANDS = new Set(topLevelCommandNames);
+function printHelpLine(usage, description) {
+    const width = 30;
+    const padding = Math.max(1, width - usage.length);
+    console.log(`  ${SAGE}${usage}${RESET}${" ".repeat(padding)}${ASH}${description}${RESET}`);
+}
+function printHelp(appRoot) {
+    const workflowCommands = readPromptSpecs(appRoot).filter((command) => command.section === "Research Workflows" && command.topLevelCli);
+    printAsciiHeader([
+        "Research-first agent shell built on Pi.",
+        "Use `ada setup` first if this is a new machine.",
+    ]);
+    printSection("Getting Started");
+    printInfo("ada");
+    printInfo("ada setup");
+    printInfo("ada doctor");
+    printInfo("ada model");
+    printInfo("ada search status");
+    printSection("Commands");
+    for (const section of cliCommandSections) {
+        for (const command of section.commands) {
+            printHelpLine(command.usage, command.description);
+        }
+    }
+    printSection("Research Workflows");
+    for (const command of workflowCommands) {
+        printHelpLine(formatCliWorkflowUsage(command), command.description);
+    }
+    printSection("Legacy Flags");
+    for (const flag of legacyFlags) {
+        printHelpLine(flag.usage, flag.description);
+    }
+    printSection("REPL");
+    printInfo("Inside the REPL, slash workflows come from the live prompt-template and extension command set.");
+}
+async function handleAlphaCommand(action) {
+    if (action === "login") {
+        const result = await loginAlpha();
+        const name = result.userInfo &&
+            typeof result.userInfo === "object" &&
+            "name" in result.userInfo &&
+            typeof result.userInfo.name === "string"
+            ? result.userInfo.name
+            : getAlphaUserName();
+        console.log(name ? `alphaXiv login complete: ${name}` : "alphaXiv login complete");
+        return;
+    }
+    if (action === "logout") {
+        logoutAlpha();
+        console.log("alphaXiv auth cleared");
+        return;
+    }
+    if (!action || action === "status") {
+        if (isAlphaLoggedIn()) {
+            const name = getAlphaUserName();
+            console.log(name ? `alphaXiv logged in as ${name}` : "alphaXiv logged in");
+        }
+        else {
+            console.log("alphaXiv not logged in");
+        }
+        return;
+    }
+    throw new Error(`Unknown alpha command: ${action}`);
+}
+async function handleModelCommand(subcommand, args, adaSettingsPath, adaAuthPath) {
+    if (!subcommand || subcommand === "list") {
+        printModelList(adaSettingsPath, adaAuthPath);
+        return;
+    }
+    if (subcommand === "login") {
+        await loginModelProvider(adaAuthPath, args[0], adaSettingsPath);
+        return;
+    }
+    if (subcommand === "logout") {
+        await logoutModelProvider(adaAuthPath, args[0]);
+        return;
+    }
+    if (subcommand === "set") {
+        const spec = args[0];
+        if (!spec) {
+            throw new Error("Usage: ada model set <provider/model>");
+        }
+        setDefaultModelSpec(adaSettingsPath, adaAuthPath, spec);
+        return;
+    }
+    throw new Error(`Unknown model command: ${subcommand}`);
+}
+async function handleUpdateCommand(workingDir, adaAgentDir, source) {
+    const settingsManager = SettingsManager.create(workingDir, adaAgentDir);
+    const packageManager = new DefaultPackageManager({
+        cwd: workingDir,
+        agentDir: adaAgentDir,
+        settingsManager,
+    });
+    packageManager.setProgressCallback((event) => {
+        if (event.type === "start") {
+            console.log(`Updating ${event.source}...`);
+        }
+        else if (event.type === "complete") {
+            console.log(`Updated ${event.source}`);
+        }
+        else if (event.type === "error") {
+            console.error(`Failed to update ${event.source}: ${event.message ?? "unknown error"}`);
+        }
+    });
+    await packageManager.update(source);
+    await settingsManager.flush();
+    console.log("All packages up to date.");
+}
+async function handlePackagesCommand(subcommand, args, workingDir, adaAgentDir) {
+    const settingsManager = SettingsManager.create(workingDir, adaAgentDir);
+    const configuredSources = new Set(settingsManager
+        .getPackages()
+        .map((entry) => (typeof entry === "string" ? entry : entry.source))
+        .filter((entry) => typeof entry === "string"));
+    if (!subcommand || subcommand === "list") {
+        printPanel("Ada Packages", [
+            "Core packages are installed by default to keep first-run setup fast.",
+        ]);
+        printSection("Core");
+        for (const source of CORE_PACKAGE_SOURCES) {
+            printInfo(source);
+        }
+        printSection("Optional");
+        for (const preset of listOptionalPackagePresets()) {
+            const installed = preset.sources.every((source) => configuredSources.has(source));
+            printInfo(`${preset.name}${installed ? " (installed)" : ""}  ${preset.description}`);
+        }
+        printInfo("Install with: ada packages install <preset>");
+        return;
+    }
+    if (subcommand !== "install") {
+        throw new Error(`Unknown packages command: ${subcommand}`);
+    }
+    const target = args[0];
+    if (!target) {
+        throw new Error("Usage: ada packages install <generative-ui|memory|session-search|all-extras>");
+    }
+    const sources = getOptionalPackagePresetSources(target);
+    if (!sources) {
+        throw new Error(`Unknown package preset: ${target}`);
+    }
+    const packageManager = new DefaultPackageManager({
+        cwd: workingDir,
+        agentDir: adaAgentDir,
+        settingsManager,
+    });
+    packageManager.setProgressCallback((event) => {
+        if (event.type === "start") {
+            console.log(`Installing ${event.source}...`);
+        }
+        else if (event.type === "complete") {
+            console.log(`Installed ${event.source}`);
+        }
+        else if (event.type === "error") {
+            console.error(`Failed to install ${event.source}: ${event.message ?? "unknown error"}`);
+        }
+    });
+    for (const source of sources) {
+        if (configuredSources.has(source)) {
+            console.log(`${source} already installed`);
+            continue;
+        }
+        await packageManager.install(source);
+    }
+    await settingsManager.flush();
+    console.log("Optional packages installed.");
+}
+function handleSearchCommand(subcommand) {
+    if (!subcommand || subcommand === "status") {
+        printSearchStatus();
+        return;
+    }
+    throw new Error(`Unknown search command: ${subcommand}`);
+}
+function loadPackageVersion(appRoot) {
+    try {
+        return JSON.parse(readFileSync(resolve(appRoot, "package.json"), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+export function resolveInitialPrompt(command, rest, oneShotPrompt, workflowCommands) {
+    if (oneShotPrompt) {
+        return oneShotPrompt;
+    }
+    if (!command) {
+        return undefined;
+    }
+    if (command === "chat") {
+        return rest.length > 0 ? rest.join(" ") : undefined;
+    }
+    if (workflowCommands.has(command)) {
+        return [`/${command}`, ...rest].join(" ").trim();
+    }
+    if (!TOP_LEVEL_COMMANDS.has(command)) {
+        return [command, ...rest].join(" ");
+    }
+    return undefined;
+}
+export async function main() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const appRoot = resolve(here, "..");
+    const adaVersion = loadPackageVersion(appRoot).version;
+    const bundledSettingsPath = resolve(appRoot, ".ada", "settings.json");
+    const adaHome = getAdaHome();
+    const adaAgentDir = getAdaAgentDir(adaHome);
+    ensureAdaHome(adaHome);
+    syncBundledAssets(appRoot, adaAgentDir);
+    const { values, positionals } = parseArgs({
+        args: process.argv.slice(2),
+        allowPositionals: true,
+        options: {
+            cwd: { type: "string" },
+            doctor: { type: "boolean" },
+            help: { type: "boolean" },
+            version: { type: "boolean" },
+            "alpha-login": { type: "boolean" },
+            "alpha-logout": { type: "boolean" },
+            "alpha-status": { type: "boolean" },
+            model: { type: "string" },
+            "new-session": { type: "boolean" },
+            prompt: { type: "string" },
+            "session-dir": { type: "string" },
+            "setup-preview": { type: "boolean" },
+            thinking: { type: "string" },
+        },
+    });
+    if (values.help) {
+        printHelp(appRoot);
+        return;
+    }
+    if (values.version) {
+        if (adaVersion) {
+            console.log(adaVersion);
+            return;
+        }
+        throw new Error("Unable to determine the installed Ada version.");
+    }
+    const workingDir = resolve(values.cwd ?? process.cwd());
+    const sessionDir = resolve(values["session-dir"] ?? getDefaultSessionDir(adaHome));
+    const adaSettingsPath = resolve(adaAgentDir, "settings.json");
+    const adaAuthPath = resolve(adaAgentDir, "auth.json");
+    const thinkingLevel = normalizeThinkingLevel(values.thinking ?? process.env.ADA_THINKING) ?? "medium";
+    normalizeAdaSettings(adaSettingsPath, bundledSettingsPath, thinkingLevel, adaAuthPath);
+    if (values.doctor) {
+        runDoctor({
+            settingsPath: adaSettingsPath,
+            authPath: adaAuthPath,
+            sessionDir,
+            workingDir,
+            appRoot,
+        });
+        return;
+    }
+    if (values["setup-preview"]) {
+        const result = setupPreviewDependencies();
+        console.log(result.message);
+        return;
+    }
+    if (values["alpha-login"]) {
+        await handleAlphaCommand("login");
+        return;
+    }
+    if (values["alpha-logout"]) {
+        await handleAlphaCommand("logout");
+        return;
+    }
+    if (values["alpha-status"]) {
+        await handleAlphaCommand("status");
+        return;
+    }
+    const [command, ...rest] = positionals;
+    if (command === "help") {
+        printHelp(appRoot);
+        return;
+    }
+    if (command === "setup") {
+        await runSetup({
+            settingsPath: adaSettingsPath,
+            bundledSettingsPath,
+            authPath: adaAuthPath,
+            workingDir,
+            sessionDir,
+            appRoot,
+            defaultThinkingLevel: thinkingLevel,
+        });
+        process.exit(0);
+    }
+    if (command === "update") {
+        runUpdate(appRoot);
+        process.exit(0);
+    }
+    if (command === "web") {
+        const { launchWebUI } = await import("./web/launch.js");
+        await launchWebUI({
+            appRoot,
+            workingDir,
+            port: rest[0] ? parseInt(rest[0]) : 3001,
+            model: values.model ?? process.env.ADA_MODEL,
+            thinking: values.thinking ?? process.env.ADA_THINKING,
+        });
+        return;
+    }
+    if (command === "doctor") {
+        runDoctor({
+            settingsPath: adaSettingsPath,
+            authPath: adaAuthPath,
+            sessionDir,
+            workingDir,
+            appRoot,
+        });
+        return;
+    }
+    if (command === "status") {
+        runStatus({
+            settingsPath: adaSettingsPath,
+            authPath: adaAuthPath,
+            sessionDir,
+            workingDir,
+            appRoot,
+        });
+        return;
+    }
+    if (command === "model") {
+        await handleModelCommand(rest[0], rest.slice(1), adaSettingsPath, adaAuthPath);
+        return;
+    }
+    if (command === "search") {
+        handleSearchCommand(rest[0]);
+        return;
+    }
+    if (command === "packages") {
+        await handlePackagesCommand(rest[0], rest.slice(1), workingDir, adaAgentDir);
+        return;
+    }
+    if (command === "update") {
+        await handleUpdateCommand(workingDir, adaAgentDir, rest[0]);
+        return;
+    }
+    if (command === "alpha") {
+        await handleAlphaCommand(rest[0]);
+        return;
+    }
+    const explicitModelSpec = values.model ?? process.env.ADA_MODEL;
+    if (explicitModelSpec) {
+        const modelRegistry = new ModelRegistry(AuthStorage.create(adaAuthPath));
+        const explicitModel = parseModelSpec(explicitModelSpec, modelRegistry);
+        if (!explicitModel) {
+            throw new Error(`Unknown model: ${explicitModelSpec}`);
+        }
+    }
+    if (!explicitModelSpec && !getCurrentModelSpec(adaSettingsPath) && process.stdin.isTTY && process.stdout.isTTY) {
+        // Run setup in a child process to avoid stdin/readline contamination
+        const { spawnSync } = await import("node:child_process");
+        const setupResult = spawnSync(process.execPath, [process.argv[1], "setup"], {
+            stdio: "inherit",
+            env: process.env,
+        });
+        if (setupResult.status !== 0 || !getCurrentModelSpec(adaSettingsPath)) {
+            return;
+        }
+        normalizeAdaSettings(adaSettingsPath, bundledSettingsPath, thinkingLevel, adaAuthPath);
+    }
+    await launchPiChat({
+        appRoot,
+        workingDir,
+        sessionDir,
+        adaAgentDir,
+        adaVersion,
+        thinkingLevel,
+        explicitModelSpec,
+        oneShotPrompt: values.prompt,
+        initialPrompt: resolveInitialPrompt(command, rest, values.prompt, new Set(readPromptSpecs(appRoot).filter((s) => s.topLevelCli).map((s) => s.name))),
+    });
+}

package/dist/config/paths.js

@@ -0,0 +1,32 @@
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+export function getAdaHome() {
+    return resolve(process.env.ADA_HOME ?? homedir(), ".ada");
+}
+export function getAdaAgentDir(home = getAdaHome()) {
+    return resolve(home, "agent");
+}
+export function getAdaMemoryDir(home = getAdaHome()) {
+    return resolve(home, "memory");
+}
+export function getAdaStateDir(home = getAdaHome()) {
+    return resolve(home, ".state");
+}
+export function getDefaultSessionDir(home = getAdaHome()) {
+    return resolve(home, "sessions");
+}
+export function getBootstrapStatePath(home = getAdaHome()) {
+    return resolve(getAdaStateDir(home), "bootstrap.json");
+}
+export function ensureAdaHome(home = getAdaHome()) {
+    for (const dir of [
+        home,
+        getAdaAgentDir(home),
+        getAdaMemoryDir(home),
+        getAdaStateDir(home),
+        getDefaultSessionDir(home),
+    ]) {
+        mkdirSync(dir, { recursive: true });
+    }
+}

package/dist/index.js

@@ -0,0 +1,10 @@
+import { ensureSupportedNodeVersion } from "./system/node-version.js";
+async function run() {
+    ensureSupportedNodeVersion();
+    const { main } = await import("./cli.js");
+    await main();
+}
+run().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+});

package/dist/model/catalog.js

@@ -0,0 +1,255 @@
+import { AuthStorage, ModelRegistry } from "@mariozechner/pi-coding-agent";
+const PROVIDER_LABELS = {
+    anthropic: "Anthropic",
+    openai: "OpenAI",
+    "openai-codex": "OpenAI Codex",
+    openrouter: "OpenRouter",
+    google: "Google",
+    "google-gemini-cli": "Google Gemini CLI",
+    zai: "Z.AI / GLM",
+    minimax: "MiniMax",
+    "minimax-cn": "MiniMax (China)",
+    "github-copilot": "GitHub Copilot",
+    "vercel-ai-gateway": "Vercel AI Gateway",
+    opencode: "OpenCode",
+    "opencode-go": "OpenCode Go",
+    "kimi-coding": "Kimi / Moonshot",
+    xai: "xAI",
+    groq: "Groq",
+    mistral: "Mistral",
+    cerebras: "Cerebras",
+    huggingface: "Hugging Face",
+    "amazon-bedrock": "Amazon Bedrock",
+    "azure-openai-responses": "Azure OpenAI Responses",
+};
+const RESEARCH_MODEL_PREFERENCES = [
+    {
+        spec: "anthropic/claude-opus-4-6",
+        reason: "strong long-context reasoning for source-heavy research work",
+    },
+    {
+        spec: "anthropic/claude-opus-4-5",
+        reason: "strong long-context reasoning for source-heavy research work",
+    },
+    {
+        spec: "anthropic/claude-sonnet-4-6",
+        reason: "balanced reasoning and speed for iterative research sessions",
+    },
+    {
+        spec: "anthropic/claude-sonnet-4-5",
+        reason: "balanced reasoning and speed for iterative research sessions",
+    },
+    {
+        spec: "openai/gpt-5.4",
+        reason: "strong general reasoning and drafting quality for research tasks",
+    },
+    {
+        spec: "openai/gpt-5",
+        reason: "strong general reasoning and drafting quality for research tasks",
+    },
+    {
+        spec: "openai-codex/gpt-5.4",
+        reason: "strong research + coding balance when Pi exposes Codex directly",
+    },
+    {
+        spec: "google/gemini-3-pro-preview",
+        reason: "good fallback for broad web-and-doc research work",
+    },
+    {
+        spec: "google/gemini-2.5-pro",
+        reason: "good fallback for broad web-and-doc research work",
+    },
+    {
+        spec: "google-antigravity/gemini-3.1-pro-high",
+        reason: "strong research model via Antigravity",
+    },
+    {
+        spec: "google-antigravity/gemini-3-flash",
+        reason: "fast research model via Antigravity",
+    },
+    {
+        spec: "openrouter/openai/gpt-5.1-codex",
+        reason: "good routed fallback when only OpenRouter is configured",
+    },
+    {
+        spec: "zai/glm-5",
+        reason: "good fallback when GLM is the available research model",
+    },
+    {
+        spec: "kimi-coding/kimi-k2-thinking",
+        reason: "good fallback when Kimi is the available research model",
+    },
+];
+const PROVIDER_SORT_ORDER = [
+    "anthropic",
+    "openai",
+    "openai-codex",
+    "google",
+    "openrouter",
+    "zai",
+    "kimi-coding",
+    "minimax",
+    "minimax-cn",
+    "github-copilot",
+    "vercel-ai-gateway",
+];
+function formatProviderLabel(provider) {
+    return PROVIDER_LABELS[provider] ?? provider;
+}
+function modelSpec(model) {
+    return `${model.provider}/${model.id}`;
+}
+function compareByResearchPreference(left, right) {
+    const leftSpec = modelSpec(left);
+    const rightSpec = modelSpec(right);
+    const leftIndex = RESEARCH_MODEL_PREFERENCES.findIndex((entry) => entry.spec === leftSpec);
+    const rightIndex = RESEARCH_MODEL_PREFERENCES.findIndex((entry) => entry.spec === rightSpec);
+    if (leftIndex !== -1 || rightIndex !== -1) {
+        if (leftIndex === -1)
+            return 1;
+        if (rightIndex === -1)
+            return -1;
+        return leftIndex - rightIndex;
+    }
+    const leftProviderIndex = PROVIDER_SORT_ORDER.indexOf(left.provider);
+    const rightProviderIndex = PROVIDER_SORT_ORDER.indexOf(right.provider);
+    if (leftProviderIndex !== -1 || rightProviderIndex !== -1) {
+        if (leftProviderIndex === -1)
+            return 1;
+        if (rightProviderIndex === -1)
+            return -1;
+        return leftProviderIndex - rightProviderIndex;
+    }
+    return modelSpec(left).localeCompare(modelSpec(right));
+}
+function sortProviders(left, right) {
+    if (left.configured !== right.configured) {
+        return left.configured ? -1 : 1;
+    }
+    if (left.current !== right.current) {
+        return left.current ? -1 : 1;
+    }
+    if (left.recommended !== right.recommended) {
+        return left.recommended ? -1 : 1;
+    }
+    const leftIndex = PROVIDER_SORT_ORDER.indexOf(left.id);
+    const rightIndex = PROVIDER_SORT_ORDER.indexOf(right.id);
+    if (leftIndex !== -1 || rightIndex !== -1) {
+        if (leftIndex === -1)
+            return 1;
+        if (rightIndex === -1)
+            return -1;
+        return leftIndex - rightIndex;
+    }
+    return left.label.localeCompare(right.label);
+}
+function createModelRegistry(authPath) {
+    return new ModelRegistry(AuthStorage.create(authPath));
+}
+// Models known to be incompatible with certain providers due to tool schema limitations
+const BLOCKED_MODEL_PATTERNS = [
+    // Claude models via Google Antigravity don't support patternProperties/const in tool schemas
+    { provider: "google-antigravity", pattern: /^claude-/ },
+];
+function isBlockedModel(model) {
+    return BLOCKED_MODEL_PATTERNS.some((rule) => model.provider === rule.provider && rule.pattern.test(model.id));
+}
+export function getAvailableModelRecords(authPath) {
+    return createModelRegistry(authPath)
+        .getAvailable()
+        .map((model) => ({ provider: model.provider, id: model.id, name: model.name }))
+        .filter((model) => !isBlockedModel(model));
+}
+export function getSupportedModelRecords(authPath) {
+    return createModelRegistry(authPath)
+        .getAll()
+        .map((model) => ({ provider: model.provider, id: model.id, name: model.name }));
+}
+export function chooseRecommendedModel(authPath) {
+    const available = getAvailableModelRecords(authPath).sort(compareByResearchPreference);
+    if (available.length === 0) {
+        return undefined;
+    }
+    const matchedPreference = RESEARCH_MODEL_PREFERENCES.find((entry) => entry.spec === modelSpec(available[0]));
+    if (matchedPreference) {
+        return matchedPreference;
+    }
+    return {
+        spec: modelSpec(available[0]),
+        reason: "best currently authenticated fallback for research work",
+    };
+}
+export function buildModelStatusSnapshotFromRecords(supported, available, current) {
+    const availableSpecs = available
+        .slice()
+        .sort(compareByResearchPreference)
+        .map((model) => modelSpec(model));
+    const recommended = available.length > 0
+        ? (() => {
+            const preferred = available.slice().sort(compareByResearchPreference)[0];
+            const matched = RESEARCH_MODEL_PREFERENCES.find((entry) => entry.spec === modelSpec(preferred));
+            return {
+                spec: modelSpec(preferred),
+                reason: matched?.reason ?? "best currently authenticated fallback for research work",
+            };
+        })()
+        : undefined;
+    const currentValid = current ? availableSpecs.includes(current) : false;
+    const providerMap = new Map();
+    for (const model of supported) {
+        const provider = providerMap.get(model.provider) ?? {
+            id: model.provider,
+            label: formatProviderLabel(model.provider),
+            supportedModels: 0,
+            availableModels: 0,
+            configured: false,
+            current: false,
+            recommended: false,
+        };
+        provider.supportedModels += 1;
+        provider.current ||= current?.startsWith(`${model.provider}/`) ?? false;
+        provider.recommended ||= recommended?.spec.startsWith(`${model.provider}/`) ?? false;
+        providerMap.set(model.provider, provider);
+    }
+    for (const model of available) {
+        const provider = providerMap.get(model.provider) ?? {
+            id: model.provider,
+            label: formatProviderLabel(model.provider),
+            supportedModels: 0,
+            availableModels: 0,
+            configured: false,
+            current: false,
+            recommended: false,
+        };
+        provider.availableModels += 1;
+        provider.configured = true;
+        provider.current ||= current?.startsWith(`${model.provider}/`) ?? false;
+        provider.recommended ||= recommended?.spec.startsWith(`${model.provider}/`) ?? false;
+        providerMap.set(model.provider, provider);
+    }
+    const guidance = [];
+    if (available.length === 0) {
+        guidance.push("No authenticated Pi models are available yet.");
+        guidance.push("Run `ada model login <provider>` or add provider credentials that Pi can see.");
+        guidance.push("After auth is in place, rerun `ada model list` or `ada setup model`.");
+    }
+    else if (!current) {
+        guidance.push(`No default research model is set. Recommended: ${recommended?.spec}.`);
+        guidance.push("Run `ada model set <provider/model>` or `ada setup model`.");
+    }
+    else if (!currentValid) {
+        guidance.push(`Configured default model is unavailable: ${current}.`);
+        if (recommended) {
+            guidance.push(`Switch to the current research recommendation: ${recommended.spec}.`);
+        }
+    }
+    return {
+        current,
+        currentValid,
+        recommended: recommended?.spec,
+        recommendationReason: recommended?.reason,
+        availableModels: availableSpecs,
+        providers: Array.from(providerMap.values()).sort(sortProviders),
+        guidance,
+    };
+}