@henryqw/pi-task-models 3.0.1 → 4.0.0

package/README.md

@@ -1,10 +1,10 @@
 # `@henryqw/pi-task-models`
 
-Shared `fast`, `balanced`, `frontier`, and `fav` model profiles plus routing for consumer-owned Model Tasks.
+Choose shared `fast`, `balanced`, `frontier`, and `fav` model profiles for consumer-owned Model Tasks.
 
 ## Why
 
-- **Created for**: Deduplicating model pickers and catalogs that each extension previously owned separately.
+- **Created for**: Remove duplicated model pickers and catalogs that extensions once owned separately.
 - **Advantage**: One shared profile control plane keeps routes consistent while each consumer owns its task identity, intent, and default profile.
 
 ## Install
@@ -20,24 +20,35 @@ pi install npm:@henryqw/pi-task-models
 | `@henryqw/pi-auto-compact` | Consumer. Its local compaction task defaults to `fast`. |
 | `@henryqw/pi-herdr-btw` | Consumer. Its local side-thread task defaults to `fast`. |
 | `@henryqw/pi-herdr-rename` | Consumer. Its local rename task defaults to `fast`. |
-| `@henryqw/pi-subagent` | Consumer. Its local delegation task defaults to `fast`; callers can declare their own task. |
+| `@henryqw/pi-memory` | Consumer. Its local candidate-review task defaults to `balanced`. |
 | `@henryqw/pi-multi-codex` | Improves. Numbered Codex slots dedupe to one route. |
+| `@henryqw/pi-subagent` | Consumer. Its local delegation task defaults to `fast`; callers can declare their own task. |
 
 ## Use
 
-| Surface | Type | Purpose |
-| --- | --- | --- |
-| `/task-models` | command | Edit a profile or override an active task's default profile. |
+Use `/task-models` to select a profile or override an active task's default profile.
+
+### Profile selection
+
+Selecting a profile sets its primary model, primary thinking, optional fallback model, and fallback thinking. One completed flow writes the whole profile.
+
+Selecting an active task sets its explicit override. Choosing its consumer-declared default removes that override.
 
-Selecting a profile sets primary model, primary thinking, optional fallback model, then fallback thinking. One completed flow writes the whole profile. Selecting an active task sets its explicit override; choosing its consumer-declared default removes that override.
+### Active declarations
 
-Consumers register their declarations at extension load. The one shared control plane asks active extensions for declarations when `/task-models` opens, so extension load order does not matter. It lists each active task's effective profile. Hidden explicit assignments stay stored when a consumer is disabled.
+Consumers register declarations at extension load. When `/task-models` opens, the shared control plane asks active extensions for declarations. Extension load order does not matter.
 
-Menus and resolution use the current session's `ctx.scopedModels`, including pinned thinking. Empty scope uses Pi's full available model registry. Numbered Codex account aliases are deduplicated. Fallback choices exclude the selected primary. BTW selects the first authenticated viable route before pane launch.
+The control plane lists each active task's effective profile. Hidden explicit assignments stay stored when a consumer is disabled.
+
+### Scoped models, aliases, and fallback
+
+Menus and resolution use the current session's `ctx.scopedModels`, including pinned thinking. An empty scope uses Pi's full available model registry. Numbered Codex account aliases are deduplicated.
+
+Fallback choices exclude the selected primary. BTW selects the first authenticated viable route before pane launch.
 
 ## Config
 
-Single shared JSON file at the exact package-owned path `~/.pi/agent/config/pi-task-models.json`. Consumers read it but never write it; only explicit `/task-models` actions save it.
+The shared JSON file is at `~/.pi/agent/config/pi-task-models/config.json`. Consumers use `loadTaskModelsConfig()` for validated values. They never read or write this file. Only explicit `/task-models` actions save it.
 
 ```json
 {
@@ -71,8 +82,33 @@ Single shared JSON file at the exact package-owned path `~/.pi/agent/config/pi-t
 | `tasks` | No | Object mapping task IDs (`<package>/<task>`) to explicit user profile overrides | `{}` |
 | `tasks.<taskId>` | Value required if the key is present | `fast`, `balanced`, `frontier`, `fav` | That task declaration's `defaultProfile` |
 
-Task defaults live only in consumer declarations. Existing explicit assignments, including one equal to a declaration's default, remain valid. Model references use canonical `provider/model`; numbered Codex account aliases (`openai-codex-N`) resolve through Pi's registry and store canonically as `openai-codex/<model>`.
+Pi's model registry, including session-scoped models, is the source of available models at resolution. This file does not contain a model catalog.
+
+Task defaults live only in consumer declarations. Existing explicit assignments, including one equal to a declaration's default, remain valid.
+
+Model references use canonical `provider/model`. Numbered Codex account aliases (`openai-codex-N`) resolve through Pi's registry and store canonically as `openai-codex/<model>`.
 
