@d3ara1n/pi-model-roles 0.3.1 → 0.5.0

package/README.md

@@ -11,6 +11,10 @@ Defines named model roles (e.g. "heavy", "fast", "utility") and resolves them to
 - Exposes a `ModelRolesAPI` singleton for other extensions to consume via direct import
 - **Pure library**: no tools, no commands, no event hooks
 
+## Dependencies
+
+None.
+
 ## Installation
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d3ara1n/pi-model-roles",
-  "version": "0.3.1",
+  "version": "0.5.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

@@ -6,6 +6,7 @@
  * Exported functions provide type-safe access — consumers never touch globalThis.
  */
 
+import { complete as piAiComplete, streamSimple as piAiStreamSimple } from "@earendil-works/pi-ai";
 import type { ModelRolesAPI, ModelRolesConfig, RoleConfig, ResolvedRole } from "./types.ts";
 import { loadRolesConfig } from "./config.ts";
 import { resolveModelForRole, resolveModelForRoleAsync } from "./resolver.ts";
@@ -14,142 +15,198 @@ const GLOBAL_KEY = "__piModelRoles";
 
 /** Mutable state. */
 interface APIState {
-	config: ModelRolesConfig | undefined;
-	currentModel: any;
-	modelRegistry: any;
+  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;
-		},
-
-		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
-	(globalThis as any)[GLOBAL_KEY] = api;
-	return api;
+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;
+    },
+
+    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;
+    },
+
+    listModels(): string[] {
+      return state.modelRegistry
+        .getAvailable()
+        .map((m: { provider: string; id: string }) => `${m.provider}/${m.id}`);
+    },
+
+    async complete(roleName: string, context: any, options?: any): Promise<any> {
+      // Resolve model: explicit override wins, else the role's declared model
+      // (model=null transparently uses pi's current model).
+      const roleConfig = getConfig().roles[roleName] ?? { model: null };
+      const model =
+        options?.model ??
+        resolveModelForRole(roleConfig, state.modelRegistry, state.currentModel).model;
+      if (!model) {
+        throw new Error(`complete: role "${roleName}" has no available model`);
+      }
+      // Resolve auth for the model actually used (refreshes OAuth tokens).
+      const auth = await state.modelRegistry.getApiKeyAndHeaders(model);
+      if (!auth.ok) {
+        throw new Error(`complete: auth failed for ${model.provider}/${model.id}: ${auth.error}`);
+      }
+      // Forward everything except `model` to pi-ai's complete().
+      const { model: _omitModel, ...streamOptions } = options ?? {};
+      if (auth.apiKey) streamOptions.apiKey = auth.apiKey;
+      if (auth.headers) streamOptions.headers = auth.headers;
+      return piAiComplete(model, context, streamOptions);
+    },
+
+    async streamWithRole(roleName: string, context: any, options?: any): Promise<any> {
+      const roleConfig = getConfig().roles[roleName] ?? { model: null };
+      const model =
+        options?.model ??
+        resolveModelForRole(roleConfig, state.modelRegistry, state.currentModel).model;
+      if (!model) {
+        throw new Error(`streamWithRole: role "${roleName}" has no available model`);
+      }
+      const auth = await state.modelRegistry.getApiKeyAndHeaders(model);
+      if (!auth.ok) {
+        throw new Error(
+          `streamWithRole: auth failed for ${model.provider}/${model.id}: ${auth.error}`,
+        );
+      }
+      const { model: _omitModel, ...streamOptions } = options ?? {};
+      if (auth.apiKey) streamOptions.apiKey = auth.apiKey;
+      if (auth.headers) streamOptions.headers = auth.headers;
+      return piAiStreamSimple(model, context, streamOptions);
+    },
+  };
+
+  // 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;
-	}
+  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;
+  }
 }
 
 /**
@@ -157,12 +214,12 @@ export function updateCurrentModel(model: any): void {
  * 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;
+  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

@@ -16,35 +16,35 @@ 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");
+  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");
-		return JSON.parse(content);
-	} catch {
-		return {};
-	}
+  try {
+    if (!fs.existsSync(filePath)) return {};
+    const content = fs.readFileSync(filePath, "utf-8");
+    return JSON.parse(content);
+  } 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;
+  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;
 }
 
 /**
@@ -52,37 +52,37 @@ function merge(target: any, source: any): any {
  * @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 global settings
+  const globalSettings = readSettingsFile(path.join(getAgentDir(), "settings.json"));
 
-	// Read project settings
-	const projectSettings = cwd
-		? readSettingsFile(path.join(cwd, ".pi", "settings.json"))
-		: {};
+  // Read project settings
+  const projectSettings = cwd ? readSettingsFile(path.join(cwd, ".pi", "settings.json")) : {};
 
-	// Merge: project overrides global
-	const settings = merge(globalSettings, projectSettings);
+  // 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 };
-	}
+  // 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;
-			}
-		}
-	}
+  // 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,
-	};
+  return {
+    roles: mergedRoles,
+    defaultRole: userConfig?.defaultRole ?? DEFAULT_ROLE_NAME,
+  };
 }

package/src/defaults.ts

@@ -13,22 +13,26 @@ import type { RoleConfig } from "./types.ts";
 export const BUILTIN_DEFAULT_ROLES: Record<string, RoleConfig> = {
   default: {
     model: null,
-    description: "General development tasks: writing new features, modifying existing code, code review, adding tests, routine debugging, file-level changes",
+    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: "Tasks requiring deep thinking: cross-file refactoring, architecture design, complex bug debugging, performance optimization, security analysis, database schema changes, multi-module migrations",
+    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: "Simple deterministic tasks: one-line edits, formatting tweaks, simple Q&A, doc lookups, git operations, confirmation replies",
+    description:
+      "Simple deterministic tasks: one-line edits, formatting tweaks, simple Q&A, doc lookups, git operations, confirmation replies",
     thinking: "low",
   },
   utility: {
     model: null,
-    description: "Lightweight utilities: model routing, commit generation, title/summary, etc. (hidden)",
+    description:
+      "Lightweight utilities: model routing, commit generation, title/summary, etc. (hidden)",
     thinking: "off",
     hidden: true,
   },

package/src/index.ts

@@ -6,43 +6,75 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
 import { initModelRolesAPI, getModelRolesAPI, updateCurrentModel } from "./api.ts";
 
 export { getModelRolesAPI } from "./api.ts";
-export type { ModelRolesAPI, RoleConfig, ResolvedRole, ModelRolesConfig, ThinkingLevel } from "./types.ts";
+export type {
+  ModelRolesAPI,
+  RoleConfig,
+  ResolvedRole,
+  ModelRolesConfig,
+  ThinkingLevel,
+} from "./types.ts";
+// Re-export pi-ai types so consumers depend on model-roles alone, not pi-ai.
+export type {
+  Api,
+  AssistantMessage,
+  AssistantMessageEventStream,
+  Context,
+  Model,
+  ProviderStreamOptions,
+  SimpleStreamOptions,
+} from "@earendil-works/pi-ai";
 
 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");
-		},
-	});
+  pi.on("session_start", async (_event, ctx) => {
+    initModelRolesAPI(ctx.modelRegistry, ctx.model, ctx.cwd);
+  });
+
+  pi.on("model_select", async (event) => {
+    updateCurrentModel(event.model);
+  });
+
+  pi.registerTool({
+    name: "list_models",
+    label: "List available models",
+    description: "List all available models from pi's model registry. Returns provider/model-id strings (e.g. 'anthropic/claude-sonnet-4'). Useful for confirming model IDs before referencing a model by name.",
+    parameters: Type.Object({}),
+    async execute() {
+      const api = getModelRolesAPI();
+      const models = api.listModels();
+      return {
+        content: [{ type: "text", text: models.join("\n") }],
+        details: undefined as any,
+      };
+    },
+  });
+
+  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

@@ -9,70 +9,72 @@ 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> }>;
+  getAvailable(): any[];
+  getApiKeyAndHeaders(
+    model: any,
+  ): Promise<{ ok: boolean; apiKey?: string; headers?: Record<string, string> }>;
 }
 
 interface ModelLike {
-	provider: string;
-	id: string;
+  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] };
+  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;
-	});
+  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,
+  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 };
-	}
+  // 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 };
+  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,
+  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 };
-	}
+  // 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 available = modelRegistry.getAvailable();
+  const match = findModel(roleConfig.model, available);
+  if (!match) return undefined;
 
-	const auth = await modelRegistry.getApiKeyAndHeaders(match);
-	if (!auth.ok) return undefined;
+  const auth = await modelRegistry.getApiKeyAndHeaders(match);
+  if (!auth.ok) return undefined;
 
-	return { model: match, apiKey: auth.apiKey, headers: auth.headers };
+  return { model: match, apiKey: auth.apiKey, headers: auth.headers };
 }

package/src/types.ts

@@ -2,6 +2,16 @@
  * Shared types for pi-model-roles.
  */
 
