@mjasnikovs/pi-task 0.38.19 → 0.38.20

package/README.md

@@ -214,6 +214,7 @@ Run `/task-config` to toggle pi-task's behavior in an editor dialog. Settings pe
 | **command timeout** | 15 min | Wall-clock ceiling on a **single** tool execution. Local models routinely run a command that never returns (a hung build, a dev server, a check with no timeout) and the run wedges until you abort by hand — pi's bash tool has an optional timeout with no default, so this is the missing one. One knob, two surfaces: in the main session the overrun call is cancelled (killing the tool's whole process tree) plus a reminder turn; in the verify/fix gate children the child is killed and re-spawned with a hint, halving the ceiling on repeat hangs. Choices: 5/10/15/30 min or **off** — off unguards both surfaces, gates included. |
 | **stuck reply retry** | 10 min | Inactivity ceiling on the **model stream**. A hung or silently-dropped stream throws nothing at all, so neither the connection-error retry (it needs a reported error) nor the **command timeout** (tool calls only) nor the dead-backend stall guard (a reachable endpoint reads as proof of life) can see it — an mx5 run lost ~2.9h to three of them while the model server stayed healthy. Measured as time since the **last stream event of any kind**, so a slow model emitting one token every 30s is never touched, and it pauses while a tool runs. On expiry the main session aborts the turn (through the same channel the command watchdog uses) and posts a resume reminder; a child is killed and routed into the existing connection-error retry. Choices: 5/10/20/30 min or **off**. Keep it generous on local backends — prompt processing on a large context legitimately emits nothing for minutes. |
 | **yolo mode** | off | **Unattended runs.** Wherever pi-task would stop and ask, it takes the option already marked RECOMMENDED, stamps the artifact `(YOLO)` so an audit can tell a machine decided, and shows no prompt at all — clarify/grill answers, the verify-FAIL picker (auto-**Accept**, recorded as a yolo debt), and the final-gate picker (autofix while the budget lasts, then leave the run FAILED). A question with no recommendation is **skipped**, never invented. For throwaway/test projects nobody is watching; a real run should decide these itself. |
+| **reasoning** | default | How much the helper sessions think before answering. Local models differ sharply here: some break without reasoning, some waste minutes with it, and some cannot do it at all. The seven **think:** rows below set one level per group of steps — research workers, spec phases, /task-auto planning, /task-plan, the checking gates, the small extraction children, and the implementation turn itself. **default** uses the table pi-task has measured, **on** and **off** force one answer everywhere, and **custom** is whatever the think: rows say (changing any of them switches to custom). A step on **inherit** passes no flag at all, so it uses whatever thinking level pi itself is set to — which is what every step did before this setting existed, and is what every cell of the measured table currently holds. The think: rows always show what a step *actually* runs at, not what the stored table says. Three tiers of model exist and pi-task tells them apart: full levels (`reasoning_effort` in the chat template, e.g. Qwen3.8), on/off only (e.g. Qwen3.6, Gemma 4), and none at all. pi silently CLAMPS a level a model does not declare — a level you set can be erased, and an `off` can be clamped back up to `medium` — so a startup warning names the model and the steps it will not honour. It never fires while every step is on inherit. |
 | **debug logs** | events | How much of a run is written to `.pi-tasks/*-debug.log`. **`events`** keeps decisions and guard actions — which phase ran, why a worker was retried, what the git-state guard restored, what a write-capable child changed on disk, why a gate returned FAIL — a few lines per task. **`full`** adds every line the child model emitted and every tool result; that's ~85% of the bytes (a real 247 KB `verify-debug.log` is 1315 lines, 521 of them tool dumps) and is what you want while actively debugging. **`off`** writes nothing. Nothing in pi-task ever reads these files back, so the setting cannot change how a run behaves — only whether you can explain it afterwards, and a log not written can't be recovered later. |
 | **watch: …** | all on | One toggle per tool in the live session, deciding whether **command timeout** applies to it. The list is discovered from `pi.getAllTools()` when the menu opens — built-ins first, then each extension's tools with the owning entry-point path in the description — so nothing is typed by hand and an uninstalled tool just stops being listed. Turn one **off** only for a tool that already owns a longer bounded, cancellable contract of its own (the guard exists because pi's `bash` has an optional timeout with *no* default — that reasoning doesn't transfer to a tool that has one). Two things to know before you do: a genuine hang in an unwatched tool is caught by nothing, since **stuck reply retry** is paused for the whole time any tool runs; and an unwatched tool is still killed as collateral if a *watched* sibling in the same turn overruns, because pi runs sibling tool calls concurrently and the abort ends the whole turn. Stored as exemptions, so the default and every tool pi-task has never seen stay guarded. |
 | **ext: …** | all off | One toggle per installed host `pi` extension, loading it into every child session by explicit path. Children otherwise run with extensions off, so a provider registered by an extension (e.g. `pi-lmstudio`) doesn't exist in them and they can't resolve the default model. Children also inherit the extension's tools and hooks, so only enable ones you trust. The list is strictly additive (discovery stays off), and an entry whose file is gone is skipped at spawn time, never fatal. |

