@mjasnikovs/pi-task 0.38.23 → 0.38.25

package/dist/task/question-dialog.d.ts

@@ -29,6 +29,7 @@
  * actions. Those genuinely differ.
  */
 import type { AnswerSource } from './plan-io.js';
+import type { YoloPick } from './yolo.js';
 /** One question awaiting an answer, in both the stored and the displayed form. */
 export interface PendingQuestion {
     /** Plain text — persisted, and fed back to the model. */
@@ -69,3 +70,58 @@ export declare function resolveAnswer(p: PendingQuestion, raw: string): {
     answer: string;
     source: AnswerSource;
 };
+/**
+ * Everything one adaptive dialog needs to settle ONE question.
+ *
+ * `ui.ask` is typed structurally rather than as `SessionUI` so this module stays
+ * out of the remote bridge's import graph — the only thing it needs is the ask.
+ */
+export interface SettleQuestionInput {
+    ui: {
+        ask: (spec: {
+            localTitle: string;
+            displayQuestion: string;
+            question: string;
+            recommended?: string;
+            recommended2?: string;
+            allowSkip: boolean;
+            options?: Array<{
+                label: string;
+                value: string;
+            }>;
+        }) => Promise<string | undefined>;
+    };
+    /** Where the settled answer is recorded. */
+    transcript: {
+        add: (kind: SettledKind, question: string, answer: string) => void;
+    };
+    /** The question, plain (persisted / fed back) and rendered (displayed). */
+    plain: string;
+    shown: string;
+    /** The recommendation and the alternative, as the model wrote them (markdown). */
+    suggested?: string;
+    alt?: string;
+    /** Render inline markdown for display. */
+    render: (md: string) => string;
+    /**
+     * This site's already-decided YOLO outcome. A PARAMETER, not a hook: yolo.ts
+     * states why the policy is per-site (grill has an anti-synthesis channel to
+     * step aside from, clarify runs before research and has none), and settling a
+     * question must not become the place that decides one.
+     */
+    yolo: YoloPick;
+    /** Run just before the ask — grill's "awaiting Qn" widget line. */
+    onAsk?: () => void;
+}
+/** The provenance kinds settling one question can produce. */
+export type SettledKind = 'yolo' | 'yolo-skip' | 'accepted' | 'typed';
+/**
+ * Settle one question: YOLO short-circuit, cards, ask, record.
+ *
+ * Returns `'cancelled'` rather than throwing, because that is the one thing the
+ * two callers genuinely disagree about — grill throws `USER_CANCELLED` into the
+ * phase ladder, clarify announces and returns null from the plan. Everything
+ * before it was written out twice at ~50 lines each and had already drifted on
+ * `recommended2`, harmless today only because the bridge re-guards it.
+ */
+export declare function settleQuestion(input: SettleQuestionInput): Promise<'settled' | 'cancelled'>;

package/dist/task/question-dialog.js

@@ -28,6 +28,7 @@
  * widget line, clarify's plan-shape and triage pre-emption, plan's control
  * actions. Those genuinely differ.
  */
+import { stripInlineMarkdown } from './inline-markdown.js';
 /** True when the question is a binary fork rather than a single recommendation. */
 export function isTwoOption(p) {
     return p.suggested !== undefined && p.alt !== undefined;
@@ -87,3 +88,55 @@ export function resolveAnswer(p, raw) {
     }
     return { answer: typed, source: 'typed' };
 }
+/**
+ * Settle one question: YOLO short-circuit, cards, ask, record.
+ *
+ * Returns `'cancelled'` rather than throwing, because that is the one thing the
+ * two callers genuinely disagree about — grill throws `USER_CANCELLED` into the
+ * phase ladder, clarify announces and returns null from the plan. Everything
+ * before it was written out twice at ~50 lines each and had already drifted on
+ * `recommended2`, harmless today only because the bridge re-guards it.
+ */
+export async function settleQuestion(input) {
+    const { ui, transcript, plain, shown, render, yolo } = input;
+    const plainSuggested = input.suggested === undefined ? undefined : stripInlineMarkdown(input.suggested);
+    const plainAlt = input.alt === undefined ? undefined : stripInlineMarkdown(input.alt);
+    if (yolo !== null) {
+        // The stamp is a RECORD fact, and which kinds are stamped is the
+        // transcript policy's call — never this call site's.
+        if (yolo.kind === 'answer') {
+            transcript.add('yolo', plain, stripInlineMarkdown(yolo.answer));
+        }
+        else {
+            transcript.add('yolo-skip', plain, `(skipped — ${yolo.note})`);
+        }
+        return 'settled';
+    }
+    const pending = {
+        plain,
+        shown,
+        ...(plainSuggested !== undefined && {
+            suggested: plainSuggested,
+            shownSuggested: render(input.suggested)
+        }),
+        ...(plainAlt !== undefined && { alt: plainAlt, shownAlt: render(input.alt) })
+    };
+    const options = buildOptionCards(pending);
+    input.onAsk?.();
+    const a = await ui.ask({
+        localTitle: shown,
+        displayQuestion: shown,
+        question: plain,
+        recommended: plainSuggested,
+        ...(plainAlt !== undefined && { recommended2: plainAlt }),
+        allowSkip: plainSuggested === undefined && plainAlt === undefined,
+        ...(options && { options })
+    });
+    if (a === undefined)
+        return 'cancelled';
+    // An accept covers both routes to it: submitting empty, and pressing the
+    // single green card.
+    const resolved = resolveAnswer(pending, a);
+    transcript.add(resolved.source === 'accepted' ? 'accepted' : 'typed', plain, resolved.answer);
+    return 'settled';
+}

package/dist/task/research-fanout-budget.d.ts

@@ -81,6 +81,26 @@ export declare const WORKER_CARRY_FORWARD_ENV = "PI_TASK_WORKER_CARRY_FORWARD";
 /** RESCUE: deadline on lack of progress instead of elapsed time. Value = absolute ceiling, ms. */
 export declare const WORKER_PROGRESS_CEILING_ENV = "PI_TASK_WORKER_PROGRESS_CEILING_MS";
 type Env = (key: string) => string | undefined;
+/**
+ * Every lever env var this module owns.
+ *
+ * Exists so `snapshotLeverEnv` cannot drift from the levers: adding a lever
+ * without adding it here would leave that one lever read LATE, which is the
+ * half-applied arm the snapshot exists to prevent.
+ */
+export declare const RESEARCH_LEVER_ENVS: readonly string[];
+/**
+ * The levers, read ONCE, as a reader the profile table can be handed.
+ *
+ * WHY A SNAPSHOT AND NOT `process.env`. Every worker in one research phase must
+ * see the same arm. The three lever values used to be resolved once in
+ * `phases.ts` and threaded down as three separate `ResearchWorkerRun` fields for
+ * exactly that reason; moving the resolution into the `research` profile would
+ * have moved the READ down to each worker with it, and a harness that flips a
+ * var mid-phase would then half-apply its own arm. Freezing the reader keeps the
+ * read-once property while letting the profile own what the values MEAN.
+ */
+export declare function snapshotLeverEnv(env?: Env): Env;
 /**
  * The CAP arm's budget, or null when the lever is off (the shipped default).
  * A non-numeric or non-positive value is off too: a typo'd env var must not

package/dist/task/research-fanout-budget.js

@@ -81,6 +81,35 @@ export const WORKER_CARRY_FORWARD_ENV = 'PI_TASK_WORKER_CARRY_FORWARD';
 /** RESCUE: deadline on lack of progress instead of elapsed time. Value = absolute ceiling, ms. */
 export const WORKER_PROGRESS_CEILING_ENV = 'PI_TASK_WORKER_PROGRESS_CEILING_MS';
 const defaultEnv = key => process.env[key];
+/**
+ * Every lever env var this module owns.
+ *
+ * Exists so `snapshotLeverEnv` cannot drift from the levers: adding a lever
+ * without adding it here would leave that one lever read LATE, which is the
+ * half-applied arm the snapshot exists to prevent.
+ */
+export const RESEARCH_LEVER_ENVS = [
+    PROJECT_DOCS_BUDGET_ENV,
+    FANOUT_TIMEOUT_PER_LOOKUP_ENV,
+    FANOUT_TIMEOUT_CEILING_ENV,
+    WORKER_CARRY_FORWARD_ENV,
+    WORKER_PROGRESS_CEILING_ENV
+];
+/**
+ * The levers, read ONCE, as a reader the profile table can be handed.
+ *
+ * WHY A SNAPSHOT AND NOT `process.env`. Every worker in one research phase must
+ * see the same arm. The three lever values used to be resolved once in
+ * `phases.ts` and threaded down as three separate `ResearchWorkerRun` fields for
+ * exactly that reason; moving the resolution into the `research` profile would
+ * have moved the READ down to each worker with it, and a harness that flips a
+ * var mid-phase would then half-apply its own arm. Freezing the reader keeps the
+ * read-once property while letting the profile own what the values MEAN.
+ */
+export function snapshotLeverEnv(env = defaultEnv) {
+    const snap = new Map(RESEARCH_LEVER_ENVS.map(k => [k, env(k)]));
+    return key => snap.get(key);
+}
 function positiveInt(raw) {
     if (raw === undefined)
         return null;

package/dist/task/research-worker.d.ts

@@ -0,0 +1,183 @@
+/**
+ * ONE research worker, cache-skip to persist.
+ *
+ * WHY IT IS A MODULE. This was a 228-line closure inside `phaseResearch` over
+ * eleven locals, and inside it live the three RETRY GATES and their precedence:
+ * the EMPTY-SECTION gate (the only one that can fail the phase), the
+ * ZERO-RETRIEVAL gate and the SILENT gate (both of which discard a failed retry
+ * and ship the original). Getting that order wrong is how a run either dies on a
+ * legitimately empty section or ships one written from memory.
+ *
+ * The cost was in the TESTS. Reaching the gates meant a temp dir, a real task
+ * file, and a fake spawn routed on prose lifted out of `prompts.ts` — plus, for
+ * attempt-1-vs-attempt-2, a second sentence lifted out of a module-private
+ * preamble constant. In a codebase whose whole workflow is re-wording prompts and
+ * measuring what changed, that means a reworded preamble silently stops the gate
+ * tests from testing the gate. Behind this interface a test scripts
+ * `runWorker(label, attempt)` and states the `RunWorkerResult` fields a gate
+ * reads.
+ *
+ * THE INVARIANT, stated once: the empty gate runs FIRST and is the only one that
+ * can throw; the other two keep the original when their retry does not improve a
+ * named measure; and `confirmedEmpty` suppresses the silent gate, because that
+ * retry already asked "you wrote nothing" and got the same answer.
+ */
+import type { RunWorkerInput, RunWorkerResult } from '../workers/pi-worker-core.js';
+import type { SpawnFn } from '../shared/child-process.js';
+import type { DebugLine } from './debug-log.js';
+/**
+ * One research worker's row. `section` is the heading its output is assembled
+ * and cached under; `label` is its child NAME — what the loader, the debug trail
+ * and the A/B ledgers print, and the key into `REASONING_GROUP_BY_CHILD`.
+ */
+export interface ResearchWorkerSpec {
+    section: string;
+    label: string;
+    /** Static, or built from the sections completed so far (serial mode hands
+     *  APIS the finished FILES map; parallel mode hands it nothing). */
+    prompt: string | ((prior: ReadonlyArray<{
+        name: string;
+        text: string;
+    }>) => string);
+    tools?: string;
+    extensions?: string[];
+    /** Deterministic gate over the worker's own output, run BEFORE the section is
+     *  persisted, so nothing it rejects survives into the cache or into compose. */
+    postProcess?: (text: string) => string;
+    /** When set, a non-empty section produced with ZERO grounding-retrieval calls is
+     *  re-run ONCE with this preamble prepended, forcing a retrieval-first pass. The
+     *  retry replaces the original only if it actually retrieved. */
+    zeroRetrievalRetry?: string;
+    /** When set, a section that comes out SILENT — zero parseable bullets from a
+     *  loop-degrade banner or a hallucinated non-bullet fragment — is re-run ONCE
+     *  with this preamble. A legitimately-empty section is NOT retried. */
+    retryIfSilent?: string;
+    /** This worker can issue project-source docs lookups, so the 5B fan-out bounds
+     *  apply to it (see task/research-fanout-budget.ts). */
+    fanoutBounded?: true;
+}
+/**
+ * The small record the driver needs: one way to run a worker, and where to put
+ * what comes back.
+ *
+ * Everything here is a fact about THIS RUN, not about the worker — which is what
+ * lets the four rows be plain data and the driver be a function of two arguments.
+ */
+export interface ResearchWorkerRun {
+    runWorker: (label: string, input: RunWorkerInput) => Promise<RunWorkerResult>;
+    cwd: string;
+    taskId: string;
+    signal: AbortSignal;
+    spawn?: SpawnFn;
+    /** The `--thinking` fragment for a named child. */
+    thinkingFor: (label: string) => string[];
+    logDebug?: (msg: string, kind?: DebugLine) => void;
+    onChildOutput?: (line: string) => void;
+    /** Record one finished worker's timing splits. */
+    record: (label: string, p: Promise<RunWorkerResult>) => Promise<RunWorkerResult>;
+    /** Called once per worker that reaches an outcome, cached ones included. */
+    onDone: () => void;
+    /**
+     * Read one worker's cached output back, or '' when there is none.
+     *
+     * A SEAM, and the symmetric half of `persistSection`. The cache skip is one
+     * of the four outcomes this driver has, and reaching it used to require a
+     * real task file on disk — which is most of why the gate tests needed a temp
+     * dir at all.
+     */
+    readCached: (heading: string) => Promise<string>;
+    /** Write one validated section to the task file. Serialised by the caller. */
+    persistSection: (heading: string, text: string) => Promise<void>;
+    /**
+     * The 5B lever env vars, READ ONCE for the whole phase.
+     *
+     * Was three resolved values (`carryForward`, `fanoutTimeout`,
+     * `progressCeilingMs`). It is one frozen reader now because the `research`
+     * profile owns what those values mean; what this layer still owns is that
+     * every worker in a run sees the SAME arm, which a live `process.env` read
+     * per worker would lose. See `snapshotLeverEnv`.
+     */
+    leverEnv: (key: string) => string | undefined;
+}
+/**
+ * Task-file heading under which a research worker's validated output is cached.
+ * A resumed research phase reads these to skip workers that already succeeded,
+ * instead of re-running all four from scratch when one of them fails — the
+ * expensive case (e.g. 3 healthy workers thrown away because the 4th looped).
+ */
+export declare function researchWorkerCacheHeading(section: string): string;
+/**
+ * Classify a research worker's result so the phase can react per-worker instead
+ * of treating every failure the same. Two distinct failure shapes:
+ *
+ *   - 'runaway' (loop-kill OR per-worker wall-clock timeout): the worker explored
+ *     too long and was killed *after* burning its MAX_LOOP_RESTARTS restarts. It
+ *     did real work and left partial text; the other three workers are unaffected.
+ *     Failing the whole task here would throw away every already-good worker AND
+ *     abort the entire auto-run over the weakest section — and because the loop is
+ *     deterministic, a resume just re-loops and re-fails. So this DEGRADES: keep
+ *     the partial answer (marked), cache it, move on. A loop-kill is a SIGTERM
+ *     (exit 143) OR a clean exit 0 with truncated text, so loopHit/timedOut — not
+ *     exitCode — are the reliable signal and are checked first.
+ *
+ *   - 'fatal' (non-zero exit that isn't a loop-kill, a provider error behind an
+ *     empty answer, or a leaked never-executed tool call): the output is
+ *     untrustworthy in a way partial text can't paper over (broken env, model
+ *     disconnect, wrong tool-call dialect). These still throw — degrading them
+ *     would launder a real breakage into a plausible-looking section.
+ *
+ *   - 'empty' (clean exit 0, no provider error, no loop/timeout — the model simply
+ *     wrote nothing): NOT a failure. On an extremely simple task ("create a folder
+ *     with an index.html in it") three of the four workers have genuinely nothing
+ *     to report, and each worker prompt tells the model to emit ONLY what this task
+ *     touches and to drop everything else — so silence is the CORRECT answer and
+ *     was killing the whole task at research (issue #10). Measured live on the
+ *     issue's own prompt (30 reps/worker, local Qwen3.6-27B): every APIS answer was
+ *     semantically "there is nothing here", and 2/30 were literally zero bytes on a
+ *     clean exit — the other 28 survived only because the model happened to wrap the
+ *     same non-answer in a parenthetical, which is model style, not signal. The
+ *     caller retries once and then accepts an explicit empty section; what stays
+ *     fatal is silence WITH a reported cause, which is the masked-disconnect case
+ *     this branch was written for and which `modelError` now names outright.
+ *
+ * Returns null when the result is trustworthy.
+ */
+export declare function classifyResearchWorker(name: string, result: RunWorkerResult): {
+    kind: 'runaway';
+    reason: string;
+} | {
+    kind: 'fatal';
+    error: Error;
+} | {
+    kind: 'empty';
+} | null;
+/**
+ * Build a degraded section body for a runaway worker: a one-line marker naming
+ * the failure (so downstream phases and a human reading the task file know this
+ * section is incomplete) followed by whatever partial answer the worker streamed
+ * before it was killed. The marker is always present even when there is no
+ * partial text, so an empty degrade is never mistaken for a real finding.
+ */
+export declare function degradedSectionBody(name: string, reason: string, partial: string): string;
+/**
+ * The body written for a research section the worker confirmed has no entries.
+ *
+ * Three states have to stay distinguishable to anyone — human or later phase —
+ * reading a research section, so each carries its own marker:
+ *   `(none — …)`     the worker RAN and answered "nothing applies" (this)
+ *   `(degraded: …)`  the worker was killed mid-answer, text may be partial
+ *                    (degradedSectionBody)
+ *   section absent   the worker never got that far — the phase threw
+ *
+ * Naming the worker inside the marker keeps it true after assembly, where the
+ * section headings are all that separate the four workers' output.
+ */
+export declare function emptySectionBody(name: string): string;
+export declare function isBareNoneAnswer(text: string): boolean;
+export declare function runResearchWorker(spec: ResearchWorkerSpec, run: ResearchWorkerRun, prior?: ReadonlyArray<{
+    name: string;
+    text: string;
+}>): Promise<{
+    name: string;
+    text: string;
+}>;