@henryqw/pi-task-models

v4.0.1

Choose shared fast, balanced, frontier, and fav model profiles for consumer-owned Model Tasks.

Why

• 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

pi install npm:@henryqw/pi-task-models

With

Use

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.

Active declarations

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.

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

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.

{
  "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" }
    },
    "fav": {
      "primary": { "model": "openai-codex/gpt-favorite", "thinkingLevel": "high" }
    }
  },
  "tasks": {
    "pi-herdr-btw/btw": "balanced"
  }
}

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. 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:

Every error directs users to /task-models. A consumer may silence only config-missing when it has a safe current-session fallback.