opencode-magi 0.0.0-dev-20260524220537 → 0.0.0-dev-20260525005102

package/README.md

@@ -155,6 +155,20 @@ Add the following content to the configuration file.
 
 Entries with `ref` are expanded from `agents.refs`. Fields set alongside `ref` override fields from the preset.
 
+`model` can be a single `provider/model` string or an ordered candidate array. Candidate arrays are resolved during validation against OpenCode's model catalog; the first available model is selected. Put provider-specific options on object candidates, not on the agent role.
+
+```json
+{
+  "model": [
+    "anthropic/claude-sonnet-4-5",
+    {
+      "id": "openai/gpt-5.1",
+      "options": { "reasoningEffort": "high" }
+    }
+  ]
+}
+```
+
 After refs are expanded, `review.agents[].account` is the GitHub account used to post reviews and approvals. Must be authenticated with `gh auth token --user <account>` and must be unique. `merge.editor.account` is used by `/magi:merge` to push fixes, close PRs, and merge PRs.
 
 #### Validate config

package/dist/config/resolve.js

@@ -33,6 +33,12 @@ export function triageAgentKey(agent, index) {
 export function validateReviewerId(id) {
     return ID_PATTERN.test(id);
 }
+function normalizedModel(model) {
+    if (typeof model !== "string") {
+        throw new Error("model must be normalized before resolving agents");
+    }
+    return model;
+}
 function clonePermissionValue(value) {
     return typeof value === "string" ? value : { ...value };
 }
@@ -86,6 +92,7 @@ export function resolveAgents(config) {
         editor: editor
             ? {
                 ...editor,
+                model: normalizedModel(editor.model),
                 permission: resolveEditorPermission(agents, editor),
             }
             : undefined,
@@ -93,18 +100,21 @@ export function resolveAgents(config) {
             ...reviewer,
             key: reviewerKey(reviewer, index),
             index,
+            model: normalizedModel(reviewer.model),
             permission: resolveReviewerPermission(agents, reviewer),
         })),
         triage: (config.triage?.agents ?? []).map((agent, index) => ({
             ...agent,
             key: triageAgentKey(agent, index),
             index,
+            model: normalizedModel(agent.model),
             permission: resolveTriageAgentPermission(agents, agent),
         })),
         triageCreator: creator
             ? {
                 ...creator,
                 account: creator.account ?? "",
+                model: normalizedModel(creator.model),
                 permission: resolveTriageCreatorPermission(agents, creator),
             }
             : undefined,

package/dist/config/validate.js

@@ -4,7 +4,7 @@ import { access } from "node:fs/promises";
 import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import schema from "../../schema.json" with { type: "json" };
-import { resolveAgents, validateReviewerId } from "./resolve";
+import { resolveAgents, reviewerKey, triageAgentKey, validateReviewerId, } from "./resolve";
 const RESERVED_REVIEWER_KEYS = new Set(["editor", "orchestrator", "system"]);
 const PERMISSION_ACTIONS = new Set(["allow", "ask", "deny"]);
 const AJV = new Ajv2020({ allErrors: true, strict: false });
@@ -27,7 +27,6 @@ const REVIEWER_KEYS = new Set([
     "account",
     "id",
     "model",
-    "options",
     "permissions",
     "persona",
 ]);
@@ -35,7 +34,6 @@ const EDITOR_KEYS = new Set([
     "account",
     "author",
     "model",
-    "options",
     "permissions",
     "persona",
 ]);
@@ -43,7 +41,6 @@ const TRIAGE_AGENT_KEYS = new Set([
     "account",
     "id",
     "model",
-    "options",
     "permissions",
     "persona",
 ]);
@@ -51,7 +48,6 @@ const TRIAGE_CREATOR_KEYS = new Set([
     "account",
     "author",
     "model",
-    "options",
     "permissions",
     "persona",
 ]);
@@ -145,6 +141,7 @@ const TRIAGE_PROMPT_KEYS = new Set([
     "existingPr",
     "reconsider",
 ]);
+const MODEL_CANDIDATE_KEYS = new Set(["id", "options"]);
 function githubHost(config) {
     return config.github?.host ?? "github.com";
 }
