oc-blackbytes 0.4.1 → 0.6.0

package/README.md

@@ -6,7 +6,7 @@ An OpenCode plugin for workflow automation. It provisions built-in MCP servers,
 
 The plugin wires five OpenCode hook surfaces:
 
-- `config` — merges built-in MCP servers and agents into the active OpenCode config
+- `config` — merges built-in MCP servers, agents, and commands into the active OpenCode config
 - `chat.headers` — injects `x-initiator: agent` for supported GitHub Copilot providers
 - `tool` — registers bundled local tools for structured editing and codebase search
 - `tool.execute.after` — post-processes `read`/`write` output when hashline editing is enabled
@@ -20,7 +20,8 @@ The plugin wires five OpenCode hook surfaces:
 - **Runtime model parameter adaptation** — the `chat.params` hook detects the actual model family at inference time and applies provider-correct parameters (Claude thinking, OpenAI reasoning effort) while stripping incompatible options
 - **Local tool registration** — exposes `hashline_edit`, `ast_grep_search`, `ast_grep_replace`, `grep`, and `glob`
 - **Hashline editing workflow** — transforms `read` output into `LINE#ID` anchors and turns successful `write` output into concise line-count summaries
-- **Config merging pipeline** — merges built-in MCPs and agents with user-defined config while preserving explicit user disables
+- **Config merging pipeline** — merges built-in MCPs, agents, and commands with user-defined config while preserving explicit user disables
+- **Built-in commands** — provides `/setup-models` for interactive model configuration setup
 - **JSONC config loading** — reads `oc-blackbytes.json` or `oc-blackbytes.jsonc` with comments and trailing commas
 - **Structured logging** — buffers plugin logs to `/tmp/oc-blackbytes.log`
 - **Binary auto-installation** — downloads cached search binaries when needed for bundled tools
@@ -97,11 +98,11 @@ Create `oc-blackbytes.jsonc` in the OpenCode config directory. For the full conf
 | `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` | Enables model fallback resolution: discovers connected providers at init and resolves fallback chains when a preferred model's provider is unavailable. |
+| `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. Set to `true` to enable. |
 | `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. 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. |
+| `fallback_models` | `string \| (string \| FallbackModelObject)[]` | — | Global fallback model chain. When 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
@@ -118,6 +119,14 @@ The plugin merges these agents into the OpenCode config and sets `default_agent`
 
 The merge behavior also preserves explicit user disables (`disable: true`), removes entries listed in `disabled_agents`, uses the OpenCode `permission` map format, and marks OpenCode's default `build` and `plan` agents as disabled unless the user configures them directly.
 
+## Built-in commands
+
+The plugin registers these built-in slash commands into the OpenCode config:
+
+| Command | Description |
+|---|---|
+| `/setup-models` | Interactive wizard that discovers available models, recommends optimal assignments per agent role, and writes the configuration to `oc-blackbytes.jsonc`. |
+
 ### Per-agent model configuration
 
 The `agents` field accepts a record of agent names to model configuration objects:
@@ -150,7 +159,7 @@ 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 — tried before the global `fallback_models` when the primary model's provider is unavailable. Requires `model_fallback: true`. |
+| `fallback_models` | `string \| (string \| object)[]` | Per-agent fallback chain — tried before the global `fallback_models` when the primary model's provider is unavailable. |
 
 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).
 
@@ -303,6 +312,7 @@ oc-blackbytes/
 │   │   ├── hooks/                  # Hook-related extension helpers
 │   │   ├── mcp/                    # Built-in MCP server configs
 │   │   ├── skills/                 # Skill extension entrypoints
+│   │   ├── commands/              # Built-in slash commands (setup-models)
 │   │   └── tools/                  # hashline_edit, ast-grep, grep, glob
 │   ├── shared/                     # Logger, constants, config path resolution, JSONC utils
 │   ├── compat/                     # Compatibility integrations

package/dist/index.js

