@mjasnikovs/pi-task 0.38.31 → 0.39.0

package/dist/config/option-picker.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The two-step picker a /task-config step row opens on Enter.
+ *
+ * WHY A SUBMENU AND NOT `ctx.ui.select`
+ * -------------------------------------
+ * The settings panel already lives inside `ctx.ui.custom` with `overlay: true`.
+ * Opening a second dialog from inside a component's input handler races two
+ * overlays for focus. `SettingsList` already solves this: it renders the submenu
+ * in place of the list and delegates input to it. And its `done(v)` calls
+ * `onChange(id, v)` with exactly the returned value while `done(undefined)`
+ * writes nothing — the same one-value contract every cycling row uses, so the
+ * panel's dispatch needs no branch and a pair chosen out of two long lists costs
+ * ONE write.
+ *
+ * WHY NOT A BARE `SelectList`
+ * ---------------------------
+ * `SelectList.handleInput` matches up, down, confirm and cancel and DROPS every
+ * other key, so it can never fill its own `setFilter`. `Container` has no
+ * `handleInput` at all — it composes `render` and nothing else. pi's own model
+ * picker (`modes/interactive/components/model-selector.js`) hand-rolls exactly
+ * this: an `Input`, a filtered list, and a `handleInput` that routes between
+ * them. The three components that DO use `SelectList` bare — theme, thinking,
+ * show-images — are short fixed lists with no filter. A model list is not.
+ */
+import { Container } from '@earendil-works/pi-tui';
+import type { SelectItem } from '@earendil-works/pi-tui';
+import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
+type Theme = ExtensionCommandContext['ui']['theme'];
+/** What the second stage offers, once the first has been answered. */
+export interface PairStage {
+    options: readonly SelectItem[];
+    /**
+     * The option to open on — the value that will ACTUALLY run.
+     *
+     * Supplied by the caller rather than derived here, because deciding it is
+     * the clamp, and the clamp belongs to the config layer that owns the model's
+     * declared ladder. It is what makes the auto-switch visible: pick a model
+     * that cannot do `medium` and this stage opens on `off`.
+     */
+    preselect: string;
+}
+export interface PairOptions {
+    first: readonly SelectItem[];
+    second: (firstValue: string) => PairStage;
+    /** Which half of the stored value stage one opens on. */
+    firstOf: (value: string) => string;
+    /** How the two answers become the one string the row stores. */
+    join: (first: string, second: string) => string;
+}
+/**
+ * Model, then thinking level, as one choice.
+ *
+ * Two stages rather than one flat list of every legal pair: the pair space is
+ * models × levels, and the common edit is "change the model, keep the level" —
+ * a flat list would make that re-pick both every time.
+ *
+ * Escape at EITHER stage cancels the whole thing. Going back one step would be
+ * friendlier, but a TUI select owns up, down, enter and escape and has no fifth
+ * key to spare, and a half-answered pair must never reach `done`.
+ */
+export declare class PairPicker extends Container {
+    private readonly options;
+    private readonly theme;
+    private readonly done;
+    private stage;
+    constructor(options: PairOptions, currentValue: string, theme: Theme, done: (value?: string) => void);
+    private openSecond;
+    handleInput(data: string): void;
+}
+export {};

package/dist/config/option-picker.js

