@henryqw/pi-task-models 5.0.1 → 5.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +18 -22
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,13 +1,9 @@
1
1
  # `@henryqw/pi-task-models`
2
2
 
3
- Choose shared model and thinking routes for extension tasks named `fast`, `balanced`, `frontier`, and `fav`.
3
+ 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.
4
4
 
5
5
  ![Pi showing task model profiles and task routes](./example.png)
6
-
7
- ## Why
8
-
9
- - **Created for**: Pi users who want one place to route model work started by several extensions.
10
- - **Advantage**: Reuse profile choices while each extension keeps ownership of its task and default.
6
+ ![Task routing from consumer declaration to route or error](./docs/task-routing-architecture.svg)
11
7
 
12
8
  ## Install
13
9
 
@@ -17,7 +13,7 @@ pi install npm:@henryqw/pi-task-models
17
13
 
18
14
  Run `/task-models` after installation. Configure each profile that your installed consumers require.
19
15
 
20
- ## With
16
+ ## Works with
21
17
 
22
18
  | Package | Why |
23
19
  | --- | --- |
@@ -42,23 +38,19 @@ Repeat these steps for `balanced`, `frontier`, or `fav` when a consumer needs th
42
38
 
43
39
  Select an active task to override its declared profile. Choosing that task's declared default removes the override.
44
40
 
45
- ### Active declarations
41
+ ## Flow
46
42
 
47
43
  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.
48
44
 
49
45
  The control plane lists each active task's effective profile. Hidden explicit assignments stay stored when a consumer is disabled.
50
46
 
51
- ![Task routing from consumer declaration to route or error](./docs/task-routing-architecture.svg)
52
-
53
- ### Scoped models, aliases, and fallback
54
-
55
47
  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.
56
48
 
57
49
  Fallback choices exclude the selected primary. BTW selects the first authenticated viable route before pane launch.
58
50
 
59
51
  ## Config
60
52
 
61
- 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.
53
+ The shared JSON file is at `~/.pi/agent/config/pi-task-models/config.json`. Only explicit `/task-models` actions save it.
62
54
 
63
55
  The following JSON shows structure only. Every model ID is a placeholder and must not be copied.
64
56
 
@@ -90,31 +82,35 @@ Use exact model IDs offered by `/task-models`. Pi's registry, not this example,
90
82
  | Field | Required | Possible values | Default |
91
83
  | --- | --- | --- | --- |
92
84
  | `profiles` | No | Object keyed by `fast`, `balanced`, `frontier`, `fav`; unknown profile names are rejected | `{}` (no profiles configured) |
93
- | `profiles.<profile>.primary.model` | Yes within a configured profile's `primary` | Canonical `provider/model` reference without whitespace or NUL; available models come from Pi's model registry (or session-scoped models) at resolution time, not from this file | — |
85
+ | `profiles.<profile>.primary.model` | Yes within a configured profile's `primary` | Canonical `provider/model` reference without whitespace or NUL; available models come from Pi's model registry or session-scoped models | — |
94
86
  | `profiles.<profile>.primary.thinkingLevel` | Yes within a configured profile's `primary` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`; the model must support the level when the route resolves | — |
95
87
  | `profiles.<profile>.fallback` | No | When present, requires both `model` and `thinkingLevel` with the corresponding `primary.*` values; not allowed for `fav` | Omitted |
96
88
  | `tasks` | No | Object mapping task IDs (`<package>/<task>`) to explicit user profile overrides | `{}` |
97
89
  | `tasks.<taskId>` | Value required if the key is present | `fast`, `balanced`, `frontier`, `fav` | That task declaration's `defaultProfile` |
98
90
 
99
- Pi's model registry, including session-scoped models, is the source of available models at resolution. This file does not contain a model catalog.
91
+ Pi's model registry, including session-scoped models, is the source of available models. This file does not contain a model catalog.
100
92
 
101
93
  Task defaults live only in consumer declarations. Existing explicit assignments, including one equal to a declaration's default, remain valid.
102
94
 
103
95
  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>`.
104
96
 
105
- Reads are strict. `loadTaskModelsConfig()` returns `{ source: "missing", value: { "profiles": {}, "tasks": {} } }` for a missing file. It does not create a file.
97
+ ## API
106
98
 
107
- At session start, task-models warns when `~/.pi/agent/config/pi-task-models/config.json` is missing; run `/task-models` to configure task routes.
99
+ A `ModelTask` is a consumer-owned independently executed model operation. Consumers define a `ModelTask` and call `registerModelTask(pi, task)` at extension load.
108
100
 
109
- 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.
101
+ Use `loadTaskModelsConfig()` to read and validate the owner config file when present. Consumers do not access the file directly. Its `source` is `"file"` or `"missing"`, so consumers can warn when defaults are in use.
110
102
 
111
- ## For extension authors
103
+ Use `resolveConfiguredTaskRoute(ctx, task)` or `resolveConfiguredTaskRoutes(ctx, task)` to resolve routes. Profile thinking is authoritative. Resolution uses `config.tasks[task.id] ?? task.defaultProfile`.
112
104
 
113
- A `ModelTask` is a consumer-owned independently executed model operation. Consumers define a `ModelTask` and call `registerModelTask(pi, task)` at extension load.
105
+ Consumers never read or write the shared file directly.
114
106
 
115
- 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.
107
+ ## Limits and recovery
116
108
 
117
- 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`.
109
+ `loadTaskModelsConfig()` returns `{ source: "missing", value: { "profiles": {}, "tasks": {} } }` for a missing file. It does not create a file.
110
+
111
+ At session start, Task Models warns when the shared config is missing. Run `/task-models` to configure task routes.
112
+
113
+ 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.
118
114
 
119
115
  Resolution errors are `TaskRouteError` values. Check `taskRouteCode`:
120
116
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@henryqw/pi-task-models",
3
- "version": "5.0.1",
3
+ "version": "5.0.2",
4
4
  "description": "Shared task model profiles and routing for HenryQW Pi extensions.",
5
5
  "keywords": [
6
6
  "pi-package",