opencode-agent-variants 0.1.0 → 0.2.0-dev.2

package/README.md

@@ -75,15 +75,16 @@ The wizard supports:
 - editing parent overrides
 - editing variant overrides
 - enabling or disabling parents and variants
-- toggling debug mode
-- running diagnostics
-- viewing and clearing the debug log
 - deleting variants
+- running diagnostics
+- opening `Debug & advanced` to toggle debug mode, view/clear logs, and change wizard-only filters
 - previewing the generated config
 - saving changes with timestamped backups
 
 Agent/variant list changes take effect after restarting OpenCode because agents and plugins are assembled at startup. Debug mode is hot-read and takes effect immediately after the wizard saves it.
 
+The wizard defaults to showing only subagent-capable parent agents when adding or editing parent entries. Agent Variants are meant for agents callable through OpenCode's `task` tool. You can temporarily show all agents from `Debug & advanced` if you need to inspect or repair existing config.
+
 ## Config File
 
 The plugin writes a sidecar config file at:
@@ -187,11 +188,11 @@ Agents defined in `opencode.json`, `.opencode/agent/*.md`, or global agent markd
 - If a variant resolves to a definitely missing model, it is skipped for that run and a warning toast is shown.
 - Conflicting aliases are skipped instead of overwriting existing agents.
 
-Use the wizard's `Run diagnostics` action to inspect model validation, alias conflicts, disabled parents, and plugin installation state.
+Use the wizard's `Run diagnostics` action to inspect model validation, alias conflicts, disabled parents, task-callability, and plugin installation state.
 
 ## Debug Mode
 
-Debug mode is off by default. Enable it from the wizard with `Debug mode: off`.
+Debug mode is off by default. Enable it from the wizard through `Debug & advanced`.
 
 When enabled, the server plugin emits diagnostic log lines and TUI toast notifications for built-in virtual variants:
 
@@ -202,7 +203,7 @@ When enabled, the server plugin emits diagnostic log lines and TUI toast notific
 
 Logs are written to `~/.config/opencode/agent-variants.debug.log`. The plugin does not write debug lines to stdout, because that can corrupt the terminal UI.
 
-Debug mode is stored in `agent-variants.jsonc` and takes effect immediately for future variant calls. The wizard can also view and clear the debug log.
+Debug mode is stored in `agent-variants.jsonc` and takes effect immediately for future variant calls. The wizard can also view and clear the debug log from `Debug & advanced`.
 
 ## Development
 