@@ -0,0 +1,113 @@
+/**
+ * The two-step picker a /task-config step row opens on Enter.
+ *
+ * WHY A SUBMENU AND NOT `ctx.ui.select`
+ * -------------------------------------
+ * The settings panel already lives inside `ctx.ui.custom` with `overlay: true`.
+ * Opening a second dialog from inside a component's input handler races two
+ * overlays for focus. `SettingsList` already solves this: it renders the submenu
+ * in place of the list and delegates input to it. And its `done(v)` calls
+ * `onChange(id, v)` with exactly the returned value while `done(undefined)`
+ * writes nothing — the same one-value contract every cycling row uses, so the
+ * panel's dispatch needs no branch and a pair chosen out of two long lists costs
+ * ONE write.
+ *
+ * WHY NOT A BARE `SelectList`
+ * ---------------------------
+ * `SelectList.handleInput` matches up, down, confirm and cancel and DROPS every
+ * other key, so it can never fill its own `setFilter`. `Container` has no
+ * `handleInput` at all — it composes `render` and nothing else. pi's own model
+ * picker (`modes/interactive/components/model-selector.js`) hand-rolls exactly
+ * this: an `Input`, a filtered list, and a `handleInput` that routes between
+ * them. The three components that DO use `SelectList` bare — theme, thinking,
+ * show-images — are short fixed lists with no filter. A model list is not.
+ */
+import { Container, getKeybindings, Input, SelectList } from '@earendil-works/pi-tui';
+/** Rows visible before the list scrolls. Matches the panel's own MAX_VISIBLE. */
+const PICKER_VISIBLE = 11;
+function selectTheme(theme) {
+    return {
+        selectedPrefix: text => theme.fg('accent', text),
+        selectedText: text => theme.fg('accent', theme.bold(text)),
+        description: text => theme.fg('muted', text),
+        scrollInfo: text => theme.fg('dim', text),
+        noMatch: text => theme.fg('dim', text)
+    };
+}
+/**
+ * A filterable list with a text filter above it.
+ *
+ * Split out because both stages are one of these and the routing is the part
+ * that is easy to get wrong: `SelectList` owns four keys and drops the rest, so
+ * everything else has to be handed to the `Input` and the filter re-applied.
+ */
+class FilterList extends Container {
+    onPick;
+    onCancel;
+    input = new Input();
+    list;
+    constructor(options, preselect, theme, onPick, onCancel) {
+        super();
+        this.onPick = onPick;
+        this.onCancel = onCancel;
+        this.list = new SelectList([...options], PICKER_VISIBLE, selectTheme(theme));
+        // A `preselect` matching no option is normal, not an error: a row can
+        // hold a spec the catalog no longer offers, and it must still open.
+        const at = options.findIndex(o => o.value === preselect);
+        if (at !== -1)
+            this.list.setSelectedIndex(at);
+        this.list.onSelect = item => this.onPick(item.value);
+        this.list.onCancel = () => this.onCancel();
+        this.addChild(this.input);
+        this.addChild(this.list);
+    }
+    handleInput(data) {
+        const kb = getKeybindings();
+        const forList = kb.matches(data, 'tui.select.up')
+            || kb.matches(data, 'tui.select.down')
+            || kb.matches(data, 'tui.select.confirm')
+            || kb.matches(data, 'tui.select.cancel');
+        if (forList) {
+            this.list.handleInput(data);
+            return;
+        }
+        // Everything else is typing. The list re-filters on every keystroke,
+        // which is what `setFilter` is for and what nothing else calls.
+        this.input.handleInput(data);
+        this.list.setFilter(this.input.getValue());
+    }
+}
+/**
+ * Model, then thinking level, as one choice.
+ *
+ * Two stages rather than one flat list of every legal pair: the pair space is
+ * models × levels, and the common edit is "change the model, keep the level" —
+ * a flat list would make that re-pick both every time.
+ *
+ * Escape at EITHER stage cancels the whole thing. Going back one step would be
+ * friendlier, but a TUI select owns up, down, enter and escape and has no fifth
+ * key to spare, and a half-answered pair must never reach `done`.
+ */
+export class PairPicker extends Container {
+    options;
+    theme;
+    done;
+    stage;
+    constructor(options, currentValue, theme, done) {
+        super();
+        this.options = options;
+        this.theme = theme;
+        this.done = done;
+        this.stage = new FilterList(options.first, options.firstOf(currentValue), theme, first => this.openSecond(first), () => done(undefined));
+        this.addChild(this.stage);
+    }
+    openSecond(first) {
+        const { options: second, preselect } = this.options.second(first);
+        this.stage = new FilterList(second, preselect, this.theme, level => this.done(this.options.join(first, level)), () => this.done(undefined));
+        this.clear();
+        this.addChild(this.stage);
+    }
+    handleInput(data) {
+        this.stage.handleInput(data);
+    }
+}

package/dist/config/reasoning.d.ts

@@ -17,35 +17,21 @@
  *
  * PURE MODULE — no imports with runtime side effects, so `config.ts` can import
  * the table and the sanitizers during its own module evaluation. `getConfig()`
