@henryqw/pi-task-models 0.1.0

package/CONTEXT.md

@@ -0,0 +1,17 @@
+# Pi Task Models
+
+Pi Task Models stores shared task profiles and task-to-profile assignments for HenryQW extensions.
+
+## Language
+
+**Task Profile**:
+Named shared route set (`fast`, `balanced`, or `frontier`) with a required primary route and optional fallback route.
+_Avoid_: package-owned model picker, per-extension model catalog
+
+**Task Route**:
+One model reference plus thinking level chosen from current Pi model scope. Empty scope means every available registry model; pinned scope thinking remains binding.
+_Avoid_: free-form provider path, copied model metadata
+
+**Active Task Package**:
+Installed HenryQW package discovered from Pi command/tool sourceInfo.
+_Avoid_: filesystem scan, settings.json scan

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Henry Wang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# `@henryqw/pi-task-models`
+
+Shared `fast`, `balanced`, and `frontier` model profiles for HenryQW Pi extensions.
+
+## Install
+
+```bash
+pi install npm:@henryqw/pi-task-models
+```
+
+Run `/task-models`. Top menu shows all profiles plus configured task assignments whose `@henryqw` package is active in Pi's effective command/tool registry. Selecting a profile chooses primary model, primary thinking, fallback model or `None`, then fallback thinking when needed; one completed flow writes whole profile once. Selecting a task changes its profile assignment.
+
+Menus and runtime resolution use current session's `ctx.scopedModels`, including pinned thinking levels. Empty scope falls back to Pi's full available model registry. Numbered Codex account aliases are deduplicated, and fallback choices exclude selected primary model. Hidden task assignments remain stored when package is disabled or removed.
+
+## Config
+
+Config lives at `getAgentDir()/config/pi-task-models.json`, normally `~/.pi/agent/config/pi-task-models.json`:
+
+```json
+{
+  "profiles": {
+    "fast": {
+      "primary": { "model": "openai-codex/gpt-fast", "thinkingLevel": "low" },
+      "fallback": { "model": "other-provider/fast-model", "thinkingLevel": "low" }
+    },
+    "balanced": {
+      "primary": { "model": "openai-codex/gpt-balanced", "thinkingLevel": "high" }
+    },
+    "frontier": {
+      "primary": { "model": "openai-codex/gpt-frontier", "thinkingLevel": "max" }
+    }
+  },
+  "tasks": {
+    "pi-herdr-rename/rename": "fast",
+    "pi-auto-compact/autoCompact": "balanced"
+  }
+}
+```
+
+Each configured profile requires one primary model and thinking level. Fallback is optional. Model references use canonical `provider/model`; numbered `openai-codex-N` account routes are stored as `openai-codex/model` and resolve onto active matching account when available.
+
+Config reads are strict. Malformed or unknown values fail visibly and never rewrite file. Only explicit `/task-models` actions write config.
+
+## Consumers
+
+- `pi-herdr-rename`: task assignment defaults to `fast`; retries configured fallback after primary route failure.
+- `pi-auto-compact`: task assignment defaults to `balanced`; retries fallback, then uses current session model so compaction still runs.
+- `pi-subagent`: caller chooses `fast`, `balanced`, or `frontier`; fallback is selected only before child starts. Started child is never retried because tools may already have side effects.
+- `pi-herdr-subagents`: intentionally independent.
+
+Primary and fallback routes outside current model scope, with unavailable models, or with unsupported or scope-pinned-different thinking levels are skipped. Consumers define final failure behavior above.
+
+## Library API
+
+Package exports config, canonical model reference, model deduplication, supported-thinking, route resolution, and active-task discovery helpers. Pi model registry and extension `sourceInfo` remain runtime authority.
+
+## Development
+
+```bash
+npm test --workspace @henryqw/pi-task-models
+npm run typecheck --workspace @henryqw/pi-task-models
+npm run pack:check --workspace @henryqw/pi-task-models
+```

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+import { type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+export declare const PROFILE_NAMES: readonly ["fast", "balanced", "frontier"];
+export type ProfileName = (typeof PROFILE_NAMES)[number];
+export declare const THINKING_LEVELS: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+export declare const DEFAULT_TASK_ASSIGNMENTS: {
+    readonly "pi-herdr-rename/rename": "fast";
+    readonly "pi-auto-compact/autoCompact": "balanced";
+};
+export type TaskModelRoute = {
+    model: string;
+    thinkingLevel: ThinkingLevel;
+};
+export type TaskModelProfile = {
+    primary: TaskModelRoute;
+    fallback?: TaskModelRoute;
+};
+export type TaskModelsConfig = {
+    profiles: Partial<Record<ProfileName, TaskModelProfile>>;
+    tasks: Record<string, ProfileName>;
+};
+export type AvailableModel = ReturnType<ExtensionContext["modelRegistry"]["getAvailable"]>[number];
+export type ResolvedTaskRoute = {
+    model: AvailableModel;
+    thinkingLevel: ThinkingLevel;
+};
+export type ActiveTaskPackage = {
+    packageName: string;
+    task: string;
+};
+export declare const configPath: (agentDir?: string) => string;
+export declare function readTaskModelsConfig(agentDir?: string): TaskModelsConfig;
+export declare function writeTaskModelsConfig(config: TaskModelsConfig, agentDir?: string): void;
+export declare function canonicalModelReference(model: {
+    provider: string;
+    id: string;
+} | string): string;
+export declare function modelReference(model: {
+    provider: string;
+    id: string;
+}): string;
+export declare function dedupeAvailableModels(models: readonly AvailableModel[], preferredProvider?: string): AvailableModel[];
+export declare function resolveAvailableModel(models: readonly AvailableModel[], reference: string, preferredProvider?: string): AvailableModel | undefined;
+export declare function supportedThinkingLevels(model: AvailableModel): ThinkingLevel[];
+export declare function availableTaskModels(ctx: ExtensionContext): AvailableModel[];
+export declare function taskThinkingLevels(ctx: ExtensionContext, model: AvailableModel): ThinkingLevel[];
+export declare function resolveTaskModelRoute(ctx: ExtensionContext, route: TaskModelRoute): ResolvedTaskRoute | undefined;
+export declare function orderedProfileRoutes(profile: TaskModelProfile): TaskModelRoute[];
+export declare function activeTaskPackages(pi: Pick<ExtensionAPI, "getCommands" | "getAllTools">, tasks?: Readonly<Record<string, ProfileName>>): ActiveTaskPackage[];
+export declare function createTaskModelsExtension(pi: ExtensionAPI, options?: {
+    agentDir?: string;
+}): void;
+export default function taskModelsExtension(pi: ExtensionAPI): void;

package/dist/index.js

@@ -0,0 +1,319 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getSupportedThinkingLevels } from "@earendil-works/pi-ai";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+export const PROFILE_NAMES = ["fast", "balanced", "frontier"];
+export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+export const DEFAULT_TASK_ASSIGNMENTS = {
+    "pi-herdr-rename/rename": "fast",
+    "pi-auto-compact/autoCompact": "balanced",
+};
+const CODEX_ALIAS = /^openai-codex-(?:[2-9]|[1-9]\d+)$/;
+const CONFIG_FILE = "pi-task-models.json";
+const defaultTaskAssignments = () => ({ ...DEFAULT_TASK_ASSIGNMENTS });
+export const configPath = (agentDir = getAgentDir()) => join(agentDir, "config", CONFIG_FILE);
+function isCodexProvider(provider) {
+    return provider === "openai-codex" || Boolean(provider && CODEX_ALIAS.test(provider));
+}
+function isProfileName(value) {
+    return typeof value === "string" && PROFILE_NAMES.includes(value);
+}
+function isThinkingLevel(value) {
+    return typeof value === "string" && THINKING_LEVELS.includes(value);
+}
+function hasOnlyKeys(value, keys) {
+    return Object.keys(value).every((key) => keys.includes(key));
+}
+function isModelReference(value) {
+    return typeof value === "string"
+        && value === value.trim()
+        && !value.includes("\0")
+        && /^[^\s/]+\/\S+$/.test(value);
+}
+function isTaskId(value) {
+    return /^[a-z0-9][a-z0-9-]*\/[A-Za-z0-9][A-Za-z0-9-]*$/.test(value);
+}
+function isTaskRoute(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const route = value;
+    return hasOnlyKeys(route, ["model", "thinkingLevel"])
+        && isModelReference(route.model)
+        && isThinkingLevel(route.thinkingLevel);
+}
+function isTaskProfile(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const profile = value;
+    return hasOnlyKeys(profile, ["primary", "fallback"])
+        && isTaskRoute(profile.primary)
+        && (profile.fallback === undefined || isTaskRoute(profile.fallback));
+}
+function normalizeRoute(route) {
+    return { model: canonicalModelReference(route.model), thinkingLevel: route.thinkingLevel };
+}
+function normalizeConfig(config) {
+    return {
+        profiles: Object.fromEntries(Object.entries(config.profiles).map(([name, profile]) => [name, {
+                primary: normalizeRoute(profile.primary),
+                ...(profile.fallback ? { fallback: normalizeRoute(profile.fallback) } : {}),
+            }])),
+        tasks: { ...config.tasks },
+    };
+}
+function parseConfig(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Config must be an object.");
+    const record = value;
+    if (!hasOnlyKeys(record, ["profiles", "tasks"]))
+        throw new Error("Config contains unknown settings.");
+    const profiles = {};
+    const tasks = defaultTaskAssignments();
+    if (record.profiles !== undefined) {
+        if (!record.profiles || typeof record.profiles !== "object" || Array.isArray(record.profiles)) {
+            throw new Error("profiles must be an object.");
+        }
+        for (const [name, profile] of Object.entries(record.profiles)) {
+            if (!PROFILE_NAMES.includes(name))
+                throw new Error(`Unknown profile: ${name}.`);
+            if (!isTaskProfile(profile))
+                throw new Error(`${name} profile is invalid.`);
+            const profileName = name;
+            profiles[profileName] = {
+                primary: normalizeRoute(profile.primary),
+                ...(profile.fallback ? { fallback: normalizeRoute(profile.fallback) } : {}),
+            };
+        }
+    }
+    if (record.tasks !== undefined) {
+        if (!record.tasks || typeof record.tasks !== "object" || Array.isArray(record.tasks)) {
+            throw new Error("tasks must be an object.");
+        }
+        for (const [task, profile] of Object.entries(record.tasks)) {
+            if (!isTaskId(task) || !isProfileName(profile))
+                throw new Error(`Invalid profile assignment for ${task}.`);
+            tasks[task] = profile;
+        }
+    }
+    return { profiles, tasks };
+}
+export function readTaskModelsConfig(agentDir = getAgentDir()) {
+    try {
+        const value = JSON.parse(readFileSync(configPath(agentDir), "utf8"));
+        return parseConfig(value);
+    }
+    catch (error) {
+        if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+            return { profiles: {}, tasks: defaultTaskAssignments() };
+        }
+        throw error;
+    }
+}
+export function writeTaskModelsConfig(config, agentDir = getAgentDir()) {
+    const file = configPath(agentDir);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, `${JSON.stringify(normalizeConfig(config), null, 2)}\n`);
+}
+export function canonicalModelReference(model) {
+    const reference = typeof model === "string" ? model : `${model.provider}/${model.id}`;
+    if (!isModelReference(reference))
+        throw new Error("Model reference must be provider/model without whitespace.");
+    const separator = reference.indexOf("/");
+    const provider = reference.slice(0, separator);
+    const id = reference.slice(separator + 1);
+    return `${isCodexProvider(provider) ? "openai-codex" : provider}/${id}`;
+}
+export function modelReference(model) {
+    return `${model.provider}/${model.id}`;
+}
+export function dedupeAvailableModels(models, preferredProvider) {
+    const deduped = [];
+    const indexes = new Map();
+    for (const model of models) {
+        const key = canonicalModelReference(model);
+        const index = indexes.get(key);
+        if (index === undefined) {
+            indexes.set(key, deduped.length);
+            deduped.push(model);
+            continue;
+        }
+        const current = deduped[index];
+        if (shouldPreferModel(model, current, preferredProvider))
+            deduped[index] = model;
+    }
+    return deduped;
+}
+function shouldPreferModel(candidate, current, preferredProvider) {
+    if (preferredProvider && candidate.provider === preferredProvider && current.provider !== preferredProvider)
+        return true;
+    if (preferredProvider && current.provider === preferredProvider && candidate.provider !== preferredProvider)
+        return false;
+    const candidateAlias = CODEX_ALIAS.test(candidate.provider);
+    const currentAlias = CODEX_ALIAS.test(current.provider);
+    if (candidateAlias !== currentAlias)
+        return candidateAlias;
+    return false;
+}
+export function resolveAvailableModel(models, reference, preferredProvider) {
+    const canonical = canonicalModelReference(reference);
+    const separator = canonical.indexOf("/");
+    const provider = canonical.slice(0, separator);
+    const id = canonical.slice(separator + 1);
+    if (provider !== "openai-codex") {
+        return models.find((model) => canonicalModelReference(model) === canonical);
+    }
+    return (preferredProvider && isCodexProvider(preferredProvider)
+        ? models.find((model) => model.provider === preferredProvider && model.id === id)
+        : undefined)
+        ?? models.find((model) => CODEX_ALIAS.test(model.provider) && model.id === id)
+        ?? models.find((model) => model.provider === "openai-codex" && model.id === id);
+}
+export function supportedThinkingLevels(model) {
+    return getSupportedThinkingLevels(model);
+}
+export function availableTaskModels(ctx) {
+    const scopedModels = ctx.scopedModels ?? [];
+    return dedupeAvailableModels((scopedModels.length ? scopedModels.map(({ model }) => model) : ctx.modelRegistry.getAvailable())
+        .filter((model) => model.input.includes("text")), ctx.model?.provider);
+}
+export function taskThinkingLevels(ctx, model) {
+    const supported = supportedThinkingLevels(model);
+    const pinned = (ctx.scopedModels ?? []).find(({ model: scoped }) => scoped.provider === model.provider && scoped.id === model.id)?.thinkingLevel;
+    if (!pinned)
+        return supported;
+    return supported.includes(pinned) ? [pinned] : [];
+}
+export function resolveTaskModelRoute(ctx, route) {
+    const model = resolveAvailableModel(availableTaskModels(ctx), route.model, ctx.model?.provider);
+    return model && taskThinkingLevels(ctx, model).includes(route.thinkingLevel)
+        ? { model, thinkingLevel: route.thinkingLevel }
+        : undefined;
+}
+export function orderedProfileRoutes(profile) {
+    return profile.fallback ? [profile.primary, profile.fallback] : [profile.primary];
+}
+export function activeTaskPackages(pi, tasks = DEFAULT_TASK_ASSIGNMENTS) {
+    const sources = [
+        ...pi.getCommands().map((command) => command.sourceInfo),
+        ...pi.getAllTools().map((tool) => tool.sourceInfo),
+    ];
+    return Object.keys(tasks).flatMap((task) => {
+        if (!isTaskId(task))
+            return [];
+        const packageName = `@henryqw/${task.slice(0, task.indexOf("/"))}`;
+        return sources.some((source) => sourceMatchesPackage(source, packageName))
+            ? [{ packageName, task }]
+            : [];
+    });
+}
+function sourceMatchesPackage(sourceInfo, packageName) {
+    const npmSource = `npm:${packageName}`;
+    if (sourceInfo.source === packageName || sourceInfo.source === npmSource || sourceInfo.source.startsWith(`${npmSource}@`))
+        return true;
+    const path = sourceInfo.path.replaceAll("\\", "/");
+    const shortName = packageName.split("/").pop();
+    return path.includes(`/node_modules/${packageName}/`)
+        || Boolean(shortName && path.includes(`/packages/${shortName}/`));
+}
+export function createTaskModelsExtension(pi, options) {
+    const agentDir = options?.agentDir ?? getAgentDir();
+    pi.registerCommand("task-models", {
+        description: "configure shared task model profiles",
+        handler: async (_args, ctx) => {
+            let config;
+            try {
+                config = readTaskModelsConfig(agentDir);
+            }
+            catch {
+                ctx.ui.notify("Couldn't read task model config.", "error");
+                return;
+            }
+            const profileOptions = PROFILE_NAMES.map((name) => {
+                const configured = config.profiles[name];
+                return {
+                    name,
+                    label: configured
+                        ? `${name} · ${routeLabel(configured.primary)} → ${configured.fallback ? routeLabel(configured.fallback) : "none"}`
+                        : `${name} · not configured`,
+                };
+            });
+            const save = () => {
+                try {
+                    writeTaskModelsConfig(config, agentDir);
+                    return true;
+                }
+                catch {
+                    ctx.ui.notify("Couldn't save task model config.", "error");
+                    return false;
+                }
+            };
+            const taskOptions = activeTaskPackages(pi, config.tasks).map((entry) => ({
+                entry,
+                label: `${entry.task} · ${config.tasks[entry.task]}`,
+            }));
+            const selected = await ctx.ui.select("Task models", [
+                ...profileOptions.map(({ label }) => label),
+                ...taskOptions.map(({ label }) => label),
+            ]);
+            if (!selected)
+                return;
+            const task = taskOptions.find(({ label }) => label === selected)?.entry;
+            if (task) {
+                const profile = await ctx.ui.select(`${task.task} profile`, [...PROFILE_NAMES]);
+                if (!isProfileName(profile))
+                    return;
+                config.tasks[task.task] = profile;
+                if (!save())
+                    return;
+                ctx.ui.notify(`${task.task} assigned to ${profile}.`, "info");
+                return;
+            }
+            const profile = profileOptions.find(({ label }) => label === selected)?.name;
+            if (!profile)
+                return;
+            const models = availableTaskModels(ctx);
+            if (!models.length) {
+                ctx.ui.notify("No text models are available.", "error");
+                return;
+            }
+            const primary = await selectRoute(ctx, `Profile ${profile} primary`, models);
+            if (!primary)
+                return;
+            const fallbackModels = models.filter((model) => canonicalModelReference(model) !== primary.model);
+            const fallbackModel = await ctx.ui.select(`Profile ${profile} fallback`, [
+                "None",
+                ...fallbackModels.map((model) => modelReference(model)),
+            ]);
+            if (!fallbackModel)
+                return;
+            const fallback = fallbackModel === "None"
+                ? undefined
+                : await selectThinkingLevel(ctx, `Profile ${profile} fallback`, fallbackModels, fallbackModel);
+            if (fallbackModel !== "None" && !fallback)
+                return;
+            config.profiles[profile] = { primary, ...(fallback ? { fallback } : {}) };
+            if (!save())
+                return;
+            ctx.ui.notify(`${profile} profile saved.`, "info");
+        },
+    });
+}
+function routeLabel(route) {
+    return `${route.model} (${route.thinkingLevel})`;
+}
+async function selectRoute(ctx, title, models) {
+    const selectedModel = await ctx.ui.select(title, models.map((model) => modelReference(model)));
+    return selectedModel ? selectThinkingLevel(ctx, title, models, selectedModel) : undefined;
+}
+async function selectThinkingLevel(ctx, title, models, selectedModel) {
+    const model = models.find((candidate) => modelReference(candidate) === selectedModel);
+    if (!model)
+        return;
+    const thinkingLevel = await ctx.ui.select(`${title} thinking`, taskThinkingLevels(ctx, model));
+    if (!isThinkingLevel(thinkingLevel))
+        return;
+    return { model: canonicalModelReference(model), thinkingLevel };
+}
+export default function taskModelsExtension(pi) {
+    createTaskModelsExtension(pi);
+}

