@mjasnikovs/pi-task 0.38.29 → 0.38.31

package/dist/config/reasoning.d.ts

@@ -3,17 +3,17 @@
  *
  * WHY THIS EXISTS
  * ---------------
- * Every pi-task child inherits `defaultThinkingLevel` from the host's
- * `~/.pi/agent/settings.json`, because `CHILD_BASE_ARGS`
- * (shared/child-process.ts) passes no `--thinking`. That is one level for ~33
- * children whose jobs are nothing alike: a planner that must reason to produce a
- * plan at all, and a label-compressor that emits four words.
- *
- * The control that WAS here — appending Qwen3's `/no_think` soft switch to eight
- * prompts — is measured inert. Captured live against Qwen3.8-27B with server
- * thinking on and `/no_think` still in the prompt: median 17k-char trace anyway,
- * n=25. A harness cannot disable thinking by prompt text; the chat-template
- * kwarg beats it. `--thinking` sets that kwarg, so it is the lever that works.
+ * `CHILD_BASE_ARGS` (shared/child-process.ts) passes no `--thinking`, so every
+ * pi-task child inherits `defaultThinkingLevel` from the host's
+ * `~/.pi/agent/settings.json`. That is one level for children whose jobs are
+ * nothing alike: a planner that must reason to produce a plan at all, and a
+ * label-compressor that emits four words.
+ *
+ * `--thinking <level>` is pi's own flag. For a Qwen model it reaches the server
+ * as `enable_thinking` — either a top-level parameter or inside
+ * `chat_template_kwargs`, depending on the model's declared thinking format
+ * (pi-ai `api/openai-completions.js`). Prompt text cannot reach that kwarg, so
+ * the flag is the only lever on it.
  *
  * PURE MODULE — no imports with runtime side effects, so `config.ts` can import
  * the table and the sanitizers during its own module evaluation. `getConfig()`
@@ -28,21 +28,17 @@ import type { PiTaskConfig } from './config.js';
  *
  * 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 two that reach the model by different code paths (`refine` via
- * runPhaseChild, `compress-label` via the same) want the same.
+ * 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`     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. They are FOUR CELLS, not one,
- *                  because the four wander differently: over mx5-n 2026-08-27
- *                  every one of the 40.7 wasted research minutes was a restart
- *                  in `tooling` or `context`, and `files` and `apis` never
- *                  restarted once. A single `research` cell cannot be set to
- *                  pay for thinking where it is needed without also paying for
- *                  it where it measurably is not.
+ *                  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 clarify / decompose / extract children
+ * - `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
@@ -52,7 +48,7 @@ export type ReasoningGroup = 'research' | 'research:files' | 'research:apis' | '
 export declare const REASONING_GROUPS: readonly ReasoningGroup[];
 /**
  * The four profiles offered by /task-config.
- * - `default` the measured per-group table below
+ * - `default` the per-group table below
  * - `on`      one level everywhere ({@link REASONING_ON_LEVEL})
  * - `off`     no thinking anywhere
  * - `custom`  the user's own per-group table
@@ -63,87 +59,35 @@ export declare const REASONING_MODES: readonly ReasoningMode[];
  * What one group is set to.
  *
  * `inherit` is NOT a pi thinking level — it means EMIT NO FLAG, so the child
- * falls back to `settings.json` exactly as it does today. It is what lets this
- * whole feature ship as a zero-behaviour-change commit: with every cell at
- * `inherit`, every child's argv is byte-identical to the version before it.
+ * falls back to `settings.json`. With every cell at `inherit` this whole table
+ * is a no-op and every child's argv is byte-identical to a build without it.
  */
 export type GroupSetting = 'inherit' | 'off' | 'minimal' | 'low' | 'medium' | 'high';
 /**
- * The settings offered in /task-config: `inherit` plus pi's OWN cycle
- * (`THINKING_LEVELS` in pi-coding-agent's agent-session).
+ * The settings offered in /task-config: `inherit` plus the standard part of pi's
+ * own thinking cycle.
  *
- * `xhigh` and `max` are DELIBERATELY ABSENT. pi treats an absent
- * `thinkingLevelMap` entry as "supported" for the standard levels but requires a
- * declared entry for the extended two (pi-ai `getSupportedThinkingLevels`), so a
- * model with no map would receive the raw string — and Qwen3.8's chat template
- * answers an unknown effort with HTTP 500, not a clamp. Offering a level that pi's
- * own UI does not is how you ship a `--thinking` that hard-fails on some models.
- * This machine already reaches xhigh through `"high": "xhigh"` in its map.
+ * `xhigh` and `max` are DELIBERATELY ABSENT. pi-ai's `getSupportedThinkingLevels`
+ * accepts the standard levels for any reasoning model, but offers `xhigh` and
+ * `max` only when the model declares them in its `thinkingLevelMap`. Offering
+ * them here would put a level in this UI that pi's own UI may not have.
  */
 export declare const REASONING_SETTINGS: readonly GroupSetting[];