- * lives one hop away in `reasoning-args.ts` for exactly this reason: importing
+ * lives one hop away in `group-args.ts` for exactly this reason: importing
  * it here would make config.ts ⇄ reasoning.ts a real cycle, and whichever module
  * a caller reached first would decide whether `DEFAULT_REASONING_TABLE` was
  * initialised before `DEFAULT_CONFIG` read it.
  */
 import type { PiTaskConfig } from './config.js';
+import { CHILD_GROUPS, type ChildGroup } from './groups.js';
 /**
- * The child roles that share one reasoning setting.
- *
- * Grouped by JOB, not by spawn mechanism — two children that both go through
- * `runWorker` (a research worker and a verify gate) want different amounts of
- * thinking, while `refine` in phases.ts and `compress-label` in title-label.ts
- * want the same amount and share the `phase` cell.
- *
- * - `research`     the ad-hoc `pi-worker` subagent tool, and the fallback the four
- *                  research workers use when their own cell is unset
- * - `research:files` / `research:apis` / `research:context` / `research:tooling`
- *                  one cell per research worker, so a level can be paid for in
- *                  one worker without paying for it in the other three
- * - `phase`        refine, verify-tooling, grill, compose, critique, compress-label
- * - `planning`     /task-auto's planning children — clarify, decompose, and the
- *                  extract/coverage passes around them
- * - `plan`         /task-plan's question and answer children
- * - `gate`         enforce, verify, lint-fix, final-fix, recommend
- * - `extraction`   the --no-tools focused docs/fetch extractors
- * - `implementation` the host-session turn that writes the code (not a child)
+ * Re-exported because this module's whole public surface — the default table,
+ * `resolveReasoning`, `effectiveReasoning` — is typed on them, so an importer of
+ * those already needs them. The roster itself lives in groups.ts; `GROUP_BY_CHILD`
+ * and `groupForChild` are deliberately NOT re-exported, so a caller that wants
+ * the roster reaches for the roster.
  */
-export type ReasoningGroup = 'research' | 'research:files' | 'research:apis' | 'research:context' | 'research:tooling' | 'phase' | 'planning' | 'plan' | 'gate' | 'extraction' | 'implementation';
-export declare const REASONING_GROUPS: readonly ReasoningGroup[];
+export { CHILD_GROUPS, type ChildGroup };
 /**
  * The four profiles offered by /task-config.
  * - `default` the per-group table below
@@ -82,44 +68,9 @@ export declare const REASONING_ON_LEVEL: GroupSetting;
  * host's level. Any other value is a decision this project made for that
  * group's job, and `/task-config` mode `custom` overrides all of it.
  */
-export declare const DEFAULT_REASONING_TABLE: Readonly<Record<ReasoningGroup, GroupSetting>>;
+export declare const DEFAULT_REASONING_TABLE: Readonly<Record<ChildGroup, GroupSetting>>;
 /** A stored mode, or `default` when the value is not one. */
 export declare function sanitizeReasoningMode(value: unknown): ReasoningMode;
