@d3ara1n/pi-model-roles 0.1.0

package/README.md

@@ -0,0 +1,100 @@
+# @d3ara1n/pi-model-roles
+
+Model role configuration library for [pi](https://github.com/earendil-works/pi) extensions.
+
+Defines named model roles (e.g. "heavy", "fast", "side") and resolves them to pi `Model` instances with API key and headers.
+
+## What it does
+
+- Reads role definitions from `~/.pi/agent/settings.json` → `modelRoles` field
+- Resolves role names to `Model<Api>` instances via pi's `ModelRegistry`
+- Exposes a `ModelRolesAPI` singleton for other extensions to consume via direct import
+- **Pure library**: no tools, no commands, no event hooks
+
+## Installation
+
+```bash
+pi extension add @d3ara1n/pi-model-roles
+```
+
+## Default Roles
+
+Works out of the box — no configuration required.
+Built-in defaults use `model: null` (use pi's current model, don't switch):
+
+| Role | model | thinking | Description |
+|------|-------|----------|-------------|
+| `default` | null | medium | Daily coding |
+| `heavy` | null | high | Architecture, deep debugging |
+| `fast` | null | off | Quick edits, simple Q&A |
+
+`model: null` means "keep using whatever model pi currently has".
+Only `thinking` level differs between roles by default.
+
+Custom roles (e.g. `side` for scout) can be added freely — any role name works:
+
+## Configuration
+
+Override specific roles in `~/.pi/agent/settings.json`:
+
+```jsonc
+{
+  "modelRoles": {
+    "roles": {
+      "heavy": {
+        "model": "anthropic/claude-opus-4"
+      },
+      "fast": {
+        "model": "google/gemini-2.5-flash",
+        "thinking": "off"
+      },
+      // Custom role for scout's side agent
+      "side": {
+        "model": "deepseek/deepseek-v4-flash",
+        "thinking": "off",
+        "hidden": true
+      }
+    },
+    "defaultRole": "default"
+  }
+}
+```
+
+User settings **merge** with built-in defaults: only override roles you want to change.
+You can also add entirely new roles.
+
+### Role fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `model` | `string \| null` | `null` | `"provider/model-id"` or `null` = use current model |
+| `thinking` | `string` | | `"off"` `"minimal"` `"low"` `"medium"` `"high"` `"xhigh"` |
+| `description` | `string` | | Human-readable description |
+| `tools` | `string` | | Comma-separated default tool list |
+| `hidden` | `boolean` | `false` | Hide from user-facing listings |
+| `systemPromptAppend` | `string` | | Extra system prompt content |
+
+## API (for extension authors)
+
+```typescript
+import { getModelRolesAPI } from "@d3ara1n/pi-model-roles";
+import type { ModelRolesAPI } from "@d3ara1n/pi-model-roles";
+
+const roles: ModelRolesAPI = getModelRolesAPI();
+
+// Resolve a role — always returns a real model or undefined
+const resolved = await roles.resolveRoleAsync("heavy");
+if (resolved.model) {
+  // Use resolved.model, resolved.apiKey, resolved.headers
+  // model=null in config is transparently resolved to pi's current model
+} else {
+  // Model not available
+}
+
+// Reverse lookup
+roles.findRoleByModel("anthropic/claude-opus-4"); // "heavy"
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@d3ara1n/pi-model-roles",
+  "version": "0.1.0",
+  "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",
+  "keywords": [
+    "pi-package",
+    "pi"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "dependencies": {},
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/d3ara1n/pi-extensions",
+    "directory": "packages/pi-model-roles"
+  },
+  "license": "MIT"
+}

package/src/api.ts

@@ -0,0 +1,153 @@
+/**
+ * ModelRolesAPI implementation.
+ *
+ * State stored on globalThis to survive module identity mismatches
+ * (extension loaded by absolute path vs import via workspace symlink).
+ * Exported functions provide type-safe access — consumers never touch globalThis.
+ */
+
+import type { ModelRolesAPI, ModelRolesConfig, RoleConfig, ResolvedRole } from "./types.ts";
+import { loadRolesConfig } from "./config.ts";
+import { resolveModelForRole, resolveModelForRoleAsync } from "./resolver.ts";
+
+const GLOBAL_KEY = "__piModelRoles";
+
+/** Mutable state. */
+interface APIState {
+	config: ModelRolesConfig | undefined;
+	currentModel: any;
+	modelRegistry: any;
+}
+
+export function initModelRolesAPI(modelRegistry: any, currentModel: any, cwd?: string): ModelRolesAPI {
+	const state: APIState = {
+		config: undefined,
+		currentModel,
+		modelRegistry,
+	};
+
+	function getConfig(): ModelRolesConfig {
+		if (!state.config) {
+			state.config = loadRolesConfig(cwd);
+		}
+		return state.config;
+	}
+
+	const api: ModelRolesAPI = {
+		getRoles(): Record<string, RoleConfig> {
+			return getConfig().roles;
+		},
+
+		getRole(name: string): RoleConfig | undefined {
+			return getConfig().roles[name];
+		},
+
+		resolveRole(name: string): ResolvedRole {
+			const roleConfig = getConfig().roles[name];
+			if (!roleConfig) {
+				return {
+					name,
+					config: { model: null },
+					model: state.currentModel,
+					apiKey: undefined,
+					headers: undefined,
+				};
+			}
+
+			const resolved = resolveModelForRole(roleConfig, state.modelRegistry, state.currentModel);
+			return { name, config: roleConfig, ...resolved };
+		},
+
+		async resolveRoleAsync(name: string): Promise<ResolvedRole> {
+			const roleConfig = getConfig().roles[name];
+			if (!roleConfig) {
+				if (state.currentModel) {
+					const auth = await state.modelRegistry.getApiKeyAndHeaders(state.currentModel);
+					return {
+						name,
+						config: { model: null },
+						model: state.currentModel,
+						apiKey: auth.ok ? auth.apiKey : undefined,
+						headers: auth.ok ? auth.headers : undefined,
+					};
+				}
+				return {
+					name,
+					config: { model: null },
+					model: undefined,
+					apiKey: undefined,
+					headers: undefined,
+				};
+			}
+
+			const resolved = await resolveModelForRoleAsync(roleConfig, state.modelRegistry, state.currentModel);
+			if (!resolved) {
+				return {
+					name,
+					config: roleConfig,
+					model: undefined,
+					apiKey: undefined,
+					headers: undefined,
+				};
+			}
+
+			return { name, config: roleConfig, ...resolved };
+		},
+
+		getDefaultRole(): string {
+			return getConfig().defaultRole ?? "default";
+		},
+
+		getVisibleRoles(): Record<string, RoleConfig> {
+			const roles = getConfig().roles;
+			const result: Record<string, RoleConfig> = {};
+			for (const [name, config] of Object.entries(roles)) {
+				if (!config.hidden) {
+					result[name] = config;
+				}
+			}
+			return result;
+		},
+
+		findRoleByModel(modelId: string): string | undefined {
+			const roles = getConfig().roles;
+			for (const [name, config] of Object.entries(roles)) {
+				if (config.model === modelId) {
+					return name;
+				}
+			}
+			return undefined;
+		},
+	};
+
+	// Store on globalThis — survives module identity mismatches
+	(globalThis as any)[GLOBAL_KEY] = api;
+	return api;
+}
+
+/**
+ * Update the tracked current model.
+ */
+export function updateCurrentModel(model: any): void {
+	const api = (globalThis as any)[GLOBAL_KEY] as ModelRolesAPI | undefined;
+	if (!api) return;
+	const state = (api as any).__state as APIState | undefined;
+	if (state) {
+		state.currentModel = model;
+	}
+}
+
+/**
+ * Get the initialized ModelRolesAPI.
+ * Throws if initModelRolesAPI() has not been called yet.
+ */
+export function getModelRolesAPI(): ModelRolesAPI {
+	const api = (globalThis as any)[GLOBAL_KEY] as ModelRolesAPI | undefined;
+	if (!api) {
+		throw new Error(
+			"ModelRolesAPI not initialized. " +
+			"Ensure @d3ara1n/pi-model-roles extension is loaded and session_start has fired.",
+		);
+	}
+	return api;
+}

package/src/config.ts

@@ -0,0 +1,90 @@
+/**
+ * Read role configuration from settings files.
+ *
+ * Reads global (~/.pi/agent/settings.json) and project-level (.pi/settings.json)
+ * settings, merges them with project overriding global.
+ * Built-in defaults form the base.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { ModelRolesConfig, RoleConfig } from "./types.ts";
+import { BUILTIN_DEFAULT_ROLES } from "./defaults.ts";
+
+const DEFAULT_ROLE_NAME = "default";
+
+/** Get the pi agent directory path. */
+function getAgentDir(): string {
+	const envDir = process.env.PI_AGENT_DIR;
+	if (envDir) return envDir;
+	return path.join(os.homedir(), ".pi", "agent");
+}
+
+/** Read and parse a settings.json file. Returns parsed object or empty. */
+function readSettingsFile(filePath: string): any {
+	try {
+		if (!fs.existsSync(filePath)) return {};
+		const content = fs.readFileSync(filePath, "utf-8");
+		// Strip JSONC comments
+		const stripped = content.replace(/\/\/.*$/gm, "").replace(/\/\*[\s\S]*?\*\//g, "");
+		return JSON.parse(stripped);
+	} catch {
+		return {};
+	}
+}
+
+/** Deep merge source into target (source wins on conflict). Only handles plain objects. */
+function merge(target: any, source: any): any {
+	if (!source || typeof source !== "object") return target;
+	if (!target || typeof target !== "object") return source;
+	const result = { ...target };
+	for (const key of Object.keys(source)) {
+		if (source[key] && typeof source[key] === "object" && !Array.isArray(source[key])) {
+			result[key] = merge(result[key], source[key]);
+		} else {
+			result[key] = source[key];
+		}
+	}
+	return result;
+}
+
+/**
+ * Load modelRoles config, merged from global + project settings.
+ * @param cwd - Project working directory (for .pi/settings.json lookup)
+ */
+export function loadRolesConfig(cwd?: string): ModelRolesConfig {
+	// Read global settings
+	const globalSettings = readSettingsFile(path.join(getAgentDir(), "settings.json"));
+
+	// Read project settings
+	const projectSettings = cwd
+		? readSettingsFile(path.join(cwd, ".pi", "settings.json"))
+		: {};
+
+	// Merge: project overrides global
+	const settings = merge(globalSettings, projectSettings);
+
+	// Start from built-in defaults
+	const mergedRoles: Record<string, RoleConfig> = {};
+	for (const [name, config] of Object.entries(BUILTIN_DEFAULT_ROLES)) {
+		mergedRoles[name] = { ...config };
+	}
+
+	// Merge user config over defaults
+	const userConfig = settings?.modelRoles;
+	if (userConfig?.roles && typeof userConfig.roles === "object") {
+		for (const [name, config] of Object.entries(userConfig.roles as Record<string, Partial<RoleConfig>>)) {
+			if (mergedRoles[name]) {
+				mergedRoles[name] = { ...mergedRoles[name], ...config };
+			} else {
+				mergedRoles[name] = config as RoleConfig;
+			}
+		}
+	}
+
+	return {
+		roles: mergedRoles,
+		defaultRole: userConfig?.defaultRole ?? DEFAULT_ROLE_NAME,
+	};
+}

package/src/defaults.ts

@@ -0,0 +1,29 @@
+/**
+ * Built-in default role definitions.
+ *
+ * Only universal roles are built-in. Scout/subagent-specific roles
+ * (like "side") are left for users to define — modelRoles accepts
+ * any custom role name.
+ *
+ * model=null means "use pi's current model, don't switch".
+ */
+
+import type { RoleConfig } from "./types.ts";
+
+export const BUILTIN_DEFAULT_ROLES: Record<string, RoleConfig> = {
+  default: {
+    model: null,
+    description: "日常编码，速度和质量平衡",
+    thinking: "medium",
+  },
+  heavy: {
+    model: null,
+    description: "架构设计、深度调试、复杂迁移",
+    thinking: "high",
+  },
+  fast: {
+    model: null,
+    description: "快速修改、简单问答",
+    thinking: "off",
+  },
+};

package/src/index.ts

@@ -0,0 +1,48 @@
+/**
+ * pi-model-roles — Extension entry point.
+ *
+ * Dependency library: provides ModelRolesAPI singleton.
+ * Registers /roles command for inspection.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { initModelRolesAPI, getModelRolesAPI, updateCurrentModel } from "./api.ts";
+
+export { getModelRolesAPI } from "./api.ts";
+export type { ModelRolesAPI, RoleConfig, ResolvedRole, ModelRolesConfig, ThinkingLevel } from "./types.ts";
+
+export default function registerModelRolesExtension(pi: ExtensionAPI): void {
+	pi.on("session_start", async (_event, ctx) => {
+		initModelRolesAPI(ctx.modelRegistry, ctx.model, ctx.cwd);
+	});
+
+	pi.on("model_select", async (event) => {
+		updateCurrentModel(event.model);
+	});
+
+	pi.registerCommand("roles", {
+		description: "Show model role definitions and resolved models",
+		handler: async (_args, ctx) => {
+			const api = getModelRolesAPI();
+			const roles = api.getRoles();
+			const lines: string[] = ["Model Roles:", ""];
+
+			for (const [name, config] of Object.entries(roles)) {
+				const resolved = api.resolveRole(name);
+				const hidden = config.hidden ? " (hidden)" : "";
+				const modelLabel = resolved.model
+					? `${resolved.model.provider}/${resolved.model.id}`
+					: config.model === null
+						? "→ current model"
+						: `→ NOT FOUND (${config.model})`;
+				const thinking = config.thinking ? ` thinking:${config.thinking}` : "";
+				lines.push(`  ${name}: ${modelLabel}${thinking}${hidden}`);
+			}
+
+			lines.push("");
+			lines.push(`Default role: ${api.getDefaultRole()}`);
+
+			ctx.ui.notify(lines.join("\n"), "info");
+		},
+	});
+}

package/src/resolver.ts

@@ -0,0 +1,78 @@
+/**
+ * Resolve role names to Model instances using pi's ModelRegistry.
+ *
+ * model=null in RoleConfig is transparently resolved to the current model.
+ * Callers never see null — they get a real model or undefined.
+ */
+
+import type { RoleConfig, ResolvedRole } from "./types.ts";
+
+/** Minimal interface from ModelRegistry. */
+interface ModelRegistryLike {
+	getAvailable(): any[];
+	getApiKeyAndHeaders(model: any): Promise<{ ok: boolean; apiKey?: string; headers?: Record<string, string> }>;
+}
+
+interface ModelLike {
+	provider: string;
+	id: string;
+}
+
+function parseModelIdentifier(modelRef: string): { provider: string | undefined; modelId: string } {
+	const parts = modelRef.split("/");
+	if (parts.length > 1) {
+		return { provider: parts[0], modelId: parts.slice(1).join("/") };
+	}
+	return { provider: undefined, modelId: parts[0] };
+}
+
+function findModel(modelRef: string, available: ModelLike[]): ModelLike | undefined {
+	const { provider, modelId } = parseModelIdentifier(modelRef);
+	return available.find((m) => {
+		if (provider) return m.provider === provider && m.id === modelId;
+		return m.id === modelId;
+	});
+}
+
+/**
+ * Sync resolve. model=null → uses currentModel if provided, else undefined.
+ */
+export function resolveModelForRole(
+	roleConfig: RoleConfig,
+	modelRegistry: ModelRegistryLike,
+	currentModel: any | undefined,
+): Pick<ResolvedRole, "model" | "apiKey" | "headers"> {
+	// model=null: fill with pi's current model
+	if (!roleConfig.model) {
+		return { model: currentModel, apiKey: undefined, headers: undefined };
+	}
+
+	const match = findModel(roleConfig.model, modelRegistry.getAvailable());
+	return { model: match ?? undefined, apiKey: undefined, headers: undefined };
+}
+
+/**
+ * Async resolve with auth. model=null → resolves currentModel's auth too.
+ */
+export async function resolveModelForRoleAsync(
+	roleConfig: RoleConfig,
+	modelRegistry: ModelRegistryLike,
+	currentModel: any | undefined,
+): Promise<Pick<ResolvedRole, "model" | "apiKey" | "headers"> | undefined> {
+	// model=null: fill with pi's current model + its auth
+	if (!roleConfig.model) {
+		if (!currentModel) return undefined;
+		const auth = await modelRegistry.getApiKeyAndHeaders(currentModel);
+		if (!auth.ok) return undefined;
+		return { model: currentModel, apiKey: auth.apiKey, headers: auth.headers };
+	}
+
+	const available = modelRegistry.getAvailable();
+	const match = findModel(roleConfig.model, available);
+	if (!match) return undefined;
+
+	const auth = await modelRegistry.getApiKeyAndHeaders(match);
+	if (!auth.ok) return undefined;
+
+	return { model: match, apiKey: auth.apiKey, headers: auth.headers };
+}

package/src/types.ts

@@ -0,0 +1,77 @@
+/**
+ * Shared types for pi-model-roles.
+ */
+
+/** Thinking level configuration for a role. */
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+
+/** Configuration for a single model role. */
+export interface RoleConfig {
+  /**
+   * Model identifier, format: "provider/model-id".
+   * null = use pi's current model (resolved internally, never exposed to consumers).
+   */
+  model: string | null;
+  /** Thinking level for this role */
+  thinking?: ThinkingLevel;
+  /** Human-readable description of when to use this role */
+  description?: string;
+  /** Comma-separated list of tools available to this role */
+  tools?: string;
+  /** If true, hide this role from user-facing listings */
+  hidden?: boolean;
+  /** Additional system prompt content appended when this role is active */
+  systemPromptAppend?: string;
+}
+
+/** Top-level modelRoles configuration stored in pi settings. */
+export interface ModelRolesConfig {
+  /** Map of role name → role configuration */
+  roles: Record<string, RoleConfig>;
+  /** Fallback role name when a requested role doesn't exist */
+  defaultRole?: string;
+}
+
+/** A fully resolved role — consumers never see null. */
+export interface ResolvedRole {
+  /** The role name */
+  name: string;
+  /** The original role configuration */
+  config: RoleConfig;
+  /** Resolved Model instance (always a real model, or undefined if unavailable) */
+  model: any | undefined; // Model<Api>
+  /** API key for this model */
+  apiKey: string | undefined;
+  /** Custom headers for API requests */
+  headers: Record<string, string> | undefined;
+}
+
+/** Public API exposed via getModelRolesAPI(). */
+export interface ModelRolesAPI {
+  /** Read all role configurations. */
+  getRoles(): Record<string, RoleConfig>;
+  /** Get a single role configuration by name. */
+  getRole(name: string): RoleConfig | undefined;
+  /**
+   * Resolve a role name to a model instance (sync, no auth).
+   * model=null is transparently resolved to pi's current model.
+   * Returns model=undefined only if the model is truly unavailable.
+   */
+  resolveRole(name: string): ResolvedRole;
+  /**
+   * Resolve a role name to a model instance with auth info (async).
+   * model=null is transparently resolved to pi's current model.
+   * Returns model=undefined only if the model is truly unavailable.
+   */
+  resolveRoleAsync(name: string): Promise<ResolvedRole>;
+  /** Get the default role name. */
+  getDefaultRole(): string;
+  /** 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.
+   */
+  findRoleByModel(modelId: string): string | undefined;
+}