@osovv/vv-opencode 0.17.4 → 0.19.0

package/dist/lib/agent-models.js

@@ -1,8 +1,8 @@
 // FILE: src/lib/agent-models.ts
-// VERSION: 0.2.0
+// VERSION: 0.3.0
 // START_MODULE_CONTRACT
 //   PURPOSE: Define supported vvoc model target IDs and shared model override validation helpers.
-//   SCOPE: Model target ID lists, type guards, model formatting, and model-argument parsing reused by CLI commands and vvoc config validation.
+//   SCOPE: Model target ID lists, type guards, model formatting, and model-argument parsing reused by CLI commands and vvoc config validation, including OpenCode agent targets that support variants.
 //   DEPENDS: [src/lib/managed-agents.ts]
 //   LINKS: [M-CLI-CONFIG, M-CLI-COMMANDS, M-CLI-PRESET]
 //   ROLE: RUNTIME
@@ -10,32 +10,41 @@
 // END_MODULE_CONTRACT
 //
 // START_MODULE_MAP
-//   SPECIAL_AGENT_NAMES - Target IDs that support provider/model[:variant] syntax.
+//   SPECIAL_AGENT_NAMES - Target IDs that support provider/model[:variant] syntax in canonical vvoc config.
 //   OPENCODE_DEFAULT_MODEL_TARGETS - Target IDs that map to top-level OpenCode model fields.
-//   CONFIGURABLE_OPENCODE_SUBAGENTS - Built-in OpenCode agent IDs vvoc can override directly.
+//   CONFIGURABLE_OPENCODE_PRIMARY_AGENTS - Built-in OpenCode primary agent IDs vvoc can override directly.
+//   CONFIGURABLE_OPENCODE_SUBAGENTS - Built-in OpenCode subagent IDs vvoc can override directly.
+//   CONFIGURABLE_OPENCODE_AGENTS - Built-in OpenCode agent IDs that vvoc can map to model plus variant fields.
 //   SupportedModelTargetName - Union of every preset-compatible model target ID.
 //   MODEL_TARGET_NAME_CHOICES - Human-readable supported target list for CLI errors.
 //   isSpecialAgentName - Checks whether a target uses Guardian-style model syntax.
 //   isOpenCodeDefaultModelTargetName - Checks whether a target maps to top-level OpenCode model fields.
+//   isConfigurableOpenCodeAgentName - Checks whether a target is a built-in OpenCode agent override.
 //   isConfigurableOpenCodeSubagentName - Checks whether a target is a built-in OpenCode agent override.
 //   parseModelTargetName - Validates a user-supplied model target ID.
 //   parseGuardianStyleModelArg - Validates provider/model[:variant] syntax.
-//   parseOpenCodeModelArg - Validates provider/model syntax.
+//   parseOpenCodeModelArg - Validates plain provider/model syntax for top-level OpenCode model fields.
+//   parseOpenCodeAgentModelArg - Validates provider/model[:variant] syntax for OpenCode agent fields.
 //   normalizeModelTargetOverride - Validates and canonicalizes a stored model override string for any supported target.
 //   formatAgentModel - Formats a model and optional variant for CLI output.
 // END_MODULE_MAP
 //
 // START_CHANGE_SUMMARY
-//   LAST_CHANGE: [v0.2.0 - Added OpenCode default and small-model targets to shared validation helpers.]
+//   LAST_CHANGE: [v0.3.0 - Added variant-aware OpenCode agent targets for build/plan/general/explore while keeping top-level default model fields plain.]
 // END_CHANGE_SUMMARY
 import { MANAGED_OPENCODE_AGENTS, isManagedOpenCodeAgentName, } from "./managed-agents.js";
 export const SPECIAL_AGENT_NAMES = ["guardian", "memory-reviewer"];
 export const OPENCODE_DEFAULT_MODEL_TARGETS = ["default", "small-model"];
+export const CONFIGURABLE_OPENCODE_PRIMARY_AGENTS = ["build", "plan"];
 export const CONFIGURABLE_OPENCODE_SUBAGENTS = ["general", "explore"];