@@ -2314,8 +2314,15 @@ var BUILTIN_FALLBACK_CHAINS = {
 };
 // src/services/model-resolver.ts
 async function discoverAvailableModels(client) {
+  let timeoutId;
   try {
-    const result = await client.provider.list();
+    const result = await Promise.race([
+      client.provider.list(),
+      new Promise((_, reject) => {
+        timeoutId = setTimeout(() => reject(new Error("Provider discovery timed out")), 20000);
+      })
+    ]);
+    clearTimeout(timeoutId);
     const data = result.data;
     if (!data) {
       log("[model-resolver] Provider list returned no data, skipping fallback resolution");
@@ -2335,6 +2342,7 @@ async function discoverAvailableModels(client) {
     log(`[model-resolver] Available: ${providerSummary || "(none)"}`);
     return models;
   } catch (e) {
+    clearTimeout(timeoutId);
     log(`[model-resolver] Failed to discover providers: ${e}`);
     return new Map;
   }
@@ -2433,6 +2441,7 @@ function resolveAgentModel(agentName, agentConfig, globalFallbacks, availableMod
       log(`  [model-resolver] ${agentName}: resolved \u2192 ${globalResolved2.model} (global fallback)`);
       return globalResolved2;
     }
+    log(`  [model-resolver] ${agentName}: no model configured, all fallback chains exhausted \u2192 using OpenCode default`);
     return { model: "", fromFallback: false };
   }
   const resolvedPrimaryModel = resolveModelRef(primaryModel, availableModels);
@@ -2456,7 +2465,7 @@ function resolveAgentModel(agentName, agentConfig, globalFallbacks, availableMod
     log(`  [model-resolver] ${agentName}: resolved \u2192 ${globalResolved.model} (global fallback)`);
     return globalResolved;
   }
-  log(`  [model-resolver] ${agentName}: no available fallback, using OpenCode default`);
+  log(`  [model-resolver] ${agentName}: primary model unavailable, all fallback chains exhausted \u2192 using OpenCode default`);
   return { model: "", fromFallback: false };
 }
 function resolveAllAgentModels(pluginConfig, availableModels) {
@@ -2480,6 +2489,8 @@ function resolveAllAgentModels(pluginConfig, availableModels) {
       ...resolution.fromFallback && resolution.temperature !== undefined && config?.temperature === undefined ? { temperature: resolution.temperature } : {}
     };
   }
+  const summary = Object.entries(resolved).map(([name, cfg]) => `${name}=${cfg.model || "(default)"}`).join(", ");
+  log(`[model-resolver] Resolution complete: ${summary}`);
   return resolved;
 }
 // src/handlers/config-handler/agent-config-handler.ts