package/extensions/task-models.ts

@@ -0,0 +1,10 @@
+import { type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createTaskModelsExtension } from "@henryqw/pi-task-models";
+
+export function registerTaskModelsExtension(pi: ExtensionAPI, options?: { agentDir?: string }): void {
+	createTaskModelsExtension(pi, options);
+}
+
+export default function taskModelsExtension(pi: ExtensionAPI): void {
+	registerTaskModelsExtension(pi);
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@henryqw/pi-task-models",
+  "version": "0.1.0",
+  "description": "Shared task model profiles and routing for HenryQW Pi extensions.",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "model",
+    "settings"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "license": "MIT",
+  "files": [
+    "dist",
+    "extensions",
+    "README.md",
+    "CONTEXT.md",
+    "LICENSE"
+  ],
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "test": "npm run build && node --test test/*.test.ts",
+    "typecheck": "tsc --noEmit --allowImportingTsExtensions --target ES2022 --module NodeNext --moduleResolution NodeNext --types node --skipLibCheck src/*.ts extensions/*.ts test/*.ts",
+    "prepack": "npm run build",
+    "pack:check": "npm pack --dry-run"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "^0.84.2",
+    "@earendil-works/pi-coding-agent": "^0.84.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HenryQW/pi-packages.git",
+    "directory": "packages/pi-task-models"
+  },
+  "bugs": {
+    "url": "https://github.com/HenryQW/pi-packages/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/task-models.ts"
+    ]
+  }
+}