@mjasnikovs/pi-task 0.38.11 → 0.38.12

package/dist/task/orchestrator.d.ts

@@ -19,7 +19,58 @@ import type { ExtensionAPI, ExtensionCommandContext } from '@earendil-works/pi-c
 import { type WidgetState } from './widget.js';
 import { type RunTaskFn } from './gate-deps.js';
 import { type GateDeps } from './task-gates.js';
+import { type PhaseDeps } from './child-runner.js';
 import type { SpawnFn } from '../shared/child-process.js';
+import { type SuperviseOptions } from './implementation-turn.js';
+/**
+ * Everything one TaskRunner needs, as one object. The runner is the shared core
+ * under `runSingleTask` (and so under /task-auto's per-task loop), so this is the
+ * shape both of those construct; `RunSingleTaskOptions` extends the injectable
+ * subset and adds what only the wrapper reads.
+ */
+export interface TaskRunnerOptions {
+    ctx: ExtensionCommandContext;
+    cwd: string;
+    rawPrompt: string;
+    /** Resume an existing task by ID instead of starting a new one. */
+    resumeId?: string;
+    /** Deliver the finished spec to the main session. Absent → nothing is sent. */
+    sendSpec?: (spec: string) => Promise<void>;
+    /** Test seam: spawn function forwarded into `PhaseDeps.spawn`. Keep for tests
+     *  that drive the Error-triage ladder or a real process. */
+    spawnFn?: SpawnFn;
+    /**
+     * Test seam: `PhaseDeps.runChild(name, tools, prompt)`. Present → every phase
+     * child is answered by name, with none of the ladder's guards. Use this when
+     * the child is a premise of the test, not its subject.
+     */
+    runChild?: PhaseDeps['runChild'];
+    /** Called with the resolved task id once its file exists, before any phase
+     *  work. Lets callers record the id (e.g. stamp the /task-auto entry) so an
+     *  interrupted run can be resumed instead of restarted. */
+    onStart?: (taskId: string) => void | Promise<void>;
+    /**
+     * Scope fence naming the sibling steps of a /task-auto plan. Forwarded into
+     * the refine phase so a single decomposed step bounds its slice instead of
+     * re-expanding the whole referenced spec doc. Set only by /task-auto's loop;
+     * a bare /task leaves it undefined and the refine prompt is unchanged.
+     */
+    planContext?: string;
+    /**
+     * Marks this run as a verify-FAIL re-attempt. When set (only by /task-auto's
+     * autofix path, with `resumeId` pointing at the already-composed task), the
+     * text — the verify gate's failure reason plus any guidance the user typed —
+     * is prepended to the delivered spec as a RE-ATTEMPT banner, so the
+     * implementer fixes the specific failure and re-satisfies the VERIFY block
+     * rather than blindly redoing the task. Empty/undefined on a first attempt.
+     */
+    fixInstruction?: string;
+    /** True when the caller awaits the implementation turn (waitForImplementation):
+     *  the impl widget stays armed across the whole impl phase (incl. compaction /
+     *  steer turns) and is disarmed here. False for fire-and-forget /task, where the
+     *  widget is armed one-shot and its own agent_end disarms it. */
+    implAwaited?: boolean;
+}
 /** Encapsulates the full lifecycle of a single pi-task run. */
 export declare class TaskRunner {
     private readonly _ctx;
@@ -30,10 +81,7 @@ export declare class TaskRunner {
     private readonly _onStart;
     private readonly _planContext;
     private readonly _fixInstruction;
-    /** True when the caller awaits the implementation turn (waitForImplementation):
-     *  the impl widget stays armed across the whole impl phase (incl. compaction /
-     *  steer turns) and is disarmed here. False for fire-and-forget /task, where the
-     *  widget is armed one-shot and its own agent_end disarms it. */
+    /** See {@link TaskRunnerOptions.implAwaited}. */
     private readonly _implAwaited;
     private readonly _abort;
     private readonly _startedAt;
@@ -50,15 +98,20 @@ export declare class TaskRunner {
      */
     private readonly _timings;
     private _currentPhaseChildren;
-    constructor(ctx: ExtensionCommandContext, cwd: string, rawPrompt: string, resumeId?: string, sendSpec?: (spec: string) => Promise<void>, spawnFn?: SpawnFn, onStart?: (taskId: string) => void | Promise<void>, planContext?: string, fixInstruction?: string, implAwaited?: boolean);
+    constructor(opts: TaskRunnerOptions);
     get taskId(): string;
     get signal(): AbortSignal;
     /** Return the current widget state, or null if not started. */
     status(): WidgetState | null;
     /** Cancel the running task by aborting the signal. */
     cancel(): void;
-    /** Execute the full task lifecycle. */
+    /** Execute the full task lifecycle. Mid-run input holds instead of starting
+     *  a competing turn for the whole of it, and the terminal interception is
+     *  armed for the same window (`withRun`); nested inside `runGatedTask` or
+     *  the `/task-auto` loop the bracket refcounts, so this changes nothing there
+     *  and covers the fire-and-forget `runSingleTask` path on its own. */
     run(): Promise<void>;
+    private _run;
     /** Stop the phase widget — clearing both the terminal and remote surfaces —
      *  exactly once. Nulling the disposer makes repeat calls no-ops, so the
      *  failure flash that handleFailure sets after the catch isn't wiped by the
@@ -76,18 +129,10 @@ export declare class TaskRunner {
      */
     private _specForDelivery;
 }
-export interface RunSingleTaskOptions {
+export interface RunSingleTaskOptions extends Pick<TaskRunnerOptions, 'resumeId' | 'spawnFn' | 'runChild' | 'onStart' | 'planContext' | 'fixInstruction'> {
     /** Await the session going idle after the spec is delivered, so the caller
      *  blocks until the agent has implemented it. Default false. */
     waitForImplementation?: boolean;
-    /** Resume an existing task by ID instead of starting a new one. */
-    resumeId?: string;
-    /** Test seam: spawn function forwarded to TaskRunner. */
-    spawnFn?: SpawnFn;
-    /** Called with the resolved task id once its file exists, before any phase
-     *  work. Lets callers record the id (e.g. stamp the /task-auto entry) so an
-     *  interrupted run can be resumed instead of restarted. */
-    onStart?: (taskId: string) => void | Promise<void>;
     /**
      * Ask the user for a steering message after they interrupt (ESC) the
      * implementation turn. Return text to continue the same task as another turn,
@@ -96,7 +141,7 @@ export interface RunSingleTaskOptions {
      * raced against a remote browser card); injectable so the steer loop is
      * testable without a real dialog.
      */
-    promptSteer?: (ctx: ExtensionCommandContext) => Promise<string | undefined>;
+    promptSteer?: SuperviseOptions['promptSteer'];
     /**
      * Push a "Task finished" notification to subscribed devices when this run
      * reaches a terminal state (completed / failed / cancelled). Set only by the
@@ -104,33 +149,7 @@ export interface RunSingleTaskOptions {
      * internal per-task runs, which must stay silent. Default false.
      */
     notifyFinish?: boolean;
-    /**
-     * Scope fence naming the sibling steps of a /task-auto plan. Forwarded into
-     * the refine phase so a single decomposed step bounds its slice instead of
-     * re-expanding the whole referenced spec doc. Set only by /task-auto's loop;
-     * a bare /task leaves it undefined and the refine prompt is unchanged.
-     */
-    planContext?: string;
-    /**
-     * Marks this run as a verify-FAIL re-attempt. When set (only by /task-auto's
-     * autofix path, with `resumeId` pointing at the already-composed task), the
-     * text — the verify gate's failure reason plus any guidance the user typed —
-     * is prepended to the delivered spec as a RE-ATTEMPT banner, so the
-     * implementer fixes the specific failure and re-satisfies the VERIFY block
-     * rather than blindly redoing the task. Empty/undefined on a first attempt.
-     */
-    fixInstruction?: string;
 }
-/**
- * The slice of the replacement-session context the steer loop needs.
- * `sendUserMessage` lives on ReplacedSessionContext (not the base command ctx,
- * and not re-exported from the package), so we narrow to just what we call.
- */
-export type SteerCtx = ExtensionCommandContext & {
-    sendUserMessage(content: string, options?: {
-        deliverAs?: 'steer' | 'followUp';
-    }): Promise<void>;
-};
 export interface RunSingleTaskResult {
     taskId: string;
     ok: boolean;
@@ -163,90 +182,6 @@ export interface RunSingleTaskResult {
      */
     reason?: string;
 }
-/**
- * True when the implementation turn went idle right after a context compaction —
- * the most recent entry in the branch is a `compaction` boundary sitting after the
- * last assistant message.
- *
- * A *threshold* auto-compaction (the runtime's "context is getting large" path)
- * compacts and then deliberately does NOT auto-continue: it returns to idle and
- * expects a manual continue (`_runAutoCompaction("threshold", false)` →
- * `hasQueuedMessages()` is false → the agent loop stops). Our implementation wait
- * resolves at exactly that idle. Without this check it reads as "the model
- * finished" (the last assistant message is a normal `stop`, not `aborted`/`error`),
- * so the run jumps straight to the verify gate and abandons a half-done task at the
- * compaction boundary — the failure this detector closes.
- *
- * Position-based, not timestamp-based: the runtime APPENDS the compaction entry to
- * the tail of the branch after the assistant message that triggered it
- * (`appendCompaction` → `_appendEntry` push), so a `compaction` after the last
- * assistant message means we are parked on a compaction with no continuation. A
- * genuinely finished turn ends on an assistant message with no trailing compaction;
- * an *overflow* compaction self-retries, so it never leaves us idle here.
- */
-export declare function endedAtCompactionBoundary(ctx: ExtensionCommandContext): boolean;
-/**
- * Nudge that resumes an implementation turn the runtime parked at a compaction
- * boundary. It must let a turn that was genuinely finished (then tipped over the
- * threshold by its own final message) confirm completion without inventing busywork
- * — we cannot tell "paused mid-task by compaction" from "finished, then compacted"
- * from the boundary alone, so the wording lets a done turn end in one line.
- */
-export declare const CONTINUE_AFTER_COMPACTION: string;
-/**
- * Safety cap on compaction-driven resumes for a single implementation turn. Each
- * resume follows a real compaction (which only fires after the model produced a
- * turn large enough to cross the threshold), so a legitimately large task may
- * resume a handful of times; the cap exists only to stop a pathological loop from
- * auto-sending forever with no user in the loop. Hitting it stops resuming and lets
- * the verify gate / `/task-auto-resume` catch any leftover incompleteness.
- */
-export declare const MAX_COMPACTION_RESUMES = 20;
-/**
- * Resume an implementation turn that went idle at a threshold-compaction boundary.
- * The runtime compacts and parks at idle without auto-continuing; we send a
- * continue and wait again, repeating across successive compactions until the turn
- * ends on a real assistant message (genuine completion). A user ESC takes priority
- * (it is not a compaction boundary, and `wasInterrupted` guards the loop so the
- * steer loop handles it), and the safety cap bounds a runaway. Returns the number
- * of resumes performed (0 when the turn did not end on a compaction).
- */
-export declare function resumeAcrossCompactions(ctx: SteerCtx): Promise<number>;
-/**
- * Timing knobs for the watchdog-abort guard in {@link steerUntilDone}, injectable
- * so tests exercise the grace expiry without a 10-second wait. `graceMs` bounds
- * how long the loop waits for the watchdog's follow-up to be DELIVERED (not to
- * finish — its turn may legitimately run for minutes afterwards); delivery is
- * normally near-instant, so the grace only expires on a stale flag.
- */
-export interface SteerWatchdogDeps {
-    consume: () => boolean;
-    graceMs: number;
-    pollMs: number;
-}
-/**
- * After the implementation turn settles, honour a user ESC by letting them steer.
- *
- * `waitForIdle` resolves both on natural completion AND on an ESC (which aborts
- * the turn → idle). When the last turn was aborted, the host's main input loop is
- * blocked inside our command handler, so a message typed in the editor would only
- * queue, never run (interactive-mode routes idle input through onInputCallback,
- * which is unset while we hold the loop). We therefore solicit the steering text
- * ourselves and feed it back as another turn via sendUserMessage — which runs to
- * completion when the session is idle. Repeat until a turn finishes uninterrupted.
- *
- * A WATCHDOG abort also ends the turn with stopReason 'aborted' — indistinguishable
- * from a human ESC by the session entries alone at that instant. The watchdog
- * queues its own recovery follow-up, so prompting there would show a steering
- * dialog to an empty room and wedge an unattended run on the race. The one-shot
- * flag (set synchronously before the abort) routes that case to
- * {@link awaitWatchdogFollowUp} instead; a stale flag degrades to a bounded wait
- * followed by the ordinary prompt, never to a suppressed one.
- *
- * Returns true when the user declined to steer (empty/cancelled) and the run
- * should pause; false when the implementation completed (steered or not).
- */
-export declare function steerUntilDone(ctx: SteerCtx, promptSteer?: (ctx: ExtensionCommandContext) => Promise<string | undefined>, watchdog?: Partial<SteerWatchdogDeps>): Promise<boolean>;
 /**
  * Run one prompt through the full single-task pipeline in a fresh session and
  * deliver its spec. With waitForImplementation, block until the agent finishes