package/dist/config/config.d.ts

@@ -1,4 +1,5 @@
 import { type SearchProvider } from '../workers/search-types.js';
+import { type GroupSetting, type ReasoningGroup, type ReasoningMode } from './reasoning.js';
 export interface PiTaskConfig {
     remote: boolean;
     autoCommit: boolean;
@@ -134,6 +135,24 @@ export interface PiTaskConfig {
      * cannot be recovered after the fact.
      */
     debugLogs: DebugLogLevel;
+    /**
+     * Which reasoning profile is in force. See config/reasoning.ts for the four
+     * modes and the group vocabulary.
+     *
+     * DEFAULT `default`, whose table ships all-`inherit` — so installing this
+     * version changes no child's argv until the user opts in.
+     */
+    reasoningMode: ReasoningMode;
+    /**
+     * The per-group thinking levels, consulted ONLY when
+     * `reasoningMode === 'custom'`.
+     *
+     * Kept populated in every mode so switching to `custom` and back does not
+     * lose the user's table — the same reason `commandTimeoutExemptTools`
+     * survives the watchdog being turned off. Its sanitizer always returns a
+     * complete record, so no consumer needs a per-key fallback.
+     */
+    reasoningLevels: Record<ReasoningGroup, GroupSetting>;
 }
 /** How verbose the `.pi-tasks/*-debug.log` trail is. See {@link PiTaskConfig.debugLogs}. */
 export type DebugLogLevel = 'off' | 'events' | 'full';

package/dist/config/config.js

@@ -3,6 +3,7 @@ import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import { isSearchProvider } from '../workers/search-types.js';
+import { DEFAULT_REASONING_TABLE, sanitizeReasoningLevels, sanitizeReasoningMode } from './reasoning.js';
 import { DEFAULT_STREAM_INACTIVITY_MS } from '../shared/stream-watchdog.js';
 /**
  * The debug-log choices offered by /task-config, in cycle order (quietest →
@@ -104,7 +105,12 @@ export const DEFAULT_CONFIG = {
     yoloMode: false,
     // EVENTS: the model chatter is 85% of the bytes and nobody reads it; the
     // guard/verdict markers are the 15% that explains a failed run.
-    debugLogs: DEFAULT_DEBUG_LOGS
+    debugLogs: DEFAULT_DEBUG_LOGS,
+    // DEFAULT: the measured per-group table, which currently holds `inherit` in
+    // every cell. Every child's argv is byte-identical to the version before
+    // reasoning profiles existed until a cell is filled in by an A/B.
+    reasoningMode: 'default',
+    reasoningLevels: { ...DEFAULT_REASONING_TABLE }
 };
 /**
  * A hand-edited config can hold anything; keep only string entries so a stray
@@ -155,7 +161,9 @@ export const CONFIG_LOADERS = {
     requestTimeoutMs: sanitizeRequestTimeoutMs,
     commandTimeoutExemptTools: sanitizeCommandTimeoutExemptTools,
     streamInactivityMs: sanitizeStreamInactivityMs,
-    debugLogs: sanitizeDebugLogs
+    debugLogs: sanitizeDebugLogs,
+    reasoningMode: sanitizeReasoningMode,
+    reasoningLevels: sanitizeReasoningLevels
 };
 /**
  * Turn parsed config JSON into a `PiTaskConfig`. Pure — this is the seam the load

package/dist/config/reasoning-args.d.ts

@@ -0,0 +1,10 @@
+import { type ReasoningGroup } from './reasoning.js';
+/**
+ * The `['--thinking', level]` fragment for a group, or `[]` when the group is
+ * `inherit` and the child should keep falling back to settings.json.
+ *
+ * This is the ONLY function the argv builders call. They never read config
+ * themselves — an argv builder that resolves its own policy is one that cannot
+ * be told to do something else, which is how childBaseArgs became universal.
+ */
+export declare function groupThinkingArgs(group: ReasoningGroup): string[];

package/dist/config/reasoning-args.js

@@ -0,0 +1,23 @@
+/**
+ * The live-config bridge for reasoning profiles: group in, argv fragment out.
+ *
+ * Separate from reasoning.ts because that module must stay import-free — see its
+ * header. This file is the one hop that reads `getConfig()`, so it imports both
+ * and neither imports it back: a tree, not a cycle.
+ *
+ * Read PER CALL, never cached at module scope, so a /task-config change lands on
+ * the next child without a restart — the same contract childBaseArgs states.
+ */
+import { getConfig } from './config.js';
+import { resolveReasoning, thinkingArgs } from './reasoning.js';
+/**
+ * The `['--thinking', level]` fragment for a group, or `[]` when the group is
+ * `inherit` and the child should keep falling back to settings.json.
+ *
+ * This is the ONLY function the argv builders call. They never read config
+ * themselves — an argv builder that resolves its own policy is one that cannot
+ * be told to do something else, which is how childBaseArgs became universal.
+ */
+export function groupThinkingArgs(group) {
+    return thinkingArgs(resolveReasoning(group, getConfig()));
+}

package/dist/config/reasoning.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Reasoning profiles — which thinking level each group of model children runs at.
+ *
+ * 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.
+ *
+ * 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
+ * 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';
+/**
+ * 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 two that reach the model by different code paths (`refine` via
+ * runPhaseChild, `compress-label` via the same) want the same.
+ *
+ * - `research`     the four research workers, plus the ad-hoc `pi-worker` tool
+ * - `phase`        refine, verify-tooling, grill, compose, critique, compress-label
+ * - `planning`     /task-auto's clarify / decompose / extract children
+ * - `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)
+ */
+export type ReasoningGroup = 'research' | 'phase' | 'planning' | 'plan' | 'gate' | 'extraction' | 'implementation';
+export declare const REASONING_GROUPS: readonly ReasoningGroup[];
+/**
+ * The four profiles offered by /task-config.
+ * - `default` the measured per-group table below
+ * - `on`      one level everywhere ({@link REASONING_ON_LEVEL})
+ * - `off`     no thinking anywhere
+ * - `custom`  the user's own per-group table
+ */
+export type ReasoningMode = 'default' | 'on' | 'off' | 'custom';
+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.
+ */
+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).
+ *
+ * `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.
+ */
+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.
+ */
+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`.
+ */
+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.
+ */
+export declare function sanitizeReasoningMode(value: unknown): ReasoningMode;
+/**
+ * Always returns a COMPLETE record, never a partial one.
+ *
+ * A hand-edited file missing a group, or one carrying a group from a future
+ * version, must not reach `resolveReasoning` as a hole: `levels[group]` would be
+ * `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>;
+/**
+ * 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.
+ */
+export declare function resolveReasoning(group: ReasoningGroup, cfg: PiTaskConfig): 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>>;