@mjasnikovs/pi-task 0.38.19 → 0.38.21

package/dist/config/register.js

@@ -1,10 +1,11 @@
-import { SettingsList, visibleWidth, wrapTextWithAnsi } from '@earendil-works/pi-tui';
+import { getKeybindings, SettingsList, visibleWidth, wrapTextWithAnsi } from '@earendil-works/pi-tui';
 import { registerBridgeCommand } from '../remote/bridge.js';
 import { readPkgVersion } from '../shared/pkg-version.js';
 import { SEARCH_PROVIDERS, SEARCH_PROVIDER_LABELS, providerForLabel } from '../workers/search-types.js';
 import { COMMAND_TIMEOUT_OPTIONS, DEBUG_LOG_OPTIONS, getConfig, sanitizeDebugLogs, saveConfig, STREAM_INACTIVITY_OPTIONS } from './config.js';
 import { listInstalledExtensions } from './extension-list.js';
 import { listGuardableTools } from './tool-list.js';
+import { REASONING_GROUPS, REASONING_MODES, sanitizeReasoningMode, REASONING_GROUP_HELP, REASONING_SETTINGS, resolveReasoning } from './reasoning.js';
 // Version in the title so a bug report or screenshot says which build it came
 // from without anyone having to go look it up.
 const CONFIG_TITLE = `pi-task ${readPkgVersion()} settings`;
@@ -67,14 +68,58 @@ class BorderedBox {
         this.child.handleInput(data);
     }
 }
+/** Section order, and the label each header renders. */
+export const SECTIONS = [
+    { key: 'session', title: 'session' },
+    { key: 'checks', title: 'after each task' },
+    { key: 'research', title: 'research' },
+    { key: 'reasoning', title: 'reasoning' },
+    { key: 'unattended', title: 'unattended' },
+    { key: 'logging', title: 'logging' },
+    { key: 'extensions', title: 'child extensions' },
+    // Last on purpose. It is the longest block (a fixed timeout plus one row
+    // per live tool, so it grows with the host) and the least often changed —
+    // in front of `unattended` it pushed every short section off the screen.
+    { key: 'timeouts', title: 'timeouts' }
+];
+/** Marks a header row, so onChange can ignore one and tests can find them. */
+export const SECTION_ID_PREFIX = 'section:';
+/**
+ * An inert titled row. No `values` ⇒ SettingsList's Enter handler no-ops on it,
+ * and {@link SkipInertRows} steps the cursor straight over it.
+ *
+ * Upper case, and styled muted by {@link makeTheme}, because the dashed
+ * lower-case form it replaces was the same case, colour and weight as the
+ * setting labels underneath it — eight headings that read as nine more rows.
+ */
+function sectionHeader(title) {
+    return {
+        id: SECTION_ID_PREFIX + title,
+        label: title.toUpperCase(),
+        description: '',
+        currentValue: ''
+    };
+}
+/**
+ * A blank row between two sections.
+ *
+ * `SettingsList` renders exactly one line per item, so the only way to put air
+ * above a heading is to hand it an empty row. It carries the header prefix so
+ * everything that already treats a header as scenery — the inert check, the
+ * cursor skip, the headless rendering — covers it with no second rule.
+ */
+function sectionGap(title) {
+    return { id: `${SECTION_ID_PREFIX}gap:${title}`, label: '', description: '', currentValue: '' };
+}
 /**
  * The shared pair for a boolean setting: shown as on/off, stored as a boolean.
  * Every non-enum row uses this, so a boolean cannot be given a bespoke parser by
  * accident.
  */
