@d3ara1n/pi-model-roles 0.2.1 → 0.3.0

package/README.md

@@ -100,6 +100,11 @@ if (resolved.model) {
 
 // Reverse lookup
 roles.findRoleByModel("anthropic/claude-opus-4"); // "heavy"
+
+// "Which role is the currently-active model?" — recognizes the default role
+// even when all roles are model=null (the common case), so callers (e.g.
+// pi-scout's router) have a real baseline instead of "unknown".
+roles.getCurrentRole("anthropic/claude-sonnet-4");
 ```
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d3ara1n/pi-model-roles",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "type": "module",
   "description": "Model role configuration library for pi extensions — defines named model roles and resolves them to Model instances",
   "main": "src/index.ts",

package/src/api.ts

@@ -118,6 +118,21 @@ export function initModelRolesAPI(modelRegistry: any, currentModel: any, cwd?: s
 			}
 			return undefined;
 		},
+
+		getCurrentRole(modelId: string): string | undefined {
+			const roles = getConfig().roles;
+			// 1. Exact match wins: a role explicitly bound to this model.
+			const exact = Object.entries(roles).find(([, c]) => c.model === modelId)?.[0];
+			if (exact) return exact;
+			// 2. Default role — when model=null it transparently uses the current
+			//    model, so it is the meaningful base in the all-null config.
+			const defaultName = getConfig().defaultRole ?? "default";
+			const defaultConfig = roles[defaultName];
+			if (defaultConfig && !defaultConfig.model) return defaultName;
+			// 3. First model=null role (reached only when default is bound elsewhere).
+			const nullRole = Object.entries(roles).find(([, c]) => !c.model)?.[0];
+			return nullRole;
+		},
 	};
 
 	// Store on globalThis — survives module identity mismatches

package/src/types.ts

@@ -69,9 +69,30 @@ export interface ModelRolesAPI {
   /** Get all non-hidden roles (for displaying to users). */
   getVisibleRoles(): Record<string, RoleConfig>;
   /**
-   * Given a model identifier (e.g. "anthropic/claude-sonnet-4"),
-   * find the first role name that uses that model.
-   * Skips roles with model=null.
+   * Given a model identifier (e.g. "anthropic/claude-sonnet-4"), find the first
+   * role name that is explicitly bound to that model. Skips roles with
+   * model=null (they have no declared model to match).
+   *
+   * This is a pure declared-binding lookup — it does NOT infer "the current
+   * role". For that, use {@link getCurrentRole}.
+   *
+   * Returns undefined if no role declares this model.
    */
   findRoleByModel(modelId: string): string | undefined;
+
+  /**
+   * Identify which role the currently-active model belongs to. Resolution order:
+   *   1. Exact match — a role explicitly bound to `modelId`
+   *      ({@link findRoleByModel}).
+   *   2. The configured default role — if it is model=null, the current model
+   *      is transparently "the default role's model", so default is the
+   *      meaningful base. This covers the common config where ALL roles are
+   *      model=null (use current model): without this step, whichever null
+   *      role iterates first would win — often a hidden utility role.
+   *   3. The first model=null role found (it too transparently uses the current
+   *      model); only reached when the default role is explicitly bound to a
+   *      different model.
+   * Returns undefined only if no role matches by any rule.
+   */
+  getCurrentRole(modelId: string): string | undefined;
 }