@@ -275,26 +272,85 @@ function validatePermissionConfig(permission, path, errors) {
         }
     }
 }
-function validateModel(model, path, errors, catalog) {
-    if (!model)
-        return;
+function modelValidationError(model, path, catalog) {
     const slash = model.indexOf("/");
-    if (slash <= 0 || slash === model.length - 1) {
-        errors.push(`${path} must be a full OpenCode model ID in provider/model form`);
-        return;
-    }
+    if (slash <= 0 || slash === model.length - 1)
+        return `${path} must be a full OpenCode model ID in provider/model form`;
     if (!catalog)
-        return;
+        return undefined;
     const providerId = model.slice(0, slash);
     const modelId = model.slice(slash + 1);
     const models = catalog[providerId];
-    if (!models) {
-        errors.push(`${path} uses unknown OpenCode provider: ${providerId}`);
+    if (!models)
+        return `${path} uses unknown OpenCode provider: ${providerId}`;
+    if (!models.includes(modelId))
+        return `${path} uses unknown OpenCode model: ${model}`;
+    return undefined;
+}
+function validateModelId(model, path, errors, catalog) {
+    const error = modelValidationError(model, path, catalog);
+    if (error) {
+        errors.push(error);
+        return false;
+    }
+    return true;
+}
+function readModelCandidate(value, path, errors) {
+    if (typeof value === "string")
+        return { id: value };
+    if (!isPlainObject(value)) {
+        errors.push(`${path} must be a string or an object`);
+        return undefined;
+    }
+    validateKnownKeys(value, path, MODEL_CANDIDATE_KEYS, errors);
+    if (typeof value.id !== "string") {
+        errors.push(`${path}.id must be a string`);
+        return undefined;
+    }
+    if (value.options != null && !isPlainObject(value.options)) {
+        errors.push(`${path}.options must be an object`);
+        return undefined;
+    }
+    return { id: value.id, options: value.options };
+}
+function validateAndNormalizeModel(target, path, errors, catalog) {
+    const model = target.model;
+    if (typeof model === "string") {
+        validateModelId(model, path, errors, catalog);
         return;
     }
-    if (!models.includes(modelId)) {
-        errors.push(`${path} uses unknown OpenCode model: ${model}`);
+    if (!Array.isArray(model)) {
+        if (model != null)
+            errors.push(`${path} must be a string or an array`);
+        return;
     }
+    if (!model.length) {
+        errors.push(`${path} must contain at least one model candidate`);
+        return;
+    }
+    if (!catalog) {
+        errors.push(`${path} requires an OpenCode model catalog`);
+        return;
+    }
+    const candidateErrors = [];
+    for (const [index, value] of model.entries()) {
+        const candidatePath = `${path}[${index}]`;
+        const candidate = readModelCandidate(value, candidatePath, errors);
+        if (!candidate)
+            continue;
+        const idPath = isPlainObject(value) ? `${candidatePath}.id` : candidatePath;
+        const error = modelValidationError(candidate.id, idPath, catalog);
+        if (!error) {
+            target.model = candidate.id;
+            if (candidate.options)
+                target.options = candidate.options;
+            else
+                delete target.options;
+            return;
+        }
+        candidateErrors.push(error);
+    }
+    errors.push(`${path} must contain at least one usable OpenCode model candidate${candidateErrors.length ? ` (${candidateErrors.join("; ")})` : ""}`);
 }
 function validateReviewerList(reviewers, path, errors, catalog) {
     if (reviewers == null)
@@ -315,14 +371,11 @@ function validateReviewerList(reviewers, path, errors, catalog) {
         validateKnownKeys(reviewer, `${path}[${index}]`, REVIEWER_KEYS, errors);
         if (!reviewer.model)
             errors.push(`${path}[${index}].model is required`);
-        validateString(reviewer.model, `${path}[${index}].model`, errors);
-        validateModel(reviewer.model, `${path}[${index}].model`, errors, catalog);
+        validateAndNormalizeModel(reviewer, `${path}[${index}].model`, errors, catalog);
         if (!reviewer.account)
             errors.push(`${path}[${index}].account is required`);
         validateString(reviewer.account, `${path}[${index}].account`, errors);
         validateString(reviewer.persona, `${path}[${index}].persona`, errors);
-        if (reviewer.options != null && !isPlainObject(reviewer.options))
-            errors.push(`${path}[${index}].options must be an object`);
         validatePermissionConfig(reviewer.permissions, `${path}[${index}].permissions`, errors);
         if (reviewer.id) {
             if (!validateReviewerId(reviewer.id)) {
@@ -353,14 +406,11 @@ function validateTriageAgentList(agents, path, errors, catalog) {
         validateKnownKeys(agent, `${path}[${index}]`, TRIAGE_AGENT_KEYS, errors);
         if (!agent.model)
             errors.push(`${path}[${index}].model is required`);
-        validateString(agent.model, `${path}[${index}].model`, errors);
-        validateModel(agent.model, `${path}[${index}].model`, errors, catalog);
+        validateAndNormalizeModel(agent, `${path}[${index}].model`, errors, catalog);
         if (!agent.account)
             errors.push(`${path}[${index}].account is required`);
         validateString(agent.account, `${path}[${index}].account`, errors);
         validateString(agent.persona, `${path}[${index}].persona`, errors);
-        if (agent.options != null && !isPlainObject(agent.options))
-            errors.push(`${path}[${index}].options must be an object`);
         validatePermissionConfig(agent.permissions, `${path}[${index}].permissions`, errors);
         if (agent.id) {
             if (!validateReviewerId(agent.id)) {
@@ -406,15 +456,11 @@ function validateEditor(editor, path, errors, catalog) {
     if (!editor.model)
         errors.push(`${path}.model is required`);
     validateKnownKeys(editor, path, EDITOR_KEYS, errors);
-    validateString(editor.model, `${path}.model`, errors);
+    validateAndNormalizeModel(editor, `${path}.model`, errors, catalog);
     validateString(editor.account, `${path}.account`, errors);
     validateString(editor.persona, `${path}.persona`, errors);
-    validateModel(editor.model, `${path}.model`, errors, catalog);
     if (!editor.account)
         errors.push(`${path}.account is required`);
-    if (editor.options != null && !isPlainObject(editor.options)) {
-        errors.push(`${path}.options must be an object`);
-    }
     validatePermissionConfig(editor.permissions, `${path}.permissions`, errors);
     const author = editor.author;
     if (!author || !isPlainObject(author)) {
@@ -450,12 +496,8 @@ function validateTriageCreator(creator, path, errors, catalog) {
     if (!creator.model)
         errors.push(`${path}.model is required`);
     validateString(creator.account, `${path}.account`, errors);
-    validateString(creator.model, `${path}.model`, errors);
+    validateAndNormalizeModel(creator, `${path}.model`, errors, catalog);
     validateString(creator.persona, `${path}.persona`, errors);
-    validateModel(creator.model, `${path}.model`, errors, catalog);
-    if (creator.options != null && !isPlainObject(creator.options)) {
-        errors.push(`${path}.options must be an object`);
-    }
     validatePermissionConfig(creator.permissions, `${path}.permissions`, errors);
     const author = creator.author;
     if (!author || !isPlainObject(author)) {
@@ -684,7 +726,12 @@ function validateTriage(config, errors, options) {
         errors.push("triage.agents is required");
     validateTriageAgentList(triage.agents, "triage.agents", errors, options.modelCatalog);
     if (Array.isArray(triage.agents)) {
-        const resolvedTriageAgents = resolveAgents(config).triage ?? [];
+        const resolvedTriageAgents = triage.agents.map((agent, index) => ({
+            account: agent && typeof agent === "object" && typeof agent.account === "string"
+                ? agent.account
+                : "",
+            key: agent && typeof agent === "object" ? triageAgentKey(agent, index) : "",
+        }));
         validateResolvedTriageAgents(resolvedTriageAgents, "triage.resolvedAgents", errors);
         if (reporter != null &&
             !resolvedTriageAgents.some((agent) => agent.key === reporter)) {
@@ -778,10 +825,10 @@ async function fetchPermissions(config, exec, account) {
     return JSON.parse(raw);
 }
 async function validateWorktreeConfig(config, exec, options, errors) {
-    const agents = resolveAgents(config);
-    const checkEditor = Boolean(agents.editor && (options.requireEditor || options.requireWorktreeConfig));
+    const checkEditor = Boolean(config.merge?.editor &&
+        (options.requireEditor || options.requireWorktreeConfig));
     const checkTriageCreator = Boolean(config.triage?.automation?.create &&
-        agents.triageCreator &&
+        config.triage?.creator &&
         (options.requireTriage || options.requireWorktreeConfig));
     if (!checkEditor && !checkTriageCreator)
         return;
@@ -853,6 +900,9 @@ export async function validateConfig(config, options = {}) {
     const warnings = [];
     if (!config || typeof config !== "object")
         errors.push("config must be an object");
+    if (options.requireModelCatalog && !options.modelCatalog) {
+        errors.push("OpenCode model catalog could not be loaded");
+    }
     expandAgentRefs(config, errors);
     if (config && typeof config === "object")
         validateJsonSchema(config, errors);
@@ -880,7 +930,16 @@ export async function validateConfig(config, options = {}) {
             errors.push("review.agents is required");
         validateReviewerList(config.review.agents, "review.agents", errors, options.modelCatalog);
         if (Array.isArray(config.review.agents)) {
-            validateResolvedReviewers(resolveAgents(config).reviewers, "review.resolvedAgents", errors);
+            validateResolvedReviewers(config.review.agents.map((reviewer, index) => ({
+                account: reviewer &&
+                    typeof reviewer === "object" &&
+                    typeof reviewer.account === "string"
+                    ? reviewer.account
+                    : "",
+                key: reviewer && typeof reviewer === "object"
+                    ? reviewerKey(reviewer, index)
+                    : "",
+            })), "review.resolvedAgents", errors);
         }
     }
     if (options.requireTriage && !config.triage) {

package/dist/index.js

@@ -9,7 +9,7 @@ import { loadConfig, mergeMagiConfig } from "./config/load";
 import { outputBaseDirs } from "./config/output";
 import { worktreeBaseDirs } from "./config/worktree";
 import { resolveRepository } from "./config/resolve";
-import { validateConfig } from "./config/validate";
+import { validateConfig, } from "./config/validate";
 import { withGitHubApiRetry } from "./github/retry";
 import { mapPool } from "./orchestrator/pool";
 import { MagiRunManager } from "./orchestrator/run-manager";
@@ -317,6 +317,9 @@ function issueMarkdownLink(repository, issue) {
     const url = `https://${host}/${repository.github.owner}/${repository.github.repo}/issues/${issue}`;
     return `[#${issue}](${url})`;
 }
+function validationError(validation) {
+    return new Error(JSON.stringify(validation, null, 2));
+}
 function isPlainObject(value) {
     return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
@@ -379,6 +382,7 @@ export async function validateMagiConfigFiles(directory, options = {}) {
                 : undefined,
             modelCatalog: options.modelCatalog,
             requireGithub: hasProjectConfig && Boolean(mergedConfig.review?.agents),
+            requireModelCatalog: true,
             requireWorktreeConfig: true,
         });
         loadedFrom = existing.map((status) => status.path).join(", ");
@@ -430,7 +434,8 @@ export const MagiPlugin = async ({ client, directory }) => {
             .then(extractModelCatalog)
             .catch(() => catalogClient.provider
             ?.list({ query: { directory } })
-            .then(extractModelCatalog));
+            .then(extractModelCatalog))
+            .catch(() => undefined);
         return modelCatalogPromise;
     }
     return {
@@ -475,9 +480,10 @@ export const MagiPlugin = async ({ client, directory }) => {
                         exec: retryingExec,
                         modelCatalog: await modelCatalog(),
                         requireEditor: true,
+                        requireModelCatalog: true,
                     });
                     if (!validation.ok)
-                        return JSON.stringify(validation, null, 2);
+                        throw validationError(validation);
                     const repository = resolveRepository(config);
                     const sync = parsed.sync || args.sync === true;
                     const states = await mapPool(parsed.prs, repository.concurrency.runs, (pr) => runManager.startMerge({
@@ -517,9 +523,10 @@ export const MagiPlugin = async ({ client, directory }) => {
                         directory,
                         exec: retryingExec,
                         modelCatalog: await modelCatalog(),
+                        requireModelCatalog: true,
                     });
                     if (!validation.ok)
-                        return JSON.stringify(validation, null, 2);
+                        throw validationError(validation);
                     const repository = resolveRepository(config);
                     const sync = parsed.sync || args.sync === true;
                     const states = await mapPool(parsed.prs, repository.concurrency.runs, (pr) => runManager.startReview({
@@ -557,12 +564,13 @@ export const MagiPlugin = async ({ client, directory }) => {
                         exec: retryingExec,
                         modelCatalog: await modelCatalog(),
                         requireEditor: config.triage?.automation?.merge === true,
+                        requireModelCatalog: true,
                         requireReview: config.triage?.automation?.review === true ||
                             config.triage?.automation?.merge === true,
                         requireTriage: true,
                     });
                     if (!validation.ok)
-                        return JSON.stringify(validation, null, 2);
+                        throw validationError(validation);
                     const repository = resolveRepository(config);
                     if (!repository.triage)
                         return JSON.stringify({ errors: ["triage configuration is required"], ok: false }, null, 2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-magi",
-  "version": "0.0.0-dev-20260524220537",
+  "version": "0.0.0-dev-20260525005102",
   "description": "Multi-agent PR review and merge orchestration plugin for OpenCode.",
   "license": "MIT",
   "author": "Hirotomo Yamada <hirotomo.yamada@avap.co.jp>",

package/schema.json

@@ -60,8 +60,7 @@
       "additionalProperties": false,
       "properties": {
         "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" },
-        "model": { "type": "string", "minLength": 1 },
-        "options": { "type": "object", "additionalProperties": true },
+        "model": { "$ref": "#/$defs/modelConfig" },
         "account": { "type": "string", "minLength": 1 },
         "author": {
           "type": "object",
@@ -83,8 +82,7 @@
       "properties": {
         "ref": { "type": "string", "minLength": 1 },
         "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" },
-        "model": { "type": "string", "minLength": 1 },
-        "options": { "type": "object", "additionalProperties": true },
+        "model": { "$ref": "#/$defs/modelConfig" },
         "account": { "type": "string", "minLength": 1 },
         "permissions": { "$ref": "#/$defs/permissions" },
         "persona": { "type": "string" }
@@ -97,8 +95,7 @@
       "additionalProperties": false,
       "properties": {
         "ref": { "type": "string", "minLength": 1 },
-        "model": { "type": "string", "minLength": 1 },
-        "options": { "type": "object", "additionalProperties": true },
+        "model": { "$ref": "#/$defs/modelConfig" },
         "account": { "type": "string", "minLength": 1 },
         "author": {
           "type": "object",
@@ -121,9 +118,8 @@
       "properties": {
         "ref": { "type": "string", "minLength": 1 },
         "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" },
-        "model": { "type": "string", "minLength": 1 },
+        "model": { "$ref": "#/$defs/modelConfig" },
         "account": { "type": "string", "minLength": 1 },
-        "options": { "type": "object", "additionalProperties": true },
         "permissions": { "$ref": "#/$defs/permissions" },
         "persona": { "type": "string" }
       }
@@ -136,8 +132,7 @@
       "properties": {
         "ref": { "type": "string", "minLength": 1 },
         "account": { "type": "string", "minLength": 1 },
-        "model": { "type": "string", "minLength": 1 },
-        "options": { "type": "object", "additionalProperties": true },
+        "model": { "$ref": "#/$defs/modelConfig" },
         "author": {
           "type": "object",
           "required": ["name", "email"],
@@ -151,6 +146,30 @@
         "persona": { "type": "string" }
       }
     },
+    "modelConfig": {
+      "oneOf": [
+        { "type": "string", "minLength": 1 },
+        {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "oneOf": [
+              { "type": "string", "minLength": 1 },
+              { "$ref": "#/$defs/modelCandidate" }
+            ]
+          }
+        }
+      ]
+    },
+    "modelCandidate": {
+      "type": "object",
+      "required": ["id"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "options": { "type": "object", "additionalProperties": true }
+      }
+    },
     "automation": {
       "type": "object",
       "additionalProperties": false,