-/**
- * Child NAME → reasoning group, for every child spawned under a name:
- * `runPhaseChild`, `runPlanningChild`, and the research workers' `spec.label`.
- *
- * WHY KEYED ON THE NAME
- * ---------------------
- * The name is the only identifier in scope at all three spawn paths (phases,
- * /task-auto planning, /task-plan), it is what the loader and the debug trail
- * already print, and it is the one thing a reader can check against the phase
- * list without following the call graph. Threading a group parameter through
- * `PhaseDeps` / `AutoDeps` instead would touch both orchestrators' dep bags to
- * express something the call site already says out loud.
- *
- * AN UNMAPPED NAME IS A BUILD FAILURE, not a silent `inherit`.
- * `reasoning-groups.test.ts` scans every literal child name under `src/task`
- * and fails if it is missing here. A defaulting lookup would let a phase added
- * later opt itself out of the table without anyone deciding to.
- *
- * The gate and extraction groups are NOT here: those children reach the model
- * through `groupThinkingArgs('gate' | 'extraction')` at call sites with no name
- * in scope (gate-deps.ts, fetch-core.ts, docs-core.ts, pi-worker-docs.ts). The
- * four research workers do have a name — their `spec.label` — so they are here.
- */
-export declare const REASONING_GROUP_BY_CHILD: Readonly<Record<string, ReasoningGroup>>;
-/**
- * The group a named child belongs to.
- *
- * Returns `undefined` for a name the table does not know, and the CALLER decides
- * what that means. `runPhaseChild` treats it as `inherit` — a child that reaches
- * the model with today's argv is always safe — while the test treats it as a
- * failure. That split is deliberate: the guard belongs at build time, where
- * someone can fix it, not at run time, where it would abort a user's task over a
- * missing table row.
- */
-export declare function reasoningGroupForChild(name: string): ReasoningGroup | undefined;
 /**
  * Always returns a COMPLETE record, never a partial one.
  *
@@ -128,16 +79,16 @@ export declare function reasoningGroupForChild(name: string): ReasoningGroup | u
  * `undefined`, and every call site would need its own fallback. Filling the gaps
  * here means the type is true at the only place that constructs the value.
  */
-export declare function sanitizeReasoningLevels(value: unknown): Record<ReasoningGroup, GroupSetting>;
+export declare function sanitizeReasoningLevels(value: unknown): Record<ChildGroup, GroupSetting>;
 /**
  * What one group is actually set to, given a config. The ONLY place the four
  * modes are interpreted.
  *
  * `cfg` is required rather than defaulted to `getConfig()` so this module stays
  * import-free (see the header). Callers that want the live config use
- * `groupThinkingArgs` from reasoning-args.ts.
+ * `groupThinkingArgs` from group-args.ts.
  */
-export declare function resolveReasoning(group: ReasoningGroup, cfg: PiTaskConfig): GroupSetting;
+export declare function resolveReasoning(group: ChildGroup, cfg: PiTaskConfig): GroupSetting;
 /**
  * The WHOLE table, as this config will actually run it.
  *
@@ -146,12 +97,23 @@ export declare function resolveReasoning(group: ReasoningGroup, cfg: PiTaskConfi
  * asks the single-group question instead, through `resolveReasoning` — which is
  * the only place the four modes are interpreted.
  */
-export declare function effectiveReasoning(cfg: PiTaskConfig): Record<ReasoningGroup, GroupSetting>;
+export declare function effectiveReasoning(cfg: PiTaskConfig): Record<ChildGroup, GroupSetting>;
 /**
  * The argv fragment for a setting. `inherit` is the empty fragment — no flag at
  * all — which is what makes an all-`inherit` config byte-identical to the
  * version before this feature existed.
  */
 export declare function thinkingArgs(setting: GroupSetting): string[];
-/** One honest sentence per group, for the /task-config rows. */
-export declare const REASONING_GROUP_HELP: Readonly<Record<ReasoningGroup, string>>;
+/**
+ * One honest sentence per step, for the merged /task-config rows.
+ *
+ * ONE table, not the model help and the reasoning help concatenated. The panel
+ * sizes every frame from its tallest description (`settingsBodyHeight`), so
+ * gluing two paragraphs together for `implementation` would permanently add
+ * about six rows to the whole menu — for a row most users never open.
+ *
+ * What survives the merge is the part that is not guessable: which children the
+ * step actually spawns, what was MEASURED about its thinking level, and the one
+ * cost that is paid per turn rather than per change.
+ */
+export declare const STEP_GROUP_HELP: Readonly<Record<ChildGroup, string>>;

package/dist/config/reasoning.js