-function booleanItem(id, label, description) {
+function booleanItem(section, id, label, description) {
     return {
         id,
+        section,
         label,
         description,
         format: cfg => (cfg[id] ? 'on' : 'off'),
@@ -92,27 +137,28 @@ function booleanItem(id, label, description) {
  * either of the two ladders this replaced.
  */
 export const ITEMS = [
-    booleanItem('remote', 'remote control', 'Serve the task UI on your local network so you can follow and steer a run from '
+    booleanItem('session', 'remote', 'remote control', 'Serve the task UI on your local network so you can follow and steer a run from '
         + 'your phone. Prints a QR code to scan when it starts'),
-    booleanItem('autoCommit', 'auto-commit', 'Make a git commit before and after every sub-task, so each step is a checkpoint '
+    booleanItem('checks', 'autoCommit', 'auto-commit', 'Make a git commit before and after every sub-task, so each step is a checkpoint '
         + 'you can read back or roll back to'),
-    booleanItem('verifyWork', 'verify work', 'When a task says it is done, actually run the checks its spec asks for and report '
+    booleanItem('checks', 'verifyWork', 'verify work', 'When a task says it is done, actually run the checks its spec asks for and report '
         + "PASS or FAIL instead of taking the model's word for it. This is also what lets "
         + '"enforce guidelines" fix things safely. /task waits for the work to finish'),
-    booleanItem('enforceGuidelines', 'enforce guidelines', 'Check what each task committed against your AGENTS.md / CLAUDE.md rules. With '
+    booleanItem('checks', 'enforceGuidelines', 'enforce guidelines', 'Check what each task committed against your AGENTS.md / CLAUDE.md rules. With '
         + '"verify work" on it also fixes what it finds, undoing any fix that breaks the '
         + 'checks; on its own it only reports. /task waits for the work to finish'),
-    booleanItem('orientation', 'project tour', 'Show the research workers the shape of the project first — package manifest, '
+    booleanItem('research', 'orientation', 'project tour', 'Show the research workers the shape of the project first — package manifest, '
         + 'types, schema — so they spend their steps on the question instead of on finding '
         + 'their way around'),
-    booleanItem('parallelResearchWorkers', 'parallel research', 'Run the 4 research workers at once instead of one after another. Only faster if '
+    booleanItem('research', 'parallelResearchWorkers', 'parallel research', 'Run the 4 research workers at once instead of one after another. Only faster if '
         + 'your model backend can answer several requests at the same time — on a single '
         + 'local GPU it is measurably slower, so leave it off there'),
-    booleanItem('researchCache', 'research cache', 'Remember docs and web pages for the length of one run, so later tasks reuse what '
+    booleanItem('research', 'researchCache', 'research cache', 'Remember docs and web pages for the length of one run, so later tasks reuse what '
         + 'the first one already fetched instead of downloading it again. Only external '
         + 'sources, only successful fetches, and it is dropped when the run ends'),
     {
         id: 'searchProvider',
+        section: 'research',
         label: 'search engine',
         description: 'Which engine backs web search. Exa and DuckDuckGo work with no setup; Brave needs '
             + 'a BRAVE_SEARCH_API_KEY in your environment',
@@ -127,6 +173,7 @@ export const ITEMS = [
     },
     {
         id: 'requestTimeoutMs',
+        section: 'timeouts',
         label: 'command timeout',
         description: 'Give up on any single command that runs this long, and tell the model to set its '
             + 'own timeout next time. Stops a run from waiting forever on a dev server or a '
@@ -144,6 +191,7 @@ export const ITEMS = [
     },
     {
         id: 'streamInactivityMs',
+        section: 'timeouts',
         label: 'stuck reply retry',
         description: 'Give up on a model reply that has sent nothing for this long and ask again. A '
             + 'dropped connection looks exactly like a model thinking hard and reports no '
@@ -160,12 +208,30 @@ export const ITEMS = [
                 cfg.streamInactivityMs = opt.ms;
         }
     },
-    booleanItem('yoloMode', 'yolo mode', 'Stop asking you anything: every question takes the option pi recommends, a failed '
+    booleanItem('unattended', 'yoloMode', 'yolo mode', 'Stop asking you anything: every question takes the option pi recommends, a failed '
         + 'check is accepted and written down as debt, and a failed final check is retried '
         + 'until the budget runs out. Each auto-answer is marked (YOLO) in the task file. '
         + 'For throwaway projects you are not watching'),
+    {
+        id: 'reasoningMode',
+        section: 'reasoning',
+        label: 'reasoning',
+        description: 'How much the helper sessions think before answering. "default" uses the '
+            + 'per-step table pi-task has measured, "on" and "off" force one answer '
+            + 'everywhere, and "custom" is whatever you set in the "think:" rows below. '
+            + 'Those rows always show what each step actually runs at, and changing one '
+            + 'switches this to custom. A step left on "inherit" uses whatever thinking '
+            + 'level pi itself is set to, which is what every step did before this setting '
+            + 'existed',
+        values: [...REASONING_MODES],
+        format: cfg => String(cfg.reasoningMode),
+        apply: (cfg, chosen) => {
+            cfg.reasoningMode = sanitizeReasoningMode(chosen);
+        }
+    },
     {
         id: 'debugLogs',
+        section: 'logging',
         label: 'debug logs',
         description: 'How much of a run gets written to .pi-tasks/*-debug.log. "events" keeps the '
             + 'decisions and the guard actions — what a checking step changed, why something '
@@ -233,10 +299,74 @@ export function applyToolToggle(exempt, toolName, watched) {
     const rest = exempt.filter(n => n !== toolName);
     return watched ? rest : [...rest, toolName];
 }
+/**
+ * One /task-config row per reasoning group, so a group's thinking level can be
+ * set without hand-editing config.json.
+ *
+ * SHOWN IN EVERY MODE, not only `custom`. Two reasons, and the second is the
+ * real one:
+ *  - `SettingsList` fixes the overlay's body height from the descriptions it was
+ *    constructed with (see createSettingsPanel), so rows that appear and vanish
+ *    would leave the box sized for the wrong list.
+ *  - The value displayed is what the group ACTUALLY runs at — resolveReasoning,
+ *    not the stored custom table. That makes the measured `default` table
+ *    readable from the menu instead of hidden in a source file, which is the
+ *    whole point of having measured it.
+ */
+const REASON_ID_PREFIX = 'reason:';
+export function reasoningItems(cfg) {
+    return REASONING_GROUPS.map(group => ({
+        id: REASON_ID_PREFIX + group,
+        label: `think: ${group}`,
+        description: REASONING_GROUP_HELP[group],
+        // The EFFECTIVE level, not cfg.reasoningLevels[group]: in default/on/off
+        // the stored table is not what runs, and a row that shows a value the
+        // run does not use is worse than no row.
+        currentValue: resolveReasoning(group, cfg),
+        values: [...REASONING_SETTINGS]
+    }));
+}
+/**
+ * Apply one group row's new value.
+ *
+ * Setting any group necessarily means "custom" — there is nowhere else to store
+ * a per-group choice. The seeding step is what stops that from being a trap: on
+ * the way out of `default`/`on`/`off` every OTHER group is first pinned to the
+ * level it was already running at, so changing one row changes one row. Without
+ * it, nudging `research` while in `off` would silently return the other six to
+ * whatever the stored table happened to hold.
+ */
+/**
+ * Write every `think:` row's displayed value back from the config.
+ *
+ * Called after ANY change, not just a reasoning one, because the mode row and
+ * the seven group rows are one control split across eight lines: cycling
+ * `reasoning` to `off` changes what all seven of them run at, and cycling one
+ * group row flips the mode, which changes the other six. A row showing a level
+ * the run will not use is worse than no row.
+ */
+export function refreshReasoningRows(cfg, list) {
+    for (const group of REASONING_GROUPS) {
+        list.updateValue(REASON_ID_PREFIX + group, resolveReasoning(group, cfg));
+    }
+    list.updateValue('reasoningMode', cfg.reasoningMode);
+}
+export function applyReasoningLevel(cfg, group, chosen) {
+    if (!REASONING_SETTINGS.includes(chosen))
+        return;
+    if (cfg.reasoningMode !== 'custom') {
+        const seeded = {};
+        for (const g of REASONING_GROUPS)
+            seeded[g] = resolveReasoning(g, cfg);
+        cfg.reasoningLevels = seeded;
+        cfg.reasoningMode = 'custom';
+    }
+    cfg.reasoningLevels = { ...cfg.reasoningLevels, [group]: chosen };
+}
 /** Overlay width; the list gets `- 4` of it, the description `- 4` again. */
 const OVERLAY_WIDTH = 68;
 /** Settings rows shown at once before the list scrolls. */
-const MAX_VISIBLE = 9;
+const MAX_VISIBLE = 11;
 /**
  * Tallest body the settings list can render, so {@link BorderedBox} can pad
  * every frame to it and hold the border still. Mirrors SettingsList's own
@@ -247,9 +377,19 @@ export function settingsBodyHeight(descriptions, maxVisible, wrapWidth) {
     const tallestDescription = Math.max(0, ...descriptions.map(d => wrapTextWithAnsi(d, wrapWidth).length));
     return 1 + maxVisible + 1 + 1 + tallestDescription + 1 + 1;
 }
-function makeTheme(theme) {
+function makeTheme(theme, isHeader) {
     return {
-        label: (text, selected) => selected ? theme.fg('accent', theme.bold(text)) : theme.fg('text', text),
+        label: (text, selected) => {
+            // Headers are scenery, so they are rendered quieter than the rows
+            // they title rather than louder. `isHeader` is asked by text
+            // because SettingsListTheme only ever sees the padded label —
+            // matching on the text is what keeps the styling in one place
+            // instead of pre-colouring the string back in panelItems, which
+            // has no theme to colour it with.
+            if (isHeader(text))
+                return theme.fg('muted', theme.bold(text));
+            return selected ? theme.fg('accent', theme.bold(text)) : theme.fg('text', text);
+        },
         // A filled/hollow dot makes the on/off column scannable at a glance
         // without reading a word on every row. Enum values (an engine name, a
         // duration) are real content, so they stay readable rather than muted.
@@ -267,34 +407,132 @@ function makeTheme(theme) {
         hint: text => theme.fg('dim', text)
     };
 }
+/** The arrow key SettingsList moves down on, under the default bindings. */
+const DOWN_KEY = '\x1b[B';
+/**
+ * Moves the cursor over the section headers and the blank rows between them.
+ *
+ * Those rows are decoration: they carry no `values`, so Enter already does
+ * nothing on them. Without this they were still stops on the way down — with a
+ * heading AND a blank line per section that is sixteen dead keypresses in a
+ * thirty-row menu, and the panel opens with the cursor parked on a heading that
+ * has no description to show.
+ *
+ * It drives the list through its own public `handleInput` — pressing the very
+ * key the user pressed, N times — rather than reaching for the private
+ * `selectedIndex`. The mirror it keeps cannot drift: with search off and no
+ * submenus, up and down are the only two things that move that index.
+ */
+class SkipInertRows {
+    list;
+    selectable;
+    index = 0;
+    constructor(list, 
+    /** True where a row can be selected, in the list's own order. */
+    selectable) {
+        this.list = list;
+        this.selectable = selectable;
+        // The first row is a header, so the panel would open on it. Only
+        // synthesise the keypress if it is actually bound to "down" — feeding
+        // a key the list ignores would move the mirror and not the cursor.
+        if (!getKeybindings().matches(DOWN_KEY, 'tui.select.down'))
+            return;
+        while (this.index < selectable.length && !selectable[this.index]) {
+            this.list.handleInput(DOWN_KEY);
+            this.index++;
+        }
+    }
+    render(width) {
+        return this.list.render(width);
+    }
+    invalidate() {
+        this.list.invalidate();
+    }
+    handleInput(data) {
+        const kb = getKeybindings();
+        const step = kb.matches(data, 'tui.select.down') ? 1
+            : kb.matches(data, 'tui.select.up') ? -1
+                : 0;
+        if (step === 0) {
+            this.list.handleInput(data);
+            return;
+        }
+        const n = this.selectable.length;
+        let target = this.index;
+        for (let moved = 1; moved <= n; moved++) {
+            target = (target + step + n) % n;
+            if (this.selectable[target]) {
+                for (let i = 0; i < moved; i++)
+                    this.list.handleInput(data);
+                this.index = target;
+                return;
+            }
+        }
+        // Every row is scenery. Nothing to select, so nothing to move.
+    }
+}
 /**
  * Builds the framed settings panel. Split out of the command handler so the
  * exact component the overlay shows can be rendered to a string in a test or a
  * preview script, rather than only being inspectable by opening the TUI.
  */
-export function createSettingsPanel(items, theme, onChange, onCancel) {
-    const list = new SettingsList(items, MAX_VISIBLE, makeTheme(theme), onChange, onCancel);
-    return new BorderedBox(list, CONFIG_TITLE, s => theme.fg('borderMuted', s), s => theme.fg('accent', theme.bold(s)), settingsBodyHeight(items.map(i => i.description), MAX_VISIBLE, OVERLAY_WIDTH - 8));
+export function createSettingsPanel(items, theme, 
+/**
+ * Called with the row's id, its new value, and the LIST ITSELF.
+ *
+ * The list is handed back because some rows change what OTHER rows display:
+ * flipping `reasoning` to off means all seven `think:` rows now run at off,
+ * and a row's `currentValue` is a snapshot taken when the panel was built.
+ * Without a way to write the others back, the menu shows `reasoning off`
+ * beside seven rows still claiming `inherit` — which is what it did.
+ */
+onChange, onCancel) {
+    // A row with no `values` is a header or the blank line above one.
+    const headerLabels = new Set(items.filter(i => i.values === undefined).map(i => i.label));
+    const list = new SettingsList(items, MAX_VISIBLE, makeTheme(theme, label => headerLabels.has(label.trimEnd())), (id, newValue) => onChange(id, newValue, list), onCancel);
+    return new BorderedBox(new SkipInertRows(list, items.map(i => (i.values?.length ?? 0) > 0)), CONFIG_TITLE, s => theme.fg('borderMuted', s), s => theme.fg('accent', theme.bold(s)), settingsBodyHeight(items.map(i => i.description), MAX_VISIBLE, OVERLAY_WIDTH - 8));
 }
 /** The full settings row list for the current config, in menu order. */
 export function panelItems(cfg, installed, tools = []) {
-    return [
-        ...ITEMS.map(({ id, label, description, values, format }) => ({
-            id: id,
-            label,
-            description,
-            currentValue: format(cfg),
-            values: values ?? ['on', 'off']
-        })),
-        ...toolItems(tools, cfg.commandTimeoutExemptTools),
-        ...extensionItems(installed, cfg.extensionWhitelist)
-    ];
+    // The discovered rows belong to a section too — the per-tool watchdog
+    // exemptions under `timeouts` (they are exemptions FROM that timeout), and
+    // the per-extension toggles under their own heading.
+    const extra = {
+        reasoning: reasoningItems(cfg),
+        timeouts: toolItems(tools, cfg.commandTimeoutExemptTools),
+        extensions: extensionItems(installed, cfg.extensionWhitelist)
+    };
+    const out = [];
+    for (const { key, title } of SECTIONS) {
+        const rows = [
+            ...ITEMS.filter(i => i.section === key).map(({ id, label, description, values, format }) => ({
+                id: id,
+                label,
+                description,
+                currentValue: format(cfg),
+                values: values ?? ['on', 'off']
+            })),
+            ...(extra[key] ?? [])
+        ];
+        // An empty section prints no header. `extensions` has no fixed rows at
+        // all, so with nothing installed the heading would otherwise sit alone.
+        if (rows.length === 0)
+            continue;
+        if (out.length > 0)
+            out.push(sectionGap(title));
+        out.push(sectionHeader(title), ...rows);
+    }
+    return out;
 }
 async function handleTaskConfig(_args, ctx, getTools = () => []) {
     const cfg = {
         ...getConfig(),
         extensionWhitelist: [...getConfig().extensionWhitelist],
-        commandTimeoutExemptTools: [...getConfig().commandTimeoutExemptTools]
+        commandTimeoutExemptTools: [...getConfig().commandTimeoutExemptTools],
+        // Copied for the same reason as the two arrays above: the panel mutates
+        // its own draft, and sharing the live object would apply half-made
+        // choices to running children before the user finished choosing.
+        reasoningLevels: { ...getConfig().reasoningLevels }
     };
     // Enumerated live at open so an installed extension appears and an
     // uninstalled one vanishes without pi-task doing any bookkeeping. A failed
@@ -307,22 +545,31 @@ async function handleTaskConfig(_args, ctx, getTools = () => []) {
     if (ctx.mode !== 'tui') {
         // Reads the SAME `format` the panel does, so the two renderings cannot
         // disagree about what a setting currently says.
-        const lines = ITEMS.map(({ label, format }) => `${label.padEnd(22)} ${format(cfg)}`);
-        for (const t of tools) {
-            const state = cfg.commandTimeoutExemptTools.includes(t.name) ? 'off' : 'on';
-            lines.push(`${('watch: ' + t.name).padEnd(22)} ${state}`);
-        }
-        for (const e of installed) {
-            const state = cfg.extensionWhitelist.includes(e.path) ? 'on' : 'off';
-            lines.push(`${('ext: ' + e.label).padEnd(22)} ${state}`);
-        }
+        // Built from panelItems, not a second hand-written walk of the same
+        // tables: the two renderings used to be able to disagree about what a
+        // setting said, and a headless run is the one place nobody would notice.
+        const lines = panelItems(cfg, installed, tools)
+            // The blank rows between sections are there to give the TUI air.
+            // One line of `|`-joined text has none to give, and an empty label
+            // would print as a stray `[]`.
+            .filter(i => i.label !== '')
+            .map(i => i.values === undefined ?
+            `[${i.label.trim()}]`
+            : `${i.label.padEnd(22)} ${i.currentValue}`);
         ctx.ui.notify(lines.join('  |  '), 'info');
         return;
     }
-    await ctx.ui.custom((_tui, theme, _kb, done) => createSettingsPanel(panelItems(cfg, installed, tools), theme, (id, newValue) => {
+    await ctx.ui.custom((_tui, theme, _kb, done) => createSettingsPanel(panelItems(cfg, installed, tools), theme, (id, newValue, list) => {
+        // Header rows carry no `values`, so SettingsList never
+        // cycles them and this can only be a real setting.
+        if (id.startsWith(SECTION_ID_PREFIX))
+            return;
         if (id.startsWith(EXT_ID_PREFIX)) {
             cfg.extensionWhitelist = applyExtensionToggle(cfg.extensionWhitelist, id.slice(EXT_ID_PREFIX.length), newValue === 'on');
         }
+        else if (id.startsWith(REASON_ID_PREFIX)) {
+            applyReasoningLevel(cfg, id.slice(REASON_ID_PREFIX.length), newValue);
+        }
         else if (id.startsWith(TOOL_ID_PREFIX)) {
             cfg.commandTimeoutExemptTools = applyToolToggle(cfg.commandTimeoutExemptTools, id.slice(TOOL_ID_PREFIX.length), newValue === 'on');
         }
@@ -334,6 +581,12 @@ async function handleTaskConfig(_args, ctx, getTools = () => []) {
             // until someone noticed.
             ITEMS.find(item => item.id === id)?.apply(cfg, newValue);
         }
+        // The reasoning rows describe each other, so they are
+        // re-read from the config after every change — including
+        // changes to unrelated rows, which costs nothing and means
+        // there is no list of "changes that need a refresh" to keep
+        // correct.
+        refreshReasoningRows(cfg, list);
         saveConfig(cfg).catch(() => { });
     }, () => done(undefined)), { overlay: true, overlayOptions: { width: OVERLAY_WIDTH } });
 }

package/dist/shared/model-endpoint.d.ts

@@ -6,3 +6,37 @@ export declare function discoverModelEndpoints(agentDir?: string): string[];
  * timeout. An empty list is true: nothing to probe means never kill.
  */
 export declare function probeModelEndpoints(urls: string[], timeoutMs?: number): Promise<boolean>;
+/**
+ * What a llama.cpp server's own chat template can actually do about reasoning,
+ * as reported by `GET /props`.
+ *
+ * This is the only source of truth that does NOT come from models.json. It
+ * answers the one question the host-side clamp cannot: *is models.json lying
+ * about the server?* — the case that matters being pi's built-in llama.cpp
+ * provider, which hardcodes `reasoning: false`, so anyone who reached their
+ * server through `/login llama.cpp` rather than a hand-written provider entry
+ * has a dead knob and nothing to tell them so.
+ */
+export interface ChatTemplateCaps {
+    /** The template reads `reasoning_effort` — i.e. levels, not just on/off. */
+    supportsReasoningEffort: boolean;
+    /** The template reads `preserve_thinking` / `preserve_reasoning`. */
+    supportsPreserveReasoning: boolean;
+    /** The template mentions `enable_thinking` at all — i.e. thinking can be switched. */
+    mentionsEnableThinking: boolean;
+}
+/**
+ * Probe one base URL for its chat-template capabilities, or `null` for "no
+ * answer worth having" — not a llama.cpp server, unreachable, or a body in a
+ * shape this does not recognise.
+ *
+ * `null` is a first-class result, not an error: every non-llama.cpp backend
+ * returns it, and the caller must degrade to the models.json view rather than
+ * warn about a server it could not read. Never throws.
+ *
+ * The LEADING SLASH in `/props` is load-bearing. A configured baseUrl normally
+ * ends in `/v1` (llama-server's OpenAI-compatible prefix) while `/props` lives at
+ * the server root, so a relative `'props'` would resolve to `/v1/props` and 404 —
+ * which this would report as `null`, i.e. as a silent loss of the better signal.
+ */
+export declare function probeChatTemplateCaps(baseUrl: string, timeoutMs?: number): Promise<ChatTemplateCaps | null>;

package/dist/shared/model-endpoint.js

@@ -54,3 +54,39 @@ export async function probeModelEndpoints(urls, timeoutMs = 5_000) {
     }));
     return results.some(Boolean);
 }
+/**
+ * Probe one base URL for its chat-template capabilities, or `null` for "no
+ * answer worth having" — not a llama.cpp server, unreachable, or a body in a
+ * shape this does not recognise.
+ *
+ * `null` is a first-class result, not an error: every non-llama.cpp backend
+ * returns it, and the caller must degrade to the models.json view rather than
+ * warn about a server it could not read. Never throws.
+ *
+ * The LEADING SLASH in `/props` is load-bearing. A configured baseUrl normally
+ * ends in `/v1` (llama-server's OpenAI-compatible prefix) while `/props` lives at
+ * the server root, so a relative `'props'` would resolve to `/v1/props` and 404 —
+ * which this would report as `null`, i.e. as a silent loss of the better signal.
+ */
+export async function probeChatTemplateCaps(baseUrl, timeoutMs = 2_000) {
+    try {
+        const res = await fetch(new URL('/props', baseUrl), {
+            signal: AbortSignal.timeout(timeoutMs)
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        const caps = body.chat_template_caps;
+        if (typeof caps !== 'object' || caps === null)
+            return null;
+        const template = typeof body.chat_template === 'string' ? body.chat_template : '';
+        return {
+            supportsReasoningEffort: caps.supports_reasoning_effort === true,
+            supportsPreserveReasoning: caps.supports_preserve_reasoning === true,
+            mentionsEnableThinking: template.includes('enable_thinking')
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/shared/reasoning-capability.d.ts

@@ -0,0 +1,86 @@
+/**
+ * What pi will ACTUALLY send, given a model and a requested thinking level.
+ *
+ * WHY A LOCAL COPY OF PI'S CLAMP
+ * ------------------------------
+ * pi never reports that it ignored or downgraded a level. Measured live against
+ * this machine's llama-server, with a proxy capturing the request body:
+ *
+ *   1. a model with `reasoning: false` + `--thinking medium`
+ *        → the body carries NO reasoning field at all. No error, no warning.
+ *   2. `thinkingLevelMap: {off: null, ...}` + `--thinking off`
+ *        → silently clamped UP to `medium`. Thinking stays on.
+ *   3. `--thinking low` where `low: null`
+ *        → silently clamped to `medium`.
+ *
+ * All three are the same arithmetic, and it is pure: `getSupportedThinkingLevels`
+ * / `clampThinkingLevel` in @earendil-works/pi-ai's models module. Reproducing it
+ * lets one predicate — `clampToModel(m, wanted) !== wanted` — catch all three
+ * host-side, before a single request is sent.
+ *
+ * Reimplemented rather than imported because `@earendil-works/pi-ai` is neither a
+ * dependency nor a peerDependency of pi-task: it is present only because
+ * pi-coding-agent hoists it, so importing it would take a hard dependency on a
+ * transitive package to get twenty lines of arithmetic. SOURCE OF TRUTH is that
+ * module; `reasoning-capability.test.ts` is where a change upstream shows up.
+ */
+import type { ReasoningGroup, GroupSetting } from '../config/reasoning.js';
+/**
+ * pi's own level ladder, in order. The order is the whole algorithm: an
+ * unsupported level is resolved by walking UP first, then down.
+ */
+export declare const THINKING_LADDER: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+export type LadderLevel = (typeof THINKING_LADDER)[number];
+/**
+ * The two fields of pi's `Model` that decide reasoning behaviour. Named
+ * separately so the pure functions below can be tested with object literals
+ * instead of a whole model registry.
+ */
+export interface ReasoningModelFacts {
+    reasoning: boolean;
+    thinkingLevelMap?: Partial<Record<string, string | null>>;
+}
+/**
+ * The levels this model will actually honour.
+ *
+ * Two rules that are easy to get backwards:
+ *  - `reasoning: false` collapses everything to `['off']`. That is failure mode
+ *    1: the knob is not rejected, it is erased.
+ *  - a MISSING map entry means "supported" for the standard levels but
+ *    "unsupported" for `xhigh` / `max`, which are opt-in and must be declared.
+ *    This is why config/reasoning.ts does not offer those two: a model with no
+ *    map at all would receive the raw string, and Qwen3.8's chat template
+ *    answers an unknown effort with HTTP 500 rather than a clamp.
+ */
+export declare function supportedThinkingLevels(model: ReasoningModelFacts): LadderLevel[];
+/**
+ * The level pi will use in place of the one asked for. Equal to the input when
+ * the model supports it — which is what makes the inequality a mismatch test.
+ */
+export declare function clampToModel(model: ReasoningModelFacts, level: LadderLevel): LadderLevel;
+/** One group whose configured setting the connected model will not honour. */
+export interface ReasoningMismatch {
+    group: ReasoningGroup;
+    /** What /task-config says. Never `inherit` — an inherited group asks for nothing. */
+    wanted: LadderLevel;
+    /** What pi will send instead. */
+    actual: LadderLevel;
+}
+/**
+ * Every group whose setting the model will silently change.
+ *
+ * `inherit` groups are skipped entirely, and that is what keeps a default
+ * install permanently quiet: with the shipped all-`inherit` table this returns
+ * an empty array for every model, including one with no reasoning at all.
+ *
+ * It reports mismatches in BOTH directions, which is wider than "warn when
+ * reasoning is on but unsupported". The failure actually captured on this
+ * machine is the mirror of that — `off` clamped UP to `medium`, so a user who
+ * turned thinking off still pays for it — and it is the same comparison. Warning
+ * about one direction while staying silent about the other would ship this
+ * feature with its own measured failure mode unreported.
+ */
+export declare function reasoningMismatches(model: ReasoningModelFacts | undefined, settings: ReadonlyArray<{
+    group: ReasoningGroup;
+    setting: GroupSetting;
+}>): ReasoningMismatch[];