@d3ara1n/pi-model-roles 0.2.0 → 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,7 @@
 {
   "name": "@d3ara1n/pi-model-roles",
-  "version": "0.2.0",
+  "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",
   "types": "src/types.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/defaults.ts

@@ -13,22 +13,22 @@ import type { RoleConfig } from "./types.ts";
 export const BUILTIN_DEFAULT_ROLES: Record<string, RoleConfig> = {
   default: {
     model: null,
-    description: "常规开发任务：编写新功能、修改现有代码、代码审查、添加测试、一般性调试、文件级别的修改",
+    description: "General development tasks: writing new features, modifying existing code, code review, adding tests, routine debugging, file-level changes",
     thinking: "medium",
   },
   heavy: {
     model: null,
-    description: "需要深度思考的任务：跨文件重构、架构设计、复杂 bug 调试、性能优化、安全分析、数据库 schema 变更、涉及多个模块的迁移",
+    description: "Tasks requiring deep thinking: cross-file refactoring, architecture design, complex bug debugging, performance optimization, security analysis, database schema changes, multi-module migrations",
     thinking: "high",
   },
   fast: {
     model: null,
-    description: "简单确定性的任务：一行修改、格式调整、简单问答、文档查阅、git 操作、确认类回复",
+    description: "Simple deterministic tasks: one-line edits, formatting tweaks, simple Q&A, doc lookups, git operations, confirmation replies",
     thinking: "low",
   },
   utility: {
     model: null,
-    description: "轻量辅助：模型路由、commit 生成、标题摘要等（hidden）",
+    description: "Lightweight utilities: model routing, commit generation, title/summary, etc. (hidden)",
     thinking: "off",
     hidden: true,
   },

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;
 }