@@ -1,16 +1,12 @@
-export const REASONING_GROUPS = [
-    'research',
-    'research:files',
-    'research:apis',
-    'research:context',
-    'research:tooling',
-    'phase',
-    'planning',
-    'plan',
-    'gate',
-    'extraction',
-    'implementation'
-];
+import { CHILD_GROUPS, sanitizeGroupRecord } from './groups.js';
+/**
+ * Re-exported because this module's whole public surface — the default table,
+ * `resolveReasoning`, `effectiveReasoning` — is typed on them, so an importer of
+ * those already needs them. The roster itself lives in groups.ts; `GROUP_BY_CHILD`
+ * and `groupForChild` are deliberately NOT re-exported, so a caller that wants
+ * the roster reaches for the roster.
+ */
+export { CHILD_GROUPS };
 export const REASONING_MODES = ['default', 'on', 'off', 'custom'];
 /**
  * The settings offered in /task-config: `inherit` plus the standard part of pi's
@@ -56,80 +52,6 @@ export const DEFAULT_REASONING_TABLE = {
 export function sanitizeReasoningMode(value) {
     return REASONING_MODES.includes(value) ? value : 'default';
 }
-/**
- * Child NAME → reasoning group, for every child spawned under a name:
- * `runPhaseChild`, `runPlanningChild`, and the research workers' `spec.label`.
- *
- * WHY KEYED ON THE NAME
- * ---------------------
- * The name is the only identifier in scope at all three spawn paths (phases,
- * /task-auto planning, /task-plan), it is what the loader and the debug trail
- * already print, and it is the one thing a reader can check against the phase
- * list without following the call graph. Threading a group parameter through
- * `PhaseDeps` / `AutoDeps` instead would touch both orchestrators' dep bags to
- * express something the call site already says out loud.
- *
- * AN UNMAPPED NAME IS A BUILD FAILURE, not a silent `inherit`.
- * `reasoning-groups.test.ts` scans every literal child name under `src/task`
- * and fails if it is missing here. A defaulting lookup would let a phase added
- * later opt itself out of the table without anyone deciding to.
- *
- * The gate and extraction groups are NOT here: those children reach the model
- * through `groupThinkingArgs('gate' | 'extraction')` at call sites with no name
- * in scope (gate-deps.ts, fetch-core.ts, docs-core.ts, pi-worker-docs.ts). The
- * four research workers do have a name — their `spec.label` — so they are here.
- */
-export const REASONING_GROUP_BY_CHILD = {
-    // ── phase: task/phases.ts + task/title-label.ts ──────────────────────────
-    refine: 'phase',
-    'verify-tooling': 'phase',
-    'grill-auto': 'phase',
-    'grill-gen': 'phase',
-    compose: 'phase',
-    critique: 'phase',
-    'critique-triage': 'phase',
-    'compress-label': 'phase',
-    // ── planning: task/auto-orchestrator.ts ──────────────────────────────────
-    'clarify-triage': 'planning',
-    'auto-clarify': 'planning',
-    'auto-decompose': 'planning',
-    'requirement-extract': 'planning',
-    'decompose-coverage': 'planning',
-    'coverage-map': 'planning',
-    'contract-extract': 'planning',
-    'launch-extract': 'planning',
-    // ── plan: task/plan-orchestrator.ts ──────────────────────────────────────
-    'plan-question': 'plan',
-    'plan-answer': 'plan',
-    // ── research: task/phases.ts `workerSpecs`, keyed on the spec's LABEL ─────
-    'worker:files': 'research:files',
-    'worker:apis': 'research:apis',
-    'worker:context': 'research:context',
-    'worker:tooling': 'research:tooling'
-};
-/**
- * The group a named child belongs to.
- *
- * Returns `undefined` for a name the table does not know, and the CALLER decides
- * what that means. `runPhaseChild` treats it as `inherit` — a child that reaches
- * the model with today's argv is always safe — while the test treats it as a
- * failure. That split is deliberate: the guard belongs at build time, where
- * someone can fix it, not at run time, where it would abort a user's task over a
- * missing table row.
- */
-export function reasoningGroupForChild(name) {
-    return REASONING_GROUP_BY_CHILD[name];
-}
-/**
- * For a `research:*` group, the group a stored config falls back to when its own
- * key is missing. Every other group maps to `undefined`.
- */
-const RESEARCH_SUBGROUP_PARENT = {
-    'research:files': 'research',
-    'research:apis': 'research',
-    'research:context': 'research',
-    'research:tooling': 'research'
-};
 /**
  * Always returns a COMPLETE record, never a partial one.
  *
@@ -139,25 +61,7 @@ const RESEARCH_SUBGROUP_PARENT = {
  * here means the type is true at the only place that constructs the value.
  */
 export function sanitizeReasoningLevels(value) {
-    const stored = typeof value === 'object' && value !== null && !Array.isArray(value) ?
-        value
-        : {};
-    const valid = (v) => REASONING_SETTINGS.includes(v);
-    const out = {};
-    for (const group of REASONING_GROUPS) {
-        const stored_ = stored[group];
-        if (valid(stored_)) {
-            out[group] = stored_;
-            continue;
-        }
-        // A `research:*` key the stored config never had falls back to its
-        // parent `research` value, so a config written before the split keeps
-        // meaning what it meant.
-        const parent = RESEARCH_SUBGROUP_PARENT[group];
-        out[group] =
-            parent && valid(stored[parent]) ? stored[parent] : DEFAULT_REASONING_TABLE[group];
-    }
-    return out;
+    return sanitizeGroupRecord(value, (v) => REASONING_SETTINGS.includes(v), group => DEFAULT_REASONING_TABLE[group]);
 }
 /**
  * What one group is actually set to, given a config. The ONLY place the four
@@ -165,7 +69,7 @@ export function sanitizeReasoningLevels(value) {
  *
  * `cfg` is required rather than defaulted to `getConfig()` so this module stays
  * import-free (see the header). Callers that want the live config use
- * `groupThinkingArgs` from reasoning-args.ts.
+ * `groupThinkingArgs` from group-args.ts.
  */
 export function resolveReasoning(group, cfg) {
     switch (cfg.reasoningMode) {
@@ -189,7 +93,7 @@ export function resolveReasoning(group, cfg) {
  */
 export function effectiveReasoning(cfg) {
     const out = {};
-    for (const group of REASONING_GROUPS)
+    for (const group of CHILD_GROUPS)
         out[group] = resolveReasoning(group, cfg);
     return out;
 }
@@ -201,12 +105,23 @@ export function effectiveReasoning(cfg) {
 export function thinkingArgs(setting) {
     return setting === 'inherit' ? [] : ['--thinking', setting];
 }
-/** One honest sentence per group, for the /task-config rows. */
-export const REASONING_GROUP_HELP = {
-    research: 'The pi-worker subagent tool, and the fallback for any research worker below '
-        + 'whose own level is unset. Read-only exploration loops.',
+/**
+ * One honest sentence per step, for the merged /task-config rows.
+ *
+ * ONE table, not the model help and the reasoning help concatenated. The panel
+ * sizes every frame from its tallest description (`settingsBodyHeight`), so
+ * gluing two paragraphs together for `implementation` would permanently add
+ * about six rows to the whole menu — for a row most users never open.
+ *
+ * What survives the merge is the part that is not guessable: which children the
+ * step actually spawns, what was MEASURED about its thinking level, and the one
+ * cost that is paid per turn rather than per change.
+ */
+export const STEP_GROUP_HELP = {
+    research: 'The pi-worker subagent tool, and the fallback for any research worker below. '
+        + 'Long read-only loops, where a cheap fast model pays off.',
     'research:files': 'Research worker 1 of 4: maps which files the task will touch. Read-heavy. '
-        + 'Measured: the two arms tie, so it runs without thinking.',
+        + 'Measured: the two thinking arms tie, so it runs without.',
     'research:apis': 'Research worker 2 of 4: the symbols and signatures the task must call. '
         + 'Read-heavy, docs- and search-capable.',
     'research:context': 'Research worker 3 of 4: how the project is put together. One of the two that '
@@ -221,6 +136,7 @@ export const REASONING_GROUP_HELP = {
     gate: 'The checks that run after code is written: verify, enforce, lint-fix, autofix.',
     extraction: 'The small no-tools children that pull one answer out of a fetched page or '
         + 'a docs chunk.',
-    implementation: 'The main session turn that actually writes the code. Changing this briefly '
-        + "changes pi's own thinking level, and puts it back afterwards."
+    implementation: 'The main session turn that writes the code — YOUR session, moved for the turn and '
+        + 'moved back. Unlike every step above, the model half here is not free: a switch '
+        + 're-bills the whole prompt as a cache miss, twice per task.'
 };