@mjasnikovs/pi-task 0.38.22 → 0.38.24

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-worker.d.ts

@@ -0,0 +1,180 @@
+/**
+ * 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>;
+    /** 5B RESCUE / SCALE knobs, resolved once for the phase. */
+    carryForward: boolean;
+    fanoutTimeout: {
+        perLookupMs: number;
+        ceilingMs: number;
+    } | null;
+    progressCeilingMs: number | null;
+}
+/**
+ * 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;
+}>;