opencode-agent-variants 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agent Variants contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,257 @@
+# OpenCode Agent Variants
+
+OpenCode Agent Variants creates model-specific versions of your agents without copying prompts by hand.
+
+Use it when you want the main model to choose between agents like:
+
+- `general` for the default or strongest model
+- `general-light` for a cheaper/faster model
+- `explore` for normal codebase exploration
+- `explore-light` for routine exploration on a smaller model
+
+The plugin adds generated variants to OpenCode's normal `task` tool list and provides one TUI wizard for editing the variant config.
+
+## Features
+
+- Generate variants from existing agents with model, temperature, prompt, description, options, and color overrides.
+- Keep OpenCode's built-in agent prompts and permissions up to date by routing built-in variants to their native parent agent.
+- Create real copied variants for agents defined in config or markdown.
+- Manage variants from a single TUI command: `Agent Variants: Configure`.
+- Store all plugin settings in a sidecar file instead of editing `opencode.json` for every variant.
+- Avoid agent-tool pollution: the plugin does not register management tools for the assistant.
+
+## Install
+
+Install it with OpenCode's plugin installer:
+
+```sh
+opencode plugin opencode-agent-variants --global
+```
+
+The installer detects both plugin targets and updates the right config files:
+
+- server target in `opencode.json` or `opencode.jsonc`
+- TUI target in `tui.json` or `tui.jsonc`
+
+Restart OpenCode after installation.
+
+## Manual Install
+
+If you prefer to configure it manually, add the package to your OpenCode config:
+
+```jsonc
+{
+  "plugin": ["opencode-agent-variants"]
+}
+```
+
+And add the same package to your TUI config:
+
+```jsonc
+{
+  "plugin": ["opencode-agent-variants"]
+}
+```
+
+For local development, use a file URL or local path instead of the npm package name.
+
+## Wizard
+
+Open the wizard from the command palette:
+
+```txt
+Agent Variants: Configure
+```
+
+If your TUI build exposes plugin slash commands, you can also run:
+
+```txt
+/agent-variants
+```
+
+The wizard supports:
+
+- adding variants
+- 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
+- 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.
+
+## Config File
+
+The plugin writes a sidecar config file at:
+
+```txt
+~/.config/opencode/agent-variants.jsonc
+```
+
+This file is separate from `opencode.json`. Your normal OpenCode config remains the source of truth for providers, base agents, permissions, and any explicit model overrides you already have.
+
+See `docs/CONFIG.md` for the complete config reference and `agent-variants.example.jsonc` for a fully commented starter file.
+
+## Example
+
+```jsonc
+{
+  "debug": false,
+  "models": {
+    "light": {
+      "model": "zai-coding-plan/glm-5.1",
+      "label": "GLM 5.1"
+    }
+  },
+  "agents": {
+    "general": {
+      "parent": {
+        "description_append": "Uses the default smartest model. Expensive; use for hard tasks."
+      },
+      "variants": {
+        "light": {
+          "model": "light",
+          "description_append": "Use for most tasks that do not need the best model."
+        }
+      }
+    },
+    "explore": {
+      "parent": {
+        "description_append": "Uses the default smartest model. Use for difficult investigations."
+      },
+      "variants": {
+        "light": {
+          "model": "light",
+          "description_append": "Use for most code search, reading, and exploration tasks."
+        }
+      }
+    }
+  }
+}
+```
+
+Variant names default to `${parent}-${variantKey}`. In the example above, `general` plus variant key `light` becomes `general-light`.
+
+Description and prompt fields support template variables such as `{parent}`, `{alias}`, `{variant_key}`, `{model}`, `{model_label}`, and `{routed_agent}`.
+
+## Supported Fields
+
+Parents and variants support these fields:
+
+- `model`
+- `variant`
+- `temperature`
+- `top_p`
+- `prompt`
+- `prompt_prepend`
+- `prompt_append`
+- `description`
+- `description_prepend`
+- `description_append`
+- `options`
+- `color`
+- `disable`
+
+Variants also support:
+
+- `name`
+
+`permission`, `tools`, and `mode` are inherited from the parent and are intentionally not configured in the sidecar.
+
+## Built-In Agents
+
+Built-in agents such as `general` and `explore` cannot be copied externally without vendoring OpenCode internals. For these agents, the plugin creates a virtual alias:
+
+- The variant appears in the task tool list.
+- The main model can call `task` once with the variant name.
+- The plugin routes the call to the native parent before execution.
+- The plugin applies configured model, request parameter, and explicit prompt overrides.
+- The plugin annotates task result metadata/output with the selected variant alias, routed native agent, and effective model.
+
+This preserves native prompts and permissions. The child session may internally show the parent agent name for built-in variants; that is expected.
+
+## Config Agents
+
+Agents defined in `opencode.json`, `.opencode/agent/*.md`, or global agent markdown can be copied directly. Their variants are real generated config agents with the supported overrides applied.
+
+## Disable Rules
+
+- If the parent is disabled in OpenCode config, variants are skipped.
+- If a sidecar parent has `disable: true`, the parent override and all variants are skipped.
+- If a variant has `disable: true`, only that variant is skipped.
+- Parent overrides apply only when the parent has at least one enabled variant.
+- 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.
+
+## Debug Mode
+
+Debug mode is off by default. Enable it from the wizard with `Debug mode: off`.
+
+When enabled, the server plugin emits diagnostic log lines and TUI toast notifications for built-in virtual variants:
+
+- when a variant is routed, such as `general-light -> general`
+- the short internal route token used for correlation
+- the target model and model variant
+- when the model override is applied to the child session message
+
+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.
+
+## Development
+
+Install dependencies:
+
+```sh
+npm install
+```
+
+Typecheck:
+
+```sh
+npm run typecheck
+```
+
+Build:
+
+```sh
+npm run build
+```
+
+Check package contents before publishing:
+
+```sh
+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/agent-variants.example.jsonc

@@ -0,0 +1,96 @@
+{
+  // Toggle route/model diagnostics. This can be changed from the wizard and
+  // takes effect immediately for future variant calls. Logs are written to
+  // ~/.config/opencode/agent-variants.debug.log.
+  "debug": false,
+
+  // Optional model shortcuts. Variants can use either a shortcut key like
+  // "light" or a full provider/model reference like "anthropic/claude-sonnet-4-6".
+  "models": {
+    "light": {
+      "model": "zai-coding-plan/glm-5.1",
+      "label": "GLM 5.1"
+    }
+
+    // "heavy": {
+    //   "model": "anthropic/claude-opus-4-5",
+    //   "label": "Opus 4.5"
+    // }
+  },
+
+  "agents": {
+    // Built-in agents are virtual-routed. The model sees general-light, but
+    // OpenCode executes native general to preserve the native prompt and permissions.
+    "general": {
+      // Disable the whole parent entry and all variants without deleting them.
+      // "disable": true,
+
+      "parent": {
+        // Parent fields apply only when this parent has at least one enabled variant.
+        "description_append": "Uses the default strongest model. Use for the hardest tasks."
+
+        // Optional parent overrides:
+        // "model": "heavy",
+        // "variant": "default",
+        // "temperature": 0.2,
+        // "top_p": 0.9,
+        // "prompt": "Replace the parent prompt/system prompt.",
+        // "prompt_prepend": "Text before the parent prompt/system prompt.",
+        // "prompt_append": "Text after the parent prompt/system prompt.",
+        // "description": "Replace the parent description.",
+        // "description_prepend": "Text before the parent description.",
+        // "options": { "reasoningEffort": "high" },
+        // "color": "primary"
+      },
+
+      "variants": {
+        "light": {
+          // Variant names default to parent-key, so this becomes general-light.
+          // "name": "general-cheap",
+          "model": "light",
+          "description_append": "Use {alias} for most tasks that do not need {parent}'s strongest model. Runs on {model_label}."
+
+          // Optional variant overrides:
+          // "variant": "default",
+          // "temperature": 0.1,
+          // "top_p": 0.95,
+          // "prompt": "Replace the prompt/system prompt for this variant only.",
+          // "prompt_prepend": "Text before this variant prompt/system prompt.",
+          // "prompt_append": "Text after this variant prompt/system prompt.",
+          // "description": "Replace the generated copy-of description.",
+          // "description_prepend": "Text before the generated description.",
+          // "options": { "reasoningEffort": "medium" },
+          // "color": "secondary",
+          // "disable": true
+        }
+      }
+    },
+
+    // Another built-in example.
+    "explore": {
+      "parent": {
+        "description_append": "Uses the default strongest model. Use for difficult investigations."
+      },
+      "variants": {
+        "light": {
+          "model": "light",
+          "description_append": "Use for most code search, reading, and exploration tasks."
+        }
+      }
+    },
+
+    // Config/markdown agents can be copied directly when they exist in OpenCode config.
+    // "frontend-designer": {
+    //   "parent": {
+    //     "description_append": "Uses the default strongest model. Use for high-quality frontend work."
+    //   },
+    //   "variants": {
+    //     "light": {
+    //       "name": "frontend-light",
+    //       "model": "light",
+    //       "description_append": "Use for routine frontend edits and reviews."
+    //     }
+    //   }
+    // }
+  }
+}

package/dist/config.d.ts

@@ -0,0 +1,211 @@
+import { z } from "zod";
+export declare const BUILTIN_AGENT_DESCRIPTIONS: Record<string, string>;
+declare const Patch: z.ZodObject<{
+    model: z.ZodOptional<z.ZodString>;
+    variant: z.ZodOptional<z.ZodString>;
+    temperature: z.ZodOptional<z.ZodNumber>;
+    top_p: z.ZodOptional<z.ZodNumber>;
+    prompt: z.ZodOptional<z.ZodString>;
+    prompt_prepend: z.ZodOptional<z.ZodString>;
+    prompt_append: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    description_prepend: z.ZodOptional<z.ZodString>;
+    description_append: z.ZodOptional<z.ZodString>;
+    options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    color: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodEnum<{
+        error: "error";
+        success: "success";
+        primary: "primary";
+        secondary: "secondary";
+        accent: "accent";
+        warning: "warning";
+        info: "info";
+    }>]>>;
+    disable: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+declare const Variant: z.ZodObject<{
+    model: z.ZodOptional<z.ZodString>;
+    variant: z.ZodOptional<z.ZodString>;
+    temperature: z.ZodOptional<z.ZodNumber>;
+    top_p: z.ZodOptional<z.ZodNumber>;
+    prompt: z.ZodOptional<z.ZodString>;
+    prompt_prepend: z.ZodOptional<z.ZodString>;
+    prompt_append: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    description_prepend: z.ZodOptional<z.ZodString>;
+    description_append: z.ZodOptional<z.ZodString>;
+    options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    color: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodEnum<{
+        error: "error";
+        success: "success";
+        primary: "primary";
+        secondary: "secondary";
+        accent: "accent";
+        warning: "warning";
+        info: "info";
+    }>]>>;
+    disable: z.ZodOptional<z.ZodBoolean>;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const SidecarConfig: z.ZodObject<{
+    debug: z.ZodDefault<z.ZodBoolean>;
+    models: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        model: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    agents: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        disable: z.ZodOptional<z.ZodBoolean>;
+        parent: z.ZodDefault<z.ZodObject<{
+            model: z.ZodOptional<z.ZodString>;
+            variant: z.ZodOptional<z.ZodString>;
+            temperature: z.ZodOptional<z.ZodNumber>;
+            top_p: z.ZodOptional<z.ZodNumber>;
+            prompt: z.ZodOptional<z.ZodString>;
+            prompt_prepend: z.ZodOptional<z.ZodString>;
+            prompt_append: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+            description_prepend: z.ZodOptional<z.ZodString>;
+            description_append: z.ZodOptional<z.ZodString>;
+            options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            color: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodEnum<{
+                error: "error";
+                success: "success";
+                primary: "primary";
+                secondary: "secondary";
+                accent: "accent";
+                warning: "warning";
+                info: "info";
+            }>]>>;
+            disable: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        variants: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+            model: z.ZodOptional<z.ZodString>;
+            variant: z.ZodOptional<z.ZodString>;
+            temperature: z.ZodOptional<z.ZodNumber>;
+            top_p: z.ZodOptional<z.ZodNumber>;
+            prompt: z.ZodOptional<z.ZodString>;
+            prompt_prepend: z.ZodOptional<z.ZodString>;
+            prompt_append: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+            description_prepend: z.ZodOptional<z.ZodString>;
+            description_append: z.ZodOptional<z.ZodString>;
+            options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            color: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodEnum<{
+                error: "error";
+                success: "success";
+                primary: "primary";
+                secondary: "secondary";
+                accent: "accent";
+                warning: "warning";
+                info: "info";
+            }>]>>;
+            disable: z.ZodOptional<z.ZodBoolean>;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type AgentPatch = z.infer<typeof Patch>;
+export type VariantConfig = z.infer<typeof Variant>;
+export type SidecarConfig = z.infer<typeof SidecarConfig>;
+export type DiagnosticLevel = "error" | "warning" | "info";
+export type Diagnostic = {
+    level: DiagnosticLevel;
+    message: string;
+    agent?: string;
+    variant?: string;
+    alias?: string;
+};
+export type ModelCatalog = {
+    providers: Set<string>;
+    providersWithModelList: Set<string>;
+    refs: Set<string>;
+};
+export type TemplateContext = {
+    parent: string;
+    alias?: string;
+    variant_key?: string;
+    model?: string;
+    model_label?: string;
+    routed_agent?: string;
+};
+export declare function defaultConfigDir(): string;
+export declare function defaultSidecarPath(configDir?: string): string;
+export declare function debugLogPath(configDir?: string): string;
+export declare function emptyConfig(): SidecarConfig;
+export declare function loadSidecar(filePath?: string): {
+    debug: boolean;
+    models: Record<string, {
+        model: string;
+        label?: string | undefined;
+    }>;
+    agents: Record<string, {
+        parent: {
+            model?: string | undefined;
+            variant?: string | undefined;
+            temperature?: number | undefined;
+            top_p?: number | undefined;
+            prompt?: string | undefined;
+            prompt_prepend?: string | undefined;
+            prompt_append?: string | undefined;
+            description?: string | undefined;
+            description_prepend?: string | undefined;
+            description_append?: string | undefined;
+            options?: Record<string, unknown> | undefined;
+            color?: string | undefined;
+            disable?: boolean | undefined;
+        };
+        variants: Record<string, {
+            model?: string | undefined;
+            variant?: string | undefined;
+            temperature?: number | undefined;
+            top_p?: number | undefined;
+            prompt?: string | undefined;
+            prompt_prepend?: string | undefined;
+            prompt_append?: string | undefined;
+            description?: string | undefined;
+            description_prepend?: string | undefined;
+            description_append?: string | undefined;
+            options?: Record<string, unknown> | undefined;
+            color?: string | undefined;
+            disable?: boolean | undefined;
+            name?: string | undefined;
+        }>;
+        disable?: boolean | undefined;
+    }>;
+};
+export declare function saveSidecar(config: SidecarConfig, filePath?: string): void;
+export declare function renderTemplate(input: string | undefined, context?: TemplateContext): string | undefined;
+export declare function applyTextPatch(base: string | undefined, patch: Pick<AgentPatch, "description" | "description_prepend" | "description_append">, context?: TemplateContext): string;
+export declare function applyPromptPatch(base: string | undefined, patch: Pick<AgentPatch, "prompt" | "prompt_prepend" | "prompt_append">, context?: TemplateContext): string;
+export declare function resolveModel(input: string | undefined, config: SidecarConfig): string | undefined;
+export declare function modelLabel(input: string | undefined, config: SidecarConfig): string;
+export declare function splitModelRef(model: string | undefined): {
+    providerID: string;
+    modelID: string;
+} | undefined;
+export declare function variantName(parent: string, key: string, variant: Pick<VariantConfig, "name">): string;
+export declare function templateContext(parent: string, key: string | undefined, variant: Pick<VariantConfig, "name" | "model">, config: SidecarConfig): {
+    parent: string;
+    alias: string;
+    variant_key: string | undefined;
+    model: string | undefined;
+    model_label: string;
+    routed_agent: string;
+};
+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 diagnoseConfig(config: SidecarConfig, input: {
+    agents: string[];
+    providers: unknown;
+    pluginEntries?: unknown[];
+}): Diagnostic[];
+export declare function fingerprint(input: {
+    parentSessionID: string;
+    agent: string;
+    prompt: string;
+    description?: string;
+}): string;
+export declare function hasPromptPatch(patch: AgentPatch): boolean;
+export declare function hasRequestPatch(patch: AgentPatch): boolean;
+export {};