+import type {
+  Api,
+  AssistantMessage,
+  AssistantMessageEventStream,
+  Context,
+  Model,
+  ProviderStreamOptions,
+  SimpleStreamOptions,
+} from "@earendil-works/pi-ai";
+
 /** Thinking level configuration for a role. */
 export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
 
@@ -95,4 +105,48 @@ export interface ModelRolesAPI {
    * Returns undefined only if no role matches by any rule.
    */
   getCurrentRole(modelId: string): string | undefined;
+  /** List all available models from pi's model registry. Returns provider/id strings (e.g. "anthropic/claude-sonnet-4"). */
+  listModels(): string[];
+
+  /**
+   * Call pi-ai's complete() with auth resolved internally from the role's model.
+   *
+   * Auth (including OAuth token refresh) is resolved for the model actually
+   * used, so callers never handle API keys or headers. The underlying call is
+   * pi-ai's complete() verbatim — no fallback, no retry, no error swallowing;
+   * throws if the role has no available model or auth resolution fails.
+   *
+   * @param roleName - Role whose model + auth to use
+   * @param context - Conversation context (systemPrompt + messages)
+   * @param options - Stream options forwarded to pi-ai's complete(). Pass
+   *   `model` to override the role's model (auth is then resolved for that
+   *   model); all other fields pass through unchanged.
+   */
+  complete<TApi extends Api = Api>(
+    roleName: string,
+    context: Context,
+    options?: ProviderStreamOptions & { model?: Model<TApi> },
+  ): Promise<AssistantMessage>;
+
+  /**
+   * Call pi-ai's streamSimple() with auth resolved internally from the role's model.
+   *
+   * Streaming counterpart to {@link complete}. Same auth resolution (including
+   * OAuth token refresh) and same error semantics (throws on no model / auth
+   * failure). Returns the pi-ai event stream verbatim — iterate it for events,
+   * call `.result()` for the final AssistantMessage.
+   *
+   * Note: unlike pi-ai's synchronous `streamSimple`, this is async because auth
+   * resolution (OAuth token refresh) must complete before the stream starts.
+   *
+   * @param roleName - Role whose model + auth to use
+   * @param context - Conversation context (systemPrompt + messages)
+   * @param options - Stream options forwarded to pi-ai's streamSimple(). Pass
+   *   `model` to override the role's model; all other fields pass through.
+   */
+  streamWithRole<TApi extends Api = Api>(
+    roleName: string,
+    context: Context,
+    options?: SimpleStreamOptions & { model?: Model<TApi> },
+  ): Promise<AssistantMessageEventStream>;
 }