@@ -2496,6 +2507,7 @@ function createBuiltinAgents(agentOverrides) {
   const agents = {};
   for (const [name, factory] of Object.entries(BUILTIN_AGENT_FACTORIES)) {
     const modelHint = agentOverrides?.[name]?.model ?? "";
+    log(`  [agents] Factory '${name}': modelHint=${modelHint || "(empty)"}`);
     agents[name] = factory(modelHint);
   }
   if (agentOverrides) {
@@ -2558,7 +2570,14 @@ function handleAgentConfig(ctx) {
   const { disabled_agents: pluginDisabledAgents = [] } = ctx.pluginConfig;
   const userAgents = ctx.config.agent;
   const userDisabledAgentNames = captureUserDisabledAgents(userAgents);
-  const effectiveOverrides = ctx.availableModels.size > 0 ? resolveAllAgentModels(ctx.pluginConfig, ctx.availableModels) ?? ctx.pluginConfig.agents : ctx.pluginConfig.agents;
+  let effectiveOverrides;
+  if (ctx.availableModels.size > 0) {
+    effectiveOverrides = resolveAllAgentModels(ctx.pluginConfig, ctx.availableModels) ?? ctx.pluginConfig.agents;
+    log(`  [agents] Model resolution: used fallback chains (${ctx.availableModels.size} provider(s) available)`);
+  } else {
+    effectiveOverrides = ctx.pluginConfig.agents;
+    log(`  [agents] Model resolution: SKIPPED (no providers discovered, using static config)`);
+  }
   const builtinAgents = createBuiltinAgents(effectiveOverrides);
   const merged = {
     ...builtinAgents
@@ -2586,12 +2605,106 @@ function handleAgentConfig(ctx) {
   }
   const enabledCount = Object.values(merged).filter((a) => !a.disable).length;
   log(`  Total agents enabled: ${enabledCount}`);
+  for (const [name, agent] of Object.entries(merged)) {
+    if (agent.disable)
+      continue;
+    const model2 = agent.model;
+    log(`  [agents] Final: ${name} \u2192 model=${model2 || "(opencode default)"}`);
+  }
   ctx.config.agent = merged;
   if (!ctx.config.default_agent && merged[DEFAULT_AGENT_NAME] && !merged[DEFAULT_AGENT_NAME].disable) {
     ctx.config.default_agent = DEFAULT_AGENT_NAME;
     log(`  Default agent set to: ${DEFAULT_AGENT_NAME}`);
   }
 }
+// src/extensions/commands/setup-models.ts
+var setupModels = {
+  description: "Set up optimal model assignments for each agent based on available providers",
+  agent: "bytes",
+  template: `You are running the /setup-models command. Your job is to help the user configure optimal model assignments for the oc-blackbytes plugin.
+
+## Step 1: Discover Available Models
+
+Run this command to see what models are available:
+\`\`\`
+opencode models
+\`\`\`
+
+## Step 2: Check for Existing Config
+
+Before writing anything, check if the user already has a plugin config file:
+\`\`\`
+ls ~/.config/opencode/oc-blackbytes.jsonc ~/.config/opencode/oc-blackbytes.json 2>/dev/null
+\`\`\`
+
+If a config file already exists, read it first and MERGE your changes with the existing settings \u2014 do not discard other fields the user may have configured (like \`disabled_mcps\`, \`disabled_tools\`, etc.).
+
+## Step 3: Analyze & Recommend
+
+Based on the available models, determine the best assignment for each agent role following these guidelines:
+
+### Agent Roles & Requirements
+
+| Agent | Role | Requirements | Ideal Tier |
+|-------|------|-------------|------------|
+| **bytes** | Primary coding agent | Strong reasoning, large context, code generation | Flagship (user's UI choice \u2014 do NOT set a model) |
+| **oracle** | Architecture advisor, deep debugging | Highest reasoning, complex analysis | Flagship \u2014 different provider than user's primary for diversity |
+| **explore** | Codebase search, read-only | Fast, cheap, good tool calling | Small/fast model |
+| **librarian** | Documentation research, read-only | Good tool calling, summarization | Small/fast model |
+| **general** | Multi-file implementation executor | Strong coding, moderate reasoning | Mid-tier coding model |
+
+### Model Preference (per tier)
+
+**Flagship tier** (oracle): Prefer cross-provider diversity. If user's primary is Claude, prefer GPT for oracle and vice versa.
+- claude-opus-4-6, gpt-5.4, gemini-3.1-pro
+
+**Mid-tier** (general): Good coding models, cost-effective.
+- claude-sonnet-4-6, gpt-5.4-mini, kimi-k2.5, gemini-3.1-pro
+
+**Small/fast tier** (explore, librarian): Cheapest available with decent tool calling.
+- gemini-3-flash, claude-haiku-4-5, gpt-5-nano, minimax-m2.7
+
+### Key Rules
+1. **bytes**: Do NOT include in the agents config \u2014 it respects the user's UI model selection
+2. **oracle**: Pick a flagship from a DIFFERENT provider than the user's likely primary model for diversity
+3. **explore & librarian**: Pick the cheapest/fastest available model \u2014 they are read-only search agents
+4. **general**: Pick a solid mid-tier coding model
+5. Only assign models from providers that are actually connected/available
+6. Include the provider prefix (e.g., "anthropic/claude-sonnet-4-6", "openai/gpt-5.4")
+
+## Step 4: Generate & Write Config
+
+Write the config as \`oc-blackbytes.jsonc\` (JSONC format \u2014 comments are supported) in the OpenCode config directory (the same directory where \`opencode.json\` or \`opencode.jsonc\` lives, typically \`~/.config/opencode/\`).
+
+Use this structure:
+\`\`\`jsonc
+{
+  // Enable model fallback resolution for automatic provider failover
+  "model_fallback": true,
+
+  "agents": {
+    // bytes is NOT included \u2014 it uses whatever model you select in the UI
+    "oracle": { "model": "<provider>/<model>" },
+    "explore": { "model": "<provider>/<model>" },
+    "librarian": { "model": "<provider>/<model>" },
+    "general": { "model": "<provider>/<model>" }
+  }
+}
+\`\`\`
+
+If an existing config file was found in Step 2, merge the \`agents\` and \`model_fallback\` fields into it, preserving all other existing fields.
+
+After writing, show a summary table of what was configured and why each model was chosen.
+
+**Important**: If a provider has very few models or only one flagship, prefer not to duplicate the same model across agents. Spread across providers when possible for resilience.`
+};
+
+// src/extensions/commands/index.ts
+function createBuiltinCommands() {
+  return {
+    "setup-models": setupModels
+  };
+}
 // src/extensions/mcp/context7.ts
 var context7 = {
   type: "remote",
@@ -2648,6 +2761,25 @@ function createBuiltinMcps(config) {
   mcps.grep_app = grep_app;
   return mcps;
 }
+// src/handlers/config-handler/command-config-handler.ts
+function handleCommandConfig(ctx) {
+  const { config } = ctx;
+  if (!config.command) {
+    config.command = {};
+  }
+  const builtinCommands = createBuiltinCommands();
+  let registered = 0;
+  for (const [name, command] of Object.entries(builtinCommands)) {
+    if (config.command[name]) {
+      log(`  [commands] Skipping '${name}': user-defined override exists`);
+      continue;
+    }
+    config.command[name] = command;
+    registered++;
+  }
+  log(`  [commands] Registered ${registered} built-in command(s)`);
+}
+
 // src/handlers/config-handler/mcp-config-handler.ts
 function isDisabledMcpEntry(value) {
   return typeof value === "object" && value !== null && "enabled" in value && value.enabled === false;
@@ -2711,8 +2843,10 @@ function handleConfig(pluginConfig, availableModels) {
   return {
     config: async (config) => {
       const configCtx = { config, pluginConfig, availableModels };
+      log(`[config] Available models: ${availableModels.size} provider(s) discovered`);
       handleMcpConfig(configCtx);
       handleAgentConfig(configCtx);
+      handleCommandConfig(configCtx);
     }
   };
 }
@@ -17515,10 +17649,10 @@ async function resolveFormatters(client, directory) {
       }
     }
     if (config2.experimental?.hook?.file_edited) {
-      for (const [ext, commands] of Object.entries(config2.experimental.hook.file_edited)) {
+      for (const [ext, commands2] of Object.entries(config2.experimental.hook.file_edited)) {
         const normalizedExt = ext.startsWith(".") ? ext : `.${ext}`;
         const existing = result.get(normalizedExt) ?? [];
-        for (const cmd of commands) {
+        for (const cmd of commands2) {
           existing.push({
             command: cmd.command,
             environment: cmd.environment ?? {}
@@ -31447,7 +31581,7 @@ function loadPluginConfig(_input) {
 // src/index.ts
 var BlackbytesPlugin = async (ctx) => {
   const pluginConfig = loadPluginConfig(ctx);
-  const availableModels = pluginConfig.model_fallback ? await discoverAvailableModels(ctx.client) : new Map;
+  const availableModels = pluginConfig.model_fallback === true ? await discoverAvailableModels(ctx.client) : new Map;
   return createOpenCodePlugin({ input: ctx, pluginConfig, availableModels });
 };
 var src_default = BlackbytesPlugin;

package/package.json

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