mindcraft 0.1.4-0 → 0.1.4-2

package/README.md

@@ -1,60 +1,50 @@
-<h1 align="center">🧠mindcraft⛏️</h1>
-<h1 align="center">
-  <a href="https://trendshift.io/repositories/9163" target="_blank"><img src="https://trendshift.io/api/badge/repositories/9163" alt="kolbytn%2Fmindcraft | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
-</h1>
-
-<p align="center">Crafting minds for Minecraft with LLMs and <a href="https://prismarinejs.github.io/mineflayer/#/">Mineflayer!</a></p>
-
-<p align="center">
-  <a href="https://github.com/mindcraft-bots/mindcraft/blob/main/FAQ.md">FAQ</a> | 
-  <a href="https://discord.gg/mp73p35dzC">Discord Support</a> | 
-  <a href="https://www.youtube.com/watch?v=gRotoL8P8D8">Video Tutorial</a> | 
-  <a href="https://kolbynottingham.com/mindcraft/">Blog Post</a> | 
-  <a href="https://mindcraft-minecollab.github.io/index.html">Paper Website</a> | 
-  <a href="https://github.com/mindcraft-bots/mindcraft/blob/main/minecollab.md">MineCollab</a>
-</p>
+# mindcraft
 
-> [!Caution]
-Do not connect this bot to public servers with coding enabled. This project allows an LLM to write/execute code on your computer. The code is sandboxed, but still vulnerable to injection attacks. Code writing is disabled by default, you can enable it by setting `allow_insecure_coding` to `true` in `settings.js`. Ye be warned.
+LLM agents that play Minecraft, built on [mineflayer](https://prismarinejs.github.io/mineflayer/#/).
 
-# Getting Started
-## Requirements
+> [!Note]
+> This is an **unofficial fork** of [mindcraft-bots/mindcraft](https://github.com/mindcraft-bots/mindcraft) that packages it as an npm CLI with a browser-based setup. See [upstream issue #758](https://github.com/mindcraft-bots/mindcraft/issues/758) for context. All credit for the agent itself goes to the upstream authors.
 
-- [Minecraft Java Edition](https://www.minecraft.net/en-us/store/minecraft-java-bedrock-edition-pc) (up to v1.21.11, recommend v1.21.6)
-- [Node.js Installed](https://nodejs.org/) (Node v18 or v20 LTS recommended. Node v24+ may cause issues with native dependencies)
-- At least one API key from a supported API provider. See [supported APIs](#model-customization). OpenAI is the default.
+> [!Caution]
+> Don't connect to public servers with `allow_insecure_coding` enabled — it lets the LLM write and run code on your machine. It's off by default.
 
-> [!Important]
-> If installing node on windows, ensure you check `Automatically install the necessary tools`
->
-> If you encounter `npm install` errors on macOS, see the [FAQ](FAQ.md#common-issues) for troubleshooting native module build issues
+## Quick start
 
-## Install and Run
+```bash
+npx mindcraft ui
+```
 
-1. Make sure you have the requirements above.
+This opens a web UI where you set your Minecraft server address, add an API key, and create an agent. Settings are saved to `~/.config/mindcraft/` so subsequent runs pick up where you left off.
 
-2. Download the [latest release](https://github.com/mindcraft-bots/mindcraft/releases/latest) and unzip it, or clone the repository.
+You'll need:
+- [Minecraft Java Edition](https://www.minecraft.net/en-us/store/minecraft-java-bedrock-edition-pc) (up to v1.21.11; v1.21.6 recommended), with a world open to LAN
+- [Node.js](https://nodejs.org/) 18 or 20 (v24+ may have native-dep issues)
+- An API key for one of the [supported providers](#supported-providers) (or a local Ollama model)
 
-3. Rename `keys.example.json` to `keys.json` and fill in your API keys (you only need one). The desired model is set in `andy.json` or other profiles. For other models refer to the table below.
+For programmatic use:
 
-4. In terminal/command prompt, run `npm install` from the installed directory
+```js
+import { init, createAgent } from 'mindcraft';
+await init();
+await createAgent({ host: 'localhost', port: 25565, profile: { name: 'andy', model: 'gpt-4o-mini' } });
+```
 
-5. Start a minecraft world and open it to LAN on localhost port `55916`
+## Running from a checkout
 
-6. Run `node main.js` from the installed directory
+If you want to hack on it, clone and `npm install`, start a Minecraft world open to LAN, then `node main.js`. Put API keys in `keys.json` (copy `keys.example.json`) and pick a profile in `settings.js`. The [FAQ](FAQ.md) covers common install errors.
 
-If you encounter issues, check the [FAQ](https://github.com/mindcraft-bots/mindcraft/blob/main/FAQ.md) or find support on [discord](https://discord.gg/mp73p35dzC). We are currently not very responsive to github issues. To run tasks please refer to [Minecollab Instructions](minecollab.md#installation)
+To run benchmark tasks: `node main.js --task_path tasks/basic/single_agent.json --task_id gather_oak_logs` — see [MineCollab](minecollab.md).
 
+## Configuration
 
-# Configuration
-## Model Customization
+The `npx mindcraft` UI writes config to `~/.config/mindcraft/config.json` and `keys.json`. Don't edit `settings.js` — it's defaults only. To override from the shell, use `SETTINGS_JSON='{"host":"..."}' node main.js` or `--profiles ./foo.json`.
 
-You can configure project details in `settings.js`. [See file.](settings.js)
+Agent name, model and prompts live in a profile JSON (e.g. `andy.json`). The model can be a string like `"gpt-4o-mini"` or `"anthropic/claude-sonnet-4-6"`, or an object — see [Model Specifications](#model-specifications).
 
-You can configure the agent's name, model, and prompts in their profile like `andy.json`. The model can be specified with the `model` field, with values like `model: "gemini-2.5-pro"`. You will need the correct API key for the API provider you choose. See all supported APIs below.
+## Supported providers
 
 <details>
-<summary><strong>⭐ VIEW SUPPORTED APIs ⭐</strong></summary>
+<summary>All supported APIs</summary>
 
 | API Name | Config Variable| Docs |
 |------|------|------|
@@ -87,59 +77,11 @@ To install our models, install ollama and run the following terminal command:
 ollama pull sweaterdog/andy-4:micro-q8_0 && ollama pull embeddinggemma
 ```
 
-## Online Servers
-To connect to online servers your bot will need an official Microsoft/Minecraft account. You can use your own personal one, but will need another account if you want to connect too and play with it. To connect, change these lines in `settings.js`:
-```javascript
-"host": "111.222.333.444",
-"port": 55920,
-"auth": "microsoft",
-
-// rest is same...
-```
-> [!Important]
-> The bot's name in the profile.json must exactly match the Minecraft profile name! Otherwise the bot will spam talk to itself.
+## Online servers
 
-To use different accounts, Mindcraft will connect with the account that the Minecraft launcher is currently using. You can switch accounts in the launcher, then run `node main.js`, then switch to your main account after the bot has connected.
+To connect to an online server the agent needs a real Microsoft/Minecraft account. Set `auth: "microsoft"` in the Server panel (or your config). The agent's profile name must exactly match the Minecraft account's username, or it will talk to itself. Mindcraft uses whichever account is active in the Minecraft launcher; switch accounts there, start the agent, then switch back.
 
-## Tasks
-
-Tasks automatically start the bot with a prompt and a goal item to acquire or blueprint to construct. To run a simple task that involves collecting 4 oak_logs run 
-
-`node main.js --task_path tasks/basic/single_agent.json --task_id gather_oak_logs`
-
-Here is an example task json format: 
-
-```
-{
-    "gather_oak_logs": {
-      "goal": "Collect at least four logs",
-      "initial_inventory": {
-        "0": {
-          "wooden_axe": 1
-        }
-      },
-      "agent_count": 1,
-      "target": "oak_log",
-      "number_of_target": 4,
-      "type": "techtree",
-      "max_depth": 1,
-      "depth": 0,
-      "timeout": 300,
-      "blocked_actions": {
-        "0": [],
-        "1": []
-      },
-      "missing_items": [],
-      "requires_ctable": false
-    }
-}
-```
-
-The `initial_inventory` is what the bot will have at the start of the episode, `target` refers to the target item and `number_of_target` refers to the number of target items the agent needs to collect to successfully complete the task. 
-
-If you want more optimization and automatic launching of the minecraft world, you will need to follow the instructions in [Minecollab Instructions](minecollab.md#installation)
-
-## Docker Container
+## Docker
 
 If you intend to `allow_insecure_coding`, it is a good idea to run the app in a docker container to reduce risks of running unknown code. This is strongly recommended before connecting to remote servers, although still does not guarantee complete safety.
 
@@ -151,21 +93,11 @@ or simply
 docker-compose up --build
 ```
 
-When running in docker, if you want the bot to join your local minecraft server, you have to use a special host address `host.docker.internal` to call your localhost from inside your docker container. Put this into your [settings.js](settings.js):
-
-```javascript
-"host": "host.docker.internal", // instead of "localhost", to join your local minecraft from inside the docker container
-```
-
-To connect to an unsupported minecraft version, you can try to use [viaproxy](services/viaproxy/README.md)
-
-# Bot Profiles
+When running in docker, use `host.docker.internal` instead of `localhost` to reach a Minecraft server on your host machine. For unsupported Minecraft versions, try [viaproxy](services/viaproxy/README.md).
 
-Bot profiles are json files (such as `andy.json`) that define:
+# Profiles
 
-1. Bot backend LLMs to use for talking, coding, and embedding.
-2. Prompts used to influence the bot's behavior.
-3. Examples help the bot perform tasks.
+A profile JSON (e.g. `andy.json`) defines the agent's name, which LLMs it uses for chat/coding/embedding, its prompts, and example conversations.
 
 ## Model Specifications
 
@@ -217,16 +149,9 @@ If you try to use an unsupported model, then it will default to a simple word-ov
 
 Voice synthesis models are used to narrate bot responses and specified with `speak_model`. This field is parsed differently than other models and only supports strings formatted as `"{api}/{model}/{voice}"`, like `"openai/tts-1/echo"`. We only support `openai` and `google` for voice synthesis.
 
-## Specifying Profiles via Command Line
-
-By default, the program will use the profiles specified in `settings.js`. You can specify one or more agent profiles using the `--profiles` argument: `node main.js --profiles ./profiles/andy.json ./profiles/jill.json`
-
-
 # Contributing
 
-We welcome contributions to the project! We are generally less responsive to github issues, and more responsive to pull requests. Join the [discord](https://discord.gg/mp73p35dzC) for more active support and direction.
-
-While AI generated code is allowed, please vet it carefully. Submitting tons of sloppy code and documentation actively harms development.
+Please contribute upstream at [mindcraft-bots/mindcraft](https://github.com/mindcraft-bots/mindcraft) — this fork tracks it. Join the upstream [discord](https://discord.gg/mp73p35dzC) for support.
 
 ## Patches
 

package/bin/mindcraft.js

@@ -46,34 +46,39 @@ async function main() {
     if (opts.cmd !== 'ui') return;
 
     // Load persisted config from ~/.config/mindcraft so a restart picks up where the
-    // wizard left off: keys → process.env, server settings → spec defaults,
-    // saved bots → recreated.
+    // setup panels left off: keys → process.env, server + settings → spec defaults,
+    // saved agents → recreated. Merge order is settings_spec.json defaults
+    // ← config.settings ← config.server ← per-agent overrides.
     userconfig.loadKeysIntoEnv();
     const config = userconfig.getConfig();
     overrideSpecDefaults({
         data_dir: opts.dataDir,
+        ...(config?.settings || {}),
         ...(config?.server || {}),
     });
 
     await init(false, opts.port, opts.open);
     console.log(`\nMindcraft UI: http://localhost:${opts.port}`);
-    console.log(`Bot data dir: ${opts.dataDir}`);
+    console.log(`Agent data dir: ${opts.dataDir}`);
 
-    if (config?.bots?.length) {
+    const agents = config?.agents || config?.bots; // .bots = legacy key
+    if (agents?.length) {
         const profiles = Object.fromEntries(userconfig.listProfiles().map(p => [p.name, p]));
-        for (const bot of config.bots) {
-            const profile = profiles[bot.profile];
-            if (!profile) { console.warn(`Skipping bot "${bot.profile}": profile not found`); continue; }
-            console.log(`Restoring bot: ${bot.profile}`);
+        for (const a of agents) {
+            const profile = profiles[a.profile];
+            if (!profile) { console.warn(`Skipping agent "${a.profile}": profile not found`); continue; }
+            console.log(`Restoring agent: ${a.profile}`);
             await createAgent({
+                ...(config.settings || {}),
                 ...(config.server || {}),
+                ...(a.settings || {}),
                 data_dir: opts.dataDir,
-                base_profile: bot.base_profile || 'assistant',
+                base_profile: a.base_profile || 'assistant',
                 profile,
             });
         }
     } else {
-        console.log(`No saved bots — open the UI to run setup.\n`);
+        console.log(`No saved agents — open the UI to run setup.\n`);
     }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "mindcraft",
-    "version": "0.1.4-0",
+    "version": "0.1.4-2",
     "type": "module",
     "publishConfig": {
         "tag": "latest"
@@ -65,8 +65,8 @@
         "node-canvas-webgl": "^0.3.0"
     },
     "overrides": {
-      "canvas": "^3.1.0",
-      "gl": "^8.1.6"
+        "canvas": "^3.1.0",
+        "gl": "^8.1.6"
     },
     "scripts": {
         "postinstall": "patch-package",

package/settings.js

@@ -1,3 +1,13 @@
+// Default settings for the `node main.js` entrypoint.
+//
+// DON'T EDIT THIS FILE for local config — that just dirties your git checkout.
+// Instead, override via:
+//   - `npx mindcraft ui` (writes ~/.config/mindcraft/config.json), or
+//   - the SETTINGS_JSON env var: SETTINGS_JSON='{"host":"..."}' node main.js, or
+//   - CLI flags: node main.js --profiles ./foo.json
+//
+// The web UI / `npx mindcraft` flow does not read this file at all; it uses
+// settings_spec.json defaults overlaid with ~/.config/mindcraft/config.json.
 const settings = {
     "minecraft_version": "auto", // or specific version like "1.21.6"
     "host": "127.0.0.1", // or "localhost", "your.ip.address.here"

package/src/agent/agent.js

@@ -11,7 +11,7 @@ import { SelfPrompter } from './self_prompter.js';
 import convoManager from './conversation.js';
 import { handleTranslation, handleEnglishTranslation } from '../utils/translator.js';
 import { addBrowserViewer } from './vision/browser_viewer.js';
-import { serverProxy, sendOutputToServer } from './mindserver_proxy.js';
+import { serverProxy, sendOutputToServer, sendLogToServer } from './mindserver_proxy.js';
 import settings from './settings.js';
 import { Task } from './tasks/tasks.js';
 import { speak } from './speak.js';
@@ -108,7 +108,11 @@ export class Agent {
         this.bot.once('spawn', async () => {
             try {
                 clearTimeout(spawnTimeout);
-                addBrowserViewer(this.bot, count_id);
+                const viewer = await addBrowserViewer(this.bot, count_id);
+                if (viewer.error) {
+                    serverProxy.getSocket()?.emit('viewer-status', this.name, { error: viewer.error });
+                    sendOutputToServer(this.name, `Viewer unavailable: ${viewer.error}`);
+                }
                 console.log('Initializing vision intepreter...');
                 // VisionInterpreter -> camera.js -> node-canvas-webgl, whose native
                 // deps (gl, canvas) are optionalDependencies and may not have built.
@@ -303,6 +307,7 @@ export class Agent {
         // Now translate the message
         message = await handleEnglishTranslation(message);
         console.log('received message from', source, ':', message);
+        sendLogToServer(this.name, self_prompt ? 'thinking' : 'user', `${source}: ${message}`);
 
         const checkInterrupt = () => this.self_prompter.shouldInterrupt(self_prompt) || this.shut_up || convoManager.responseScheduledFor(source);
         
@@ -328,6 +333,7 @@ export class Agent {
             let res = await this.prompter.promptConvo(history);
 
             console.log(`${this.name} full response to ${source}: ""${res}""`);
+            sendLogToServer(this.name, 'thinking', res);
 
             if (res.trim().length === 0) {
                 console.warn('no response')

package/src/agent/commands/actions.js

@@ -35,7 +35,7 @@ export const actionsList = [
         perform: async function(agent, prompt) {
             // just ignore prompt - it is now in context in chat history
             if (!settings.allow_insecure_coding) { 
-                agent.openChat('newAction is disabled. Enable with allow_insecure_coding=true in settings.js');
+                agent.openChat('newAction is disabled. Enable with allow_insecure_coding=true in agent settings.');
                 return "newAction not allowed! Code writing is disabled in settings. Notify the user.";
             }
             let result = "";

package/src/agent/mindserver_proxy.js

@@ -134,3 +134,9 @@ export function sendBotChatToServer(agentName, json) {
 export function sendOutputToServer(agentName, message) {
     serverProxy.getSocket().emit('bot-output', agentName, message);
 }
+
+// structured conversation log for the UI's per-agent log panel
+// role: 'user' | 'bot' | 'thinking' | 'error'
+export function sendLogToServer(agentName, role, text) {
+    serverProxy.getSocket()?.emit('agent-log', agentName, { role, text });
+}

package/src/agent/vision/browser_viewer.js

@@ -1,8 +1,31 @@
 import settings from '../settings.js';
-import prismarineViewer from 'prismarine-viewer';
-const mineflayerViewer = prismarineViewer.mineflayer;
+import net from 'net';
 
-export function addBrowserViewer(bot, count_id) {
-    if (settings.render_bot_view)
-        mineflayerViewer(bot, { port: 3000+count_id, firstPerson: true, });
-}
+// prismarine-viewer starts an express server on a fixed port and doesn't expose
+// the http.Server, so an EADDRINUSE becomes an uncaught exception that kills
+// the agent process. Probe the port first, and lazy-import so missing optional
+// native deps also degrade to "no viewer" instead of crashing.
+function portFree(port) {
+    return new Promise((resolve) => {
+        const s = net.createServer()
+            .once('error', () => resolve(false))
+            .once('listening', () => s.close(() => resolve(true)))
+            .listen(port, '127.0.0.1');
+    });
+}
+
+export async function addBrowserViewer(bot, count_id) {
+    if (!settings.render_bot_view) return { ok: false, disabled: true };
+    const port = 3000 + count_id;
+    try {
+        if (!(await portFree(port))) {
+            throw new Error(`port ${port} is already in use`);
+        }
+        const { default: prismarineViewer } = await import('prismarine-viewer');
+        prismarineViewer.mineflayer(bot, { port, firstPerson: true });
+        return { ok: true, port };
+    } catch (err) {
+        console.warn(`prismarine-viewer unavailable (port ${port}):`, err.message);
+        return { ok: false, port, error: err.message };
+    }
+}

package/src/mindcraft/mcserver.js

@@ -131,7 +131,7 @@ export async function getServer(host, port, version) {
 
     // Server not found
     if (server == null) 
-        throw new Error(`MC server not found. (Host: ${host}, Port: ${port}) Check the host and port in settings.js, and ensure the server is running and open to public or LAN.`);
+        throw new Error(`MC server not found. (Host: ${host}, Port: ${port}) Check the host and port in your server config, and ensure the server is running and open to public or LAN.`);
 
     serverString = `(Host: ${server.host}, Port: ${server.port}, Version: ${server.version})`;
 
@@ -146,7 +146,7 @@ export async function getServer(host, port, version) {
      if (!isSupported)
         throw new Error(`MC server was found ${serverString}, but version is unsupported. Supported versions are: ${mc.supportedVersions.join(", ")}.`);
     else if (version !== "auto" && server.version !== version)
-        throw new Error(`MC server was found ${serverString}, but version is incorrect. Expected ${version}, but found ${server.version}. Check the server version in settings.js.`);
+        throw new Error(`MC server was found ${serverString}, but version is incorrect. Expected ${version}, but found ${server.version}. Check the server version in your config.`);
     else
         console.log(`MC server found. ${serverString}`);
 

package/src/mindcraft/mindserver.js

@@ -5,6 +5,7 @@ import path from 'path';
 import { fileURLToPath } from 'url';
 import * as mindcraft from './mindcraft.js';
 import * as userconfig from './userconfig.js';
+import { configuredProviders } from './providers.js';
 import { readFileSync } from 'fs';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -35,10 +36,16 @@ class AgentConnection {
         this.in_game = false;
         this.full_state = null;
         this.viewer_port = viewer_port;
+        this.viewer_error = null;
+        this.log = [];
     }
     setSettings(settings) {
         this.settings = settings;
     }
+    appendLog(entry) {
+        this.log.push({ ...entry, ts: Date.now() });
+        if (this.log.length > 500) this.log.shift();
+    }
 }
 
 export function registerAgent(settings, viewer_port) {
@@ -218,21 +225,40 @@ export function createMindServer(host_public = false, port = 8080) {
 		});
 
         socket.on('bot-output', (agentName, message) => {
+            agent_connections[agentName]?.appendLog({ role: 'bot', text: message });
             io.emit('bot-output', agentName, message);
         });
 
+        socket.on('agent-log', (agentName, entry) => {
+            agent_connections[agentName]?.appendLog(entry);
+            io.emit('agent-log', agentName, entry);
+        });
+
+        socket.on('get-agent-log', (agentName, callback) => {
+            callback({ log: agent_connections[agentName]?.log || [] });
+        });
+
+        socket.on('viewer-status', (agentName, status) => {
+            if (agent_connections[agentName]) {
+                agent_connections[agentName].viewer_error = status.error || null;
+                agentsStatusUpdate();
+            }
+        });
+
         socket.on('listen-to-agents', () => {
             addListener(socket);
         });
 
-        // ---- setup wizard / persistence ----
+        // ---- setup panels / persistence ----
 
         socket.on('get-config', (callback) => {
             callback({
                 config: userconfig.getConfig(),
                 hasKeys: userconfig.hasKeys(),
+                providers: configuredProviders(userconfig.getKeys()),
                 profiles: userconfig.listProfiles(),
                 settingsSpec: settings_spec,
+                paths: { root: userconfig.paths.ROOT },
             });
         });
 
@@ -241,11 +267,12 @@ export function createMindServer(host_public = false, port = 8080) {
             catch (e) { callback({ success: false, error: e.message }); }
         });
 
-        socket.on('save-config', (config, callback) => {
+        socket.on('save-config', (partial, callback) => {
             try {
-                userconfig.saveConfig(config);
-                if (config.server) overrideSpecDefaults(config.server);
-                callback({ success: true });
+                const merged = userconfig.mergeConfig(partial);
+                if (partial.server) overrideSpecDefaults(partial.server);
+                if (partial.settings) overrideSpecDefaults(partial.settings);
+                callback({ success: true, config: merged });
             } catch (e) { callback({ success: false, error: e.message }); }
         });
 
@@ -254,6 +281,18 @@ export function createMindServer(host_public = false, port = 8080) {
             catch (e) { callback({ success: false, error: e.message }); }
         });
 
+        socket.on('delete-profile', (name, callback) => {
+            try {
+                userconfig.deleteProfile(name);
+                const cfg = userconfig.getConfig() || {};
+                if (cfg.agents) {
+                    cfg.agents = cfg.agents.filter(a => a.profile !== name);
+                    userconfig.saveConfig(cfg);
+                }
+                callback({ success: true });
+            } catch (e) { callback({ success: false, error: e.message }); }
+        });
+
         socket.on('list-profiles', (callback) => {
             callback({ profiles: userconfig.listProfiles() });
         });
@@ -278,9 +317,10 @@ function agentsStatusUpdate(socket) {
     for (let agentName in agent_connections) {
         const conn = agent_connections[agentName];
         agents.push({
-            name: agentName, 
+            name: agentName,
             in_game: conn.in_game,
             viewerPort: conn.viewer_port,
+            viewerError: conn.viewer_error,
             socket_connected: !!conn.socket
         });
     };

package/src/mindcraft/providers.js

@@ -0,0 +1,38 @@
+// Metadata for the API-providers setup panel: maps each provider (the `api`
+// prefix used in profiles, see src/models/*.js) to its env-var key name and a
+// short list of suggested models. Suggested models are just defaults for the
+// dropdown — any model string the provider accepts will work.
+//
+// Order matters: the first entry is the wizard's default selection, matching
+// upstream's default (OpenAI / andy.json uses gpt-4o-mini).
+
+export const PROVIDERS = [
+    { api: 'openai',      label: 'OpenAI',           key: 'OPENAI_API_KEY',     models: ['gpt-5.4-mini', 'gpt-5.4', 'gpt-5.4-nano', 'o3'] },
+    { api: 'anthropic',   label: 'Anthropic',        key: 'ANTHROPIC_API_KEY',  models: ['claude-sonnet-4-6', 'claude-opus-4-6', 'claude-haiku-4-5'] },
+    { api: 'google',      label: 'Google Gemini',    key: 'GEMINI_API_KEY',     models: ['gemini-3.1-pro', 'gemini-2.5-pro', 'gemini-2.5-flash'] },
+    { api: 'xai',         label: 'xAI (Grok)',       key: 'XAI_API_KEY',        models: ['grok-4', 'grok-code-fast-1'] },
+    { api: 'deepseek',    label: 'DeepSeek',         key: 'DEEPSEEK_API_KEY',   models: ['deepseek-chat', 'deepseek-reasoner'] },
+    { api: 'mistral',     label: 'Mistral',          key: 'MISTRAL_API_KEY',    models: ['mistral-large-latest', 'mistral-small-latest'] },
+    { api: 'groq',        label: 'Groq',             key: 'GROQCLOUD_API_KEY',  models: ['groq/llama-3.3-70b-versatile', 'groq/openai/gpt-oss-120b'] },
+    { api: 'qwen',        label: 'Qwen',             key: 'QWEN_API_KEY',       models: ['qwen-max', 'qwen-plus'] },
+    { api: 'replicate',   label: 'Replicate',        key: 'REPLICATE_API_KEY',  models: ['replicate/meta/meta-llama-3-70b-instruct'] },
+    { api: 'openrouter',  label: 'OpenRouter',       key: 'OPENROUTER_API_KEY', models: ['openrouter/anthropic/claude-sonnet-4-6', 'openrouter/openai/gpt-5.4'] },
+    { api: 'huggingface', label: 'Hugging Face',     key: 'HUGGINGFACE_API_KEY',models: ['huggingface/meta-llama/Llama-3.3-70B-Instruct'] },
+    { api: 'novita',      label: 'Novita',           key: 'NOVITA_API_KEY',     models: ['novita/meta-llama/llama-3.3-70b-instruct'] },
+    { api: 'hyperbolic',  label: 'Hyperbolic',       key: 'HYPERBOLIC_API_KEY', models: ['hyperbolic/meta-llama/Llama-3.3-70B-Instruct'] },
+    { api: 'cerebras',    label: 'Cerebras',         key: 'CEREBRAS_API_KEY',   models: ['cerebras/llama-3.3-70b'] },
+    { api: 'mercury',     label: 'Mercury',          key: 'MERCURY_API_KEY',    models: ['mercury/mercury-coder-small'] },
+    { api: 'glhf',        label: 'glhf.chat',        key: 'GHLF_API_KEY',       models: ['glhf/hf:meta-llama/Llama-3.3-70B-Instruct'] },
+    { api: 'azure',       label: 'Azure OpenAI',     key: 'OPENAI_API_KEY',     models: ['azure/gpt-5.4'] },
+    { api: 'ollama',      label: 'Ollama (local)',   key: null,                 models: ['ollama/sweaterdog/andy-4', 'ollama/llama3.3'] },
+    { api: 'lmstudio',    label: 'LM Studio (local)',key: null,                 models: ['lmstudio/default'] },
+    { api: 'vllm',        label: 'vLLM (local)',     key: null,                 models: ['vllm/default'] },
+];
+
+export function configuredProviders(keys) {
+    const have = new Set(Object.entries(keys).filter(([, v]) => v).map(([k]) => k));
+    return PROVIDERS.map(p => ({
+        ...p,
+        configured: p.key === null || have.has(p.key) || !!process.env[p.key],
+    }));
+}