oc-blackbytes 0.3.0 → 0.4.1

package/README.md

@@ -62,7 +62,7 @@ opencode debug config
 
 ## Configuration
 
-Create `oc-blackbytes.jsonc` in the OpenCode config directory.
+Create `oc-blackbytes.jsonc` in the OpenCode config directory. For the full configuration guide with recommended models per agent and example setups, see [docs/configuration.md](docs/configuration.md).
 
 ```jsonc
 {
@@ -97,11 +97,11 @@ Create `oc-blackbytes.jsonc` in the OpenCode config directory.
 | `disabled_tools` | `string[]` | `[]` | Prevents bundled tools from being registered. |
 | `mcp_env_alllowlist` | `string[]` | `[]` | Recognized by the schema for MCP environment filtering workflows. |
 | `hashline_edit` | `boolean` | `true` | Enables the `hashline_edit` tool and `tool.execute.after` hashline post-processing for `read`/`write`. |
-| `model_fallback` | `boolean` | `false` | Recognized by the schema for model compatibility workflows. |
+| `model_fallback` | `boolean` | `false` | Enables model fallback resolution: discovers connected providers at init and resolves fallback chains when a preferred model's provider is unavailable. |
 | `auto_update` | `boolean` | `false` | Recognized by the schema for maintenance workflows. |
 | `websearch.provider` | `"exa" \| "tavily"` | `"exa"` | Selects the built-in `websearch` MCP backend. |
 | `agents` | `Record<string, AgentModelConfig>` | `{}` | Per-agent model configuration overrides. See [Per-agent model configuration](#per-agent-model-configuration). |
-| `fallback_models` | `string \| (string \| FallbackModelObject)[]` | — | Global fallback model chain (reserved for future use). |
+| `fallback_models` | `string \| (string \| FallbackModelObject)[]` | — | Global fallback model chain. When `model_fallback: true` and an agent's primary model is unavailable, the plugin walks this chain and uses the first model whose provider is connected. |
 | `_migrations` | `string[]` | `[]` | Internal migration bookkeeping. |
 
 ## Built-in agents
@@ -150,9 +150,9 @@ Each agent model config supports:
 | `model` | `string` | Model identifier (e.g., `"openai/gpt-5.4"`). Drives prompt variant selection and, for subagents, sets the model hint. |
 | `reasoningEffort` | `string` | Override reasoning effort level for OpenAI reasoning models (`"low"`, `"medium"`, `"high"`). |
 | `temperature` | `number` | Override temperature for the agent. |
-| `fallback_models` | `string \| (string \| object)[]` | Per-agent fallback chain (reserved for future use). |
+| `fallback_models` | `string \| (string \| object)[]` | Per-agent fallback chain — tried before the global `fallback_models` when the primary model's provider is unavailable. Requires `model_fallback: true`. |
 
-When a `model` is specified for a subagent, the factory selects the appropriate prompt variant for that model family (Claude, GPT, or Gemini). The primary agent (`bytes`) uses the model hint for prompt selection only — the actual model is determined by the OpenCode UI selection.
+When a `model` is specified for a subagent, the factory selects the appropriate prompt variant for that model family (Claude, GPT, or Gemini). The primary agent (`bytes`) uses the model hint for prompt selection only — the actual model is determined by the OpenCode UI selection. For recommended models per agent, see [docs/configuration.md](docs/configuration.md).
 
 ## Runtime model parameter adaptation
 
@@ -307,9 +307,10 @@ oc-blackbytes/
 │   ├── shared/                     # Logger, constants, config path resolution, JSONC utils
 │   ├── compat/                     # Compatibility integrations
 │   ├── integrations/               # Additional runtime integrations
-│   ├── services/                   # Reserved service modules
+│   ├── services/                   # Model fallback resolution (provider discovery, fallback chains)
 │   └── stores/                     # Reserved state stores
 ├── docs/
+│   ├── configuration.md
 │   └── debugging.md
 ├── test/
 │   └── config.test.ts

package/dist/index.js

@@ -2287,6 +2287,201 @@ function createOracleAgent(model2) {
 }
 createOracleAgent.mode = MODE5;
 
+// src/services/model-requirements.ts
+var BUILTIN_FALLBACK_CHAINS = {
+  oracle: [
+    { model: "gpt-5.4", providers: ["openai", "github-copilot"], reasoningEffort: "high" },
+    { model: "gemini-3.1-pro", providers: ["google"] },
+    { model: "claude-opus-4-6", providers: ["anthropic", "github-copilot"] }
+  ],
+  explore: [
+    { model: "gemini-3-flash", providers: ["google"], temperature: 0.1 },
+    { model: "claude-haiku-4-5", providers: ["anthropic", "github-copilot"], temperature: 0.1 },
+    { model: "gpt-5-nano", providers: ["openai", "github-copilot"], temperature: 0.1 },
+    { model: "minimax-m2.7", providers: ["minimax"], temperature: 0.1 }
+  ],
+  librarian: [
+    { model: "claude-haiku-4-5", providers: ["anthropic", "github-copilot"], temperature: 0.2 },
+    { model: "gemini-3-flash", providers: ["google"], temperature: 0.2 },
+    { model: "gpt-5-nano", providers: ["openai", "github-copilot"], temperature: 0.2 }
+  ],
+  general: [
+    { model: "claude-sonnet-4-6", providers: ["anthropic", "github-copilot"] },
+    { model: "kimi-k2.5", providers: ["kimi"] },
+    { model: "gpt-5.4-mini", providers: ["openai", "github-copilot"] },
+    { model: "gemini-3.1-pro", providers: ["google"] }
+  ]
+};
+// src/services/model-resolver.ts
+async function discoverAvailableModels(client) {
+  try {
+    const result = await client.provider.list();
+    const data = result.data;
+    if (!data) {
+      log("[model-resolver] Provider list returned no data, skipping fallback resolution");
+      return new Map;
+    }
+    const connected = new Set(data.connected);
+    const models = new Map;
+    for (const provider of data.all ?? []) {
+      if (!connected.has(provider.id))
+        continue;
+      const modelIds = new Set(Object.keys(provider.models ?? {}));
+      if (modelIds.size > 0) {
+        models.set(provider.id, modelIds);
+      }
+    }
+    const providerSummary = [...models.entries()].map(([id, m]) => `${id}(${m.size})`).join(", ");
+    log(`[model-resolver] Available: ${providerSummary || "(none)"}`);
+    return models;
+  } catch (e) {
+    log(`[model-resolver] Failed to discover providers: ${e}`);
+    return new Map;
+  }
+}
+function resolveModelRef(modelRef, availableModels) {
+  if (availableModels.size === 0)
+    return modelRef;
+  const slashIdx = modelRef.indexOf("/");
+  if (slashIdx === -1)
+    return modelRef;
+  const providerId = modelRef.substring(0, slashIdx);
+  const modelId = modelRef.substring(slashIdx + 1);
+  const providerModels = availableModels.get(providerId);
+  if (!providerModels)
+    return;
+  const matchedModel = prefixMatchModel(modelId, providerModels);
+  return matchedModel ? `${providerId}/${matchedModel}` : undefined;
+}
+function prefixMatchModel(modelPrefix, providerModels) {
+  if (providerModels.has(modelPrefix))
+    return modelPrefix;
+  let bestMatch;
+  for (const available of providerModels) {
+    if (available.startsWith(modelPrefix)) {
+      const rest = available.substring(modelPrefix.length);
+      if (rest === "" || /^-\d/.test(rest)) {
+        if (!bestMatch || available.length < bestMatch.length) {
+          bestMatch = available;
+        }
+      }
+    }
+  }
+  return bestMatch;
+}
+function resolveChainEntry(entry, availableModels) {
+  for (const provider of entry.providers) {
+    const providerModels = availableModels.get(provider);
+    if (!providerModels)
+      continue;
+    const matched = prefixMatchModel(entry.model, providerModels);
+    if (matched) {
+      return {
+        model: `${provider}/${matched}`,
+        fromFallback: true,
+        reasoningEffort: entry.reasoningEffort,
+        temperature: entry.temperature
+      };
+    }
+  }
+  return;
+}
+function walkFallbackChain(fallbacks, availableModels) {
+  if (!fallbacks)
+    return;
+  const chain = typeof fallbacks === "string" ? [fallbacks] : fallbacks;
+  for (const entry of chain) {
+    const modelRef = typeof entry === "string" ? entry : entry.model;
+    const resolvedModel = resolveModelRef(modelRef, availableModels);
+    if (resolvedModel) {
+      return typeof entry === "string" ? { model: resolvedModel, fromFallback: true } : {
+        model: resolvedModel,
+        fromFallback: true,
+        reasoningEffort: entry.reasoningEffort,
+        temperature: entry.temperature
+      };
+    }
+  }
+  return;
+}
+function walkBuiltinChain(agentName, availableModels) {
+  const chain = BUILTIN_FALLBACK_CHAINS[agentName];
+  if (!chain)
+    return;
+  for (const entry of chain) {
+    const resolved = resolveChainEntry(entry, availableModels);
+    if (resolved)
+      return resolved;
+  }
+  return;
+}
+function resolveAgentModel(agentName, agentConfig, globalFallbacks, availableModels) {
+  const primaryModel = agentConfig?.model;
+  if (!primaryModel) {
+    const perAgentResolved2 = walkFallbackChain(agentConfig?.fallback_models, availableModels);
+    if (perAgentResolved2) {
+      log(`  [model-resolver] ${agentName}: resolved \u2192 ${perAgentResolved2.model} (agent fallback)`);
+      return perAgentResolved2;
+    }
+    const builtinResolved2 = walkBuiltinChain(agentName, availableModels);
+    if (builtinResolved2) {
+      log(`  [model-resolver] ${agentName}: resolved \u2192 ${builtinResolved2.model} (builtin chain)`);
+      return builtinResolved2;
+    }
+    const globalResolved2 = walkFallbackChain(globalFallbacks, availableModels);
+    if (globalResolved2) {
+      log(`  [model-resolver] ${agentName}: resolved \u2192 ${globalResolved2.model} (global fallback)`);
+      return globalResolved2;
+    }
+    return { model: "", fromFallback: false };
+  }
+  const resolvedPrimaryModel = resolveModelRef(primaryModel, availableModels);
+  if (resolvedPrimaryModel) {
+    log(`  [model-resolver] ${agentName}: using primary model ${resolvedPrimaryModel}`);
+    return { model: resolvedPrimaryModel, fromFallback: false };
+  }
+  log(`  [model-resolver] ${agentName}: primary model ${primaryModel} not available, trying fallbacks...`);
+  const perAgentResolved = walkFallbackChain(agentConfig?.fallback_models, availableModels);
+  if (perAgentResolved) {
+    log(`  [model-resolver] ${agentName}: resolved \u2192 ${perAgentResolved.model} (agent fallback)`);
+    return perAgentResolved;
+  }
+  const builtinResolved = walkBuiltinChain(agentName, availableModels);
+  if (builtinResolved) {
+    log(`  [model-resolver] ${agentName}: resolved \u2192 ${builtinResolved.model} (builtin chain)`);
+    return builtinResolved;
+  }
+  const globalResolved = walkFallbackChain(globalFallbacks, availableModels);
+  if (globalResolved) {
+    log(`  [model-resolver] ${agentName}: resolved \u2192 ${globalResolved.model} (global fallback)`);
+    return globalResolved;
+  }
+  log(`  [model-resolver] ${agentName}: no available fallback, using OpenCode default`);
+  return { model: "", fromFallback: false };
+}
+function resolveAllAgentModels(pluginConfig, availableModels) {
+  const agentOverrides = pluginConfig.agents;
+  const globalFallbacks = pluginConfig.fallback_models;
+  const agentNames = new Set([
+    ...Object.keys(BUILTIN_FALLBACK_CHAINS),
+    ...agentOverrides ? Object.keys(agentOverrides) : []
+  ]);
+  if (agentNames.size === 0)
+    return;
+  const resolved = {};
+  log("[model-resolver] Resolving agent models with fallback chains...");
+  for (const name of agentNames) {
+    const config = agentOverrides?.[name];
+    const resolution = resolveAgentModel(name, config, globalFallbacks, availableModels);
+    resolved[name] = {
+      ...config,
+      model: resolution.model || undefined,
+      ...resolution.fromFallback && resolution.reasoningEffort !== undefined && config?.reasoningEffort === undefined ? { reasoningEffort: resolution.reasoningEffort } : {},
+      ...resolution.fromFallback && resolution.temperature !== undefined && config?.temperature === undefined ? { temperature: resolution.temperature } : {}
+    };
+  }
+  return resolved;
+}
 // src/handlers/config-handler/agent-config-handler.ts
 var DEFAULT_AGENT_NAME = "bytes";
 var SUPERSEDED_AGENTS = ["build", "plan"];
@@ -2363,7 +2558,8 @@ function handleAgentConfig(ctx) {
   const { disabled_agents: pluginDisabledAgents = [] } = ctx.pluginConfig;
   const userAgents = ctx.config.agent;
   const userDisabledAgentNames = captureUserDisabledAgents(userAgents);
-  const builtinAgents = createBuiltinAgents(ctx.pluginConfig.agents);
+  const effectiveOverrides = ctx.availableModels.size > 0 ? resolveAllAgentModels(ctx.pluginConfig, ctx.availableModels) ?? ctx.pluginConfig.agents : ctx.pluginConfig.agents;
+  const builtinAgents = createBuiltinAgents(effectiveOverrides);
   const merged = {
     ...builtinAgents
   };
@@ -2511,10 +2707,10 @@ function handleMcpConfig(ctx) {
 }
 
 // src/handlers/config-handler/index.ts
-function handleConfig(pluginConfig) {
+function handleConfig(pluginConfig, availableModels) {
   return {
     config: async (config) => {
-      const configCtx = { config, pluginConfig };
+      const configCtx = { config, pluginConfig, availableModels };
       handleMcpConfig(configCtx);
       handleAgentConfig(configCtx);
     }
@@ -17634,10 +17830,11 @@ function handleTools(pluginConfig, ctx) {
 // src/bootstrap.ts
 async function createOpenCodePlugin({
   input,
-  pluginConfig
+  pluginConfig,
+  availableModels
 }) {
   return {
-    ...handleConfig(pluginConfig),
+    ...handleConfig(pluginConfig, availableModels),
     ...handleChatHeaders(pluginConfig),
     ...handleChatParams(pluginConfig),
     tool: handleTools(pluginConfig, input),
@@ -31250,7 +31447,8 @@ function loadPluginConfig(_input) {
 // src/index.ts
 var BlackbytesPlugin = async (ctx) => {
   const pluginConfig = loadPluginConfig(ctx);
-  return createOpenCodePlugin({ input: ctx, pluginConfig });
+  const availableModels = pluginConfig.model_fallback ? await discoverAvailableModels(ctx.client) : new Map;
+  return createOpenCodePlugin({ input: ctx, pluginConfig, availableModels });
 };
 var src_default = BlackbytesPlugin;
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oc-blackbytes",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "An OpenCode plugin tailored to streamline my everyday workflow.",
   "type": "module",
   "main": "./dist/index.js",