@0xkahi/pi-qol 0.0.1

package/README.md

@@ -0,0 +1,135 @@
+# pi-qol
+
+> Quality-of-life extensions for [pi](https://github.com/earendil-works/pi).
+
+A small collection of opt-in extensions that smooth out everyday pi usage. Today
+it ships **`auto_session_name`** — automatic, opencode-style session titling — with
+more QoL features planned.
+
+## Features
+
+### `auto_session_name`
+
+Automatically generates a short, human-readable title for a brand-new session from
+its first user message, using a cheap model call that runs in the background and
+never blocks your turn.
+
+- **Non-blocking** — titles are generated asynchronously while the agent responds.
+- **Fires once, early** — only on the very first real user turn of a session.
+- **Smart guards** — skips sessions that already have a name, forked/child
+  sessions, and empty prompts.
+- **Model-flexible** — use a configured cheap model, or fall back to the active
+  session model automatically.
+- **Safe output** — strips `<think>` blocks, unwraps quotes, and truncates titles
+  to 100 characters.
+
+## Installation
+
+Install the package from npm:
+
+```bash
+pi install npm:@0xkahi/pi-qol
+```
+
+Then register it in your pi configuration so pi loads `./src/index.ts` as an
+extension (see the `pi.extensions` field in `package.json`).
+
+## Configuration
+
+`pi-qol` reads a JSON config file named `config.json` from two locations and merges
+them (project overrides global):
+
+| Scope   | Path                                                       |
+| ------- | ---------------------------------------------------------- |
+| Global  | `<agent-dir>/extensions/pi-qol/config.json`                |
+| Project | `<cwd>/.pi/extensions/pi-qol/config.json` (trusted projects only) |
+
+> Project config is only loaded when the project is trusted.
+
+### Example
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/0xKahi/pi-qol/main/assets/config.schema.json",
+  "auto_session_name": {
+    "enabled": true,
+    "model": {
+      "provider": "anthropic",
+      "modelId": "claude-3-5-haiku-latest",
+      "reasoning": "minimal"
+    }
+  }
+}
+```
+
+### Options
+
+#### `auto_session_name`
+
+| Key       | Type      | Default | Description                                                        |
+| --------- | --------- | ------- | ------------------------------------------------------------------ |
+| `enabled` | `boolean` | `false` | Turn the auto session naming feature on.                           |
+| `model`   | `object`  | —       | Optional model used to generate titles. Falls back to the session model if omitted. |
+
+
+#### `model`
+
+| Key         | Type     | Description                                                            |
+| ----------- | -------- | --------------------------------------------------------------------- |
+| `provider`  | `string` | Model provider id (e.g. `anthropic`, `openai`).                       |
+| `modelId`   | `string` | Model identifier as registered in pi's model registry.               |
+| `reasoning` | `enum`   | One of `off`, `minimal`, `low`, `medium`, `high`, `xhigh`.            |
+
+
+When `model` is set but cannot be found or authenticated, `pi-qol` automatically
+falls back to the active session model and surfaces a warning notification.
+
+## How it works
+
+On `before_agent_start`, the `auto_session_name` extension checks a series of
+guards before doing any work. It only proceeds when **all** of the following hold:
+
+1. The feature is enabled in config.
+2. The session does not already have a name.
+3. The session is not a fork/child session.
+4. It is the user's first turn.
+5. The user prompt is non-empty.
+
+If those pass, it resolves a model, generates a title via a dedicated
+title-generation prompt, cleans the result, and persists it with
+`pi.setSessionName()`. The work runs in a cancellable background task that is
+aborted on session shutdown.
+
+## Development
+
+This project uses [Bun](https://bun.sh) and [Biome](https://biomejs.dev).
+
+```bash
+bun install        # install dependencies
+bun run check      # biome fix + type-check
+bun test           # run tests
+bun run buildSchema # regenerate assets/config.schema.json from the zod schemas
+```
+
+### Project structure
+
+```
+src/
+  index.ts                       # extension entry — lifecycle wiring only
+  config-loader.ts               # loads + merges global/project config
+  constants.ts                   # EXTENSION_ID
+  schemas/                       # zod config schemas (full + partial)
+  utils/                         # path + model-resolution helpers
+  extensions/
+    auto-session-name/           # the auto_session_name feature
+scripts/                         # JSON schema generation
+assets/config.schema.json        # generated config schema
+```
+
+## License
+
+See repository for license details.
+
+## Author
+
+[0xKahi](https://github.com/0xKahi)

package/assets/config.schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/0xKahi/pi-qol/main/assets/config.schema.json",
+  "title": "Pi Btw Extension Configuration",
+  "description": "Configuration schema for pi-qol extension",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "auto_session_name": {
+      "default": {
+        "enabled": false
+      },
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "default": false,
+          "type": "boolean"
+        },
+        "model": {
+          "type": "object",
+          "properties": {
+            "provider": {
+              "type": "string"
+            },
+            "modelId": {
+              "type": "string"
+            },
+            "reasoning": {
+              "type": "string",
+              "enum": [
+                "off",
+                "minimal",
+                "low",
+                "medium",
+                "high",
+                "xhigh"
+              ]
+            }
+          },
+          "required": [
+            "provider",
+            "modelId",
+            "reasoning"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "enabled"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "required": [
+    "auto_session_name"
+  ],
+  "additionalProperties": false
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@0xkahi/pi-qol",
+  "version": "0.0.1",
+  "description": "quality of life pi extensions",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension"
+  ],
+  "author": "0xKahi",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "assets/config.schema.json",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/0xKahi/pi-qol.git"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "biome": "biome check ./src",
+    "lint": "bun biome",
+    "lint:fix": "bun biome --write",
+    "type-check": "tsc --noEmit",
+    "test": "bun test",
+    "check": "bun run lint:fix && bun run type-check",
+    "release": "changeset publish",
+    "version": "changeset version",
+    "changeset": "changeset",
+    "buildSchema": "bun run scripts/build-schema.ts"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.79.4",
+    "@earendil-works/pi-coding-agent": "^0.79.4",
+    "@earendil-works/pi-tui": "^0.79.4",
+    "@biomejs/biome": "^2.4.15",
+    "@changesets/cli": "^2.31.0",
+    "@types/node": "^24.0.0",
+    "@types/bun": "latest",
+    "bun-types": "latest",
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  }
+}

package/src/config-loader.ts

@@ -0,0 +1,80 @@
+import { readFileSync } from 'node:fs';
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { z } from 'zod';
+import { type Config, ConfigSchema, type PartialConfig, PartialConfigSchema } from './schemas/config.schema';
+import { PathUtil } from './utils/path.util';
+
+export class ConfigLoader {
+  private config: Config = this.defaultConfig;
+
+  get defaultConfig(): Config {
+    return ConfigSchema.parse({});
+  }
+
+  getConfig(): Config {
+    return this.config;
+  }
+
+  isEnabled(key: keyof Config): boolean {
+    const section = this.config[key];
+    return typeof section === 'object' && section !== null && 'enabled' in section ? Boolean((section as { enabled?: boolean }).enabled) : false;
+  }
+
+  getAutoSessionName(): Config['auto_session_name'] {
+    return this.config.auto_session_name;
+  }
+
+  initializeConfig(ctx: ExtensionContext): { success: boolean; error?: string } {
+    let merged: Config = this.defaultConfig;
+
+    const globalRes = PathUtil.findExtensionConfig({ type: 'global' });
+    if (globalRes.exists) {
+      const loaded = this.loadConfig(globalRes.path);
+      if (!loaded.success) return { success: false, error: `at path => ${globalRes.path}\n${loaded.error}` };
+      merged = this.mergeConfig(merged, loaded.data);
+    }
+
+    if (ctx.isProjectTrusted()) {
+      const projectRes = PathUtil.findExtensionConfig({ type: 'project', cwd: ctx.cwd });
+      if (projectRes.exists) {
+        const loaded = this.loadConfig(projectRes.path);
+        if (!loaded.success) return { success: false, error: `at path => ${projectRes.path}\n${loaded.error}` };
+        merged = this.mergeConfig(merged, loaded.data);
+      }
+    }
+
+    const parsed = ConfigSchema.safeParse(merged);
+    if (!parsed.success) return { success: false, error: z.prettifyError(parsed.error) };
+
+    this.config = parsed.data;
+    return { success: true };
+  }
+
+  private mergeConfig(base: Config, partial: PartialConfig): Config {
+    const next = { ...base } as Record<string, unknown>;
+
+    for (const [key, value] of Object.entries(partial)) {
+      if (key === '$schema' || value === undefined) continue;
+
+      const baseValue = next[key];
+      next[key] = this.isPlainObject(baseValue) && this.isPlainObject(value) ? { ...baseValue, ...value } : value;
+    }
+
+    return ConfigSchema.parse(next);
+  }
+
+  private isPlainObject(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+  }
+
+  private loadConfig(path: string): { success: true; data: PartialConfig } | { success: false; error: string } {
+    try {
+      const raw = JSON.parse(readFileSync(path, 'utf8'));
+      const parsed = PartialConfigSchema.safeParse(raw);
+      if (!parsed.success) return { success: false, error: z.prettifyError(parsed.error) };
+      return { success: true, data: parsed.data };
+    } catch (err) {
+      return { success: false, error: err instanceof Error ? err.message : String(err) };
+    }
+  }
+}

package/src/constants.ts

@@ -0,0 +1 @@
+export const EXTENSION_ID = 'pi-qol';

package/src/extensions/auto-session-name/constants.ts

@@ -0,0 +1,3 @@
+export const MAX_TITLE_LENGTH = 100;
+export const TITLE_MAX_TOKENS = 1024;
+export const MAX_RETRIES = 2;

package/src/extensions/auto-session-name/guards.ts

@@ -0,0 +1,22 @@
+import type { ExtensionAPI, SessionEntry, SessionHeader } from '@earendil-works/pi-coding-agent';
+
+type SessionManagerForGuards = {
+  getBranch(): SessionEntry[];
+  getHeader(): SessionHeader | null;
+};
+
+export class AutoSessionNameGuard {
+  static isSessionNameSet(pi: Pick<ExtensionAPI, 'getSessionName'>): boolean {
+    return pi.getSessionName() !== undefined;
+  }
+
+  static isChildSession(sessionOpts: { startReason?: string; manager: Pick<SessionManagerForGuards, 'getHeader'> }): boolean {
+    return sessionOpts.startReason === 'fork' || Boolean(sessionOpts.manager.getHeader()?.parentSession);
+  }
+
+  static isUsersFirstTurn(sessionManager: Pick<SessionManagerForGuards, 'getBranch'>): boolean {
+    // Pi emits before_agent_start before appending the current user message, so a fresh opening turn has zero prior user messages.
+    const userMsgs = sessionManager.getBranch().filter(entry => entry.type === 'message' && entry.message.role === 'user');
+    return userMsgs.length === 0;
+  }
+}

package/src/extensions/auto-session-name/index.ts

@@ -0,0 +1,74 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import type { ConfigLoader } from '../../config-loader';
+import { ModelResolver } from '../../utils/model-resolver.util';
+import { AutoSessionNameGuard } from './guards';
+import { AutoSessionNameTitleGenerator } from './title-generator';
+
+export function registerAutoSessionName(pi: ExtensionAPI, deps: { config: ConfigLoader }) {
+  let lastSessionStartReason: string | undefined;
+  let titleController: AbortController | undefined;
+
+  pi.on('session_start', (event, _ctx) => {
+    lastSessionStartReason = event.reason;
+  });
+
+  pi.on('session_shutdown', () => {
+    titleController?.abort();
+    titleController = undefined;
+  });
+
+  pi.on('before_agent_start', (event, ctx) => {
+    if (!deps.config.isEnabled('auto_session_name')) return;
+    if (AutoSessionNameGuard.isSessionNameSet(pi)) return;
+    if (AutoSessionNameGuard.isChildSession({ startReason: lastSessionStartReason, manager: ctx.sessionManager })) return;
+    if (!AutoSessionNameGuard.isUsersFirstTurn(ctx.sessionManager)) return;
+
+    const userText = event.prompt?.trim();
+    if (!userText) return;
+
+    const cfg = deps.config.getAutoSessionName();
+    const configModel = cfg.enabled ? cfg.model : undefined;
+
+    titleController?.abort();
+    titleController = new AbortController();
+    const signal = titleController.signal;
+
+    void (async () => {
+      const resolved = await new ModelResolver(ctx).resolveModel(configModel);
+      if (resolved.error) {
+        ctx.ui.notify(resolved.error, 'warning');
+      }
+      if (!resolved.result) return;
+
+      const result = await AutoSessionNameTitleGenerator.generateAndApplyTitle({
+        pi,
+        userText,
+        resolvedModel: {
+          ...resolved.result,
+          reasoning: resolved.result.reasoning ?? 'minimal',
+        },
+        signal,
+      });
+
+      if (result.error) {
+        ctx.ui.notify(`(pi-qol) auto_session_name: ${result.error}`, 'warning');
+        return;
+      }
+
+      if (!result.text) {
+        ctx.ui.notify('(pi-qol) auto_session_name: no title was generated', 'warning');
+        return;
+      }
+
+      const appliedTitle = pi.getSessionName();
+      if (appliedTitle !== result.text) {
+        ctx.ui.notify(`(pi-qol) auto_session_name generated but not applied: ${result.text}`, 'warning');
+        return;
+      }
+
+      ctx.ui.notify(`(pi-qol) auto_session_name: ${result.text}  `, 'info');
+    })().catch(err => {
+      ctx.ui.notify(`(pi-qol) auto_session_name: ${JSON.stringify(err)}`, 'error');
+    });
+  });
+}

package/src/extensions/auto-session-name/prompt.ts

@@ -0,0 +1,64 @@
+import type { Context } from '@earendil-works/pi-ai';
+
+const LEADING_PROMPT = 'Generate a title for this conversation:\n';
+const TITLE_SYSTEM_PROMPT = `You are a title generator. You output ONLY a thread title. Nothing else.
+
+<task>
+Generate a brief title that would help the user find this conversation later.
+
+Follow all rules in <rules>
+Use the <examples> so you know what a good title looks like.
+Your output must be:
+- A single line
+- ≤70 characters
+- No explanations
+</task>
+
+<rules>
+- you MUST use the same language as the user message you are summarizing
+- Title must be grammatically correct and read naturally - no word salad
+- Never include tool names in the title (e.g. "read tool", "bash tool", "edit tool")
+- Focus on the main topic or question the user needs to retrieve
+- Vary your phrasing - avoid repetitive patterns like always starting with "Analyzing"
+- When a file is mentioned, focus on WHAT the user wants to do WITH the file, not just that they shared it
+- Keep exact: technical terms, numbers, filenames, HTTP codes
+- Remove: the, this, my, a, an
+- Never assume tech stack
+- Never use tools
+- NEVER respond to questions, just generate a title for the conversation
+- The title should NEVER include "summarizing" or "generating" when generating a title
+- DO NOT SAY YOU CANNOT GENERATE A TITLE OR COMPLAIN ABOUT THE INPUT
+- Always output something meaningful, even if the input is minimal.
+- If the user message is short or conversational (e.g. "hello", "lol", "what's up", "hey"):
+  → create a title that reflects the user's tone or intent (such as Greeting, Quick check-in, Light chat, Intro message, etc.)
+</rules>
+
+<examples>
+"debug 500 errors in production" → Debugging production 500 errors
+"refactor user service" → Refactoring user service
+"why is app.js failing" → app.js failure investigation
+"implement rate limiting" → Rate limiting implementation
+"how do I connect postgres to my API" → Postgres API connection
+"best practices for React hooks" → React hooks best practices
+"@src/auth.ts can you add refresh token support" → Auth refresh token support
+"@utils/parser.ts this is broken" → Parser bug fix
+"look at @config.json" → Config review
+"@App.tsx add dark mode toggle" → Dark mode toggle in App
+</examples>`;
+
+function buildTitleUserMessage(userText: string): string {
+  return `${LEADING_PROMPT}${userText}`;
+}
+
+export function buildTitleContext(userText: string): Context {
+  return {
+    systemPrompt: TITLE_SYSTEM_PROMPT,
+    messages: [
+      {
+        role: 'user',
+        content: buildTitleUserMessage(userText),
+        timestamp: Date.now(),
+      },
+    ],
+  };
+}

package/src/extensions/auto-session-name/title-generator.ts

@@ -0,0 +1,113 @@
+import type { Api, AssistantMessage, Context, Model, SimpleStreamOptions, TextContent } from '@earendil-works/pi-ai';
+import { completeSimple } from '@earendil-works/pi-ai';
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import type { ResolvedModel } from '../../utils/model-resolver.util';
+import { MAX_RETRIES, MAX_TITLE_LENGTH, TITLE_MAX_TOKENS } from './constants';
+import { buildTitleContext } from './prompt';
+
+type CompleteFn = (model: Model<Api>, context: Context, options?: SimpleStreamOptions) => Promise<AssistantMessage>;
+
+export type GenerateTitleResult = {
+  text?: string;
+  error?: string;
+};
+
+export class AutoSessionNameTitleGenerator {
+  static async generateAndApplyTitle(deps: {
+    pi: Pick<ExtensionAPI, 'setSessionName'>;
+    userText: string;
+    resolvedModel: ResolvedModel;
+    signal?: AbortSignal;
+    completeFn?: CompleteFn;
+  }): Promise<GenerateTitleResult> {
+    try {
+      const completeTitle = deps.completeFn ?? completeSimple;
+      const msg = await completeTitle(
+        deps.resolvedModel.model,
+        buildTitleContext(deps.userText),
+        AutoSessionNameTitleGenerator.buildTitleOptions(deps.resolvedModel, deps.signal),
+      );
+
+      const rawText = AutoSessionNameTitleGenerator.extractText(msg);
+      const title = AutoSessionNameTitleGenerator.cleanTitle(rawText);
+      if (!title) {
+        return {
+          error: AutoSessionNameTitleGenerator.buildEmptyTitleError(msg, rawText),
+          text: rawText || undefined,
+        };
+      }
+
+      deps.pi.setSessionName(title);
+      return { text: title };
+    } catch (err) {
+      const error = AutoSessionNameTitleGenerator.formatError(err);
+      return { error };
+    }
+  }
+
+  static cleanTitle(raw: string): string {
+    const withoutThinking = raw.replace(/<think>[\s\S]*?<\/think>/gi, '').replace(/<\/?think>/gi, '');
+    const title = withoutThinking
+      .split(/\r?\n/)
+      .map(line => line.trim())
+      .find(Boolean);
+
+    if (!title) return '';
+
+    const unwrapped = AutoSessionNameTitleGenerator.unwrapSurroundingQuotes(title);
+    if (!unwrapped) return '';
+    if (unwrapped.length <= MAX_TITLE_LENGTH) return unwrapped;
+
+    return `${unwrapped.slice(0, MAX_TITLE_LENGTH - 1).trimEnd()}…`;
+  }
+
+  private static extractText(msg: AssistantMessage): string {
+    return msg.content
+      .filter((content): content is TextContent => content.type === 'text')
+      .map(content => content.text)
+      .join('')
+      .trim();
+  }
+
+  private static unwrapSurroundingQuotes(value: string): string {
+    return value.replace(/^("+|'+|`+)([\s\S]*)\1$/, '$2').trim();
+  }
+
+  private static buildTitleOptions(resolvedModel: ResolvedModel, signal?: AbortSignal): SimpleStreamOptions {
+    const base: SimpleStreamOptions = {
+      apiKey: resolvedModel.apiKey,
+      headers: resolvedModel.headers,
+      signal,
+      maxRetries: MAX_RETRIES,
+      maxTokens: TITLE_MAX_TOKENS,
+    };
+
+    if (!resolvedModel.model.reasoning || !resolvedModel.reasoning || resolvedModel.reasoning === 'off') return base;
+
+    return {
+      ...base,
+      reasoning: resolvedModel.reasoning,
+    };
+  }
+
+  private static buildEmptyTitleError(msg: AssistantMessage, rawText: string): string {
+    const contentTypes = msg.content.map(content => content.type).join(', ') || 'none';
+    const details = [`model returned no title`, `stopReason=${msg.stopReason}`, `contentTypes=${contentTypes}`];
+
+    if (msg.errorMessage) details.push(`errorMessage=${msg.errorMessage}`);
+    if (rawText) details.push(`rawText=${rawText}`);
+
+    return details.join('; ');
+  }
+
+  private static formatError(err: unknown): string {
+    if (err instanceof Error) return err.message;
+    if (typeof err === 'string') return err;
+
+    try {
+      return JSON.stringify(err);
+    } catch {
+      return String(err);
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { ConfigLoader } from './config-loader';
+import { registerAutoSessionName } from './extensions/auto-session-name';
+
+export default function (pi: ExtensionAPI) {
+  const config = new ConfigLoader();
+
+  pi.on('session_start', (_event, ctx) => {
+    const { error } = config.initializeConfig(ctx);
+    if (error) ctx.ui.notify(error, 'error');
+  });
+
+  registerAutoSessionName(pi, { config });
+}

package/src/schemas/auto-session-name.config.schema.ts

@@ -0,0 +1,11 @@
+import z from 'zod';
+import { ModelConfigschema } from './shared-config.schema';
+
+export const AutoSessionNameConfigSchema = z.object({
+  enabled: z.boolean().default(false),
+  model: ModelConfigschema.optional(),
+});
+export type AutoSessionNameConfig = z.infer<typeof AutoSessionNameConfigSchema>;
+
+export const PartialAutoSessionNameConfigSchema = AutoSessionNameConfigSchema.partial();
+export type PartialAutoSessionNameConfig = z.infer<typeof PartialAutoSessionNameConfigSchema>;

package/src/schemas/config.schema.ts

@@ -0,0 +1,16 @@
+import z from 'zod';
+import { AutoSessionNameConfigSchema, PartialAutoSessionNameConfigSchema } from './auto-session-name.config.schema';
+
+export const ConfigSchema = z.object({
+  $schema: z.string().optional(),
+  auto_session_name: AutoSessionNameConfigSchema.default({
+    enabled: false,
+  }),
+});
+export type Config = z.infer<typeof ConfigSchema>;
+
+export const PartialConfigSchema = z.object({
+  $schema: z.string().optional(),
+  auto_session_name: PartialAutoSessionNameConfigSchema.optional(),
+});
+export type PartialConfig = z.infer<typeof PartialConfigSchema>;

package/src/schemas/shared-config.schema.ts

@@ -0,0 +1,11 @@
+import z from 'zod';
+
+export const ReasoningLevelSchema = z.enum(['off', 'minimal', 'low', 'medium', 'high', 'xhigh']);
+export type ReasoningLevel = z.infer<typeof ReasoningLevelSchema>;
+
+export const ModelConfigschema = z.object({
+  provider: z.string(),
+  modelId: z.string(),
+  reasoning: ReasoningLevelSchema,
+});
+export type ModelConfig = z.infer<typeof ModelConfigschema>;

package/src/utils/model-resolver.util.ts

@@ -0,0 +1,67 @@
+import type { Api, Model } from '@earendil-works/pi-ai';
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type { ModelConfig } from '../schemas/shared-config.schema';
+
+export type ResolvedModel = {
+  model: Model<Api>;
+  apiKey?: string;
+  headers?: Record<string, string>;
+  reasoning?: ModelConfig['reasoning'];
+};
+
+export type ResolveModelResult = {
+  error?: string;
+  result?: ResolvedModel;
+};
+
+export class ModelResolver {
+  constructor(private readonly ctx: ExtensionContext) {}
+
+  sessionModel(): Model<Api> | undefined {
+    return this.ctx.model;
+  }
+
+  async resolveModel(configModel?: ModelConfig): Promise<ResolveModelResult> {
+    const errors: string[] = [];
+    const candidates: Array<{ model: Model<Api>; reasoning?: ModelConfig['reasoning'] }> = [];
+
+    if (configModel) {
+      const found = this.ctx.modelRegistry.find(configModel.provider, configModel.modelId);
+      if (found) {
+        candidates.push({ model: found, reasoning: configModel.reasoning });
+      } else {
+        errors.push(`Configured model not found: ${configModel.provider}/${configModel.modelId}`);
+      }
+    }
+
+    const sessionModel = this.sessionModel();
+    if (sessionModel && !candidates.some(candidate => candidate.model.provider === sessionModel.provider && candidate.model.id === sessionModel.id)) {
+      candidates.push({ model: sessionModel });
+    }
+
+    for (const candidate of candidates) {
+      const { model } = candidate;
+      const auth = await this.ctx.modelRegistry.getApiKeyAndHeaders(model);
+      if (auth.ok) {
+        return {
+          error: errors.length > 0 ? errors.join('\n') : undefined,
+          result: {
+            model,
+            apiKey: auth.apiKey,
+            headers: auth.headers,
+            reasoning: candidate.reasoning,
+          },
+        };
+      }
+
+      const isConfiguredModel = configModel && model.provider === configModel.provider && model.id === configModel.modelId;
+      errors.push(`${isConfiguredModel ? 'Configured' : 'Session'} model auth failed for ${model.provider}/${model.id}: ${auth.error}`);
+    }
+
+    if (!sessionModel) errors.push('No active session model is available as a fallback.');
+
+    return {
+      error: errors.length > 0 ? errors.join('\n') : 'No model could be resolved.',
+    };
+  }
+}

package/src/utils/path.util.ts

@@ -0,0 +1,37 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { getAgentDir } from '@earendil-works/pi-coding-agent';
+import { EXTENSION_ID } from '../constants';
+
+export type FileSearchResult = {
+  exists: boolean;
+  path: string;
+};
+
+type FindConfigInput = { type: 'global' } | { type: 'project'; cwd: string };
+
+export class PathUtil {
+  static findFile(filePath: string): FileSearchResult {
+    if (existsSync(filePath)) {
+      return { exists: true, path: filePath };
+    }
+    return { exists: false, path: filePath };
+  }
+
+  static findExtensionConfig(input: { type: 'global' }): FileSearchResult;
+  static findExtensionConfig(input: { type: 'project'; cwd: string }): FileSearchResult;
+  static findExtensionConfig(input: FindConfigInput): FileSearchResult {
+    switch (input.type) {
+      case 'global': {
+        return PathUtil.findFile(PathUtil.getExtensionConfig([getAgentDir()]));
+      }
+      case 'project': {
+        return PathUtil.findFile(PathUtil.getExtensionConfig([input.cwd, '.pi']));
+      }
+    }
+  }
+
+  private static getExtensionConfig(paths: string[]): string {
+    return path.join(...paths, 'extensions', EXTENSION_ID, 'config.json');
+  }
+}