@henryqw/pi-task-models

Choose shared model and thinking routes for extension tasks named fast, balanced, frontier, and fav. Users configure routes once while each extension keeps ownership of its task and default.

Install

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

Run /task-models after installation. Configure each profile that your installed consumers require.

Works with

Package	Relationship	Purpose
@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-memory	Consumer	Its local candidate-review task defaults to balanced.
@henryqw/pi-multi-codex	Improves	Numbered Codex slots dedupe to one route.
@henryqw/pi-prompt-creator	Consumer	Its local prompt-drafting task defaults to fast.
@henryqw/pi-subagent	Consumer	Its local delegation task defaults to fast; callers can declare their own task.

Use

Run /task-models to complete the first setup:

1. Select fast.
2. Choose a primary model from Pi's effective registry, then choose its thinking level.
3. Choose a different fallback model and thinking level, or choose None.
4. Reopen /task-models. The fast row now shows the saved route instead of not configured.

Repeat these steps for balanced, frontier, or fav when a consumer needs them. The fav profile has no fallback.

Select an active task to override its declared profile. Choosing that task's declared default removes the override.

Flow

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.

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. Only explicit /task-models actions save it.

The following JSON shows structure only. Every model ID is a placeholder and must not be copied.

{
  "profiles": {
    "fast": {
      "primary": { "model": "<provider>/<fast-model-from-Pi>", "thinkingLevel": "low" },
      "fallback": { "model": "<provider>/<fallback-model-from-Pi>", "thinkingLevel": "low" }
    },
    "balanced": {
      "primary": { "model": "<provider>/<balanced-model-from-Pi>", "thinkingLevel": "high" }
    },
    "frontier": {
      "primary": { "model": "<provider>/<frontier-model-from-Pi>", "thinkingLevel": "max" }
    },
    "fav": {
      "primary": { "model": "<provider>/<favorite-model-from-Pi>", "thinkingLevel": "high" }
    }
  },
  "tasks": {
    "pi-herdr-btw/btw": "balanced"
  }
}

Use exact model IDs offered by /task-models. Pi's registry, not this example, defines available models.

Name	Description	Values	Default
profiles	Stores configured shared routes by profile name.	Object keyed by fast, balanced, frontier, or fav; unknown profile names are rejected.	{} (no profiles configured)
profiles.<profile>.primary.model	Selects the primary model. Required within a configured primary route.	Canonical provider/model reference without whitespace or NUL; available models come from Pi's model registry or session-scoped models.	—
profiles.<profile>.primary.thinkingLevel	Sets the primary model's thinking level. Required within a configured primary route.	off, minimal, low, medium, high, xhigh, or max; the model must support the level when the route resolves.	—
profiles.<profile>.fallback	Sets the route to try when the primary route is unavailable.	Object requiring model and thinkingLevel under the same rules as primary; not allowed for fav.	No fallback route.
tasks	Stores explicit profile overrides by task ID.	Object mapping task IDs (<package>/<task>) to profiles.	{}
tasks.<taskId>	Overrides that task's declared profile.	fast, balanced, frontier, or fav.	That task declaration's defaultProfile

Pi's model registry, including session-scoped models, is the source of available models. 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>.

API

Surface	Type	Purpose
ModelTask	type	Describes a consumer-owned independently executed model operation.
registerModelTask(pi, task)	function	Registers a consumer's task declaration at extension load.
loadTaskModelsConfig()	function	Reads and validates the owner config file when present.
resolveConfiguredTaskRoute(ctx, task)	function	Resolves the first usable route for a task.
resolveConfiguredTaskRoutes(ctx, task)	function	Resolves the task's configured route candidates.
executeTaskRoutes(routes, attempt, { shouldFallback, signal? })	function	Tries supplied resolved routes in order and returns the first success.

Consumers do not access the config file directly. loadTaskModelsConfig() returns source as "file" or "missing", so consumers can warn when defaults are in use.

Profile thinking is authoritative. Resolution uses config.tasks[task.id] ?? task.defaultProfile.

Consumers never read or write the shared file directly.

Limits and recovery

loadTaskModelsConfig() returns { source: "missing", value: { "profiles": {}, "tasks": {} } } for a missing file. It does not create a file.

At session start, Task Models warns when the shared config 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.

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.

executeTaskRoutes() uses only caller-supplied resolved routes. It does not resolve routes, authenticate, inspect providers, log, wait, or retry a route.

It rejects empty route lists and checks its optional abort signal before every attempt. It stops on cancellation or when shouldFallback(error) returns false.

After allowed failures, it rethrows the final route error unchanged. Each attempt must be atomic and safe to repeat.