+export const CONFIGURABLE_OPENCODE_AGENTS = [
+    ...CONFIGURABLE_OPENCODE_PRIMARY_AGENTS,
+    ...CONFIGURABLE_OPENCODE_SUBAGENTS,
+];
 export const SUPPORTED_MODEL_TARGET_NAMES = [
     ...SPECIAL_AGENT_NAMES,
     ...OPENCODE_DEFAULT_MODEL_TARGETS,
-    ...CONFIGURABLE_OPENCODE_SUBAGENTS,
+    ...CONFIGURABLE_OPENCODE_AGENTS,
     ...MANAGED_OPENCODE_AGENTS.map((definition) => definition.name),
 ];
 export const MODEL_TARGET_NAME_CHOICES = SUPPORTED_MODEL_TARGET_NAMES.join(", ");
@@ -48,6 +57,9 @@ export function isOpenCodeDefaultModelTargetName(value) {
 export function isConfigurableOpenCodeSubagentName(value) {
     return CONFIGURABLE_OPENCODE_SUBAGENTS.includes(value);
 }
+export function isConfigurableOpenCodeAgentName(value) {
+    return CONFIGURABLE_OPENCODE_AGENTS.includes(value);
+}
 export function parseModelTargetName(value, operation) {
     if (typeof value !== "string" || !value.trim()) {
         throw new Error(`target argument required for ${operation}`);
@@ -55,13 +67,19 @@ export function parseModelTargetName(value, operation) {
     const trimmed = value.trim();
     if (isSpecialAgentName(trimmed) ||
         isOpenCodeDefaultModelTargetName(trimmed) ||
-        isConfigurableOpenCodeSubagentName(trimmed) ||
+        isConfigurableOpenCodeAgentName(trimmed) ||
         isManagedOpenCodeAgentName(trimmed)) {
         return trimmed;
     }
     throw new Error(`unsupported target: ${trimmed}. Expected one of: ${MODEL_TARGET_NAME_CHOICES}`);
 }
 export function parseGuardianStyleModelArg(value, operation) {
+    return parseModelArgWithOptionalVariant(value, operation);
+}
+export function parseOpenCodeAgentModelArg(value, operation) {
+    return parseModelArgWithOptionalVariant(value, operation);
+}
+function parseModelArgWithOptionalVariant(value, operation) {
     if (typeof value !== "string" || !value.trim()) {
         throw new Error(`model argument required for ${operation}`);
     }
@@ -81,20 +99,21 @@ export function parseGuardianStyleModelArg(value, operation) {
     return { model: trimmed };
 }
 export function parseOpenCodeModelArg(value, operation) {
-    if (typeof value !== "string" || !value.trim()) {
-        throw new Error(`model argument required for ${operation}`);
+    const { model, variant } = parseModelArgWithOptionalVariant(value, operation);
+    if (variant) {
+        throw new Error(`model must be in provider/model-id format without :variant for ${operation}, got: ${value}`);
     }
-    const trimmed = value.trim();
-    if (!trimmed.includes("/")) {
-        throw new Error(`model must be in provider/model-id format, got: ${trimmed}`);
-    }
-    return trimmed;
+    return model;
 }
 export function normalizeModelTargetOverride(targetName, value, operation) {
     if (isSpecialAgentName(targetName)) {
         const { model, variant } = parseGuardianStyleModelArg(value, operation);
         return formatAgentModel(model, variant);
     }
+    if (isConfigurableOpenCodeAgentName(targetName) || isManagedOpenCodeAgentName(targetName)) {
+        const { model, variant } = parseOpenCodeAgentModelArg(value, operation);
+        return formatAgentModel(model, variant);
+    }
     return parseOpenCodeModelArg(value, operation);
 }
 export function formatAgentModel(model, variant) {

package/dist/lib/agent-models.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-models.js","sourceRoot":"","sources":["../../src/lib/agent-models.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,iBAAiB;AACjB,wBAAwB;AACxB,kGAAkG;AAClG,+IAA+I;AAC/I,yCAAyC;AACzC,wDAAwD;AACxD,kBAAkB;AAClB,sBAAsB;AACtB,sBAAsB;AACtB,EAAE;AACF,mBAAmB;AACnB,mFAAmF;AACnF,6FAA6F;AAC7F,8FAA8F;AAC9F,iFAAiF;AACjF,qFAAqF;AACrF,mFAAmF;AACnF,wGAAwG;AACxG,wGAAwG;AACxG,sEAAsE;AACtE,4EAA4E;AAC5E,6DAA6D;AAC7D,wHAAwH;AACxH,4EAA4E;AAC5E,iBAAiB;AACjB,EAAE;AACF,uBAAuB;AACvB,yGAAyG;AACzG,qBAAqB;AAErB,OAAO,EACL,uBAAuB,EACvB,0BAA0B,GAE3B,MAAM,qBAAqB,CAAC;AAE7B,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,UAAU,EAAE,iBAAiB,CAAU,CAAC;AAG5E,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAAC,SAAS,EAAE,aAAa,CAAU,CAAC;AAGlF,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAAC,SAAS,EAAE,SAAS,CAAU,CAAC;AAS/E,MAAM,CAAC,MAAM,4BAA4B,GAAwC;IAC/E,GAAG,mBAAmB;IACtB,GAAG,8BAA8B;IACjC,GAAG,+BAA+B;IAClC,GAAG,uBAAuB,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC;CAChE,CAAC;AAEF,MAAM,CAAC,MAAM,yBAAyB,GAAG,4BAA4B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEjF,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC9C,OAAO,mBAAmB,CAAC,QAAQ,CAAC,KAAyB,CAAC,CAAC;AACjE,CAAC;AAED,MAAM,UAAU,gCAAgC,CAC9C,KAAa;IAEb,OAAO,8BAA8B,CAAC,QAAQ,CAAC,KAAuC,CAAC,CAAC;AAC1F,CAAC;AAED,MAAM,UAAU,kCAAkC,CAChD,KAAa;IAEb,OAAO,+BAA+B,CAAC,QAAQ,CAAC,KAAyC,CAAC,CAAC;AAC7F,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,KAAc,EAAE,SAAiB;IACpE,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QAC/C,MAAM,IAAI,KAAK,CAAC,gCAAgC,SAAS,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAE7B,IACE,kBAAkB,CAAC,OAAO,CAAC;QAC3B,gCAAgC,CAAC,OAAO,CAAC;QACzC,kCAAkC,CAAC,OAAO,CAAC;QAC3C,0BAA0B,CAAC,OAAO,CAAC,EACnC,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,uBAAuB,OAAO,sBAAsB,yBAAyB,EAAE,CAAC,CAAC;AACnG,CAAC;AAED,MAAM,UAAU,0BAA0B,CACxC,KAAc,EACd,SAAiB;IAEjB,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QAC/C,MAAM,IAAI,KAAK,CAAC,+BAA+B,SAAS,EAAE,CAAC,CAAC;IAC9D,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAE7B,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QAC3C,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;QAC1C,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;QAC7C,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,mDAAmD,OAAO,EAAE,CAAC,CAAC;QAChF,CAAC;QACD,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;IAC5B,CAAC;IAED,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,mDAAmD,OAAO,EAAE,CAAC,CAAC;IAChF,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,KAAc,EAAE,SAAiB;IACrE,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QAC/C,MAAM,IAAI,KAAK,CAAC,+BAA+B,SAAS,EAAE,CAAC,CAAC;IAC9D,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,mDAAmD,OAAO,EAAE,CAAC,CAAC;IAChF,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,4BAA4B,CAC1C,UAAoC,EACpC,KAAc,EACd,SAAiB;IAEjB,IAAI,kBAAkB,CAAC,UAAU,CAAC,EAAE,CAAC;QACnC,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,0BAA0B,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;QACxE,OAAO,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAC1C,CAAC;IAED,OAAO,qBAAqB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,KAAc,EAAE,OAAgB;IAC/D,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAO,OAAO,CAAC,CAAC,CAAC,GAAG,KAAK,IAAI,OAAO,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;AACjD,CAAC"}
+{"version":3,"file":"agent-models.js","sourceRoot":"","sources":["../../src/lib/agent-models.ts"],"names":[],"mappings":"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"}

package/dist/lib/model-roles.d.ts

@@ -0,0 +1,44 @@
+export declare const BUILTIN_ROLE_NAMES: readonly ["default", "smart", "fast", "vision"];
+export type BuiltInRoleName = (typeof BUILTIN_ROLE_NAMES)[number];
+export declare const ROLE_REFERENCE_PREFIX = "vv-role:";
+export type ModelRolesErrorCode = "INVALID_ROLE_ID" | "INVALID_ROLE_REFERENCE" | "INVALID_MODEL_SELECTION" | "UNKNOWN_ROLE";
+export type ModelRolesError = Error & {
+    code: ModelRolesErrorCode;
+    field: "roleId" | "roleRef" | "modelSelection";
+    value: string;
+};
+export type ParsedModelSelection = {
+    provider: string;
+    model: string;
+    variant?: string;
+    normalized: string;
+};
+export type ResolvedRoleSelection = ParsedModelSelection & {
+    roleId: string;
+    roleRef: string;
+};
+export type BuiltInRoleBindings = {
+    opencodeDefaults: {
+        model: BuiltInRoleName;
+        smallModel: BuiltInRoleName;
+    };
+    opencodeAgents: {
+        build: BuiltInRoleName;
+        plan: BuiltInRoleName;
+        general: BuiltInRoleName;
+        explore: BuiltInRoleName;
+    };
+    managedAgents: {
+        guardian: BuiltInRoleName;
+        "memory-reviewer": BuiltInRoleName;
+        enhancer: BuiltInRoleName;
+        implementer: BuiltInRoleName;
+        "spec-reviewer": BuiltInRoleName;
+        "code-reviewer": BuiltInRoleName;
+        investitagor: BuiltInRoleName;
+    };
+};
+export declare function isRoleReference(value: string): boolean;
+export declare function parseModelSelection(modelSelection: string): ParsedModelSelection;
+export declare function resolveRoleReference(roleRef: string, roleMap: Record<string, string>): ResolvedRoleSelection;
+export declare function getBuiltInRoleBindings(): BuiltInRoleBindings;

package/dist/lib/model-roles.js

@@ -0,0 +1,144 @@
+// FILE: src/lib/model-roles.ts
+// VERSION: 0.1.1
+// START_MODULE_CONTRACT
+//   PURPOSE: Define built-in role IDs, role-reference parsing, concrete model-selection parsing, and deterministic built-in role bindings.
+//   SCOPE: Role ID validation, vv-role reference detection/resolution, provider/model[:variant] parsing, and hard-coded built-in role binding lookup.
+//   INPUTS: roleId | roleRef | modelSelection strings and a canonical role map.
+//   OUTPUTS: Normalized role IDs plus parsed and resolved model-selection objects.
+//   DEPENDS: [none]
+//   LINKS: [M-MODEL-ROLES]
+//   ROLE: RUNTIME
+//   MAP_MODE: EXPORTS
+// END_MODULE_CONTRACT
+//
+// START_MODULE_MAP
+//   BUILTIN_ROLE_NAMES - Built-in role IDs in deterministic order.
+//   ROLE_REFERENCE_PREFIX - Stable role-reference prefix.
+//   isRoleReference - Checks whether a value is a vv-role reference.
+//   parseModelSelection - Parses provider/model[:variant] into normalized parts.
+//   resolveRoleReference - Resolves vv-role references through a canonical role map.
+//   getBuiltInRoleBindings - Returns hard-coded role bindings for OpenCode defaults and bundled agents.
+// END_MODULE_MAP
+//
+// START_CHANGE_SUMMARY
+//   LAST_CHANGE: [v0.1.1 - Distinguished unknown-role from blank configured role bindings and aligned role-reference whitespace handling between checker and resolver.]
+//   LAST_CHANGE: [v0.1.0 - Added role ID validation, role reference resolution helpers, model selection parsing, and deterministic built-in role bindings.]
+// END_CHANGE_SUMMARY
+export const BUILTIN_ROLE_NAMES = ["default", "smart", "fast", "vision"];
+export const ROLE_REFERENCE_PREFIX = "vv-role:";
+const ROLE_ID_PATTERN = /^[a-z][a-z0-9-]*$/;
+const MODEL_SELECTION_PATTERN = /^([^\s/:]+)\/([^\s/:]+)(?::([^\s:]+))?$/;
+const BUILTIN_ROLE_BINDINGS = {
+    opencodeDefaults: {
+        model: "default",
+        smallModel: "fast",
+    },
+    opencodeAgents: {
+        build: "smart",
+        plan: "smart",
+        general: "default",
+        explore: "fast",
+    },
+    managedAgents: {
+        guardian: "fast",
+        "memory-reviewer": "fast",
+        enhancer: "smart",
+        implementer: "default",
+        "spec-reviewer": "smart",
+        "code-reviewer": "smart",
+        investitagor: "smart",
+    },
+};
+// START_CONTRACT: isRoleReference
+//   PURPOSE: Check whether a model-like value is a vv-role:* reference.
+//   INPUTS: { value: string - Candidate model-like string. }
+//   OUTPUTS: { boolean - True only when the value starts with the vv-role prefix and has a non-empty suffix. }
+//   SIDE_EFFECTS: none
+//   LINKS: [fn-isRoleReference, fn-resolveRoleReference]
+// END_CONTRACT: isRoleReference
+export function isRoleReference(value) {
+    const trimmed = value.trim();
+    return trimmed.startsWith(ROLE_REFERENCE_PREFIX) && trimmed.length > ROLE_REFERENCE_PREFIX.length;
+}
+// START_CONTRACT: parseModelSelection
+//   PURPOSE: Parse provider/model[:variant] syntax into normalized model-selection parts.
+//   INPUTS: { modelSelection: string - Concrete model-selection input. }
+//   OUTPUTS: { ParsedModelSelection - Normalized provider/model and optional variant values. }
+//   SIDE_EFFECTS: none
+//   LINKS: [fn-parseModelSelection]
+// END_CONTRACT: parseModelSelection
+export function parseModelSelection(modelSelection) {
+    const trimmed = modelSelection.trim();
+    const match = MODEL_SELECTION_PATTERN.exec(trimmed);
+    if (!match) {
+        throw createModelRolesError("INVALID_MODEL_SELECTION", "modelSelection", modelSelection, "expected provider/model[:variant]");
+    }
+    const [, provider, model, variant] = match;
+    const normalized = variant ? `${provider}/${model}:${variant}` : `${provider}/${model}`;
+    return variant ? { provider, model, variant, normalized } : { provider, model, normalized };
+}
+// START_CONTRACT: resolveRoleReference
+//   PURPOSE: Resolve a vv-role:* reference to a concrete provider/model[:variant] selection.
+//   INPUTS: { roleRef: string - vv-role reference, roleMap: Record<string, string> - canonical role assignments. }
+//   OUTPUTS: { ResolvedRoleSelection - Parsed concrete model selection plus normalized role information. }
+//   SIDE_EFFECTS: none
+//   LINKS: [fn-resolveRoleReference, fn-parseModelSelection]
+// END_CONTRACT: resolveRoleReference
+export function resolveRoleReference(roleRef, roleMap) {
+    // START_BLOCK_RESOLVE_ROLE_REFERENCE
+    const roleId = parseRoleReference(roleRef);
+    if (!Object.hasOwn(roleMap, roleId)) {
+        throw createModelRolesError("UNKNOWN_ROLE", "roleRef", roleRef, `unknown role: ${roleId}`);
+    }
+    const rawModelSelection = roleMap[roleId];
+    if (typeof rawModelSelection !== "string" || !rawModelSelection.trim()) {
+        throw createModelRolesError("INVALID_MODEL_SELECTION", "modelSelection", typeof rawModelSelection === "string" ? rawModelSelection : String(rawModelSelection), `configured role binding is blank or invalid for role: ${roleId}`);
+    }
+    if (isRoleReference(rawModelSelection.trim())) {
+        throw createModelRolesError("INVALID_MODEL_SELECTION", "modelSelection", rawModelSelection, "role-to-role chaining is not allowed");
+    }
+    const parsed = parseModelSelection(rawModelSelection);
+    return {
+        roleId,
+        roleRef: `${ROLE_REFERENCE_PREFIX}${roleId}`,
+        ...parsed,
+    };
+    // END_BLOCK_RESOLVE_ROLE_REFERENCE
+}
+// START_CONTRACT: getBuiltInRoleBindings
+//   PURPOSE: Return deterministic built-in role bindings used by OpenCode defaults and bundled agents.
+//   INPUTS: {}
+//   OUTPUTS: { BuiltInRoleBindings - Immutable hard-coded role bindings. }
+//   SIDE_EFFECTS: none
+//   LINKS: [fn-getBuiltInRoleBindings, const-BUILTIN_ROLE_NAMES]
+// END_CONTRACT: getBuiltInRoleBindings
+export function getBuiltInRoleBindings() {
+    return {
+        opencodeDefaults: { ...BUILTIN_ROLE_BINDINGS.opencodeDefaults },
+        opencodeAgents: { ...BUILTIN_ROLE_BINDINGS.opencodeAgents },
+        managedAgents: { ...BUILTIN_ROLE_BINDINGS.managedAgents },
+    };
+}
+function parseRoleReference(roleRef) {
+    const trimmed = roleRef.trim();
+    if (!isRoleReference(trimmed)) {
+        throw createModelRolesError("INVALID_ROLE_REFERENCE", "roleRef", roleRef, `expected ${ROLE_REFERENCE_PREFIX}<role-id>`);
+    }
+    const roleId = trimmed.slice(ROLE_REFERENCE_PREFIX.length);
+    return normalizeRoleId(roleId);
+}
+function normalizeRoleId(roleId) {
+    const normalized = roleId.trim();
+    if (!ROLE_ID_PATTERN.test(normalized)) {
+        throw createModelRolesError("INVALID_ROLE_ID", "roleId", roleId, "expected lowercase letters, digits, and hyphens");
+    }
+    return normalized;
+}
+function createModelRolesError(code, field, value, detail) {
+    const error = new Error(`${code}: ${field} ${detail} (received: ${value})`);
+    error.code = code;
+    error.field = field;
+    error.value = value;
+    return error;
+}
+//# sourceMappingURL=model-roles.js.map

package/dist/lib/model-roles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-roles.js","sourceRoot":"","sources":["../../src/lib/model-roles.ts"],"names":[],"mappings":"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"}

package/dist/lib/opencode.d.ts

@@ -24,6 +24,11 @@ export type WriteResult = {
     reason?: string;
 };
 export type ManagedAgentModelMap = Record<ManagedOpenCodeAgentName, string | undefined>;
+export type OpenCodeAgentOverride = {
+    model?: string;
+    variant?: string;
+};
+export type ManagedAgentOverrideMap = Record<ManagedOpenCodeAgentName, OpenCodeAgentOverride>;
 export type InstallationInspection = {
     scope: Scope;
     opencode: {
@@ -50,6 +55,18 @@ export type InstallationInspection = {
     secretsRedaction: {
         config?: SecretsRedactionConfig;
     };
+    roles: {
+        assignments: Array<{
+            roleId: string;
+            model: string;
+            builtIn: boolean;
+        }>;
+        unresolvedReferences: Array<{
+            fieldPath: string;
+            roleRef: string;
+            roleId: string;
+        }>;
+    };
     warnings: string[];
     problems: string[];
 };
@@ -71,10 +88,13 @@ export declare function syncManagedAgentPrompts(paths: ResolvedPaths, options: {
     force: boolean;
 }): Promise<WriteResult[]>;
 export declare function readManagedAgentModels(paths: Pick<ResolvedPaths, "opencodeConfigPath">): Promise<ManagedAgentModelMap>;
+export declare function readManagedAgentOverrides(paths: Pick<ResolvedPaths, "opencodeConfigPath">): Promise<ManagedAgentOverrideMap>;
 export declare function readOpenCodeAgentModel(paths: Pick<ResolvedPaths, "opencodeConfigPath">, agentName: string): Promise<string | undefined>;
+export declare function readOpenCodeAgentOverride(paths: Pick<ResolvedPaths, "opencodeConfigPath">, agentName: string): Promise<OpenCodeAgentOverride>;
 export declare function readOpenCodeDefaultModel(paths: Pick<ResolvedPaths, "opencodeConfigPath">, key: OpenCodeDefaultModelKey): Promise<string | undefined>;
 export declare function writeOpenCodeAgentModel(paths: Pick<ResolvedPaths, "opencodeConfigPath">, agentName: string, options: {
     model?: string;
+    variant?: string;
     ensureEntry: boolean;
 }): Promise<WriteResult>;
 export declare function writeOpenCodeDefaultModel(paths: Pick<ResolvedPaths, "opencodeConfigPath">, key: OpenCodeDefaultModelKey, options: {
@@ -84,6 +104,7 @@ export declare function writeOpenCodeDefaultModel(paths: Pick<ResolvedPaths, "op
 export declare function writeOpenCodeProviderObject(paths: Pick<ResolvedPaths, "opencodeConfigPath">, providerID: string, value: JsonObject): Promise<WriteResult>;
 export declare function writeManagedAgentModel(paths: Pick<ResolvedPaths, "managedAgentsDirPath" | "opencodeConfigPath">, agentName: ManagedOpenCodeAgentName, options: {
     model?: string;
+    variant?: string;
     ensureEntry: boolean;
 }): Promise<WriteResult>;
 export { parseGuardianConfigText, renderGuardianConfig, type GuardianConfigOverrides, } from "./vvoc-config.js";