-Reads are strict. A missing file yields `{ "profiles": {}, "tasks": {} }`; malformed JSON, unknown keys, invalid task IDs, unknown profiles, or invalid profile or route values fail visibly with `/task-models` guidance and never rewrite the file.
+Reads are strict. `loadTaskModelsConfig()` returns `{ source: "missing", value: { "profiles": {}, "tasks": {} } }` for a missing file. It does not create a file.
+
+At session start, task-models warns when `~/.pi/agent/config/pi-task-models/config.json` is missing; run `/task-models` to configure task routes.
+
+Malformed JSON, unknown keys, invalid task IDs, unknown profiles, or invalid profile or route values fail visibly with `/task-models` guidance. The malformed file is preserved.
+
+## For extension authors
+
+A `ModelTask` is a consumer-owned independently executed model operation. Consumers define a `ModelTask` and call `registerModelTask(pi, task)` at extension load.
+
+Use `loadTaskModelsConfig()` to get validated config without reading a file. Its `source` is `"file"` or `"missing"`, so consumers can warn when defaults are in use.
+
+Use `resolveConfiguredTaskRoute(ctx, task)` or `resolveConfiguredTaskRoutes(ctx, task)` to resolve routes. Profile thinking is authoritative for task routes. Resolution uses `config.tasks[task.id] ?? task.defaultProfile`.
+
+Resolution errors are `TaskRouteError` values. Check `taskRouteCode`:
+
+| Code | Meaning |
+| --- | --- |
+| `config-missing` | The optional shared config file is absent. |
+| `config-read` | A present shared config file cannot be read or validated. |
+| `profile-missing` | The selected profile is not configured. |
+| `no-route` | The selected profile has no available route. |
 
-Profile thinking is authoritative for task routes. Consumers define a `ModelTask`, call `registerModelTask(pi, task)` at extension load, then call `resolveConfiguredTaskRoute(ctx, task)` or `resolveConfiguredTaskRoutes(ctx, task)`. Resolution uses `config.tasks[task.id] ?? task.defaultProfile`.
+Every error directs users to `/task-models`. A consumer may silence only `config-missing` when it has a safe current-session fallback.

package/dist/index.d.ts

@@ -28,9 +28,10 @@ export type ResolvedTaskRoute = {
     model: AvailableModel;
     thinkingLevel: ThinkingLevel;
 };
