@henryqw/pi-task-models 3.0.2 → 4.0.1

package/README.md

@@ -2,6 +2,8 @@
 
 Choose shared `fast`, `balanced`, `frontier`, and `fav` model profiles for consumer-owned Model Tasks.
 
+![Pi showing task model profiles and task routes](./example.png)
+
 ## Why
 
 - **Created for**: Remove duplicated model pickers and catalogs that extensions once owned separately.
@@ -48,7 +50,7 @@ Fallback choices exclude the selected primary. BTW selects the first authenticat
 
 ## Config
 
-The single shared JSON file is 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
 {
@@ -88,12 +90,27 @@ Task defaults live only in consumer declarations. Existing explicit assignments,
 
 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": {} }`.
+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 file is never rewritten.
+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. |
+
+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.2",
+  "version": "4.0.1",
   "description": "Shared task model profiles and routing for HenryQW Pi extensions.",
   "keywords": [
     "pi-package",
@@ -40,11 +40,11 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/HenryQW/pi-packages.git",
-    "directory": "packages/pi-task-models"
+    "url": "git+https://github.com/HenryQW/pi-harness.git",
+    "directory": "extensions/pi-task-models"
   },
   "bugs": {
-    "url": "https://github.com/HenryQW/pi-packages/issues"
+    "url": "https://github.com/HenryQW/pi-harness/issues"
   },
   "publishConfig": {
     "access": "public"
@@ -52,6 +52,10 @@
   "pi": {
     "extensions": [
       "./extensions/task-models.ts"
-    ]
+    ],
+    "image": "https://raw.githubusercontent.com/HenryQW/pi-harness/main/extensions/pi-task-models/example.png"
+  },
+  "dependencies": {
+    "@henryqw/pi-config-store": "^0.1.0"
   }
 }