@henryqw/pi-task-models

Configure shared Task Profiles for fast, balanced, frontier, and fav. Each Task Route pairs a model with a thinking level; each consumer owns its Model Tasks and defaults.

Install

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

Requires Pi 1.5.0 or later in the 1.x series.

Works with

Use

Type /task-models to see the available actions. The command without arguments opens profile and task settings.

Run /task-models, select fast, then choose a primary model and thinking level. Choose a different fallback model and thinking level, or None. Reopen /task-models: fast shows the saved route instead of not configured.

Configure each profile your consumers require. fav has no fallback. Select an active task to override its declared profile; choosing its declared default removes the override.

Delegate routes

/task-models lists the billion-context acp_delegate roles. Researcher defaults to fast; reviewer, worker, planner, and oracle default to balanced. Assign a profile to each role as needed. The first available route supplies the model and thinking level.

Run /task-models sync-delegates to write the available routes to the external delegate role settings. This overwrites the model and thinking level for each role with an available route. Startup, prompts, and other task model saves do not sync delegate settings. The command runs only when the registered acp_delegate comes from npm:billion-context. Other delegate providers are skipped.

When pi.subagents is an object or true in the billion-context config, the sync updates its role settings. When it is false or has enabled: false, the sync stays inactive. When it is absent, billion-context uses the legacy acp.json files.

The sync updates the project file when it has a delegate setting; otherwise, it updates the global file. It creates the global file only when a route is available. The sync preserves other settings and does not change a disabled legacy delegate. Project delegate settings replace the global delegate object.

The config path is BILI_CONFIG_FILE when set, otherwise billion-context/billion-context.json under XDG_CONFIG_HOME, or ~/.config when that variable is unset. The legacy paths are ~/.pi/acp.json and .pi/acp.json in the session working directory; the directory name follows Pi.

Sync requires strict JSON in these files, even if the billion-context loader accepts comments or trailing commas. If a file is not strict JSON, sync shows a warning and leaves it unchanged. Remove comments and trailing commas, and use quoted keys and strings to repair it.

Sync also leaves files unchanged if delegate role settings are invalid, if they are symbolic or hard links, or if permissions or metadata are unsupported. Files with numbers that would change during JSON serialization are also left unchanged. Route or write problems show a warning and do not block Pi. Explicit delegate call settings still take priority.

Billion-context loads delegate config at session initialization. Start a new session after sync to use the changes.

Presets

Run /task-models preset and choose a name. Included profiles replace complete routes, thinking levels, and fallbacks in one atomic update. Omitted profiles and task assignments stay unchanged. Applying can create missing active config.

To save, open /task-models, press Option+S (macOS) or Alt+S, then enter a name. The preset contains all configured profiles, not task assignments. Other presets stay unchanged. Cancelling a preset prompt writes nothing.

The shortcut requires an interactive terminal that sends Option/Alt as Meta (Escape); RPC does not support it.

Flow

The menu shows effective profiles for active tasks. Disabled consumers' assignments remain stored but hidden.

Menus list your scoped models and pinned thinking levels, or all available text models when no scope is set. Duplicate numbered Codex aliases collapse into one choice; fallback choices exclude the primary.

Config

Package-owned: ~/.pi/agent/config/pi-task-models/config.json. Only explicit /task-models actions save it. Use exact model IDs from Pi's registry, not these placeholders:

{
  "profiles": {
    "fast": {
      "primary": { "model": "<provider>/<model>", "thinkingLevel": "low" }
    }
  },
  "tasks": {}
}

Task defaults belong to consumer declarations. Existing overrides equal to those defaults remain valid.

Preset file

You can edit ~/.pi/agent/config/pi-task-models/presets.json manually. It maps preset names to any subset of the four profiles, each in the profiles.<profile> format above. The picker sorts names alphabetically.

Missing, empty, or invalid files do not change active config. Invalid names, presets, and profiles produce warnings and are ignored; valid entries remain available.

Saving never overwrites a preset file that has problems; a conflict message asks you to try again.

API

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

The optional onFallback(profileName, route) callback reports when the first usable route is the configured fallback. It does not run when the primary is usable or when no route is usable. It does not report execution failures or retries. Consumers own warning delivery and duplicate suppression.

Consumers must not read or write shared config; call report(ctx) before resolution.

executeTaskRoutes() rejects empty lists and checks signal before each route. Cancellation or shouldFallback(error) === false stops execution. Allowed failures end with the final error unchanged. Each route call must be atomic and safe to repeat.

Limits and recovery

Problems appear at session start and when /task-models opens. For the shared rules, see Config files. Resolution throws TaskRouteError with a taskRouteCode:

Saves retain only valid settings, including valid tasks when profiles is invalid. If the file changed while /task-models was open, saving writes nothing; reopen /task-models.

Saving refuses oversized, unreadable, or non-regular files. Fix, shrink, or remove the file first.

Consumers may silence only config-missing, and only with a safe current-session fallback.