@@ -230,28 +231,6 @@ Check package contents before publishing:
 npm pack --dry-run
 ```
 
-## Release
-
-CI runs on pushes and pull requests. It installs with `npm ci`, typechecks, builds, and verifies package contents with `npm pack --dry-run`.
-
-Automated releases run when a version tag is pushed:
-
-```sh
-git tag v0.1.0
-git push origin v0.1.0
-```
-
-The release workflow:
-
-- installs dependencies
-- typechecks
-- builds `dist`
-- verifies package contents
-- publishes to npm with provenance
-- creates a GitHub release with generated notes
-
-Before the first automated publish, add an npm automation token as the repository secret `NPM_TOKEN`.
-
 ## License
 
 MIT

package/dist/config.d.ts

@@ -128,6 +128,7 @@ export type TemplateContext = {
     model_label?: string;
     routed_agent?: string;
 };
+export type AgentMode = "primary" | "subagent" | "all";
 export declare function defaultConfigDir(): string;
 export declare function defaultSidecarPath(configDir?: string): string;
 export declare function debugLogPath(configDir?: string): string;
@@ -195,10 +196,12 @@ export declare function templateContext(parent: string, key: string | undefined,
 export declare function generatedVariantDescription(parent: string, key: string, variant: VariantConfig, config: SidecarConfig): string;
 export declare function modelCatalogFromProviders(providers: unknown): ModelCatalog;
 export declare function validateModel(modelInput: string | undefined, config: SidecarConfig, catalog: ModelCatalog): string | undefined;
+export declare function isSubagentCapableMode(mode: AgentMode | undefined): mode is "subagent" | "all" | undefined;
 export declare function diagnoseConfig(config: SidecarConfig, input: {
     agents: string[];
     providers: unknown;
     pluginEntries?: unknown[];
+    agentModes?: Record<string, AgentMode>;
 }): Diagnostic[];
 export declare function fingerprint(input: {
     parentSessionID: string;

package/dist/config.js

@@ -176,6 +176,9 @@ export function validateModel(modelInput, config, catalog) {
     if (catalog.providersWithModelList.has(split.providerID) && !catalog.refs.has(model))
         return `Model "${model}" was not found in provider "${split.providerID}".`;
 }
+export function isSubagentCapableMode(mode) {
+    return mode !== "primary";
+}
 export function diagnoseConfig(config, input) {
     const diagnostics = [];
     const catalog = modelCatalogFromProviders(input.providers);
@@ -188,10 +191,14 @@ export function diagnoseConfig(config, input) {
     for (const [agent, entry] of Object.entries(config.agents)) {
         if (!knownAgents.has(agent))
             diagnostics.push({ level: "warning", agent, message: `Parent agent "${agent}" is not a known built-in or configured agent.` });
+        if (!isSubagentCapableMode(input.agentModes?.[agent]))
+            diagnostics.push({ level: "warning", agent, message: `Parent agent "${agent}" is primary-only and will not be callable by the task tool.` });
         if (entry.disable)
             diagnostics.push({ level: "info", agent, message: `Parent "${agent}" is disabled in sidecar config.` });
         for (const [key, variant] of Object.entries(entry.variants)) {
             const alias = variantName(agent, key, variant);
+            if (!isSubagentCapableMode(input.agentModes?.[agent]))
+                diagnostics.push({ level: "warning", agent, variant: key, alias, message: `Variant "${alias}" inherits a primary-only parent and will not be callable by the task tool.` });
             const issue = validateModel(variant.model, config, catalog);
             if (issue)
                 diagnostics.push({ level: "warning", agent, variant: key, alias, message: `Variant "${alias}" disabled at runtime: ${issue}` });

package/dist/tui.js

@@ -1,7 +1,14 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { BUILTIN_AGENT_DESCRIPTIONS, debugLogPath, defaultConfigDir, defaultSidecarPath, diagnoseConfig, loadSidecar, saveSidecar, variantName, } from "./config.js";
+import { BUILTIN_AGENT_DESCRIPTIONS, debugLogPath, defaultConfigDir, defaultSidecarPath, diagnoseConfig, isSubagentCapableMode, loadSidecar, saveSidecar, variantName, } from "./config.js";
 // Constants.
 const BUILTIN_AGENT_KEYS = Object.keys(BUILTIN_AGENT_DESCRIPTIONS);
+const BUILTIN_AGENT_MODES = {
+    build: "primary",
+    plan: "primary",
+    general: "subagent",
+    explore: "subagent",
+    scout: "subagent",
+};
 const THEME_COLORS = ["primary", "secondary", "accent", "success", "warning", "error", "info"];
 const EDITABLE_FIELDS = [
     { key: "model", label: "Model", type: "string" },
@@ -23,6 +30,18 @@ function agentsFromState(api) {
     const merged = new Set([...BUILTIN_AGENT_KEYS, ...configured]);
     return [...merged].sort();
 }
+function agentMode(api, agent) {
+    return api.state.config.agent?.[agent]?.mode ?? BUILTIN_AGENT_MODES[agent] ?? "all";
+}
+function agentModes(api) {
+    return Object.fromEntries(agentsFromState(api).map((agent) => [agent, agentMode(api, agent)]));
+}
+function selectableParentAgents(api, config, settings) {
+    const aliases = generatedAliasSet(config);
+    return agentsFromState(api)
+        .filter((agent) => !aliases.has(agent))
+        .filter((agent) => !settings.subagentCapableOnly || isSubagentCapableMode(agentMode(api, agent)));
+}
 function modelOptions(api, config) {
     const opts = [];
     for (const [key, raw] of Object.entries(config.models)) {
@@ -154,21 +173,33 @@ function showAlert(ui, props) {
     });
 }
 // Main wizard flows.
-async function addVariant(api, config) {
-    const aliases = generatedAliasSet(config);
-    const agents = agentsFromState(api).filter((agent) => !aliases.has(agent));
+async function addVariant(api, config, settings) {
+    const agents = selectableParentAgents(api, config, settings);
     if (agents.length === 0) {
-        await showAlert(api.ui, { title: "No agents", message: "No agents available to add a variant to." });
+        await showAlert(api.ui, {
+            title: "No agents",
+            message: settings.subagentCapableOnly
+                ? "No subagent-capable agents are available. Open Debug & advanced and disable the parent filter only if you need to inspect or repair existing config."
+                : "No agents available to add a variant to.",
+        });
         return config;
     }
     const agentOpts = agents.map((a) => ({
         title: a,
         value: a,
-        description: BUILTIN_AGENT_DESCRIPTIONS[a] ?? api.state.config.agent?.[a]?.description,
+        description: `${agentMode(api, a)} - ${BUILTIN_AGENT_DESCRIPTIONS[a] ?? api.state.config.agent?.[a]?.description ?? "Configured agent"}`,
     }));
     const agent = await showSelect(api.ui, { title: "Add variant - pick parent agent", options: agentOpts });
     if (!agent)
         return config;
+    if (settings.subagentCapableOnly && !isSubagentCapableMode(agentMode(api, agent))) {
+        await showAlert(api.ui, {
+            title: "Primary-only agent",
+            message: `"${agent}" is primary-only and cannot be used by the task tool. Agent Variants are intended for subagents.`,
+        });
+        api.ui.toast({ variant: "warning", title: "Variant not added", message: `${agent} is primary-only.` });
+        return config;
+    }
     const existingKeys = Object.keys(config.agents[agent]?.variants ?? {});
     const defaultKey = existingKeys.length === 0 ? "light" : undefined;
     const key = await showPrompt(api.ui, {
@@ -584,6 +615,7 @@ async function runDiagnostics(api, config) {
         agents: agentsFromState(api).filter((agent) => !generatedAliases.has(agent)),
         providers: api.state.provider,
         pluginEntries: api.state.config.plugin,
+        agentModes: agentModes(api),
     });
     const errors = diagnostics.filter((item) => item.level === "error").length;
     const warnings = diagnostics.filter((item) => item.level === "warning").length;
@@ -729,7 +761,7 @@ function formatInputValue(value) {
     return JSON.stringify(value);
 }
 // Main menu loop.
-async function mainMenu(api, config) {
+async function mainMenu(api, config, settings) {
     const agentCount = Object.keys(config.agents).length;
     const vCount = variantCount(config);
     const opts = [
@@ -737,15 +769,9 @@ async function mainMenu(api, config) {
         { title: "Edit parent fields...", value: "edit-parent", description: "Override fields on an agent parent" },
         { title: "Edit variant...", value: "edit-variant", description: "Change fields on an existing variant" },
         { title: "Toggle disable...", value: "toggle", description: "Enable or disable agents/variants" },
-        { title: "Run diagnostics", value: "diagnostics", description: "Check models, conflicts, plugin install, and disabled variants" },
-        {
-            title: `Debug mode: ${config.debug ? "on" : "off"}`,
-            value: "debug",
-            description: "Toggle routing/model diagnostic toasts immediately",
-        },
-        { title: "View debug log", value: "view-log", description: "Show recent agent-variants.debug.log entries" },
-        { title: "Clear debug log", value: "clear-log", description: "Empty agent-variants.debug.log" },
         { title: "Delete variant...", value: "delete", description: "Remove a variant" },
+        { title: "Run diagnostics", value: "diagnostics", description: "Check models, conflicts, plugin install, and task-callability" },
+        { title: "Debug & advanced...", value: "advanced", description: "Debug mode, logs, and wizard-only parent filter" },
         { title: "Preview configuration", value: "preview", description: `View current config (${agentCount} agents, ${vCount} variants)` },
         { title: "Save & exit", value: "save", description: "Write to disk with backup" },
     ];
@@ -756,29 +782,23 @@ async function mainMenu(api, config) {
     });
     switch (action) {
         case "add":
-            return mainMenu(api, await addVariant(api, config));
+            return mainMenu(api, await addVariant(api, config, settings), settings);
         case "edit-parent":
-            return editParentFlow(api, config);
+            return editParentFlow(api, config, settings);
         case "edit-variant":
-            return mainMenu(api, await editVariant(api, config));
+            return mainMenu(api, await editVariant(api, config), settings);
         case "toggle":
-            return mainMenu(api, await toggleDisable(api, config));
+            return mainMenu(api, await toggleDisable(api, config), settings);
         case "diagnostics":
             await runDiagnostics(api, config);
-            return mainMenu(api, config);
-        case "debug":
-            return mainMenu(api, await toggleDebug(api, config));
-        case "view-log":
-            await viewDebugLog(api);
-            return mainMenu(api, config);
-        case "clear-log":
-            await clearDebugLog(api);
-            return mainMenu(api, config);
+            return mainMenu(api, config, settings);
+        case "advanced":
+            return mainMenu(api, await debugAdvancedMenu(api, config, settings), settings);
         case "delete":
-            return mainMenu(api, await deleteVariant(api, config));
+            return mainMenu(api, await deleteVariant(api, config), settings);
         case "preview":
             await previewConfig(api, config);
-            return mainMenu(api, config);
+            return mainMenu(api, config, settings);
         case "save":
             await saveConfig(api, config);
             return config;
@@ -786,16 +806,15 @@ async function mainMenu(api, config) {
             return config;
     }
 }
-async function editParentFlow(api, config) {
-    const aliases = generatedAliasSet(config);
-    const agents = agentsFromState(api).filter((agent) => !aliases.has(agent));
+async function editParentFlow(api, config, settings) {
+    const agents = selectableParentAgents(api, config, settings);
     const opts = agents.map((a) => {
         const entry = config.agents[a];
         const overrides = entry ? Object.keys(entry.parent).length : 0;
         return {
             title: a,
             value: a,
-            description: overrides > 0 ? `${overrides} parent override(s)` : "No overrides",
+            description: `${agentMode(api, a)} - ${overrides > 0 ? `${overrides} parent override(s)` : "No overrides"}`,
         };
     });
     opts.push({
@@ -805,9 +824,47 @@ async function editParentFlow(api, config) {
     });
     const agent = await showSelect(api.ui, { title: "Edit parent fields - pick agent", options: opts });
     if (!agent || agent === "__back__")
-        return mainMenu(api, config);
+        return mainMenu(api, config, settings);
     const updated = await editParentFields(api, config, agent);
-    return mainMenu(api, updated);
+    return mainMenu(api, updated, settings);
+}
+async function debugAdvancedMenu(api, config, settings) {
+    const opts = [
+        {
+            title: `Debug mode: ${config.debug ? "on" : "off"}`,
+            value: "debug",
+            description: "Toggle routing/model diagnostic toasts immediately",
+        },
+        { title: "View debug log", value: "view-log", description: "Show recent agent-variants.debug.log entries" },
+        { title: "Clear debug log", value: "clear-log", description: "Empty agent-variants.debug.log" },
+        {
+            title: `Parent picker filter: ${settings.subagentCapableOnly ? "subagent-capable only" : "all agents"}`,
+            value: "filter",
+            description: "Wizard-only filter for adding/editing parent entries",
+        },
+        { title: "< Back", value: "__back__", description: "Return to main menu" },
+    ];
+    const action = await showSelect(api.ui, { title: "Debug & advanced", options: opts });
+    switch (action) {
+        case "debug":
+            return debugAdvancedMenu(api, await toggleDebug(api, config), settings);
+        case "view-log":
+            await viewDebugLog(api);
+            return debugAdvancedMenu(api, config, settings);
+        case "clear-log":
+            await clearDebugLog(api);
+            return debugAdvancedMenu(api, config, settings);
+        case "filter":
+            settings.subagentCapableOnly = !settings.subagentCapableOnly;
+            api.ui.toast({
+                variant: "info",
+                title: "Parent filter updated",
+                message: settings.subagentCapableOnly ? "Showing subagent-capable parents only." : "Showing all parent agents.",
+            });
+            return debugAdvancedMenu(api, config, settings);
+        default:
+            return config;
+    }
 }
 // Plugin entrypoint.
 function registerConfigureCommand(api, run) {
@@ -840,7 +897,7 @@ function registerConfigureCommand(api, run) {
 const tui = async (api) => {
     const unregister = registerConfigureCommand(api, async () => {
         const config = loadSidecar(defaultSidecarPath());
-        await mainMenu(api, config);
+        await mainMenu(api, config, { subagentCapableOnly: true });
     });
     api.lifecycle.onDispose(() => {
         unregister?.();

package/docs/CONFIG.md

@@ -67,6 +67,8 @@ Variants also support:
 
 The sidecar intentionally does not configure `permission`, `tools`, or `mode`. Those come from the parent.
 
+Agent Variants are intended for agents callable by OpenCode's `task` tool. The wizard defaults to a subagent-capable parent filter (`mode: "subagent"` or `mode: "all"`) and hides primary-only agents from add/edit parent pickers. This is a wizard-only setting, not a sidecar field. Existing sidecar entries for primary-only parents still appear in edit/delete/toggle flows so they can be repaired.
+
 ## Description Generation
 
 If a variant does not set `description`, the plugin generates:
@@ -119,7 +121,8 @@ The plugin skips problematic variants instead of producing ambiguous agents:
 - variant alias equals parent name,
 - two variants generate the same alias,
 - generated alias conflicts with an existing agent,
-- variant model is definitely missing.
+- variant model is definitely missing,
+- parent is primary-only and will not be callable by `task`.
 
 Run `Agent Variants: Configure` -> `Run diagnostics` to inspect these issues.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-agent-variants",
-  "version": "0.1.0",
+  "version": "0.2.0-dev.2",
   "type": "module",
   "description": "OpenCode plugin for creating and managing model variants of agents",
   "license": "MIT",
@@ -55,8 +55,12 @@
   "scripts": {
     "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
     "build": "npm run clean && tsc --outDir dist --declaration",
-    "ci": "npm run typecheck && npm run build && npm pack --dry-run",
+    "ci": "npm run release:intent:check && npm run typecheck && npm run build && npm pack --dry-run",
+    "commit:check": "npm run ci",
+    "hooks:install": "node scripts/install-git-hooks.mjs",
     "pack:dry-run": "npm pack --dry-run",
+    "release:intent": "node scripts/set-release-intent.mjs",
+    "release:intent:check": "node scripts/check-release-intent.mjs",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run typecheck && npm run build"
   },