-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 loadTaskModelsConfig(agentDir?: string): {
+    source: "file" | "missing";
+    value: TaskModelsConfig;
+};
 export declare function canonicalModelReference(model: {
     provider: string;
     id: string;
@@ -45,7 +46,7 @@ export declare function availableTaskModels(ctx: ExtensionContext): AvailableMod
 export declare function taskThinkingLevels(ctx: ExtensionContext, model: AvailableModel): ThinkingLevel[];
 export declare function resolveTaskModelRoute(ctx: ExtensionContext, route: TaskModelRoute, agentDir?: string, thinking?: ThinkingLevel): ResolvedTaskRoute | undefined;
 export declare function resolveConfiguredTaskRoutes(ctx: ExtensionContext, task: ModelTask, agentDir?: string, thinking?: ThinkingLevel): ResolvedTaskRoute[];
-export type TaskRouteErrorCode = "config-read" | "profile-missing" | "no-route";
+export type TaskRouteErrorCode = "config-missing" | "config-read" | "profile-missing" | "no-route";
 export type TaskRouteError = Error & {
     taskRouteCode: TaskRouteErrorCode;
     profileName?: ProfileName;

package/dist/index.js

@@ -1,16 +1,13 @@
-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";
+import { createConfigStore } from "@henryqw/pi-config-store";
 export const PROFILE_NAMES = ["fast", "balanced", "frontier", "fav"];
 export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
 const CODEX_ALIAS = /^openai-codex-(?:[2-9]|[1-9]\d+)$/;
-const CONFIG_FILE = "pi-task-models.json";
 const MODEL_TASK_REQUEST_EVENT = "@henryqw/pi-task-models:model-task-request";
 const MODEL_TASK_RESPONSE_EVENT = "@henryqw/pi-task-models:model-task-response";
 const registeredModelTasks = new WeakMap();
 let modelTaskRequestNumber = 0;
-export const configPath = (agentDir = getAgentDir()) => join(agentDir, "config", CONFIG_FILE);
 function isCodexProvider(provider) {
     return provider === "openai-codex" || Boolean(provider && CODEX_ALIAS.test(provider));
 }
@@ -89,15 +86,6 @@ function isTaskProfile(value) {
 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.");
@@ -136,24 +124,16 @@ function parseConfig(value) {
     }
     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: {} };
-        }
-        throw error;
-    }
+function taskModelsConfigStore(agentDir = getAgentDir()) {
+    return createConfigStore({
+        extensionId: "pi-task-models",
+        agentDir,
+        defaults: () => ({ profiles: {}, tasks: {} }),
+        parse: parseConfig,
+    });
 }
-export function writeTaskModelsConfig(config, agentDir = getAgentDir()) {
-    if (config.profiles.fav?.fallback)
-        throw new Error("fav profile has no fallback.");
-    const file = configPath(agentDir);
-    mkdirSync(dirname(file), { recursive: true });
-    writeFileSync(file, `${JSON.stringify(normalizeConfig(config), null, 2)}\n`);
+export function loadTaskModelsConfig(agentDir = getAgentDir()) {
+    return taskModelsConfigStore(agentDir).loadSync();
 }
 export function canonicalModelReference(model) {
     const reference = typeof model === "string" ? model : `${model.provider}/${model.id}`;
@@ -237,13 +217,17 @@ export function resolveTaskModelRoute(ctx, route, agentDir = getAgentDir(), thin
 }
 export function resolveConfiguredTaskRoutes(ctx, task, agentDir = getAgentDir(), thinking) {
     const declaration = validatedModelTask(task);
-    let config;
+    let loadedConfig;
     try {
-        config = readTaskModelsConfig(agentDir);
+        loadedConfig = loadTaskModelsConfig(agentDir);
     }
     catch {
         throw taskRouteError("config-read", "Couldn't read task model config. Run /task-models.");
     }
+    if (loadedConfig.source === "missing") {
+        throw taskRouteError("config-missing", "Task model config is missing. Run /task-models to configure task routes.");
+    }
+    const config = loadedConfig.value;
     const profileName = config.tasks[declaration.id] ?? declaration.defaultProfile;
     const profile = config.profiles[profileName];
     if (!profile)
@@ -351,12 +335,18 @@ function discoverModelTasks(pi) {
 }
 export function createTaskModelsExtension(pi, options) {
     const agentDir = options?.agentDir ?? getAgentDir();
+    const configStore = taskModelsConfigStore(agentDir);
+    pi.on("session_start", (_event, ctx) => {
+        if (configStore.loadSync().source === "missing") {
+            ctx.ui.notify(`Task model config is missing at ${configStore.path}; run /task-models to configure task routes.`, "warning");
+        }
+    });
     pi.registerCommand("task-models", {
         description: "configure shared task model profiles",
         handler: async (_args, ctx) => {
             let config;
             try {
-                config = readTaskModelsConfig(agentDir);
+                config = configStore.loadSync().value;
             }
             catch {
                 ctx.ui.notify("Couldn't read task model config.", "error");
@@ -371,9 +361,9 @@ export function createTaskModelsExtension(pi, options) {
                         : `${name} · not configured`,
                 };
             });
-            const save = () => {
+            const save = async () => {
                 try {
-                    writeTaskModelsConfig(config, agentDir);
+                    await configStore.save(config);
                     return true;
                 }
                 catch {
@@ -400,7 +390,7 @@ export function createTaskModelsExtension(pi, options) {
                     delete config.tasks[task.id];
                 else
                     config.tasks[task.id] = profile;
-                if (!save())
+                if (!await save())
                     return;
                 ctx.ui.notify(`${task.id} assigned to ${profile}.`, "info");
                 return;
@@ -434,7 +424,7 @@ export function createTaskModelsExtension(pi, options) {
                     return;
                 config.profiles[profile] = { primary, ...(fallback ? { fallback } : {}) };
             }
-            if (!save())
+            if (!await save())
                 return;
             ctx.ui.notify(`${profile} profile saved.`, "info");
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-task-models",
-  "version": "3.0.1",
+  "version": "4.0.0",
   "description": "Shared task model profiles and routing for HenryQW Pi extensions.",
   "keywords": [
     "pi-package",
@@ -14,11 +14,11 @@
   },
   "license": "MIT",
   "files": [
+    "LICENSE",
     "dist",
     "extensions",
     "README.md",
-    "CONTEXT.md",
-    "LICENSE"
+    "CONTEXT.md"
   ],
   "types": "./dist/index.d.ts",
   "exports": {
@@ -53,5 +53,8 @@
     "extensions": [
       "./extensions/task-models.ts"
     ]
+  },
+  "dependencies": {
+    "@henryqw/pi-config-store": "^0.1.0"
   }
 }