-/**
- * The level mode `on` uses, and the treatment arm of the A/B that fills in
- * {@link DEFAULT_REASONING_TABLE}. ONE constant so the shipped config and the
- * measurement behind it can never drift apart.
- */
+/** The level mode `on` uses. */
 export declare const REASONING_ON_LEVEL: GroupSetting;
 /**
  * The per-group table used by mode `default`.
  *
- * A cell is `inherit` until it has been MEASURED, and then it names a level.
- * Every non-`inherit` cell here must be a live A/B result
- * (scripts/live-reasoning-group-ab.ts, n>=20 per arm, arms `off` vs
- * {@link REASONING_ON_LEVEL}) carrying its date, model, counts and RUNG in the
- * comment beside it. A cell filled in from intuition is WORSE than `inherit`:
- * `inherit` is honest about knowing nothing, while a wrong cell is a
- * measurement nobody took, wearing the authority of a default.
- *
- * THE RUNG IS PART OF THE RESULT, so read it before trusting a cell. The
- * harness returns a two-way verdict — `off` or {@link REASONING_ON_LEVEL},
- * never a tie — down a three-rung ladder: rung 1 a significant quality
- * difference, rung 2 quality level and a significant speed difference, rung 3
- * nothing separated the arms and the cheaper level carries it by a stated
- * prior. A rung-3 cell is a DECISION, not a finding: it says "no reason found
- * to pay for thinking", not "thinking was shown not to help". At n=20/arm the
- * run is only powered for large effects, so rung 3 is the common outcome and
- * an absent effect and an undetected one look identical from here.
- *
- * NOTHING IS ALREADY ON THE RECORD, and the belief that something was is worth
- * writing down. This docstring used to say magicknumbers.md had measured the
- * decompose child "with one knob, `enable_thinking` — off answered 1/10, on
- * answered 8/8", and treated that as the split the A/B had to reproduce.
- *
- * VERIFIED 2026-08-27: the string "8/8" does not appear in magicknumbers.md, and
- * never has (`git log -S`; the phrase was introduced by THIS file's own commit,
- * `0b91f71`). What that page records is
- *
- *     "Measured, captured decompose request, REASONING OFF, n=10 per cell:
- *      1/10 → 7/10 (stall detector) → 8/9 (all three)."
- *
- * — a ladder over THREE GUARDS at CONSTANT reasoning off, from `fea7bbb`. Both
- * endpoints are the same arm. `enable_thinking` is not its knob and never was,
- * and the "8/8" is a misread of the ladder's last cell, `8/9`.
- *
- * So no reasoning effect on `planning` had ever been measured, and the 10/10 vs
- * 10/10 read on the current tree was not a contradiction of a prior result — it
- * was the only reading there had ever been. The controls that page DOES record
- * (Qwen3.6-27B 10/10, Gemma4-12B 10/10) are likewise reasoning off, so they say
- * nothing about a cell flipping by model either.
- *
- * The `planning` cell below is the FIRST measured reading of that knob, taken
- * 2026-08-27 on a citation-fidelity axis built for it. It is also the first cell
- * that is not `off`.
+ * `inherit` says nothing was decided for that group and the child keeps the
+ * 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>>;
-/**
- * A hand-edited or stale mode must not reach {@link resolveReasoning}'s switch as
- * an unknown string — the `default:` arm would silently absorb it and the user
- * would see "custom" in the file and the default table in behaviour.
- */
+/** 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 that goes through
- * `runPhaseChild` / `runPlanningChild`.
+ * Child NAME → reasoning group, for every child spawned under a name:
+ * `runPhaseChild`, `runPlanningChild`, and the research workers' `spec.label`.
  *
  * WHY KEYED ON THE NAME
  * ---------------------
@@ -155,15 +99,14 @@ export declare function sanitizeReasoningMode(value: unknown): ReasoningMode;
  * 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 in src/ and fails if
- * it is missing here. A defaulting lookup would let a phase added next year opt
- * itself out of a measured setting without anyone deciding to — which is exactly
- * how `/no_think` ended up applied to eight prompts and read by none of them.
+ * `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 `runWorker` / `focusedChildArgs` at a site with no name in scope, so
- * the group is passed directly. The four RESEARCH workers do have a name — their
- * `spec.label` — and so they are here.
+ * 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>>;
 /**
@@ -198,14 +141,10 @@ export declare function resolveReasoning(group: ReasoningGroup, cfg: PiTaskConfi
 /**
  * The WHOLE table, as this config will actually run it.
  *
- * This is the question every caller has — the settings menu when it repaints,
- * the mismatch warning when it scans, the custom-mode seeder when it freezes the
- * table — and each of them used to write the same loop over `resolveReasoning`.
- * A per-key accessor with no whole-table companion is also how a THIRD shape got
- * invented (`Array<{group, setting}>`) and leaked into `reasoningMismatches`.
- *
- * `resolveReasoning` stays: one group is still a fair question, and it is the
- * only place the four modes are interpreted.
+ * The question the mismatch scan and the custom-mode seeder both ask. One
+ * accessor, so they cannot each invent their own shape for it. The settings menu
+ * 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>;
 /**